@sema-agent/core 5.45.0 → 5.47.0

package/dist/core/memory-engine/engine.d.ts

@@ -1,8 +1,10 @@
 import type { EngineNotice } from "../types.js";
+import { foreignDanglingSessionAccounts, type EffectiveSettlement, type HoldRow } from "./delegation-settlement.js";
+import { type OriginClearanceRow } from "./origin-clearance.js";
 import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
 import { type MemoryExportBundle, type MemoryImportReport } from "./export-bundle.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionMarkOutcome, type SessionPollutionRecord } from "./layout.js";
-import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemorySessionHandle, ScanFinding } from "./types.js";
+import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntryOrigin, MemorySessionHandle, ScanFinding } from "./types.js";
 /**
  * The CC `# Memory` instruction section — VERBATIM from the live capture
  * (bench/cc-parity-toolsuite/reminders/live-capture-main-session-2026-07-08.md §12), with the
@@ -34,6 +36,34 @@ export declare function buildMemoryInstruction(memoryDir: string, instructionFil
  * dual-root instruction merge ("the write plane's instruction wins") never sees a second candidate.
  */
 export declare const MEMORY_RECALL_DISCIPLINE = "Before answering questions about earlier work, decisions, dates, people, or the user's preferences, look them up: `memory_search` finds entries by keyword and `memory_get` reads a full entry \u2014 the injected memory index only lists what exists. When a lookup comes up empty, say that you checked memory and found nothing instead of guessing.";
+/**
+ * design/336 §5.4 — the recall-discipline SEGMENT as the runner composes (and, on a retracted tool
+ * pair, strips) it: the base paragraph, plus — under `provenance: "carry"` only — the
+ * label-semantics sentence ({@link MEMORY_PROVENANCE_RECALL_SENTENCE}: what a `⚠ext` handle row /
+ * external-origin note means, "stays usable, verify before acting"). ONE function on purpose:
+ * prepare-memory appends this exact string and prepare-task's pair-retraction removes this exact
+ * string — two compositions would drift the moment either mode's wording moved. Under "off" this
+ * is byte-identical to {@link MEMORY_RECALL_DISCIPLINE} (the pre-336 segment).
+ */
+export declare function memoryRecallDisciplineSegment(provenance: "off" | "carry"): string;
+/**
+ * design/336 §5.5 (file-face half) — does the entry file at `absPath` carry a committed
+ * external-origin marker? A BOUNDED head read (default 64 KiB — an engine-projected frontmatter
+ * block sits at the head and is orders of magnitude smaller; the per-file store cap is 100 KB) +
+ * the one marker normalization ({@link committedOriginOf}: typed field or extra-form carrier).
+ * Consumed by the runner's Read-tool recall-taint judgment: a model that bypasses `memory_get` and
+ * Reads a marked entry file straight off a zero-copy plane takes up the same content, so the same
+ * derived mark must follow the delivery.
+ *
+ * FAIL-OPEN by design (`false` on any read/parse failure): this is a taint-propagation widening
+ * over a disclosure the file bytes already make themselves (the origin block is IN the file the
+ * model just read), not a gate — a refusal here would break ordinary reads on I/O hiccups. Named
+ * residuals (§5.5's standing bypass-channel class, disclosed): a frontmatter block larger than the
+ * bound reads as unmarked, and a file swapped between the tool's read and this one is judged on
+ * the swapped bytes (either direction; a spurious derived mark is the safe side — marks are
+ * over-approximations by law, and a missed one is exactly the residual Bash reads already carry).
+ */
+export declare function entryFileHeadCarriesOrigin(absPath: string, maxBytes?: number): boolean;
 /**
  * design/180 B-3 — the preference-header discipline paragraph. Same carriage as
  * {@link MEMORY_RECALL_DISCIPLINE}: a runner-appended segment OUTSIDE `inject()`, so the
@@ -89,6 +119,12 @@ export declare const DEFAULT_HARVEST_DEADLINE_MS = 5000;
 /** M7 — default per-harvest processed-file budget (deliberately above the file-count cap, so it is
  *  inert unless configured tighter). */
 export declare const DEFAULT_HARVEST_FILE_BUDGET = 2000;
