@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/lib/runs-native-launches.ts

@@ -0,0 +1,270 @@
+/**
+ * Native launch evidence persistence.
+ * Owns: generation-bound intent/birth/settlement records and unresolved-scope mutation fences.
+ * Excludes: runtime-local admission/acquisition, complete membership, termination, and restart execution.
+ */
+
+import { randomUUID } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.ts";
+import { runProcessIdentityDigest, type RunProcessIdentity } from "./runs-process.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export const RUN_NATIVE_LAUNCH_FILE = "native-launches.json";
+const SCHEMA = "run-native-launches-v1";
+
+export interface RunNativeLaunchOwner {
+  readonly run: string;
+  readonly runInstanceId: string;
+  readonly ownerId?: string;
+  readonly pid: number;
+  readonly processIdentityDigest?: string;
+}
+
+export interface RunNativeLaunchRequest {
+  readonly commandId: string;
+  readonly attempt: number;
+}
+
+export interface RunNativeLaunchBirth {
+  readonly pid: number;
+  readonly observed_at: string;
+  readonly process_identity: Readonly<RunProcessIdentity>;
+}
+
+export interface RunNativeLaunchCloseSettlement {
+  readonly basis?: never;
+  readonly observed_at: string;
+  readonly native_exit_code: number | null;
+  readonly native_signal: NodeJS.Signals | null;
+}
+
+export interface RunNativeLaunchAbsenceSettlement {
+  readonly basis: "verified_absence";
+  readonly observed_at: string;
+}
+
+export type RunNativeLaunchSettlement = RunNativeLaunchCloseSettlement | RunNativeLaunchAbsenceSettlement;
+
+export interface RunNativeLaunchIntent {
+  readonly intent_id: string;
+  readonly command_id: string;
+  readonly attempt: number;
+  readonly admitted_at: string;
+  readonly birth?: RunNativeLaunchBirth;
+  readonly settlement?: RunNativeLaunchSettlement;
+}
+
+export interface RunNativeLaunchLedger {
+  readonly schema: typeof SCHEMA;
+  readonly run: string;
+  readonly run_instance_id: string;
+  readonly ownerId?: string;
+  readonly runner_pid: number;
+  readonly runner_identity_digest: string | null;
+  readonly intents: readonly RunNativeLaunchIntent[];
+}
+
+export type RunNativeLaunchReading =
+  | { state: "absent" | "invalid" }
+  | { state: "available"; ledger: RunNativeLaunchLedger };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function text(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function intentId(value: unknown): value is string {
+  return typeof value === "string" &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.exec(value)?.[0] === value;
+}
+
+function canonicalTimestamp(value: unknown): value is string {
+  if (!text(value)) return false;
+  try { return new Date(value).toISOString() === value; } catch { return false; }
+}
+
+function validRequest(value: unknown): value is RunNativeLaunchRequest {
+  if (!record(value)) return false;
+  return typeof value.commandId === "string" &&
+    /^command-[0-9]{3,}$/.exec(value.commandId)?.[0] === value.commandId &&
+    Number.isSafeInteger(value.attempt) && Number(value.attempt) > 0;
+}
+
+function validOwner(owner: RunNativeLaunchOwner): boolean {
+  return !!owner && text(owner.run) && text(owner.runInstanceId) &&
+    Number.isSafeInteger(owner.pid) && owner.pid > 0 &&
+    (owner.ownerId === undefined || text(owner.ownerId)) &&
+    (owner.processIdentityDigest === undefined ||
+      (typeof owner.processIdentityDigest === "string" && /^[a-f0-9]{64}$/.exec(owner.processIdentityDigest)?.[0] === owner.processIdentityDigest));
+}
+
+function decodeBirth(value: unknown, runnerPid: number): RunNativeLaunchBirth | undefined {
+  if (!record(value) || !onlyKeys(value, ["pid", "observed_at", "process_identity"]) ||
+    !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 || value.pid === runnerPid ||
+    !canonicalTimestamp(value.observed_at) || !record(value.process_identity)) return undefined;
+  const identity = value.process_identity;
+  if (!onlyKeys(identity, ["platform", "start_time", "command", "cwd"]) || !runProcessIdentityDigest(identity) ||
+    (identity.cwd !== undefined && !text(identity.cwd))) return undefined;
+  return Object.freeze({
+    pid: Number(value.pid), observed_at: value.observed_at,
+    process_identity: Object.freeze({
+      platform: identity.platform as NodeJS.Platform, start_time: String(identity.start_time), command: String(identity.command),
+      ...(identity.cwd === undefined ? {} : { cwd: String(identity.cwd) }),
+    }),
+  });
+}
+
+function decodeSettlement(value: unknown): RunNativeLaunchSettlement | undefined {
+  if (!record(value) || !canonicalTimestamp(value.observed_at)) return undefined;
+  if (value.basis === "verified_absence") {
+    return onlyKeys(value, ["basis", "observed_at"])
+      ? Object.freeze({ basis: "verified_absence", observed_at: value.observed_at }) : undefined;
+  }
+  if (!onlyKeys(value, ["observed_at", "native_exit_code", "native_signal"])) return undefined;
+  const code = value.native_exit_code;
+  const signal = value.native_signal;
+  if (!((Number.isSafeInteger(code) && signal === null) ||
+    (code === null && typeof signal === "string" && /^SIG[A-Z0-9]+$/.exec(signal)?.[0] === signal))) return undefined;
+  return Object.freeze({
+    observed_at: value.observed_at, native_exit_code: code as number | null, native_signal: signal as NodeJS.Signals | null,
+  });
+}
+
+function decode(value: unknown, owner: RunNativeLaunchOwner): RunNativeLaunchLedger | undefined {
+  if (!record(value) || !onlyKeys(value, ["schema", "run", "run_instance_id", "ownerId", "runner_pid", "runner_identity_digest", "intents"]) ||
+    value.schema !== SCHEMA || value.run !== owner.run ||
+    value.run_instance_id !== owner.runInstanceId || value.ownerId !== owner.ownerId ||
+    value.runner_pid !== owner.pid || value.runner_identity_digest !== (owner.processIdentityDigest ?? null) ||
+    !Array.isArray(value.intents)) return undefined;
+  const ids = new Set<string>();
+  const attempts = new Map<string, number>();
+  const births = new Set<string>();
+  const intents: RunNativeLaunchIntent[] = [];
+  for (const item of value.intents) {
+    if (!record(item) || !onlyKeys(item, ["intent_id", "command_id", "attempt", "admitted_at", "birth", "settlement"]) ||
+      !intentId(item.intent_id) || ids.has(item.intent_id) ||
+      !validRequest({ commandId: item.command_id, attempt: item.attempt }) || !canonicalTimestamp(item.admitted_at)) return undefined;
+    const command = String(item.command_id);
+    const attempt = Number(item.attempt);
+    if (attempt !== (attempts.get(command) ?? 0) + 1) return undefined;
+    const birth = item.birth === undefined ? undefined : decodeBirth(item.birth, owner.pid);
+    if (item.birth !== undefined && !birth) return undefined;
+    if (birth) {
+      const key = JSON.stringify([birth.process_identity.platform, birth.pid, birth.process_identity.start_time]);
+      if (births.has(key)) return undefined;
+      births.add(key);
+    }
+    const settlement = item.settlement === undefined ? undefined : decodeSettlement(item.settlement);
+    if (item.settlement !== undefined && (!birth || !settlement)) return undefined;
+    ids.add(item.intent_id);
+    attempts.set(command, attempt);
+    intents.push(Object.freeze({ intent_id: item.intent_id, command_id: command, attempt, admitted_at: item.admitted_at,
+      ...(birth ? { birth } : {}), ...(settlement ? { settlement } : {}) }));
+  }
+  return Object.freeze({
+    schema: SCHEMA, run: owner.run, run_instance_id: owner.runInstanceId,
+    ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }),
+    runner_pid: owner.pid, runner_identity_digest: owner.processIdentityDigest ?? null,
+    intents: Object.freeze(intents),
+  });
+}
+
+/** Even every recorded member's settlement is not complete-scope closure or mutation authority. */
+export function assertNoRetainedNativeLaunchScope(stateDir: string): void {
+  try { lstatSync(join(stateDir, RUN_NATIVE_LAUNCH_FILE)); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; }
+  throw new Error("Run native launch scope is unproven; confirm the complete owned scope before replacing or retiring its state.");
+}
+
+/** Absence or an available admission list never proves no child was born or complete scope membership. */
+export function readRunNativeLaunchLedger(stateDir: string, owner: RunNativeLaunchOwner): RunNativeLaunchReading {
+  if (!validOwner(owner)) return { state: "invalid" };
+  let path: string;
+  try { path = join(assertOwnedRunStateDirectory(stateDir, owner.run), RUN_NATIVE_LAUNCH_FILE); }
+  catch { return { state: "invalid" }; }
+  try { if (!lstatSync(path).isFile()) return { state: "invalid" }; }
+  catch (error) { return { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "absent" : "invalid" }; }
+  const read = readJsonFileResilient<unknown>(path, undefined);
+  if (read.diagnostics.length) return { state: "invalid" };
+  const ledger = decode(read.value, owner);
+  return ledger ? { state: "available", ledger } : { state: "invalid" };
+}
+
+/** Storage only: caller must hold lifecycle admission and supply a kernel-acquired birth, never replayed runtime authority. */
+export function recordRunNativeLaunchBirthUnderLock(
+  stateDir: string,
+  owner: RunNativeLaunchOwner,
+  intent: Readonly<RunNativeLaunchIntent>,
+  birth: RunNativeLaunchBirth,
+): Readonly<RunNativeLaunchBirth> {
+  if (!validOwner(owner)) throw new Error("Run native launch identity or request is invalid.");
+  const canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+  const current = readRunNativeLaunchLedger(canonical, owner);
+  if (current.state !== "available") throw new Error("Run native launch evidence is unavailable or invalid.");
+  const index = current.ledger.intents.findIndex((item) => item.intent_id === intent.intent_id);
+  const prior = current.ledger.intents[index];
+  if (!prior || prior.birth || prior.command_id !== intent.command_id || prior.attempt !== intent.attempt ||
+    prior.admitted_at !== intent.admitted_at) throw new Error("Run native launch birth binding changed or is already retained.");
+  const updated = decode({ ...current.ledger, intents: current.ledger.intents.map((item, i) => i === index ? { ...item, birth } : item) }, owner);
+  if (!updated) throw new Error("Run native launch birth evidence is unavailable or invalid.");
+  writeJsonAtomic(join(canonical, RUN_NATIVE_LAUNCH_FILE), updated);
+  return updated.intents[index]!.birth!;
+}
+
+/** Storage only: exact retained birth plus admitted native-close or verified-absence evidence, never work authority. */
+export function recordRunNativeLaunchSettlementUnderLock<T extends RunNativeLaunchSettlement>(
+  stateDir: string,
+  owner: RunNativeLaunchOwner,
+  update: { intent: Readonly<RunNativeLaunchIntent>; birth: RunNativeLaunchBirth; settlement: T },
+): Readonly<T> {
+  if (!validOwner(owner)) throw new Error("Run native launch identity or request is invalid.");
+  const canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+  const current = readRunNativeLaunchLedger(canonical, owner);
+  if (current.state !== "available") throw new Error("Run native launch evidence is unavailable or invalid.");
+  const { intent, birth, settlement } = update;
+  const index = current.ledger.intents.findIndex((item) => item.intent_id === intent.intent_id);
+  const prior = current.ledger.intents[index];
+  if (!prior?.birth || prior.settlement || prior.command_id !== intent.command_id || prior.attempt !== intent.attempt ||
+    prior.admitted_at !== intent.admitted_at || prior.birth.pid !== birth.pid || prior.birth.observed_at !== birth.observed_at ||
+    runProcessIdentityDigest(prior.birth.process_identity) !== runProcessIdentityDigest(birth.process_identity)) {
+    throw new Error("Run native launch settlement binding changed or is already retained.");
+  }
+  const updated = decode({ ...current.ledger, intents: current.ledger.intents.map((item, i) => i === index ? { ...item, settlement } : item) }, owner);
+  if (!updated) throw new Error("Run native launch settlement evidence is unavailable or invalid.");
+  writeJsonAtomic(join(canonical, RUN_NATIVE_LAUNCH_FILE), updated);
+  return updated.intents[index]!.settlement! as Readonly<T>;
+}
+
+/** Kernel storage only: caller must hold lifecycle/work admission. No reset or rollback of existing intents. */
+export function recordRunNativeLaunchIntentUnderLock(
+  stateDir: string,
+  owner: RunNativeLaunchOwner,
+  request: RunNativeLaunchRequest,
+): Readonly<RunNativeLaunchIntent> {
+  if (!validOwner(owner) || !validRequest(request)) throw new Error("Run native launch identity or request is invalid.");
+  const canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+  const current = readRunNativeLaunchLedger(canonical, owner);
+  if (current.state === "invalid") throw new Error("Run native launch evidence is unavailable or invalid.");
+  const prior = current.state === "available" ? current.ledger.intents : [];
+  const last = prior.filter((item) => item.command_id === request.commandId).at(-1)?.attempt ?? 0;
+  if (request.attempt !== last + 1) throw new Error("Run native launch attempt is duplicate or out of order.");
+  const intent = Object.freeze({ intent_id: randomUUID(), command_id: request.commandId, attempt: request.attempt, admitted_at: new Date().toISOString() });
+  writeJsonAtomic(join(canonical, RUN_NATIVE_LAUNCH_FILE), {
+    schema: SCHEMA, run: owner.run, run_instance_id: owner.runInstanceId,
+    ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }),
+    runner_pid: owner.pid, runner_identity_digest: owner.processIdentityDigest ?? null,
+    intents: [...prior, intent],
+  });
+  return intent;
+}

