@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/testing/perf/budgets.ts

@@ -19,83 +19,167 @@
  * p95, and it lands TIGHTER than 2× its median); its arithmetic is written out
  * in full in BUDGETS.md, as are the measurements and environment for all of
  * them.
+ *
+ * A CEILING IS ALSO RELATIVE TO WHAT THE SURFACE HAS GROWN INTO. Re-derived
+ * again 2026-09-10, because three of the five had drifted red for two causes,
+ * both of them real work rather than noise: the eagerly-imported capability
+ * barrel grew 37.6 → 68.0 ms as the surface reached 22 capability modules and
+ * 42 MCP tools, and the embedded pack grew 8 479 → 49 630 triples. Every
+ * constant below names its cause, because a raised ceiling with no cause is
+ * just a lower standard. The two in-process ceilings were re-measured and
+ * DELIBERATELY LEFT ALONE — they have three orders of magnitude of headroom.
+ *
+ * THIS PASS IS NOT RUN BY CI — owner ruling 2026-08-30, restated 2026-09-10.
+ * Nothing reaches it indirectly either: `test` does not chain it, no Nx target
+ * or workflow names it, and the repo has no git hooks. See
+ * `vitest.perf.config.ts`, `docs/CI.md` and BUDGETS.md.
+ *
+ * EVERY CEILING HERE IS LATENCY. The one SIZE budget the package enforces on a
+ * verb — a list-shaped answer's payload — deliberately does not live here: it
+ * is a property of the payload rather than of wall-clock time, so it needs
+ * neither the serial pass nor the spawned binary, — and a budget nothing
+ * runs is not a gate. It sits where the payload is built, in
+ * `capabilities/listBudget.shipped.exec.test.ts`, as the MCP resource
+ * listing's own ceiling does in `capabilities/resources/resources.test.ts`.
  */
 
 /**
- * `pragma --help` ceiling (ms). Designed 50; the rule is 2× the measured median.
- *
- * Down from the provisional 220, which covered the create surface's eager
- * registration imports on the capabilities barrel. Those are gone — the
- * registered flag spellings are baked into `createSurface.generated.ts` at
- * build time, the mount's adapter loads behind `CliProjection.prepare()`, and
- * the bare-help path no longer loads Commander at all — and the lazy-graph
- * guard in `lazy.test.ts` pins all three so the cost cannot creep back
- * silently.
- *
- * MEASURED, paired: the pre-refactor tree and this one were each built and
- * spawned alternately, 40 kept samples per cell, so drift on a shared box hits
- * both arms. Median 74.6 → 64.7 ms; net of each arm's own `--version` control,
- * the work this path does went 49.3 → 35.3 ms (−28%). 2 × 64.7 = 129.5, so
- * 130 is the rule's own number rather than a number the rule tolerates. It is
- * also where this path sat before the regression. BUDGETS.md carries the full
- * table, the reference-box projection, and why this is the floor.
+ * `pragma --help` ceiling (ms). Designed 50 — **not met, and recorded as such**
+ * for the same reason as {@link BUDGET_COMPLETE_MS}: node's own start is most
+ * of that number before pragma runs a line. The rule is 2× the measured median.
+ *
+ * Up from 130, re-derived 2026-09-10. 130 *was* the rule's own number, back
+ * when this path's work was 35.3 ms net of process start; it is not any more.
+ * The eagerly-imported capability barrel (`capabilities/index`) now costs
+ * **68.0 ms** to import where the recovery A/B measured 37.6 — the surface
+ * grew to 22 capability modules and 42 MCP tools, and each one puts its spec +
+ * formatter modules on this path. `lazy.test.ts` is green, so this is SURFACE
+ * GROWTH and not a lazy-boundary leak: summon-core's projection, its Commander
+ * adapter, `commander`, zod and oxigraph are all still absent from the
+ * fast-path graph. The barrel import is now essentially the whole of the cost
+ * (68.0 of 69.1 ms), which is where any future cut has to come from.
+ *
+ * MEASURED (2026-09-10; five load-gated repetitions × 40 kept samples,
+ * interleaved with an in-run `--version` control of 34.8 ms): median
+ * **103.3 ms**, p95 134.0 ms, work **69.1 ms** net of the control.
+ * `2 × 103.3 = 206.6`, so **210**. The reference-box projection cross-checks
+ * LOOSER, not tighter — `45.5 + 69.1 = 114.6` median → 2× = 229 — so 210 is
+ * the tight side of the rule, exactly as 130 was.
+ *
+ * What this can and cannot separate: at 210 against a 103 ms median it catches
+ * a doubling of the path and no longer catches the ~30 ms the barrel just
+ * gained. It is asserted on median AND raw p95 over 12 kept samples, where a
+ * nearest-rank p95 is effectively the maximum — the worst of 12 protocol
+ * replays here was 200.2 ms, so it holds but without much room. BUDGETS.md
+ * carries the table, the environment, and that flake characterisation.
  */
-export const BUDGET_HELP_MS = 130;
+export const BUDGET_HELP_MS = 210;
 
 /**
  * `pragma __complete …` ceiling (ms). Designed 50 — **not met, and recorded as
  * such**: the shipped entry cannot reach it, because node's own start is most
  * of that number before pragma runs a line.
  *
- * Down from the provisional 220 for the same reason as {@link BUDGET_HELP_MS}:
- * the eager create-surface imports both fast paths paid for are deferred, and
- * completion additionally sheds Commander — nothing on the `__complete`
- * closure imports it any more.
- *
- * MEASURED in the same paired run: median 79.1 → 69.2 ms for the noun case and
- * 74.2 → 69.3 ms for the name-source case; net of the control, 53.7 → 39.7 ms
- * and 48.9 → 39.8 ms.
- *
- * 2× the slower median is 138.5, BELOW this 150 — and it stays 150 anyway,
- * because a ceiling is relative to the box as well as the artifact. This box's
- * cold start is 25–30 ms against the reference box's 45.5; projecting the
- * measured work onto the reference box gives a ~85 ms median, whose 2× is
- * ~170. CI has already run this path at a ~100 ms trimmed mean. Cutting to 140
- * on a local median would be deriving a ceiling on hardware the suite does not
- * run on. Completion is typed interactively, so this stays the budget most
- * worth defending — see BUDGETS.md for the arithmetic.
+ * Up from 150, re-derived 2026-09-10, and for the same single cause as
+ * {@link BUDGET_HELP_MS} — completion pays for the same grown capability
+ * barrel. It still sheds Commander (nothing on the `__complete` closure
+ * imports it), and it still costs ~12 ms more than `--help` because it walks
+ * the grammar and, in the name-source case, the skills directory.
+ *
+ * MEASURED in the same runs, on the SLOWER of the two cases
+ * (`__complete skill lookup do`): median **115.7 ms**, 10%-trimmed mean
+ * 118.6 ms, p95 145.0 ms, work 81.4 ms net of the control. The noun case
+ * (`__complete config`) is median 116.4 / trimmed mean 118.5 ms — the two are
+ * now within a millisecond of each other. `2 × 115.7 = 231.4`, so **240**;
+ * 2× the trimmed mean gives 237.2, the same 240. The reference-box projection
+ * again cross-checks looser (`45.5 + 81.4 = 126.9` → 2× = 254), so 240 is the
+ * tight side of the rule.
+ *
+ * The ceiling is enforced on the trimmed mean, with p95 kept as a SOFT signal
+ * at 1.5× — the statistic change made in the p95-stabilization work, which is
+ * unaffected by this re-derivation. Worst trimmed mean across 8 protocol
+ * replays here: 136.7 ms, so 240 is not a marginal ceiling.
+ *
+ * Completion is typed interactively, so this stays the budget most worth
+ * defending, and it has now lost 90 ms of standard across two re-derivations
+ * with nothing bought back. See BUDGETS.md.
  */
