@yahoo/uds-create-config 5.41.7 → 5.42.0

package/dist/configs/build-options.js

@@ -60,36 +60,35 @@ const buildFields = z.strictObject({
 		description: "The directory every sealed component file lives under, relative to the config. Emitted modules keep the layout beneath it. Unset, the `uds/components/` folder convention applies."
 	}).optional(),
 	/**
-	* Files to ship that no component imports — a toast queue's `createToast`, a motion wrapper like
-	* yos-v3's `SpringMotionConfig` — as paths relative to the config.
+	* Files under {@link inputDir} to keep out of what the system ships, as paths or globs relative to
+	* the config: `src/components/legacy`, `src/components/**\/*.mock.ts`.
 	*
-	* A build only emits component files and what they import, so a module apps import on its own
-	* never reached the output. That bites hardest for a system that links this one: its build emits
-	* only what this system's components reach, so it had nothing to import the module from. This
-	* system's own apps couldn't import `#uds/components/<file>` either. Listing a file here emits it,
-	* and what it imports, at its own path under `components/` — `#uds/components/toast-portal` here,
-	* `@/uds/registry/<slug>/toast-portal` for a consumer that links it.
-	*
-	* Each has to live under {@link inputDir}, like every other file the output mirrors. Shipping
-	* every file by default is planned.
+	* Every source file under `inputDir` ships by default, with what it imports. A module no component
+	* imports, a toast queue's `createToast` or a motion wrapper like yos-v3's `SpringMotionConfig`,
+	* is emitted at its own path under `components/`, so this system's apps import it as
+	* `#uds/components/<file>` and a system that links this one as `@/uds/registry/<slug>/<file>`.
+	* Tests, stories and type declarations never ship, and neither does a file only the config or a
+	* script imports. List a file here to keep it out as well, such as a helper whose npm
+	* dependencies a linking team shouldn't have to install. An excluded file nothing else imports is
+	* not sealed either.
 	*/
-	include: z.array(z.string().min(1).refine((value) => !value.startsWith("/") && !/^[A-Za-z]:/.test(value) && !value.replace(/\\/g, "/").split("/").includes(".."), { message: "A path in `include` is relative to the config, inside the project." })).meta({
-		title: "Include",
-		description: "A build only emits component files and what they import, so a module apps import but no component imports, such as a toast queue's `createToast` or a motion wrapper, never ships: a system that links yours has nothing to import it from, and your own apps can't import `#uds/components/<file>`. List those files here, as paths relative to the config: `src/components/toast-portal.tsx`. Each is emitted with what it imports under `components/`, and a linking system's build emits it too. Shipping every file by default is planned."
+	exclude: z.array(z.string().min(1).refine((value) => !value.startsWith("/") && !/^[A-Za-z]:/.test(value) && !value.replace(/\\/g, "/").split("/").includes(".."), { message: "A path in `exclude` is relative to the config, inside the project." })).meta({
+		title: "Exclude",
+		description: "Every source file under `inputDir` ships by default, with what it imports, so an app can import a module no component imports, such as a toast queue's `createToast`, from `#uds/components/<file>`, and a system that links yours can import it too. Tests, stories, type declarations and files only the config or a script imports never ship. List paths or globs here, relative to the config, to keep other files out: `src/components/legacy`, `src/components/**/*.mock.ts`."
 	}).optional(),
 	/**
 	* Files a team that links this system runs from its installed sources — a migration script that
 	* reads a team's old config and writes their new one — as paths relative to the config.
 	*
-	* Each is a root of the source graph, as an {@link include}d file is, so it is sealed, pushed and
-	* installed with the system's sources even though nothing imports it. Unlike an included file it
-	* is never emitted: a script runs as written, against the authoring package, so it may read the
+	* Each is a root of the source graph, so it is sealed, pushed and installed with the system's
+	* sources even though nothing imports it. Unlike a shipped module it is never emitted, even under
+	* {@link inputDir}: a script runs as written, against the authoring package, so it may read the
 	* config (`Token.get`, `Component.list`) where a shipped module may only read token values. A
 	* linking team runs it from the installed tree, `src/uds/registry/<slug>/<path>`.
 	*/
 	scripts: z.array(z.string().min(1).refine((value) => !value.startsWith("/") && !/^[A-Za-z]:/.test(value) && !value.replace(/\\/g, "/").split("/").includes(".."), { message: "A path in `scripts` is relative to the config, inside the project." })).meta({
 		title: "Scripts",
-		description: "Files a team that links this system runs from its installed sources, such as a migration script that reads their old config and writes their new one, as paths relative to the config: `src/migrate/convert.ts`. Each is sealed, pushed and installed with the system's sources, at `src/uds/registry/<slug>/<path>` in a linking project, but never emitted, so it runs as written against the authoring package and may read the config. A file apps import at runtime belongs in `include` instead."
+		description: "Files a team that links this system runs from its installed sources, such as a migration script that reads their old config and writes their new one, as paths relative to the config: `src/migrate/convert.ts`. Each is sealed, pushed and installed with the system's sources, at `src/uds/registry/<slug>/<path>` in a linking project, but never emitted, so it runs as written against the authoring package and may read the config. A file apps import at runtime ships without being listed."
 	}).optional(),
 	/** Where `uds build` writes. A CLI `--output-dir` still wins, because a one-off build into a
 	*  scratch directory is not a property of the system. */
@@ -131,6 +130,6 @@ const buildFields = z.strictObject({
 		description: `The React major the app this repo builds for runs. \`18\` wraps each emitted web component in \`forwardRef\`, so a call site's \`ref\` reaches its element. Unset, \`${BUILD_DEFAULTS.react}\`.`,
 		default: BUILD_DEFAULTS.react
 	}).optional()
-});
+}, { error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("include") ? "`settings.build.include` was removed: every source file under `inputDir` now ships by default. Delete it, and list any file to keep out in `settings.build.exclude`." : void 0 });
 //#endregion
 export { BUILD_DEFAULTS, buildFields };

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

