@canonical/pragma-cli 0.31.0 → 0.32.0

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,153 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } 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 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 });
+    }
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * The two content hashes a pack carries — kept in distinct roles, never
+ * conflated.
+ *
+ * 1. {@link contentHash} — a SHA-256 (ke-graphql's `sha256Hex`) over the
+ *    canonicalized *source inputs* (sorted by path, path + content joined with
+ *    fixed delimiters). It names the pack's cache directory and is pinned in the
+ *    lock, so the same sources always resolve to the same directory and a
+ *    changed source is a new directory (free invalidation). Hashing the sorted
+ *    TTL *inputs* — never the `data.nq` dump, whose n-quads line order is not
+ *    canonical — keeps it deterministic.
+ * 2. `hashSources` (re-exported from ke-graphql) — an order-independent FNV-1a
+ *    64 fingerprint stored *inside* `schema.json` as the extraction's freshness
+ *    token. ke-graphql compares it against the loaded sources to detect a stale
+ *    artifact. It is a staleness signal, not a cache key.
+ */
+
+import { hashSources, sha256Hex } from "@canonical/ke-graphql";
+
+/** A single source input: a stable path label and its raw text content. */
+export interface HashInput {
+  readonly path: string;
+  readonly content: string;
+}
+
+/** Delimiter between a source's path and its content. */
+const FIELD_SEP = "\n<<<pragma-pack:content>>>\n";
+/** Delimiter between successive sources. */
+const RECORD_SEP = "\n<<<pragma-pack:next>>>\n";
+
+/**
+ * The pack's content hash: SHA-256 over the canonicalized source inputs.
+ *
+ * @param inputs - The source inputs (path + content).
+ * @returns The lowercase hex SHA-256 — the pack's cache-directory name.
+ * @note Async — SHA-256 via Web Crypto.
+ */
+export function contentHash(inputs: readonly HashInput[]): Promise<string> {
+  const canonical = [...inputs]
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .map((input) => `${input.path}${FIELD_SEP}${input.content}`)
+    .join(RECORD_SEP);
+  return sha256Hex(canonical);
+}
+
+export { hashSources };

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

@@ -0,0 +1,21 @@
+/**
+ * Graphpack barrel — the content-addressed pack cache: build, read, embedded
+ * fallback, and the artifact contracts.
+ */
+
+export type {
+  BuildPackInput,
+  BuildPackOptions,
+  BuildPackResult,
+} from "./build.js";
+export { buildPack } from "./build.js";
+export { buildIndex } from "./buildIndex.js";
+export { embeddedContentHash, materializeEmbeddedPack } from "./embedded.js";
+export { contentHash, type HashInput, hashSources } from "./hash.js";
+export { packIsComplete, readManifest } from "./manifest.js";
+export { readPack } from "./read.js";
+export type {
+  Manifest,
+  PackIndex,
+  PackIndexEntity,
+} from "./types.js";

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

@@ -0,0 +1,55 @@
+/**
+ * Read a pack's `manifest.json`. Its presence is the completeness marker: a
+ * directory without a valid manifest is a torn build (writes land in a temp
+ * directory and the manifest is renamed in last), so an absent or invalid
+ * manifest means "treat the pack as not there".
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+  DATA_FILE,
+  INDEX_FILE,
+  MANIFEST_FILE,
+  type Manifest,
+  manifestSchema,
+  SCHEMA_FILE,
+} from "./types.js";
+
+/**
+ * Read and validate a pack directory's manifest.
+ *
+ * @param dir - The pack directory.
+ * @returns The parsed manifest, or `undefined` when absent or invalid.
+ * @note Impure — reads from disk.
+ */
+export function readManifest(dir: string): Manifest | undefined {
+  const path = join(dir, MANIFEST_FILE);
+  if (!existsSync(path)) return undefined;
+  try {
+    return manifestSchema.parse(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether a pack directory holds a complete pack: a valid manifest AND every
+ * non-empty query artifact — the `data.nq` dump, the extracted `schema.json`,
+ * and the entity `index.json`. The manifest alone is not enough: an intact
+ * manifest beside a missing/truncated `data.nq` boots EMPTY (a silent, then
+ * permanent, loss), and a torn or evicted `schema.json`/`index.json` (manifest +
+ * dump intact) would be REUSED by `buildPack` and then fail at BOOT as an
+ * internal error. Requiring all three present + non-empty makes `buildPack`
+ * rebuild a torn pack and makes the boot decision surface STORE_UNAVAILABLE
+ * (the ordinary "not built" recovery) instead of a "please report this" crash. */
+export function packIsComplete(dir: string): boolean {
+  if (readManifest(dir) === undefined) return false;
+  for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE]) {
+    try {
+      if (statSync(join(dir, file)).size <= 0) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Boot a {@link StoreSession} from a built pack directory — the perf keystone.
+ *
+ * The store loads from `data.nq` through ke's cache path (no TTL parse), and
+ * the executable GraphQL schema is rebuilt from `schema.json` via ke-graphql's
+ * `compileFromExtraction` — passes 2-7, pure JS, no store, no SPARQL. The live
+ * 7-pass `compile` is NEVER called here; that only runs at build time. The
+ * entity index is a plain `JSON.parse`. The result is an immutable session the
+ * lazy store memoizes for the process's lifetime.
+ *
+ * Reached only behind a dynamic import (store boot), never on the storeless
+ * fast path.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createStore } from "@canonical/ke";
+import { compileFromExtraction } from "@canonical/ke-graphql";
+import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import { cliRecovery } from "../../error/recovery.js";
+import type { StoreSession } from "../types.js";
+import { readManifest } from "./manifest.js";
+import {
+  DATA_FILE,
+  INDEX_FILE,
+  packIndexSchema,
+  SCHEMA_FILE,
+} from "./types.js";
+
+/** STORE_UNAVAILABLE with the canonical `pragma sources update` recovery (CLI + MCP). */
+function packUnavailable(reason: string): PragmaError {
+  return PragmaError.storeUnavailable(reason, {
+    recovery: cliRecovery(
+      `${RECOVERY_CLI_PREFIX}sources update`,
+      "Rebuild the local store from the configured packages.",
+      // An agent recovers by calling the tool, then retrying (PR9 C1 cold-store
+      // retry makes the post-update retry succeed).
+      { tool: "sources_update" },
+    ),
+  });
+}
+
+/**
+ * Read a pack directory into a bootable store session.
+ *
+ * @param dir - The pack directory (must hold a complete pack).
+ * @returns The store session: store, schema, context factory, prefixes, index.
+ * @throws PragmaError STORE_UNAVAILABLE when the pack is incomplete.
+ * @note Impure — creates a store from the cached n-quads dump.
+ */
+export async function readPack(dir: string): Promise<StoreSession> {
+  const manifest = readManifest(dir);
+  if (!manifest) {
+    throw packUnavailable(`The pack at ${dir} is incomplete.`);
+  }
+
+  const store = await createStore({
+    // Cache hit loads the n-quads dump directly — no sources are re-parsed.
+    sources: [],
+    prefixes: manifest.prefixes,
+    cache: join(dir, DATA_FILE),
+  });
+
+  // `loaderCache: "process"` shares the DataLoader caches across every context
+  // for this immutable store's lifetime (the MCP p95 win) — sound because the
+  // store never mutates between reloads. PR7 relies on it.
+  const compiled = compileFromExtraction(
+    readFileSync(join(dir, SCHEMA_FILE), "utf-8"),
+    { loaderCache: "process" },
+  );
+  const index = packIndexSchema.parse(
+    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))) {
+    store.dispose();
+    throw packUnavailable(`The pack at ${dir} has a corrupt data cache.`);
+  }
+
+  return {
+    store,
+    schema: compiled.schema,
+    createContext: compiled.createContext,
+    prefixes: manifest.prefixes,
+    index,
+  };
+}
+
+/** 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;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Graphpack artifact contracts — the four files a built pack directory holds
+ * and the zod schemas that keep them honest on read.
+ *
+ * A pack is the content-addressed, boot-ready form of a set of RDF sources:
+ * `data.nq` (the store's n-quads dump — boots via ke's cache path, no TTL
+ * parse), `schema.json` (the serialized ke-graphql extraction — boots via
+ * `compileFromExtraction`, no live 7-pass compile), `index.json` (the storeless
+ * entity index the completion tier and reads consume), and `manifest.json`
+ * (provenance + the prefixes the store was built with). A directory missing
+ * `manifest.json` is treated as absent (a torn build), so writes are always
+ * temp-dir + atomic rename.
+ *
+ * This module is reached only behind a dynamic import (pack build / read /
+ * store boot), so its zod dependency never lands on the storeless fast path.
+ */
+
+import { z } from "zod";
+
+/** The n-quads store dump — ke boots it via `createStore({ cache })`. */
+export const DATA_FILE = "data.nq";
+/** The serialized ke-graphql extraction — boots via `compileFromExtraction`. */
+export const SCHEMA_FILE = "schema.json";
+/** The storeless entity index (PR-C's dynamic-completion contract). */
+export const INDEX_FILE = "index.json";
+/** Provenance + prefixes; its presence marks a pack directory as complete. */
+export const MANIFEST_FILE = "manifest.json";
+
+/**
+ * One indexed entity. The `{ name, type }` pair is the FROZEN minimum the
+ * dynamic-completion tier (and PR-C's read verbs) rely on; every other field is
+ * enrichment a later PR may add without breaking the contract.
+ */
+export interface PackIndexEntity {
+  /** Completion token — the prefixed name a user types (e.g. `ds:Button`). */
+  readonly name: string;
+  /** Prefixed primary `rdf:type` — the completion filter key (e.g. `ds:UIBlock`). */
+  readonly type: string;
+  /** Full subject URI. */
+  readonly uri?: string;
+  /** Prefixed subject (same value as `name`, kept explicit for readers). */
+  readonly prefixed?: string;
+  /** All prefixed `rdf:type` values asserted on the subject. */
+  readonly types?: readonly string[];
+  /** Human label (rdfs:label / skos:prefLabel / dcterms:title / schema:name). */
+  readonly label?: string | null;
+  /**
+   * Alternative completable names — the `ds:name` values a family (e.g.
+   * `ds:Tier`, matched by `tier lookup`) is addressed by, when they differ from
+   * `name`/`label`. Enrichment for the storeless name-completion sources.
+   */
+  readonly altNames?: readonly string[];
+  /** Schema (`tbox`) vs individual (`abox`). */
+  readonly box?: "tbox" | "abox";
+  /** Short description (rdfs:comment / dcterms:description / skos:definition). */
+  readonly description?: string | null;
+}
+
+/**
+ * The storeless entity index a pack ships as `index.json`.
+ *
+ * `version` is `2` for packs built by this kernel (the v2 enrichment fields on
+ * each entity + the resource browser depend on it); `1` is a legacy artifact
+ * whose enrichment is absent — the resources provider degrades to a "run
+ * `pragma sources update`" hint rather than a live re-index.
+ */
+export interface PackIndex {
+  readonly version: 1 | 2;
+  /** The pack's content hash (matches its cache directory name). */
+  readonly contentHash: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+  readonly entities: readonly PackIndexEntity[];
+  /** Full-type-URI → count of asserted instances. */
+  readonly instanceCountByType: Readonly<Record<string, number>>;
+}
+
+/** zod schema validating a persisted {@link PackIndexEntity}. */
+export const packIndexEntitySchema: z.ZodType<PackIndexEntity> = z.object({
+  name: z.string(),
+  type: z.string(),
+  uri: z.string().optional(),
+  prefixed: z.string().optional(),
+  types: z.array(z.string()).optional(),
+  label: z.string().nullable().optional(),
+  altNames: z.array(z.string()).optional(),
+  box: z.enum(["tbox", "abox"]).optional(),
+  description: z.string().nullable().optional(),
+});
+
+/** zod schema validating a persisted {@link PackIndex}. */
+export const packIndexSchema: z.ZodType<PackIndex> = z.object({
+  version: z.union([z.literal(1), z.literal(2)]),
+  contentHash: z.string(),
+  prefixes: z.record(z.string(), z.string()),
+  entities: z.array(packIndexEntitySchema),
+  instanceCountByType: z.record(z.string(), z.number()),
+});
+
+/** zod schema validating a persisted `manifest.json`. */
+export const manifestSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  /** The config `packages` ref this pack was built from (verbatim), or a label. */
+  sourceRef: z.string(),
+  contentHash: z.string(),
+  prefixes: z.record(z.string(), z.string()),
+  createdAt: z.string(),
+});
+
+/** Pack provenance and the prefixes the store was built with. */
+export type Manifest = z.infer<typeof manifestSchema>;

package/src/kernel/runtime/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Runtime kernel barrel — the per-invocation context, its builder, and the
+ * lazy store / query facade the store-backed capabilities reach through.
+ */
+
+export { bootRuntime } from "./boot.js";
+export { createQueryFacade } from "./facade.js";
+export { createLazyStore, type LazyStoreContext } from "./store.js";
+export type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+  QueryFacade,
+  StoreSession,
+} from "./types.js";

package/src/kernel/runtime/loadSession.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolve the boot decision into a live {@link StoreSession} — the heavy,
+ * dynamic-import-only module that pulls ke/ke-graphql/oxigraph.
+ *
+ * The lazy store reaches this behind `await import(...)`, so nothing on the
+ * storeless fast path (or in the `capabilities/index` static graph) loads the
+ * runtime. Boot is cache-only and networkless: a cold store surfaces
+ * STORE_UNAVAILABLE with the single `pragma sources update` recovery, rather
+ * 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 type { StoreSession } from "./types.js";
+
+/** What {@link loadStoreSession} needs from the runtime. */
+export interface LoadSessionContext {
+  readonly cwd: string;
+  readonly loadConfig: () => Promise<ConfigLayers>;
+}
+
+/**
+ * Boot the store session per the decision table.
+ *
+ * @param ctx - The working directory and memoized config loader.
+ * @returns The booted store session.
+ * @throws PragmaError STORE_UNAVAILABLE when the store is cold.
+ * @note Impure — reads config, materializes/loads a pack, boots oxigraph.
+ */
+export async function loadStoreSession(
+  ctx: LoadSessionContext,
+): Promise<StoreSession> {
+  const layers = await ctx.loadConfig();
+  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" },
+      ),
+    });
+  }
+
+  const dir =
+    decision.kind === "embedded" ? materializeEmbeddedPack() : decision.dir;
+  return readPack(dir);
+}