@mgiles/perk 1.0.1

package/extension/substrate/miniYaml.ts

@@ -0,0 +1,262 @@
+// A deliberately minimal YAML-subset reader for perk's OWN bundled contract files only
+// (`shared/{registry,bindings,providers}.yaml`) — this is NOT a general-purpose YAML parser.
+//
+// Why this exists: pi loads the perk extension from a git-package clone whose imports resolve
+// through a FIXED host-alias set (`@earendil-works/pi-*`, `typebox`) plus native `node_modules`
+// walking. The extension must therefore be SELF-CONTAINED — zero runtime npm deps: a bare
+// `import { parse } from "yaml"` would only resolve if pi's `npm install --omit=dev` happened to
+// install it, which is fragile (and perk pre-materializes the clone with a plain `git
+// clone` and NO `npm install` at all, so the clone has no `node_modules` to resolve against). This
+// reader replaces the lone non-host runtime import (`yaml`) with Node builtins only — NO bare npm
+// imports — so the extension loads from a bare git checkout regardless of whether any install ran.
+//
+// Scope (the bounded feature surface across the three shipped files):
+//   - block mappings (indentation-nested) and block sequences (`- item`, incl. `- id: x`
+//     map-as-sequence-item),
+//   - flow mappings `{ k: v, ... }` and flow sequences `[a, b]` / `[]`,
+//   - scalars: integers, `true`/`false`, `null`, bare strings, and double-quoted strings (whose
+//     contents may contain `:` / `@` / `/`, and where a `#` is NOT a comment),
+//   - trailing `#` comments (outside double quotes), whole-line `#` comments, and blank lines.
+//
+// Explicitly UNSUPPORTED (and made to throw loudly rather than silently mis-parse): YAML
+// anchors/aliases (`&`/`*`), block/multiline scalars (`|`/`>`), single-quoted strings, `~` null,
+// floats, and multi-document `---`/`...` streams. An unsupported future edit fails CI loudly.
+//
+// Fidelity to the reference `yaml` library is pinned by `miniYaml.test.ts`, which deep-equals this
+// reader's output against `yaml.parse` for all three bundled files (the `yaml` lib is a dev-only
+// dependency that powers that test and never ships in the consumer git clone). This reader is the
+// twin of the Python plane's `pyyaml`-based readers in `perk/substrate/{registry,bindings,providers}.py`.
+
+interface Line {
+  indent: number;
+  text: string;
+}
+
+interface Cursor {
+  i: number;
+}
+
+/** Strip a trailing `#` comment, honoring double-quoted strings (a `#` inside a quote is literal). */
+function stripComment(line: string): string {
+  let inQuote = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"' && (i === 0 || line[i - 1] !== "\\")) {
+      inQuote = !inQuote;
+    } else if (c === "#" && !inQuote && (i === 0 || /\s/.test(line[i - 1] ?? ""))) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+/** Split raw text into comment-stripped, blank-free logical lines with their indentation depth. */
+function preprocess(text: string): Line[] {
+  const out: Line[] = [];
+  for (const raw of text.split("\n")) {
+    const stripped = stripComment(raw);
+    if (stripped.trim() === "") continue;
+    const indent = stripped.length - stripped.trimStart().length;
+    const body = stripped.slice(indent).trimEnd();
+    if (body === "---" || body === "...") {
+      throw new Error("perk miniYaml: multi-document streams (`---`/`...`) are not supported");
+    }
+    out.push({ indent, text: body });
+  }
+  return out;
+}
+
+/**
+ * Index of the first `:` that delimits a key from a value: not inside double quotes, not inside a
+ * flow collection, and followed by whitespace or end-of-string. Returns -1 if there is none.
+ */
+function findColon(s: string): number {
+  let inQuote = false;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === '"' && (i === 0 || s[i - 1] !== "\\")) {
+      inQuote = !inQuote;
+    } else if (!inQuote && (c === "{" || c === "[")) {
+      depth++;
+    } else if (!inQuote && (c === "}" || c === "]")) {
+      depth--;
+    } else if (c === ":" && !inQuote && depth === 0) {
+      const next = s[i + 1];
+      if (next === undefined || /\s/.test(next)) return i;
+    }
+  }
+  return -1;
+}
+
+/** Split `key: value` at the delimiting colon into trimmed `[key, value]`. */
+function splitKeyValue(text: string): [string, string] {
+  const idx = findColon(text);
+  if (idx === -1) return [text.trim(), ""];
+  return [text.slice(0, idx).trim(), text.slice(idx + 1).trim()];
+}
+
+/** Split a flow body on top-level commas (honoring quotes and nested flow collections). */
+function splitTopLevel(s: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let inQuote = false;
+  let cur = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === '"' && (i === 0 || s[i - 1] !== "\\")) {
+      inQuote = !inQuote;
+      cur += c;
+    } else if (!inQuote && (c === "{" || c === "[")) {
+      depth++;
+      cur += c;
+    } else if (!inQuote && (c === "}" || c === "]")) {
+      depth--;
+      cur += c;
+    } else if (c === "," && !inQuote && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += c;
+    }
+  }
+  if (cur.trim() !== "") parts.push(cur);
+  return parts;
+}
+
+/** Unescape the minimal set of double-quoted escapes that the reference parser would process. */
+function unescapeDoubleQuoted(inner: string): string {
+  return inner.replace(/\\(["\\nt])/g, (_m, ch) => {
+    if (ch === "n") return "\n";
+    if (ch === "t") return "\t";
+    return ch; // `\"` -> `"`, `\\` -> `\`
+  });
+}
+
+/** Type a leaf scalar token to match `yaml.parse`. Throws on an unsupported construct. */
+function parseScalar(token: string): unknown {
+  const t = token.trim();
+  if (t === "") return null;
+  if (t.startsWith('"')) {
+    if (!t.endsWith('"') || t.length < 2) {
+      throw new Error(`perk miniYaml: malformed double-quoted scalar: ${token}`);
+    }
+    return unescapeDoubleQuoted(t.slice(1, -1));
+  }
+  if (t.startsWith("'")) {
+    throw new Error("perk miniYaml: single-quoted strings are not supported");
+  }
+  if (t.startsWith("&") || t.startsWith("*")) {
+    throw new Error("perk miniYaml: anchors/aliases (`&`/`*`) are not supported");
+  }
+  if (t === "~" || /^[|>][+-]?\d*$/.test(t)) {
+    throw new Error(`perk miniYaml: unsupported scalar/block construct: ${token}`);
+  }
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t === "null") return null;
+  if (/^-?\d+$/.test(t)) return Number(t);
+  return t;
+}
+
+/** Parse a value that may be a flow collection or a leaf scalar. */
+function parseFlowOrScalar(token: string): unknown {
+  const t = token.trim();
+  if (t.startsWith("{")) return parseFlowMapping(t);
+  if (t.startsWith("[")) return parseFlowSequence(t);
+  return parseScalar(t);
+}
+
+function parseFlowMapping(s: string): Record<string, unknown> {
+  if (!s.endsWith("}")) throw new Error(`perk miniYaml: unterminated flow mapping: ${s}`);
+  const map: Record<string, unknown> = {};
+  for (const part of splitTopLevel(s.slice(1, -1))) {
+    const [key, value] = splitKeyValue(part.trim());
+    if (key === "") continue;
+    map[key] = parseFlowOrScalar(value);
+  }
+  return map;
+}
+
+function parseFlowSequence(s: string): unknown[] {
+  if (!s.endsWith("]")) throw new Error(`perk miniYaml: unterminated flow sequence: ${s}`);
+  return splitTopLevel(s.slice(1, -1)).map((part) => parseFlowOrScalar(part.trim()));
+}
+
+function isDash(text: string): boolean {
+  return text === "-" || text.startsWith("- ");
+}
+
+/** Parse a block node (mapping or sequence) whose content lives at column `indent`. */
+function parseNode(lines: Line[], cursor: Cursor, indent: number): unknown {
+  const first = lines[cursor.i];
+  if (first === undefined) return null;
+  if (isDash(first.text)) return parseSequence(lines, cursor, indent);
+  return parseMapping(lines, cursor, indent);
+}
+
+function parseMapping(lines: Line[], cursor: Cursor, indent: number): Record<string, unknown> {
+  const map: Record<string, unknown> = {};
+  while (cursor.i < lines.length) {
+    const line = lines[cursor.i];
+    if (line === undefined || line.indent !== indent) break;
+    const [key, rest] = splitKeyValue(line.text);
+    cursor.i++;
+    if (rest === "") {
+      const next = lines[cursor.i];
+      if (next !== undefined && next.indent > indent) {
+        map[key] = parseNode(lines, cursor, next.indent);
+      } else {
+        map[key] = null;
+      }
+    } else {
+      map[key] = parseFlowOrScalar(rest);
+    }
+  }
+  return map;
+}
+
+function parseSequence(lines: Line[], cursor: Cursor, indent: number): unknown[] {
+  const arr: unknown[] = [];
+  while (cursor.i < lines.length) {
+    const line = lines[cursor.i];
+    if (line === undefined || line.indent !== indent || !isDash(line.text)) break;
+    const after = line.text === "-" ? "" : line.text.slice(2);
+    if (after === "") {
+      cursor.i++;
+      const next = lines[cursor.i];
+      if (next !== undefined && next.indent > indent) {
+        arr.push(parseNode(lines, cursor, next.indent));
+      } else {
+        arr.push(null);
+      }
+    } else if (findColon(after) !== -1) {
+      // A mapping as a sequence item (`- id: x` + deeper-indented continuation keys). Rewrite the
+      // dash line into a plain mapping line at the content column, then parse the whole mapping.
+      const contentIndent = indent + 2;
+      lines[cursor.i] = { indent: contentIndent, text: after };
+      arr.push(parseMapping(lines, cursor, contentIndent));
+    } else {
+      cursor.i++;
+      arr.push(parseFlowOrScalar(after));
+    }
+  }
+  return arr;
+}
+
+/**
+ * Parse a YAML-subset document into a `yaml.parse`-equivalent JS value graph. Same call shape as
+ * `yaml`'s `parse`. Throws a clear `Error` on any construct outside the supported surface.
+ */
+export function parse(text: string): unknown {
+  const lines = preprocess(text);
+  if (lines.length === 0) return null;
+  const cursor: Cursor = { i: 0 };
+  const result = parseNode(lines, cursor, lines[0]?.indent ?? 0);
+  if (cursor.i !== lines.length) {
+    throw new Error(
+      `perk miniYaml: unexpected content at line ${cursor.i + 1} (indentation not understood)`,
+    );
+  }
+  return result;
+}

