@skill-harness/adapters 0.10.0 → 0.12.0

package/dist/pi-json.d.ts

@@ -32,6 +32,11 @@ export interface PiJsonRunOptions {
     turn: number;
     changedPaths?: string[];
     homeDir?: string;
+    /**
+     * Extra env for the subject process, from the arm. `spawn` treats `undefined`
+     * as "inherit", so the control arm (which never sets this) is unaffected.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 export interface PiJsonRunResult {
     trace: ExecutionTraceV1;
@@ -39,5 +44,12 @@ export interface PiJsonRunResult {
     malformedLines: number;
     code: number | null;
     stderr: string;
+    /**
+     * Set when a line on the stream carried a provider-side failure diagnostic
+     * (auth, transport) rather than the model answering badly. `runStructured`
+     * collects this across turns; `run.ts` turns it into ERROR — never a model
+     * verdict.
+     */
+    providerFailure: string | null;
 }
 export declare function runPiJson(opts: PiJsonRunOptions): Promise<PiJsonRunResult>;

package/dist/pi-json.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { parseTrace } from "@skill-harness/core";
+import { parseTrace, providerFailureFromJsonLine } from "@skill-harness/core";
 /**
  * Run `pi --mode json` and build an execution trace, **streaming**.
  *
@@ -28,12 +28,14 @@ export function runPiJson(opts) {
     return new Promise((resolve, reject) => {
         const child = spawn("pi", opts.args, {
             cwd: opts.cwd,
+            env: opts.env,
             // stdin from /dev/null: pi hangs waiting on it otherwise, and a hang in a
             // wave is indistinguishable from a slow model until the timeout fires.
             stdio: ["ignore", "pipe", "pipe"],
         });
         const kept = [];
         let stderr = "";
+        let providerFailure = null;
         let settled = false;
         const timer = setTimeout(() => {
             if (settled)
@@ -58,6 +60,8 @@ export function runPiJson(opts) {
             if (SKIPPED_TYPE_RE.test(line))
                 return;
             kept.push(line);
+            if (providerFailure === null)
+                providerFailure = providerFailureFromJsonLine(line);
         });
         child.stderr.on("data", (chunk) => {
             if (stderr.length < MAX_STDERR_CHARS)
@@ -85,7 +89,7 @@ export function runPiJson(opts) {
                 changedPaths: opts.changedPaths,
                 homeDir: opts.homeDir,
             });
-            resolve({ ...parsed, code, stderr: stderr.slice(0, MAX_STDERR_CHARS) });
+            resolve({ ...parsed, code, stderr: stderr.slice(0, MAX_STDERR_CHARS), providerFailure });
         });
     });
 }

package/dist/pi.js

@@ -1,10 +1,88 @@
-import { existsSync, mkdtempSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir, homedir } from "node:os";
+import { randomBytes } from "node:crypto";
 import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { runPiJson } from "./pi-json.js";
 import { collectTrajectorySources, normalizePiTraces, resequence } from "./trajectory.js";
-import { exec, onPath, envNum, traceSha256 } from "@skill-harness/core";
+import { bindPromptObservation, observeProviderPayload, promptCaptureIsTrusted, verifyPromptSummary } from "./prompt-provenance.js";
+import { exec, onPath, envNum, traceSha256, withProviderFailure, splitPromptDoc } from "@skill-harness/core";
 const PI_TIMEOUT_MS = envNum("PI_TIMEOUT_MS", 300_000);
+const PROMPT_CAPTURE_EXTENSION = fileURLToPath(new URL("./prompt-capture-extension.js", import.meta.url));
+function contractFor(req) {
+    if (req.systemPromptFile) {
+        const raw = readFileSync(req.systemPromptFile, "utf8");
+        return { text: raw, raw, mechanism: "system-prompt-file" };
+    }
+    const raw = readFileSync(join(requireSkillDir(req.skillDir, req.mode), "SKILL.md"), "utf8");
+    const body = splitPromptDoc(raw).body;
+    if (req.mode === "red")
+        return { text: body, raw, mechanism: "none" };
+    return { text: body, raw, mechanism: req.mode === "green" ? "pi-skill" : "append-system-prompt" };
+}
+const RUNTIME_INJECTION_ENV = ["NODE_OPTIONS", "NODE_PATH", "LD_PRELOAD", "DYLD_INSERT_LIBRARIES"];
+function hasRuntimeInjection(req) {
+    return Boolean(req.armEnv && Object.keys(req.armEnv).length) || RUNTIME_INJECTION_ENV.some(key => Boolean(process.env[key]));
+}
+function captureSetup(req, env, contract, counter) {
+    if (!req.onPromptObservation)
+        return { env, finish: () => { } };
+    // Arbitrary scenario/arm extensions and runtime-injection env execute in Pi's
+    // process with full Node authority. Refuse a forgeable positive observation.
+    if (!promptCaptureIsTrusted(req.extensions?.length ?? 0, hasRuntimeInjection(req)))
+        return { env, finish: () => {
+                const empty = observeProviderPayload({}, contract.text, contract.mechanism, counter.value++);
+                req.onPromptObservation?.({ ...empty, status: "ERROR", error: "prompt delivery provenance is unauthenticated when subject extensions or runtime-injection env share Pi's process" });
+            } };
+    const dir = mkdtempSync(join(tmpdir(), "skill-harness-prompt-"));
+    const path = join(dir, "observations.jsonl"), contractPath = join(dir, "contract.json");
+    const authenticationKey = randomBytes(32).toString("hex");
+    writeFileSync(path, "", { mode: 0o600 });
+    writeFileSync(contractPath, JSON.stringify({ text: contract.text, mechanism: contract.mechanism, authentication_key: authenticationKey }), { mode: 0o600 });
+    const finish = () => {
+        try {
+            const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+            const parsed = lines.map(line => { try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            } });
+            const records = parsed.slice(0, -1), summary = parsed.at(-1);
+            if (!verifyPromptSummary(summary, records.length, authenticationKey)) {
+                const empty = observeProviderPayload({}, contract.text, contract.mechanism, counter.value++);
+                req.onPromptObservation?.({ ...empty, status: "ERROR", error: "Pi prompt observation log is missing, truncated, replayed, or unauthenticated" });
+            }
+            else
+                records.forEach((record, observerRequestIndex) => {
+                    req.onPromptObservation?.(bindPromptObservation(record, contract.text, contract.mechanism, counter.value++, authenticationKey, observerRequestIndex));
+                });
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    };
+    return { env: { ...(env ?? process.env), SKILL_HARNESS_PROMPT_CAPTURE_FILE: path, SKILL_HARNESS_PROMPT_CONTRACT_FILE: contractPath }, finish };
+}
+function observerFlags(req) {
+    return req.onPromptObservation && promptCaptureIsTrusted(req.extensions?.length ?? 0, hasRuntimeInjection(req)) ? ["--extension", PROMPT_CAPTURE_EXTENSION] : [];
+}
+/**
+ * stderr fragments that mean the provider refused the request, so the run measured
+ * nothing about the model. Substring matching on a message pi passes through from
+ * the provider — deliberately narrow: a stderr line we cannot classify stays an
+ * ordinary non-zero exit, because calling a real model failure "infrastructure"
+ * would hide a regression.
+ */
+const PROVIDER_STDERR_SIGNATURES = [
+    "invalidated oauth token",
+    "invalid_api_key",
+    "insufficient_quota",
+];
+function providerStderr(stderr) {
+    const hay = stderr.toLowerCase();
+    return PROVIDER_STDERR_SIGNATURES.some((sig) => hay.includes(sig)) ? stderr.trim() : null;
+}
 /**
  * Refuse to hand pi a skill dir it will silently ignore.
  *
@@ -41,14 +119,15 @@ function requireSkillDir(skillDir, mode) {
  * made conditional. Both are checked the same way, because the failure being
  * prevented — a skill dir that isn't there — costs a whole wave either way.
  */
