@sdd-method/author-cli 0.15.1 → 0.16.1

package/dist/lib/behaviour-store/archive.js

@@ -129,10 +129,17 @@ export async function orderArchives(sddPath, archiveRel, names) {
     }
     return { order, ties, history: history !== null };
 }
+/**
+ * Whether the evidence's `**Observed in:**` line is the typed claim `none`: a baseline that admits no behaviour (no
+ * spec deltas), such as a structure-only removal, observed no repository serving any.
+ */
+export function observedNone(evidence) {
+    return /^\s*\*\*Observed in:\*\*\s*none\b/im.test(evidence);
+}
 /** The repositories a baseline was observed in: its evidence file's `**Observed in:** repo[@sha], repo[@sha]` line. */
 export function observedIn(evidence) {
     const m = /^\s*\*\*Observed in:\*\*\s*(.+)$/m.exec(evidence);
-    if (!m)
+    if (!m || observedNone(evidence))
         return [];
     return m[1]
         .split(",")
@@ -148,18 +155,30 @@ export function observedIn(evidence) {
  * `**Surfaces:**` line is read, so an earlier prose section under the same label does not shadow the list.
  * Covered needs evidence that exercises the surface as the service exposes it; evidence below the transport is
  * not coverage, so `covered at handler` is a problem, not an entry. A wildcard may only exclude.
+ *
+ * `**Surfaces:** none` on one line is the typed claim that the baseline lists no surface, which only a baseline that
+ * admits no behaviour may make (the caller decides; `none` is true and the list is empty).
  */
 export function parseSurfaces(evidence) {
     const lines = evidence.split("\n");
     // The LAST standalone line: an evidence file may carry an earlier prose section under the same label, and
     // the list is what the file ends up asserting.
     let at = -1;
+    let none = false;
     lines.forEach((l, i) => {
-        if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l))
+        if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l)) {
             at = i;
+            none = false;
+        }
+        else if (/^\s*\*\*Surfaces:\*\*\s*none\b/i.test(l)) {
+            at = i;
+            none = true;
+        }
     });
     if (at < 0)
-        return { present: false, entries: [], problems: [] };
+        return { present: false, none: false, entries: [], problems: [] };
+    if (none)
+        return { present: true, none: true, entries: [], problems: [] };
     const entries = [];
     const problems = [];
     for (const line of lines.slice(at + 1)) {
@@ -193,8 +212,36 @@ export function parseSurfaces(evidence) {
         }
     }
     if (entries.length + problems.length === 0)
