@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/shared/mergeAndParseRefs.ts

@@ -0,0 +1,44 @@
+import {
+  type PackageRef,
+  parsePackageEntry,
+  type RawPackageEntry,
+} from "../refs/operations/parseRef.js";
+import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
+
+/**
+ * Merge config packages, global refs, and the built-in defaults into a
+ * final parsed `PackageRef` array.
+ *
+ * Priority: config `packages` > global `refs.json` > hardcoded defaults.
+ * A non-empty config list is a full replacement — only the listed packages
+ * resolve. An empty or absent list means "not configured": global refs are
+ * merged over the defaults by package name, so a global entry for
+ * "@canonical/foo" overrides the default entry for the same package.
+ *
+ * Kept free of store imports so config-only consumers (e.g.
+ * `resolveConfiguredGraphs`) can merge refs without loading the ke/WASM
+ * runtime.
+ *
+ * @note Impure — reads global refs from `~/.config/pragma/refs.json`.
+ *
+ * @param configPackages - The `packages` field from `pragma.config.json`.
+ * @returns Parsed refs ready for the loader chain.
+ * @throws PragmaError with code CONFIG_ERROR when an entry is malformed.
+ */
+export function mergeAndParseRefs(
+  configPackages?: ReadonlyArray<RawPackageEntry>,
+): PackageRef[] {
+  // A non-empty config list replaces the package set entirely.
+  if (configPackages && configPackages.length > 0) {
+    return configPackages.map((entry) => parsePackageEntry(entry));
+  }
+
+  // Empty or absent → merge global refs over the defaults, keyed by name.
+  const merged = new Map<string, RawPackageEntry>();
+  for (const entry of [...DEFAULT_PACKAGES, ...readGlobalRefs()]) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
+  }
+  return [...merged.values()].map((entry) => parsePackageEntry(entry));
+}

package/src/domains/shared/namespaces.ts

@@ -6,12 +6,20 @@
  */
 
 import { createNamespace } from "@canonical/ke";
-import { PREFIX_MAP } from "./prefixes.js";
+import { PREFIX_MAP, TRANSITIONAL_DS_PREFIX_MAP } from "./prefixes.js";
 
-/** Design system namespace — classes, properties, and instances (e.g., `ds:Component`). */
-export const ds = createNamespace(PREFIX_MAP.ds);
-/** Component specification namespace — component-level metadata (e.g., `cs:anatomy`). */
-export const cs = createNamespace(PREFIX_MAP.cs);
+/**
+ * Design system namespace — classes, properties, and instances (e.g., `ds:Component`).
+ * @remarks transitional — sourced from the bundled DS fallback until the
+ * design-system package declares its own prefixes (remove in P4).
+ */
+export const ds = createNamespace(TRANSITIONAL_DS_PREFIX_MAP.ds);
+/**
+ * Component specification namespace — component-level metadata (e.g., `cs:anatomy`).
+ * @remarks transitional — sourced from the bundled DS fallback until the
+ * code-standards package declares its own prefixes (remove in P4).
+ */
+export const cs = createNamespace(TRANSITIONAL_DS_PREFIX_MAP.cs);
 /** RDF Schema namespace — core vocabulary (e.g., `rdfs:label`, `rdfs:subClassOf`). */
 export const rdfs = createNamespace(PREFIX_MAP.rdfs);
 /** OWL namespace — ontology constructs (e.g., `owl:Class`, `owl:ObjectProperty`). */

package/src/domains/shared/packages.ts

@@ -1,27 +1,20 @@
 /**
  * Default semantic graph package registry.
  *
- * Defines the default graph packages loaded when no config overrides
- * are present. Each entry is a git ref pointing to the canonical
- * repository so `pragma update-refs` fetches data out of the box.
+ * Sourced from the declarative built-in defaults document
+ * (`src/config/defaults.json`) — pragma core carries no hardcoded
+ * knowledge of specific design-system packages. These form the base
+ * package set whenever a config layer does not declare a non-empty
+ * `packages` list; global `refs.json` entries then merge over them by
+ * package name, and a non-empty config list replaces them entirely
+ * (see `mergeAndParseRefs`).
  *
  * Resolution is handled by the loader chain in `loaders/`.
  */
 
