@dtmd/temper 0.0.4 → 0.0.7

package/dist/src/emit.js

@@ -1,35 +1,135 @@
 /**
- * Emit — the compile from the six-noun face to the seam's JSON pipe
- * (`specs/architecture/20-surface.md`, "Emit — total, byte-reproducible, refusing";
- * "The seam — one implementation"). The SDK implements **no semantics**: emit
+ * Emit — the compile from the six-noun face to the seam's JSON pipe.
+ * The SDK implements **no semantics**: emit
  * produces plain data — the declaration rows the engine reads and, per projected
  * member, its ordered typed fields and resolved prose body. The engine is the
  * sole compiler of every projection and the whole lock; the SDK writes neither.
  * Emit is total (members are the only source), refuses before it produces a byte
  * on a broken source, and is byte-reproducible — double-emit verified at every
- * run (law 5).
+ * run.
  */
-import { resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";
-import { renderText } from "./prose.js";
+import { renderText, resolveLeaf } from "./prose.js";
 import { permissionUnion } from "./needs.js";
-import { SEAM_VERSION, compileDeclarations } from "./declarations.js";
+import { compareStrings, compileDeclarations, declaredAddresses, declaredRequirements, encodeSeam, registrationRows, settingsRows, } from "./declarations.js";
+/**
+ * TOML-quote a leaf's authored text into a basic-string literal — the escapes
+ * `toml_edit`'s parser reads back (backslash, quote, and the C0 control set),
+ * so a leaf survives the write↔read round trip byte-identically.
+ */
+function tomlString(text) {
+    let out = '"';
+    for (const char of text) {
+        switch (char) {
+            case "\\":
+                out += "\\\\";
+                break;
+            case '"':
+                out += '\\"';
+                break;
+            case "\b":
+                out += "\\b";
+                break;
+            case "\t":
+                out += "\\t";
+                break;
+            case "\n":
+                out += "\\n";
+                break;
+            case "\f":
+                out += "\\f";
+                break;
+            case "\r":
+                out += "\\r";
+                break;
+            default:
+                out += char.charCodeAt(0) < 0x20 ? `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}` : char;
+        }
+    }
+    return out + '"';
+}
+/**
+ * Resolve one embedded member's value's leaves — top-level and each
+ * collection entry's — to their final stored strings: a `Text`-authored leaf
+ * resolves the way `resolveBody` resolves a member-level `Text` body (mention
+ * resolution-checked against `mentionable`, loud on a dangling address); a
+ * bare-string leaf is unchanged. The one resolution point shared by the
+ * default TOML view and a kind's own `render` hook, so refusing on a dangling
+ * embedded-kind leaf mention never depends on whether the kind declares
+ * `render` (`pipeline.md`, "Emit", the "Refusing" bullet).
+ */
+function resolveMemberLeaves(value, mentionable) {
+    const context = (childPath) => `member.${value.kind} ${value.key}: leaf \`${childPath}\``;
+    const leaves = {};
+    for (const [key, leaf] of Object.entries(value.leaves)) {
+        leaves[key] = resolveLeaf(leaf, mentionable, context(key));
+    }
+    const collections = {};
+    for (const [collection, entries] of Object.entries(value.collections)) {
+        collections[collection] = entries.map((entry) => {
+            const entryLeaves = {};
+            for (const [leaf, text] of Object.entries(entry.leaves)) {
+                entryLeaves[leaf] = resolveLeaf(text, mentionable, context(`${collection}.${entry.key}.${leaf}`));
+            }
+            return { key: entry.key, leaves: entryLeaves };
+        });
+    }
+    return { kind: value.kind, key: value.key, leaves, collections };
+}
+/**
+ * Render one resolved embedded member's interior TOML: its top-level leaves,
+ * then each collection's entries, in authored order, each its own
+ * `[collection.entry]` table — the default view a `blocks()` value renders
+ * with, when its originating kind declares no `render` hook (`kind.ts`).
+ */
+function renderMemberToml(value) {
+    const lines = [];
+    for (const [key, leaf] of Object.entries(value.leaves)) {
+        lines.push(`${key} = ${tomlString(leaf)}`);
+    }
+    for (const [collection, entries] of Object.entries(value.collections)) {
+        for (const entry of entries) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push(`[${collection}.${entry.key}]`);
+            for (const [leaf, text] of Object.entries(entry.leaves)) {
+                lines.push(`${leaf} = ${tomlString(text)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Render one embedded member's value to its `member.<kind> <key>` fenced block:
+ * the originating kind's own `render` hook, when declared, in place of the
+ * default `[collection.entry]` TOML view — the fence wrapper itself never
+ * changes, so a `render`-less kind's projection is byte-unchanged. Leaves
+ * resolve once (`resolveMemberLeaves`) before either path sees them, so a
+ * hook receives plain strings, never a raw `Text` leaf.
+ */
+function renderMemberFence(value, options) {
+    const mentionable = options.mentionable ?? new Set();
+    const resolved = resolveMemberLeaves(value, mentionable);
+    const body = value.render !== undefined ? value.render(resolved) : renderMemberToml(resolved);
+    return `\`\`\`member.${value.kind} ${value.key}\n${body}\n\`\`\``;
+}
 /**
  * Resolve a member's prose to its final body bytes: a `file()` asset is read in
  * byte-for-byte; a `text` body's mentions are resolution-checked (loud on a
- * dangling address) and rendered by the one display rule; a `blocks()` body is
- * refused until the fence format lands. The words are never reworded (law 5).
+ * dangling address) and rendered by the one display rule; a `blocks()` body
+ * renders each embedded member as a `member.<kind> <key>` TOML fence. The words
+ * are never reworded.
  *
  * # Throws
- * If a `file()` asset does not resolve, a mention names no declared value, or a
- * `blocks()` body is projected before `(genre-fence-format)` lands.
+ * If a `file()` asset does not resolve, or a mention names no declared value.
  */
 function resolveBody(member, options) {
     const prose = member.prose;
     if (prose === undefined)
         return "";
     if (prose.kind === "file") {
-        const assetPath = fileSourcePath(member, options);
+        const assetPath = fileSourcePath(member);
         try {
             return readFileSync(assetPath, "utf8");
         }
@@ -39,39 +139,20 @@ function resolveBody(member, options) {
         }
     }
     if (prose.kind === "blocks") {
-        throw new Error(`member \`${member.name}\`: a blocks() body renders through the genre fence format, ` +
-            `deferred until its first consumer lands ((genre-fence-format), specs/architecture/15-kinds.md).`);
+        return prose.values.map((value) => renderMemberFence(value, options)).join("\n\n") + "\n";
     }
     const mentionable = options.mentionable ?? new Set();
     for (const mention of prose.mentions) {
         if (!mentionable.has(mention.target.address)) {
             throw new Error(`member \`${member.name}\`: mention of \`${mention.target.address}\` resolves to no ` +
-                `declared value — a mention cannot dangle (specs/architecture/45-governance.md).`);
+                `declared value — a mention cannot dangle (specs/model/contract.md).`);
         }
     }
     return renderText(prose);
 }
-/** Every requirement name a `satisfies` claim may fill — assembly `require` ∪ member `requires`. */
-function declaredRequirements(harness) {
-    const set = new Set();
-    for (const name of Object.keys(harness.require))
-        set.add(name);
-    for (const member of harness.members) {
-        for (const name of Object.keys(member.requires))
-            set.add(name);
-    }
-    return set;
-}
-/** Every address a mention may name — declared requirement names ∪ each member's `kind:name`. */
-function declaredAddresses(harness) {
-    const set = declaredRequirements(harness);
-    for (const member of harness.members)
-        set.add(`${member.kind}:${member.name}`);
-    return set;
-}
 /**
- * The two declare-side refusals emit runs before it produces a byte
- * (`20-surface.md`, "Emit refuses before it writes"): a `satisfies` claim naming
+ * The two declare-side refusals emit runs before it produces a byte:
+ * a `satisfies` claim naming
  * no declared requirement (a dangling join), and a `required` requirement no
  * member fills (an unfilled required requirement).
  *
@@ -86,7 +167,7 @@ function refuseBrokenSource(harness) {
             if (!requirements.has(name)) {
                 throw new Error(`member \`${member.name}\`: \`satisfies\` claims requirement \`${name}\`, which no ` +
                     `harness-level or member-published requirement declares — a dangling join ` +
-                    `(specs/architecture/20-surface.md, "Emit refuses before it writes").`);
+                    `(specs/model/pipeline.md, "Emit", the "Refusing" bullet).`);
             }
             filled.add(name);
         }
@@ -106,54 +187,94 @@ function refuseBrokenSource(harness) {
         if (!filled.has(name)) {
             throw new Error(`required requirement \`${name}\` (declared by ${source}) is filled by no member's ` +
                 `\`satisfies\` — an unfilled required requirement ` +
-                `(specs/architecture/20-surface.md, "Emit refuses before it writes").`);
+                `(specs/model/pipeline.md, "Emit", the "Refusing" bullet).`);
         }
     }
 }
-/** A member is projected iff its kind lives at a path locus (a genre member is not). */
+/**
+ * A fields-only registration member (a hook, an MCP server) surfaces embedded in a
+ * host manifest, so it owns no standalone artifact — its facts erase into a
+ * {@link RegistrationFact} for the manifest write face, never a projected member.
+ */
+function isRegistration(member) {
+    return member.facts.shape === "fields";
+}
+/**
+ * A member is projected iff its kind lives at a path locus and is not a fields-only
+ * registration member — an embedded member and a registration member each carry no
+ * standalone projection.
+ */
 function isProjected(member) {
-    return member.facts.locus.kind === "at";
+    return member.facts.locus.kind === "at" && !isRegistration(member);
 }
 /**
  * The resolved absolute path of a `file()` prose asset, or `undefined` for
  * `text`/`blocks` prose (or no prose) — the lift's own-path detection
- * (`specs/architecture/20-surface.md`, "surface authority is a declared
- * posture": the lock is what names a path a projection, so the engine needs
- * each `file()` member's true source path to tell a lifted member's own file
- * apart from a generated one).
+ * (drift: the lock is what names a path a
+ * projection, so the engine needs each `file()` member's true source path to
+ * tell a lifted member's own file apart from a generated one). Resolves
+ * against the declaring module's own `import.meta.url` (`prose.moduleUrl`),
+ * never the process cwd — the path is the stating module's, not the
+ * workspace's.
  */
-function fileSourcePath(member, options) {
+function fileSourcePath(member) {
     const prose = member.prose;
     if (prose?.kind !== "file")
         return undefined;
-    return resolvePath(options.baseDir ?? process.cwd(), prose.path);
+    return fileURLToPath(new URL(prose.path, prose.moduleUrl));
+}
+/**
+ * The harness's fields-only registration members as the public {@link RegistrationFact}
+ * view — the seam's own `registration` rows ({@link registrationRows}) mapped to the
+ * nested `collectionAddress` shape the `EmitResult` sibling exposes, so the two cannot
+ * disagree on what a manifest carries. Kind-then-key ordered so double emit is byte-stable.
+ *
+ * # Throws
+ * If a fields-only member declares no collection address — it surfaces in no manifest.
+ */
+function registrationFacts(harness) {
+    return registrationRows(harness).map((row) => ({
+        kind: row.kind,
+        key: row.key,
+        collectionAddress: { manifest: row.manifest, keyPath: row.key_path },
+        fields: row.fields,
+    }));
+}
+/**
+ * The harness's residual settings keys as the public {@link SettingsResidue} view — the
+ * seam's own `settings` rows ({@link settingsRows}) surfaced under the `EmitResult` sibling,
+ * so the two cannot disagree on what a manifest's residue carries. Key-sorted, the same
+ * byte-stable order the seam family takes.
+ */
+function settingsResidue(harness) {
+    return settingsRows(harness).map((row) => ({ manifest: row.manifest, key: row.key, value: row.value }));
 }
 /** The harness's projected members as payload members, deterministically kind-then-name ordered. */
 function orderedMembers(harness, options) {
     return [...harness.members]
         .filter(isProjected)
-        .sort((a, b) => (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) ||
-        (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+        .sort((a, b) => compareStrings(a.kind, b.kind) || compareStrings(a.name, b.name))
         .map((member) => ({
         kind: member.kind,
         name: member.name,
-        fields: member.fields,
+        // The generated row carries a mutable field list; the member's is read-only,
+        // so copy each pair into a fresh tuple — the same values, a shape the row accepts.
+        fields: member.fields.map(([name, value]) => [name, value]),
         body: resolveBody(member, options),
-        source_path: fileSourcePath(member, options),
+        source_path: fileSourcePath(member),
     }));
 }
 /**
  * Compile the whole face in one deterministic pass: the declaration rows (its
- * rollup and its five families) and every projected member's erased payload.
+ * rollup and its seven families) and every projected member's erased payload.
  * Prose resolves once (`file()` assets read in, mentions resolution-checked
  * against the harness's declared values). Double-emit verified — nondeterministic
- * authoring is a loud failure, never a silent churn (law 5).
+ * authoring is a loud failure, never a silent churn.
  */
-export function emit(harness, options = {}) {
+export function emit(harness) {
     refuseBrokenSource(harness);
     const resolve = {
         mentionable: declaredAddresses(harness),
-        baseDir: options.baseDir,
     };
     const compile = () => {
         const members = orderedMembers(harness, resolve);
@@ -161,8 +282,10 @@ export function emit(harness, options = {}) {
         return {
             declarations,
             members,
-            seam: JSON.stringify({ version: SEAM_VERSION, declarations, members }, null, 2) + "\n",
+            seam: encodeSeam({ declarations, members }),
             permissions: permissionUnion(harness.members.flatMap((member) => [...member.needs])),
+            registrations: registrationFacts(harness),
+            settings: settingsResidue(harness),
         };
     };
     const first = compile();

package/dist/src/generated/AssemblyFactRow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One assembly-scope fact — the root member's own declarations plus the
+ * graph edges the harness binds: a `fact` discriminator (`mode`, `edge`)
+ * plus the columns that fact carries. Absent columns are omitted from the
+ * lock, so each row round-trips to exactly what its producer wrote.
+ */
+export type AssemblyFactRow = {
+    /**
+     * The fact discriminator: `mode` or `edge`.
+     */
+    fact: string;
+    /**
+     * The scalar value a `mode` fact carries (the root member's declared
+     * enforcement mode).
+     */
+    value?: string;
+    /**
+     * An `edge` fact's source kind.
+     */
+    from?: string;
+    /**
+     * An `edge` fact's reference field.
+     */
+    field?: string;
+    /**
+     * An `edge` fact's target kind.
+     */
+    to?: string;
+};

package/dist/src/generated/AssemblyFactRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/BoundRow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A node-scope clause row's scalar bound — `min_len`'s `min`, `max_len`/`max_lines`'s
+ * `max`, each endpoint optional so the row carries only what the predicate declared.
+ */
+export type BoundRow = {
+    /**
+     * The inclusive lower bound, when the predicate declares one (`min_len`).
+     */
+    min?: number;
+    /**
+     * The inclusive upper bound, when the predicate declares one (`max_len`/`max_lines`).
+     */
+    max?: number;
+};

package/dist/src/generated/BoundRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/CharsetRow.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An `allowed_chars` clause row's declared character class — the wire form of
+ * [`crate::contract::Charset`]: inclusive `"<lo>-<hi>"` range specs plus a literal
+ * string of individually permitted characters.
+ */
+export type CharsetRow = {
+    /**
+     * The inclusive character ranges, each a two-character `"<lo>-<hi>"` spec.
+     */
+    ranges?: Array<string>;
+    /**
+     * The individually permitted characters, when any are declared.
+     */
+    chars?: string;
+};

package/dist/src/generated/CharsetRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/ClauseRow.d.ts

@@ -0,0 +1,97 @@
+import type { BoundRow } from "./BoundRow.js";
+import type { CharsetRow } from "./CharsetRow.js";
+import type { CountBoundRow } from "./CountBoundRow.js";
+import type { DegreeBoundRow } from "./DegreeBoundRow.js";
+import type { RangeBoundRow } from "./RangeBoundRow.js";
+import type { SectionContainsRow } from "./SectionContainsRow.js";
+/**
+ * One clause of a kind's effective contract, reduced to the columns the lock records:
+ * which kind it governs, the predicate's key, the field it targets (when it names one),
+ * its declared severity, its guidance and cite — the clause's four channels
+ * —
+ * and, per predicate, its own argument: the node-set/edge-scope predicates
+ * carry
+ * their bounds/target, and the node-scope predicates that need more than
+ * `field`/`severity` (`min_len`/`max_len`/`max_lines`'s bound, `allowed_chars`'s
+ * charset, `forbidden_keys`'s keys, `deny`'s values) carry theirs too — so a kind's
+ * own floor clause round-trips losslessly, not identity+severity alone.
+ * `unique`'s field rides the shared `field`
+ * column (the same slot `required`/`min_len`/… target); the rest carry their own
+ * optional columns since a plain field/severity pair cannot express them.
+ *
+ * Not `Eq`: the `range` column carries `f64` bounds ([`RangeBoundRow`]), so the
+ * whole clause-row family it rides is `PartialEq`-only — the same trade
+ * [`crate::contract::Predicate`] already makes for its own `Range` bounds.
+ */
+export type ClauseRow = {
+    /**
+     * The kind whose contract carries the clause. `None` when this row is nested
+     * inside a [`RequirementRow`]'s own [`clauses`](RequirementRow::clauses) — a
+     * requirement's set-scope demand names no kind of its own; it ranges over
+     * whatever kind the requirement's own row already carries.
+     */
+    kind?: string;
+    /**
+     * The predicate's clause key (`required`, `max_len`, …).
+     */
+    predicate: string;
+    /**
+     * The field (or marker) the predicate constrains, when it names one.
+     */
+    field?: string;
+    /**
+     * The clause's declared severity (`required` / `advisory`).
+     */
+    severity: string;
+    /**
+     * The just-in-time teaching channel — the best-practice prose the predicate
+     * cannot encode, quoted at the point of a failing finding.
+     */
+    guidance?: string;
+    /**
+     * The external-fact source backing the clause — a doc URL plus retrieved date,
+     * carried as data.
+     */
+    cite?: string;
+    /**
+     * The `count` clause's satisfier-set-size bound, when the predicate is `count`.
+     */
+    count?: CountBoundRow;
+    /**
+     * The `membership` clause's target requirement name, when the predicate is
+     * `membership`.
+     */
+    target?: string;
+    /**
+     * The `degree` clause's in/out edge-count bound, when the predicate is `degree`.
+     */
+    degree?: DegreeBoundRow;
+    /**
+     * The `min_len`/`max_len`/`max_lines` clause's scalar bound, when the predicate
+     * is one of those three.
+     */
+    bound?: BoundRow;
+    /**
+     * The `allowed_chars` clause's declared character class, when the predicate is
+     * `allowed_chars`.
+     */
+    charset?: CharsetRow;
+    /**
+     * The `forbidden_keys` clause's forbidden key list, when the predicate is
+     * `forbidden_keys`.
+     */
+    keys?: Array<string>;
+    /**
+     * The `deny` clause's forbidden value list, when the predicate is `deny`.
+     */
+    values?: Array<string>;
+    /**
+     * The `range` clause's inclusive numeric bound, when the predicate is `range`.
+     */
+    range?: RangeBoundRow;
+    /**
+     * The `section_contains` clause's heading prefix and required marker, when the
+     * predicate is `section_contains`.
+     */
+    section?: SectionContainsRow;
+};

package/dist/src/generated/ClauseRow.js

@@ -0,0 +1 @@
+export {};

package/dist/src/generated/CollectionAddressRow.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A kind's declared **collection address** row — the manifest a registration member
+ * surfaces in and the key path it keys at, the presence-coupled pair
+ * [`KindFactRow::collection_address`] carries. Absent from a [`KindFactRow`] means the
+ * kind owns its own file locus.
+ */
+export type CollectionAddressRow = {
+    /**
+     * The host manifest the registration surfaces in (`settings.json`, `.mcp.json`).
+     */
+    manifest: string;
+    /**
+     * The manifest key path the registration keys at (`hooks.<Event>`, `mcpServers.*`), a
+     * closed vocabulary the engine's kind lift rejects an unknown value from.
+     */
+    key_path: string;
+};

package/dist/src/generated/CollectionAddressRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/CollectionEntryRow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One entry belonging to one of a [`NestedMemberRow`]'s sibling collections: the
+ * collection name, the entry's own key, and its leaf fields — the row's
+ * flattened, order-preserving shape (`to_table`/`from_table` serialize the whole
+ * column as one array, the discipline every other array-shaped declaration
+ * family gets from `toml_edit`).
+ */
+export type CollectionEntryRow = {
+    /**
+     * The collection this entry belongs to.
+     */
+    collection: string;
+    /**
+     * The entry's key among its collection's siblings.
+     */
+    key: string;
+    /**
+     * The entry's own leaf fields, field name → authored string.
+     */
+    leaves: {
+        [key in string]: string;
+    };
+};

package/dist/src/generated/CollectionEntryRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/CollectionEntryWire.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One collection entry's wire shape as the SDK payload carries it, nested under
+ * its owning collection name — [`deserialize_collections`] copies the collection
+ * name onto each entry it flattens into a [`CollectionEntryRow`].
+ */
+export type CollectionEntryWire = {
+    /**
+     * The entry's key among its collection's siblings.
+     */
+    key: string;
+    /**
+     * The entry's own leaf fields, field name → resolved string.
+     */
+    leaves: {
+        [key in string]: string;
+    };
+};

package/dist/src/generated/CollectionEntryWire.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/src/generated/CountBoundRow.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A requirement row's `count` bound — the satisfier-set size's inclusive `[min, max]`.
+ */
+export type CountBoundRow = {
+    /**
+     * The inclusive lower bound on the satisfier-set size.
+     */
+    min: number;
+    /**
+     * The inclusive upper bound on the satisfier-set size.
+     */
+    max: number;
+};

package/dist/src/generated/CountBoundRow.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};