@cat-factory/contracts 0.277.0 → 0.278.0

package/dist/index.js.map

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

package/dist/public-spend.d.ts

@@ -0,0 +1,204 @@
+import * as v from 'valibot';
+/**
+ * The time window a breakdown aggregates over, measured back from `generatedAt` and snapped
+ * DOWN to a bucket edge (see {@link publicSpendSchema}'s `since`).
+ *
+ * Same members as the internal `reportWindowSchema` in `reports.ts`, and `public-spend.test.ts`
+ * asserts the two stay in step, but this is the FROZEN copy: adding a
+ * window internally does not publish it, and removing one internally has to arrive here as a
+ * deliberate `/api/v1` decision rather than as a member that quietly stopped being accepted.
+ */
+export declare const publicSpendWindowSchema: v.PicklistSchema<["24h", "7d", "30d", "90d"], undefined>;
+export type PublicSpendWindow = v.InferOutput<typeof publicSpendWindowSchema>;
+/**
+ * Which store answered a breakdown. Frozen here for the same reason the window is: this is a
+ * value an external consumer branches on, so the internal spelling of it is not free to move.
+ */
+export declare const publicSpendSourceSchema: v.PicklistSchema<["ledger", "daily-rollup"], undefined>;
+export type PublicSpendSource = v.InferOutput<typeof publicSpendSourceSchema>;
+/**
+ * Hard ceiling on the slices one response may carry.
+ *
+ * A real bound rather than a suggestion: two of the published dimensions grow with ACTIVITY
+ * rather than with a catalog (`run` is one row per pipeline execution, `ticket` one per issue
+ * a run touched), so an unbounded `90d` breakdown on a busy board is a response nobody sized.
+ * The rows are heaviest first, so the cap is a prefix by cost: the slice a cost question is
+ * about, with {@link publicSpendSchema}'s `truncated` saying when there was a tail.
+ */
+export declare const PUBLIC_SPEND_MAX_ROWS = 500;
+/**
+ * What a public spend breakdown groups by.
+ *
+ * The two axes this surface exists for are `repo` and `ticket`: what an organisation budgets
+ * against, and the pair no other public read can produce. `run` is the finest of the three
+ * (one pipeline execution, end to end), and the rest are the same slices the usage read
+ * already implies, offered here because they come from one grouped query rather than four.
+ */
+export declare const publicSpendDimensionSchema: v.PicklistSchema<["model", "agentKind", "service", "repo", "taskType", "ticket", "run"], undefined>;
+export type PublicSpendDimension = v.InferOutput<typeof publicSpendDimensionSchema>;
+/**
+ * The spend dimensions this surface deliberately does NOT offer, each with the reason.
+ *
+ * Stated rather than left as an absence, and paired with a test asserting every internal
+ * `reportSpendDimensionSchema` member is EXACTLY ONCE across the two lists: a dimension
+ * added internally then has to be either published or explained, instead of silently missing
+ * from the surface that four SDKs are generated against.
+ */
+export declare const PUBLIC_SPEND_DIMENSIONS_OMITTED: Record<string, string>;
+/**
+ * One slice of a spend breakdown.
+ *
+ * `key` is the raw dimension value and the row's identity; the EMPTY string is a real bucket
+ * meaning UNATTRIBUTED (a call whose run, service, repository or ticket could not be resolved),
+ * never a dropped row. Dropping it would under-report the window while the breakdown still
+ * looked complete, which is the one thing `totals` and `truncated` exist to prevent.
+ *
+ * The two costs are separate on purpose and must never be summed: only `meteredCost` is money.
+ * `subscriptionCost` is what the same tokens WOULD have cost on the metered API, which is what
+ * a flat-rate harness plan (Claude Code, Codex, …) spends nothing per token on, and it is why
+ * the spend budget excludes it.
+ */
+export declare const publicSpendRowSchema: v.ObjectSchema<{
+    readonly key: v.StringSchema<undefined>;
+    /**
+     * A display name for `key` where the store can resolve one (a service's frame title, a
+     * repository's `owner/name`, the title of the block a run targets); null where the key is
+     * self-describing (a model id, an agent kind, a task type) or where nothing could be joined
+     * (a repository this board holds no projection row for keeps its money and loses its name).
+     */
+    readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly inputTokens: v.NumberSchema<undefined>;
+    readonly outputTokens: v.NumberSchema<undefined>;
+    /** Recorded LLM calls in this slice, both billing kinds. */
+    readonly calls: v.NumberSchema<undefined>;
+    /** Real per-token cost, in the response's `currency`. */
+    readonly meteredCost: v.NumberSchema<undefined>;
+    /** Illustrative equivalent-API cost of flat-rate subscription usage. Never real spend. */
+    readonly subscriptionCost: v.NumberSchema<undefined>;
+}, undefined>;
+export type PublicSpendRow = v.InferOutput<typeof publicSpendRowSchema>;
+/**
+ * Window-wide totals, over EVERY slice the window holds rather than only the ones `rows`
+ * carries. So a `truncated` breakdown still reports what the board actually spent, the same
+ * rule the run LLM export states about its own rollups, and a caller reading the top twenty
+ * repositories can still say what share of the bill they are. On an untruncated response the
+ * rows sum to exactly this.
+ */
+export declare const publicSpendTotalsSchema: v.ObjectSchema<{
+    readonly inputTokens: v.NumberSchema<undefined>;
+    readonly outputTokens: v.NumberSchema<undefined>;
+    readonly calls: v.NumberSchema<undefined>;
+    readonly meteredCost: v.NumberSchema<undefined>;
+    readonly subscriptionCost: v.NumberSchema<undefined>;
+}, undefined>;
+export type PublicSpendTotals = v.InferOutput<typeof publicSpendTotalsSchema>;
+/** Query of `GET /api/v1/usage/spend`. */
+export declare const publicSpendQuerySchema: v.ObjectSchema<{
+    readonly dimension: v.PicklistSchema<["model", "agentKind", "service", "repo", "taskType", "ticket", "run"], undefined>;
+    /** Defaults to `7d`, the widest window served live off the ledger. */
+    readonly window: v.OptionalSchema<v.PicklistSchema<["24h", "7d", "30d", "90d"], undefined>, undefined>;
+    /**
+     * How many SLICES to return, 1..{@link PUBLIC_SPEND_MAX_ROWS} (default 100), heaviest first.
+     * `totals` is unaffected: it aggregates the whole window whatever this says, so a capped
+     * response still reports what the board spent.
+     *
+     * Digit-checked before the numeric coercion, like every other query number on this API:
+     * bare `Number()` also accepts `1e9`, `0x64` and `' '`, which read as plausible values
+     * rather than as the 400 a malformed request has earned.
+     */
+    readonly limit: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Must be a whole number">, v.TransformAction<any, number>, v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 500, undefined>]>, undefined>;
+}, undefined>;
+export type PublicSpendQuery = v.InferOutput<typeof publicSpendQuerySchema>;
+/**
+ * The workspace's spend over a window, sliced one way.
+ *
+ * ONE dimension per request rather than every dimension at once (the shape the internal
+ * Reports panel reads): a panel renders all of them together, where a caller asks a question
+ * and each dimension is its own grouped query. Serving seven would make the common request
+ * seven times the work and the response mostly rows nobody asked for.
+ */
+export declare const publicSpendSchema: v.ObjectSchema<{
+    /** Echoes the requested dimension, so a stored response says what it grouped by. */
+    readonly dimension: v.PicklistSchema<["model", "agentKind", "service", "repo", "taskType", "ticket", "run"], undefined>;
+    readonly window: v.PicklistSchema<["24h", "7d", "30d", "90d"], undefined>;
+    /** When the breakdown was computed (epoch ms). */
+    readonly generatedAt: v.NumberSchema<undefined>;
+    /**
+     * Start of the window (epoch ms): `generatedAt - window`, snapped DOWN to a bucket edge, and
+     * the real span every number here was computed over. A window therefore covers up to one
+     * bucket more than its nominal length, which is why this is reported rather than left to be
+     * re-derived from `window`.
+     */
+    readonly since: v.NumberSchema<undefined>;
+    /** ISO 4217 currency both costs are denominated in (the deployment's base currency). */
+    readonly currency: v.StringSchema<undefined>;
+    /**
+     * Which store answered: a live scan of the metered ledger (`ledger`, the `24h`/`7d` windows)
+     * or the durable daily cost-attribution rollup (`daily-rollup`, `30d`/`90d`).
+     *
+     * They differ in more than freshness. The ledger resolves a repository or a ticket through
+     * the LIVE links, so it re-attributes history whenever a service is re-pointed or an issue
+     * re-imported, and it forgets whatever retention has pruned. The rollup froze that
+     * attribution while the money was being spent and is never pruned, at the cost of being only
+     * as current as the last sweep. A reader comparing two windows has to know which is talking.
+     */
+    readonly source: v.PicklistSchema<["ledger", "daily-rollup"], undefined>;
+    /**
+     * On a `daily-rollup` window: the newest UTC day (epoch ms, midnight) the rollup sweep has
+     * covered, or null when no pass has ever completed. Always null on a `ledger` window, where
+     * there is no rollup in the path to be behind.
+     *
+     * Null is why the field exists: a rollup that has never run and a board that spent nothing
+     * produce the same empty breakdown, and they call for opposite reactions. Read it before
+     * reporting a quiet quarter.
+     */
+    readonly rolledUpThrough: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly totals: v.ObjectSchema<{
+        readonly inputTokens: v.NumberSchema<undefined>;
+        readonly outputTokens: v.NumberSchema<undefined>;
+        readonly calls: v.NumberSchema<undefined>;
+        readonly meteredCost: v.NumberSchema<undefined>;
+        readonly subscriptionCost: v.NumberSchema<undefined>;
+    }, undefined>;
+    /**
+     * True when the window holds more slices than `limit`, so `rows` is the heaviest prefix of
+     * them rather than all of them. STATED rather than left to be inferred from
+     * `rows.length === limit`, which cannot tell a board with exactly `limit` slices from one
+     * with a tail, and which is the reading that turns a capped list into a complete one.
+     *
+     * `totals` above is unaffected, so the share the returned rows account for is computable:
+     * what a truncated breakdown loses is the identity of the long tail, never its money.
+     */
+    readonly truncated: v.BooleanSchema<undefined>;
+    /**
+     * The slices, heaviest by metered cost first, capped at `limit`.
+     *
+     * Capped rather than served whole because two of the published dimensions grow with
+     * ACTIVITY rather than with a catalog: `run` is one row per pipeline execution and `ticket`
+     * one per issue a run touched, so a busy board over `90d` is thousands of rows on a
+     * response nobody sized. (`model`, `agentKind`, `service`, `repo` and `taskType` all key on
+     * a catalog and stay small on their own.) The order is what makes the cap honest: a cost
+     * question is about the heavy end, `truncated` says when there was a tail, and `totals`
+     * still covers all of it.
+     */
+    readonly rows: v.ArraySchema<v.ObjectSchema<{
+        readonly key: v.StringSchema<undefined>;
+        /**
+         * A display name for `key` where the store can resolve one (a service's frame title, a
+         * repository's `owner/name`, the title of the block a run targets); null where the key is
+         * self-describing (a model id, an agent kind, a task type) or where nothing could be joined
+         * (a repository this board holds no projection row for keeps its money and loses its name).
+         */
+        readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly inputTokens: v.NumberSchema<undefined>;
+        readonly outputTokens: v.NumberSchema<undefined>;
+        /** Recorded LLM calls in this slice, both billing kinds. */
+        readonly calls: v.NumberSchema<undefined>;
+        /** Real per-token cost, in the response's `currency`. */
+        readonly meteredCost: v.NumberSchema<undefined>;
+        /** Illustrative equivalent-API cost of flat-rate subscription usage. Never real spend. */
+        readonly subscriptionCost: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicSpend = v.InferOutput<typeof publicSpendSchema>;
+//# sourceMappingURL=public-spend.d.ts.map

package/dist/public-spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-spend.d.ts","sourceRoot":"","sources":["../src/public-spend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAwB5B;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,0DAA0C,CAAA;AAC9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yDAAyC,CAAA;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,qGAQrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKlE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB;;IAE/B;;;;;OAKG;;;;IAIH,4DAA4D;;IAE5D,yDAAyD;;IAEzD,0FAA0F;;aAE1F,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;aAMlC,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB;;IAEjC,sEAAsE;;IAEtE;;;;;;;;OAQG;;aAYH,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;IAC5B,oFAAoF;;;IAGpF,kDAAkD;;IAElD;;;;;OAKG;;IAEH,wFAAwF;;IAExF;;;;;;;;;OASG;;IAEH;;;;;;;;OAQG;;;;;;;;;IAGH;;;;;;;;OAQG;;IAEH;;;;;;;;;;OAUG;;;QA/HH;;;;;WAKG;;;;QAIH,4DAA4D;;QAE5D,yDAAyD;;QAEzD,0FAA0F;;;aAoH1F,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA"}

package/dist/public-spend.js

@@ -0,0 +1,207 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Public spend analytics (`GET /api/v1/usage/spend`): the workspace's money sliced by the
+// dimension a budget is actually kept against.
+//
+// `GET /api/v1/usage` answers "how much has this board spent THIS PERIOD, and is it paused",
+// grouped by `(billing, vendor, provider, model)`. That is the budget question. It cannot
+// answer the TCO one (what did this repository cost us last quarter, what did that ticket
+// cost, what did one pipeline run cost), because it carries no board-shape axis and no window
+// but the current calendar month. Inside the product those answers already exist (the Reports
+// panel reads them account-wide behind the admin gate, served for the long windows from the
+// durable `spend_days` rollup); outside it there was nothing, so an external cost dashboard
+// had to re-derive attribution it could not see.
+//
+// The shapes here are deliberately their OWN projection rather than the internal report rows,
+// exactly as `publicUsageRow` is a projection of `UsageBreakdownRow`: everything on this page
+// is frozen by the public-API stability contract, and an internal analytics shape must stay
+// free to change. That covers the VOCABULARIES too, which are declared below rather than
+// aliased off `reports.ts`: an alias makes an internal rename a silent `/api/v1` break, where a
+// declaration turns the same edit into a failing assertion in `public-spend.test.ts` naming
+// this file as the thing that has to decide.
+// ---------------------------------------------------------------------------
+/**
+ * The time window a breakdown aggregates over, measured back from `generatedAt` and snapped
+ * DOWN to a bucket edge (see {@link publicSpendSchema}'s `since`).
+ *
+ * Same members as the internal `reportWindowSchema` in `reports.ts`, and `public-spend.test.ts`
+ * asserts the two stay in step, but this is the FROZEN copy: adding a
+ * window internally does not publish it, and removing one internally has to arrive here as a
+ * deliberate `/api/v1` decision rather than as a member that quietly stopped being accepted.
+ */
+export const publicSpendWindowSchema = v.picklist(['24h', '7d', '30d', '90d']);
+/**
+ * Which store answered a breakdown. Frozen here for the same reason the window is: this is a
+ * value an external consumer branches on, so the internal spelling of it is not free to move.
+ */
+export const publicSpendSourceSchema = v.picklist(['ledger', 'daily-rollup']);
+/**
+ * Hard ceiling on the slices one response may carry.
+ *
+ * A real bound rather than a suggestion: two of the published dimensions grow with ACTIVITY
+ * rather than with a catalog (`run` is one row per pipeline execution, `ticket` one per issue
+ * a run touched), so an unbounded `90d` breakdown on a busy board is a response nobody sized.
+ * The rows are heaviest first, so the cap is a prefix by cost: the slice a cost question is
+ * about, with {@link publicSpendSchema}'s `truncated` saying when there was a tail.
+ */
+export const PUBLIC_SPEND_MAX_ROWS = 500;
+/**
+ * What a public spend breakdown groups by.
+ *
+ * The two axes this surface exists for are `repo` and `ticket`: what an organisation budgets
+ * against, and the pair no other public read can produce. `run` is the finest of the three
+ * (one pipeline execution, end to end), and the rest are the same slices the usage read
+ * already implies, offered here because they come from one grouped query rather than four.
+ */
+export const publicSpendDimensionSchema = v.picklist([
+    'model',
+    'agentKind',
+    'service',
+    'repo',
+    'taskType',
+    'ticket',
+    'run',
+]);
+/**
+ * The spend dimensions this surface deliberately does NOT offer, each with the reason.
+ *
+ * Stated rather than left as an absence, and paired with a test asserting every internal
+ * `reportSpendDimensionSchema` member is EXACTLY ONCE across the two lists: a dimension
+ * added internally then has to be either published or explained, instead of silently missing
+ * from the surface that four SDKs are generated against.
+ */
+export const PUBLIC_SPEND_DIMENSIONS_OMITTED = {
+    workspace: 'Every key is bound to one workspace, so this axis would return a single row naming the ' +
+        'board the caller already addressed. The account-wide view it exists for is admin-gated ' +
+        'and cross-workspace, which is exactly what a workspace-scoped key must never reach.',
+};
+/**
+ * One slice of a spend breakdown.
+ *
+ * `key` is the raw dimension value and the row's identity; the EMPTY string is a real bucket
+ * meaning UNATTRIBUTED (a call whose run, service, repository or ticket could not be resolved),
+ * never a dropped row. Dropping it would under-report the window while the breakdown still
+ * looked complete, which is the one thing `totals` and `truncated` exist to prevent.
+ *
+ * The two costs are separate on purpose and must never be summed: only `meteredCost` is money.
+ * `subscriptionCost` is what the same tokens WOULD have cost on the metered API, which is what
+ * a flat-rate harness plan (Claude Code, Codex, …) spends nothing per token on, and it is why
+ * the spend budget excludes it.
+ */
+export const publicSpendRowSchema = v.object({
+    key: v.string(),
+    /**
+     * A display name for `key` where the store can resolve one (a service's frame title, a
+     * repository's `owner/name`, the title of the block a run targets); null where the key is
+     * self-describing (a model id, an agent kind, a task type) or where nothing could be joined
+     * (a repository this board holds no projection row for keeps its money and loses its name).
+     */
+    label: v.nullable(v.string()),
+    inputTokens: v.number(),
+    outputTokens: v.number(),
+    /** Recorded LLM calls in this slice, both billing kinds. */
+    calls: v.number(),
+    /** Real per-token cost, in the response's `currency`. */
+    meteredCost: v.number(),
+    /** Illustrative equivalent-API cost of flat-rate subscription usage. Never real spend. */
+    subscriptionCost: v.number(),
+});
+/**
+ * Window-wide totals, over EVERY slice the window holds rather than only the ones `rows`
+ * carries. So a `truncated` breakdown still reports what the board actually spent, the same
+ * rule the run LLM export states about its own rollups, and a caller reading the top twenty
+ * repositories can still say what share of the bill they are. On an untruncated response the
+ * rows sum to exactly this.
+ */
+export const publicSpendTotalsSchema = v.object({
+    inputTokens: v.number(),
+    outputTokens: v.number(),
+    calls: v.number(),
+    meteredCost: v.number(),
+    subscriptionCost: v.number(),
+});
+/** Query of `GET /api/v1/usage/spend`. */
+export const publicSpendQuerySchema = v.object({
+    dimension: publicSpendDimensionSchema,
+    /** Defaults to `7d`, the widest window served live off the ledger. */
+    window: v.optional(publicSpendWindowSchema),
+    /**
+     * How many SLICES to return, 1..{@link PUBLIC_SPEND_MAX_ROWS} (default 100), heaviest first.
+     * `totals` is unaffected: it aggregates the whole window whatever this says, so a capped
+     * response still reports what the board spent.
+     *
+     * Digit-checked before the numeric coercion, like every other query number on this API:
+     * bare `Number()` also accepts `1e9`, `0x64` and `' '`, which read as plausible values
+     * rather than as the 400 a malformed request has earned.
+     */
+    limit: v.optional(v.pipe(v.string(), v.regex(/^\d+$/, 'Must be a whole number'), v.transform(Number), v.number(), v.integer(), v.minValue(1), v.maxValue(PUBLIC_SPEND_MAX_ROWS))),
+});
+/**
+ * The workspace's spend over a window, sliced one way.
+ *
+ * ONE dimension per request rather than every dimension at once (the shape the internal
+ * Reports panel reads): a panel renders all of them together, where a caller asks a question
+ * and each dimension is its own grouped query. Serving seven would make the common request
+ * seven times the work and the response mostly rows nobody asked for.
+ */
+export const publicSpendSchema = v.object({
+    /** Echoes the requested dimension, so a stored response says what it grouped by. */
+    dimension: publicSpendDimensionSchema,
+    window: publicSpendWindowSchema,
+    /** When the breakdown was computed (epoch ms). */
+    generatedAt: v.number(),
+    /**
+     * Start of the window (epoch ms): `generatedAt - window`, snapped DOWN to a bucket edge, and
+     * the real span every number here was computed over. A window therefore covers up to one
+     * bucket more than its nominal length, which is why this is reported rather than left to be
+     * re-derived from `window`.
+     */
+    since: v.number(),
+    /** ISO 4217 currency both costs are denominated in (the deployment's base currency). */
+    currency: v.string(),
+    /**
+     * Which store answered: a live scan of the metered ledger (`ledger`, the `24h`/`7d` windows)
+     * or the durable daily cost-attribution rollup (`daily-rollup`, `30d`/`90d`).
+     *
+     * They differ in more than freshness. The ledger resolves a repository or a ticket through
+     * the LIVE links, so it re-attributes history whenever a service is re-pointed or an issue
+     * re-imported, and it forgets whatever retention has pruned. The rollup froze that
+     * attribution while the money was being spent and is never pruned, at the cost of being only
+     * as current as the last sweep. A reader comparing two windows has to know which is talking.
+     */
+    source: publicSpendSourceSchema,
+    /**
+     * On a `daily-rollup` window: the newest UTC day (epoch ms, midnight) the rollup sweep has
+     * covered, or null when no pass has ever completed. Always null on a `ledger` window, where
+     * there is no rollup in the path to be behind.
+     *
+     * Null is why the field exists: a rollup that has never run and a board that spent nothing
+     * produce the same empty breakdown, and they call for opposite reactions. Read it before
+     * reporting a quiet quarter.
+     */
+    rolledUpThrough: v.nullable(v.number()),
+    totals: publicSpendTotalsSchema,
+    /**
+     * True when the window holds more slices than `limit`, so `rows` is the heaviest prefix of
+     * them rather than all of them. STATED rather than left to be inferred from
+     * `rows.length === limit`, which cannot tell a board with exactly `limit` slices from one
+     * with a tail, and which is the reading that turns a capped list into a complete one.
+     *
+     * `totals` above is unaffected, so the share the returned rows account for is computable:
+     * what a truncated breakdown loses is the identity of the long tail, never its money.
+     */
+    truncated: v.boolean(),
+    /**
+     * The slices, heaviest by metered cost first, capped at `limit`.
+     *
+     * Capped rather than served whole because two of the published dimensions grow with
+     * ACTIVITY rather than with a catalog: `run` is one row per pipeline execution and `ticket`
+     * one per issue a run touched, so a busy board over `90d` is thousands of rows on a
+     * response nobody sized. (`model`, `agentKind`, `service`, `repo` and `taskType` all key on
+     * a catalog and stay small on their own.) The order is what makes the cap honest: a cost
+     * question is about the heavy end, `truncated` says when there was a tail, and `totals`
+     * still covers all of it.
+     */
+    rows: v.array(publicSpendRowSchema),
+});
+//# sourceMappingURL=public-spend.js.map

package/dist/public-spend.js.map

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

package/dist/routes/debug-api.d.ts

@@ -551,6 +551,192 @@ export declare const getDebugLlmCallContract: {
 } & {
     readonly minScope: "read";
 };
+/**
+ * The run's model activity as one self-describing bundle: the complete SQL rollups plus a
+ * bounded window of the calls behind them. The external counterpart of the app's own export
+ * button, and the one call a caller with a fixed context budget makes instead of the overview
+ * plus a walk of the call list.
+ */
+export declare const getDebugLlmExportContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        runId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/core").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ runId }: {
+        runId: string;
+    }) => string;
+    readonly requestQuerySchema: import("valibot").ObjectSchema<{
+        readonly limit: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "Must be a whole number">, import("valibot").TransformAction<any, number>, import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 1, undefined>, import("valibot").MaxValueAction<number, 100, undefined>]>, undefined>;
+        readonly order: import("valibot").OptionalSchema<import("valibot").PicklistSchema<["oldest", "newest"], undefined>, undefined>;
+        readonly bodyChars: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "Must be a whole number">, import("valibot").TransformAction<any, number>, import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 0, undefined>, import("valibot").MaxValueAction<number, 4000, undefined>]>, undefined>;
+    }, undefined>;
+    readonly responsesByStatusCode: {
+        readonly '4xx': import("valibot").ObjectSchema<{
+            readonly error: import("valibot").ObjectSchema<{
+                readonly code: import("valibot").StringSchema<undefined>;
+                readonly message: import("valibot").StringSchema<undefined>;
+                readonly details: import("valibot").OptionalSchema<import("valibot").UnknownSchema, undefined>;
+                readonly issues: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly path: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly message: import("valibot").StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+            }, undefined>;
+        }, undefined>;
+        readonly '5xx': import("valibot").ObjectSchema<{
+            readonly error: import("valibot").ObjectSchema<{
+                readonly code: import("valibot").StringSchema<undefined>;
+                readonly message: import("valibot").StringSchema<undefined>;
+                readonly details: import("valibot").OptionalSchema<import("valibot").UnknownSchema, undefined>;
+                readonly issues: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly path: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly message: import("valibot").StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+            }, undefined>;
+        }, undefined>;
+        readonly 200: import("valibot").ObjectSchema<{
+            readonly kind: import("valibot").LiteralSchema<"cat-factory.run-llm-export", undefined>;
+            readonly version: import("valibot").LiteralSchema<1, undefined>;
+            readonly runId: import("valibot").StringSchema<undefined>;
+            readonly generatedAt: import("valibot").NumberSchema<undefined>;
+            readonly available: import("valibot").BooleanSchema<undefined>;
+            readonly llm: import("valibot").ObjectSchema<{
+                readonly totals: import("valibot").ObjectSchema<{
+                    readonly calls: import("valibot").NumberSchema<undefined>;
+                    readonly promptTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheReadTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheWriteTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheHitRate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly completionTokens: import("valibot").NumberSchema<undefined>;
+                    readonly upstreamMs: import("valibot").NumberSchema<undefined>;
+                    readonly overheadMs: import("valibot").NumberSchema<undefined>;
+                    readonly transportOverheadRatio: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly errors: import("valibot").NumberSchema<undefined>;
+                    readonly warnings: import("valibot").NumberSchema<undefined>;
+                    readonly truncatedCalls: import("valibot").NumberSchema<undefined>;
+                    readonly costEstimate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                }, undefined>;
+                readonly byAgentKind: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly agentKind: import("valibot").StringSchema<undefined>;
+                    readonly calls: import("valibot").NumberSchema<undefined>;
+                    readonly promptTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheReadTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheWriteTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheHitRate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly completionTokens: import("valibot").NumberSchema<undefined>;
+                    readonly peakCompletionTokens: import("valibot").NumberSchema<undefined>;
+                    readonly maxOutputTokens: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly outputHeadroomRatio: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly truncatedCalls: import("valibot").NumberSchema<undefined>;
+                    readonly upstreamMs: import("valibot").NumberSchema<undefined>;
+                    readonly overheadMs: import("valibot").NumberSchema<undefined>;
+                    readonly transportOverheadRatio: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly errors: import("valibot").NumberSchema<undefined>;
+                    readonly warnings: import("valibot").NumberSchema<undefined>;
+                    readonly costEstimate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                }, undefined>, undefined>;
+                readonly byPhase: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly phase: import("valibot").StringSchema<undefined>;
+                    readonly calls: import("valibot").NumberSchema<undefined>;
+                    readonly promptTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheReadTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheWriteTokens: import("valibot").NumberSchema<undefined>;
+                    readonly cacheHitRate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly completionTokens: import("valibot").NumberSchema<undefined>;
+                    readonly carryCostTokens: import("valibot").NumberSchema<undefined>;
+                    readonly carryCostShare: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                    readonly upstreamMs: import("valibot").NumberSchema<undefined>;
+                    readonly overheadMs: import("valibot").NumberSchema<undefined>;
+                    readonly errors: import("valibot").NumberSchema<undefined>;
+                    readonly warnings: import("valibot").NumberSchema<undefined>;
+                    readonly truncatedCalls: import("valibot").NumberSchema<undefined>;
+                    readonly costEstimate: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                }, undefined>, undefined>;
+                readonly costCurrency: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            }, undefined>;
+            readonly order: import("valibot").PicklistSchema<["oldest", "newest"], undefined>;
+            readonly truncated: import("valibot").BooleanSchema<undefined>;
+            readonly calls: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly callId: import("valibot").StringSchema<undefined>;
+                readonly runId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly agentKind: import("valibot").StringSchema<undefined>;
+                readonly provider: import("valibot").StringSchema<undefined>;
+                readonly model: import("valibot").StringSchema<undefined>;
+                readonly createdAt: import("valibot").NumberSchema<undefined>;
+                readonly outcome: import("valibot").PicklistSchema<["ok", "warning", "error"], undefined>;
+                readonly ok: import("valibot").BooleanSchema<undefined>;
+                readonly httpStatus: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                readonly errorMessage: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly finishReason: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly streaming: import("valibot").BooleanSchema<undefined>;
+                readonly phase: import("valibot").StringSchema<undefined>;
+                readonly turnIndex: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                readonly messageCount: import("valibot").NumberSchema<undefined>;
+                readonly toolCount: import("valibot").NumberSchema<undefined>;
+                readonly requestMaxTokens: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                readonly promptTokens: import("valibot").NumberSchema<undefined>;
+                readonly cacheReadTokens: import("valibot").NumberSchema<undefined>;
+                readonly cacheWriteTokens: import("valibot").NumberSchema<undefined>;
+                readonly completionTokens: import("valibot").NumberSchema<undefined>;
+                readonly totalTokens: import("valibot").NumberSchema<undefined>;
+                readonly upstreamMs: import("valibot").NumberSchema<undefined>;
+                readonly overheadMs: import("valibot").NumberSchema<undefined>;
+                readonly totalMs: import("valibot").NumberSchema<undefined>;
+                readonly elidedLeadingMessages: import("valibot").NumberSchema<undefined>;
+                readonly prompt: import("valibot").ObjectSchema<{
+                    readonly text: import("valibot").StringSchema<undefined>;
+                    readonly chars: import("valibot").NumberSchema<undefined>;
+                    readonly offset: import("valibot").NumberSchema<undefined>;
+                    readonly totalChars: import("valibot").NumberSchema<undefined>;
+                    readonly truncated: import("valibot").BooleanSchema<undefined>;
+                    readonly matchOffset: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, undefined>;
+                }, undefined>;
+                readonly response: import("valibot").ObjectSchema<{
+                    readonly text: import("valibot").StringSchema<undefined>;
+                    readonly chars: import("valibot").NumberSchema<undefined>;
+                    readonly offset: import("valibot").NumberSchema<undefined>;
+                    readonly totalChars: import("valibot").NumberSchema<undefined>;
+                    readonly truncated: import("valibot").BooleanSchema<undefined>;
+                    readonly matchOffset: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, undefined>;
+                }, undefined>;
+                readonly reasoning: import("valibot").ObjectSchema<{
+                    readonly text: import("valibot").StringSchema<undefined>;
+                    readonly chars: import("valibot").NumberSchema<undefined>;
+                    readonly offset: import("valibot").NumberSchema<undefined>;
+                    readonly totalChars: import("valibot").NumberSchema<undefined>;
+                    readonly truncated: import("valibot").BooleanSchema<undefined>;
+                    readonly matchOffset: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, undefined>;
+                }, undefined>;
+                readonly promptMessages: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly index: import("valibot").NumberSchema<undefined>;
+                    readonly role: import("valibot").StringSchema<undefined>;
+                    readonly name: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly toolCallId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly toolCalls: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                        readonly name: import("valibot").StringSchema<undefined>;
+                        readonly args: import("valibot").ObjectSchema<{
+                            readonly text: import("valibot").StringSchema<undefined>;
+                            readonly chars: import("valibot").NumberSchema<undefined>;
+                            readonly offset: import("valibot").NumberSchema<undefined>;
+                            readonly totalChars: import("valibot").NumberSchema<undefined>;
+                            readonly truncated: import("valibot").BooleanSchema<undefined>;
+                            readonly matchOffset: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, undefined>;
+                        }, undefined>;
+                    }, undefined>, undefined>;
+                    readonly content: import("valibot").ObjectSchema<{
+                        readonly text: import("valibot").StringSchema<undefined>;
+                        readonly chars: import("valibot").NumberSchema<undefined>;
+                        readonly offset: import("valibot").NumberSchema<undefined>;
+                        readonly totalChars: import("valibot").NumberSchema<undefined>;
+                        readonly truncated: import("valibot").BooleanSchema<undefined>;
+                        readonly matchOffset: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, undefined>;
+                    }, undefined>;
+                }, undefined>, undefined>, undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "read";
+};
 /** The run's captured agent-context dispatches, sizes only, keyset-paginated. */
 export declare const listDebugAgentContextContract: {
     readonly method: "get";