open-multi-agent-kit 0.90.8 → 0.91.0

package/dist/guardrails/shell-command-tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-command-tokenizer.d.ts","sourceRoot":"","sources":["../../src/guardrails/shell-command-tokenizer.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AACD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AACD,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,cAGC;CACD;AAoBD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA0HxE","sourcesContent":["import { hasActiveShellNameGlob } from \"./shell-command-name-glob.ts\";\n\nconst MAX_STATIC_SHELL_INPUT_CHARS = 64 * 1024;\nconst MAX_STATIC_SHELL_WORDS = 4_096;\ntype ShellQuote = '\"' | \"'\";\nexport interface ShellSourceRange {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly contentEnd: number;\n\treadonly quoteStart?: number;\n\treadonly kind: \"literal\" | \"variable\";\n\treadonly escaped: boolean;\n}\nexport interface StaticShellWord {\n\treadonly start: number;\n\treadonly end: number;\n}\nexport interface StaticShellVariable {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly sourceStart: number;\n\treadonly sourceEnd: number;\n}\nexport interface NormalizedStaticShell {\n\treadonly text: string;\n\treadonly sources: readonly ShellSourceRange[];\n\treadonly words: readonly StaticShellWord[];\n\treadonly variables: readonly StaticShellVariable[];\n}\nexport class StaticShellSyntaxError extends Error {\n\tconstructor() {\n\t\tsuper(\"shell command is dynamic or malformed; failing closed\");\n\t\tthis.name = \"StaticShellSyntaxError\";\n\t}\n}\nfunction fail(): never {\n\tthrow new StaticShellSyntaxError();\n}\nfunction isWordBoundary(character: string): boolean {\n\treturn /[\\s;&|()<>]/.test(character);\n}\n\nfunction variableAt(text: string, index: number): string | undefined {\n\tconst remainder = text.slice(index);\n\treturn /^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}/.exec(remainder)?.[0] ?? /^\\$[A-Za-z_][A-Za-z0-9_]*/.exec(remainder)?.[0];\n}\n\nfunction isBraceExpansion(text: string, index: number): boolean {\n\tconst close = text.indexOf(\"}\", index + 1);\n\tif (close < 0) return false;\n\tconst body = text.slice(index + 1, close);\n\treturn body.includes(\",\") || body.includes(\"..\");\n}\n\nexport function normalizeStaticShell(text: string): NormalizedStaticShell {\n\tif (text.length > MAX_STATIC_SHELL_INPUT_CHARS || text.includes(\"`\") || text.includes(\"<(\") || text.includes(\">(\"))\n\t\tfail();\n\tconst output: string[] = [];\n\tconst sources: ShellSourceRange[] = [];\n\tconst words: StaticShellWord[] = [];\n\tconst variables: StaticShellVariable[] = [];\n\tconst append = (\n\t\tcharacter: string,\n\t\tstart: number,\n\t\tend: number,\n\t\tkind: ShellSourceRange[\"kind\"],\n\t\tescaped: boolean,\n\t\tquoteStart?: number,\n\t): void => {\n\t\toutput.push(character);\n\t\tsources.push({ start, end, contentEnd: end, kind, escaped, ...(quoteStart === undefined ? {} : { quoteStart }) });\n\t};\n\tlet index = 0;\n\twhile (index < text.length) {\n\t\tif (isWordBoundary(text[index])) {\n\t\t\tappend(text[index], index, index + 1, \"literal\", false);\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (words.length >= MAX_STATIC_SHELL_WORDS) fail();\n\t\tconst wordStart = output.length;\n\t\tlet quote: ShellQuote | undefined;\n\t\tlet quoteStart: number | undefined;\n\t\tlet pendingStart = index;\n\t\tlet lastSource = -1;\n\t\twhile (index < text.length && (quote !== undefined || !isWordBoundary(text[index]))) {\n\t\t\tconst character = text[index];\n\t\t\tif (quote === \"'\") {\n\t\t\t\tif (character === \"'\") {\n\t\t\t\t\tif (lastSource >= wordStart) sources[lastSource] = { ...sources[lastSource], end: index + 1 };\n\t\t\t\t\tquote = undefined;\n\t\t\t\t\tquoteStart = undefined;\n\t\t\t\t\tindex++;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === '\"' && character === '\"') {\n\t\t\t\tif (lastSource >= wordStart) sources[lastSource] = { ...sources[lastSource], end: index + 1 };\n\t\t\t\tquote = undefined;\n\t\t\t\tquoteStart = undefined;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"\\\\\") {\n\t\t\t\tconst next = text[index + 1];\n\t\t\t\tif (next === undefined) fail();\n\t\t\t\tif (next === \"\\n\") {\n\t\t\t\t\tindex += 2;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (quote === '\"' && !'\\\\\"$'.includes(next)) {\n\t\t\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\t\tindex++;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tappend(next, pendingStart, index + 2, \"literal\", true, quoteStart);\n\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\tindex += 2;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === undefined && (character === '\"' || character === \"'\")) {\n\t\t\t\tquote = character;\n\t\t\t\tquoteStart = index;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"$\") {\n\t\t\t\tif (text[index + 1] === \"(\") fail();\n\t\t\t\tconst token = variableAt(text, index);\n\t\t\t\tif (token === undefined) fail();\n\t\t\t\tconst normalizedStart = output.length;\n\t\t\t\tfor (let offset = 0; offset < token.length; offset++) {\n\t\t\t\t\tappend(\n\t\t\t\t\t\ttoken[offset],\n\t\t\t\t\t\toffset === 0 ? pendingStart : index + offset,\n\t\t\t\t\t\tindex + offset + 1,\n\t\t\t\t\t\t\"variable\",\n\t\t\t\t\t\tfalse,\n\t\t\t\t\t\tquoteStart,\n\t\t\t\t\t);\n\t\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\t}\n\t\t\t\tvariables.push({\n\t\t\t\t\tstart: normalizedStart,\n\t\t\t\t\tend: output.length,\n\t\t\t\t\tsourceStart: index,\n\t\t\t\t\tsourceEnd: index + token.length,\n\t\t\t\t});\n\t\t\t\tindex += token.length;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === undefined && character === \"{\" && isBraceExpansion(text, index)) fail();\n\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\tlastSource = sources.length - 1;\n\t\t\tindex++;\n\t\t\tpendingStart = index;\n\t\t}\n\t\tif (quote !== undefined) fail();\n\t\twords.push({ start: wordStart, end: output.length });\n\t}\n\tconst shell = { text: output.join(\"\"), sources, words, variables };\n\tif (hasActiveShellNameGlob(shell)) fail();\n\treturn shell;\n}\n"]}

package/dist/guardrails/shell-command-tokenizer.js

