@xrkseek/harness 0.6.21 → 0.7.0-rc.1

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

@@ -0,0 +1,7 @@
+/**
+ * Client-namespace projection of token-meter's browser-safe contracts and folds.
+ *
+ * @module @xrkseek/xrk-token-meter/client
+ */
+export { deriveTurnTokenUsage } from "./turn-usage.js";
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * Fixed-density heuristic token pricing shared by the meter service and the
+ * pure context-breakdown projection, so both surfaces price identical content
+ * to identical numbers.
+ *
+ * @module @xrkseek/xrk-token-meter/estimate
+ */
+import type { ContentBlock, Message } from '@xrkseek/xrk-llm';
+import type { EpochHeader } from '@xrkseek/xrk-session';
+/** Role-field framing overhead added to every priced message. */
+export declare const ROLE_OVERHEAD = 4;
+/**
+ * Price content blocks recursively under the fixed density heuristic.
+ * @param blocks - content blocks to price without mutation.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export declare function estimateContent(blocks: readonly ContentBlock[]): number;
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed heuristic.
+ */
+export declare function estimateMessage(message: Message): number;
+/**
+ * Price the system-prompt part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system-prompt tokens; 0 when absent.
+ */
+export declare function estimateSystemTokens(header: EpochHeader | undefined): number;
+/**
+ * Price the tool-schema part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic tool-schema tokens; 0 when absent or empty.
+ */
+export declare function estimateToolsTokens(header: EpochHeader | undefined): number;
+/**
+ * Price the complete non-surface request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system plus tool tokens.
+ */
+export declare function estimateHeader(header: EpochHeader | undefined): number;
+//# sourceMappingURL=estimate.d.ts.map

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

@@ -0,0 +1,79 @@
+/**
+ * Fixed-density heuristic token pricing shared by the meter service and the
+ * pure context-breakdown projection, so both surfaces price identical content
+ * to identical numbers.
+ *
+ * @module @xrkseek/xrk-token-meter/estimate
+ */
+/** Fixed text-density estimate used until exact tokenization is needed. */
+const CHARS_PER_TOKEN = 4;
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4;
+/** Role-field framing overhead added to every priced message. */
+export const ROLE_OVERHEAD = 4;
+/**
+ * Price content blocks recursively under the fixed density heuristic.
+ * @param blocks - content blocks to price without mutation.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export function estimateContent(blocks) {
+    let tokens = 0;
+    for (const block of blocks) {
+        switch (block.type) {
+            case 'text':
+            case 'reasoning':
+                tokens += Math.ceil(block.text.length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+                break;
+            case 'tool-call':
+                tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN)
+                    + Math.ceil(block.arguments.length / CHARS_PER_TOKEN)
+                    + BLOCK_OVERHEAD;
+                break;
+            case 'tool-result':
+                tokens += estimateContent(block.content) + BLOCK_OVERHEAD;
+                break;
+            default:
+                // ContentBlockMap is merge-extensible; unknown blocks retain a
+                // conservative structural JSON price under the fixed heuristic.
+                tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN);
+        }
+    }
+    return tokens;
+}
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed heuristic.
+ */
+export function estimateMessage(message) {
+    return estimateContent(message.content) + ROLE_OVERHEAD;
+}
+/**
+ * Price the system-prompt part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system-prompt tokens; 0 when absent.
+ */
+export function estimateSystemTokens(header) {
+    if (header?.system === undefined)
+        return 0;
+    return Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
+}
+/**
+ * Price the tool-schema part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic tool-schema tokens; 0 when absent or empty.
+ */
+export function estimateToolsTokens(header) {
+    if (header?.tools === undefined || header.tools.length === 0)
+        return 0;
+    return Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+}
+/**
+ * Price the complete non-surface request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system plus tool tokens.
+ */
+export function estimateHeader(header) {
+    return estimateSystemTokens(header) + estimateToolsTokens(header);
+}
+//# sourceMappingURL=estimate.js.map

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

