@platformos/platformos-mcp-supervisor 0.0.2 → 0.1.0

package/dist/adapter-input.spec.js

@@ -0,0 +1,275 @@
+import { APP_SOURCE_SUBTREES } from '@platformos/platformos-common';
+import { join, parse } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { bufferTooLarge, fileApplicability, MAX_BUFFER_BYTES, misplacedSource, notPlatformOSFile, toAbsoluteFilePath, } from './adapter-input.js';
+/**
+ * Without this gate `validate_code` lints ANY path, and because check-common's
+ * `toSourceCode` types an unrecognized extension as JSON, `/etc/passwd` came back as
+ * `ValidJSON` with `must_fix_before_write: true` while `/etc/shadow` containing `{}` came
+ * back `ok` — a false approval for a path outside the project.
+ *
+ * These pin the pure decision; the end-to-end consequence is pinned in
+ * `transport/validate-code.spec.ts`.
+ */
+const PROJECT = join('/srv', 'app');
+const applicable = (filePath) => fileApplicability(PROJECT, filePath);
+/**
+ * The two refusal messages, duplicated from the implementation on purpose: the prose is the
+ * entire payload of a declined call. Both must state that nothing was checked — an agent
+ * must never read a refusal as a pass.
+ */
+const outside = (filePath) => ({
+    applicable: false,
+    code: 'outside_project',
+    reason: `\`${filePath}\` resolves outside the project root (${PROJECT}), so there is no project ` +
+        `context to validate it against. This server validates only files inside the project it was ` +
+        `started for. Nothing was checked — treat this as "unknown", not as approval.`,
+});
+const unsupported = (relativePath) => ({
+    applicable: false,
+    code: 'unsupported_type',
+    reason: `\`${relativePath}\` is not a platformOS source file, so there is nothing to check. The ` +
+        `platform deploys app/, marketplace_builder/, modules/*/public/, modules/*/private/ only. ` +
+        `Nothing was checked — writing this file is your call, not a validated pass. Directory ` +
+        `structure: https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure`,
+});
+/**
+ * An ASSET is refused for a different reason and says so. It IS part of the app and IS
+ * deployed — there is simply no source in it to check — so the "not a platformOS source
+ * file, the platform deploys app/ only" message above would be false about it.
+ */
+const asset = (relativePath) => ({
+    applicable: false,
+    code: 'unsupported_type',
+    reason: `\`${relativePath}\` is an asset, not a source file the linter understands — it checks ` +
+        `Liquid, GraphQL and YAML — so no check ran against it. The file is still deployed and ` +
+        `served; there is simply nothing here to validate. Nothing was checked, which is not the ` +
+        `same as a pass.`,
+});
+describe('Unit: fileApplicability', () => {
+    describe('accepts every file type the linter would actually visit', () => {
+        it.each([
+            'app/views/pages/index.liquid',
+            'app/views/partials/card.liquid',
+            'app/views/layouts/application.liquid',
+            'app/lib/helper.liquid',
+            // A page that emits JSON is Liquid — classified by the `.liquid` extension, NOT by
+            // the `.json` in its name, which a naive extension check would misroute.
+            'app/views/pages/feed.json.liquid',
+            'app/graphql/things/search.graphql',
+            'app/translations/en.yml',
+            'app/schema/thing.yml',
+            'modules/mcp/public/views/partials/tool.liquid',
+        ])('%s', (filePath) => {
+            expect(applicable(filePath)).toEqual({ applicable: true });
+        });
+        it('accepts an absolute path inside the project', () => {
+            expect(applicable(join(PROJECT, 'app/views/pages/index.liquid'))).toEqual({
+                applicable: true,
+            });
+        });
+        it('accepts a path whose `..` segments normalize back inside the project', () => {
+            expect(applicable('app/views/pages/../partials/card.liquid')).toEqual({ applicable: true });
+        });
+    });
+    describe('declines paths outside the project root', () => {
+        // `''` is refused by the zod schema instead — see validate-code.spec.ts.
+        it.each([
+            ['an absolute system path', '/etc/passwd'],
+            ['a relative traversal', '../../../etc/passwd'],
+            ['a traversal onto a plausible-looking file', '../other/app/views/pages/x.liquid'],
+            ['an absolute path outside the root', '/tmp/scratch/app/views/pages/x.liquid'],
+            // A `startsWith` containment test would ACCEPT this, since
+            // '/srv/app-backup'.startsWith('/srv/app'); only a path-segment comparison rejects it.
+            ['a sibling root extending the project name', '/srv/app-backup/app/views/pages/x.liquid'],
+        ])('%s', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(outside(filePath));
+        });
+        it.each([
+            ['the project root itself', PROJECT],
+            ['the project root via a round trip', 'app/..'],
+        ])('%s is a directory, not a file under edit', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(outside(filePath));
+        });
+    });
+    describe('declines in-project files that are not platformOS sources', () => {
+        it.each([
+            ['markdown', 'README.md'],
+            ['plain text', 'app/notes.txt'],
+            // The extension whose fallback used to swallow everything else.
+            ['standalone json', 'app/pos-modules.json'],
+            ['ruby', 'script/deploy.rb'],
+            ['no extension at all', 'Makefile'],
+        ])('%s', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(unsupported(filePath));
+        });
+        /**
+         * REFUSED BY TYPE, not by extension, and this branch fixes a measured FALSE BLOCK: a
+         * bare `.liquid` has no response format, so `sourceCodeTypeOf` falls back to
+         * `html.liquid` and handed `app/assets/x.liquid` to the Liquid parser. Backwards
+         * besides, since `theme.css.liquid` — the asset form the platform DOES process — was
+         * exempt all along.
+         *
+         * The rule is `platformos-common`'s `isParsedFileType`, and this gate ASKS it rather
+         * than comparing to `PlatformOSFileType.Asset` itself, so it cannot drift from the
+         * lint's answer.
+         */
+        it.each([
+            ['an image', 'app/assets/logo.png'],
+            ['a stylesheet', 'app/assets/site.css'],
+            ['a css asset partial', 'app/assets/site.css.liquid'],
+            ['a js asset partial', 'app/assets/app.js.liquid'],
+            ['an asset manifest', 'app/assets/manifest.json'],
+            // THE CASE THAT WAS BLOCKING WRITES. A parser accepts it; the platform does not
+            // evaluate it. Sabotage check: revert the `Asset` branch in `fileApplicability` and
+            // only this row fails, because it is the only one a parser claims.
+            ['a bare liquid file the parser would accept', 'app/assets/x.liquid'],
+            ['a nested bare liquid file', 'app/assets/nested/deep/w.liquid'],
+            // Legacy spelling of the same directory, so the rule cannot be half-applied.
+            ['a marketplace_builder asset', 'marketplace_builder/assets/x.liquid'],
+        ])('refuses %s as an asset, never as a source', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(asset(filePath));
+        });
+        /**
+         * THE LINE THIS GATE DRAWS. It asks ONE question — "is this a type we parse at all?" —
+         * from the extension and nothing else, and deliberately not whether the path is
+         * somewhere the platform deploys, which `isSupportedSourceFile(uri, root)` would answer.
+         *
+         * Using that here would collapse two situations into one wrong answer.
+         * `scripts/helper.liquid` IS a platformOS source in the wrong place, and its author
+         * needs to hear "nothing will ever load this", not "this is not a platformOS file".
+         * check-node draws that distinction where classification happens, so the gate admits
+         * anything parseable and lets the lint say which it is.
+         *
+         * So being ADMITTED here means "worth asking about", not "will be linted".
+         */
+        it.each([
+            // Liquid outside every deployed subtree: admitted here, then reported as
+            // `misplaced_source` by the lint, which is the answer that helps.
+            ['unclassified liquid', 'scripts/helper.liquid'],
+            // A REAL platformOS source under master's classification: `PlatformOSFileType` has
+            // `InstanceConfig` (`app/config.yml`) and `UserSchema` (`app/user.yml`) as fixed-path
+            // singletons, and the file-type-coverage group pins that something examines them.
+            ['the app config singleton', 'app/config.yml'],
+            ['the user schema singleton', 'app/user.yml'],
+            // KNOWN WRONG ADVICE, admitted here on purpose rather than special-cased. A `.yml` at
+            // the project root is parseable, so the lint calls it `misplaced-source` — telling the
+            // author of this toolchain's OWN config file that it is "likely misplaced". It never
+            // blocks a write, and narrowing it belongs at the point of classification, in
+            // check-node. Asserted so the behaviour is recorded and the fix has a test to flip.
+            ['the check config itself', '.platformos-check.yml'],
+        ])('admits %s, leaving the verdict to the lint', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual({ applicable: true });
+        });
+        it('reports the PROJECT-RELATIVE path even when given an absolute one', () => {
+            // Forward slashes, spelled literally rather than built with `join`: the reason string
+            // is agent-facing, and an agent that sent `app/notes.txt` must get that spelling back
+            // on every platform. Building the expectation with `join` made it agree with whatever
+            // the host does, so it passed on POSIX while asserting `app\notes.txt` on Windows.
+            //
+            // This cannot FAIL on POSIX if the separator handling regresses — check-common's
+            // `path.spec.ts` is what guards that, over Windows-shaped input on any host.
+            expect(applicable(join(PROJECT, 'app/notes.txt'))).toEqual(unsupported('app/notes.txt'));
+        });
+    });
+    it('checks containment BEFORE type, so an unsupported outside path cites the root', () => {
+        // Both rules reject `/etc/passwd`; the order determines which reason the agent
+        // gets, and "outside the project" is the more actionable of the two.
+        expect(applicable('/etc/passwd')).toEqual(outside('/etc/passwd'));
+    });
+});
+/**
+ * The size bound is the ONLY guard that acts before a pathological buffer reaches the
+ * parser, and it is sized against the FULL lint (~61 ms/KiB), not the parse alone.
+ *
+ * A deadline cannot substitute for it: the parse is synchronous, so the timer cannot even
+ * FIRE during one, and further out the parser stops completing at all — 2 MiB throws inside
+ * ohm's CST→AST recursion, 4 MiB produced a native V8 abort that no handler can catch.
+ */
+describe('Unit: bufferTooLarge', () => {
+    const bytes = (n) => 'a'.repeat(n);
+    it('accepts a buffer at exactly the limit', () => {
+        // Boundary is inclusive — an exactly-limit buffer is legal, so `<=` not `<`.
+        expect(bufferTooLarge(bytes(MAX_BUFFER_BYTES))).toBeUndefined();
+    });
+    it('refuses a buffer one byte over the limit', () => {
+        const declined = bufferTooLarge(bytes(MAX_BUFFER_BYTES + 1));
+        expect(declined?.code).toEqual('too_large');
+        expect(declined?.reason).toEqual('The buffer is 128 KiB, above the 128 KiB limit this server will validate, so it was ' +
+            'refused before parsing. Liquid validation costs about 75 ms per KiB and the parser stops ' +
+            'completing at all a few MiB out, so checking this would risk hanging the server rather ' +
+            'than answering. Nothing was checked — consider splitting the file, which is almost ' +
+            'certainly worth doing at this size regardless.');
+    });
+    it('accepts every realistic file size', () => {
+        // The largest real source file found across local projects is 76 KiB.
+        expect([
+            bufferTooLarge(''),
+            bufferTooLarge('{% render "card" %}'),
+            bufferTooLarge(bytes(76 * 1024)),
+            bufferTooLarge(bytes(120 * 1024)),
+        ]).toEqual([undefined, undefined, undefined, undefined]);
+    });
+    it('counts BYTES, not string length, so multi-byte content cannot slip past', () => {
+        // '€' is 3 bytes in UTF-8. A `content.length` check would see a third of the real cost
+        // and admit a buffer three times the intended size.
+        const justUnderByLength = '€'.repeat(Math.floor(MAX_BUFFER_BYTES / 3) + 1);
+        expect(justUnderByLength.length).toBeLessThan(MAX_BUFFER_BYTES);
+        expect(bufferTooLarge(justUnderByLength)?.code).toEqual('too_large');
+    });
+    it('reports the actual size in the reason, so the agent knows by how much', () => {
+        expect(bufferTooLarge(bytes(2 * 1024 * 1024))?.reason).toContain('The buffer is 2048 KiB');
+    });
+});
+describe('Unit: toAbsoluteFilePath', () => {
+    it('joins a relative path onto the project root', () => {
+        expect(toAbsoluteFilePath(PROJECT, 'app/views/pages/index.liquid')).toEqual(join(PROJECT, 'app/views/pages/index.liquid'));
+    });
+    it('returns an absolute path unchanged', () => {
+        expect(toAbsoluteFilePath(PROJECT, '/etc/passwd')).toEqual('/etc/passwd');
+    });
+    it('normalizes `..` segments when joining', () => {
+        // Expressed against the filesystem ROOT rather than a literal `/etc/passwd`, so it
+        // resolves with the host's own separator; hard-coding the POSIX spelling asserted the
+        // platform rather than the normalization this test is about.
+        const filesystemRoot = parse(PROJECT).root;
+        expect(toAbsoluteFilePath(PROJECT, '../../../etc/passwd')).toEqual(join(filesystemRoot, 'etc', 'passwd'));
+    });
+});
+/**
+ * `next_step` is prose the supervisor writes ABOUT ITS OWN ANSWER, which invariant #6
+ * permits. The line is thin here, because a refusal has to say something about where
+ * platformOS looks for files in order to be actionable at all.
+ *
+ * It stays on the right side of it by DERIVING that fact: the deployed subtrees come from
+ * `APP_SOURCE_SUBTREES`, and the rule itself is a documentation URL. A hand-written list
+ * would be a second source of truth for the directory layout.
+ */
+describe('Unit: refusal prose derives platform facts rather than restating them', () => {
+    const subtrees = APP_SOURCE_SUBTREES.map((subtree) => `${subtree}/`);
+    it.each([
+        ['misplacedSource', misplacedSource('scripts/build.liquid')],
+        ['notPlatformOSFile', notPlatformOSFile('README.md')],
+    ])('%s names every deployed subtree, from the shared table', (_name, declined) => {
+        expect(subtrees.filter((subtree) => !declined.reason.includes(subtree))).toEqual([]);
+    });
+    it('points at the documentation for the rule instead of explaining it here', () => {
+        // The pointer, not the prose: an agent that needs the whole directory layout is sent
+        // to the page that owns it.
+        expect(misplacedSource('scripts/build.liquid').reason).toContain('https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure');
+    });
+    /**
+     * The CONTROL: this must fail if the subtree list is ever hardcoded to today's value.
+     * Deriving the expectation from the same constant the code reads would pass either way,
+     * so the assertion is that the message tracks a subtree the shared table does NOT
+     * currently contain — impossible to satisfy with a literal string.
+     */
+    it('would track a new subtree without an edit here', () => {
+        // Every subtree in the message came from the table, and the message contains no
+        // directory that looks deployed but is absent from it.
+        const invented = 'definitely_not_a_subtree';
+        expect(misplacedSource('x.liquid').reason).not.toContain(invented);
+        expect(APP_SOURCE_SUBTREES).not.toContain(invented);
+    });
+});
+//# sourceMappingURL=adapter-input.spec.js.map

package/dist/bin/args.spec.d.ts

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

package/dist/bin/args.spec.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { parseArgs, resolveProjectDir } from './args.js';
+describe('Unit: parseArgs', () => {
+    it('parses --project <dir>', () => {
+        expect(parseArgs(['--project', '/p'])).toEqual({ projectDir: '/p', help: false });
+    });
+    it('parses --project=<dir>', () => {
+        expect(parseArgs(['--project=/p'])).toEqual({ projectDir: '/p', help: false });
+    });
+    it('parses --help and -h', () => {
+        expect(parseArgs(['--help'])).toEqual({ projectDir: undefined, help: true });
+        expect(parseArgs(['-h'])).toEqual({ projectDir: undefined, help: true });
+    });
+    it('tolerates unknown flags', () => {
+        expect(parseArgs(['--future', 'x', '--project', '/p'])).toEqual({
+            projectDir: '/p',
+            help: false,
+        });
+    });
+    it('returns no projectDir when none given', () => {
+        expect(parseArgs([])).toEqual({ projectDir: undefined, help: false });
+    });
+});
+describe('Unit: resolveProjectDir', () => {
+    it('prefers the --project argument over env and cwd', () => {
+        expect(resolveProjectDir({ projectDir: '/arg', help: false }, { POS_SUPERVISOR_PROJECT_DIR: '/env' }, '/cwd')).toEqual('/arg');
+    });
+    it('falls back to POS_SUPERVISOR_PROJECT_DIR when no argument', () => {
+        expect(resolveProjectDir({ help: false }, { POS_SUPERVISOR_PROJECT_DIR: '/env' }, '/cwd')).toEqual('/env');
+    });
+    it('falls back to cwd when neither argument nor env is set', () => {
+        expect(resolveProjectDir({ help: false }, {}, '/cwd')).toEqual('/cwd');
+    });
+});
+//# sourceMappingURL=args.spec.js.map

package/dist/check-docs.d.ts

@@ -0,0 +1,21 @@
+/** The documentation a check publishes about itself. */
+export interface CheckDocs {
+    /** One-line description, from `meta.docs.description`. */
+    description: string;
+    /**
+     * The check's documentation page. Absent for the few checks whose meta publishes no
+     * `url` — absent rather than guessed, because a URL assembled from a code is a link
+     * that 404s, which is worse than no link.
+     */
+    url?: string;
+}
+/**
+ * The documentation for a check code, or `undefined` when nothing is registered under it.
+ *
+ * `undefined` is a real answer, not a gap to paper over: `CheckError` — check-common's code
+ * for "a check crashed on this file" — is reported on offenses and is not a registered
+ * check, so a consumer must handle a miss rather than assume every offense has a page.
+ */
+export declare function checkDocs(code: string): CheckDocs | undefined;
+/** Every registered check code. Exported for the tests that assert this map is complete. */
+export declare function registeredCheckCodes(): string[];

package/dist/check-docs.js

@@ -0,0 +1,38 @@
+/**
+ * What a check MEANS and where to read more — derived from check-common's registry.
+ *
+ * THE SUPERVISOR AUTHORS NO DOCUMENTATION (ARCHITECTURE.md §Invariants). It may describe
+ * itself — its result contract, how to read an answer — and nothing about the platform or
+ * about what a check is for; that prose lives in `meta.docs.description` and at
+ * `meta.docs.url`.
+ *
+ * So this module is a LOOKUP, not a table, built from `allChecks` at load time: a check
+ * renamed, removed or added upstream changes this map without anyone editing it.
+ */
+import { allChecks } from '@platformos/platformos-check-common';
+/**
+ * Keyed by `meta.code` ONLY, which is the exact string an offense carries
+ * (`check: check.meta.code` in check-common's `check()`).
+ *
+ * `meta.aliases` are deliberately NOT keys: an alias is a name a CONFIG may use, never
+ * something an offense carries, so mapping it would add entries nothing can look up.
+ */
+const BY_CODE = new Map(allChecks.map((check) => [
+    check.meta.code,
+    { description: check.meta.docs.description, url: check.meta.docs.url },
+]));
+/**
+ * The documentation for a check code, or `undefined` when nothing is registered under it.
+ *
+ * `undefined` is a real answer, not a gap to paper over: `CheckError` — check-common's code
+ * for "a check crashed on this file" — is reported on offenses and is not a registered
+ * check, so a consumer must handle a miss rather than assume every offense has a page.
+ */
+export function checkDocs(code) {
+    return BY_CODE.get(code);
+}
+/** Every registered check code. Exported for the tests that assert this map is complete. */
+export function registeredCheckCodes() {
+    return [...BY_CODE.keys()];
+}
+//# sourceMappingURL=check-docs.js.map

package/dist/check-docs.spec.d.ts

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

package/dist/check-docs.spec.js

@@ -0,0 +1,87 @@
+/**
+ * The check-documentation lookup is DERIVED, and these assertions are written so a
+ * documentation release cannot fail them while OUR side falling behind does.
+ *
+ * Nothing here restates what a check's description SAYS, or which URL it has. That is
+ * settled in check-common and in the `platformos-documentation` repo, where the page
+ * lives; a test here that pinned the text would duplicate a gate it cannot see and rot on
+ * a release that is perfectly correct.
+ */
+import { allChecks } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { checkDocs, registeredCheckCodes } from './check-docs.js';
+describe('Unit: checkDocs', () => {
+    it('answers for every registered check, and for nothing else', () => {
+        // Derived on both sides: the registry is the input AND the expectation, so adding a
+        // check upstream cannot leave this map behind.
+        expect(registeredCheckCodes().sort()).toEqual(allChecks.map((check) => check.meta.code).sort());
+    });
+    it('returns each check its own description, taken from the registry rather than restated', () => {
+        const mismatched = allChecks
+            .map((check) => ({
+            code: check.meta.code,
+            expected: check.meta.docs.description,
+            actual: checkDocs(check.meta.code)?.description,
+        }))
+            .filter((entry) => entry.actual !== entry.expected);
+        expect(mismatched).toEqual([]);
+    });
+    it('returns the check its own documentation URL, and omits it when meta publishes none', () => {
+        const mismatched = allChecks
+            .map((check) => ({
+            code: check.meta.code,
+            expected: check.meta.docs.url,
+            actual: checkDocs(check.meta.code)?.url,
+        }))
+            .filter((entry) => entry.actual !== entry.expected);
+        expect(mismatched).toEqual([]);
+    });
+    /**
+     * A miss is a real answer. `CheckError` is check-common's code for "a check crashed on
+     * this file"; it reaches an agent as an ordinary offense and has no registry entry, so a
+     * consumer that assumed every code resolves would throw on exactly the paths that are
+     * already going wrong.
+     */
+    it('returns undefined for a code that is not a registered check', () => {
+        expect(checkDocs('CheckError')).toBeUndefined();
+        expect(checkDocs('NotACheckAtAll')).toBeUndefined();
+    });
+    /**
+     * EVERY check publishes a documentation URL — a requirement rather than a report, now
+     * that the server instructions tell an agent to follow `see_also` instead of restating
+     * platform rules. A check with no URL means an agent is stopped by a finding and given
+     * nowhere to read about it.
+     *
+     * A new check therefore fails here until it is documented: the page is part of shipping a
+     * check, not a follow-up.
+     */
+    it('every registered check publishes a documentation URL', () => {
+        const withoutUrl = allChecks
+            .filter((check) => !check.meta.docs.url)
+            .map((check) => check.meta.code)
+            .sort();
+        expect(withoutUrl, `these checks have no docs.url — add a page under ` +
+            `app/views/pages/developer-guide/platformos-check/checks/ in platformos-documentation, ` +
+            `plus its overview row and nav entry:\n${withoutUrl.join('\n')}`).toEqual([]);
+    });
+    /**
+     * The URL must be one the documentation site can serve, not merely a non-empty string.
+     *
+     * Asserted by SHAPE rather than by fetching — no network in a unit test — which still
+     * catches the realistic mistake: a URL pointing at the wrong section, or a check code
+     * pasted where a slug belongs.
+     *
+     * A check with NO url is skipped rather than dereferenced; that is the sibling test's
+     * subject, and a `TypeError` here would preempt it.
+     */
+    it('every documentation URL points into the checks section of the docs site', () => {
+        const BASE = 'https://documentation.platformos.com/developer-guide/platformos-check/checks/';
+        const malformed = allChecks
+            .map((check) => ({ code: check.meta.code, url: check.meta.docs.url }))
+            .filter(({ url }) => url !== undefined &&
+            (!url.startsWith(BASE) || !/^[a-z0-9-]+$/.test(url.slice(BASE.length))))
+            .map(({ code, url }) => `${code} -> ${url}`);
+        expect(malformed).toEqual([]);
+    });
+});
+//# sourceMappingURL=check-docs.spec.js.map

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+/** The per-server context and the request-path deadlines — shared INFRASTRUCTURE. */
+import type { Logger } from './logger.js';
+/**
+ * Per-server context threaded into every handler.
+ *
+ * NO CACHE HANDLES HERE, and their absence is the point. check-node keeps ONE lazy `App`
+ * per project at process level and reconciles it per call, so a cache nobody has to
+ * remember to pass is a cache no call path can forget — do not reintroduce a handle here
+ * (see check-node's "Process-level state"). The blast radius is likewise DERIVED per
+ * request from the project's text (`impact/project-scan.ts`), so nothing can be stale.
+ */
+export interface SupervisorContext {
+    /** Absolute project root that buffers are validated against. */
+    projectDir: string;
+    log: Logger;
+}
+/**
+ * Deadline for the blast radius. Much tighter than the lint's, which is a function of
+ * admitted bytes and lives in `cost-model.ts` — deliberately not re-exported from here.
+ *
+ * Tight because the work is small — one project read (235 ms measured on a 2,615-file
+ * project) plus a name filter and a handful of parses, p50 9 ms / p90 63 ms per file — and
+ * because exceeding it costs only the answer, which has an `unavailable` state. The tail it
+ * exists for is real but rare: the most-referenced partial measured took ~1 s.
+ */
+export declare const IMPACT_DEADLINE_MS = 2000;

package/dist/context.js

@@ -0,0 +1,11 @@
+/**
+ * Deadline for the blast radius. Much tighter than the lint's, which is a function of
+ * admitted bytes and lives in `cost-model.ts` — deliberately not re-exported from here.
+ *
+ * Tight because the work is small — one project read (235 ms measured on a 2,615-file
+ * project) plus a name filter and a handful of parses, p50 9 ms / p90 63 ms per file — and
+ * because exceeding it costs only the answer, which has an `unavailable` state. The tail it
+ * exists for is real but rare: the most-referenced partial measured took ~1 s.
+ */
+export const IMPACT_DEADLINE_MS = 2_000;
+//# sourceMappingURL=context.js.map

package/dist/cost-model.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What a lint COSTS — and therefore how much work one request may admit, and how long the
+ * server waits for it.
+ *
+ * The byte caps and the deadline are ONE relationship, written here as arithmetic and
+ * derived rather than chosen. Adding per-node work moves {@link LINT_MS_PER_KIB} and every
+ * dependent bound follows; `cost-model.spec.ts` fails if any of them stops fitting. A batch
+ * admitted past its deadline returns `timed_out` for EVERY file in the request, so the two
+ * drifting apart fails quietly and in the expensive direction.
+ *
+ * THE DEADLINE SCALES WITH THE REQUEST because a fixed one and a meaningful batch cap
+ * cannot both exist: hold it at 60 s and the largest admissible batch is ~133 KiB, smaller
+ * than a single legal buffer. Scaling costs little — this deadline is a backstop for ASYNC
+ * stalls (see `deadline.ts`) rather than a CPU bound.
+ *
+ * Every number here is MEASURED, and the measurement is named. A plausible constant is how
+ * this file rots back into unrelated magic numbers.
+ */
+/**
+ * Wall-clock cost of linting one KiB of buffer, on an idle machine, warm cache.
+ *
+ * Measured end to end (`runValidateCode`, the whole request path), not against the parse
+ * alone. Reproduce with `scripts/measure-lint-cost.mjs`, which builds a synthetic project
+ * and prints the rate for a single buffer and for batch shapes; the slowest observed was
+ * ~51 ms/KiB, on CLEAN markup rather than the diagnostic-dense shape.
+ *
+ * DO NOT LOWER THIS TO MATCH A FASTER MEASUREMENT. The rate varies by several times with
+ * the project and the markup, so the constant is deliberately set above the slowest
+ * observed value. Being wrong FAST costs a longer wait before a stall is declared; being
+ * wrong SLOW admits a request that cannot finish and returns `timed_out` for every file.
+ */
+export declare const LINT_MS_PER_KIB = 75;
+/**
+ * How much slower the same lint runs on a contended machine than on an idle one.
+ *
+ * Measured at ~2.3x (128 KiB: ~10 s idle, ~23 s under load), held at 3 because it bounds
+ * someone else's machine. Being wrong low produces a false `timed_out` — a silent
+ * no-answer — while being wrong high costs only a longer wait before declaring a stall.
+ */
+export declare const LOAD_FACTOR = 3;
+/**
+ * How far beyond the expected loaded worst case the deadline sits. The deadline must never
+ * fire on work that was legal to admit; it exists to catch a stall.
+ */
+export declare const DEADLINE_MARGIN = 2;
+/** Deadline granted per KiB of admitted work: idle cost, under load, with margin. */
+export declare const DEADLINE_MS_PER_KIB: number;
+/**
+ * Deadline floor, applied to every request however small.
+ *
+ * Small requests are not dominated by their buffers: a cold first call also builds the app,
+ * loads the config and reconciles the graph (~0.8 s idle, ~1.6 s loaded on a 162-file
+ * project). The floor covers that fixed cost with room to spare.
+ */
+export declare const MIN_LINT_DEADLINE_MS = 60000;
+/**
+ * Deadline ceiling, and therefore the origin of {@link maxBytesWithin}'s answer for the
+ * batch cap.
+ *
+ * POLICY rather than measurement: how long the server holds a request open before
+ * concluding it has stalled. Two minutes is past the point where an agent has any use for
+ * the answer, and every extra second of ceiling buys a larger admissible batch.
+ */
+export declare const MAX_LINT_DEADLINE_MS = 120000;
+/**
+ * How much of the AGENT'S CONTEXT one `validate_code` answer may spend.
+ *
+ * POLICY, like {@link MAX_LINT_DEADLINE_MS}, and the one bound here that is not about the
+ * server's own work. Unbounded, a legal call was measured returning ~336 000 tokens — more
+ * than most context windows hold, with nothing in the payload saying so.
+ *
+ * At ~153 bytes per diagnostic this budget holds roughly 200 findings. Measured real calls
+ * cost tens to hundreds of tokens, so the cap cannot touch them; what it defends against is
+ * the tail — a generated file, or one cascading syntax error in a large partial.
+ */
+export declare const RESPONSE_TOKEN_BUDGET = 8000;
+/**
+ * Bytes per token, for converting the budget above into something countable.
+ *
+ * A crude ESTIMATE — this JSON is mostly ASCII prose, where ~4 bytes/token is the usual
+ * rule of thumb, and the real tokenizer is the client's. Being wrong by 25% moves the cap
+ * between ~150 and ~250 diagnostics, which changes nothing about which calls it affects.
+ */
+export declare const BYTES_PER_TOKEN = 4;
+/**
+ * The bound actually enforced: serialized bytes of diagnostics one response may
+ * carry, across the WHOLE request rather than per file.
+ *
+ * Per-request because per-file alone leaves the worst case multiplied by the file
+ * count — 50 files each just under a per-file cap is 50x the intended bound, and the
+ * batch form exists precisely so agents send many files at once.
+ */
+export declare const MAX_RESPONSE_DIAGNOSTIC_BYTES: number;
+/**
+ * What one file costs in a response BEFORE any diagnostics: its status, gate, `impact`
+ * object, empty lists, and — when findings were withheld — the truncation note.
+ *
+ * Measured, not assumed: a 50-file batch of clean files serializes to 234 bytes per file,
+ * and the note adds ~150. Held at 512 because this multiplies by the file count.
+ */
+export declare const RESPONSE_ENVELOPE_BYTES_PER_FILE = 512;
+/**
+ * The whole response bound, stated as arithmetic rather than enforced directly.
+ *
+ * The allocator bounds DIAGNOSTICS, the only unbounded dimension; the envelope is O(files)
+ * and already bounded by the batch file cap. `transport/validate-code.spec.ts` measures the
+ * worst legal request against this.
+ *
+ * Takes the file count rather than importing `MAX_BATCH_FILES`, which lives in
+ * `validate/batch-bounds.ts` and already imports this module.
+ */
+export declare function maxResponseBytes(fileCount: number): number;
+/**
+ * How long to wait for a lint that was handed `bytes` of buffer.
+ *
+ * Never below {@link MIN_LINT_DEADLINE_MS}. Callers do not clamp to
+ * {@link MAX_LINT_DEADLINE_MS} — the byte caps do that upstream by refusing the request
+ * outright, so the ceiling is enforced where the work is admitted, not where it is timed.
+ */
+export declare function lintDeadlineMs(bytes: number): number;
+/**
+ * The most bytes whose {@link lintDeadlineMs} still fits inside `deadlineMs`.
+ *
+ * The inverse of the function above, floored to a whole KiB so the answer is exact at the
+ * boundary — one byte more and the deadline exceeds `deadlineMs`. Used to derive the batch
+ * cap from the deadline ceiling instead of from a round multiple of the per-buffer bound.
+ */
+export declare function maxBytesWithin(deadlineMs: number): number;