@yahoo/uds-create-config 5.20.0 → 5.21.0

package/dist/configs/system.js

@@ -64,6 +64,7 @@ import { buildReactMigration } from "../migrations/20261008181849_build_react.js
 import { cssMotionStatesMigration } from "../migrations/20261009000514_css_motion_states.js";
 import { startingStyleModifierMigration } from "../migrations/20261009022722_starting_style_modifier.js";
 import { cssMotionStrictMigration } from "../migrations/20261009181635_css_motion_strict.js";
+import { linkOverrideRefMigration } from "../migrations/20261009193004_link_override_ref.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.",
@@ -139,5 +140,6 @@ if (!registeredSchemaMigrations().has(20261008181849)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261009000514)) registerSchemaMigrations(cssMotionStatesMigration);
 if (!registeredSchemaMigrations().has(20261009022722)) registerSchemaMigrations(startingStyleModifierMigration);
 if (!registeredSchemaMigrations().has(20261009181635)) registerSchemaMigrations(cssMotionStrictMigration);
+if (!registeredSchemaMigrations().has(20261009193004)) registerSchemaMigrations(linkOverrideRefMigration);
 //#endregion
 export { System };

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

@@ -249,7 +249,7 @@ type PinOptionsInput<K extends string = string> = { [A in keyof RegisteredEntiti
 /** A motion entry: an adjustment whose `runtime` is one the linked preset can be read as
  *  ({@link RegisteredMotionRuntimes}), so a swap the conversion would refuse doesn't type. */
 type PinMotionAdjustment<E, P extends string> = {
-  override?: PinMotionBody<E, P>;
+  override?: PinMotionBody<E, P> | KindRefOf<E>;
   extend?: PinMotionBody<E, P>;
   hidden?: boolean;
 };
@@ -259,8 +259,14 @@ type PinMotionBody<E, P extends string> = Extract<StoredBodyOf<PartialBodyOf<E>>
 /** The linked presets registered at `path`, from whichever source. */
 type LinkedMotionKey<P extends string> = Extract<keyof RegisteredMotionRuntimes, `${P}@${string}`>;
 type MotionRuntimeOf<P extends string> = [LinkedMotionKey<P>] extends [never] ? 'css' | 'js' : RegisteredMotionRuntimes[LinkedMotionKey<P>];
+/** A ref to another entity of `E`'s kind, which re-points the path to it. */
+type KindRefOf<E> = E extends {
+  readonly kind: infer K extends string;
+} ? {
+  readonly __ref: `${K}:${string}`;
+} : never;
 type PinComponentAdjustment<E, P extends string> = {
-  override?: PinComponentBody<E, P>;
+  override?: PinComponentBody<E, P> | KindRefOf<E>;
   extend?: PinComponentBody<E, P>;
   hidden?: boolean;
 };
@@ -280,7 +286,7 @@ type LinkDeclaration = '*' | Record<string, '*' | readonly string[]>;
 /** One `options` entry, checked against the kind its accessor addresses. The runtime floor — that an
  *  entry names at least one of the three — is the schema's `refine`, which reports the path. */
 type PinAdjustment<E> = {
-  override?: StoredBodyOf<PartialBodyOf<E>>;
+  override?: StoredBodyOf<PartialBodyOf<E>> | KindRefOf<E>;
   extend?: StoredBodyOf<PartialBodyOf<E>>;
   hidden?: boolean;
 };
@@ -296,6 +302,7 @@ type StoredBodyOf<Body> = 'styles' extends keyof Body ? Omit<Body, 'styles'> & {
  * the same entry, with nothing to check the bodies against yet.
  */
 interface PinDirective {
+  /** A body, or a ref that re-points the path to another entity of the same kind. */
   readonly override?: Record<string, unknown>;
   readonly extend?: Record<string, unknown>;
   readonly hidden?: boolean;
@@ -428,5 +435,23 @@ declare function suggestLinkSlug({
   name: string;
   taken: ReadonlySet<string>;
 }): string;
+/**
+ * A link's `options` entry whose `override` is a ref: the path it names reads as that entity
+ * (`'js/scale': { override: Motion.ref('css/scale') }`). `problem` says why it can't: the ref names
+ * another kind, it leads back to this path through other re-pointed paths, or, once the link's
+ * source is attached, it names nothing.
+ */
+interface LinkRedirect {
+  /** The link's slug. */
+  readonly link: string;
+  readonly accessor: string;
+  readonly path: string;
+  readonly target: string;
+  readonly problem?: 'kind' | 'cycle' | 'missing';
+}
+/** Every re-pointed path the config's links declare, with what stops each one, if anything. */
+declare function linkRedirects(config: Config): LinkRedirect[];
+/** One sentence for a re-pointed path that can't be read. */
+declare function redirectSentence(redirect: LinkRedirect): string;
 //#endregion
-export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkedSystem, LinkedSystemClass, LinkedSystemCreateInput, LinkedSystemItemInput, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, PinOptionsInput, ResolvedSource, Source, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkRedirect, LinkedSystem, LinkedSystemClass, LinkedSystemCreateInput, LinkedSystemItemInput, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, PinOptionsInput, ResolvedSource, Source, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

package/dist/entities/system/LinkedSystem.js

@@ -1,5 +1,5 @@
 import { rejectData } from "../../framework/rejection.js";
-import { isRef } from "../../framework/utils/refs.js";
+import { isRef, kindOf, pathOf, refSchema } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
 import { pathInput } from "../../framework/schemas.js";
 import { kindBorrowable } from "../../framework/registry.js";
@@ -262,7 +262,7 @@ function exampleBorrowable(config, slug) {
 	}
 }
 const pinOptions = z.record(z.string(), z.record(z.string(), z.strictObject({
-	override: z.record(z.string(), z.unknown()).optional(),
+	override: z.union([refSchema, z.record(z.string(), z.unknown())]).optional(),
 	extend: z.record(z.string(), z.unknown()).optional(),
 	hidden: z.boolean().optional()
 }).refine((entry) => entry.override !== void 0 || entry.extend !== void 0 || entry.hidden !== void 0, { message: "An `options` entry needs `override`, `extend` or `hidden`." }))).optional().describe("Per-entity adjustments, keyed by accessor, then path, then verb.");
@@ -270,7 +270,7 @@ const LinkedSystemDefinition = defineEntity({
 	kind: "linked-system",
 	label: "Linked system",
 	labelPlural: "Linked systems",
-	invariants: (config) => config.list("linked-system").filter(({ path }) => !isLinkSlug(path)).map(({ path }) => `Link "${path}": ${LINK_SLUG_MESSAGE}`),
+	invariants: (config) => [...config.list("linked-system").filter(({ path }) => !isLinkSlug(path)).map(({ path }) => `Link "${path}": ${LINK_SLUG_MESSAGE}`), ...linkRedirects(config).filter((redirect) => redirect.problem !== void 0 && redirect.problem !== "missing").map(redirectSentence)],
 	schemas: {
 		create: { example: ({ config }) => {
 			const path = freeExampleSlug(config);
@@ -892,5 +892,56 @@ function suggestLinkSlug({ name, taken }) {
 		if (!taken.has(candidate)) return candidate;
 	}
 }
+/** Every re-pointed path the config's links declare, with what stops each one, if anything. */
+function linkRedirects(config) {
+	const kindOfAccessor = (accessor) => config.accessors()[accessor]?.kind ?? accessor;
+	const declared = [];
+	for (const link of config.list("linked-system")) {
+		const { options } = link.toJSON();
+		for (const [accessor, entries] of Object.entries(options ?? {})) for (const [path, entry] of Object.entries(entries ?? {})) {
+			const override = isPlainObject(entry) ? entry.override : void 0;
+			if (!isRef(override)) continue;
+			declared.push({
+				link: link.path,
+				accessor,
+				path,
+				target: override.__ref
+			});
+		}
+	}
+	const next = /* @__PURE__ */ new Map();
+	for (const { accessor, path, target } of declared) next.set(`${kindOfAccessor(accessor)}:${path}`, `${kindOf(target)}:${pathOf(target)}`);
+	const loops = (start) => {
+		const seen = /* @__PURE__ */ new Set();
+		for (let at = start; at !== void 0; at = next.get(at)) {
+			if (seen.has(at)) return at === start;
+			seen.add(at);
+		}
+		return false;
+	};
+	return declared.map((redirect) => {
+		const kind = kindOfAccessor(redirect.accessor);
+		if (kindOf(redirect.target) !== kind) return {
+			...redirect,
+			problem: "kind"
+		};
+		if (loops(`${kind}:${redirect.path}`)) return {
+			...redirect,
+			problem: "cycle"
+		};
+		if (config.sourceFor(redirect.link) && !config.resolveRef(redirect.target)) return {
+			...redirect,
+			problem: "missing"
+		};
+		return redirect;
+	});
+}
+/** One sentence for a re-pointed path that can't be read. */
+function redirectSentence(redirect) {
+	const at = `Link "${redirect.link}": options.${redirect.accessor}["${redirect.path}"] re-points to ${redirect.target}`;
+	if (redirect.problem === "kind") return `${at}, which is no ${redirect.accessor} entry. A path can only read as another entity of its own kind.`;
+	if (redirect.problem === "cycle") return `${at}, which leads back to it through other re-pointed paths.`;
+	return `${at}, which names nothing this config can read.`;
+}
 //#endregion
-export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

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 = 20261009181635;
+declare const SERIALIZED_CONFIG_VERSION = 20261009193004;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -1328,6 +1328,31 @@ declare class Config {
    * only as a borrow the picker offered and the read then refused.
    */
   private extensionBody;
+  /**
+   * A source's body with a linked extension's `extend` laid over it, the one merge every read and
+   * write of a borrowed row goes through. An `extend` whose `__ref` names another entity of the kind
+   * (a link's `override: Motion.ref('css/scale')`) re-points the path: it reads as that entity, as
+   * this config resolves it, with the rest of the `extend` over it. The kind's
+   * {@link EntityKind.rebaseLinkedBody} then adapts the base before the merge.
+   *
+   * A target that resolves to nothing, names another kind, or leads back to this path through other
+   * re-pointed paths leaves an empty body, which the kind's schema refuses, so the row reads as
+   * nothing. The pin's invariants refuse the last two when they're written, and the build reports a
+   * missing target (`brokenLinkRedirects`).
+   */
+  laidLinkedBody({
+    kind,
+    path,
+    body,
+    extend
+  }: {
+    kind: string;
+    path: string;
+    body: Record<string, unknown>;
+    extend: Record<string, unknown>;
+  }): Record<string, unknown>;
+  /** The body of the entity a re-pointed path names, or `undefined` when there is none to read. */
+  private redirectedBody;
   /**
    * Resolve one locally extended linked item: the pinned source body, shallowly overlaid by the fields
    * authored here, then parsed through this config's kind. Parsing on this side is what lets a React

package/dist/framework/Config.js

@@ -1800,7 +1800,12 @@ var Config = class Config {
 					kind: patch.kind,
 					path: pathOf(extension)
 				}) : void 0;
-				const inherited = current ? extendBody(current.source, current.overlay) : resolved.toJSON();
+				const inherited = current ? this.at(snapshot).laidLinkedBody({
+					kind: patch.kind,
+					path: pathOf(extension),
+					body: current.source,
+					extend: current.overlay
+				}) : resolved.toJSON();
 				const materialized = snapshot.withChanges([itemChange(entry, patch.kind, patch.path, inherited)]);
 				const changed = this.applySub(materialized, patch, materialized.get(patch.kind, patch.path) ?? resolved, mode);
 				const body = changed.get(patch.kind, patch.path)?.toJSON();
@@ -1884,24 +1889,24 @@ var Config = class Config {
 				kind: patch.kind,
 				path: pathOf(extension)
 			}) : void 0;
-			const written = applyPathDelta(current ? extendBody(rebasedLinkedBody({
-				entry,
+			const written = applyPathDelta(current ? this.at(snapshot).laidLinkedBody({
+				kind: patch.kind,
 				path: pathOf(extension),
 				body: current.source,
 				extend: current.overlay
-			}), current.overlay) : resolved.toJSON(), delta, isField);
+			}) : resolved.toJSON(), delta, isField);
 			const local = { ...current ? current.overlay : extension.extend };
 			for (const field of touched) if (Object.hasOwn(delta, field) && delta[field] === null) delete local[field];
 			else if (Object.hasOwn(written, field)) local[field] = written[field];
 			else delete local[field];
 			const sourceBody = this.configFor(extension)?.resolve(patch.kind, pathOf(extension))?.toJSON();
 			if (!sourceBody) reject("NOT_FOUND", `Cannot edit ${patch.kind} "${patch.path}" — its source "${extension.__ref}" is unavailable`);
-			const candidate = extendBody(rebasedLinkedBody({
-				entry,
+			const candidate = this.at(snapshot).laidLinkedBody({
+				kind: patch.kind,
 				path: pathOf(extension),
 				body: sourceBody,
 				extend: local
-			}), local);
+			});
 			const createSchema = wholeBodySchema(entry, { config: this });
 			let merged = candidate;
 			if (createSchema) {
@@ -1920,8 +1925,12 @@ var Config = class Config {
 				if (!sourceKind || !write) reject("UNSUPPORTED", `Cannot edit ${patch.kind} "${patch.path}" — "${slug}" has no way to record the change`);
 				const accessor = view.accessorOf(patch.kind) ?? patch.kind;
 				const existing = view.sourceOverlay(slug, patch.kind, patch.path);
+				const { target: redirect, rest } = redirectOf(local);
 				const overlay = {
-					...classifyOverlay(local, sourceBody),
+					...redirect === void 0 ? classifyOverlay(local, sourceBody) : {
+						override: { __ref: redirect },
+						...Object.keys(rest).length > 0 ? { extend: rest } : {}
+					},
 					...existing?.hidden ? { hidden: true } : {}
 				};
 				const data = view.directiveWrite({
@@ -2642,13 +2651,12 @@ var Config = class Config {
 			owns,
 			namesItAlready: (target) => this.borrowsExactly(target, slug)
 		}) : base.toJSON();
-		const extend = extension.extend ?? {};
-		const merged = extendBody(rebasedLinkedBody({
-			entry: this.entityOf(kind),
+		const merged = this.laidLinkedBody({
+			kind,
 			path: pathOf(extension),
 			body: inherited,
-			extend
-		}), extend);
+			extend: extension.extend ?? {}
+		});
 		return this.entityOf(kind)?.prepareLinkedBody?.({
 			path: pathOf(extension),
 			body: merged,
@@ -2657,6 +2665,46 @@ var Config = class Config {
 		}) ?? merged;
 	}
 	/**
+	* A source's body with a linked extension's `extend` laid over it, the one merge every read and
+	* write of a borrowed row goes through. An `extend` whose `__ref` names another entity of the kind
+	* (a link's `override: Motion.ref('css/scale')`) re-points the path: it reads as that entity, as
+	* this config resolves it, with the rest of the `extend` over it. The kind's
+	* {@link EntityKind.rebaseLinkedBody} then adapts the base before the merge.
+	*
+	* A target that resolves to nothing, names another kind, or leads back to this path through other
+	* re-pointed paths leaves an empty body, which the kind's schema refuses, so the row reads as
+	* nothing. The pin's invariants refuse the last two when they're written, and the build reports a
+	* missing target (`brokenLinkRedirects`).
+	*/
+	laidLinkedBody({ kind, path, body, extend }) {
+		const { target, rest } = redirectOf(extend);
+		const base = target === void 0 ? body : this.redirectedBody({
+			kind,
+			path,
+			target
+		}) ?? {};
+		return extendBody(rebasedLinkedBody({
+			entry: this.entityOf(kind),
+			path,
+			body: base,
+			extend: rest
+		}), rest);
+	}
+	/** The body of the entity a re-pointed path names, or `undefined` when there is none to read. */
+	redirectedBody({ kind, path, target }) {
+		if (kindOf(target) !== kind) return void 0;
+		const reading = redirecting.get(this.state) ?? /* @__PURE__ */ new Set();
+		const key = `${kind}:${path}`;
+		if (reading.has(key)) return void 0;
+		reading.add(key);
+		redirecting.set(this.state, reading);
+		try {
+			return this.resolveRef(target)?.toJSON();
+		} finally {
+			reading.delete(key);
+		}
+	}
+	/**
 	* Resolve one locally extended linked item: the pinned source body, shallowly overlaid by the fields
 	* authored here, then parsed through this config's kind. Parsing on this side is what lets a React
 	* Native kind transform or reject a web value rather than trusting the source kind's rules.
@@ -3552,6 +3600,12 @@ var Config = class Config {
 			},
 			theirs
 		});
+		if (laid && redirectOf(laid).target !== void 0) return this.laidLinkedBody({
+			kind,
+			path,
+			body: theirs,
+			extend: laid
+		});
 		return laid ? {
 			...theirs,
 			...laid
@@ -5458,7 +5512,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 > 20261009181635) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261009193004) 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;
@@ -5623,6 +5677,20 @@ function extendBody(base, delta) {
 * differently, and why the source's body is a parameter. `extend: { values: [Token.ref('surface')] }`
 * means "alongside what they already accept", which has nothing to join without their list.
 */
+/** The paths each config is reading through a re-pointed link, for {@link Config.laidLinkedBody} to
+*  find a loop by. Keyed on the config's state, which every read of one config shares. */
+const redirecting = /* @__PURE__ */ new WeakMap();
+/**
+* The entity an `extend` re-points its path to, and the rest of it: a link's `override` written as a
+* ref lands in the stored `extend` as its `__ref`, beside whatever the `extend` verb adds.
+*/
+function redirectOf(extend) {
+	const { __ref: target, ...rest } = extend;
+	return typeof target === "string" ? {
+		target,
+		rest
+	} : { rest: extend };
+}
 /** A source's body as an extension reads it before its `extend` merges in: the kind's
 *  {@link EntityKind.rebaseLinkedBody}, where it declares one. */
 function rebasedLinkedBody({ entry, path, body, extend }) {

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

package/dist/migrations/20261009193004_link_override_ref.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A link's `options` entry may give `override` as a ref to another entity of the same kind, which
+ * re-points the path to it (`'js/scale': { override: Motion.ref('css/scale') }`). Every stored
+ * `override` is a body, so the wire shape of every stored config is unchanged. Additive, so the
+ * envelope passes through as it is.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const LINK_OVERRIDE_REF_VERSION = 20261009193004;
+export declare const linkOverrideRefMigration: SchemaMigration;

package/dist/migrations/20261009193004_link_override_ref.js

@@ -0,0 +1,10 @@
+//#region src/migrations/20261009193004_link_override_ref.ts
+const LINK_OVERRIDE_REF_VERSION = 20261009193004;
+const linkOverrideRefMigration = {
+	version: LINK_OVERRIDE_REF_VERSION,
+	up(json) {
+		return json;
+	}
+};
+//#endregion
+export { LINK_OVERRIDE_REF_VERSION, linkOverrideRefMigration };

package/dist/spec/links.d.ts

@@ -0,0 +1,2 @@
+import { LinkRedirect, linkRedirects, redirectSentence } from "../entities/system/LinkedSystem.js";
+export { type LinkRedirect, linkRedirects, redirectSentence };

package/dist/spec/links.js

@@ -0,0 +1,2 @@
+import { linkRedirects, redirectSentence } from "../entities/system/LinkedSystem.js";
+export { linkRedirects, redirectSentence };