kestrel.markets/dist/blotter/model-registry.js

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # blotter/model-registry — the MODEL_KNOWLEDGE_CUTOFF fence + the pinned month-boundary rule (kestrel-m9i.23)
 *
 * The declared `envelope.training_cutoff` (a57.14) is the basis for **model-relative holdback**: a tape
 * date is "post-cutoff" (holdback-eligible, ranking) iff it falls after the model's knowledge cutoff. A
 * DECLARED cutoff is only trustworthy if it AGREES with the platform model registry — so this module is the
 * ONE place that holds all three pieces of that verification, co-located so the boundary logic is never
 * duplicated (SYSTEM-PROFILE.md line 41; the [PLANNED kestrel-m9i.23] item resolved here):
 *
 *   1. {@link MODEL_KNOWLEDGE_CUTOFF} — the fence: model id → knowledge-cutoff month (`YYYY-MM`). The local
 *      MIRROR of the platform `fence.ts` registry (attestation-side, ATT — this repo verifies against a
 *      pinned copy; it never mutates the platform fence). Keyed by the model id, closed by construction: an
 *      id with no entry is UNKNOWN (fail-closed), never an open default.
 *   2. {@link isPostCutoff} — the SOLE month-boundary rule: a tape date is post-cutoff IFF *strictly after
 *      the last day of the declared cutoff month*. Declared `2025-10` gates through `2025-10-31` inclusive;
 *      `2025-11-01` is the first post-cutoff day. This is the only place the boundary is computed — the
 *      post-cutoff *classification* (kestrel-m9i.25) consumes this function, never a second copy of the rule.
 *   3. {@link checkTrainingCutoff} — the fail-closed lookup + declared-vs-registry cross-check. Returns the
 *      registry cutoff when the declared value is consistent, else a typed {@link TrainingCutoffReason}
 *      (unknown model id | declared-vs-registry mismatch) NAMING the disagreement — never a silent default,
 *      never a silent correction of the declared value. The a57.14 projector ({@link ./project.ts}) renders
 *      the reason's `detail` onto `certification.reasons` and fails the Blotter closed to PROVISIONAL.
 *
 * PURE and DETERMINISTIC (RUNTIME §0): every export is a function of its arguments (the model id, the
 * declared cutoff, the tape date) — no wall clock, no RNG, no I/O. The `TrainingCutoffReason` type lives in
 * the built-in-free bus leaf (`../bus/types.ts`, `import type` only) so this module pulls no Bun/node
 * built-in into the light type graph (kestrel-exx: no bus BARREL import on a light-reachable path).
 */
/**
 * The **model knowledge-cutoff fence** (kestrel-m9i.23): model id → knowledge-cutoff month (`YYYY-MM`). The
 * local mirror of the platform `fence.ts` `MODEL_KNOWLEDGE_CUTOFF` registry — a declared `training_cutoff`
 * is cross-checked against the entry for its model id. Keyed by the model id; an id absent here is UNKNOWN
 * and fails closed (never treated as post- or pre-cutoff). The entries are the model ids the graded fixtures
 * declare; a new registered model is added HERE (one definition, no drift), matching the platform fence.
 */
export const MODEL_KNOWLEDGE_CUTOFF = {
    "acme-lm-1": "2025-10",
    "acme-lm-2": "2025-10",
    "claude-haiku-4-5": "2025-02",
    // NOTE: `kimi-k3` is DELIBERATELY absent — its cutoff is unpublished, so it fails closed
    // (unknown-model-id). See CUTOFF_UNKNOWN_PENDING below; move it here with a real YYYY-MM once published.
};
/**
 * DELIBERATELY-UNREGISTERED models — KNOWN to the roster/lanes but kept OUT of {@link MODEL_KNOWLEDGE_CUTOFF}
 * because their training-knowledge cutoff is UNPUBLISHED. Absence from the fence above is the fail-closed
 * marker (an id with no cutoff entry is UNKNOWN ⇒ {@link checkTrainingCutoff} returns `unknown-model-id`, so
 * the row can never certify as post-cutoff). This constant makes that omission EXPLICIT and greppable — the
 * difference between "we forgot" and "we know, and it is deliberately fail-closed until the model card
 * publishes the cutoff". Register the real `YYYY-MM` by MOVING the id INTO the map above the moment it is
 * published; do NOT guess a cutoff (a guessed cutoff would gate contamination on a fiction). The value here
 * is the HUMAN REASON, never a cutoff month — nothing reads it as a boundary.
 *
 * kestrel-2ojt (owner directive 2026-07-17): Kimi K3 (`kimi-k3` / gateway `moonshotai/kimi-k3`) shipped
 * 2026-07-16; weights + model card land 2026-07-27; Moonshot has published NO training cutoff. Until it
 * does, K3 is fail-closed here and CANNOT enter the post-cutoff corpus window. A brand-new model's RECENT
 * cutoff also SHRINKS its post-cutoff window (less untrained tape to grade over) — flag for the corpus
 * program. The platform mirror `apps/api/src/bench/fence.ts` (DAY granularity, `YYYY-MM-DD`) needs the same
 * deliberate omission; that is a platform-side follow-up, not editable from this OSS repo.
 */
