@xrkseek/harness 0.6.21 → 0.7.0-rc.1

package/node_modules/@xrkseek/xrk-token-meter/lib/types/surface-projection.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The O(1) surface-token fold shared by the token-meter projection units.
+ *
+ * A projection state must stay bounded — the persisted projection cache
+ * checkpoints every unit's whole state, so carrying the priced surface
+ * (one node per model-visible message) would grow a checkpoint without
+ * bound over the session's life. Instead, replacements ride the compact
+ * seam's shadow-price protocol: the metering event immediately before a
+ * surface `replace` (`compaction/summary` or `compaction/prune`) states the
+ * heuristic price of the exact replaced range, so the fold keeps a running
+ * total plus at most one pending claim and never retains per-node prices.
+ * The counts are exact by construction: producers derive them from the same
+ * fixed estimator this module prices appends with. A replacement without an
+ * armed claim folds with zero delta because bounded state cannot reconstruct
+ * the replaced range; this preserves replay at the cost of possible drift.
+ *
+ * @module @xrkseek/xrk-token-meter/surface-projection
+ */
+import type { SessionEvent } from '@xrkseek/xrk-session';
+/**
+ * One armed shadow price: the heuristic tokens of the surface range the
+ * IMMEDIATELY following event replaces. Plain JSON — it is part of the
+ * persisted unit state while armed.
+ */
+export interface ShadowPriceClaim {
+    /** Declared inclusive first surface-node seq of the priced range. */
+    start: number;
+    /** Declared inclusive last surface-node seq of the priced range. */
+    end: number;
+    /** Heuristic tokens of the priced range under the fixed estimator. */
+    tokens: number;
+}
+/** One event's effect on a running surface-token total. */
+export interface SurfaceTokensFold {
+    /** Signed change in the surface total; 0 for events off the surface. */
+    readonly deltaTokens: number;
+    /** Claim to carry into the next event; undefined when none survives. */
+    readonly claim: ShadowPriceClaim | undefined;
+}
+/**
+ * Fold one committed event onto a running surface-token total.
+ *
+ * A shadow-price event arms a claim; any other event expires it, and a
+ * surface `replace` consumes the claim naming its exact range — the
+ * producers append the metering event and the replacement synchronously
+ * adjacent, so a surviving claim always prices the very next event.
+ * A replace with no claim folds with zero delta because the bounded state
+ * cannot reconstruct the replaced range. An armed claim for another range
+ * still fails because the adjacent events contradict each other.
+ * @param claim - the claim armed by the immediately preceding event, if any.
+ * @param event - the next committed session event.
+ * @returns the signed token delta and the claim state after this event.
+ * @throws when a replacement arrives with an armed claim for a different
+ *   range — the metering event was adjacent, so this is a live producer's
+ *   shadow-price contract violation, not historical data, and must fail
+ *   loud rather than let the total drift.
+ */
+export declare function foldSurfaceProjection(claim: ShadowPriceClaim | undefined, event: SessionEvent): SurfaceTokensFold;
+//# sourceMappingURL=surface-projection.d.ts.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/surface-projection.js

@@ -0,0 +1,66 @@
+/**
+ * The O(1) surface-token fold shared by the token-meter projection units.
+ *
+ * A projection state must stay bounded — the persisted projection cache
+ * checkpoints every unit's whole state, so carrying the priced surface
+ * (one node per model-visible message) would grow a checkpoint without
+ * bound over the session's life. Instead, replacements ride the compact
+ * seam's shadow-price protocol: the metering event immediately before a
+ * surface `replace` (`compaction/summary` or `compaction/prune`) states the
+ * heuristic price of the exact replaced range, so the fold keeps a running
+ * total plus at most one pending claim and never retains per-node prices.
+ * The counts are exact by construction: producers derive them from the same
+ * fixed estimator this module prices appends with. A replacement without an
+ * armed claim folds with zero delta because bounded state cannot reconstruct
+ * the replaced range; this preserves replay at the cost of possible drift.
+ *
+ * @module @xrkseek/xrk-token-meter/surface-projection
+ */
+import { deriveEventMessage, isSurfaceEvent } from '@xrkseek/xrk-session';
+import { estimateMessage } from "./estimate.js";
+/**
+ * Fold one committed event onto a running surface-token total.
+ *
+ * A shadow-price event arms a claim; any other event expires it, and a
+ * surface `replace` consumes the claim naming its exact range — the
+ * producers append the metering event and the replacement synchronously
+ * adjacent, so a surviving claim always prices the very next event.
+ * A replace with no claim folds with zero delta because the bounded state
+ * cannot reconstruct the replaced range. An armed claim for another range
+ * still fails because the adjacent events contradict each other.
+ * @param claim - the claim armed by the immediately preceding event, if any.
+ * @param event - the next committed session event.
+ * @returns the signed token delta and the claim state after this event.
+ * @throws when a replacement arrives with an armed claim for a different
+ *   range — the metering event was adjacent, so this is a live producer's
+ *   shadow-price contract violation, not historical data, and must fail
+ *   loud rather than let the total drift.
+ */
+export function foldSurfaceProjection(claim, event) {
+    if (event.type === 'compaction/summary' || event.type === 'compaction/prune') {
+        const { shadowedRange, shadowedTokenCount } = event.data;
+        return {
+            deltaTokens: 0,
+            claim: { start: shadowedRange.start, end: shadowedRange.end, tokens: shadowedTokenCount },
+        };
+    }
+    if (!isSurfaceEvent(event))
+        return { deltaTokens: 0, claim: undefined };
+    const message = deriveEventMessage(event);
+    const tokens = message === null ? 0 : estimateMessage(message);
+    const op = event.surfaceOp;
+    if (op === 'append')
+        return { deltaTokens: tokens, claim: undefined };
+    // Sessions recorded before the shadow-price protocol log replacements with
+    // no adjacent metering event; the bounded state cannot reconstruct the
+    // replaced range's price, so fold those neutrally — historical replay
+    // degrades to drift instead of failing.
+    if (claim === undefined)
+        return { deltaTokens: 0, claim: undefined };
+    if (claim.start !== op.start || claim.end !== op.end) {
+        throw new Error(`token surface: replace at seq ${event.seq} over range ${op.start}-${op.end} has no adjacent shadow price`
+            + ` (armed claim covers ${claim.start}-${claim.end})`);
+    }
+    return { deltaTokens: tokens - claim.tokens, claim: undefined };
+}
+//# sourceMappingURL=surface-projection.js.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/turn-usage.d.ts

@@ -0,0 +1,33 @@
+import type { SessionEvent } from '@xrkseek/xrk-session/types';
+/** One provider/model route that contributed a billed request attempt. */
+export interface TurnTokenUsageRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Exact provider-reported token accounting for every attempt in one completed Turn. */
+export interface TurnTokenUsage {
+    /** Sum of uncached prompt input across all attempts. */
+    readonly uncachedInputTokens: number;
+    readonly outputTokens: number;
+    /** Exact aggregate prompt plus output total across all attempts. */
+    readonly totalTokens: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheReadTokens?: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheWriteTokens?: number;
+    /** Output subset, present only when every attempt reported it. */
+    readonly reasoningTokens?: number;
+    /** Present only when every billed attempt has provider/model attribution. */
+    readonly routes?: readonly TurnTokenUsageRoute[];
+}
+/**
+ * Fold one complete Turn's durable attempt lifecycle into exact token accounting.
+ *
+ * No attempt is inferred from a usage sample. Any missing lifecycle boundary,
+ * incomplete attempt usage, unsafe count, or contradictory exact total makes
+ * the whole disclosure unavailable.
+ * @param events - Turn-local durable events from `turn/start` through `turn/end`.
+ * @returns exact aggregate usage, or undefined when it cannot be proven.
+ */
+export declare function deriveTurnTokenUsage(events: readonly SessionEvent[]): TurnTokenUsage | undefined;
+//# sourceMappingURL=turn-usage.d.ts.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/turn-usage.js

@@ -0,0 +1,247 @@
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function safeSum(values) {
+    let total = 0;
+    for (const value of values) {
+        total += value;
+        if (!Number.isSafeInteger(total))
+            return undefined;
+    }
+    return total;
+}
+function messageRoute(message) {
+    const { provider, model } = message.source;
+    return provider.length > 0 && model.length > 0 ? { provider, model } : undefined;
+}
+function eventKind(event) {
+    return event.type;
+}
+function retryCoords(event) {
+    const kind = eventKind(event);
+    if (kind !== 'llm/retry' && kind !== 'llm/retry-started')
+        return undefined;
+    const data = event.data;
+    return typeof data.turn === 'number' && typeof data.step === 'number' ? data : undefined;
+}
+function normalizeUsage(usage, route) {
+    const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, totalTokens, } = usage;
+    if (!isCount(inputTokens) || !isCount(outputTokens))
+        return undefined;
+    if (cacheReadTokens !== undefined && !isCount(cacheReadTokens))
+        return undefined;
+    if (cacheWriteTokens !== undefined && !isCount(cacheWriteTokens))
+        return undefined;
+    if (reasoningTokens !== undefined && (!isCount(reasoningTokens) || reasoningTokens > outputTokens)) {
+        return undefined;
+    }
+    const knownPrompt = safeSum([
+        inputTokens,
+        ...cacheReadTokens === undefined ? [] : [cacheReadTokens],
+        ...cacheWriteTokens === undefined ? [] : [cacheWriteTokens],
+    ]);
+    if (knownPrompt === undefined)
+        return undefined;
+    let exactTotal;
+    if (totalTokens !== undefined) {
+        if (!isCount(totalTokens))
+            return undefined;
+        const exactPrompt = totalTokens - outputTokens;
+        if (!isCount(exactPrompt) || exactPrompt < knownPrompt)
+            return undefined;
+        if (cacheReadTokens !== undefined && cacheWriteTokens !== undefined && exactPrompt !== knownPrompt) {
+            return undefined;
+        }
+        exactTotal = totalTokens;
+    }
+    else {
+        if (cacheReadTokens === undefined || cacheWriteTokens === undefined)
+            return undefined;
+        const derivedTotal = safeSum([knownPrompt, outputTokens]);
+        if (derivedTotal === undefined)
+            return undefined;
+        exactTotal = derivedTotal;
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: exactTotal,
+        ...cacheReadTokens === undefined ? {} : { cacheReadTokens },
+        ...cacheWriteTokens === undefined ? {} : { cacheWriteTokens },
+        ...reasoningTokens === undefined ? {} : { reasoningTokens },
+        ...route === undefined ? {} : { route },
+    };
+}
+function aggregateAttempts(attempts) {
+    if (attempts.length === 0)
+        return undefined;
+    const inputTokens = safeSum(attempts.map(attempt => attempt.inputTokens));
+    const outputTokens = safeSum(attempts.map(attempt => attempt.outputTokens));
+    const totalTokens = safeSum(attempts.map(attempt => attempt.totalTokens));
+    if (inputTokens === undefined || outputTokens === undefined || totalTokens === undefined)
+        return undefined;
+    const cacheRead = attempts.map(attempt => attempt.cacheReadTokens);
+    const cacheWrite = attempts.map(attempt => attempt.cacheWriteTokens);
+    const reasoning = attempts.map(attempt => attempt.reasoningTokens);
+    const cacheReadTokens = cacheRead.every(isCount) ? safeSum(cacheRead) : undefined;
+    const cacheWriteTokens = cacheWrite.every(isCount) ? safeSum(cacheWrite) : undefined;
+    const reasoningTokens = reasoning.every(isCount) ? safeSum(reasoning) : undefined;
+    // A present cache bucket is bounded by exact prompt, and reasoning is bounded
+    // by output. Safe required aggregates therefore imply safe optional sums.
+    let routes;
+    const attributed = attempts.map(attempt => attempt.route);
+    if (attributed.every((route) => route !== undefined)) {
+        const unique = new Map();
+        for (const route of attributed)
+            unique.set(`${route.provider}\0${route.model}`, route);
+        routes = [...unique.values()];
+    }
+    return {
+        uncachedInputTokens: inputTokens,
+        outputTokens,
+        totalTokens,
+        ...cacheReadTokens === undefined ? {} : { cacheReadTokens },
+        ...cacheWriteTokens === undefined ? {} : { cacheWriteTokens },
+        ...reasoningTokens === undefined ? {} : { reasoningTokens },
+        ...routes === undefined ? {} : { routes },
+    };
+}
+function sameAttempt(state, turn, step) {
+    return state.turn === turn && state.step === step;
+}
+/**
+ * Fold one complete Turn's durable attempt lifecycle into exact token accounting.
+ *
+ * No attempt is inferred from a usage sample. Any missing lifecycle boundary,
+ * incomplete attempt usage, unsafe count, or contradictory exact total makes
+ * the whole disclosure unavailable.
+ * @param events - Turn-local durable events from `turn/start` through `turn/end`.
+ * @returns exact aggregate usage, or undefined when it cannot be proven.
+ */
+export function deriveTurnTokenUsage(events) {
+    let state = { kind: 'idle' };
+    const attempts = [];
+    let turn;
+    let sawEnd = false;
+    let invalid = false;
+    const closeOpen = (route) => {
+        if (state.kind !== 'open' || state.sample === undefined)
+            return false;
+        const normalized = normalizeUsage(state.sample, route);
+        if (normalized === undefined)
+            return false;
+        attempts.push(normalized);
+        return true;
+    };
+    for (const event of events) {
+        if (invalid)
+            break;
+        const kind = eventKind(event);
+        if (kind === 'turn/start') {
+            if (turn !== undefined || state.kind !== 'idle')
+                invalid = true;
+            else
+                turn = event.data.turn;
+            continue;
+        }
+        if (turn === undefined) {
+            invalid = true;
+            break;
+        }
+        if (kind === 'turn/end') {
+            const data = event.data;
+            if (data.turn !== turn || state.kind !== 'idle' || sawEnd)
+                invalid = true;
+            else
+                sawEnd = true;
+            continue;
+        }
+        if (sawEnd) {
+            invalid = true;
+            break;
+        }
+        if (kind === 'step/start') {
+            const data = event.data;
+            if (data.turn !== turn || state.kind !== 'idle')
+                invalid = true;
+            else
+                state = { kind: 'open', turn, step: data.step };
+            continue;
+        }
+        if (kind === 'llm/retry-started') {
+            const coords = retryCoords(event);
+            if (coords === undefined
+                || coords.turn !== turn
+                || state.kind !== 'settled'
+                || state.by !== 'retry'
+                || !sameAttempt(state, coords.turn, coords.step))
+                invalid = true;
+            else
+                state = { kind: 'open', turn, step: coords.step };
+            continue;
+        }
+        if (kind === 'assistant/chunk') {
+            const data = event.data;
+            if (data.turn !== turn
+                || state.kind !== 'open'
+                || !sameAttempt(state, data.turn, data.step)) {
+                invalid = true;
+                continue;
+            }
+            if (data.chunk.type === 'usage') {
+                state = { ...state, sample: data.chunk.usage };
+            }
+            else if (data.chunk.type === 'finish'
+                && (data.chunk.reason.kind === 'error' || data.chunk.reason.kind === 'aborted')) {
+                if (!closeOpen())
+                    invalid = true;
+                else
+                    state = { kind: 'finishClosed', turn, step: data.step };
+            }
+            continue;
+        }
+        if (kind === 'assistant/message') {
+            const data = event.data;
+            if (data.turn !== turn
+                || state.kind !== 'open'
+                || !sameAttempt(state, data.turn, data.step)) {
+                invalid = true;
+                continue;
+            }
+            if (data.usage !== undefined)
+                state = { ...state, sample: data.usage };
+            if (!closeOpen(messageRoute(data.message)))
+                invalid = true;
+            else
+                state = { kind: 'settled', turn, step: data.step, by: 'message' };
+            continue;
+        }
+        if (kind === 'llm/retry') {
+            const coords = retryCoords(event);
+            if (coords === undefined || coords.turn !== turn || state.kind === 'idle'
+                || !sameAttempt(state, coords.turn, coords.step)) {
+                invalid = true;
+                continue;
+            }
+            if (state.kind === 'settled' || (state.kind === 'open' && !closeOpen()))
+                invalid = true;
+            if (!invalid)
+                state = { kind: 'settled', turn, step: coords.step, by: 'retry' };
+            continue;
+        }
+        if (kind === 'step/end') {
+            const data = event.data;
+            if (data.turn !== turn || state.kind === 'idle'
+                || !sameAttempt(state, data.turn, data.step)) {
+                invalid = true;
+                continue;
+            }
+            if (state.kind === 'open' && !closeOpen())
+                invalid = true;
+            if (!invalid)
+                state = { kind: 'idle' };
+        }
+    }
+    return invalid || !sawEnd || state.kind !== 'idle' ? undefined : aggregateAttempts(attempts);
+}
+//# sourceMappingURL=turn-usage.js.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @xrkseek/xrk-token-meter/types
+ */
+import type { TokenUsage } from '@xrkseek/xrk-llm';
+export type { ContextBreakdownProjection, ContextPressureProjection, TokenUsageProjection } from './projection.ts';
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record<string, never>;
+/** The baseline from which a signed surface delta produces current pressure. */
+export type TokenMeasurementBaseline = {
+    readonly kind: 'none';
+    readonly tokens: 0;
+} | {
+    readonly kind: 'estimated';
+    readonly tokens: number;
+} | {
+    readonly kind: 'usage';
+    readonly tokens: number;
+    readonly usage: Readonly<TokenUsage>;
+};
+/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
+export interface TokenMeasurement {
+    /** Number of durable events consumed; equal to the next unread event seq. */
+    readonly logRevision: number;
+    /** Provider or heuristic anchor used for this measurement. */
+    readonly baseline: TokenMeasurementBaseline;
+    /** Signed repricing of current surface content relative to the baseline anchor. */
+    readonly surfaceDeltaTokens: number;
+    /** Non-negative current request-and-response pressure. */
+    readonly totalTokens: number;
+    /** Total heuristic tokens across the current surface. */
+    readonly surfaceTokens: number;
+    /** Current surface nodes in positional head-to-tail order. */
+    readonly nodes: readonly TokenSurfaceNode[];
+}
+/** One token-priced node in the current ordered session surface. */
+export interface TokenSurfaceNode {
+    /** Durable sequence number of the surface event. */
+    readonly seq: number;
+    /** Heuristic tokens for the exact message projected by this node. */
+    readonly tokens: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @xrkseek/xrk-token-meter/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/usage-projection.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure folds for durable provider-reported token usage and context occupancy.
+ */
+import type { ProjectionDefinition } from '@xrkseek/xrk-session-projection';
+import type { TokenUsageProjection } from './projection.ts';
+import type { ShadowPriceClaim } from './surface-projection.ts';
+interface UsageSample {
+    turn: number;
+    step: number;
+    buckets: TokenUsageProjection;
+}
+interface TokenUsageState {
+    totals: TokenUsageProjection;
+    last: UsageSample | null;
+}
+/**
+ * Context-occupancy state: the two independent last-wins records plus the
+ * O(1) running surface total needed to carry the newest sample forward.
+ */
+interface ContextPressureState {
+    contextWindow?: number;
+    pressureTokens?: number;
+    /** Running heuristic total over the current surface ({@link foldSurfaceProjection}). */
+    surfaceTokens: number;
+    /** {@link surfaceTokens} at the newest usage sample; absent until one lands. */
+    sampledSurfaceTokens?: number;
+    /** Shadow price armed by the immediately preceding metering event. */
+    claim?: ShadowPriceClaim;
+}
+/**
+ * Token-meter's session projection unit.
+ *
+ * Usage chunks provide an early sample that survives a later request failure;
+ * an assistant message provides the final sample for the same turn/step. A
+ * repeated sample replaces that step's earlier value instead of double
+ * counting it. The single `last` slot relies on the session-log invariant
+ * that usage reports for one turn/step are adjacent: once a later step begins,
+ * a legal log never reports usage for an earlier step again.
+ */
+export declare const tokenUsageProjectionDefinition: ProjectionDefinition<'tokenUsage', TokenUsageState>;
+/**
+ * Token-meter's context-occupancy projection unit.
+ *
+ * Independent last-wins slots: the newest usage sample supplies the provider
+ * numerator, the newest `request/context` record the denominator. Both are
+ * whole values, so replay order alone decides the result and no cross-field
+ * consistency is claimed — the pair is explicitly not one atomic request
+ * observation (see {@link ContextPressureProjection}).
+ *
+ * `pressureTokens` is prompt-side only, so it holds still while a turn streams
+ * and steps forward once the next request reports its usage. Because nothing
+ * but a request reports usage, it also cannot see a compaction: the fold
+ * therefore carries a running surface total alongside it and publishes
+ * `projectedTokens` — the sample plus the surface's signed movement since it
+ * was taken — so occupancy answers for the next request rather than the last
+ * one. The total rides {@link foldSurfaceProjection}, so the state stays O(1)
+ * and a replacement shrinks it by its logged shadow price. A replacement
+ * without a claim preserves the previous total. A usage sample is stamped
+ * BEFORE the same event joins the surface, so an `assistant/message` anchors
+ * against the surface its own request saw.
+ */
+export declare const contextPressureProjectionDefinition: ProjectionDefinition<'contextPressure', ContextPressureState>;
+export {};
+//# sourceMappingURL=usage-projection.d.ts.map