@ashlr/hub 3.10.0 → 3.10.1

package/dist/core/routing/capacity-history-types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Seat capacity history — the wire contract (3.10.1). BROWSER-SAFE: types
+ * and constants only, so the Command surface can import them without pulling
+ * node:fs into the web bundle. The store is core/routing/capacity-history.ts;
+ * the route is core/routing/capacity-history-api.ts.
+ *
+ *   GET /api/verse/budget/history[?days=1..14]  → CapacityHistoryResponse
+ *
+ * WHY: the weekly burn-downs on Command need the whole window, but
+ * capacity.json holds only the latest snapshot and the budget route serves
+ * one reading per seat. Every snapshot publish (the Verse server's, or the
+ * daemon's when no Verse server runs) now also appends to a small rolling
+ * log beside capacity.json, and this route serves it back per seat.
+ */
+export declare const VERSE_CAPACITY_HISTORY_PATH = "/api/verse/budget/history";
+export declare const CAPACITY_HISTORY_DEFAULT_DAYS = 8;
+export declare const CAPACITY_HISTORY_MAX_DAYS = 14;
+/** The two account windows a burn-down draws (headroom.ts SeatWindowClass minus per-model windows, which never bind). */
+export type CapacityHistoryWindow = 'session' | 'weekly';
+/** Which process recorded the row: the Verse server, or the standing daemon. */
+export type CapacityHistorySource = 'daemon' | 'verse';
+/** One persisted row — one line of ~/.ashlr/routing/capacity-history.jsonl. */
+export interface CapacityHistoryRow {
+    /** When the provider window was READ (the seat's observedAt), ISO, second precision. */
+    ts: string;
+    /** Budget seat id (BUDGET_SEAT_ID_RE). */
+    seat: string;
+    window: CapacityHistoryWindow;
+    /** Percent of the window used, 0–100, one decimal — the peak account window of this class, exactly as headroom.ts reads it. */
+    usedPct: number;
+    /** The window's machine reset, when the provider publishes one (never for Claude). */
+    resetsAt: string | null;
+    source: CapacityHistorySource;
+}
+/** One seat window's readings, oldest first. */
+export interface CapacityHistorySeries {
+    seatId: string;
+    window: CapacityHistoryWindow;
+    /**
+     * `[epoch ms, percent used]`, oldest first. Interior points of a flat run
+     * are dropped (its first and last reading draw the same line), and a
+     * series longer than the response bound is thinned evenly — first and last
+     * points always kept.
+     */
+    points: Array<[number, number]>;
+    /** The newest row's machine reset, when known. */
+    resetsAt: string | null;
+    /** True when the series was thinned to fit the response bound. */
+    thinned: boolean;
+}
+export interface CapacityHistoryResponse {
+    v: 1;
+    generatedAt: string;
+    /** The window asked for, in days. */
+    days: number;
+    /** generatedAt − days: nothing older is served. */
+    since: string;
+    /** The oldest row served, across every series; null when there is none. */
+    oldestAt: string | null;
+    series: CapacityHistorySeries[];
+    /** True when series were dropped to fit the response bound. */
+    truncated: boolean;
+}

package/dist/core/routing/capacity-history-types.js

@@ -0,0 +1,18 @@
+/**
+ * Seat capacity history — the wire contract (3.10.1). BROWSER-SAFE: types
+ * and constants only, so the Command surface can import them without pulling
+ * node:fs into the web bundle. The store is core/routing/capacity-history.ts;
+ * the route is core/routing/capacity-history-api.ts.
+ *
+ *   GET /api/verse/budget/history[?days=1..14]  → CapacityHistoryResponse
+ *
+ * WHY: the weekly burn-downs on Command need the whole window, but
+ * capacity.json holds only the latest snapshot and the budget route serves
+ * one reading per seat. Every snapshot publish (the Verse server's, or the
+ * daemon's when no Verse server runs) now also appends to a small rolling
+ * log beside capacity.json, and this route serves it back per seat.
+ */
+export const VERSE_CAPACITY_HISTORY_PATH = '/api/verse/budget/history';
+export const CAPACITY_HISTORY_DEFAULT_DAYS = 8;
+export const CAPACITY_HISTORY_MAX_DAYS = 14;
+//# sourceMappingURL=capacity-history-types.js.map

package/dist/core/routing/capacity-history-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity-history-types.js","sourceRoot":"","sources":["../../../src/core/routing/capacity-history-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAA2B,CAAC;AACvE,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC"}

package/dist/core/routing/capacity-history.d.ts

@@ -0,0 +1,130 @@
+import { type CapacitySnapshot } from './budget-store.js';
+import type { CapacityHistoryResponse, CapacityHistoryRow, CapacityHistorySource, CapacityHistoryWindow } from './capacity-history-types.js';
+import { type CapacityWindow, type SeatCapacity, type SeatWindowClass } from './headroom.js';
+export declare const CAPACITY_HISTORY_FILE = "capacity-history.jsonl";
+/** A flat seat window still gets one row this often (so a reader can tell "flat" from "not watched"). */
+export declare const HISTORY_FLAT_ROW_MS: number;
+/** Rows younger than this are always kept (subject to the byte cap). */
+export declare const HISTORY_KEEP_MS: number;
+/** Past this size the file is compacted. */
+export declare const HISTORY_MAX_BYTES: number;
+/** Compaction rewrites down to this, so the next byte compaction is days away, not one append away. */
+export declare const HISTORY_COMPACT_TARGET_BYTES: number;
+/**
+ * Byte compaction thins before it drops (3.10.1 review: a flat cut to the
+ * target evicted the start of EVERY seat's weekly window once a multi-seat
+ * setup passed ~16 series). Each step leaves rows newer than `rawMs`
+ * untouched and keeps, per series, at most the lowest and the highest reading
+ * in each `slotMs` slot of the older rows — a climb keeps its ends, a reset
+ * keeps its drop. Steps run in order until the file fits the target. Rough
+ * cost of 8 days per series: 30 min slots ≈ 85 KB, 2 h ≈ 22 KB, 6 h ≈ 8 KB,
+ * so even MAX_SEATS paid seats (128 series) fit at the last step. Slots are
+ * epoch-aligned, so re-thinning already-thinned rows keeps the same rows.
+ */
+export declare const HISTORY_THIN_STEPS: readonly {
+    rawMs: number;
+    slotMs: number;
+}[];
+/** Response bounds: ≤ 32 series × ≤ 720 points (one per ~14 min over a week) — a few hundred KB at worst. */
+export declare const HISTORY_MAX_SERIES = 32;
+export declare const HISTORY_MAX_POINTS_PER_SERIES = 720;
+/** True when ASHLR_CAPACITY_HISTORY=0: no recorder writes (the route still serves what exists). */
+export declare function capacityHistoryDisabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function capacityHistoryPath(): string;
+/** Series identity: seat ids may contain `:` and `/` (BUDGET_SEAT_ID_RE), never `#`. */
+export declare function historySeriesKey(seatId: string, window: CapacityHistoryWindow): string;
+export interface HistoryRowOptions {
+    nowMs: number;
+    source: CapacityHistorySource;
+    /**
+     * Per seat id, the `resetsAt` of that seat's newest recorded WEEKLY row
+     * (appendCapacityHistory reads it from the file's tail). Feeds the sticky
+     * rule in {@link historyWindowClass}; absent = headroom.ts's class as is.
+     */
+    weeklyResetBySeat?: ReadonlyMap<string, string>;
+}
+/**
+ * The series a window's reading is recorded under: headroom.ts's class, made
+ * STABLE for the one window whose class depends on the clock.
+ *
+ * headroom.ts calls a Codex `*_primary` window weekly only while its reset is
+ * more than ~5 h away (the primary is usually the 5-hour window, but some
+ * accounts report a weekly-only primary). Recorded as is, a weekly-only
+ * primary would move to the session series for the last ~5 h before its
+ * reset, splitting one physical window across two lines. So a primary the
+ * live classifier calls 'session' stays 'weekly' when this seat's newest
+ * weekly row carries the same reset instant (within the countdown jitter)
+ * and no window the classifier already calls weekly accounts for that reset
+ * — i.e. that primary IS the window the weekly line has been drawing. A
+ * window's reset instant is fixed for its life, so a real 5-hour window
+ * never inherits a weekly one's. The next period (reset ~7 days out) is
+ * weekly on its own. With no weekly row on file (first seen inside its last
+ * 5 h) there is no evidence, and the headroom class stands. Budget gating is
+ * unchanged: this only picks the history series.
+ */
+export declare function historyWindowClass(seat: SeatCapacity, window: CapacityWindow, nowMs: number, weeklyReset: string | undefined): SeatWindowClass;
+/** The rows one snapshot of `seats` would record (before compression). Pure. */
+export declare function historyRowsFromSeats(seats: readonly SeatCapacity[], opts: HistoryRowOptions): CapacityHistoryRow[];
+/**
+ * Flat-run compression: record `row` after `last` (that series' newest row)
+ * only when it is a NEWER observation and its value or reset changed, or
+ * ≥ 10 min passed. An equal or older timestamp is an observation already
+ * recorded — by this process or the other recorder.
+ */
+export declare function shouldRecordRow(last: CapacityHistoryRow | undefined, row: CapacityHistoryRow): boolean;
+/** One line → a validated row, or null (corrupt, partial, foreign). Never throws. */
+export declare function parseHistoryLine(line: string): CapacityHistoryRow | null;
+/**
+ * Rewrite the file with rows younger than the keep window; duplicates (one
+ * observation recorded by both recorders) and unreadable lines go too. Over
+ * the compaction target, older rows are thinned per series
+ * (HISTORY_THIN_STEPS) so every seat keeps its whole window, and only if the
+ * coarsest step still does not fit are the oldest rows dropped. Atomic (temp
+ * + fsync + rename, 0600). Returns the rows kept. Throws on a storage failure.
+ */
+export declare function compactCapacityHistory(file?: string, nowMs?: number): number;
+export interface CapacityHistoryWriteResult {
+    appended: number;
+    compacted: boolean;
+    /** Why nothing could be written; null on success (including "nothing new"). */
+    error: string | null;
+}
+/**
+ * Record `seats` (one snapshot's readings) under the compression rule.
+ * NEVER THROWS: history is a convenience beside the budget gate, never a
+ * reason a publish or a budget read fails. Failures come back as `error`.
+ * A no-op under ASHLR_CAPACITY_HISTORY=0 — this is the one door every
+ * recorder (daemon, request path, follow) writes through.
+ */
+export declare function appendCapacityHistory(seats: readonly SeatCapacity[], opts: {
+    source: CapacityHistorySource;
+    nowMs?: number;
+    file?: string;
+    env?: NodeJS.ProcessEnv;
+}): CapacityHistoryWriteResult;
+/**
+ * Record a capacity snapshot — the one given, or (when `snapshot` is
+ * undefined) the one on disk. A missing or unreadable snapshot records
+ * nothing, and so does ASHLR_CAPACITY_HISTORY=0 (before any read). Never
+ * throws.
+ */
+export declare function recordCapacityHistoryFromSnapshot(snapshot: CapacitySnapshot | null | undefined, source: CapacityHistorySource, opts?: {
+    nowMs?: number;
+    file?: string;
+    snapshotFile?: string;
+    env?: NodeJS.ProcessEnv;
+}): CapacityHistoryWriteResult;
+/** Every readable row at or after `sinceMs`, in file order. Never throws. */
+export declare function readCapacityHistory(opts?: {
+    sinceMs?: number;
+    file?: string;
+}): CapacityHistoryRow[];
+type Point = [number, number];
+/** Drop the interior points of every flat run: its first and last reading draw the same line. */
+export declare function collapseFlatRuns(points: readonly Point[]): Point[];
+/** Group `rows` into bounded per-seat-window series for the last `days`. Pure. */
+export declare function buildCapacityHistoryResponse(rows: readonly CapacityHistoryRow[], opts: {
+    nowMs: number;
+    days: number;
+}): CapacityHistoryResponse;
+export {};