@celestea/runtime 2.7.1

package/dist/ledger-query.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Aggregate views over the append-only usage ledger (iteration E §3.2.4, W785 P1).
+ *
+ * Two readers, both pure functions of the records a [UsageLedgerFile] hands over,
+ * so a restart, a hot swap or a second process cannot change the answer:
+ *
+ *   - [queryLedger]      — `GET /api/usage/ledger`: the step rows of the ledger,
+ *                          filtered (`session`/`since`/`until`) and folded into
+ *                          one row per `session` | `turn` | `model` | `day`;
+ *   - [ledgerCostBlock]  — `/api/status.cost`: one session's running total, its
+ *                          newest `turn_total` row and how many attempts bought it.
+ *
+ * `turn_total` rows are DELIBERATELY excluded from every sum: they are the
+ * reconciliation convenience of §3.2.1 (they restate the steps of their turn), so
+ * counting them would book every token twice. Details stay the only truth.
+ *
+ * `cost` is `null` — never `0` — when no contributing row carried a cost, and
+ * `unpriced_records`/`unpriced_models` name the models the price table could not
+ * cover (§3.2.2 rule 3: an unknown price is UNKNOWN, not free).
+ */
+import { type Usage } from "@celestea/core";
+import { type LedgerCost } from "./pricing.js";
+import { type LedgerTotals, type UsageLedgerRecord } from "./ledger.js";
+/** The dimension one aggregate row is folded by (§3.2.4). */
+export type LedgerGroupBy = "session" | "turn" | "model" | "day";
+/** What `GET /api/usage/ledger` accepts. `since`/`until` are SECONDS, like `ts`. */
+export interface LedgerQuery {
+    session?: string;
+    since?: number;
+    until?: number;
+    group_by?: LedgerGroupBy;
+}
+/** One aggregate row: the same accumulation rule for every dimension. */
+export interface LedgerQueryRow {
+    key: string;
+    tokens: Usage;
+    /** null = no contributing row was priced (never 0, §3.2.2). */
+    cost: LedgerCost | null;
+    records: number;
+    /** Rows that carried usage the table could not price. */
+    unpriced_records: number;
+}
+/** The `GET /api/usage/ledger` body (P1 ①). */
+export interface LedgerQueryResult {
+    ok: true;
+    currency: string;
+    group_by: LedgerGroupBy;
+    rows: LedgerQueryRow[];
+    totals: LedgerTotals;
+    unpriced_models: string[];
+    price_version: string | null;
+}
+/** The `/api/status.cost` block (P1 ②) — the engine's own estimate, per session. */
+export interface LedgerCostBlock {
+    /** Sum of the session's step-row costs; null = nothing priced yet (not 0). */
+    session_total: number | null;
+    /** Cost of the session's NEWEST `turn_total` row; null = none/unpriced. */
+    turn_total: number | null;
+    /**
+     * How many ATTEMPTS bought it — the COUNT of this session's step rows, the
+     * same口径 as `turn_total.attempts` in the ledger (E §3.4 D6: three attempts
+     * read as 3, never as 1+2+3 = 6). One row is one attempt by construction.
+     */
+    attempts: number;
+    currency: string;
+    /** `unpriced` = at least one row was unpriced or unbilled (cost incomplete). */
+    priced_by: "table" | "unpriced";
+    unpriced_models: string[];
+    records: number;
+    cost_complete: boolean;
+}
+/** The default dimension when the query omits `group_by` (§3.2.4). */
+export declare const DEFAULT_LEDGER_GROUP_BY: LedgerGroupBy;
+/** Every dimension the endpoint accepts, in contract order. */
+export declare const LEDGER_GROUP_BY_VALUES: readonly LedgerGroupBy[];
+/** Label of a row whose model the provider never reported (§3.2.1). */
+export declare const UNKNOWN_MODEL_LABEL = "(unknown model)";
+/**
+ * The aggregate view: filter, fold by dimension, and total.
+ *
+ * `totals` reuses [aggregateUsage] over the ALREADY filtered rows (the P0
+ * aggregate, unchanged: it owns the currency/price-version/unpriced rules), and the
+ * result echoes its `currency`/`price_version`/`unpriced_models` so a client never
+ * has to recompute them from the rows.
+ */
+export declare function queryLedger(records: readonly UsageLedgerRecord[], q: LedgerQuery): LedgerQueryResult;
+/**
+ * `/api/status.cost` for ONE session (P1 ②): what this session has spent so far,
+ * what its newest turn cost, and how many attempts that took.
+ */
+export declare function ledgerCostBlock(records: readonly UsageLedgerRecord[], session: string): LedgerCostBlock;

