@dtmd/temper 0.0.1

package/dist/src/lock.js

@@ -0,0 +1,127 @@
+/**
+ * The lock — tool-written provenance, emit fingerprints, and the program's
+ * declaration rows (`specs/architecture/20-surface.md`, "The lock and drift").
+ * Two row families: a per-member `[[<kind>]]` rollup (`name`, `source_path`,
+ * `source_hash`, `emit_hash`) and the `[declaration]` table's four sub-families
+ * (`[[declaration.kind]]`, `[[declaration.clause]]`, `[[declaration.requirement]]`,
+ * `[[declaration.assembly]]`). Both are byte-identical to the Rust lock
+ * (`src/import.rs` `write_rollup`, `src/drift.rs` `Declarations::write_into`) — the
+ * byte-parity lockstep two writers keep until single-writer lands.
+ *
+ * Fingerprints are SHA-256 hex over raw UTF-8 (`hash::sha256_hex`), so an
+ * SDK-emitted lock and a Rust-emitted lock agree for the same harness.
+ */
+import { createHash } from "node:crypto";
+import { joinSections, keyValue, encodeString } from "./toml.js";
+/** Lowercase hex SHA-256 of `text`'s UTF-8 bytes — the Rust `sha256_hex` port. */
+export function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** The member name a projection encodes — the path's identity segment. */
+function projectionName(projection) {
+    const segments = projection.path.split("/");
+    const last = segments[segments.length - 1];
+    if (last === "SKILL.md")
+        return segments[segments.length - 2];
+    return last.replace(/\.md$/, "");
+}
+/**
+ * The rollup row a projection stamps: both fingerprints are `sha256(projection
+ * bytes)`, the fresh-emit baseline (`source_hash == emit_hash`) a Rust import then
+ * emit lands on for a byte-identical projection.
+ */
+export function lockRow(kind, projection) {
+    const hash = sha256Hex(projection.bytes);
+    return {
+        kind,
+        name: projectionName(projection),
+        sourcePath: projection.path,
+        sourceHash: hash,
+        emitHash: hash,
+    };
+}
+/** The rollup sections — one `[[<kind>]]` table per member, kinds then rows name-sorted. */
+function rollupSections(rows) {
+    const byKind = new Map();
+    for (const row of rows) {
+        const bucket = byKind.get(row.kind);
+        if (bucket)
+            bucket.push(row);
+        else
+            byKind.set(row.kind, [row]);
+    }
+    const sections = [];
+    for (const kind of [...byKind.keys()].sort()) {
+        const kindRows = byKind
+            .get(kind)
+            .slice()
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const row of kindRows) {
+            sections.push(`[[${kind}]]\n` +
+                keyValue("name", encodeString(row.name)) +
+                keyValue("source_path", encodeString(row.sourcePath)) +
+                keyValue("source_hash", encodeString(row.sourceHash)) +
+                keyValue("emit_hash", encodeString(row.emitHash)));
+        }
+    }
+    return sections;
+}
+/** A `key = "value"\n` line for a present string column, or "" to omit an absent one. */
+function optionalColumn(key, value) {
+    return value === undefined ? "" : keyValue(key, encodeString(value));
+}
+/**
+ * The `[declaration]` table's sections, in the fixed family order kind · clause ·
+ * requirement · assembly, each row a `[[declaration.<family>]]` table with its
+ * columns in the Rust `to_table` order. An empty family writes nothing — an empty
+ * array vanishes on the toml round-trip.
+ */
+function declarationSections(declarations) {
+    const sections = [];
+    for (const row of declarations.kinds) {
+        sections.push("[[declaration.kind]]\n" +
+            keyValue("name", encodeString(row.name)) +
+            optionalColumn("provider", row.provider) +
+            keyValue("governs_root", encodeString(row.governs_root)) +
+            keyValue("governs_glob", encodeString(row.governs_glob)) +
+            optionalColumn("format", row.format) +
+            optionalColumn("unit_shape", row.unit_shape) +
+            optionalColumn("activation", row.activation));
+    }
+    for (const row of declarations.clauses) {
+        sections.push("[[declaration.clause]]\n" +
+            keyValue("kind", encodeString(row.kind)) +
+            keyValue("predicate", encodeString(row.predicate)) +
+            optionalColumn("field", row.field) +
+            keyValue("severity", encodeString(row.severity)));
+    }
+    for (const row of declarations.requirements) {
+        sections.push("[[declaration.requirement]]\n" +
+            keyValue("name", encodeString(row.name)) +
+            optionalColumn("kind", row.kind) +
+            optionalColumn("package", row.package) +
+            keyValue("required", row.required ? "true" : "false") +
+            optionalColumn("verified_by", row.verified_by));
+    }
+    for (const row of declarations.assembly) {
+        sections.push("[[declaration.assembly]]\n" +
+            keyValue("fact", encodeString(row.fact)) +
+            optionalColumn("value", row.value) +
+            optionalColumn("from", row.from) +
+            optionalColumn("field", row.field) +
+            optionalColumn("to", row.to));
+    }
+    return sections;
+}
+/**
+ * Serialize the lock — the rollup rows then the declaration families, joined the
+ * `toml_edit` way (exactly one blank line before every table header but the
+ * document's first). An all-empty declaration set contributes no sections, so a
+ * memberless lock is empty and a rollup-only lock carries no `[declaration]` rows.
+ */
+export function stampLock(rows, declarations) {
+    const sections = [...rollupSections(rows)];
+    if (declarations !== undefined)
+        sections.push(...declarationSections(declarations));
+    return joinSections(sections);
+}