-function skillFlags(mode, skillDir) {
+function skillFlags(mode, skillDir, boundRaw) {
     switch (mode) {
         case "red":
             return ["--no-skills"];
         case "green":
             return ["--skill", requireSkillDir(skillDir, mode)];
         case "force": {
-            const body = readFileSync(join(requireSkillDir(skillDir, mode), "SKILL.md"), "utf8");
+            requireSkillDir(skillDir, mode);
+            const body = boundRaw ?? readFileSync(join(resolve(skillDir), "SKILL.md"), "utf8");
             return ["--no-skills", "--append-system-prompt", body];
         }
     }
@@ -81,6 +160,7 @@ function header(turnNo, total, text) {
 }
 export const piAdapter = {
     name: "pi",
+    observesPrompts: true,
     available() {
         return Promise.resolve(onPath("pi"));
     },
@@ -116,37 +196,74 @@ export const piAdapter = {
             "--no-context-files",
             "--no-extensions",
             ...extensionFlags(req.extensions),
+            ...observerFlags(req),
             "--provider",
             req.model.provider,
             "--model",
             req.model.model,
         ];
-        // An agent-file run IS the system prompt: no skill activation, whatever the mode.
+        // Bind bytes once: argv and provenance must describe the same contract even if a file changes mid-run.
+        const contract = contractFor(req);
         const flags = req.systemPromptFile
-            ? ["--no-skills", "--append-system-prompt", readFileSync(req.systemPromptFile, "utf8")]
-            : skillFlags(req.mode, req.skillDir);
+            ? ["--no-skills", "--append-system-prompt", contract.raw]
+            : skillFlags(req.mode, req.skillDir, contract.raw);
+        const requestCounter = { value: 0 };
         const total = req.turns.length;
         const parts = [];
+        // The arm's env, merged over the harness's own — undefined (not `process.env`)
+        // when there is none, so `exec`'s `env: opts.env ?? process.env` inherits
+        // normally and the control arm is unaffected.
+        const env = req.armEnv ? { ...process.env, ...req.armEnv } : undefined;
+        // Collected across turns and written by `withProviderFailure` into the
+        // transcript PREAMBLE at the end, never inline after an assistant turn: the
+        // preamble is the only region of the transcript the model provably cannot
+        // reach, and a marker anywhere else is forgeable by a model that types the
+        // words (which would convert a FAIL into ERROR and mute the judge forever).
+        let providerFailure = null;
         if (total === 1) {
             const args = [...flags, ...common, "--no-session", "-p", req.turns[0]];
-            const r = await exec("pi", args, { cwd: req.cwd, timeoutMs: PI_TIMEOUT_MS });
+            const capture = captureSetup(req, env, contract, requestCounter);
+            let r;
+            try {
+                r = await exec("pi", args, { cwd: req.cwd, timeoutMs: PI_TIMEOUT_MS, env: capture.env });
+            }
+            finally {
+                capture.finish();
+            }
             parts.push(header(1, 1, req.turns[0]));
             parts.push(`<<< ASSISTANT:\n${r.stdout.trim()}\n`);
-            if (r.code !== 0)
-                parts.push(`[pi exited ${r.code}]\n${r.stderr.trim()}\n`);
-            return parts.join("\n");
+            if (r.code !== 0) {
+                providerFailure = providerStderr(r.stderr);
+                if (!providerFailure)
+                    parts.push(`[pi exited ${r.code}]\n${r.stderr.trim()}\n`);
+            }
+            return withProviderFailure(parts.join("\n"), providerFailure);
         }
         const session = mkdtempSync(join(tmpdir(), "sc-pi-session-"));
         for (let i = 0; i < total; i++) {
             const turnFlags = i === 0 ? ["--session-dir", session] : ["--session-dir", session, "-c"];
             const args = [...flags, ...common, ...turnFlags, "-p", req.turns[i]];
-            const r = await exec("pi", args, { cwd: req.cwd, timeoutMs: PI_TIMEOUT_MS });
+            const capture = captureSetup(req, env, contract, requestCounter);
+            let r;
+            try {
+                r = await exec("pi", args, { cwd: req.cwd, timeoutMs: PI_TIMEOUT_MS, env: capture.env });
+            }
+            finally {
+                capture.finish();
+            }
             parts.push(header(i + 1, total, req.turns[i]));
             parts.push(`<<< ASSISTANT:\n${r.stdout.trim()}\n`);
-            if (r.code !== 0)
-                parts.push(`[pi exited ${r.code} on turn ${i + 1}]\n${r.stderr.trim()}\n`);
+            if (r.code !== 0) {
+                const provider = providerStderr(r.stderr);
+                // First failure wins, same as the structured path: the turns after an
+                // outage are downstream of it, not independent evidence.
+                if (provider && providerFailure === null)
+                    providerFailure = provider;
+                if (!provider)
+                    parts.push(`[pi exited ${r.code} on turn ${i + 1}]\n${r.stderr.trim()}\n`);
+            }
         }
-        return parts.join("\n");
+        return withProviderFailure(parts.join("\n"), providerFailure);
     },
     /**
      * Structured run: same flags, same turn loop, plus `--mode json` and a trace
@@ -165,19 +282,26 @@ export const piAdapter = {
             "--no-context-files",
             "--no-extensions",
             ...extensionFlags(req.extensions),
+            ...observerFlags(req),
             "--provider",
             req.model.provider,
             "--model",
             req.model.model,
         ];
+        const contract = contractFor(req);
         const flags = req.systemPromptFile
-            ? ["--no-skills", "--append-system-prompt", readFileSync(req.systemPromptFile, "utf8")]
-            : skillFlags(req.mode, req.skillDir);
+            ? ["--no-skills", "--append-system-prompt", contract.raw]
+            : skillFlags(req.mode, req.skillDir, contract.raw);
+        const requestCounter = { value: 0 };
         const piVersion = await this.version();
         const total = req.turns.length;
         const traces = [];
         const parts = [];
         const session = total === 1 ? null : mkdtempSync(join(tmpdir(), "sc-pi-session-"));
+        let providerFailure = null;
+        // Same merge as `run()`: undefined when the arm carries no env, so `spawn`
+        // (which treats `undefined` as "inherit") leaves the control arm untouched.
+        const env = req.armEnv ? { ...process.env, ...req.armEnv } : undefined;
         for (let i = 0; i < total; i++) {
             const turnFlags = session === null
                 ? ["--no-session"]
@@ -185,18 +309,26 @@ export const piAdapter = {
                     ? ["--session-dir", session]
                     : ["--session-dir", session, "-c"];
             const args = [...flags, ...common, "--mode", "json", ...turnFlags, "-p", req.turns[i]];
-            const r = await runPiJson({
-                args,
-                cwd: req.cwd,
-                timeoutMs: PI_TIMEOUT_MS,
-                piVersion,
-                subject: req.model,
-                scenarioId: req.scenarioId ?? "(unknown)",
-                mode: req.mode,
-                rep: req.rep ?? 0,
-                turn: i,
-                homeDir: homedir(),
-            });
+            const capture = captureSetup(req, env, contract, requestCounter);
+            let r;
+            try {
+                r = await runPiJson({
+                    args,
+                    cwd: req.cwd,
+                    timeoutMs: PI_TIMEOUT_MS,
+                    piVersion,
+                    subject: req.model,
+                    scenarioId: req.scenarioId ?? "(unknown)",
+                    mode: req.mode,
+                    rep: req.rep ?? 0,
+                    turn: i,
+                    homeDir: homedir(),
+                    env: capture.env,
+                });
+            }
+            finally {
+                capture.finish();
+            }
             // A stream with no terminal events at all is not evidence of a clean run.
             // Fail loudly here rather than let an empty trace satisfy a `forbid_calls`
             // gate — "the model called nothing" and "we recorded nothing" must not
@@ -210,6 +342,14 @@ export const piAdapter = {
                 r.trace.capture_errors = [`pi JSONL contained ${r.malformedLines} malformed line(s); absence-based trace assertions are unsafe`];
                 r.trace.trace_sha256 = traceSha256(r.trace);
             }
+            // Recorded here, written into the transcript preamble by
+            // `withProviderFailure` below — not just returned on `providerFailure`: the
+            // artifact on disk is the only thing a later `grade`/`regrade` call ever
+            // reads (see `judgeOneRep` in core/regrade.ts), and the structured path
+            // exits 0 while carrying the evidence, so a field a re-judge never sees
+            // leaves it unrecoverable from the saved transcript.
+            if (providerFailure === null && r.providerFailure)
+                providerFailure = r.providerFailure;
             traces.push(r.trace);
             parts.push(header(i + 1, total, req.turns[i]));
             parts.push(`<<< ASSISTANT:\n${r.trace.final_text.trim()}\n`);
@@ -235,10 +375,11 @@ export const piAdapter = {
         }
         const eventErrors = [...native.errors, ...chronologyErrors];
         return {
-            transcript: parts.join("\n"),
+            transcript: withProviderFailure(parts.join("\n"), providerFailure),
             traces,
             events: resequence(combined),
             ...(eventErrors.length ? { eventErrors } : {}),
+            ...(providerFailure ? { providerFailure } : {}),
         };
     },
     /**

package/dist/prompt-capture-extension.d.ts

@@ -0,0 +1,10 @@
+interface PromptEvent {
+    payload: unknown;
+}
+interface MinimalExtensionApi {
+    on(name: "before_provider_request", handler: (event: PromptEvent) => void): void;
+    on(name: "session_shutdown", handler: () => void): void;
+}
+/** Internal observation extension: hashes the final provider prompt in-process; never writes payload plaintext. */
+export default function promptCapture(pi: MinimalExtensionApi): void;
+export {};

package/dist/prompt-capture-extension.js

@@ -0,0 +1,26 @@
+import { appendFileSync, readFileSync, rmSync } from "node:fs";
+import { authenticatePromptObservation, authenticatePromptSummary, observeProviderPayload } from "./prompt-provenance.js";
+/** Internal observation extension: hashes the final provider prompt in-process; never writes payload plaintext. */
+export default function promptCapture(pi) {
+    const target = process.env.SKILL_HARNESS_PROMPT_CAPTURE_FILE;
+    const contractPath = process.env.SKILL_HARNESS_PROMPT_CONTRACT_FILE;
+    if (!target || !contractPath)
+        throw new Error("prompt capture paths are required");
+    const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+    // Remove the capability before any subject/tool execution. The observer keeps
+    // only closed-over values; child processes cannot discover contract/evidence paths.
+    delete process.env.SKILL_HARNESS_PROMPT_CAPTURE_FILE;
+    delete process.env.SKILL_HARNESS_PROMPT_CONTRACT_FILE;
+    rmSync(contractPath, { force: true });
+    let requestIndex = 0;
+    pi.on("before_provider_request", (event) => {
+        const observation = observeProviderPayload(event.payload, contract.text, contract.mechanism, requestIndex++);
+        appendFileSync(target, JSON.stringify(authenticatePromptObservation(observation, contract.authentication_key)) + "\n", { encoding: "utf8", mode: 0o600 });
+    });
+    // Written after the agent loop, so a tool subprocess can at most corrupt the
+    // log into ERROR; it cannot truncate/replay a valid prefix into trusted PASS.
+    pi.on("session_shutdown", () => {
+        appendFileSync(target, JSON.stringify(authenticatePromptSummary(requestIndex, contract.authentication_key)) + "\n", { encoding: "utf8", mode: 0o600 });
+    });
+}
+//# sourceMappingURL=prompt-capture-extension.js.map

package/dist/prompt-provenance.d.ts

@@ -0,0 +1,22 @@
+import { PROMPT_NORMALIZATION_RULE, type PromptMechanism, type PromptProvenance } from "@skill-harness/core";
+export { PROMPT_NORMALIZATION_RULE } from "@skill-harness/core";
+/** Registry entry 1: replace exactly Pi's dynamic cwd line, preserving every other byte. */
+export declare function normalizePromptPayload(value: unknown, rule: typeof PROMPT_NORMALIZATION_RULE): unknown;
+export declare function promptCaptureIsTrusted(extensionCount: number, hasRuntimeInjection?: boolean): boolean;
+export interface AuthenticatedPromptObservation {
+    observation: PromptProvenance;
+    mac: string;
+}
+export interface AuthenticatedPromptSummary {
+    summary: {
+        count: number;
+    };
+    mac: string;
+}
+export declare function authenticatePromptObservation(observation: PromptProvenance, authenticationKey: string): AuthenticatedPromptObservation;
+export declare function authenticatePromptSummary(count: number, authenticationKey: string): AuthenticatedPromptSummary;
+export declare function verifyPromptSummary(value: unknown, expectedCount: number, authenticationKey: string): boolean;
+/** Compute observation from final provider payload prompt bytes; caller supplies content, never status. */
+export declare function observeProviderPayload(payload: unknown, contract: string, mechanism: PromptMechanism, requestIndex: number): PromptProvenance;
+/** Parent-side binding: never accept contract identity or status from the child observer. */
+export declare function bindPromptObservation(value: unknown, contract: string, mechanism: PromptMechanism, requestIndex: number, authenticationKey: string, observerRequestIndex?: number): PromptProvenance;

package/dist/prompt-provenance.js

@@ -0,0 +1,146 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { PROMPT_NORMALIZATION_FLAGS, PROMPT_NORMALIZATION_PATTERN, PROMPT_NORMALIZATION_REPLACEMENT, PROMPT_NORMALIZATION_RULE } from "@skill-harness/core";
+export { PROMPT_NORMALIZATION_RULE } from "@skill-harness/core";
+function sha(bytes) {
+    return createHash("sha256").update(bytes, "utf8").digest("hex");
+}
+/** Registry entry 1: replace exactly Pi's dynamic cwd line, preserving every other byte. */
+export function normalizePromptPayload(value, rule) {
+    if (rule !== PROMPT_NORMALIZATION_RULE)
+        throw new Error(`unknown prompt normalization rule ${String(rule)}`);
+    if (typeof value === "string")
+        return value.replace(new RegExp(PROMPT_NORMALIZATION_PATTERN, PROMPT_NORMALIZATION_FLAGS), PROMPT_NORMALIZATION_REPLACEMENT);
+    if (Array.isArray(value))
+        return value.map((entry) => normalizePromptPayload(entry, rule));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, normalizePromptPayload(entry, rule)]));
+    return value;
+}
+function countInStrings(value, needle) {
+    if (typeof value === "string") {
+        if (!needle)
+            return 0;
+        let count = 0, at = 0;
+        while ((at = value.indexOf(needle, at)) !== -1) {
+            count++;
+            at += needle.length;
+        }
+        return count;
+    }
+    if (Array.isArray(value))
+        return value.reduce((sum, entry) => sum + countInStrings(entry, needle), 0);
+    if (value && typeof value === "object") {
+        const record = value;
+        // A scenario may quote the contract. User-authored text is stimulus, never
+        // delivery, but providers also place tool results inside role=user messages.
+        if (record.role === "user") {
+            const content = Array.isArray(record.content) ? record.content : Array.isArray(record.parts) ? record.parts : [];
+            return content
+                .filter(block => block && typeof block === "object" && (["tool_result", "tool_response", "function_response"].includes(String(block.type ?? "")) ||
+                "functionResponse" in block || "function_response" in block))
+                .reduce((sum, block) => sum + countInStrings(block, needle), 0);
+        }
+        return Object.values(record).reduce((sum, entry) => sum + countInStrings(entry, needle), 0);
+    }
+    return 0;
+}
+const PROMPT_FIELDS = new Set(["instructions", "input", "system", "messages", "prompt", "contents"]);
+function promptProjection(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const record = payload;
+    const projected = Object.fromEntries(Object.entries(record).filter(([key]) => PROMPT_FIELDS.has(key)));
+    const config = record.config && typeof record.config === "object" ? record.config : null;
+    if (config?.systemInstruction !== undefined)
+        projected.systemInstruction = config.systemInstruction;
+    return Object.keys(projected).length ? projected : null;
+}
+export function promptCaptureIsTrusted(extensionCount, hasRuntimeInjection = false) {
+    return extensionCount === 0 && !hasRuntimeInjection;
+}
+function observationMac(observation, authenticationKey) {
+    return createHmac("sha256", authenticationKey).update(JSON.stringify(observation)).digest("hex");
+}
+export function authenticatePromptObservation(observation, authenticationKey) {
+    return { observation, mac: observationMac(observation, authenticationKey) };
+}
+export function authenticatePromptSummary(count, authenticationKey) {
+    const summary = { count };
+    return { summary, mac: createHmac("sha256", authenticationKey).update(JSON.stringify(summary)).digest("hex") };
+}
+function validMac(supplied, expected) {
+    if (typeof supplied !== "string" || !/^[a-f0-9]{64}$/i.test(supplied))
+        return false;
+    const suppliedBytes = Buffer.from(supplied, "hex"), expectedBytes = Buffer.from(expected, "hex");
+    return suppliedBytes.length === expectedBytes.length && timingSafeEqual(suppliedBytes, expectedBytes);
+}
+export function verifyPromptSummary(value, expectedCount, authenticationKey) {
+    if (!value || typeof value !== "object")
+        return false;
+    const envelope = value;
+    if (!envelope.summary || envelope.summary.count !== expectedCount)
+        return false;
+    const expected = createHmac("sha256", authenticationKey).update(JSON.stringify(envelope.summary)).digest("hex");
+    return validMac(envelope.mac, expected);
+}
+function statusFor(occurrences, mechanism, observable) {
+    if (!observable)
+        return "ERROR";
+    return occurrences === (mechanism === "none" ? 0 : 1) ? "PASS" : "NOT-MEASURED";
+}
+/** Compute observation from final provider payload prompt bytes; caller supplies content, never status. */
+export function observeProviderPayload(payload, contract, mechanism, requestIndex) {
+    const projection = promptProjection(payload);
+    const raw = JSON.stringify(projection ?? {});
+    const normalized = JSON.stringify(normalizePromptPayload(projection ?? {}, PROMPT_NORMALIZATION_RULE));
+    const occurrences = countInStrings(projection ?? {}, contract);
+    const observable = projection !== null;
+    return {
+        capture_version: "prompt-provenance-v1",
+        request_index: requestIndex,
+        raw_sha256: sha(raw),
+        normalized_sha256: sha(normalized),
+        normalization_rule: PROMPT_NORMALIZATION_RULE,
+        bytes: Buffer.byteLength(raw),
+        contract_sha256: sha(contract),
+        contract_bytes: Buffer.byteLength(contract),
+        contract_occurrences: occurrences,
+        mechanism,
+        status: statusFor(occurrences, mechanism, observable),
+        ...(observable ? {} : { error: "provider payload has no supported model-visible prompt field" }),
+    };
+}
+/** Parent-side binding: never accept contract identity or status from the child observer. */
+export function bindPromptObservation(value, contract, mechanism, requestIndex, authenticationKey, observerRequestIndex = requestIndex) {
+    const fallback = { ...observeProviderPayload({}, contract, mechanism, requestIndex), status: "ERROR" };
+    if (!value || typeof value !== "object")
+        return { ...fallback, error: "prompt observer emitted a non-object record" };
+    const envelope = value;
+    if (!envelope.observation)
+        return { ...fallback, error: "prompt observation authentication missing" };
+    const expectedMac = observationMac(envelope.observation, authenticationKey);
+    if (!validMac(envelope.mac, expectedMac))
+        return { ...fallback, error: "prompt observation authentication failed" };
+    const record = envelope.observation;
+    if (record.request_index !== observerRequestIndex)
+        return { ...fallback, error: "prompt observation replay or ordering mismatch" };
+    const expectedDigest = sha(contract), expectedBytes = Buffer.byteLength(contract);
+    const valid = record.capture_version === "prompt-provenance-v1" &&
+        record.normalization_rule === PROMPT_NORMALIZATION_RULE && record.mechanism === mechanism &&
+        record.contract_sha256 === expectedDigest && record.contract_bytes === expectedBytes &&
+        typeof record.raw_sha256 === "string" && /^[a-f0-9]{64}$/i.test(record.raw_sha256) &&
+        typeof record.normalized_sha256 === "string" && /^[a-f0-9]{64}$/i.test(record.normalized_sha256) &&
+        Number.isInteger(record.bytes) && record.bytes >= 0 &&
+        Number.isInteger(record.contract_occurrences) && record.contract_occurrences >= 0;
+    if (!valid)
+        return { ...fallback, error: "prompt observation failed parent contract/provenance binding" };
+    const occurrences = record.contract_occurrences;
+    return {
+        capture_version: "prompt-provenance-v1", request_index: requestIndex,
+        raw_sha256: record.raw_sha256, normalized_sha256: record.normalized_sha256,
+        normalization_rule: PROMPT_NORMALIZATION_RULE, bytes: record.bytes,
+        contract_sha256: expectedDigest, contract_bytes: expectedBytes, contract_occurrences: occurrences,
+        mechanism, status: statusFor(occurrences, mechanism, true),
+    };
+}
+//# sourceMappingURL=prompt-provenance.js.map

