knodin 0.13.0 → 0.14.0

package/docs/BACKUP-RETENTION.md

@@ -5,7 +5,8 @@ Knodin graph promotions leave completed snapshots named
 They are promotion snapshots, not a supported restore interface. Malformed and
 legacy names are inventory-only and are never pruning candidates.
 
-Nothing is deleted by default. Inspect one checkout or bounded portfolio roots:
+One-shot pruning is preview-only unless `--apply` is supplied. Inspect one
+checkout or bounded portfolio roots:
 
 ```bash
 knodin backups list
@@ -25,6 +26,48 @@ trees. It unions explicit roots with valid absolute checkout paths in
 
 ## Opt-in ongoing retention
 
+### Managed storage and legacy consent
+
+New successfully indexed stores automatically receive `.knodin/storage-policy.json`
+unless a healthy, applicable bounded global policy already manages that store.
+In that case no local policy file is materialized; `backups policy status` reports
+the effective policy. The local defaults provide:
+one protected recoverable backup, a 1 GiB allocated-backup budget, and a 512 MiB
+free-space reserve. Post-promotion maintenance runs after releasing the operation
+lease. Count/byte quotas override the age window, but never recovery protection.
+If protected data exceeds the quota, Knodin reports it and refuses unsafe further
+candidate allocation; increase the budget or resolve the storage condition.
+
+Existing unmanaged graphs require explicit consent:
+
+```bash
+knodin backups policy status /path/to/repo --json
+knodin backups policy preview /path/to/repo --json
+knodin backups policy apply /path/to/repo --json
+knodin backups policy apply /path/to/repo --max-count 2 --max-bytes 2147483648
+knodin backups policy apply /path/to/repo --mode preview
+knodin backups policy apply /path/to/repo --mode disabled
+```
+
+Preview writes nothing and includes the pruning plan and bounded inventory.
+Apply persists consent and runs policy-approved backup maintenance. Omitted
+settings preserve an existing policy, including explicit dry-run. Use
+`--mode enabled` to explicitly return to deleting eligible managed backups.
+`--reserve-bytes` configures free space retained beyond a conservative scratch
+estimate. Unknown capacity/allocated sizes refuse allocations instead of
+guessing zero. The estimate is not a reservation against other writers.
+
+Candidate maintenance removes only managed empty or audit-only directories with
+a validated owner marker and confirmed exited owner. Owner-unknown legacy
+directories, live owners, DB-bearing interrupted candidates, symlinks, leases
+and promotion markers are protected. Permission/deletion failures and protected over-budget data are
+visible, not claimed as reclaimed space. Allocated versus apparent totals differ;
+APFS clones can share extents, so allocated-byte sums are not promised physical
+recovery. Source mirrors and external development harness directories are
+separate storage classes, not promotion backups.
+
+### Native daily scheduler
+
 Installation is the consent boundary:
 
 ```bash
