@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/dist/provider-data.d.ts

@@ -0,0 +1,184 @@
+import type { AttrSchema, TypeDefinition, TypeRegistry } from "./registry.js";
+import { TypeId } from "./registry.js";
+import type { MetaData } from "./shared/meta-data.js";
+/**
+ * A UNIFIED child requirement (spec §3.1). Every constraint on a type — both its
+ * structural children AND its attributes — is one of these entries in a single
+ * `children` list, distinguished by `type`:
+ *
+ *  - an **attribute** is a `{ type: "attr", … }` entry. Its `subType` is the
+ *    attr's value-type (a single subtype — never a list), `max` is always 1
+ *    (single-valued; a list-valued attr sets `isArray: true`), and it carries the
+ *    attr-only facets `default` / `allowedValues` / `isArray`.
+ *  - a **structural child** (`field`/`identity`/`source`/`validator`/…) carries
+ *    full cardinality (`min`/`max`, `max: null` = unbounded) and may admit any of
+ *    several subtypes via a `subType` list.
+ *
+ * `type` / `subType` / `name` accept the `"*"` wildcard.
+ */
+export interface ChildDef {
+    /** Child type, or `"*"` for any. For attrs this is the literal `"attr"`. */
+    type: string;
+    /**
+     * Child subtype: a single subtype, a list of admitted subtypes, or `"*"`.
+     * For an `attr` entry this is the attr's value-type and MUST be a single
+     * subtype (a list is invalid for attrs). Optional on an `attr` entry: an
+     * omitted `subType` declares a polymorphic/untyped attr (e.g. `@default`,
+     * whose value-type follows the owning field's subtype). A structural child
+     * always supplies a `subType` (or `"*"`).
+     */
+    subType?: string | readonly string[];
+    /** Child name, or `"*"` for any. */
+    name: string;
+    /** Cardinality lower bound. An attr is required iff `min >= 1`. */
+    min: number;
+    /** Cardinality upper bound; `null` = unbounded. For an attr this is 1. */
+    max: number | null;
+    /** Whether the child must carry an explicit name. */
+    named?: boolean;
+    description?: string;
+    /** Prose documenting the complex rules enforced in code. */
+    rules?: string;
+    /** An example value/usage, shown only in the provider detail page. */
+    example?: string;
+    /** Guidance on when to reach for this child/attr. */
+    whenToUse?: string;
+    /** Default value applied when the attr is absent. */
+    default?: unknown;
+    /** Closed enum of allowed values. */
+    allowedValues?: readonly unknown[];
+    /** Whether the attr is array-valued (the only way an attr's `max` may be > 1). */
+    isArray?: boolean;
+}
+/**
+ * A declarative type/subtype definition (spec §3). The `factory` is NOT here — it
+ * is code, supplied via the `FactoryMap`. An attribute is a `type: "attr"` entry
+ * inside `children`; structural children are the non-`"attr"` entries.
+ */
+export interface TypeDef {
+    type: string;
+    subType: string;
+    description: string;
+    dataType?: string;
+    rules?: string;
+    example?: string;
+    whenToUse?: string;
+    /** Unified children list: attrs (`type: "attr"`) + structural children. */
+    children?: ChildDef[];
+    /** Child-side placement: the `type.subType`s under which this type is allowed. */
+    parents?: readonly string[];
+    /**
+     * FR-033 base-composition opt-in. When `true` (and this is a non-base subtype),
+     * the subtype additively inherits its `<type>.base`'s attrs (dedup by name) and
+     * childRules (dedup structurally) — letting the JSON declare per-type-universal
+     * rules once on `base`. Default/absent = OFF, so a subtype that deliberately
+     * declares FEWER attrs than base (e.g. `validator.required`, which wants no
+     * `min`/`max`) is never silently widened. Opted in per-subtype in S1; inert (no
+     * registered output change) under S0.
+     */
+    extendsBase?: boolean;
+    /**
+     * Max number of children of this `type.subType` permitted under one parent.
+     * `1` marks a singleton child (e.g. `identity.primary` — one per entity). The
+     * loader enforces it. A singleton is the ONLY place a static `defaultName` is
+     * safe (no sibling can collide), so `defaultName` is honored only when
+     * `maxOccurs === 1`. Absent = unbounded.
+     */
+    maxOccurs?: number;
+    /**
+     * Author-omittable name for a singleton child. When a node of this type is
+     * declared with no `name` AND `maxOccurs === 1`, the loader assigns
+     * `defaultName` (e.g. `identity.primary` → `"primary"`). Keeps the one-and-only
+     * node addressable (`Entity.primary`) without forcing a hand-written name.
+     */
+    defaultName?: string;
+}
+/**
+ * FR-033 S1.5 — a declarative `registry.extend` directive. A **concern** provider
+ * (db / ui / prompt) does NOT register new `type.subType`s; it ADDS attrs to types
+ * an upstream provider (core) already registered. This entry is the data form of a
+ * `registry.extend(type, sub, { attributes })` call: `subType` selects the target
+ * subtype(s) and `children` are the `type: "attr"` entries (→ `AttrSchema`) to add.
+ */
+export interface ExtendDef {
+    /** Target type whose subtype(s) are extended (e.g. `"field"`, `"source"`). */
+    type: string;
+    /**
+     * Target subtype(s): a single subtype name, a LIST of subtype names, or the
+     * `"*"` wildcard (= every currently-registered subtype of `type`). Resolved at
+     * apply time against the registry.
+     */
+    subType: string | readonly string[];
+    /**
+     * Attrs to add to each resolved target. Concern providers add attrs only — these
+     * must all be `type: "attr"` entries (lowered via `toAttrSchema`). A structural
+     * child here is rejected (concern providers do not contribute child rules).
+     */
+    children: ChildDef[];
+}
+export interface ProviderDefinition {
+    /** Owning provider id (groups doc pages). */
+    provider: string;
+    /**
+     * The provider's type definitions. ONE entry may be the **universal** `*.*`
+     * entry (`type: "*", subType: "*"`): it is NOT a registered type — its named
+     * `attr` children are COMMON attributes (accepted on every node, registered via
+     * `registry.registerCommonAttrs`). Every other entry is a real `type.subType`.
+     * Optional — a concern (extends-only) provider declares no new types and may
+     * omit this entirely (it carries only `extends`).
+     */
+    types?: TypeDef[];
+    /**
+     * FR-033 S1.5 — DATA-DRIVEN `registry.extend` directives. A **concern** provider
+     * (db / ui / prompt) declares no new types; it reads its attrs from data and ADDS
+     * them to already-registered types via these entries. Applied AFTER `types` in
+     * `applyProviderDefinition`. Optional — a provider with only `types` is unaffected.
+     */
+    extends?: ExtendDef[];
+}
+/**
+ * The code half of the data/code boundary: a `"<type>.<subType>"` → factory map.
+ * The factory constructs the node instance; it stays code (behavior).
+ */
+export type FactoryMap = Record<string, (typeId: TypeId, name: string) => MetaData>;
+/**
+ * Turn a declarative `ProviderDefinition` + a code-supplied factory map into the
+ * `TypeDefinition`s a provider passes to `registry.register()`.
+ *
+ * For each real `TypeDef` (every entry EXCEPT the universal `*.*` entry, which
+ * carries common attrs and is handled by `applyProviderDefinition`): look up its
+ * factory (throws if missing); fan its `children` out so `type: "attr"` entries
+ * become `AttrSchema`s and structural entries become `ChildRule`s; carry `parents`
+ * and the optional `rules`/`example`/`whenToUse` doc fields through onto the
+ * returned `TypeDefinition`.
+ *
+ * BASE-COMPOSITION (FR-033): a non-base subtype that opts in via
+ * `extendsBase: true` additively inherits its `<type>.base`'s `attributes` (dedup
+ * by name) and `childRules` (dedup structurally) — letting a JSON declare
+ * universal-per-type rules once on `base`. Purely additive (a subtype's own
+ * declarations win on a name/shape collision). OFF by default so a subtype that
+ * deliberately declares fewer attrs than base is never widened — inert under S0
+ * (no provider opts in yet), the rail S1 will use.
+ *
+ * Builder-local validation (cheap, structural): an attr entry must be
+ * single-valued (`max === 1`) unless `isArray`; an attr entry's `subType` must be
+ * a single subtype (not a list); every child must have `min >= 0` and
+ * (`max === null || max >= min`).
+ */
+export declare function defineProviderFromData(data: ProviderDefinition, factories: FactoryMap): TypeDefinition[];
+/**
+ * Apply a `ProviderDefinition` to a registry via the ONE uniform path: register
+ * every real `type.subType` (with base-composition) AND register the universal
+ * `*.*` entry's named `attr` children as COMMON attrs. This replaces the bespoke
+ * `commonAttrs` helper — documentation rides the same mechanism as every other
+ * provider.
+ */
+export declare function applyProviderDefinition(registry: TypeRegistry, data: ProviderDefinition, factories: FactoryMap): void;
+/**
+ * Lower the universal `*.*` entry's named `attr` children into `AttrSchema[]` for
+ * `registry.registerCommonAttrs(...)`. Returns `[]` when no `*.*` entry is present.
+ * Same field mapping as `toAttrSchema`. Exported for callers that register common
+ * attrs themselves; `applyProviderDefinition` is the usual door.
+ */
+export declare function universalCommonAttrs(data: ProviderDefinition): AttrSchema[];
+//# sourceMappingURL=provider-data.d.ts.map

package/dist/provider-data.d.ts.map

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

package/dist/provider-data.js

@@ -0,0 +1,271 @@
+// FR-033 — provider definitions as declarative data.
+//
+// A provider's *declarative* metamodel definition (vocabulary + attr constraints
+// + child cardinality + descriptions + rule prose) lives as data; the factory
+// (behavior) is supplied separately. `defineProviderFromData` turns that data +
+// a code-supplied factory map into the `TypeDefinition`s a provider passes to
+// `registry.register()`. This is the data/code boundary: declarative facts and
+// rule *prose* are data; factories, imperative validation, and codegen stay code.
+//
+// See spec/superpowers/specs/2026-06-13-metamodel-self-description-design.md §3 +
+// §3.1 (the constraint model). This module implements Plan Task 1, Task 2, and
+// the format half of Task 7.
+import { TypeId } from "./registry.js";
+import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
+import { SUBTYPE_BASE } from "./shared/base-types.js";
+const ATTR_CHILD_TYPE = "attr";
+/** Whether a `ChildDef` declares an attribute (vs a structural child). */
+function isAttrChild(child) {
+    return child.type === ATTR_CHILD_TYPE;
+}
+/**
+ * Whether a `TypeDef` is the UNIVERSAL `*.*` entry — the carrier for COMMON
+ * attributes (attrs accepted on EVERY node). It is NOT a real registered type;
+ * its named `attr` children are routed to `registry.registerCommonAttrs(...)` by
+ * the unified apply path. Documentation uses this; ordinary providers do not.
+ */
+function isUniversalEntry(t) {
+    return t.type === CHILD_RULE_WILDCARD && t.subType === CHILD_RULE_WILDCARD;
+}
+/**
+ * Turn a declarative `ProviderDefinition` + a code-supplied factory map into the
+ * `TypeDefinition`s a provider passes to `registry.register()`.
+ *
+ * For each real `TypeDef` (every entry EXCEPT the universal `*.*` entry, which
+ * carries common attrs and is handled by `applyProviderDefinition`): look up its
+ * factory (throws if missing); fan its `children` out so `type: "attr"` entries
+ * become `AttrSchema`s and structural entries become `ChildRule`s; carry `parents`
+ * and the optional `rules`/`example`/`whenToUse` doc fields through onto the
+ * returned `TypeDefinition`.
+ *
+ * BASE-COMPOSITION (FR-033): a non-base subtype that opts in via
+ * `extendsBase: true` additively inherits its `<type>.base`'s `attributes` (dedup
+ * by name) and `childRules` (dedup structurally) — letting a JSON declare
+ * universal-per-type rules once on `base`. Purely additive (a subtype's own
+ * declarations win on a name/shape collision). OFF by default so a subtype that
+ * deliberately declares fewer attrs than base is never widened — inert under S0
+ * (no provider opts in yet), the rail S1 will use.
+ *
+ * Builder-local validation (cheap, structural): an attr entry must be
+ * single-valued (`max === 1`) unless `isArray`; an attr entry's `subType` must be
+ * a single subtype (not a list); every child must have `min >= 0` and
+ * (`max === null || max >= min`).
+ */
+export function defineProviderFromData(data, factories) {
+    // Pre-compute each type's OWN lowered attrs + childRules, keyed by "type.subType",
+    // so base-composition can fold a base's contributions into its subtypes. A
+    // concern (extends-only) provider may omit `types` entirely.
+    const realTypes = (data.types ?? []).filter((t) => !isUniversalEntry(t));
+    const lowered = new Map();
+    for (const t of realTypes) {
+        const key = `${t.type}.${t.subType}`;
+        const attributes = [];
+        const childRules = [];
+        for (const child of t.children ?? []) {
+            validateCardinality(data.provider, key, child);
+            if (isAttrChild(child)) {
+                attributes.push(toAttrSchema(data.provider, key, child));
+            }
+            else {
+                childRules.push(toChildRule(child));
+            }
+        }
+        lowered.set(key, { attributes, childRules });
+    }
+    return realTypes.map((t) => {
+        const key = `${t.type}.${t.subType}`;
+        const factory = factories[key];
+        if (factory === undefined) {
+            throw new Error(`defineProviderFromData(${data.provider}): no factory for "${key}"`);
+        }
+        const self = lowered.get(key);
+        const { attributes, childRules } = composeWithBase(t, self, lowered);
+        return {
+            typeId: new TypeId(t.type, t.subType),
+            description: t.description,
+            factory,
+            childRules,
+            attributes,
+            ...(t.dataType !== undefined ? { dataType: t.dataType } : {}),
+            ...(t.parents !== undefined ? { parents: t.parents } : {}),
+            ...(t.rules !== undefined ? { rules: t.rules } : {}),
+            ...(t.example !== undefined ? { example: t.example } : {}),
+            ...(t.whenToUse !== undefined ? { whenToUse: t.whenToUse } : {}),
+            ...(t.maxOccurs !== undefined ? { maxOccurs: t.maxOccurs } : {}),
+            ...(t.defaultName !== undefined ? { defaultName: t.defaultName } : {}),
+        };
+    });
+}
+/**
+ * Apply a `ProviderDefinition` to a registry via the ONE uniform path: register
+ * every real `type.subType` (with base-composition) AND register the universal
+ * `*.*` entry's named `attr` children as COMMON attrs. This replaces the bespoke
+ * `commonAttrs` helper — documentation rides the same mechanism as every other
+ * provider.
+ */
+export function applyProviderDefinition(registry, data, factories) {
+    for (const def of defineProviderFromData(data, factories)) {
+        registry.register(def);
+    }
+    const commonAttrs = universalCommonAttrs(data);
+    if (commonAttrs.length > 0) {
+        registry.registerCommonAttrs(commonAttrs);
+    }
+    applyExtends(registry, data);
+}
+/**
+ * Apply a definition's `extends` directives (FR-033 S1.5) via `registry.extend`.
+ * For each directive: resolve the target subtypes (`"*"` → every registered subtype
+ * of the type; a list → each named subtype; a string → that one), lower its `attr`
+ * children to `AttrSchema[]`, and `registry.extend(type, sub, { attributes })`.
+ * Concern providers contribute attrs only — a non-`attr` child is rejected.
+ */
+function applyExtends(registry, data) {
+    for (const ext of data.extends ?? []) {
+        const attributes = [];
+        for (const child of ext.children) {
+            if (!isAttrChild(child)) {
+                throw new Error(`applyProviderDefinition(${data.provider}): extends "${ext.type}" may only carry attr ` +
+                    `children; found a structural child "${child.type}".`);
+            }
+            validateCardinality(data.provider, ext.type, child);
+            attributes.push(toAttrSchema(data.provider, ext.type, child));
+        }
+        for (const subType of resolveExtendSubTypes(registry, ext)) {
+            registry.extend(ext.type, subType, { attributes });
+        }
+    }
+}
+/**
+ * Resolve an `ExtendDef`'s `subType` selector to concrete subtype names:
+ *   - `"*"` → every currently-registered subtype of `ext.type`;
+ *   - a list → each named subtype, in declared order;
+ *   - a single string → that one subtype.
+ */
+function resolveExtendSubTypes(registry, ext) {
+    if (ext.subType === CHILD_RULE_WILDCARD) {
+        return registry.allSubTypesOf(ext.type);
+    }
+    return Array.isArray(ext.subType) ? ext.subType : [ext.subType];
+}
+/**
+ * Lower the universal `*.*` entry's named `attr` children into `AttrSchema[]` for
+ * `registry.registerCommonAttrs(...)`. Returns `[]` when no `*.*` entry is present.
+ * Same field mapping as `toAttrSchema`. Exported for callers that register common
+ * attrs themselves; `applyProviderDefinition` is the usual door.
+ */
+export function universalCommonAttrs(data) {
+    const universal = (data.types ?? []).find(isUniversalEntry);
+    if (universal === undefined)
+        return [];
+    const key = `${universal.type}.${universal.subType}`;
+    const out = [];
+    for (const child of universal.children ?? []) {
+        if (!isAttrChild(child)) {
+            throw new Error(`applyProviderDefinition(${data.provider}): the universal "${key}" entry may only ` +
+                `carry attr children (common attrs); found a structural child "${child.type}".`);
+        }
+        validateCardinality(data.provider, key, child);
+        out.push(toAttrSchema(data.provider, key, child));
+    }
+    return out;
+}
+/**
+ * Fold a real `TypeDef`'s OWN lowered attrs/childRules with its `<type>.base`'s
+ * (when the definition declares one and this subtype is not itself `base`).
+ * Additive: own entries win on a name (attr) / structural-shape (rule) collision;
+ * base entries the subtype lacks are appended. A NO-OP when there is no base in
+ * THIS definition, or when the subtype already declares the full base set.
+ */
+function composeWithBase(t, self, lowered) {
+    // OFF by default (S0): a subtype inherits its base only when it opts in via
+    // `extendsBase: true`. Keeps the current canonical byte-identical — no provider
+    // sets it yet — while the rail is in place for S1.
+    if (t.extendsBase !== true)
+        return self;
+    if (t.subType === SUBTYPE_BASE)
+        return self;
+    const base = lowered.get(`${t.type}.${SUBTYPE_BASE}`);
+    if (base === undefined)
+        return self;
+    const attributes = [...self.attributes];
+    const haveAttr = new Set(attributes.map((a) => a.name));
+    for (const baseAttr of base.attributes) {
+        if (!haveAttr.has(baseAttr.name)) {
+            attributes.push(baseAttr);
+            haveAttr.add(baseAttr.name);
+        }
+    }
+    const childRules = [...self.childRules];
+    const haveRule = new Set(childRules.map(childRuleId));
+    for (const baseRule of base.childRules) {
+        const id = childRuleId(baseRule);
+        if (!haveRule.has(id)) {
+            childRules.push(baseRule);
+            haveRule.add(id);
+        }
+    }
+    return { attributes, childRules };
+}
+/** A stable structural identity for a ChildRule (base-composition dedup). */
+function childRuleId(rule) {
+    const sub = typeof rule.childSubType === "string"
+        ? rule.childSubType
+        : [...rule.childSubType].sort().join("|");
+    return [
+        rule.childType,
+        sub,
+        rule.childName,
+        rule.min ?? "",
+        rule.max === null ? "null" : (rule.max ?? ""),
+        rule.named ?? "",
+    ].join(" ");
+}
+/** Validate the min/max axis (and attr single-valuedness) for one child entry. */
+function validateCardinality(provider, typeKey, child) {
+    if (child.min < 0) {
+        throw new Error(`defineProviderFromData(${provider}): child "${child.name}" on "${typeKey}" has min ${child.min} < 0.`);
+    }
+    if (child.max !== null && child.max < child.min) {
+        throw new Error(`defineProviderFromData(${provider}): child "${child.name}" on "${typeKey}" has max ${child.max} < min ${child.min}.`);
+    }
+    if (isAttrChild(child) && child.max !== 1 && child.isArray !== true) {
+        throw new Error(`defineProviderFromData(${provider}): attr "${child.name}" on "${typeKey}" is single-valued ` +
+            `(max must be 1; a list-valued attr sets isArray: true).`);
+    }
+}
+/** An `type: "attr"` child entry IS an `AttrSchema`. */
+function toAttrSchema(provider, typeKey, child) {
+    if (Array.isArray(child.subType)) {
+        throw new Error(`defineProviderFromData(${provider}): attr "${child.name}" on "${typeKey}" declares a list subType ` +
+            `— an attr's value-type is a single subtype.`);
+    }
+    return {
+        name: child.name,
+        ...(child.subType !== undefined ? { valueType: child.subType } : {}),
+        ...(child.isArray !== undefined ? { isArray: child.isArray } : {}),
+        required: child.min >= 1,
+        ...(child.default !== undefined ? { default: child.default } : {}),
+        ...(child.allowedValues !== undefined
+            ? { allowedValues: child.allowedValues }
+            : {}),
+        description: child.description ?? "",
+        ...(child.rules !== undefined ? { rules: child.rules } : {}),
+        ...(child.example !== undefined ? { example: child.example } : {}),
+        ...(child.whenToUse !== undefined ? { whenToUse: child.whenToUse } : {}),
+    };
+}
+/** A structural (`type !== "attr"`) child entry IS a `ChildRule`. */
+function toChildRule(child) {
+    return {
+        childType: child.type,
+        // A structural child always supplies a subType; default to the `"*"`
+        // wildcard if (unusually) omitted, so the rule stays well-formed.
+        childSubType: child.subType ?? CHILD_RULE_WILDCARD,
+        childName: child.name,
+        min: child.min,
+        max: child.max,
+        ...(child.named !== undefined ? { named: child.named } : {}),
+    };
+}
+//# sourceMappingURL=provider-data.js.map

