@sema-ai/core 1.275.1

package/dist/core/context-guard.js

@@ -0,0 +1,171 @@
+import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
+import { isToolResult, messageRole } from "./message-utils.js";
+/** Fraction of the model's effective window the guard tries to stay under. */
+const GUARD_FRACTION = 0.85;
+function isSummary(m) {
+    // "branchSummary" was a second summary role until the design/71 清尾 pass removed the whole
+    // (never-produced) branch-summary chain; compaction summaries are the only summary role left.
+    return messageRole(m) === "compactionSummary";
+}
+/**
+ * Last-resort, in-task context trim. Proper compaction (LLM summary) runs *between* tasks;
+ * this prevents a single task whose internal tool-loop balloons from overflowing the window.
+ *
+ * Keeps all summary messages (compaction/branch) and the most recent messages that fit the
+ * budget, dropping older regular messages at a safe boundary (never starting on an orphan
+ * toolResult). Returns the original array when already within budget.
+ *
+ * design/123 D3 (codex-B1 = fable-M5) — anchored accounting: when `anchoredTotalTokens`
+ * (= `estimateContextTokens(messages, charsPerToken).tokens` for the SAME array) is provided, the
+ * trigger gate and the internal bookkeeping start from the usage-anchored value instead of the
+ * structural sum (which underestimates code/CJK and lets over-window requests through). Dropping a
+ * message AFTER the usage anchor reduces the accounted total by its structural estimate; dropping a
+ * message AT/BEFORE the anchor reduces it by ZERO (the anchor usage was billed with that content —
+ * a request-view drop only pays off on the NEXT request), so the trim keeps cutting deeper until
+ * the anchored total meets the budget or only the minimal tail is left. Absent ⇒ legacy structural
+ * behavior, byte-identical. `charsPerToken` (design/123 D2): structural coefficient, default 4.
+ */
+export function trimToBudget(messages, budgetTokens, anchoredTotalTokens, charsPerToken) {
+    const cpt = charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    const anchored = anchoredTotalTokens !== undefined;
+    let structuralTotal = 0;
+    for (const m of messages) {
+        structuralTotal += estimateTokens(m, cpt);
+    }
+    const total = anchored ? anchoredTotalTokens : structuralTotal;
+    if (total <= budgetTokens || messages.length <= 1) {
+        return messages;
+    }
+    // The usage-anchor position (anchored mode only): drops at/before it reduce the accounting by 0.
+    const anchorIdx = anchored ? (estimateContextTokens(messages, cpt).lastUsageIndex ?? -1) : -1;
+    // Always-kept summary messages and their budget.
+    const summaries = messages.filter(isSummary);
+    let summaryTokens = 0;
+    for (const s of summaries) {
+        summaryTokens += estimateTokens(s, cpt);
+    }
+    // Per-message REDUCTION value in the active coordinate: structural for post-anchor messages,
+    // 0 for at/before-anchor messages (legacy mode: anchorIdx = -1 ⇒ all structural, and the tail
+    // budget below reduces to the historical `budget - summaryTokens`).
+    const nonSummary = [];
+    const reductions = [];
+    let reductionSum = 0;
+    for (let i = 0; i < messages.length; i++) {
+        if (isSummary(messages[i]))
+            continue;
+        nonSummary.push(messages[i]);
+        const r = i > anchorIdx ? estimateTokens(messages[i], cpt) : 0;
+        reductions.push(r);
+        reductionSum += r;
+    }
+    const requiredReduction = total - budgetTokens; // > 0 here
+    let start;
+    if (anchored && reductionSum <= requiredReduction) {
+        // Even dropping every droppable message cannot bring the anchored total under budget (the whole
+        // droppable prefix sits at/before the anchor). Deep-trim to the minimal tail — "keep cleaning
+        // until the target is met or nothing clearable remains" (design/123 D3); the next request's
+        // fresh usage re-anchors at the real (small) size. If this floor lands on a toolResult, the
+        // SHARED turn-alignment below extends it backward to the owning tool-call assistant.
+        start = nonSummary.length - 1;
+    }
+    else {
+        // Walk the non-summary messages from the end, keeping the maximal tail whose dropped-prefix
+        // reduction still meets the requirement. In the legacy coordinate `reductionSum - requiredReduction`
+        // equals the historical `budgetTokens - summaryTokens` tail budget exactly.
+        const tailBudget = Math.max(0, reductionSum - requiredReduction);
+        let acc = 0;
+        start = nonSummary.length;
+        for (let i = nonSummary.length - 1; i >= 0; i--) {
+            acc += reductions[i];
+            if (acc > tailBudget && i + 1 < nonSummary.length) {
+                start = i + 1;
+                break;
+            }
+            start = i;
+        }
+    }
+    // Never begin the kept window on an orphan toolResult (a result whose call was dropped): first
+    // prefer dropping the leading orphans forward (budget-friendly, the legacy guard).
+    while (start < nonSummary.length && isToolResult(nonSummary[start])) {
+        start++;
+    }
+    if (start >= nonSummary.length) {
+        // The ENTIRE tail from the chosen start is toolResults — the design/123 D3 live-caught 400 path
+        // ("Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"):
+        // requests built right after tool execution END in a toolResult batch, so both the anchored
+        // deep-trim floor and the walk branch routinely land inside that trailing batch, and the OLD
+        // fallback here kept a single ORPHAN toolResult (its tool-call assistant dropped — API-invalid
+        // on strict gateways; "tolerated" only because pre-anchored coordinates rarely reached it).
+        // TURN-ALIGN instead: extend BACKWARD over the trailing toolResult batch to include the
+        // assistant that issued the tool_calls, keeping one COMPLETE turn tail (may overshoot the
+        // budget — validity beats budget, same tradeoff as the findCutPoint A-2 oversized-batch
+        // fallback; this also resolves the codex-review MINOR on single-message floor granularity).
+        // Only when NO owning assistant exists at all (the whole array is toolResults) keep the last
+        // message — the prepare-task belt drops such an orphan before the provider ever sees it.
+        start = nonSummary.length - 1;
+        while (start > 0 && isToolResult(nonSummary[start])) {
+            start--;
+        }
+        if (isToolResult(nonSummary[start])) {
+            start = nonSummary.length - 1;
+        }
+    }
+    const keptTail = new Set(nonSummary.slice(start));
+    // Rebuild from the ORIGINAL array so chronology holds even if a summary sits *after* a kept message
+    // (don't assume every summary precedes the tail — a branch/compaction summary can be interleaved).
+    return messages.filter((m) => isSummary(m) || keptTail.has(m));
+}
+/**
+ * design/123 D3 belt (invariant-level, live-caught 16k 400s): the FINAL request view must never
+ * contain a toolResult whose tool-call assistant is absent — strict gateways hard-400 on it
+ * ("Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"). Every
+ * individual producer is turn-aligned (findCutPoint never cuts on a toolResult; trimToBudget
+ * turn-aligns its floor), but NO pipeline combination may ship an orphan, so the prepare-task
+ * context hook sweeps its output through this last. Deterministic ⇒ byte-stable per request ⇒
+ * prefix-cache safe. Returns the SAME array when clean (zero-cost fast path); `dropped` carries a
+ * diagnostic per removed orphan (toolCallId + neighbor roles) for onError attribution.
+ */
+export function dropOrphanToolResults(messages) {
+    const seenCallIds = new Set();
+    let orphanAt = -1;
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        if (m.role === "assistant" && Array.isArray(m.content)) {
+            for (const c of m.content) {
+                if (c?.type === "toolCall" && typeof c.id === "string")
+                    seenCallIds.add(c.id);
+            }
+        }
+        else if (m.role === "toolResult" && !seenCallIds.has(m.toolCallId ?? "")) {
+            orphanAt = i;
+            break;
+        }
+    }
+    if (orphanAt === -1) {
+        return { messages, dropped: [] }; // clean — the common case, same array back
+    }
+    const dropped = [];
+    const out = messages.slice(0, orphanAt);
+    const roleOf = (i) => i < 0 || i >= messages.length ? "(none)" : (messages[i].role ?? "(unknown)");
+    for (let i = orphanAt; i < messages.length; i++) {
+        const m = messages[i];
+        if (m.role === "assistant" && Array.isArray(m.content)) {
+            for (const c of m.content) {
+                if (c?.type === "toolCall" && typeof c.id === "string")
+                    seenCallIds.add(c.id); // keep accumulating past the first orphan
+            }
+        }
+        else if (m.role === "toolResult" && !seenCallIds.has(m.toolCallId ?? "")) {
+            dropped.push({ toolCallId: m.toolCallId ?? "(missing)", index: i, prevRole: roleOf(i - 1), nextRole: roleOf(i + 1) });
+            continue;
+        }
+        out.push(messages[i]);
+    }
+    return { messages: out, dropped };
+}
+/** Budget the in-task guard targets for a model. */
+export function guardBudget(model) {
+    const window = model.contextTokens ?? model.contextWindow;
+    return Math.floor(window * GUARD_FRACTION);
+}
+//# sourceMappingURL=context-guard.js.map

package/dist/core/context-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-guard.js","sourceRoot":"","sources":["../../src/core/context-guard.ts"],"names":[],"mappings":"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"}

package/dist/core/dynamic-recall.d.ts

@@ -0,0 +1,100 @@
+import type { AgentMessage } from "../internal/harness.js";
+import { type MemorySelector, encodeSurfacedKey } from "./memory-recall.js";
+import type { MemoryStore } from "./memory.js";
+/**
+ * design/86 §3 缺口 A — DYNAMIC memory re-recall seam (CC `processSessionStartHooks('compact')` parity).
+ *
+ * PROBLEM (design/86 §3): our memory is a one-shot snapshot taken at task start (`prepareTask` →
+ * `selectAndComposeMemory`/`Layered`, injected into the STABLE system prefix). A long task that runs many
+ * turns and compacts loses the *fine detail* of its early turns; we never re-select more-relevant memory for
+ * the conversation as it has evolved. CC re-evaluates relevant memories after every compaction.
+ *
+ * THIS SEAM (default OFF, data-gated like Seam C): after a REAL within-task compaction, re-run the EXISTING
+ * selector + `selectAndComposeMemory`/`Layered` against the CURRENT conversation context (recent messages),
+ * de-dup against everything already surfaced (`priorSurfacedIds`/`priorSurfacedKeys`, the same machinery the
+ * initial recall uses), and inject any NEW relevant notes as a TAIL ATTACHMENT user message — NEVER touching
+ * the stable system prefix (touching the prefix would break the 90–98% prefix-cache the whole stable-prefix
+ * design rests on).
+ *
+ * Security (design/86 §3 ⑤): the bodies re-recalled here come back through the SAME read API
+ * (`listStructuredNotes`/`getByIds`) and the SAME compose path (`selectAndComposeMemory`/`Layered`, which wrap
+ * in `RECALL_CAVEAT` + `<user_memory mode="selective">`) the INITIAL recall uses. Every note in the store has
+ * already passed the WRITE-side secret gate (`guardedMemoryStore` → `enforceStructuredNoteSecretGate`); this
+ * path adds NO new write inlet and NO new read inlet — it reuses the audited initial-recall pipeline verbatim,
+ * so it cannot surface anything the initial recall couldn't, and it cannot leak a secret the write gate
+ * already rejected. The de-dup also guarantees an already-shown body is never re-injected.
+ */
+/** Trust-injected configuration for the dynamic re-recall seam (lives on `RunnerDeps`, never `TaskSpec` —
+ *  it is part of the `memoryRecall` function-seam family, off by default). *
+ * @deprecated design/138 S4 — the dynamic re-recall seam served ONLY the retired legacy memoryStore
+ * injection path; prepareTask never wires it anymore (the runtask hook is dead-by-input). Removal is the
+ * next major.
+ */
+export interface DynamicRecallConfig {
+    /** Master switch. Absent/false ⇒ no dynamic re-recall (byte-identical to current behavior). */
+    enabled?: boolean;
+    /** How many of the most-recent conversation messages form the re-recall query context. Default 6. */
+    recentMessageWindow?: number;
+    /** Max chars of recent-message text fed to the selector as the query objective. Default 4000. */
+    maxQueryChars?: number;
+}
+export declare const DEFAULT_RECENT_MESSAGE_WINDOW = 6;
+export declare const DEFAULT_MAX_QUERY_CHARS = 4000;
+/**
+ * Build the re-recall QUERY string from the recent conversation messages. Pure + deterministic. Takes the
+ * last `window` messages, extracts their text, and joins/caps to `maxChars` (keeping the TAIL — the most
+ * recent text — when over the cap, since the latest turns are the most relevant query signal). Returns ""
+ * when there is no usable text (caller then skips re-recall: nothing to query on).
+ */
+export declare function buildRecallQuery(messages: readonly AgentMessage[], window?: number, maxChars?: number): string;
+/** What a single dynamic re-recall attempt produced. `block` present ⇒ the caller injects it as a tail
+ *  user message; `surfaced*` are the NEW ids/keys to fold into the run's durable surfaced set. A no-new /
+ *  degrade / disabled outcome yields `block: undefined` and empty surfaced sets (caller injects nothing). */
+export interface DynamicRecallOutcome {
+    block: string | undefined;
+    /** Single-scope: note ids whose bodies were newly injected this attempt. */
+    surfacedIds: readonly string[];
+    /** Multi-scope (layered): `(scope,id)` composite keys whose bodies were newly injected this attempt. */
+    surfacedKeys: readonly string[];
+}
+/** Inputs the Runner threads into one dynamic re-recall attempt. Mirrors the initial-recall call sites in
+ *  `prepare-task.ts` (single-scope vs layered), so the two paths share the exact same selector pipeline. */
+export interface DynamicRecallInput {
+    store: MemoryStore;
+    /** The scope list (1 ⇒ single-scope path; >1 ⇒ layered path). Same `scopes` as the initial recall. */
+    scopes: readonly string[];
+    selector: MemorySelector;
+    /** Query objective derived from the CURRENT conversation (see {@link buildRecallQuery}). */
+    query: string;
+    recentTools?: string[];
+    maxSelected?: number;
+    maxLinked?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    nowMs?: number;
+    /** Single-scope durable de-dup: note ids already surfaced (initial recall + prior re-recalls). */
+    priorSurfacedIds?: ReadonlySet<string>;
+    /** Multi-scope durable de-dup: `(scope,id)` keys already surfaced. */
+    priorSurfacedKeys?: ReadonlySet<string>;
+}
+/**
+ * Run ONE dynamic re-recall against the current conversation. Reuses `selectAndComposeMemory` (single-scope)
+ * or `selectAndComposeLayeredMemory` (multi-scope) — the SAME functions the initial recall uses — so the
+ * dedup, the manifest, the fence, the caveat, and the degrade/no-new branches are all identical.
+ *
+ * Crucially, on a DEGRADE the dynamic seam injects NOTHING (returns `block: undefined`). This differs from
+ * the INITIAL recall, which degrades to inject-all: at task start, degrade-to-inject-all is the safe floor
+ * (never start a task with NO memory). MID-TASK, the stable prefix ALREADY holds the initial inject — so a
+ * degrade here means "couldn't pick anything NEW relevant", and re-dumping the whole scope as a tail
+ * attachment would (a) duplicate the prefix's memory and (b) explode the tail / break the cache. So the
+ * dynamic seam treats degrade exactly like no-new: inject nothing, surface nothing. (This is the security-
+ * and cost-correct choice: the seam can only ADD relevant tail notes, never re-dump or fail open.)
+ *
+ * @deprecated design/138 S4 — the dynamic re-recall seam served ONLY the retired legacy memoryStore
+ * injection path; prepareTask never wires it anymore (the runtask hook is dead-by-input). Removal is the
+ * next major.
+ */
+export declare function runDynamicRecall(input: DynamicRecallInput): Promise<DynamicRecallOutcome>;
+/** Re-export so the wiring + tests have one import site for the composite key encoder. */
+export { encodeSurfacedKey };
+//# sourceMappingURL=dynamic-recall.d.ts.map

package/dist/core/dynamic-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-recall.d.ts","sourceRoot":"","sources":["../../src/core/dynamic-recall.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAEL,KAAK,cAAc,EAEnB,iBAAiB,EAGlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qGAAqG;IACrG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,MAAM,GAAE,MAAsC,EAC9C,QAAQ,GAAE,MAAgC,GACzC,MAAM,CAYR;AAgBD;;6GAE6G;AAC7G,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,wGAAwG;IACxG,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAID;4GAC4G;AAC5G,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,sGAAsG;IACtG,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA2C/F;AAED,0FAA0F;AAC1F,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/core/dynamic-recall.js

@@ -0,0 +1,108 @@
+import { encodeSurfacedKey, selectAndComposeLayeredMemory, selectAndComposeMemory, } from "./memory-recall.js";
+export const DEFAULT_RECENT_MESSAGE_WINDOW = 6;
+export const DEFAULT_MAX_QUERY_CHARS = 4_000;
+/**
+ * Build the re-recall QUERY string from the recent conversation messages. Pure + deterministic. Takes the
+ * last `window` messages, extracts their text, and joins/caps to `maxChars` (keeping the TAIL — the most
+ * recent text — when over the cap, since the latest turns are the most relevant query signal). Returns ""
+ * when there is no usable text (caller then skips re-recall: nothing to query on).
+ */
+export function buildRecallQuery(messages, window = DEFAULT_RECENT_MESSAGE_WINDOW, maxChars = DEFAULT_MAX_QUERY_CHARS) {
+    if (window <= 0 || maxChars <= 0)
+        return "";
+    const recent = messages.slice(-window);
+    const parts = [];
+    for (const m of recent) {
+        const text = messageText(m);
+        if (text)
+            parts.push(text);
+    }
+    const joined = parts.join("\n").trim();
+    if (joined.length <= maxChars)
+        return joined;
+    // Over cap: keep the TAIL (latest text is the strongest query signal), not the head.
+    return joined.slice(joined.length - maxChars);
+}
+/** Extract a flat text view of a message's content (assistant/user/tool). Pure. */
+function messageText(m) {
+    const content = m.content;
+    if (typeof content === "string")
+        return content.trim();
+    if (Array.isArray(content)) {
+        const out = [];
+        for (const c of content) {
+            if (typeof c.text === "string" && c.text.length > 0)
+                out.push(c.text);
+        }
+        return out.join(" ").trim();
+    }
+    return "";
+}
+const EMPTY_OUTCOME = { block: undefined, surfacedIds: [], surfacedKeys: [] };
+/**
+ * Run ONE dynamic re-recall against the current conversation. Reuses `selectAndComposeMemory` (single-scope)
+ * or `selectAndComposeLayeredMemory` (multi-scope) — the SAME functions the initial recall uses — so the
+ * dedup, the manifest, the fence, the caveat, and the degrade/no-new branches are all identical.
+ *
+ * Crucially, on a DEGRADE the dynamic seam injects NOTHING (returns `block: undefined`). This differs from
+ * the INITIAL recall, which degrades to inject-all: at task start, degrade-to-inject-all is the safe floor
+ * (never start a task with NO memory). MID-TASK, the stable prefix ALREADY holds the initial inject — so a
+ * degrade here means "couldn't pick anything NEW relevant", and re-dumping the whole scope as a tail
+ * attachment would (a) duplicate the prefix's memory and (b) explode the tail / break the cache. So the
+ * dynamic seam treats degrade exactly like no-new: inject nothing, surface nothing. (This is the security-
+ * and cost-correct choice: the seam can only ADD relevant tail notes, never re-dump or fail open.)
+ *
+ * @deprecated design/138 S4 — the dynamic re-recall seam served ONLY the retired legacy memoryStore
+ * injection path; prepareTask never wires it anymore (the runtask hook is dead-by-input). Removal is the
+ * next major.
+ */
+export async function runDynamicRecall(input) {
+    if (input.scopes.length === 0 || input.query.trim().length === 0)
+        return EMPTY_OUTCOME;
+    if (input.scopes.length === 1) {
+        const res = await selectAndComposeMemory({
+            store: input.store,
+            scope: input.scopes[0],
+            objective: input.query,
+            selector: input.selector,
+            recentTools: input.recentTools,
+            maxSelected: input.maxSelected,
+            maxLinked: input.maxLinked,
+            timeoutMs: input.timeoutMs,
+            signal: input.signal,
+            nowMs: input.nowMs,
+            priorSurfacedIds: input.priorSurfacedIds,
+        });
+        // degrade ⇒ inject nothing (see doc above). no-new (`block: undefined`) ⇒ inject nothing. block ⇒ inject.
+        // EMPTY-SELECTION guard (mid-task specific): when the selector picks ZERO ids, selectAndComposeMemory still
+        // returns a `block` — a manifest with "(no notes selected)". At task START that block is the worth-injecting
+        // manifest affordance; MID-TASK as a TAIL attachment it carries NO new bodies and just bloats the tail /
+        // re-shows the manifest, so treat surfaced-nothing as no-new and inject nothing.
+        if ("degrade" in res)
+            return EMPTY_OUTCOME;
+        if (res.block === undefined || res.surfacedIds.length === 0)
+            return EMPTY_OUTCOME;
+        return { block: res.block, surfacedIds: res.surfacedIds, surfacedKeys: [] };
+    }
+    const res = await selectAndComposeLayeredMemory({
+        store: input.store,
+        scopes: [...input.scopes],
+        objective: input.query,
+        selector: input.selector,
+        recentTools: input.recentTools,
+        maxSelected: input.maxSelected,
+        maxLinked: input.maxLinked,
+        timeoutMs: input.timeoutMs,
+        signal: input.signal,
+        nowMs: input.nowMs,
+        priorSurfacedKeys: input.priorSurfacedKeys,
+    });
+    if ("degrade" in res)
+        return EMPTY_OUTCOME;
+    if (res.block === undefined || res.surfacedKeys.length === 0)
+        return EMPTY_OUTCOME; // empty-selection guard (see above)
+    return { block: res.block, surfacedIds: [], surfacedKeys: res.surfacedKeys };
+}
+/** Re-export so the wiring + tests have one import site for the composite key encoder. */
+export { encodeSurfacedKey };
+//# sourceMappingURL=dynamic-recall.js.map

