aimeat 3.1.0 → 3.3.0

package/dist/src/services/usage/usage-buffer.js

@@ -0,0 +1,146 @@
+/**
+ * @file src/services/usage/usage-buffer.ts
+ * @description The one write door for the usage call stream. Every measured call anywhere in the
+ *   node goes through `recordUsageCall`, which buffers in memory and flushes on an interval.
+ *   Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY BUFFERED, AND WHY THIS IS NOT THE BILLING PATH. A call must never wait on a metrics write,
+ *   and a metrics write must never be able to fail a call. That trade means at most one flush
+ *   window is lost on a hard kill, which is fine for reporting and is exactly why the money paths
+ *   (AgentUsageDaily, the budget alerts, the morsel settlement) stay synchronous and do not move
+ *   behind this buffer. Reporting may be approximate at the edge; a ledger may not.
+ *
+ *   WHY IT IS SYNCHRONOUS AND RETURNS VOID. A door that could `await` this would eventually be
+ *   written to `await` it inside a request path, and then a slow database would be a slow node. The
+ *   signature refuses that: there is nothing to await and nothing to catch.
+ * @structure
+ *   - initUsageBuffer(storage)     -- wire storage + start the flush interval
+ *   - recordUsageCall(input)       -- buffer one call (fire and forget, never throws)
+ *   - pendingUsageCalls(filter)    -- the unflushed tail, so a just-made call is not invisible
+ *   - flushUsageBuffer()           -- write the buffer out
+ *   - shutdownUsageBuffer()        -- stop the interval + final flush
+ * @usage
+ *   import { recordUsageCall } from '../services/usage/usage-buffer.js';
+ *   recordUsageCall({ ownerGhii, surface: 'mcp', coordinate: toolName, outcome: 'ok', durationMs });
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: the buffered ingest door for the usage call stream.
+ */
+import { randomUUID } from 'node:crypto';
+import { logger } from '../../utils/logger.js';
+/** Flush cadence. A dashboard reading raw calls is at most this stale, plus the fold's own lag. */
+const FLUSH_INTERVAL_MS = Number(process.env.AIMEAT_USAGE_BUFFER_MS) || 15_000;
+/**
+ * Hard ceiling on the unflushed buffer. If storage is down, telemetry must degrade rather than grow
+ * until the process dies: past this, the OLDEST entries drop. Losing the oldest reporting rows is a
+ * gap in a chart; running out of memory takes the node with it.
+ */
+const MAX_BUFFERED = 20_000;
+let storageRef = null;
+let flushTimer = null;
+let flushing = false;
+let buffer = [];
+let droppedSinceLastWarning = 0;
+/**
+ * Buffer one call. Never throws and never blocks: a door records what happened and gets on with
+ * answering the request.
+ */
+export function recordUsageCall(input) {
+    try {
+        buffer.push({
+            id: randomUUID(),
+            ts: input.ts ?? new Date().toISOString(),
+            ownerGhii: input.ownerGhii,
+            actorGaii: input.actorGaii ?? '',
+            actorKind: input.actorKind ?? 'owner',
+            surface: input.surface,
+            coordinate: input.coordinate,
+            appId: input.appId ?? '',
+            counterpartyGhii: input.counterpartyGhii ?? '',
+            outcome: input.outcome ?? 'ok',
+            reason: input.reason ?? '',
+            durationMs: Math.max(0, Math.round(input.durationMs ?? 0)),
+            chargedUnits: Math.max(0, Math.round(input.chargedUnits ?? 0)),
+            unit: input.unit ?? '',
+            currency: input.currency ?? '',
+            entitlementId: input.entitlementId ?? '',
+            runId: input.runId ?? '',
+            meta: input.meta ?? {},
+        });
+        if (buffer.length > MAX_BUFFERED) {
+            const overflow = buffer.length - MAX_BUFFERED;
+            buffer.splice(0, overflow);
+            droppedSinceLastWarning += overflow;
+        }
+    }
+    catch (err) {
+        // Recording a call must never be able to fail the call. There is no retry that helps here:
+        // whatever went wrong is in this process, and the row is not worth a second attempt.
+        logger.warn('usage-buffer: dropped one call record', { error: String(err) });
+    }
+}
+/**
+ * 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 function pendingUsageCalls(filter) {
+    return buffer.filter(r => (!filter.ownerGhii || r.ownerGhii === filter.ownerGhii)
+        && (!filter.actorGaii || r.actorGaii === filter.actorGaii)
+        && (!filter.surface || r.surface === filter.surface)
+        && (!filter.appId || r.appId === filter.appId)
+        && (!filter.outcome || r.outcome === filter.outcome)
+        && (!filter.from || r.ts >= filter.from)
+        && (!filter.to || r.ts <= filter.to));
+}
+/**
+ * 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 async function flushUsageBuffer() {
+    if (!storageRef || flushing || buffer.length === 0)
+        return;
+    flushing = true;
+    const batch = buffer;
+    buffer = [];
+    if (droppedSinceLastWarning > 0) {
+        logger.warn('usage-buffer: dropped oldest records to stay under the memory ceiling', {
+            dropped: droppedSinceLastWarning, ceiling: MAX_BUFFERED,
+        });
+        droppedSinceLastWarning = 0;
+    }
+    try {
+        await storageRef.appendUsageCall(batch);
+    }
+    catch (err) {
+        logger.warn('usage-buffer: flush failed, this window is lost', {
+            count: batch.length, error: String(err),
+        });
+    }
+    finally {
+        flushing = false;
+    }
+}
+/** Wire storage and start the flush interval. Idempotent. */
+export function initUsageBuffer(storage) {
+    storageRef = storage;
+    if (flushTimer)
+        return;
+    flushTimer = setInterval(() => { void flushUsageBuffer(); }, FLUSH_INTERVAL_MS);
+    // Don't keep the process alive solely for the flush timer (matters for in-process tests).
+    flushTimer.unref?.();
+}
+/** Stop the interval and perform one final flush. Called from graceful shutdown. */
+export async function shutdownUsageBuffer() {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    await flushUsageBuffer();
+}
+/** Test seam: drop everything in flight. Not used by the running node. */
+export function resetUsageBuffer() {
+    buffer = [];
+    droppedSinceLastWarning = 0;
+}
+//# sourceMappingURL=usage-buffer.js.map

package/dist/src/services/usage/usage-buffer.js.map

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

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

@@ -0,0 +1,115 @@
+/**
+ * @file src/services/usage/usage-read.ts
+ * @description The one read path over the serving layer. A caller names a REPORT and a scope; this
+ *   resolves it to a declared cut, queries the precomputed rows, and returns them already grouped,
+ *   sorted and totalled. Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY A REPORT NAME RATHER THAN A CUT NAME. A cut is an internal storage decision — which
+ *   dimension set was materialised. A report is what someone wants to see. Keeping them apart means
+ *   a cut can be split, renamed or given a finer grain without breaking a URL anyone bookmarked,
+ *   and it means the owner and operator versions of the same question ("which models get used")
+ *   resolve to DIFFERENT cuts behind ONE name, so neither door has to know about the other's.
+ *
+ *   OWNER SCOPING IS STRUCTURAL, NOT A FILTER SOMEONE REMEMBERED. An owner-scoped read resolves to
+ *   a cut that carries ownerGhii and is always queried with it set. There is no code path here that
+ *   takes an ownerGhii from a caller and trusts it: the route passes the resolved identity, and the
+ *   cross-owner variants are separate report keys the operator door alone can reach.
+ * @structure
+ *   - OWNER_REPORTS / NODE_REPORTS -- report name to cut, per scope
+ *   - readUsageReport(storage, args) -- the query, grouped and totalled
+ *   - usageComputedThrough(storage) -- how fresh the serving layer is
+ * @usage
+ *   const report = await readUsageReport(storage, { report: 'model', ownerGhii, from, to });
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: one read service over the precomputed rollups.
+ */
+import type { Storage, UsageRollupRow, UsageRollupFilter } from '../../storage/interface.js';
+import { type UsageDim } from './rollup-cuts.js';
+/** Reports an owner may ask about their OWN usage. Every cut here carries ownerGhii. */
+export declare const OWNER_REPORTS: Record<string, string>;
+/** Reports across every owner. Operator-only: the calling route MUST gate on the operator role. */
+export declare const NODE_REPORTS: Record<string, string>;
+export interface UsageGroup {
+    /** Display label for this row: the dimension that names it, or the bucket for a time series. */
+    key: string;
+    /** Every dimension this cut keyed on, so a client can drill without parsing `key`. */
+    dims: Partial<Record<UsageDim, string>>;
+    calls: number;
+    errors: number;
+    refusals: number;
+    tokens_in: number;
+    tokens_out: number;
+    total_tokens: number;
+    cost_usd: number;
+    unpriced_calls: number;
+    charged_units: number;
+    duration_ms_avg: number;
+    duration_ms_max: number;
+    /** Distinct actors, undercounted across fold batches. Never use for billing. */
+    actors_seen_approx: number;
+}
+export interface UsageReport {
+    report: string;
+    cut: string;
+    grain: 'hour' | 'day';
+    from: string;
+    to: string;
+    scope: 'owner' | 'node';
+    owner: string | null;
+    /** Buckets in chronological order, for a chart. Empty unless `series` was asked for. */
+    series: Array<{
+        bucket: string;
+        calls: number;
+        cost_usd: number;
+        total_tokens: number;
+    }>;
+    groups: UsageGroup[];
+    totals: Omit<UsageGroup, 'key' | 'dims'>;
+    /**
+     * The oldest point both raw streams have been folded through. Everything after it may be missing
+     * from these numbers. Stated rather than implied, because a dashboard that silently lags is a
+     * dashboard people stop trusting the first time they notice.
+     */
+    computed_through: string | null;
+    /** True when the request asked for a window the archive holds and the hot tables no longer do. */
+    beyond_hot_window: boolean;
+}
+/** YYYY-MM-DD `days` before today, UTC. */
+export declare function dayNDaysAgo(days: number): string;
+export interface ReadUsageArgs {
+    report: string;
+    scope: 'owner' | 'node';
+    /** Required when scope is 'owner'. Ignored — deliberately — when scope is 'node'. */
+    ownerGhii?: string;
+    from?: string;
+    to?: string;
+    grain?: 'hour' | 'day';
+    /** Also return the per-bucket series (a chart wants it; a table does not). */
+    series?: boolean;
+    limit?: number;
+}
+export declare class UnknownReportError extends Error {
+    available: string[];
+    constructor(report: string, available: string[]);
+}
+/** The oldest point both streams have been folded through; null before the first fold. */
+export declare function usageComputedThrough(storage: Storage): Promise<string | null>;
+/**
+ * Read a cut INCLUDING what the fold has not caught up on yet.
+ *
+ * The stored rows answer the history; the pending deltas answer the last few minutes. Merging them
+ * here rather than making every caller do it is what lets both the owner reports and the two
+ * operator aggregates be live and bounded at the same time — the alternative was either a stale
+ * dashboard or the full-table scan this whole layer replaced.
+ *
+ * Exported because the operator aggregates (ledger-admin, ai-usage-admin) compose their own shapes
+ * from the same cuts and must not accidentally read only the folded half.
+ */
+export declare function queryUsageRollupLive(storage: Storage, filter: UsageRollupFilter, stream: 'llm' | 'call'): Promise<UsageRollupRow[]>;
+/**
+ * Read one report. The window defaults to the trailing 30 days; a `grain` the cut does not
+ * materialise falls back to the one it does, rather than answering with an empty chart the caller
+ * has no way to explain.
+ */
+export declare function readUsageReport(storage: Storage, args: ReadUsageArgs): Promise<UsageReport>;
+//# sourceMappingURL=usage-read.d.ts.map

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

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