@@ -0,0 +1,145 @@
+import { hasActiveShellNameGlob } from "./shell-command-name-glob.js";
+const MAX_STATIC_SHELL_INPUT_CHARS = 64 * 1024;
+const MAX_STATIC_SHELL_WORDS = 4_096;
+export class StaticShellSyntaxError extends Error {
+    constructor() {
+        super("shell command is dynamic or malformed; failing closed");
+        this.name = "StaticShellSyntaxError";
+    }
+}
+function fail() {
+    throw new StaticShellSyntaxError();
+}
+function isWordBoundary(character) {
+    return /[\s;&|()<>]/.test(character);
+}
+function variableAt(text, index) {
+    const remainder = text.slice(index);
+    return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}/.exec(remainder)?.[0] ?? /^\$[A-Za-z_][A-Za-z0-9_]*/.exec(remainder)?.[0];
+}
+function isBraceExpansion(text, index) {
+    const close = text.indexOf("}", index + 1);
+    if (close < 0)
+        return false;
+    const body = text.slice(index + 1, close);
+    return body.includes(",") || body.includes("..");
+}
+export function normalizeStaticShell(text) {
+    if (text.length > MAX_STATIC_SHELL_INPUT_CHARS || text.includes("`") || text.includes("<(") || text.includes(">("))
+        fail();
+    const output = [];
+    const sources = [];
+    const words = [];
+    const variables = [];
+    const append = (character, start, end, kind, escaped, quoteStart) => {
+        output.push(character);
+        sources.push({ start, end, contentEnd: end, kind, escaped, ...(quoteStart === undefined ? {} : { quoteStart }) });
+    };
+    let index = 0;
+    while (index < text.length) {
+        if (isWordBoundary(text[index])) {
+            append(text[index], index, index + 1, "literal", false);
+            index++;
+            continue;
+        }
+        if (words.length >= MAX_STATIC_SHELL_WORDS)
+            fail();
+        const wordStart = output.length;
+        let quote;
+        let quoteStart;
+        let pendingStart = index;
+        let lastSource = -1;
+        while (index < text.length && (quote !== undefined || !isWordBoundary(text[index]))) {
+            const character = text[index];
+            if (quote === "'") {
+                if (character === "'") {
+                    if (lastSource >= wordStart)
+                        sources[lastSource] = { ...sources[lastSource], end: index + 1 };
+                    quote = undefined;
+                    quoteStart = undefined;
+                    index++;
+                    pendingStart = index;
+                    continue;
+                }
+                append(character, pendingStart, index + 1, "literal", false, quoteStart);
+                lastSource = sources.length - 1;
+                index++;
+                pendingStart = index;
+                continue;
+            }
+            if (quote === '"' && character === '"') {
+                if (lastSource >= wordStart)
+                    sources[lastSource] = { ...sources[lastSource], end: index + 1 };
+                quote = undefined;
+                quoteStart = undefined;
+                index++;
+                pendingStart = index;
+                continue;
+            }
+            if (character === "\\") {
+                const next = text[index + 1];
+                if (next === undefined)
+                    fail();
+                if (next === "\n") {
+                    index += 2;
+                    pendingStart = index;
+                    continue;
+                }
+                if (quote === '"' && !'\\"$'.includes(next)) {
+                    append(character, pendingStart, index + 1, "literal", false, quoteStart);
+                    lastSource = sources.length - 1;
+                    index++;
+                    pendingStart = index;
+                    continue;
+                }
+                append(next, pendingStart, index + 2, "literal", true, quoteStart);
+                lastSource = sources.length - 1;
+                index += 2;
+                pendingStart = index;
+                continue;
+            }
+            if (quote === undefined && (character === '"' || character === "'")) {
+                quote = character;
+                quoteStart = index;
+                index++;
+                pendingStart = index;
+                continue;
+            }
+            if (character === "$") {
+                if (text[index + 1] === "(")
+                    fail();
+                const token = variableAt(text, index);
+                if (token === undefined)
+                    fail();
+                const normalizedStart = output.length;
+                for (let offset = 0; offset < token.length; offset++) {
+                    append(token[offset], offset === 0 ? pendingStart : index + offset, index + offset + 1, "variable", false, quoteStart);
+                    lastSource = sources.length - 1;
+                }
+                variables.push({
+                    start: normalizedStart,
+                    end: output.length,
+                    sourceStart: index,
+                    sourceEnd: index + token.length,
+                });
+                index += token.length;
+                pendingStart = index;
+                continue;
+            }
+            if (quote === undefined && character === "{" && isBraceExpansion(text, index))
+                fail();
+            append(character, pendingStart, index + 1, "literal", false, quoteStart);
+            lastSource = sources.length - 1;
+            index++;
+            pendingStart = index;
+        }
+        if (quote !== undefined)
+            fail();
+        words.push({ start: wordStart, end: output.length });
+    }
+    const shell = { text: output.join(""), sources, words, variables };
+    if (hasActiveShellNameGlob(shell))
+        fail();
+    return shell;
+}
+//# sourceMappingURL=shell-command-tokenizer.js.map

package/dist/guardrails/shell-command-tokenizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-command-tokenizer.js","sourceRoot":"","sources":["../../src/guardrails/shell-command-tokenizer.ts"],"names":[],"mappings":"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","sourcesContent":["import { hasActiveShellNameGlob } from \"./shell-command-name-glob.ts\";\n\nconst MAX_STATIC_SHELL_INPUT_CHARS = 64 * 1024;\nconst MAX_STATIC_SHELL_WORDS = 4_096;\ntype ShellQuote = '\"' | \"'\";\nexport interface ShellSourceRange {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly contentEnd: number;\n\treadonly quoteStart?: number;\n\treadonly kind: \"literal\" | \"variable\";\n\treadonly escaped: boolean;\n}\nexport interface StaticShellWord {\n\treadonly start: number;\n\treadonly end: number;\n}\nexport interface StaticShellVariable {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly sourceStart: number;\n\treadonly sourceEnd: number;\n}\nexport interface NormalizedStaticShell {\n\treadonly text: string;\n\treadonly sources: readonly ShellSourceRange[];\n\treadonly words: readonly StaticShellWord[];\n\treadonly variables: readonly StaticShellVariable[];\n}\nexport class StaticShellSyntaxError extends Error {\n\tconstructor() {\n\t\tsuper(\"shell command is dynamic or malformed; failing closed\");\n\t\tthis.name = \"StaticShellSyntaxError\";\n\t}\n}\nfunction fail(): never {\n\tthrow new StaticShellSyntaxError();\n}\nfunction isWordBoundary(character: string): boolean {\n\treturn /[\\s;&|()<>]/.test(character);\n}\n\nfunction variableAt(text: string, index: number): string | undefined {\n\tconst remainder = text.slice(index);\n\treturn /^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}/.exec(remainder)?.[0] ?? /^\\$[A-Za-z_][A-Za-z0-9_]*/.exec(remainder)?.[0];\n}\n\nfunction isBraceExpansion(text: string, index: number): boolean {\n\tconst close = text.indexOf(\"}\", index + 1);\n\tif (close < 0) return false;\n\tconst body = text.slice(index + 1, close);\n\treturn body.includes(\",\") || body.includes(\"..\");\n}\n\nexport function normalizeStaticShell(text: string): NormalizedStaticShell {\n\tif (text.length > MAX_STATIC_SHELL_INPUT_CHARS || text.includes(\"`\") || text.includes(\"<(\") || text.includes(\">(\"))\n\t\tfail();\n\tconst output: string[] = [];\n\tconst sources: ShellSourceRange[] = [];\n\tconst words: StaticShellWord[] = [];\n\tconst variables: StaticShellVariable[] = [];\n\tconst append = (\n\t\tcharacter: string,\n\t\tstart: number,\n\t\tend: number,\n\t\tkind: ShellSourceRange[\"kind\"],\n\t\tescaped: boolean,\n\t\tquoteStart?: number,\n\t): void => {\n\t\toutput.push(character);\n\t\tsources.push({ start, end, contentEnd: end, kind, escaped, ...(quoteStart === undefined ? {} : { quoteStart }) });\n\t};\n\tlet index = 0;\n\twhile (index < text.length) {\n\t\tif (isWordBoundary(text[index])) {\n\t\t\tappend(text[index], index, index + 1, \"literal\", false);\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (words.length >= MAX_STATIC_SHELL_WORDS) fail();\n\t\tconst wordStart = output.length;\n\t\tlet quote: ShellQuote | undefined;\n\t\tlet quoteStart: number | undefined;\n\t\tlet pendingStart = index;\n\t\tlet lastSource = -1;\n\t\twhile (index < text.length && (quote !== undefined || !isWordBoundary(text[index]))) {\n\t\t\tconst character = text[index];\n\t\t\tif (quote === \"'\") {\n\t\t\t\tif (character === \"'\") {\n\t\t\t\t\tif (lastSource >= wordStart) sources[lastSource] = { ...sources[lastSource], end: index + 1 };\n\t\t\t\t\tquote = undefined;\n\t\t\t\t\tquoteStart = undefined;\n\t\t\t\t\tindex++;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === '\"' && character === '\"') {\n\t\t\t\tif (lastSource >= wordStart) sources[lastSource] = { ...sources[lastSource], end: index + 1 };\n\t\t\t\tquote = undefined;\n\t\t\t\tquoteStart = undefined;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"\\\\\") {\n\t\t\t\tconst next = text[index + 1];\n\t\t\t\tif (next === undefined) fail();\n\t\t\t\tif (next === \"\\n\") {\n\t\t\t\t\tindex += 2;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (quote === '\"' && !'\\\\\"$'.includes(next)) {\n\t\t\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\t\tindex++;\n\t\t\t\t\tpendingStart = index;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tappend(next, pendingStart, index + 2, \"literal\", true, quoteStart);\n\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\tindex += 2;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === undefined && (character === '\"' || character === \"'\")) {\n\t\t\t\tquote = character;\n\t\t\t\tquoteStart = index;\n\t\t\t\tindex++;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"$\") {\n\t\t\t\tif (text[index + 1] === \"(\") fail();\n\t\t\t\tconst token = variableAt(text, index);\n\t\t\t\tif (token === undefined) fail();\n\t\t\t\tconst normalizedStart = output.length;\n\t\t\t\tfor (let offset = 0; offset < token.length; offset++) {\n\t\t\t\t\tappend(\n\t\t\t\t\t\ttoken[offset],\n\t\t\t\t\t\toffset === 0 ? pendingStart : index + offset,\n\t\t\t\t\t\tindex + offset + 1,\n\t\t\t\t\t\t\"variable\",\n\t\t\t\t\t\tfalse,\n\t\t\t\t\t\tquoteStart,\n\t\t\t\t\t);\n\t\t\t\t\tlastSource = sources.length - 1;\n\t\t\t\t}\n\t\t\t\tvariables.push({\n\t\t\t\t\tstart: normalizedStart,\n\t\t\t\t\tend: output.length,\n\t\t\t\t\tsourceStart: index,\n\t\t\t\t\tsourceEnd: index + token.length,\n\t\t\t\t});\n\t\t\t\tindex += token.length;\n\t\t\t\tpendingStart = index;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === undefined && character === \"{\" && isBraceExpansion(text, index)) fail();\n\t\t\tappend(character, pendingStart, index + 1, \"literal\", false, quoteStart);\n\t\t\tlastSource = sources.length - 1;\n\t\t\tindex++;\n\t\t\tpendingStart = index;\n\t\t}\n\t\tif (quote !== undefined) fail();\n\t\twords.push({ start: wordStart, end: output.length });\n\t}\n\tconst shell = { text: output.join(\"\"), sources, words, variables };\n\tif (hasActiveShellNameGlob(shell)) fail();\n\treturn shell;\n}\n"]}