package/dist/core/dynamic-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-recall.js","sourceRoot":"","sources":["../../src/core/dynamic-recall.ts"],"names":[],"mappings":"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"}

package/dist/core/exec-gate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * L2 mechanical verification gate (design/54) — the "verifiable outputs" exit oracle.
+ *
+ * Runs a TRUSTED, spec-derived suite of commands (build / type-check / test) in an {@link ExecutionEnv}
+ * and gates on the **real exit codes**: pass = every step exited 0. This is the mechanical half of
+ * verifiable outputs (design/54 §2); the de-correlated LLM-judge half is {@link runWithVerification}
+ * (L3). It catches what tests cover; service[33] measured L2 alone misses 50-100% of semantic/edge
+ * defects, which is why L3 runs on what passes L2.
+ *
+ * **It is a thin exit oracle, not a framework** — no model, no Runner, no agents dependency. It just runs
+ * commands and reports their exit truthfully, choosing the streaming `execStream` on a remote env (long
+ * builds, read-timeout, output cap) or the buffered `exec` on a base env. Which commands to run, and how
+ * to compose L2 with L3 / per-module sub-gates, is the caller's (profile's) job (design/54 §4).
+ *
+ * 🔴 SECURITY (design/53 §2.B, threat BUG8 — "L2 can be gamed"): `steps` MUST be a trusted, spec-derived
+ * suite — NOT test files an **untrusted worker** authored (a worker can write `assert(true)` / happy-path
+ * tests that pass while the code is broken, pushing all pressure onto an uncalibrated L3). This helper does
+ * not and cannot know which commands are trustworthy; the caller owns that. The gate's guarantee is narrow:
+ * "did these exact commands all exit 0 in this env" — nothing about whether the commands are meaningful,
+ * whether the env is isolated (design/53 §E = deployment), or the semantics of the change (that is L3).
+ */
+import type { ExecutionEnv } from "../internal/harness.js";
+/** One command in an L2 suite. */
+export interface ExecStep {
+    /** Shell command to run (e.g. `"npm test"`, `"tsc --noEmit"`, `"git diff"`). */
+    command: string;
+    /** Human label for reporting. Default: the command string. */
+    label?: string;
+    /** Working directory; relative paths resolve against the env root. Default: the env's cwd. */
+    cwd?: string;
+    /** Extra environment variables for this command. */
+    env?: Record<string, string>;
+    /** Per-step timeout (seconds). Default: none. */
+    timeoutSec?: number;
+}
+/** The outcome of a single {@link ExecStep}. */
+export interface ExecStepResult {
+    label: string;
+    command: string;
+    /** The real exit code, or `null` when the command never produced one (transport error / timeout / abort). */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** `exitCode === 0`. A `null` exit is **never** `ok` (we can't confirm success, so we don't pass it). */
+    ok: boolean;
+    /** Set when the step failed to RUN (an `ExecutionError`/`RemoteExecutionError` code) — distinct from a non-zero exit. */
+    errorCode?: string;
+    /** True when captured output was truncated at {@link ExecGateOptions.maxOutputBytes}. */
+    truncated?: boolean;
+}
+/** The L2 verdict over a whole suite. */
+export interface ExecGateResult {
+    /** True iff there was ≥1 step AND every step ran and exited 0. An EMPTY suite is `false` (nothing was verified — not a vacuous pass). */
+    passed: boolean;
+    /** Per-step detail, in order. With `stopOnFailure` (default), steps after the first failure are absent. */
+    steps: ExecStepResult[];
+}
+/** Options for {@link runExecGate}. */
+export interface ExecGateOptions {
+    /** Stop at the first failed/non-zero step (default `true` — a cheap CI-style short-circuit). */
+    stopOnFailure?: boolean;
+    /** Cap captured output **per step** in UTF-8 bytes (default 64 KiB) so a `find /` can't flood memory. */
+    maxOutputBytes?: number;
+    /** Idle read timeout (ms) for the streaming (remote) path; ignored on the buffered path. */
+    readTimeoutMs?: number;
+    /** Abort the whole gate (also forwarded to each command). */
+    signal?: AbortSignal;
+}
+/**
+ * Run an L2 mechanical gate: execute `steps` in `env` and gate on real exit codes. See the file header for
+ * the security contract — `steps` must be a trusted, spec-derived suite, not worker-authored tests.
+ */
+export declare function runExecGate(env: ExecutionEnv, steps: ExecStep[], options?: ExecGateOptions): Promise<ExecGateResult>;
+//# sourceMappingURL=exec-gate.d.ts.map