package/dist/ledger-query.js

@@ -0,0 +1,153 @@
+/**
+ * Aggregate views over the append-only usage ledger (iteration E §3.2.4, W785 P1).
+ *
+ * Two readers, both pure functions of the records a [UsageLedgerFile] hands over,
+ * so a restart, a hot swap or a second process cannot change the answer:
+ *
+ *   - [queryLedger]      — `GET /api/usage/ledger`: the step rows of the ledger,
+ *                          filtered (`session`/`since`/`until`) and folded into
+ *                          one row per `session` | `turn` | `model` | `day`;
+ *   - [ledgerCostBlock]  — `/api/status.cost`: one session's running total, its
+ *                          newest `turn_total` row and how many attempts bought it.
+ *
+ * `turn_total` rows are DELIBERATELY excluded from every sum: they are the
+ * reconciliation convenience of §3.2.1 (they restate the steps of their turn), so
+ * counting them would book every token twice. Details stay the only truth.
+ *
+ * `cost` is `null` — never `0` — when no contributing row carried a cost, and
+ * `unpriced_records`/`unpriced_models` name the models the price table could not
+ * cover (§3.2.2 rule 3: an unknown price is UNKNOWN, not free).
+ */
+import { usageAdd, zeroUsage } from "@celestea/core";
+import { costAdd } from "./pricing.js";
+import { aggregateUsage, } from "./ledger.js";
+/** The default dimension when the query omits `group_by` (§3.2.4). */
+export const DEFAULT_LEDGER_GROUP_BY = "session";
+/** Every dimension the endpoint accepts, in contract order. */
+export const LEDGER_GROUP_BY_VALUES = ["session", "turn", "model", "day"];
+/** Label of a row whose model the provider never reported (§3.2.1). */
+export const UNKNOWN_MODEL_LABEL = "(unknown model)";
+/** The step rows a query counts, in file order (see the module header). */
+function queryRows(records, q) {
+    const out = [];
+    for (const record of records) {
+        if (record.kind === "turn_total")
+            continue;
+        if (!inRange(record, q))
+            continue;
+        out.push(record);
+    }
+    return out;
+}
+/** `session` exact match plus the INCLUSIVE `since`/`until` window (§3.2.4). */
+function inRange(record, q) {
+    if (q.session !== undefined && record.session !== q.session)
+        return false;
+    if (q.since !== undefined && record.ts < q.since)
+        return false;
+    if (q.until !== undefined && record.ts > q.until)
+        return false;
+    return true;
+}
+/** The key one step row folds into for the requested dimension. */
+function groupKeyOf(record, by) {
+    if (by === "model")
+        return record.model ?? UNKNOWN_MODEL_LABEL;
+    if (by === "turn")
+        return `${record.session}|${record.turn_id ?? "-"}`;
+    if (by === "day")
+        return new Date(record.ts * 1000).toISOString().slice(0, 10);
+    return record.session;
+}
+/** Tokens, cost and the unpriced count all follow the SAME per-row rule. */
+function accumulate(acc, record) {
+    acc.records += 1;
+    if (record.usage !== null) {
+        acc.tokens = usageAdd(acc.tokens, record.usage);
+        if (record.priced_by === "unpriced")
+            acc.unpriced += 1;
+    }
+    if (record.cost !== null)
+        acc.cost = acc.cost === null ? record.cost : costAdd(acc.cost, record.cost);
+}
+/** Stable, locale-independent key order (`<`/`>` on code units, ascending). */
+function compareKeys(a, b) {
+    if (a.key === b.key)
+        return 0;
+    return a.key < b.key ? -1 : 1;
+}
+/** Fold the selected step rows into the aggregate rows of one dimension. */
+function foldRows(selected, by) {
+    const groups = new Map();
+    for (const record of selected) {
+        const key = groupKeyOf(record, by);
+        const acc = groups.get(key) ?? { tokens: zeroUsage(), cost: null, records: 0, unpriced: 0 };
+        accumulate(acc, record);
+        groups.set(key, acc);
+    }
+    const rows = [];
+    for (const [key, acc] of groups) {
+        rows.push({ key, tokens: acc.tokens, cost: acc.cost, records: acc.records, unpriced_records: acc.unpriced });
+    }
+    return rows.sort(compareKeys);
+}
+/**
+ * The aggregate view: filter, fold by dimension, and total.
+ *
+ * `totals` reuses [aggregateUsage] over the ALREADY filtered rows (the P0
+ * aggregate, unchanged: it owns the currency/price-version/unpriced rules), and the
+ * result echoes its `currency`/`price_version`/`unpriced_models` so a client never
+ * has to recompute them from the rows.
+ */
+export function queryLedger(records, q) {
+    const by = q.group_by ?? DEFAULT_LEDGER_GROUP_BY;
+    const selected = queryRows(records, q);
+    const totals = aggregateUsage(selected);
+    return {
+        ok: true,
+        currency: totals.currency,
+        group_by: by,
+        rows: foldRows(selected, by),
+        totals,
+        unpriced_models: totals.unpriced_models,
+        price_version: totals.price_version,
+    };
+}
+/** The newest `turn_total` row of one session (file order = write order). */
+function lastTurnTotal(records, session) {
+    for (let i = records.length - 1; i >= 0; i--) {
+        const record = records[i];
+        if (record !== undefined && record.kind === "turn_total" && record.session === session)
+            return record;
+    }
+    return null;
+}
+/** The step rows of ONE session (the `turn_total` rows never contribute). */
+function sessionSteps(records, session) {
+    const out = [];
+    for (const record of records) {
+        if (record.kind !== "turn_total" && record.session === session)
+            out.push(record);
+    }
+    return out;
+}
+/**
+ * `/api/status.cost` for ONE session (P1 ②): what this session has spent so far,
+ * what its newest turn cost, and how many attempts that took.
+ */
+export function ledgerCostBlock(records, session) {
+    const steps = sessionSteps(records, session);
+    const totals = aggregateUsage(steps);
+    const last = lastTurnTotal(records, session);
+    const attempts = steps.length;
+    return {
+        session_total: totals.cost === null ? null : totals.cost.total,
+        turn_total: last === null || last.cost === null ? null : last.cost.total,
+        attempts,
+        currency: totals.currency,
+        priced_by: totals.cost_complete ? "table" : "unpriced",
+        unpriced_models: totals.unpriced_models,
+        records: steps.length,
+        cost_complete: totals.cost_complete,
+    };
+}

