@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/dist/lib/runs-descendant-launches.js

@@ -0,0 +1,287 @@
+/**
+ * Descendant Run launch-intent evidence.
+ * Owns: declared/prepared parent-child generation facts, strict persistence, and unresolved-scope mutation fences.
+ * Excludes: authenticating child birth/membership, work/control authority, exhaustive scope, and termination.
+ */
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
+import { readJsonFileResilient } from "./state-readers.js";
+export const RUN_DESCENDANT_LAUNCH_FILE = "descendant-launches.json";
+export const RUN_DESCENDANT_PREPARATION_FILE = "descendant-preparation.json";
+export const RUN_DESCENDANT_PREPARED_META_FILE = "prepared-run.json";
+const SCHEMA = "run-descendant-launches-v1";
+const PREPARATION_SCHEMA = "run-descendant-preparation-v1";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function onlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function required(value, keys) {
+    return keys.every((key) => Object.hasOwn(value, key));
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function optionalText(value, key) {
+    return !(key in value) || (Object.hasOwn(value, key) && (value[key] === undefined || text(value[key])));
+}
+function validOwner(value) {
+    if (!record(value) || !required(value, ["run", "runInstanceId", "pid"]) ||
+        !text(value.run) || !text(value.runInstanceId) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 ||
+        !optionalText(value, "ownerId"))
+        return false;
+    return !("processIdentityDigest" in value) || (Object.hasOwn(value, "processIdentityDigest") &&
+        (value.processIdentityDigest === undefined || (typeof value.processIdentityDigest === "string" &&
+            /^[a-f0-9]{64}$/.exec(value.processIdentityDigest)?.[0] === value.processIdentityDigest)));
+}
+function intentId(value) {
+    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 timestamp(value) {
+    if (!text(value))
+        return false;
+    try {
+        return new Date(value).toISOString() === value;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeReference(value) {
+    if (!record(value) || !onlyKeys(value, ["run", "run_instance_id", "ownerId", "state_dir"]) ||
+        !required(value, ["run", "run_instance_id", "state_dir"]) || typeof value.run !== "string" ||
+        /^[A-Za-z0-9_.-]+$/.exec(value.run)?.[0] !== value.run || !text(value.run_instance_id) ||
+        !optionalText(value, "ownerId") || !text(value.state_dir) || !isAbsolute(value.state_dir) ||
+        resolve(value.state_dir) !== value.state_dir)
+        return undefined;
+    // A normalized declaration is not filesystem identity, existence, or child ownership proof.
+    return Object.freeze({ run: value.run, run_instance_id: value.run_instance_id,
+        ...(value.ownerId === undefined ? {} : { ownerId: String(value.ownerId) }), state_dir: value.state_dir });
+}
+function decodeTarget(value, owner, stateDir) {
+    const target = decodeReference(value);
+    return target && target.run_instance_id !== owner.runInstanceId && target.state_dir !== stateDir ? target : undefined;
+}
+function decodePreparedFact(value) {
+    if (!record(value) || !onlyKeys(value, ["preparation_id", "prepared_at"]) ||
+        !intentId(value.preparation_id) || !timestamp(value.prepared_at))
+        return undefined;
+    return Object.freeze({ preparation_id: value.preparation_id, prepared_at: value.prepared_at });
+}
+function decodeProducerBinding(value) {
+    if (!record(value) || !onlyKeys(value, ["pid", "process_identity_digest"]) ||
+        !required(value, ["pid", "process_identity_digest"]) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 ||
+        (value.process_identity_digest !== null && (typeof value.process_identity_digest !== "string" ||
+            /^[a-f0-9]{64}$/.exec(value.process_identity_digest)?.[0] !== value.process_identity_digest)))
+        return undefined;
+    return Object.freeze({ pid: Number(value.pid), process_identity_digest: value.process_identity_digest });
+}
+function decodePreparation(value) {
+    if (!record(value) || !onlyKeys(value, ["schema", "preparation_id", "prepared_at", "parent", "child", "parent_producer"]) ||
+        value.schema !== PREPARATION_SCHEMA || !intentId(value.preparation_id) || !timestamp(value.prepared_at))
+        return undefined;
+    const parent = decodeReference(value.parent);
+    const child = decodeReference(value.child);
+    const producer = Object.hasOwn(value, "parent_producer") ? decodeProducerBinding(value.parent_producer) : undefined;
+    if (!parent || !child || parent.run_instance_id === child.run_instance_id || parent.state_dir === child.state_dir ||
+        ("parent_producer" in value && (!Object.hasOwn(value, "parent_producer") || !producer)))
+        return undefined;
+    return Object.freeze({ schema: PREPARATION_SCHEMA, preparation_id: value.preparation_id, prepared_at: value.prepared_at, parent, child,
+        ...(producer ? { parent_producer: producer } : {}) });
+}
+function sameReference(a, b) {
+    return a.run === b.run && a.run_instance_id === b.run_instance_id && a.ownerId === b.ownerId && a.state_dir === b.state_dir;
+}
+/** Validated reference data only; resolving a target never grants work or membership authority. */
+export function resolveRunDescendantLaunchTarget(value, owner, stateDir) {
+    if (!record(value) || !onlyKeys(value, ["run", "runInstanceId", "ownerId", "stateDir"]) ||
+        !required(value, ["run", "runInstanceId", "stateDir"]) || !optionalText(value, "ownerId"))
+        return undefined;
+    return decodeTarget({ run: value.run, run_instance_id: value.runInstanceId,
+        ...(value.ownerId === undefined ? {} : { ownerId: value.ownerId }), state_dir: value.stateDir }, owner, stateDir);
+}
+function decode(value, owner, stateDir) {
+    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();
+    const generations = new Set();
+    const preparations = new Set();
+    const intents = [];
+    for (const item of value.intents) {
+        if (!record(item) || !onlyKeys(item, ["intent_id", "admitted_at", "child", "preparation"]) || !intentId(item.intent_id) ||
+            ids.has(item.intent_id) || !timestamp(item.admitted_at))
+            return undefined;
+        const child = decodeTarget(item.child, owner, stateDir);
+        const preparation = item.preparation === undefined ? undefined : decodePreparedFact(item.preparation);
+        if (!child || generations.has(child.run_instance_id) || (item.preparation !== undefined && !preparation) ||
+            (preparation && preparations.has(preparation.preparation_id)))
+            return undefined;
+        ids.add(item.intent_id);
+        generations.add(child.run_instance_id);
+        if (preparation)
+            preparations.add(preparation.preparation_id);
+        intents.push(Object.freeze({ intent_id: item.intent_id, admitted_at: item.admitted_at, child,
+            ...(preparation ? { preparation } : {}) }));
+    }
+    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) });
+}
+/** Only ENOENT permits mutation; an empty or invalid journal is not closure proof. */
+export function assertNoRetainedDescendantLaunchScope(stateDir) {
+    assertNoRetainedDescendantFiles(stateDir, [RUN_DESCENDANT_LAUNCH_FILE, RUN_DESCENDANT_PREPARATION_FILE, RUN_DESCENDANT_PREPARED_META_FILE]);
+}
+function assertNoRetainedDescendantFiles(stateDir, files) {
+    for (const file of files) {
+        try {
+            lstatSync(join(stateDir, file));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+        }
+        throw new Error("Run descendant launch scope is unproven; confirm the complete owned scope before replacing or retiring its state.");
+    }
+}
+/** Declared generations and paths confer no child work/control authority or exhaustive membership. */
+export function readRunDescendantLaunchLedger(stateDir, owner) {
+    if (!validOwner(owner))
+        return { state: "invalid" };
+    let canonical;
+    try {
+        canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+    }
+    catch {
+        return { state: "invalid" };
+    }
+    const path = join(canonical, RUN_DESCENDANT_LAUNCH_FILE);
+    try {
+        if (!lstatSync(path).isFile())
+            return { state: "invalid" };
+    }
+    catch (error) {
+        return { state: error.code === "ENOENT" ? "absent" : "invalid" };
+    }
+    const read = readJsonFileResilient(path, undefined);
+    if (read.diagnostics.length)
+        return { state: "invalid" };
+    const ledger = decode(read.value, owner, canonical);
+    return ledger ? { state: "available", ledger } : { state: "invalid" };
+}
+/** Retained preparation data is evidence, never a native-start or membership capability. */
+export function readRunDescendantPreparation(stateDir, child, parent) {
+    try {
+        const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+        const path = join(canonical, RUN_DESCENDANT_PREPARATION_FILE);
+        if (!lstatSync(path).isFile())
+            return undefined;
+        const value = decodePreparation(JSON.parse(readFileSync(path, "utf8")));
+        return value && child.state_dir === canonical && sameReference(value.child, child) && sameReference(value.parent, parent) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fresh evidence checks only, not a capability reconstructed from staged metadata. */
+export function assertRunDescendantPreparedMetadata(stateDir, child) {
+    const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+    let unpublished = false;
+    try {
+        lstatSync(join(canonical, "run.json"));
+    }
+    catch (error) {
+        unpublished = error.code === "ENOENT";
+    }
+    if (!unpublished)
+        throw new Error("Run descendant preparation is published or unavailable.");
+    const path = join(canonical, RUN_DESCENDANT_PREPARED_META_FILE);
+    if (!lstatSync(path).isFile())
+        throw new Error("Run descendant prepared metadata is unavailable or invalid.");
+    const meta = JSON.parse(readFileSync(path, "utf8"));
+    if (!record(meta) || meta.run !== child.run || meta.run_instance_id !== child.run_instance_id ||
+        meta.ownerId !== child.ownerId || meta.state_dir !== canonical || child.state_dir !== canonical ||
+        meta.pid !== 0 || meta.process_identity !== undefined) {
+        throw new Error("Run descendant prepared metadata is unavailable or invalid.");
+    }
+}
+/** Storage only: the kernel prepare-only branch owns child creation and holds parent then child lifecycle locks. */
+export function recordRunDescendantPreparationUnderLock(stateDir, child, parent, producer) {
+    const parentReference = decodeReference(parent);
+    if (!validOwner(producer) || !parentReference || parentReference.run !== producer.run ||
+        parentReference.run_instance_id !== producer.runInstanceId || parentReference.ownerId !== producer.ownerId) {
+        throw new Error("Run descendant preparation producer binding is invalid.");
+    }
+    const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+    assertNoRetainedDescendantFiles(canonical, [RUN_DESCENDANT_LAUNCH_FILE, RUN_DESCENDANT_PREPARATION_FILE]);
+    assertRunDescendantPreparedMetadata(canonical, child);
+    const preparation = decodePreparation({ schema: PREPARATION_SCHEMA, preparation_id: randomUUID(),
+        prepared_at: new Date().toISOString(), child, parent: parentReference,
+        parent_producer: { pid: producer.pid, process_identity_digest: producer.processIdentityDigest ?? null } });
+    if (!preparation || preparation.child.state_dir !== canonical)
+        throw new Error("Run descendant preparation binding is invalid.");
+    writeJsonAtomic(join(canonical, RUN_DESCENDANT_PREPARATION_FILE), preparation);
+    return preparation;
+}
+/** Storage only: bare intents require work admission; prepared facts may use evidence admission. Validate child evidence under its lock. */
+export function recordRunDescendantLaunchIntentUnderLock(stateDir, owner, request, preparation) {
+    if (!validOwner(owner))
+        throw new Error("Run descendant launch identity or request is invalid.");
+    const canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+    const child = resolveRunDescendantLaunchTarget(request, owner, canonical);
+    if (!child)
+        throw new Error("Run descendant launch identity or request is invalid.");
+    const current = readRunDescendantLaunchLedger(canonical, owner);
+    if (current.state === "invalid")
+        throw new Error("Run descendant launch evidence is unavailable or invalid.");
+    const prior = current.state === "available" ? current.ledger.intents : [];
+    const index = prior.findIndex((item) => item.child.run_instance_id === child.run_instance_id);
+    const existing = prior[index];
+    if (existing && preparation === undefined)
+        throw new Error("Run descendant launch generation is already retained.");
+    if (existing && !sameReference(existing.child, child))
+        throw new Error("Run descendant preparation target changed.");
+    let prepared;
+    if (preparation !== undefined) {
+        const parent = { run: owner.run, run_instance_id: owner.runInstanceId,
+            ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }), state_dir: canonical };
+        const claimed = decodePreparation(preparation);
+        if (!claimed || !sameReference(claimed.parent, parent) || !sameReference(claimed.child, child)) {
+            throw new Error("Run descendant preparation binding changed or is unavailable.");
+        }
+        if (existing?.preparation && (existing.preparation.preparation_id !== claimed.preparation_id ||
+            existing.preparation.prepared_at !== claimed.prepared_at)) {
+            throw new Error("Run descendant preparation binding changed or is unavailable.");
+        }
+        const retained = readRunDescendantPreparation(child.state_dir, child, parent);
+        if (!retained || JSON.stringify(claimed) !== JSON.stringify(retained)) {
+            throw new Error("Run descendant preparation binding changed or is unavailable.");
+        }
+        assertRunDescendantPreparedMetadata(child.state_dir, child);
+        if (existing?.preparation)
+            return existing;
+        if (!retained.parent_producer || retained.parent_producer.pid !== owner.pid ||
+            retained.parent_producer.process_identity_digest !== (owner.processIdentityDigest ?? null)) {
+            throw new Error("Run descendant preparation producer binding changed or is unavailable.");
+        }
+        prepared = Object.freeze({ preparation_id: retained.preparation_id, prepared_at: retained.prepared_at });
+    }
+    const intent = existing ? Object.freeze({ ...existing, preparation: prepared })
+        : Object.freeze({ intent_id: randomUUID(), admitted_at: new Date().toISOString(), child,
+            ...(prepared ? { preparation: prepared } : {}) });
+    const intents = existing ? prior.map((item, i) => i === index ? intent : item) : [...prior, intent];
+    const updated = decode({ 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 }, owner, canonical);
+    if (!updated)
+        throw new Error("Run descendant launch evidence is unavailable or invalid.");
+    writeJsonAtomic(join(canonical, RUN_DESCENDANT_LAUNCH_FILE), updated);
+    return updated.intents[existing ? index : updated.intents.length - 1];
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-execution-evidence.d.ts

@@ -0,0 +1,110 @@
+import { type RunContextIndexIdentity } from "./runs-context-index.ts";
+export interface ExecutionCaptureView {
+    readonly reported_saved_bytes: number | null;
+    readonly persistence: "incomplete" | "reported_complete" | "unproven";
+    readonly reported_observed_bytes?: number;
+    readonly error?: "capture_write_failed";
+}
+export interface ExecutionAttemptView {
+    readonly attempt: number;
+    readonly code: number;
+    readonly native_exit_code?: number | null;
+    readonly native_signal?: string;
+    readonly reported_killed?: boolean;
+    readonly stdout: Readonly<ExecutionCaptureView>;
+    readonly stderr: Readonly<ExecutionCaptureView>;
+}
+export interface ExecutionCommandView {
+    readonly id: string;
+    readonly reported_status: string;
+    readonly attempts: readonly Readonly<ExecutionAttemptView>[];
+    readonly stage?: string;
+    readonly command?: string;
+    readonly label?: string;
+    readonly occurrence?: number;
+    readonly branch_index?: number;
+    readonly prompt_bytes?: number;
+    readonly started_at?: string;
+    readonly completed_at?: string;
+    readonly semantic_acceptance?: string;
+    readonly exit_code?: number;
+    readonly effective_exit_code?: number;
+    readonly native_exit_code?: number | null;
+    readonly reported_killed?: boolean;
+    readonly interruption?: string;
+    readonly reported_session_file_count?: number;
+}
+export interface RunExecutionView {
+    readonly reported_status: string;
+    readonly updated_at: string;
+    readonly reported_active_subagents: number;
+    readonly commands_total: number;
+    readonly settled_attempts_reported: number;
+    readonly commands: readonly Readonly<ExecutionCommandView>[];
+}
+export type RunExecutionProjection = {
+    readonly state: "available";
+    readonly view: Readonly<RunExecutionView>;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "manifest_invalid" | "identity_mismatch";
+};
+/** Already-captured metadata is data, never a reconstructed producer/work/close capability. */
+export declare function projectRunExecutionManifest(expected: {
+    readonly run: string;
+    readonly run_instance_id: string;
+}, value: unknown, recipe?: Record<string, unknown>, redactEvidence?: (value: unknown) => unknown): Readonly<RunExecutionProjection>;
+export type KernelRunStreamSourceReading = {
+    readonly state: "available";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly stream: "stdout" | "stderr";
+    readonly source_scope: "canonical_runner_stream";
+    readonly visibility: "kernel_only";
+    readonly capture_completeness: "not_asserted";
+    readonly bytes_total: number;
+    readonly text: string;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "stream_invalid" | "identity_unavailable" | "identity_mismatch" | "observation_changed" | "stream_missing" | "stream_unavailable" | "stream_too_large" | "stream_invalid_text";
+};
+/** Never serialize this raw source as tool/model evidence: an export owner still owes a fixed privacy projection. */
+export declare function readRunStreamSource(stateDir: string, expected: unknown, stream: unknown): Readonly<KernelRunStreamSourceReading>;
+export type RunExecutionReferenceRequest = {
+    readonly kind: "capture";
+    readonly command_id: string;
+    readonly attempt: number;
+    readonly stream: "stdout" | "stderr";
+} | {
+    readonly kind: "session";
+    readonly command_id: string;
+    readonly path: string;
+};
+interface ExecutionReferenceMetadata {
+    readonly command_id: string;
+    readonly path: string;
+    readonly local_path: string;
+    readonly bytes_total: number;
+    readonly mutable: true;
+}
+export type RunExecutionReference = ExecutionReferenceMetadata & ({
+    readonly kind: "capture";
+    readonly attempt: number;
+    readonly stream: "stdout" | "stderr";
+    readonly capture: Readonly<ExecutionCaptureView>;
+} | {
+    readonly kind: "session";
+});
+export type RunExecutionReferenceReading = {
+    readonly state: "available";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly source_updated_at: string;
+    readonly reference: Readonly<RunExecutionReference>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "request_invalid" | "identity_unavailable" | "identity_mismatch" | "observation_changed" | "manifest_absent" | "manifest_unavailable" | "manifest_invalid" | "manifest_identity_mismatch" | "reference_not_recorded" | "reference_invalid" | "reference_missing" | "reference_unavailable" | "reference_changed" | "reference_size_unrepresentable" | "capture_size_mismatch";
+};
+/** Local paths and unchanged callbacks describe data only, never readable-body exposure or native capabilities. */
+export declare function readRunExecutionReference(stateDir: string, expected: unknown, query: unknown): Readonly<RunExecutionReferenceReading>;
+export {};