+/** design/336 §4.2 — the default settlement window: how long a delegation may stay `pending`
+ *  before reconciliation judges it `expired` (holds disposed as unproven — LOUDLY, never silently
+ *  dropped — and the session's unprovable window closes exposed). 72h = a comfortable upper bound
+ *  on background-child lifetimes; the cost of the window is that a held instruction entry is
+ *  delayed at most this long, never lost. */
+export declare const DEFAULT_HOLD_SETTLE_TIMEOUT_MS: number;
 /** design/138 §2.4 删除防线 — the mass-deletion fuse threshold (fraction of materialized writable
  *  entries missing at harvest above which the whole harvest is judged an incident and refused). The
  *  fuse guards the BACKEND from having a wipe written back; renames (same id re-appearing elsewhere)
@@ -114,6 +150,39 @@ export interface MemoryEngineOptions {
     maxFiles?: number;
     /** Max nesting depth under the writable root (default {@link DEFAULT_MAX_ENTRY_DEPTH}). */
     maxDepth?: number;
+    /**
+     * design/336 §13-3 — the memory-provenance master switch (the deployment threads
+     * {@link import("../types.js").RunnerDeps.memoryProvenance} here; engine-direct hosts set it
+     * directly). Two exact spellings:
+     *  - `"carry"` (absent ≡ this; the default) — the 336 posture: an externally-exposed session's
+     *    ORDINARY memory writes commit WITH an engine-minted `origin` marker (tag-admit; the content
+     *    scan gates still run in full — a marker is not an exemption), instruction-form files
+     *    (type: feedback / v2 injection hints) are withheld and quarantined (the narrow `polluted`
+     *    rejection), the derived index's session prose still rolls back to its materialize-time
+     *    baseline, and exposure carries the SAME file-count cap and harvest budget as a clean
+     *    session;
+     *  - `"off"` — the pre-336 behavior: an exposed session's harvest admits nothing (every changed/
+     *    new file quarantines, host-auditable), no origin marker is ever MINTED, and the read side
+     *    mounts no origin decorations. One stated deviation from the byte level: origin-form
+     *    frontmatter written by the model is STILL stripped-with-warning from what commits (the
+     *    origin seat is engine-authored in both modes — preserving model-authored marker bytes under
+     *    "off" would hand a forgeable typed field to the next "carry" period), and an EXISTING
+     *    committed origin still carries forward on edits (the backend's immutability law is
+     *    structural and mode-independent — "off" stops minting, it never strips standing facts).
+     * Any other value refuses loudly at construction (`config.memory_provenance`, #123 — exact
+     * spellings, never truthiness).
+     */
+    provenance?: "off" | "carry";
+    /**
+     * design/336 §4.2 — the delegation settlement window in ms (default
+     * {@link DEFAULT_HOLD_SETTLE_TIMEOUT_MS} = 72h): a `pending` settlement row older than this is
+     * judged `expired` at the next harvest reconciliation — the session's unprovable window closes
+     * exposed, and its instruction holds dispose (announced explicitly as a TIMEOUT, never a
+     * conviction; the `resolveHold` valve can still release them with a `"static"`-cause marker).
+     * A bad value (non-finite, zero, negative, non-number) refuses loudly at construction
+     * (`config.memory_hold_timeout`, #123 — never folded to the default).
+     */
+    holdSettleTimeoutMs?: number;
     /** M7 — harvest deadline in ms (default {@link DEFAULT_HARVEST_DEADLINE_MS}); over-deadline files
      *  are deferred to the next harvest (report.degraded), never dropped. */
     harvestDeadlineMs?: number;