package/dist/ledger.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Cost & usage ledger (iteration E §3 P0, W728) — append-only, step granularity.
+ *
+ * One JSON line per model step in `<data dir>/usage-ledger.jsonl`, plus one
+ * `turn_total` line per turn for reconciliation. The file is the durable,
+ * never-rewritten record of what was spent: the in-memory usage tracker is
+ * reset by every generation rebuild (§3.1 G3-1), the ledger is not.
+ *
+ * Discipline (all mechanical, see the §3.4 assertions):
+ *   - append-only: a line is written once and never edited (no rewrite, no
+ *     compaction). Rotation (§3.3 P1 ④, W785) rolls the WHOLE file to
+ *     `<path>.1` once it passes [USAGE_LEDGER_MAX_BYTES]: the current file is
+ *     still only ever appended to, and `read()` reads the current file only
+ *     (the CUMULATIVE views call `readAll()`, which prefixes the rolled `.1`);
+ *   - one `writeSync` on an `O_APPEND` fd per record, mode 0600, so concurrent
+ *     writers cannot interleave a line;
+ *   - idempotent: the key is `(session, turn_id, step, attempt)`; a key already
+ *     booked by THIS writer is skipped, never rewritten. The key set is
+ *     per-process ON PURPOSE: seeding it from the file would silently drop
+ *     legitimate out-of-turn rows, whose turn_id is null and whose step index
+ *     restarts at 1 after a restart (cross-process dedupe is still open work;
+ *     rotation does not change it, §3.3);
+ *   - no prompt/message text and no credential can reach a line: a record is
+ *     built from counters, names and prices only (§3.5 R3-4);
+ *   - observation only: a write failure is reported on stderr and swallowed —
+ *     bookkeeping must never change request behaviour (§3.5 R3-3).
+ *
+ * WHERE a step is observed: `packages/llm`'s `LlmError.httpStatus/retryable`
+ * (W723) is only visible at the `Llm` seam, and so are the step boundaries — a
+ * stream that tears AFTER a usage frame is ONE error row, not an ok row plus an
+ * error row (§3.2.3). [createLedgerLlm] therefore drives `beginStep` → one
+ * `record` per usage frame → `close` at the stream's terminal event, while the
+ * turn boundaries come from the runtime's [TurnLedgerHooks]. [UsageLedger]
+ * still implements the runtime's structural `UsageAccounting` seam, and its
+ * `latest`/`total` views are derived from the FILE, so they survive a restart.
+ */
+import { type SessionEvent, type SessionLog, type TurnOutcome, type Usage } from "@celestea/core";
+import { type LedgerCost, type PriceSnapshot, type PricingTable } from "./pricing.js";
+import type { UsageAccounting } from "./usage.js";
+/** `<data dir>/usage-ledger.jsonl` (§3.2.1). */
+export declare const USAGE_LEDGER_FILE = "usage-ledger.jsonl";
+/** `CELESTEA_USAGE_LEDGER=off` disables the ledger entirely (§3.5 R3-3). */
+export declare const ENV_USAGE_LEDGER = "CELESTEA_USAGE_LEDGER";
+/** Path override (`CELESTEA_USAGE_LEDGER_FILE`). */
+export declare const ENV_USAGE_LEDGER_FILE = "CELESTEA_USAGE_LEDGER_FILE";
+/** Record version, written as `v` on every line. */
+export declare const LEDGER_VERSION = 1;
+/**
+ * Rotation threshold (§3.3 P1 ④): before a write, a ledger file at or above this
+ * size is rolled to `<path>.1` (replacing the previous `.1`) and the next write
+ * recreates the current file. 16 MiB is the audit-trail discipline borrowed from
+ * `grants-audit.jsonl`, never a durability boundary: the rolled file keeps every
+ * row it had.
+ */
+export declare const USAGE_LEDGER_MAX_BYTES: number;
+/**
+ * Bound of the in-process idempotency-key set (P2-5, W836): a long-lived engine
+ * books one key per model step, so the set is trimmed once it exceeds this many
+ * entries (oldest first). Per-turn keys are evicted wholesale when their turn
+ * ends ([UsageLedgerFile.evictTurn]); this cap is only the backstop for keys
+ * whose turn never closed (torn process, out-of-turn row).
+ */
+export declare const USAGE_LEDGER_MAX_KEYS = 100000;
+export type LedgerStepKind = "ok" | "error";
+export type PricedBy = "table" | "record" | "unpriced";
+/** The model half of a record (§3.2.1). */
+export interface LedgerModelInfo {
+    provider: string | null;
+    model: string | null;
+    base_url_host: string | null;
+}
+/** One step row: `kind: "ok"` (a response arrived) or `"error"` (§3.2.3). */
+export interface UsageStepRecord extends LedgerModelInfo {
+    v: number;
+    ts: number;
+    kind: LedgerStepKind;
+    session: string;
+    turn: number | null;
+    turn_id: string | null;
+    step: number;
+    attempt: number;
+    usage: Usage | null;
+    /** true = the provider reported no usage: the cost is UNKNOWN, not 0. */
+    billed_unknown: boolean;
+    error_kind: string | null;
+    http_status: number | null;
+    retryable: boolean | null;
+    price: PriceSnapshot | null;
+    cost: LedgerCost | null;
+    priced_by: PricedBy;
+    fallback_from: string | null;
+}
+/** The per-turn summary row (a reconciliation convenience; details stay). */
+export interface UsageTurnTotalRecord {
+    v: number;
+    ts: number;
+    kind: "turn_total";
+    session: string;
+    turn: number | null;
+    turn_id: string | null;
+    steps: number;
+    attempts: number;
+    usage: Usage;
+    cost: LedgerCost | null;
+    /** false = at least one contributing row was unpriced or unbilled. */
+    cost_complete: boolean;
+    priced_by: PricedBy;
+    unpriced_models: string[];
+    billed_unknown_steps: number;
+    outcome: TurnOutcome;
+}
+export type UsageLedgerRecord = UsageStepRecord | UsageTurnTotalRecord;
+/** What the ledger is told when a model step opens. */
+export interface LedgerStepInfo extends LedgerModelInfo {
+    /** 0 = first attempt; retries/fallbacks increment (§5.2). P0 writes 0. */
+    attempt: number;
+    fallback_from: string | null;
+}
+/** The terminal verdict of one step (the only place a failure is announced). */
+export interface LedgerStepOutcome {
+    kind: LedgerStepKind;
+    error_kind?: string | null;
+    http_status?: number | null;
+    retryable?: boolean | null;
+}
+/** The handle [UsageLedger.beginStep] hands back: one buffer per model step. */
+export interface LedgerStepHandle {
+    record(usage: Usage): void;
+    close(outcome: LedgerStepOutcome): void;
+}
+/** Write side of the ledger, as consumed by the `Llm` step observer. */
+export interface LedgerStepSink {
+    beginStep(info: LedgerStepInfo): LedgerStepHandle;
+}
+/** Turn lifecycle hooks the runtime calls (observation only, never throws). */
+export interface TurnLedgerHooks {
+    beginTurn(log: SessionLog): void;
+    endTurn(outcome: TurnOutcome): void;
+}
+/** The open turn of a session log: the newest `turn_start` with no `turn_end`. */
+export declare function openTurnOf(events: readonly SessionEvent[]): {
+    id: string;
+    turn: number | null;
+} | null;
+/** `turn-7` -> 7 (the ledger only needs the display number of the log's id). */
+export declare function turnNumberOf(id: string): number | null;
+/** The idempotency key of a step row (§3.2.3). */
+export declare function ledgerKey(record: Pick<UsageStepRecord, "session" | "turn_id" | "step" | "attempt">): string;
+/** Append-only writer of one ledger file, shared by every session (§3.6). */
+export declare class UsageLedgerFile {
+    private fd;
+    private readonly keys;
+    private readonly target;
+    private readonly clock;
+    private readonly maxBytes;
+    readonly pricing: PricingTable;
+    constructor(opts: {
+        path: string;
+        pricing?: PricingTable;
+        now?: () => number;
+        maxBytes?: number;
+    });
+    /** Absolute path of the append-only ledger. */
+    get path(): string;
+    /** Second-resolution timestamp of a row (the ledger's own injectable clock). */
+    stamp(): number;
+    /**
+     * Append one record. False = the key was already booked, or the write failed
+     * (reported on stderr, never thrown: bookkeeping cannot break a turn).
+     */
+    append(record: UsageLedgerRecord, key?: string | null): boolean;
+    /** The CURRENT file records only, in file order (audit detail, P2-2). */
+    read(): UsageLedgerRecord[];
+    /**
+     * The CUMULATIVE records: the rolled `.1` segment first, then the current
+     * file, so a rotation does not hide history from total()/latest() or the host
+     * cost views (P2-2, W836). `read()` stays current-only so an audit detail view
+     * cannot double-count rows that are also reachable under `.1`.
+     */
+    readAll(): UsageLedgerRecord[];
+    /** How many idempotency keys are remembered (bounded-memory diagnostics). */
+    get keyCount(): number;
+    /** Drop the keys of ONE closed turn (see [LedgerKeySet.evictTurn]). */
+    evictTurn(session: string, turnId: string | null): void;
+    /** Close the descriptor (idempotent; the file itself is never truncated). */
+    close(): void;
+    /**
+     * Roll the file to `<path>.1` once it reaches [maxBytes] (§3.3 P1 ④).
+     *
+     * The fd is closed FIRST and the rename replaces any previous `.1`, so the
+     * rolled file is the complete prefix and the next `ensureFd()` starts a fresh
+     * current file. A failure is reported on stderr and swallowed (observation
+     * discipline, §3.5 R3-3): the worst case is a file that keeps growing.
+     */
+    private rotateIfLarge;
+    /** One `O_APPEND` descriptor; one `writeSync` per record keeps lines whole. */
+    private ensureFd;
+}
+/** Per-session ledger: usage frames in, append-only rows out (§3.3 P0 ①–④). */
+export declare class UsageLedger implements UsageAccounting, LedgerStepSink, TurnLedgerHooks {
+    private readonly file;
+    private readonly session;
+    private logRef;
+    private acc;
+    private current;
+    constructor(opts: {
+        session: string;
+        file: UsageLedgerFile;
+    });
+    /** The process-shared file this session books into. */
+    get ledgerFile(): UsageLedgerFile;
+    /** Turn start: bind the session log, drop the previous turn's buffer. */
+    beginTurn(log: SessionLog): void;
+    /** Turn end: flush the summary row (a turn that booked nothing writes none). */
+    endTurn(outcome: TurnOutcome): void;
+    /**
+     * Open one model step. The turn identity is captured HERE (not at close), so
+     * a step that outlives its turn still books against the turn it belongs to.
+     */
+    beginStep(info: LedgerStepInfo): LedgerStepHandle;
+    /** UsageRecorder: one frame for whichever step is open (see [beginStep]). */
+    record(usage: Usage): void;
+    /** Usage of the most recent booked step of this session (file-derived). */
+    latest(): Usage;
+    /** Every token this session ever booked (survives a restart, §3.4 C5). */
+    total(): Usage;
+    /** C3/C5 view: tokens, cost, and the models the table could not price. */
+    totals(): LedgerTotals;
+    /** This session's step rows, newest first (`turn_total` rows excluded). */
+    private rows;
+    /** One handle per step: its own buffer, closed at most once. */
+    private stepHandle;
+    /** Build the row of one closed step and append it (idempotent by key). */
+    private book;
+    /** The accumulator of the step's turn, created on first use. */
+    private accumulator;
+}
+/** Factory form (`createXxx` convention, ARCHITECTURE.md §6.1). */
+export declare function createUsageLedger(opts: {
+    session: string;
+    file: UsageLedgerFile;
+}): UsageLedger;
+/** Aggregate view over step rows (the P0 half of §3.2.4; the endpoint is P1). */
+export interface LedgerTotals {
+    currency: string;
+    price_version: string | null;
+    records: number;
+    tokens: Usage;
+    cost: LedgerCost | null;
+    cost_complete: boolean;
+    /** Rows that carried usage the table could not price (never silently 0). */
+    unpriced_records: number;
+    /** Rows whose provider reported no usage: the cost is UNKNOWN. */
+    billed_unknown_records: number;
+    unpriced_models: string[];
+}
+/** Sum the step rows of one session (or of the whole file when omitted). */
+export declare function aggregateUsage(records: readonly UsageLedgerRecord[], session?: string): LedgerTotals;
+/**
+ * The process-level ledger file (one writer per process, every session books
+ * into it — §3.6). `CELESTEA_USAGE_LEDGER=off|0|false|no` disables it entirely;
+ * the price snapshot is read once here, so a new process picks up a new version
+ * while every already-written row keeps the one it was priced with (C7).
+ */
+export declare function createUsageLedgerFile(opts: {
+    dataDir: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}): UsageLedgerFile | null;
+/** `off` (and the usual falsey spellings) turns the ledger off. */
+export declare function ledgerEnabled(env?: NodeJS.ProcessEnv): boolean;