@@ -34,7 +77,8 @@ knodin backups retention doctor
 knodin backups retention remove
 ```
 
-Options are `--retention-days` (3), `--keep-newest` (1), `--depth` (5),
+Options are `--retention-days` (3), `--keep-newest` (1), `--max-count` (1),
+`--max-bytes` (1073741824), `--depth` (5),
 `--schedule` (`04:17` local), and `--dry-run`. Installation writes a versioned
 policy to `$XDG_CONFIG_HOME/knodin/backup-retention.json` and owned receipt/run
 state beneath `$XDG_STATE_HOME/knodin/backup-retention/`. Ordinary Knodin use

package/docs/CLI.md

@@ -37,8 +37,12 @@ knodin update --help
 
 Backup discovery and pruning are native and cross-platform. `knodin backups
 list` and the default `knodin backups prune` are read-only; deletion requires
-`--apply`, while recurring cleanup requires the separate `knodin backups
-retention install` consent step. See `docs/BACKUP-RETENTION.md` for safety,
+`--apply`. New successfully indexed stores get bounded post-promotion retention
+(one rollback, 1 GiB allocated-backup budget, 512 MiB free-space reserve).
+Existing stores require `knodin backups policy preview` followed by explicit
+`policy apply`; status/preview expose bounded inventory and exact cleanup plans.
+Native daily scheduling remains opt-in through `knodin backups retention install`.
+See `docs/BACKUP-RETENTION.md` for safety,
 scheduler, logging, and removal details.
 
 `repos search` resolves configured system memberships independently for every
@@ -227,8 +231,8 @@ configuration `consumers_of`. `count` is total observed matching sites,
 `files` contains aggregates only for files represented on this page.
 `targetKind` identifies the resolved declaration as `class` or `interface` and is
 preserved on every page. Interface consumers cover supported type-position roles,
-not constructors, static-field reads, `implements` relationships, or inferred
-runtime dispatch. Query implementation relationships separately.
+not constructors, static-field reads, static-method receivers, `implements`
+relationships, or inferred runtime dispatch. Query implementation relationships separately.
 
 Use `--test-scope test|production|all` (default `all`), a canonical repository-relative
 `--path` prefix, and stable `--identity`/`--file` target selectors when needed.
@@ -240,10 +244,13 @@ A minimum complete site plus qualifications must fit; source fields are never sh
 
 Sites retain exact spelling, role, source-owner identity when known, and exclusive
 end positions: one-based lines/UTF-16 columns and zero-based UTF-8 byte offsets.
-The target's own file is excluded. Nine supported syntax roles do not cover every
+The target's own file is excluded. Supported syntax roles include `instanceof`
+types and explicit static-method receivers, but do not cover every
 Apex use, metadata relationship, or runtime path. Read `classConsumerAnalysis` and
 `indexCoverage` before interpreting a negative; missing/invalid descriptors and
 unresolved uses remain qualified, not proof that a class is unused.
+Legacy descriptors without receiver or `instanceof` capability require
+`knodin repair` to re-extract affected files within the declared index scope.
 An indexed retained interface declaration without a safely matching interface
 symbol returns `CLASS_CONSUMER_TARGET_CAPABILITY_MISSING`, `targetResolution: capability-missing`,
 and a nonzero exit—not a successful zero or a fabricated identity. Follow the

package/docs/DEAD-CODE-AND-IMPACT.md

@@ -6,6 +6,47 @@ reference. It does not prove that reflection, runtime dependency injection,
 framework configuration, metadata, deployed infrastructure, or external
 consumers cannot invoke the code.
 
+For Apex, `dead_code` can also report connected methods with
+`candidateReason: "unrooted-chain"`: no modeled root reaches that chain in
+the indexed inventory, even though its methods reference one another.
+`deadCodeAnalysis.rootReachability` records the model, counts, limitations,
+stable chain identities, method membership, structural owners and call edges.
+Owner membership is not a finding that the entire class is unused.
+
+Completeness has two separate scopes. `deadCodeAnalysis.partial`, labeled
+`partialScope: "apex-platform-declarations"`, reports unsupported or missing
+Apex declaration capabilities. It does not certify complete call resolution.
+`deadCodeAnalysis.rootReachability.partial` independently reports uncertainty
+in the indexed root/call analysis. Complete declaration coverage can therefore
+coexist with partial root reachability; inspect both before interpreting results.
+
+`deadCodeAnalysis.platformEntries` separately describes matching indexed
+org-invokable declarations. It does not add them to candidate `results` or
+change the candidate `count`. Returned entries include identity, location and
+source-verified `platformEntry` evidence, or an explicit unavailable reason.
+The classification total is not a verified-proof count or evidence of runtime use.
+
+This collection is a bounded preview: at most 25 entries, further limited by
+the query limit, with at most eight source-file verification attempts and a
+1 MiB bound per file. Each selected file is verified once per request. Counts
+separate verified, unavailable and omitted entries; `truncated`/`partial` and
+omission reasons disclose incomplete delivery. There is no collection cursor:
+narrow the path or use identity-qualified `explain` for a specific declaration.
+Response budgets preserve the returned collection or fail explicitly.
+
+An org-invokable declaration may also have static callers, including Flow
+metadata. These tags do not assert no static callers and do not replace
+`callers_of` evidence. `runtimeInvocation: "not-established"` remains explicit.
+
+The analysis considers platform declarations, triggers, test declarations and
+supported metadata boundaries before filtering the requested output paths.
+Possible local calls conservatively protect reachable targets; unresolved
+reflection, missing provenance and bounded-inventory omissions remain qualified.
+An omitted candidate is not proof of runtime use. Root reachability is scoped
+to indexed source, with `runtimeInvocation: "not-established"` and
+`safeToDelete: false`. Response budgets preserve the root-analysis contract or
+fail explicitly when it cannot fit; narrow the request or increase its budget.
+
 Impact follows source-evidenced resolved relationships. High-confidence
 incoming cross-repository relationships can make a dependency visible to
 impact and dead-code analysis. Heuristic or unresolved relationships lower

package/docs/MCP.md

@@ -4,6 +4,14 @@ knodin exposes exactly one MCP tool named `knodin`. Capabilities such as
 context, explain, review, search, docs, doctor, repositories, and systems are
 operations of that gateway, not separate top-level tools.
 
+Indexing and repair use the same storage-capacity and managed-retention guards
+as the CLI. Low or unknown capacity refuses scratch allocation without replacing
+the active graph. Maintenance warnings go to stderr, not the stdio JSON protocol.
+Repository storage-policy consent and inventory are CLI administrative commands:
+`knodin backups policy status|preview|apply /path/to/repo --json`.
+Existing unmanaged stores do not gain destructive cleanup through an MCP read.
+See `docs/BACKUP-RETENTION.md` for limits, migration and recovery protection.
+
 Shared-index support also stays inside that one gateway. Status, context,
 query, explain, review, map, and search responses include a bounded
 `sharedIndex` provenance object. `source: "shared-snapshot"` identifies origin;
@@ -229,8 +237,9 @@ and `limit` (1–1000 sites). This is separate from method calls and Java config
 and `returnedCount` counts delivered sites; page-local `files` aggregates do not
 enumerate every matching file until paging is complete.
 The protected `targetKind` is `class` or `interface`. Interface targets admit
-supported type-position roles, not constructor/static-field uses. `implements`
-relationships and concrete runtime dispatch are not typed consumer sites.
+supported type-position roles, including `instanceof`, not constructor/static-field
+or static-method-receiver uses. `implements` relationships and concrete runtime
+dispatch are not typed consumer sites.
 
 Use the returned `continuation` with the same target and filters. Byte/token/item
 budgets may vary. The signed token is interchangeable with CLI `--continuation`
@@ -239,10 +248,13 @@ qualifications fit before the cursor is signed; no generic truncation follows.
 An extra limit-one backend read currently revalidates the snapshot before delivery;
 this correctness guard is not a claim of optimized paging cost.
 
-The nine supported Apex roles exclude target-self-file sites and do not establish
+Supported Apex roles include explicit static-method receivers and `instanceof`
+types, exclude target-self-file sites and do not establish
 complete class-use or runtime reachability. `classConsumerAnalysis` reports partial
 extraction and indexed-inventory counters, separately from `indexCoverage`. Unknown
 targets and ambiguity are unavailable, never successful zero-site answers.
+Legacy descriptors without receiver or `instanceof` capability remain partial;
+follow the scope-preserving `knodin repair` guidance to re-extract them.
 `CLASS_CONSUMER_TARGET_CAPABILITY_MISSING` with `targetResolution: "capability-missing"`
 means retained indexed interface evidence exists but its symbol capability is
 missing. It is unavailable without a fabricated target identity or zero count;

package/docs/SALESFORCE-BINDINGS.md

@@ -106,16 +106,34 @@ and [dynamic picklist configuration guide](https://developer.salesforce.com/docs
 
 ## Apex class-use sites are a separate query
 
-`query class_consumers` exposes static-field reads, constructors, variable types,
-casts, class literals, parameter types, generic parameter types, loop-variable
-types, and generic type arguments. It does not widen metadata bindings or method
+For a selected Apex platform entry declaration, `explain` also exposes
+`platformEntry`: the declared contract, reason, source hash and exact declaration
+and owner spans. `runtimeInvocation: "not-established"` is intentional: a
+Batchable, Queueable or other platform-facing declaration does not prove that
+an org invokes it. Missing or mismatched declaration evidence is explicitly
+unavailable, not a positive entry classification. Ordinary helper declarations
+do not gain a platform-entry label merely from global visibility.
+
+This evidence is separate from class-use sites and dead-code candidate filtering.
+CLI/MCP source and compact modes retain the qualification; a budget too small
+for the complete platform-entry field fails explicitly rather than dropping it.
+
+`query class_consumers` exposes static-field reads, static-method receivers,
+constructors, variable types, casts, `instanceof` types, class literals,
+parameter types, generic parameter types, loop-variable types, and generic type
+arguments. It does not widen metadata bindings or method
 call edges. Case-insensitive type resolution requires unique declarations and
-validated owner chains; value/type shadows, malformed source and ambiguous
-catalog entries cannot become confident class matches.
+validated owner chains. Relevant lexical shadows, malformed source and ambiguous
+catalog entries cannot become confident class matches. A value-name shadow does
+not hide an explicit `instanceof` RHS type.
 
 Results exclude the target's own source file and include test files by default.
 Missing descriptors, unresolved uses and unsupported forms qualify the observed
-counts. Static method receivers, return types, inheritance and writes are not
-promoted into these nine roles. These source-evidenced sites are not complete
-Apex usage enumeration or runtime reachability proof. See the CLI/MCP paging
+counts. Method receivers require a unique same-owner method name and arity
+before the static modifier is accepted; same-arity overloads remain ambiguous.
+Return types, inheritance and writes are not promoted into these roles.
+Legacy descriptors without receiver or `instanceof` capability remain partial;
+run `knodin repair` to re-extract affected files within the declared index scope.
+These source-evidenced sites are not complete Apex usage enumeration or runtime
+reachability proof. See the CLI/MCP paging
 sections for signed continuations and exact site-position conventions.

package/docs/releases/0.13.1.md

@@ -0,0 +1,216 @@
+# knodin 0.13.1
+
+Compatible patch release for KNODIN-47 and KNODIN-48: correct false stale
+evidence after repair and bound managed graph storage.
+
+## Fixed
+
+- Align freshness probes with source-indexing eligibility. Non-source files and
+  collapsed untracked directories no longer make an unchanged, repaired graph
+  appear stale.
+- Preserve exact Git paths, including renames and names containing whitespace,
+  and exclude canonical pruned trees before expanding untracked files.
+- Track relevant `.gitignore` rules, including tracked policy files omitted by
+  Git's stat cache, Git's local exclude file, and its
+  effective global exclude file with bounded reads. Retain previously indexed
+  paths for deletion detection and respect scoped-index path safety.
+- Encode dirty path sets without newline collisions. Failed Git or ignore-policy
+  checks remain unknown, including Git checkouts without their first commit.
+- Reindex relevant dirty or committed-diff source before accepting a repaired
+  baseline, so restored file sizes and timestamps cannot hide source changes.
+  Repair's initial audit also checks change times against the completed source snapshot,
+  covering source edits omitted by Git's stat-cache shortcuts.
+  Verify source and Git stability before publishing the baseline; unresolved
+  historical evidence requires explicit recovery rather than a false success.
+- Preserve first-time repair of an empty graph while refusing to guess missing
+  history or refresh timestamps for an existing graph.
+- Preserve completed-file resume behavior in direct-engine repairs with content
+  proofs that are invalidated by later index writes. Public repair retains its
+  atomic candidate cancellation behavior.
+- Separate repair's content-proof epoch from ordinary reconciliation timestamps.
+  Existing non-empty Git graphs need a one-time `knodin index --clean` before
+  this versioned proof is established. Status, query freshness, and repair
+  refuse to certify missing, malformed, or future-dated provenance rather than
+  trusting a legacy timestamp.
+- Force-reindex paths that Git reports changed, even when size and timestamp
+  match the indexed tuple, so ordinary reconciliation cannot retain old symbols.
+- Establish Knodin's existing repository-local state exclusion before candidate
+  indexing and repair record their policy baseline.
+- Accept the platform null device as an empty global Git exclude policy, and
+  retain the documented bounded stat fallback for verified nested Git paths.
+- Bound new manifest eligibility reads together with ignore-policy reads. When
+  the freshness budget is exceeded, report unknown; explicitly index a large
+  new manifest before relying on automatic freshness for it.
+- Revalidate already-dirty source content with a bounded proof (at most 256
+  paths and 1 MiB per probe). Over-budget content or unreliable Git stat settings
+  remain unknown on the cheap freshness path. A complete deep audit can verify
+  the retained source snapshot; unknown is not evidence that nothing changed.
+- Validate clean-build resume provenance strictly, preserve the original HEAD,
+  recheck equal-stat source edits, and remove deleted paths before promotion.
+  Source/Git changes during clean indexing or final promotion refuse publication
+  of the candidate rather than minting a proof over a mixed snapshot.
+- Preserve verified parsed-source proofs when seeding an unchanged linked
+  worktree. Missing, malformed, or mismatched copied proofs require extraction;
+  omitted equal-stat source edits cannot retain stale sibling symbols.
+- Reuse scoped, canonically pruned Git enumeration for cold reconciliation,
+  including unborn repositories. Failed or over-budget working-tree/commit-diff
+  enumeration cannot advance the stored HEAD or freshness baseline. Missing
+  shallow/foreign commit history requires explicit clean-index recovery rather
+  than a stat-only fallback that misses equal-stat source edits.
+- Withhold a first scoped content-proof epoch after unhealthy verification or
+  an exception, including failures after the deep audit completes. Existing
+  verified epochs are not deleted by failed scope widening.
+- Preserve structural revisions and Apex consumer paging snapshots across
+  unchanged cold opens, including unborn Git repositories. Canonical discovery
+  and relationship/semantic maintenance always run; only unchanged file
+  extraction is skipped using an exact retained parsed-source proof. Missing,
+  malformed, or changed per-file evidence forces extraction. The extraction
+  fence also retains proof before a repository epoch exists, using bounded-memory
+  streaming reads before and after parsing (additional source I/O, not a measured
+  performance gain). Failed extraction cannot publish a new per-file proof;
+  aggregate completion still requires healthy verification.
+  Worker-queued inputs also retain pre/post-parse source fences; per-queued-file
+  metadata scales with the source inventory, while streaming uses a 64 KiB read
+  buffer. Successful batched writes retain their parsed proofs; rolled-back
+  file writes cannot regain a proof at the batch boundary.
+  Stable unparsed/skipped source reads also retain their consumed-source proof
+  after pre/post-read verification; extraction and database-write errors do not.
+  Batch write failures retain successful per-file work but refuse aggregate
+  completion before publishing an epoch or baseline; resolve the write error
+  and retry indexing. A failed candidate is not promoted over the active graph.
+
+## Storage stewardship (KNODIN-48)
+
+New successfully indexed stores receive a repository-local storage policy:
+one recoverable promotion backup, a 1 GiB allocated-backup budget, and a
+512 MiB free-space reserve. Count/byte budgets override the age grace period.
+Cleanup runs after durable promotion and operation-lease release; cleanup
+failures are reported without rolling back the committed graph. The newest
+snapshot and an integrity-checked rollback remain protected, even when that
+requires reporting an over-budget condition instead of deleting recovery data.
+
+Existing unmanaged stores are not silently migrated. Run
+`knodin backups policy preview /path/to/repo --json`, inspect exact candidates,
+then `knodin backups policy apply /path/to/repo --json` to consent. Existing
+explicit dry-run/disabled policies remain respected. Configure limits with
+`--max-count`, `--max-bytes`, and `--reserve-bytes`; `--mode preview` or
+`--mode disabled` records the corresponding maintenance choice.
+
+Automatic cleanup rechecks effective policy under its lease before deletion.
+New-store initialization eligibility is durably recorded in the graph before
+publication and survives later clean replacement if policy publication fails;
+successful initialization clears it, so deliberate policy removal stays unmanaged.
+Clearing this internal marker preserves an already validated graph audit and its
+original timestamp across clean close/reopen; concurrent database changes refuse
+audit carry-forward rather than being labeled as previously verified.
+Policy reads use the shared external-state resolver for registered mirrors;
+policy initialization, apply, and automatic cleanup refuse mirror source writes,
+including source aliases. Unsupported Windows directory syncing does not turn
+an already file-synced policy publication into failure; other I/O errors remain visible.
+
+Candidate creation and repair's VACUUM preflight require conservatively
+estimated scratch space plus the reserve. Unknown capacity or allocated-size
+measurements fail closed before allocating scratch. This is an estimate, not
+a disk reservation; ENOSPC and concurrent writers can still cause refusal.
+Bounded candidate sweeping removes only managed empty/audit-only residue with
+a validated marker and confirmed exited owner. Unknown legacy owners and
+DB-bearing resumable candidates are preserved. Inventory distinguishes apparent from
+allocated bytes; APFS shared extents mean allocated totals are not guaranteed
+physical reclamation. External source mirrors and development acceptance
+directories are not graph backups and are not blanket-deleted by this policy.
+Candidate allocation revalidates the managed root and new directory before any
+owner or database write. JSON-manifest eligibility uses a no-follow descriptor
+with final pathname identity checks. Shared-index restore always releases its
+lifecycle lease and invokes post-promotion storage finalization even when cache
+lease release or candidate cleanup fails.
+
+The release auto-merge dispatch retains exact-SHA, unresolved-conversation,
+local final-gate, approval, and atomic-merge protections when Copilot review is
+unavailable because its AI-credit budget is exhausted. The explicit fallback
+reason is opt-in; ordinary dispatches still require a clean exact-head review.
+The exhausted-credit path also covers a new PR for which Copilot cannot create
+any review object; an exact-head review containing findings still blocks merge.
+The dispatch runs on the organization's approved self-hosted Linux pool so IP
+allow-list enforcement does not prevent it from reading or merging its own PR.
+The tagged release verifier allows 45 minutes for the same full-suite workload,
+preventing a successful test run from being cancelled by the former 30-minute cap.
+
+## Release verification
+
+Release-candidate pushes run full coverage without repeatedly scanning Sonar. After the current
+PR head has completed review, maintainers run `npm run release:verify` locally; it runs full
+coverage and the local Sonar quality gate, refuses a dirty tracked tree or remote-head mismatch,
+and records the exact verified SHA in Git-local metadata. Any later commit invalidates that result.
+The gate also refuses branch changes and ambiguous remote references. Isolated
+subprocess regressions cover preflight refusals, verification failures, SHA drift,
+and the evidence payload without invoking real scans.
+
+Ordinary PR pushes no longer enable auto-merge. Maintainers explicitly dispatch
+the auto-merge workflow with the PR number and exact SHA only after independently
+verifying clean current-head review and successful local final-gate evidence.
+The dispatch checks the live open PR head; it does not authenticate local evidence
+or replace protected-branch checks.
+
+Regression coverage includes repeated cold status checks after repair, genuine
+source edits, ignore-policy changes, scoped paths, symlinks, JSON eligibility,
+and unusual filenames. A freshness-only development build was also verified
+against SalesforceCI's approximately 903,000-file graph: repair completed, then
+two separate-process status checks reported healthy and fresh without changing
+repository source files or existing working-tree edits.
+
+That acceptance establishes the reported repair/status defect, not a complete
+cross-repository init/repair/status certification or a general performance gain.
+Real source changes still require graph refresh. After upgrading an affected
+checkout, run `knodin repair`. If it reports that content provenance is missing,
+run the requested one-time `knodin index --clean`; then run `knodin status`.
+
+## Additional review safety fixes
+
+Already-dirty source proofs reject symlinked paths and recheck held-file identity
+and change time; an unverifiable path reports unknown rather than false freshness.
+Candidate reads and promotion fences retain no-follow descriptor evidence.
+Interrupted candidates with unknown/live owners or nonselected databases are
+preserved rather than recursively discarded. Failed promotion rollback preserves
+uncertain files and a repair-needed marker for manual inspection instead of
+automatically accepting a substituted graph. These are boundary checks, not an
+atomic filesystem reservation against concurrent pathname changes.
+
+Mirror identities use the generated `repo_<20 hexadecimal characters>` format.
+Malformed/unreadable registries fail closed; registry writes reject unsafe targets
+and publish through an exclusive temporary file. Managed staging/source guards
+refuse symlink escapes and reject an unrelated clone path before it can be cached
+as that mirror. Canonical aliases remain supported, and a missing clone remains
+registered only at its deterministic managed path. Mirror indexing keeps graph
+state out of source but does not opt read-only mirrors into managed backup-policy
+initialization or report that intentional omission as failed maintenance.
+Duplicate mirror identities or canonical clone paths are rejected before routing.
+Owner-proven audit-only
+quarantines remain discoverable and retryable after cleanup failure; unknown or
+database-bearing quarantines remain preserved.
+
+The local final gate uses the existing npm coverage command without requiring Bun.
+The privileged merge action is pinned to an immutable upstream commit.
+
+Repair snapshot proofs now use component-wise no-follow source checks and bind
+the opened descriptor to the final pathname across the complete read. Storage
+policy reads similarly reject atomic pathname replacement, and applied policy
+changes share the cleanup lifecycle lease so deletion cannot continue under
+superseded consent.
+
+Opportunistic global retention respects configured roots and depth and revalidates
+installed consent under its deletion lease. Direct candidate cleanup refuses
+read-only mirrors. Seeded worktree promotions run the same post-audit storage
+finalizer, with durable retry after policy publication failure. Read-only mirror
+inventory measures exact backups in resolved external state, not source decoys.
+
+Global policy resolution and opportunistic retention share the same bounded scope
+check; scheduled and opportunistic deletion share lease-time consent validation.
+Mirror aliases resolve through one canonical identity seam. Mirror allocation
+previews external backup quotas, while deletion remains refused. Any skipped or
+unverified rollback inventory blocks managed allocation. Failed policy writes
+clean their unpublished temporary files. A healthy applicable bounded global
+policy can manage a new store without materializing a local policy file.
+Shared-index restores and committed worktree seeds now finalize pending storage
+policy and maintenance after promotion, including a failed post-promotion status
+check. Release dispatch uses GitHub's exact-SHA merge precondition rather than
+arming unbound auto-merge; a changed head requires fresh review and verification.

package/docs/releases/0.14.0.md

@@ -0,0 +1,78 @@
+# knodin 0.14.0
+
+Minor release for KNODIN-47, KNODIN-49, and KNODIN-50: Salesforce evidence for
+static-method receivers, `instanceof` checks, platform entry points, and
+unrooted Apex chains; and a corrected upgrade path for graphs indexed before
+0.13.1, whose lifecycle hooks reported success while the graph fell behind.
+
+Pre-1.0 minor: the `class_consumers` binding version advances and the lifecycle
+hook now exits non-zero on a graph the audit refuses to certify. No stored graph
+is rewritten without an explicit `init` or `index --clean`.
+
+## Upgrade note for graphs built before 0.13.1
+
+0.13.1 introduced a versioned content-proof epoch and required a one-time
+`knodin index --clean` for existing non-empty graphs, but nothing performed or
+enforced it. On such a graph the background hook indexed the changed paths,
+saw the audit refuse to certify the result, and still logged the paths and
+exited 0. `status` reported lifecycle healthy with no last error while the
+indexed HEAD sat dozens of commits behind. Observed on a real checkout: 33
+commits behind, two days after the upgrade.
+
+In 0.14.0:
+
+- `knodin init` detects the missing epoch and runs the clean index itself, then
+  verifies health. Run it once per affected checkout; no other step is needed.
+- The lifecycle hook does not migrate on its own. It fails with the audit's
+  first finding and remedy, records the cause in
+  `.knodin/hooks/last-refresh-failure`, and `knodin status` reports lifecycle
+  degraded with that error until `init` or `index --clean` runs. A hook on a
+  healthy graph is unchanged and its JSON result now includes `verification`.
+- `status`, `repair`, `index`, and `init` print the audit's own first repair
+  step. Previously all three hardcoded `Run knodin repair`, which cannot fix
+  this condition; on the observed checkout the user was bounced
+  `status → repair → status` with an unchanged graph before finding
+  `index --clean` at the bottom of an unrelated error dump.
+- `repair` says "Repair made no changes" when it repaired nothing and the
+  before/after audit counts are equal, instead of reading as progress.
+- Each `.knodin/indexer.log` record carries `at` (UTC) and `event` (kind,
+  before/after commits, queued `sequence`), so a refresh can be tied to the Git
+  event that queued it. Lines remain one JSON object each.
+- `IndexResult.verification` carries `repairSteps` for `--json` and MCP
+  consumers.
+
+## Salesforce evidence (KNODIN-47)
+
+- `class_consumers` adds two roles: `static_method_receiver`, bound to the
+  receiving class with method arity, and `instanceof_type`. The binding
+  version advances from `2-interface-types` to `4-instanceof-types`. Graphs
+  materialized under the older binding report these roles as a repair
+  limitation instead of silently under-reporting them.
+- The class-consumer catalog memo is deflate-packed, removing the 8 MiB cache
+  cliff that evicted large orgs, and the materialization digest seeks by bare
+  tuple.
+- `explain` carries source-verified `platformEntry` evidence for Apex REST,
+  Flow, and platform contracts, and `dead_code` carries a bounded
+  `deadCodeAnalysis.platformEntries` collection (capped at 25 previews
+  independently of candidate pagination). Sealed artifacts read source through
+  a bounded, integrity-checked path; compact `explain` refuses a budget that
+  cannot hold the entry rather than dropping it.
+- `dead_code` reports Apex method chains with no reachable root as candidates
+  with `candidateReason: "unrooted-chain"`, `chainIdentity`, and
+  `deadCodeAnalysis.rootReachability`. Response budgets protect these fields.
+- Known gap: C2 REST acceptance is not green on the vendored Apex grammar
+  (lowercase `boolean.` parse-partial). Recorded in
+  `benchmarks/evaluations/knodin-41-outcomes/C2-ENTRY-EXPLANATION-ACCEPTANCE.md`.
+
+## Release verification
+
+Both branches passed the full 16-shard suite locally before merge. New
+regressions in `legacy-epoch-migration.spec.ts` fabricate a 0.13.0-shaped graph
+(non-empty `index_state`, no `contentProofEpochV1`) and exercise the real CLI:
+scoped indexing refuses and explains, `hook-refresh` exits non-zero with the
+remedy, the healthy hook path still advances HEAD, `init` migrates, and
+`status`/`repair` agree on the issue count for the unchanged graph.
+
+After upgrading an affected checkout, run `knodin init`; then `knodin status`
+should report healthy and fresh. `knodin index --clean` remains available as the
+explicit equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"knodin": {
 		"compatibility": "breaking"
 	},
@@ -73,6 +73,8 @@
 		"docs/releases/0.12.1.md",
 		"docs/releases/0.12.2.md",
 		"docs/releases/0.13.0.md",
+		"docs/releases/0.13.1.md",
+		"docs/releases/0.14.0.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",
@@ -121,6 +123,7 @@
 		"test:watch": "vitest --watch",
 		"test:coverage": "tsx scripts/run-vitest-shards.ts --coverage",
 		"scan:sonar": "npm run test:coverage && sh scripts/run-sonar-scan.sh",
+		"release:verify": "tsx scripts/release-final-gate.ts",
 		"mirror:sync": "sh tools/hooks/sync-ghes-mirror.sh",
 		"test:pack-install": "tsx scripts/pack-install-smoke.ts",
 		"test:package-managers": "tsx scripts/package-manager-smoke.ts",