@canonical/pragma-cli 0.31.0 → 0.33.0

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,117 @@
+/**
+ * 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 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.`);
+  }
+
+  return {
+    store,
+    schema: compiled.schema,
+    createContext: compiled.createContext,
+    prefixes: manifest.prefixes,
+    index,
+  };
+}
+
+/** 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

@@ -0,0 +1,125 @@
+/**
+ * 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(),
+  /**
+   * 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. */
+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,48 @@
+/**
+ * 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 type { ConfigLayers } from "../config/types.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. */
+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") {
+    // 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 =
+    decision.kind === "embedded" ? materializeEmbeddedPack() : decision.dir;
+  return readPack(dir);
+}

package/src/kernel/runtime/lock.ts

@@ -0,0 +1,90 @@
+/**
+ * The project lock — `pragma.lock.json`, committed at the project root.
+ *
+ * It pins the single combined pack the store boots from: `contentHash` names
+ * the pack's cache directory, and `packs[]` records the resolved provenance of
+ * every configured source (so `sources status` reports it and a `--frozen`
+ * update re-resolves to exactly these commits). Serialization is canonical —
+ * fixed field order, packs sorted by name, one trailing newline — so a
+ * `--frozen` update that changes nothing rewrites a byte-identical file.
+ *
+ * Pure: zod + fs only, no store code, so both the storeless `sources status`
+ * verb and the store-boot decision table read it without booting oxigraph.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { lockPath } from "./paths.js";
+
+/** One resolved source's provenance in the lock. */
+export const lockPackageSchema = z.object({
+  /** Package name (config `packages` entry name / npm name). */
+  name: z.string(),
+  /** The config `packages` source ref, verbatim (e.g. `git+https://…#main`). */
+  source: z.string(),
+  /** The resolved commit / version / absolute path this ref pinned to. */
+  resolved: z.string(),
+  /** ISO timestamp the ref was resolved. */
+  resolvedAt: z.string(),
+});
+
+/** The lock document. */
+export const pragmaLockSchema = z.object({
+  version: z.literal(1),
+  /** The combined pack's content hash — names its cache directory. */
+  contentHash: z.string(),
+  packs: z.array(lockPackageSchema),
+});
+
+/** One resolved source's provenance in the lock. */
+export type PragmaLockPackage = z.infer<typeof lockPackageSchema>;
+/** The parsed lock document. */
+export type PragmaLock = z.infer<typeof pragmaLockSchema>;
+
+/**
+ * Read and validate the lock for a working directory.
+ *
+ * @param cwd - The project directory.
+ * @returns The parsed lock, or `undefined` when absent or invalid.
+ * @note Impure — reads from disk.
+ */
+export function readLock(cwd: string): PragmaLock | undefined {
+  const path = lockPath(cwd);
+  if (!existsSync(path)) return undefined;
+  try {
+    return pragmaLockSchema.parse(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Serialize a lock canonically — stable field order, sorted packs, newline. */
+export function serializeLock(lock: PragmaLock): string {
+  const packs = [...lock.packs]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .map((pack) => ({
+      name: pack.name,
+      source: pack.source,
+      resolved: pack.resolved,
+      resolvedAt: pack.resolvedAt,
+    }));
+  return `${JSON.stringify(
+    { version: lock.version, contentHash: lock.contentHash, packs },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Write the lock for a working directory.
+ *
+ * @param cwd - The project directory.
+ * @param lock - The lock to persist.
+ * @returns The exact bytes written (for the write effect / assertions).
+ * @note Impure — writes `pragma.lock.json`.
+ */
+export function writeLock(cwd: string, lock: PragmaLock): string {
+  const content = serializeLock(lock);
+  writeFileSync(lockPath(cwd), content);
+  return content;
+}

package/src/kernel/runtime/paths.ts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem locations for the store layer: the content-addressed pack cache,
+ * the git-ref checkout cache, and the project lock file.
+ *
+ * The pack cache lives under `$XDG_CACHE_HOME/pragma/packs/<contentHash>/`
+ * (content-addressed, so a new source set is a new directory and invalidation
+ * is free); ref checkouts under `.../pragma/refs/`. The lock is a committed
+ * project artifact at `<cwd>/pragma.lock.json`. All cache paths derive from the
+ * config kernel's {@link cacheDir}, so the XDG isolation the tests install
+ * contains them.
+ */
+
+import { join } from "node:path";
+import { cacheDir } from "../config/paths.js";
+
+/** The lock file basename, committed at the project root. */
+export const LOCK_BASENAME = "pragma.lock.json";
+
+/** `$XDG_CACHE_HOME/pragma/packs` — the content-addressed pack cache root. */
+export function packsCacheDir(): string {
+  return join(cacheDir(), "packs");
+}
+
+/** `$XDG_CACHE_HOME/pragma/refs` — cached git-ref checkouts. */
+export function refsCacheDir(): string {
+  return join(cacheDir(), "refs");
+}
+
+/** The cache directory for a pack, named by its content hash. */
+export function packDir(contentHash: string): string {
+  return join(packsCacheDir(), contentHash);
+}
+
+/** The project lock file for a working directory. */
+export function lockPath(cwd: string): string {
+  return join(cwd, LOCK_BASENAME);
+}

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { runStoreProbe } from "./probe.js";
+
+describe("store probe (in-process)", () => {
+  it("boots the embedded pack and reports entity + triple counts", async () => {
+    const out = JSON.parse(await runStoreProbe()) as {
+      ok: boolean;
+      entities: number;
+      triples: string;
+    };
+    expect(out.ok).toBe(true);
+    // The embedded sample pack ships six indexed entities (3 abox + 3 tbox).
+    expect(out.entities).toBe(6);
+    expect(Number(out.triples)).toBeGreaterThan(0);
+  });
+});

package/src/kernel/runtime/probe.ts

@@ -0,0 +1,39 @@
+/**
+ * The `__store-probe` diagnostic — boot the embedded pack and report a count.
+ *
+ * Its whole reason to exist is the compiled binary: it exercises the full
+ * store-boot path (oxigraph WASM load, n-quads cache load, `compileFromExtraction`,
+ * a SPARQL count) so a spawned-binary smoke test can prove the WASM and the
+ * embedded pack survive `bun build --compile`. A silent store-boot failure in
+ * the standalone binary is the one failure vitest's in-process suite cannot
+ * catch, so this is the guard. Storeless code never imports it — the bin
+ * fast-paths it behind a dynamic import.
+ */
+
+/**
+ * Boot the embedded pack and return a one-line JSON diagnostic.
+ *
+ * @returns `{ ok, entities, triples }` as compact JSON.
+ * @note Impure — materializes the embedded pack and boots a store.
+ */
+export async function runStoreProbe(): Promise<string> {
+  const [{ materializeEmbeddedPack }, { readPack }] = await Promise.all([
+    import("./graphpack/embedded.js"),
+    import("./graphpack/read.js"),
+  ]);
+  const session = await readPack(materializeEmbeddedPack());
+  try {
+    const result = await session.store.query(
+      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+    );
+    const triples =
+      result.type === "select" ? (result.bindings[0]?.n ?? "0") : "0";
+    return JSON.stringify({
+      ok: true,
+      entities: session.index.entities.length,
+      triples,
+    });
+  } finally {
+    session.store.dispose();
+  }
+}