@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/kernel/spec/emitSurface.js

@@ -0,0 +1,202 @@
+/**
+ * Surface emitter: project capability modules into the machine-readable
+ * surface document that the covenant (`surface/surface.v2.json`) freezes.
+ *
+ * The emitter is pure and zod-free so it sits on the `--help`/`__complete`
+ * fast path. It reads only the grammar — never a run body — and merges in the
+ * fixed kernel sections that describe the invariant contract (bins, flags,
+ * envelope, exit codes, budgets, ...). Hidden verbs are excluded.
+ */
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
+/** kebab-case a camelCase param name for its flag form (`allTiers` -> `all-tiers`). */
+export function kebabCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** The MCP tool name for a verb path (`["config","show"]` -> `config_show`). */
+export function toolName(path) {
+    const [noun, verb] = path;
+    return verb ? `${noun}_${verb}` : noun;
+}
+/** The verb label within its noun (last path segment; the noun itself when self-verb). */
+export function verbLabel(path) {
+    return path[1] ?? path[0];
+}
+/**
+ * The invariant kernel contract, merged into every emitted surface and frozen
+ * verbatim in the covenant. This is the single authoring point — the golden
+ * embeds a copy and conformance deep-equals the two, so drift is caught.
+ */
+export const FIXED_SURFACE = {
+    bins: {
+        [BIN_NAME]: `${BIN_NAME} CLI and MCP server host (stdio)`,
+    },
+    globalFlags: [
+        {
+            flag: "--format <plain|llm|json>",
+            doc: "Select output format (llm = condensed Markdown for agents)",
+        },
+        { flag: "--verbose", doc: "Diagnostic output on stderr (sources update)" },
+        {
+            flag: "--detail <level>",
+            doc: "Progressive-disclosure level (summary, standard, detailed)",
+        },
+        {
+            flag: "--no-headers",
+            doc: "Hide the table header row in plain output",
+        },
+        {
+            flag: "--quiet",
+            doc: "Suppress success and progress output (errors still print)",
+        },
+    ],
+    detailLevels: ["summary", "standard", "detailed"],
+    envelope: {
+        success: { ok: true, data: "<payload>", meta: "<object>" },
+        error: {
+            ok: false,
+            error: {
+                code: "<ErrorCode>",
+                message: "<string>",
+                suggestions: "string[]?",
+                recovery: "Recovery?",
+                validOptions: "string[]?",
+                filters: "object?",
+            },
+        },
+    },
+    exitCodes: {
+        "0": "success",
+        "1": "runtime (entity-not-found, empty, config, internal)",
+        "2": "usage (invalid/ambiguous input, unknown verb)",
+        "3": "store unavailable",
+    },
+    mutationContract: {
+        cli: { dryRun: "--dry-run", undo: "--undo", confirm: "--yes" },
+        mcp: {
+            planFirst: true,
+            confirmParam: "confirm",
+            planMeta: { planOnly: true, confirmRequired: true },
+        },
+    },
+    completion: {
+        static: "shell script tier emitted by `setup completions`",
+        dynamic: "hidden `__complete` resolver, storeless",
+        paramSource: "ParamSpec.complete",
+    },
+    configFiles: {
+        project: `${PROJECT_CONFIG_FILENAME} (evaluated, content-hash cached)`,
+        global: `$XDG_CONFIG_HOME/${BIN_NAME}/config.json`,
+        // Named `configCache` because that is what it is: the evaluated project
+        // config's content-addressed cache. It was called `lock` for a project lock
+        // file that no longer exists.
+        configCache: `$XDG_STATE_HOME/${BIN_NAME}/config-cache/<sha256>.json`,
+        defaults: "built-in defaults.ts",
+    },
+    budgets: {
+        $comment: "help/complete/warmStoreVerb are designed aspirations; the ENFORCED ceilings (budgets.test.ts) are 130ms help / 100ms complete / 500ms warmStoreVerb, each derived from measurement on the build hardware and recorded in BUDGETS.md. Designed-aspiration vs enforced-measured. warmStoreVerb joined this list when the embedded pack became the distribution's real graph rather than a sample, which puts the reference box's projected p95 over the designed 300ms; BUDGETS.md carries the arithmetic.",
+        help: "<50ms",
+        complete: "<50ms",
+        projectConfigLoad: "<10ms",
+        warmStoreVerb: "<300ms",
+        mcpP95Warm: "<100ms",
+        condensedSDL: "<=8000 tokens",
+    },
+};
+/** Format a positional param as its usage token (`<name>` required, `[name]` optional). */
+function positionalToken(param) {
+    const variadic = param.kind === "string[]" ? "..." : "";
+    return param.required
+        ? `<${param.name}${variadic}>`
+        : `[${param.name}${variadic}]`;
+}
+/**
+ * Project one verb into its surface entry, omitting default/falsy fields.
+ *
+ * `flagTokens` is a MOUNTED verb's registered spelling per param name — the
+ * same `ReferenceCliSyntax.flagTokens` seam the reference emitter consumes,
+ * supplied by the module's `cliProjection` and derived there from
+ * `buildOptionInfo` (the single flag-shape authority both binaries register
+ * from; a default-`true` confirm registers ONLY its `--no-<kebab>` form).
+ * Without it the token derives from the param name — the kernel convention,
+ * sound for kernel-registered verbs where B9 ADDS the `--no-` negation
+ * beside the positive form; false for a mounted noun, where kebab-casing
+ * wrote seven covenant tokens the CLI rejects (`--with-styles`, `--ssr`, …).
+ *
+ * `positionalTokens` is the same seam's registered POSITIONAL spelling per
+ * param name (`componentPath` → `[component-path]` — the token the usage
+ * line and the Args tables print), preferred for `args` exactly as
+ * `flagTokens` is for `flags`; a param absent there keeps the kernel
+ * `<name>`/`[name]` derivation.
+ */
+export function emitVerb(verb, flagTokens, positionalTokens) {
+    const positionals = verb.params.filter((p) => p.positional);
+    const flags = verb.params.filter((p) => !p.positional);
+    const entry = { v: verbLabel(verb.path) };
+    if (positionals.length > 0)
+        entry.args = positionals.map((p) => positionalTokens?.[p.name] ?? positionalToken(p));
+    if (flags.length > 0)
+        entry.flags = flags.map((p) => flagTokens?.[p.name] ?? `--${kebabCase(p.name)}`);
+    if (verb.capability.mutates)
+        entry.mutates = true;
+    if (verb.capability.needsStore)
+        entry.needsStore = true;
+    entry.mcp = verb.capability.mcp.expose ? toolName(verb.path) : false;
+    return entry;
+}
+/**
+ * Emit the full surface document for a set of capability modules.
+ *
+ * @param modules - The capability modules to project (hidden verbs excluded).
+ * @returns The surface document: live nouns + sorted tools + fixed sections.
+ */
+export function emitSurface(modules) {
+    const nouns = {};
+    const tools = [];
+    const resources = [];
+    let prompts = false;
+    for (const module of modules) {
+        for (const verb of module.verbs) {
+            if (verb.hidden)
+                continue;
+            const noun = verb.path[0];
+            const bucket = nouns[noun] ?? { verbs: [] };
+            nouns[noun] = bucket;
+            // A mounted verb's covenant flags AND args are its REGISTERED
+            // spellings, from the module's own syntax seam (see emitVerb) — the
+            // covenant must name tokens the CLI parses (`--no-with-styles`,
+            // `[component-path]`), not camelCase param names its help never prints.
+            const syntax = module.cliProjection?.referenceSyntax?.(verb.path);
+            bucket.verbs.push(emitVerb(verb, syntax?.flagTokens, syntax?.positionalTokens));
+            if (verb.capability.mcp.expose)
+                tools.push(toolName(verb.path));
+        }
+        // Non-tool MCP surfaces (module hooks, NOT verbs): the resource template ids
+        // the provider declares, and whether a native prompt surface is offered.
+        if (module.mcpResources?.surface) {
+            resources.push(...module.mcpResources.surface.templates);
+        }
+        if (module.mcpPrompts)
+            prompts = true;
+    }
+    return {
+        nouns,
+        mcpSurface: {
+            tools: tools.sort(),
+            resources: resources.sort(),
+            prompts,
+            // The server always carries handshake instructions (buildServer sets them
+            // unconditionally), so this is an invariant true — a stable presence marker.
+            instructions: true,
+        },
+        bins: FIXED_SURFACE.bins,
+        globalFlags: FIXED_SURFACE.globalFlags,
+        detailLevels: FIXED_SURFACE.detailLevels,
+        envelope: FIXED_SURFACE.envelope,
+        exitCodes: FIXED_SURFACE.exitCodes,
+        mutationContract: FIXED_SURFACE.mutationContract,
+        completion: FIXED_SURFACE.completion,
+        configFiles: FIXED_SURFACE.configFiles,
+        budgets: FIXED_SURFACE.budgets,
+    };
+}
+//# sourceMappingURL=emitSurface.js.map