package/dist/src/services/usage/usage-read.js

@@ -0,0 +1,246 @@
+import { findCut } from './rollup-cuts.js';
+import { pendingRollupDeltas } from './rollup-engine.js';
+import { pendingUsageCalls } from './usage-buffer.js';
+/** Reports an owner may ask about their OWN usage. Every cut here carries ownerGhii. */
+export const OWNER_REPORTS = {
+    day: 'llm.owner',
+    model: 'llm.owner.model',
+    app: 'llm.owner.app',
+    agent: 'llm.actor',
+    tool: 'call.owner.tool',
+    surface: 'call.owner.surface',
+    'apps-used': 'call.owner.app',
+    activity: 'call.owner',
+    sold: 'call.provider.coordinate',
+};
+/** Reports across every owner. Operator-only: the calling route MUST gate on the operator role. */
+export const NODE_REPORTS = {
+    day: 'llm.node',
+    model: 'llm.model',
+    app: 'llm.app',
+    'app-model': 'llm.app.model',
+    agent: 'llm.actor',
+    user: 'llm.owner',
+    tool: 'call.tool',
+    surface: 'call.surface',
+    'apps-used': 'call.app',
+    activity: 'call.node',
+    provider: 'call.provider.coordinate',
+};
+/**
+ * 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';
+/**
+ * Which dimension NAMES a row, for the display label. First match wins.
+ *
+ * `outcome` is deliberately absent. It qualifies a row rather than identifying one, and having it
+ * as a fallback made an app-opens table label an unattributed row "ok" — a heading that reads like
+ * an app name and is not one. A row none of these can name is honestly "(unattributed)".
+ */
+const LABEL_ORDER = [
+    'model', 'appId', 'coordinate', 'actorGaii', 'surface', 'ownerGhii', 'counterpartyGhii', 'provider',
+];
+function emptyTotals() {
+    return {
+        calls: 0, errors: 0, refusals: 0, tokens_in: 0, tokens_out: 0, total_tokens: 0,
+        cost_usd: 0, unpriced_calls: 0, charged_units: 0,
+        duration_ms_avg: 0, duration_ms_max: 0, actors_seen_approx: 0,
+    };
+}
+/** YYYY-MM-DD `days` before today, UTC. */
+export function dayNDaysAgo(days) {
+    return new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+}
+export class UnknownReportError extends Error {
+    available;
+    constructor(report, available) {
+        super(`Unknown report "${report}". Available: ${available.join(', ')}`);
+        this.name = 'UnknownReportError';
+        this.available = available;
+    }
+}
+/** The oldest point both streams have been folded through; null before the first fold. */
+export async function usageComputedThrough(storage) {
+    const [llm, call] = await Promise.all([
+        storage.getUsageCursor('llm'),
+        storage.getUsageCursor('call'),
+    ]);
+    const points = [llm?.lastTs, call?.lastTs].filter((t) => !!t);
+    if (points.length === 0)
+        return null;
+    // The OLDER of the two: a report is only as fresh as its least fresh input, and claiming the
+    // newer would overstate exactly when one stream has fallen behind.
+    return points.sort()[0];
+}
+/** A delta carries no id or updatedAt; a reader only ever sums, so both are cosmetic here. */
+function deltaAsRow(d) {
+    return { ...d, id: '', extra: d.extra ?? {}, updatedAt: '' };
+}
+/** Does a not-yet-folded delta belong in the answer this filter asked for? */
+function deltaMatches(d, filter, grain) {
+    if (d.cut !== filter.cut || d.grain !== grain)
+        return false;
+    if (filter.from && d.bucket < filter.from)
+        return false;
+    if (filter.to && d.bucket > filter.to)
+        return false;
+    if (filter.ownerGhii && d.ownerGhii !== filter.ownerGhii)
+        return false;
+    if (filter.appId && d.appId !== filter.appId)
+        return false;
+    if (filter.actorGaii && d.actorGaii !== filter.actorGaii)
+        return false;
+    if (filter.counterpartyGhii && d.counterpartyGhii !== filter.counterpartyGhii)
+        return false;
+    return true;
+}
+/**
+ * Read a cut INCLUDING what the fold has not caught up on yet.
+ *
+ * The stored rows answer the history; the pending deltas answer the last few minutes. Merging them
+ * here rather than making every caller do it is what lets both the owner reports and the two
+ * operator aggregates be live and bounded at the same time — the alternative was either a stale
+ * dashboard or the full-table scan this whole layer replaced.
+ *
+ * Exported because the operator aggregates (ledger-admin, ai-usage-admin) compose their own shapes
+ * from the same cuts and must not accidentally read only the folded half.
+ */
+export async function queryUsageRollupLive(storage, filter, stream) {
+    const grain = filter.grain ?? 'day';
+    const [stored, pending] = await Promise.all([
+        storage.queryUsageRollup({ ...filter, grain }),
+        pendingRollupDeltas(storage, stream, stream === 'call' ? pendingUsageCalls({}) : []),
+    ]);
+    const extra = pending.filter(d => deltaMatches(d, filter, grain)).map(deltaAsRow);
+    return extra.length ? [...stored, ...extra] : stored;
+}
+/** Fold one stored row into a group accumulator. */
+function addRow(target, r, durationCalls) {
+    target.calls += r.calls;
+    target.errors += r.errors;
+    target.refusals += r.refusals;
+    target.tokens_in += r.tokensIn;
+    target.tokens_out += r.tokensOut;
+    target.total_tokens += r.tokensIn + r.tokensOut;
+    target.cost_usd += r.costUsd;
+    target.unpriced_calls += r.unpricedCalls;
+    target.charged_units += r.chargedUnits;
+    target.actors_seen_approx += r.actorsSeen;
+    if (r.durationMsMax > target.duration_ms_max)
+        target.duration_ms_max = r.durationMsMax;
+    durationCalls.n += r.calls;
+    durationCalls.sum += r.durationMsSum;
+}
+/**
+ * Read one report. The window defaults to the trailing 30 days; a `grain` the cut does not
+ * materialise falls back to the one it does, rather than answering with an empty chart the caller
+ * has no way to explain.
+ */
+export async function readUsageReport(storage, args) {
+    const table = args.scope === 'owner' ? OWNER_REPORTS : NODE_REPORTS;
+    const cutName = table[args.report];
+    if (!cutName)
+        throw new UnknownReportError(args.report, Object.keys(table));
+    const cut = findCut(cutName);
+    if (!cut)
+        throw new UnknownReportError(args.report, Object.keys(table));
+    const grain = args.grain && cut.grains.includes(args.grain)
+        ? args.grain
+        : (cut.grains.includes('day') ? 'day' : cut.grains[0]);
+    const from = args.from ?? dayNDaysAgo(30);
+    const to = args.to ?? dayNDaysAgo(0);
+    const rows = await queryUsageRollupLive(storage, {
+        cut: cutName,
+        grain,
+        from,
+        to: grain === 'hour' ? `${to}T23` : to,
+        // The whole reason owner scoping is safe here: an owner report is a cut that CARRIES ownerGhii,
+        // and the value comes from the route's resolved identity, never from a query parameter.
+        ownerGhii: args.scope === 'owner' ? args.ownerGhii : undefined,
+        limit: 50_000,
+    }, cut.stream);
+    // ── Group by the cut's dimension tuple ──
+    const groups = new Map();
+    const totals = emptyTotals();
+    const totalDuration = { n: 0, sum: 0 };
+    const series = new Map();
+    // The dimensions a row is actually GROUPED by, after two removals.
+    //
+    //   ownerGhii, when the scope already pinned it. An owner-scoped read of `llm.owner` pins the only
+    //   dimension that cut has, so what is left to distinguish one row from another is time — which is
+    //   why "spend per day" groups by bucket instead of showing one row labelled with the reader's own
+    //   identity.
+    //
+    //   outcome, always. It QUALIFIES a call, it does not identify one, and `refusals` and `errors`
+    //   are already metrics on every row. Grouping by it too split one surface into an ok row and an
+    //   error row that both read "mcp", which is a table that answers no question anyone asked.
+    //
+    // Derived rather than declared per report, so a new cut gets the right shape with nothing for its
+    // author to remember.
+    const groupDims = cut.dims.filter(d => d !== 'outcome' && !(d === 'ownerGhii' && args.scope === 'owner'));
+    const isTimeSeries = groupDims.length === 0;
+    for (const r of rows) {
+        const dims = {};
+        for (const d of groupDims) {
+            const value = r[d];
+            if (value)
+                dims[d] = value;
+        }
+        const key = isTimeSeries
+            // Nothing but time distinguishes these rows, so the bucket IS the row's identity.
+            ? r.bucket
+            : (LABEL_ORDER.map(d => dims[d]).find(v => !!v) ?? '(unattributed)');
+        const groupKey = isTimeSeries ? r.bucket : groupDims.map(d => r[d]).join(DIM_SEPARATOR);
+        let entry = groups.get(groupKey);
+        if (!entry) {
+            entry = { g: { key, dims, ...emptyTotals() }, d: { n: 0, sum: 0 } };
+            groups.set(groupKey, entry);
+        }
+        addRow(entry.g, r, entry.d);
+        addRow(totals, r, totalDuration);
+        if (args.series) {
+            const s = series.get(r.bucket) ?? { bucket: r.bucket, calls: 0, cost_usd: 0, total_tokens: 0 };
+            s.calls += r.calls;
+            s.cost_usd += r.costUsd;
+            s.total_tokens += r.tokensIn + r.tokensOut;
+            series.set(r.bucket, s);
+        }
+    }
+    for (const { g, d } of groups.values()) {
+        g.duration_ms_avg = d.n > 0 ? Math.round(d.sum / d.n) : 0;
+    }
+    totals.duration_ms_avg = totalDuration.n > 0 ? Math.round(totalDuration.sum / totalDuration.n) : 0;
+    const limit = Math.min(Math.max(args.limit ?? 200, 1), 2000);
+    const ordered = [...groups.values()].map(e => e.g).sort((a, b) => {
+        // A time series reads chronologically; everything else reads worst-or-biggest first, which is
+        // what someone opening a usage report is actually looking for.
+        if (isTimeSeries)
+            return a.key.localeCompare(b.key);
+        if (b.cost_usd !== a.cost_usd)
+            return b.cost_usd - a.cost_usd;
+        return b.calls - a.calls;
+    }).slice(0, limit);
+    const hotWindowStart = dayNDaysAgo(Number(process.env.AIMEAT_USAGE_HOT_DAYS) || 90);
+    return {
+        report: args.report,
+        cut: cutName,
+        grain,
+        from,
+        to,
+        scope: args.scope,
+        owner: args.scope === 'owner' ? (args.ownerGhii ?? null) : null,
+        series: [...series.values()].sort((a, b) => a.bucket.localeCompare(b.bucket)),
+        groups: ordered,
+        totals,
+        computed_through: await usageComputedThrough(storage),
+        // The rollups themselves go back further than raw does. Saying so is what stops someone
+        // drilling into an old month and reading an empty raw list as "nothing happened".
+        beyond_hot_window: from < hotWindowStart,
+    };
+}
+//# sourceMappingURL=usage-read.js.map

