@yahoo/uds-create-config 5.26.0 → 5.27.0

package/dist/configs/react-native-system.d.ts

@@ -69,10 +69,19 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
   tokens: EntityClass<_$zod.ZodObject<Omit<{
     value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     type: _$zod.ZodOptional<_$zod.ZodString>;
-    overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
+    overrides: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodPipe<_$zod.ZodArray<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
       value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-    }, _$zod_v4_core0.$strip>>>;
+    }, _$zod_v4_core0.$strip>>, _$zod.ZodTransform<Record<string, {
+      on: OverrideCondition;
+      value: string | number | Ref | ComposedValue;
+    }>, {
+      on: OverrideCondition;
+      value: string | number | Ref | ComposedValue;
+    }[]>>, SubEntityClass<_$zod.ZodObject<{
+      on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+    }, _$zod_v4_core0.$strip>>]>>;
     utility: _$zod.ZodOptional<_$zod.ZodBoolean>;
     property: _$zod.ZodOptional<_$zod.ZodObject<{
       syntax: _$zod.ZodOptional<_$zod.ZodString>;
@@ -81,10 +90,19 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
     cssVariable: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodLiteral<false>]>>;
   }, "value" | "property" | "overrides" | "cssVariable"> & {
     value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-    overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
+    overrides: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodPipe<_$zod.ZodArray<_$zod.ZodObject<{
+      on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
+      value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+    }, _$zod_v4_core0.$strip>>, _$zod.ZodTransform<Record<string, {
+      on: OverrideCondition;
+      value: string | number | boolean | Ref | DerivedColor;
+    }>, {
+      on: OverrideCondition;
+      value: string | number | boolean | Ref | DerivedColor;
+    }[]>>, SubEntityClass<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
       value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-    }, _$zod_v4_core0.$strip>>>;
