@mjasnikovs/pi-task 0.38.1 → 0.38.3

package/dist/task/question-dialog.js

@@ -0,0 +1,89 @@
+/**
+ * question-dialog — the one-question-at-a-time picker shared by the three places
+ * that ask the user to settle a fork: `/task`'s grill phase, `/task-auto`'s
+ * clarify loop, and the Plan session.
+ *
+ * All three do the same thing. Strip markdown for storage and render it for
+ * display; decide whether the question is a binary fork; short-circuit under
+ * YOLO; build `A: …` / `B: …` cards; call `ui.ask`; treat `undefined` as a
+ * cancel; and map the reply back onto an answer — where an empty submit accepts
+ * the recommendation, a bare "A"/"B" from a remote user (or the picker's
+ * free-text fallback) maps back to the option's full text, and anything else is
+ * taken verbatim.
+ *
+ * The mapping is the load-bearing part. Storing the literal letter "A" leaves the
+ * next generation call a dangling reference it cannot decode, so getting it wrong
+ * is not cosmetic.
+ *
+ * It was written three times. The Plan session factored its copy into a pure
+ * `resolveAnswer` returning a typed `AnswerSource`, and its own docstring said so
+ * out loud — "Mirrors the identical mapping in phaseGrill and planAuto" — but the
+ * two mirrors were never converted, and they had already drifted apart in three
+ * ways (which of them stamps an accepted recommendation, which has a
+ * single-option card branch, which handles a typed reply that equals an option).
+ * None was a crash. The next edit to any of them is where the bug lands, which is
+ * why they now share this.
+ *
+ * What stays at the call sites is POLICY, not mechanics: grill's auto-answer and
+ * widget line, clarify's plan-shape and triage pre-emption, plan's control
+ * actions. Those genuinely differ.
+ */
+/** True when the question is a binary fork rather than a single recommendation. */
+export function isTwoOption(p) {
+    return p.suggested !== undefined && p.alt !== undefined;
+}
+/**
+ * The answer cards: the recommendation first (index 0 is the green RECOMMENDED
+ * card), the alternative second when the question is a fork. `undefined` — not an
+ * empty array — when there is nothing to recommend, because that is what makes
+ * `ui.ask` fall back to a bare text prompt instead of an empty picker.
+ */
+export function buildOptionCards(p) {
+    if (isTwoOption(p)) {
+        return [
+            { label: `A: ${p.shownSuggested ?? p.suggested}`, value: p.suggested },
+            { label: `B: ${p.shownAlt ?? p.alt}`, value: p.alt }
+        ];
+    }
+    if (p.suggested !== undefined) {
+        return [{ label: p.shownSuggested ?? p.suggested, value: p.suggested }];
+    }
+    return undefined;
+}
+/**
+ * Map what the picker returned onto the answer that gets recorded, and say WHERE
+ * the answer came from.
+ *
+ * The `source` is returned rather than baked into the string because the three
+ * call sites disagree about provenance stamping, and that disagreement is real:
+ * `/task-auto`'s clarify transcript marks an accepted recommendation
+ * ("… (accepted recommendation)") while grill's does not, because grill's
+ * transcript is fed back verbatim into the next grill-gen prompt and the stamp
+ * would become model input. Keeping the stamp at the call site makes that a
+ * one-line difference you can see instead of a divergence hidden inside two
+ * six-branch ladders.
+ */
+export function resolveAnswer(p, raw) {
+    const typed = raw.trim();
+    const twoOption = isTwoOption(p);
+    if (typed.length === 0 && p.suggested !== undefined) {
+        return { answer: p.suggested, source: 'accepted' };
+    }
+    if (typed.length === 0)
+        return { answer: '(skipped)', source: 'skipped' };
+    if (twoOption && /^a[.)]?$/i.test(typed))
+        return { answer: p.suggested, source: 'chosen' };
+    if (twoOption && /^b[.)]?$/i.test(typed))
+        return { answer: p.alt, source: 'chosen' };
+    if (p.suggested !== undefined && typed === p.suggested) {
+        // Accepting the single green card by pressing it has the same provenance
+        // as accepting it by submitting empty. On a FORK, picking one of two is a
+        // choice, not an acceptance.
+        return { answer: p.suggested, source: twoOption ? 'chosen' : 'accepted' };
+    }
+    if (p.alt !== undefined) {
+        if (typed === p.alt)
+            return { answer: p.alt, source: 'chosen' };
+    }
+    return { answer: typed, source: 'typed' };
+}

