@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/coalesce.js

@@ -0,0 +1,60 @@
+//#region src/framework/coalesce.ts
+/**
+* Run an expensive side effect for the LAST value of a burst, never for the ones it superseded.
+*
+* Here rather than in the app because coalescing is not a property of any one derivation: one user
+* gesture reaches a config holder several times — an edit lands optimistically, comes back as a
+* realtime echo, then again as the pull that trues up against what the server persisted. Each landing
+* describes the same edit, so a subscriber that recomputes per landing pays for two results nobody
+* ever sees, on the frames the gesture is trying to respond on. That is true of every `onChange`
+* point, so {@link runChangeHooks} owns it and a hook never writes it again.
+*
+* Leading-edge, not a trailing debounce: the first value is handed to `schedule` right away, so a
+* continuous gesture (a drag that writes per tick) keeps painting instead of going dark until it
+* stops. What coalesces is everything that arrives while a run is scheduled or in flight — those
+* collapse into ONE follow-up run carrying the newest value.
+*
+* `run` may be async; a value arriving mid-run waits for it rather than overlapping, which is what
+* keeps an older result from landing after a newer one.
+*/
+function coalesceLatest({ run, schedule }) {
+	let pending;
+	let hasPending = false;
+	let scheduled = false;
+	let running = false;
+	const fire = () => {
+		scheduled = false;
+		if (!hasPending || running) return;
+		const value = pending;
+		pending = void 0;
+		hasPending = false;
+		running = true;
+		const done = () => {
+			running = false;
+			if (hasPending) request(pending);
+		};
+		let result;
+		try {
+			result = run(value);
+		} catch {
+			done();
+			return;
+		}
+		if (result instanceof Promise) result.then(done, done);
+		else done();
+	};
+	const request = (value) => {
+		pending = value;
+		hasPending = true;
+		if (scheduled || running) return;
+		scheduled = true;
+		schedule(fire);
+	};
+	request.cancel = () => {
+		pending = void 0;
+		hasPending = false;
+	};
+	return request;
+}
+//#endregion
+export { coalesceLatest };

package/dist/framework/config-op.d.ts

