@mgiles/perk 3.2.0 → 3.3.0

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")}`;
 }