-        problems.push("the **Surfaces:** line lists no contract");
-    return { present: true, entries, problems };
+        problems.push('the **Surfaces:** line lists no contract; a baseline that admits no behaviour writes "**Surfaces:** none"');
+    return { present: true, none: false, entries, problems };
+}
+/**
+ * A structural delta's `moved: {contracts: [{from, to, from_path?}]}` block. A contract's id is derived from its path,
+ * so moving the file changes the id; the change that moves it records the move once, and what named the old
+ * identity (an archived baseline's Surfaces list) follows it rather than being edited.
+ */
+export function contractMoves(raw) {
+    const moves = [];
+    const problems = [];
+    if (raw === undefined || raw === null)
+        return { moves, problems };
+    const contracts = typeof raw === "object" && !Array.isArray(raw) ? raw["contracts"] : undefined;
+    const extra = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? Object.keys(raw).filter((k) => k !== "contracts") : [];
+    if (!Array.isArray(contracts) || extra.length > 0) {
+        problems.push(`moved must be {contracts: [{from: <old contract id>, to: <new contract id>, from_path?: <old spec path>}]}`);
+        return { moves, problems };
+    }
+    for (const [i, m] of contracts.entries()) {
+        const e = (m ?? {});
+        const from = typeof e["from"] === "string" ? e["from"].trim() : "";
+        const to = typeof e["to"] === "string" ? e["to"].trim() : "";
+        const fromPath = typeof e["from_path"] === "string" ? e["from_path"].trim() : undefined;
+        if (from === "" || to === "" || from === to)
+            problems.push(`moved.contracts[${i}] needs a from and a to that differ`);
+        else
+            moves.push({ from, to, ...(fromPath ? { fromPath } : {}) });
+    }
+    return { moves, problems };
 }
 /** Whether a Surfaces entry names a catalogue contract: its id, or a path suffix of its spec_path on a segment boundary. */
 export function surfaceMatches(entry, contractId, specPath) {

package/dist/lib/behaviour-store/schema.js

@@ -14,6 +14,16 @@ export const SCHEMA_NAME = "sdd-change";
 export const SHIPPED_SCHEMA_DIR = "docs/method/foundations/openspec/sdd-change";
 export const SHIPPED_CONFIG_TEMPLATE = "docs/method/foundations/openspec/config-template.yaml";
 export const STORE_SCHEMA_DIR = `openspec/schemas/${SCHEMA_NAME}`;
+/**
+ * The baseline schema (M-ADR 0222 §4.3-4.4): a baseline change selects it in its own .openspec.yaml, the store's
+ * config.yaml keeping sdd-change as the default. Copied and checked as sdd-change is, where the SDD's bundle
+ * ships it; a bundle from before it shipped has none, and nothing is asked of the store.
+ */
+export const BASELINE_SCHEMA_NAME = "sdd-baseline";
+/** Every schema the method ships for a store, the default first. */
+export const STORE_SCHEMAS = [SCHEMA_NAME, BASELINE_SCHEMA_NAME];
+export const shippedSchemaDir = (name) => `docs/method/foundations/openspec/${name}`;
+export const storeSchemaDir = (name) => `openspec/schemas/${name}`;
 export const STORE_CONFIG = "openspec/config.yaml";
 async function files(dir) {
     const out = [];
@@ -50,36 +60,38 @@ export async function storeSchemaName(repo) {
     const v = parseDocument(text.toString("utf8")).toJS()?.schema;
     return typeof v === "string" ? v : "";
 }
-/** Compare the store's copy of the schema with the one the SDD's method bundle shipped, file by file. */
-export async function compareStoreSchema(repo) {
-    const shipped = await files(join(repo, SHIPPED_SCHEMA_DIR));
+/** Compare the store's copy of a schema with the one the SDD's method bundle shipped, file by file. */
+export async function compareStoreSchema(repo, name = SCHEMA_NAME) {
+    const shippedDir = shippedSchemaDir(name);
+    const storeDir = storeSchemaDir(name);
+    const shipped = await files(join(repo, shippedDir));
     if (shipped === null || shipped.length === 0)
         return { shipped: false, missing: [], differing: [], extra: [] };
-    const store = (await files(join(repo, STORE_SCHEMA_DIR))) ?? [];
+    const store = (await files(join(repo, storeDir))) ?? [];
     const missing = shipped.filter((f) => !store.includes(f));
     const extra = store.filter((f) => !shipped.includes(f));
     const differing = [];
     for (const f of shipped.filter((x) => store.includes(x))) {
-        const a = await read(join(repo, SHIPPED_SCHEMA_DIR, f));
-        const b = await read(join(repo, STORE_SCHEMA_DIR, f));
+        const a = await read(join(repo, shippedDir, f));
+        const b = await read(join(repo, storeDir, f));
         if (a === null || b === null || !a.equals(b))
             differing.push(f);
     }
     return { shipped: true, missing, differing, extra };
 }
 /**
- * Replace the store's copy of the schema with the shipped one. Returns what changed, as a
+ * Replace the store's copy of a schema with the shipped one. Returns what changed, as a
  * comparison taken before the write; a store already current returns empty lists.
  */
-export async function writeStoreSchema(repo) {
-    const before = await compareStoreSchema(repo);
+export async function writeStoreSchema(repo, name = SCHEMA_NAME) {
+    const before = await compareStoreSchema(repo, name);
     if (!before.shipped)
         return before;
     if (before.missing.length + before.differing.length + before.extra.length === 0)
         return before;
-    await rm(join(repo, STORE_SCHEMA_DIR), { recursive: true, force: true });
-    await mkdir(join(repo, STORE_SCHEMA_DIR), { recursive: true });
-    await cp(join(repo, SHIPPED_SCHEMA_DIR), join(repo, STORE_SCHEMA_DIR), { recursive: true });
+    await rm(join(repo, storeSchemaDir(name)), { recursive: true, force: true });
+    await mkdir(join(repo, storeSchemaDir(name)), { recursive: true });
+    await cp(join(repo, shippedSchemaDir(name)), join(repo, storeSchemaDir(name)), { recursive: true });
     return before;
 }
 //# sourceMappingURL=schema.js.map

package/dist/lib/catalogue/aggregation-manifest-loader.js

@@ -0,0 +1,173 @@
+// Aggregation-manifest loader per
+// docs/method/methods/aggregation-manifest-schema.yaml.
+//
+// v1 supports `pull.kind: filesystem` only; the other kinds (git-ref,
+// release-asset) are schema-reserved and reject with a
+// clear "deferred" error so adopters get unambiguous feedback.
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { SCHEMA_COMPAT, formatSchemaVersionMismatch } from "./schema-compat.js";
+import { isInRange } from "./manifest-loader.js";
+export const DEFAULT_AGGREGATION_MANIFEST_REL = "orchestration/aggregation-manifest.yaml";
+const PullSchema = z
+    .object({
+    kind: z.string(),
+    path: z.string().optional(),
+})
+    .passthrough();
+const SiblingSchema = z.object({
+    sdd_id: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+        message: "sdd_id must match /^[a-z][a-z0-9-]*$/",
+    }),
+    pull: PullSchema,
+    description: z.string().optional(),
+    level: z.string().optional(),
+});
+/**
+ * An ecosystem member that is real and intended but has no SDD yet
+ * (aggregation-manifest-schema 1.1.0, per M-ADR 0195 §4.3).
+ *
+ * A SEPARATE list rather than a flag on `siblings[]`: `pull` is required on a sibling
+ * and a pending member has nothing to pull, and `siblings[]` must keep meaning exactly
+ * "members whose catalogues merge in" — adding skippable entries would give one list
+ * two meanings, which every existing reader would keep miscounting.
+ *
+ * `reason` is required and non-empty. A bare marker suppresses the build failure while
+ * saying nothing about why, losing the signal that a pending member is a WORK ITEM —
+ * the state this replaces.
+ */
+const PendingMemberSchema = z.object({
+    sdd_id: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+        message: "pending_members[].sdd_id must match /^[a-z][a-z0-9-]*$/",
+    }),
+    reason: z.string().min(1, {
+        message: "pending_members[].reason must be non-empty — a marker without a reason suppresses a failure without explaining it",
+    }),
+    blocked_on: z.string().optional(),
+});
+const SLUG = /^[a-z][a-z0-9-]*$/;
+// M-ADR 0208 §4.3: `root_sdd_id` is canonical; `ecosystem_root` is its DEPRECATED alias
+// (at organisation tier the old name called an organisation-root an "ecosystem root").
+// Exactly one of the two must be present. Removed at 2.0.0.
+const AggregationManifestSchema = z
+    .object({
+    schema_version: z.string(),
+    root_sdd_id: z.string().regex(SLUG).optional(),
+    ecosystem_root: z.string().regex(SLUG).optional(),
+    level: z.enum(["platform", "organisation"]).optional(),
+    siblings: z.array(SiblingSchema),
+    pending_members: z.array(PendingMemberSchema).optional(),
+})
+    .refine((m) => (m.root_sdd_id !== undefined) !== (m.ecosystem_root !== undefined), {
+    message: "exactly one of `root_sdd_id` (canonical, M-ADR 0208 §4.3) or `ecosystem_root` (deprecated alias) must be present",
+});
+export async function loadAggregationManifest(manifestPath, options) {
+    let text;
+    try {
+        text = await readFile(manifestPath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Aggregation manifest not found at ${manifestPath}\n\n` +
+                `Ecosystem-root SDDs declare an aggregation manifest at the path\n` +
+                `recorded in .sdd/sdd-manifest.yaml#aggregation_manifest_path, or\n` +
+                `at ${DEFAULT_AGGREGATION_MANIFEST_REL} by default.\n` +
+                `Schema: docs/method/methods/aggregation-manifest-schema.yaml.`);
+        }
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`failed to parse YAML at ${manifestPath}: ${err.message}`);
+    }
+    const parsed = AggregationManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("\n");
+        throw new Error(`invalid aggregation manifest at ${manifestPath}:\n${issues}`);
+    }
+    if (!isInRange(parsed.data.schema_version, SCHEMA_COMPAT.aggregation_manifest)) {
+        throw new Error(formatSchemaVersionMismatch({
+            schema: "aggregation_manifest",
+            readVersion: parsed.data.schema_version,
+            cliVersion: options.cliVersion,
+            sourcePath: manifestPath,
+        }));
+    }
+    // Duplicate sibling-id check.
+    const seen = new Set();
+    for (const s of parsed.data.siblings) {
+        if (seen.has(s.sdd_id)) {
+            throw new Error(`aggregation manifest has duplicate sibling sdd_id "${s.sdd_id}"\n` +
+                `  (${manifestPath})`);
+        }
+        seen.add(s.sdd_id);
+    }
+    // Resolve each sibling's pull. v1 supports `kind: filesystem` only.
+    const resolved = [];
+    for (const s of parsed.data.siblings) {
+        const kind = s.pull.kind;
+        if (kind !== "filesystem") {
+            throw new Error(`aggregation manifest: sibling "${s.sdd_id}" uses pull.kind="${kind}"\n` +
+                `  v1 supports filesystem only. The other kinds (git-ref, release-asset)\n` +
+                `  are schema-reserved and not yet implemented.\n` +
+                `  See: docs/method/methods/aggregation-manifest-schema.yaml#pull_kinds`);
+        }
+        const path = s.pull.path;
+        if (!path || typeof path !== "string") {
+            throw new Error(`aggregation manifest: sibling "${s.sdd_id}" pull.kind=filesystem requires \`path\``);
+        }
+        const cataloguesPath = isAbsolute(path)
+            ? path
+            : resolve(options.ecosystemRootPath, path);
+        // The sibling's repo root is the parent of `catalogues/`.
+        const sddRoot = resolve(cataloguesPath, "..");
+        // Portable form for the committed JSON snapshot: keep a relative source
+        // verbatim; anchor an absolute source to the ecosystem root so the emitted
+        // value never carries a machine-specific $HOME/checkout prefix.
+        const relativeCataloguesPath = isAbsolute(path)
+            ? relative(options.ecosystemRootPath, cataloguesPath)
+            : path;
+        resolved.push({
+            sddId: s.sdd_id,
+            description: s.description ?? "",
+            cataloguesPath,
+            relativeCataloguesPath,
+            sddRoot,
+            level: s.level,
+        });
+    }
+    // A member is pending authoring OR contributing catalogues, never both. Declaring
+    // both is a contradiction rather than something to merge, and silently preferring
+    // one reading would make the work queue untrustworthy — so it fails with the id.
+    const pendingMembers = [];
+    const siblingIds = new Set(resolved.map((r) => r.sddId));
+    for (const p of parsed.data.pending_members ?? []) {
+        if (siblingIds.has(p.sdd_id)) {
+            throw new Error(`aggregation manifest: "${p.sdd_id}" appears in BOTH siblings and pending_members.\n` +
+                `  A member is either pending authoring or contributing catalogues, not both.\n` +
+                `  Remove whichever declaration is stale (${parsed.data.root_sdd_id ?? parsed.data.ecosystem_root}).`);
+        }
+        pendingMembers.push({
+            sddId: p.sdd_id,
+            reason: p.reason,
+            ...(p.blocked_on !== undefined ? { blockedOn: p.blocked_on } : {}),
+        });
+    }
+    return {
+        schemaVersion: parsed.data.schema_version,
+        ecosystemRoot: (parsed.data.root_sdd_id ?? parsed.data.ecosystem_root),
+        level: parsed.data.level,
+        rootFieldDeprecated: parsed.data.root_sdd_id === undefined,
+        siblings: resolved,
+        pendingMembers,
+        sourcePath: manifestPath,
+    };
+}
+//# sourceMappingURL=aggregation-manifest-loader.js.map

