aimeat 3.1.0 → 3.3.0

package/dist/src/services/usage/archive-job.js

@@ -0,0 +1,36 @@
+import { logger } from '../../utils/logger.js';
+/** How long raw stays queryable in the hot tables. */
+const HOT_DAYS = Number(process.env.AIMEAT_USAGE_HOT_DAYS) || 90;
+/** Hour-grain rollups are a live-dashboard resolution; the day grain carries the history. */
+const HOUR_ROLLUP_DAYS = Number(process.env.AIMEAT_USAGE_HOUR_ROLLUP_DAYS) || 30;
+const BATCH = Number(process.env.AIMEAT_USAGE_ARCHIVE_BATCH) || 2_000;
+/** Sweeps per run. Bounded so one run cannot occupy the database for an unbounded time. */
+const MAX_SWEEPS = 50;
+function daysAgo(days) {
+    return new Date(Date.now() - days * 86_400_000).toISOString();
+}
+export async function runUsageArchiveJob(storage) {
+    const before = daysAgo(HOT_DAYS);
+    const pruneHourBefore = daysAgo(HOUR_ROLLUP_DAYS).slice(0, 13);
+    const total = { usageCalls: 0, usageEvents: 0, hourRollupsPruned: 0 };
+    for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+        const moved = await storage.archiveUsageRows({ before, pruneHourBefore, batch: BATCH });
+        total.usageCalls += moved.usageCalls;
+        total.usageEvents += moved.usageEvents;
+        total.hourRollupsPruned += moved.hourRollupsPruned;
+        // Nothing left to move. The hour prune is a single statement that runs on every sweep and is
+        // idempotent, so it is not part of the stop condition.
+        if (moved.usageCalls === 0 && moved.usageEvents === 0)
+            break;
+    }
+    if (total.usageCalls > 0 || total.usageEvents > 0 || total.hourRollupsPruned > 0) {
+        logger.info('usage-archive: swept', {
+            hotDays: HOT_DAYS,
+            calls: total.usageCalls,
+            events: total.usageEvents,
+            hourRollupsPruned: total.hourRollupsPruned,
+        });
+    }
+    return total;
+}
+//# sourceMappingURL=archive-job.js.map

package/dist/src/services/usage/archive-job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-job.js","sourceRoot":"","sources":["../../../../src/services/usage/archive-job.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,sDAAsD;AACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC;AACjE,6FAA6F;AAC7F,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,IAAI,EAAE,CAAC;AACjF,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,IAAI,KAAK,CAAC;AACtE,2FAA2F;AAC3F,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAgB;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAuB,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;IAE1F,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACxF,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC;QACrC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;QACvC,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,CAAC;QACnD,6FAA6F;QAC7F,uDAAuD;QACvD,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,KAAK,CAAC,WAAW,KAAK,CAAC;YAAE,MAAM;IAC/D,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;QACjF,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE;YAClC,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,KAAK,CAAC,UAAU;YACvB,MAAM,EAAE,KAAK,CAAC,WAAW;YACzB,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/services/usage/record-app-open.d.ts

@@ -0,0 +1,8 @@
+export declare function recordAppOpen(args: {
+    /** The app author's identity as stored on the app record. */
+    appOwnerGaii: string;
+    filename: string;
+    /** The signed-in visitor, when there is one. */
+    viewer?: string | null;
+}): void;
+//# sourceMappingURL=record-app-open.d.ts.map

package/dist/src/services/usage/record-app-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-app-open.d.ts","sourceRoot":"","sources":["../../../../src/services/usage/record-app-open.ts"],"names":[],"mappings":"AAqCA,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,GAAG,IAAI,CAeP"}

package/dist/src/services/usage/record-app-open.js

