@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/entities/system/Modifier.d.ts

@@ -0,0 +1,92 @@
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { Config } from "../../framework/Config.js";
+import { StyleValue } from "./style-bag.js";
+import { z } from "zod";
+
+//#region src/entities/system/Modifier.d.ts
+/** The category a typed group gives its members. Untyped groups are folders; their members are
+ *  plain modifiers that compose as fragments and that no surface treats specially. */
+declare const MODIFIER_CATEGORIES: readonly ["mode", "state"];
+type ModifierCategory = (typeof MODIFIER_CATEGORIES)[number];
+/** How a web modifier activates. A `media-query` is an at-rule the emitter wraps the block in;
+ *  `selector` composes onto the element, or stands as an ancestor for a mode. */
+declare const WEB_ACTIVATIONS: readonly ["selector", "media-query", "composite"];
+type WebActivation = (typeof WEB_ACTIVATIONS)[number];
+/**
+ * A modifier group's own fields.
+ *
+ * `type` says what category of condition the group's members are. A `mode` is an axis of the
+ * document or a subtree: one option active at a time, switched by a viewer, activating on an
+ * ancestor or the viewport. A `state` is a condition of the element itself, entered by interaction
+ * or by a prop; it gets a grid column and a `data-create-force-<leaf>` twin. A group with no `type`
+ * is a folder and its members are plain.
+ *
+ * `default` names the option a viewer starts in. The native theme reads it; on web the resting state
+ * is the base values and no option is default.
+ */
+declare const modifierGroupFields: z.ZodObject<{
+  type: z.ZodOptional<z.ZodEnum<{
+    mode: "mode";
+    state: "state";
+  }>>;
+  default: z.ZodOptional<z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ModifierGroupMeta = z.infer<typeof modifierGroupFields> & {
+  label?: string;
+  description?: string;
+};
+declare const Modifier: EntityClass<z.ZodObject<{
+  type: z.ZodEnum<{
+    composite: "composite";
+    selector: "selector";
+    "media-query": "media-query";
+  }>;
+  value: z.ZodUnion<readonly [z.ZodString, z.ZodLazy<EntityClass<z.ZodObject<{
+    styles: SubEntityClass<z.ZodType<StyleValue, unknown, z.core.$ZodTypeInternals<StyleValue, unknown>>>;
+  }, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "composite", Record<never, never>, Record<never, never>, false>>]>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodOptional<z.ZodEnum<{
+    mode: "mode";
+    state: "state";
+  }>>;
+  default: z.ZodOptional<z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, "modifier", Record<never, never>, Record<never, never>, false>;
+/** A path's last segment. */
+declare function modifierLeaf(path: string): string;
+/**
+ * The typed group a modifier belongs to — its category and the group's path — or `undefined` for a
+ * plain one. The nearest typed ancestor answers; folders above it are organisation only.
+ */
+declare function modifierAxis(config: Config, pathOrLeaf: string): {
+  group: string;
+  type: ModifierCategory;
+  meta: ModifierGroupMeta;
+} | undefined;
+/** The category of a modifier: `mode`, `state`, or `undefined` for a plain one. */
+declare function modifierCategory(config: Config, pathOrLeaf: string): ModifierCategory | undefined;
+/** The typed groups of one category, each with the options it offers, in group order. */
+declare function modifierAxes(config: Config, type: ModifierCategory): {
+  path: string;
+  meta: ModifierGroupMeta;
+  options: ReturnType<typeof Modifier.list>;
+}[];
+/** The mode axes a config declares — what a switcher offers and a token override conditions on. */
+declare function modeAxes(config: Config): {
+  path: string;
+  meta: ModifierGroupMeta;
+  options: ReturnType<typeof Modifier.list>;
+}[];
+/**
+ * The rule one item's schema cannot see, because it spans the kind: a typed group is the axis, so
+ * it sits under no other typed group and holds its options as direct children. That is what lets
+ * every reader split an option's path at its last slash to find the axis. Leaf uniqueness is the
+ * framework's, from `uniqueLeaves`.
+ */
+declare function modifierInvariants(config: Config): string[];
+//#endregion
+export { MODIFIER_CATEGORIES, Modifier, ModifierCategory, ModifierGroupMeta, WEB_ACTIVATIONS, WebActivation, modeAxes, modifierAxes, modifierAxis, modifierCategory, modifierGroupFields, modifierInvariants, modifierLeaf };

package/dist/entities/system/Modifier.js

@@ -0,0 +1,120 @@
+import { isRef, kindOf } from "../../framework/utils/refs.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { Composite } from "./Composite.js";
+import { z } from "zod";
+//#region src/entities/system/Modifier.ts
+/** The category a typed group gives its members. Untyped groups are folders; their members are
+*  plain modifiers that compose as fragments and that no surface treats specially. */
+const MODIFIER_CATEGORIES = ["mode", "state"];
+/** How a web modifier activates. A `media-query` is an at-rule the emitter wraps the block in;
+*  `selector` composes onto the element, or stands as an ancestor for a mode. */
+const WEB_ACTIVATIONS = [
+	"selector",
+	"media-query",
+	"composite"
+];
+/** A ref to a modifier, spelled out because the kind's own class is what this is a field of. */
+const modifierRef = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === "modifier") }).meta({
+	ref: true,
+	refKind: "modifier"
+});
+/**
+* A modifier group's own fields.
+*
+* `type` says what category of condition the group's members are. A `mode` is an axis of the
+* document or a subtree: one option active at a time, switched by a viewer, activating on an
+* ancestor or the viewport. A `state` is a condition of the element itself, entered by interaction
+* or by a prop; it gets a grid column and a `data-create-force-<leaf>` twin. A group with no `type`
+* is a folder and its members are plain.
+*
+* `default` names the option a viewer starts in. The native theme reads it; on web the resting state
+* is the base values and no option is default.
+*/
+const modifierGroupFields = z.object({
+	type: z.enum(MODIFIER_CATEGORIES).optional(),
+	default: modifierRef.optional()
+});
+const Modifier = defineEntity({
+	kind: "modifier",
+	fields: z.object({
+		type: z.enum(WEB_ACTIVATIONS),
+		value: z.union([z.string(), z.lazy(() => Composite)])
+	}).check((ctx) => {
+		const { type, value } = ctx.value;
+		const wantsRef = type === "composite";
+		if (wantsRef === isRef(value)) return;
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			path: ["value"],
+			message: wantsRef ? "a `composite` modifier activates inside an element wearing a composite value, so `value` is a `Composite.ref(…)`" : `a \`${type}\` modifier's \`value\` is a string — a selector fragment, or the at-rule's condition`
+		});
+	}),
+	groupFields: modifierGroupFields,
+	uniqueLeaves: true,
+	invariants: (config) => modifierInvariants(config)
+});
+/** A path's last segment. */
+function modifierLeaf(path) {
+	return path.slice(path.lastIndexOf("/") + 1);
+}
+/**
+* The typed group a modifier belongs to — its category and the group's path — or `undefined` for a
+* plain one. The nearest typed ancestor answers; folders above it are organisation only.
+*/
+function modifierAxis(config, pathOrLeaf) {
+	const entity = config.resolve("modifier", pathOrLeaf);
+	if (!entity) return void 0;
+	return typedAncestor(config, entity.path);
+}
+/** The category of a modifier: `mode`, `state`, or `undefined` for a plain one. */
+function modifierCategory(config, pathOrLeaf) {
+	return modifierAxis(config, pathOrLeaf)?.type;
+}
+/** The typed groups of one category, each with the options it offers, in group order. */
+function modifierAxes(config, type) {
+	return config.groups("modifier").filter((group) => group.meta.type === type).map((group) => ({
+		path: group.path,
+		meta: group.meta,
+		options: Modifier.list(config).filter((item) => item.path.startsWith(`${group.path}/`))
+	}));
+}
+/** The mode axes a config declares — what a switcher offers and a token override conditions on. */
+function modeAxes(config) {
+	return modifierAxes(config, "mode");
+}
+function typedAncestor(config, path) {
+	const groups = new Map(config.groups("modifier").map((group) => [group.path, group.meta]));
+	const segments = path.split("/");
+	for (let depth = segments.length - 1; depth >= 1; depth--) {
+		const group = segments.slice(0, depth).join("/");
+		const meta = groups.get(group);
+		if (meta?.type) return {
+			group,
+			type: meta.type,
+			meta
+		};
+	}
+}
+/**
+* The rule one item's schema cannot see, because it spans the kind: a typed group is the axis, so
+* it sits under no other typed group and holds its options as direct children. That is what lets
+* every reader split an option's path at its last slash to find the axis. Leaf uniqueness is the
+* framework's, from `uniqueLeaves`.
+*/
+function modifierInvariants(config) {
+	const problems = [];
+	const items = Modifier.list(config);
+	const typed = config.groups("modifier").filter((group) => group.meta.type !== void 0);
+	for (const group of typed) {
+		const above = typedAncestor(config, group.path);
+		if (above) problems.push(`Modifier group "${group.path}" is typed but sits under the typed group "${above.group}"; a typed group is the axis and nests under folders only.`);
+	}
+	for (const item of items) {
+		const axis = typedAncestor(config, item.path);
+		if (axis && item.path !== `${axis.group}/${item.leaf}`) problems.push(`Modifier "${item.path}" is nested inside the typed group "${axis.group}"; an axis holds its options directly.`);
+	}
+	return problems;
+}
+//#endregion
+export { MODIFIER_CATEGORIES, Modifier, WEB_ACTIVATIONS, modeAxes, modifierAxes, modifierAxis, modifierCategory, modifierGroupFields, modifierInvariants, modifierLeaf };