package/dist/guardrails/shell-command-wrapper.d.ts

@@ -0,0 +1,18 @@
+export interface ShellCommandWrapperState {
+    readonly kind: "command" | "exec";
+    readonly options: boolean;
+    readonly pendingName?: boolean;
+    readonly lookup?: boolean;
+}
+export interface ShellCommandWrapperStep {
+    readonly state?: ShellCommandWrapperState;
+    readonly ambiguous?: boolean;
+    readonly optionEnd?: number;
+    readonly value?: boolean;
+    readonly target?: boolean;
+}
+/** Recognize only wrappers whose option grammar is modeled below. */
+export declare function shellCommandWrapper(commandName: string): ShellCommandWrapperState | undefined;
+/** Consume one wrapper argument without mistaking option values for command names. */
+export declare function consumeShellCommandWrapper(state: ShellCommandWrapperState, word: string): ShellCommandWrapperStep;
+//# sourceMappingURL=shell-command-wrapper.d.ts.map

package/dist/guardrails/shell-command-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-command-wrapper.d.ts","sourceRoot":"","sources":["../../src/guardrails/shell-command-wrapper.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAG7F;AAED,sFAAsF;AACtF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,wBAAwB,EAAE,IAAI,EAAE,MAAM,GAAG,uBAAuB,CA4BjH","sourcesContent":["export interface ShellCommandWrapperState {\n\treadonly kind: \"command\" | \"exec\";\n\treadonly options: boolean;\n\treadonly pendingName?: boolean;\n\treadonly lookup?: boolean;\n}\n\nexport interface ShellCommandWrapperStep {\n\treadonly state?: ShellCommandWrapperState;\n\treadonly ambiguous?: boolean;\n\treadonly optionEnd?: number;\n\treadonly value?: boolean;\n\treadonly target?: boolean;\n}\n\n/** Recognize only wrappers whose option grammar is modeled below. */\nexport function shellCommandWrapper(commandName: string): ShellCommandWrapperState | undefined {\n\tconst name = commandName.slice(commandName.lastIndexOf(\"/\") + 1).replace(/\\.exe$/i, \"\");\n\treturn name === \"command\" || name === \"exec\" ? { kind: name, options: true } : undefined;\n}\n\n/** Consume one wrapper argument without mistaking option values for command names. */\nexport function consumeShellCommandWrapper(state: ShellCommandWrapperState, word: string): ShellCommandWrapperStep {\n\tif (state.kind === \"command\") {\n\t\tif (state.lookup && (!state.options || !word.startsWith(\"-\") || word === \"-\")) {\n\t\t\treturn { value: true };\n\t\t}\n\t\tif (state.options && word === \"--\") return { state: { ...state, options: false }, optionEnd: word.length };\n\t\tif (state.options && word.startsWith(\"-\") && word !== \"-\") {\n\t\t\tif (!/^-[pVv]+$/.test(word)) return { ambiguous: true };\n\t\t\treturn {\n\t\t\t\tstate: /[Vv]/.test(word) ? { ...state, lookup: true } : state,\n\t\t\t\toptionEnd: word.length,\n\t\t\t};\n\t\t}\n\t\treturn state.lookup ? { value: true } : { target: true };\n\t}\n\tif (state.pendingName) return { state: { ...state, pendingName: false }, value: true };\n\tif (state.options && word === \"--\") return { state: { ...state, options: false }, optionEnd: word.length };\n\tif (state.options && word.startsWith(\"-\") && word !== \"-\") {\n\t\tfor (let index = 1; index < word.length; index++) {\n\t\t\tif (word[index] === \"c\" || word[index] === \"l\") continue;\n\t\t\tif (word[index] !== \"a\") return { ambiguous: true };\n\t\t\treturn index + 1 < word.length\n\t\t\t\t? { state, optionEnd: index + 1 }\n\t\t\t\t: { state: { ...state, pendingName: true }, optionEnd: word.length };\n\t\t}\n\t\treturn { state, optionEnd: word.length };\n\t}\n\treturn { target: true };\n}\n"]}

package/dist/guardrails/shell-command-wrapper.js

@@ -0,0 +1,42 @@
+/** Recognize only wrappers whose option grammar is modeled below. */
+export function shellCommandWrapper(commandName) {
+    const name = commandName.slice(commandName.lastIndexOf("/") + 1).replace(/\.exe$/i, "");
+    return name === "command" || name === "exec" ? { kind: name, options: true } : undefined;
+}
+/** Consume one wrapper argument without mistaking option values for command names. */
+export function consumeShellCommandWrapper(state, word) {
+    if (state.kind === "command") {
+        if (state.lookup && (!state.options || !word.startsWith("-") || word === "-")) {
+            return { value: true };
+        }
+        if (state.options && word === "--")
+            return { state: { ...state, options: false }, optionEnd: word.length };
+        if (state.options && word.startsWith("-") && word !== "-") {
+            if (!/^-[pVv]+$/.test(word))
+                return { ambiguous: true };
+            return {
+                state: /[Vv]/.test(word) ? { ...state, lookup: true } : state,
+                optionEnd: word.length,
+            };
+        }
+        return state.lookup ? { value: true } : { target: true };
+    }
+    if (state.pendingName)
+        return { state: { ...state, pendingName: false }, value: true };
+    if (state.options && word === "--")
+        return { state: { ...state, options: false }, optionEnd: word.length };
+    if (state.options && word.startsWith("-") && word !== "-") {
+        for (let index = 1; index < word.length; index++) {
+            if (word[index] === "c" || word[index] === "l")
+                continue;
+            if (word[index] !== "a")
+                return { ambiguous: true };
+            return index + 1 < word.length
+                ? { state, optionEnd: index + 1 }
+                : { state: { ...state, pendingName: true }, optionEnd: word.length };
+        }
+        return { state, optionEnd: word.length };
+    }
+    return { target: true };
+}
+//# sourceMappingURL=shell-command-wrapper.js.map

