agent-nuvira 3.3.12 → 3.3.14

package/dist/learning/outcome-observation.js

@@ -0,0 +1,95 @@
+/**
+ * Turn outcome → router learning signal.
+ *
+ * WHY THIS EXISTS. `RouterBandit` has always carried a measured-quality reward model — `testPassed`,
+ * `userAccepted`, `verificationPassed`, `qualityScore` — with arms for the provider AND the concrete
+ * model, and `applyReward` already folds all four into the reward. But nothing on the real path ever
+ * filled it in: `AutoModelRouter.recordOutcome` forwarded `undefined` to every arm, so the reward was
+ * a cost-adjusted coin flip on "the agent did not throw". That is the D2 defect one layer down — a
+ * response that was empty or useless still counted as a success for the purpose of learning.
+ *
+ * The harness ALREADY derives the honest signal: `TurnReport.verification` is built from recorded tool
+ * and plan evidence and can never be talked up by the model's narration. This module is the single
+ * pure translation between that verdict and the learning payload, so the mapping is ONE reviewable
+ * decision instead of a payload assembled ad hoc at each call site.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO.
+ * - It records NOTHING when the report carries no verdict about the model. A plain answer with no
+ *   plan and no changes is not evidence of quality, and inventing a neutral sample for it would
+ *   dilute the samples that are real.
+ * - It never GUESSES a `qualityScore`. It now carries one — but only from the FITTED
+ *   acceptance model (`acceptance-model.ts`), which is a measured scale built from the user's own
+ *   verdicts and which refuses to fit below its sample floor. On a machine with too few ratings the
+ *   field is absent, exactly as before: a made-up number written into a learning record is worse
+ *   than a missing one, because the record outlives whoever knows it was fabricated.
+ *   (`NUVIRA_BANDIT_QUALITY=off` disables it outright.)
+ * - It never attributes an environmental failure to the model: a `blocked` turn is a wall the run hit,
+ *   not a capability verdict.
+ */
+import { cachedAcceptanceFit, featuresFromReport, predictAcceptance, } from './acceptance-model.js';
+import { envBuff } from '../config/paths.js';
+/**
+ * The Q off-switch. Unset/empty = ON; an explicit OFF word disables the measured
+ * quality score so the router falls back to the derived signals it always had.
+ * (`NUVIRA_BANDIT_QUALITY=off`.)
+ */
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+export function banditQualityEnabled() {
+    const v = envBuff('BANDIT_QUALITY');
+    if (v === undefined || v === '')
+        return true;
+    return !OFF_WORDS.has(v.toLowerCase());
+}
+/**
+ * The measured `qualityScore` for a turn, or `undefined`.
+ *
+ * `undefined` is the honest default: the fitted acceptance model refuses below
+ * its sample floor, so on a machine with too few ratings the router learns
+ * exactly what it learned before. A number is written ONLY when a trained model
+ * exists — never a guessed constant (see `DESIGN_CAPABILITY_BY_MEASUREMENT.md`).
+ */
+function qualityScoreForTurn(report, opts) {
+    const features = featuresFromReport(report);
+    if (opts.qualityScoreFor)
+        return opts.qualityScoreFor(features);
+    if (!banditQualityEnabled())
+        return undefined;
+    const fit = cachedAcceptanceFit();
+    return fit.ok ? predictAcceptance(fit.model, features) : undefined;
+}
+/**
+ * Map a turn's verification verdict to what the router should learn from it.
+ * Returns `null` when the turn carries no evidence about the model.
+ */
+export function turnOutcomeObservation(report, opts = {}) {
+    if (!report)
+        return null;
+    // ACCURACY EVIDENCE — the turn's own checks, when it ran any. `checksPassed` is
+    // tri-state precisely so that "nobody checked" contributes no `testPassed` sample:
+    // a plain question and a failing test suite must not teach the same lesson.
+    const checkData = report.checksPassed === undefined ? {} : { testPassed: report.checksPassed };
+    // MEASURED QUALITY — the one input derived signals cannot supply (was the work
+    // WANTED, not just "did it verify"). Present only when the acceptance model has
+    // trained on enough of the user's own verdicts; otherwise omitted entirely.
+    const quality = qualityScoreForTurn(report, opts);
+    const qualityData = quality === undefined ? {} : { qualityScore: quality };
+    switch (report.verification) {
+        case 'verified':
+            // A change was made and an observation followed it.
+            return { outcome: 'success', outcomeData: { verificationPassed: true, ...checkData, ...qualityData } };
+        case 'unverified':
+            // The turn ran, and its work could not be confirmed (an edit with no
+            // observation, an honesty flag, or an unobserved mutation). Booked as a
+            // success WITH `verificationPassed: false` rather than as a hard failure:
+            // the model DID answer, and the reward model's own penalty for an
+            // unverified success is the calibrated weight for exactly this shape.
+            // Calling it a failure outright would double-penalise one event.
+            return { outcome: 'success', outcomeData: { verificationPassed: false, ...checkData, ...qualityData } };
+        default:
+            // 'blocked' — a step could not complete (often environmental, not the
+            // model's doing). 'not-applicable' — nothing checkable happened. Neither
+            // is evidence about the model, so neither is recorded.
+            return null;
+    }
+}
+//# sourceMappingURL=outcome-observation.js.map

