@mgiles/perk 3.1.0 → 3.3.0

package/extension/session/workflowSession.ts

@@ -0,0 +1,971 @@
+// The feature-facing WorkflowSession seam AND its one deep engine (module-contracts.md's
+// `session/` home): run identity + verified session-artifact operations + the named
+// workflow-state reads (`nodeClaim`/`activeObjective`/`activeSessionPlanRef`/`reviewPosts`) and
+// the closed change union, sized strictly to the callers that exist. No `stage`/`mode`/pointer-map
+// snapshot — no feature caller consumes them through the seam yet (stage routing and the gate
+// stay adapter-side; startup's lifecycle facts live in `session/lifecycle.ts`); the seam grows
+// only from proven callers.
+//
+// ONE ENGINE, TWO NARROW PORTS. `openWorkflowSession(deps)` implements every WorkflowChange
+// invariant, the full artifact discipline (name policy → identity refusal → unchanged
+// short-circuit → store → read-back digest → pointer construction → merged-map strict append;
+// the classified read tiers), and all error/problem text exactly once. Backings supply only
+// mechanics: a `SessionStateStore` (session/lifecycle.ts — the same workflow-state store port
+// the identity lifecycle uses) and an `ArtifactContentStore` (content I/O only, zero error
+// prose). The production binding is `branchWorkflowSession.ts` (branch/file); the deterministic
+// in-memory binding lives in `testing/memoryWorkflowSession.ts` (dev-only, outside the
+// production corpus). Both are exercised by the shared interface suite in
+// `workflowSession.test.ts`.
+//
+// Identity is OPTIONAL: `runId` is `string | null` and a session always opens — the plan-save
+// surfaces prove the shape (workflow-state appends are branch-backed and identity-independent:
+// an identity-less save still links `active_plan_ref`). The ARTIFACT ops classify no-identity as
+// `rejected` (write) / `absent` (ordinary read) / `invalid` (strict read); the state ops work without
+// identity. Identity is TRUST-NARROWED: a rebuilt `run_id` that is unsafe as a path component
+// (`isSafeRunId`) degrades to no-identity before any path derivation — a hostile persisted id
+// can never steer artifact reads outside the run root or reach a receipt.
+//
+// Results carry the session-owned `SessionArtifactReceipt` — validated or re-derived values
+// ONLY (never the persisted pointer, whose rebuilt fields are unvalidated branch data). The
+// full `SessionArtifactPointer` wire shape is still constructed here for the
+// `session_artifacts` strict append (contracts §8.3's persistence format) — derived at the
+// storage boundary, internal to the engine, never exposed through results.
+//
+// `apply(change)` is a CLOSED union admitted from proven callers (never a feature dispatcher);
+// the first two variants come from the plan-save surfaces, the second two from the objective
+// flows (`transitionObjectiveNode`'s planning arm records the claim; `saveObjective`'s
+// post-save linkage sets `active_objective`). No snapshot payloads on the applied/unchanged
+// arms — nothing consumes them (narrow until proven).
+
+import { isSafeRunId, type PlanRef } from "../substrate/cache.ts";
+import { digestSessionData, type SessionDataRead } from "../substrate/sessionData.ts";
+import {
+  nodeClaimsEqual,
+  planRefsEqual,
+  type SessionArtifactPointer,
+} from "../substrate/workflowState.ts";
+import type { SessionStateStore } from "./lifecycle.ts";
+
+/** Session-owned vocabulary: features import the plan-ref shape through the session seam. */
+export type { PlanRef };
+/** One digest convention, exposed through the session boundary for bound review consumers. */
+export { digestSessionData };
+
+/** A human-readable problem description (the backing has already warned where its tier is loud). */
+export type SessionProblem = string;
+
+/** The refinement stage id (the session keys its subject mapping + stage-only entry on it). */
+const REFINE_STAGE_ID = "objective-refine";
+
+/**
+ * The refinement grounding-context artifact name — session-owned vocabulary because the review
+ * binding fences the refinement subject on this artifact's digest (features import it here).
+ */
+export const REFINEMENT_CONTEXT_ARTIFACT = "objective-refinement-context.json";
+
+/**
+ * Session-owned artifact receipt: validated or re-derived values ONLY. `runId` is the
+ * safe-narrowed active run id (matches the persisted pointer's `run_id` by construction);
+ * `path` is re-derived from the content store (fs: repo-relative; memory: the name) — NEVER a
+ * persisted pointer field; `digest` is proven — computed from the bytes read back (applied) or
+ * from the stored bytes during the unchanged probe.
+ */
+export interface SessionArtifactReceipt {
+  runId: string;
+  path: string;
+  digest: string;
+}
+
+/**
+ * The artifact content port: content I/O only, mechanical results, zero error prose —
+ * classification, policy, and all problem text are engine-owned. Every operation receives the
+ * ENGINE-VALIDATED run id (the artifact namespace), so storage, pointer, and receipt share one
+ * identity by construction — a backing never derives its own.
+ */
+export interface ArtifactContentStore {
+  /** Persist bytes under the run; false = refusal (the port has already warned where its tier is loud). */
+  store(runId: string, name: string, content: string): boolean;
+  /** The run's current bytes; null = missing/unreadable. */
+  load(runId: string, name: string): string | null;
+  /** Strict reads distinguish genuine absence from I/O refusal; no fallback to load(). */
+  loadStrict(runId: string, name: string): SessionDataRead;
+  /** The receipt/warning display path, re-derived from the given identity — NEVER a persisted pointer field. */
+  displayPath(runId: string, name: string): string;
+}
+
+/**
+ * The classified artifact read. `absent` is the silent, branchable tier (no identity, no
+ * pointer, or a cross-run fork pointer — designed isolation); `invalid` is the loud tier (a
+ * pointer whose file is missing or digest-mismatched — rewind/tamper). Opt-in strict reads also
+ * classify missing identity, malformed provenance, orphan bytes and I/O failure as `invalid`;
+ * they return problems to the authorizing caller rather than emitting ordinary read warnings.
+ */
+export type ReadArtifactResult =
+  | { status: "found"; content: string }
+  | { status: "absent" }
+  | { status: "invalid"; problem: SessionProblem };
+
+/**
+ * The classified artifact write — the verified state op: `applied` proves the file AND the
+ * strict-appended `session_artifacts` pointer both landed and read back; `unchanged` is the
+ * byte-identical short-circuit (the recorded pointer already proves these bytes); `rejected`
+ * refused before any effect (including the no-identity refusal — artifacts need a run_id);
+ * `unverified` means an effect may have landed but the read-back proof failed — never
+ * consumable.
+ */
+export type WriteArtifactResult =
+  | { status: "applied"; receipt: SessionArtifactReceipt }
+  | { status: "unchanged"; receipt: SessionArtifactReceipt }
+  | { status: "unverified"; problem: SessionProblem }
+  | { status: "rejected"; problem: SessionProblem };
+
+/**
+ * The last automated `/pr-review` outcome (`last_pr_review`, contracts §8.3): exactly the
+ * record the `post_pr_review` post surface constructs on a real success. After a recorded wave,
+ * `angles` is the authoritative attempted manifest and `covered_angles` its schema-valid
+ * subset; standalone posts use the caller's angles for both.
+ */
+export interface PrReviewRecord {
+  pr: number;
+  verdict: "clean" | "actionable";
+  angles: readonly string[];
+  covered_angles: readonly string[];
+  comment_count: number | null;
+  mode: string | null;
+  at: string;
+}
+
+/**
+ * The last curated review-door outcome (`last_review`, contracts §8.3): exactly the record the
+ * `submit_pr_review` post surface constructs on a real success. `event` stays `string` in the
+ * record — the decode boundary already constrains it; the stored field is render-only.
+ */
+export interface ReviewSubmissionRecord {
+  pr: number;
+  event: string;
+  comment_count: number | null;
+  mode: string | null;
+  at: string;
+}
+
+/** The four known review-classification count keys the finalizer records (§8.3). */
+export interface ReviewBatchCounts {
+  actionable?: number;
+  informational?: number;
+  praise?: number;
+  question?: number;
+}
+
+/**
+ * The last finalized review batch (`last_review_batch`, contracts §8.3): exactly the record the
+ * address finalizer constructs after publication and corroborated full thread resolution.
+ */
+export interface ReviewBatchRecord {
+  pr: number | null;
+  counts: ReviewBatchCounts | null;
+  resolved_thread_ids: string[];
+  at: string;
+}
+
+/** One `review_posts` ledger row: a REAL curated submission that reached GitHub (§8.3). */
+export interface ReviewPostRow {
+  pr: number;
+  event: string;
+  at: string;
+}
+
+/**
+ * Tolerant re-narrow of a rebuilt `review_posts` list (best-effort tier: a malformed row is
+ * dropped, never a refusal — the ledger only ever grows from the seam's own writes).
+ */
+export function reviewPostsOf(raw: unknown): ReviewPostRow[] {
+  if (!Array.isArray(raw)) return [];
+  const rows: ReviewPostRow[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+    const row = item as Record<string, unknown>;
+    if (typeof row.pr !== "number" || !Number.isInteger(row.pr)) continue;
+    if (typeof row.event !== "string" || typeof row.at !== "string") continue;
+    rows.push({ pr: row.pr, event: row.event, at: row.at });
+  }
+  return rows;
+}
+
+/** Ledger equality for the read-back verification (order-sensitive — posting order matters). */
+export function reviewPostsEqual(rebuilt: unknown, expected: unknown): boolean {
+  const a = reviewPostsOf(rebuilt);
+  const b = reviewPostsOf(expected);
+  if (a.length !== b.length) return false;
+  return a.every(
+    (row, i) => row.pr === b[i]?.pr && row.event === b[i]?.event && row.at === b[i]?.at,
+  );
+}
+
+/**
+ * The closed workflow-state change union — admitted variant-by-variant from proven callers
+ * (the proven callers: the plan-save surfaces). Reads stay NAMED (`nodeClaim()`); only changes
+ * ride the union.
+ */
+export type WorkflowChange =
+  /** Link the live session to a saved plan: append `active_plan_ref` iff it differs. */
+  | { kind: "link-plan-ref"; ref: PlanRef }
+  /**
+   * Clear `objective_node_claim` iff the live claim matches BOTH fields (never clobbers an
+   * unrelated claim — a save linked to objective B node 1.1 must not clear objective A's 1.1).
+   */
+  | { kind: "clear-node-claim"; claim: { objective: string; node: string } }
+  /**
+   * Record `objective_node_claim` iff the live claim differs (`nodeClaimsEqual`) — an
+   * idempotent re-claim short-circuits `unchanged` (the re-append "refresh" carries no
+   * semantic payload: the claim has no timestamp and rebuilds identically).
+   */
+  | { kind: "record-node-claim"; claim: { objective: string; node: string } }
+  /** Link the live session to a saved objective: append `active_objective` iff it differs. */
+  | { kind: "link-objective"; objective: string }
+  /**
+   * Enter the refinement stage from a warm session: append `stage: "objective-refine"` iff the
+   * live stage differs — a STAGE-ONLY change (never a claim, plan-ref, objective or mode write;
+   * the warm `/objective-refine` entry sets the stage the cold handoff would have carried). An
+   * idempotent re-entry short-circuits `unchanged`.
+   */
+  | { kind: "enter-refinement-stage" }
+  /**
+   * Record the last automated `/pr-review` outcome: ONE `last_pr_review` append (LWW), strict
+   * read-back. No pre-read, no dedupe (same runtime invariant as `record-review`:
+   * `applied`/`unverified`/`rejected` only).
+   */
+  | { kind: "record-pr-review"; record: PrReviewRecord }
+  /**
+   * Record the last curated review-door outcome: ONE `last_review` append (LWW), strict
+   * read-back. No pre-read, no dedupe — the `already_posted` resume guard is feature-op policy
+   * upstream, so at runtime this yields `applied`/`unverified`/`rejected` only (a runtime
+   * invariant, not a type claim).
+   */
+  | { kind: "record-review"; record: ReviewSubmissionRecord }
+  /**
+   * Append one `review_posts` ledger row: read-rebuild-append of the whole ordered list, with
+   * the order-sensitive `reviewPostsEqual` read-back. The pre-read is FAIL-CLOSED and
+   * STRICT-DECODED (an unrebuildable or malformed persisted ledger refuses the append — see the
+   * engine's arm); no dedupe (same invariant as `record-review`:
+   * `applied`/`unverified`/`rejected` only at runtime).
+   */
+  | { kind: "append-review-post"; row: ReviewPostRow }
+  /**
+   * Record the last finalized review batch: ONE `last_review_batch` append (LWW), strict
+   * read-back. No pre-read, no dedupe — the corroborated-success-first ordering is feature-op
+   * policy upstream (`applied`/`unverified`/`rejected` only at runtime).
+   */
+  | { kind: "record-review-batch"; record: ReviewBatchRecord };
+
+/**
+ * The classified change outcome: `applied` proves the append landed and read back; `unchanged`
+ * is the idempotent short-circuit (link: the rebuilt ref already equals; clear: no matching
+ * claim); `unverified` means the append may have landed but the read-back proof failed (the
+ * branch backing has already warned loudly); `rejected` refused before any effect.
+ */
+export type WorkflowChangeResult =
+  | { status: "applied" }
+  | { status: "unchanged" }
+  | { status: "unverified"; problem: SessionProblem }
+  | { status: "rejected"; problem: SessionProblem };
+
+/**
+ * The feature-facing session: optional identity + verified artifact ops + the named
+ * workflow-state reads and the closed change union. A session ALWAYS opens; `runId: null` is
+ * the identity-less arm (artifact ops classify it; state ops still work).
+ */
+export interface WorkflowSession {
+  readonly runId: string | null;
+  /** Strict live identity only; completion must not revalidate source or routing inputs. */
+  currentRunIdentity():
+    | { ok: true; runId: string }
+    | { ok: false; reason: "no-identity" | "invalid-state" };
+  /** Strict single-snapshot routing read; malformed relevant claims refuse, never disappear. */
+  draftReviewContext():
+    | {
+        ok: true;
+        runId: string;
+        subject: "plan" | "objective" | "gist" | "refinement";
+        warmNodeClaim: { objective: string; node: string } | null;
+      }
+    | { ok: false; reason: "no-identity" | "invalid-state" };
+  readArtifact(name: string, options?: { provenance: "strict" }): ReadArtifactResult;
+  /** Strict writes refuse broken prior provenance; callers still own exclusion and failure residue. */
+  writeArtifact(
+    name: string,
+    content: string,
+    options?: { provenance: "strict" },
+  ): WriteArtifactResult;
+  /** Snapshot read of the rebuilt `objective_node_claim` (malformed ⇒ null). */
+  nodeClaim(): { objective: string; node: string } | null;
+  /** Snapshot read of the rebuilt `active_objective` (malformed/throwing ⇒ null). */
+  activeObjective(): string | null;
+  /**
+   * Shape-validated, fail-open read of the LIVE SESSION's rebuilt `active_plan_ref` — session
+   * linkage ONLY, deliberately with no checkout `cache.plan-ref` fallback (the checkout selector
+   * can name a future plan unrelated to this session; the checkout-first read is
+   * `substrate/workflowState.ts::activePlanRef`, a different authority). Absent, malformed, or
+   * unreadable linkage reads null. For continuation rendering, never permission, verified
+   * linkage, artifact validation, or review routing.
+   */
+  activeSessionPlanRef(): PlanRef | null;
+  /** Fail-open read of the rebuilt `review_posts` ledger (malformed rows dropped, never a refusal). */
+  reviewPosts(): ReviewPostRow[];
+  apply(change: WorkflowChange): WorkflowChangeResult;
+}
+
+// ------------------------------------------------------------------------------- the engine
+
+/**
+ * Validate a session-artifact name at the seam: non-empty, no path separators (the artifact
+ * name keys the pointer map and joins under the run's data dir — a separator would escape it).
+ * Returns the problem string, or `null` when the name is safe. Name policy is refusal policy —
+ * it lives with the engine, not the backings.
+ */
+export function sessionArtifactNameProblem(name: string): string | null {
+  if (name.trim() === "") return "session artifact name is empty";
+  if (name.includes("/") || name.includes("\\")) {
+    return `session artifact name ${JSON.stringify(name)} carries a path separator`;
+  }
+  return null;
+}
+
+/**
+ * The ONE persisted-pointer decode: accept a rebuilt `session_artifacts` value only when it is
+ * SHAPE-SOUND, and narrow the return to exactly the two fields the engine dereferences —
+ * branch data is unvalidated (`rebuildWorkflowState` trusts entry data), so a malformed session
+ * entry can put `null` — or anything else — where a pointer belongs, and the OTHER persisted
+ * fields (`path`, `name`, `at`) stay untrusted `unknown` even on a sound value (`path` is always
+ * re-derived, `name` is the map key, `at` has no consumer). Anything unsound reads as "no
+ * pointer" and never throws. Tests asserting persisted-pointer facts narrow through this —
+ * never a cast.
+ */
+export function soundPointer(candidate: unknown): { run_id: string; digest: string } | null {
+  if (typeof candidate !== "object" || candidate === null) return null;
+  const pointer = candidate as Record<string, unknown>;
+  if (typeof pointer.run_id !== "string" || typeof pointer.digest !== "string") return null;
+  return { run_id: pointer.run_id, digest: pointer.digest };
+}
+
+/** Per-name pointer identity: same run_id + same digest (each side narrowed via the decode). */
+function artifactMapsEqual(
+  rebuilt: Record<string, unknown> | null | undefined,
+  expected: Record<string, unknown> | 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) => {
+    const ra = soundPointer(a[name]);
+    const rb = soundPointer(b[name]);
+    // Unsound on both sides (junk siblings carried forward by the merged-map spread) compares
+    // equal — the append is verified on the pointers it can vouch for, never on junk shape.
+    if (ra === null || rb === null) return ra === rb;
+    return ra.run_id === rb.run_id && ra.digest === rb.digest;
+  });
+}
+
+/**
+ * Strict `review_posts` decode for the append pre-read — the ONE row schema is `reviewPostsOf`,
+ * consumed strictly: a present-but-malformed persisted ledger (non-array, or any row the
+ * tolerant decode would DROP) refuses with a problem naming the malformed variant instead of
+ * silently narrowing (a tolerant pre-read would let the whole-list LWW re-append ERASE
+ * malformed-but-possibly-real rows, violating the ledger invariant that a confirmed post is
+ * never erased by a write). Extra row fields are narrowed out, never a refusal.
+ */
+function strictReviewPosts(raw: unknown): { rows: ReviewPostRow[] } | { malformed: string } {
+  if (!Array.isArray(raw)) return { malformed: `not a list (${JSON.stringify(raw)})` };
+  const rows = reviewPostsOf(raw);
+  if (rows.length !== raw.length) {
+    return {
+      malformed: `${raw.length - rows.length} malformed row(s) in ${JSON.stringify(raw)}`,
+    };
+  }
+  return { rows };
+}
+
+/** The two ports the engine runs over — the backings supply ONLY these. */
+export interface WorkflowSessionDeps {
+  state: SessionStateStore;
+  artifacts: ArtifactContentStore;
+}
+
+/**
+ * The safe-narrowed active run id: the rebuilt `run_id`, non-empty AND safe as a path component
+ * (`isSafeRunId` — an unsafe persisted id degrades to no-identity BEFORE any path derivation);
+ * a throwing rebuild degrades to null (no resolvable identity, never a stamp).
+ */
+function activeRunId(state: SessionStateStore): string | null {
+  try {
+    const runId = state.rebuild().run_id;
+    if (typeof runId === "string" && isSafeRunId(runId)) return runId;
+  } catch {
+    // a throwing rebuild means no resolvable identity — degrade to null
+  }
+  return null;
+}
+
+/** The rebuilt `objective_node_claim`, read fail-open (malformed/throwing rebuild → null). */
+function readClaim(state: SessionStateStore): { objective: string; node: string } | null {
+  try {
+    const claim = state.rebuild().objective_node_claim ?? null;
+    if (
+      claim !== null &&
+      typeof claim.objective === "string" &&
+      claim.objective !== "" &&
+      typeof claim.node === "string" &&
+      claim.node !== ""
+    ) {
+      return claim;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** The rebuilt `active_objective`, read fail-open (malformed/throwing rebuild ⇒ null). */
+function readActiveObjective(state: SessionStateStore): string | null {
+  try {
+    const value = state.rebuild().active_objective ?? null;
+    return typeof value === "string" && value !== "" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Non-blank string guard for the session plan-ref decode (bytes are preserved, never trimmed). */
+const nonblank = (value: unknown): value is string =>
+  typeof value === "string" && value.trim() !== "";
+
+/**
+ * The ONE session-only plan-ref decode: the rebuilt `active_plan_ref` inspected as `unknown`
+ * (branch data is unvalidated) and accepted only in its persisted shape — non-blank string
+ * `provider`/`pr_id`/`url`, an all-string `labels` list, a REQUIRED `objective_id` that is null
+ * or a string, and `base` absent, null, or a string. The return is a reconstructed `PlanRef`
+ * carrying exactly those fields (extra persisted keys never escape; `base` omission is preserved
+ * versus an explicit null; no trimming, provider constraint, or URL parse). Fail-open: absent,
+ * malformed, or throwing rebuilds read null — the only consumer renders optional continuation
+ * guidance, so unreadability must degrade to "no plan named", never a thrown handler. One fresh
+ * rebuild per call; no checkout, artifact, append, or memoization.
+ */
+function readActiveSessionPlanRef(state: SessionStateStore): PlanRef | null {
+  try {
+    const ref: unknown = state.rebuild().active_plan_ref;
+    if (typeof ref !== "object" || ref === null) return null;
+    const { provider, pr_id, url, labels, objective_id, base } = ref as Record<string, unknown>;
+    if (!nonblank(provider) || !nonblank(pr_id) || !nonblank(url)) return null;
+    if (!Array.isArray(labels) || !labels.every((l): l is string => typeof l === "string")) {
+      return null;
+    }
+    if (objective_id !== null && typeof objective_id !== "string") return null;
+    if (base !== undefined && base !== null && typeof base !== "string") return null;
+    return {
+      provider,
+      pr_id,
+      url,
+      labels: [...labels],
+      objective_id,
+      ...(base !== undefined ? { base } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The rebuilt `review_posts` ledger, read fail-open (malformed rows drop; a throwing rebuild ⇒ []). */
+function readReviewPosts(state: SessionStateStore): ReviewPostRow[] {
+  try {
+    return reviewPostsOf(state.rebuild().review_posts);
+  } catch {
+    return [];
+  }
+}
+
+function strictArtifactMap(raw: unknown): Record<string, SessionArtifactPointer> {
+  if (raw === undefined || raw === null) return {};
+  if (
+    typeof raw !== "object" ||
+    Array.isArray(raw) ||
+    (Object.getPrototypeOf(raw) !== Object.prototype && Object.getPrototypeOf(raw) !== null)
+  ) {
+    throw new Error("session_artifacts map is malformed");
+  }
+  const entries: [string, SessionArtifactPointer][] = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (
+      !isSafeRunId(key) ||
+      key.trim() === "" ||
+      typeof value !== "object" ||
+      value === null ||
+      Array.isArray(value)
+    )
+      throw new Error("session_artifacts pointer is malformed");
+    const p = value as Record<string, unknown>;
+    if (
+      typeof p.run_id !== "string" ||
+      !isSafeRunId(p.run_id) ||
+      typeof p.digest !== "string" ||
+      !/^sha256:[0-9a-f]{64}$/.test(p.digest) ||
+      p.name !== key ||
+      typeof p.path !== "string" ||
+      p.path.length === 0 ||
+      typeof p.at !== "string" ||
+      p.at.length === 0
+    ) {
+      throw new Error("session_artifacts pointer is malformed");
+    }
+    entries.push([key, { run_id: p.run_id, name: key, path: p.path, digest: p.digest, at: p.at }]);
+  }
+  return Object.fromEntries(entries);
+}
+
+function strictArtifactRead(deps: WorkflowSessionDeps, name: string): ReadArtifactResult {
+  const invalid = (problem: string): ReadArtifactResult => ({ status: "invalid", problem });
+  if (!isSafeRunId(name) || sessionArtifactNameProblem(name) !== null) {
+    return invalid("unsafe session artifact name");
+  }
+  try {
+    // One snapshot: a throwing/malformed identity read is never evidence of absence.
+    const snapshot = deps.state.rebuild();
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+      return invalid("session artifact state is malformed");
+    }
+    const runId = snapshot.run_id;
+    if (typeof runId !== "string" || !isSafeRunId(runId)) {
+      return invalid("session has no safe run_id — strict artifact reads need identity");
+    }
+    // Validate siblings too: the next whole-map append must not launder malformed provenance.
+    const map = strictArtifactMap(snapshot.session_artifacts);
+    const pointer = Object.hasOwn(map, name) ? map[name] : null;
+    // Never dereference inherited pointers. Inspect ONLY the active run's namespace, including
+    // when there is no pointer: bytes without current-run provenance are an orphan, not absent.
+    const loaded = deps.artifacts.loadStrict(runId, name);
+    if (loaded.status === "io-error") return invalid(`session artifact ${name} I/O failure`);
+    if (pointer == null || pointer.run_id !== runId) {
+      return loaded.status === "absent"
+        ? { status: "absent" }
+        : invalid(`session artifact ${name} has no current-run provenance (orphan)`);
+    }
+    if (loaded.status === "absent")
+      return invalid(`session artifact ${name} has a pointer but no file`);
+    if (digestSessionData(loaded.content) !== pointer.digest) {
+      return invalid(`session artifact ${name} digest mismatch (rewound or modified)`);
+    }
+    return { status: "found", content: loaded.content };
+  } catch {
+    return invalid(`session artifact ${name} strict read failed`);
+  }
+}
+
+/**
+ * Open a session over the two ports — the ONE deep implementation of the seam. ALWAYS opens;
+ * `runId: null` is the identity-less arm (artifact writes reject, reads read absent; the state
+ * ops are store-backed and identity-independent). `runId` is captured at open and re-derived
+ * per artifact call (a fork entry appended mid-session re-keys the artifact ops — today's
+ * behavior). Loudness: the strict-append port reports its own read-back failures (the
+ * classified-append seam's report() channel inside the production binding); the engine warns on
+ * stderr for the loud read tier (rewind/tamper) and the unreadable-after-write arm.
+ */
+export function openWorkflowSession(deps: WorkflowSessionDeps): WorkflowSession {
+  const { state, artifacts } = deps;
+
+  return {
+    runId: activeRunId(state),
+    currentRunIdentity() {
+      try {
+        const snapshot = state.rebuild();
+        if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot))
+          return { ok: false, reason: "invalid-state" };
+        const runId = snapshot.run_id;
+        return typeof runId === "string" && isSafeRunId(runId)
+          ? { ok: true, runId }
+          : { ok: false, reason: "no-identity" };
+      } catch {
+        return { ok: false, reason: "invalid-state" };
+      }
+    },
+    draftReviewContext() {
+      try {
+        const snapshot = state.rebuild();
+        const runId = snapshot.run_id;
+        if (typeof runId !== "string" || !isSafeRunId(runId))
+          return { ok: false, reason: "no-identity" };
+        const stage = snapshot.stage;
+        if (stage != null && (typeof stage !== "string" || !stage.trim()))
+          return { ok: false, reason: "invalid-state" };
+        const subject =
+          stage === "objective-author" || stage === "objective-save"
+            ? "objective"
+            : stage === "gist-author"
+              ? "gist"
+              : stage === REFINE_STAGE_ID
+                ? "refinement"
+                : "plan";
+        const raw: unknown = subject === "plan" ? snapshot.objective_node_claim : null;
+        let warmNodeClaim: { objective: string; node: string } | null = null;
+        if (raw != null) {
+          if (typeof raw !== "object" || Array.isArray(raw))
+            return { ok: false, reason: "invalid-state" };
+          const claim = raw as Record<string, unknown>;
+          if (
+            Object.keys(claim).length !== 2 ||
+            typeof claim.objective !== "string" ||
+            !claim.objective.trim() ||
+            typeof claim.node !== "string" ||
+            !claim.node.trim()
+          )
+            return { ok: false, reason: "invalid-state" };
+          warmNodeClaim = { objective: claim.objective, node: claim.node };
+        }
+        return { ok: true, runId, subject, warmNodeClaim };
+      } catch {
+        return { ok: false, reason: "invalid-state" };
+      }
+    },
+    readArtifact(name: string, options): ReadArtifactResult {
+      if (options?.provenance === "strict") return strictArtifactRead(deps, name);
+      const runId = activeRunId(state);
+      if (runId === null) return { status: "absent" }; // no identity — silent, branchable
+      let pointer: { run_id: string; digest: string } | null;
+      try {
+        pointer = soundPointer(state.rebuild().session_artifacts?.[name]);
+      } catch {
+        return { status: "absent" };
+      }
+      if (pointer === null) return { status: "absent" }; // no pointer — or a malformed one (no provenance)
+      if (pointer.run_id !== runId) return { status: "absent" }; // fork isolation — by design, silent
+
+      const content = artifacts.load(runId, name);
+      if (content === null) {
+        console.error(
+          `perk: warning: session artifact ${name} has a pointer but no file at ` +
+            artifacts.displayPath(runId, name),
+        );
+        return { status: "invalid", problem: `session artifact ${name} has a pointer but no file` };
+      }
+      if (digestSessionData(content) !== pointer.digest) {
+        console.error(
+          `perk: warning: session artifact ${artifacts.displayPath(runId, name)} digest mismatch ` +
+            "(rewound or modified) — refusing",
+        );
+        return {
+          status: "invalid",
+          problem: `session artifact ${name} digest mismatch (rewound or modified)`,
+        };
+      }
+      return { status: "found", content };
+    },
+    writeArtifact(name: string, content: string, options): WriteArtifactResult {
+      const strict = options?.provenance === "strict";
+      if (strict) {
+        const prior = strictArtifactRead(deps, name);
+        if (prior.status === "invalid") return { status: "rejected", problem: prior.problem };
+      }
+      let effectAttempted = false;
+      try {
+        const nameProblem = sessionArtifactNameProblem(name);
+        if (nameProblem !== null) return { status: "rejected", problem: nameProblem };
+
+        const runId = activeRunId(state);
+        if (runId === null) {
+          return {
+            status: "rejected",
+            problem: "session has no run_id — session artifacts need identity",
+          };
+        }
+
+        // The unchanged short-circuit: a byte-identical rewrite is a no-op (no store, no fresh
+        // pointer entry) — the recorded pointer already proves exactly these bytes. QUIET by
+        // design: a stale/broken/malformed pointer simply fails the probe and the write proceeds
+        // (the probe must never emit the read tier's rewind warnings). The receipt is fully
+        // re-derived — junk persisted fields are unobservable.
+        let current: { run_id: string; digest: string } | null;
+        try {
+          const snapshot = state.rebuild();
+          if (strict && snapshot.run_id !== runId) throw new Error("session identity changed");
+          current = strict
+            ? (strictArtifactMap(snapshot.session_artifacts)[name] ?? null)
+            : soundPointer(snapshot.session_artifacts?.[name]);
+        } catch (error) {
+          if (strict) throw error;
+          current = null;
+        }
+        if (current !== null && current.run_id === runId) {
+          const checked = strict ? strictArtifactRead(deps, name) : null;
+          if (checked !== null && checked.status !== "found") {
+            return {
+              status: "rejected",
+              problem: `session artifact ${name} provenance changed before write`,
+            };
+          }
+          const stored =
+            checked?.status === "found" ? checked.content : artifacts.load(runId, name);
+          if (
+            stored !== null &&
+            digestSessionData(stored) === current.digest &&
+            current.digest === digestSessionData(content)
+          ) {
+            return {
+              status: "unchanged",
+              receipt: {
+                runId,
+                path: artifacts.displayPath(runId, name),
+                digest: digestSessionData(stored),
+              },
+            };
+          }
+        }
+
+        effectAttempted = true;
+        if (!artifacts.store(runId, name, content)) {
+          // the port already warned; never point at an unwritten file
+          return {
+            status: "rejected",
+            problem: `could not write session data ${name} (see warnings)`,
+          };
+        }
+
+        // Digest the bytes as read back from the store — catches encoding/disk surprises.
+        const strictReadBack = strict ? artifacts.loadStrict(runId, name) : null;
+        const readBack =
+          strictReadBack === null
+            ? artifacts.load(runId, name)
+            : strictReadBack.status === "found"
+              ? strictReadBack.content
+              : null;
+        if (readBack === null) {
+          const problem = `session artifact ${artifacts.displayPath(runId, name)} unreadable after write`;
+          console.error(`perk: warning: ${problem}`);
+          return { status: "unverified", problem };
+        }
+
+        if (strict && readBack !== content) {
+          return {
+            status: "unverified",
+            problem: `session artifact ${name} write read-back differs`,
+          };
+        }
+
+        // The persisted wire shape (contracts §8.3) — constructed at the storage boundary,
+        // internal to the engine, never exposed through results.
+        const pointer: SessionArtifactPointer = {
+          run_id: runId,
+          name,
+          path: artifacts.displayPath(runId, name),
+          digest: digestSessionData(readBack),
+          at: new Date().toISOString(),
+        };
+
+        // Per-field LWW: each append must carry the WHOLE merged map so sibling artifacts survive
+        // (junk siblings carry forward unchanged — existing LWW behavior).
+        const latest = state.rebuild();
+        if (strict && latest.run_id !== runId) {
+          return { status: "unverified", problem: "session identity changed after artifact write" };
+        }
+        const merged: Record<string, unknown> = {
+          ...(strict
+            ? strictArtifactMap(latest.session_artifacts)
+            : (latest.session_artifacts ?? {})),
+          [name]: pointer,
+        };
+        const appended = state.appendVerified({
+          data: { session_artifacts: merged },
+          field: "session_artifacts",
+          expected: merged,
+          scope: "session-data",
+          failure: `session_artifacts pointer read-back failed for ${name}`,
+          equals: artifactMapsEqual,
+        });
+        if (appended.status !== "applied") {
+          // already reported through the strict-append port
+          return {
+            status: "unverified",
+            problem: `session_artifacts pointer read-back failed for ${name}`,
+          };
+        }
+        if (strict) {
+          const verified = strictArtifactRead(deps, name);
+          if (verified.status !== "found" || verified.content !== content) {
+            return {
+              status: "unverified",
+              problem: `session artifact ${name} strict write verification failed`,
+            };
+          }
+        }
+        return {
+          status: "applied",
+          receipt: { runId, path: pointer.path, digest: pointer.digest },
+        };
+      } catch (error) {
+        if (!strict) throw error;
+        return {
+          status: effectAttempted ? "unverified" : "rejected",
+          problem: `session artifact ${name} strict write failed`,
+        };
+      }
+    },
+    nodeClaim() {
+      return readClaim(state);
+    },
+    activeObjective() {
+      return readActiveObjective(state);
+    },
+    activeSessionPlanRef() {
+      return readActiveSessionPlanRef(state);
+    },
+    reviewPosts() {
+      return readReviewPosts(state);
+    },
+    apply(change: WorkflowChange): WorkflowChangeResult {
+      switch (change.kind) {
+        case "link-plan-ref": {
+          const ref = change.ref;
+          // The pre-read dedupe is deliberately NOT try/caught — a throwing rebuild propagates.
+          if (planRefsEqual(state.rebuild().active_plan_ref ?? null, ref)) {
+            return { status: "unchanged" };
+          }
+          // The classified strict-append distinguishes a PROVEN refusal-before-effect (the
+          // append threw and the rebuilt field never changed — `rejected`) from a read-back
+          // miss (`unverified`: an append may have landed unproven); its report() path stays
+          // the loudness channel. `ClassifiedAppend` IS the seam's change vocabulary.
+          return state.appendVerified({
+            data: { active_plan_ref: ref },
+            field: "active_plan_ref",
+            expected: ref,
+            scope: "plan-save",
+            failure: `plan-ref read-back failed for ${ref.provider}:${ref.pr_id}`,
+            equals: planRefsEqual,
+          });
+        }
+        case "clear-node-claim": {
+          const claim = change.claim;
+          // Never clobber an unrelated claim: clear only when the LIVE claim matches BOTH
+          // fields (same-node/different-objective stays untouched).
+          if (!nodeClaimsEqual(readClaim(state), claim)) return { status: "unchanged" };
+          return state.appendVerified({
+            data: { objective_node_claim: null },
+            field: "objective_node_claim",
+            expected: null,
+            scope: "plan-save",
+            failure: `objective_node_claim clear read-back failed for node ${claim.node}`,
+            equals: nodeClaimsEqual,
+          });
+        }
+        case "record-node-claim": {
+          const claim = change.claim;
+          // The idempotent re-claim short-circuit: an equal live claim rebuilds identically, so
+          // a re-append would carry no semantic payload (the claim has no timestamp).
+          if (nodeClaimsEqual(readClaim(state), claim)) return { status: "unchanged" };
+          return state.appendVerified({
+            data: { objective_node_claim: claim },
+            field: "objective_node_claim",
+            expected: claim,
+            scope: "objective-plan",
+            failure: `objective_node_claim read-back failed for #${claim.objective} node ${claim.node}`,
+            equals: nodeClaimsEqual,
+          });
+        }
+        case "link-objective": {
+          const objective = change.objective;
+          if (readActiveObjective(state) === objective) return { status: "unchanged" };
+          return state.appendVerified({
+            data: { active_objective: objective },
+            field: "active_objective",
+            expected: objective,
+            scope: "objective-save",
+            failure: `active_objective read-back failed for #${objective}`,
+          });
+        }
+        case "enter-refinement-stage": {
+          if (state.rebuild().stage === REFINE_STAGE_ID) return { status: "unchanged" };
+          return state.appendVerified({
+            data: { stage: REFINE_STAGE_ID },
+            field: "stage",
+            expected: REFINE_STAGE_ID,
+            scope: "objective-refine",
+            failure: `stage read-back failed for ${REFINE_STAGE_ID}`,
+          });
+        }
+        case "record-pr-review": {
+          // No pre-read/dedupe by design (the single-use wave state is feature-op policy
+          // upstream): at runtime this yields applied/unverified/rejected only.
+          return state.appendVerified({
+            data: { last_pr_review: change.record },
+            field: "last_pr_review",
+            expected: change.record,
+            scope: "pr-review",
+            failure: "last_pr_review read-back failed",
+          });
+        }
+        case "record-review": {
+          // No pre-read/dedupe by design (the resume guard is feature-op policy upstream): at
+          // runtime this yields applied/unverified/rejected only.
+          return state.appendVerified({
+            data: { last_review: change.record },
+            field: "last_review",
+            expected: change.record,
+            scope: "review",
+            failure: "last_review read-back failed",
+          });
+        }
+        case "record-review-batch": {
+          // No pre-read/dedupe by design (the corroborated-success ordering is feature-op
+          // policy upstream): at runtime this yields applied/unverified/rejected only.
+          return state.appendVerified({
+            data: { last_review_batch: change.record },
+            field: "last_review_batch",
+            expected: change.record,
+            scope: "address",
+            failure: "last_review_batch read-back failed",
+          });
+        }
+        case "append-review-post": {
+          // Read-rebuild-append: each write carries the whole ordered list (the resume reader
+          // sees every confirmed post); order-sensitive read-back. The pre-read is FAIL-CLOSED
+          // and STRICT — deliberately NOT the fail-open `reviewPosts()` read: appending over an
+          // unrebuildable OR malformed ledger would LWW-overwrite possibly-real earlier rows,
+          // and the resume guard would then permit duplicate GitHub reviews. Refusing before
+          // any effect keeps the asymmetric trust rule intact (a row may be MISSING spuriously,
+          // never PRESENT spuriously — and never erased by a write). An ABSENT field is the
+          // normal first append (the empty prior ledger).
+          let prior: ReviewPostRow[];
+          try {
+            const raw = state.rebuild().review_posts;
+            if (raw === undefined || raw === null) {
+              prior = [];
+            } else {
+              const decoded = strictReviewPosts(raw);
+              if ("malformed" in decoded) {
+                return {
+                  status: "rejected",
+                  problem:
+                    "review_posts ledger is malformed — refusing to append over an unknown " +
+                    `ledger: ${decoded.malformed}`,
+                };
+              }
+              prior = decoded.rows;
+            }
+          } catch (error) {
+            return {
+              status: "rejected",
+              problem:
+                "review_posts ledger rebuild failed — refusing to append over an unknown " +
+                `ledger: ${String(error)}`,
+            };
+          }
+          const posts: ReviewPostRow[] = [...prior, change.row];
+          return state.appendVerified({
+            data: { review_posts: posts },
+            field: "review_posts",
+            expected: posts,
+            scope: "review",
+            failure: "review_posts read-back failed",
+            equals: reviewPostsEqual,
+          });
+        }
+      }
+    },
+  };
+}