@trazum/core 1.65.0 → 1.67.0

package/dist/judgement.js

@@ -0,0 +1,188 @@
+/**
+ * One policy, judged once — the function every door calls.
+ *
+ * The `limits` block states the policy: per-day, per-session and per-label
+ * USD ceilings. This module answers whether a proposed call fits it, and the
+ * design constraint is the 1.62 arc's lesson: **two doors to the same value
+ * agreeing by coincidence is a defect waiting for its input.** So the doors
+ * — the gateway's 402, `serve`'s cost answer, `spend_guard` over MCP — do
+ * not each read a slice of config and do their own arithmetic. They hand
+ * this function the policy, the measured position and the call, and forward
+ * its answer.
+ *
+ * Nothing here re-derives the single-ceiling semantics either. Each ceiling
+ * is judged by `answerCost`, the function that has answered "does this call
+ * fit this budget" for every door since 1.44 — including its refusals: a
+ * negative token count is rejected before it can become money, an unpriced
+ * model is a cannot-tell rather than a guess, and a verdict always names
+ * whether it rests on a measurement alone or needed the estimate. A policy
+ * judgement is those answers, one per applicable ceiling, under one verdict.
+ *
+ * Two refusals are this module's own, and both close the same loophole: a
+ * policy with per-label ceilings judging a call that names no label, or a
+ * per-session ceiling judging a call that names no session, is `cannot-tell`
+ * — not "no ceiling applies". A call that omits its label does not slip past
+ * the label's ceiling; it becomes unjudgeable, and the answer says why.
+ */
+import { answerCost } from './answer.js';
+import { formatUsd } from './savings.js';
+const judgementOf = (scope, label, limitUsd, answer) => ({
+    scope,
+    label,
+    limitUsd,
+    verdict: answer.verdict,
+    restsOn: answer.restsOn,
+    // The single-ceiling reasons map one-to-one; the two call-shape refusals
+    // (`no-label-on-call`, `no-session-on-call`) never reach answerCost.
+    reason: answer.reason === null ? null : answer.reason === 'model-unpriced' ? 'model-unpriced' : 'nothing-measured',
+    measuredUsd: answer.budget?.consumedUsd ?? null,
+    window: answer.budget?.window ?? null,
+    afterCallUsd: answer.afterCall?.usd ?? null,
+    waived: null,
+});
+const unjudgeable = (scope, label, limitUsd, reason) => ({
+    scope,
+    label,
+    limitUsd,
+    verdict: 'cannot-tell',
+    restsOn: null,
+    reason,
+    measuredUsd: null,
+    window: null,
+    afterCallUsd: null,
+    waived: null,
+});
+/** The waiver gate that names one judgement's ceiling. */
+const gateOf = (judgement) => judgement.scope === 'day'
+    ? 'limits.dayUsd'
+    : judgement.scope === 'session'
+        ? 'limits.sessionUsd'
+        : `limits.byLabel:${judgement.label ?? ''}`;
+/**
+ * The unexpired waiver for one judgement, if the config carries one.
+ *
+ * Judged in UTC at run time, the same rule `check` applies: the day the
+ * waiver expires, the ceiling refuses again — nobody has to remember.
+ */
+const waiverFor = (judgement, waivers, on) => {
+    const today = on.toISOString().slice(0, 10);
+    const match = waivers.find((entry) => entry.gate === gateOf(judgement) && entry.until >= today);
+    return match === undefined ? null : { reason: match.reason, until: match.until };
+};
+/**
+ * Judges a proposed call against the whole `limits` policy.
+ *
+ * Pure and synchronous for the same reason `answerCost` is: this runs inside
+ * a request that has not been sent yet, and a function that reads a file
+ * cannot promise single-digit milliseconds. The caller measures; this judges.
+ */
+export function judgeLimits(policy, position, call, options) {
+    const judgements = [];
+    const judge = (consumedUsd, limitUsd, window) => answerCost({
+        model: call.model,
+        inputTokens: call.inputTokens,
+        outputTokens: call.outputTokens,
+        basis: call.basis,
+        limitUsd,
+        consumedUsd: consumedUsd ?? undefined,
+        window,
+    }, options);
+    if (policy?.dayUsd !== undefined) {
+        judgements.push(judgementOf('day', null, policy.dayUsd, judge(position.dayUsd, policy.dayUsd, position.dayWindow ?? null)));
+    }
+    if (policy?.sessionUsd !== undefined) {
+        judgements.push(call.session === undefined
+            ? unjudgeable('session', null, policy.sessionUsd, 'no-session-on-call')
+            : judgementOf('session', null, policy.sessionUsd, judge(position.sessionUsd, policy.sessionUsd, position.sessionWindow ?? null)));
+    }
+    if (policy?.byLabel !== undefined && Object.keys(policy.byLabel).length > 0) {
+        if (call.label === undefined) {
+            /*
+              The loophole this closes: per-label ceilings with an unlabelled call.
+              Skipping the scope would mean the ceiling only binds calls polite
+              enough to name themselves — the same defect as the negative token
+              count, worn as an omission. One judgement, no label, cannot-tell.
+              The ceiling reported is the smallest, because that is the one the
+              call might be dodging.
+            */
+            const smallest = Math.min(...Object.values(policy.byLabel));
+            judgements.push(unjudgeable('label', null, smallest, 'no-label-on-call'));
+        }
+        else if (policy.byLabel[call.label] !== undefined) {
+            const limitUsd = policy.byLabel[call.label];
+            judgements.push(judgementOf('label', call.label, limitUsd, judge(position.labelUsd, limitUsd, position.labelWindow ?? null)));
+        }
+        // A labelled call whose label has no ceiling is judged by the other
+        // scopes alone: the policy said nothing about this label, and inventing
+        // a ceiling for it would be enforcing config nobody wrote.
+    }
+    if (judgements.length === 0) {
+        return { schemaVersion: 1, verdict: 'cannot-tell', reason: 'no-policy', judgements: [] };
+    }
+    /**
+     * Waivers, applied after every ceiling is judged: the measurement stays —
+     * a waived judgement still says `over` — but the silence is attached, on
+     * the record, and the verdict below treats a waived `over` as not-refusing.
+     */
+    const { on = new Date(), waivers = [] } = options;
+    if (waivers.length > 0) {
+        for (const judgement of judgements) {
+            if (judgement.verdict === 'over')
+                judgement.waived = waiverFor(judgement, waivers, on);
+        }
+    }
+    const verdict = judgements.some((entry) => entry.verdict === 'over' && entry.waived === null)
+        ? 'over'
+        : judgements.some((entry) => entry.verdict === 'cannot-tell')
+            ? 'cannot-tell'
+            : 'within';
+    return { schemaVersion: 1, verdict, reason: null, judgements };
+}
+/** The scope, as a refusal names it. Labels print; session identifiers never do. */
+export function limitScopeName(judgement) {
+    return judgement.scope === 'day'
+        ? "the day's ceiling"
+        : judgement.scope === 'session'
+            ? "this session's ceiling"
+            : judgement.label === null
+                ? 'the per-label ceiling'
+                : `the "${judgement.label}" label's ceiling`;
+}
+/** The period a measured figure covers, when the judgement carries one. */
+function periodOf(judgement) {
+    if (judgement.window === null)
+        return '';
+    const from = new Date(judgement.window.fromMs).toISOString();
+    const to = new Date(judgement.window.toMs).toISOString();
+    return ` between ${from} and ${to}`;
+}
+/**
+ * The refusal, legible — chapter four's rule, written once.
+ *
+ * Every over-limit sentence names the limit, the measured position and the
+ * period, so an agent can log it and a person can audit it without
+ * re-running anything. Every door uses this builder rather than composing
+ * its own, for the same reason every door uses the same judge.
+ */
+export function limitSentence(judgement) {
+    const limit = formatUsd(judgement.limitUsd);
+    const measured = judgement.measuredUsd === null ? 'nothing measured' : `${formatUsd(judgement.measuredUsd)} measured`;
+    return judgement.restsOn === 'measured'
+        ? `${capital(limitScopeName(judgement))} of ${limit} is already spent: ${measured}${periodOf(judgement)}.`
+        : `This call would take ${limitScopeName(judgement)} of ${limit} past its limit: ${measured}${periodOf(judgement)}, plus this call's estimate.`;
+}
+/** Why the policy could not be judged, in one auditable sentence. */
+export function unjudgedSentence(judged) {
+    const first = judged.judgements.find((entry) => entry.verdict === 'cannot-tell');
+    const which = first === undefined ? 'a ceiling' : limitScopeName(first);
+    const why = first?.reason === 'no-label-on-call'
+        ? 'the call names no label'
+        : first?.reason === 'no-session-on-call'
+            ? 'the call names no session'
+            : first?.reason === 'model-unpriced'
+                ? 'the model is not in the price catalogue'
+                : 'its spend has not been measured';
+    return `${capital(which)} in the limits policy cannot be judged: ${why}.`;
+}
+const capital = (text) => `${text[0].toUpperCase()}${text.slice(1)}`;
+//# sourceMappingURL=judgement.js.map

