@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/kernel/runtime/loadSession.js

@@ -0,0 +1,34 @@
+/**
+ * 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 { materializeEmbeddedPack } from "./graphpack/embedded.js";
+import { readPack } from "./graphpack/read.js";
+import { resolveSources } from "./resolveSources.js";
+import { storeUnavailable } from "./storeReadiness.js";
+/**
+ * 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) {
+    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);
+}
+//# sourceMappingURL=loadSession.js.map

package/dist/src/kernel/runtime/loadSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadSession.js","sourceRoot":"","sources":["../../../../src/kernel/runtime/loadSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AASvD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAEjD,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACpC,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,GAAG,GACP,QAAQ,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAuB,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;IAC1E,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/src/kernel/runtime/paths.js

@@ -0,0 +1,78 @@
+/**
+ * Filesystem locations for the store layer: the content-addressed pack cache,
+ * the git-ref checkout cache, and the per-project active-pack pointer.
+ *
+ * The pack cache lives under `$XDG_CACHE_HOME/<bin>/packs/<contentHash>/`
+ * (content-addressed, so a new source set is a new directory and invalidation
+ * is free); ref checkouts under `.../<bin>/refs/`. Which pack answers a
+ * project's reads is recorded by a one-line POINTER under
+ * `.../<bin>/projects/` — the content hash `sources update` last built there,
+ * and nothing else. It lives in the cache rather than the repo because the pack
+ * it names is machine-local: a committed pointer would promise a store the next
+ * machine does not have.
+ *
+ * A LEAF module on purpose: it imports node builtins and the distribution's
+ * {@link BIN_NAME}, and owns the cache root's XDG resolution outright
+ * (`kernel/config/paths.ts` keeps config and state). The storeless `__complete`
+ * fast path (`kernel/completion/entitySource.ts`) has to read the pointer, and
+ * `completion/safety.test.ts` forbids the config LAYER anywhere on that import
+ * graph — so the cache root is resolved here rather than imported. `constants.ts`
+ * is not the config layer: it reads inert data, and that same guard positive-lists
+ * it.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { BIN_NAME } from "../../constants.js";
+/** `$XDG_CACHE_HOME/<bin>` (default `~/.cache/<bin>`) — the cache root. */
+function cacheDir() {
+    const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(base, BIN_NAME);
+}
+/** `$XDG_CACHE_HOME/<bin>/packs` — the content-addressed pack cache root. */
+export function packsCacheDir() {
+    return join(cacheDir(), "packs");
+}
+/** `$XDG_CACHE_HOME/<bin>/refs` — cached git-ref checkouts. */
+export function refsCacheDir() {
+    return join(cacheDir(), "refs");
+}
+/** The cache directory for a pack, named by its content hash. */
+export function packDir(contentHash) {
+    return join(packsCacheDir(), contentHash);
+}
+/**
+ * The active-pack pointer for a project: `$XDG_CACHE_HOME/<bin>/projects/<key>`.
+ *
+ * The key is the SHA-256 of the resolved `cwd` — a hash rather than the path
+ * itself so a deep project directory can never exceed the 255-byte filename
+ * limit, and a cryptographic one so two projects can never collide onto each
+ * other's graph.
+ */
+export function activePackPath(cwd) {
+    return join(cacheDir(), "projects", createHash("sha256").update(resolve(cwd)).digest("hex"));
+}
+/**
+ * The content hash of the pack `sources update` built for a project.
+ *
+ * @param cwd - The project directory.
+ * @returns The 64-hex content hash, or `undefined` when the project was never
+ *   built. A pointer that is unreadable, or that does not hold exactly one
+ *   hash, is treated as absent — a corrupt pointer must never name an arbitrary
+ *   cache directory.
+ * @note Impure — reads the pointer from the cache.
+ */
+export function readActivePack(cwd) {
+    const path = activePackPath(cwd);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const hash = readFileSync(path, "utf-8").trim();
+        return /^[0-9a-f]{64}$/.test(hash) ? hash : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/kernel/runtime/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/kernel/runtime/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,2EAA2E;AAC3E,SAAS,QAAQ;IACf,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,WAAmB;IACzC,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,WAAW,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,IAAI,CACT,QAAQ,EAAE,EACV,UAAU,EACV,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAChD,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/src/kernel/runtime/probe.js

@@ -0,0 +1,37 @@
+/**
+ * The `__store-probe` diagnostic — boot the embedded pack and report a count.
+ *
+ * Its whole reason to exist is the PROCESS BOUNDARY: it exercises the full
+ * store-boot path (oxigraph WASM load, n-quads cache load,
+ * `compileFromExtraction`, a SPARQL count) so a spawned smoke test can prove the
+ * WASM and the embedded pack load from what actually ships. A silent store-boot
+ * failure in the shipped artifact is the one failure vitest's in-process suite
+ * cannot catch, so this is the guard (`wasmEmbed.test.ts` spawns it). 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() {
+    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 }");
+        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();
+    }
+}
+//# sourceMappingURL=probe.js.map

package/dist/src/kernel/runtime/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../../src/kernel/runtime/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,CAAC,EAAE,uBAAuB,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpE,MAAM,CAAC,yBAAyB,CAAC;QACjC,MAAM,CAAC,qBAAqB,CAAC;KAC9B,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CACtC,4CAAqD,CACtD,CAAC;QACF,MAAM,OAAO,GACX,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,EAAE,EAAE,IAAI;YACR,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM;YACvC,OAAO;SACR,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/src/kernel/runtime/readEntity.js

@@ -0,0 +1,363 @@
+/**
+ * Store-backed single-entity read: the GRAPH NEIGHBOURHOOD of one URI.
+ *
+ * The ONE reader shared by the `graph inspect` CLI verb and the MCP resource
+ * `read` — so a resource read and a `graph inspect` of the same URI return
+ * identical content (the mirror contract). The URI is resolved through the
+ * store's merged prefix map and validated safe for `<iri>` embedding — via
+ * `resolveUri` → `assertSafeIri`, which rejects every IRI-breaking character
+ * (`<>"{}|\^\`` + whitespace) — before it is interpolated, so a prefixed name or
+ * absolute IRI addresses the subject exactly and user input never reaches the
+ * query text raw.
+ *
+ * Four things make the payload answerable rather than merely faithful:
+ *
+ * - **Typed terms.** Read from ke's `termBindings` (the term-preserving view of
+ *   the SAME rows), never the stringly `bindings`. This is what makes prefix
+ *   compaction SAFE: only a `NamedNode` is compacted, so a literal whose text
+ *   happens to start with a namespace IRI is no longer silently rewritten into
+ *   something that reads as an IRI. It also keeps `datatype`/`language`, which
+ *   the string view drops.
+ * - **Inbound relations.** Everything pointing AT the subject, grouped by
+ *   predicate. Without it the entity that a resource is supposed to describe
+ *   cannot answer "what implements this?" or "what inherits from this?" — the
+ *   relations live on the OTHER side of the arrow and were simply invisible.
+ * - **Nested blank nodes.** A blank node is a store-local handle: it re-mints on
+ *   every load and is unreachable through `pragma:{+uri}`. Inlining one level
+ *   turns a dead `_:hash` into the record it stands for (a changelog entry's
+ *   text/type/timestamp). Depth ONE is not a shortcut — 11 of this graph's 922
+ *   blank nodes nest, so one level is what there is to inline.
+ * - **Neighbour titles.** Every named neighbour carries the human name the index
+ *   already holds, so a reader is not forced into a second read per IRI just to
+ *   learn that `ds:tag.needsdocumentation` is "needs:documentation".
+ *
+ * Bounded by the SHARED disclosure ladder, and by what an inbound group IS —
+ * because not every edge pointing at an entity is the same kind of thing:
+ *
+ * - A RELATION fans in narrowly and every subject is part of the answer
+ *   (`ds:implementsBlock`, `ds:inheritsFrom`), so it is LISTED.
+ * - A ROSTER fans in without bound because it grows with the data rather than
+ *   the model — a class extension (`rdf:type`), a tier's membership (`ds:tier`,
+ *   141 deep here) — and is already answered by `pragma/instanceCount` and by
+ *   the noun's list verb. So it is SAMPLED: a few exemplars, flagged `sampled`,
+ *   never a page. Listing rosters cost a `detailed` read 19.5 KB on one class
+ *   and 20.9 KB on one tier, restating what a single `*_list` answers properly.
+ *
+ * The two are told apart by FAN-IN, not by predicate name, so the kernel names
+ * no vocabulary and a graph whose rosters hang off different predicates is
+ * bounded just the same. `count` always reports the TRUE total either way: a
+ * sample that silently passed for the whole set is how "3 implementations"
+ * becomes a wrong answer.
+ *
+ * Reached only behind the lazy store (a `needsStore` verb / a resource read), so
+ * it never lands on the storeless fast path.
+ */
+import { cliRecovery, PragmaError } from "../error/index.js";
+import { resolveUri } from "../packs/iri.js";
+import { compactUri, resolveDetail } from "../render/index.js";
+/**
+ * Where a relation stops being an answer and becomes a roster.
+ *
+ * A group at or under this fan-in is LISTED: every subject is part of the
+ * answer, and there are few enough that reading them is cheaper than going to
+ * fetch them. Above it, listing the head is not more useful than showing a few
+ * — only longer — so the group is SAMPLED instead.
+ *
+ * Derived from fan-in rather than from a predicate name, which is what keeps the
+ * kernel free of vocabulary: `rdf:type` inbound is the obvious roster (a class
+ * extension, unbounded by construction and already answered by
+ * `pragma/instanceCount` and the noun's list verb), but it is NOT the only one.
+ * Membership edges behave identically — this graph's `ds:tier` fans in 141 deep
+ * — and a rule keyed on `rdf:type` would have left a `detailed` read of one tier
+ * at 20.9 KB while congratulating itself on having fixed classes.
+ */
+const ROSTER_THRESHOLD = 20;
+/** How many subjects each level lists for a genuine ANSWER (fan-in ≤ threshold). */
+const ANSWER_CAP = {
+    summary: 0,
+    standard: 10,
+    detailed: ROSTER_THRESHOLD,
+};
+/**
+ * How many EXEMPLARS each level shows for a roster — the move the `*_sample`
+ * verbs make, and for the same reason: enough to see the shape of a member,
+ * never the roster itself. `count` stays exact and {@link InboundGroup.sampled}
+ * says which kind of answer this is, so a reader reaches for the list verb
+ * rather than trying to page a resource read into one.
+ */
+const SAMPLE_CAP = {
+    summary: 0,
+    standard: 3,
+    detailed: 5,
+};
+/**
+ * How many characters of a LITERAL each level carries.
+ *
+ * The measured cost of a rich entity is not its structure but its prose: one
+ * button spent 8,572 of its 9,734 literal characters on two fields
+ * (`ds:guidelines` 5,814, `ds:usage` 2,758). Serving those in full at the
+ * DEFAULT level makes every read of that entity pay for documentation the
+ * reader may not have asked for — and the noun's own lookup verb serves the
+ * same fields under its own disclosure, properly.
+ *
+ * So long-form prose is what `detailed` is FOR. Below it a literal is previewed
+ * and marked {@link ReadTerm.truncated} with its true {@link ReadTerm.length},
+ * so a reader can always see that there is more and how much.
+ */
+const LITERAL_CAP = {
+    summary: 120,
+    standard: 400,
+    detailed: Number.POSITIVE_INFINITY,
+};
+/**
+ * Ceiling on the EXEMPLAR rows fetched — never on the counts.
+ *
+ * Counting and exhibiting are two different questions, and answering both from
+ * one capped query answered neither: a single `LIMIT` applies to the whole
+ * ordered result, so the first predicate to fill it under-reported its own
+ * `count` and every predicate after it vanished from the read entirely — while
+ * `InboundGroup.count` promised the true total. Counts now come from an
+ * aggregate the store computes; only the exemplars are bounded.
+ */
+const EXEMPLAR_FETCH_LIMIT = 500;
+/** The predicate whose object is a subject's type — hoisted out of nested records. */
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+/**
+ * Whether a name tells a reader anything the URI's own local name did not.
+ *
+ * Measured on this graph, EVERY title a button's neighbourhood carried merely
+ * restated its local name in different casing (`ds:implementsBlock` titled
+ * "implementsBlock", `ds:apps.component.file_tree` titled "FileTree"). Emitting
+ * those spends a reader's attention — and an agent's context — to say the same
+ * word twice. A graph whose labels are real prose (a concept at `ds:concept.pd`
+ * named "Progressive disclosure") still keeps them, so this thins noise without
+ * deciding that labels are worthless.
+ */
+function isInformativeName(name, short) {
+    const normalize = (value) => value.replace(/[\s._:-]/g, "").toLowerCase();
+    const local = short.split(/[:.]/).pop() ?? short;
+    return normalize(name) !== normalize(local);
+}
+/** Index lookup for a neighbour's human name (`label`, else the first alt name). */
+function nameIndex(index) {
+    const names = new Map();
+    for (const entity of index.entities) {
+        if (!entity.uri)
+            continue;
+        const name = entity.label ?? entity.altNames?.[0];
+        if (name && !names.has(entity.uri))
+            names.set(entity.uri, name);
+    }
+    return names;
+}
+/** Project one ke term into a {@link ReadTerm}, previewing long literals. */
+function toReadTerm(term, prefixes, names, detail) {
+    if (term.termType === "NamedNode") {
+        const prefixed = compactUri(term.value, prefixes);
+        const name = names.get(term.value);
+        const title = name && isInformativeName(name, prefixed) ? name : undefined;
+        return {
+            termType: "NamedNode",
+            value: term.value,
+            // compactUri returns the input unchanged when no namespace matches, so an
+            // unmatched IRI carries no `prefixed` rather than one echoing `value`.
+            ...(prefixed === term.value ? {} : { prefixed }),
+            ...(title ? { title } : {}),
+        };
+    }
+    if (term.termType === "BlankNode") {
+        return { termType: "BlankNode", value: term.value, addressable: false };
+    }
+    const cap = LITERAL_CAP[detail];
+    const overlong = term.value.length > cap;
+    return {
+        termType: "Literal",
+        value: overlong ? term.value.slice(0, cap) : term.value,
+        ...(overlong
+            ? { truncated: true, length: term.value.length }
+            : {}),
+        ...(term.datatype ? { datatype: compactUri(term.datatype, prefixes) } : {}),
+        ...(term.language ? { language: term.language } : {}),
+        ...(term.direction ? { direction: term.direction } : {}),
+    };
+}
+/**
+ * Read one entity's graph neighbourhood.
+ *
+ * @param rt - The runtime (lazy store, query facade, config, global flags).
+ * @param uri - A prefixed name or absolute IRI.
+ * @returns The resolved subject, its outbound groups, inbound groups, inlined
+ *   blank nodes, and the detail level the payload was built at.
+ * @throws PragmaError ENTITY_NOT_FOUND when the subject asserts no triples.
+ * @note Impure — boots the store and queries it (three reads: out, in, nested).
+ */
+export async function readEntity(rt, uri) {
+    const session = await rt.store.get();
+    const resolved = resolveUri(uri, session.prefixes);
+    const outbound = await rt.query.sparql(`SELECT ?predicate ?object WHERE { <${resolved}> ?predicate ?object } ORDER BY ?predicate ?object`);
+    if (outbound.type !== "select" || outbound.termBindings.length === 0) {
+        throw PragmaError.notFound("entity", uri, {
+            recovery: cliRecovery(`graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'`, "Check the URI, or list known entities.", { tool: "graph_query" }),
+        });
+    }
+    // The level is resolved from the SAME sources as every other disclosure: the
+    // `--detail` flag (which the MCP `detail` param also seeds), then config. A
+    // resource read carries no params of its own, so it lands on the config value
+    // — `config_set detail detailed` is how an agent asks a resource for more.
+    const detail = resolveDetail({
+        flag: rt.globalFlags.detail,
+        config: (await rt.loadConfig()).config.detail,
+    });
+    const names = nameIndex(session.index);
+    const term = (value) => toReadTerm(value, session.prefixes, names, detail);
+    const groupMap = new Map();
+    const predicates = new Map();
+    let hasBlankObject = false;
+    for (const binding of outbound.termBindings) {
+        const predicate = binding.predicate;
+        const object = binding.object;
+        if (!predicate || !object)
+            continue;
+        if (object.termType === "BlankNode")
+            hasBlankObject = true;
+        predicates.set(predicate.value, term(predicate));
+        const objects = groupMap.get(predicate.value) ?? [];
+        objects.push(term(object));
+        groupMap.set(predicate.value, objects);
+    }
+    const groups = [...groupMap.entries()].map(([predicate, objects]) => ({
+        // Every key was written from a binding above, so the lookup cannot miss.
+        predicate: predicates.get(predicate),
+        objects,
+    }));
+    const inbound = await readInbound(rt, resolved, detail, term);
+    const nested = detail === "summary" || !hasBlankObject
+        ? {}
+        : await readNested(rt, resolved, session.prefixes, term);
+    const prefixed = compactUri(resolved, session.prefixes);
+    const label = session.index.entities.find((e) => e.uri === resolved)?.label;
+    return {
+        uri: resolved,
+        ...(prefixed === resolved ? {} : { prefixed }),
+        ...(label != null ? { label } : {}),
+        groups,
+        inbound,
+        nested,
+        detail,
+        prefixes: session.prefixes,
+    };
+}
+/**
+ * Everything asserting a predicate about the subject, grouped and capped.
+ *
+ * One query rather than one per predicate: the rows are grouped in memory, so a
+ * hub costs the same round trip as a leaf.
+ */
+async function readInbound(rt, resolved, detail, term) {
+    // Counts from an AGGREGATE, so every predicate is counted in full and no
+    // predicate can be pushed out of the answer by a noisy neighbour.
+    const totals = await rt.query.sparql(`SELECT ?predicate (COUNT(*) AS ?total) WHERE { ?subject ?predicate <${resolved}> } GROUP BY ?predicate ORDER BY ?predicate`);
+    if (totals.type !== "select")
+        return [];
+    const counts = new Map();
+    const predicates = new Map();
+    for (const binding of totals.termBindings) {
+        const predicate = binding.predicate;
+        const total = binding.total;
+        if (!predicate || !total)
+            continue;
+        predicates.set(predicate.value, predicate);
+        counts.set(predicate.value, Number(total.value));
+    }
+    if (counts.size === 0)
+        return [];
+    // Exemplars in a second, separately bounded pass. Blank nodes are excluded in
+    // the QUERY rather than after it, so the limit is spent on subjects that can
+    // actually be exhibited — a hub whose members are all blank returns nothing
+    // here and is reported by its count alone.
+    const retained = new Map();
+    const widest = Math.max(...Object.values(ANSWER_CAP), ...Object.values(SAMPLE_CAP));
+    if (widest > 0) {
+        const exemplars = await rt.query.sparql(`SELECT ?predicate ?subject WHERE { ?subject ?predicate <${resolved}> . FILTER(isIRI(?subject)) } ORDER BY ?predicate ?subject LIMIT ${EXEMPLAR_FETCH_LIMIT}`);
+        if (exemplars.type === "select") {
+            for (const binding of exemplars.termBindings) {
+                const predicate = binding.predicate;
+                const subject = binding.subject;
+                if (!predicate || !subject)
+                    continue;
+                const rows = retained.get(predicate.value) ?? [];
+                if (rows.length < widest)
+                    rows.push(subject);
+                retained.set(predicate.value, rows);
+            }
+        }
+    }
+    return [...counts.entries()].map(([key, count]) => {
+        // What the group IS decides how it is shown: a relation is listed, a roster
+        // is sampled. Derived from fan-in, so no predicate is named here.
+        const roster = count > ROSTER_THRESHOLD;
+        const cap = roster ? SAMPLE_CAP[detail] : ANSWER_CAP[detail];
+        const subjects = (retained.get(key) ?? []).slice(0, cap).map(term);
+        return {
+            predicate: term(predicates.get(key)),
+            count,
+            subjects,
+            exhibits: cap,
+            ...(subjects.length < count ? { truncated: true } : {}),
+            ...(roster ? { sampled: true } : {}),
+        };
+    });
+}
+/**
+ * Blank-node objects inlined one level, as one record per node.
+ *
+ * Records rather than triples: the same content is roughly half the bytes and
+ * reads as the thing it models (a changelog entry, a property) instead of a
+ * scatter of rows the reader has to reassemble. `rdf:type` is hoisted to `type`
+ * — it is the record's kind, not one of its fields, and repeating it inline put
+ * the same IRI on every row.
+ */
+async function readNested(rt, resolved, prefixes, term) {
+    const result = await rt.query.sparql(`SELECT ?predicate ?node ?nodePredicate ?nodeObject WHERE { <${resolved}> ?predicate ?node . FILTER(isBlank(?node)) . ?node ?nodePredicate ?nodeObject } ORDER BY ?predicate ?node ?nodePredicate`);
+    if (result.type !== "select")
+        return {};
+    // Keyed by blank-node label so repeated nodes under one predicate stay
+    // separate records; the label itself never reaches the payload.
+    const records = new Map();
+    for (const binding of result.termBindings) {
+        const predicate = binding.predicate;
+        const node = binding.node;
+        const nodePredicate = binding.nodePredicate;
+        const nodeObject = binding.nodeObject;
+        if (!predicate || !node || !nodePredicate || !nodeObject)
+            continue;
+        const via = compactUri(predicate.value, prefixes);
+        // Keyed by predicate AND node. Keyed by node alone, a blank node linked from
+        // two predicates kept only whichever `via` arrived first and the second edge
+        // silently disappeared — and in Turtle the ordinary blank object is filtered
+        // out too, so nothing was left to notice it by.
+        const key = `${predicate.value}\u0000${node.value}`;
+        const record = records.get(key) ?? { via, row: {} };
+        const field = nodePredicate.value === RDF_TYPE
+            ? "type"
+            : compactUri(nodePredicate.value, prefixes);
+        record.row[field] = term(nodeObject);
+        records.set(key, record);
+    }
+    const nested = {};
+    for (const { via, row } of records.values()) {
+        const rows = nested[via] ?? [];
+        rows.push(row);
+        nested[via] = rows;
+    }
+    // Order records by their CONTENT, never by the blank-node label that grouped
+    // them. Oxigraph re-mints those labels on every load, so ordering by them made
+    // two reads of the same unchanged entity return the same records in different
+    // orders — nondeterminism the mirror test caught and a caller diffing two
+    // reads would have seen as spurious change.
+    for (const rows of Object.values(nested)) {
+        rows.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    }
+    return nested;
+}
+//# sourceMappingURL=readEntity.js.map

package/dist/src/kernel/runtime/readEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readEntity.js","sourceRoot":"","sources":["../../../../src/kernel/runtime/readEntity.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/runtime/refs/gitOps.js

@@ -0,0 +1,65 @@
+/**
+ * Git operations for cached package clones.
+ *
+ * Ported from the v1 refs domain. Every call is `execFileSync` with the default
+ * `shell: false`, so refs and URLs are passed as argv, never interpolated into
+ * a shell. Authentication is delegated entirely to the user's git client (SSH
+ * keys, credential helpers) — zero custom auth. Shallow clones (`--depth 1`)
+ * keep checkouts cheap.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/** Whether a ref looks like a commit SHA (7-40 hex chars). */
+export function isSha(ref) {
+    return /^[0-9a-f]{7,40}$/.test(ref);
+}
+/** Run git in a directory, throwing on non-zero exit. */
+function git(cwd, args) {
+    execFileSync("git", [...args], { cwd, stdio: "pipe" });
+}
+/** Run git and return trimmed stdout. */
+function gitOutput(cwd, args) {
+    return execFileSync("git", [...args], { cwd, stdio: "pipe" })
+        .toString()
+        .trim();
+}
+/**
+ * Clone a repository at a ref into a destination directory (must not exist).
+ *
+ * @param url - Git remote URL.
+ * @param ref - Branch, tag, or commit SHA.
+ * @param dest - Target directory.
+ * @note Impure — runs git, writes the checkout.
+ */
+export function cloneRef(url, ref, dest) {
+    mkdirSync(dirname(dest), { recursive: true });
+    if (isSha(ref)) {
+        // Shallow clone by SHA is unsupported — init + fetch the commit + checkout.
+        mkdirSync(dest, { recursive: true });
+        git(dest, ["init"]);
+        git(dest, ["fetch", "--depth", "1", url, ref]);
+        git(dest, ["checkout", "FETCH_HEAD"]);
+    }
+    else {
+        execFileSync("git", ["clone", "--depth", "1", "--branch", ref, url, dest], {
+            stdio: "pipe",
+        });
+    }
+}
+/**
+ * Fetch a ref into an existing cached clone and check it out.
+ *
+ * @returns The newly resolved HEAD commit.
+ * @note Impure — runs git, updates the checkout.
+ */
+export function fetchRef(url, ref, dest) {
+    git(dest, ["fetch", "--depth", "1", url, ref]);
+    git(dest, ["checkout", "FETCH_HEAD"]);
+    return gitOutput(dest, ["rev-parse", "HEAD"]);
+}
+/** The resolved HEAD commit of a checkout. */
+export function headCommit(dest) {
+    return gitOutput(dest, ["rev-parse", "HEAD"]);
+}
+//# sourceMappingURL=gitOps.js.map

package/dist/src/kernel/runtime/refs/gitOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitOps.js","sourceRoot":"","sources":["../../../../../src/kernel/runtime/refs/gitOps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,8DAA8D;AAC9D,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,OAAO,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,yDAAyD;AACzD,SAAS,GAAG,CAAC,GAAW,EAAE,IAAuB;IAC/C,YAAY,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,yCAAyC;AACzC,SAAS,SAAS,CAAC,GAAW,EAAE,IAAuB;IACrD,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;SAC1D,QAAQ,EAAE;SACV,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY;IAC7D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACf,4EAA4E;QAC5E,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QACpB,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE;YACzE,KAAK,EAAE,MAAM;SACd,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY;IAC7D,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/C,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IACtC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/src/kernel/runtime/refs/index.js

@@ -0,0 +1,29 @@
+/**
+ * Package refs — turning what a project DECLARED into pinned, on-disk RDF.
+ *
+ * `sources update` is the only caller, and this domain is its whole
+ * resolution: parse a `packs` entry into a typed reference, resolve that
+ * reference to a revision and the TTL/story files it carries, and report what
+ * the resulting set of sources says about itself. Three declaration kinds
+ * (`npm`, `file`, `git`) resolve three different ways but converge on one
+ * `ResolvedPackage`, so callers pin, hash, and build from a single shape.
+ *
+ * The prefix inspectors belong here rather than with the pack builder because
+ * they answer a question about the RESOLVED SET, not about any one package: a
+ * label two packages bind to different IRIs is a conflict nobody can see from
+ * inside either one, and it must be caught before the sources are built rather
+ * than after, when it would surface as a query that silently reads the wrong
+ * namespace.
+ *
+ * `redactUrl` is on the surface because every one of these paths ends in a
+ * message: a git URL may carry a token, and the caller that reports what it
+ * resolved needs the redactor as much as it needs the result.
+ *
+ * The git operations underneath — clone, fetch, head — stay internal. They are
+ * how `git` refs resolve, and they are safe because refs and URLs reach them
+ * as argv and never as shell text; exposing them would offer the operations
+ * without the parsing that validated their arguments.
+ */
+export { parsePackDeclaration, redactUrl } from "./parseRef.js";
+export { detectPrefixClashes, harvestPrefixes, resolvePackage, } from "./resolve.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/runtime/refs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/kernel/runtime/refs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAMhE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC"}