+import { DEFAULT_CONFIG } from "../../config/defaultConfig.js";
 import type { RawPackageEntry } from "../refs/operations/parseRef.js";
 
 /** Default semantic graph packages loaded when no config overrides are present. */
-export const DEFAULT_PACKAGES: readonly RawPackageEntry[] = [
-  {
-    name: "@canonical/design-system",
-    source: "git+https://github.com/canonical/design-system.git#main",
-  },
-  {
-    name: "@canonical/anatomy-dsl",
-    source: "git+https://github.com/canonical/anatomy-dsl.git#main",
-  },
-  {
-    name: "@canonical/code-standards",
-    source: "git+https://github.com/canonical/web-code-standards.git#main",
-  },
-];
+export const DEFAULT_PACKAGES: readonly RawPackageEntry[] =
+  DEFAULT_CONFIG.packages;

package/src/domains/shared/parseSampleCount.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../../error/index.js";
+import parseSampleCount, {
+  DEFAULT_SAMPLE_COUNT,
+  MAX_SAMPLE_COUNT,
+  MIN_SAMPLE_COUNT,
+} from "./parseSampleCount.js";
+
+describe("parseSampleCount", () => {
+  it("returns the default for undefined/null/empty input", () => {
+    expect(parseSampleCount(undefined)).toBe(DEFAULT_SAMPLE_COUNT);
+    expect(parseSampleCount(null)).toBe(DEFAULT_SAMPLE_COUNT);
+    expect(parseSampleCount("")).toBe(DEFAULT_SAMPLE_COUNT);
+  });
+
+  it("accepts an in-range integer verbatim", () => {
+    expect(parseSampleCount("3")).toBe(3);
+    expect(parseSampleCount(4)).toBe(4);
+  });
+
+  it("clamps below the minimum and above the maximum", () => {
+    expect(parseSampleCount("0")).toBe(MIN_SAMPLE_COUNT);
+    expect(parseSampleCount("-3")).toBe(MIN_SAMPLE_COUNT);
+    expect(parseSampleCount("99")).toBe(MAX_SAMPLE_COUNT);
+  });
+
+  it("tolerates surrounding whitespace", () => {
+    expect(parseSampleCount(" 3 ")).toBe(3);
+  });
+
+  it.each([
+    "abc",
+    "3.5",
+    "0x5",
+    "1e1",
+    "3,4",
+    "NaN",
+    "Infinity",
+  ])("throws INVALID_INPUT for the non-integer value %j", (value) => {
+    expect(() => parseSampleCount(value)).toThrowError(PragmaError);
+    try {
+      parseSampleCount(value);
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+});

package/src/domains/shared/parseSampleCount.ts

@@ -0,0 +1,45 @@
+/**
+ * Parse and validate the `--count` argument shared by every `sample` command.
+ *
+ * A missing count falls back to the default. A non-numeric or non-integer
+ * value is rejected as invalid input (so the command exits non-zero) rather
+ * than silently coercing to `NaN` and returning zero samples. A valid integer
+ * is clamped to the supported 1–5 range.
+ */
+
+import { PragmaError } from "#error";
+
+/** Smallest number of samples a `sample` command will return. */
+export const MIN_SAMPLE_COUNT = 1;
+/** Largest number of samples a `sample` command will return. */
+export const MAX_SAMPLE_COUNT = 5;
+/** Number of samples returned when `--count` is omitted. */
+export const DEFAULT_SAMPLE_COUNT = 2;
+
+/**
+ * Resolve the raw `--count` param into a clamped sample count.
+ *
+ * @param raw - The raw param value (`params.count`), possibly undefined.
+ * @returns An integer in [MIN_SAMPLE_COUNT, MAX_SAMPLE_COUNT].
+ * @throws PragmaError INVALID_INPUT when `raw` is present but not an integer.
+ */
+export default function parseSampleCount(raw: unknown): number {
+  if (raw === undefined || raw === null || raw === "") {
+    return DEFAULT_SAMPLE_COUNT;
+  }
+
+  // Accept only a plain decimal integer. Number() would otherwise coerce hex
+  // ("0x5"), scientific ("1e1"), and whitespace-padded forms, none of which a
+  // user should be able to pass to --count.
+  const text = String(raw).trim();
+  if (!/^-?\d+$/.test(text)) {
+    throw PragmaError.invalidInput("count", String(raw), {
+      recovery: {
+        message: `Provide an integer between ${MIN_SAMPLE_COUNT} and ${MAX_SAMPLE_COUNT}.`,
+      },
+    });
+  }
+
+  const parsed = Number(text);
+  return Math.max(MIN_SAMPLE_COUNT, Math.min(MAX_SAMPLE_COUNT, parsed));
+}

package/src/domains/shared/prefixes.test.ts

@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  DEFAULT_PREFIX_MAP,
+  P,
+  PREFIX_MAP,
+  resolvePrefixes,
+  TRANSITIONAL_DS_PREFIX_MAP,
+  TTL_PREFIXES,
+} from "./prefixes.js";
+
+describe("core PREFIX_MAP", () => {
+  it("ships only generic RDF vocabularies — no design-system prefixes", () => {
+    expect(Object.keys(PREFIX_MAP).sort()).toEqual([
+      "owl",
+      "rdf",
+      "rdfs",
+      "skos",
+      "xsd",
+    ]);
+    expect(PREFIX_MAP).not.toHaveProperty("ds");
+    expect(PREFIX_MAP).not.toHaveProperty("cs");
+  });
+});
+
+describe("TRANSITIONAL_DS_PREFIX_MAP", () => {
+  it("bundles the design-system prefixes separately from the core", () => {
+    expect(TRANSITIONAL_DS_PREFIX_MAP).toEqual({
+      ds: "https://ds.canonical.com/",
+      cs: "http://pragma.canonical.com/codestandards#",
+    });
+  });
+});
+
+describe("DEFAULT_PREFIX_MAP (display set)", () => {
+  it("reproduces the pre-P0 compaction set — ds/cs plus rdfs/owl/skos", () => {
+    expect(Object.keys(DEFAULT_PREFIX_MAP).sort()).toEqual([
+      "cs",
+      "ds",
+      "owl",
+      "rdfs",
+      "skos",
+    ]);
+  });
+
+  it("omits rdf/xsd so URI compaction in output is unchanged", () => {
+    expect(DEFAULT_PREFIX_MAP).not.toHaveProperty("rdf");
+    expect(DEFAULT_PREFIX_MAP).not.toHaveProperty("xsd");
+  });
+});
+
+describe("P accessor", () => {
+  it("exposes prefixed-name accessors including the transitional ds/cs", () => {
+    expect(P.ds).toBe("ds:");
+    expect(P.cs).toBe("cs:");
+    expect(P.rdfs).toBe("rdfs:");
+    expect(P.owl).toBe("owl:");
+    expect(P.skos).toBe("skos:");
+  });
+});
+
+describe("TTL_PREFIXES", () => {
+  it("declares every display prefix plus xsd", () => {
+    expect(TTL_PREFIXES).toContain("@prefix ds: <https://ds.canonical.com/> .");
+    expect(TTL_PREFIXES).toContain(
+      "@prefix cs: <http://pragma.canonical.com/codestandards#> .",
+    );
+    expect(TTL_PREFIXES).toContain(
+      "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
+    );
+  });
+});
+
+describe("resolvePrefixes", () => {
+  it("returns core plus the transitional DS fallback for a bare core", () => {
+    const resolved = resolvePrefixes([]);
+    expect(resolved).toEqual({ ...PREFIX_MAP, ...TRANSITIONAL_DS_PREFIX_MAP });
+  });
+
+  it("layers package-declared prefixes over the fallback", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { ex: "https://example.org/" } },
+    ]);
+    expect(resolved.ex).toBe("https://example.org/");
+    // core + fallback still present
+    expect(resolved.ds).toBe(TRANSITIONAL_DS_PREFIX_MAP.ds);
+    expect(resolved.rdf).toBe(PREFIX_MAP.rdf);
+  });
+
+  it("lets a package override the transitional DS fallback", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { ds: "https://packaged-ds.example/" } },
+    ]);
+    expect(resolved.ds).toBe("https://packaged-ds.example/");
+  });
+
+  it("lets config prefixes win over both packages and the fallback", () => {
+    const resolved = resolvePrefixes(
+      [{ prefixes: { ds: "https://packaged-ds.example/" } }],
+      { ds: "https://config-ds.example/" },
+    );
+    expect(resolved.ds).toBe("https://config-ds.example/");
+  });
+
+  it("merges multiple packages in array order", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { a: "https://one.example/" } },
+      { prefixes: { a: "https://two.example/", b: "https://b.example/" } },
+    ]);
+    expect(resolved.a).toBe("https://two.example/");
+    expect(resolved.b).toBe("https://b.example/");
+  });
+
+  it("tolerates packages that declare no prefixes", () => {
+    const resolved = resolvePrefixes([{}, { prefixes: undefined }]);
+    expect(resolved).toEqual({ ...PREFIX_MAP, ...TRANSITIONAL_DS_PREFIX_MAP });
+  });
+});
+
+describe("resolvePrefixes — injection & shadowing hardening", () => {
+  let warnings: string[];
+  let write: typeof process.stderr.write;
+
+  beforeEach(() => {
+    warnings = [];
+    write = process.stderr.write;
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      warnings.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+  });
+
+  afterEach(() => {
+    process.stderr.write = write;
+  });
+
+  it("drops a namespace that could break out of the SPARQL IRIREF", () => {
+    // A `>` would close `<...>` early and inject arbitrary SPARQL into every
+    // query the store runs.
+    const resolved = resolvePrefixes([
+      { prefixes: { evil: "http://e> SELECT * WHERE {?s ?p ?o} #" } },
+    ]);
+    expect(resolved).not.toHaveProperty("evil");
+    expect(warnings.join("")).toContain("not valid in an IRI");
+  });
+
+  it("rejects namespaces containing whitespace or angle/quote/brace chars", () => {
+    const resolved = resolvePrefixes([
+      {
+        prefixes: {
+          space: "http://e /x",
+          quote: 'http://e"x',
+          brace: "http://e{x}",
+        },
+      },
+    ]);
+    expect(resolved).not.toHaveProperty("space");
+    expect(resolved).not.toHaveProperty("quote");
+    expect(resolved).not.toHaveProperty("brace");
+  });
+
+  it("keeps a clean namespace untouched", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { ex: "https://example.org/ns#" } },
+    ]);
+    expect(resolved.ex).toBe("https://example.org/ns#");
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("refuses to let a package redefine a reserved core prefix", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { rdf: "https://evil.example/rdf#" } },
+    ]);
+    expect(resolved.rdf).toBe(PREFIX_MAP.rdf);
+    expect(warnings.join("")).toContain("reserved");
+  });
+
+  it("refuses reserved prefixes from config too", () => {
+    const resolved = resolvePrefixes([], { owl: "https://evil.example/owl#" });
+    expect(resolved.owl).toBe(PREFIX_MAP.owl);
+  });
+
+  it("skips a malformed prefix name", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { "bad name!": "https://example.org/" } },
+    ]);
+    expect(resolved).not.toHaveProperty("bad name!");
+    expect(warnings.join("")).toContain("not a valid prefix name");
+  });
+
+  it("warns on a last-wins collision between two packages", () => {
+    const resolved = resolvePrefixes([
+      { prefixes: { a: "https://one.example/" } },
+      { prefixes: { a: "https://two.example/" } },
+    ]);
+    expect(resolved.a).toBe("https://two.example/");
+    expect(warnings.join("")).toContain("overrides an earlier declaration");
+  });
+
+  it("names the declaring package in collision warnings when available", () => {
+    resolvePrefixes([
+      { name: "@canonical/one", prefixes: { a: "https://one.example/" } },
+      { name: "@canonical/two", prefixes: { a: "https://two.example/" } },
+    ]);
+    expect(warnings.join("")).toContain('package "@canonical/two"');
+  });
+
+  it("does not warn when a package overrides the trusted DS fallback", () => {
+    resolvePrefixes([{ prefixes: { ds: "https://packaged-ds.example/" } }]);
+    expect(warnings).toHaveLength(0);
+  });
+});

