omnius 1.0.591 → 1.0.592

package/docs/work-orders/world-class-memory-compiler/README.md

@@ -0,0 +1,162 @@
+# World-Class Memory Compiler Program
+
+**Status:** active implementation program  
+**Owner:** Omnius orchestration and memory packages  
+**Last updated:** 2026-07-13
+
+## Mission
+
+Replace chronological transcript compaction with a provenance-preserving memory
+compiler. The compiler manages context as a materialized view of typed,
+versioned task memory; it does not coerce the agent's reasoning, deny tool use,
+or replace evidence with generic summaries.
+
+The implementation has one non-negotiable invariant:
+
+> Memory management may preserve, retrieve, organize, and defer. It must never
+> block exploration, source reads, edits, verification, or a model's legitimate
+> change of plan.
+
+## Architecture at a glance
+
+```text
+immutable event ledger ──► typed memory records ──► dependency graph
+                                      │                    │
+                                      └────► hybrid index ◄─┘
+                                                     │
+exact outbound request ──► budget compiler ──► working-set materializer
+                                                     │
+                                    isolated inference memory compiler
+                                                     │
+                                      validated MemoryDelta + audit trail
+```
+
+The outbound request is built before any compaction decision. Its complete
+budget includes stable prompts, tool schemas, active steering, task state,
+selected evidence, output reservation, and safety margin. No automatic or
+manual compaction may run while the final request has at least 40% of the real
+model context window free.
+
+## Memory classes
+
+| Class | Canonical contents | Rule |
+|---|---|---|
+| Authority | current user intent, active steering, trusted policy | never summarize or retrieve from untrusted content |
+| Task / working set | open requirements, next action, unresolved claims, live verifier | materialize for the active task epoch |
+| Artifact | exact files/chunks, content hash, range, revision | exact body is canonical; extract is derived |
+| Action ledger | intent → tool call → result → mutation → verifier → outcome | preserve transaction integrity |
+| Episodic | immutable event history | archive-first; not blindly model-visible |
+| Semantic | validated facts and decisions with temporal validity | source-backed and supersedable |
+| Procedural | validated reusable workflow lessons | explicitly promoted, never inferred from one failure |
+
+## Work-order index and execution todos
+
+| ID | Work order | Depends on | Status | Completion evidence |
+|---|---|---|---|---|
+| WO-01 | [Exact Request and Budget Compiler](./WO-01-exact-request-budget.md) | — | in progress | exact serializer, dump ledger, threshold tests |
+| WO-02 | [Typed Memory Fabric and Event Ledger](./WO-02-typed-memory-fabric.md) | WO-01 | in progress | immutable ledger, authority/progress tests |
+| WO-03 | [Dependency Graph and Working-Set Materializer](./WO-03-dependency-working-set.md) | WO-02 | in progress | graph-cut, active-root, and transaction tests |
+| WO-04 | [Inference-Driven Memory Compiler](./WO-04-inference-memory-compiler.md) | WO-01, WO-03 | in progress | exact-request shadow proposal tests |
+| WO-05 | [Artifact Fidelity and Explicit Materialization](./WO-05-artifact-fidelity-materialization.md) | WO-02, WO-03 | in progress | full-read, stale revision, extract coverage tests |
+| WO-06 | [Temporal Hybrid Retrieval](./WO-06-temporal-hybrid-retrieval.md) | WO-02, WO-03, WO-05 | in progress | retrieval/relevance/abstention tests |
+| WO-07 | [Replay Evaluation and Adversarial Harness](./WO-07-evaluation-harness.md) | WO-01–WO-06 | in progress | deterministic trace reports and tiered harness results |
+| WO-08 | [Shadow Rollout, Migration, and Legacy Removal](./WO-08-rollout-legacy-removal.md) | WO-07 | planned | canary report, rollback drill, legacy deletion |
+
+`[ ]` entries in each work order are the canonical engineering todos. The
+[granular tracker](./TRACKER.md) reconciles every implementation and promotion
+subtask. An item cannot be marked complete from a model claim: it requires the
+named code, focused tests, typecheck, and recorded acceptance evidence.
+
+## Global acceptance criteria
+
+- [ ] The compaction trigger uses the exact pending request, not historical
+  messages alone.
+- [ ] No request compacts with 40% or more real-window headroom remaining.
+- [ ] A current action, exact evidence it needs, and its verifier remain an
+  atomic dependency transaction.
+- [ ] Current user authority and unacknowledged steering are present exactly
+  once and cannot be overwritten by history or tool output.
+- [ ] Full source reads are first-class; branch extraction is derived,
+  coverage-checked, and never silently substitutes for source.
+- [ ] Memory compiler failure results in `hold` and an audit record, never
+  heuristic deletion.
+- [ ] Repeated identical compiler analyses are deduplicated by a content/state
+  fingerprint; state change is required to re-run.
+- [ ] All compaction choices are inspectable in the TUI and session logs.
+- [ ] The implementation is benchmarked on real replay traces and adversarial
+  traces across small, medium, and large model tiers before enforcement.
+
+## Research basis
+
+These work orders borrow principles, not implementations. LongMemEval motivates
+separate indexing, retrieval, and reading with temporal updates and abstention;
+MemGPT motivates memory tiers; RAPTOR motivates retaining raw leaves beside
+derived hierarchy; graph-memory work motivates associative recall; and
+instruction hierarchy motivates authority separation. See
+[LongMemEval](https://arxiv.org/abs/2410.10813),
+[MemGPT](https://arxiv.org/abs/2310.08560),
+[RAPTOR](https://arxiv.org/abs/2401.18059),
+[HippoRAG 2](https://arxiv.org/abs/2502.14802), and
+[Instruction Hierarchy](https://arxiv.org/abs/2404.13208).
+
+Research claims are hypotheses to test against Omnius traces, not a reason to
+copy a paper's architecture wholesale.
+
+## Verified implementation evidence — 2026-07-13
+
+- `request-budget.ts` snapshots and fingerprints the actual JSON-wire-equivalent
+  outgoing payload (including aliases and model-visible memory prefixes), then
+  computes a segmented budget from that one immutable request; every
+  context-window dump persists or safely recompiles that exact budget.
+- `ContextMemoryLedger` persists append-only authority, task, action, tool,
+  artifact, mutation, verifier, dependency, transaction, and supersession
+  records. The runner records the user/task root before its first tool call and
+  records tool transactions without making telemetry a tool gate.
+- `memory-compiler.ts` rejects an inference cut that would archive authority,
+  active dependency evidence, a partial tool transaction, an unknown record,
+  or an insufficiently classified proposal.
+- Full source reads remain canonical in `EvidenceLedger`; a completed manual
+  branch extract can replace only the rendered view while canonical source is
+  retained. Automatic branch routing now requires real headroom exhaustion
+  rather than a fixed 20% file-size boundary. Capped grep/tool output is typed
+  partial success with recoverable provenance and deterministic narrowing.
+- Active working sets are graph- and transaction-closed: a soft rendering
+  budget may omit optional history but cannot split a live action from its
+  call, result, source, mutation, or verifier. The bounded retriever filters
+  by epoch, authority, temporal validity, path/revision/range and active graph
+  roots before lexical/host-semantic ranking; it returns explicit abstention on
+  missing or over-budget evidence.
+- The existing isolated compaction analyst now caches byte-identical state
+  signatures and exposes cache/fingerprint information in its audit record.
+- The exact final request now drives the v2 inference memory compiler at the
+  shared pre-backend boundary. It projects every mutable message body into a
+  typed candidate, requires one inference-selected disposition per candidate,
+  and applies nothing unless graph, authority, artifact, and exact
+  post-materialization budget checks all pass. Missing or invalid inference is
+  a `hold`, never a heuristic truncation. `OMNIUS_MEMORY_COMPILER_MODE=shadow`
+  is the explicit rollback/diagnostic mode.
+- Immutable `omnius-artifact://sha256/...` references are range-readable with
+  the first-class `artifact_read` tool. A partial representation is trusted
+  code materializing declared lines from that object, never model-authored
+  source text.
+- `memory-compiler-replay.mjs` executes versioned, deterministic adversarial
+  fixtures against the production ledger, request budget, and graph-cut
+  validator. Current cases include active evidence, partial extraction,
+  prompt-shaped tool data, source supersession, verifier-after-change, and a
+  20-artifact batch.
+
+Focused verification completed:
+
+```text
+@omnius/orchestrator: 66 focused tests passed
+@omnius/memory: 11 SQLite ledger tests passed
+@omnius/execution: 27 focused tests passed
+TypeScript: all 11 workspace packages built
+memory compiler replay: 14/14 deterministic adversarial scenarios passed
+live large-model extraction: 20/20 approved-A100 contracts passed
+```
+
+These are foundations, not a release claim. WO-07 and WO-08 remain incomplete
+until real redacted trace comparison, controlled model-tier evaluation,
+shadow-operation evidence, canary/rollback, and legacy-path deletion prove the
+new pipeline is safer than the old one.

package/docs/work-orders/world-class-memory-compiler/TRACKER.md

@@ -0,0 +1,179 @@
+# Memory Compiler Implementation Tracker
+
+**Last reconciled:** 2026-07-13  
+**Authority:** This file is the granular program tracker. The work-order
+documents define the contract and acceptance criteria; neither test output nor
+a model claim may check an item without the named evidence.
+
+## WO-01 — Exact outbound request
+
+- [x] Capture a JSON-wire-equivalent outbound request snapshot before shadow
+  analysis.
+- [x] Fingerprint the complete request payload, not selected message fields.
+- [x] Account for messages, tools, memory prefix, output reserve, safety
+  reserve, `numCtx`/`num_ctx`, and `maxTokens`/`max_tokens`.
+- [x] Persist/reuse a precompiled budget only after request-byte/hash match.
+- [x] Keep normal and brute request envelope fields in parity.
+- [x] Regression-test late prefix/schema/alias changes and snapshot isolation.
+- [ ] Extract all request construction into one side-effect-free intermediate
+  model.
+- [ ] Add a backend tokenizer adapter and estimator provenance to accounting.
+- [ ] Include backend prompt-template normalization and think-mode reserve in
+  the final compiler budget.
+- [x] Route active automatic compaction through the final request budget and
+  shared pre-backend boundary; the legacy `/compact` path is available only
+  under the explicit `OMNIUS_MEMORY_COMPILER_MODE=shadow` rollback mode.
+- [ ] Remove legacy post-assembly accounting after a parity replay proves it
+  redundant.
+
+## WO-02 — Typed memory fabric
+
+- [x] Define authority, task, claim, artifact, extract, action, tool result,
+  mutation, verifier, outcome, semantic, procedural, and orientation records.
+- [x] Persist epoch, authority/trust class, provenance, revision/range,
+  fidelity, content hash, validity interval, and metadata.
+- [x] Create append-only SQLite records, transactions, dependencies, and
+  working-set snapshots.
+- [x] Add record and transaction idempotency/conflict protection.
+- [x] Reject non-user/non-system `trusted_instruction` records.
+- [x] Reject unsupported semantic facts.
+- [x] Store raw user intent and substantive progress independently of read and
+  diagnostic noise.
+- [x] Model source supersession without deleting historical records.
+- [ ] Add a dual-read adapter for every older memory/event store.
+- [ ] Migrate historical evidence/run-event ingestion through the adapter.
+- [ ] Add a deterministic replay of a migrated real event stream.
+
+## WO-03 — Dependency graph and working set
+
+- [x] Record action → tool call → result transactions from runner tool calls.
+- [x] Attach canonical file artifacts once; store a compact tool-result receipt.
+- [x] Attach mutations and shell verifier observations to the transaction.
+- [x] Close materialization over required graph dependencies.
+- [x] Close materialization over entire intersecting transactions.
+- [x] Preserve a transaction even when its presentation cap is lower than its
+  atomic record count.
+- [x] Persist active-root snapshots and graph explanations in request audits.
+- [ ] Link todo/workboard state and every legacy evidence event into the graph.
+- [ ] Rank open requirement/current action/unresolved claim/verifier state,
+  rather than only record kind and recency.
+- [x] Render a production model-visible request projection only from a
+  validated v2 plan; the durable graph and transcript remain untouched.
+
+## WO-04 — Inference memory compiler
+
+- [x] Send isolated compiler candidates as explicitly untrusted data.
+- [x] Validate full candidate classification, IDs, authority boundary,
+  confidence, request fingerprint, graph cut, and transaction integrity.
+- [x] Cache unchanged decisions by exact final-request fingerprint.
+- [x] Make malformed/overlarge/incomplete analysis a `hold`, never deletion.
+- [x] Run the compiler in non-blocking shadow mode and audit its decision.
+- [x] Test prompt-like tool data, stale fingerprints, duplicate classifications,
+  active evidence, partial transaction, and 40%-headroom holds.
+- [x] Add an exact-request compatibility projection from every mutable
+  model-visible string body to a typed, provenance-bound ledger candidate.
+- [x] Bound and source-link model-visible orientation separately from audit
+  payloads; audit receipts contain locators and justifications, never bodies.
+- [ ] Add an independent second opinion for ambiguous/high-risk shadow deltas.
+- [x] Apply accepted v2 plans atomically only after inference, graph/artifact,
+  and exact post-materialization 45–52% budget validation pass.
+- [x] Disable every legacy heuristic/message-summary path while active; any
+  failed, missing, or invalid inference plan holds the complete request.
+
+## WO-05 — Artifact fidelity and materialization
+
+- [x] Keep normal/explicit full reads canonical and hash/range-addressable.
+- [x] Admit full reads using actual headroom rather than a fixed percentage.
+- [x] Preserve an admitted full body for its turn instead of generic output
+  folding.
+- [x] Retain a completed extract as derived evidence while canonical full
+  source remains recoverable.
+- [x] Keep partial extracts from hiding full source or satisfying coverage.
+- [x] Honor declared requirement search terms and credit an overlapping exact
+  source anchor to every requirement it independently proves.
+- [x] Treat output/line/capture-capped grep output as success with partial
+  provenance and deterministic narrowing.
+- [x] Supersede changed canonical source revisions and permit a justified reread.
+- [x] Enforce a closed A100-class hardware preflight in the live 20-file
+  harness.
+- [x] Capture a successful 20-file `robit/ornith:35b` A100 report: 20/20
+  complete two-requirement contracts, no unresolved coverage, 20 isolated
+  requests, and a 6,080-character largest branch prompt.
+- [x] Persist an idempotent materialization record for every rendered full
+  source body, naming the active action and canonical artifact revision.
+- [x] Record extractor kind/model/confidence/search-round provenance as typed
+  metadata on every derived artifact record.
+- [x] Persist canonical model-visible tool artifacts in an immutable SHA-256
+  store and expose a range-safe `artifact_read` resolver for retained refs.
+
+## WO-06 — Temporal hybrid retrieval
+
+- [x] Enforce epoch, typed task/action/claim roots, authority boundaries, and
+  token/character limits.
+- [x] Implement exact path/revision/range filtering before lexical scoring.
+- [x] Add temporal `asOf` filtering and artifact supersession handling.
+- [x] Traverse active-work dependencies bidirectionally with six-hop/128-node
+  bounds and truncation disclosure.
+- [x] Use deterministic ranking and one-materialized-body-per-source diversity.
+- [x] Surface active refutation and explicit missing/over-budget abstention.
+- [ ] Integrate a versioned vector/semantic index rather than host callback
+  scoring only.
+- [ ] Join retrieval across legacy memory stores through the WO-02 adapter.
+- [ ] Measure next-action evidence recall/precision against redacted traces.
+
+## WO-07 — Evaluation
+
+- [x] Create a versioned deterministic graph-memory replay report with stable
+  scenario/reason/report fingerprints.
+- [x] Exercise active source, transaction, supersession, partial extract,
+  `/nothink` tool data, stale fingerprint, duplicate, confidence, and headroom
+  adversarial cases.
+- [x] Emit candidate/retention/archive/request/graph/transaction metrics.
+- [x] Add a closed-whitelist real-trace importer that emits text-free,
+  salted-pseudonym behavioral fixtures and rejects raw/unknown fields.
+- [ ] Define a redacted real-trace ingestion schema and source-body redactor.
+- [ ] Import representative MyActuator and Omnius traces with consented,
+  non-source-sensitive fixtures.
+- [ ] Run current/no-compaction/summary/selector/compiler baselines over the
+  same trace corpus.
+- [ ] Measure stale use, duplicate reads, false-not-found, repeated action
+  signatures, completion, latency, and cost.
+- [ ] Add a natural mid-action no-mutation steering replay with first-affected
+  action assertion.
+- [x] Complete the live large-model 20-file run on approved A100 hardware.
+- [ ] Run approved small and medium model tiers with identical contracts.
+- [ ] Publish objective promotion thresholds from the comparison report.
+
+## WO-08 — Rollout and removal
+
+- [x] Make strict v2 request compilation the default. `shadow` is an explicit
+  rollback/diagnostic mode; active inference failure holds instead of reviving
+  a heuristic deletion path.
+- [x] Emit exact request budget and shadow decision into request-dump audit.
+- [x] Emit body-free applied/hold/rejected plan receipts with classifications,
+  artifact locators, rationale, and pre/post request fingerprints into dumps
+  and expandable TUI compaction audit boxes.
+- [ ] Define explicit flags for ledger dual-write, graph materialization,
+  shadow, active compiler, and second opinion.
+- [ ] Render the full lifecycle in TUI/session telemetry: budget → working set
+  → delta → hold/apply → first affected action.
+- [ ] Define authority/fidelity/tool-freedom promotion thresholds.
+- [ ] Canary by session and model tier with one-click rollback to untouched
+  history.
+- [ ] Exercise and document rollback.
+- [ ] Delete synthetic recap, silent rehydration, stale-controller, and
+  heuristic fallback paths only after canary acceptance.
+- [ ] Remove obsolete flags/tests/docs in the same release.
+
+## Promotion status
+
+- [x] Foundation code typechecks and focused regression suite passes.
+- [ ] Deterministic replay meets published comparison thresholds.
+- [x] Approved large-model live harness report is captured.
+- [ ] Approved small/medium/large comparative runs are captured.
+- [ ] Shadow telemetry is reviewed on real redacted traces.
+- [ ] Canary and rollback drill are accepted.
+- [ ] Legacy deletion is complete.
+
+Until every promotion item is checked, this program is **not deployable** and
+must not be represented as replacing the legacy compaction path.

package/docs/work-orders/world-class-memory-compiler/WO-01-exact-request-budget.md

@@ -0,0 +1,79 @@
+# WO-01 — Exact Request and Budget Compiler
+
+**Status:** in progress  
+**Primary modules:** `packages/orchestrator/src/agenticRunner.ts`,
+`contextWindowDump.ts`, `context-compiler.ts`, `context-fabric.ts`  
+**Depends on:** none
+
+## Problem
+
+The old compaction path estimated only durable history. The actual outgoing
+request subsequently appended system text, tool schemas, dynamic controller
+frames, active steering, evidence, and output reservation. A history that
+appeared safe could therefore send an overfull or low-signal request; the
+inverse caused needless compaction.
+
+## Contract
+
+Create one pure `compileOutboundRequestBudget()` path that receives the exact
+request payload and returns a reproducible ledger:
+
+```ts
+interface OutboundRequestBudget {
+  requestFingerprint: string;
+  modelContextTokens: number;
+  stableSystemTokens: number;
+  toolSchemaTokens: number;
+  authorityTokens: number;
+  taskAndWorkingSetTokens: number;
+  evidenceTokens: number;
+  historyTokens: number;
+  outputReservationTokens: number;
+  safetyMarginTokens: number;
+  totalInputTokens: number;
+  projectedTotalTokens: number;
+  freeTokens: number;
+  freeRatio: number;
+  compactionEligible: boolean;
+}
+```
+
+`compactionEligible` is false while `freeRatio >= 0.40`. It must be based on
+the serialized request, with a conservative estimator used only where the
+backend tokenizer is unavailable. The fingerprint covers all materialized
+segments and their hashes, not timestamps.
+
+## Todos
+
+- [ ] Extract request assembly into a side-effect-free intermediate request
+  model, preserving current request behavior.
+- [x] Count each rendered segment separately, including tool schemas and output
+  reservation.
+- [ ] Add a tokenizer adapter with deterministic conservative fallback and
+  expose estimator provenance in dumps.
+- [ ] Make automatic and manual compaction consume this budget only.
+- [x] Use request fingerprints to suppress duplicate analysis while all inputs
+  are identical.
+- [ ] Extend context-window dump and TUI compaction box with the segment ledger,
+  projected headroom, threshold decision, and fingerprint.
+- [ ] Remove duplicated post-assembly accounting paths after parity tests pass.
+
+## Acceptance tests
+
+- A large tool schema or dynamic frame changes eligibility even if `messages[]`
+  does not change.
+- At 40.0% or more free real context, both auto and manual compaction hold.
+- At 39.9% free context, the compiler can request compaction but does not alter
+  agent/tool permissions.
+- Two byte-equivalent requests produce the same fingerprint and one analyst
+  invocation.
+- A changed active steering slot, file hash, tool schema, or output reservation
+  produces a new fingerprint.
+- The dump totals reconcile to the exact request estimate within documented
+  tokenizer rounding.
+
+## Definition of done
+
+Focused unit and integration tests pass, the orchestrator typecheck passes, and
+one fixture demonstrates a previous history-only false decision corrected by
+final-request accounting.

package/docs/work-orders/world-class-memory-compiler/WO-02-typed-memory-fabric.md

@@ -0,0 +1,65 @@
+# WO-02 — Typed Memory Fabric and Immutable Event Ledger
+
+**Status:** in progress  
+**Primary modules:** `packages/memory/src/*`, `packages/schemas/src/memory.ts`,
+`packages/orchestrator/src/evidenceLedger.ts`, `runEvents.ts`  
+**Depends on:** WO-01
+
+## Problem
+
+Conversation messages currently carry incompatible roles: authority,
+observations, evidence, plans, outcomes, and stale controller prose. A summary
+can accidentally change their meaning or authority.
+
+## Contract
+
+Introduce a canonical envelope shared by persisted memory classes:
+
+```ts
+interface MemoryRecord<T> {
+  id: string;
+  kind: "authority" | "task" | "artifact" | "action" | "episode" |
+        "semantic" | "procedural";
+  taskEpoch: string;
+  authority: "system" | "user" | "agent" | "tool-data" | "derived";
+  provenance: { producer: string; sourceIds: string[]; contentHash?: string };
+  validFrom: string;
+  validUntil?: string;
+  supersedes?: string[];
+  confidence?: number;
+  payload: T;
+}
+```
+
+Events are append-only. Current state is a derived projection; no mutation may
+silently rewrite the event that established its evidence.
+
+## Todos
+
+- [ ] Reconcile existing memory types and stores with the canonical envelope;
+  reuse compatible schemas rather than introducing duplicates.
+- [x] Add explicit authority, artifact revision, action transaction, semantic
+  fact, and procedural-promotion payload types.
+- [x] Create an append-only, per-epoch event ledger with deterministic ordering
+  and idempotency keys.
+- [x] Build a projection that resolves supersession without deleting history.
+- [ ] Migrate current evidence and run events through adapters with dual-read
+  compatibility.
+- [x] Persist raw user intent, epoch, artifact evidence, and last substantive
+  progress independently of diagnostics.
+- [x] Reject a derived/tool-data record attempting to become authority.
+
+## Acceptance tests
+
+- Revising a file yields a new artifact record linked to, rather than replacing,
+  the old revision.
+- A semantic fact without source IDs cannot enter the validated semantic view.
+- Diagnostics and failed empty reads do not advance substantive-progress state.
+- Replaying the same event stream produces an identical projection.
+- User authority remains distinct even when tool output contains imperative
+  text.
+
+## Definition of done
+
+Schema tests, store round-trip tests, migration fixtures, and an event replay
+test prove deterministic state reconstruction.

package/docs/work-orders/world-class-memory-compiler/WO-03-dependency-working-set.md

@@ -0,0 +1,55 @@
+# WO-03 — Dependency Graph and Working-Set Materializer
+
+**Status:** in progress  
+**Primary modules:** `packages/memory/src/memoryGraph.ts`, `temporalGraph.ts`,
+`packages/orchestrator/src/evidenceLedger.ts`, `agenticRunner.ts`  
+**Depends on:** WO-02
+
+## Problem
+
+Message-level retention can split an action from its tool result or retire a
+source body still required by a pending edit or verifier.
+
+## Contract
+
+Represent active work as immutable graph nodes and edges:
+
+```text
+task ─requires→ claim ─supported-by→ artifact evidence
+  └plans→ action ─invokes→ tool call ─produces→ result
+                    └mutates→ artifact revision ─verified-by→ verifier outcome
+```
+
+The materializer takes active task/steering plus the projected memory graph and
+returns the smallest evidence-closed working set. An action transaction is
+atomic for retention unless its outcome is terminal and all dependants are
+closed.
+
+## Todos
+
+- [x] Define node/edge types and graph invariants in schemas.
+- [x] Emit graph transactions from tool calls, mutations, verifier results,
+  canonical file evidence, and exact-request projections; todo/workboard
+  backfill remains a separate migration task.
+- [x] Add dependency closure and safe graph-cut algorithms.
+- [ ] Implement a materializer that ranks open requirements, current action,
+  unresolved claims, and verifier dependencies above recency.
+- [x] Preserve exact evidence bodies once, referenced by stable IDs elsewhere.
+- [x] Surface a graph explanation in context audit records.
+- [x] Link an exact request projection back to matching active graph evidence
+  before validation, so graph-cut safety protects the rendered copy too.
+
+## Acceptance tests
+
+- An assistant tool call and each matching tool result cannot be split.
+- An exact file range remains materialized while an open edit or verifier cites
+  it.
+- A completed, unreferenced discovery transaction can archive without changing
+  the active set.
+- A failed verifier remains eligible for rerun after a dependent source revision
+  changes; no verifier lock is introduced.
+
+## Definition of done
+
+Graph invariants, closure tests, and a MyActuator-derived fixture pass without
+reintroducing historical controller recaps.

package/docs/work-orders/world-class-memory-compiler/WO-04-inference-memory-compiler.md

@@ -0,0 +1,67 @@
+# WO-04 — Inference-Driven Memory Compiler
+
+**Status:** in progress  
+**Primary modules:** `packages/orchestrator/src/compaction-analyst.ts`,
+`agenticRunner.ts`, `contextWindowDump.ts`  
+**Depends on:** WO-01, WO-03
+
+## Problem
+
+An inference selector that chooses individual transcript messages is safer than
+heuristics but is still not a memory compiler: it lacks graph constraints,
+state-signature deduplication, version awareness, and a meaningful `hold`
+contract.
+
+## Contract
+
+The isolated worker sees the real candidate context, typed as untrusted data,
+and returns a schema-validated `MemoryDelta`. It is read-only, cannot write
+model-visible history directly, and cannot deny main-agent tools.
+
+```ts
+interface MemoryDelta {
+  decision: "compact" | "hold";
+  requestFingerprint: string;
+  retain: string[];
+  archive: Array<{ id: string; reason: "completed" | "superseded" | "noise" }>;
+  supersede: Array<{ old: string; next: string }>;
+  unresolvedClaims: string[];
+  orientation?: string;
+  coverage: { allCandidatesClassified: boolean };
+  confidence: number;
+}
+```
+
+## Todos
+
+- [x] Project every mutable exact-request message body into a provenance-bound
+  graph record while retaining the legacy analyst only for explicit shadow
+  rollback tests.
+- [x] Supply the complete outbound-request budget and working-set query.
+- [x] Require coverage of all eligible candidates and validate hashes, graph
+  closure, authority, and budget before apply.
+- [x] Cache `hold` and `compact` decisions by request fingerprint; invalidate
+  only on task, authority, artifact, action, or budget change.
+- [x] Keep model-visible orientation bounded, source-linked, and newly derived;
+  retain full analyst inputs/outputs only in audit logs.
+- [ ] Route ambiguous/high-risk deltas to a second opinion in shadow mode; a
+  disagreement holds compaction, never blocks the main agent.
+- [x] In active mode, disable heuristic fallback behavior; invalid/missing
+  inference keeps the complete exact request unchanged. Legacy behavior exists
+  only behind explicit shadow rollback while canary evidence is gathered.
+
+## Acceptance tests
+
+- Invalid IDs, missing classifications, broken dependencies, unknown hashes, or
+  over-budget output produce `hold` with no memory deletion.
+- Identical calls reuse a cached result; a changed file hash invokes analysis.
+- Prompt-like content in source/tool output cannot change the analyst's
+  authority contract.
+- The worker may defer compaction but the parent still permits reads, edits,
+  exploration, and verification.
+
+## Definition of done
+
+Contract, cache, fault-injection, prompt-injection, active materialization,
+and audit tests pass. Shadow remains available for rollback/replay comparison;
+active mode is strictly hold-on-failure and never blocks agent tools.