@@ -0,0 +1,52 @@
+/**
+ * @file src/services/usage/record-app-open.ts
+ * @description Records that an app was opened, from the two places an app is actually served.
+ *   Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHAT THIS REPLACES. `AppDownload.count` is one lifetime integer per app: it can say an app has
+ *   been opened 4 000 times and can never say whether that was last week or last year, by two
+ *   people or by two hundred. It stays (the catalogue shows it); this adds the dimensions that make
+ *   "is this app alive" answerable.
+ *
+ *   WHOSE CALL IT IS. `ownerGhii` is the VIEWER, because the question the owner cuts answer is
+ *   "which apps does this person use". The app's author goes in `counterpartyGhii`, which is the
+ *   same slot an exchange seller occupies, so an author reads their app's traffic through the same
+ *   cut a capability provider reads theirs. An anonymous open carries no owner at all rather than
+ *   being attributed to the author, which would make every public app look like its author's own use.
+ * @structure
+ *   - recordAppOpen({ appOwnerGaii, filename, viewer })
+ * @usage
+ *   recordAppOpen({ appOwnerGaii: app.ownerGaii, filename: app.filename, viewer: req.auth?.sub });
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: app opens become a measured, time-dimensioned surface.
+ */
+import { recordUsageCall } from './usage-buffer.js';
+import { ownerGhiiOf } from '../../utils/gaii.js';
+/** `undefined`, `''` and the literal 'anon' all mean nobody signed in. */
+function isAnonymous(viewer) {
+    return !viewer || viewer === 'anon';
+}
+function actorKindOf(principal) {
+    if (principal.startsWith('eco:'))
+        return 'eco';
+    if (principal.includes('#'))
+        return 'agent';
+    return 'owner';
+}
+export function recordAppOpen(args) {
+    const anon = isAnonymous(args.viewer);
+    const viewer = anon ? '' : args.viewer;
+    recordUsageCall({
+        ownerGhii: anon ? '' : ownerGhiiOf(viewer),
+        actorGaii: viewer,
+        actorKind: anon ? 'anon' : actorKindOf(viewer),
+        surface: 'app',
+        // The app id everywhere else in the node: `owner/filename`. Same string in the coordinate and
+        // in appId, so a report can group by either without knowing which surface produced the row.
+        coordinate: `${ownerGhiiOf(args.appOwnerGaii).split('@')[0]}/${args.filename}`,
+        appId: `${ownerGhiiOf(args.appOwnerGaii).split('@')[0]}/${args.filename}`,
+        counterpartyGhii: ownerGhiiOf(args.appOwnerGaii),
+        outcome: 'ok',
+    });
+}
+//# sourceMappingURL=record-app-open.js.map

package/dist/src/services/usage/record-app-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-app-open.js","sourceRoot":"","sources":["../../../../src/services/usage/record-app-open.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,0EAA0E;AAC1E,SAAS,WAAW,CAAC,MAAsB;IACzC,OAAO,CAAC,MAAM,IAAI,MAAM,KAAK,MAAM,CAAC;AACtC,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAM7B;IACC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAgB,CAAC;IACjD,eAAe,CAAC;QACd,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC;QAC1C,SAAS,EAAE,MAAM;QACjB,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC;QAC9C,OAAO,EAAE,KAAK;QACd,8FAA8F;QAC9F,4FAA4F;QAC5F,UAAU,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE;QAC9E,KAAK,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE;QACzE,gBAAgB,EAAE,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC;QAChD,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/src/services/usage/rollup-cuts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file src/services/usage/rollup-cuts.ts
+ * @description THE EXTENSION POINT. A "cut" is one named dimension set the fold materialises, and
+ *   adding a report to this system means adding an entry here plus a backfill. No migration, no
+ *   repository method, no provider pair, no new route.
+ *   Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY DECLARED CUTS RATHER THAN EVERY COMBINATION. Nine dimensions crossed with each other is a
+ *   row count nobody can reason about and an index nobody can use. Declaring the twenty slices the
+ *   product actually asks for keeps the table bounded by real cardinality: the largest,
+ *   call.owner.tool, is (active owners x tools they actually called) per day.
+ *
+ *   WHY GRAINS ARE PER-CUT. Hour grain is for a live dashboard and multiplies a cut's rows by 24.
+ *   Only the two cuts that back a live view carry it; the rest are day-only, and the archive job
+ *   prunes hour rows at 30 days while day rows are kept indefinitely.
+ *
+ *   ADDING A CUT: append it, then run POST /v1/admin/usage/rollup/rebuild so history exists for it.
+ *   Without the rebuild the new cut is correct from today forward and empty before that, which
+ *   looks exactly like "this feature was never used" on a chart.
+ * @structure
+ *   - UsageDim / UsageCut / CUTS
+ *   - cutsForStream(stream) · findCut(name)
+ * @usage
+ *   import { CUTS, cutsForStream } from './rollup-cuts.js';
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: twenty cuts over the llm and call streams.
+ */
+/** The dimension columns a cut may key on. Every one exists on UsageRollup and defaults to ''. */
+export type UsageDim = 'ownerGhii' | 'actorGaii' | 'appId' | 'model' | 'provider' | 'surface' | 'outcome' | 'coordinate' | 'counterpartyGhii';
+export interface UsageCut {
+    /** Stable name, stored in the row. Renaming one orphans its history — add a new one instead. */
+    name: string;
+    /** Which raw stream feeds it. */
+    stream: 'llm' | 'call';
+    /** The dimensions this cut is keyed by. Everything else is rolled over and stored as ''. */
+    dims: UsageDim[];
+    grains: Array<'hour' | 'day'>;
+    /** What question this answers, so the list stays readable as it grows. */
+    answers: string;
+}
+export declare const CUTS: UsageCut[];
+export declare function cutsForStream(stream: 'llm' | 'call'): UsageCut[];
+export declare function findCut(name: string): UsageCut | undefined;
+//# sourceMappingURL=rollup-cuts.d.ts.map