package/dist/src/kernel/spec/emitSurface.js.map

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

package/dist/src/kernel/spec/index.js

@@ -0,0 +1,11 @@
+/**
+ * Spec kernel barrel — the grammar and its zod-free projections.
+ *
+ * `validate.ts` (zod) is intentionally NOT re-exported here: it is imported
+ * directly, and lazily, by the registration seams so this barrel — and the
+ * `--help`/`__complete` path that reaches it — stays free of zod.
+ */
+export { emitReference } from "./emitReference.js";
+export { emitSurface, emitVerb, FIXED_SURFACE, kebabCase, toolName, verbLabel, } from "./emitSurface.js";
+export { assertConforms, deepEqual } from "./surfaceConformance.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/spec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kernel/spec/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD,OAAO,EACL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,SAAS,EACT,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/src/kernel/spec/surfaceConformance.js

@@ -0,0 +1,103 @@
+/**
+ * Frozen-covenant conformance (D1).
+ *
+ * `surface/surface.v2.json` is the designed, frozen surface. Each PR emits
+ * only the entries it has actually built and asserts that its emitted surface
+ * *conforms* to the covenant: every emitted noun+verb exists in the covenant
+ * and deep-equals it, every emitted tool is one the covenant blesses, and the
+ * fixed kernel sections match verbatim. The covenant may hold entries no PR
+ * emits yet (the future surface) — conformance is one-directional
+ * (emitted subset of covenant), so later PRs re-snapshot their slice in-diff
+ * without disturbing this one.
+ */
+/** The fixed kernel sections a covenant must match verbatim. */
+const FIXED_SECTIONS = [
+    "bins",
+    "globalFlags",
+    "detailLevels",
+    "envelope",
+    "exitCodes",
+    "mutationContract",
+    "completion",
+    "configFiles",
+    "budgets",
+];
+/** Order-sensitive structural deep-equality for JSON-shaped values. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (typeof a !== "object")
+        return false;
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => key in bObj && deepEqual(aObj[key], bObj[key]));
+}
+/**
+ * Assert that an emitted surface conforms to the covenant.
+ *
+ * @param emitted - The surface produced by {@link emitSurface}.
+ * @param covenant - The parsed `surface.v2.json` golden.
+ * @throws Error with a specific path on the first non-conformance.
+ */
+export function assertConforms(emitted, covenant) {
+    for (const [noun, { verbs }] of Object.entries(emitted.nouns)) {
+        const covNoun = covenant.nouns[noun];
+        if (!covNoun) {
+            throw new Error(`surface: emitted noun "${noun}" is not in the covenant`);
+        }
+        for (const verb of verbs) {
+            const covVerb = covNoun.verbs.find((entry) => entry.v === verb.v);
+            if (!covVerb) {
+                throw new Error(`surface: emitted verb "${noun} ${verb.v}" is not in the covenant`);
+            }
+            if (!deepEqual(verb, covVerb)) {
+                throw new Error(`surface: emitted verb "${noun} ${verb.v}" does not match the covenant\n` +
+                    `  emitted:  ${JSON.stringify(verb)}\n` +
+                    `  covenant: ${JSON.stringify(covVerb)}`);
+            }
+        }
+    }
+    const blessed = new Set(covenant.mcpSurface.tools);
+    for (const tool of emitted.mcpSurface.tools) {
+        if (!blessed.has(tool)) {
+            throw new Error(`surface: emitted tool "${tool}" is not in the covenant`);
+        }
+    }
+    // Non-tool MCP surface (PR7 covenant extension), checked with the same subset
+    // semantics as tools and ONLY when the covenant declares the section — so an
+    // emitted-empty surface still conforms and synthetic tool-only covenants pass.
+    const cov = covenant.mcpSurface;
+    if (cov.resources) {
+        const blessedResources = new Set(cov.resources);
+        for (const template of emitted.mcpSurface.resources) {
+            if (!blessedResources.has(template)) {
+                throw new Error(`surface: emitted resource template "${template}" is not in the covenant`);
+            }
+        }
+    }
+    if (cov.prompts !== undefined && emitted.mcpSurface.prompts && !cov.prompts) {
+        throw new Error("surface: emitted a prompts surface the covenant does not bless");
+    }
+    if (cov.instructions !== undefined &&
+        emitted.mcpSurface.instructions !== cov.instructions) {
+        throw new Error("surface: instructions marker does not match the covenant");
+    }
+    for (const section of FIXED_SECTIONS) {
+        if (!deepEqual(emitted[section], covenant[section])) {
+            throw new Error(`surface: fixed section "${section}" does not match the covenant`);
+        }
+    }
+}
+//# sourceMappingURL=surfaceConformance.js.map

