@sema-agent/core 7.53.0 → 7.54.0

package/dist/core/{shell-lexer.js → shell-run-candidates.js}

@@ -1,62 +1,74 @@
+import { arithmeticTextIsPlain, compoundValueHidesRun, expansionHidesRun, heredocBodyHidesRun, lexShell, namesRedirectDescriptor, PARSE_FAILURE_SENTENCE, } from "../shell/lex.js";
 import { shellWordsOf } from "../shell/shell-words.js";
+import { isLauncherAssignmentOperand } from "../tools/fs/bash-program-position.js";
+import { extglobOpenerIn } from "../tools/fs/bash-readonly-classifier.js";
 import { evaluatesOperand, SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
-import { arithmeticHidesRun, carriesSubstitution, freshWord, matchOp, readDoubleQuoted, readExpansion, skipBalanced, skipHeredocBodies } from "./shell-scan.js";
 export { SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
 const WRAPPERS = new Map(Object.entries(SHELL_WRAPPER_TABLE));
 const PREFIX_KEYWORDS = shellWordsOf("stripped_prefix");
 const CLOSING_KEYWORDS = shellWordsOf("stripped_standalone");
 const OPAQUE_KEYWORDS = shellWordsOf("opaque");
-const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?\+?=/;
+const CONTROL_PREFIXES = shellWordsOf("control_prefix");
 const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
-const REDIRECT_OPS = ["<<<", "<<-", "<<", "<>", "<&", "<", ">>", ">|", ">&", "&>>", "&>", ">"];
-const CONNECTOR_OPS = ["&&", "||", "|&", "|", ";;&", ";&", ";;", ";", "&"];
-const ALL_OPS = [...CONNECTOR_OPS, ...REDIRECT_OPS];
 export const MAX_SHELL_READ_CHARS = 10_000;
+const LEXED_WORDS = new WeakMap();
+export function lexedWordOf(w) {
+    return LEXED_WORDS.get(w);
+}
+function wordOf(w) {
+    let expands = false;
+    const widen = (to) => { if (expands !== "many")
+        expands = to; };
+    let text = "";
+    for (const p of w.pieces) {
+        const e = p.expansion;
+        if (p.quotedBy === "$'" || (e === undefined && p.literal === undefined)) {
+            widen("many");
+            continue;
+        }
+        if (e === undefined) {
+            text += p.literal ?? "";
+            continue;
+        }
+        if (e.kind === "tilde") {
+            if (p === w.pieces[0])
+                widen(e.yields);
+            text += e.body ?? "";
+        }
+        else if (e.kind === "brace") {
+            widen("many");
+            text += `{${e.body ?? ""}}`;
+        }
+        else {
+            widen(e.yields);
+            text += e.pattern?.folded ?? "";
+        }
+    }
+    const out = { text, raw: w.raw, expands };
+    LEXED_WORDS.set(out, w);
+    return out;
+}
+const literalIn = (w, set) => w !== undefined && w.expands === false && set.has(w.text);
+const bareAssignment = (w) => lexedWordOf(w)?.assignment?.bare === true;
+const hidesRun = (w) => w.expansions.some((p) => p.expansion !== undefined && expansionHidesRun(p.expansion)) || (w.assignment?.subscript !== undefined && !arithmeticTextIsPlain(w.assignment.subscript.raw)) || compoundValueHidesRun(w);
+const CASE_ARM_UNREAD = "a `case` arm terminator outside a `case` this lane reads";
+const EXTGLOB_UNREAD = "an extended pattern (`?(…)` `*(…)` `+(…)` `@(…)` `!(…)`) is one this reader does not expand";
 export function readShellCommand(source) {
     if (source.length > MAX_SHELL_READ_CHARS)
         return { segments: [{ argv: [], redirections: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false, backgrounded: false, strayRedirection: false };
+    const lexed = lexShell(source);
+    const failed = "parseFailure" in lexed ? lexed : undefined;
+    const read = "parseFailure" in lexed ? lexed.readBefore : lexed.segments;
     const segments = [];
     const connectors = [];
     let grouped = false;
     let backgrounded = false;
     let strayRedirection = false;
     let seg = { words: [], redirections: [] };
-    let word = freshWord();
-    let pendingRedirect;
-    let heredocs = [];
-    let badDelimiter = false;
     let afterBoundary = true;
     let lastConnector;
-    let tail;
-    const n = source.length;
-    let i = 0;
-    const endWord = () => {
-        if (!word.started)
-            return;
-        if (word.braceExpands)
-            word.expands = "many";
-        if (word.substitution)
-            seg.substitution = true;
-        if (pendingRedirect !== undefined) {
-            if (pendingRedirect === "<<" || pendingRedirect === "<<-") {
-                if (word.expands !== false)
-                    badDelimiter = true;
-                heredocs.push({ delimiter: word.text, quoted: word.raw !== word.text, dash: pendingRedirect === "<<-" });
-            }
-            seg.redirections.push({ op: pendingRedirect, target: publicWord(word) });
-            pendingRedirect = undefined;
-        }
-        else {
-            seg.words.push(word);
-        }
-        word = freshWord();
-    };
+    let arithmetic;
     const finishSegment = (connector) => {
-        endWord();
-        if (pendingRedirect !== undefined) {
-            seg.unreadable ??= `the redirection \`${pendingRedirect}\` has no operand — a syntax error`;
-            pendingRedirect = undefined;
-        }
         let built = buildSegment(seg);
         if (built === "keyworded")
             grouped = true;
@@ -86,214 +98,121 @@ export function readShellCommand(source) {
         afterBoundary = false;
     };
     const boundary = () => { finishSegment(undefined); grouped = true; afterBoundary = true; lastConnector = undefined; };
-    while (i < n && tail === undefined) {
-        const ch = source[i];
-        if (ch === " " || ch === "\t") {
-            endWord();
-            i++;
-            continue;
-        }
-        if (ch === "\n") {
-            endWord();
-            if (badDelimiter) {
-                tail = "a here-document delimiter spelled with an expansion";
-                break;
-            }
-            if (heredocs.length === 0) {
-                finishSegment("\n");
-                i++;
-                continue;
-            }
-            const skipped = skipHeredocBodies(source, i + 1, heredocs);
-            heredocs = [];
-            if (skipped === undefined) {
-                tail = "a here-document body never reaches its delimiter";
-                break;
+    const word = (w) => { if (hidesRun(w))
+        seg.substitution = true; return wordOf(w); };
+    const readTokens = (s) => {
+        const tokens = s.tokens;
+        const shown = tokens.flatMap((t) => (t.kind === "word" ? t.expansions : t.kind === "redirect" ? t.target?.expansions ?? [] : [])).filter((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic").length;
+        if (s.substitutions.length > shown)
+            seg.substitution = true;
+        let definitionClose = false;
+        tokens.forEach((t, i) => {
+            if (arithmetic !== undefined) {
+                if (t.kind === "group") {
+                    arithmetic.depth += t.op === "(" ? 1 : -1;
+                    if (arithmetic.depth === 0)
+                        arithmetic = undefined;
+                    return;
+                }
+                const w = t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined;
+                if (w === undefined || hidesRun(w) || !arithmeticTextIsPlain(w.raw) || t.kind === "heredoc")
+                    seg.substitution = true;
+                if (t.kind === "redirect" && t.dup !== undefined && !arithmeticTextIsPlain(t.dup))
+                    seg.substitution = true;
+                return;
             }
-            if (skipped.substitution)
-                seg.substitution = true;
-            finishSegment("\n");
-            i = skipped.end;
-            continue;
-        }
-        if (ch === "#" && !word.started) {
-            while (i < n && source[i] !== "\n")
-                i++;
-            continue;
-        }
-        if (ch === "\\") {
-            if (i + 1 >= n) {
-                tail = "a trailing backslash — the line never ends";
-                break;
+            if (t.kind === "word") {
+                if (!namesRedirectDescriptor(t, tokens[i + 1]))
+                    seg.words.push(word(t));
+                return;
             }
-            if (source[i + 1] === "\n") {
-                i += 2;
-                continue;
+            if (t.kind === "redirect") {
+                const target = t.target !== undefined ? word(t.target) : { text: t.dup ?? "", raw: t.dup ?? "", expands: false };
+                seg.redirections.push({ op: t.op, target });
+                return;
             }
-            word.started = true;
-            word.text += source[i + 1];
-            word.raw += source.slice(i, i + 2);
-            i += 2;
-            continue;
-        }
-        if (ch === "'") {
-            const close = source.indexOf("'", i + 1);
-            if (close < 0) {
-                tail = "an unterminated single quote";
-                break;
+            if (t.kind === "heredoc") {
+                seg.redirections.push({ op: "<<", target: { text: t.delimiter, raw: t.delimiter, expands: false } });
+                if (!t.quoted && heredocBodyHidesRun(t.body))
+                    seg.substitution = true;
+                return;
             }
-            word.started = true;
-            word.text += source.slice(i + 1, close);
-            word.raw += source.slice(i, close + 1);
-            i = close + 1;
-            continue;
-        }
-        let dq = i + 1;
-        if (ch === "$")
-            while (source[dq] === "\\" && source[dq + 1] === "\n")
-                dq += 2;
-        if (ch === '"' || (ch === "$" && source[dq] === '"')) {
-            const open = ch === "$" ? dq + 1 : i + 1;
-            const end = readDoubleQuoted(source, open, word);
-            if (end === undefined) {
-                tail = "an unterminated double quote";
-                break;
+            const next = tokens[i + 1];
+            if (definitionClose) {
+                definitionClose = false;
+                return;
             }
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "$" || ch === "`" || ((ch === "<" || ch === ">") && source[i + 1] === "(")) {
-            const end = readExpansion(source, i, word);
-            if (end === undefined) {
-                tail = "an unterminated substitution";
-                break;
+            if (t.op === "(" && next?.kind === "group" && next.op === "(" && seg.redirections.length === 0 && seg.words.every((w) => literalIn(w, CONTROL_PREFIXES) || literalIn(w, CLOSING_KEYWORDS) || (w.expands === false && w.text === "-p"))) {
+                arithmetic = { depth: 1 };
+                return;
             }
-            if (end === i + 1) {
-                word.started = true;
-                word.text += ch;
-                word.raw += ch;
-                i = end;
-                continue;
+            if (t.op === "(" && next?.kind === "group" && next.op === ")" && seg.words.length === 1 && seg.words[0].expands === false && seg.redirections.length === 0) {
+                seg.words.pop();
+                definitionClose = true;
             }
-            word.started = true;
-            word.expands = ch === "$" || ch === "`" ? "many" : word.expands || "one";
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "~" && !word.started)
-            word.expands = "one";
-        const op = matchOp(source, i, ALL_OPS);
-        if (op !== undefined) {
-            if (CONNECTOR_OPS.includes(op)) {
-                if (op === ";;" || op === ";&" || op === ";;&") {
-                    endWord();
-                    seg.unreadable ??= "a `case` arm terminator outside a `case` this lane reads";
-                    i += op.length;
-                    continue;
-                }
-                if (op === "&")
-                    backgrounded = true;
-                finishSegment(op);
-                i += op.length;
+            boundary();
+        });
+    };
+    for (let k = 0; k < read.length; k++) {
+        const s = read[k];
+        if (k > 0) {
+            const armEnd = caseArmEnd(read, k);
+            if (armEnd !== undefined) {
+                seg.unreadable ??= CASE_ARM_UNREAD;
+                k = armEnd;
+                readTokens(read[k]);
                 continue;
             }
-            if (word.started && word.raw === word.text && (/^\d+$/.test(word.text) || /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(word.text)))
-                word = freshWord();
-            else
-                endWord();
-            if (pendingRedirect !== undefined)
-                seg.unreadable ??= `the redirection \`${pendingRedirect}\` has no operand — a syntax error`;
-            pendingRedirect = op;
-            i += op.length;
-            continue;
-        }
-        if (ch === "(" && word.started && "@?*+!".includes(word.raw.slice(-1)) && word.raw !== "!") {
-            const end = skipBalanced(source, i, "(", ")");
-            if (end === undefined) {
-                tail = "an unterminated extended pattern (`@(…)`)";
-                break;
-            }
-            if (carriesSubstitution(source.slice(i + 1, end - 1)))
-                word.substitution = true;
-            word.expands = "many";
-            word.text += source.slice(i, end);
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "(" && source[i + 1] === "(" && (!word.started || word.raw === "!") && pendingRedirect === undefined && seg.words.every((w) => w.expands === false && (shellWordsOf("control_prefix").has(w.text) || CLOSING_KEYWORDS.has(w.text) || w.text === "-p"))) {
-            endWord();
-            const end = skipBalanced(source, i, "(", ")");
-            if (end === undefined) {
-                tail = "an unterminated arithmetic command";
-                break;
+            const connector = s.pipesStderr === true ? "|&" : s.connector;
+            if (arithmetic !== undefined) {
+                if (connector === ";")
+                    seg.substitution = true;
             }
-            if (arithmeticHidesRun(source.slice(i + 2, end - 1)))
-                seg.substitution = true;
-            i = end;
-            continue;
-        }
-        if (ch === "(" || ch === ")") {
-            if (ch === "(" && word.started && !word.expands && seg.words.length === 0 && pendingRedirect === undefined) {
-                let j = i + 1;
-                while (j < n && (source[j] === " " || source[j] === "\t"))
-                    j++;
-                if (source[j] === ")") {
-                    word = freshWord();
-                    boundary();
-                    i = j + 1;
-                    continue;
-                }
+            else {
+                if (connector === "&")
+                    backgrounded = true;
+                finishSegment(connector);
             }
-            boundary();
-            i++;
-            continue;
         }
-        if (ch === "*" || ch === "?" || (ch === "]" && word.bracketOpen))
-            word.expands = "many";
-        if (ch === "[")
-            word.bracketOpen = true;
-        if (ch === "{")
-            word.braceOpen = true;
-        if (word.braceOpen && (ch === "," || (ch === "." && source[i + 1] === ".")))
-            word.braceExpands = true;
-        if (ch === "}" && !word.braceExpands)
-            word.braceOpen = false;
-        word.started = true;
-        word.text += ch;
-        word.raw += ch;
-        i++;
+        readTokens(s);
     }
-    if (tail !== undefined) {
-        endWord();
-        seg.unreadable ??= tail;
-        finishSegment(undefined);
+    if (failed !== undefined) {
+        seg.unreadable ??= PARSE_FAILURE_SENTENCE[failed.parseFailure.reason];
+    }
+    else if (arithmetic !== undefined) {
+        seg.unreadable ??= "an unterminated arithmetic command";
     }
     else {
-        if (heredocs.length > 0)
-            seg.unreadable ??= "a here-document with no body";
-        const dangling = seg.words.length === 0 && !word.started && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
+        const dangling = seg.words.length === 0 && seg.redirections.length === 0 && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
         if (dangling)
             seg.unreadable ??= `the connector \`${lastConnector}\` has no command after it — a syntax error`;
-        finishSegment(undefined);
     }
+    finishSegment(undefined);
+    if (failed === undefined && "segments" in lexed && extglobOpenerIn(lexed, source))
+        return { segments: segments.map((s) => (s.unreadable !== undefined ? s : { ...s, peelUnreadable: s.peelUnreadable ?? EXTGLOB_UNREAD })), connectors, grouped, backgrounded, strayRedirection };
     return { segments, connectors, grouped, backgrounded, strayRedirection };
 }
-const publicWord = ({ text, raw, expands }) => ({ text, raw, expands });
+function caseArmEnd(read, k) {
+    const arm = (j) => read[j].connector === ";" && read[j].text === "" && read[j].tokens.length === 0;
+    const next = read[k + 1];
+    if (!arm(k) || next === undefined || (next.connector !== ";" && next.connector !== "&"))
+        return undefined;
+    const third = read[k + 2];
+    return next.connector === ";" && arm(k + 1) && third?.connector === "&" ? k + 2 : k + 1;
+}
 const SUBSTITUTION_UNREAD = "a command substitution runs a program this reader does not read";
 const MAX_WRAPPER_LAYERS = 8;
 export function isFullyReadable(shape) {
     return shape.segments.every((s) => s.unreadable === undefined && s.peelUnreadable === undefined && [s.argv, ...s.peeled].every((argv) => argv[0]?.expands === false));
 }
+const operandsOf = (run) => run.map((w) => ({ text: w.text, raw: w.raw, assignment: lexedWordOf(w)?.assignment }));
 function buildSegment(seg) {
     if (seg.unreadable !== undefined)
-        return { argv: seg.words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
+        return { argv: seg.words, redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
     const carried = () => (seg.substitution === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
     let keyworded = false;
     let k0 = 0;
-    while (k0 < seg.words.length && seg.words[k0].expands === false && (PREFIX_KEYWORDS.has(seg.words[k0].text) || CLOSING_KEYWORDS.has(seg.words[k0].text))) {
+    while (k0 < seg.words.length && (literalIn(seg.words[k0], PREFIX_KEYWORDS) || literalIn(seg.words[k0], CLOSING_KEYWORDS))) {
         k0++;
         keyworded = true;
     }
@@ -301,24 +220,24 @@ function buildSegment(seg) {
     const head = words[0];
     if (head === undefined)
         return carried();
-    if (evaluatesOperand(words))
+    if (evaluatesOperand(operandsOf(words)))
         seg.substitution = true;
     if (head.expands === false && (head.text === "[[" || head.text === "["))
         return carried();
-    if (head.expands === false && OPAQUE_KEYWORDS.has(head.text))
-        return { argv: words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
-    const argv = words.map(publicWord);
+    if (literalIn(head, OPAQUE_KEYWORDS))
+        return { argv: words, redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
+    const argv = words;
     const peeled = [];
     let peelUnreadable;
     let k = 0;
-    while (k < argv.length && ASSIGNMENT_RE.test(argv[k].raw))
+    while (k < argv.length && bareAssignment(argv[k]))
         k++;
     let run = argv.slice(k);
     if (k > 0 && run.length > 0)
         peeled.push(run);
     for (let layer = 0; run.length > 0; layer++) {
         let j = 0;
-        while (j < run.length && ((run[j].text === "!" && run[j].expands === false) || ASSIGNMENT_RE.test(run[j].raw)))
+        while (j < run.length && ((run[j].text === "!" && run[j].expands === false) || bareAssignment(run[j])))
             j++;
         if (j > 0) {
             run = run.slice(j);
@@ -344,7 +263,7 @@ function buildSegment(seg) {
         run = next;
         peeled.push(run);
     }
-    if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(c)))
+    if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(operandsOf(c))))
         peelUnreadable ??= SUBSTITUTION_UNREAD;
     return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
 }
@@ -364,6 +283,7 @@ function unwrap(words) {
     const flags = new Set(row.flags);
     const attached = new Set(row.attached ?? []);
     const commandString = new Set(row.commandString);
+    const assignmentOperand = (w) => row.assignments === true && w.expands === false && isLauncherAssignmentOperand(w.text);
     let positionalTaken = row.positional === undefined;
     let durationTaken = row.duration !== true;
     let replaceToken;
@@ -405,7 +325,7 @@ function unwrap(words) {
                     return r;
                 i++;
             }
-            while (row.assignments === true && i < words.length && words[i].expands === false && ASSIGNMENT_RE.test(words[i].text))
+            while (i < words.length && assignmentOperand(words[i]))
                 i++;
             break;
         }
@@ -464,7 +384,7 @@ function unwrap(words) {
             i++;
             continue;
         }
-        if (row.assignments === true && ASSIGNMENT_RE.test(t)) {
+        if (assignmentOperand(w)) {
             i++;
             continue;
         }

package/dist/core/shell-wrapper-table.d.ts

@@ -1,5 +1,6 @@
+import type { AssignmentFact } from "../shell/lex.js";
 /**
- * The wrapper programs the tightening reader ({@link import("./shell-lexer.js").readShellCommand}) peels to
+ * The wrapper programs the tightening reader ({@link import("./shell-run-candidates.js").readShellCommand}) peels to
  * reach the program they run — upstream's three tables (its light strip on every arm, its full strip on
  * the deny/ask arms, and its `xargs` clause inlined in the matcher) as ONE closed table. Peeling is
  * ADDITIVE on the reading side: the segment keeps its spelled argv as one run candidate and adds one
@@ -395,13 +396,14 @@ export interface ShellWrapperRow {
  *  subscript (`arr[a]`, quoted, bare, attached `-varr[a]`, or `arr[a]=1`) is evaluated as arithmetic —
  *  recursively, like `$((a))` — when the builtin reads or writes it (`printf -v 'arr[a]' …`, `unset arr[a]`,
  *  `declare arr[a]=1`, `read arr[a]`, `[[ -v arr[a] ]]`, `test -v arr[a]`), and so is the value of an
- *  INTEGER-attribute assignment (`declare -i x=a`). The lexer marks such a run's hidden run at every peel
+ *  INTEGER-attribute assignment (`declare -i x=a`). The tightening reader marks such a run's hidden run at every peel
  *  candidate (`command printf -v …`). An operand that is WHOLLY an expansion is not judged here (`unset "$X"`
  *  — one more indirection; the price of reading it would be a prompt on every `export FOO="$BAR"`), nor is
  *  an arithmetic comparison's operand (`[[ $n -gt 0 ]]` evaluates `$n` — the same price). */
 export declare const VARIABLE_OPERAND_BUILTINS: ReadonlySet<string>;
-/** Does this run of a variable-operand builtin evaluate an operand arithmetically? Linear in the words. */
+/** Does this run of a variable-operand builtin evaluate an operand arithmetically? `assignment`: the lexer's fact on the word. */
 export declare function evaluatesOperand(run: readonly {
     readonly text: string;
     readonly raw: string;
+    readonly assignment?: AssignmentFact | undefined;
 }[]): boolean;

package/dist/core/shell-wrapper-table.js

@@ -67,7 +67,7 @@ export function evaluatesOperand(run) {
     if (!VARIABLE_OPERAND_BUILTINS.has(run[0]?.text ?? ""))
         return false;
     const integer = run.some((w) => /^-[A-Za-z]*i/.test(w.text));
-    return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && /^[A-Za-z_][A-Za-z0-9_]*\+?=.*[A-Za-z_$]/.test(w.text)));
+    return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && w.assignment !== undefined && /[A-Za-z_$]/.test(w.assignment.value.folded)));
 }
 function namesArrayElement(word) {
     for (let open = word.indexOf("["); open > 0; open = word.indexOf("[", open + 1)) {

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -308,7 +308,7 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
-    run("design/388 B18 × B6 identity + face group: a row's eight optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget/names) survive the round-trip verbatim; an absent group stays absent", async () => {
+    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/names + targets) survive the round-trip verbatim; an absent group stays absent", async () => {
         const store = make();
         const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
         const group = {
@@ -316,10 +316,10 @@ export async function checkpointStoreContract(make, runAssertion) {
             contractId: "acme.write@2",
             shapeDigest: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
             implementationRevision: "r7",
-            rosterDigest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
             family: "file-write",
             pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
             names: ["AcmeWrite", "acme_write"],
+            targets: { protective: "/srv/work/out.txt", declared: "/srv/work/out.txt" },
         };
         Object.assign(carried.pendingAction, group);
         const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });

package/dist/core/store-contracts/session-store-contract.d.ts

@@ -0,0 +1,49 @@
+import { type SessionStore } from "../session.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+import { type SessionStoreIncarnationContractHooks } from "./session-store-incarnation-contract.js";
+/**
+ * The cross-backend contract for {@link SessionStore} as the interface states it TODAY — what a store must
+ * do so that the engine, a deployment's authorizer and a shell read the same answers off it whether the
+ * store is the bundled `TtlSessionStore` (over an in-memory or file repo) or a backend that implements the
+ * interface directly (a SQL store). vitest-free (see `contract-harness.ts`); every case builds a FRESH store
+ * through `make()` and disposes it.
+ *
+ * Each case pins one sentence of the interface (`core/session.ts`) or of the session-tree storage it hands
+ * out (`SessionStorage`, whose path / leaf / write-CAS rules every store's sessions carry). Optional faces
+ * are judged only when present; a group whose face is absent passes WITHOUT asserting and says so through
+ * `onOptionalMember` — a case name cannot carry "absent" (the default runner drops names, and a green
+ * absent run is byte-identical to a green verified one), so a consumer that relies on a face asserts the
+ * report, never the green.
+ *
+ * What the kit cannot see from outside, it does not claim: idle eviction and `pin` (the interface has no
+ * clock seam), what `release` does to an ordinary session's live set (`size` is best-effort and a durable
+ * `list` may still show the history), a durable backend's crash recovery, and a delete that fails half-way.
+ * One stated obligation is not a case yet because the bundled store does not keep it: an ownership row
+ * outliving its session across a restart (`TtlSessionStore` holds owners in process memory).
+ *
+ * Semantics since @sema-agent/core 7.55.0.
+ */
+export interface SessionStoreContractHooks {
+    /** The same hook as the incarnation kit's ({@link SessionStoreIncarnationContractHooks.deleteSession}): one
+     *  function serves both kits. */
+    deleteSession: SessionStoreIncarnationContractHooks["deleteSession"];
+    /** A SECOND, independent store instance over the same rows as `store` — what a restarted process
+     *  constructs. After calling it the kit no longer uses `store`, so a backend that holds an exclusive lock
+     *  may release `store`'s first (the kit still disposes `store` at the end of the case: that dispose must
+     *  then be harmless). The kit disposes the returned instance. */
+    reopen: (store: SessionStore) => SessionStore | Promise<SessionStore>;
+    /** A second LIVE instance over the same rows, used CONCURRENTLY with `store` — what another replica
+     *  constructs. Absent ⇒ the replica case is reported absent (a backend that is single-process by
+     *  contract has no replica). The kit disposes it. */
+    replica?: (store: SessionStore) => SessionStore;
+    runAssertion?: ContractAssertionRunner;
+    /** Optional faces (plus the replica hook, and `requireExisting` — absent = the store rejects the option, its other
+     *  legal mode) a run verified or found absent; reported per judging case, after its assertions held. */
+    onOptionalMember?: (report: {
+        member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "ownership" | "incarnationOf" | "replica";
+        status: "verified" | "absent";
+    }) => void;
+}
+/** A hooks record the kit cannot run with is refused SYNCHRONOUSLY, before any case is registered, so a
+ *  `void sessionStoreContract(…)` registration fails at collection instead of as an unhandled rejection. */
+export declare function sessionStoreContract(make: () => SessionStore, hooks: SessionStoreContractHooks): Promise<void>;