package/dist/src/services/usage/rollup-cuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup-cuts.d.ts","sourceRoot":"","sources":["../../../../src/services/usage/rollup-cuts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,kGAAkG;AAClG,MAAM,MAAM,QAAQ,GAChB,WAAW,GACX,WAAW,GACX,OAAO,GACP,OAAO,GACP,UAAU,GACV,SAAS,GACT,SAAS,GACT,YAAY,GACZ,kBAAkB,CAAC;AAEvB,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,4FAA4F;IAC5F,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,eAAO,MAAM,IAAI,EAAE,QAAQ,EAyC1B,CAAC;AAOF,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,EAAE,CAEhE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE1D"}

package/dist/src/services/usage/rollup-cuts.js

@@ -0,0 +1,81 @@
+/**
+ * @file src/services/usage/rollup-cuts.ts
+ * @description THE EXTENSION POINT. A "cut" is one named dimension set the fold materialises, and
+ *   adding a report to this system means adding an entry here plus a backfill. No migration, no
+ *   repository method, no provider pair, no new route.
+ *   Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY DECLARED CUTS RATHER THAN EVERY COMBINATION. Nine dimensions crossed with each other is a
+ *   row count nobody can reason about and an index nobody can use. Declaring the twenty slices the
+ *   product actually asks for keeps the table bounded by real cardinality: the largest,
+ *   call.owner.tool, is (active owners x tools they actually called) per day.
+ *
+ *   WHY GRAINS ARE PER-CUT. Hour grain is for a live dashboard and multiplies a cut's rows by 24.
+ *   Only the two cuts that back a live view carry it; the rest are day-only, and the archive job
+ *   prunes hour rows at 30 days while day rows are kept indefinitely.
+ *
+ *   ADDING A CUT: append it, then run POST /v1/admin/usage/rollup/rebuild so history exists for it.
+ *   Without the rebuild the new cut is correct from today forward and empty before that, which
+ *   looks exactly like "this feature was never used" on a chart.
+ * @structure
+ *   - UsageDim / UsageCut / CUTS
+ *   - cutsForStream(stream) · findCut(name)
+ * @usage
+ *   import { CUTS, cutsForStream } from './rollup-cuts.js';
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: twenty cuts over the llm and call streams.
+ */
+const DAY = ['day'];
+const LIVE = ['hour', 'day'];
+export const CUTS = [
+    // ── LLM spend ──────────────────────────────────────────────────────────────────────────────
+    { name: 'llm.node', stream: 'llm', dims: [], grains: LIVE,
+        answers: 'node-wide LLM spend over time' },
+    { name: 'llm.owner', stream: 'llm', dims: ['ownerGhii'], grains: LIVE,
+        answers: 'per-user spend; the operator top-spenders list' },
+    { name: 'llm.model', stream: 'llm', dims: ['model', 'provider'], grains: DAY,
+        answers: 'which models are used most, node-wide, and where they ran' },
+    { name: 'llm.owner.model', stream: 'llm', dims: ['ownerGhii', 'model', 'provider'], grains: DAY,
+        answers: 'which models THIS person uses most' },
+    { name: 'llm.actor', stream: 'llm', dims: ['ownerGhii', 'actorGaii'], grains: DAY,
+        answers: 'per-agent spend' },
+    { name: 'llm.app', stream: 'llm', dims: ['appId'], grains: DAY,
+        answers: 'which app burns the most tokens, node-wide' },
+    { name: 'llm.owner.app', stream: 'llm', dims: ['ownerGhii', 'appId'], grains: DAY,
+        answers: 'this person spend per app' },
+    { name: 'llm.app.model', stream: 'llm', dims: ['appId', 'model', 'provider'], grains: DAY,
+        answers: 'which model an app actually calls — impossible before appId reached the ledger' },
+    // ── Calls ──────────────────────────────────────────────────────────────────────────────────
+    { name: 'call.node', stream: 'call', dims: [], grains: LIVE,
+        answers: 'total call volume and error rate' },
+    { name: 'call.owner', stream: 'call', dims: ['ownerGhii'], grains: LIVE,
+        answers: 'per-user activity' },
+    { name: 'call.surface', stream: 'call', dims: ['surface', 'outcome'], grains: DAY,
+        answers: 'is MCP or the web carrying the work' },
+    { name: 'call.owner.surface', stream: 'call', dims: ['ownerGhii', 'surface', 'outcome'], grains: DAY,
+        answers: 'how this person actually works' },
+    { name: 'call.tool', stream: 'call', dims: ['surface', 'coordinate', 'outcome'], grains: DAY,
+        answers: 'which tool is used, which fails, which nobody has ever called' },
+    { name: 'call.owner.tool', stream: 'call', dims: ['ownerGhii', 'surface', 'coordinate'], grains: DAY,
+        answers: 'the operator drill into one person tool use' },
+    { name: 'call.app', stream: 'call', dims: ['appId', 'outcome'], grains: DAY,
+        answers: 'which app is alive' },
+    { name: 'call.owner.app', stream: 'call', dims: ['ownerGhii', 'appId'], grains: DAY,
+        answers: 'who uses which app' },
+    { name: 'call.actor', stream: 'call', dims: ['ownerGhii', 'actorGaii'], grains: DAY,
+        answers: 'per-agent and per-app-grant activity' },
+    { name: 'call.provider.coordinate', stream: 'call',
+        dims: ['counterpartyGhii', 'coordinate', 'outcome'], grains: DAY,
+        answers: 'what a seller sold and what they refused; also an app author own traffic' },
+];
+const BY_STREAM = new Map([
+    ['llm', CUTS.filter(c => c.stream === 'llm')],
+    ['call', CUTS.filter(c => c.stream === 'call')],
+]);
+export function cutsForStream(stream) {
+    return BY_STREAM.get(stream) ?? [];
+}
+export function findCut(name) {
+    return CUTS.find(c => c.name === name);
+}
+//# sourceMappingURL=rollup-cuts.js.map

