@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -0,0 +1,217 @@
+/**
+ * Generated, injection-safe SPARQL lookup queries for a pack story.
+ *
+ * Pack authors declare *what* names an entity (`by`, optional `type`/`types`)
+ * and which properties to read; the query text is generated here so
+ * user-supplied names are always escaped SPARQL string literals, and level-gated
+ * fields below the active level are excluded from the projection (fetch-gating).
+ * Matching on the `by` property is exact and case-insensitive.
+ *
+ * Every name-addressed resolve is TOTALLY ORDERED before its `LIMIT 1`. A name
+ * can recur across tiers, and an unordered `LIMIT 1` hands the tie to the
+ * store's enumeration order — a different answer on a different machine, or
+ * after a repack. `ORDER BY STR(?uri)` is a total, engine-independent order over
+ * a variable that is always bound (`?uri` carries the `by` triple), so it needs
+ * no unbound-value sentinel. It fixes WHICH answer is arbitrary, not WHETHER:
+ * declaring a precedence between tiers is an ontology change, tracked separately.
+ */
+import { activeExpands, activeFields } from "../disclosure.js";
+import { escapeSparqlString, formatTerm } from "./escape.js";
+/**
+ * The class-constraint clause for a lookup: a single `a` triple for `type`, a
+ * VALUES-constrained type triple for `types`, or nothing. All terms are
+ * validated pack terms, never user input.
+ */
+function buildTypeConstraint(lookup) {
+    if (lookup.type) {
+        return `  ?uri a ${formatTerm(lookup.type)} .\n`;
+    }
+    if (lookup.types && lookup.types.length > 0) {
+        const values = lookup.types.map(formatTerm).join(" ");
+        return `  VALUES ?packType { ${values} }\n  ?uri a ?packType .\n`;
+    }
+    return "";
+}
+/**
+ * The gated projection shared by both lookup forms: the `?uri ?name <vars>`
+ * SELECT header, the class constraint, and the OPTIONAL field triples, all
+ * restricted to the fields active at `level`. The name- and IRI-addressed forms
+ * differ ONLY in how `?uri` is bound (a `FILTER` on the escaped name vs a `BIND`
+ * of the resolved IRI), so both thread the active level through here and gate
+ * identically — an IRI-addressed lookup honours `--detail` just like a name one.
+ */
+function lookupProjection(lookup, level) {
+    const fields = activeFields(lookup, level);
+    const vars = fields.map((field) => `?${field.name}`).join(" ");
+    const optionals = fields
+        .map((field) => `  OPTIONAL { ?uri ${formatTerm(field.property)} ?${field.name} . }`)
+        .join("\n");
+    return {
+        header: `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
+        body: buildTypeConstraint(lookup) + optionals,
+    };
+}
+/**
+ * Build the SELECT retrieving one named entity with its declared fields.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param name - User-supplied entity name (escaped here).
+ * @param level - Active canonical level; gated fields below it are excluded.
+ * @returns SPARQL SELECT text.
+ */
+export function buildLookupQuery(lookup, name, level) {
+    const { header, body } = lookupProjection(lookup, level);
+    return [
+        header,
+        `  ?uri ${formatTerm(lookup.by)} ?name .`,
+        body,
+        `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+        "}",
+        "ORDER BY STR(?uri)",
+        "LIMIT 1",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * The `?name` clause for an IRI-addressed form.
+ *
+ * An IRI names the entity by itself, so the `by` value is a LABEL to project,
+ * not the thing that identifies it — and a class constraint is already a
+ * sufficient existence check. Requiring the `by` triple here made every entity
+ * that carries no name unaddressable by any means at all: 131 of the 144 live
+ * code standards have no `cs:name` (their displayed name is synthesized from the
+ * IRI by the list story), and shell completion offers their IRIs. So the triple
+ * is OPTIONAL wherever a class constraint can vouch for the entity, and
+ * REQUIRED only for a lookup that declares no `type`/`types` — where it is the
+ * one thing standing between a typo'd IRI and an empty entity.
+ */
+function iriNameClause(lookup) {
+    const named = `?uri ${formatTerm(lookup.by)} ?name .`;
+    const constrained = Boolean(lookup.type ?? lookup.types?.length);
+    return constrained ? `  OPTIONAL { ${named} }` : `  ${named}`;
+}
+/**
+ * Build the SELECT retrieving one entity addressed directly by IRI.
+ *
+ * Binds the already-resolved IRI to `?uri` instead of filtering on the `by`
+ * value; otherwise identical to the name form, including level-gating. Injection-
+ * safe by construction: the caller validates `iri` against the embeddable-IRI
+ * shape BEFORE it is interpolated here — raw user input never reaches this
+ * function.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param iri - The already-resolved, embeddable entity IRI.
+ * @param level - Active canonical level; gated fields below it are excluded.
+ */
+export function buildLookupByIriQuery(lookup, iri, level) {
+    const { header, body } = lookupProjection(lookup, level);
+    return [
+        header,
+        `  BIND(<${iri}> AS ?uri)`,
+        iriNameClause(lookup),
+        body,
+        "}",
+        "LIMIT 1",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * Build the minimal name→URI resolve for a graphql-sourced lookup (and the
+ * shared entry point for the sparql path's name form): maps the user-supplied
+ * name to the entity IRI, everything else comes from the field fetch. The name
+ * is an escaped literal; all terms are validated pack terms.
+ */
+export function buildNameResolveQuery(lookup, name) {
+    return [
+        "SELECT ?uri ?name WHERE {",
+        `  ?uri ${formatTerm(lookup.by)} ?name .`,
+        buildTypeConstraint(lookup).trimEnd(),
+        `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+        "}",
+        "ORDER BY STR(?uri)",
+        "LIMIT 1",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * Build the minimal IRI→entity resolve for a graphql-sourced lookup: the mirror
+ * of {@link buildNameResolveQuery} for the other argument shape.
+ *
+ * The GraphQL lane fetches by IRI, so this exists to ANSWER ONE QUESTION — does
+ * the pack's class constraint vouch for this entity? — and to pick up a display
+ * name if there is one. Injection-safe by construction: `iri` is already
+ * resolved and validated against the embeddable-IRI shape by the caller.
+ */
+export function buildIriResolveQuery(lookup, iri) {
+    return [
+        "SELECT ?uri ?name WHERE {",
+        `  BIND(<${iri}> AS ?uri)`,
+        iriNameClause(lookup),
+        buildTypeConstraint(lookup).trimEnd(),
+        "}",
+        "LIMIT 1",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Build the SELECT listing every entity IRI a lookup can address (IRI globs). */
+export function buildLookupIrisQuery(lookup) {
+    const constraint = buildTypeConstraint(lookup).trimEnd();
+    return [
+        "SELECT DISTINCT ?uri WHERE {",
+        // A pack that constrains by class is asking about its class; one that does
+        // not has only the `by` triple to bound the scan, so it keeps that bound
+        // (and, like the name population, addresses only entities that carry one).
+        constraint !== "" ? constraint : `  ?uri ${formatTerm(lookup.by)} ?name .`,
+        "}",
+        "ORDER BY STR(?uri)",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * Build the sub-SELECT retrieving one expand's child rows for a resolved entity.
+ *
+ * Injection-safe: the only interpolated value is `entityUri`, the IRI the base
+ * lookup already resolved from the store (never user input); the
+ * relation/properties are validated pack terms. SPARQL expands are single-hop,
+ * so every select entry here is a plain field.
+ */
+export function buildExpandQuery(expand, entityUri) {
+    const vars = expand.select.map((field) => `?${field.name}`).join(" ");
+    const optionals = expand.select
+        .map((field) => "property" in field
+        ? `  OPTIONAL { ?child ${formatTerm(field.property)} ?${field.name} . }`
+        : "")
+        .filter((line) => line !== "")
+        .join("\n");
+    return [
+        `SELECT ${vars} WHERE {`,
+        `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
+        optionals,
+        "}",
+    ].join("\n");
+}
+/** Build the SELECT listing all entity names — lookup-miss suggestions. */
+export function buildLookupNamesQuery(lookup) {
+    return [
+        // DISTINCT: this population feeds miss-suggestions and glob expansion, and
+        // a name that several entities share is one CANDIDATE, not several. Without
+        // it a glob matching such a name expanded to it once per entity carrying
+        // it, and `lookup` then resolved each copy to the same winner — so
+        // `block lookup 'Butt*'` listed one Button twice while the other Button
+        // never appeared at all.
+        "SELECT DISTINCT ?name WHERE {",
+        `  ?uri ${formatTerm(lookup.by)} ?name .`,
+        buildTypeConstraint(lookup).trimEnd(),
+        "}",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Re-export the active-value helpers the GraphQL document generator shares. */
+export { activeExpands, activeFields };
+//# sourceMappingURL=buildLookupQuery.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * SPARQL literal/term escaping for generated pack queries.
+ *
+ * Pack authors declare RDF terms (prefixed names or IRIs); users supply entity
+ * names. The generators here escape user names as SPARQL string literals and
+ * render validated terms as query tokens, so a pack definition never
+ * interpolates raw user input into query text.
+ */
+/** Escape a user-supplied value as a SPARQL string-literal body. */
+export function escapeSparqlString(value) {
+    return value
+        .replaceAll("\\", "\\\\")
+        .replaceAll('"', '\\"')
+        .replaceAll("\n", "\\n")
+        .replaceAll("\r", "\\r");
+}
+/** Render a validated term (prefixed name or absolute IRI) as a query token. */
+export function formatTerm(term) {
+    return term.includes("://") ? `<${term}>` : term;
+}
+//# sourceMappingURL=escape.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK;SACT,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC;SACtB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;SACvB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * The SPARQL path — every generated read a pack story performs, and the two
+ * row operations that must NOT be generated.
+ *
+ * The domain is organised around one invariant: user input never reaches query
+ * text. The query builders compose only from validated pack terms and escaped
+ * literals, so a name a user typed becomes a SPARQL string literal or nothing;
+ * `runSelect` is the single choke point every one of those trusted queries
+ * goes through, which is what makes "a generated query failed" distinguishable
+ * from "the user's own `graph query` failed". Filtering and search then run as
+ * predicates over the resolved ROWS rather than as clauses in the query —
+ * which is why they live in this domain despite touching no SPARQL at all:
+ * they are the operations that would otherwise be tempting to express as query
+ * text, and keeping them here keeps the temptation answered.
+ *
+ * The escaping primitives stay internal. They are how the builders keep that
+ * invariant, not a service for composing query text elsewhere — a caller with
+ * the escaper is a caller who can build an unvalidated query, which is exactly
+ * the shape this domain exists to prevent.
+ *
+ * Two names re-exported by `buildLookupQuery.ts` for its own callers'
+ * convenience — the disclosure-level field and expand selectors — are also
+ * omitted. They belong to `kernel/packs/disclosure.ts`; laundering them
+ * through here would make this domain look like their owner and freeze a
+ * pass-through that has no reason to be permanent.
+ */
+export { applyPackFilters } from "./applyFilters.js";
+export { applyPackSearch } from "./applySearch.js";
+export { buildExpandQuery, buildLookupByIriQuery, buildLookupNamesQuery, buildLookupQuery, buildNameResolveQuery, } from "./buildLookupQuery.js";
+export { runSelect } from "./runSelect.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,101 @@
+/**
+ * Run a pack story's SELECT through the query facade and return its rows.
+ *
+ * The store rejects non-read queries at the engine level; this guards the result
+ * shape so a pack whose query is not a SELECT fails with a recoverable config
+ * error instead of a shape mismatch downstream. The facade boots the store
+ * lazily and auto-applies the pack's prefixes, so generated queries use prefixed
+ * terms directly. This is the single choke point for every TRUSTED, generated
+ * SPARQL read (list stories, lookup name→URI resolves, expands) — user SPARQL
+ * (`graph query`) goes through the facade directly and stays INVALID_INPUT.
+ */
+import { cliRecovery, PragmaError } from "../../error/index.js";
+/**
+ * True when a trusted, generated query failed because the store does not know a
+ * prefix it used. Generated queries are composed from terms the distribution
+ * declares and from a pack's own story text, never from user input — so an
+ * unknown prefix is never a query bug. It means this store was not built from a
+ * pack that binds that term: most often nothing was built at all, and otherwise
+ * a store built from a pack whose vocabulary is simply different.
+ *
+ * For a DISTRIBUTION story both are answered by the same lever
+ * (`sources update`), so both are remapped to it; the message says which claim
+ * it is actually making, and does NOT assert the store is unbuilt. Widening the
+ * detection any further would start hiding query bugs, which is the failure this
+ * whole choke point exists to prevent.
+ *
+ * A story from a package or a user's config is a different diagnosis, which is
+ * why {@link runSelect} now takes the query's provenance: see
+ * {@link unboundPrefixError}.
+ */
+function isUnseededStoreError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /prefix/i.test(message) && /not\s+found/i.test(message);
+}
+/**
+ * The error for a generated query naming a prefix the graph does not bind,
+ * diagnosed by WHO declared the story.
+ *
+ * A distribution story ships with the packs that bind its terms, so the honest
+ * reading is "nothing is built yet" (or "what is built came from a pack with a
+ * different vocabulary") — both fixed by `sources update`, so it keeps today's
+ * STORE_UNAVAILABLE and that recovery.
+ *
+ * A config or package story is the author's own: they named a prefix the graph
+ * does not bind, and `sources update` cannot help them — `buildIndex` already
+ * treats the same condition as the ordinary third-party case and degrades
+ * gracefully, while this path escalated it. It is a CONFIG_ERROR naming the
+ * story, which is the module's own precedent for a declaration that cannot be
+ * served (ruling R3).
+ */
+function unboundPrefixError(source) {
+    if (source.origin !== "distribution") {
+        return PragmaError.configError(`Story query in ${source.label} uses a prefix the graph does not bind. ` +
+            `Declare it under \`prefixes\`, or use a term the configured packs define.`);
+    }
+    return PragmaError.storeUnavailable("The local store was not built from a pack that defines every term this read uses.", {
+        recovery: cliRecovery("sources update", "Build the local store from the configured packs.", 
+        // An agent recovers by calling the tool, then retrying (PR9 C1 cold-
+        // store retry makes the post-update retry succeed).
+        { tool: "sources_update" }),
+    });
+}
+/**
+ * Run the facade query, remapping a store that cannot answer it. A generated
+ * query hitting an unknown prefix surfaces an actionable error — chosen by the
+ * story's provenance, see {@link unboundPrefixError} — instead of a raw SPARQL
+ * "Prefix not found" wrapped as INTERNAL_ERROR ("report this issue").
+ * Returns the inferred facade result type, so this module stays clear of a
+ * static `@canonical/ke` import (the lazy-dispatch guard).
+ */
+async function queryOrRemap(rt, query, source) {
+    try {
+        return await rt.query.sparql(query);
+    }
+    catch (error) {
+        if (error instanceof PragmaError)
+            throw error;
+        if (isUnseededStoreError(error))
+            throw unboundPrefixError(source);
+        throw error;
+    }
+}
+/**
+ * @param rt - The runtime (its query facade over the lazy store).
+ * @param query - SPARQL SELECT text (prefixes auto-applied by the store).
+ * @param source - The story's provenance: its label for attribution, and the
+ *   layer that declared it, which decides how an unbound prefix is diagnosed.
+ * @returns One record per row, keyed by SELECT variable name.
+ * @throws PragmaError CONFIG_ERROR when the query is not a SELECT, or when a
+ *   config/package story names a prefix the graph does not bind;
+ *   STORE_UNAVAILABLE (exit 3) when a distribution story finds one.
+ * @note Impure — queries the store through the facade.
+ */
+export async function runSelect(rt, query, source) {
+    const result = await queryOrRemap(rt, query, source);
+    if (result.type !== "select") {
+        throw PragmaError.configError(`Story query in ${source.label} must be a SELECT (got ${result.type}).`);
+    }
+    return result.bindings;
+}
+//# sourceMappingURL=runSelect.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runSelect.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/runSelect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,oBAAoB,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,kBAAkB,CAAC,MAAmB;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACrC,OAAO,WAAW,CAAC,WAAW,CAC5B,kBAAkB,MAAM,CAAC,KAAK,0CAA0C;YACtE,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,gBAAgB,CACjC,mFAAmF,EACnF;QACE,QAAQ,EAAE,WAAW,CACnB,gBAAgB,EAChB,kDAAkD;QAClD,qEAAqE;QACrE,oDAAoD;QACpD,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAC3B;KACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,YAAY,CACzB,EAAgC,EAChC,KAAa,EACb,MAAmB;IAEnB,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW;YAAE,MAAM,KAAK,CAAC;QAC9C,IAAI,oBAAoB,CAAC,KAAK,CAAC;YAAE,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAClE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAgC,EAChC,KAAa,EACb,MAAmB;IAEnB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,WAAW,CAAC,WAAW,CAC3B,kBAAkB,MAAM,CAAC,KAAK,0BAA0B,MAAM,CAAC,IAAI,IAAI,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,QAAqB,CAAC;AACtC,CAAC"}

package/dist/src/kernel/packs/types.js

@@ -0,0 +1,30 @@
+/**
+ * The pack grammar (v2) — "reads as data".
+ *
+ * A pack maps a noun to preferred queries: a SPARQL SELECT for the list story
+ * and a generated, injection-safe lookup. One grammar and one compiler
+ * ({@link ../compile}) project a pack into {@link ../../spec/types.VerbSpec}s;
+ * the CLI and MCP projectors then treat pack verbs like any other. This closes
+ * the two old forks — three read-noun styles collapse to one pack shape, and
+ * the two pack compilers collapse to one.
+ *
+ * These types are hand-authored and zod-free so the compiler (reached on the
+ * `--help`/`__complete` fast path via `capabilities/index`) never pulls zod;
+ * {@link ../schema} validates the same shapes and is imported lazily, only for
+ * dynamic (config/package) packs and in tests.
+ *
+ * Progressive disclosure is CANONICAL: a level tag names one of
+ * `constants.DETAIL_LEVELS` (`summary` < `standard` < `detailed`), and gating
+ * is by that canonical index — a pack's declared `levels` is any ordered subset
+ * of the canonical set.
+ */
+/** Whether an expand-select entry is a nested expand (vs a plain field). */
+export function isNestedExpand(entry) {
+    return "relation" in entry;
+}
+/** A story the distribution itself declares (`pragma.conf.ts` and its kin). */
+export const distributionSource = (label) => ({
+    label,
+    origin: "distribution",
+});
+//# sourceMappingURL=types.js.map

package/dist/src/kernel/packs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/kernel/packs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqEH,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAC5B,KAAuB;IAEvB,OAAO,UAAU,IAAI,KAAK,CAAC;AAC7B,CAAC;AA+RD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAa,EAAe,EAAE,CAAC,CAAC;IACjE,KAAK;IACL,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC"}

package/dist/src/kernel/packs/uniqueness.js

@@ -0,0 +1,30 @@
+/**
+ * Plain `(noun, verb)` uniqueness across compiled verbs.
+ *
+ * Replaces the old reserved-verb / derive-reserved machinery: every verb the
+ * projectors see — authored, distribution-declared, or dynamic — must own a
+ * distinct `(noun, verb)` key. Precedence (config > package > distribution) is
+ * resolved by NOUN before this runs, so a surviving collision here is a real
+ * conflict, reported with both sources.
+ */
+/** The `(noun, verb)` key for a verb path (`["standard","list"]` → `standard list`). */
+export function verbKey(path) {
+    return path[1] ? `${path[0]} ${path[1]}` : path[0];
+}
+/**
+ * Assert that no two verbs share a `(noun, verb)` key.
+ *
+ * @param verbs - Every verb the projectors will see.
+ * @throws Error naming the colliding key on the first duplicate.
+ */
+export function assertUniqueVerbs(verbs) {
+    const seen = new Set();
+    for (const verb of verbs) {
+        const key = verbKey(verb.path);
+        if (seen.has(key)) {
+            throw new Error(`duplicate command "${key}" — two capabilities claim it.`);
+        }
+        seen.add(key);
+    }
+}
+//# sourceMappingURL=uniqueness.js.map

package/dist/src/kernel/packs/uniqueness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniqueness.js","sourceRoot":"","sources":["../../../../src/kernel/packs/uniqueness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAC,IAAgC;IACtD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA0B;IAC1D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,gCAAgC,CAC1D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;AACH,CAAC"}