@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/kernel/error/validOptions.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { formatValidOptions, MAX_LISTED_OPTIONS } from "./validOptions.js";
+
+/** `count` option names, distinct and ordered. */
+function options(count: number): string[] {
+  return Array.from({ length: count }, (_, index) => `option-${index}`);
+}
+
+describe("formatValidOptions", () => {
+  it("names every option when the vocabulary is a choice", () => {
+    // Every real filter at or below the cap renders in full: the type filter
+    // at 7, the tier filter at 16, the coordinate set at 36.
+    const line = formatValidOptions(["color", "dimension", "duration"]);
+
+    expect(line).toBe("Valid options: color, dimension, duration");
+  });
+
+  it("names every option at exactly the cap", () => {
+    const line = formatValidOptions(options(MAX_LISTED_OPTIONS));
+
+    expect(line).toContain(`option-${MAX_LISTED_OPTIONS - 1}`);
+    expect(line).not.toContain("more");
+  });
+
+  it("withholds the tail one past the cap, and counts it", () => {
+    const line = formatValidOptions(options(MAX_LISTED_OPTIONS + 1));
+
+    expect(line).toContain(`(${MAX_LISTED_OPTIONS + 1})`);
+    expect(line).toContain("and 1 more");
+    expect(line).not.toContain(`option-${MAX_LISTED_OPTIONS}`);
+  });
+
+  it("keeps a catalogue-sized vocabulary to a readable line", () => {
+    // The case that forced this: the variable filter's vocabulary is 1,156
+    // names, and naming them all rendered roughly 90KB — unreadable in a
+    // terminal, and large enough over MCP to threaten the payload budget.
+    const line = formatValidOptions(options(1156));
+
+    expect(line).toContain("(1156)");
+    expect(line).toContain("and 1116 more");
+    expect(line.length).toBeLessThan(2000);
+  });
+
+  it("carries a caller's own prefix", () => {
+    // The prefix seam is how a caller that renders its OWN options line names
+    // the flag. Nothing in the error path passes one any more: the renderers
+    // print the vocabulary once, from `validOptions`, and a recovery that
+    // enumerated it too printed the same catalogue twice.
+    const line = formatValidOptions(
+      options(1156),
+      "Values allowed for --variable",
+    );
+
+    expect(line.startsWith("Values allowed for --variable (1156)")).toBe(true);
+    expect(line.length).toBeLessThan(2000);
+  });
+});

package/src/kernel/error/validOptions.ts

@@ -0,0 +1,45 @@
+/**
+ * Naming a filter's admissible values without printing a catalogue.
+ *
+ * ONE error, ONE list. The vocabulary rides an error's `validOptions`, and the
+ * renderers here are the only place it is spelled out — a filter that also
+ * enumerated it in its `recovery` message printed the same 40 names twice,
+ * about 1.4KB of duplicate terminal output on a single mistyped `--symbol`. A
+ * recovery says what to DO; the options line says what the values ARE.
+ */
+
+/**
+ * How many valid options a rendered error names before it stops listing them.
+ *
+ * Taken from the real vocabularies rather than picked round: the largest a
+ * reader can usefully scan is the coordinate set at 36, so every filter at or
+ * below this cap still renders in full. Above it sit the vocabularies that are
+ * catalogues rather than choices — variables at 1,156, symbols at 745, blocks
+ * at 252 — and naming those turned one mistyped filter value into roughly 90KB
+ * of terminal output, or an MCP response large enough to threaten its own
+ * payload budget. The JSON error envelope still carries every option, so a
+ * machine consumer loses nothing.
+ */
+export const MAX_LISTED_OPTIONS = 40;
+
+/**
+ * Render an admissible-value list, naming at most {@link MAX_LISTED_OPTIONS}.
+ *
+ * The count of what is withheld is the useful part of a long vocabulary: it
+ * tells the reader this is a catalogue to list, not a choice to read.
+ *
+ * @param options - Every accepted value, in the order the caller supplies.
+ * @param prefix - How the line introduces the values.
+ * @returns One line, with no trailing newline and no full stop.
+ */
+export function formatValidOptions(
+  options: readonly string[],
+  prefix = "Valid options",
+): string {
+  if (options.length <= MAX_LISTED_OPTIONS) {
+    return `${prefix}: ${options.join(", ")}`;
+  }
+  const shown = options.slice(0, MAX_LISTED_OPTIONS).join(", ");
+  const rest = options.length - MAX_LISTED_OPTIONS;
+  return `${prefix} (${options.length}), first ${MAX_LISTED_OPTIONS}: ${shown}, and ${rest} more`;
+}