package/extension/substrate/prompts.ts

@@ -0,0 +1,35 @@
+// The TS plane's prompt render seam — the twin of perk/prompts.py::render.
+//
+// Templates are loaded by explicit `name` (root-relative under `prompts/`) via promptsDir(),
+// the same directory the Python twin reads. The feature surface is intentionally small —
+// `{{ var }}` substitution and `{% include %}` — and `throwOnUndefined` makes a missing
+// variable fail loudly rather than render an empty string.
+//
+// jinja2 is the REFERENCE engine: the committed golden bytes under prompts/_fixtures/golden/
+// ARE jinja2's output, and this nunjucks twin must reproduce them byte-for-byte. Golden parity
+// is enforced by prompts.test.ts + tests/test_prompts.py. The Environment config below is the
+// parity baseline both engines share (autoescape off, trimBlocks on so a block tag on its own
+// line emits no spurious newline — letting conditional templates keep their tags off the content
+// lines while preserving indentation — lstripBlocks off; nunjucks keeps the trailing newline,
+// matching jinja2's keep_trailing_newline=True).
+//
+// This module is imported ONLY by its test in this node — there is no real prompt to render
+// until Phase 2, so wiring it into extension/index.ts would be dead code. The runtime nunjucks
+// dependency is removed and the zero-dep / bare-clone-loadable invariant restored when the
+// renderer is vendored (node 4.2).
+
+import nunjucks from "nunjucks";
+
+import { promptsDir } from "./resources.ts";
+
+const env = new nunjucks.Environment(new nunjucks.FileSystemLoader(promptsDir()), {
+  throwOnUndefined: true,
+  autoescape: false,
+  trimBlocks: true,
+  lstripBlocks: false,
+});
+
+/** Render the template at `name` (root-relative under `prompts/`) with `vars`. */
+export function render(name: string, vars: Record<string, unknown>): string {
+  return env.render(name, vars);
+}

