slidemind 0.3.20 → 0.4.1

package/src/lib/edit-transitions.mjs

@@ -0,0 +1,120 @@
+// The operation-scope gate, CLI half (workflow/edit.md → "This is not a
+// text-only cage"). The add-in refuses these transitions at the write
+// (`edit-transitions.ts`); this CLI's agent writes slide files with its own
+// tools, so the first moment slidemind sees a change is the next command that
+// reads the deck — view-draft, build-pptx, push. The RULE is shared
+// (`editTransitionViolation`, src/lib/edit-operations.mjs, mirrored into the
+// add-in); this module only reads the deck to ask it.
+//
+// One write it makes, and only for an authorized redesign: an imported slide
+// whose pragma a redesign dropped is recorded as restyled (`dialect:
+// "semantic"`, back to `needsReview`) — the counterpart of the add-in's
+// dialect-sync. Without it the render keeps reading the record as converted,
+// and every later edit of the restyled slide would read as a dropped pragma.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONVERSIONS_DIR, conversionProvenance } from "./conversions.mjs";
+import { deckSlug } from "./deck-paths.mjs";
+import { editTransitionViolation, operationSlideKeys } from "./edit-operations.mjs";
+import { openOperations, resolveSlideTargets } from "./edit-state.mjs";
+
+// The renderer's own test: the pragma is the source's FIRST line.
+const PRAGMA_RE = /^\s*\/\/\s*SLIDEMIND_DIALECT:\s*converted\s*$/;
+const keepsPragma = (jsx) => PRAGMA_RE.test(String(jsx).split("\n", 1)[0] ?? "");
+
+function readSource(deckDir, jsxPath) {
+  try {
+    return fs.readFileSync(path.join(deckDir, jsxPath), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function markRestyled(deckDir, file, record) {
+  const stem = file.replace(/\.jsx$/i, "");
+  const next = { ...record, dialect: "semantic", state: "needsReview" };
+  fs.writeFileSync(path.join(deckDir, CONVERSIONS_DIR, `${stem}.json`), `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Every change on disk that the open scopes do not authorize, as refusal lines
+ * (empty when the deck may proceed). A record that cannot be read refuses: what
+ * this session may change cannot be established.
+ */
+export function editTransitionRefusals(deckDir) {
+  let operations;
+  try {
+    operations = openOperations(deckDir);
+  } catch (err) {
+    return [`${err.message} What this session may change cannot be established, so nothing was rendered.`];
+  }
+  // Nothing scoped and nothing imported: no transition to ask about.
+  if (operations.length === 0 && !fs.existsSync(path.join(deckDir, CONVERSIONS_DIR))) return [];
+  const refusals = [];
+  const slides = resolveSlideTargets(deckDir);
+  // Scopes are compared by slide key, never by path: a reorder renames every
+  // file, and a renamed target is still the slide the scope named.
+  const scoped = operations.filter((op) => op.kind !== "create");
+  const inScope = scoped.length ? [...new Set(scoped.flatMap((op) => operationSlideKeys(op)))] : null;
+  const deck = deckSlug(deckDir);
+
+  // Another slide, or a sibling beside a target, changed while a scope is open.
+  for (const slide of slides) {
+    if (!editTransitionViolation({ scoped: inScope }, { slide: slide.slideKey })) continue;
+    const op = scoped.find((o) => (o.preparedSourceHashes ?? {})[slide.slideKey] !== slide.sourceHash);
+    if (!op) continue;
+    const before = (op.preparedSourceHashes ?? {})[slide.slideKey];
+    refusals.push(
+      `${slide.jsxPath} ${before === undefined ? "appeared" : "changed"} after the ${op.kind} scope ` +
+        `${op.operationId} opened on ${op.targets.map((t) => t.jsxPath).join(", ")}. A scope authorizes its own slides only — a ` +
+        `second file beside a target does not become the edit, it becomes an extra slide nobody asked for. Undo it ` +
+        `and make the change in the target itself; if the request covers this slide too, finish the session ` +
+        `(\`slidemind revision finish ${deck}\`) and open a scope that names it.`,
+    );
+  }
+
+  // An imported slide re-authored without its pragma: a restyle, so a redesign.
+  for (const slide of slides) {
+    if (!/\.jsx$/i.test(slide.file)) continue;
+    const record = conversionProvenance(deckDir, slide.file);
+    if (!record || (record.dialect ?? "converted") !== "converted") continue;
+    const jsx = readSource(deckDir, slide.jsxPath);
+    if (jsx === null || keepsPragma(jsx)) continue;
+    const op = operations.find((o) => (o.targets ?? []).some((t) => t?.slideKey === slide.slideKey)) ?? null;
+    const kind = op?.kind ?? null;
+    if (!editTransitionViolation({ kind }, { slide: slide.slideKey, imported: true, keepsPragma: false })) {
+      markRestyled(deckDir, slide.file, record);
+      continue;
+    }
+    refusals.push(
+      `${slide.jsxPath} is an imported slide and its source no longer starts with ` +
+        `\`// SLIDEMIND_DIALECT: converted\` — that restyles the import into brand jsx, which is a redesign. ` +
+        (op ? `Its scope ${op.operationId} is a ${kind}` : `No redesign scope names it`) +
+        `, so the change is not authorized, and deleting the line does not authorize it: the import is recorded ` +
+        `in ${CONVERSIONS_DIR}/${slide.file.replace(/\.jsx$/i, "")}.json. Restore the pragma as the first line and ` +
+        `make the change inside the imported source. A restyle the user asked for runs as ` +
+        `\`slidemind revision begin ${deck} --operation redesign --slides ${slide.number}\`.`,
+    );
+  }
+  return refusals;
+}
+
+/**
+ * The slide files the open scopes authorize, or null when none is open — what
+ * bounds slidemind's own rewrites (view-draft's autofix) to the same slides.
+ */
+export function scopedSlideFiles(deckDir) {
+  let operations;
+  try {
+    operations = openOperations(deckDir).filter((op) => op.kind !== "create");
+  } catch {
+    return null;
+  }
+  if (operations.length === 0) return null;
+  const keys = new Set(operations.flatMap((op) => operationSlideKeys(op)));
+  return resolveSlideTargets(deckDir)
+    .filter((t) => keys.has(t.slideKey) && /\.jsx$/i.test(t.file))
+    .map((t) => t.file);
+}

package/src/lib/extensions.mjs

@@ -0,0 +1,501 @@
+// Trusted installed extensions — protocol v1.
+//
+// A deck can carry business rules the generic CLI has no business knowing:
+// which coverage a deck must show, which commercial figures have to agree,
+// which approved plan its content was signed off against. Those rules live in a
+// privately distributed pack, and this is the wire between the two.
+//
+// The single security property everything else follows from: **the deck selects
+// an extension by id; it never supplies what to run.** Registration is local and
+// deliberate — a file this machine's user installed — so a mailed .pptx can name
+// `some-pack` and get nothing at all on a machine that does not have it
+// (a `extension_missing` blocker, and no managed publish), rather than executing
+// whatever a tag said.
+//
+// Five methods, JSON in on stdin, JSON out on stdout, one process per call:
+//
+//   hydrate    cold open: restore local context from the portable refs, and say
+//              which slides need to be editable for the work ahead.
+//   manifest   which durable artifacts this deck owns right now — purpose,
+//              requiredness, mutability, content hash, where they sit locally.
+//   assess     incoming changes landed; does the business side accept them?
+//   validate   the FINAL candidate bytes plus the final dependency refs. Returns
+//              hash-bound evidence, which is what makes a later reuse legitimate.
+//   committed  a confirmed receipt, idempotently. Local state only — an
+//              extension may not publish or build from here.
+//
+// The CLI stays purpose-agnostic on purpose (AGENTS.md: this package must never
+// carry, name or hardcode anything from a pack). `purpose` is an opaque string
+// used for pairing and requiredness; what the CLI DOES enforce is containment —
+// a declared local path that escapes the deck, traverses a symlink, or lands on
+// the revision protocol's own state is refused and diverted to isolated recovery
+// storage, whatever the purpose was called.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { deckRoot, deckSlug } from "./deck-paths.mjs";
+import { sessionConfigDir } from "../bridge/config.mjs";
+
+export const PROTOCOL = "slidemind.extension";
+export const PROTOCOL_VERSION = 1;
+export const METHODS = ["hydrate", "manifest", "assess", "validate", "committed"];
+
+/** Every status an extension may answer with. Anything else is read as `error`. */
+export const STATUSES = ["ok", "blocked", "unsupported", "error"];
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+// A response bigger than this is a bug on the other side, not a manifest.
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+const sha256File = (file) =>
+  createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+function envTimeoutMs() {
+  const n = Number(process.env.SLIDEMIND_EXTENSION_TIMEOUT_MS);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+
+// ---------------------------------------------------------------------------
+// registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Where the machine's trusted registrations live.
+ *
+ * `SLIDEMIND_EXTENSIONS_FILE` overrides it — the test seam, and the way an
+ * admin-managed harness points at a read-only registry it controls.
+ */
+export function registryPath() {
+  return (
+    process.env.SLIDEMIND_EXTENSIONS_FILE ||
+    path.join(sessionConfigDir(), "extensions.json")
+  );
+}
+
+/**
+ * The registry: `{ version: 1, extensions: { "<id>": { command, protocolVersions,
+ * dataVersions, label } } }`.
+ *
+ * `command` is an argv ARRAY, never a shell string: a string would be parsed by
+ * a shell, and a registry entry is exactly the place where that turns into
+ * command injection with a straight face.
+ */
+export function readRegistry() {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(registryPath(), "utf8"));
+  } catch {
+    return { version: 1, extensions: {} };
+  }
+  if (raw?.version !== 1 || !raw.extensions || typeof raw.extensions !== "object") {
+    return { version: 1, extensions: {} };
+  }
+  const extensions = {};
+  for (const [id, entry] of Object.entries(raw.extensions)) {
+    if (!Array.isArray(entry?.command) || entry.command.length === 0) continue;
+    if (entry.command.some((a) => typeof a !== "string")) continue;
+    extensions[id] = {
+      command: entry.command,
+      protocolVersions: Array.isArray(entry.protocolVersions) ? entry.protocolVersions : [1],
+      dataVersions: Array.isArray(entry.dataVersions) ? entry.dataVersions : null,
+      label: typeof entry.label === "string" ? entry.label : id,
+      // Optional workspace adapter (protocol `slidemind.workspace-adapter`, a
+      // separate wire from this one — src/workspace/adapters.mjs). Same rule:
+      // an argv array from THIS registry, never from a deck.
+      workspace: workspaceEntry(entry.workspace),
+    };
+  }
+  return { version: 1, extensions };
+}
+
+function workspaceEntry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  if (!Array.isArray(raw.command) || raw.command.length === 0) return null;
+  if (raw.command.some((a) => typeof a !== "string")) return null;
+  const versions = Array.isArray(raw.protocolVersions)
+    ? raw.protocolVersions.filter((v) => Number.isInteger(v))
+    : [1];
+  return { command: raw.command, protocolVersions: versions };
+}
+
+/**
+ * Resolve one declaration from a deck's context against what is installed here.
+ *
+ * Returns `{ id, entry }` when it is usable, or `{ id, blocker }` naming exactly
+ * which of the two failures it is — "you do not have this pack" and "your pack
+ * is too old for this deck" need different remedies, and collapsing them into
+ * one message has sent people to reinstall something that was already there.
+ */
+export function resolveExtension(declaration, registry = readRegistry()) {
+  const id = declaration?.id;
+  if (!id) return { id: null, blocker: { code: "extension_incompatible", message: "an extension declaration carries no id" } };
+  const entry = registry.extensions[id];
+  if (!entry) {
+    return {
+      id,
+      blocker: {
+        code: "extension_missing",
+        message:
+          `this deck requires the '${id}' extension, which is not installed on this machine. ` +
+          `Inspection and local recovery still work; a managed publish does not.`,
+        actor: "user",
+      },
+    };
+  }
+  const wantProtocol = declaration.protocolVersion ?? PROTOCOL_VERSION;
+  if (!entry.protocolVersions.includes(wantProtocol)) {
+    return {
+      id,
+      blocker: {
+        code: "extension_incompatible",
+        message:
+          `this deck speaks '${id}' protocol v${wantProtocol}; the installed copy speaks ` +
+          `v${entry.protocolVersions.join(", v")}. Update it before publishing.`,
+        actor: "user",
+      },
+    };
+  }
+  if (
+    declaration.dataVersion !== undefined &&
+    entry.dataVersions &&
+    !entry.dataVersions.includes(declaration.dataVersion)
+  ) {
+    return {
+      id,
+      blocker: {
+        code: "extension_incompatible",
+        message:
+          `this deck carries '${id}' data version ${declaration.dataVersion}; the installed copy ` +
+          `reads ${entry.dataVersions.join(", ")}.`,
+        actor: "user",
+      },
+    };
+  }
+  return { id, entry };
+}
+
+// ---------------------------------------------------------------------------
+// the call
+// ---------------------------------------------------------------------------
+
+/**
+ * One request envelope. Built here rather than by each caller so every method
+ * carries the same evidence fields and the pack has one shape to parse.
+ */
+export function buildRequest({
+  method,
+  workspaceDir,
+  operationId = null,
+  declaration = null,
+  revision = null,
+  dependencies = [],
+  context = null,
+  candidate = null,
+  incoming = null,
+  receipt = null,
+}) {
+  return {
+    protocol: PROTOCOL,
+    version: PROTOCOL_VERSION,
+    method,
+    operationId,
+    extensionId: declaration?.id ?? null,
+    dataVersion: declaration?.dataVersion ?? null,
+    deck: {
+      workspace: workspaceDir,
+      root: deckRoot(workspaceDir),
+      slug: deckSlug(workspaceDir),
+    },
+    revision,
+    dependencies,
+    context,
+    candidate,
+    incoming,
+    receipt,
+  };
+}
+
+/**
+ * Run one method. Never throws for the other side's failures — a crashed,
+ * timed-out or unparseable extension comes back as `status: "error"` with a
+ * typed blocker, because the caller's job is to decide whether that blocks a
+ * publish, not to unwind a stack.
+ */
+export function callExtension(entry, method, request, { timeoutMs = null } = {}) {
+  if (!METHODS.includes(method)) throw new Error(`unknown extension method: ${method}`);
+  const [cmd, ...prefix] = entry.command;
+  const result = spawnSync(cmd, [...prefix, method, "--json"], {
+    input: JSON.stringify(request),
+    encoding: "utf8",
+    maxBuffer: MAX_RESPONSE_BYTES,
+    timeout: timeoutMs ?? envTimeoutMs(),
+    // No shell, ever: `command` is argv, and the whole trust model depends on it
+    // staying argv.
+    shell: false,
+  });
+  const fail = (message) => ({
+    protocol: PROTOCOL,
+    version: PROTOCOL_VERSION,
+    method,
+    status: "error",
+    blockers: [{ code: "extension_incompatible", message, actor: "user" }],
+  });
+  if (result.error) {
+    return fail(
+      `the '${request.extensionId ?? "installed"}' extension could not be run (${result.error.code ?? result.error.message}).`,
+    );
+  }
+  if (result.status !== 0) {
+    const detail = String(result.stderr ?? "").trim().split("\n").slice(-1)[0] ?? "";
+    return fail(
+      `the '${request.extensionId ?? "installed"}' extension exited ${result.status}${detail ? `: ${detail}` : ""}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(String(result.stdout ?? ""));
+  } catch {
+    return fail(
+      `the '${request.extensionId ?? "installed"}' extension did not answer ${method} with JSON.`,
+    );
+  }
+  return normalizeResponse(parsed, method);
+}
+
+/** Fill in the fields a lenient implementation may omit, and reject a wrong shape. */
+export function normalizeResponse(parsed, method) {
+  const status = STATUSES.includes(parsed?.status) ? parsed.status : "error";
+  const blockers = (Array.isArray(parsed?.blockers) ? parsed.blockers : [])
+    .filter((b) => b && typeof b.code === "string")
+    .map((b) => ({
+      code: b.code,
+      message: typeof b.message === "string" ? b.message : b.code,
+      actor: b.actor === "agent" ? "agent" : "user",
+      detail: b.detail ?? null,
+    }));
+  return {
+    protocol: PROTOCOL,
+    version: Number(parsed?.version) === PROTOCOL_VERSION ? PROTOCOL_VERSION : parsed?.version ?? null,
+    method,
+    status,
+    dataVersion: parsed?.dataVersion ?? null,
+    blockers:
+      status === "ok" || blockers.length
+        ? blockers
+        : [
+            {
+              code: status === "unsupported" ? "extension_incompatible" : "validation_required",
+              message: typeof parsed?.message === "string" ? parsed.message : `${method} did not pass`,
+              actor: "user",
+              detail: null,
+            },
+          ],
+    artifacts: Array.isArray(parsed?.artifacts) ? parsed.artifacts : [],
+    hydrate: parsed?.hydrate ?? null,
+    context: parsed?.context ?? null,
+    contextDigest: typeof parsed?.contextDigest === "string" ? parsed.contextDigest : null,
+    evidence: parsed?.evidence ?? null,
+    message: typeof parsed?.message === "string" ? parsed.message : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// containment — where a declared artifact may and may not live
+// ---------------------------------------------------------------------------
+
+// Executable suffixes: an artifact that lands on one of these is a program this
+// machine might later run, which is not what "the deck's approved workbook" is.
+const EXECUTABLE = /\.(mjs|cjs|js|ts|sh|bash|zsh|ps1|psm1|bat|cmd|com|exe|dll|dylib|so|py|rb|pl|scpt|app)$/i;
+
+// Directories the CLI's own protocols own. An extension writing here could
+// forge an accepted base, a receipt or an owner token.
+const RESERVED_DIRS = ["state", "slides", "conversions"];
+
+/** Isolated storage for anything that failed containment — never overwrites, never runs. */
+export function recoveryDir(workspaceDir, extensionId) {
+  return path.join(workspaceDir, "state", "recovery", sanitizeSegment(extensionId));
+}
+
+function sanitizeSegment(value) {
+  return String(value ?? "unknown").replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "") || "unknown";
+}
+
+// A path is inside `root` only if every step of the way is a real directory, not
+// a symlink: resolving the final path alone would happily follow a symlink that
+// points out of the deck and report a contained answer.
+function traversesSymlink(root, target) {
+  let current = path.resolve(target);
+  const stop = path.resolve(root);
+  while (current !== stop && current.startsWith(stop)) {
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) return true;
+    } catch {
+      /* not there yet — a path that does not exist cannot be a symlink */
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return false;
+}
+
+/**
+ * Where an artifact the extension declared may actually live, and why not.
+ *
+ * Returns `{ ok: true, path }` or `{ ok: false, why, recovery }` — the second
+ * form still carries a usable destination, because a refused placement must not
+ * lose the bytes; it isolates them.
+ */
+export function resolveArtifactPath(workspaceDir, artifact) {
+  const root = path.resolve(deckRoot(workspaceDir));
+  const recovery = path.join(
+    recoveryDir(workspaceDir, artifact?.extensionId ?? "unknown"),
+    sanitizeSegment(artifact?.artifactId),
+  );
+  const raw = artifact?.localPath;
+  if (typeof raw !== "string" || !raw) {
+    return { ok: false, why: "the artifact declares no localPath", recovery };
+  }
+  if (path.isAbsolute(raw)) {
+    return { ok: false, why: "an artifact's localPath must be relative to the deck", recovery };
+  }
+  const target = path.resolve(workspaceDir, raw);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    return { ok: false, why: "it resolves outside the deck", recovery };
+  }
+  const relToWorkspace = path.relative(workspaceDir, target).split(path.sep);
+  if (RESERVED_DIRS.includes(relToWorkspace[0])) {
+    return {
+      ok: false,
+      why: `\`${relToWorkspace[0]}/\` belongs to the CLI's own revision protocol`,
+      recovery,
+    };
+  }
+  if (EXECUTABLE.test(target)) {
+    return { ok: false, why: "an artifact may not be an executable file", recovery };
+  }
+  if (traversesSymlink(root, target)) {
+    return { ok: false, why: "its path traverses a symlink", recovery };
+  }
+  return { ok: true, path: target };
+}
+
+/**
+ * Read a manifest's artifacts into the shape the publisher works with: one entry
+ * per artifact with its resolved local file, its hash as it is on disk RIGHT NOW,
+ * and whether it may be uploaded.
+ *
+ * This is also the upload allowlist. Only files an extension DECLARED are
+ * candidates — never a glob over the workspace, never a recursive walk. A deck
+ * directory holds the user's scratch, their source corpus and whatever else they
+ * dropped in; uploading it because a manifest said "the deck" would be a data
+ * leak with a progress bar.
+ */
+export function collectManifest(workspaceDir, response, { extensionId }) {
+  const artifacts = [];
+  const problems = [];
+  for (const declared of response.artifacts ?? []) {
+    // The declaring extension wins: `extensionId` here is only the fallback for
+    // a single-extension call that did not tag its own artifacts.
+    const artifact = { ...declared, extensionId: declared.extensionId ?? extensionId };
+    const placement = resolveArtifactPath(workspaceDir, artifact);
+    if (!placement.ok) {
+      problems.push(`${artifact.artifactId ?? "(unnamed)"}: ${placement.why}`);
+      artifacts.push({ ...artifact, uploadable: false, refused: placement.why, recovery: placement.recovery });
+      continue;
+    }
+    if (!fs.existsSync(placement.path)) {
+      problems.push(`${artifact.artifactId ?? "(unnamed)"}: ${declared.localPath} is not on disk`);
+      artifacts.push({ ...artifact, uploadable: false, refused: "missing", file: placement.path });
+      continue;
+    }
+    const digest = sha256File(placement.path);
+    if (artifact.sha256 && artifact.sha256 !== digest) {
+      // Declared hash vs. bytes on disk. The bytes win for uploading, but the
+      // disagreement is reported: an extension that hashed a file it then
+      // rewrote is about to pair the deck with content nobody checked.
+      problems.push(
+        `${artifact.artifactId}: declared sha256 does not match the file on disk`,
+      );
+    }
+    artifacts.push({
+      ...artifact,
+      file: placement.path,
+      sha256: digest,
+      bytes: fs.statSync(placement.path).size,
+      uploadable: true,
+    });
+  }
+  return { artifacts, problems };
+}
+
+/**
+ * Write a hydrated artifact into the workspace, or into isolated recovery
+ * storage when it fails containment. Never overwrites a file whose bytes already
+ * match — identical durable content is reused, so a hydrate does not churn the
+ * deck's dirty set.
+ */
+export function materializeArtifact(workspaceDir, artifact, bytes) {
+  const placement = resolveArtifactPath(workspaceDir, artifact);
+  const target = placement.ok ? placement.path : placement.recovery;
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (artifact.sha256 && artifact.sha256 !== digest) {
+    const e = new Error(
+      `${artifact.artifactId}: the bytes fetched do not hash to the ref's sha256 — not written`,
+    );
+    e.code = "artifact_hash_mismatch";
+    throw e;
+  }
+  let existing = null;
+  try {
+    existing = sha256File(target);
+  } catch {
+    /* not there */
+  }
+  if (existing === digest) return { path: target, written: false, isolated: !placement.ok };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, bytes);
+  return {
+    path: target,
+    written: true,
+    isolated: !placement.ok,
+    why: placement.ok ? null : placement.why,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the orchestration one caller does over several extensions
+// ---------------------------------------------------------------------------
+
+/**
+ * Run one method across every extension a context declares.
+ *
+ * Returns `{ results, blockers, missing }`. A REQUIRED extension that is missing
+ * or incompatible contributes a blocker; an optional one is simply skipped —
+ * inspection and local recovery must keep working on a machine that does not
+ * have every pack a deck has ever met.
+ */
+export function runDeclared(workspaceDir, declarations, method, requestFields = {}) {
+  const registry = readRegistry();
+  const results = [];
+  const blockers = [];
+  const missing = [];
+  for (const declaration of declarations ?? []) {
+    const { id, entry, blocker } = resolveExtension(declaration, registry);
+    if (!entry) {
+      missing.push({ id, required: declaration?.required !== false, blocker });
+      if (declaration?.required !== false) blockers.push({ ...blocker, extensionId: id });
+      continue;
+    }
+    const request = buildRequest({ method, workspaceDir, declaration, ...requestFields });
+    const response = callExtension(entry, method, request);
+    results.push({ id, declaration, request, response });
+    if (response.status !== "ok" && declaration?.required !== false) {
+      blockers.push(...response.blockers.map((b) => ({ ...b, extensionId: id })));
+    }
+  }
+  return { results, blockers, missing };
+}