pi-daddy 0.22.0 → 0.23.0

package/src/execution-retention.ts

@@ -0,0 +1,230 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, writeFile, rename } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { buildExecutionRetentionManifest } from "./retention-contract.ts";
+import { missingNativeSession, readNativeSession, type NativeSessionObservation, type NativeSessionManager, type NativeSessionCapture } from "./native-session.ts";
+export { buildExecutionRetentionManifest, parseExecutionRetentionManifest, RETENTION_SCHEMA } from "./retention-contract.ts";
+export { ENV_NATIVE_SESSION_ROOT, readNativeSession, parseNativeSessionBytes, type NativeSessionObservation, type NativeSessionManager } from "./native-session.ts";
+
+/** Operator-owned archive boundary; never a model-facing parameter or an authority source. */
+export const ENV_EXECUTION_ARCHIVE = "PI_GRANTS_EXECUTION_ARCHIVE";
+export const RETENTION_VERSION = "2.0";
+const LIMIT = 1024 * 1024;
+const MAX_ACTIVE = 32;
+let active = 0;
+const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+export interface RetentionIdentity {
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  toolCallId: string | null;
+  executor: "process" | "herdr" | "check";
+  taskDigest: string | null;
+  definitionDigest: string | null;
+  configurationDigest: string;
+  workspaceId: string | null;
+}
+export interface RetainedContent {
+  status: "retained" | "missing";
+  path: string | null;
+  sha256: string | null;
+  bytes: number | null;
+}
+export interface ExecutionRetentionManifest {
+  version: "2.0";
+  archiveId: string;
+  identity: RetentionIdentity;
+  native: { pid: number | null; paneId: string | null; agentName: string | null; tabId: string | null;
+    sessionId: string | null; sessionPath: string | null; branchLeafId: string | null };
+  nativeSession: NativeSessionObservation;
+  state: "running" | "terminal";
+  outcome: { code: number | null; signal: string | null; timedOut: boolean; aborted: boolean;
+    truncated: boolean; failed: boolean } | null;
+  content: Record<"stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result" | "session", RetainedContent>;
+  coverage: { complete: false; losses: string[] };
+  /** Retention is observation, never a work-v4 acceptance decision. */
+  acceptance: "not-assessed";
+}
+export interface RetentionStatus { manifestPath: string | null; status: "disabled" | "pending" | "retained" | "lost" }
+const drains = new WeakMap<RetentionStatus, () => Promise<RetentionStatus>>();
+/** Original live status only; drains admitted observations, not producer completeness or fsync. */
+export function drainExecutionRetention(status: RetentionStatus): Promise<RetentionStatus> {
+  const drain = drains.get(status);
+  if (!drain) return Promise.reject(new TypeError("original live retention status required"));
+  return drain();
+}
+const missing = (): RetainedContent => ({ status: "missing", path: null, sha256: null, bytes: null });
+
+/** Hash only an explicitly selected configuration. Callers must not pass environment/auth objects. */
+export const retentionConfigurationDigest = (configuration: unknown): string => digest(JSON.stringify(configuration));
+
+/**
+ * A bounded, coalescing observation queue. No worker-control path awaits publication. A failed or stalled
+ * archive never changes required ledger/lease semantics. `flush` is exclusively for external archival at
+ * quiescence; it is NOT called by the spawner. Missing terminal publication means incomplete observation.
+ */
+export function beginExecutionRetention(identity: RetentionIdentity, directory = process.env[ENV_EXECUTION_ARCHIVE]) {
+  const archiveId = randomUUID();
+  const valid = Boolean(directory && isAbsolute(directory) && !directory.split(/[\\/]/).includes(".pi"));
+  const admitted = valid && active < MAX_ACTIVE;
+  const root = admitted ? join(directory!, archiveId) : null;
+  const manifestPath = root ? join(root, "manifest.json") : null;
+  let status: RetentionStatus["status"] = !directory ? "disabled" : admitted ? "pending" : "lost";
+  const manifest: ExecutionRetentionManifest = {
+    version: RETENTION_VERSION, archiveId, identity: {
+      executionId: identity.executionId, parentExecutionId: identity.parentExecutionId, childId: identity.childId,
+      toolCallId: identity.toolCallId, executor: identity.executor, taskDigest: identity.taskDigest,
+      definitionDigest: identity.definitionDigest, configurationDigest: identity.configurationDigest, workspaceId: identity.workspaceId,
+    },
+    native: { pid: null, paneId: null, agentName: null, tabId: null, sessionId: null, sessionPath: null, branchLeafId: null },
+    nativeSession: missingNativeSession(),
+    state: "running", outcome: null,
+    content: { stdout: missing(), stderr: missing(), paneSnapshot: missing(), checkReceipt: missing(), result: missing(), session: missing() },
+    coverage: { complete: false, losses: ["native-session-content-unavailable", "active-branch-unknown"] },
+    acceptance: "not-assessed",
+  };
+  const buffers = new Map<keyof typeof manifest.content, Buffer>();
+  const written = new Set<string>();
+  let total = 0;
+  let dirty = false;
+  let running: Promise<void> | undefined;
+  let finished = false;
+  let released = false;
+  let nativeTask: Promise<void> | undefined;
+  let nextNative: { source: "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager"; value: string; manager?: NativeSessionManager } | undefined;
+  let pinnedSessionId: string | undefined;
+  let pinnedFile: NativeSessionCapture["fileIdentity"];
+  const loss = (reason: string) => { if (!manifest.coverage.losses.includes(reason)) manifest.coverage.losses.push(reason); };
+  const release = () => { if (admitted && !released) { active--; released = true; } };
+  if (admitted) active++;
+  else if (directory) loss("archive-unavailable-or-capacity-exceeded");
+  const publish = async () => {
+    try {
+      await mkdir(root!, { recursive: true, mode: 0o700 });
+      while (dirty) {
+        dirty = false;
+        // Detached checkpoint: asynchronous I/O cannot mix later outcome/content into this generation.
+        const checkpoint: ExecutionRetentionManifest = JSON.parse(JSON.stringify(manifest));
+        const contents = [...buffers];
+        for (const [kind, bytes] of contents) {
+          const sha256 = digest(bytes);
+          const name = `${kind}-${sha256}.bin`;
+          if (!written.has(name)) {
+            await writeFile(join(root!, name), bytes, { flag: "wx", mode: 0o600 });
+            written.add(name);
+          }
+          checkpoint.content[kind] = { status: "retained", path: name, sha256, bytes: bytes.length };
+        }
+        await writeFile(join(root!, "manifest.pending"), JSON.stringify(buildExecutionRetentionManifest(checkpoint)) + "\n", { mode: 0o600 });
+        await rename(join(root!, "manifest.pending"), manifestPath!);
+        status = "retained";
+      }
+    } catch {
+      status = "lost";
+      loss("archive-write-failed");
+      buffers.clear();
+      release();
+    } finally {
+      running = undefined;
+      if (finished && !nativeTask) { buffers.clear(); release(); }
+    }
+  };
+  const schedule = () => {
+    if (!admitted || status === "lost" || released) return;
+    dirty = true;
+    status = "pending";
+    if (!running) running = Promise.resolve().then(publish);
+  };
+  const observeSession = (reference: NonNullable<typeof nextNative>) => {
+    if (finished || !admitted || released || status === "lost") return;
+    if (nextNative && (nextNative.source !== reference.source || nextNative.value !== reference.value)) loss("native-session-reference-coalesced");
+    nextNative = { source: reference.source, value: reference.value, ...(reference.manager ? { manager: reference.manager } : {}) };
+    if (nativeTask) return;
+    nativeTask = Promise.resolve().then(async () => {
+      while (nextNative) {
+        const current = nextNative; nextNative = undefined;
+        const captured: NativeSessionCapture = current.source === "herdr-id"
+          ? { observation: { ...missingNativeSession(), source: current.source, status: "missing" as const,
+              sessionId: current.value, reason: "native-session-path-unavailable" } }
+          : await readNativeSession({ path: current.value, source: current.source, manager: current.manager, expectedSessionId: pinnedSessionId, expectedFile: pinnedFile });
+        if (captured.observation.sessionId && captured.fileIdentity) pinnedFile ??= captured.fileIdentity;
+        let observation = captured.observation;
+        if (pinnedSessionId && observation.sessionId && pinnedSessionId !== observation.sessionId) {
+          observation = { ...missingNativeSession(), source: current.source, status: "changed", reason: "native-session-id-changed" };
+        }
+        if (observation.sessionId) pinnedSessionId ??= observation.sessionId;
+        manifest.nativeSession = { ...observation };
+        manifest.native.sessionId = observation.sessionId;
+        manifest.native.sessionPath = observation.sessionPath;
+        manifest.native.branchLeafId = observation.branchLeafId;
+        buffers.delete("session");
+        if (captured.bytes && observation === captured.observation) buffers.set("session", captured.bytes);
+        if (observation.reason) loss(observation.reason);
+        schedule();
+      }
+    }).catch(() => { loss("native-session-observation-failed"); }).finally(() => { nativeTask = undefined; schedule(); });
+  };
+  const drain = async (): Promise<RetentionStatus> => {
+    while (nativeTask || running) { if (nativeTask) await nativeTask; if (running) await running; }
+    return { manifestPath, status };
+  };
+  schedule();
+  return {
+    /** Read-only native API reference; never derive IDs from the locator or a displayed name. */
+    observeSession,
+    observeSessionManager(manager: NativeSessionManager) {
+      try {
+        const value = manager.getSessionFile();
+        if (value) observeSession({ source: "pi-session-manager", value, manager });
+        else { loss("native-session-not-persisted"); schedule(); }
+      } catch { loss("native-session-manager-unavailable"); schedule(); }
+    },
+    status: (): RetentionStatus => { const value = { manifestPath, status }; drains.set(value, drain); return value; },
+    native(value: Partial<Pick<ExecutionRetentionManifest["native"], "pid" | "paneId" | "agentName" | "tabId">>) {
+      if (finished) return;
+      for (const key of ["pid", "paneId", "agentName", "tabId"] as const) {
+        const item = value[key];
+        if (key === "pid") { if (typeof item === "number" && Number.isSafeInteger(item) && item > 0) manifest.native.pid = item; }
+        else if (typeof item === "string" && item.length <= 4096) manifest.native[key] = item;
+      }
+      schedule();
+    },
+    capture(kind: "stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result", bytes: Uint8Array, replace = false) {
+      if (finished || !admitted || status === "lost") return;
+      const indivisible = kind === "checkReceipt" || kind === "result";
+      if (indivisible) replace = true;
+      const old = buffers.get(kind) ?? Buffer.alloc(0);
+      const available = indivisible ? LIMIT : LIMIT - total + (replace ? old.length : 0);
+      // Receipts and assembled results each have reserved capacity and are never partially published.
+      if (indivisible && bytes.length > available) { loss(`${kind === "checkReceipt" ? "check-receipt" : kind}-not-retained-capacity`); schedule(); return; }
+      const kept = Buffer.from(bytes.subarray(0, Math.max(0, available)));
+      if (kept.length !== bytes.length) loss(`${kind}-observation-dropped`);
+      if (kind === "paneSnapshot") loss("pane-snapshot-not-full-transcript");
+      const next = replace ? kept : Buffer.concat([old, kept]);
+      if (!indivisible) total += next.length - old.length;
+      buffers.set(kind, next);
+      schedule();
+    },
+    finish(outcome: NonNullable<ExecutionRetentionManifest["outcome"]>) {
+      if (finished) return;
+      manifest.outcome = { code: outcome.code, signal: outcome.signal, timedOut: outcome.timedOut,
+        aborted: outcome.aborted, truncated: outcome.truncated, failed: outcome.failed };
+      manifest.state = "terminal";
+      if (outcome.truncated) loss("executor-output-truncated");
+      if (outcome.aborted || outcome.timedOut) loss("execution-interrupted");
+      finished = true;
+      schedule();
+    },
+    /** Observation-only diagnostic; never establishes successful execution or accepted work. */
+    coverage: () => ({ complete: false as const, losses: [...manifest.coverage.losses] }),
+    flush: drain,
+  };
+}
+export type ExecutionRetention = ReturnType<typeof beginExecutionRetention>;
+
+/** Public consumer check: neither a reference nor a wire status supplies the missing bytes. */
+export function verifyRetainedBytes(reference: RetainedContent, bytes?: Uint8Array): "retained" | "missing" | "mismatch" {
+  if (reference.status !== "retained" || bytes === undefined) return "missing";
+  if (reference.bytes !== bytes.byteLength || reference.sha256 !== digest(bytes)) return "mismatch";
+  return "retained";
+}

package/src/experiment-contract.ts

@@ -0,0 +1,66 @@
+import type { WorkFrozen } from "./work-ledger-types.ts";
+import { createHash } from "node:crypto";
+import { intentKey, type WorkIntentBinding } from "./intent-control.ts";
+import { workIntentBinding } from "./intent-application.ts";
+import { freezeWork, parseWorkJson } from "./work-ledger-json.ts";
+import { orderSchedule, type OrderSchedule } from "./order-schedule.ts";
+import { DIGEST_PROFILE } from "./effect-profile.ts";
+export const experimentHash = (value: unknown) => createHash("sha256").update(intentKey(value)).digest("hex");
+export const byteHash = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+export const cloneExperiment = <T>(value: T): T => JSON.parse(intentKey(value));
+export function closed(value: unknown, keys: string[]): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Object.keys(value).sort().join() !== keys.sort().join()) throw new TypeError("closed experiment data required");
+}
+const id = (x: unknown) => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
+const hex = (x: unknown) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+export interface ExperimentVariant {
+  variantId: string; executionId: string; kind: "primary" | "shadow" | "retry";
+  parentExecutionId: string | null; suffixBase64: string; operation: "digest" | "hold";
+  configuration: { model: null; effort: null; skills: null };
+}
+export interface ExperimentCharter {
+  version: "fixed-experiment-v1" | "fixed-experiment-v2"; order?: OrderSchedule; experimentId: string; orderId: string; budgetDigest: string;
+  profile: typeof DIGEST_PROFILE; common: { sha256: string; bytes: number; work: WorkFrozen<WorkIntentBinding> | null; workTextDigest: string | null };
+  mode: "bounded-waves" | "concurrent-shadow"; deadlineMs: number; variants: readonly ExperimentVariant[];
+}
+export function experimentCharter(input: ExperimentCharter): ExperimentCharter {
+  const c = cloneExperiment(input); closed(c, ["version", "experimentId", "orderId", "budgetDigest", "profile", "common", "mode", "deadlineMs", "variants", ...(c.version === "fixed-experiment-v2" ? ["order"] : [])]);
+  if (!["fixed-experiment-v1", "fixed-experiment-v2"].includes(c.version) || !id(c.experimentId) || !id(c.orderId) || !hex(c.budgetDigest) || c.profile !== DIGEST_PROFILE || !["bounded-waves", "concurrent-shadow"].includes(c.mode) || !Number.isSafeInteger(c.deadlineMs) || c.deadlineMs < 1000 || c.deadlineMs > 30000 || Buffer.byteLength(intentKey(c)) > 48000) throw new TypeError("unsupported experiment charter/profile");
+  closed(c.common, ["sha256", "bytes", "work", "workTextDigest"]);
+  if (!hex(c.common.sha256) || !Number.isSafeInteger(c.common.bytes) || c.common.bytes < 0 || c.common.bytes > 16384) throw new TypeError("bounded common input required");
+  if (c.common.work !== null) { c.common.work = workIntentBinding(JSON.parse(intentKey(c.common.work))); if (!hex(c.common.workTextDigest)) throw new TypeError("exact work bytes required"); }
+  else if (c.common.workTextDigest !== null) throw new TypeError("unexpected work digest");
+  if (!Array.isArray(c.variants) || c.variants.length < (c.version === "fixed-experiment-v2" ? 1 : 2) || c.variants.length > 32) throw new TypeError("2..32 explicit attempts required");
+  const ids = new Set<string>(), variants = new Set<string>();
+  for (const [i, v] of (c.variants as readonly ExperimentVariant[]).entries()) {
+    closed(v, ["variantId", "executionId", "kind", "parentExecutionId", "suffixBase64", "operation", "configuration"]);
+    closed(v.configuration, ["model", "effort", "skills"]);
+    if (!id(v.variantId) || !id(v.executionId) || ids.has(v.executionId) || variants.has(v.variantId) || !["digest", "hold"].includes(v.operation) || Object.values(v.configuration).some(x => x !== null)) throw new TypeError("unknown/general configuration cannot execute");
+    if (c.version === "fixed-experiment-v2" ? !["primary", "retry"].includes(v.kind) || (v.kind === "primary" ? v.parentExecutionId !== null : !ids.has(v.parentExecutionId!)) : i === 0 ? v.kind !== "primary" || v.parentExecutionId !== null || v.operation !== "digest" : !["shadow", "retry"].includes(v.kind) || !ids.has(v.parentExecutionId!)) throw new TypeError("explicit ordered parent/primary required");
+    if (typeof v.suffixBase64 !== "string" || v.suffixBase64.length > 22000 || Buffer.from(v.suffixBase64, "base64").toString("base64") !== v.suffixBase64 || c.common.bytes + Buffer.from(v.suffixBase64, "base64").length > 16384) throw new TypeError("invalid bounded byte difference");
+    ids.add(v.executionId); variants.add(v.variantId);
+  }
+  if (c.mode === "concurrent-shadow" && (c.variants.length !== 2 || c.variants[1].kind !== "shadow")) throw new TypeError("concurrent shadow requires exactly primary and shadow");
+  if (c.version === "fixed-experiment-v2") {
+    if (c.mode !== "bounded-waves" || !c.common.work) throw new Error("orders require pinned work and bounded scheduling");
+    c.order = orderSchedule(c.order!, c.variants.map(v => v.executionId));
+    for (const n of c.order.nodes) for (const [i,id] of n.executions.entries()) { const v=c.variants.find(v=>v.executionId===id)!; if(i ? v.kind!=="retry"||v.parentExecutionId!==n.executions[i-1] : v.kind!=="primary") throw new Error("node recovery lineage mismatch"); }
+  }
+  return freezeWork(c) as ExperimentCharter;
+}
+export const parseExperimentCharter = (text: string) => experimentCharter(parseWorkJson(text) as unknown as ExperimentCharter);
+export const experimentCharterDigest = (c: ExperimentCharter) => experimentHash(experimentCharter(c));
+export interface ExperimentAuthority { authorityDigest: string; charterDigests: readonly string[]; cancellationDigests: readonly string[] }
+export function experimentAuthority(value: ExperimentAuthority | null): ExperimentAuthority | null {
+  if (value === null) return null;
+  const a = cloneExperiment(value); closed(a, ["authorityDigest", "charterDigests", "cancellationDigests"]);
+  if (!hex(a.authorityDigest) || [a.charterDigests, a.cancellationDigests].some(xs => !Array.isArray(xs) || xs.length > 128 || xs.some(x => !hex(x)))) throw new TypeError("independent bounded host approvals required");
+  return freezeWork(a);
+}
+export interface ExperimentCancellation { version: "experiment-cancel-v1"; requestId: string; bindingDigest: string; executionId: string }
+export function experimentCancellation(value: ExperimentCancellation): ExperimentCancellation {
+  const c = cloneExperiment(value); closed(c, ["version", "requestId", "bindingDigest", "executionId"]);
+  if (c.version !== "experiment-cancel-v1" || !id(c.requestId) || !hex(c.bindingDigest) || !id(c.executionId)) throw new TypeError("exact cancellation required");
+  return freezeWork(c);
+}
+export const experimentCancellationDigest = (c: ExperimentCancellation) => experimentHash(experimentCancellation(c));

package/src/experiment-state.ts

@@ -0,0 +1,44 @@
+import { closed, experimentCancellation, type ExperimentCancellation, type ExperimentCharter, type ExperimentVariant } from "./experiment-contract.ts";
+import { factoryDecision, type FactoryDecision } from "./order-schedule.ts";
+export type VariantState = "unstarted" | "queued" | "dispatching" | "running" | "completed" | "failed" | "cancelled" | "timed-out" | "unknown";
+export interface VariantRecord extends Pick<ExperimentVariant, "variantId" | "kind" | "operation"> { executionId: string; state: VariantState; artifactDigest: string | null; spawned: boolean }
+export function replayExperiment(c: ExperimentCharter, events: Record<string, unknown>[]) {
+  let claim: { owner: string; deadlineAt: number } | null = null, admitted = false;
+  const variants: VariantRecord[] = c.variants.map(v => ({ variantId: v.variantId, kind: v.kind, operation: v.operation, executionId: v.executionId, state: "unstarted", artifactDigest: null, spawned: false }));
+  const cancellations: ExperimentCancellation[] = [], decisions: FactoryDecision[] = [];
+  let superseded = false, controllerFailed = false;
+  for (const e of events) {
+    if (e.type === "order-decision") {
+      closed(e,["type","request"]);const d=factoryDecision(e.request as FactoryDecision);
+      if(!c.order || !c.order.nodes.some(n=>n.nodeId===d.nodeId&&n.decision?.authorityId===d.authorityId)||decisions.some(r=>r.nodeId===d.nodeId||r.requestId===d.requestId))throw new Error("invalid order decision sequence");decisions.push(d);
+    } else if(e.type === "order-migrated") {
+      closed(e,["type","requestId","successorDigest"]);if(!c.order||claim||superseded||typeof e.requestId!=="string"||typeof e.successorDigest!=="string"||!/^[a-f0-9]{64}$/.test(e.successorDigest))throw new Error("migration requires unstarted order");superseded=true;
+    } else if (e.type === "claim") {
+      closed(e, ["type", "owner", "deadlineAt"]);
+      if (superseded || claim || typeof e.owner !== "string" || !/^[a-f0-9-]{36}$/.test(e.owner) || !Number.isSafeInteger(e.deadlineAt)) throw new Error("invalid experiment claim");
+      claim = { owner: e.owner, deadlineAt: e.deadlineAt as number }; variants.forEach(v => v.state = "queued");
+    } else if (e.type === "admitted") {
+      closed(e, ["type"]); if (!claim || admitted) throw new Error("invalid experiment admission"); admitted = true;
+    } else if (e.type === "cancel") {
+      closed(e, ["type", "request"]); const request = experimentCancellation(e.request as ExperimentCancellation);
+      if (!variants.some(v => v.executionId === request.executionId) || cancellations.some(r => r.requestId === request.requestId) || cancellations.length >= 64) throw new Error("invalid cancellation sequence");
+      cancellations.push(request);
+    } else if (e.type === "controller-unknown") {
+      closed(e, ["type"]); if (!claim) throw new Error("missing claim"); controllerFailed = true;
+      variants.filter(v => v.artifactDigest === null).forEach(v => v.state = "unknown");
+    } else {
+      const v = variants.find(v => v.executionId === e.executionId);
+      if (!claim || !admitted || !v || v.artifactDigest !== null) throw new Error("invalid variant sequence");
+      if (e.type === "dispatch") {
+        closed(e, ["type", "executionId"]); if (v.state !== "queued") throw new Error("duplicate dispatch"); v.state = "dispatching";
+      } else if (e.type === "spawn") {
+        closed(e, ["type", "executionId"]); if (v.state !== "dispatching") throw new Error("invalid spawn observation"); v.state = "running"; v.spawned = true;
+      } else if (e.type === "result") {
+        closed(e, ["type", "executionId", "state", "artifactDigest"]);
+        if (!["dispatching", "running"].includes(v.state) || !["completed", "failed", "cancelled", "timed-out"].includes(String(e.state)) || typeof e.artifactDigest !== "string" || !/^[a-f0-9]{64}$/.test(e.artifactDigest)) throw new Error("invalid result observation");
+        v.state = e.state as VariantState; v.artifactDigest = e.artifactDigest;
+      } else throw new Error("unknown experiment event");
+    }
+  }
+  return { claim, admitted, variants, cancellations, decisions, superseded, controllerFailed };
+}

