@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/registry.d.ts

@@ -0,0 +1,300 @@
+import { DerivedOp, SchemaEntry } from "./schemas.js";
+import { SubEntityClass } from "./defineSubEntity.js";
+import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
+import { Config } from "./Config.js";
+import { z } from "zod";
+
+//#region src/framework/registry.d.ts
+/** What a computed field is handed: the member's own stored fields, the config it lives in, and the
+ *  path it is filed under. An object because three arguments in a fixed order is an order to
+ *  remember, and because `config` was previously named `source` at both declaration sites — a word
+ *  that now means the config a dependency resolves to. */
+interface ComputedInput {
+  readonly member: Record<string, unknown>;
+  readonly config: Config;
+  /** Identity, so a field that defaults to it can say so (`LinkedSystem.displayName`). */
+  readonly path: string;
+}
+/**
+ * Virtual fields, recomputed on read and never stored — a pure fn of {@link ComputedInput}.
+ *
+ * Declared by stored kinds too, not only derived ones. A fact that is a derivation of what an entity
+ * already holds belongs on the entity, computed: provenance is the case that forced this — whether a
+ * Token is borrowed, and from where, is read off the source qualifier in its own `value`, so any
+ * consumer re-deriving it is a second place that knows the entity's shape and a second place to get it
+ * wrong. Studio had one; the CLI and the AI read tools would each have wanted their own.
+ */
+type ComputedFields = Record<string, (input: ComputedInput) => unknown>;
+/** A derived kind's compute metadata — set via `defineDerivedEntity`. Members are computed from a
+ *  source config (`deriveMembers`); `overridable` fields accept a sparse user override; `computed`
+ *  fields are recomputed on read (never stored). Absent for a normal (stored) kind. */
+interface DerivedKind {
+  readonly deriveMembers: (source: Config) => Record<string, Record<string, unknown>>;
+  readonly overridable?: readonly string[];
+  readonly computed?: ComputedFields;
+}
+/**
+ * Whether a kind may be borrowed from a linked source: a flat answer, or one judged per pair of
+ * configs. See {@link EntityKind.linkable}.
+ */
+type Linkable = boolean | ((args: {
+  readonly config: Config;
+  readonly source: Config;
+}) => boolean);
+interface EntityKind {
+  readonly name: string;
+  /** The entity class's name (`style-property` → `StyleProperty`) — what a consumer writes to reach
+   *  it (`StyleProperty.ref(...)`, `Token.group(...)`).
+   *
+   *  Derived once, here, because three places used to re-derive it from the kind and one of them
+   *  drifted: the authoring reference told consumers the helper was `styleProperty` while the code
+   *  emitters wrote `StyleProperty`. A fact about a kind belongs on the kind.
+   *
+   *  A variant declares its own, since the derivation can't reach it: `NativeToken` implements kind
+   *  `token`, so deriving the name from the kind would emit `Token.item(…)` into a native config — a
+   *  class that file never imports, checking the body against the wrong schema. `extend({ entityName })`
+   *  is where the entity says its own name instead. */
+  readonly entityName: string;
+  /** Human label for one item — for UI/docs surfaces (a folder header, a tool label). Defaults
+   *  to a title-cased `name`; set via `defineEntity({ label })`. */
+  readonly label: string;
+  /** Human label for the collection (a folder of items). Defaults to `label + 's'`; set via
+   *  `defineEntity({ labelPlural })` when the naive plural is wrong (`Style Properties`). */
+  readonly labelPlural: string;
+  readonly fieldKeys: string[];
+  readonly groupFieldKeys: string[];
+  /** {@link ComputedFields} this kind declares — evaluated by `Config.resolve`, present on reads, and
+   *  excluded from `toJSON` so no derivation is ever written into an artifact. */
+  readonly computed?: ComputedFields;
+  readonly computedKeys: readonly string[];
+  /** The first declared field — a bare value (`'color/brand': '#1167f4'`) is shorthand
+   *  for it, so the common case skips the object wrapper. */
+  readonly primaryField: string;
+  /** The keyed sub-entity collections, field name → its definition (`layers` → `Layer`). These
+   *  are the fields sub-entity CRUD (create/update/delete/reorder a member) may target, and each
+   *  definition carries the member's own schema + labels rather than them being inferred. */
+  readonly subEntities: Readonly<Record<string, SubEntityClass>>;
+  readonly groupCreateSchema: z.ZodTypeAny;
+  /** The kind's canonical op map, keyed by verb — defaults (CRUD + reads + sub-*) merged with the
+   *  author's `schemas` param (override / add / remove). `opsForKind` and the Operation entity read
+   *  it. Empty for a derived kind. */
+  readonly schemas: Readonly<Record<string, SchemaEntry>>;
+  /** Set for a kind declared via `defineDerivedEntity` — its members are computed, read-only
+   *  (+ optional sparse overrides), and it derives no CRUD operations. */
+  readonly derived?: DerivedKind;
+  /**
+   * Declared by a kind whose items name an external source, listing the fields that decide which
+   * source. An item of such a kind is a slug other entities borrow through, so values recorded from
+   * it are only true while these fields hold — editing one invalidates them, editing any other field
+   * (a display label) does not.
+   *
+   * Declared here rather than tested for by name in the framework, which knows borrowing as a
+   * mechanism and must not know which kind implements it.
+   */
+  readonly sourceIdentity?: readonly string[];
+  /**
+   * The subset of {@link sourceIdentity} that names *which* system, leaving out the fields that name a
+   * version of it. Two pins agreeing on these draw on one origin at possibly different versions, which
+   * is what {@link Config.originOf} compares. Falls back to `sourceIdentity` when not declared.
+   */
+  readonly sourceOrigin?: readonly string[];
+  /**
+   * Whether an author ever writes a ref to this kind by hand. Default true; a kind whose paths the
+   * build mints declares `false`.
+   *
+   * What reads it is the emitted `uds-env.d.ts`, whose `RegisteredPaths` exists to type
+   * `<Entity>.ref(...)` at an authoring site. A kind with no authoring site gets nothing from being
+   * enumerated there and costs something real: `file`'s paths are paths in the source tree, so a
+   * checked-in `uds-env.d.ts` would change every time a component file is added, renamed or moved —
+   * churn on a generated artifact for a reason that has nothing to do with the design system.
+   *
+   * Declared by the kind rather than tested for by name, the same as {@link sourceIdentity}: the
+   * emitter knows "these paths are a type surface" as a property, and must not know which kinds have
+   * it. Omitting a kind is safe by construction — `PathOf` falls back to `string` for any kind the
+   * augmentation does not mention, which is the same branch an empty kind already takes.
+   */
+  readonly authoredRefs?: boolean;
+  /**
+   * Whether this kind may be borrowed from a linked source at all — default true; a kind that is
+   * about this config rather than about design declares `false`.
+   *
+   * A statement about meaning, not capability: every kind a source owns and this config declares
+   * could land (`Config.borrowableKinds` is exactly that intersection), and these are the ones where
+   * landing is incoherent — a `file`'s path is a path in your own source tree, and a linked-system pin
+   * would make that source's own dependencies yours, at their versions.
+   *
+   * Declared by the kind rather than tested for by name, the same as {@link sourceIdentity} — the
+   * borrow op knows "some kinds are not borrowable" as a property, never which. Omitting it is safe:
+   * a kind that says nothing is borrowable, which is every design-bearing kind.
+   *
+   * A kind whose answer depends on the pair of configs declares a predicate instead. A `package` row is
+   * a claim about what the holding config's renders import, so it carries across two configs of one
+   * platform and not across a web system and a native one. Readers go through {@link kindBorrowable}.
+   */
+  readonly linkable?: Linkable;
+  /**
+   * The group fields a borrowed group does NOT inherit — default none, so a source's group node
+   * arrives whole.
+   *
+   * A group node carries two sorts of field, and only one of them is the source's to say. `variants`
+   * and `sizes` on an icon library describe the set itself, so a consumer that borrows the library
+   * needs them: without `variants` the borrowed `Icon`'s `variant` prop has no domain and
+   * `icon:<slug>#variants` resolves to nothing. `cssPrefix` describes how a config EMITS — a borrowed
+   * component's classes carry the consumer's prefix, so inheriting the source's would name classes
+   * this stylesheet does not contain.
+   *
+   * Declared by the kind rather than tested for by name, the same as {@link linkable}: `Config`
+   * knows "some group fields are local" as a property, never which. Omitting it inherits everything,
+   * which is right for every kind whose group node only describes the group.
+   */
+  readonly localGroupFields?: readonly string[];
+  /**
+   * Whether a `/` in this kind's paths is a folder boundary — default true. A kind whose slash is
+   * part of the name (a `Package`'s npm specifier) declares `false`, and `Config.groups` then
+   * synthesizes nothing from a path prefix. See {@link EntityKindSpec.emergentGroups}.
+   */
+  readonly emergentGroups?: boolean;
+  /**
+   * Declared by a kind that has exactly one item, at a path equal to the kind's name — a config's
+   * `settings`, where the thing being written is the config itself and there is nothing to create,
+   * delete, rename or reorder.
+   *
+   * What the framework does with it: registering the kind seeds the item from the schema's defaults,
+   * so every field has to be optional or defaulted (checked when the kind is built); the catalog drops
+   * `create`, `delete`, `rename`, `reorder` and the group verbs; every op's `path` defaults to the kind
+   * name so a caller can omit it; and `register` takes the item's body under the accessor directly,
+   * with no path level. Whether the item is borrowed or refed is the kind's own declaration, as for
+   * any other kind.
+   *
+   * Declared here so a singleton is an ordinary kind to every surface — patches, undo, rebase, the
+   * changes list, the agent catalog — rather than a second thing each of them special-cases.
+   */
+  readonly singleton?: true;
+  /**
+   * The collection a member ref addresses when it names no collection — `package:react-native#View`
+   * rather than `#View`.
+   *
+   * Declared, never inferred from "the kind has exactly one sub-entity": that rule would silently
+   * re-point every stored ref the day a second one is added. A kind that declares none keeps the
+   * qualified form, which is what `component:Input#props/disabled` needs, since several collections
+   * mean the ref has to say which.
+   */
+  readonly bareMember?: string;
+  /**
+   * Declared by a source kind that can be resolved: the schemas its resolutions' two branches are
+   * validated against — `{ resolved, unavailable }`, see {@link SourceResolutionSchemas}.
+   *
+   * Separate from {@link sourceIdentity} because they are separate capabilities. `sourceIdentity` makes
+   * a kind borrowable — its items become slugs a ref can qualify with, which is all an emit-and-read
+   * path needs. This makes it resolvable, which only `Config.load` needs. A kind can honestly be the
+   * first without the second.
+   *
+   * Here rather than in the framework because the payloads are the kind's vocabulary: what "resolved"
+   * means for a linked system (a config path, or a systemId at a version) is not what it would mean
+   * for a linked package (a lockfile entry), and a union naming one is a shape the other cannot fill.
+   * The framework contributes the `status` tag and nothing else — `resolutionSchema` composes the two.
+   */
+  readonly sourceResolution?: SourceResolutionSchemas;
+  /**
+   * Declared by a source kind that records a bulk take: whether one of its pins still covers a
+   * borrowed entity — `bulkAdopts(pin's body, the borrow's kind/accessor/source path)`.
+   *
+   * Read by the delete gate. Taking a kind wholesale and then deleting one of the entities that
+   * arrived is two statements that disagree — a re-run can't tell a path you removed on purpose from
+   * one you never took — so the delete is refused while the declaration still covers it. The
+   * framework knows that shape; only the kind knows where the record lives and how it's keyed.
+   *
+   * The `path` handed in is the path the source spells, not the local one, since a declaration names
+   * what was taken from the source and `to` lets the two differ. A kind that records nothing declares
+   * nothing, and no delete is ever refused for it.
+   */
+  readonly bulkAdopts?: (args: BulkQuery) => boolean;
+  /** What the declared source lays over the entity at this path, when it declares anything. */
+  readonly bulkOverlay?: (args: BulkQuery) => SourceOverlay | undefined;
+  /**
+   * Every path this declaration says anything about, as written — the three reads above answer for a
+   * path you already have, and this is what enumerates them.
+   *
+   * The inverse direction, and the only one that can see a directive aimed at nothing: a check driven
+   * by the source's catalogue asks "does the declaration mention this path", so a misspelled path is
+   * never a question anyone puts. It also costs less, since the declarations are a handful of entries
+   * where a catalogue is thousands.
+   *
+   * `accessor` is returned as the declaration spells it, unresolved, since an accessor this config has
+   * no kind for is exactly one of the mistakes worth reporting.
+   */
+  readonly bulkDirectives?: (body: Record<string, unknown>) => {
+    accessor: string;
+    path: string;
+  }[];
+  /**
+   * The field-path delta that lands `overlay` on this path — the write {@link bulkOverlay} has no
+   * counterpart for, since only the kind knows where a directive is stored.
+   *
+   * Asked by `Config.apply`'s `update` handler when an edit lands on a minted row: the row has no
+   * body of its own to take the edit, so the edit becomes a patch on the declared source's own item
+   * instead, at whatever field this returns. A kind that declares {@link bulkOverlay} but not this one
+   * can be read but never edited through a minted row.
+   */
+  readonly bulkOverlayWrite?: (args: BulkOverlayWrite) => Record<string, unknown>;
+  /**
+   * Edges this kind's data implies by name rather than by ref — `nameEdges(body)` for one item.
+   *
+   * A record that carries identity in a key is invisible to `collectRefs`: a component's style bag is
+   * keyed `bg`, so nothing said it depends on `style-property:bg`, and both halves of a rename broke
+   * quietly — the delete wasn't refused and the cascade had nothing to rewrite. `namesMembersOf`
+   * already draws this distinction for a sibling collection's names; this is the same statement about
+   * another kind's items.
+   *
+   * Must be a pure function of the body it is handed. That is what lets these edges ride the same
+   * incremental index update as ref-borne ones — a derivation that read another kind's state would be
+   * recomputed only when this entity changed, so renaming the thing it read would leave it stale, and
+   * silently-stale reporting is what this whole mechanism exists to remove.
+   */
+  readonly nameEdges?: (data: unknown) => string[];
+  /**
+   * Whether an item's leaf (its last path segment) is unique across the kind, so the leaf alone names
+   * it. `Config.resolve` then answers a bare leaf, and an edge keyed by the leaf (a style bag's `_dark`)
+   * counts as pointing at the item. A modifier declares it: a bag key and a force attribute spell the
+   * leaf, since neither can hold a slash.
+   */
+  readonly uniqueLeaves?: boolean;
+  /**
+   * Rules that hold across the kind's items and groups together, which no single item's schema can
+   * see — a typed group nested under another typed group. Returns the violations as sentences; a
+   * write that leaves any is refused. Checked after registration and after every patch on the kind,
+   * never on hydration, so a stored artifact stays loadable.
+   */
+  readonly invariants?: (config: Config) => string[];
+  /**
+   * Rewrite one name wherever this kind's data holds it as a key — the cascade half of
+   * {@link nameEdges}, applied by `Config.apply`'s rename alongside `rewriteRefs`.
+   *
+   * Takes and returns the whole body. Order-preserving is the caller's responsibility and it matters:
+   * a style bag's key order is declaration order in the emitted rule, so rebuilding a record in a
+   * different order changes what paints.
+   */
+  readonly rewriteName?: (data: unknown, from: string, to: string) => unknown;
+  /**
+   * Where this kind keeps its style bags — a set of declarations keyed by the property being set.
+   *
+   * The third statement about the same records {@link nameEdges} and {@link rewriteName} describe, and
+   * the one a reader needs: those two answer for a bag's keys, and a bag's values carry names too. A
+   * leaf that resolves is stored as a ref (`bindBagTokens`), so the ref graph sees it — but a leaf
+   * that resolves to nothing stays a plain string, which is exactly the case worth reporting and the
+   * one nothing could find, because no generic walk knew where a kind's bags were.
+   *
+   * Declared per kind for the same reason as the other two: only the kind knows that a component's
+   * bags are its style rules' per-layer maps, its anatomy nodes' props, and its own defaults. Missing
+   * a position is not a partial answer but a silent one.
+   */
+  readonly styleBags?: (data: unknown) => {
+    bag: Record<string, unknown>;
+  }[];
+}
+/** Every operation a kind exposes — its merged `schemas` map, flattened to `{ kind, verb, ... }`.
+ *  The single derivation the Operation entity maps over; nothing hardcodes a CRUD list. Reads the
+ *  kind def a `Config` holds (`config.entityOf(kind)`); `undefined` → no ops. */
+declare function opsForKind(entry: EntityKind | undefined, config?: Config): DerivedOp[];
+//#endregion
+export { ComputedFields, ComputedInput, EntityKind, Linkable, opsForKind };

package/dist/framework/registry.js

@@ -0,0 +1,104 @@
+import { compileSchema } from "./utils/compiled-schema.js";
+import { deriveCreateSchema, fieldKeys } from "./utils/field-schema.js";
+import { dataSchema, defaultSchemas, mergeSchemas, resolveFields, resolveInputSchema } from "./schemas.js";
+import { sourceSlugs } from "./source-integrity.js";
+//#region src/framework/registry.ts
+/**
+* Whether `entry`'s kind may be borrowed into `config` from `source`. The one reader of
+* {@link EntityKind.linkable}, so a predicate and a boolean are asked the same way everywhere.
+*
+* A predicate with no source to judge answers no: the question is about a pair, and half of one is
+* not enough to say the borrow is sound.
+*/
+function kindBorrowable(entry, { config, source }) {
+	if (!entry) return false;
+	const { linkable } = entry;
+	if (typeof linkable === "function") return source !== void 0 && linkable({
+		config,
+		source
+	});
+	return linkable !== false;
+}
+/** `style-property` → `StyleProperty`. The kind→class-name rule, in one place. */
+function entityClassName(kind) {
+	const camel = kind.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+	return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+/** A kind name → a Title-Cased default label (`style-property` → `Style Property`). The fallback for
+*  an unregistered name (a synthetic UI group); `Config.entityLabel` uses it. */
+function titleCase(kind) {
+	return kind.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+/** Derive a kind's immutable metadata from its field schemas — the value a `defineEntity`/
+*  `defineDerivedEntity` attaches to its class and a `Config.register` stores in `#entities`. */
+function buildKind(spec) {
+	const { name, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, invariants } = spec;
+	const allComputed = {
+		sources: ({ member, config }) => sourceSlugs(member, config),
+		borrowedFrom: ({ config, path }) => config.borrowedFrom(name, path),
+		...computed
+	};
+	const resolvedLabel = label ?? titleCase(name);
+	const keys = fieldKeys(resolveFields(fields));
+	const subs = Object.fromEntries(Object.entries(subEntities).filter(([, def]) => def !== void 0));
+	const schemas = derived ? {} : mergeSchemas(name, defaultSchemas(name, fields, groupFields, subs, { singleton }), userSchemas, fields);
+	if (singleton) {
+		const seeded = dataSchema(schemas, "replace")?.safeParse({});
+		if (!seeded?.success) throw new Error(`defineEntity: singleton kind "${name}" cannot be seeded from its defaults — every field of a singleton has to be optional or carry a default.${seeded ? ` ${seeded.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}` : ""}`);
+	}
+	return {
+		name,
+		label: resolvedLabel,
+		entityName: spec.entityName ?? entityClassName(name),
+		labelPlural: labelPlural ?? `${resolvedLabel}s`,
+		fieldKeys: keys,
+		groupFieldKeys: fieldKeys(groupFields),
+		computed: allComputed,
+		computedKeys: Object.keys(allComputed),
+		primaryField: singleton ? "" : keys[0] ?? "",
+		subEntities: subs,
+		groupCreateSchema: compileSchema(deriveCreateSchema(groupFields)),
+		schemas,
+		derived,
+		...sourceIdentity ? { sourceIdentity } : {},
+		...sourceOrigin ? { sourceOrigin } : {},
+		...authoredRefs === false ? { authoredRefs } : {},
+		...linkable !== void 0 && linkable !== true ? { linkable } : {},
+		...localGroupFields?.length ? { localGroupFields } : {},
+		...emergentGroups === false ? { emergentGroups } : {},
+		...singleton ? { singleton: true } : {},
+		...bareMember ? { bareMember } : {},
+		...sourceResolution ? { sourceResolution } : {},
+		...bulkAdopts ? { bulkAdopts } : {},
+		...bulkOverlay ? { bulkOverlay } : {},
+		...bulkDirectives ? { bulkDirectives } : {},
+		...bulkOverlayWrite ? { bulkOverlayWrite } : {},
+		nameEdges,
+		rewriteName,
+		styleBags,
+		...uniqueLeaves ? { uniqueLeaves } : {},
+		...invariants ? { invariants } : {}
+	};
+}
+/** Every operation a kind exposes — its merged `schemas` map, flattened to `{ kind, verb, ... }`.
+*  The single derivation the Operation entity maps over; nothing hardcodes a CRUD list. Reads the
+*  kind def a `Config` holds (`config.entityOf(kind)`); `undefined` → no ops. */
+function opsForKind(entry, config) {
+	if (!entry) return [];
+	return Object.entries(entry.schemas).map(([verb, schema]) => ({
+		kind: entry.name,
+		verb,
+		input: resolveInputSchema(schema.input, { config }),
+		readOnly: schema.readOnly,
+		handler: schema.handler,
+		label: schema.label,
+		description: schema.description,
+		scope: schema.scope,
+		creates: schema.creates,
+		approval: schema.approval,
+		title: schema.title,
+		example: schema.example
+	}));
+}
+//#endregion
+export { buildKind, kindBorrowable, opsForKind, titleCase };

package/dist/framework/rejection.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+//#region src/framework/rejection.d.ts
+/**
+ * Why a write was refused. Four, because these are the four things a config can distinguish — three
+ * about the target (missing, taken, not offered) and one about the data. A finer code would be a
+ * finer distinction than `apply` actually makes.
+ */
+type ConfigIssueCode = /** Nothing at that path / no such member — an update, delete or rename with no target. */'NOT_FOUND' /** A create over an existing path, or a rename onto a taken one. */ | 'ALREADY_EXISTS'
+/**
+ * The address cannot be an identity — a path carrying `@` other than as a leading npm scope, which
+ * `isEntityPath` refuses because it cannot be told apart from a borrowed address.
+ *
+ * A distinct code rather than `INVALID_DATA`: nothing about the data is wrong, and the surface that
+ * reports it is a name field rather than a form. This is a distinction `apply` genuinely makes.
+ */
+| 'INVALID_PATH' /** The data failed the entity's own schema. Carries the zod issue's `path`. */ | 'INVALID_DATA'
+/** The kind or the operation isn't offered here — an unknown kind, a kind with no create op, a
+ *  field that isn't a sub-entity collection, a derived kind asked for anything but an override. */
+| 'UNSUPPORTED'
+/** A delete that something still points at. Carries the referrers, because "42 things break" is
+ *  only actionable as a list of which ones. */
+| 'REFERRERS_BLOCK';
+interface ConfigIssue {
+  readonly code: ConfigIssueCode;
+  readonly message: string;
+  /** Where in the written data the problem is (`['layers','icon','bg']`) — zod's own path, for the
+   *  `INVALID_DATA` issues that have one. Absent for the target-shaped codes, which are about the
+   *  patch's address rather than its body. */
+  readonly path?: (string | number)[];
+}
+/**
+ * A write this config refused. `issues` is never empty; `message` joins them so an uncaught one still
+ * reads well in a log.
+ */
+declare class ConfigRejection extends Error {
+  readonly issues: readonly ConfigIssue[];
+  /** Which op of an `edit` batch was refused, by position. Absent for a refusal outside a batch. */
+  readonly opIndex?: number;
+  constructor(issues: readonly ConfigIssue[], {
+    opIndex
+  }?: {
+    opIndex?: number;
+  });
+}
+declare function isConfigRejection(value: unknown): value is ConfigRejection;
+/**
+ * A serialized config this build cannot read: not a config-v2 artifact at all, one whose `options`
+ * slot holds a value no migration placed, or one stamped newer than this build reads
+ * (`SchemaVersionTooNew`). Distinct from {@link ConfigRejection}, which refuses a write to a config
+ * that loaded. The message names the fix (migrate, rebuild, or upgrade).
+ */
+declare class ConfigFormatError extends Error {
+  constructor(message: string);
+}
+declare function isConfigFormatError(value: unknown): value is ConfigFormatError;
+//#endregion
+export { ConfigFormatError, ConfigIssue, ConfigIssueCode, ConfigRejection, isConfigFormatError, isConfigRejection };

package/dist/framework/rejection.js

@@ -0,0 +1,111 @@
+//#region src/framework/rejection.ts
+/**
+* A write this config refused. `issues` is never empty; `message` joins them so an uncaught one still
+* reads well in a log.
+*/
+var ConfigRejection = class extends Error {
+	issues;
+	/** Which op of an `edit` batch was refused, by position. Absent for a refusal outside a batch. */
+	opIndex;
+	constructor(issues, { opIndex } = {}) {
+		super(issues.map((issue) => issue.message).join("; "));
+		this.name = "ConfigRejection";
+		this.issues = issues;
+		if (opIndex !== void 0) this.opIndex = opIndex;
+	}
+};
+function isConfigRejection(value) {
+	if (value instanceof ConfigRejection) return true;
+	return value instanceof Error && value.name === "ConfigRejection" && Array.isArray(value.issues);
+}
+/** Refuse a write for a reason about its target — one issue, no path. */
+function reject(code, message) {
+	throw new ConfigRejection([{
+		code,
+		message
+	}]);
+}
+/**
+* Refuse a write because the data isn't the shape the op takes, where no zod issue says so — the value
+* never reached a schema. A merge's delta is the case: it is applied and the result validated, so a
+* delta that isn't an object has to be refused before the merge walks it as one.
+*/
+function rejectData(message, path) {
+	throw new ConfigRejection([{
+		code: "INVALID_DATA",
+		message,
+		...path ? { path } : {}
+	}]);
+}
+/**
+* Refuse a write because the data failed a schema — one issue per zod issue, each keeping its path.
+*
+* The path appears twice on purpose: as `path`, for a surface that wants to point at the field, and
+* inside `message`, because a message has to stand alone. Every consumer shows the message, and a
+* caller that reads only `path` is the exception — so dropping it from the prose turned
+* "layers.icon.bg — Invalid input" into "Invalid input", which is the one thing a rejection must not do.
+*
+* `context` says what was being written (`Invalid component styles create`), so the whole line reads
+* the way the single-string throw it replaced did.
+*/
+function rejectInvalid(context, error) {
+	throw new ConfigRejection(refusalIssues(error).map((issue) => {
+		const path = issuePath(issue);
+		return {
+			code: "INVALID_DATA",
+			message: `${context}: ${path.join(".") || "(root)"} — ${issue.message}`,
+			...path.length > 0 ? { path } : {}
+		};
+	}));
+}
+/**
+* The issues a refusal reports. A union no member matched is one issue. A union that failed because a
+* member's own check refused the value reports that member's issues instead, at the union's path: the
+* check's sentence is the one a writer can act on, and "Invalid input" is not.
+*/
+function refusalIssues(error) {
+	const out = [];
+	for (const issue of error.issues) {
+		if (issue.code !== "invalid_union") {
+			out.push(issue);
+			continue;
+		}
+		const refused = issue.errors.flat().filter((inner) => inner.code === "custom").map((inner) => ({
+			...inner,
+			path: [...issue.path, ...inner.path]
+		}));
+		out.push(...refused.length > 0 ? refused : [issue]);
+	}
+	return out;
+}
+/**
+* One zod issue's path, with the offending key appended when zod reports it separately.
+*
+* A strict object rejecting an unknown key paths at the object (`layers.icon`) and names the key in
+* `keys` — so the naive read gives a caller the bag rather than the field, which for the case this
+* exists to serve (a style rule setting a prop its layer's element can't take) is the one thing worth
+* knowing. Only the first key: the path addresses a single field, and an issue listing several is a
+* bag with several unknown keys, which the message already spells out in full.
+*/
+function issuePath(issue) {
+	const path = [...issue.path];
+	if (issue.code === "unrecognized_keys" && issue.keys.length > 0) return [...path, issue.keys[0]];
+	return path;
+}
+/**
+* A serialized config this build cannot read: not a config-v2 artifact at all, one whose `options`
+* slot holds a value no migration placed, or one stamped newer than this build reads
+* (`SchemaVersionTooNew`). Distinct from {@link ConfigRejection}, which refuses a write to a config
+* that loaded. The message names the fix (migrate, rebuild, or upgrade).
+*/
+var ConfigFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigFormatError";
+	}
+};
+function isConfigFormatError(value) {
+	return value instanceof ConfigFormatError;
+}
+//#endregion
+export { ConfigFormatError, ConfigRejection, isConfigFormatError, isConfigRejection, issuePath, refusalIssues, reject, rejectData, rejectInvalid };

package/dist/framework/rename-inference.d.ts

@@ -0,0 +1,26 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/rename-inference.d.ts
+/** One name that moved. `bodyMatches` separates "certainly" from "probably" — see {@link inferredRenames}. */
+interface InferredRename {
+  readonly kind: string;
+  readonly from: string;
+  readonly to: string;
+  /** Whether the arrived entity's body is byte-identical to the one that left. False means the author
+   *  changed the value in the same edit, which is ordinary — it just isn't corroboration. */
+  readonly bodyMatches: boolean;
+}
+/**
+ * The renames that explain the difference between `previous` and `current`.
+ *
+ * Per kind: pair what LEFT against what ARRIVED, by body first and by count second.
+ *
+ *  - a body that appears once on each side pairs those two, whatever their paths — which is what
+ *    catches a move between groups, and what keeps two renames in one edit from crossing over
+ *  - one leaving and one arriving with nothing else to confuse them pairs on the count alone, since a
+ *    rename may perfectly well change the value too
+ *  - anything else is ambiguous and yields nothing
+ */
+declare function inferredRenames(previous: Config, current: Config): InferredRename[];
+//#endregion
+export { InferredRename, inferredRenames };

package/dist/framework/rename-inference.js

@@ -0,0 +1,50 @@
+//#region src/framework/rename-inference.ts
+const bodyOf = (config, kind, path) => JSON.stringify(config.resolve(kind, path)?.toJSON() ?? null);
+/**
+* The renames that explain the difference between `previous` and `current`.
+*
+* Per kind: pair what LEFT against what ARRIVED, by body first and by count second.
+*
+*  - a body that appears once on each side pairs those two, whatever their paths — which is what
+*    catches a move between groups, and what keeps two renames in one edit from crossing over
+*  - one leaving and one arriving with nothing else to confuse them pairs on the count alone, since a
+*    rename may perfectly well change the value too
+*  - anything else is ambiguous and yields nothing
+*/
+function inferredRenames(previous, current) {
+	const found = [];
+	for (const kind of current.ownedKinds()) {
+		if (!previous.ownedKinds().includes(kind)) continue;
+		const before = previous.list(kind).map((item) => item.path);
+		const after = new Set(current.list(kind).map((item) => item.path));
+		const gone = before.filter((path) => !after.has(path));
+		const arrived = [...after].filter((path) => !before.includes(path));
+		if (gone.length === 0 || arrived.length === 0) continue;
+		const unpairedGone = new Set(gone);
+		const unpairedArrived = new Set(arrived);
+		for (const from of gone) {
+			const body = bodyOf(previous, kind, from);
+			if (gone.filter((path) => bodyOf(previous, kind, path) === body).length !== 1) continue;
+			const matches = arrived.filter((path) => bodyOf(current, kind, path) === body);
+			if (matches.length !== 1) continue;
+			const to = matches[0];
+			found.push({
+				kind,
+				from,
+				to,
+				bodyMatches: true
+			});
+			unpairedGone.delete(from);
+			unpairedArrived.delete(to);
+		}
+		if (unpairedGone.size === 1 && unpairedArrived.size === 1) found.push({
+			kind,
+			from: [...unpairedGone][0],
+			to: [...unpairedArrived][0],
+			bodyMatches: false
+		});
+	}
+	return found;
+}
+//#endregion
+export { inferredRenames };