@dtmd/temper 0.0.17 → 0.0.19

package/dist/src/declarations.js

@@ -9,8 +9,10 @@
  * in lockstep.
  */
 import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
 import { isTextSpan, resolveLeaf } from "./prose.js";
 import { SETTINGS_MANIFEST, TELEMETRY_EVENT_HOOKS, hook, tapHookRegistration } from "./builtins.js";
+import { hostAddress, leafAddress, nestedAddress } from "./member-address.js";
 /**
  * Compile one `Clause` into its lock row: the shared `key`/`field`/`severity`/
  * `guidance`/`cite` columns — the clause's four channels surviving erasure
@@ -60,20 +62,31 @@ function clauseRow(clause, kind) {
     return {
         kind,
         predicate: predicate.key,
-        field: predicate.field,
+        field: clauseField(predicate),
         severity: clause.severity,
         guidance: clause.guidance,
         cite: clause.cite,
         count: predicate.key === "count"
             ? { min: predicate.args?.min ?? 0, max: predicate.args?.max ?? Number.MAX_SAFE_INTEGER }
             : undefined,
-        target: predicate.key === "membership" ? predicate.target : undefined,
+        // The requirement-name column `membership`'s allowed-value target and
+        // `reached-from`'s closure roots share — one naming scheme for "the requirement
+        // whose satisfiers this clause reads" (`src/contract.rs` `predicate_from_row`).
+        target: predicate.key === "membership" || predicate.key === "reached-from"
+            ? predicate.target
+            : undefined,
         degree: predicate.key === "degree"
             ? {
                 incoming: edgeBoundArgs(predicate.args, "incoming"),
                 outgoing: edgeBoundArgs(predicate.args, "outgoing"),
             }
             : undefined,
+        // The by-incidence field set rides its own shared column, not the direction-only
+        // `degree` bound — the slot `reached-from`'s via set joins it. Copied into a
+        // fresh array: the predicate's set is read-only, the row's column is not.
+        fields: (predicate.key === "degree" || predicate.key === "reached-from") && predicate.fields
+            ? [...predicate.fields]
+            : undefined,
         gate: predicate.key === "mention-reachable" ? predicate.gate : undefined,
         value_type: predicate.key === "type" && predicate.value_type ? [...predicate.value_type] : undefined,
         shape: predicate.key === "shape" ? predicate.shape : undefined,
@@ -103,6 +116,57 @@ function clauseRow(clause, kind) {
             : undefined,
     };
 }
+/**
+ * The `field` column for one predicate: the field it names, or — for the four
+ * predicates that name a *section*, a field *set*, or a *requirement* rather than a
+ * field — an identity synthesized from the arguments the row already carries.
+ *
+ * `section_contains`, `require_sections`, `degree` and `reached-from` set no `field`,
+ * and the column is what emit stamps a clause's label from (`stamp_clause_label`,
+ * `src/drift.rs`), so reading `Predicate.field` folds every clause of one of those
+ * predicates on one kind into one label — two rows wearing one label, which
+ * admissibility refuses as a malformed lock. Synthesizing here keeps the whole fix at
+ * the lowering: the Rust reader reconstructs all four predicates from the
+ * `section`/`sections`/`fields`/`target` columns and never from this one, so nothing
+ * round-trips through the synthesized text.
+ */
+function clauseField(predicate) {
+    if (predicate.key === "section_contains") {
+        const { section } = predicate;
+        return section === undefined ? undefined : `${section.heading}.${section.marker}`;
+    }
+    if (predicate.key === "require_sections") {
+        // Joined with `+` rather than the label's own `.`, so the segment reads as the
+        // set it is and two different heading lists cannot fold to one label.
+        return predicate.sections?.join("+");
+    }
+    if (predicate.key === "degree") {
+        // A `degree` clause names no field of its own: its by-incidence filter is what
+        // distinguishes two bounds on one kind, so the filter is the segment — sorted and
+        // `+`-joined by the rule directly above, so two field lists spelling one set land
+        // one address and two different sets never fold to one. An unfiltered bound adds
+        // no segment: it ranges over every edge at the member, so two of them on one kind
+        // are a redundancy the author collapses, never a distinction an address must hold.
+        return predicate.fields === undefined ? undefined : [...predicate.fields].sort().join("+");
+    }
+    if (predicate.key === "reached-from") {
+        // A `reached-from` clause names no field either: its identity is the pair it walks.
+        // The roots requirement leads, and a declared via set follows after a `.` — the
+        // two-argument `section_contains` precedent — sorted and `+`-joined by `degree`'s
+        // rule directly above. So two closures rooted at one requirement over different
+        // arcs land two addresses instead of folding into one, and two spellings of one via
+        // set land one. An unfiltered closure adds no second segment: the roots are its
+        // whole identity, and two of them on one kind are a redundancy the author
+        // collapses.
+        const { target } = predicate;
+        if (target === undefined)
+            return undefined;
+        return predicate.fields === undefined
+            ? target
+            : `${target}.${[...predicate.fields].sort().join("+")}`;
+    }
+    return predicate.field;
+}
 /** `min_len`/`max_len`/`extent`'s scalar bound off their shared `min`/`max`
  * args keys — `undefined` for every other predicate, and for these three when
  * neither endpoint is present. */
@@ -240,6 +304,16 @@ function collectionAddressRow(facts) {
         entry_shape: facts.collectionAddress.entryShape,
     };
 }
+/**
+ * Lower a kind's exhaustive leaf-set witness into the row's `leaves` column: the
+ * witness's own keys, in the order its author declared them (`kind.ts`'s `LeafSet`,
+ * decision 0053 — the type is the declaration, and TypeScript erases it, so the record is
+ * how the corpus hands the key set over). `undefined` for a kind declaring no witness, so
+ * its row omits the column.
+ */
+function leafSetRow(leaves) {
+    return leaves === undefined ? undefined : Object.keys(leaves);
+}
 /**
  * One kind's fact row — an `at` locus supplies `governs_root`/`governs_glob` and any
  * other locus neither (a nested-file kind's path composes from its host's unit and the
@@ -247,7 +321,8 @@ function collectionAddressRow(facts) {
  * A file locus's `commitment` class rides the same spelling, absent for the committed
  * default. `templates` names the embedded kinds the corpus admits over it, and `content`
  * lowers a declared layout (absent for a `file`-content kind). A registration kind
- * extends the row with its `shape` marker and `collection_address`. Advisory
+ * extends the row with its `shape` marker and `collection_address`. A declared leaf-set
+ * witness lowers to `leaves` ([`leafSetRow`]), absent for a kind declaring none. Advisory
  * `guidance`/`cite` pair rides alongside, locus-optional so an embedded kind's own
  * counsel reaches the lock the same way a nested-file kind's already does (decision
  * 0045) — callable for any locus; [`kindFactKindsInPlay`] decides which embedded kinds
@@ -267,11 +342,95 @@ function kindFactRow(facts, admissions) {
         templates: templatesFor(facts, admissions),
         content: contentRow(facts.content),
         shape: facts.shape,
+        leaves: leafSetRow(facts.leaves),
         collection_address: collectionAddressRow(facts),
         guidance: facts.guidance,
         cite: facts.cite,
     };
 }
+/**
+ * The locus a colliding kind is declared at, for {@link resolveNameCollision}'s refusal:
+ * an `at` kind names the path its members are found at, and every other locus names
+ * itself — a kind that governs no glob has no path of its own to name.
+ */
+function locusLabel(facts) {
+    const { locus } = facts;
+    if (locus.kind !== "at")
+        return `the \`${locus.kind}\` locus`;
+    return `\`${locus.root === "." ? locus.glob : `${locus.root}/${locus.glob}`}\``;
+}
+/**
+ * A kind's facts with the three faces a relocation may diverge from its base on erased:
+ * the `relocates` marker, the appended `edgeFields`, and an `at` locus's moved root and
+ * glob (`kind.ts`'s `KindRelocation`). Two values agreeing here are one kind up to a
+ * relocation delta; the delta's own faces are checked on their own terms.
+ */
+function relocationInvariants(facts) {
+    const bare = { ...facts };
+    delete bare.relocates;
+    delete bare.edgeFields;
+    if (facts.locus.kind === "at")
+        bare.locus = { ...facts.locus, root: "", glob: "" };
+    return bare;
+}
+/**
+ * Whether `relocation` was derived from `base` — the provenance the relocation-wins rule
+ * rests on. The marker names the base, `relocate` only ever *appends* edge fields (so the
+ * base's are a prefix of the relocation's), and every other fact rides through unchanged:
+ * the base's facts are a subset by construction, which is exactly what makes keeping the
+ * relocation lossless. Checked rather than assumed, because the marker carries a name and
+ * a name is what is in dispute — a value bearing it whose facts are not the other's
+ * superset is a third kind of the same name, and dropping *that* would be the very silent
+ * loss this decision exists to end.
+ */
+function isRelocationOf(relocation, base) {
+    if (relocation.relocates !== base.name || base.relocates !== undefined)
+        return false;
+    const inherited = base.edgeFields ?? [];
+    const declared = relocation.edgeFields ?? [];
+    return (declared.length >= inherited.length &&
+        isDeepStrictEqual(declared.slice(0, inherited.length), inherited) &&
+        isDeepStrictEqual(relocationInvariants(relocation), relocationInvariants(base)));
+}
+/**
+ * Which of two `KindFacts` values sharing one name is the kind in play — a decision that
+ * must not depend on the order the two arrived in, since {@link kindsInPlay} draws its
+ * facts from `members`, then `expect`, then `admit`, then embedded templates, and a kind
+ * legitimately reaches it through any of them.
+ *
+ * A **relocation** wins over its base whichever way round they arrive
+ * ({@link isRelocationOf} proves the provenance): the base's facts are the relocation's
+ * minus the delta, so keeping the base would silently drop the relocation's added edge
+ * fields and moved locus. Two values that are structurally equal are one kind declared
+ * twice — keep the first. Anything else is a genuine collision and refuses: kind identity
+ * travels by import, never by string (`representation.md`, "kind"), while the lock is a
+ * string-keyed medium, so the second kind has no name to reach the engine
+ * under and dropping it is a silent loss of everything it declared. Two relocations of
+ * one base collide the same way — each is still a kind of the base's own name.
+ *
+ * # Throws
+ * On a collision, naming the kind and both loci — the two declarations an author has to
+ * go look at.
+ */
+function resolveNameCollision(held, arriving) {
+    // At most one holds: each direction demands the other value carry no marker at all.
+    if (isRelocationOf(held, arriving))
+        return held;
+    if (isRelocationOf(arriving, held))
+        return arriving;
+    if (isDeepStrictEqual(held, arriving))
+        return held;
+    throw new Error(held.relocates !== undefined && arriving.relocates !== undefined
+        ? `two relocations of kind \`${held.name}\` are in play, at ${locusLabel(held)} and ` +
+            `${locusLabel(arriving)}, and they diverge. A relocation is still a kind of its base's ` +
+            `name, so a second one collides with the first: relocate the base once and import that ` +
+            `one value wherever it is used (specs/model/representation.md, "kind").`
+        : `two kinds named \`${held.name}\` are in play, at ${locusLabel(held)} and ` +
+            `${locusLabel(arriving)}. Kind identity travels by import, never by string, and the lock ` +
+            `is keyed by name — the second kind has no name of its own to reach the engine under. ` +
+            `Import the declared kind rather than redeclaring it; to move a built-in to another root ` +
+            `or add an edge field to it, use \`relocate()\` (specs/model/representation.md, "kind").`);
+}
 /**
  * Every kind in play, at any locus — member kinds ∪ expect kinds ∪ their embedded
  * children — name-sorted, so every family derived from it inherits one stable order.
@@ -285,15 +444,24 @@ function kindFactRow(facts, admissions) {
  * Only *embedded* children are drawn in. A path-carrying template is the nested-file
  * layer, whose child owns a unit and reaches the lock through `expect` like any other
  * unit kind; pulling one in here would forge it a kind-fact row it never declared.
+ *
+ * Two facts values arriving under one name are decided by {@link resolveNameCollision},
+ * never by arrival order: the deduped facts are what `assemblyFactRows` derives every
+ * `edge` row from, so first-wins would drop a relocation's added edge on the floor
+ * whenever the base happened to be named first.
  */
 function kindsInPlay(harness) {
     const byName = new Map();
     const pending = [];
     const admit = (facts) => {
-        if (byName.has(facts.name))
+        const held = byName.get(facts.name);
+        if (held === facts)
+            return;
+        const winner = held === undefined ? facts : resolveNameCollision(held, facts);
+        if (winner === held)
             return;
-        byName.set(facts.name, facts);
-        pending.push(facts);
+        byName.set(facts.name, winner);
+        pending.push(winner);
     };
     for (const member of harness.members)
         admit(member.facts);
@@ -317,13 +485,20 @@ function atLocusKindsInPlay(allKinds) {
 /**
  * The distinct kinds in play that take a kind-fact row: every non-embedded locus
  * unconditionally (a nested-file kind owns a file the engine must place, and places it
- * off its row, though it governs no glob to be discovered at), plus an embedded kind
- * only when it declares `guidance` or `cite` of its own (decision 0045) — an embedded
- * kind with neither has nothing for the row to carry, and its members already reach the
- * corpus through their host's `templates` column alone (`kindsInPlay`), never the row.
+ * off its row, though it governs no glob to be discovered at), plus an embedded kind that
+ * has something of its own for a row to carry: `guidance` or `cite` (decision 0045), or a
+ * declared leaf set (decision 0053). The leaf set is on this list for the reason the
+ * column exists — it teaches what a child carries *before* the surface holds a member of
+ * it, and an embedded kind taking no row never reaches the lock to teach it. An embedded
+ * kind declaring none of the three has nothing for the row to carry, and its members
+ * already reach the corpus through their host's `templates` column alone (`kindsInPlay`),
+ * never the row.
  */
 function kindFactKindsInPlay(allKinds) {
-    return allKinds.filter((facts) => facts.locus.kind !== "embedded" || facts.guidance !== undefined || facts.cite !== undefined);
+    return allKinds.filter((facts) => facts.locus.kind !== "embedded" ||
+        facts.guidance !== undefined ||
+        facts.cite !== undefined ||
+        facts.leaves !== undefined);
 }
 /** The requirement rows — assembly `require` and every member's `requires`, one namespace. */
 function requirementRows(harness) {
@@ -388,7 +563,7 @@ function assemblyFactRows(harness, kinds) {
 function satisfiesRows(harness) {
     const rows = [];
     for (const member of harness.members) {
-        const address = `${member.kind}:${member.name}`;
+        const address = hostAddress(member.kind, member.name);
         for (const requirement of member.satisfies) {
             rows.push({ member: address, requirement });
         }
@@ -409,7 +584,7 @@ function satisfiesRows(harness) {
 function mentionRows(harness) {
     const rows = [];
     for (const member of harness.members) {
-        const address = `${member.kind}:${member.name}`;
+        const address = hostAddress(member.kind, member.name);
         if (member.prose?.kind === "text") {
             for (const mention of member.prose.mentions) {
                 rows.push({ member: address, target: mention.target.address });
@@ -435,13 +610,11 @@ function mentionRows(harness) {
  * contribute — top-level leaves addressed by their bare field name, a
  * collection entry's leaves addressed `<collection>.<entry>.<field>` (one layer
  * deep, matching the row's own shape) — each row keyed to the leaf's own
- * structural address, the `<member>/<kind>/<key>/<child-path>` grammar
- * `src/read.rs`'s `parse_leaf_address` resolves. A bare-string leaf names no
- * mention.
+ * structural address ({@link leafAddress}). A bare-string leaf names no mention.
  */
 function embeddedLeafMentionRows(hostName, value) {
     const rows = [];
-    const addressed = (childPath) => `${hostName}/${value.kind}/${value.key}/${childPath}`;
+    const addressed = (childPath) => leafAddress(hostName, value.kind, value.key, childPath);
     for (const [field, leaf] of Object.entries(value.leaves)) {
         if (typeof leaf === "string")
             continue;
@@ -478,7 +651,7 @@ function includeRows(harness) {
         rows.push({ member: address, source_path: fileURLToPath(new URL(include.path, include.moduleUrl)) });
     };
     for (const member of harness.members) {
-        const address = `${member.kind}:${member.name}`;
+        const address = hostAddress(member.kind, member.name);
         if (member.prose?.kind === "text") {
             for (const include of member.prose.includes)
                 push(address, include);
@@ -494,6 +667,27 @@ function includeRows(harness) {
     }
     return rows;
 }
+/**
+ * The `input` rows — every member's declared inputs, in member-then-authored order.
+ * Each carries the declaring member's `kind:name` address and the input's path resolved
+ * against the stating module ({@link fileURLToPath} over the input's own `moduleUrl`),
+ * never the workspace — exactly as an include's is; the engine reads and fingerprints
+ * it, and splices nothing.
+ *
+ * Unlike an include, an input pairs with no body slot, so nothing downstream depends on
+ * this order — the authored one is kept anyway, so a re-emit is byte-stable and the
+ * author reads their own declarations back.
+ */
+function inputRows(harness) {
+    const rows = [];
+    for (const member of harness.members) {
+        const address = hostAddress(member.kind, member.name);
+        for (const declared of member.inputs) {
+            rows.push({ member: address, source_path: fileURLToPath(new URL(declared.path, declared.moduleUrl)) });
+        }
+    }
+    return rows;
+}
 /**
  * One composed embedded value's key in an {@link EdgePlacements} table — its host's
  * `kind:name` address plus the value's own kind and key, the same triple the
@@ -591,7 +785,7 @@ function nestedMemberRows(harness, admissions, scope, placements, extents) {
     for (const member of harness.members) {
         if (member.prose?.kind !== "blocks")
             continue;
-        const host = `${member.kind}:${member.name}`;
+        const host = hostAddress(member.kind, member.name);
         for (const value of member.prose.values) {
             if (isTextSpan(value))
                 continue;
@@ -729,22 +923,22 @@ export function declaredRequirements(harness) {
 export function declaredAddresses(harness) {
     const set = declaredRequirements(harness);
     for (const member of harness.members) {
-        set.add(`${member.kind}:${member.name}`);
+        set.add(hostAddress(member.kind, member.name));
         if (member.prose?.kind !== "blocks")
             continue;
         for (const value of member.prose.values) {
             if (isTextSpan(value))
                 continue;
-            set.add(`${member.kind}:${member.name}/${value.kind}/${value.key}`);
+            set.add(nestedAddress(hostAddress(member.kind, member.name), value.kind, value.key));
         }
     }
     return set;
 }
 /**
  * Every discoverable (`at`-locus) kind the program declares — the deferral signal a
- * dangling mention is measured against (`prose.ts`'s `defersToGate`): a mention naming
- * one of these whose member is not a composed value defers to `check`, while a mention
- * naming no declared kind refuses at emit. Member kinds ∪ `expect` kinds; an embedded
+ * dangling mention is measured against (`prose.ts`'s `defersToGate`): a mention whose
+ * address is a host address of one of these and names no composed value defers to
+ * `check`, while a mention naming no declared kind refuses at emit. Member kinds ∪ `expect` kinds; an embedded
  * kind is excluded — its members are composed within a host, never discovered, so a
  * flat `kind:name` mention of one has no discovery locus to defer to.
  */
@@ -774,6 +968,15 @@ export function compileDeclarations(harness, placements, extents) {
             clauses.push(clauseRow(clause, binding.kind.key));
         }
     }
+    // The root member's own clauses — the third source of a clause row, beside `expect`'s
+    // kind-keyed rows and a requirement's nested ones. They lower with **no** `kind`
+    // column: that absence at the top level is the discriminator
+    // `compose::root_contract_from_rows` reads, and `drift::stamp_clause_labels` addresses
+    // them under the `root` owner segment. Declaration order within the array, appended
+    // past the kind-sorted `expect` rows — a fixed position, so double emit is byte-stable.
+    for (const clause of harness.contract) {
+        clauses.push(clauseRow(clause, undefined));
+    }
     return {
         kinds: kindFactKindsInPlay(allKinds).map((facts) => kindFactRow(facts, admissions)),
         clauses,
@@ -782,6 +985,7 @@ export function compileDeclarations(harness, placements, extents) {
         satisfies: satisfiesRows(harness),
         mentions: mentionRows(harness),
         includes: includeRows(harness),
+        inputs: inputRows(harness),
         nested_members: nestedMemberRows(harness, admissions, mentionScope(harness), placements, extents),
         registrations: [...registrationRows(harness), ...tapHookRows(harness)],
         settings: settingsRows(harness),

package/dist/src/emit.d.ts

@@ -9,10 +9,30 @@
  * run.
  */
 import type { Harness } from "./assembly.js";
-import type { Member } from "./kind.js";
+import type { EmbeddedMemberValue, Member } from "./kind.js";
 import type { Declarations } from "./declarations.js";
 import type { PayloadMember } from "./generated/index.js";
 export type { PayloadMember } from "./generated/index.js";
+/**
+ * One composed embedded value as an edge target, carried with the host member whose body
+ * it lives in: an embedded member owns no file, so every path fact about it is derived
+ * from its host's own projection.
+ */
+export interface EmbeddedTarget {
+    /** The member whose composed body carries the value — the projection it lives in. */
+    readonly host: Member;
+    /** The composed value itself. */
+    readonly value: EmbeddedMemberValue;
+}
+/**
+ * What one address in the member table names: a top-level composed member, or the
+ * embedded values one nested spelling reaches. The nested list carries one element for
+ * a full `<host-address>/<kind>/<key>` address, and one per host for a bare `kind:key` —
+ * a bare key names a nested member only when a single host carries it, and resolution
+ * refuses the rest as ambiguous rather than picking one: uniqueness is the resolver's
+ * bar, not the grammar's.
+ */
+export type EdgeTarget = Member | readonly EmbeddedTarget[];
 /** What a mention may resolve against at emit. */
 export interface ResolveOptions {
     /** The addresses a mention may name — resolution-checked; a mention cannot dangle. */
@@ -23,12 +43,14 @@ export interface ResolveOptions {
      */
     readonly deferrableKinds?: ReadonlySet<string>;
     /**
-     * The program's composed members by `kind:name` address — what an embedded value's
-     * edge field resolves against to derive its target facts. An edge target never defers
-     * to the gate the way a bare mention may: the facts are rendered into the projection
-     * now, so an unresolved one has nothing true to place.
+     * The program's composed members by address — what an embedded value's edge field
+     * resolves against to derive its target facts. Top-level members index at their
+     * `kind:name` address, and each composed embedded value at both of its own spellings:
+     * its full `<host-address>/<kind>/<key>` address and its bare `kind:key`.
+     * An edge target never defers to the gate the way a bare mention may: the facts are
+     * rendered into the projection now, so an unresolved one has nothing true to place.
      */
-    readonly members?: ReadonlyMap<string, Member>;
+    readonly members?: ReadonlyMap<string, EdgeTarget>;
 }
 /**
  * One fields-only registration member erased for the manifest write face: its key