-export const BUDGET_COMPLETE_MS = 150;
+export const BUDGET_COMPLETE_MS = 240;
 
-/** Warm project-config (`pragma.config.ts`) load ceiling (ms). Cache hit is sub-ms. */
+/**
+ * Warm project-config (`pragma.config.ts`) load ceiling (ms). Cache hit is
+ * sub-ms.
+ *
+ * RE-MEASURED 2026-09-10 and deliberately UNCHANGED: 40 warm
+ * `evaluateProjectConfig` calls after priming the content-hash cache give a
+ * median of **0.011 ms** and a p95 of 0.034 ms — roughly 900× of headroom. The
+ * 2×-median rule would put this at 0.02 ms, which would assert nothing but
+ * scheduler jitter. 10 ms is a gross-regression guard (a cache that stopped
+ * hitting, an import that stopped being cached) and that is all it is for.
+ */
 export const BUDGET_PROJECT_CONFIG_MS = 10;
 
 /**
  * Warm store-backed verb ceiling (ms) — a store boot from the cached n-quads
  * dump plus a query, through the shipped entry.
  *
- * Re-derived when the embed became the distribution's real 8 479-triple graph
- * instead of a 23-triple sample. Netted against a `--version` control from the
- * SAME binary in the SAME run (this box's process start swings 60–287 ms with
- * page-cache state alone), the real pack's store work is 2.83× the sample's —
- * the median of five repetitions across two protocols. Projected onto the
- * reference box, whose own toy store work is 147 − 45.5 = 101.5 ms: 45.5 +
- * 101.5 × 2.83 ≈ 333 ms median, and 333 × (176/147) ≈ 398 ms p95 using the
- * reference box's own dispersion for this command. `ceil(398 × 1.25 / 50) × 50`
- * = 500 — which is 1.6× the projected median, i.e. tighter than the
- * 2×-of-median rule the ceilings above use. Every input, every step, and the
- * raw measurements are in BUDGETS.md; the designed `<300ms` target stays in the
- * surface covenant, exactly as the 50 ms `help` target survived its 130 ms
- * ceiling.
+ * Up from 500, re-derived 2026-09-10. The cause is the pack, not the code: the
+ * embed went from the 8 479-triple graph the 500 was derived against to
+ * **49 630 triples / 4 167 entities** (5.85× the triples). Boot still loads
+ * the n-quads dump rather than parsing TTL and still rebuilds the schema from
+ * the extraction artifact rather than running a live 7-pass compile, which is
+ * why the cost grew 1.75× and not 5.85×.
+ *
+ * The arithmetic, on the same route that produced 500, with one new input —
+ * the within-box growth multiplier. This box's netted real store work was
+ * +285.4 ms against the 8 479-triple pack (five repetitions, recorded in
+ * BUDGETS.md) and is +499.9 ms against this one (four load-gated repetitions
+ * × 40 kept samples, 2026-09-10), so:
+ *
+ * ```
+ * within-box growth multiplier  = 499.9 / 285.4                = 1.752
+ * reference store work (old pack) = 101.5 × 2.83               = 287.2 ms
+ * reference store work (new pack) = 287.2 × 1.752              = 503.2 ms
+ * projected reference median      = 45.5 + 503.2               = 548.7 ms
+ * reference p95/median, this command = 176 / 147               = 1.197
+ * projected p95                   = 548.7 × 1.197              = 656.9 ms
+ * ceiling = ceil(656.9 × 1.25 / 50) × 50                       = 850 ms
+ * ```
+ *
+ * The local-only route agrees to within 6%: this box's own measured p95 is
+ * 608.9 ms and `ceil(608.9 × 1.25 / 50) × 50` = 800. The reference-box number
+ * is taken, because that is the route the standing ceiling came from.
+ *
+ * 850 is still **1.55×** the projected median, i.e. tighter than the
+ * 2×-of-median rule the fast paths use. But it is now **2.83×** the designed
+ * `<300ms` target, where 500 was 1.67× — and that gap is the honest headline:
+ * the designed target was set against a 23-triple sample and then held against
+ * 8 479, and a 49 630-triple pack whose store work alone is ~500 ms cannot
+ * reach 300 ms at all. `warmStoreVerb: "<300ms"` stays in the surface covenant
+ * as the aspiration, and it is now an aspiration that needs a different boot
+ * strategy rather than a tuning pass. Every input and every step is in
+ * BUDGETS.md.
+ *
+ * What this can and cannot separate: asserted on median AND p95 over 9 kept
+ * samples, where a nearest-rank p95 IS the maximum — kept deliberately,
+ * because this excess is real work rather than contention noise, and hiding
+ * real cost behind a robust statistic would make the budget lie.
  */
-export const BUDGET_WARM_STORE_MS = 500;
+export const BUDGET_WARM_STORE_MS = 850;
 
 /**
  * Warm in-process MCP tool-call ceiling (ms) — PR7 graduates this from seeded to
  * ENFORCED. Measured over a warm, storeless tool (`capabilities`): pure envelope
  * + dispatch, no store boot, no network, so it isolates the per-call overhead of
- * the grown 38-tool catalog. Measured p95 is ~0.4 ms here (huge headroom), so
- * 100 ms guards against a gross regression without flaking. `info` is
- * deliberately NOT used — its network update-check makes it ~55 ms (see BUDGETS.md).
+ * the grown tool catalog. `info` is deliberately NOT used — its network
+ * update-check makes it ~55 ms (see BUDGETS.md).
+ *
+ * RE-MEASURED 2026-09-10 and deliberately UNCHANGED. The catalog has grown
+ * 38 → 42 tools and the warm call grew with it — p95 **0.732 ms**, trimmed
+ * mean 0.530 ms over 40 calls, against ~0.4 ms p95 at 38 tools — but that is
+ * still ~137× of headroom under 100 ms. This is a gross-regression guard (a
+ * per-call store boot, a network read, a catalog rebuilt per call), and 100 ms
+ * is what lets it be one without flaking. Enforced on the trimmed mean with
+ * p95 as a second check (both ≤ 100).
  */
 export const BUDGET_MCP_P95_WARM_MS = 100;

package/dist/src/kernel/packs/sparql/applyFilters.js