package/dist/entities/system/Motion.d.ts

@@ -0,0 +1,28 @@
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/Motion.d.ts
+declare const Motion: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject<{
+  runtime: z.ZodLiteral<"css">;
+  keyframes: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  duration: z.ZodOptional<z.ZodString>;
+  delay: z.ZodOptional<z.ZodString>;
+  timingFunction: z.ZodOptional<z.ZodString>;
+  iterationCount: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+  direction: z.ZodOptional<z.ZodString>;
+  fillMode: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  runtime: z.ZodLiteral<"js">;
+  initial: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  animate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  transition: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  whileHover: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  whileTap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  whileFocus: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  whileDrag: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  drag: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+  dragConstraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+  dragElastic: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>], "runtime">, z.ZodObject<Record<never, never>, z.core.$strip>, "motion", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Motion };

package/dist/entities/system/Motion.js

@@ -0,0 +1,48 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { z } from "zod";
+//#region src/entities/system/Motion.ts
+/**
+* Motion (`fade/in`) — an animation preset, DISCRIMINATED by `runtime` so the payload is
+* coupled to how it animates, not loosely optional:
+*  - `css` → `keyframes` REQUIRED (codegen emits `@keyframes` from them); a css preset with
+*    no keyframes — which used to validate and silently emit nothing — is now rejected.
+*  - `js`  → no keyframes; carries the interaction state the client drives.
+* Illegal cross-runtime mixes (a css preset with `animate`, a js preset with `keyframes`)
+* can't be represented — each member is strict.
+*
+* Each member declares its WHOLE surface, because `strictObject` drops what it doesn't name and does
+* it silently: the first version declared three js fields, so every gesture preset in a real system
+* lost `whileHover`/`whileTap`/`drag` on the way in and animated nothing.
+*/
+const gesture = z.record(z.string(), z.unknown()).optional();
+const CssMotion = z.strictObject({
+	runtime: z.literal("css"),
+	keyframes: z.record(z.string(), z.record(z.string(), z.unknown())),
+	duration: z.string().optional(),
+	delay: z.string().optional(),
+	timingFunction: z.string().optional(),
+	iterationCount: z.union([z.string(), z.number()]).optional(),
+	direction: z.string().optional(),
+	fillMode: z.string().optional()
+});
+const JsMotion = z.strictObject({
+	runtime: z.literal("js"),
+	initial: gesture,
+	animate: gesture,
+	transition: gesture,
+	whileHover: gesture,
+	whileTap: gesture,
+	whileFocus: gesture,
+	whileDrag: gesture,
+	drag: z.union([z.boolean(), z.string()]).optional(),
+	dragConstraints: z.record(z.string(), z.number()).optional(),
+	dragElastic: z.number().optional()
+});
+const Motion = defineEntity({
+	kind: "motion",
+	label: "Motion",
+	labelPlural: "Motion presets",
+	fields: z.discriminatedUnion("runtime", [CssMotion, JsMotion])
+});
+//#endregion
+export { Motion };

