@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,317 @@
+/**
+ * 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
+ * (`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";
+import type { PackIndex, PackIndexEntity } from "./types.js";
+
+type Store = import("@canonical/ke").Store;
+
+/** `rdf:type`. */
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+/** Meta-types that mark a subject as TBox schema (a class). */
+const CLASS_METATYPES = new Set([
+  "http://www.w3.org/2002/07/owl#Class",
+  "http://www.w3.org/2000/01/rdf-schema#Class",
+]);
+
+/** Meta-types that mark a subject as TBox schema (a property). */
+const PROPERTY_METATYPES = new Set([
+  "http://www.w3.org/2002/07/owl#ObjectProperty",
+  "http://www.w3.org/2002/07/owl#DatatypeProperty",
+  "http://www.w3.org/2002/07/owl#AnnotationProperty",
+  "http://www.w3.org/1999/02/22-rdf-syntax-ns#Property",
+]);
+
+/** `owl:NamedIndividual` — a typing artifact, never a subject's domain class. */
+const NAMED_INDIVIDUAL = "http://www.w3.org/2002/07/owl#NamedIndividual";
+
+/** Namespaces whose types are structural, not a subject's domain class. */
+const STD_VOCAB_PREFIXES = [
+  "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+  "http://www.w3.org/2000/01/rdf-schema#",
+  "http://www.w3.org/2002/07/owl#",
+  "http://www.w3.org/2001/XMLSchema#",
+  "http://www.w3.org/2004/02/skos/core#",
+  "http://www.w3.org/ns/shacl#",
+];
+
+/** Label predicates, in preference order. */
+const LABEL_PREDICATES = [
+  "http://www.w3.org/2000/01/rdf-schema#label",
+  "http://www.w3.org/2004/02/skos/core#prefLabel",
+  "http://purl.org/dc/terms/title",
+  "http://schema.org/name",
+];
+
+/** Description predicates, in preference order. */
+const DESCRIPTION_PREDICATES = [
+  "http://www.w3.org/2000/01/rdf-schema#comment",
+  "http://purl.org/dc/terms/description",
+  "http://www.w3.org/2004/02/skos/core#definition",
+  "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));
+
+/** 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));
+  const propMeta = fullTypes.find((t) => PROPERTY_METATYPES.has(t));
+  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; langRank: number }
+  >();
+  for (const term of result.termBindings) {
+    if (term.s?.termType !== "NamedNode") continue;
+    const valueTerm = term[valueVar];
+    const predicate = term.p?.value;
+    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);
+    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);
+  return picked;
+}
+
+/**
+ * Collect ALL matching object values per subject (deduped, insertion order) —
+ * for multi-valued enrichment like `altNames`, where every value is a
+ * completable token rather than a single preferred one.
+ */
+function allBySubject(
+  result: import("@canonical/ke").SelectResult,
+  valueVar: string,
+): Map<string, string[]> {
+  const collected = new Map<string, string[]>();
+  for (const term of result.termBindings) {
+    if (term.s?.termType !== "NamedNode") continue;
+    const value = term[valueVar]?.value;
+    if (!value) continue;
+    const bucket = collected.get(term.s.value) ?? [];
+    if (!bucket.includes(value)) bucket.push(value);
+    collected.set(term.s.value, bucket);
+  }
+  return collected;
+}
+
+/**
+ * Build the entity index from a populated store.
+ *
+ * @param store - The ke store to query.
+ * @param prefixes - The store's merged prefix map.
+ * @param contentHash - The pack's content hash, embedded in the index.
+ * @returns The storeless {@link PackIndex}.
+ * @note Impure — runs bulk SPARQL queries against the store.
+ */
+export async function buildIndex(
+  store: Store,
+  prefixes: Readonly<Record<string, string>>,
+  contentHash: string,
+): Promise<PackIndex> {
+  const [typesResult, labelResult, descResult, altNameResult] =
+    await Promise.all([
+      store.query(
+        `SELECT ?s ?type WHERE { ?s <${RDF_TYPE}> ?type }` as never,
+      ) as Promise<import("@canonical/ke").SelectResult>,
+      store.query(
+        `SELECT ?s ?p ?label WHERE { ?s ?p ?label . VALUES ?p { ${valuesList(LABEL_PREDICATES)} } }` as never,
+      ) as Promise<import("@canonical/ke").SelectResult>,
+      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>,
+    ]);
+
+  const typesBySubject = new Map<string, string[]>();
+  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 = typeTerm.value;
+    const bucket = typesBySubject.get(subject) ?? [];
+    bucket.push(typeUri);
+    typesBySubject.set(subject, bucket);
+    instanceCountByType[typeUri] = (instanceCountByType[typeUri] ?? 0) + 1;
+  }
+
+  const labelBySubject = preferredBySubject(
+    labelResult,
+    "label",
+    LABEL_PREDICATES,
+  );
+  const descBySubject = preferredBySubject(
+    descResult,
+    "desc",
+    DESCRIPTION_PREDICATES,
+  );
+  const altNamesBySubject = allBySubject(altNameResult, "alt");
+
+  const entities: PackIndexEntity[] = [];
+  for (const [subject, fullTypes] of typesBySubject) {
+    const facets = classify(fullTypes);
+    if (facets.length === 0) continue;
+    const prefixed = compactUri(subject, prefixes);
+    const altNames = altNamesBySubject.get(subject);
+    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,
+      });
+    }
+  }
+  // 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,
+    contentHash,
+    prefixes,
+    entities,
+    instanceCountByType,
+  };
+}

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

@@ -0,0 +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\":\"1970-01-01T00:00:00.000Z\",\"tripleCount\":23,\"entityCount\":3}";

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

@@ -0,0 +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}}";

package/src/kernel/runtime/graphpack/embedded/sample.ttl

@@ -0,0 +1,39 @@
+# Embedded fallback pack source — a small, self-contained sample ontology.
+#
+# Compiled by `scripts/genEmbedded.ts` into `pack.generated.ts`. It exists so a
+# fresh install (no configured packages, no lock) can answer store-backed reads
+# without a network round-trip. Keep it tiny: it ships inside the binary.
+
+@prefix ex:   <https://pragma.canonical.com/sample#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+
+ex:Component a owl:Class ;
+  rdfs:label "Component" ;
+  rdfs:comment "A reusable design-system building block." .
+
+ex:componentName a owl:DatatypeProperty ;
+  rdfs:label "component name" ;
+  rdfs:domain ex:Component ;
+  rdfs:range xsd:string .
+
+ex:dependsOn a owl:ObjectProperty ;
+  rdfs:label "depends on" ;
+  rdfs:domain ex:Component ;
+  rdfs:range ex:Component .
+
+ex:Button a ex:Component ;
+  rdfs:label "Button" ;
+  ex:componentName "Button" .
+
+ex:Card a ex:Component ;
+  rdfs:label "Card" ;
+  ex:componentName "Card" ;
+  ex:dependsOn ex:Button .
+
+ex:Dialog a ex:Component ;
+  rdfs:label "Dialog" ;
+  ex:componentName "Dialog" ;
+  ex:dependsOn ex:Button , ex:Card .

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