package/dist/src/needs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Needs — the capabilities a member's behavior uses, declared as typed values
+ * (`specs/architecture/20-surface.md`, "The member"; "Emit — total"). Emit derives
+ * the settings permission list from their union, so a permission is never authored
+ * twice: `permissions.allow` is the union of the members' declared `needs`, and a
+ * permission with no member is visible as exactly that (the derived-list Decision).
+ */
+/** A declared capability — its `permission` is the entry it derives in the union. */
+export interface Capability {
+    /**
+     * The permission-list entry this capability derives. The union of every
+     * member's needs is the settings `permissions.allow` — the fold hooks and MCP
+     * members ride into once those kinds land (`20-surface.md`, "Emit — total").
+     */
+    readonly permission: string;
+}
+/**
+ * A shell-command capability. Its derived permission is the Claude Code allow
+ * entry `Bash(<command>)` (code.claude.com/docs/en/settings, retrieved
+ * 2026-07-04) — the port scene's `bash("git diff")` (`20-surface.md`).
+ */
+export declare function bash(command: string): Capability;
+/** Any capability whose permission entry the author states verbatim. */
+export declare function capability(permission: string): Capability;
+/**
+ * The derived permission list — the union of every capability's entry, deduped
+ * and sorted so the derived artifact is byte-stable across runs (law 5). The
+ * permission is derived here, never authored (`20-surface.md`, the derived-list
+ * Decision).
+ */
+export declare function permissionUnion(needs: readonly Capability[]): string[];

package/dist/src/needs.js

@@ -0,0 +1,28 @@
+/**
+ * Needs — the capabilities a member's behavior uses, declared as typed values
+ * (`specs/architecture/20-surface.md`, "The member"; "Emit — total"). Emit derives
+ * the settings permission list from their union, so a permission is never authored
+ * twice: `permissions.allow` is the union of the members' declared `needs`, and a
+ * permission with no member is visible as exactly that (the derived-list Decision).
+ */
+/**
+ * A shell-command capability. Its derived permission is the Claude Code allow
+ * entry `Bash(<command>)` (code.claude.com/docs/en/settings, retrieved
+ * 2026-07-04) — the port scene's `bash("git diff")` (`20-surface.md`).
+ */
+export function bash(command) {
+    return { permission: `Bash(${command})` };
+}
+/** Any capability whose permission entry the author states verbatim. */
+export function capability(permission) {
+    return { permission };
+}
+/**
+ * The derived permission list — the union of every capability's entry, deduped
+ * and sorted so the derived artifact is byte-stable across runs (law 5). The
+ * permission is derived here, never authored (`20-surface.md`, the derived-list
+ * Decision).
+ */
+export function permissionUnion(needs) {
+    return [...new Set(needs.map((need) => need.permission))].sort();
+}

