@canonical/pragma-cli 0.32.0 → 0.33.0

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

@@ -4,11 +4,24 @@
  * 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 nodes are reachable via `graph query` but never listed). Each entity
- * carries the FROZEN `{ name, type }` minimum plus the enrichment fields
+ * 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.
+ *
+ * Real-data correctness (things a single-typed toy graph never exercises):
+ * - Blank-node `rdf:type` objects (SHACL shapes, RDF lists) are ignored — a
+ *   `_:b0` is never a domain class and must not become a `type:"_:b0"` key.
+ * - The abox primary type is the LEXICALLY-SMALLEST domain class, a
+ *   deterministic tie-break: SPARQL returns a subject's types in unspecified
+ *   order, so a multi-domain individual would otherwise get an arbitrary
+ *   completion key that flips across builds/engines.
+ * - Multilingual labels prefer untagged / `@en`, then the lexically smallest —
+ *   never the store's arbitrary first row.
+ * - An OWL-punned subject (a class/property IRI ALSO asserted as a domain
+ *   individual) emits BOTH its tbox and abox facet, so its abox membership
+ *   stays completable instead of vanishing behind the tbox facet.
  */
 
 import { compactUri } from "../../render/compactUri.js";
@@ -73,51 +86,109 @@ const ALT_NAME_PREDICATES = ["https://ds.canonical.com/name"];
 const isStdVocab = (uri: string): boolean =>
   STD_VOCAB_PREFIXES.some((ns) => uri.startsWith(ns));
 
