@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/defineConfig.js

@@ -0,0 +1,100 @@
+import { pathOf } from "./utils/refs.js";
+import { Config } from "./Config.js";
+//#region src/framework/defineConfig.ts
+/**
+* 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.
+*/
+function kindsOf(...configTypes) {
+	const kinds = /* @__PURE__ */ new Set();
+	for (const configType of configTypes) for (const entity of Object.values(configType.entities)) kinds.add(entity.kind);
+	return [...kinds];
+}
+function defineConfig(spec) {
+	const owned = spec.entities;
+	const sources = spec.sources ?? {};
+	for (const name of Object.keys(sources)) {
+		const cls = owned[name];
+		if (!cls) throw new Error(`${spec.name}: source "${name}" is not an owned entity of this config`);
+		const kindDef = cls.kindDef;
+		const kindName = kindDef?.name ?? name;
+		if (!kindDef?.sourceIdentity) throw new Error(`${spec.name}: source "${name}" names the kind "${kindName}", which declares no \`sourceIdentity\` — a source's items are the slugs refs qualify with, so the kind has to say which of its fields identify a source`);
+		if (!kindDef.sourceResolution) throw new Error(`${spec.name}: source "${name}" names the kind "${kindName}", which declares no \`sourceResolution\` — resolving a source has to be validated against the kind's OWN \`{ resolved, unavailable }\` schemas, because what an origin and a failure are is the kind's to say and not the framework's`);
+	}
+	const derived = spec.derivedEntities ?? {};
+	/** The read/link handle an accessor returns — kind-generic reads delegate to the config, so it works
+	*  uniformly for owned and derived kinds. */
+	const makeCollection = (config, kind) => ({
+		__linkedKind: kind,
+		source: config.liveSource,
+		list: (opts) => config.list(kind, opts),
+		get: (pathOrRef) => config.resolve(kind, typeof pathOrRef === "string" ? pathOrRef : pathOf(pathOrRef.__ref)),
+		dependents: (path) => config.dependentsOf(kind, path),
+		tree: () => config.tree(kind)
+	});
+	class TypedConfig extends Config {
+		constructor() {
+			super(spec.name, spec.description);
+			for (const cls of Object.values(owned)) this.seedEntityInPlace(cls);
+			for (const cls of Object.values(derived)) this.seedEntityInPlace(cls);
+		}
+		/** Load items into a NEW config — like every other mutation, this returns rather than mutates,
+		*  which is why the chained authoring form (`new System().register(…)`) is the idiom. */
+		register(records) {
+			let next = this;
+			for (const [name, record] of Object.entries(records)) {
+				const cls = owned[name];
+				if (!cls) throw new Error(`"${name}" is not an owned entity of config "${spec.name}"`);
+				next = next.registerEntity(cls, record);
+			}
+			return next.coerceOwned();
+		}
+		static fromJSON(json, options) {
+			return new TypedConfig().hydrateFrom(json, options);
+		}
+		static configName = spec.name;
+		static entities = owned;
+		static derivedEntities = derived;
+		static sources = sources;
+		/** Swap kinds by their accessor name, across owned / derived. */
+		static extend(swaps) {
+			const pick = (base) => {
+				const next = { ...base };
+				for (const [name, cls] of Object.entries(swaps)) if (name in base) next[name] = cls;
+				return next;
+			};
+			const unknownSlots = Object.keys(swaps).filter((name) => !(name in owned) && !(name in derived));
+			if (unknownSlots.length > 0) throw new Error(`${spec.name}.extend: no such entity ${unknownSlots.map((n) => `"${n}"`).join(", ")} — an extension may only replace a kind this config already declares`);
+			return defineConfig({
+				name: spec.name,
+				description: spec.description,
+				entities: pick(owned),
+				derivedEntities: pick(derived),
+				sources,
+				extendsBase: true
+			});
+		}
+	}
+	for (const [name, cls] of [...Object.entries(owned), ...Object.entries(derived)]) {
+		if (name in TypedConfig.prototype || name === "state") throw new Error(`${spec.name}: entity accessor "${name}" collides with a Config member — rename the accessor (the KIND itself is unaffected)`);
+		Object.defineProperty(TypedConfig.prototype, name, {
+			get() {
+				return makeCollection(this, cls.kind);
+			},
+			enumerable: false,
+			configurable: true
+		});
+	}
+	if (!spec.extendsBase) Config.registerConfigType(spec.name, TypedConfig);
+	return TypedConfig;
+}
+//#endregion
+export { defineConfig, kindsOf };