package/dist/task/terminal-outcome.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What each way a gated task can END means for persistence and for what the user
+ * is told — stated once, for both `/task` and `/task-auto`.
+ *
+ * `runGatesForTask` is already shared verbatim by the two commands, so both
+ * consume the same five-kind outcome. What was NOT shared was the answer to the
+ * three questions each kind raises: demote the inner task file? fail the parent
+ * run file? what do we say, at what level? Those were two `switch`es 600 lines
+ * apart with line-for-line correspondence — down to the identical
+ * `reason.slice(0, 160)` truncation — differing only in the resume verb, whether
+ * a parent run file exists to fail, and whether the message names the step.
+ *
+ * That is not the shared "task-runner base" CONTEXT.md rules out, and for the
+ * same reason `runFinalGateStage` could leave `runAutoLoop`: this is the
+ * outcome → (persistence, message) mapping, and it touches none of either loop's
+ * state. Adding a sixth outcome kind is now a compile error in one place rather
+ * than a silently-unhandled fallthrough in whichever command was not updated.
+ *
+ * The PRE-gate outcomes (`res.sessionCancelled` / `res.interrupted` / `!res.ok`,
+ * before the gate runs) are deliberately NOT here. Their wording genuinely
+ * differs between the two commands — `/task` says "could not start a fresh
+ * session for /task" where `/task-auto` says "could not start a session. Run
+ * /task-auto-resume to retry" — and `/task-auto` has a cancel-requested branch
+ * `/task` has no equivalent for. Folding them in would mean a table of message
+ * overrides, which is not a simplification.
+ */
+/** The gate outcomes a command has to act on. Mirrors runGatesForTask's union. */
+export type TerminalOutcomeKind = 'done' | 'paused' | 'session-cancelled' | 'interrupted' | 'failed';
+/** What the message needs to name. */
+export interface TerminalMessageContext {
+    /** The task or run id shown to the user (`TASK_0007`, `AUTO_0002`, `Task`). */
+    tag: string;
+    /**
+     * The step this happened at, ALREADY formatted with its leading space —
+     * ` at "Add auth routes"`. Empty for `/task`, which runs one task and has no
+     * step to name.
+     */
+    at: string;
+    /** The failure cause, already truncated and formatted with its leading dash. */
+    why: string;
+    /** `/task-resume` or `/task-auto-resume`. */
+    resumeCmd: string;
+}
+export interface TerminalOutcome {
+    /**
+     * Demote the INNER task file to resumable. It reads `completed` from
+     * spec-handoff, and leaving it that way is how a failed run's task file
+     * claimed success in the run 6 audit.
+     */
+    markResumable: boolean;
+    /**
+     * Mark the PARENT run file failed. Only `/task-auto` has one; `/task` ignores
+     * this, which is why it is a property of the OUTCOME rather than of the
+     * command — the outcome is equally fatal either way.
+     */
+    failParent: boolean;
+    level: 'info' | 'warning' | 'error';
+    message: (c: TerminalMessageContext) => string;
+}
+/**
+ * Truncate a failure reason for a one-line notification, or produce nothing.
+ * Both commands did this identically and inline.
+ */
+export declare function formatWhy(reason?: string): string;
+/** The step suffix, or empty when the command has no step to name. */
+export declare function formatAt(title?: string): string;
+export declare const TERMINAL_OUTCOMES: Record<TerminalOutcomeKind, TerminalOutcome>;

package/dist/task/terminal-outcome.js