package/extension/substrate/providers.ts

@@ -0,0 +1,177 @@
+// The TS plane's reader for the shared provider-selection supported set (`shared/providers.yaml`).
+//
+// Twin of perk/substrate/providers.py: both planes parse the SAME bundled file (no codegen). This is the
+// THIRD parsed cross-plane contract (after registry.yaml and bindings.yaml). It is the SUPPORTED
+// SET — the catalog of plan/todo/askuser/footer/web providers perk knows how to wire — distinct from
+// the per-repo SELECTION (the flat `[providers]` table in .pi/perk.toml).
+//
+// The Python CLI is the authoritative validator (perk/substrate/providers.py); this side does a thin
+// structural parse only — no deep content validation here. `resolveProviders` is CONSUMED by
+// `planMode` (plan-seam registration-time vacating when a foreign plan provider is selected); the
+// todo-seam runtime deferral is likewise live.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "./miniYaml.ts";
+import { sharedDir } from "./resources.ts";
+
+export interface Provider {
+  id: string;
+  seam: string;
+  package: string | null;
+  adapter: string | null;
+  default: boolean;
+  packageFilter?: Record<string, unknown>;
+}
+
+export const PROVIDER_SEAMS = ["plan", "todo", "askuser", "footer", "web"] as const;
+
+/** The bundled reference provider ids (the behavior-preserving no-config defaults per seam). */
+export const PERK_PLAN_PROVIDER_ID = "perk-plan";
+export const PERK_CHECKPOINTS_PROVIDER_ID = "perk-checkpoints";
+export const PERK_ASK_USER_PROVIDER_ID = "perk-ask-user";
+export const PERK_FOOTER_PROVIDER_ID = "perk-footer";
+
+/** The foreign `@tombell/pi-plan` plan-provider id. */
+export const TOMBELL_PLAN_PROVIDER_ID = "tombell-plan";
+
+/** The foreign `@plannotator/pi-extension` plan-provider id (augment-posture adapter selection check). */
+export const PLANNOTATOR_PLAN_PROVIDER_ID = "plannotator-plan";
+
+/** The foreign `@juicesharp/rpiv-todo` todo-provider id. */
+export const JUICESHARP_TODO_PROVIDER_ID = "juicesharp-todo";
+
+/** The foreign `@juicesharp/rpiv-ask-user-question` askuser-provider id (vacate-only interface seam). */
+export const JUICESHARP_ASK_USER_PROVIDER_ID = "juicesharp-ask-user";
+
+/** The foreign `pi-powerline-footer` footer-provider id (vacate-only interface seam). */
+export const POWERLINE_FOOTER_PROVIDER_ID = "powerline-footer";
+
+/** The foreign `pi-bar` footer-provider id (vacate-only interface seam). */
+export const PI_BAR_FOOTER_PROVIDER_ID = "pi-bar-footer";
+
+/** The foreign `@tombell/pi-status` footer-provider id (vacate-only; no extension-status rendering). */
+export const PI_STATUS_FOOTER_PROVIDER_ID = "pi-status-footer";
+
+/** The "install nothing / pi stock footer" footer-provider id (`package: null`, vacate-only). */
+export const PI_DEFAULT_FOOTER_PROVIDER_ID = "pi-default";
+
+/** The web seam DEFAULT id — the FOREIGN reference provider (`pi-web-access`; perk owns no native web impl). */
+export const PI_WEB_ACCESS_PROVIDER_ID = "pi-web-access";
+
+/** The foreign `@ollama/pi-web-search` web-provider id (vacate-only interface seam). */
+export const OLLAMA_WEB_PROVIDER_ID = "ollama-web-search";
+
+/** The foreign `@juicesharp/rpiv-web-tools` web-provider id (vacate-only interface seam). */
+export const JUICESHARP_WEB_PROVIDER_ID = "juicesharp-web-tools";
+
+/** Parse the bundled `providers.yaml`. Throws on a missing file or unexpected shape. */
+export function loadProviders(): Provider[] {
+  const path = join(sharedDir(), "providers.yaml");
+  const data = parse(readFileSync(path, "utf8")) as unknown;
+
+  if (typeof data !== "object" || data === null) {
+    throw new Error(`perk: ${path} is not a mapping`);
+  }
+  const record = data as Record<string, unknown>;
+  const providers = record.providers;
+  if (!Array.isArray(providers)) {
+    throw new Error(`perk: ${path} has no providers`);
+  }
+
+  return providers.map((raw) => {
+    const entry = raw as Record<string, unknown>;
+    const packageFilter = entry.package_filter;
+    const provider: Provider = {
+      id: typeof entry.id === "string" ? entry.id : "",
+      seam: typeof entry.seam === "string" ? entry.seam : "",
+      package: typeof entry.package === "string" ? entry.package : null,
+      adapter: typeof entry.adapter === "string" ? entry.adapter : null,
+      default: entry.default === true,
+    };
+    if (typeof packageFilter === "object" && packageFilter !== null) {
+      provider.packageFilter = packageFilter as Record<string, unknown>;
+    }
+    return provider;
+  });
+}
+
+// ------------------------------------------------------------------------ resolve
+
+/**
+ * The effective provider per seam after resolving a repo selection against the supported set.
+ * `issues` collects every loud-but-non-fatal finding (an unknown id or a wrong-seam provider) as a
+ * plain string — the TS plane has no `Issue`/`Severity` (those live in `perk/substrate/registry.py`); the
+ * Python plane is the authoritative validator. Twin of `perk.substrate.providers.ResolvedProviders`.
+ */
+export interface ResolvedProviders {
+  plan: Provider;
+  todo: Provider;
+  askuser: Provider;
+  footer: Provider;
+  web: Provider;
+  issues: string[];
+}
+
+/** The first `default: true` provider for `seam` (the validator enforces exactly one). */
+function defaultFor(set: Provider[], seam: string): Provider | undefined {
+  return set.find((p) => p.seam === seam && p.default);
+}
+
+/** Map `id -> Provider` (last wins on a duplicate id; the Python validator flags duplicates). */
+function byId(set: Provider[]): Map<string, Provider> {
+  const map = new Map<string, Provider>();
+  for (const p of set) if (p.id) map.set(p.id, p);
+  return map;
+}
+
+/**
+ * Resolve a per-seam selection against the supported set (pure mirror of `resolve_providers`).
+ *
+ * For each seam, the selection resolves to the named provider **iff** the id exists AND its `seam`
+ * matches the key; otherwise it falls back to `defaultFor(seam)` and appends a loud-but-non-fatal
+ * issue (unknown id / seam mismatch). An **absent** key falls back to the default **silently** (the
+ * zero-config default — no issue). Defaults are trusted (not re-validated). Throws if the bundled
+ * set has no default for a seam (a corrupt install — the caller's try/catch fails safe). Omitting
+ * `set` loads the bundled `providers.yaml`.
+ */
+export function resolveProviders(
+  selection: { plan?: string; todo?: string; askuser?: string; footer?: string; web?: string },
+  set?: Provider[],
+): ResolvedProviders {
+  const providers = set ?? loadProviders();
+  const ids = byId(providers);
+  const issues: string[] = [];
+
+  const requireDefault = (seam: string): Provider => {
+    const def = defaultFor(providers, seam);
+    if (def === undefined) {
+      throw new Error(`perk: no default provider for seam \`${seam}\` — reinstall perk`);
+    }
+    return def;
+  };
+
+  const resolveSeam = (seam: "plan" | "todo" | "askuser" | "footer" | "web"): Provider => {
+    const selected = selection[seam];
+    if (selected == null) return requireDefault(seam);
+    const provider = ids.get(selected);
+    if (provider === undefined) {
+      issues.push(`\`${seam}\` selects unknown provider \`${selected}\``);
+      return requireDefault(seam);
+    }
+    if (provider.seam !== seam) {
+      issues.push(`provider \`${selected}\` is a \`${provider.seam}\` provider, not \`${seam}\``);
+      return requireDefault(seam);
+    }
+    return provider;
+  };
+
+  return {
+    plan: resolveSeam("plan"),
+    todo: resolveSeam("todo"),
+    askuser: resolveSeam("askuser"),
+    footer: resolveSeam("footer"),
+    web: resolveSeam("web"),
+    issues,
+  };
+}