+    }, _$zod_v4_core0.$strip>>]>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Omit<{
     cssPrefix: _$zod.ZodOptional<_$zod.ZodString>;
     cssVariables: _$zod.ZodOptional<_$zod.ZodBoolean>;

package/dist/configs/system.js

@@ -67,6 +67,7 @@ import { cssMotionStrictMigration } from "../migrations/20261009181635_css_motio
 import { linkOverrideRefMigration } from "../migrations/20261009193004_link_override_ref.js";
 import { linkedComponentModulesMigration } from "../migrations/20261012200606_linked_component_modules.js";
 import { componentStatesMigration } from "../migrations/20261013154037_component_states.js";
+import { tokenOverridesListMigration } from "../migrations/20261013164300_token_overrides_list.js";
 const System = defineConfig({
 	name: WEB_CONFIG_NAME,
 	description: "A design system: the values, primitives and compositions an app is built from. A ref is written `{ \"__ref\": \"<kind>:<path>\" }`, so a token is `{ \"__ref\": \"token:<group>/<name>\" }` and a token group is `{ \"__ref\": \"token:<group>\" }`. Build it in this order. Tokens first, in groups by purpose (colors, spacing, radii, type sizes), since everything else names them. Then style properties, each with `values` holding one ref to the token group whose members it accepts (`{ \"__ref\": \"token:color\" }`), so a prop takes token names rather than raw CSS; add a string keyword only for a value no token holds. A style rule's bag holds a prop's values (`\"padding\": \"4\"`, `\"bg\": \"brand\"`), never raw CSS. Then a few primitive components, one layer each, whose props are style properties (a box for layout and surface, a text for type, a pressable for interaction). Then every other component composed from those primitives: its layers name a primitive or an element, its anatomy places them (a node renders a layer, a tag or `Slot` where a slot prop's content lands; `children` is the edge list; `visible` is `{ \"$state\": \"<prop>\" }`; a prop shown in a nested layer is a `forward` route, and `$state` never sits in a node's props), and its style rules set style-property values per layer, keyed by prop values when a variant changes them. Modes (a dark mode is `{ type: \"selector\", value: \".dark\" }`) change token values through a token's `overrides`, so a component never restyles for a mode; modifiers (hover, focus, disabled) name a state, and a style rule applies under one as a `_hover` block inside a layer bag. Composites bundle style values that recur. Last, register canvas roles: the canvas draws with them, one entity per tool (`frame` for the layout primitive, `text` for the text primitive, `image`) whose entries name the components that tool inserts, and a tool whose role is unregistered is disabled. Give each component a `preview` entry under `*` so it shows content, and never write a CSS property name where a style-property name belongs.",
@@ -145,5 +146,6 @@ if (!registeredSchemaMigrations().has(20261009181635)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261009193004)) registerSchemaMigrations(linkOverrideRefMigration);
 if (!registeredSchemaMigrations().has(20261012200606)) registerSchemaMigrations(linkedComponentModulesMigration);
 if (!registeredSchemaMigrations().has(20261013154037)) registerSchemaMigrations(componentStatesMigration);
+if (!registeredSchemaMigrations().has(20261013164300)) registerSchemaMigrations(tokenOverridesListMigration);
 //#endregion
 export { System };

package/dist/entities/native/NativeToken.d.ts

@@ -12,10 +12,19 @@ declare const nativeTokenValue: z.ZodType<number | boolean | string | Ref$1 | De
 declare const NativeToken: EntityClass<z.ZodObject<Omit<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;
@@ -24,10 +33,19 @@ declare const NativeToken: EntityClass<z.ZodObject<Omit<{
   cssVariable: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
 }, "value" | "property" | "overrides" | "cssVariable"> & {
   value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | boolean | Ref | DerivedColor;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | boolean | Ref | DerivedColor;
+  }[]>>, SubEntityClass<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>]>>;
 }, z.core.$strip>, z.ZodObject<Omit<{
   cssPrefix: z.ZodOptional<z.ZodString>;
   cssVariables: z.ZodOptional<z.ZodBoolean>;

package/dist/entities/native/NativeToken.js

@@ -1,5 +1,6 @@
 import { refSchema } from "../../framework/utils/refs.js";
 import { oklchColor } from "../system/color.js";
+import { orList } from "../../framework/defineSubEntity.js";
 import { Font } from "../system/Font.js";
 import { NATIVE_CONFIG_NAME } from "../../configs/platform.js";
 import { prepareLinkedTokenBody } from "../system/linked-token-values.js";
@@ -66,7 +67,7 @@ const NativeToken = Token.extend({
 	entityName: "NativeToken",
 	fields: {
 		value: nativeTokenValue,
-		overrides: NativeOverride.optional(),
+		overrides: orList(NativeOverride).optional(),
 		cssVariable: null,
 		property: null
 	},

package/dist/entities/system/LinkedSystem.js

@@ -753,8 +753,9 @@ displayName: ({ member, path }) => typeof member.name === "string" && member.nam
 	bulkOverlayWrite: ({ accessor, path, overlay }) => ({ [`options.${accessor}.${path}`]: overlay })
 });
 /** An `override` or `extend` body with its `styles` as a list, in the stored form: the record keyed by
-*  each rule's condition, as `Component.item` stores one. Only a component's `styles` is a rule list —
-*  every other kind's is a record — so a list here is one whatever accessor it sits under. */
+*  each rule's condition, as `Component.item` stores one. Only a component has `styles`, so a list
+*  there is a rule list whatever accessor it sits under. A token's `overrides` list is stored as
+*  written and keyed where the overlay is read. */
 function storedPinBody(body) {
 	if (!isPlainObject(body) || !Array.isArray(body.styles)) return body;
 	return {

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

@@ -44,10 +44,19 @@ declare function defineOverride<TValue extends z.ZodTypeAny>(value: TValue): Sub
 declare const tokenFields: z.ZodObject<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;
@@ -61,10 +70,19 @@ type TokenBody = z.infer<typeof tokenFields>;
 declare const TokenEntity: EntityClass<z.ZodObject<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;

package/dist/entities/system/Token.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, pathOf, ref, refKey, sourceOf } from "../../framework/utils/refs.js";
 import { composedValueSchemas } from "./composed-values.js";
 import { defineEntity } from "../../framework/defineEntity.js";
-import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { defineSubEntity, orList } from "../../framework/defineSubEntity.js";
 import { Font } from "./Font.js";
 import { Modifier } from "./Modifier.js";
 import { spellTokenRead } from "./token-values.js";
@@ -112,7 +112,8 @@ function defineOverride(value) {
 			on: config ? declaredCondition(config) : overrideConditionSchema,
 			value
 		}),
-		key: (override) => overrideKey(override.on)
+		key: (override) => overrideKey(override.on),
+		listed: true
 	});
 }
 const Override = defineOverride(tokenValue);