package/dist/trajectory.d.ts

@@ -12,20 +12,26 @@ export declare function normalizePiTraces(traces: ExecutionTraceV1[]): Trajector
 /** Normalize principal-pi-skills' immutable assurance event schema v1.0. */
 export declare function normalizePrincipalAssuranceLedger(text: string): TrajectoryEventV1[];
 /**
- * Normalize pi-daddy's public ledgers: unversioned 0.17 GrantRecord lines and
- * ledgerVersion 2 runtime events emitted by 0.18.0. Version detection precedes
- * the legacy fallback so a new event can never be misdiagnosed as an old grant.
+ * Normalize pi-daddy's public ledgers: unversioned 0.17 GrantRecord lines,
+ * frozen ledgerVersion 2 events, and separately pinned production ledgerVersion
+ * 3 events. Explicit version dispatch precedes legacy fallback, so an unknown or
+ * malformed new record is never reinterpreted as an old grant.
  */
+/** Historical selector behavior: unversioned 0.17 and frozen ledger v2 only. */
+export declare function normalizePiDaddyLegacyLedger(text: string): TrajectoryEventV1[];
+/** Separately versioned selector: every line must be an explicit ledgerVersion 3 event. */
+export declare function normalizePiDaddyLedgerV3(text: string): TrajectoryEventV1[];
+/** Programmatic mixed-version dispatcher; source declarations use explicit selectors above. */
 export declare function normalizePiDaddyLedger(text: string): TrajectoryEventV1[];
 /**
- * pi-daddy's canonical refusal vocabulary, in the pinned contract's own order.
- *
- * This is a copy of `#/$defs/refusalCode` from the pinned schema and is exported
- * so `pi-daddy-contract.test.ts` can assert set equality against the producer
- * artifact — a hand-maintained second vocabulary without that drift assertion is
- * exactly how `GRANT_ID_MALFORMED` came to be rejected as "unsupported".
+ * pi-daddy's canonical refusal vocabulary, derived directly from the immutable
+ * pinned schema. The producer's `src/refusals.ts` is vendored and digest-checked
+ * separately, while the real-builder verifier proves its production export is
+ * set-equal to this schema-derived runtime set. There is no second list here to
+ * forget when pi-daddy adds a contract-valid code.
  */
 export declare const V2_REFUSAL_CODES: Set<string>;
+export declare const V3_REFUSAL_CODES: Set<string>;
 /**
  * Every vocabulary the adapter restates from the pinned contract, paired with the
  * place in the schema it must equal.