package/dist/src/services/usage/rollup-cuts.js.map

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

package/dist/src/services/usage/rollup-engine.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file src/services/usage/rollup-engine.ts
+ * @description The fold: raw usage rows in, precomputed UsageRollup deltas out, incrementally and
+ *   exactly once. Design: docs/internal/telemetria/02-design.md
+ *
+ *   EXACTLY-ONCE IS ONE PROPERTY IN ONE PLACE. The deltas and the watermark that accounts for them
+ *   commit together (storage.advanceUsageRollup). A crash before that commit replays the same rows;
+ *   a crash after it continues past them. Neither double-counts. Everything else here — batching,
+ *   pass caps, the fact projection — is bookkeeping around that one guarantee, and none of it is
+ *   allowed to advance the cursor on its own.
+ *
+ *   WHY A FACT IN THE MIDDLE. Each raw row becomes ONE fact carrying every dimension and every
+ *   metric, and each cut then picks the dimensions it keys on. Without that step, twenty cuts means
+ *   twenty places that each decide what "an error" is, and the day someone adds a metric, nineteen
+ *   of them are still right and one is not.
+ * @structure
+ *   - runUsageRollup(storage) -- fold both streams; returns what it processed
+ *   - foldStream(storage, stream) -- one stream, bounded passes
+ *   - factOfCall / factOfEvent -- raw row to fact
+ *   - accumulate(facts) -- facts to deltas, per declared cut and grain
+ * @usage
+ *   import { runUsageRollup } from './services/usage/rollup-engine.js';
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: incremental, transactional fold over the llm and call streams.
+ */
+import type { Storage, UsageCallRecord, UsageRollupDelta } from '../../storage/interface.js';
+/**
+ * The deltas a read would be missing because the fold has not run yet: everything after the
+ * watermark, projected through the same cuts, plus the call rows still sitting in the write buffer.
+ *
+ * WHY A READ NEEDS THIS AT ALL. Without it the serving layer is up to one fold interval stale, and
+ * an operator who just watched a spend happen would open the dashboard and see nothing. "It will
+ * appear in five minutes" is not something a person accepts from a number they are accountable for.
+ *
+ * WHY IT IS NOT A SCAN. The tail is bounded by the fold interval, not by history: it reads from the
+ * watermark forward with a hard limit, on the same (ts, id) index the fold uses. A node that has
+ * been running for a year reads exactly as many rows here as one that started this morning.
+ *
+ * It reuses `accumulate`, so a top-up can never disagree with the fold about what a row means.
+ */
+export declare function pendingRollupDeltas(storage: Storage, stream: 'llm' | 'call', bufferedCalls?: UsageCallRecord[]): Promise<UsageRollupDelta[]>;
+export interface FoldResult {
+    stream: 'llm' | 'call';
+    rows: number;
+    deltas: number;
+    passes: number;
+}
+/**
+ * Fold both streams. Called on a schedule; safe to call concurrently with itself only in the sense
+ * that the transaction protects correctness — a second overlapping run wastes work rather than
+ * corrupting anything, because it reads the cursor the first one has already advanced.
+ */
+export declare function runUsageRollup(storage: Storage): Promise<FoldResult[]>;
+/**
+ * Rebuild a bucket range from raw. Deletes the range first BECAUSE THE FOLD ADDS: re-folding onto
+ * existing rows would double every number in the window rather than correcting it. Then rewinds the
+ * cursors and lets the ordinary fold refill.
+ *
+ * Only reaches as far back as the hot window: raw older than that is in the archive, which this
+ * does not read. A rebuild across the archive boundary therefore produces a correct recent range
+ * and leaves the older buckets deleted, so the caller is given the boundary rather than discovering
+ * it as a hole in a chart.
+ */
+export declare function rebuildUsageRollup(storage: Storage, args: {
+    from: string;
+    grain?: 'hour' | 'day';
+}): Promise<{
+    cleared: number;
+    folded: FoldResult[];
+}>;
+//# sourceMappingURL=rollup-engine.d.ts.map