export const CUTOFF_UNKNOWN_PENDING = {
    "kimi-k3": "training cutoff UNPUBLISHED as of 2026-07-17 (shipped 2026-07-16; weights + card 2026-07-27) — fail-closed until Moonshot publishes it (kestrel-2ojt)",
};
/**
 * The SOLE month-boundary rule (kestrel-m9i.23): a tape date is **post-cutoff IFF strictly after the last
 * day of the declared cutoff month**. For zero-padded ISO tokens that is exactly the tape date's own
 * `YYYY-MM` being lexicographically greater than the cutoff's `YYYY-MM`: any day WITHIN the cutoff month —
 * including its last day — shares the month key and is NOT after it, and the first day of the following month
 * is the first strictly-greater key (the year-wrap is handled by the fixed-width comparison, so a `2025-12`
 * cutoff gates through `2025-12-31` and `2026-01-01` is post-cutoff). Declared `2025-03` ⇒ `2025-03-31` is
 * NOT post-cutoff, `2025-04-01` IS. Pure and deterministic — no wall clock (RUNTIME §0). This is the ONLY
 * place the boundary is computed; consumers (post-cutoff classification, kestrel-m9i.25) call it, never fork it.
 *
 * @param cutoffMonth the declared cutoff month (`YYYY-MM`)
 * @param tapeDate    the tape/session date (`YYYY-MM-DD`)
 */
export function isPostCutoff(cutoffMonth, tapeDate) {
    return tapeDate.slice(0, 7) > cutoffMonth;
}
/**
 * The fail-closed lookup + declared-vs-registry cross-check (kestrel-m9i.23), keyed by the model id. An
 * attestation-side VERIFICATION (ATT), never a rewrite:
 *
 *   - the model id has NO registry entry ⇒ `unknown-model-id`: the declared cutoff cannot be verified, so the
 *     row cannot certify as post-cutoff (NOT silently treated as post- or pre-cutoff);
 *   - the model id is registered but the declared cutoff DISAGREES with the registry's ⇒
 *     `declared-registry-mismatch`: the declared value is RECORDED verbatim (never rewritten to the
 *     registry's), with both cutoffs named;
 *   - otherwise the declared cutoff matches the registry ⇒ `ok`, carrying the registry cutoff month.
 *
 * Pure and deterministic — a function of the model id + the declared cutoff alone (no wall clock, no RNG).
 */
