@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/workers/docs-chunk.js

@@ -1,29 +1,24 @@
 /**
- * docs-chunk — cutting source text into retrievable chunks, for every corpus the
- * docs Worker tool indexes.
+ * docs-chunk — cutting source text into retrievable chunks, for both corpora the
+ * docs Worker tool indexes: an npm package's `.d.ts` + README (docs-index.ts),
+ * and the local project's own `.ts`/`.tsx` (docs-project.ts).
  *
- * There are two corpora — an npm package's `.d.ts` + README, and the local
- * project's own `.ts`/`.tsx` — and they were chunked by two copies of this code.
- * Not similar code: the same chunk-split regex, the same size cap, byte-identical
- * `chunkDts`/`chunkTs` bodies, and byte-identical `splitAtMatches`/`sliceBytes`,
- * in `docs-index.ts` and `docs-project.ts`. One copy had tests; the other
- * (`docs-project.ts`, 319 lines) had no test file at all and was only ever
- * reached incidentally through the worker's own suite.
+ * The chunk boundary is load-bearing for retrieval: a chunk that splits a
+ * declaration in half matches on neither half's terms, so one boundary rule for
+ * both corpora is the point of this module.
  *
- * The chunk boundary is load-bearing for retrieval quality — a chunk that splits
- * a declaration in half retrieves as neither — so having it in two places was two
- * places for it to drift.
- *
- * What is NOT unified: the two INDEX bodies. They key on genuinely different
- * provenance (a package is name+version with a content hash and keeps its old
- * versions; the project is a cwd key with a max-mtime version and drops its old
- * ones on every re-index), and collapsing them would change one of those
- * behaviours rather than describe them.
+ * What is NOT shared: the two INDEX bodies. They key on genuinely different
+ * provenance. A package is `(name, version)` with a content hash, and re-indexing
+ * runs `DELETE FROM chunks WHERE name = ? AND version = ?`, so older versions
+ * survive. The project is a cwd-hash name with a max-mtime version, and
+ * re-indexing runs `DELETE FROM chunks WHERE name = ?`, dropping every older
+ * version. Collapsing them would change one of those behaviours, not describe it.
  */
 /**
- * Chunk ceiling. Chosen against the retrieval budget: chunks are assembled into
- * a fixed character budget for the extraction child, so a chunk larger than this
- * would crowd out every other result.
+ * Chunk ceiling, in UTF-8 bytes. Sized against the retrieval budget: retrieved
+ * chunks are assembled into `RETRIEVE_CONTENT_BUDGET` (24,000 characters) before
+ * going to the extraction child, so this caps any one chunk at about a third of
+ * what the child will ever see.
  */
 export const MAX_CHUNK_BYTES = 8 * 1024;
 /**
@@ -47,8 +42,10 @@ export function splitAtMatches(text, re) {
         if (m.index > lastIndex)
             parts.push(text.slice(lastIndex, m.index));
         lastIndex = m.index;
-        // Advance by ONE, not by the match length: the next declaration can begin
-        // inside what this match consumed (`export default async function`).
+        // Advance by ONE, not by the match length. The regex's trailing `\s+` can
+        // span a newline, so the next line-anchored declaration may start INSIDE
+        // what this match consumed: `export\nfunction a(){}` is two chunks here
+        // and one if the scan resumes past the match.
         re.lastIndex = m.index + 1;
     }
     if (lastIndex < text.length)
@@ -59,19 +56,17 @@ export function splitAtMatches(text, re) {
  * Cut a string into pieces of at most `maxBytes` UTF-8 bytes, never splitting a
  * character.
  *
- * The cut point is walked BACK to a UTF-8 lead byte first. Both copies of this
- * function used to cut at exactly `maxBytes` and rely on
- * `Buffer.toString('utf8')` to tidy up, which it does not: decoding a buffer that
- * ends mid-character yields a U+FFFD replacement character. That replacement is
- * 3 bytes wide, so measuring the advance by the decoded slice's byte length then
- * skipped PAST the straddling character. A `€`-dense chunk came out as
- * `€€€�€€€�…` — corrupted, and one character shorter per slice.
+ * The cut point is walked BACK to a UTF-8 lead byte first. Cutting at exactly
+ * `maxBytes` and letting `Buffer.toString('utf8')` tidy up does not work: decoding
+ * a buffer that ends mid-character yields U+FFFD. That replacement is 3 bytes
+ * wide, so the decoded slice measures LONGER than the cut — a 100-byte cut of
+ * `€`-dense text decodes to 102 bytes — and advancing by the decoded length then
+ * skips past the straddling character entirely.
  *
  * It matters beyond looking wrong: a chunk is quoted back as an `<excerpt>` and
- * checked verbatim against the source, and an excerpt carrying a replacement
- * character can never be found, so the answer is flagged as a possible
- * hallucination. Only reachable on non-ASCII text past the 8 KB chunk ceiling,
- * which is why two copies of it survived untested.
+ * checked verbatim against the source (`excerptVerified`), and an excerpt carrying
+ * a replacement character can never be found, so the answer is flagged as a
+ * possible hallucination. Only reachable on non-ASCII text past the chunk ceiling.
  */
 export function sliceBytes(s, maxBytes) {
     const out = [];
@@ -82,8 +77,9 @@ export function sliceBytes(s, maxBytes) {
         let end = maxBytes;
         while (end > 0 && (buf[end] & 0xc0) === 0x80)
             end--;
-        // A single character wider than the whole cap cannot be placed. Cut
-        // anyway rather than loop forever; unreachable for any cap >= 4.
+        // A single character wider than the whole cap cannot be placed. Cut anyway
+        // rather than loop forever — this is the one path that DOES emit U+FFFD.
+        // Unreachable for any cap >= 4: the widest UTF-8 character is 4 bytes.
         if (end === 0)
             end = maxBytes;
         out.push(buf.subarray(0, end).toString('utf8'));
@@ -97,11 +93,11 @@ export function sliceBytes(s, maxBytes) {
  * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
  * each labelled with the file it came from.
  *
- * `relPath` is a MODEL-FACING label and is used exactly as given — the npm path
- * normalises it to POSIX first so an index is identical across platforms, while
- * the project path keeps the native separator. It is never re-joined to the
- * filesystem, so neither choice is wrong; passing it through keeps that decision
- * with the caller that has a reason for it.
+ * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
+ * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
+ * across platforms; docs-project.ts passes `path.relative` through with the native
+ * separator. It is never re-joined to the filesystem, so neither is wrong — this
+ * leaves the choice with the caller that has a reason for it.
  */
 export function chunkDeclarations(content, relPath) {
     const chunks = [];

package/dist/workers/docs-core.d.ts

@@ -11,9 +11,9 @@ import { type ExcerptVerification } from '../shared/child-output.js';
  * what the version is grounded in instead of leaving it buried in tool details.
  * - 'declared-range': install was pinned to the project's own package.json range
  *   (the resolved version therefore matches project intent).
- * - 'npm-latest': nothing in the project declared the dep, so the install fell
- *   back to whatever npm tags `latest` — which may be a newer MAJOR than the
- *   project targets (this is what a scaffolding task hits, and needs a banner).
+ * - 'npm-latest': nothing usable in the project declared the dep, so the install
+ *   fell back to whatever npm tags `latest` — which may be a newer MAJOR than the
+ *   project targets, which is what the banner warns about.
  */
 export interface AutoInstallPin {
     source: 'declared-range' | 'npm-latest';
@@ -74,9 +74,9 @@ export interface DocsRawInput {
 export interface DocsFocusedResult {
     /**
      * The child's answer — EMPTY when `failure` is set. A failed child's stdout is never
-     * parsed as an answer (it used to be: `parseChildOutput` returns the whole trimmed
-     * stdout when there is no `<answer>` tag, so a crashed child's error dump was handed
-     * to phaseAutoAnswer as if it were package documentation).
+     * parsed as an answer. `parseChildOutput` returns the whole trimmed stdout when
+     * there is no `<answer>` tag, so parsing one hands a crashed child's error dump
+     * to phaseAutoAnswer as if it were package documentation.
      */
     answer: string;
     excerpt?: string;
@@ -117,9 +117,10 @@ export interface Declaration {
  * The names a declaration for `asked` can honestly live under, nearest first:
  * the package itself, its DefinitelyTyped package, and the terminal the type
  * resolution chain landed on. A project that uses Bun declares `@types/bun`, not
- * `bun`; asking only about the terminal `bun-types` finds nothing at all, which
- * is how 35 of run 20's 48 banners came to report on a package nobody asked
- * about.
+ * `bun`; asking only about the terminal `bun-types` finds nothing at all, so a
+ * banner keyed on the terminal would report on a package nobody asked about. The
+ * terminal is deduped: `declarationChain('hono', 'hono')` is
+ * `['hono', '@types/hono']`.
  */
 export declare function declarationChain(asked: string, resolved?: string): string[];
 /**
@@ -127,8 +128,8 @@ export declare function declarationChain(asked: string, resolved?: string): stri
  * dependency maps of `cwd`'s package.json. A USABLE declaration always wins;
  * only if none of the names has one does an unusable declaration (a dist-tag or
  * a non-registry protocol) come back, so the caller can tell "declared as
- * `latest`" apart from "not declared at all" — two different facts that used to
- * produce the same sentence. Returns null when no name appears anywhere, or the
+ * `latest`" apart from "not declared at all" — two different facts that would
+ * otherwise produce the same sentence. Returns null when no name appears anywhere, or the
  * package.json is missing or unparseable. Best-effort; never throws.
  */
 export declare function findDeclaration(names: string[], cwd: string): Declaration | null;
@@ -165,10 +166,9 @@ export declare function buildVersionBanner(pin: AutoInstallPin | undefined, reso
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
 /**
- * Options rather than a positional tail: `signal` and `versionRange` sat adjacent,
- * and reaching the range meant writing `undefined` into the signal slot — which is
- * exactly how the primary acquisition path lost its abort signal while the hop path
- * kept it.
+ * An options object, not a positional tail. Two adjacent optionals mean reaching
+ * the second requires writing `undefined` into the first — and an abort signal
+ * dropped that way is not a type error, so nothing catches it.
  */
 export interface AutoInstallOptions {
     signal?: AbortSignal | undefined;
@@ -215,42 +215,25 @@ export interface AcquireInput {
  * `not_installed` install it — at the range the PROJECT declares when it declares
  * one — then resolve again from the install dir.
  *
- * One statement of the ladder, for both callers. It was written twice: inline in
- * `docsRaw` for the requested package, and in `tryResolveOrInstall` for each hop
- * of the type-redirect chain — and the copies had drifted on all three things
- * that matter.
+ * ONE statement of the ladder, for both callers: `docsRaw` for the requested
+ * package, and `tryResolveOrInstall` for each hop of the type-redirect chain.
+ * Three things must come out the same on either path, and each is silent when it
+ * does not — no test fails, the answer just gets worse:
  *
- *  - The abort signal. The hop copy passed it; the primary copy passed a bare
- *    `undefined` placeholder to reach the fourth positional, while
- *    `DocsRawInput.signal` was honoured on either side of that call. So a user
- *    cancel during the MAIN `npm install` of a model-chosen package was not
- *    delivered. `runAutoInstall` takes an options object now, so a hole like that
- *    cannot be typed.
- *  - The version pin. `findDeclaredRange` had exactly one call site — the primary
- *    copy. The hop copy installed `latest` unconditionally, on the hop most likely
- *    to be the declared one: `declarationChain` exists precisely because "a
- *    project that uses Bun declares `@types/bun`, not `bun`".
- *  - The provenance. `autoInstalled`/`autoInstallPin` were locals of `docsRaw`, so
- *    a package acquired only through a hop reported neither and got no version
- *    banner.
+ *  - the abort signal reaching the `npm install`, so a user cancel is delivered;
+ *  - the version pin, so a hop installs the project's declared range rather than
+ *    `latest` — and the hop is the LIKELIER one to be declared, since a project
+ *    that uses Bun declares `@types/bun`, not `bun`;
+ *  - the provenance (`autoInstalled` and the pin), without which a package
+ *    acquired only through a hop gets no version banner.
  *
- * CONTEXT.md records the redirect WALK as unified (`resolveTypeSource`) and its
- * `resolveHop` seam as "the one thing its two call sites disagree about". They
- * should disagree only about WHETHER to install, never about HOW.
+ * The redirect WALK itself is `resolveTypeSource` in docs-resolve.ts. Its two call
+ * sites should differ only about WHETHER to install, never about HOW.
  */
 export declare function acquirePackage(input: AcquireInput): Promise<AcquireOutcome>;
 export declare function docsRaw(input: DocsRawInput): Promise<DocsRawResult>;
 export declare function docsFocused(input: DocsFocusedInput): Promise<DocsFocusedResult>;
 export declare function buildPrompt(pkg: ResolvedPackage, query: string, content: string): string;
-/** Thin wrapper so existing callers using the pkg-based signature still work. */
-/**
- * The provenance header a docs answer carries. Takes the HEADER, not a package:
- * the whole body is one string, and the project-source path — which has no
- * package — used to fabricate a `ResolvedPackage`
- * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
- * this call compile, with three of the five fields existing only for that.
- */
-/** The header for an npm package answer. */
 /**
  * The PACKAGE corpus row: an npm package's `.d.ts` + README chunks.
  *
@@ -258,4 +241,5 @@ export declare function buildPrompt(pkg: ResolvedPackage, query: string, content
  * prompt and the header name the exact `name@version` that was read.
  */
 export declare function packageCorpus(pkg: ResolvedPackage): DocsCorpus;
+/** The provenance line that leads a package answer. */
 export declare function packageHeader(pkg: ResolvedPackage): string;

package/dist/workers/docs-core.js

@@ -10,6 +10,7 @@ import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { runChild } from '../shared/child-process.js';
 import { docsLookup } from './docs-lookup.js';
 import { buildExtractionPrompt } from './abstention.js';
+import {} from '../shared/child-output.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
 const DEFAULT_LIMIT = PACKAGE_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
@@ -45,9 +46,10 @@ function isUsableRange(range) {
  * The names a declaration for `asked` can honestly live under, nearest first:
  * the package itself, its DefinitelyTyped package, and the terminal the type
  * resolution chain landed on. A project that uses Bun declares `@types/bun`, not
- * `bun`; asking only about the terminal `bun-types` finds nothing at all, which
- * is how 35 of run 20's 48 banners came to report on a package nobody asked
- * about.
+ * `bun`; asking only about the terminal `bun-types` finds nothing at all, so a
+ * banner keyed on the terminal would report on a package nobody asked about. The
+ * terminal is deduped: `declarationChain('hono', 'hono')` is
+ * `['hono', '@types/hono']`.
  */
 export function declarationChain(asked, resolved) {
     const out = [asked];
@@ -63,8 +65,8 @@ export function declarationChain(asked, resolved) {
  * dependency maps of `cwd`'s package.json. A USABLE declaration always wins;
  * only if none of the names has one does an unusable declaration (a dist-tag or
  * a non-registry protocol) come back, so the caller can tell "declared as
- * `latest`" apart from "not declared at all" — two different facts that used to
- * produce the same sentence. Returns null when no name appears anywhere, or the
+ * `latest`" apart from "not declared at all" — two different facts that would
+ * otherwise produce the same sentence. Returns null when no name appears anywhere, or the
  * package.json is missing or unparseable. Best-effort; never throws.
  */
 export function findDeclaration(names, cwd) {
@@ -187,9 +189,7 @@ export async function runAutoInstall(spawn, packageName, opts = {}) {
     // `--ignore-scripts` is not optional here. The package NAME is model-chosen —
     // it comes out of a worker's question, or out of a `/// <reference types="X" />`
     // line in someone else's declaration file — so a hallucinated or typosquatted
-    // name would otherwise run its preinstall/postinstall as the user. This cache
-    // has already run install hooks for `node`, `argon2`, `onnxruntime-node` and
-    // `sharp`, next to fetched names like `app.ts`, `pkg.json` and `tsconfig.json`.
+    // name would otherwise run its preinstall/postinstall hooks as the user.
     // Nothing is lost: the docs worker only ever READS `.d.ts` files and the README
     // out of the installed tree, and those ship in the tarball.
     const result = await runChild(spawn, {
@@ -210,28 +210,20 @@ export async function runAutoInstall(spawn, packageName, opts = {}) {
  * `not_installed` install it — at the range the PROJECT declares when it declares
  * one — then resolve again from the install dir.
  *
- * One statement of the ladder, for both callers. It was written twice: inline in
- * `docsRaw` for the requested package, and in `tryResolveOrInstall` for each hop
- * of the type-redirect chain — and the copies had drifted on all three things
- * that matter.
+ * ONE statement of the ladder, for both callers: `docsRaw` for the requested
+ * package, and `tryResolveOrInstall` for each hop of the type-redirect chain.
+ * Three things must come out the same on either path, and each is silent when it
+ * does not — no test fails, the answer just gets worse:
  *
- *  - The abort signal. The hop copy passed it; the primary copy passed a bare
- *    `undefined` placeholder to reach the fourth positional, while
- *    `DocsRawInput.signal` was honoured on either side of that call. So a user
- *    cancel during the MAIN `npm install` of a model-chosen package was not
- *    delivered. `runAutoInstall` takes an options object now, so a hole like that
- *    cannot be typed.
- *  - The version pin. `findDeclaredRange` had exactly one call site — the primary
- *    copy. The hop copy installed `latest` unconditionally, on the hop most likely
- *    to be the declared one: `declarationChain` exists precisely because "a
- *    project that uses Bun declares `@types/bun`, not `bun`".
- *  - The provenance. `autoInstalled`/`autoInstallPin` were locals of `docsRaw`, so
- *    a package acquired only through a hop reported neither and got no version
- *    banner.
+ *  - the abort signal reaching the `npm install`, so a user cancel is delivered;
+ *  - the version pin, so a hop installs the project's declared range rather than
+ *    `latest` — and the hop is the LIKELIER one to be declared, since a project
+ *    that uses Bun declares `@types/bun`, not `bun`;
+ *  - the provenance (`autoInstalled` and the pin), without which a package
+ *    acquired only through a hop gets no version banner.
  *
- * CONTEXT.md records the redirect WALK as unified (`resolveTypeSource`) and its
- * `resolveHop` seam as "the one thing its two call sites disagree about". They
- * should disagree only about WHETHER to install, never about HOW.
+ * The redirect WALK itself is `resolveTypeSource` in docs-resolve.ts. Its two call
+ * sites should differ only about WHETHER to install, never about HOW.
  */
 export async function acquirePackage(input) {
     const { name, cwd, spawn, resolvePackage, signal } = input;
@@ -285,10 +277,9 @@ async function tryResolveOrInstall(name, cwd, spawn, resolvePackage, signal, onA
  *  hops resolve through the auto-installing lookup, so a declaration package that is
  *  declared but not yet on disk is fetched rather than abandoned. */
 async function resolveTypeSourceForDocs(pkg, requested, cwd, spawn, resolvePackage, signal) {
-    // A package acquired ONLY through a hop used to report neither `autoInstalled`
-    // nor a pin, so `pi-worker-docs` emitted no version banner for it — while the
-    // banner's own text ("only its types are, as `@types/bun` `^1.2`") claims a
-    // range as provenance. Report the last hop that actually installed.
+    // A package acquired ONLY through a hop reports neither `autoInstalled` nor a
+    // pin unless this runs, so pi-worker-docs would emit no version banner for it.
+    // Report the last hop that actually installed.
     let installed = false;
     let pin;
     const out = await resolveTypeSource(pkg, extractParentPackage(requested), next => tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal, hopPin => {
@@ -317,8 +308,7 @@ export async function docsRaw(input) {
     }).catch(() => null);
     // Step 1: acquire the package — resolve, or install-at-the-declared-range and
     // resolve again. The ladder is `acquirePackage`; this maps its stages onto the
-    // rich error results the docs tool reports. `input.signal` now reaches the
-    // install, which it never did while the range was a fourth positional.
+    // rich error results the docs tool reports.
     const got = await acquirePackage({
         name: requested,
         cwd: input.cwd,
@@ -598,16 +588,6 @@ export function buildPrompt(pkg, query, content) {
         content
     });
 }
-// ─── Backward-compatible wrappers (thin — delegates to shared/) ─────────────
-/** Thin wrapper so existing callers using the pkg-based signature still work. */
-/**
- * The provenance header a docs answer carries. Takes the HEADER, not a package:
- * the whole body is one string, and the project-source path — which has no
- * package — used to fabricate a `ResolvedPackage`
- * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
- * this call compile, with three of the five fields existing only for that.
- */
-/** The header for an npm package answer. */
 /**
  * The PACKAGE corpus row: an npm package's `.d.ts` + README chunks.
  *
@@ -622,6 +602,7 @@ export function packageCorpus(pkg) {
         abortedMessage: 'Docs lookup aborted.'
     };
 }
+/** The provenance line that leads a package answer. */
 export function packageHeader(pkg) {
     return `Per ${pkg.name}@${pkg.version}:`;
 }

package/dist/workers/docs-index.js

@@ -78,9 +78,10 @@ function ingestBody(cache, pkg, contentHash) {
     let filesIngested = 0;
     const insertChunk = cache.db.prepare('INSERT INTO chunks (name, version, file_path, kind, content) VALUES (?, ?, ?, ?, ?)');
     for (const abs of files.dts) {
-        // Store the file identifier POSIX-style so indexed docs are identical
-        // across platforms (this value is a model-facing label, never re-joined
-        // to the filesystem — node reads forward slashes fine on Windows too).
+        // Normalise the separator before storing, so the same package indexes to
+        // the same rows whatever built the path. The value is a MODEL-FACING
+        // label: chunkDeclarations turns it into the chunk's `// <path>` header,
+        // and nothing ever joins it back to the filesystem.
         const rel = path.relative(pkg.root, abs).replace(/\\/g, '/');
         let raw;
         try {

package/dist/workers/docs-lookup.d.ts

@@ -1,28 +1,20 @@
 /**
  * The docs TAIL — concatenate the chunks, extract against them, verify the
- * citation, format the answer — written once, with the corpus as a row.
+ * citation, format the answer — written once, with the corpus as a row. Its three
+ * callers are pi-worker-docs' project arm, its package arm, and `docsFocused` in
+ * docs-core.
  *
- * WHY. This sequence existed three times: the project-source arm of
- * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
- * channel proves the shape is avoidable — `fetchFocused` is one core and
- * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
- * the same job over two corpora.
- *
- * The copies had drifted, in the place hand-flattening always drifts: the
- * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
- * paths keep — so a package that was auto-installed and then failed to re-resolve
- * lost the `versionSource`/`declaredRange` provenance the last defect in this
- * area was about.
- *
- * A CORPUS is what genuinely varies: the prompt, the header the answer is
- * introduced by, and what an abort of it is called. Everything a corpus does NOT
- * vary — where the content comes from, the version banner, the type-only
- * detector, the details bag — stays with its caller, because those differ in kind
- * and not in value.
+ * A CORPUS is exactly what varies between them, and it is three fields: the
+ * prompt, the header the answer is introduced by, and what an abort is called.
+ * Everything a corpus does NOT vary — where the content comes from, the version
+ * banner, the type-only detector, the details bag — stays with the caller,
+ * because those differ in kind rather than in value.
  */
 import type { SpawnFn } from '../shared/child-process.js';
 import { type FocusedAnswer, type FocusedFailure } from './focused-extractor.js';
-/** The two corpora a docs lookup can read. A third (`page`) already has a prompt. */
+/** The two corpora a docs lookup can read. A fetched `page` is a third corpus in
+ *  spirit, but it lives on the fetch channel: fetch-core builds its own prompt and
+ *  never comes through here. */
 export type DocsCorpusId = 'package' | 'project';
 export interface DocsCorpus {
     id: DocsCorpusId;
@@ -65,8 +57,9 @@ export type DocsLookup = {
 /**
  * Run one docs lookup over already-retrieved chunks.
  *
- * The citation is verified against exactly the text that was prompted with — the
- * concatenation, not a superset. (`fetch` is the one site that verifies against a
- * superset; see `FocusedRequest.verifyAgainst`.)
+ * The citation is verified against exactly the text that was prompted with: the
+ * `\n\n`-joined chunks are passed as BOTH the prompt content and `verifyAgainst`.
+ * fetch-core is the only call site in this repo that passes a superset instead —
+ * see `FocusedRequest.verifyAgainst`.
  */
 export declare function docsLookup(input: DocsLookupInput): Promise<DocsLookup>;

package/dist/workers/docs-lookup.js

@@ -1,33 +1,24 @@
 /**
  * The docs TAIL — concatenate the chunks, extract against them, verify the
- * citation, format the answer — written once, with the corpus as a row.
+ * citation, format the answer — written once, with the corpus as a row. Its three
+ * callers are pi-worker-docs' project arm, its package arm, and `docsFocused` in
+ * docs-core.
  *
- * WHY. This sequence existed three times: the project-source arm of
- * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
- * channel proves the shape is avoidable — `fetchFocused` is one core and
- * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
- * the same job over two corpora.
- *
- * The copies had drifted, in the place hand-flattening always drifts: the
- * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
- * paths keep — so a package that was auto-installed and then failed to re-resolve
- * lost the `versionSource`/`declaredRange` provenance the last defect in this
- * area was about.
- *
- * A CORPUS is what genuinely varies: the prompt, the header the answer is
- * introduced by, and what an abort of it is called. Everything a corpus does NOT
- * vary — where the content comes from, the version banner, the type-only
- * detector, the details bag — stays with its caller, because those differ in kind
- * and not in value.
+ * A CORPUS is exactly what varies between them, and it is three fields: the
+ * prompt, the header the answer is introduced by, and what an abort is called.
+ * Everything a corpus does NOT vary — where the content comes from, the version
+ * banner, the type-only detector, the details bag — stays with the caller,
+ * because those differ in kind rather than in value.
  */
 import { formatResultText } from '../shared/child-output.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 /**
  * Run one docs lookup over already-retrieved chunks.
  *
- * The citation is verified against exactly the text that was prompted with — the
- * concatenation, not a superset. (`fetch` is the one site that verifies against a
- * superset; see `FocusedRequest.verifyAgainst`.)
+ * The citation is verified against exactly the text that was prompted with: the
+ * `\n\n`-joined chunks are passed as BOTH the prompt content and `verifyAgainst`.
+ * fetch-core is the only call site in this repo that passes a superset instead —
+ * see `FocusedRequest.verifyAgainst`.
  */
 export async function docsLookup(input) {
     const content = input.chunks.map(c => c.content).join('\n\n');

package/dist/workers/docs-project.d.ts

@@ -7,14 +7,20 @@ export declare function cwdKey(cwd: string): string;
 /**
  * Which source files make up the project.
  *
- * `git ls-files` is the source of truth when there is one — it already knows
+ * `git ls-files` is the source of truth whenever it answers: it already knows
  * what is tracked and what `.gitignore` excludes, which no hand-rolled walk gets
- * right — and the walk is the fallback for a directory that is not a repo.
+ * right. `walkTsFiles` is the fallback, and it is reached in TWO cases — no git
+ * repo, and a repo where git matched nothing.
  *
- * Injectable through `projectDocsRaw` because it is the only unmockable
- * dependency left in the docs cluster: without a seam, ANY test of the project
- * path needs a real temp directory, real files on disk, and a machine where git
- * is installed and the temp dir is not itself inside a repo.
+ * The two disagree in both directions, so which one ran is observable:
+ *   - git honours `.gitignore`; the walk does not, so a repo whose only `.ts`
+ *     files are all gitignored falls through and indexes them anyway.
+ *   - the walk skips node_modules, .git, dist, build and coverage outright; git
+ *     lists whatever those contain unless `.gitignore` says otherwise.
+ *
+ * Injectable through `projectDocsRaw` because without a seam, ANY test of the
+ * project path needs a real temp directory, real files on disk, git installed,
+ * and a temp dir that is not itself inside a repo.
  */
 export declare function getProjectFiles(cwd: string): string[];
 export declare function getMaxMtime(files: string[]): string;
@@ -54,8 +60,8 @@ export declare function buildProjectPrompt(projectName: string, query: string, c
 /**
  * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
  *
- * Named after the project so a reader of the answer can tell a project-source
- * citation from a package one at a glance — they are read and cited the same way
- * and mean very different things.
+ * The header reads `Per <name> (project source):`, where the package corpus reads
+ * `Per <name>@<version>:`. Both are read and cited the same way and mean very
+ * different things, so the answer has to say which it came from.
  */
 export declare function projectCorpus(projectName: string): DocsCorpus;

package/dist/workers/docs-project.js

@@ -22,14 +22,20 @@ export function cwdKey(cwd) {
 /**
  * Which source files make up the project.
  *
- * `git ls-files` is the source of truth when there is one — it already knows
+ * `git ls-files` is the source of truth whenever it answers: it already knows
  * what is tracked and what `.gitignore` excludes, which no hand-rolled walk gets
- * right — and the walk is the fallback for a directory that is not a repo.
+ * right. `walkTsFiles` is the fallback, and it is reached in TWO cases — no git
+ * repo, and a repo where git matched nothing.
  *
- * Injectable through `projectDocsRaw` because it is the only unmockable
- * dependency left in the docs cluster: without a seam, ANY test of the project
- * path needs a real temp directory, real files on disk, and a machine where git
- * is installed and the temp dir is not itself inside a repo.
+ * The two disagree in both directions, so which one ran is observable:
+ *   - git honours `.gitignore`; the walk does not, so a repo whose only `.ts`
+ *     files are all gitignored falls through and indexes them anyway.
+ *   - the walk skips node_modules, .git, dist, build and coverage outright; git
+ *     lists whatever those contain unless `.gitignore` says otherwise.
+ *
+ * Injectable through `projectDocsRaw` because without a seam, ANY test of the
+ * project path needs a real temp directory, real files on disk, git installed,
+ * and a temp dir that is not itself inside a repo.
  */
 export function getProjectFiles(cwd) {
     try {
@@ -93,7 +99,8 @@ export function ensureProjectIndexed(cache, name, version, files, cwd) {
     const t0 = Date.now();
     cache.db.exec('BEGIN IMMEDIATE');
     try {
-        // Clear all old versions of this project
+        // Delete by NAME with no version: unlike the package index, a project
+        // keeps only its newest max-mtime version, so every older one goes.
         cache.db.prepare('DELETE FROM chunks WHERE name = ?').run(name);
         cache.db.prepare('DELETE FROM packages WHERE name = ?').run(name);
         const insertChunk = cache.db.prepare('INSERT INTO chunks (name, version, file_path, kind, content) VALUES (?, ?, ?, ?, ?)');
@@ -211,9 +218,9 @@ export function buildProjectPrompt(projectName, query, content) {
 /**
  * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
  *
- * Named after the project so a reader of the answer can tell a project-source
- * citation from a package one at a glance — they are read and cited the same way
- * and mean very different things.
+ * The header reads `Per <name> (project source):`, where the package corpus reads
+ * `Per <name>@<version>:`. Both are read and cited the same way and mean very
+ * different things, so the answer has to say which it came from.
  */
 export function projectCorpus(projectName) {
     return {