@mgiles/perk 3.1.0 → 3.3.0

package/extension/substrate/resolverLease.ts

@@ -0,0 +1,364 @@
+// The conflict-resolver claim (contracts.md §8.51): a machine-local SESSION CLAIM on a retained
+// sync-continuation operation, taken during preparation before native execution. It is NOT a
+// child-lifecycle-bound execution lock: after a verified dispatch preparation this claim stays
+// held across every resolver outcome, including confirmed completion. Only preparation failure
+// releases this call's token. The separate worktree execution lock cannot be reclaimed here.
+// The session claim self-heals instead, via the
+// reclaimability predicate: the holder pid is dead, the recorded operation was consumed (a fresh
+// conflict minted a new operation id), or the lease is missing/corrupt and the lock dir has aged
+// past `RECLAIM_GRACE_MS`. The accepted residual: a live session's claim on a still-pending SAME
+// operation blocks other sessions' dispatch until that session exits or the operation is
+// consumed — the busy reason names the holder pid, the lock path, and the remediation.
+//
+// Reclaim mechanics mirror `hunkFeedback/store.ts::acquireLease` (the interleaving-safe recipe):
+// judge reclaimability → quarantine-RENAME the observed lock dir to a unique name (rename is
+// atomic, so two reclaimers can never both delete a successor) → post-rename re-judgment on the
+// MOVED state (a claim that changed since the judgment, or whose lease is missing/corrupt but
+// still inside the grace window, is renamed back — a raced-in claim is NEVER stolen, whatever
+// operation it names) → ONE fresh-acquire retry → best-effort quarantine removal; a lost retry
+// is an honest busy. Deletion only ever targets our own quarantine dir or our own same-call
+// acquisition, and the explicit withheld-dispatch release is token-fenced through its own
+// quarantine-verify (`releaseResolverClaim`).
+//
+// Error posture: a MISSING or MALFORMED lease is DATA (it routes to the reclaim rules), and the
+// expected race disappearances (ENOENT on read/stat/rename, EEXIST on mkdir) are contention —
+// every OTHER filesystem failure propagates to the typed `io_error` arm, never a fabricated
+// busy/reclaim judgment.
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "./cache.ts";
+
+/**
+ * A corrupt/missing `lease.json` is reclaimable only once the lock dir is older than this —
+ * closes the winner's mkdir↔first-write window (implementation constant, not config).
+ */
+export const RECLAIM_GRACE_MS = 60_000;
+
+/** The claim lock dir sits beside the continuation manifest it guards. */
+export function resolverLockDir(manifestPath: string): string {
+  return `${manifestPath}.resolver-lock`;
+}
+
+export type LeaseAcquisition =
+  | { acquired: true; token: string }
+  | { acquired: false; kind: "busy" | "io_error"; reason: string };
+
+/** Deterministic-interleave seams for the reclaim-race tests — never set in production. */
+export interface AcquireRaceHooks {
+  /** Runs after the reclaimability judgment, before the quarantine rename. */
+  beforeQuarantine?(): void;
+  /** Runs after the quarantine rename attempt, before the fresh-acquire retry. */
+  afterQuarantine?(): void;
+}
+
+/** The raw fs operations the claim touches — injectable ONLY for deterministic fault tests. */
+export interface LeaseFsOps {
+  /** Non-recursive mkdir: EEXIST is the contention signal. */
+  mkdir(path: string): void;
+  /** utf8 read. */
+  readFile(path: string): string;
+  /** Atomic lease write (temp + rename — the atomicWriteFileSync discipline). */
+  writeLease(path: string, content: string): void;
+  rename(from: string, to: string): void;
+  /** Recursive, force. */
+  rm(path: string): void;
+  statMtimeMs(path: string): number;
+}
+
+const REAL_FS: LeaseFsOps = {
+  mkdir: (path) => mkdirSync(path),
+  readFile: (path) => readFileSync(path, "utf8"),
+  writeLease: (path, content) => atomicWriteFileSync(path, content),
+  rename: (from, to) => renameSync(from, to),
+  rm: (path) => rmSync(path, { recursive: true, force: true }),
+  statMtimeMs: (path) => statSync(path).mtimeMs,
+};
+
+interface ResolverLease {
+  schema: 1;
+  pid: number;
+  operation_id: string;
+  /** The per-acquisition ownership fence: rotated on every (re)acquire; release verifies it. */
+  token: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException).code;
+}
+
+/**
+ * Read the lease as DATA: a missing file or malformed/mis-shaped content is `null` (the
+ * corrupt/missing reclaim rules own it). Any OTHER read failure (EACCES, EIO, EISDIR, …) is a
+ * genuine I/O failure and THROWS so the caller's typed `io_error` arm reports it honestly.
+ */
+function readLease(fs: LeaseFsOps, lockDir: string): ResolverLease | null {
+  let raw: string;
+  try {
+    raw = fs.readFile(join(lockDir, "lease.json"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    isRecord(parsed) &&
+    parsed.schema === 1 &&
+    typeof parsed.pid === "number" &&
+    Number.isInteger(parsed.pid) &&
+    typeof parsed.operation_id === "string" &&
+    typeof parsed.token === "string"
+  ) {
+    return parsed as unknown as ResolverLease;
+  }
+  return null;
+}
+
+/** The lock dir's mtime, or -Infinity when it vanished (ENOENT — a racing reclaim finished);
+ * any other stat failure throws to the typed `io_error` arm. */
+function lockDirBasisMs(fs: LeaseFsOps, path: string): number {
+  try {
+    return fs.statMtimeMs(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return Number.NEGATIVE_INFINITY;
+    throw error;
+  }
+}
+
+function leaseBytes(lease: ResolverLease): string {
+  return `${JSON.stringify(lease)}\n`;
+}
+
+function mintToken(): string {
+  return randomBytes(8).toString("hex");
+}
+
+/** Liveness probe: ESRCH = dead; EPERM (a foreign-uid process) and success both count alive. */
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) !== "ESRCH";
+  }
+}
+
+/**
+ * Atomic non-recursive `mkdir` (EEXIST = contention) + the first lease write. Returns the fresh
+ * token on acquisition, null on contention; throws on any other fs failure — after best-effort
+ * removing the dir THIS call created (we own it; any surviving residue self-heals via the
+ * aged-corrupt reclaim rule).
+ */
+function tryFreshAcquire(
+  fs: LeaseFsOps,
+  lockDir: string,
+  pid: number,
+  operationId: string,
+): string | null {
+  try {
+    fs.mkdir(lockDir);
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") return null;
+    throw error;
+  }
+  const token = mintToken();
+  try {
+    fs.writeLease(
+      join(lockDir, "lease.json"),
+      leaseBytes({ schema: 1, pid, operation_id: operationId, token }),
+    );
+  } catch (error) {
+    try {
+      fs.rm(lockDir);
+    } catch {
+      // best-effort — the corrupt-lease reclaim rule collects it once it ages
+    }
+    throw error;
+  }
+  return token;
+}
+
+function busyHolder(pid: number, lockDir: string): string {
+  return (
+    `another live session (pid ${pid}) holds the resolver claim at ${lockDir} — ` +
+    "dispatch from that session, or remove the lock dir if it is provably stale"
+  );
+}
+
+function busyUnidentified(lockDir: string): string {
+  return (
+    `an unidentified holder claims the resolver lock at ${lockDir} (lease unreadable, ` +
+    "created recently) — retry shortly, or remove the lock dir if it is provably stale"
+  );
+}
+
+function sameLease(a: ResolverLease, b: ResolverLease | null): boolean {
+  return b !== null && a.pid === b.pid && a.operation_id === b.operation_id && a.token === b.token;
+}
+
+/**
+ * Acquire the resolver claim for `operationId` on the continuation at `manifestPath`. Never
+ * throws: every genuine filesystem failure is caught and returned as `kind: "io_error"` (the
+ * expected race disappearances are classified inline — see the module doc). Same-pid contention
+ * is an idempotent REACQUIRE that rewrites `lease.json` with the CURRENT operation id and a
+ * fresh token (a continue-time NEW conflict reuses the same operation id — the original
+ * dispatching session re-claims; it never routes through reclaim). On success the returned
+ * `token` is the ownership fence a withheld dispatch passes to `releaseResolverClaim`.
+ * `pid`/`isAlive`/`now`/`hooks`/`fs` are injectable for deterministic tests.
+ */
+export function acquireResolverLease(
+  manifestPath: string,
+  operationId: string,
+  opts?: {
+    pid?: number;
+    isAlive?: (pid: number) => boolean;
+    now?: () => number;
+    hooks?: AcquireRaceHooks;
+    fs?: Partial<LeaseFsOps>;
+  },
+): LeaseAcquisition {
+  const pid = opts?.pid ?? process.pid;
+  const isAlive = opts?.isAlive ?? defaultIsAlive;
+  const now = opts?.now ?? Date.now;
+  const hooks = opts?.hooks ?? {};
+  const fs: LeaseFsOps = { ...REAL_FS, ...(opts?.fs ?? {}) };
+  const lockDir = resolverLockDir(manifestPath);
+  try {
+    const fresh = tryFreshAcquire(fs, lockDir, pid, operationId);
+    if (fresh !== null) return { acquired: true, token: fresh };
+
+    const observed = readLease(fs, lockDir);
+    if (observed !== null && observed.pid === pid) {
+      // Same pid: reacquire, not reclaim — rewrite with the current operation id + fresh token.
+      const token = mintToken();
+      fs.writeLease(
+        join(lockDir, "lease.json"),
+        leaseBytes({ schema: 1, pid, operation_id: operationId, token }),
+      );
+      return { acquired: true, token };
+    }
+
+    // Reclaimability: dead holder / consumed operation / aged corrupt-or-missing lease.
+    if (observed !== null) {
+      if (isAlive(observed.pid) && observed.operation_id === operationId) {
+        return { acquired: false, kind: "busy", reason: busyHolder(observed.pid, lockDir) };
+      }
+    } else if (now() - lockDirBasisMs(fs, lockDir) < RECLAIM_GRACE_MS) {
+      // Corrupt/missing lease.json inside the grace window (a winner may sit between its
+      // mkdir and first write) — busy; a vanished dir counts old and the retry settles it.
+      return { acquired: false, kind: "busy", reason: busyUnidentified(lockDir) };
+    }
+
+    // Reclaim: quarantine-rename → post-rename re-judgment → ONE fresh-acquire retry.
+    hooks.beforeQuarantine?.();
+    const quarantine = `${lockDir}.stale-${pid.toString(36)}-${randomBytes(4).toString("hex")}`;
+    let renamed = false;
+    try {
+      fs.rename(lockDir, quarantine);
+      renamed = true;
+    } catch (error) {
+      // ENOENT = a competing reclaimer moved it first — still take the one retry. Any other
+      // rename failure is genuine I/O and must not masquerade as contention.
+      if (errorCode(error) !== "ENOENT") throw error;
+      renamed = false;
+    }
+    if (renamed) {
+      // Post-rename re-judgment on the MOVED state: between our judgment and the rename a
+      // competitor may have installed a successor claim (any operation id — never assume the
+      // one we are acquiring), or a winner may sit inside its mkdir↔first-write window (a
+      // young dir with no lease yet). Neither is ours to take: restore and report busy. Only
+      // the unchanged judged-stale state, a dead raced-in holder, or an AGED lease-less dir
+      // proceeds to the retry.
+      const moved = readLease(fs, quarantine);
+      let busyReason: string | null = null;
+      if (moved !== null) {
+        if (!sameLease(moved, observed) && isAlive(moved.pid)) {
+          busyReason = busyHolder(moved.pid, lockDir);
+        }
+      } else if (now() - lockDirBasisMs(fs, quarantine) < RECLAIM_GRACE_MS) {
+        // rename preserves mtime — the moved dir's age is the original dir's age.
+        busyReason = busyUnidentified(lockDir);
+      }
+      if (busyReason !== null) {
+        try {
+          fs.rename(quarantine, lockDir);
+        } catch {
+          // the name was retaken meanwhile — leave the quarantine; it self-heals as residue
+        }
+        return { acquired: false, kind: "busy", reason: busyReason };
+      }
+    }
+    hooks.afterQuarantine?.();
+    const retried = tryFreshAcquire(fs, lockDir, pid, operationId);
+    if (renamed) {
+      try {
+        fs.rm(quarantine);
+      } catch {
+        // best-effort — a leftover quarantine dir is inert
+      }
+    }
+    if (retried !== null) return { acquired: true, token: retried };
+    return {
+      acquired: false,
+      kind: "busy",
+      reason:
+        `another session claimed the resolver lock at ${lockDir} first — dispatch from that ` +
+        "session, or retry once its claim clears",
+    };
+  } catch (error) {
+    return {
+      acquired: false,
+      kind: "io_error",
+      reason: `resolver-claim filesystem failure at ${lockDir}: ${String(error)}`,
+    };
+  }
+}
+
+/**
+ * Release THIS call's claim — the withheld-dispatch cleanup (a verified-increment failure must
+ * not leave a phantom holder). Token-fenced through a quarantine-verify: the claim is renamed
+ * to a private name first (atomic — a successor installed at the canonical path is never
+ * touched), verified against `token`, and deleted only when it proved ours; anything else is
+ * renamed back. Best-effort and never throws: leftover residue self-heals via the reclaim
+ * rules.
+ */
+export function releaseResolverClaim(
+  manifestPath: string,
+  token: string,
+  opts?: { fs?: Partial<LeaseFsOps> },
+): void {
+  const fs: LeaseFsOps = { ...REAL_FS, ...(opts?.fs ?? {}) };
+  const lockDir = resolverLockDir(manifestPath);
+  const quarantine = `${lockDir}.release-${process.pid.toString(36)}-${randomBytes(4).toString("hex")}`;
+  try {
+    try {
+      fs.rename(lockDir, quarantine);
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") return; // nothing to release
+      throw error;
+    }
+    const moved = readLease(fs, quarantine);
+    if (moved !== null && moved.token === token) {
+      fs.rm(quarantine);
+      return;
+    }
+    // Not ours (a successor raced in) — put it back untouched.
+    try {
+      fs.rename(quarantine, lockDir);
+    } catch {
+      // the name was retaken meanwhile — leave the quarantine; it self-heals as residue
+    }
+  } catch {
+    // best-effort — a leftover claim/quarantine goes stale and is reclaimed by the next acquire
+  }
+}