@@ -1,167 +0,0 @@
-/**
- * Apply declared pack filters to resolved list rows.
- *
- * Filters are row predicates on projected SELECT variables — the author query is
- * never modified, so user input cannot inject SPARQL and the query's ordering is
- * preserved. With declared `values` the input is canonicalized against the set
- * (NFC, case-insensitive) and rows are matched case-insensitively; without them
- * the input is a free term matched the same way. A row lacking the variable never
- * matches. Several filters combine conjunctively; several values for one
- * filter (a repeated flag) combine as a union.
- *
- * A filter declaring `match: "set"` reads its cell as a space-separated SET and
- * matches any member — the shape a query produces for a dimension a row belongs
- * to several values of at once (a category and its ancestors, say). The
- * comparison is otherwise identical, so exactly one code path decides what a
- * match is.
- *
- * A value-free filter still REJECTS a value the data does not carry, with the
- * admissible values as `validOptions` — the same courtesy a declared-`values`
- * filter has always extended, without copying the vocabulary into the consumer.
- * The vocabulary is read from the graph, because the graph IS the vocabulary; a
- * story that hard-coded the slugs would go stale the first time the data grew a
- * category. Before this, a typo'd `--category` returned
- * `{"ok":true,"data":[],"meta":{}}` — indistinguishable, over MCP, from a
- * genuinely empty category.
- *
- * WHICH part of the graph is the vocabulary matters, and it is NOT the rows.
- * Rows are a population: a value can be perfectly real while no row carries it —
- * `standard categories` lists a category with count 0, `ds:ConceptType` declares
- * "Decision guide" before any concept uses it. Validating against rows called
- * those `INVALID_INPUT`, when the documented answer is a calm empty list. So a
- * filter DECLARES where its vocabulary lives ({@link PackFilter.vocabulary},
- * resolved by the caller and handed in here), and the observed rows are the
- * fallback for a filter that declares none — the only evidence there is, and
- * knowingly narrower than the truth.
- */
-import { PragmaError } from "../../error/index.js";
-/**
- * @param rows - Rows produced by the pack's list query.
- * @param filters - Declared filters (absent means no filtering).
- * @param params - Story parameters as provided by the surface.
- * @param vocabularies - Authoritative values per filter param, resolved from
- *   each filter's declared `vocabulary` (see {@link FilterVocabularies}).
- * @returns Rows matching every provided filter.
- * @throws PragmaError INVALID_INPUT when a value is not in a filter's declared
- *   set, or when a value-free filter receives a non-string value.
- */
-export function applyPackFilters(rows, filters, params, vocabularies) {
-    let result = rows;
-    for (const filter of filters ?? []) {
-        const provided = params[filter.param];
-        if (provided === undefined)
-            continue;
-        // A repeated CLI flag accumulates into an array; MCP args stay scalar.
-        // Several values for ONE filter are a union (a row matches any of them);
-        // several filters still combine conjunctively.
-        const occurrences = Array.isArray(provided) ? provided : [provided];
-        if (occurrences.length === 0)
-            continue;
-        const values = filter.values;
-        const terms = occurrences.map((occurrence) => values === undefined
-            ? requireStringValue(occurrence, filter).toLowerCase()
-            : canonicalizeFilterValue(occurrence, filter, values).toLowerCase());
-        // The fallback vocabulary is read from the UNFILTERED rows: a value that
-        // exists but is excluded by a conjunction is a legitimately empty answer,
-        // not a bad argument.
-        if (values === undefined)
-            rejectUnknownValue(vocabularies?.get(filter.param) ?? observedValues(rows, filter), filter, occurrences, terms);
-        result = result.filter((row) => cellValues(row, filter).some((value) => terms.includes(value.toLowerCase())));
-    }
-    return result;
-}
-/**
- * The values the rows themselves carry — the fallback vocabulary for a filter
- * that declares no authoritative one, in the data's own DISPLAY spelling.
- */
-function observedValues(rows, filter) {
-    const observed = new Map();
-    for (const row of rows) {
-        for (const value of cellValues(row, filter)) {
-            const key = value.toLowerCase();
-            if (!observed.has(key))
-                observed.set(key, value);
-        }
-    }
-    return [...observed.values()];
-}
-/**
- * Reject a value-free filter value the vocabulary does not admit, naming the
- * ones it does.
- *
- * Silent when the vocabulary is EMPTY: an unbuilt or genuinely-empty store is
- * not the caller's mistake, and the list's own `emptyRecovery` is the right
- * voice for it.
- *
- * A value the vocabulary admits is never rejected here even when no row carries
- * it — a real slug with zero standards is a calm empty list, which is what the
- * tool descriptions document and what `standard categories` reporting count 0
- * promises.
- *
- * @throws PragmaError INVALID_INPUT when a term matches none of the admissible
- *   values, carrying them as `validOptions`.
- */
-function rejectUnknownValue(vocabulary, filter, occurrences, terms) {
-    const admissible = new Map();
-    for (const value of vocabulary) {
-        const key = value.normalize("NFC").toLowerCase();
-        if (!admissible.has(key))
-            admissible.set(key, value.normalize("NFC"));
-    }
-    if (admissible.size === 0)
-        return;
-    const index = terms.findIndex((term) => !admissible.has(term));
-    if (index === -1)
-        return;
-    const validOptions = [...admissible.values()].sort();
-    throw PragmaError.invalidInput(filter.param, String(occurrences[index]), {
-        validOptions,
-        recovery: {
-            message: `Values allowed for --${filter.param}: ${validOptions.join(", ")}.`,
-        },
-    });
-}
-/**
- * The values a row offers for one filter, in their DISPLAY spelling (NFC).
- *
- * One value for an ordinary filter; every space-separated member for a `"set"`
- * one. A row lacking the variable offers none, so it never matches. Kept in the
- * data's own casing because these are also what an INVALID_INPUT lists back as
- * `validOptions` — lowercasing here would hand the caller a value the graph does
- * not spell that way. Comparison lowercases at the point of comparison instead.
- */
-function cellValues(row, filter) {
-    const cell = row[filter.variable];
-    if (cell === undefined)
-        return [];
-    const normalized = cell.normalize("NFC");
-    if (filter.match !== "set") {
-        return normalized === "" ? [] : [normalized];
-    }
-    return normalized.split(/\s+/).filter((value) => value !== "");
-}
-/** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
-function requireStringValue(provided, filter) {
-    if (typeof provided !== "string") {
-        throw PragmaError.invalidInput(filter.param, String(provided), {
-            recovery: { message: `Provide a string value for --${filter.param}.` },
-        });
-    }
-    return provided.trim().normalize("NFC");
-}
-/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
-function canonicalizeFilterValue(provided, filter, values) {
-    if (typeof provided === "string") {
-        const normalized = provided.trim().normalize("NFC");
-        const match = values.find((value) => value.normalize("NFC").toLowerCase() === normalized.toLowerCase());
-        if (match !== undefined)
-            return match.normalize("NFC");
-    }
-    throw PragmaError.invalidInput(filter.param, String(provided), {
-        validOptions: [...values],
-        recovery: {
-            message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
-        },
-    });
-}
-//# sourceMappingURL=applyFilters.js.map

package/dist/src/kernel/packs/sparql/applyFilters.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"applyFilters.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/applyFilters.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/sparql/applySearch.js

@@ -1,25 +0,0 @@
-/**
- * Apply a pack list's free-text search to resolved rows.
- *
- * Like filters, search runs AFTER the author query, so user input never touches
- * the query text (injection-safe) and the author's ORDER BY is preserved. The
- * term is NFC-normalized and matched case-insensitively; a row passes when ANY
- * declared variable contains it as a substring. A non-string or empty term is a
- * no-op.
- */
-/**
- * @param rows - Rows produced by the pack's list query (post-filter).
- * @param search - The declared search (absent means no searching).
- * @param params - Story parameters as provided by the surface.
- * @returns Rows containing the term in at least one searched variable.
- */
-export function applyPackSearch(rows, search, params) {
-    const provided = params.search;
-    if (search === undefined || typeof provided !== "string")
-        return rows;
-    const term = provided.trim().normalize("NFC").toLowerCase();
-    if (term === "")
-        return rows;
-    return rows.filter((row) => search.variables.some((variable) => row[variable]?.normalize("NFC").toLowerCase().includes(term)));
-}
-//# sourceMappingURL=applySearch.js.map

