@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/workspace-lifecycle.ts

@@ -1,141 +0,0 @@
-/** P.3: execution owns checkpoints; session opening owns no filesystem baseline. */
-import { randomUUID } from "node:crypto";
-import type { CheckpointEvent, FileVersion, FileChanges, WorkspaceObservationEvent } from "../core/checkpoints.ts";
-import { sameVersion } from "../core/checkpoints.ts";
-import { blobAddress } from "../store/blobs.ts";
-import { archiveEdit, replaceFile, readEditableFile } from "../store/file-checkpoints.ts";
-import { GitCheckpoints, type GitCheckpoint } from "../store/git-checkpoints.ts";
-import { observeWorkspace } from "../store/workspace-observation.ts";
-import type { ToolResult } from "./tools.ts";
-import type { JsonValue } from "../core/tool-contract.ts";
-
-type Record = Omit<CheckpointEvent, "id" | "at"> | Omit<WorkspaceObservationEvent, "id" | "at">;
-interface CommandCheckpoint { operation: string; snapshot?: GitCheckpoint; unavailable?: string; }
-export class WorkspaceLifecycle {
-  readonly root: string;
-  readonly blobs: string;
-  readonly shellCheckpoints: boolean;
-  private readonly record: (event: Record) => Promise<void>;
-  private readonly ownedPaths: readonly string[];
-  private readonly git: GitCheckpoints;
-  private readonly pending = new Map<number, CommandCheckpoint>();
-  private fingerprint: string | undefined;
-  constructor(root: string, blobs: string, shellCheckpoints: boolean, record: (event: Record) => Promise<void>, checkpointStorage = blobs, ownedPaths: readonly string[] = []) {
-    this.root = root; this.blobs = blobs; this.shellCheckpoints = shellCheckpoints; this.record = record;
-    this.ownedPaths = ownedPaths;
-    this.git = new GitCheckpoints(root, checkpointStorage, ownedPaths);
-  }
-  private interfere(): void {
-    for (const checkpoint of this.pending.values()) checkpoint.unavailable = "overlapping mutations prevent attributing a command checkpoint";
-  }
-  async patch(changes: FileChanges, execute: () => Promise<void>, signal?: AbortSignal): Promise<void> {
-    signal?.throwIfAborted(); this.interfere();
-    const operation = randomUUID();
-    await this.record({ t: "checkpoint", operation, source: "edit", phase: "prepared", changes });
-    try {
-      await execute();
-      for (const [path, change] of Object.entries(changes)) if (!sameVersion((await readEditableFile(this.root, path)).version, change.after)) throw Error(`file changed concurrently after patch: ${path}`);
-      await this.record({ t: "checkpoint", operation, source: "edit", phase: "applied", changes });
-    } catch (error) {
-      await this.record({ t: "checkpoint", operation, source: "edit", phase: "unavailable", changes, reason: "patch did not establish the expected versions; inspect before retrying" });
-      throw error;
-    }
-  }
-  async edit(path: string, before: { bytes: Uint8Array | null; version: FileVersion }, after: Uint8Array, signal?: AbortSignal): Promise<void> {
-    this.interfere();
-    await archiveEdit(this.blobs, before.bytes, after);
-    const operation = randomUUID();
-    const next = { sha256: blobAddress(after), mode: before.version?.mode ?? (0o666 & ~process.umask()) };
-    const changes = { [path]: { before: before.version, after: next } };
-    await this.record({ t: "checkpoint", operation, source: "edit", phase: "prepared", changes });
-    try {
-      await replaceFile(this.root, path, before.version, after, next.mode, signal);
-      const actual = (await readEditableFile(this.root, path)).version;
-      if (!sameVersion(actual, next)) throw new Error(`file changed concurrently after editing: ${path}`);
-      await this.record({ t: "checkpoint", operation, source: "edit", phase: "applied", changes });
-    } catch (error) {
-      await this.record({ t: "checkpoint", operation, source: "edit", phase: "unavailable", changes,
-        reason: "edit did not establish the expected file version; inspect before retrying" });
-      throw error;
-    }
-  }
-  async command(name: string, input: unknown, execute: () => Promise<ToolResult>, signal?: AbortSignal): Promise<ToolResult> {
-    const args = input as { session_id?: number };
-    let checkpoint: CommandCheckpoint | undefined;
-    if (name === "write_stdin") checkpoint = args.session_id === undefined ? undefined : this.pending.get(args.session_id);
-    else {
-      this.interfere();
-      if (this.shellCheckpoints) {
-        checkpoint = { operation: randomUUID() };
-        try {
-          if (this.pending.size) throw new Error("another command is still running");
-          checkpoint.snapshot = await this.git.capture(signal);
-          await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "prepared", changes: {}, tree: checkpoint.snapshot.tree });
-        } catch (error) { checkpoint.unavailable = error instanceof Error ? error.message : "Git checkpoint unavailable"; }
-      }
-    }
-    const result = await execute();
-    if (!checkpoint) return result;
-    const data = (result.data && typeof result.data === "object" && !Array.isArray(result.data) ? result.data : {}) as { readonly [key: string]: JsonValue };
-    const session = data["session_id"];
-    if (data["running"] === true && typeof session === "number") {
-      this.pending.set(session, checkpoint);
-      return { ...result, data: { ...data, checkpoint: "pending" } };
-    }
-    if (typeof args.session_id === "number") this.pending.delete(args.session_id);
-    try {
-      if (checkpoint.unavailable || !checkpoint.snapshot) throw new Error(checkpoint.unavailable ?? "missing command baseline");
-      const snapshot = await this.git.capture(signal);
-      const changes = await this.git.changes(checkpoint.snapshot, snapshot, this.blobs, signal);
-      await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "applied", changes, tree: snapshot.tree });
-      return { ...result, data: { ...data, checkpoint: "captured" } };
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : "Git checkpoint unavailable";
-      await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "unavailable", changes: {}, reason });
-      return { ...result, content: `${result.content}\nFile recovery unavailable: ${reason}. The command result is unchanged.`, data: { ...data, checkpoint: "unavailable" } };
-    }
-  }
-  async abandonCommands(): Promise<void> {
-    for (const checkpoint of this.pending.values()) await this.record({ t: "checkpoint", operation: checkpoint.operation,
-      source: "git", phase: "unavailable", changes: {}, reason: "process ended without an observed checkpoint boundary" });
-    this.pending.clear();
-  }
-  /**
-   * A full source snapshot through the private Git checkpoint store, or null
-   * where Git checkpoints cannot run (not a Git working directory, over
-   * budget). Never touches the user's HEAD, index or stash (P.3).
-   */
-  async snapshot(signal?: AbortSignal): Promise<GitCheckpoint | null> {
-    try { return await this.git.capture(signal); } catch { return null; }
-  }
-
-  /** What changed between two snapshots, with both versions' bytes in the blob store. */
-  async snapshotChanges(before: GitCheckpoint, after: GitCheckpoint, signal?: AbortSignal): Promise<FileChanges> {
-    return this.git.changes(before, after, this.blobs, signal);
-  }
-
-  /**
-   * Records the workspace as a goal request begins, always: the state a
-   * counter-check must rebuild exactly before it may run (feat-counter-check).
-   */
-  async baseline(signal?: AbortSignal): Promise<void> {
-    const observation = await observeWorkspace(this.root, signal, this.ownedPaths);
-    const fingerprint = observation.ok ? observation.fingerprint : undefined;
-    await this.record({ t: "workspace_observation", scope: "source-v1", baseline: true,
-      changed: !observation.ok || this.fingerprint !== undefined && fingerprint !== this.fingerprint,
-      ...(observation.ok ? { fingerprint: observation.fingerprint } : { reason: observation.reason }) });
-    this.fingerprint = fingerprint;
-  }
-
-  async observe(previous?: string, signal?: AbortSignal): Promise<void> {
-    const observation = await observeWorkspace(this.root, signal, this.ownedPaths);
-    const fingerprint = observation.ok ? observation.fingerprint : undefined;
-    // S.1: an observation identical to the last known fingerprint adds no fact.
-    // Failures, a first look without a baseline, and changes are still recorded.
-    const known = previous ?? this.fingerprint;
-    if (fingerprint !== undefined && known !== undefined && fingerprint === known) { this.fingerprint = fingerprint; return; }
-    await this.record({ t: "workspace_observation", scope: "source-v1", changed: !observation.ok || (previous ?? this.fingerprint) !== undefined && fingerprint !== (previous ?? this.fingerprint),
-      ...(observation.ok ? { fingerprint: observation.fingerprint } : { reason: observation.reason }) });
-    this.fingerprint = fingerprint;
-  }
-}

