@dtmd/temper 0.0.7 → 0.0.9

package/dist/src/kind.d.ts

@@ -1,7 +1,7 @@
 /**
  * Kinds — the engine room. A kind is a plain typed surface — an interface
- * `T` and a constructor `kind<T>()` — plus six facts of runtime residue: label,
- * locus, layout, registration, edge fields, and content. A registration kind (a hook,
+ * `T` and a constructor `kind<T>()` — plus seven facts of runtime residue: label,
+ * locus, projection, registration, edge fields, content, and template. A registration kind (a hook,
  * an MCP server) extends the content fact with a fields-only `shape` and a
  * `collectionAddress` naming the host manifest it surfaces in. `tsc` is the keystroke
  * wall; every type erases at the seam, and what a kind leaves behind rides the lock as
@@ -11,15 +11,25 @@
 import type { Prose, Text } from "./prose.js";
 import type { Capability } from "./needs.js";
 import type { Requirement } from "./contract.js";
-/** The shape of the on-disk artifact a member projects to (fact 3, layout). */
-export type Format = "yaml-frontmatter";
+/**
+ * The shape of the on-disk artifact a member projects to (fact 3, projection) — a closed
+ * vocabulary the engine implements once per entry, and the fact deciding which adapter
+ * reads a file kind's artifact. `"json-document"` is a whole artifact that is one JSON
+ * object: its top-level keys the member's fields, its identity a declared key among them.
+ * `"toml-document"` is that read over TOML, and a **read face only** — nothing projects a
+ * member declaring it, so it serves a document temper reads in place and never writes.
+ */
+export type Format = "yaml-frontmatter" | "json-document" | "toml-document";
 /**
  * Whether a member is a lone file (identity from the stem), a directory with an
- * entry file (identity from the directory name), or a lone file whose identity is
- * read from a declared frontmatter field (`identityField`) instead of derived from
- * the path (an agent's `name`).
+ * entry file (identity from the directory name), a lone file whose identity is
+ * read from a declared field (`identityField`) instead of derived from the path (an
+ * agent's `name`) — on whichever surface the kind's `format` carries its fields — or a
+ * lone file keyed by the directory segment its single-`*` segment glob stars
+ * (`"starred-segment"`), coexisting inside another kind's directory rather than owning
+ * one. The identity source is this spelled fact, never inferred from the glob.
  */