package/extension/substrate/registry.ts

@@ -0,0 +1,62 @@
+// The TS plane's reader for the shared stage registry (`shared/registry.yaml`).
+//
+// Twin of perk/substrate/registry.py: both planes parse the SAME bundled file (no codegen). The
+// extension drives in-session transitions from the parsed registry. The Python CLI is the
+// authoritative validator (`perk registry check`); this side does a thin structural assertion.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "./miniYaml.ts";
+import { sharedDir } from "./resources.ts";
+
+export interface RegistryStage {
+  id: string;
+  command: string;
+  doors: Record<string, boolean>;
+  predecessors: string[];
+  successors: string[];
+  requires?: string[];
+  reads?: string[];
+  writes?: string[];
+}
+
+export interface Registry {
+  schemaVersion: number;
+  stages: RegistryStage[];
+}
+
+/** The registry state-key for the active plan->branch ref (contracts.md §8.1/§8.4). */
+export const PLAN_REF_STATE_KEY = "cache.plan-ref";
+
+/**
+ * Whether a stage *consumes* the plan-ref selector — i.e. its `requires ∪ reads` lists
+ * `cache.plan-ref`. The worktree stages (implement/submit/address/land/learn) do; the
+ * root `worktree: none` stages (plan/objective-plan/save) do not. An unknown stage id is
+ * treated as non-consuming (false).
+ */
+export function stageConsumesPlanRef(registry: Registry, stageId: string): boolean {
+  const stage = registry.stages.find((s) => s.id === stageId);
+  if (stage === undefined) return false;
+  const keys = [...(stage.requires ?? []), ...(stage.reads ?? [])];
+  return keys.includes(PLAN_REF_STATE_KEY);
+}
+
+/** Parse the bundled `registry.yaml`. Throws on a missing file or unexpected shape. */
+export function loadRegistry(): Registry {
+  const path = join(sharedDir(), "registry.yaml");
+  const data = parse(readFileSync(path, "utf8")) as unknown;
+
+  if (typeof data !== "object" || data === null) {
+    throw new Error(`perk: ${path} is not a mapping`);
+  }
+  const record = data as Record<string, unknown>;
+  const stages = record.stages;
+  if (!Array.isArray(stages) || stages.length === 0) {
+    throw new Error(`perk: ${path} has no stages`);
+  }
+
+  return {
+    schemaVersion: typeof record.schema_version === "number" ? record.schema_version : 0,
+    stages: stages.map((raw) => raw as RegistryStage),
+  };
+}

