@dtmd/temper 0.0.17 → 0.0.19

package/dist/src/member-address.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The member-address grammar — one home for every spelling a member's identity takes and
+ * for the reader those writers round-trip against. Three spellings, each the one before
+ * it plus a segment:
+ *
+ * - `<kind>:<name>` — a **host address**, a top-level member's own identity.
+ * - `<host-address>/<kind>/<key>` — a **nested-member address**, the identity a member
+ *   embedded in a host carries.
+ * - `<member>/<kind>/<key>/<leaf>` — a **leaf address**, one authored string beneath a
+ *   nested member. A grain of its own, and no member address at all.
+ *
+ * Because the third is the second plus a `/<leaf>` tail, both are read off one
+ * segmentation ({@link segment}) rather than two independently-shaped parses that could
+ * come to disagree about where the member ends. The engine's `src/member_address.rs` is
+ * the other end of the same grammar: a spelling moves on both sides at once or the seam
+ * breaks.
+ */
+/** The two halves a host address names — the reader's answer, and never re-split by hand. */
+export interface HostAddress {
+    /** The member's kind. */
+    readonly kind: string;
+    /** The member's name among its kind. */
+    readonly name: string;
+}
+/** One parsed nested-member address. */
+export interface NestedAddress {
+    /** The host member's own `<kind>:<name>` address — the segment before the first `/`. */
+    readonly host: string;
+    /** The nested member's kind. */
+    readonly kind: string;
+    /** The nested member's key among its host's members of that kind. */
+    readonly key: string;
+}
+/** One parsed leaf address — a nested-member address plus its `/<leaf>` tail. */
+export interface LeafAddress {
+    /**
+     * The member the leaf lives under, verbatim as its author spelled it: the canonical
+     * `<kind>:<name>` host address, or the bare member id this SDK's own leaf writer and
+     * the committed lock mention targets spell. Which of the two a head is, is resolution's
+     * question, not the grammar's.
+     */
+    readonly member: string;
+    /** The nested member's kind. */
+    readonly kind: string;
+    /** The nested member's key among its host's members of that kind. */
+    readonly key: string;
+    /** The leaf's path within the nested member — the whole remainder after the third slash. */
+    readonly childPath: string;
+}
+/** Spell a top-level member's own `<kind>:<name>` address. */
+export declare function hostAddress(kind: string, name: string): string;
+/** Spell a nested member's address from its host's address, its own kind and its key. */
+export declare function nestedAddress(host: string, kind: string, key: string): string;
+/**
+ * Spell one leaf's address beneath a nested member. `member` is carried verbatim, so a
+ * writer holding the bare member id spells the short form the lock already commits
+ * ({@link LeafAddress.member}).
+ */
+export declare function leafAddress(member: string, kind: string, key: string, childPath: string): string;
+/**
+ * The member-table **lookup key** a bare `<kind>:<key>` reference spells — shaped like a
+ * host address and never one: a nested member's address composes through its host, and a
+ * corpus-unique key was rejected as the grammar because uniqueness is the resolver's bar,
+ * not the grammar's. The engine strips this prefix back off before matching, so the two
+ * ends agree and the apparent mismatch is not a defect to fix.
+ */
+export declare function bareLookupKey(kind: string, key: string): string;
+/**
+ * The key an authored edge address is looked up under: a one-element `to` set resolves a
+ * bare address within its one admissible kind, so an unqualified address is lifted into a
+ * {@link bareLookupKey}; an address already carrying a colon is the kind-qualified form
+ * the author wrote and stands as it is.
+ */
+export declare function edgeLookupKey(address: string, to: readonly string[]): string;
+/**
+ * The `(kind, name)` a host address spells, or `undefined` when it spells none — the
+ * reader half of {@link hostAddress}. Both halves are non-empty: an address names exactly
+ * one thing or it names nothing. Splits at the **first** colon, so a name carrying one
+ * stays whole.
+ *
+ * A `/` anywhere is this grammar's own segment separator ({@link segment} splits on it),
+ * so an address carrying one is a segmented spelling with its own reader
+ * ({@link parseNestedAddress}, {@link parseLeafAddress}) and no host address at all. The
+ * refusal lives here rather than at each caller, so a reader that asks "is this a host
+ * address?" never has to re-spell the separator to get the answer right.
+ */
+export declare function parseHostAddress(address: string): HostAddress | undefined;
+/**
+ * Parse a nested-member address, or `undefined` when `address` is not one: exactly three
+ * non-empty segments, the first of them a host address.
+ *
+ * A `/<leaf>` tail is ruled out here explicitly — a leaf is its own grain, and truncating
+ * one to the member that happens to contain it would answer a leaf reference with a member
+ * the author never named.
+ */
+export declare function parseNestedAddress(address: string): NestedAddress | undefined;
+/**
+ * Parse a leaf address, or `undefined` when `target` carries no tail or a segment-shaped
+ * hole. The head is carried on verbatim rather than split, because the bare member id is
+ * a live short form ({@link LeafAddress.member}).
+ */
+export declare function parseLeafAddress(target: string): LeafAddress | undefined;

