@mjasnikovs/pi-task 0.40.1 → 0.40.3

package/dist/task/enrichment.d.ts

@@ -6,8 +6,21 @@
  * denylisted shell names are dropped, a URL's trailing sentence punctuation is
  * stripped, docs targets stop at ENRICH_CAP while version targets continue to
  * ENRICH_VERSION_CAP, and the version list is a strict superset of the docs list.
+ *
+ * Package extraction is additionally gated on the caller's declared dependencies;
+ * see the `declared` parameter on {@link extractEnrichTargets}.
+ */
+export declare function extractEnrichTargets(text: string, 
+/**
+ * The project's declared dependencies. A backticked name outside this set is
+ * not enriched: the model backticks filenames (`config.ts`, `tsconfig.json`)
+ * and field names (`name`, `port`) far more often than package names, and each
+ * of those is also a real, unrelated package on the public registry — so the
+ * permissive read fetched and indexed a stranger's code under the project's
+ * own filename. Omit when the manifest is unreadable, which is not the same
+ * fact as "declares nothing".
  */
-export declare function extractEnrichTargets(text: string): {
+declared?: ReadonlySet<string>): {
     /** Packages that get a (heavy) docs fetch — capped at ENRICH_CAP. */
     packages: string[];
     /**

package/dist/task/enrichment.js

@@ -6,6 +6,9 @@
  * denylisted shell names are dropped, a URL's trailing sentence punctuation is
  * stripped, docs targets stop at ENRICH_CAP while version targets continue to
  * ENRICH_VERSION_CAP, and the version list is a strict superset of the docs list.
+ *
+ * Package extraction is additionally gated on the caller's declared dependencies;
+ * see the `declared` parameter on {@link extractEnrichTargets}.
  */
 const ENRICH_PKG_RE = /`((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)`/g;
 const ENRICH_URL_RE = /https?:\/\/[^\s)`>]+/g;
@@ -79,13 +82,25 @@ function parseServices(text) {
     }
     return out;
 }
-export function extractEnrichTargets(text) {
+export function extractEnrichTargets(text, 
+/**
+ * The project's declared dependencies. A backticked name outside this set is
+ * not enriched: the model backticks filenames (`config.ts`, `tsconfig.json`)
+ * and field names (`name`, `port`) far more often than package names, and each
+ * of those is also a real, unrelated package on the public registry — so the
+ * permissive read fetched and indexed a stranger's code under the project's
+ * own filename. Omit when the manifest is unreadable, which is not the same
+ * fact as "declares nothing".
+ */
+declared) {
     const pkgs = [];
     const seen = new Set();
     for (const m of text.matchAll(ENRICH_PKG_RE)) {
         const t = m[1];
         if (ENRICH_DENYLIST.has(t) || seen.has(t))
             continue;
+        if (declared && !declared.has(t))
+            continue;
         seen.add(t);
         pkgs.push(t);
         if (pkgs.length >= ENRICH_VERSION_CAP)

package/dist/task/external-context.d.ts

@@ -83,6 +83,18 @@ export interface ExternalContextPolicy {
     targetCap?: number;
     /** Max services fanned out. Omit for uncapped; the auto-answer path caps at 2. */
     serviceCap?: number;
+    /**
+     * Fan named packages out to a docs body. The RESEARCH path does not, and the
+     * auto-answer path does.
+     *
+     * Research retrieves against `refined.split('\n')[0]` — the literal word
+     * "GOAL" for every refined spec — so its bodies are whatever ranks against
+     * that, pasted raw. The live run of 2026-09-05 found no research output
+     * citing one, while the model's own docs tool answered 49 real questions
+     * across the same three runs. The auto-answer path asks a focused child an
+     * actual question, which is the shape that works.
+     */
+    packageDocs?: boolean;
     /**
      * A cheap live version lookup for every named dep that did NOT get a docs
      * target, so a version block exists for ALL of them. Omit to disable, as the

package/dist/task/external-context.js

@@ -22,7 +22,7 @@
  * Run against a mixed source, the emitted headings come out in exactly that order:
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
-import { chooseEcosystem, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
+import { chooseEcosystem, declaredDepNames, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -39,18 +39,24 @@ const RAW_BODY_LIMIT = 4000;
  */
 export async function buildExternalContext(source, deps, lookups, policy = {}) {
     const searchFn = lookups.search ?? defaultSearch;
-    const enrichTargets = extractEnrichTargets(source);
+    const enrichTargets = extractEnrichTargets(source, declaredDepNames(deps.cwd));
     // Packages lead urls, then the combined cap applies — so a capped run spends
     // its budget on named deps first. Uncapped, this is just "packages, then urls".
+    const docsPackages = policy.packageDocs === false ? [] : enrichTargets.packages;
     const targets = [
-        ...enrichTargets.packages.map(name => ({ kind: 'pkg', name })),
+        ...docsPackages.map(name => ({ kind: 'pkg', name })),
         ...enrichTargets.urls.map(name => ({ kind: 'url', name }))
     ].slice(0, policy.targetCap ?? Number.POSITIVE_INFINITY);
     const services = enrichTargets.services.slice(0, policy.serviceCap ?? Number.POSITIVE_INFINITY);
     const versionLookup = policy.versionLookup;
     const docsTargets = new Set(targets.filter(t => t.kind === 'pkg').map(t => t.name));
     const extraVersionPkgs = versionLookup ? enrichTargets.versionPackages.filter(p => !docsTargets.has(p)) : [];
-    if (policy.earlyReturnOnNoTargets && targets.length === 0 && services.length === 0)
+    // Version packages count as work here: with `packageDocs: false` a named dep
+    // produces no target at all, and returning early would drop its version block.
+    if (policy.earlyReturnOnNoTargets
+        && targets.length === 0
+        && services.length === 0
+        && extraVersionPkgs.length === 0)
         return '';
     const startedAt = Date.now();
     const [targetResults, serviceResults, extraVersionResults] = await Promise.all([
@@ -191,6 +197,7 @@ export async function gatherExternalContext(refined, deps) {
         search: deps.searchFn
     }, {
         versionLookup,
+        packageDocs: false,
         subStepLabel: 'enrichment',
         earlyReturnOnNoTargets: true
     });

package/dist/workers/docs-chunk.js

@@ -37,16 +37,25 @@ export const README_SPLIT_RE = /^#{1,2} /m;
 export function splitAtMatches(text, re) {
     const parts = [];
     let lastIndex = 0;
+    let acceptedEnd = 0;
     let m;
     while ((m = re.exec(text))) {
+        // Scan resumes ONE character in, not past the match: the regex's trailing
+        // `\s+` can span a newline, so a genuinely separate line-anchored
+        // declaration may start inside what this match consumed.
+        re.lastIndex = m.index + 1;
+        // But a match that starts inside the last ACCEPTED one is that match's own
+        // tail, not a new declaration, and cutting there severs a declaration from
+        // the modifiers and attributes that open it. `export\nfunction a(){}` is
+        // one declaration; so is a cargo `#[cfg(…)]` above its `impl`, which
+        // CARGO_DECL_SPLIT_RE absorbs on purpose and this used to hand back as a
+        // chunk holding nothing but the attribute.
+        if (m.index < acceptedEnd)
+            continue;
         if (m.index > lastIndex)
             parts.push(text.slice(lastIndex, m.index));
         lastIndex = m.index;
-        // 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;
+        acceptedEnd = m.index + m[0].length;
     }
     if (lastIndex < text.length)
         parts.push(text.slice(lastIndex));

package/dist/workers/docs-core.js

@@ -128,9 +128,32 @@ export function findDeclaredRange(parentPkg, cwd) {
  * does or does not say has to be a sentence about `bun`.
  */
 export function buildVersionBanner(pin, resolved, version, cwd, profile = ECOSYSTEMS.npm) {
+    const asked = pin?.asked ?? resolved;
+    // Resolvable is not usable. A lock file, a cabal plan and `node_modules` are
+    // all the transitive CLOSURE, so the tool can answer in full confidence about
+    // a package the project may not import. That is what made the Rust run of
+    // 2026-09-05 a hard fail: a correct `tower::util::ServiceExt` answer, the
+    // import written, and E0433 "cannot find module or crate tower" from the compiler.
+    const undeclared = undeclaredNotice(asked, cwd, profile);
     if (!pin)
+        return undeclared;
+    return undeclared + pinBanner(pin, asked, resolved, version, cwd, profile);
+}
+/**
+ * The one sentence a package present-but-not-declared needs, or `''` when it is
+ * declared or when no manifest could be read.
+ */
+function undeclaredNotice(asked, cwd, profile) {
+    const declared = profile.manifestDeps(cwd);
+    const root = profile.parentPackage(asked);
+    if (!declared || declared.has(root) || declared.has(asked))
         return '';
-    const asked = pin.asked ?? resolved;
+    return (`[DEPENDENCY] "${root}" is present in this project but is not a declared `
+        + `dependency in ${profile.manifestLabel} — it resolves only because something `
+        + `else pulled it in. Add it to ${profile.manifestLabel} before importing it, or `
+        + `the build will not find it.\n\n`);
+}
+function pinBanner(pin, asked, resolved, version, cwd, profile) {
     const grounded = resolved !== asked ? ` The types this answer reads come from ${resolved}.` : '';
     const manifest = profile.manifestLabel;
     const registry = profile.registryLabel;
@@ -485,7 +508,8 @@ function docsRawCached(cache, pkg, profile, query, ensureIndexed, retrieveChunks
             version: pkg.version,
             query,
             limit: DEFAULT_LIMIT,
-            contentBudget: DEFAULT_BUDGET
+            contentBudget: DEFAULT_BUDGET,
+            typeKeywords: profile.typeKeywords
         });
     }
     catch (err) {

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

@@ -84,6 +84,11 @@ export interface EcosystemProfile {
     surface: (content: string) => string;
     /** Where a declaration begins, so a chunk never splits a signature. */
     declSplitRe: 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.
+     */
+    typeKeywords: readonly string[];
     /** Line-comment marker, used to label a chunk with the file it came from. */
     commentPrefix: string;
     /** Directories the surface walk never descends into: tests, build output. */
@@ -105,6 +110,15 @@ export interface EcosystemProfile {
      * package's version, which is a different fact from "declares nothing".
      */
     declaredDeps: (cwd: string) => Record<string, string> | undefined;
+    /**
+     * The names the MANIFEST itself declares — what the project may import.
+     *
+     * Distinct from {@link declaredDeps}, which for cargo and hackage reads a
+     * lock or plan file: that is the whole transitive closure, so it answers
+     * "does this resolve" and not "may this be used". Undefined when there is no
+     * readable manifest, which is not the same fact as "declares nothing".
+     */
+    manifestDeps: (cwd: string) => Set<string> | undefined;
 }
 /** Overrides a caller has already been given its own copies of. */
 export interface NpmProfileHooks {
@@ -134,6 +148,12 @@ export declare const ECOSYSTEMS: {
 };
 /** Which ecosystems `cwd` looks like a project of, in roster order. */
 export declare function detectEcosystems(cwd: string, roster?: readonly EcosystemProfile[]): EcosystemId[];
+/**
+ * Every dependency `cwd`'s manifests declare, across the ecosystems it is a
+ * project of. Undefined when no detected ecosystem could read its manifest —
+ * "we cannot tell", which callers must not read as "declares nothing".
+ */
+export declare function declaredDepNames(cwd: string, roster?: readonly EcosystemProfile[]): Set<string> | undefined;
 export type EcosystemChoice = {
     ok: true;
     profile: EcosystemProfile;

package/dist/workers/docs-ecosystems.js

@@ -21,8 +21,8 @@ import { runAutoInstall, findDeclaredRange, extractParentPackage, resolveTypeSou
 import { resolvePackage, isDtsFile, isValidModuleName } from './docs-resolve.js';
 import { DECL_SPLIT_RE } from './docs-chunk.js';
 import { npmVersionLookup } from './npm-version.js';
-import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, CARGO_DECL_SPLIT_RE } from './eco-cargo.js';
-import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, findCabalTarball, cachedVersions, resolvedVersions, 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, CARGO_DECL_SPLIT_RE } from './eco-cargo.js';
+import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, findCabalTarball, cachedVersions, resolvedVersions, manifestPackages, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS } from './eco-hackage.js';
 import { runChild } from '../shared/child-process.js';
 /**
  * Is any of `names` present at `cwd` or above it?
@@ -128,6 +128,7 @@ export function npmProfile(hooks = {}) {
         isSurfaceFile: isDtsFile,
         surface: content => content,
         declSplitRe: DECL_SPLIT_RE,
+        typeKeywords: ['interface', 'type', 'class', 'enum'],
         commentPrefix: '//',
         // A nested node_modules is another package's surface, never this one's.
         skipDirs: ['node_modules'],
@@ -135,7 +136,11 @@ export function npmProfile(hooks = {}) {
         packageSubject: 'an npm package',
         projectGlobs: ['*.ts', '*.tsx'],
         projectName: npmProjectName,
-        declaredDeps: npmDeclaredDeps
+        declaredDeps: npmDeclaredDeps,
+        manifestDeps: cwd => {
+            const deps = npmDeclaredDeps(cwd);
+            return deps && new Set(Object.keys(deps));
+        }
     };
 }
 const NPM_DEP_BLOCKS = [
@@ -266,13 +271,15 @@ const cargoProfile = {
     isSurfaceFile: isRustFile,
     surface: content => rustSurface(content),
     declSplitRe: CARGO_DECL_SPLIT_RE,
+    typeKeywords: ['struct', 'trait', 'enum', 'type', 'union'],
     commentPrefix: '//',
     skipDirs: ['tests', 'benches', 'examples', 'target'],
     surfaceLabel: '.rs source or README',
     packageSubject: 'a Rust crate from crates.io',
     projectGlobs: ['*.rs'],
     projectName: cargoProjectName,
-    declaredDeps: lockedDeps
+    declaredDeps: lockedDeps,
+    manifestDeps: manifestCrates
 };
 /**
  * Unpack a Hackage tarball into the tool's own directory. Whether it came from
@@ -351,13 +358,15 @@ const hackageProfile = {
     isSurfaceFile: isHaskellFile,
     surface: haskellSurface,
     declSplitRe: HACKAGE_DECL_SPLIT_RE,
+    typeKeywords: ['type', 'data', 'newtype', 'class'],
     commentPrefix: '--',
     skipDirs: HACKAGE_SKIP_DIRS,
     surfaceLabel: '.hs source or README',
     packageSubject: 'a Haskell package from Hackage',
     projectGlobs: ['*.hs'],
     projectName: hackageProjectName,
-    declaredDeps: resolvedVersions
+    declaredDeps: resolvedVersions,
+    manifestDeps: manifestPackages
 };
 /** A cabal, stack or hpack project declares itself with one of these. */
 function hasCabalManifest(cwd) {
@@ -385,6 +394,26 @@ export const ECOSYSTEMS = {
 export function detectEcosystems(cwd, roster = Object.values(ECOSYSTEMS)) {
     return roster.filter(p => p.detect(cwd)).map(p => p.id);
 }
+/**
+ * Every dependency `cwd`'s manifests declare, across the ecosystems it is a
+ * project of. Undefined when no detected ecosystem could read its manifest —
+ * "we cannot tell", which callers must not read as "declares nothing".
+ */
+export function declaredDepNames(cwd, roster = Object.values(ECOSYSTEMS)) {
+    let any = false;
+    const names = new Set();
+    for (const p of roster) {
+        if (!p.detect(cwd))
+            continue;
+        const deps = p.manifestDeps(cwd);
+        if (!deps)
+            continue;
+        any = true;
+        for (const name of deps)
+            names.add(name);
+    }
+    return any ? names : undefined;
+}
 /**
  * Which ecosystem a lookup belongs to. The MANIFEST decides, never the model:
  * `text`, `base`, `aeson`, `tokio` and `clap` are all real npm packages as well

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

@@ -7,4 +7,32 @@ export interface IndexResult {
     chunksWritten: number;
     contentHash: string;
 }
+/**
+ * The gate that decides whether a package needs re-indexing.
+ *
+ * The entry file goes in SURFACED, not raw. What is cached is the extractor's
+ * OUTPUT, so a build whose extractor changed has stale chunks even though every
+ * byte on disk is identical — a crate indexed before the braced-`use` fix keeps
+ * `pub use crate::runtime::;` forever, because name, version and file bytes all
+ * still match. Surfacing here costs one file and makes the hash answer the
+ * question actually being asked: would re-reading produce the same chunks?
+ *
+ * The CHUNKER counts too, for the same reason: the rows are chunks, not surface,
+ * so a fix to where a declaration is cut leaves stale rows behind on its own. So
+ * does WHICH FILES are read: dropping a package's duplicate `.d.cts` twins
+ * changes the rows without changing a byte on disk.
+ *
+ * It is not total. An extractor change that alters only files BELOW the entry
+ * goes unnoticed; deleting the cache is still the escape hatch for that.
+ */
+/**
+ * The chunker's own source, so a cut-point fix invalidates every cached package.
+ *
+ * `declSplitRe.source` alone does not do it: the attribute-orphaning bug was in
+ * `splitAtMatches`, not in any profile's regex, so the fingerprint sat still while
+ * the rows it describes changed. A package indexed before that fix keeps its
+ * dangling `#[cfg(...)]` chunks forever, and the hash is the only thing that would
+ * have said so.
+ */
+export declare function chunkerFingerprint(): string;
 export declare function ensureIndexed(cache: CacheHandle, pkg: ResolvedPackage, profile?: EcosystemProfile): IndexResult;

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 } from './docs-chunk.js';
+import { chunkDeclarations, chunkReadme, splitAtMatches } from './docs-chunk.js';
 import { ECOSYSTEMS } from './docs-ecosystems.js';
 const ZERO_SEP = Buffer.from([0]);
 /**
@@ -16,17 +16,38 @@ const ZERO_SEP = Buffer.from([0]);
  * question actually being asked: would re-reading produce the same chunks?
  *
  * The CHUNKER counts too, for the same reason: the rows are chunks, not surface,
- * so a fix to where a declaration is cut leaves stale rows behind on its own.
+ * so a fix to where a declaration is cut leaves stale rows behind on its own. So
+ * does WHICH FILES are read: dropping a package's duplicate `.d.cts` twins
+ * changes the rows without changing a byte on disk.
  *
  * It is not total. An extractor change that alters only files BELOW the entry
  * goes unnoticed; deleting the cache is still the escape hatch for that.
  */
+/**
+ * The chunker's own source, so a cut-point fix invalidates every cached package.
+ *
+ * `declSplitRe.source` alone does not do it: the attribute-orphaning bug was in
+ * `splitAtMatches`, not in any profile's regex, so the fingerprint sat still while
+ * the rows it describes changed. A package indexed before that fix keeps its
+ * dangling `#[cfg(...)]` chunks forever, and the hash is the only thing that would
+ * have said so.
+ */
+export function chunkerFingerprint() {
+    return `${String(splitAtMatches)}\u0000${String(chunkDeclarations)}\u0000${String(chunkReadme)}`;
+}
 function computeContentHash(pkg, profile) {
     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(ZERO_SEP);
+    hash.update(Buffer.from(chunkerFingerprint(), 'utf8'));
+    hash.update(ZERO_SEP);
+    // Source text, the same trick as `declSplitRe.source`: the fingerprint moves
+    // whenever the selection rule does, with nothing to remember to bump.
+    hash.update(Buffer.from(`${String(profile.isSurfaceFile)}\u0000${String(dropParallelDeclarations)}`
+        + `\u0000${String(dropDeadMajors)}`, 'utf8'));
+    hash.update(ZERO_SEP);
     if (pkg.entry && fs.existsSync(pkg.entry)) {
         try {
             hash.update(Buffer.from(profile.surface(fs.readFileSync(pkg.entry, 'utf8')), 'utf8'));
@@ -83,9 +104,56 @@ function walkSurface(root, profile) {
     }
     return out.sort();
 }
+/**
+ * Drop a `.d.cts` / `.d.mts` that sits beside a `.d.ts` of the same name.
+ *
+ * Modern npm packages ship parallel declarations for ESM and CJS: the same API
+ * written twice. zod 4.5.4 indexed to 2565 chunks over 1215 distinct bodies,
+ * 1280 of them from `.d.cts`; hono, which ships none, had 704 distinct of 708.
+ * The cost is the eight-chunk retrieval budget — half of it can go to text the
+ * reader already has.
+ *
+ * The sibling test, not a blanket ban on the extensions: a package shipping only
+ * `.d.cts` still has to be readable, and all 123 of zod's had a `.d.ts` twin.
+ */
+function dropParallelDeclarations(files) {
+    const esm = new Set(files.filter(f => f.endsWith('.d.ts')).map(f => f.slice(0, -'.d.ts'.length)));
+    return files.filter(f => {
+        const base = /\.d\.[cm]ts$/.exec(f) ? f.slice(0, -'.d.cts'.length) : null;
+        return base === null || !esm.has(base);
+    });
+}
+/**
+ * Drop a top-level `vN/` directory holding a major the package is no longer on.
+ *
+ * zod@4.5.4 ships `v3/` for back-compat, and 414 of its 2565 chunks came from
+ * it. Nothing downstream can separate them: same identifiers, same package, same
+ * version banner, and the file path is not a ranking signal. An answer went out
+ * under `Per zod@4.5.4:` carrying v3's `email(message?): ZodString` — wrong
+ * parameter, wrong return, and silent about the `@deprecated` line sitting
+ * directly above the real declaration.
+ *
+ * Only a MISMATCHING major goes. `v4/` under 4.5.4 is the current API and is
+ * most of the package; a package whose only content lives under `v1/` keeps it.
+ */
+function dropDeadMajors(files, root, version) {
+    const major = /^(\d+)\./.exec(version)?.[1];
+    if (major === undefined)
+        return files;
+    const kept = files.filter(abs => {
+        const top = path.relative(root, abs).replace(/\\/g, '/').split('/')[0];
+        const dir = /^v(\d+)$/.exec(top);
+        return dir === null || dir[1] === major;
+    });
+    // A package whose whole surface lives under a `vN/` that does not match its
+    // own version is not shipping a dead major — it is shipping its API there.
+    return kept.length > 0 ? kept : files;
+}
 function collectFiles(pkg, profile) {
+    const walked = walkSurface(pkg.root, profile);
+    const surface = dropDeadMajors(walked, pkg.root, pkg.version);
     return {
-        surface: walkSurface(pkg.root, profile),
+        surface: profile.id === 'npm' ? dropParallelDeclarations(surface) : surface,
         readme: pkg.readme
     };
 }

package/dist/workers/docs-project.js

@@ -234,7 +234,11 @@ listFiles = getProjectFiles) {
             version,
             query,
             limit: DEFAULT_LIMIT,
-            contentBudget: DEFAULT_BUDGET
+            contentBudget: DEFAULT_BUDGET,
+            // Every detected ecosystem's keywords: a polyglot project's own
+            // source has no single language, and the extra keywords only widen
+            // which definition the hop can find.
+            typeKeywords: [...new Set(projectProfiles(cwd).flatMap(p => p.typeKeywords))]
         });
     }
     catch (err) {

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

@@ -12,6 +12,13 @@ export interface RetrieveOptions {
     version: string;
     query: string;
     limit?: number;
+    /**
+     * The keywords that introduce a named type, for the definition hop. Passed by
+     * the caller rather than read off `EcosystemProfile` here: docs-ecosystems
+     * imports docs-core, which imports this module, and reaching back for the
+     * profile closes that cycle at run time.
+     */
+    typeKeywords?: readonly string[];
     contentBudget?: number;
 }
 /**

package/dist/workers/docs-retrieve.js

@@ -16,6 +16,19 @@ export const RETRIEVE_CONTENT_BUDGET = 24_000;
 const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const MIN_TOKEN_LEN = 2;
+/**
+ * How many alias definitions one retrieval will chase. Three covers the observed
+ * case — hono's `get`/`json` pair plus one — without letting a chunk full of
+ * aliased members spend the whole budget on hops.
+ */
+const MAX_ALIAS_HOPS = 3;
+/** Backstop for a caller that names no ecosystem; every real one passes its own. */
+const DEFAULT_TYPE_KEYWORDS = ['interface', 'type', 'class', 'enum'];
+/** A member declared as a bare capitalised type: `get: HandlerInterface<…>`. */
+const MEMBER_TYPE_RE = /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:\s*([A-Z][A-Za-z0-9_]*)\s*[<;,)|&]/gm;
+const TYPE_DECL_RE = /\b(?:interface|type|class|data|newtype|struct|trait|enum)\s+([A-Z][A-Za-z0-9_]*)/g;
+/** The `<E extends Env, BasePath extends string>` a declaration introduces itself. */
+const TYPE_PARAMS_RE = /<([^<>]*)>/g;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;
 /**
@@ -86,6 +99,77 @@ function enforceBudget(chunks, budget) {
     }
     return out;
 }
+/**
+ * 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.
+ */
+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)) {
+        for (const part of m[1].split(',')) {
+            const name = /^\s*([A-Z][A-Za-z0-9_]*)\s*(?:extends|=|$)/.exec(part);
+            if (name)
+                typeParams.add(name[1]);
+        }
+    }
+    const asked = new Set(tokens.map(t => t.toLowerCase()));
+    const out = [];
+    // A capitalised name the QUERY itself asks about. scotty's seven failures were
+    // all of this shape: `type ActionM = ActionT IO` sits in one chunk of 312
+    // while 67 chunks USE the name, and a chunk carrying BOTH query terms
+    // (`get :: RoutePattern -> ActionM () -> ScottyM ()`) outranks the definition
+    // every time. Reading the ranked output, all eight slots went to uses.
+    for (const t of tokens) {
+        if (!/^[A-Z][A-Za-z0-9_]{2,}$/.test(t) || declared.has(t) || out.includes(t))
+            continue;
+        out.push(t);
+        if (out.length >= MAX_ALIAS_HOPS)
+            return out;
+    }
+    for (const m of text.matchAll(MEMBER_TYPE_RE)) {
+        const [, member, typeName] = m;
+        if (declared.has(typeName) || typeParams.has(typeName))
+            continue;
+        if (!asked.has(member.toLowerCase()) && !asked.has(typeName.toLowerCase()))
+            continue;
+        if (out.includes(typeName))
+            continue;
+        out.push(typeName);
+        if (out.length >= MAX_ALIAS_HOPS)
+            break;
+    }
+    return out;
+}
+/** The smallest chunk that DECLARES `name`, or null. */
+function definitionChunk(cache, opts, name) {
+    const keywords = opts.typeKeywords ?? DEFAULT_TYPE_KEYWORDS;
+    // Smallest first: the DEFINITION of a name is a short declaration, while the
+    // long chunks holding it are the ones that merely use it.
+    const where = keywords.map((_, i) => `content GLOB ?${i + 4}`).join(' OR ');
+    const row = cache.db
+        .prepare(`SELECT file_path, kind, content, 0 AS rank FROM chunks
+             WHERE ecosystem = ?1 AND name = ?2 AND version = ?3
+               AND (${where})
+             ORDER BY length(content) LIMIT 1`)
+        .get(opts.ecosystem, opts.name, opts.version, ...keywords.map(k => `*${k} ${name}[ <={(=]*`));
+    if (!row)
+        return null;
+    return { filePath: row.file_path, kind: row.kind, content: row.content, rank: row.rank };
+}
 export function retrieveChunks(cache, opts) {
     const limit = opts.limit ?? DEFAULT_LIMIT;
     const budget = opts.contentBudget ?? DEFAULT_BUDGET;
@@ -117,5 +201,20 @@ export function retrieveChunks(cache, opts) {
         content: r.content,
         rank: r.rank
     }));
-    return enforceBudget(mapped, budget);
+    const kept = enforceBudget(mapped, budget);
+    const key = (c) => `${c.filePath}\u0000${c.content.length}`;
+    const have = new Set(kept.map(key));
+    const hops = [];
+    for (const name of hopNames(kept.map(c => c.content).join('\n'), tokens)) {
+        const def = definitionChunk(cache, opts, name);
+        if (!def || have.has(key(def)))
+            continue;
+        hops.push(def);
+    }
+    if (hops.length === 0)
+        return kept;
+    // Hops sit directly behind the top-ranked chunk, so re-budgeting drops the
+    // WEAKEST original rather than the definition that explains the strongest.
+    // The budget itself does not move.
+    return enforceBudget([kept[0], ...hops, ...kept.slice(1)], budget);
 }

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

@@ -6,9 +6,9 @@
  * bodies and private items dropped. That is what `surface` below does, and it is
  * why this row needs code where the npm row needed none.
  *
- * Nothing here parses TOML. `Cargo.lock` is a generated file with a fixed
- * `[[package]]` shape, and a line reader over it costs one small function where
- * a TOML dependency would cost a dependency.
+ * No TOML parser. `Cargo.lock` is generated with a fixed `[[package]]` shape, and
+ * `Cargo.toml`'s dependency tables are read for their KEYS only, so a line reader
+ * covers both where a TOML dependency would cost a dependency.
  */
 import { type ResolvedPackage } from './docs-resolve.js';
 import type { NpmVersionInfo } from './npm-version.js';