@@ -0,0 +1,70 @@
+/**
+ * The embedded fallback pack: a small, self-contained pack compiled into the
+ * binary as inlined strings (`pack.generated.ts`, produced by
+ * `scripts/genEmbedded.ts`). It is the store the CLI boots when no packages are
+ * configured beyond the defaults and no lock has been written yet — so a fresh
+ * install answers store-backed reads without a network round-trip.
+ *
+ * The inlined strings are materialized into the ordinary content-addressed pack
+ * cache on first use and then read back through {@link readPack}, so the
+ * embedded pack and a built pack share one boot path. Inlining as JS strings
+ * (rather than file assets) guarantees the content survives `bun build
+ * --compile` with no asset-embedding step.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { packDir, packsCacheDir } from "../paths.js";
+import { dataNq, manifestJson, schemaJson } from "./embedded/pack.generated.js";
+import { indexJson } from "./embedded/pack.index.generated.js";
+import { packIsComplete } from "./manifest.js";
+import {
+  DATA_FILE,
+  INDEX_FILE,
+  MANIFEST_FILE,
+  manifestSchema,
+  SCHEMA_FILE,
+} from "./types.js";
+
+/** The embedded pack's content hash (its cache-directory name). */
+export function embeddedContentHash(): string {
+  return manifestSchema.parse(JSON.parse(manifestJson)).contentHash;
+}
+
+/**
+ * Materialize the embedded pack into the pack cache and return its directory.
+ *
+ * Idempotent: if the content-addressed directory already holds a complete pack
+ * (this or a previous run, or a build with identical sources), it is reused.
+ *
+ * @returns The pack directory, ready for {@link readPack}.
+ * @note Impure — writes the inlined pack files into the cache.
+ */
+export function materializeEmbeddedPack(): string {
+  const dir = packDir(embeddedContentHash());
+  if (packIsComplete(dir)) return dir;
+
+  mkdirSync(packsCacheDir(), { recursive: true });
+  const temp = mkdtempSync(join(packsCacheDir(), ".embed-"));
+  try {
+    writeFileSync(join(temp, DATA_FILE), dataNq);
+    writeFileSync(join(temp, SCHEMA_FILE), schemaJson);
+    writeFileSync(join(temp, INDEX_FILE), indexJson);
+    // Written last — the completeness marker.
+    writeFileSync(join(temp, MANIFEST_FILE), manifestJson);
+    if (!packIsComplete(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+      renameSync(temp, dir);
+    }
+  } finally {
+    if (existsSync(temp)) rmSync(temp, { recursive: true, force: true });
+  }
+  return dir;
+}

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

@@ -0,0 +1,221 @@
+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";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { buildPack } from "./build.js";
+import { contentHash } from "./hash.js";
+import { readPack } from "./read.js";
+import { DATA_FILE, INDEX_FILE, MANIFEST_FILE, SCHEMA_FILE } from "./types.js";
+
+const PREFIXES = {
+  ex: "https://pragma.canonical.com/sample#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ex:   <https://pragma.canonical.com/sample#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+ex:Component a owl:Class ; rdfs:label "Component" .
+ex:componentName a owl:DatatypeProperty ; rdfs:domain ex:Component ; rdfs:range xsd:string .
+ex:Button a ex:Component ; rdfs:label "Button" ; ex:componentName "Button" .
+ex:Card a ex:Component ; rdfs:label "Card" ; ex:componentName "Card" .
+`;
+
+const build = (inputs: { path: string; content: string }[]) =>
+  buildPack(inputs, {
+    name: "test-pack",
+    version: "0.0.0",
+    sourceRef: "test:inline",
+    prefixes: PREFIXES,
+  });
+
+let savedCacheHome: string | undefined;
+let cacheHome: string;
+
+beforeAll(() => {
+  savedCacheHome = process.env.XDG_CACHE_HOME;
+  cacheHome = mkdtempSync(join(tmpdir(), "pragma-graphpack-"));
+  process.env.XDG_CACHE_HOME = cacheHome;
+});
+
+afterAll(() => {
+  process.env.XDG_CACHE_HOME = savedCacheHome;
+  rmSync(cacheHome, { recursive: true, force: true });
+});
+
+describe("graphpack round-trip (PROTECTED)", () => {
+  it("builds the four artifact files and reuses a cached pack", async () => {
+    const result = await build([{ path: "a.ttl", content: TTL }]);
+    expect(result.reused).toBe(false);
+    for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE, MANIFEST_FILE]) {
+      expect(existsSync(join(result.dir, file))).toBe(true);
+    }
+
+    // A second build over identical inputs is a pure cache hit — no rebuild.
+    const again = await build([{ path: "a.ttl", content: TTL }]);
+    expect(again.reused).toBe(true);
+    expect(again.contentHash).toBe(result.contentHash);
+  });
+
+  it("boots the pack: SPARQL data + an executable schema + the entity index", async () => {
+    const { dir } = await build([{ path: "a.ttl", content: TTL }]);
+    const session = await readPack(dir);
+    try {
+      const count = await session.store.query(
+        "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+      );
+      expect(count.type).toBe("select");
+      expect(
+        Number((count as { bindings: { n: string }[] }).bindings[0]?.n),
+      ).toBeGreaterThan(0);
+
+      // compileFromExtraction produced a working schema.
+      expect(session.schema.getType("Component")).toBeDefined();
+
+      // A GraphQL query resolves ABox data through the booted store.
+      const gql = await executeLocal({
+        schema: session.schema,
+        source: "{ __schema { queryType { name } } }",
+        contextValue: session.createContext(session.store),
+      });
+      expect((gql as { errors?: unknown[] }).errors).toBeUndefined();
+
+      // The index carries the FROZEN { name, type } minimum.
+      const names = session.index.entities.map((e) => e.name);
+      expect(names).toContain("ex:Button");
+      expect(names).toContain("ex:Component");
+      const button = session.index.entities.find((e) => e.name === "ex:Button");
+      expect(button?.type).toBe("ex:Component");
+      expect(button?.box).toBe("abox");
+      const component = session.index.entities.find(
+        (e) => e.name === "ex:Component",
+      );
+      expect(component?.type).toBe("owl:Class");
+      expect(component?.box).toBe("tbox");
+    } finally {
+      session.store.dispose();
+    }
+  });
+});
+
+describe("graphpack hash stability (PROTECTED)", () => {
+  it("is order-independent and content-sensitive", async () => {
+    const a = { path: "a.ttl", content: "ex:one a ex:X ." };
+    const b = { path: "b.ttl", content: "ex:two a ex:Y ." };
+    const forward = await contentHash([a, b]);
+    const reversed = await contentHash([b, a]);
+    expect(forward).toBe(reversed);
+
+    const changed = await contentHash([
+      { ...a, content: "ex:one a ex:Z ." },
+      b,
+    ]);
+    expect(changed).not.toBe(forward);
+  });
+
+  it("the built manifest's contentHash names its cache directory", async () => {
+    const result = await build([{ path: "a.ttl", content: TTL }]);
+    const manifest = JSON.parse(
+      readFileSync(join(result.dir, MANIFEST_FILE), "utf-8"),
+    );
+    expect(manifest.contentHash).toBe(result.contentHash);
+    expect(result.dir.endsWith(result.contentHash)).toBe(true);
+  });
+});
+
+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
+    // store boot. The recovery names both the CLI command and the MCP tool an
+    // agent calls, so a cold agent isn't left with a CLI-only hint it can't run.
+    const emptyDir = mkdtempSync(join(tmpdir(), "pragma-incomplete-pack-"));
+    try {
+      let caught: unknown;
+      try {
+        await readPack(emptyDir);
+      } catch (error) {
+        caught = error;
+      }
+      expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+      const recovery = (caught as { recovery?: Record<string, unknown> })
+        .recovery;
+      expect(recovery?.cli).toBe("pragma sources update");
+      expect(recovery?.mcp).toMatchObject({ tool: "sources_update" });
+    } finally {
+      rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+});