package/dist/src/member-address.js

@@ -0,0 +1,114 @@
+/**
+ * The member-address grammar — one home for every spelling a member's identity takes and
+ * for the reader those writers round-trip against. Three spellings, each the one before
+ * it plus a segment:
+ *
+ * - `<kind>:<name>` — a **host address**, a top-level member's own identity.
+ * - `<host-address>/<kind>/<key>` — a **nested-member address**, the identity a member
+ *   embedded in a host carries.
+ * - `<member>/<kind>/<key>/<leaf>` — a **leaf address**, one authored string beneath a
+ *   nested member. A grain of its own, and no member address at all.
+ *
+ * Because the third is the second plus a `/<leaf>` tail, both are read off one
+ * segmentation ({@link segment}) rather than two independently-shaped parses that could
+ * come to disagree about where the member ends. The engine's `src/member_address.rs` is
+ * the other end of the same grammar: a spelling moves on both sides at once or the seam
+ * breaks.
+ */
+/** Spell a top-level member's own `<kind>:<name>` address. */
+export function hostAddress(kind, name) {
+    return `${kind}:${name}`;
+}
+/** Spell a nested member's address from its host's address, its own kind and its key. */
+export function nestedAddress(host, kind, key) {
+    return `${host}/${kind}/${key}`;
+}
+/**
+ * Spell one leaf's address beneath a nested member. `member` is carried verbatim, so a
+ * writer holding the bare member id spells the short form the lock already commits
+ * ({@link LeafAddress.member}).
+ */
+export function leafAddress(member, kind, key, childPath) {
+    return `${nestedAddress(member, kind, key)}/${childPath}`;
+}
+/**
+ * The member-table **lookup key** a bare `<kind>:<key>` reference spells — shaped like a
+ * host address and never one: a nested member's address composes through its host, and a
+ * corpus-unique key was rejected as the grammar because uniqueness is the resolver's bar,
+ * not the grammar's. The engine strips this prefix back off before matching, so the two
+ * ends agree and the apparent mismatch is not a defect to fix.
+ */
+export function bareLookupKey(kind, key) {
+    return `${kind}:${key}`;
+}
+/**
+ * The key an authored edge address is looked up under: a one-element `to` set resolves a
+ * bare address within its one admissible kind, so an unqualified address is lifted into a
+ * {@link bareLookupKey}; an address already carrying a colon is the kind-qualified form
+ * the author wrote and stands as it is.
+ */
+export function edgeLookupKey(address, to) {
+    return to.length === 1 && !address.includes(":") ? bareLookupKey(to[0], address) : address;
+}
+/**
+ * The `(kind, name)` a host address spells, or `undefined` when it spells none — the
+ * reader half of {@link hostAddress}. Both halves are non-empty: an address names exactly
+ * one thing or it names nothing. Splits at the **first** colon, so a name carrying one
+ * stays whole.
+ *
+ * A `/` anywhere is this grammar's own segment separator ({@link segment} splits on it),
+ * so an address carrying one is a segmented spelling with its own reader
+ * ({@link parseNestedAddress}, {@link parseLeafAddress}) and no host address at all. The
+ * refusal lives here rather than at each caller, so a reader that asks "is this a host
+ * address?" never has to re-spell the separator to get the answer right.
+ */
+export function parseHostAddress(address) {
+    if (address.includes("/"))
+        return undefined;
+    const colon = address.indexOf(":");
+    if (colon <= 0 || colon === address.length - 1)
+        return undefined;
+    return { kind: address.slice(0, colon), name: address.slice(colon + 1) };
+}
+/**
+ * Cut an address into its segments, or `undefined` when it carries fewer than three or a
+ * segment-shaped hole. The tail keeps its own dots and slashes, so it is the whole
+ * remainder after the third slash rather than a fourth segment among more.
+ */
+function segment(address) {
+    const parts = address.split("/");
+    if (parts.length < 3)
+        return undefined;
+    const [host, kind, key] = parts;
+    const tail = parts.length > 3 ? parts.slice(3).join("/") : undefined;
+    if (host === "" || kind === "" || key === "" || tail === "")
+        return undefined;
+    return { host, kind, key, tail };
+}
+/**
+ * Parse a nested-member address, or `undefined` when `address` is not one: exactly three
+ * non-empty segments, the first of them a host address.
+ *
+ * A `/<leaf>` tail is ruled out here explicitly — a leaf is its own grain, and truncating
+ * one to the member that happens to contain it would answer a leaf reference with a member
+ * the author never named.
+ */
+export function parseNestedAddress(address) {
+    const segments = segment(address);
+    if (segments === undefined || segments.tail !== undefined)
+        return undefined;
+    if (parseHostAddress(segments.host) === undefined)
+        return undefined;
+    return { host: segments.host, kind: segments.kind, key: segments.key };
+}
+/**
+ * Parse a leaf address, or `undefined` when `target` carries no tail or a segment-shaped
+ * hole. The head is carried on verbatim rather than split, because the bare member id is
+ * a live short form ({@link LeafAddress.member}).
+ */
+export function parseLeafAddress(target) {
+    const segments = segment(target);
+    if (segments?.tail === undefined)
+        return undefined;
+    return { member: segments.host, kind: segments.kind, key: segments.key, childPath: segments.tail };
+}

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
@@ -19,8 +23,8 @@ export interface Mentionable {
 }
 /**
  * Spell a top-level member as the {@link Mentionable} a mention carries: its
- * `kind:name` address, its bare name the display text — the convention every
- * corpus repeats to cite a member from prose, captured once here.
+ * {@link hostAddress}, its bare name the display text — the convention every corpus
+ * repeats to cite a member from prose.
  */
 export declare function mentionOf(member: Member): Mentionable;
 /** One authored interpolation: position in the template plus its target. */
