@yahoo/uds-create-config 5.73.2 → 5.75.0

package/dist/configs/CanvasConfig.d.ts

@@ -312,7 +312,7 @@ declare const CanvasConfigDefinition: ConfigClass<{
   tools: ToolClass;
 }, {
   systems: () => typeof System | typeof ReactNativeSystem;
-}>;
+}, Record<never, never>>;
 interface CanvasConfigClass extends Named<typeof CanvasConfigDefinition> {}
 declare const CanvasConfig: CanvasConfigClass;
 /**
@@ -333,6 +333,6 @@ declare function createCanvasConfig(system: AnySystemConfig): ConfigInstance<{
 }, {
   operations: OperationClass;
   tools: ToolClass;
-}>;
+}, Record<never, never>>;
 //#endregion
 export { AiChat, AiChatClass, AiFlow, AiFlowClass, AiFlowOrigin, AiGeneration, AiGenerationClass, AiMessage, AiMessageClass, AiMultiAgentMode, Annotation, AnnotationClass, AnnotationFields, AnnotationSegment, Canvas, CanvasClass, CanvasConfig, CanvasConfigClass, Node, NodeClass, Page, PageClass, SystemSource, SystemSourceClass, createCanvasConfig };

package/dist/configs/documentation.d.ts

@@ -9,7 +9,7 @@ declare const DocumentationLibraryDefinition: ConfigClass<{
 }, {
   operations: OperationClass;
   tools: ToolClass;
-}, Record<never, never>>;
+}, Record<never, never>, Record<never, never>>;
 interface DocumentationLibraryClass extends Named<typeof DocumentationLibraryDefinition> {}
 declare const DocumentationLibrary: DocumentationLibraryClass;
 //#endregion

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

@@ -12,7 +12,7 @@ import { CompositeClass } from "../entities/system/Composite.js";
 import { OverrideCondition } from "../entities/system/Token.js";
 import { StylePropValue } from "../entities/system/StyleProperty.js";
 import { ComponentClass } from "../entities/system/Component.js";
-import { LinkedSystemClass } from "../entities/system/LinkedSystem.js";
+import { SourceClass } from "../entities/system/LinkedSystem.js";
 import { IconClass } from "../entities/system/Icon.js";
 import { NativeModifierClass } from "../entities/native/NativeModifier.js";
 import { CanvasRoleClass } from "../entities/system/CanvasRole.js";
@@ -408,12 +408,14 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
   guidance: GuidanceClass;
   canvasRoles: CanvasRoleClass;
   devices: DeviceClass;
-  linkedSystems: LinkedSystemClass;
+  sources: SourceClass;
 }, {
   operations: OperationClass;
   tools: ToolClass;
 }, {
-  linkedSystems: () => ReactNativeSystemClass;
+  sources: () => ReactNativeSystemClass;
+}, {
+  /** @deprecated Use `sources`. */readonly linkedSystems: "sources";
 }>;
 interface ReactNativeSystemClass extends Named<typeof ReactNativeSystemDefinition> {}
 declare const ReactNativeSystem: ReactNativeSystemClass;

package/dist/configs/react-native-system.js

@@ -18,7 +18,7 @@ import { motionJsonSchemaMigration } from "../migrations/20261015221052_motion_j
 import { motionTypeOnlyMigration } from "../migrations/20261016135620_motion_type_only.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { Guidance } from "../entities/system/Guidance.js";
-import { LinkedSystem } from "../entities/system/LinkedSystem.js";
+import { Source } from "../entities/system/LinkedSystem.js";
 import { settingsAsKindMigration } from "../migrations/20260908171448_settings_as_kind.js";
 import { visibleStatePointerMigration } from "../migrations/20260908194245_visible_state_pointer.js";
 import { iconKnockoutVariantsMigration } from "../migrations/20260909183001_icon_knockout_variants.js";
