@remnic/core 9.3.692 → 9.3.693

package/src/coding/session-delta.ts

@@ -0,0 +1,442 @@
+/**
+ * Session delta — pure repo differ + thin state persistence
+ * (issue #1548 Track A PR 4).
+ *
+ * Tells a returning agent "since you last worked here: N commits, these
+ * files." The differ is a pure function over a {@link GitLogSlice}; the
+ * caller supplies the slice (from a real git invoker or a test fixture).
+ *
+ * Design rules honoured:
+ *  - rule 11 — no module-level mutable state; the state file is read and
+ *    written through passed-in functions, never cached in module scope.
+ *  - rule 25 — the new last-seen-head is persisted AFTER the delta is
+ *    computed from the old one; the caller never destroys the old marker
+ *    before the new state is useful.
+ *  - rule 27 — `slice(-n)` caps guard against `n === 0` (which would
+ *    return the whole array instead of an empty slice).
+ *  - rule 34 — every non-trivial outcome is a tagged union; a missing
+ *    prior head, an unreachable head (force-push/rebase), or a git failure
+ *    is surfaced with a distinct code, never as an empty delta.
+ *  - rule 48 — least-privileged defaults: caps are conservative.
+ *  - rule 51 — invalid inputs are rejected loudly by the persistence
+ *    helpers, never silently coerced.
+ *  - rule 54 — state writes are temp-file-then-rename so a crashed write
+ *    never leaves a truncated JSON file at the canonical path.
+ *
+ * Storage: `<memoryDir>/state/coding-knowledge/<sanitized-namespace>.json`
+ * (precedent: `calibration.ts`). The namespace is already sanitized by the
+ * coding-namespace router, but `sanitizeFragment` is reused defensively so a
+ * future caller cannot place a state file outside the directory.
+ */
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import path from "node:path";
+import { sanitizeFragment } from "./coding-namespace.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Public types
+// ──────────────────────────────────────────────────────────────────────────
+
+/** A single commit in the delta slice. */
+export interface GitCommit {
+  /** Full or abbreviated SHA — callers decide precision. */
+  sha: string;
+  /** First-line commit subject. */
+  subject: string;
+}
+
+/**
+ * The repo's current state since the last-seen head. Callers populate this
+ * from a real git invoker (see {@link SessionDeltaGitInvoker}); tests inject
+ * a fixture directly.
+ */
+export interface GitLogSlice {
+  /** Commits in `lastSeen..currentHead`, oldest-first. Empty when unchanged. */
+  commits: GitCommit[];
+  /** Files touched across those commits, de-duplicated and sorted. */
+  touchedFiles: string[];
+  /** The repo's current HEAD SHA. */
+  currentHead: string;
+}
+
+/** Persisted marker: the HEAD we last computed a delta against, and when. */
+export interface LastSeenState {
+  /** HEAD SHA at the time of the last delta. */
+  head: string;
+  /** ISO timestamp of the last delta computation. */
+  at: string;
+}
+
+/** A successful delta computation. */
+export interface SessionDelta {
+  /** Commits since last seen, capped to {@link MAX_DELTA_COMMITS}. */
+  commits: GitCommit[];
+  /** Touched files since last seen, capped to {@link MAX_DELTA_FILES}. */
+  touchedFiles: string[];
+  /** A single human-readable summary line for briefing injection. */
+  summaryLine: string;
+}
+
+/**
+ * Tagged result. Every non-trivial path returns a distinct shape so callers
+ * (briefing, xray, doctor) can distinguish "first run" from "no changes"
+ * from "delta unavailable" — never an empty delta masquerading as "nothing
+ * happened" (rule 34).
+ */
+export type SessionDeltaResult =
+  /** A non-empty delta was computed. */
+  | { ok: true; kind: "changed"; delta: SessionDelta; nextState: LastSeenState }
+  /** Prior head equals current head — no changes to report. */
+  | { ok: true; kind: "unchanged"; nextState: LastSeenState }
+  /** No prior state — first session for this namespace. */
+  | { ok: true; kind: "first_run"; nextState: LastSeenState }
+  /** The prior head is unreachable (force-push/rebase). Delta unavailable. */
+  | { ok: false; code: "unreachable_head"; detail: string; nextState: LastSeenState }
+  /** The git invoker failed (timeout, missing binary, non-zero exit). */
+  | { ok: false; code: "git_failed"; detail: string };
+
+// ──────────────────────────────────────────────────────────────────────────
+// Caps (rule 27 / rule 48)
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Maximum commits retained in a delta. Older commits beyond the cap are dropped. */
+export const MAX_DELTA_COMMITS = 20;
+
+/** Maximum touched files retained in a delta. */
+export const MAX_DELTA_FILES = 50;
+
+// ──────────────────────────────────────────────────────────────────────────
+// Pure differ
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Compute a session delta from a prior state and the current repo slice.
+ *
+ * Returns one of:
+ *  - `first_run` — no prior state; the caller should persist `nextState`
+ *    but render NO delta section (a first session must not claim "0 changes").
+ *  - `unchanged` — prior head equals current head; suppress the section.
+ *  - `changed` — a real delta with capped commits/files + a summary line.
+ *
+ * This function is pure: it reads neither disk nor git. The caller supplies
+ * `current` already resolved. The only side-effect-bearing step is the
+ * caller's subsequent `writeLastSeenState(nextState)` call.
+ */
+export function computeSessionDelta(
+  lastSeen: LastSeenState | null,
+  current: GitLogSlice,
+): SessionDeltaResult {
+  const now = new Date().toISOString();
+  const nextState: LastSeenState = { head: current.currentHead, at: now };
+
+  // First session — no prior marker. Initialize state but render nothing.
+  // A first session claiming "0 changes" is a contract lie (rule 34).
+  if (lastSeen === null) {
+    return { ok: true, kind: "first_run", nextState };
+  }
+
+  // Unchanged — prior head still current. Suppress, do not render "no changes".
+  if (lastSeen.head === current.currentHead) {
+    return { ok: true, kind: "unchanged", nextState };
+  }
+
+  // If the slice reports zero commits despite a head change, the prior head
+  // is unreachable (force-push/rebase erased it). Tagged failure, never a crash.
+  if (current.commits.length === 0) {
+    return {
+      ok: false,
+      code: "unreachable_head",
+      detail: `prior head ${lastSeen.head} is not an ancestor of current ${current.currentHead}`,
+      nextState,
+    };
+  }
+
+  const commits = capCommits(current.commits, MAX_DELTA_COMMITS);
+  const touchedFiles = capFiles(current.touchedFiles, MAX_DELTA_FILES);
+
+  return {
+    ok: true,
+    kind: "changed",
+    delta: {
+      commits,
+      touchedFiles,
+      summaryLine: buildSummaryLine(commits.length, touchedFiles.length, lastSeen.at),
+    },
+    nextState,
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Caps — rule 27: guard slice(-n) against n === 0
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Cap a commits array to the most-recent `max` entries.
+ *
+ * `Array.prototype.slice(-n)` with `n === 0` returns the WHOLE array (not
+ * an empty slice), so an explicit guard is mandatory (rule 27). We keep the
+ * most-recent commits (tail), which is what a returning agent cares about.
+ */
+export function capCommits(commits: GitCommit[], max: number): GitCommit[] {
+  if (!Number.isFinite(max) || max <= 0) return [];
+  if (commits.length <= max) return commits;
+  return commits.slice(-max);
+}
+
+/**
+ * Cap a touched-files list to `max` entries, preserving sort order.
+ * Same rule-27 guard as {@link capCommits}.
+ */
+export function capFiles(files: string[], max: number): string[] {
+  if (!Number.isFinite(max) || max <= 0) return [];
+  if (files.length <= max) return files;
+  return files.slice(0, max);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Summary line
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build the single briefing-summary line. Deterministic and locale-stable
+ * so a briefing snapshot is byte-identical across runs for the same input.
+ */
+export function buildSummaryLine(commitCount: number, fileCount: number, sinceIso: string): string {
+  const since = formatSinceDate(sinceIso);
+  const commitWord = commitCount === 1 ? "commit" : "commits";
+  const fileWord = fileCount === 1 ? "file" : "files";
+  return `Since ${since}: ${commitCount} ${commitWord}, ${fileCount} ${fileWord} touched.`;
+}
+
+/**
+ * Format the "since" timestamp as a stable, locale-independent label.
+ * Returns the raw ISO date (YYYY-MM-DD) so the briefing snapshot never
+ * depends on the runtime locale or timezone.
+ */
+function formatSinceDate(iso: string): string {
+  // Defensive: if the stored timestamp is malformed, fall back to the raw
+  // string rather than crashing the delta render (rule 34 — never crash on
+  // persisted state corruption).
+  const match = /^(\d{4}-\d{2}-\d{2})/.exec(iso);
+  return match ? match[1]! : iso;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// State persistence
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Subdirectory under `<memoryDir>/state/` holding coding-knowledge markers. */
+export const CODING_KNOWLEDGE_STATE_DIR = path.join("state", "coding-knowledge");
+
+/**
+ * Compute the canonical state-file path for a namespace.
+ *
+ * The namespace is already router-sanitized, but `sanitizeFragment` is
+ * applied defensively so a caller passing an unsanitized value cannot place
+ * a file outside the directory (rule 51 — defensive at the boundary).
+ */
+export function sessionDeltaStatePath(memoryDir: string, namespace: string): string {
+  const safe = sanitizeFragment(namespace) || "default";
+  return path.join(memoryDir, CODING_KNOWLEDGE_STATE_DIR, `${safe}.json`);
+}
+
+/**
+ * Read the persisted last-seen-head marker. Returns `null` when the file is
+ * absent, empty, or malformed — never throws (rule 34 — corrupted state
+ * degrades to a first-run, not a crash).
+ */
+export async function readLastSeenState(statePath: string): Promise<LastSeenState | null> {
+  try {
+    const raw = await readFile(statePath, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const obj = parsed as Record<string, unknown>;
+    const head = typeof obj.head === "string" ? obj.head : null;
+    const at = typeof obj.at === "string" ? obj.at : null;
+    if (!head || !at) return null;
+    return { head, at };
+  } catch {
+    // Absent or unreadable — treat as first run.
+    return null;
+  }
+}
+
+/**
+ * Persist the last-seen-head marker using temp-file-then-rename (rule 54)
+ * so a crashed write never leaves a truncated file at the canonical path.
+ *
+ * The caller invokes this AFTER computing the delta from the prior state
+ * (rule 25 — do not destroy the old marker before the new state is useful).
+ */
+export async function writeLastSeenState(
+  statePath: string,
+  state: LastSeenState,
+): Promise<void> {
+  if (!state.head || !state.at) {
+    throw new Error(
+      `writeLastSeenState: invalid state (head=${JSON.stringify(state.head)}, at=${JSON.stringify(state.at)})`,
+    );
+  }
+  const dir = path.dirname(statePath);
+  await mkdir(dir, { recursive: true });
+  const tmp = `${statePath}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(state, null, 2), "utf8");
+  await rename(tmp, statePath);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Git invoker — the contract the surface handler satisfies to populate a
+// GitLogSlice from a real repo. Mirrors coding/git-context.ts discipline:
+// 2s timeout per call, never throws, exitCode returned to the caller.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Injectable git-invocation surface for session-delta. Only the two commands
+ * the differ needs are exposed. Implementations MUST NOT throw for non-zero
+ * exit codes — they return `{ exitCode, stdout }` so the handler can decide
+ * how to recover (rule 34).
+ */
+export interface SessionDeltaGitInvoker {
+  /**
+   * Run `git <args>` with `cwd` as the working directory.
+   * Implementations enforce a per-call timeout (2s precedent in
+   * `coding/git-context.ts`) and return non-zero exit codes instead of
+   * throwing.
+   */
+  (cwd: string, args: string[]): { stdout: string; exitCode: number };
+}
+
+/**
+ * Result of resolving the current repo slice. Tagged so the handler can
+ * surface a distinct degradation code (rule 34).
+ */
+export type ResolveSliceResult =
+  | { ok: true; slice: GitLogSlice }
+  | { ok: false; code: "git_failed" | "no_head"; detail: string };
+
+/** Default per-call timeout when no invoker override is supplied. */
+export const SESSION_DELTA_GIT_TIMEOUT_MS = 2_000;
+
+/**
+ * Resolve the current HEAD and the commit/file slice since `sinceHead`.
+ *
+ * Uses two git calls:
+ *   1. `rev-parse HEAD` — current head.
+ *   2. `log --name-only --pretty=format:... sinceHead..HEAD` — commits + files.
+ *
+ * Never throws; failures map to `{ ok: false, code }` and the handler
+ * surfaces them as `git_failed` or `unreachable_head`.
+ */
+export function resolveSlice(
+  repoRoot: string,
+  sinceHead: string | null,
+  invoker: SessionDeltaGitInvoker,
+): ResolveSliceResult {
+  const headResult = invoker(repoRoot, ["rev-parse", "HEAD"]);
+  if (headResult.exitCode !== 0) {
+    return {
+      ok: false,
+      code: headResult.stdout.trim().length === 0 ? "no_head" : "git_failed",
+      detail: `rev-parse HEAD exited ${headResult.exitCode}`,
+    };
+  }
+  const currentHead = headResult.stdout.trim();
+  if (!currentHead) {
+    return { ok: false, code: "no_head", detail: "rev-parse HEAD returned empty" };
+  }
+
+  // First run — no prior head to diff against. Return an empty slice; the
+  // differ turns this into a `first_run` outcome.
+  if (!sinceHead) {
+    return { ok: true, slice: { commits: [], touchedFiles: [], currentHead } };
+  }
+
+  // Unchanged — short-circuit before the log call (saves a git invocation).
+  if (sinceHead === currentHead) {
+    return { ok: true, slice: { commits: [], touchedFiles: [], currentHead } };
+  }
+
+  // Use a unique ASCII separator unlikely to appear in commit subjects or
+  // paths. NUL would be ideal but is awkward to pass through argv; unit
+  // separator (\x1f) is the next-best thing and is rejected by sanitize if
+  // it ever leaks into memory content.
+  const SEP = "\x1f";
+  // --reverse makes git emit oldest-first, so the commits array reads in
+  // chronological order and capCommits' slice(-max) keeps the NEWEST entries
+  // (the ones a returning agent cares about). Without --reverse, git log is
+  // newest-first and slice(-max) would drop exactly the commits we want.
+  const logResult = invoker(repoRoot, [
+    "log",
+    "--reverse",
+    `--pretty=format:%H${SEP}%s`,
+    "--name-only",
+    `${sinceHead}..${currentHead}`,
+  ]);
+  if (logResult.exitCode !== 0) {
+    // Exit code 128 is git's "bad revision" / "object not found" — the prior
+    // head is genuinely unreachable (force-push/rebase erased it). Return an
+    // empty slice so the differ labels it `unreachable_head`; the state marker
+    // advances so the next call sees the new head as the baseline.
+    if (logResult.exitCode === 128) {
+      return { ok: true, slice: { commits: [], touchedFiles: [], currentHead } };
+    }
+    // Other non-zero exit codes (127 = spawn failure / 2s timeout, 129+ =
+    // signal, etc.) are TRANSIENT — the old head is probably still valid. Do
+    // NOT treat these as unreachable and do NOT let the caller advance the
+    // state marker. Return `git_failed` so the surface preserves the old
+    // marker and the next session retries.
+    return {
+      ok: false,
+      code: "git_failed",
+      detail: 'git log exited ' + logResult.exitCode + ' (transient — state marker preserved)',
+    };
+  }
+
+  const { commits, touchedFiles } = parseLogOutput(logResult.stdout, SEP);
+  return { ok: true, slice: { commits, touchedFiles, currentHead } };
+}
+
+/**
+ * Parse `git log --pretty=format:%H<SEP>%s --name-only` output into structured
+ * commits + a de-duplicated, sorted touched-file list.
+ *
+ * Exported for unit tests.
+ */
+export function parseLogOutput(stdout: string, sep: string): {
+  commits: GitCommit[];
+  touchedFiles: string[];
+} {
+  const commits: GitCommit[] = [];
+  const fileSet = new Set<string>();
+
+  // Git emits each commit as:
+  //   <sha><SEP><subject>
+  //   <blank line>
+  //   <file1>
+  //   <file2>
+  //   <blank line>
+  //   <next commit>...
+  //
+  // We split on blank-line-separated blocks. A commit block starts with a
+  // line containing the separator; file blocks do not.
+  const blocks = stdout.split(/\n\s*\n/);
+  for (const block of blocks) {
+    const lines = block.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    if (lines.length === 0) continue;
+    const header = lines[0]!;
+    const sepIdx = header.indexOf(sep);
+    if (sepIdx >= 0) {
+      const sha = header.slice(0, sepIdx);
+      const subject = header.slice(sepIdx + sep.length);
+      commits.push({ sha, subject });
+      for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i]!) fileSet.add(lines[i]!);
+      }
+    } else {
+      // A file-only block (continuation) — every non-empty line is a file.
+      for (const line of lines) fileSet.add(line);
+    }
+  }
+
+  const touchedFiles = [...fileSet].sort((a, b) => a.localeCompare(b));
+  return { commits, touchedFiles };
+}

package/dist/chunk-2EN5WZQB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/access-boundary.ts"],"sourcesContent":["/**\n * Single input-validation and error boundary for the CLI/MCP/HTTP access\n * surfaces (issue #1525, epic #1520 Phase 1).\n *\n * Every operation that crosses the access-service facade passes through ONE\n * registry entry: a zod-validated request envelope, a shared error mapper,\n * and the \"reject invalid input and list valid options\" behavior that\n * CLAUDE.md rules 14/17/24/28/36/48/51 previously had to be re-implemented\n * per handler. The three surfaces become thin adapters — one operation\n * definition, three transports — so a validation fix lands everywhere at\n * once.\n *\n * Host-agnostic (rule 31): operation names carry no `openclaw-*`/`engram-*`\n * prefix. Session/namespace tenancy stays in the handler layer (resolved via\n * ScopePlan #1521); the boundary validates SHAPE, not tenancy.\n */\n\nimport { z } from \"zod\";\nimport { EngramAccessInputError, type EngramAccessService } from \"./access-service.js\";\nimport { expandTildePath } from \"./utils/path.js\";\n\n// ---------------------------------------------------------------------------\n// Canonical operation names — host-agnostic (rule 31)\n// ---------------------------------------------------------------------------\n\n/**\n * Canonical operation ids. One id is shared by the MCP tool, the HTTP route,\n * and the CLI command that expose the same operation. Add to this union as\n * each domain-group migration PR (memory ops → connectors → namespaces …)\n * lands; the fitness test in `access-surface-catalog.test.ts` treats the\n * registered set as the migration state.\n */\nexport type OperationName =\n  | \"memory_get\"\n  | \"memory_search\"\n  | \"memory_store\"\n  | \"coding_decision\"\n  | \"coding_architecture\";\n\n// ---------------------------------------------------------------------------\n// Operation context — what every handler receives\n// ---------------------------------------------------------------------------\n\n/**\n * Per-call context. `service` is the facade the handler delegates to; the\n * boundary never reaches past it. `authenticatedPrincipal` is resolved by\n * the SURFACE (MCP header / HTTP identity / CLI flag) before the boundary\n * runs, so handlers stay principal-source-agnostic. `hooks` carries\n * transport-level callbacks (e.g. HTTP write-quota enforcement) that must\n * fire atomically inside the service call; surfaces that have no such hook\n * leave it undefined.\n */\nexport interface OperationContext {\n  readonly service: EngramAccessService;\n  readonly authenticatedPrincipal?: string;\n  readonly hooks?: OperationHooks;\n}\n\n/**\n * Transport-level callbacks a handler forwards into the service call. Kept\n * narrow on purpose: the boundary owns validation + dispatch shape, not\n * transport policy. Add fields here only when a surface genuinely needs a\n * callback the service itself consumes.\n */\nexport interface OperationHooks {\n  /** HTTP write-quota gate; throws to reject the write when exhausted. */\n  readonly enforceWriteQuota?: () => void | Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Operation spec + bound operation\n// ---------------------------------------------------------------------------\n\nexport interface OperationSpec<In, Out> {\n  /** Canonical operation id; matches an {@link OperationName}. */\n  readonly name: OperationName;\n  readonly description: string;\n  /** Zod schema validating the raw request envelope. */\n  readonly schema: z.ZodType<In>;\n  /** Handler invoked with the parsed input; throws EngramAccessInputError for domain faults. */\n  readonly handler: (input: In, ctx: OperationContext) => Promise<Out>;\n}\n\nexport interface BoundOperation<In = unknown, Out = unknown> {\n  readonly spec: OperationSpec<In, Out>;\n  /** Validate the raw envelope, then invoke the handler. Throws EngramAccessInputError on any validation failure. */\n  readonly run: (rawInput: unknown, ctx: OperationContext) => Promise<Out>;\n}\n\n// ---------------------------------------------------------------------------\n// Shared normalizers the boundary owns (rules 17, 28, 36, 48, 51)\n// ---------------------------------------------------------------------------\n\n/**\n * Coerce boolean-like strings at the edge (rule 36). Accepts actual booleans\n * and the string spellings clients send (\"true\"/\"false\"/\"1\"/\"0\"/\"yes\"/\"no\"/\n * \"on\"/\"off\", case-insensitive). Rejects anything else loudly — `Boolean(\"false\")`\n * would silently be `true`, which is the bug rule 36 exists to prevent.\n *\n * `undefined`/`null`/`\"\"` → `undefined`, so callers can keep treating an\n * absent flag as \"use the default\" without a separate presence check.\n */\nexport function coerceBooleanLike(value: unknown): boolean | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") {\n    const lower = value.trim().toLowerCase();\n    if (lower === \"true\" || lower === \"1\" || lower === \"yes\" || lower === \"on\") return true;\n    if (lower === \"false\" || lower === \"0\" || lower === \"no\" || lower === \"off\") return false;\n  }\n  throw new EngramAccessInputError(\n    `expected a boolean-like value (true|false|1|0|yes|no|on|off); got ${JSON.stringify(value)}`,\n  );\n}\n\n/**\n * Coerce + validate a positive integer from a numeric string or number\n * (rule 28). Loosely-typed MCP/CLI clients send `\"5\"`; `typeof saved === \"number\"`\n * on read-back would reject it later, so we coerce at the edge and reject\n * booleans/objects loudly (`Number(true) === 1` would silently pass otherwise).\n *\n * `undefined`/`null`/`\"\"` → `undefined`.\n */\nexport function coercePositiveInteger(value: unknown, label: string): number | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value) || value <= 0 || !Number.isInteger(value)) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    return value;\n  }\n  if (typeof value === \"string\") {\n    const trimmed = value.trim();\n    if (!/^[+-]?\\d+$/.test(trimmed)) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    const parsed = Number(trimmed);\n    if (!Number.isSafeInteger(parsed) || parsed <= 0) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    return parsed;\n  }\n  throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n}\n\n/**\n * Expand `~` in a path-shaped input (rule 17). Node `fs` does NOT expand `~`;\n * ad-hoc regex drifts. `undefined`/`null`/`\"\"` → `undefined`.\n */\nexport function normalizeOptionalPath(value: unknown): string | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value !== \"string\") {\n    throw new EngramAccessInputError(`expected a path string; got ${JSON.stringify(value)}`);\n  }\n  return expandTildePath(value);\n}\n\n// ---------------------------------------------------------------------------\n// Error formatting — rule 51: list valid options, never silently default\n// ---------------------------------------------------------------------------\n\n/**\n * Turn a zod failure into an {@link EngramAccessInputError} whose message\n * names the offending field and — for enum/union issues — lists the valid\n * options, so the caller can correct rather than guess (rule 51).\n */\nexport function formatZodIssues(error: z.ZodError): string {\n  const parts: string[] = [];\n  for (const issue of error.issues) {\n    const path = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    const options = enumOptionsFromIssue(issue);\n    const suffix = options ? `. Valid: ${options.join(\", \")}` : \"\";\n    parts.push(`${path}: ${issue.message}${suffix}`);\n  }\n  return parts.length > 0\n    ? `request validation failed: ${parts.join(\"; \")}`\n    : \"request validation failed\";\n}\n\nfunction enumOptionsFromIssue(issue: z.ZodIssue): readonly string[] | undefined {\n  // zod exposes accepted enum values on the issue for ZodEnum / ZodNativeEnum\n  // and on the options of invalid_union discriminators. Reading them here\n  // keeps \"list valid options\" in ONE place rather than per handler.\n  if (issue.code === z.ZodIssueCode.invalid_enum_value) {\n    const rawOptions = (issue as { options?: unknown }).options;\n    if (Array.isArray(rawOptions)) {\n      return rawOptions.map((opt) => String(opt));\n    }\n  }\n  return undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Registry\n// ---------------------------------------------------------------------------\n\nconst registry = new Map<OperationName, BoundOperation>();\n\n/**\n * Register an operation. Throws if the name is already registered — duplicate\n * registration is a programming error, not a runtime input fault, so it throws\n * a plain Error (not the input-error class surfaces translate for clients).\n */\nexport function defineOperation<In, Out>(spec: OperationSpec<In, Out>): BoundOperation<In, Out> {\n  if (registry.has(spec.name)) {\n    throw new Error(`access-boundary: operation already registered: ${spec.name}`);\n  }\n  const bound: BoundOperation<In, Out> = {\n    spec,\n    run: async (rawInput, ctx) => {\n      const parseResult = spec.schema.safeParse(rawInput);\n      if (!parseResult.success) {\n        throw new EngramAccessInputError(formatZodIssues(parseResult.error));\n      }\n      return spec.handler(parseResult.data, ctx);\n    },\n  };\n  // Store under the canonical name; the cast is safe because In/Out are\n  // erased at the registry boundary and recovered by callers via getOperation.\n  registry.set(spec.name, bound as unknown as BoundOperation);\n  return bound;\n}\n\n/** Look up a registered operation by canonical name. */\nexport function getOperation(name: OperationName): BoundOperation | undefined {\n  return registry.get(name);\n}\n\n/** All registered operation names. */\nexport function listRegisteredOperations(): readonly OperationName[] {\n  return [...registry.keys()];\n}\n\n/** Test-only: clear the registry so pilot definitions can be re-registered. */\nexport function __resetRegistryForTest(): void {\n  registry.clear();\n}\n"],"mappings":";;;;;;;;AAiBA,SAAS,SAAS;AAqFX,SAAS,kBAAkB,OAAqC;AACrE,MAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,GAAI,QAAO;AAClE,MAAI,OAAO,UAAU,UAAW,QAAO;AACvC,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,QAAQ,MAAM,KAAK,EAAE,YAAY;AACvC,QAAI,UAAU,UAAU,UAAU,OAAO,UAAU,SAAS,UAAU,KAAM,QAAO;AACnF,QAAI,UAAU,WAAW,UAAU,OAAO,UAAU,QAAQ,UAAU,MAAO,QAAO;AAAA,EACtF;AACA,QAAM,IAAI;AAAA,IACR,qEAAqE,KAAK,UAAU,KAAK,CAAC;AAAA,EAC5F;AACF;AAUO,SAAS,sBAAsB,OAAgB,OAAmC;AACvF,MAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,GAAI,QAAO;AAClE,MAAI,OAAO,UAAU,UAAU;AAC7B,QAAI,CAAC,OAAO,SAAS,KAAK,KAAK,SAAS,KAAK,CAAC,OAAO,UAAU,KAAK,GAAG;AACrE,YAAM,IAAI,uBAAuB,GAAG,KAAK,oCAAoC,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,IACtG;AACA,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,UAAU,MAAM,KAAK;AAC3B,QAAI,CAAC,aAAa,KAAK,OAAO,GAAG;AAC/B,YAAM,IAAI,uBAAuB,GAAG,KAAK,oCAAoC,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,IACtG;AACA,UAAM,SAAS,OAAO,OAAO;AAC7B,QAAI,CAAC,OAAO,cAAc,MAAM,KAAK,UAAU,GAAG;AAChD,YAAM,IAAI,uBAAuB,GAAG,KAAK,oCAAoC,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,IACtG;AACA,WAAO;AAAA,EACT;AACA,QAAM,IAAI,uBAAuB,GAAG,KAAK,oCAAoC,KAAK,UAAU,KAAK,CAAC,EAAE;AACtG;AAMO,SAAS,sBAAsB,OAAoC;AACxE,MAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,GAAI,QAAO;AAClE,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,IAAI,uBAAuB,+BAA+B,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,EACzF;AACA,SAAO,gBAAgB,KAAK;AAC9B;AAWO,SAAS,gBAAgB,OAA2B;AACzD,QAAM,QAAkB,CAAC;AACzB,aAAW,SAAS,MAAM,QAAQ;AAChC,UAAM,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,GAAG,IAAI;AAC5D,UAAM,UAAU,qBAAqB,KAAK;AAC1C,UAAM,SAAS,UAAU,YAAY,QAAQ,KAAK,IAAI,CAAC,KAAK;AAC5D,UAAM,KAAK,GAAG,IAAI,KAAK,MAAM,OAAO,GAAG,MAAM,EAAE;AAAA,EACjD;AACA,SAAO,MAAM,SAAS,IAClB,8BAA8B,MAAM,KAAK,IAAI,CAAC,KAC9C;AACN;AAEA,SAAS,qBAAqB,OAAkD;AAI9E,MAAI,MAAM,SAAS,EAAE,aAAa,oBAAoB;AACpD,UAAM,aAAc,MAAgC;AACpD,QAAI,MAAM,QAAQ,UAAU,GAAG;AAC7B,aAAO,WAAW,IAAI,CAAC,QAAQ,OAAO,GAAG,CAAC;AAAA,IAC5C;AAAA,EACF;AACA,SAAO;AACT;AAMA,IAAM,WAAW,oBAAI,IAAmC;AAOjD,SAAS,gBAAyB,MAAuD;AAC9F,MAAI,SAAS,IAAI,KAAK,IAAI,GAAG;AAC3B,UAAM,IAAI,MAAM,kDAAkD,KAAK,IAAI,EAAE;AAAA,EAC/E;AACA,QAAM,QAAiC;AAAA,IACrC;AAAA,IACA,KAAK,OAAO,UAAU,QAAQ;AAC5B,YAAM,cAAc,KAAK,OAAO,UAAU,QAAQ;AAClD,UAAI,CAAC,YAAY,SAAS;AACxB,cAAM,IAAI,uBAAuB,gBAAgB,YAAY,KAAK,CAAC;AAAA,MACrE;AACA,aAAO,KAAK,QAAQ,YAAY,MAAM,GAAG;AAAA,IAC3C;AAAA,EACF;AAGA,WAAS,IAAI,KAAK,MAAM,KAAkC;AAC1D,SAAO;AACT;AAGO,SAAS,aAAa,MAAiD;AAC5E,SAAO,SAAS,IAAI,IAAI;AAC1B;AAGO,SAAS,2BAAqD;AACnE,SAAO,CAAC,GAAG,SAAS,KAAK,CAAC;AAC5B;AAGO,SAAS,yBAA+B;AAC7C,WAAS,MAAM;AACjB;","names":[]}