@@ -112,4 +112,15 @@ export declare function rustSurface(src: string, insideTrait?: boolean, topLevel
 export declare function isRustFile(name: string): boolean;
 /** The `[package] name` of a cargo project, for labelling its own source. */
 export declare function cargoProjectName(cwd: string): string | null;
+/**
+ * The crate names `Cargo.toml` itself declares, under both `-` and `_` spellings.
+ *
+ * NOT {@link lockedDeps}: a lock file is the whole transitive closure, so it
+ * answers "can this resolve" and not "may this crate `use` it". The live run of
+ * 2026-09-05 answered about `tower` — in the lock via axum, absent from
+ * `[dependencies]` — and the crate did not compile.
+ *
+ * Undefined when there is no readable manifest, which is not "declares nothing".
+ */
+export declare function manifestCrates(cwd: string): Set<string> | undefined;
 export {};

package/dist/workers/eco-cargo.js

@@ -6,9 +6,9 @@
  * bodies and private items dropped. That is what `surface` below does, and it is
  * why this row needs code where the npm row needed none.
  *
- * Nothing here parses TOML. `Cargo.lock` is a generated file with a fixed
- * `[[package]]` shape, and a line reader over it costs one small function where
- * a TOML dependency would cost a dependency.
+ * No TOML parser. `Cargo.lock` is generated with a fixed `[[package]]` shape, and
+ * `Cargo.toml`'s dependency tables are read for their KEYS only, so a line reader
+ * covers both where a TOML dependency would cost a dependency.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -791,3 +791,44 @@ export function cargoProjectName(cwd) {
     const match = /^\s*name\s*=\s*"([^"]+)"/m.exec(section?.[1] ?? '');
     return match ? match[1] : null;
 }
