agentfootprint 10.3.0 → 10.3.1

package/dist/esm/core/agent/receipt/receiptDigests.d.ts

@@ -0,0 +1,123 @@
+/**
+ * receiptDigests — what a run's receipts have already hashed, so each piece of
+ * a request is hashed ONCE per run instead of once per call.
+ *
+ * Role:  Memo. A plain data structure the receipt mint (`receipt.ts` ·
+ *        `buildReceipt`) reads and fills; it hashes nothing itself, reads no
+ *        scope and emits nothing.
+ * Reads: what the mint hands it.
+ * Emits: N/A.
+ *
+ * ── WHY IT EXISTS ───────────────────────────────────────────────────────────
+ * An agent's request at call k is the request at call k−1 plus what the loop
+ * appended — and the mint used to hash every message of it again, on every
+ * call. Measured on an agent run with 1,000-row tool results: SHA-256 input
+ * grew with the square of the iteration count, and the mint was the largest
+ * single cost of the run (63% of its CPU at 40 iterations, under a caching
+ * provider). The digests themselves never needed to change: a receipt's hashes
+ * are functions of the bytes, so a message hashed at call 3 has the same hash
+ * at call 30. This keeps them.
+ *
+ * ── THE TWO LOOKUPS ─────────────────────────────────────────────────────────
+ *   BY PREIMAGE  `hash(preimage)` — the salted hashes of the per-call pieces
+ *                that are not messages (system text, system pieces, tool
+ *                schemas), keyed by the exact string that was hashed. Exact by
+ *                construction: a hash is a function of its preimage, so a hit
+ *                returns what recomputing would return.
+ *   BY OBJECT    `message(m)` — what was derived from one message OBJECT: its
+ *                entry hash, its transform-chain digest, whether it serializes,
+ *                and its request measurement (`requestMeasurement.ts`), so a
+ *                message the run has already seen costs no string building at
+ *                all. It keeps DIGESTS and counts, never a copy of the message's
+ *                text — a 1,000-row tool result is not held twice. Valid only while
+ *                the object's own fields are the values they were: every field
+ *                is compared by identity on each hit, and a mismatch derives
+ *                again. Committed state is never edited in place (footprintjs's
+ *                immutable-after-swap law), so a hit is the common case — the
+ *                agent's history hands the mint the same message objects call
+ *                after call.
+ *
+ * ── WHAT IT DOES NOT CHANGE ─────────────────────────────────────────────────
+ * Every hash a receipt carries is the hash it carried before this memo existed:
+ * same preimage, same salt, same digest. A receipt minted with the memo and one
+ * minted without it are byte-identical, and so is the request measurement —
+ * pinned by test/core/agent/receipt/receipt-incremental.test.ts.
+ *
+ * The one assumption a hit makes: a message's NESTED values (`toolCalls`,
+ * `args`, `thinkingBlocks`) are not edited in place while the message object
+ * is reused. The agent's history is committed state, which is never edited in
+ * place; a caller that hands the mint its own objects and then mutates one
+ * deep inside must hand a new object instead.
+ *
+ * ── LIFETIME ────────────────────────────────────────────────────────────────
+ * One memo per run, bound to the run id (the salt). `forRun` hands back the
+ * current run's memo, and a different run id starts a fresh one — so a reused
+ * agent never carries one run's strings into the next.
+ *
+ * Within a run, the two string memos (BY PREIMAGE, and the transform chain's
+ * links) keep TWO CALLS' worth — the call being minted and the one before it.
+ * Each `forRun` is one mint, and it rotates them. A piece that repeats from one
+ * call to the next (a system prompt, a tool schema, the chain's prefix) is
+ * found; a piece that changes every call (a system prompt with the time in it)
+ * is not kept past the next call. What the memo holds is bounded by two
+ * requests' worth — their non-message pieces and one chain link per message —
+ * never by how many calls the run made. The BY OBJECT memo is weak — it lives
+ * as long as the message objects do.
+ *
+ * ── TOTAL ───────────────────────────────────────────────────────────────────
+ * A receipt is bookkeeping and must never stop a run. A message whose fields
+ * cannot be read (a throwing getter on an object a caller handed in) is not
+ * memoized: `message()` hands back a fresh, unkept record and the mint derives
+ * everything from the message as it would with no memo at all.
+ */
+import type { MessageMeasure, MessageMeasureCache } from './requestMeasurement.js';
+/** What one message object has already been turned into. */
+export interface MessageDigests {
+    /** `messageDigestInput(m)` hashed — the receipt's `messages.entries[].hash`. */
+    entryHash?: string;
+    /**
+     * Whether `stableJson([m])` — the message as one array element — produced a
+     * value. Read by the cache comparison, which is `'unknown'` when a message
+     * cannot be serialized.
+     */
+    serializable?: boolean;
+    /** `H(stableJson([m]) ?? UNSERIALIZABLE)` — the transform chain's digest of
+     *  this message (`receipt.ts` · `transformHashOf`). Kept as the digest, never
+     *  as the JSON, so the memo holds no copy of a message's text. */
+    elementDigest?: string;
+    /** The message as `measureRequest` measured it at a request's
+     *  `messages[i]` (`requestMeasurement.ts` · `MessageMeasure`). */
+    measure?: MessageMeasure;
+}
+/** One run's memo. */
+export interface RunDigests extends MessageMeasureCache {
+    /** The run id every hash in this memo is salted with. */
+    readonly runId: string;
+    /** The salted hash of `preimage`, computed by `compute` the first time only. */
+    hash(preimage: string, compute: () => string): string;
+    /** What has been derived from `message` while its fields are unchanged. */
+    message(message: object): MessageDigests;
+    /** The chain link after `previous` and `digest` — see `receipt.ts` ·
+     *  `transformHashOf`. Computed by `compute` the first time only. */
+    link(previous: string, digest: string, compute: () => string): string;
+    /** @internal Strings the two string memos hold right now — pinned by
+     *  test/core/agent/receipt/receipt-incremental.test.ts (bounded by two calls). */
+    retained(): number;
+}
+/**
+ * A memo the receipt mint keeps across the calls of a run. Create one per
+ * agent; it rebinds itself when the run id changes.
+ *
+ * @example
+ * ```ts
+ * const digests = createReceiptDigests();
+ * buildReceipt(callOne, digests);   // hashes every piece
+ * buildReceipt(callTwo, digests);   // hashes only what call two added
+ * ```
+ */
+export interface ReceiptDigests {
+    /** The memo for `runId` — the current one, or a fresh one for a new run. */
+    forRun(runId: string): RunDigests;
+}
+/** Start an empty memo. See {@link ReceiptDigests}. */
+export declare function createReceiptDigests(): ReceiptDigests;