package/dist/src/services/usage/rollup-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup-engine.d.ts","sourceRoot":"","sources":["../../../../src/services/usage/rollup-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EACV,OAAO,EAAE,eAAe,EAAmB,gBAAgB,EAC5D,MAAM,4BAA4B,CAAC;AAgKpC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,aAAa,GAAE,eAAe,EAAO,GACpC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAc7B;AAED,MAAM,WAAW,UAAU;IAAG,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAsCpG;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAwB5E;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,GAC7C,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CASpD"}

package/dist/src/services/usage/rollup-engine.js

@@ -0,0 +1,237 @@
+import { logger } from '../../utils/logger.js';
+import { cutsForStream } from './rollup-cuts.js';
+/** Raw rows per pass. Small enough that one transaction stays short, large enough to catch up. */
+const BATCH = Number(process.env.AIMEAT_USAGE_ROLLUP_BATCH) || 5_000;
+/** Passes per run, so one run is bounded even after a long outage. The next run continues. */
+const MAX_PASSES = Number(process.env.AIMEAT_USAGE_ROLLUP_PASSES) || 20;
+/**
+ * The separator inside an in-memory grouping key. A dimension value can contain a space, a slash or
+ * a colon (`apptool:alice/app.html`, an owner GHII, a model id), so a printable separator would let
+ * two DIFFERENT dimension tuples collide into one bucket and silently merge two rows' numbers. A
+ * control character cannot appear in any of them. Written as an escape rather than a literal, so it
+ * stays visible in an editor and the file stays text to grep.
+ */
+const DIM_SEPARATOR = '\u0000';
+function factOfCall(r) {
+    return {
+        ts: r.ts,
+        ownerGhii: r.ownerGhii,
+        actorGaii: r.actorGaii,
+        appId: r.appId,
+        model: '', provider: '',
+        surface: r.surface,
+        outcome: r.outcome,
+        coordinate: r.coordinate,
+        counterpartyGhii: r.counterpartyGhii,
+        calls: 1,
+        // A refusal is the system working and an error is it failing. Counted apart on purpose: a
+        // refusal is a demand signal, an error is a defect, and one number covering both is useless
+        // for either.
+        errors: r.outcome === 'error' ? 1 : 0,
+        refusals: r.outcome === 'refused' ? 1 : 0,
+        tokensIn: 0, tokensOut: 0, costUsd: 0, unpricedCalls: 0,
+        chargedUnits: r.chargedUnits,
+        durationMs: r.durationMs,
+    };
+}
+function factOfEvent(e) {
+    return {
+        ts: e.ts,
+        ownerGhii: e.ownerGhii,
+        actorGaii: e.agentGaii,
+        appId: e.appId ?? '',
+        model: e.model,
+        provider: e.provider,
+        surface: e.surface ?? '',
+        outcome: 'ok',
+        coordinate: '',
+        // On a capability call the consumer is the other party; on an ordinary call there is none.
+        counterpartyGhii: e.consumerGhii ?? '',
+        calls: 1,
+        errors: 0, refusals: 0,
+        tokensIn: e.promptTokens,
+        tokensOut: e.completionTokens,
+        // null cost is NOT zero. It is a price we did not have, kept visible in its own counter rather
+        // than silently averaged into a total that would then understate what the node actually spent.
+        costUsd: e.costUsd ?? 0,
+        unpricedCalls: e.costUsd === null ? 1 : 0,
+        chargedUnits: 0,
+        durationMs: 0,
+    };
+}
+/** '2026-08-14' or '2026-08-14T13'. Both sort chronologically as plain text. */
+function bucketOf(ts, grain) {
+    return grain === 'day' ? ts.slice(0, 10) : ts.slice(0, 13);
+}
+/** The dimension values this cut keys on; everything outside the cut is '' (rolled over). */
+function dimsFor(cut, fact) {
+    const out = {
+        ownerGhii: '', actorGaii: '', appId: '', model: '', provider: '',
+        surface: '', outcome: '', coordinate: '', counterpartyGhii: '',
+    };
+    for (const d of cut.dims)
+        out[d] = fact[d];
+    return out;
+}
+/**
+ * Turn facts into one delta per (cut, grain, bucket, dimension tuple). All in memory: a batch is
+ * bounded, and doing it here means the database sees one upsert per distinct key rather than one
+ * per raw row.
+ */
+function accumulate(facts, stream) {
+    const buckets = new Map();
+    for (const fact of facts) {
+        for (const cut of cutsForStream(stream)) {
+            const dims = dimsFor(cut, fact);
+            for (const grain of cut.grains) {
+                const bucket = bucketOf(fact.ts, grain);
+                const key = [cut.name, grain, bucket, dims.ownerGhii, dims.actorGaii, dims.appId,
+                    dims.model, dims.provider, dims.surface, dims.outcome, dims.coordinate,
+                    dims.counterpartyGhii].join(DIM_SEPARATOR);
+                let entry = buckets.get(key);
+                if (!entry) {
+                    entry = {
+                        delta: {
+                            cut: cut.name, grain, bucket, ...dims,
+                            calls: 0, errors: 0, refusals: 0, tokensIn: 0, tokensOut: 0, costUsd: 0,
+                            unpricedCalls: 0, chargedUnits: 0, durationMsSum: 0, durationMsMax: 0, actorsSeen: 0,
+                        },
+                        actors: new Set(),
+                    };
+                    buckets.set(key, entry);
+                }
+                const d = entry.delta;
+                d.calls += fact.calls;
+                d.errors += fact.errors;
+                d.refusals += fact.refusals;
+                d.tokensIn += fact.tokensIn;
+                d.tokensOut += fact.tokensOut;
+                d.costUsd += fact.costUsd;
+                d.unpricedCalls += fact.unpricedCalls;
+                d.chargedUnits += fact.chargedUnits;
+                d.durationMsSum += fact.durationMs;
+                if (fact.durationMs > d.durationMsMax)
+                    d.durationMsMax = fact.durationMs;
+                if (fact.actorGaii)
+                    entry.actors.add(fact.actorGaii);
+            }
+        }
+    }
+    // Distinct within THIS batch only. Across batches the storage layer adds, so the stored number
+    // undercounts an actor active in two batches. That is why it is called actorsSeen rather than
+    // actors, is served with the caveat attached, and is never used for billing.
+    return [...buckets.values()].map(b => ({ ...b.delta, actorsSeen: b.actors.size }));
+}
+/**
+ * The deltas a read would be missing because the fold has not run yet: everything after the
+ * watermark, projected through the same cuts, plus the call rows still sitting in the write buffer.
+ *
+ * WHY A READ NEEDS THIS AT ALL. Without it the serving layer is up to one fold interval stale, and
+ * an operator who just watched a spend happen would open the dashboard and see nothing. "It will
+ * appear in five minutes" is not something a person accepts from a number they are accountable for.
+ *
+ * WHY IT IS NOT A SCAN. The tail is bounded by the fold interval, not by history: it reads from the
+ * watermark forward with a hard limit, on the same (ts, id) index the fold uses. A node that has
+ * been running for a year reads exactly as many rows here as one that started this morning.
+ *
+ * It reuses `accumulate`, so a top-up can never disagree with the fold about what a row means.
+ */
+export async function pendingRollupDeltas(storage, stream, bufferedCalls = []) {
+    const cursor = await storage.getUsageCursor(stream);
+    const lastTs = cursor?.lastTs ?? '';
+    const lastId = cursor?.lastId ?? '';
+    const raw = stream === 'call'
+        ? await storage.listUsageCallsForFold({ lastTs, lastId, limit: BATCH })
+        : await storage.listUsageEventsForFold({ lastTs, lastId, limit: BATCH });
+    const facts = stream === 'call'
+        ? [...raw, ...bufferedCalls].map(factOfCall)
+        : raw.map(factOfEvent);
+    if (facts.length === 0)
+        return [];
+    return accumulate(facts, stream);
+}
+/** Fold one stream forward from its watermark, in bounded passes. */
+async function foldStream(storage, stream) {
+    const cursor = await storage.getUsageCursor(stream);
+    let lastTs = cursor?.lastTs ?? '';
+    let lastId = cursor?.lastId ?? '';
+    let rows = 0, deltas = 0, passes = 0;
+    for (; passes < MAX_PASSES; passes++) {
+        const raw = stream === 'call'
+            ? await storage.listUsageCallsForFold({ lastTs, lastId, limit: BATCH })
+            : await storage.listUsageEventsForFold({ lastTs, lastId, limit: BATCH });
+        if (raw.length === 0)
+            break;
+        const facts = stream === 'call'
+            ? raw.map(factOfCall)
+            : raw.map(factOfEvent);
+        const batchDeltas = accumulate(facts, stream);
+        // The last row IN THE ORDER THE QUERY RETURNED, which is (ts, id) ascending. Taking a maximum
+        // by ts alone would skip the tail of a tied timestamp on the next pass.
+        const last = raw[raw.length - 1];
+        await storage.advanceUsageRollup({ stream, deltas: batchDeltas, lastTs: last.ts, lastId: last.id });
+        lastTs = last.ts;
+        lastId = last.id;
+        rows += raw.length;
+        deltas += batchDeltas.length;
+        // A short batch means the stream is caught up. Stopping here rather than issuing one more empty
+        // query is the difference between a quiet node doing one read per run and doing two.
+        if (raw.length < BATCH) {
+            passes++;
+            break;
+        }
+    }
+    return { stream, rows, deltas, passes };
+}
+/**
+ * Fold both streams. Called on a schedule; safe to call concurrently with itself only in the sense
+ * that the transaction protects correctness — a second overlapping run wastes work rather than
+ * corrupting anything, because it reads the cursor the first one has already advanced.
+ */
+export async function runUsageRollup(storage) {
+    const results = [];
+    for (const stream of ['llm', 'call']) {
+        try {
+            const r = await foldStream(storage, stream);
+            results.push(r);
+            if (r.rows > 0) {
+                logger.info('usage-rollup: folded', {
+                    stream, rows: r.rows, deltas: r.deltas, passes: r.passes,
+                });
+            }
+            if (r.passes >= MAX_PASSES) {
+                // Not an error: the cap did its job. Worth saying, because it means the serving layer is
+                // further behind than the run interval suggests and someone reading a chart should know.
+                logger.warn('usage-rollup: hit the pass cap, still catching up', { stream, rows: r.rows });
+            }
+        }
+        catch (err) {
+            // One stream failing must not stop the other, and neither may advance a cursor it did not
+            // account for — which advanceUsageRollup guarantees, so there is nothing to undo here.
+            logger.warn('usage-rollup: stream failed, cursor unchanged', { stream, error: String(err) });
+            results.push({ stream, rows: 0, deltas: 0, passes: 0 });
+        }
+    }
+    return results;
+}
+/**
+ * Rebuild a bucket range from raw. Deletes the range first BECAUSE THE FOLD ADDS: re-folding onto
+ * existing rows would double every number in the window rather than correcting it. Then rewinds the
+ * cursors and lets the ordinary fold refill.
+ *
+ * Only reaches as far back as the hot window: raw older than that is in the archive, which this
+ * does not read. A rebuild across the archive boundary therefore produces a correct recent range
+ * and leaves the older buckets deleted, so the caller is given the boundary rather than discovering
+ * it as a hole in a chart.
+ */
+export async function rebuildUsageRollup(storage, args) {
+    const cleared = await storage.clearUsageRollupRange({ from: args.from, grain: args.grain });
+    // Rewind to the START of the day being rebuilt, not to the bucket string: the cursor compares
+    // against an ISO timestamp, and '2026-08-14' sorts before every '2026-08-14T..' on that day.
+    const rewindTo = `${args.from.slice(0, 10)}T00:00:00.000Z`;
+    await storage.setUsageCursor('llm', rewindTo, '');
+    await storage.setUsageCursor('call', rewindTo, '');
+    const folded = await runUsageRollup(storage);
+    return { cleared, folded };
+}
+//# sourceMappingURL=rollup-engine.js.map