+/**
+ * The crate names `Cargo.toml` itself declares, under both `-` and `_` spellings.
+ *
+ * NOT {@link lockedDeps}: a lock file is the whole transitive closure, so it
+ * answers "can this resolve" and not "may this crate `use` it". The live run of
+ * 2026-09-05 answered about `tower` — in the lock via axum, absent from
+ * `[dependencies]` — and the crate did not compile.
+ *
+ * Undefined when there is no readable manifest, which is not "declares nothing".
+ */
+export function manifestCrates(cwd) {
+    const text = safeRead(path.join(cwd, 'Cargo.toml'));
+    if (text === null)
+        return undefined;
+    const out = new Set();
+    const add = (name) => {
+        for (const key of new Set([name, canonical(name)]))
+            out.add(key);
+    };
+    let inDeps = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const header = /^\[([^\]]+)\]$/.exec(line);
+        if (header) {
+            const section = header[1];
+            // `[dependencies.serde]` and `[target.'cfg(unix)'.dependencies]` both
+            // declare, and the first names its crate in the header itself.
+            const table = /^(?:target\.[^.]*\.)?(?:dev-|build-)?dependencies(?:\.(.+))?$/.exec(section);
+            inDeps = table !== null && table[1] === undefined;
+            if (table?.[1])
+                add(table[1]);
+            continue;
+        }
+        if (!inDeps)
+            continue;
+        const key = /^([A-Za-z0-9_-]+)\s*=/.exec(line);
+        if (key)
+            add(key[1]);
+    }
+    return out;
+}

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