package/dist/esm/core/agent/receipt/receiptDigests.js

@@ -0,0 +1,166 @@
+/**
+ * receiptDigests — what a run's receipts have already hashed, so each piece of
+ * a request is hashed ONCE per run instead of once per call.
+ *
+ * Role:  Memo. A plain data structure the receipt mint (`receipt.ts` ·
+ *        `buildReceipt`) reads and fills; it hashes nothing itself, reads no
+ *        scope and emits nothing.
+ * Reads: what the mint hands it.
+ * Emits: N/A.
+ *
+ * ── WHY IT EXISTS ───────────────────────────────────────────────────────────
+ * An agent's request at call k is the request at call k−1 plus what the loop
+ * appended — and the mint used to hash every message of it again, on every
+ * call. Measured on an agent run with 1,000-row tool results: SHA-256 input
+ * grew with the square of the iteration count, and the mint was the largest
+ * single cost of the run (63% of its CPU at 40 iterations, under a caching
+ * provider). The digests themselves never needed to change: a receipt's hashes
+ * are functions of the bytes, so a message hashed at call 3 has the same hash
+ * at call 30. This keeps them.
+ *
+ * ── THE TWO LOOKUPS ─────────────────────────────────────────────────────────
+ *   BY PREIMAGE  `hash(preimage)` — the salted hashes of the per-call pieces
+ *                that are not messages (system text, system pieces, tool
+ *                schemas), keyed by the exact string that was hashed. Exact by
+ *                construction: a hash is a function of its preimage, so a hit
+ *                returns what recomputing would return.
+ *   BY OBJECT    `message(m)` — what was derived from one message OBJECT: its
+ *                entry hash, its transform-chain digest, whether it serializes,
+ *                and its request measurement (`requestMeasurement.ts`), so a
+ *                message the run has already seen costs no string building at
+ *                all. It keeps DIGESTS and counts, never a copy of the message's
+ *                text — a 1,000-row tool result is not held twice. Valid only while
+ *                the object's own fields are the values they were: every field
+ *                is compared by identity on each hit, and a mismatch derives
+ *                again. Committed state is never edited in place (footprintjs's
+ *                immutable-after-swap law), so a hit is the common case — the
+ *                agent's history hands the mint the same message objects call
+ *                after call.
+ *
+ * ── WHAT IT DOES NOT CHANGE ─────────────────────────────────────────────────
+ * Every hash a receipt carries is the hash it carried before this memo existed:
+ * same preimage, same salt, same digest. A receipt minted with the memo and one
+ * minted without it are byte-identical, and so is the request measurement —
+ * pinned by test/core/agent/receipt/receipt-incremental.test.ts.
+ *
+ * The one assumption a hit makes: a message's NESTED values (`toolCalls`,
+ * `args`, `thinkingBlocks`) are not edited in place while the message object
+ * is reused. The agent's history is committed state, which is never edited in
+ * place; a caller that hands the mint its own objects and then mutates one
+ * deep inside must hand a new object instead.
+ *
+ * ── LIFETIME ────────────────────────────────────────────────────────────────
+ * One memo per run, bound to the run id (the salt). `forRun` hands back the
+ * current run's memo, and a different run id starts a fresh one — so a reused
+ * agent never carries one run's strings into the next.
+ *
+ * Within a run, the two string memos (BY PREIMAGE, and the transform chain's
+ * links) keep TWO CALLS' worth — the call being minted and the one before it.
+ * Each `forRun` is one mint, and it rotates them. A piece that repeats from one
+ * call to the next (a system prompt, a tool schema, the chain's prefix) is
+ * found; a piece that changes every call (a system prompt with the time in it)
+ * is not kept past the next call. What the memo holds is bounded by two
+ * requests' worth — their non-message pieces and one chain link per message —
+ * never by how many calls the run made. The BY OBJECT memo is weak — it lives
+ * as long as the message objects do.
+ *
+ * ── TOTAL ───────────────────────────────────────────────────────────────────
+ * A receipt is bookkeeping and must never stop a run. A message whose fields
+ * cannot be read (a throwing getter on an object a caller handed in) is not
+ * memoized: `message()` hands back a fresh, unkept record and the mint derives
+ * everything from the message as it would with no memo at all.
+ */
+// FOLD · the one owner of "already hashed this run": buildReceipt reads it, and
+// nothing else re-derives a receipt digest across calls
+// detached: no — it holds the message objects of the run as WeakMap keys (never
+// keeps them alive) and the preimage strings of the last two calls.
+/** Start an empty memo. See {@link ReceiptDigests}. */
+export function createReceiptDigests() {
+    let current;
+    return {
+        forRun(runId) {
+            if (current === undefined || current.runId !== runId)
+                current = runDigests(runId);
+            else
+                current.nextCall();
+            return current;
+        },
+    };
+}
+function runDigests(runId) {
+    const byPreimage = twoCalls();
+    const links = twoCalls();
+    const byObject = new WeakMap();
+    const message = (value) => {
+        try {
+            const keys = Object.keys(value);
+            const held = byObject.get(value);
+            if (held !== undefined && sameFields(held, value, keys))
+                return held.digests;
+            const entry = {
+                keys,
+                values: keys.map((key) => value[key]),
+                digests: {},
+            };
+            byObject.set(value, entry);
+            return entry.digests;
+        }
+        catch {
+            return {}; // unreadable: derive everything afresh, keep nothing (see TOTAL)
+        }
+    };
+    return {
+        runId,
+        hash: (preimage, compute) => byPreimage.get(preimage, compute),
+        message,
+        measureOf: (value) => message(value).measure,
+        keep: (value, measure) => {
+            message(value).measure = measure;
+        },
+        link: (previous, digest, compute) => links.get(`${previous}\u001F${digest}`, compute),
+        retained: () => byPreimage.size() + links.size(),
+        nextCall: () => {
+            byPreimage.rotate();
+            links.rotate();
+        },
+    };
+}
+/**
+ * A string memo that keeps the current call's entries and the previous call's,
+ * nothing older — see LIFETIME. A hit in the previous call's entries is carried
+ * into the current one.
+ */
+function twoCalls() {
+    let current = new Map();
+    let previous = new Map();
+    return {
+        get(key, compute) {
+            let value = current.get(key);
+            if (value === undefined) {
+                value = previous.get(key) ?? compute();
+                current.set(key, value);
+            }
+            return value;
+        },
+        rotate() {
+            previous = current;
+            current = new Map();
+        },
+        size: () => current.size + previous.size,
+    };
+}
+/** Are `message`'s own fields still exactly the values `held` saw? Identity per
+ *  field — a field that is a new object is a different field, even when equal. */
+function sameFields(held, message, keys) {
+    if (keys.length !== held.keys.length)
+        return false;
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (key !== held.keys[i])
+            return false;
+        if (message[key] !== held.values[i])
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=receiptDigests.js.map

package/dist/esm/core/agent/receipt/receiptDigests.js.map

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

package/dist/esm/core/agent/receipt/requestMeasurement.d.ts

@@ -0,0 +1,70 @@
+/** Counts only: the initial prepared request at the library's provider port.
+ * No token estimate, payload retention, retry total or vendor wire claim. */
+export interface RequestJsonSize {
+    /** UTF-16 code units in the JSON representation, including JSON punctuation. */
+    readonly jsonChars: number;
+    /** UTF-8 bytes in that same JSON representation. */
+    readonly jsonBytes: number;
+}
+type MeasurementBoundary = {
+    readonly boundary: 'initial-prepared-request';
+    readonly format: 'json-utf8-v1';
+};
+/** Sizes describe JSON of the canonical request, excluding its root `signal`.
+ * Slot values are serialized separately and do not sum to the request total.
+ * Missing slots were absent/undefined; an empty array still has JSON size. */
+export type RequestMeasurement = MeasurementBoundary & ({
+    readonly status: 'measured';
+    readonly total: RequestJsonSize;
+    readonly slots: {
+        readonly systemPrompt?: RequestJsonSize;
+        readonly messages?: RequestJsonSize;
+        readonly tools?: RequestJsonSize;
+    };
+} | {
+    readonly status: 'unavailable';
+    readonly reason: 'unsupported-value' | 'cyclic-value' | 'measurement-limit';
+});
+/**
+ * One message object as {@link measureRequest} measured it at a request's
+ * `messages[i]` — the counts its walk added and its JSON size, so a later call
+ * that hands the same message adds the counts instead of walking it again.
+ * Kept only for a walk that raised nothing (a value the walk refuses is walked
+ * again, and refused again, every call).
+ */
+export interface MessageMeasure {
+    /** Values the walk visited inside this message, the message included. */
+    readonly visited: number;
+    /** Characters the walk counted inside it (string values and keys). */
+    readonly chars: number;
+    /** The highest value-budget demand its walk made, relative to the count it
+     *  started from — `visited` plus the largest array/object it sized up front. */
+    readonly need: number;
+    /** Its JSON, as one array element: UTF-16 code units and UTF-8 bytes. */
+    readonly json: RequestJsonSize;
+}
+/** Where {@link measureRequest} keeps a message's measurement across the calls
+ *  of one run — the receipt memo (`receiptDigests.ts`) is the one owner. */
+export interface MessageMeasureCache {
+    measureOf(message: object): MessageMeasure | undefined;
+    keep(message: object, measure: MessageMeasure): void;
+}
+/** Internal receipt helper. Read plain data through descriptors so telemetry
+ * does not invoke getters or custom toJSON. Unsupported values fail open with
+ * a reason code, never exception text. Transport adapters remain authoritative
+ * for what they actually serialize; this helper does not validate requests.
+ *
+ * INCREMENTAL. The request's `messages` are measured one element at a time and
+ * the sizes composed (`[` + elements joined by `,` + `]`, spliced into the rest
+ * of the request) — JSON is compositional, so the sum IS the size of the whole.
+ * With a `cache`, a message object already measured this run adds its kept
+ * counts and size instead of being walked again: an agent's request at call k
+ * is call k−1's plus what the loop appended, and measuring it whole every call
+ * grew with the square of the iteration count. Every limit is checked against
+ * the same running counts as a whole walk, so the result — `measured` or the
+ * reason it is `unavailable` — is the one the whole walk gives; pinned by
+ * test/core/agent/receipt/receipt-incremental.test.ts. A cache hit assumes what
+ * the receipt memo assumes: the message's nested values were not edited in
+ * place (`receiptDigests.ts`). */
+export declare function measureRequest(request: unknown, cache?: MessageMeasureCache): RequestMeasurement;
+export {};

package/dist/esm/core/agent/receipt/requestMeasurement.js

@@ -0,0 +1,231 @@
+const boundary = {
+    boundary: 'initial-prepared-request',
+    format: 'json-utf8-v1',
+};
+const CYCLIC = Symbol('cyclic');
+const UNSUPPORTED = Symbol('unsupported');
+const LIMIT = Symbol('limit');
+const MAX_VALUES = 100_000;
+const MAX_CHARS = 4_000_000;
+const MAX_DEPTH = 64;
+/** Internal receipt helper. Read plain data through descriptors so telemetry
+ * does not invoke getters or custom toJSON. Unsupported values fail open with
+ * a reason code, never exception text. Transport adapters remain authoritative
+ * for what they actually serialize; this helper does not validate requests.
+ *
+ * INCREMENTAL. The request's `messages` are measured one element at a time and
+ * the sizes composed (`[` + elements joined by `,` + `]`, spliced into the rest
+ * of the request) — JSON is compositional, so the sum IS the size of the whole.
+ * With a `cache`, a message object already measured this run adds its kept
+ * counts and size instead of being walked again: an agent's request at call k
+ * is call k−1's plus what the loop appended, and measuring it whole every call
+ * grew with the square of the iteration count. Every limit is checked against
+ * the same running counts as a whole walk, so the result — `measured` or the
+ * reason it is `unavailable` — is the one the whole walk gives; pinned by
+ * test/core/agent/receipt/receipt-incremental.test.ts. A cache hit assumes what
+ * the receipt memo assumes: the message's nested values were not edited in
+ * place (`receiptDigests.ts`). */
+export function measureRequest(request, cache) {
+    const active = new Set();
+    let visited = 0;
+    let chars = 0;
+    // The highest value-budget demand any check has made — what a kept message
+    // replays as `need` (every LIMIT check on values is `demand > MAX_VALUES`).
+    let peak = 0;
+    const demand = (amount) => {
+        if (amount > peak)
+            peak = amount;
+        if (amount > MAX_VALUES)
+            throw LIMIT;
+    };
+    const countChars = (length) => {
+        chars += length;
+        if (chars > MAX_CHARS)
+            throw LIMIT;
+    };
+    const copy = (value, depth = 0) => {
+        demand(++visited);
+        if (value === null || typeof value !== 'object') {
+            if (['bigint', 'function', 'symbol'].includes(typeof value))
+                throw UNSUPPORTED;
+            if (typeof value === 'string')
+                countChars(value.length);
+            return value;
+        }
+        if (active.has(value))
+            throw CYCLIC;
+        if (depth >= MAX_DEPTH)
+            throw LIMIT;
+        const array = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== (array ? Array.prototype : Object.prototype)) {
+            throw UNSUPPORTED;
+        }
+        if (Object.hasOwn(value, 'toJSON') ||
+            Object.hasOwn(Object.prototype, 'toJSON') ||
+            (array && Object.hasOwn(Array.prototype, 'toJSON')))
+            throw UNSUPPORTED;
+        active.add(value);
+        let result;
+        if (array) {
+            const items = [];
+            eachItem(value, (item) => items.push(copy(item, depth + 1)));
+            result = items;
+        }
+        else {
+            const keys = Object.getOwnPropertyNames(value);
+            demand(visited + keys.length);
+            const object = Object.create(null);
+            for (const key of keys) {
+                if (depth === 0 && key === 'signal')
+                    continue;
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor)
+                    throw UNSUPPORTED;
+                if (!descriptor.enumerable)
+                    continue;
+                if (!('value' in descriptor))
+                    throw UNSUPPORTED;
+                countChars(key.length);
+                object[key] =
+                    depth === 0 && key === 'messages' && Array.isArray(descriptor.value)
+                        ? copyMessages(descriptor.value)
+                        : copy(descriptor.value, depth + 1);
+            }
+            result = object;
+        }
+        active.delete(value);
+        return result;
+    };
+    /** Visit an array's elements as JSON reads them — length and holes checked
+     *  first, each index's descriptor checked just before its element is. */
+    const eachItem = (value, visit) => {
+        const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+        if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+            throw UNSUPPORTED;
+        demand(visited + length);
+        // JSON reads inherited indexed values at holes; we decline them rather
+        // than invoking accessors or silently measuring a different array.
+        if ([Array.prototype, Object.prototype].some((parent) => Object.getOwnPropertyNames(parent).some((key) => /^(0|[1-9]\d*)$/.test(key))))
+            throw UNSUPPORTED;
+        for (let i = 0; i < length; i++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+            if (descriptor && !('value' in descriptor))
+                throw UNSUPPORTED;
+            visit(descriptor?.value);
+        }
+        return length;
+    };
+    /** The request's `messages` (depth 1): walked like any array, but sized per
+     *  element and returned as their composed JSON size — see the header. */
+    const copyMessages = (value) => {
+        // `copy`'s own preamble for an array at depth 1.
+        demand(++visited);
+        if (active.has(value))
+            throw CYCLIC;
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== Array.prototype)
+            throw UNSUPPORTED;
+        if (Object.hasOwn(value, 'toJSON') ||
+            Object.hasOwn(Object.prototype, 'toJSON') ||
+            Object.hasOwn(Array.prototype, 'toJSON'))
+            throw UNSUPPORTED;
+        active.add(value);
+        let jsonChars = 0;
+        let jsonBytes = 0;
+        const length = eachItem(value, (item) => {
+            const size = messageSize(item);
+            jsonChars += size.jsonChars;
+            jsonBytes += size.jsonBytes;
+        });
+        // `[`, `]` and the commas between elements — one byte each.
+        const punctuation = 2 + Math.max(0, length - 1);
+        active.delete(value);
+        return new Composed({
+            jsonChars: jsonChars + punctuation,
+            jsonBytes: jsonBytes + punctuation,
+        });
+    };
+    /** One element of `messages` (depth 2): replayed from the cache, or walked. */
+    const messageSize = (item) => {
+        const cacheable = cache !== undefined && item !== null && typeof item === 'object';
+        const kept = cacheable ? cache.measureOf(item) : undefined;
+        if (kept !== undefined) {
+            demand(visited + kept.need);
+            visited += kept.visited;
+            countChars(kept.chars);
+            return kept.json;
+        }
+        const startVisited = visited;
+        const startChars = chars;
+        const outerPeak = peak;
+        peak = visited;
+        const json = jsonSizeOf(JSON.stringify(copy(item, 2)) ?? 'null');
+        const measure = {
+            visited: visited - startVisited,
+            chars: chars - startChars,
+            need: peak - startVisited,
+            json,
+        };
+        peak = Math.max(outerPeak, peak);
+        if (cacheable)
+            cache.keep(item, measure);
+        return measure.json;
+    };
+    try {
+        if (request === null || typeof request !== 'object' || Array.isArray(request))
+            throw UNSUPPORTED;
+        const snapshot = copy(request);
+        const size = (value) => {
+            if (value instanceof Composed)
+                return limited(value.size);
+            return limited(jsonSizeOf(JSON.stringify(value)));
+        };
+        const slots = {};
+        for (const key of ['systemPrompt', 'messages', 'tools']) {
+            if (snapshot[key] !== undefined)
+                slots[key] = size(snapshot[key]);
+        }
+        return { ...boundary, status: 'measured', total: size(totalOf(snapshot)), slots };
+    }
+    catch (error) {
+        return {
+            ...boundary,
+            status: 'unavailable',
+            reason: error === CYCLIC
+                ? 'cyclic-value'
+                : error === LIMIT
+                    ? 'measurement-limit'
+                    : 'unsupported-value',
+        };
+    }
+}
+/** The `messages` slot once measured: its JSON size, never its JSON. */
+class Composed {
+    size;
+    constructor(size) {
+        this.size = size;
+    }
+}
+/** The whole request's JSON size, with a composed `messages` spliced in: the
+ *  rest is serialized with `[]` in its place, and the two characters (and two
+ *  bytes) of `[]` are swapped for the slot's own size. */
+function totalOf(snapshot) {
+    const messages = snapshot.messages;
+    if (!(messages instanceof Composed))
+        return snapshot;
+    const rest = jsonSizeOf(JSON.stringify({ ...snapshot, messages: [] }));
+    return new Composed({
+        jsonChars: rest.jsonChars - 2 + messages.size.jsonChars,
+        jsonBytes: rest.jsonBytes - 2 + messages.size.jsonBytes,
+    });
+}
+function jsonSizeOf(json) {
+    return { jsonChars: json.length, jsonBytes: new TextEncoder().encode(json).byteLength };
+}
+function limited(size) {
+    if (size.jsonChars > MAX_CHARS)
+        throw LIMIT;
+    return size;
+}
+//# sourceMappingURL=requestMeasurement.js.map

