@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/entities/system/LinkedSystem.js

@@ -0,0 +1,814 @@
+import { rejectData } from "../../framework/rejection.js";
+import { isPlainObject } from "../../framework/utils/field-path.js";
+import { pathInput } from "../../framework/schemas.js";
+import { kindBorrowable } from "../../framework/registry.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { sourceUnreachable } from "../../framework/sources.js";
+import { planCopy } from "./copy-plan.js";
+import { planBreak, planLink, planUnlink, sourceRowStates } from "./link-plan.js";
+import { z } from "zod";
+//#region src/entities/system/LinkedSystem.ts
+/**
+* `LinkedSystem` (`yahoo-os`) — another team's design system, drawn from at an exact version.
+*
+* Two questions kept apart, and this entity answers only the first:
+*
+*   • **What can I see?** — you link a system. Everything in it becomes visible and resolvable.
+*   • **What am I using?** — you write a ref (`token:color/brand@yahoo-os`). That's the only thing
+*     stored.
+*
+* Linking copies nothing and makes nothing yours; it puts a system within reach. That is what makes
+* partial use the normal case rather than a mode: link 400 tokens, use 12, store 12 refs. The other
+* 388 stay visible, for browsing and for later, without being in your system.
+*
+* **The key is a local slug**, not the source's database id. It is what every ref spells, so it has to
+* be readable and to survive the source renaming itself. `systemId` carries durable identity
+* underneath, and `name` is display only, so a source that renames strands no refs.
+*
+* **A repo-local link round-trips.** Push writes the resolved `systemId`/`version` beside the authored
+* `configPath`, so Studio reads an ordinary link while `uds pull` can still restore the path form.
+* Dropping `configPath` at push would make a pull rewrite `'../design-system'` into a published pin.
+* The path is inert server-side, as `playground.pagesDir` is.
+*
+* **Being an entity means it needs no special support.** Create, update, delete, validation and
+* `dependents` all derive from these three fields as they do for a token, so an upgrade is an ordinary
+* update of one field with no separate manifest to keep in sync. It is also the install list: `uds
+* pull` reads these entries and materializes each one.
+*/
+/**
+* An exact version — `2.4.0`, never `^2.4.0` or `latest`.
+*
+* A link is always pinned: you draw from Yahoo OS 2.4.0 rather than from "Yahoo OS", so their next
+* release can't change what you render until you move the pin. A range would give that away, and it
+* would need a resolution step and a lockfile to mean anything, neither of which exists. Spelled as a
+* pattern rather than pulled from `semver`, so this package keeps its three dependencies.
+*/
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+* A link's slug, as a single path segment.
+*
+* The slug is more than a key: `uds install` writes one registry folder per link and names it this, so
+* a slug that isn't a path segment is one the install step can't use, and `../..` would be a traversal
+* handed to a file write. Stated here on the entity so the rule has one home — the install refuses
+* with it, an authoring UI can say so before submitting, and an AI tool creating a link is bound by it
+* too. Enforced only at install, a config would commit fine and break for whoever runs the build.
+*/
+const LINK_SLUG = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i;
+/** Whether `slug` can be a link's local name — {@link LINK_SLUG}, as a predicate for a caller that wants
+*  to ask rather than to match. */
+function isLinkSlug(slug) {
+	return LINK_SLUG.test(slug);
+}
+/** What a refused slug should say, in one place, so the install and a form word it identically. */
+const LINK_SLUG_MESSAGE = "A link's slug is a single path segment — letters, digits, dot, dash and underscore — because it becomes a folder in the registry.";
+/**
+* Where a linked system resolved from, carrying the identity that origin actually has.
+*
+* Discriminated on `from` rather than a flat `{ systemId, version, from }`. A repo-local source has no
+* published identity to report: its identity is the config path, and a built artifact carries no
+* `systemId` or `version` at all. A flat shape would require two fields that one of the three origins
+* can never fill, so a resolver would have to invent an id to satisfy it.
+*
+* Each origin therefore says what it knows, which is also what makes "what did this build against"
+* answerable for both kinds of source.
+*
+* Declared here beside the kind and handed to the framework through `sourceResolution`. These three
+* origins are what a linked system has; a `linkedPackages` kind would resolve from a lockfile and
+* couldn't fill this union, which is why the framework holds only the `status` tag.
+*/
+const resolvedSource = z.discriminatedUnion("from", [
+	z.object({
+		from: z.literal("disk"),
+		configPath: z.string().min(1)
+	}),
+	z.object({
+		from: z.literal("registry"),
+		systemId: z.string().min(1),
+		version: z.string().min(1)
+	}),
+	z.object({
+		from: z.literal("storage"),
+		systemId: z.string().min(1),
+		version: z.string().min(1)
+	})
+]);
+/**
+* Why a declared linked system couldn't be met — a code plus the data that case needs, and no prose.
+*
+* A closed set, so a surface switches exhaustively and adding a case is a compile error at every
+* consumer. Collapsed into `undefined`, these all look alike, which is how a rail ends up saying a
+* value "isn't loaded here" when it is loaded and the ref is broken.
+*
+* **No `message`.** The fix depends on the surface rather than the code: a build tells you to run
+* `uds install` or to build the sibling first, and neither sentence means anything in a browser where
+* `stale` is an update button. One string per code would put CLI instructions into Studio. What such a
+* message really carries is the data here — `stale` can't be phrased at all without both versions.
+*
+* **`not-found` covers three situations on purpose.** A system the caller can't see and a version
+* never published have to be indistinguishable, or the difference is a probe: ask for an id you
+* suspect exists, and a separate code confirms it. A resolver may know which internally; it must not
+* cross out in the value.
+*/
+const sourceUnavailable = z.discriminatedUnion("code", [
+	z.object({ code: z.literal("not-installed") }),
+	z.object({
+		code: z.literal("unbuilt"),
+		configPath: z.string().min(1)
+	}),
+	z.object({
+		code: z.literal("stale"),
+		installed: z.string().min(1),
+		pinned: z.string().min(1)
+	}),
+	z.object({ code: z.literal("not-found") }),
+	z.object({ code: z.literal("unmaterializable") }),
+	sourceUnreachable
+]);
+/** What one accessor of a copy names: every entry of the kind, or the source's paths — items or folders. */
+const copyPaths = z.union([z.literal("*"), z.array(z.string().min(1)).min(1)]);
+const copyInput = z.object({
+	path: pathInput("linked-system"),
+	/**
+	* What to take, keyed by accessor the way the pin's `link` is — `{ tokens: ['color/brand', 'color'],
+	* icons: '*' }` — or `'*'` for every kind the source offers and this config can hold. A path that
+	* names a folder in the source takes its members. Copied rows keep the source's own names.
+	*/
+	data: z.union([z.literal("*"), z.record(z.string(), copyPaths)]),
+	/**
+	* What to do at a path this config already holds. `'skip'` (the default) keeps what is there and
+	* binds copied refs to it; `'replace'` writes the source's body over a row of yours, and over a row
+	* held through another pin when `data` names it. A row the copy only reaches through a ref is kept
+	* either way.
+	*/
+	onConflict: z.enum(["skip", "replace"]).optional()
+});
+const linkInput = z.object({
+	path: pathInput("linked-system"),
+	/** What to draw, keyed by accessor the way the pin's `link` is, or `'*'` for everything the source
+	*  offers. A path that names a folder in the source covers its members. */
+	data: z.union([z.literal("*"), z.record(z.string(), copyPaths)])
+});
+const unlinkInput = z.object({
+	path: pathInput("linked-system"),
+	/** What to stop drawing, in `link`'s shape; everything when omitted. */
+	data: z.union([z.literal("*"), z.record(z.string(), copyPaths)]).optional()
+});
+const breakInput = z.object({
+	path: pathInput("linked-system"),
+	/** Whether every value drawn through the pin becomes this config's own first. */
+	keep: z.boolean()
+});
+const breakPlanInput = z.object({
+	path: pathInput("linked-system"),
+	keep: z.boolean().optional(),
+	/** One entity or folder detached through `copy` rather than the whole pin. */
+	data: z.union([z.literal("*"), z.record(z.string(), copyPaths)]).optional()
+});
+const rowsInput = z.object({ path: pathInput("linked-system") });
+/** The parsed op input as the plan takes it. */
+function copyInputOf(input) {
+	return {
+		path: String(input.path),
+		data: input.data,
+		...input.onConflict === void 0 ? {} : { onConflict: input.onConflict }
+	};
+}
+/** A `link` or `unlink` example: one entity the source offers, under the accessor this config files it by. */
+function linkExample({ config, path }) {
+	const target = exampleBorrowable(config, path);
+	if (!target) return void 0;
+	return {
+		path,
+		data: { [config.accessorOf(target.kind) ?? target.kind]: [target.from] }
+	};
+}
+/** An example for an op that takes the pin alone, shown once the pin has a source to read. */
+function pinExample({ config, path }) {
+	return exampleBorrowable(config, path) ? { path } : void 0;
+}
+/** A break's example, shown once the pin has a source to read. */
+function breakExample({ config, path }) {
+	return exampleBorrowable(config, path) ? {
+		path,
+		keep: true
+	} : void 0;
+}
+/** A copy's example: one entity the source offers, under the accessor this config files it by. */
+function copyExample({ config, path }) {
+	const target = exampleBorrowable(config, path);
+	if (!target) return void 0;
+	return {
+		path,
+		data: { [config.accessorOf(target.kind) ?? target.kind]: [target.from] }
+	};
+}
+/**
+* A real borrow target on the other side of a pin, for the custom ops' examples.
+*
+* The derived default example is built from the standard `path`/`to` address shape, which describes a
+* rename and satisfies none of these ops' own `required`. So each declares one, and each declares it
+* from the catalogue rather than from a canned string, because an example naming a token the source
+* doesn't have teaches a caller to write a refusal.
+*
+* A pin with nothing attached has no catalogue to read, so the op shows no example rather than an
+* invented one.
+*/
+function exampleBorrowable(config, slug) {
+	const source = config.sourceFor(slug);
+	if (!source) return void 0;
+	for (const kind of source.ownedKinds()) {
+		if (!config.entityOf(kind)) continue;
+		if (!kindBorrowable(config.entityOf(kind), {
+			config,
+			source
+		})) continue;
+		const [first] = source.list(kind);
+		if (first) return {
+			kind,
+			from: first.path
+		};
+	}
+}
+const pinOptions = z.record(z.string(), z.record(z.string(), z.strictObject({
+	override: 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();
+const LinkedSystem = defineEntity({
+	kind: "linked-system",
+	label: "Linked system",
+	labelPlural: "Linked systems",
+	schemas: {
+		/**
+		* Draw entities from a linked system: the pin's `link` declaration grows to cover them and the
+		* build mints a pointer row per entity, in this one op. A row of this config's own at a covered
+		* path is deleted so theirs shows through; a row held through another pin becomes an extension
+		* through this one. `link-plan` says what that replaces before anything is written.
+		*/
+		link: {
+			input: linkInput,
+			readOnly: false,
+			label: "Link from",
+			description: "Draw entities from a linked system, following the source: `data` names them by accessor — `{ tokens: ['color/brand', 'color'] }` takes an entity and a folder's members, `{ tokens: '*' }` every token, and `'*'` the whole system. What this config already holds at those paths is replaced by theirs, so run `linked-system/link-plan` with the same input first to see what that is. To hold their values as your own instead, `copy`.",
+			scope: "item",
+			approval: "reference-change",
+			title: (entity) => `Link something from ${entity}`,
+			example: linkExample,
+			handler: (input, config) => {
+				const { patches } = planLink({
+					config,
+					input: {
+						path: String(input.path),
+						data: input.data
+					}
+				});
+				if (patches.length === 0) return config;
+				return config.applyAll(patches).withDerivedRows();
+			}
+		},
+		"link-plan": {
+			input: linkInput,
+			readOnly: true,
+			label: "Plan a link",
+			description: "What `link` with the same input replaces — rows of yours deleted so the source shows through, rows held through another pin turned into extensions, and members left alone because they are already here from the same origin. Writes nothing.",
+			scope: "item",
+			title: (entity) => `Plan a link from ${entity}`,
+			example: linkExample,
+			handler: (input, config) => {
+				const { patches: _patches, ...plan } = planLink({
+					config,
+					input: {
+						path: String(input.path),
+						data: input.data
+					}
+				});
+				return plan;
+			}
+		},
+		/**
+		* Stop drawing from a linked system, whole or in part. The declaration narrows and the rows it
+		* minted retire in the same op; the pin stays, so it can be linked again.
+		*/
+		unlink: {
+			input: unlinkInput,
+			readOnly: false,
+			label: "Unlink from",
+			description: "Stop following a linked system's entities, in `link`'s shape or everything when `data` is omitted. The rows the declaration minted go with it, and so do the linked rows that point at them, since left linked they would bring them back; nothing of yours moves. A row of yours pointing at one of theirs refuses this — `copy` what is used first, or `break` with `keep: true`. `unlink-plan` names everything that goes.",
+			scope: "item",
+			approval: "reference-change",
+			title: (entity) => `Unlink from ${entity}`,
+			example: pinExample,
+			handler: (input, config) => {
+				const { patches, blocked } = planUnlink({
+					config,
+					input: {
+						path: String(input.path),
+						...input.data === void 0 ? {} : { data: input.data }
+					}
+				});
+				if (blocked !== void 0) rejectData(blocked);
+				if (patches.length === 0) return config;
+				return config.applyAll(patches);
+			}
+		},
+		"unlink-plan": {
+			input: unlinkInput,
+			readOnly: true,
+			label: "Plan an unlink",
+			description: "What `unlink` with the same input removes — the minted rows the narrower declaration no longer reaches, with the linked rows taken along because they point at them named in `cascade` — and why the config would refuse it. Writes nothing.",
+			scope: "item",
+			title: (entity) => `Plan unlinking from ${entity}`,
+			example: pinExample,
+			handler: (input, config) => {
+				const { patches: _patches, ...plan } = planUnlink({
+					config,
+					input: {
+						path: String(input.path),
+						...input.data === void 0 ? {} : { data: input.data }
+					}
+				});
+				return plan;
+			}
+		},
+		/**
+		* Break the link: the pin goes, and everything drawn through it either becomes this config's own
+		* or goes with it.
+		*/
+		break: {
+			input: breakInput,
+			readOnly: false,
+			label: "Break link",
+			description: "Remove a linked system. With `keep: true` every value drawn through it is copied in as your own first, and a row of yours that pointed through the pin points at the copies; with `keep: false` the rows it minted go, and a row of yours still pointing through it refuses the break. Run `linked-system/break-plan` first to see every row it reaches.",
+			scope: "item",
+			approval: "destructive",
+			title: (entity) => `Break the link to ${entity}`,
+			example: breakExample,
+			handler: (input, config) => {
+				const { patches } = planBreak({
+					config,
+					input: {
+						path: String(input.path),
+						keep: Boolean(input.keep)
+					}
+				});
+				return config.applyAll(patches);
+			}
+		},
+		"break-plan": {
+			input: breakPlanInput,
+			readOnly: true,
+			label: "Plan a break",
+			description: "Every row a break reaches, and why the config would refuse it. `keep` plans `break` with the same input; `data` in `copy`'s shape plans detaching those entities alone — the rows the copy lands, the rows of yours it points at the copies, and the rows still linked that reference what moves. Writes nothing.",
+			scope: "item",
+			title: (entity) => `Plan breaking the link to ${entity}`,
+			example: breakExample,
+			handler: (input, config) => {
+				const { patches: _patches, ...plan } = planBreak({
+					config,
+					input: {
+						path: String(input.path),
+						...input.keep === void 0 ? {} : { keep: Boolean(input.keep) },
+						...input.data === void 0 ? {} : { data: input.data }
+					}
+				});
+				return plan;
+			}
+		},
+		/**
+		* The source's catalogue read against this config: one row per top-level folder or item the
+		* source offers, saying whether it is linked here and what linking it would replace.
+		*/
+		rows: {
+			input: rowsInput,
+			readOnly: true,
+			label: "Source rows",
+			description: "Every top-level folder and item the linked system offers, read against this config: whether every member is linked through this pin, how many rows of yours a `link` would replace, and how many members are already here from the source's own origin. Needs the source attached; empty otherwise.",
+			scope: "item",
+			title: (entity) => `What ${entity} offers`,
+			example: pinExample,
+			handler: (input, config) => sourceRowStates({
+				config,
+				slug: String(input.path)
+			})
+		},
+		/**
+		* Take entities from a linked system as this config's own — the source's bodies, written once.
+		* A pin puts a system within reach and its `link` mints pointers; `copy` stores the value. A copied
+		* row is an ordinary authored row from the moment it lands: the source's later versions never reach
+		* it, and it renames and deletes like anything else here.
+		*
+		* A copy stands on its own. What a copied row points at comes with it — a component brings the
+		* style properties and tokens it names, a style property brings the token folder its values
+		* range over, a code component brings the files its module reaches — and every one of those refs
+		* lands bare, on the local copy. A path this config already holds as its own is reused rather
+		* than copied, and refs bind to it. Only a ref to a kind this config can't hold stays qualified,
+		* and the pin survives to answer it. Someone who wants theirs by reference writes `Button@slug`
+		* instead.
+		*
+		* A pointer at the path, minted through this pin, becomes the literal it stood for with its
+		* `extend` laid over the source's body. A folder's meta comes with its members, so a label the
+		* folder was inheriting becomes its own.
+		*
+		* `data` is keyed the way the pin's `link` is: by accessor, then `'*'` for every entry of the kind
+		* or the source's paths — an item, or a folder, which takes its members. `'*'` alone takes every
+		* kind the source offers and this config can hold. Kinds taken in one edit are copied together,
+		* which is what lets a copied component point at the copied tokens rather than back through the
+		* pin.
+		*
+		* Every row lands in one derive (`Config.applyAll`), and each is its own `create` or `replace`
+		* patch carrying the literal body, so a draft replays a copy onto a base with nothing attached.
+		*/
+		copy: {
+			input: copyInput,
+			readOnly: false,
+			label: "Copy from",
+			description: "Take entities from a linked system as your own, holding the values the source has now and no longer following it. `data` names them by accessor: `{ tokens: ['color/brand', 'color'] }` takes an entity and a folder's members, `{ tokens: '*' }` every token, and `'*'` the whole system. What a copied entity points at comes with it, so run `linked-system/copy-plan` with the same input first and see everything that lands. To use theirs without owning it, declare it in the pin's `link` instead. A whole-system copy is thousands of rows, and on a repo-backed system each one is written into `uds.config.ts`.",
+			scope: "item",
+			approval: "reference-change",
+			title: (entity) => `Copy something from ${entity}`,
+			example: copyExample,
+			handler: (input, config) => {
+				const { patches } = planCopy({
+					config,
+					input: copyInputOf(input)
+				});
+				return config.applyAll(patches);
+			}
+		},
+		/**
+		* What that same `copy` call would do, without doing it — the rows that land, what comes along
+		* because something named points at it, and the rows of yours a copied ref binds to instead.
+		*
+		* A read, taking `copy`'s own input verbatim, so a surface plans the invocation it is about to
+		* send. The op is this plan applied, so the two cannot disagree.
+		*/
+		"copy-plan": {
+			input: copyInput,
+			readOnly: true,
+			label: "Plan a copy",
+			description: "See what copying would bring before you do it — what lands as yours, what comes along because it is pointed at, and what you already hold that the copies will point at. Takes exactly the same input as `copy` and writes nothing. Run it before `copy`, and always before a `'*'` copy.",
+			scope: "item",
+			title: (entity) => `Plan a copy from ${entity}`,
+			example: copyExample,
+			handler: (input, config) => {
+				const { patches: _patches, ...plan } = planCopy({
+					config,
+					input: copyInputOf(input)
+				});
+				return plan;
+			}
+		}
+	},
+	fields: z.strictObject({
+		/**
+		* The sibling config this link resolves from — the repo-local form, and the primary field, so it is
+		* declared as a bare string.
+		*
+		* A config path rather than a directory, because `-c, --config <path>` is the convention everywhere
+		* else and a package may hold more than one config (web and native), so a directory would be
+		* ambiguous about which system you meant. Naming the config also lets install check
+		* `.uds/build-context.json`, so pointing at one config and reading another's output is an error
+		* rather than a silent wrong answer.
+		*
+		* ```ts
+		* linkedSystems: {
+		*   ds: '../design-system/uds.config.ts',                       // repo-local
+		*   yahooOs: LinkedSystem.item({ systemId, name, version }),    // published
+		* }
+		* ```
+		*
+		* Both forms are declared in one place, because "which system" and "where from" are one decision
+		* per link. npm spells it the same way, with the value saying both (`"workspace:*"` against
+		* `"^2.4.0"`).
+		*
+		* It is `configPath` and not `path`, because an entity's identity is its `path`: `Entity` assigns
+		* fields onto itself, so a field called `path` would overwrite the slug and key the link by its own
+		* directory. Nor `workspace`, which is a product noun here (org → workspace → team → system). It is
+		* literally a config path, and it mirrors `githubConfigPath` on `systems`, the field push derives
+		* this link's identity against.
+		*
+		* **`configPath` wins for resolution.** When it is set, the build reads the sibling's artifact and
+		* ignores `version`: a repo-local link tracks whatever the sibling currently is, which is the point
+		* in a monorepo, and a built artifact carries no `systemId` or `version` to pin against.
+		*/
+		configPath: z.string().min(1).optional(),
+		/**
+		* What this system draws from that source — a standing declaration, and the thing the build turns
+		* into rows.
+		* ```ts
+		* link: '*'                                            // everything, every kind
+		* link: { tokens: '*', icons: '*' }                    // those kinds whole
+		* link: { tokens: ['color/brand', 'color/paper'] }     // those entities
+		* link: { components: ['actions'] }                    // a folder: its members
+		* ```
+		* `Config.withDerivedRows` reads it and makes a pointer row per entity it covers — on every build,
+		* and inside the apply of any patch to this pin — so a link's cost in authored source is this one
+		* declaration whatever the source's size, and the rows come and go with it.
+		*
+		* Keyed by accessor (`tokens`, `components`) rather than by kind (`token`, `component`), because
+		* this is read in a config file, and a config file is keyed by accessor everywhere else —
+		* `register({ tokens, components })`, `sources: { linkedSystems: … }`. Ops and refs use the kind.
+		* `Config.accessorOf` maps between them, off the config type's own manifest, so no kind is named
+		* here. Paths are the source's own; a path that names a folder there covers its members.
+		*
+		* **Standing, so a source that grows is covered without re-running anything.** The declaration is
+		* read on every build, and what it produces is an ordinary stored row — indistinguishable from a
+		* borrow written by hand, which is what keeps the rename gate, `inlineAllSources` when it seals an
+		* artifact and `emitBorrowedComponents` when it emits a module all working unchanged.
+		*
+		* A path this config already holds is left alone, silently, whether it authored that row or
+		* borrowed it. Local shadows a source, and that is what makes deriving over a grown source
+		* additive rather than a set of conflicts to resolve. It is also how one of their entities is kept
+		* out: author your own at that path, or narrow what this declares.
+		*
+		* Deleting a row this covers is refused ({@link EntityKind.bulkAdopts} is what reads it): the
+		* build would make it again on the next pass, and a delete that comes back is worse than one that
+		* was refused. To own one of their entities, `copy` it; to stop drawing it, `unlink` it.
+		*
+		* The gestures that write this are the kind's own ops — `link`, `unlink`, `break` — each with a
+		* `-plan` read beside it, so a surface never assembles the declaration by hand.
+		*
+		* `'*'` means every kind that may be drawn on, which is every kind that may be borrowed — each
+		* kind says which it is (`EntityKind.linkable`). Nothing is subtracted: a pin and a `file` aren't
+		* borrowable, so no borrow of one exists for this to cover.
+		*/
+		link: z.union([z.literal("*"), z.record(z.string(), z.union([z.literal("*"), z.array(z.string().min(1)).min(1)]))]).optional(),
+		/**
+		* What this system does to individual entities of the source, keyed by accessor, then by the path
+		* the source spells, then by verb.
+		*
+		* ```ts
+		* options: {
+		*   tokens: {
+		*     'color/brand': {
+		*       override: { modifiers: { dark: Token.ref('spectrum/violet/70') } },
+		*       extend: { modifiers: { highContrast: Token.ref('spectrum/violet/90') } },
+		*     },
+		*     'palette/legacy': { hidden: true },
+		*   },
+		* }
+		* ```
+		*
+		* `override` changes a value the source defines and `extend` covers a case it does not. Both land in
+		* the row's `extend`, so a bulk adjustment and a hand-written `.extend(...)` store the same thing and
+		* nothing downstream can tell which spelling made it. Both may sit on one path: a token overridden
+		* under one modifier and extended under another is one entity pulled two ways.
+		*
+		* OPEN: `overlayBody` combines the two with a spread, so two verbs naming one top-level field keep
+		* only the `extend` half — the example above loses its dark override. They have to merge by member,
+		* the way the stored `extend` merges into the source's body.
+		*
+		* Which verb applies is derivable — comparing the body against the source says whether a leaf is
+		* new — and the build does compare, to check the declaration. It is declared anyway because that is
+		* what notices the source moving: a field they add later turns an extension into an override
+		* silently, and a declared verb is what has something to disagree with.
+		*
+		* `hidden` keeps the entity and stops offering it; references already resolving through it have to
+		* keep working, so nothing about the output changes. Carried on {@link SourceOverlay}, and read by no
+		* authoring surface yet.
+		*
+		* A field rather than accessor keys at the pin's top level, so the pin stays a closed object and a
+		* misspelled `systemId` is still refused. Only these keys are open, and they are accessor names
+		* for the reason `link` takes accessors: a config file is accessor-keyed everywhere else.
+		*
+		* OPEN: nothing checks them against the config's own accessors, so a misspelled `toknes` covers no
+		* path and says nothing.
+		*/
+		options: pinOptions,
+		/**
+		* An npm package that ships a built system — `@acme/design-system`.
+		*
+		* The third origin, and the one a consumer outside the publisher's monorepo and off their Create
+		* instance actually has. Resolution walks the `node_modules` ancestry for the name and reads that
+		* package's own build output, so the package has to ship its `.uds/` directory.
+		*
+		* **A name, not a path into `node_modules`.** A path would hardcode a hoisting layout, which is the
+		* one thing about `node_modules` a consumer can't predict, and is why the resolver walks upward. A
+		* name also keeps the origin legible: a linking surface can say "from npm" instead of
+		* pattern-matching a directory.
+		*
+		* **npm does the pinning, so there is no `version` here.** A `package` link tracks whatever is
+		* installed, the way a `configPath` link tracks whatever the sibling currently is. `package.json`
+		* and the lockfile already decide it, so a second copy here would be a version nobody resolves
+		* against. `version` stays observed for this origin, as it is for a sibling.
+		*/
+		package: z.string().min(1).optional(),
+		/**
+		* The source's database id — durable identity, which survives a rename on their side.
+		*
+		* Optional, because a repo-local link has none to give. Identity is a Create concept resolved from
+		* the repo binding, and the only thing that reads it is Studio, which is only reached by `uds push`.
+		* So push derives it for a `configPath` link and writes it into the artifact, and nothing local asks
+		* an author to hand-type an unverifiable id.
+		*/
+		systemId: z.string().min(1).optional(),
+		/** Display only, never identity: what to call this source in the UI. Defaults to the slug. */
+		name: z.string().optional(),
+		/**
+		* The exact published version every ref through this link resolves against.
+		*
+		* For a `configPath` link this is **observed rather than pinned**: push records what the sibling was
+		* at push time so Studio can say which version it saw, and the local build still tracks current
+		* state. Read as a pin, a repo-local link would go stale the moment the sibling moved.
+		*/
+		version: z.string().regex(EXACT_VERSION, "A link is pinned to an exact version (2.4.0), not a range").optional()
+	}),
+	computed: { 
+	/**
+	* What to call this source — its `name`, or the slug when it declares none.
+	*
+	* The fallback belongs here because the default is a fact about the field: `name` is optional, and
+	* a source with none is the slug it's filed under. Left to consumers, every surface that renders a
+	* source implements the same `??`, and one of them eventually renders `undefined`.
+	*/
+displayName: ({ member, path }) => typeof member.name === "string" && member.name.length > 0 ? member.name : path },
+	/**
+	* The fields that decide which system a slug resolves against — the same ones `uds install` records
+	* in `pin.json`. `name` is display only, so a value borrowed through this link survives a rename of
+	* the label.
+	*/
+	sourceIdentity: [
+		"configPath",
+		"package",
+		"systemId",
+		"version"
+	],
+	/** Which system, at whatever version: two pins agreeing here draw on one origin. */
+	sourceOrigin: [
+		"configPath",
+		"package",
+		"systemId"
+	],
+	/**
+	* A pin is never borrowed, only declared. Taking one from a source would make their dependencies
+	* yours, at their versions, including systems you have no access to and no way to see — and the slug
+	* would join `sourceSlugs()` as a source this config must resolve on its own. What motivates it needs
+	* none of that: a borrow whose value points at a system two hops away already resolves, because
+	* `ownerOf` follows the chain through the source that declared it.
+	*
+	* Wanting a direct dependency on what a source depends on is reasonable, and it is a pin of your own,
+	* with a version you chose.
+	*/
+	linkable: false,
+	/**
+	* What a resolver for this kind may answer with. The framework supplies the `attached`/`unavailable`
+	* tag; these two say what each branch of this kind's answer carries.
+	*/
+	sourceResolution: {
+		resolved: resolvedSource,
+		unavailable: sourceUnavailable
+	},
+	/**
+	* Whether this pin's `link` declaration covers one of the source's entities — the derive pass's
+	* question and the delete gate's, answered here because `link` is this kind's field and its shape
+	* is this kind's to interpret.
+	*
+	* `'*'` at either level covers everything under it; a list covers the paths it names, as the source
+	* spells them, and a named folder covers its members. Nothing excludes a kind here — a kind a
+	* whole-source take does not reach is one no borrow of it exists for (`EntityKind.linkable`), so
+	* the claim is unreachable rather than filtered.
+	*/
+	bulkAdopts: ({ body, kind, accessor, path }) => {
+		const declared = body.link;
+		if (declared === void 0) return false;
+		if (declared === "*") return true;
+		const paths = declared[accessor ?? kind];
+		if (paths === void 0) return false;
+		if (paths === "*") return true;
+		return paths.some((declaredPath) => declaredPath === path || path.startsWith(`${declaredPath}/`));
+	},
+	bulkOverlay: ({ body, kind, accessor, path }) => {
+		const directive = directiveAt(body, accessor ?? kind, path);
+		if (!directive) return void 0;
+		return {
+			override: directive.override,
+			extend: directive.extend,
+			hidden: directive.hidden === true
+		};
+	},
+	/**
+	* The field-path address `options` stores one entry at — accessor, then the path the source
+	* spells, so an edit to a minted row lands on the same key {@link directiveAt} reads back.
+	*/
+	bulkDirectives: (body) => {
+		const options = body.options;
+		if (!options) return [];
+		return Object.entries(options).flatMap(([accessor, entries]) => isPlainObject(entries) ? Object.keys(entries).map((path) => ({
+			accessor,
+			path
+		})) : []);
+	},
+	bulkOverlayWrite: ({ accessor, path, overlay }) => ({ [`options.${accessor}.${path}`]: overlay })
+});
+/** The `options` entry for one path, or `undefined` where the pin says nothing about it. */
+function directiveAt(body, accessor, path) {
+	return body.options?.[accessor]?.[path];
+}
+/**
+* The source an entity comes from — `undefined` for one wholly this config's own, and for one that
+* involves two systems, since naming either would label the other wrongly. See `Entity.source`.
+*
+* This is the provenance read. It folds both ways an entity can involve another system — borrowed and
+* locally extended, or authored here with a value pointing through a link — because a badge, an
+* adornment and a "Source" row want the same answer either way. {@link borrowedItem} is the other read,
+* the one a write gate wants, and picking the wrong one is quiet in both directions.
+*
+* Two hops: the entity's `source` answers which slug, and this kind answers for the slug. It lives
+* beside the kind rather than on `Config` because the answer is one of these items, typed off the schema
+* above. A `Config` method could only hand back a bare `Entity` or a bag naming the fields this kind
+* happens to declare, and every consumer of that bag has to be found again when the kind gains one.
+*
+* Named for the item it answers about, because {@link Config.sourceFor} already answers the
+* slug-to-config question and `sourceOf` already reads the slug off a ref.
+*/
+function sourceOfItem({ config, kind, path }) {
+	const slug = config.resolve(kind, path)?.source;
+	return slug === void 0 ? void 0 : LinkedSystem.get(config, slug);
+}
+/**
+* The source a group draws through — set only when every member agrees on one.
+*
+* The agreement rule is kind-agnostic and lives on {@link Config.groupSource}. This makes the same
+* second hop {@link sourceOfItem} makes, so a surface gets the typed pin rather than a slug it would
+* have to look up itself.
+*/
+function sourceOfGroup({ config, kind, groupPath }) {
+	const slug = config.groupSource({
+		kind,
+		groupPath
+	});
+	return slug === void 0 ? void 0 : LinkedSystem.get(config, slug);
+}
+/**
+* The source an item is — `undefined` for one this config authored, including one whose own fields
+* point through a link.
+*
+* The write gate's reader, where {@link sourceOfItem} is the badge's. They are easy to swap, and the
+* failure is quiet in both directions: gating on `sourceOfItem` locks a local alias its own author
+* wrote, and badging on this one leaves a borrowed value looking native.
+*
+* To choose between them, ask whether the other side is affected. Retargeting a ref we declared changes
+* nothing but our artifact, so it is ours; the fields of an item we borrowed are the source's, and a
+* local edit to them can only be an overlay. See `Entity.borrowedFrom`.
+*/
+function borrowedItem({ config, kind, path }) {
+	const slug = config.resolve(kind, path)?.borrowedFrom;
+	return slug === void 0 ? void 0 : LinkedSystem.get(config, slug);
+}
+/** The source a whole group is borrowed from — {@link borrowedItem}'s group form, and the same second
+*  hop {@link sourceOfGroup} makes. Set only when every member agrees, which is `Config`'s rule to
+*  state and not this one's. Gates what can be done to the folder: adding, renaming, reordering. */
+function borrowedGroup({ config, kind, groupPath }) {
+	const slug = config.groupBorrowedFrom({
+		kind,
+		groupPath
+	});
+	return slug === void 0 ? void 0 : LinkedSystem.get(config, slug);
+}
+/**
+* A config path as a source is indexed by — separators normalized and a leading `./` dropped, so
+* `./a/b` and `a/b` name one source rather than two.
+*
+* Not exported. It is the grammar of the `configPath` field, and the question a caller has is
+* {@link sourceSlugFor}, which applies it. A caller normalizing paths itself is a second copy of this
+* rule, and the copies disagree the first time one forgets a case.
+*/
+const configPathKey = (value) => value.replace(/\\/g, "/").replace(/^\.\//, "");
+/**
+* The slug this config already draws a source under, or `undefined` when it doesn't draw it at all.
+*
+* Takes either way a source can be named, because the same system reached two ways is the same system:
+* a form offering to draw on one that is already a source should say so and name the slug it lives
+* under, rather than offering a second declaration under another name. Which fields those are is this
+* kind's to know ({@link LinkedSystem.sourceIdentity}); a caller that indexed them itself would be
+* restating the schema.
+*/
+function sourceSlugFor({ config, configPath, systemId }) {
+	if (!config) return void 0;
+	const wanted = configPath ? configPathKey(configPath) : void 0;
+	for (const entry of LinkedSystem.list(config)) {
+		if (wanted !== void 0 && entry.configPath !== void 0 && configPathKey(entry.configPath) === wanted) return entry.path;
+		if (systemId && entry.systemId === systemId) return entry.path;
+	}
+}
+/**
+* A system's name as a starting slug — lowercase, a single path segment as {@link LINK_SLUG} wants,
+* and not one this config has already taken.
+*
+* The suffix matters because the suggestion is applied on open and on every pick, before anyone has
+* typed: suggesting a slug that already exists greets you with a validation error you didn't cause and
+* a dead submit button. It is for two different systems whose names normalize to the same slug — the
+* same system declared twice is refused outright, by {@link sourceSlugFor}.
+*/
+function suggestLinkSlug({ name, taken }) {
+	const base = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+	if (!base) return "";
+	if (!isLinkSlug(base)) return "";
+	if (!taken.has(base)) return base;
+	for (let suffix = 2;; suffix++) {
+		const candidate = `${base}-${suffix}`;
+		if (!taken.has(candidate)) return candidate;
+	}
+}
+//#endregion
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };