[DEL-A2] Native Controller-owned Issue Working Memory and Evidence Ledger

Begin by reading EPIC #315 and its hard dependency #316 (DEL-A1) to ground the controller-owned model, then review ADR 0004 and the existing SafeRoot/lock code. The work implements a native, crash-consistent SQLite-backed Ledger with typed redaction under Python, so locate the current MemoryStore and single-agent execution path. 'Done' means all acceptance checks pass with regression tests for atomic create/reconcile and no sensitive data leakage.

Parent: EPIC #315 · Stage M1 (native Issue Working Memory) · Size L · Reconciled 2026-10-25 (UTC) against main at f04db5f (state protocol 12). "Current scope" is authoritative. The earlier planning text follows verbatim and still applies where it does not conflict.

Current scope (reconciled 2026-10-25)

Deliver the first usable, bounded, controller-owned MemoryStore for one Issue. It is the storage and read half of the Memory MVP; #333 integrates it into the running single-agent workflow. This issue on its own does not prove that Memory is useful in a run.

Record model

Types, or equivalent representations, for:

• MemoryFact: one typed claim with a semantic class;
• MemoryEvent: an append-only lifecycle event on a fact;
• MemoryScope: repository, issue, run, phase and candidate (base and candidate SHA);
• EvidenceRef: a reference to a controller-owned receipt (validation record, review, Git object, effect record), with its retention status;
• MemoryFreshness: the revision, watermark and staleness reported on every read;
• Correction / Retraction: typed events naming the fact they act on, the actor and the reason;
• ContextProjection: the bounded, read-only selection handed to an agent.

Semantic classes: verified observation, unverified observation, hypothesis, failed approach, candidate-specific finding, repository constraint, task handoff summary. Model confidence is advisory metadata, never verification.

Lifecycle

candidate, active, superseded, retracted, rejected and needs_revalidation, or an explicit equivalent that #316 ratifies. Every authoritative lifecycle transition records its actor, reason, provenance, scope and applicability.

A model may propose a record. Controller-owned typed validation and policy decide whether the proposal enters the ledger, and with what trust status. A stored proposal is not thereby proven true.

Persistence and trust

• SafeRoot-compatible storage, atomic publication, crash recovery and strict schema validation on load.
• Issue, run, phase and candidate identity on every record; bounded record counts and sizes.
• Redaction before persistence, with the run-log redactor. No secrets, raw transcripts, hidden reasoning, prompts or whole diffs.
• Controlled retention and expiry.
• An explicit rule for an EvidenceRef whose receipt was evicted or is missing (validation records are bounded to 64, src/autoforge/evidence.py:77). The fact is downgraded, never silently kept as verified.
• Durable corrections and retractions; replay never resurrects a stale or retracted record.
• No cross-issue reads by default.
• No isolation claim stronger than the launch has. Under sandbox.mode: disabled a same-UID agent can reach controller files by absolute path, and the docs say so.

Initial read interface

A small, deterministic, read-only function produces a bounded ContextProjection from typed Issue records. It selects by scope, status, candidate compatibility, recency and provenance, under fixed ranking rules and explicit size and token limits. It needs no live memory tool callback (AgentRequest, src/autoforge/providers.py:281, has none). Full-text search and semantic retrieval belong to #324, in EPIC #331.

Not required for the MVP

Vector embeddings, LTSearch, external databases or daemons, cloud services, repository-wide search, offline consolidation, agent plugins or skills, transcript capture.

The earlier text's incremental source export for #326 and its bounded derived episodic summary are deferred to EPIC #331: #326 (or a follow-up there) builds them against this store when that EPIC starts. This issue closes without them, and neither #333 nor #319 waits for them.

Dependencies

• Hard (native): #316.
• Blocks (native): #333, #319, #320; and #324, #325, #326 in EPIC #331.
• Coordination: #332 (compatible EvidenceRef and context contracts), #23 (protocol), #281 / #284 / #285 (the redaction functions this store relies on).

Acceptance criteria (added 2026-10-25)

• A finding can be stored and recovered after a controller restart.
• A wrong hypothesis can be retracted and stays retracted after replay and rebuild.
• A stale candidate-specific fact is not silently served as current.
• A verified observation is not superseded by newer, unsupported text.
• A projection is reproducible from the same Memory revision and policy.
• Every output is bounded and redacted.
• With Memory disabled, single-agent behaviour and state are unchanged.
• No GitHub effect and no workflow transition arises from a Memory record.

Earlier planning text (verbatim)

Superseded where it conflicts with "Current scope" above. In particular:

• The incremental source export for #326 and the derived episodic summary are not part of this issue's MVP.
• The read-only surface is consumed first by #333, then by #319.
• The "SQLite events/projections" wording does not pre-decide storage; #316 decides it.
• #324 and #325 now belong to EPIC #331.

Parent: EPIC #315 · Wave A · Size L · Planning baseline f4fd5ef (2026-10-25 UTC). Research: GVS5H, not an implementation dependency.

Objective / deliverable

Implement a controller-private, atomic per issue/run/phase/candidate SHA Ledger storing bounded plan, curated facts with source/evidence references, attempts, verifier summaries and handoff. Treat worker-generated notes as untrusted input. Use SafeRoot/path containment, versioned typed schema, explicit expiry and retention, redaction and size/record budgets; never store raw model reasoning, credentials, whole diffs, prompts or uncontrolled transcripts by default. Preserve legal notes across FIX only after binding/reconciliation.