package/src/store/acceptance.ts

@@ -1,15 +0,0 @@
-/** Explicit files or trusted project declarations; never infer natural-language criteria. */
-import { join, resolve } from "node:path";
-import { parseAcceptanceContract, type AcceptanceContract } from "../core/acceptance.ts";
-import { blobAddress } from "./blobs.ts";
-
-export async function loadAcceptanceContract(workspace: string, trusted: boolean, explicit?: string): Promise<AcceptanceContract | undefined> {
-  if (!explicit && !trusted) return undefined;
-  const path = explicit ? resolve(workspace, explicit) : join(workspace, ".xeno", "acceptance.json");
-  const file = Bun.file(path);
-  if (!await file.exists()) { if (explicit) throw new Error(`missing acceptance file: ${path}`); return undefined; }
-  if (file.size > 64000) throw new Error("acceptance file exceeds 64 KiB");
-  const text = await file.text();
-  const contract = parseAcceptanceContract(JSON.parse(text));
-  return { ...contract, scope: contract.scope ?? (explicit ? "request" : "changes"), source: { path, sha256: blobAddress(text) } };
-}

package/src/store/agent-profile-files.ts

@@ -1,13 +0,0 @@
-/** R13: profile files are inert JSON; project trust is decided by the app. */
-import { readFile } from "node:fs/promises";
-
-export async function readAgentProfileFile(path: string): Promise<{ value: unknown; diagnostic?: string } | null> {
-  let body: string;
-  try { body = await readFile(path, "utf8"); }
-  catch (error) {
-    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return null;
-    return { value: null, diagnostic: `${path}: unable to read agents configuration` };
-  }
-  try { return { value: JSON.parse(body) as unknown }; }
-  catch { return { value: null, diagnostic: `${path}: invalid JSON in agents configuration` }; }
-}