package/extension/substrate/resources.ts

@@ -0,0 +1,41 @@
+// The TS plane's twin of perk/_resources.py: locate the bundled `shared/`
+// contracts dir and read the lockstep version. `extension/` and `shared/` are
+// siblings in both the dev tree and the published tarball (npm `files` preserves
+// the layout), so a single `../shared` path resolves in both modes — no
+// dual-path manifest is needed.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function packageRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+
+/** Absolute path to the bundled `shared/` contracts directory. */
+export function sharedDir(): string {
+  const dir = join(packageRoot(), "shared");
+  if (!existsSync(dir)) {
+    throw new Error(`perk: could not locate the bundled 'shared/' directory at ${dir}`);
+  }
+  return dir;
+}
+
+/** Absolute path to the bundled `prompts/` directory. */
+export function promptsDir(): string {
+  const dir = join(packageRoot(), "prompts");
+  if (!existsSync(dir)) {
+    throw new Error(`perk: could not locate the bundled 'prompts/' directory at ${dir}`);
+  }
+  return dir;
+}
+
+/** perk version, read from the package.json shipped alongside the extension. */
+export function perkVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/extension/substrate/result.ts

@@ -0,0 +1,72 @@
+// The one warm-door Result seam — owns the canonical { content, details, terminate? } tool-result
+// shape and the loud-but-soft failure idiom (report + "<label> failed: <message>"), so the nine
+// cold-door-delegating doors share one discriminated union instead of ad-hoc *Result/*Details
+// pairs (cf. report.ts, branchOf).
+
+import { type ReportTarget, report } from "../surfaces/report.ts";
+
+/** The single text block every warm-door result renders ("one text field, two doors"). */
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+/** The canonical failure details. `X` adds module-specific fail extras (address's batch results). */
+export type FailDetails<X extends object = Record<never, never>> = {
+  ok: false;
+  error: string;
+  error_type: string;
+} & X;
+
+export type OkDetails<D extends object> = { ok: true } & D;
+
+export interface OkResult<D extends object> {
+  content: TextBlock[];
+  details: OkDetails<D>;
+  terminate?: boolean;
+}
+
+export interface FailResult<X extends object = Record<never, never>> {
+  content: TextBlock[];
+  details: FailDetails<X>;
+  terminate?: boolean;
+}
+
+/** The discriminated-union warm-door result (discriminant: `details.ok`). */
+export type Result<D extends object, X extends object = Record<never, never>> =
+  | OkResult<D>
+  | FailResult<X>;
+
+/** Build a success result. `terminate: true` is included ONLY when requested (key-absent otherwise). */
+export function ok<D extends object>(
+  text: string,
+  details: D,
+  opts?: { terminate?: boolean },
+): OkResult<D> {
+  return {
+    content: [{ type: "text", text }],
+    details: { ok: true, ...details },
+    ...(opts?.terminate ? { terminate: true } : {}),
+  };
+}
+
+/**
+ * Bind the module's fail constructor once: `const fail = failFor(ctx, scope)` (or
+ * `failFor(ctx, scope, label)` when the content label differs from the report scope). Each call
+ * reports loudly (`report(ctx, scope, "error", message, { alsoLog: true })`) and returns the
+ * canonical soft failure: content `"<label> failed: <message>"`, details
+ * `{ ok: false, error: message, error_type: errorType }`, no `terminate`.
+ */
+export function failFor(
+  target: ReportTarget,
+  scope: string,
+  label: string = scope,
+): (message: string, errorType: string) => FailResult {
+  return (message, errorType) => {
+    report(target, scope, "error", message, { alsoLog: true });
+    return {
+      content: [{ type: "text", text: `${label} failed: ${message}` }],
+      details: { ok: false, error: message, error_type: errorType },
+    };
+  };
+}