package/dist/core/exec-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-gate.d.ts","sourceRoot":"","sources":["../../src/core/exec-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,EAAE,EAAE,OAAO,CAAC;IACZ,yHAAyH;IACzH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,yIAAyI;IACzI,MAAM,EAAE,OAAO,CAAC;IAChB,2GAA2G;IAC3G,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yGAAyG;IACzG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA2GD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/core/exec-gate.js

@@ -0,0 +1,143 @@
+/**
+ * L2 mechanical verification gate (design/54) — the "verifiable outputs" exit oracle.
+ *
+ * Runs a TRUSTED, spec-derived suite of commands (build / type-check / test) in an {@link ExecutionEnv}
+ * and gates on the **real exit codes**: pass = every step exited 0. This is the mechanical half of
+ * verifiable outputs (design/54 §2); the de-correlated LLM-judge half is {@link runWithVerification}
+ * (L3). It catches what tests cover; service[33] measured L2 alone misses 50-100% of semantic/edge
+ * defects, which is why L3 runs on what passes L2.
+ *
+ * **It is a thin exit oracle, not a framework** — no model, no Runner, no agents dependency. It just runs
+ * commands and reports their exit truthfully, choosing the streaming `execStream` on a remote env (long
+ * builds, read-timeout, output cap) or the buffered `exec` on a base env. Which commands to run, and how
+ * to compose L2 with L3 / per-module sub-gates, is the caller's (profile's) job (design/54 §4).
+ *
+ * 🔴 SECURITY (design/53 §2.B, threat BUG8 — "L2 can be gamed"): `steps` MUST be a trusted, spec-derived
+ * suite — NOT test files an **untrusted worker** authored (a worker can write `assert(true)` / happy-path
+ * tests that pass while the code is broken, pushing all pressure onto an uncalibrated L3). This helper does
+ * not and cannot know which commands are trustworthy; the caller owns that. The gate's guarantee is narrow:
+ * "did these exact commands all exit 0 in this env" — nothing about whether the commands are meaningful,
+ * whether the env is isolated (design/53 §E = deployment), or the semantics of the change (that is L3).
+ */
+import { isRemoteExecutionEnv, RemoteExecutionError } from "./remote-env.js";
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+/**
+ * Truncate a string to at most `maxBytes` UTF-8 bytes WITHOUT splitting a multi-byte char (including
+ * supplementary-plane chars / surrogate pairs). Encodes once, then backs the cut point off any UTF-8
+ * continuation bytes (`10xxxxxx`) so the boundary lands on a complete code point — never producing a lone
+ * surrogate / U+FFFD. Returns the exact byte length of `text` so callers needn't re-measure.
+ */
+function clampBytes(s, maxBytes) {
+    // Fast path (common): measure without allocating a Buffer copy when nothing needs truncating.
+    const total = Buffer.byteLength(s, "utf8");
+    if (total <= maxBytes)
+        return { text: s, bytes: total, truncated: false };
+    const buf = Buffer.from(s, "utf8");
+    // Move the cut to a code-point boundary: if the FIRST EXCLUDED byte is a UTF-8 continuation byte
+    // (10xxxxxx) we're slicing mid-sequence, so step back until it isn't (a lead/ASCII byte = a boundary).
+    let end = maxBytes;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    return { text: buf.toString("utf8", 0, end), bytes: end, truncated: true };
+}
+/** Run one step on a remote env via the streaming `execStream`, capping output and never throwing out. */
+async function runStreamStep(env, step, options, maxOutputBytes) {
+    const label = step.label ?? step.command;
+    const out = [];
+    const errOut = [];
+    let outBytes = 0;
+    let errBytes = 0;
+    let truncated = false;
+    let exitCode = null;
+    const append = (bucket, used, chunk) => {
+        if (used >= maxOutputBytes) {
+            truncated = true;
+            return used;
+        }
+        const { text, bytes, truncated: cut } = clampBytes(chunk, maxOutputBytes - used);
+        if (cut)
+            truncated = true;
+        bucket.push(text);
+        return used + bytes;
+    };
+    try {
+        for await (const chunk of env.execStream(step.command, {
+            cwd: step.cwd,
+            env: step.env,
+            timeout: step.timeoutSec,
+            signal: options.signal,
+            readTimeoutMs: options.readTimeoutMs,
+            maxOutputBytes,
+        })) {
+            if (chunk.type === "stdout")
+                outBytes = append(out, outBytes, chunk.data);
+            else if (chunk.type === "stderr")
+                errBytes = append(errOut, errBytes, chunk.data);
+            else
+                exitCode = chunk.exitCode;
+        }
+    }
+    catch (e) {
+        const code = e instanceof RemoteExecutionError
+            ? e.code
+            : e?.name === "AbortError"
+                ? "aborted"
+                : "unknown";
+        return { label, command: step.command, exitCode: null, stdout: out.join(""), stderr: errOut.join(""), ok: false, errorCode: code, truncated };
+    }
+    return { label, command: step.command, exitCode, stdout: out.join(""), stderr: errOut.join(""), ok: exitCode === 0, truncated };
+}
+/** Run one step on a base env via the buffered `exec`, capping output. */
+async function runBufferedStep(env, step, options, maxOutputBytes) {
+    const label = step.label ?? step.command;
+    const res = await env.exec(step.command, {
+        cwd: step.cwd,
+        env: step.env,
+        timeout: step.timeoutSec,
+        abortSignal: options.signal,
+    });
+    if (!res.ok) {
+        return { label, command: step.command, exitCode: null, stdout: "", stderr: "", ok: false, errorCode: res.error.code };
+    }
+    const so = clampBytes(res.value.stdout, maxOutputBytes);
+    const se = clampBytes(res.value.stderr, maxOutputBytes);
+    return {
+        label,
+        command: step.command,
+        exitCode: res.value.exitCode,
+        stdout: so.text,
+        stderr: se.text,
+        ok: res.value.exitCode === 0,
+        truncated: so.truncated || se.truncated,
+    };
+}
+/** Narrowing assertion so the stream branch carries the remote type (only called after `isRemoteExecutionEnv`). */
+function assertRemote(env) {
+    if (!isRemoteExecutionEnv(env))
+        throw new Error("not a remote env");
+    return env;
+}
+/**
+ * Run an L2 mechanical gate: execute `steps` in `env` and gate on real exit codes. See the file header for
+ * the security contract — `steps` must be a trusted, spec-derived suite, not worker-authored tests.
+ */
+export async function runExecGate(env, steps, options = {}) {
+    const stopOnFailure = options.stopOnFailure ?? true;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const remote = isRemoteExecutionEnv(env);
+    const results = [];
+    for (const step of steps) {
+        if (options.signal?.aborted) {
+            results.push({ label: step.label ?? step.command, command: step.command, exitCode: null, stdout: "", stderr: "", ok: false, errorCode: "aborted" });
+            break;
+        }
+        const r = remote
+            ? await runStreamStep(assertRemote(env), step, options, maxOutputBytes)
+            : await runBufferedStep(env, step, options, maxOutputBytes);
+        results.push(r);
+        if (!r.ok && stopOnFailure)
+            break;
+    }
+    return { passed: results.length > 0 && results.every((s) => s.ok), steps: results };
+}
+//# sourceMappingURL=exec-gate.js.map

package/dist/core/exec-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-gate.js","sourceRoot":"","sources":["../../src/core/exec-gate.ts"],"names":[],"mappings":"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"}