@@ -50,9 +50,12 @@ const ReactNativeSystem = defineConfig({
 		guidance: Guidance,
 		canvasRoles: CanvasRole,
 		devices: Device,
-		linkedSystems: LinkedSystem
+		sources: Source
 	},
-	sources: { linkedSystems: () => ReactNativeSystem },
+	sources: { sources: () => ReactNativeSystem },
+	deprecatedAccessors: { 
+	/** @deprecated Use `sources`. */
+linkedSystems: "sources" },
 	derivedEntities: {
 		operations: Operation,
 		tools: Tool

package/dist/configs/system.d.ts

@@ -6,7 +6,7 @@ import { ModifierClass } from "../entities/system/Modifier.js";
 import { TokenClass } from "../entities/system/Token.js";
 import { StylePropertyClass } from "../entities/system/StyleProperty.js";
 import { ComponentClass } from "../entities/system/Component.js";
-import { LinkedSystemClass } from "../entities/system/LinkedSystem.js";
+import { SourceClass } from "../entities/system/LinkedSystem.js";
 import { IconClass } from "../entities/system/Icon.js";
 import { CanvasRoleClass } from "../entities/system/CanvasRole.js";
 import { DeviceClass } from "../entities/system/Device.js";
@@ -37,12 +37,14 @@ declare const SystemDefinition: ConfigClass<{
   canvasRoles: CanvasRoleClass;
   globalStyles: GlobalStyleClass;
   devices: DeviceClass;
-  linkedSystems: LinkedSystemClass;
+  sources: SourceClass;
 }, {
   operations: OperationClass;
   tools: ToolClass;
 }, {
-  linkedSystems: () => SystemClass;
+  sources: () => SystemClass;
+}, {
+  /** @deprecated Use `sources`. */readonly linkedSystems: "sources";
 }>;
 interface SystemClass extends Named<typeof SystemDefinition> {}
 declare const System: SystemClass;

package/dist/configs/system.js

@@ -38,11 +38,12 @@ import { layerPrefixMigration } from "../migrations/20261030163028_layer_prefix.
 import { defaultColorsMigration } from "../migrations/20261102143821_default_colors.js";
 import { linkReplaceMigration } from "../migrations/20261102185610_link_replace.js";
 import { mapPropsFromMigration } from "../migrations/20261102193912_map_props_from.js";
+import { sourcesAuthoringMigration } from "../migrations/20261103115059_sources_authoring.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
 import { GuidanceStyle } from "../entities/system/GuidanceStyle.js";
-import { LinkedSystem } from "../entities/system/LinkedSystem.js";
+import { Source } from "../entities/system/LinkedSystem.js";
 import { loadV1Artifact } from "../migrations/2.0.0/v1-artifact.js";
 import { settingsAsKindMigration } from "../migrations/20260908171448_settings_as_kind.js";
 import { visibleStatePointerMigration } from "../migrations/20260908194245_visible_state_pointer.js";
@@ -118,9 +119,12 @@ const System = defineConfig({
 		canvasRoles: CanvasRole,
 		globalStyles: GlobalStyle,
 		devices: Device,
-		linkedSystems: LinkedSystem
+		sources: Source
 	},
-	sources: { linkedSystems: () => System },
+	sources: { sources: () => System },
+	deprecatedAccessors: { 
+	/** @deprecated Use `sources`. */
+linkedSystems: "sources" },
 	derivedEntities: {
 		operations: Operation,
 		tools: Tool
@@ -209,5 +213,6 @@ if (!registeredSchemaMigrations().has(20261030163028)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261102143821)) registerSchemaMigrations(defaultColorsMigration);
 if (!registeredSchemaMigrations().has(20261102185610)) registerSchemaMigrations(linkReplaceMigration);
 if (!registeredSchemaMigrations().has(20261102193912)) registerSchemaMigrations(mapPropsFromMigration);
+if (!registeredSchemaMigrations().has(20261103115059)) registerSchemaMigrations(sourcesAuthoringMigration);
 //#endregion
 export { System };

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

@@ -212,19 +212,46 @@ declare const LinkedSystemDefinition: EntityClass<z.ZodObject<{
     path
   }: ComputedInput) => string;
 }, false, Record<never, never>, Record<never, never>>;
-/** A pin body as `register` takes one. */
-type LinkedSystemCreateInput = Exclude<ReturnType<typeof LinkedSystemDefinition.item>, string | number | Ref>;
-/** `LinkedSystem.item`'s body: the stored fields, with `options` as {@link PinOptionsInput} takes it. */
-type LinkedSystemItemInput<K extends string = string> = Omit<LinkedSystemCreateInput, 'options'> & {
-  readonly options?: PinOptionsInput<K>;
+/** A source body as `register` takes one. */
+type SourceCreateInput = Exclude<ReturnType<typeof LinkedSystemDefinition.item>, string | number | Ref>;
+/** @deprecated Use {@link SourceCreateInput}. */
+type LinkedSystemCreateInput = SourceCreateInput;
+/**
+ * `Source.item`'s body: the stored fields, with `options` as {@link PinOptionsInput} takes it, plus
+ * `options.include`, which is what the source brings in and is stored as `link`.
+ */
+type SourceItemInput<K extends string = string> = Omit<SourceCreateInput, 'options' | 'link'> & {
+  /** @deprecated Use `options.include`. */readonly link?: LinkDeclaration;
+  readonly options?: SourceOptionsInput<K>;
 };
-interface LinkedSystemClass extends Omit<Named<typeof LinkedSystemDefinition>, 'item'> {
-  /** One pin. A component entry's `override` and `extend` take their `styles` as the stored record or
-   *  the rule list `defineComponent.styles` takes, and a list is stored as the record. */
-  item<const K extends string = string>(def: LinkedSystemItemInput<K>): LinkedSystemCreateInput;
-  item(def: LinkedSystemCreateInput | string | number | Ref): LinkedSystemCreateInput | string | number | Ref;
+/**
+ * What a source includes, beside {@link PinOptionsInput}'s directives. Where no accessors are
+ * registered the directives are an open record, as {@link PinOptionsInput} leaves them.
+ */
+type SourceOptionsInput<K extends string> = ([keyof RegisteredEntities] extends [never] ? Record<string, unknown> : PinOptionsInput<K>) & {
+  /**
+   * What this system draws from the source, standing: `'*'` for everything, or a record by accessor
+   * (`'*'` keys every accessor it doesn't name). A list's `'!path'` entry leaves that path out.
+   */
+  readonly include?: LinkDeclaration;
+};
+/** @deprecated Use {@link SourceItemInput}. */
+type LinkedSystemItemInput<K extends string = string> = SourceItemInput<K>;
+interface SourceClass extends Omit<Named<typeof LinkedSystemDefinition>, 'item'> {
+  /** One source. A component entry's `override` and `extend` take their `styles` as the stored record
+   *  or the rule list `defineComponent.styles` takes, and a list is stored as the record. */
+  item<const K extends string = string>(def: SourceItemInput<K>): SourceCreateInput;
+  item(def: SourceCreateInput | string | number | Ref): SourceCreateInput | string | number | Ref;
 }
-declare const LinkedSystem: LinkedSystemClass;
+/** @deprecated Use {@link SourceClass}. */
+type LinkedSystemClass = SourceClass;
+/**
+ * `Source` (`yahoo-os`): another team's design system, drawn from at an exact version. Registered
+ * under `sources`.
+ */
+declare const Source: SourceClass;
+/** @deprecated Use {@link Source}, registered under `sources`. */
+declare const LinkedSystem: SourceClass;
 /**
  * What a pin's `options` may say, checked against the config type it is declared in — one record per
  * accessor, keyed by the path the source spells, valued by what this config does to it.
@@ -332,7 +359,7 @@ interface PinDirective {
   readonly hidden?: boolean;
 }
 /** One declared source, typed off this kind's own schema — what the readers below hand back. */
-type Source = ItemOf<typeof LinkedSystem>;
+type Source = ItemOf<typeof Source>;
 /**
  * A linked system's state as `Config.sourceStates()` reports it, narrowed to this kind's vocabulary.
  *
@@ -478,4 +505,4 @@ 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, 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 };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkRedirect, LinkedSystem, LinkedSystemClass, LinkedSystemCreateInput, LinkedSystemItemInput, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, PinOptionsInput, ResolvedSource, Source, SourceClass, SourceCreateInput, SourceItemInput, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

package/dist/entities/system/LinkedSystem.js

@@ -5,6 +5,7 @@ import { pathInput } from "../../framework/schemas.js";
 import { kindBorrowable } from "../../framework/registry.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { storedStyleRules } from "./Component.js";
+import { storedFromAuthored } from "../../framework/authored-at.js";
 import { sourceUnreachable } from "../../framework/sources.js";
 import { covers, excludes } from "./link-declaration.js";
 import { planCopy } from "./copy-plan.js";
@@ -290,10 +291,19 @@ const pinOptions = z.record(z.string(), z.record(z.string(), z.strictObject({
 	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.");
+/**
+* Where a source's stored fields are authored. What a source includes is authored as
+* `options.include`, beside the directives, and stored as `link`; `link` is still taken in a body.
+* `include` sits among `options`' accessor keys, and no config type registers an accessor called
+* `include`.
+*/
+const SOURCE_AUTHORED_AT = { link: "options.include" };
 const LinkedSystemDefinition = defineEntity({
 	kind: "linked-system",
 	label: "Linked system",
 	labelPlural: "Linked systems",
+	entityName: "Source",
+	authoredAt: SOURCE_AUTHORED_AT,
 	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),
@@ -897,15 +907,25 @@ function storedPinOptions(options) {
 	}
 	return stored;
 }
-function linkedSystemItem(def) {
+function sourceItem(def) {
 	if (typeof def !== "object" || def === null || isRef(def)) return def;
-	if (!isPlainObject(def.options)) return def;
+	const body = storedFromAuthored({
+		body: def,
+		authoredAt: SOURCE_AUTHORED_AT
+	});
+	if (!isPlainObject(body.options)) return body;
 	return {
-		...def,
-		options: storedPinOptions(def.options)
+		...body,
+		options: storedPinOptions(body.options)
 	};
 }
-const LinkedSystem = Object.assign(LinkedSystemDefinition, { item: linkedSystemItem });
+/**
+* `Source` (`yahoo-os`): another team's design system, drawn from at an exact version. Registered
+* under `sources`.
+*/
+const Source = Object.assign(LinkedSystemDefinition, { item: sourceItem });
+/** @deprecated Use {@link Source}, registered under `sources`. */
+const LinkedSystem = Source;
 /** Each `options` entry at a path its pin's `link` excludes, which derives no row for it to adjust. */
 function excludedDirectives(config) {
 	return config.list("linked-system").flatMap(({ path: slug }) => {
@@ -1080,4 +1100,4 @@ function redirectSentence(redirect) {
 	return `${at}, which names nothing this config can read.`;
 }
 //#endregion
-export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, Source, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

package/dist/framework/Config.d.ts

@@ -74,7 +74,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 = 20261102193912;
+declare const SERIALIZED_CONFIG_VERSION = 20261103115059;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -2236,6 +2236,14 @@ declare class Config {
   accessors(): Record<string, {
     kind: string;
   }>;
+  /**
+   * The accessor spellings this config type has retired, each mapped to the accessor it is now
+   * (`{ linkedSystems: 'sources' }`). A writer locating an entity in authored source reads it, since a
+   * file written before the rename still spells the old one.
+   */
+  deprecatedAccessors(): Readonly<Record<string, string>>;
+  /** `name`, or the accessor it now is when it's a retired spelling. */
+  currentAccessor(name: string): string;
   /** The kinds registered into this config — what it owns, whether or not they hold items yet.
    *  Tool derivation (reads + mutations) scopes to these so a config only exposes its own kinds
    *  (a source's kinds are read through their own config, so they derive none). */

package/dist/framework/Config.js

@@ -13,6 +13,7 @@ import { authoredBag, cssVar, declaresCssVariable, pinBodyStyleNumbers, stylePro
 import { addressOf, editOp, inputOf, opVerb } from "./config-op.js";
 import { isAuthoringPhantom, phantomsIn } from "./utils/authoring-phantom.js";
 import { configSchemas } from "./config-ops.js";
+import { storedFromAuthored } from "./authored-at.js";
 import { isAuthored } from "./authoring.js";
 import { Entity } from "./Entity.js";
 import { inlineAllSources } from "./inline-sources.js";
@@ -4540,6 +4541,18 @@ var Config = class Config {
 	accessors() {
 		return this.constructor.entities ?? {};
 	}
+	/**
+	* The accessor spellings this config type has retired, each mapped to the accessor it is now
+	* (`{ linkedSystems: 'sources' }`). A writer locating an entity in authored source reads it, since a
+	* file written before the rename still spells the old one.
+	*/
+	deprecatedAccessors() {
+		return this.constructor.deprecatedAccessors ?? {};
+	}
+	/** `name`, or the accessor it now is when it's a retired spelling. */
+	currentAccessor(name) {
+		return this.deprecatedAccessors()[name] ?? name;
+	}
 	/** The kinds registered into this config — what it owns, whether or not they hold items yet.
 	*  Tool derivation (reads + mutations) scopes to these so a config only exposes its own kinds
 	*  (a source's kinds are read through their own config, so they derive none). */
@@ -6255,12 +6268,13 @@ var Config = class Config {
 	* ({@link sources}: nobody resolved this) into a verdict. So the incremental case gets its own door.
 	*/
 	attachResolved({ source, slug, answer }) {
-		const kind = this.sourceAccessors().get(source);
-		if (!kind) throw new Error(`attachResolved: "${source}" is not a source this config declares. Its source accessors are ${[...this.sourceAccessors().keys()].map((name) => `"${name}"`).join(", ") || "(none)"}.`);
+		const accessor = this.currentAccessor(source);
+		const kind = this.sourceAccessors().get(accessor);
+		if (!kind) throw new Error(`attachResolved: "${accessor}" is not a source this config declares. Its source accessors are ${[...this.sourceAccessors().keys()].map((name) => `"${name}"`).join(", ") || "(none)"}.`);
 		const { config: resolved, ...state } = parseResolution({
-			source,
+			source: accessor,
 			slug,
-			schema: Config.resolutionSchemaOf(this, kind, source),
+			schema: Config.resolutionSchemaOf(this, kind, accessor),
 			answer
 		});
 		const sources = new Map(this.state.sources);
@@ -6344,12 +6358,13 @@ var Config = class Config {
 	*/
 	static async resolveDeclared(config, resolvers) {
 		const kindOfAccessor = config.sourceAccessors();
-		const missing = [...kindOfAccessor.keys()].filter((name) => !(name in resolvers));
+		const byAccessor = Object.fromEntries(Object.entries(resolvers).map(([name, resolve]) => [config.currentAccessor(name), resolve]));
+		const missing = [...kindOfAccessor.keys()].filter((name) => !(name in byAccessor));
 		if (missing.length > 0) throw new Error(`Config.load: no resolver for source ${missing.map((name) => `"${name}"`).join(", ")}. A source kind with no resolver answers nothing, which reads exactly like a config that borrows nothing — so it is refused here instead.`);
 		const states = /* @__PURE__ */ new Map();
 		const attached = {};
 		for (const [name, kind] of kindOfAccessor) {
-			const resolve = resolvers[name];
+			const resolve = byAccessor[name];
 			const bySlug = {};
 			const declared = Config.resolutionSchemaOf(config, kind, name);
 			const answers = await Promise.all(config.list(kind).map(async (entity) => {
@@ -6391,7 +6406,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 > 20261102193912) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261103115059) 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;
@@ -6741,7 +6756,11 @@ function extensionChange(entry, kind, path, raw, validate = false) {
 */
 function itemChange(entry, kind, path, raw, validate = false) {
 	const body = isRef(raw) || isComposedValue(raw) || typeof raw !== "object" || raw === null ? { [entry.primaryField]: raw } : raw;
-	const def = validate === "author" && entry.authoredBody ? entry.authoredBody(body) : body;
+	let def = validate === "author" && entry.authoredBody ? entry.authoredBody(body) : body;
+	if (validate === "author" && entry.authoredAt) def = storedFromAuthored({
+		body: def,
+		authoredAt: entry.authoredAt
+	});
 	if (validate) {
 		const parsed = wholeBodySchema(entry)?.safeParse(def);
 		if (parsed && !parsed.success) {

package/dist/framework/authored-at.d.ts

@@ -0,0 +1,31 @@
+//#region src/framework/authored-at.d.ts
+/**
+ * A stored field an author writes somewhere else in the body: `{ link: 'options.include' }` stores
+ * `options.include` as `link`. Declared by the kind (`EntityKind.authoredAt`), and read in three
+ * places that have to agree: `register` folds the authored spelling into the stored field, the config
+ * emitter writes the stored field back where an author writes it, and a patch written into a
+ * checkout lands at whichever of the two the file already spells.
+ *
+ * The stored field stays a spelling an author may use, so a file written before the move keeps
+ * evaluating. A body that spells both is refused, since the two are one value.
+ */
+/** Stored field → the dotted path it is authored at. */
+type AuthoredAt = Readonly<Record<string, string>>;
+/** A body as authored, with each field `authoredAt` moves folded into the field it's stored as. */
+declare function storedFromAuthored({
+  body,
+  authoredAt
+}: {
+  readonly body: Record<string, unknown>;
+  readonly authoredAt: AuthoredAt;
+}): Record<string, unknown>;
+/** A stored body as an author writes it: each field `authoredAt` moves, at the path it's authored at. */
+declare function authoredFromStored({
+  body,
+  authoredAt
+}: {
+  readonly body: Record<string, unknown>;
+  readonly authoredAt: AuthoredAt;
+}): Record<string, unknown>;
+//#endregion
+export { AuthoredAt, authoredFromStored, storedFromAuthored };

package/dist/framework/authored-at.js

@@ -0,0 +1,73 @@
+import { isPlainObject, setAtPath } from "./utils/field-path.js";
+import { rejectData } from "./rejection.js";
+//#region src/framework/authored-at.ts
+/**
+* A stored field an author writes somewhere else in the body: `{ link: 'options.include' }` stores
+* `options.include` as `link`. Declared by the kind (`EntityKind.authoredAt`), and read in three
+* places that have to agree: `register` folds the authored spelling into the stored field, the config
+* emitter writes the stored field back where an author writes it, and a patch written into a
+* checkout lands at whichever of the two the file already spells.
+*
+* The stored field stays a spelling an author may use, so a file written before the move keeps
+* evaluating. A body that spells both is refused, since the two are one value.
+*/
+/** The value at a dotted path, or `undefined` when nothing is there. */
+function valueAt(body, segments) {
+	let at = body;
+	for (const segment of segments) {
+		if (!isPlainObject(at) || !Object.hasOwn(at, segment)) return void 0;
+		at = at[segment];
+	}
+	return at;
+}
+/** `body` without the value at `segments`, pruning a parent the removal empties. */
+function without(body, segments) {
+	const [head, ...rest] = segments;
+	if (head === void 0 || !Object.hasOwn(body, head)) return body;
+	const { [head]: child, ...others } = body;
+	if (rest.length === 0) return others;
+	if (!isPlainObject(child)) return body;
+	const remaining = without(child, rest);
+	return Object.keys(remaining).length === 0 ? others : {
+		...others,
+		[head]: remaining
+	};
+}
+/** `body` with `value` first among the keys of the container at `segments`. */
+function withFirst(body, segments, value) {
+	const [head, ...rest] = segments;
+	if (head === void 0) return body;
+	if (rest.length === 0) return {
+		[head]: value,
+		...body
+	};
+	const child = isPlainObject(body[head]) ? body[head] : {};
+	return {
+		...body,
+		[head]: withFirst(child, rest, value)
+	};
+}
+/** A body as authored, with each field `authoredAt` moves folded into the field it's stored as. */
+function storedFromAuthored({ body, authoredAt }) {
+	let stored = body;
+	for (const [field, at] of Object.entries(authoredAt)) {
+		const segments = at.split(".");
+		const value = valueAt(stored, segments);
+		if (value === void 0) continue;
+		if (stored[field] !== void 0) rejectData(`\`${at}\` and \`${field}\` are one value, so a body sets only one of them. \`${field}\` is the deprecated spelling.`, segments);
+		stored = setAtPath(without(stored, segments), [field], value);
+	}
+	return stored;
+}
+/** A stored body as an author writes it: each field `authoredAt` moves, at the path it's authored at. */
+function authoredFromStored({ body, authoredAt }) {
+	let authored = body;
+	for (const [field, at] of Object.entries(authoredAt)) {
+		if (authored[field] === void 0) continue;
+		const { [field]: value, ...rest } = authored;
+		authored = withFirst(rest, at.split("."), value);
+	}
+	return authored;
+}
+//#endregion
+export { authoredFromStored, storedFromAuthored };

package/dist/framework/defineConfig.d.ts

@@ -113,8 +113,19 @@ type SourceMap<Owned extends EntityMap> = { readonly [K in keyof Owned]?: () =>
 type SourcesOf<C> = C extends {
   readonly sources: infer D;
 } ? D : Record<never, never>;
-/** `register` arg — partial, keyed by owned accessor name; a key not in `entities` is a type error. */
-type OwnedRecords<Owned extends EntityMap> = { [K in keyof Owned]?: RecordFor<Owned[K]> };
+/**
+ * Accessor spellings a config type has retired, each naming the accessor it is now:
+ * `{ linkedSystems: 'sources' }`.
+ *
+ * A retired spelling keeps working wherever an accessor is written (`register`, a `Collection`
+ * accessor, the resolver map `Config.load` takes) and is read as the accessor it names, so nothing
+ * stored or reported ever carries it. A JSDoc `@deprecated` on the entry reaches every one of those
+ * spellings, since the types below map over this record's own keys.
+ */
+type AccessorAliases<Owned extends EntityMap> = Readonly<Record<string, keyof Owned & string>>;
+/** `register` arg — partial, keyed by owned accessor name or a retired spelling of one; a key not in
+ *  `entities` is a type error. */
+type OwnedRecords<Owned extends EntityMap, Aliases extends AccessorAliases<Owned> = Record<never, never>> = { [K in keyof Owned]?: RecordFor<Owned[K]> } & { [A in keyof Aliases]?: RecordFor<Owned[Aliases[A]]> };
 /** A read-capable window onto a kind's items in a config — the value an accessor (`system.components`)
  *  returns, branded by the entity CLASS type so a wrong-kind one fails to type.
  *
@@ -142,9 +153,9 @@ interface Collection<E extends AnyEntityClass> {
  * the nominal brand its private members carry, so a `ConfigInstance` would stop being assignable to
  * `Config` — and nearly every reader in the codebase takes a `Config`.
  */
-type ConfigInstance<Owned extends EntityMap, Derived extends EntityMap> = {
-  register(records: OwnedRecords<Owned>): ConfigInstance<Owned, Derived>;
-} & Config & { [K in keyof Owned]: Collection<Owned[K]> } & { [K in keyof Derived]: Collection<Derived[K]> };
+type ConfigInstance<Owned extends EntityMap, Derived extends EntityMap, Aliases extends AccessorAliases<Owned> = Record<never, never>> = {
+  register(records: OwnedRecords<Owned, Aliases>): ConfigInstance<Owned, Derived, Aliases>;
+} & Config & { [K in keyof Owned]: Collection<Owned[K]> } & { [K in keyof Derived]: Collection<Derived[K]> } & { [A in keyof Aliases]: Collection<Owned[Aliases[A]]> };
 /**
  * What `defineConfig` returns — a constructor plus a typed static `fromJSON`.
  *
@@ -152,14 +163,16 @@ type ConfigInstance<Owned extends EntityMap, Derived extends EntityMap> = {
  * read — its borrowed values simply do not resolve — which is what `Config.load` exists to make
  * deliberate rather than accidental.
  */
-interface ConfigClass<Owned extends EntityMap, Derived extends EntityMap, Sources extends SourceMap<Owned> = Record<never, never>> {
-  new (): ConfigInstance<Owned, Derived>;
-  fromJSON(json: StoredConfig, options?: HydrationOptions): ConfigInstance<Owned, Derived>;
+interface ConfigClass<Owned extends EntityMap, Derived extends EntityMap, Sources extends SourceMap<Owned> = Record<never, never>, Aliases extends AccessorAliases<Owned> = Record<never, never>> {
+  new (): ConfigInstance<Owned, Derived, Aliases>;
+  fromJSON(json: StoredConfig, options?: HydrationOptions): ConfigInstance<Owned, Derived, Aliases>;
   readonly configName: string;
   readonly entities: Owned;
   readonly derivedEntities: Derived;
   /** What this type DRAWS ON — see {@link SourceMap}. Empty for a config that draws on nothing. */
   readonly sources: Sources;
+  /** Retired accessor spellings — see {@link AccessorAliases}. */
+  readonly deprecatedAccessors: Aliases;
   /**
    * Extend this config type — the same config with some kinds swapped for their extensions
    * (`System.extend({ tools: CliTool })`). What differs between two consumers is which entity answers
@@ -172,9 +185,9 @@ interface ConfigClass<Owned extends EntityMap, Derived extends EntityMap, Source
    * `fromJSON`. (Nothing is lost — a swapped DERIVED kind never serializes, so the wire form is
    * identical.)
    */
-  extend(swaps: Partial<Record<keyof Owned | keyof Derived, unknown>>): ConfigClass<Owned, Derived, Sources>;
+  extend(swaps: Partial<Record<keyof Owned | keyof Derived, unknown>>): ConfigClass<Owned, Derived, Sources, Aliases>;
 }
-declare function defineConfig<Owned extends EntityMap, Derived extends EntityMap = Record<never, never>, Sources extends SourceMap<Owned> = Record<never, never>>(spec: {
+declare function defineConfig<Owned extends EntityMap, Derived extends EntityMap = Record<never, never>, Sources extends SourceMap<Owned> = Record<never, never>, const Aliases extends AccessorAliases<Owned> = Record<never, never>>(spec: {
   name: string;
   /**
    * What this config type holds and how one is authored, for a reader arriving cold — an agent
@@ -193,10 +206,11 @@ declare function defineConfig<Owned extends EntityMap, Derived extends EntityMap
    * would declare a source on a collection no ref can qualify with, and the failure would surface as
    * "this config borrows nothing" much later.
    */
-  sources?: Sources;
+  sources?: Sources; /** Retired accessor spellings, each naming the accessor it is now — see {@link AccessorAliases}. */
+  deprecatedAccessors?: Aliases;
   /** Internal: built by `.extend` — it shares its base's name, so it must not take over the base's
    *  slot in the untyped `Config.fromJSON` dispatch registry. */
   extendsBase?: boolean;
-}): ConfigClass<Owned, Derived, Sources>;
+}): ConfigClass<Owned, Derived, Sources, Aliases>;
 //#endregion
-export { Collection, ConfigClass, ConfigInstance, ConfigKind, EntityMap, OwnedRecords, PartialBodyOf, PartialGroupBodyOf, SourceMap, SourcesOf, defineConfig, kindsOf };
+export { AccessorAliases, Collection, ConfigClass, ConfigInstance, ConfigKind, EntityMap, OwnedRecords, PartialBodyOf, PartialGroupBodyOf, SourceMap, SourcesOf, defineConfig, kindsOf };

package/dist/framework/defineConfig.js

@@ -21,6 +21,8 @@ function kindsOf(...configTypes) {
 function defineConfig(spec) {
 	const owned = spec.entities;
 	const sources = spec.sources ?? {};
+	const aliases = spec.deprecatedAccessors ?? {};
+	for (const [retired, current] of Object.entries(aliases)) if (retired in owned || !(current in owned)) throw new Error(`${spec.name}: retired accessor "${retired}" has to name an owned accessor and not be one itself`);
 	for (const name of Object.keys(sources)) {
 		const cls = owned[name];
 		if (!cls) throw new Error(`${spec.name}: source "${name}" is not an owned entity of this config`);
@@ -50,7 +52,9 @@ function defineConfig(spec) {
 		*  which is why the chained authoring form (`new System().register(…)`) is the idiom. */
 		register(records) {
 			let next = this;
-			for (const [name, record] of Object.entries(records)) {
+			for (const [written, record] of Object.entries(records)) {
+				const name = aliases[written] ?? written;
+				if (name !== written && name in records) throw new Error(`"${written}" and "${name}" are one collection in config "${spec.name}" ("${written}" is its retired spelling), so register takes only one of them`);
 				const cls = owned[name];
 				if (!cls) throw new Error(`"${name}" is not an owned entity of config "${spec.name}"`);
 				next = next.registerEntity(cls, record);
@@ -64,6 +68,7 @@ function defineConfig(spec) {
 		static entities = owned;
 		static derivedEntities = derived;
 		static sources = sources;
+		static deprecatedAccessors = aliases;
 		/** Swap kinds by their accessor name, across owned / derived. */
 		static extend(swaps) {
 			const pick = (base) => {
@@ -79,11 +84,19 @@ function defineConfig(spec) {
 				entities: pick(owned),
 				derivedEntities: pick(derived),
 				sources,
+				deprecatedAccessors: aliases,
 				extendsBase: true
 			});
 		}
 	}
-	for (const [name, cls] of [...Object.entries(owned), ...Object.entries(derived)]) {
+	for (const [name, cls] of [
+		...Object.entries(owned),
+		...Object.entries(derived),
+		...Object.entries(aliases).flatMap(([retired, current]) => {
+			const entity = owned[current];
+			return entity ? [[retired, entity]] : [];
+		})
+	]) {
 		if (name in TypedConfig.prototype || name === "state") throw new Error(`${spec.name}: entity accessor "${name}" collides with a Config member — rename the accessor (the KIND itself is unaffected)`);
 		Object.defineProperty(TypedConfig.prototype, name, {
 			get() {