@mgiles/perk 3.2.0 → 3.3.0

package/extension/substrate/workflowState.ts

@@ -1,14 +1,15 @@
-// The `perk:workflow-state` session tier (contracts.md §8.3) — rebuild, claim, fork-derive,
-// and the strict-append seam (appendWorkflowState).
+// The `perk:workflow-state` session tier (contracts.md §8.3) — rebuild and the strict-append
+// seam (appendWorkflowState). The identity-lifecycle decisions (claim/fork-derive/stage
+// resolution) live in `session/lifecycle.ts` — the named session operation.
 //
 // Mostly pure, fs-light logic kept separate from the `pi`/`ctx` effects (in index.ts); the
 // strict-append seam touches effects only through structural slices (`EntrySink`, `BranchSource`,
 // `ReportTarget`), so the whole module stays unit-testable under `node --test` with fakes. The
 // reconstruction discipline (scan getBranch on session_start AND session_tree, per-field LWW)
-// and the verified-linkage claim live here.
+// lives here.
 
 import { type ReportTarget, report } from "../surfaces/report.ts";
-import { listRunIds, type PlanRef, readHandoff } from "./cache.ts";
+import { type PlanRef, readPlanRef } from "./cache.ts";
 
 export const WORKFLOW_STATE_TYPE = "perk:workflow-state";
 
@@ -16,6 +17,9 @@ export const WORKFLOW_STATE_TYPE = "perk:workflow-state";
  * A session-artifact provenance pointer (contracts §8.3): the session tier's proof
  * that a `scratch/runs/<run_id>/data/` file is current for THIS run. Reads validate the
  * on-disk file against the rebuilt pointer (run_id match + digest match) and refuse otherwise.
+ * This is the PERSISTENCE format only — rebuilt branch data is unvalidated, so consumption
+ * flows through the session engine's exported decode (`session/workflowSession.ts`), which
+ * narrows exactly the fields it validates.
  */
 export interface SessionArtifactPointer {
   run_id: string;
@@ -65,8 +69,13 @@ export interface WorkflowState {
    * Best-effort tier (per-field LWW in `rebuildWorkflowState`, no rebuild change).
    */
   review_posts?: unknown;
-  /** Session-artifact provenance pointers, keyed by artifact name (§8.3). */
-  session_artifacts?: Record<string, SessionArtifactPointer> | null;
+  /**
+   * Session-artifact provenance pointers, keyed by artifact name (§8.3). The persisted wire
+   * shape is `SessionArtifactPointer`, but rebuilt branch data is UNVALIDATED (`rebuildWorkflowState`
+   * trusts entry data) — so the values are `unknown` and consumption goes through the session
+   * engine's exported persisted-pointer decode (`session/workflowSession.ts`), never a cast.
+   */
+  session_artifacts?: Record<string, unknown> | null;
   /**
    * The objective node this session has claimed `planning` (§8.3) — the warm
    * node-link carrier an approval-triggered save recovers from. Written by the `objective_node`
@@ -120,45 +129,19 @@ export function branchOf(source: BranchSource): BranchEntry[] {
 }
 
 /**
- * Whether any entry on the branch already carries `needle` — the once-only injection dedup guard
- * (the bindingDelivery `branchHasHeader` form). Serializing each entry is the robust,
- * shape-agnostic scan; safe while the needle is a distinctive literal that other entries' data
- * can't casually contain (known accepted false positive: a tool result quoting perk's own source;
- * the typed customType scan is the escalation if that bites — docs/learned/pi/context-injection.md).
+ * Whether any entry on the FULL selected branch already carries `needle` — the historical
+ * once-per-selected-branch guard (the toolGating read-only marker form): history across
+ * compaction, not live model context. Serializing each entry is the robust, shape-agnostic scan;
+ * safe while the needle is a distinctive literal that other entries' data can't casually contain
+ * (known accepted false positive: a tool result quoting perk's own source; the typed customType
+ * scan is the escalation if that bites — docs/learned/pi/context-injection.md). Live-delivery
+ * evidence ("is the copy still in model context?") is a different authority — Pi's own projection
+ * via `pi/v1/contextEvidence.ts` — never reconstructed from branch entries here.
  */
 export function branchCarries(branch: readonly BranchEntry[], needle: string): boolean {
   return branch.some((entry) => JSON.stringify(entry).includes(needle));
 }
 
-/**
- * The branch entries still represented directly in model context. Before compaction that is the
- * full branch. After compaction, Pi keeps entries from `firstKeptEntryId` onward plus anything
- * appended later; historical entries before that cutoff survive only through the summary.
- * Compaction entries are excluded because text quoted by a summary is not a live custom block.
- */
-export function activeContextWindow(branch: readonly BranchEntry[]): BranchEntry[] {
-  let latestCompaction = -1;
-  for (let i = branch.length - 1; i >= 0; i--) {
-    if (branch[i]?.type === "compaction") {
-      latestCompaction = i;
-      break;
-    }
-  }
-  if (latestCompaction === -1) return [...branch];
-
-  const firstKeptEntryId = (branch[latestCompaction] as { firstKeptEntryId?: unknown })
-    .firstKeptEntryId;
-  const firstKept =
-    typeof firstKeptEntryId === "string"
-      ? branch.findIndex(
-          (entry, index) =>
-            index < latestCompaction && (entry as { id?: unknown }).id === firstKeptEntryId,
-        )
-      : -1;
-  const start = firstKept === -1 ? latestCompaction + 1 : firstKept;
-  return branch.slice(start).filter((entry) => entry.type !== "compaction");
-}
-
 /**
  * Per-field last-write-wins over the `perk:workflow-state` custom entries on a branch.
  * Non-perk entries are ignored; `undefined` fields never clobber (but explicit `null` does).
@@ -188,156 +171,188 @@ export interface EntrySink {
 export function appendWorkflowState<K extends keyof WorkflowState>(
   sink: EntrySink,
   source: BranchSource & ReportTarget,
-  opts: {
-    /** The entry payload — may carry extra fields beyond the verified one (the claim record). */
-    data: WorkflowState;
-    /** The field verified on read-back. */
-    field: K;
-    /** The value the rebuilt field must equal. */
-    expected: WorkflowState[K];
-    /** report() scope, e.g. "plan-save", "workflow-state linkage error". */
-    scope: string;
-    /** The mismatch message (byte-preserved per site). */
-    failure: string;
-    /** Comparator; default: (a, b) => Object.is(a ?? null, b ?? null). */
-    equals?: (rebuilt: WorkflowState[K] | undefined, expected: WorkflowState[K]) => boolean;
-  },
+  opts: AppendWorkflowStateOpts<K>,
 ): boolean {
+  return appendWorkflowStateClassified(sink, source, opts).status === "applied";
+}
+
+/** The strict-append options (shared by the boolean and classified entry points). */
+export interface AppendWorkflowStateOpts<K extends keyof WorkflowState> {
+  /** The entry payload — may carry extra fields beyond the verified one (the claim record). */
+  data: WorkflowState;
+  /** The field verified on read-back. */
+  field: K;
+  /** The value the rebuilt field must equal. */
+  expected: WorkflowState[K];
+  /** report() scope, e.g. "plan-save", "workflow-state linkage error". */
+  scope: string;
+  /** The mismatch message (byte-preserved per site). */
+  failure: string;
+  /** Comparator; default: (a, b) => Object.is(a ?? null, b ?? null). */
+  equals?: (rebuilt: WorkflowState[K] | undefined, expected: WorkflowState[K]) => boolean;
+}
+
+/**
+ * The classified strict-append outcome. `rejected` is PROVEN refusal-before-effect: the append
+ * threw AND the rebuilt field is still not the expected value, so no entry landed. `unverified`
+ * means an effect may have landed unproven — the append returned but the read-back missed, or
+ * the post-throw rebuild itself failed.
+ */
+export type ClassifiedAppend =
+  | { status: "applied" }
+  | { status: "rejected"; problem: string }
+  | { status: "unverified"; problem: string };
+
+/**
+ * The classified sibling of `appendWorkflowState` (same report discipline — every failure arm
+ * reports loudly before returning). The extra classification work happens only on failure
+ * paths: a throwing `appendEntry` is re-checked against the rebuilt branch — a field still not
+ * equal to `expected` proves the entry never landed (`rejected`, the refusal-before-effect arm
+ * the session seam surfaces); a field that DOES equal `expected` landed despite the throw (the
+ * read-back is the proof authority — `applied`); a rebuild failure stays honest (`unverified`).
+ */
+export function appendWorkflowStateClassified<K extends keyof WorkflowState>(
+  sink: EntrySink,
+  source: BranchSource & ReportTarget,
+  opts: AppendWorkflowStateOpts<K>,
+): ClassifiedAppend {
   const equals =
     opts.equals ??
     ((a: WorkflowState[K] | undefined, b: WorkflowState[K]) => Object.is(a ?? null, b ?? null));
   try {
     sink.appendEntry(WORKFLOW_STATE_TYPE, opts.data);
     const rebuilt = rebuildWorkflowState(branchOf(source))[opts.field];
-    if (equals(rebuilt, opts.expected)) return true;
+    if (equals(rebuilt, opts.expected)) return { status: "applied" };
     report(source, opts.scope, "error", opts.failure, { alsoLog: true });
-    return false;
+    return { status: "unverified", problem: opts.failure };
   } catch (error) {
-    report(source, opts.scope, "error", `${String(opts.field)} append threw — ${String(error)}`, {
-      alsoLog: true,
-    });
-    return false;
+    const problem = `${String(opts.field)} append threw — ${String(error)}`;
+    report(source, opts.scope, "error", problem, { alsoLog: true });
+    try {
+      const rebuilt = rebuildWorkflowState(branchOf(source))[opts.field];
+      if (equals(rebuilt, opts.expected)) return { status: "applied" };
+      return { status: "rejected", problem };
+    } catch {
+      return { status: "unverified", problem };
+    }
   }
 }
 
 /**
- * Equality by identity (provider + pr_id) — the plan-ref dedup key. Two refs to
- * the same plan are equal even if other fields drift; absent compares equal only to absent.
+ * The rebuilt `conflict_resolution_attempts` counter, read WITHOUT a catch: a throwing
+ * `getBranch()` propagates — unreadable bounding state is never treated as proven zero (the
+ * load-bearing failure path both conflict drives rely on). A READABLE but malformed persisted
+ * value (non-integer, negative, string, object, null, absent) narrows to 0.
  */