package/dist/judgement.js.map

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

package/dist/position-report.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The month, ended on a measured position — the 1.67 arc's one answer.
+ *
+ * The product refuses to forecast, and that refusal stays. But "refuses to
+ * forecast" and "cannot say where the month stands" are different sentences:
+ * the measured burn, the days measured, and the arithmetic distance to each
+ * configured ceiling are all measurements — and before this module they were
+ * scattered across `profile`, `budgetPositions` and `watch` rather than
+ * answerable as one question.
+ *
+ * **One source, named.** Everything here is measured from a usage log — the
+ * record of what was called, priced record by record. The store's monthly
+ * standing (provider-billed buckets, the number `serve` and `store` report)
+ * is a different measurement of a different thing, and folding the two into
+ * one figure would be the two-doors defect with extra steps. The document
+ * says `source: "usage-log"` so no reader has to guess which this is.
+ *
+ * **The distance is division, labelled as division.** "At this measured
+ * rate, the limit is N days away" is `remaining ÷ (measured ÷ days
+ * measured)` — arithmetic on the past, stated with its own denominators. It
+ * is absent, not zeroed, when the rate stands on fewer measured days than
+ * `MIN_SCALE_DAYS`, the same floor every scaled figure in this product
+ * respects; absent when nothing was measured; and absent on an `over`,
+ * because the distance to a place you have already passed is not a number
+ * this tool prints. There is no field naming a date, here or anywhere.
+ */
+import type { BudgetPeriod } from './budget.js';
+import type { UsageRecord } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { LimitsConfig, SpendConfig } from './config-schema.js';
+/** What a position is measured against, and over which window. */
+export type PositionScope = 'month' | 'day' | 'label';
+export interface PositionDistance {
+    /** `remainingUsd ÷ usdPerDay`. Division on the past, not a prediction. */
+    daysAway: number;
+    /** The measured rate: month-to-date spend over the days that measured it. */
+    usdPerDay: number;
+    /** The denominator of the rate — how many measured days stand behind it. */
+    overDays: number;
+    /** Always `division`: what this number is, stated in the number. */
+    arithmetic: 'division';
+}
+export interface PositionStanding {
+    scope: PositionScope;
+    /** Which label, when the scope is `label`. Null otherwise. */
+    label: string | null;
+    limitUsd: number;
+    /** Priced from the log's own records. Never an estimate. */
+    measuredUsd: number;
+    remainingUsd: number;
+    /** The window the measured figure covers. */
+    window: {
+        fromMs: number;
+        toMs: number;
+    };
+    /** Distinct UTC days inside the window carrying any measurement. */
+    daysMeasured: number;
+    /** Days of the window already elapsed when this was computed. */
+    daysElapsed: number;
+    verdict: 'within' | 'over' | 'cannot-tell';
+    /**
+     * Present only when it means something: a `within` verdict standing on at
+     * least `MIN_SCALE_DAYS` measured days and a non-zero rate. Null is "this
+     * arithmetic would mislead", never "we forgot".
+     */
+    distance: PositionDistance | null;
+}
+/** A configured ceiling this log cannot measure, with the reason stated. */
+export interface UnmeasuredPosition {
+    scope: PositionScope;
+    label: string | null;
+    limitUsd: number;
+    why: 'no-clock' | 'no-labels' | 'nothing-recorded' | 'label-unseen';
+}
+export interface PositionDocument {
+    schemaVersion: 1;
+    /** Where every figure below was measured from. */
+    source: 'usage-log';
+    month: BudgetPeriod;
+    positions: PositionStanding[];
+    /** Configured ceilings the log cannot answer for, each with the reason. */
+    unmeasured: UnmeasuredPosition[];
+    /**
+     * What this document deliberately does not answer, stated rather than
+     * implied. The per-session ceiling is judged per call at the doors — a
+     * session is not a calendar scope, and a "session position for the month"
+     * would be an average wearing a limit's name.
+     */
+    cannotSay: string[];
+    /** Records whose model the catalogue cannot price — money nobody can see. */
+    unpricedRecords: number;
+}
+/**
+ * The position, measured from one parsed usage log.
+ *
+ * Pure over its inputs, like `judgeLimits` and for the same reason: the
+ * same function answers at the CLI, in the HTML door and over MCP, so the
+ * surfaces cannot disagree about where the month stands.
+ */
+export declare function positionReport(records: readonly UsageRecord[], config: {
+    spend?: SpendConfig;
+    limits?: LimitsConfig;
+}, options: {
+    catalogue: PricingCatalogue;
+    on?: Date;
+}): PositionDocument;
+//# sourceMappingURL=position-report.d.ts.map

package/dist/position-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-report.d.ts","sourceRoot":"","sources":["../src/position-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIpE,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACnC;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,UAAU,GAAG,WAAW,GAAG,kBAAkB,GAAG,cAAc,CAAC;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,kDAAkD;IAClD,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,2EAA2E;IAC3E,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAE,EACtD,OAAO,EAAE;IAAE,SAAS,EAAE,gBAAgB,CAAC;IAAC,EAAE,CAAC,EAAE,IAAI,CAAA;CAAE,GAClD,gBAAgB,CA4JlB"}

package/dist/position-report.js

@@ -0,0 +1,180 @@
+/**
+ * The month, ended on a measured position — the 1.67 arc's one answer.
+ *
+ * The product refuses to forecast, and that refusal stays. But "refuses to
+ * forecast" and "cannot say where the month stands" are different sentences:
+ * the measured burn, the days measured, and the arithmetic distance to each
+ * configured ceiling are all measurements — and before this module they were
+ * scattered across `profile`, `budgetPositions` and `watch` rather than
+ * answerable as one question.
+ *
+ * **One source, named.** Everything here is measured from a usage log — the
+ * record of what was called, priced record by record. The store's monthly
+ * standing (provider-billed buckets, the number `serve` and `store` report)
+ * is a different measurement of a different thing, and folding the two into
+ * one figure would be the two-doors defect with extra steps. The document
+ * says `source: "usage-log"` so no reader has to guess which this is.
+ *
+ * **The distance is division, labelled as division.** "At this measured
+ * rate, the limit is N days away" is `remaining ÷ (measured ÷ days
+ * measured)` — arithmetic on the past, stated with its own denominators. It
+ * is absent, not zeroed, when the rate stands on fewer measured days than
+ * `MIN_SCALE_DAYS`, the same floor every scaled figure in this product
+ * respects; absent when nothing was measured; and absent on an `over`,
+ * because the distance to a place you have already passed is not a number
+ * this tool prints. There is no field naming a date, here or anywhere.
+ */
+import { monthOf } from './budget.js';
+import { MIN_SCALE_DAYS } from './measured-profile.js';
+import { costOf } from './session-cost.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const daysIn = (stamps) => {
+    const days = new Set();
+    for (const ms of stamps)
+        days.add(new Date(ms).toISOString().slice(0, 10));
+    return days.size;
+};
+/**
+ * The position, measured from one parsed usage log.
+ *
+ * Pure over its inputs, like `judgeLimits` and for the same reason: the
+ * same function answers at the CLI, in the HTML door and over MCP, so the
+ * surfaces cannot disagree about where the month stands.
+ */
+export function positionReport(records, config, options) {
+    const { catalogue, on = new Date() } = options;
+    const month = monthOf(on);
+    const dayFromMs = Math.floor(on.getTime() / DAY_MS) * DAY_MS;
+    const dayWindow = { fromMs: dayFromMs, toMs: dayFromMs + DAY_MS };
+    const monthWindow = { fromMs: month.fromMs, toMs: month.toMs };
+    const elapsedDays = Math.max(1, Math.min(month.days, Math.ceil((on.getTime() - month.fromMs) / DAY_MS)));
+    let unpricedRecords = 0;
+    let clocksSeen = false;
+    let labelsSeen = false;
+    let monthUsd = 0;
+    let dayUsd = 0;
+    const monthDays = new Set();
+    const labelUsd = new Map();
+    const labelDays = new Map();
+    for (const record of records) {
+        if (record.ts !== null)
+            clocksSeen = true;
+        if (record.label !== null)
+            labelsSeen = true;
+        const usd = costOf(record, catalogue, on);
+        if (usd === null) {
+            unpricedRecords += 1;
+            continue;
+        }
+        if (record.ts === null)
+            continue; // a clockless record belongs to no window
+        const day = Math.floor(record.ts / DAY_MS) * DAY_MS;
+        if (record.ts >= month.fromMs && record.ts < month.toMs) {
+            monthUsd += usd;
+            monthDays.add(day);
+            if (record.label !== null) {
+                labelUsd.set(record.label, (labelUsd.get(record.label) ?? 0) + usd);
+                if (!labelDays.has(record.label))
+                    labelDays.set(record.label, new Set());
+                labelDays.get(record.label).add(day);
+            }
+        }
+        if (record.ts >= dayWindow.fromMs && record.ts < dayWindow.toMs)
+            dayUsd += usd;
+    }
+    const positions = [];
+    const unmeasured = [];
+    const standing = (scope, label, limitUsd, measuredUsd, window, daysMeasured, daysElapsed, measured) => {
+        const verdict = !measured ? 'cannot-tell' : measuredUsd > limitUsd ? 'over' : 'within';
+        const usdPerDay = daysMeasured > 0 ? measuredUsd / daysMeasured : 0;
+        const distance = verdict === 'within' && daysMeasured >= MIN_SCALE_DAYS && usdPerDay > 0
+            ? {
+                daysAway: (limitUsd - measuredUsd) / usdPerDay,
+                usdPerDay,
+                overDays: daysMeasured,
+                arithmetic: 'division',
+            }
+            : null;
+        return {
+            scope,
+            label,
+            limitUsd,
+            measuredUsd,
+            remainingUsd: limitUsd - measuredUsd,
+            window,
+            daysMeasured,
+            daysElapsed,
+            verdict,
+            distance,
+        };
+    };
+    const monthly = config.spend?.monthlyUsd;
+    if (monthly !== undefined) {
+        if (!clocksSeen) {
+            unmeasured.push({ scope: 'month', label: null, limitUsd: monthly, why: records.length === 0 ? 'nothing-recorded' : 'no-clock' });
+        }
+        else {
+            /**
+             * A month with zero measured days is a stale log, not a quiet month:
+             * `budgetPositions` has held that line since 1.49 ("coverage none is
+             * cannot-tell"), and this module agreeing with it is the point of the
+             * arc. Contrast the day scope below, deliberately.
+             */
+            positions.push(standing('month', null, monthly, monthUsd, monthWindow, monthDays.size, elapsedDays, monthDays.size > 0));
+        }
+    }
+    const day = config.limits?.dayUsd;
+    if (day !== undefined) {
+        if (!clocksSeen) {
+            unmeasured.push({ scope: 'day', label: null, limitUsd: day, why: records.length === 0 ? 'nothing-recorded' : 'no-clock' });
+        }
+        else {
+            /**
+             * A day with no records inside a log that records clocks is a quiet
+             * day, measured at $0 — the same reading `positionAt` gives the doors,
+             * because a position page and an enforcement door disagreeing about
+             * today's spend is the exact defect the 1.66 arc closed. And one day
+             * is one day: the distance arithmetic needs a multi-day rate, so a
+             * day position never carries a `distance` — always under the floor.
+             */
+            positions.push(standing('day', null, day, dayUsd, dayWindow, monthDays.has(dayFromMs) ? 1 : 0, 1, true));
+        }
+    }
+    for (const [label, limitUsd] of Object.entries(config.limits?.byLabel ?? {})) {
+        if (!clocksSeen || !labelsSeen) {
+            unmeasured.push({
+                scope: 'label',
+                label,
+                limitUsd,
+                why: records.length === 0 ? 'nothing-recorded' : !clocksSeen ? 'no-clock' : 'no-labels',
+            });
+        }
+        else if (!labelUsd.has(label)) {
+            // The log records labels and has never seen this one this month. That
+            // is a measured empty history — but a position of $0 with no days
+            // behind it would print the healthiest possible line for a label that
+            // may simply have been renamed, so it is named instead.
+            unmeasured.push({ scope: 'label', label, limitUsd, why: 'label-unseen' });
+        }
+        else {
+            positions.push(standing('label', label, limitUsd, labelUsd.get(label), monthWindow, daysIn(labelDays.get(label)), elapsedDays, true));
+        }
+    }
+    const cannotSay = [];
+    if (config.limits?.sessionUsd !== undefined) {
+        cannotSay.push('limits.sessionUsd is judged per call at the doors. A session is not a calendar scope, and a "session position for the month" would be an average wearing a limit\'s name.');
+    }
+    if (monthly === undefined && config.limits?.dayUsd === undefined && Object.keys(config.limits?.byLabel ?? {}).length === 0) {
+        cannotSay.push('No monthly budget and no limits are configured, so there is no ceiling to state a position against. spend.monthlyUsd and the limits block are where ceilings live.');
+    }
+    return {
+        schemaVersion: 1,
+        source: 'usage-log',
+        month,
+        positions,
+        unmeasured,
+        cannotSay,
+        unpricedRecords,
+    };
+}
+//# sourceMappingURL=position-report.js.map

package/dist/position-report.js.map

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

package/dist/position.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The measured side of the limits policy: what a usage log says each scope
+ * has already spent.
+ *
+ * `judgeLimits` judges; this measures. The split is the product's oldest
+ * rule — the judging function must be pure and instant, so whatever reads
+ * and prices records happens once, here, and the doors keep the result.
+ *
+ * **Absence is `null`, never zero.** A log with no clock cannot say what
+ * today has cost; a log that records no sessions cannot say what a session
+ * has spent. Both come back `null`, and `judgeLimits` turns a `null` into
+ * `cannot-tell` rather than an approval. The one deliberate asymmetry: a log
+ * that *does* record sessions and has never seen this one answers `0` — the
+ * history of a conversation that has not started is complete and empty,
+ * which is a measurement, not an absence.
+ *
+ * **Session keys never leave this module.** The index groups by them — that
+ * is the whole job — but the map lives in door memory, `positionAt` returns
+ * only dollar figures, and nothing here is serialised. The guarantee the
+ * usage module states (a session key is somebody's conversation and is never
+ * printed) holds through this door too.
+ */
+import type { UsageRecord } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { MeasuredPosition } from './judgement.js';
+/**
+ * Everything a door needs to answer `positionAt` in constant time, built
+ * once from the log it was pointed at.
+ */
+export interface MeasuredIndex {
+    /** Spend inside the current UTC day. Null when no record carries a clock. */
+    dayUsd: number | null;
+    /** The UTC day the figure covers. Null exactly when `dayUsd` is. */
+    dayWindow: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    /** Whether any record carried a label / a session at all. */
+    labelsSeen: boolean;
+    sessionsSeen: boolean;
+    /** Priced spend per label. Keys are labels, which do print. */
+    labels: ReadonlyMap<string, number>;
+    /** Priced spend per session. Keys are session identifiers — never printed. */
+    sessions: ReadonlyMap<string, number>;
+    /** Whether the log held any records at all. */
+    any: boolean;
+    /** Records whose model the catalogue cannot price — money nobody can see. */
+    unpriced: number;
+}
+/**
+ * Prices and groups a parsed usage log, once.
+ *
+ * An unpriced record contributes nothing to any figure and is **counted**
+ * instead of dropped silently: a door that reports "measured $3" over a log
+ * with a thousand unpriced records is wrong by an amount nobody can see, in
+ * the flattering direction, and `unpriced` is how the door says so.
+ */
+export declare function indexUsage(records: readonly UsageRecord[], options: {
+    catalogue: PricingCatalogue;
+    on?: Date;
+}): MeasuredIndex;
+/**
+ * The measured position for one proposed call, from an index built once.
+ *
+ * A scope the log cannot see is `null`; a scope it can see and has nothing
+ * recorded for is `0`. The difference is the difference between "unknown"
+ * and "a conversation that has not started yet", and collapsing them is how
+ * a dead log approves a live spend.
+ */
+export declare function positionAt(index: MeasuredIndex, call: {
+    label?: string;
+    session?: string;
+}): MeasuredPosition;
+//# sourceMappingURL=position.d.ts.map

package/dist/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../src/position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oEAAoE;IACpE,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,+CAA+C;IAC/C,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE;IAAE,SAAS,EAAE,gBAAgB,CAAC;IAAC,EAAE,CAAC,EAAE,IAAI,CAAA;CAAE,GAClD,aAAa,CAsCf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,gBAAgB,CAWlB"}