sfora-cli 0.9.0 → 0.11.0

package/dist/format/__tests__/byteStable.js

@@ -0,0 +1,64 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// Round-trip assertions for the document/entity serializers.
+//
+// Two properties, checked separately, because they are not the same claim:
+//
+//   byte-stable  — one round trip reaches a fixpoint: roundTrip(roundTrip(s))
+//                  is byte-identical to roundTrip(s). A serializer is allowed to
+//                  canonicalize on first contact; it is not allowed to keep
+//                  changing its mind. This is the property that stops documents
+//                  growing a heading or a fence per save.
+//   identity     — roundTrip(s) === s. Only true for sources that are already
+//                  canonical, i.e. ones our own serializers emitted.
+//
+// No vitest import on purpose: this file lives under src/, so packages/sfora's
+// sync-format copies it into the published CLI tarball and it has to compile
+// with nothing but TypeScript.
+import { buildDocument } from "../markdown/document.js";
+import { serializeFrontmatter } from "../markdown/yaml.js";
+import { parseDocumentWithFallback } from "../parseWithFallback.js";
+// The document envelope round trip: read a file the way /v1/fs reads it, write
+// it back the way /v1/fs writes it. Frontmatter keys keep their source order
+// (object insertion order), so a clean file comes back unchanged.
+export const documentRoundTrip = (source) => {
+    const parsed = parseDocumentWithFallback(source);
+    const fm = serializeFrontmatter(Object.entries(parsed.frontmatter));
+    return buildDocument(fm, parsed.title, parsed.body);
+};
+function describeDivergence(a, b) {
+    const limit = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < limit && a[i] === b[i])
+        i++;
+    const window = (s) => JSON.stringify(s.slice(Math.max(0, i - 40), i + 40));
+    return `first divergence at char ${i}\n  pass 1: ${window(a)}\n  pass 2: ${window(b)}`;
+}
+// parse → serialize → parse → serialize; the second pass must be byte-identical
+// to the first.
+export function assertByteStable(source, roundTrip = documentRoundTrip) {
+    const once = roundTrip(source);
+    const twice = roundTrip(once);
+    if (twice !== once) {
+        throw new Error(`round trip is not byte-stable: ${describeDivergence(once, twice)}`);
+    }
+}
+// Stronger: the source is already canonical and must survive untouched.
+export function assertRoundTripIdentity(source, roundTrip = documentRoundTrip) {
+    const once = roundTrip(source);
+    if (once !== source) {
+        throw new Error(`round trip changed a canonical source: ${describeDivergence(source, once)}`);
+    }
+    assertByteStable(source, roundTrip);
+}
+// True when one round trip is a fixpoint — the predicate form, for corpora where
+// some divergence is expected and counted against a baseline rather than failing.
+export function isByteStable(source, roundTrip = documentRoundTrip) {
+    try {
+        assertByteStable(source, roundTrip);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/format/blockSplice.d.ts

@@ -0,0 +1,135 @@
+/**
+ * One block of a source string: its byte range, and its identity.
+ *
+ * `key` is what "unchanged" means. Two blocks with the same key are the same
+ * block for splice purposes and the old one's bytes win. A caller that keys by
+ * raw text gets a byte-exact diff (and no canonicalization softening at all);
+ * a caller that keys by a position-stripped parse gets the semantic diff this
+ * module exists to serve.
+ */
+export interface SourceBlock {
+    /** Byte offset of the block's first byte. */
+    start: number;
+    /** One past the block's last byte. */
+    end: number;
+    /** Identity under whatever equality the caller decided on. */
+    key: string;
+}
+/** Why a splice gave up and handed back the new source whole. */
+export type BlockSpliceFallback = "none"
+/** One side has no blocks at all — there is nothing to preserve or to keep. */
+ | "no-blocks"
+/** A block list was out of order, overlapping, or out of bounds. */
+ | "unusable-blocks";
+export interface BlockSpliceResult {
+    /** The bytes to store. */
+    source: string;
+    /** Old blocks that kept their bytes. */
+    kept: number;
+    /** Blocks written from the new source. */
+    rewritten: number;
+    /** Set when the result is just `newSource`. */
+    fallback: BlockSpliceFallback;
+}
+/**
+ * Above this many DP cells the middle region is treated as one changed run
+ * instead of being aligned properly.
+ *
+ * The prefix/suffix trim below already handles the shape a real edit has — one
+ * changed region, everything before and after it identical — in linear time,
+ * so the quadratic pass only ever runs on a genuinely scattered diff. 250k
+ * cells is a 500-block-by-500-block middle, which is a document nobody has;
+ * past it the splice degrades to exactly what open-knowledge's
+ * `map-driven-splice.ts` does at every size (one over-wide contiguous splice),
+ * which is correct, merely less preserving.
+ *
+ * Exported so the test that pins the boundary can build the block lists either
+ * side of it from this number rather than from a second copy of it: a budget
+ * quietly raised past a hard-coded 500×500 would leave a test that still
+ * passes while asserting nothing about the fallback.
+ */
+export declare const ALIGNMENT_CELL_BUDGET = 250000;
+/**
+ * A run of blocks that is either kept from old or written from new.
+ *
+ * `kept: true` means every block in the range keyed identically on both sides,
+ * one for one, so `oldTo - oldFrom === newTo - newFrom` and the i-th old block
+ * IS the i-th new block. `kept: false` means the two ranges are the region the
+ * alignment could not explain: they may be different lengths, and nothing here
+ * says which old block became which new one — that judgement belongs to the
+ * consumer, because the splice does not need it and a rebinding ledger does.
+ */
+export interface BlockRun {
+    kept: boolean;
+    /** Half-open index range into the old block list. */
+    oldFrom: number;
+    oldTo: number;
+    /** Half-open index range into the new block list. */
+    newFrom: number;
+    newTo: number;
+}
+/**
+ * How much of the correspondence was actually computed.
+ *
+ * `"exact"` is a real alignment: every block that survives unchanged is inside
+ * a kept run. `"budget"` says the middle region was past
+ * `ALIGNMENT_CELL_BUDGET` and was handed back as one changed run without being
+ * looked at, so blocks that did survive are sitting inside it unrecognised.
+ * The splice does not care — an over-wide changed run is merely less
+ * preserving — but a consumer that reads a changed run as "these blocks were
+ * edited" would be stating something the alignment never checked, so the
+ * degradation is reported rather than inferred from the run shapes.
+ */
+export type BlockAlignmentQuality = "exact" | "budget";
+/** The old↔new block correspondence, and how far it was actually worked out. */
+export interface BlockAlignment {
+    /**
+     * Alternating kept/changed runs covering both lists end to end: every index
+     * of `oldBlocks` appears in exactly one run's old range, every index of
+     * `newBlocks` in exactly one run's new range, both in ascending order.
+     */
+    runs: BlockRun[];
+    quality: BlockAlignmentQuality;
+}
+/**
+ * Assemble the bytes to store from `oldSource` and `newSource`.
+ *
+ * The contract, in order of how much it matters:
+ *
+ * 1. If every key matches, the result is `oldSource` byte-for-byte. Not
+ *    "equivalent to" — identical, including its trailing newline or lack of
+ *    one. A save that changed nothing must reach the store as no change at
+ *    all, or the whole exercise is decorative.
+ * 2. A block whose key changed contributes its NEW bytes, together with the
+ *    gap bytes on either side of it, because a new or deleted block has to be
+ *    able to bring its own blank lines.
+ * 3. A block whose key did not change contributes its OLD bytes, and so do
+ *    the gaps between two such blocks.
+ * 4. The bytes outside every block — leading whitespace, the trailing
+ *    newline — belong to no block, so they follow the block nearest them: old
+ *    if that first/last block was kept, new if it was rewritten. Kept-at-the-
+ *    edge is what makes rule 1 exact; rewritten-at-the-edge is what lets a
+ *    document that really was replaced arrive with its own final newline
+ *    instead of inheriting the absence of one.
+ */
+export declare function spliceBlocks(oldSource: string, newSource: string, oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockSpliceResult;
+/**
+ * Split both block lists into alternating kept/changed runs — the old↔new
+ * correspondence, on its own, with no bytes involved.
+ *
+ * Common prefix and suffix first — that is the entire diff for a normal edit
+ * and it costs one pass. What is left in the middle gets a longest-common-
+ * subsequence alignment so that two edits with untouched blocks between them
+ * keep those blocks' bytes; open-knowledge's version collapses that case into
+ * one over-wide splice, and it is the one thing here worth doing better than
+ * the reference, because "find and replace in three places" is an ordinary
+ * afternoon and it should not rewrite the paragraphs in between.
+ *
+ * Public because it is most of a rebinding ledger and it already runs on every
+ * write. `spliceBlocks` reads it for bytes; a caller that has derived an
+ * identity from the same keys reads it for what became what. Only `key` is
+ * consulted, so a caller holding keys and no offsets can ask this directly —
+ * the offset sanity `spliceBlocks` insists on is a slicing concern, not an
+ * alignment one.
+ */
+export declare function alignBlockRuns(oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockAlignment;

package/dist/format/blockSplice.js

@@ -0,0 +1,330 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// The block-aligned splice: write only the blocks that changed.
+//
+// Every save in sfora goes through a serializer, and a serializer has
+// opinions — `*em*` becomes `_em_`, a setext heading becomes an ATX one, a
+// table's padding is re-laid. Those opinions are correct for the block the
+// author just edited and pure vandalism everywhere else: change one word in
+// paragraph nine and the naive write path hands the store a document in which
+// all forty blocks have been re-spelled. The author's diff is unreadable, the
+// activity trail lies about what changed, and every byte-form the serializer
+// cannot represent is gone for good.
+//
+// This module is the fix, and it is deliberately the dumbest possible one.
+// It knows nothing about serializers, editors or markdown syntax. It takes
+// two strings and two lists of BLOCKS — byte ranges plus an identity key —
+// and returns a third string assembled from old bytes wherever the keys agree
+// and new bytes wherever they do not. The key is where the intelligence
+// lives, and it lives in the caller: `blockSpliceMdast.ts` derives one by
+// parsing and stripping positions, so `*em*` and `_em_` key the same and the
+// OLD bytes survive. Nothing in this file can tell the difference, which is
+// exactly why it will survive the serializer swap wave 2 is heading for.
+//
+// There are two exits. `spliceBlocks` is the one the write paths call and
+// returns bytes. `alignBlockRuns` is the correspondence underneath it —
+// which old block became which new one — returned on its own, because that
+// question has a second consumer: a document's derived block ids change when
+// their blocks change, and the ledger that carries an anchor across an edit
+// needs exactly this answer and nothing else from this file. It was already
+// being computed on every save and thrown away.
+//
+// Zero dependencies, no parser, no I/O — it ships in the CLI.
+/**
+ * Above this many DP cells the middle region is treated as one changed run
+ * instead of being aligned properly.
+ *
+ * The prefix/suffix trim below already handles the shape a real edit has — one
+ * changed region, everything before and after it identical — in linear time,
+ * so the quadratic pass only ever runs on a genuinely scattered diff. 250k
+ * cells is a 500-block-by-500-block middle, which is a document nobody has;
+ * past it the splice degrades to exactly what open-knowledge's
+ * `map-driven-splice.ts` does at every size (one over-wide contiguous splice),
+ * which is correct, merely less preserving.
+ *
+ * Exported so the test that pins the boundary can build the block lists either
+ * side of it from this number rather than from a second copy of it: a budget
+ * quietly raised past a hard-coded 500×500 would leave a test that still
+ * passes while asserting nothing about the fallback.
+ */
+export const ALIGNMENT_CELL_BUDGET = 250_000;
+/**
+ * Assemble the bytes to store from `oldSource` and `newSource`.
+ *
+ * The contract, in order of how much it matters:
+ *
+ * 1. If every key matches, the result is `oldSource` byte-for-byte. Not
+ *    "equivalent to" — identical, including its trailing newline or lack of
+ *    one. A save that changed nothing must reach the store as no change at
+ *    all, or the whole exercise is decorative.
+ * 2. A block whose key changed contributes its NEW bytes, together with the
+ *    gap bytes on either side of it, because a new or deleted block has to be
+ *    able to bring its own blank lines.
+ * 3. A block whose key did not change contributes its OLD bytes, and so do
+ *    the gaps between two such blocks.
+ * 4. The bytes outside every block — leading whitespace, the trailing
+ *    newline — belong to no block, so they follow the block nearest them: old
+ *    if that first/last block was kept, new if it was rewritten. Kept-at-the-
+ *    edge is what makes rule 1 exact; rewritten-at-the-edge is what lets a
+ *    document that really was replaced arrive with its own final newline
+ *    instead of inheriting the absence of one.
+ */
+export function spliceBlocks(oldSource, newSource, oldBlocks, newBlocks) {
+    if (oldBlocks.length === 0 || newBlocks.length === 0) {
+        return { source: newSource, kept: 0, rewritten: 0, fallback: "no-blocks" };
+    }
+    if (!blocksAreUsable(oldBlocks, oldSource.length) ||
+        !blocksAreUsable(newBlocks, newSource.length)) {
+        return {
+            source: newSource,
+            kept: 0,
+            rewritten: 0,
+            fallback: "unusable-blocks",
+        };
+    }
+    const { runs } = alignBlockRuns(oldBlocks, newBlocks);
+    const parts = [];
+    // The head: everything before the first block, from whichever side owns it.
+    parts.push(runs[0].kept
+        ? oldSource.slice(0, oldBlocks[0].start)
+        : newSource.slice(0, newBlocks[0].start));
+    let kept = 0;
+    let rewritten = 0;
+    for (const run of runs) {
+        if (run.kept) {
+            parts.push(oldSource.slice(oldBlocks[run.oldFrom].start, oldBlocks[run.oldTo - 1].end));
+            kept += run.oldTo - run.oldFrom;
+            continue;
+        }
+        // A changed run owns the gaps on both sides of it in the NEW source: the
+        // bytes from the end of the last kept new block to the start of the next
+        // one. At an edge of the document it stops at the edge block's own
+        // boundary; the head/tail beyond it is added once, outside this loop,
+        // under rule 4.
+        const from = run.newFrom > 0 ? newBlocks[run.newFrom - 1].end : newBlocks[0].start;
+        const to = run.newTo < newBlocks.length
+            ? newBlocks[run.newTo].start
+            : newBlocks[newBlocks.length - 1].end;
+        parts.push(newSource.slice(from, to));
+        rewritten += run.newTo - run.newFrom;
+    }
+    // The tail: everything after the last block, from whichever side owns it.
+    parts.push(runs[runs.length - 1].kept
+        ? oldSource.slice(oldBlocks[oldBlocks.length - 1].end)
+        : newSource.slice(newBlocks[newBlocks.length - 1].end));
+    return { source: parts.join(""), kept, rewritten, fallback: "none" };
+}
+/**
+ * Offsets have to be ascending, non-overlapping and inside the string, because
+ * the assembly above slices without re-checking and a bad list would silently
+ * produce scrambled bytes rather than an error. Callers feed these from a
+ * parser; a parser that ever emits a tree whose top-level children overlap is
+ * a bug we would rather see as a whole-document write than as a corrupted one.
+ */
+function blocksAreUsable(blocks, length) {
+    let previousEnd = 0;
+    for (const block of blocks) {
+        if (!Number.isInteger(block.start) || !Number.isInteger(block.end)) {
+            return false;
+        }
+        if (block.start < previousEnd)
+            return false;
+        if (block.end < block.start)
+            return false;
+        if (block.end > length)
+            return false;
+        previousEnd = block.end;
+    }
+    return true;
+}
+/**
+ * Split both block lists into alternating kept/changed runs — the old↔new
+ * correspondence, on its own, with no bytes involved.
+ *
+ * Common prefix and suffix first — that is the entire diff for a normal edit
+ * and it costs one pass. What is left in the middle gets a longest-common-
+ * subsequence alignment so that two edits with untouched blocks between them
+ * keep those blocks' bytes; open-knowledge's version collapses that case into
+ * one over-wide splice, and it is the one thing here worth doing better than
+ * the reference, because "find and replace in three places" is an ordinary
+ * afternoon and it should not rewrite the paragraphs in between.
+ *
+ * Public because it is most of a rebinding ledger and it already runs on every
+ * write. `spliceBlocks` reads it for bytes; a caller that has derived an
+ * identity from the same keys reads it for what became what. Only `key` is
+ * consulted, so a caller holding keys and no offsets can ask this directly —
+ * the offset sanity `spliceBlocks` insists on is a slicing concern, not an
+ * alignment one.
+ */
+export function alignBlockRuns(oldBlocks, newBlocks) {
+    const shorter = Math.min(oldBlocks.length, newBlocks.length);
+    let prefix = 0;
+    while (prefix < shorter && oldBlocks[prefix].key === newBlocks[prefix].key) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < shorter - prefix &&
+        oldBlocks[oldBlocks.length - 1 - suffix].key ===
+            newBlocks[newBlocks.length - 1 - suffix].key) {
+        suffix++;
+    }
+    const runs = [];
+    if (prefix > 0) {
+        runs.push({ kept: true, oldFrom: 0, oldTo: prefix, newFrom: 0, newTo: prefix });
+    }
+    const oldMid = oldBlocks.slice(prefix, oldBlocks.length - suffix);
+    const newMid = newBlocks.slice(prefix, newBlocks.length - suffix);
+    const middle = alignMiddle(oldMid, newMid);
+    for (const run of middle.runs) {
+        runs.push({
+            kept: run.kept,
+            oldFrom: run.oldFrom + prefix,
+            oldTo: run.oldTo + prefix,
+            newFrom: run.newFrom + prefix,
+            newTo: run.newTo + prefix,
+        });
+    }
+    if (suffix > 0) {
+        runs.push({
+            kept: true,
+            oldFrom: oldBlocks.length - suffix,
+            oldTo: oldBlocks.length,
+            newFrom: newBlocks.length - suffix,
+            newTo: newBlocks.length,
+        });
+    }
+    return { runs: mergeAdjacent(runs), quality: middle.quality };
+}
+/** Runs for the region the prefix/suffix trim could not explain. */
+function alignMiddle(oldMid, newMid) {
+    if (oldMid.length === 0 && newMid.length === 0) {
+        return { runs: [], quality: "exact" };
+    }
+    const whole = [
+        {
+            kept: false,
+            oldFrom: 0,
+            oldTo: oldMid.length,
+            newFrom: 0,
+            newTo: newMid.length,
+        },
+    ];
+    // A pure insertion or deletion in the middle: one side is empty, so there is
+    // nothing to match against and the single changed run IS the exact answer.
+    if (oldMid.length === 0 || newMid.length === 0) {
+        return { runs: whole, quality: "exact" };
+    }
+    // Past the budget the same shape means something weaker — "not looked at" —
+    // and the quality field is the only place that difference is recorded.
+    if (oldMid.length * newMid.length > ALIGNMENT_CELL_BUDGET) {
+        return { runs: whole, quality: "budget" };
+    }
+    return {
+        runs: runsFromPairs(longestCommonSubsequence(oldMid, newMid), oldMid.length, newMid.length),
+        quality: "exact",
+    };
+}
+/**
+ * Index pairs of a longest common subsequence of the two key sequences,
+ * ascending. Plain O(n·m) DP over an Int32Array — the budget above is what
+ * keeps that honest, and the keys are interned to integers first so the inner
+ * loop compares numbers instead of strings.
+ */
+function longestCommonSubsequence(oldMid, newMid) {
+    const ids = new Map();
+    const intern = (key) => {
+        const seen = ids.get(key);
+        if (seen !== undefined)
+            return seen;
+        const id = ids.size;
+        ids.set(key, id);
+        return id;
+    };
+    const a = oldMid.map((block) => intern(block.key));
+    const b = newMid.map((block) => intern(block.key));
+    const width = b.length + 1;
+    const table = new Int32Array((a.length + 1) * width);
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i * width + j] =
+                a[i] === b[j]
+                    ? table[(i + 1) * width + j + 1] + 1
+                    : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+        }
+    }
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    return pairs;
+}
+/** Turn matched index pairs into the alternating run list. */
+function runsFromPairs(pairs, oldLength, newLength) {
+    const runs = [];
+    let oldAt = 0;
+    let newAt = 0;
+    for (const [oldIndex, newIndex] of pairs) {
+        if (oldIndex > oldAt || newIndex > newAt) {
+            runs.push({
+                kept: false,
+                oldFrom: oldAt,
+                oldTo: oldIndex,
+                newFrom: newAt,
+                newTo: newIndex,
+            });
+        }
+        runs.push({
+            kept: true,
+            oldFrom: oldIndex,
+            oldTo: oldIndex + 1,
+            newFrom: newIndex,
+            newTo: newIndex + 1,
+        });
+        oldAt = oldIndex + 1;
+        newAt = newIndex + 1;
+    }
+    if (oldAt < oldLength || newAt < newLength) {
+        runs.push({
+            kept: false,
+            oldFrom: oldAt,
+            oldTo: oldLength,
+            newFrom: newAt,
+            newTo: newLength,
+        });
+    }
+    return runs;
+}
+/**
+ * Fuse touching runs of the same kind.
+ *
+ * The LCS emits one run per matched block, and the prefix/suffix trim adds its
+ * own on both sides. Left as-is, two adjacent kept runs would each slice from
+ * their own first block's start, which DROPS the gap bytes between them —
+ * blank lines between untouched paragraphs would vanish on every save. Merging
+ * is not tidying; it is what makes rule 3 true.
+ */
+function mergeAdjacent(runs) {
+    const merged = [];
+    for (const run of runs) {
+        const last = merged[merged.length - 1];
+        if (last && last.kept === run.kept) {
+            last.oldTo = run.oldTo;
+            last.newTo = run.newTo;
+            continue;
+        }
+        merged.push({ ...run });
+    }
+    return merged;
+}

