@tapcue/extension-sdk 0.1.0

package/src/manifest.ts

@@ -0,0 +1,1572 @@
+/**
+ * Manifest types and the non-executing validator.
+ *
+ * The manifest is readable without running any JavaScript: static commands,
+ * their arguments, settings, and the permission upper bound all come from here.
+ * `validateManifest` is the executable spec — the installer (Rust) must reject
+ * exactly what this rejects.
+ */
+
+import type { JsonValue } from "./json.js";
+import {
+  CONTRIBUTABLE_SCOPE_TYPES,
+  CONTRIBUTION_MATCH_FIELDS,
+  isContributableScopeType,
+} from "./types.js";
+import type { ContributableScopeType } from "./types.js";
+import {
+  BOOLEAN_PERMISSION_GROUPS,
+  FLAG_PERMISSION_UNITS,
+  PERMISSION_UNITS,
+} from "./permission-units.js";
+
+export type { PermissionUnit } from "./permission-units.js";
+import { HEX_COLOR_PATTERN } from "./scene.js";
+
+export const MANIFEST_SCHEMA_VERSION = 1;
+export const SDK_API_VERSION = "1.0";
+
+/**
+ * The action id a `no-view` command is invoked with when the user runs its row.
+ *
+ * A `view` command names its action per item (`CommandItem.defaultActionId`), but a
+ * `no-view` command *is* its action: its row comes from the manifest, so there is no
+ * item to carry an id. Core routes Enter on that row to `invoke` with this reserved
+ * id. Further actions on the row (the ⌘K panel) still use their own ids.
+ */
+export const DEFAULT_ACTION_ID = "default";
+
+/** The names from the capability table. One unit, one all-or-nothing approval. */
+export type PackageType = "commands" | "skill" | "extension" | "script";
+export type RuntimeId = "deno";
+
+export interface ExtensionManifest {
+  schemaVersion: 1;
+  type: PackageType;
+  runtime?: RuntimeId;
+  id: string;
+  /** A leading `@` makes any user-facing string a catalog key; see `i18n.ts`. */
+  name: string;
+  description: string;
+  version: string;
+  engines: { tapcue: string };
+  /** SDK API version range the bundle was built against (`extension` type only). */
+  api?: string;
+  entry?: string;
+  /** Catalog used when the user's locale has none. Defaults to `en`. */
+  defaultLocale?: string;
+  /**
+   * The extension's icon, and the fallback for any command that declares none.
+   * It is in the manifest because a command row must be drawable — icon included —
+   * without executing a line of the extension's code.
+   */
+  icon?: string;
+  /**
+   * **The apps this extension integrates with**, by bundle identifier (spec 016 §1).
+   *
+   * One declaration, four uses: `contributes[].when.bundleId` may only name apps from here; a
+   * `files.read` grant's `container` root is resolved under one of them; an `exec` grant's `inApp`
+   * binary is resolved inside one of their bundles; and `native.open` will accept a custom scheme
+   * only when the system's handler for it *is* one of them.
+   *
+   * That is the same rule §11.3 runs on — **the extension names a kind, the host decides the
+   * location** — so an extension can never write an absolute path, name somebody else's bundle, or
+   * hand a URL to an app it did not disclose. And the install sheet says it once ("Works with
+   * 1Password") instead of four times in four vocabularies.
+   *
+   * Absent or empty for almost every extension. The forms above simply become undeclarable.
+   */
+  integratesWith?: string[];
+  commands: ManifestCommand[];
+  /**
+   * **Rows this extension adds to scopes it does not own** (architecture §11.3) — the third
+   * right over a scope, next to owning one and producing an item that enters one.
+   *
+   * In the manifest and not in code, for the same reason commands are: the user enters the
+   * scope, so Tapcue must know who to ask *without executing anything*. Entering an app's scope
+   * must no more run every installed extension than opening root search does. A scope the
+   * extension **owns** is the opposite case — reachable only through a row it produced — and
+   * stays in code (`defineScope`).
+   */
+  contributes?: ManifestContribution[];
+  /**
+   * **Slots this extension fills** — the mirror image of `contributes`.
+   *
+   * A contribution adds the extension's rows to a place Tapcue owns. A provision answers a
+   * *question* Tapcue asks: a slot is a named question with a fixed answer shape, and the host
+   * calls whoever declared it, when it needs the answer, and merges what comes back with its own.
+   *
+   * In the manifest for the same reason contributions are: the host has to know who to ask before
+   * anything has run. It asks when the panel opens, not on a keystroke — so the answer is a query,
+   * never an effect, and a slow one is simply late rather than felt.
+   */
+  provides?: ManifestProvision[];
+  settings?: ManifestSetting[];
+  /**
+   * **When this extension's own rows should be suggested** (spec 018 §8), in the rule DSL.
+   *
+   * A string, or an array of strings joined by newlines — JSON has no block literal, and a rule is
+   * three lines:
+   *
+   * ```json
+   * "suggestionRules": [
+   *   "rule mail-reply (origin: extension \"com.example.ai-mail\"):",
+   *   "  when frontmost(\"com.apple.mail\")",
+   *   "  emit boost(own(\"reply-with-ai\"), lift: 1.4)"
+   * ]
+   * ```
+   *
+   * Declared rather than called for three reasons: it is reviewable at install ("this extension
+   * suggests when Mail is frontmost"), the host evaluates it with **zero isolate wake** — the
+   * extension runs only when its suggestion is actually picked — and it can be permission-gated
+   * (`permissions.suggestions.rules`) like anything else. `own(...)` names one of this manifest's
+   * own command ids; the host expands it, clamps every lift to the extension tier's [1, 1.5], and
+   * refuses anything aimed at somebody else's rows. The grammar is the host's: this side checks
+   * only that the field is text and that there is not too much of it.
+   */
+  suggestionRules?: string | string[];
+  /**
+   * Capabilities the extension cannot work without. Denying one means the
+   * extension is not enabled — so at runtime a required capability is always
+   * there, and extension code never checks for it.
+   */
+  permissions?: ManifestPermissions;
+  /**
+   * Capabilities the extension can do without. The user may deny any of them, and
+   * then the capability (or the individual method) is absent from the invocation
+   * context. An extension **must** stay useful without every one of these.
+   *
+   * A capability unit appears in exactly one of the two blocks — approval is
+   * all-or-nothing per unit, so `http`'s host list is not separately approvable.
+   */
+  optionalPermissions?: ManifestPermissions;
+}
+
+/**
+ * One contribution: a native scope, which of its subjects, and the rows to add there.
+ *
+ * ```json
+ * { "id": "vault-items",
+ *   "scope": "application",
+ *   "when": { "bundleId": ["com.1password.1password"] },
+ *   "title": "@contributes.vault-items.title" }
+ * ```
+ */
+export interface ManifestContribution {
+  /**
+   * Stable, kebab-case, unique inside the extension — and distinct from every command id, since
+   * both name rows the user can end up standing on. The key its handler is registered under in
+   * `defineExtension({ contributions })`.
+   */
+  id: string;
+  /** The native scope type to contribute into; one of `CONTRIBUTABLE_SCOPE_TYPES`. */
+  scope: ContributableScopeType;
+  /**
+   * **Which subjects — required, and exhaustive.**
+   *
+   * A map from a subject field to the values that match it, compared case-insensitively as whole
+   * strings. Only the fields in `CONTRIBUTION_MATCH_FIELDS` for that scope type, and at least
+   * one of them: a wildcard contribution to `application` would mean "tell me every app you
+   * ever open", which is not what any real contribution needs and is not a thing this manifest
+   * can ask for. Several fields is an AND; several values in one field is an OR.
+   *
+   * This is both the gate and the disclosure. Tapcue matches it in its own process, so a
+   * subject the predicate does not accept never reaches the extension — and the installer can
+   * say exactly where the rows will appear, read straight off the manifest.
+   */
+  when: Record<string, string[]>;
+  /**
+   * What to call this group of rows where the user decides about it — the install sheet's
+   * "Adds items to" line. Localizable (`@key`). It is not the rows' facet title: rows carry
+   * their own facet, because a contribution may section its rows however it likes.
+   */
+  title: string;
+}
+
+/**
+ * One provision: which slot, and the handler that answers it.
+ *
+ * ```json
+ * { "id": "codex-projects", "slot": "workspace.roots", "title": "@provides.codex-projects.title" }
+ * ```
+ */
+export interface ManifestProvision {
+  /**
+   * Stable, kebab-case, unique inside the extension. The key its handler is registered under in
+   * `defineExtension({ provisions })`.
+   */
+  id: string;
+  /** Which slot it fills; one of `SLOT_TYPES`. */
+  slot: SlotType;
+  /**
+   * What to call it where the user decides about it. Localizable (`@key`). The slot's permission
+   * unit is what grants it; this is what the install sheet reads out beside that unit, because
+   * "may tell Tapcue where you work" is a sentence that needs a *who*.
+   */
+  title: string;
+}
+
+/**
+ * The slots a provision may fill. One entry today.
+ *
+ * `workspace.roots` — the project folders the user works in. Tapcue joins a relative path typed
+ * into home (`apps/api/config.ts`, pasted out of a terminal or a diff) against them, alongside the
+ * folder the frontmost app is showing. An extension that already knows which projects a tool is
+ * open on is the only thing that knows this; the launcher cannot read it out of the app.
+ */
+export const SLOT_TYPES = ["workspace.roots"] as const;
+export type SlotType = (typeof SLOT_TYPES)[number];
+
+export interface ManifestCommand {
+  id: string;
+  title: string;
+  description: string;
+  mode: "view" | "no-view";
+  /**
+   * How Tapcue sources this command's rows. Required for `mode: "view"`, and
+   * meaningless — so rejected — for `mode: "no-view"`: a command with no `query`
+   * handler has no query to schedule.
+   */
+  queryMode?: "catalog" | "remote";
+  /** Defaults to the extension's icon. */
+  icon?: string;
+  keywords?: string[];
+  /**
+   * Free-text arguments the command accepts after its keyword. Tapcue parses
+   * them (keyword stripping is the core's job) and hands them to the extension
+   * in `QueryRequest.arguments`.
+   */
+  arguments?: ManifestArgument[];
+  /** Required for `queryMode: "remote"`; see `ActivationPolicy`. */
+  activation?: ActivationPolicy;
+  /** What this command's surface takes in its query field; see `CommandInput`. */
+  input?: CommandInput;
+  /** How the command's own surface is laid out; see `CommandSurface`. */
+  surface?: CommandSurface;
+}
+
+/**
+ * How a command's **own** surface is laid out.
+ *
+ * Scopes are declared in code because a scope is only reachable through an item the extension
+ * produced, so nothing about it is knowable until the extension has run. A command's own surface
+ * (§23.10 — a no-argument `view` command's row *enters* it) is the exception: it is reached from
+ * the static manifest row, stamped before any code runs, and was therefore always a `list`. What is
+ * knowable without executing anything belongs in the manifest, so it lives here.
+ */
+export interface CommandSurface {
+  /**
+   * `list` (the default) or `grid`. A `grid` carries the chip row, and its chips are the surface's
+   * own facet sections — so a grid that groups its rows gets tabs without asking twice.
+   *
+   * The rowless layouts are absent on purpose: `canvas` and `pane` are filled by a *handler*, which
+   * is code, so they stay where code is.
+   */
+  layout?: "list" | "grid";
+}
+
+/**
+ * What a command's query field takes — **a description, not a request**.
+ *
+ * A colour command's field wants a colour, and the colour someone is about to type is very often
+ * already on their clipboard. An extension cannot read the clipboard (`clipboard.read` would hand
+ * over every password a manager last copied, for this) and cannot draw in the query field
+ * (extension-ui §2). So it says what belongs there, and Tapcue — which owns the clipboard, the
+ * field and the keyboard — decides whether it has something worth offering, shows it as ghost text,
+ * and completes it on Tab.
+ *
+ * **The extension learns nothing until the value is accepted.** No Tab, no query, no value: the
+ * suggestion is the shell's, and the first the extension hears of it is an ordinary `query` call
+ * carrying text the user chose to accept.
+ */
+export interface CommandInput {
+  /**
+   * Native subject types Tapcue knows how to recognise a value of. `"color"` today, and the union
+   * is closed on purpose: a type the shell cannot *find* is a suggestion it can never make, and a
+   * field that quietly accepts one is a promise nothing keeps.
+   */
+  accepts?: "color"[];
+  /**
+   * A regular expression a candidate must match, for input the shell has no type for — an issue
+   * key, a tracking number, a coupon code. Tested against the clipboard's text only, and only when
+   * that text is short (the host caps it, because this pattern runs in the launcher's process).
+   * Anchor it: `^…$` is almost always what you mean.
+   */
+  pattern?: string;
+  /**
+   * May Tapcue put a value in the field? **Off by default.** Describing the input is one decision;
+   * letting the shell fill it in is another, and a command should not get the second by forgetting
+   * to say.
+   */
+  autocomplete?: boolean;
+}
+
+export interface ManifestArgument {
+  name: string;
+  title: string;
+  placeholder?: string;
+  type: "text";
+  required?: boolean;
+}
+
+/**
+ * When Tapcue is allowed to run this command's `query`.
+ *
+ * Note what is *not* here: debounce. How often a keystroke turns into work is a
+ * UI-responsiveness decision, it must be uniform across every provider, and it is
+ * not something a third party gets to set for the launcher it is running inside.
+ * Core debounces, core cancels the previous generation, and the shell streams
+ * whatever arrives. The fields below are consent (`runsAtRoot`), a floor the
+ * extension asks for its own backing service (`minQueryLength`), and limits that
+ * may only ever narrow the host's own (`deadlineMs`, `maxResults`).
+ */
+export interface ActivationPolicy {
+  /**
+   * Run the command's `query` as soon as root search opens, with no query text —
+   * the opt-in that lets a row show live data (weather, unread count) in root.
+   * Off by default: opening root search must not execute every extension.
+   */
+  runsAtRoot?: boolean;
+  /** Do not call me with fewer characters than this. Core may still be lazier. */
+  minQueryLength?: number;
+  /** Narrower than the host's limit only; the host cap always wins. */
+  deadlineMs?: number;
+  maxResults?: number;
+}
+
+export type ManifestSetting =
+  | { key: string; type: "string"; title: string; description?: string; default: string }
+  | { key: string; type: "number"; title: string; description?: string; default: number }
+  | { key: string; type: "boolean"; title: string; description?: string; default: boolean }
+  | {
+      key: string;
+      type: "select";
+      title: string;
+      description?: string;
+      default: string;
+      options: { value: string; title: string }[];
+    };
+
+/**
+ * **One place the extension may read** (spec 016 §2). Read-only, and the host resolves the location.
+ *
+ * Two forms, and the second exists because most apps do not name their data directory after their
+ * bundle id (`~/Library/Application Support/Code/`, `~/.config/op/`), so container derivation alone
+ * would cover almost nothing:
+ *
+ * - **`container`** — a subpath inside the container of an app from `integratesWith`. The extension
+ *   never writes the root, so it cannot climb out of it.
+ * - **`root` + `path`** — a *named* root from `proto/extension-roots.json` plus a literal subpath.
+ *   The root is a namespace selector, not the grant.
+ *
+ * `match` globs **leaf names only**. `path` may not contain wildcards or `..`. The host re-checks
+ * the resolved real path on every read, because a symlink inside the tree leads out of it.
+ */
+export type FileReadGrant =
+  | { container: string; match?: string; root?: never; path?: never }
+  | { root: FileRoot; path: string; match?: string; container?: never };
+
+/** Named roots a `files.read` grant may anchor to. The table lives in `proto/extension-roots.json`. */
+export const FILE_ROOTS = ["containers", "appSupport", "preferences", "configHome", "toolHome"] as const;
+export type FileRoot = (typeof FILE_ROOTS)[number];
+
+/**
+ * What `path` must look like under each root — the other half of `proto/extension-roots.json`.
+ *
+ * `toolHome` resolves *at* the home directory, which every other rule here exists to prevent, and
+ * `dot-segment` is what buys it back: exactly one segment, and it must begin with a dot. So
+ * `~/.codex` is declarable and `~/Documents` is not, and the install sheet's sentence stays one a
+ * person can evaluate. Command-line tools keep their state in `~/.codex`, `~/.claude`, `~/.aws` —
+ * a convention as settled as `Library/Application Support`, and one no other root can reach.
+ */
+export const ROOT_PATH_SHAPES: Record<FileRoot, "subpath" | "dot-segment"> = {
+  containers: "subpath",
+  appSupport: "subpath",
+  preferences: "subpath",
+  configHome: "subpath",
+  toolHome: "dot-segment",
+};
+
+/**
+ * **One stored query the extension may run.**
+ *
+ * The shape of `files.read` applied to a database: the extension declares *where* and *what to ask*
+ * at install time, and at runtime supplies only the values that fill the statement's `?` holes. It
+ * never sees a path, never sees a connection, and cannot compose SQL — exactly as `exec`'s argv
+ * template means it cannot compose a command line.
+ *
+ * This exists because a whole class of integration keeps its state in SQLite and nowhere else, and
+ * neither of the other two reaches it: `files.read` hands over bytes an extension would need a
+ * database engine to interpret (and the sandbox has no WebAssembly to bring one), while `exec`
+ * needs the app to have shipped a CLI that answers the question, which Codex — the extension that
+ * prompted this — does not. Handing over rows instead of bytes keeps the engine, the file handle
+ * and the write path on Tapcue's side of the boundary.
+ *
+ * The host opens the database **read-only** and refuses a statement that is not a single read: one
+ * statement, no semicolon, `SELECT`/`WITH` only, and SQLite's own `readonly` verdict on the
+ * prepared statement is the second door.
+ */
+export interface QueryGrant {
+  /** Stable id the extension calls it by. Unique inside the manifest. */
+  id: string;
+  /** A named root, same vocabulary as `FileReadGrant`. */
+  root: FileRoot;
+  /** A literal subpath under that root, shaped by `ROOT_PATH_SHAPES`. */
+  path: string;
+  /** The database's leaf name inside that directory. One named file — no globs. */
+  database: string;
+  /** The statement, fixed here. `?` for each value supplied at call time, in order. */
+  sql: string;
+}
+
+/**
+ * **One binary the extension may run** (spec 016 §3), identified by *what it is* rather than by
+ * where it sits — a path is user-configurable, and "run the program at this path" is "run anything".
+ *
+ * - **`identifier` + `team`** — an external binary, checked against its code signature. The host
+ *   resolves the path from its own search list; the extension never supplies one.
+ * - **`inApp` + `executable`** — a binary inside the bundle of an app from `integratesWith`. The
+ *   bundle is the identity, so no signature declaration is needed.
+ *
+ * **`args` is a template, and it is required.** Holes are `{}`, filled positionally at call time
+ * from `ctx.exec.run(id, [...])`; a hole is always exactly one argv element, never split and never
+ * shell-interpreted. The template is what makes a later policy possible at all — "no write
+ * operations" is a statement about argv, and a runtime string cannot be judged. Declare one entry
+ * per shape you need.
+ *
+ * `protocol: "mcp"` runs the binary as a long-lived stdio MCP server instead: `ctx.exec.mcp(id)`
+ * hands back `listTools()` / `callTool()`, the process is reused across invocations rather than
+ * spawned per keystroke, and the install sheet can enumerate the tools. MCP is plain JSON-RPC over
+ * stdio and involves no model.
+ */
+export interface ExecGrant {
+  /** Stable id the extension calls it by. Unique inside the manifest. */
+  id: string;
+  /** External form: the binary's code-signing identifier, e.g. `com.1password.op`. */
+  identifier?: string;
+  /** External form: its Team ID, e.g. `2BUA8C4S2C`. Required with `identifier`. */
+  team?: string;
+  /** Bundle form: a bundle id from `integratesWith`. */
+  inApp?: string;
+  /**
+   * **The binary's name** — `op`, `1password-mcp`. Required for both forms.
+   *
+   * Distinct from `id`, which names the *declaration*: one binary normally carries several, because
+   * each argv shape is its own entry (`op item list`, `op read`). Conflating them sends the host
+   * looking for a file named after the declaration, which no machine has.
+   *
+   * For the bundle form it is resolved inside `Contents/MacOS`; for the external form, on the
+   * host's own search path.
+   */
+  executable?: string;
+  /** Fixed argv, with `{}` for each value supplied at call time. Omit for `protocol: "mcp"`. */
+  args?: string[];
+  /** Speak MCP to it over stdio rather than reading stdout. */
+  protocol?: "mcp";
+}
+
+export interface ManifestPermissions {
+  http?: { hosts: string[] };
+  storage?: { maxBytes: number };
+  cache?: { maxBytes: number };
+  /** Where the extension may read. See `FileReadGrant`; spec 016 §2. */
+  files?: { read: FileReadGrant[] };
+  /** Which binaries it may run. See `ExecGrant`; spec 016 §3. */
+  exec?: ExecGrant[];
+  /** Which stored statements it may run. See `QueryGrant`. */
+  queries?: QueryGrant[];
+  secrets?: { names: string[] };
+  clipboard?: { read?: boolean; write?: boolean };
+  /** Tapcue's unified Recents: `record` files a produced item (scope-entry only — the host
+   * stamps the extension's identity and drops any action), `list` reads back this
+   * extension's own records (never anyone else's), `remove` drops one it recorded. */
+  recents?: { record?: boolean; list?: boolean; remove?: boolean };
+  /**
+   * Fill Tapcue's `workspace.roots` slot: answer, when asked, which project folders the user works
+   * in. Tapcue joins a relative path typed into home against them, so a root is a claim about where
+   * the user's files are — the host still requires each one to exist, to be a directory, and to sit
+   * under the user's home, and every row built from one shows the full path it landed on.
+   */
+  workspace?: { roots?: boolean };
+  /**
+   * The situation that summoned Tapcue: the frontmost app, the selection, the highlighted
+   * files. Invocation-scoped facts, and only those — machine-wide queries live below.
+   */
+  context?: {
+    frontmostApp?: boolean;
+    selectedText?: boolean;
+    selectedFiles?: boolean;
+  };
+  /**
+   * Enumerate the fonts installed on this machine. A platform-API read (CoreText /
+   * DirectWrite / fontconfig), never a filesystem walk. Includes each family's file path and
+   * name-table metadata: an installed extension the user granted this to is asking exactly
+   * "which fonts do I have, and where did this one come from".
+   */
+  fonts?: boolean;
+  /**
+   * Where the machine is. Promoted out of `context.*`: a position is true whether or not
+   * anyone opened the launcher, so it is a machine fact, not an invocation fact.
+   */
+  location?: { precision: "coarse" | "precise" };
+  /**
+   * The processes running on this machine. Enumeration is a platform API a sandboxed guest
+   * cannot reach (no child process, no `/proc`), so the host supplies it — like `fonts`.
+   *
+   * - `list` — the benign read: name, pid, cpu, memory, listening ports.
+   * - `command` — adds argv (`ProcessInfo.command`) to the read. Its own toggle because a command
+   *   line routinely carries secrets; `list` without `command` is the safe default. Requires `list`.
+   * - `kill` — the manage effect (`kill` + `activate`), action-only. Requires `list`. It carries no
+   *   pid scope; the host-owned confirm dialog is the boundary.
+   */
+  process?: { list?: boolean; command?: boolean; kill?: boolean };
+  /**
+   * `notify` posts a notification (unsolicited), and `save` writes one file to a user-visible
+   * location (Downloads) that the host — never the extension — names and sanitizes. `open` and
+   * `reveal` are **not** here: they are ambient action-only effects needing no grant (see
+   * `PermissionUnit`), so an extension does not declare them and the user does not approve them.
+   */
+  native?: { notify?: boolean; save?: boolean };
+  /**
+   * The screen (architecture §9.4). `overlay` draws and receives pointer input and grants
+   * no pixel access at all; `capture` reads pixels and is the Screen Recording permission
+   * in everything but name. A ruler asks for the first and never the second.
+   */
+  screen?: { overlay?: boolean; capture?: boolean };
+  /**
+   * A panel-hosted WebView surface (architecture §12.1). It is the deliberate escape hatch
+   * for UI the semantic scene vocabulary cannot express — a drawing canvas is the first one
+   * that needs it. Reviewed at a higher trust tier: the surface runs the extension's own
+   * HTML/JS, so it is not "describe, the shell renders" — it is the exception the rest of
+   * the UI contract is defined against. The surface still has zero network (`connect-src
+   * 'none'`), loads only package assets, and can never cover Tapcue's own chrome.
+   */
+  ui?: { webview?: boolean };
+  /**
+   * **Stay loaded between calls.** Without it the isolate is torn down when Tapcue is done with
+   * it, and that is the design rather than a memory optimization: an isolate that does not survive
+   * a call cannot hold anything across one. With it the isolate lives, and the runtime's phase
+   * check is what makes stashing a capability pointless instead of impossible.
+   */
+  background?: boolean;
+  /**
+   * **Let the manifest's `suggestionRules` take part in the suggestion band** (spec 018 §8).
+   *
+   * The one unit the extension's own code never touches: the rules are text in the manifest, and
+   * the *host* parses, clamps and evaluates them — no isolate is woken to produce a suggestion, and
+   * the extension runs only once the user picks one. Withdrawing it drops that extension's rules
+   * and nothing else, which is why it is a unit rather than a side effect of being installed.
+   */
+  suggestions?: { rules?: boolean };
+}
+
+/* ------------------------------------------------------------ validation --- */
+
+export interface ManifestProblem {
+  path: string;
+  message: string;
+}
+
+/** Same grammar the shell resolves at runtime; see `scene.ts`. */
+export function iconProblem(icon: unknown): string | undefined {
+  if (typeof icon !== "string") return "must be a string";
+  if (icon === "extension" || icon.startsWith("symbol:")) return undefined;
+  if (icon.startsWith("color:")) {
+    return HEX_COLOR_PATTERN.test(icon.slice("color:".length))
+      ? undefined
+      : "colour chip must be color:#RRGGBB";
+  }
+  // A specimen tile drawn in the named family — the font counterpart of a `color:` chip. The
+  // family is untrusted text here; the shell resolves it and falls back if it is not installed,
+  // exactly as it does for an unresolvable `asset:`.
+  if (icon.startsWith("font:")) {
+    return icon.slice("font:".length).trim() === ""
+      ? "font specimen must name a family, e.g. font:Helvetica Neue"
+      : undefined;
+  }
+  // The running process's app icon, resolved by the shell from the pid — no bytes cross to the
+  // extension. The pid is untrusted; the shell degrades to a generic glyph if it names no app.
+  if (icon.startsWith("process:")) {
+    return /^\d+$/.test(icon.slice("process:".length))
+      ? undefined
+      : "process icon must name a pid, e.g. process:1234";
+  }
+  // The site's own icon, fetched and cached by the shell. The host is untrusted text: it is a
+  // *name*, never a URL and never a path, so anything with a slash, a scheme, or no dot is refused
+  // here rather than handed to a fetcher to make sense of.
+  if (icon.startsWith("favicon:")) {
+    const host = icon.slice("favicon:".length).trim();
+    return /^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(host)
+      ? undefined
+      : "favicon must name a host, e.g. favicon:github.com";
+  }
+  if (!icon.startsWith("asset:")) {
+    return 'must be "extension", "symbol:<name>", "color:#RRGGBB", "font:<family>", "process:<pid>", "favicon:<host>", or "asset:<path>"';
+  }
+  const path = icon.slice("asset:".length);
+  if (path === "" || path.startsWith("/") || path.split("/").includes("..")) {
+    return "asset path must be package-relative and must not traverse";
+  }
+  return undefined;
+}
+
+const ID_PATTERN = /^[a-z0-9]+(\.[a-z0-9-]+)+$/;
+/**
+ * Somebody *else's* bundle id, which is theirs to case however they cased it: `com.apple.TextEdit`,
+ * `com.apple.Safari`, `com.microsoft.VSCode`. `ID_PATTERN` is Tapcue's house style for an
+ * extension's own id and was wrong here — it made every Apple app permanently un-integratable.
+ * What still must hold is that the string is a *name* and not a path: it is appended to
+ * `~/Library/Containers/` for a container grant, so no empty segment, no slash, no `..`.
+ */
+const BUNDLE_ID_PATTERN = /^[A-Za-z0-9]+(\.[A-Za-z0-9-]+)+$/;
+const COMMAND_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+const HOST_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+
+/**
+ * Validates a parsed manifest without executing any package code. Returns every
+ * problem it finds rather than throwing on the first, so an author sees the full
+ * list in one run.
+ */
+export function validateManifest(value: unknown): ManifestProblem[] {
+  const problems: ManifestProblem[] = [];
+  const fail = (path: string, message: string) => problems.push({ path, message });
+
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return [{ path: "", message: "manifest must be a JSON object" }];
+  }
+  const m = value as Record<string, unknown>;
+
+  if (m.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    fail("schemaVersion", `must be ${MANIFEST_SCHEMA_VERSION}`);
+  }
+
+  const types: PackageType[] = ["commands", "skill", "extension", "script"];
+  if (typeof m.type !== "string" || !types.includes(m.type as PackageType)) {
+    fail("type", `must be one of ${types.join(", ")}`);
+  }
+
+  if (typeof m.id !== "string" || !ID_PATTERN.test(m.id)) {
+    fail("id", "must be a reverse-domain identifier, e.g. com.example.weather");
+  }
+  for (const field of ["name", "description"] as const) {
+    if (typeof m[field] !== "string" || (m[field] as string).trim() === "") {
+      fail(field, "must be a non-empty string");
+    }
+  }
+  if (typeof m.version !== "string" || !SEMVER_PATTERN.test(m.version)) {
+    fail("version", "must be a semantic version, e.g. 1.0.0");
+  }
+  const engines = m.engines as { tapcue?: unknown } | undefined;
+  if (!engines || typeof engines.tapcue !== "string") {
+    fail("engines.tapcue", "must declare a Tapcue version range");
+  }
+
+  if (m.icon !== undefined) {
+    const problem = iconProblem(m.icon);
+    if (problem) fail("icon", problem);
+  }
+
+  if (m.type === "extension") {
+    if (m.runtime !== "deno") fail("runtime", 'must be "deno" for type: extension');
+    if (typeof m.api !== "string") fail("api", "must declare the SDK API range, e.g. 1.x");
+    if (typeof m.entry !== "string" || !(m.entry as string).endsWith(".js")) {
+      fail("entry", "must point at the bundled ES module, e.g. main.js");
+    }
+  }
+
+  const commands = m.commands;
+  if (!Array.isArray(commands) || commands.length === 0) {
+    fail("commands", "must declare at least one command");
+  } else {
+    const seen = new Set<string>();
+    commands.forEach((raw, index) => {
+      const path = `commands[${index}]`;
+      const c = raw as Record<string, unknown>;
+      if (typeof c.id !== "string" || !COMMAND_ID_PATTERN.test(c.id)) {
+        fail(`${path}.id`, "must be a kebab-case identifier");
+      } else if (seen.has(c.id)) {
+        fail(`${path}.id`, `duplicate command id "${c.id}"`);
+      } else {
+        seen.add(c.id);
+      }
+      if (typeof c.title !== "string" || c.title.trim() === "") fail(`${path}.title`, "required");
+      if (typeof c.description !== "string") fail(`${path}.description`, "required");
+      if (c.mode !== "view" && c.mode !== "no-view") fail(`${path}.mode`, 'must be "view" or "no-view"');
+      // A `no-view` command has no `query` handler, so it has nothing to schedule:
+      // a `queryMode` on it would be a field the host silently ignores, and a field
+      // the host silently ignores is a field an author will believe in.
+      if (c.mode === "no-view") {
+        if (c.queryMode !== undefined) {
+          fail(`${path}.queryMode`, "a no-view command has no query — omit queryMode");
+        }
+      } else if (c.queryMode !== "catalog" && c.queryMode !== "remote") {
+        fail(`${path}.queryMode`, 'must be "catalog" or "remote"');
+      }
+      if (c.icon !== undefined) {
+        const problem = iconProblem(c.icon);
+        if (problem) fail(`${path}.icon`, problem);
+      }
+      const activation = c.activation as ActivationPolicy | undefined;
+      if (c.queryMode === "remote" && !activation) {
+        fail(`${path}.activation`, "a remote command must declare its activation policy");
+      }
+      if (activation?.runsAtRoot && c.queryMode !== "remote") {
+        fail(`${path}.activation.runsAtRoot`, "only a remote command can run at root");
+      }
+      validateInput(c.input as CommandInput | undefined, `${path}.input`, fail);
+      const surface = c.surface as CommandSurface | undefined;
+      if (surface !== undefined) {
+        if (surface.layout !== undefined && surface.layout !== "list" && surface.layout !== "grid") {
+          fail(`${path}.surface.layout`, 'must be "list" or "grid"');
+        }
+        if (c.mode === "no-view") {
+          // A `no-view` command has no surface at all — its row *is* its action — so a layout on
+          // one is a field the host would ignore, which is a field an author will believe in.
+          fail(`${path}.surface`, "a no-view command has no surface");
+        }
+      }
+      const args = c.arguments;
+      if (args !== undefined) {
+        if (!Array.isArray(args)) {
+          fail(`${path}.arguments`, "must be an array");
+        } else {
+          if (args.length > 3) fail(`${path}.arguments`, "at most 3 arguments");
+          const names = new Set<string>();
+          args.forEach((rawArg, argIndex) => {
+            const a = rawArg as Record<string, unknown>;
+            const argPath = `${path}.arguments[${argIndex}]`;
+            if (typeof a.name !== "string" || !COMMAND_ID_PATTERN.test(a.name)) {
+              fail(`${argPath}.name`, "must be a kebab-case identifier");
+            } else if (names.has(a.name)) {
+              fail(`${argPath}.name`, `duplicate argument name "${a.name}"`);
+            } else {
+              names.add(a.name);
+            }
+            if (typeof a.title !== "string") fail(`${argPath}.title`, "required");
+            if (a.type !== "text") fail(`${argPath}.type`, 'must be "text"');
+          });
+          // Only the last argument may be optional: Tapcue splits trailing free
+          // text left to right, so an optional argument in the middle is ambiguous.
+          args.forEach((rawArg, argIndex) => {
+            const a = rawArg as Record<string, unknown>;
+            if (a.required !== true && argIndex < args.length - 1) {
+              fail(`${path}.arguments[${argIndex}]`, "only the last argument may be optional");
+            }
+          });
+        }
+      }
+    });
+  }
+
+  const integrates = validateIntegratesWith(m, fail);
+  validateContributes(m, integrates, fail);
+  validateProvides(m, fail);
+  for (const block of ["permissions", "optionalPermissions"] as const) {
+    validateReach(m[block] as ManifestPermissions | undefined, block, integrates, fail);
+  }
+
+  const settings = m.settings;
+  if (settings !== undefined) {
+    if (!Array.isArray(settings)) {
+      fail("settings", "must be an array");
+    } else {
+      const keys = new Set<string>();
+      settings.forEach((raw, index) => {
+        const s = raw as Record<string, unknown>;
+        const path = `settings[${index}]`;
+        if (typeof s.key !== "string" || s.key.trim() === "") fail(`${path}.key`, "required");
+        else if (keys.has(s.key)) fail(`${path}.key`, `duplicate setting key "${s.key}"`);
+        else keys.add(s.key);
+        if (typeof s.title !== "string") fail(`${path}.title`, "required");
+        if (s.default === undefined) fail(`${path}.default`, "every setting must declare a default");
+        if (s.type === "select") {
+          const options = s.options;
+          if (!Array.isArray(options) || options.length === 0) {
+            fail(`${path}.options`, "a select setting must declare options");
+          } else if (!options.some((o) => (o as { value?: unknown }).value === s.default)) {
+            fail(`${path}.default`, "default must be one of the declared options");
+          }
+        } else if (!["string", "number", "boolean"].includes(s.type as string)) {
+          fail(`${path}.type`, 'must be "string", "number", "boolean", or "select"');
+        }
+      });
+    }
+  }
+
+  validateSuggestionRules(m.suggestionRules, fail);
+
+  const required = m.permissions as ManifestPermissions | undefined;
+  const optional = m.optionalPermissions as ManifestPermissions | undefined;
+  for (const [block, permissions] of [
+    ["permissions", required],
+    ["optionalPermissions", optional],
+  ] as const) {
+    if (!permissions) continue;
+    if (permissions.http) {
+      const hosts = permissions.http.hosts;
+      if (!Array.isArray(hosts) || hosts.length === 0) {
+        fail(`${block}.http.hosts`, "must list at least one host");
+      } else {
+        hosts.forEach((host, index) => {
+          if (typeof host !== "string" || !HOST_PATTERN.test(host)) {
+            fail(`${block}.http.hosts[${index}]`, "must be a bare host name, no scheme or path");
+          }
+        });
+      }
+    }
+    const precision = permissions.location?.precision;
+    if (precision !== undefined && precision !== "coarse" && precision !== "precise") {
+      fail(`${block}.location.precision`, 'must be "coarse" or "precise"');
+    }
+  }
+
+  // Approval is all-or-nothing per unit, so a unit cannot be required *and*
+  // optional — there would be no way for the user, or the extension, to say which.
+  const requiredUnits = permissionUnits(required);
+  for (const unit of permissionUnits(optional)) {
+    if (requiredUnits.has(unit)) {
+      fail(`optionalPermissions.${unit}`, `"${unit}" is already declared as required`);
+    }
+  }
+
+  // `process.command` (argv) and `process.kill`/`activate` both operate on what the read returns:
+  // neither is meaningful without `process.list`, and the runtime keys the whole `ctx.process`
+  // object on the read being granted, so the type's `WritableProcessManager extends
+  // ReadonlyProcessManager` only holds if `list` is always there when the object is.
+  const declaredUnits = new Set([...requiredUnits, ...permissionUnits(optional)]);
+  // Rules with no unit behind them are text the host reads and throws away (spec 018 §8), and a
+  // field the host silently ignores is a field an author will believe in. The host says the same
+  // thing again at load, in its log — this one is just early enough to fix before shipping.
+  if (m.suggestionRules !== undefined && !declaredUnits.has("suggestions.rules")) {
+    fail("suggestionRules", 'needs the "suggestions.rules" permission, or nothing loads them');
+  }
+  for (const unit of ["process.command", "process.kill"] as const) {
+    if (declaredUnits.has(unit) && !declaredUnits.has("process.list")) {
+      const block = requiredUnits.has(unit) ? "permissions" : "optionalPermissions";
+      fail(`${block}.process`, `"${unit}" needs "process.list" — you cannot manage what you cannot read`);
+    }
+  }
+
+  return problems;
+}
+
+/** The names from the capability table that this permission block grants. */
+export function permissionUnits(permissions: ManifestPermissions | undefined): Set<string> {
+  const units = new Set<string>();
+  if (!permissions) return units;
+  for (const spec of PERMISSION_UNITS) {
+    const group = (permissions as Record<string, unknown>)[spec.group];
+    if (group === undefined || group === null || group === false) continue;
+    // A group with no key *is* the unit: its presence grants it (`http`, `storage`, `location`),
+    // except `http`, whose empty host list grants nothing to reach.
+    // A list-valued unit grants only what is *in* the list: an empty `exec` reaches no binary and
+    // an empty `files.read` reaches no file, exactly as an empty `http.hosts` reaches no server.
+    if (spec.kind === "binaries") {
+      if (Array.isArray(group) && group.length > 0) units.add(spec.unit);
+      continue;
+    }
+    if (spec.kind === "paths") {
+      const list = (group as Record<string, unknown>)[spec.key!];
+      if (Array.isArray(list) && list.length > 0) units.add(spec.unit);
+      continue;
+    }
+    if (spec.key === null) {
+      if (spec.unit === "http" && (permissions.http?.hosts?.length ?? 0) === 0) continue;
+      units.add(spec.unit);
+      continue;
+    }
+    if ((group as Record<string, unknown>)[spec.key] === true) units.add(spec.unit);
+  }
+  return units;
+}
+
+/**
+ * What the extension actually gets: everything `required` (it could not have been
+ * enabled otherwise) plus whichever `optional` units the user approved.
+ *
+ * `approvedOptional` is intersected with the declaration, never unioned: an
+ * over-generous approval cannot widen a manifest.
+ */
+export function effectiveGrants(
+  manifest: ExtensionManifest,
+  approvedOptional?: ManifestPermissions,
+): ManifestPermissions {
+  const optional = intersectPermissions(
+    manifest.optionalPermissions,
+    approvedOptional ?? manifest.optionalPermissions,
+  );
+  return mergePermissions(manifest.permissions ?? {}, optional);
+}
+
+type PermissionRecord = Record<string, any>;
+
+/** The longest `pattern` a command may declare — see `CommandInput.pattern`. */
+const MAX_INPUT_PATTERN_LENGTH = 200;
+
+/**
+ * Validates a command's `input` block at install time, where a bad one costs nothing.
+ *
+ * The pattern is checked for two things and neither is a nicety. It must **compile**, because a
+ * pattern the host cannot build is a suggestion that silently never appears; and it must be
+ * **short**, because it is a guest-authored regular expression that the launcher's own process will
+ * run — the host separately caps the text it is run against, and between the two, catastrophic
+ * backtracking has nowhere interesting to go.
+ */
+function validateInput(
+  input: CommandInput | undefined,
+  path: string,
+  fail: (path: string, message: string) => void,
+): void {
+  if (input === undefined) return;
+  if (typeof input !== "object" || input === null) {
+    fail(path, "must be an object");
+    return;
+  }
+  if (input.accepts !== undefined) {
+    if (!Array.isArray(input.accepts) || input.accepts.length === 0) {
+      fail(`${path}.accepts`, "must be a non-empty array");
+    } else {
+      for (const type of input.accepts) {
+        // Closed, and it stays closed until the shell can actually find a value of the new type.
+        if (type !== "color") fail(`${path}.accepts`, `unknown subject type "${String(type)}"`);
+      }
+    }
+  }
+  if (input.pattern !== undefined) {
+    if (typeof input.pattern !== "string" || input.pattern.length === 0) {
+      fail(`${path}.pattern`, "must be a non-empty string");
+    } else if (input.pattern.length > MAX_INPUT_PATTERN_LENGTH) {
+      fail(`${path}.pattern`, `at most ${MAX_INPUT_PATTERN_LENGTH} characters`);
+    } else {
+      try {
+        new RegExp(input.pattern);
+      } catch {
+        fail(`${path}.pattern`, "is not a valid regular expression");
+      }
+    }
+  }
+  if (input.autocomplete !== undefined && typeof input.autocomplete !== "boolean") {
+    fail(`${path}.autocomplete`, "must be a boolean");
+  }
+  if (input.autocomplete && input.accepts === undefined && input.pattern === undefined) {
+    // Otherwise it reads as "suggest me something" with nothing said about what — and the host
+    // would have to guess, which is the one thing this declaration exists to avoid.
+    fail(path, "autocomplete needs `accepts` or `pattern` to know what to offer");
+  }
+}
+
+/**
+ * Combine the boolean units of two blocks with `combine` — `||` when merging required with
+ * approved-optional, `&&` when intersecting a declaration with an approval.
+ *
+ * Walks the unit table rather than naming each field, so adding a boolean unit is one row there.
+ * A group with nothing granted inside it is dropped entirely, which is what makes an absent
+ * capability object mean "denied" rather than "empty".
+ */
+function combineBooleans(
+  a: ManifestPermissions,
+  b: ManifestPermissions,
+  into: ManifestPermissions,
+  combine: (left: boolean, right: boolean) => boolean,
+  requireBothGroups: boolean,
+): void {
+  const left = a as PermissionRecord;
+  const right = b as PermissionRecord;
+  const target = into as PermissionRecord;
+
+  for (const spec of FLAG_PERMISSION_UNITS) {
+    if (combine(Boolean(left[spec.group]), Boolean(right[spec.group]))) target[spec.group] = true;
+  }
+
+  for (const [group, keys] of BOOLEAN_PERMISSION_GROUPS) {
+    // Intersection needs the group present on *both* sides; a union needs only one.
+    if (requireBothGroups && !(left[group] && right[group])) continue;
+    const value: Record<string, boolean> = {};
+    let granted = false;
+    for (const key of keys) {
+      const on = combine(Boolean(left[group]?.[key]), Boolean(right[group]?.[key]));
+      value[key] = on;
+      granted ||= on;
+    }
+    if (granted) target[group] = value;
+  }
+}
+
+function mergePermissions(a: ManifestPermissions, b: ManifestPermissions): ManifestPermissions {
+  const merged: ManifestPermissions = {};
+  const hosts = [...(a.http?.hosts ?? []), ...(b.http?.hosts ?? [])];
+  if (hosts.length > 0) merged.http = { hosts };
+  if (a.storage || b.storage) {
+    merged.storage = { maxBytes: Math.max(a.storage?.maxBytes ?? 0, b.storage?.maxBytes ?? 0) };
+  }
+  if (a.cache || b.cache) {
+    merged.cache = { maxBytes: Math.max(a.cache?.maxBytes ?? 0, b.cache?.maxBytes ?? 0) };
+  }
+  const names = [...(a.secrets?.names ?? []), ...(b.secrets?.names ?? [])];
+  if (names.length > 0) merged.secrets = { names };
+  // The two list-valued units (spec 016) concatenate, required block first. Order matters and is
+  // part of the contract: a `files.read` grant's **index** is the only handle the guest has on it,
+  // so required-then-optional has to be the same order on both sides of the boundary.
+  const read = [...(a.files?.read ?? []), ...(b.files?.read ?? [])];
+  if (read.length > 0) merged.files = { read };
+  const exec = [...(a.exec ?? []), ...(b.exec ?? [])];
+  if (exec.length > 0) merged.exec = exec;
+  const queries = [...(a.queries ?? []), ...(b.queries ?? [])];
+  if (queries.length > 0) merged.queries = queries;
+  if (a.location || b.location) merged.location = a.location ?? b.location;
+  combineBooleans(a, b, merged, (left, right) => left || right, false);
+  return merged;
+}
+
+/** Effective optional grant = declaration ∩ approval. Never wider than either. */
+export function intersectPermissions(
+  declared: ManifestPermissions | undefined,
+  approved: ManifestPermissions | undefined,
+): ManifestPermissions {
+  if (!declared || !approved) return {};
+  const effective: ManifestPermissions = {};
+
+  if (declared.http && approved.http) {
+    const hosts = approved.http.hosts.filter((host) => declared.http!.hosts.includes(host));
+    if (hosts.length > 0) effective.http = { hosts };
+  }
+  if (declared.storage && approved.storage) {
+    effective.storage = { maxBytes: Math.min(declared.storage.maxBytes, approved.storage.maxBytes) };
+  }
+  if (declared.cache && approved.cache) {
+    effective.cache = { maxBytes: Math.min(declared.cache.maxBytes, approved.cache.maxBytes) };
+  }
+  if (declared.secrets && approved.secrets) {
+    const names = approved.secrets.names.filter((name) => declared.secrets!.names.includes(name));
+    if (names.length > 0) effective.secrets = { names };
+  }
+  // Approval narrows, never widens: an entry the manifest never declared cannot be approved into
+  // existence. Compared structurally, since these carry no natural key the user picks from — the
+  // switch is per *unit* (§7.1), so in practice approval is the whole list or none of it.
+  if (declared.files?.read && approved.files?.read) {
+    const read = declared.files.read.filter((grant) =>
+      approved.files!.read.some((other) => JSON.stringify(other) === JSON.stringify(grant)),
+    );
+    if (read.length > 0) effective.files = { read };
+  }
+  if (declared.queries && approved.queries) {
+    const queries = declared.queries.filter((grant) =>
+      approved.queries!.some((other) => JSON.stringify(other) === JSON.stringify(grant)),
+    );
+    if (queries.length > 0) effective.queries = queries;
+  }
+  if (declared.exec && approved.exec) {
+    const exec = declared.exec.filter((grant) =>
+      approved.exec!.some((other) => JSON.stringify(other) === JSON.stringify(grant)),
+    );
+    if (exec.length > 0) effective.exec = exec;
+  }
+  if (declared.location && approved.location) {
+    // The narrower precision wins.
+    effective.location = {
+      precision:
+        declared.location.precision === "coarse" || approved.location.precision === "coarse"
+          ? "coarse"
+          : "precise",
+    };
+  }
+  combineBooleans(declared, approved, effective, (left, right) => left && right, true);
+  return effective;
+}
+
+/** Every `@key` reference in the manifest, for catalog completeness checks. */
+export function manifestCatalogKeys(manifest: ExtensionManifest): string[] {
+  const keys: string[] = [];
+  const take = (value: string | undefined) => {
+    if (value?.startsWith("@")) keys.push(value.slice(1));
+  };
+  take(manifest.name);
+  take(manifest.description);
+  for (const command of manifest.commands) {
+    take(command.title);
+    take(command.description);
+    for (const argument of command.arguments ?? []) {
+      take(argument.title);
+      take(argument.placeholder);
+    }
+  }
+  for (const setting of manifest.settings ?? []) {
+    take(setting.title);
+    take(setting.description);
+    if (setting.type === "select") for (const option of setting.options) take(option.title);
+  }
+  return keys;
+}
+
+export function settingsDefaults(manifest: ExtensionManifest): Record<string, JsonValue> {
+  const defaults: Record<string, JsonValue> = {};
+  for (const setting of manifest.settings ?? []) {
+    defaults[setting.key] = setting.default;
+  }
+  return defaults;
+}
+
+/**
+ * What a proposed setting value is *worth* — the one place `ctx.settings.set` and the Preferences
+ * field are reconciled against the manifest.
+ *
+ * Returns the value coerced to the key's declared type, or `undefined` when the manifest has no
+ * such key or the value cannot be that type. Undefined means **leave the setting alone**: a write
+ * the manifest does not describe is not a new setting, and a `select` value outside its options is
+ * not a new option. Declaring a setting is what makes it exist; writing one only moves it.
+ *
+ * `"5"` for a `number` coerces rather than fails, because the two writers disagree about strings
+ * by nature: a rendered `<select>` hands back option values, which are text.
+ */
+export function coerceSetting(
+  manifest: ExtensionManifest,
+  key: string,
+  value: JsonValue,
+): JsonValue | undefined {
+  const setting = (manifest.settings ?? []).find((s) => s.key === key);
+  if (setting === undefined) return undefined;
+  switch (setting.type) {
+    case "boolean":
+      if (typeof value === "boolean") return value;
+      if (value === "true") return true;
+      if (value === "false") return false;
+      return undefined;
+    case "number": {
+      const n = typeof value === "number" ? value : Number(value);
+      return Number.isFinite(n) ? n : undefined;
+    }
+    case "select": {
+      const text = typeof value === "string" ? value : String(value);
+      return setting.options.some((option) => option.value === text) ? text : undefined;
+    }
+    case "string":
+      return typeof value === "string" ? value : undefined;
+  }
+}
+
+/** The id a guest item is namespaced to before it enters core state. */
+export function namespacedItemId(extensionId: string, commandId: string, guestId: string): string {
+  return `extension:${extensionId}:${commandId}:${guestId}`;
+}
+
+/** Extension-declared scope types must live under this prefix. */
+export function scopeTypePrefix(extensionId: string): string {
+  return `ext.${extensionId}.`;
+}
+
+/**
+ * `contributes[]` — a native scope, a required subject predicate, and a title.
+ *
+ * Every rejection here is a rejection the installer must make too, and the reason they are
+ * rejections rather than ignored keys is the trap this whole mechanism sits in: a `when` field
+ * the host does not understand, silently dropped, is a predicate that matches **everything**.
+ * An author would ship it, the installer would accept it, and the extension would be called for
+ * every app on the machine. So an unknown field fails, loudly, before installation.
+ */
+/**
+ * `provides[]` — which slot, and the unit that grants it.
+ *
+ * Both halves are checked against each other here, as `contributes` checks its handler: a provision
+ * with no permission unit is an answer nobody may give, and a unit with no provision is an approval
+ * the user was asked for and nothing will ever use. Neither is a shrug — the install sheet reads
+ * both, and a sheet that lists a permission with no visible purpose teaches people to stop reading
+ * it.
+ */
+function validateProvides(
+  m: Record<string, unknown>,
+  fail: (path: string, message: string) => void,
+): void {
+  const declaresWorkspaceRoots = (block: unknown): boolean =>
+    (block as ManifestPermissions | undefined)?.workspace?.roots === true;
+  const granted = declaresWorkspaceRoots(m.permissions) || declaresWorkspaceRoots(m.optionalPermissions);
+
+  const provides = m.provides;
+  if (provides === undefined) {
+    if (granted) {
+      fail("permissions.workspace.roots", "grants a slot nothing fills — declare it in provides[]");
+    }
+    return;
+  }
+  if (!Array.isArray(provides)) {
+    fail("provides", "must be an array");
+    return;
+  }
+  const ids = new Set<string>();
+  const filled = new Set<string>();
+  provides.forEach((raw, index) => {
+    const path = `provides[${index}]`;
+    const entry = raw as Record<string, unknown>;
+    if (typeof entry?.id !== "string" || !COMMAND_ID_PATTERN.test(entry.id)) {
+      fail(`${path}.id`, "must be a kebab-case identifier");
+    } else if (ids.has(entry.id)) {
+      fail(`${path}.id`, `duplicate provision id "${entry.id}"`);
+    } else {
+      ids.add(entry.id);
+    }
+    if (typeof entry?.slot !== "string" || !(SLOT_TYPES as readonly string[]).includes(entry.slot)) {
+      fail(`${path}.slot`, `must be one of ${SLOT_TYPES.join(", ")}`);
+    } else {
+      filled.add(entry.slot);
+    }
+    if (typeof entry?.title !== "string" || entry.title.trim() === "") {
+      fail(`${path}.title`, "must say what fills the slot, for the install sheet");
+    }
+  });
+  if (filled.has("workspace.roots") && !granted) {
+    fail("provides", "filling workspace.roots needs the workspace.roots permission");
+  }
+  if (granted && !filled.has("workspace.roots")) {
+    fail("permissions.workspace.roots", "grants a slot nothing fills — declare it in provides[]");
+  }
+}
+
+function validateContributes(
+  m: Record<string, unknown>,
+  integrates: string[],
+  fail: (path: string, message: string) => void,
+): void {
+  const contributes = m.contributes;
+  if (contributes === undefined) return;
+  if (!Array.isArray(contributes)) {
+    fail("contributes", "must be an array");
+    return;
+  }
+  const commandIds = new Set(
+    (Array.isArray(m.commands) ? m.commands : [])
+      .map((raw) => (raw as Record<string, unknown>)?.id)
+      .filter((id): id is string => typeof id === "string"),
+  );
+  const seen = new Set<string>();
+  contributes.forEach((raw, index) => {
+    const path = `contributes[${index}]`;
+    const c = raw as Record<string, unknown>;
+    if (typeof c.id !== "string" || !COMMAND_ID_PATTERN.test(c.id)) {
+      fail(`${path}.id`, "must be a kebab-case identifier");
+    } else if (seen.has(c.id)) {
+      fail(`${path}.id`, `duplicate contribution id "${c.id}"`);
+    } else if (commandIds.has(c.id)) {
+      fail(`${path}.id`, `"${c.id}" is already a command id`);
+    } else {
+      seen.add(c.id);
+    }
+    if (typeof c.title !== "string" || c.title.trim() === "") {
+      fail(`${path}.title`, "required — it is what the install sheet shows");
+    }
+    if (typeof c.scope !== "string" || !isContributableScopeType(c.scope)) {
+      fail(
+        `${path}.scope`,
+        `must be one of ${CONTRIBUTABLE_SCOPE_TYPES.join(", ")} — a scope an extension may own is declared in code, not here`,
+      );
+      return;
+    }
+    const fields = CONTRIBUTION_MATCH_FIELDS[c.scope as ContributableScopeType];
+    const when = c.when;
+    if (typeof when !== "object" || when === null || Array.isArray(when)) {
+      fail(`${path}.when`, "must be an object naming which subjects match");
+      return;
+    }
+    const entries = Object.entries(when as Record<string, unknown>);
+    if (entries.length === 0) {
+      fail(
+        `${path}.when`,
+        `must name at least one of ${fields.join(", ")} — a contribution to every subject of a scope is not declarable`,
+      );
+    }
+    for (const [field, values] of entries) {
+      const fieldPath = `${path}.when.${field}`;
+      if (!fields.includes(field)) {
+        fail(fieldPath, `"${c.scope}" subjects have no matchable "${field}"; try ${fields.join(", ")}`);
+        continue;
+      }
+      if (!Array.isArray(values) || values.length === 0) {
+        fail(fieldPath, "must be a non-empty array of values");
+        continue;
+      }
+      values.forEach((value, valueIndex) => {
+        if (typeof value !== "string" || value.trim() === "") {
+          fail(`${fieldPath}[${valueIndex}]`, "must be a non-empty string");
+          return;
+        }
+        // One declaration, four uses (spec 016 §1): an app named here must be named at the top
+        // level too, so the install sheet has one list to show and every other reach — the
+        // container to read, the bundle binary to run, the scheme to open — resolves against it.
+        if (field === "bundleId" && !integrates.includes(value)) {
+          fail(
+            `${fieldPath}[${valueIndex}]`,
+            `"${value}" is not in integratesWith — declare the apps this extension works with there`,
+          );
+        }
+      });
+    }
+  });
+}
+
+/** The most rule text a manifest may carry — see `ExtensionManifest.suggestionRules`. */
+const MAX_SUGGESTION_RULES_LENGTH = 8_000;
+
+/**
+ * `suggestionRules` — shape and size only.
+ *
+ * **The grammar is deliberately not checked here.** There is exactly one parser for the rule DSL
+ * and it lives in the host (spec 018 §8), so a second, weaker reading of the same text on this side
+ * would only be able to disagree with it. What this side can say without owning the grammar is that
+ * the field is text, that there is some, and that there is not so much of it that parsing it at
+ * every launch stops being free.
+ */
+function validateSuggestionRules(
+  value: unknown,
+  fail: (path: string, message: string) => void,
+): void {
+  if (value === undefined) return;
+  let text: string;
+  if (typeof value === "string") {
+    text = value;
+  } else if (Array.isArray(value)) {
+    const bad = value.findIndex((line) => typeof line !== "string");
+    if (bad >= 0) {
+      fail(`suggestionRules[${bad}]`, "must be a string");
+      return;
+    }
+    text = value.join("\n");
+  } else {
+    fail("suggestionRules", "must be rule text, or an array of lines");
+    return;
+  }
+  if (text.trim() === "") fail("suggestionRules", "must not be empty");
+  if (text.length > MAX_SUGGESTION_RULES_LENGTH) {
+    fail("suggestionRules", `must be at most ${MAX_SUGGESTION_RULES_LENGTH} characters`);
+  }
+}
+
+/** `integratesWith` — bundle identifiers, unique, and the anchor every other reach resolves against. */
+function validateIntegratesWith(
+  m: Record<string, unknown>,
+  fail: (path: string, message: string) => void,
+): string[] {
+  const raw = m.integratesWith;
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    fail("integratesWith", "must be an array of bundle identifiers");
+    return [];
+  }
+  const seen = new Set<string>();
+  raw.forEach((value, index) => {
+    if (typeof value !== "string" || !BUNDLE_ID_PATTERN.test(value)) {
+      fail(`integratesWith[${index}]`, "must be a reverse-domain bundle identifier");
+    } else if (seen.has(value)) {
+      fail(`integratesWith[${index}]`, `duplicate "${value}"`);
+    } else {
+      seen.add(value);
+    }
+  });
+  return [...seen];
+}
+
+/**
+ * `files.read` and `exec` — the two grants that reach outside the sandbox (spec 016).
+ *
+ * Every problem here is a rejection rather than an ignored key, for the reason §11.3's `when` is:
+ * these are the blocks whose failure mode is **widening**. A dropped `path` is a grant on the whole
+ * root; a dropped `args` template is an unconstrained argv.
+ */
+/**
+ * A `path` under a named root, judged by that root's shape.
+ *
+ * `subpath` keeps spec 016's rule, bare root included: a grant on the whole root is legal and left
+ * to review, but it has to be *written*, so the install sheet says "every app's data" rather than
+ * printing a path. `dot-segment` has no bare form at all — the root is the home directory, and the
+ * one dot-segment is the entire reason it is declarable.
+ */
+function validateRootPath(
+  root: FileRoot,
+  value: unknown,
+  path: string,
+  fail: (path: string, message: string) => void,
+): void {
+  if (ROOT_PATH_SHAPES[root] === "dot-segment") {
+    if (typeof value !== "string" || value.trim() === "") {
+      fail(path, `${root} needs a dot-directory, e.g. ".codex"`);
+      return;
+    }
+    if (value.includes("/") || value.includes("\\")) {
+      fail(path, `${root} reaches exactly one directory — ".codex", not ".codex/sessions"`);
+      return;
+    }
+    if (!value.startsWith(".") || value === "." || value === "..") {
+      fail(path, `${root} reaches a tool's dot-directory — the name must begin with a dot`);
+    }
+    return;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    if (value !== undefined) fail(path, "must be a non-empty subpath, or omitted");
+    return;
+  }
+  validateSubpath(value, path, fail);
+}
+
+/**
+ * The statement a `files.query` grant fixes at install time.
+ *
+ * Rejected rather than sanitized, and checked here only as the *first* door: the host prepares the
+ * statement against a read-only connection and takes SQLite's own `readonly` verdict as the second.
+ * A reader that has to guess what a string does is a reader that will eventually guess wrong, which
+ * is why the shape is this narrow — one statement, one leading keyword, holes that are only `?`.
+ */
+function validateReadOnlySql(
+  value: unknown,
+  path: string,
+  fail: (path: string, message: string) => void,
+): void {
+  if (typeof value !== "string" || value.trim() === "") {
+    fail(path, "must be a SELECT statement");
+    return;
+  }
+  const sql = value.trim();
+  if (sql.replace(/;\s*$/, "").includes(";")) {
+    fail(path, "is one statement — a semicolon can only end it");
+    return;
+  }
+  if (!/^(select|with)\b/i.test(sql)) {
+    fail(path, "must begin with SELECT or WITH — a query grant cannot write");
+  }
+  if (/\b(attach|pragma)\b/i.test(sql)) {
+    fail(path, "cannot ATTACH or PRAGMA — those reach outside the database that was declared");
+  }
+  if (/\$[A-Za-z_]|[:@][A-Za-z_]/.test(sql)) {
+    fail(path, "takes positional ? holes only, so the values cannot be named or reordered");
+  }
+}
+
+function validateReach(
+  permissions: ManifestPermissions | undefined,
+  block: string,
+  integrates: string[],
+  fail: (path: string, message: string) => void,
+): void {
+  if (!permissions) return;
+
+  const reads = permissions.files?.read;
+  if (permissions.files !== undefined) {
+    if (!Array.isArray(reads) || reads.length === 0) {
+      fail(`${block}.files.read`, "must be a non-empty array of places to read");
+    } else {
+      reads.forEach((grant, index) => {
+        const path = `${block}.files.read[${index}]`;
+        const g = grant as unknown as Record<string, unknown>;
+        const hasContainer = typeof g.container === "string";
+        const hasRoot = typeof g.root === "string";
+        if (hasContainer === hasRoot) {
+          fail(path, "declare exactly one of container (an app you integrate with) or root (a named root)");
+          return;
+        }
+        if (hasContainer) {
+          if (integrates.length === 0) {
+            fail(path, "container reads resolve inside an app's bundle container — declare it in integratesWith");
+          }
+          validateSubpath(g.container as string, `${path}.container`, fail);
+        } else {
+          if (!(FILE_ROOTS as readonly string[]).includes(g.root as string)) {
+            fail(`${path}.root`, `must be one of ${FILE_ROOTS.join(", ")}`);
+            return;
+          }
+          validateRootPath(g.root as FileRoot, g.path, `${path}.path`, fail);
+        }
+        if (g.match !== undefined && (typeof g.match !== "string" || g.match.includes("/"))) {
+          fail(`${path}.match`, "globs leaf names only — it cannot contain a slash");
+        }
+      });
+    }
+  }
+
+  const queries = permissions.queries;
+  if (queries !== undefined) {
+    if (!Array.isArray(queries) || queries.length === 0) {
+      fail(`${block}.queries`, "must be a non-empty array of stored queries");
+    } else {
+      const ids = new Set<string>();
+      queries.forEach((grant, index) => {
+        const path = `${block}.queries[${index}]`;
+        const g = grant as unknown as Record<string, unknown>;
+        if (typeof g.id !== "string" || !COMMAND_ID_PATTERN.test(g.id)) {
+          fail(`${path}.id`, "must be a kebab-case identifier");
+        } else if (ids.has(g.id)) {
+          fail(`${path}.id`, `duplicate query id "${g.id}"`);
+        } else {
+          ids.add(g.id);
+        }
+        if (!(FILE_ROOTS as readonly string[]).includes(g.root as string)) {
+          fail(`${path}.root`, `must be one of ${FILE_ROOTS.join(", ")}`);
+        } else {
+          validateRootPath(g.root as FileRoot, g.path, `${path}.path`, fail);
+        }
+        if (typeof g.database !== "string" || g.database.trim() === "") {
+          fail(`${path}.database`, "must name one database file");
+        } else if (g.database.includes("/") || g.database.includes("\\") || g.database.includes("..")) {
+          fail(`${path}.database`, "is a leaf name inside the declared folder — no separators, no ..");
+        }
+        validateReadOnlySql(g.sql, `${path}.sql`, fail);
+      });
+    }
+  }
+
+  const execs = permissions.exec;
+  if (execs !== undefined) {
+    if (!Array.isArray(execs) || execs.length === 0) {
+      fail(`${block}.exec`, "must be a non-empty array of binaries");
+      return;
+    }
+    const ids = new Set<string>();
+    execs.forEach((grant, index) => {
+      const path = `${block}.exec[${index}]`;
+      const g = grant as unknown as Record<string, unknown>;
+      if (typeof g.id !== "string" || !COMMAND_ID_PATTERN.test(g.id)) {
+        fail(`${path}.id`, "must be a kebab-case identifier");
+      } else if (ids.has(g.id)) {
+        fail(`${path}.id`, `duplicate exec id "${g.id}"`);
+      } else {
+        ids.add(g.id);
+      }
+      const external = typeof g.identifier === "string";
+      const inApp = typeof g.inApp === "string";
+      if (external === inApp) {
+        fail(path, "declare exactly one of identifier+team (an external binary) or inApp+executable");
+      } else if (external) {
+        if (typeof g.team !== "string" || g.team.trim() === "") {
+          fail(`${path}.team`, "an external binary is identified by its signature — team is required");
+        }
+      } else if (!integrates.includes(g.inApp as string)) {
+        fail(`${path}.inApp`, `"${String(g.inApp)}" is not in integratesWith`);
+      }
+      // Required for *both* forms: `id` names the declaration, never the file, and one binary
+      // normally carries several declarations.
+      if (typeof g.executable !== "string" || g.executable.includes("/")) {
+        fail(`${path}.executable`, 'must name the binary, e.g. "op"');
+      }
+      if (g.protocol !== undefined && g.protocol !== "mcp") {
+        fail(`${path}.protocol`, 'the only protocol is "mcp"');
+      }
+      if (g.protocol === "mcp") {
+        if (g.args !== undefined) fail(`${path}.args`, "an mcp binary is spoken to, not argv-invoked");
+      } else if (!Array.isArray(g.args) || g.args.some((arg: unknown) => typeof arg !== "string")) {
+        // Required, and this is the load-bearing rule: a later policy ("no write operations") is a
+        // statement about argv, and there is nothing to state it about if the shape is only known
+        // at call time.
+        fail(`${path}.args`, "required — declare the argv template, with {} for each value supplied at call time");
+      }
+    });
+  }
+}
+
+/** A subpath inside a host-chosen root: no wildcards, no climbing, no absolute form. */
+function validateSubpath(value: string, path: string, fail: (path: string, message: string) => void): void {
+  if (value.trim() === "") {
+    fail(path, "must be a non-empty subpath");
+  } else if (value.startsWith("/") || value.startsWith("~")) {
+    fail(path, "is relative to a root the host chooses — it cannot be absolute");
+  } else if (value.split("/").some((segment) => segment === "..")) {
+    fail(path, 'cannot contain ".."');
+  } else if (/[*?[\]]/.test(value)) {
+    fail(path, "cannot contain wildcards — glob leaf names with `match` instead");
+  }
+}