package/dist/esm/core/agent/receipt/requestMeasurement.js.map

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

package/dist/esm/core/agent/repeatedCall.d.ts

@@ -51,7 +51,7 @@
  * value and so looked like new information each time.
  *
  * A tool that declares `repeatedWhen: 'arguments'` on itself (see
- * `Tool.repeatedWhen` in `core/tools.ts`) tells the ledger to fingerprint on
+ * `Tool.repeatedWhen` in `tools/tools.ts`) tells the ledger to fingerprint on
  * the ARGUMENTS ALONE — the result never enters the key, and the note's
  * wording changes to match (it cannot honestly say "returned exactly this
  * result" when the whole point is that the result is not being compared).

package/dist/esm/core/agent/repeatedCall.js

@@ -51,7 +51,7 @@
  * value and so looked like new information each time.
  *
  * A tool that declares `repeatedWhen: 'arguments'` on itself (see
- * `Tool.repeatedWhen` in `core/tools.ts`) tells the ledger to fingerprint on
+ * `Tool.repeatedWhen` in `tools/tools.ts`) tells the ledger to fingerprint on
  * the ARGUMENTS ALONE — the result never enters the key, and the note's
  * wording changes to match (it cannot honestly say "returned exactly this
  * result" when the whole point is that the result is not being compared).

package/dist/esm/core/agent/resultCeiling.d.ts

@@ -30,7 +30,7 @@
  * Emits: nothing itself (pure measurement); zero-cost-when-unused — no
  * declared ceiling means one `undefined` check and byte-identical behavior.
  */
-import type { ToolResultCeiling } from '../tools.js';
+import type { ToolResultCeiling } from '../../tools/tools.js';
 /** What an over-ceiling measurement hands the dispatch loop: the sentence the
  *  model reads and the true size for the record. `undefined` from
  *  {@link applyResultCeiling} means no ceiling or under it — untouched path. */

package/dist/esm/core/agent/results/subflow.d.ts

@@ -55,9 +55,9 @@
  * key to the inputs layer's row for the same call.
  */
 import type { TypedScope } from 'footprintjs';
-import { type DeclaredPeriod, type HeldSpan, type PeriodRow } from '../coverage/period.js';
-import { type PeriodCheckInput, type PeriodTimeCheck } from '../../time/check.js';
-import type { PeriodFacts, PeriodForm } from '../../time/convert.js';
+import { type DeclaredPeriod, type HeldSpan, type PeriodRow } from '../../../semantics/coverage/period.js';
+import { type PeriodCheckInput, type PeriodTimeCheck } from '../../../time/check.js';
+import type { PeriodFacts, PeriodForm } from '../../../time/convert.js';
 /** One call of the batch ToolCalls just ran — identities only. */
 export interface RanCall {
     readonly toolCallId: string;