@sema-agent/core 5.57.0 → 5.59.0

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

@@ -91,6 +91,25 @@ export interface MemoryConsolidationOptions {
     maxDirectedPatchesPerPlan?: number;
     minRunIntervalMs?: number;
     minSessionsBetweenRuns?: number;
+    /** design/376 C-2② — the scan-refusal fuse's ratio leg, in (0, 1]: scan findings refuse the
+     *  affected PRODUCT (disclosed beside eligibility drift), and the whole plan refuses only when
+     *  more than max(1, ⌊ratio × submitted products⌋) of them fail the scan (the floor keeps the
+     *  per-product tolerance alive on 1-4 product plans — the drive lane's common size) — see
+     *  {@link scanRefusalCeiling}. Default 0.25. */
+    scanRefusalRatioCap?: number;
+    /** design/376 C-2② — the fuse's absolute leg (positive integer): the large-batch upper bound on
+     *  tolerated scan refusals per plan, so the ratio cannot scale the tolerance without limit.
+     *  Default 8 (the point where the 0.25 ratio hands over at 32 submitted products — the family's
+     *  "小 N" quantification; below that the ratio leg alone governs). */
+    scanRefusalMaxPerPlan?: number;
+    /** design/376 C-3 — the EXPLICIT escape hatch for the unconditional instruction-form gate:
+     *  instruction-form consolidation products (`type: "feedback"` / v2 hint carriers) are refused
+     *  by default REGARDLESS of the visible set's markers — a clean-set instruction product is the
+     *  model-reachable privilege route (N ordinary notes in, one instruction entry out). `true` is
+     *  the only accepted value (a posture declaration, like {@link multiNode}); it opens the
+     *  CLEAN-set arm only — a marked visible set refuses instruction forms under the laundering
+     *  hard gate no matter what (privilege and hard gate enter and exit through one door). */
+    allowInstructionProducts?: true;
     /** D-13a — the multi-node POSTURE declaration: present ⇒ `lease` must be injected (constructor
      *  refusal otherwise). Multi-node without declaring is OUT OF CONTRACT (structurally
      *  undetectable — the declaration turns a silent omission into an explicit choice). */
@@ -113,6 +132,8 @@ export declare const CONSOLIDATION_DEFAULTS: {
     readonly maxDirectedPatchesPerPlan: 32;
     readonly minRunIntervalMs: number;
     readonly minSessionsBetweenRuns: 5;
+    readonly scanRefusalRatioCap: 0.25;
+    readonly scanRefusalMaxPerPlan: 8;
 };
 /**
  * §2.2 — the HARD throttle floor: even a `force` run cannot start a second same-scope run within
@@ -126,7 +147,7 @@ export declare const CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS = 60000;
 /** The bounded distinct-session ring (§2.3 sessionsSince dedup). */
 export declare const CONSOLIDATION_SESSION_RING_MAX = 64;
 /**
- * codex r2 — the seat's FREEZE GRACE: reconcile's orphan-release arm treats a seat whose plan file
+ * the seat's FREEZE GRACE: reconcile's orphan-release arm treats a seat whose plan file
  * is absent as crashed ONLY once the claim is at least this old. Calibration: the freeze between
  * the seat CAS and the plan file's durable write is committed READS only (headers + a bounded
  * getByIds) — seconds on any healthy store; ten minutes is orders of magnitude past it, while a
@@ -142,6 +163,9 @@ export interface ScreenedConsolidationOptions {
     maxDirectedPatchesPerPlan: number;
     minRunIntervalMs: number;
     minSessionsBetweenRuns: number;
+    scanRefusalRatioCap: number;
+    scanRefusalMaxPerPlan: number;
+    allowInstructionProducts: boolean;
     multiNode: boolean;
     lease?: ConsolidationLeaseSeat;
 }
@@ -159,6 +183,21 @@ export declare function screenConsolidationOptions(raw: MemoryConsolidationOptio
 /** §1.2-2 — the supersession fuse ceiling: min(N-1, max(floor, ⌊ratio×N⌋)); N ≤ 1 ⇒ 0 (one plan
  *  may NEVER empty the active set — the N-1 ceiling is unconditional, G21). */
 export declare function supersessionFuseCeiling(activeSetSize: number, opts: Pick<ScreenedConsolidationOptions, "supersedeRatioCap" | "supersedeAbsoluteFloor">): number;
+/**
+ * design/376 C-2② — the scan-refusal fuse ceiling: how many scan-refused products ONE plan may
+ * carry before the whole plan refuses instead of committing around them.
+ * `min(max(1, ⌊ratio × submitted⌋), absolute max)`; the ratio leg governs small plans, the
+ * absolute leg is the large-batch upper bound, and the FLOOR of one keeps C-2①'s per-product
+ * tolerance alive at the drive lane's common plan sizes — under the default 0.25 ratio a bare
+ * floor answers 0 for every ≤3-product plan, so one stray refused product re-killed the whole
+ * plan there, exactly the shape C-2① was adopted to remove (an adopted review finding). The
+ * floor is NOT a hole for the fully-refused tiny plan: a plan whose every product is refused
+ * (and which carries no directed work) still dies at the freeze-emptied C-2③ backstop, never a
+ * quiet mostly-no-op — what the floor tolerates is exactly one refused product beside at least
+ * one survivor. Submitted count = the proposal's product count (per THIS plan, never a
+ * cross-run tally).
+ */
+export declare function scanRefusalCeiling(submittedProducts: number, opts: Pick<ScreenedConsolidationOptions, "scanRefusalRatioCap" | "scanRefusalMaxPerPlan">): number;
 /** §3.1 — the type axis of the eligibility predicate: episodic entries are read-only evidence
  *  (never candidates, never supersession/directed targets, A-7); procedural promotion is a v3
  *  follow-on ticket. Unknown/absent types are ordinary semantic notes — eligible. */
@@ -177,13 +216,23 @@ export interface ConsolidationGateRow {
     /** The plan-seat mutex: the one non-terminal (or conflict-parked) plan of this scope. */
     openPlanId?: string;
     /** When the seat was claimed (ms epoch) — the reconcile orphan-release arm's staleness anchor
-     *  (codex r2: a freeze legitimately computes for a while between the seat CAS and the plan
+     *  (a freeze legitimately computes for a while between the seat CAS and the plan
      *  file's durable write; an absent file alone must never read as a crash). */
     seatClaimedAt?: number;
     /** §1.4.5 collapse-fuse baseline (last observed active-set size). */
     activeSetBaseline?: number;
     /** Once-per-crossing edge for the recommendation notice. */
     lastRecommendedAt?: number;
+    /** The last force requestId whose FORCED announcement was enqueued (additive; design/376 §1.1-4):
+     *  a RUN-scoped force carries ONE requestId across every cycle of a multi-cycle run, and the
+     *  audit announcement is deduplicated on it — one disclosure per run, never one per cycle (a
+     *  cold start would otherwise flood the next session's injection face with a dozen identical
+     *  lines). A NEW requestId re-arms the disclosure. The dedup is the ONLY record: this row keeps
+     *  just the LAST id (no history structure exists — the gate row is mutated in place, the
+     *  announcement queue is drained destructively, and plan files do not mark forced-ness), so
+     *  per-force facts beyond the one announcement are not persisted, and a caller that reuses a
+     *  fixed requestId across runs keeps the disclosure silent for as long as it does. */
+    lastForcedRequestId?: string;
     /** Run watermark: increments on every completed/discarded settlement (the stale-proposal gate). */
     epoch: number;
     /** §1.2-1 — the last COMPLETED run's full-eligible-set fingerprint (id → committed rev):
@@ -221,6 +270,24 @@ export declare function updateConsolidationGate<T>(controlDir: string, fn: (file
 export declare function readConsolidationGateFile(controlDir: string): ConsolidationGateFile;
 /** True ⇔ the gate store file exists at all (G1's zero-file pin reads this negatively). */
 export declare function consolidationGateFileExists(controlDir: string): boolean;
+/**
+ * design/376 slice ③ (#437②) — the gate read face's DISCRIMINATED answer
+ * ({@link import("./engine.js").MemoryEngine.readConsolidationGateState}): `present` carries the
+ * row; `absent` means the store is readable and simply has no row for the scope (a never-run
+ * scope, or no gate file at all); `corrupt` means the store cannot be trusted and carries the
+ * refusal detail. The undiscriminated `readConsolidationGate` face folds corrupt into `undefined`
+ * — an operator (or a driver's scheduling read) could not tell a healthy never-run scope from a
+ * store every verb will refuse fail-closed.
+ */
+export type ConsolidationGateRead = {
+    state: "present";
+    row: ConsolidationGateRow;
+} | {
+    state: "absent";
+} | {
+    state: "corrupt";
+    detail: string;
+};
 /**
  * §2.2 — the engine-minted session count (harvest-tail bookkeeping; ≤1 row write per terminal
  * harvest; the OFF mode never calls this — D-9a zero-write). Returns the recommendation edge:
@@ -294,7 +361,15 @@ export interface ConsolidationDirectedPatch {
 }
 export type ConsolidationPlanState = "open" | "applying" | "completed" | "conflict" | "discarded";
 export interface ConsolidationPlanFile {
-    v: 1;
+    /** Plan schema version. `2` ⇔ the plan carries {@link freezeRefusedInputIds} — that member is a
+     *  LOAD-BEARING settle input (C-2④ keeps the named ids out of the completion fingerprint), and
+     *  a reader that predates it would accept the file as v1, ignore the member, and settle a
+     *  fingerprint that stamps the refused members (silently blinding the incremental face — the
+     *  exact hole the field closes). Version-gating the member makes such a reader answer its
+     *  "unrecognized version" corrupt arm instead: the plan parks loudly for the valve, never
+     *  settles wrong (mixed-fleet crash window between the durable plan write and gate settlement).
+     *  Plans without the member stay v1 — zero noise on the common path. */
+    v: 1 | 2;
     planId: string;
     scope: string;
     requestId: string;
@@ -308,6 +383,13 @@ export interface ConsolidationPlanFile {
     /** Frozen products — FULL entry bytes (id/frontmatter incl. distilled + origin/body/rev). */
     products: MemoryEntry[];
     productStates: Record<string, "pending" | "applied" | "conflict">;
+    /** design/376 C-2④ — the declared input ids of every product the FREEZE refused (scan findings
+     *  and eligibility drift alike). Settlement keeps these ids OUT of the completion fingerprint:
+     *  a scan-refused input's rev never moved, so stamping it would make every later incremental
+     *  snapshot read it as unchanged and never offer it again — the refused member must stay a
+     *  candidate. Absent on plans frozen before the field existed, and on plans with nothing
+     *  refused (either way the settle filter simply has nothing extra to exclude). */
+    freezeRefusedInputIds?: string[];
     directed: ConsolidationDirectedPatch[];
     intents: Array<{
         requestId: string;
@@ -375,4 +457,38 @@ export declare class ConsolidationRefusedError extends Error {
 }
 /** A NotePatch list for one frozen product (the §1.3 add-only arm's one spelling). */
 export declare function productAddPatch(product: MemoryEntry): NotePatch;
+/**
+ * Why a driver run stopped — ONE closed set shared verbatim by the run receipt and the
+ * `memory.consolidation_incomplete` notice (two vocabularies for the same fact would let an
+ * operator-facing channel and the host-facing receipt drift). Non-`converged` values mark a
+ * library in a PARTIAL fold — a transitional state the readings show is worse than unfolded, so
+ * it must never pass silently:
+ *  - `converged`      — nothing left to fold (the only completed-run value; includes the
+ *                       empty-plan no-op: a model that proposes nothing commits nothing);
+ *  - `fuse_residue`   — the supersession fuse admits no remaining product; the residue is named
+ *                       and the next run's full snapshot re-distills the shrunken library;
+ *  - `max_cycles`     — the cycle bound elapsed before a fixpoint;
+ *  - `parked`         — a plan settled conflict (or a corrupt plan holds the seat); the host
+ *                       valve `resolveConsolidationPlan` is the only way forward;
+ *  - `refused`        — an engine verb refused and the drive could not continue this run;
+ *  - `driver_failed`  — the DRIVER half could not complete. Two grains, one verdict: a failed
+ *                       MINT (model unreachable/unreadable/over the repair budget) settles with
+ *                       zero writes, zero seat and an unburned time gate; a run whose surviving
+ *                       plan reached its fixpoint while the driver's own half left groups
+ *                       unfolded (writing-pass failures, or products dropped stale against
+ *                       inputs edited mid-run) settles here TOO — committed cycles stand
+ *                       (add-only, no rollback), the residue is named, and a fresh run re-mints
+ *                       over the current bytes. The clean `converged` label never covers a
+ *                       driver-side residue.
+ * Extending this set is a consumer-visible closed-set expansion (release-note duty: every
+ * downstream that pinned the enumeration becomes a named party).
+ *
+ * The type DERIVES from the array (never `satisfies` beside it): the array exists precisely for
+ * downstream enumeration, and two independent declarations would let a new union arm skip the
+ * array with no compile error — the derived form makes an edit to either side a type error at
+ * the other.
+ */
+export declare const CONSOLIDATION_RUN_STOP_REASONS: readonly ["converged", "fuse_residue", "max_cycles", "parked", "refused", "driver_failed"];
+/** See the doc on {@link CONSOLIDATION_RUN_STOP_REASONS} — the single source this derives from. */
+export type ConsolidationRunStopReason = (typeof CONSOLIDATION_RUN_STOP_REASONS)[number];
 export {};

package/dist/core/memory-engine/consolidation.js

@@ -40,6 +40,8 @@ export const CONSOLIDATION_DEFAULTS = {
     maxDirectedPatchesPerPlan: 32,
     minRunIntervalMs: 24 * 60 * 60 * 1000,
     minSessionsBetweenRuns: 5,
+    scanRefusalRatioCap: 0.25,
+    scanRefusalMaxPerPlan: 8,
 };
 export const CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS = 60_000;
 export const CONSOLIDATION_SESSION_RING_MAX = 64;
@@ -70,12 +72,18 @@ export function screenConsolidationOptions(raw, provenance) {
         maxDirectedPatchesPerPlan: num("maxDirectedPatchesPerPlan", raw.maxDirectedPatchesPerPlan, (n) => Number.isInteger(n) && n >= 1, "a positive integer"),
         minRunIntervalMs: num("minRunIntervalMs", raw.minRunIntervalMs, (n) => n > 0, "a positive number of milliseconds"),
         minSessionsBetweenRuns: num("minSessionsBetweenRuns", raw.minSessionsBetweenRuns, (n) => Number.isInteger(n) && n >= 0, "a non-negative integer"),
+        scanRefusalRatioCap: num("scanRefusalRatioCap", raw.scanRefusalRatioCap, (n) => n > 0 && n <= 1, "a number in (0, 1]"),
+        scanRefusalMaxPerPlan: num("scanRefusalMaxPerPlan", raw.scanRefusalMaxPerPlan, (n) => Number.isInteger(n) && n >= 1, "a positive integer"),
+        allowInstructionProducts: raw.allowInstructionProducts === true,
         multiNode: raw.multiNode === true,
         ...(raw.lease !== undefined ? { lease: raw.lease } : {}),
     };
     if (raw.multiNode !== undefined && raw.multiNode !== true) {
         throw coded(`MemoryEngineOptions.consolidation.multiNode must be exactly true when present (a posture declaration, not a boolean knob).`, "config.memory_consolidation");
     }
+    if (raw.allowInstructionProducts !== undefined && raw.allowInstructionProducts !== true) {
+        throw coded(`MemoryEngineOptions.consolidation.allowInstructionProducts must be exactly true when present (a posture declaration, not a boolean knob — absent means the instruction-form gate stays closed).`, "config.memory_consolidation");
+    }
     if (screened.multiNode && screened.lease === undefined) {
         throw coded(`MemoryEngineOptions.consolidation.multiNode declared without a lease seat — a multi-node deployment MUST inject the host's global lease (the local plan-seat CAS does not reach across nodes). Inject consolidation.lease or remove the multiNode declaration.`, "config.memory_consolidation_lease_required");
     }
@@ -89,6 +97,11 @@ export function supersessionFuseCeiling(activeSetSize, opts) {
         return 0;
     return Math.min(activeSetSize - 1, Math.max(opts.supersedeAbsoluteFloor, Math.floor(opts.supersedeRatioCap * activeSetSize)));
 }
+export function scanRefusalCeiling(submittedProducts, opts) {
+    if (submittedProducts <= 0)
+        return 0;
+    return Math.min(Math.max(1, Math.floor(opts.scanRefusalRatioCap * submittedProducts)), opts.scanRefusalMaxPerPlan);
+}
 export function consolidationTypeEligible(type) {
     return type !== "episodic" && type !== "procedural";
 }
@@ -186,7 +199,7 @@ function planShapeInvalid(raw, planId) {
     if (typeof raw !== "object" || raw === null)
         return "not an object";
     const p = raw;
-    if (p["v"] !== 1)
+    if (p["v"] !== 1 && p["v"] !== 2)
         return "unrecognized version";
     if (p["planId"] !== planId)
         return "planId mismatch";
@@ -248,6 +261,13 @@ function planShapeInvalid(raw, planId) {
     }
     if (!p["directed"].every((d) => intentIds.has(d.intentRequestId)))
         return "directed patch references an undeclared intent";
+    const freezeRefused = p["freezeRefusedInputIds"];
+    if (freezeRefused !== undefined && (!Array.isArray(freezeRefused) || !freezeRefused.every((x) => typeof x === "string"))) {
+        return "malformed freezeRefusedInputIds";
+    }
+    if ((p["v"] === 2) !== (freezeRefused !== undefined)) {
+        return p["v"] === 2 ? "v2 plan without its freezeRefusedInputIds member" : "freezeRefusedInputIds on a v1 plan";
+    }
     if (!Array.isArray(p["audit"]))
         return "malformed audit trail";
     return undefined;
@@ -340,3 +360,4 @@ export class ConsolidationRefusedError extends Error {
 export function productAddPatch(product) {
     return { op: "add", id: product.id, entry: product, guard: "absent" };
 }
+export const CONSOLIDATION_RUN_STOP_REASONS = ["converged", "fuse_residue", "max_cycles", "parked", "refused", "driver_failed"];

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

@@ -4,7 +4,7 @@ import type { HarvestRejection, MemoryBackend, MemoryEntry, NotePatch, PatchRepo
 export declare const REMOTE_HARVEST_PER_FILE_BYTES: number;
 /** Missing-file ratio above which the harvest refuses wholesale (engine MASS_DELETION_FUSE_RATIO). */
 export declare const REMOTE_MASS_DELETION_FUSE_RATIO = 0.5;
-/** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity — codex H10). */
+/** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity). */
 export declare const REMOTE_HARVEST_MAX_FILES = 500;
 /** Max DIRECTORY nesting depth below the memory root (host DEFAULT_MAX_ENTRY_DEPTH parity — the
  *  host's `scanEntryFiles` walks a subdir only while `depth + 1 <= maxDepth`, so it counts directory