wyrd-scribe 0.1.0

package/dist/refusal.js

@@ -0,0 +1,24 @@
+/**
+ * THE SCRIBE'S OWN REFUSAL SHAPE, and the one rule that binds every field in it.
+ *
+ * ⚠⚠ NEVER A RESOLVED ABSOLUTE PATH IN A `detail`. This is the fence's `META-no-outside-names`
+ * property carried across the package boundary — the fence returns `rel` and never `actual`
+ * precisely so a refusal cannot become a filesystem oracle, and a Scribe refusal that echoed a
+ * caller-supplied path would hand that oracle back one layer up. So a Scribe `detail` names a
+ * CONSTANT (`.wyrd/scribe.json`) or a BOUND (`65536 bytes`), never a request string.
+ *
+ * ⚠ THE CALLER'S OWN REQUEST STRING IS NOT SAFE TO ECHO EITHER, and that is the non-obvious half.
+ * It looks harmless — the caller already knows what it sent — but the refusal travels to a MODEL
+ * driving the server over stdio, and echoing `C:\Users\...\secrets\x.md` back into a transcript
+ * puts an outside name in the one place the fence spent seven rounds keeping it out of. A refusal
+ * says which RULE fired; it does not repeat the request.
+ *
+ * ⚠ FENCE REFUSALS PASS THROUGH UNCHANGED and are NOT re-wrapped in this shape. A parallel
+ * vocabulary for `ESCAPES`/`MISSING`/`EXISTS` would be a second thing to get wrong, and D8's whole
+ * argument is that there is one containment implementation and one set of words for its outcomes.
+ * `SOURCE_MISSING` in the spec's prose IS the fence's `MISSING`; it is not a distinct reason.
+ */
+export function scribeRefuse(reason, detail) {
+    return Object.freeze({ ok: false, reason, detail });
+}
+//# sourceMappingURL=refusal.js.map

package/dist/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA8BH,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,MAAc;IAC7D,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACjE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+import { Server } from '@modelcontextprotocol/server';
+import type { CallToolResult, Tool } from '@modelcontextprotocol/server';
+export { SERVER_VERSION } from './version.js';
+export declare const SERVER_NAME = "wyrd-scribe";
+export type Tier = 'A' | 'B' | 'C';
+export interface ServerContext {
+    readonly instructions: (activeTier: Tier, toolNames: readonly string[]) => string;
+}
+export interface ToolRegistration {
+    readonly declaration: Tool;
+    readonly call: (args: Record<string, unknown>) => Promise<CallToolResult>;
+}
+export type ToolLayerFactory<C extends ServerContext> = (context: C, activeTier: Tier) => readonly ToolRegistration[];
+export interface TierLayers<C extends ServerContext> {
+    readonly A: ToolLayerFactory<C>;
+    readonly B: ToolLayerFactory<C> | null;
+    readonly C: ToolLayerFactory<C> | null;
+}
+export interface TierPlan<C extends ServerContext> {
+    readonly ok: true;
+    readonly tier: Tier;
+    readonly factories: readonly ToolLayerFactory<C>[];
+}
+export interface StartupRefusal {
+    readonly ok: false;
+    readonly reason: 'UNRECOGNISED_TIER' | 'TIER_UNAVAILABLE';
+    readonly message: string;
+}
+/** Select every cumulative layer before a grant or transport is opened. */
+export declare function planTier<C extends ServerContext>(rawTier: string | undefined, layers: TierLayers<C>): TierPlan<C> | StartupRefusal;
+export declare const FENCE_DISCLOSURE: string;
+export declare function productionInstructions(root: string, tier: Tier, names: readonly string[]): string;
+/** Build one frozen registration map; listing and dispatch both consult this object. */
+export declare function createServer<C extends ServerContext>(plan: TierPlan<C>, context: C): Server;

package/dist/server.js

