@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -0,0 +1,480 @@
+/**
+ * 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 name is exact and case-insensitive.
+ *
+ * WHAT an entity's name IS lives in one place — {@link nameBinding} — and every
+ * form here uses it: the asserted `by` value, plus, for a lookup that DECLARES
+ * `nameFallback: "iri"`, the IRI-derived name its class constraint can vouch
+ * for. That single binding is what makes the population a `list` publishes and
+ * the population a `lookup` answers to the same population.
+ *
+ * A name-addressed resolve RANKS, and returns every row it ranked. A name can
+ * reach several entities (25 of the live design system's block names do), and
+ * the `LIMIT 1` that used to sit under the ordering discarded all but the first
+ * inside the STORE, where nothing downstream could see that it had happened —
+ * `block lookup button` answered with Launchpad's Button and gave no sign the
+ * global one existed, because `apps_launchpad…` sorts before `global…`.
+ *
+ * The limit is gone from the NAME forms so the resolver can see what it is
+ * choosing between. It still answers with one entity — the arity is the tool's
+ * contract — but the rows it did not take become the IRIs of its notice, which
+ * is the only address that reaches them. (An IRI-addressed form keeps its
+ * `LIMIT 1`: an IRI is one entity by construction, so there is nothing to rank
+ * and nothing set aside.)
+ *
+ * The losers are NOT free, and an earlier draft of this comment claimed they
+ * were. `lookupProjection`'s optionals sit in the same SELECT as the ranking, so
+ * every matching URI has its declared fields projected, and a multi-valued field
+ * multiplies rows per entity before `firstRowPerEntity` throws them away. On the
+ * live graph that is small — 25 shared names, two entities each — but it is a
+ * product, not a constant, and the honest shape is a two-phase resolve: rank the
+ * URIs in a minimal SELECT, then project fields for the ones actually answered
+ * with. That restructure is deliberately not done here: it is the same query the
+ * pending no-limit change would rewrite again, and doing it twice would land two
+ * migrations on one seam.
+ *
+ * The order is {@link rankingClause}'s `?score`, then `STR(?uri)`. The score
+ * multiplies the two things a pack may declare about which entity a bare name
+ * MEANS — `weights` (which KIND of thing) and `scopeWeight` (WHOSE) — and a
+ * story that declares neither falls through to `STR(?uri)` alone, a total,
+ * engine-independent order over a variable that is always bound (`?uri` carries
+ * the class constraint, or the `by` triple when the name is not derived), so it
+ * needs no unbound-value sentinel. That final key is what makes the ranking a
+ * TOTAL order rather than a better arbitrary one.
+ */
+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.
+ *
+ * `constraint` and `optionals` are handed back SEPARATELY because the `?name`
+ * binding has to sit between them: it reads `?uri`, which the class constraint
+ * binds, and a SPARQL `BIND` may only name variables already in scope.
+ */
+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 {`,
+        constraint: buildTypeConstraint(lookup).trimEnd(),
+        optionals,
+    };
+}
+/**
+ * The IRI-derived display name, in ONE spelling every relaxed form shares.
+ *
+ * The local name is everything after the last `#` or `/`, and its dot-separated
+ * hierarchy segments are published with slashes — `cs:react.component.props` →
+ * `react/component/props`. That is not an invention here: it is the derivation
+ * the `standard` list story already performs to PUBLISH a row's name, so this is
+ * the same rule read from the other side. Written once, so the name a list hands
+ * out and the name a lookup answers to cannot drift apart.
+ */
+const DERIVED_NAME = 'REPLACE(REPLACE(STR(?uri), "^.*[#/]", ""), "\\\\.", "/")';
+/**
+ * The `?name` binding shared by every lookup form.
+ *
+ * By DEFAULT the `by` triple is required, and that is the honest default: `by`
+ * is documented as "the property whose value names the entity", so an entity
+ * without one has no name, is not addressable, and is not drawn by `sample`.
+ * It is also the one thing standing between a typo'd IRI and an empty entity.
+ *
+ * A story whose `list` SYNTHESIZES a name instead of reading one declares
+ * `nameFallback: "iri"`, and then the triple becomes OPTIONAL with
+ * {@link DERIVED_NAME} behind it. `standard` is the case that exists: 22 of the
+ * 156 live code standards carry a `cs:name`, and the code-standards ontology
+ * says so deliberately — it is "an optional human-readable display title" that
+ * "never participates in identity". `standard list` published
+ * `react/component/tsdoc` while `standard lookup react/component/tsdoc`
+ * answered ENTITY_NOT_FOUND with empty suggestions, because the only
+ * addressable population was the ~13% carrying an asserted name.
+ *
+ * INFERRING the fallback from the mere PRESENCE of a class constraint is what
+ * this option replaced, and it was over-reach in both directions of the same
+ * defect: `token list` requires `ds:tokenId`, so an inferred fallback made a
+ * `ds:Token` without one addressable and sampleable under a name `token list`
+ * never publishes. The declaration is per story because the list/lookup
+ * agreement is per story.
+ *
+ * The class constraint is still required for the fallback (the schema rejects
+ * the pairing, and this guard keeps a statically-compiled story from generating
+ * a query with nothing bounding `?uri`): a derived name is only as trustworthy
+ * as the class vouching for the entity it came from.
+ *
+ * One binding then serves the name resolve, the miss-suggestion pool, glob
+ * expansion and `sample`'s draw pool alike — every form that decides WHICH
+ * entities a name can reach. (The IRI-addressed forms reach an entity without
+ * going through a name at all: see {@link iriNameBinding}.)
+ */
+function nameBinding(lookup) {
+    if (!derivesNames(lookup))
+        return `  ?uri ${formatTerm(lookup.by)} ?name .`;
+    return [
+        `  OPTIONAL { ?uri ${formatTerm(lookup.by)} ?byName . }`,
+        `  BIND(COALESCE(?byName, ${DERIVED_NAME}) AS ?name)`,
+    ].join("\n");
+}
+/**
+ * Whether this lookup names an entity that carries no `by` value.
+ *
+ * The class constraint is part of the condition, not merely a schema rule the
+ * builders trust: without one there is no triple bounding `?uri`, so a derived
+ * name would be scanned over the whole graph. The schema rejects the pairing
+ * for declared packs; this keeps a statically-compiled story from generating
+ * that query.
+ */
+function derivesNames(lookup) {
+    return (lookup.nameFallback === "iri" &&
+        Boolean(lookup.type ?? lookup.types?.length));
+}
+/**
+ * The `?name` binding for an IRI-ADDRESSED form.
+ *
+ * An IRI names the entity by itself, so here the `by` value is a LABEL to
+ * project, not the thing that identifies it — and the class constraint is
+ * already a sufficient existence check. So the triple is OPTIONAL wherever a
+ * class vouches for the entity, and `?name` is simply left unbound when there is
+ * no label; it is REQUIRED only for a lookup constraining no class, where it is
+ * the one thing standing between a typo'd IRI and an empty entity.
+ *
+ * A story that {@link derivesNames} gets the same COALESCE the name forms use,
+ * so an entity reached by IRI reports the name `list` published for it rather
+ * than a blank.
+ */
+function iriNameBinding(lookup) {
+    if (derivesNames(lookup))
+        return nameBinding(lookup);
+    const named = `?uri ${formatTerm(lookup.by)} ?name .`;
+    const constrained = Boolean(lookup.type ?? lookup.types?.length);
+    return constrained ? `  OPTIONAL { ${named} }` : `  ${named}`;
+}
+/**
+ * Render a declared weight as a SPARQL numeric literal (never exponential).
+ *
+ * `toFixed` is the wrong instrument twice over, and both bite inside the 0–1
+ * range the schema allows. It ROUNDS — `0.1234567` became `0.123457`, silently
+ * altering a ranking a pack author declared — and stripping the trailing zeros
+ * off its output turns `0.0000001` into `0.`, which is not a numeric literal at
+ * all and makes the query a parse error rather than a wrong answer.
+ *
+ * `String` already prints the shortest exact round-trip, so it is the right
+ * source of digits; the only thing it does that SPARQL cannot read is
+ * exponent notation, which xsd:decimal's grammar has no form for. Expand that
+ * case and pass everything else through untouched.
+ */
+function sparqlNumber(value) {
+    if (Number.isInteger(value))
+        return String(value);
+    const text = String(value);
+    const exponent = /e-(\d+)$/i.exec(text);
+    if (exponent === null)
+        return text;
+    // `1e-7` / `1.5e-7`: the decimal places needed are the exponent plus whatever
+    // the mantissa already carried, which is exact — no rounding can occur.
+    const mantissaPlaces = text.split("e")[0]?.split(".")[1]?.length ?? 0;
+    return value.toFixed(Number(exponent[1]) + mantissaPlaces);
+}
+/**
+ * `left * right`, guarded where an operand may be ZERO.
+ *
+ * Not defensiveness — a MEASURED engine defect, and the top scope hits it every
+ * time. oxigraph raises on an xsd:decimal times a zero (`0.2 * 0` errors, while
+ * `0.2 * 1` is `0.2`), and a raising expression inside a `BIND` leaves its
+ * variable unbound. Written the arithmetic way, the depth-0 scope — the one that
+ * is supposed to WIN — is the only one whose weight never binds, and what
+ * happens next is decided by whatever the surrounding `COALESCE` falls back to.
+ * The same expression on the `block list` side fell back to 0 and sorted every
+ * top-tier row LAST, which is how this was found. Both sides now say what they
+ * mean. Only VARIABLE operands are tested; a declared literal is resolved at
+ * build time by the callers.
+ */
+function sparqlProduct(left, right) {
+    const guards = [left, right]
+        .filter((operand) => operand.startsWith("?"))
+        .map((operand) => `${operand} = 0`);
+    const product = `${left} * ${right}`;
+    return guards.length === 0
+        ? product
+        : `IF(${guards.join(" || ")}, 0, ${product})`;
+}
+/**
+ * The type factor: the LOWEST weight declared for any class the entity belongs
+ * to, 1 when none is.
+ *
+ * An IF-ladder over `EXISTS` rather than a weight column on the class VALUES,
+ * because a join would multiply rows for an entity in two weighted classes and
+ * the resolve now returns every row it finds. Lowest weight tested FIRST, so the
+ * ladder means MIN — the same rule the MCP listing's `effectiveWeight` states in
+ * prose: a demotion any membership asks for is not cancelled by a membership
+ * that asked for nothing.
+ */
+function typeWeightBind(lookup) {
+    const declared = Object.entries(lookup.weights ?? {});
+    if (declared.length === 0)
+        return "";
+    const ladder = [...declared]
+        .sort(([aType, aWeight], [bType, bWeight]) => aWeight === bWeight ? aType.localeCompare(bType) : aWeight - bWeight)
+        .reduceRight((fallback, [type, weight]) => `IF(EXISTS { ?uri a ${formatTerm(type)} }, ${sparqlNumber(weight)}, ${fallback})`, "1");
+    return `  BIND(${ladder} AS ?rankType)`;
+}
+/**
+ * The scope factor: how much the entity's containing scope is worth, DERIVED
+ * from the depth of that scope's own path-shaped name.
+ *
+ * Nested OPTIONALs, not a flat sequence: `?rankScope` is unbound for an entity
+ * outside any scope, and a following top-level `OPTIONAL { ?rankScope <by> ?n }`
+ * would then match every such triple in the graph and multiply the row.
+ *
+ * The depth is the separator count, so nothing is enumerated and a scope the
+ * ontology adds tomorrow inherits its place. `COALESCE` states the retirement
+ * path in the query itself: an ASSERTED weight wins, the derived one answers
+ * until there is one, and an entity with no scope at all scores a neutral 1
+ * rather than dropping below entities that have one.
+ */
+function scopeWeightBinds(lookup) {
+    const scope = lookup.scopeWeight;
+    if (!scope)
+        return "";
+    const name = "?rankScopeName";
+    const asserted = scope.asserted
+        ? [
+            `    OPTIONAL { ?rankScope ${formatTerm(scope.asserted)} ?rankAsserted . }`,
+        ]
+        : [];
+    // A falloff of 0 ranks every scope alike, so the derived weight is the
+    // constant — and the depth it would multiply is never computed.
+    const derived = scope.falloff === 0
+        ? "1"
+        : `1 - ${sparqlProduct(sparqlNumber(scope.falloff), "?rankDepth")}`;
+    return [
+        "  OPTIONAL {",
+        `    ?uri ${formatTerm(scope.via)} ?rankScope .`,
+        `    OPTIONAL { ?rankScope ${formatTerm(scope.by)} ${name} . }`,
+        ...asserted,
+        "  }",
+        `  BIND(STRLEN(${name}) - STRLEN(REPLACE(${name}, "/", "")) AS ?rankDepth)`,
+        `  BIND(${derived} AS ?rankDerived)`,
+        // Floored at 0: a scope deep enough to drive the factor negative would
+        // otherwise INVERT the type factor it multiplies, promoting a part of a
+        // block above a whole one.
+        `  BIND(COALESCE(${scope.asserted ? "?rankAsserted, " : ""}IF(?rankDerived < 0, 0, ?rankDerived), 1) AS ?rankScopeWeight)`,
+    ].join("\n");
+}
+/**
+ * The `?score` a name resolve orders by, and the ORDER BY that reads it.
+ *
+ * The two factors MULTIPLY rather than tiebreak, and that is the editorial
+ * ruling, not an implementation convenience: neither question subsumes the
+ * other. A whole component in a nested scope (1 × 0.8) outranks a mere PART of a
+ * block in the widest one (0.6 × 1), while two components of equal kind are
+ * separated by their scopes alone (1 × 1 beats 1 × 0.8). Both live cases fall
+ * out of one product.
+ *
+ * @returns The BIND lines to splice into the WHERE clause, and the ORDER BY
+ *   line — a story declaring neither factor gets no BINDs and `STR(?uri)` alone.
+ */
+function rankingClause(lookup) {
+    const factors = [typeWeightBind(lookup), scopeWeightBinds(lookup)].filter((line) => line !== "");
+    if (factors.length === 0)
+        return { binds: "", orderBy: "ORDER BY STR(?uri)" };
+    const terms = [
+        lookup.weights && Object.keys(lookup.weights).length > 0 ? "?rankType" : "",
+        lookup.scopeWeight ? "?rankScopeWeight" : "",
+    ].filter((term) => term !== "");
+    return {
+        binds: [
+            ...factors,
+            `  BIND(${terms.length === 2 ? sparqlProduct(terms[0], terms[1]) : terms.join("")} AS ?score)`,
+        ].join("\n"),
+        orderBy: "ORDER BY DESC(?score) STR(?uri)",
+    };
+}
+/**
+ * Build the SELECT retrieving the entities a name reaches, with their declared
+ * fields, best first. The caller answers with the first and names the rest.
+ *
+ * @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, ranked and unlimited.
+ */
+export function buildLookupQuery(lookup, name, level) {
+    const { header, constraint, optionals } = lookupProjection(lookup, level);
+    const ranking = rankingClause(lookup);
+    return [
+        header,
+        constraint,
+        nameBinding(lookup),
+        ranking.binds,
+        optionals,
+        `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+        "}",
+        ranking.orderBy,
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * 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, constraint, optionals } = lookupProjection(lookup, level);
+    return [
+        header,
+        `  BIND(<${iri}> AS ?uri)`,
+        constraint,
+        iriNameBinding(lookup),
+        optionals,
+        "}",
+        "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 IRIs, everything else comes from the field fetch. The name
+ * is an escaped literal; all terms are validated pack terms.
+ *
+ * Ranked and unlimited, exactly like {@link buildLookupQuery} — the two paths
+ * differ in where the VALUES come from, never in which entities a name reaches.
+ * `?score` is deliberately NOT projected: it orders the rows and is none of the
+ * caller's business, and projecting it would leak a ranking artefact into
+ * `--format json`.
+ */
+export function buildNameResolveQuery(lookup, name) {
+    const ranking = rankingClause(lookup);
+    return [
+        "SELECT ?uri ?name WHERE {",
+        buildTypeConstraint(lookup).trimEnd(),
+        nameBinding(lookup),
+        ranking.binds,
+        `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+        "}",
+        ranking.orderBy,
+    ]
+        .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)`,
+        buildTypeConstraint(lookup).trimEnd(),
+        iriNameBinding(lookup),
+        "}",
+        "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 {",
+        buildTypeConstraint(lookup).trimEnd(),
+        // Same {@link nameBinding} the resolves use, so the addressable population
+        // and the resolvable population are the same population. When they were
+        // not, a name a miss-suggestion offered could itself miss, and a glob
+        // expanded over a pool the resolve could not answer from.
+        nameBinding(lookup),
+        "}",
+    ]
+        .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"}