wyrd-scribe 0.1.0

package/dist/frontmatter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * B2 — THE OPT-IN FRONTMATTER STAMP. Line-based, and it REFUSES rather than merging.
+ *
+ * ⚠⚠ NO YAML PARSER AND NO AST MERGE, AND THAT IS A SECURITY DECISION RATHER THAN A DEPENDENCY ONE.
+ * Parsing a stranger's frontmatter means running a YAML parser over untrusted text on the write
+ * path — YAML's own history of anchor-expansion and tag-resolution defects is why that is not a
+ * free operation — and then RE-EMITTING their document from an AST, which rewrites quoting,
+ * ordering, comments and anchors in a file the user did not ask us to reformat. D3's justification
+ * for writing into someone else's notes is that the act is benign and disclosed; silently
+ * reserialising their frontmatter is neither.
+ *
+ * So this module does the smallest thing that can be correct: it finds the block's boundary LINES
+ * and inserts ONE line. Anything it cannot do that way it REFUSES.
+ *
+ * ⚠⚠ THE PROJECTION CARRIES NO `page` KEY AT ALL, AND THE FULL REASON IS WORTH THE PARAGRAPH,
+ * because the shape it replaces looked correct and was measurably wrong.
+ *
+ * It used to omit `page.content` and keep `page.identity`, on the argument that only the DIGEST is
+ * self-referential: the frontmatter becomes part of the page bytes, so a projection containing the
+ * page's own digest would have to be computed from bytes that do not exist until it is inserted.
+ * That argument is sound and it does not go far enough — the IDENTITY is unrecordable here for a
+ * different reason, and the two together leave nothing of `page` behind.
+ *
+ * The projection is built from the DRAFT record, whose page path is the CALLER'S SPELLING, because
+ * the fence has not resolved the target yet and will not until the create. The ledger line is
+ * rebuilt afterwards from the fence's canonical `created.rel`. So a write through an in-grant
+ * junction — `Alias/answer.md` resolving to `Mage/answer.md` — put `Alias/answer.md` in the page
+ * and `Mage/answer.md` in the ledger: TWO PROVENANCE RECORDS FOR ONE WRITE, DISAGREEING ABOUT WHICH
+ * PAGE THIS IS. A reader with both cannot tell which is the page's identity, and the one embedded
+ * in the bytes is the one that travels with the file.
+ *
+ * The fix is not to defer the projection until the canonical path is known — that would mean
+ * composing the page bytes after creating the page, which inverts the ordering `stamp.ts`'s header
+ * spends its length defending. It is that A PAGE DOES NOT NEED TO NAME ITSELF INSIDE ITSELF. The
+ * projection's job is to carry the SOURCES — their identities, hashes and spans — plus the schema
+ * and vault fields that make those readable. Page identity has exactly one home, the ledger, which
+ * is where the canonical path is known and where a consumer already looks for it.
+ *
+ * ⚠ ONE KEY, `wyrd_lineage`, HOLDING SINGLE-LINE JSON. JSON is a subset of YAML 1.2, so a flow-style
+ * value on one line parses under any conformant reader without this module emitting block scalars,
+ * indentation or line folding — three things a hand-rolled emitter gets wrong and a diff makes
+ * unreadable. It also keeps the insertion to exactly one line, which is what makes the "find the
+ * closing fence and insert above it" rule sound.
+ */
+import type { LineageRecord } from './lineage.js';
+import type { ScribeRefusal } from './refusal.js';
+export declare const FRONTMATTER_KEY = "wyrd_lineage";
+/**
+ * How far in we look for the closing `---`.
+ *
+ * ⚠ A BOUND, NOT A GUESS AT REAL DOCUMENTS. Without one, content that merely OPENS with `---` and
+ * never closes makes this scan the whole file to decide it has no frontmatter — an unbounded read
+ * of caller-supplied bytes on the write path, for a question about the document's first few lines.
+ * A block longer than this refuses; it does not get treated as absent, because treating it as
+ * absent would PREPEND a second block and produce a document with two.
+ */
+export declare const MAX_FRONTMATTER_LINES = 200;
+/**
+ * The record as it appears in the page: the SOURCES, and the fields that make them readable.
+ *
+ * ⚠ NO `page` MEMBER, AND ITS ABSENCE IS THE TYPE ENFORCING THE RULE ABOVE — a later session that
+ * decides the page should name itself has to widen this interface deliberately rather than by
+ * adding a line to `project`.
+ */
+export interface FrontmatterProjection {
+    readonly schema: string;
+    readonly event: string;
+    readonly event_id: string;
+    readonly recorded_at: string;
+    readonly writer: LineageRecord['writer'];
+    readonly vault: LineageRecord['vault'];
+    readonly sources: LineageRecord['sources'];
+}
+/**
+ * ⚠ `event_id` IS CARRIED AND THE PAGE PATH IS NOT, WHICH IS THE ASYMMETRY WORTH NAMING. The id is
+ * the one field that JOINS this projection to its ledger line — without it a reader holding a
+ * stamped page and a ledger of many lines has only the timestamp to match on, and `ST29` exists
+ * because a timestamp does not distinguish two writes. It is server-minted per write, so it says
+ * nothing about the path and cannot disagree with the fence about anything.
+ */
+export declare function project(record: LineageRecord): FrontmatterProjection;
+/**
+ * Insert the stamp, or refuse.
+ *
+ * `content` is the caller's page text; the return carries the bytes to write.
+ */
+export declare function stamp(content: string, projection: FrontmatterProjection): string | ScribeRefusal;

package/dist/frontmatter.js

@@ -0,0 +1,302 @@
+/**
+ * B2 — THE OPT-IN FRONTMATTER STAMP. Line-based, and it REFUSES rather than merging.
+ *
+ * ⚠⚠ NO YAML PARSER AND NO AST MERGE, AND THAT IS A SECURITY DECISION RATHER THAN A DEPENDENCY ONE.
+ * Parsing a stranger's frontmatter means running a YAML parser over untrusted text on the write
+ * path — YAML's own history of anchor-expansion and tag-resolution defects is why that is not a
+ * free operation — and then RE-EMITTING their document from an AST, which rewrites quoting,
+ * ordering, comments and anchors in a file the user did not ask us to reformat. D3's justification
+ * for writing into someone else's notes is that the act is benign and disclosed; silently
+ * reserialising their frontmatter is neither.
+ *
+ * So this module does the smallest thing that can be correct: it finds the block's boundary LINES
+ * and inserts ONE line. Anything it cannot do that way it REFUSES.
+ *
+ * ⚠⚠ THE PROJECTION CARRIES NO `page` KEY AT ALL, AND THE FULL REASON IS WORTH THE PARAGRAPH,
+ * because the shape it replaces looked correct and was measurably wrong.
+ *
+ * It used to omit `page.content` and keep `page.identity`, on the argument that only the DIGEST is
+ * self-referential: the frontmatter becomes part of the page bytes, so a projection containing the
+ * page's own digest would have to be computed from bytes that do not exist until it is inserted.
+ * That argument is sound and it does not go far enough — the IDENTITY is unrecordable here for a
+ * different reason, and the two together leave nothing of `page` behind.
+ *
+ * The projection is built from the DRAFT record, whose page path is the CALLER'S SPELLING, because
+ * the fence has not resolved the target yet and will not until the create. The ledger line is
+ * rebuilt afterwards from the fence's canonical `created.rel`. So a write through an in-grant
+ * junction — `Alias/answer.md` resolving to `Mage/answer.md` — put `Alias/answer.md` in the page
+ * and `Mage/answer.md` in the ledger: TWO PROVENANCE RECORDS FOR ONE WRITE, DISAGREEING ABOUT WHICH
+ * PAGE THIS IS. A reader with both cannot tell which is the page's identity, and the one embedded
+ * in the bytes is the one that travels with the file.
+ *
+ * The fix is not to defer the projection until the canonical path is known — that would mean
+ * composing the page bytes after creating the page, which inverts the ordering `stamp.ts`'s header
+ * spends its length defending. It is that A PAGE DOES NOT NEED TO NAME ITSELF INSIDE ITSELF. The
+ * projection's job is to carry the SOURCES — their identities, hashes and spans — plus the schema
+ * and vault fields that make those readable. Page identity has exactly one home, the ledger, which
+ * is where the canonical path is known and where a consumer already looks for it.
+ *
+ * ⚠ ONE KEY, `wyrd_lineage`, HOLDING SINGLE-LINE JSON. JSON is a subset of YAML 1.2, so a flow-style
+ * value on one line parses under any conformant reader without this module emitting block scalars,
+ * indentation or line folding — three things a hand-rolled emitter gets wrong and a diff makes
+ * unreadable. It also keeps the insertion to exactly one line, which is what makes the "find the
+ * closing fence and insert above it" rule sound.
+ */
+import { scribeRefuse } from './refusal.js';
+export const FRONTMATTER_KEY = 'wyrd_lineage';
+/**
+ * How far in we look for the closing `---`.
+ *
+ * ⚠ A BOUND, NOT A GUESS AT REAL DOCUMENTS. Without one, content that merely OPENS with `---` and
+ * never closes makes this scan the whole file to decide it has no frontmatter — an unbounded read
+ * of caller-supplied bytes on the write path, for a question about the document's first few lines.
+ * A block longer than this refuses; it does not get treated as absent, because treating it as
+ * absent would PREPEND a second block and produce a document with two.
+ */
+export const MAX_FRONTMATTER_LINES = 200;
+/**
+ * ⚠ `event_id` IS CARRIED AND THE PAGE PATH IS NOT, WHICH IS THE ASYMMETRY WORTH NAMING. The id is
+ * the one field that JOINS this projection to its ledger line — without it a reader holding a
+ * stamped page and a ledger of many lines has only the timestamp to match on, and `ST29` exists
+ * because a timestamp does not distinguish two writes. It is server-minted per write, so it says
+ * nothing about the path and cannot disagree with the fence about anything.
+ */
+export function project(record) {
+    return {
+        schema: record.schema,
+        event: record.event,
+        event_id: record.event_id,
+        recorded_at: record.recorded_at,
+        writer: record.writer,
+        vault: record.vault,
+        sources: record.sources
+    };
+}
+/**
+ * ⚠⚠ THE LINE SCAN IS OVER `\n` AND TOLERATES `\r`, because a document authored on Windows has
+ * CRLF endings and a scan that only knows `\n` sees the closing fence as `"---\r"`, fails to match
+ * it, and refuses `FRONTMATTER_INVALID` on a perfectly ordinary file. Trimming only the trailing
+ * `\r` — never other whitespace — keeps the match exact in every other respect: ` ---` is NOT a
+ * fence in YAML and must not be treated as one.
+ */
+function isFence(line) {
+    return (line.endsWith('\r') ? line.slice(0, -1) : line) === '---';
+}
+/**
+ * The key a mapping line declares, or `null` if the line declares none AT THE TOP LEVEL.
+ *
+ * ⚠⚠ THE INDENTATION TEST IS THE ONLY THING SEPARATING A TOP-LEVEL KEY FROM A NESTED ONE, AND IT
+ * HAD TO BE MADE SO. The first version sliced the key WITHOUT trimming, so an indented
+ * `  wyrd_lineage:` yielded the string `"  wyrd_lineage"`, which never equalled the key anyway —
+ * two guards where one was doing the work, and the mutation matrix measured exactly that: removing
+ * the indentation test left the suite green (`M14`, a real survivor). The name is trimmed first now,
+ * so the test is load-bearing and the mutant dies. A guard that is masked by an incidental
+ * mismatch is a guard nothing is checking.
+ */
+function keyOf(line) {
+    const body = line.endsWith('\r') ? line.slice(0, -1) : line;
+    // ⚠ Only a TOP-LEVEL key counts for the conflict check: an indented `wyrd_lineage:` is a member
+    // of someone else's mapping and is not ours to collide with. A leading space disqualifies it.
+    if (/^\s/.test(body))
+        return null;
+    const colon = body.indexOf(':');
+    if (colon <= 0)
+        return null;
+    return unquote(body.slice(0, colon).trim());
+}
+/**
+ * ⚠⚠ `"wyrd_lineage"`, `'wyrd_lineage'` AND `wyrd_lineage` ARE ONE KEY IN YAML, AND UNTIL THIS
+ * EXISTED THE CONFLICT CHECK SAW THREE. MEASURED 2026-09-03, not reasoned: stamping a page whose
+ * frontmatter carried `"wyrd_lineage": {...}` did not refuse — it WROTE, leaving a document with
+ * TWO top-level `wyrd_lineage` keys. That is invalid YAML, and the ordinary parser response is to
+ * take one and silently drop the other, so the user's existing provenance record is destroyed
+ * without a refusal, an error, or a visible mark. `FRONTMATTER_CONFLICT` exists for exactly that
+ * case and was being routed around by a quote character.
+ *
+ * ⚠ IT STRIPS A MATCHED PAIR AND NOTHING MORE, AND THE NARROWNESS IS THE DESIGN. This module's
+ * founding rule is that it does not run a YAML parser over a stranger's frontmatter on the write
+ * path, so full scalar semantics — escape sequences, multi-line keys, flow keys — are deliberately
+ * NOT handled here. What is handled is the spelling a stamp or a person actually produces.
+ *
+ * ⚠ THE FAILURE DIRECTION IS THE SAFE ONE EITHER WAY. An exotic spelling this does not recognise
+ * falls back to today's behaviour, which is the bug and no worse than it. There is no spelling on
+ * which this makes the module refuse a document it should have written: an unmatched or absent
+ * quote returns the name unchanged.
+ */
+function unquote(name) {
+    if (name.length < 2)
+        return name;
+    const first = name[0];
+    if ((first === '"' || first === "'") && name.endsWith(first)) {
+        return name.slice(1, -1);
+    }
+    return name;
+}
+/**
+ * ⚠⚠ A FIRST-LINE `---` IS NOT ENOUGH TO CALL SOMETHING FRONTMATTER, and the version that believed
+ * it was mishandled ordinary documents in two directions.
+ *
+ * A Markdown document may legitimately OPEN with a horizontal rule. Under the old rule that first
+ * line was an opening fence, so:
+ *
+ *   · a document opening with a rule and then prose was refused `FRONTMATTER_INVALID` — a
+ *     perfectly ordinary file the user could never write through this server, with a message
+ *     saying their frontmatter had no closing fence when they had written no frontmatter at all;
+ *   · a document with a SECOND rule within the 200-line ceiling was worse, because it succeeded:
+ *     the key was inserted between two horizontal rules, in the middle of the user's prose, as if
+ *     the span between them had been a mapping.
+ *
+ * So the block between the fences must LOOK like YAML mapping lines. Every non-blank line is either
+ * `key:`-shaped at column 0, a `#` comment, or an indented continuation of the line above. Prose
+ * fails all three, and a document whose first line is a rule is then correctly treated as having no
+ * frontmatter — it gets a block PREPENDED, which is the outcome the user wanted.
+ *
+ * ⚠ THIS IS A RECOGNISER, NOT A YAML PARSER, AND THE DISTINCTION IS THE MODULE'S WHOLE DESIGN. It
+ * decides one question — does this look like a mapping block? — from line shapes alone, and it
+ * still never parses, never builds an AST and never re-emits. The header's argument against running
+ * a YAML parser over untrusted text on the write path is untouched.
+ *
+ * ⚠ IT ERRS TOWARD "NOT FRONTMATTER". A block this rejects is PREPENDED to rather than inserted
+ * into, so the failure mode of a false negative is a document with a stamp block above a rule —
+ * visible, correct YAML, and nothing of the user's rewritten. A false POSITIVE is the defect above:
+ * a key spliced into prose.
+ */
+function looksLikeMapping(lines, from, to) {
+    for (let index = from; index < to; index += 1) {
+        const raw = lines[index];
+        const body = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (body.trim().length === 0)
+            continue;
+        // An indented line continues whatever came before it — a nested mapping, a sequence member,
+        // a folded scalar. Its own shape is not this recogniser's business.
+        if (/^\s/.test(body))
+            continue;
+        if (body.startsWith('#'))
+            continue;
+        // ⚠ A KEY AT COLUMN 0, WITH THE COLON REQUIRED. `keyOf` already encodes exactly this shape
+        // for the conflict check, so it is reused rather than re-expressed — two spellings of "what
+        // is a top-level key" would be two things to keep in step.
+        if (keyOf(body) !== null)
+            continue;
+        return false;
+    }
+    return true;
+}
+/**
+ * The document's line ending, decided from the OPENING FENCE rather than from a scan.
+ *
+ * ⚠ A CRLF DOCUMENT MUST GET A CRLF KEY LINE. Inserting a lone LF into a file whose every other
+ * line ends CRLF produces a document with mixed endings — which git will report as a whole-file
+ * change on the next normalisation, and which some Windows editors render as one run-on line. The
+ * fence we are inserting above is the nearest evidence of what this document does, and it is the
+ * line our insertion sits against.
+ */
+function endingOf(line) {
+    return line.endsWith('\r') ? '\r' : '';
+}
+/**
+ * ⚠⚠ THE PREPENDED BLOCK'S ENDING, AND EVERY PREPEND EXIT GOES THROUGH HERE. Three call sites
+ * used to build `` `---\n${keyLine}\n---\n${content}` `` inline, which put THREE lone LFs into a
+ * CRLF document — measured 2026-09-03 on all three, against the compiled build. That is the
+ * mixed-ending file `endingOf` exists to prevent, arrived at through the one path that had no
+ * fence to read: a prepend happens precisely when the document has no frontmatter block.
+ *
+ * ⚠ THE BLOCK HAS THREE SEPARATORS AND ALL THREE MATTER — after the opening fence, after the key
+ * line, and BETWEEN THE CLOSING FENCE AND THE USER'S FIRST LINE. A fix that changed only the ones
+ * inside the block would still leave a lone LF at the seam, which is the byte that actually abuts
+ * the user's text. That is why this returns the whole string rather than an ending to interpolate.
+ *
+ * ⚠ THE RULE IS THE FIRST PHYSICAL LINE'S ENDING, NOT A DOCUMENT-WIDE SURVEY, and the narrowness
+ * is the design. Our block touches the document at exactly one seam — above its first line — so
+ * that line is the only nearby evidence, and it is the same shape of rule the splice path already
+ * follows (take the ending from the line you are inserting against). A majority or last-ending
+ * heuristic would invent a global policy for a document that is already inconsistent, and would
+ * disagree with the splice path on that document — one module with two rules.
+ *
+ * ⚠ AN ALREADY-MIXED DOCUMENT STAYS MIXED, DELIBERATELY. We did not cause it, and this module's
+ * justification for writing into someone else's notes is that the act is minimal and disclosed;
+ * normalising their line endings is neither. Not one byte of `content` is rewritten here.
+ *
+ * ⚠ NO BREAK AT ALL — an empty document, or a single unterminated line — HAS NO STYLE TO PRESERVE,
+ * so it takes LF. Bare-CR (classic Mac) documents are out of scope and stay that way: `split('\n')`
+ * does not see them as multi-line anywhere in this module.
+ */
+function prepended(keyLine, content) {
+    const firstBreak = content.indexOf('\n');
+    const eol = firstBreak > 0 && content[firstBreak - 1] === '\r' ? '\r\n' : '\n';
+    return `---${eol}${keyLine}${eol}---${eol}${content}`;
+}
+/**
+ * Insert the stamp, or refuse.
+ *
+ * `content` is the caller's page text; the return carries the bytes to write.
+ */
+export function stamp(content, projection) {
+    const value = JSON.stringify(projection);
+    const keyLine = `${FRONTMATTER_KEY}: ${value}`;
+    // ⚠ THE OPENING FENCE MUST BE THE FIRST LINE, with nothing before it — not even a blank line.
+    // A `---` further down is a horizontal rule or a document separator in the body, and prepending
+    // a block above it is correct; treating it as an opening fence would insert our key into the
+    // middle of the user's prose.
+    const lines = content.split('\n');
+    const opens = lines.length > 0 && isFence(lines[0]);
+    if (!opens) {
+        return prepended(keyLine, content);
+    }
+    const ceiling = Math.min(lines.length, MAX_FRONTMATTER_LINES);
+    for (let index = 1; index < ceiling; index += 1) {
+        const line = lines[index];
+        if (isFence(line)) {
+            /**
+             * ⚠⚠ THE BLOCK IS RECOGNISED BEFORE IT IS WRITTEN INTO, AND A BLOCK THAT IS NOT A
+             * MAPPING IS NOT FRONTMATTER AT ALL. A pair of fences around PROSE is two horizontal
+             * rules, and splicing a key between them puts YAML into the middle of the user's
+             * document — the defect this check exists for.
+             *
+             * ⚠ SO IT PREPENDS RATHER THAN REFUSING, and the choice is the whole point. Refusing
+             * would leave an ordinary Markdown file — a rule, some prose, another rule —
+             * permanently unwritable through this server, which is the OTHER half of the same
+             * defect rather than an improvement on it. Treating the document as having no
+             * frontmatter is both true and useful: it gets a block on top and not one byte of the
+             * user's own text moves.
+             *
+             * ⚠ IT IS THE SAME ANSWER THE NO-CLOSING-FENCE PATH BELOW GIVES FOR THE SAME SHAPE,
+             * deliberately. One question — is this a mapping block? — with one answer, rather than
+             * two outcomes hanging on whether a second rule happened to fall inside the ceiling.
+             */
+            if (!looksLikeMapping(lines, 1, index)) {
+                return prepended(keyLine, content);
+            }
+            // ⚠ THE KEY LINE MATCHES THE DOCUMENT'S OWN ENDING, taken from the closing fence it is
+            // inserted above. A lone LF in a CRLF document is a mixed-ending file.
+            const spliced = [...lines.slice(0, index), keyLine + endingOf(line), ...lines.slice(index)];
+            return spliced.join('\n');
+        }
+        if (keyOf(line) === FRONTMATTER_KEY) {
+            // ⚠ THE CONFLICT REFUSES; IT DOES NOT OVERWRITE. The existing value may be a previous
+            // stamp or may be the user's own key — this module cannot tell, and replacing either
+            // one destroys information the caller never offered up. Refusing is the only outcome
+            // that is right in both readings.
+            return scribeRefuse('FRONTMATTER_CONFLICT', `the page already carries a top-level ${FRONTMATTER_KEY} key`);
+        }
+    }
+    /**
+     * No closing fence within the ceiling.
+     *
+     * ⚠⚠ AND THE MAPPING TEST DECIDES WHICH FAILURE THIS IS, which is the second half of the
+     * horizontal-rule fix. If what follows the first line reads as a mapping, this really is an
+     * unclosed frontmatter block and it REFUSES — prepending a second block would hand back a
+     * document with two, which is why the ceiling refuses rather than falling through.
+     *
+     * If it does NOT read as a mapping, the first line was a horizontal rule and this document has
+     * no frontmatter at all. It gets a block prepended, exactly as a document opening with prose
+     * would. The old code refused here, which made an ordinary Markdown file — a rule, then prose —
+     * permanently unwritable through this server, with a message about a closing fence the user had
+     * no reason to think they owed.
+     */
+    if (!looksLikeMapping(lines, 1, ceiling)) {
+        return prepended(keyLine, content);
+    }
+    return scribeRefuse('FRONTMATTER_INVALID', `the page opens a frontmatter block with no closing --- within ${MAX_FRONTMATTER_LINES} lines`);
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { createFsGate } from 'wyrd-fence';
+import { main } from './main.js';
+await main({
+    argv: process.argv.slice(2),
+    env: process.env,
+    makeFsGate: createFsGate,
+    makeTransport: () => new StdioServerTransport(),
+    stderr: line => process.stderr.write(`${line}\n`),
+    setExitCode: code => {
+        process.exitCode = code;
+    }
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,IAAI,CAAC;IACP,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,UAAU,EAAE,YAAY;IACxB,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI,oBAAoB,EAAE;IAC/C,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;IACjD,WAAW,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC5B,CAAC;CACJ,CAAC,CAAC"}

package/dist/ledger.d.ts

@@ -0,0 +1,69 @@
+/**
+ * THE LEDGER SEAM — a TYPE, the production appender over the fence, and a refusing one for the arms.
+ *
+ * ⚠⚠ THE APPEND IS THE FENCE'S, NEVER THIS FILE'S. B4 rules the append is one `O_APPEND` write of
+ * one fully-serialised line, and `FsGate.appendLineInGrant` is that write — landed 2026-09-02 with
+ * its own containment argument, its own name screens and its own identity re-proof. Everything
+ * `gateAppender` below does is name the path and hand the bytes over. Reaching around the gate with
+ * `fs.appendFileSync` would put a second, unfenced write path in the very package whose D8 argument
+ * is that there is exactly one — and it is worth saying plainly that the temptation is real, since
+ * an append to a known relative path looks like the most harmless call in the file.
+ *
+ * ⚠ THIS FILE USED TO SAY THE PRIMITIVE DID NOT EXIST, AND THE ARM IT NAMED AS OWED IS NOW PAID.
+ * `ST22`–`ST25` append real lines to a real `.wyrd/lineage.jsonl` over a real grant: one line
+ * landing, three accumulating in order, a parent deleted underneath the write refusing after the
+ * page was created, and eight concurrent writers producing eight intact lines. The `ST-OWED`
+ * inventory row is gone rather than annotated, because an inventory that describes a debt already
+ * settled is worse than no row at all.
+ *
+ * ⚠ INJECTED, NOT IMPORTED, at the composition root. `writePage` takes the appender as a parameter
+ * so the arms can supply a spy or a refuser without the production path acquiring a mode flag. A
+ * module that knows whether it is under test is a module whose test proves less than it looks like.
+ */
+import type { FenceRefusal, FsGate } from 'wyrd-fence';
+/** What an append reports on success. `bytes` is the line INCLUDING its terminating LF. */
+export interface Appended {
+    readonly ok: true;
+    readonly bytes: number;
+}
+/**
+ * ⚠ THE PARAMETER IS A FULLY-SERIALISED BUFFER, AND THE TYPE IS THE RULE. B4's atomicity argument
+ * holds for ONE write of ONE complete line; an implementation handed a record and left to serialise
+ * it could emit in pieces. Handing over bytes makes "never split a line" a property of the
+ * signature rather than of a comment inside whoever implements it.
+ */
+export interface LedgerAppender {
+    appendLine(line: Buffer): Promise<Appended | FenceRefusal>;
+}
+/**
+ * THE PRODUCTION APPENDER. One line, through the gate, to the vault's own lineage log.
+ *
+ * ⚠⚠ THE FENCE'S RESULT IS PASSED THROUGH UNCHANGED, NOT REPACKAGED, and that is a decision rather
+ * than laziness. The fence's `Appended` carries `rel` alongside `ok` and `bytes`, so it already
+ * satisfies this module's narrower `Appended`; its `WriteRefusal` is a `FenceRefusal` carrying
+ * `retained`, which is the field that tells a caller whether a failed append may have left a
+ * partial line behind. Narrowing either one to this file's shape would DISCARD exactly the
+ * diagnostics the fence spent its slice producing — and `stamp.ts` hands the refusal straight to
+ * the caller inside `PAGE_WRITTEN_LEDGER_FAILED`, where the retention answer is the whole point.
+ *
+ * ⚠ THE PATH IS A CONSTANT AND THE CALLER CANNOT CHOOSE IT. A lineage log the caller can redirect
+ * is a provenance record that can be written somewhere nobody reads — so the only path this
+ * appender will ever name is `config.ts`'s `LINEAGE_PATH`, and the constant is shared with the
+ * config loader so the ledger and the config can never disagree about which directory is the
+ * vault's.
+ *
+ * ⚠ NO RETRY, ANYWHERE ABOVE THE FENCE EITHER. The fence refuses to retry under `O_APPEND` because
+ * a second attempt re-selects the end of file and splices this record through whatever another
+ * appender landed in between; a retry loop added HERE would manufacture precisely that, one level
+ * up, where the fence's comment explaining why cannot be seen.
+ */
+export declare function gateAppender(gate: FsGate): LedgerAppender;
+/**
+ * The appender the arms use to exercise the failure branch.
+ *
+ * ⚠ IT REFUSES RATHER THAN NO-OPS, deliberately. A no-op appender would make every arm above it
+ * green while the ledger silently recorded nothing — the exact "green on a path that does nothing"
+ * shape the suite runner exists to make impossible. It is no longer what the package ships with:
+ * `createScribe` now defaults to `gateAppender`, and the argument for that change is in `index.ts`.
+ */
+export declare function refusingAppender(detail?: string): LedgerAppender;

package/dist/ledger.js

@@ -0,0 +1,64 @@
+/**
+ * THE LEDGER SEAM — a TYPE, the production appender over the fence, and a refusing one for the arms.
+ *
+ * ⚠⚠ THE APPEND IS THE FENCE'S, NEVER THIS FILE'S. B4 rules the append is one `O_APPEND` write of
+ * one fully-serialised line, and `FsGate.appendLineInGrant` is that write — landed 2026-09-02 with
+ * its own containment argument, its own name screens and its own identity re-proof. Everything
+ * `gateAppender` below does is name the path and hand the bytes over. Reaching around the gate with
+ * `fs.appendFileSync` would put a second, unfenced write path in the very package whose D8 argument
+ * is that there is exactly one — and it is worth saying plainly that the temptation is real, since
+ * an append to a known relative path looks like the most harmless call in the file.
+ *
+ * ⚠ THIS FILE USED TO SAY THE PRIMITIVE DID NOT EXIST, AND THE ARM IT NAMED AS OWED IS NOW PAID.
+ * `ST22`–`ST25` append real lines to a real `.wyrd/lineage.jsonl` over a real grant: one line
+ * landing, three accumulating in order, a parent deleted underneath the write refusing after the
+ * page was created, and eight concurrent writers producing eight intact lines. The `ST-OWED`
+ * inventory row is gone rather than annotated, because an inventory that describes a debt already
+ * settled is worse than no row at all.
+ *
+ * ⚠ INJECTED, NOT IMPORTED, at the composition root. `writePage` takes the appender as a parameter
+ * so the arms can supply a spy or a refuser without the production path acquiring a mode flag. A
+ * module that knows whether it is under test is a module whose test proves less than it looks like.
+ */
+import { LINEAGE_PATH } from './config.js';
+/**
+ * THE PRODUCTION APPENDER. One line, through the gate, to the vault's own lineage log.
+ *
+ * ⚠⚠ THE FENCE'S RESULT IS PASSED THROUGH UNCHANGED, NOT REPACKAGED, and that is a decision rather
+ * than laziness. The fence's `Appended` carries `rel` alongside `ok` and `bytes`, so it already
+ * satisfies this module's narrower `Appended`; its `WriteRefusal` is a `FenceRefusal` carrying
+ * `retained`, which is the field that tells a caller whether a failed append may have left a
+ * partial line behind. Narrowing either one to this file's shape would DISCARD exactly the
+ * diagnostics the fence spent its slice producing — and `stamp.ts` hands the refusal straight to
+ * the caller inside `PAGE_WRITTEN_LEDGER_FAILED`, where the retention answer is the whole point.
+ *
+ * ⚠ THE PATH IS A CONSTANT AND THE CALLER CANNOT CHOOSE IT. A lineage log the caller can redirect
+ * is a provenance record that can be written somewhere nobody reads — so the only path this
+ * appender will ever name is `config.ts`'s `LINEAGE_PATH`, and the constant is shared with the
+ * config loader so the ledger and the config can never disagree about which directory is the
+ * vault's.
+ *
+ * ⚠ NO RETRY, ANYWHERE ABOVE THE FENCE EITHER. The fence refuses to retry under `O_APPEND` because
+ * a second attempt re-selects the end of file and splices this record through whatever another
+ * appender landed in between; a retry loop added HERE would manufacture precisely that, one level
+ * up, where the fence's comment explaining why cannot be seen.
+ */
+export function gateAppender(gate) {
+    return Object.freeze({
+        appendLine: (line) => gate.appendLineInGrant(LINEAGE_PATH, line)
+    });
+}
+/**
+ * The appender the arms use to exercise the failure branch.
+ *
+ * ⚠ IT REFUSES RATHER THAN NO-OPS, deliberately. A no-op appender would make every arm above it
+ * green while the ledger silently recorded nothing — the exact "green on a path that does nothing"
+ * shape the suite runner exists to make impossible. It is no longer what the package ships with:
+ * `createScribe` now defaults to `gateAppender`, and the argument for that change is in `index.ts`.
+ */
+export function refusingAppender(detail = 'the ledger append was refused') {
+    return Object.freeze({
+        appendLine: async () => Object.freeze({ ok: false, reason: 'IO_ERROR', detail, resolvedPath: '' })
+    });
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAkB3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC;QACjB,UAAU,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,YAAY,EAAE,IAAI,CAAC;KAC3E,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAM,GAAG,+BAA+B;IACrE,OAAO,MAAM,CAAC,MAAM,CAAC;QACjB,UAAU,EAAE,KAAK,IAA2B,EAAE,CAC1C,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,MAAM,EAAE,UAAmB,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;KACnG,CAAC,CAAC;AACP,CAAC"}