@dtmd/temper 0.0.17 → 0.0.19

package/dist/src/kind.d.ts

@@ -137,6 +137,24 @@ export interface Layout {
  * {@link Layout}.
  */
 export type Shape = "fields";
+/**
+ * A kind's **leaf-set witness** — the leaf names a member of the kind carries, handed
+ * over by the kind's own typed surface `T` (decision 0053). The type is the declaration:
+ * nothing here is a second schema to keep in step with `T`, because the record's keys
+ * *are* `keyof T`. It exists at all because TypeScript erases `T` at the seam, so the
+ * set the compiler knows has to reach emit as a runtime value.
+ *
+ * The record is **exhaustive** — `-?` strips optionality, so omitting one key of `T` is a
+ * compile error and a key that is not `T`'s own is one too. That binding is what keeps
+ * the witness from degrading into the free-hand leaf schema the decision rejected: a
+ * partial set is unwritable rather than merely discouraged.
+ *
+ * Key order is the order the lowered row carries (`declarations.ts`), so a kind's leaves
+ * read in the order its author declared them.
+ */
+export type LeafSet<T extends object> = {
+    readonly [K in keyof T]-?: true;
+};
 /**
  * A registration member's **collection address** — where inside a host manifest its
  * registration surfaces: which `manifest` (`settings.json`, `.mcp.json`) and which
@@ -168,16 +186,38 @@ export interface Template {
     /** Where a file child's unit sits, relative to the parent's unit; absent for an embedded layer. */
     readonly path?: string;
 }
-/** The seven facts of a kind's runtime residue. */
-export interface KindFacts {
+/**
+ * The seven facts of a kind's runtime residue, plus the derived {@link LeafSet} witness
+ * its typed surface hands over. `T` is that surface — the interface the kind's
+ * constructor is generic over. It defaults to an erased `Record<string, unknown>`, so
+ * every signature that only ever *reads* a facts value (`declarations.ts`'s lowering,
+ * {@link Member}, {@link KindDefinition}) names `KindFacts` bare and no call site
+ * re-spells a type argument.
+ */
+export type KindFacts<T extends object = Record<string, unknown>> = {
     /** Fact 1, label — the compiled debug label findings speak; the kind's name. */
     readonly name: string;
     /** The declared provider authority, when the kind qualifies by one. */
     readonly provider?: string;
+    /**
+     * The built-in kind this facts value **relocates** — set only by {@link relocate},
+     * from the base kind's own name, never authored. It is the authoring layer's
+     * *provenance* fact: the value was derived from the imported built-in, so a
+     * second same-named kind in play is a sanctioned relocation rather than a name
+     * collision. It never reaches a kind-fact row — the lock reader holds no base
+     * value to compare against and re-decides *structurally* instead
+     * (`src/compose.rs`'s `row_relocates_builtin`).
+     */
+    readonly relocates?: string;
     /** Fact 2, locus — where members live, and for a file locus whether their documents
      * are committed: a `local` commitment class declares the kind reviewed and its
      * members' documents not. */
-    readonly locus: Locus;
+    readonly locus: {
+        readonly kind: "at";
+        readonly root: string;
+        readonly glob: string;
+        readonly commitment?: "local";
+    };
     /** Fact 3a, projection — the artifact format; omitted for a kind that declares none. */
     readonly format?: Format;
     /** Fact 3b, projection — the on-disk unit shape. */
@@ -186,15 +226,78 @@ export interface KindFacts {
      * the world reaches a member (never rivals — a member is live if any one is). */
     readonly registration: readonly Registration[];
     /**
-      * The frontmatter key the member's name writes under. For `unitShape:
-      * "named-field"` this is the id **source** — the declared field a member's
-      * identity is read from (an agent's `name`), never the filename or directory.
-      * For `"directory"` it is a projection-order detail only (a skill's `name`
-      * still writes into frontmatter, but identity is the directory name); absent
-      * when identity is the file stem and no field carries it (a rule), or the
-      * starred directory segment (`"starred-segment"`) — both path-derived, never a
-      * field.
-    */
+     * The frontmatter key the member's name writes under. For `unitShape:
+     * "named-field"` this is the id **source** — the declared field a member's
+     * identity is read from (an agent's `name`), never the filename or directory.
+     * For `"directory"` it is a projection-order detail only (a skill's `name`
+     * still writes into frontmatter, but identity is the directory name); absent
+     * when identity is the file stem and no field carries it (a rule), or the
+     * starred directory segment (`"starred-segment"`) — both path-derived, never a
+     * field.
+     */
+    readonly identityField?: string;
+    /** Fact 5, edge fields — the kind's fields that are references to other members. */
+    readonly edgeFields?: readonly EdgeField[];
+    /** Fact 6, content — a declared {@link Layout} over the body's heading tree; absent
+     * leaves the kind `file`-content (one verbatim prose body, the default). */
+    readonly content?: Layout;
+    /** Fact 6b, content — the fields-only body shape (`"fields"`, no body slot); absent
+     * leaves the kind body-bearing (`file` or a {@link Layout}). */
+    readonly shape?: Shape;
+    /** The registration member's {@link CollectionAddress} — which manifest and key path
+     * its registration surfaces at; absent for a kind that owns its own file locus. */
+    readonly collectionAddress?: CollectionAddress;
+    /** Fact 7, template — one {@link Template} per inner layer of nested members the kind
+     * hosts; absent for a kind that nests nothing. */
+    readonly templates?: readonly Template[];
+    /** The kind's **leaf set**, witnessed exhaustively over its own typed surface and
+     * lowered to the row's `leaves` column at emit ({@link LeafSet}, decision 0053) —
+     * what a read verb renders where the surface holds no member of the kind yet.
+     * Absent for a kind whose constructor declares no witness. */
+    readonly leaves?: LeafSet<T>;
+    /** Advisory authoring counsel for the kind as a whole — teaching at authoring time via
+     * `schema` hover or `explain`, carrying no predicate or severity (decision 0045). */
+    readonly guidance?: string;
+    /** External-fact source backing the guidance — a doc URL plus retrieved date,
+     * carried as data. */
+    readonly cite?: string;
+} | {
+    /** Fact 1, label — the compiled debug label findings speak; the kind's name. */
+    readonly name: string;
+    /** The declared provider authority, when the kind qualifies by one. */
+    readonly provider?: string;
+    /**
+     * The built-in kind this facts value **relocates** — set only by {@link relocate},
+     * from the base kind's own name, never authored. It is the authoring layer's
+     * *provenance* fact: the value was derived from the imported built-in, so a
+     * second same-named kind in play is a sanctioned relocation rather than a name
+     * collision. It never reaches a kind-fact row — the lock reader holds no base
+     * value to compare against and re-decides *structurally* instead
+     * (`src/compose.rs`'s `row_relocates_builtin`).
+     */
+    readonly relocates?: string;
+    /** Fact 2, locus — where members live, and for a file locus whether their documents
+     * are committed: a `local` commitment class declares the kind reviewed and its
+     * members' documents not. */
+    readonly locus: {
+        readonly kind: "embedded";
+    };
+    /** Fact 3a, projection — the artifact format; omitted for a kind that declares none. */
+    readonly format?: Format;
+    /** Fact 3b, projection — the on-disk unit shape. */
+    readonly unitShape: UnitShape;
+    /** Fact 4, registration — embedded members register nothing. */
+    readonly registration: readonly [];
+    /**
+     * The frontmatter key the member's name writes under. For `unitShape:
+     * "named-field"` this is the id **source** — the declared field a member's
+     * identity is read from (an agent's `name`), never the filename or directory.
+     * For `"directory"` it is a projection-order detail only (a skill's `name`
+     * still writes into frontmatter, but identity is the directory name); absent
+     * when identity is the file stem and no field carries it (a rule), or the
+     * starred directory segment (`"starred-segment"`) — both path-derived, never a
+     * field.
+     */
     readonly identityField?: string;
     /** Fact 5, edge fields — the kind's fields that are references to other members. */
     readonly edgeFields?: readonly EdgeField[];
@@ -210,13 +313,106 @@ export interface KindFacts {
     /** Fact 7, template — one {@link Template} per inner layer of nested members the kind
      * hosts; absent for a kind that nests nothing. */
     readonly templates?: readonly Template[];
+    /** The kind's **leaf set**, witnessed exhaustively over its own typed surface and
+     * lowered to the row's `leaves` column at emit ({@link LeafSet}, decision 0053) —
+     * what a read verb renders where the surface holds no member of the kind yet.
+     * Absent for a kind whose constructor declares no witness. */
+    readonly leaves?: LeafSet<T>;
     /** Advisory authoring counsel for the kind as a whole — teaching at authoring time via
      * `schema` hover or `explain`, carrying no predicate or severity (decision 0045). */
     readonly guidance?: string;
     /** External-fact source backing the guidance — a doc URL plus retrieved date,
      * carried as data. */
     readonly cite?: string;
+} | {
+    /** Fact 1, label — the compiled debug label findings speak; the kind's name. */
+    readonly name: string;
+    /** The declared provider authority, when the kind qualifies by one. */
+    readonly provider?: string;
+    /**
+     * The built-in kind this facts value **relocates** — set only by {@link relocate},
+     * from the base kind's own name, never authored. It is the authoring layer's
+     * *provenance* fact: the value was derived from the imported built-in, so a
+     * second same-named kind in play is a sanctioned relocation rather than a name
+     * collision. It never reaches a kind-fact row — the lock reader holds no base
+     * value to compare against and re-decides *structurally* instead
+     * (`src/compose.rs`'s `row_relocates_builtin`).
+     */
+    readonly relocates?: string;
+    /** Fact 2, locus — where members live, and for a file locus whether their documents
+     * are committed: a `local` commitment class declares the kind reviewed and its
+     * members' documents not. */
+    readonly locus: {
+        readonly kind: "nested-file";
+    };
+    /** Fact 3a, projection — the artifact format; omitted for a kind that declares none. */
+    readonly format?: Format;
+    /** Fact 3b, projection — the on-disk unit shape. */
+    readonly unitShape: UnitShape;
+    /** Fact 4, registration — nested-file members register nothing. */
+    readonly registration: readonly [];
+    /**
+     * The frontmatter key the member's name writes under. For `unitShape:
+     * "named-field"` this is the id **source** — the declared field a member's
+     * identity is read from (an agent's `name`), never the filename or directory.
+     * For `"directory"` it is a projection-order detail only (a skill's `name`
+     * still writes into frontmatter, but identity is the directory name); absent
+     * when identity is the file stem and no field carries it (a rule), or the
+     * starred directory segment (`"starred-segment"`) — both path-derived, never a
+     * field.
+     */
+    readonly identityField?: string;
+    /** Fact 5, edge fields — the kind's fields that are references to other members. */
+    readonly edgeFields?: readonly EdgeField[];
+    /** Fact 6, content — a declared {@link Layout} over the body's heading tree; absent
+     * leaves the kind `file`-content (one verbatim prose body, the default). */
+    readonly content?: Layout;
+    /** Fact 6b, content — the fields-only body shape (`"fields"`, no body slot); absent
+     * leaves the kind body-bearing (`file` or a {@link Layout}). */
+    readonly shape?: Shape;
+    /** The registration member's {@link CollectionAddress} — which manifest and key path
+     * its registration surfaces at; absent for a kind that owns its own file locus. */
+    readonly collectionAddress?: CollectionAddress;
+    /** Fact 7, template — one {@link Template} per inner layer of nested members the kind
+     * hosts; absent for a kind that nests nothing. */
+    readonly templates?: readonly Template[];
+    /** The kind's **leaf set**, witnessed exhaustively over its own typed surface and
+     * lowered to the row's `leaves` column at emit ({@link LeafSet}, decision 0053) —
+     * what a read verb renders where the surface holds no member of the kind yet.
+     * Absent for a kind whose constructor declares no witness. */
+    readonly leaves?: LeafSet<T>;
+    /** Advisory authoring counsel for the kind as a whole — teaching at authoring time via
+     * `schema` hover or `explain`, carrying no predicate or severity (decision 0045). */
+    readonly guidance?: string;
+    /** External-fact source backing the guidance — a doc URL plus retrieved date,
+     * carried as data. */
+    readonly cite?: string;
+};
+/**
+ * A **declared input** — a file the member's claims rest on, fingerprinted by the lock
+ * and moved nowhere (`specs/model/authoring.md`, "The SDK"). The path resolves against
+ * the stating module ({@link moduleUrl}), never the workspace — the same anchor
+ * `include()` and a `file()` body take.
+ *
+ * It lives here rather than beside the prose references it rhymes with: an input rides
+ * no text span and pairs with no body slot, so it is a member-grain framework key, not a
+ * word in a body. When the input's bytes move, the member's own freshness finding routes
+ * the author to re-verify the claims *before* re-emitting — temper never judges whether
+ * the claim still holds, only names the place to look.
+ */
+export interface Input {
+    readonly kind: "input";
+    /** Path to the input, resolved against {@link moduleUrl}. */
+    readonly path: string;
+    /** The declaring module's own `import.meta.url` — what {@link path} resolves against. */
+    readonly moduleUrl: string;
 }
+/**
+ * Declare a file a member's claims rest on — the lock fingerprints it and no byte
+ * reaches the projection. The path resolves against the stating module, so the call is
+ * `input(import.meta.url, "./schema.json")`.
+ */
+export declare function input(moduleUrl: string, path: string): Input;
 /**
  * One authored member — a typed value in the library. Kind identity travels by
  * import (`facts`), never by string; the
@@ -242,8 +438,27 @@ export interface Member {
     readonly requires: Readonly<Record<string, Requirement>>;
     /** The capabilities the member's behavior uses — the permission union's source. */
     readonly needs: readonly Capability[];
+    /** The files this member's claims rest on — fingerprinted, never moved. */
+    readonly inputs: readonly Input[];
 }
-/** The init a kind constructor takes — the framework keys plus the kind's typed fields `T`. */
+/**
+ * The bag a surface `T` declares its {@link RESIDUE_KEY} channel as — the keys `T` does
+ * *not* type, and only those. The two halves partition the format's key space, so a key
+ * in both is a mis-spelling rather than an override: open by key, then narrowed against
+ * `keyof T`, which leaves a typed key's slot here holding nothing a value can fill.
+ *
+ * The narrowing is the front door, never the whole gate — a bag the program computed
+ * arrives as a bare `Record<string, unknown>` and types fine, so the constructor refuses
+ * the collision again over the keys it actually holds ({@link orderedFields}).
+ */
+export type Residue<T> = Readonly<Record<string, unknown>> & {
+    readonly [K in keyof T]?: never;
+};
+/**
+ * The init a kind constructor takes — the framework keys plus the kind's typed fields `T`.
+ * {@link RESIDUE_KEY} is a framework key too, deliberately not spelled below: a kind opts
+ * into that channel through its own surface `T`.
+ */
 export type MemberInit<T> = {
     readonly name: string;
     /** The host member this member's unit composes under — a nested-file child's, and only its. */
@@ -252,6 +467,12 @@ export type MemberInit<T> = {
     readonly satisfies?: readonly string[];
     readonly requires?: Readonly<Record<string, Requirement>>;
     readonly needs?: readonly Capability[];
+    /**
+     * The files this member's claims rest on ({@link input}) — fingerprinted by the lock,
+     * with no byte reaching the projection. The surface binds a *member*: an embedded
+     * value takes no `MemberInit`, and its claims are its host's.
+     */
+    readonly inputs?: readonly Input[];
 } & T;
 /**
  * A kind — a callable constructor carrying its seven facts. Calling it builds a
@@ -283,8 +504,80 @@ export interface KindOptions {
  * into emit is the seven facts plus flat field data. `options.render`, when given,
  * rides alongside `facts`/`key` on the returned constructor — never on the member
  * it builds, since it is erased before a member reaches emit.
+ *
+ * The facts are typed over the same `T` the constructor is, which is what binds a
+ * declared {@link LeafSet} witness to `keyof T`: the leaf set is the kind's own surface,
+ * checked here at the keystroke, and its lowering to the row is the one place it is
+ * spelled again (`declarations.ts`).
+ */
+export declare function kind<T extends object>(facts: KindFacts<T>, options?: KindOptions): KindDefinition<T>;
+/**
+ * A **relocation delta** — the facts a relocated built-in kind diverges from its base
+ * on. Two faces, either or both:
+ *
+ * - `edgeFields`, *added* to whatever the base already declares (never replacing them,
+ *   which would drop a shipped kind's own edges silently). Each added field names a key
+ *   of the relocated kind's typed surface `T`, so an edge can never be declared over a
+ *   field the kind does not carry.
+ * - `governs`, *replacing* the base's `at` locus root and glob — moving where the kind's
+ *   members are found, the one fact the engine's own overlay exists to apply
+ *   (`src/compose.rs`'s `overlay_builtin_kind`).
+ *
+ * Every other fact — format, unit shape, registration, content, templates, the declared
+ * leaf set — rides through unchanged, which is exactly what makes the emitted row still
+ * read as a relocation rather than a name collision on the reading side.
+ */
+export interface KindRelocation<T> {
+    /** The edge fields this relocation adds, each over a field of the kind's own surface. */
+    readonly edgeFields?: readonly {
+        readonly field: keyof T & string;
+        readonly to: readonly [string, ...string[]];
+    }[];
+    /**
+     * The locus this relocation moves the kind's members to — root and glob, the two
+     * columns the lock reader's overlay writes back. A file locus's `commitment` class is
+     * deliberately absent: the overlay writes `Governs { root, glob }` and nothing else, so
+     * a `commitment` delta would author a fact the reader drops in silence — a built-in's
+     * commitment class stays the built-in's.
+     */
+    readonly governs?: {
+        readonly root: string;
+        readonly glob: string;
+    };
+}
+/**
+ * **Relocate** a built-in kind: the sanctioned way an adopting corpus moves a kind it
+ * does not own to its own root, adds an edge field to it, or both. Returns a fresh
+ * constructor over the widened typed surface `T` (the base's fields plus the added edge
+ * fields, spelled by the caller as one interface), carrying the base's facts with
+ * `delta`'s edge fields appended, `delta`'s `governs` in place of the base's locus root
+ * and glob, and the base's own {@link KindDefinition.render} hook preserved. Ownership,
+ * not privilege — a relocated built-in is an ordinary kind value from here on, and its
+ * added edge reaches the lock as an assembly `edge` row keyed by `from`, exactly as any
+ * kind's does (`declarations.ts`), never as a column on a kind-fact row.
+ *
+ * A moved locus, by contrast, *is* a kind-fact row column pair: the emitted row carries
+ * the delta's `governs_root`/`governs_glob` while `format`, `unit_shape` and
+ * `registration` stay the base's — which is precisely the three-fact test the lock
+ * reader applies before overlaying the row onto its compiled-in built-in
+ * (`src/compose.rs`'s `row_relocates_builtin`), so the engine reads members at the new
+ * root rather than treating the row as a colliding kind.
+ *
+ * The produced facts carry `relocates`, naming the base — the marker that tells a
+ * legitimate relocation from a genuine name collision when two same-named kinds are in
+ * play. Identity travels by import: the base is the imported built-in value, so the
+ * provenance is proven here rather than inferred downstream.
+ *
+ * # Throws
+ * If an added edge field re-declares one the base already carries, or one another
+ * entry of the same delta already added — two `edge` rows over one `<from, field>`
+ * cross-wire the graph instead of declaring one relationship. If a `governs` delta
+ * names a base whose locus is not `at` ({@link relocatedLocus}). And if the delta
+ * declares neither face, which would mint a marker-bearing clone of the base — a second
+ * same-named kind diverging on nothing, which is a name collision spelled as a
+ * relocation.
  */
-export declare function kind<T extends object>(facts: KindFacts, options?: KindOptions): KindDefinition<T>;
+export declare function relocate<T extends object>(base: KindDefinition<any>, delta: KindRelocation<T>): KindDefinition<T>;
 /**
  * One entry in a sibling collection: its own key plus its leaf fields
  * (`rejected."baked-projection"`) — an ordered list element, never a positional
@@ -390,8 +683,14 @@ export interface ResolvedEmbeddedMemberValue {
  * composed value's shape. A bare string names a kind whose facts are out of reach, so
  * such a value renders with no target facts.
  */
+export declare function embeddedMemberValue<T extends object>(init: {
+    kind: KindDefinition<T>;
+    key: string;
+    leaves: Readonly<Record<keyof T, string | Text>>;
+    collections?: EmbeddedMemberValue["collections"];
+}): EmbeddedMemberValue;
 export declare function embeddedMemberValue(init: {
-    kind: string | KindDefinition<any>;
+    kind: string;
     key: string;
     leaves: Readonly<Record<string, string | Text>>;
     collections?: EmbeddedMemberValue["collections"];

package/dist/src/kind.js

@@ -8,8 +8,43 @@
  * rows. Identity travels by import, never by string — a `kind` reference is the imported
  * value.
  */
+/**
+ * Declare a file a member's claims rest on — the lock fingerprints it and no byte
+ * reaches the projection. The path resolves against the stating module, so the call is
+ * `input(import.meta.url, "./schema.json")`.
+ */
+export function input(moduleUrl, path) {
+    return { kind: "input", path, moduleUrl };
+}
 /** The framework keys of a member init — everything else is a typed field (flat). */
-const FRAMEWORK_KEYS = new Set(["name", "host", "prose", "satisfies", "requires", "needs"]);
+const FRAMEWORK_KEYS = new Set(["name", "host", "prose", "satisfies", "requires", "needs", "inputs", "residue"]);
+/**
+ * The **reserved leaf key** a nested member's own span lands under (0051) —
+ * `<host-address>/<kind>/<key>/prose`. On the read half a layout collection member's
+ * own paragraph, the text under its heading before the first child heading, lands here
+ * (`src/layout.rs`'s `OWN_SPAN_LEAF`); leaves stay one family, so leaf predicates, leaf
+ * addresses and `explain`'s narration range over one source.
+ *
+ * `prose` is already this word at member grain ({@link MemberInit.prose}), so it is a
+ * framework key for an init and a reserved name for a leaf — the same thing spelled once.
+ * The composed half authors no own span (its leaves are all author-named), so the
+ * reservation binds here as a refusal: a composed leaf of this name would address
+ * identically to a read member's own span and mean something else.
+ */
+const RESERVED_LEAF = "prose";
+/**
+ * The **residue key** — the channel a partially-governed external format's undocumented
+ * keys ride under. A kind whose schema is large and version-evolving types what it
+ * governs and leaves the remainder opaque and *named* rather than indicted; `residue` is
+ * that name, spliced flat into the projected fields by {@link orderedFields}.
+ *
+ * Like {@link RESERVED_LEAF}, this is a name the framework owns — a kind whose external
+ * format documents a top-level key of it cannot spell that key as an ordinary field. The
+ * reservation is kindless, but the channel is opt-in by **type**: only a surface `T`
+ * declaring `residue?` can spell the bag, so a closed-frontmatter kind (a skill, a rule,
+ * an agent) keeps refusing it by excess-property check like any other unknown key.
+ */
+const RESIDUE_KEY = "residue";
 /**
  * Build the ordered projected fields for a member: nothing for a frontmatterless
  * body-bearing kind (memory declares no `format` and is not fields-only), else the
@@ -17,6 +52,9 @@ const FRAMEWORK_KEYS = new Set(["name", "host", "prose", "satisfies", "requires"
  * typed fields in the author's declared order. A fields-only registration kind (a
  * hook, an MCP server) carries its typed fields though it declares no `format` —
  * the fields are the whole member, folded into a manifest entry, never a header.
+ *
+ * A {@link RESIDUE_KEY} bag splices in last: what the program types, it orders; what it
+ * merely carries, it sorts.
  */
 function orderedFields(facts, init) {
     if (facts.format === undefined && facts.shape !== "fields")
@@ -27,7 +65,41 @@ function orderedFields(facts, init) {
             typed.push([key, value]);
     }
     const head = facts.identityField !== undefined ? [[facts.identityField, init.name]] : [];
-    return [...head, ...typed];
+    const projected = [...head, ...typed];
+    return [...projected, ...residueFields(facts, init, projected)];
+}
+/**
+ * The init's residue bag as projected fields, key-sorted and disjoint from what the
+ * member already projects. The bag is a record, so it carries no authored order to
+ * preserve — sorting is what makes the projection a function of the keys alone, the same
+ * stability the harness-level residue rows already take (`declarations.ts`'s
+ * `settingsRows`).
+ *
+ * # Throws
+ * If a residue key is one `projected` already carries. The bag holds what the surface
+ * does not type, so a key in both is a mis-spelling, not an override — and a silent one
+ * downstream, since the engine's writer collects the field list into a map and the
+ * residue pair, spliced last, would take the typed value's place.
+ */
+function residueFields(facts, init, projected) {
+    const residue = init[RESIDUE_KEY];
+    if (residue === undefined)
+        return [];
+    const already = new Set(projected.map(([key]) => key));
+    const fields = [];
+    // Default `sort()` is UTF-16 code-unit order — the same total order `compareStrings`
+    // gives every declaration family, reached without importing `declarations.ts` (which
+    // imports `builtins.ts`, which imports this module).
+    for (const key of Object.keys(residue).sort()) {
+        if (already.has(key)) {
+            throw new Error(`member \`${init.name}\` of kind \`${facts.name}\`: \`${RESIDUE_KEY}\` key \`${key}\` is ` +
+                `already a field this member projects — the bag carries the keys the kind's surface ` +
+                `does not type, so spell this one as the field it is ` +
+                `(specs/builtins.md, "The shipped kinds").`);
+        }
+        fields.push([key, residue[key]]);
+    }
+    return fields;
 }
 /**
  * The host a member init names, checked against its kind's locus: a nested-file child's
@@ -56,6 +128,11 @@ function hostOf(facts, init) {
  * into emit is the seven facts plus flat field data. `options.render`, when given,
  * rides alongside `facts`/`key` on the returned constructor — never on the member
  * it builds, since it is erased before a member reaches emit.
+ *
+ * The facts are typed over the same `T` the constructor is, which is what binds a
+ * declared {@link LeafSet} witness to `keyof T`: the leaf set is the kind's own surface,
+ * checked here at the keystroke, and its lowering to the row is the one place it is
+ * spelled again (`declarations.ts`).
  */
 export function kind(facts, options = {}) {
     const construct = (init) => ({
@@ -68,23 +145,106 @@ export function kind(facts, options = {}) {
         satisfies: init.satisfies ?? [],
         requires: init.requires ?? {},
         needs: init.needs ?? [],
+        inputs: init.inputs ?? [],
     });
     return Object.assign(construct, { facts, key: facts.name, render: options.render });
 }
 /**
- * Compose an embedded member's value for `blocks()` — the shape any project's own
- * child kind uses. `kind` names the child kind: a bare string, or the child kind's
- * own `KindDefinition` — passing the definition carries its `render` hook and its
- * declared edge fields (when declared) through to emit, with no other change to the
- * composed value's shape. A bare string names a kind whose facts are out of reach, so
- * such a value renders with no target facts.
+ * The locus a `governs` delta moves the base to: the base's `at` root and glob replaced,
+ * every other locus fact (its commitment class among them) riding through.
+ *
+ * # Throws
+ * If the base's locus is not `at` — an embedded or nested-file kind governs no glob at
+ * all (its members compose their paths from a host's unit, or own no file), so there is
+ * no locus to move and its row carries no `governs` columns to move it to.
+ */
+function relocatedLocus(base, governs) {
+    if (base.locus.kind !== "at") {
+        throw new Error(`relocating kind \`${base.name}\`: a \`governs\` delta moves the ` +
+            `path glob a kind's members are found at, and this kind's locus is \`${base.locus.kind}\` ` +
+            `— it governs no glob of its own. Drop the \`governs\` face of the delta ` +
+            `(specs/model/representation.md, "locus").`);
+    }
+    return { ...base.locus, root: governs.root, glob: governs.glob };
+}
+/**
+ * **Relocate** a built-in kind: the sanctioned way an adopting corpus moves a kind it
+ * does not own to its own root, adds an edge field to it, or both. Returns a fresh
+ * constructor over the widened typed surface `T` (the base's fields plus the added edge
+ * fields, spelled by the caller as one interface), carrying the base's facts with
+ * `delta`'s edge fields appended, `delta`'s `governs` in place of the base's locus root
+ * and glob, and the base's own {@link KindDefinition.render} hook preserved. Ownership,
+ * not privilege — a relocated built-in is an ordinary kind value from here on, and its
+ * added edge reaches the lock as an assembly `edge` row keyed by `from`, exactly as any
+ * kind's does (`declarations.ts`), never as a column on a kind-fact row.
+ *
+ * A moved locus, by contrast, *is* a kind-fact row column pair: the emitted row carries
+ * the delta's `governs_root`/`governs_glob` while `format`, `unit_shape` and
+ * `registration` stay the base's — which is precisely the three-fact test the lock
+ * reader applies before overlaying the row onto its compiled-in built-in
+ * (`src/compose.rs`'s `row_relocates_builtin`), so the engine reads members at the new
+ * root rather than treating the row as a colliding kind.
+ *
+ * The produced facts carry `relocates`, naming the base — the marker that tells a
+ * legitimate relocation from a genuine name collision when two same-named kinds are in
+ * play. Identity travels by import: the base is the imported built-in value, so the
+ * provenance is proven here rather than inferred downstream.
+ *
+ * # Throws
+ * If an added edge field re-declares one the base already carries, or one another
+ * entry of the same delta already added — two `edge` rows over one `<from, field>`
+ * cross-wire the graph instead of declaring one relationship. If a `governs` delta
+ * names a base whose locus is not `at` ({@link relocatedLocus}). And if the delta
+ * declares neither face, which would mint a marker-bearing clone of the base — a second
+ * same-named kind diverging on nothing, which is a name collision spelled as a
+ * relocation.
  */
+export function relocate(base, delta) {
+    const declaredEdges = delta.edgeFields ?? [];
+    if (declaredEdges.length === 0 && delta.governs === undefined) {
+        throw new Error(`relocating kind \`${base.facts.name}\`: a relocation declares at least one diverging ` +
+            `fact — \`edgeFields\`, \`governs\`, or both. A delta declaring neither mints a ` +
+            `second kind of the base's own name that diverges on nothing, which reads as a name ` +
+            `collision rather than a relocation (specs/model/representation.md, "kind").`);
+    }
+    const locus = delta.governs === undefined ? undefined : relocatedLocus(base.facts, delta.governs);
+    const inherited = base.facts.edgeFields ?? [];
+    const claimed = new Set(inherited.map((edge) => edge.field));
+    const added = [];
+    for (const edge of declaredEdges) {
+        if (claimed.has(edge.field)) {
+            throw new Error(`relocating kind \`${base.facts.name}\`: edge field \`${edge.field}\` is already ` +
+                `declared, and a second declaration of one field cross-wires the graph rather than ` +
+                `adding a relationship (specs/model/representation.md, "kind").`);
+        }
+        claimed.add(edge.field);
+        added.push({ field: edge.field, to: edge.to });
+    }
+    const edgeFields = [...inherited, ...added];
+    const relocated = { ...base.facts, relocates: base.facts.name, edgeFields };
+    // Two spellings, not one with an optional `locus`: `KindFacts` is a union discriminated
+    // on the locus, so the moved case must carry the `at` locus as its own literal branch.
+    const facts = locus === undefined ? relocated : { ...relocated, locus };
+    // The base's leaf-set witness rides through as data, and the assertion is that
+    // pass-through spelled: a relocation appends *edge fields* over the kind's own surface,
+    // never a leaf, so the set the base's own constructor already bound still names what a
+    // member carries. `T` here is the widened surface (the base's fields plus the added
+    // edges), so re-binding the witness to `keyof T` would demand the edge fields be leaves.
+    return kind(facts, { render: base.render });
+}
 export function embeddedMemberValue(init) {
     const definition = typeof init.kind === "string" ? undefined : init.kind;
+    const kindKey = definition?.key ?? init.kind;
+    refuseReservedLeaf(kindKey, init.key, init.leaves);
+    for (const [collection, entries] of Object.entries(init.collections ?? {})) {
+        for (const entry of entries) {
+            refuseReservedLeaf(kindKey, `${init.key}.${collection}.${entry.key}`, entry.leaves);
+        }
+    }
     const render = definition?.render;
     const edgeFields = definition?.facts.edgeFields;
     return {
-        kind: definition?.key ?? init.kind,
+        kind: kindKey,
         key: init.key,
         leaves: init.leaves,
         collections: init.collections ?? {},
@@ -92,3 +252,18 @@ export function embeddedMemberValue(init) {
         ...(edgeFields !== undefined ? { edgeFields } : {}),
     };
 }
+/**
+ * Refuse a composed leaf named {@link RESERVED_LEAF} — the key a read member's own span
+ * owns, so a second meaning under it is a coincident leaf address, refused at compose
+ * rather than resolved by precedence (0051). Loud at the authoring seam, where the author
+ * can rename the field, not at emit over bytes already written.
+ *
+ * # Throws
+ * If `leaves` carries the reserved key.
+ */
+function refuseReservedLeaf(kind, key, leaves) {
+    if (!Object.hasOwn(leaves, RESERVED_LEAF))
+        return;
+    throw new Error(`embedded member \`${kind}\` \`${key}\`: leaf \`${RESERVED_LEAF}\` is reserved for a ` +
+        `member's own span — rename the field, or author the words as the member's prose`);
+}