package/src/kernel/packs/collect.test.ts

@@ -259,6 +259,8 @@ describe("validateStories — package stories NEVER throw (PROTECTED)", () => {
     const before = capabilities.find((module) => module.name === "token");
     expect(before?.verbs.map((verb) => verb.path.join(" "))).toEqual([
       "token list",
+      "token values",
+      "token consumers",
       "token lookup",
       "token sample",
     ]);

package/src/kernel/packs/compile.test.ts

@@ -10,11 +10,16 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/types.js";
+import { kebabCase } from "../spec/emitSurface.js";
+import type { VerbSpec } from "../spec/types.js";
 import { compileListable, compilePack, compileStoryModule } from "./compile.js";
+import { encodeCursor, pageFingerprint } from "./cursor.js";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_WINDOW } from "./paging.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
-import type { PackDefinition, PackRow } from "./types.js";
+import type { PackDefinition, PackPage, PackRow } from "./types.js";
 import { distributionSource } from "./types.js";
 import { assertUniqueVerbs, verbKey } from "./uniqueness.js";
 
@@ -135,7 +140,14 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
       distributionSource("bundled:widget"),
       PREFIXES,
     );
-    expect(list?.params.map((p) => p.name)).toEqual(["kind", "search"]);
+    // The page pair is the KERNEL's, on every list-shaped verb whether the
+    // story mentions it or not — see compile.ts#PAGE_PARAMS.
+    expect(list?.params.map((p) => p.name)).toEqual([
+      "kind",
+      "search",
+      "limit",
+      "after",
+    ]);
     const kind = list?.params.find((p) => p.name === "kind");
     expect(kind?.kind).toBe("enum");
     expect(list?.capability.needsStore).toBe(true);
@@ -248,8 +260,8 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
 
   it("rejects a filter param declared twice, on list or on an extra verb", () => {
     const twice = [
-      { param: "kind", variable: "uri" },
-      { param: "kind", variable: "uri" },
+      { param: "kind", variable: "uri", values: ["a"] },
+      { param: "kind", variable: "uri", values: ["a"] },
     ];
     expect(
       parse({ noun: "widget", list: { ...listShape, filters: twice } }),
@@ -263,6 +275,51 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
     ).toThrow(/filter param "kind" is declared twice/);
   });
 
