@platformos/platformos-mcp-supervisor 0.0.2 → 0.1.0

package/dist/cost-model.js

@@ -0,0 +1,137 @@
+/**
+ * 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 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 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 const DEADLINE_MARGIN = 2;
+/** Deadline granted per KiB of admitted work: idle cost, under load, with margin. */
+export const DEADLINE_MS_PER_KIB = LINT_MS_PER_KIB * LOAD_FACTOR * DEADLINE_MARGIN;
+/**
+ * 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 const MIN_LINT_DEADLINE_MS = 60_000;
+/**
+ * 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 const MAX_LINT_DEADLINE_MS = 120_000;
+/**
+ * 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 const RESPONSE_TOKEN_BUDGET = 8_000;
+/**
+ * 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 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 const MAX_RESPONSE_DIAGNOSTIC_BYTES = RESPONSE_TOKEN_BUDGET * BYTES_PER_TOKEN;
+/**
+ * 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 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 function maxResponseBytes(fileCount) {
+    return MAX_RESPONSE_DIAGNOSTIC_BYTES + fileCount * RESPONSE_ENVELOPE_BYTES_PER_FILE;
+}
+/** KiB in `bytes`, rounded UP — a partial KiB still costs a full unit of work. */
+const kib = (bytes) => Math.ceil(bytes / 1024);
+/**
+ * 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 function lintDeadlineMs(bytes) {
+    return Math.max(MIN_LINT_DEADLINE_MS, kib(bytes) * DEADLINE_MS_PER_KIB);
+}
+/**
+ * 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 function maxBytesWithin(deadlineMs) {
+    return Math.floor(deadlineMs / DEADLINE_MS_PER_KIB) * 1024;
+}
+//# sourceMappingURL=cost-model.js.map

package/dist/cost-model.spec.d.ts

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

package/dist/cost-model.spec.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { DEADLINE_MARGIN, DEADLINE_MS_PER_KIB, LINT_MS_PER_KIB, LOAD_FACTOR, MAX_LINT_DEADLINE_MS, MIN_LINT_DEADLINE_MS, lintDeadlineMs, maxBytesWithin, } from './cost-model.js';
+import { MAX_BUFFER_BYTES } from './adapter-input.js';
+import { MAX_BATCH_BYTES, MAX_BATCH_FILES } from './validate/batch-bounds.js';
+/**
+ * The arithmetic, and the invariants that make it safe.
+ *
+ * WHAT THIS FILE IS FOR. The defect it exists to prevent is not a wrong number —
+ * it is two numbers that stopped being related to each other without anything
+ * noticing. `MAX_BATCH_BYTES` was `4 * MAX_BUFFER_BYTES` and the deadline was 60 s,
+ * and they were compatible until `FilterArity` moved throughput; after that the
+ * worst legal batch could not finish inside the deadline it was given, and every
+ * file in such a request comes back `timed_out` — no validation, no error, no sign.
+ *
+ * So the assertions below are mostly RELATIONSHIPS, not values. A relationship
+ * fails the moment someone changes one side of it, which is precisely when it needs
+ * to be looked at. The few literal values that are pinned are pinned because they
+ * are what makes the relationships legible in a failure message.
+ */
+describe('Unit: the lint cost model', () => {
+    it('composes the per-KiB deadline from its three named factors', () => {
+        // Pinned as a composition, not as 450: a reader who changes LOAD_FACTOR should
+        // see this follow, and a reader who changes this alone should see it break.
+        expect([LINT_MS_PER_KIB, LOAD_FACTOR, DEADLINE_MARGIN, DEADLINE_MS_PER_KIB]).toEqual([
+            75,
+            3,
+            2,
+            75 * 3 * 2,
+        ]);
+    });
+    it('charges a partial KiB as a whole one', () => {
+        // Rounding DOWN would grant a deadline smaller than the work admitted, which is
+        // the failure this module exists to prevent — so the rounding direction is part
+        // of the contract, not an implementation detail.
+        expect([lintDeadlineMs(300 * 1024), lintDeadlineMs(300 * 1024 - 1023)]).toEqual([
+            300 * DEADLINE_MS_PER_KIB,
+            300 * DEADLINE_MS_PER_KIB,
+        ]);
+    });
+    it('never returns less than the floor, however small the request', () => {
+        expect([lintDeadlineMs(0), lintDeadlineMs(1), lintDeadlineMs(1024)]).toEqual([
+            MIN_LINT_DEADLINE_MS,
+            MIN_LINT_DEADLINE_MS,
+            MIN_LINT_DEADLINE_MS,
+        ]);
+    });
+    it('inverts exactly: one KiB more than maxBytesWithin overshoots the deadline', () => {
+        const bytes = maxBytesWithin(MAX_LINT_DEADLINE_MS);
+        expect([lintDeadlineMs(bytes) <= MAX_LINT_DEADLINE_MS, lintDeadlineMs(bytes + 1024)]).toEqual([
+            true,
+            lintDeadlineMs(bytes) + DEADLINE_MS_PER_KIB,
+        ]);
+    });
+});
+describe('Unit: the bounds derived from the cost model', () => {
+    it('admits the worst legal BATCH inside the deadline that batch is granted', () => {
+        // The regression, stated directly. Before this derivation MAX_BATCH_BYTES was
+        // 512 KiB against a fixed 60 s deadline: 512 KiB of measured work is ~38 s idle
+        // and ~115 s loaded, so the worst legal batch could not finish in time and every
+        // file in it returned `timed_out`.
+        expect(lintDeadlineMs(MAX_BATCH_BYTES) <= MAX_LINT_DEADLINE_MS).toBe(true);
+    });
+    it('admits the worst legal single BUFFER inside the deadline it is granted', () => {
+        expect(lintDeadlineMs(MAX_BUFFER_BYTES) <= MAX_LINT_DEADLINE_MS).toBe(true);
+    });
+    it('leaves the single-file path on exactly the deadline it had before scaling', () => {
+        // Every real single-file call is far below MAX_BUFFER_BYTES, and even a maximal
+        // one lands on the floor. Scaling the deadline therefore changed nothing about
+        // the path that carries essentially all traffic — which is why it was safe to
+        // introduce. If this ever fails, single-file latency behaviour has moved and the
+        // 60 s figure quoted in `context.ts` and in the timeout message is stale.
+        expect(lintDeadlineMs(MAX_BUFFER_BYTES)).toEqual(MIN_LINT_DEADLINE_MS);
+    });
+    it('never refuses a batch for being smaller than one legal single buffer', () => {
+        // A batch cap below the per-buffer cap would refuse a one-file batch containing
+        // a file the single-file form accepts — the same content, refused for the shape
+        // of the request. This is also what forces the deadline to scale: at a fixed
+        // 60 s the derived batch cap is ~133 KiB, and this invariant fails.
+        expect(MAX_BATCH_BYTES > MAX_BUFFER_BYTES).toBe(true);
+    });
+    it('states the derived cap, so a change to the model shows up as a number', () => {
+        expect([MAX_BATCH_BYTES, MAX_BATCH_BYTES / 1024, MAX_BATCH_FILES]).toEqual([272_384, 266, 50]);
+    });
+    it('bounds the whole request even at the file-count cap', () => {
+        // MAX_BATCH_FILES alone cannot bound the work: 50 files just under the buffer
+        // cap would be ~6 MiB. The byte cap is what binds, and it binds well before the
+        // file cap does — this records which of the two is load-bearing.
+        expect(MAX_BATCH_FILES * MAX_BUFFER_BYTES > MAX_BATCH_BYTES).toBe(true);
+    });
+});
+//# sourceMappingURL=cost-model.spec.js.map

package/dist/deadline.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A deadline wrapper for the request path.
+ *
+ * WHAT THIS DOES AND DOES NOT BUY. The lint cannot be interrupted mid-flight: parsing is
+ * synchronous CPU work on the one event loop, so no timer preempts it. Racing a deadline
+ * returns control to the CALLER while the work runs on to completion. That fixes the
+ * failure mode that hurts — the agent stops waiting — but it is a BACKSTOP, not the primary
+ * defence, which is bounding the input (`MAX_BUFFER_BYTES`). True cancellation would need
+ * the lint on a worker thread.
+ */
+/**
+ * Returned instead of a value when the deadline expires. A unique symbol rather
+ * than `undefined`/`null` so it can never collide with a legitimate result.
+ */
+export declare const TIMED_OUT: unique symbol;
+export type TimedOut = typeof TIMED_OUT;
+/**
+ * Resolve with `work`'s value, or with {@link TIMED_OUT} once `ms` elapses.
+ *
+ * The timer is cleared on BOTH outcomes, and `unref`'d besides, so a pending deadline can
+ * never hold the process open.
+ *
+ * A rejection from `work` propagates unchanged. NOTE that when the deadline wins, `work` is
+ * left running and unobserved — the caller MUST attach a handler to it, or a later
+ * rejection becomes an unhandled rejection.
+ */
+export declare function withDeadline<T>(work: Promise<T>, ms: number): Promise<T | TimedOut>;

package/dist/deadline.js

@@ -0,0 +1,40 @@
+/**
+ * A deadline wrapper for the request path.
+ *
+ * WHAT THIS DOES AND DOES NOT BUY. The lint cannot be interrupted mid-flight: parsing is
+ * synchronous CPU work on the one event loop, so no timer preempts it. Racing a deadline
+ * returns control to the CALLER while the work runs on to completion. That fixes the
+ * failure mode that hurts — the agent stops waiting — but it is a BACKSTOP, not the primary
+ * defence, which is bounding the input (`MAX_BUFFER_BYTES`). True cancellation would need
+ * the lint on a worker thread.
+ */
+/**
+ * Returned instead of a value when the deadline expires. A unique symbol rather
+ * than `undefined`/`null` so it can never collide with a legitimate result.
+ */
+export const TIMED_OUT = Symbol('platformos-supervisor:timed-out');
+/**
+ * Resolve with `work`'s value, or with {@link TIMED_OUT} once `ms` elapses.
+ *
+ * The timer is cleared on BOTH outcomes, and `unref`'d besides, so a pending deadline can
+ * never hold the process open.
+ *
+ * A rejection from `work` propagates unchanged. NOTE that when the deadline wins, `work` is
+ * left running and unobserved — the caller MUST attach a handler to it, or a later
+ * rejection becomes an unhandled rejection.
+ */
+export function withDeadline(work, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(TIMED_OUT), ms);
+        // Node-only: `unref` keeps a pending deadline from holding the event loop.
+        timer.unref?.();
+        work.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=deadline.js.map

package/dist/deadline.spec.d.ts

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

package/dist/deadline.spec.js

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TIMED_OUT, withDeadline } from './deadline.js';
+/**
+ * TASK-15. `withDeadline` is a backstop, and its contract is narrow on purpose:
+ * add a deadline, change nothing else. In particular a rejection must pass through
+ * untouched, because the lint is the primary gate and swallowing its failure would
+ * turn a real error into a silent pass.
+ */
+const after = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));
+const rejectAfter = (ms, error) => new Promise((_, reject) => setTimeout(() => reject(error), ms));
+describe('Unit: withDeadline', () => {
+    it('resolves with the value when the work finishes first', async () => {
+        await expect(withDeadline(after(1, 'done'), 1_000)).resolves.toEqual('done');
+    });
+    it('resolves with TIMED_OUT when the deadline wins', async () => {
+        await expect(withDeadline(after(1_000, 'too late'), 5)).resolves.toBe(TIMED_OUT);
+    });
+    it('resolves with TIMED_OUT for work that never settles at all', async () => {
+        // The exact shape that used to hang the tool for the life of the session.
+        await expect(withDeadline(new Promise(() => { }), 5)).resolves.toBe(TIMED_OUT);
+    });
+    it('propagates a rejection unchanged rather than converting it to TIMED_OUT', async () => {
+        // The lint is the primary gate: a genuine failure must stay a failure.
+        const failure = new Error('lint exploded');
+        await expect(withDeadline(rejectAfter(1, failure), 1_000)).rejects.toThrow(failure);
+    });
+    it('preserves a falsy result, which a null/undefined sentinel would have destroyed', async () => {
+        // TIMED_OUT is a unique Symbol precisely so these stay distinguishable.
+        await expect(withDeadline(Promise.resolve(undefined), 1_000)).resolves.toBeUndefined();
+        await expect(withDeadline(Promise.resolve(null), 1_000)).resolves.toBeNull();
+        await expect(withDeadline(Promise.resolve(0), 1_000)).resolves.toEqual(0);
+        await expect(withDeadline(Promise.resolve([]), 1_000)).resolves.toEqual([]);
+    });
+    it('clears the timer when the work wins, so nothing is left pending', async () => {
+        const clearSpy = vi.spyOn(globalThis, 'clearTimeout');
+        try {
+            await withDeadline(after(1, 'done'), 60_000);
+            // A 60 s timer left armed would hold a stdio server open past its work.
+            expect(clearSpy).toHaveBeenCalled();
+        }
+        finally {
+            clearSpy.mockRestore();
+        }
+    });
+    it('clears the timer when the work REJECTS, not only when it resolves', async () => {
+        const clearSpy = vi.spyOn(globalThis, 'clearTimeout');
+        try {
+            await expect(withDeadline(rejectAfter(1, new Error('x')), 60_000)).rejects.toThrow();
+            expect(clearSpy).toHaveBeenCalled();
+        }
+        finally {
+            clearSpy.mockRestore();
+        }
+    });
+    it('unrefs the deadline timer so a pending one cannot hold the process open', async () => {
+        const unref = vi.fn();
+        const setSpy = vi
+            .spyOn(globalThis, 'setTimeout')
+            .mockImplementation((() => ({ unref })));
+        try {
+            void withDeadline(Promise.resolve('immediate'), 60_000);
+            expect(unref).toHaveBeenCalledOnce();
+        }
+        finally {
+            setSpy.mockRestore();
+        }
+    });
+    it('does not stop the abandoned work from continuing — the documented limitation', async () => {
+        // Parsing is synchronous CPU work; nothing here can preempt it. The deadline
+        // frees the CALLER, it does not cancel. Pinned so the limitation is not
+        // mistaken for a bug later, and so nobody assumes cancellation they don't have.
+        let finished = false;
+        const work = after(30, 'eventually').then((value) => {
+            finished = true;
+            return value;
+        });
+        expect(await withDeadline(work, 5)).toBe(TIMED_OUT);
+        expect(finished).toBe(false);
+        await work;
+        expect(finished).toBe(true);
+    });
+});
+//# sourceMappingURL=deadline.spec.js.map

package/dist/enrich/enrich.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The PURE enrichment stage: what the supervisor adds to a diagnostic beyond what the
+ * engine reported.
+ *
+ * It adds exactly two things, and **authors neither of them**:
+ *
+ *   `see_also`  the check's own documentation page, from check-common `meta.docs.url`.
+ *   `hint`      the docset entry for the symbol the diagnostic is about, rendered by the
+ *               same function every editor hover uses.
+ *
+ * The restraint is the design. The supervisor ships no documentation (ARCHITECTURE.md
+ * §Invariants #6): the words an agent reads come from `filters.json` / `tags.json` /
+ * `objects.json` and from the check registry, both owned and tested where they are
+ * published. A hint composed here would be a second source of truth that goes stale.
+ *
+ * PURE, and mechanically so: no `fs`, no `process`, no import of `lint/`, nothing async.
+ * The docset arrives already resolved to plain arrays, so "no I/O below the lint edge" is a
+ * matter of shape rather than of trust.
+ */
+import type { FilterEntry, LiquidHtmlNode, ObjectEntry, TagEntry } from '@platformos/platformos-check-common';
+import type { ValidateCodeDiagnostic } from '../result/types.js';
+/**
+ * The docset, resolved to data.
+ *
+ * Plain arrays rather than the `AugmentedPlatformOSDocset` itself, whose methods return
+ * promises and would let a future edit `await` inside the pure stage. The caller resolves it
+ * once per request and hands over the result.
+ */
+export interface DocsetVocabulary {
+    filters: readonly FilterEntry[];
+    tags: readonly TagEntry[];
+    objects: readonly ObjectEntry[];
+}
+/**
+ * The checks for which a published SIGNATURE is the answer.
+ *
+ * Policy, not documentation — a statement about which findings an agent can act on with a
+ * signature in front of it, the same kind of judgement as `BLOCKING_CHECKS`. Each entry
+ * says why, because "it seemed relevant" is how this grows into noise.
+ *
+ * DEFAULTS TO SILENCE. A check not listed gets no hint, so a check added upstream cannot
+ * start emitting an unrelated wall of markdown before anyone has looked at it.
+ *
+ * A list rather than a structural rule, because no structural rule separates the useful
+ * case from the useless one: `{% render 'ghost' %}` resolves to the `render` TAG, so
+ * rendering whatever symbol an offense sits on answers "'ghost' does not exist" with
+ * general documentation about how `render` works.
+ */
+export declare const SIGNATURE_HINT_CHECKS: ReadonlySet<string>;
+/** One diagnostic, with the buffer offset the engine reported it at. */
+export interface EnrichInput {
+    diagnostic: ValidateCodeDiagnostic;
+    /**
+     * 0-based offset of the offense start, in the buffer as sent. Carried alongside rather
+     * than added to `ValidateCodeDiagnostic`, which an agent reads.
+     *
+     * OPTIONAL, and absence means "do not resolve a symbol for this one" — not spelled as an
+     * out-of-range sentinel, which only LOOKS inert: `findCurrentNode` always answers, and at
+     * an impossible offset it answers `Document`.
+     */
+    startIndex?: number;
+}
+/** Everything enrichment reads. All of it data; none of it fetched here. */
+export interface EnrichContext {
+    /**
+     * The buffer's Liquid tree, as returned by the lint that produced these diagnostics.
+     *
+     * `undefined` for a buffer with no Liquid tree — GraphQL, YAML, or a file that did not
+     * parse. Those diagnostics simply get no symbol hint; the check's documentation URL
+     * still attaches, because it does not depend on the tree.
+     */
+    ast?: LiquidHtmlNode;
+    vocabulary: DocsetVocabulary;
+}
+/**
+ * Attach what we can to each diagnostic, and nothing we cannot.
+ *
+ * Returns NEW objects; the inputs are not mutated. A diagnostic gains a key only when there
+ * is a real value for it — never an empty string or a placeholder — so an agent can read
+ * absence as "nothing more is known".
+ *
+ * ONE HINT PER SYMBOL PER FILE. A signature is ~880 bytes of markdown and it is the SAME
+ * bytes every time the symbol is misused, so repeats would spend the diagnostic budget
+ * (`result/response-budget.ts`) restating one paragraph. The FIRST occurrence keeps it,
+ * which is also the one truncation keeps: the cap retains the top of the file.
+ */
+export declare function enrichDiagnostics(inputs: readonly EnrichInput[], context: EnrichContext): ValidateCodeDiagnostic[];

package/dist/enrich/enrich.js

@@ -0,0 +1,97 @@
+// Deep import, NOT the package root: measured at +5 ms against +110 ms, the difference
+// being the css / json / graphql language services this package never uses. The bin is
+// launched once per agent session, so that is paid every session. See ADR 002 Amendment 1.
+import { render } from '@platformos/platformos-language-server-common/dist/docset/index.js';
+import { checkDocs } from '../check-docs.js';
+import { documentedSymbolAt } from './symbol.js';
+/**
+ * The checks for which a published SIGNATURE is the answer.
+ *
+ * Policy, not documentation — a statement about which findings an agent can act on with a
+ * signature in front of it, the same kind of judgement as `BLOCKING_CHECKS`. Each entry
+ * says why, because "it seemed relevant" is how this grows into noise.
+ *
+ * DEFAULTS TO SILENCE. A check not listed gets no hint, so a check added upstream cannot
+ * start emitting an unrelated wall of markdown before anyone has looked at it.
+ *
+ * A list rather than a structural rule, because no structural rule separates the useful
+ * case from the useless one: `{% render 'ghost' %}` resolves to the `render` TAG, so
+ * rendering whatever symbol an offense sits on answers "'ghost' does not exist" with
+ * general documentation about how `render` works.
+ */
+export const SIGNATURE_HINT_CHECKS = new Set([
+    // "given 1, expected 2" — the published arity IS the fix, and it is the one thing the
+    // message cannot carry without restating the documentation.
+    'FilterArity',
+    // An argument of the wrong type. What the filter actually accepts is the answer, and
+    // the parameter list is where it is written down.
+    'ValidFilterArgumentTypes',
+    // The same for a tag's arguments: `{% for x in y limit: 'ten' %}` is answered by the
+    // `for` entry's parameter types.
+    'ValidTagArgumentTypes',
+]);
+/**
+ * Attach what we can to each diagnostic, and nothing we cannot.
+ *
+ * Returns NEW objects; the inputs are not mutated. A diagnostic gains a key only when there
+ * is a real value for it — never an empty string or a placeholder — so an agent can read
+ * absence as "nothing more is known".
+ *
+ * ONE HINT PER SYMBOL PER FILE. A signature is ~880 bytes of markdown and it is the SAME
+ * bytes every time the symbol is misused, so repeats would spend the diagnostic budget
+ * (`result/response-budget.ts`) restating one paragraph. The FIRST occurrence keeps it,
+ * which is also the one truncation keeps: the cap retains the top of the file.
+ */
+export function enrichDiagnostics(inputs, context) {
+    const rendered = new Set();
+    return inputs.map(({ diagnostic, startIndex }) => {
+        const enriched = { ...diagnostic };
+        const url = checkDocs(diagnostic.check)?.url;
+        if (url)
+            enriched.see_also = url;
+        const hint = hintFor(diagnostic.check, startIndex, context, rendered);
+        if (hint)
+            enriched.hint = hint;
+        return enriched;
+    });
+}
+/**
+ * The rendered docset entry for the symbol at `offset`, when the docset publishes one and
+ * this file has not already been shown it.
+ *
+ * NOTHING when it does not: a symbol the docset has never heard of has no signature to
+ * show, and the engine's own `suggestions` are what help there.
+ *
+ * Searched from the offset OUTWARDS through the ancestors — `{% for x in y limit: 'ten' %}`
+ * reports on the argument, and the `for` entry that answers it is three levels up.
+ *
+ * `rendered` is mutated only when a hint is actually produced, so an unpublished symbol
+ * cannot consume the slot its name has and silence a later published one.
+ */
+function hintFor(check, offset, context, rendered) {
+    if (!SIGNATURE_HINT_CHECKS.has(check))
+        return undefined;
+    if (!context.ast || offset === undefined)
+        return undefined;
+    const symbol = documentedSymbolAt(context.ast, offset);
+    if (!symbol)
+        return undefined;
+    const key = `${symbol.kind}:${symbol.name}`;
+    if (rendered.has(key))
+        return undefined;
+    const entry = entryFor(symbol, context.vocabulary);
+    if (!entry)
+        return undefined;
+    rendered.add(key);
+    return render(entry, undefined, symbol.kind);
+}
+/** The published entry for a symbol, matched by exact name within its own kind. */
+function entryFor(symbol, vocabulary) {
+    const entries = symbol.kind === 'filter'
+        ? vocabulary.filters
+        : symbol.kind === 'tag'
+            ? vocabulary.tags
+            : vocabulary.objects;
+    return entries.find((entry) => entry.name === symbol.name);
+}
+//# sourceMappingURL=enrich.js.map

package/dist/enrich/enrich.spec.d.ts

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