package/dist/guardrails/shell-command-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-command-wrapper.js","sourceRoot":"","sources":["../../src/guardrails/shell-command-wrapper.ts"],"names":[],"mappings":"AAeA,qEAAqE;AACrE,MAAM,UAAU,mBAAmB,CAAC,WAAmB,EAAwC;IAC9F,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACxF,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACzF;AAED,sFAAsF;AACtF,MAAM,UAAU,0BAA0B,CAAC,KAA+B,EAAE,IAAY,EAA2B;IAClH,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC/E,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3G,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YAC3D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YACxD,OAAO;gBACN,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK;gBAC7D,SAAS,EAAE,IAAI,CAAC,MAAM;aACtB,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,CAAC,WAAW;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACvF,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAC3G,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QAC3D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;YAClD,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;gBAAE,SAAS;YACzD,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;gBAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YACpD,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;gBAC7B,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,EAAE;gBACjC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QACvE,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAAA,CACxB","sourcesContent":["export interface ShellCommandWrapperState {\n\treadonly kind: \"command\" | \"exec\";\n\treadonly options: boolean;\n\treadonly pendingName?: boolean;\n\treadonly lookup?: boolean;\n}\n\nexport interface ShellCommandWrapperStep {\n\treadonly state?: ShellCommandWrapperState;\n\treadonly ambiguous?: boolean;\n\treadonly optionEnd?: number;\n\treadonly value?: boolean;\n\treadonly target?: boolean;\n}\n\n/** Recognize only wrappers whose option grammar is modeled below. */\nexport function shellCommandWrapper(commandName: string): ShellCommandWrapperState | undefined {\n\tconst name = commandName.slice(commandName.lastIndexOf(\"/\") + 1).replace(/\\.exe$/i, \"\");\n\treturn name === \"command\" || name === \"exec\" ? { kind: name, options: true } : undefined;\n}\n\n/** Consume one wrapper argument without mistaking option values for command names. */\nexport function consumeShellCommandWrapper(state: ShellCommandWrapperState, word: string): ShellCommandWrapperStep {\n\tif (state.kind === \"command\") {\n\t\tif (state.lookup && (!state.options || !word.startsWith(\"-\") || word === \"-\")) {\n\t\t\treturn { value: true };\n\t\t}\n\t\tif (state.options && word === \"--\") return { state: { ...state, options: false }, optionEnd: word.length };\n\t\tif (state.options && word.startsWith(\"-\") && word !== \"-\") {\n\t\t\tif (!/^-[pVv]+$/.test(word)) return { ambiguous: true };\n\t\t\treturn {\n\t\t\t\tstate: /[Vv]/.test(word) ? { ...state, lookup: true } : state,\n\t\t\t\toptionEnd: word.length,\n\t\t\t};\n\t\t}\n\t\treturn state.lookup ? { value: true } : { target: true };\n\t}\n\tif (state.pendingName) return { state: { ...state, pendingName: false }, value: true };\n\tif (state.options && word === \"--\") return { state: { ...state, options: false }, optionEnd: word.length };\n\tif (state.options && word.startsWith(\"-\") && word !== \"-\") {\n\t\tfor (let index = 1; index < word.length; index++) {\n\t\t\tif (word[index] === \"c\" || word[index] === \"l\") continue;\n\t\t\tif (word[index] !== \"a\") return { ambiguous: true };\n\t\t\treturn index + 1 < word.length\n\t\t\t\t? { state, optionEnd: index + 1 }\n\t\t\t\t: { state: { ...state, pendingName: true }, optionEnd: word.length };\n\t\t}\n\t\treturn { state, optionEnd: word.length };\n\t}\n\treturn { target: true };\n}\n"]}

package/dist/guardrails/verified-executor.d.ts

@@ -0,0 +1,65 @@
+import type { EvidenceCommandDescriptor, EvidenceExecutor, EvidenceReceipt, EvidenceReceiptDisposition, ReplayEvent, Sha256Hex, WorkspaceScope } from "../types/evidence.ts";
+import { type CommandHmacBinder } from "./evidence-attestation.ts";
+import type { AlreadyRedactedOutputBytes } from "./evidence-receipt.ts";
+import type { EvidenceReceiptStore } from "./evidence-receipt-store.ts";
+import type { EvidenceGateOptions, ReplayLedgerManager } from "./evidence-system.ts";
+export type VerifiedEvidenceExecutionOutcome = EvidenceReceiptDisposition & {
+    readonly alreadyRedactedOutput: AlreadyRedactedOutputBytes;
+};
+export interface VerifiedEvidenceExecutionRequest {
+    readonly goalId: string;
+    readonly laneId?: string;
+    readonly claim: string;
+    readonly command: EvidenceCommandDescriptor;
+    readonly cwd: string;
+    readonly timeoutMs: number | null;
+    readonly workspaceScope: WorkspaceScope;
+    readonly executor: EvidenceExecutor;
+    readonly toolCallId?: string;
+    readonly execute: () => Promise<VerifiedEvidenceExecutionOutcome>;
+}
+export interface VerifiedEvidenceMetadata {
+    readonly receiptId: string;
+    readonly receiptSchemaVersion: 3;
+    readonly receiptCommandSha256: Sha256Hex;
+    readonly receiptLaneId?: string;
+    readonly timestamp: string;
+}
+export interface VerifiedEvidenceExecutionResult {
+    readonly receipt: EvidenceReceipt;
+    readonly receiptPath: string;
+    readonly evidenceMetadata: VerifiedEvidenceMetadata;
+}
+export interface VerifiedEvidenceExecutorOptions {
+    readonly store: EvidenceReceiptStore;
+    readonly ledger: ReplayLedgerManager;
+    readonly now?: () => Date;
+    readonly receiptIdFactory?: () => string;
+    readonly commandAttestationBinder?: CommandHmacBinder;
+}
+export declare class VerifiedEvidenceExecutorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Execute one caller-provided verification operation between two scoped workspace snapshots,
+ * then persist a replay-bound immutable receipt. The callback must normalize process
+ * completion and provide already-redacted bounded output bytes.
+ */
+export declare class VerifiedEvidenceExecutor {
+    private readonly store;
+    private readonly ledger;
+    private readonly now;
+    private readonly receiptIdFactory;
+    private readonly commandAttestationBinder;
+    private readonly attestedCommands;
+    constructor(options: VerifiedEvidenceExecutorOptions);
+    readonly resolveReceipt: (receiptId: string) => EvidenceReceipt;
+    readonly resolveLedgerEvent: (seq: number) => ReplayEvent | undefined;
+    readonly resolveVerifiedLedgerSnapshot: () => import("../types/evidence.ts").VerifiedReplayLedgerSnapshot;
+    readonly resolveAttestedCommand: (receiptId: string) => EvidenceCommandDescriptor | undefined;
+    /** Latest relevant `workspace_mutation` seq from this executor's own replay ledger. */
+    readonly resolveLatestWorkspaceMutationSeq: (scope: WorkspaceScope) => number | null;
+    createGateOptions(): Pick<EvidenceGateOptions, "resolveReceipt" | "resolveLedgerEvent" | "resolveVerifiedLedgerSnapshot" | "captureWorkspaceFingerprint" | "resolveLatestWorkspaceMutationSeq" | "commandAttestationBinder" | "resolveAttestedCommand">;
+    execute(request: VerifiedEvidenceExecutionRequest): Promise<VerifiedEvidenceExecutionResult>;
+}
+//# sourceMappingURL=verified-executor.d.ts.map