package/dist/src/services/usage/rollup-engine.js.map

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

package/dist/src/services/usage/usage-buffer.d.ts

@@ -0,0 +1,25 @@
+import type { Storage, UsageCallRecord, UsageCallInput, UsageCallFilter } from '../../storage/interface.js';
+/**
+ * Buffer one call. Never throws and never blocks: a door records what happened and gets on with
+ * answering the request.
+ */
+export declare function recordUsageCall(input: UsageCallInput): void;
+/**
+ * The unflushed tail, filtered the same way `listUsageCalls` filters storage. Reader and writer
+ * share a process, so there is no reason to make an operator wait out a flush interval to see a
+ * call that has already happened: an empty view they cannot explain is what makes a UI look broken.
+ */
+export declare function pendingUsageCalls(filter: UsageCallFilter): UsageCallRecord[];
+/**
+ * Write the buffer out. Snapshot-and-clear up front so calls arriving mid-flush accumulate for the
+ * next window. At-most-once by choice: a failed write drops that window rather than risking a
+ * double count, which matches what this stream is for.
+ */
+export declare function flushUsageBuffer(): Promise<void>;
+/** Wire storage and start the flush interval. Idempotent. */
+export declare function initUsageBuffer(storage: Storage): void;
+/** Stop the interval and perform one final flush. Called from graceful shutdown. */
+export declare function shutdownUsageBuffer(): Promise<void>;
+/** Test seam: drop everything in flight. Not used by the running node. */
+export declare function resetUsageBuffer(): void;
+//# sourceMappingURL=usage-buffer.d.ts.map

package/dist/src/services/usage/usage-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-buffer.d.ts","sourceRoot":"","sources":["../../../../src/services/usage/usage-buffer.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAmB5G;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAiC3D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,EAAE,CAS5E;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBtD;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAMtD;AAED,oFAAoF;AACpF,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMzD;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}