package/dist/entities/system/Operation.d.ts

@@ -0,0 +1,100 @@
+import { DerivedEntityClass } from "../../framework/defineDerivedEntity.js";
+import { Config } from "../../framework/Config.js";
+import { ComputedInput } from "../../framework/registry.js";
+import { z } from "zod";
+
+//#region src/entities/system/Operation.d.ts
+declare const Operation: DerivedEntityClass<z.ZodObject<{
+  kind: z.ZodString;
+  verb: z.ZodString;
+  readOnly: z.ZodBoolean;
+  label: z.ZodString;
+  description: z.ZodString;
+  scope: z.ZodString;
+  creates: z.ZodBoolean;
+  approval: z.ZodOptional<z.ZodEnum<{
+    destructive: "destructive";
+    "reference-change": "reference-change";
+  }>>;
+}, z.core.$strip>, {
+  inputSchema: ({
+    member: op,
+    config
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      kind: string;
+      verb: string;
+      readOnly: boolean;
+      label: string;
+      description: string;
+      scope: string;
+      creates: boolean;
+      approval?: "destructive" | "reference-change" | undefined;
+    };
+  }) => z.ZodTypeAny<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | undefined;
+  execute: ({
+    member: op,
+    config: declaring
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      kind: string;
+      verb: string;
+      readOnly: boolean;
+      label: string;
+      description: string;
+      scope: string;
+      creates: boolean;
+      approval?: "destructive" | "reference-change" | undefined;
+    };
+  }) => ((input: Record<string, unknown>, config: Config) => unknown) | undefined; /** The sub-entity collection this op targets (`layers`) — absent on a kind-level op. */
+  field: ({
+    member: op
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      kind: string;
+      verb: string;
+      readOnly: boolean;
+      label: string;
+      description: string;
+      scope: string;
+      creates: boolean;
+      approval?: "destructive" | "reference-change" | undefined;
+    };
+  }) => string | undefined;
+  /** An op-declared title composer, for a verb that doesn't read as `<Verb> <Noun>`. A function,
+   *  so it can't be stored — the entity label it takes is the caller's to supply. */
+  title: ({
+    member: op,
+    config
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      kind: string;
+      verb: string;
+      readOnly: boolean;
+      label: string;
+      description: string;
+      scope: string;
+      creates: boolean;
+      approval?: "destructive" | "reference-change" | undefined;
+    };
+  }) => ((entity: string) => string) | undefined;
+  /** A runnable example bound to this config — the op's own `example` when it declares one (its
+   *  input isn't an address shape), else filled from the input schema. */
+  example: ({
+    member: op,
+    config
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      kind: string;
+      verb: string;
+      readOnly: boolean;
+      label: string;
+      description: string;
+      scope: string;
+      creates: boolean;
+      approval?: "destructive" | "reference-change" | undefined;
+    };
+  }) => Record<string, unknown> | undefined;
+}>;
+//#endregion
+export { Operation };

package/dist/entities/system/Operation.js

@@ -0,0 +1,236 @@
+import { CONFIG_OPERATION_KIND } from "../../framework/config-operation-kind.js";
+import { isPlainObject } from "../../framework/utils/field-path.js";
+import { resolveInputSchema } from "../../framework/schemas.js";
+import { opsForKind } from "../../framework/registry.js";
+import { opOf } from "../../framework/config-op.js";
+import { configSchemas } from "../../framework/config-ops.js";
+import { defineDerivedEntity } from "../../framework/defineDerivedEntity.js";
+import { z } from "zod";
+//#region src/entities/system/Operation.ts
+/**
+* `Operation` — the capability catalog, a derived entity. One ref-able member per (kind, verb) the
+* Config's owned kinds expose — mutations and reads (`list`/`get`/`dependents`) alike, each tagged
+* `readOnly` — computed from each kind's `schemas` map (`opsForKind`). Read-only: you can't author a
+* capability that doesn't exist.
+*
+* `inputSchema` (a zod schema) and `execute` (a function) are non-serializable, so they live as
+* `computed` fields — recomputed on read from the kind's `schemas[verb]`, never stored.
+*
+* An op also carries what it means: its verb `label`, its `description`, what it addresses (`scope`),
+* whether it `creates`, and a runnable discovery `example`. All declared next to the op's `input` in
+* `schemas.ts` — or, for a custom op, on the entity that declares it — because that's where the verb
+* is defined. A consumer therefore never infers meaning from a verb string, and adding an op touches
+* no consumer: the `Tool` surface picks it up with correct display, prose, and example.
+*/
+/** The op entry behind a member — a kind's own, or the config-scoped table when the "kind" is the
+*  Config. One lookup so `inputSchema`, `execute`, `title` and `example` don't each branch. */
+function opEntry(source, kind, verb) {
+	if (kind === "config") return configSchemas(source.name)[verb];
+	return source.entityOf(kind)?.schemas[verb];
+}
+/**
+* The sub-entity collection a sub-op targets (`sub-create/layers` → `layers`); absent on a
+* kind-level op. The only thing a verb string is ever split for.
+*
+* A nested collection keeps its whole path (`sub-create/props/value` → `props/value`), because that
+* path is what identifies it: truncating at the first segment would name the outer collection, and
+* two ops that address different things would answer to one name.
+*/
+function opField(verb) {
+	const slash = verb.indexOf("/");
+	return slash === -1 ? void 0 : verb.slice(slash + 1);
+}
+/** Keep only the first field of a body — a minimal patch, for an op that merges rather than sets. */
+function onePartial(data) {
+	const key = Object.keys(data)[0];
+	return key ? { [key]: data[key] } : {};
+}
+const asRecord = (value) => value && typeof value === "object" ? value : {};
+/** The entity this op's example addresses, plus the body and member it reads from — a real one where
+*  the config has one, so a generated example is runnable. A sub-op needs an owner that actually has
+*  the collection; a group op addresses a group NODE, never an item. */
+function target(config, kind, scope, field) {
+	if (scope === "group") {
+		const group = config.groups(kind)[0];
+		return {
+			path: group?.path ?? kind,
+			body: asRecord(group?.meta),
+			members: {}
+		};
+	}
+	const items = config.list(kind, { retired: false });
+	const slash = field?.indexOf("/") ?? -1;
+	if (config.entityOf(kind)?.singleton) {
+		const body = asRecord(items[0]?.toJSON());
+		return {
+			path: kind,
+			body,
+			members: field ? asRecord(body[field]) : {},
+			...field ? { section: true } : {}
+		};
+	}
+	if (field && slash !== -1) {
+		const [outer, inner] = [field.slice(0, slash), field.slice(slash + 1)];
+		for (const item of items) {
+			const body = asRecord(item.toJSON());
+			for (const [key, member] of Object.entries(asRecord(body[outer]))) {
+				const members = asRecord(asRecord(member)[inner]);
+				if (Object.keys(members).length === 0) continue;
+				return {
+					path: item.path,
+					body,
+					members,
+					owner: key
+				};
+			}
+		}
+		return {
+			path: `${kind}/example`,
+			body: {},
+			members: {}
+		};
+	}
+	const item = field ? items.find((entry) => asRecord(entry.toJSON())[field]) : items[0];
+	const body = asRecord(item?.toJSON());
+	return {
+		path: item?.path ?? `${kind}/example`,
+		body,
+		members: field ? asRecord(body[field]) : {}
+	};
+}
+/** The sequence a kind-level reorder rearranges — the kind's group nodes when the op is scoped to
+*  groups, its items otherwise. Paths, because that is what a reorder's `order` is a list of. */
+function sequenceOf(config, kind, scope) {
+	return scope === "group" ? config.groups(kind).map((group) => group.path) : config.list(kind).map((item) => item.path);
+}
+/**
+* A runnable example invocation, built by filling the op'S own input — one producer per address field
+* (`path`, `key`, `data`, `to`, `order`), so nothing here knows a verb. The op supplies the two bits
+* a schema can't express (`scope`, `creates`); an op whose input isn't an address shape declares its
+* own `example` instead (a component's `validate` does).
+*
+* Bound to a real entity where the config has one, falling back to a `<kind>/example` path when it
+* doesn't — an empty config yields a placeholder example rather than an error.
+*
+* A placeholder covers an address (`{ path: 'token/example' }` parses; it merely resolves to nothing),
+* but it cannot cover a body: a kind with no entity to read has no fields to show, so `data` comes out
+* empty and the schema that requires one refuses it. So the filled example is checked against the op's
+* own input before it is offered, and an input the op would reject is handed back as nothing.
+*
+* Undefined rather than best-effort because of who reads this. Operation discovery prints it and a
+* model copies it verbatim, so an example that cannot be sent is worse than no example at all: it
+* teaches the caller to write a refusal, and the caller has no way to tell that from a real one.
+*/
+function exampleFor(config, op) {
+	const field = opField(op.verb);
+	const { path, body, members, owner, section } = target(config, op.kind, op.scope, field);
+	const targetPath = op.creates === true && field === void 0 ? `${path}-2` : path;
+	const [firstKey, firstMember] = Object.entries(members)[0] ?? [];
+	const memberKey = op.creates ? "newMember" : firstKey ?? "member";
+	let source = body;
+	if (section) source = members;
+	else if (field) source = firstMember;
+	const shape = op.inputSchema instanceof z.ZodObject ? op.inputSchema.shape : {};
+	const out = {};
+	for (const name of Object.keys(shape)) if (name === "path") out.path = targetPath;
+	else if (name === "owner") out.owner = owner ?? "member";
+	else if (name === "key") out.key = memberKey;
+	else if (name === "order") out.order = field ? Object.keys(members) : sequenceOf(config, op.kind, op.scope);
+	else if (name === "data") if (!isPlainObject(source)) out.data = source;
+	else out.data = op.creates ? source : onePartial(source);
+	else if (name === "to") out.to = "key" in shape ? `${memberKey}-2` : `${targetPath}-2`;
+	if (op.inputSchema && !z.validate(op.inputSchema, out)) return void 0;
+	return out;
+}
+const Operation = defineDerivedEntity({
+	kind: "operation",
+	label: "Operation",
+	fields: z.object({
+		kind: z.string(),
+		verb: z.string(),
+		readOnly: z.boolean(),
+		/** The verb's human name (`Create`, `Add`) — declared by the op, not inferred from the verb. */
+		label: z.string(),
+		/** What the op does, for a model to choose it by — the derived default a `Tool` may override. */
+		description: z.string(),
+		/** `item` | `collection` | `group` — what the op addresses. Decides plural-vs-singular display
+		*  and which entity an example binds to; the reason no consumer parses a verb. */
+		scope: z.string(),
+		/** The innermost address is new (a create), so an example must not reuse an existing one. */
+		creates: z.boolean(),
+		approval: z.enum(["destructive", "reference-change"]).optional()
+	}),
+	deriveMembers: (source) => Object.fromEntries([...Object.entries(configSchemas(source.name)).map(([verb, entry]) => [`${CONFIG_OPERATION_KIND}/${verb}`, {
+		kind: CONFIG_OPERATION_KIND,
+		verb,
+		readOnly: entry.readOnly,
+		label: entry.label,
+		description: entry.description,
+		scope: entry.scope,
+		creates: false,
+		approval: entry.approval
+	}]), ...source.ownedKinds().flatMap((kind) => opsForKind(source.entityOf(kind), source).map((op) => [`${kind}/${op.verb}`, {
+		kind: op.kind,
+		verb: op.verb,
+		readOnly: op.readOnly,
+		label: op.label,
+		description: op.description,
+		scope: op.scope,
+		creates: op.creates ?? false,
+		approval: op.approval
+	}]))]),
+	computed: {
+		inputSchema: ({ member: op, config }) => {
+			const declared = opEntry(config, String(op.kind), String(op.verb))?.input;
+			return declared === void 0 ? void 0 : resolveInputSchema(declared, { config });
+		},
+		execute: ({ member: op, config: declaring }) => {
+			if (!opEntry(declaring, String(op.kind), String(op.verb))?.handler) return void 0;
+			return (input, config) => {
+				const invocation = opOf({
+					kind: String(op.kind),
+					verb: String(op.verb),
+					input
+				});
+				return config.run(invocation);
+			};
+		},
+		/** The sub-entity collection this op targets (`layers`) — absent on a kind-level op. */
+		field: ({ member: op }) => opField(String(op.verb)),
+		/** An op-declared title composer, for a verb that doesn't read as `<Verb> <Noun>`. A function,
+		*  so it can't be stored — the entity label it takes is the caller's to supply. */
+		title: ({ member: op, config }) => opEntry(config, String(op.kind), String(op.verb))?.title,
+		/** A runnable example bound to this config — the op's own `example` when it declares one (its
+		*  input isn't an address shape), else filled from the input schema. */
+		example: ({ member: op, config }) => {
+			const declared = opEntry(config, String(op.kind), String(op.verb))?.example;
+			const inputSchema = (() => {
+				const raw = opEntry(config, String(op.kind), String(op.verb))?.input;
+				return raw === void 0 ? void 0 : resolveInputSchema(raw, { config });
+			})();
+			try {
+				if (declared) {
+					const { path } = target(config, String(op.kind), String(op.scope), opField(String(op.verb)));
+					return declared({
+						config,
+						kind: String(op.kind),
+						path
+					});
+				}
+				return exampleFor(config, {
+					kind: String(op.kind),
+					verb: String(op.verb),
+					scope: String(op.scope),
+					creates: Boolean(op.creates),
+					inputSchema
+				});
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				console.warn(`[uds] the example for ${String(op.kind)}/${String(op.verb)} failed and was left out: ${reason}`);
+				return;
+			}
+		}
+	}
+});
+//#endregion
+export { Operation, opField };