package/src/store/atomic.ts

@@ -1,31 +0,0 @@
-/** Durable replacement for small derived metadata (D3/D8). */
-import { mkdir, open, rename, rm } from "node:fs/promises";
-import { dirname, join, basename } from "node:path";
-import { randomUUID } from "node:crypto";
-
-export async function atomicWrite(path: string, content: string | Uint8Array): Promise<void> {
-  const directory = dirname(path);
-  await mkdir(directory, { recursive: true });
-  const temporary = join(directory, `.${basename(path)}.${randomUUID()}.tmp`);
-  try {
-    const file = await open(temporary, "wx", 0o600);
-    try {
-      await file.writeFile(content);
-      await file.sync();
-    } finally { await file.close(); }
-    await rename(temporary, path);
-    const folder = await open(directory, "r");
-    try { await folder.sync(); } finally { await folder.close(); }
-  } finally {
-    await rm(temporary, { force: true });
-  }
-}
-
-/** The record must reach durable storage before its side effect is dispatched. */
-export async function durableAppend(path: string, record: string): Promise<void> {
-  const file = await open(path, "a", 0o600);
-  try { await file.writeFile(record); await file.sync(); }
-  finally { await file.close(); }
-  const directory = await open(dirname(path), "r");
-  try { await directory.sync(); } finally { await directory.close(); }
-}

package/src/store/auth-store.ts

@@ -1,50 +0,0 @@
-/**
- * Read-modify-write for `auth.json`.
- *
- * The file holds API keys and OAuth tokens under one lock so a refresh cannot
- * clobber a login that landed between the read and the write. 0600 is applied
- * on every write -- an older world-readable file would otherwise keep leaking
- * after we started storing refresh tokens in it.
- */
-
-import { authPath, readJsonFile, writeJsonFile } from "./config.ts";
-
-export type StoredAuthEntry =
-  | { type: "api_key"; key: string }
-  | {
-      type: "oauth";
-      access: string;
-      refresh: string;
-      expires: number;
-      accountId?: string;
-      enterpriseUrl?: string;
-    };
-
-export type AuthFileContents = {
-  [provider: string]: StoredAuthEntry | undefined;
-};
-
-export async function readAuthFile(): Promise<AuthFileContents> {
-  const got = await readJsonFile<AuthFileContents>(authPath());
-  return got.value ?? {};
-}
-
-export async function writeAuthFile(auth: AuthFileContents): Promise<void> {
-  await writeJsonFile(authPath(), auth, true);
-}
-
-export async function upsertCredential(
-  provider: string,
-  credential: StoredAuthEntry,
-): Promise<void> {
-  const current = await readAuthFile();
-  const next: AuthFileContents = { ...current, [provider]: credential };
-  await writeAuthFile(next);
-}
-
-export async function deleteCredential(provider: string): Promise<void> {
-  const current = await readAuthFile();
-  const next: AuthFileContents = { ...current };
-  delete next[provider];
-  await writeAuthFile(next);
-}

