@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/render/style.test.ts

@@ -1,31 +1,82 @@
-import { describe, expect, it } from "vitest";
-import { defaultStyle, styleFor } from "./style.js";
-
-describe("styleFor", () => {
-  it("passes every color through unchanged when disabled", () => {
-    const style = styleFor(false);
-    expect(style.enabled).toBe(false);
-    expect(style.bold("x")).toBe("x");
-    expect(style.dim("x")).toBe("x");
-    expect(style.cyan("x")).toBe("x");
-    expect(style.green("x")).toBe("x");
-    expect(style.yellow("x")).toBe("x");
+/**
+ * The color gate.
+ *
+ * `forbidsColor` is tested directly because it encodes a convention with two
+ * counter-intuitive edges — an empty assignment does NOT disable, and any
+ * non-empty value DOES, including `0`. The zero-escape guarantee is asserted
+ * against the shared chalk instance, which is what the four modules that bypass
+ * `RenderStyle` actually reach for.
+ */
+
+import chalk from "chalk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { forbidsColor, styleFor } from "./style.js";
+
+/** The ANSI escape introducer, written as an escape so no control byte
+ * sits in the source. Assertions read "does not contain this". */
+const ANSI_ESCAPE = "\u001B[";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("forbidsColor", () => {
+  it("disables for any non-empty value, whatever it says", () => {
+    expect(forbidsColor({ NO_COLOR: "1" })).toBe(true);
+    // Counter-intuitive and deliberate: the value is never parsed.
+    expect(forbidsColor({ NO_COLOR: "0" })).toBe(true);
+    expect(forbidsColor({ NO_COLOR: "false" })).toBe(true);
   });
 
-  it("reports enabled and drives chalk when enabled", () => {
-    const style = styleFor(true);
-    expect(style.enabled).toBe(true);
-    // A non-TTY test process leaves chalk at level 0, so the text survives
-    // verbatim; what the beautified renderers gate on is `enabled`.
-    expect(style.cyan("x")).toContain("x");
+  it("does NOT disable for an absent or empty variable", () => {
+    expect(forbidsColor({})).toBe(false);
+    expect(forbidsColor({ NO_COLOR: "" })).toBe(false);
   });
 });
 
-describe("defaultStyle", () => {
-  it("is disabled when stdout is not a TTY (keeps piped output byte-stable)", () => {
-    // The vitest runner's stdout is never a TTY, so the beautify seam is inert
-    // here — the guarantee that piped / agent output is unstyled and stable.
-    expect(process.stdout.isTTY).not.toBe(true);
-    expect(defaultStyle().enabled).toBe(false);
+describe("the plain style emits no escapes (PROTECTED)", () => {
+  it("returns its input untouched for every role", () => {
+    const plain = styleFor(false);
+    // `enabled` rides alongside the roles, so select the callables rather than
+    // assuming the shape — a role added later is then covered automatically.
+    const roles = Object.values(plain).filter(
+      (value): value is (text: string) => string => typeof value === "function",
+    );
+    expect(roles.length).toBeGreaterThan(0);
+    for (const role of roles) {
+      expect(role("text")).toBe("text");
+      expect(role("text")).not.toContain(ANSI_ESCAPE);
+    }
+  });
+});
+
+describe("NO_COLOR reaches the shared chalk instance (PROTECTED)", () => {
+  // The defect this pins: the gate delegated to chalk, and the vendored
+  // `supports-color` it ships has no NO_COLOR branch at all — so the flag did
+  // nothing while the code asserted it worked. Re-importing under a stubbed env
+  // exercises the module-load check that now zeroes the level.
+  it("zeroes chalk's level, so even direct chalk callers go plain", async () => {
+    const level = chalk.level;
+    try {
+      // FORCE a color-capable level first. Under vitest there is no TTY, so
+      // chalk already reports 0 and the assertion below would hold whether or
+      // not the module does anything — the test would pass with the fix
+      // deleted, which is no test at all. Starting from 3 makes the zeroing the
+      // only thing that can satisfy it.
+      chalk.level = 3;
+      expect(chalk.cyan("text")).toContain(ANSI_ESCAPE);
+
+      vi.stubEnv("NO_COLOR", "1");
+      vi.resetModules();
+      await import("./style.js");
+
+      expect(chalk.level).toBe(0);
+      // The four modules that bypass RenderStyle call chalk exactly like this.
+      expect(chalk.cyan("text")).toBe("text");
+      expect(chalk.bold("text")).not.toContain(ANSI_ESCAPE);
+    } finally {
+      chalk.level = level;
+      vi.resetModules();
+    }
   });
 });

package/src/kernel/render/style.ts

@@ -58,13 +58,43 @@ export function styleFor(enabled: boolean): RenderStyle {
   };
 }
 
+/**
+ * Whether the environment forbids color outright.
+ *
+ * `NO_COLOR` is honored when PRESENT AND NON-EMPTY, whatever its value — an
+ * empty assignment is explicitly not a request to disable (no-color.org). The
+ * value is never parsed: `NO_COLOR=0` still disables, which surprises people
+ * and is nonetheless what the convention says.
+ *
+ * @param env - The environment to read.
+ * @returns True when color must not be emitted.
+ */
+export function forbidsColor(env: NodeJS.ProcessEnv): boolean {
+  const value = env.NO_COLOR;
+  return value !== undefined && value !== "";
+}
+
+// Applied to the SHARED chalk instance at module load, not inside
+// `defaultStyle()`, because four modules reach for `chalk` directly rather than
+// through `RenderStyle` — help formatting, doctor, upgrade and the colophon's
+// Markdown renderer. Gating only the style seam would leave every one of them
+// still emitting escapes. Zeroing the level once covers them by construction,
+// including any site added later.
+//
+// This used to be delegated to chalk, and the delegation was silent: the
+// vendored `supports-color` this version ships handles `FORCE_COLOR` and has no
+// `NO_COLOR` branch at all, so the flag did nothing while the code asserted it
+// worked.
+if (forbidsColor(process.env)) chalk.level = 0;
+
 /**
  * The active style for this process's stdout.
  *
  * Gated on BOTH signals: stdout must be an attended TTY, so piped / redirected /
  * MCP output stays byte-stable even where `supports-color` fires off a TTY (CI
  * sets `GITHUB_ACTIONS`, which chalk honors); AND chalk must report a usable
- * color level, so `NO_COLOR` on a real terminal still yields the plain form.
+ * color level, which the module-load check above forces to zero under
+ * `NO_COLOR`.
  *
  * @returns A colorizing style on a color-capable TTY, else the identity styler.
  * @note Impure — reads `process.stdout.isTTY` and chalk's color level.

package/src/kernel/render/turtle.ts

@@ -0,0 +1,222 @@
+/**
+ * Serialize an entity's neighbourhood as Turtle — the dense form of the read.
+ *
+ * The JSON projection is faithful but expensive: one named node costs about 95
+ * bytes of wrapper to convey thirteen characters, and that overhead is paid per
+ * term. Measured on one button, structure alone was ~6.1 KB of a 15.8 KB read.
+ * Turtle spends the prefixes ONCE and then writes each term as itself.
+ *
+ * It is not merely shorter — it is the shape this data already has:
+ *
+ * - IRI versus literal is SYNTAX (`ds:Foo` against `"Foo"`), which is the whole
+ *   thing the typed-term projection had to carry a `termType` field to say.
+ * - A blank node is `[ … ]` inline, which is exactly the record the reader
+ *   assembles by hand for the JSON form.
+ * - Datatypes and language tags are native (`"x"@en`, `"2026-02-20"^^xsd:date`).
+ * - An inbound edge is just a triple written the other way round. The whole
+ *   `InboundGroup` structure exists only because JSON cannot point an arrow
+ *   backwards.
+ *
+ * Counts, samples and truncations ride as `#` comments. That is not a fallback:
+ * a comment is the one place a serialization can say something ABOUT the data
+ * without asserting it as data, and a reader — human or model — takes it the
+ * same way.
+ *
+ * Pure: it reads only the projection it is handed, so the same neighbourhood
+ * always renders the same bytes.
+ */
+
+import type {
+  InboundGroup,
+  InspectResult,
+  NestedRecord,
+  ReadTerm,
+} from "../runtime/readEntity.js";
+
+/** Characters that must be escaped inside a single-line Turtle literal. */
+const ESCAPES: Readonly<Record<string, string>> = {
+  "\\": "\\\\",
+  '"': '\\"',
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+/** Whether a literal is better served by a triple-quoted long string. */
+function isMultiline(value: string): boolean {
+  return value.includes("\n");
+}
+
+/** Escape a literal for the single-line `"…"` form. */
+function escapeShort(value: string): string {
+  return value.replace(/[\\"\n\r\t]/g, (char) => ESCAPES[char] ?? char);
+}
+
+/**
+ * Escape a literal for the `"""…"""` form.
+ *
+ * Only backslashes and a trailing/tripled quote need attention there — newlines
+ * are the entire point of the form and must survive untouched, which is what
+ * keeps an embedded YAML or Markdown body readable rather than turning it into
+ * one `\n`-riddled line.
+ */
+function escapeLong(value: string): string {
+  return (
+    value
+      .replace(/\\/g, "\\\\")
+      .replace(/"""/g, '\\"\\"\\"')
+      // A value ENDING in a quote would run straight into the closing delimiter
+      // and produce four quotes, which no parser reads as intended. Truncation
+      // makes this reachable on ordinary prose, not just on hostile input.
+      .replace(/"$/, '\\"')
+  );
+}
+
+/**
+ * Write a name that may or may not have compacted.
+ *
+ * `compactUri` returns its input UNCHANGED when no namespace matches, so a
+ * datatype or predicate outside the prefix map arrived here as a bare absolute
+ * IRI and was emitted raw — producing `"x"^^http://example.com/type`, which no
+ * parser accepts. A prefixed name goes through as-is; anything else is wrapped.
+ */
+function asName(value: string): string {
+  return /^[A-Za-z][\w.-]*:[^/]/.test(value) && !value.includes("://")
+    ? value
+    : `<${value}>`;
+}
+
+/** Render one term in Turtle: a prefixed name, an `<iri>`, or a literal. */
+function renderTerm(term: ReadTerm): string {
+  if (term.termType === "NamedNode") {
+    return term.prefixed ?? `<${term.value}>`;
+  }
+  if (term.termType === "BlankNode") {
+    // A bare `[]` — the label is store-local and re-minted on every load, so
+    // writing it would publish an identifier that means nothing on the next read.
+    return "[]";
+  }
+  const body = isMultiline(term.value)
+    ? `"""${escapeLong(term.value)}"""`
+    : `"${escapeShort(term.value)}"`;
+  // Direction is RDF 1.2's `@lang--dir`; it only ever accompanies a language.
+  if (term.language) {
+    return `${body}@${term.language}${term.direction ? `--${term.direction}` : ""}`;
+  }
+  if (term.datatype) return `${body}^^${asName(term.datatype)}`;
+  return body;
+}
+
+/**
+ * `# ds:guidelines — 5,814 chars, showing 400` — states a preview as a preview.
+ *
+ * On its OWN line ABOVE the triple, never trailing it: a Turtle comment runs to
+ * end of line, so a note placed after the object swallows the `;` or `.` that
+ * terminates the statement and silently breaks the document.
+ */
+function truncationNote(predicate: string, term: ReadTerm): string | undefined {
+  if (!term.truncated || term.length === undefined) return undefined;
+  const total = term.length.toLocaleString("en-US");
+  return `  # ${predicate} — ${total} chars, showing ${term.value.length}`;
+}
+
+/** Render one inlined blank node as a Turtle `[ … ]` record. */
+function renderNested(record: NestedRecord): string {
+  const fields = Object.entries(record).map(([field, value]) => {
+    // `type` was hoisted out of the record body on the way in; `a` is Turtle's
+    // own shorthand for it, so it goes back exactly where it came from.
+    const predicate = field === "type" ? "a" : asName(field);
+    return `${predicate} ${renderTerm(value)}`;
+  });
+  return `[ ${fields.join(" ; ")} ]`;
+}
+
+/** The prefixes a rendering actually uses, so the header declares no more. */
+function usedPrefixes(
+  text: string,
+  prefixes: Readonly<Record<string, string>>,
+): string[] {
+  return Object.entries(prefixes)
+    .filter(([prefix]) => new RegExp(`\\b${prefix}:`).test(text))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([prefix, namespace]) => `@prefix ${prefix}: <${namespace}> .`);
+}
+
+/** `# rdf:type — 330 total, sample of 5` and the triples under it. */
+function renderInbound(subject: string, group: InboundGroup): string[] {
+  const predicate = renderTerm(group.predicate);
+  const total = group.count.toLocaleString("en-US");
+  // An empty `subjects` means two different things, and conflating them told a
+  // lie: at `summary` EVERY group is empty because the level exhibits none, so
+  // claiming "none individually addressable" there libelled perfectly nameable
+  // subjects. Only a level that WOULD have shown exemplars can conclude that
+  // none exist.
+  const exhibits = group.exhibits ?? 0;
+  const note =
+    exhibits > 0 && group.subjects.length === 0 && group.count > 0
+      ? `# ${predicate} — ${total} total, none individually addressable; use the noun's list verb`
+      : group.sampled
+        ? `# ${predicate} — ${total} total, sample of ${group.subjects.length}; use the noun's list verb for the full set`
+        : group.truncated
+          ? `# ${predicate} — ${total} total, showing ${group.subjects.length}`
+          : `# ${predicate} — ${total}`;
+  return [
+    note,
+    ...group.subjects.map((s) => `${renderTerm(s)} ${predicate} ${subject} .`),
+  ];
+}
+
+/**
+ * Render an entity's neighbourhood as a Turtle document.
+ *
+ * @param result - The neighbourhood projection to serialize.
+ * @param prefixes - The store's merged prefix map, for the `@prefix` header.
+ * @returns A Turtle document: header, the subject's own triples, its inlined
+ *   blank nodes, then the edges pointing at it.
+ */
+export function toTurtle(
+  result: InspectResult,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  const subject = result.prefixed ?? `<${result.uri}>`;
+  const body: string[] = [];
+
+  // The subject's own triples, one predicate per line.
+  const predicates: string[] = [];
+  for (const group of result.groups) {
+    const predicate = renderTerm(group.predicate);
+    // Blank objects are written as their inlined records instead, so they are
+    // skipped here — emitting both would assert the same edge twice.
+    const objects = group.objects.filter((o) => o.termType !== "BlankNode");
+    if (objects.length === 0) continue;
+    const keyword = predicate === "rdf:type" ? "a" : predicate;
+    // Notes are folded INTO the element, above its statement, so the `;` the
+    // join appends always lands on the statement line. Pushed as siblings they
+    // would each take a separator of their own — into a comment, which runs to
+    // end of line and eats it.
+    const notes = objects
+      .map((o) => truncationNote(keyword, o))
+      .filter((n): n is string => n !== undefined);
+    const rendered = objects.map(renderTerm).join(", ");
+    predicates.push([...notes, `  ${keyword} ${rendered}`].join("\n"));
+  }
+  for (const [via, records] of Object.entries(result.nested)) {
+    predicates.push(
+      `  ${via}\n    ${records.map(renderNested).join(",\n    ")}`,
+    );
+  }
+  if (predicates.length > 0) {
+    body.push(`${subject}\n${predicates.join(" ;\n")} .`);
+  }
+
+  if (result.inbound.length > 0) {
+    body.push("", "# ── referenced by ──");
+    for (const group of result.inbound) {
+      body.push(...renderInbound(subject, group));
+    }
+  }
+
+  const text = body.join("\n");
+  const header = usedPrefixes(text, prefixes);
+  return [...header, "", text].join("\n").trimEnd();
+}

package/src/kernel/runtime/graphpack/build.ts

@@ -39,6 +39,7 @@ import {
   MANIFEST_FILE,
   type Manifest,
   SCHEMA_FILE,
+  STORIES_FILE,
 } from "./types.js";
 
 /** One RDF source to build into a pack. */
@@ -53,10 +54,17 @@ export interface BuildPackInput {
 export interface BuildPackOptions {
   readonly name: string;
   readonly version: string;
-  /** The config `packages` ref (verbatim) or a label. */
+  /** The config `packs` ref (verbatim) or a label. */
   readonly sourceRef: string;
   /** Prefixes the store (and every query) is built with. */
   readonly prefixes?: Readonly<Record<string, string>>;
+  /**
+   * The `stories/*.json` files the resolved packages ship, as raw text. Hash
+   * inputs like any other source — a story-only edit is a new pack, and a set
+   * of packages shipping none keeps the hash it had before stories existed, so
+   * no cached pack is invalidated by rehashing.
+   */
+  readonly stories?: readonly BuildPackInput[];
 }
 
 /** The outcome of a pack build (or cache hit). */
@@ -72,7 +80,8 @@ export interface BuildPackResult {
  * Build (or reuse) the pack for a set of source inputs.
  *
  * @param inputs - The RDF sources (path + content).
- * @param options - Provenance and the prefixes to build with.
+ * @param options - Provenance, the prefixes to build with, and the packages'
+ *   carried read stories.
  * @returns The pack directory, its content hash, and whether it was reused.
  * @note Impure — creates a store, compiles the schema, writes the pack.
  */
@@ -80,8 +89,12 @@ export async function buildPack(
   inputs: readonly BuildPackInput[],
   options: BuildPackOptions,
 ): Promise<BuildPackResult> {
+  const stories = options.stories ?? [];
   const hash = await contentHash(
-    inputs.map((input) => ({ path: input.path, content: input.content })),
+    [...inputs, ...stories].map((input) => ({
+      path: input.path,
+      content: input.content,
+    })),
   );
   const dir = packDir(hash);
 
@@ -121,6 +134,19 @@ export async function buildPack(
       const index = await buildIndex(store, store.prefixes, hash);
       writeFileSync(join(temp, INDEX_FILE), JSON.stringify(index));
 
+      // Written UNCONDITIONALLY (`[]` when the packages ship none): the artifact
+      // set is FIVE AND ONLY FIVE, and `packIsComplete` gates on it, so a pack
+      // whose hash covers stories always holds them.
+      writeFileSync(
+        join(temp, STORIES_FILE),
+        JSON.stringify(
+          stories.map((story) => ({
+            source: story.path,
+            content: story.content,
+          })),
+        ),
+      );
+
       const tripleCount = await countTriples(store);
       // Distinct abox subjects — the same figure `entityTotal` reports (A10),
       // so `sources status` reads it from the manifest without parsing the

package/src/kernel/runtime/graphpack/buildIndex.test.ts

@@ -6,6 +6,7 @@ import {
   OWL_EXPORT_TTL,
 } from "../../../testing/fixtures/graph/owlExport.js";
 import { entityTotal } from "../../completion/entitySource.js";
+import { VOCABULARY } from "../../vocabulary.js";
 import { buildIndex } from "./buildIndex.js";
 import type { PackIndex } from "./types.js";
 
@@ -101,3 +102,48 @@ describe("buildIndex — real-data counters/classifiers (backlog A)", () => {
     );
   });
 });
+
+/**
+ * The alternative-name property is DECLARED by the distribution, so a pack whose
+ * prefix map does not bind its prefix is an ordinary case — a third-party pack
+ * outside that namespace — not an error. Resolving the term strictly would throw
+ * there and take the whole pack build down with it.
+ */
+describe("buildIndex — the declared alternative-name property", () => {
+  let store: Store;
+
+  beforeAll(async () => {
+    store = await createStore({
+      sources: [{ content: OWL_EXPORT_TTL, path: "owl-export.ttl" }],
+      prefixes: OWL_EXPORT_PREFIXES,
+    });
+  });
+
+  afterAll(() => {
+    store.dispose();
+  });
+
+  it("projects it into altNames when the pack binds its prefix", async () => {
+    const index = await buildIndex(store, OWL_EXPORT_PREFIXES, "bound");
+    const named = index.entities.filter((entity) => entity.altNames);
+    expect(named.length).toBeGreaterThan(0);
+    expect(named.at(0)?.altNames?.length).toBeGreaterThan(0);
+  });
+
+  it("still builds, carrying no altNames, when the pack binds no such prefix", async () => {
+    // Unbind the prefix the DECLARATION uses, whatever it is — the subject here
+    // is the declared property, so naming a prefix would couple this case to
+    // today's values and quietly stop testing anything if they moved.
+    const declared = VOCABULARY.altName.slice(
+      0,
+      VOCABULARY.altName.indexOf(":"),
+    );
+    const { [declared]: _unbound, ...withoutDomain } = OWL_EXPORT_PREFIXES;
+    const index = await buildIndex(store, withoutDomain, "unbound");
+    // The graph is unchanged, so every entity is still indexed…
+    expect(index.entities.length).toBeGreaterThan(0);
+    // …they simply carry no alternative names, exactly as a pack that never
+    // authored the property would.
+    expect(index.entities.filter((entity) => entity.altNames)).toEqual([]);
+  });
+});

package/src/kernel/runtime/graphpack/buildIndex.ts

@@ -1,11 +1,16 @@
 /**
  * Build the storeless entity index (`index.json`) from a populated store.
  *
- * A lean port of the v1 `buildGraphIndex` (#856): three bulk SPARQL queries —
- * types, labels, and instance counts — joined in memory, rather than a query
- * per subject. Only typed named-node subjects are indexed (untyped subjects and
- * blank-node subjects are reachable via `graph query` but never listed). Each
- * entity carries the FROZEN `{ name, type }` minimum plus the enrichment fields
+ * A lean port of the v1 `buildGraphIndex` (#856): a few bulk SPARQL queries —
+ * types (which also yield the instance counts), labels, descriptions and
+ * alternative names — joined in memory, rather than a query per subject. Only
+ * the last names a DOMAIN property, and it is read from the distribution's
+ * declaration rather than spelled out here; see {@link resolveAltNamePredicate} for
+ * the pack that binds no such prefix.
+ *
+ * Only typed named-node subjects are indexed (untyped subjects and blank-node
+ * subjects are reachable via `graph query` but never listed). Each entity
+ * carries the FROZEN `{ name, type }` minimum plus the enrichment fields
  * (`uri`, `prefixed`, `types`, `label`, `box`) the completion tier and reads
  * use. The output is pure JSON — no store handle survives — so the completion
  * tier reads it without ever booting oxigraph.
@@ -24,7 +29,8 @@
  *   stays completable instead of vanishing behind the tbox facet.
  */
 
-import { compactUri } from "../../render/compactUri.js";
+import { compactUri } from "../../render/index.js";
+import { VOCABULARY } from "../../vocabulary.js";
 import type { PackIndex, PackIndexEntity } from "./types.js";
 
 type Store = import("@canonical/ke").Store;
@@ -75,14 +81,6 @@ const DESCRIPTION_PREDICATES = [
   "http://schema.org/description",
 ];
 
-/**
- * Alternative-name predicates: `ds:name`, the property `tier lookup` (and other
- * `ds:name`-addressed families) match on. Projected into `altNames` so the
- * storeless name-completion sources can offer those tokens exactly, without a
- * store boot. Distinct from the display `label` — a subject may carry both.
- */
-const ALT_NAME_PREDICATES = ["https://ds.canonical.com/name"];
-
 const isStdVocab = (uri: string): boolean =>
   STD_VOCAB_PREFIXES.some((ns) => uri.startsWith(ns));
 
@@ -141,6 +139,37 @@ function classify(fullTypes: readonly string[]): Facet[] {
 const valuesList = (uris: readonly string[]): string =>
   uris.map((uri) => `<${uri}>`).join(" ");
 
+/**
+ * Expand the declared alternative-name property against a pack's prefix map.
+ *
+ * That property is what a family is addressed by, so the storeless completion
+ * sources can offer those tokens exactly and a bespoke lookup can match them,
+ * without a store boot. Distinct from the display `label`: a subject may carry
+ * both.
+ *
+ * The distribution DECLARES it as a prefixed name; this resolves it against the
+ * PACK's own prefixes, which are not the distribution's. A pack that binds no
+ * such prefix simply carries no alternative names — the normal case for a
+ * third-party pack outside the distribution's namespace. Expanding through
+ * `packs/iri.ts` instead would THROW on exactly that pack and take its whole
+ * build down, so this degrades and the caller skips the query.
+ *
+ * The split needs no guard: `kernel/vocabulary.ts` has already held the term to
+ * `prefix:local`, so the colon is there and both sides are non-empty.
+ *
+ * @param prefixes - The store's merged prefix map.
+ * @returns The full IRI to collect, or `undefined` when the prefix is unbound.
+ */
+function resolveAltNamePredicate(
+  prefixes: Readonly<Record<string, string>>,
+): string | undefined {
+  const colon = VOCABULARY.altName.indexOf(":");
+  const namespace = prefixes[VOCABULARY.altName.slice(0, colon)];
+  return namespace === undefined
+    ? undefined
+    : `${namespace}${VOCABULARY.altName.slice(colon + 1)}`;
+}
+
 /** Language rank for label selection: untagged (0) < `@en` (1) < any other (2). */
 function rankLanguage(language: string): number {
   if (language === "") return 0;
@@ -230,6 +259,7 @@ export async function buildIndex(
   prefixes: Readonly<Record<string, string>>,
   contentHash: string,
 ): Promise<PackIndex> {
+  const altNameUri = resolveAltNamePredicate(prefixes);
   const [typesResult, labelResult, descResult, altNameResult] =
     await Promise.all([
       store.query(
@@ -241,9 +271,11 @@ export async function buildIndex(
       store.query(
         `SELECT ?s ?p ?desc WHERE { ?s ?p ?desc . VALUES ?p { ${valuesList(DESCRIPTION_PREDICATES)} } }` as never,
       ) as Promise<import("@canonical/ke").SelectResult>,
-      store.query(
-        `SELECT ?s ?p ?alt WHERE { ?s ?p ?alt . VALUES ?p { ${valuesList(ALT_NAME_PREDICATES)} } }` as never,
-      ) as Promise<import("@canonical/ke").SelectResult>,
+      altNameUri === undefined
+        ? undefined
+        : (store.query(
+            `SELECT ?s ?p ?alt WHERE { ?s ?p ?alt . VALUES ?p { <${altNameUri}> } }` as never,
+          ) as Promise<import("@canonical/ke").SelectResult>),
     ]);
 
   const typesBySubject = new Map<string, string[]>();
@@ -273,7 +305,10 @@ export async function buildIndex(
     "desc",
     DESCRIPTION_PREDICATES,
   );
-  const altNamesBySubject = allBySubject(altNameResult, "alt");
+  const altNamesBySubject =
+    altNameResult === undefined
+      ? new Map<string, string[]>()
+      : allBySubject(altNameResult, "alt");
 
   const entities: PackIndexEntity[] = [];
   for (const [subject, fullTypes] of typesBySubject) {