loopforge 3.9.2 → 4.0.7

package/README.md

@@ -1,18 +1,19 @@
-# LoopForge package
+# LoopForge
 
-The `loopforge` package is the TypeScript runtime behind LoopForge. It keeps
-round state durable, collects machine evidence, verifies submitted claims, and
-compiles the next prompt. The external coding Agent still owns planning, file
-changes, tool use, and execution.
+LoopForge is durable round infrastructure for coding agents. It records which
+rounds were committed, keeps machine observations with those records, and
+prepares each next prompt from committed state. The external agent retains
+control of task interpretation, planning, workspace changes, and recovery
+choices.
 
-For the product model and the contract mental model, read the
-[root README](../README.md) or [中文说明](../README.zh-CN.md). This document is
-the package and integration reference.
+The package runs as an MCP server or as a TypeScript library. It requires
+Node.js 18 or newer and has zero runtime dependencies. The version in
+`package.json` is the package version source.
 
-**Requirements:** Node.js >= 18. Zero runtime dependencies. The package version
-is defined only by the `version` field in `package.json`.
+For the product rationale and responsibility boundary, see the
+[project README](../README.md) or [Chinese overview](../README.zh-CN.md).
 
-## Install and run
+## Install and connect
 
 ```bash
 npm install -g loopforge
@@ -20,7 +21,8 @@ loopforge init --client claude
 claude mcp add loopforge -- npx loopforge mcp
 ```
 
-The CLI provides the following entry points:
+`loopforge init` supports `claude`, `codex`, and `generic` clients. The CLI
+entry points are:
 
 ```text
 loopforge mcp [--workspace DIR]
@@ -30,133 +32,255 @@ loopforge inspect LOOP_ID [--round N] [--prompt] [--json]
 loopforge explain LOOP_ID [--round N] [--json]
 ```
 
-`loopforge mcp` starts the synchronous MCP server. `init` installs the client
-configuration, `doctor` reports local readiness, `inspect` reads persisted loop
-state, and `explain` shows why a committed round received its disposition.
-
-The two directory flags answer different questions and are not
-interchangeable:
-
-- `--target DIR` is where the **client skill** is installed
-  (`DIR/perception/SKILL.md`). Without it, the skill goes to the client's own
-  skills directory.
-- `--workspace DIR` is the **runtime boundary**: `loop_policy.json`,
-  `.loopforge/`, evidence commands, and every workspace check resolve against
-  it. Without it, the current directory is used.
-
-`loopforge mcp --workspace DIR` switches to that directory before the server
-reads its policy or resolves its store root, which is why the policy it uses is
-always the one in the workspace it was started against.
-
-## MCP integration
-
-The MCP server exposes nine tools:
-
-- `loopforge_start` creates a session and returns the first prompt.
-- `loopforge_next` submits the structured evaluation for the held round.
-- `loopforge_status` returns session, loop, audit, or explain views.
-- `loopforge_stop` intentionally stops a session.
-- `loopforge_pause` pauses a session at a round boundary.
-- `loopforge_resume` reconstructs a durable session.
-- `loopforge_replay` reads the committed timeline and round diffs.
-- `loopforge_gate_check` preflights a high-risk action.
-- `loopforge_gate_resolve` records the decision for an opened user gate.
-
-The two gate tools are opt-in through `policy.gate.enabled` and are hidden from
-`tools/list` when disabled. A gate decision is an auditable process record. It
-does not prove that a human was present because the Agent submits the resolve
-call.
-
-Every `loopforge_next` submission must include the four strict evaluation
-fields: `success`, `output_summary`, `constraint_violations`, and
-`should_continue`. `round_contract`, `subgoal_updates`, and
-`execution_report.contract_item_claims` are also strict structural boundaries.
-Malformed payloads return a retryable error for the same `roundId` without
-writing session state, a round, gate records, rejection counters, or metrics.
-Agent reports remain claims. Only independent observations can support a
-verified fact.
-
-Prepared responses carry `submission_guidance` with the real contract item and
-sub-goal ids, real criterion ids/text, usable commands and the fields that apply
-now. The prompt's evaluation block uses a compact trigger checklist rather than
-a field catalog; omitting an optional field whose event did not happen remains
-correct. Each submission returns `submission_receipt`, which separates saved
-reports, derived-state effects and machine verification; a rejected attempt is
-never shown as applied. `execution_report.files_changed` is the boundary net
-change from round preparation, including deletions — a commit alone adds no
-entry when content is unchanged. The receipt's `files_reconciliation` compares
-the report with the derived round delta's `changedFiles`; raw observation
-`files` is display data only. A missing or unobservable boundary is `null`,
-never the dirty list and never an empty diff. A worker's
-`discoveredConstraints` stays a report; only top-level `discovered_constraints`
-promotes it into the active set. Unknown or retired optional fields are
-diagnosed and dropped, never silently accepted; field metrics separate
-attempted from retained values. A success claim with an empty report is a
-reporting gap (warn), not an acceptance gate.
+`mcp` starts the synchronous JSON-RPC server over stdio. `doctor` checks local
+readiness and configured evidence capabilities without running evidence
+commands. `inspect` reads stored state, and `explain` shows why a committed
+round received its disposition.
+
+`--target` selects where the Forge skill directory is installed. `--workspace`
+selects the runtime boundary for policy, storage, evidence commands, and
+workspace checks. If omitted, the current directory is used. A normal `init`
+leaves an existing Forge skill untouched; if the installed files differ from
+the packaged skill (for example after an upgrade), `init` reports `Stale:` and
+`loopforge doctor` warns, but neither overwrites your tree. `--force` replaces
+the package-owned skill tree (including its `references/` files).
+
+## MCP workflow
+
+The core loop is `loopforge_start` followed by `loopforge_next` for each held
+round. Every response that holds a round returns a `submissionHandle` and the
+durable `loopId`; keep both. Pass the handle unchanged to `loopforge_next`,
+`loopforge_checkpoint`, and `loopforge_gate_check`. Never edit or reconstruct
+it. A rejection keeps the logical round but returns a new handle; an invalid
+evaluation keeps the same handle. A stale handle never submits work: if only the
+handle was lost while the current prompt is still in context, re-anchor it with
+`loopforge_status` using the live `sessionId` or durable `loopId`; if the prompt
+was also lost, or status reports no live session or no current handle, use
+`loopforge_resume` with the `loopId`. After a process restart,
+`loopforge_resume` requires the `loopId` (not `sessionId`).
+A submission is either an evaluation or an Agent-requested recovery, never
+both. Invalid core fields can be corrected for the same round without
+committing that attempt.
+
+Every returned prompt declares its derived context strategy in the header.
+`fresh_invocation` is clean context: the host starts a new model conversation,
+so the previous model transcript, tool outputs and uncommitted reasoning are
+not carried. It is not a host-runtime restart requirement and not a workspace
+reset: the same `loopId`, logical session and current modified workspace
+continue, and a host process that stays alive may keep the MCP connection and
+tool processes warm and the installed skill files available. LoopForge does not
+manage provider prompt/KV caches or implicit Agent habits; continuity that must
+survive belongs in the prompt's committed projection, and host-side state
+outside it is explicit host configuration, not a LoopForge fact.
+`fresh_invocation` is used for the first round, the next round, recovery redo,
+rejection escalation and invocation recovery, and may describe the SAME logical
+round. `same_round_retry` (in-context repair) continues the original invocation
+with the failure lessons injected. If that invocation is gone, call
+`loopforge_resume` with `invocationLost: true`: LoopForge recompiles the SAME
+round and attempt as `fresh_invocation` / `invocation_recovery` at L2, with
+Machine Evidence, bounded Working Memory and the rejection lessons. Prompt
+density and context boundary are independent; use the returned `contextMode`
+and `contextReason` at any L0/L1/L2 density. Only recovery restores a
+checkpoint.
+
+### Host invocation contract
+
+A clean context is a model-conversation boundary, not a host restart. The host
+may keep its MCP connection, tool processes, installed skill files and modified
+workspace warm across invocations; it must start a clean model conversation and
+must not carry the previous transcript, tool logs or uncommitted reasoning into
+it. A warm runtime is not model memory: the new conversation knows only what
+the prompt and the host's stable environment provide. LoopForge does not manage
+provider prompt/KV caches or infer Agent habits; only committed facts and the
+bounded projections LoopForge returns are guaranteed. Anything else that must
+survive belongs to explicit host configuration.
+
+### Stable environment vs per-round payload
+
+An adapter can treat the MCP `initialize` result's `instructions`, the
+`tools/list` schemas and the installed skill files as the stable environment,
+and each `loopforge_start` / `loopforge_next` / `loopforge_resume` prompt plus
+`submission_guidance` and `submissionHandle` as the per-round payload. Reuse the
+stable environment while the LoopForge version, tool list and policy are
+unchanged; refresh it when they change. A kept-warm runtime must not carry
+execution-affecting mutable state (for example shell variables or REPL values)
+into a new round; the adapter isolates or resets that state. A cache miss must
+never change round governance.
+
+`loopforge_next` and `loopforge_resume` accept an optional
+`currentUserInstruction`. It is host input for that invocation and never
+rewrites the loop task, objective, criteria, constraints or Round Contract;
+omitting it makes the prompt state that none was provided.
+
+Round results keep three kinds of facts separate: the **Agent report**
+(`success_claim`, `outcome`, `blocker`), the **LoopForge decision** (`action`,
+`loop_stop_reason`, `enforcement_reason`), and the persisted **Machine
+evidence** (the round's `evidencePosture`). Explain, a terminal `stopDetail` and
+`resume` of a stopped loop render the same blocks. `completed` means the Agent's
+stop declaration passed the gates; it does not imply machine-backed success.
+`outcome` is the Agent's ONE round conclusion; there is no separate Agent stop
+reason, and `blocker` is its text explanation.
+
+A clean-context prompt carries compact Machine Evidence (the previous committed
+round's evidence posture: workspace/change counts, provider and command
+statuses, contract item statuses, and stable finding ids) plus bounded Working
+Memory compiled from committed reports, assumptions, open questions, consumed
+recoveries, and contract redirects. Machine Evidence is protected and informs
+verification. Working Memory is optional, indivisible, and may be dropped whole
+if the prompt budget cannot fit it; the artifact records whether it rendered
+and its source/rendered/omitted counts. L1 and L2 include the same full fixed
+Working Memory projection, while L0 remains compact. The default prompt
+ceilings are 5,000 / 50,000 / 100,000 characters for L0 / L1 / L2. They are
+safety ceilings, not targets for routine memory omission. Working Memory is
+derived from the canonical state, never a second history, and does not feed a
+gate. Older history is available through `loopforge_replay` (`start`/`end`;
+default last 10 committed positions, at most 50 in an explicit window) and
+`loopforge_status view: "explain"`.
+
+The four required evaluation fields are `outcome`, `output_summary`,
+`constraint_violations`, and `should_continue`. They are the Agent's report,
+not evidence. `outcome` is one of `success | partial | failed | blocked`;
+`success` requires `should_continue=false`, and `blocked` additionally requires
+a non-empty `blocker`. Optional fields let the Agent report events such as
+changed files, discovered constraints, and one `execution_report.claims`
+channel (`cr-` criterion claims are advisory, `rci-` active-contract item
+claims are strict). `objective_refinement` evolves only the overall working
+objective; it never changes operator acceptance, criteria or hard constraints.
+`subtask_boundary` / `subtask_boundary_label` declare an L2 rehydration boundary;
+they are not a workspace checkpoint. `retroactiveClaims` remains a separate
+free-text claim channel checked against a prior round's Git evidence. LoopForge returns guidance with the real references and
+currently applicable fields, plus a receipt that distinguishes saved reports
+from derived effects and machine verification. Read surfaces use
+`agentSuccessClaim`/`agentOutcome` for the Agent's claim and
+`evidencePosture`/`machineBackedSuccess` for machine facts; they are never
+merged. Optional fields are not a completion checklist.
+
+The server also provides status, stop, pause, resume, and replay tools. Two gate
+tools are available only when `policy.gate.enabled` is true. See the MCP tool
+schemas for exact input and output shapes.
+
+## Evidence and contracts
+
+Configured observations and commands let LoopForge compare Agent reports with
+machine-visible facts. Git observes the complete tracked and non-ignored
+untracked workspace boundary. Explicitly configured commands run with an
+executable and argument list, without a shell, and are restricted to the
+workspace. Command evidence is disabled by default. Unavailable or unknown
+observations remain unknown; they are not treated as a pass or an empty diff.
+
+An Agent may propose a Round Contract for a bounded deliverable. Its acceptance
+items bind to configured verification commands. LoopForge validates the
+structure, references, and bindings; the Agent's optional `scope` is a
+report-only intent statement (drift is an info fact, not a rejection). An item
+becomes verified when the Agent claims it is met and all bound commands pass in
+the closing round with the declared binding intact. A command disabled or
+reconfigured later does not rewrite that historical observation; only command
+observations are test facts, never an Agent-reported test count. LoopForge does
+not judge whether the deliverable or its tests are semantically appropriate.
+
+With an after-capable command configured, a continuing round that has a
+successor available must leave an ACTIVE contract for the next round: omit
+`round_contract` to continue the current contract, or declare the next slice.
+The Agent decides whether the current logical round ends through
+`should_continue`; a contract scopes the successor round's bounded work and
+acceptance conditions. It does not decide the round boundary. `maxRounds` is
+LoopForge's hard stop.
+The final configured round has no successor consumer, so it may omit the
+proposal even when the Agent reports `should_continue=true`; LoopForge then
+stops at the configured round limit. A different proposal while the
+contract is open is rejected as `contract_premature` unless it carries
+`round_contract.supersedes` targeting the exact active `rc-*` id; a successor
+for a closed contract must change the acceptance items or it is rejected as
+`contract_successor_unchanged`. Stopping and blocked rounds cannot leave a
+proposal (`contract_on_stop`). The old contract closes as `superseded`; its item
+statuses remain in audit/explain, the workspace is not restored, and the
+redirect round cannot be `completed`. A stale target or unchanged items is
+`contract_invalid`. `scope` is report-only and, like `supersedes`, never
+participates in `rc-*` identity.
+
+Progress is a Git workspace fact with an explicit coverage range. The stall rule
+and prompt freshness consume only that fixed coverage. A custom observation is
+an ordinary report: it is shown in replay and explain as raw observation data,
+but it cannot supply a progress fact or affect stall, freshness, or any other
+decision.
+
+## Recovery and durable history
+
+The Agent may request recovery to a workspace checkpoint: the automatic
+before-image of a prepared round or an explicit mid-round savepoint created with
+`loopforge_checkpoint`. LoopForge resolves the checkpoint through the current
+branch's transaction refs, records a rollback directive, then executes and
+verifies the restore itself against the manifest's complete Git boundary and
+recorded HEAD. Only after verification does it issue the redo prompt; a failed
+restore leaves the directive pending and the session resumable. LoopForge does
+not choose the target or interpret the Agent's reason. Machine-triggered
+backtracks use the same restore protocol. Redo uses a child branch and is
+excluded from the active branch history. The directive preserves the abandoned
+approaches, wrong assumptions, machine-observed vs Agent-reported skipped
+files, compact trigger findings and the Recovery Brief; the Brief states the
+real restore marker (or `restore NOT verified`). A same-round redo replaces
+that numeric round's feedback slot, so the abandoned evaluation is not retained
+as a second copy. Explain, replay, audit and the receipt expose the committed
+checkpoints/restore marker and the directive digest.
+
+Committed typed round documents in the Vault are the factual source.
+`CommittedRoundView` is the shared history read model, and `CanonicalLoopState`
+is compiled from committed facts. Prompts, status views, replay, audit, explain,
+and the optional state file are read or derived views. The state file is
+regenerable and is not a second source of truth.
+
+The prompt contains current governance facts, compact Machine Evidence, and a
+bounded Agent-report Working Memory. It is not a replay of external memory or
+an unbounded conversation summary. LoopForge does not execute the coding task,
+automatically plan or decompose it, or guarantee task completion.
 
 ## TypeScript API
 
-The package exports the runtime in separate entry points:
+The package exposes these entry points:
 
 ```text
-loopforge          protocol types, policy, store, compiler, engine, evidence,
-                   transactions, metrics, and MCP classes
-loopforge/compiler compiler helpers
-loopforge/replay   ReplayBackend
+loopforge          engine, protocol, policy, storage, compiler, evidence, MCP
+loopforge/compiler prompt compiler helpers
+loopforge/replay   read-only ReplayBackend
 loopforge/mcp      MCP server entry point
 ```
 
-The main exports include `createEngine` and `LoopForgeEngine` for an in-process
-engine, `FileLoopStore` for durable JSON storage, `compileLoop` for compiling a
-prompt from committed facts, `ReplayBackend` for read-only history queries,
-`McpServer` for the MCP transport, and `SessionManager` for durable MCP
-sessions. Type declarations are emitted alongside the runtime in `dist/`.
-
-Example import:
+The main entry exports `createEngine`, `LoopForgeEngine`, `FileLoopStore`,
+`compileLoop`, `ReplayBackend`, `McpServer`, `SessionManager`, and protocol
+types. Type declarations are emitted in `dist/`.
 
 ```ts
 import { createEngine, FileLoopStore, compileLoop } from "loopforge";
 ```
 
-Use the generated `.d.ts` files in `dist/` for the exact signatures and input
-types. The public protocol constructors and types are exported from the main
-entry point.
-
-## Persistence and policy
+Use the generated declarations for exact signatures and input types.
 
-LoopForge stores durable loop data under `.loopforge/loops/` and derived human
-state under `.loopforge/state/`. Committed typed round documents are the source
-of truth. The state file can be regenerated and must not be treated as a second
-history.
+## Policy and storage
 
-Runtime behavior is controlled by `loop_policy.json`, read from the workspace
-the process was started in. Evidence commands are explicitly configured, run
-without a shell, and restricted to the workspace. The default policy keeps the
-optional user gate disabled.
+Runtime policy is read from `loop_policy.json` in the selected workspace. A
+missing file uses defaults; a present but invalid file is reported as
+`policy_invalid`. Durable loop data is stored under `.loopforge/loops/`, with
+regenerable state views under `.loopforge/state/`.
 
-A **missing** policy file is normal: the defaults apply. A file that exists but
-cannot be read or parsed is reported as `policy_invalid` with its path rather
-than silently ignored — a configuration nobody chose must not look like a
-working one. `loopforge doctor` reports the policy, the store root, provider
-registration, every configured command's static validity, and the current
-evidence posture; it never executes a command.
+Evidence commands are explicitly configured and disabled by default. The
+optional user gate is also disabled by default. `loopforge doctor` reports
+policy validity, storage readiness, provider registration, command
+configuration, and evidence posture; it does not execute commands.
 
 ## Development
 
-Run these commands from this directory:
+Run from this directory:
 
 ```bash
 npm run check
 npm run build
 npm test
-npm pack --dry-run --json
 npm run verify:artifacts
-git diff --check
 ```
 
-The build generates `../loopforge-protocol.json` and `dist/`. Change protocol
-types in `src/protocol.ts` first, then run the build. Do not edit generated
-artifacts by hand.
+The build generates `../loopforge-protocol.json` and `dist/`. Edit protocol
+types in `src/protocol.ts` first, then build to regenerate artifacts. Do not
+edit generated files by hand.
 
 ## License
 

package/dist/audit.d.ts

@@ -1,23 +1,36 @@
-/** v2.12: Read-only, replayable end-of-loop audit — the verification view.
+/** v2.12/v4.0.3: Read-only, replayable end-of-loop audit — the verification
+ *  view.
  *
  *  Positioning vs loopforge_replay: replay is the factual timeline (what
  *  happened per round); audit is the assessment layer (which claims are
  *  machine-verified, which gates were decided, is the sequence intact).
  *  Everything is derived from committed vault entries — audit never writes.
  *
- *  v3.8: the CONTRACT ITEM axis is the primary completion basis. The criterion
- *  claims stay as an advisory second view — a criterion claim is an agent
- *  statement whose machine backing is mediated by the contract items, so it
- *  cannot be the completion signal. Both axes read the same committed-round
- *  model and the same item reducer the coordinator and explain use.
+ *  v4.0.3: every round reports the SAME persisted evidence posture. A claim is
+ *  `verified` only when a machine criterion fact backs its criterion; Agent
+ *  reports never upgrade themselves. `evidenceVerdict` is the terminal
+ *  posture, while `verdict` is the verification view over structure + posture.
  */
 import type { LoopStore } from "./loop-store.js";
 import type { VaultEntry } from "./loop-store.js";
-import type { ContractItemStatus, SubmissionDiagnostic } from "./protocol.js";
+import type { ContractItemStatus, EvidencePosture, EvidencePostureStatus, FilesReconciliation, SubmissionDiagnostic } from "./protocol.js";
 import type { SubmissionReceipt } from "./protocol.js";
 export interface AuditRound {
     round: number;
-    outcome: string;
+    /** v4.0.3: Agent claim; never a machine verdict. */
+    agentSuccessClaim: boolean;
+    agentOutcome: string;
+    /** v4.0.6: the Agent's blocker text, verbatim (report only). */
+    blocker: string | null;
+    /** v4.0.6: the Agent's committed working-objective refinement, if any. */
+    objectiveRefinement: string | null;
+    /** v4.0.6: the committed redirect derived from the proposal's `supersedes`. */
+    contractRedirect: {
+        contract_id: string;
+        reason?: string;
+    } | null;
+    machineBackedSuccess: boolean;
+    evidencePosture: EvidencePosture | null;
     claims: Array<{
         text: string;
         status: "verified" | "unverified";
@@ -38,12 +51,32 @@ export interface AuditRound {
             status: ContractItemStatus;
         }>;
     } | null;
-    /** v3.9.1: compact submission accounting. The full receipt is available in
-     *  explain/status; audit keeps the fields that matter for its verdict. */
+    /** v4.0.3: committed recovery material that history can still discover. */
+    checkpoints: Array<{
+        checkpoint_id: string;
+        role: "before" | "mid";
+        round: number;
+        content_hash: string;
+    }>;
+    restore: {
+        directive_transaction_id: string;
+        redo_round: number;
+        verified_at: number;
+    } | null;
+    restore_verified: boolean;
+    /** v3.9.1/v4.0.3: compact submission accounting. */
     submission: {
+        record: SubmissionReceipt["record"];
+        entered_history: boolean;
         diagnostics: SubmissionDiagnostic[];
         saved_not_expanded: string[];
         effects: SubmissionReceipt["effects"];
+        verification: {
+            evidence_posture: EvidencePosture;
+            checks: SubmissionReceipt["verification"]["checks"];
+        };
+        files_reconciliation: FilesReconciliation;
+        recovery_checkpoint: SubmissionReceipt["recovery_checkpoint"] | null;
         prompt: {
             level: string;
             dropped_sections: string[];
@@ -58,15 +91,15 @@ export interface AuditGate {
     decidedAt: string;
     round: number;
 }
-/** v3.8: One contract's outcome over the loaned loop, keyed by its content-
- *  addressed id. Re-declaring the same contract later extends the same entry —
- *  the identity says it IS the same contract. */
+/** v3.8: One contract's outcome over the loop, keyed by its content-addressed
+ *  id. Re-declaring the same contract later extends the same entry — the
+ *  identity says it IS the same contract. */
 export interface AuditContract {
     contract_id: string;
     declared_at_round: number;
     first_active_round: number;
     last_active_round: number;
-    closure: "open" | "verified" | "blocked";
+    closure: "open" | "verified" | "blocked" | "superseded";
     closed_at_round: number | null;
     /** Item statuses as of the last round the contract was execution-relevant. */
     items: Array<{
@@ -79,6 +112,8 @@ export interface AuditContractSummary {
     contracts: AuditContract[];
     /** Contracts whose final closure is still `open`. */
     open: number;
+    /** v3.9.9: contracts the Agent explicitly abandoned via a transition. */
+    superseded: number;
     verifiedItems: number;
     insufficientItems: number;
     contradictedItems: number;
@@ -86,14 +121,37 @@ export interface AuditContractSummary {
 }
 export interface AuditResult {
     loopId: string;
+    /** Verification-view verdict: `passed` requires the structure to be intact
+     *  AND the terminal evidence posture to be verified/not_applicable. */
     verdict: "passed" | "incomplete" | "contradicted";
+    /** v4.0.3: the terminal posture itself, unmodified. */
+    evidenceVerdict: EvidencePostureStatus | null;
     rounds: AuditRound[];
+    /** v3.9.6: committed rollback directives — events, never normal rounds. */
+    rollbacks: Array<{
+        round: number;
+        transactionId: string;
+        origin: "agent" | "machine";
+        redoRound: number;
+        targetCheckpointId: string;
+        reason: string;
+        observedSkippedFiles: string[];
+        reportedSkippedFiles: string[];
+        skippedFiles: string[];
+        abandonedRounds: number[];
+        failedRounds: number[];
+        /** v4.0.3: Agent reports preserved by the rollback. */
+        preservedDiscoveries: string[];
+        approaches: string[];
+        wrongAssumptions: string[];
+    }>;
     gates: AuditGate[];
     unresolvedUserGates: string[];
     /** v3.8: the verification skeleton — the primary completion basis. */
     contracts: AuditContractSummary;
     /** Advisory second axis: criterion claims, not the completion signal.
-     *  `declared` and `evidenced` are both DISTINCT-id counts, so they compare. */
+     *  `declared` comes from the immutable operator objective; `evidenced` is the
+     *  machine-verified set. Both are distinct-id counts. */
     criteria: {
         declared: number;
         evidenced: number;

package/dist/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAAA;KAAE,CAAC,CAAC;IACnE,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IACxF;8DAC0D;IAC1D,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,kBAAkB,CAAA;SAAE,CAAC,CAAC;KAC9D,GAAG,IAAI,CAAC;IACT;8EAC0E;IAC1E,UAAU,EAAE;QACV,WAAW,EAAE,oBAAoB,EAAE,CAAC;QACpC,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9D,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;iDAEiD;AACjD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACzC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8EAA8E;IAC9E,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,GAAG,YAAY,GAAG,cAAc,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,sEAAsE;IACtE,SAAS,EAAE,oBAAoB,CAAC;IAChC;mFAC+E;IAC/E,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,mBAAmB,EAAE,OAAO,CAAC;IAC7B;;iFAE6E;IAC7E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,CAAC,EAAE,SAAS,GAChB,WAAW,CA2Mb"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}