@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -0,0 +1,143 @@
+/**
+ * Bounded Run observation projection.
+ * Owns: one data-only snapshot shape from already-admitted identity/lifecycle/timing facts.
+ * Excludes: evidence reads/admission, reference authorization/redaction, clocks, exports,
+ * lifecycle mutation, delivery acceptance, and native work/control/scope authority.
+ */
+
+import { RUN_DELIVERY_MODEL_MAX_BYTES } from "./limits.ts";
+
+export interface RunSnapshotIdentity {
+  readonly run: string;
+  readonly run_instance_id: string;
+  readonly ownerId?: string;
+}
+
+/** Kernel read-model inputs, not raw Run metadata or serialized proof capabilities. */
+export interface RunSnapshotFacts {
+  readonly identity: RunSnapshotIdentity;
+  readonly captured_at: string;
+  readonly timing:
+    | { readonly basis: "live" | "terminal"; readonly elapsed_ms: number }
+    | { readonly basis: "unproven" };
+  readonly lifecycle:
+    | { readonly status: "running"; readonly phase?: "stopping" }
+    | { readonly status: "done" | "failed" }
+    | { readonly status: "unproven" };
+  readonly cwd: string;
+  readonly context_index?: {
+    readonly identity: RunSnapshotIdentity;
+    readonly path: string;
+  };
+}
+
+export interface RunSnapshot {
+  readonly kind: "run_snapshot";
+  readonly run: string;
+  readonly run_instance_id: string;
+  readonly captured_at: string;
+  readonly elapsed_ms: number;
+  readonly status: "running" | "done" | "failed";
+  readonly phase?: "stopping";
+  readonly cwd: string;
+  readonly evidence: string | null;
+  readonly evidence_error?: "index_unavailable";
+}
+
+type SnapshotUnavailableReason =
+  | "identity_unavailable"
+  | "identity_mismatch"
+  | "observation_unavailable"
+  | "lifecycle_unproven"
+  | "timing_unproven"
+  | "references_unavailable"
+  | "snapshot_too_large";
+
+export type RunSnapshotProjection =
+  | { readonly state: "available"; readonly snapshot: Readonly<RunSnapshot> }
+  | { readonly state: "unavailable"; readonly reason: SnapshotUnavailableReason };
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function own(value: Record<string, unknown> | undefined, key: string): unknown {
+  return value && Object.hasOwn(value, key) ? value[key] : undefined;
+}
+
+function boundedText(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= RUN_DELIVERY_MODEL_MAX_BYTES;
+}
+
+function readIdentity(value: unknown): RunSnapshotIdentity | undefined {
+  const source = record(value);
+  const run = own(source, "run");
+  const generation = own(source, "run_instance_id");
+  if (!boundedText(run) || /[^A-Za-z0-9_.-]/u.test(run) || !boundedText(generation)) return undefined;
+  if (source && Object.hasOwn(source, "ownerId")) {
+    if (!boundedText(source.ownerId)) return undefined;
+    return { run, run_instance_id: generation, ownerId: source.ownerId };
+  }
+  if (source?.ownerId !== undefined) return undefined;
+  return { run, run_instance_id: generation };
+}
+
+function sameIdentity(left: RunSnapshotIdentity, right: RunSnapshotIdentity): boolean {
+  return left.run === right.run && left.run_instance_id === right.run_instance_id && left.ownerId === right.ownerId;
+}
+
+function readableReference(value: unknown): value is string {
+  return boundedText(value) && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+
+function unavailable(reason: SnapshotUnavailableReason): RunSnapshotProjection {
+  return Object.freeze({ state: "unavailable", reason });
+}
+
+/** Facts and curated references must be admitted by their owners before projection; no I/O or authority is acquired here. */
+export function projectRunSnapshot(expected: unknown, facts: unknown): Readonly<RunSnapshotProjection> {
+  const expectedIdentity = readIdentity(expected);
+  const source = record(facts);
+  const identity = readIdentity(own(source, "identity"));
+  if (!expectedIdentity || !identity) return unavailable("identity_unavailable");
+  if (!sameIdentity(expectedIdentity, identity)) return unavailable("identity_mismatch");
+  const capturedAt = own(source, "captured_at");
+  if (!boundedText(capturedAt)) return unavailable("observation_unavailable");
+  const capturedMs = Date.parse(capturedAt);
+  if (!Number.isSafeInteger(capturedMs) || new Date(capturedMs).toISOString() !== capturedAt) {
+    return unavailable("observation_unavailable");
+  }
+  const lifecycle = record(own(source, "lifecycle"));
+  const status = own(lifecycle, "status");
+  const phase = own(lifecycle, "phase");
+  if ((status !== "running" && status !== "done" && status !== "failed") ||
+    (phase !== undefined && (status !== "running" || phase !== "stopping"))) {
+    return unavailable("lifecycle_unproven");
+  }
+  const timing = record(own(source, "timing"));
+  const elapsedMs = own(timing, "elapsed_ms");
+  if (own(timing, "basis") !== (status === "running" ? "live" : "terminal") ||
+    typeof elapsedMs !== "number" || !Number.isSafeInteger(elapsedMs) || elapsedMs < 0) {
+    return unavailable("timing_unproven");
+  }
+  const cwd = own(source, "cwd");
+  if (typeof cwd === "string" && cwd.length > RUN_DELIVERY_MODEL_MAX_BYTES) return unavailable("snapshot_too_large");
+  if (!readableReference(cwd)) return unavailable("references_unavailable");
+  const index = record(own(source, "context_index"));
+  const indexIdentity = readIdentity(own(index, "identity"));
+  const indexPath = own(index, "path");
+  const evidence = indexIdentity && sameIdentity(identity, indexIdentity) && readableReference(indexPath) ? indexPath : null;
+  const snapshot: Readonly<RunSnapshot> = Object.freeze({
+    kind: "run_snapshot", run: identity.run, run_instance_id: identity.run_instance_id,
+    captured_at: capturedAt, elapsed_ms: elapsedMs, status,
+    ...(phase === "stopping" ? { phase } : {}), cwd, evidence,
+    ...(evidence === null ? { evidence_error: "index_unavailable" } as const : {}),
+  });
+  // This is a row ceiling, not a second allowance: delivery still bounds the combined packet.
+  if (Buffer.byteLength(JSON.stringify(snapshot), "utf8") > RUN_DELIVERY_MODEL_MAX_BYTES) {
+    return unavailable("snapshot_too_large");
+  }
+  return Object.freeze({ state: "available", snapshot });
+}

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

@@ -4,13 +4,18 @@
  * preparation before a new runner process is spawned.
  */
 
-import { rmSync } from "node:fs";
-import { join } from "node:path";
+import { readdirSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
 
 import {
   acquireFileMutationLock,
+  mutationLockPath,
   type FileMutationLockOptions,
 } from "./file-state.ts";
+import { assertNoRetainedDescendantLaunchScope } from "./runs-descendant-launches.ts";
+import { assertNoRetainedNativeLaunchScope } from "./runs-native-launches.ts";
+import { isRunStopResultCapture, readRunStopClaim, RUN_STOP_CLAIM_FILE } from "./runs-outcomes.ts";
+import { RUN_STATE_OWNERSHIP_FILE } from "./runs-ownership.ts";
 import {
   isAlive,
   verifyRunProcessIdentity,
@@ -19,6 +24,19 @@ import {
 
 type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 
+function assertNoPendingStop(stateDir: string, meta: Record<string, unknown>): void {
+  const stop = readRunStopClaim(stateDir, meta);
+  if (stop.state === "pending" || stop.state === "invalid") {
+    throw new Error("Run stop is pending or unproven; confirm the complete owned scope before restarting.");
+  }
+}
+
+function assertNoUnresolvedCapture(result: Record<string, unknown> | undefined): void {
+  if (isRunStopResultCapture(result)) {
+    throw new Error("Run stop result capture is not confirmed terminal evidence.");
+  }
+}
+
 export function readActiveOwnedRunState(
   stateDir: string,
   readJson: RunJsonReader,
@@ -26,7 +44,9 @@ export function readActiveOwnedRunState(
 ): Record<string, unknown> | undefined {
   const meta = readJson(join(stateDir, "run.json"));
   if (!meta) return undefined;
+  assertNoPendingStop(stateDir, meta);
   const result = readJson(join(stateDir, "result.json"));
+  assertNoUnresolvedCapture(result);
   if (typeof result?.completedAt === "string") return undefined;
   const pid = Number(meta.pid || 0);
   if (!pid || !isAlive(pid)) return undefined;
@@ -52,6 +72,8 @@ export function assertNoActiveRunState(
   readJson: RunJsonReader,
   runnerPath: string,
 ): void {
+  assertNoRetainedDescendantLaunchScope(stateDir);
+  assertNoRetainedNativeLaunchScope(stateDir);
   const meta = readActiveOwnedRunState(stateDir, readJson, runnerPath);
   if (meta) {
     throw new Error(
@@ -60,6 +82,21 @@ export function assertNoActiveRunState(
   }
 }
 
+/** Prepare-only metadata must neither replace an earlier Run nor erase unrelated retained evidence. */
+export function assertFreshRunPreparationState(stateDir: string): void {
+  assertNoRetainedDescendantLaunchScope(stateDir);
+  let entries: string[];
+  try { entries = readdirSync(stateDir); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const lock = basename(mutationLockPath(join(stateDir, ".lifecycle")));
+  if (entries.some((name) => name !== RUN_STATE_OWNERSHIP_FILE && name !== lock && !name.startsWith(`${lock}.`))) {
+    throw new Error("Run descendant preparation requires fresh state without published Run metadata or retained evidence.");
+  }
+}
+
 export function acquireStateStartLock(
   stateDir: string,
   options: FileMutationLockOptions = {},
@@ -72,7 +109,11 @@ export function prepareStateDirForStart(
   readJson: RunJsonReader,
   _runnerPath: string,
 ): void {
+  assertNoRetainedDescendantLaunchScope(stateDir);
+  assertNoRetainedNativeLaunchScope(stateDir);
   const existing = readJson(join(stateDir, "run.json"));
+  assertNoPendingStop(stateDir, existing ?? {});
+  assertNoUnresolvedCapture(readJson(join(stateDir, "result.json")));
   const existingPid = Number(existing?.pid || 0);
   if (existingPid && isAlive(existingPid)) {
     const identity = verifyRunProcessIdentity(
@@ -102,6 +143,7 @@ export function prepareStateDirForStart(
     "execution.json",
     "progress.json",
     "result.json",
+    RUN_STOP_CLAIM_FILE,
     "stderr.log",
     "stdout.log",
     "terminal-delivery-failure.json",

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

@@ -1,16 +1,29 @@
 /**
  * Async run status and log readers.
- * Owns: status derivation from run state files plus bounded log/event tails.
+ * Owns: status derivation, readonly canonical snapshot-fact admission and bounded log/event tails.
+ * Excludes: snapshot timing/visibility authority, export publication, scheduling and native scope closure.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, type BigIntStats } from "node:fs";
+import { platform } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { types as UtilTypes } from "node:util";
 
+import { RUN_DELIVERY_MODEL_MAX_BYTES } from "./limits.ts";
+import { readRunContextIdentity, readRunContextIndex, RUN_CONTEXT_INDEX_FILE, RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES } from "./runs-context-index.ts";
+import { RUN_OUTCOME_PROTOCOL, RUN_STOP_CLAIM_FILE, isRunStopResultCapture, readRunNaturalOutcomeSnapshot, readRunStopClaim } from "./runs-outcomes.ts";
+import type { RunSnapshotFacts } from "./runs-snapshot.ts";
+import { RUN_STATE_OWNERSHIP_FILE } from "./runs-ownership.ts";
 import {
+  isAlive,
+  observeRunProcessExit,
+  readWindowsProcessIdentities,
+  WINDOWS_IDENTITY_QUERY_PID_LIMIT,
   verifyRunProcessIdentity,
   type RunProcessIdentity,
+  type RunProcessIdentityResult,
 } from "./runs-process.ts";
-import { readJsonlFileResilient } from "./state-readers.ts";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.ts";
 
 export type AsyncRunStatus =
   | "running"
@@ -50,17 +63,30 @@ export function buildRunStatus(
   _runnerPath: string,
   _runnerIdentityGraceMs: number,
 ): Record<string, unknown> {
-  const result = readJson(join(stateDir, "result.json"));
+  return deriveRunStatus(stateDir, meta, readJson, (pid, expected) => verifyRunProcessIdentity(pid, expected));
+}
+
+function deriveRunStatus(stateDir: string, meta: Record<string, unknown>, readJson: RunJsonReader,
+  observeIdentity: (pid: number, expected: RunProcessIdentity | undefined) => RunProcessIdentityResult): Record<string, unknown> {
+  const snapshot = readRunNaturalOutcomeSnapshot(stateDir, meta, readJson);
+  const rawResult = snapshot.result;
+  const staleResult = rawResult?.run_instance_id !== undefined && rawResult.run_instance_id !== meta.run_instance_id;
+  const result = staleResult ? undefined : rawResult;
+  const stop = readRunStopClaim(stateDir, meta);
+  const unresolvedCapture = isRunStopResultCapture(result);
+  const natural = snapshot.outcome;
+  const stopping = natural.state !== "accepted" && (stop.state === "pending" || stop.state === "invalid" || unresolvedCapture);
   const pid = Number(meta.pid || 0);
-  const processIdentity = verifyRunProcessIdentity(
-    pid,
-    meta.process_identity as RunProcessIdentity | undefined,
-  );
+  const processIdentity = observeIdentity(pid, meta.process_identity as RunProcessIdentity | undefined);
   const aliveOwnedRunner = Boolean(
     pid &&
       (processIdentity.valid || processIdentity.status === "unsupported_proof"),
   );
-  const status: AsyncRunStatus = result
+  const status: AsyncRunStatus = natural.state === "accepted"
+    ? natural.status
+    : stopping
+    ? "running"
+    : result
     ? Number(result.code ?? 0) === 0
       ? "done"
       : "failed"
@@ -76,6 +102,11 @@ export function buildRunStatus(
     traceFile: join(stateDir, "trace.jsonl"),
     executionFile: join(stateDir, "execution.json"),
     process_identity_status: processIdentity.status,
+    ...(stopping ? { phase: "stopping", stopped: false } : {}),
+    ...(stopping && stop.state === "pending" ? { stop_reason: stop.claim.reason, stop_claim_id: stop.claim.claim_id } : {}),
+    ...(stop.state === "invalid" || (unresolvedCapture && stop.state !== "pending")
+      ? { stop_error: "claim_unavailable" } : {}),
+    ...(staleResult ? { result_error: "generation_mismatch" } : {}),
     progress: readJson(join(stateDir, "progress.json")) || null,
     result: result || null,
     ...(terminalDeliveryFailure
@@ -88,6 +119,217 @@ export function buildRunStatus(
   };
 }
 
+interface InventorySource {
+  stamp: BigIntStats;
+  bytes: Buffer;
+}
+
+function readInventorySource(path: string): InventorySource | undefined {
+  let fd: number | undefined;
+  try {
+    const stamp = snapshotStamp(path);
+    if (!stamp?.isFile() || stamp.size > BigInt(RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES)) return undefined;
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const opened = fstatSync(fd, { bigint: true });
+    if (opened.dev !== stamp.dev || opened.ino !== stamp.ino || !opened.isFile() || opened.size !== stamp.size ||
+      opened.mtimeNs !== stamp.mtimeNs || opened.ctimeNs !== stamp.ctimeNs) return undefined;
+    const bytes = Buffer.alloc(Number(stamp.size)); let offset = 0;
+    while (offset < bytes.length) {
+      const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (!count) return undefined;
+      offset += count;
+    }
+    if (readSync(fd, Buffer.alloc(1), 0, 1, offset) !== 0 ||
+      !sameSnapshotStamp(stamp, path)) return undefined;
+    const after = fstatSync(fd, { bigint: true });
+    return after.size === stamp.size && after.mtimeNs === stamp.mtimeNs && after.ctimeNs === stamp.ctimeNs ? { stamp, bytes } : undefined;
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function admitInventoryRow(stateDir: string) {
+  const path = join(stateDir, "run.json"); const markerPath = join(stateDir, RUN_STATE_OWNERSHIP_FILE);
+  const source = readInventorySource(path);
+  if (!source) return undefined;
+  let meta: Record<string, unknown>;
+  try { meta = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(source.bytes)); }
+  catch { return undefined; }
+  if (!meta || typeof meta !== "object" || Array.isArray(meta) || meta.state_dir !== stateDir ||
+    typeof meta.pid !== "number" || !Number.isSafeInteger(meta.pid) || meta.pid <= 0) return undefined;
+  const expected = meta.process_identity as RunProcessIdentity | undefined;
+  if (!expected || expected.platform !== "win32" || typeof expected.command !== "string" ||
+    typeof expected.start_time !== "string" || (expected.cwd !== undefined && typeof expected.cwd !== "string")) return undefined;
+  const owner = readRunContextIdentity(stateDir, meta);
+  if (owner.state !== "available" || owner.local_path !== stateDir) return undefined;
+  const marker = readInventorySource(markerPath);
+  if (!marker) return undefined;
+  const unchanged = (): boolean => {
+    if (!owner.unchanged() || !sameSnapshotStamp(source.stamp, path) || !sameSnapshotStamp(marker.stamp, markerPath)) return false;
+    const current = readInventorySource(path); const currentMarker = readInventorySource(markerPath);
+    return !!current && !!currentMarker && source.bytes.equals(current.bytes) && marker.bytes.equals(currentMarker.bytes) && owner.unchanged();
+  };
+  // Once admitted, a changed row can only be discarded, never reread through the scalar facade.
+  return { meta, pid: meta.pid as number, expected, unchanged };
+}
+
+/** Fixed kernel inventory path. Native frames are synchronous locals, never capabilities returned to consumers. */
+export function readRunInventoryStatuses(stateDirs: readonly string[], readJson: RunJsonReader,
+  scalarStatus: (stateDir: string) => Record<string, unknown>): (Record<string, unknown> | undefined)[] {
+  const scalar = (stateDir: string) => { try { return scalarStatus(stateDir); } catch { return undefined; } };
+  if (platform() !== "win32") return stateDirs.map(scalar);
+  const rows = stateDirs.map(stateDir => { try { return admitInventoryRow(stateDir); } catch { return undefined; } });
+  // This selects optional acquisition only; assembly still verifies freshly and excluded rows retain scalar fallback.
+  const pids = [...new Set(rows.flatMap(row => row ? [row.pid] : []))].filter(isAlive);
+  const observations = new Map<number, Map<number, RunProcessIdentity> | undefined>();
+  for (let offset = 0; offset < pids.length; offset += WINDOWS_IDENTITY_QUERY_PID_LIMIT) {
+    const chunk = pids.slice(offset, offset + WINDOWS_IDENTITY_QUERY_PID_LIMIT);
+    const identities = readWindowsProcessIdentities(chunk);
+    for (const pid of chunk) observations.set(pid, identities);
+  }
+  const statuses = stateDirs.map((stateDir, index) => {
+    const row = rows[index];
+    if (!row) return scalar(stateDir);
+    try {
+      if (!row.unchanged()) return undefined;
+      const identities = observations.get(row.pid);
+      const status = deriveRunStatus(stateDir, row.meta, readJson, () => {
+        if (!row.unchanged()) throw new Error("Inventory frame changed");
+        const identity = identities === undefined ? verifyRunProcessIdentity(row.pid, row.expected)
+          : verifyRunProcessIdentity(row.pid, row.expected, "win32", pid => identities.get(pid));
+        if (!row.unchanged()) throw new Error("Inventory frame changed");
+        return identity;
+      });
+      return row.unchanged() ? status : undefined;
+    } catch { return undefined; }
+  });
+  // Later row assembly can reenter file readers and invalidate an earlier assembled row.
+  return statuses.map((status, index) => {
+    const row = rows[index];
+    if (!status || !row) return status;
+    try { return row.unchanged() ? status : undefined; } catch { return undefined; }
+  });
+}
+
+export type RunSnapshotFactsReading =
+  | { readonly state: "available"; readonly facts: Readonly<RunSnapshotFacts>; readonly unchanged: () => boolean }
+  | { readonly state: "unavailable"; readonly reason: "identity_unavailable" | "identity_mismatch" | "observation_changed" |
+      "observation_unavailable" | "references_unavailable" | "snapshot_too_large" };
+
+function snapshotStamp(path: string): BigIntStats | undefined {
+  try { return lstatSync(path, { bigint: true }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+}
+function sameSnapshotStamp(before: BigIntStats | undefined, path: string): boolean {
+  const after = snapshotStamp(path);
+  return before === undefined ? after === undefined : after !== undefined && before.dev === after.dev && before.ino === after.ino &&
+    before.mode === after.mode && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs;
+}
+
+function snapshotDeferred(value: unknown): boolean {
+  if (!UtilTypes.isPromise(value)) return false;
+  void Promise.prototype.then.call(value, undefined, () => {}); return true;
+}
+function snapshotData(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  for (let target: object | null = value; target; target = Object.getPrototypeOf(target)) {
+    const then = Object.getOwnPropertyDescriptor(target, "then");
+    if (then && (!Object.hasOwn(then, "value") || typeof then.value === "function")) 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;
+}
+
+/** Kernel-local facts only. Opt-in timing must be the original retained owner's method, never actor data or a cached DTO. */
+export function readRunSnapshotFacts(stateDir: string, expected: unknown, capturedAt: unknown,
+  observeTime?: (expected: unknown, stateDir?: string) => unknown,
+  observeFrozenNaturalTime?: (expected: unknown, stateDir?: string) => unknown): Readonly<RunSnapshotFactsReading> {
+  const unavailable = (reason: Extract<RunSnapshotFactsReading, { state: "unavailable" }>["reason"]): Readonly<RunSnapshotFactsReading> => Object.freeze({ state: "unavailable", reason });
+  if ((observeTime !== undefined && typeof observeTime !== "function") ||
+    (observeFrozenNaturalTime !== undefined && typeof observeFrozenNaturalTime !== "function") || typeof capturedAt !== "string" || capturedAt.length > 32) return unavailable("observation_unavailable");
+  const capturedMs = Date.parse(capturedAt);
+  if (!Number.isSafeInteger(capturedMs) || new Date(capturedMs).toISOString() !== capturedAt) return unavailable("observation_unavailable");
+  const owner = readRunContextIdentity(stateDir, expected);
+  if (owner.state !== "available") return unavailable(owner.reason);
+  try {
+    const root = owner.local_path; const metadataPath = join(root, "run.json"); const resultPath = join(root, "result.json");
+    const indexPath = join(root, RUN_CONTEXT_INDEX_FILE); const metadata = snapshotStamp(metadataPath);
+    if (!metadata?.isFile() || metadata.size > BigInt(RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES)) return unavailable("observation_unavailable");
+    const read = readJsonFileResilient<unknown>(metadataPath, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+    if (!owner.unchanged() || !sameSnapshotStamp(metadata, metadataPath)) return unavailable("observation_changed");
+    if (read.diagnostics.length || !read.value || typeof read.value !== "object" || Array.isArray(read.value)) return unavailable("observation_unavailable");
+    const meta = read.value as Record<string, unknown>;
+    if (meta.run !== owner.identity.run || meta.run_instance_id !== owner.identity.run_instance_id || meta.ownerId !== owner.identity.ownerId || meta.state_dir !== root) return unavailable("identity_mismatch");
+    if (typeof meta.cwd !== "string" || !isAbsolute(meta.cwd) || /[\u0000-\u001f\u007f]/u.test(meta.cwd)) return unavailable("references_unavailable");
+    if (meta.cwd.length > RUN_DELIVERY_MODEL_MAX_BYTES) return unavailable("snapshot_too_large");
+    const result = snapshotStamp(resultPath); const index = snapshotStamp(indexPath);
+    if (result && !result.isFile()) return unavailable("observation_unavailable");
+    const outcome = readRunNaturalOutcomeSnapshot(root, meta, path => {
+      const canonical = readJsonFileResilient<unknown>(path, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+      return canonical.diagnostics.length ? undefined : canonical.value;
+    });
+    const natural = outcome.outcome; const context = readRunContextIndex(root, owner.identity);
+    const stopPath = join(root, RUN_STOP_CLAIM_FILE); let stopObserved = false; let stopStamp: BigIntStats | undefined; let timingUnchanged: (() => unknown) | undefined;
+    const frameUnchanged = (): boolean => owner.unchanged() && sameSnapshotStamp(metadata, metadataPath) &&
+      sameSnapshotStamp(result, resultPath) && sameSnapshotStamp(index, indexPath) && (!stopObserved || sameSnapshotStamp(stopStamp, stopPath));
+    const unchanged = (): boolean => {
+      try {
+        if (!frameUnchanged()) return false;
+        if (!timingUnchanged) return true;
+        const stable = timingUnchanged();
+        return !snapshotDeferred(stable) && stable === true && frameUnchanged();
+      } catch { return false; }
+    };
+    if (!unchanged()) return unavailable("observation_changed");
+    let lifecycle: RunSnapshotFacts["lifecycle"] = meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && natural.state === "accepted"
+      ? Object.freeze({ status: natural.status }) : Object.freeze({ status: "unproven" });
+    let timing: RunSnapshotFacts["timing"] = Object.freeze({ basis: "unproven" });
+    if (observeFrozenNaturalTime && meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && natural.state === "accepted") {
+      const retained = observeFrozenNaturalTime(owner.identity, root);
+      if (snapshotDeferred(retained)) return unavailable("observation_unavailable");
+      const frozen = snapshotData(retained); if (!frozen) return unavailable("observation_unavailable");
+      if (frozen.state === "available") {
+        const identity = snapshotData(frozen.identity); const accepted = snapshotData(frozen.natural_acceptance);
+        if (!identity || identity.run !== owner.identity.run || identity.run_instance_id !== owner.identity.run_instance_id || identity.ownerId !== owner.identity.ownerId) return unavailable("identity_mismatch");
+        if (frozen.basis !== "first_natural_acceptance" || !accepted || accepted.recorded_status !== natural.status || accepted.code !== outcome.result?.code ||
+          accepted.completed_at !== outcome.result?.completedAt || typeof frozen.elapsed_ms !== "number" || !Number.isSafeInteger(frozen.elapsed_ms) || frozen.elapsed_ms < 0 ||
+          typeof frozen.unchanged !== "function") return unavailable("observation_unavailable");
+        timingUnchanged = frozen.unchanged as () => unknown;
+        timing = Object.freeze({ basis: "terminal", elapsed_ms: frozen.elapsed_ms });
+      } else if (frozen.state !== "unavailable") return unavailable("observation_unavailable");
+      if (!unchanged()) return unavailable("observation_changed");
+    }
+    if (observeTime && meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && (natural.state === "absent" || natural.state === "captured") &&
+      typeof meta.pid === "number" && Number.isSafeInteger(meta.pid) && meta.pid > 0) {
+      stopObserved = true; stopStamp = snapshotStamp(stopPath);
+      const stop = readRunStopClaim(root, meta);
+      const eligible = (natural.state === "absent" && (stop.state === "absent" || stop.state === "stale" || stop.state === "pending")) ||
+        (natural.state === "captured" && stop.state === "pending" && outcome.result?.stop_claim_id === stop.claim.claim_id);
+      if (eligible && observeRunProcessExit(meta.pid, meta.process_identity as RunProcessIdentity | undefined).status === "running") {
+        if (!unchanged()) return unavailable("observation_changed");
+        const sampled = observeTime(owner.identity, root);
+        if (snapshotDeferred(sampled)) return unavailable("observation_unavailable");
+        const observed = snapshotData(sampled); if (!observed) return unavailable("observation_unavailable");
+        if (observed.state === "available") {
+          const identity = snapshotData(observed.identity); const measured = snapshotData(observed.timing);
+          if (!identity || identity.run !== owner.identity.run || identity.run_instance_id !== owner.identity.run_instance_id || identity.ownerId !== owner.identity.ownerId) return unavailable("identity_mismatch");
+          if (observed.basis !== "since_admission" || !measured || typeof observed.unchanged !== "function") return unavailable("observation_unavailable");
+          timingUnchanged = observed.unchanged as () => unknown;
+          lifecycle = Object.freeze({ status: "running", ...(stop.state === "pending" ? { phase: "stopping" as const } : {}) });
+          if (measured.state === "available" && typeof measured.elapsed_ms === "number" && Number.isSafeInteger(measured.elapsed_ms) && measured.elapsed_ms >= 0) {
+            timing = Object.freeze({ basis: "live", elapsed_ms: measured.elapsed_ms });
+          } else if (measured.state !== "unproven" || measured.elapsed_ms !== null) return unavailable("observation_unavailable");
+        } else if (observed.state !== "unavailable") return unavailable("observation_unavailable");
+        if (!unchanged() || observeRunProcessExit(meta.pid, meta.process_identity as RunProcessIdentity | undefined).status !== "running" || !unchanged()) return unavailable("observation_changed");
+      }
+    }
+    const facts: Readonly<RunSnapshotFacts> = Object.freeze({ identity: owner.identity, captured_at: capturedAt,
+      lifecycle, timing, cwd: meta.cwd,
+      ...(context.state === "available" ? { context_index: Object.freeze({ identity: context.identity, path: context.local_path }) } : {}) });
+    if (Buffer.byteLength(JSON.stringify(facts)) > RUN_DELIVERY_MODEL_MAX_BYTES) return unavailable("snapshot_too_large");
+    return unchanged() ? Object.freeze({ state: "available", facts, unchanged }) : unavailable("observation_changed");
+  } catch { return unavailable("observation_unavailable"); }
+}
+
 export function tailFile(path: string, lines: number): string {
   if (!existsSync(path)) return "";
   const content = readFileSync(path, "utf8").trimEnd();