@@ -57,11 +61,11 @@ export interface MentionScope {
 }
 /**
  * Whether a mention's unresolved address **defers to the gate** rather than refusing at
- * emit: a top-level `kind:name` address whose kind is one the program declares at a
- * discovery locus (an `at`-locus kind) may name a member discovered on disk, so `check`
- * owns the verdict. An embedded leaf address (a `<host>/<kind>/<key>` form, carrying a
- * `/`), a bare requirement name (no `:`), or a kind the program does not declare has no
- * discovery locus and stays a dangling refusal.
+ * emit: a host address ({@link parseHostAddress}) whose kind is one the program declares
+ * at a discovery locus (an `at`-locus kind) may name a member discovered on disk, so
+ * `check` owns the verdict. Anything the grammar's reader answers `undefined` for — a
+ * segmented embedded address, a bare requirement name, a name-less `kind:` — names no
+ * discoverable member, and stays a dangling refusal however deferrable its head reads.
  */
 export declare function defersToGate(address: string, deferrableKinds: ReadonlySet<string>): boolean;
 /**
@@ -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,35 +1,38 @@
 /**
- * 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
  * projection. Both are authored per word and resolution-checked at emit, never mined.
  */
+import { hostAddress, parseHostAddress } from "./member-address.js";
 /**
  * Spell a top-level member as the {@link Mentionable} a mention carries: its
- * `kind:name` address, its bare name the display text — the convention every
- * corpus repeats to cite a member from prose, captured once here.
+ * {@link hostAddress}, its bare name the display text — the convention every corpus
+ * repeats to cite a member from prose.
  */
 export function mentionOf(member) {
-    return { address: `${member.kind}:${member.name}`, display: member.name };
+    return { address: hostAddress(member.kind, member.name), display: member.name };
 }
 /**
  * Whether a mention's unresolved address **defers to the gate** rather than refusing at
- * emit: a top-level `kind:name` address whose kind is one the program declares at a
- * discovery locus (an `at`-locus kind) may name a member discovered on disk, so `check`
- * owns the verdict. An embedded leaf address (a `<host>/<kind>/<key>` form, carrying a
- * `/`), a bare requirement name (no `:`), or a kind the program does not declare has no
- * discovery locus and stays a dangling refusal.
+ * emit: a host address ({@link parseHostAddress}) whose kind is one the program declares
+ * at a discovery locus (an `at`-locus kind) may name a member discovered on disk, so
+ * `check` owns the verdict. Anything the grammar's reader answers `undefined` for — a
+ * segmented embedded address, a bare requirement name, a name-less `kind:` — names no
+ * discoverable member, and stays a dangling refusal however deferrable its head reads.
  */
 export function defersToGate(address, deferrableKinds) {
-    if (address.includes("/"))
-        return false;
-    const colon = address.indexOf(":");
-    return colon > 0 && deferrableKinds.has(address.slice(0, colon));
+    const host = parseHostAddress(address);
+    return host !== undefined && deferrableKinds.has(host.kind);
 }
 /**
  * Refuse a mention whose address neither resolves against the scope's `mentionable`
@@ -66,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");
@@ -103,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];
@@ -120,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.17",
+  "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.17",
-    "@dtmd/temper-win32-x64": "0.0.17"
+    "@dtmd/temper-linux-x64": "0.0.19",
+    "@dtmd/temper-win32-x64": "0.0.19"
   }
 }