@@ -128,7 +129,7 @@ const TokenEntity = defineEntity({
 	fields: z.object({
 		value: tokenValue.describe("The base value: a literal, a ref to another token, or a composed value such as a gradient."),
 		type: z.string().optional().describe("The CSS value type, when the value alone does not say it."),
-		overrides: Override.optional().describe("Per-mode values, keyed by the condition they apply under."),
+		overrides: orList(Override).optional().describe("Per-mode values, a list of `{ on, value }`. Stored keyed by the condition each applies under."),
 		utility: z.boolean().optional().describe("`false` keeps the token out of its group's values, so a style prop that takes the group writes no class for it — `spacing/scale` powers `--spacing` without becoming a `p-scale`. A ref naming the token still resolves."),
 		property: z.strictObject({
 			syntax: z.string().optional().describe("The `@property` syntax, as `<length>`. Defaults to `*`."),

package/dist/framework/Config.d.ts

@@ -73,7 +73,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20261013154037;
+declare const SERIALIZED_CONFIG_VERSION = 20261013164300;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -318,6 +318,37 @@ function leafOf(field) {
 function wholeBodySchema(entry, ctx = {}) {
 	return dataSchema(entry.schemas, "create", ctx) ?? dataSchema(entry.schemas, "replace", ctx);
 }
+/**
+* An overlay whose bodies hold a list for a collection keyed by its members (`defineSubEntity({ key })`),
+* with each list written as the record that collection is stored as. A pin stores its bodies as
+* authored, and the overlay is laid onto the source key by key, so a list left as written would
+* replace the source's record rather than add to it. A later member wins over an earlier one with
+* the same key.
+*/
+function keyedOverlay(entry, overlay) {
+	if (!entry) return overlay;
+	const keyed = (body) => {
+		if (!body) return body;
+		let out;
+		for (const [field, sub] of Object.entries(entry.subEntities)) {
+			const members = body[field];
+			if (!sub.key || !Array.isArray(members)) continue;
+			const record = {};
+			for (const member of members) record[sub.key(member)] = member;
+			out ??= { ...body };
+			out[field] = record;
+		}
+		return out ?? body;
+	};
+	const override = keyed(overlay.override);
+	const extend = keyed(overlay.extend);
+	if (override === overlay.override && extend === overlay.extend) return overlay;
+	return {
+		...overlay,
+		override,
+		extend
+	};
+}
 /** The sub-entity a field path names, at either depth. */
 function subEntityAt(entry, field) {
 	const slash = field.indexOf("/");
@@ -3764,7 +3795,7 @@ var Config = class Config {
 			const overlay = entry.bulkOverlay?.(args);
 			if (overlay !== void 0) return {
 				claimed,
-				overlay
+				overlay: keyedOverlay(this.entityOf(kind), overlay)
 			};
 			if (claimed) return { claimed: true };
 		}
@@ -5749,7 +5780,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20261013154037) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261013164300) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

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

@@ -16,7 +16,7 @@ interface KindSignature {
   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. */
+  /** A real entry from this config, as it is authored. */
   readonly example?: unknown;
 }
 interface AuthoringSignatureOptions {

package/dist/framework/config-ops.js

@@ -75,6 +75,19 @@ function authoringSignature(schema, options) {
 	const json = jsonSchema(schema);
 	return json === void 0 ? void 0 : renderSignature(withoutMetadata(json), options);
 }
+/**
+* A real entry, spelled the way it is authored. A collection whose schema offers only a list (see
+* `withDeprecated`) is stored as the record keyed by its members, so the example writes its members
+* as that list, and a reader copying it never learns the deprecated record.
+*/
+function authoredExample({ item, fields }) {
+	const body = item.toJSON();
+	const properties = fields?.properties;
+	if (!properties) return { [item.path]: body };
+	const authored = { ...body };
+	for (const [field, value] of Object.entries(body)) if (properties[field]?.type === "array" && value && typeof value === "object" && !Array.isArray(value)) authored[field] = Object.values(value);
+	return { [item.path]: authored };
+}
 /** 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) => {
@@ -87,14 +100,18 @@ function authoringSignatures(config, { depth, memberDepth = depth } = {}) {
 			if (signature) collections[field] = singleton ? `one section, no key (\`sub-update/${field}\`): ${signature}` : signature;
 		}
 		const first = config.list(kind)[0];
+		const create = dataSchemaOf(config, entity.schemas.create);
 		return [{
 			kind,
 			label: entity.label,
 			refHelper: entity.entityName,
-			create: authoringSignature(dataSchemaOf(config, entity.schemas.create), { depth }),
+			create: authoringSignature(create, { depth }),
 			collections,
 			group: authoringSignature(entity.groupCreateSchema, { depth }),
-			example: first ? { [first.path]: first.toJSON() } : void 0
+			example: first ? authoredExample({
+				item: first,
+				fields: jsonSchema(create)
+			}) : void 0
 		}];
 	});
 }
@@ -137,14 +154,18 @@ function authoringReference(config) {
 			collections[field] = jsonSchema(dataSchemaOf(config, entity.schemas[`sub-create/${field}`]));
 		}
 		const first = config.list(kind)[0];
+		const fields = jsonSchema(dataSchemaOf(config, entity.schemas.create));
 		return [{
 			kind,
 			label: entity.label,
 			refHelper: entity.entityName,
-			fields: jsonSchema(dataSchemaOf(config, entity.schemas.create)),
+			fields,
 			collections,
 			groupFields: jsonSchema(entity.groupCreateSchema),
-			example: first ? { [first.path]: first.toJSON() } : void 0
+			example: first ? authoredExample({
+				item: first,
+				fields
+			}) : void 0
 		}];
 	}) };
 }

package/dist/framework/defineSubEntity.d.ts

@@ -36,6 +36,9 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
    *  caller, so key and value can't drift, two members with the same identity can't both exist, and
    *  an edit that changes the identity moves the entry. Omit when the key is arbitrary. */
   readonly key?: (member: unknown) => string;
+  /** The collection is authored as a list of its members, which carry their own `key`. The keyed
+   *  record it is stored as is still read but no longer offered: see {@link orList}. */
+  readonly listed?: true;
   /** Whether a member DECLARES nothing — a style rule whose every layer bag is empty. Asked only
    *  when a \`sub-update\` would bring the member into being: a delta made entirely of removals has
    *  nothing to remove from a member that is not there, so creating one files an entry that emits
@@ -143,6 +146,7 @@ declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
    */
   base?: z.ZodTypeAny;
   key?: (member: unknown) => string;
+  listed?: true;
   vacant?: (member: unknown) => boolean;
   schemas?: UserSchemas;
   namespaces?: string;
@@ -161,6 +165,9 @@ declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
  * Two members with the same key are one member, the later one, as the key derivation on write
  * already treats a record whose keys disagree with their members — unless `merge` says how the two
  * combine, in which case the member is `merge(earlier, later)`, placed where the later one was.
+ *
+ * A collection declared `listed` still takes the keyed record but offers only the list, see
+ * {@link withDeprecated}.
  */
 declare function orList<F extends z.ZodTypeAny>(collection: SubEntityClass<F>, {
   merge

package/dist/framework/defineSubEntity.js

@@ -1,6 +1,7 @@
 import { kindOf, memberOf, memberRef, pathOf } from "./utils/refs.js";
 import { resolveSchema } from "./schemas.js";
 import { titleCase } from "./registry.js";
+import { withDeprecated } from "./utils/deprecated.js";
 import { z } from "zod";
 //#region src/framework/defineSubEntity.ts
 /**
@@ -78,6 +79,7 @@ function defineSubEntity(spec) {
 		fields: spec.fields,
 		base: spec.base,
 		key: spec.key,
+		...spec.listed ? { listed: true } : {},
 		vacant: spec.vacant,
 		schemas: spec.schemas,
 		namespaces: spec.namespaces,
@@ -126,6 +128,9 @@ function defineSubEntity(spec) {
 * Two members with the same key are one member, the later one, as the key derivation on write
 * already treats a record whose keys disagree with their members — unless `merge` says how the two
 * combine, in which case the member is `merge(earlier, later)`, placed where the later one was.
+*
+* A collection declared `listed` still takes the keyed record but offers only the list, see
+* {@link withDeprecated}.
 */
 function orList(collection, { merge } = {}) {
 	const key = collection.key;
@@ -142,6 +147,10 @@ function orList(collection, { merge } = {}) {
 		}
 		return keyed;
 	});
+	if (collection.listed) return withDeprecated({
+		offered: listed,
+		deprecated: collection
+	});
 	return z.union([listed, collection]);
 }
 //#endregion

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20261013154037;
+declare const CURRENT_SCHEMA_VERSION = 20261013164300;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20261013154037;
+const CURRENT_SCHEMA_VERSION = 20261013164300;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20261013154037) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20261013164300) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20261013154037;
+	const target = options?.target ?? 20261013164300;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20261013154037;
+	const target = options?.target ?? 20261013164300;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20261013154037;
+	const target = options?.target ?? 20261013164300;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/utils/deprecated.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A schema that still takes a deprecated form but no longer offers it.
+ *
+ * Parsing accepts `offered` or `deprecated`, so stored data and older config files keep loading.
+ * Rendered as JSON Schema, which is what tool signatures, `config/api`, the MCP's input schemas and
+ * the docs are built from, it shows only `offered`, so nothing that reads a schema learns the old
+ * form.
+ */
+import { z } from 'zod';
+/**
+ * `read` with every deprecated form shown in the JSON Schema it renders. The schema-version tripwire
+ * reads through this, since it guards everything a client accepts, offered or not.
+ */
+export declare function includingDeprecated<T>(read: () => T): T;
+export declare function withDeprecated<O extends z.ZodTypeAny, D extends z.ZodTypeAny>({ offered, deprecated, }: {
+    offered: O;
+    deprecated: D;
+}): z.ZodUnion<readonly [O, D]>;

package/dist/framework/utils/deprecated.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+function withDeprecated({ offered, deprecated }) {
+	const schema = z.union([offered, deprecated]);
+	const offeredOnly = () => {
+		const { $schema: _dialect, ...json } = z.toJSONSchema(offered, { io: "input" });
+		return json;
+	};
+	schema._zod.toJSONSchema = () => offeredOnly();
+	return schema;
+}
+//#endregion
+export { withDeprecated };

package/dist/migrations/20261013164300_token_overrides_list.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A token's `overrides` also takes a list of `{ on, value }`, which is stored as the record keyed by
+ * each override's condition. The stored form is unchanged, so the hop is identity.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const TOKEN_OVERRIDES_LIST_VERSION = 20261013164300;
+export declare const tokenOverridesListMigration: SchemaMigration;

package/dist/migrations/20261013164300_token_overrides_list.js

@@ -0,0 +1,10 @@
+//#region src/migrations/20261013164300_token_overrides_list.ts
+const TOKEN_OVERRIDES_LIST_VERSION = 20261013164300;
+const tokenOverridesListMigration = {
+	version: TOKEN_OVERRIDES_LIST_VERSION,
+	up(json) {
+		return json;
+	}
+};
+//#endregion
+export { TOKEN_OVERRIDES_LIST_VERSION, tokenOverridesListMigration };