package/dist/framework/defineDerivedEntity.d.ts

@@ -0,0 +1,74 @@
+import { Entity } from "./Entity.js";
+import { Ref } from "./utils/refs.js";
+import { TraverseOptions } from "./ref-graph.js";
+import { FieldsSchema } from "./utils/field-schema.js";
+import { Config } from "./Config.js";
+import { ComputedInput, EntityKind } from "./registry.js";
+import { z } from "zod";
+
+//#region src/framework/defineDerivedEntity.d.ts
+/** The zod schema an entity class IS — a ref to this entity. */
+type RefSchema = z.ZodObject<{
+  __ref: z.ZodString;
+}>;
+/** Compute a kind's members from a source config, keyed by path. */
+type DeriveMembers<F extends FieldsSchema> = (source: Config) => Record<string, z.infer<F>>;
+/** Virtual, recomputed-on-read fields — a pure fn of {@link ComputedInput}, with `member` narrowed to
+ *  this kind's own fields. Non-serializable is fine. */
+type ComputedMap<F extends FieldsSchema> = Record<string, (input: Omit<ComputedInput, 'member'> & {
+  member: z.infer<F>;
+}) => unknown>;
+/** The read shape of a derived entity — its declared fields plus the return types of its computeds. */
+type Computed<C extends ComputedMap<FieldsSchema>> = { [K in keyof C]: ReturnType<C[K]> };
+/** A derived entity class — a ref schema (so `z.array(Tool)` type-checks a Tool ref array) plus the
+ *  read/override toolkit. NO create/delete/rename: membership is derived, not authored.
+ *
+ *  Zod's own `extend` is omitted before ours is declared, so the name resolves to one method rather
+ *  than an overload pair — see {@link DerivedEntityClass.extend}. */
+type DerivedEntityClass<F extends FieldsSchema, C extends ComputedMap<F> = Record<never, never>> = Omit<RefSchema, 'extend'> & {
+  readonly kind: string;
+  readonly isDerived: true;
+  /** The kind's immutable metadata, built once by `buildKind` (carries `derived` — the compute
+   *  spec). `Config.register` copies this into the config's `#entities`. */
+  readonly kindDef: EntityKind; /** `Tool.ref('component/create')` → `{ __ref: 'tool:component/create' }`. */
+  ref(path: string): Ref; /** Resolve one member — accepts a path OR a `Ref` (ref-aware; rejects a wrong-kind ref). */
+  get(config: Config, pathOrRef: string | Ref): (Entity & z.infer<F> & Computed<C>) | undefined;
+  list(config: Config): (Entity & z.infer<F> & Computed<C>)[];
+  dependents(config: Config, path: string, opts?: TraverseOptions): string[]; /** Overridable kinds only — merges a sparse override of `overridable` fields. */
+  update<Cfg extends Config>(config: Cfg, path: string, data: Partial<z.infer<F>>): Cfg;
+  /**
+   * Extend this kind — the same kind with part of it replaced. The consumer difference becomes a
+   * different entity in a different config type (`ConfigClass.extend`) rather than a branch inside a
+   * shared derivation: a CLI's `Tool` describes the authoring API, Studio's describes the patch, and
+   * neither has to ask who's calling.
+   *
+   * `computed` MERGES over the base (replace one field, keep the rest); everything else replaces.
+   * `kind` is inherited and can't be changed — an extension stands in for its base in a config slot,
+   * so it has to answer to the same kind.
+   *
+   * SHADOWS `ZodObject.extend`, which this class inherits by being a zod schema. Deliberate, and it
+   * costs nothing: the schema an entity class IS is its REF schema (`{ __ref }`), and adding fields to
+   * a ref is meaningless for an entity — there's no legitimate call to displace. Shadowing writes an
+   * own property, so no other zod object is affected. A SUB-entity class must never do this: its
+   * schema is the member shape, and `deriveCreateSchema` really does call zod's `extend` on it.
+   */
+  extend<C2 extends ComputedMap<F> = C>(overrides: Partial<Omit<DerivedEntitySpec<F, C2>, 'kind'>>): DerivedEntityClass<F, C2>;
+};
+/** What `defineDerivedEntity` takes — named so {@link DerivedEntityClass.extend} can restate part of
+ *  it without repeating the shape. Its keys are the extendable surface ({@link EXTENDABLE_KEYS}). */
+interface DerivedEntitySpec<F extends FieldsSchema, C extends ComputedMap<F> = Record<never, never>> {
+  kind: string;
+  fields: F;
+  deriveMembers: DeriveMembers<F>;
+  /** Fields a user may override. Present → an `update`-only op + a sparse override store. */
+  overridable?: readonly (keyof z.infer<F> & string)[];
+  /** Virtual fields, recomputed on read, never serialized. Intersecting with `ComputedMap<F>` gives
+   *  each fn's `member` param its contextual type (`z.infer<F>`) while still inferring `C` for the
+   *  precise return types on `get`/`list`. */
+  computed?: C & ComputedMap<F>;
+  label?: string;
+  labelPlural?: string;
+}
+declare function defineDerivedEntity<F extends FieldsSchema, C extends ComputedMap<F> = Record<never, never>>(spec: DerivedEntitySpec<F, C>): DerivedEntityClass<F, C>;
+//#endregion
+export { ComputedMap, DeriveMembers, DerivedEntityClass, defineDerivedEntity };

