@harrym1707/sdk 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +98 -0
- package/README.md +48 -2
- package/bin/mesh-demo.mjs +105 -0
- package/bin/mesh-proxy.mjs +39 -0
- package/bin/mesh-quote.mjs +45 -0
- package/bin/mesh-report.mjs +47 -0
- package/index.cjs +6306 -0
- package/index.js +6204 -0
- package/package.json +39 -4
- package/types/blind-features.d.ts +28 -0
- package/types/cache-volatility-guard.d.ts +31 -0
- package/types/core/account-store.d.ts +7 -0
- package/types/core/accounts.d.ts +134 -0
- package/types/core/billing-worker.d.ts +113 -0
- package/types/core/budget.d.ts +216 -0
- package/types/core/cache-simulator.d.ts +271 -0
- package/types/core/confidence.d.ts +36 -0
- package/types/core/cost.d.ts +16 -0
- package/types/core/evaluator.d.ts +16 -0
- package/types/core/gateway.d.ts +75 -0
- package/types/core/geo-visibility.d.ts +25 -0
- package/types/core/github-oauth.d.ts +41 -0
- package/types/core/helicone.d.ts +6 -0
- package/types/core/index.d.ts +36 -0
- package/types/core/langfuse.d.ts +7 -0
- package/types/core/ledger-store.d.ts +62 -0
- package/types/core/litellm.d.ts +15 -0
- package/types/core/local-tier.d.ts +82 -0
- package/types/core/model-prices.d.ts +25 -0
- package/types/core/output-diagnostics.d.ts +39 -0
- package/types/core/price-catalogue.d.ts +168 -0
- package/types/core/provider-usage.d.ts +84 -0
- package/types/core/quote-report.d.ts +54 -0
- package/types/core/replay.d.ts +2 -0
- package/types/core/router.d.ts +9 -0
- package/types/core/routing.d.ts +282 -0
- package/types/core/savings-ledger.d.ts +349 -0
- package/types/core/savings-model.d.ts +132 -0
- package/types/core/stripe-billing.d.ts +67 -0
- package/types/core/stripe-client.d.ts +117 -0
- package/types/core/stripe-sink.d.ts +77 -0
- package/types/core/theo-coverage.d.ts +49 -0
- package/types/core/token-reduction.d.ts +219 -0
- package/types/core/tool-schema.d.ts +64 -0
- package/types/core/traffic.d.ts +182 -0
- package/types/core/triage.d.ts +70 -0
- package/types/core/types.d.ts +149 -0
- package/types/core/workflow-sessions.d.ts +50 -0
- package/types/cta.d.ts +60 -0
- package/types/evaluation-capture.d.ts +11 -0
- package/types/exact-cache.d.ts +20 -0
- package/types/graders.d.ts +53 -0
- package/types/index.d.ts +31 -0
- package/types/ledger-mirror.d.ts +38 -0
- package/types/openai.d.ts +23 -0
- package/types/proxy.d.ts +104 -0
- package/types/reduce-request.d.ts +272 -0
- package/types/replay-gate.d.ts +120 -0
- package/types/report.d.ts +33 -0
- package/types/routing.d.ts +11 -0
- package/types/savings-ledger.d.ts +22 -0
- package/types/savings-snapshot.d.ts +11 -0
- package/types/semantic-compaction.d.ts +84 -0
- package/types/telemetry.d.ts +6 -0
- package/types/theo-agent-store.d.ts +27 -0
- package/types/theo-agent.d.ts +247 -0
- package/types/theo-gate.d.ts +75 -0
- package/types/theo-policy.d.ts +219 -0
- package/types/types.d.ts +287 -0
- package/types/wrap.d.ts +60 -0
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
import type { InferenceEvent, ModelTarget, QualityPolicy, QualityResult, RoutingDecision } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Stage 6 --- the Router.
|
|
4
|
+
*
|
|
5
|
+
* The control plane decides, per task class, whether a request is served by the
|
|
6
|
+
* baseline model or by an approved cheaper candidate, and advances or reverts
|
|
7
|
+
* that candidate along a staged rollout ladder. This module is the engine
|
|
8
|
+
* behind those decisions, built from the six components the spec names:
|
|
9
|
+
*
|
|
10
|
+
* PolicyLoader -- holds the active staged policy per task class.
|
|
11
|
+
* CandidateSelector -- the quality gate: may this candidate take traffic?
|
|
12
|
+
* Router -- the deterministic per-request decision.
|
|
13
|
+
* RolloutManager -- the pure 1% -> 100% ladder state machine.
|
|
14
|
+
* EscalationManager -- promotes a candidate up the ladder on good signal.
|
|
15
|
+
* RollbackManager -- reverts a candidate on a quality regression.
|
|
16
|
+
*
|
|
17
|
+
* Two invariants hold throughout:
|
|
18
|
+
*
|
|
19
|
+
* 1. Determinism. Once a policy is selected, `Router.route(request, policy)`
|
|
20
|
+
* is a pure function of the request and that policy: the same pair always
|
|
21
|
+
* yields the same `RoutingDecision`. No clocks, no `Math.random`. A
|
|
22
|
+
* request's cohort position is a stable hash, so it also never flip-flops
|
|
23
|
+
* as the rollout widens -- a request served by the candidate at 10% is
|
|
24
|
+
* still served by it at 25%.
|
|
25
|
+
*
|
|
26
|
+
* 2. Quality first. A cheaper candidate is activated ONLY when its quality
|
|
27
|
+
* policy (Stage 5) requirements are met on enough samples and a human has
|
|
28
|
+
* approved it; otherwise the request falls back to baseline. Cost is never
|
|
29
|
+
* reduced by silently reducing customer-defined output quality.
|
|
30
|
+
*/
|
|
31
|
+
/** The staged rollout ladder: the fraction of traffic the candidate may take at each rung. */
|
|
32
|
+
export declare const ROLLOUT_LADDER: readonly [0.01, 0.05, 0.1, 0.25, 0.5, 1];
|
|
33
|
+
/** Index of the final (100%) rung. */
|
|
34
|
+
export declare const ROLLOUT_LADDER_TOP: number;
|
|
35
|
+
/** `stageIndex` for a halted rollout: no candidate traffic, baseline only. */
|
|
36
|
+
export declare const ROLLOUT_HALTED_STAGE = -1;
|
|
37
|
+
/**
|
|
38
|
+
* Default floor for evaluation/observation sample sizes when a policy omits its
|
|
39
|
+
* own. A candidate is never qualified, escalated, or rolled back on one or two
|
|
40
|
+
* examples (Technical Architecture §6); 30 is the smallest sample that carries
|
|
41
|
+
* any statistical signal.
|
|
42
|
+
*/
|
|
43
|
+
export declare const DEFAULT_MINIMUM_SAMPLES = 30;
|
|
44
|
+
/**
|
|
45
|
+
* Where a candidate sits on the ladder right now. `stageIndex` is an index into
|
|
46
|
+
* `ROLLOUT_LADDER` while `status` is `"active"`; a `"halted"` rollout sends no
|
|
47
|
+
* candidate traffic regardless of the index.
|
|
48
|
+
*/
|
|
49
|
+
export type RolloutState = {
|
|
50
|
+
stageIndex: number;
|
|
51
|
+
status: "active" | "halted";
|
|
52
|
+
/** Trace of the transition that produced this state. */
|
|
53
|
+
lastReason?: string;
|
|
54
|
+
};
|
|
55
|
+
/** Stage 5 evaluation evidence standing behind a candidate. */
|
|
56
|
+
export type CandidateEvidence = {
|
|
57
|
+
/** Measured quality of the candidate from offline evaluation. */
|
|
58
|
+
quality: QualityResult;
|
|
59
|
+
/** How many evaluation samples the measurement rests on. */
|
|
60
|
+
sampleSize: number;
|
|
61
|
+
};
|
|
62
|
+
/** A cheaper model a policy may route to, with the bar it must clear first. */
|
|
63
|
+
export type RolloutCandidate = {
|
|
64
|
+
target: ModelTarget;
|
|
65
|
+
/** Fraction of baseline cost avoided, 0..1 (0.71 == 71% cheaper). */
|
|
66
|
+
estimatedCostReduction: number;
|
|
67
|
+
/** The quality bar this candidate must clear before any traffic (Stage 5). */
|
|
68
|
+
qualityPolicy: QualityPolicy;
|
|
69
|
+
/** Explicit human sign-off after reviewing the offline evaluation. */
|
|
70
|
+
approved: boolean;
|
|
71
|
+
/** Measured quality evidence from Stage 5. */
|
|
72
|
+
evidence: CandidateEvidence;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* A compiled, runtime policy for one task class: the baseline, the single
|
|
76
|
+
* candidate under rollout, and where that candidate currently sits on the
|
|
77
|
+
* ladder. One candidate per policy keeps the cohort interval unambiguous; a
|
|
78
|
+
* second cheaper model is a new policy version.
|
|
79
|
+
*/
|
|
80
|
+
export type StagedRoutingPolicy = {
|
|
81
|
+
id: string;
|
|
82
|
+
version: number;
|
|
83
|
+
taskClass: string;
|
|
84
|
+
baseline: ModelTarget;
|
|
85
|
+
candidate: RolloutCandidate;
|
|
86
|
+
rollout: RolloutState;
|
|
87
|
+
enabled: boolean;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* The minimum a request must carry for a routing decision. `requestId` is any
|
|
91
|
+
* stable, non-sensitive identity (request id, tenant+user, job id); it is the
|
|
92
|
+
* only thing the cohort hash reads, so the same identity always lands in the
|
|
93
|
+
* same cohort.
|
|
94
|
+
*/
|
|
95
|
+
export type RouterRequest = {
|
|
96
|
+
requestId: string;
|
|
97
|
+
taskClass?: string;
|
|
98
|
+
};
|
|
99
|
+
/** A live production quality signal observed at the current rollout stage. */
|
|
100
|
+
export type RolloutSignal = {
|
|
101
|
+
/** Measured quality of candidate traffic at the current stage. */
|
|
102
|
+
quality: QualityResult;
|
|
103
|
+
/** Observations gathered at the current stage. */
|
|
104
|
+
sampleSize: number;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Map a policy and a request identity to a stable position in [0, 1). Same
|
|
108
|
+
* inputs, same position, forever -- this is what makes routing deterministic
|
|
109
|
+
* and monotonic across rollout stages. The policy version is part of the key so
|
|
110
|
+
* a new policy version reshuffles cohorts (a fresh rollout), while every stage
|
|
111
|
+
* of one version shares one cohort assignment.
|
|
112
|
+
*/
|
|
113
|
+
export declare function cohortPosition(policy: Pick<StagedRoutingPolicy, "id" | "version">, requestId: string): number;
|
|
114
|
+
/**
|
|
115
|
+
* The human-readable `routeReason` (Technical Architecture §5). Carries the task
|
|
116
|
+
* class, the candidate, the quality evidence against its threshold, the
|
|
117
|
+
* estimated cost reduction, and the rollout percentage the decision was made at.
|
|
118
|
+
*/
|
|
119
|
+
export declare function formatRouteReason(policy: StagedRoutingPolicy, quality: QualityResult, rolloutFraction: number): string;
|
|
120
|
+
export type CandidateVerdict = {
|
|
121
|
+
qualified: true;
|
|
122
|
+
quality: QualityResult;
|
|
123
|
+
} | {
|
|
124
|
+
qualified: false;
|
|
125
|
+
reason: string;
|
|
126
|
+
quality: QualityResult;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Decides whether a candidate is allowed to take ANY traffic, independent of
|
|
130
|
+
* the rollout percentage. This is the enforcement point for the core invariant:
|
|
131
|
+
* a candidate qualifies only with human approval, enough samples, and a quality
|
|
132
|
+
* measurement that clears its own quality policy.
|
|
133
|
+
*/
|
|
134
|
+
export declare class CandidateSelector {
|
|
135
|
+
select(candidate: RolloutCandidate): CandidateVerdict;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The Router from the architecture spec: `route(request, policy)` returns a
|
|
139
|
+
* `RoutingDecision` and is a pure function of its inputs. Every path that does
|
|
140
|
+
* not route to the candidate falls back to baseline with a reason naming why.
|
|
141
|
+
*/
|
|
142
|
+
export declare class Router {
|
|
143
|
+
private readonly selector;
|
|
144
|
+
constructor(selector?: CandidateSelector);
|
|
145
|
+
route(request: RouterRequest, policy: StagedRoutingPolicy): RoutingDecision;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* The pure ladder state machine. Every transition returns a NEW state; nothing
|
|
149
|
+
* is mutated in place, so a caller can keep the prior state to revert to.
|
|
150
|
+
*/
|
|
151
|
+
export declare class RolloutManager {
|
|
152
|
+
readonly ladder: readonly [0.01, 0.05, 0.1, 0.25, 0.5, 1];
|
|
153
|
+
/** A fresh rollout: active at the first rung (1%). */
|
|
154
|
+
initial(): RolloutState;
|
|
155
|
+
/** The traffic fraction this state grants the candidate (0 when halted). */
|
|
156
|
+
percentage(state: RolloutState): number;
|
|
157
|
+
/** True once the candidate is active at the final (100%) rung. */
|
|
158
|
+
isComplete(state: RolloutState): boolean;
|
|
159
|
+
/**
|
|
160
|
+
* Promote one rung. A halted rollout cannot advance (resume it first); the top
|
|
161
|
+
* rung is a no-op. Returns the input state unchanged when neither applies.
|
|
162
|
+
*/
|
|
163
|
+
advance(state: RolloutState, reason?: string): RolloutState;
|
|
164
|
+
/**
|
|
165
|
+
* Revert one rung. Stepping down from the first rung halts the rollout (no
|
|
166
|
+
* candidate traffic). This is the graduated rollback path.
|
|
167
|
+
*/
|
|
168
|
+
stepDown(state: RolloutState, reason?: string): RolloutState;
|
|
169
|
+
/** Full stop: no candidate traffic, baseline only, until resumed. */
|
|
170
|
+
halt(_state: RolloutState, reason?: string): RolloutState;
|
|
171
|
+
/** Resume a halted rollout back at the first rung. */
|
|
172
|
+
resume(_state: RolloutState, reason?: string): RolloutState;
|
|
173
|
+
}
|
|
174
|
+
/** How a rollback reverts: a full stop to baseline, or one rung down the ladder. */
|
|
175
|
+
export type RollbackMode = "halt" | "step_down";
|
|
176
|
+
export type RollbackDecision = {
|
|
177
|
+
triggered: boolean;
|
|
178
|
+
rollout: RolloutState;
|
|
179
|
+
reason: string;
|
|
180
|
+
};
|
|
181
|
+
/**
|
|
182
|
+
* The authority on quality regressions during rollout. It decides when a live
|
|
183
|
+
* signal breaches the candidate's quality bar and produces the reverted state.
|
|
184
|
+
*/
|
|
185
|
+
export declare class RollbackManager {
|
|
186
|
+
private readonly mode;
|
|
187
|
+
private readonly rolloutManager;
|
|
188
|
+
private readonly minimumSamples;
|
|
189
|
+
constructor(mode?: RollbackMode, rolloutManager?: RolloutManager, options?: {
|
|
190
|
+
minimumSamples?: number;
|
|
191
|
+
});
|
|
192
|
+
/** True when live candidate quality no longer clears the candidate's policy. */
|
|
193
|
+
shouldRollback(candidate: RolloutCandidate, signal: RolloutSignal): boolean;
|
|
194
|
+
/** Revert the policy's rollout (halt or step down, per the configured mode). */
|
|
195
|
+
rollback(policy: StagedRoutingPolicy, reason?: string): StagedRoutingPolicy;
|
|
196
|
+
/**
|
|
197
|
+
* Inspect a signal and, if it breaches quality on enough samples, produce the
|
|
198
|
+
* reverted state. A breach measured on fewer than `minimumSamples` is held,
|
|
199
|
+
* not acted on, so the ladder does not flap on one or two bad examples.
|
|
200
|
+
*/
|
|
201
|
+
decide(policy: StagedRoutingPolicy, signal: RolloutSignal): RollbackDecision;
|
|
202
|
+
}
|
|
203
|
+
export type EscalationAction = "advance" | "hold" | "rollback";
|
|
204
|
+
export type EscalationDecision = {
|
|
205
|
+
action: EscalationAction;
|
|
206
|
+
rollout: RolloutState;
|
|
207
|
+
reason: string;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* Drives a candidate up the ladder from a live production quality signal. A
|
|
211
|
+
* regression always rolls back first (delegated to the RollbackManager); a
|
|
212
|
+
* healthy signal advances one rung once enough traffic has been observed at the
|
|
213
|
+
* current stage; otherwise it holds. Advancement itself never relaxes the
|
|
214
|
+
* quality gate -- the Router still re-checks quality on every request.
|
|
215
|
+
*/
|
|
216
|
+
export declare class EscalationManager {
|
|
217
|
+
private readonly rolloutManager;
|
|
218
|
+
private readonly rollbackManager;
|
|
219
|
+
private readonly minimumSamplesPerStage;
|
|
220
|
+
constructor(options?: {
|
|
221
|
+
minimumSamplesPerStage?: number;
|
|
222
|
+
}, rolloutManager?: RolloutManager, rollbackManager?: RollbackManager);
|
|
223
|
+
evaluate(policy: StagedRoutingPolicy, signal: RolloutSignal): EscalationDecision;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Holds the active staged policy per task class. In production this is a
|
|
227
|
+
* local/Redis-backed cache the data plane reads on the hot path (Technical
|
|
228
|
+
* Architecture §2); here it is an in-memory registry with the same contract:
|
|
229
|
+
* lookups are cheap and deterministic, disabled policies are not served, and
|
|
230
|
+
* the latest version wins for a task class.
|
|
231
|
+
*
|
|
232
|
+
* Lifecycle updates from the EscalationManager / RollbackManager are persisted
|
|
233
|
+
* with `update`, which bumps nothing but the stored rollout state -- the policy
|
|
234
|
+
* id and version are stable across ladder movements within one version.
|
|
235
|
+
*/
|
|
236
|
+
export declare class PolicyLoader {
|
|
237
|
+
private readonly byId;
|
|
238
|
+
private readonly byTaskClass;
|
|
239
|
+
constructor(policies?: readonly StagedRoutingPolicy[]);
|
|
240
|
+
register(policy: StagedRoutingPolicy): void;
|
|
241
|
+
/** The active policy for a task class, or undefined when none is enabled. */
|
|
242
|
+
load(taskClass: string | undefined): StagedRoutingPolicy | undefined;
|
|
243
|
+
loadById(id: string): StagedRoutingPolicy | undefined;
|
|
244
|
+
/** Persist a lifecycle transition (new rollout state) for an existing policy. */
|
|
245
|
+
update(policy: StagedRoutingPolicy): void;
|
|
246
|
+
all(): StagedRoutingPolicy[];
|
|
247
|
+
}
|
|
248
|
+
/** Sink for the InferenceEvent stream (Technical Architecture §9). */
|
|
249
|
+
export type RoutingTelemetrySink = {
|
|
250
|
+
record(event: InferenceEvent): void | Promise<void>;
|
|
251
|
+
};
|
|
252
|
+
/**
|
|
253
|
+
* Turn a routing decision into the InferenceEvent the telemetry path carries.
|
|
254
|
+
* The decision's `reason` becomes `routeReason`, and the chosen target's
|
|
255
|
+
* provider/model are recorded so downstream pricing and the savings ledger see
|
|
256
|
+
* exactly where the request went.
|
|
257
|
+
*/
|
|
258
|
+
export declare function routingDecisionEvent(request: RouterRequest, decision: RoutingDecision, extra: {
|
|
259
|
+
applicationId: string;
|
|
260
|
+
timestamp: string;
|
|
261
|
+
inputTokens?: number;
|
|
262
|
+
outputTokens?: number;
|
|
263
|
+
costUsd?: number;
|
|
264
|
+
latencyMs?: number;
|
|
265
|
+
}): InferenceEvent;
|
|
266
|
+
/**
|
|
267
|
+
* Convenience wiring for the data plane: load the policy for a request's task
|
|
268
|
+
* class, route deterministically, and record the decision through the telemetry
|
|
269
|
+
* sink. Returns the decision. When no policy is active the request still routes
|
|
270
|
+
* to baseline (via a synthesised decision) and is still recorded, so every
|
|
271
|
+
* served request produces one inference event.
|
|
272
|
+
*/
|
|
273
|
+
export declare class RoutingService {
|
|
274
|
+
private readonly loader;
|
|
275
|
+
private readonly sink;
|
|
276
|
+
private readonly router;
|
|
277
|
+
constructor(loader: PolicyLoader, sink: RoutingTelemetrySink, router?: Router);
|
|
278
|
+
route(request: RouterRequest, baseline: ModelTarget, telemetry: {
|
|
279
|
+
applicationId: string;
|
|
280
|
+
timestamp: string;
|
|
281
|
+
}): Promise<RoutingDecision>;
|
|
282
|
+
}
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
import { type PriceCatalogue } from "./price-catalogue.js";
|
|
2
|
+
/**
|
|
3
|
+
* The savings ledger: the append-only record MESH bills from, and the pure
|
|
4
|
+
* functions that turn it back into an invoice.
|
|
5
|
+
*
|
|
6
|
+
* MESH charges a percentage of VERIFIED savings, so the ledger is designed to
|
|
7
|
+
* be recomputed by the customer, not trusted:
|
|
8
|
+
*
|
|
9
|
+
* - Every event carries the provider-verbatim token usage and the content hash
|
|
10
|
+
* of the price catalogue it was priced against. Anyone holding the same
|
|
11
|
+
* catalogue can re-derive every USD figure with zero tolerance.
|
|
12
|
+
* - Events are hash-chained (seq, prevHash, eventHash), so a perturbed or
|
|
13
|
+
* removed event is detectable, and the exact position is named.
|
|
14
|
+
* - `recomputeInvoice` is deterministic and idempotent by requestId: replaying
|
|
15
|
+
* the same spool twice, late, or shuffled yields a byte-identical invoice.
|
|
16
|
+
* - Only verified components bill: price-mode deltas on actual tokens, MESH's
|
|
17
|
+
* own exact-cache avoidance at the originally measured cost, provider-cache
|
|
18
|
+
* economics on prefixes MESH itself placed, and lossy levers whose replay
|
|
19
|
+
* gate verdict is "approved". Savings the customer already had (provider
|
|
20
|
+
* cache on appended history they placed or got by default, gateway caches)
|
|
21
|
+
* are recorded for transparency and never billed. Token-reduction levers may
|
|
22
|
+
* bill from an estimated baseline anchored to provider-verbatim usage, and
|
|
23
|
+
* every such figure is labelled "estimated-baseline" on the lever and the
|
|
24
|
+
* invoice line item — an estimate is never passed off as a measurement.
|
|
25
|
+
* - Negative components are netted, never clamped: a 1h cache-write surcharge
|
|
26
|
+
* that never earned its reads shows up AGAINST MESH on the invoice, and a
|
|
27
|
+
* net-non-positive period produces the "do_not_charge" verdict.
|
|
28
|
+
*/
|
|
29
|
+
export type LedgerExecutionMode = "standard" | "flex" | "batch";
|
|
30
|
+
export type LedgerLeverKind =
|
|
31
|
+
/** Transform that cannot change the answer (schema compaction, dedupe). */
|
|
32
|
+
"lossless"
|
|
33
|
+
/** Behaviour-changing lever; bills only with an approved replay-gate verdict. */
|
|
34
|
+
| "lossy"
|
|
35
|
+
/** Execution-tier price delta (flex/batch) on actual tokens. */
|
|
36
|
+
| "tier"
|
|
37
|
+
/** MESH's own exact response cache: a request never sent. */
|
|
38
|
+
| "exact_cache"
|
|
39
|
+
/** Provider prompt-cache economics on cache_control MESH itself placed. */
|
|
40
|
+
| "provider_cache";
|
|
41
|
+
/** Reference to the replay-gate run that approved or rejected a lossy lever. */
|
|
42
|
+
export type LedgerGateVerdict = {
|
|
43
|
+
ref: string;
|
|
44
|
+
verdict: "approved" | "rejected";
|
|
45
|
+
};
|
|
46
|
+
export type LedgerLever = {
|
|
47
|
+
leverId: string;
|
|
48
|
+
kind: LedgerLeverKind;
|
|
49
|
+
/**
|
|
50
|
+
* Verified USD this lever saved on THIS request. MAY be negative (netted on
|
|
51
|
+
* the invoice, never clamped). Omitted means the lever was applied but has no
|
|
52
|
+
* per-request verified measurement; it is then recorded and never billed.
|
|
53
|
+
*/
|
|
54
|
+
savedUsd?: number;
|
|
55
|
+
/**
|
|
56
|
+
* How savedUsd was derived. "measured" (the default when absent) means it
|
|
57
|
+
* came entirely from provider-verbatim deltas. "estimated-baseline" means
|
|
58
|
+
* the tokens this lever removed were counted BEFORE send by MESH's own
|
|
59
|
+
* counter, anchored to the provider-verbatim input total by ratio, and
|
|
60
|
+
* valued at this event's realized blended input rate — a conservative
|
|
61
|
+
* under-claim on cache-heavy traffic, labelled as an estimate everywhere
|
|
62
|
+
* it appears, including the invoice line item.
|
|
63
|
+
*/
|
|
64
|
+
basis?: "measured" | "estimated-baseline";
|
|
65
|
+
gateVerdict?: LedgerGateVerdict;
|
|
66
|
+
detail?: string;
|
|
67
|
+
};
|
|
68
|
+
export type LedgerUsage = {
|
|
69
|
+
inputTokens: number;
|
|
70
|
+
outputTokens: number;
|
|
71
|
+
cachedInputTokens: number;
|
|
72
|
+
/** TOTAL cache writes, inclusive of any TTL-split share below. */
|
|
73
|
+
cacheWriteInputTokens: number;
|
|
74
|
+
/**
|
|
75
|
+
* Provider-reported TTL split of the cache writes, present as a PAIR only
|
|
76
|
+
* when the provider reported one (Anthropic usage.cache_creation). The two
|
|
77
|
+
* buckets must sum exactly to cacheWriteInputTokens or the event is unpriced.
|
|
78
|
+
* Absent means the split is UNKNOWN: writes on a MESH-placed cache_control
|
|
79
|
+
* use the TTL stamped by MESH when it is recorded (otherwise the 1h premium,
|
|
80
|
+
* dispute-safe and counted against MESH), never assumed to be 5m writes.
|
|
81
|
+
*/
|
|
82
|
+
cacheWrite5mInputTokens?: number;
|
|
83
|
+
cacheWrite1hInputTokens?: number;
|
|
84
|
+
};
|
|
85
|
+
/** One append-only billable event, written once per completed request. */
|
|
86
|
+
export type BillableEvent = {
|
|
87
|
+
schemaVersion: 1;
|
|
88
|
+
/** End-to-end idempotency key; duplicates are ignored at invoice time. */
|
|
89
|
+
requestId: string;
|
|
90
|
+
applicationId: string;
|
|
91
|
+
/** Correlation to a multi-turn task, so a failed task's turns can be excluded. */
|
|
92
|
+
taskId?: string;
|
|
93
|
+
turnIndex?: number;
|
|
94
|
+
/** YYYY-MM, fixed from `timestamp` at write time so late replays land in the same period. */
|
|
95
|
+
invoicePeriod: string;
|
|
96
|
+
timestamp: string;
|
|
97
|
+
provider: string;
|
|
98
|
+
model: string;
|
|
99
|
+
/** Taken from the provider RESPONSE (service_tier / batch), never the request. */
|
|
100
|
+
executionMode: LedgerExecutionMode;
|
|
101
|
+
pricingStatus: "priced" | "unpriced";
|
|
102
|
+
pricingReason?: string;
|
|
103
|
+
/** Content hash of the catalogue the USD figures were computed against. */
|
|
104
|
+
catalogueVersion?: string;
|
|
105
|
+
/** Provider-verbatim normalised token usage. */
|
|
106
|
+
usage?: LedgerUsage;
|
|
107
|
+
/** Catalogue-priced cost of this request at its actual execution mode. */
|
|
108
|
+
actualUsd?: number;
|
|
109
|
+
/** Measured counterfactual (standard tier, no levers), when a measurement path supplies one. */
|
|
110
|
+
baselineUsd?: number;
|
|
111
|
+
/** The caller's own pricing of the request, informational only. */
|
|
112
|
+
reportedCostUsd?: number;
|
|
113
|
+
levers: LedgerLever[];
|
|
114
|
+
/**
|
|
115
|
+
* Evidence behind any estimated-baseline lever on this event: MESH's own
|
|
116
|
+
* pre-send token counts. Informational — the invoice never reads it; it
|
|
117
|
+
* exists so an auditor can re-derive every estimated savedUsd from the
|
|
118
|
+
* event alone (removedFraction = removed / before, baseline input =
|
|
119
|
+
* usage.inputTokens / (1 - removedFraction), valued at actual input cost
|
|
120
|
+
* divided by actual input tokens).
|
|
121
|
+
*/
|
|
122
|
+
estimatedReduction?: {
|
|
123
|
+
estimatedInputTokensBefore: number;
|
|
124
|
+
estimatedInputTokensRemoved: number;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* Output-side waste metering (never billed, never mutated): how much of
|
|
128
|
+
* this completion was verbatim re-emission of lines already in the request
|
|
129
|
+
* context, and whether this request byte-duplicated an earlier one. Pure
|
|
130
|
+
* diagnostics for the statement's waste view; token counts only.
|
|
131
|
+
*/
|
|
132
|
+
outputDiagnostics?: {
|
|
133
|
+
inspectedOutputTokens: number;
|
|
134
|
+
reEmittedOutputTokens: number;
|
|
135
|
+
reEmittedCodeTokens: number;
|
|
136
|
+
};
|
|
137
|
+
/** This request was byte-identical to an earlier one from the same app. */
|
|
138
|
+
duplicateOfRequestId?: string;
|
|
139
|
+
/** Savings the customer already had. Recorded for transparency, NEVER billed. */
|
|
140
|
+
excluded?: {
|
|
141
|
+
providerCacheAlreadyOwnedUsd?: number;
|
|
142
|
+
gatewayCacheUsd?: number;
|
|
143
|
+
};
|
|
144
|
+
status: "succeeded" | "failed";
|
|
145
|
+
};
|
|
146
|
+
export declare const LEDGER_GENESIS_HASH: string;
|
|
147
|
+
export type LedgerRecord = {
|
|
148
|
+
seq: number;
|
|
149
|
+
prevHash: string;
|
|
150
|
+
eventHash: string;
|
|
151
|
+
event: BillableEvent;
|
|
152
|
+
};
|
|
153
|
+
/** Hash of one chained event; covers its position, its predecessor and its content. */
|
|
154
|
+
export declare function ledgerEventHash(seq: number, prevHash: string, event: BillableEvent): string;
|
|
155
|
+
/** Chain one event onto the previous record (or onto genesis). */
|
|
156
|
+
export declare function chainLedgerRecord(event: BillableEvent, previous?: LedgerRecord): LedgerRecord;
|
|
157
|
+
export type LedgerChainVerification = {
|
|
158
|
+
ok: true;
|
|
159
|
+
length: number;
|
|
160
|
+
} | {
|
|
161
|
+
ok: false;
|
|
162
|
+
seq: number;
|
|
163
|
+
reason: string;
|
|
164
|
+
};
|
|
165
|
+
/**
|
|
166
|
+
* Verify a spool end to end. A perturbed usage field, a reordered record, or a
|
|
167
|
+
* missing record is reported with the exact sequence number where the chain breaks.
|
|
168
|
+
*/
|
|
169
|
+
export declare function verifyLedgerChain(records: readonly LedgerRecord[]): LedgerChainVerification;
|
|
170
|
+
export type LedgerPricingInput = {
|
|
171
|
+
provider: string;
|
|
172
|
+
/** Raw API model identifier, resolved against the catalogue. */
|
|
173
|
+
model: string;
|
|
174
|
+
/** ISO calendar date the request was billed on. */
|
|
175
|
+
at: string;
|
|
176
|
+
executionMode: LedgerExecutionMode;
|
|
177
|
+
usage: LedgerUsage;
|
|
178
|
+
/**
|
|
179
|
+
* True when MESH itself placed the cache_control (the cache-ttl lever applies
|
|
180
|
+
* only when the caller had none), so the request's cache economics -- reads
|
|
181
|
+
* at the cached rate MINUS the write surcharge -- attribute to MESH. False
|
|
182
|
+
* means the customer already owned those economics; they are then excluded.
|
|
183
|
+
*/
|
|
184
|
+
meshPlacedCacheControl: boolean;
|
|
185
|
+
/**
|
|
186
|
+
* The TTL MESH stamped, when meshPlacedCacheControl is true. Decides how an
|
|
187
|
+
* ABSENT provider TTL split prices the writes: a "5m" stamp can only have
|
|
188
|
+
* produced 5m writes (1.25x), while "1h" or unspecified prices every write
|
|
189
|
+
* at the 1h premium (2x) — the dispute-safe reading for an hour-long stamp.
|
|
190
|
+
*/
|
|
191
|
+
meshPlacedTtl?: "5m" | "1h";
|
|
192
|
+
};
|
|
193
|
+
export type LedgerPricing = {
|
|
194
|
+
pricingStatus: "priced";
|
|
195
|
+
actualUsd: number;
|
|
196
|
+
/** Input-side share of actualUsd (actual mode, cache usage included, output excluded). */
|
|
197
|
+
inputUsd: number;
|
|
198
|
+
/** Standard-mode minus actual-mode cost on the same tokens; set only when the mode differs. */
|
|
199
|
+
tierSavedUsd?: number;
|
|
200
|
+
/** Cache economics attributable to MESH; MAY be negative (write surcharge unearned by reads). */
|
|
201
|
+
cacheAttributedUsd?: number;
|
|
202
|
+
/** Cache economics the customer already had; informational, never billed. */
|
|
203
|
+
providerCacheAlreadyOwnedUsd?: number;
|
|
204
|
+
} | {
|
|
205
|
+
pricingStatus: "unpriced";
|
|
206
|
+
reason: string;
|
|
207
|
+
};
|
|
208
|
+
/**
|
|
209
|
+
* Decompose one request's catalogue cost into auditable parts:
|
|
210
|
+
*
|
|
211
|
+
* actualUsd = fullRateStandardUsd - cacheDeltaUsd - tierSavedUsd
|
|
212
|
+
*
|
|
213
|
+
* where fullRateStandardUsd prices every input token at the standard full rate,
|
|
214
|
+
* cacheDeltaUsd is what the prompt cache changed (negative when writes outweigh
|
|
215
|
+
* reads), and tierSavedUsd is the flex/batch price delta on the actual tokens.
|
|
216
|
+
* Unpriced is returned rather than zero whenever a needed rate is missing.
|
|
217
|
+
*/
|
|
218
|
+
export declare function priceLedgerUsage(catalogue: PriceCatalogue, input: LedgerPricingInput): LedgerPricing;
|
|
219
|
+
export type LedgerPricingAudit = {
|
|
220
|
+
status: "verified";
|
|
221
|
+
} | {
|
|
222
|
+
status: "catalogue_version_mismatch";
|
|
223
|
+
eventVersion?: string;
|
|
224
|
+
catalogueVersion: string;
|
|
225
|
+
} | {
|
|
226
|
+
status: "unpriced";
|
|
227
|
+
reason: string;
|
|
228
|
+
} | {
|
|
229
|
+
status: "mismatch";
|
|
230
|
+
field: "actualUsd";
|
|
231
|
+
storedUsd?: number;
|
|
232
|
+
recomputedUsd: number;
|
|
233
|
+
};
|
|
234
|
+
/**
|
|
235
|
+
* Recompute one event's stored cost from its provider-verbatim usage and the
|
|
236
|
+
* given catalogue, with zero tolerance. The catalogue must be the exact version
|
|
237
|
+
* the event was priced against; auditing against a bumped catalogue is reported
|
|
238
|
+
* as a version mismatch rather than a false pricing error.
|
|
239
|
+
*/
|
|
240
|
+
export declare function auditEventPricing(event: BillableEvent, catalogue: PriceCatalogue): LedgerPricingAudit;
|
|
241
|
+
export type InvoiceOptions = {
|
|
242
|
+
/** Restrict to one invoice period (YYYY-MM), matched against each event's own stamp. */
|
|
243
|
+
period?: string;
|
|
244
|
+
/**
|
|
245
|
+
* Override gate verdicts by lever id WITHOUT mutating any event: flipping a
|
|
246
|
+
* lever to "rejected" drops its savings from the invoice on the next recompute.
|
|
247
|
+
*/
|
|
248
|
+
gateVerdictOverrides?: Record<string, "approved" | "rejected">;
|
|
249
|
+
/** Tasks known to have failed quality out-of-band; all their turns' savings are excluded. */
|
|
250
|
+
failedTaskIds?: readonly string[];
|
|
251
|
+
/** MESH's contracted share of net verified savings, 0-100. Omitted: no fee line. */
|
|
252
|
+
feePercent?: number;
|
|
253
|
+
/**
|
|
254
|
+
* Verified-savings deficit carried in from prior periods (the ESPC G.5
|
|
255
|
+
* mechanic): a period that lost money does not just bill zero — its
|
|
256
|
+
* deficit offsets future fees, so aggregate fees can never exceed
|
|
257
|
+
* aggregate verified savings. Non-negative USD.
|
|
258
|
+
*/
|
|
259
|
+
carryForwardDeficitUsd?: number;
|
|
260
|
+
};
|
|
261
|
+
export type InvoiceLineItem = {
|
|
262
|
+
leverId: string;
|
|
263
|
+
kind: LedgerLeverKind;
|
|
264
|
+
events: number;
|
|
265
|
+
savedUsd: number;
|
|
266
|
+
savedCents: number;
|
|
267
|
+
/** Present when ANY contributing lever's savedUsd was estimated-baseline rather than fully measured. */
|
|
268
|
+
basis?: "estimated-baseline";
|
|
269
|
+
gateVerdictRefs: string[];
|
|
270
|
+
};
|
|
271
|
+
export type InvoiceUnbilledItem = {
|
|
272
|
+
leverId: string;
|
|
273
|
+
kind: LedgerLeverKind;
|
|
274
|
+
events: number;
|
|
275
|
+
reason: string;
|
|
276
|
+
};
|
|
277
|
+
export type Invoice = {
|
|
278
|
+
schemaVersion: 1;
|
|
279
|
+
period: string | null;
|
|
280
|
+
catalogueVersions: string[];
|
|
281
|
+
eventsConsidered: number;
|
|
282
|
+
eventsBilled: number;
|
|
283
|
+
failedTaskIds: string[];
|
|
284
|
+
eventsExcludedForFailedTasks: number;
|
|
285
|
+
unpricedEvents: number;
|
|
286
|
+
lineItems: InvoiceLineItem[];
|
|
287
|
+
/** Levers that were applied but carry no billable per-request measurement. */
|
|
288
|
+
recordedUnbilled: InvoiceUnbilledItem[];
|
|
289
|
+
/** Savings the customer already had; shown so the exclusion is checkable, never billed. */
|
|
290
|
+
excludedAlreadyOwned: {
|
|
291
|
+
providerCacheOnAppendedHistoryUsd: number;
|
|
292
|
+
gatewayCacheUsd: number;
|
|
293
|
+
};
|
|
294
|
+
/** Sum of billable components; negatives are netted, never clamped. */
|
|
295
|
+
netVerifiedSavingsUsd: number;
|
|
296
|
+
netVerifiedSavingsCents: number;
|
|
297
|
+
/** Deficit applied from prior periods, when the option was supplied. */
|
|
298
|
+
carryForwardDeficitInUsd?: number;
|
|
299
|
+
/** Deficit to carry into the NEXT period (this period's shortfall after netting). */
|
|
300
|
+
carryForwardDeficitOutUsd?: number;
|
|
301
|
+
verdict: "charge" | "do_not_charge";
|
|
302
|
+
feePercent?: number;
|
|
303
|
+
amountDueUsd?: number;
|
|
304
|
+
amountDueCents?: number;
|
|
305
|
+
};
|
|
306
|
+
/**
|
|
307
|
+
* Why one lever's savings may NOT bill, or undefined when they may. The single
|
|
308
|
+
* rule the invoice and every projection of it (for example the Stripe meter
|
|
309
|
+
* sink) share, so no downstream artifact can ever bill a lever the invoice
|
|
310
|
+
* would refuse: unmeasured levers never bill, and lossy levers bill only with
|
|
311
|
+
* an approved replay-gate verdict.
|
|
312
|
+
*/
|
|
313
|
+
export declare function leverUnbilledReason(lever: LedgerLever, gateVerdictOverrides?: Record<string, "approved" | "rejected">): string | undefined;
|
|
314
|
+
/**
|
|
315
|
+
* The shared selection pipeline: validate, sort, dedupe by requestId, filter
|
|
316
|
+
* to one period, and void every turn of a failed task. Extracted so the
|
|
317
|
+
* invoice and its projections apply IDENTICAL filters; recomputeInvoice's
|
|
318
|
+
* output bytes are unchanged by the extraction.
|
|
319
|
+
*/
|
|
320
|
+
export declare function selectBillableEvents(events: readonly BillableEvent[], options?: Pick<InvoiceOptions, "period" | "failedTaskIds">): {
|
|
321
|
+
/** Deduplicated events inside the period, before task-failure exclusion. */
|
|
322
|
+
consideredEvents: BillableEvent[];
|
|
323
|
+
/** Events whose levers may bill: succeeded, on no failed task. */
|
|
324
|
+
billableEvents: BillableEvent[];
|
|
325
|
+
failedTaskIds: Set<string>;
|
|
326
|
+
eventsExcludedForFailedTasks: number;
|
|
327
|
+
duplicatesIgnored: number;
|
|
328
|
+
};
|
|
329
|
+
/**
|
|
330
|
+
* Recompute the invoice from raw events. Pure and deterministic: events are
|
|
331
|
+
* sorted and deduplicated by requestId before anything is summed, so the same
|
|
332
|
+
* spool replayed twice, a day late, or shuffled produces byte-identical output.
|
|
333
|
+
*/
|
|
334
|
+
export type LedgerAudit = {
|
|
335
|
+
/** Events dropped as requestId replays before anything was summed. */
|
|
336
|
+
duplicatesIgnored: number;
|
|
337
|
+
};
|
|
338
|
+
/**
|
|
339
|
+
* The canonical, customer-recomputable invoice. Deliberately does NOT include
|
|
340
|
+
* replay metadata: whether a spool was transmitted once or three times must not
|
|
341
|
+
* change a single byte of the billing artifact, or "recompute it yourself"
|
|
342
|
+
* stops being a guarantee and becomes a dispute. Replay counts are audit
|
|
343
|
+
* telemetry and come back separately from recomputeInvoiceWithAudit.
|
|
344
|
+
*/
|
|
345
|
+
export declare function recomputeInvoice(events: readonly BillableEvent[], options?: InvoiceOptions): Invoice;
|
|
346
|
+
export declare function recomputeInvoiceWithAudit(events: readonly BillableEvent[], options?: InvoiceOptions): {
|
|
347
|
+
invoice: Invoice;
|
|
348
|
+
audit: LedgerAudit;
|
|
349
|
+
};
|