-export function planRefsEqual(
-  a: PlanRef | null | undefined,
-  b: PlanRef | null | undefined,
-): boolean {
-  if (a === null || a === undefined || b === null || b === undefined) {
-    return (a === null || a === undefined) && (b === null || b === undefined);
-  }
-  return a.provider === b.provider && a.pr_id === b.pr_id;
+export function conflictResolutionAttempts(source: BranchSource): number {
+  const value = rebuildWorkflowState(branchOf(source)).conflict_resolution_attempts;
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) return value;
+  return 0;
 }
 
 /**
- * Derive a fork-child run_id: `<parent>.<n>` where `n` is the max existing sibling + 1
- * (scanning `scratch/runs/`), else 1.
+ * The checked `conflict_resolution_attempts` write: a non-integer/negative value is refused
+ * loudly (`false`, no append — the reader narrows such values to 0, so persisting one would
+ * silently reopen the budget); equal-value short-circuit (no append) → `true`; otherwise the
+ * strict-read-back boolean from `appendWorkflowState` (its loud report path is the loudness
+ * channel). The counter is shared across the two warm conflict drives, so
+ * `scope` names the TRUE writing surface for failure reports — `/submit` passes "submit", the
+ * stack door "objective-sync".
  */
-export function deriveForkRunId(parentRunId: string, cwd: string): string {
-  const prefix = `${parentRunId}.`;
-  let max = 0;
-  for (const id of listRunIds(cwd)) {
-    if (!id.startsWith(prefix)) continue;
-    const segment = id.slice(prefix.length).split(".")[0] ?? "";
-    const n = Number.parseInt(segment, 10);
-    if (Number.isInteger(n) && n > max) max = n;
+export function setConflictAttempts(
+  sink: EntrySink,
+  source: BranchSource & ReportTarget,
+  opts: { attempts: number; scope: string },
+): boolean {
+  // The write seam enforces the same invariant the reader narrows by: persisting a value the
+  // reader would coerce to 0 would silently reopen the conflict budget on the next read, so an
+  // invalid write is refused loudly instead of persisted (invalid counter states are
+  // unrepresentable through this seam).
+  if (!Number.isInteger(opts.attempts) || opts.attempts < 0) {
+    report(
+      source,
+      opts.scope,
+      "warning",
+      `refused an invalid conflict_resolution_attempts write (${opts.attempts}) — the counter is a non-negative integer`,
+      { alsoLog: true },
+    );
+    return false;
   }
-  return `${parentRunId}.${max + 1}`;
+  if (conflictResolutionAttempts(source) === opts.attempts) return true;
+  return appendWorkflowState(sink, source, {
+    data: { conflict_resolution_attempts: opts.attempts },
+    field: "conflict_resolution_attempts",
+    expected: opts.attempts,
+    scope: opts.scope,
+    failure:
+      opts.attempts === 0
+        ? "conflict_resolution_attempts reset read-back failed (expected 0)"
+        : `conflict_resolution_attempts read-back failed (expected ${opts.attempts})`,
+  });
 }
 
-export type ClaimDecision =
-  | { action: "keep"; source: "session"; state: WorkflowState }
-  | {
-      action: "fork";
-      source: "fork";
-      childRunId: string;
-      parentRunId: string;
-      state: WorkflowState;
-    }
-  | { action: "claim"; source: "env"; runId: string }
-  | {
-      action: "adopt";
-      source: "env-child";
-      childRunId: string;
-      parentRunId: string;
-      /** Inherited from the parent's handoff so read-only gating survives into the child. */
-      mode?: string;
-    }
-  | { action: "none"; source: "none"; state: WorkflowState };
+/** Structural claim equality (objective + node match); absent compares equal only to absent. */
+export function nodeClaimsEqual(
+  a: WorkflowState["objective_node_claim"] | undefined,
+  b: WorkflowState["objective_node_claim"] | undefined,
+): boolean {
+  const an = a ?? null;
+  const bn = b ?? null;
+  if (an === null || bn === null) return an === bn;
+  return an.objective === bn.objective && an.node === bn.node;
+}
 
 /**
- * Decide what `session_start` should do, from the rebuilt state + the current session handle
- * + the launch env. Reload vs fork is distinguished by the `run_id ↔ pi_session_id` mapping
- * (NOT `event.reason`, which is "startup" for a headless `pi --fork`): if the branch already
- * carries a `run_id` whose recorded `pi_session_id` differs from the current session, the id
- * was inherited across a fork → derive a child; if it matches (or is absent), it's a reload.
- * An env-inherited run id whose handoff was already CONSUMED by a different session is a
- * spawned child, not the launched session → `adopt` (derive a sibling id, inherit `mode`).
+ * Resolve the active plan-ref: the worktree's `cache.plan-ref` file first, then the rebuilt
+ * workflow-state's `active_plan_ref` (the branch-carried linkage). The worktree read is itself
+ * null-lenient and runs OUTSIDE the catch (a throw from it propagates); only the branch
+ * rebuild is fail-open → null. Structural + Pi-free: `ExtensionContext` satisfies the slice.
  */
+export function activePlanRef(source: { cwd: string } & BranchSource): PlanRef | null {
+  const fromWorktree = readPlanRef(source.cwd);
+  if (fromWorktree) return fromWorktree;
+  try {
+    const branch = branchOf(source);
+    return (rebuildWorkflowState(branch).active_plan_ref as PlanRef | null) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
- * The registry stage id the launched run is acting on, read from its handoff blob, or null.
- * Only `claim` (cold) and `keep` (reload) sessions have a settled run whose handoff records a
- * `stage`; `fork`, `adopt`, and `none` carry no launched stage (an adopted env-child must never
- * impersonate the launched stage; LWW restores fork/none state instead). The stage gates whether
- * `session_start` reconciles `cache.plan-ref` into `active_plan_ref`.
+ * The three-tier stack-objective resolution shared by every stack tool + command: an explicit
+ * id wins; else the branch-rebuilt `active_objective`; else the worktree plan-ref's
+ * `objective_id`. Each fallible tier fails open to the next; null when nothing resolves.
+ * Structural + Pi-free: `ExtensionContext` satisfies the slice.
  */
-export function resolveRunStage(decision: ClaimDecision, cwd: string): string | null {
-  const runId =
-    decision.action === "claim"
-      ? decision.runId
-      : decision.action === "keep"
-        ? decision.state.run_id
-        : null;
-  if (runId === undefined || runId === null) return null;
-  const stage = readHandoff(cwd, runId)?.stage;
-  return typeof stage === "string" && stage !== "" ? stage : null;
+export function resolveStackObjective(
+  explicit: string | undefined,
+  source: { cwd: string } & BranchSource,
+): string | null {
+  if (explicit !== undefined && explicit.length > 0) return explicit;
+  try {
+    const active = rebuildWorkflowState(branchOf(source)).active_objective;
+    if (active !== undefined && active !== null) return active;
+  } catch {
+    // fall through to the plan-ref tier
+  }
+  try {
+    return readPlanRef(source.cwd)?.objective_id ?? null;
+  } catch {
+    return null;
+  }
 }
 
-export function decideClaim(args: {
-  state: WorkflowState;
-  currentSessionId: string | null;
-  envRunId: string | null;
-  cwd: string;
-}): ClaimDecision {
-  const { state, currentSessionId, envRunId, cwd } = args;
-  if (state.run_id !== undefined) {
-    if (state.pi_session_id === undefined || state.pi_session_id === currentSessionId) {
-      return { action: "keep", source: "session", state };
-    }
-    const childRunId = deriveForkRunId(state.run_id, cwd);
-    return { action: "fork", source: "fork", childRunId, parentRunId: state.run_id, state };
-  }
-  if (envRunId !== null && envRunId !== "") {
-    // Env-child detection (contracts §8.2): subagent children are spawned as separate `pi`
-    // processes with the parent's env, so they arrive here carrying the parent's PERK_RUN_ID.
-    // A handoff already consumed by a DIFFERENT (or unrecorded) session belongs to someone else:
-    // adopt a derived `<run_id>.<n>` child identity instead of re-claiming — never re-consume the
-    // handoff, never capture pointers, never impersonate the launched stage. The parent's `mode`
-    // is inherited so read-only gating survives into exploration children. Everything else —
-    // absent/corrupt/mismatched handoff (the loud unclaimed error), unconsumed (the normal cold
-    // claim), or consumed by THIS session (idempotent re-claim after lost branch state) — stays
-    // the claim arm.
-    const handoff = readHandoff(cwd, envRunId);
-    if (
-      handoff !== null &&
-      handoff.run_id === envRunId &&
-      handoff.consumed === true &&
-      handoff.pi_session_id !== currentSessionId
-    ) {
-      return {
-        action: "adopt",
-        source: "env-child",
-        childRunId: deriveForkRunId(envRunId, cwd),
-        parentRunId: envRunId,
-        mode: handoff.mode,
-      };
-    }
-    return { action: "claim", source: "env", runId: envRunId };
+/**
+ * Equality by identity (provider + pr_id) — the plan-ref dedup key. Two refs to
+ * the same plan are equal even if other fields drift; absent compares equal only to absent.
+ */
+export function planRefsEqual(
+  a: PlanRef | null | undefined,
+  b: PlanRef | null | undefined,
+): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) {
+    return (a === null || a === undefined) && (b === null || b === undefined);
   }
-  return { action: "none", source: "none", state };
+  return a.provider === b.provider && a.pr_id === b.pr_id;
 }