-export type UnitShape = "file" | "directory" | "named-field";
+export type UnitShape = "file" | "directory" | "named-field" | "starred-segment";
 /**
  * One **channel** a kind's registration declares — a documented way a member
  * reaches the world (fact 4, `builtins.md`, "The shipped kinds": "user
@@ -42,25 +52,57 @@ export type Registration = {
     readonly field: string;
 } | {
     readonly via: "connection";
+} | {
+    readonly via: "enablement";
+    readonly field: string;
+} | {
+    readonly via: "registry";
 };
 /** One of a kind's fields that is a reference to another member — a graph edge (fact 5). */
 export interface EdgeField {
     readonly field: string;
-    /** The target kind's name — the far end of the edge. */
-    readonly to: string;
+    /**
+     * The far end of the edge: the non-empty **set** of kinds the field may target.
+     * A one-element set resolves a bare address within its one kind; a multi-element
+     * set demands the kind-qualified `kind:name` address always, since resolution
+     * reads the written text and never infers from the member population. The
+     * non-emptiness is the type's to hold — an edge declaring no target kind can
+     * never resolve.
+     */
+    readonly to: readonly [string, ...string[]];
 }
 /**
- * A kind's **locus** (fact 2): members live at path globs (`at`) or as typed
- * fenced blocks inside host documents (`embedded`). An `at` locus is split root +
- * glob so the kind fact row carries `governs_root`/`governs_glob` directly.
+ * A kind's **locus** (fact 2), in three spellings: members live at path globs (`at`),
+ * as typed fenced blocks inside host documents (`embedded`), or as `nested-file`
+ * children owning a file whose path composes from their host member's unit and the host
+ * kind's template pattern. An `at` locus is split root + glob so the kind fact row
+ * carries `governs_root`/`governs_glob` directly; a `nested-file` kind declares neither
+ * — the pattern is the host {@link Template}'s one home, so a child can never collide
+ * with its host's own governs glob. An `embedded` locus names no host: which types may
+ * compose a kind's body is the adopting corpus's `admit` declaration over the host kind
+ * (`assembly.ts`), so one embedded type means the same thing in every body that admits
+ * it. A `nested-file` child names its host per member ({@link MemberInit}'s `host`) —
+ * the unit its path composes under.
+ *
+ * An `at` locus may declare a `commitment` class of `local`: per-machine and
+ * uncommitted — the kind is declared and reviewed, its members' documents are not. The
+ * class is a *file* locus's own fact, which is why only `at` spells it. A local locus is
+ * read-side only (the document is the governed source, read at check in place under
+ * whatever format the kind declares, and never an `emit` input or target), and its
+ * members' rows never enter the lock —
+ * they derive at read time under the kind the lock declares. Absent is the other class
+ * and the default: committed, where the kind and its members' documents are reviewed
+ * together and `emit` owns the bytes.
  */
 export type Locus = {
     readonly kind: "at";
     readonly root: string;
     readonly glob: string;
+    readonly commitment?: "local";
 } | {
     readonly kind: "embedded";
-    readonly withinHosts: readonly string[];
+} | {
+    readonly kind: "nested-file";
 };
 /**
  * One region of a kind's **layout** — one of the three corpus primitives over the
@@ -98,24 +140,47 @@ export type Shape = "fields";
 /**
  * A registration member's **collection address** — where inside a host manifest its
  * registration surfaces: which `manifest` (`settings.json`, `.mcp.json`) and which
- * `keyPath` (`hooks.<Event>`, `mcpServers.*`) it keys at. Carried by a fields-only
- * registration kind; absent for a kind that owns its own file locus.
+ * `keyPath` it keys at — one of the four addresses the shipped kinds surface at.
+ * Carried by a fields-only registration kind; absent for a kind that owns its own file
+ * locus.
  */
 export interface CollectionAddress {
     readonly manifest: string;
-    readonly keyPath: "hooks.<Event>" | "mcpServers.*";
+    readonly keyPath: "hooks.<Event>" | "mcpServers.*" | "enabledPlugins.*" | "extraKnownMarketplaces.*";
+    readonly entryShape: string;
+}
+/**
+ * A kind's **template** for one inner layer of nested members it hosts (fact 7): the
+ * child `kind`, plus the `path` pattern its children sit at — relative to the parent's
+ * own unit — when they are files (a skill's bundled reference documents at `*.md`).
+ * Omit `path` for an embedded layer, whose children live in the host's body and own no
+ * unit of their own.
+ *
+ * The declaration is the kind's own nesting fact, and a declared fact only: nothing
+ * discovers a file child off the pattern, exactly as a host's embedded members resolve
+ * off `nested_members` by address rather than off its templates. An adopting corpus may
+ * override the child kind by admitting its own over the host (`declarations.ts`'s
+ * `templatesFor`).
+ */
+export interface Template {
+    /** The child kind this layer templates — a kind value, since identity travels by import. */
+    readonly kind: KindDefinition<any>;
+    /** Where a file child's unit sits, relative to the parent's unit; absent for an embedded layer. */
+    readonly path?: string;
 }