package/dist/learning/outcome-observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome-observation.js","sourceRoot":"","sources":["../../src/learning/outcome-observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAElB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAO7C;;;;GAIG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvD,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACzC,CAAC;AAUD;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAC1B,MAAkB,EAClB,IAA4B;IAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC,oBAAoB,EAAE;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;IAClC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAqC,EACrC,OAA+B,EAAE;IAEjC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,gFAAgF;IAChF,mFAAmF;IACnF,4EAA4E;IAC5E,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;IAC/F,+EAA+E;IAC/E,gFAAgF;IAChF,4EAA4E;IAC5E,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC3E,QAAQ,MAAM,CAAC,YAAY,EAAE,CAAC;QAC5B,KAAK,UAAU;YACb,oDAAoD;YACpD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,SAAS,EAAE,GAAG,WAAW,EAAE,EAAE,CAAC;QACzG,KAAK,YAAY;YACf,qEAAqE;YACrE,wEAAwE;YACxE,0EAA0E;YAC1E,kEAAkE;YAClE,sEAAsE;YACtE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,GAAG,SAAS,EAAE,GAAG,WAAW,EAAE,EAAE,CAAC;QAC1G;YACE,sEAAsE;YACtE,yEAAyE;YACzE,uDAAuD;YACvD,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/learning/pair-entitlement.d.ts