@@ -0,0 +1,62 @@
+/**
+ * Single replay-aware token-meter service for request and surface pressure.
+ *
+ * @module @xrkseek/xrk-token-meter
+ */
+import { Context, Service } from '@xrkseek/cordis';
+import z from '@xrkseek/schemastery';
+import type { Message } from '@xrkseek/xrk-llm';
+import type { EpochHeader, Session } from '@xrkseek/xrk-session';
+import type { TokenMeasurement, TokenMeterConfig } from './types.ts';
+export type * from './types.ts';
+declare module '@xrkseek/cordis' {
+    interface Context {
+        tokenMeter: TokenMeter;
+    }
+}
+/** Replay owner for one service-wide estimator and isolated per-session folds. */
+export declare class TokenMeter extends Service {
+    static Config: z<TokenMeterConfig>;
+    private readonly states;
+    constructor(ctx: Context, config?: TokenMeterConfig);
+    /**
+     * Measure current request pressure and surface through the durable tail.
+     *
+     * Provider usage is reused only when the latest successful call's canonical
+     * request envelope matches `requestHeader` and its total is no lower than
+     * that call's full heuristic anchor; otherwise the complete envelope and
+     * surface are heuristically repriced.
+     *
+     * `requestHeader` affects request pressure only; surface fields always
+     * describe the current session surface. Every call clones those positional
+     * nodes, so measurement is O(surface).
+     *
+     * @param session - session to replay through its current durable tail.
+     * @param requestHeader - optional effective request envelope replacing the latest logged header.
+     * @returns a detached deeply immutable pressure and surface measurement.
+     */
+    measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement;
+    /**
+     * Heuristically price one model-visible message (instance face of the pure
+     * `estimateMessage` export from `estimate.ts`).
+     * @param message - message to price without mutation.
+     * @returns content and role-framing tokens under the fixed service heuristic.
+     */
+    estimateMessage(message: Message): number;
+    /** Catch one session's fold up to the current durable tail. */
+    private _sync;
+    /**
+     * Validate and prepare every fallible part before mutating replay state.
+     * A malformed event remains unread on every retry instead of partially
+     * applying the same mutation more than once.
+     */
+    private _foldEvent;
+    /**
+     * Reassemble provider output from the exact cited chunk seqs for a usage anchor.
+     * Missing legacy source seqs conservatively treat the durable output as the
+     * provider output; an explicit empty list prices a known empty stream.
+     */
+    private _estimateProviderAssistant;
+}
+export default TokenMeter;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,250 @@
+/**
+ * Single replay-aware token-meter service for request and surface pressure.
+ *
+ * @module @xrkseek/xrk-token-meter
+ */
+import { Service } from '@xrkseek/cordis';
+import z from '@xrkseek/schemastery';
+import { BlockAssembler, deepFreeze } from '@xrkseek/xrk-llm';
+import { canonicalHeader, headerEquals, isSurfaceEvent } from '@xrkseek/xrk-session';
+import { contextBreakdownProjectionDefinition } from "./breakdown-projection.js";
+import { contextPressureProjectionDefinition, tokenUsageProjectionDefinition } from "./usage-projection.js";
+import { estimateContent, estimateHeader, estimateMessage, ROLE_OVERHEAD } from "./estimate.js";
+import { foldSurfaceTokens } from "./surface-fold.js";
+/** Sum disjoint provider usage buckets without double-counting reasoning output. */
+function usageTokens(usage) {
+    return usage.inputTokens
+        + (usage.cacheReadTokens ?? 0)
+        + (usage.cacheWriteTokens ?? 0)
+        + usage.outputTokens;
+}
+/** Compare optional envelopes so a headerless estimate can track later surface deltas. */
+function optionalHeaderEquals(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return headerEquals(left, right);
+}
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateConfigKeys(config) {
+    for (const key of Object.keys(config)) {
+        throw new Error(`TokenMeterConfig: unknown key "${key}" (no settings are supported)`);
+    }
+}
+/** Replay owner for one service-wide estimator and isolated per-session folds. */
+export class TokenMeter extends Service {
+    // Schemastery preserves untrusted loader keys on an empty object schema;
+    // the public type excludes settings while validateConfigKeys rejects them.
+    static Config = z.object({});
+    states = new WeakMap();
+    constructor(ctx, config = {}) {
+        super(ctx, 'tokenMeter');
+        validateConfigKeys(config);
+        // Projection registration is an optional child: compositions without the
+        // generic registry keep the meter's standalone read shape.
+        ctx.inject(['sessionProjections'], (projectionCtx) => {
+            projectionCtx.sessionProjections.register(tokenUsageProjectionDefinition);
+            projectionCtx.sessionProjections.register(contextPressureProjectionDefinition);
+            projectionCtx.sessionProjections.register(contextBreakdownProjectionDefinition);
+        });
+        // Readers catch up independently, while eager observation bounds ordinary
+        // read latency without creating state for sessions no consumer has read.
+        ctx.on('session/event', (session) => {
+            if (this.states.has(session))
+                this._sync(session);
+        });
+    }
+    /**
+     * Measure current request pressure and surface through the durable tail.
+     *
+     * Provider usage is reused only when the latest successful call's canonical
+     * request envelope matches `requestHeader` and its total is no lower than
+     * that call's full heuristic anchor; otherwise the complete envelope and
+     * surface are heuristically repriced.
+     *
+     * `requestHeader` affects request pressure only; surface fields always
+     * describe the current session surface. Every call clones those positional
+     * nodes, so measurement is O(surface).
+     *
+     * @param session - session to replay through its current durable tail.
+     * @param requestHeader - optional effective request envelope replacing the latest logged header.
+     * @returns a detached deeply immutable pressure and surface measurement.
+     */
+    measure(session, requestHeader) {
+        const state = this._sync(session);
+        const header = requestHeader === undefined
+            ? state.header
+            : canonicalHeader(requestHeader);
+        const anchor = state.anchor;
+        let baseline;
+        let surfaceDeltaTokens;
+        if (anchor !== undefined && optionalHeaderEquals(anchor.header, header)) {
+            baseline = anchor.baseline;
+            surfaceDeltaTokens = state.surfaceTokens - anchor.surfaceTokens;
+        }
+        else if (header === undefined && state.surfaceTokens === 0) {
+            baseline = { kind: 'none', tokens: 0 };
+            surfaceDeltaTokens = 0;
+        }
+        else {
+            baseline = {
+                kind: 'estimated',
+                tokens: estimateHeader(header) + state.surfaceTokens,
+            };
+            surfaceDeltaTokens = 0;
+        }
+        return deepFreeze(structuredClone({
+            logRevision: state.consumedEvents,
+            baseline,
+            surfaceDeltaTokens,
+            totalTokens: Math.max(0, baseline.tokens + surfaceDeltaTokens),
+            surfaceTokens: state.surfaceTokens,
+            nodes: state.surface,
+        }));
+    }
+    /**
+     * Heuristically price one model-visible message (instance face of the pure
+     * `estimateMessage` export from `estimate.ts`).
+     * @param message - message to price without mutation.
+     * @returns content and role-framing tokens under the fixed service heuristic.
+     */
+    estimateMessage(message) {
+        return estimateMessage(message);
+    }
+    /** Catch one session's fold up to the current durable tail. */
+    _sync(session) {
+        let state = this.states.get(session);
+        if (state === undefined) {
+            state = {
+                consumedEvents: 0,
+                header: undefined,
+                surface: [],
+                surfaceTokens: 0,
+                stepStart: undefined,
+                anchor: undefined,
+            };
+            this.states.set(session, state);
+        }
+        while (state.consumedEvents < session.events.length) {
+            // oxlint-disable-next-line typescript/no-non-null-assertion -- contiguous session seqs index the durable log
+            const event = session.events[state.consumedEvents];
+            this._foldEvent(session, state, event);
+            state.consumedEvents += 1;
+        }
+        return state;
+    }
+    /**
+     * Validate and prepare every fallible part before mutating replay state.
+     * A malformed event remains unread on every retry instead of partially
+     * applying the same mutation more than once.
+     */
+    _foldEvent(session, state, event) {
+        let nextHeader = state.header;
+        let nextStepStart = state.stepStart;
+        let nextAnchor = state.anchor;
+        switch (event.type) {
+            case 'request/header':
+                nextHeader = canonicalHeader(event.data.header);
+                break;
+            case 'step/start':
+                if (state.stepStart !== undefined) {
+                    throw new Error(`token meter: step/start at seq ${event.seq} arrived before turn ${state.stepStart.turn}/step ${state.stepStart.step} ended`);
+                }
+                nextStepStart = { ...event.data, surfaceTokens: state.surfaceTokens };
+                break;
+            case 'step/end':
+                if (state.stepStart === undefined
+                    || state.stepStart.turn !== event.data.turn
+                    || state.stepStart.step !== event.data.step) {
+                    throw new Error(`token meter: step/end at seq ${event.seq} has no matching step/start event`);
+                }
+                nextStepStart = undefined;
+                break;
+            default:
+                break;
+        }
+        const surface = isSurfaceEvent(event)
+            ? foldSurfaceTokens(state.surface, event)
+            : undefined;
+        if (event.type === 'assistant/message') {
+            const stepStart = state.stepStart;
+            if (stepStart === undefined
+                || stepStart.turn !== event.data.turn
+                || stepStart.step !== event.data.step) {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} has no matching step/start event`);
+            }
+            // assistant/message is surface-mandatory at every append/seed boundary.
+            // oxlint-disable-next-line typescript/no-non-null-assertion
+            const eventTokens = surface.tokens;
+            if (event.data.usage !== undefined && nextHeader !== undefined) {
+                const providerAssistantTokens = this._estimateProviderAssistant(session, event, eventTokens);
+                const anchorSurfaceTokens = stepStart.surfaceTokens + providerAssistantTokens;
+                const providerTokens = usageTokens(event.data.usage);
+                const estimatedAnchorTokens = estimateHeader(nextHeader) + anchorSurfaceTokens;
+                nextAnchor = {
+                    header: nextHeader,
+                    surfaceTokens: anchorSurfaceTokens,
+                    // Signed heuristic deltas remain conservative only from an anchor
+                    // that is at least as large as the matching full heuristic price.
+                    baseline: providerTokens >= estimatedAnchorTokens
+                        ? { kind: 'usage', tokens: providerTokens, usage: event.data.usage }
+                        : { kind: 'estimated', tokens: estimatedAnchorTokens },
+                };
+            }
+            else {
+                const anchorSurfaceTokens = stepStart.surfaceTokens + eventTokens;
+                nextAnchor = {
+                    header: nextHeader,
+                    surfaceTokens: anchorSurfaceTokens,
+                    baseline: {
+                        kind: 'estimated',
+                        tokens: estimateHeader(nextHeader) + anchorSurfaceTokens,
+                    },
+                };
+            }
+        }
+        state.header = nextHeader;
+        state.stepStart = nextStepStart;
+        if (surface !== undefined) {
+            state.surface = surface.nodes;
+            state.surfaceTokens += surface.deltaTokens;
+        }
+        state.anchor = nextAnchor;
+    }
+    /**
+     * Reassemble provider output from the exact cited chunk seqs for a usage anchor.
+     * Missing legacy source seqs conservatively treat the durable output as the
+     * provider output; an explicit empty list prices a known empty stream.
+     */
+    _estimateProviderAssistant(session, event, durableEventTokens) {
+        const sourceSeqs = event.sourceEventSeqs;
+        if (sourceSeqs === undefined)
+            return durableEventTokens;
+        const assembler = new BlockAssembler();
+        const seen = new Set();
+        for (const seq of sourceSeqs) {
+            if (seq >= event.seq) {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not earlier`);
+            }
+            if (seen.has(seq)) {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} repeats source seq ${seq}`);
+            }
+            seen.add(seq);
+            // Session construction validates contiguous seqs, and the explicit
+            // earlier-than-assistant check above therefore guarantees existence.
+            const source = session.events[seq];
+            // oxlint-disable-next-line typescript/no-non-null-assertion
+            const sourceEvent = source;
+            if (sourceEvent.type !== 'assistant/chunk') {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not assistant/chunk`);
+            }
+            if (sourceEvent.data.turn !== event.data.turn || sourceEvent.data.step !== event.data.step) {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} belongs to another step`);
+            }
+            assembler.push(sourceEvent.data.chunk);
+        }
+        const providerContent = assembler.blocks();
+        return providerContent.length === 0 ? 0 : estimateContent(providerContent) + ROLE_OVERHEAD;
+    }
+}
+export default TokenMeter;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@xrkseek/xrk-token-meter`.
+ * @module @xrkseek/xrk-token-meter/invariant
+ */
+import type { Context } from '@xrkseek/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "token-meter-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@xrkseek/xrk-token-meter`.
+ * @module @xrkseek/xrk-token-meter/invariant
+ */
+const PACKAGE_NAME = '@xrkseek/xrk-token-meter';
+/** Cordis companion plugin name. */
+export const name = 'token-meter-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: token estimates are per-call outputs and the private
+ * session cache is invalidated at its event mutation boundary. The package's
+ * three projections do expose observation streams, but their schemas fix the
+ * JSON payloads; the usage folds replace same-step samples, so totals need not
+ * be monotone when a final sample corrects an earlier chunk, and the
+ * composition fold prices through the same `estimate.ts` heuristic as the
+ * measurement service and subtracts producer-logged shadow prices derived
+ * from that service's own nodes, which makes its message figure equal
+ * `measure().surfaceTokens` by construction rather than by a relation worth
+ * observing at runtime.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * Pure client-safe token-projection vocabulary.
+ *
+ * @module @xrkseek/xrk-token-meter/projection
+ */
+/**
+ * Durable cumulative provider usage for a complete session log.
+ *
+ * The four buckets are disjoint. In particular, reasoning tokens are already
+ * included in `outputTokens` and are not accumulated again.
+ */
+export interface TokenUsageProjection {
+    uncachedInputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/**
+ * Approximate context occupancy for a status display.
+ *
+ * The fields, when present, are deliberately NOT one atomic request
+ * observation: each is a last-wins record of a different moment. Switching
+ * models can therefore pair a fresh capacity with the previous route's
+ * pressure until the next request reports usage. This is an intentional trade
+ * — the value is a user-facing reference, not a billing or gating input. See
+ * the token-meter README for the full rationale.
+ */
+export interface ContextPressureProjection {
+    /**
+     * Provider-reported prompt size of the most recent request: uncached input
+     * plus cache reads and writes. Response output is excluded, so this does not
+     * grow as the current turn streams. Absent until a provider reports usage.
+     */
+    pressureTokens?: number;
+    /**
+     * What the NEXT request's prompt would cost: {@link pressureTokens} plus the
+     * heuristic repricing of everything the surface gained or lost since that
+     * sample. Only the delta is estimated, so the figure stays anchored to the
+     * provider while still reacting the moment a compaction shadows a span —
+     * which `pressureTokens` alone cannot do, since compaction reports no usage
+     * of its own. Absent until a provider reports usage.
+     */
+    projectedTokens?: number;
+    /** Newest recorded route capacity; absent when no adapter advertised one. */
+    contextWindow?: number;
+}
+/**
+ * Heuristic composition of the next request's context: what the prompt is
+ * made of, not what it costs. All three figures use the meter's fixed
+ * density estimate, so they will not sum to the provider-anchored
+ * `projectedTokens`: the estimator systematically underprices CJK text and
+ * JSON schemas, which is exactly the error the anchoring in
+ * {@link ContextPressureProjection.projectedTokens} keeps out of the occupancy
+ * figure. Present these as approximations of composition, never as a total.
+ */
+export interface ContextBreakdownProjection {
+    /** Heuristic tokens of the newest request envelope's system prompt; 0 before any request. */
+    systemTokens: number;
+    /** Heuristic tokens of the newest request envelope's tool schemas; 0 before any request. */
+    toolsTokens: number;
+    /** Heuristic tokens of the current model-visible conversation surface. */
+    messageTokens: number;
+}
+declare module '@xrkseek/xrk-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Provider-reported usage accumulated across the complete durable log. */
+        tokenUsage: TokenUsageProjection;
+        /** Newest request pressure paired with the newest known route capacity. */
+        contextPressure: ContextPressureProjection;
+        /** Heuristic system/tools/message composition of the next request. */
+        contextBreakdown: ContextBreakdownProjection;
+    }
+}
+//# sourceMappingURL=projection.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * Pure client-safe token-projection vocabulary.
+ *
+ * @module @xrkseek/xrk-token-meter/projection
+ */
+export {};
+//# sourceMappingURL=projection.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * The measurement service's positional surface fold: the per-node priced
+ * surface `measure()` serves and compaction plans against. The projection
+ * units deliberately do NOT share this fold — their state must stay O(1)
+ * for the persisted checkpoint, so they ride `surface-projection.ts`'s
+ * shadow-price protocol instead. Fully metered logs stay in agreement by
+ * construction: both price through `estimate.ts`, and every logged shadow
+ * price is derived from THIS fold's nodes by the replace producer. A
+ * projection replacement without a claim deliberately folds with zero delta.
+ *
+ * @module @xrkseek/xrk-token-meter/surface-fold
+ */
+import type { SurfaceEvent } from '@xrkseek/xrk-session';
+import type { TokenSurfaceNode } from './types.ts';
+/** One surface event's placement and cost against the surface preceding it. */
+export interface SurfaceTokenFold {
+    /** Heuristic price of the event's own message; 0 when it derives none. */
+    readonly tokens: number;
+    /** The surface after the event, detached from the input. */
+    readonly nodes: TokenSurfaceNode[];
+    /** Signed change in the surface total: `tokens` minus anything shadowed. */
+    readonly deltaTokens: number;
+}
+/**
+ * Fold one surface event onto a priced surface.
+ *
+ * Total and allocation-fresh: the caller assigns the result rather than
+ * mutating in place, so a throw here leaves the caller's state untouched and
+ * the same malformed event fails identically on every retry.
+ * @param nodes - the priced surface preceding this event, in model-visible order.
+ * @param event - the surface event to place.
+ * @returns the event's price, the next surface, and the signed total delta.
+ * @throws when a replacement names a range absent from `nodes` — committed
+ *   logs are surface-validated at append time, so an unresolvable range is log
+ *   corruption and must fail loud rather than skip the event.
+ */
+export declare function foldSurfaceTokens(nodes: readonly TokenSurfaceNode[], event: SurfaceEvent): SurfaceTokenFold;
+//# sourceMappingURL=surface-fold.d.ts.map

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