-/** Classify a subject's full types into a box and a primary (filter) type. */
-function classify(
-  fullTypes: readonly string[],
-): { box: "tbox" | "abox"; primary: string } | null {
-  if (fullTypes.length === 0) return null;
+/** One classification facet: which box a subject occupies + its primary type. */
+interface Facet {
+  readonly box: "tbox" | "abox";
+  readonly primary: string;
+}
+
+/**
+ * Classify a subject's full types into its facets — one per box it occupies.
+ *
+ * A plain individual or a plain class yields ONE facet. An OWL-punned subject
+ * (a class/property IRI ALSO asserted as a domain individual) yields BOTH its
+ * tbox and abox facet (A8), so its abox membership stays completable rather than
+ * disappearing behind the tbox one. The abox primary is the lexically-smallest
+ * domain class — a deterministic tie-break (A3), not the store's first row.
+ *
+ * @param fullTypes - The subject's asserted `rdf:type` values (blank nodes
+ *   already dropped), in store order.
+ * @returns The subject's facets (empty when it has no usable type).
+ */
+function classify(fullTypes: readonly string[]): Facet[] {
+  if (fullTypes.length === 0) return [];
+  const facets: Facet[] = [];
   const classMeta = fullTypes.find((t) => CLASS_METATYPES.has(t));
-  if (classMeta) return { box: "tbox", primary: classMeta };
   const propMeta = fullTypes.find((t) => PROPERTY_METATYPES.has(t));
-  if (propMeta) return { box: "tbox", primary: propMeta };
-  // An individual: its filter key is the most specific domain class.
-  const domain =
-    fullTypes.find((t) => t !== NAMED_INDIVIDUAL && !isStdVocab(t)) ??
-    fullTypes.find((t) => t !== NAMED_INDIVIDUAL) ??
-    fullTypes[0];
-  return { box: "abox", primary: domain as string };
+  if (classMeta !== undefined) facets.push({ box: "tbox", primary: classMeta });
+  else if (propMeta !== undefined)
+    facets.push({ box: "tbox", primary: propMeta });
+
+  // A subject's domain classes: its own types minus the structural std vocab
+  // and the `owl:NamedIndividual` typing artifact. Sorted, so the abox primary
+  // (the smallest) is stable across builds/engines regardless of store order.
+  const domainClasses = fullTypes
+    .filter((t) => t !== NAMED_INDIVIDUAL && !isStdVocab(t))
+    .sort();
+  const primaryDomain = domainClasses.at(0);
+  if (primaryDomain !== undefined) {
+    facets.push({ box: "abox", primary: primaryDomain });
+  } else if (facets.length === 0) {
+    // No schema facet and no domain class — a bare individual (only
+    // `owl:NamedIndividual`, or only std-vocab types). Keep it indexed under a
+    // deterministic primary rather than dropping it silently.
+    const fallback =
+      fullTypes
+        .filter((t) => t !== NAMED_INDIVIDUAL)
+        .sort()
+        .at(0) ?? [...fullTypes].sort().at(0);
+    if (fallback !== undefined) facets.push({ box: "abox", primary: fallback });
+  }
+  return facets;
 }
 
 /** A `VALUES ?p { … }` body from a predicate list. */
 const valuesList = (uris: readonly string[]): string =>
   uris.map((uri) => `<${uri}>`).join(" ");
 
+/** Language rank for label selection: untagged (0) < `@en` (1) < any other (2). */
+function rankLanguage(language: string): number {
+  if (language === "") return 0;
+  const lower = language.toLowerCase();
+  return lower === "en" || lower.startsWith("en-") ? 1 : 2;
+}
+
 /**
  * Per subject, keep the object whose predicate ranks HIGHEST (lowest index) in
  * `preference`. The `?p` binding is projected so the winner is chosen by declared
  * preference order: SPARQL returns solutions in an unspecified order, so keeping
  * the first row per subject would be store-order-dependent (an entity carrying
  * both `rdfs:label` and `skos:prefLabel` could index either), not ranked.
+ *
+ * Ties within a predicate (a subject with several `rdfs:label` values — the
+ * multilingual case) are broken deterministically: untagged / `@en` first, then
+ * the lexically smallest value. So `"Button"@en`/`"Bouton"@fr` always resolves
+ * to `Button`, never whichever row the store happened to return first (A7).
  */
 function preferredBySubject(
   result: import("@canonical/ke").SelectResult,
   valueVar: string,
   preference: readonly string[],
 ): Map<string, string> {
-  const best = new Map<string, { value: string; rank: number }>();
+  const best = new Map<
+    string,
+    { value: string; rank: number; langRank: number }
+  >();
   for (const term of result.termBindings) {
     if (term.s?.termType !== "NamedNode") continue;
-    const value = term[valueVar]?.value;
+    const valueTerm = term[valueVar];
     const predicate = term.p?.value;
-    if (!value || predicate === undefined) continue;
+    if (valueTerm === undefined || predicate === undefined) continue;
+    const value = valueTerm.value;
+    if (!value) continue;
     const rank = preference.indexOf(predicate);
     if (rank === -1) continue;
+    const language =
+      valueTerm.termType === "Literal" ? (valueTerm.language ?? "") : "";
+    const langRank = rankLanguage(language);
     const current = best.get(term.s.value);
-    if (current === undefined || rank < current.rank) {
-      best.set(term.s.value, { value, rank });
-    }
+    const better =
+      current === undefined ||
+      rank < current.rank ||
+      (rank === current.rank &&
+        (langRank < current.langRank ||
+          (langRank === current.langRank && value < current.value)));
+    if (better) best.set(term.s.value, { value, rank, langRank });
   }
   const picked = new Map<string, string>();
   for (const [subject, entry] of best) picked.set(subject, entry.value);
@@ -179,8 +250,13 @@ export async function buildIndex(
   const instanceCountByType: Record<string, number> = {};
   for (const term of typesResult.termBindings) {
     if (term.s?.termType !== "NamedNode") continue;
+    const typeTerm = term.type;
+    // Ignore blank-node `rdf:type` objects (SHACL shapes / RDF lists): a `_:b0`
+    // is never a domain class, so it must not become a garbage primary type or
+    // inflate the per-type instance counts (A6).
+    if (typeTerm === undefined || typeTerm.termType === "BlankNode") continue;
     const subject = term.s.value;
-    const typeUri = term.type?.value ?? "";
+    const typeUri = typeTerm.value;
     const bucket = typesBySubject.get(subject) ?? [];
     bucket.push(typeUri);
     typesBySubject.set(subject, bucket);
@@ -201,23 +277,35 @@ export async function buildIndex(
 
   const entities: PackIndexEntity[] = [];
   for (const [subject, fullTypes] of typesBySubject) {
-    const classification = classify(fullTypes);
-    if (classification === null) continue;
+    const facets = classify(fullTypes);
+    if (facets.length === 0) continue;
     const prefixed = compactUri(subject, prefixes);
     const altNames = altNamesBySubject.get(subject);
-    entities.push({
-      name: prefixed,
-      type: compactUri(classification.primary, prefixes),
-      uri: subject,
-      prefixed,
-      types: fullTypes.map((t) => compactUri(t, prefixes)),
-      label: labelBySubject.get(subject) ?? null,
-      ...(altNames && altNames.length > 0 ? { altNames } : {}),
-      box: classification.box,
-      description: descBySubject.get(subject) ?? null,
-    });
+    const typesCompact = fullTypes.map((t) => compactUri(t, prefixes));
+    const label = labelBySubject.get(subject) ?? null;
+    const description = descBySubject.get(subject) ?? null;
+    // A punned subject emits one entity per facet (tbox class + abox individual).
+    for (const facet of facets) {
+      entities.push({
+        name: prefixed,
+        type: compactUri(facet.primary, prefixes),
+        uri: subject,
+        prefixed,
+        types: typesCompact,
+        label,
+        ...(altNames && altNames.length > 0 ? { altNames } : {}),
+        box: facet.box,
+        description,
+      });
+    }
   }
-  entities.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  // Sort by name, then a deterministic tie-break (box, then type) so a punned
+  // subject's two facets keep a stable order across builds.
+  entities.sort((a, b) => {
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+    if (a.box !== b.box) return a.box === "tbox" ? -1 : 1;
+    return a.type < b.type ? -1 : a.type > b.type ? 1 : 0;
+  });
 
   return {
     version: 2,

package/src/kernel/runtime/graphpack/embedded/pack.generated.ts

@@ -1,8 +1,5 @@
 // AUTO-GENERATED by scripts/genEmbedded.ts — do not edit by hand.
 // Regenerate after changing sample.ttl: `bun run scripts/genEmbedded.ts`.
-export const dataNq =
-  '<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Card> .\n<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Button> .\n<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#componentName> "Dialog" .\n<https://pragma.canonical.com/sample#Dialog> <http://www.w3.org/2000/01/rdf-schema#label> "Dialog" .\n<https://pragma.canonical.com/sample#Dialog> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#Card> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Button> .\n<https://pragma.canonical.com/sample#Card> <https://pragma.canonical.com/sample#componentName> "Card" .\n<https://pragma.canonical.com/sample#Card> <http://www.w3.org/2000/01/rdf-schema#label> "Card" .\n<https://pragma.canonical.com/sample#Card> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#Button> <https://pragma.canonical.com/sample#componentName> "Button" .\n<https://pragma.canonical.com/sample#Button> <http://www.w3.org/2000/01/rdf-schema#label> "Button" .\n<https://pragma.canonical.com/sample#Button> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#range> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#domain> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#label> "depends on" .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#ObjectProperty> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#range> <http://www.w3.org/2001/XMLSchema#string> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#domain> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#label> "component name" .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#DatatypeProperty> .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/2000/01/rdf-schema#comment> "A reusable design-system building block." .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/2000/01/rdf-schema#label> "Component" .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Class> .\n';
-export const schemaJson =
-  '{"version":1,"sourcesHash":"8a510cc1fb8c950e","classes":[{"uri":"https://pragma.canonical.com/sample#Component","superclasses":[],"label":"Component","definition":"A reusable design-system building block."}],"properties":[{"uri":"https://pragma.canonical.com/sample#dependsOn","kind":"object","domains":["https://pragma.canonical.com/sample#Component"],"ranges":["https://pragma.canonical.com/sample#Component"],"label":"depends on"},{"uri":"https://pragma.canonical.com/sample#componentName","kind":"datatype","domains":["https://pragma.canonical.com/sample#Component"],"ranges":["http://www.w3.org/2001/XMLSchema#string"],"label":"component name"}],"inverses":[],"functionals":[],"datatypes":[],"namespaces":[["https://pragma.canonical.com/sample#","ex"]],"shaclConstraints":[],"unions":[],"instanceStats":[["http://www.w3.org/2002/07/owl#ObjectProperty",{"total":1,"named":1}],["https://pragma.canonical.com/sample#Component",{"total":3,"named":3}],["http://www.w3.org/2002/07/owl#DatatypeProperty",{"total":1,"named":1}],["http://www.w3.org/2002/07/owl#Class",{"total":1,"named":1}]],"selfReferential":[],"functionalViolations":[],"undeclaredPredicates":[],"annotations":[],"deepBlankNesting":false}';
-export const manifestJson =
-  '{"name":"pragma-sample","version":"0.31.0","sourceRef":"embedded:sample.ttl","contentHash":"bfe536dc9afc625502a8f578aadf4eb9927b55260951bc61f58cf07219593034","prefixes":{"ex":"https://pragma.canonical.com/sample#","rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#","rdfs":"http://www.w3.org/2000/01/rdf-schema#","owl":"http://www.w3.org/2002/07/owl#","xsd":"http://www.w3.org/2001/XMLSchema#"},"createdAt":"2026-07-18T04:52:05.250Z"}';
+export const dataNq = "<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Card> .\n<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Button> .\n<https://pragma.canonical.com/sample#Dialog> <https://pragma.canonical.com/sample#componentName> \"Dialog\" .\n<https://pragma.canonical.com/sample#Dialog> <http://www.w3.org/2000/01/rdf-schema#label> \"Dialog\" .\n<https://pragma.canonical.com/sample#Dialog> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#Card> <https://pragma.canonical.com/sample#dependsOn> <https://pragma.canonical.com/sample#Button> .\n<https://pragma.canonical.com/sample#Card> <https://pragma.canonical.com/sample#componentName> \"Card\" .\n<https://pragma.canonical.com/sample#Card> <http://www.w3.org/2000/01/rdf-schema#label> \"Card\" .\n<https://pragma.canonical.com/sample#Card> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#Button> <https://pragma.canonical.com/sample#componentName> \"Button\" .\n<https://pragma.canonical.com/sample#Button> <http://www.w3.org/2000/01/rdf-schema#label> \"Button\" .\n<https://pragma.canonical.com/sample#Button> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#range> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#domain> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/2000/01/rdf-schema#label> \"depends on\" .\n<https://pragma.canonical.com/sample#dependsOn> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#ObjectProperty> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#range> <http://www.w3.org/2001/XMLSchema#string> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#domain> <https://pragma.canonical.com/sample#Component> .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/2000/01/rdf-schema#label> \"component name\" .\n<https://pragma.canonical.com/sample#componentName> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#DatatypeProperty> .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/2000/01/rdf-schema#comment> \"A reusable design-system building block.\" .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/2000/01/rdf-schema#label> \"Component\" .\n<https://pragma.canonical.com/sample#Component> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Class> .\n";
+export const schemaJson = "{\"version\":1,\"sourcesHash\":\"8a510cc1fb8c950e\",\"classes\":[{\"uri\":\"https://pragma.canonical.com/sample#Component\",\"superclasses\":[],\"label\":\"Component\",\"definition\":\"A reusable design-system building block.\"}],\"properties\":[{\"uri\":\"https://pragma.canonical.com/sample#dependsOn\",\"kind\":\"object\",\"domains\":[\"https://pragma.canonical.com/sample#Component\"],\"ranges\":[\"https://pragma.canonical.com/sample#Component\"],\"label\":\"depends on\"},{\"uri\":\"https://pragma.canonical.com/sample#componentName\",\"kind\":\"datatype\",\"domains\":[\"https://pragma.canonical.com/sample#Component\"],\"ranges\":[\"http://www.w3.org/2001/XMLSchema#string\"],\"label\":\"component name\"}],\"inverses\":[],\"functionals\":[],\"datatypes\":[],\"namespaces\":[[\"https://pragma.canonical.com/sample#\",\"ex\"]],\"shaclConstraints\":[],\"unions\":[],\"instanceStats\":[[\"http://www.w3.org/2002/07/owl#ObjectProperty\",{\"total\":1,\"named\":1}],[\"https://pragma.canonical.com/sample#Component\",{\"total\":3,\"named\":3}],[\"http://www.w3.org/2002/07/owl#DatatypeProperty\",{\"total\":1,\"named\":1}],[\"http://www.w3.org/2002/07/owl#Class\",{\"total\":1,\"named\":1}]],\"selfReferential\":[],\"functionalViolations\":[],\"undeclaredPredicates\":[],\"annotations\":[],\"deepBlankNesting\":false}";
+export const manifestJson = "{\"name\":\"pragma-sample\",\"version\":\"0.31.0\",\"sourceRef\":\"embedded:sample.ttl\",\"contentHash\":\"bfe536dc9afc625502a8f578aadf4eb9927b55260951bc61f58cf07219593034\",\"prefixes\":{\"ex\":\"https://pragma.canonical.com/sample#\",\"rdf\":\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\",\"rdfs\":\"http://www.w3.org/2000/01/rdf-schema#\",\"owl\":\"http://www.w3.org/2002/07/owl#\",\"xsd\":\"http://www.w3.org/2001/XMLSchema#\"},\"createdAt\":\"1970-01-01T00:00:00.000Z\",\"tripleCount\":23,\"entityCount\":3}";

package/src/kernel/runtime/graphpack/embedded/pack.index.generated.ts

@@ -1,4 +1,3 @@
 // AUTO-GENERATED by scripts/genEmbedded.ts — do not edit by hand.
 // Regenerate after changing sample.ttl: `bun run scripts/genEmbedded.ts`.
-export const indexJson =
-  '{"version":2,"contentHash":"bfe536dc9afc625502a8f578aadf4eb9927b55260951bc61f58cf07219593034","prefixes":{"ex":"https://pragma.canonical.com/sample#","rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#","rdfs":"http://www.w3.org/2000/01/rdf-schema#","owl":"http://www.w3.org/2002/07/owl#","xsd":"http://www.w3.org/2001/XMLSchema#"},"entities":[{"name":"ex:Button","type":"ex:Component","uri":"https://pragma.canonical.com/sample#Button","prefixed":"ex:Button","types":["ex:Component"],"label":"Button","box":"abox","description":null},{"name":"ex:Card","type":"ex:Component","uri":"https://pragma.canonical.com/sample#Card","prefixed":"ex:Card","types":["ex:Component"],"label":"Card","box":"abox","description":null},{"name":"ex:Component","type":"owl:Class","uri":"https://pragma.canonical.com/sample#Component","prefixed":"ex:Component","types":["owl:Class"],"label":"Component","box":"tbox","description":"A reusable design-system building block."},{"name":"ex:Dialog","type":"ex:Component","uri":"https://pragma.canonical.com/sample#Dialog","prefixed":"ex:Dialog","types":["ex:Component"],"label":"Dialog","box":"abox","description":null},{"name":"ex:componentName","type":"owl:DatatypeProperty","uri":"https://pragma.canonical.com/sample#componentName","prefixed":"ex:componentName","types":["owl:DatatypeProperty"],"label":"component name","box":"tbox","description":null},{"name":"ex:dependsOn","type":"owl:ObjectProperty","uri":"https://pragma.canonical.com/sample#dependsOn","prefixed":"ex:dependsOn","types":["owl:ObjectProperty"],"label":"depends on","box":"tbox","description":null}],"instanceCountByType":{"https://pragma.canonical.com/sample#Component":3,"http://www.w3.org/2002/07/owl#ObjectProperty":1,"http://www.w3.org/2002/07/owl#DatatypeProperty":1,"http://www.w3.org/2002/07/owl#Class":1}}';
+export const indexJson = "{\"version\":2,\"contentHash\":\"bfe536dc9afc625502a8f578aadf4eb9927b55260951bc61f58cf07219593034\",\"prefixes\":{\"ex\":\"https://pragma.canonical.com/sample#\",\"rdf\":\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\",\"rdfs\":\"http://www.w3.org/2000/01/rdf-schema#\",\"owl\":\"http://www.w3.org/2002/07/owl#\",\"xsd\":\"http://www.w3.org/2001/XMLSchema#\"},\"entities\":[{\"name\":\"ex:Button\",\"type\":\"ex:Component\",\"uri\":\"https://pragma.canonical.com/sample#Button\",\"prefixed\":\"ex:Button\",\"types\":[\"ex:Component\"],\"label\":\"Button\",\"box\":\"abox\",\"description\":null},{\"name\":\"ex:Card\",\"type\":\"ex:Component\",\"uri\":\"https://pragma.canonical.com/sample#Card\",\"prefixed\":\"ex:Card\",\"types\":[\"ex:Component\"],\"label\":\"Card\",\"box\":\"abox\",\"description\":null},{\"name\":\"ex:Component\",\"type\":\"owl:Class\",\"uri\":\"https://pragma.canonical.com/sample#Component\",\"prefixed\":\"ex:Component\",\"types\":[\"owl:Class\"],\"label\":\"Component\",\"box\":\"tbox\",\"description\":\"A reusable design-system building block.\"},{\"name\":\"ex:Dialog\",\"type\":\"ex:Component\",\"uri\":\"https://pragma.canonical.com/sample#Dialog\",\"prefixed\":\"ex:Dialog\",\"types\":[\"ex:Component\"],\"label\":\"Dialog\",\"box\":\"abox\",\"description\":null},{\"name\":\"ex:componentName\",\"type\":\"owl:DatatypeProperty\",\"uri\":\"https://pragma.canonical.com/sample#componentName\",\"prefixed\":\"ex:componentName\",\"types\":[\"owl:DatatypeProperty\"],\"label\":\"component name\",\"box\":\"tbox\",\"description\":null},{\"name\":\"ex:dependsOn\",\"type\":\"owl:ObjectProperty\",\"uri\":\"https://pragma.canonical.com/sample#dependsOn\",\"prefixed\":\"ex:dependsOn\",\"types\":[\"owl:ObjectProperty\"],\"label\":\"depends on\",\"box\":\"tbox\",\"description\":null}],\"instanceCountByType\":{\"https://pragma.canonical.com/sample#Component\":3,\"http://www.w3.org/2002/07/owl#ObjectProperty\":1,\"http://www.w3.org/2002/07/owl#DatatypeProperty\":1,\"http://www.w3.org/2002/07/owl#Class\":1}}";

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

@@ -1,4 +1,10 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { executeLocal } from "@canonical/ke-graphql";
@@ -128,6 +134,68 @@ describe("graphpack hash stability (PROTECTED)", () => {
   });
 });
 
+describe("graphpack manifest — persisted counts (A9/A10)", () => {
+  it("records tripleCount and a distinct-abox entityCount", async () => {
+    const { dir } = await build([{ path: "a.ttl", content: TTL }]);
+    const manifest = JSON.parse(
+      readFileSync(join(dir, MANIFEST_FILE), "utf-8"),
+    ) as { tripleCount?: number; entityCount?: number };
+    expect(typeof manifest.tripleCount).toBe("number");
+    expect(manifest.tripleCount ?? 0).toBeGreaterThan(0);
+    // TTL declares two individuals (ex:Button, ex:Card) → two abox subjects.
+    expect(manifest.entityCount).toBe(2);
+  });
+});
+
+describe("graphpack read — truncated data cache (A9)", () => {
+  it("a truncated-but-non-empty data.nq surfaces STORE_UNAVAILABLE", async () => {
+    // A UNIQUE graph so corrupting its cache never poisons the shared TTL pack.
+    const uniqueTtl = `${TTL}\nex:Truncated a ex:Component ; rdfs:label "Truncated" .\n`;
+    const { dir } = await build([{ path: "trunc.ttl", content: uniqueTtl }]);
+    const dataPath = join(dir, DATA_FILE);
+    const lines = readFileSync(dataPath, "utf-8")
+      .split("\n")
+      .filter((line) => line.trim() !== "");
+    expect(lines.length).toBeGreaterThan(1);
+    // Drop the last statement: the dump is now a PARTIAL graph — still
+    // non-empty (so it passes the size>0 completeness gate) but fewer triples
+    // than the manifest recorded, which the boot cross-check must catch.
+    writeFileSync(dataPath, `${lines.slice(0, -1).join("\n")}\n`);
+
+    let caught: unknown;
+    try {
+      const session = await readPack(dir);
+      session.store.dispose();
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+  });
+
+  it("tolerates a benign superset (actual > recorded), not corruption", async () => {
+    // A future ke counting change could load MORE triples than the manifest
+    // recorded. That is not truncation, so boot must NOT reject it — otherwise
+    // one counting change trips a fleet-wide false STORE_UNAVAILABLE. Simulate by
+    // lowering the manifest's tripleCount below the dump's actual count.
+    const uniqueTtl = `${TTL}\nex:Superset a ex:Component ; rdfs:label "Superset" .\n`;
+    const { dir } = await build([{ path: "superset.ttl", content: uniqueTtl }]);
+    const manifestPath = join(dir, MANIFEST_FILE);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as {
+      tripleCount: number;
+    };
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({ ...manifest, tripleCount: manifest.tripleCount - 1 }),
+    );
+
+    // The booted store holds one MORE triple than the (lowered) manifest — a
+    // superset. On the pre-fix exact-equality guard this threw; now it boots.
+    const session = await readPack(dir);
+    expect(session.index.entities.length).toBeGreaterThan(0);
+    session.store.dispose();
+  });
+});
+
 describe("graphpack read — incomplete pack recovery (CLI + MCP)", () => {
   it("an incomplete pack is STORE_UNAVAILABLE with a `sources_update` tool recovery", async () => {
     // A dir with no manifest is an incomplete pack — readPack rejects before any

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

@@ -73,13 +73,28 @@ export async function readPack(dir: string): Promise<StoreSession> {
     JSON.parse(readFileSync(join(dir, INDEX_FILE), "utf-8")),
   );
 
-  // Guard against a corrupt/unparseable `data.nq` beside an intact manifest:
-  // ke silently falls back to an EMPTY store (and rewrites an empty dump).
-  // If the index says the pack is populated but the store booted with no
-  // triples, the cache is ruined — surface STORE_UNAVAILABLE (and, via the
-  // now-empty dump, `packIsComplete` turns false so recovery rebuilds) rather
-  // than serve an empty graph as if it were the pack.
-  if (index.entities.length > 0 && !(await storeHasTriples(store))) {
+  // Guard against a corrupt or TRUNCATED `data.nq` beside an intact manifest:
+  // ke silently serves whatever loaded (falling back to an EMPTY store on a
+  // parse failure, and rewriting an empty dump). When the manifest records the
+  // build-time triple count (A9), require the booted store to hold AT LEAST it:
+  // a SHORTFALL means the dump was truncated (fewer triples than were built) —
+  // it passes the mere size>0 completeness gate yet would serve a partial graph
+  // silently, so it must surface STORE_UNAVAILABLE here. A benign SUPERSET (more
+  // triples than recorded — e.g. a future ke counting change) is TOLERATED
+  // rather than treated as corruption, so such a change can't trip a fleet-wide
+  // false STORE_UNAVAILABLE. Older packs without the count fall back to the
+  // "populated index but empty store" check (via the now-empty dump,
+  // `packIsComplete` turns false so recovery rebuilds) rather than serving an
+  // empty graph as the pack.
+  const actualTriples = await countTriples(store);
+  if (manifest.tripleCount !== undefined) {
+    if (actualTriples < manifest.tripleCount) {
+      store.dispose();
+      throw packUnavailable(
+        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualTriples}).`,
+      );
+    }
+  } else if (index.entities.length > 0 && actualTriples === 0) {
     store.dispose();
     throw packUnavailable(`The pack at ${dir} has a corrupt data cache.`);
   }
@@ -93,10 +108,10 @@ export async function readPack(dir: string): Promise<StoreSession> {
   };
 }
 
-/** Whether the booted store holds at least one triple (a cheap ASK probe). */
-async function storeHasTriples(store: StoreSession["store"]): Promise<boolean> {
-  const result = (await store.query("ASK { ?s ?p ?o }" as never)) as {
-    result: boolean;
-  };
-  return result.result === true;
+/** Count the booted store's triples (a cheap aggregate over the union graph). */
+async function countTriples(store: StoreSession["store"]): Promise<number> {
+  const result = (await store.query(
+    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+  )) as import("@canonical/ke").SelectResult;
+  return Number(result.bindings.at(0)?.n ?? 0);
 }

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

@@ -105,6 +105,20 @@ export const manifestSchema = z.object({
   contentHash: z.string(),
   prefixes: z.record(z.string(), z.string()),
   createdAt: z.string(),
+  /**
+   * The store's triple count at build time. Cross-checked against the booted
+   * store so a truncated-but-non-empty `data.nq` (a partial graph that passes
+   * the mere size>0 completeness gate) surfaces as STORE_UNAVAILABLE rather
+   * than being served silently (A9). Optional — packs built before this field
+   * skip the check.
+   */
+  tripleCount: z.number().optional(),
+  /**
+   * The distinct abox entity count (matches {@link entityTotal}). Lets
+   * `sources status` report the figure without parsing the whole `index.json`
+   * (A10). Optional — packs built before this field fall back to the index read.
+   */
+  entityCount: z.number().optional(),
 });
 
 /** Pack provenance and the prefixes the store was built with. */

package/src/kernel/runtime/loadSession.ts

@@ -9,13 +9,11 @@
  * than silently reaching out.
  */
 
-import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
 import { materializeEmbeddedPack } from "./graphpack/embedded.js";
 import { readPack } from "./graphpack/read.js";
 import { resolveSources } from "./resolveSources.js";
+import { storeUnavailable } from "./storeReadiness.js";
 import type { StoreSession } from "./types.js";
 
 /** What {@link loadStoreSession} needs from the runtime. */
@@ -39,15 +37,9 @@ export async function loadStoreSession(
   const decision = resolveSources(layers, ctx.cwd);
 
   if (decision.kind === "unavailable") {
-    throw PragmaError.storeUnavailable(`${decision.reason}.`, {
-      recovery: cliRecovery(
-        `${RECOVERY_CLI_PREFIX}sources update`,
-        "Build the local store from the configured packages.",
-        // An agent recovers by calling the tool (then retrying — PR9's C1 cold-
-        // store retry makes a post-update retry succeed).
-        { tool: "sources_update" },
-      ),
-    });
+    // The SAME cold-store diagnostic the native MCP surfaces raise (shared via
+    // storeReadiness), so a cold store reads identically on every surface.
+    throw storeUnavailable(decision.reason);
   }
 
   const dir =

package/src/kernel/runtime/refs/resolve.ts

@@ -9,7 +9,7 @@
  * machine-independent. Reached only from the `sources update` Task body.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, relative } from "node:path";
 import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
@@ -84,9 +84,28 @@ function walkTtl(
     // build (a `.`-prefixed Turtle local name isn't even valid).
     if (entry.name.startsWith(".")) continue;
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
+    // Resolve symlinks: pnpm / workspace trees link their sources, but
+    // `Dirent.isFile`/`isDirectory` are BOTH false for a symlink — so a
+    // symlinked `.ttl` was silently skipped (L6). Follow the link to recover a
+    // symlinked FILE, but NEVER recurse into a symlinked DIRECTORY: a symlink
+    // cycle (a link to an ancestor dir) would recurse without bound — a
+    // stack-overflow RangeError surfacing as an INTERNAL "please report" — and a
+    // linked directory could pull `.ttl` from OUTSIDE the package root. Linking
+    // individual source files (all L6 needs) stays supported; a dangling link is
+    // skipped, not fatal.
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        isFile = statSync(full).isFile();
+        isDir = false;
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
       walkTtl(full, base, label, out);
-    } else if (entry.isFile() && entry.name.endsWith(".ttl")) {
+    } else if (isFile && entry.name.endsWith(".ttl")) {
       out.push({
         path: `${label}/${relative(base, full)}`,
         content: readFileSync(full, "utf-8"),
@@ -143,6 +162,47 @@ export function harvestPrefixes(
   return prefixes;
 }
 
+/** One `@prefix` clash: a label declared with two or more distinct IRIs. */
+export interface PrefixClash {
+  readonly label: string;
+  /** The distinct IRIs bound to the label, in first-seen order. */
+  readonly iris: readonly string[];
+}
+
+/**
+ * Detect `@prefix` label clashes across a set of sources.
+ *
+ * {@link harvestPrefixes} resolves clashes last-wins (Turtle's own rule),
+ * silently compacting the losing package's URIs to the wrong prefix (or to full
+ * IRIs). This surfaces the clashes so `sources update` can warn (A5): a label
+ * bound to two or more distinct IRIs. Harmless same-label/same-IRI
+ * redeclarations (the common case) are NOT clashes. Result is sorted by label
+ * so the warnings are deterministic.
+ *
+ * @param sources - The packages' labelled RDF sources.
+ * @returns One entry per clashing label, each with its distinct IRIs.
+ */
+export function detectPrefixClashes(
+  sources: readonly { readonly content: string }[],
+): PrefixClash[] {
+  const byLabel = new Map<string, string[]>();
+  for (const { content } of sources) {
+    for (const match of content.matchAll(PREFIX_DECL)) {
+      const [, label, iri] = match;
+      if (label === undefined || iri === undefined) continue;
+      const iris = byLabel.get(label) ?? [];
+      if (!iris.includes(iri)) iris.push(iri);
+      byLabel.set(label, iris);
+    }
+  }
+  const clashes: PrefixClash[] = [];
+  for (const [label, iris] of byLabel) {
+    if (iris.length > 1) clashes.push({ label, iris });
+  }
+  clashes.sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+  return clashes;
+}
+
 /**
  * Locate a package's `package.json` from the project.
  *

package/src/kernel/runtime/storeReadiness.ts

@@ -0,0 +1,61 @@
+/**
+ * The STORELESS store-readiness check — the ONE source of the cold-store
+ * `STORE_UNAVAILABLE` error (its message AND its `pragma sources update` /
+ * `sources_update` recovery), shared by the lazy store boot ({@link
+ * loadStoreSession}) and the native MCP discovery surfaces (the `prompts/*`
+ * provider, the `pragma:{+uri}` resource browser).
+ *
+ * A cold store must present the SAME diagnostic on every surface: an agent that
+ * lists prompts over the `prompt_list` tool (store-backed, so its `needsStore`
+ * pre-check throws) and one that lists them over native `prompts/list` must see
+ * the identical `STORE_UNAVAILABLE` + `sources_update` recovery, not one error
+ * and one silently-empty list. Centralizing the construction here is what keeps
+ * those surfaces from drifting apart.
+ *
+ * It reaches only {@link resolveSources} (a lock + config probe — no store, no
+ * ke), so a caller on the storeless fast path can pre-check availability without
+ * ever booting the store.
+ */
+
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+import type { ConfigLayers } from "../config/types.js";
+import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
+import { resolveSources } from "./resolveSources.js";
+
+/**
+ * Build the canonical cold-store `STORE_UNAVAILABLE` error: the reason plus the
+ * single `pragma sources update` recovery that also names the `sources_update`
+ * tool an agent calls (then retries — PR9's C1 cold-store retry succeeds).
+ *
+ * @param reason - The boot decision's reason (e.g. "the locked pack is missing").
+ * @returns The structured STORE_UNAVAILABLE error.
+ */
+export function storeUnavailable(reason: string): PragmaError {
+  return PragmaError.storeUnavailable(`${reason}.`, {
+    recovery: cliRecovery(
+      `${RECOVERY_CLI_PREFIX}sources update`,
+      "Build the local store from the configured packages.",
+      { tool: "sources_update" },
+    ),
+  });
+}
+
+/**
+ * The STORE_UNAVAILABLE error to surface when the store cannot boot from the
+ * current config/lock, or `undefined` when a store read may proceed. STORELESS —
+ * probes the decision table only, never constructs the store.
+ *
+ * @param layers - The resolved config layers.
+ * @param cwd - The project directory the boot resolves against.
+ * @returns The error to surface cold, or `undefined` when the store is available.
+ */
+export function checkStoreAvailable(
+  layers: ConfigLayers,
+  cwd: string,
+): PragmaError | undefined {
+  const decision = resolveSources(layers, cwd);
+  return decision.kind === "unavailable"
+    ? storeUnavailable(decision.reason)
+    : undefined;
+}

package/src/kernel/runtime/types.ts

@@ -17,7 +17,7 @@ import type { ConfigLayers } from "../config/types.js";
  * separately so inferred mode can shape output without switching behaviour.
  */
 export interface GlobalFlags {
-  /** Condensed Markdown output for LLM/agent consumption. */
+  /** Condensed Markdown output, from `--format llm` or auto-detection. */
   readonly llm: boolean;
   /** True when `llm` was inferred from a non-interactive stdout, not requested. */
   readonly autoLlm?: boolean;