@platformos/platformos-mcp-supervisor 0.0.2 → 0.1.0

package/dist/result/blocking.spec.js

@@ -0,0 +1,201 @@
+import { allChecks } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { BLOCKING_CHECKS, blocksWrite } from './blocking.js';
+/**
+ * `must_fix_before_write` is not `errors.length > 0`: check-common severities are
+ * calibrated for a linter in an editor rather than for a write gate, so passing an argument
+ * a partial does not declare is `Severity.ERROR` while platformOS ignores it and the page
+ * renders fine. The gate answers only "will this file be broken if I write it?".
+ */
+const at = (check, severity = 'error') => ({
+    check,
+    severity,
+});
+describe('Unit: blocksWrite', () => {
+    describe('blocks on findings that mean the file will not work', () => {
+        it.each([
+            ['does not parse', 'LiquidHTMLSyntaxError'],
+            ['does not parse, and the converter rejects the changeset', 'YAMLSyntaxError'],
+            ['broken reference', 'MissingPartial'],
+            ['platformOS raises on it', 'UnknownFilter'],
+            ['a known filter, wrong argument count — same raise', 'FilterArity'],
+            ['raises, and the deploy converter rejects the changeset', 'JsonLiteralQuoteStyle'],
+            ['renders an empty page body', 'MissingContentForLayout'],
+            ['a declared contract was violated', 'MissingRenderPartialArguments'],
+            ['the query fails when executed', 'GraphQLCheck'],
+            ['the query fails when executed', 'GraphQLVariablesCheck'],
+            ['runtime error', 'InvalidWriteTarget'],
+        ])('%s: %s', (_why, check) => {
+            expect(blocksWrite([at(check)])).toBe(true);
+        });
+    });
+    describe('does NOT block on findings the file survives', () => {
+        it.each([
+            // The reported bug. platformOS ignores an undeclared argument.
+            ['a dead/unknown argument', 'PartialCallArguments'],
+            ['the same dead argument, again', 'UnrecognizedRenderPartialArguments'],
+            ['a missing key renders the key', 'TranslationKeyExists'],
+            ['a missing key renders the key', 'MatchingTranslations'],
+            ['resolves to nil', 'UnknownProperty'],
+            ['doc hygiene, no runtime effect', 'UniqueDocParamNames'],
+            ['doc hygiene, no runtime effect', 'ValidDocParamTypes'],
+            // Both measured against a live instance: the page renders and returns HTTP 200.
+            ['the asset 404s, the page is fine', 'MissingAsset'],
+            ['visibly wrong, still a working page', 'ReservedVariableName'],
+            ['performance advice', 'ImgWidthAndHeight'],
+            ['performance advice', 'ParserBlockingScript'],
+        ])('%s: %s', (_why, check) => {
+            expect(blocksWrite([at(check)])).toBe(false);
+        });
+    });
+    it('treats an UNRECOGNIZED check code as non-blocking', () => {
+        // Load-bearing: check-common gains checks over time, and a gate that blocked on codes
+        // it had never heard of would silently over-block every time the engine grew.
+        expect(blocksWrite([at('SomeBrandNewCheck')])).toBe(false);
+        expect(blocksWrite([at('community-extension:Whatever')])).toBe(false);
+    });
+    it('blocks when a blocking finding is MIXED IN with non-blocking ones', () => {
+        expect(blocksWrite([
+            at('PartialCallArguments'),
+            at('ImgWidthAndHeight'),
+            at('MissingPartial'), // the one that matters
+            at('UnknownProperty'),
+        ])).toBe(true);
+    });
+    it('does not block when every finding is non-blocking, however many', () => {
+        expect(blocksWrite([
+            at('PartialCallArguments'),
+            at('UnrecognizedRenderPartialArguments'),
+            at('ImgWidthAndHeight'),
+            at('ParserBlockingScript'),
+            at('UnknownProperty'),
+        ])).toBe(false);
+    });
+    it('does not block on an empty list', () => {
+        expect(blocksWrite([])).toBe(false);
+    });
+    it('ignores a blocking code carrying a NON-error severity', () => {
+        // A check reconfigured down to warning in a project's config has been
+        // deliberately de-escalated by its owner; the gate must respect that.
+        expect(blocksWrite([at('MissingPartial', 'warning')])).toBe(false);
+        expect(blocksWrite([at('MissingPartial', 'info')])).toBe(false);
+        expect(blocksWrite([at('MissingPartial', 'error')])).toBe(true);
+    });
+    it('exposes the set so the membership decision is inspectable, not implicit', () => {
+        // Pinned exactly: adding or removing an entry is a contract change to the write
+        // gate and must be a deliberate edit here, not a side effect elsewhere.
+        expect([...BLOCKING_CHECKS].sort()).toEqual([
+            'FilterArity',
+            'GraphQLCheck',
+            'GraphQLVariablesCheck',
+            'InvalidWriteTarget',
+            'JsonLiteralQuoteStyle',
+            'LiquidHTMLSyntaxError',
+            'MissingContentForLayout',
+            'MissingPartial',
+            'MissingRenderPartialArguments',
+            'UnknownFilter',
+            'YAMLSyntaxError',
+        ]);
+    });
+    it('does not block the two codes NO accepted buffer can ever produce', () => {
+        // Removed on reachability, not on severity — both are `SourceCodeType.JSON` checks, and
+        // this server never routes a JSON-typed file to anything. Pinned rather than merely
+        // deleted because they READ as obviously belonging; the "every blocking check can
+        // actually block" group in `transport/validate-code.spec.ts` holds the behavioural proof.
+        expect([BLOCKING_CHECKS.has('ValidJSON'), BLOCKING_CHECKS.has('JSONSyntaxError')]).toEqual([
+            false,
+            false,
+        ]);
+    });
+    /**
+     * Three entries were measured against a live instance and found wrong. These pin the
+     * corrections individually, so a future edit that "restores" one has to argue with the
+     * evidence rather than silently reverting it.
+     *
+     * `MissingAsset`: `{{ 'no_such.css' | asset_url }}` renders, page HTTP 200, deploy
+     * accepted. `ReservedVariableName`: `{% assign blank = 'oops' %}` renders `[]`, HTTP 200.
+     * `JsonLiteralQuoteStyle`: `{% assign o = {'k': 'v'} %}` raises `Invalid JSON in assign`
+     * AND is rejected by `--dry-run`, failing the whole changeset.
+     */
+    it('does not block the two findings measured to render a working page', () => {
+        expect(BLOCKING_CHECKS.has('MissingAsset')).toBe(false);
+        expect(BLOCKING_CHECKS.has('ReservedVariableName')).toBe(false);
+        expect(blocksWrite([at('MissingAsset'), at('ReservedVariableName')])).toBe(false);
+    });
+    it('blocks the JSON literal quote style, which is fatal at runtime AND on deploy', () => {
+        expect(BLOCKING_CHECKS.has('JsonLiteralQuoteStyle')).toBe(true);
+        expect(blocksWrite([at('JsonLiteralQuoteStyle')])).toBe(true);
+    });
+    /**
+     * `InvalidWriteTarget` stays on its OWN evidence rather than a neighbour's shared
+     * "runtime errors" justification, which measurement disproved for `ReservedVariableName`:
+     * `hash_assign` against a number, string, boolean or range each raises
+     * `HashAssignTagError`, while the object form it permits renders HTTP 200.
+     *
+     * Its old over-report on filter-produced arrays was a precision bug in the check rather
+     * than grounds to de-block — de-blocking would have approved the cases that genuinely
+     * raise.
+     */
+    it('blocks the hash_assign target error, on its own measured evidence', () => {
+        expect(BLOCKING_CHECKS.has('InvalidWriteTarget')).toBe(true);
+        expect(blocksWrite([at('InvalidWriteTarget')])).toBe(true);
+    });
+    it('still reports a de-escalated finding as non-blocking, including the new member', () => {
+        // The gate reads severity as well as code, so a project that downgrades
+        // `JsonLiteralQuoteStyle` in its config is respected exactly like any other member.
+        expect(blocksWrite([at('JsonLiteralQuoteStyle', 'warning')])).toBe(false);
+    });
+    it('does NOT contain the dead-argument checks — the bug this fixes', () => {
+        expect(BLOCKING_CHECKS.has('PartialCallArguments')).toBe(false);
+        expect(BLOCKING_CHECKS.has('UnrecognizedRenderPartialArguments')).toBe(false);
+    });
+    /**
+     * `PartialCallArguments` reports two different things under ONE code: a dead argument
+     * (harmless) and a missing required one (real). There is no structured discriminator on
+     * the offense and non-goal #2 forbids regex over messages, so it is non-blocking
+     * wholesale.
+     *
+     * Safe only because the blocking half is covered independently — a partial WITH a
+     * `{% doc %}` block is owned by `MissingRenderPartialArguments`. What stays unblocked is
+     * a DOC-LESS partial whose required params are INFERRED from usage.
+     */
+    it('still blocks a missing required arg via the doc-based check', () => {
+        expect(blocksWrite([at('MissingRenderPartialArguments'), at('PartialCallArguments')])).toBe(true);
+    });
+    it('does not block a doc-less inferred requirement (documented trade-off)', () => {
+        // Only PartialCallArguments fires for a doc-less partial. An inferred requirement is a
+        // heuristic, and the failure mode is a nil value rather than a crash.
+        expect(blocksWrite([at('PartialCallArguments')])).toBe(false);
+    });
+});
+/**
+ * The gate is POLICY, and policy about check codes goes stale silently.
+ *
+ * Every entry is a hand-written string, and check-common owns the codes. A check renamed
+ * or removed upstream leaves a dead entry here that simply stops matching — the gate
+ * quietly stops blocking a thing it was written to block, no test fails, and the symptom
+ * is an agent being told to write a broken file. That is the one failure mode this set
+ * can have that nothing else would catch.
+ */
+describe('Unit: BLOCKING_CHECKS is tied to the check registry', () => {
+    const registered = new Set(allChecks.map((check) => check.meta.code));
+    it('names only checks that exist in check-common', () => {
+        expect([...BLOCKING_CHECKS].filter((code) => !registered.has(code)).sort()).toEqual([]);
+    });
+    /**
+     * The CONVERSE is deliberately not asserted, and this test exists to say so rather than
+     * leave the absence looking like an oversight.
+     *
+     * Blocking is not severity: `blocksWrite` requires an `error` AND membership here, so a
+     * new check is non-blocking until someone argues it into the set. Requiring every check
+     * to be classified would invert that default.
+     */
+    it('does not require every registered check to be classified: silence is the default', () => {
+        const unclassified = [...registered].filter((code) => !BLOCKING_CHECKS.has(code));
+        // Most checks are not blocking, and that is the intended state, not a gap.
+        expect(unclassified.length > 0).toBe(true);
+        expect(blocksWrite([at(unclassified[0])])).toBe(false);
+    });
+});
+//# sourceMappingURL=blocking.spec.js.map

