bareloop 0.45.0 → 0.46.1

package/types/learn.d.ts

@@ -0,0 +1,575 @@
+/**
+ * Mask secrets and strip the working-tree prefix from a text. Pure.
+ * @param {string} text @param {string|null} workdir
+ * @returns {string}
+ */
+export function cleanText(text: string, workdir: string | null): string;
+/**
+ * A card/audit path made relative to the run's tree, or null when it is not inside it. The workdir is the
+ * authority; the patient-prefix shapes are the fallback for a spine read without one.
+ * @param {string} abs @param {string|null} workdir
+ * @returns {string|null}
+ */
+export function relPath(abs: string, workdir: string | null): string | null;
+/**
+ * Cut at a word / sentence edge, never mid-word where avoidable. Whitespace collapsed.
+ * @param {unknown} text @param {number} n @returns {string}
+ */
+export function cutText(text: unknown, n: number): string;
+/**
+ * Deep-redact every string of a plain JSON value through the ONE secret inventory (a secret in a person's repo must
+ * not enter an append-only record). Pure; returns a new value.
+ * @template T @param {T} v @returns {T}
+ */
+export function redactDeep<T>(v: T): T;
+/**
+ * The flagged text of ONE quote line (wrapper stripped), or null when the line is not a flagged line.
+ * Flagged lines: `... added <id> - <text>` and `close: [<id>] <file>:<line>: <text>` (id in the allowed list), and
+ * lines with `error TS<digits>:` or `error:`.
+ * @param {string} line @returns {string|null}
+ */
+export function flaggedText(line: string): string | null;
+/**
+ * The error-kind set of a quote: TS codes; `[id]` of `added <id>` and `close: [id]` lines; a mypy trailing bracket
+ * code; empty -> `other`. Also the files named, the first symbol, and whether the card is CHECK-SUSPECT.
+ * @param {string} text the (path-stripped) quote @param {string} [fullGap] the whole gap, for the suspect read
+ * @returns {{kinds: string[], files: string[], symbol: string|null, suspect: boolean}}
+ */
+export function errorKinds(text: string, fullGap?: string): {
+    kinds: string[];
+    files: string[];
+    symbol: string | null;
+    suspect: boolean;
+};
+/**
+ * The token set of a quote's flagged lines: lowercase runs of `[a-z0-9_]` of length >= 2, union over flagged lines.
+ * File paths, line numbers, `added <id> -`, `error TS<n>:` and the trailing mypy code are already stripped.
+ * @param {string} text @returns {string[]} sorted
+ */
+export function flaggedTokens(text: string): string[];
+/**
+ * @typedef {object} Card
+ * @property {string} id            `<runid>:<check>:<fixed|stuck>`
+ * @property {string} runid
+ * @property {string} at            the run's end (ISO)
+ * @property {string} date          YYYY-MM-DD of `at`
+ * @property {string} job           the workflow key
+ * @property {string|null} model
+ * @property {string} check         the check / close stage name
+ * @property {'FIXED'|'NEVER_FIXED'} kind
+ * @property {string} goal          Job (as written), cut
+ * @property {string|null} stepId
+ * @property {string|null} stepAction  Step (as planned), cut
+ * @property {string|null} meaning  the check's own catalogue sentence (code-owned)
+ * @property {string[]} said        It said: <= 3 lines, paths and prefixes stripped
+ * @property {number} saidMore      lines left out
+ * @property {string[]} kinds       error kinds, sorted; ['other'] when none
+ * @property {string[]} files       files the quote names, sorted
+ * @property {string|null} symbol
+ * @property {string[]} tokens      the flagged-text token set, sorted
+ * @property {string|null} nextCheck  the next failing check after this moment, if any
+ * @property {string} ended         how the run ended (job-end outcome, or its escalation word)
+ * @property {string[]} fixTouched  files written by the passing try (the try that followed the red, for NEVER FIXED)
+ * @property {{files: {path: string, diff: string, truncated: boolean, cutLines?: number}[], binary: string[], truncated: boolean}|null} whatChanged
+ *   the passing try's attempt-diff (FIXED only), as the spine capped it
+ * @property {string} key           the one-line machine key
+ */
+/**
+ * The one-line machine key of a card. Line numbers never appear in it.
+ * @param {{id: string, job: string, check: string, kinds: string[], files: string[], model: string|null, runid: string, date: string}} c
+ * @returns {string}
+ */
+export function cardKey(c: {
+    id: string;
+    job: string;
+    check: string;
+    kinds: string[];
+    files: string[];
+    model: string | null;
+    runid: string;
+    date: string;
+}): string;
+/**
+ * The lines of a gap a card quotes: lines that carry a path:line or an error code come first, accumulated up to
+ * ~250 characters (the cut the fold was fitted on). Pure.
+ * @param {string} gap @returns {string[]}
+ */
+export function quoteLines(gap: string): string[];
+/**
+ * @typedef {object} CardBuild
+ * @property {Card[]} cards         foldable cards (FIXED and NEVER FIXED), suspect and too-thin removed
+ * @property {Card[]} suspect       CHECK-SUSPECT cards: listed, never folded
+ * @property {number} thin          TOO-THIN count: no error kind and no fix files
+ * @property {string|null} noise    why the whole run was set aside (provider-red, close-crashed, worker-crash, no-close-spoke, no-job-end), else null
+ */
+/**
+ * Turn one run's record into cards. Every field is COPIED from the spine / gate audit; nothing is generated.
+ *
+ * Candidates: FIXED = a check red, then the SAME check passes later in the same run; NEVER FIXED = a check still red
+ * at run end. At most one of each per check per run (the last red before the pass; the last red). Excluded, counted:
+ * noise runs, CHECK-SUSPECT, TOO-THIN.
+ *
+ * Written files come from `attempt-diff` events (rubric `output/steps/<n>.json` included: the diff force-adds the
+ * fence) and the REAL gate audit's allow write/edit rows relative to `workdir` — never `git status`, and never a
+ * reader that drops a path it cannot place under a known patient prefix (the POC defect: a rubric job's writes read
+ * as none).
+ * `questions` is the check catalogue (stage name -> plain question, src/stagewords.js) the caller resolved from the signed
+ * spec; a check with none reads `(not in the record)`.
+ * @param {{runid: string, events: any[], audit?: any[]|null, workdir?: string|null, spec?: any, model?: string|null, questions?: Map<string, string|null>}} o
+ * @returns {CardBuild}
+ */
+export function buildCards({ runid, events, audit, workdir, spec, model, questions }: {
+    runid: string;
+    events: any[];
+    audit?: any[] | null;
+    workdir?: string | null;
+    spec?: any;
+    model?: string | null;
+    questions?: Map<string, string | null>;
+}): CardBuild;
+/** @param {{kinds: string[]}} a @param {{kinds: string[]}} b */
+export function sharedKind(a: {
+    kinds: string[];
+}, b: {
+    kinds: string[];
+}): boolean;
+/**
+ * Do two cards agree on kind? A shared error code / kind, OR (RULED 2026-10-23 R1) both carry NO code (`other`) and both
+ * have a non-empty flagged-text token set, so the text rule alone decides. A coded card never matches a code-less one.
+ * The 60% was fitted on cards WITH codes; the code-less use is UNTESTED on real data.
+ * @param {{kinds: string[], tokens: string[]}} a @param {{kinds: string[], tokens: string[]}} b
+ */
+export function kindAgrees(a: {
+    kinds: string[];
+    tokens: string[];
+}, b: {
+    kinds: string[];
+    tokens: string[];
+}): boolean;
+/** Jaccard of two token arrays; an empty side scores 0. @param {string[]} a @param {string[]} b */
+export function jaccard(a: string[], b: string[]): number;
+/**
+ * Are two cards one lesson? Same check, kinds that agree ({@link kindAgrees}: a shared code, or both code-less with text
+ * on both sides) and Jaccard >= 60% on flagged-text tokens. `sameJob: false` drops the job test (RULING 1: the cross-job rule for climbing).
+ * @param {Card} a @param {Card} b @param {{sameJob?: boolean}} [o]
+ * @returns {{match: boolean, score: number}}
+ */
+export function cardsMatch(a: Card, b: Card, { sameJob }?: {
+    sameJob?: boolean;
+}): {
+    match: boolean;
+    score: number;
+};
+/**
+ * Group cards into lessons: single-link components over eligible pairs; every pair INSIDE a component is re-checked
+ * for a shared kind, and a component with any pair lacking one splits back to singletons.
+ * @param {Card[]} cards
+ * @returns {Card[][]} groups, in first-card order; each group in input order
+ */
+export function foldCards(cards: Card[]): Card[][];
+/**
+ * @typedef {object} Row
+ * @property {string} id
+ * @property {string} lesson        ONE sentence, template-only (see {@link lessonOf})
+ * @property {number} count         runs seen; STARTS AT 1
+ * @property {Card} sample          the LATEST card
+ * @property {Record<string, number>} models  per-model counts (read-only information; never a filter)
+ * @property {string} workflow
+ * @property {string|null} place
+ * @property {'workflow'|'place'|'user'} level  STORED as 'workflow' only; the level a reader sees is derived by {@link readableRows} from the rows memory still shows (an older file's stored value is ignored and reset on the next write)
+ * @property {'deterministic'|'rubric'} trust
+ * @property {string[]} runIds
+ * @property {string} firstSeen
+ * @property {string} lastSeen
+ * @property {string|null} specHash  the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
+ * @property {string} key           check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
+ */
+/**
+ * @typedef {object} Pending
+ * @property {string} runid @property {string} at @property {string} workflow @property {string|null} place
+ * @property {string|null} specHash @property {Card[]} cards
+ */
+/**
+ * @typedef {object} Ledger
+ * @property {1} version
+ * @property {Row[]} rows
+ * @property {Pending[]} pending     rubric cards held until a human Accept (NOT counted, NOT readable)
+ * @property {Card[]} suspect        CHECK-SUSPECT cards, listed, newest last
+ * @property {Record<string, {at: string, noise: string|null, cards: number, suspect: number, thin: number}>} health  per run (idempotent by run id)
+ */
+/** @returns {Ledger} */
+export function emptyLedger(): Ledger;
+/**
+ * ONE sentence, rendered by code from the card's own fields (RULING 5, template-only).
+ * @param {Card} c @returns {string}
+ */
+export function lessonOf(c: Card): string;
+/**
+ * Fold ONE run's cards into the ledger. Pure: returns a new ledger.
+ *
+ * +1 per RUN per row: the run's own cards are folded into lessons first, and a row whose `runIds` already holds the
+ * run id is never counted twice (a resumed run, one id, never double counts). A matching lesson replaces the row's
+ * sample, bumps the model count and appends the run id (a row last seen 56+ days ago counts +1 and is read again);
+ * otherwise it opens a new row at count 1. NEVER FIXED cards count like FIXED ones (RULING 3). A workflow row of
+ * another signed hash is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
+ * @param {Ledger} ledger
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', now: Date}} o
+ * @returns {Ledger}
+ */
+export function countLedger(ledger: Ledger, { runid, cards, workflow, place, specHash, trust, now }: {
+    runid: string;
+    cards: Card[];
+    workflow: string;
+    place: string | null;
+    specHash: string | null;
+    trust: "deterministic" | "rubric";
+    now: Date;
+}): Ledger;
+/**
+ * Climbing (RULING 1): the same lesson across workflows — the section-3 rule with "same job" dropped — seen in 3
+ * distinct workflows on one place climbs to `place`; in 3 distinct places, to `user`. Derived from the rows handed in
+ * alone (every row starts at `workflow`, a stored level is ignored): {@link readableRows} hands it only the rows memory
+ * still shows, so a level drops back when siblings age out. Returns copies; keeps every run id.
+ * @param {Row[]} rows @returns {Row[]}
+ */
+export function climb(rows: Row[]): Row[];
+/**
+ * A rubric run's cards are HELD, not counted, until a human Accept (the existing quarantine is the rule). Replaces
+ * an earlier hold for the same run id (a resumed run re-derives its cards). Pure.
+ * @param {Ledger} ledger
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, at: string}} o
+ * @param {Date} now @returns {Ledger}
+ */
+export function holdPending(ledger: Ledger, { runid, cards, workflow, place, specHash, at }: {
+    runid: string;
+    cards: Card[];
+    workflow: string;
+    place: string | null;
+    specHash: string | null;
+    at: string;
+}, now: Date): Ledger;
+/**
+ * The human Accept releases a held rubric run: its cards count now (trust `rubric`). Only forward, only here. A hold
+ * older than 60 days is dropped uncounted. Idempotent (no hold = nothing to do; run ids stop a double count).
+ * @param {Ledger} ledger @param {string} runid @param {Date} now
+ * @returns {{ledger: Ledger, released: number}}
+ */
+export function releasePending(ledger: Ledger, runid: string, now: Date): {
+    ledger: Ledger;
+    released: number;
+};
+/**
+ * Record the run's health line and CHECK-SUSPECT list (idempotent by run id). Pure.
+ * @param {Ledger} ledger @param {string} runid @param {CardBuild} build @param {string} at @param {Date} now
+ * @returns {Ledger}
+ */
+export function recordHealth(ledger: Ledger, runid: string, build: CardBuild, at: string, now: Date): Ledger;
+/**
+ * The +/- content lines of a card's stored attempt-diff, in file order: only lines INSIDE a hunk that start with `+` or
+ * `-` (so `diff --git`, `index`, `---`/`+++` headers, `@@` lines, context and `\ No newline` lines never appear; a removed
+ * line that itself starts with `--` is still content once a hunk has opened). Leading indent after the sign is dropped.
+ * @param {Card['whatChanged']} wc @returns {string[]}
+ */
+export function changedLines(wc: Card["whatChanged"]): string[];
+/**
+ * The line "It said:" shows (R5): the first REAL flagged source/error line of the stored quote (the same lines the fold's
+ * flagged-text rule reads, with or without the `close:` wrapper the card already stripped), else the first line when no
+ * line is flagged (a summary such as `SPAWNER red: 3 suppression(s) added ...` is only the fallback).
+ * @param {string[]} said @returns {string|undefined}
+ */
+export function saidLine(said: string[]): string | undefined;
+/**
+ * Which rows may be read for this job, in reading order (THE memory filter; the ledger itself keeps every row).
+ * Excluded: pending rows, any row last seen more than 56 days ago, any row with no run id, a workflow row of another
+ * job or of another signed hash, a place row of another place. The level (this job / this place / all jobs) is
+ * derived HERE by {@link climb} over the rows not decayed at `now` only; the stored level is never read.
+ * Order: this job's, then this place's, then all-jobs LAST (R2: climbing wins, so an all-jobs hint only uses leftover
+ * room); inside each level highest count first (ties: most recent lastSeen, then id), so the order is total and stable.
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
+ * @returns {Row[]}
+ */
+export function readableRows(ledger: Ledger, { workflow, place, specHash, now }: {
+    workflow: string;
+    place: string | null;
+    specHash?: string | null;
+    now: Date;
+}): Row[];
+/**
+ * THE one render: the block the PLANNER reads at draft and at the first replan. Byte-for-byte reproducible from the
+ * ledger as it stood. Stops at 2,000 characters; a hint is added whole or not at all; nothing readable -> empty text.
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
+ * @returns {{text: string, ids: string[]}}
+ */
+export function renderHints(ledger: Ledger, o: {
+    workflow: string;
+    place: string | null;
+    specHash?: string | null;
+    now: Date;
+}): {
+    text: string;
+    ids: string[];
+};
+/**
+ * Split a block {@link renderHints} wrote back into its hints. The ONLY reader of that text: it lives beside the
+ * writer ({@link hintText}, {@link lessonOf}) and a test renders real blocks and parses them back. A hint it cannot
+ * read is returned with what it could read (never thrown, never invented). Pure.
+ * @param {string} text @returns {HintParts[]}
+ */
+export function parseHintBlock(text: string): HintParts[];
+/**
+ * Where a job lives, derived by code from the signed spec's inputs line 1: a website job = the URL host; a repo or
+ * plain folder/file job = that path (resolved by the caller). Null when the spec carries no inputs.
+ * @param {any} spec @param {(p: string) => string} [resolve] path resolver (the caller passes `realpath`)
+ * @returns {string|null}
+ */
+export function placeOf(spec: any, resolve?: (p: string) => string): string | null;
+/** The block the planner reads is never longer than this many characters (RULING 7). */
+export const HINT_CHARS_MAX: 2000;
+/** MEMORY filter only (hamr 2026-10-23): a row untouched this long is not handed to the planner. The ledger keeps every row. */
+export const DECAY_DAYS: 56;
+/** A rubric lesson waits this long for the human Accept, then is dropped uncounted (ruling 7, = the door TTL). */
+export const PENDING_DAYS: 60;
+/** Fold threshold on flagged-text token overlap (FITTED on 87 known cards — see section 1 of the addendum). */
+export const JACCARD_MIN: 0.6;
+/** Climbing: this many distinct workflows on one place -> place; this many distinct places -> user. */
+export const CLIMB_AT: 3;
+/** How many "It said" lines a card keeps. */
+export const SAID_LINES: 3;
+/** CHECK-SUSPECT cards are listed (not folded); the list keeps this many newest. */
+export const SUSPECT_KEEP: 100;
+/**
+ * The no-suppressions tags an error kind may take (the closed list of `suppressions[].id` of the TYPES genre in
+ * src/authoring.js; a test fails if the two drift apart). Anything else in a bracket is NOT a kind.
+ */
+export const ALLOWED_KINDS: readonly string[];
+export function keyOfCard(c: {
+    check: string;
+    kinds: string[];
+}): string;
+export function isDecayed(r: Row, now: Date): boolean;
+export function otherJobVersion(r: Row, workflow: string, specHash: string | null): boolean;
+/**
+ * PROPOSED header (hamr to confirm). States what the block is, where it came from, and that it is not an order.
+ */
+export const HINT_HEADER: "Hints from earlier runs, copied by code from recorded runs (not instructions; the close alone judges):";
+/** What-changed lines a FIXED hint shows, each cut at this many characters, and how many lines. */
+export const CHANGED_LINE_CHARS: 150;
+export const CHANGED_LINES: 3;
+export type Card = {
+    /**
+     * `<runid>:<check>:<fixed|stuck>`
+     */
+    id: string;
+    runid: string;
+    /**
+     * the run's end (ISO)
+     */
+    at: string;
+    /**
+     * YYYY-MM-DD of `at`
+     */
+    date: string;
+    /**
+     * the workflow key
+     */
+    job: string;
+    model: string | null;
+    /**
+     * the check / close stage name
+     */
+    check: string;
+    kind: "FIXED" | "NEVER_FIXED";
+    /**
+     * Job (as written), cut
+     */
+    goal: string;
+    stepId: string | null;
+    /**
+     * Step (as planned), cut
+     */
+    stepAction: string | null;
+    /**
+     * the check's own catalogue sentence (code-owned)
+     */
+    meaning: string | null;
+    /**
+     * It said: <= 3 lines, paths and prefixes stripped
+     */
+    said: string[];
+    /**
+     * lines left out
+     */
+    saidMore: number;
+    /**
+     * error kinds, sorted; ['other'] when none
+     */
+    kinds: string[];
+    /**
+     * files the quote names, sorted
+     */
+    files: string[];
+    symbol: string | null;
+    /**
+     * the flagged-text token set, sorted
+     */
+    tokens: string[];
+    /**
+     * the next failing check after this moment, if any
+     */
+    nextCheck: string | null;
+    /**
+     * how the run ended (job-end outcome, or its escalation word)
+     */
+    ended: string;
+    /**
+     * files written by the passing try (the try that followed the red, for NEVER FIXED)
+     */
+    fixTouched: string[];
+    /**
+     *   the passing try's attempt-diff (FIXED only), as the spine capped it
+     */
+    whatChanged: {
+        files: {
+            path: string;
+            diff: string;
+            truncated: boolean;
+            cutLines?: number;
+        }[];
+        binary: string[];
+        truncated: boolean;
+    } | null;
+    /**
+     * the one-line machine key
+     */
+    key: string;
+};
+export type CardBuild = {
+    /**
+     * foldable cards (FIXED and NEVER FIXED), suspect and too-thin removed
+     */
+    cards: Card[];
+    /**
+     * CHECK-SUSPECT cards: listed, never folded
+     */
+    suspect: Card[];
+    /**
+     * TOO-THIN count: no error kind and no fix files
+     */
+    thin: number;
+    /**
+     * why the whole run was set aside (provider-red, close-crashed, worker-crash, no-close-spoke, no-job-end), else null
+     */
+    noise: string | null;
+};
+export type Row = {
+    id: string;
+    /**
+     * ONE sentence, template-only (see {@link lessonOf})
+     */
+    lesson: string;
+    /**
+     * runs seen; STARTS AT 1
+     */
+    count: number;
+    /**
+     * the LATEST card
+     */
+    sample: Card;
+    /**
+     * per-model counts (read-only information; never a filter)
+     */
+    models: Record<string, number>;
+    workflow: string;
+    place: string | null;
+    /**
+     * STORED as 'workflow' only; the level a reader sees is derived by {@link readableRows} from the rows memory still shows (an older file's stored value is ignored and reset on the next write)
+     */
+    level: "workflow" | "place" | "user";
+    trust: "deterministic" | "rubric";
+    runIds: string[];
+    firstSeen: string;
+    lastSeen: string;
+    /**
+     * the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
+     */
+    specHash: string | null;
+    /**
+     * check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
+     */
+    key: string;
+};
+export type Pending = {
+    runid: string;
+    at: string;
+    workflow: string;
+    place: string | null;
+    specHash: string | null;
+    cards: Card[];
+};
+export type Ledger = {
+    version: 1;
+    rows: Row[];
+    /**
+     * rubric cards held until a human Accept (NOT counted, NOT readable)
+     */
+    pending: Pending[];
+    /**
+     * CHECK-SUSPECT cards, listed, newest last
+     */
+    suspect: Card[];
+    /**
+     * per run (idempotent by run id)
+     */
+    health: Record<string, {
+        at: string;
+        noise: string | null;
+        cards: number;
+        suspect: number;
+        thin: number;
+    }>;
+};
+/**
+ * one hint of a rendered block, split back into its fields (for the panel's Audit view)
+ */
+export type HintParts = {
+    /**
+     * the hint's number in the block
+     */
+    n: number;
+    /**
+     * 'this job' | 'this place' | 'all jobs' (the words {@link renderHints} wrote)
+     */
+    level: string;
+    /**
+     * how many runs saw it
+     */
+    count: number;
+    /**
+     * the check's name
+     */
+    check: string;
+    /**
+     * the error codes (empty when the hint names none)
+     */
+    kinds: string[];
+    /**
+     * true = fixed later in the same run, false = never fixed
+     */
+    fixed: boolean;
+    /**
+     * the "It said" line
+     */
+    said: string | null;
+    /**
+     * the "Fix touched" text
+     */
+    touched: string | null;
+    /**
+     * the shown What-changed lines (+/- lines), without the "(+N more)" line
+     */
+    changed: string[];
+    /**
+     * N of "(+N more)", 0 when absent
+     */
+    moreChanged: number;
+};