package/dist/src/services/usage/usage-read.js.map

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

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

@@ -42,6 +42,10 @@ export interface UsageEventInput {
     /** The AI provenance record this call produced (TARGET-058), so a spend can be joined to what it
      *  made. Optional — every existing caller keeps working without it. */
     provenanceId?: string;
+    /** Which app spent this, as `owner/filename`. Empty for an agent's own call. */
+    appId?: string;
+    /** Which door the spend came through: 'app', 'mcp', 'schedule', ''. Matches UsageCall.surface. */
+    surface?: string;
     /** Override the record timestamp (defaults to now). */
     ts?: string;
 }
@@ -71,6 +75,7 @@ export declare function extractUsageFields(data: Record<string, unknown>): {
     capabilityId?: string;
     consumerGhii?: string;
     provenanceId?: string;
+    appId?: string;
 } | null;
 /**
  * Turn one telemetry event into a priced usage event, when it carries what pricing needs.

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

@@ -1 +1 @@
-{"version":3,"file":"usage-metering.d.ts","sourceRoot":"","sources":["../../../src/services/usage-metering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAMxE,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;2EACuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAMD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyEzG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAiCP;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,OAAO,CAAC,IAAI,CAAC,CAiBf"}
+{"version":3,"file":"usage-metering.d.ts","sourceRoot":"","sources":["../../../src/services/usage-metering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAMxE,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;2EACuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAMD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA2EzG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAsCP;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/src/services/usage-metering.js

@@ -61,6 +61,8 @@ export async function recordUsageEvent(storage, input) {
         capabilityId: input.capabilityId,
         consumerGhii: input.consumerGhii,
         provenanceId: input.provenanceId,
+        appId: input.appId ?? '',
+        surface: input.surface ?? '',
     };
     // 1. Source of truth — must persist (billing audit, TARGET-019). Let failures propagate.
     await storage.appendUsageEvent(event);
@@ -133,6 +135,11 @@ export function extractUsageFields(data) {
         // This is a CLAIM by the agent, stored on the agent's own row — it grants nothing: resolving
         // that id still goes through the authorized /v1/provenance/:id, which checks ownership itself.
         provenanceId: str(data.provenance_id),
+        // Which app this call was made FOR. Same class of field as organism_id and capability_id above:
+        // a CLAIM by the reporting agent, stored on its own row, granting nothing. It is what makes an
+        // agent's work on behalf of an app show up in the per-app view instead of vanishing into
+        // "unattributed" — the app is what the spend was for, whichever door reported it.
+        appId: str(data.app_id),
     };
 }
 /**

package/dist/src/services/usage-metering.js.map

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

package/dist/src/services/workflow/engine-human.d.ts

@@ -6,6 +6,13 @@
  *   Extracted from engine.ts to satisfy max-file-lines.
  * @usage import { validateHumanAnswer, applyHumanAnswer } from './engine-human.js';
  * @version-history
+ *   v1.2.0 — 2026-08-15 — The upgrade requires a PERSON, which the paragraph guarding it always
+ *     said and the code never asked. An agent could call aimeat_workflow_answer on the step holding
+ *     its own draft and the node stamped that content 'editorial-control' with the note "reviewed
+ *     by <the agent>", turning the public disclosure label from "no human editorial review" into
+ *     the reviewed wording with nobody having read the bytes. `byIsHuman` is set by the door that
+ *     knows the principal class and absent everywhere else, so agents keep answering and stop
+ *     upgrading. E2E test-quality audit finding A18.
  *   v1.1.0 — 2026-08-01 — TARGET-058 Phase 4: a human-input step that names `reviews_key` re-stamps
  *     the reviewed content with humanInvolvement 'editorial-control'. This is the ONLY place in
  *     the engine that may upgrade that field, and a watchdog timeout default never does — nobody
@@ -20,6 +27,14 @@ export interface HumanAnswerValue {
     pick: string;
     other?: string;
     by: string;
+    /**
+     * Was the answerer a PERSON? Absent means no, deliberately: the upgrade below is the one thing in
+     * the engine that can turn "no human editorial review" into "reviewed by a person", so a caller
+     * has to say so on purpose. `by` alone cannot answer it — an agent's GAII and a human's GHII are
+     * both just strings here, and inferring humanness from their shape would break the moment a new
+     * principal class arrives.
+     */
+    byIsHuman?: boolean;
 }
 /**
  * Validate an incoming answer against the question PINNED at ask time (not the current def — a