package/dist/provider-data.js.map

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

package/dist/provider.d.ts

@@ -16,5 +16,7 @@ export interface MetaDataTypeProvider {
  * ordering constraint between them keep input order. Throws on a duplicate
  * provider id, a missing dependency, or a dependency cycle.
  */
-export declare function composeRegistry(providers: readonly MetaDataTypeProvider[]): TypeRegistry;
+export declare function composeRegistry(providers: readonly MetaDataTypeProvider[], opts?: {
+    validate?: boolean;
+}): TypeRegistry;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,YAAY,CAOd"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAK7C,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,YAAY,CAsBd"}

package/dist/provider.js

@@ -6,18 +6,32 @@
 // composeRegistry. See docs/superpowers/specs/2026-05-17-type-provider-model-design.md.
 import { TypeRegistry } from "./registry.js";
 import { MetaModelError } from "./errors.js";
+import { mergeConstraints } from "./constraint-merge.js";
+import { validateConstraints } from "./constraint-validate.js";
 /**
  * Build a TypeRegistry by composing providers. Providers are topologically
  * sorted by their `dependencies`; the sort is stable — providers with no
  * ordering constraint between them keep input order. Throws on a duplicate
  * provider id, a missing dependency, or a dependency cycle.
  */
-export function composeRegistry(providers) {
+export function composeRegistry(providers, opts) {
     const ordered = topoSortProviders(providers);
     const registry = new TypeRegistry();
     for (const provider of ordered) {
         provider.registerTypes(registry);
     }
+    // FR-033 — opt-in metamodel contradiction gate. The library bootstrap (the
+    // loader's default registry) sets validate:true so a contradictory provider set
+    // fails fast at bootstrap (mirrors ADR-0023 strictness). Off by default so
+    // synthetic/partial registries (tests, incremental composition) are unaffected.
+    if (opts?.validate === true) {
+        const contradictions = validateConstraints(mergeConstraints(registry), registry);
+        if (contradictions.length > 0) {
+            throw new MetaModelError(`composeRegistry: the provider set has ${contradictions.length} metamodel ` +
+                `constraint contradiction(s) (FR-033):\n` +
+                contradictions.map((e) => `  - ${e.message}`).join("\n"), { code: "ERR_INVALID_METAMODEL_CONSTRAINT" });
+        }
+    }
     return registry;
 }
 function topoSortProviders(providers) {

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,oEAAoE;AACpE,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAc7C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA0C;IAE1C,MAAM,OAAO,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;IACpC,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,iBAAiB,CACxB,SAA0C;IAE1C,sBAAsB;IACtB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,cAAc,CAAC,2CAA2C,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,2BAA2B,EAAE,CAAC,CAAC;QACtH,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IACD,4BAA4B;IAC5B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,IAAI,cAAc,CACtB,8BAA8B,CAAC,CAAC,EAAE,iBAAiB,GAAG,qCAAqC,EAC3F,EAAE,IAAI,EAAE,iCAAiC,EAAE,CAC5C,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,OAAO,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,CAAC,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACtD,CAAC;QACF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,SAAS;iBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;iBACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpB,MAAM,IAAI,cAAc,CACtB,sDAAsD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EACzE,EAAE,IAAI,EAAE,+BAA+B,EAAE,CAC1C,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/registry-coverage.d.ts

@@ -0,0 +1,99 @@
+/** One attr in the registry manifest. */
+export interface ManifestAttr {
+    name: string;
+    valueType: string | null;
+    required: boolean;
+}
+/** One registered (type, subType) with its declared attrs. */
+export interface ManifestType {
+    type: string;
+    subType: string;
+    attrs: ManifestAttr[];
+}
+/** The canonical registry manifest (expected-registry.json). */
+export interface RegistryManifest {
+    types: ManifestType[];
+    commonAttrs: ManifestAttr[];
+    defaultSubTypes: Record<string, string>;
+}
+/** Per-subtype attr coverage: which declared attrs no fixture sets. */
+export interface UntestedAttrs {
+    /** The `"<type>.<subType>"` key. */
+    key: string;
+    /** Sorted attr names declared on this subtype that NO fixture exercises. */
+    untestedAttrs: string[];
+}
+/** The full coverage report — all collections sorted for determinism. */
+export interface CoverageReport {
+    /** Total registered `(type, subType)` keys. */
+    registeredSubTypeCount: number;
+    /** Registered keys at least one fixture exercises. */
+    exercisedSubTypeCount: number;
+    /** Sorted registered keys NO fixture exercises (the valuable backlog). */
+    untestedSubTypes: string[];
+    /**
+     * Per EXERCISED subtype, the declared attrs no fixture sets. Only includes
+     * subtypes that ARE exercised (an untested subtype's attrs are all untested
+     * by definition — listing them would be noise). Sorted by key; only entries
+     * with a non-empty `untestedAttrs` list are included.
+     */
+    untestedAttrsByExercisedSubType: UntestedAttrs[];
+}
+/** The snapshot written to disk — a stable, diffable subset of the report. */
+export interface CoverageSnapshot {
+    registeredSubTypeCount: number;
+    exercisedSubTypeCount: number;
+    untestedSubTypes: string[];
+    untestedAttrsByExercisedSubType: UntestedAttrs[];
+}
+/** What a single fixture corpus exercises. */
+interface Usage {
+    /** Set of `"<type>.<subType>"` keys seen in any fixture node. */
+    subTypes: Set<string>;
+    /** key → set of attr names (sans `@` prefix) set on a node of that subtype. */
+    attrsByKey: Map<string, Set<string>>;
+}
+/** Scan a set of corpus roots, unioning vocabulary usage across all of them. */
+export declare function scanFixtureUsage(roots: readonly string[]): Usage;
+/**
+ * Compute the untested-vocabulary coverage report.
+ *
+ * @param manifest the parsed registry manifest (the registered vocabulary)
+ * @param roots    fixture-corpus directory roots to scan for usage
+ */
+export declare function computeCoverage(manifest: RegistryManifest, roots: readonly string[]): CoverageReport;
+/** Project a report into the stable, diffable snapshot shape. */
+export declare function toSnapshot(report: CoverageReport): CoverageSnapshot;
+/** Serialize a snapshot as byte-stable JSON (2-space indent, trailing newline). */
+export declare function emitSnapshot(snapshot: CoverageSnapshot): string;
+/** One named coverage regression — an item that became unexercised. */
+export interface CoverageRegression {
+    /** "subtype" — a registered (type, subType) no longer exercised; or "attr". */
+    kind: "subtype" | "attr";
+    /** The `"<type>.<subType>"` key that regressed. */
+    key: string;
+    /** For an attr regression: the attr name that became untested (else undefined). */
+    attr?: string;
+}
+/** The ratchet verdict: ok=true when live coverage is no worse than baseline. */
+export interface RatchetResult {
+    ok: boolean;
+    /** Every named regression (empty when ok). Sorted for determinism. */
+    regressions: CoverageRegression[];
+}
+/**
+ * Compare a live coverage snapshot against a committed baseline and report any
+ * REGRESSION (an item the baseline had exercised that the live run no longer
+ * exercises). Improvements (items that left an untested set) are NOT regressions.
+ *
+ * - subtype regression: a key in `live.untestedSubTypes` not in baseline's set.
+ * - attr regression: an attr in a live subtype's `untestedAttrs` not in the
+ *   baseline's untested-attrs set for that SAME key. (A subtype that newly became
+ *   untested is reported once as a subtype regression — its attrs are not double-
+ *   reported, since an untested subtype has no per-attr entry by construction.)
+ */
+export declare function checkRatchet(baseline: CoverageSnapshot, live: CoverageSnapshot): RatchetResult;
+/** Render the regressions into an actionable, human-readable failure message. */
+export declare function formatRatchetFailure(result: RatchetResult): string;
+export {};
+//# sourceMappingURL=registry-coverage.d.ts.map

package/dist/registry-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-coverage.d.ts","sourceRoot":"","sources":["../src/registry-coverage.ts"],"names":[],"mappings":"AA8BA,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAMD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,+BAA+B,EAAE,aAAa,EAAE,CAAC;CAClD;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,+BAA+B,EAAE,aAAa,EAAE,CAAC;CAClD;AAMD,8CAA8C;AAC9C,UAAU,KAAK;IACb,iEAAiE;IACjE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,+EAA+E;IAC/E,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACtC;AA0HD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAchE;AAUD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,cAAc,CAoChB;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAOnE;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAE/D;AAmBD,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,gBAAgB,GACrB,aAAa,CA6Cf;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAsBlE"}