@celestea/runtime 2.7.1

package/dist/ledger.js

@@ -0,0 +1,444 @@
+/**
+ * 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 { closeSync, openSync, renameSync, statSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { usageAdd, zeroUsage } from "@celestea/core";
+import { costAdd, costOf, emptyPricing, loadPricingFile, priceFor, priceSnapshot, pricingPath, } from "./pricing.js";
+import { LedgerKeySet, readLedgerRecords } from "./ledger-io.js";
+/** `<data dir>/usage-ledger.jsonl` (§3.2.1). */
+export const USAGE_LEDGER_FILE = "usage-ledger.jsonl";
+/** `CELESTEA_USAGE_LEDGER=off` disables the ledger entirely (§3.5 R3-3). */
+export const ENV_USAGE_LEDGER = "CELESTEA_USAGE_LEDGER";
+/** Path override (`CELESTEA_USAGE_LEDGER_FILE`). */
+export const ENV_USAGE_LEDGER_FILE = "CELESTEA_USAGE_LEDGER_FILE";
+/** Record version, written as `v` on every line. */
+export 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 const USAGE_LEDGER_MAX_BYTES = 16 * 1024 * 1024;
+/**
+ * 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 const USAGE_LEDGER_MAX_KEYS = 100_000;
+/** The open turn of a session log: the newest `turn_start` with no `turn_end`. */
+export function openTurnOf(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev === undefined)
+            continue;
+        if (ev.type === "turn_end")
+            return null;
+        if (ev.type === "turn_start")
+            return { id: ev.id, turn: turnNumberOf(ev.id) };
+    }
+    return null;
+}
+/** `turn-7` -> 7 (the ledger only needs the display number of the log's id). */
+export function turnNumberOf(id) {
+    const m = /^turn-(\d+)$/.exec(id);
+    if (m === null || m[1] === undefined)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isSafeInteger(n) ? n : null;
+}
+/** The idempotency key of a step row (§3.2.3). */
+export function ledgerKey(record) {
+    return `${record.session}|${record.turn_id ?? "-"}|${record.step}|${record.attempt}`;
+}
+/** Append-only writer of one ledger file, shared by every session (§3.6). */
+export class UsageLedgerFile {
+    fd = null;
+    keys = new LedgerKeySet(USAGE_LEDGER_MAX_KEYS);
+    target;
+    clock;
+    maxBytes;
+    pricing;
+    constructor(opts) {
+        this.target = opts.path;
+        this.clock = opts.now ?? Date.now;
+        this.maxBytes = opts.maxBytes ?? USAGE_LEDGER_MAX_BYTES;
+        this.pricing = opts.pricing ?? emptyPricing(null);
+    }
+    /** Absolute path of the append-only ledger. */
+    get path() {
+        return this.target;
+    }
+    /** Second-resolution timestamp of a row (the ledger's own injectable clock). */
+    stamp() {
+        return Math.floor(this.clock() / 1000);
+    }
+    /**
+     * 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, key = null) {
+        if (key !== null && this.keys.has(key))
+            return false;
+        try {
+            this.rotateIfLarge();
+            writeSync(this.ensureFd(), `${JSON.stringify(record)}\n`);
+        }
+        catch (e) {
+            // P1-3 (W836): the key is committed ONLY after the row reached the file.
+            // Committing it first poisoned the rest of the turn: the failed step kept
+            // its number, recomputed the same key, and every later step was dropped as
+            // a duplicate. A failed write must leave no trace beyond the warning.
+            warn(`ledger write failed (${errorText(e)})`);
+            return false;
+        }
+        if (key !== null)
+            this.keys.add(key);
+        return true;
+    }
+    /** The CURRENT file records only, in file order (audit detail, P2-2). */
+    read() {
+        return readLedgerRecords(this.target);
+    }
+    /**
+     * 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() {
+        return [...readLedgerRecords(`${this.target}.1`), ...this.read()];
+    }
+    /** How many idempotency keys are remembered (bounded-memory diagnostics). */
+    get keyCount() {
+        return this.keys.size;
+    }
+    /** Drop the keys of ONE closed turn (see [LedgerKeySet.evictTurn]). */
+    evictTurn(session, turnId) {
+        this.keys.evictTurn(session, turnId);
+    }
+    /** Close the descriptor (idempotent; the file itself is never truncated). */
+    close() {
+        if (this.fd === null)
+            return;
+        try {
+            closeSync(this.fd);
+        }
+        catch {
+            // A descriptor we cannot close must not fail a shutdown.
+        }
+        this.fd = null;
+    }
+    /**
+     * 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.
+     */
+    rotateIfLarge() {
+        let size = 0;
+        try {
+            size = statSync(this.target).size;
+        }
+        catch {
+            // No file yet: nothing to roll.
+        }
+        if (size < this.maxBytes)
+            return;
+        try {
+            this.close();
+            renameSync(this.target, `${this.target}.1`);
+        }
+        catch (e) {
+            warn(`ledger rotation failed (${errorText(e)})`);
+        }
+    }
+    /** One `O_APPEND` descriptor; one `writeSync` per record keeps lines whole. */
+    ensureFd() {
+        if (this.fd === null)
+            this.fd = openSync(this.target, "a", 0o600);
+        return this.fd;
+    }
+}
+/** Per-session ledger: usage frames in, append-only rows out (§3.3 P0 ①–④). */
+export class UsageLedger {
+    file;
+    session;
+    logRef = null;
+    acc = null;
+    current = null;
+    constructor(opts) {
+        this.session = opts.session;
+        this.file = opts.file;
+    }
+    /** The process-shared file this session books into. */
+    get ledgerFile() {
+        return this.file;
+    }
+    /** Turn start: bind the session log, drop the previous turn's buffer. */
+    beginTurn(log) {
+        this.logRef = log;
+        this.acc = null;
+    }
+    /** Turn end: flush the summary row (a turn that booked nothing writes none). */
+    endTurn(outcome) {
+        const acc = this.acc;
+        this.acc = null;
+        if (acc !== null)
+            this.file.evictTurn(this.session, acc.turnId);
+        if (acc === null || acc.steps === 0)
+            return;
+        const complete = acc.unpriced.size === 0 && acc.billedUnknown === 0;
+        this.file.append({
+            v: LEDGER_VERSION,
+            ts: this.file.stamp(),
+            kind: "turn_total",
+            session: this.session,
+            turn: acc.turn,
+            turn_id: acc.turnId,
+            steps: acc.steps,
+            attempts: acc.attempts,
+            usage: { ...acc.usage },
+            cost: acc.cost === null ? null : { ...acc.cost },
+            cost_complete: complete,
+            priced_by: complete ? "table" : "unpriced",
+            unpriced_models: [...acc.unpriced].sort(),
+            billed_unknown_steps: acc.billedUnknown,
+            outcome,
+        });
+    }
+    /**
+     * 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) {
+        const open = this.logRef === null ? null : openTurnOf(this.logRef.events());
+        const ref = { info, turnId: open?.id ?? null, turn: open?.turn ?? null };
+        const handle = this.stepHandle(ref);
+        this.current = handle;
+        return handle;
+    }
+    /** UsageRecorder: one frame for whichever step is open (see [beginStep]). */
+    record(usage) {
+        this.current?.record(usage);
+    }
+    /** Usage of the most recent booked step of this session (file-derived). */
+    latest() {
+        for (const record of this.rows()) {
+            if (record.usage !== null)
+                return { ...record.usage };
+        }
+        return zeroUsage();
+    }
+    /** Every token this session ever booked (survives a restart, §3.4 C5). */
+    total() {
+        return aggregateUsage(this.rows()).tokens;
+    }
+    /** C3/C5 view: tokens, cost, and the models the table could not price. */
+    totals() {
+        return aggregateUsage(this.rows());
+    }
+    /** This session's step rows, newest first (`turn_total` rows excluded). */
+    rows() {
+        return this.file
+            .readAll()
+            .filter((r) => r.kind !== "turn_total" && r.session === this.session)
+            .reverse();
+    }
+    /** One handle per step: its own buffer, closed at most once. */
+    stepHandle(ref) {
+        let buffered = null;
+        let closed = false;
+        return {
+            record: (usage) => {
+                if (!closed)
+                    buffered = usage;
+            },
+            close: (outcome) => {
+                if (closed)
+                    return;
+                closed = true;
+                if (outcome.kind === "ok" && buffered === null)
+                    return;
+                this.book(ref, outcome, buffered);
+            },
+        };
+    }
+    /** Build the row of one closed step and append it (idempotent by key). */
+    book(ref, outcome, usage) {
+        const acc = this.accumulator(ref.turnId, ref.turn);
+        // P1-3 (W836): an INDEPENDENT step number, consumed even when the write
+        // fails. Reusing `acc.steps` (which only counts rows that reached the file)
+        // would hand the same number to the next step, so a later successful row
+        // could collide with a key the failed write had left behind.
+        const step = acc.nextStep + 1;
+        acc.nextStep = step;
+        const price = usage === null ? null : priceFor(this.file.pricing, ref.info.model);
+        const cost = usage !== null && price !== null ? costOf(usage, price) : null;
+        const record = {
+            v: LEDGER_VERSION,
+            ts: this.file.stamp(),
+            kind: outcome.kind,
+            session: this.session,
+            turn: ref.turn,
+            turn_id: ref.turnId,
+            step,
+            attempt: ref.info.attempt,
+            provider: ref.info.provider,
+            model: ref.info.model,
+            base_url_host: ref.info.base_url_host,
+            usage: usage === null ? null : { ...usage },
+            billed_unknown: usage === null,
+            error_kind: outcome.error_kind ?? null,
+            http_status: outcome.http_status ?? null,
+            retryable: outcome.retryable ?? null,
+            price: price === null ? null : priceSnapshot(this.file.pricing, price),
+            cost,
+            priced_by: cost === null ? "unpriced" : "table",
+            fallback_from: ref.info.fallback_from,
+        };
+        if (!this.file.append(record, ledgerKey(record)))
+            return;
+        acc.steps += 1;
+        // E §4/§3 P1 (W785): `attempts` counts ATTEMPTS, not `attempt+1` sums. The
+        // P0 form was equivalent while every row was attempt 0; with a real attempt
+        // dimension (fallback chain) summing the indices would report 1+2+3 = 6 for
+        // three attempts (§3.4 D6). Row counts are unchanged for a P0-shaped turn.
+        acc.attempts += 1;
+        if (usage !== null)
+            acc.usage = usageAdd(acc.usage, usage);
+        if (cost !== null)
+            acc.cost = acc.cost === null ? cost : costAdd(acc.cost, cost);
+        if (usage !== null && cost === null)
+            acc.unpriced.add(ref.info.model ?? "(unknown model)");
+        if (usage === null)
+            acc.billedUnknown += 1;
+    }
+    /** The accumulator of the step's turn, created on first use. */
+    accumulator(turnId, turn) {
+        if (this.acc !== null && this.acc.turnId === turnId)
+            return this.acc;
+        this.acc = {
+            turnId,
+            turn,
+            nextStep: 0,
+            steps: 0,
+            attempts: 0,
+            usage: zeroUsage(),
+            cost: null,
+            unpriced: new Set(),
+            billedUnknown: 0,
+        };
+        return this.acc;
+    }
+}
+/** Factory form (`createXxx` convention, ARCHITECTURE.md §6.1). */
+export function createUsageLedger(opts) {
+    return new UsageLedger(opts);
+}
+/** Sum the step rows of one session (or of the whole file when omitted). */
+export function aggregateUsage(records, session) {
+    const totals = {
+        currency: "CNY",
+        price_version: null,
+        records: 0,
+        tokens: zeroUsage(),
+        cost: null,
+        cost_complete: true,
+        unpriced_records: 0,
+        billed_unknown_records: 0,
+        unpriced_models: [],
+    };
+    const unpriced = new Set();
+    for (const record of records) {
+        if (record.kind === "turn_total")
+            continue;
+        if (session !== undefined && record.session !== session)
+            continue;
+        totals.records += 1;
+        if (record.price !== null) {
+            totals.currency = record.price.currency;
+            totals.price_version = record.price.version;
+        }
+        if (record.usage === null) {
+            totals.billed_unknown_records += 1;
+        }
+        else {
+            totals.tokens = usageAdd(totals.tokens, record.usage);
+            if (record.priced_by === "unpriced") {
+                totals.unpriced_records += 1;
+                unpriced.add(record.model ?? "(unknown model)");
+            }
+        }
+        if (record.cost !== null)
+            totals.cost = totals.cost === null ? record.cost : costAdd(totals.cost, record.cost);
+    }
+    totals.unpriced_models = [...unpriced].sort();
+    totals.cost_complete = totals.unpriced_records === 0 && totals.billed_unknown_records === 0;
+    return totals;
+}
+/**
+ * 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 function createUsageLedgerFile(opts) {
+    const env = opts.env ?? process.env;
+    if (!ledgerEnabled(env))
+        return null;
+    const override = env[ENV_USAGE_LEDGER_FILE];
+    const path = override === undefined || override.trim() === "" ? join(opts.dataDir, USAGE_LEDGER_FILE) : override;
+    const pricing = loadPricingFile(pricingPath(opts.dataDir, env));
+    return new UsageLedgerFile({ path, pricing, ...(opts.now === undefined ? {} : { now: opts.now }) });
+}
+/** `off` (and the usual falsey spellings) turns the ledger off. */
+export function ledgerEnabled(env = process.env) {
+    const raw = (env[ENV_USAGE_LEDGER] ?? "").trim().toLowerCase();
+    return !["off", "0", "false", "no"].includes(raw);
+}
+function warn(message) {
+    process.stderr.write(`usage ledger: ${message}\n`);
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/pricing.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Pricing snapshot for the usage ledger (iteration E §3.2.2, W728 P0).
+ *
+ * The engine converts tokens into money with EXACTLY one rule:
+ * `tokens / 1e6 × unit price`. It deliberately does NOT re-implement the
+ * platform's billing (group multipliers, expressions, cache discounts):
+ * `newapi` owns the price of record (LTS `biz/newapi.md` I1–I3), so a snapshot
+ * here is an engine-side ESTIMATE, never a second source of truth (§3.5 R3-2).
+ *
+ * `pricing.json` is operator/ops supplied (§3.5 R3-1: P0 does not depend on the
+ * newapi sync script). A model absent from the table is NOT priced as 0:
+ * [priceFor] returns null and the caller must mark the record `unpriced`.
+ * A missing or unreadable file is an empty table (every model unpriced) — it is
+ * reported on stderr and never throws, because a pricing problem must not break
+ * a turn.
+ */
+import type { Usage } from "@celestea/core";
+/** `<data dir>/pricing.json` (§3.2.2). */
+export declare const PRICING_FILE = "pricing.json";
+/** Path override (`CELESTEA_PRICING_FILE`). */
+export declare const ENV_PRICING_FILE = "CELESTEA_PRICING_FILE";
+/** The only unit the ledger understands (per million tokens). */
+export declare const PRICING_UNIT = "per_mtok";
+/** Unit prices of one model, in `PricingTable.currency`, per million tokens. */
+export interface ModelPrice {
+    in: number;
+    out: number;
+    cache_read: number;
+}
+/** A loaded price table plus where it came from (never a bare number map). */
+export interface PricingTable {
+    version: string;
+    currency: string;
+    unit: typeof PRICING_UNIT;
+    models: Record<string, ModelPrice>;
+    effective_from: number | null;
+    /** Absolute path the snapshot was read from; null = no table at all. */
+    path: string | null;
+}
+/** Money of one ledger row: the three components and their sum. */
+export interface LedgerCost {
+    /**
+     * Cost of the UNCACHED input only: `max(0, prompt_tokens - cache_read) × in`.
+     * The prompt counter already contains the cache-hit region, so `in` is NOT
+     * `prompt_tokens × in` - the hit region is charged once, under [cache].
+     */
+    in: number;
+    /** Cost of the completion tokens (`completion_tokens × out`). */
+    out: number;
+    /**
+     * Cost of the cache-hit region (`cache_read × cache_read`). Charged HERE
+     * only - never also at the input price.
+     */
+    cache: number;
+    /** `in + out + cache` (the parts cannot drift from the total). */
+    total: number;
+}
+/** A table with no models: every lookup is `unpriced` (never 0). */
+export declare function emptyPricing(path?: string | null): PricingTable;
+/** `<data dir>/pricing.json`, overridable with `CELESTEA_PRICING_FILE`. */
+export declare function pricingPath(dataDir: string, env?: NodeJS.ProcessEnv): string;
+/** Price of `model`, or null when the snapshot does not cover it. */
+export declare function priceFor(table: PricingTable, model: string | null): ModelPrice | null;
+/**
+ * `uncached_in × in + completion × out + cache_read × cache_read`, rounded
+ * to 6 decimals.
+ *
+ * The provider's `prompt_tokens` ALREADY CONTAINS the cache-hit region (host
+ * turn-usage: `total - output === input + cacheRead + cacheWrite`; the LLM seam
+ * reads `prompt_tokens` as that total and the cache counters separately), so
+ * the hit region must be billed ONCE, at the cache price:
+ * `billableIn = max(0, prompt_tokens - cache_read)` is the input the provider
+ * did NOT serve from cache. Charging the whole prompt at the input price AND
+ * the cache counter on top would bill the hit region twice; that reading was
+ * rejected by the product, so this function never does it.
+ *
+ * `max(0, ...)` guards anomalous data (`cache_read > prompt_tokens`, which the
+ * provider should never report): the input component floors at 0 instead of
+ * going negative. The cache component still charges what was reported.
+ */
+export declare function costOf(usage: Usage, price: ModelPrice): LedgerCost;
+/** Sum of two costs, component-wise (so the total cannot drift from the parts). */
+export declare function costAdd(a: LedgerCost, b: LedgerCost): LedgerCost;
+/** The frozen form written into every priced ledger row (a per-row snapshot). */
+export interface PriceSnapshot extends ModelPrice {
+    version: string;
+    currency: string;
+    unit: string;
+}
+/** `price` field of a priced ledger row. */
+export declare function priceSnapshot(table: PricingTable, price: ModelPrice): PriceSnapshot;
+/** Parse a pricing.json document; null = malformed (caller falls back to empty). */
+export declare function parsePricing(input: unknown, path?: string | null): PricingTable | null;
+/**
+ * Read the snapshot. A missing file is an empty table (everything unpriced). A
+ * file that exists but does not parse is ALSO an empty table, reported on
+ * stderr: pricing half the fleet by a half-read table would under-report cost
+ * silently (G3-7).
+ */
+export declare function loadPricingFile(path: string): PricingTable;