package/dist/src/kernel/spec/surfaceConformance.js.map

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

package/dist/src/kernel/spec/types.js

@@ -0,0 +1,14 @@
+/**
+ * The one grammar. Every capability is described by this vocabulary and
+ * nothing else: the CLI projector, the MCP projector, the surface emitter,
+ * and the completion resolver all read these shapes. Do NOT add fields — a
+ * new projection need is a signal to reshape an existing field, not to grow
+ * the grammar, so the surface covenant stays the single source of truth.
+ *
+ * Naming rule: `[noun]` -> CLI `pragma <noun>`, tool `<noun>`;
+ * `[noun, verb]` -> CLI `pragma <noun> <verb>`, tool `<noun>_<verb>`.
+ * Positionals are params with `positional: true`, in declared order; every
+ * other param is a kebab-cased flag.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/kernel/spec/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/kernel/spec/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/kernel/spec/validate.js

@@ -0,0 +1,110 @@
+/**
+ * Runtime validation of capability modules against the grammar.
+ *
+ * zod lives here (and only in the few registration seams the conventions
+ * name) so it never reaches the `--help`/`__complete` fast path: this module
+ * is imported lazily, at boot/registration, to fail fast on a malformed spec.
+ * It validates the *data* shape of the grammar — paths, params, capability,
+ * MCP exposure — and asserts the function-valued fields are functions.
+ */
+import { z } from "zod";
+const fn = z.custom((value) => typeof value === "function", { message: "expected a function" });
+const completionSourceRefSchema = z.object({
+    from: z.enum(["index", "skills", "prefixes"]),
+    type: z.string().optional(),
+    field: z.enum(["name", "label", "altNames"]).optional(),
+});
+const paramCompleteSchema = z.union([
+    z.object({ kind: z.literal("values") }),
+    z.object({ kind: z.literal("files") }),
+    z.object({ kind: z.literal("none") }),
+    z.object({
+        kind: z.literal("names"),
+        source: completionSourceRefSchema,
+        match: z.enum(["prefix", "substring", "fuzzy"]).optional(),
+        minChars: z.number().int().min(0).optional(),
+        caseSensitive: z.boolean().optional(),
+        enabled: z.boolean().optional(),
+    }),
+]);
+const positionalFields = {
+    name: z.string().min(1),
+    doc: z.string(),
+    required: z.boolean().optional(),
+    positional: z.boolean().optional(),
+    complete: paramCompleteSchema.optional(),
+};
+const paramSpecSchema = z.union([
+    z.object({
+        ...positionalFields,
+        kind: z.enum(["string", "boolean", "number"]),
+        default: z.unknown().optional(),
+    }),
+    z.object({
+        ...positionalFields,
+        kind: z.literal("enum"),
+        values: z.array(z.string()).min(1),
+        default: z.string().optional(),
+    }),
+    z.object({ ...positionalFields, kind: z.literal("string[]") }),
+]);
+const mcpAnnotationsSchema = z.object({
+    readOnlyHint: z.boolean(),
+    destructiveHint: z.boolean().optional(),
+    openWorldHint: z.boolean(),
+});
+const capabilitySchema = z.object({
+    needsStore: z.boolean(),
+    mutates: z.boolean(),
+    destructive: z.boolean().optional(),
+    needsNetwork: z.boolean().optional(),
+    interactive: z.boolean().optional(),
+    mcp: z.union([
+        z.object({
+            expose: z.literal(true),
+            annotations: mcpAnnotationsSchema.optional(),
+        }),
+        z.object({ expose: z.literal(false), reason: z.string().min(1) }),
+    ]),
+});
+const verbSpecSchema = z.object({
+    path: z.tuple([z.string().min(1)]).rest(z.string()),
+    summary: z.string().min(1),
+    doc: z.string().optional(),
+    params: z.array(paramSpecSchema),
+    output: z.object({
+        schema: z.unknown().optional(),
+        formatters: z.object({ plain: fn, llm: fn, json: fn }),
+    }),
+    examples: z
+        .array(z.object({ cmd: z.string(), note: z.string().optional() }))
+        .optional(),
+    disclosure: z
+        .object({ levels: z.array(z.string()), default: z.string() })
+        .optional(),
+    capability: capabilitySchema,
+    run: fn,
+    errors: z.array(z.object({ code: z.string(), when: z.string() })).optional(),
+    hidden: z.boolean().optional(),
+});
+const moduleSchema = z.object({
+    name: z.string().min(1),
+    verbs: z.array(verbSpecSchema).min(1),
+    boot: fn.optional(),
+});
+/**
+ * Validate a capability module against the grammar, throwing on the first
+ * malformation.
+ *
+ * @param module - The capability module to validate.
+ * @throws Error describing the first schema violation.
+ */
+export function validateModule(module) {
+    const result = moduleSchema.safeParse(module);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue?.path.join(".") ?? "<root>";
+        throw new Error(`invalid capability module "${module?.name ?? "?"}" at ${path}: ${issue?.message ?? "unknown error"}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/src/kernel/spec/validate.js.map

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

package/dist/src/kernel/vocabulary.js

@@ -0,0 +1,97 @@
+/**
+ * The domain vocabulary this distribution declares, validated once at load.
+ *
+ * The kernel reads a graph whose vocabulary it must not name. Two of its reads
+ * need domain terms: the pack index projects an alternative-name property into
+ * `altNames` (what a family is addressed by, hence what completes and what a
+ * lookup resolves), and the MCP prompt surface materializes prompt entities
+ * with a generated SELECT. Both take their terms from here, and the bundled
+ * capability packs that query the same terms read the same declaration — so
+ * complete and resolve cannot drift apart.
+ *
+ * A DISTRIBUTION DECLARATION, not a config layer field, and deliberately so.
+ * Both readers sit where the config layer is unreachable: the storeless
+ * `__complete` fast path builds a completion ref at module load, and the index
+ * is built inside the pack builder. Made layerable, a user setting it in their
+ * project config would change nothing anywhere — silence, which is the exact
+ * failure a dead config field is. A fork ships its own binary: it edits the
+ * declaration and rebuilds.
+ *
+ * Terms must be PREFIXED NAMES whose prefix the distribution BINDS, and
+ * {@link parseVocabulary} rejects anything else by name. They are interpolated
+ * into SPARQL, where an absolute IRI written bare is a parse error and an
+ * unbound prefix is either a parse error or a silently empty result — and a
+ * failed read is indistinguishable from an empty graph, which is how a
+ * malformed declaration would otherwise surface as "this distribution has no
+ * prompts". Both halves matter: rejecting the shape alone still lets a
+ * one-character typo (`ds:name` → `dss:name`) pass startup and then drop every
+ * `altNames` from the index while reporting a built store as unbuilt. Failing
+ * at module load is correct for a compiled-in build defect: the distribution
+ * config's own layer validation (`config/defaults.ts`) already throws the same
+ * way.
+ *
+ * Standard vocabulary (`rdfs:label`, `rdfs:comment`) is deliberately absent —
+ * it is the same in every graph, and the index already treats it as universal.
+ */
+import conf, { vocabulary } from "../../pragma.conf.js";
+import { PragmaError } from "./error/PragmaError.js";
+/** A prefixed name — `prefix:local`, the only form a generated query can read. */
+const PREFIXED_NAME = /^[A-Za-z][A-Za-z0-9_-]*:[A-Za-z_][A-Za-z0-9_.-]*$/;
+/**
+ * The distribution config file, quoted in the diagnostics.
+ *
+ * The literal, not `${BIN_NAME}.conf.ts`: the import above names this file, and
+ * so do four other modules, so a fork CANNOT rename it — deriving the name from
+ * the fork's would send its maintainer to a path that is not on disk.
+ * `config/defaults.ts` names the same file for the same reason.
+ */
+const CONF_FILE = "pragma.conf.ts";
+/**
+ * Hold one declared term to a form a generated query can actually read: the
+ * `prefix:local` shape, AND a prefix the distribution binds.
+ *
+ * @param field - The term's path in the declaration, for the message.
+ * @param term - The declared value.
+ * @param prefixes - The distribution's declared namespace bindings.
+ * @param source - The file the declaration was read from.
+ * @throws PragmaError CONFIG_ERROR when the term is not `prefix:local`, or
+ *   names a prefix `prefixes` does not bind.
+ */
+function assertReadableTerm(field, term, prefixes, source) {
+    const reject = (problem, fix) => {
+        throw PragmaError.configError(`Invalid vocabulary in ${source}: \`${field}\` ${problem}, not ${JSON.stringify(term)}.`, { recovery: { message: `In ${source}, ${fix}` } });
+    };
+    if (!PREFIXED_NAME.test(term)) {
+        reject("must be a prefixed name like `ex:thing`", `write \`${field}\` as \`<prefix>:<local>\`. These terms are interpolated into queries, which cannot read an absolute IRI here.`);
+    }
+    const prefix = term.slice(0, term.indexOf(":"));
+    if (!Object.hasOwn(prefixes, prefix)) {
+        reject(`must use a prefix \`prefixes\` binds, and nothing binds \`${prefix}:\``, `either bind \`${prefix}\` under \`prefixes\` or write \`${field}\` with a prefix that is bound. An unbound prefix makes the generated query fail, which a read cannot tell apart from an empty graph.`);
+    }
+}
+/**
+ * Validate a declared vocabulary.
+ *
+ * @param raw - A distribution's `vocabulary` export.
+ * @param prefixes - That distribution's `prefixes`, which must bind every
+ *   prefix the terms use.
+ * @param source - The file it was declared in, quoted in errors.
+ * @returns The same declaration, once every term is readable.
+ * @throws PragmaError CONFIG_ERROR naming the offending field and its value.
+ */
+export function parseVocabulary(raw, prefixes, source) {
+    assertReadableTerm("altName", raw.altName, prefixes, source);
+    for (const [term, value] of Object.entries(raw.prompt)) {
+        assertReadableTerm(`prompt.${term}`, value, prefixes, source);
+    }
+    return raw;
+}
+/**
+ * This distribution's validated vocabulary.
+ *
+ * The declaration is type-checked at this call — a fork that drops or mistypes
+ * a term fails `tsc`, and one that writes an unreadable term fails here at
+ * startup rather than at the read that would have swallowed it.
+ */
+export const VOCABULARY = parseVocabulary(vocabulary, conf.prefixes ?? {}, CONF_FILE);
+//# sourceMappingURL=vocabulary.js.map

