crewly 1.20.302 → 1.20.304

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.recorder.js

@@ -0,0 +1,314 @@
+/**
+ * Writes the usage ledger as work happens.
+ *
+ * Attribution comes from the trace context (which ticket an agent's turn is
+ * about, set when the harness delivers a message). The recorder listens to
+ * trace events and to token-usage events and appends facts; usage and busy
+ * time are summed per (unit, agent, model, hour) in memory and written as one
+ * delta fact per bucket on a timer, so the ledger stays small.
+ *
+ * Rules (specs/2026-10-11-usage-ledger.md):
+ * - A usage event belongs to the ticket(s) the agent's turn was about at the
+ *   event's time. One ticket: all of it. A delivery naming n tickets: 1/n
+ *   each. No ticket: a per-agent "(no ticket)" unit.
+ * - Busy time is recorded when a turn ends, in the ticket the turn started on
+ *   and the one it is on now, split evenly.
+ * - Owner messages delivered to an agent on a ticket are owner-message facts;
+ *   active spans are computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.recorder
+ */
+import { eventCostUsd, eventTokens } from '../monitoring/token-usage.service.js';
+import { getTraceContext } from '../trace/trace-context.service.js';
+import { setRequestObserver, setUsageObserver } from './ledger-hooks.js';
+import { cleanText, cut, EXCERPT_MAX, TITLE_MAX, titleFromSummary } from './excerpt.js';
+import { LEDGER_VERSION, UNTICKETED_PREFIX, } from './usage-ledger.types.js';
+/** Statuses that close a ticket / request. */
+const TERMINAL_STATUSES = new Set(['done', 'cancelled']);
+/** Owner messages closer than this on one unit are the same message delivered twice. */
+const OWNER_DEDUPE_MS = 2_000;
+/** Default flush interval of the in-memory buckets. */
+const FLUSH_INTERVAL_MS = 60_000;
+/**
+ * Start of the UTC hour of a time.
+ *
+ * @param ms - Epoch ms
+ * @returns ISO string of the hour start
+ */
+export function hourStart(ms) {
+    return new Date(Math.floor(ms / 3_600_000) * 3_600_000).toISOString();
+}
+/**
+ * Appends ledger facts from live events.
+ */
+export class UsageLedgerRecorder {
+    deps;
+    context;
+    now;
+    opened = new Set();
+    agentsSeen = new Set();
+    closed = new Set();
+    lastOwner = new Map();
+    usage = new Map();
+    busy = new Map();
+    detach = null;
+    timer = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.context = deps.context ?? getTraceContext;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    /**
+     * Start listening (trace events, usage events, new requests) and flushing.
+     */
+    start() {
+        if (this.detach)
+            return;
+        const removeListener = this.context().addListener((event, meta) => this.onTraceEvent(event, meta.share));
+        setUsageObserver((session, event) => this.noteUsage(session, event));
+        setRequestObserver((meta) => this.noteRequest(meta));
+        this.detach = () => {
+            removeListener();
+            setUsageObserver(null);
+            setRequestObserver(null);
+        };
+        this.timer = setInterval(() => void this.flush(), this.deps.flushIntervalMs ?? FLUSH_INTERVAL_MS);
+        this.timer.unref?.();
+    }
+    /**
+     * Stop listening and write what is buffered.
+     */
+    async stop() {
+        this.detach?.();
+        this.detach = null;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        await this.flush();
+    }
+    /**
+     * Write the buffered usage / busy buckets and wait for the files.
+     */
+    async flush() {
+        const facts = [...this.usage.values(), ...this.busy.values()];
+        this.usage.clear();
+        this.busy.clear();
+        this.deps.store.appendMany(facts);
+        await this.deps.store.flush();
+    }
+    /**
+     * A token-usage event was recorded: attribute it to the ticket(s) its
+     * session was working on at that time.
+     *
+     * @param session - Agent session
+     * @param event - The usage event
+     */
+    noteUsage(session, event) {
+        const at = Date.parse(event.timestamp);
+        const when = Number.isFinite(at) ? at : this.now();
+        const ctx = this.context();
+        let units = ctx.tracesAt(session, when);
+        if (event.traceId && units[0] !== event.traceId)
+            units = [event.traceId];
+        if (units.length === 0)
+            units = [`${UNTICKETED_PREFIX}${session}`];
+        const share = 1 / units.length;
+        const tokens = eventTokens(event);
+        const costUsd = eventCostUsd(event);
+        const info = this.deps.directory.lookup(session);
+        const hour = hourStart(when);
+        for (const unitId of units) {
+            this.ensureUnit(unitId, when);
+            this.noteAgent(unitId, session, when);
+            const key = [unitId, session, event.model, hour, share].join('|');
+            const fact = this.usage.get(key) ??
+                {
+                    v: LEDGER_VERSION,
+                    ts: hour,
+                    kind: 'usage',
+                    unitId,
+                    agent: session,
+                    ...(info?.team ? { team: info.team } : {}),
+                    model: event.model,
+                    ...(event.runtime ? { runtime: event.runtime } : {}),
+                    events: 0,
+                    share,
+                    input: 0,
+                    cachedInput: 0,
+                    output: 0,
+                    cacheWrite: 0,
+                    budget: 0,
+                    costUsd: 0,
+                    attribution: 'recorded',
+                };
+            fact.events += 1;
+            fact.input += tokens.input;
+            fact.cachedInput += tokens.cachedInput;
+            fact.output += tokens.output;
+            fact.cacheWrite += tokens.cacheWrite;
+            fact.budget += tokens.budget;
+            fact.costUsd += costUsd;
+            this.usage.set(key, fact);
+        }
+    }
+    /**
+     * A request got its trace: record what the ticket is about.
+     *
+     * @param meta - Request facts
+     */
+    noteRequest(meta) {
+        this.ensureUnit(meta.traceId);
+        this.deps.store.append({
+            v: LEDGER_VERSION,
+            ts: meta.createdAt ?? new Date(this.now()).toISOString(),
+            kind: 'unit.meta',
+            unitId: meta.traceId,
+            ...(meta.ticketId ? { ticketId: meta.ticketId } : {}),
+            requestId: meta.requestId,
+            title: cut(cleanText(meta.title), TITLE_MAX),
+            ...(meta.description ? { excerpt: cut(cleanText(meta.description), EXCERPT_MAX) } : {}),
+            ...(meta.channel ? { channel: meta.channel } : {}),
+            ...(meta.threadRef ? { threadRef: meta.threadRef } : {}),
+            attribution: 'recorded',
+        });
+    }
+    /**
+     * Fold one trace event into facts.
+     *
+     * @param event - The trace event
+     * @param share - Fraction of a shared fact this trace carries
+     */
+    onTraceEvent(event, share) {
+        const unitId = event.traceId;
+        const at = Date.parse(event.ts);
+        const when = Number.isFinite(at) ? at : this.now();
+        switch (event.type) {
+            case 'turn.delivered': {
+                this.ensureUnit(unitId, when);
+                if (event.refs.session)
+                    this.noteAgent(unitId, event.refs.session, when);
+                if (event.actor.kind === 'owner' && event.data?.kind === 'owner_message')
+                    this.noteOwnerMessage(unitId, when);
+                break;
+            }
+            case 'turn.ended': {
+                const busyMs = Number(event.data?.busyMs);
+                const session = event.refs.session ?? event.actor.session;
+                if (!session || !Number.isFinite(busyMs) || busyMs <= 0)
+                    break;
+                this.ensureUnit(unitId, when);
+                this.noteAgent(unitId, session, when);
+                this.addBusy(unitId, session, when, busyMs, share);
+                break;
+            }
+            case 'request.status':
+            case 'ticket.status': {
+                const to = typeof event.data?.to === 'string' ? event.data.to : '';
+                this.ensureUnit(unitId, when);
+                const projectId = typeof event.data?.projectId === 'string' ? event.data.projectId : '';
+                const project = projectId ? this.deps.directory.projectName(projectId) : undefined;
+                if (project) {
+                    this.deps.store.append({ v: LEDGER_VERSION, ts: event.ts, kind: 'unit.meta', unitId, project, attribution: 'recorded' });
+                }
+                if (TERMINAL_STATUSES.has(to)) {
+                    const key = `${unitId}|${to}`;
+                    if (!this.closed.has(key)) {
+                        this.closed.add(key);
+                        this.deps.store.append({ v: LEDGER_VERSION, ts: event.ts, kind: 'unit.closed', unitId, status: to, attribution: 'recorded' });
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    addBusy(unitId, agent, when, busyMs, share) {
+        const hour = hourStart(when);
+        const key = [unitId, agent, hour, share].join('|');
+        const info = this.deps.directory.lookup(agent);
+        const fact = this.busy.get(key) ??
+            {
+                v: LEDGER_VERSION,
+                ts: hour,
+                kind: 'busy',
+                unitId,
+                agent,
+                ...(info?.team ? { team: info.team } : {}),
+                turns: 0,
+                busyMs: 0,
+                share,
+                attribution: 'recorded',
+            };
+        fact.turns += 1;
+        fact.busyMs += busyMs;
+        this.busy.set(key, fact);
+    }
+    noteOwnerMessage(unitId, when) {
+        const last = this.lastOwner.get(unitId);
+        if (last !== undefined && Math.abs(when - last) < OWNER_DEDUPE_MS)
+            return;
+        this.lastOwner.set(unitId, when);
+        this.deps.store.append({ v: LEDGER_VERSION, ts: new Date(when).toISOString(), kind: 'owner.message', unitId, attribution: 'recorded' });
+    }
+    noteAgent(unitId, agent, when) {
+        const key = `${unitId}|${agent}`;
+        if (this.agentsSeen.has(key))
+            return;
+        this.agentsSeen.add(key);
+        const info = this.deps.directory.lookup(agent);
+        this.deps.store.append({
+            v: LEDGER_VERSION,
+            ts: new Date(when).toISOString(),
+            kind: 'unit.agent',
+            unitId,
+            agent,
+            ...(info?.team ? { team: info.team } : {}),
+            ...(info?.project ? { project: info.project } : {}),
+            attribution: 'recorded',
+        });
+    }
+    /**
+     * Write a unit's descriptive fact the first time the unit is seen (this
+     * process): ticket id, title, excerpt, kind, start. Later facts (the
+     * request's description, thread, project) fill the gaps.
+     */
+    ensureUnit(unitId, when = this.now()) {
+        if (this.opened.has(unitId))
+            return;
+        this.opened.add(unitId);
+        const ts = new Date(when).toISOString();
+        if (unitId.startsWith(UNTICKETED_PREFIX)) {
+            this.deps.store.append({
+                v: LEDGER_VERSION,
+                ts,
+                kind: 'unit.meta',
+                unitId,
+                rootKind: 'none',
+                title: `(no ticket) ${unitId.slice(UNTICKETED_PREFIX.length)}`,
+                attribution: 'recorded',
+            });
+            return;
+        }
+        let root;
+        try {
+            root = this.context().store.getEntry(unitId)?.root;
+        }
+        catch {
+            root = undefined;
+        }
+        const clean = root ? cleanText(root.summary) : '';
+        this.deps.store.append({
+            v: LEDGER_VERSION,
+            ts,
+            kind: 'unit.meta',
+            unitId,
+            ...(root?.refs.ticketId ? { ticketId: root.refs.ticketId } : {}),
+            ...(root?.refs.requestId ? { requestId: root.refs.requestId } : {}),
+            ...(root ? { rootKind: root.kind, openedAt: root.createdAt } : {}),
+            ...(root ? { title: titleFromSummary(root.summary), excerpt: cut(clean, EXCERPT_MAX) } : {}),
+            attribution: 'recorded',
+        });
+    }
+}
+//# sourceMappingURL=usage-ledger.recorder.js.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.recorder.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.recorder.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.runtime.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Wires the usage ledger: store, recorder, rollup, categories, report.
+ * One instance per process (see {@link getUsageLedger}).
+ *
+ * @module services/usage-ledger/usage-ledger.runtime
+ */
+import { LedgerRollup } from './ledger-rollup.js';
+import { type TeamLookup } from './team-directory.js';
+import { UsageCategoriesStore } from './usage-categories.store.js';
+import { type BackfillResult } from './usage-ledger.backfill.js';
+import { UsageLedgerRecorder } from './usage-ledger.recorder.js';
+import { UsageLedgerStore } from './usage-ledger.store.js';
+import { type CategoryLlm } from './unit-classifier.js';
+import { UsageReportService } from './usage-report.service.js';
+/** Overrides for tests. */
+export interface UsageLedgerOptions {
+    /** Crewly home (default CREWLY_HOME) */
+    home?: string;
+    directory?: TeamLookup;
+    llm?: CategoryLlm | null;
+}
+/**
+ * The assembled ledger.
+ */
+export declare class UsageLedger {
+    readonly store: UsageLedgerStore;
+    readonly rollup: LedgerRollup;
+    readonly categories: UsageCategoriesStore;
+    readonly directory: TeamLookup;
+    readonly recorder: UsageLedgerRecorder;
+    readonly reports: UsageReportService;
+    private readonly home;
+    private backfillTimer;
+    constructor(options?: UsageLedgerOptions);
+    /**
+     * Start recording and schedule the one-time history rebuild.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop recording and write what is buffered.
+     */
+    stop(): Promise<void>;
+    /**
+     * Rebuild history (once; later calls do nothing).
+     *
+     * @returns What happened
+     */
+    backfill(): Promise<BackfillResult>;
+}
+/**
+ * The process-wide ledger.
+ *
+ * @returns The ledger (created on first use)
+ */
+export declare function getUsageLedger(): UsageLedger;
+/**
+ * Replace the process-wide ledger (tests).
+ *
+ * @param ledger - Ledger, or null to rebuild lazily
+ */
+export declare function setUsageLedgerForTesting(ledger: UsageLedger | null): void;
+//# sourceMappingURL=usage-ledger.runtime.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.runtime.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAmB,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAK/D,2BAA2B;AAC3B,MAAM,WAAW,kBAAkB;IAClC,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,GAAG,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,WAAW;IACvB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,eAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,aAAa,CAA+B;gBAExC,OAAO,GAAE,kBAAuB;IAoB5C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;CAazC;AAID;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEzE"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.runtime.js

@@ -0,0 +1,106 @@
+/**
+ * Wires the usage ledger: store, recorder, rollup, categories, report.
+ * One instance per process (see {@link getUsageLedger}).
+ *
+ * @module services/usage-ledger/usage-ledger.runtime
+ */
+import * as path from 'path';
+import { TRACE_CONSTANTS } from '../../constants.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+import { LoggerService } from '../core/logger.service.js';
+import { TokenUsageService } from '../monitoring/token-usage.service.js';
+import { LedgerRollup } from './ledger-rollup.js';
+import { TeamDirectory } from './team-directory.js';
+import { UsageCategoriesStore } from './usage-categories.store.js';
+import { ensureLiveSince, runBackfill } from './usage-ledger.backfill.js';
+import { UsageLedgerRecorder } from './usage-ledger.recorder.js';
+import { UsageLedgerStore, LEDGER_DIR_NAME } from './usage-ledger.store.js';
+import { defaultCategoryLlm, UnitClassifier } from './unit-classifier.js';
+import { UsageReportService } from './usage-report.service.js';
+/** Delay before the one-time history rebuild, so startup is not slowed. */
+const BACKFILL_DELAY_MS = 120_000;
+/**
+ * The assembled ledger.
+ */
+export class UsageLedger {
+    store;
+    rollup = new LedgerRollup();
+    categories;
+    directory;
+    recorder;
+    reports;
+    home;
+    backfillTimer = null;
+    constructor(options = {}) {
+        this.home = options.home ?? getCrewlyHomePath();
+        const dir = path.join(this.home, LEDGER_DIR_NAME);
+        this.store = new UsageLedgerStore(dir);
+        this.categories = new UsageCategoriesStore(dir);
+        this.directory = options.directory ?? new TeamDirectory(this.home);
+        this.recorder = new UsageLedgerRecorder({ store: this.store, directory: this.directory });
+        const classifier = new UnitClassifier(dir, options.llm === undefined ? defaultCategoryLlm() : options.llm);
+        this.reports = new UsageReportService({
+            rollup: this.rollup,
+            directory: this.directory,
+            classifier,
+            categories: async () => (await this.categories.list()).categories,
+            sync: async () => {
+                await this.recorder.flush();
+                await this.rollup.refresh(this.store);
+            },
+        });
+    }
+    /**
+     * Start recording and schedule the one-time history rebuild.
+     */
+    async start() {
+        await ensureLiveSince(this.store.dir);
+        this.recorder.start();
+        this.backfillTimer = setTimeout(() => {
+            void this.backfill().catch((err) => LoggerService.getInstance().createComponentLogger('UsageLedger').warn('Ledger backfill failed', { error: err instanceof Error ? err.message : String(err) }));
+        }, BACKFILL_DELAY_MS);
+        this.backfillTimer.unref?.();
+    }
+    /**
+     * Stop recording and write what is buffered.
+     */
+    async stop() {
+        if (this.backfillTimer)
+            clearTimeout(this.backfillTimer);
+        await this.recorder.stop();
+    }
+    /**
+     * Rebuild history (once; later calls do nothing).
+     *
+     * @returns What happened
+     */
+    async backfill() {
+        await this.directory.ready();
+        const liveSince = await ensureLiveSince(this.store.dir);
+        return runBackfill(this.store, {
+            forEachUsage: (visit) => TokenUsageService.getInstance().forEachEvent(visit),
+            traceDir: path.join(this.home, TRACE_CONSTANTS.DIR_NAME),
+            directory: this.directory,
+        }, { cutoffMs: Date.parse(liveSince) });
+    }
+}
+let instance = null;
+/**
+ * The process-wide ledger.
+ *
+ * @returns The ledger (created on first use)
+ */
+export function getUsageLedger() {
+    if (!instance)
+        instance = new UsageLedger();
+    return instance;
+}
+/**
+ * Replace the process-wide ledger (tests).
+ *
+ * @param ledger - Ledger, or null to rebuild lazily
+ */
+export function setUsageLedgerForTesting(ledger) {
+    instance = ledger;
+}
+//# sourceMappingURL=usage-ledger.runtime.js.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.runtime.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.runtime.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Append-only storage of ledger facts: one JSON object per line, one file per
+ * UTC month (`2026-10.jsonl`), plus `backfill.jsonl` for facts rebuilt from
+ * history. There is no update and no delete: a fact is written once.
+ *
+ * @module services/usage-ledger/usage-ledger.store
+ */
+import type { LedgerFact, LedgerFile } from './usage-ledger.types.js';
+/** Directory under CREWLY_HOME that holds the ledger. */
+export declare const LEDGER_DIR_NAME = "usage-ledger";
+/** File of facts rebuilt from history. */
+export declare const BACKFILL_FILE = "backfill.jsonl";
+/** Month file name of an ISO time (UTC). */
+export declare function monthFileFor(ts: string): string;
+/**
+ * The ledger's files. Writes are queued and applied in order.
+ */
+export declare class UsageLedgerStore {
+    readonly dir: string;
+    private chain;
+    private dirReady;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir?: string);
+    /**
+     * Queue a fact. Never throws; a failed write is dropped (accounting must not
+     * break the harness).
+     *
+     * @param fact - The fact
+     * @param file - `live` (month file of the fact) or `backfill`
+     */
+    append(fact: LedgerFact, file?: LedgerFile): void;
+    /**
+     * Queue several facts as one write.
+     *
+     * @param facts - The facts
+     * @param file - Target
+     */
+    appendMany(facts: LedgerFact[], file?: LedgerFile): void;
+    /**
+     * Wait for every queued write.
+     */
+    flush(): Promise<void>;
+    /**
+     * The ledger's fact files.
+     *
+     * @returns File names (month files oldest first, then the backfill file)
+     */
+    listFiles(): Promise<string[]>;
+}
+//# sourceMappingURL=usage-ledger.store.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.store.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,yDAAyD;AACzD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAC9C,0CAA0C;AAC1C,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAE9C,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAOhB,QAAQ,CAAC,GAAG,EAAE,MAAM;IANhC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;gBACkB,GAAG,GAAE,MAAwD;IAElF;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,UAAmB,GAAG,IAAI;IAIzD;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,IAAI,GAAE,UAAmB,GAAG,IAAI;IAwBhE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CASpC"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.store.js

@@ -0,0 +1,95 @@
+/**
+ * Append-only storage of ledger facts: one JSON object per line, one file per
+ * UTC month (`2026-10.jsonl`), plus `backfill.jsonl` for facts rebuilt from
+ * history. There is no update and no delete: a fact is written once.
+ *
+ * @module services/usage-ledger/usage-ledger.store
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** Directory under CREWLY_HOME that holds the ledger. */
+export const LEDGER_DIR_NAME = 'usage-ledger';
+/** File of facts rebuilt from history. */
+export const BACKFILL_FILE = 'backfill.jsonl';
+/** Month file name of an ISO time (UTC). */
+export function monthFileFor(ts) {
+    return `${/^\d{4}-\d{2}/.test(ts) ? ts.slice(0, 7) : new Date().toISOString().slice(0, 7)}.jsonl`;
+}
+/**
+ * The ledger's files. Writes are queued and applied in order.
+ */
+export class UsageLedgerStore {
+    dir;
+    chain = Promise.resolve();
+    dirReady = false;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir = path.join(getCrewlyHomePath(), LEDGER_DIR_NAME)) {
+        this.dir = dir;
+    }
+    /**
+     * Queue a fact. Never throws; a failed write is dropped (accounting must not
+     * break the harness).
+     *
+     * @param fact - The fact
+     * @param file - `live` (month file of the fact) or `backfill`
+     */
+    append(fact, file = 'live') {
+        this.appendMany([fact], file);
+    }
+    /**
+     * Queue several facts as one write.
+     *
+     * @param facts - The facts
+     * @param file - Target
+     */
+    appendMany(facts, file = 'live') {
+        if (facts.length === 0)
+            return;
+        const byFile = new Map();
+        for (const fact of facts) {
+            const name = file === 'backfill' ? BACKFILL_FILE : monthFileFor(fact.ts);
+            const lines = byFile.get(name) ?? [];
+            lines.push(JSON.stringify(fact));
+            byFile.set(name, lines);
+        }
+        this.chain = this.chain.then(async () => {
+            try {
+                if (!this.dirReady) {
+                    await fs.mkdir(this.dir, { recursive: true });
+                    this.dirReady = true;
+                }
+                for (const [name, lines] of byFile) {
+                    await fs.appendFile(path.join(this.dir, name), `${lines.join('\n')}\n`, 'utf-8');
+                }
+            }
+            catch {
+                // dropped
+            }
+        });
+    }
+    /**
+     * Wait for every queued write.
+     */
+    async flush() {
+        await this.chain;
+    }
+    /**
+     * The ledger's fact files.
+     *
+     * @returns File names (month files oldest first, then the backfill file)
+     */
+    async listFiles() {
+        try {
+            const names = await fs.readdir(this.dir);
+            const months = names.filter((n) => /^\d{4}-\d{2}\.jsonl$/.test(n)).sort();
+            return names.includes(BACKFILL_FILE) ? [...months, BACKFILL_FILE] : months;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=usage-ledger.store.js.map