@@ -264,8 +333,13 @@ export interface EntryProvenanceAccount {
  * writing memory files, the harvest quarantined every one of them, and nothing said so while a host
  * could still act on it.
  *
+ * MODE-AWARE MESSAGE (design/336): the wording follows the engine's provenance mode — under
+ * `"carry"` (default) it states the tag-admit semantics (ordinary writes commit with an origin
+ * marker; instruction-form files are withheld); the `"off"`/absent spelling keeps the pre-336 text
+ * byte-identical. The caller passes the mode it constructed the engine with.
+ *
  * SCOPE OF THE CLAIM (adversarial-review round 1, P1 — the first cut PROMISED quarantine on every mark).
- * This notice states the VERDICT, not the mechanism's outcome: "no longer eligible", plus what a harvest
+ * This notice states the VERDICT, not the mechanism's outcome: "no longer eligible" (its "off" form), plus what a harvest
  * does WHEN IT COLLECTS. That distinction is load-bearing, because several real paths reach a polluted
  * harvest that quarantines nothing — a `writeScope`-null layering and a declared-unavailable session
  * both take `harvestCore`'s zero-admission return (nothing is collected, so nothing is captured), and a
@@ -290,6 +364,7 @@ export interface EntryProvenanceAccount {
 export declare function memorySessionPollutedNotice(input: {
     reason: string;
     sessionId?: string;
+    provenance?: "off" | "carry";
 }): EngineNotice;
 /**
  * The polluted harvest's loud half ({@link EngineNotice}): what the containment actually did, minted
@@ -340,7 +415,17 @@ export declare function memoryHarvestQuarantinedNotice(input: {
     escalated: number;
     reason?: string;
     sessionId?: string;
+    provenance?: "off" | "carry";
+    indexRolledBack?: boolean;
 }): EngineNotice;
+/**
+ * design/336 §6.3 — the hold family's operator notices, derived from ONE harvest report's
+ * structured containment signal (`report.containment`), the same runner-minted posture as
+ * `memory.session_polluted`. Factual wording only (§13-2 model-psyche guardrail: no threat
+ * vocabulary — a hold is a sequencing fact, not an accusation); paths are model-controlled
+ * identifiers, neutralized and length-capped before they ride the message or the detail.
+ */
+export declare function memoryHoldNotices(report: HarvestReport, sessionId?: string): EngineNotice[];
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
@@ -352,6 +437,10 @@ export declare class MemoryEngine {
     private readonly maxDepth;
     private readonly harvestDeadlineMs;
     private readonly harvestFileBudget;
+    /** {@link MemoryEngineOptions.holdSettleTimeoutMs} (screened at construction, #123). */
+    private readonly holdSettleTimeoutMs;
+    /** {@link MemoryEngineOptions.provenance} — the design/336 master switch (screened at construction). */
+    private readonly provenance;
     /** {@link MemoryEngineOptions.onIncident} — the advisory disclosure seat (partition + announce codes). */
     private readonly onIncident;
     /** A backend-pinned directory (FileBackend zero-copy detection). */
@@ -368,6 +457,10 @@ export declare class MemoryEngine {
      * failure produces no second-order disclosure — the alternative (announcing the announce failure)
      * would recurse through the very lane that just failed.
      */
+    /** design/336 §3.6 (slice 2) — the session-account incident channel (`memory.session_account_failed`):
+     *  a degraded residue classification is DISCLOSED, never quiet (the behavioral fail-closed half —
+     *  harvest refusing on `handle.sessionAccountFailed` — is enforced at the write boundary). */
+    private discloseSessionAccountIncident;
     private discloseAnnounceFailure;
     /**
      * Record retrieval hits (entries a memory tool actually RETURNED to the model) into this engine's
@@ -394,7 +487,7 @@ export declare class MemoryEngine {
      * markers of one session would both read clean and both announce). Callers that do not disclose
      * ignore it exactly as before.
      */
-    markSessionPolluted(sessionId: string, reason: string): SessionPollutionMarkOutcome;
+    markSessionPolluted(sessionId: string, reason: string, cause?: import("./types.js").MemoryOriginCause): SessionPollutionMarkOutcome;
     /** The session's pollution record (in-process mark first, then the durable marker) — undefined =
      *  clean. Reads are side-effect-free. */
     sessionPollution(sessionId: string): SessionPollutionRecord | undefined;
@@ -584,9 +677,11 @@ export declare class MemoryEngine {
     private settlePromotions;
     materialize(scopes: readonly string[], writeScope: string | null, opts?: {
         adoptionRestricted?: boolean;
+        sessionId?: string;
     }): Promise<MemorySessionHandle>;
     inject(handle: MemorySessionHandle, opts?: {
         writeToolMounted?: boolean;
+        reminderMark?: string;
     }): MemoryInjection;
     /**
      * design/138 S2-C — gate ONE tool write (Write/Edit/NotebookEdit) against the memory domain.
@@ -617,6 +712,7 @@ export declare class MemoryEngine {
     harvest(handle: MemorySessionHandle, opts?: {
         polluted?: {
             reason: string;
+            cause?: import("./types.js").MemoryOriginCause;
         };
         sessionId?: string;
         admitNothing?: {
@@ -624,6 +720,102 @@ export declare class MemoryEngine {
         };
     }): Promise<HarvestReport>;
     private harvestCore;
+    /**
+     * Settle every DUE hold at harvest opening (the reconciliation leg): a hold whose session's
+     * account is all-clean releases (the captured bytes re-walk the FULL gate set — content scan,
+     * size cap, origin strip — and commit under the ORIGINAL session's lineage: the true writer is
+     * who the retroaction machinery must find); a dirty/unprovable account disposes to quarantine
+     * (host-auditable, LOUD — a timeout is announced as a timeout, never as a conviction); the host
+     * valve's standing verdicts execute here. A hold whose settlements are still pending stays held.
+     * Throws only on a corrupt hold/settlement ledger — the caller's fail-closed reconciliation arm
+     * refuses the harvest (integrity unknown must not read as "no holds").
+     */
+    private settleDueHolds;
+    /**
+     * The release leg: re-walk the captured bytes through the FULL gate set and commit them under
+     * the ORIGINAL writer session's lineage. Returns the released relPath, or undefined when the
+     * hold did not release (disposed on a gate refusal / CAS conflict / lost capture, or kept held
+     * on a transient backend refusal — retried next harvest, never silently dropped).
+     */
+    private releaseHold;
+    /** §3.3 — the settlement valve: an audited host ruling over one delegation's outcome. `"clean"`
+     *  releases the post-expiry gates (effective only — the history bit never flips, and a LATER
+     *  observed `external` overrides the ruling); `"external"` convicts. Advisory trust plane. */
+    resolveSettlement(settleId: string, to: "clean" | "external", requestId: string): void;
+    /** §4.2③ — the hold valve: `"release"` commits the held entry at the next harvest WITH a
+     *  `"static"`-cause marker (a valve release is not a cleanliness proof); `"discard"` disposes it
+     *  to quarantine. Audited (requestId required). */
+    resolveHold(holdId: string, action: "release" | "discard", requestId: string): void;
+    /** §3.6 — the session-account valve: close a dangling foreign row WITHOUT adjudication (the
+     *  residue arm keeps firing until the next full-domain harvest closes normally — a valve close
+     *  must not launder the window it covers). Audited (requestId required). */
+    resolveSessionAccount(sessionId: string, requestId: string): void;
+    /** The engine's control-plane directory (the sidecar home: pollution markers, lineage/challenge
+     *  ledgers, and the design/336 settlement/hold/session accounts). Exposed so a host (and the
+     *  runner's settlement handle) can address the SAME plane the engine writes — a second derivation
+     *  would be a drift seam. */
+    get controlPlaneDir(): string;
+    /** Read face: every delegation settlement row with its folded effective status (host audit). */
+    readDelegationSettlements(): EffectiveSettlement[];
+    /** Read face: every instruction-hold row (host audit; custody bytes are addressable through
+     *  `captureName`/`disposition.quarantineName` under the control plane). */
+    readInstructionHolds(): HoldRow[];
+    /** Read face: the dangling foreign session-account rows a given session would classify residue
+     *  against (host audit for the §3.6 valve). */
+    readDanglingSessionAccounts(selfSessionId: string): ReturnType<typeof foreignDanglingSessionAccounts>;
+    /** The committed, side-effect-free audit read: the adoption-restricted committed view when the
+     *  backend offers one (zero-copy File — ledger+shadow, no disk adoption), else the non-adopting
+     *  retrieval view (copy-out File), else the backend itself (Pg/TiDB shapes — naturally committed
+     *  and side-effect-free per the getByIds contract clause). */
+    private committedAuditFace;
+    private static originClearRefusal;
+    /**
+     * §13-4① — the VIEW face: every marked entry in the given scopes, each with its marker (what /
+     * cause / when) and its assembled provenance account (来源委派: the lineage contributors joined
+     * with their sessions' pollution records — `provenanceOf`'s answer, one authority, never a
+     * second store). Committed state only; a marked entry that is also challenged still lists here
+     * (the exclusion rides inside the provenance account) — the host must SEE it to adjudicate it.
+     *
+     * Enumeration trusts the backend's `MemoryEntryHeader.exposure` clause (§6.2): a third-party
+     * backend that violates it UNDER-REPORTS here — the conformance suite is the acceptance
+     * contract (its exposure-carriage case reds on exactly that backend), and the B3 upgrade-order
+     * duty covers mixed fleets; the engine deliberately does not re-fetch whole scopes to
+     * second-guess a header face it published a contract for.
+     */
+    listExternalOriginEntries(scopes: readonly string[]): Promise<Array<{
+        id: string;
+        slug: string;
+        scope: string;
+        origin: MemoryEntryOrigin;
+        provenance: EntryProvenanceAccount;
+    }>>;
+    /** §13-4② read half — the clearance audit trail (pending rows are crash-recovery seats: their
+     *  custody carries the cleared bytes; a later {@link clearEntryOrigin} call resumes them). */
+    listOriginClearances(): OriginClearanceRow[];
+    /**
+     * §13-4② — the audited UN-MARK valve. There is deliberately NO in-place strip spelling anywhere
+     * (the backend immutability law stands untouched); the clear rides the law's own single legal
+     * exit (§2.3-2): write-ahead clearance row (custody = the full cleared-entry text) → COMMITTED
+     * tombstone (CAS on the judged rev) → later-batch re-record of the SAME id with the marker
+     * stripped (the host's explicit vouching starts the entry's unmarked life; same id on purpose —
+     * links, usage accounts and the clearance join keep their key). Terminals are appended events
+     * (who/when/why stay queryable beside the entry); every failure leaves the custody row standing
+     * and a re-call RESUMES it idempotently. Refusals (#123 coded, caller-shape):
+     * unattributed/invalid input, unknown/unmarked entry, and a CHALLENGED entry — the clear valve
+     * is not a challenge exit (adjudicate the challenge first; clearing a challenged entry would
+     * launder the exclusion through the weaker credential).
+     */
+    clearEntryOrigin(entryId: string, input: {
+        requestId: string;
+        reason: string;
+    }): Promise<{
+        entryId: string;
+        clearanceId: string;
+        origin: MemoryEntryOrigin;
+        landedSlug: string;
+    }>;
+    /** The clear's effect half — replayable from the row alone (the resume arm re-enters here). */
+    private completeOriginClearance;
     /**
      * @param keepBaseline RB-440 (2026-07-31, hardening probe P3) — relative paths whose baseline must NOT
      * advance: the files a DEGRADED harvest deferred (`report.degraded.pending`).
@@ -652,6 +844,19 @@ export declare class MemoryEngine {
      *  the deleted disk file WAS the backend's storage). Zero-copy skips getByIds: its read-side scan
      *  cannot see a deleted file, and calling it mid-harvest would sync-adopt in-session edits. */
     private committedContentFor;
+    /**
+     * design/336 §2.2 (r4-9) — the COMMITTED frontmatter an origin carry-forward is computed against.
+     * Deliberately NOT {@link committedContentFor}'s non-zero-copy leg: that one calls the backend's
+     * plain `getByIds`, and the File backend's plain read path ADOPTS out-of-band disk changes (a
+     * read-side sync that advances revs and books retrievals) — a carry-forward read must be
+     * side-effect-free, or assembling one harvest mutates the store it is reading. Reading order:
+     *  - zero-copy File: the control-plane shadow IS the committed state (the disk file is the
+     *    session's own working copy — exactly what must NOT serve as the committed baseline);
+     *  - copy-out with a `retrievalView` face (File): the lock-free non-adopting view;
+     *  - twins (Pg/TiDB shapes): plain `getByIds` — naturally committed-state and side-effect-free
+     *    (the contract clause on {@link MemoryBackend.getByIds}).
+     */
+    private committedFrontmatterFor;
     /** L4/C-F9 (S2-0) — capture a gate-rejected file into control-plane quarantine FROM THE SCANNED
      *  CONTENT (never re-reading the path: the disk bytes may have been swapped since the scan —
      *  TOCTOU), then remove the suspect from the model-visible plane (delete, falling back to clearing
@@ -712,6 +917,6 @@ export declare class MemoryEngine {
 }
 /** Render drained announcements as ONE engine-owned system-reminder block (the lead/frame is
  *  trusted; item identifiers were neutralized at enqueue — see {@link MemoryAnnouncement.items}). */
-export declare function renderAnnouncements(queue: readonly MemoryAnnouncement[], folded: number): string;
+export declare function renderAnnouncements(queue: readonly MemoryAnnouncement[], folded: number, reminderMark?: string): string;
 /** Truncate the derived index to the CC injection parameters (200 lines / 25KB). */
 export declare function truncateIndex(text: string): string;