package/dist/src/kernel/packs/sparql/applySearch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"applySearch.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/applySearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAe,EACf,MAA8B,EAC9B,MAA+B;IAE/B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5D,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACzB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CACjC,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAC7D,CACF,CAAC;AACJ,CAAC"}

package/src/kernel/packs/sparql/applyFilters.ts

@@ -1,203 +0,0 @@
-/**
- * Apply declared pack filters to resolved list rows.
- *
- * Filters are row predicates on projected SELECT variables — the author query is
- * never modified, so user input cannot inject SPARQL and the query's ordering is
- * preserved. With declared `values` the input is canonicalized against the set
- * (NFC, case-insensitive) and rows are matched case-insensitively; without them
- * the input is a free term matched the same way. A row lacking the variable never
- * matches. Several filters combine conjunctively; several values for one
- * filter (a repeated flag) combine as a union.
- *
- * A filter declaring `match: "set"` reads its cell as a space-separated SET and
- * matches any member — the shape a query produces for a dimension a row belongs
- * to several values of at once (a category and its ancestors, say). The
- * comparison is otherwise identical, so exactly one code path decides what a
- * match is.
- *
- * A value-free filter still REJECTS a value the data does not carry, with the
- * admissible values as `validOptions` — the same courtesy a declared-`values`
- * filter has always extended, without copying the vocabulary into the consumer.
- * The vocabulary is read from the graph, because the graph IS the vocabulary; a
- * story that hard-coded the slugs would go stale the first time the data grew a
- * category. Before this, a typo'd `--category` returned
- * `{"ok":true,"data":[],"meta":{}}` — indistinguishable, over MCP, from a
- * genuinely empty category.
- *
- * WHICH part of the graph is the vocabulary matters, and it is NOT the rows.
- * Rows are a population: a value can be perfectly real while no row carries it —
- * `standard categories` lists a category with count 0, `ds:ConceptType` declares
- * "Decision guide" before any concept uses it. Validating against rows called
- * those `INVALID_INPUT`, when the documented answer is a calm empty list. So a
- * filter DECLARES where its vocabulary lives ({@link PackFilter.vocabulary},
- * resolved by the caller and handed in here), and the observed rows are the
- * fallback for a filter that declares none — the only evidence there is, and
- * knowingly narrower than the truth.
- */
-
-import { PragmaError } from "../../error/index.js";
-import type { PackFilter, PackRow } from "../types.js";
-
-/**
- * Authoritative values per filter `param`, read from each filter's declared
- * `vocabulary`. A param absent from the map falls back to the observed rows.
- */
-export type FilterVocabularies = ReadonlyMap<string, readonly string[]>;
-
-/**
- * @param rows - Rows produced by the pack's list query.
- * @param filters - Declared filters (absent means no filtering).
- * @param params - Story parameters as provided by the surface.
- * @param vocabularies - Authoritative values per filter param, resolved from
- *   each filter's declared `vocabulary` (see {@link FilterVocabularies}).
- * @returns Rows matching every provided filter.
- * @throws PragmaError INVALID_INPUT when a value is not in a filter's declared
- *   set, or when a value-free filter receives a non-string value.
- */
-export function applyPackFilters(
-  rows: PackRow[],
-  filters: readonly PackFilter[] | undefined,
-  params: Record<string, unknown>,
-  vocabularies?: FilterVocabularies,
-): PackRow[] {
-  let result = rows;
-  for (const filter of filters ?? []) {
-    const provided = params[filter.param];
-    if (provided === undefined) continue;
-    // A repeated CLI flag accumulates into an array; MCP args stay scalar.
-    // Several values for ONE filter are a union (a row matches any of them);
-    // several filters still combine conjunctively.
-    const occurrences = Array.isArray(provided) ? provided : [provided];
-    if (occurrences.length === 0) continue;
-    const values = filter.values;
-    const terms = occurrences.map((occurrence) =>
-      values === undefined
-        ? requireStringValue(occurrence, filter).toLowerCase()
-        : canonicalizeFilterValue(occurrence, filter, values).toLowerCase(),
-    );
-    // The fallback vocabulary is read from the UNFILTERED rows: a value that
-    // exists but is excluded by a conjunction is a legitimately empty answer,
-    // not a bad argument.
-    if (values === undefined)
-      rejectUnknownValue(
-        vocabularies?.get(filter.param) ?? observedValues(rows, filter),
-        filter,
-        occurrences,
-        terms,
-      );
-    result = result.filter((row) =>
-      cellValues(row, filter).some((value) =>
-        terms.includes(value.toLowerCase()),
-      ),
-    );
-  }
-  return result;
-}
-
-/**
- * The values the rows themselves carry — the fallback vocabulary for a filter
- * that declares no authoritative one, in the data's own DISPLAY spelling.
- */
-function observedValues(
-  rows: readonly PackRow[],
-  filter: PackFilter,
-): string[] {
-  const observed = new Map<string, string>();
-  for (const row of rows) {
-    for (const value of cellValues(row, filter)) {
-      const key = value.toLowerCase();
-      if (!observed.has(key)) observed.set(key, value);
-    }
-  }
-  return [...observed.values()];
-}
-
-/**
- * Reject a value-free filter value the vocabulary does not admit, naming the
- * ones it does.
- *
- * Silent when the vocabulary is EMPTY: an unbuilt or genuinely-empty store is
- * not the caller's mistake, and the list's own `emptyRecovery` is the right
- * voice for it.
- *
- * A value the vocabulary admits is never rejected here even when no row carries
- * it — a real slug with zero standards is a calm empty list, which is what the
- * tool descriptions document and what `standard categories` reporting count 0
- * promises.
- *
- * @throws PragmaError INVALID_INPUT when a term matches none of the admissible
- *   values, carrying them as `validOptions`.
- */
-function rejectUnknownValue(
-  vocabulary: readonly string[],
-  filter: PackFilter,
-  occurrences: readonly unknown[],
-  terms: readonly string[],
-): void {
-  const admissible = new Map<string, string>();
-  for (const value of vocabulary) {
-    const key = value.normalize("NFC").toLowerCase();
-    if (!admissible.has(key)) admissible.set(key, value.normalize("NFC"));
-  }
-  if (admissible.size === 0) return;
-  const index = terms.findIndex((term) => !admissible.has(term));
-  if (index === -1) return;
-  const validOptions = [...admissible.values()].sort();
-  throw PragmaError.invalidInput(filter.param, String(occurrences[index]), {
-    validOptions,
-    recovery: {
-      message: `Values allowed for --${filter.param}: ${validOptions.join(", ")}.`,
-    },
-  });
-}
-
-/**
- * The values a row offers for one filter, in their DISPLAY spelling (NFC).
- *
- * One value for an ordinary filter; every space-separated member for a `"set"`
- * one. A row lacking the variable offers none, so it never matches. Kept in the
- * data's own casing because these are also what an INVALID_INPUT lists back as
- * `validOptions` — lowercasing here would hand the caller a value the graph does
- * not spell that way. Comparison lowercases at the point of comparison instead.
- */
-function cellValues(row: PackRow, filter: PackFilter): string[] {
-  const cell = row[filter.variable];
-  if (cell === undefined) return [];
-  const normalized = cell.normalize("NFC");
-  if (filter.match !== "set") {
-    return normalized === "" ? [] : [normalized];
-  }
-  return normalized.split(/\s+/).filter((value) => value !== "");
-}
-
-/** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
-function requireStringValue(provided: unknown, filter: PackFilter): string {
-  if (typeof provided !== "string") {
-    throw PragmaError.invalidInput(filter.param, String(provided), {
-      recovery: { message: `Provide a string value for --${filter.param}.` },
-    });
-  }
-  return provided.trim().normalize("NFC");
-}
-
-/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
-function canonicalizeFilterValue(
-  provided: unknown,
-  filter: PackFilter,
-  values: readonly string[],
-): string {
-  if (typeof provided === "string") {
-    const normalized = provided.trim().normalize("NFC");
-    const match = values.find(
-      (value) =>
-        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
-    );
-    if (match !== undefined) return match.normalize("NFC");
-  }
-  throw PragmaError.invalidInput(filter.param, String(provided), {
-    validOptions: [...values],
-    recovery: {
-      message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
-    },
-  });
-}