package/dist/format/blocks/dropClosure.d.ts

@@ -0,0 +1,81 @@
+import type { FormatAxisId } from "../formatAxes.js";
+import type { StructuredBlockLanguage } from "./structured-block-schema.js";
+/**
+ * Every reason a structured-block parser drops bytes. Adding a case here
+ * without adding it to {@link BLOCK_DROP_ADJUDICATIONS} does not compile —
+ * that is the "no unadjudicated drop" half of the closure.
+ */
+export type BlockDropReason = "blank-line" | "block-unread" | "entry-bullet-marker" | "status:unsigned-line" | "board:unparsed-line" | "chat:unparsed-line" | "sheet:non-row-line" | "sheet:delimiter-row" | "sheet:excess-cells" | "map:unparsed-line";
+/** A block body that provokes a drop, and the exact bytes it loses. */
+export interface DropWitness {
+    lang: StructuredBlockLanguage;
+    /** The fence body — what the parser is handed. */
+    source: string;
+    /** The dropped text the accounting must report, verbatim. */
+    dropped: string;
+}
+export type DropAdjudication = {
+    kind: "structural-only";
+    witness: DropWitness;
+    rationale: string;
+    /** True when the line still rendered and only part of it was lost. */
+    partial?: true;
+} | {
+    kind: "format-dof-axis";
+    /**
+     * Ids from `../formatAxes`, not free text. Card #288 turned the axis
+     * vocabulary into a closed union precisely so this field cannot name a
+     * spelling nobody defined — before it, `format-dof-axis` was a verdict
+     * that pointed at a string, which is a shrug with a citation on it.
+     * `__tests__/formatAxes.test.ts` closes the reference the other way too:
+     * an axis no ledger entry spends is stale and fails.
+     */
+    axisIds: readonly FormatAxisId[];
+    witness: DropWitness;
+    rationale: string;
+    partial?: true;
+} | {
+    kind: "retained-by-capture";
+    witness: DropWitness;
+    /** Where the bytes went, as a path into the parsed data. */
+    retained: string;
+    rationale: string;
+    partial?: true;
+} | {
+    kind: "documented-residual";
+    witnesses: readonly DropWitness[];
+    rationale: string;
+    partial?: true;
+};
+export declare const BLOCK_DROP_ADJUDICATIONS: Readonly<Record<BlockDropReason, DropAdjudication>>;
+/**
+ * True when the drop takes the whole line with it. A partial drop happened on
+ * a line that rendered anyway — the bullet marker in front of a chat entry,
+ * the cells past the end of a sheet's header — and must NOT be subtracted from
+ * the consumed set.
+ */
+export declare function isWholeLineDrop(reason: BlockDropReason): boolean;
+/**
+ * True when an author should hear about the drop. Only a documented residual
+ * is real loss; the other three verdicts say the bytes were structure, a
+ * spelling, or captured elsewhere, and a diagnostic for those would be noise
+ * on a block that rendered exactly as written.
+ */
+export declare function isReportableDrop(reason: BlockDropReason): boolean;
+/** Every witness in the ledger, flattened, with the reason it belongs to. */
+export declare function dropWitnesses(): Array<{
+    reason: BlockDropReason;
+    witness: DropWitness;
+}>;
+export interface ClosureCheckResult {
+    /** Reasons the parsers produced that the ledger does not adjudicate. */
+    unadjudicated: string[];
+    /** Ledger entries no fixture provokes any more. */
+    stale: string[];
+}
+/**
+ * Close the ledger against what the parsers actually did. `observed` is every
+ * reason seen across the whole fixture corpus — one document's drops are never
+ * enough to close anything.
+ */
+export declare function checkDropClosure(observed: readonly string[]): ClosureCheckResult;