package/dist/guardrails/verified-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verified-executor.d.ts","sourceRoot":"","sources":["../../src/guardrails/verified-executor.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type {\n\tEvidenceCommandDescriptor,\n\tEvidenceExecutor,\n\tEvidenceReceipt,\n\tEvidenceReceiptDisposition,\n\tReplayEvent,\n\tSha256Hex,\n\tWorkspaceScope,\n} from \"../types/evidence.ts\";\nimport { redactCommandDescriptor } from \"./command-redaction.ts\";\nimport { type CommandHmacBinder, createCommandHmacBinder } from \"./evidence-attestation.ts\";\nimport type { AlreadyRedactedOutputBytes } from \"./evidence-receipt.ts\";\nimport {\n\tcomputeEvidenceCommandSha256,\n\tcreateEvidenceReceipt,\n\tevidenceReceiptReplayPayload,\n\tisSafeEvidenceReceiptId,\n\tparseSha256Hex,\n\twithEvidenceReceiptEnvelope,\n} from \"./evidence-receipt.ts\";\nimport type { EvidenceReceiptStore } from \"./evidence-receipt-store.ts\";\nimport type { EvidenceGateOptions, ReplayLedgerManager } from \"./evidence-system.ts\";\nimport { latestRelevantWorkspaceMutationSeq } from \"./evidence-system.ts\";\nimport { captureWorkspaceFingerprint } from \"./workspace-fingerprint.ts\";\n\nexport type VerifiedEvidenceExecutionOutcome = EvidenceReceiptDisposition & {\n\treadonly alreadyRedactedOutput: AlreadyRedactedOutputBytes;\n};\n\nexport interface VerifiedEvidenceExecutionRequest {\n\treadonly goalId: string;\n\treadonly laneId?: string;\n\treadonly claim: string;\n\treadonly command: EvidenceCommandDescriptor;\n\treadonly cwd: string;\n\treadonly timeoutMs: number | null;\n\treadonly workspaceScope: WorkspaceScope;\n\treadonly executor: EvidenceExecutor;\n\treadonly toolCallId?: string;\n\treadonly execute: () => Promise<VerifiedEvidenceExecutionOutcome>;\n}\n\nexport interface VerifiedEvidenceMetadata {\n\treadonly receiptId: string;\n\treadonly receiptSchemaVersion: 3;\n\treadonly receiptCommandSha256: Sha256Hex;\n\treadonly receiptLaneId?: string;\n\treadonly timestamp: string;\n}\n\nexport interface VerifiedEvidenceExecutionResult {\n\treadonly receipt: EvidenceReceipt;\n\treadonly receiptPath: string;\n\treadonly evidenceMetadata: VerifiedEvidenceMetadata;\n}\n\nexport interface VerifiedEvidenceExecutorOptions {\n\treadonly store: EvidenceReceiptStore;\n\treadonly ledger: ReplayLedgerManager;\n\treadonly now?: () => Date;\n\treadonly receiptIdFactory?: () => string;\n\treadonly commandAttestationBinder?: CommandHmacBinder;\n}\n\nexport class VerifiedEvidenceExecutorError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"VerifiedEvidenceExecutorError\";\n\t}\n}\n\nconst EVIDENCE_EXECUTORS: ReadonlySet<string> = new Set([\"bash-tool\", \"ci-runner\", \"mcp\", \"internal\"]);\n\n/**\n * Fail-closed parse of the callback-reported disposition. Only these two facts\n * (plus the redacted output bytes) are accepted from the callback; a contradictory\n * pair is rejected rather than repaired.\n */\nfunction parseExecutionDisposition(status: unknown, exitCode: unknown): EvidenceReceiptDisposition {\n\tif (status === \"passed\" && exitCode === 0) return { status: \"passed\", exitCode: 0 };\n\tif (status === \"failed\" && Number.isSafeInteger(exitCode) && exitCode !== 0) {\n\t\treturn { status: \"failed\", exitCode: exitCode as number };\n\t}\n\tif ((status === \"timeout\" || status === \"aborted\") && exitCode === null) {\n\t\treturn { status, exitCode: null };\n\t}\n\tthrow new VerifiedEvidenceExecutorError(\"execution callback returned an invalid disposition\");\n}\n\nfunction assertRequestText(value: unknown, label: string): void {\n\tif (typeof value !== \"string\" || value.length === 0 || value.includes(\"\\0\")) {\n\t\tthrow new VerifiedEvidenceExecutorError(`${label} must be a non-empty string without NUL bytes`);\n\t}\n}\n\nfunction validateRequest(request: VerifiedEvidenceExecutionRequest): void {\n\tassertRequestText(request.goalId, \"goalId\");\n\tif (request.laneId !== undefined) assertRequestText(request.laneId, \"laneId\");\n\tassertRequestText(request.claim, \"claim\");\n\tassertRequestText(request.cwd, \"cwd\");\n\tif (request.toolCallId !== undefined) assertRequestText(request.toolCallId, \"toolCallId\");\n\tif (request.timeoutMs !== null && (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0)) {\n\t\tthrow new VerifiedEvidenceExecutorError(\"timeoutMs must be null or a positive safe integer\");\n\t}\n\tif (!EVIDENCE_EXECUTORS.has(request.executor)) {\n\t\tthrow new VerifiedEvidenceExecutorError(\"executor is invalid\");\n\t}\n\tif (typeof request.execute !== \"function\") {\n\t\tthrow new VerifiedEvidenceExecutorError(\"execute must be a function\");\n\t}\n}\n\n/**\n * Execute one caller-provided verification operation between two scoped workspace snapshots,\n * then persist a replay-bound immutable receipt. The callback must normalize process\n * completion and provide already-redacted bounded output bytes.\n */\nexport class VerifiedEvidenceExecutor {\n\tprivate readonly store: EvidenceReceiptStore;\n\tprivate readonly ledger: ReplayLedgerManager;\n\tprivate readonly now: () => Date;\n\tprivate readonly receiptIdFactory: () => string;\n\tprivate readonly commandAttestationBinder: CommandHmacBinder;\n\tprivate readonly attestedCommands = new Map<string, EvidenceCommandDescriptor>();\n\n\tconstructor(options: VerifiedEvidenceExecutorOptions) {\n\t\tthis.store = options.store;\n\t\tthis.ledger = options.ledger;\n\t\tthis.now = options.now ?? (() => new Date());\n\t\tthis.receiptIdFactory = options.receiptIdFactory ?? randomUUID;\n\t\tthis.commandAttestationBinder = options.commandAttestationBinder ?? createCommandHmacBinder();\n\t}\n\n\treadonly resolveReceipt = (receiptId: string): EvidenceReceipt => this.store.read(receiptId);\n\n\treadonly resolveLedgerEvent = (seq: number): ReplayEvent | undefined =>\n\t\tthis.ledger.getEvents().find((event) => event.seq === seq);\n\n\treadonly resolveVerifiedLedgerSnapshot = () => this.ledger.getVerifiedSnapshot();\n\n\treadonly resolveAttestedCommand = (receiptId: string): EvidenceCommandDescriptor | undefined => {\n\t\tconst command = this.attestedCommands.get(receiptId);\n\t\treturn command === undefined ? undefined : structuredClone(command);\n\t};\n\n\t/** Latest relevant `workspace_mutation` seq from this executor's own replay ledger. */\n\treadonly resolveLatestWorkspaceMutationSeq = (scope: WorkspaceScope): number | null =>\n\t\tlatestRelevantWorkspaceMutationSeq(this.ledger.getEvents(), scope);\n\n\tcreateGateOptions(): Pick<\n\t\tEvidenceGateOptions,\n\t\t| \"resolveReceipt\"\n\t\t| \"resolveLedgerEvent\"\n\t\t| \"resolveVerifiedLedgerSnapshot\"\n\t\t| \"captureWorkspaceFingerprint\"\n\t\t| \"resolveLatestWorkspaceMutationSeq\"\n\t\t| \"commandAttestationBinder\"\n\t\t| \"resolveAttestedCommand\"\n\t> {\n\t\treturn {\n\t\t\tresolveReceipt: this.resolveReceipt,\n\t\t\tresolveLedgerEvent: this.resolveLedgerEvent,\n\t\t\tresolveVerifiedLedgerSnapshot: this.resolveVerifiedLedgerSnapshot,\n\t\t\tcaptureWorkspaceFingerprint,\n\t\t\tresolveLatestWorkspaceMutationSeq: this.resolveLatestWorkspaceMutationSeq,\n\t\t\tcommandAttestationBinder: this.commandAttestationBinder,\n\t\t\tresolveAttestedCommand: this.resolveAttestedCommand,\n\t\t};\n\t}\n\n\tasync execute(request: VerifiedEvidenceExecutionRequest): Promise<VerifiedEvidenceExecutionResult> {\n\t\tvalidateRequest(request);\n\t\tconst ledgerGoalId = this.ledger.getLedger().goalId;\n\t\tif (request.goalId !== ledgerGoalId) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification goalId does not match the replay ledger\");\n\t\t}\n\t\tconst receiptId = this.receiptIdFactory();\n\t\tif (!isSafeEvidenceReceiptId(receiptId)) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"receiptIdFactory returned an unsafe receipt ID\");\n\t\t}\n\t\t// Tokenize the persisted representation and bind the ORIGINAL command under the\n\t\t// internal process key BEFORE any side effect; unrepresentable or oversize\n\t\t// redaction metadata fails closed here. The original is never persisted.\n\t\tconst redaction = redactCommandDescriptor(request.command);\n\t\tconst commandBinding = this.commandAttestationBinder.bind(request.command);\n\t\tconst receiptCommandSha256 = computeEvidenceCommandSha256(redaction.command);\n\t\tconst workspaceBefore = captureWorkspaceFingerprint(request.workspaceScope);\n\t\tconst started = this.now();\n\t\tconst startedMs = started.getTime();\n\t\tif (!Number.isSafeInteger(startedMs)) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification clock produced an invalid start time\");\n\t\t}\n\t\tconst outcome = await request.execute();\n\t\t// Independent-review P3: accept ONLY the disposition and the already-redacted\n\t\t// output bytes from the callback. Every other receipt field is executor-captured\n\t\t// provenance that a callback outcome object must never be able to override.\n\t\tconst { status, exitCode, alreadyRedactedOutput } = outcome;\n\t\tconst disposition = parseExecutionDisposition(status, exitCode);\n\t\tconst finished = this.now();\n\t\tconst finishedMs = finished.getTime();\n\t\tif (!Number.isSafeInteger(finishedMs) || finishedMs < startedMs) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification clock produced an invalid execution interval\");\n\t\t}\n\t\tconst workspaceAfter = captureWorkspaceFingerprint(request.workspaceScope);\n\t\tconst receipt = createEvidenceReceipt({\n\t\t\treceiptId,\n\t\t\tgoalId: request.goalId,\n\t\t\t...(request.laneId !== undefined ? { laneId: request.laneId } : {}),\n\t\t\tclaim: request.claim,\n\t\t\tcommand: redaction.command,\n\t\t\tcommandRedaction: redaction.summary,\n\t\t\tcommandBinding,\n\t\t\tcwd: request.cwd,\n\t\t\ttimeoutMs: request.timeoutMs,\n\t\t\tstartedAt: started.toISOString(),\n\t\t\tfinishedAt: finished.toISOString(),\n\t\t\tdurationMs: finishedMs - startedMs,\n\t\t\tworkspaceBefore,\n\t\t\tworkspaceAfter,\n\t\t\texecutor: request.executor,\n\t\t\t...disposition,\n\t\t\talreadyRedactedOutput,\n\t\t\t...(request.toolCallId !== undefined ? { toolCallId: request.toolCallId } : {}),\n\t\t});\n\t\tconst event = this.ledger.append({\n\t\t\ttype: \"evidence_receipt\",\n\t\t\tgoalId: request.goalId,\n\t\t\t...(request.laneId !== undefined ? { laneId: request.laneId } : {}),\n\t\t\tpayload: evidenceReceiptReplayPayload(receipt),\n\t\t});\n\t\tthis.ledger.persist();\n\t\tconst boundReceipt = withEvidenceReceiptEnvelope(receipt, {\n\t\t\tledgerBinding: { seq: event.seq, eventHash: parseSha256Hex(event.eventHash, \"ledger eventHash\") },\n\t\t});\n\t\tconst receiptPath = this.store.write(boundReceipt);\n\t\tthis.attestedCommands.set(receiptId, structuredClone(request.command));\n\t\treturn {\n\t\t\treceipt: boundReceipt,\n\t\t\treceiptPath,\n\t\t\tevidenceMetadata: {\n\t\t\t\treceiptId,\n\t\t\t\treceiptSchemaVersion: 3,\n\t\t\t\treceiptCommandSha256,\n\t\t\t\t...(request.laneId !== undefined ? { receiptLaneId: request.laneId } : {}),\n\t\t\t\ttimestamp: finished.toISOString(),\n\t\t\t},\n\t\t};\n\t}\n}\n"]}

package/dist/guardrails/verified-executor.js

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { redactCommandDescriptor } from "./command-redaction.js";
+import { createCommandHmacBinder } from "./evidence-attestation.js";
+import { computeEvidenceCommandSha256, createEvidenceReceipt, evidenceReceiptReplayPayload, isSafeEvidenceReceiptId, parseSha256Hex, withEvidenceReceiptEnvelope, } from "./evidence-receipt.js";
+import { latestRelevantWorkspaceMutationSeq } from "./evidence-system.js";
+import { captureWorkspaceFingerprint } from "./workspace-fingerprint.js";
+export class VerifiedEvidenceExecutorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VerifiedEvidenceExecutorError";
+    }
+}
+const EVIDENCE_EXECUTORS = new Set(["bash-tool", "ci-runner", "mcp", "internal"]);
+/**
+ * Fail-closed parse of the callback-reported disposition. Only these two facts
+ * (plus the redacted output bytes) are accepted from the callback; a contradictory
+ * pair is rejected rather than repaired.
+ */
+function parseExecutionDisposition(status, exitCode) {
+    if (status === "passed" && exitCode === 0)
+        return { status: "passed", exitCode: 0 };
+    if (status === "failed" && Number.isSafeInteger(exitCode) && exitCode !== 0) {
+        return { status: "failed", exitCode: exitCode };
+    }
+    if ((status === "timeout" || status === "aborted") && exitCode === null) {
+        return { status, exitCode: null };
+    }
+    throw new VerifiedEvidenceExecutorError("execution callback returned an invalid disposition");
+}
+function assertRequestText(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new VerifiedEvidenceExecutorError(`${label} must be a non-empty string without NUL bytes`);
+    }
+}
+function validateRequest(request) {
+    assertRequestText(request.goalId, "goalId");
+    if (request.laneId !== undefined)
+        assertRequestText(request.laneId, "laneId");
+    assertRequestText(request.claim, "claim");
+    assertRequestText(request.cwd, "cwd");
+    if (request.toolCallId !== undefined)
+        assertRequestText(request.toolCallId, "toolCallId");
+    if (request.timeoutMs !== null && (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0)) {
+        throw new VerifiedEvidenceExecutorError("timeoutMs must be null or a positive safe integer");
+    }
+    if (!EVIDENCE_EXECUTORS.has(request.executor)) {
+        throw new VerifiedEvidenceExecutorError("executor is invalid");
+    }
+    if (typeof request.execute !== "function") {
+        throw new VerifiedEvidenceExecutorError("execute must be a function");
+    }
+}
+/**
+ * Execute one caller-provided verification operation between two scoped workspace snapshots,
+ * then persist a replay-bound immutable receipt. The callback must normalize process
+ * completion and provide already-redacted bounded output bytes.
+ */
+export class VerifiedEvidenceExecutor {
+    store;
+    ledger;
+    now;
+    receiptIdFactory;
+    commandAttestationBinder;
+    attestedCommands = new Map();
+    constructor(options) {
+        this.store = options.store;
+        this.ledger = options.ledger;
+        this.now = options.now ?? (() => new Date());
+        this.receiptIdFactory = options.receiptIdFactory ?? randomUUID;
+        this.commandAttestationBinder = options.commandAttestationBinder ?? createCommandHmacBinder();
+    }
+    resolveReceipt = (receiptId) => this.store.read(receiptId);
+    resolveLedgerEvent = (seq) => this.ledger.getEvents().find((event) => event.seq === seq);
+    resolveVerifiedLedgerSnapshot = () => this.ledger.getVerifiedSnapshot();
+    resolveAttestedCommand = (receiptId) => {
+        const command = this.attestedCommands.get(receiptId);
+        return command === undefined ? undefined : structuredClone(command);
+    };
+    /** Latest relevant `workspace_mutation` seq from this executor's own replay ledger. */
+    resolveLatestWorkspaceMutationSeq = (scope) => latestRelevantWorkspaceMutationSeq(this.ledger.getEvents(), scope);
+    createGateOptions() {
+        return {
+            resolveReceipt: this.resolveReceipt,
+            resolveLedgerEvent: this.resolveLedgerEvent,
+            resolveVerifiedLedgerSnapshot: this.resolveVerifiedLedgerSnapshot,
+            captureWorkspaceFingerprint,
+            resolveLatestWorkspaceMutationSeq: this.resolveLatestWorkspaceMutationSeq,
+            commandAttestationBinder: this.commandAttestationBinder,
+            resolveAttestedCommand: this.resolveAttestedCommand,
+        };
+    }
+    async execute(request) {
+        validateRequest(request);
+        const ledgerGoalId = this.ledger.getLedger().goalId;
+        if (request.goalId !== ledgerGoalId) {
+            throw new VerifiedEvidenceExecutorError("verification goalId does not match the replay ledger");
+        }
+        const receiptId = this.receiptIdFactory();
+        if (!isSafeEvidenceReceiptId(receiptId)) {
+            throw new VerifiedEvidenceExecutorError("receiptIdFactory returned an unsafe receipt ID");
+        }
+        // Tokenize the persisted representation and bind the ORIGINAL command under the
+        // internal process key BEFORE any side effect; unrepresentable or oversize
+        // redaction metadata fails closed here. The original is never persisted.
+        const redaction = redactCommandDescriptor(request.command);
+        const commandBinding = this.commandAttestationBinder.bind(request.command);
+        const receiptCommandSha256 = computeEvidenceCommandSha256(redaction.command);
+        const workspaceBefore = captureWorkspaceFingerprint(request.workspaceScope);
+        const started = this.now();
+        const startedMs = started.getTime();
+        if (!Number.isSafeInteger(startedMs)) {
+            throw new VerifiedEvidenceExecutorError("verification clock produced an invalid start time");
+        }
+        const outcome = await request.execute();
+        // Independent-review P3: accept ONLY the disposition and the already-redacted
+        // output bytes from the callback. Every other receipt field is executor-captured
+        // provenance that a callback outcome object must never be able to override.
+        const { status, exitCode, alreadyRedactedOutput } = outcome;
+        const disposition = parseExecutionDisposition(status, exitCode);
+        const finished = this.now();
+        const finishedMs = finished.getTime();
+        if (!Number.isSafeInteger(finishedMs) || finishedMs < startedMs) {
+            throw new VerifiedEvidenceExecutorError("verification clock produced an invalid execution interval");
+        }
+        const workspaceAfter = captureWorkspaceFingerprint(request.workspaceScope);
+        const receipt = createEvidenceReceipt({
+            receiptId,
+            goalId: request.goalId,
+            ...(request.laneId !== undefined ? { laneId: request.laneId } : {}),
+            claim: request.claim,
+            command: redaction.command,
+            commandRedaction: redaction.summary,
+            commandBinding,
+            cwd: request.cwd,
+            timeoutMs: request.timeoutMs,
+            startedAt: started.toISOString(),
+            finishedAt: finished.toISOString(),
+            durationMs: finishedMs - startedMs,
+            workspaceBefore,
+            workspaceAfter,
+            executor: request.executor,
+            ...disposition,
+            alreadyRedactedOutput,
+            ...(request.toolCallId !== undefined ? { toolCallId: request.toolCallId } : {}),
+        });
+        const event = this.ledger.append({
+            type: "evidence_receipt",
+            goalId: request.goalId,
+            ...(request.laneId !== undefined ? { laneId: request.laneId } : {}),
+            payload: evidenceReceiptReplayPayload(receipt),
+        });
+        this.ledger.persist();
+        const boundReceipt = withEvidenceReceiptEnvelope(receipt, {
+            ledgerBinding: { seq: event.seq, eventHash: parseSha256Hex(event.eventHash, "ledger eventHash") },
+        });
+        const receiptPath = this.store.write(boundReceipt);
+        this.attestedCommands.set(receiptId, structuredClone(request.command));
+        return {
+            receipt: boundReceipt,
+            receiptPath,
+            evidenceMetadata: {
+                receiptId,
+                receiptSchemaVersion: 3,
+                receiptCommandSha256,
+                ...(request.laneId !== undefined ? { receiptLaneId: request.laneId } : {}),
+                timestamp: finished.toISOString(),
+            },
+        };
+    }
+}
+//# sourceMappingURL=verified-executor.js.map