package/src/domains/shared/prefixes.ts

@@ -1,37 +1,204 @@
 /**
- * Prefix map for ke store creation.
+ * Prefix maps for ke store creation and display compaction.
  *
- * Registered as PREFIX declarations in every SPARQL query.
- * Single source of truth — rename a key here and P updates automatically.
+ * The core ships only generic RDF vocabularies. Domain prefixes (e.g. the
+ * design system's `ds:`/`cs:`) are supplied by the loaded semantic
+ * packages and merged over the core at boot via {@link resolvePrefixes}.
+ * Renaming a key here updates every derived accessor automatically.
  */
 
 import type { PrefixMap } from "@canonical/ke";
 
+/**
+ * Core prefix map — the generic RDF vocabularies pragma itself ships.
+ *
+ * Registered as PREFIX declarations in every SPARQL query and used as the
+ * base of the effective prefix map. Contains no domain-specific prefixes:
+ * `ds:`/`cs:` and any other package namespaces arrive from the resolved
+ * semantic packages (see {@link resolvePrefixes}).
+ */
 export const PREFIX_MAP = {
-  ds: "https://ds.canonical.com/",
-  cs: "http://pragma.canonical.com/codestandards#",
+  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   owl: "http://www.w3.org/2002/07/owl#",
   skos: "http://www.w3.org/2004/02/skos/core#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
 } as const satisfies PrefixMap;
 
 /**
- * SPARQL prefix accessors derived from {@link PREFIX_MAP}.
+ * Transitional design-system prefixes bundled with the core.
+ *
+ * @remarks transitional — remove in P4. These belong to the
+ * `@canonical/design-system` and `@canonical/code-standards` packages and
+ * must move into their own prefix declarations. Until those packages
+ * declare `pragma.prefixes`, this bundled fallback keeps existing DS
+ * queries resolving and DS IRIs compacting in output. Package-declared
+ * prefixes (and config overrides) win over this fallback.
+ */
+export const TRANSITIONAL_DS_PREFIX_MAP = {
+  ds: "https://ds.canonical.com/",
+  cs: "http://pragma.canonical.com/codestandards#",
+} as const satisfies PrefixMap;
+
+/**
+ * The default display/compaction prefix set and the base of the derived
+ * accessors — the exact set compacted before P0 split the core from the
+ * design system, kept stable during the transition.
+ *
+ * Deliberately omits `rdf:`/`xsd:` (present in {@link PREFIX_MAP}) so URI
+ * compaction in output is unchanged from pre-P0 behavior; the store's
+ * query prefix map (see {@link resolvePrefixes}) still carries them.
+ *
+ * @remarks transitional — the `ds:`/`cs:` members move to their packages
+ * in P4, at which point this collapses toward {@link PREFIX_MAP}. Runtime
+ * code should prefer the map from {@link resolvePrefixes}, which layers in
+ * package-declared and config prefixes over the store base.
+ */
+export const DEFAULT_PREFIX_MAP = {
+  ds: TRANSITIONAL_DS_PREFIX_MAP.ds,
+  cs: TRANSITIONAL_DS_PREFIX_MAP.cs,
+  rdfs: PREFIX_MAP.rdfs,
+  owl: PREFIX_MAP.owl,
+  skos: PREFIX_MAP.skos,
+} as const satisfies PrefixMap;
+
+/**
+ * Core prefixes reserved for pragma's own vocabularies. Packages and config
+ * may not redefine these — every query and the RDF/OWL/SKOS toolchain depend
+ * on them resolving to the canonical W3C namespaces, so a package that shadows
+ * `rdf:` (accidentally or maliciously) would silently corrupt every query.
+ */
+const RESERVED_PREFIXES: ReadonlySet<string> = new Set(Object.keys(PREFIX_MAP));
+
+/** A syntactically safe SPARQL prefix name (PN_PREFIX subset we accept). */
+const SAFE_PREFIX_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+/**
+ * Reject a namespace that cannot appear inside a SPARQL `<IRIREF>` unescaped.
+ * ke injects prefixes verbatim as `PREFIX name: <iri>`; a namespace containing
+ * `>` (or whitespace/control/`<"{}|^`\``) would break out of the IRI and inject
+ * arbitrary SPARQL into every query. SPARQL's IRIREF grammar forbids exactly
+ * these, so anything matching is both unsafe and invalid Turtle/SPARQL.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: IRIREF forbids U+0000–U+0020 by grammar
+const UNSAFE_NAMESPACE = /[\x00-\x20<>"{}|^`\\]/;
+
+/**
+ * Validate and merge one source of declared prefixes onto an accumulator.
+ *
+ * Skips (with a stderr warning) any entry that is unsafe to inject: a
+ * malformed prefix name, a namespace that could break out of the SPARQL
+ * IRIREF, or an attempt to redefine a reserved core prefix. Also warns when a
+ * later source silently overrides an already-declared prefix (last-wins
+ * collision), so a name clash between two packages is visible rather than
+ * mysterious.
+ *
+ * @note Impure — writes warnings to stderr.
+ */
+function mergePrefixSource(
+  acc: Record<string, string>,
+  claimed: Set<string>,
+  source: Readonly<Record<string, string>> | undefined,
+  origin: string,
+): void {
+  if (!source) return;
+  for (const [name, namespace] of Object.entries(source)) {
+    if (!SAFE_PREFIX_NAME.test(name)) {
+      process.stderr.write(
+        `Warning: ignoring prefix "${name}" from ${origin} — not a valid prefix name.\n`,
+      );
+      continue;
+    }
+    if (RESERVED_PREFIXES.has(name)) {
+      process.stderr.write(
+        `Warning: ignoring prefix "${name}" from ${origin} — "${name}:" is reserved for a core RDF vocabulary and cannot be redefined.\n`,
+      );
+      continue;
+    }
+    if (UNSAFE_NAMESPACE.test(namespace)) {
+      process.stderr.write(
+        `Warning: ignoring prefix "${name}" from ${origin} — namespace contains characters that are not valid in an IRI.\n`,
+      );
+      continue;
+    }
+    // Warn only on a collision between two *validated* sources (package vs.
+    // package/config). Silently overriding the trusted DS fallback is the
+    // expected transitional handoff, not a clash.
+    if (claimed.has(name) && acc[name] !== namespace) {
+      process.stderr.write(
+        `Warning: prefix "${name}" from ${origin} overrides an earlier declaration (was <${acc[name]}>, now <${namespace}>).\n`,
+      );
+    }
+    acc[name] = namespace;
+    claimed.add(name);
+  }
+}
+
+/**
+ * Resolve the effective prefix map for a boot.
+ *
+ * Precedence (lowest → highest): the generic {@link PREFIX_MAP}, the
+ * transitional DS fallback, prefixes declared by resolved packages (in
+ * array order), then config-level overrides. A package that declares its
+ * own `ds:`/`cs:` therefore overrides the bundled fallback, and a user's
+ * `pragma.config.json` `prefixes` wins over everything.
+ *
+ * Package- and config-declared prefixes are validated before they reach the
+ * store: unsafe names/namespaces are skipped (they would otherwise be injected
+ * verbatim into every SPARQL query), reserved core prefixes cannot be
+ * redefined, and last-wins collisions are surfaced as warnings. The bundled
+ * core and DS fallback are trusted and merged as-is.
+ *
+ * @param packages - Resolved packages, each optionally declaring prefixes.
+ * @param configPrefixes - Config-level prefix overrides.
+ * @returns The merged prefix map for the store and every query.
+ */
+export function resolvePrefixes(
+  packages: readonly {
+    readonly name?: string;
+    readonly prefixes?: Readonly<Record<string, string>>;
+  }[] = [],
+  configPrefixes?: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const merged: Record<string, string> = {
+    ...PREFIX_MAP,
+    ...TRANSITIONAL_DS_PREFIX_MAP,
+  };
+  // Keys claimed by a validated source, so collisions between two such
+  // sources warn while overriding the trusted seed stays silent.
+  const claimed = new Set<string>();
+  for (const pkg of packages) {
+    // Name the declaring package in the origin so collision/injection
+    // warnings point at the actual source, not a generic placeholder.
+    const origin = pkg.name ? `package "${pkg.name}"` : "a semantic package";
+    mergePrefixSource(merged, claimed, pkg.prefixes, origin);
+  }
+  mergePrefixSource(merged, claimed, configPrefixes, "pragma.config.json");
+  return merged;
+}
+
+/**
+ * SPARQL prefix accessors derived from {@link DEFAULT_PREFIX_MAP}.
  *
  * Use in query templates: `${P.ds}Component` → `"ds:Component"`.
- * Renaming a key in PREFIX_MAP automatically updates every query.
+ * Renaming a key in the underlying maps automatically updates every query.
+ *
+ * @remarks The `ds:`/`cs:` accessors are transitional (see
+ * {@link TRANSITIONAL_DS_PREFIX_MAP}); they resolve at query time against
+ * the store's merged prefix map, which the packages now supply.
  */
 export const P = Object.fromEntries(
-  Object.keys(PREFIX_MAP).map((k) => [k, `${k}:`]),
-) as { readonly [K in keyof typeof PREFIX_MAP]: `${K}:` };
+  Object.keys(DEFAULT_PREFIX_MAP).map((k) => [k, `${k}:`]),
+) as { readonly [K in keyof typeof DEFAULT_PREFIX_MAP]: `${K}:` };
 
 /**
- * Turtle `@prefix` declarations derived from {@link PREFIX_MAP}.
- *
- * Includes `xsd:` which TTL data files commonly use but SPARQL queries
- * don't need (ke auto-injects PREFIX_MAP for queries).
+ * Turtle `@prefix` declarations derived from {@link DEFAULT_PREFIX_MAP},
+ * plus `xsd:` — commonly used by TTL data files but omitted from the
+ * display set (SPARQL queries auto-inject the store prefix map).
  */
 export const TTL_PREFIXES = [
-  ...Object.entries(PREFIX_MAP).map(([k, uri]) => `@prefix ${k}: <${uri}> .`),
-  "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
+  ...Object.entries(DEFAULT_PREFIX_MAP).map(
+    ([k, uri]) => `@prefix ${k}: <${uri}> .`,
+  ),
+  `@prefix xsd: <${PREFIX_MAP.xsd}> .`,
 ].join("\n");

package/src/domains/shared/renderers.ts

@@ -13,7 +13,7 @@ import type {
   RenderLookupOptions,
   SectionDef,
 } from "./contracts.js";
-import { PREFIX_MAP } from "./prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
 
 type RenderMode = "plain" | "llm";
 
@@ -21,7 +21,7 @@ export function renderListPlain<T>(
   items: readonly T[],
   options: RenderListOptions<T>,
 ): string {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
   const rows = items.map((item) =>
     options.columns
       .map((column) => ({
@@ -52,7 +52,7 @@ export function renderListLlm<T>(
   items: readonly T[],
   options: RenderListOptions<T>,
 ): string {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
   const lines = [`## ${options.heading} (${items.length})`, ""];
 
   for (const item of items) {
@@ -121,7 +121,7 @@ function renderLookupFields<T>(
   options: RenderLookupOptions<T>,
   mode: RenderMode,
 ): string[] {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
   return options.fields.flatMap((field) => {
     const value = field.value(entity);
     if (isEmptyValue(value)) {
@@ -173,7 +173,7 @@ function renderSectionValue<T>(
   options: RenderLookupOptions<T>,
   mode: RenderMode,
 ): string | null {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
 
   switch (section.kind) {
     case "field":