@playola-radio/slipstream 0.1.0

package/dist/clip-projection.js

@@ -0,0 +1,585 @@
+/**
+ * The clip projection: a READER-DERIVED public projection over the immutable
+ * before/after blobs of a `file.changed` event. It is NOT a log event, is never
+ * appended, and successful extraction is a function of (before bytes, after
+ * bytes, language, projection_version) — so identical blobs always yield the identical result and
+ * a dropped cache recomputes the same answer.
+ *
+ * This module has no I/O or threads. Span selection is deterministic and
+ * work-capped for fixed extractor outcomes; timeouts are transient exceptions.
+ * The reader resolves each side to a {@link SideInput} (reading CAS blobs) and
+ * calls {@link projectClips} with the tree-sitter extractor. This module has no
+ * runtime parser dependency; direct pure callers may supply the same extractor.
+ * A successful function-only result is ready; mixed/unreliable hunks fall back.
+ * Transient parser timeouts return prepared ranges and are never cached.
+ *
+ * Byte/line conventions (part of the published contract):
+ *  - Spans reference the RAW blob bytes by ZERO-BASED HALF-OPEN byte offsets.
+ *  - Lines split on `\n` (0x0a); a preceding `\r` stays in the line's bytes
+ *    (CRLF is preserved). A trailing newline terminates the final line — no
+ *    phantom empty last line. `line_start`/`line_end` are 1-based inclusive.
+ *  - A span for line range [a,b] covers `[startOfLine(a), startOfLine(b+1))`,
+ *    where `startOfLine(lastLine+1)` is the blob length; line b's terminator is
+ *    included. `\n` is always a UTF-8 boundary, so spans land on UTF-8
+ *    boundaries.
+ *  - A `null` span means NO corresponding span on that side (created/deleted
+ *    content), NEVER unreadable content. Unreadable/gone content is a non-`ready`
+ *    status (or a per-side `unavailable` method) with an explicit reason.
+ */
+export const CLIP_PROJECTION_VERSION = 'clip.v3';
+/** Fixed extraction budgets. May only be tightened by an explicit option (raising
+ *  a ceiling is a product decision, out of scope). */
+export const MAX_UTF8_BYTES = 1024 * 1024; // parse only UTF-8 <= 1 MiB
+export const MAX_ALIGN_CELLS = 8_000_000; // before x after line-pair product cap
+export const MAX_LINES_PER_SIDE = 300; // across the whole clip array, per side
+export const MAX_BYTES_PER_SIDE = 64 * 1024; // across the whole clip array, per side
+export const DEFAULT_CONTEXT = 20; // fallback = changed ranges +/- 20 lines
+const FALLBACK_REASON = 'function-extraction-unavailable';
+export function projectClips(before, after, opts, extract) {
+    // Options may only TIGHTEN a locked ceiling, never raise it: clamp each to its
+    // constant. Raising a budget is a product decision, out of scope (see D4).
+    const limits = {
+        context: opts.context ?? DEFAULT_CONTEXT,
+        maxLines: Math.min(opts.maxLinesPerSide ?? MAX_LINES_PER_SIDE, MAX_LINES_PER_SIDE),
+        maxBytes: Math.min(opts.maxBytesPerSide ?? MAX_BYTES_PER_SIDE, MAX_BYTES_PER_SIDE),
+        maxCells: Math.min(opts.maxCells ?? MAX_ALIGN_CELLS, MAX_ALIGN_CELLS),
+        maxUtf8Bytes: Math.min(opts.maxBytes ?? MAX_UTF8_BYTES, MAX_UTF8_BYTES),
+    };
+    const a = resolveSide(after, limits.maxUtf8Bytes);
+    const b = resolveSide(before, limits.maxUtf8Bytes);
+    const build = (status, reason, clips) => ({
+        change_seq: opts.changeSeq,
+        projection_version: CLIP_PROJECTION_VERSION,
+        status,
+        fallback_reason: reason,
+        clips,
+    });
+    const skipped = (reason) => build('skipped', reason, []);
+    const unavailable = (reason) => build('unavailable', reason, []);
+    const fallback = (clips) => build('fallback', FALLBACK_REASON, clips);
+    // Materialize plans within budget. If not even one bounded clip fits (e.g. a
+    // single line wider than the byte ceiling), skip rather than invent or exceed.
+    const asFallback = (plans) => {
+        const clips = clipArray(plans, b, a, limits);
+        return clips.length > 0 ? fallback(clips) : skipped('clip-too-large');
+    };
+    // B2 extension point: bounded fallback is assembled BEFORE any parse. Only
+    // this pure core chooses spans; the I/O wrapper supplies the WASM extractor.
+    const enrich = (plans, blocks) => {
+        const prepared = asFallback(plans);
+        if (!extract)
+            return prepared;
+        const language = opts.language ?? 'unsupported';
+        const empty = { functions: [], errors: [] };
+        let bi, ai;
+        try {
+            bi = b.kind === 'text' ? extract(b.lines.join(''), language) : empty;
+            ai = a.kind === 'text' ? extract(a.lines.join(''), language) : empty;
+        }
+        catch {
+            bi = ai = { ...empty, reason: 'worker-error' };
+        }
+        const failure = [bi.reason, ai.reason].find(r => r === 'timeout') ?? bi.reason ?? ai.reason;
+        if (failure) {
+            prepared.fallback_reason = failure;
+            for (const c of prepared.clips)
+                for (const side of [c.before, c.after]) {
+                    if (side.span)
+                        side.reason = failure;
+                }
+            return prepared;
+        }
+        const selected = functionPlans(blocks, b, a, bi, ai, limits.context);
+        if (selected === null) {
+            prepared.fallback_reason = 'extraction-budget-exhausted';
+            for (const c of prepared.clips)
+                for (const side of [c.before, c.after]) {
+                    if (side.span)
+                        side.reason = 'extraction-budget-exhausted';
+                }
+            return prepared;
+        }
+        const clips = clipArray(selected, b, a, limits);
+        // An enclosing function can start with a line too large to render even when
+        // the changed hunk itself already fit. Keep that prepared hunk: `skipped`
+        // means no bounded clip exists at all, not merely that the expanded one did
+        // not fit.
+        if (!clips.length) {
+            if (prepared.clips.length === 0)
+                return skipped('clip-too-large');
+            prepared.fallback_reason = 'function-clip-too-large';
+            for (const c of prepared.clips)
+                for (const side of [c.before, c.after]) {
+                    if (side.span)
+                        side.reason = 'function-clip-too-large';
+                }
+            return prepared;
+        }
+        // B1 marks the last emitted SPAN on each omitted side. A function insertion
+        // may spend the other side's budget before this side has emitted any span;
+        // disclose that omission at projection level without falsifying a null side.
+        for (const side of ['before', 'after']) {
+            if (!clips.some(c => c[side].span) && selected.slice(clips.length).some(c => planHasContent(c[side]))) {
+                return build('fallback', `truncated-${side}`, clips);
+            }
+        }
+        // Inspect ALL plans, including any omitted by the budget: truncation must
+        // not conceal a fallback hunk and turn a mixed result into ready.
+        const reasons = selected.flatMap(c => [c.before.reason, c.after.reason]).filter(Boolean);
+        const hasFunction = selected.some(c => c.before.method === 'function' || c.after.method === 'function');
+        if (hasFunction && reasons.length === 0) {
+            return { change_seq: opts.changeSeq, projection_version: CLIP_PROJECTION_VERSION, status: 'ready', clips };
+        }
+        return build('fallback', reasons[0] ?? 'no-enclosing-function', clips);
+    };
+    // The after side drives the primary disposition: if we cannot show the result
+    // state, nothing else matters.
+    if (a.kind === 'gone')
+        return unavailable(`after-${a.origin}`);
+    if (a.kind === 'skip')
+        return skipped(a.reason);
+    if (a.kind === 'absent') {
+        if (b.kind === 'text') {
+            return enrich([{ before: wholeRange(), after: nullSide('absent') }], [{ before: { s0: 0, e0: b.lines.length }, after: { s0: 0, e0: 0 } }]);
+        }
+        if (b.kind === 'absent')
+            return skipped('no-content');
+        if (b.kind === 'gone')
+            return unavailable(`before-${b.origin}`);
+        return skipped(b.reason); // before oversize/not-utf8 while after deleted
+    }
+    // after is text from here on.
+    if (b.kind === 'text') {
+        if (b.lines.length * a.lines.length > limits.maxCells) {
+            return asFallback([wholeFileClip('diff-too-large')]);
+        }
+        const blocks = diffRawBlocks(b.lines, a.lines);
+        const hunks = mergeRawBlocks(blocks, b.lines.length, a.lines.length, limits.context);
+        if (hunks.length === 0) {
+            if (equalBytes(b.bytes, a.bytes))
+                return skipped('no-change');
+            return asFallback([wholeFileClip('no-line-change')]);
+        }
+        const plans = hunks.map((h) => ({
+            // A raw-empty side (pure insertion/deletion) is null even though context
+            // padding makes the merged range non-empty: the contract requires no
+            // corresponding span there, never a context-only span.
+            before: h.beforeRawEmpty
+                ? { kind: 'null', method: 'changed-range' }
+                : { kind: 'range', range: h.before, method: 'changed-range' },
+            after: h.afterRawEmpty
+                ? { kind: 'null', method: 'changed-range' }
+                : { kind: 'range', range: h.after, method: 'changed-range' },
+        }));
+        return enrich(plans, blocks);
+    }
+    // after text, before not text: cannot diff, show after whole-file.
+    if (b.kind === 'absent') {
+        return enrich([{ before: nullSide('absent'), after: wholeRange() }], [{ before: { s0: 0, e0: 0 }, after: { s0: 0, e0: a.lines.length } }]);
+    }
+    const beforeReason = b.kind === 'gone' ? `before-${b.origin}` : `before-${b.reason}`;
+    const clips = clipArray([{ before: nullSide('unavailable', beforeReason), after: wholeRange() }], b, a, limits);
+    if (clips.length > 0)
+        return fallback(clips);
+    // Nothing of the after side fits the budget. When the before side is genuinely
+    // gone (GC'd/uncaptured), this outcome is availability-dependent — a restored
+    // before blob would diff and likely fit — so surface it as `unavailable` (never
+    // cached) rather than a stale `skipped`. A present-but-unparseable before
+    // (oversize/binary) is deterministic, so it stays a cacheable skip.
+    return b.kind === 'gone' ? unavailable(beforeReason) : skipped('clip-too-large');
+}
+function resolveSide(side, maxUtf8Bytes) {
+    switch (side.kind) {
+        case 'absent':
+            return { kind: 'absent' };
+        case 'oversize':
+            return { kind: 'skip', reason: 'oversize' };
+        case 'missing':
+            return { kind: 'gone', origin: 'missing' };
+        case 'unavailable':
+            return { kind: 'gone', origin: 'unavailable' };
+        case 'bytes': {
+            const bytes = side.bytes;
+            if (bytes.length > maxUtf8Bytes)
+                return { kind: 'skip', reason: 'oversize' };
+            const text = decodeUtf8(bytes);
+            if (text === null)
+                return { kind: 'skip', reason: 'not-utf8' };
+            const starts = indexLineStarts(bytes);
+            const lines = lineContents(text);
+            return { kind: 'text', bytes, starts, len: bytes.length, lines };
+        }
+    }
+}
+/** Decode UTF-8 strictly; a NUL byte (binary marker) or an invalid sequence
+ *  returns null. `ignoreBOM` keeps a leading BOM in the text so a BOM-only change
+ *  is a real diff difference, matching the raw-byte spans. Mirrors the
+ *  binary/not-text detection used elsewhere. */
+function decodeUtf8(bytes) {
+    for (let i = 0; i < bytes.length; i++)
+        if (bytes[i] === 0)
+            return null;
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+/** Byte offset of each line start. A `\n` starts a new line at the next byte
+ *  unless it is the final byte (then it only terminates the last line). Empty
+ *  input is zero lines. */
+function indexLineStarts(bytes) {
+    if (bytes.length === 0)
+        return [];
+    const starts = [0];
+    for (let i = 0; i < bytes.length - 1; i++) {
+        if (bytes[i] === 0x0a)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** Per-line content strings that PRESERVE terminators (a trailing `\r` and the
+ *  `\n`) and final-newline presence, so a line-ending or trailing-newline change
+ *  is a real diff difference rather than a silently hidden one. Used only for
+ *  line comparison; spans are always computed from raw bytes. The result length
+ *  matches {@link indexLineStarts}. */
+function lineContents(text) {
+    if (text === '')
+        return [];
+    const parts = text.split('\n');
+    const trailingNewline = parts[parts.length - 1] === '';
+    if (trailingNewline)
+        parts.pop();
+    return parts.map((p, i) => (i < parts.length - 1 || trailingNewline ? p + '\n' : p));
+}
+function equalBytes(a, b) {
+    return Buffer.from(a.buffer, a.byteOffset, a.byteLength).equals(Buffer.from(b.buffer, b.byteOffset, b.byteLength));
+}
+/** Line-level LCS diff grouped into hunks of changed lines +/- `context`
+ *  unchanged lines. Hunks whose context windows would touch are merged. */
+function diffRawBlocks(before, after) {
+    const n = before.length;
+    const m = after.length;
+    const w = m + 1;
+    const dp = new Int32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i * w + j] = before[i] === after[j]
+                ? dp[(i + 1) * w + (j + 1)] + 1
+                : Math.max(dp[(i + 1) * w + j], dp[i * w + (j + 1)]);
+        }
+    }
+    // Raw change blocks between matched (equal) line pairs.
+    const blocks = [];
+    let i = 0;
+    let j = 0;
+    let pi = 0;
+    let pj = 0;
+    while (i < n && j < m) {
+        if (before[i] === after[j]) {
+            if (i > pi || j > pj)
+                blocks.push({ before: { s0: pi, e0: i }, after: { s0: pj, e0: j } });
+            i++;
+            j++;
+            pi = i;
+            pj = j;
+        }
+        else if (dp[(i + 1) * w + j] >= dp[i * w + (j + 1)]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    if (pi < n || pj < m)
+        blocks.push({ before: { s0: pi, e0: n }, after: { s0: pj, e0: m } });
+    return blocks;
+}
+function mergeRawBlocks(blocks, n, m, context) {
+    // Merge blocks separated by <= 2*context equal lines, then pad with context.
+    // Raw (pre-context) emptiness must survive the merge: a merged run is only
+    // "raw-empty" on a side if EVERY block it absorbed was empty on that side —
+    // one non-empty block anywhere in the run means real content is in play.
+    const merged = [];
+    for (const blk of blocks) {
+        const beforeEmpty = blk.before.s0 === blk.before.e0;
+        const afterEmpty = blk.after.s0 === blk.after.e0;
+        const last = merged[merged.length - 1];
+        if (last && blk.before.s0 - last.beforeRaw.e0 <= 2 * context) {
+            last.beforeRaw.e0 = blk.before.e0;
+            last.afterRaw.e0 = blk.after.e0;
+            last.beforeRawEmpty = last.beforeRawEmpty && beforeEmpty;
+            last.afterRawEmpty = last.afterRawEmpty && afterEmpty;
+        }
+        else {
+            merged.push({
+                before: { ...blk.before }, after: { ...blk.after },
+                beforeRaw: { ...blk.before }, afterRaw: { ...blk.after },
+                beforeRawEmpty: beforeEmpty, afterRawEmpty: afterEmpty,
+            });
+        }
+    }
+    return merged.map((h) => ({
+        before: { s0: Math.max(0, h.beforeRaw.s0 - context), e0: Math.min(n, h.beforeRaw.e0 + context) },
+        after: { s0: Math.max(0, h.afterRaw.s0 - context), e0: Math.min(m, h.afterRaw.e0 + context) },
+        beforeRawEmpty: h.beforeRawEmpty,
+        afterRawEmpty: h.afterRawEmpty,
+    }));
+}
+/** Split raw changes at function boundaries BEFORE adding fallback context.
+ * Pair segments by their order within the same LCS block, never by names or
+ * inferred identity. Repeated edits of one paired function share one clip.
+ */
+function functionPlans(blocks, before, after, bi, ai, context) {
+    let work = 0;
+    let exhausted = false;
+    const withinBudget = (index) => (work += index.functions.length + index.errors.length + 1) <= 400_000;
+    // A line diff gives no character range within its changed line. At a function
+    // boundary, only use the function when it owns that whole line; otherwise a
+    // same-line top-level declaration could be incorrectly reported as function
+    // content. Interior rows are unambiguous.
+    const enclosesRow = (fn, row, side) => {
+        if (fn.s0 > row || row >= fn.e0)
+            return false;
+        const line = side.lines[row];
+        return (fn.s0 !== row || line.slice(0, fn.c0).trim() === '')
+            && (fn.e0 !== row + 1 || line.slice(fn.c1).trim() === '');
+    };
+    const segments = (range, side, index) => {
+        if (side.kind !== 'text' || range.s0 === range.e0)
+            return [];
+        const plans = [];
+        for (let row = range.s0; row < range.e0;) {
+            if (!withinBudget(index))
+                return [];
+            // Smallest enclosing span wins (nested functions are independently useful).
+            const fn = index.functions.filter(f => enclosesRow(f, row, side))
+                .sort((x, y) => (x.e0 - x.s0) - (y.e0 - y.s0) || y.s0 - x.s0)[0];
+            if (fn) {
+                plans.push({ kind: 'range', range: fn, method: 'function' });
+                // Do not jump past an ambiguous final boundary row. It can carry a
+                // contiguous top-level edit after the closing brace and needs its own
+                // changed-range fallback.
+                const finalRow = fn.e0 - 1;
+                row = Math.min(enclosesRow(fn, finalRow, side) ? fn.e0 : finalRow, range.e0);
+            }
+            else {
+                const start = row++;
+                while (row < range.e0 && !index.functions.some(f => enclosesRow(f, row, side))) {
+                    if (!withinBudget(index))
+                        return [];
+                    row++;
+                }
+                // Separating blank lines in a created/deleted block need no standalone
+                // clip. If these are the entire edit, the caller preserves the fallback.
+                if (side.lines.slice(start, row).every(line => line.trim() === ''))
+                    continue;
+                const damaged = index.errors.some(e => e.s0 < row && start < e.e0);
+                plans.push({ kind: 'range', method: 'changed-range',
+                    range: { s0: Math.max(0, start - context), e0: Math.min(side.lines.length, row + context) },
+                    reason: damaged ? 'parse-error-in-enclosing-scope' : 'no-enclosing-function' });
+            }
+        }
+        return plans;
+    };
+    const absent = (side) => side.kind === 'absent'
+        ? nullSide('absent') : { kind: 'null', method: 'changed-range' };
+    const output = [];
+    const seen = new Set();
+    for (const block of blocks) {
+        const bs = segments(block.before, before, bi);
+        const as = segments(block.after, after, ai);
+        if (work > 400_000)
+            return null;
+        // A body insertion/deletion can still have an enclosing function on its
+        // zero-line side. Require an interior anchor and a surviving enclosing
+        // boundary on the other side; a whole newly inserted function stays null.
+        const counterpart = (empty, other, plans, index) => {
+            if (empty.s0 !== empty.e0 || plans.length !== 1)
+                return undefined;
+            const p = plans[0];
+            if (p.kind !== 'range' || p.method !== 'function' || !p.range
+                || (p.range.s0 >= other.s0 && p.range.e0 <= other.e0))
+                return undefined;
+            // This scans the full index, so it belongs to the same deterministic
+            // selection budget as the row scans above.
+            if (!withinBudget(index)) {
+                exhausted = true;
+                return undefined;
+            }
+            const fn = index.functions.filter(f => f.s0 < empty.s0 && empty.s0 < f.e0)
+                .sort((x, y) => (x.e0 - x.s0) - (y.e0 - y.s0))[0];
+            return fn ? { kind: 'range', method: 'function', range: fn } : undefined;
+        };
+        if (!bs.length) {
+            const p = counterpart(block.before, block.after, as, bi);
+            if (p)
+                bs.push(p);
+        }
+        if (!as.length) {
+            const p = counterpart(block.after, block.before, bs, ai);
+            if (p)
+                as.push(p);
+        }
+        if (exhausted)
+            return null;
+        // Whitespace-only edits remain real changes, even outside any function.
+        if (!bs.length && !as.length) {
+            const h = mergeRawBlocks([block], before.kind === 'text' ? before.lines.length : 0, after.kind === 'text' ? after.lines.length : 0, context)[0];
+            const side = (range, empty, resolved) => empty ? absent(resolved)
+                : { kind: 'range', range, method: 'changed-range', reason: 'no-enclosing-function' };
+            output.push({ before: side(h.before, h.beforeRawEmpty, before), after: side(h.after, h.afterRawEmpty, after) });
+        }
+        for (let i = 0; i < Math.max(bs.length, as.length); i++) {
+            const plan = { before: bs[i] ?? absent(before), after: as[i] ?? absent(after) };
+            const key = JSON.stringify(plan);
+            if (!seen.has(key)) {
+                seen.add(key);
+                output.push(plan);
+            }
+        }
+    }
+    return output;
+}
+function nullSide(method, reason) {
+    return reason === undefined ? { kind: 'null', method } : { kind: 'null', method, reason };
+}
+function wholeRange() {
+    return { kind: 'range', range: null, method: 'whole-file' };
+}
+function wholeFileClip(reason) {
+    return {
+        before: { kind: 'range', range: null, method: 'whole-file', reason },
+        after: { kind: 'range', range: null, method: 'whole-file', reason },
+    };
+}
+/** Whether a plan carries actual content on the given side: a `range` plan with
+ *  a non-empty range, or a `whole-file` plan. A `null` plan (absent/unavailable)
+ *  or a zero-length `range` is NOT content — there is nothing there to omit. */
+function planHasContent(plan) {
+    if (plan.kind === 'null')
+        return false;
+    if (plan.method === 'whole-file')
+        return true;
+    return plan.range === null || plan.range.e0 - plan.range.s0 > 0;
+}
+/** Materialize clip plans into clips, enforcing the per-side line/byte caps
+ *  across the whole array. When a side's budget clips a span short, or prevents
+ *  a later hunk from being emitted at all, the last emitted span on that side is
+ *  marked `truncated` so the omission is disclosed rather than silent. Disclosure
+ *  is precise: a side is only marked truncated if some OMITTED plan (the one
+ *  that triggered the break, or a later one never reached) actually carries
+ *  content on that side — dropping past a plan with nothing on a given side must
+ *  not mark that side truncated. */
+function clipArray(plans, before, after, limits) {
+    const beforeBudget = { lines: limits.maxLines, bytes: limits.maxBytes };
+    const afterBudget = { lines: limits.maxLines, bytes: limits.maxBytes };
+    const clips = [];
+    let beforeTrunc = false;
+    let afterTrunc = false;
+    for (let i = 0; i < plans.length; i++) {
+        const plan = plans[i];
+        const b = materialize(plan.before, before, beforeBudget);
+        const a = materialize(plan.after, after, afterBudget);
+        if (b.outcome === 'dropped' || a.outcome === 'dropped') {
+            // Every omitted plan is the current one (whichever side dropped it discards
+            // the whole clip) plus every later plan never reached. Either side may
+            // carry content in the omitted set independent of which side triggered the
+            // break, so scan both sides across the full omitted range.
+            for (const omitted of plans.slice(i)) {
+                if (planHasContent(omitted.before))
+                    beforeTrunc = true;
+                if (planHasContent(omitted.after))
+                    afterTrunc = true;
+            }
+            break;
+        }
+        clips.push({ before: b.side, after: a.side });
+        if (b.outcome === 'partial')
+            beforeTrunc = true;
+        if (a.outcome === 'partial')
+            afterTrunc = true;
+        if (b.outcome === 'partial' || a.outcome === 'partial') {
+            for (const omitted of plans.slice(i + 1)) {
+                if (planHasContent(omitted.before))
+                    beforeTrunc = true;
+                if (planHasContent(omitted.after))
+                    afterTrunc = true;
+            }
+            break;
+        }
+    }
+    if (beforeTrunc)
+        markLastSpanTruncated(clips, 'before');
+    if (afterTrunc)
+        markLastSpanTruncated(clips, 'after');
+    return clips;
+}
+/** Disclose truncation on the last emitted span of a side. The last CLIP may be
+ *  a null-span insertion/deletion on that side, so walk back to the last clip
+ *  that actually has a span there — otherwise a dropped later hunk would go
+ *  silently undisclosed. */
+function markLastSpanTruncated(clips, side) {
+    for (let i = clips.length - 1; i >= 0; i--) {
+        const span = clips[i][side].span;
+        if (span) {
+            span.truncated = true;
+            return;
+        }
+    }
+}
+function materialize(plan, side, budget) {
+    if (plan.kind === 'null')
+        return { side: sideOf(plan.method, null, plan.reason), outcome: 'ok' };
+    if (side.kind !== 'text') {
+        // whole-file plan against a non-text side is a bug in the caller.
+        return { side: { span: null, method: 'unavailable', reason: 'internal-error' }, outcome: 'ok' };
+    }
+    const range = plan.range ?? { s0: 0, e0: side.starts.length };
+    if (range.e0 - range.s0 <= 0) {
+        // A zero-length corresponding range (the empty side of an insertion/deletion):
+        // a null span, not budget exhaustion. Later hunks must still be processed.
+        return { side: sideOf(plan.method, null, plan.reason), outcome: 'empty' };
+    }
+    const clamped = clampToBudget(range, side, budget);
+    if (clamped === null)
+        return { side: sideOf(plan.method, null, plan.reason), outcome: 'dropped' };
+    budget.lines -= clamped.line_end - clamped.line_start + 1;
+    budget.bytes -= clamped.byte_end - clamped.byte_start;
+    return { side: sideOf(plan.method, clamped, plan.reason), outcome: clamped.truncated ? 'partial' : 'ok' };
+}
+function sideOf(method, span, reason) {
+    return reason === undefined ? { span, method } : { span, method, reason };
+}
+/** Trim a line range to the remaining line/byte budget, on whole-line
+ *  granularity. The caller guarantees a non-empty range. Returns null when
+ *  nothing fits — either the line budget is spent, or even a single line exceeds
+ *  the byte budget (the locked 64 KiB clip ceiling is never exceeded, so a
+ *  minified line wider than the ceiling yields no clip rather than an oversized
+ *  one). */
+function clampToBudget(range, side, budget) {
+    const total = range.e0 - range.s0; // > 0, guaranteed by caller
+    if (budget.lines <= 0)
+        return null;
+    let take = Math.min(total, budget.lines);
+    const byteStart = lineStartByte(side, range.s0);
+    let byteEnd = lineStartByte(side, range.s0 + take);
+    while (take > 1 && byteEnd - byteStart > budget.bytes) {
+        take--;
+        byteEnd = lineStartByte(side, range.s0 + take);
+    }
+    if (byteEnd - byteStart > budget.bytes)
+        return null; // even one line exceeds the byte budget
+    const truncated = take < total;
+    return {
+        byte_start: byteStart,
+        byte_end: byteEnd,
+        line_start: range.s0 + 1,
+        line_end: range.s0 + take,
+        truncated,
+    };
+}
+function lineStartByte(side, line0) {
+    return line0 < side.starts.length ? side.starts[line0] : side.len;
+}