package/extension/substrate/sessionData.ts

@@ -1,4 +1,4 @@
-// The session-data accessor seam (contracts.md §8.1).
+// The session-data accessor seam (contracts.md §8.1) — RAW PRIMITIVES ONLY.
 //
 // Every run-scoped session artifact lives under `.perk/workflow/scratch/runs/<run_id>/data/`, and
 // ALL session-data paths flow through this module (interior) or `perk/state/cache.py` (exterior) — the
@@ -6,59 +6,68 @@
 // `scratch`/`runs` path segments anywhere else.
 //
 // Seam doctrine — degrade gracefully, never invent identity:
-// - The current run_id resolves from the rebuilt `perk:workflow-state` and degrades to `null`
-//   when the session has no identity. CONTRAST with `coldDoor.activeRunId`, which falls back to
-//   a `cold-door-<ts>` stamp for stdin-staging debuggability: a stamp here would orphan data
-//   dirs and break run_id-keyed provenance, so this seam never stamps.
-// - Reads return `null` on absence (normal, branchable) and on I/O errors (with a loud stderr
-//   warning); writes return the written path or `null` on failure (with a warning). Never
-//   throws — a broken disk must not wedge a session.
+// - The current run_id resolves from the rebuilt `perk:workflow-state`, narrowed non-empty AND
+//   safe as a path component (`isSafeRunId` — a hostile rebuilt id degrades to no-identity
+//   before any path derivation), and degrades to `null` when the session has no identity.
+//   CONTRAST with `coldDoor.activeRunId`, which falls back to a `cold-door-<ts>` stamp for
+//   stdin-staging debuggability: a stamp here would orphan data dirs and break run_id-keyed
+//   provenance, so this seam never stamps.
+// - Ordinary reads return `null` on absence and I/O errors (with a loud stderr warning);
+//   opt-in strict reads classify ENOENT separately and refuse unsafe namespaces. Writes return
+//   the written path or `null` on failure (with a warning). Content operations never throw —
+//   a broken disk must not wedge a session.
+// - The file primitives (`readSessionData`/`writeSessionData`/`ensureSessionDataDir`) take an
+//   EXPLICIT run id — identity is resolved ONCE (by the session engine, or here via
+//   `activeSessionRunId`) and passed down, so two independent identity reads can never
+//   disagree about which run's storage an operation touches.
 //