package/dist/guardrails/verified-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verified-executor.js","sourceRoot":"","sources":["../../src/guardrails/verified-executor.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type {\n\tEvidenceCommandDescriptor,\n\tEvidenceExecutor,\n\tEvidenceReceipt,\n\tEvidenceReceiptDisposition,\n\tReplayEvent,\n\tSha256Hex,\n\tWorkspaceScope,\n} from \"../types/evidence.ts\";\nimport { redactCommandDescriptor } from \"./command-redaction.ts\";\nimport { type CommandHmacBinder, createCommandHmacBinder } from \"./evidence-attestation.ts\";\nimport type { AlreadyRedactedOutputBytes } from \"./evidence-receipt.ts\";\nimport {\n\tcomputeEvidenceCommandSha256,\n\tcreateEvidenceReceipt,\n\tevidenceReceiptReplayPayload,\n\tisSafeEvidenceReceiptId,\n\tparseSha256Hex,\n\twithEvidenceReceiptEnvelope,\n} from \"./evidence-receipt.ts\";\nimport type { EvidenceReceiptStore } from \"./evidence-receipt-store.ts\";\nimport type { EvidenceGateOptions, ReplayLedgerManager } from \"./evidence-system.ts\";\nimport { latestRelevantWorkspaceMutationSeq } from \"./evidence-system.ts\";\nimport { captureWorkspaceFingerprint } from \"./workspace-fingerprint.ts\";\n\nexport type VerifiedEvidenceExecutionOutcome = EvidenceReceiptDisposition & {\n\treadonly alreadyRedactedOutput: AlreadyRedactedOutputBytes;\n};\n\nexport interface VerifiedEvidenceExecutionRequest {\n\treadonly goalId: string;\n\treadonly laneId?: string;\n\treadonly claim: string;\n\treadonly command: EvidenceCommandDescriptor;\n\treadonly cwd: string;\n\treadonly timeoutMs: number | null;\n\treadonly workspaceScope: WorkspaceScope;\n\treadonly executor: EvidenceExecutor;\n\treadonly toolCallId?: string;\n\treadonly execute: () => Promise<VerifiedEvidenceExecutionOutcome>;\n}\n\nexport interface VerifiedEvidenceMetadata {\n\treadonly receiptId: string;\n\treadonly receiptSchemaVersion: 3;\n\treadonly receiptCommandSha256: Sha256Hex;\n\treadonly receiptLaneId?: string;\n\treadonly timestamp: string;\n}\n\nexport interface VerifiedEvidenceExecutionResult {\n\treadonly receipt: EvidenceReceipt;\n\treadonly receiptPath: string;\n\treadonly evidenceMetadata: VerifiedEvidenceMetadata;\n}\n\nexport interface VerifiedEvidenceExecutorOptions {\n\treadonly store: EvidenceReceiptStore;\n\treadonly ledger: ReplayLedgerManager;\n\treadonly now?: () => Date;\n\treadonly receiptIdFactory?: () => string;\n\treadonly commandAttestationBinder?: CommandHmacBinder;\n}\n\nexport class VerifiedEvidenceExecutorError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"VerifiedEvidenceExecutorError\";\n\t}\n}\n\nconst EVIDENCE_EXECUTORS: ReadonlySet<string> = new Set([\"bash-tool\", \"ci-runner\", \"mcp\", \"internal\"]);\n\n/**\n * Fail-closed parse of the callback-reported disposition. Only these two facts\n * (plus the redacted output bytes) are accepted from the callback; a contradictory\n * pair is rejected rather than repaired.\n */\nfunction parseExecutionDisposition(status: unknown, exitCode: unknown): EvidenceReceiptDisposition {\n\tif (status === \"passed\" && exitCode === 0) return { status: \"passed\", exitCode: 0 };\n\tif (status === \"failed\" && Number.isSafeInteger(exitCode) && exitCode !== 0) {\n\t\treturn { status: \"failed\", exitCode: exitCode as number };\n\t}\n\tif ((status === \"timeout\" || status === \"aborted\") && exitCode === null) {\n\t\treturn { status, exitCode: null };\n\t}\n\tthrow new VerifiedEvidenceExecutorError(\"execution callback returned an invalid disposition\");\n}\n\nfunction assertRequestText(value: unknown, label: string): void {\n\tif (typeof value !== \"string\" || value.length === 0 || value.includes(\"\\0\")) {\n\t\tthrow new VerifiedEvidenceExecutorError(`${label} must be a non-empty string without NUL bytes`);\n\t}\n}\n\nfunction validateRequest(request: VerifiedEvidenceExecutionRequest): void {\n\tassertRequestText(request.goalId, \"goalId\");\n\tif (request.laneId !== undefined) assertRequestText(request.laneId, \"laneId\");\n\tassertRequestText(request.claim, \"claim\");\n\tassertRequestText(request.cwd, \"cwd\");\n\tif (request.toolCallId !== undefined) assertRequestText(request.toolCallId, \"toolCallId\");\n\tif (request.timeoutMs !== null && (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0)) {\n\t\tthrow new VerifiedEvidenceExecutorError(\"timeoutMs must be null or a positive safe integer\");\n\t}\n\tif (!EVIDENCE_EXECUTORS.has(request.executor)) {\n\t\tthrow new VerifiedEvidenceExecutorError(\"executor is invalid\");\n\t}\n\tif (typeof request.execute !== \"function\") {\n\t\tthrow new VerifiedEvidenceExecutorError(\"execute must be a function\");\n\t}\n}\n\n/**\n * Execute one caller-provided verification operation between two scoped workspace snapshots,\n * then persist a replay-bound immutable receipt. The callback must normalize process\n * completion and provide already-redacted bounded output bytes.\n */\nexport class VerifiedEvidenceExecutor {\n\tprivate readonly store: EvidenceReceiptStore;\n\tprivate readonly ledger: ReplayLedgerManager;\n\tprivate readonly now: () => Date;\n\tprivate readonly receiptIdFactory: () => string;\n\tprivate readonly commandAttestationBinder: CommandHmacBinder;\n\tprivate readonly attestedCommands = new Map<string, EvidenceCommandDescriptor>();\n\n\tconstructor(options: VerifiedEvidenceExecutorOptions) {\n\t\tthis.store = options.store;\n\t\tthis.ledger = options.ledger;\n\t\tthis.now = options.now ?? (() => new Date());\n\t\tthis.receiptIdFactory = options.receiptIdFactory ?? randomUUID;\n\t\tthis.commandAttestationBinder = options.commandAttestationBinder ?? createCommandHmacBinder();\n\t}\n\n\treadonly resolveReceipt = (receiptId: string): EvidenceReceipt => this.store.read(receiptId);\n\n\treadonly resolveLedgerEvent = (seq: number): ReplayEvent | undefined =>\n\t\tthis.ledger.getEvents().find((event) => event.seq === seq);\n\n\treadonly resolveVerifiedLedgerSnapshot = () => this.ledger.getVerifiedSnapshot();\n\n\treadonly resolveAttestedCommand = (receiptId: string): EvidenceCommandDescriptor | undefined => {\n\t\tconst command = this.attestedCommands.get(receiptId);\n\t\treturn command === undefined ? undefined : structuredClone(command);\n\t};\n\n\t/** Latest relevant `workspace_mutation` seq from this executor's own replay ledger. */\n\treadonly resolveLatestWorkspaceMutationSeq = (scope: WorkspaceScope): number | null =>\n\t\tlatestRelevantWorkspaceMutationSeq(this.ledger.getEvents(), scope);\n\n\tcreateGateOptions(): Pick<\n\t\tEvidenceGateOptions,\n\t\t| \"resolveReceipt\"\n\t\t| \"resolveLedgerEvent\"\n\t\t| \"resolveVerifiedLedgerSnapshot\"\n\t\t| \"captureWorkspaceFingerprint\"\n\t\t| \"resolveLatestWorkspaceMutationSeq\"\n\t\t| \"commandAttestationBinder\"\n\t\t| \"resolveAttestedCommand\"\n\t> {\n\t\treturn {\n\t\t\tresolveReceipt: this.resolveReceipt,\n\t\t\tresolveLedgerEvent: this.resolveLedgerEvent,\n\t\t\tresolveVerifiedLedgerSnapshot: this.resolveVerifiedLedgerSnapshot,\n\t\t\tcaptureWorkspaceFingerprint,\n\t\t\tresolveLatestWorkspaceMutationSeq: this.resolveLatestWorkspaceMutationSeq,\n\t\t\tcommandAttestationBinder: this.commandAttestationBinder,\n\t\t\tresolveAttestedCommand: this.resolveAttestedCommand,\n\t\t};\n\t}\n\n\tasync execute(request: VerifiedEvidenceExecutionRequest): Promise<VerifiedEvidenceExecutionResult> {\n\t\tvalidateRequest(request);\n\t\tconst ledgerGoalId = this.ledger.getLedger().goalId;\n\t\tif (request.goalId !== ledgerGoalId) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification goalId does not match the replay ledger\");\n\t\t}\n\t\tconst receiptId = this.receiptIdFactory();\n\t\tif (!isSafeEvidenceReceiptId(receiptId)) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"receiptIdFactory returned an unsafe receipt ID\");\n\t\t}\n\t\t// Tokenize the persisted representation and bind the ORIGINAL command under the\n\t\t// internal process key BEFORE any side effect; unrepresentable or oversize\n\t\t// redaction metadata fails closed here. The original is never persisted.\n\t\tconst redaction = redactCommandDescriptor(request.command);\n\t\tconst commandBinding = this.commandAttestationBinder.bind(request.command);\n\t\tconst receiptCommandSha256 = computeEvidenceCommandSha256(redaction.command);\n\t\tconst workspaceBefore = captureWorkspaceFingerprint(request.workspaceScope);\n\t\tconst started = this.now();\n\t\tconst startedMs = started.getTime();\n\t\tif (!Number.isSafeInteger(startedMs)) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification clock produced an invalid start time\");\n\t\t}\n\t\tconst outcome = await request.execute();\n\t\t// Independent-review P3: accept ONLY the disposition and the already-redacted\n\t\t// output bytes from the callback. Every other receipt field is executor-captured\n\t\t// provenance that a callback outcome object must never be able to override.\n\t\tconst { status, exitCode, alreadyRedactedOutput } = outcome;\n\t\tconst disposition = parseExecutionDisposition(status, exitCode);\n\t\tconst finished = this.now();\n\t\tconst finishedMs = finished.getTime();\n\t\tif (!Number.isSafeInteger(finishedMs) || finishedMs < startedMs) {\n\t\t\tthrow new VerifiedEvidenceExecutorError(\"verification clock produced an invalid execution interval\");\n\t\t}\n\t\tconst workspaceAfter = captureWorkspaceFingerprint(request.workspaceScope);\n\t\tconst receipt = createEvidenceReceipt({\n\t\t\treceiptId,\n\t\t\tgoalId: request.goalId,\n\t\t\t...(request.laneId !== undefined ? { laneId: request.laneId } : {}),\n\t\t\tclaim: request.claim,\n\t\t\tcommand: redaction.command,\n\t\t\tcommandRedaction: redaction.summary,\n\t\t\tcommandBinding,\n\t\t\tcwd: request.cwd,\n\t\t\ttimeoutMs: request.timeoutMs,\n\t\t\tstartedAt: started.toISOString(),\n\t\t\tfinishedAt: finished.toISOString(),\n\t\t\tdurationMs: finishedMs - startedMs,\n\t\t\tworkspaceBefore,\n\t\t\tworkspaceAfter,\n\t\t\texecutor: request.executor,\n\t\t\t...disposition,\n\t\t\talreadyRedactedOutput,\n\t\t\t...(request.toolCallId !== undefined ? { toolCallId: request.toolCallId } : {}),\n\t\t});\n\t\tconst event = this.ledger.append({\n\t\t\ttype: \"evidence_receipt\",\n\t\t\tgoalId: request.goalId,\n\t\t\t...(request.laneId !== undefined ? { laneId: request.laneId } : {}),\n\t\t\tpayload: evidenceReceiptReplayPayload(receipt),\n\t\t});\n\t\tthis.ledger.persist();\n\t\tconst boundReceipt = withEvidenceReceiptEnvelope(receipt, {\n\t\t\tledgerBinding: { seq: event.seq, eventHash: parseSha256Hex(event.eventHash, \"ledger eventHash\") },\n\t\t});\n\t\tconst receiptPath = this.store.write(boundReceipt);\n\t\tthis.attestedCommands.set(receiptId, structuredClone(request.command));\n\t\treturn {\n\t\t\treceipt: boundReceipt,\n\t\t\treceiptPath,\n\t\t\tevidenceMetadata: {\n\t\t\t\treceiptId,\n\t\t\t\treceiptSchemaVersion: 3,\n\t\t\t\treceiptCommandSha256,\n\t\t\t\t...(request.laneId !== undefined ? { receiptLaneId: request.laneId } : {}),\n\t\t\t\ttimestamp: finished.toISOString(),\n\t\t\t},\n\t\t};\n\t}\n}\n"]}

package/dist/guardrails/workspace-fingerprint.d.ts

@@ -0,0 +1,23 @@
+import type { ArtifactState, GitWorkspaceState, Sha256Hex, WorkspaceFingerprint, WorkspaceScope } from "../types/evidence.ts";
+export type WorkspaceFingerprintCaptureFaultStage = "before-artifact-open";
+export interface WorkspaceFingerprintCaptureOptions {
+    /** Tests only: mutate a selected path immediately before its artifact is opened. */
+    readonly faultInjector?: (stage: WorkspaceFingerprintCaptureFaultStage, artifactPath: string) => void;
+}
+/** Compute the domain-separated digest for an already validated canonical manifest. */
+export declare function computeWorkspaceManifestSha256(scope: WorkspaceScope, artifacts: readonly ArtifactState[]): Sha256Hex;
+/** Canonical digest committing sorted changed paths, both diff digests, and every selected artifact state. */
+export declare function computeGitWorkspaceDirtySha256(changedPaths: readonly string[], stagedDiffSha256: Sha256Hex, unstagedDiffSha256: Sha256Hex, artifacts: readonly ArtifactState[]): Sha256Hex;
+/** Compute the domain-separated digest for an already validated canonical git manifest. */
+export declare function computeGitWorkspaceManifestSha256(scope: WorkspaceScope, artifacts: readonly ArtifactState[], git: GitWorkspaceState): Sha256Hex;
+/** Strictly parse and validate a fingerprint of either kind, including its canonical digests. */
+export declare function parseWorkspaceFingerprint(value: unknown): WorkspaceFingerprint;
+/**
+ * Hash the selected workspace scope. When the trusted root is itself a git work-tree
+ * top level, capture HEAD plus a scope-limited canonical dirty digest; otherwise hash
+ * the caller-selected artifact set directly and perform no git commands.
+ * Phase A assumes a trusted, quiescent workspace: pathname identity checks reject
+ * observed rebinds, but do not prove an immutable snapshot against a same-UID adversary.
+ */
+export declare function captureWorkspaceFingerprint(scope: WorkspaceScope, options?: WorkspaceFingerprintCaptureOptions): WorkspaceFingerprint;
+//# sourceMappingURL=workspace-fingerprint.d.ts.map