@intentset/core 0.1.0

package/src/carrier.ts

@@ -0,0 +1,81 @@
+/**
+ * The plain-Markdown carrier (Core §3, §9; ADR 0003).
+ *
+ * `plainCarrier` produces the `DocumentInput` shape from nothing but the
+ * text: the frontmatter between the `---` fences at the top of the file, and
+ * the ATX headings that lie outside fenced code blocks. The Markset adapter
+ * produces the same shape from the Markset AST; a test holds the two equal.
+ * This carrier emits no syntax diagnostics: plain Markdown has no grammar to
+ * fail, and an unclosed fence or missing frontmatter is reported by
+ * `readArtifact` as CORE001.
+ */
+import type { DocumentInput, Heading } from "./types.ts";
+
+/** Core §3 and §9: the plain-Markdown fallback carrier. */
+export function plainCarrier(path: string, source: string): DocumentInput {
+  const text = source.startsWith("") ? source.slice(1) : source;
+  const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+  const frontmatter = findFrontmatter(lines);
+  const bodyStart = frontmatter === null ? 0 : frontmatter.close + 1;
+  return {
+    path,
+    source,
+    frontmatter: frontmatter === null ? null : { text: frontmatter.text, line: 2 },
+    headings: collectHeadings(lines, bodyStart),
+    syntax: [],
+  };
+}
+
+/** Core §3: the 0-based index of the closing frontmatter fence of a document that starts with one, or -1. */
+export function closingFenceIndex(lines: readonly string[]): number {
+  if (lines.length === 0 || lines[0].trimEnd() !== "---") return -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trimEnd() === "---") return i;
+  }
+  return -1;
+}
+
+function findFrontmatter(lines: string[]): { text: string; close: number } | null {
+  const close = closingFenceIndex(lines);
+  if (close === -1) return null;
+  return { text: lines.slice(1, close).join("\n"), close };
+}
+
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const ATX = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*$/;
+
+/** Core §6 and ADR 0003: ATX headings outside fenced code blocks, with inline markup removed. */
+export function collectHeadings(lines: readonly string[], from: number): Heading[] {
+  const headings: Heading[] = [];
+  let fence: { char: string; length: number } | null = null;
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i];
+    if (fence !== null) {
+      const close = new RegExp(`^ {0,3}\\${fence.char}{${fence.length},}[ \\t]*$`);
+      if (close.test(line)) fence = null;
+      continue;
+    }
+    const open = FENCE_OPEN.exec(line);
+    if (open !== null && !(open[1][0] === "`" && open[2].includes("`"))) {
+      fence = { char: open[1][0], length: open[1].length };
+      continue;
+    }
+    const atx = ATX.exec(line);
+    if (atx === null) continue;
+    headings.push({ depth: atx[1].length, text: headingText(atx[2] ?? ""), line: i + 1 });
+  }
+  return headings;
+}
+
+/** Core §6 and ADR 0003: the plain text of a heading, closing `#`s, emphasis, code spans and link brackets removed. */
+export function headingText(raw: string): string {
+  let text = raw.trim();
+  if (/^#+$/.test(text)) return "";
+  text = text.replace(/[ \t]+#+$/, "");
+  text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+  text = text.replace(/\[([^\]]*)\]/g, "$1");
+  text = text.replace(/[*`]/g, "");
+  text = text.replace(/(^|\s)_+|_+(?=\s|$)/g, "$1");
+  text = text.replace(/\\([\\`*_{}[\]()#+\-.!])/g, "$1");
+  return text.replace(/\s+/g, " ").trim();
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+/**
+ * `.intentset/config.yaml` (Core §11: a conformance claim names its declared
+ * repository scope). `repository` is the stable identity the export carries;
+ * `scope` is the globs that select documents; `registries` is the path of
+ * registries.yaml or null; `ignore` excludes generated output. A bad shape is
+ * CFG001 and the defaults stand in, so a caller always gets a usable config.
+ */
+import type { Diagnostic } from "./diagnostics.ts";
+import { compareStrings, makeDiagnostic } from "./report.ts";
+import { patternProblem } from "./validate.ts";
+import type { Config } from "./types.ts";
+import { parseYamlDetailed } from "./yaml.ts";
+
+export const DEFAULT_SCOPE = ["**/*.md"];
+export const DEFAULT_IGNORE = ["node_modules/**", "dist/**", ".git/**"];
+const KNOWN_KEYS = ["repository", "scope", "registries", "ignore"];
+
+/** Core §11: read the repository configuration. Shape problems are CFG001. */
+export function readConfig(text: string, path: string): { config: Config; diagnostics: Diagnostic[] } {
+  const diagnostics: Diagnostic[] = [];
+  const config: Config = { repository: "", scope: [...DEFAULT_SCOPE], registries: null, ignore: [...DEFAULT_IGNORE] };
+  const parsed = parseYamlDetailed(text);
+  if (parsed.error) {
+    diagnostics.push(
+      makeDiagnostic({
+        code: "CFG001",
+        origin: "profile",
+        artifact: null,
+        path,
+        location: { line: parsed.error.line },
+        message: `The configuration does not parse: ${parsed.error.message}`,
+        remediation: "Write the configuration as a block mapping with repository, scope, registries and ignore.",
+      }),
+    );
+    return { config, diagnostics };
+  }
+  const root = parsed.value;
+  const report = (field: string, message: string, remediation: string) => {
+    const line = parsed.lines.get(field);
+    diagnostics.push(
+      makeDiagnostic({
+        code: "CFG001",
+        origin: "profile",
+        artifact: null,
+        path,
+        ...(line !== undefined ? { location: { line } } : {}),
+        field,
+        message,
+        remediation,
+      }),
+    );
+  };
+
+  for (const key of Object.keys(root).sort(compareStrings)) {
+    if (!KNOWN_KEYS.includes(key)) {
+      report(`/${key}`, `Unknown configuration key \`${key}\`.`, `Remove it; the keys are ${KNOWN_KEYS.join(", ")}.`);
+    }
+  }
+  if (typeof root.repository === "string" && root.repository !== "") {
+    config.repository = root.repository;
+  } else {
+    report(
+      "/repository",
+      "`repository` is required and must be a non-empty string.",
+      'Set it to the repository\'s stable identity, such as "org/name".',
+    );
+  }
+  for (const key of ["scope", "ignore"] as const) {
+    const value = root[key];
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string" && item !== "")) {
+      config[key] = [...(value as string[])];
+      for (const [index, pattern] of (value as string[]).entries()) {
+        const why = patternProblem(pattern);
+        if (why !== null) {
+          report(
+            `/${key}/${index}`,
+            `${key} pattern ${JSON.stringify(pattern)} is not a supported pattern: ${why}`,
+            "Use repository-relative POSIX paths with literal segments, * within a segment and ** across segments.",
+          );
+        }
+      }
+    } else {
+      report(
+        `/${key}`,
+        `\`${key}\` must be a list of glob strings.`,
+        `Write ${key} as a sequence of patterns such as "**/*.md".`,
+      );
+    }
+  }
+  if (root.registries !== undefined && root.registries !== null) {
+    if (typeof root.registries === "string" && root.registries !== "") config.registries = root.registries;
+    else report("/registries", "`registries` must be a path or null.", "Point it at registries.yaml, or remove it.");
+  }
+  return { config, diagnostics };
+}

package/src/context.ts

@@ -0,0 +1,240 @@
+/**
+ * Agent context (Core §10): the bounded set of artifacts an engineer or an
+ * agent loads before changing implementation, starting from one ID.
+ *
+ *   behavior    its owning slices (the derived side of `implements`), the
+ *               behavior, its rules (`governedBy`), the scenarios that
+ *               illustrate it, the verifications over it, its rules and its
+ *               scenarios, the owning slices' exposed and consumed contracts,
+ *               the decisions informing the behavior, the slices and the
+ *               contracts, the knowledge explaining it, and its parent chain
+ *   rule        the behaviors it governs, and from each of their bundles the
+ *               owning slices and the verifications; also the verifications
+ *               and knowledge naming the rule itself, so a rule no behavior
+ *               governs yet still shows what checks and explains it
+ *   capability  the bundles of its behaviors (children through `parent`,
+ *               through sub-capabilities, with a visited set), merged, plus
+ *               the knowledge explaining it and its own parent chain
+ *   slice       the bundles of the behaviors it implements, merged, plus its
+ *               own contracts and the decisions informing it and them
+ *   otherwise   the artifact and its direct neighbours, authored and derived
+ *
+ * Each artifact appears once, under the first role it has in role order, and
+ * the bundle is sorted by role then ID. `restricted` artifacts, the start
+ * included, are withheld and counted unless asked for, so a short context
+ * never reads as a complete one. Only IDs in the graph are followed; an
+ * unresolved edge is the validator's to report. Pure and deterministic: the
+ * result depends on the graph's artifacts and edges, not on file order.
+ */
+import { compareStrings } from "./report.ts";
+import type { ArtifactType, Graph, LinkKind, Status, Visibility } from "./types.ts";
+
+/** The roles an artifact can have in a bundle, in the order a bundle is sorted by. */
+export const CONTEXT_ROLES = [
+  "start",
+  "owner",
+  "behavior",
+  "rule",
+  "scenario",
+  "verification",
+  "contract",
+  "decision",
+  "knowledge",
+  "ancestor",
+  "neighbour",
+] as const;
+export type ContextRole = (typeof CONTEXT_ROLES)[number];
+
+export interface ContextArtifact {
+  id: string;
+  type: ArtifactType;
+  title: string;
+  status: Status;
+  visibility: Visibility;
+  /** Repository-relative path of the artifact's file. */
+  path: string;
+  role: ContextRole;
+}
+
+export interface ContextBundle {
+  start: string;
+  /** Sorted by role order, then ID. Each artifact once, under the first role it has in that order. */
+  artifacts: ContextArtifact[];
+  /** Restricted artifacts left out because they were not asked for. */
+  withheld: number;
+}
+
+export interface ContextOptions {
+  /** Include `restricted` artifacts instead of withholding them. Default false. */
+  includeRestricted?: boolean;
+}
+
+const RANK = new Map<ContextRole, number>(CONTEXT_ROLES.map((role, index) => [role, index]));
+
+/** Core §10: the bounded context of an artifact, or null when the graph has no artifact with this ID. */
+export function contextFor(graph: Graph, id: string, options: ContextOptions = {}): ContextBundle | null {
+  const start = graph.artifacts.get(id);
+  if (start === undefined) return null;
+  const roles = new Roles(graph);
+  roles.add(id, "start");
+
+  switch (start.meta.type) {
+    case "behavior":
+      behaviorBundle(graph, id, roles);
+      break;
+    case "rule":
+      for (const behavior of into(graph, id, "governedBy", "behavior")) {
+        roles.add(behavior, "behavior");
+        const bundle = new Roles(graph);
+        behaviorBundle(graph, behavior, bundle);
+        for (const [member, role] of bundle.entries()) {
+          if (role === "owner" || role === "verification") roles.add(member, role);
+        }
+      }
+      for (const verification of into(graph, id, "verifies", "verification")) roles.add(verification, "verification");
+      for (const knowledge of into(graph, id, "explains", "knowledge")) roles.add(knowledge, "knowledge");
+      break;
+    case "capability":
+      for (const behavior of behaviorsUnder(graph, id)) behaviorBundle(graph, behavior, roles);
+      for (const knowledge of into(graph, id, "explains", "knowledge")) roles.add(knowledge, "knowledge");
+      for (const ancestor of ancestors(graph, id)) roles.add(ancestor, "ancestor");
+      break;
+    case "slice": {
+      for (const behavior of from(graph, id, "implements", "behavior")) behaviorBundle(graph, behavior, roles);
+      const contracts = [...from(graph, id, "exposes", "contract"), ...from(graph, id, "consumes", "contract")];
+      for (const contract of contracts) roles.add(contract, "contract");
+      for (const source of [id, ...contracts]) {
+        for (const decision of from(graph, source, "informedBy", "decision")) roles.add(decision, "decision");
+      }
+      break;
+    }
+    default:
+      for (const edge of graph.out.get(id) ?? []) roles.add(edge.to, "neighbour");
+      for (const edge of graph.in.get(id) ?? []) roles.add(edge.from, "neighbour");
+      break;
+  }
+
+  const artifacts: ContextArtifact[] = [];
+  let withheld = 0;
+  for (const [member, role] of roles.entries()) {
+    const artifact = graph.artifacts.get(member);
+    if (artifact === undefined) continue;
+    const { meta } = artifact;
+    if (meta.visibility === "restricted" && options.includeRestricted !== true) {
+      withheld++;
+      continue;
+    }
+    artifacts.push({
+      id: meta.id,
+      type: meta.type,
+      title: meta.title,
+      status: meta.status,
+      visibility: meta.visibility,
+      path: artifact.path,
+      role,
+    });
+  }
+  artifacts.sort((a, b) => rank(a.role) - rank(b.role) || compareStrings(a.id, b.id));
+  return { start: id, artifacts, withheld };
+}
+
+/** Role assignment with "first role in role order wins", over IDs that are in the graph. */
+class Roles {
+  readonly #graph: Graph;
+  readonly #roles = new Map<string, ContextRole>();
+
+  constructor(graph: Graph) {
+    this.#graph = graph;
+  }
+
+  add(id: string, role: ContextRole): void {
+    if (!this.#graph.artifacts.has(id)) return;
+    const previous = this.#roles.get(id);
+    if (previous === undefined || rank(role) < rank(previous)) this.#roles.set(id, role);
+  }
+
+  /** Entries sorted by ID, so nothing downstream depends on insertion order. */
+  entries(): [string, ContextRole][] {
+    return [...this.#roles.entries()].sort((a, b) => compareStrings(a[0], b[0]));
+  }
+}
+
+function rank(role: ContextRole): number {
+  return RANK.get(role) ?? CONTEXT_ROLES.length;
+}
+
+/** One behavior's bundle, added into `roles`. */
+function behaviorBundle(graph: Graph, behavior: string, roles: Roles): void {
+  roles.add(behavior, "behavior");
+  const owners = into(graph, behavior, "implements", "slice");
+  const rules = from(graph, behavior, "governedBy", "rule");
+  const scenarios = into(graph, behavior, "illustrates", "scenario");
+  const contracts = owners.flatMap((slice) => [
+    ...from(graph, slice, "exposes", "contract"),
+    ...from(graph, slice, "consumes", "contract"),
+  ]);
+  for (const slice of owners) roles.add(slice, "owner");
+  for (const rule of rules) roles.add(rule, "rule");
+  for (const scenario of scenarios) roles.add(scenario, "scenario");
+  for (const claim of [behavior, ...rules, ...scenarios]) {
+    for (const verification of into(graph, claim, "verifies", "verification")) roles.add(verification, "verification");
+  }
+  for (const contract of contracts) roles.add(contract, "contract");
+  for (const source of [behavior, ...owners, ...contracts]) {
+    for (const decision of from(graph, source, "informedBy", "decision")) roles.add(decision, "decision");
+  }
+  for (const knowledge of into(graph, behavior, "explains", "knowledge")) roles.add(knowledge, "knowledge");
+  for (const ancestor of ancestors(graph, behavior)) roles.add(ancestor, "ancestor");
+}
+
+/** Behaviors whose navigation parent is the capability or one of its sub-capabilities, with a visited set. */
+function behaviorsUnder(graph: Graph, capability: string): string[] {
+  const behaviors = new Set<string>();
+  const seen = new Set<string>([capability]);
+  const queue = [capability];
+  while (queue.length > 0) {
+    const current = queue.shift() as string;
+    for (const child of into(graph, current, "parent")) {
+      const type = graph.artifacts.get(child)?.meta.type;
+      if (type === "behavior") behaviors.add(child);
+      else if (type === "capability" && !seen.has(child)) {
+        seen.add(child);
+        queue.push(child);
+      }
+    }
+  }
+  return [...behaviors].sort(compareStrings);
+}
+
+/** The navigation parent chain, nearest first, stopping at a cycle or an ID not in the graph. */
+function ancestors(graph: Graph, id: string): string[] {
+  const chain: string[] = [];
+  const visited = new Set<string>([id]);
+  let cursor = graph.artifacts.get(id)?.meta.parent;
+  while (cursor !== undefined && !visited.has(cursor) && graph.artifacts.has(cursor)) {
+    visited.add(cursor);
+    chain.push(cursor);
+    cursor = graph.artifacts.get(cursor)?.meta.parent;
+  }
+  return chain;
+}
+
+/** Targets of authored edges of one kind leaving `id`, in the graph and of the given type, sorted and unique. */
+function from(graph: Graph, id: string, kind: LinkKind, type?: ArtifactType): string[] {
+  const ids = (graph.out.get(id) ?? []).filter((edge) => edge.kind === kind).map((edge) => edge.to);
+  return typed(graph, ids, type);
+}
+
+/** Sources of authored edges of one kind arriving at `id`: the derived side, read from the authored edge. */
+function into(graph: Graph, id: string, kind: LinkKind, type?: ArtifactType): string[] {
+  const ids = (graph.in.get(id) ?? []).filter((edge) => edge.kind === kind).map((edge) => edge.from);
+  return typed(graph, ids, type);
+}
+
+function typed(graph: Graph, ids: string[], type: ArtifactType | undefined): string[] {
+  const kept = ids.filter((each) => {
+    const artifact = graph.artifacts.get(each);
+    return artifact !== undefined && (type === undefined || artifact.meta.type === type);
+  });
+  return [...new Set(kept)].sort(compareStrings);
+}

package/src/diagnostics.ts

@@ -0,0 +1,60 @@
+/**
+ * One diagnostic shape across every package (ADR 0004, Core §11).
+ *
+ * `location` is present only when known; a missing location stays missing
+ * rather than becoming an invented coordinate. `field` is a JSON pointer into
+ * the frontmatter when the problem is a frontmatter value.
+ */
+export type Severity = "error" | "warning";
+
+export type Origin = "syntax" | "profile" | "graph" | "architecture" | "evidence" | "publication" | "render";
+
+export interface Location {
+  /** 1-based line in the file named by `path`. */
+  line: number;
+  /** 1-based column, when known. */
+  column?: number;
+}
+
+export interface Diagnostic {
+  /** Stable code, e.g. CORE003, VSA005, TS003, AMP001. */
+  code: string;
+  severity: Severity;
+  origin: Origin;
+  /** Artifact ID the problem belongs to, or null when the file has no readable ID. */
+  artifact: string | null;
+  /** Repository-relative POSIX path, or null for a repository-wide problem. */
+  path: string | null;
+  location?: Location;
+  /** JSON pointer into the frontmatter, e.g. "/intentset/links/governedBy/0". */
+  field?: string;
+  message: string;
+  remediation: string;
+}
+
+/** ADR 0004: true when any diagnostic is an error; warnings never fail a check. */
+export function hasErrors(diagnostics: readonly Diagnostic[]): boolean {
+  return diagnostics.some((d) => d.severity === "error");
+}
+
+/** Core §11 order: path, artifact ID, code; then line so output is total and deterministic. */
+export function compareDiagnostics(a: Diagnostic, b: Diagnostic): number {
+  return (
+    cmp(a.path ?? "", b.path ?? "") ||
+    cmp(a.artifact ?? "", b.artifact ?? "") ||
+    cmp(a.code, b.code) ||
+    (a.location?.line ?? 0) - (b.location?.line ?? 0) ||
+    (a.location?.column ?? 0) - (b.location?.column ?? 0) ||
+    cmp(a.field ?? "", b.field ?? "") ||
+    cmp(a.message, b.message)
+  );
+}
+
+/** Core §11 and ADR 0004: a sorted copy, in `compareDiagnostics` order. */
+export function sortDiagnostics<T extends Diagnostic>(diagnostics: readonly T[]): T[] {
+  return [...diagnostics].sort(compareDiagnostics);
+}
+
+function cmp(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/export.ts

@@ -0,0 +1,173 @@
+/**
+ * The export envelope (Core §12; the integration contract; spec/export.schema.json).
+ * Artifacts are sorted by ID and every list inside is sorted, so the same
+ * validation result with the same `generatedAt` is the same bytes. Bodies
+ * are included only when asked for.
+ */
+import { graphHash, sortKeysDeep } from "./hash.ts";
+import { compareStrings } from "./report.ts";
+import {
+  type Availability,
+  EXPORT_CONTRACT,
+  type ExportArtifact,
+  type ExportEnvelope,
+  LINK_KINDS,
+  type Level,
+  type LinkKind,
+  type Registries,
+  SPEC_VERSION,
+  type SliceMeta,
+  type ValidationResult,
+} from "./types.ts";
+
+/** What the caller knows and the validation result does not: identity, commit, scope, level, release. */
+export interface ExportMeta {
+  /** Stable identity of the repository, from config. */
+  repository: string;
+  /** The commit the export describes, or null with `commitUnavailable` saying why (a default reason is written when none is given). */
+  commit: string | null;
+  commitUnavailable?: string;
+  /** The scope globs validated; defaults to every Markdown file. */
+  scope?: string[];
+  /** The level the validation ran at; defaults to L1. */
+  level?: Level;
+  release?: { product: string; label: string } | null;
+  /** ISO 8601; defaults to now. Fix it to make two exports comparable byte for byte. */
+  generatedAt?: string;
+  includeBodies?: boolean;
+}
+
+/** Core §12 and the integration contract: the `intentset/export/0.1` envelope over a validation result. */
+export function exportGraph(result: ValidationResult, registries: Registries, meta: ExportMeta): ExportEnvelope {
+  const { graph } = result;
+  const ids = [...graph.artifacts.keys()].sort(compareStrings);
+  const errors = result.diagnostics.filter((d) => d.severity === "error").length;
+  const warnings = result.diagnostics.length - errors;
+  const source: ExportEnvelope["source"] = { commit: meta.commit };
+  if (meta.commit === null)
+    source.commitUnavailable = meta.commitUnavailable ?? "No commit was supplied to the export.";
+
+  return {
+    contract: EXPORT_CONTRACT,
+    spec: SPEC_VERSION,
+    generatedAt: meta.generatedAt ?? new Date().toISOString(),
+    repository: meta.repository,
+    products: ids.filter((id) => graph.artifacts.get(id)?.meta.type === "product"),
+    source,
+    graphHash: graphHash(graph),
+    release: meta.release ?? null,
+    validation: {
+      level: meta.level ?? "L1",
+      scope: [...(meta.scope ?? ["**/*.md"])],
+      status: result.ok ? "pass" : "fail",
+      errors,
+      warnings,
+      diagnostics: [...result.diagnostics],
+    },
+    registries: exportRegistries(registries),
+    artifacts: ids.map((id) => exportArtifact(result, id, meta.includeBodies === true)),
+  };
+}
+
+function exportArtifact(result: ValidationResult, id: string, includeBody: boolean): ExportArtifact {
+  const { graph } = result;
+  const artifact = graph.artifacts.get(id);
+  if (artifact === undefined) throw new Error(`graph has no artifact ${id}`);
+  const { meta } = artifact;
+
+  const links: ExportArtifact["links"] = {};
+  for (const kind of LINK_KINDS) {
+    if (kind === "parent") continue;
+    const list = meta.links[kind];
+    if (list !== undefined) links[kind] = [...list].sort(compareStrings);
+  }
+  const derived: ExportArtifact["derived"] = {};
+  const byKind = new Map<LinkKind, string[]>();
+  for (const edge of graph.in.get(id) ?? []) {
+    const list = byKind.get(edge.kind);
+    if (list === undefined) byKind.set(edge.kind, [edge.from]);
+    else list.push(edge.from);
+  }
+  for (const kind of LINK_KINDS) {
+    const list = byKind.get(kind);
+    if (list !== undefined) derived[kind] = [...new Set(list)].sort(compareStrings);
+  }
+
+  const exported: ExportArtifact = {
+    id,
+    type: meta.type,
+    title: meta.title,
+    status: meta.status,
+    owner: meta.owner,
+    visibility: meta.visibility,
+    audiences: [...meta.audiences].sort(compareStrings),
+    profile: meta.profile,
+    revision: meta.revision ?? null,
+    path: artifact.path,
+    sourceHash: artifact.sourceHash,
+    parent: meta.parent ?? null,
+    links,
+    derived,
+    availability: meta.availability === undefined ? null : sortedAvailability(meta.availability),
+    slice: meta.slice === undefined ? null : sortedSlice(meta.slice),
+    verification:
+      meta.verification === undefined
+        ? null
+        : {
+            method: meta.verification.method,
+            locator: meta.verification.locator,
+            selector: meta.verification.selector,
+          },
+    extensions: meta.extensions === undefined ? null : (sortKeysDeep(meta.extensions) as Record<string, unknown>),
+  };
+  if (includeBody) exported.body = artifact.body;
+  return exported;
+}
+
+function sortedAvailability(availability: Availability): Availability {
+  return {
+    products: [...availability.products].sort(compareStrings),
+    releases: [...availability.releases].sort(compareStrings),
+    roles: [...availability.roles].sort(compareStrings),
+    editions: [...availability.editions].sort(compareStrings),
+    flags: [...availability.flags].sort(compareStrings),
+  };
+}
+
+function sortedSlice(slice: SliceMeta): SliceMeta {
+  const layers: Record<string, string[]> = {};
+  for (const layer of Object.keys(slice.layers).sort(compareStrings)) {
+    layers[layer] = [...slice.layers[layer]].sort(compareStrings);
+  }
+  const out: SliceMeta = {
+    kind: slice.kind,
+    domain: slice.domain,
+    entrypoints: [...slice.entrypoints].sort(compareStrings),
+    layers,
+    claims: [...slice.claims]
+      .map((claim) => ({ kind: claim.kind, path: claim.path }))
+      .sort((a, b) => compareStrings(a.kind, b.kind) || compareStrings(a.path, b.path)),
+    usesResources: [...slice.usesResources].sort(compareStrings),
+  };
+  if (slice.rationale !== undefined) out.rationale = slice.rationale;
+  return out;
+}
+
+function exportRegistries(registries: Registries): Registries {
+  return {
+    owners: [...registries.owners].sort(compareStrings),
+    audiences: [...registries.audiences].sort(compareStrings),
+    releases: [...registries.releases].sort(compareStrings),
+    roles: [...registries.roles].sort(compareStrings),
+    editions: [...registries.editions].sort(compareStrings),
+    flags: [...registries.flags].sort(compareStrings),
+    resources: [...registries.resources]
+      .map((resource) => ({
+        id: resource.id,
+        path: resource.path,
+        owner: resource.owner,
+        consumers: [...resource.consumers].sort(compareStrings),
+      }))
+      .sort((a, b) => compareStrings(a.id, b.id)),
+  };
+}