-// Provenance doctrine (contracts §8.1/§8.3) — the pointer makes it consumable:
-// - A session artifact is *consumable* only via its `session_artifacts` pointer
-//   ({run_id, name, path, digest, at}) in the rebuilt `perk:workflow-state`. A bare file on
-//   disk is never trusted: `writeSessionArtifact` returns a path only once BOTH the file and
-//   the pointer landed; `readSessionArtifact` validates the on-disk bytes against the rebuilt
-//   pointer and fails open to `null` when validation refuses.
-// - Validation always derives the path from `run_id` + `name` through the seam; the recorded
-//   `pointer.path` is informational/debugging only and is never dereferenced (workflow-state
-//   entries are reconstructable from untrusted session history).
-// - The four lifecycle guarantees: REWIND ⇒ the rebuilt branch carries an older pointer while
-//   disk holds newer bytes ⇒ digest mismatch ⇒ refusal. FORK ⇒ the child run_id no longer
-//   matches the inherited pointer's ⇒ silent refusal (no inheritance; fresh dir).
-//   RELOAD/COMPACTION ⇒ same run_id ⇒ pointer + dir persist. CONCURRENT SESSIONS ⇒ run_id
-//   keying isolates dirs and pointers alike — validation never crosses run_ids.
+// The ARTIFACT DISCIPLINE (provenance pointers, digest validation, the classified write/read
+// tiers — contracts §8.1/§8.3) lives in the session engine, `session/workflowSession.ts`: this
+// module supplies only the file mechanics its production binding
+// (`session/branchWorkflowSession.ts`) builds its content port from. A bare file on disk is
+// never trusted — consumers go through the `WorkflowSession` seam.
 //
 // Imports only node builtins + cache.ts + workflowState.ts + report.ts so the module stays
 // loadable under `node --test`; accepts a minimal structural ctx (`BranchSource & { cwd }`).
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { ReportTarget } from "../surfaces/report.ts";
-import { atomicWriteFileSync, ensureRunScratch, sessionDataDir } from "./cache.ts";
 import {
-  appendWorkflowState,
-  type BranchSource,
-  branchOf,
-  type EntrySink,
-  rebuildWorkflowState,
-  type SessionArtifactPointer,
-} from "./workflowState.ts";
+  atomicWriteFileSync,
+  canonicalSessionDataDir,
+  ensureRunScratch,
+  isSafeRunId,
+  sessionDataDir,
+} from "./cache.ts";
+import { type BranchSource, branchOf, rebuildWorkflowState } from "./workflowState.ts";
+
+export { canonicalSessionDataDir } from "./cache.ts";
 
 /** Minimal context slice — `ExtensionContext` satisfies it (the `BranchSource` precedent). */
 export interface SessionDataCtx extends BranchSource {
   cwd: string;
 }
 