@@ -0,0 +1,76 @@
+/**
+ * What each way a gated task can END means for persistence and for what the user
+ * is told — stated once, for both `/task` and `/task-auto`.
+ *
+ * `runGatesForTask` is already shared verbatim by the two commands, so both
+ * consume the same five-kind outcome. What was NOT shared was the answer to the
+ * three questions each kind raises: demote the inner task file? fail the parent
+ * run file? what do we say, at what level? Those were two `switch`es 600 lines
+ * apart with line-for-line correspondence — down to the identical
+ * `reason.slice(0, 160)` truncation — differing only in the resume verb, whether
+ * a parent run file exists to fail, and whether the message names the step.
+ *
+ * That is not the shared "task-runner base" CONTEXT.md rules out, and for the
+ * same reason `runFinalGateStage` could leave `runAutoLoop`: this is the
+ * outcome → (persistence, message) mapping, and it touches none of either loop's
+ * state. Adding a sixth outcome kind is now a compile error in one place rather
+ * than a silently-unhandled fallthrough in whichever command was not updated.
+ *
+ * The PRE-gate outcomes (`res.sessionCancelled` / `res.interrupted` / `!res.ok`,
+ * before the gate runs) are deliberately NOT here. Their wording genuinely
+ * differs between the two commands — `/task` says "could not start a fresh
+ * session for /task" where `/task-auto` says "could not start a session. Run
+ * /task-auto-resume to retry" — and `/task-auto` has a cancel-requested branch
+ * `/task` has no equivalent for. Folding them in would mean a table of message
+ * overrides, which is not a simplification.
+ */
+/**
+ * Truncate a failure reason for a one-line notification, or produce nothing.
+ * Both commands did this identically and inline.
+ */
+export function formatWhy(reason) {
+    return reason ? ` — ${reason.slice(0, 160)}` : '';
+}
+/** The step suffix, or empty when the command has no step to name. */
+export function formatAt(title) {
+    return title === undefined ? '' : ` at "${title}"`;
+}
+export const TERMINAL_OUTCOMES = {
+    done: {
+        markResumable: false,
+        failParent: false,
+        level: 'info',
+        message: c => `${c.tag} complete — verified.`
+    },
+    paused: {
+        // The user was shown the verify-failure picker and dismissed it. Nothing
+        // is wrong with the tree; they simply have not decided yet.
+        markResumable: true,
+        failParent: true,
+        level: 'warning',
+        message: c => `${c.tag} paused${c.at} — verification failed and you dismissed the choice; `
+            + `resume with ${c.resumeCmd}.`
+    },
+    'session-cancelled': {
+        // No session for the autofix child. Nothing ran, so nothing to demote.
+        markResumable: false,
+        failParent: false,
+        level: 'warning',
+        message: c => `${c.tag} paused — could not start a session for autofix. `
+            + `Run ${c.resumeCmd} to retry.`
+    },
+    interrupted: {
+        markResumable: true,
+        // NOT a failure: the user stopped it. The parent run stays in_progress so
+        // a resume picks up where it left off.
+        failParent: false,
+        level: 'warning',
+        message: c => `${c.tag} paused${c.at} — resume with ${c.resumeCmd}.`
+    },
+    failed: {
+        markResumable: true,
+        failParent: true,
+        level: 'error',
+        message: c => `${c.tag} stopped${c.at}${c.why} — fix and run ${c.resumeCmd}.`
+    }
+};

package/dist/task/type-only-answer.js

@@ -58,6 +58,7 @@
  *
  * Pure and side-effect free; unit-tested in type-only-answer.test.ts against real run-15 text.
  */