+  it("admits a camelCase filter param, and it reaches the flag the projector spells", () => {
+    // The grammar and the projector have to agree about what a param name may
+    // be. `emitVerb` writes a flag as `--${kebabCase(param)}`, so a two-word
+    // dimension only has a readable spelling if the param may carry the hump —
+    // and the gate used to refuse the one spelling that projects well while
+    // admitting `channelof`, which projects to `--channelof`.
+    const definition = parsePackDefinition(
+      {
+        noun: "widget",
+        list: {
+          query:
+            "SELECT ?uri ?channelOf WHERE { ?uri ex:channelOf ?channelOf }",
+          columns: [{ field: "uri" }, { field: "channelOf" }],
+          filters: [
+            { param: "channelOf", variable: "channelOf", values: ["a"] },
+          ],
+        },
+      },
+      "pkg/stories/widget.json",
+    );
+    const list = compilePack(
+      definition,
+      distributionSource("pkg/stories/widget.json"),
+      PREFIXES,
+    ).find((verb) => verbKey(verb.path) === "widget list") as VerbSpec;
+    // The MCP key keeps the declared spelling; the CLI flag is its kebab form.
+    expect(list.params.map((param) => param.name)).toContain("channelOf");
+    expect(`--${kebabCase("channelOf")}`).toBe("--channel-of");
+  });
+
+  it("still refuses a filter param that does not start lowercase", () => {
+    // A leading capital would kebab to a LEADING DASH, and Commander would
+    // register a flag with an empty name — outside every error envelope the
+    // CLI owns. The widening is the hump, not the initial.
+    expect(
+      parse({
+        noun: "widget",
+        list: {
+          ...listShape,
+          filters: [{ param: "ChannelOf", variable: "uri", values: ["a"] }],
+        },
+      }),
+    ).toThrow();
+  });
+
   it("still accepts the distinct forms, and they compile to unique keys/params", () => {
     const definition = parsePackDefinition(
       {
@@ -270,8 +327,8 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
         list: {
           ...listShape,
           filters: [
-            { param: "kind", variable: "uri" },
-            { param: "tier", variable: "uri" },
+            { param: "kind", variable: "uri", values: ["a"] },
+            { param: "tier", variable: "uri", values: ["b"] },
           ],
         },
         verbs: [{ ...listShape, verb: "categories" }],
@@ -291,7 +348,12 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
       "widget sample",
     ]);
     expect(() => assertUniqueVerbs(verbs)).not.toThrow();
-    expect(verbs.at(0)?.params.map((p) => p.name)).toEqual(["kind", "tier"]);
+    expect(verbs.at(0)?.params.map((p) => p.name)).toEqual([
+      "kind",
+      "tier",
+      "limit",
+      "after",
+    ]);
   });
 
   it("names the shape a noun must have, not the regex", () => {
@@ -331,6 +393,24 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
     (await rt.store.get()).store.dispose();
   });
 
