bareloop 0.8.0 → 0.10.0

package/types/authorjob.d.ts

@@ -0,0 +1,242 @@
+/**
+ * The spine events a refusal produces — returned rather than emitted, because
+ * this module owns no spine (the runner shell does, exactly as with `runJob`).
+ *
+ * The `job-red` carries the structured `verb`/`lib`, which is the channel
+ * `classifyIncidents` already reads; the escalation carries the human's levers
+ * and is EXCLUDED from classification so the same demand is not counted twice.
+ * @param {Refusal} refusal
+ * @returns {{type: string, [k: string]: any}[]}
+ */
+export function refusalEvents(refusal: Refusal): {
+    type: string;
+    [k: string]: any;
+}[];
+/**
+ * Read the picked verdict class and that class's own frozen answers. Pure: no
+ * model, no repository, no clock.
+ *
+ * Four outcomes, and the middle two are the ones that matter:
+ *   - `ok` — a class v1 builds, every answer present, a repository named;
+ *   - a CLASS REFUSAL — the user picked soft-green or hitl. Counted demand for a
+ *     VERDICT CLASS, refused at ADMISSION, before that class's questions run
+ *     (they are named but locked, and asking them would be an interview for a
+ *     job nothing here can close);
+ *   - a REPO REFUSAL — a green pick with nothing deterministic to measure
+ *     against. Counted demand too;
+ *   - plain `reds` — the interview is not finished, or the radio was not set.
+ *     NOT demand: an incomplete form is not a user asking for a capability, and
+ *     an unknown class is a typo, never a request (the same split `src/job.js`
+ *     makes between a locked verdict and an invalid one).
+ *
+ * @param {{answers: Record<string|number, any>, verdictType?: string|null,
+ *   repoPath?: string|null, questions?: Record<string|number, string>|null}} o
+ *   `verdictType` and `repoPath` are STRUCTURED input from the UI, never parsed
+ *   out of the prose of an answer: a class is picked off a radio and a path is
+ *   read off the machine, or neither exists.
+ * @returns {{ok: boolean, answers: Record<string|number, string>,
+ *   verdictType: string|null, repoPath: string|null, refusal: Refusal|null, reds: Red[]}}
+ */
+export function runInterview({ answers, verdictType, repoPath, questions }: {
+    answers: Record<string | number, any>;
+    verdictType?: string | null;
+    repoPath?: string | null;
+    questions?: Record<string | number, string> | null;
+}): {
+    ok: boolean;
+    answers: Record<string | number, string>;
+    verdictType: string | null;
+    repoPath: string | null;
+    refusal: Refusal | null;
+    reds: Red[];
+};
+/**
+ * The refusal for a user who asks for a LOCKED KIND by name — a judged score or
+ * a person's sign-off. Exposed because the tool-mode declaration schema makes a
+ * locked kind INEXPRESSIBLE (M3's header states the cost): the demand cannot
+ * arrive through the model, so it has to arrive through the interview layer, and
+ * this is that layer.
+ * @param {string} kind @returns {Refusal}
+ */
+export function refuseLockedKind(kind: string): Refusal;
+/**
+ * Interview answers in, a signable close DECLARATION out.
+ *
+ * The order is the design's own, and every cheap refusal happens before any
+ * token: interview → seed → scout → listing → the grounded authoring loop (M3).
+ *
+ * `scoutFn`, `listingFn` and `seedFn` are seams so a caller can supply a survey
+ * it already paid for (the prereg reuses one across arms), and so the whole
+ * pipeline is testable without a provider. All three are REAL by default.
+ *
+ * THE GENRE REFUSAL LIVES HERE NOW (PRD v1.57 §2). D13's interview slot asked
+ * the user to confirm a genre; the interview no longer asks, and the refusal
+ * moved to the COMPOSER — a job the catalogue cannot measure refuses at this
+ * layer, on the same `request-red` path, still counted as demand. Two mechanical
+ * signals reach it and neither is a reading of prose: a language the genre owns
+ * no data for (so there is no guard battery to attach), and a LOCKED KIND the
+ * model reached for (the catalogue's own counted-demand red, carried up). D13's
+ * one-genre-at-a-time law is untouched.
+ *
+ * @param {{answers: Record<string|number, any>, repoPath?: string|null, lang: string,
+ *   verdictType?: string|null,
+ *   questions?: Record<string|number, string>|null, generate?: Function, provider?: any,
+ *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null,
+ *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
+ *   authorFn?: Function, authorOpts?: object}} o
+ * @returns {Promise<{ok: boolean, refusal: Refusal|null, verdictType: string|null,
+ *   closeDecl: any, seedRef: string|null, authoring: any, reds: Red[], stop: string|null,
+ *   cost: any, interview: any}>}
+ */
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, seedFn, scoutFn, listingFn, authorFn, authorOpts, }: {
+    answers: Record<string | number, any>;
+    repoPath?: string | null;
+    lang: string;
+    verdictType?: string | null;
+    questions?: Record<string | number, string> | null;
+    generate?: Function;
+    provider?: any;
+    seedRef?: string | null;
+    scout?: any;
+    listing?: any;
+    ceilingUsd?: number | null;
+    seedFn?: Function;
+    scoutFn?: Function;
+    listingFn?: Function;
+    authorFn?: Function;
+    authorOpts?: object;
+}): Promise<{
+    ok: boolean;
+    refusal: Refusal | null;
+    verdictType: string | null;
+    closeDecl: any;
+    seedRef: string | null;
+    authoring: any;
+    reds: Red[];
+    stop: string | null;
+    cost: any;
+    interview: any;
+}>;
+/**
+ * Fold an authored close into the OPERATOR's own half of the spec.
+ *
+ * The two halves never mix: budgets, the fence, cadence, escalation and the
+ * provider are operator input and are not authored by anything here (the
+ * permanent hard line). What this adds is the close, the derived verdict class,
+ * and nothing else.
+ *
+ * The GOAL is passed through, not generated. F87 requires the goal to state
+ * everything the close judges, and §3 of the design record says that becomes
+ * structural once the goal RENDERS from the same answers — that rendering is UI
+ * work (PRD v1.51 §5, "lands with the close-authoring interview UI") and is
+ * deliberately not invented here.
+ *
+ * A draft that ALREADY carries the authored half is REFUSED, not merged and not
+ * overwritten. `src/job.js` states the rule for the close in its own words — two
+ * closes are two arbiters, and "picking one silently is how the signed artefact
+ * stops meaning what the signer read" — and the same holds one step earlier and
+ * for the class: this fold used to drop a draft's `close` on the floor and stamp
+ * its own `verdictType` over the operator's, so a person who typed either would
+ * read back a signed spec that never contained what they wrote. Refusing by name
+ * costs the legitimate path nothing (a draft is the operator's half BY
+ * DEFINITION, and nothing in the pipeline builds one carrying these) and it is
+ * the same direction every other gate here takes: a mismatch a human cannot see
+ * is worse than a stop a human can read.
+ * @param {any} specDraft the operator's half (everything except close/closeDecl/verdictType)
+ * @param {{closeDecl: any, verdictType: string}} authored
+ * @throws {Error} when the draft already carries close, closeDecl or verdictType
+ */
+export function assembleSpec(specDraft: any, { closeDecl, verdictType }: {
+    closeDecl: any;
+    verdictType: string;
+}): any;
+/**
+ * D9, in code: *nothing JUDGES the close; three mechanical gates plus a
+ * signature.* No LLM validates another LLM's close, here or anywhere.
+ *
+ *   1. THE DECLARATION VALIDATOR — the spec's own gate plus M2's, run GROUNDED
+ *      against the real seed listing (the job validator defers that half).
+ *   2. THE CLOSE PRECHECK — every stage runs against the real patient. A stage
+ *      that cannot run is `broken-close`, and it is a CASUALTY, never a red.
+ *   3. THE SEED-VERDICT READ — every stage, offered or not, run at the seed. Which
+ *      are RED (the work) and which are GREEN (the guards) is shown to the user.
+ *      A close with NO work stage red at seed has nothing to do and is refused
+ *      decision-ready — gate-2 round 2's arm B died exactly there, on a mypy that
+ *      scanned nothing and therefore read clean.
+ *
+ * Gates 2 and 3 share ONE execution, and that is stated rather than hidden: at
+ * job creation the tree IS the seed, so "does every stage run against the real
+ * patient" and "what does every stage say at the seed" are two readings of the
+ * same pass. `seedRead` runs EVERY stage rather than first-red-wins, which is
+ * D12's own named build item — a stage that never ran mints no baseline, and
+ * every shipped close opens with a guard that is red at its own seed.
+ *
+ * IT NEVER SIGNS. The approvals array and the human's word are unchanged; what
+ * comes back is the resolved spec, its hash, and the evidence to sign against.
+ *
+ * @param {{spec: any, workdir: string, seedRef?: string|null, shellCapUsd?: number,
+ *   timeoutMs?: number, seedFn?: Function, listingFn?: Function, seedReadFn?: Function}} o
+ * @returns {Promise<{ok: boolean, specHash: string|null, seedRef: string|null,
+ *   gates: any, work: any[], guards: any[], stops: any[], reds: Red[], refusal: Refusal|null}>}
+ */
+export function prepareSigning({ spec, workdir, seedRef, shellCapUsd, timeoutMs, seedFn, listingFn, seedReadFn, }: {
+    spec: any;
+    workdir: string;
+    seedRef?: string | null;
+    shellCapUsd?: number;
+    timeoutMs?: number;
+    seedFn?: Function;
+    listingFn?: Function;
+    seedReadFn?: Function;
+}): Promise<{
+    ok: boolean;
+    specHash: string | null;
+    seedRef: string | null;
+    gates: any;
+    work: any[];
+    guards: any[];
+    stops: any[];
+    reds: Red[];
+    refusal: Refusal | null;
+}>;
+/** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
+/** @typedef {{kind: 'request-red'|'decision-ready', verb: string|null, path: string,
+ *   detail: string, options: string[], red: Red|null}} Refusal */
+/** the one genre v1 admits (D13). The interview no longer ASKS about it — the
+ * catalogue is one genre wide and the composer is where that refuses — but the
+ * signed `closeDecl` still names the genre it was authored under. */
+export const GENRE: "TYPES";
+/** The territory every refusal here lands against. bareloop's OWN catalogue —
+ * the genre menu, the verdict menu, the kind menu — never a bare-suite package.
+ * Stamped at the emit site (the typed-lib rule). */
+export const REFUSAL_LIB: "bareloop";
+/** the escalation category a refusal escalates under. It is DELIBERATELY in the
+ * ledger's executable excluded set: the demand is already counted once as a
+ * `request-red`, and counting the escalation too would inflate the very number
+ * the admission path exists to measure. */
+export const REFUSAL_CATEGORY: "close-unauthorable";
+/** The fields `assembleSpec` writes, and therefore the fields a DRAFT must not
+ * carry. Named as data so the refusal and the fold can never disagree about
+ * which half of the spec is which. */
+export const AUTHORED_SPEC_FIELDS: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail: string;
+    [k: string]: any;
+};
+export type Refusal = {
+    kind: "request-red" | "decision-ready";
+    verb: string | null;
+    path: string;
+    detail: string;
+    options: string[];
+    red: Red | null;
+};
+import { QUESTION_SETS } from './authorflow.js';
+import { questionsFor } from './authorflow.js';
+import { requiredAnswersFor } from './authorflow.js';
+import { VERDICT_CLASSES } from './authoring.js';
+import { LOCKED_CLASSES } from './authoring.js';
+import { LIVE_CLASSES } from './authoring.js';
+export { QUESTION_SETS, questionsFor, requiredAnswersFor, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES };

package/types/authorscout.d.ts

@@ -0,0 +1,320 @@
+/**
+ * The re-ask, when the survey came back MALFORMED. It names what failed
+ * MECHANICALLY — the parse error and its position — which is the gap genre that
+ * converts (F38/F39), and it says explicitly that the FINDINGS are not in
+ * question, only their form.
+ *
+ * There is NO JSON repair anywhere behind this and there never will be: a
+ * repairer decides what the model meant to say and writes it down as though the
+ * model had said it. That is a dishonest instrument in the one artefact whose
+ * entire job is to be honest about what the repository contains.
+ * @param {string} reason the classifier's own mechanical reason
+ */
+export function scoutReaskTurn(reason: string): string;
+/**
+ * The survey brief. Deliberately NEUTRAL about what anyone will do with the
+ * facts: this scout is not allowed to have an opinion about the work, because
+ * the authoring call is the only thing that composes a close (D11).
+ * @param {string} workdir the ABSOLUTE repository root
+ */
+export function scoutPrompt(workdir: string): string;
+/**
+ * @typedef {{bytes: number, rounds: number, bounded: boolean, recovered: boolean, error: string|null,
+ *   attempts?: number, attemptsAllowed?: number}} SurveyMeta
+ * @typedef {{state: 'PRESENT'|'ABSENT', facts: any, reason: string|null, cause: string|null, meta: SurveyMeta}} Survey
+ */
+/**
+ * THE F59 CONTRACT, IN CODE. Six routes to ABSENT, one route to PRESENT — and
+ * the LAST of them is the whole point of the finding: a parsed `{}` is the
+ * scout FAILING, never "no special facts are needed".
+ *
+ * Every ABSENT route also carries a TYPED `cause` beside its prose reason. The
+ * prose is for the operator; the type is what the retry gate reads, so widening
+ * that gate requires editing the enum rather than a regular expression over a
+ * sentence (the standing rule: hand over the enumerated set, never a rule about
+ * prose). `empty` is split OUT of the byte floor for exactly that reason — "the
+ * model said nothing" and "the model was cut off mid-sentence" are two findings
+ * that used to render as one number.
+ * @param {string} blob the scrubbed, capped survey text
+ * @param {SurveyMeta} meta
+ * @returns {Survey}
+ */
+export function classifySurvey(blob: string, meta: SurveyMeta): Survey;
+/**
+ * The DEFAULT surveyor: a real bareguard fence plus the granted read-only tools.
+ * Read-only TWICE OVER — the menu carries no write verb, and the fence grants no
+ * write path — and the arbiter's own books are denied outright, exactly as every
+ * worker's are.
+ *
+ * It is a seam because it is the only part of this module that needs a live
+ * process, an index and a gate; the ROUND BOUND and the F59 recovery stay in
+ * `runAuthorScout` where they can be proven.
+ * @param {{workdir: string, granted: readonly string[], auditPath?: string, ctx?: boolean}} o
+ */
+export function defaultSurveyor({ workdir, granted, auditPath, ctx }: {
+    workdir: string;
+    granted: readonly string[];
+    auditPath?: string;
+    ctx?: boolean;
+}): Promise<{
+    tools: any[];
+    policy: Function;
+    onLlmResult: Function;
+    cleanup: () => Promise<void>;
+}>;
+/**
+ * Run the authoring scout.
+ *
+ * `createLoop` and `createSurveyor` are the two seams, both REAL by default. The
+ * round bound, F59's reserved round, the blob cap, the scrub and the
+ * classification all live HERE rather than behind a seam, because those are the
+ * behaviours the finding is about.
+ *
+ * THE ATTEMPT LADDER (hamr, 2026-08-09) sits OUTSIDE all of that, and it fires
+ * on the typed malformed class only — see `SCOUT_RETRY_CAUSES` for what is
+ * deliberately excluded and why. Attempt 1 is the full survey; a re-ask is
+ * TOOLLESS over the conversation the survey already produced, because the model
+ * has already READ the repository and only its final emission was unreadable —
+ * re-paying the exploration would buy the same facts twice. Every attempt is a
+ * paid call, metered under its own label, and every attempt's raw text is
+ * persisted so the malformation can be READ later rather than remembered.
+ *
+ * ONE FALLBACK, stated because the code has it: a retry with NO conversation to
+ * re-ask over re-runs the FULL toolable survey instead. The toolless form rests
+ * entirely on "the model already read the tree", and an empty transcript is that
+ * premise gone — re-asking over nothing would be a bare "say it again" to a model
+ * that was never shown the repository. Re-surveying costs the exploration twice;
+ * the alternative buys a second sample of noise. It is not reachable through the
+ * shipped Loop (whose `msgs` starts from the caller's own messages and is never
+ * empty) and it is reachable through the `createLoop` seam, so it is a fail-safe
+ * with a test rather than a promise with a comment.
+ *
+ * @param {{workdir: string, provider?: any,
+ *   rounds?: number, minBytes?: number, blobMax?: number, maxTokens?: number, ctx?: boolean,
+ *   attempts?: number, ceilingUsd?: number|null,
+ *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any}) => any,
+ *   createSurveyor?: (o: {workdir: string, granted: readonly string[], ctx: boolean}) => Promise<any>}} o
+ * @returns {Promise<Survey & {raw: string, raws: ReturnType<typeof scrubRaw>[],
+ *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
+ *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
+ */
+export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, createLoop, createSurveyor, }: {
+    workdir: string;
+    provider?: any;
+    rounds?: number;
+    minBytes?: number;
+    blobMax?: number;
+    maxTokens?: number;
+    ctx?: boolean;
+    attempts?: number;
+    ceilingUsd?: number | null;
+    createLoop?: (o: {
+        system: string;
+        policy: any;
+        onLlmResult: any;
+        provider: any;
+    }) => any;
+    createSurveyor?: (o: {
+        workdir: string;
+        granted: readonly string[];
+        ctx: boolean;
+    }) => Promise<any>;
+}): Promise<Survey & {
+    raw: string;
+    raws: ReturnType<typeof scrubRaw>[];
+    calls: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }[];
+    budgetStop: "cap-halt" | "pricing-red" | null;
+}>;
+/**
+ * `git ls-tree -r --name-only <seed>` — the files as of the SEED COMMIT.
+ * Deliberately NOT `ls-files`, which reads the index and the working tree: this
+ * listing is what a path is judged against, and it must describe the tree the
+ * close will be measured from, not whatever is lying around today.
+ *
+ * A fault comes back as a named `stop`, never as an empty list — an unreadable
+ * listing that rendered as "no files" would fail every path in the declaration
+ * for the wrong reason.
+ * `files` is spelled `null` on the stop branch rather than left off: a caller
+ * that destructures the failure and finds `undefined` reads it as falsy, which
+ * is the "absent renders as empty" shape this whole module exists to refuse.
+ *
+ * The command itself lives in `src/kinds.js` beside the executor's other git
+ * reads (`seedListing`) — the declared close's runtime gate judges paths against
+ * the SAME listing this scout hands the author, and two spellings of "what
+ * exists at the seed" would be two instruments.
+ * @param {string} workdir @param {string} seedRef
+ * @returns {Promise<{stop: string, files: null}|{stop: null, files: string[]}>}
+ */
+export function seedFileList(workdir: string, seedRef: string): Promise<{
+    stop: string;
+    files: null;
+} | {
+    stop: null;
+    files: string[];
+}>;
+/**
+ * THE SEED LISTING, both halves.
+ *
+ * `files` is the WHOLE tree and is what the validator judges paths against.
+ * `block` is SCOPED to the survey's own sourcePaths/testPaths and is what the
+ * prompt carries. Giving the validator the scoped half instead would make a job
+ * scoped to `src/` read as whole-tree, and M2's one-population law — which fires
+ * only on a SCOPED job — would silently stop firing.
+ *
+ * @param {{workdir: string, seedRef: string, sourcePaths?: any, testPaths?: any,
+ *   listCap?: number, byteCap?: number}} o
+ * @returns {Promise<{stop: string, files: null, block: null, meta: null}
+ *   |{stop: null, files: string[], block: string, meta: {seedRef: string, totalSeedFiles: number,
+ *     entries: {entry: string, raw: string, section: string, matched: number}[], tier: string}}>}
+ */
+export function buildSeedListing({ workdir, seedRef, sourcePaths, testPaths, listCap, byteCap }: {
+    workdir: string;
+    seedRef: string;
+    sourcePaths?: any;
+    testPaths?: any;
+    listCap?: number;
+    byteCap?: number;
+}): Promise<{
+    stop: string;
+    files: null;
+    block: null;
+    meta: null;
+} | {
+    stop: null;
+    files: string[];
+    block: string;
+    meta: {
+        seedRef: string;
+        totalSeedFiles: number;
+        entries: {
+            entry: string;
+            raw: string;
+            section: string;
+            matched: number;
+        }[];
+        tier: string;
+    };
+}>;
+/** src/planrun.js:42 — the survey's hard round bound. */
+export const AUTHOR_SCOUT_ROUNDS: 8;
+/** src/planrun.js:44 — the survey is a PROMPT INGREDIENT for the authoring call. */
+export const AUTHOR_SCOUT_BLOB_MAX: 8000;
+/**
+ * src/planrun.js:62 — below this a survey is ABSENT, not empty. Sized off the
+ * archive rather than taste: 15 truncated scouts produced 0/74/86 bytes; every
+ * real survey was 5991-8056. It is imported as a NUMBER, not as an import, on
+ * purpose — planrun does not export it, and a `SCOUT_MIN_BYTES` that drifts
+ * between the two scouts is two instruments, so the suite pins them equal.
+ */
+export const AUTHOR_SCOUT_MIN_BYTES: 200;
+/** F30 — the 4096 provider default cannot hold a whole survey. */
+export const AUTHOR_SCOUT_MAX_TOKENS: 32000;
+/**
+ * TOTAL survey attempts, HARDCODED (hamr, 2026-08-09: *"depending on causes, we
+ * can hardcode 3 attempts, but if reasons are beyond malformed then we may verge
+ * into self-healing but i don't think we should"*).
+ *
+ * It is a ceiling, not a target: an operator may pass a LOWER cap and never a
+ * higher one, exactly the direction the standing budget rule runs in (*the agent
+ * may only TIGHTEN*). A widened value CLAMPS here rather than throwing, because
+ * the number is not a signed artefact — nothing downstream depends on a caller
+ * having asked for the right one, and refusing a run over a too-generous cap
+ * costs a paid scout for no safety.
+ *
+ * Sited beside `MAX_REVISIONS`/`MAX_STRUCTURE_RETRIES` in spirit: the same
+ * bounded-retry family, one axis each. This one is the SURVEY's axis.
+ */
+export const SCOUT_ATTEMPTS: 3;
+/**
+ * THE TYPED CAUSE, at the detection site.
+ *
+ * The retry gate reads this enum and nothing else. Typing it here is what stops
+ * the gate quietly widening to "any ABSENT" the next time someone edits the
+ * classifier: a new route to ABSENT has to be named, and naming it is the moment
+ * somebody decides whether it retries.
+ */
+export const SURVEY_CAUSES: Readonly<{
+    /** the call itself died — provider error, transport, `truncated:max_tokens` */
+    CALL_FAILED: "call-failed";
+    /** the model returned nothing at all, and nothing went wrong to explain it */
+    EMPTY: "empty";
+    /** short of the ABSENT floor but not empty — F59's cut-off population */
+    SHORT: "short";
+    /** nothing extractable in the reply */
+    NO_ARTIFACT: "no-artifact";
+    /** there IS a body and it is not JSON — run mslhn707's own death */
+    UNPARSEABLE: "unparseable";
+    /** valid JSON, wrong shape */
+    NON_OBJECT: "non-object";
+    /** valid JSON, no content — F59's whole point, and a SEMANTIC failure */
+    EMPTY_OBJECT: "empty-object";
+    /**
+     * THE SURVEY WAS NEVER ASKED FOR: the operator's money ceiling was already
+     * spent when the first attempt came due, so no call was made. Named as its own
+     * cause for the reason this enum exists at all — a new route to ABSENT has to
+     * be named, and naming it is the moment somebody decides whether it retries.
+     * This one does not, and cannot: a retry is precisely what the cap forbade.
+     * It is deliberately ABSENT of the model's own doing, and the prose says so —
+     * "the scout did not complete" would blame a model that never spoke.
+     */
+    NOT_FUNDED: "not-funded";
+}>;
+/**
+ * THE MALFORMED CLASS — the only causes a retry fires on.
+ *
+ * What is deliberately NOT here, and why:
+ *   - `call-failed` covers `truncated:max_tokens` and every transport death.
+ *     Standing doctrine routes both as provider-red with NO redraft; a retry
+ *     here would pay for the same failure again under a different name.
+ *   - `short` is F59's cut-off population, and it already has an instrument: the
+ *     reserved TOOLLESS recovery round, which fires inside the attempt.
+ *   - `non-object` and `empty-object` are VALID JSON with wrong or vacuous
+ *     content. That is a SEMANTIC failure, and F38/F39 measured what re-asking
+ *     one buys: the same distribution, sampled twice. Reacting to content is a
+ *     designed loop; this is a retry. The line between them is the self-healing
+ *     line, and it is not crossed here.
+ */
+/** @type {readonly string[]} */
+export const SCOUT_RETRY_CAUSES: readonly string[];
+/**
+ * THE GRANT: the full menu MINUS every write-class and store-class verb.
+ * Read-only by MENU CONSTRUCTION — no write-class tool object is ever built, so
+ * there is nothing for a fence to have to refuse. Derived from the shipped
+ * constants so a verb added to `TOOL_MENU` is covered the day it lands.
+ */
+export const AUTHOR_SCOUT_VERBS: readonly string[];
+export const SCOUT_SYSTEM: string;
+/**
+ * F59's reserved round, as a FIXED constant. The round is toolless BY
+ * CONSTRUCTION (`defs` is `[]`, so text is the only output the model can
+ * produce) — never by asking politely in prose (F19/F37).
+ */
+export const SCOUT_RECOVERY_PROMPT: string;
+/** per-path full-listing cap; over it, names give way to counted directories */
+export const LIST_CAP: 40;
+/** whole-block ceiling — the block is a prompt ingredient, like the survey */
+export const LISTING_BYTE_CAP: 12000;
+/** how many bare file NAMES survive the deepest tier of a flat directory */
+export const COUNTS_ONLY_NAMES: 12;
+export function cleanEntry(e: any): string;
+export type SurveyMeta = {
+    bytes: number;
+    rounds: number;
+    bounded: boolean;
+    recovered: boolean;
+    error: string | null;
+    attempts?: number;
+    attemptsAllowed?: number;
+};
+export type Survey = {
+    state: "PRESENT" | "ABSENT";
+    facts: any;
+    reason: string | null;
+    cause: string | null;
+    meta: SurveyMeta;
+};
+import { scrubRaw } from './text.js';