Dependencies

• Hard: #316 (DEL-A1)
• Coordination only: #147 SDK providers / #126 interactions, #154 usage, #176 scheduler and #266 sandbox. Do not add blanket cross-EPIC hard blockers without evidence.

Acceptance criteria

• Schema and redaction prevent path traversal, symlinks, prompt-injection promoted to authority, oversized input and replay across issue/run/candidate
• Crash-window tests prove atomic create/update and deterministic reconcile without corruption or lost verified candidate
• Candidate drift invalidates or distinctly marks stale assumptions; no notes treated as review evidence or GitHub effect commands
• Bounded recap and handoff are reproducible from validated Ledger entries with provenance and version
• No sensitive data in state/log/Artifact; no migration without #23 protocol decision
• Regression tests preserve original single-agent path, ADR 0004 controller-owned effects, exact candidate validation, ReviewCertificate and merge safety; provider credentials remain isolated.
• Docs/doctor/config compatibility updated where behavior changes; skipped real-runtime evidence never reported as pass.

Invariants / exclusions

The LLM Manager is advisory. Controller exclusively owns done acceptance, typed GitHub effects, state transitions, candidate identities and merge. Inner tasks are not GitHub native sub-issues and do not modify EPIC graph. Neither Agent nor verifier may execute repository-controlled commands outside the existing sandbox. No unbounded raw transcript/reasoning recording or ambient credentials. Feature remains opt-in; no Public Alpha #255 gate. Coordinate persisted schema on #23 before migration. Do not copy GVS5H's arbitrary subprocess verifier or its text-hash scratchpad and call it production recovery.

Verification hints

Use deterministic fake provider plus real existing CLI integration where available; include redacted bounded evidence, attack cases, failure/cancel/resume, explicit run/issue/candidate SHA. No new orchestration daemon or scheduler.

Native MemoryStore / Evidence Ledger contract (2026-10-24)

Implement Memory state and evidence handling natively in AutoForge; do not couple correctness to retrieval technology. Retain the already specified bounded, run/candidate-bound issue ledger and strengthen its semantics:

• Typed append/replay or equivalently auditable and crash-consistent SQLite events/projections for MemoryFact, MemoryEvent, MemoryScope, EvidenceRef, MemoryFreshness. The host/controller is the only authoritative writer, using existing lock and SafeRoot constraints; migration protocol coordinated on #23.
• Fact lifecycle candidate/active/superseded/retracted/rejected/needs_revalidation (or explicit equivalent), current/historical read semantics, provider/tool/OS/version applicability, Git base/candidate/verified SHA, source issue/run/phase/review round. Provenance is validated against Controller-owned receipts; LLM-reported certainty is not objective verification.
• Correct/reject must survive reconstruction and prevent the same discredited assertion from returning merely because an old transcript/hand-off was replayed. Facts with incompatible candidate SHA or changed applicability carry a stale/recheck verdict, not silently current.
• Every read reports freshness (source_seq, applied_seq, pending, failed, is_current or equivalent) and typed redaction/size budgets; no hot-buffer or memory index may override a current revocation or permission decision.
• Deterministic conflict resolution for applicable singleton facts; no generic rule that newer text automatically supersedes stronger verified evidence; rejected changes retain reason and actor. Unit/property tests cover sequence drift, conflict, corrections, replay, concurrent write, crash and scope isolation.
• Expose a small provider-neutral read-only candidate/context surface consumed by #319; full-text indexing and optional LTSearch are deliberately delegated to #324. Repository-wide approval/promotion lifecycle is delegated to #325 and is not an automatic side effect of Ledger writes.
• No implicit collection of full provider sessions, hidden reasoning, prompt secrets, raw command output or GitHub tokens. Repository content/Agent notes are untrusted and inert, never a direct execution instruction or Controller permission.
• No dependency on LTSearch/Beacon/TenseMem runtime, Docker, remote sandbox or embeddings for the initial Issue Ledger. Existing single-agent execution unchanged.

Evidence acceptance: one stale claim is corrected, reconstructed, and still excluded; same claim for a different valid provider version remains properly scoped; missing verified evidence is never promoted from a proposal to authoritative state.

MemCurrent-derived online memory and consolidation inputs (2026-10-25)

• Make online corrections immediate to the authoritative, candidate-bound Issue Ledger (including REVIEW/FIX feedback); corrections/retractions block retrieval instantly, regardless of delayed FTS/remote indexes or consolidation checkpoints.
• Offer a bounded derived episodic summary from existing verified controller/run events (e.g. decision, attempt, observed failure, verified fix and evidence refs), not a copy of raw session prompts, tool output, hidden reasoning or credentials.
• Provide a typed, read-only incremental source export for #326 with repository/issue/run partition, monotonic source_seq, candidate/base/verified SHA and schema revision, explicit redaction, permission policy and provenance. Identify pending/unverified events distinctly; do not advance on missing evidence.
• Preserve correction/rejection tombstones across backup/rebuild/backfill and resumed Worker handoffs; enforce freshness status and watermark in every launch-bound context projection.
• Crash and replay tests prove no skipped events, duplicate fact activation, stale-fact leaks, or mutation of existing state on single-agent-disabled mode.