package/dist/result/impact-states.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The non-`computed` blast-radius states.
+ *
+ * Each is a FACTORY, not a shared constant: the zeroed `dependents` object is mutable and
+ * ends up inside a returned result, so one shared instance would let a mutation reach every
+ * past and future response.
+ *
+ * IMPORTANT: `dependents` is meaningful ONLY when `status` is `computed`. Every state here
+ * zeroes it, and a zero must NEVER be read as "nothing depends on this, safe to change" —
+ * that is what `status` is for.
+ */
+import type { ValidateCodeImpact } from './types.js';
+/** The blast radius could not be computed at all — a failure, or a deadline. */
+export declare const UNAVAILABLE_IMPACT: () => ValidateCodeImpact;
+/** This file has no dependency edges to speak of — see `ValidateCodeImpactStatus`. */
+export declare const NOT_APPLICABLE_IMPACT: () => ValidateCodeImpact;

package/dist/result/impact-states.js

@@ -0,0 +1,18 @@
+const noDependents = () => ({
+    total: 0,
+    by_kind: {},
+    sample: [],
+});
+/** The blast radius could not be computed at all — a failure, or a deadline. */
+export const UNAVAILABLE_IMPACT = () => ({
+    scope: 'direct',
+    status: 'unavailable',
+    dependents: noDependents(),
+});
+/** This file has no dependency edges to speak of — see `ValidateCodeImpactStatus`. */
+export const NOT_APPLICABLE_IMPACT = () => ({
+    scope: 'direct',
+    status: 'not_applicable',
+    dependents: noDependents(),
+});
+//# sourceMappingURL=impact-states.js.map

package/dist/result/response-budget.d.ts

@@ -0,0 +1,9 @@
+import type { ValidateCodeResult } from './types.js';
+/**
+ * Apply the response bound to a whole request's results.
+ *
+ * Pure: returns new results, in the same iteration order, leaving the inputs alone. A result
+ * with nothing withheld is returned unchanged and carries no `truncated` field, so the
+ * field's presence is a reliable signal.
+ */
+export declare function capToBudget(results: ReadonlyMap<string, ValidateCodeResult>, budgetBytes?: number): Map<string, ValidateCodeResult>;

package/dist/result/response-budget.js

@@ -0,0 +1,131 @@
+/**
+ * Bound the diagnostics one response carries, and say so when anything is withheld.
+ *
+ * IT RUNS AFTER ASSEMBLY, and that ordering is the design: this module never computes the
+ * gate, never re-derives `status`, and never sees an unassembled diagnostic. It takes
+ * finished results — whose verdict was computed from the COMPLETE set — and removes entries
+ * from the tails of their lists, so no ordering of operations here can soften the gate.
+ * `response-budget.spec.ts` asserts that with a buffer whose only blocking error sorts last.
+ *
+ * WHAT IS SPENT FIRST. The budget belongs to the whole request, so a batch cannot multiply
+ * it, and it is allocated in two orders at once:
+ *
+ *   BY SEVERITY   every file's errors before any file's warnings, warnings before infos.
+ *   BY FILE       round-robin within each severity, in the order the caller listed them, so
+ *                 one file with thousands of findings cannot starve the others.
+ *
+ * Within a file and bucket, entries are taken from the FRONT, so what survives is the head
+ * of a list already ordered by line and column — where the root cause of a cascade is.
+ *
+ * A STREAM THAT CANNOT FIT IS CLOSED, not skipped: once a bucket's next entry does not fit
+ * it takes nothing further, so the returned list stays a contiguous head rather than a
+ * scattered sample.
+ *
+ * ONE ERROR PER FILE IS GUARANTEED, budget or not — a blocked write with an empty `errors`
+ * list names a problem and then declines to say what it is. Bounded: one entry per file,
+ * and the batch form already caps files.
+ */
+import { MAX_RESPONSE_DIAGNOSTIC_BYTES } from '../cost-model.js';
+/** The buckets, in the order the budget is spent on them. */
+const BUCKETS = ['errors', 'warnings', 'infos'];
+/**
+ * What one diagnostic costs in the serialized response.
+ *
+ * Measured on the thing that is actually sent — the JSON — rather than estimated from a
+ * field count, because `hint`, `suggestion` and `fix` make entries vary by an order of
+ * magnitude. The `+ 1` is the separating comma.
+ */
+function costOf(diagnostic) {
+    return Buffer.byteLength(JSON.stringify(diagnostic), 'utf8') + 1;
+}
+function truncationFor(result, taken) {
+    const withheld = {};
+    let total = 0;
+    let returned = 0;
+    for (const bucket of BUCKETS) {
+        const found = result[bucket].length;
+        total += found;
+        returned += taken[bucket];
+        if (taken[bucket] < found) {
+            withheld[bucket] = { returned: taken[bucket], total: found };
+        }
+    }
+    if (Object.keys(withheld).length === 0)
+        return undefined;
+    return {
+        ...withheld,
+        // Written for an agent that reads only this object, and kept SHORT: it repeats per
+        // file. Two claims earn their bytes — the list is partial, and the verdict is not.
+        note: `Showing ${returned} of ${total} findings, from the top of the file; the rest were withheld to bound ` +
+            `this response. "status" and "must_fix_before_write" reflect all ${total}. Fix these and validate again.`,
+    };
+}
+/**
+ * Apply the response bound to a whole request's results.
+ *
+ * Pure: returns new results, in the same iteration order, leaving the inputs alone. A result
+ * with nothing withheld is returned unchanged and carries no `truncated` field, so the
+ * field's presence is a reliable signal.
+ */
+export function capToBudget(results, budgetBytes = MAX_RESPONSE_DIAGNOSTIC_BYTES) {
+    const streams = [];
+    for (const [key, result] of results) {
+        for (const bucket of BUCKETS) {
+            streams.push({ key, bucket, entries: result[bucket], taken: 0, open: true });
+        }
+    }
+    let spent = 0;
+    // The guarantee, taken first and charged honestly: it can push `spent` past the
+    // budget before the loop below starts, in which case that loop admits nothing more.
+    for (const stream of streams) {
+        if (stream.bucket !== 'errors' || stream.entries.length === 0)
+            continue;
+        spent += costOf(stream.entries[0]);
+        stream.taken = 1;
+    }
+    for (const bucket of BUCKETS) {
+        const inBucket = streams.filter((stream) => stream.bucket === bucket);
+        // Round-robin: one entry from each file in turn, until every stream in this
+        // bucket is exhausted or closed by the budget.
+        let progressed = true;
+        while (progressed) {
+            progressed = false;
+            for (const stream of inBucket) {
+                if (!stream.open || stream.taken >= stream.entries.length)
+                    continue;
+                const cost = costOf(stream.entries[stream.taken]);
+                if (spent + cost > budgetBytes) {
+                    stream.open = false;
+                    continue;
+                }
+                spent += cost;
+                stream.taken += 1;
+                progressed = true;
+            }
+        }
+    }
+    const takenByKey = new Map();
+    for (const stream of streams) {
+        const counts = takenByKey.get(stream.key) ?? { errors: 0, warnings: 0, infos: 0 };
+        counts[stream.bucket] = stream.taken;
+        takenByKey.set(stream.key, counts);
+    }
+    const capped = new Map();
+    for (const [key, result] of results) {
+        const taken = takenByKey.get(key);
+        const truncated = truncationFor(result, taken);
+        if (!truncated) {
+            capped.set(key, result);
+            continue;
+        }
+        capped.set(key, {
+            ...result,
+            errors: result.errors.slice(0, taken.errors),
+            warnings: result.warnings.slice(0, taken.warnings),
+            infos: result.infos.slice(0, taken.infos),
+            truncated,
+        });
+    }
+    return capped;
+}
+//# sourceMappingURL=response-budget.js.map

package/dist/result/response-budget.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/result/response-budget.spec.js

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+import { capToBudget } from './response-budget.js';
+import { MAX_RESPONSE_DIAGNOSTIC_BYTES } from '../cost-model.js';
+import { UNAVAILABLE_IMPACT } from './impact-states.js';
+/**
+ * The response bound, tested where it is decidable: as a pure function over finished
+ * results.
+ *
+ * ONE ASSERTION MATTERS MORE THAN THE REST — the one about the gate. A cap that drops the
+ * diagnostic holding `must_fix_before_write` true, while leaving the flag false,
+ * manufactures a false approval on exactly the inputs nobody inspects. The architecture is
+ * meant to make that impossible, and the case below is what turns that claim into a
+ * measurement.
+ */
+const diagnostic = (line, severity, check = 'SomeCheck', padding = '') => ({
+    check,
+    severity,
+    message: `finding at ${line}${padding}`,
+    line,
+    column: 1,
+});
+const resultWith = (errors, warnings = [], infos = [], blocked = errors.length > 0) => ({
+    status: errors.length > 0 ? 'error' : warnings.length > 0 ? 'warning' : 'ok',
+    must_fix_before_write: blocked,
+    errors,
+    warnings,
+    infos,
+    impact: UNAVAILABLE_IMPACT(),
+});
+const many = (count, severity = 'error') => Array.from({ length: count }, (_, index) => diagnostic(index + 1, severity));
+/** Serialized size of the diagnostics a capped result actually carries. */
+const diagnosticBytes = (results) => {
+    let bytes = 0;
+    for (const result of results.values()) {
+        for (const bucket of [result.errors, result.warnings, result.infos]) {
+            for (const entry of bucket)
+                bytes += Buffer.byteLength(JSON.stringify(entry), 'utf8') + 1;
+        }
+    }
+    return bytes;
+};
+describe('Unit: capToBudget', () => {
+    it('leaves a result that fits completely untouched, with NO truncation field', async () => {
+        // The presence of `truncated` has to be a reliable signal. A stub emitted on
+        // every response would make an agent inspect it to learn nothing, which is the
+        // same reasoning that removed the permanently-empty fields from this contract.
+        const results = new Map([['a.liquid', resultWith(many(3))]]);
+        const capped = capToBudget(results);
+        expect(capped.get('a.liquid')).toEqual(results.get('a.liquid'));
+        expect(capped.get('a.liquid').truncated).toBeUndefined();
+    });
+    it('NEVER softens the gate: the blocking error may be withheld, the verdict may not', async () => {
+        // The case the whole design exists for. One thousand findings where the ONLY
+        // blocking one sorts last, so any cap that recomputed the verdict from what it
+        // returned would flip `must_fix_before_write` to false and tell the agent to
+        // write a file the server knows is broken.
+        const errors = [...many(999), diagnostic(1000, 'error', 'MissingPartial')];
+        const results = new Map([['a.liquid', resultWith(errors, [], [], true)]]);
+        const capped = capToBudget(results, 500);
+        const result = capped.get('a.liquid');
+        expect({
+            blocked: result.must_fix_before_write,
+            status: result.status,
+            returnedFewer: result.errors.length < errors.length,
+            blockingOneWithheld: !result.errors.some((error) => error.check === 'MissingPartial'),
+            total: result.truncated.errors.total,
+        }).toEqual({
+            blocked: true,
+            status: 'error',
+            returnedFewer: true,
+            blockingOneWithheld: true,
+            total: 1000,
+        });
+    });
+    it('reports the true total per affected bucket, distinguishable from what it returned', async () => {
+        const results = new Map([
+            ['a.liquid', resultWith(many(50), many(40, 'warning'), many(30, 'info'))],
+        ]);
+        const capped = capToBudget(results, 900);
+        const result = capped.get('a.liquid');
+        expect({
+            errors: result.truncated.errors,
+            returnedErrors: result.errors.length,
+            warnings: result.truncated.warnings,
+            infos: result.truncated.infos,
+        }).toEqual({
+            errors: { returned: result.errors.length, total: 50 },
+            returnedErrors: result.errors.length,
+            warnings: { returned: 0, total: 40 },
+            infos: { returned: 0, total: 30 },
+        });
+    });
+    it('names only the buckets it actually withheld from', async () => {
+        // A bucket that came back whole must not appear. Otherwise "which of my lists is
+        // partial" becomes a question an agent answers by comparing numbers.
+        const results = new Map([['a.liquid', resultWith(many(2), many(400, 'warning'))]]);
+        const capped = capToBudget(results, 800);
+        const truncated = capped.get('a.liquid').truncated;
+        expect({
+            errors: truncated.errors,
+            warnings: truncated.warnings !== undefined,
+            infos: truncated.infos,
+        }).toEqual({ errors: undefined, warnings: true, infos: undefined });
+    });
+    it('spends the budget on errors before any info, across every file', async () => {
+        // Severity-major allocation. A file that is nothing but infos must not consume
+        // the budget a LATER file's errors need — note the noisy file is listed first, so
+        // a purely round-robin allocation would serve it before seeing the errors at all.
+        //
+        // Asserted as the RELATIONSHIP rather than a count: "17 of 20 errors fit in 1500 bytes"
+        // is arithmetic about this fixture's message lengths. The property is that while any
+        // error is still being withheld, no info has been served.
+        const results = new Map([
+            ['noisy.liquid', resultWith([], [], many(500, 'info'))],
+            ['broken.liquid', resultWith(many(20))],
+        ]);
+        const capped = capToBudget(results, 1_500);
+        expect({
+            errorsWithheld: capped.get('broken.liquid').truncated?.errors !== undefined,
+            infosReturned: capped.get('noisy.liquid').infos.length,
+        }).toEqual({ errorsWithheld: true, infosReturned: 0 });
+    });
+    it('still serves infos once every error fits, so lower severities are not starved needlessly', async () => {
+        // The other half of the same rule. Errors first must not mean infos never.
+        const results = new Map([
+            ['noisy.liquid', resultWith([], [], many(500, 'info'))],
+            ['broken.liquid', resultWith(many(20))],
+        ]);
+        const capped = capToBudget(results, 20_000);
+        expect({
+            errorsWhole: capped.get('broken.liquid').truncated,
+            someInfos: capped.get('noisy.liquid').infos.length > 0,
+            infosPartial: capped.get('noisy.liquid').truncated?.infos?.total,
+        }).toEqual({ errorsWhole: undefined, someInfos: true, infosPartial: 500 });
+    });
+    it('shares the budget round-robin, so one loud file cannot starve the others', async () => {
+        // The realistic batch shape: one file with a cascading failure and three ordinary
+        // ones. Every file must come back with something to act on.
+        const results = new Map([
+            ['cascade.liquid', resultWith(many(2000))],
+            ['b.liquid', resultWith(many(3))],
+            ['c.liquid', resultWith(many(3))],
+            ['d.liquid', resultWith(many(3))],
+        ]);
+        const capped = capToBudget(results, 2_000);
+        expect([
+            capped.get('b.liquid').errors.length,
+            capped.get('c.liquid').errors.length,
+            capped.get('d.liquid').errors.length,
+        ]).toEqual([3, 3, 3]);
+    });
+    it('keeps the HEAD of each list, so what survives is the top of the file', async () => {
+        // Diagnostics arrive ordered by line and column, and a cascade's root cause is
+        // almost always the first entry. Returning a scattered sample would also make
+        // "returned 12 of 300" meaningless about WHICH twelve.
+        const results = new Map([['a.liquid', resultWith(many(100))]]);
+        const capped = capToBudget(results, 400);
+        const lines = capped.get('a.liquid').errors.map((error) => error.line);
+        expect(lines).toEqual(Array.from({ length: lines.length }, (_, index) => index + 1));
+    });
+    it('closes a bucket at the first entry that does not fit, rather than skipping it', async () => {
+        // Contiguity again, from the other direction: a huge entry in the middle must
+        // stop the list there instead of being stepped over to collect smaller ones.
+        const errors = [
+            diagnostic(1, 'error'),
+            diagnostic(2, 'error', 'SomeCheck', 'x'.repeat(5_000)),
+            diagnostic(3, 'error'),
+        ];
+        const results = new Map([['a.liquid', resultWith(errors)]]);
+        const capped = capToBudget(results, 1_000);
+        expect(capped.get('a.liquid').errors.map((error) => error.line)).toEqual([1]);
+    });
+    it('always returns one error per file, even when a single entry exceeds the whole budget', async () => {
+        // A blocked write with an empty `errors` list names a problem and then refuses to
+        // say what it is. The guarantee is bounded to one entry per file.
+        const enormous = [
+            diagnostic(1, 'error', 'MissingPartial', 'x'.repeat(50_000)),
+            diagnostic(2, 'error'),
+        ];
+        const results = new Map([['a.liquid', resultWith(enormous, [], [], true)]]);
+        const capped = capToBudget(results, 100);
+        const result = capped.get('a.liquid');
+        expect({
+            returned: result.errors.length,
+            firstCheck: result.errors[0].check,
+            blocked: result.must_fix_before_write,
+            total: result.truncated.errors.total,
+        }).toEqual({ returned: 1, firstCheck: 'MissingPartial', blocked: true, total: 2 });
+    });
+    it('bounds the REQUEST, not each file, so a 50-file batch cannot multiply the cap', async () => {
+        // The bound that per-file capping alone would miss, and the reason the batch form
+        // needed its own answer: 50 files under a per-file cap is 50x the intended size.
+        const results = new Map(Array.from({ length: 50 }, (_, index) => [`f${index}.liquid`, resultWith(many(500))]));
+        const capped = capToBudget(results);
+        // The guarantee costs one error per file on top of the budget; that overshoot is
+        // bounded by the file cap and is asserted rather than hidden.
+        expect(diagnosticBytes(capped)).toBeLessThan(MAX_RESPONSE_DIAGNOSTIC_BYTES * 1.5);
+    });
+    it('leaves a not_applicable result exactly as it was', async () => {
+        // Nothing to withhold, and nothing that should acquire a truncation field.
+        const declined = {
+            status: 'not_applicable',
+            not_applicable_reason: 'too_large',
+            must_fix_before_write: false,
+            errors: [],
+            warnings: [],
+            infos: [],
+            impact: UNAVAILABLE_IMPACT(),
+            next_step: 'refused',
+        };
+        expect(capToBudget(new Map([['a.liquid', declined]])).get('a.liquid')).toEqual(declined);
+    });
+    it('preserves the caller order of the map, so a batch still lines up with its request', async () => {
+        const results = new Map([
+            ['z.liquid', resultWith(many(2))],
+            ['a.liquid', resultWith(many(2))],
+            ['m.liquid', resultWith(many(2))],
+        ]);
+        expect([...capToBudget(results).keys()]).toEqual(['z.liquid', 'a.liquid', 'm.liquid']);
+    });
+});
+//# sourceMappingURL=response-budget.spec.js.map