@canonical/pragma-cli 0.35.0 → 0.37.0

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

@@ -5,15 +5,47 @@
  * 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.
+ * Matching on the name 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.
+ * 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";
@@ -43,11 +75,15 @@ function buildTypeConstraint(lookup: PackLookup): string {
  * 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: PackLookup,
   level: string | undefined,
-): { header: string; body: string } {
+): { header: string; constraint: string; optionals: string } {
   const fields = activeFields(lookup, level);
   const vars = fields.map((field) => `?${field.name}`).join(" ");
   const optionals = fields
@@ -58,56 +94,290 @@ function lookupProjection(
     .join("\n");
   return {
     header: `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
-    body: buildTypeConstraint(lookup) + optionals,
+    constraint: buildTypeConstraint(lookup).trimEnd(),
+    optionals,
   };
 }
 
 /**
- * Build the SELECT retrieving one named entity with its declared fields.
+ * 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. When the
+ * defect was measured, 22 of the then-156 live code standards carried a
+ * `cs:name`, and the code-standards ontology said so deliberately — "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. (Upstream has since retired `cs:name` for
+ * `rdfs:label`, which every standard carries; the fallback stays because a
+ * pack is data, and a dropped label must degrade to the derived name rather
+ * than become unaddressable.)
+ *
+ * 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: PackLookup): string {
+  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: PackLookup): boolean {
+  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: PackLookup): string {
+  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: number): string {
+  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: string, right: string): string {
+  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: PackLookup): string {
+  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: PackLookup): string {
+  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: PackLookup): {
+  binds: string;
+  orderBy: string;
+} {
+  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] as string, terms[1] as string) : 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.
+ * @returns SPARQL SELECT text, ranked and unlimited.
  */
 export function buildLookupQuery(
   lookup: PackLookup,
   name: string,
   level?: string,
 ): string {
-  const { header, body } = lookupProjection(lookup, level);
+  const { header, constraint, optionals } = lookupProjection(lookup, level);
+  const ranking = rankingClause(lookup);
   return [
     header,
-    `  ?uri ${formatTerm(lookup.by)} ?name .`,
-    body,
+    constraint,
+    nameBinding(lookup),
+    ranking.binds,
+    optionals,
     `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
     "}",
-    "ORDER BY STR(?uri)",
-    "LIMIT 1",
+    ranking.orderBy,
   ]
     .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: PackLookup): string {
-  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.
  *
@@ -126,12 +396,13 @@ export function buildLookupByIriQuery(
   iri: string,
   level?: string,
 ): string {
-  const { header, body } = lookupProjection(lookup, level);
+  const { header, constraint, optionals } = lookupProjection(lookup, level);
   return [
     header,
     `  BIND(<${iri}> AS ?uri)`,
-    iriNameClause(lookup),
-    body,
+    constraint,
+    iriNameBinding(lookup),
+    optionals,
     "}",
     "LIMIT 1",
   ]
@@ -142,21 +413,28 @@ export function buildLookupByIriQuery(
 /**
  * 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
+ * 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: PackLookup,
   name: string,
 ): string {
+  const ranking = rankingClause(lookup);
   return [
     "SELECT ?uri ?name WHERE {",
-    `  ?uri ${formatTerm(lookup.by)} ?name .`,
     buildTypeConstraint(lookup).trimEnd(),
+    nameBinding(lookup),
+    ranking.binds,
     `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
     "}",
-    "ORDER BY STR(?uri)",
-    "LIMIT 1",
+    ranking.orderBy,
   ]
     .filter((line) => line !== "")
     .join("\n");
@@ -175,8 +453,8 @@ export function buildIriResolveQuery(lookup: PackLookup, iri: string): string {
   return [
     "SELECT ?uri ?name WHERE {",
     `  BIND(<${iri}> AS ?uri)`,
-    iriNameClause(lookup),
     buildTypeConstraint(lookup).trimEnd(),
+    iriNameBinding(lookup),
     "}",
     "LIMIT 1",
   ]
@@ -239,8 +517,12 @@ export function buildLookupNamesQuery(lookup: PackLookup): string {
     // `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(),
+    // 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 !== "")

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

@@ -68,7 +68,11 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
       (t) => t.name === "standard_categories",
     )?.description;
     await mcp.cleanup();
-    expect(desc).toBe("List all code standard categories.");
+    // The authored prose reaches the extra verb's tool, whole. Asserted by
+    // fragment rather than by exact string: the wiring is what this pins, and
+    // tool descriptions are explicitly not frozen (`registerVerb.ts:324-326`).
+    expect(desc).toContain("List all code standard categories");
+    expect(desc).toContain("Example: standard_categories {}");
   });
 
   it("CLI --help shows the rich prose but NEVER the MCP tool-call syntax", () => {
@@ -126,3 +130,33 @@ describe("a tool-call example names a parameter the tool ACCEPTS (PROTECTED)", (
     }
   });
 });
+
+describe("every story tool CARRIES a call example (PROTECTED)", () => {
+  // The check above only polices examples that exist. `standard` authored NONE,
+  // and the auto-generated one fires only for a filter declaring `values` —
+  // which the category filter deliberately does not, because the graph is the
+  // vocabulary. So the four `standard_*` tools shipped with no worked call at
+  // all, and the model that could not form one had nothing to copy.
+  //
+  // This asserts the gap cannot reappear on a future story: a compiled story
+  // tool must show an agent one call it can make, spelled with its OWN name so
+  // the example cannot be copied from a sibling tool and left stale.
+  it("names its own tool in an `Example: <tool_name> {…}` fragment", async () => {
+    const mcp = await projectMcp([...storyModules.values()]);
+    try {
+      const tools = await mcp.listTools();
+      expect(tools.length).toBeGreaterThan(0);
+      const missing = tools
+        .filter(
+          (tool) =>
+            !new RegExp(`Example:\\s*${tool.name}\\s*\\{`).test(
+              tool.description ?? "",
+            ),
+        )
+        .map((tool) => tool.name);
+      expect(missing).toEqual([]);
+    } finally {
+      await mcp.cleanup();
+    }
+  });
+});

package/src/kernel/packs/types.ts

@@ -150,10 +150,56 @@ export interface PackFilter {
    * string matched case-insensitively against the variable).
    */
   readonly values?: readonly string[];
+  /**
+   * How a provided value is compared to the row's cell.
+   *
+   * `"exact"` (the default) compares the whole cell. `"set"` reads the cell as
+   * a SPACE-SEPARATED set and matches when ANY member equals the provided
+   * value — the shape a `GROUP_CONCAT` produces, for a dimension where one row
+   * legitimately belongs to several values at once. The standing case is a
+   * hierarchy: a standard filed under `testing-unit` is, by the definition of
+   * the hierarchy, also a `testing` standard, and a filter that compared only
+   * the leaf answered `--category testing` with 1 of 8 — a silently wrong
+   * answer, exit 0.
+   */
+  readonly match?: "exact" | "set";
+  /**
+   * Where the dimension's VOCABULARY lives in the graph, for a filter with no
+   * declared {@link values}.
+   *
+   * A value-free filter rejects a value the data does not carry. The question is
+   * what "the data" means. The rows a list just returned are the wrong answer:
+   * they are a POPULATION, and a value can be real while no row carries it — a
+   * category the graph declares with zero standards filed under it, a
+   * `ds:ConceptType` no concept uses yet. Validating against rows turns those
+   * into `INVALID_INPUT`, when the honest answer is a calm empty list.
+   *
+   * So the vocabulary is read from the graph directly, from the same terms the
+   * surface that ENUMERATES it reads (`standard categories` reads `cs:Category`
+   * / `cs:slug`; so does the `category` filter's vocabulary query). The ruling
+   * this honours is "the graph is the vocabulary, don't hard-code the slugs" —
+   * rows were never the graph, just the part of it that answered.
+   *
+   * Without it a value-free filter falls back to the observed rows, which is the
+   * only evidence available; that is a NARROWER vocabulary than the truth, and a
+   * story whose dimension has an authoritative source should declare it.
+   */
+  readonly vocabulary?: PackFilterVocabulary;
   /** Help text (defaults to a generated description). */
   readonly description?: string;
 }
 
+/** The authoritative value set for a value-free {@link PackFilter}. */
+export interface PackFilterVocabulary {
+  /** SPARQL SELECT producing one row per admissible value. */
+  readonly query: string;
+  /**
+   * SELECT variable carrying the value (without `?`). Defaults to the filter's
+   * own {@link PackFilter.variable}.
+   */
+  readonly variable?: string;
+}
+
 /**
  * Free-text search over list rows: a `--search` string keeping a row when ANY
  * named SELECT variable contains the term (case-insensitive substring). Applied
@@ -239,6 +285,49 @@ export interface PackCompletion {
   readonly minChars?: number;
 }
 
+/**
+ * How much an entity's containing SCOPE is worth when a name reaches several
+ * entities at once — the ranking factor {@link PackLookup.scopeWeight} declares.
+ *
+ * DERIVED, never enumerated. The scope's own name is a path (`Global`,
+ * `Apps/Launchpad`), so its DEPTH is a fact the graph already states, and a
+ * scope nobody has heard of yet inherits its place the day it appears. An
+ * enumerated ranking would have to be edited for each new one, and the one
+ * nobody edited would silently rank first.
+ *
+ * The weight falls by {@link falloff} per level below the top, so the top level
+ * is worth 1 and each nesting step costs the same again; floored at 0, so a very
+ * deep scope can never turn negative and invert the type factor it multiplies.
+ *
+ * {@link asserted} is the retirement path for the DERIVATION, not for this
+ * declaration: an asserted value wins over the derived one
+ * (`COALESCE(?asserted, ?derived)`), so the day the ontology states the ranking
+ * itself, the depth heuristic stops mattering and `falloff` becomes inert.
+ *
+ * The declaration itself must stay. Every read of {@link asserted} is reached
+ * through this object, so deleting it does not fall back to the ontology's rank
+ * — it removes scope ranking from the query altogether and silently returns the
+ * lookup to `STR(?uri)` order, which is the defect this exists to fix. What
+ * retires is the derivation, and what remains is `via` plus `asserted`.
+ */
+export interface PackScopeWeight {
+  /** The entity → scope edge (e.g. `ds:tier`). */
+  readonly via: string;
+  /**
+   * The scope property holding its path-shaped name (e.g. `ds:name`), whose
+   * `/`-separated depth derives the weight.
+   *
+   * It must be the NAME, not the IRI: the live tiers spell the same scope
+   * `ds:apps_launchpad` and `"Apps/Launchpad"`, and only the name carries the
+   * separator that makes the hierarchy legible.
+   */
+  readonly by: string;
+  /** Score cost per level below the top, 0–1 (e.g. 0.2 → 1, 0.8, 0.6, …). */
+  readonly falloff: number;
+  /** An asserted weight on the scope, which WINS over the derived one. */
+  readonly asserted?: string;
+}
+
 /**
  * The lookup half of a pack. The query is generated from `by` and `type`/`types`
  * — user-supplied names are escaped by the generator, never interpolated by the
@@ -256,6 +345,29 @@ export interface PackLookup {
   readonly source?: "sparql" | "graphql";
   /** Property whose value names the entity — prefixed name or IRI. */
   readonly by: string;
+  /**
+   * What names an entity that carries no {@link by} value. Absent (the default)
+   * means NOTHING does: the `by` triple is required, and an entity without one
+   * is not addressable by name and never drawn by `sample`.
+   *
+   * `"iri"` opts the family into an IRI-DERIVED name — the local name after the
+   * last `#`/`/`, with dot-separated hierarchy segments published as slashes
+   * (`cs:react.component.props` → `react/component/props`).
+   *
+   * DECLARE IT ONLY WHEN THE STORY'S `list` PUBLISHES THE SAME DERIVED NAME.
+   * The option exists to keep the two halves of the two-step grammar over ONE
+   * population: `standard list` synthesizes a name for the ~87% of code
+   * standards carrying no `cs:name`, so `standard lookup` must answer to it.
+   * Turning it on where the list does NOT publish such a name is the mirror
+   * defect — `token list` requires `ds:tokenId`, so a `ds:Token` without one
+   * would become addressable and sampleable under a name the list never
+   * published.
+   *
+   * Requires a class constraint ({@link type}/{@link types}): the derived name
+   * is only as trustworthy as the class that vouches for the entity, and
+   * without one there is nothing to bound the scan with either.
+   */
+  readonly nameFallback?: "iri";
   /** Optional single class constraint — prefixed name or IRI. */
   readonly type?: string;
   /** CLI description for the lookup command (defaults to a generated one). */
@@ -271,8 +383,9 @@ export interface PackLookup {
    * Relative importance per addressed type, prefixed type → 0–1 (unlisted types
    * default to 1). Editorial judgement about which of a noun's classes matters
    * most, declared as DATA rather than frozen into the kernel — it feeds the MCP
-   * listing's `annotations.priority` AND breaks ties in URI-completion ranking,
-   * so a `ds:Subcomponent` at 0.6 sinks below every component at equal match.
+   * listing's `annotations.priority`, breaks ties in URI-completion ranking, AND
+   * is one factor of the score a name resolve ORDERS BY, so a `ds:Subcomponent`
+   * at 0.6 sinks below every component at equal match.
    *
    * A separate map rather than an entry shape on `types` so `types` keeps its
    * flat `readonly string[]` form and the addition is non-breaking. A key naming
@@ -280,6 +393,16 @@ export interface PackLookup {
    * is how a weight that never applied survives review.
    */
   readonly weights?: Readonly<Record<string, number>>;
+  /**
+   * The OTHER factor of that score: how much an entity's containing scope is
+   * worth, derived from how DEEP that scope sits in its own hierarchy.
+   *
+   * {@link weights} answers "which KIND of thing did they mean"; this answers
+   * "whose?". They multiply rather than tiebreak, because neither subsumes the
+   * other: a whole component in a narrow scope still beats a mere part of a
+   * block in the widest one.
+   */
+  readonly scopeWeight?: PackScopeWeight;
   /**
    * GraphQL type or interface the generated document's inline fragment targets
    * (`source: "graphql"` only). Defaults to the local name of `type`; required