@@ -0,0 +1,47 @@
+/**
+ * The measurement service's positional surface fold: the per-node priced
+ * surface `measure()` serves and compaction plans against. The projection
+ * units deliberately do NOT share this fold — their state must stay O(1)
+ * for the persisted checkpoint, so they ride `surface-projection.ts`'s
+ * shadow-price protocol instead. Fully metered logs stay in agreement by
+ * construction: both price through `estimate.ts`, and every logged shadow
+ * price is derived from THIS fold's nodes by the replace producer. A
+ * projection replacement without a claim deliberately folds with zero delta.
+ *
+ * @module @xrkseek/xrk-token-meter/surface-fold
+ */
+import { deriveEventMessage } from '@xrkseek/xrk-session';
+import { estimateMessage } from "./estimate.js";
+/**
+ * Fold one surface event onto a priced surface.
+ *
+ * Total and allocation-fresh: the caller assigns the result rather than
+ * mutating in place, so a throw here leaves the caller's state untouched and
+ * the same malformed event fails identically on every retry.
+ * @param nodes - the priced surface preceding this event, in model-visible order.
+ * @param event - the surface event to place.
+ * @returns the event's price, the next surface, and the signed total delta.
+ * @throws when a replacement names a range absent from `nodes` — committed
+ *   logs are surface-validated at append time, so an unresolvable range is log
+ *   corruption and must fail loud rather than skip the event.
+ */
+export function foldSurfaceTokens(nodes, event) {
+    const message = deriveEventMessage(event);
+    const tokens = message === null ? 0 : estimateMessage(message);
+    const op = event.surfaceOp;
+    if (op === 'append') {
+        return { tokens, nodes: [...nodes, { seq: event.seq, tokens }], deltaTokens: tokens };
+    }
+    const startIdx = nodes.findIndex(node => node.seq === op.start);
+    const endIdx = nodes.findIndex(node => node.seq === op.end);
+    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+        throw new Error(`token surface: replace at seq ${event.seq} has invalid current range ${op.start}-${op.end}`);
+    }
+    const removed = nodes
+        .slice(startIdx, endIdx + 1)
+        .reduce((total, node) => total + node.tokens, 0);
+    const next = [...nodes];
+    next.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, tokens });
+    return { tokens, nodes: next, deltaTokens: tokens - removed };
+}
+//# sourceMappingURL=surface-fold.js.map