@mgiles/perk 3.2.0 → 3.3.0

package/extension/authoring/refinement/draft.ts

@@ -0,0 +1,261 @@
+// The objective-refinement working DRAFT: the one model-facing artifact (`objective_refinement_draft`
+// writes it), bound to the session's context by run id + exact context digest, and the review
+// rendering over the validated (draft, context) pair (contracts.md §8.67).
+//
+// Byte ownership: TypeScript alone serializes drafts — the explicit property order
+// `schema_version`, `run_id`, `context_digest`, `markdown`, compact `JSON.stringify`, one LF.
+// The Markdown is the model's ONLY contribution: it cannot supply a title, path, target, digest,
+// run id or expectation. Python parses the transferred draft without reserializing or trimming.
+//
+// A draft is USABLE only when both strict session pointers verify, the run ids match, the
+// draft's `context_digest` equals the current context artifact's digest, the context fields
+// validate, and the Markdown is nonblank. A context re-prepared after the draft makes the draft
+// `mismatch` (evidence that needs rewriting), never a silent rebind.
+
+import type { SessionArtifactReceipt, WorkflowSession } from "../../session/workflowSession.ts";
+import {
+  checkoutObservationLine,
+  isArtifactDigest,
+  type RefinementContextRead,
+  resumeRefinementContext,
+} from "./context.ts";
+
+/** The fixed working-draft artifact name (one small JSON envelope around the Markdown). */
+export const REFINEMENT_DRAFT_ARTIFACT = "objective-refinement-draft.json";
+
+export interface RefinementDraft {
+  run_id: string;
+  context_digest: string;
+  markdown: string;
+}
+
+/** The validated (draft, context) pair plus the draft's exact bytes — the review + save unit. */
+export interface RefinementDraftPair {
+  draft: RefinementDraft;
+  draftRaw: string;
+  context: RefinementContextRead;
+}
+
+/**
+ * Serialize a draft: the fixed property order, compact `JSON.stringify`, exactly one trailing LF.
+ * Pure; never throws.
+ */
+export function encodeRefinementDraft(draft: {
+  runId: string;
+  contextDigest: string;
+  markdown: string;
+}): string {
+  return `${JSON.stringify({
+    schema_version: 1,
+    run_id: draft.runId,
+    context_digest: draft.contextDigest,
+    markdown: draft.markdown,
+  })}\n`;
+}
+
+export type DecodeRefinementDraftResult =
+  | { ok: true; draft: RefinementDraft }
+  | { ok: false; problem: string };
+
+/**
+ * Strictly decode draft bytes: a JSON object with exactly the four keys, `schema_version` 1, a
+ * nonblank run id, a `sha256:` context digest and nonblank Markdown (tested with trim, NEVER
+ * trimmed). Never throws.
+ */
+export function decodeRefinementDraft(raw: string): DecodeRefinementDraftResult {
+  const refuse = (why: string): { ok: false; problem: string } => ({
+    ok: false,
+    problem: `${REFINEMENT_DRAFT_ARTIFACT} ${why}`,
+  });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return refuse("is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    return refuse("is not a JSON object");
+  const p = parsed as Record<string, unknown>;
+  const keys = Object.keys(p).sort();
+  const expected = ["context_digest", "markdown", "run_id", "schema_version"];
+  if (keys.length !== expected.length || keys.some((k, i) => k !== expected[i]))
+    return refuse("does not carry exactly schema_version, run_id, context_digest, markdown");
+  if (p.schema_version !== 1) return refuse("has an unsupported schema_version");
+  if (typeof p.run_id !== "string" || !p.run_id.trim()) return refuse("has a blank run_id");
+  if (typeof p.context_digest !== "string" || !isArtifactDigest(p.context_digest))
+    return refuse("has a malformed context_digest");
+  if (typeof p.markdown !== "string" || !p.markdown.trim()) return refuse("has blank markdown");
+  return {
+    ok: true,
+    draft: { run_id: p.run_id, context_digest: p.context_digest, markdown: p.markdown },
+  };
+}
+
+// ------------------------------------------------------------------------------- revise
+
+export type ReviseRefinementDraftResult =
+  | {
+      status: "revised";
+      receipt: SessionArtifactReceipt;
+      bytes: number;
+      context: RefinementContextRead;
+    }
+  | {
+      status: "unchanged";
+      receipt: SessionArtifactReceipt;
+      bytes: number;
+      context: RefinementContextRead;
+    }
+  | {
+      status: "rejected";
+      reason: "blank_markdown" | "no_identity" | "no_context" | "context_refused" | "write_refused";
+      problem: string;
+    }
+  | { status: "unverified"; problem: string };
+
+/**
+ * Rewrite the working draft (a whole-value replacement) bound to the CURRENT context: blank
+ * Markdown is refused first, then missing identity, then the strict context resume (absent →
+ * the session needs a grounding pass; refused → a fail-closed stop), then the verified write of
+ * the small fixed envelope. Identical bytes are `unchanged`. Never throws.
+ */
+export function reviseRefinementDraft(
+  input: { markdown: string },
+  session: WorkflowSession,
+): ReviseRefinementDraftResult {
+  if (!input.markdown.trim()) {
+    return {
+      status: "rejected",
+      reason: "blank_markdown",
+      problem: "no refinement markdown to write (pass the full working draft)",
+    };
+  }
+  const identity = session.currentRunIdentity();
+  if (!identity.ok) {
+    return {
+      status: "rejected",
+      reason: "no_identity",
+      problem: `session identity ${identity.reason} — cannot write the refinement draft`,
+    };
+  }
+  const context = resumeRefinementContext(session);
+  if (context.kind === "absent") {
+    return {
+      status: "rejected",
+      reason: "no_context",
+      problem:
+        "no refinement context in this session — enter a grounding pass first (perk objective " +
+        "refine <objective> or /objective-refine)",
+    };
+  }
+  if (context.kind === "refused") {
+    return {
+      status: "rejected",
+      reason: "context_refused",
+      problem: `the refinement context is invalid: ${context.problem}`,
+    };
+  }
+  const content = encodeRefinementDraft({
+    runId: identity.runId,
+    contextDigest: context.read.digest,
+    markdown: input.markdown,
+  });
+  const bytes = Buffer.byteLength(content, "utf8");
+  const written = session.writeArtifact(REFINEMENT_DRAFT_ARTIFACT, content, {
+    provenance: "strict",
+  });
+  switch (written.status) {
+    case "applied":
+      return { status: "revised", receipt: written.receipt, bytes, context: context.read };
+    case "unchanged":
+      return { status: "unchanged", receipt: written.receipt, bytes, context: context.read };
+    case "rejected":
+      return {
+        status: "rejected",
+        reason: "write_refused",
+        problem: `could not write the ${REFINEMENT_DRAFT_ARTIFACT} artifact (${written.problem})`,
+      };
+    case "unverified":
+      return {
+        status: "unverified",
+        problem: `could not write the ${REFINEMENT_DRAFT_ARTIFACT} artifact (${written.problem})`,
+      };
+  }
+}
+
+// ------------------------------------------------------------------------------- resume
+
+/** The classified draft resume. `mismatch` is a usable-looking draft bound to a DIFFERENT
+ * context (re-prepared after it was written) — evidence that must be rewritten, never routed. */
+export type ResumeRefinementDraftResult =
+  | { kind: "valid"; pair: RefinementDraftPair }
+  | { kind: "absent" }
+  | { kind: "no-context" }
+  | { kind: "mismatch"; problem: string }
+  | { kind: "refused"; problem: string };
+
+/**
+ * Resume the (draft, context) pair strictly: identity → strict context → strict draft → the
+ * binding check (matching run id AND exact context digest). Corruption, orphan pointers,
+ * fork/wrong-run data and a context mismatch never fall back to plans or to any other artifact.
+ * Never throws.
+ */
+export function resumeRefinementDraft(session: WorkflowSession): ResumeRefinementDraftResult {
+  const identity = session.currentRunIdentity();
+  if (!identity.ok) return { kind: "refused", problem: `session identity ${identity.reason}` };
+  const context = resumeRefinementContext(session);
+  if (context.kind === "refused") return { kind: "refused", problem: context.problem };
+  const read = session.readArtifact(REFINEMENT_DRAFT_ARTIFACT, { provenance: "strict" });
+  if (read.status === "invalid") return { kind: "refused", problem: read.problem };
+  if (context.kind === "absent")
+    return read.status === "absent" ? { kind: "absent" } : { kind: "no-context" };
+  if (read.status === "absent") return { kind: "absent" };
+  const decoded = decodeRefinementDraft(read.content);
+  if (!decoded.ok) return { kind: "refused", problem: decoded.problem };
+  const draft = decoded.draft;
+  if (draft.run_id !== identity.runId)
+    return { kind: "refused", problem: `${REFINEMENT_DRAFT_ARTIFACT} belongs to another run` };
+  if (draft.context_digest !== context.read.digest)
+    return {
+      kind: "mismatch",
+      problem:
+        "the working draft was written against an earlier refinement context (the context was " +
+        "re-prepared since) — rewrite it with objective_refinement_draft against the current context",
+    };
+  return { kind: "valid", pair: { draft, draftRaw: read.content, context: context.read } };
+}
+
+// ------------------------------------------------------------------------------- render
+
+/**
+ * Render the validated pair as the review surface: identity + carrier + pass time, a prominent
+ * advisory notice, the capture-time observation label (never "verified/frozen/current"), then
+ * the FULL Markdown verbatim. Identity/provenance are immutable review metadata — the
+ * Markdown below the rule is the only reviewable content. Pure; never throws.
+ */
+export function renderRefinementDraft(pair: RefinementDraftPair): string {
+  const c = pair.context.context;
+  const t = c.target;
+  const head = [
+    `# Refinement — objective ${c.objective.id} · node ${t.identity.node_id}`,
+    "",
+    `Objective: ${c.objective.title}`,
+    `Node ${t.identity.node_id} (${t.status}): ${t.source.description}`,
+    `Carrier: ${t.carrier_identifier}${t.carrier_url ? ` — ${t.carrier_url}` : ""}`,
+    `Authoring pass started: ${c.provenance.authored_at} (run ${c.provenance.authoring_run_id})`,
+    c.prior !== null
+      ? `Replaces the prior refinement saved at ${c.prior.saved_at} (full-content replacement).`
+      : "First refinement of this node.",
+    "",
+    "> ADVISORY: this is a dated refinement of a FUTURE node, not an executable plan. Saving it " +
+      "writes only the node's marked refinement comment — no plan is created, no node is claimed, " +
+      "no status changes. Unresolved future assumptions are legitimate here.",
+    ">",
+    `> ${checkoutObservationLine(c.provenance)}`,
+    "",
+    "---",
+    "",
+    "",
+  ];
+  return head.join("\n") + pair.draft.markdown;
+}

package/extension/authoring/refinement/prose.ts

@@ -0,0 +1,79 @@
+// The refinement feature's model-facing prose units: the draft tool's guidelines, the
+// refinement session context content builder, and the injection marker/customType constants.
+// Prose-unit MEANING and ORDER live here (the feature); the v1 adapter only PLACES these units
+// in Pi registration fields and event payloads. Prompting, NOT enforcement — the read-only tool
+// gate (its refinement flavor) is the enforcement.
+
+import { render } from "../../substrate/prompts.ts";
+import { objectiveReadInstruction } from "../objective/prose.ts";
+import type { RefinementContext } from "./context.ts";
+
+/** The refinement context customType (distinct from the plan/objective/gist contexts). */
+export const REFINEMENT_CONTEXT_TYPE = "perk:objective-refinement-context";
+
+/** The injected refinement context's identity marker (the strip + dedup key). */
+export const REFINEMENT_MARKER = "[OBJECTIVE REFINEMENT]";
+
+/**
+ * The refinement session context: live state + pointers only (contracts.md §8.57 — the flow is
+ * stated by the launch statement, the detail by the `perk-objective-refine` skill). It names the
+ * context artifact, the working-draft tool, the review tool, the human failsafe and the bound
+ * skill; it never restates the flow.
+ */
+export const REFINEMENT_CONTEXT = render("contexts/objective-refinement.md", {
+  marker: REFINEMENT_MARKER,
+});
+
+/** Build the full injection, appending the project-config authoring addendum when present. */
+export function refinementContextContent(addendum: string | undefined): string {
+  return addendum ? `${REFINEMENT_CONTEXT}\n\n${addendum.trim()}` : REFINEMENT_CONTEXT;
+}
+
+/** The `objective_refinement_draft` tool guidelines (verbatim prose units; the adapter places them). */
+export const REFINEMENT_DRAFT_TOOL_GUIDELINES = [
+  "Call objective_refinement_draft to persist the current working refinement as you author or revise it; pass the FULL Markdown each time (it rewrites the whole draft).",
+  "objective_refinement_draft binds the draft to the session's grounding context for you — it never saves to the issue backend and never ends the turn; plan_review (approval) or the human's /objective-refinement-save persist it.",
+  "Name unresolved future assumptions and the code seams as observed at capture time; never present the checkout observation as a freshness guarantee.",
+];
+
+/** The re-refinement note (byte-identical to the cold door's `_PRIOR_NOTE`). */
+const PRIOR_NOTE =
+  "A valid prior refinement already exists on this node — the context carries its FULL " +
+  "Markdown; you are re-refining, and a save replaces it whole (full-content replacement).";
+
+/**
+ * The shared cold/warm refinement flow prompt (`stages/objective-refine/seed.md`) rendered for
+ * the warm `/objective-refine` entry from the VALIDATED context: the objective title + node
+ * description ride inside `<untrusted_objective>` as DATA; the only door-derived interpolations
+ * are identifiers, the read clause and the session-data path of the context artifact.
+ */
+export function refinementGuidance(context: RefinementContext, contextPath: string): string {
+  const t = context.target;
+  return render("stages/objective-refine/seed.md", {
+    number: context.objective.id,
+    title: context.objective.title,
+    node_id: t.identity.node_id,
+    node_description: t.source.description,
+    read_clause: objectiveReadInstruction(
+      t.identity.backend,
+      context.objective.id,
+      context.objective.url,
+    ),
+    context_path: contextPath,
+    prior_note: context.prior !== null ? PRIOR_NOTE : "",
+  });
+}
+
+/**
+ * The refusal every plan-graph surface renders when invoked inside a refinement session
+ * (contracts.md §8.67 isolation): the surface names itself; the text names the only two
+ * legitimate exits. Pure.
+ */
+export function refinementStageRefusal(surface: string): string {
+  return (
+    `${surface} is not available in an objective-refine session — a refinement never creates ` +
+    "a plan, claims a node, or changes node/objective state. Author with " +
+    "objective_refinement_draft and review with plan_review; the human saves with " +
+    "/objective-refinement-save."
+  );
+}

package/extension/authoring/refinement/review.ts

@@ -0,0 +1,111 @@
+// The objective-refinement REVIEW feature: the reviewer role over the rendered pair and the
+// one-entry completion routing (contracts.md §8.67 / §8.23's refinement arm).
+//
+// Discipline: the (draft, context) pair is the SOLE review source — never a param, never the
+// transcript. The Pi arm resumes the pair, renders it, reviews, then routes the verdict through
+// `completeRefinementReview`. An approval carrying Direct Edits SKIPS the save and returns one
+// revise round (the heading means no save and no gate exit — Markdown edits are folded via the
+// draft tool and re-reviewed; target/provenance edits need a new grounding pass, never
+// fabricated metadata). A plain approval re-reads the pair through `refinementApprovalSave`,
+// which compares it with the REVIEWED pair when the caller captured one — approval never
+// transfers to a replacement artifact. Denial stays untrusted DATA. Skipped / dismissed /
+// unavailable outcomes save nothing — the caller offers the human `/objective-refinement-save`.
+
+import type { RefinementApprovalSaveOutcome } from "./save.ts";
+
+export type RefinementReviewOutcome =
+  | { status: "approved"; feedback?: string; reviewId?: string }
+  | { status: "approvedDirectEdits"; feedback: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/** The reviewer role: judge the RENDERED surface (never raw artifact JSON). */
+export interface RefinementDraftReviewer {
+  review(rendered: string, signal?: AbortSignal): Promise<RefinementReviewOutcome>;
+}
+
+export type ReviewRefinementResult =
+  | { status: "noDraft" }
+  | { status: "noContext" }
+  | { status: "refusedDraft"; problem: string }
+  | { status: "directEditsRevise"; feedback: string; reviewId?: string }
+  | {
+      status: "approvedSaved";
+      save: Extract<RefinementApprovalSaveOutcome, { status: "saved" }>;
+      feedback?: string;
+      reviewId?: string;
+    }
+  | {
+      status: "approvedSaveFailed";
+      save: Extract<RefinementApprovalSaveOutcome, { status: "save-failed" }>;
+      feedback?: string;
+      reviewId?: string;
+    }
+  | { status: "approvedNoDraft"; feedback?: string; reviewId?: string }
+  | { status: "approvedRefusedDraft"; problem: string; feedback?: string; reviewId?: string }
+  | {
+      /** The approval named a pair the session no longer holds: nothing saved, review again. */
+      status: "approvedSourceChanged";
+      changed: "draft" | "context";
+      feedback?: string;
+      reviewId?: string;
+    }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/** Subject policy only: callers authorize effects before entering this completion seam. */
+export async function completeRefinementReview(
+  outcome: RefinementReviewOutcome,
+  approvalSave: () => Promise<RefinementApprovalSaveOutcome>,
+): Promise<ReviewRefinementResult> {
+  if (outcome.status === "approvedDirectEdits") {
+    return {
+      status: "directEditsRevise",
+      feedback: outcome.feedback,
+      ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+    };
+  }
+  if (outcome.status === "approved") {
+    const carried = {
+      ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+      ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+    };
+    const save = await approvalSave();
+    switch (save.status) {
+      case "saved":
+        return { status: "approvedSaved", save, ...carried };
+      case "save-failed":
+        return { status: "approvedSaveFailed", save, ...carried };
+      case "no-draft":
+        return { status: "approvedNoDraft", ...carried };
+      case "no-context":
+        return {
+          status: "approvedRefusedDraft",
+          problem: "the refinement context vanished between the review and the save",
+          ...carried,
+        };
+      case "refused-draft":
+        return { status: "approvedRefusedDraft", problem: save.problem, ...carried };
+      case "source-changed":
+        return { status: "approvedSourceChanged", changed: save.changed, ...carried };
+    }
+  }
+  switch (outcome.status) {
+    case "denied":
+      return {
+        status: "denied",
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "dismissed":
+      return { status: "dismissed" };
+    case "aborted":
+      return { status: "aborted" };
+    case "unavailable":
+      return { status: "unavailable", warning: outcome.warning };
+  }
+}

package/extension/authoring/refinement/save.ts

@@ -0,0 +1,119 @@
+// The objective-refinement SAVE feature: the narrow exterior `RefinementBackend` port (one
+// production adapter — the `perk objective refinement-save` cold door in pi/v1 — plus
+// deterministic fakes in the tests) and the shared save seam `refinementApprovalSave` both
+// persistence gestures run: the APPROVED `plan_review` refinement arm and the human
+// `/objective-refinement-save` command (contracts.md §8.67).
+//
+// The seam strict-resumes the (draft, context) pair and hands the backend the draft's EXACT
+// bytes (never the rendered markdown, never in-hand bytes) with the explicit run id; the gate
+// exits only after a verified save (D1a). A caller that showed a human a specific pair passes
+// its `reviewed` digests: the resumed pair must equal them byte for byte (draft) and digest for
+// digest (context), or the seam stops with `source-changed` — an approval never transfers to a
+// replacement artifact written during the human wait. There is no linkage, budget, claim or
+// cache effect: a successful save carries the backend's verified facts for the caller to relay,
+// and the caller says advisory content — not an executable plan — was saved.
+
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { type ApprovalGate, saveThroughApprovalGate } from "../review/approvalGate.ts";
+import { type RefinementDraftPair, resumeRefinementDraft } from "./draft.ts";
+
+/** The verified save facts (the worker's success envelope) or a typed failure. */
+export type RefinementBackendSaveResult =
+  | {
+      status: "saved";
+      commentId: string;
+      carrierUrl: string;
+      carrierIdentifier: string;
+      objectiveId: string;
+      objectiveRunId: string;
+      nodeId: string;
+      bodyDigest: string;
+      savedAt: string;
+      authoredAt: string;
+    }
+  | {
+      status: "failed";
+      message: string;
+      errorType: string;
+      /** The worker's diagnostics when it reported them (read back, never blindly retry). */
+      writeAttempted: boolean | null;
+      commentIds: string[];
+    };
+
+/** The narrow exterior port: the exact draft bytes + the run whose context they bind to. */
+export interface RefinementBackend {
+  save(req: { runId: string; draftRaw: string }): Promise<RefinementBackendSaveResult>;
+}
+
+/**
+ * The pair a reviewer actually judged: the draft's exact bytes and the context artifact's digest
+ * (the two inputs the rendering is a pure function of — identical rendering over a re-prepared
+ * context still names a different pair). Callers capture it BEFORE display and hand it to the
+ * seam AFTER the verdict.
+ */
+export interface ReviewedRefinementPair {
+  draftRaw: string;
+  contextDigest: string;
+}
+
+/** The exact digests of a resumed pair, for a later `reviewed` comparison. */
+export function reviewedPairOf(pair: RefinementDraftPair): ReviewedRefinementPair {
+  return { draftRaw: pair.draftRaw, contextDigest: pair.context.digest };
+}
+
+/** The save-seam outcome. The four non-save arms are fail-closed stops: nothing saved, the
+ * gate never touched, with the exact guidance the caller renders. */
+export type RefinementApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "no-context" }
+  | { status: "refused-draft"; problem: string }
+  | {
+      /** The resumed pair is valid but is not the pair the approval was given for. */
+      status: "source-changed";
+      changed: "draft" | "context";
+    }
+  | {
+      status: "saved";
+      save: Extract<RefinementBackendSaveResult, { status: "saved" }>;
+      pair: RefinementDraftPair;
+      gateExited: boolean;
+    }
+  | {
+      status: "save-failed";
+      save: Extract<RefinementBackendSaveResult, { status: "failed" }>;
+      pair: RefinementDraftPair;
+      gateExited: false;
+    };
+
+/**
+ * The shared save seam: strict-resume the pair at save time (a `mismatch` is a refused draft —
+ * it names the rewrite; `no-context` names the grounding pass), compare it with the `reviewed`
+ * pair when one was captured (the context first: a re-prepared context also rebinds any draft
+ * written against it), stage the EXACT draft bytes through the backend with the session's run
+ * id, and exit the gate only on a verified save (`saveThroughApprovalGate`: snapshot before,
+ * exit after success while read-only, a failed save leaves the gate ON). Never throws.
+ */
+export async function refinementApprovalSave(deps: {
+  session: WorkflowSession;
+  backend: RefinementBackend;
+  gate: ApprovalGate;
+  reviewed?: ReviewedRefinementPair;
+}): Promise<RefinementApprovalSaveOutcome> {
+  const resumed = resumeRefinementDraft(deps.session);
+  if (resumed.kind === "absent") return { status: "no-draft" };
+  if (resumed.kind === "no-context") return { status: "no-context" };
+  if (resumed.kind === "refused" || resumed.kind === "mismatch")
+    return { status: "refused-draft", problem: resumed.problem };
+  const pair = resumed.pair;
+  if (deps.reviewed !== undefined) {
+    if (pair.context.digest !== deps.reviewed.contextDigest)
+      return { status: "source-changed", changed: "context" };
+    if (pair.draftRaw !== deps.reviewed.draftRaw)
+      return { status: "source-changed", changed: "draft" };
+  }
+  const { outcome: save, gateExited } = await saveThroughApprovalGate(deps.gate, () =>
+    deps.backend.save({ runId: pair.draft.run_id, draftRaw: pair.draftRaw }),
+  );
+  if (save.status !== "saved") return { status: "save-failed", save, pair, gateExited: false };
+  return { status: "saved", save, pair, gateExited };
+}

package/extension/authoring/review/approvalGate.ts

@@ -0,0 +1,34 @@
+// The shared approval-gate invariant behind the three approval→save orchestrations
+// (`gistApprovalSave`/`planApprovalSave`/`objectiveApprovalSave` — contracts §8.23/§8.41):
+// the gate transition and its structural type unify HERE; draft resolution, save unions, and
+// result field names stay feature-owned. Pi-free and storage-free (the pi/v1 adapters build the
+// gate slice over ToolGating). The no-save siblings — `reviewPlanDraft`'s implement-here arm and
+// `pi/v1/planReview.ts`'s `implementHereExit` — keep their own gate handling on purpose (the
+// sanctioned §8.23 no-save exits, not save flows).
+
+/** The structural gate slice the approval→save flows release (pi/v1 adapters build it over ToolGating). */
+export interface ApprovalGate {
+  isActive(): boolean;
+  exit(): void;
+}
+
+/**
+ * The approval-gate invariant (contracts §8.23/§8.41 — the D1a pattern): snapshot the gate
+ * BEFORE the save; exit ONLY after a successful save while read-only; report gateExited.
+ * Success is the fixed shared discriminant (status === "saved") — not caller policy. A failed
+ * save leaves the gate untouched; a thrown save propagates with the gate untouched.
+ */
+export async function saveThroughApprovalGate<T extends { status: "saved" } | { status: "failed" }>(
+  gate: ApprovalGate,
+  save: () => Promise<T>,
+): Promise<{ outcome: T; gateExited: boolean }> {
+  const wasReadOnly = gate.isActive();
+  const outcome = await save();
+  if (outcome.status !== "saved") return { outcome, gateExited: false };
+  let gateExited = false;
+  if (wasReadOnly) {
+    gate.exit();
+    gateExited = true;
+  }
+  return { outcome, gateExited };
+}

package/extension/authoring/review/draftContext.ts

@@ -0,0 +1,68 @@
+// The door-primed draft-review context + per-activation state for the draft-review doors
+// (/plan-review-browser + /objective-review-browser). THE TRUST POSTURE (the difference from
+// the PR pair): the wave's inputs — the draft under review, its type, and the optional
+// human-supplied custom-angle definition — are REGISTRATION-OWNED STATE primed by the door
+// (the `primeAnnotationSurface` discipline), never tool params: one `DraftReviewWaveState`
+// instance per activation, created in `index.ts` and threaded to the two browser doors and the
+// `pi/v1/draftReviewWaveTools.ts` tool pair. `start_draft_review_wave` takes ONLY `{angles}`
+// and refuses unprimed, so the model can never substitute a transcript/arbitrary draft or
+// invent a custom lane: reviewed bytes == browsed bytes == wave bytes by construction. A prime
+// supersedes everything (context AND pending ref); a clear drops only the primed inputs — a
+// launched wave stays collectable.
+
+import type { ReportWaveRef } from "../../waves/reportWave.ts";
+
+/** The door-primed draft-review inputs (registration-owned state — never tool params). */
+export interface DraftReviewContext {
+  /** The draft kind under review (the wave lane tasks are parameterized on it). */
+  draftType: "plan" | "objective";
+  /** The rendered draft bytes the door surfaced in the browser — the wave reviews exactly these. */
+  draft: string;
+  /** The human-supplied custom-angle definition from the door arg — adds the `custom` lane. */
+  custom?: string;
+}
+
+/**
+ * The draft pair's per-activation state: the ONE opaque ref of the pending (launched,
+ * uncollected) draft-review wave (the `pi/v1/codeReview/reviewWave.ts` pending-slot mirror —
+ * `start_draft_review_wave` refuses while it is set, and `collect_draft_review_wave` drains it;
+ * the wave's settled keys include the `custom` lane when one was primed — the covered
+ * computation needs it) PLUS the door-primed context slot (same defect class, same lifetime —
+ * one browser session's inputs, superseded by the next prime). Which wave is *current* is flow
+ * policy (this slot); every race/grace/drain mechanic below it is wave-owned.
+ */
+export interface DraftReviewWaveState {
+  pending: ReportWaveRef | null;
+  context: DraftReviewContext | null;
+}
+
+/** Create a fresh draft-review state (plain object — no Pi calls; safe anywhere in activation). */
+export function createDraftReviewWaveState(): DraftReviewWaveState {
+  return { pending: null, context: null };
+}
+
+/**
+ * Prime the draft-review context for a new browser session (door-owned; called beside
+ * `primeAnnotationSurface` the moment the browser open picks the port). Resets the pending-wave
+ * slot too — a new browser session supersedes everything (the `primeAnnotationSurface`
+ * discipline).
+ */
+export function primeDraftReviewContext(
+  state: DraftReviewWaveState,
+  next: DraftReviewContext,
+): void {
+  state.context = {
+    draftType: next.draftType,
+    draft: next.draft,
+    ...(next.custom !== undefined ? { custom: next.custom } : {}),
+  };
+  state.pending = null;
+}
+
+/**
+ * Drop the context (door-owned; called when the bridge settles AND on the degrade arm). A
+ * launched wave stays collectable — only the primed inputs die with the browser session.
+ */
+export function clearDraftReviewContext(state: DraftReviewWaveState): void {
+  state.context = null;
+}