+/**
+ * The composed context the session engine's production binding needs (`SessionDataCtx` for
+ * paths/branch + `ReportTarget` for the strict-append seam's loud failure reporting). Exported
+ * so `session/` consumes the reporting slice THROUGH this seam without importing `surfaces/`
+ * directly.
+ */
+export type SessionArtifactCtx = SessionDataCtx & ReportTarget;
+
 /**
  * The current session's run_id from the rebuilt workflow-state; `null` when the session has no
- * identity (no stamp fallback — see the header).
+ * identity (no stamp fallback — see the header) OR when the rebuilt id is unsafe as a path
+ * component (the read-path trust boundary: `isSafeRunId` — an unsafe persisted id must never
+ * reach a path derivation or a receipt).
  */
 export function activeSessionRunId(ctx: SessionDataCtx): string | null {
   try {
     const runId = rebuildWorkflowState(branchOf(ctx)).run_id;
-    if (typeof runId === "string" && runId.length > 0) return runId;
+    if (typeof runId === "string" && isSafeRunId(runId)) return runId;
   } catch {
     // a throwing getBranch means no resolvable identity — degrade to null
   }
@@ -72,13 +81,16 @@ export function activeSessionDataDir(ctx: SessionDataCtx): string | null {
   return sessionDataDir(ctx.cwd, runId);
 }
 
-/** Ensure the validated run root, then its data dir; `null` + a warning on failure. */
-export function ensureSessionDataDir(ctx: SessionDataCtx): string | null {
-  const runId = activeSessionRunId(ctx);
-  if (runId === null) return null;
-  const dir = sessionDataDir(ctx.cwd, runId);
+/**
+ * Ensure the validated run root, then its data dir, for an EXPLICIT run id; `null` + a warning
+ * on failure (an unsafe id is refused loudly by the write path's `ensureRunScratch`). The run
+ * identity is the CALLER's: the session engine passes its one validated id so storage, pointer,
+ * and receipt can never disagree.
+ */
+export function ensureSessionDataDir(cwd: string, runId: string): string | null {
+  const dir = sessionDataDir(cwd, runId);
   try {
-    ensureRunScratch(ctx.cwd, runId);
+    ensureRunScratch(cwd, runId);
     mkdirSync(dir, { recursive: true });
   } catch (error) {
     console.error(`perk: warning: could not create session data dir ${dir}: ${error}`);
@@ -88,13 +100,11 @@ export function ensureSessionDataDir(ctx: SessionDataCtx): string | null {
 }
 
 /**
- * Read a session-data file; `null` on no run_id or an absent file (normal, branchable), and on
- * read errors (with a stderr warning). Never throws.
+ * Read a run's session-data file; `null` on an absent file (normal, branchable) and on read
+ * errors (with a stderr warning). Never throws.
  */
-export function readSessionData(ctx: SessionDataCtx, name: string): string | null {
-  const dir = activeSessionDataDir(ctx);
-  if (dir === null) return null;
-  const path = join(dir, name);
+export function readSessionData(cwd: string, runId: string, name: string): string | null {
+  const path = join(sessionDataDir(cwd, runId), name);
   if (!existsSync(path)) return null;
   try {
     return readFileSync(path, "utf8");
@@ -104,16 +114,39 @@ export function readSessionData(ctx: SessionDataCtx, name: string): string | nul
   }
 }
 
+export type SessionDataRead =
+  | { status: "found"; content: string }
+  | { status: "absent" }
+  | { status: "io-error" };
+
+/** Strict content port: only ENOENT is absent; unsafe redirects and non-files are I/O refusals. */
+export function readSessionDataStrict(cwd: string, runId: string, name: string): SessionDataRead {
+  try {
+    if (!isSafeRunId(name)) return { status: "io-error" };
+    const dir = canonicalSessionDataDir(cwd, runId, { create: false });
+    if (dir === null) return { status: "absent" };
+    const path = join(dir, name);
+    if (!lstatSync(path).isFile()) return { status: "io-error" };
+    return { status: "found", content: readFileSync(path, "utf8") };
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return { status: "absent" };
+    }
+    return { status: "io-error" };
+  }
+}
+
 /**
- * Write a session-data file (creating the data dir lazily); returns the absolute path, or
- * `null` + a stderr warning on any failure. Never throws.
+ * Write a run's session-data file (creating the data dir lazily); returns the absolute path,
+ * or `null` + a stderr warning on any failure. Never throws.
  */
 export function writeSessionData(
-  ctx: SessionDataCtx,
+  cwd: string,
+  runId: string,
   name: string,
   content: string,
 ): string | null {
-  const dir = ensureSessionDataDir(ctx);
+  const dir = ensureSessionDataDir(cwd, runId);
   if (dir === null) return null;
   const path = join(dir, name);
   try {
@@ -126,106 +159,6 @@ export function writeSessionData(
 }
 
 /** The session-artifact digest convention: `sha256:` + lowercase hex of the UTF-8 bytes. */
-export function digestSessionData(content: string): string {
-  return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
-}
-
-/** Per-name pointer identity: same run_id + same digest (the custom-equals comparator). */
-function artifactMapsEqual(
-  rebuilt: Record<string, SessionArtifactPointer> | null | undefined,
-  expected: Record<string, SessionArtifactPointer> | null | undefined,
-): boolean {
-  const a = rebuilt ?? {};
-  const b = expected ?? {};
-  const names = Object.keys(b);
-  if (Object.keys(a).length !== names.length) return false;
-  return names.every(
-    (name) => a[name]?.run_id === b[name]?.run_id && a[name]?.digest === b[name]?.digest,
-  );
-}
-
-/**
- * Write a session artifact AND record its provenance pointer in `perk:workflow-state`.
- * Returns the absolute written path only when the artifact is *fully recorded* (file written,
- * read back, digested, pointer strict-appended); `null` on any failure — the seam/module has
- * already warned, and an orphan file (pointer-append failure) is gitignored scratch for the
- * GC to prune. Never throws.
- */
-export function writeSessionArtifact(
-  sink: EntrySink,
-  ctx: SessionDataCtx & ReportTarget,
-  name: string,
-  content: string,
-): string | null {
-  const written = writeSessionData(ctx, name, content);
-  if (written === null) return null; // already warned; never point at an unwritten file
-
-  // Digest the bytes as read back from disk — catches encoding/disk surprises.
-  const readBack = readSessionData(ctx, name);
-  if (readBack === null) {
-    console.error(`perk: warning: session artifact ${written} unreadable after write`);
-    return null;
-  }
-
-  const runId = activeSessionRunId(ctx);
-  if (runId === null) return null; // unreachable after a successful write; belt-and-braces
-  const pointer: SessionArtifactPointer = {
-    run_id: runId,
-    name,
-    path: relative(ctx.cwd, written),
-    digest: digestSessionData(readBack),
-    at: new Date().toISOString(),
-  };
-
-  // Per-field LWW: each append must carry the WHOLE merged map so sibling artifacts survive.
-  const merged: Record<string, SessionArtifactPointer> = {
-    ...(rebuildWorkflowState(branchOf(ctx)).session_artifacts ?? {}),
-    [name]: pointer,
-  };
-  const ok = appendWorkflowState(sink, ctx, {
-    data: { session_artifacts: merged },
-    field: "session_artifacts",
-    expected: merged,
-    scope: "session-data",
-    failure: `session_artifacts pointer read-back failed for ${name}`,
-    equals: artifactMapsEqual,
-  });
-  return ok ? written : null;
-}
-
-/**
- * Read a session artifact through its provenance pointer; fail-open `null` when validation
- * refuses. Tiering: no identity / no pointer / run_id mismatch (the designed fork-isolation
- * path) → silent `null`; pointer matches but the file is absent, unreadable, or its digest
- * differs (rewind, tamper) → stderr warning + `null`. The path is always DERIVED from
- * `run_id` + `name` via the seam — `pointer.path` is never dereferenced. Never throws.
- */
-export function readSessionArtifact(
-  ctx: SessionDataCtx,
-  name: string,
-): { path: string; content: string } | null {
-  const runId = activeSessionRunId(ctx);
-  if (runId === null) return null;
-  let pointer: SessionArtifactPointer | undefined;
-  try {
-    pointer = rebuildWorkflowState(branchOf(ctx)).session_artifacts?.[name];
-  } catch {
-    return null;
-  }
-  if (pointer === undefined) return null;
-  if (pointer.run_id !== runId) return null; // fork / concurrent isolation — by design, silent
-
-  const path = join(sessionDataDir(ctx.cwd, runId), name);
-  const content = readSessionData(ctx, name);
-  if (content === null) {
-    console.error(`perk: warning: session artifact ${name} has a pointer but no file at ${path}`);
-    return null;
-  }
-  if (digestSessionData(content) !== pointer.digest) {
-    console.error(
-      `perk: warning: session artifact ${path} digest mismatch (rewound or modified) — refusing`,
-    );
-    return null;
-  }
-  return { path, content };
+export function digestSessionData(content: string | Uint8Array): string {
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }