@sema-agent/core 5.46.0 → 5.48.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)
@@ -137,6 +173,16 @@ export interface MemoryEngineOptions {
      * 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;
@@ -370,7 +416,16 @@ export declare function memoryHarvestQuarantinedNotice(input: {
     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;
@@ -382,6 +437,8 @@ 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). */
@@ -400,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
@@ -616,6 +677,7 @@ 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;
@@ -658,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`).