-/** The six facts of a kind's runtime residue. */
+/** The seven facts of a kind's runtime residue. */
 export interface KindFacts {
     /** 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;
-    /** Fact 2, locus — where members live. */
+    /** 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;
-    /** Fact 3a, layout — the projection format; omitted for a frontmatterless kind. */
+    /** Fact 3a, projection — the artifact format; omitted for a kind that declares none. */
     readonly format?: Format;
-    /** Fact 3b, layout — the on-disk unit shape. */
+    /** Fact 3b, projection — the on-disk unit shape. */
     readonly unitShape: UnitShape;
     /** Fact 4, registration — the declared channel set naming every documented way
      * the world reaches a member (never rivals — a member is live if any one is). */
@@ -126,7 +191,9 @@ export interface KindFacts {
       * 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).
+      * 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. */
@@ -140,6 +207,9 @@ export interface KindFacts {
     /** 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[];
 }
 /**
  * One authored member — a typed value in the library. Kind identity travels by
@@ -150,10 +220,12 @@ export interface KindFacts {
 export interface Member {
     /** The kind's name — its declaration-row and lock identity. */
     readonly kind: string;
-    /** The kind's six facts — carried for projection and the declaration rows. */
+    /** The kind's seven facts — carried for projection and the declaration rows. */
     readonly facts: KindFacts;
     /** Identity within the kind. */
     readonly name: string;
+    /** The host member a nested-file child's path composes under; absent at every other locus. */
+    readonly host?: Member;
     /** The member's words. */
     readonly prose?: Prose;
     /** The kind's typed fields, flat and ordered — the projected frontmatter. */
@@ -168,13 +240,15 @@ export interface Member {
 /** The init a kind constructor takes — the framework keys plus the kind's typed fields `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. */
+    readonly host?: Member;
     readonly prose?: Prose;
     readonly satisfies?: readonly string[];
     readonly requires?: Readonly<Record<string, Requirement>>;
     readonly needs?: readonly Capability[];
 } & T;
 /**
- * A kind — a callable constructor carrying its six facts. Calling it builds a
+ * A kind — a callable constructor carrying its seven facts. Calling it builds a
  * member; `key` (its name) keys `expect` and a `kind` reference in a requirement.
  * The value *is* the identity — it travels by import, never by string.
  */
@@ -193,14 +267,14 @@ export interface KindDefinition<T> {
      */
     readonly render?: (value: ResolvedEmbeddedMemberValue) => string;
 }
-/** The options `kind()` takes beyond its six facts — today, only the embedded `render` hook. */
+/** The options `kind()` takes beyond its seven facts — today, only the embedded `render` hook. */
 export interface KindOptions {
     readonly render?: (value: ResolvedEmbeddedMemberValue) => string;
 }
 /**
  * Define a kind. Returns a constructor over the kind's typed
  * fields `T`; every type erases at the seam, so what the returned member carries
- * into emit is the six facts plus flat field data. `options.render`, when given,
+ * 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.
  */
@@ -220,7 +294,7 @@ export interface EmbeddedMemberCollectionEntry {
     readonly leaves: Readonly<Record<string, string | Text>>;
 }
 /**
- * An **embedded member's** composed value (posture 3, passed to `blocks()`):
+ * An **embedded member's** composed value — one child of a composed body, passed to `blocks()`:
  * leaves are authored strings keyed by field name; sibling collections are keyed
  * by collection name, each an authored-order list of entries — leaf addresses
  * are structural and keyed. Its
@@ -244,6 +318,12 @@ export interface EmbeddedMemberValue {
     readonly collections: Readonly<Record<string, readonly EmbeddedMemberCollectionEntry[]>>;
     /** The originating kind's `render` hook, when declared — resolved once at construction. */
     readonly render?: (value: ResolvedEmbeddedMemberValue) => string;
+    /**
+     * The originating kind's declared edge fields — which of the value's leaves are
+     * addresses, and the target facts emit derives from them. Resolved once at
+     * construction, the way `render` is.
+     */
+    readonly edgeFields?: readonly EdgeField[];
 }
 /**
  * One resolved sibling-collection entry: its own key plus its leaf fields,
@@ -255,6 +335,23 @@ export interface ResolvedEmbeddedMemberCollectionEntry {
     /** The entry's own leaf fields, already resolved to their final strings. */
     readonly leaves: Readonly<Record<string, string>>;
 }
+/**
+ * The closed set of facts an embedded format may place about one edge field's
+ * target — derived at emit off the resolved target member, never authored at the
+ * instance and never fabricated, so a rendered reference is true by construction.
+ * The set is exactly these four; a fifth fact is a spec question, not a
+ * convenience.
+ */
+export interface EdgeTargetFacts {
+    /** The target member's identity within its kind. */
+    readonly name: string;
+    /** The target's `kind:name` address — what the edge field's leaf authored. */
+    readonly address: string;
+    /** The target member's kind. */
+    readonly kind: string;
+    /** The target's projection, relative to the host member's own projection. */
+    readonly path: string;
+}
 /**
  * An {@link EmbeddedMemberValue} after every leaf (top-level and each
  * collection entry's) resolves to its final stored string
@@ -270,12 +367,21 @@ export interface ResolvedEmbeddedMemberValue {
     readonly leaves: Readonly<Record<string, string>>;
     /** Sibling collections, each entry's leaves already resolved. */
     readonly collections: Readonly<Record<string, readonly ResolvedEmbeddedMemberCollectionEntry[]>>;