package/dist/entities/system/Package.d.ts

@@ -0,0 +1,42 @@
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/Package.d.ts
+/**
+ * Package (`react-native`, `@ariakit/react`, `motion/react`) — one MODULE a system renders through.
+ *
+ * **The path IS the specifier**, verbatim, subpath and all — the same choice `File` makes for its src.
+ * So there is no `module` field: a second copy of the path could disagree with it, which is the
+ * reason a `File` computes its `binary` rather than storing one.
+ *
+ * Verbatim matters because the stored form has to regenerate the import an author wrote. `motion` and
+ * `motion/react` are ONE npm package and TWO modules; emitting `from 'motion'` for a source that
+ * wrote `from 'motion/react'` names a different entry point that resolves to a different file. That
+ * the two are one thing to INSTALL is a separate question, and the seal is the only place it is asked
+ * — `packageName` collapses them there.
+ *
+ * A key derived from the module — a slug like `ariakit` — is what this replaced. The slug was
+ * resolved over the whole import SET so two specifiers sharing a scope could both qualify away from
+ * it, which made a key depend on what else happened to be imported: `@phosphor-icons/core` arriving
+ * beside `@phosphor-icons/react` renamed the latter and stranded every ref that named it. npm has
+ * already made a module name unique; nothing here has to.
+ *
+ * The same shape `Icon` uses for a glyph library, with one difference in where membership comes from.
+ * An icon group lists every glyph the package exports, because a person picks one from a picker and
+ * all of them are candidates. A package's exports are only what a render actually placed in JSX,
+ * because nobody browses a component library's exports; the build registers them from JSX usage. The
+ * MODULE set is broader: it records every external module the render closure needs, which is what
+ * makes the portable config the source of truth for consumer install requirements.
+ *
+ * Ordinary component authoring does not maintain this graph: the build derives modules and exports
+ * from the source it walked. A human may still author one — to carry a label, or to pin a `version` —
+ * and build collection updates rather than replaces it, so that metadata survives. What authoring
+ * cannot do is choose the path.
+ */
+declare const Package: EntityClass<z.ZodObject<{
+  version: z.ZodOptional<z.ZodString>;
+  exports: z.ZodOptional<SubEntityClass<z.ZodObject<{}, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "package", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Package };