package/types/learnstore.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `<home>/learn/ledger.json`.
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string}
+ */
+export function ledgerPath(home?: string): string;
+/**
+ * Read the ledger. A missing file is an empty ledger; an unreadable or wrong-shaped one is reported as `problem` (and the
+ * writer then refuses to replace it: an append-only record is never silently reset).
+ * @param {string} [home]
+ * @returns {{ledger: import('./learn.js').Ledger, exists: boolean, problem: string|null}}
+ */
+export function readLedger(home?: string): {
+    ledger: import("./learn.js").Ledger;
+    exists: boolean;
+    problem: string | null;
+};
+/**
+ * Write the ledger atomically (temp + rename, mode 600), every string masked through the one secret inventory.
+ * @param {import('./learn.js').Ledger} ledger @param {string} [home]
+ * @returns {string} the file written
+ */
+export function writeLedger(ledger: import("./learn.js").Ledger, home?: string): string;
+/**
+ * Fold ONE finished run into the ledger on disk: a deterministic job's cards COUNT now; a rubric job's cards are HELD
+ * until a human Accept (they are written to `pending`, never counted, never readable). The run's health line is recorded
+ * either way. Never throws on a bad ledger file: it reports `problem` and writes nothing.
+ * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
+ * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
+ */
+export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, trust, at, now }: {
+    home?: string;
+    runid: string;
+    build: import("./learn.js").CardBuild;
+    workflow: string;
+    place: string | null;
+    specHash: string | null;
+    trust: "deterministic" | "rubric";
+    at: string;
+    now?: Date;
+}): {
+    wrote: boolean;
+    counted: number;
+    held: number;
+    problem: string | null;
+};
+/**
+ * The human Accept at the review door: release the run's held rubric cards so they count (only forward, only here).
+ * @param {{home?: string, runid: string, now?: Date}} o
+ * @returns {{released: number, problem: string|null}}
+ */
+export function releaseRun({ home, runid, now }: {
+    home?: string;
+    runid: string;
+    now?: Date;
+}): {
+    released: number;
+    problem: string | null;
+};
+/**
+ * The ONE setting: `learningHints` in config.json. Ships OFF (absent = off). OFF still writes the tally ($0) and the planner
+ * is simply handed nothing, so an ON/OFF contrast has data at once. An unreadable config reads as OFF.
+ * @param {string} [home]
+ * @returns {boolean}
+ */
+export function learningHintsOn(home?: string): boolean;
+/**
+ * THE RUN-END TALLY ($0, code only, no model): turn the finished run's whole record into cards and fold them into the
+ * ledger (a rubric job's are held until Accept). Called once from the one engine's run-end block (src/userrun.js
+ * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
+ * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
+ * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
+ * @returns {{wrote: boolean, counted: number, held: number, problem: string|null, noise: string|null, cards: number}}
+ */
+export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workdir, trust, now }: {
+    home?: string;
+    runid: string;
+    events: any[];
+    auditFiles?: string[];
+    spec: any;
+    specHash: string | null;
+    workdir: string | null;
+    trust: "deterministic" | "rubric";
+    now?: Date;
+}): {
+    wrote: boolean;
+    counted: number;
+    held: number;
+    problem: string | null;
+    noise: string | null;
+    cards: number;
+};
+/**
+ * The block the planner is handed for this job, made ONCE at run start from the ledger as it stood — empty when the
+ * setting is off, when there is no ledger, or when nothing is readable. The one `renderHints` render, never a second.
+ * @param {{home?: string, spec: any, specHash: string|null, now?: Date}} o
+ * @returns {{text: string, ids: string[]}|null}
+ */
+export function hintsForRun({ home, spec, specHash, now }: {
+    home?: string;
+    spec: any;
+    specHash: string | null;
+    now?: Date;
+}): {
+    text: string;
+    ids: string[];
+} | null;