+  /**
+   * The INVALID_INPUT recovery a call raises, which is where a pack error puts
+   * the sentence a caller acts on — the factory's own message is the uniform
+   * `Invalid <field> "<value>".`
+   */
+  const recoveryOf = async (call: () => Promise<unknown>): Promise<string> => {
+    try {
+      await call();
+    } catch (error) {
+      if (error instanceof PragmaError) {
+        expect(error.code).toBe("INVALID_INPUT");
+        return error.recovery?.message ?? "";
+      }
+      throw error;
+    }
+    throw new Error("expected the call to be refused");
+  };
+
   const run = <R>(verbLabel: string, params: Record<string, unknown>) => {
     const verb = compilePack(
       WIDGET_PACK,
@@ -342,19 +422,112 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
   };
 
   it("lists rows in the uniform pack shape", async () => {
-    const rows = await run<PackRow[]>("list", {});
-    expect(rows.map((r) => r.name)).toEqual(["Button", "Label"]);
-    expect(rows[0]?.uri).toBe("https://example.org/widgets#button");
+    const page = await run<PackPage>("list", {});
+    expect(page.rows.map((r) => r.name)).toEqual(["Button", "Label"]);
+    expect(page.rows[0]?.uri).toBe("https://example.org/widgets#button");
+    // The whole population fits the default page, so nothing is withheld and
+    // there is no cursor to spend.
+    expect(page.nextAfter).toBeUndefined();
+    expect(page.limit).toBe(DEFAULT_LIST_LIMIT);
   });
 
-  it("filters by an enum value (post-query row predicate)", async () => {
-    const rows = await run<PackRow[]>("list", { kind: "input" });
-    expect(rows.map((r) => r.name)).toEqual(["Button"]);
+  it("filters by an enum value, compiled into the query", async () => {
+    const page = await run<PackPage>("list", { kind: "input" });
+    expect(page.rows.map((r) => r.name)).toEqual(["Button"]);
   });
 
   it("searches case-insensitively", async () => {
-    const rows = await run<PackRow[]>("list", { search: "lab" });
-    expect(rows.map((r) => r.name)).toEqual(["Label"]);
+    const page = await run<PackPage>("list", { search: "lab" });
+    expect(page.rows.map((r) => r.name)).toEqual(["Label"]);
+  });
+
+  it("pages inside the query: a page, its successor, and their union", async () => {
+    const whole = await run<PackPage>("list", {});
+    const first = await run<PackPage>("list", { limit: 1 });
+    expect(first.rows).toEqual([whole.rows[0]]);
+    expect(first.nextAfter).toBeTypeOf("string");
+    const second = await run<PackPage>("list", {
+      limit: 1,
+      after: first.nextAfter,
+    });
+    expect(second.rows).toEqual([whole.rows[1]]);
+    // The last page reports no successor, and one past it is a calm empty page
+    // rather than an error.
+    expect(second.nextAfter).toBeUndefined();
+    const past = await run<PackPage>("list", {
+      limit: 1,
+      after: encodeCursor(
+        9,
+        pageFingerprint([WIDGET_PACK.list?.query ?? "", "[]", "null"]),
+      ),
+    });
+    expect(past.rows).toEqual([]);
+  });
+
+  it("refuses a cursor issued for a different read", async () => {
+    const filtered = await run<PackPage>("list", { limit: 1, kind: "input" });
+    const unfiltered = await run<PackPage>("list", { limit: 1 });
+    // Spending the unfiltered read's cursor on the filtered one would answer a
+    // page of the wrong question, with nothing in the payload to show it.
+    await expect(
+      recoveryOf(() =>
+        run<PackPage>("list", {
+          limit: 1,
+          kind: "input",
+          after: unfiltered.nextAfter,
+        }),
+      ),
+    ).resolves.toMatch(/issued for a different read/);
+    expect(filtered.nextAfter).toBeUndefined();
+  });
+
+  it("refuses a limit that is not a whole number of rows", async () => {
+    await expect(
+      recoveryOf(() => run<PackPage>("list", { limit: 0 })),
+    ).resolves.toMatch(new RegExp(`1 to ${MAX_LIST_WINDOW}`));
+  });
+
+  it("refuses a limit above the ceiling, naming it", async () => {
+    // `--limit 9007199254740991` is the natural "give me everything" an agent
+    // writes, and it used to reach the store's own `LIMIT` — which must fit a
+    // 32-bit integer — and come back as a parse error dressed as
+    // INTERNAL_ERROR with "report this issue". A typed refusal that says what
+    // it would accept is the answer to a legitimate question asked too big.
+    for (const limit of [MAX_LIST_WINDOW + 1, 2 ** 32 - 1, 1e21, 2 ** 53 - 1]) {
+      await expect(
+        recoveryOf(() => run<PackPage>("list", { limit })),
+      ).resolves.toMatch(new RegExp(`1 to ${MAX_LIST_WINDOW}`));
+    }
+    // The ceiling itself is admitted: a refusal one row early would be a
+    // different bug.
+    await expect(
+      run<PackPage>("list", { limit: MAX_LIST_WINDOW }),
+    ).resolves.toBeDefined();
+  });
+
+  it("refuses a cursor whose offset is above the ceiling", async () => {
+    // The fingerprint covers the query and the arguments, not the offset — so
+    // a real cursor with only `o` edited is fingerprint-valid, and that is the
+    // path by which an unbounded offset reached the query's own `OFFSET`.
+    const fingerprint = pageFingerprint([
+      WIDGET_PACK.list?.query ?? "",
+      "[]",
+      "null",
+    ]);
+    await expect(
+      recoveryOf(() =>
+        run<PackPage>("list", {
+          limit: 1,
+          after: encodeCursor(2 ** 53 - 1, fingerprint),
+        }),
+      ),
+    ).resolves.toMatch(/cursor from a previous page/);
+    // An offset the kernel can serve is still served, empty page and all.
+    const edge = await run<PackPage>("list", {
+      limit: 1,
+      after: encodeCursor(MAX_LIST_WINDOW, fingerprint),
+    });
+    expect(edge.rows).toEqual([]);
   });
 
   it("looks up an entity by name with its fields and expands (detailed)", async () => {

package/src/kernel/packs/compile.ts

@@ -15,6 +15,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
+import { PragmaError } from "../error/index.js";
 import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
 import { asVerb } from "../spec/asVerb.js";
@@ -25,6 +26,7 @@ import type {
   ParamSpec,
   VerbSpec,
 } from "../spec/types.js";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_WINDOW } from "./paging.js";
 import {
   listFormatters,
   lookupFormatters,
@@ -37,14 +39,18 @@ import {
   MIN_SAMPLE_COUNT,
   sampleDefaultCount,
 } from "./sample.js";
-import type {
-  PackDefinition,
-  PackFilter,
-  PackList,
-  PackLookup,
-  PackRow,
-  PackSearch,
-  StorySource,
+import { storyIssues } from "./storyRules.js";
+import {
+  EVERY_TIER,
+  type PackDefinition,
+  type PackFilter,
+  type PackList,
+  type PackLookup,
+  type PackPage,
+  type PackSearch,
+  type PackTierScope,
+  type StorySource,
+  TIER_PARAM,
 } from "./types.js";
 
 // The run bodies pull the SPARQL/GraphQL fetch layer; they are dynamic-imported
@@ -78,6 +84,8 @@ export function compilePack(
   const { noun } = definition;
   const verbs: VerbSpec[] = [];
 
+  const tierScope = definition.tierScope;
+
   if (definition.list) {
     verbs.push(
       compileListVerb(definition.list, {
@@ -87,6 +95,7 @@ export function compilePack(
         doc: definition.toolDescription,
         source,
         prefixes,
+        ...(tierScope ? { tierScope } : {}),
       }),
     );
   }
@@ -100,12 +109,15 @@ export function compilePack(
         doc: verb.toolDescription,
         source,
         prefixes,
+        ...(tierScope ? { tierScope } : {}),
       }),
     );
   }
 
   if (definition.lookup) {
-    verbs.push(compileLookupVerb(definition.lookup, noun, source, prefixes));
+    verbs.push(
+      compileLookupVerb(definition.lookup, noun, source, prefixes, tierScope),
+    );
     if (definition.lookup.sample) {
       verbs.push(compileSampleVerb(definition.lookup, noun, source, prefixes));
     }
@@ -171,16 +183,33 @@ export function compileListable(
  * through here alike, so a module-level projection derived from the story
  * (today: {@link compileListable}) cannot reach one tier and miss the other.
  *
+ * That door is also where the COMPILABILITY rules are checked
+ * ({@link ./storyRules.storyIssues}), for the same reason. The zod grammar runs
+ * for config- and package-declared stories only, so a rule stated only there
+ * was a declaration-time refusal for a third-party author and a first-call
+ * CONFIG_ERROR for the distribution's own stories. The rules are pure string
+ * work over text the story already carries, which is what makes them affordable
+ * on this path; a story that passed zod has passed them already, so the throw
+ * below is reachable only for a story that never saw zod.
+ *
  * @param definition - A validated pack definition.
  * @param source - Where the definition came from, for diagnostics.
  * @param prefixes - The merged prefix map used for display compaction.
  * @returns The module: the compiled verbs plus the story's module-level data.
+ * @throws PragmaError CONFIG_ERROR when the definition cannot be compiled,
+ *   naming the field and the rule.
  */
 export function compileStoryModule(
   definition: PackDefinition,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): CapabilityModule {
+  const issue = storyIssues(definition)[0];
+  if (issue) {
+    throw PragmaError.configError(
+      `Invalid story in ${source.label} at ${issue.path.join(".")}: ${issue.message}`,
+    );
+  }
   const listable = compileListable(definition);
   return {
     name: definition.noun,
@@ -200,6 +229,8 @@ interface ListVerbMeta {
   readonly doc?: string;
   readonly source: StorySource;
   readonly prefixes: Readonly<Record<string, string>>;
+  /** The noun's declared tier hierarchy, when its entities are tiered. */
+  readonly tierScope?: PackTierScope;
 }
 
 /** Compile the `list` verb or an extra list-shaped verb. */
@@ -207,9 +238,11 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
   const params = [
     ...projectFilters(shape.filters),
     ...projectSearch(shape.search),
+    ...tierParams(meta.tierScope),
+    ...PAGE_PARAMS,
   ];
   const filterExample = shape.filters?.find((f) => f.values !== undefined);
-  const verb: VerbSpec<Record<string, unknown>, PackRow[]> = {
+  const verb: VerbSpec<Record<string, unknown>, PackPage> = {
     path: [meta.noun, meta.verb],
     summary: meta.summary,
     ...(meta.doc ? { doc: meta.doc } : {}),
@@ -237,7 +270,10 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
       runBodies().then((m) =>
-        m.makeListRun(shape, { source: meta.source })(params, rt),
+        m.makeListRun(shape, {
+          source: meta.source,
+          ...(meta.tierScope ? { tierScope: meta.tierScope } : {}),
+        })(params, rt),
       ),
   };
   return asVerb(verb);
@@ -249,6 +285,7 @@ function compileLookupVerb(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  tierScope?: PackTierScope,
 ): VerbSpec {
   // Derive-by-default: every lookup completes its `<name>` from the pack index
   // (empty type = any, the reader handles it), UNLESS the pack opts out
@@ -282,21 +319,55 @@ function compileLookupVerb(
     summary:
       lookup.description ?? `Look up ${noun} details by name, IRI, or glob.`,
     ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
-    params: [nameParam],
+    params: [nameParam, ...tierParams(tierScope)],
     output: { formatters: lookupFormatters(lookup, prefixes) },
-    examples: [{ cmd: `${BIN_NAME} ${noun} lookup <name>` }],
+    examples: [
+      { cmd: `${BIN_NAME} ${noun} lookup <name>` },
+      ...(tierScope
+        ? [
+            {
+              cmd: `${BIN_NAME} ${noun} lookup --tier all <name>`,
+              note: "every tier, not just the ones in scope",
+            },
+          ]
+        : []),
+    ],
     ...(lookup.disclosure
       ? { disclosure: disclosureSpec(lookup.disclosure) }
       : {}),
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
       runBodies().then((m) =>
-        m.makeLookupRun(lookup, noun, source, prefixes)(params, rt),
+        m.makeLookupRun(lookup, noun, source, prefixes, tierScope)(params, rt),
       ),
   };
   return asVerb(verb);
 }
 
+/**
+ * The `--tier` parameter a TIERED noun's reads carry (`tier` over MCP).
+ *
+ * Kernel-added, like the page: being tiered is declared, but the argument that
+ * steers the scope is the kernel's to name — one spelling across every tiered
+ * noun, so an agent that learned `--tier` on `block list` can use it on
+ * `concept list` without asking. The help text names the default and the
+ * escape, because a scope a caller cannot see is exactly the hidden behaviour
+ * CONSTITUTION §VI rules out.
+ *
+ * Not `repeatable`: a repeated `--tier` would be two chains, and the scope is
+ * one chain. The run body refuses an array rather than quietly taking the last.
+ */
+function tierParams(tierScope: PackTierScope | undefined): ParamSpec[] {
+  if (!tierScope) return [];
+  return [
+    {
+      kind: "string",
+      name: TIER_PARAM,
+      doc: `Read this tier and its ancestors (default: the top-level tiers; "${EVERY_TIER}" for every tier).`,
+    },
+  ];
+}
+
 /** Compile the `sample` verb (N random exemplars at the highest level). */
 function compileSampleVerb(
   lookup: PackLookup,
@@ -355,6 +426,30 @@ function disclosureSpec(disclosure: PackLookup["disclosure"]): DisclosureSpec {
   };
 }
 
+/**
+ * The page parameters EVERY list-shaped verb carries — `list` and every extra
+ * verb alike.
+ *
+ * Not declared per story, and not declarable: a page is a property of a
+ * list-shaped read, so a story that forgot to declare one would be the one
+ * answer an agent could not bound. The default is named in the help text
+ * because a cap a caller cannot see is exactly the hidden behaviour
+ * CONSTITUTION §VI rules out — the number a caller gets when they pass nothing
+ * has to be readable in `--help`.
+ */
+const PAGE_PARAMS: readonly ParamSpec[] = [
+  {
+    kind: "number",
+    name: "limit",
+    doc: `Maximum rows to return, 1 to ${MAX_LIST_WINDOW} (default ${DEFAULT_LIST_LIMIT}).`,
+  },
+  {
+    kind: "string",
+    name: "after",
+    doc: "Continue from a previous page: the cursor that page reported.",
+  },
+];
+
 /** Project declared filters onto verb params (enum for a value set, else string). */
 function projectFilters(
   filters: readonly PackFilter[] | undefined,