@mjasnikovs/pi-task 0.40.14 → 0.40.26

package/dist/workers/abstention.js

@@ -39,15 +39,27 @@ export function abstentionSentence(kind) {
  * Matches any corpus's abstention. Built from the same table the prompts read, so
  * adding a corpus cannot leave a matcher behind.
  *
- * A SUBSTRING match, unlike fetch-core's separate `not covered by this page`
- * sentinel, which is anchored. The instructions differ, so the matchers must. The
- * "not covered" rule asks for a partial answer that NAMES what is missing, so a
- * sourced answer legitimately contains the phrase and only an anchored match keeps
- * it from being filed as a coverage miss. Rule 4 below asks for this sentinel
- * INSTEAD of an answer, so nothing sourced can contain it, and a substring match
- * still catches a child that wraps the sentence in an explanation.
+ * ANCHORED, and it was a substring match until it was measured. The docstring here
+ * used to say "rule 4 asks for this sentinel INSTEAD of an answer, so nothing
+ * sourced can contain it". That was true when it was written and defect 15's fix
+ * made it false: rule 4 now ends with "answer the parts <content> covers, and name
+ * the parts it does not", and a child naming the missing part reaches for the
+ * phrase the same prompt just taught it.
+ *
+ * Six of 73 flagged abstentions across seven runs were substantial answers that
+ * named a gap at the end — full signatures for `oneshot`, `TcpListener::bind`,
+ * `eitherDecode`, a whole zod schema — every one scored as a non-answer. Rule 4
+ * asks for the sentence ALONE, so leading with it is the abstention and trailing it
+ * behind real content is the partial answer defect 15 exists to produce.
+ *
+ * The leading `<answer>` tag is admitted because some consumers see the child's raw
+ * output rather than the parsed body.
+ *
+ * The cost, stated: a child that writes prose first and only then declines outright
+ * now scores as an answer. Across 243 recorded answers that shape does not occur —
+ * all 67 real abstentions lead with the sentence.
  */
-const ABSTENTION_RE = new RegExp(`unclear\\s+from\\s+this\\s+(${Object.values(NOUNS).join('|')})\\b`, 'i');
+const ABSTENTION_RE = new RegExp(`^(?:\\s*<answer>)?[\\s"'\`\\-*]*unclear\\s+from\\s+this\\s+(${Object.values(NOUNS).join('|')})\\b`, 'i');
 /** True when the child declined to answer rather than answering. See the header
  *  for the two decisions this drives. */
 export function isAbstention(text) {

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

@@ -34,6 +34,19 @@ export declare const MAX_CHUNK_BYTES: number;
  * defines `fetch`.
  */
 export declare const DECL_SPLIT_RE: RegExp;
+/**
+ * Where a member of an oversized declaration begins — the same heads, indented.
+ *
+ * `declare module "bun" { … }` is ONE top-level declaration holding a whole module,
+ * so `DECL_SPLIT_RE` matches once and everything after it was cut at byte offsets.
+ * That shape is rare and enormous: 3.8% of indexed chunks sat at the cap and held
+ * 51.1% of all indexed bytes, 86.8% of `@types/node`'s and 78.1% of `bun-types`'.
+ *
+ * Only reached when a declaration does not fit. A member split applied to every
+ * declaration would cut an interface away from its own members, which is the thing
+ * `DECL_SPLIT_RE` exists to prevent.
+ */
+export declare const MEMBER_SPLIT_RE: RegExp;
 /** Where a README section starts. */
 export declare const README_SPLIT_RE: RegExp;
 /**
@@ -60,6 +73,18 @@ export declare function splitAtMatches(text: string, re: RegExp): string[];
  * possible hallucination. Only reachable on non-ASCII text past the chunk ceiling.
  */
 export declare function sliceBytes(s: string, maxBytes: number): string[];
+/**
+ * Slice a body that will not fit, giving every piece the same header.
+ *
+ * The header was applied once and then sliced, so only the first piece said where
+ * it came from: 487 of 12,815 indexed chunks had no provenance line, 53% of
+ * `@types/node`'s and 22% of `bun-types`'. A `node:url` query for `fileURLToPath`
+ * came back as two 8,192-byte pieces that began mid-sentence inside a doc comment
+ * and named no file.
+ *
+ * The cap counts the header, so the body budget is what is left after it.
+ */
+export declare function headedSlices(header: string, body: string, maxBytes: number): string[];
 /**
  * Chunk a declaration file, one chunk per declaration, each labelled with the
  * file it came from.
@@ -73,6 +98,19 @@ export declare function sliceBytes(s: string, maxBytes: number): string[];
  * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
  * both the project corpus and npm packages are written in.
  */
-export declare function chunkDeclarations(content: string, relPath: string, splitRe?: RegExp, commentPrefix?: string): string[];
+export declare function chunkDeclarations(content: string, relPath: string, splitRe?: RegExp, commentPrefix?: string, memberRe?: RegExp): string[];
+/**
+ * Cut a declaration that does not fit at its own member boundaries, keeping the
+ * line that says what it is a member OF.
+ *
+ * Without that line a piece of `declare module "bun"` is an anonymous list of
+ * functions: a `Bun.file` question came back carrying slices about S3 ETags and
+ * tar archives, because bm25 was matching words in the middles of byte cuts that
+ * shared no subject.
+ *
+ * Byte slicing stays as the floor. A single member wider than the cap — one
+ * function with a 20 KB doc comment — still has to be cut somewhere.
+ */
+export declare function splitOversized(header: string, body: string, memberRe: RegExp): string[];
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */
 export declare function chunkReadme(content: string): string[];

package/dist/workers/docs-chunk.js

@@ -34,6 +34,19 @@ export const MAX_CHUNK_BYTES = 8 * 1024;
  * defines `fetch`.
  */
 export const DECL_SPLIT_RE = /^(?:export\s+)?(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
+/**
+ * Where a member of an oversized declaration begins — the same heads, indented.
+ *
+ * `declare module "bun" { … }` is ONE top-level declaration holding a whole module,
+ * so `DECL_SPLIT_RE` matches once and everything after it was cut at byte offsets.
+ * That shape is rare and enormous: 3.8% of indexed chunks sat at the cap and held
+ * 51.1% of all indexed bytes, 86.8% of `@types/node`'s and 78.1% of `bun-types`'.
+ *
+ * Only reached when a declaration does not fit. A member split applied to every
+ * declaration would cut an interface away from its own members, which is the thing
+ * `DECL_SPLIT_RE` exists to prevent.
+ */
+export const MEMBER_SPLIT_RE = /^[ \t]+(?:export\s+)?(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
 /** Where a README section starts. */
 export const README_SPLIT_RE = /^#{1,2} /m;
 /**
@@ -106,6 +119,29 @@ export function sliceBytes(s, maxBytes) {
         out.push(buf.toString('utf8'));
     return out;
 }
+/**
+ * Slice a body that will not fit, giving every piece the same header.
+ *
+ * The header was applied once and then sliced, so only the first piece said where
+ * it came from: 487 of 12,815 indexed chunks had no provenance line, 53% of
+ * `@types/node`'s and 22% of `bun-types`'. A `node:url` query for `fileURLToPath`
+ * came back as two 8,192-byte pieces that began mid-sentence inside a doc comment
+ * and named no file.
+ *
+ * The cap counts the header, so the body budget is what is left after it.
+ */
+export function headedSlices(header, body, maxBytes) {
+    const prefixed = `${header}\n${body}`;
+    if (Buffer.byteLength(prefixed, 'utf8') <= maxBytes)
+        return [prefixed];
+    const room = maxBytes - Buffer.byteLength(`${header}\n`, 'utf8');
+    // A header that fills the cap on its own leaves no room, and `sliceBytes` with a
+    // non-positive cap never shrinks its buffer. Slice the prefixed string instead:
+    // the first piece still names the source, which is all the header buys.
+    if (room <= 0)
+        return sliceBytes(prefixed, maxBytes);
+    return sliceBytes(body, room).map(slice => `${header}\n${slice}`);
+}
 /**
  * Chunk a declaration file, one chunk per declaration, each labelled with the
  * file it came from.
@@ -119,23 +155,48 @@ export function sliceBytes(s, maxBytes) {
  * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
  * both the project corpus and npm packages are written in.
  */
-export function chunkDeclarations(content, relPath, splitRe = DECL_SPLIT_RE, commentPrefix = '//') {
+export function chunkDeclarations(content, relPath, splitRe = DECL_SPLIT_RE, commentPrefix = '//', memberRe = MEMBER_SPLIT_RE) {
     const chunks = [];
+    const header = `${commentPrefix} ${relPath}`;
     for (const part of splitAtMatches(content, new RegExp(splitRe.source, 'gm'))) {
         const trimmed = part.trim();
         if (!trimmed)
             continue;
-        const prefixed = `${commentPrefix} ${relPath}\n${trimmed}`;
-        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
-            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
-                chunks.push(slice);
-        }
-        else {
-            chunks.push(prefixed);
-        }
+        chunks.push(...splitOversized(header, trimmed, memberRe));
     }
     return chunks;
 }
+/**
+ * Cut a declaration that does not fit at its own member boundaries, keeping the
+ * line that says what it is a member OF.
+ *
+ * Without that line a piece of `declare module "bun"` is an anonymous list of
+ * functions: a `Bun.file` question came back carrying slices about S3 ETags and
+ * tar archives, because bm25 was matching words in the middles of byte cuts that
+ * shared no subject.
+ *
+ * Byte slicing stays as the floor. A single member wider than the cap — one
+ * function with a 20 KB doc comment — still has to be cut somewhere.
+ */
+export function splitOversized(header, body, memberRe) {
+    if (Buffer.byteLength(`${header}\n${body}`, 'utf8') <= MAX_CHUNK_BYTES) {
+        return [`${header}\n${body}`];
+    }
+    const parts = splitAtMatches(body, new RegExp(memberRe.source, 'gm'));
+    if (parts.length < 2)
+        return headedSlices(header, body, MAX_CHUNK_BYTES);
+    // The first part carries the enclosing head; every later one has to be told.
+    const enclosing = parts[0].split('\n')[0].trim();
+    const out = [];
+    for (const [i, part] of parts.entries()) {
+        const trimmed = part.replace(/\s+$/, '');
+        if (!trimmed.trim())
+            continue;
+        const withContext = i === 0 ? trimmed : `${enclosing}\n${trimmed}`;
+        out.push(...headedSlices(header, withContext, MAX_CHUNK_BYTES));
+    }
+    return out;
+}
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */
 export function chunkReadme(content) {
     const chunks = [];
@@ -146,14 +207,7 @@ export function chunkReadme(content) {
             continue;
         const headingMatch = /^(#{1,2}) (.+)$/m.exec(trimmed);
         const heading = headingMatch ? headingMatch[2] : '(intro)';
-        const prefixed = `<!-- README: ${heading} -->\n${trimmed}`;
-        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
-            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
-                chunks.push(slice);
-        }
-        else {
-            chunks.push(prefixed);
-        }
+        chunks.push(...headedSlices(`<!-- README: ${heading} -->`, trimmed, MAX_CHUNK_BYTES));
     }
     return chunks;
 }

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

@@ -107,6 +107,12 @@ export interface EcosystemProfile {
     surface: (content: string) => string;
     /** Where a declaration begins, so a chunk never splits a signature. */
     declSplitRe: RegExp;
+    /**
+     * Where a MEMBER of a declaration begins — the same heads, indented. Reached
+     * only when one declaration does not fit a chunk, which in npm is
+     * `declare module "bun" { … }` holding a whole module.
+     */
+    memberSplitRe: RegExp;
     /**
      * The keywords that INTRODUCE a named type in this language, for finding the
      * chunk that defines a name rather than the many that use it.

package/dist/workers/docs-ecosystems.js

@@ -19,10 +19,10 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { runAutoInstall, findDeclaredRange, extractParentPackage, resolveTypeSourceForDocs, getDocsModulesDir } from './docs-core.js';
 import { resolvePackage, isDtsFile, isValidModuleName } from './docs-resolve.js';
-import { DECL_SPLIT_RE } from './docs-chunk.js';
+import { DECL_SPLIT_RE, MEMBER_SPLIT_RE } from './docs-chunk.js';
 import { npmVersionLookup } from './npm-version.js';
-import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, manifestCrates, cargoExportGap, cargoContentFingerprint, cargoSupplementCandidates, CARGO_DECL_SPLIT_RE } from './eco-cargo.js';
-import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, supplementCandidates, hackageExportGap, hackageContentFingerprint, findCabalTarball, cachedVersions, resolvedVersions, manifestPackages, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS } from './eco-hackage.js';
+import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, manifestCrates, cargoExportGap, cargoContentFingerprint, cargoSupplementCandidates, CARGO_DECL_SPLIT_RE, CARGO_MEMBER_SPLIT_RE } from './eco-cargo.js';
+import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, supplementCandidates, hackageExportGap, hackageContentFingerprint, findCabalTarball, cachedVersions, resolvedVersions, manifestPackages, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS, HACKAGE_MEMBER_SPLIT_RE } from './eco-hackage.js';
 import { runChild } from '../shared/child-process.js';
 /**
  * Is any of `names` present at `cwd` or above it?
@@ -134,6 +134,7 @@ export function npmProfile(hooks = {}) {
         // identity for a fingerprint to miss.
         contentFingerprint: () => String(npmSurface),
         declSplitRe: DECL_SPLIT_RE,
+        memberSplitRe: MEMBER_SPLIT_RE,
         typeKeywords: ['interface', 'type', 'class', 'enum'],
         commentPrefix: '//',
         // A nested node_modules is another package's surface, never this one's.
@@ -313,6 +314,7 @@ const cargoProfile = {
     // index as `insideTrait`. `contentFingerprint` is what covers its source.
     surface: content => rustSurface(content),
     declSplitRe: CARGO_DECL_SPLIT_RE,
+    memberSplitRe: CARGO_MEMBER_SPLIT_RE,
     typeKeywords: ['struct', 'trait', 'enum', 'type', 'union'],
     commentPrefix: '//',
     skipDirs: ['tests', 'benches', 'examples', 'target'],
@@ -429,6 +431,7 @@ const hackageProfile = {
     isSurfaceFile: isHaskellFile,
     surface: haskellSurface,
     declSplitRe: HACKAGE_DECL_SPLIT_RE,
+    memberSplitRe: HACKAGE_MEMBER_SPLIT_RE,
     typeKeywords: ['type', 'data', 'newtype', 'class'],
     commentPrefix: '--',
     skipDirs: HACKAGE_SKIP_DIRS,

package/dist/workers/docs-index.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {} from './docs-resolve.js';
-import { chunkDeclarations, chunkReadme, splitAtMatches } from './docs-chunk.js';
+import { chunkDeclarations, chunkReadme, splitAtMatches, headedSlices, splitOversized, MEMBER_SPLIT_RE } from './docs-chunk.js';
 import { ECOSYSTEMS } from './docs-ecosystems.js';
 const ZERO_SEP = Buffer.from([0]);
 /**
@@ -33,13 +33,27 @@ const ZERO_SEP = Buffer.from([0]);
  * have said so.
  */
 export function chunkerFingerprint() {
-    return `${String(splitAtMatches)}\u0000${String(chunkDeclarations)}\u0000${String(chunkReadme)}`;
+    return [
+        String(splitAtMatches),
+        String(chunkDeclarations),
+        String(chunkReadme),
+        // Both chunkers now delegate their slicing, so their own source would sit
+        // still through a change to where an oversized declaration is cut. That is
+        // the third fix to hide one level below a `String(fn)` here.
+        String(headedSlices),
+        String(splitOversized),
+        // The member split is per-ecosystem, and a profile's regex is not source
+        // this function can see. `declSplitRe` is already hashed beside it in
+        // computeContentHash; this puts its sibling there too.
+        MEMBER_SPLIT_RE.source
+    ].join('\u0000');
 }
 function computeContentHash(pkg, profile, supplements = []) {
     const hash = createHash('sha256');
     hash.update(Buffer.from(`${pkg.name}@${pkg.version}`, 'utf8'));
     hash.update(ZERO_SEP);
-    hash.update(Buffer.from(`${profile.declSplitRe.source}\u0000${profile.commentPrefix}`, 'utf8'));
+    hash.update(Buffer.from(`${profile.declSplitRe.source}\u0000${profile.memberSplitRe.source}`
+        + `\u0000${profile.commentPrefix}`, 'utf8'));
     hash.update(ZERO_SEP);
     hash.update(Buffer.from(chunkerFingerprint(), 'utf8'));
     hash.update(ZERO_SEP);
@@ -205,7 +219,7 @@ function ingestBody(cache, pkg, profile, contentHash, supplements = []) {
         catch {
             continue;
         }
-        const chunks = chunkDeclarations(profile.surface(raw), rel, profile.declSplitRe, profile.commentPrefix);
+        const chunks = chunkDeclarations(profile.surface(raw), rel, profile.declSplitRe, profile.commentPrefix, profile.memberSplitRe);
         if (!chunks.length)
             continue;
         filesIngested++;
@@ -236,7 +250,7 @@ function ingestBody(cache, pkg, profile, contentHash, supplements = []) {
             // wrong package is the bug this whole table exists for.
             const rel = `${sup.name}-${sup.version}/` + path.relative(sup.root, abs).replace(/\\/g, '/');
             const whole = gap.wholesale(rel, raw);
-            for (const c of chunkDeclarations(profile.surface(raw), rel, profile.declSplitRe, profile.commentPrefix)) {
+            for (const c of chunkDeclarations(profile.surface(raw), rel, profile.declSplitRe, profile.commentPrefix, profile.memberSplitRe)) {
                 if (!whole && !gap.fillsHole(c.replace(/^\S.*\n/, '')))
                     continue;
                 if (seen.has(c))

package/dist/workers/docs-project.js

@@ -174,7 +174,7 @@ export function ensureProjectIndexed(cache, name, version, files, cwd) {
             // `pi-worker-docs(".", …)` answers "no chunks" for the whole project.
             // Only the CHUNK BOUNDARY is language-specific.
             const profile = profileForFile(abs, profiles);
-            const chunks = chunkDeclarations(raw, rel, profile.declSplitRe, profile.commentPrefix);
+            const chunks = chunkDeclarations(raw, rel, profile.declSplitRe, profile.commentPrefix, profile.memberSplitRe);
             if (!chunks.length)
                 continue;
             filesIngested++;

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

@@ -30,12 +30,20 @@ export interface RetrieveOptions {
  *
  *   retrieval — does a chunk DEFINE the queried symbol?   91/101 -> 97/101,
  *               monotone to 50 and flat at 100, p = 0.0703
- *   answers   — does the extraction child answer at all?  67/94 -> 79/94,
- *               only-8 3, only-50 15, McNemar exact p = 0.0075
+ *   answers   — 67/94 -> 79/94, p = 0.0075 when first measured, and it DOES NOT
+ *               replicate. That run was block-ordered, which makes arm and
+ *               position the same variable; re-run as warm-up then ABBA it reads
+ *               159/206 -> 163/206, p = 0.5716, with both within-arm A/A controls
+ *               at p = 1.0000. The retrieval line above is what justifies 50.
  *
- * Abstention on the replay corpus falls 29% to 16%. The cost is +70% of retrieved
- * text, and `RETRIEVE_CONTENT_BUDGET` still bounds it — at 8 only 6 of 74 calls
- * reached that budget, so two thirds of it was never spent.
+ * The cost is +70% of retrieved text, 14,986 characters per call to 20,882, and
+ * `RETRIEVE_CONTENT_BUDGET` now binds where it did not: at 8 only 6 of 74 calls
+ * reached the budget, at 50 it is 90 of 103.
+ *
+ * Do not raise the budget to follow it. 24,000 -> 48,000 was measured the same
+ * balanced way and reads p = 0.1360 on answers and p = 0.2500 on defines. Three
+ * measurements now agree that retrieved VOLUME is not what makes this child
+ * answer; what the text IS, is.
  *
  * Changing either is still a retrieval-policy change, not a tidy-up.
  */
@@ -43,4 +51,22 @@ export declare const PACKAGE_RETRIEVE_LIMIT = 50;
 export declare const PROJECT_RETRIEVE_LIMIT = 50;
 /** Character budget for the assembled chunk text. The same for both corpora. */
 export declare const RETRIEVE_CONTENT_BUDGET = 24000;
+/**
+ * The type names the retrieved text declares MEMBERS as, whose own definitions
+ * are not in hand and which the query itself names — by the member or by the
+ * type.
+ *
+ * This is the alias hop. A package that types its public surface through
+ * interface aliases puts every real signature one declaration away from the name
+ * a query matches: hono writes `get: HandlerInterface<…>` in hono-base.d.ts and
+ * keeps the call signatures in `HandlerInterface`, in types.d.ts. BM25 ranks
+ * chunks independently, so retrieval lands on the alias and the extraction child
+ * sees a name where a signature should be. Measured on hono 4.13.5: three real
+ * lookups, three abstentions, and the definition in one chunk of 708.
+ *
+ * Ranking hops by frequency does not work — `Response` and the English word
+ * `The` both outrank `HandlerInterface` in the same text. What the query names
+ * is the signal.
+ */
+export declare function hopNames(text: string, tokens: string[]): string[];
 export declare function retrieveChunks(cache: CacheHandle, opts: RetrieveOptions): RetrievedChunk[];

package/dist/workers/docs-retrieve.js

@@ -7,12 +7,20 @@
  *
  *   retrieval — does a chunk DEFINE the queried symbol?   91/101 -> 97/101,
  *               monotone to 50 and flat at 100, p = 0.0703
- *   answers   — does the extraction child answer at all?  67/94 -> 79/94,
- *               only-8 3, only-50 15, McNemar exact p = 0.0075
+ *   answers   — 67/94 -> 79/94, p = 0.0075 when first measured, and it DOES NOT
+ *               replicate. That run was block-ordered, which makes arm and
+ *               position the same variable; re-run as warm-up then ABBA it reads
+ *               159/206 -> 163/206, p = 0.5716, with both within-arm A/A controls
+ *               at p = 1.0000. The retrieval line above is what justifies 50.
  *
- * Abstention on the replay corpus falls 29% to 16%. The cost is +70% of retrieved
- * text, and `RETRIEVE_CONTENT_BUDGET` still bounds it — at 8 only 6 of 74 calls
- * reached that budget, so two thirds of it was never spent.
+ * The cost is +70% of retrieved text, 14,986 characters per call to 20,882, and
+ * `RETRIEVE_CONTENT_BUDGET` now binds where it did not: at 8 only 6 of 74 calls
+ * reached the budget, at 50 it is 90 of 103.
+ *
+ * Do not raise the budget to follow it. 24,000 -> 48,000 was measured the same
+ * balanced way and reads p = 0.1360 on answers and p = 0.2500 on defines. Three
+ * measurements now agree that retrieved VOLUME is not what makes this child
+ * answer; what the text IS, is.
  *
  * Changing either is still a retrieval-policy change, not a tidy-up.
  */
@@ -25,6 +33,25 @@ export const RETRIEVE_CONTENT_BUDGET = 24_000;
 // backstop for a third caller that does not.
 const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
+/**
+ * Shortest query token that reaches the FTS query. Swept twice, and 2 stays.
+ *
+ * The first sweep put the peak at 3 — one gain, no losses — because no truth entry
+ * named a two-letter symbol and the metric could not see what 3 throws away. Two-
+ * letter tokens across every recorded query are mostly English filler (`to` 97,
+ * `of` 64, `in` 57), and mixed in with them are `v4` 13, `it` 47, `IO`, `fn`, `u8`.
+ *
+ * One entry for `bun:test`'s `it` was enough to reverse it:
+ *
+ *   min   without a 2-letter entry      with one
+ *    2       150/157                     151/159      <- peak
+ *    3       151/157   +1                150/159   -1
+ *    4       150/157                     146/159      p = 0.1797
+ *    5       134/157   p = 0.0015        131/159      p = 8.8e-5
+ *
+ * Raising it drops `v4` from a zod query, which is the token that distinguishes the
+ * major this whole test set exists to pin.
+ */
 const MIN_TOKEN_LEN = 2;
 /**
  * How many alias definitions one retrieval will chase. Three covers the observed
@@ -120,6 +147,10 @@ function enforceBudget(chunks, budget) {
             total += c.content.length;
             continue;
         }
+        // `break`, not `continue`, and it is load-bearing. Packing lower-ranked
+        // chunks into the gap left by an oversized one leaves less room in the
+        // SECOND enforceBudget, where the alias hops sit — and a dropped hop costs
+        // more than a gained tail chunk. Measured: defines 150/157 -> 149/157.
         if (total + c.content.length > budget)
             break;
         out.push(c);
@@ -144,7 +175,7 @@ function enforceBudget(chunks, budget) {
  * `The` both outrank `HandlerInterface` in the same text. What the query names
  * is the signal.
  */
-function hopNames(text, tokens) {
+export function hopNames(text, tokens) {
     const declared = new Set([...text.matchAll(TYPE_DECL_RE)].map(m => m[1]));
     const typeParams = new Set();
     for (const m of text.matchAll(TYPE_PARAMS_RE)) {

package/dist/workers/eco-cargo.d.ts

@@ -83,6 +83,8 @@ export declare function crateTarballUrl(name: string, version: string): string;
  * receiver type, carrying the next method's doc comment.
  */
 export declare const CARGO_DECL_SPLIT_RE: RegExp;
+/** The same heads, indented — a member of an oversized `impl` or `mod` block. */
+export declare const CARGO_MEMBER_SPLIT_RE: RegExp;
 interface Item {
     /** Doc comments and attributes immediately above the item. */
     pending: string;

package/dist/workers/eco-cargo.js

@@ -365,6 +365,8 @@ export function crateTarballUrl(name, version) {
  * receiver type, carrying the next method's doc comment.
  */
 export const CARGO_DECL_SPLIT_RE = /^(?:#\[[^\n]*\]\s*)*(?:pub\s+)?(?:async\s+|unsafe\s+|const\s+|extern\s+)*(?:fn|struct|enum|union|trait|type|impl|mod|const|static)\b/m;
+/** The same heads, indented — a member of an oversized `impl` or `mod` block. */
+export const CARGO_MEMBER_SPLIT_RE = /^[ \t]+(?:#\[[^\n]*\]\s*)*(?:pub\s+)?(?:async\s+|unsafe\s+|const\s+|extern\s+)*(?:fn|struct|enum|union|trait|type|impl|mod|const|static)\b/m;
 // `macro_rules!` carries its own terminator, so it sits OUTSIDE the `\b` — a word
 // boundary after `!` requires a word character next, and what follows is a space.
 const ITEM_HEAD_RE = /^(?:pub(?:\s*\([^)]*\))?\s+)?(?:default\s+|async\s+|unsafe\s+|const\s+|extern\s+"[^"]*"\s+|extern\s+)*((?:fn|struct|enum|union|trait|impl|mod|type|const|static|use)\b|macro_rules!)/;

package/dist/workers/eco-hackage.d.ts

@@ -67,6 +67,8 @@ export declare function resolveHackage(name: string, cwd: string, dirs: HackageR
 export declare function hackageLatest(name: string, fetchFn: typeof fetch, signal?: AbortSignal): Promise<NpmVersionInfo | null>;
 /** Where a Haskell declaration begins, so a chunk never splits a signature. */
 export declare const HACKAGE_DECL_SPLIT_RE: RegExp;
+/** The same heads, indented — a member of an oversized `class` or `instance`. */
+export declare const HACKAGE_MEMBER_SPLIT_RE: RegExp;
 /**
  * Reduce Haskell source to its public API surface: the module header with its
  * export list, every top-level type signature, every type and class

package/dist/workers/eco-hackage.js

@@ -303,6 +303,8 @@ export async function hackageLatest(name, fetchFn, signal) {
 // ── surface extraction ──────────────────────────────────────────────────────
 /** Where a Haskell declaration begins, so a chunk never splits a signature. */
 export const HACKAGE_DECL_SPLIT_RE = /^(?:[a-z_][\w']*\s*::|data\s|newtype\s|type\s|class\s|instance\s|pattern\s)/m;
+/** The same heads, indented — a member of an oversized `class` or `instance`. */
+export const HACKAGE_MEMBER_SPLIT_RE = /^[ \t]+(?:[a-z_][\w']*\s*::|data\s|newtype\s|type\s|class\s|instance\s|pattern\s)/m;
 const SIGNATURE_RE = /^[a-z_][\w']*(?:\s*,\s*[a-z_][\w']*)*\s*::/;
 const OPERATOR_SIGNATURE_RE = /^\([^)]+\)\s*::/;
 /** The same heads with the `::` wrapped onto the next line. */

package/dist/workers/pi-worker-docs.d.ts

@@ -12,6 +12,12 @@ interface DocsDetails {
     hitCache?: boolean;
     chunksRetrieved?: number;
     excerptVerified?: boolean;
+    /**
+     * The excerpt cites a word the source never wrote — a possible fabrication, as
+     * opposed to a quote stitched from several real spans. `excerptVerified: false`
+     * covers both and cannot tell them apart.
+     */
+    excerptFabricated?: boolean;
     childExitCode?: number;
     indexingMs?: number;
     indexedFiles?: number;
@@ -35,6 +41,12 @@ interface DocsDetails {
     /** The project-lookup budget for this attempt is spent, so the call was refused
      *  before any work. Only set when PI_TASK_PROJECT_DOCS_BUDGET is configured. */
     budgetSpent?: boolean;
+    /**
+     * The child declined to answer. Recorded HERE, at the one place the bare
+     * `<answer>` is in hand: the tool text a cache predicate is handed leads with a
+     * provenance header, and the anchored matcher scores that as a real answer.
+     */
+    abstained?: boolean;
 }
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
@@ -73,7 +85,17 @@ export declare function registerPiWorkerDocs(pi: ExtensionAPI, internals?: PiWor
  * assert against its own copy — green even after the shipped rule changed. Exported,
  * the test imports the rule it is checking.
  */
-export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerptVerified'>, text: string): boolean;
+/**
+ * Did the excerpt cite a word the source never wrote?
+ *
+ * `verified` is false for a stitched quote too, and the two must not share a gate:
+ * one is a possible fabrication and the other is what the extraction prompt asks
+ * for. Absent of a check, nothing was verified and nothing is claimed.
+ */
+export declare function excerptFabricated(check: {
+    absent: readonly string[];
+} | undefined): boolean;
+export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerptVerified' | 'excerptFabricated' | 'abstained'>): boolean;
 /** The docs cache key: a package's answer is per (module, question), with the question
  *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
  *  null for the project-source `.` lookup, which is never cached — the working tree

package/dist/workers/pi-worker-docs.js

@@ -218,7 +218,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 });
                 return workerAnswer(text, {
                     ...baseDetails,
-                    excerptVerified: verified
+                    excerptVerified: verified,
+                    excerptFabricated: excerptFabricated(extraction.excerptCheck),
+                    ...(isAbstention(extraction.answer) ? { abstained: true } : {})
                 });
             }
             // ── npm package lookup (existing path) ──────────────────────────
@@ -353,7 +355,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             return workerAnswer(text, {
                 ...baseDetails,
                 excerptVerified: verified,
-                ...(typeOnly.typeOnly ? { typeOnly: true } : {})
+                excerptFabricated: excerptFabricated(extraction.excerptCheck),
+                ...(typeOnly.typeOnly ? { typeOnly: true } : {}),
+                ...(isAbstention(extraction.answer) ? { abstained: true } : {})
             });
         },
         renderCall(args, theme) {
@@ -382,9 +386,6 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // child that ran fine and answered "unclear from this package" exits 0 — so a rule
         // keyed on exit code would memoise that non-answer and re-serve it as a hit to
         // every later sibling, with nothing left to re-trigger an escalation.
-        //
-        // `text` is supplied by makeWorkerTool (shared.ts) alongside details, so the
-        // content check needs no new plumbing.
         cacheable: docsCacheable
     });
 }
@@ -397,12 +398,33 @@ export function registerPiWorkerDocs(pi, internals = {}) {
  * assert against its own copy — green even after the shipped rule changed. Exported,
  * the test imports the rule it is checking.
  */
-export function docsCacheable(d, text) {
+/**
+ * Did the excerpt cite a word the source never wrote?
+ *
+ * `verified` is false for a stitched quote too, and the two must not share a gate:
+ * one is a possible fabrication and the other is what the extraction prompt asks
+ * for. Absent of a check, nothing was verified and nothing is claimed.
+ */
+export function excerptFabricated(check) {
+    return check !== undefined && check.absent.length > 0;
+}
+export function docsCacheable(d) {
     // Answer QUALITY only. Whether there IS an answer is `WorkerOutcome.kind`, and
     // `makeWorkerTool` has already refused an `unavailable` before reaching here —
     // opening this with `childExitCode === 0` memoises an aborted lookup for the
     // whole run, because a signal-killed child satisfies it.
-    return d.typeOnly !== true && d.excerptVerified !== false && !isAbstention(text);
+    //
+    // It reads `excerptFabricated`, not `excerptVerified`. A quarter of every run's
+    // answers come back unverified and this refused all of them; re-checked with the
+    // classifier defect 18 added, 41 of 41 unverified excerpts across seven runs are
+    // STITCHED — every span verbatim, not one absent word. The gate was refusing
+    // non-contiguous quoting, and every sibling paid a fresh child for it.
+    //
+    // The abstention is read off DETAILS, not off the tool text. `makeWorkerTool`
+    // hands this the FINAL text, which leads with `Per <pkg>@<version>:` — and
+    // `isAbstention` is anchored, so testing that text scored every abstention as a
+    // real answer and memoised the dead end for the whole run.
+    return d.typeOnly !== true && d.excerptFabricated !== true && d.abstained !== true;
 }
 /** The docs cache key: a package's answer is per (module, question), with the question
  *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns

package/dist/workers/pi-worker-fetch.d.ts

@@ -32,7 +32,7 @@ export declare function registerPiWorkerFetch(pi: ExtensionAPI, internals?: PiWo
  * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
  * refused.
  */
-export declare function fetchCacheable(_d: Pick<FetchDetails, never>, text: string): boolean;
+export declare function fetchCacheable(d: Pick<FetchDetails, 'answer'>): boolean;
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —
  *  same page, different question is a different answer. */
 export declare function fetchCacheKey(params: {

package/dist/workers/pi-worker-fetch.js

@@ -112,12 +112,16 @@ export function registerPiWorkerFetch(pi, internals = {}) {
  * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
  * refused.
  */
-export function fetchCacheable(_d, text) {
-    // Answer QUALITY only — see docsCacheable. This predicate returns true for
-    // `"Fetch aborted."` on its own; what keeps an aborted fetch out of the cache is
-    // the `unavailable` outcome upstream. Leading the rule with `childExitCode === 0`
-    // would not, because an aborted child settles at exit code 0.
-    return !isAbstention(text);
+export function fetchCacheable(d) {
+    // Answer QUALITY only — see docsCacheable. An aborted fetch is kept out of the
+    // cache by its `unavailable` outcome upstream, never by this rule; leading with
+    // `childExitCode === 0` would not work, because an aborted child settles at 0.
+    //
+    // It reads the child's bare answer, not the rendered tool text: `isAbstention` is
+    // anchored, and the text leads with an excerpt NOTE/WARNING whenever the excerpt
+    // did not verify — which, since rule 4 asks for the closest related text, is the
+    // ordinary shape of an abstention.
+    return d.answer !== undefined && !isAbstention(d.answer);
 }
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —
  *  same page, different question is a different answer. */

package/dist/workers/shared.d.ts

@@ -121,8 +121,12 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      * (type-only, an abstention, an unverified excerpt), never about process
      * health. An `unavailable` outcome never reaches this: `makeWorkerTool` has
      * already refused it. Defaults to always-cacheable when omitted.
+     *
+     * It sees `details` only. Handed the rendered tool text as well, a rule reaches
+     * for it and reads a string that leads with provenance and excerpt notes — and an
+     * anchored abstention matcher then scores every abstention as an answer.
      */
-    cacheable?(details: TDetails, text: string): boolean;
+    cacheable?(details: TDetails): boolean;
 }
 /** Register a worker tool from its spec, supplying the shared registration ritual. */
 export declare function makeWorkerTool<TParams extends TSchema, TDetails>(pi: ExtensionAPI, spec: WorkerToolSpec<TParams, TDetails>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.40.14",
+    "version": "0.40.26",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",