@@ -33,7 +33,7 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
     }, _$zod_v4_core0.$strict>>;
     build: _$zod.ZodOptional<_$zod.ZodObject<{
       inputDir: _$zod.ZodOptional<_$zod.ZodString>;
-      include: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
+      exclude: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
       scripts: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
       outDir: _$zod.ZodOptional<_$zod.ZodString>;
       sourceAlias: _$zod.ZodOptional<_$zod.ZodString>;

package/dist/configs/system.js

@@ -22,6 +22,7 @@ import { motionJsonSchemaMigration } from "../migrations/20261015221052_motion_j
 import { motionTypeOnlyMigration } from "../migrations/20261016135620_motion_type_only.js";
 import { motionCompatibilityMigration } from "../migrations/20261016164316_motion_compatibility.js";
 import { nativeStyleArraysAndAutoMigration } from "../migrations/20261016201727_native_style_arrays_and_auto.js";
+import { buildExcludeMigration } from "../migrations/20261019165323_build_exclude.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -175,5 +176,6 @@ if (!registeredSchemaMigrations().has(20261016135620)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261015202345)) registerSchemaMigrations(componentElementSwapMigration);
 if (!registeredSchemaMigrations().has(20261016164316)) registerSchemaMigrations(motionCompatibilityMigration);
 if (!registeredSchemaMigrations().has(20261016201727)) registerSchemaMigrations(nativeStyleArraysAndAutoMigration);
+if (!registeredSchemaMigrations().has(20261019165323)) registerSchemaMigrations(buildExcludeMigration);
 //#endregion
 export { System };

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

@@ -24,7 +24,7 @@ declare const NativeSettings: EntityClass<z.ZodObject<Omit<{
   }, z.core.$strict>>;
   build: z.ZodOptional<z.ZodObject<{
     inputDir: z.ZodOptional<z.ZodString>;
-    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     scripts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     outDir: z.ZodOptional<z.ZodString>;
     sourceAlias: z.ZodOptional<z.ZodString>;

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

@@ -17,7 +17,7 @@ declare const SystemSection: SystemSectionClass;
  *  where linked systems are materialised. */
 declare const BuildSectionDefinition: SubEntityClass<z.ZodObject<{
   inputDir: z.ZodOptional<z.ZodString>;
-  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
   scripts: z.ZodOptional<z.ZodArray<z.ZodString>>;
   outDir: z.ZodOptional<z.ZodString>;
   sourceAlias: z.ZodOptional<z.ZodString>;
@@ -96,13 +96,20 @@ declare const PlaygroundSectionDefinition: SubEntityClass<z.ZodObject<{
 }, z.core.$strict>>;
 interface PlaygroundSectionClass extends Named<typeof PlaygroundSectionDefinition> {}
 declare const PlaygroundSection: PlaygroundSectionClass;
+/**
+ * {@link derivedInputDir} over paths alone, for a build that has walked its source graph but not yet
+ * written the `file` rows the computed `inputDir` reads. `components` are the config-relative paths
+ * of the component files, and `reached` answers them with every local file they import, asked only
+ * when the convention's folder doesn't settle it.
+ */
+declare function deriveInputDir(components: readonly string[], reached: () => readonly string[]): string;
 declare const SettingsDefinition: EntityClass<z.ZodObject<{
   system: z.ZodOptional<z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
   build: z.ZodOptional<z.ZodObject<{
     inputDir: z.ZodOptional<z.ZodString>;
-    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     scripts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     outDir: z.ZodOptional<z.ZodString>;
     sourceAlias: z.ZodOptional<z.ZodString>;
@@ -140,4 +147,4 @@ declare const SettingsDefinition: EntityClass<z.ZodObject<{
 interface SettingsClass extends Named<typeof SettingsDefinition> {}
 declare const Settings: SettingsClass;
 //#endregion
-export { BuildSection, BuildSectionClass, CSS_DEFAULTS, CssPrefix, CssSection, CssSectionClass, PLAYGROUND_DEFAULTS, PlaygroundSection, PlaygroundSectionClass, Settings, SettingsClass, SystemSection, SystemSectionClass, classPrefixOf, cssPrefixes, prefixed, varPrefixOf };
+export { BuildSection, BuildSectionClass, CSS_DEFAULTS, CssPrefix, CssSection, CssSectionClass, PLAYGROUND_DEFAULTS, PlaygroundSection, PlaygroundSectionClass, Settings, SettingsClass, SystemSection, SystemSectionClass, classPrefixOf, cssPrefixes, deriveInputDir, prefixed, varPrefixOf };

package/dist/entities/system/Settings.js

@@ -223,12 +223,21 @@ const derivedInputDir = createSliceMemo({
 	kinds: ["component", "file"],
 	compute: (config) => {
 		const components = localComponentFiles(config);
-		if (components.length === 0) return "";
-		const shared = sharedFolders(components.map(foldersOf));
-		for (let end = shared.length; end >= 2; end -= 1) if (shared[end - 2] === "uds" && shared[end - 1] === "components") return shared.slice(0, end).join("/");
-		return sharedFolders(reachedFiles(config, components).map(foldersOf)).join("/");
+		return deriveInputDir(components, () => reachedFiles(config, components));
 	}
 });
+/**
+* {@link derivedInputDir} over paths alone, for a build that has walked its source graph but not yet
+* written the `file` rows the computed `inputDir` reads. `components` are the config-relative paths
+* of the component files, and `reached` answers them with every local file they import, asked only
+* when the convention's folder doesn't settle it.
+*/
+function deriveInputDir(components, reached) {
+	if (components.length === 0) return "";
+	const shared = sharedFolders(components.map(foldersOf));
+	for (let end = shared.length; end >= 2; end -= 1) if (shared[end - 2] === "uds" && shared[end - 1] === "components") return shared.slice(0, end).join("/");
+	return sharedFolders(reached().map(foldersOf)).join("/");
+}
 const Settings = defineEntity({
 	kind: "settings",
 	label: "Settings",
@@ -257,4 +266,4 @@ const Settings = defineEntity({
 inputDir: ({ member, config }) => resolveInputDir(member.build) ?? derivedInputDir(config) }
 });
 //#endregion
-export { BuildSection, CSS_DEFAULTS, CssSection, PLAYGROUND_DEFAULTS, PlaygroundSection, Settings, SystemSection, classPrefixOf, cssPrefixes, prefixed, varPrefixOf };
+export { BuildSection, CSS_DEFAULTS, CssSection, PLAYGROUND_DEFAULTS, PlaygroundSection, Settings, SystemSection, classPrefixOf, cssPrefixes, deriveInputDir, prefixed, varPrefixOf };

package/dist/entities/system/shipped-modules.d.ts

@@ -0,0 +1,66 @@
+import { Config } from "../../framework/Config.js";
+
+//#region src/entities/system/shipped-modules.d.ts
+/**
+ * The modules a system ships beside its components: every source file under its `inputDir` that no
+ * component reaches, so an app imports it on its own (`#uds/components/toast-portal`) and a system
+ * that links this one emits it too (`@/uds/registry/<slug>/toast-portal`).
+ *
+ * One rule, read three ways. The owner's build emits these, the server serves them with a linked
+ * version, and a linking build emits them from the installed tree. Each reads it from the same
+ * sealed graph, so the three can't disagree about which files a system ships the way a hand-kept
+ * list did, where forgetting an entry failed only for a linked consumer.
+ */
+/** A sealed file as the rule reads it: its config-relative path and the local files it imports. */
+interface ShipGraphFile {
+  readonly path: string;
+  readonly imports: readonly string[];
+}
+/** The settings the rule reads, as config-relative paths. Structural, so a caller passes the
+ *  computed `inputDir` and the `build` record of an artifact it never loaded. */
+interface ShipRuleOptions {
+  /** The root the system's files are laid out beneath. Empty ships nothing: with no root there is
+   *  nowhere to emit a module at. */
+  readonly inputDir: string;
+  /** `settings.build.scripts`: sealed and run as written, never emitted. */
+  readonly scripts?: readonly string[];
+  /** `settings.build.exclude`: paths or globs kept out of the default set. */
+  readonly exclude?: readonly string[];
+  /** `settings.playground.pagesDir`: the pages `uds dev --playground` serves, which are this repo's
+   *  own and never ship, even when they sit under `inputDir`. */
+  readonly pagesDir?: string;
+}
+/**
+ * Whether `file` matches an `exclude` entry: a glob (`**`, `*`, `?`), or a plain path that names the
+ * file or a folder above it. Spelled out rather than taken from a glob package, because nothing in
+ * this package imports one and Studio runs the config in a browser.
+ */
+declare function matchesExclude(file: string, patterns: readonly string[]): boolean;
+/**
+ * Whether a file is in the default ship set by its path alone: a module under `inputDir` that isn't
+ * a test or story, a platform variant, a script, a playground page, or excluded. Whether it ships as a module of its
+ * own also depends on what imports it, which {@link shippedModuleRoots} decides.
+ */
+declare function shipsByDefault(file: string, options: ShipRuleOptions): boolean;
+/**
+ * The files that ship as modules of their own: in the default set, and imported by no other local
+ * file.
+ *
+ * What imports a file is what tells the three kinds apart. A component's helper is imported by the
+ * component, so it already ships as part of that module. A config-only file (`tokens.ts`,
+ * `composites.ts`) is imported by the config, and shipping it would fail the build, since those use
+ * `Token.ref(...)` as values. A script's helper is imported by the script. A file nothing imports
+ * is there for an app to import, so it ships, with everything it imports. `components` names the
+ * component files, which are emitted as their components already.
+ */
+declare function shippedModuleRoots(files: readonly ShipGraphFile[], options: ShipRuleOptions & {
+  readonly components?: readonly string[];
+}): string[];
+/**
+ * {@link shippedModuleRoots} over a built config: its `file` rows, each component's `file` ref, its
+ * computed `inputDir` and its build settings. What the server serves with a linked version, and what
+ * a linking build emits from the installed tree.
+ */
+declare function shippedModules(config: Config): string[];
+//#endregion
+export { ShipGraphFile, ShipRuleOptions, matchesExclude, shippedModuleRoots, shippedModules, shipsByDefault };

package/dist/entities/system/shipped-modules.js

@@ -0,0 +1,127 @@
+import { splitRef } from "../../framework/utils/refs.js";
+import { Settings } from "./Settings.js";
+import { SCRIPT_EXTENSIONS } from "./File.js";
+//#region src/entities/system/shipped-modules.ts
+/** A file-name part that marks a test or story (`button.test.tsx`), which no app imports. */
+const NOT_SHIPPED_MARKERS = new Set([
+	"test",
+	"spec",
+	"e2e",
+	"stories"
+]);
+/** Folders of tests and their fixtures. */
+const NOT_SHIPPED_FOLDERS = new Set(["__tests__", "__fixtures__"]);
+/** A Metro platform suffix (`toast.ios.tsx`): the variant travels with the file it varies rather
+*  than as a module of its own. */
+const PLATFORM_SUFFIXES = new Set([
+	"ios",
+	"android",
+	"native",
+	"web"
+]);
+/**
+* Whether a path's own name rules it out: a test or story, a type declaration, a platform variant,
+* or a file in a test or fixture folder. Read off the path's segments rather than matched with
+* patterns, since every path comes from a repo's tree and an unanchored pattern backtracks across a
+* name with many dots.
+*/
+function notShippedByName(file) {
+	const segments = file.split("/");
+	if (segments.slice(0, -1).some((folder) => NOT_SHIPPED_FOLDERS.has(folder))) return true;
+	const parts = (segments[segments.length - 1] ?? "").split(".");
+	const extension = parts[parts.length - 1] ?? "";
+	const middle = parts.slice(1, -1);
+	return middle.some((part) => NOT_SHIPPED_MARKERS.has(part)) || middle[middle.length - 1] === "d" && /^[mc]?ts$/.test(extension) || middle.length > 0 && PLATFORM_SUFFIXES.has(middle[middle.length - 1] ?? "");
+}
+/** Forward slashes, no leading `./`, no trailing slash. Scanned rather than matched with `/\/+$/`,
+*  which backtracks quadratically on a run of slashes (see `registry-dir.ts`). */
+const normalize = (value) => {
+	const posix = value.replaceAll("\\", "/");
+	const start = posix.startsWith("./") ? 2 : 0;
+	let end = posix.length;
+	while (end > start && posix[end - 1] === "/") end--;
+	return posix.slice(start, end);
+};
+const escapeRegExp = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+/**
+* Whether `file` matches an `exclude` entry: a glob (`**`, `*`, `?`), or a plain path that names the
+* file or a folder above it. Spelled out rather than taken from a glob package, because nothing in
+* this package imports one and Studio runs the config in a browser.
+*/
+function matchesExclude(file, patterns) {
+	const target = normalize(file);
+	return patterns.some((raw) => {
+		const pattern = normalize(raw);
+		if (!/[*?]/.test(pattern)) return target === pattern || target.startsWith(`${pattern}/`);
+		const source = pattern.split(/(\*\*\/|\*\*|\*|\?)/).map((part) => {
+			if (part === "**/") return "(?:.*/)?";
+			if (part === "**") return ".*";
+			if (part === "*") return "[^/]*";
+			if (part === "?") return "[^/]";
+			return escapeRegExp(part);
+		}).join("");
+		return new RegExp(`^${source}$`).test(target);
+	});
+}
+/**
+* Whether a file is in the default ship set by its path alone: a module under `inputDir` that isn't
+* a test or story, a platform variant, a script, a playground page, or excluded. Whether it ships as a module of its
+* own also depends on what imports it, which {@link shippedModuleRoots} decides.
+*/
+function shipsByDefault(file, options) {
+	const inputDir = normalize(options.inputDir);
+	const target = normalize(file);
+	if (!inputDir || !target.startsWith(`${inputDir}/`)) return false;
+	const dot = target.lastIndexOf(".");
+	if (dot < 0 || !SCRIPT_EXTENSIONS.has(target.slice(dot))) return false;
+	return !(notShippedByName(target) || (options.scripts ?? []).some((script) => normalize(script) === target) || matchesExclude(target, [...options.pagesDir ? [options.pagesDir] : [], ...options.exclude ?? []]));
+}
+/**
+* The files that ship as modules of their own: in the default set, and imported by no other local
+* file.
+*
+* What imports a file is what tells the three kinds apart. A component's helper is imported by the
+* component, so it already ships as part of that module. A config-only file (`tokens.ts`,
+* `composites.ts`) is imported by the config, and shipping it would fail the build, since those use
+* `Token.ref(...)` as values. A script's helper is imported by the script. A file nothing imports
+* is there for an app to import, so it ships, with everything it imports. `components` names the
+* component files, which are emitted as their components already.
+*/
+function shippedModuleRoots(files, options) {
+	const imported = new Set(files.flatMap((file) => file.imports.map(normalize)));
+	const components = new Set((options.components ?? []).map(normalize));
+	return files.map((file) => normalize(file.path)).filter((file) => !imported.has(file) && !components.has(file) && shipsByDefault(file, options)).sort();
+}
+/**
+* {@link shippedModuleRoots} over a built config: its `file` rows, each component's `file` ref, its
+* computed `inputDir` and its build settings. What the server serves with a linked version, and what
+* a linking build emits from the installed tree.
+*/
+function shippedModules(config) {
+	const settings = Settings.get(config);
+	const local = (ref) => {
+		if (!ref) return void 0;
+		const target = splitRef(ref);
+		return target.kind === "file" && !target.source ? target.path : void 0;
+	};
+	const files = config.list("file").map((item) => {
+		const { imports } = item.toJSON();
+		return {
+			path: item.path,
+			imports: Object.values(imports ?? {}).flatMap((edge) => local(edge.target?.__ref) ?? [])
+		};
+	});
+	const components = config.list("component").flatMap((component) => {
+		const { file } = component.toJSON();
+		return local(file?.__ref) ?? [];
+	});
+	return shippedModuleRoots(files, {
+		inputDir: settings?.inputDir ?? "",
+		scripts: settings?.build?.scripts,
+		exclude: settings?.build?.exclude,
+		pagesDir: settings?.playground?.pagesDir,
+		components
+	});
+}
+//#endregion
+export { matchesExclude, shippedModuleRoots, shippedModules, shipsByDefault };

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 = 20261016201727;
+declare const SERIALIZED_CONFIG_VERSION = 20261019165323;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -6,7 +6,7 @@ import { applyPathDelta, isPlainObject, namedFields, pathSegments, sectionDelta,
 import { METADATA_KEYS, declaredField } from "./utils/field-schema.js";
 import { dataSchema, resolveInputSchema } from "./schemas.js";
 import { isComposedValue } from "../entities/system/composed-values.js";
-import { borrowedSlug, classifyOverlay } from "./source-integrity.js";
+import { borrowedSlug, classifyOverlay, uniteEntries } from "./source-integrity.js";
 import { kindBorrowable, titleCase } from "./registry.js";
 import { isGroupBody } from "./utils/group.js";
 import { authoredBag, pinBodyStyleNumbers, stylePropNumberUnit } from "./projections.js";
@@ -5862,7 +5862,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 > 20261016201727) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261019165323) 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.`);
 		const leftover = wire.options;
@@ -6095,19 +6095,6 @@ function layerOverlay({ onto, patch, theirs, union }) {
 	}
 	return merged;
 }
-/** A union that keeps the existing order and drops a repeat. Entries are refs and small literals, so
-*  identity is what they serialize to rather than reference equality. */
-function uniteEntries(existing, added) {
-	const out = Array.isArray(existing) ? [...existing] : [];
-	const seen = new Set(out.map((entry) => JSON.stringify(entry)));
-	for (const entry of added) {
-		const key = JSON.stringify(entry);
-		if (seen.has(key)) continue;
-		seen.add(key);
-		out.push(entry);
-	}
-	return out;
-}
 function derivedItemChange(kind, path, base, extend = {}) {
 	return {
 		kind,

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 = 20261016201727;
+declare const CURRENT_SCHEMA_VERSION = 20261019165323;
 /** 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 = 20261016201727;
+const CURRENT_SCHEMA_VERSION = 20261019165323;
 /** 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 > 20261016201727) 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 > 20261019165323) 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 ?? 20261016201727;
+	const target = options?.target ?? 20261019165323;
 	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 ?? 20261016201727;
+	const target = options?.target ?? 20261019165323;
 	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 ?? 20261016201727;
+	const target = options?.target ?? 20261019165323;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/source-integrity.d.ts

@@ -117,6 +117,9 @@ interface MisdeclaredOverlay {
   declared: 'override' | 'extend';
   /** The field it was wrong about, addressed from the entity body as segments. */
   field: readonly string[];
+  /** For an `extend` of a list, the entries the list it lays onto already holds. The entries are what
+   *  the extension is judged on, so a list the source defines is not wrong to extend. */
+  entries?: readonly unknown[];
 }
 /**
  * A leaf address: dotted, or spelled as segments where a member key can itself contain a dot (a
@@ -136,6 +139,9 @@ type OverlayVerb = 'override' | 'extend';
  * nothing local sits there or the two agree. A leaf carried along unchanged is not overlaid: a sub-op
  * copies the whole record it touched into the delta, so a token given one local condition holds the
  * source's other conditions beside it.
+ *
+ * A list is the one leaf with members. One that keeps all of theirs and adds to it is an `extend`,
+ * since that is what an `extend` of the added entries reads back as.
  */
 declare function leafVerb({
   ours,
@@ -162,6 +168,10 @@ declare function overlayVerb(overlay: LocalOverlay, field: LeafAddress): Overlay
  * Judged leaf by leaf, because one entity legitimately carries both — a token overridden under one
  * modifier and extended under another is one body with two verbs, and a whole-entity comparison would
  * have to call it one or the other.
+ *
+ * A list is judged by its entries: an `extend` of one the source defines adds to it, and is wrong only
+ * in the entries the list beneath already holds. That is the same moving source one level down — they
+ * added a value this config was extending with.
  */
 declare function misdeclaredOverlays(config: Config): MisdeclaredOverlay[];
 /**

package/dist/framework/source-integrity.js

@@ -243,17 +243,50 @@ function valueAt(body, field) {
 function isRuleCondition(address) {
 	return address.length >= 3 && address[0] === "styles" && address[2] === "when";
 }
+/** A list entry's identity. Entries are refs and small literals, so it is what they serialize to
+*  rather than reference equality. */
+const entryKey = (entry) => JSON.stringify(entry);
+/**
+* A union that keeps the existing order and drops a repeat — what an `extend` of a list lays onto the
+* list beneath it.
+*/
+function uniteEntries(existing, added) {
+	const out = Array.isArray(existing) ? [...existing] : [];
+	const seen = new Set(out.map(entryKey));
+	for (const entry of added) {
+		const key = entryKey(entry);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(entry);
+	}
+	return out;
+}
+/**
+* The entries `ours` adds to `theirs`, where uniting them onto `theirs` gives back `ours` exactly —
+* their list whole and in order, with ours after it. `undefined` where it doesn't: a list that drops
+* or reorders one of theirs replaces it, and so does anything that isn't a list on both sides.
+*/
+function addedEntries(ours, theirs) {
+	if (!Array.isArray(ours) || !Array.isArray(theirs)) return void 0;
+	const listed = new Set(theirs.map(entryKey));
+	const added = ours.filter((entry) => !listed.has(entryKey(entry)));
+	return sameValue(uniteEntries(theirs, added), ours) ? added : void 0;
+}
 /**
 * The verb one local leaf is against the source's value at the same address: `extend` where the
 * source has nothing there, `override` where it has something different, and `undefined` where
 * nothing local sits there or the two agree. A leaf carried along unchanged is not overlaid: a sub-op
 * copies the whole record it touched into the delta, so a token given one local condition holds the
 * source's other conditions beside it.
+*
+* A list is the one leaf with members. One that keeps all of theirs and adds to it is an `extend`,
+* since that is what an `extend` of the added entries reads back as.
 */
 function leafVerb({ ours, theirs }) {
 	if (ours === void 0) return void 0;
 	if (theirs === void 0) return "extend";
-	return sameValue(ours, theirs) ? void 0 : "override";
+	if (sameValue(ours, theirs)) return void 0;
+	return addedEntries(ours, theirs)?.length ? "extend" : "override";
 }
 /**
 * Which verb this config's value at `field` is, in the pin's vocabulary — `override` where the source
@@ -286,6 +319,10 @@ function sameValue(a, b) {
 * Judged leaf by leaf, because one entity legitimately carries both — a token overridden under one
 * modifier and extended under another is one body with two verbs, and a whole-entity comparison would
 * have to call it one or the other.
+*
+* A list is judged by its entries: an `extend` of one the source defines adds to it, and is wrong only
+* in the entries the list beneath already holds. That is the same moving source one level down — they
+* added a value this config was extending with.
 */
 function misdeclaredOverlays(config) {
 	const found = [];
@@ -299,7 +336,29 @@ function misdeclaredOverlays(config) {
 			const theirs = source.resolve(kind, path)?.toJSON();
 			for (const field of leafAddresses(overlay.extend)) {
 				if (isRuleCondition(field)) continue;
-				if (valueAt(theirs, field) !== void 0) found.push({
+				const defined = valueAt(theirs, field);
+				if (defined === void 0) continue;
+				const added = valueAt(overlay.extend, field);
+				if (Array.isArray(added) && Array.isArray(defined)) {
+					const replaced = valueAt(overlay.override, field);
+					const beneath = Array.isArray(replaced) ? replaced : valueAt(config.copyOf({
+						slug,
+						kind,
+						path
+					}), field);
+					const listed = new Set((Array.isArray(beneath) ? beneath : defined).map(entryKey));
+					const entries = added.filter((entry) => listed.has(entryKey(entry)));
+					if (entries.length > 0) found.push({
+						slug,
+						kind,
+						path,
+						declared: "extend",
+						field,
+						entries
+					});
+					continue;
+				}
+				found.push({
 					slug,
 					kind,
 					path,
@@ -336,12 +395,16 @@ function classifyOverlay(local, theirs) {
 	for (const [address, value] of leafEntries(local)) {
 		if (address.length === 0) continue;
 		if (isRuleCondition(address)) continue;
+		const defined = valueAt(theirs, address);
 		const verb = leafVerb({
 			ours: value,
-			theirs: valueAt(theirs, address)
+			theirs: defined
 		});
 		if (verb === "override") override = setAtPath(override, address, value);
-		else if (verb === "extend") extend = setAtPath(extend, address, value);
+		else if (verb === "extend") {
+			const added = addedEntries(value, defined) ?? value;
+			extend = setAtPath(extend, address, added);
+		}
 	}
 	const rules = local.styles;
 	if (isWalkable(rules)) for (const [key, rule] of Object.entries(rules)) {
@@ -594,4 +657,4 @@ function borrowedSlug(body) {
 	return isRef(body) ? sourceOf(body) : void 0;
 }
 //#endregion
-export { borrowedSlug, classifyOverlay, danglingDirectives, danglingSourcedRefs, excludedCondition, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, sourceSlugs, unadoptedDirectives, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };
+export { borrowedSlug, classifyOverlay, danglingDirectives, danglingSourcedRefs, excludedCondition, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, sourceSlugs, unadoptedDirectives, uniteEntries, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };