@dtmd/temper 0.0.18 → 0.0.19

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,6 +145,7 @@ 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 });
 }
@@ -147,14 +225,26 @@ export function relocate(base, delta) {
     // 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 ?? {},
@@ -162,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`);
+}

package/dist/src/prose.d.ts

@@ -1,9 +1,13 @@
 /**
- * Prose — three constructors, one field type. A member's words are data the
+ * Prose — four constructors, one field type. A member's words are data the
  * member declares: `file()` for a document that keeps its medium, `` text`…` ``
- * for short inline prose, `blocks()` for a composed body that interleaves verbatim
- * prose spans with embedded-member values in authored order. Whatever
- * the constructor, the words land byte-identical to their authored text.
+ * for short inline prose, `span()` for prose the program computes, `blocks()` for a
+ * composed body that interleaves verbatim prose spans with embedded-member values in
+ * authored order. Whatever the constructor, the words land byte-identical to their
+ * authored text. The two inline constructors build the same {@link Text} and differ
+ * only in where the words come from: reach for `` text`…` `` when they are literal, for
+ * `span()` when they are a string the program derived — the tag's interpolations are
+ * references, never words, so a computed string has no slot to ride in.
  * Interpolations in `` text`…` `` are references, two intents apart: a **mention**
  * (a {@link Mentionable}) is a declared one-way edge that moves no content, and an
  * **include** (an {@link Include}) pulls the target file's bytes into the host's emitted
@@ -116,7 +120,7 @@ export interface Blocks {
     readonly kind: "blocks";
     readonly values: readonly (Text | EmbeddedMemberValue)[];
 }
-/** A member's prose — one of the three constructors, one field type. */
+/** A member's prose — one of the four constructors, one field type. */
 export type Prose = File | Text | Blocks;
 /**
  * Declare a document whose medium is preserved — read in whole at emit.
@@ -136,6 +140,19 @@ export declare function file(moduleUrl: string, path: string): File;
  * are the tool's alone, so a stray one is a loud authoring error, not a silent mis-split.
  */
 export declare function text(strings: TemplateStringsArray, ...targets: Reference[]): Text;
+/**
+ * The computed-prose constructor: the same inline prose as `` text`…` ``, from a string
+ * the program built rather than a template the author typed — a rolled-up participants
+ * line, a table derived from the members. An author reaches for the tag whenever the
+ * words are literal, since only the tag can carry a {@link Reference}; a computed string
+ * cannot, because the tag's interpolations *are* the references. So a span is prose with
+ * zero references by construction, dedented by the same rule, and composes wherever a
+ * `` text`…` `` span does — a member's whole body or a {@link blocks} child.
+ *
+ * # Throws
+ * If `words` carries {@link MENTION_SLOT} or {@link INCLUDE_SLOT} ({@link refuseReservedMarkers}).
+ */
+export declare function span(words: string): Text;
 /**
  * Declare an include target — its bytes are pulled into the host's projection at emit,
  * a dependency the lock fingerprints. `moduleUrl` is the declaring module's own

package/dist/src/prose.js

@@ -1,9 +1,13 @@
 /**
- * Prose — three constructors, one field type. A member's words are data the
+ * Prose — four constructors, one field type. A member's words are data the
  * member declares: `file()` for a document that keeps its medium, `` text`…` ``
- * for short inline prose, `blocks()` for a composed body that interleaves verbatim
- * prose spans with embedded-member values in authored order. Whatever
- * the constructor, the words land byte-identical to their authored text.
+ * for short inline prose, `span()` for prose the program computes, `blocks()` for a
+ * composed body that interleaves verbatim prose spans with embedded-member values in
+ * authored order. Whatever the constructor, the words land byte-identical to their
+ * authored text. The two inline constructors build the same {@link Text} and differ
+ * only in where the words come from: reach for `` text`…` `` when they are literal, for
+ * `span()` when they are a string the program derived — the tag's interpolations are
+ * references, never words, so a computed string has no slot to ride in.
  * Interpolations in `` text`…` `` are references, two intents apart: a **mention**
  * (a {@link Mentionable}) is a declared one-way edge that moves no content, and an
  * **include** (an {@link Include}) pulls the target file's bytes into the host's emitted
@@ -65,6 +69,20 @@ const MENTION_SLOT = "\u0000";
  * carries one, so the split is unambiguous.
  */
 const INCLUDE_SLOT = "\u0001";
+/**
+ * Refuse authored words carrying {@link MENTION_SLOT} or {@link INCLUDE_SLOT} — the
+ * markers are the tool's alone. A stray one would split into a chunk no reference
+ * claims, and {@link renderText} drops every chunk past the last mention, so the loud
+ * error is the only alternative to silently swallowing the words after it.
+ *
+ * # Throws
+ * If `words` carries either reserved marker.
+ */
+function refuseReservedMarkers(words) {
+    if (words.includes(MENTION_SLOT) || words.includes(INCLUDE_SLOT)) {
+        throw new Error("authored prose contains a reserved reference marker (U+0000/U+0001); remove it.");
+    }
+}
 /** Strip the common leading indentation a template literal picks up from its module. */
 function dedent(text) {
     const lines = text.split("\n");
@@ -102,9 +120,7 @@ export function text(strings, ...targets) {
     const mentions = [];
     const includes = [];
     strings.forEach((chunk, i) => {
-        if (chunk.includes(MENTION_SLOT) || chunk.includes(INCLUDE_SLOT)) {
-            throw new Error("authored prose contains a reserved reference marker (U+0000/U+0001); remove it.");
-        }
+        refuseReservedMarkers(chunk);
         if (i === 0)
             return;
         const target = targets[i - 1];
@@ -119,6 +135,22 @@ export function text(strings, ...targets) {
     });
     return { kind: "text", template: dedent(template), mentions, includes };
 }
+/**
+ * The computed-prose constructor: the same inline prose as `` text`…` ``, from a string
+ * the program built rather than a template the author typed — a rolled-up participants
+ * line, a table derived from the members. An author reaches for the tag whenever the
+ * words are literal, since only the tag can carry a {@link Reference}; a computed string
+ * cannot, because the tag's interpolations *are* the references. So a span is prose with
+ * zero references by construction, dedented by the same rule, and composes wherever a
+ * `` text`…` `` span does — a member's whole body or a {@link blocks} child.
+ *
+ * # Throws
+ * If `words` carries {@link MENTION_SLOT} or {@link INCLUDE_SLOT} ({@link refuseReservedMarkers}).
+ */
+export function span(words) {
+    refuseReservedMarkers(words);
+    return { kind: "text", template: dedent(words), mentions: [], includes: [] };
+}
 /**
  * Declare an include target — its bytes are pulled into the host's projection at emit,
  * a dependency the lock fingerprints. `moduleUrl` is the declaring module's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtmd/temper",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "The temper authoring face — the six-noun model as typed modules: harness(), kind<T>(), clause values, needs, and file()/text/blocks(). Emit compiles to the declaration rows the engine reads, a byte-faithful projection, and the lock.",
   "license": "(MIT OR Apache-2.0)",
   "repository": {
@@ -52,7 +52,7 @@
     "temper": "bin/temper.js"
   },
   "optionalDependencies": {
-    "@dtmd/temper-linux-x64": "0.0.18",
-    "@dtmd/temper-win32-x64": "0.0.18"
+    "@dtmd/temper-linux-x64": "0.0.19",
+    "@dtmd/temper-win32-x64": "0.0.19"
   }
 }