package/dist/framework/defineDerivedEntity.js

@@ -0,0 +1,83 @@
+import { isRef, kindOf, pathOf, ref } from "./utils/refs.js";
+import { buildKind } from "./registry.js";
+import { z } from "zod";
+//#region src/framework/defineDerivedEntity.ts
+/**
+* `defineDerivedEntity({ kind, fields, deriveMembers, overridable?, computed? })` — a THIRD member
+* source beside stored (`defineEntity`) and depended-on (a qualified ref). A derived kind's members are
+* COMPUTED from a source config (`deriveMembers(source)`) — ref-able and resolvable like any entity,
+* but read-only: no create/delete/rename. Two optional extensions:
+*
+*  - `overridable` — the fields a user may overwrite; the kind gains an `update`-only op that writes a
+*    SPARSE override (only the diff persists; the base always re-derives). Everything else stays derived.
+*  - `computed` — VIRTUAL fields recomputed on read, never stored, never overridable — the home for a
+*    non-serializable projection (a zod schema, a function). Each fn declares its own provenance.
+*
+* A derived kind self-derives on registration, sourcing from the config it's registered into;
+* `Config.register` routes it by whether the KIND is derived. See `docs/config-v2.md`.
+*/
+/** What `extend` accepts. Checked at runtime because `extend` is shadowed: an unrecognized key is a
+*  typo, or a zod raw shape reaching this method expecting zod's `extend`. Either should say so
+*  rather than quietly build a kind missing half its derivation. `kind` is absent on purpose — an
+*  extension answers to its base's kind. */
+const EXTENDABLE_KEYS = new Set([
+	"fields",
+	"deriveMembers",
+	"overridable",
+	"computed",
+	"label",
+	"labelPlural"
+]);
+function defineDerivedEntity(spec) {
+	const kindDef = buildKind({
+		name: spec.kind,
+		fields: spec.fields,
+		groupFields: z.object({}),
+		label: spec.label,
+		labelPlural: spec.labelPlural,
+		derived: {
+			deriveMembers: spec.deriveMembers,
+			overridable: spec.overridable,
+			computed: spec.computed
+		}
+	});
+	const schema = z.object({ __ref: z.string().startsWith(ref(spec.kind, "").__ref) });
+	const toPath = (pathOrRef) => {
+		if (!isRef(pathOrRef)) return pathOrRef;
+		if (kindOf(pathOrRef) !== spec.kind) return void 0;
+		return pathOf(pathOrRef);
+	};
+	return Object.assign(schema, {
+		kind: spec.kind,
+		kindDef,
+		isDerived: true,
+		ref: (path) => ref(spec.kind, path),
+		get: (config, pathOrRef) => {
+			const path = toPath(pathOrRef);
+			return path === void 0 ? void 0 : config.resolve(spec.kind, path);
+		},
+		list: (config) => config.list(spec.kind),
+		dependents: (config, path, opts) => config.dependentsOf(spec.kind, path, opts),
+		update: (config, path, data) => config.apply({
+			kind: spec.kind,
+			operation: "update",
+			path,
+			data
+		}),
+		extend: (overrides) => {
+			const unknown = Object.keys(overrides).filter((key) => !EXTENDABLE_KEYS.has(key));
+			if (unknown.length > 0) throw new Error(`${spec.kind}.extend: unknown option ${unknown.map((key) => `"${key}"`).join(", ")} — expected one of ${[...EXTENDABLE_KEYS].join(", ")}. This is an entity extension, not \`ZodObject.extend\`.`);
+			return defineDerivedEntity({
+				...spec,
+				...overrides,
+				kind: spec.kind,
+				computed: {
+					...spec.computed,
+					...overrides.computed
+				}
+			});
+		}
+	});
+}
+//#endregion
+export { defineDerivedEntity };