@@ -0,0 +1,184 @@
+/**
+ * PAIR ENTITLEMENT — of two providers that both list the same model, which one
+ * can actually serve it RIGHT NOW?
+ *
+ * THE DEFECT THIS CLOSES (reported 2026-10-07). Four providers list a DeepSeek
+ * model. One key genuinely has access to it; on the others the account has no
+ * model access and no free tokens. Ranking is per MODEL, so all four twins
+ * present the same capability rank — and the router, ordering on rank (and, on
+ * a tie, on whichever provider it happened to score first), could spend the
+ * turn's first call on a pair the registry had ALREADY recorded as refused:
+ * a `402 Insufficient credits` / `403` / `credit-exhausted` round trip, then a
+ * failover, then the turn finally starts. Measured in run D of this programme:
+ * a strict pin at `openrouter/deepseek/deepseek-v4.1-flash` failed in 6 SECONDS
+ * with `402 Insufficient credits` — while `deepseek/deepseek-flash`, the same
+ * model on a funded account, sat in the pool.
+ *
+ * The registry already knew. `ModelRegistryEntry` carries `status`,
+ * `lastError`, `deadPair` and `quotaParkedUntil` for every provider × model
+ * pair, and two predicates in `model-registry.ts` interpret them
+ * (`isEntitlementFailure`, `isNonexistentPair`). What did not exist was a single
+ * answer to "may the router call THIS PAIR", asked before the call instead of
+ * after it.
+ *
+ * ─── DOCTRINE (read before changing the order below) ───────────────────────
+ *
+ * 1. **The verdict is per PAIR, never per model.** `openrouter`'s exhausted
+ *    credit balance and `deepseek`'s funded account are facts about two
+ *    different ACCOUNTS. Two twins may share a canonical model id and still
+ *    have opposite verdicts, and each verdict is read from ITS OWN registry row.
+ *    Nothing here ever infers "this provider is funded because its twin is" —
+ *    that is the F6 defect (an availability verdict erased by unrelated
+ *    evidence) wearing a new hat.
+ * 2. **A refusal is a NO, and it is FINAL while a funded alternative exists.**
+ *    `refused` means the account cannot serve this pairing: no credits, no
+ *    billing, a rejected key, or the id does not exist on that endpoint. None
+ *    of those are repaired by retrying, so a refused pair is never picked while
+ *    anything else can be. `stalled` (a quota park, or proof that aged out) is
+ *    the opposite: it clears by itself, so it stays eligible and simply sinks.
+ * 3. **Never dead-end.** This module never REMOVES a candidate — it orders them
+ *    (`orderByEntitlement` is a stable partition). If every provider refuses the
+ *    model, the refused pairs are still there, in their old relative order, and
+ *    the router can still try them. "Use every model we can actually call;
+ *    reject only when nothing is left" survives.
+ * 4. **Ties go to the funded twin.** The user's rule, verbatim: "the rank of a
+ *    model can be the same across providers, but the agent should only pick the
+ *    one which has genuine token budget available". Because the ordering is a
+ *    partition applied AFTER scoring, a funded twin outranks a refused twin even
+ *    when the refused twin scored higher — a rank advantage cannot buy a call
+ *    that is certain to fail.
+ *
+ * The labels below are printed (`model explain`, the fallback chain), so an
+ * operator can see WHY a twin was passed over instead of having to guess.
+ */
+/**
+ * What the registry says about ONE provider × model pair's right to be called.
+ *
+ * Four states, not a boolean, because they need OPPOSITE handling and a
+ * two-valued answer would flatten them into one: `refused` is a permanent no
+ * (skip it), `stalled` is a temporary no (it may recover, so keep it), `unknown`
+ * is not a failure at all (never tried), and `funded` is a proven yes.
+ */
+export type PairEntitlement = 
+/** Verified and usable right now — a real call proved THIS ACCOUNT serves THIS model. */
+'funded'
+/** No entry, or an unverified one. Nothing has ever been tried: an unknown, not a failure. */
+ | 'unknown'
+/** Provably served before, but not right now, for a reason that clears by itself (quota park, stale proof, a transient failure). */
+ | 'stalled'
+/** The account was REFUSED this pairing: credit-exhausted / auth / billing / 40x, or the id does not exist on that endpoint. */
+ | 'refused';
+/** The fields of a registry row this classifier reads. Deliberately minimal. */
+export interface EntitlementInput {
+    status?: string;
+    lastError?: string;
+    deadPair?: boolean;
+    quotaParkedUntil?: number;
+    providerParked?: boolean;
+    lastVerifiedAt?: number;
+}
+/**
+ * Classify one pair. Pure and total — never throws, never returns undefined.
+ *
+ * CLAUSE ORDER IS LOAD-BEARING, and `status` comes FIRST — exactly as in
+ * `classifyReachability`. That is not cosmetic; getting it backwards creates a
+ * brand-new false refusal:
+ *
+ *   - `verified` is a LATCH. Two different writes can leave a row `verified`
+ *     while an old refusal still sits in `lastError`: `markVerified`
+ *     deliberately PRESERVES `lastError` across a success (it rebuilds the entry
+ *     field by field and keeps `existing?.lastError`), and `recordCall` succeeds
+ *     through `markVerified`. So after a user tops up their credits and the next
+ *     call works, the row is `verified` + `"credit-exhausted (…)"` — the model is
+ *     being served RIGHT NOW.
+ *   - Checking `isEntitlementFailure(lastError)` before `status` would call that
+ *     pair refused and skip the funded account we just proved works. It is the
+ *     same mistake in the other direction (a stale verdict outranking fresh
+ *     evidence), so an entitlement refusal only counts while the entry is still
+ *     sitting in the state that refusal produced — the registry's own guard,
+ *     `existing?.status === 'unavailable' && isEntitlementFailure(...)` in
+ *     `markListed`.
+ *
+ * The clauses:
+ *
+ *   1. A NONEXISTENT pair is refused whatever the status says: `deadPair` is an
+ *      explicit "this id does not exist on this endpoint" and the provider's own
+ *      model list is what clears it. (`isNonexistentPair` also covers an
+ *      `unavailable` row whose recorded reason is a not-found — legacy data.)
+ *   2. `unverified` / absent is `unknown` — never a failure. Most of any registry
+ *      is here, and treating "never tried" as "cannot work" would empty the pool.
+ *   3. `unavailable` + an entitlement reason is `refused` (credit-exhausted /
+ *      auth / billing / 40x — what run D hit). Any other `unavailable` reason is
+ *      `stalled`: rate limits, timeouts and 5xx are transient by the registry's
+ *      own doctrine and must not be treated as a permanent no.
+ *   4. A `verified` entry is `funded` unless a MODEL-level park or a stale proof
+ *      holds it back. A PROVIDER-level park does not count — that is the Gemini
+ *      parking bug, and `isUsable()` skips it for proven models too.
+ */
+export declare function classifyPairEntitlement(entry: EntitlementInput | undefined, now?: number): PairEntitlement;
+/**
+ * The pick order: funded, then never-tried, then stalled, then refused.
+ *
+ * `unknown` deliberately outranks `stalled`: `stalled` is "no budget right
+ * now" (the exact thing this module exists to avoid spending a round on), while
+ * `unknown` may simply work. This also matches how the model scorer already
+ * weights the two (`quotaAvailability` 0.6 for unverified vs 0.0 for parked).
+ */
+export declare const ENTITLEMENT_ORDER: Record<PairEntitlement, number>;
+/**
+ * Stable partition of candidates by entitlement — funded pairs first, refused
+ * pairs last, everything else untouched inside its group (and the input array
+ * never mutated). A PARTITION and not a filter: see doctrine 3 (never dead-end).
+ */
+export declare function orderByEntitlement<T>(items: readonly T[], of: (item: T) => PairEntitlement): T[];
+/** Short chip for a verdict — CLI/dashboard labels. */
+export declare const ENTITLEMENT_LABEL: Record<PairEntitlement, string>;
+/**
+ * One sentence naming the EVIDENCE, not just the verdict — an operator reading
+ * `model explain` has to be able to tell a refused account from an untried one.
+ */
+export declare function entitlementNote(entitlement: PairEntitlement, entry?: EntitlementInput): string;
+/**
+ * The model id two rows must share before they are treated as the same model
+ * offered by different providers — the "twins" the user's rule is about.
+ *
+ * A1 (2026-10-07): the rule is now `learning/model-identity.ts` — an EXACT
+ * comparison against a bare or `vendor/`-prefixed id, WIDENED by the DECLARED
+ * alias table and never by similarity. That widening is what relates
+ * `openrouter/deepseek/deepseek-v4.1-flash` to `deepseek/deepseek-flash` (the two
+ * rows a run-D 402 pin needed related), while `deepseek-flash` and
+ * `deepseek-v4-flash` stay separate because no declaration relates them.
+ *
+ * Grouping is the only thing identity does here. A verdict is still read from
+ * each twin's OWN row — see the doctrine at the top of this file.
+ */
+export declare function twinKey(model: string): string;
+/** Do these two model ids name the same model served by different providers? */
+export declare function areTwins(a: string, b: string): boolean;
+/** One twin in a same-model group, with the verdict read from ITS OWN row. */
+export interface TwinVerdict<T> {
+    item: T;
+    provider: string;
+    model: string;
+    entitlement: PairEntitlement;
+    note: string;
+}
+/**
+ * Resolve a group of SAME-MODEL twins to the one the router may call, and say
+ * what was passed over and why.
+ *
+ * This is the user's requirement as a function: identical ranks, one funded
+ * twin, so the funded twin is the only acceptable pick — and each twin's verdict
+ * comes from its own registry row (doctrine 1). The refused ones come back in
+ * `passedOver` so the caller can PRINT them ("`openrouter` refuses this model —
+ * credit-exhausted") instead of silently pretending they were never there.
+ *
+ * Never returns nothing when the group is non-empty: if EVERY twin is refused,
+ * the first is still chosen (doctrine 3 — a certain failure beats no attempt at
+ * all only when there is genuinely nothing else, and the caller decides).
+ */
+export declare function resolveFundedTwin<T>(twins: readonly TwinVerdict<T>[]): {
+    chosen?: TwinVerdict<T>;
+    passedOver: TwinVerdict<T>[];
+};
+//# sourceMappingURL=pair-entitlement.d.ts.map

package/dist/learning/pair-entitlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-entitlement.d.ts","sourceRoot":"","sources":["../../src/learning/pair-entitlement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAKH;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe;AACzB,yFAAyF;AACvF,QAAQ;AACV,8FAA8F;GAC5F,SAAS;AACX,oIAAoI;GAClI,SAAS;AACX,gIAAgI;GAC9H,SAAS,CAAC;AAEd,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,GAAG,GAAE,MAAmB,GACvB,eAAe,CAgBjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAK7D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,eAAe,GAAG,CAAC,EAAE,CAIhG;AAED,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAK7D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAmB9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,eAAe,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,GAC/B;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,CAO3D"}

package/dist/learning/pair-entitlement.js

@@ -0,0 +1,214 @@
+/**
+ * PAIR ENTITLEMENT — of two providers that both list the same model, which one
+ * can actually serve it RIGHT NOW?
+ *
+ * THE DEFECT THIS CLOSES (reported 2026-10-07). Four providers list a DeepSeek
+ * model. One key genuinely has access to it; on the others the account has no
+ * model access and no free tokens. Ranking is per MODEL, so all four twins
+ * present the same capability rank — and the router, ordering on rank (and, on
+ * a tie, on whichever provider it happened to score first), could spend the
+ * turn's first call on a pair the registry had ALREADY recorded as refused:
+ * a `402 Insufficient credits` / `403` / `credit-exhausted` round trip, then a
+ * failover, then the turn finally starts. Measured in run D of this programme:
+ * a strict pin at `openrouter/deepseek/deepseek-v4.1-flash` failed in 6 SECONDS
+ * with `402 Insufficient credits` — while `deepseek/deepseek-flash`, the same
+ * model on a funded account, sat in the pool.
+ *
+ * The registry already knew. `ModelRegistryEntry` carries `status`,
+ * `lastError`, `deadPair` and `quotaParkedUntil` for every provider × model
+ * pair, and two predicates in `model-registry.ts` interpret them
+ * (`isEntitlementFailure`, `isNonexistentPair`). What did not exist was a single
+ * answer to "may the router call THIS PAIR", asked before the call instead of
+ * after it.
+ *
+ * ─── DOCTRINE (read before changing the order below) ───────────────────────
+ *
+ * 1. **The verdict is per PAIR, never per model.** `openrouter`'s exhausted
+ *    credit balance and `deepseek`'s funded account are facts about two
+ *    different ACCOUNTS. Two twins may share a canonical model id and still
+ *    have opposite verdicts, and each verdict is read from ITS OWN registry row.
+ *    Nothing here ever infers "this provider is funded because its twin is" —
+ *    that is the F6 defect (an availability verdict erased by unrelated
+ *    evidence) wearing a new hat.
+ * 2. **A refusal is a NO, and it is FINAL while a funded alternative exists.**
+ *    `refused` means the account cannot serve this pairing: no credits, no
+ *    billing, a rejected key, or the id does not exist on that endpoint. None
+ *    of those are repaired by retrying, so a refused pair is never picked while
+ *    anything else can be. `stalled` (a quota park, or proof that aged out) is
+ *    the opposite: it clears by itself, so it stays eligible and simply sinks.
+ * 3. **Never dead-end.** This module never REMOVES a candidate — it orders them
+ *    (`orderByEntitlement` is a stable partition). If every provider refuses the
+ *    model, the refused pairs are still there, in their old relative order, and
+ *    the router can still try them. "Use every model we can actually call;
+ *    reject only when nothing is left" survives.
+ * 4. **Ties go to the funded twin.** The user's rule, verbatim: "the rank of a
+ *    model can be the same across providers, but the agent should only pick the
+ *    one which has genuine token budget available". Because the ordering is a
+ *    partition applied AFTER scoring, a funded twin outranks a refused twin even
+ *    when the refused twin scored higher — a rank advantage cannot buy a call
+ *    that is certain to fail.
+ *
+ * The labels below are printed (`model explain`, the fallback chain), so an
+ * operator can see WHY a twin was passed over instead of having to guess.
+ */
+import { DEFAULT_STALE_MS, isEntitlementFailure, isNonexistentPair } from './model-registry.js';
+import { identityKey, sameModel } from './model-identity.js';
+/**
+ * Classify one pair. Pure and total — never throws, never returns undefined.
+ *
+ * CLAUSE ORDER IS LOAD-BEARING, and `status` comes FIRST — exactly as in
+ * `classifyReachability`. That is not cosmetic; getting it backwards creates a
+ * brand-new false refusal:
+ *
+ *   - `verified` is a LATCH. Two different writes can leave a row `verified`
+ *     while an old refusal still sits in `lastError`: `markVerified`
+ *     deliberately PRESERVES `lastError` across a success (it rebuilds the entry
+ *     field by field and keeps `existing?.lastError`), and `recordCall` succeeds
+ *     through `markVerified`. So after a user tops up their credits and the next
+ *     call works, the row is `verified` + `"credit-exhausted (…)"` — the model is
+ *     being served RIGHT NOW.
+ *   - Checking `isEntitlementFailure(lastError)` before `status` would call that
+ *     pair refused and skip the funded account we just proved works. It is the
+ *     same mistake in the other direction (a stale verdict outranking fresh
+ *     evidence), so an entitlement refusal only counts while the entry is still
+ *     sitting in the state that refusal produced — the registry's own guard,
+ *     `existing?.status === 'unavailable' && isEntitlementFailure(...)` in
+ *     `markListed`.
+ *
+ * The clauses:
+ *
+ *   1. A NONEXISTENT pair is refused whatever the status says: `deadPair` is an
+ *      explicit "this id does not exist on this endpoint" and the provider's own
+ *      model list is what clears it. (`isNonexistentPair` also covers an
+ *      `unavailable` row whose recorded reason is a not-found — legacy data.)
+ *   2. `unverified` / absent is `unknown` — never a failure. Most of any registry
+ *      is here, and treating "never tried" as "cannot work" would empty the pool.
+ *   3. `unavailable` + an entitlement reason is `refused` (credit-exhausted /
+ *      auth / billing / 40x — what run D hit). Any other `unavailable` reason is
+ *      `stalled`: rate limits, timeouts and 5xx are transient by the registry's
+ *      own doctrine and must not be treated as a permanent no.
+ *   4. A `verified` entry is `funded` unless a MODEL-level park or a stale proof
+ *      holds it back. A PROVIDER-level park does not count — that is the Gemini
+ *      parking bug, and `isUsable()` skips it for proven models too.
+ */
+export function classifyPairEntitlement(entry, now = Date.now()) {
+    if (!entry)
+        return 'unknown';
+    // 1. "This model does not exist here" — provider-declared, status-independent.
+    if (isNonexistentPair(entry))
+        return 'refused';
+    const status = entry.status ?? 'unverified';
+    // 2. Never tried — an unknown, not a refusal.
+    if (status === 'unverified')
+        return 'unknown';
+    // 3. Unavailable: refused if the ACCOUNT was refused, otherwise a no for now.
+    if (status !== 'verified') {
+        return isEntitlementFailure(entry.lastError) ? 'refused' : 'stalled';
+    }
+    // 4. Verified: only a MODEL-level park or an aged-out proof holds it back.
+    const parkedUntil = entry.quotaParkedUntil ?? 0;
+    if (parkedUntil > now && entry.providerParked === false)
+        return 'stalled';
+    if (now - (entry.lastVerifiedAt ?? 0) > DEFAULT_STALE_MS)
+        return 'stalled';
+    return 'funded';
+}
+/**
+ * The pick order: funded, then never-tried, then stalled, then refused.
+ *
+ * `unknown` deliberately outranks `stalled`: `stalled` is "no budget right
+ * now" (the exact thing this module exists to avoid spending a round on), while
+ * `unknown` may simply work. This also matches how the model scorer already
+ * weights the two (`quotaAvailability` 0.6 for unverified vs 0.0 for parked).
+ */
+export const ENTITLEMENT_ORDER = {
+    funded: 0,
+    unknown: 1,
+    stalled: 2,
+    refused: 3,
+};
+/**
+ * Stable partition of candidates by entitlement — funded pairs first, refused
+ * pairs last, everything else untouched inside its group (and the input array
+ * never mutated). A PARTITION and not a filter: see doctrine 3 (never dead-end).
+ */
+export function orderByEntitlement(items, of) {
+    const buckets = { funded: [], unknown: [], stalled: [], refused: [] };
+    for (const item of items)
+        buckets[of(item)].push(item);
+    return [...buckets.funded, ...buckets.unknown, ...buckets.stalled, ...buckets.refused];
+}
+/** Short chip for a verdict — CLI/dashboard labels. */
+export const ENTITLEMENT_LABEL = {
+    funded: '✅ funded',
+    unknown: '❔ untried',
+    stalled: '⏸ stalled',
+    refused: '⛔ refused',
+};
+/**
+ * One sentence naming the EVIDENCE, not just the verdict — an operator reading
+ * `model explain` has to be able to tell a refused account from an untried one.
+ */
+export function entitlementNote(entitlement, entry) {
+    switch (entitlement) {
+        case 'funded':
+            return 'proven to work on this account, and nothing is blocking it right now';
+        case 'unknown':
+            return 'never tried on this provider — no evidence either way (not a failure)';
+        case 'stalled': {
+            const parkedUntil = entry?.quotaParkedUntil ?? 0;
+            if (parkedUntil > Date.now()) {
+                const mins = Math.max(1, Math.round((parkedUntil - Date.now()) / 60_000));
+                return `proven to work, but parked on its own quota window — free again in ~${mins}m`;
+            }
+            return 'proven to work once, but not provably servable right now (stale proof or a transient failure)';
+        }
+        case 'refused':
+            return isNonexistentPair(entry ?? {})
+                ? 'the provider says this model does not exist on this endpoint'
+                : `this account was refused: ${entry?.lastError ?? 'no reason recorded'}`;
+    }
+}
+/**
+ * The model id two rows must share before they are treated as the same model
+ * offered by different providers — the "twins" the user's rule is about.
+ *
+ * A1 (2026-10-07): the rule is now `learning/model-identity.ts` — an EXACT
+ * comparison against a bare or `vendor/`-prefixed id, WIDENED by the DECLARED
+ * alias table and never by similarity. That widening is what relates
+ * `openrouter/deepseek/deepseek-v4.1-flash` to `deepseek/deepseek-flash` (the two
+ * rows a run-D 402 pin needed related), while `deepseek-flash` and
+ * `deepseek-v4-flash` stay separate because no declaration relates them.
+ *
+ * Grouping is the only thing identity does here. A verdict is still read from
+ * each twin's OWN row — see the doctrine at the top of this file.
+ */
+export function twinKey(model) {
+    return identityKey(model);
+}
+/** Do these two model ids name the same model served by different providers? */
+export function areTwins(a, b) {
+    return sameModel(a, b);
+}
+/**
+ * Resolve a group of SAME-MODEL twins to the one the router may call, and say
+ * what was passed over and why.
+ *
+ * This is the user's requirement as a function: identical ranks, one funded
+ * twin, so the funded twin is the only acceptable pick — and each twin's verdict
+ * comes from its own registry row (doctrine 1). The refused ones come back in
+ * `passedOver` so the caller can PRINT them ("`openrouter` refuses this model —
+ * credit-exhausted") instead of silently pretending they were never there.
+ *
+ * Never returns nothing when the group is non-empty: if EVERY twin is refused,
+ * the first is still chosen (doctrine 3 — a certain failure beats no attempt at
+ * all only when there is genuinely nothing else, and the caller decides).
+ */
+export function resolveFundedTwin(twins) {
+    if (twins.length === 0)
+        return { passedOver: [] };
+    const ordered = [...twins].sort((a, b) => ENTITLEMENT_ORDER[a.entitlement] - ENTITLEMENT_ORDER[b.entitlement]);
+    const [chosen, ...passedOver] = ordered;
+    return { chosen, passedOver };
+}
+//# sourceMappingURL=pair-entitlement.js.map

package/dist/learning/pair-entitlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-entitlement.js","sourceRoot":"","sources":["../../src/learning/pair-entitlement.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,83 @@
+/**
+ * PROJECT DOCUMENTATION (software deliverables).
+ *
+ * The gap this closes: a software build produced CODE and stopped. The
+ * documents a real project ships — a README, a changelog that grows with each
+ * change, a short architecture note with a diagram, and (for a library/service)
+ * usage + API docs — were only produced when the user named them, which is
+ * exactly backwards: a user should not have to ask a "world-class developer" to
+ * write down what it built.
+ *
+ * Two rules keep this from becoming noise:
+ *
+ *   1. **Software only.** This module is consulted ONLY for a `code` deliverable
+ *      that is not authored (`deliverable-class.ts` already separates a poem
+ *      from a program). Nobody wants a README and an ARCHITECTURE.md for
+ *      "write me a poem about rain" — the classifier decides, and this guidance
+ *      is never appended to an authored ask.
+ *   2. **Proportionate.** A README and a CHANGELOG are expected of every
+ *      software deliverable; the heavier documents (architecture, API reference,
+ *      contributing guide) are asked for only when the shape warrants them —
+ *      a multi-component or library/service build, or an explicit request for
+ *      docs. A one-file script still gets a README; it is not asked to invent an
+ *      architecture diagram.
+ *
+ * It also encodes the maintenance rule the user cares about: an EXISTING
+ * document is UPDATED in place (CHANGELOG gets a new entry at the top), never
+ * shadowed by a second file — a project with two changelogs is worse than one
+ * with none.
+ *
+ * Pure and side-effect free: every input is data, so it is unit-testable and can
+ * be appended to any prompt without touching the filesystem.
+ */
+/** The canonical documents a software project ships, in priority order. */
+export interface ProjectDocArtifact {
+    /** Project-relative path the document lives at. */
+    path: string;
+    /** What it is FOR — handed to the model so the document has a job. */
+    purpose: string;
+    /** Required of every software deliverable (README, CHANGELOG). */
+    always: boolean;
+}
+export declare const PROJECT_DOC_ARTIFACTS: readonly ProjectDocArtifact[];
+/** What we know about the deliverable, from the goal + project assessment. */
+export interface ProjectDocShape {
+    /**
+     * True when the workspace has no project yet (a scaffold). A greenfield build
+     * gets the full proportionate set rather than only the always-on pair.
+     */
+    greenfield?: boolean;
+    /**
+     * A library, package, SDK or service — a thing other code CONSUMES — rather
+     * than an end-user app. Its public surface must be documented.
+     */
+    isLibraryOrService?: boolean;
+    /** The project already exposes tests (or the agent is expected to write them). */
+    hasTests?: boolean;
+    /** Names the user explicitly asked for docs ("with documentation", "API docs"). */
+    docsRequested?: boolean;
+    /**
+     * Documents that ALREADY exist in the workspace (project-relative paths).
+     * These are UPDATED in place, never duplicated.
+     */
+    existingDocs?: readonly string[];
+}
+/** The always-on pair, plus the heavier docs a bigger build warrants. */
+export declare function requiredProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * Does the goal name something other code CONSUMES (a library, package, SDK,
+ * CLI, service, plugin) rather than an end-user app? A consumed surface has a
+ * public API worth documenting; an app does not need an API reference.
+ */
+export declare function looksLikeLibraryOrService(goal: string): boolean;
+/** The required docs that do NOT yet exist on disk (the ones to CREATE). */
+export declare function missingProjectDocs(shape?: ProjectDocShape): string[];
+/** The required docs that already exist (the ones to UPDATE, not recreate). */
+export declare function existingProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * The instruction appended to the reasoner/planner prompt for a SOFTWARE
+ * deliverable. Returns `''` for a non-software (authored) ask, so callers can
+ * append it unconditionally without a poem ever being asked for a CHANGELOG.
+ */
+export declare function softwareProjectGuidance(verdictClass: string, authored: boolean, shape?: ProjectDocShape): string;
+//# sourceMappingURL=project-docs.d.ts.map

package/dist/learning/project-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-docs.d.ts","sourceRoot":"","sources":["../../src/learning/project-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAqC9D,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAU/D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGxE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,OAAO,EACjB,KAAK,GAAE,eAAoB,GAC1B,MAAM,CAmCR"}