@@ -0,0 +1,145 @@
+import { Ajv } from 'ajv';
+import { Server } from '@modelcontextprotocol/server';
+import { SERVER_VERSION } from './version.js';
+export { SERVER_VERSION } from './version.js';
+export const SERVER_NAME = 'wyrd-scribe';
+const ORDER = Object.freeze(['A', 'B', 'C']);
+/** Select every cumulative layer before a grant or transport is opened. */
+export function planTier(rawTier, layers) {
+    const selected = rawTier ?? 'A';
+    if (selected !== 'A' && selected !== 'B' && selected !== 'C') {
+        return Object.freeze({
+            ok: false,
+            reason: 'UNRECOGNISED_TIER',
+            message: `UNRECOGNISED_TIER: wyrd-scribe does not recognise tier ${JSON.stringify(selected)}`
+        });
+    }
+    const tier = selected;
+    const needed = ORDER.slice(0, ORDER.indexOf(tier) + 1).map(name => layers[name]);
+    if (needed.some(factory => factory === null)) {
+        return Object.freeze({
+            ok: false,
+            reason: 'TIER_UNAVAILABLE',
+            message: `TIER_UNAVAILABLE: tier ${tier} is recognised but unavailable in this build`
+        });
+    }
+    return Object.freeze({
+        ok: true,
+        tier,
+        factories: Object.freeze(needed)
+    });
+}
+export const FENCE_DISCLOSURE = [
+    'Direct normalized `Arc/` targets are refused. The fence rejects a pre-existing parent alias',
+    'when its spelled and resolved paths differ after case-folding; its documented fold-equal-alias',
+    'limit still applies. The fence rechecks root object identity before each operation that',
+    'touches the filesystem;',
+    'component/leaf/link/rename races and the interval between that recheck and opening the file',
+    'remain. Append refusals may retain a partial or complete line. See the `wyrd-fence` README',
+    'section "Security boundary and limits" and the `createFileInGrant` / `appendLineInGrant` API',
+    'documentation for the authoritative contracts.'
+].join('\n');
+export function productionInstructions(root, tier, names) {
+    return [
+        `wyrd-scribe is serving exactly one canonical grant: ${root}`,
+        `The active write tier is ${tier}. Exactly these tools are registered: ${names.map(name => `\`${name}\``).join(', ')}.`,
+        '',
+        FENCE_DISCLOSURE,
+        '',
+        'Every write target and every derived_from source is grant-relative and is sent through',
+        'the imported `wyrd-fence` operations. Tier A creates files exclusively; an occupied leaf refuses',
+        'EXISTS. A successful write_page creates the page and appends one lineage line, and the',
+        'vault configuration may also project lineage into frontmatter. If the ledger fails after',
+        'the page is created, the page stays in place and the refusal reports that outcome.'
+    ].join('\n');
+}
+function memberNamedBy(error) {
+    if (error.keyword === 'additionalProperties') {
+        return error.params.additionalProperty ?? null;
+    }
+    if (error.keyword === 'required') {
+        return error.params.missingProperty ?? null;
+    }
+    return null;
+}
+function violationPath(error) {
+    const member = memberNamedBy(error);
+    return `arguments${error.instancePath}${member === null ? '' : `/${member}`}`;
+}
+/** Return one actionable violation. The deepest branch error wins over `oneOf`'s wrapper error. */
+function firstViolation(validate, args) {
+    if (validate(args))
+        return null;
+    const errors = validate.errors ?? [];
+    if (errors.length === 0)
+        return 'arguments did not satisfy inputSchema';
+    let chosen = errors[0];
+    for (const error of errors.slice(1)) {
+        if (error.instancePath.split('/').length > chosen.instancePath.split('/').length) {
+            chosen = error;
+        }
+    }
+    const path = violationPath(chosen);
+    if (chosen.keyword === 'additionalProperties')
+        return `${path} is not allowed by inputSchema`;
+    if (chosen.keyword === 'required')
+        return `${path} is required by inputSchema`;
+    return `${path} ${chosen.message ?? `violates inputSchema keyword ${chosen.keyword}`}`;
+}
+/** The sole route to a registration's port: its advertised schema is compiled and enforced here. */
+async function callValidated(registration, args) {
+    const violation = firstViolation(registration.validate, args);
+    if (violation !== null) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `wyrd-scribe refused invalid tool arguments: ${violation}.`
+                }]
+        };
+    }
+    return registration.call(args);
+}
+/** Build one frozen registration map; listing and dispatch both consult this object. */
+export function createServer(plan, context) {
+    const ajv = new Ajv({ allErrors: true, strict: true });
+    const entries = [];
+    for (const factory of plan.factories) {
+        for (const registration of factory(context, plan.tier)) {
+            const name = registration.declaration.name;
+            if (entries.some(([existing]) => existing === name)) {
+                throw new Error(`duplicate tool registration: ${name}`);
+            }
+            entries.push([name, Object.freeze({
+                    declaration: registration.declaration,
+                    call: registration.call,
+                    validate: ajv.compile(registration.declaration.inputSchema)
+                })]);
+        }
+    }
+    const registrations = Object.freeze(Object.fromEntries(entries));
+    const names = Object.freeze(Object.keys(registrations));
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: { tools: {} },
+        instructions: context.instructions(plan.tier, names)
+    });
+    server.setRequestHandler('tools/list', () => ({
+        tools: Object.values(registrations).map(registration => registration.declaration)
+    }));
+    server.setRequestHandler('tools/call', async (request) => {
+        const registration = registrations[request.params.name];
+        if (registration === undefined) {
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: `wyrd-scribe has no tool named ${request.params.name}.`
+                    }]
+            };
+        }
+        const args = (request.params.arguments ?? {});
+        return callValidated(registration, args);
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/source.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SOURCES — read and hashed THROUGH THE EXISTING GATE, with no fence change of any kind.
+ *
+ * ⚠⚠ D8 IS THE WHOLE REASON THIS MODULE EXISTS AT ALL, and the hole it closed is worth restating
+ * because the shape is easy to rebuild by accident. The spec's first draft fenced only the path
+ * being WRITTEN; the paths being CITED went straight to read-and-hash with no containment check.
+ * That made `write_page` an arbitrary-file-read primitive — name any path the process can reach as
+ * a "source", get back confirmation of its existence and its content hash, and because D4 stores
+ * the QUOTED TEXT, get its bytes copied permanently into the ledger. Every read here goes through
+ * `readFileInGrant`/`hashInGrant`, which are the identical code path the Reader uses.
+ *
+ * ⚠⚠ AND THE HASH IS NOT A FORMALITY — IT IS THE CHIMERA CHECK (D4). The window loop reads a
+ * source in pieces; a source edited between the first window and the last yields a buffer that
+ * existed at no instant, and span offsets over a chimera are SILENT MISLOCATION, which is the one
+ * failure this whole lane is built against. So the bytes we hold are hashed ourselves and compared
+ * against `hashInGrant`'s independent full read of the same path. A mismatch REFUSES.
+ *
+ * ⚠ THAT COMPARISON IS A DETECTOR, NOT A LOCK. Nothing here holds the file open across the two
+ * reads — the gate opens and closes per call, deliberately, because a long-held handle is a
+ * different hazard — so a source edited and edited BACK between them passes. The claim is
+ * "detects the ordinary case", never "serialises against a concurrent writer".
+ */
+import type { FenceRefusal, FsGate } from 'wyrd-fence';
+import type { ScribeRefusal } from './refusal.js';
+export interface SourceBytes {
+    /** The grant-relative path AS THE FENCE REPORTS IT, separators already folded to `/`. */
+    readonly rel: string;
+    readonly bytes: Buffer;
+    readonly digest: string;
+    readonly size: number;
+}
+/**
+ * ⚠ SEPARATORS ARE FOLDED HERE AND NOWHERE ELSE. The fence builds `rel` with `path.relative`,
+ * which yields BACKSLASHES on win32 — so a ledger written on this host and read on any other would
+ * carry a path no POSIX consumer can resolve, and the two hosts would disagree about whether two
+ * records name the same page. The ledger's path is a portable identity, so the fold happens at the
+ * boundary where a fence value becomes a RECORD value.
+ */
+export declare function toLedgerPath(rel: string): string;
+/**
+ * ⚠ THE FENCE'S OWN `isRefusal`, IMPORTED RATHER THAN RE-DECLARED — spec D8, and the same rule the
+ * package manifest states about `createFsGate`. This file used to carry a byte-identical private
+ * copy called `isRefusalLike`; so did `config.ts`. A local copy of a guard that decides whether a
+ * fence result is a refusal is a second definition of the fence's own contract, free to drift from
+ * it silently. ⚠ `stamp.ts` deliberately keeps a private one — read the note there before assuming
+ * it was missed.
+ */
+/**
+ * The per-process source cache the cost model requires (spec "Cost model": a stamp is
+ * O(source bytes) once per source per process).
+ *
+ * ⚠⚠ THE KEY IS `path + size + digest`, WHICH MEANS A HIT STILL COSTS ONE FULL READ. That is not
+ * an oversight and it is the honest version of the criterion. The cost model's original key was
+ * `(path, size, mtime)`, but the gate exposes no mtime — and the only identity it DOES expose is
+ * the digest, which cannot be known without reading. So what the cache buys is skipping the WINDOW
+ * LOOP and the second buffer, not skipping I/O: `hashInGrant` streams in 64 KiB windows and
+ * retains nothing, while the window loop materialises the whole source in memory. On a hit the
+ * resident cost is one buffer instead of two and the traversal is one pass instead of two.
+ *
+ * ⚠ AC7's "reads that source's bytes once" is therefore NOT satisfied by this cache, and saying so
+ * is the point of this paragraph. Satisfying it literally needs an mtime the gate does not expose;
+ * claiming it while the digest key forces a read would be a cost claim the code cannot back.
+ */
+export declare class SourceCache {
+    #private;
+    get(rel: string, size: number, digest: string): SourceBytes | undefined;
+    set(entry: SourceBytes): void;
+    get size(): number;
+}
+/**
+ * Read a source whole, through the gate, and prove the bytes we hold are the bytes on disk.
+ *
+ * Order matters: HASH FIRST. The hash gives the cache key, so a hit skips the window loop entirely;
+ * hashing second would mean always paying for the loop before discovering the answer was cached.
+ */
+export declare function readSource(gate: FsGate, request: string, cache: SourceCache): Promise<SourceBytes | ScribeRefusal | FenceRefusal>;

package/dist/source.js

@@ -0,0 +1,134 @@
+/**
+ * SOURCES — read and hashed THROUGH THE EXISTING GATE, with no fence change of any kind.
+ *
+ * ⚠⚠ D8 IS THE WHOLE REASON THIS MODULE EXISTS AT ALL, and the hole it closed is worth restating
+ * because the shape is easy to rebuild by accident. The spec's first draft fenced only the path
+ * being WRITTEN; the paths being CITED went straight to read-and-hash with no containment check.
+ * That made `write_page` an arbitrary-file-read primitive — name any path the process can reach as
+ * a "source", get back confirmation of its existence and its content hash, and because D4 stores
+ * the QUOTED TEXT, get its bytes copied permanently into the ledger. Every read here goes through
+ * `readFileInGrant`/`hashInGrant`, which are the identical code path the Reader uses.
+ *
+ * ⚠⚠ AND THE HASH IS NOT A FORMALITY — IT IS THE CHIMERA CHECK (D4). The window loop reads a
+ * source in pieces; a source edited between the first window and the last yields a buffer that
+ * existed at no instant, and span offsets over a chimera are SILENT MISLOCATION, which is the one
+ * failure this whole lane is built against. So the bytes we hold are hashed ourselves and compared
+ * against `hashInGrant`'s independent full read of the same path. A mismatch REFUSES.
+ *
+ * ⚠ THAT COMPARISON IS A DETECTOR, NOT A LOCK. Nothing here holds the file open across the two
+ * reads — the gate opens and closes per call, deliberately, because a long-held handle is a
+ * different hazard — so a source edited and edited BACK between them passes. The claim is
+ * "detects the ordinary case", never "serialises against a concurrent writer".
+ */
+import { isRefusal } from 'wyrd-fence';
+import { hashText } from './lineage.js';
+import { scribeRefuse } from './refusal.js';
+/**
+ * The window the source loop asks for. The gate clamps anything above its own `MAX_LIMIT` silently,
+ * so asking for more than 1 MiB would be a request the gate quietly rewrites — a number that reads
+ * as a decision and is not one.
+ */
+const SOURCE_WINDOW = 1 << 20;
+/**
+ * ⚠ SEPARATORS ARE FOLDED HERE AND NOWHERE ELSE. The fence builds `rel` with `path.relative`,
+ * which yields BACKSLASHES on win32 — so a ledger written on this host and read on any other would
+ * carry a path no POSIX consumer can resolve, and the two hosts would disagree about whether two
+ * records name the same page. The ledger's path is a portable identity, so the fold happens at the
+ * boundary where a fence value becomes a RECORD value.
+ */
+export function toLedgerPath(rel) {
+    return rel.split('\\').join('/');
+}
+/**
+ * ⚠ THE FENCE'S OWN `isRefusal`, IMPORTED RATHER THAN RE-DECLARED — spec D8, and the same rule the
+ * package manifest states about `createFsGate`. This file used to carry a byte-identical private
+ * copy called `isRefusalLike`; so did `config.ts`. A local copy of a guard that decides whether a
+ * fence result is a refusal is a second definition of the fence's own contract, free to drift from
+ * it silently. ⚠ `stamp.ts` deliberately keeps a private one — read the note there before assuming
+ * it was missed.
+ */
+/**
+ * The per-process source cache the cost model requires (spec "Cost model": a stamp is
+ * O(source bytes) once per source per process).
+ *
+ * ⚠⚠ THE KEY IS `path + size + digest`, WHICH MEANS A HIT STILL COSTS ONE FULL READ. That is not
+ * an oversight and it is the honest version of the criterion. The cost model's original key was
+ * `(path, size, mtime)`, but the gate exposes no mtime — and the only identity it DOES expose is
+ * the digest, which cannot be known without reading. So what the cache buys is skipping the WINDOW
+ * LOOP and the second buffer, not skipping I/O: `hashInGrant` streams in 64 KiB windows and
+ * retains nothing, while the window loop materialises the whole source in memory. On a hit the
+ * resident cost is one buffer instead of two and the traversal is one pass instead of two.
+ *
+ * ⚠ AC7's "reads that source's bytes once" is therefore NOT satisfied by this cache, and saying so
+ * is the point of this paragraph. Satisfying it literally needs an mtime the gate does not expose;
+ * claiming it while the digest key forces a read would be a cost claim the code cannot back.
+ */
+export class SourceCache {
+    #entries = new Map();
+    #key(rel, size, digest) {
+        return `${rel}\u0000${size}\u0000${digest}`;
+    }
+    get(rel, size, digest) {
+        return this.#entries.get(this.#key(rel, size, digest));
+    }
+    set(entry) {
+        this.#entries.set(this.#key(entry.rel, entry.size, entry.digest), entry);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}
+/**
+ * Read a source whole, through the gate, and prove the bytes we hold are the bytes on disk.
+ *
+ * Order matters: HASH FIRST. The hash gives the cache key, so a hit skips the window loop entirely;
+ * hashing second would mean always paying for the loop before discovering the answer was cached.
+ */
+export async function readSource(gate, request, cache) {
+    const hashed = await gate.hashInGrant(request);
+    // ⚠ PASSED THROUGH UNDER THE FENCE'S OWN REASON — `ESCAPES`, `MISSING`, `DENIED`. The spec's
+    // `SOURCE_MISSING` IS this `MISSING`; inventing a parallel word would make two vocabularies for
+    // one outcome and force every consumer to learn both.
+    if (isRefusal(hashed))
+        return hashed;
+    const rel = toLedgerPath(hashed.rel);
+    const cached = cache.get(rel, hashed.size, hashed.digest);
+    if (cached)
+        return cached;
+    const chunks = [];
+    let held = 0;
+    let offset = 0;
+    for (;;) {
+        const slice = await gate.readFileInGrant(request, offset, SOURCE_WINDOW);
+        if (isRefusal(slice))
+            return slice;
+        chunks.push(slice.bytes);
+        held += slice.bytes.length;
+        if (!slice.truncated)
+            break;
+        // ⚠⚠ A NON-ADVANCING WINDOW IS A REFUSAL, NEVER A RETRY. `nextOffset` can equal `offset`
+        // only if the gate kept zero bytes while still reporting more to come; looping on that is
+        // an unbounded spin inside a server, and treating it as "the source moved under us" is both
+        // true and the outcome a caller can act on.
+        if (slice.nextOffset <= offset) {
+            return scribeRefuse('SOURCE_CHANGED_DURING_READ', 'a source stopped yielding bytes before the end it reported');
+        }
+        offset = slice.nextOffset;
+    }
+    const bytes = Buffer.concat(chunks, held);
+    const ours = hashText(bytes);
+    /**
+     * ⚠⚠ BOTH HALVES ARE COMPARED, AND THE SIZE HALF IS NOT REDUNDANT. A digest comparison alone
+     * would pass if the loop somehow held a DIFFERENT number of bytes whose hash collided — which
+     * is not the realistic case — but more usefully, comparing sizes catches the ordinary shape of
+     * this failure (the file grew or shrank between the hash and the loop) with a check that cannot
+     * itself be fooled by a truncated read reporting success.
+     */
+    if (bytes.length !== hashed.size || ours !== hashed.digest) {
+        return scribeRefuse('SOURCE_CHANGED_DURING_READ', 'a source changed between being hashed and being read; span offsets over it would be silently wrong');
+    }
+    const entry = Object.freeze({ rel, bytes, digest: hashed.digest, size: hashed.size });
+    cache.set(entry);
+    return entry;
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

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

package/dist/span.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ */
+export type SpanReason = 'SPAN_INVALID_RANGE' | 'SPAN_INVALID_QUOTE' | 'SPAN_NOT_ALIGNED' | 'SPAN_NOT_FOUND' | 'SPAN_AMBIGUOUS' | 'SPAN_MISMATCH';
+/**
+ * The member at fault — **absence included**, which is the part the narrow wording missed.
+ * `{ offset: 0 }` refuses `where: 'length'`, naming a member the caller never sent, because THERE
+ * the fault IS the absence and naming it is the informative answer. That is not in tension with
+ * the quote-only alignment path refusing `'request'`: there the fault is a property of a derived
+ * span and the absent members are not at fault at all. So `where` names the member at fault,
+ * supplied or absent — never "a supplied member."
+ *
+ * ⚠ ENUMERATED SO THE TYPE CANNOT CARRY A VALUE — and the type is not the enforcement. A frozen
+ * own accessor named `where` can serve an enumerated value to the first readers and the whole
+ * source afterwards; `envelope()`'s data-property assertion is what forbids it.
+ */
+export type SpanWhere = 'offset' | 'length' | 'quote' | 'request';
+export interface ResolvedSpan {
+    readonly ok: true;
+    readonly offset: number;
+    readonly length: number;
+    readonly quote: string;
+}
+/**
+ * ⚠ NO FREE-TEXT FIELD, AND NO SLOT FOR A RESOLUTION. There is no place in this shape for an
+ * offset, a length, a quote, a candidate list or the source bytes. A `detail: string` was removed
+ * at round 2 precisely because an unrestricted string can hold all of them.
+ */
+export interface SpanRefusal {
+    readonly ok: false;
+    readonly reason: SpanReason;
+    readonly where: SpanWhere;
+}
+/**
+ * Three shapes, all resolving to the same triple (D4 minus the hash, which is the fence's).
+ * Any other shape — a lone `offset`, an unknown key, a non-object — refuses `SPAN_INVALID_RANGE`.
+ */
+export type SpanRequest = {
+    readonly offset: number;
+    readonly length: number;
+} | {
+    readonly quote: string;
+} | {
+    readonly offset: number;
+    readonly length: number;
+    readonly quote: string;
+};
+/**
+ * Resolves a span request against the source bytes it was recorded over.
+ *
+ * ⚠ THE SOURCE IS A CALLER CONTRACT, NOT A REQUEST MEMBER. A non-Buffer source THROWS rather than
+ * refusing: `where` names a member of the request, and there is no honest value for it here. A
+ * refusal would have to lie about which member was at fault.
+ */
+/**
+ * EVERY REFUSAL THIS MODULE CAN REACH WITHOUT THE SOURCE BYTES, AND NOTHING ELSE.
+ *
+ * ⚠⚠ IT EXISTS SO A GUARANTEED REFUSAL CAN BE DECIDED BEFORE A SOURCE IS READ. `stamp.ts` calls it
+ * ahead of `loadConfig` and ahead of every read: a request carrying a malformed span is going to
+ * refuse whatever the bytes turn out to be, so reading the source first buys nothing and COSTS the
+ * existence-oracle property — an existing in-grant source and a missing one would otherwise produce
+ * different reasons and different timings for a request that was always going to refuse. That is
+ * the same argument the `Arc/` screen's ordering makes, applied to the other guaranteed refusal.
+ *
+ * ⚠⚠ IT IS `resolveSpan`'s OWN FIRST STEP, NOT A SECOND COPY OF THESE CHECKS. A parallel
+ * implementation is a thing that drifts: the moment one side learns a rule the other has not, a
+ * request refuses in one place and resolves in the other, and the pre-check stops being a
+ * prediction of what the resolver will do. One function, two callers.
+ *
+ * ⚠ WHAT IT DELIBERATELY DOES NOT DECIDE: range-against-length, alignment, the lossy round-trip,
+ * `SPAN_NOT_FOUND`, `SPAN_AMBIGUOUS` and `SPAN_MISMATCH`. Every one of those is a question about
+ * the bytes, and answering it here would need the source — which is precisely what must not be read
+ * yet. A `SpanMembers` from this function is NOT a prediction of success; it means only "nothing is
+ * decided yet".
+ *
+ * ⚠⚠ IT RETURNS THE MEMBERS IT READ, AND THAT IS THE READ-ONCE RULE SURVIVING THE EXTRACTION. If
+ * this function read the request's members and `resolveSpan` then read them AGAIN, a caller-supplied
+ * accessor would fire twice and could serve one value to the shape check and another to the
+ * resolver — which is precisely the defect `M1` pins, rebuilt by the refactor that was supposed to
+ * be behaviour-preserving. Handing the values back means the request object is read exactly once on
+ * every path, `stamp.ts`'s pre-check included.
+ */
+export interface SpanMembers {
+    readonly hasOffset: boolean;
+    readonly hasQuote: boolean;
+    readonly offsetValue: unknown;
+    readonly lengthValue: unknown;
+    readonly quoteValue: unknown;
+}
+export declare function spanShapeFault(request: SpanRequest): SpanRefusal | SpanMembers;
+export declare function resolveSpan(bytes: Buffer, request: SpanRequest): ResolvedSpan | SpanRefusal;