package/dist/lib/catalogue/build.js

@@ -394,6 +394,9 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         knownDomainIds,
         profile: manifest.profile,
         category: manifest.category,
+        domainExternal: schema.catalogues
+            .find((c) => c.name === "adrs")
+            ?.foreignKeys.some((fk) => fk.column === "domain_id" && (fk.external || (fk.externalForProfiles ?? []).includes(manifest.profile))) ?? false,
     });
     const supersedes = buildAdrSupersedes({ findings, adrs: adrResult.parsed });
     out.set("adr_supersedes", supersedes.rows);

package/dist/lib/catalogue/builders/adrs.js

@@ -88,7 +88,7 @@ export async function buildAdrs(inputs) {
             inputs.findings.add("convention", `${relPath}: **Effective:** is "${effectiveRaw}", neither "on acceptance" nor "on archive of <change>"; read as on acceptance (M-ADR 0230 §4.2)`);
         }
         const effectiveChange = onArchive?.[1] ?? "";
-        if (scope === "domain" && !inputs.knownDomainIds.has(domainId)) {
+        if (scope === "domain" && !inputs.knownDomainIds.has(domainId) && !inputs.domainExternal) {
             inputs.findings.add("orphan", `${relPath}: ADR is in domain "${domainId}" but no docs/domains/${domainId}/ exists`);
         }
         // Method-scoped ADRs are cross-cutting governance and belong to no

package/dist/lib/catalogue/builders/contracts.js

@@ -58,6 +58,10 @@ const KIND_SPECS = [
     // name as their surface (M-ADR 0222 §4.4). Reachable from every path at once, unlike graphql above: discovered here, mapped from a
     // traceability manifest's `cli:` block (DECLARED_KINDS), loaded (CONTRACT_LIST_KEYS) and keyed by repo-config.
     { subdir: "cli", extensions: [".yaml", ".yml"], kind: "cli" },
+    // `ui` — an embeddable UI surface's manifest (schema 7.2.0): its custom elements and the messages it sends and
+    // receives. A UI-only repository that other applications load serves no other contract, so its behaviour
+    // baselines had nothing to name as their surface (M-ADR 0222 §4.4). Reachable from every path, as `cli` is.
+    { subdir: "ui", extensions: [".yaml", ".yml"], kind: "ui" },
 ];
 export async function buildContracts(inputs) {
     const rows = [];
@@ -318,6 +322,7 @@ const DECLARED_KINDS = {
     spicedb: "authz",
     graphql: "graphql",
     cli: "cli",
+    ui: "ui",
 };
 export function buildDeclaredExternalContracts(inputs) {
     const rows = [];

package/dist/lib/catalogue/builders/features.js

@@ -24,9 +24,18 @@
 //
 // Dedup ordering matters: walker (1) runs first (capability features),
 // then walker (2) (standalone specs), then walker (3) (bullets). When
-// a bullet's id is already in `seen` from a standalone spec the spec
-// wins — divergence finding fires for the bullet. This matches the
-// "standalone is more authoritative than bullet inventory" rule.
+// a bullet's id is already claimed by a standalone app spec (2), the two
+// are one feature and make one row (sdm-mbhi): the feature tree is the home
+// of its placement and inventory facts (parent_group_id, maturity, runway,
+// description), the spec of its lifecycle (status, kind), and source stays
+// feature-spec, since a spec exists. A spec does not restate the tree's
+// fields, and its H1 title is a name, not a description. A bullet whose id a
+// capability feature (1) already claims is still a divergence.
+//
+// A standalone spec's stem is the feature's slug, without the product
+// prefix: features/<group>/alerts.md is <productId>-alerts. A stem that
+// already starts with "<productId>-" would double the prefix, so it is
+// refused with a convention finding naming the stem to use.
 import { readdir, readFile } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 import { featureGroupId, findFeatureTreeFile, walkFeatureTree, } from "./feature-tree-walker.js";
@@ -103,10 +112,15 @@ export async function buildFeatures(inputs) {
     // These features are owned by the SDD's product (not by a capability) —
     // capability_id is left empty; product_id carries the link.
     if (inputs.profile === "application-product") {
+        const appSpecRow = new Map();
         const appFeatures = await collectAppFeatureSpecs(inputs.sddPath);
         for (const path of appFeatures) {
             const relPath = relative(inputs.sddPath, path);
             const stem = basename(relPath).replace(/\.md$/i, "");
+            if (stem.startsWith(`${inputs.productId}-`)) {
+                inputs.findings.add("convention", `${relPath}: feature spec stem "${stem}" repeats the product prefix, so its id would read "${inputs.productId}-${stem}"; name the file after the feature's slug ("${stem.slice(inputs.productId.length + 1)}.md"), the slug feature-tree.md uses`);
+                continue;
+            }
             const id = `${inputs.productId}-${stem}`;
             if (seen.has(id)) {
                 inputs.findings.add("divergence", `${relPath}: feature id "${id}" already emitted by an earlier file`);
@@ -133,6 +147,7 @@ export async function buildFeatures(inputs) {
             idByPath.set(relPath, id);
             if (!idBySlug.has(stem))
                 idBySlug.set(stem, id);
+            appSpecRow.set(id, rows.length - 1);
         }
         // Bullet branch — feature-tree.md.
         await emitBulletRows({
@@ -143,6 +158,7 @@ export async function buildFeatures(inputs) {
             seen,
             rows,
             idBySlug,
+            appSpecRow,
         });
     }
     return { rows, idByPath, idBySlug };
@@ -178,7 +194,8 @@ async function emitBulletRows(ctx) {
             continue;
         bulletCount++;
         const id = `${ctx.productId}-${ev.slug}`;
-        if (ctx.seen.has(id)) {
+        const specIndex = ctx.appSpecRow.get(id);
+        if (ctx.seen.has(id) && specIndex === undefined) {
             ctx.findings.add("divergence", `${relPath}: feature-tree.md bullet "${ev.slug}" superseded by an earlier feature spec with id "${id}"`);
             continue;
         }
@@ -196,6 +213,19 @@ async function emitBulletRows(ctx) {
         const description = ev.description.length > DESCRIPTION_MAX
             ? ev.description.slice(0, DESCRIPTION_MAX)
             : ev.description;
+        if (specIndex !== undefined) {
+            // One feature, one row: the tree's placement and inventory facts, the spec's lifecycle.
+            ctx.rows[specIndex] = {
+                ...ctx.rows[specIndex],
+                parent_group_id: parentGroupId,
+                description,
+                maturity: maturityFromRunway(ev.runway),
+                runway: ev.runway,
+            };
+            if (!ctx.idBySlug.has(ev.slug))
+                ctx.idBySlug.set(ev.slug, id);
+            continue;
+        }
         ctx.rows.push({
             id,
             name: ev.slug,

package/dist/lib/catalogue/builders/repositories.js

@@ -33,10 +33,11 @@ const LOC_REPORT_REL = join("docs", "platform", "reference", "loc-report.csv");
 const REPOS_DIR_REL = "repos";
 const REVERSE_METADATA_BASENAME = "reverse-metadata.yaml";
 // The contract kinds a repo-config `contracts:` block keys, under `contracts/<kind>/`. The sdd-index reader
-// accepts the same five; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
+// accepts the same six; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
 // so a declared `.zed` schema vanished without a finding. `cli` (schema 4.1.0) declares the command manifest a
-// command-line repository serves. GraphQL is not keyed in repo-config: that is its own question, on this schema.
-export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "cli"];
+// command-line repository serves, and `ui` (schema 7.2.0) the manifest of an embeddable UI surface a UI-only
+// repository serves. GraphQL is not keyed in repo-config: that is its own question, on this schema.
+export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "cli", "ui"];
 const ContractsBlockSchema = z
     .object({
     openapi: z.array(z.string()).optional(),
@@ -44,6 +45,7 @@ const ContractsBlockSchema = z
     avro: z.array(z.string()).optional(),
     spicedb: z.array(z.string()).optional(),
     cli: z.array(z.string()).optional(),
+    ui: z.array(z.string()).optional(),
 })
     .optional();
 const EventEntrySchema = z.object({

package/dist/lib/catalogue/builders/requirements.js

@@ -276,7 +276,7 @@ export async function buildRequirements(inputs) {
             structureEffects.push(effectRow(scoped(dir), "structure", e.element, e.operation, e.base ?? "", e.target ?? ""));
         if (evidence !== null) {
             const repos = observedIn(evidence);
-            if (repos.length === 0) {
+            if (repos.length === 0 && delta.length > 0) {
                 findings.add("convention", `${rel(sddPath, join(changeDir, "baseline-evidence.md"))}: no "**Observed in:**" line, so its requirements carry no observed status`);
             }
             for (const repo of repos)

package/dist/lib/catalogue/canonical-schema.yaml

@@ -7,7 +7,7 @@
 # Emitted by sdd-cli's YAML emitter with no line folding; the three header scalars are quoted for the
 # textual readers downstream. The one deliberate difference from the authored form is schema_status:
 # the authored form says canonical; a projection never does.
-schema_version: "7.1.0"
+schema_version: "7.2.0"
 schema_owner: "sdd-method"
 schema_status: "generated"
 enums:
@@ -364,6 +364,7 @@ enums:
     - value: rpc
     - value: authz
     - value: cli
+    - value: ui
     description: Contract kind. Bound at 3.13.0 from the column descriptions; measured against both reference estates before binding (M-ADR 0205 §4.4).
   contract_status:
     values:
@@ -1791,7 +1792,7 @@ catalogues:
     - name: kind
       type: string
       nullable: false
-      description: rest | graphql | rpc | event | authz | cli. rpc covers Proto/gRPC; event covers Avro schemas; authz covers authorization/policy schemas (SpiceDB .zed and equivalents), added because an adopter contract agreement gate certified .zed schemas as contracts while no kind could represent them; cli covers a command-line interface's command manifest (its commands, options and exit codes), added at 4.1.0 because a command-line tool often serves no REST, RPC, event or authorization contract, so its behaviour baselines had nothing to name as their surface.
+      description: rest | graphql | rpc | event | authz | cli | ui. rpc covers Proto/gRPC; event covers Avro schemas; authz covers authorization/policy schemas (SpiceDB .zed and equivalents), added because an adopter contract agreement gate certified .zed schemas as contracts while no kind could represent them; cli covers a command-line interface's command manifest (its commands, options and exit codes), added at 4.1.0 because a command-line tool often serves no REST, RPC, event or authorization contract, so its behaviour baselines had nothing to name as their surface; ui covers an embeddable UI surface's manifest (its custom elements with their attributes, properties and emitted events, and the messages it sends and receives), added at 7.2.0 because a UI-only repository that other applications load serves no other contract, so its behaviour baselines had nothing to name as their surface.
     - name: version
       type: string
       nullable: true

package/dist/lib/catalogue/contract-id.js

@@ -2,7 +2,7 @@
 // M-ADR 0203 §4.4, the cut's acid test.
 //
 // From 3.0.0 a contract id carries its KIND component: `{domain}-{stem}-{kind}`
-// (kind ∈ rest | graphql | rpc | event | authz | cli). The kindless 2.x form made one
+// (kind ∈ rest | graphql | rpc | event | authz | cli | ui). The kindless 2.x form made one
 // measured collision class unrepresentable: a service published as two contract
 // families (`calendar-service.yaml` + `calendar_service.proto`) minted one id,
 // costing a live estate one row and two edges permanently, and mislabelling

package/dist/lib/catalogue/impact-run.js

@@ -103,7 +103,12 @@ export function buildImpactPropagation(edges, semantics) {
     for (const [key, rec] of pairs) {
         const abOnly = [...rec.ab].filter((t) => !rec.ba.has(t));
         const baOnly = [...rec.ba].filter((t) => !rec.ab.has(t));
-        if (abOnly.length > 0 && baOnly.length > 0) {
+        // Every opposing type a foreign key of ONE catalogue: an entity-FK step runs between a row and what it
+        // references, so such a pair is one row naming the same node in two of its columns, a self-reference (an
+        // entity related to itself), and the opposition is that row's own two ends meeting, not drift.
+        const catalogues = new Set([...abOnly, ...baOnly].map((t) => (t.includes(".") ? t.slice(0, t.indexOf(".")) : `\u0000${t}`)));
+        const selfReference = catalogues.size === 1 && !([...catalogues][0].startsWith("\u0000"));
+        if (abOnly.length > 0 && baOnly.length > 0 && !selfReference) {
             const [a, b] = key.split("␟");
             throw new Error(`impact: counter-directional reciprocal pair (M-ADR 0206 §4.4): ` +
                 `${abOnly[0]} propagates ${a} -> ${b} while ${baOnly[0]} propagates ` +

package/dist/lib/catalogue/traceability-loader.js

@@ -48,6 +48,7 @@ export const CONTRACT_LIST_KEYS = [
     "spicedb",
     "graphql",
     "cli",
+    "ui",
 ];
 /**
  * Every contract path a contracts block declares, across all kinds and both
@@ -283,6 +284,7 @@ function extractContracts(raw) {
     const spicedb = arr("spicedb");
     const graphql = arr("graphql");
     const cli = arr("cli");
+    const ui = arr("ui");
     // `provenance` (3.5.0) MUST be extracted here or the builder that reads it
     // sees nothing — this function reconstructs the block key-by-key rather than
     // passing the parsed object through, which is precisely the shape the
@@ -300,6 +302,7 @@ function extractContracts(raw) {
         ...(spicedb ? { spicedb } : {}),
         ...(graphql ? { graphql } : {}),
         ...(cli ? { cli } : {}),
+        ...(ui ? { ui } : {}),
         ...(provenance ? { provenance } : {}),
     };
 }

package/dist/lib/contracts-availability/index.js

@@ -116,7 +116,7 @@ async function collectReferences(repo) {
         const block = m.traceability.contracts;
         if (!block)
             continue;
-        for (const list of [block.openapi, block.proto, block.avro, block.spicedb, block.graphql, block.cli]) {
+        for (const list of [block.openapi, block.proto, block.avro, block.spicedb, block.graphql, block.cli, block.ui]) {
             if (!Array.isArray(list))
                 continue;
             for (const entry of list) {
@@ -201,6 +201,9 @@ export function inferKind(ref) {
     // repository whose own name ends in -cli stays rest.
     if (/(^|\/)cli\/.*\.ya?ml$/.test(ref))
         return "cli";
+    // A UI surface manifest lives under a `ui/` contracts folder, tested after rest for the same reason.
+    if (/(^|\/)ui\/.*\.ya?ml$/.test(ref))
+        return "ui";
     return undefined;
 }
 /** The SDD's attested external artefacts (`.sdd/contract-availability.yaml`); none when it has no manifest. */

package/dist/lib/plan/read-sdd.js

@@ -44,7 +44,7 @@ async function readRepoConfigFor(sddRoot, manifestAbsPath) {
         path: manifestAbsPath,
         aggregates: [],
         internalDependencies: [],
-        contracts: { openapi: [], proto: [], avro: [], spicedb: [], graphql: [], cli: [] },
+        contracts: { openapi: [], proto: [], avro: [], spicedb: [], graphql: [], cli: [], ui: [] },
     };
     if (!(await fileExists(manifestAbsPath)))
         return empty;
@@ -63,6 +63,7 @@ function legacyShape(node, sourcePath) {
         avro: [],
         spicedb: [],
         cli: [],
+        ui: [],
     };
     for (const ref of node.contracts)
         byKind[ref.kind].push(ref.path);

package/dist/lib/scaffold/behaviour-store.js

@@ -5,7 +5,7 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { parseDocument } from "yaml";
-import { SHIPPED_CONFIG_TEMPLATE, SHIPPED_SCHEMA_DIR, STORE_CONFIG, STORE_SCHEMA_DIR, writeStoreSchema } from "../behaviour-store/schema.js";
+import { SHIPPED_CONFIG_TEMPLATE, SHIPPED_SCHEMA_DIR, STORE_CONFIG, writeStoreSchema, STORE_SCHEMAS, storeSchemaDir } from "../behaviour-store/schema.js";
 import { MANIFEST_REL_PATH } from "../catalogue/manifest-loader.js";
 export const STORE_KEEP_FILES = ["openspec/specs/.gitkeep", "openspec/changes/archive/.gitkeep", "docs/agreements/.gitkeep"];
 async function exists(p) {
@@ -53,8 +53,10 @@ export async function scaffoldBehaviourStore(repo) {
         await writeFile(join(repo, rel), "");
         filesWritten.push(rel);
     }
-    const copied = await writeStoreSchema(repo);
-    filesWritten.push(...copied.missing.map((f) => `${STORE_SCHEMA_DIR}/${f}`));
+    for (const name of STORE_SCHEMAS) {
+        const copied = await writeStoreSchema(repo, name);
+        filesWritten.push(...copied.missing.map((f) => `${storeSchemaDir(name)}/${f}`));
+    }
     return { filesWritten, sddId };
 }
 //# sourceMappingURL=behaviour-store.js.map

package/dist/lib/sdd-index/repo-config.js

@@ -17,6 +17,7 @@ const CONTRACT_KINDS = [
     "avro",
     "spicedb",
     "cli",
+    "ui",
 ];
 export function readAllRepoConfigs(reader) {
     const services = [];