export function checkTrainingCutoff(input) {
    const { model, declaredCutoff } = input;
    const registry = MODEL_KNOWLEDGE_CUTOFF[model];
    if (registry === undefined) {
        return {
            ok: false,
            reason: {
                kind: "unknown-model-id",
                model,
                declared: declaredCutoff,
                detail: `training_cutoff: model id '${model}' is not in the MODEL_KNOWLEDGE_CUTOFF registry — the declared cutoff ` +
                    `'${declaredCutoff}' cannot be verified; the row is not treated as post- or pre-cutoff (fail-closed, kestrel-m9i.23). ` +
                    `REMEDY: run the Knowledge-Horizon Eval (kestrel-cf62) and register an 'empirically-bounded' cutoff source ` +
                    `(see registerEmpiricalBound / docs/research/knowledge-horizon-eval.md)`,
            },
        };
    }
    if (registry !== declaredCutoff) {
        return {
            ok: false,
            reason: {
                kind: "declared-registry-mismatch",
                model,
                declared: declaredCutoff,
                registry,
                detail: `training_cutoff: declared '${declaredCutoff}' disagrees with the registry cutoff '${registry}' for model id ` +
                    `'${model}' — the declared value is recorded, never rewritten to the registry's (fail-closed, kestrel-m9i.23)`,
            },
        };
    }
    return { ok: true, cutoffMonth: registry };
}
/**
 * The empirically-bounded registry (kestrel-cf62): model id → measured cutoff source. Populated by a
 * probe run via {@link registerEmpiricalBound}; consulted alongside the vendor-published fence. Keyed by
 * the EXACT model id the probe reported (version-pinning). Starts empty — a bound exists only once measured.
 */
export const EMPIRICAL_CUTOFF_BOUNDS = {};
/**
 * The VERSION-PINNING gate (kestrel-cf62, PR #300 F4): an `empirically-bounded` source is only
 * acceptable if it carries a non-empty `probeRunId` AND a non-empty `reportedModelId` that AGREES
 * with the model id being registered AND a non-empty `curveArtifact` AND a non-negative margin AND a
 * well-formed `YYYY-MM` cutoff. An unpinned bound (no run id / no artifact) or a MISMATCHED pin (the
 * probe's provider-reported model id is not the id being filed) is REFUSED — a registry entry must
 * always trace to the exact probe AND the exact model version that produced it. Pure and
 * deterministic.
 *
 * @param model the registry key the bound is being validated FOR (the requested seat id)
 */
export function validateEmpiricalBound(model, source) {
    if (!/^\d{4}-\d{2}$/.test(source.cutoffMonth)) {
        return { ok: false, detail: `empirical bound cutoffMonth '${source.cutoffMonth}' is not a YYYY-MM month` };
    }
    if (source.probeRunId.trim() === "") {
        return { ok: false, detail: "empirical bound is UNPINNED: probeRunId is empty (version-pinning gate, kestrel-cf62)" };
    }
    if (source.reportedModelId.trim() === "") {
        return { ok: false, detail: "empirical bound is UNPINNED: reportedModelId is empty (version-pinning gate, PR #300 F4)" };
    }
    if (source.reportedModelId !== model) {
        return {
            ok: false,
            detail: `empirical bound VERSION-PIN MISMATCH: probe run '${source.probeRunId}' reported model id ` +
                `'${source.reportedModelId}' but is being registered for '${model}' — a bound measured on one model ` +
                `version is never filed under another id (kestrel-cf62, PR #300 F4)`,
        };
    }
    if (source.curveArtifact.trim() === "") {
        return { ok: false, detail: "empirical bound is UNPINNED: curveArtifact is empty (version-pinning gate, kestrel-cf62)" };
    }
    if (!Number.isFinite(source.margin) || source.margin < 0) {
        return { ok: false, detail: `empirical bound margin '${source.margin}' must be a non-negative number of months` };
    }
    return { ok: true, source };
}
/**
 * Register a measured bound for a model id (the remedy the unknown-model-id path names). Passes the
 * version-pinning gate first — an unpinned bound is never registered. Returns the check so callers can
 * surface the refusal. Keyed by the exact reported model id.
 */
export function registerEmpiricalBound(model, source) {
    const check = validateEmpiricalBound(model, source);
    if (check.ok)
        EMPIRICAL_CUTOFF_BOUNDS[model] = source;
    return check;
}
/**
 * Resolve a model id's cutoff from EITHER source: the vendor-published fence takes precedence (it is the
 * attested spec), else a validated empirical bound if one has been measured. Returns null when neither
 * exists — still fail-closed, but now the caller knows to run the probe.
 */
export function resolveCutoffSource(model) {
    const vendor = MODEL_KNOWLEDGE_CUTOFF[model];
    if (vendor !== undefined)
        return { kind: "vendor-published", cutoffMonth: vendor };
    const empirical = EMPIRICAL_CUTOFF_BOUNDS[model];
    if (empirical !== undefined && validateEmpiricalBound(model, empirical).ok)
        return empirical;
    return null;
}