wyrd-scribe 0.1.0

package/dist/span.js

@@ -0,0 +1,242 @@
+/**
+ * B1 — THE SPAN RESOLVER. Bytes in, a located span or a refusal out.
+ *
+ * Built to `designs/2026-08-31-span-resolver-plan.md`, which carries the reasoning and four rounds
+ * of gate findings. The one rule everything here serves:
+ *
+ *   ⚠⚠ NO SILENT MISLOCATION. AMBIGUITY REFUSES; IT NEVER PICKS.
+ *
+ * ⚠ FENCE-FREE, AND THAT IS STRUCTURAL RATHER THAN POLITE. This module takes `(bytes, request)` and
+ * no path. It never opens a file, never imports the fence, and has no way to reach the filesystem —
+ * reading is the fence's job, and a resolver that opens files has become a second write path.
+ *
+ * ⚠ THE PROPERTY THIS MODULE PROTECTS: no substituted span resolution in a refusal, and no source
+ * bytes in EITHER variant. It is NOT the fence's no-absolute-path rule — that belongs to
+ * `wyrd-fence` (`packages/wyrd-fence/src/fsgate.ts`) and is asserted there. A reviewer briefed on
+ * the fence's property is on the wrong axis here.
+ *
+ * ⚠⚠ AND THE PROPERTY IS NOT ENFORCED BY THESE TYPES. `SpanRefusal` and `ResolvedSpan` are
+ * TypeScript-only shapes: the compiler forbids no extra property at runtime, and an unchecked
+ * assignment can put a value anywhere. The enforcement is the own-key envelope in
+ * `test/span.test.js`, applied to EVERY arm — refusal and success alike. This comment is not a
+ * mechanism.
+ *
+ * ⚠ `Object.freeze` on every return is the runtime half OF THE EXTRA-KEY RULE ONLY. It says
+ * nothing about what an ACCESSOR returns: freeze constrains the property, never the getter, so a
+ * frozen own getter can serve a correct value to the first readers and the source buffer to the
+ * next. Measured at code-gate round 2 — it passed all 29 arms. What closes that is the
+ * data-property assertion in `envelope()`, not this line.
+ */
+/**
+ * ⚠ AN UNKNOWN KEY REFUSES RATHER THAN BEING IGNORED, and the reason is a fail-open, not tidiness.
+ * `{ offset, length, qoute }` read leniently is a valid OFFSETS-ONLY request: it succeeds, records
+ * a quote the caller never asked to have verified, and silently drops the verification the caller
+ * was asking for. That is mislocation arriving through a typo.
+ */
+const REQUEST_KEYS = new Set(['offset', 'length', 'quote']);
+function refuse(reason, where) {
+    return Object.freeze({ ok: false, reason, where });
+}
+function resolved(offset, length, quote) {
+    return Object.freeze({ ok: true, offset, length, quote });
+}
+/** A UTF-8 continuation byte — `10xxxxxx`. A span may not START on one, nor END just before one. */
+function isContinuation(byte) {
+    return byte !== undefined && (byte & 0xc0) === 0x80;
+}
+/**
+ * ⚠ BOTH ENDPOINTS, AND THE ARMS TEST THEM SEPARATELY. `é` is `c3 a9`: `{1,1}` cuts the START,
+ * `{0,1}` cuts the END, and a check that validates one side passes half the rule while reading as
+ * complete.
+ *
+ * Why a non-aligned span refuses at all: D4 stores the quoted TEXT over a source model the spec
+ * declares UTF-8, and a lone `a9` has no lossless UTF-8 text representation. Decoding substitutes
+ * `U+FFFD`, so the stored quote no longer re-encodes to the bytes it came from — the identity D4
+ * exists to establish is destroyed at the moment of recording.
+ */
+function alignmentFault(bytes, offset, length) {
+    if (isContinuation(bytes[offset]))
+        return 'offset';
+    const end = offset + length;
+    if (end < bytes.length && isContinuation(bytes[end]))
+        return 'length';
+    return null;
+}
+/**
+ * ⚠ THE QUOTE IS VALIDATED FOR LOSSLESS UTF-8 ROUND-TRIP BEFORE ANY MATCHING. `"\uD800"` is a
+ * well-formed JavaScript string and NOT well-formed Unicode text; encoding it substitutes
+ * `U+FFFD`, so an unvalidated lone-surrogate quote would match GENUINE replacement-character bytes
+ * in the source and return a quote that does not identify them.
+ *
+ * The empty quote refuses here too: against an empty source it would otherwise "uniquely match"
+ * and mint a zero-length span, which the positive-length rule forbids on the offsets side.
+ */
+function quoteFault(quote) {
+    if (typeof quote !== 'string' || quote.length === 0)
+        return refuse('SPAN_INVALID_QUOTE', 'quote');
+    if (Buffer.from(quote, 'utf8').toString('utf8') !== quote)
+        return refuse('SPAN_INVALID_QUOTE', 'quote');
+    return null;
+}
+/** Narrows `spanShapeFault`'s result. A refusal carries `ok: false`; members never do. */
+function isMembers(value) {
+    return value.ok !== false;
+}
+export function spanShapeFault(request) {
+    const raw = request;
+    if (typeof raw !== 'object' || raw === null)
+        return refuse('SPAN_INVALID_RANGE', 'request');
+    // ⚠ OWN KEYS, NOT `in`. `in` walks the prototype chain, so an inherited `offset` would be read
+    // as a supplied one. Symbol keys are unknown keys and refuse with the rest.
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== 'string' || !REQUEST_KEYS.has(key))
+            return refuse('SPAN_INVALID_RANGE', 'request');
+    }
+    const own = (key) => Object.prototype.hasOwnProperty.call(raw, key);
+    const hasOffset = own('offset');
+    const hasLength = own('length');
+    const hasQuote = own('quote');
+    // ⚠ THE SAME READ-ONCE, READ-ONLY-WHAT-WAS-SUPPLIED DISCIPLINE AS THE RESOLVER BELOW, and it
+    // binds here for an additional reason: this function runs BEFORE any source is read, so an
+    // inherited accessor fired here would run earlier than the one the resolver's rule is about.
+    const view = raw;
+    const offsetValue = hasOffset ? view.offset : undefined;
+    const lengthValue = hasLength ? view.length : undefined;
+    const quoteValue = hasQuote ? view.quote : undefined;
+    if (!hasOffset && !hasLength && !hasQuote)
+        return refuse('SPAN_INVALID_RANGE', 'request');
+    // ⚠ `offset` and `length` are REQUIRED TOGETHER; `where` names the member that is missing.
+    if (hasOffset !== hasLength)
+        return refuse('SPAN_INVALID_RANGE', hasOffset ? 'length' : 'offset');
+    if (hasOffset) {
+        /**
+         * ⚠⚠ RANGE VALIDATION RUNS FIRST AND COMPLETELY. Common byte-slice APIs coerce or clamp a
+         * fractional, negative or oversized bound silently, producing a quote for a DIFFERENT
+         * effective range while the record stores the offsets as supplied. That is silent
+         * mislocation arriving through type coercion. An invalid range must never reach the
+         * matcher, or the refusal describes the wrong failure.
+         *
+         * ⚠ THE `> bytes.length` HALF IS NOT HERE, and its absence is the boundary of this
+         * function. Whether a well-formed range FITS is a question about the source.
+         */
+        if (!Number.isSafeInteger(offsetValue) || offsetValue < 0) {
+            return refuse('SPAN_INVALID_RANGE', 'offset');
+        }
+        if (!Number.isSafeInteger(lengthValue) || lengthValue <= 0) {
+            return refuse('SPAN_INVALID_RANGE', 'length');
+        }
+    }
+    // ⚠ THE QUOTE'S OWN WELL-FORMEDNESS IS SOURCE-INDEPENDENT ON BOTH PATHS — a lone surrogate or
+    // an empty string refuses against any source at all — so it is decided here for both, in the
+    // order the resolver reaches it: after the range members on the offsets path, immediately on
+    // the quote-only path.
+    if (hasQuote) {
+        const badQuote = quoteFault(quoteValue);
+        if (badQuote)
+            return badQuote;
+    }
+    return Object.freeze({ hasOffset, hasQuote, offsetValue, lengthValue, quoteValue });
+}
+export function resolveSpan(bytes, request) {
+    if (!Buffer.isBuffer(bytes)) {
+        throw new TypeError('resolveSpan(bytes, request): bytes must be a Buffer of source bytes');
+    }
+    /**
+     * ⚠⚠ THE SOURCE-INDEPENDENT PREFIX, RUN AS ONE STEP, AND IT CARRIES THE READ-ONCE RULE WITH IT.
+     * Every refusal it can reach is one this function reached itself before the extraction, in the
+     * identical order — which is what makes `stamp.ts`'s pre-check a prediction of this resolver
+     * rather than a second opinion about the same request. It also performs the ONLY read of the
+     * request's members on this path and hands the values back: reading them again here would fire
+     * a caller-supplied accessor twice, which is `M1`'s defect arriving through a refactor.
+     */
+    const shape = spanShapeFault(request);
+    if (!isMembers(shape))
+        return shape;
+    const { hasOffset, hasQuote, offsetValue, lengthValue, quoteValue } = shape;
+    if (hasOffset) {
+        const offset = offsetValue;
+        const length = lengthValue;
+        // ⚠ OVERFLOW-SAFE BY SUBTRACTION, NEVER `offset + length > bytes.length`. Both operands are
+        // safe integers, so `bytes.length - offset` is exact and small; the sum is never compared.
+        if (offset > bytes.length)
+            return refuse('SPAN_INVALID_RANGE', 'offset');
+        if (length > bytes.length - offset)
+            return refuse('SPAN_INVALID_RANGE', 'length');
+        const fault = alignmentFault(bytes, offset, length);
+        if (fault)
+            return refuse('SPAN_NOT_ALIGNED', fault);
+        const slice = bytes.subarray(offset, offset + length);
+        const text = slice.toString('utf8');
+        /**
+         * ⚠ ALIGNMENT IS NECESSARY AND NOT SUFFICIENT. `41 c3` is aligned at both endpoints and
+         * still decodes lossily, because the sequence INSIDE the span is truncated. The round-trip
+         * is the property alignment is a proxy for, so it is asserted directly rather than assumed
+         * from the endpoints. `where` is `'request'`: with a well-formed source neither endpoint is
+         * at fault, and naming one would be a guess.
+         */
+        if (!Buffer.from(text, 'utf8').equals(slice))
+            return refuse('SPAN_NOT_ALIGNED', 'request');
+        if (!hasQuote)
+            return resolved(offset, length, text);
+        /**
+         * ⚠⚠ MISMATCH PREFERS NEITHER SIDE, AND `where` IS `'request'`. Preferring the offsets
+         * silently rewrites the caller's quote; preferring the quote silently relocates the
+         * caller's offsets. Naming `'quote'` at fault IS preferring the offsets — the first of the
+         * two failures the rule forbids. A whole-request inconsistency is `'request'`.
+         *
+         * String comparison is exact and safe here only because both sides are known to round-trip
+         * losslessly: the source slice by the check above, the quote by `quoteFault`.
+         */
+        if (quoteValue !== text)
+            return refuse('SPAN_MISMATCH', 'request');
+        return resolved(offset, length, text);
+    }
+    // ⚠ THE QUOTE IS ALREADY KNOWN WELL-FORMED — `spanShapeFault` decided it, on both paths, before
+    // any byte was looked at. The two `quoteFault` calls that used to sit here and in the offsets
+    // branch are GONE rather than kept as belt-and-braces: a second call would re-run a decided
+    // check against a value that can no longer change, and a guard nothing can trip is a guard
+    // nobody is measuring.
+    const needle = Buffer.from(quoteValue, 'utf8');
+    /**
+     * ⚠⚠ THE SCAN ADVANCES BY ONE BYTE, NEVER BY THE NEEDLE LENGTH. Bytes `"aaa"` with quote `"aa"`
+     * match at offset 0 AND offset 1; a scan advancing by the needle length finds one match and
+     * returns it, passing a naive occurs-twice arm while resolving an ambiguous span. Two matches
+     * is all this needs to know, so it stops there.
+     */
+    let first = -1;
+    let ambiguous = false;
+    for (let from = 0; from <= bytes.length - needle.length;) {
+        const at = bytes.indexOf(needle, from);
+        if (at === -1)
+            break;
+        if (first === -1) {
+            first = at;
+            from = at + 1;
+            continue;
+        }
+        ambiguous = true;
+        break;
+    }
+    if (first === -1)
+        return refuse('SPAN_NOT_FOUND', 'quote');
+    if (ambiguous)
+        return refuse('SPAN_AMBIGUOUS', 'quote');
+    /**
+     * ⚠ ALIGNMENT IS A PROPERTY OF THE SPAN, SO IT IS CHECKED ON EVERY SHAPE THAT PRODUCES ONE.
+     * In well-formed UTF-8 a located match is aligned by construction, since a valid encoded quote
+     * never begins with a continuation byte. In a malformed source it need not be — `41 a9` with
+     * quote `"A"` ends immediately before a continuation byte — and applying the rule only to the
+     * shape that supplies offsets is the one-sided check this plan kept catching.
+     */
+    // ⚠ `where` is 'request', NOT the endpoint `alignmentFault` names. A quote-only request has no
+    // `offset` and no `length` member, so naming either blames something the caller never sent —
+    // the diagnostic would point at a value it derived itself. The offsets path above reaches the
+    // same conclusion for a malformed source and says so in its own words: naming one endpoint
+    // "would be a guess." Extending alignment to quote-only matches was right; inheriting the
+    // offsets path's `where` with it was not. Both round-1 code-gate lenses, both judging the CODE
+    // wrong and the SPEC right.
+    if (alignmentFault(bytes, first, needle.length))
+        return refuse('SPAN_NOT_ALIGNED', 'request');
+    return resolved(first, needle.length, quoteValue);
+}
+//# sourceMappingURL=span.js.map

package/dist/span.js.map

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

package/dist/stamp.d.ts

@@ -0,0 +1,297 @@
+/**
+ * `writePage` — THE STAMP PATH, TIER A (create-only). The Scribe-side half of the spec's step list.
+ *
+ * ⚠⚠ THE ORDER IS THE SECURITY PROPERTY, NOT AN IMPLEMENTATION DETAIL. Read the numbered steps
+ * below as a sequence of things that must not have happened yet:
+ *
+ *   · EVERY REFUSAL KNOWABLE FROM THE REQUEST'S OWN SHAPE IS DECIDED BEFORE ANY SOURCE IS READ —
+ *     the `Arc/` screen, the count caps, and every span fault. If any of them ran after, a caller
+ *     could send a request that was ALWAYS going to refuse — an `Arc/` target, 65 sources, a
+ *     malformed span — with a `derived_from` naming any path on the machine, and read those
+ *     sources' existence and hashes out of the refusal's timing and reason. That turns a check into
+ *     an EXISTENCE ORACLE, which is D8's hole arriving through the back door after D8 closed the
+ *     front one. ⚠ The rule was written for `Arc/` and enforced only there until 2026-09-02; the
+ *     counts and the span shapes were being decided after the whole source loop had run.
+ *
+ *     ⚠⚠ THIS SAID "EVERY GUARANTEED REFUSAL" UNTIL 2026-09-08 AND THAT IS NO LONGER TRUE, so the
+ *     claim is narrowed to what the order actually buys. The fence's `PARENT_ALIAS` is a guaranteed
+ *     refusal — the page's parent is an alias, and no source read can change that — but it is
+ *     knowable only from the vault's TOPOLOGY, not from the request's shape, and it fires at page
+ *     creation in step 6, AFTER the source loop. ⚠ The oracle argument survives the narrowing: what
+ *     a caller learns from a `PARENT_ALIAS` is a fact about a directory INSIDE the grant, which
+ *     every read operation already discloses. The `.wyrd/` half is not affected at all — step 4's
+ *     `loadConfig` refuses an aliased `.wyrd` before step 5 reads anything.
+ *   · NO PAGE IS WRITTEN until every source has resolved and every limit KNOWABLE BEFORE THE PAGE
+ *     EXISTS has passed. When a page IS created and the ledger step then REFUSES — the final size
+ *     check at step 9, or the append after it — this invocation leaves that page with no ledger
+ *     line: an ORPHAN, which the no-rollback ruling below leaves on disk and which the
+ *     create-before-append clause two bullets down calls "detectable and repairable". That is what
+ *     the draft size check at step 6 stands in front of.
+ *
+ *     ⚠ THE FIRST SENTENCE READ UNCONDITIONALLY UNTIL 2026-09-08 — "a page created before the
+ *     ledger line is known to be serialisable is a page this invocation leaves with no ledger line"
+ *     — WHICH IS WIDER THAN THE CODE. The ordinary path creates the page before the FINAL size
+ *     check and then appends successfully; the orphan is what a REFUSAL at either ledger step
+ *     leaves, not what the ordering leaves. The condition is now in the sentence.
+ *
+ *     ⚠ AND IT SAID "a page whose provenance can NEVER be recorded" BEFORE THAT, WHICH THE CODE
+ *     ALSO DID NOT ESTABLISH. What this invocation leaves behind is a page with no ledger line.
+ *     **`writePage` provides no pass that records one later, and re-invoking it on the same path
+ *     refuses `EXISTS`** — so nothing in this package records one, which is narrower than the
+ *     retired "a later pass can still record one" and is what the code actually says. Overclaiming
+ *     in either direction is not a harmless flourish: the first makes the residual hole at step 9
+ *     (`ST41`) sound impossible instead of merely narrow, the second promises a repair path this
+ *     package does not contain.
+ *
+ *     ⚠⚠ "EVERY LIMIT" IS NOT WHAT THIS ORDERING BUYS AND THE CLAUSE SAID SO UNTIL 2026-09-08. One
+ *     limit is decided AFTER the page exists: the final ledger-line size check at step 9, over the
+ *     CANONICAL path the fence returns from the create. It is reachable — a fold-equal parent alias
+ *     of different byte width makes `created.rel` wider than the request the draft was sized
+ *     against (`ST41`) — and when it fires the page is already on disk with no ledger line. That
+ *     ORPHAN is the outcome, asserted PRESENT on purpose by `ST38` and `ST41` so a green suite is
+ *     never read as meaning it was closed. What the ordering buys is the narrower claim, which is
+ *     still the one worth having: no page exists until every check that CAN be decided without one
+ *     has passed.
+ *
+ *     ⚠⚠ THIS SAID "NOTHING IS WRITTEN" UNTIL 2026-09-08 AND THAT IS NO LONGER TRUE EITHER, so the
+ *     subject is narrowed to the thing the ordering actually protects. Option C's part 3 hoists
+ *     `loadConfig`'s exclusive create ahead of its read, so STEP 4 CAN CREATE `.wyrd/scribe.json`
+ *     BEFORE ANY SOURCE IS READ. The distinction is worth the words: the config is this server's
+ *     own bookkeeping, minted at a fixed path inside a directory the user created for it, and a
+ *     vault that gains one has gained none of the caller's PAGE CONTENT (the `vault_id` it carries
+ *     is whatever `newUuid` returned, and a caller supplying that option chose it). The PAGE is
+ *     the first write of caller-supplied content, and it is still the write every check above
+ *     stands in front of.
+ *     Sources are read BETWEEN the two.
+ *   · the page is created BEFORE the ledger line is appended, and that ORDER IS ALSO DELIBERATE.
+ *     The reverse records provenance for a page that may never exist, which is a FALSE PROVENANCE
+ *     CLAIM — D4 names that as the failure that matters, worse than breakage, because it looks
+ *     healthy. A page with a missing ledger line is DETECTABLE — the page is on disk and the ledger
+ *     has no line naming it, which a reader can see — and repairable BY SOMETHING OUTSIDE THIS
+ *     PACKAGE; a ledger line with no page is a lie in the permanent record, and nothing detects it.
+ *     ⚠ "repairable" ALONE READ AS A PROMISE THIS PACKAGE KEEPS, WHICH IT DOES NOT: `writePage` has
+ *     no repair pass and refuses `EXISTS` on the orphan's own path. What the ordering buys is that
+ *     the failure is the visible kind rather than the invisible kind.
+ *
+ * ⚠⚠ AND THERE IS NO ROLLBACK, WHICH IS A RULING RATHER THAN AN OMISSION. If the append fails after
+ * the page was created, the page STAYS and the refusal says so (`PAGE_WRITTEN_LEDGER_FAILED`,
+ * carrying the fence's `Created`). Two reasons, and the second is the load-bearing one: the fence
+ * has no delete primitive at all in tier A, and deleting BY PATH would reopen the TOCTOU window the
+ * fence's `wx` create exists to close — between the create and the delete, the name can become
+ * something else. A caller told exactly what happened can decide; a caller handed a silent cleanup
+ * that deleted the wrong object cannot.
+ */
+import type { Created, FenceRefusal, FsGate } from 'wyrd-fence';
+import type { LineageRecord } from './lineage.js';
+import type { LedgerAppender } from './ledger.js';
+import type { ScribeRefusal } from './refusal.js';
+import { SourceCache } from './source.js';
+import type { SpanRefusal, SpanRequest } from './span.js';
+/** A `derived_from` entry: one source path and the spans cited from it. */
+export interface DerivedFrom {
+    readonly source: string;
+    readonly spans: readonly SpanRequest[];
+}
+export interface WritePageRequest {
+    readonly path: string;
+    readonly content: string;
+    readonly derivedFrom: readonly DerivedFrom[];
+}
+/**
+ * ⚠⚠ THE OUTER SIDE-EFFECT SUMMARY, AND IT IS A DIFFERENT QUESTION FROM `retained`.
+ *
+ * `retained` is the FENCE's field and it is honest exactly as scoped: **it describes the ONE fence
+ * call that produced the refusal it sits on** — whether that call may have left bytes at the target
+ * IT was given. It says nothing about the invocation around it, and reading it as an
+ * invocation-wide "nothing happened" is the mistake this field exists to ANSWER — the answer is
+ * available beside it now, which is a different thing from the misreading being unavailable; a
+ * caller can still read `retained` alone and reach the old wrong conclusion. Since
+ * part 3 hoisted `loadConfig`'s exclusive create ahead of its read, a `writePage` that refuses at
+ * step 4 or later may ALREADY have minted the vault's config — a real, persistent change to the
+ * user's vault — while every `retained` in sight is `null` because the target that fence call was
+ * given was never opened.
+ *
+ * ⚠ WHICH TARGET IT DESCRIBES IS GIVEN BY WHERE THE REFUSAL AROSE, AND THERE IS NO SHORTER RULE
+ * THAN THAT. `retained`, where present, describes the fence call that produced the refusal it sits
+ * on — which target that call was given is answered by reading where in `writePage` the refusal
+ * came from, not by the refusal's shape. A pass-through from step 4 describes the CONFIG target
+ * (`ST39`, `stamp.test.js` ~2280); one from step 8 describes the page; a source-read refusal may
+ * carry no `retained` at all. On `LedgerFailed` the field lives at `cause.retained` and describes
+ * whatever the failing call addressed — and where the cause is Scribe-originated, as `ST41`'s
+ * `LINEAGE_LINE_TOO_LARGE` is, there is no `cause.retained` to read. The page's own outcome is
+ * never in that field either way: it is the `created` beside it, which says the page exists.
+ *
+ * **`retained` describes the fence call that produced the refusal it sits on; `config_created` says
+ * whether this invocation minted the vault config.** A caller repairing after a refusal needs both.
+ *
+ * ⚠ This field was added before the package's first public contract, so no earlier consumer shape
+ * required compatibility.
+ * It is on the ok shape AND on every POST-CONFIG Scribe-originated refusal shape for the same
+ * reason: a field present only on success answers the question only when the answer is least
+ * interesting. (A refusal decided at steps 1-3 carries no field; there is no answer yet.)
+ *
+ * ⚠⚠ AND THE RULE IS EXACTLY ONE SENTENCE WIDE, so read it before adding a return site. **Every
+ * result `writePage` returns after `loadConfig` has run carries `config_created`, set from what
+ * THIS invocation's `loadConfig` did — except a fence refusal passed through unchanged under D8,
+ * which carries no field.** A refusal decided at steps 1-3, before `loadConfig` runs, carries no
+ * field either, for the plainer reason that there is no answer yet.
+ *
+ * ⚠ ON A FENCE PASS-THROUGH THE CALLER IS SIMPLY NOT TOLD, and the residual is stated rather than
+ * argued away: a fence refusal from step 6's create, or from the source loop, CAN follow a config
+ * mint at step 4 and will not say so. **The absence of the field is not evidence the config was
+ * untouched.** On a fence pass-through the caller is not told whether this invocation minted the
+ * config, and **this package offers no observation that attributes it** — a later stat says the
+ * file is there, not who put it there, and nothing here records the answer anywhere else. ⚠ THAT
+ * CLAUSE READ "no later observation attributes it" UNTIL 2026-09-08, which speaks for observations
+ * outside this package that it knows nothing about. Closing the gap properly means a discriminated
+ * envelope around the pass-throughs, which is a wider change than this round is scoped to make.
+ */
+export interface ConfigCreated {
+    /** True when THIS invocation minted `.wyrd/scribe.json`. */
+    readonly config_created: boolean;
+}
+/**
+ * ⚠ THE FAILED-LEDGER OUTCOME CARRIES THE `Created`, AND IT IS A REQUIRED FIELD. The caller's next
+ * action depends entirely on knowing the page IS on disk and where — telling them only that
+ * something failed leaves them unable to distinguish "nothing happened" from "a page exists with no
+ * provenance", which are opposite situations demanding opposite repairs.
+ */
+export interface LedgerFailed extends ScribeRefusal, ConfigCreated {
+    readonly reason: 'PAGE_WRITTEN_LEDGER_FAILED';
+    readonly created: Created;
+    /**
+     * The fence or ledger refusal that actually fired, passed through rather than summarised.
+     *
+     * ⚠⚠ `ScribeRefusal` IS IN THIS UNION BECAUSE ITS ABSENCE WAS THE DEFECT. Every cause reaching
+     * here used to be typed `FenceRefusal`, whose `reason` is the fence's closed `FenceReason`
+     * union — so the one site that fires on a Scribe-side fault, the post-create line-size
+     * re-check, had NOTHING HONEST IT COULD TYPECHECK and returned a fabricated `IO_ERROR`. The
+     * caller was told a filesystem error lost their provenance when the truth was a request over a
+     * documented bound. **A too-narrow cause type does not prevent the wrong cause; it compels
+     * one.** Widening the union is what lets the site name `LINEAGE_LINE_TOO_LARGE`.
+     */
+    readonly cause: FenceRefusal | ScribeRefusal;
+}
+export interface Stamped extends ConfigCreated {
+    readonly ok: true;
+    readonly created: Created;
+    readonly record: LineageRecord;
+    readonly appended: number;
+}
+/**
+ * A Scribe-originated refusal from the stamp path, carrying the outer summary.
+ *
+ * ⚠⚠ EVERY SCRIBE-ORIGINATED SHAPE RETURNED AFTER STEP 4 CARRIES THE FIELD, AND THE ONE EXCLUSION
+ * IS THE FENCE PASS-THROUGH. The fence's refusals are returned unwrapped under D8 — a second
+ * vocabulary for one containment implementation is what D8 exists to prevent — so they carry no
+ * `config_created` and a caller reading one is NOT told whether this invocation minted the config.
+ * That is the whole of the exclusion, and it is stated on the type at `WritePageResult` below.
+ *
+ * ⚠⚠ THE SPAN REFUSALS WERE IN THAT EXCLUSION UNTIL 2026-09-08 AND ARE NOT ANY MORE. The retired
+ * argument was that `span.ts`'s envelope holds exactly `ok`, `reason` and `where`, that `ST20`
+ * asserts that own-key set exactly, and that widening it here would be this module rewriting
+ * another module's contract on its way past. What that reasoning missed is WHICH module's contract
+ * the returned value belongs to: a `SPAN_*` refusal reaching a `writePage` caller is `writePage`'s
+ * result, and the own-key envelope exists to stop UNDOCUMENTED keys reaching that caller rather
+ * than to fix a cardinality. `config_created` is documented, on the type, in the same words on
+ * every shape that carries it — so the envelope grows by exactly one documented key and `ST20`'s
+ * assertion is widened to say so. `span.ts`'s own arms are untouched: the module still returns
+ * three keys, and step 5 is what adds the fourth on its way out.
+ *
+ * ⚠ THE SHAPE-ONLY SPAN FAULTS AT STEP 3 STILL CARRY NOTHING, and that is the ordering rather than
+ * an exception: they are decided BEFORE `loadConfig` runs, so there is no answer to report.
+ */
+export interface StampRefusal extends ScribeRefusal, ConfigCreated {
+}
+/**
+ * A `SPAN_*` refusal from step 5, carrying the outer summary. See `StampRefusal` for why the span
+ * envelope grew by one key on 2026-09-08, and `span.ts` for why the module's own returns did not.
+ */
+export interface StampSpanRefusal extends SpanRefusal, ConfigCreated {
+}
+export interface WritePageOptions {
+    readonly gate: FsGate;
+    readonly appender: LedgerAppender;
+    readonly version: string;
+    /** Injected so an arm can pin `recorded_at` and the minted vault id. Production uses the defaults. */
+    readonly now?: () => Date;
+    readonly newUuid?: () => string;
+    /**
+     * ⚠ A SEPARATE SEAM FROM `newUuid`, WHICH MINTS THE VAULT ID. They are both v4 UUIDs and both
+     * default to `randomUUID`, and sharing one injection point would be convenient and wrong: an
+     * arm pinning the vault id to a fixed value would pin every `event_id` to the SAME value, which
+     * is precisely the collision `event_id` exists to make impossible. A suite that cannot pin one
+     * without flattening the other cannot measure either.
+     */
+    readonly newEventId?: () => string;
+    readonly cache?: SourceCache;
+}
+/**
+ * ⚠⚠ THE ONE RULE THIS UNION EXISTS TO STATE, AND IT IS A RULE ABOUT `config_created`:
+ *
+ *   **Every result `writePage` returns after `loadConfig` has run carries `config_created`, set
+ *   from what THIS invocation's `loadConfig` did — EXCEPT a fence refusal passed through unchanged
+ *   under D8, which carries no field at all.**
+ *
+ * So the union is written to make that sentence checkable rather than merely asserted. `ScribeRefusal`
+ * and `SpanRefusal` appear as `PreConfigRefusal`, a shape reachable ONLY from steps 1-3 — before
+ * `loadConfig` runs, where there is nothing to report — and every Scribe-originated shape from step
+ * 4 down carries the field. `FenceRefusal` is the documented exclusion: it is the ONE POST-CONFIG
+ * member that does not carry the field. `PreConfigRefusal` lacks it too, which is the ordering
+ * rather than an exclusion — it is decided before there is an answer.
+ *
+ * ⚠⚠ THE BARE `ScribeRefusal` MEMBER WAS THE DEFECT, NOT THE FIX. Until 2026-09-08 this union
+ * listed `ScribeRefusal` and `SpanRefusal` outright, which made the type say "a Scribe refusal may
+ * or may not carry the summary" — so a return site that dropped the field TYPECHECKED, and three
+ * did. A type that admits both answers cannot catch the wrong one. If a later change makes
+ * TypeScript reject a return site here, that site is an instance of the class, not a reason to
+ * widen the union back.
+ *
+ * ⚠⚠ AND THE BRAND IS WHAT MAKES IT BIND, WHICH LISTING THE SHAPES SEPARATELY DID NOT. Measured
+ * twice during this round, because the first attempt looked right and was not:
+ *
+ *   · With `PreConfigRefusal` declared as a bare `ScribeRefusal | SpanRefusal`, a post-config site
+ *     returning the refusal unwrapped still COMPILED. The two shapes are structurally identical,
+ *     so TypeScript matched the return against the pre-config member and had nothing to say. A
+ *     union whose members are structurally interchangeable cannot encode WHERE a value came from.
+ *   · With the brand declared OPTIONAL (`?: never`) it still compiled, for the plainer reason that
+ *     an optional property is satisfied by its absence. An optional brand brands nothing.
+ *
+ * So the brand is REQUIRED. `PRE_CONFIG` is a `unique symbol` declared and never defined, so the
+ * property exists only in the type system — no runtime value carries it, nothing can read it, and
+ * it costs no bytes. What it buys is that an unbranded bare refusal returned from step 4 down
+ * matches NO member of this union and is REJECTED, which is the whole point of writing the rule as
+ * a type instead of as a sentence.
+ */
+declare const PRE_CONFIG: unique symbol;
+/**
+ * A refusal decided at steps 1-3, before `loadConfig` has run. It carries no `config_created` for
+ * the plain reason that there is no answer yet, and the brand is what keeps it from standing in for
+ * the post-config shapes — see the note above for the two measurements that forced it.
+ */
+export type PreConfigRefusal = (ScribeRefusal | SpanRefusal) & {
+    readonly [PRE_CONFIG]: never;
+};
+export type WritePageResult = Stamped | StampRefusal | StampSpanRefusal | PreConfigRefusal | LedgerFailed | FenceRefusal;
+/**
+ * ⚠⚠ THE OUTER HALF IS THE **ONLY** SCOPE IN WHICH THIS MODULE HOLDS THE CALLER'S REQUEST OBJECT,
+ * and that is the containment rather than a tidy split. (The caller's own option hooks may close
+ * over that object and run downstream; they are the caller's, and outside what the split
+ * contains.) Steps 4-9 live in `stampValidated` below, which takes a
+ * `Validated` snapshot and has NO `request` parameter — so a downstream read of the caller's object
+ * is not a discipline anyone has to remember, it is `TS2304: Cannot find name 'request'`. The same
+ * argument the `preConfigRefuse` local makes about building a pre-config refusal: a name out of
+ * scope is a compile error.
+ *
+ * ⚠⚠ THE DISCRIMINATION IS `instanceof`, NOT `ok === false`, AND THE OLD TEST WAS A LIVE DEFECT.
+ * `isRefusalLike(checked)` read `.ok` through the prototype chain, so a request whose PROTOTYPE
+ * carried `{ ok: false }` came back from `preflight` validated, was read HERE as a refusal, and was
+ * returned to the caller as one — a refusal the caller minted, wearing this module's name. Asking
+ * `checked instanceof Validated` puts the answer on a prototype this module owns and never exports,
+ * which a caller cannot supply through inheritance or any other means. `isRefusalLike` stays where
+ * it belongs, guarding the fence and Scribe results below — values returned by the `gate` and the
+ * `appender`, which are injected dependencies. Reading `.ok` off those is trust in the dependency
+ * the caller chose to inject, not a defence against the request; it was never meant as one.
+ */
+export declare function writePage(request: WritePageRequest, options: WritePageOptions): Promise<WritePageResult>;
+export {};