+import { isAbstention } from '../workers/abstention.js';
 /**
  * Question seeks usage/semantics rather than a bare type. A usage concept whose MEANING is
  * being asked about ("base url") counts, because the F-2 defect is exactly a semantics need
@@ -164,8 +165,6 @@ const SIGNATURE = [
     /\bconstructor\s+accepts/i,
     /declare\s+(const|function)/i
 ];
-/** Explicit non-answer the docs child emits when the package cannot answer. */
-const UNCLEAR = /\bunclear\s+from\s+this\s+(package|page)\b/i;
 function firstMatch(text, patterns) {
     for (const p of patterns) {
         const m = p.exec(text);
@@ -213,7 +212,7 @@ export function isTypeOnlyAnswer(answer, question) {
     if (a.length === 0) {
         return { typeOnly: false, reason: 'empty answer' };
     }
-    if (UNCLEAR.test(a)) {
+    if (isAbstention(a)) {
         return {
             typeOnly: false,
             reason: 'explicit "unclear" non-answer — routed through the existing unclear/escalation path, not type-only'

package/dist/workers/abstention.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ABSTENTION — the explicit non-answer a focused-extractor child writes when the
+ * content it was given cannot answer the question, and the one place both halves
+ * of that contract live.
+ *
+ * Why one module. The sentinel has two halves that MUST agree: the sentence a
+ * prompt instructs the child to emit, and the predicate that later recognises it.
+ * They used to be independent. Three prompts wrote three phrasings — two of them
+ * as bare string literals buried in a template — and four regexes matched
+ * different subsets of the three:
+ *
+ *   pi-worker-docs   /unclear from this package/i          (package only)
+ *   typeonly-log     /unclear from this (package|project)/i (no page)
+ *   type-only-answer /unclear from this (package|page)/i    (no project)
+ *   pi-worker-fetch  no check at all
+ *
+ * That already cost one bug, recorded in typeonly-log: matching only the first
+ * silently scored every PROJECT abstention as a valid answer. The fix went into
+ * that one regex; the other three never learned.
+ *
+ * And it was still live on the fetch channel. pi-worker-docs documents F-2(e) at
+ * length — an "unclear" non-answer exits 0, so it was memoised into the research
+ * cache and re-served to every sibling task (52 of run 15's cached entries were
+ * "unclear" with hitCache true), one dead end paid for many times, with
+ * escalation unable to re-fire because the miss never recurred. `pi-worker-fetch`
+ * cached on `childExitCode === 0` alone, so "unclear from this page" reproduced
+ * exactly that failure on pages instead of packages.
+ *
+ * With emitter and matcher reading one table, a fourth corpus is one row and
+ * cannot be half-wired.
+ */
+/** The content a focused extractor was pointed at. One row per corpus. */
+export type AbstentionKind = 'package' | 'project' | 'page';
+/**
+ * The exact sentence to instruct a child to emit. Prompt builders must
+ * interpolate this rather than typing the words, or the matcher below stops
+ * describing what the prompts actually ask for.
+ */
+export declare function abstentionSentence(kind: AbstentionKind): string;
+/**
+ * True when the child declined to answer rather than answering.
+ *
+ * Callers use this for two different decisions and both matter: it must not be
+ * SCORED as an answer (typeonly-log, type-only-answer), and it must not be
+ * CACHED as one (pi-worker-docs, pi-worker-fetch) — a memoised non-answer is
+ * re-served to every later sibling and permanently suppresses escalation.
+ */
+export declare function isAbstention(text: string): boolean;
+/**
+ * The extraction prompt every corpus shares.
+ *
+ * Rules 1–5 were word-for-word identical in the npm and project prompt builders,
+ * differing only in the four nouns this signature takes — and one of those, the
+ * abstention sentence in rule 4, was a bare literal that the matchers above then
+ * had to guess at. Building the prompt from the same table that recognises its
+ * output is the whole point: rule 4 tells the child to write EXACTLY the sentence
+ * `isAbstention` looks for, by construction.
+ *
+ * `subject` is the prose noun ("npm package", "local project's source code");
+ * `tag` names both the identity element and the content element, which must match
+ * because rules 1, 2 and 4 all refer to `<{tag}-content>`.
+ */
+export declare function buildExtractionPrompt(opts: {
+    kind: AbstentionKind;
+    subject: string;
+    tag: string;
+    /** What goes inside `<{tag}>` — `hono@4.6.3`, or a project name. */
+    identity: string;
+    query: string;
+    content: string;
+}): string;

package/dist/workers/abstention.js

@@ -0,0 +1,108 @@
+/**
+ * ABSTENTION — the explicit non-answer a focused-extractor child writes when the
+ * content it was given cannot answer the question, and the one place both halves
+ * of that contract live.
+ *
+ * Why one module. The sentinel has two halves that MUST agree: the sentence a
+ * prompt instructs the child to emit, and the predicate that later recognises it.
+ * They used to be independent. Three prompts wrote three phrasings — two of them
+ * as bare string literals buried in a template — and four regexes matched
+ * different subsets of the three:
+ *
+ *   pi-worker-docs   /unclear from this package/i          (package only)
+ *   typeonly-log     /unclear from this (package|project)/i (no page)
+ *   type-only-answer /unclear from this (package|page)/i    (no project)
+ *   pi-worker-fetch  no check at all
+ *
+ * That already cost one bug, recorded in typeonly-log: matching only the first
+ * silently scored every PROJECT abstention as a valid answer. The fix went into
+ * that one regex; the other three never learned.
+ *
+ * And it was still live on the fetch channel. pi-worker-docs documents F-2(e) at
+ * length — an "unclear" non-answer exits 0, so it was memoised into the research
+ * cache and re-served to every sibling task (52 of run 15's cached entries were
+ * "unclear" with hitCache true), one dead end paid for many times, with
+ * escalation unable to re-fire because the miss never recurred. `pi-worker-fetch`
+ * cached on `childExitCode === 0` alone, so "unclear from this page" reproduced
+ * exactly that failure on pages instead of packages.
+ *
+ * With emitter and matcher reading one table, a fourth corpus is one row and
+ * cannot be half-wired.
+ */
+/**
+ * The noun each corpus calls itself IN THE PROMPT. The sentinel is built from
+ * this, so the sentence a child is told to write and the sentence the host looks
+ * for cannot drift apart.
+ */
+const NOUNS = {
+    package: 'package',
+    project: 'project',
+    page: 'page'
+};
+/**
+ * The exact sentence to instruct a child to emit. Prompt builders must
+ * interpolate this rather than typing the words, or the matcher below stops
+ * describing what the prompts actually ask for.
+ */
+export function abstentionSentence(kind) {
+    return `unclear from this ${NOUNS[kind]}`;
+}
+/**
+ * Matches any corpus's abstention. Built from the same table the prompts read, so
+ * adding a corpus cannot leave a matcher behind.
+ *
+ * Deliberately a SUBSTRING match, unlike fetch-core's separate
+ * `not covered by this page` sentinel, which is anchored. The two differ because
+ * the instructions differ: the "not covered" rule asks for a partial answer that
+ * NAMES what is missing, so a sourced answer can legitimately contain the phrase
+ * and an anchored match is required to avoid filing it as a coverage miss. The
+ * abstention rule asks for the sentinel INSTEAD of an answer, and models wrap it
+ * ("Unclear from this package — the README does not mention it."), so anchoring
+ * here would miss the real non-answers this exists to catch.
+ */
+const ABSTENTION_RE = new RegExp(`unclear\\s+from\\s+this\\s+(${Object.values(NOUNS).join('|')})\\b`, 'i');
+/**
+ * True when the child declined to answer rather than answering.
+ *
+ * Callers use this for two different decisions and both matter: it must not be
+ * SCORED as an answer (typeonly-log, type-only-answer), and it must not be
+ * CACHED as one (pi-worker-docs, pi-worker-fetch) — a memoised non-answer is
+ * re-served to every later sibling and permanently suppresses escalation.
+ */
+export function isAbstention(text) {
+    return ABSTENTION_RE.test(text);
+}
+/**
+ * The extraction prompt every corpus shares.
+ *
+ * Rules 1–5 were word-for-word identical in the npm and project prompt builders,
+ * differing only in the four nouns this signature takes — and one of those, the
+ * abstention sentence in rule 4, was a bare literal that the matchers above then
+ * had to guess at. Building the prompt from the same table that recognises its
+ * output is the whole point: rule 4 tells the child to write EXACTLY the sentence
+ * `isAbstention` looks for, by construction.
+ *
+ * `subject` is the prose noun ("npm package", "local project's source code");
+ * `tag` names both the identity element and the content element, which must match
+ * because rules 1, 2 and 4 all refer to `<{tag}-content>`.
+ */
+export function buildExtractionPrompt(opts) {
+    const { tag } = opts;
+    return (`You answer one question about ${opts.subject}, using only the provided content.\n`
+        + `\n`
+        + `Rules:\n`
+        + `1. Output ONLY two tags, in this order, with NO text outside them:\n`
+        + `   <answer>...your answer...</answer>\n`
+        + `   <excerpt>...verbatim quote from <${tag}-content>...</excerpt>\n`
+        + `2. The <excerpt> MUST be copied character-for-character from <${tag}-content>.\n`
+        + `   Do not paraphrase, translate, or summarise inside <excerpt>.\n`
+        + `3. Prefer type signatures, function declarations, and code blocks as evidence over prose.\n`
+        + `4. If the answer is unclear, ambiguous, or absent from <${tag}-content>, write exactly:\n`
+        + `   <answer>${abstentionSentence(opts.kind)}</answer> and put the closest related text in <excerpt>.\n`
+        + `   Do not guess.\n`
+        + `5. Be terse. One short paragraph in <answer> max.\n`
+        + `\n`
+        + `<${tag}>${opts.identity}</${tag}>\n`
+        + `<question>${opts.query}</question>\n`
+        + `<${tag}-content>\n${opts.content}\n</${tag}-content>\n`);
+}

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

@@ -0,0 +1,74 @@
+/**
+ * docs-chunk — cutting source text into retrievable chunks, for every corpus the
+ * docs Worker tool indexes.
+ *
+ * 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 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.
+ */
+/**
+ * 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.
+ */
+export declare const MAX_CHUNK_BYTES: number;
+/**
+ * Where a declaration starts. Splitting here keeps a signature and its body in
+ * one chunk, which is what makes a retrieved chunk quotable as evidence.
+ */
+export declare const DECL_SPLIT_RE: RegExp;
+/** Where a README section starts. */
+export declare const README_SPLIT_RE: RegExp;
+/**
+ * Split at every match, keeping the match with the text that FOLLOWS it — so a
+ * declaration keyword opens its chunk rather than closing the previous one.
+ *
+ * Never returns empty: a text with no match is one chunk, not zero.
+ */
+export declare function splitAtMatches(text: string, re: RegExp): string[];
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function sliceBytes(s: string, maxBytes: number): string[];
+/**
+ * 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.
+ */
+export declare function chunkDeclarations(content: string, relPath: string): 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

@@ -0,0 +1,143 @@
+/**
+ * docs-chunk — cutting source text into retrievable chunks, for every corpus the
+ * docs Worker tool indexes.
+ *
+ * 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 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.
+ */
+/**
+ * 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.
+ */
+export const MAX_CHUNK_BYTES = 8 * 1024;
+/**
+ * Where a declaration starts. Splitting here keeps a signature and its body in
+ * one chunk, which is what makes a retrieved chunk quotable as evidence.
+ */
+export const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\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;
+/**
+ * Split at every match, keeping the match with the text that FOLLOWS it — so a
+ * declaration keyword opens its chunk rather than closing the previous one.
+ *
+ * Never returns empty: a text with no match is one chunk, not zero.
+ */
+export function splitAtMatches(text, re) {
+    const parts = [];
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+        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`).
+        re.lastIndex = m.index + 1;
+    }
+    if (lastIndex < text.length)
+        parts.push(text.slice(lastIndex));
+    return parts.length ? parts : [text];
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function sliceBytes(s, maxBytes) {
+    const out = [];
+    let buf = Buffer.from(s, 'utf8');
+    while (buf.length > maxBytes) {
+        // Continuation bytes are 0b10xxxxxx. Back up while the byte we are about
+        // to cut before is one, so the cut lands on a character boundary.
+        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.
+        if (end === 0)
+            end = maxBytes;
+        out.push(buf.subarray(0, end).toString('utf8'));
+        buf = buf.subarray(end);
+    }
+    if (buf.length)
+        out.push(buf.toString('utf8'));
+    return out;
+}
+/**
+ * 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.
+ */
+export function chunkDeclarations(content, relPath) {
+    const chunks = [];
+    for (const part of splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'))) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const prefixed = `// ${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);
+        }
+    }
+    return chunks;
+}
+/** Chunk a README, one chunk per top-level section, each labelled by heading. */
+export function chunkReadme(content) {
+    const chunks = [];
+    for (const part of splitAtMatches(content, new RegExp(README_SPLIT_RE.source, 'gm'))) {
+        // Trailing whitespace only — leading blank lines carry the section break.
+        const trimmed = part.replace(/\s+$/, '');
+        if (!trimmed)
+            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);
+        }
+    }
+    return chunks;
+}