@@ -0,0 +1,76 @@
+//#region src/framework/config-op.d.ts
+/**
+ * The address grammar — three spellings, one rule, written here once so `kind/verb`, `group/item` and
+ * `kind:path` are not read for one another. Other docblocks point here rather than restate a piece.
+ *
+ * | Spelling                      | What it is           | Example                                          |
+ * | ----------------------------- | -------------------- | ------------------------------------------------ |
+ * | `kind/verb`                   | an operation address | `token/create`, `component/sub-update/props`     |
+ * | `group/item`                  | an entity path       | `spacing/0`, `icons/Trophy`                      |
+ * | `kind:path[@source][#member]` | a ref to an entity   | `token:spacing/0`, `component:actions/Button@ds` |
+ *
+ * A slash after a KIND opens an operation; a slash after a GROUP walks an entity path; a colon always
+ * introduces a ref, and everything after it is the ref's qualified path. So a bare `token` is a kind
+ * and its slash is a verb, `spacing` is a group and its slash is a path, and any `:` means a ref
+ * follows — the leftmost token and the colon are what tell the three apart.
+ *
+ * `addressOf` builds the operation address; {@link splitRef} in `utils/refs.ts` reads a ref. An
+ * operation carries an entity `path` (the second spelling) in its input, never a ref-marked one.
+ */
+/**
+ * One operation, addressed the way a patch is.
+ *
+ * `kind` and `operation` name what runs; `field` names the member collection when the operation acts on
+ * one (`sub-update` of `props`); everything else is the operation's input, flat beside them. `run`,
+ * `run` and `plan` take this shape, the read and edit tools carry it, and a patch in a draft is one
+ * of these with its `path` spelled. The catalog addresses the same operation as `<kind>/<verb>`, where
+ * the verb is `operation` with `/field` appended; that string is a tool's name and the key an op is
+ * described under, and {@link addressOf} builds it.
+ */
+interface ConfigOp {
+  readonly kind: string;
+  readonly operation: string;
+  readonly field?: string;
+  readonly [input: string]: unknown;
+}
+/**
+ * An op with the id its first patch lands under.
+ *
+ * Every patch a config records carries an id, and `run` mints one when nobody names it. `id` is for the
+ * caller that has to name it: a surface that paints an edit before the round trip stages a draft row
+ * under an id of its own, and the patch the commit writes has to carry that same id, or the staged row
+ * is never acknowledged and its undo step names a patch that does not exist. A custom op writes several
+ * patches; the first takes the id, and it is the changeset's too, so what was staged, what a list groups
+ * under and what undo drops are one identifier. It rides beside the op rather than on it, since every
+ * key on an op is its input.
+ */
+interface IdentifiedOp {
+  readonly op: ConfigOp;
+  readonly id?: string;
+}
+/** What `run` takes as a list and what an edit surface hands around: an op, or one with its id named. */
+type ConfigEdit = ConfigOp | IdentifiedOp;
+/** The op an edit carries, and the id it should land under when the caller named one. */
+declare function editOp(edit: ConfigEdit): {
+  readonly op: ConfigOp;
+  readonly id?: string;
+};
+/** The verb the catalog keys an op under: `sub-update/props`, or the bare operation. */
+declare function opVerb(op: Pick<ConfigOp, 'operation' | 'field'>): string;
+/** The catalog address: `component/sub-update/props`. */
+declare function addressOf(op: Pick<ConfigOp, 'kind' | 'operation' | 'field'>): string;
+/** The op's input: everything but its address. */
+declare function inputOf(op: ConfigOp): Record<string, unknown>;
+/** An op from its catalog address halves, for a caller holding `kind` and `verb` apart. A verb splits
+ *  at its first slash: a nested collection's field keeps the rest (`sub-update/props/value`). */
+declare function opOf({
+  kind,
+  verb,
+  input
+}: {
+  kind: string;
+  verb: string;
+  input?: Record<string, unknown>;
+}): ConfigOp;
+//#endregion
+export { ConfigEdit, ConfigOp, IdentifiedOp, addressOf, editOp, inputOf, opOf, opVerb };

package/dist/framework/config-op.js

@@ -0,0 +1,43 @@
+//#region src/framework/config-op.ts
+/** The op an edit carries, and the id it should land under when the caller named one. */
+function editOp(edit) {
+	if ("op" in edit && typeof edit.op === "object" && edit.op !== null) {
+		const { op, id } = edit;
+		return {
+			op,
+			id
+		};
+	}
+	return { op: edit };
+}
+/** The verb the catalog keys an op under: `sub-update/props`, or the bare operation. */
+function opVerb(op) {
+	return op.field === void 0 ? op.operation : `${op.operation}/${op.field}`;
+}
+/** The catalog address: `component/sub-update/props`. */
+function addressOf(op) {
+	return `${op.kind}/${opVerb(op)}`;
+}
+/** The op's input: everything but its address. */
+function inputOf(op) {
+	const { kind: _kind, operation: _operation, field: _field, ...input } = op;
+	return input;
+}
+/** An op from its catalog address halves, for a caller holding `kind` and `verb` apart. A verb splits
+*  at its first slash: a nested collection's field keeps the rest (`sub-update/props/value`). */
+function opOf({ kind, verb, input = {} }) {
+	const slash = verb.indexOf("/");
+	if (slash === -1) return {
+		...input,
+		kind,
+		operation: verb
+	};
+	return {
+		...input,
+		kind,
+		operation: verb.slice(0, slash),
+		field: verb.slice(slash + 1)
+	};
+}
+//#endregion
+export { addressOf, editOp, inputOf, opOf, opVerb };

package/dist/framework/config-operation-kind.d.ts

@@ -0,0 +1,14 @@
+//#region src/framework/config-operation-kind.d.ts
+/**
+ * The kind segment of the config's own operations: `config/info`, `config/api`.
+ *
+ * An operation address is `<kind>/<verb>` (the address grammar is written whole in `config-op.ts`). The
+ * config's own operations address no entity, so they need a segment that is not a kind, and it is this
+ * fixed word rather than the config type's name: an address a model sends should not depend on whether
+ * the type is called `system-config`,
+ * `design-file` or `react-native-system`. No entity kind may take the word, which `defineEntity`
+ * refuses.
+ */
+declare const CONFIG_OPERATION_KIND = "config";
+//#endregion
+export { CONFIG_OPERATION_KIND };

package/dist/framework/config-operation-kind.js

@@ -0,0 +1,14 @@
+//#region src/framework/config-operation-kind.ts
+/**
+* The kind segment of the config's own operations: `config/info`, `config/api`.
+*
+* An operation address is `<kind>/<verb>` (the address grammar is written whole in `config-op.ts`). The
+* config's own operations address no entity, so they need a segment that is not a kind, and it is this
+* fixed word rather than the config type's name: an address a model sends should not depend on whether
+* the type is called `system-config`,
+* `design-file` or `react-native-system`. No entity kind may take the word, which `defineEntity`
+* refuses.
+*/
+const CONFIG_OPERATION_KIND = "config";
+//#endregion
+export { CONFIG_OPERATION_KIND };

package/dist/framework/config-ops.d.ts

@@ -0,0 +1,34 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/config-ops.d.ts
+/**
+ * One kind's authoring shape as one-line signatures — what a prompt carries for every kind, and what
+ * `api` answers unless one kind's full JSON Schema is asked for.
+ */
+interface KindSignature {
+  readonly kind: string;
+  readonly label: string;
+  /** The entity a consumer imports to write a ref to this kind — `Token.ref('color/brand')`. */
+  readonly refHelper: string;
+  /** What `create` takes as `data`. */
+  readonly create?: string;
+  /** Each sub-entity collection with what its `sub-create` takes as `data`. */
+  readonly collections: Record<string, string>;
+  /** The group node's own fields, when the kind carries any. */
+  readonly group?: string;
+  /** A real entry from this config, in stored form. */
+  readonly example?: unknown;
+}
+interface AuthoringSignatureOptions {
+  /** Object nesting shown for a kind's own create shape. */
+  readonly depth?: number;
+  /** Object nesting shown for a sub-entity member's shape; a prompt lists many, so it collapses sooner. */
+  readonly memberDepth?: number;
+}
+/** Every owned kind's authoring shape as signatures, with a real example where the config has one. */
+declare function authoringSignatures(config: Config, {
+  depth,
+  memberDepth
+}?: AuthoringSignatureOptions): KindSignature[];
+//#endregion
+export { AuthoringSignatureOptions, KindSignature, authoringSignatures };

package/dist/framework/config-ops.js

@@ -0,0 +1,187 @@
+import { ref } from "./utils/refs.js";
+import { METADATA_KEYS } from "./utils/field-schema.js";
+import { resolveSchema } from "./schemas.js";
+import { renderSignature } from "./signature.js";
+import { z } from "zod";
+//#region src/framework/config-ops.ts
+/**
+* The operations a CONFIG exposes about itself, rather than about one of its kinds — a summary of what
+* the system contains, and the authoring reference for changing it.
+*
+* Every config gets both, automatically, because both are pure functions of the entities it declares.
+* The old surface hand-wrote them (`uds_info`, `uds_config_api`) against a fixed idea of what a system
+* holds, so a new kind was invisible to them until someone remembered to edit the tool. Here a kind
+* appears in both the moment it's registered.
+*
+* `api` is the interesting one. The old version was largely static prose explaining a different factory
+* API per concept — `defineComponent(...).config().render().preview()`, `token()`, `styleProperty()` — which
+* is exactly the surface config-v2 doesn't have: authoring is uniform data, so the reference is the
+* entity's own field schema plus a real example from the config. What can't be derived is prose about
+* INTENT, and there's far less of it to write when every kind is authored the same way.
+*/
+/** A ref as a model writes it, spelled from the ref itself so the prose can't drift from the shape. */
+const spell = (kind, path) => JSON.stringify(ref(kind, path));
+/** JSON Schema for a zod schema, or `undefined` when it can't be represented. A reference that omits
+*  one field beats one that throws.
+*
+*  Read from the INPUT side, since this documents what an author WRITES — and because a schema that
+*  coerces (a style rule's condition stores a ref for the bare value it takes) has no output shape
+*  to represent, so the whole collection silently fell into the `catch` above. */
+function jsonSchema(schema) {
+	if (schema === void 0) return void 0;
+	try {
+		return z.toJSONSchema(schema, { io: "input" });
+	} catch {
+		return;
+	}
+}
+/**
+* The AUTHORING shape behind an op — the `data` half of its `{ path, data }` input.
+*
+* Read off the op rather than from a stored `fields` schema, because the op's `data` is the schema
+* that actually validates an authored entry: a kind that narrows its `create` (a `{ data }` override)
+* is documented as it really behaves, not as its raw fields would suggest.
+*/
+function dataSchemaOf(config, entry) {
+	if (!entry) return void 0;
+	const resolved = resolveSchema(entry.input, { config });
+	if (!(resolved instanceof z.ZodObject)) return void 0;
+	return resolved.shape.data;
+}
+/** The universal metadata every body may carry (`label`, `description`, `copiedFrom`) dropped from an
+*  object schema, or from each member of a union, so a kind's signature shows the kind's own fields. */
+function withoutMetadata(node) {
+	if (!node || typeof node !== "object") return node;
+	const record = node;
+	if (Array.isArray(record.anyOf)) return {
+		...record,
+		anyOf: record.anyOf.map(withoutMetadata)
+	};
+	if (Array.isArray(record.oneOf)) return {
+		...record,
+		oneOf: record.oneOf.map(withoutMetadata)
+	};
+	if (record.properties && typeof record.properties === "object") {
+		const properties = { ...record.properties };
+		for (const key of METADATA_KEYS) delete properties[key];
+		return {
+			...record,
+			properties
+		};
+	}
+	return node;
+}
+function authoringSignature(schema, options) {
+	const json = jsonSchema(schema);
+	return json === void 0 ? void 0 : renderSignature(withoutMetadata(json), options);
+}
+/** Every owned kind's authoring shape as signatures, with a real example where the config has one. */
+function authoringSignatures(config, { depth, memberDepth = depth } = {}) {
+	return config.ownedKinds().flatMap((kind) => {
+		const entity = config.entityOf(kind);
+		if (!entity) return [];
+		const collections = {};
+		for (const [field, sub] of Object.entries(entity.subEntities)) {
+			const singleton = sub.singleton === true;
+			const signature = authoringSignature(dataSchemaOf(config, entity.schemas[`${singleton ? "sub-update" : "sub-create"}/${field}`]), { depth: memberDepth });
+			if (signature) collections[field] = singleton ? `one section, no key (\`sub-update/${field}\`): ${signature}` : signature;
+		}
+		const first = config.list(kind)[0];
+		return [{
+			kind,
+			label: entity.label,
+			refHelper: entity.entityName,
+			create: authoringSignature(dataSchemaOf(config, entity.schemas.create), { depth }),
+			collections,
+			group: authoringSignature(entity.groupCreateSchema, { depth }),
+			example: first ? { [first.path]: first.toJSON() } : void 0
+		}];
+	});
+}
+/** What the system CONTAINS — per kind, how many entries and groups, with a sample of paths. Generic
+*  over `ownedKinds`, so a newly registered kind is summarized without touching this. */
+function summarize(config) {
+	const kinds = config.ownedKinds().map((kind) => {
+		const items = config.list(kind);
+		const groups = config.groups(kind);
+		return {
+			kind,
+			label: config.entityLabelPlural(kind),
+			count: items.length,
+			groups: groups.map((group) => group.path),
+			paths: items.slice(0, 12).map((item) => item.path),
+			truncated: items.length > 12
+		};
+	});
+	return {
+		name: config.name,
+		description: config.description,
+		kinds: kinds.filter((entry) => entry.count > 0 || entry.groups.length > 0),
+		empty: kinds.filter((entry) => entry.count === 0 && entry.groups.length === 0).map((entry) => entry.kind)
+	};
+}
+/** How to AUTHOR this config — one entry per kind, derived from the entity's own schemas. */
+function authoringReference(config) {
+	return { kinds: config.ownedKinds().flatMap((kind) => {
+		const entity = config.entityOf(kind);
+		if (!entity) return [];
+		const collections = {};
+		for (const [field, sub] of Object.entries(entity.subEntities)) {
+			if (sub.singleton === true) {
+				collections[field] = {
+					singleton: true,
+					fields: jsonSchema(dataSchemaOf(config, entity.schemas[`sub-update/${field}`]))
+				};
+				continue;
+			}
+			collections[field] = jsonSchema(dataSchemaOf(config, entity.schemas[`sub-create/${field}`]));
+		}
+		const first = config.list(kind)[0];
+		return [{
+			kind,
+			label: entity.label,
+			refHelper: entity.entityName,
+			fields: jsonSchema(dataSchemaOf(config, entity.schemas.create)),
+			collections,
+			groupFields: jsonSchema(entity.groupCreateSchema),
+			example: first ? { [first.path]: first.toJSON() } : void 0
+		}];
+	}) };
+}
+/**
+* The config-scoped op table. Mirrors `defaultSchemas`' entry shape so these flow through `Operation`,
+* `Tool` and every consumer with no special case — the only difference is `scope: 'config'`, which tells
+* a tool name to leave out an entity segment it doesn't have.
+*/
+function configSchemas(configName) {
+	return {
+		info: {
+			input: z.object({}),
+			readOnly: true,
+			label: "Info",
+			description: `What the ${configName} contains — what this kind of config is and how one is built, then every kind with its entry count, its groups, and a sample of paths. Call this first to orient; follow up with a kind's \`list\`/\`get\` for detail.`,
+			scope: "config",
+			title: () => `${configName} overview`,
+			handler: (_input, config) => summarize(config)
+		},
+		api: {
+			input: z.object({ data: z.object({ kind: z.string().optional().describe("Scope the reference to one kind; omit for every kind.") }).optional() }),
+			readOnly: true,
+			label: "Authoring API",
+			description: `How to AUTHOR this ${configName} — every kind's create shape as a one-line signature, its sub-entity collections, the helper that writes a ref to it, and a real example from this config, in one read. Pass \`data.kind\` for one kind's full JSON Schema instead. Use \`info\` to see what the system already contains.`,
+			scope: "config",
+			title: () => `${configName} authoring API`,
+			handler: (input, config) => {
+				const only = input.data?.kind;
+				if (typeof only === "string") return { kinds: authoringReference(config).kinds.filter((entry) => entry.kind === only) };
+				return {
+					ref: `A ref is written \`${spell("<kind>", "<path>")}\`, so a token is \`${spell("token", "<group>/<name>")}\`. A ref to a group (\`${spell("token", "<group>")}\`) names every member.`,
+					order: `Each layer is built from the one before it, by ref, so author in this order: tokens in groups (\`<group>/<name>\`); style properties whose \`values\` is the group ref (\`${spell("token", "<group>")}\`), named as the camelCase JSX prop they become; primitives — components whose layers are tags — exposing those style properties as props and a \`children\` slot where they hold content; then components whose layers are refs to the primitives (\`${spell("component", "<primitive>")}\`), styled through the primitives' props.`,
+					kinds: authoringSignatures(config)
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { authoringSignatures, configSchemas };

package/dist/framework/defineConfig.d.ts

@@ -0,0 +1,196 @@
+import { Ref } from "./utils/refs.js";
+import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
+import { DerivedEntityClass } from "./defineDerivedEntity.js";
+import { AuthoredEntry } from "./utils/group.js";
+import { EntityClass } from "./defineEntity.js";
+import { Config, HydrationOptions, ListOptions, StoredConfig, TreeNode } from "./Config.js";
+import { z } from "zod";
+
+//#region src/framework/defineConfig.d.ts
+type AnyEntityClass = EntityClass<any, any, string, any, any, boolean> | DerivedEntityClass<any, any>;
+/** A named map of entity classes — the shape of `entities` / `derivedEntities`. */
+type EntityMap = Record<string, AnyEntityClass>;
+/** One entity class's kind, as the literal it declared. Distributive on purpose, so a UNION of
+ *  classes yields the union of their kinds. */
+type KindOfEntity<E> = E extends {
+  readonly kind: infer K extends string;
+} ? K : never;
+/**
+ * The kinds a config TYPE owns, as a union of literals — `ConfigKind<typeof System>` is
+ * `'token' | 'component' | 'modifier' | …`.
+ *
+ * Every entity carries its kind as a literal (so a ref can narrow), and a config type keeps its
+ * `entities` map's exact types. So this union is already in the types, and anything that has to NAME
+ * kinds can be checked against what the config actually declares instead of spelling strings the
+ * compiler never sees. A memo's `kinds`, a change hook's `watches`: declared as
+ * `readonly ConfigKind<typeof System>[]`, a typo or a kind that was renamed out from under it stops
+ * compiling — where a `string[]` just silently under-declares, which is the failure that serves a
+ * stale result rather than throwing.
+ *
+ * OWNED kinds only. A SOURCE's data lives in its own config and is reached by a qualified ref (see
+ * `memo.ts`), and a derived kind is computed rather than read.
+ */
+type ConfigKind<C> = C extends {
+  readonly entities: infer M;
+} ? KindOfEntity<M[keyof M]> : never;
+/**
+ * One entity's authored body as a partial at every depth — what a caller writing a delta against an
+ * entity of that kind may say.
+ *
+ * A ref is a leaf. `{ __ref: string }` partialized to `{ __ref?: string }` would accept `{}` as a ref,
+ * which is the one shape nothing downstream can resolve. An array is a leaf too: a partial of its
+ * elements describes no gesture anyone makes, and a caller replacing one writes the whole list.
+ */
+type PartialBodyOf<E> = E extends EntityClass<infer F extends FieldsSchema, FieldsSchema> ? DeepPartial<CreateInput<F>> : never;
+/** Optional at every depth, stopping at refs, arrays and primitives. */
+type DeepPartial<T> = T extends Ref | readonly unknown[] ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/**
+ * The kinds one or more config types own, as VALUES — the runtime half of {@link ConfigKind}.
+ *
+ * For the declaration whose honest content is "all of them": a section of the stylesheet whose reach
+ * is the whole config, a scan with no smaller answer. Written out as a literal that list is a copy of
+ * the config type, and a copy silently stops being every kind the day a kind is added — the new one
+ * is simply absent, and whatever keyed on the list serves a stale answer for exactly the edits that
+ * touch it. Derived, it cannot be short.
+ *
+ * Variadic because a declaration can span platforms: a web system and a native one are different
+ * config types, and an emitter asked to describe both wants the union.
+ */
+declare function kindsOf<T extends readonly {
+  readonly entities: EntityMap;
+}[]>(...configTypes: T): readonly ConfigKind<T[number]>[];
+/** What `register` accepts for one owned entity: an items record keyed by path segment, or for a
+ *  singleton kind the one item's body itself — `register({ settings: { css: { prefix: 'acme' } } })`.
+ *  A singleton has no path level to key by, so a record of paths would be a spelling with nothing to
+ *  mean. */
+type RecordFor<E> = E extends {
+  readonly singleton: true;
+} ? E extends EntityClass<infer F, FieldsSchema, string, any, any, true> ? Partial<z.input<F>> : never : E extends EntityClass<infer F, infer G> ? Record<string, AuthoredEntry<F, G>> : never;
+/**
+ * What a config DRAWS ON — keyed by the accessor name of the kind whose items ARE the sources, valued
+ * by a thunk yielding the config type each one resolves to.
+ *
+ * ```ts
+ * sources: { linkedSystems: () => System }
+ * ```
+ *
+ * One word for one thing: the declaration here, `Config.registerSources`, `Config.load`'s resolvers,
+ * `fromJSON`'s attachments and the `sources` key `toJSON` writes all spell it the same way, and all
+ * key it by the same accessor name `register` uses.
+ *
+ * Keyed by the KIND rather than by a slug, because the slugs are that kind's item paths:
+ * `linkedSystems: { yos: …, ds: … }` declares the slugs `yos` and `ds` that a ref qualifies with. So
+ * the declaration says which collection those names come from, and cardinality follows from the data —
+ * a system editor has n items, a design file has 1, same kind and same reader.
+ *
+ * A THUNK because of self-reference: `sources: { linkedSystems: System }` sits inside the call that
+ * produces `System`, where the binding is not initialised yet.
+ *
+ * **TYPING ONLY, and deliberately so.** What it buys is that a resolver is handed that kind's own
+ * entity and that an attached source is typed as the config type named here. It is NOT a constraint on
+ * what may be attached: nothing checks a source's artifact against this, and adding that check would
+ * break the case the design is for.
+ *
+ * That case is a native system drawing on a web one. `ReactNativeSystem` names itself here, so a `System`
+ * source is a declared mismatch — and it is legal, because the type named here is not who may answer,
+ * only who is assumed to. The real check is PER ENTITY and one layer down: `Config.resolveExtension`
+ * parses a borrowed body through the BORROWING config's kind, so a native config accepts a web token it
+ * can represent (`1rem` replaced by `16` in the local delta) and refuses one it cannot. A type-level
+ * refusal at attach would reject the whole source and never reach that. Asserted both ways in
+ * `Config.test.ts` — "the consumer kind validates the merged result".
+ *
+ * The declaration is not load-bearing at record time either — an artifact names its own type, so the
+ * framework can ask an attached source what it contributes rather than trusting this.
+ */
+type SourceMap<Owned extends EntityMap> = { readonly [K in keyof Owned]?: () => unknown };
+/** The source map a config type declares — for a caller naming the resolver set it must supply. */
+type SourcesOf<C> = C extends {
+  readonly sources: infer D;
+} ? D : Record<never, never>;
+/** `register` arg — partial, keyed by owned accessor name; a key not in `entities` is a type error. */
+type OwnedRecords<Owned extends EntityMap> = { [K in keyof Owned]?: RecordFor<Owned[K]> };
+/** A read-capable window onto a kind's items in a config — the value an accessor (`system.components`)
+ *  returns, branded by the entity CLASS type so a wrong-kind one fails to type.
+ *
+ *  A read accessor and nothing more. It used to double as the handle another config borrowed a whole
+ *  KIND through; a config draws on another by declaring a `source`, and a ref carries which source it
+ *  points into. */
+interface Collection<E extends AnyEntityClass> {
+  /** Phantom brand — makes `Collection<Token>` and `Collection<Component>` distinct types. */
+  readonly __for: E;
+  list(opts?: ListOptions): ReturnType<E['list']>;
+  get(pathOrRef: string | Ref): ReturnType<E['get']>;
+  dependents(path: string): string[];
+  tree(): TreeNode[];
+}
+/**
+ * A typed instance — `Config` plus the typed `register` and a `Collection` accessor per owned / derived
+ * name.
+ *
+ * The typed members come first in the intersection. Were `Config` ever to declare a member of the same
+ * name, the two would form an overload set that TypeScript resolves by intersection position, and an
+ * editor would complete against the untyped one; `config-instance-completions.test.ts` asks the
+ * language service what it offers inside `register({ settings: { build: { … } } })` for that reason.
+ *
+ * `Config` stays IN the intersection rather than being `Omit`ed from it. `Omit` on a class type drops
+ * the nominal brand its private members carry, so a `ConfigInstance` would stop being assignable to
+ * `Config` — and nearly every reader in the codebase takes a `Config`.
+ */
+type ConfigInstance<Owned extends EntityMap, Derived extends EntityMap> = {
+  register(records: OwnedRecords<Owned>): ConfigInstance<Owned, Derived>;
+} & Config & { [K in keyof Owned]: Collection<Owned[K]> } & { [K in keyof Derived]: Collection<Derived[K]> };
+/**
+ * What `defineConfig` returns — a constructor plus a typed static `fromJSON`.
+ *
+ * Sources are always OPTIONAL. A config whose sources are unresolved is a legitimate config to
+ * read — its borrowed values simply do not resolve — which is what `Config.load` exists to make
+ * deliberate rather than accidental.
+ */
+interface ConfigClass<Owned extends EntityMap, Derived extends EntityMap, Sources extends SourceMap<Owned> = Record<never, never>> {
+  new (): ConfigInstance<Owned, Derived>;
+  fromJSON(json: StoredConfig, options?: HydrationOptions): ConfigInstance<Owned, Derived>;
+  readonly configName: string;
+  readonly entities: Owned;
+  readonly derivedEntities: Derived;
+  /** What this type DRAWS ON — see {@link SourceMap}. Empty for a config that draws on nothing. */
+  readonly sources: Sources;
+  /**
+   * Extend this config type — the same config with some kinds swapped for their extensions
+   * (`System.extend({ tools: CliTool })`). What differs between two consumers is which entity answers
+   * for a kind, so that difference is a config type rather than a flag: a flag can't change what an
+   * entity derives or validates.
+   *
+   * Keeps the base's NAME, because it IS the same system — tool names (`uds_<name>_…`) and the wire
+   * `name` are unchanged, so a model calls the same tools either way. It therefore does NOT take over
+   * the untyped `Config.fromJSON` dispatch slot: construct the extension directly, or use its own
+   * `fromJSON`. (Nothing is lost — a swapped DERIVED kind never serializes, so the wire form is
+   * identical.)
+   */
+  extend(swaps: Partial<Record<keyof Owned | keyof Derived, unknown>>): ConfigClass<Owned, Derived, Sources>;
+}
+declare function defineConfig<Owned extends EntityMap, Derived extends EntityMap = Record<never, never>, Sources extends SourceMap<Owned> = Record<never, never>>(spec: {
+  name: string;
+  /**
+   * What this config type holds and how one is authored, for a reader arriving cold — an agent
+   * orienting before its first edit. Prose about intent, which nothing derives: the kinds say what
+   * can be written, this says what to write first and what to build from it.
+   */
+  description?: string;
+  entities: Owned;
+  derivedEntities?: Derived;
+  /**
+   * The kinds whose items are this config's sources, each naming the config type it resolves to — see
+   * {@link SourceMap}.
+   *
+   * Every key must name an OWNED kind that declares `sourceIdentity`, which is what makes its items
+   * addressable as `@slug`. Checked at definition time: a key naming a kind that isn't a source kind
+   * would declare a source on a collection no ref can qualify with, and the failure would surface as
+   * "this config borrows nothing" much later.
+   */
+  sources?: Sources;
+  /** Internal: built by `.extend` — it shares its base's name, so it must not take over the base's
+   *  slot in the untyped `Config.fromJSON` dispatch registry. */
+  extendsBase?: boolean;
+}): ConfigClass<Owned, Derived, Sources>;
+//#endregion
+export { Collection, ConfigClass, ConfigInstance, ConfigKind, EntityMap, OwnedRecords, PartialBodyOf, SourceMap, SourcesOf, defineConfig, kindsOf };