+    /**
+     * The target facts of each edge field this value *fills*, keyed by the edge field's
+     * own name — the data a `render` hook selects to spell a reference. An unfilled
+     * field is no edge and carries no entry; a kind declaring no edge fields (or a value
+     * composed off a bare kind name, which carries none) has an empty map.
+     */
+    readonly targets: Readonly<Record<string, EdgeTargetFacts>>;
 }
 /**
  * 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 (when
- * declared) through to emit, with no other change to the composed value's shape.
+ * 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.
  */
 export declare function embeddedMemberValue(init: {
     kind: string | KindDefinition<any>;

package/dist/src/kind.js

@@ -1,7 +1,7 @@
 /**
  * Kinds — the engine room. A kind is a plain typed surface — an interface
- * `T` and a constructor `kind<T>()` — plus six facts of runtime residue: label,
- * locus, layout, registration, edge fields, and content. A registration kind (a hook,
+ * `T` and a constructor `kind<T>()` — plus seven facts of runtime residue: label,
+ * locus, projection, registration, edge fields, content, and template. A registration kind (a hook,
  * an MCP server) extends the content fact with a fields-only `shape` and a
  * `collectionAddress` naming the host manifest it surfaces in. `tsc` is the keystroke
  * wall; every type erases at the seam, and what a kind leaves behind rides the lock as
@@ -9,7 +9,7 @@
  * value.
  */
 /** The framework keys of a member init — everything else is a typed field (flat). */
-const FRAMEWORK_KEYS = new Set(["name", "prose", "satisfies", "requires", "needs"]);
+const FRAMEWORK_KEYS = new Set(["name", "host", "prose", "satisfies", "requires", "needs"]);
 /**
  * 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
@@ -29,10 +29,31 @@ function orderedFields(facts, init) {
     const head = facts.identityField !== undefined ? [[facts.identityField, init.name]] : [];
     return [...head, ...typed];
 }
+/**
+ * The host a member init names, checked against its kind's locus: a nested-file child's
+ * path composes from its host's unit, so it names one and every other locus names none.
+ *
+ * # Throws
+ * If a nested-file member declares no host, or a member at any other locus declares one.
+ */
+function hostOf(facts, init) {
+    const nested = facts.locus.kind === "nested-file";
+    if (nested && init.host === undefined) {
+        throw new Error(`member \`${init.name}\` of kind \`${facts.name}\`: a nested file child owns a file whose ` +
+            `path composes from its host's unit, so it names the \`host\` member it sits under ` +
+            `(specs/model/representation.md, "locus").`);
+    }
+    if (!nested && init.host !== undefined) {
+        throw new Error(`member \`${init.name}\` of kind \`${facts.name}\`: \`host\` names the member a nested ` +
+            `file child composes its path under, and this kind's locus is \`${facts.locus.kind}\` — ` +
+            `its path composes from nobody.`);
+    }
+    return init.host;
+}
 /**
  * Define a kind. Returns a constructor over the kind's typed
  * fields `T`; every type erases at the seam, so what the returned member carries
- * into emit is the six facts plus flat field data. `options.render`, when given,
+ * 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.
  */
@@ -41,6 +62,7 @@ export function kind(facts, options = {}) {
         kind: facts.name,
         facts,
         name: init.name,
+        host: hostOf(facts, init),
         prose: init.prose,
         fields: orderedFields(facts, init),
         satisfies: init.satisfies ?? [],
@@ -52,16 +74,21 @@ export function kind(facts, options = {}) {
 /**
  * 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 (when
- * declared) through to emit, with no other change to the composed value's shape.
+ * 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.
  */
 export function embeddedMemberValue(init) {
-    const [kindName, render] = typeof init.kind === "string" ? [init.kind, undefined] : [init.kind.key, init.kind.render];
+    const definition = typeof init.kind === "string" ? undefined : init.kind;
+    const render = definition?.render;
+    const edgeFields = definition?.facts.edgeFields;
     return {
-        kind: kindName,
+        kind: definition?.key ?? init.kind,
         key: init.key,
         leaves: init.leaves,
         collections: init.collections ?? {},
         ...(render !== undefined ? { render } : {}),
+        ...(edgeFields !== undefined ? { edgeFields } : {}),
     };
 }

package/dist/src/prose.d.ts

@@ -1,15 +1,15 @@
 /**
  * Prose — three 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 fully composed embedded-member values. Whatever
- * the constructor, the words land byte-identical to their authored text (law 5).
+ * 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.
  * 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
- * (law 8).
+ * projection. Both are authored per word and resolution-checked at emit, never mined.
  */
-import type { EmbeddedMemberValue } from "./kind.js";
+import type { EmbeddedMemberValue, Member } from "./kind.js";
 /** A declared value a mention may name — the target of the one-way citation edge. */
 export interface Mentionable {
     /** The mention's rendered form and graph edge target (`kind:name` or a leaf address). */
@@ -17,6 +17,12 @@ export interface Mentionable {
     /** The display text the one corpus-wide rule renders in place. */
     readonly display: string;
 }
+/**
+ * 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.
+ */
+export declare function mentionOf(member: Member): Mentionable;
 /** One authored interpolation: position in the template plus its target. */
 export interface Mention {
     readonly index: number;
@@ -37,11 +43,42 @@ export interface Include {
 }
 /** A `` text`…` `` interpolation — a mention (moves no content) or an include (moves content). */
 export type Reference = Mentionable | Include;
+/**
+ * The resolution universe a mention is checked against at emit: the addresses that
+ * resolve here and now ({@link mentionable}), and the kinds whose members the program
+ * declares but does not compose ({@link deferrableKinds}) — a mention naming one of
+ * those defers to `check` rather than refusing at emit.
+ */
+export interface MentionScope {
+    /** Every address a mention may resolve against in the program's own universe. */
+    readonly mentionable: ReadonlySet<string>;
+    /** The discoverable (`at`-locus) kinds the program declares — the deferral signal. */
+    readonly deferrableKinds: ReadonlySet<string>;
+}
+/**
+ * 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.
+ */
+export declare function defersToGate(address: string, deferrableKinds: ReadonlySet<string>): boolean;
+/**
+ * Refuse a mention whose address neither resolves against the scope's `mentionable`
+ * set nor defers to the gate ({@link defersToGate}) — the one dangling-mention refusal,
+ * shared by a member-level `Text` body, a composed body's prose span, and an embedded
+ * `Text` leaf. `context` prefixes the error so it names the host.
+ *
+ * # Throws
+ * If a mention names no declared value and its address has no discovery locus.
+ */
+export declare function checkMentions(mentions: readonly Mention[], scope: MentionScope, context: string): void;
 /**
  * `file(moduleUrl, path)` — the document keeps its medium: markdown in a
- * markdown file, full tooling, forever legal (posture 1, `15-kinds.md`).
- * Resolved and read in byte-for-byte at emit, relative to the declaring
- * module, never the process cwd.
+ * markdown file, full tooling, forever legal. Resolved and read in
+ * byte-for-byte at emit, relative to the declaring module, never the
+ * process cwd.
  */
 export interface File {
     readonly kind: "file";
@@ -53,7 +90,7 @@ export interface File {
 /**
  * `` text`…` `` — short prose inline, dedented, byte-deterministic; the
  * three-line rule that would be silly as a sidecar file. Mentions ride beside
- * the text, never inside it (law 5).
+ * the text, never inside it.
  */
 export interface Text {
     readonly kind: "text";
@@ -67,20 +104,23 @@ export interface Text {
     readonly includes: readonly Include[];
 }
 /**
- * `blocks(…)` — fully composed embedded-member values (posture 3): typed
- * collections rendered to `member.<kind> <key>` TOML fences, byte-identical to
- * the same values authored as fences directly (posture 2) and read back by the
+ * `blocks(…)` — a composed body of ordered children: verbatim prose spans
+ * ({@link Text}) and embedded-member values interleaved in authored order,
+ * the write-side mirror of a layout's ordered regions. A {@link Text} span stays
+ * prose — it carries its own mentions and includes and mints no wrapper member;
+ * an embedded value renders to its `member.<kind> <key>` TOML fence, byte-identical
+ * to the same value authored as a fence directly and read back by the
  * engine's fold (`src/extract.rs` `parse_embedded_info`/`parse_embedded_member`).
  */
 export interface Blocks {
     readonly kind: "blocks";
-    readonly values: readonly EmbeddedMemberValue[];
+    readonly values: readonly (Text | EmbeddedMemberValue)[];
 }
 /** A member's prose — one of the three constructors, one field type. */
 export type Prose = File | Text | Blocks;
 /**
- * Declare a document whose medium is preserved — read in whole at emit
- * (posture 1). `moduleUrl` is the declaring module's own `import.meta.url`,
+ * Declare a document whose medium is preserved — read in whole at emit.
+ * `moduleUrl` is the declaring module's own `import.meta.url`,
  * so `path` resolves relative to that module, never the process cwd:
  * `file(import.meta.url, "./long.md")`.
  */
@@ -89,7 +129,7 @@ export declare function file(moduleUrl: string, path: string): File;
  * The inline dedenting prose constructor. Interpolate {@link Reference} values — a
  * {@link Mentionable} is a mention (moves no content), an {@link Include} pulls the
  * target's bytes in; either is opt-in per word, and plain prose with zero references is
- * fully legal forever (the opt-in Decision, `20-surface.md`).
+ * fully legal forever.
  *
  * # Throws
  * If an authored chunk carries {@link MENTION_SLOT} or {@link INCLUDE_SLOT} — the markers
@@ -103,23 +143,39 @@ export declare function text(strings: TemplateStringsArray, ...targets: Referenc
  * `include(import.meta.url, "./fragment.md")`.
  */
 export declare function include(moduleUrl: string, path: string): Include;
-/** Compose fully-typed embedded-member values into a member's body (posture 3). */
-export declare function blocks(...values: EmbeddedMemberValue[]): Blocks;
+/**
+ * Compose a member's body from ordered children: verbatim prose spans
+ * ({@link text}) and embedded-member values interleaved in authored order. A prose
+ * span rides as prose — no wrapper member is minted to carry a narrative.
+ *
+ * # Throws
+ * If a child is a {@link File} — the parameter type excludes one, so only a JS or
+ * cast caller arrives here, and the alternative is a raw crash downstream on the
+ * `leaves` a `File` has no reason to carry.
+ */
+export declare function blocks(...values: (Text | EmbeddedMemberValue)[]): Blocks;
+/**
+ * Whether a composed-body child is a verbatim prose span rather than an embedded
+ * member value — the discriminant emit and the row builders branch on to render a
+ * span as prose and count its refs at host level, never as a nested member.
+ */
+export declare function isTextSpan(value: Text | EmbeddedMemberValue): value is Text;
 /**
  * Render an inline body to its final text — the display rule applied: each
  * mention slot becomes its target's display form, the surrounding words
- * untouched (law 5). The chunk count is `mentions.length + 1` by {@link text}'s
+ * untouched. The chunk count is `mentions.length + 1` by {@link text}'s
  * construction, so the walk consumes every slot.
  */
 export declare function renderText(prose: Text): string;
 /**
  * Resolve a leaf's authored value to its stored/rendered string: a bare string
- * is unchanged; a `Text` leaf is mention-resolution-checked against
- * `mentionable` (loud on a dangling address) and rendered by {@link renderText}
- * — the same rule a member-level `Text` body resolves by. `context` prefixes
- * the dangling-mention error so it names the leaf, not just the mention.
+ * is unchanged; a `Text` leaf is mention-resolution-checked against `scope`
+ * ({@link checkMentions}: loud on a dangling address, a discovery-locus one
+ * deferred) and rendered by {@link renderText} — the same rule a member-level
+ * `Text` body resolves by. `context` prefixes the dangling-mention error so it
+ * names the leaf, not just the mention.
  *
  * # Throws
- * If a mention names no declared value.
+ * If a mention names no declared value and has no discovery locus.
  */
-export declare function resolveLeaf(value: string | Text, mentionable: ReadonlySet<string>, context: string): string;
+export declare function resolveLeaf(value: string | Text, scope: MentionScope, context: string): string;