@@ -91,3 +91,12 @@ export declare function haskellSurface(rawSrc: string): string;
 export declare function isHaskellFile(name: string): boolean;
 /** The `name:` field of the project's own `.cabal` file. */
 export declare function hackageProjectName(cwd: string): string | null;
+/**
+ * The package names the project's `.cabal` file declares in `build-depends`,
+ * across every stanza.
+ *
+ * NOT {@link resolvedVersions}: that reads the cabal install plan, which is the
+ * whole transitive closure, so it cannot say whether a module may be imported.
+ * Undefined when there is no readable `.cabal` file.
+ */
+export declare function manifestPackages(cwd: string): Set<string> | undefined;

package/dist/workers/eco-hackage.js

@@ -506,3 +506,49 @@ export function hackageProjectName(cwd) {
     const match = /^\s*name\s*:\s*(\S+)/m.exec(safeRead(path.join(cwd, cabal)) ?? '');
     return match ? match[1] : null;
 }
+/**
+ * The package names the project's `.cabal` file declares in `build-depends`,
+ * across every stanza.
+ *
+ * NOT {@link resolvedVersions}: that reads the cabal install plan, which is the
+ * whole transitive closure, so it cannot say whether a module may be imported.
+ * Undefined when there is no readable `.cabal` file.
+ */
+export function manifestPackages(cwd) {
+    let entries;
+    try {
+        entries = fs.readdirSync(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    const cabal = entries.find(e => e.endsWith('.cabal'));
+    if (!cabal)
+        return undefined;
+    const text = safeRead(path.join(cwd, cabal));
+    if (text === null)
+        return undefined;
+    const out = new Set();
+    let inDepends = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/--.*$/, '');
+        const start = /^\s*build-depends\s*:(.*)$/i.exec(line);
+        const body = start ? start[1] : line;
+        if (start)
+            inDepends = true;
+        else if (!inDepends)
+            continue;
+        // A continuation is indented; a new field at the stanza's own indent ends
+        // the list. Both `,`-leading and `,`-trailing layouts are in the wild.
+        else if (/^\s*[A-Za-z-]+\s*:/.test(line) || line.trim() === '') {
+            inDepends = false;
+            continue;
+        }
+        for (const part of body.split(',')) {
+            const name = /^\s*([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(part);
+            if (name)
+                out.add(name[1]);
+        }
+    }
+    return out;
+}

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

@@ -194,7 +194,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 const r = await lookup(projectCorpus(projectName), chunks);
                 if (r.kind === 'failed')
                     return docsFailureResult(r.extraction, baseDetails, '');
-                const { extraction, excerptVerified: verified, body: text } = r;
+                const { extraction, excerptVerified: verified, body: text, content: retrieved } = r;
                 // SAME instrumentation channel as the package path below. Both branches
                 // record, or "the last docs answer before the worker stopped" is
                 // unanswerable whenever the last answer came from the branch that does
@@ -213,7 +213,8 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     reason: 'project-source lookup — the type-only detector is not applied here',
                     excerptVerified: verified,
                     excerptCheck: extraction.excerptCheck,
-                    toolText: text
+                    toolText: text,
+                    retrievedText: retrieved
                 });
                 return workerAnswer(text, {
                     ...baseDetails,
@@ -346,7 +347,8 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 reason: typeOnly.reason,
                 excerptVerified: verified,
                 excerptCheck: extraction.excerptCheck,
-                toolText: text
+                toolText: text,
+                retrievedText: concatenated
             });
             return workerAnswer(text, {
                 ...baseDetails,

package/dist/workers/typeonly-log.d.ts

@@ -31,6 +31,19 @@ export interface TypeOnlyLogRecord {
      * Optional — older records still parse.
      */
     excerptCheck?: ExcerptVerification;
+    /**
+     * The retrieved chunk text handed to the extraction child, before it wrote a word.
+     *
+     * `toolText` cannot stand in for it. The tool return embeds the child's own prose,
+     * so scoring that prose against it asks whether the answer contains itself — two
+     * full runs read 13/13, 12/12, 10/10, 13/13, 4/4 and 2/2 clean, 54 answers and not
+     * one miss, while one of them shipped `decodeFile`, which aeson 2 does not have.
+     * Removing the prose leaves only the child's own CITED excerpt, a line or two, and
+     * flags `from_str` and `Context` as invented. Neither corpus is the one the question
+     * needs; this is. Optional — records written before it still parse, and a scorer
+     * must say "not computable" rather than guess when it is absent.
+     */
+    retrievedText?: string;
     /**
      * The tool's ENTIRE return text — version banner, npm header, the answer prose, the cited
      * excerpt, and (when it fires) the type-only banner. Optional so logs written before this

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.40.1",
+    "version": "0.40.3",
     "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",