package/src/experiment-store.ts

@@ -0,0 +1,90 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { withFileLock } from "./file-lock.ts";
+import { runWithFinalizers } from "./finalization.ts";
+import { parseWorkJson, freezeWork } from "./work-ledger-json.ts";
+import { resourceBindingDigest, type ExperimentBudgetBinding } from "./resource-budget.ts";
+import { byteHash, cloneExperiment, closed, experimentCharter, experimentHash, type ExperimentCharter } from "./experiment-contract.ts";
+export interface ExperimentBinding { version: "experiment-binding-v1"; directory: string; device: string; inode: string; journalDevice: string; journalInode: string; budget: ExperimentBudgetBinding; charter: ExperimentCharter }
+export const experimentBindingDigest = (b: ExperimentBinding) => experimentHash(b);
+export async function ownedDirectory(path: string) {
+  const s = await lstat(path, { bigint: true });
+  if (!s.isDirectory() || s.isSymbolicLink() || s.uid !== BigInt(process.getuid!()) || (s.mode & 0o077n) !== 0n || await realpath(path) !== path) throw new Error("canonical private experiment directory required");
+  return s;
+}
+export async function readExperimentFile(path: string, max: number): Promise<Buffer> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  return runWithFinalizers(async () => {
+    const s = await file.stat({ bigint: true });
+    if (!s.isFile() || s.nlink !== 1n || s.uid !== BigInt(process.getuid!()) || (s.mode & 0o077n) !== 0n || s.size > BigInt(max)) throw new Error("unsafe experiment file");
+    const data = Buffer.alloc(Number(s.size)); let offset = 0;
+    while (offset < data.length) { const n = (await file.read(data, offset, data.length - offset, offset)).bytesRead; if (!n) throw new Error("short experiment read"); offset += n; }
+    const end = await file.stat({ bigint: true }), current = await lstat(path, { bigint: true });
+    if (end.size !== s.size || end.mtimeNs !== s.mtimeNs || current.dev !== s.dev || current.ino !== s.ino || current.nlink !== 1n) throw new Error("experiment source changed");
+    return data;
+  }, [{ label: "experiment read close failed", run: () => file.close() }]);
+}
+export async function writeExperimentFile(path: string, bytes: Uint8Array) {
+  const f = await open(path, "wx", 0o600);
+  await runWithFinalizers(async () => { await f.writeFile(bytes); await f.sync(); await f.chmod(0o400); }, [{ label: "experiment artifact close failed", run: () => f.close() }]);
+  const dir = await open(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY);
+  await runWithFinalizers(() => dir.sync(), [{ label: "experiment artifact directory close failed", run: () => dir.close() }]);
+}
+export function validateExperimentBinding(value: ExperimentBinding): ExperimentBinding {
+  const b = cloneExperiment(value); closed(b, ["version", "directory", "device", "inode", "journalDevice", "journalInode", "budget", "charter"]);
+  if (b.version !== "experiment-binding-v1" || typeof b.directory !== "string" || b.directory !== resolve(b.directory) || b.directory.length > 1024 || b.directory.split("/").includes(".pi") || [b.device, b.inode, b.journalDevice, b.journalInode].some(v => typeof v !== "string" || !/^\d+$/.test(v)) || b.budget.version !== "4.0") throw new TypeError("independent experiment binding required");
+  b.charter = experimentCharter(b.charter);
+  if (resourceBindingDigest(b.budget) !== b.charter.budgetDigest) throw new TypeError("experiment budget mismatch");
+  return freezeWork(b) as ExperimentBinding;
+}
+export async function createExperimentStore(directory: string, budget: ExperimentBudgetBinding, charter: ExperimentCharter, bytes: Uint8Array): Promise<ExperimentBinding> {
+  if (directory !== resolve(directory) || directory.split("/").includes(".pi")) throw new Error("explicit unprotected absolute destination required");
+  await ownedDirectory(dirname(directory)); await mkdir(directory, { mode: 0o700 }); const s = await ownedDirectory(directory);
+  await writeExperimentFile(join(directory, "common.bin"), bytes);
+  for (const v of charter.variants) await mkdir(join(directory, "variant-" + byteHash(v.executionId)), { mode: 0o700 });
+  const journal = await open(join(directory, "experiment.jsonl"), "wx", 0o600);
+  const b = await runWithFinalizers(async () => {
+    const st = await journal.stat({ bigint: true });
+    const value = validateExperimentBinding({ version: "experiment-binding-v1", directory, device: String(s.dev), inode: String(s.ino), journalDevice: String(st.dev), journalInode: String(st.ino), budget, charter });
+    await journal.writeFile(JSON.stringify(value) + "\n"); await journal.sync(); return value;
+  }, [{ label: "experiment creation close failed", run: () => journal.close() }]);
+  const dir = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY);
+  await runWithFinalizers(() => dir.sync(), [{ label: "experiment creation directory close failed", run: () => dir.close() }]); return b;
+}
+export function experimentStore(value: ExperimentBinding) {
+  const b = validateExperimentBinding(value), path = join(b.directory, "experiment.jsonl");
+  const check = async () => {
+    const root = await ownedDirectory(b.directory), file = await lstat(path, { bigint: true });
+    if (String(root.dev) !== b.device || String(root.ino) !== b.inode || String(file.dev) !== b.journalDevice || String(file.ino) !== b.journalInode) throw new Error("experiment identity replaced");
+  };
+  const read = async () => {
+    await check(); const bytes = await readExperimentFile(path, 256 * 1024); await check();
+    const text = new TextDecoder("utf8", { fatal: true }).decode(bytes); if (!text.endsWith("\n")) throw new Error("torn experiment journal");
+    const lines = text.slice(0, -1).split("\n"); if (lines.length > 260 || experimentHash(parseWorkJson(lines[0])) !== experimentHash(b)) throw new Error("experiment header/bound mismatch");
+    let previous = experimentHash(b); const events: Record<string, unknown>[] = [];
+    for (const line of lines.slice(1)) {
+      const record = parseWorkJson(line) as Record<string, unknown>; closed(record, ["seq", "previous", "event"]);
+      if (record.seq !== events.length || record.previous !== previous || !record.event || typeof record.event !== "object" || Array.isArray(record.event)) throw new Error("invalid experiment sequence");
+      previous = experimentHash(record); events.push(record.event as Record<string, unknown>);
+    }
+    return { events, previous, bytes: bytes.length };
+  };
+  return { binding: b, read, async transaction<T>(fn: (events: Record<string, unknown>[], append: (event: unknown) => Promise<void>) => Promise<T>) {
+    await check(); return withFileLock(path, "experiment", async () => {
+      const state = await read(); let size = state.bytes;
+      return fn(state.events, async event => {
+        if (state.events.length >= 258) throw new Error("experiment record bound reached");
+        const record = { seq: state.events.length, previous: state.previous, event }, data = Buffer.from(JSON.stringify(record) + "\n");
+        if (size + data.length > 256 * 1024) throw new Error("experiment journal byte bound reached");
+        await check(); const f = await open(path, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        await runWithFinalizers(async () => {
+          const s = await f.stat({ bigint: true });
+          if (!s.isFile() || s.nlink !== 1n || String(s.dev) !== b.journalDevice || String(s.ino) !== b.journalInode || s.size !== BigInt(size) || (s.mode & 0o077n) !== 0n) throw new Error("journal changed under lock");
+          await f.writeFile(data); await f.sync();
+        }, [{ label: "experiment append close failed", run: () => f.close() }]);
+        size += data.length; await check(); state.previous = experimentHash(record); state.events.push(cloneExperiment(event) as Record<string, unknown>);
+      });
+    }, { staleRecovery: "disabled" });
+  } };
+}