package/dist/src/kernel/vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../../src/kernel/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAwBrD,kFAAkF;AAClF,MAAM,aAAa,GAAG,mDAAmD,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CACzB,KAAa,EACb,IAAY,EACZ,QAA0C,EAC1C,MAAc;IAEd,MAAM,MAAM,GAAG,CAAC,OAAe,EAAE,GAAW,EAAS,EAAE;QACrD,MAAM,WAAW,CAAC,WAAW,CAC3B,yBAAyB,MAAM,OAAO,KAAK,MAAM,OAAO,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EACxF,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,MAAM,KAAK,GAAG,EAAE,EAAE,EAAE,CAClD,CAAC;IACJ,CAAC,CAAC;IACF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,CACJ,yCAAyC,EACzC,WAAW,KAAK,gHAAgH,CACjI,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,CACJ,6DAA6D,MAAM,KAAK,EACxE,iBAAiB,MAAM,oCAAoC,KAAK,uIAAuI,CACxM,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAuB,EACvB,QAA0C,EAC1C,MAAc;IAEd,kBAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,kBAAkB,CAAC,UAAU,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CACvC,UAAU,EACV,IAAI,CAAC,QAAQ,IAAI,EAAE,EACnB,SAAS,CACV,CAAC"}

package/dist/src/types.js

@@ -0,0 +1,11 @@
+/**
+ * Cross-cutting type re-exports for the public barrel.
+ *
+ * The kernel keeps its authoritative type definitions co-located with the
+ * modules that own them (spec grammar, config, error, runtime); this file is
+ * the single import hop the types-only `index.ts` barrel re-exports from, so
+ * the public surface never reaches into deep module paths. It grows one
+ * section per PR as each kernel layer lands.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}