package/dist/framework/defineEntity.d.ts

@@ -0,0 +1,318 @@
+import { Entity } from "./Entity.js";
+import { ExtendableRef, Ref } from "./utils/refs.js";
+import { TraverseOptions } from "./ref-graph.js";
+import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
+import { FieldsCtx, UserSchemas } from "./schemas.js";
+import { SubEntityClass } from "./defineSubEntity.js";
+import { PathOf } from "./registered.js";
+import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
+import { GroupBody } from "./utils/group.js";
+import { Config, ListOptions, TreeNode } from "./Config.js";
+import { ComputedFields, EntityKind, Linkable } from "./registry.js";
+import { z } from "zod";
+
+//#region src/framework/defineEntity.d.ts
+/** Keys of any member of a (possibly union) type — distributes, so a union yields every
+ *  member's keys, not just the ones shared by all (which is what `keyof` gives on a union). */
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+/** The zod schema shape an entity class is — a ref to this entity: `{ __ref: '<kind>:<path>' }`. */
+type RefSchema = z.ZodObject<{
+  __ref: z.ZodString;
+}>;
+/** What a `fields`/`groupFields` override may be: a plain record of schemas where `null` removes
+ *  the named key, or a zod object as the merge-only sugar (a shape has no way to spell a removal). */
+type ShapeOverride = z.ZodObject<z.ZodRawShape> | Record<string, z.ZodTypeAny | null>;
+/** The keys-to-schemas (or null) view of an override, whichever form it was written in. */
+type OverrideEntries<O extends ShapeOverride> = O extends z.ZodObject<infer S extends z.ZodRawShape> ? S : O;
+/** The merged fields type an extension ends up with — the override's keys replace (or, via `null`,
+ *  remove) the base's; everything unnamed is inherited. Type-level twin of `extendShape`. */
+type ExtendedFields<F extends FieldsSchema, O extends ShapeOverride> = F extends z.ZodObject<infer Shape extends z.ZodRawShape> ? z.ZodObject<Omit<Shape, keyof OverrideEntries<O>> & { [K in keyof OverrideEntries<O> as OverrideEntries<O>[K] extends null ? never : K & string]: Extract<OverrideEntries<O>[K], z.ZodTypeAny> }> : never;
+/** An entity class — the whole toolkit for a kind. It is a zod schema (a ref to this entity), so
+ *  it can be used directly as another entity's field (`component: Component` = "a ref to a
+ *  Component"), and it carries the authoring/resolution methods. `Component.ref('Card')` makes a
+ *  specific member-ref value; `Component` itself is the entity-level ref schema.
+ *
+ *  Zod's own `extend` is removed from this type so ours is the only `extend` TypeScript sees —
+ *  see {@link EntityClass.extend} for why we shadow it. */
+/**
+ * One resolved item of a kind — `ItemOf<typeof Mode>`.
+ *
+ * What `Token.get(config, path)` hands back: the entity (its path, leaf, `toJSON`) with its own fields
+ * on it. Consumers need to name that type constantly — a function taking a mode, a list of canvas
+ * roles — and the entity is exported as a value, so `Mode` in a type position is an error and
+ * `NonNullable<ReturnType<typeof Token.get>>` is what people were left writing.
+ *
+ * Read off `get` rather than off the fields schema, so it stays whatever `get` actually returns.
+ */
+type ItemOf<E> = E extends {
+  get(config: Config, pathOrRef: string | Ref): infer R;
+} ? NonNullable<R> : never;
+/** An entity as a read returns it — its declared fields, plus the return type of every computed. */
+type Read<F extends FieldsSchema, C extends ComputedFields> = Entity & z.infer<F> & { readonly [K in keyof C]: ReturnType<C[K]> };
+type EntityClass<F extends FieldsSchema, G extends FieldsSchema,
+/** The kind as a literal, so `ref` can narrow to the paths a consumer's config declares. Defaults
+ *  to `string`, which is what every 2-argument use of this type keeps getting. */
+K extends string = string,
+/** The op schemas as written, so a consumer can infer an operation's input type off the entity
+ *  instead of restating it. See {@link OpInput}. */
+S extends UserSchemas = UserSchemas,
+/** The kind's `computed` map as written, so `Token.get(...).link` is typed off the function that
+ *  produces it rather than restated. Defaults to none. */
+C extends ComputedFields = Record<never, never>,
+/** Whether the kind has exactly one item — see `singleton` on `defineEntity`. Read off the spec so
+ *  `get` can drop its path argument for exactly the kinds whose one item needs none. */
+Single extends boolean = false> = Omit<RefSchema, 'extend'> & {
+  readonly kind: K;
+  /** Whether the kind has exactly one item — see `singleton` on `defineEntity`. A property rather than
+   *  only a type parameter so a conditional type can tell the two apart: `get`'s signature differs by
+   *  it, but methods compare bivariantly and a required parameter matches an optional one. */
+  readonly singleton: Single;
+  /**
+   * The entity's own op schemas, at the type level.
+   *
+   * Present so `OpInput<typeof Component, 'element-insert'>` resolves. Every consumer that wrote an
+   * operation used to hand-declare its input shape — 20 files did, because the zod schema was defined
+   * here and thrown away by this type — and a hand-declared shape is checked against nothing.
+   */
+  readonly schemas: S;
+  /** The kind's immutable metadata (field names, primary field, sub-entities, merged op `schemas`),
+   *  built once by `buildKind`. `Config.register` copies this into the config's `#entities`. */
+  readonly kindDef: EntityKind;
+  /** The kind-bound member-ref maker — `Component.ref('Card')` → `{ __ref: 'component:Card' }`.
+   *  Called on the entity itself; a kind never re-exports it under a second, lowercase name. A
+   *  singleton's one item sits at the kind's own name, so its path may be left out: `Settings.ref()`. */
+  ref(...path: Single extends true ? [path?: PathOf<K>] : [path: PathOf<K>]): ExtendableRef<Partial<CreateInput<F>>>;
+  /** Typed constructor for one item — a full body, or a bare value/ref that's shorthand
+   *  for the kind's primary field. Returned as-is; `register` normalizes the shorthand. */
+  item(def: CreateInput<F> | string | number | Ref): CreateInput<F> | string | number | Ref;
+  /** Typed constructor for a group node — branded so `register` routes it to the group
+   *  store; input is the group fields' create body. */
+  group(meta: GroupBody<F, G>): GroupBody<F, G>;
+  /** Resolve one item, typed off the fields — `Component.get(config, 'Button')`. Ref-aware: also
+   *  accepts a `Ref` (`Node.component` → `Component.get(config, node.component)`), rejecting a
+   *  wrong-kind ref. A singleton's one item sits at the kind's own name, so its path may be left out:
+   *  `Settings.get(config)`, which answers `undefined` on a config type that declares no such kind. */
+  get(config: Config, ...pathOrRef: Single extends true ? [pathOrRef?: string | Ref] : [pathOrRef: string | Ref]): Read<F, C> | undefined;
+  /** Every item of this kind, typed off the fields — `Component.list(config)`. Total by default;
+   *  `{ retired: false }` is the offer surface's read (see `Config.list`). */
+  list(config: Config, opts?: ListOptions): Read<F, C>[]; /** This kind's items as a folder/file tree — `Component.tree(config)` (the sidebar). */
+  tree(config: Config): TreeNode[];
+  /** This kind's group nodes and their metadata — `Package.groups(config)`, the packages a system
+   *  depends on. The enumeration `list`/`tree` can't give: both derive from item paths, so a group
+   *  declared with no members yet (a package the host supplies, which no render names) is invisible
+   *  to them. */
+  groups(config: Config, opts?: ListOptions): {
+    path: string;
+    meta: GroupBody<F, G>;
+  }[];
+  /** What references a given item (`kind:path` strings) — the reverse dependency graph.
+   *  `{ transitive: true }` returns the whole closure rather than the direct edges, which is what
+   *  a chain like `font → token → composite → component` needs: every hop is a different kind, so
+   *  the one-hop answer names an intermediate rather than anything a person recognises as a use. */
+  dependents(config: Config, path: string, opts?: TraverseOptions): string[];
+  /** Create an item of this kind — `Component.create(config, 'Button', {…})`. Typed body; returns
+   *  the config for chaining. (The typed twin of `config.apply({kind, operation:'create', …})`.) */
+  create<C extends Config>(config: C, path: string, data: CreateInput<F>): C; /** Update an item — a partial patch merged over the current value. */
+  update<C extends Config>(config: C, path: string, data: Partial<z.infer<F>>): C; /** Delete an item (refused while other entities still reference it). */
+  delete<C extends Config>(config: C, path: string): C; /** Rename an item's path — references cascade. */
+  rename<C extends Config>(config: C, path: string, to: string): C;
+  /**
+   * Make a variant of this kind — same kind, different rules, stating only the differences.
+   * `NativeToken = Token.extend({ fields: z.object({ value: nativeTokenValue }) })` is a token
+   * whose values must be native-legal; everything it doesn't mention works like the base. A
+   * Config type adopts the variant through `ConfigClass.extend`, and it takes the base's slot.
+   *
+   * One rule for how an override combines with the base: **merge per key, `null` removes,
+   * anything unmentioned is inherited.**
+   *
+   *  - `fields` / `groupFields`: a named key replaces (or adds) that field; `null` removes it —
+   *    `groupFields: { cssPrefix: null }` is how the native token drops a web-only setting. A zod
+   *    object also works as the merge-only form (its shape can't spell a removal). Removal must be
+   *    explicit because only declared fields survive save and load — an implicit wipe would
+   *    silently drop stored data.
+   *  - `subEntities`: same — name one to swap it, `null` to drop it, the rest are inherited. A
+   *    collection must keep a field of the same name; extend refuses a half-swap.
+   *  - `schemas`: same, per verb — `{ delete: null }` removes one (`UserSchemas`' own form).
+   *  - `kind` cannot change. The variant stands in for the base everywhere, so refs, tool names
+   *    and stored data keep working, and nothing downstream ever asks which variant it has.
+   *
+   * Shadows zod's `ZodObject.extend`, on purpose — this class doubles as a zod schema, but the
+   * schema it is is just the ref wrapper, and adding fields to a ref means nothing. A sub-entity
+   * class must never do the same: its schema is the member shape, and `deriveCreateSchema` really
+   * does call zod's `extend` on it.
+   */
+  extend<F2 extends ShapeOverride = Record<never, never>, G2 extends ShapeOverride = Record<never, never>, S2 extends UserSchemas = S>(overrides: {
+    fields?: F2;
+    groupFields?: G2;
+    subEntities?: Partial<Record<string, SubEntityClass | null>>;
+    schemas?: S2 & UserSchemas;
+    label?: string;
+    labelPlural?: string;
+    /** What a config file calls this variant. A variant keeps its base's `kind`, so nothing derived
+     *  from the kind can name it — and a source writer that guesses emits the base's class into a
+     *  Config that never imported it. See {@link EntityKind.entityName}. */
+    entityName?: string;
+  }): EntityClass<ExtendedFields<F, F2>, ExtendedFields<G, G2>, K, S2, C, Single>;
+};
+declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z.ZodObject<Record<never, never>>, K extends string = string, const S extends UserSchemas = Record<never, never>, const C extends ComputedFields = Record<never, never>, Single extends boolean = false>(spec: {
+  kind: K;
+  /** The kind's fields, or a factory over the write's context (`config`, `body`) when a field's
+   *  schema depends on the config or on its sibling fields. See {@link FieldsDeclaration}. */
+  fields: F | ((ctx: FieldsCtx) => F);
+  groupFields?: G; /** Human label for one item, for UI/docs surfaces (defaults to a title-cased `kind`). */
+  label?: string;
+  /** Human label for the collection (defaults to `label + 's'`) — set when the naive plural is
+   *  wrong (`style-prop` → `Style Properties`). */
+  labelPlural?: string;
+  /** The class name a config file spells this entity through, when it isn't the one the kind derives.
+   *  See {@link EntityKind.entityName} — a variant is the case that needs it. */
+  entityName?: string;
+  /** The keyed sub-entity collections — field name → its `defineSubEntity` definition (e.g. a
+   *  Component's `{ layers: Layer, props: Prop }`). These are the fields sub-entity CRUD
+   *  (`Config.apply` sub-ops) may target, and each definition declares its member's schema and
+   *  labels rather than them being inferred from this entity's field type. Keys distribute over a
+   *  union so a collection declared on just one variant (a composite's `layers`) is allowed —
+   *  plain `keyof` on a union would only see the shared discriminant. */
+  subEntities?: Partial<Record<KeysOfUnion<z.infer<F>> & string, SubEntityClass>>;
+  /** Op-schema overrides/additions/removals, keyed by verb — merged over the derived defaults
+   *  (CRUD + reads + sub-*). `{ create: { data } }` overrides a data schema; `{ resolve: { input,
+   *  readOnly, handler } }` adds a custom op; `{ delete: null }` removes one. See {@link UserSchemas}. */
+  schemas?: S & UserSchemas;
+  /**
+   * Virtual fields, recomputed on every read and never serialized — `(the item's own fields, the config
+   * it lives in) => value`.
+   *
+   * For a fact that is a derivation of what the entity already holds, rather than something an author
+   * states. Declaring it here is what stops every consumer deriving its own: a token's provenance is
+   * read off the source qualifier in its `value`, and a UI, the CLI and the AI read tools would
+   * otherwise each carry a copy of that rule and drift.
+   *
+   * They read like any other field and are absent from `toJSON`, so nothing computed can be written
+   * into an artifact and then contradict the value it was derived from.
+   */
+  computed?: C;
+  /**
+   * For a kind whose items name an external source: the fields that decide which source.
+   *
+   * Declaring it is what lets the framework treat values recorded through this kind as belonging to
+   * the exact source they came from, without the framework naming this kind. See
+   * {@link EntityKind.sourceIdentity}.
+   */
+  sourceIdentity?: readonly string[];
+  /** The part of `sourceIdentity` that names the system and not its version. See
+   *  {@link EntityKind.sourceOrigin}. */
+  sourceOrigin?: readonly string[];
+  /**
+   * Whether an author ever hand-writes a ref to this kind — default true. See
+   * {@link EntityKind.authoredRefs}; a kind the build populates from the source tree declares
+   * `false` so its paths stay out of the emitted authoring types.
+   */
+  authoredRefs?: boolean;
+  /**
+   * Whether this kind may be borrowed from a linked source — default true. See
+   * {@link EntityKind.linkable}; a kind that is about this config rather than about design (a `file`,
+   * a source pin) declares `false` and the borrow op leaves it alone. A kind whose answer depends on
+   * the two configs declares a predicate over them.
+   */
+  linkable?: Linkable;
+  /**
+   * Group fields that describe how THIS config emits, rather than what the group is — so a borrowed
+   * group does not inherit them. See {@link EntityKind.localGroupFields}.
+   */
+  localGroupFields?: readonly string[];
+  /**
+   * Whether a `/` in this kind's path is a folder boundary — default true.
+   *
+   * A kind declares `false` when the slash is part of the name rather than a hierarchy, and then no
+   * group is synthesized from a path prefix. `Package` is the case: its path is an npm specifier, so
+   * `@ariakit/react` is one identity and `@ariakit` is a scope that nothing installs and no import
+   * names. Synthesized anyway, those prefixes reached every surface that reads groups — including the
+   * emitted authoring types, which offered `Package.ref('@ariakit')` as though it were a module.
+   *
+   * The same statement `.claude/rules/config-authoring.md` makes about a name that contains a slash:
+   * `w/1/2` is the fraction one-half, not a folder named `1`. Declared here so the framework asks
+   * the kind rather than testing for one by name.
+   */
+  emergentGroups?: boolean;
+  /**
+   * Whether this kind has exactly one item, at a path equal to the kind's name — a config's settings.
+   * See {@link EntityKind.singleton} for what the framework does with it. Every field has to be
+   * optional or defaulted, since the item is seeded from `{}` when the kind is registered. Its `get`
+   * and `ref` take no path: `Settings.get(config)`.
+   */
+  singleton?: Single;
+  /**
+   * 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.
+   */
+  bareMember?: string; /** Whether a leaf names an item on its own — see {@link EntityKind.uniqueLeaves}. */
+  uniqueLeaves?: boolean; /** Cross-item rules the kind holds — see {@link EntityKind.invariants}. */
+  invariants?: (config: Config) => string[];
+  /**
+   * For a source kind that can be resolved: the two schemas its resolutions are validated against —
+   * `{ resolved, unavailable }`. Declare it alongside `sourceIdentity` for a kind a config lists in its
+   * `sources`; that pairing is checked by `defineConfig`. See {@link EntityKind.sourceResolution}.
+   */
+  sourceResolution?: SourceResolutionSchemas;
+  /**
+   * For a source kind that records a bulk take: whether one of its pins still covers a borrowed
+   * Entity, which is what the delete gate refuses on. Declare it alongside `sourceIdentity` for a kind
+   * whose items declare what is drawn in bulk. See {@link EntityKind.bulkAdopts}.
+   */
+  bulkAdopts?: (args: BulkQuery) => boolean;
+  /**
+   * Whether the pin declines this path — the counterpart to {@link EntityKind.bulkAdopts}, and the
+   * tombstone `link`'s own note asks for. A declined path derives no row, so the name is free for
+   * this config to author, and the source's entity stays reachable qualified.
+   */
+  /**
+   * What the declared source lays over the entity at this path, when it declares anything — the
+   * bodies a minted row carries in place of an empty `extend`, so a bulk adjustment and a hand-written
+   * `.extend(...)` produce the same stored row, and whether the source still offers it.
+   */
+  bulkOverlay?: (args: BulkQuery) => SourceOverlay | undefined; /** See {@link EntityKind.bulkDirectives}. */
+  bulkDirectives?: (body: Record<string, unknown>) => {
+    accessor: string;
+    path: string;
+  }[];
+  /**
+   * The field-path delta that lands an overlay on this path — see {@link EntityKind.bulkOverlayWrite}.
+   * Declare it alongside `bulkOverlay` for a kind whose minted rows should stay editable; without it,
+   * an edit to one has nowhere to land.
+   */
+  bulkOverlayWrite?: (args: BulkOverlayWrite) => Record<string, unknown>;
+  /**
+   * Edges this kind's data implies by name rather than by ref, and how to rewrite one — the pair that
+   * makes a record keyed by another kind's item names behave like a reference: reported by
+   * `dependentsOf`, refused by a delete, and rewritten by a rename.
+   *
+   * Declared here because only the kind knows what its own keys mean. See
+   * {@link EntityKind.nameEdges} for why `nameEdges` must be pure in its argument.
+   */
+  nameEdges?: (data: unknown) => string[];
+  /** See {@link EntityKind.styleBags} — where this kind keeps its style bags, for a reader that has to
+   *  find every one of them without knowing the kind. */
+  styleBags?: (data: unknown) => {
+    bag: Record<string, unknown>;
+  }[];
+  rewriteName?: (data: unknown, from: string, to: string) => unknown;
+}): EntityClass<F, G, K, S, C, Single>;
+/**
+ * The input type of one of an entity's operations — `OpInput<typeof Component, 'element-insert'>`.
+ *
+ * Inferred from the zod schema the entity declares, so a caller that writes an operation is checked
+ * against the thing that will validate it. Restating the shape by hand is how a gesture ends up carrying
+ * a field the op has no input for: the write is silently dropped, and nothing catches it until a merge.
+ */
+type OpInput<E extends {
+  readonly schemas: UserSchemas;
+}, V extends keyof E['schemas']> = E['schemas'][V] extends {
+  input: infer I extends z.ZodTypeAny;
+} ? z.input<I> : never;
+//#endregion
+export { EntityClass, ItemOf, OpInput, defineEntity };