@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/kernel/packs/types.ts

@@ -19,6 +19,80 @@
  * of the canonical set.
  */
 
+/**
+ * The parameter names the KERNEL puts on a compiled verb, which a story's own
+ * filter may therefore not claim.
+ *
+ * `search` is a story's declared free-text flag; `detail` the disclosure
+ * selector; `name` and `count` a lookup's and a sample's positionals; `limit`
+ * and `after` the page every list-shaped verb carries. A filter claiming one
+ * would collide with a flag the CLI has already registered — a Commander
+ * failure outside every error envelope the CLI owns. Declared here, in the
+ * zod-free grammar, so the validator that refuses them and any reader that
+ * needs to tell a story's OWN params from the kernel's read one list.
+ */
+export const RESERVED_STORY_PARAMS: readonly string[] = [
+  "search",
+  "detail",
+  "name",
+  "count",
+  "limit",
+  "after",
+];
+
+/**
+ * The SPARQL VARIABLE prefix the kernel reserves, which a story's own query may
+ * therefore not use.
+ *
+ * The generated filter and search clauses bind a caller's values to variables
+ * under this prefix (`?__pragmaFilter0`, `?__pragmaSearch`). A story query using
+ * it would have its own variable shadowed, and the symptom would be a filter
+ * matching nothing with nothing raised anywhere. Beside the reserved PARAMS for
+ * the same reason: the grammar that refuses it and the builder that mints it
+ * must read one name, and this file is the zod-free place both can reach — the
+ * builder lives behind the dynamically imported run bodies, so nothing on the
+ * `--help` fast path may import it.
+ */
+export const RESERVED_VARIABLE_PREFIX = "__pragma";
+
+/**
+ * The `--tier` value that turns the tier scope OFF — every tier, the way every
+ * read answered before the scope existed.
+ *
+ * A word rather than a second flag (this distribution retired an `--all-tiers`
+ * once already): `--tier all` answers the same question the flag already asks,
+ * so there is one argument to learn and one to document.
+ *
+ * Declared HERE, in the zod-free grammar, for the reason
+ * {@link RESERVED_VARIABLE_PREFIX} is: the compiler that puts the flag on a
+ * verb runs on the storeless `--help` fast path, and the run body that reads it
+ * lives behind a dynamic import. Both must read one spelling.
+ */
+export const EVERY_TIER = "all";
+
+/**
+ * The parameter name the kernel puts on a TIER-SCOPED noun's reads (`--tier`,
+ * `tier` over MCP).
+ *
+ * Not in {@link RESERVED_STORY_PARAMS}, because it is reserved CONDITIONALLY:
+ * an unscoped noun may still declare a `tier` filter of its own, and one does —
+ * `variable list --tier` filters the token graph's `dt:tier`, a different
+ * predicate in a different namespace from the `ds:tier` this scope reads. The
+ * rule that a SCOPED story may not claim it lives in {@link ./storyRules}.
+ */
+export const TIER_PARAM = "tier";
+
+/**
+ * The SELECT variable a list-shaped story publishes its entity IRI in.
+ *
+ * A convention this package already depends on twice — the condensed renderer
+ * titles a row from `uri`/`name`, and every shipped list's IRI column is `uri`
+ * — stated here because the tier scope is compiled in as a constraint on that
+ * variable, and because both the storeless declaration rules and the query
+ * builder behind the dynamic import must read one spelling of it.
+ */
+export const ENTITY_VARIABLE = "uri";
+
 /** A list column: a SELECT variable to display. */
 export interface PackColumn {
   /** SELECT variable name (without `?`). */
@@ -53,6 +127,17 @@ export interface PackField {
 export interface PackSection extends PackField {
   /** Rendering kind (inline field or fenced code block). */
   readonly kind?: "field" | "code";
+  /**
+   * One sentence rendered under the section's heading, above its body: how to
+   * READ what follows, when the body's own notation does not say.
+   *
+   * For a section whose body is a document the graph authored, the label is
+   * enough. For one whose body is a NOTATION — a block's anatomy is a YAML
+   * document in which `background.color: [a, b]` is a fallback chain, first
+   * value that resolves winning — the reader has to be told, and the place to
+   * tell them is where they are looking.
+   */
+  readonly note?: string;
 }
 
 /** A field read from each child node of a {@link PackExpand}. */
@@ -65,6 +150,22 @@ export interface PackExpandField {
   readonly label?: string;
   /** Explicit GraphQL field name (escape hatch). Ignored on the SPARQL path. */
   readonly graphqlField?: string;
+  /**
+   * Leave the cell BLANK when its value repeats the looked-up entity's own
+   * `by` value — for a relation an entity can point back at ITSELF along.
+   *
+   * The standing case is a block's token bindings: `ds:viaBlock` names the
+   * anatomy tree a binding was reached through, and the ontology defines it as
+   * present on every record and EQUAL to the block on the block's own tree. So
+   * a Button lookup printed "Button" in the via column of all 24 of its rows —
+   * a cell that is only ever news when it differs. Blank says "this block's
+   * own", which is the reading, and leaves the column carrying only the
+   * inherited trees.
+   *
+   * SPARQL lane only: the generated sub-SELECT can bind the entity's own name
+   * and filter against it, and a GraphQL document cannot.
+   */
+  readonly blankWhenSelf?: true;
 }
 
 /**
@@ -119,6 +220,72 @@ export interface PackExpand {
   readonly showWhenEmpty?: boolean;
   /** Minimum canonical disclosure level at which this expand is fetched. */
   readonly level?: string;
+  /**
+   * One sentence rendered under the section's heading, above the rows: how to
+   * READ them, when the columns do not say it themselves.
+   *
+   * The same seam a {@link PackSection} carries, for the same reason and
+   * through the same renderer field — a section's note was declarable only for
+   * a section whose body is one literal, and a TABLE can be the notation that
+   * needs reading just as much: a `rank` column is a position in a fallback
+   * chain, and nothing in the word "rank" says which chain or that first wins.
+   */
+  readonly note?: string;
+  /**
+   * Child field names to ORDER BY in the generated sub-SELECT, in order.
+   *
+   * Without one an expand's rows arrive in the store's own scan order, which
+   * SPARQL does not define and which no reader can predict. That is tolerable
+   * for a short list of names and wrong for a TABLE whose rows differ in one
+   * column: Button's 24 token bindings came back with `spacing.internal.inline.start`
+   * and `…end` adjacent, in no stated order, and a reader comparing two rows
+   * had no way to know whether the pair was two facts or one repeated.
+   *
+   * Names must be fields the `select` declares (the grammar refuses others),
+   * so the clause is composed only from validated identifiers. SPARQL lane
+   * only — a GraphQL connection's order is the schema's, not the story's.
+   */
+  readonly orderBy?: readonly string[];
+  /**
+   * Resolve THIS expand through the SPARQL lane even when the lookup is
+   * `source: "graphql"`.
+   *
+   * The lanes are not interchangeable, and a lookup is one or the other: the
+   * GraphQL lane can project a grandchild through a MULTI-valued relation
+   * (a nested expand), which the single-hop SPARQL sub-SELECT cannot, and the
+   * SPARQL lane can read property paths and any property the ontology defines,
+   * which the GraphQL lane cannot — a derived field name that the compiled
+   * schema does not carry drops out of the document in silence.
+   *
+   * The block lookup needs both at once, which is why this exists rather than
+   * a second lookup. Its modifier families are a nested expand and so must
+   * stay on the GraphQL lane; its token bindings must not, because
+   * `anatomy:styleKey` and `anatomy:styleState` — two of the six columns that
+   * IDENTIFY a binding — carry no `rdfs:domain`, so ke-graphql generates no
+   * field for them on `TokenBinding` and the two columns vanished without a
+   * word, leaving rows that differed only in a dropped column looking like
+   * duplicates.
+   *
+   * Only `"sparql"` is admissible: the SPARQL lane is every lookup's default,
+   * so an expand opting INTO GraphQL would be asking for a document the lookup
+   * never builds.
+   */
+  readonly source?: "sparql";
+}
+
+/**
+ * Which lane resolves one expand: its own declared {@link PackExpand.source},
+ * else the lookup's, else SPARQL.
+ *
+ * Read by BOTH lanes — the GraphQL document generator skips what it does not
+ * own, and the entity fetcher runs it — so the question is answered in one
+ * place rather than asked twice with two spellings.
+ */
+export function expandIsSparql(
+  lookup: Pick<PackLookup, "source">,
+  expand: Pick<PackExpand, "source">,
+): boolean {
+  return (expand.source ?? lookup.source ?? "sparql") === "sparql";
 }
 
 /**
@@ -136,8 +303,12 @@ export interface PackDisclosure {
 
 /**
  * A declarative list filter: a CLI/MCP parameter constraining one SELECT
- * variable. Filters are row predicates applied AFTER the author query runs — the
- * query text is never modified, so filter input cannot inject SPARQL.
+ * variable. Filters compile INTO the generated query, as predicates over the
+ * author query read as a sub-select — the author's text is never modified, and
+ * a caller's value is bound through a `VALUES` block rather than spliced into
+ * query text, so filter input still cannot inject SPARQL. Compiling them in is
+ * what puts filtering on the right side of a page: a predicate over returned
+ * rows would decide over whatever the page happened to contain.
  */
 export interface PackFilter {
   /** Parameter name — a single lowercase word (`--param` / MCP key). */
@@ -161,11 +332,16 @@ export interface PackFilter {
    * the hierarchy, also a `testing` standard, and a filter that compared only
    * the leaf answered `--category testing` with 1 of 8 — a silently wrong
    * answer, exit 0.
+   *
+   * A `"set"` cell is computed by the author's own `GROUP BY`, so its predicate
+   * can only run AFTER aggregation. That is why a filtered list wraps the
+   * author query in a sub-select rather than appending to it, and why a
+   * filterable story must project its variables by name.
    */
   readonly match?: "exact" | "set";
   /**
-   * Where the dimension's VOCABULARY lives in the graph, for a filter with no
-   * declared {@link values}.
+   * Where the dimension's VOCABULARY lives in the graph. REQUIRED for a filter
+   * with no declared {@link values} — a filter declaring neither is refused.
    *
    * A value-free filter rejects a value the data does not carry. The question is
    * what "the data" means. The rows a list just returned are the wrong answer:
@@ -180,9 +356,13 @@ export interface PackFilter {
    * this honours is "the graph is the vocabulary, don't hard-code the slugs" —
    * rows were never the graph, just the part of it that answered.
    *
-   * Without it a value-free filter falls back to the observed rows, which is the
-   * only evidence available; that is a NARROWER vocabulary than the truth, and a
-   * story whose dimension has an authoritative source should declare it.
+   * A value-free filter USED to fall back to the observed rows — knowingly
+   * narrower than the truth, but the only evidence available. Now that a list
+   * answers with a PAGE that fallback is not merely narrow, it is wrong: a real
+   * value outside the window would be refused as a bad argument, with a
+   * truncated list of alternatives. So the fallback is gone and the declaration
+   * takes its place — a filter names `values` or a vocabulary, and one that
+   * names neither is refused where it is declared.
    */
   readonly vocabulary?: PackFilterVocabulary;
   /** Help text (defaults to a generated description). */
@@ -202,8 +382,9 @@ export interface PackFilterVocabulary {
 
 /**
  * Free-text search over list rows: a `--search` string keeping a row when ANY
- * named SELECT variable contains the term (case-insensitive substring). Applied
- * after the author query, so input never touches the query text.
+ * named SELECT variable contains the term (case-insensitive substring).
+ * Compiled into the generated query alongside the filters, with the term bound
+ * through a `VALUES` block rather than spliced into query text.
  */
 export interface PackSearch {
   /** SELECT variables searched (without `?`). */
@@ -426,6 +607,73 @@ export interface PackLookup {
 /** A pack list row / flat lookup base: variable name → string value. */
 export type PackRow = Record<string, string>;
 
+/**
+ * What a list-shaped verb answers with: one page of rows, and whether more
+ * follow.
+ *
+ * The ROWS are still the payload — `formatters.json` projects this to
+ * {@link rows} alone, so `--format json` and the MCP tool result stay the bare
+ * array they always were and nothing downstream had to learn a new shape. The
+ * page's own facts ride the `notice` seam into the envelope's `meta`, the same
+ * channel a calm empty result already uses. That is deliberate: a caller
+ * reading the data reads data, and a caller who needs to know there is more is
+ * told in the one place this surface already puts things the data cannot say
+ * about itself.
+ */
+export interface PackPage {
+  /** This page's rows, in the story's own order. */
+  readonly rows: readonly PackRow[];
+  /**
+   * The filters this read was narrowed by, as the caller spelled them — absent
+   * when the read was unfiltered.
+   *
+   * Carried because a zero-row answer has something to say that its rows
+   * cannot: which arguments narrowed it. A reader who typed `--kind input` and
+   * got nothing has to see that it was applied and came back empty, so the
+   * empty-state sentence names the filters in force. The story's
+   * `emptyRecovery` — which speaks about the population, and is worded to hold
+   * whether or not a filter is in force — prints under that sentence, the same
+   * as it prints on its own when nothing narrowed the read. The renderer cannot
+   * re-derive this: it sees a page, not the arguments, so the run body records
+   * what it narrowed by.
+   */
+  readonly filters?: readonly PackAppliedFilter[];
+  /**
+   * The cursor that asks for the rows after this page, absent when this page is
+   * the last. Its presence IS the "more rows exist" answer.
+   */
+  readonly nextAfter?: string;
+  /** The limit this page was cut to, for the notice that reports it. */
+  readonly limit: number;
+  /**
+   * The tier scope this read was narrowed to, absent when the story is not
+   * tiered or the caller asked for every tier.
+   *
+   * Carried for the same reason {@link filters} is: the rows cannot say that a
+   * whole part of the population was never considered. A reader who sees 175
+   * blocks under a heading that says `(175)` reads it as the design system; the
+   * scope is how the answer admits it is one tier chain of it.
+   */
+  readonly scope?: PageTierScope;
+}
+
+/** The tier scope a page was read under, as a caller can read it back. */
+export interface PageTierScope {
+  /**
+   * The in-scope tiers, in the spelling the `--tier` flag and the `Tier` column
+   * use (the tier IRI's local name), base first and then shallowest first.
+   */
+  readonly tiers: readonly string[];
+}
+
+/** One filter a list read was narrowed by, as the caller spelled it. */
+export interface PackAppliedFilter {
+  /** The parameter name (its CLI flag is `--<param>`). */
+  readonly param: string;
+  /** The value(s) supplied, already joined for display. */
+  readonly value: string;
+}
+
 /**
  * A child record under an expand. Scalar values come from child fields; a nested
  * expand contributes either a collapsed string array (single-field select) or
@@ -467,6 +715,60 @@ export interface PackDefinition {
    * modules) by `pragma colophon`, after pragma's own built-in colophon.
    */
   readonly colophon?: string;
+  /**
+   * The tier hierarchy this noun's entities carry, which SCOPES every read of
+   * them. Absent means unscoped — the read answers from every tier, as every
+   * read did before the scope existed.
+   */
+  readonly tierScope?: PackTierScope;
+}
+
+/**
+ * The tier hierarchy this noun's entities belong to, and the scope every read
+ * of them is narrowed by.
+ *
+ * DECLARED PER NOUN, because being tiered is a property of the entities: the
+ * design system's blocks, modifier families and concepts carry a `ds:tier`, and
+ * its token symbols, variables and code standards carry nothing of the kind. A
+ * noun that declares this gets the scope compiled into every list it declares
+ * and applied to its lookup; a noun that does not is read exactly as before.
+ *
+ * WHY THE HIERARCHY IS A NAME AND NOT AN EDGE. The shipped graph asserts no
+ * parent predicate on a tier — `ds:apps_lxd` is `a ds:Tier` with a
+ * `ds:name "Apps/LXD"`, and that slash IS the hierarchy: `Apps/LXD` sits under
+ * `Apps`, which sits under nothing. So the parent of a tier is the tier whose
+ * name is its own name minus the last `/` segment, exactly the derivation
+ * {@link PackScopeWeight} already ranks by ("the depth is the `/` count in the
+ * tier's OWN `ds:name`, not in its IRI"). Reading the hierarchy from the same
+ * place twice is what keeps the ranking and the scope from disagreeing about
+ * which tier is above which. The day a parent edge is asserted upstream, `by`
+ * gives way to it and every reader here changes in one place.
+ */
+export interface PackTierScope {
+  /** The class whose instances ARE the tiers (e.g. `ds:Tier`). */
+  readonly type: string;
+  /** The entity → tier edge (e.g. `ds:tier`), same term as `scopeWeight.via`. */
+  readonly via: string;
+  /**
+   * The tier property holding its path-shaped name (e.g. `ds:name`), whose
+   * `/`-separated segments ARE the hierarchy: `Apps/LXD` is a child of `Apps`,
+   * and a name with no `/` is top-level.
+   */
+  readonly by: string;
+  /**
+   * The tier every other tier builds on, in scope whenever a scope is in force
+   * (e.g. `ds:global`).
+   *
+   * DECLARED, not inferred: nothing in the graph says which of the top-level
+   * tiers is the base — the design system's own colophon does ("`global` >
+   * `apps` > `apps/lxd`: a lower tier inherits and overrides the blocks of its
+   * ancestors"), and that is editorial judgement the ontology has not made yet,
+   * so it belongs in the declaration layer beside `weights` and `scopeWeight`.
+   * Without it a narrowed read would hide the very blocks the narrow tier
+   * inherits: `--tier apps_lxd` would answer with LXD's nine and not the 119
+   * global ones every LXD screen is actually built from.
+   */
+  readonly base?: string;
 }
 
 /** A validated pack definition paired with where it was declared. */

package/src/kernel/project/cli/buildProgram.ts

@@ -175,7 +175,23 @@ function attachVerb(
 
   command.action(async (...actionArgs: unknown[]) => {
     const { positionals: positionalArgs, opts } = splitActionArgs(actionArgs);
-    await dispatch(verb, positionalArgs, opts, globalFlags);
+    // `command.args` is every operand this leaf received; the action arguments
+    // are only the DECLARED ones, so a verb that declares none is handed
+    // nothing and a stray word vanishes between the two. Dispatch reads the
+    // longer of the two lists and refuses what the verb cannot take
+    // (`dispatch.ts#refuseExcessPositionals`) — Commander's own excess check
+    // cannot: a sub-verb-only noun opts into excess operands to keep its
+    // "unknown command" suggestion, and `copyInheritedSettings` hands that
+    // opt-in down to every verb attached beneath it.
+    const operands = command.args.filter(
+      (arg): arg is string => typeof arg === "string",
+    );
+    await dispatch(
+      verb,
+      operands.length > positionalArgs.length ? operands : positionalArgs,
+      opts,
+      globalFlags,
+    );
   });
 }
 

package/src/kernel/project/cli/dispatch.test.ts

@@ -379,6 +379,93 @@ describe("dispatch — errors", () => {
   });
 });
 
+describe("a positional the spec cannot hold is refused, not dropped", () => {
+  const savedExit = process.exitCode;
+  afterEach(() => {
+    process.exitCode = savedExit;
+  });
+
+  /** Run `verb` with `positionals` and collect what stderr was told. */
+  async function stderrOf(
+    verb: VerbSpec,
+    positionals: string[],
+  ): Promise<string> {
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    // The verb that is NOT refused runs and prints; keep it out of the report.
+    const out = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    await dispatch(verb, positionals, {}, PLAIN);
+    spy.mockRestore();
+    out.mockRestore();
+    return errs.join("");
+  }
+
+  /** A verb addressed by a flag, the shape `variable chain` has. */
+  const chain: VerbSpec = {
+    path: ["gizmo", "chain"],
+    summary: "Walk a gizmo.",
+    params: [
+      { kind: "string", name: "gizmo", doc: "The gizmo." },
+      { kind: "number", name: "limit", doc: "Rows." },
+    ],
+    output: { formatters: passthroughFormatters },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async () => ({ walked: true }),
+  };
+
+  it("names the flag the value belonged to, and exits 2", async () => {
+    const out = await stderrOf(chain, ["color-text"]);
+
+    expect(out).toContain(
+      '`pragma gizmo chain` takes no positional argument, but received "color-text".',
+    );
+    expect(out).toContain("Did you mean `--gizmo color-text`?");
+    expect(process.exitCode).toBe(2);
+  });
+
+  it("points at --help when no flag could have held it", async () => {
+    const bare: VerbSpec = { ...chain, params: [] };
+
+    const out = await stderrOf(bare, ["color-text"]);
+
+    expect(out).toContain("takes no positional argument");
+    expect(out).toContain("run `pragma gizmo chain --help`");
+  });
+
+  it("refuses one MORE than the spec declares", async () => {
+    const out = await stderrOf(echo, ["hello", "spare"]);
+
+    expect(out).toContain(
+      '`pragma probe echo` takes 1 positional argument, but received an extra "spare".',
+    );
+  });
+
+  it("leaves a variadic verb alone — its tail is the point", async () => {
+    const many: VerbSpec = {
+      ...echo,
+      params: [
+        {
+          kind: "string[]",
+          name: "name",
+          doc: "Names.",
+          positional: true,
+          required: true,
+        },
+      ],
+      run: async (p) => (p as { name: string[] }).name,
+    };
+
+    expect(await stderrOf(many, ["one", "two", "three"])).toBe("");
+  });
+});
+
 describe("--dry-run is honest (PRA-104)", () => {
   const savedExit = process.exitCode;
   afterEach(() => {

package/src/kernel/project/cli/dispatch.ts

@@ -13,6 +13,7 @@
 
 import { describeEffect, type Effect, type Task } from "@canonical/task";
 import { runPreview, runTask, runUndo } from "@canonical/task/node";
+import { BIN_NAME } from "../../../constants.js";
 import {
   asPragmaError,
   CANCELLED_MESSAGE,
@@ -34,7 +35,7 @@ import type {
   InteractionRuntime,
   PragmaRuntime,
 } from "../../runtime/types.js";
-import type { ParamSpec, VerbSpec } from "../../spec/index.js";
+import { kebabCase, type ParamSpec, type VerbSpec } from "../../spec/index.js";
 import { EXIT, mapExitCode } from "./exitCodes.js";
 
 /** The CLI-only mutation flags auto-injected onto every mutating verb. */
@@ -177,9 +178,17 @@ function renderData(
     // (`mcp/registerVerb.ts#noticeMeta`) — the two machine surfaces stay
     // byte-equal.
     const notice = verb.output.formatters.notice?.(data);
+    // The machine half of the same seam: facts the read wants to hand an agent
+    // as data rather than prose (`meta.scope`). MCP merges the same seam into
+    // the same keys (`mcp/registerVerb.ts#readMeta`).
+    const extra = verb.output.formatters.meta?.(data);
     return {
       stdout: `${JSON.stringify(
-        successEnvelope(projection, notice ? { ...meta, notice } : meta),
+        successEnvelope(projection, {
+          ...meta,
+          ...(extra ?? {}),
+          ...(notice ? { notice } : {}),
+        }),
       )}\n`,
       exitCode: 0,
     };
@@ -411,7 +420,29 @@ export async function executeVerb(
       }
     }
     if (mutation.undo) {
-      const { undoCount } = await runUndo(task, { onLog: logSink(flags) });
+      // The truth seam. `runUndo`'s collection phase drove the verb's task
+      // with every effect mocked, so anything the task body reported was a
+      // narration of the mocked walk, not of the reversals — which have only
+      // JUST run, each isolated, each with its own outcome. Those outcomes
+      // are the one honest record of what the undo did: a verb that reports
+      // per-target results sets `undoReport` (like `exec`/`planData`) and
+      // projects them onto its own rows; a throw from it renders as the
+      // run's error, exactly like a failed real run. Verbs without a
+      // projector of their own still may not exit 0 over a failed reversal,
+      // so the outcomes are re-checked here as the backstop.
+      const { undoCount, outcomes } = await runUndo(task, {
+        onLog: logSink(flags),
+      });
+      await mutationRuntime.undoReport?.(outcomes);
+      const failed = outcomes.filter((o) => o.status === "failed");
+      if (failed.length > 0) {
+        throw new PragmaError({
+          code: "UNSUPPORTED",
+          message: `${failed.length} of ${outcomes.length} undo step(s) did not complete: ${failed
+            .map((o) => o.error.message)
+            .join("; ")}`,
+        });
+      }
       return renderUndo(flags, undoCount);
     }
     // Real execution: spread the verb's runner options into the node
@@ -508,12 +539,91 @@ export async function dispatch(
   };
   await runPrepared(
     verb,
-    () => extractParams(verb.params, positionals, opts),
+    () => {
+      refuseExcessPositionals(verb, positionals);
+      return extractParams(verb.params, positionals, opts);
+    },
     mutation,
     globalFlags,
   );
 }
 
+/**
+ * Refuse a positional the verb's spec has nowhere to put.
+ *
+ * `extractParams` maps positionals onto DECLARED positional params and drops
+ * the rest, so `pragma variable chain color-text` — whose story takes its
+ * subject as `--variable` — ran the unfiltered chain and printed 300 unrelated
+ * rows, having silently discarded the one word the user cared about. A wrong
+ * answer with no diagnostic is worse than a refusal.
+ *
+ * The refusal names the flag the value most likely belongs to: the verb's own
+ * noun as a flag (`variable chain` → `--variable`), else its first
+ * value-taking flag. That is the identity filter for every story shaped like
+ * this one, and where it is not, the flag list is one `--help` away.
+ *
+ * @param verb - The verb the user invoked.
+ * @param positionals - The operands Commander collected for it.
+ * @throws PragmaError INVALID_INPUT when more operands arrived than the spec
+ *   declares (a variadic positional absorbs the tail, so it never trips).
+ */
+function refuseExcessPositionals(
+  verb: VerbSpec,
+  positionals: readonly string[],
+): void {
+  const declared = verb.params.filter((param) => param.positional);
+  if (declared.some((param) => param.kind === "string[]")) return;
+  const excess = positionals[declared.length];
+  if (excess === undefined) return;
+  const command = `${BIN_NAME} ${verb.path.join(" ")}`;
+  const flag = suggestedFlag(verb);
+  throw new PragmaError({
+    code: "INVALID_INPUT",
+    message:
+      declared.length === 0
+        ? `\`${command}\` takes no positional argument, but received "${excess}".`
+        : `\`${command}\` takes ${declared.length} positional argument${
+            declared.length === 1 ? "" : "s"
+          }, but received an extra "${excess}".`,
+    recovery: {
+      message: flag
+        ? `Did you mean \`--${flag} ${excess}\`?`
+        : `Pass values as flags — run \`${command} --help\` to see them.`,
+    },
+  });
+}
+
+/**
+ * The flag a stray positional most likely belonged to.
+ *
+ * The verb's NOUN first (`variable chain` declares `--variable`, which is the
+ * identity filter every such story is addressed by), then the first flag that
+ * takes a value at all. Paging and disclosure flags are never the answer — a
+ * bare word is not a cursor.
+ *
+ * @param verb - The verb the user invoked.
+ * @returns The flag name (without dashes), or undefined when none fits.
+ */
+function suggestedFlag(verb: VerbSpec): string | undefined {
+  const candidates = verb.params.filter(
+    (param) =>
+      !param.positional &&
+      param.kind !== "boolean" &&
+      !GENERIC_FLAGS.has(param.name),
+  );
+  const identity = candidates.find((param) => param.name === verb.path[0]);
+  const flag = identity ?? candidates[0];
+  return flag ? kebabCase(flag.name) : undefined;
+}
+
+/** Flags that answer no question a stray word could be the answer to. */
+const GENERIC_FLAGS: ReadonlySet<string> = new Set([
+  "limit",
+  "after",
+  "detail",
+  "count",
+]);
+
 /**
  * Dispatch a verb whose params were ALREADY extracted by the caller — the
  * seam a mounted subtree drives: its leaf specs carry no Commander defaults