package/src/store/blind-checks.ts

@@ -1,32 +0,0 @@
-/**
- * Reading a blind check directory (feat-blind-checks). It must sit outside
- * the workspace -- a check inside it is a file the model can open -- and is
- * frozen into the session with every file's digest, so a resumed session
- * runs exactly the checks it started with.
- */
-import { readdir, readFile, realpath, stat } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
-import { BLIND_BYTES_LIMIT, BLIND_FILE_LIMIT, parseBlindManifest, type BlindChecks } from "../core/blind-checks.ts";
-import { blobAddress } from "./blobs.ts";
-
-export async function loadBlindChecks(dir: string, workspace: string): Promise<BlindChecks> {
-  const given = resolve(workspace, dir), root = await realpath(given), work = await realpath(workspace);
-  const inside = relative(work, root);
-  if (inside === "" || !inside.startsWith("..") && !isAbsolute(inside)) throw Error("--blind-checks must be outside the workspace, where the model cannot read it");
-  const files: Record<string, string> = {};
-  let bytes = 0;
-  const walk = async (path: string): Promise<void> => {
-    for (const entry of await readdir(path, { withFileTypes: true })) {
-      const full = join(path, entry.name), rel = relative(root, full);
-      if (entry.isDirectory()) { await walk(full); continue; }
-      if (!entry.isFile()) throw Error(`blind check ${rel} is not a regular file`);
-      if (Object.keys(files).length >= BLIND_FILE_LIMIT) throw Error(`--blind-checks holds more than ${BLIND_FILE_LIMIT} files`);
-      bytes += (await stat(full)).size;
-      if (bytes > BLIND_BYTES_LIMIT) throw Error(`--blind-checks holds more than ${BLIND_BYTES_LIMIT} bytes`);
-      files[rel] = blobAddress(await readFile(full));
-    }
-  };
-  await walk(root);
-  const manifest = parseBlindManifest(JSON.parse(await readFile(join(root, "blind.json"), "utf8")));
-  return { dir: root, aliases: given === root ? [] : [given], manifest, files };
-}

package/src/store/blobs.ts

@@ -1,143 +0,0 @@
-/**
- * Content-addressed blob store.
- *
- * A directory of sha256-named files, sharded two hex digits deep so no single
- * directory holds every blob. Writes are immutable: the same bytes always land
- * at the same address, so storing a file twice costs nothing and a stored blob
- * is never modified in place.
- *
- * Why not git's object database, which is exactly this and comes free with
- * every repository: git's lifetime contract is REACHABILITY. A blob with no
- * ref pointing at it is by definition unreachable, which is precisely what
- * `git gc` deletes -- and gc runs automatically on pull, merge, rebase and
- * commit. The default two-week grace period would be the only thing between a
- * restore and data loss, and a write-heavy store also trips git's
- * "too many unreachable loose objects" warning, after which git refuses
- * further automatic cleanup until its log is cleared by hand. Keeping a ref
- * per blob is more work than this file, and it would tie the lifetime of our
- * data to the user's git operations.
- *
- * What that costs: no packing and no delta compression, so a large file
- * edited many times is stored in full each time. Acceptable while the
- * granularity is a turn rather than a keystroke, and revisitable behind this
- * interface if it stops being.
- */
-
-import { readFile, access, mkdir, open, rename, rm, copyFile, stat, chmod } from "node:fs/promises";
-import { createReadStream } from "node:fs";
-import { createHash, randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { atomicWrite } from "./atomic.ts";
-
-export function blobAddress(content: string | Uint8Array): string {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-/** Hash and archive in bounded chunks, so large ordinary files need no cap. */
-export async function digestFile(path: string): Promise<string> {
-  const hash = createHash("sha256");
-  for await (const chunk of createReadStream(path)) hash.update(chunk as Uint8Array);
-  return hash.digest("hex");
-}
-
-export async function putFileBlob(dir: string, source: string): Promise<string> {
-  await mkdir(dir, { recursive: true });
-  const temp = join(dir, `.${randomUUID()}.blob`);
-  const file = await open(temp, "wx", 0o600);
-  const hash = createHash("sha256");
-  try {
-    try {
-      for await (const chunk of createReadStream(source)) {
-        const bytes = chunk as Uint8Array;
-        hash.update(bytes);
-        await file.writeFile(bytes);
-      }
-      await file.sync();
-    } finally { await file.close(); }
-    const sha = hash.digest("hex");
-    const dest = blobFilePath(dir, sha);
-    if (await hasBlob(dir, sha)) {
-      if (await digestFile(dest) !== sha) throw new Error(`blob integrity failure: ${sha}`);
-      return sha;
-    }
-    await mkdir(dirname(dest), { recursive: true });
-    await rename(temp, dest);
-    const parent = await open(dirname(dest), "r");
-    try { await parent.sync(); } finally { await parent.close(); }
-    return sha;
-  } finally { await rm(temp, { force: true }); }
-}
-
-export async function verifyBlob(dir: string, sha: string): Promise<boolean> {
-  try {
-    if (await digestFile(blobFilePath(dir, sha)) !== sha) throw new Error(`blob integrity failure: ${sha}`);
-    return true;
-  } catch (error) {
-    if ((error as { code?: string }).code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-/** Stage before replacing; never expose half of a large restored file. */
-export async function restoreBlob(dir: string, sha: string, destination: string): Promise<void> {
-  await mkdir(dirname(destination), { recursive: true });
-  const temp = `${destination}.${randomUUID()}.restore`;
-  try {
-    await copyFile(blobFilePath(dir, sha), temp);
-    if (await digestFile(temp) !== sha) throw new Error(`blob integrity failure: ${sha}`);
-    try { await chmod(temp, (await stat(destination)).mode); }
-    catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
-    const file = await open(temp, "r");
-    try { await file.sync(); } finally { await file.close(); }
-    await rename(temp, destination);
-  } finally { await rm(temp, { force: true }); }
-}
-
-export function blobFilePath(dir: string, sha: string): string {
-  if (!/^[a-f0-9]{64}$/.test(sha)) throw new Error("invalid blob digest");
-  // Two-digit shard: a flat directory of tens of thousands of files is slow
-  // to list on most filesystems, and listing is how a human inspects this.
-  return join(dir, sha.slice(0, 2), sha.slice(2));
-}
-
-/** Stores content and returns its address. Storing the same bytes twice is free. */
-export async function putBlob(dir: string, content: string | Uint8Array): Promise<string> {
-  const sha = blobAddress(content);
-  const path = blobFilePath(dir, sha);
-  // Content addressing means an existing blob already holds these exact
-  // bytes, so rewriting it could only turn a good file into a torn one.
-  if (await hasBlob(dir, sha)) {
-    await getBlobBytes(dir, sha);
-    return sha;
-  }
-  await atomicWrite(path, content);
-  return sha;
-}
-
-/** Null rather than throwing: a missing blob is a state callers must handle. */
-export async function getBlob(dir: string, sha: string): Promise<string | null> {
-  const bytes = await getBlobBytes(dir, sha);
-  return bytes === null ? null : Buffer.from(bytes).toString("utf8");
-}
-
-/** Restore uses bytes; decoding binary data is an irreversible transformation. */
-export async function getBlobBytes(dir: string, sha: string, maxBytes?: number): Promise<Uint8Array | null> {
-  try {
-    if (maxBytes !== undefined && (await stat(blobFilePath(dir, sha))).size > maxBytes) throw new RangeError("Blob exceeds byte limit");
-    const bytes = await readFile(blobFilePath(dir, sha));
-    if (blobAddress(bytes) !== sha) throw new Error(`blob integrity failure: ${sha}`);
-    return bytes;
-  } catch (err) {
-    if ((err as { code?: string }).code === "ENOENT") return null;
-    throw err;
-  }
-}
-
-export async function hasBlob(dir: string, sha: string): Promise<boolean> {
-  try {
-    await access(blobFilePath(dir, sha));
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/store/checkpoint-history.ts

@@ -1,32 +0,0 @@
-/** File ancestry is independent of model-context ancestry (P.3). */
-import { readNodeHistory, type RestoreTarget } from "./restore.ts";
-import { planFileTransition, type CheckpointEvent, type FileChanges } from "../core/checkpoints.ts";
-
-export async function checkpointHistory(dir: string, target: RestoreTarget, visited = new Set<string>()): Promise<CheckpointEvent[]> {
-  const position = typeof target === "number" ? { node: target } : target;
-  const key = `${position.node}:${position.atEvent ?? "end"}`;
-  if (visited.has(key) || visited.size >= 256) throw new Error("cyclic or excessively deep file history");
-  const next = new Set(visited).add(key);
-  const history = await readNodeHistory(dir, position.node);
-  if (!history.ok) throw new Error(history.error);
-  let checkpoints: CheckpointEvent[] = [];
-  for (const node of history.nodes) {
-    let events = node.events;
-    if (node.node === position.node && position.atEvent !== undefined) {
-      const at = events.findIndex(event => event.id === position.atEvent);
-      if (at < 0) throw new Error(`NO_SUCH_EVENT: ${position.atEvent}`);
-      events = events.slice(0, at + 1);
-    }
-    for (const event of events) {
-      if (event.t === "rewind" && event.files_from) {
-        checkpoints = await checkpointHistory(dir, { node: event.files_from.node,
-          ...(event.files_from.at_event ? { atEvent: event.files_from.at_event } : {}) }, next);
-      } else if (event.t === "checkpoint") checkpoints.push(event);
-    }
-  }
-  return checkpoints;
-}
-
-export async function planCheckpointRestore(dir: string, current: RestoreTarget, target: RestoreTarget): Promise<FileChanges> {
-  return planFileTransition(await checkpointHistory(dir, current), await checkpointHistory(dir, target));
-}

package/src/store/command-artifacts.ts

@@ -1,96 +0,0 @@
-/** R8: bounded observations over file descriptors; binaries themselves are not copied into the log. */
-import { constants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
-import { resolve, join, relative, sep } from "node:path";
-import { createHash } from "node:crypto";
-import { MAX_COMMAND_ARTIFACT_BYTES, COMMAND_ARTIFACT_SCOPE, sameArtifactIdentity, validArtifactPath,
-  type ArtifactFile, type ArtifactFileIdentity, type CommandArtifactPlan } from "../core/command-artifacts.ts";
-import { archiveObservation } from "./observations.ts";
-import { observeWorkspace, SOURCE_IGNORE } from "./workspace-observation.ts";
-import { blobAddress } from "./blobs.ts";
-
-// Assumed per-phase bounds, not performance measurements; exhaustion yields unknown.
-const OBSERVATION_MS = 10_000;
-const CHUNK_BYTES = 1024 * 1024;
-type IdentityStat = { dev: bigint; ino: bigint; mtimeNs: bigint; ctimeNs: bigint; mode: bigint };
-const identity = (info: IdentityStat): ArtifactFileIdentity => ({ device: String(info.dev), inode: String(info.ino),
-  mtime_ns: String(info.mtimeNs), ctime_ns: String(info.ctimeNs), mode: Number(info.mode) & 0o777 });
-
-/** Both walks reject symlink components. This is a local observation, not an OS sandbox against hostile concurrent renames. */
-async function ordinaryPath(root: string, path: string): Promise<string> {
-  let current = root;
-  const parts = path.split("/");
-  for (let i = 0; i < parts.length; i++) {
-    current = join(current, parts[i]!);
-    const info = await lstat(current);
-    if (info.isSymbolicLink() || (i === parts.length - 1 ? !info.isFile() : !info.isDirectory())) throw Object.assign(new Error("not an ordinary confined file"), { code: "EUNSAFE" });
-  }
-  if (await realpath(current) !== current) throw Object.assign(new Error("file path changed or follows a symlink"), { code: "EUNSAFE" });
-  return current;
-}
-
-export function artifactExclusions(root: string, plan: CommandArtifactPlan, ownedPaths: readonly string[] = []): string[] {
-  const owned = ownedPaths.map(path => relative(resolve(root), resolve(path)))
-    .filter(path => path && path !== ".." && !path.startsWith(`..${sep}`) && !path.startsWith(sep) && !path.split(sep).some(part => SOURCE_IGNORE.includes(part)));
-  return [...new Set([...plan.output_roots, ...owned])].sort();
-}
-export async function observeArtifactInputs(root: string, exclusions: readonly string[], signal?: AbortSignal): Promise<{ sha256: string | null; reason?: string }> {
-  const bounded = AbortSignal.any([AbortSignal.timeout(OBSERVATION_MS), ...(signal ? [signal] : [])]);
-  const result = await observeWorkspace(root, bounded, exclusions.map(path => resolve(root, path)));
-  // A digest binds the declared finite scope as well as its bytes; it is never source-v1 evidence.
-  return result.ok && !bounded.aborted ? { sha256: blobAddress(JSON.stringify([COMMAND_ARTIFACT_SCOPE, SOURCE_IGNORE, exclusions, result.fingerprint])) }
-    : { sha256: null, reason: result.ok ? "input observation cancelled or timed out" : result.reason };
-}
-
-export async function observeArtifactFiles(root: string, paths: readonly string[], signal?: AbortSignal): Promise<ArtifactFile[]> {
-  const bounded = AbortSignal.any([AbortSignal.timeout(OBSERVATION_MS), ...(signal ? [signal] : [])]);
-  let remaining = MAX_COMMAND_ARTIFACT_BYTES;
-  const results: ArtifactFile[] = [];
-  let base: string;
-  try { base = await realpath(root); } catch { return paths.map(() => ({ state: "unknown", reason: "workspace unavailable" })); }
-  for (const path of paths) {
-    if (!validArtifactPath(path)) { results.push({ state: "unsafe", reason: "invalid workspace artifact path" }); continue; }
-    if (bounded.aborted) { results.push({ state: "unknown", reason: "artifact observation cancelled or timed out" }); continue; }
-    try {
-      const absolute = await ordinaryPath(base, path);
-      // O_NONBLOCK prevents a concurrent FIFO replacement from hanging before fstat rejects it.
-      const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-      try {
-        const before = await file.stat({ bigint: true });
-        if (!before.isFile()) { results.push({ state: "unsafe", reason: "opened object is not an ordinary file" }); continue; }
-        if (before.size > BigInt(remaining)) { results.push({ state: "unknown", reason: "artifact byte budget exceeded" }); continue; }
-        const limit = Number(before.size), buffer = Buffer.alloc(Math.min(CHUNK_BYTES, Math.max(1, limit + 1))), hash = createHash("sha256");
-        let bytes = 0, failed = false;
-        for (;;) {
-          if (bounded.aborted) { results.push({ state: "unknown", reason: "artifact observation cancelled or timed out" }); failed = true; break; }
-          const read = await file.read(buffer, 0, Math.min(buffer.length, limit + 1 - bytes), bytes);
-          bytes += read.bytesRead;
-          remaining -= read.bytesRead;
-          if (bytes > limit) { results.push({ state: "changed", reason: "file grew during observation" }); failed = true; break; }
-          if (read.bytesRead === 0) break;
-          hash.update(buffer.subarray(0, read.bytesRead));
-        }
-        if (failed) continue;
-        const after = await file.stat({ bigint: true });
-        await ordinaryPath(base, path);
-        const named = await lstat(absolute, { bigint: true });
-        if (bytes !== Number(before.size) || after.size !== before.size || named.size !== before.size ||
-          !sameArtifactIdentity(identity(before), identity(after)) || !sameArtifactIdentity(identity(after), identity(named))) {
-          results.push({ state: "changed", reason: "file contents or identity changed during observation" }); continue;
-        }
-        results.push({ state: "observed", sha256: hash.digest("hex"), bytes, identity: identity(after) });
-      } finally { await file.close(); }
-    } catch (error) {
-      const code = (error as { code?: string }).code;
-      results.push(code === "ENOENT" || code === "ENOTDIR" ? { state: "missing", reason: "artifact path was not found" }
-        : code === "EUNSAFE" || code === "ELOOP" ? { state: "unsafe", reason: "artifact path is not an ordinary confined file" }
-        : { state: "unknown", reason: "artifact file could not be observed" });
-    }
-  }
-  return results;
-}
-
-export async function archiveCommandArtifacts(outputStore: string, observation: unknown) {
-  async function* bytes() { yield new TextEncoder().encode(JSON.stringify(observation)); }
-  return (await archiveObservation(outputStore, bytes(), 0)).ref;
-}