package/dist/src/project.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Projection — emit compiles each member to its harness format under `.claude/**`,
+ * whole-file and byte-faithful (`specs/architecture/20-surface.md`, "Emit —
+ * total"). A member with frontmatter fields projects to a fresh `---`-delimited
+ * block over its resolved body; a frontmatterless kind (memory) projects to its
+ * body alone. The words are the author's, untouched — emit never stamps metadata
+ * into the projection (law 5); the managed-by note and the schema modeline ride
+ * `install`, and a re-emit round-trips them through the whole-file write.
+ *
+ * The locus and layout come from the kind's five facts (`15-kinds.md`), never a
+ * hardcoded kind name: a directory unit lands its entry file under a per-member
+ * directory, a lone file lands at the stem, a frontmatterless any-depth memory
+ * lands the root `<name>.md`.
+ */
+import type { KindFacts } from "./kind.js";
+/** One projected harness file: where it lands and the byte-faithful content. */
+export interface Projection {
+    /** The slash path relative to the harness root (`.claude/**`, or a root memory). */
+    readonly path: string;
+    /** The whole-file projection bytes — frontmatter (if any) over the body. */
+    readonly bytes: string;
+}
+/** The resolved member emit hands the projector — facts, name, ordered fields, resolved body. */
+export interface ProjectionInput {
+    readonly facts: KindFacts;
+    readonly name: string;
+    readonly fields: ReadonlyArray<readonly [string, unknown]>;
+    readonly body: string;
+}
+/** Emit-time inputs beyond the member — where install's placements are read from. */
+export interface ProjectOptions {
+    /**
+     * The harness root the **committed** projection is read from to carry install's
+     * frontmatter placements (the schema modeline + managed-by note) through the
+     * whole-file re-emit — the two-projectors seam. Absent — or an absent committed
+     * file — carries no placements: emit writes the projection fresh.
+     */
+    readonly projectionDir?: string;
+}
+/**
+ * The install-placed frontmatter comment lines present in `source`, in on-disk
+ * order — the schema modeline and the managed-by note. `emit` round-trips these
+ * through its whole-file re-emit so its content-faithful projection (law 5)
+ * carries install's metadata instead of dropping it (`20-surface.md`).
+ */
+export declare function placementLines(source: string): string[];
+/**
+ * The harness locus a member of `facts` named `name` projects onto, derived from
+ * the kind's locus and unit shape (`15-kinds.md`): a directory unit lands its
+ * entry file under `<root>/<name>/`; a lone file replaces the glob's `*` with the
+ * name (an any-depth memory lands the root `<name>.md`).
+ *
+ * # Throws
+ * If the kind is a genre — a block-locus member has no standalone projection.
+ */
+export declare function projectionPath(facts: KindFacts, name: string): string;
+/**
+ * One frontmatter field as `key: <value>\n`, or `null` to omit a null/undefined
+ * value. The value is compact JSON — valid YAML flow, round-tripping to the same
+ * JSON on the next parse — matching the Rust `render_field` (`serde_json::to_string`).
+ */
+export declare function renderField(key: string, value: unknown): string | null;
+/**
+ * The whole-file projection bytes for one member: no surviving field ⇒ the body
+ * alone (no frontmatter block, so no place a modeline/note could sit); one or
+ * more ⇒ a fresh `---` frontmatter (install's preserved `placements` first, then
+ * every field in order) over the byte-faithful body.
+ */
+export declare function projectBytes(fields: ReadonlyArray<readonly [string, unknown]>, body: string, placements?: readonly string[]): string;
+/**
+ * Project one resolved member onto its harness file — its locus and the whole-file
+ * bytes. With `options.projectionDir` set, install's placement lines ride through
+ * the re-emit (the two-projectors seam).
+ *
+ * # Throws
+ * If the member's kind is a genre ([`projectionPath`]), or the committed projection
+ * cannot be read for a reason other than absence.
+ */
+export declare function projectMember(member: ProjectionInput, options?: ProjectOptions): Projection;

package/dist/src/project.js

@@ -0,0 +1,162 @@
+/**
+ * Projection — emit compiles each member to its harness format under `.claude/**`,
+ * whole-file and byte-faithful (`specs/architecture/20-surface.md`, "Emit —
+ * total"). A member with frontmatter fields projects to a fresh `---`-delimited
+ * block over its resolved body; a frontmatterless kind (memory) projects to its
+ * body alone. The words are the author's, untouched — emit never stamps metadata
+ * into the projection (law 5); the managed-by note and the schema modeline ride
+ * `install`, and a re-emit round-trips them through the whole-file write.
+ *
+ * The locus and layout come from the kind's five facts (`15-kinds.md`), never a
+ * hardcoded kind name: a directory unit lands its entry file under a per-member
+ * directory, a lone file lands at the stem, a frontmatterless any-depth memory
+ * lands the root `<name>.md`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The schema modeline marker install places and emit preserves (`src/install.rs`). */
+const MODELINE_MARKER = "# yaml-language-server:";
+/** The managed-by note's stable marker (`src/install.rs`). */
+const NOTE_MARKER = "# temper: managed projection";
+/** Whether `line` is one of install's managed metadata comments. */
+function isPlacementComment(line) {
+    const trimmed = line.replace(/^\s+/, "");
+    return trimmed.startsWith(MODELINE_MARKER) || trimmed.startsWith(NOTE_MARKER);
+}
+/**
+ * A string's lines the Rust `str::lines` way: split on `\n`, a trailing newline
+ * opens no line, a trailing `\r` is stripped from each.
+ */
+function lines(textValue) {
+    if (textValue === "")
+        return [];
+    const parts = textValue.split("\n");
+    if (parts[parts.length - 1] === "")
+        parts.pop();
+    return parts.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+}
+/**
+ * The frontmatter interior of `rest` — everything after the opening `---\n` up to
+ * the closing `---` line — or `null` when there is no closing delimiter (an
+ * opening `---` that is really prose). A port of the Rust `install::frontmatter_inner`.
+ */
+function frontmatterInner(rest) {
+    let offset = 0;
+    let cursor = 0;
+    while (cursor < rest.length) {
+        const newline = rest.indexOf("\n", cursor);
+        const end = newline === -1 ? rest.length : newline + 1;
+        const piece = rest.slice(cursor, end);
+        const content = piece.endsWith("\n") ? piece.slice(0, -1) : piece;
+        if (content.replace(/\s+$/, "") === "---")
+            return rest.slice(0, offset);
+        offset += piece.length;
+        cursor = end;
+    }
+    return null;
+}
+/**
+ * The install-placed frontmatter comment lines present in `source`, in on-disk
+ * order — the schema modeline and the managed-by note. `emit` round-trips these
+ * through its whole-file re-emit so its content-faithful projection (law 5)
+ * carries install's metadata instead of dropping it (`20-surface.md`).
+ */
+export function placementLines(source) {
+    if (!source.startsWith("---\n"))
+        return [];
+    const inner = frontmatterInner(source.slice("---\n".length));
+    if (inner === null)
+        return [];
+    return lines(inner).filter(isPlacementComment);
+}
+/** Join non-empty, non-`.` path segments with `/` — a `.` root drops out (root memory). */
+function joinSlash(...parts) {
+    return parts.filter((part) => part !== "" && part !== ".").join("/");
+}
+/**
+ * The harness locus a member of `facts` named `name` projects onto, derived from
+ * the kind's locus and unit shape (`15-kinds.md`): a directory unit lands its
+ * entry file under `<root>/<name>/`; a lone file replaces the glob's `*` with the
+ * name (an any-depth memory lands the root `<name>.md`).
+ *
+ * # Throws
+ * If the kind is a genre — a block-locus member has no standalone projection.
+ */
+export function projectionPath(facts, name) {
+    if (facts.locus.kind !== "at") {
+        throw new Error(`kind \`${facts.name}\` is a genre — its members live inside host documents ` +
+            `and have no standalone projection (specs/architecture/15-kinds.md).`);
+    }
+    const { root, glob } = facts.locus;
+    if (facts.unitShape === "directory") {
+        // `*/SKILL.md` → the entry file after the first slash, under a per-member dir.
+        const entry = glob.slice(glob.indexOf("/") + 1);
+        return joinSlash(root, name, entry);
+    }
+    // A lone file: any-depth glob (`**/CLAUDE.md`) is the root `<name>.md`; a simple
+    // glob (`*.md`) replaces its single star with the name.
+    const filename = glob.includes("**") ? `${name}.md` : glob.replace("*", name);
+    return joinSlash(root, filename);
+}
+/**
+ * One frontmatter field as `key: <value>\n`, or `null` to omit a null/undefined
+ * value. The value is compact JSON — valid YAML flow, round-tripping to the same
+ * JSON on the next parse — matching the Rust `render_field` (`serde_json::to_string`).
+ */
+export function renderField(key, value) {
+    if (value === null || value === undefined)
+        return null;
+    return `${key}: ${JSON.stringify(value)}\n`;
+}
+/**
+ * The whole-file projection bytes for one member: no surviving field ⇒ the body
+ * alone (no frontmatter block, so no place a modeline/note could sit); one or
+ * more ⇒ a fresh `---` frontmatter (install's preserved `placements` first, then
+ * every field in order) over the byte-faithful body.
+ */
+export function projectBytes(fields, body, placements = []) {
+    const rendered = fields
+        .map(([key, value]) => renderField(key, value))
+        .filter((line) => line !== null);
+    if (rendered.length === 0)
+        return body;
+    const frontmatter = placements.map((line) => `${line}\n`).join("") + rendered.join("");
+    return `---\n${frontmatter}---\n${body}`;
+}
+/**
+ * Read the install-placed frontmatter lines from the committed projection at
+ * `projectionDir/path`, or `[]` when none is read (no `projectionDir`, or the file
+ * is absent — emit writes it fresh). Reads are of committed bytes, never a clock,
+ * so the double-emit purity check still holds.
+ *
+ * # Throws
+ * On a read failure that is not "file absent".
+ */
+function committedPlacements(projectionDir, path) {
+    if (projectionDir === undefined)
+        return [];
+    try {
+        return placementLines(readFileSync(join(projectionDir, path), "utf8"));
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return [];
+        throw new Error(`failed to read committed projection \`${path}\` under \`${projectionDir}\`.`, {
+            cause,
+        });
+    }
+}
+/**
+ * Project one resolved member onto its harness file — its locus and the whole-file
+ * bytes. With `options.projectionDir` set, install's placement lines ride through
+ * the re-emit (the two-projectors seam).
+ *
+ * # Throws
+ * If the member's kind is a genre ([`projectionPath`]), or the committed projection
+ * cannot be read for a reason other than absence.
+ */
+export function projectMember(member, options = {}) {
+    const path = projectionPath(member.facts, member.name);
+    const placements = committedPlacements(options.projectionDir, path);
+    return { path, bytes: projectBytes(member.fields, member.body, placements) };
+}

package/dist/src/prose.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Prose — three constructors, one field type (`specs/architecture/20-surface.md`,
+ * "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 genre values. Whatever
+ * the constructor, the words land byte-identical to their authored text (law 5).
+ * Interpolations in `` text`…` `` are **mentions** — declared one-way edges,
+ * authored per word, resolution-checked at emit, never mined (law 8).
+ */
+import type { GenreValue } from "./genres.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). */
+    readonly address: string;
+    /** The display text the one corpus-wide rule renders in place. */
+    readonly display: string;
+}
+/** One authored interpolation: position in the template plus its target. */
+export interface Mention {
+    readonly index: number;
+    readonly target: Mentionable;
+}
+/**
+ * `file(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.
+ */
+export interface File {
+    readonly kind: "file";
+    /** Module-relative path to the authored document. */
+    readonly path: string;
+}
+/**
+ * `` 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).
+ */
+export interface Text {
+    readonly kind: "text";
+    /** The dedented authored text with one {@link MENTION_SLOT} per mention, in order. */
+    readonly template: string;
+    readonly mentions: readonly Mention[];
+}
+/**
+ * `blocks(…)` — fully composed genre values (posture 3): typed collections whose
+ * emitted document is pure render, byte-identical to the same values authored as
+ * fences (posture 2). The shared fence format is `(genre-fence-format)`, deferred
+ * until its first consumer lands (`15-kinds.md`), so a `blocks()` body composes
+ * now and renders when the pilot does — emit refuses to project one until then,
+ * never guessing a format.
+ */
+export interface Blocks {
+    readonly kind: "blocks";
+    readonly values: readonly GenreValue[];
+}
+/** 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). */
+export declare function file(path: string): File;
+/**
+ * The inline dedenting prose constructor. Interpolate only {@link Mentionable}
+ * values — each interpolation is a mention, opt-in per word; plain prose with
+ * zero mentions is fully legal forever (the opt-in Decision, `20-surface.md`).
+ *
+ * # Throws
+ * If an authored chunk contains {@link MENTION_SLOT} — the marker must be the
+ * tool's alone, so a stray NUL is a loud authoring error, not a silent mis-split.
+ */
+export declare function text(strings: TemplateStringsArray, ...targets: Mentionable[]): Text;
+/** Compose fully-typed genre values into a member's body (posture 3). */
+export declare function blocks(...values: GenreValue[]): Blocks;
+/**
+ * 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
+ * construction, so the walk consumes every slot.
+ */
+export declare function renderText(prose: Text): string;

package/dist/src/toml.d.ts

@@ -0,0 +1,26 @@
+/**
+ * TOML value/key encoding and table layout — a faithful port of `toml_write`
+ * 0.1.2 (`src/string.rs`) and `toml_edit` 0.22.27's `visit_table`
+ * (`specs/architecture/20-surface.md`, "Content-faithful, deterministically
+ * emitted (law 5)"). Shared by the manifest emitter (`emit.ts`) and the lock
+ * stamper (`lock.ts`) so every `key = value` line and every table header the SDK
+ * writes is byte-identical to the Rust `toml_edit` output — the manifest, the
+ * projection frontmatter, and the lock all agree to the byte.
+ */
+/** A TOML string *value* — the exact bytes `toml_edit`'s `value(String)` emits. */
+export declare function encodeString(s: string): string;
+/** A TOML *key* — bare where it can be, else `toml_edit`'s `TomlKeyBuilder::as_default`. */
+export declare function encodeKey(s: string): string;
+/** One `key = value\n` line, the key/value decor `toml_edit` renders (`key = value`). */
+export declare function keyValue(key: string, valueRepr: string): string;
+/** A TOML string array — `["a", "b"]`, no leading space, `, ` between elements. */
+export declare function stringArray(values: readonly string[]): string;
+/** Sorted keys — the stable order `toml_edit` gets for free from its `BTreeMap`s. */
+export declare function sortedKeys(record: Readonly<Record<string, unknown>>): string[];
+/**
+ * Join an ordered list of table sections the `toml_edit` way — exactly one blank
+ * line before every table header but the document's first
+ * (`DEFAULT_TABLE_DECOR = ("\n", "")`, the first table `("", …)`). Each section is
+ * a header line plus its `key = value\n` lines, already newline-terminated.
+ */
+export declare function joinSections(sections: readonly string[]): string;