v2.1.22

Cartograph v2.1.22

Cartograph v2.1.22 keeps generation admission and freshness consistent,
provides an explicit bounded heap-reclaim path, makes capacity configuration
failures actionable, and gives find a uniform text/JSON output selector. This
resolves
issue #143,
issue #144,
issue #145, and
issue #146.

Generation capacity and source admission

• Capacity failures now state that maxGenerationBytes has a hard 8 GiB
  maximum. When PostgreSQL spill is already selected and the ceiling is
  reached, the next action points to generated/compiled artifact exclusions
  instead of recommending an impossible increase.
• An out-of-range maxGenerationBytes reports the exact field and inclusive
  1..=8589934592 range through direct CLI and MCP errors.
• Migration 39 records run-scoped exclusion globs on the generation they
  build. Status, source context, changed-since, automatic synchronization,
  sync-if-dirty, and resumable upgrade replay that policy, so a just-published
  subset generation can remain current.
• Public status/debug output exposes only the number of run exclusions. A later
  explicit index without --exclude intentionally clears the run-scoped list;
  automatic reconciliation inherits it.

Bounded heap recovery

• cartograph db compact --heap is a read-only plan that measures dead and
  reusable-free allocation in allowlisted Cartograph main and TOAST heaps with
  pgstattuple_approx. It reports estimated reclaimable bytes, total relation
  bytes, headroom, truncation, and the exclusive-lock requirement.
• Apply requires the separate compact-heap-relations confirmation, verified
  filesystem headroom, and no live Cartograph operation leases. It runs one
  VACUUM FULL at a time outside a transaction, fences existing and newly
  attempted project-operation leases, and records exact before/after
  bytes plus any stable partial-stop reason.
• Managed database initialization installs pgstattuple; external PostgreSQL
  operators install it explicitly. Existing online B-tree compaction remains
  unchanged under compact-online-indexes.
• Fenced failed-generation cleanup now deletes that generation's exact spill
  root and cascaded staging payload immediately, making pages reusable before
  a retry rather than retaining live spill rows until a later prune.

Consistent find output

• Public cartograph find accepts --format text|json on every search axis.
  JSON remains the compatibility default; text renders concise deterministic
  freshness, count, truncation, name/kind/path/line, and abstention evidence.
• --compact remains independent and continues to control the exact-name JSON
  payload sent through the shared MCP tool boundary.

Upgrade

Use the resumable project upgrade:

cartograph upgrade --apply --project-path <PATH> --json

Require completed: true. Migration 39 is append-only and gives existing
generations an empty run-exclusion policy. New/reconciled generations retain
the exact policy that built them. Restart or reopen an attached agent host only
when the report says restartRequired: true.

Cartograph v2.1.22 remains native Rust and PostgreSQL-only. It does not bundle
PostgreSQL, ParadeDB, pgvector, a database, or a container image, and it has no
SQLite runtime, importer, optional feature, or fallback.

Full changelog: v2.1.21...v2.1.22