@yahoo/uds-create-config 2.44.0 → 3.0.0

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

@@ -0,0 +1,46 @@
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/Icon.d.ts
+/**
+ * Icon (`icons/AcornIcon`) — one glyph in an icon library. The library (`icons`) is an EMERGENT group
+ * from the path, and everything that describes the SET lives on that group node: its version, the
+ * sizes and variants it ships, the component a placed icon renders through, and where the members'
+ * descriptive facts come from (`metadata`).
+ *
+ * A member's identity is still its name; its fields carry what the name can't say. A group that
+ * declares `metadata` gets those fields baked at BUILD time from the declared source, and the bake
+ * fills only fields with no stored value — an author's hand-written value is never overwritten
+ * (every such skip is logged by the build), and a curator's Studio edit is a patch that replays on
+ * top of the base regardless. Fields are re-derived every build, so a source removing facts flows
+ * through at the next dependency bump rather than lingering.
+ *
+ * (A per-icon type/variant is config-v2 model gap 8; this is where it lands.)
+ */
+declare const Icon: EntityClass<z.ZodObject<{
+  categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  codepoint: z.ZodOptional<z.ZodNumber>;
+  knockoutVariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+  module: z.ZodOptional<z.ZodString>;
+  version: z.ZodOptional<z.ZodString>;
+  metadata: z.ZodOptional<z.ZodObject<{
+    from: EntityClass<z.ZodObject<{
+      version: z.ZodOptional<z.ZodString>;
+      exports: z.ZodOptional<SubEntityClass<z.ZodObject<{}, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "package", Record<never, never>, Record<never, never>, false>;
+    format: z.ZodEnum<{
+      uds: "uds";
+      phosphor: "phosphor";
+    }>;
+  }, z.core.$strict>>;
+  sizes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+  variants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  component: z.ZodOptional<z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strict>, "icon", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Icon };

package/dist/entities/system/Icon.js

@@ -0,0 +1,46 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { Component } from "./Component.js";
+import { iconMemberMetadata, iconMetadataDeclaration } from "./icon-metadata.js";
+import { z } from "zod";
+//#region src/entities/system/Icon.ts
+/**
+* Icon (`icons/AcornIcon`) — one glyph in an icon library. The library (`icons`) is an EMERGENT group
+* from the path, and everything that describes the SET lives on that group node: its version, the
+* sizes and variants it ships, the component a placed icon renders through, and where the members'
+* descriptive facts come from (`metadata`).
+*
+* A member's identity is still its name; its fields carry what the name can't say. A group that
+* declares `metadata` gets those fields baked at BUILD time from the declared source, and the bake
+* fills only fields with no stored value — an author's hand-written value is never overwritten
+* (every such skip is logged by the build), and a curator's Studio edit is a patch that replays on
+* top of the base regardless. Fields are re-derived every build, so a source removing facts flows
+* through at the next dependency bump rather than lingering.
+*
+* (A per-icon type/variant is config-v2 model gap 8; this is where it lands.)
+*/
+const Icon = defineEntity({
+	kind: "icon",
+	label: "Icon",
+	labelPlural: "Icons",
+	fields: iconMemberMetadata,
+	groupFields: z.strictObject({
+		/** The package the glyphs come from. Declared here rather than recovered by scanning source for
+		*  a namespace import used inside a `.group(…)` call, which is what `assetModules` does today —
+		*  and what a generated module needs, since it has to import the glyph it renders. The same
+		*  field a `Package` group carries, for the same reason. */
+		module: z.string().optional(),
+		version: z.string().optional(),
+		/** Where member metadata comes from and how to read it — `{ from, format }`. The build resolves
+		*  the source and bakes each member's fields; see `icon-metadata.ts`. */
+		metadata: iconMetadataDeclaration.optional(),
+		/** Named sizes the set ships (`sm: 16`). */
+		sizes: z.record(z.string(), z.number()).optional(),
+		/** Weights/styles the set ships (`regular`, `fill`). */
+		variants: z.array(z.string()).optional(),
+		/** The component a placed icon renders through — a REF, so the graph sees the edge and a
+		*  rename of that component cascades into this library. */
+		component: Component.optional()
+	})
+});
+//#endregion
+export { Icon };

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

@@ -0,0 +1,504 @@
+import { CopyPlan } from "./copy-plan.js";
+import { RegisteredEntities } from "../../framework/registered.js";
+import { SourceResolver, SourceState } from "../../framework/sources.js";
+import { EntityClass, ItemOf } from "../../framework/defineEntity.js";
+import { PartialBodyOf } from "../../framework/defineConfig.js";
+import { BreakPlan, LinkPlan, SourceRowState, UnlinkPlan } from "./link-plan.js";
+import { Config } from "../../framework/Config.js";
+import { ComputedInput } from "../../framework/registry.js";
+import { z } from "zod";
+
+//#region src/entities/system/LinkedSystem.d.ts
+/**
+ * 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.
+ */
+declare const LINK_SLUG: RegExp;
+/** 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. */
+declare function isLinkSlug(slug: string): boolean;
+/** What a refused slug should say, in one place, so the install and a form word it identically. */
+declare const LINK_SLUG_MESSAGE = "A link's slug is a single path segment \u2014 letters, digits, dot, dash and underscore \u2014 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.
+ */
+declare const resolvedSource: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  from: z.ZodLiteral<"disk">;
+  configPath: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  from: z.ZodLiteral<"registry">;
+  systemId: z.ZodString;
+  version: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  from: z.ZodLiteral<"storage">;
+  systemId: z.ZodString;
+  version: z.ZodString;
+}, z.core.$strip>], "from">;
+type ResolvedSource = z.infer<typeof resolvedSource>;
+/**
+ * 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.
+ */
+declare const sourceUnavailable: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  code: z.ZodLiteral<"not-installed">;
+}, z.core.$strip>, z.ZodObject<{
+  code: z.ZodLiteral<"unbuilt">;
+  configPath: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  code: z.ZodLiteral<"stale">;
+  installed: z.ZodString;
+  pinned: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  code: z.ZodLiteral<"not-found">;
+}, z.core.$strip>, z.ZodObject<{
+  code: z.ZodLiteral<"unmaterializable">;
+}, z.core.$strip>, z.ZodObject<{
+  code: z.ZodLiteral<"unreachable">;
+}, z.core.$strip>], "code">;
+type SourceUnavailable = z.infer<typeof sourceUnavailable>;
+/** A `link` or `unlink` example: one entity the source offers, under the accessor this config files it by. */
+declare function linkExample({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): Record<string, unknown> | undefined;
+/** An example for an op that takes the pin alone, shown once the pin has a source to read. */
+declare function pinExample({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): Record<string, unknown> | undefined;
+/** A break's example, shown once the pin has a source to read. */
+declare function breakExample({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): Record<string, unknown> | undefined;
+/** A copy's example: one entity the source offers, under the accessor this config files it by. */
+declare function copyExample({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): Record<string, unknown> | undefined;
+/**
+ * The bridging cast, and the annotation that survives declaration emit.
+ *
+ * Spelled as a named type because the emitted `.d.ts` is where this has to hold: a structural type
+ * here is printed expanded, and {@link RegisteredEntities} is empty in this package, so the field
+ * would reach every consumer already resolved against no accessors at all — augmenting it downstream
+ * would then change nothing.
+ */
+type PinOptionsField = z.ZodOptional<z.ZodType<PinOptions, PinOptions>>;
+declare const LinkedSystem: EntityClass<z.ZodObject<{
+  configPath: z.ZodOptional<z.ZodString>;
+  link: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>>;
+  options: PinOptionsField;
+  package: z.ZodOptional<z.ZodString>;
+  systemId: z.ZodOptional<z.ZodString>;
+  name: z.ZodOptional<z.ZodString>;
+  version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "linked-system", {
+  /**
+   * 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.
+   */
+  readonly link: {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>;
+    }, z.core.$strip>;
+    readonly readOnly: false;
+    readonly label: "Link from";
+    readonly 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`.";
+    readonly scope: "item";
+    readonly approval: "reference-change";
+    readonly title: (entity: string) => string;
+    readonly example: typeof linkExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Config;
+  };
+  readonly 'link-plan': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>;
+    }, z.core.$strip>;
+    readonly readOnly: true;
+    readonly label: "Plan a link";
+    readonly 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.";
+    readonly scope: "item";
+    readonly title: (entity: string) => string;
+    readonly example: typeof linkExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Omit<LinkPlan, "patches">;
+  };
+  /**
+   * 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.
+   */
+  readonly unlink: {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>>;
+    }, z.core.$strip>;
+    readonly readOnly: false;
+    readonly label: "Unlink from";
+    readonly 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.";
+    readonly scope: "item";
+    readonly approval: "reference-change";
+    readonly title: (entity: string) => string;
+    readonly example: typeof pinExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Config;
+  };
+  readonly 'unlink-plan': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>>;
+    }, z.core.$strip>;
+    readonly readOnly: true;
+    readonly label: "Plan an unlink";
+    readonly 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.";
+    readonly scope: "item";
+    readonly title: (entity: string) => string;
+    readonly example: typeof pinExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Omit<UnlinkPlan, "patches">;
+  };
+  /**
+   * Break the link: the pin goes, and everything drawn through it either becomes this config's own
+   * or goes with it.
+   */
+  readonly break: {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      keep: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly readOnly: false;
+    readonly label: "Break link";
+    readonly 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.";
+    readonly scope: "item";
+    readonly approval: "destructive";
+    readonly title: (entity: string) => string;
+    readonly example: typeof breakExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Config;
+  };
+  readonly 'break-plan': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      keep: z.ZodOptional<z.ZodBoolean>;
+      data: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>>;
+    }, z.core.$strip>;
+    readonly readOnly: true;
+    readonly label: "Plan a break";
+    readonly 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.";
+    readonly scope: "item";
+    readonly title: (entity: string) => string;
+    readonly example: typeof breakExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Omit<BreakPlan, "patches">;
+  };
+  /**
+   * 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.
+   */
+  readonly rows: {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+    }, z.core.$strip>;
+    readonly readOnly: true;
+    readonly label: "Source rows";
+    readonly 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.";
+    readonly scope: "item";
+    readonly title: (entity: string) => string;
+    readonly example: typeof pinExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => SourceRowState[];
+  };
+  /**
+   * 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.
+   */
+  readonly copy: {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>;
+      onConflict: z.ZodOptional<z.ZodEnum<{
+        replace: "replace";
+        skip: "skip";
+      }>>;
+    }, z.core.$strip>;
+    readonly readOnly: false;
+    readonly label: "Copy from";
+    readonly 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`.";
+    readonly scope: "item";
+    readonly approval: "reference-change";
+    readonly title: (entity: string) => string;
+    readonly example: typeof copyExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Config;
+  };
+  /**
+   * 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.
+   */
+  readonly 'copy-plan': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>]>;
+      onConflict: z.ZodOptional<z.ZodEnum<{
+        replace: "replace";
+        skip: "skip";
+      }>>;
+    }, z.core.$strip>;
+    readonly readOnly: true;
+    readonly label: "Plan a copy";
+    readonly 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.";
+    readonly scope: "item";
+    readonly title: (entity: string) => string;
+    readonly example: typeof copyExample;
+    readonly handler: (input: Record<string, unknown>, config: Config) => Omit<CopyPlan, "patches">;
+  };
+}, {
+  /**
+   * 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`.
+   */
+  readonly displayName: ({
+    member,
+    path
+  }: ComputedInput) => string;
+}, false>;
+/**
+ * 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.
+ *
+ * Each entry names a verb. The two bodies are partial at every depth because that is what an overlay
+ * is: `override: { overrides: { dark: … } }` says one conditional
+ * value and nothing about the rest of the token.
+ *
+ * **Which kind an accessor addresses comes from the emitted `uds-env.d.ts`**, through
+ * {@link RegisteredEntities}. It cannot come from the schema: this kind is a member of the entity map
+ * whose accessors key `options`, so naming that map here would be a type referencing itself. It
+ * cannot come from `register` either — the contextual type there is a union with an index signature
+ * in it, which switches excess-property checking off, so a misspelled field types clean.
+ *
+ * So the same route {@link RegisteredPaths} takes: the build knows the answer and writes it down.
+ * A config that has built gets `override: { modifers: … }` refused against the token schema; one that
+ * has not keeps the open record the schema describes and still compiles.
+ *
+ * The paths are still `string`. A source's catalogue lives in its installed artifact, so typing those
+ * needs a declaration per source — see the source-model doc.
+ */
+type PinOptions = { [A in keyof RegisteredEntities]?: Record<string, PinAdjustment<RegisteredEntities[A]>> };
+/** The pin's `link` field as stored — see the field's own doc. */
+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?: PartialBodyOf<E>;
+  extend?: PartialBodyOf<E>;
+  hidden?: boolean;
+};
+/**
+ * One `options` entry as stored — what this config does to that path, with the two bodies left open.
+ *
+ * Also what {@link PinOptions} falls back to before a build has written {@link RegisteredEntities}:
+ * the same entry, with nothing to check the bodies against yet.
+ */
+interface PinDirective {
+  readonly override?: Record<string, unknown>;
+  readonly extend?: Record<string, unknown>;
+  readonly hidden?: boolean;
+}
+/** One declared source, typed off this kind's own schema — what the readers below hand back. */
+type Source = ItemOf<typeof LinkedSystem>;
+/**
+ * A linked system's state as `Config.sourceStates()` reports it, narrowed to this kind's vocabulary.
+ *
+ * `Config` spans every source kind a config declares, so it can only type the payloads as `unknown`;
+ * only the kind knows them. This is that knowledge, named once so no surface restates the union or
+ * casts its way to it. Pick states out of `config.sourceStates()` by their `source` accessor name, then read
+ * them as this.
+ */
+type LinkedSystemState = SourceState<ResolvedSource, SourceUnavailable>;
+/**
+ * The resolver `Config.load` wants for `linkedSystems`, typed both ways: handed a {@link Source}, and
+ * held to this kind's own two payloads.
+ *
+ * The build's disk resolver and Studio's storage resolver both implement this, which is what makes them
+ * answer in one vocabulary rather than two that agree by convention.
+ */
+type LinkedSystemResolver = SourceResolver<Source, ResolvedSource, SourceUnavailable>;
+/**
+ * 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.
+ */
+declare function sourceOfItem({
+  config,
+  kind,
+  path
+}: {
+  config: Config;
+  kind: string;
+  path: string;
+}): Source | undefined;
+/**
+ * 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.
+ */
+declare function sourceOfGroup({
+  config,
+  kind,
+  groupPath
+}: {
+  config: Config;
+  kind: string;
+  groupPath: string;
+}): Source | undefined;
+/**
+ * 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`.
+ */
+declare function borrowedItem({
+  config,
+  kind,
+  path
+}: {
+  config: Config;
+  kind: string;
+  path: string;
+}): Source | undefined;
+/** 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. */
+declare function borrowedGroup({
+  config,
+  kind,
+  groupPath
+}: {
+  config: Config;
+  kind: string;
+  groupPath: string;
+}): Source | undefined;
+/**
+ * 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.
+ */
+declare function sourceSlugFor({
+  config,
+  configPath,
+  systemId
+}: {
+  config: Config | null | undefined;
+  configPath?: string | null;
+  systemId?: string | null;
+}): string | undefined;
+/**
+ * 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}.
+ */
+declare function suggestLinkSlug({
+  name,
+  taken
+}: {
+  name: string;
+  taken: ReadonlySet<string>;
+}): string;
+//#endregion
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkedSystem, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, ResolvedSource, Source, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };