@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/workers/focused-extractor.js

@@ -2,26 +2,23 @@
  * The **Focused extractor** — the one place a no-tools child pi is run to answer ONE question
  * over content already in hand, cite a verbatim `<excerpt>`, and have that citation checked.
  *
- * It had four copies: `fetchFocused` (fetch-core), `docsFocused` (docs-core), and both paths
- * of `pi-worker-docs` (project source, npm package) — the last two 17-of-20 lines identical
- * and 150 lines apart inside one function. Everything the four did around the child was
- * byte-identical: the `--no-tools` argv, `getPiInvocation`, `runChild`, `parseChildOutput`,
- * and no retry. What genuinely differed was DATA, and the copies hid it:
+ * Its two callers are `fetchFocused` (fetch-core) and `docsLookup` (docs-lookup), and
+ * everything they do around the child is the same: the `--no-tools` argv,
+ * `getPiInvocation`, `runChild`, `parseChildOutput`, and no retry. What genuinely differs is
+ * DATA, and each difference has a name here:
  *
- *   1. the prompt body — so {@link FocusedRequest.prompt} is a string the caller assembles;
+ *   1. the prompt body — {@link FocusedRequest.prompt} is a string the caller assembles;
  *   2. WHAT the excerpt is verified against — see {@link FocusedRequest.verifyAgainst};
  *   3. what the answer MEANS (fetch's coverage-miss sentinel) — left to the caller, because
  *      classifying an answer is the caller's domain, not the child runner's.
  *
- * Two things the copies got wrong, fixed here once:
- *   - **Failure.** `docsFocused` never called `formatChildFailure`, so a child that exited
- *     non-zero had its raw stdout parsed as if it were an answer (`parseChildOutput` returns
- *     the whole trimmed stdout when there is no `<answer>` tag) and handed to the caller.
- *     The result type below makes that unrepresentable: there is no `answer` on a failure.
- *   - **Evidence.** Only fetch kept the rich {@link ExcerptVerification}; the other three
- *     reduced it to a bare boolean, which is exactly the diagnostic gap typeonly-log.ts
- *     names — an `excerptVerified === false` that cannot afterwards be attributed to
- *     fabrication vs a normaliser gap. Every caller now gets the struct.
+ * Two invariants the result type enforces rather than documents:
+ *   - **Failure.** A child that aborted or exited non-zero has no `answer` field at all. It
+ *     cannot be read as one, which matters because `parseChildOutput` returns the whole
+ *     trimmed stdout when there is no `<answer>` tag — a crashed child's error dump.
+ *   - **Evidence.** Every caller gets the full {@link ExcerptVerification}, not a bare
+ *     boolean, so a false verdict can afterwards be attributed to fabrication rather than a
+ *     normaliser gap.
  */
 import { spawn as defaultSpawn } from 'node:child_process';
 import { getPiInvocation } from '../shared/pi-invocation.js';
@@ -30,9 +27,9 @@ import { childBaseArgs } from '../shared/child-extensions.js';
 import { parseChildOutput, verifyExcerpt } from '../shared/child-output.js';
 import { formatChildFailure } from './shared.js';
 /**
- * The argv every focused extraction child runs with: the shared child base (whitelisted
- * extensions + `--print --no-session …`) plus `--no-tools`. This was three byte-identical
- * one-liners in fetch-core, docs-core and pi-worker-docs.
+ * The argv every focused extraction child runs with: the shared child base — any whitelisted
+ * extensions, then `--print --no-skills --no-extensions --no-prompt-templates
+ * --no-context-files --no-session` — then the caller's thinking fragment, then `--no-tools`.
  *
  * `--no-tools` is the contract, not a default: the child is given all the content it may use
  * inside its prompt, so a tool call could only reach for something unsourced.
@@ -47,7 +44,7 @@ export const focusedChildArgs = (thinking = []) => [
  * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
  *
  * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
- * bill for the same answer, and all four call sites already had it that way.
+ * bill for the same answer. Exactly one child is spawned per call.
  */
 export async function runFocusedExtraction(req) {
     const spawn = req.spawn ?? defaultSpawn;

package/dist/workers/html-clean.js

@@ -20,7 +20,8 @@ export function cleanHtml(html, baseUrl) {
             finalUrl: baseUrl
         };
     }
-    // Fallback: turndown the body
+    // Readability found no article — turndown the raw body instead. An empty body
+    // yields empty markdown, and the title falls back to the URL's hostname.
     const body = doc.body;
     const bodyHtml = body ? body.innerHTML : '';
     const markdown = turndown.turndown(bodyHtml).trim();
@@ -32,14 +33,17 @@ export function cleanHtml(html, baseUrl) {
 }
 const DEFAULT_TIMEOUT_MS = 15_000;
 const DEFAULT_MAX_BYTES = 2 * 1024 * 1024; // 2 MB
-// Read at runtime so the User-Agent never drifts out of sync with releases.
+// Read at runtime — `readPkgVersion` re-reads package.json on every call — so the
+// User-Agent never drifts out of sync with releases and no build step bakes it in.
 const PKG_VERSION = readPkgVersion();
 const USER_AGENT = `pi-worker/${PKG_VERSION} (+https://npmjs.com/package/@mjasnikovs/pi-worker)`;
-// Decide how to handle a response based on its content-type. HTML is run through
-// the readability/turndown pipeline; text-ish formats (markdown, plain text,
-// JSON, XML/feeds) are already clean and pass through verbatim; binary formats
-// (PDF, images, octet-stream, …) are rejected. A missing content-type is treated
-// as text — many plain-text endpoints (llms.txt, robots.txt) omit the header.
+// Decide how to handle a response based on its content-type, case-insensitively
+// and ignoring any `; charset=…` tail. HTML and XHTML run through the
+// readability/turndown pipeline; text-ish formats (any `text/*`, JSON and `+json`,
+// XML and `+xml`, javascript) are already clean and pass through verbatim; anything
+// else — PDF, images, octet-stream — is rejected as `not-html`. A missing
+// content-type is treated as text: many plain-text endpoints (llms.txt,
+// robots.txt) omit the header.
 function classifyContentType(contentType) {
     const mime = contentType.split(';')[0].trim().toLowerCase();
     if (mime === '')
@@ -58,14 +62,17 @@ function classifyContentType(contentType) {
 }
 // Extract the charset from a content-type header, if present and supported by
 // TextDecoder; otherwise fall back to UTF-8 so non-UTF-8 pages aren't mangled.
+// Quotes around the label are stripped, and an unsupported label decodes exactly
+// as UTF-8 would rather than throwing.
 function decoderFor(contentType) {
     const match = /charset=([^;]+)/i.exec(contentType);
     const charset = match?.[1]?.trim().replace(/^["']|["']$/g, '');
     if (charset) {
         try {
-            // The runtime accepts any charset label string; the type is narrowed
-            // to a known-encoding union by Bun/Node's lib (DOM's looser signature
-            // is no longer pulled in transitively). Cast to the actual param type.
+            // The runtime accepts any charset label string, but the type here is the
+            // narrow `Encoding` union — passing a plain `string` is TS2345,
+            // "not assignable to parameter of type 'Encoding | undefined'". Cast to
+            // the actual param type rather than widening the guard.
             return new TextDecoder(charset, {
                 fatal: false
             });
@@ -113,16 +120,19 @@ export async function fetchAndClean(url, opts = {}) {
             let bytesRead = 0;
             try {
                 while (true) {
-                    // response.body's stream type doesn't resolve here, so the chunk
-                    // surfaces as `any`; pin it to the Uint8Array the reader yields.
+                    // `reader.read()` resolves to `any` under this tsconfig — assigning
+                    // its `value` to a `number` raises no error — so the destructure is
+                    // pinned to the Uint8Array the reader actually yields.
                     const { value, done } = (await reader.read());
                     if (done)
                         break;
                     if (value) {
                         bytesRead += value.byteLength;
                         if (bytesRead > maxBytes) {
-                            // OUR abort, told apart from the user's and the clock's
-                            // by the seam — all three abort the same signal.
+                            // OUR abort. All three cancels fire the same signal, so the
+                            // seam is what tells them apart: `ctl.abort()` here,
+                            // `ctl.userAborted()` for the caller's, `ctl.timedOut()` for
+                            // the clock. Only the local `sizeExceeded` flag says it was us.
                             sizeExceeded = true;
                             ctl.abort();
                             break;

package/dist/workers/http-request.d.ts

@@ -1,32 +1,36 @@
 /**
  * http-request — the one bounded HTTP request in this codebase.
  *
- * Five modules used to hand-roll the same ~12 lines: an internal
- * `AbortController`, a `setTimeout` that aborts it, a `userAborted` flag set
- * from the caller's signal, and a `finally` that clears the timer and removes
- * the listener. Five copies of a rule is five chances to drift, and it HAD
- * drifted — `npm-version.ts` never grew the `userAborted` flag, so a user cancel
- * came back as `null`, indistinguishable from a registry that is down.
+ * Its five callers — brave-search, ddg-search, exa-search, html-clean and
+ * npm-version — would otherwise each hand-roll the same dozen lines: an internal
+ * `AbortController`, a `setTimeout` that aborts it, a `userAborted` flag set from
+ * the caller's signal, and a `finally` that clears the timer and removes the
+ * listener. Five copies of a rule is five chances to drift, and the flag is the
+ * piece that goes missing: without it a user cancel is indistinguishable from a
+ * host that is down.
  *
  * What is shared is the BOUNDING, not the interpretation. Each caller still owns
  * its own status-code policy (DDG treats 429/403 as rate-limiting, Brave splits
- * auth from rate-limit, npm treats every non-OK as "no answer") and its own error
- * type, because those genuinely differ. What they cannot differ on is whether the
- * request was cancelled by the user, killed by the clock, or refused by the
- * network — so that verdict is made once, here.
+ * auth from rate-limit, npm-version treats every non-OK as "no answer") and its
+ * own error type, because those genuinely differ. A status code never reaches
+ * {@link HttpRequestError} at all — the handler is simply called with the
+ * response, whatever its status.
  *
  * The handler runs INSIDE the timeout. `fetch` resolves as soon as the headers
  * arrive, so a seam that returned the `Response` and cleared its own timer would
- * leave the body read unbounded — a hung stream would hang forever. Passing a
- * handler keeps the clock over the whole operation, which is what every copy of
- * the ritual already did.
+ * leave the body read unbounded — a hung stream would hang forever. Here the
+ * clock aborts a handler that is still reading, and `ctl.timedOut()` is true
+ * inside it when that happens.
  */
 /** Injectable fetch — the narrow signature keeps test fakes free of Bun's extras. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 /**
- * Why the request never produced a response. Deliberately only two kinds: a
- * status code is not a failure of the REQUEST, and what a given status means is
- * the caller's policy.
+ * Why the request never produced a response. Only two kinds, because a status code
+ * is not a failure of the REQUEST and what a status means is the caller's policy.
+ *
+ * `aborted` means the CALLER cancelled — nothing else mints it. A timeout during
+ * `fetch` arrives here as `network`, since only `userAborted` is consulted on that
+ * path; a handler that needs to tell the clock apart reads `ctl.timedOut()`.
  */
 export declare class HttpRequestError extends Error {
     readonly kind: 'aborted' | 'network';
@@ -44,7 +48,9 @@ export interface HttpRequestOpts {
     redirect?: 'follow' | 'error' | 'manual';
     /** Wall clock over the request AND the handler. Required — no silent default. */
     timeoutMs: number;
-    /** The caller's cancel. Its firing is what makes `userAborted()` true. */
+    /** The caller's cancel. Its firing is what makes `userAborted()` true — and a
+     *  signal that is ALREADY aborted sets the flag before `fetch` is called, so
+     *  the immediate rejection is still classified as `aborted`. */
     signal?: AbortSignal;
     fetchImpl?: FetchLike;
 }
@@ -54,8 +60,9 @@ export interface HttpRequestControl {
     readonly signal: AbortSignal;
     /**
      * Abort the in-flight request from inside the handler — a size cap hit, an
-     * early stop. Distinct from both a user cancel and the timeout, so a handler
-     * that calls this can tell its own abort apart from the other two.
+     * early stop. It sets NEITHER flag, so after calling it `userAborted()` and
+     * `timedOut()` are both false while `signal.aborted` is true. A handler that
+     * calls this can therefore tell its own abort from the other two.
      */
     abort(): void;
     /** The CALLER cancelled. Not the timeout, not `abort()`. */
@@ -70,5 +77,6 @@ export interface HttpRequestControl {
  * `handle` throws propagates untouched — that is the caller's own policy talking.
  */
 export declare function httpRequest<T>(url: string, opts: HttpRequestOpts, handle: (response: Response, ctl: HttpRequestControl) => Promise<T>): Promise<T>;
-/** A readable one-liner for an unknown thrown value. Four byte-identical copies. */
+/** A readable one-liner for an unknown thrown value: an Error's `message`,
+ *  otherwise `String(err)` — so `42` and `null` render as text, not as a crash. */
 export declare function describeError(err: unknown): string;

package/dist/workers/http-request.js

@@ -1,30 +1,34 @@
 /**
  * http-request — the one bounded HTTP request in this codebase.
  *
- * Five modules used to hand-roll the same ~12 lines: an internal
- * `AbortController`, a `setTimeout` that aborts it, a `userAborted` flag set
- * from the caller's signal, and a `finally` that clears the timer and removes
- * the listener. Five copies of a rule is five chances to drift, and it HAD
- * drifted — `npm-version.ts` never grew the `userAborted` flag, so a user cancel
- * came back as `null`, indistinguishable from a registry that is down.
+ * Its five callers — brave-search, ddg-search, exa-search, html-clean and
+ * npm-version — would otherwise each hand-roll the same dozen lines: an internal
+ * `AbortController`, a `setTimeout` that aborts it, a `userAborted` flag set from
+ * the caller's signal, and a `finally` that clears the timer and removes the
+ * listener. Five copies of a rule is five chances to drift, and the flag is the
+ * piece that goes missing: without it a user cancel is indistinguishable from a
+ * host that is down.
  *
  * What is shared is the BOUNDING, not the interpretation. Each caller still owns
  * its own status-code policy (DDG treats 429/403 as rate-limiting, Brave splits
- * auth from rate-limit, npm treats every non-OK as "no answer") and its own error
- * type, because those genuinely differ. What they cannot differ on is whether the
- * request was cancelled by the user, killed by the clock, or refused by the
- * network — so that verdict is made once, here.
+ * auth from rate-limit, npm-version treats every non-OK as "no answer") and its
+ * own error type, because those genuinely differ. A status code never reaches
+ * {@link HttpRequestError} at all — the handler is simply called with the
+ * response, whatever its status.
  *
  * The handler runs INSIDE the timeout. `fetch` resolves as soon as the headers
  * arrive, so a seam that returned the `Response` and cleared its own timer would
- * leave the body read unbounded — a hung stream would hang forever. Passing a
- * handler keeps the clock over the whole operation, which is what every copy of
- * the ritual already did.
+ * leave the body read unbounded — a hung stream would hang forever. Here the
+ * clock aborts a handler that is still reading, and `ctl.timedOut()` is true
+ * inside it when that happens.
  */
 /**
- * Why the request never produced a response. Deliberately only two kinds: a
- * status code is not a failure of the REQUEST, and what a given status means is
- * the caller's policy.
+ * Why the request never produced a response. Only two kinds, because a status code
+ * is not a failure of the REQUEST and what a status means is the caller's policy.
+ *
+ * `aborted` means the CALLER cancelled — nothing else mints it. A timeout during
+ * `fetch` arrives here as `network`, since only `userAborted` is consulted on that
+ * path; a handler that needs to tell the clock apart reads `ctl.timedOut()`.
  */
 export class HttpRequestError extends Error {
     kind;
@@ -95,7 +99,8 @@ export async function httpRequest(url, opts, handle) {
             opts.signal.removeEventListener('abort', onUserAbort);
     }
 }
-/** A readable one-liner for an unknown thrown value. Four byte-identical copies. */
+/** A readable one-liner for an unknown thrown value: an Error's `message`,
+ *  otherwise `String(err)` — so `42` and `null` render as text, not as a crash. */
 export function describeError(err) {
     if (err instanceof Error)
         return err.message;

package/dist/workers/npm-version.d.ts

@@ -1,18 +1,25 @@
 /**
  * Live npm registry version lookup.
  *
- * Solves a real failure mode: the auto-answer/research workers have no live
- * source for "what's the latest published version of X", so they answer from
- * training data, which goes stale. TASK_0005 hit this — the worker said
- * "18.3.1, the latest stable React" when React 19.x had shipped months earlier.
+ * Without it the auto-answer and research workers have no live source for "what
+ * is the latest published version of X", so they answer from training data, which
+ * is stale by construction — it can only ever name a version that existed when the
+ * model was trained.
  *
- * This module fetches the npm registry's metadata endpoint and returns just
- * enough to anchor the worker in current reality: the dist-tag 'latest', a
- * short list of recent versions, and the publish date of latest.
+ * This fetches the registry's metadata endpoint and returns just enough to anchor
+ * a worker in the present: the dist-tag `latest`, a short list of versions, and
+ * the publish date of `latest`.
  */
 export interface NpmVersionInfo {
     pkg: string;
+    /** The `latest` dist-tag — the stable release npm would install. */
     latest: string;
+    /**
+     * The LAST `RECENT_VERSIONS_LIMIT` keys of the registry's `versions` map,
+     * reversed. That is publication order, not semver order, and it is not
+     * filtered: for a package that publishes prereleases these are mostly canary
+     * and experimental builds, not the recent stable releases.
+     */
     recent: string[];
     publishedAt?: string;
 }
@@ -23,10 +30,20 @@ export interface NpmVersionOpts {
 }
 /**
  * Fetch the latest version + recent version list for an npm package.
- * Returns `null` (never throws) on any failure — registry down, package not
- * found, network error, malformed response. The caller treats null as "no
- * fresh data available" and continues without it.
+ *
+ * Returns `null` on every ordinary failure — an invalid package name, a registry
+ * that is down, a 404, a malformed body, a missing `dist-tags.latest`. The caller
+ * treats null as "no fresh data available" and continues without it.
+ *
+ * It is NOT null-on-everything: a user cancel is re-thrown (see below), and so is
+ * anything that is not an {@link HttpRequestError}.
+ *
+ * An invalid name is rejected before any request is made. `UPPER` is valid — the
+ * name regex is case-insensitive — while an empty name, a leading `.` or `_`, a
+ * space, more than 214 characters, or an unscoped path like `a/b/c` are not.
  */
 export declare function npmVersionLookup(pkg: string, opts?: NpmVersionOpts): Promise<NpmVersionInfo | null>;
-/** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT. */
+/** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT: a
+ *  `### npm: <pkg>` heading, a `latest:` line that gains ` (published YYYY-MM-DD)`
+ *  when the date is known, and a `recent:` line only when the list is non-empty. */
 export declare function formatNpmVersionSection(info: NpmVersionInfo): string;

package/dist/workers/npm-version.js

@@ -1,14 +1,14 @@
 /**
  * Live npm registry version lookup.
  *
- * Solves a real failure mode: the auto-answer/research workers have no live
- * source for "what's the latest published version of X", so they answer from
- * training data, which goes stale. TASK_0005 hit this — the worker said
- * "18.3.1, the latest stable React" when React 19.x had shipped months earlier.
+ * Without it the auto-answer and research workers have no live source for "what
+ * is the latest published version of X", so they answer from training data, which
+ * is stale by construction — it can only ever name a version that existed when the
+ * model was trained.
  *
- * This module fetches the npm registry's metadata endpoint and returns just
- * enough to anchor the worker in current reality: the dist-tag 'latest', a
- * short list of recent versions, and the publish date of latest.
+ * This fetches the registry's metadata endpoint and returns just enough to anchor
+ * a worker in the present: the dist-tag `latest`, a short list of versions, and
+ * the publish date of `latest`.
  */
 import { httpRequest, HttpRequestError } from './http-request.js';
 const REGISTRY_BASE = 'https://registry.npmjs.org';
@@ -16,9 +16,17 @@ const DEFAULT_TIMEOUT_MS = 3000;
 const RECENT_VERSIONS_LIMIT = 10;
 /**
  * Fetch the latest version + recent version list for an npm package.
- * Returns `null` (never throws) on any failure — registry down, package not
- * found, network error, malformed response. The caller treats null as "no
- * fresh data available" and continues without it.
+ *
+ * Returns `null` on every ordinary failure — an invalid package name, a registry
+ * that is down, a 404, a malformed body, a missing `dist-tags.latest`. The caller
+ * treats null as "no fresh data available" and continues without it.
+ *
+ * It is NOT null-on-everything: a user cancel is re-thrown (see below), and so is
+ * anything that is not an {@link HttpRequestError}.
+ *
+ * An invalid name is rejected before any request is made. `UPPER` is valid — the
+ * name regex is case-insensitive — while an empty name, a leading `.` or `_`, a
+ * space, more than 214 characters, or an unscoped path like `a/b/c` are not.
  */
 export async function npmVersionLookup(pkg, opts = {}) {
     if (!isValidPackageName(pkg))
@@ -54,10 +62,9 @@ export async function npmVersionLookup(pkg, opts = {}) {
         });
     }
     catch (err) {
-        // A user cancel is re-thrown, not swallowed. This module was the copy of the
-        // request ritual that never grew a `userAborted` flag, so a cancelled lookup
-        // returned `null` — indistinguishable from a registry that is down, and the
-        // caller went on assembling a block for a run the user had already stopped.
+        // A user cancel is RE-THROWN, not swallowed. Returning null here would make a
+        // cancelled lookup indistinguishable from a registry that is down, and the
+        // caller would go on assembling a version block for a run the user stopped.
         if (err instanceof HttpRequestError && err.kind === 'aborted')
             throw err;
         if (err instanceof HttpRequestError)
@@ -65,7 +72,9 @@ export async function npmVersionLookup(pkg, opts = {}) {
         throw err;
     }
 }
-/** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT. */
+/** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT: a
+ *  `### npm: <pkg>` heading, a `latest:` line that gains ` (published YYYY-MM-DD)`
+ *  when the date is known, and a `recent:` line only when the list is non-empty. */
 export function formatNpmVersionSection(info) {
     const lines = [`### npm: ${info.pkg}`, `latest: ${info.latest}`];
     if (info.publishedAt) {

package/dist/workers/phantom-imports.d.ts

@@ -37,7 +37,9 @@ export declare function findPhantomImports(text: string, cwd: string, loadText?:
 /** Render flagged phantoms as an authoritative research section, or '' if none. */
 export declare function formatApiCorrections(phantoms: PhantomImport[]): string;
 /**
- * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * A top-of-handoff override banner (Layer B — orchestrator.ts names the two layers:
+ * A strips phantoms from the refined spec, B overrides at delivery). The check has
+ * proven —
  * against the installed type definitions — that the spec, or a design doc it
  * references, names an API that does NOT exist. The implementer is told the spec/doc
  * is authoritative, so a residual affirmative that survived into the composed spec, or
@@ -57,17 +59,18 @@ export declare function formatApiOverrideBanner(phantoms: PhantomImport[]): stri
 export declare function findDeliveryPhantoms(spec: string, cwd: string): Promise<PhantomImport[]>;
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
- * import the installed types prove, so NO affirmative occurrence of the non-existent
- * specifier survives downstream. This is the half an appended correction can't do:
- * REFINE preserves identifiers verbatim, so `bun:sql` otherwise rides into the
- * composed GOAL (proven: compose re-leaks it 4/4) and on to the implementer. Strike
- * it at the source and compose has nothing to contradict.
+ * import the installed types prove, so NO affirmative occurrence of the specifier
+ * survives downstream. This is the half an APPENDED correction cannot do: later
+ * phases copy identifiers verbatim, so a `bun:sql` left in the text keeps being
+ * re-stated no matter what a correction says about it.
  *
- * Deterministic, no LLM. Idempotent on healthy input: once a specifier is replaced
- * the literal is gone, so a second pass is a no-op (the only residue is a `declare
- * module` comment that quotes the spec inside a slash-star, which the bare-word rule
- * skips via its lookbehind). Handles the four forms a phantom takes: an import/require
- * `from "<spec>"`, a fabricated `declare module "<spec>"`, a backticked prose mention
- * `` `<spec>` ``, and a bare word `<spec>`.
+ * Deterministic, no LLM. Handles the four forms a phantom takes: an import/require
+ * `from "<spec>"`, a fabricated `declare module "<spec>"`, a backticked prose
+ * mention `` `<spec>` ``, and a bare word. A path-like `./bun:sql/x` is left alone
+ * by the bare-word rule's lookbehind.
+ *
+ * Idempotent: once a specifier is replaced the literal is gone. The `declare
+ * module` replacement deliberately does not echo the spec, so a second pass over
+ * the output returns it byte for byte.
  */
 export declare function rewritePhantomSpecifiers(text: string, phantoms: PhantomImport[]): string;

package/dist/workers/phantom-imports.js

@@ -3,13 +3,16 @@
  * task/spec but NOT actually declared by the runtime's installed types.
  *
  * A real `<runtime>:<sub>` builtin appears as `declare module "<runtime>:<sub>"`
- * in the runtime's type files (bun-types declares bun:sqlite/bun:test/bun:ffi/…;
- * @types/node declares node:fs/…). A specifier with no such declaration is a
- * hallucination — the symbol, if it exists at all, lives on the base module. This
- * is the exact `bun:sql` failure class: a design doc invented `bun:sql`, every
- * phase echoed it, and the implementer fabricated a `declare module "bun:sql"`
- * shim to make it compile. Verifying the specifier against the installed types
- * catches it deterministically, with no false positives and no LLM call.
+ * in the runtime's type files: bun-types declares exactly bun:bundle, bun:ffi,
+ * bun:jsc, bun:sqlite and bun:test, and @types/node declares node:assert,
+ * node:buffer, node:child_process and the rest. A specifier with no such
+ * declaration is a hallucination — the symbol, if it exists at all, lives on the
+ * base module. `bun:sql` is the canonical case: bun-types declares no such module,
+ * but `declare module "bun"` does declare `const sql: SQL`, so the correct import
+ * is from `"bun"` and a `declare module "bun:sql"` shim only hides the mistake.
+ *
+ * The check is deterministic and needs no LLM call. It can only be as good as the
+ * installed types: a runtime whose types are not on disk is skipped entirely.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -22,9 +25,9 @@ const DECLARE_MODULE_RE = /declare module "([^"]+)"/g;
 export function extractRuntimeSpecifiers(text) {
     const seen = new Set();
     for (const m of text.matchAll(SPEC_RE)) {
-        // Normalise: drop a trailing punctuation the word boundary may include is
-        // already excluded by the class; lowercase the runtime only (subpaths are
-        // case-sensitive). splitRuntimeNamespace lowercases the runtime itself.
+        // Kept exactly as written, including case: `BUN:SQL` and `bun:sql` are two
+        // entries here. `splitRuntimeNamespace` lowercases the runtime downstream,
+        // and the subpath is case-sensitive, so nothing is folded at this layer.
         if (!seen.has(m[0]))
             seen.add(m[0]);
     }
@@ -44,8 +47,8 @@ export function classifyRuntimeImport(spec, runtime, sub, typeText) {
     if (!real) {
         const leaf = sub.split('/').pop() ?? sub;
         // Does the base runtime module declare a symbol named like the submodule
-        // leaf (e.g. `bun:sql` → `const sql` / `class SQL` in `declare module "bun"`)?
-        // Case-insensitive so `sql` matches the `SQL` class too.
+        // leaf? Case-insensitive, which is what makes `bun:sql` find the real
+        // `const sql: SQL` and report `SQL` as the symbol to import.
         const re = new RegExp(`\\b(?:const|class|function|let|var|namespace|interface|type)\\s+(${escapeRe(leaf)})\\b`, 'i');
         const m = re.exec(typeText);
         baseSymbol = m ? m[1] : null;
@@ -174,7 +177,9 @@ export function formatApiCorrections(phantoms) {
     return `API CORRECTIONS\n${lines.join('\n')}`;
 }
 /**
- * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * A top-of-handoff override banner (Layer B — orchestrator.ts names the two layers:
+ * A strips phantoms from the refined spec, B overrides at delivery). The check has
+ * proven —
  * against the installed type definitions — that the spec, or a design doc it
  * references, names an API that does NOT exist. The implementer is told the spec/doc
  * is authoritative, so a residual affirmative that survived into the composed spec, or
@@ -225,18 +230,19 @@ export async function findDeliveryPhantoms(spec, cwd) {
 }
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
- * import the installed types prove, so NO affirmative occurrence of the non-existent
- * specifier survives downstream. This is the half an appended correction can't do:
- * REFINE preserves identifiers verbatim, so `bun:sql` otherwise rides into the
- * composed GOAL (proven: compose re-leaks it 4/4) and on to the implementer. Strike
- * it at the source and compose has nothing to contradict.
+ * import the installed types prove, so NO affirmative occurrence of the specifier
+ * survives downstream. This is the half an APPENDED correction cannot do: later
+ * phases copy identifiers verbatim, so a `bun:sql` left in the text keeps being
+ * re-stated no matter what a correction says about it.
+ *
+ * Deterministic, no LLM. Handles the four forms a phantom takes: an import/require
+ * `from "<spec>"`, a fabricated `declare module "<spec>"`, a backticked prose
+ * mention `` `<spec>` ``, and a bare word. A path-like `./bun:sql/x` is left alone
+ * by the bare-word rule's lookbehind.
  *
- * Deterministic, no LLM. Idempotent on healthy input: once a specifier is replaced
- * the literal is gone, so a second pass is a no-op (the only residue is a `declare
- * module` comment that quotes the spec inside a slash-star, which the bare-word rule
- * skips via its lookbehind). Handles the four forms a phantom takes: an import/require
- * `from "<spec>"`, a fabricated `declare module "<spec>"`, a backticked prose mention
- * `` `<spec>` ``, and a bare word `<spec>`.
+ * Idempotent: once a specifier is replaced the literal is gone. The `declare
+ * module` replacement deliberately does not echo the spec, so a second pass over
+ * the output returns it byte for byte.
  */
 export function rewritePhantomSpecifiers(text, phantoms) {
     let out = text;