package/node_modules/@llblab/pi-actors/lib/runs-outcomes.ts

@@ -0,0 +1,377 @@
+/**
+ * Generation-bound outcome protocol and durable stop-request state.
+ * Owns: bounded stop records, process binding, lifecycle-locked stop persistence, canonical result classification and primary/artifact binding data schemas.
+ * Excludes: lock acquisition, primary body admission/publication, deadline eligibility, signals, exit proof and delivery.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import { RUN_COMPLETION_MODEL_MAX_BYTES, RUN_DELIVERY_MODEL_MAX_BYTES } from "./limits.ts";
+import { runProcessIdentityDigest } from "./runs-process.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export const RUN_PRIMARY_TEXT_PROTOCOL = "run-primary-text-v1";
+export const RUN_ARTIFACT_INVENTORY_PROTOCOL = "run-artifact-inventory-v1";
+export const RUN_RESULT_DIAGNOSTICS_PROTOCOL = "run-result-diagnostics-v1";
+export const RUN_RESULT_DIAGNOSTIC_FIELDS = ["command", "error", "failure_reason"] as const;
+export type RunResultDiagnosticField = typeof RUN_RESULT_DIAGNOSTIC_FIELDS[number];
+export type RunResultDiagnosticCandidate = Readonly<Partial<Record<RunResultDiagnosticField, string>>>;
+export const RUN_RESULT_DIAGNOSTIC_EXCERPT_CHARS = 1_000;
+export interface RunResultDiagnosticExcerpt {
+  readonly text: string;
+  readonly bytes_total: number;
+  readonly shown_bytes: Readonly<{ start: number; end: number }>;
+  readonly chars_total: number;
+  readonly chars_shown: number;
+  readonly chars_omitted: number;
+  readonly truncated: boolean;
+}
+export type RunResultDiagnosticPacketExcerpt = Readonly<RunResultDiagnosticExcerpt & { field: RunResultDiagnosticField }>;
+export interface RunResultDiagnosticsReference {
+  readonly source: Readonly<{ path: string; run_instance_id: string; sha256: string }>;
+  readonly bytes_total: number;
+  readonly fields: readonly RunResultDiagnosticField[];
+}
+export type RunResultDiagnosticsBinding =
+  | { readonly result_diagnostics: Readonly<RunResultDiagnosticsReference> }
+  | { readonly result_diagnostics: null; readonly result_diagnostics_unavailable: string };
+export interface RunArtifactInventoryReference {
+  readonly source: Readonly<{ path: string; run_instance_id: string; sha256: string }>;
+  readonly bytes_total: number;
+  readonly declarations_total: number;
+}
+export type RunArtifactInventoryBinding =
+  | { readonly artifact_inventory: Readonly<RunArtifactInventoryReference> }
+  | { readonly artifact_inventory: null; readonly artifact_inventory_unavailable: string };
+
+export interface RunPrimaryTextOutput {
+  readonly text_basis?: "actor_response";
+  readonly upstream_truncated?: boolean;
+  readonly source: { readonly path: string; readonly run_instance_id: string; readonly sha256: string };
+  readonly bytes_total: number;
+  readonly shown_bytes: { readonly start: number; readonly end: number };
+  readonly chars_total: number;
+  readonly chars_shown: number;
+  readonly chars_omitted: number;
+  readonly preview: string;
+  readonly truncated: boolean;
+  readonly redacted: boolean;
+}
+/** Completion-only admitted source text; this data is not an independent publication or read grant. */
+export interface RunCompletionText {
+  readonly text: string;
+  readonly shown_bytes: Readonly<{ start: number; end: number }>;
+}
+
+/** Prefix presentation only; preserve Unicode scalars and never split an admitted CRLF. */
+export function projectRunCompletionText(text: string, maxBytes: number): Readonly<RunCompletionText> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > RUN_COMPLETION_MODEL_MAX_BYTES ||
+      Buffer.from(text).toString("utf8") !== text) throw new Error("Completion text prefix is invalid.");
+  const bytes = Buffer.from(text); let end = Math.min(bytes.length, maxBytes);
+  while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end--;
+  if (end < bytes.length && bytes[end - 1] === 13 && bytes[end] === 10) end--;
+  return Object.freeze({ text: bytes.subarray(0, end).toString("utf8"), shown_bytes: Object.freeze({ start: 0, end }) });
+}
+
+export function decodeRunCompletionText(primary: Readonly<RunPrimaryTextBinding> | undefined, value: unknown): Readonly<RunCompletionText> {
+  const data = primaryData(value), range = primaryData(data?.shown_bytes), output = primary?.output;
+  if (!data || Object.keys(data).some(key => key !== "text" && key !== "shown_bytes") || !range ||
+      Object.keys(range).some(key => key !== "start" && key !== "end") || !output || typeof data.text !== "string" ||
+      range.start !== 0 || !Number.isSafeInteger(range.end) || Number(range.end) < 0 ||
+      Number(range.end) > Math.min(output.bytes_total, RUN_COMPLETION_MODEL_MAX_BYTES) ||
+      Buffer.byteLength(data.text) !== range.end || Buffer.from(data.text).toString("utf8") !== data.text ||
+      [...data.text].length > output.chars_total ||
+      (range.end === output.bytes_total && (createHash("sha256").update(data.text).digest("hex") !== output.source.sha256 ||
+        [...data.text].length !== output.chars_total))) throw new Error("Completion source text is invalid.");
+  const end = Math.min(Number(range.end), output.shown_bytes.end), start = output.shown_bytes.start;
+  if (end > start && !Buffer.from(data.text).subarray(start, end).equals(Buffer.from(output.preview).subarray(0, end - start))) {
+    throw new Error("Completion source text does not match its recorded preview.");
+  }
+  return Object.freeze({ text: data.text, shown_bytes: Object.freeze({ start: 0, end: Number(range.end) }) });
+}
+
+export type RunPrimaryTextBinding =
+  | { readonly output: Readonly<RunPrimaryTextOutput> }
+  | { readonly output: null; readonly output_unavailable: string };
+
+function primaryData(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  return Object.values(descriptors).every(field => Object.hasOwn(field, "value"))
+    ? Object.fromEntries(Object.entries(descriptors).map(([key, field]) => [key, field.value])) : undefined;
+}
+
+/** Curated JSON-data schema only; neither decoding nor a protocol marker admits a body, producer or work. */
+export function decodeRunPrimaryTextBinding(stateDir: string, generation: string, value: unknown): Readonly<RunPrimaryTextBinding> {
+  const input = primaryData(value);
+  if (input?.output === null && typeof input.output_unavailable === "string" && /^[a-z_]{1,80}$/.exec(input.output_unavailable)?.[0] === input.output_unavailable) {
+    return Object.freeze({ output: null, output_unavailable: input.output_unavailable });
+  }
+  const output = primaryData(input?.output);
+  if (!output || typeof output !== "object") throw new Error("Run primary text binding is invalid.");
+  const source = primaryData(output.source); const range = primaryData(output.shown_bytes);
+  const { preview, bytes_total: bytes, chars_total: total, chars_shown: shown, chars_omitted: omitted } = output;
+  if ((output.text_basis !== undefined && output.text_basis !== "actor_response") ||
+    (output.text_basis === "actor_response" ? typeof output.upstream_truncated !== "boolean" : output.upstream_truncated !== undefined) ||
+    !source || typeof source.path !== "string" || !isAbsolute(source.path) || resolve(source.path) !== source.path ||
+    dirname(source.path) !== join(stateDir, "evidence") || /^primary-[a-f0-9]{64}\.txt$/.exec(basename(source.path))?.[0] !== basename(source.path) || source.run_instance_id !== generation ||
+    typeof source.sha256 !== "string" || source.sha256.length !== 64 || !/^[a-f0-9]{64}$/.test(source.sha256) || !range ||
+    ![bytes, total, shown, omitted, range.start, range.end].every(number => typeof number === "number" && Number.isSafeInteger(number) && number >= 0) ||
+    Number(range.start) > Number(range.end) || Number(range.end) > Number(bytes) || typeof preview !== "string" || Buffer.byteLength(preview) !== Number(range.end) - Number(range.start) ||
+    Buffer.from(preview).toString("utf8") !== preview || [...preview].length !== shown || Number(shown) + Number(omitted) !== total || Number(total) > Number(bytes) || typeof output.redacted !== "boolean" || output.truncated !== (Number(omitted) > 0)) {
+    throw new Error("Run primary text binding is invalid.");
+  }
+  const binding = { output: { ...(output.text_basis === "actor_response" ? { text_basis: "actor_response" as const, upstream_truncated: output.upstream_truncated as boolean } : {}),
+    source: Object.freeze({ path: source.path, run_instance_id: generation, sha256: source.sha256 }),
+    bytes_total: Number(bytes), shown_bytes: Object.freeze({ start: Number(range.start), end: Number(range.end) }), chars_total: Number(total), chars_shown: Number(shown), chars_omitted: Number(omitted),
+    preview, truncated: output.truncated, redacted: output.redacted } };
+  if (Buffer.byteLength(JSON.stringify(binding)) > RUN_DELIVERY_MODEL_MAX_BYTES) throw new Error("Run primary text binding is too large.");
+  return Object.freeze({ output: Object.freeze(binding.output) });
+}
+
+/** Inspect completion shape without invoking getters/custom thenables; this grants no source authority. */
+function synchronousBindingData(value: unknown, label: string): Record<string, unknown> | undefined {
+  for (let target = value && typeof value === "object" ? value : null; target; target = Object.getPrototypeOf(target)) {
+    const then = Object.getOwnPropertyDescriptor(target, "then");
+    if (then && (!Object.hasOwn(then, "value") || typeof then.value === "function")) throw new Error(`${label} binding must complete synchronously.`);
+  }
+  const input = primaryData(value);
+  if (input && Object.hasOwn(input, "then")) throw new Error(`${label} binding must complete synchronously.`);
+  return input;
+}
+
+/** Data schema only; copied actor fields/markers cannot publish or authorize inventory/body reads. */
+export function decodeRunArtifactInventoryBinding(stateDir: string, generation: string, value: unknown): Readonly<RunArtifactInventoryBinding> {
+  const input = synchronousBindingData(value, "Run artifact inventory");
+  if (input?.artifact_inventory === null && typeof input.artifact_inventory_unavailable === "string" &&
+    /^[a-z_]{1,80}$/u.exec(input.artifact_inventory_unavailable)?.[0] === input.artifact_inventory_unavailable) {
+    return Object.freeze({ artifact_inventory: null, artifact_inventory_unavailable: input.artifact_inventory_unavailable });
+  }
+  const inventory = primaryData(input?.artifact_inventory); const source = primaryData(inventory?.source);
+  if (!inventory || !source || typeof source.path !== "string" || !isAbsolute(source.path) || resolve(source.path) !== source.path ||
+    dirname(source.path) !== join(stateDir, "evidence") || /^artifact-inventory-[a-f0-9]{64}\.json$/u.exec(basename(source.path))?.[0] !== basename(source.path) ||
+    source.run_instance_id !== generation || typeof source.sha256 !== "string" || source.sha256.length !== 64 || !/^[a-f0-9]{64}$/u.test(source.sha256) ||
+    typeof inventory.bytes_total !== "number" || !Number.isSafeInteger(inventory.bytes_total) || inventory.bytes_total <= 0 ||
+    typeof inventory.declarations_total !== "number" || !Number.isSafeInteger(inventory.declarations_total) || inventory.declarations_total <= 0 || inventory.declarations_total > inventory.bytes_total) {
+    throw new Error("Run artifact inventory binding is invalid.");
+  }
+  const binding = Object.freeze({ artifact_inventory: Object.freeze({ source: Object.freeze({ path: source.path, run_instance_id: generation, sha256: source.sha256 }),
+    bytes_total: inventory.bytes_total, declarations_total: inventory.declarations_total }) });
+  if (Buffer.byteLength(JSON.stringify(binding)) > RUN_DELIVERY_MODEL_MAX_BYTES) throw new Error("Run artifact inventory binding is too large.");
+  return binding;
+}
+
+/** Curated diagnostic reference data only, never candidate/producer/publication/body permission. */
+export function decodeRunResultDiagnosticsBinding(stateDir: string, generation: string, value: unknown): Readonly<RunResultDiagnosticsBinding> {
+  const input = synchronousBindingData(value, "Run result diagnostics");
+  if (input?.result_diagnostics === null && typeof input.result_diagnostics_unavailable === "string" &&
+    /^[a-z_]{1,80}$/u.exec(input.result_diagnostics_unavailable)?.[0] === input.result_diagnostics_unavailable) {
+    return Object.freeze({ result_diagnostics: null, result_diagnostics_unavailable: input.result_diagnostics_unavailable });
+  }
+  const reference = primaryData(input?.result_diagnostics); const source = primaryData(reference?.source);
+  const list = Array.isArray(reference?.fields) ? Object.getOwnPropertyDescriptors(reference.fields as object) : undefined;
+  const fields = list && Object.values(list).every(field => Object.hasOwn(field, "value")) &&
+    Number.isSafeInteger(list.length?.value) && list.length!.value > 0 && list.length!.value <= RUN_RESULT_DIAGNOSTIC_FIELDS.length
+    ? Array.from({ length: list.length!.value as number }, (_, index) => list[String(index)]?.value) : undefined;
+  if (!reference || !source || typeof source.path !== "string" || !isAbsolute(source.path) || resolve(source.path) !== source.path ||
+    dirname(source.path) !== join(stateDir, "evidence") || /^result-diagnostics-[a-f0-9]{64}\.json$/u.exec(basename(source.path))?.[0] !== basename(source.path) ||
+    source.run_instance_id !== generation || typeof source.sha256 !== "string" || source.sha256.length !== 64 || !/^[a-f0-9]{64}$/u.test(source.sha256) ||
+    typeof reference.bytes_total !== "number" || !Number.isSafeInteger(reference.bytes_total) || reference.bytes_total <= 0 || !fields ||
+    fields.some((field, index) => !RUN_RESULT_DIAGNOSTIC_FIELDS.includes(field as RunResultDiagnosticField) || fields.indexOf(field) !== index) ||
+    JSON.stringify(fields) !== JSON.stringify(RUN_RESULT_DIAGNOSTIC_FIELDS.filter(field => fields.includes(field)))) throw new Error("Run result diagnostics binding is invalid.");
+  const binding = Object.freeze({ result_diagnostics: Object.freeze({ source: Object.freeze({ path: source.path, run_instance_id: generation, sha256: source.sha256 }),
+    bytes_total: reference.bytes_total, fields: Object.freeze(fields as RunResultDiagnosticField[]) }) });
+  if (Buffer.byteLength(JSON.stringify(binding)) > RUN_DELIVERY_MODEL_MAX_BYTES) throw new Error("Run result diagnostics binding is too large.");
+  return binding;
+}
+
+/** Frozen literal prefix metadata only; a valid excerpt/reference DTO does not authorize source publication. */
+export function decodeRunResultDiagnosticExcerpt(reference: Readonly<RunResultDiagnosticsReference>, value: unknown): RunResultDiagnosticPacketExcerpt {
+  const input = primaryData(value); const range = primaryData(input?.shown_bytes);
+  if (!input || !range || !reference.fields.includes(input.field as RunResultDiagnosticField) || typeof input.text !== "string" ||
+    Buffer.from(input.text, "utf8").toString("utf8") !== input.text || ![input.bytes_total, input.chars_total, input.chars_shown, input.chars_omitted, range.start, range.end]
+      .every(number => typeof number === "number" && Number.isSafeInteger(number) && number >= 0) ||
+    range.start !== 0 || Number(range.end) > Number(input.bytes_total) || Buffer.byteLength(input.text) !== range.end ||
+    Array.from(input.text).length !== input.chars_shown || Number(input.chars_shown) > RUN_RESULT_DIAGNOSTIC_EXCERPT_CHARS ||
+    Number(input.chars_shown) + Number(input.chars_omitted) !== input.chars_total || Number(input.chars_total) > Number(input.bytes_total) ||
+    input.truncated !== (Number(input.chars_omitted) > 0)) throw new Error("Run result diagnostic excerpt is invalid.");
+  const excerpt = Object.freeze({ field: input.field as RunResultDiagnosticField, text: input.text, bytes_total: Number(input.bytes_total),
+    shown_bytes: Object.freeze({ start: 0, end: Number(range.end) }), chars_total: Number(input.chars_total), chars_shown: Number(input.chars_shown),
+    chars_omitted: Number(input.chars_omitted), truncated: input.truncated as boolean });
+  if (Buffer.byteLength(JSON.stringify(excerpt)) > RUN_DELIVERY_MODEL_MAX_BYTES) throw new Error("Run result diagnostic excerpt is too large.");
+  return excerpt;
+}
+
+export const RUN_OUTCOME_PROTOCOL = "run-outcome-v1" as const;
+export const RUN_STOP_CLAIM_FILE = "stop-claim.json";
+const MAX_STOP_CLAIM_BYTES = 16_384;
+
+export type RunStopReason = "manual_kill" | "max_runtime";
+
+export interface RunStopClaim {
+  version: 1;
+  claim_id: string;
+  run: string;
+  run_instance_id: string;
+  ownerId?: string;
+  pid: number;
+  process_identity_digest: string;
+  reason: RunStopReason;
+  requested_at: string;
+}
+
+export type RunStopClaimReading =
+  | { state: "absent" | "stale" | "invalid" }
+  | { state: "pending"; claim: Readonly<RunStopClaim> };
+
+
+function isCanonicalTimestamp(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const time = Date.parse(value);
+  return Number.isSafeInteger(time) && new Date(time).toISOString() === value;
+}
+
+function decodeStopClaim(value: unknown): RunStopClaim | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  if (record.version !== 1 ||
+    typeof record.claim_id !== "string" || !/^[0-9a-f-]{36}$/.test(record.claim_id) ||
+    typeof record.run !== "string" || !record.run ||
+    typeof record.run_instance_id !== "string" || !record.run_instance_id ||
+    (record.ownerId !== undefined && (typeof record.ownerId !== "string" || !record.ownerId)) ||
+    !Number.isSafeInteger(record.pid) || Number(record.pid) <= 0 ||
+    typeof record.process_identity_digest !== "string" || !/^[0-9a-f]{64}$/.test(record.process_identity_digest) ||
+    (record.reason !== "manual_kill" && record.reason !== "max_runtime") ||
+    !isCanonicalTimestamp(record.requested_at)) return undefined;
+  return {
+    version: 1,
+    claim_id: record.claim_id,
+    run: record.run,
+    run_instance_id: record.run_instance_id,
+    ...(typeof record.ownerId === "string" ? { ownerId: record.ownerId } : {}),
+    pid: Number(record.pid),
+    process_identity_digest: record.process_identity_digest,
+    reason: record.reason,
+    requested_at: record.requested_at,
+  };
+}
+
+export function readRunStopClaim(
+  stateDir: string,
+  meta: Record<string, unknown>,
+): RunStopClaimReading {
+  const path = join(stateDir, RUN_STOP_CLAIM_FILE);
+  try {
+    if (!lstatSync(path).isFile()) return { state: "invalid" };
+  } catch (error) {
+    return { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "absent" : "invalid" };
+  }
+  const read = readJsonFileResilient<unknown>(path, undefined, { maxBytes: MAX_STOP_CLAIM_BYTES });
+  if (read.diagnostics.length) return { state: "invalid" };
+  if (read.value && typeof read.value === "object" && !Array.isArray(read.value)) {
+    const generation = (read.value as Record<string, unknown>).run_instance_id;
+    if (typeof generation === "string" && generation && typeof meta.run_instance_id === "string" &&
+      generation !== meta.run_instance_id) return { state: "stale" };
+  }
+  const claim = decodeStopClaim(read.value);
+  if (!claim || meta.outcome_protocol !== RUN_OUTCOME_PROTOCOL ||
+    claim.run !== meta.run || claim.run_instance_id !== meta.run_instance_id ||
+    claim.ownerId !== meta.ownerId || claim.pid !== meta.pid ||
+    claim.process_identity_digest !== runProcessIdentityDigest(meta.process_identity)) {
+    return { state: "invalid" };
+  }
+  return { state: "pending", claim: Object.freeze(claim) };
+}
+
+/** Only the control owner may call this after admission under the canonical lifecycle lock. */
+export function writeRunStopClaimUnderLock(
+  stateDir: string,
+  meta: Record<string, unknown>,
+  reason: RunStopReason,
+): Readonly<RunStopClaim> {
+  if (readRunStopClaim(stateDir, meta).state !== "absent") {
+    throw new Error("Run stop claim cannot replace existing evidence.");
+  }
+  const claim = {
+    version: 1,
+    claim_id: randomUUID(),
+    run: meta.run,
+    run_instance_id: meta.run_instance_id,
+    ...(meta.ownerId !== undefined ? { ownerId: meta.ownerId } : {}),
+    pid: meta.pid,
+    process_identity_digest: runProcessIdentityDigest(meta.process_identity),
+    reason,
+    requested_at: new Date().toISOString(),
+  };
+  const decoded = decodeStopClaim(claim);
+  if (!decoded || meta.outcome_protocol !== RUN_OUTCOME_PROTOCOL ||
+    Buffer.byteLength(JSON.stringify(claim, null, 2), "utf8") > MAX_STOP_CLAIM_BYTES) {
+    throw new Error("Run stop claim identity is unavailable or invalid.");
+  }
+  writeJsonAtomic(join(stateDir, RUN_STOP_CLAIM_FILE), decoded);
+  return Object.freeze(decoded);
+}
+
+/** Capture markers never imply terminal acceptance, even when their claim is unavailable. */
+export function isRunStopResultCapture(result: Record<string, unknown> | undefined): boolean {
+  return result?.terminal_acceptance === "after_stop_claim" || result?.stop_claim_id !== undefined;
+}
+
+export type RunNaturalOutcomeReading =
+  | { state: "absent" | "invalid" | "captured" }
+  | { state: "accepted"; status: "done" | "failed" };
+
+export interface RunNaturalOutcomeSnapshot {
+  readonly result: Record<string, unknown> | undefined;
+  readonly outcome: RunNaturalOutcomeReading;
+}
+
+function classifyNaturalOutcome(result: Record<string, unknown>, meta: Record<string, unknown>): RunNaturalOutcomeReading {
+  if (typeof meta.run_instance_id !== "string" || !meta.run_instance_id || !Object.hasOwn(result, "code") ||
+    result.run_instance_id !== meta.run_instance_id || !Number.isSafeInteger(result.code) ||
+    !isCanonicalTimestamp(result.completedAt)) return { state: "invalid" };
+  if (result.terminal_acceptance === "after_stop_claim" && typeof result.stop_claim_id === "string") {
+    return { state: "captured" };
+  }
+  if (result.terminal_acceptance !== "natural" || Object.hasOwn(result, "stop_claim_id")) {
+    return { state: "invalid" };
+  }
+  return { state: "accepted", status: result.code === 0 ? "done" : "failed" };
+}
+
+function readResultJson(path: string): unknown {
+  const read = readJsonFileResilient<unknown>(path, undefined);
+  return read.diagnostics.length ? undefined : read.value;
+}
+
+/** Read one regular-file result snapshot for both precedence and rendering; data never grants work/stop authority. */
+export function readRunNaturalOutcomeSnapshot(
+  stateDir: string,
+  meta: Record<string, unknown>,
+  readResult: (path: string) => unknown = readResultJson,
+): Readonly<RunNaturalOutcomeSnapshot> {
+  const path = join(stateDir, "result.json");
+  try {
+    if (!lstatSync(path).isFile()) return Object.freeze<RunNaturalOutcomeSnapshot>({ result: undefined, outcome: { state: "invalid" } });
+  } catch (error) {
+    return Object.freeze<RunNaturalOutcomeSnapshot>({ result: undefined,
+      outcome: { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "absent" : "invalid" } });
+  }
+  const value = readResult(path);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return Object.freeze<RunNaturalOutcomeSnapshot>({ result: undefined, outcome: { state: "invalid" } });
+  }
+  const result = value as Record<string, unknown>;
+  return Object.freeze({ result, outcome: classifyNaturalOutcome(result, meta) });
+}
+
+/** Result bodies remain in their existing canonical file; this is admission, not a second store. */
+export function readRunNaturalOutcome(
+  stateDir: string,
+  meta: Record<string, unknown>,
+): RunNaturalOutcomeReading {
+  return readRunNaturalOutcomeSnapshot(stateDir, meta).outcome;
+}