harnery 0.35.0 → 0.36.0

package/dist/core/semantic/soak.js

@@ -0,0 +1,476 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { coordEnv } from "../../lib/env.js";
+import { createStorageCatalog } from "../storage/catalog.js";
+import { parseLogRecord } from "../storage/jsonl.js";
+import { familyLogDirectory, readSegmentManifest } from "../storage/segments.js";
+import { SEMANTIC_CONFIGURED_MODELS, SEMANTIC_EXPRESSION_CUES, SEMANTIC_HARNESSES, SEMANTIC_PHASES, } from "./contract.js";
+import { readSemanticServiceStatus } from "./service-status.js";
+import { readSemanticAgentDocument, semanticPaths } from "./storage.js";
+import { emptySemanticUsageAggregate, mergeSemanticUsageAggregates, } from "./usage.js";
+export const SEMANTIC_SOAK_SCHEMA_VERSION = 1;
+export const SEMANTIC_SOAK_DEFAULT_MINUTES = 60;
+export const SEMANTIC_SOAK_REVERSAL_WINDOW_MS = 10 * 60_000;
+const MAX_LOG_BYTES = 512 * 1024;
+const MAX_LOG_RECORDS = 10_000;
+const SUBJECT_DIGEST_LENGTH = 16;
+/**
+ * Project accepted pass outcomes into bounded log tokens. No task text, model
+ * prose, event IDs, instance IDs, or generation IDs cross this boundary.
+ */
+export function semanticSoakReadings(coordRootRaw, outcomes) {
+    const coordRoot = resolve(coordRootRaw);
+    return outcomes.flatMap((outcome) => {
+        if (outcome.action !== "accepted" && outcome.action !== "cached")
+            return [];
+        const document = readSemanticAgentDocument(coordRoot, outcome.generation_id);
+        if (document?.reader_outcome !== "accepted")
+            return [];
+        const cue = document.meaning.expression_cue;
+        return [
+            {
+                subject_id: semanticSubjectId(outcome.generation_id),
+                generated_at: document.generated_at,
+                source_harness: document.reader.harness,
+                configured_model: document.reader.configured_model,
+                ...(document.reader.resolved_model_id
+                    ? { resolved_model_id: document.reader.resolved_model_id }
+                    : {}),
+                ...(document.reader.model_attestation
+                    ? { model_attestation: document.reader.model_attestation }
+                    : {}),
+                origin: outcome.action === "cached" ? "cache" : "model-call",
+                phase: document.meaning.phase.value,
+                phase_confidence: document.meaning.phase.confidence,
+                ...(cue
+                    ? {
+                        expression_cue: cue.value,
+                        expression_confidence: cue.confidence,
+                    }
+                    : {}),
+            },
+        ];
+    });
+}
+export function readSemanticSoakReport(coordRootRaw, options = {}) {
+    const coordRoot = resolve(coordRootRaw);
+    const minutes = positiveMinutes(options.minutes ?? SEMANTIC_SOAK_DEFAULT_MINUTES);
+    const now = options.now ?? new Date();
+    const endedAt = now.toISOString();
+    const requestedStart = new Date(now.getTime() - minutes * 60_000).toISOString();
+    const entries = readSemanticServiceLog(coordRoot);
+    const timestamped = entries.filter((entry) => validTimestamp(entry.ts));
+    const passEntries = timestamped.filter((entry) => entry.event === "pass" && entry.ts >= requestedStart && entry.ts <= endedAt);
+    const usage = passEntries.reduce((total, entry) => isSemanticUsageAggregate(entry.usage)
+        ? mergeSemanticUsageAggregates(total, entry.usage)
+        : total, emptySemanticUsageAggregate());
+    const readings = passEntries.flatMap((entry) => Array.isArray(entry.semantic_readings)
+        ? entry.semantic_readings
+            .filter(isSemanticSoakReading)
+            .map((reading) => ({ captured_at: entry.ts, reading }))
+        : []);
+    const accepted = readings.filter(({ reading }) => reading.origin === "model-call");
+    const cached = readings.filter(({ reading }) => reading.origin === "cache");
+    const omittedReadings = passEntries.reduce((total, entry) => total + (entry.semantic_readings_omitted ?? 0), 0);
+    const service = readSemanticServiceStatus(coordRoot);
+    const availableFrom = timestamped[0]?.ts;
+    const availableThrough = timestamped.at(-1)?.ts;
+    return {
+        schema_version: SEMANTIC_SOAK_SCHEMA_VERSION,
+        generated_at: endedAt,
+        window: {
+            requested_minutes: minutes,
+            requested_start_at: requestedStart,
+            ended_at: endedAt,
+            ...(availableFrom ? { available_from: availableFrom } : {}),
+            ...(availableThrough ? { available_through: availableThrough } : {}),
+            window_complete: availableFrom !== undefined && availableFrom <= requestedStart,
+        },
+        service: { running: service.running, stale: service.stale },
+        coverage: {
+            pass_count: passEntries.length,
+            instrumented_pass_count: passEntries.filter((entry) => Array.isArray(entry.semantic_readings))
+                .length,
+            legacy_pass_count: passEntries.filter((entry) => !Array.isArray(entry.semantic_readings))
+                .length,
+            accepted_reading_count: accepted.length,
+            cached_reading_count: cached.length,
+        },
+        outcomes: usage.outcomes,
+        usage,
+        readings: summarizeReadings(accepted),
+        stability: summarizeStability(accepted),
+        limitations: [
+            ...(omittedReadings > 0
+                ? [`${omittedReadings} semantic readings were omitted at bounded log element boundaries.`]
+                : []),
+            "Expression frequency counts accepted model readings, not on-screen dwell time.",
+            "Cue transitions can reflect real work changes; rapid reversals are review candidates, not proven flicker.",
+            "Inference correctness requires labeled review and is not computed by this report.",
+        ],
+    };
+}
+function summarizeReadings(readings) {
+    const phaseCounts = {};
+    const expressionCounts = {};
+    const confidenceCounts = {};
+    const byHarness = {};
+    for (const { reading } of readings) {
+        increment(phaseCounts, reading.phase);
+        increment(expressionCounts, reading.expression_cue ?? "abstained");
+        if (reading.expression_confidence)
+            increment(confidenceCounts, reading.expression_confidence);
+        increment(byHarness, reading.source_harness);
+    }
+    return {
+        phase_counts: phaseCounts,
+        expression_counts: expressionCounts,
+        expression_confidence_counts: confidenceCounts,
+        by_harness: byHarness,
+    };
+}
+function summarizeStability(readings) {
+    const bySubject = new Map();
+    for (const item of readings) {
+        const subject = bySubject.get(item.reading.subject_id) ?? [];
+        subject.push(item);
+        bySubject.set(item.reading.subject_id, subject);
+    }
+    let repeatedSubjects = 0;
+    let adjacentComparisons = 0;
+    let unchangedCues = 0;
+    let cueChanges = 0;
+    let rapidReversals = 0;
+    const transitions = new Map();
+    for (const subjectReadings of bySubject.values()) {
+        subjectReadings.sort((left, right) => left.captured_at.localeCompare(right.captured_at));
+        if (subjectReadings.length > 1)
+            repeatedSubjects += 1;
+        for (let index = 1; index < subjectReadings.length; index += 1) {
+            adjacentComparisons += 1;
+            const from = cueOf(subjectReadings[index - 1].reading);
+            const to = cueOf(subjectReadings[index].reading);
+            if (from === to) {
+                unchangedCues += 1;
+            }
+            else {
+                cueChanges += 1;
+                const key = `${from}\u0000${to}`;
+                const current = transitions.get(key) ?? { from, to, count: 0 };
+                current.count += 1;
+                transitions.set(key, current);
+            }
+            if (index < 2)
+                continue;
+            const earlier = subjectReadings[index - 2];
+            const middle = subjectReadings[index - 1];
+            const latest = subjectReadings[index];
+            if (cueOf(earlier.reading) === cueOf(latest.reading) &&
+                cueOf(earlier.reading) !== cueOf(middle.reading) &&
+                Date.parse(latest.captured_at) - Date.parse(earlier.captured_at) <=
+                    SEMANTIC_SOAK_REVERSAL_WINDOW_MS) {
+                rapidReversals += 1;
+            }
+        }
+    }
+    return {
+        subject_count: bySubject.size,
+        subjects_with_repeat_observations: repeatedSubjects,
+        adjacent_comparisons: adjacentComparisons,
+        unchanged_cues: unchangedCues,
+        cue_changes: cueChanges,
+        rapid_reversals: rapidReversals,
+        ...(adjacentComparisons > 0
+            ? { stable_repeat_rate: Number((unchangedCues / adjacentComparisons).toFixed(3)) }
+            : {}),
+        transitions: [...transitions.values()].sort((left, right) => right.count - left.count ||
+            `${left.from}/${left.to}`.localeCompare(`${right.from}/${right.to}`)),
+    };
+}
+function readSemanticServiceLog(coordRoot) {
+    if (coordEnv("SHARED_LOGS") === "0") {
+        return readLegacySemanticServiceLog(coordRoot, MAX_LOG_BYTES).entries;
+    }
+    let shared = { entries: [], bytes: 0 };
+    try {
+        shared = readSharedSemanticServiceLog(coordRoot, MAX_LOG_BYTES, MAX_LOG_RECORDS);
+    }
+    catch {
+        // A racing or corrupt best-effort generation yields to bounded historical fallback.
+    }
+    const remainingBytes = Math.max(0, MAX_LOG_BYTES - shared.bytes);
+    const remainingRecords = Math.max(0, MAX_LOG_RECORDS - shared.entries.length);
+    const legacy = remainingBytes > 0 && remainingRecords > 0
+        ? readLegacySemanticServiceLog(coordRoot, remainingBytes, remainingRecords).entries
+        : [];
+    return mergeSemanticServiceEntries(shared.entries, legacy);
+}
+function readSharedSemanticServiceLog(coordRoot, maxBytes, maxRecords) {
+    const family = createStorageCatalog({ coord_root: coordRoot }).require("semantic-service-log");
+    const directory = familyLogDirectory(family);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const manifest = readSegmentManifest(directory, family);
+        const generation = manifestGeneration(manifest);
+        const sources = [
+            ...manifest.segments.map((segment) => ({ path: join(directory, segment.file), gzip: true })),
+            { path: join(directory, "active.jsonl"), gzip: false },
+        ];
+        const entries = [];
+        let bytes = 0;
+        for (const source of sources) {
+            if (!existsSync(source.path) || bytes >= maxBytes || entries.length >= maxRecords)
+                continue;
+            let read;
+            try {
+                read = readBoundedLogSource(source.path, source.gzip, maxBytes - bytes);
+            }
+            catch {
+                continue;
+            }
+            bytes += read.bytes;
+            for (const line of completeLines(read.body)) {
+                if (entries.length >= maxRecords)
+                    break;
+                try {
+                    const entry = sharedRecordToEntry(parseLogRecord(line));
+                    if (entry)
+                        entries.push(entry);
+                }
+                catch {
+                    // Malformed or partial best-effort records are skipped without widening the budget.
+                }
+            }
+        }
+        const after = readSegmentManifest(directory, family);
+        if (manifestGeneration(after) === generation)
+            return { entries, bytes };
+    }
+    return { entries: [], bytes: 0 };
+}
+function readLegacySemanticServiceLog(coordRoot, maxBytes, maxRecords = MAX_LOG_RECORDS) {
+    const path = semanticPaths(coordRoot).log;
+    if (!existsSync(path) || maxBytes <= 0 || maxRecords <= 0)
+        return { entries: [], bytes: 0 };
+    const size = statSync(path).size;
+    if (size <= 0 || size > maxBytes)
+        return { entries: [], bytes: 0 };
+    const body = readFileSync(path, "utf8");
+    const entries = body
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const value = JSON.parse(line);
+            return isLogEntry(value) ? [value] : [];
+        }
+        catch {
+            return [];
+        }
+    })
+        .slice(0, maxRecords);
+    return { entries, bytes: Buffer.byteLength(body) };
+}
+function sharedRecordToEntry(record) {
+    if (record.family_id !== "semantic-service-log")
+        return undefined;
+    const usage = parseJsonField(record.fields.usage);
+    const semanticReadings = parseJsonField(record.fields.semantic_readings);
+    return {
+        ts: record.emitted_at,
+        event: record.event,
+        ...(nonNegativeInteger(record.fields.model_calls) !== undefined
+            ? { model_calls: record.fields.model_calls }
+            : {}),
+        ...(nonNegativeInteger(record.fields.cache_hits) !== undefined
+            ? { cache_hits: record.fields.cache_hits }
+            : {}),
+        ...(isSemanticUsageAggregate(usage) ? { usage } : {}),
+        ...(Array.isArray(semanticReadings)
+            ? { semantic_readings: semanticReadings.filter(isSemanticSoakReading) }
+            : {}),
+        ...(record.fields.semantic_readings_truncated === true
+            ? { semantic_readings_truncated: true }
+            : {}),
+        ...(nonNegativeInteger(record.fields.semantic_readings_omitted) !== undefined
+            ? { semantic_readings_omitted: record.fields.semantic_readings_omitted }
+            : {}),
+    };
+}
+function mergeSemanticServiceEntries(shared, legacy) {
+    const merged = new Map();
+    for (const entry of shared)
+        merged.set(logEntryIdentity(entry), entry);
+    for (const entry of legacy) {
+        const identity = logEntryIdentity(entry);
+        if (!merged.has(identity))
+            merged.set(identity, entry);
+    }
+    return [...merged.entries()]
+        .sort(([leftIdentity, left], [rightIdentity, right]) => left.ts.localeCompare(right.ts) || leftIdentity.localeCompare(rightIdentity))
+        .map(([, entry]) => entry);
+}
+function logEntryIdentity(entry) {
+    return createHash("sha256")
+        .update(stableJson([
+        entry.ts,
+        entry.event,
+        entry.model_calls ?? null,
+        entry.cache_hits ?? null,
+        entry.usage ?? null,
+        entry.semantic_readings ?? null,
+        entry.semantic_readings_truncated ?? false,
+        entry.semantic_readings_omitted ?? 0,
+    ]))
+        .digest("hex");
+}
+function readBoundedLogSource(path, gzip, maxBytes) {
+    if (maxBytes <= 0)
+        return { body: "", bytes: 0 };
+    const size = statSync(path).size;
+    if (size <= 0)
+        return { body: "", bytes: 0 };
+    if (gzip) {
+        if (size > maxBytes)
+            return { body: "", bytes: maxBytes };
+        try {
+            const body = gunzipSync(readFileSync(path), { maxOutputLength: maxBytes });
+            return { body: body.toString("utf8"), bytes: body.byteLength };
+        }
+        catch {
+            return { body: "", bytes: maxBytes };
+        }
+    }
+    const buffer = Buffer.allocUnsafe(Math.min(size, maxBytes));
+    const descriptor = openSync(path, "r");
+    try {
+        const bytes = readSync(descriptor, buffer, 0, buffer.byteLength, 0);
+        return { body: buffer.subarray(0, bytes).toString("utf8"), bytes };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function completeLines(body) {
+    const lastNewline = body.lastIndexOf("\n");
+    return lastNewline < 0 ? [] : body.slice(0, lastNewline).split("\n").filter(Boolean);
+}
+function parseJsonField(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function manifestGeneration(manifest) {
+    return JSON.stringify([
+        manifest.next_sequence,
+        manifest.segments.map((segment) => [segment.file, segment.sha256]),
+    ]);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function semanticSubjectId(generationId) {
+    return `subject_${createHash("sha256").update(generationId).digest("hex").slice(0, SUBJECT_DIGEST_LENGTH)}`;
+}
+function cueOf(reading) {
+    return reading.expression_cue ?? "abstained";
+}
+function increment(target, key) {
+    target[key] = (target[key] ?? 0) + 1;
+}
+function positiveMinutes(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error("minutes must be a positive integer");
+    }
+    return value;
+}
+function isLogEntry(value) {
+    if (!objectValue(value))
+        return false;
+    const row = value;
+    return typeof row.ts === "string" && typeof row.event === "string";
+}
+function isSemanticUsageAggregate(value) {
+    const row = objectValue(value);
+    return (!!row &&
+        nonNegativeInteger(row.call_count) !== undefined &&
+        nonNegativeInteger(row.unreported_calls) !== undefined &&
+        isUsageOutcomes(row.outcomes) &&
+        isTokenTotals(row.native_tokens) &&
+        isTokenTotals(row.estimated_tokens) &&
+        Array.isArray(row.breakdowns) &&
+        row.breakdowns.every(isUsageBreakdown));
+}
+function isSemanticSoakReading(value) {
+    const row = objectValue(value);
+    return (!!row &&
+        typeof row.subject_id === "string" &&
+        /^subject_[a-f0-9]{16}$/.test(row.subject_id) &&
+        validTimestamp(row.generated_at) &&
+        (row.origin === "model-call" || row.origin === "cache") &&
+        member(SEMANTIC_HARNESSES, row.source_harness) &&
+        member(SEMANTIC_CONFIGURED_MODELS, row.configured_model) &&
+        member(SEMANTIC_PHASES, row.phase) &&
+        confidence(row.phase_confidence) &&
+        (row.expression_cue === undefined || member(SEMANTIC_EXPRESSION_CUES, row.expression_cue)) &&
+        (row.expression_confidence === undefined || confidence(row.expression_confidence)));
+}
+function isUsageOutcomes(value) {
+    const row = objectValue(value);
+    return (!!row &&
+        ["accepted", "invalid", "unavailable", "deferred"].every((key) => nonNegativeInteger(row[key]) !== undefined));
+}
+function isTokenTotals(value) {
+    const row = objectValue(value);
+    if (!row)
+        return false;
+    return Object.entries(row).every(([key, count]) => [
+        "input_tokens",
+        "cached_input_tokens",
+        "cache_creation_input_tokens",
+        "output_tokens",
+        "reasoning_tokens",
+        "total_tokens",
+    ].includes(key) && nonNegativeInteger(count) !== undefined);
+}
+function isUsageBreakdown(value) {
+    const row = objectValue(value);
+    return (!!row &&
+        nonNegativeInteger(row.call_count) !== undefined &&
+        nonNegativeInteger(row.unreported_calls) !== undefined &&
+        isUsageOutcomes(row.outcomes) &&
+        isTokenTotals(row.native_tokens) &&
+        isTokenTotals(row.estimated_tokens) &&
+        !!objectValue(row.invalid_reasons));
+}
+function objectValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function member(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+function confidence(value) {
+    return value === "high" || value === "medium" || value === "low";
+}

package/dist/core/semantic/storage.d.ts

@@ -1,5 +1,5 @@
 import type { LedgerCursorV3 } from "../events/v3/reader.js";
-import { SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_PROMPT_CONTRACT_VERSION, type SemanticAgentReadModelV2, type SemanticConfiguredModel, type SemanticHarness } from "./contract.js";
+import type { SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_PROMPT_CONTRACT_VERSION, SemanticAgentReadModelV2, SemanticConfiguredModel, SemanticHarness, SemanticInvalidReasonCode, SemanticUsageReceiptV1 } from "./contract.js";
 export declare const SEMANTIC_MANIFEST_SCHEMA_VERSION: 2;
 export interface SemanticReaderResolution {
     harness: SemanticHarness;
@@ -19,6 +19,16 @@ export interface SemanticPendingItem {
 export interface SemanticCallReceipt {
     generation_id: string;
     started_at: string;
+    source_harness?: SemanticHarness;
+    configured_model?: SemanticConfiguredModel;
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    outcome?: "accepted" | "invalid" | "unavailable";
+    invalid_reason_codes?: SemanticInvalidReasonCode[];
+    duration_ms?: number;
+    input_bytes?: number;
+    output_bytes?: number;
+    usage?: SemanticUsageReceiptV1;
 }
 export interface SemanticManifestV2 {
     schema_version: typeof SEMANTIC_MANIFEST_SCHEMA_VERSION;

package/dist/core/semantic/storage.d.ts.map

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

package/dist/core/semantic/storage.js

@@ -2,7 +2,6 @@ import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.js";
-import { SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_PROMPT_CONTRACT_VERSION, } from "./contract.js";
 import { validateSemanticReadModel } from "./validate.js";
 export const SEMANTIC_MANIFEST_SCHEMA_VERSION = 2;
 const MAX_JSON_BYTES = 512 * 1024;
@@ -51,8 +50,10 @@ export function readSemanticManifest(coordRootRaw) {
         return undefined;
     const value = readBoundedJson(path, "semantic manifest");
     if (value.schema_version !== SEMANTIC_MANIFEST_SCHEMA_VERSION ||
-        value.evidence_contract_version !== SEMANTIC_EVIDENCE_CONTRACT_VERSION ||
-        value.prompt_contract_version !== SEMANTIC_PROMPT_CONTRACT_VERSION ||
+        !Number.isSafeInteger(value.evidence_contract_version) ||
+        value.evidence_contract_version < 1 ||
+        !Number.isSafeInteger(value.prompt_contract_version) ||
+        value.prompt_contract_version < 1 ||
         !Array.isArray(value.pending) ||
         !Array.isArray(value.call_history)) {
         throw new Error("semantic manifest has an unsupported schema");

package/dist/core/semantic/usage.d.ts

@@ -0,0 +1,43 @@
+import { type SemanticConfiguredModel, type SemanticHarness, type SemanticInvalidReasonCode, type SemanticUsageReceiptV1 } from "./contract.js";
+export declare const SEMANTIC_USAGE_TOKEN_FIELDS: readonly ["input_tokens", "cached_input_tokens", "cache_creation_input_tokens", "output_tokens", "reasoning_tokens", "total_tokens"];
+export type SemanticUsageTokenField = (typeof SEMANTIC_USAGE_TOKEN_FIELDS)[number];
+export type SemanticUsageTokenTotals = Partial<Record<SemanticUsageTokenField, number>>;
+export type SemanticUsageOutcome = "accepted" | "invalid" | "unavailable" | "deferred";
+export interface SemanticUsageEvent {
+    source_harness?: SemanticHarness;
+    configured_model?: SemanticConfiguredModel;
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    action?: string;
+    model_call: boolean;
+    usage?: SemanticUsageReceiptV1;
+    invalid_reason_codes?: SemanticInvalidReasonCode[];
+}
+export interface SemanticUsageBreakdown {
+    harness?: SemanticHarness;
+    configured_model?: SemanticConfiguredModel;
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    call_count: number;
+    outcomes: Record<SemanticUsageOutcome, number>;
+    invalid_reasons: Partial<Record<SemanticInvalidReasonCode, number>>;
+    native_tokens: SemanticUsageTokenTotals;
+    estimated_tokens: SemanticUsageTokenTotals;
+    unreported_calls: number;
+}
+export interface SemanticUsageAggregate {
+    call_count: number;
+    outcomes: Record<SemanticUsageOutcome, number>;
+    invalid_reasons: Partial<Record<SemanticInvalidReasonCode, number>>;
+    native_tokens: SemanticUsageTokenTotals;
+    estimated_tokens: SemanticUsageTokenTotals;
+    unreported_calls: number;
+    breakdowns: SemanticUsageBreakdown[];
+}
+export declare function nativeSemanticUsage(values: Partial<Record<SemanticUsageTokenField, unknown>>): SemanticUsageReceiptV1 | undefined;
+export declare function estimateVisibleSemanticUsage(prompt: string, response: string): SemanticUsageReceiptV1;
+export declare function unreportedSemanticUsage(): SemanticUsageReceiptV1;
+export declare function aggregateSemanticUsage(events: readonly SemanticUsageEvent[]): SemanticUsageAggregate;
+export declare function mergeSemanticUsageAggregates(left: SemanticUsageAggregate, right: SemanticUsageAggregate): SemanticUsageAggregate;
+export declare function emptySemanticUsageAggregate(): SemanticUsageAggregate;
+//# sourceMappingURL=usage.d.ts.map

package/dist/core/semantic/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/usage.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAE5B,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,2BAA2B,sIAO9B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AACnF,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAC;AACxF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,oBAAoB,CAAC,EAAE,yBAAyB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAC/C,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,aAAa,EAAE,wBAAwB,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAC/C,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,aAAa,EAAE,wBAAwB,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC,GACxD,sBAAsB,GAAG,SAAS,CAapC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,sBAAsB,CAiBxB;AAED,wBAAgB,uBAAuB,IAAI,sBAAsB,CAMhE;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GACpC,sBAAsB,CA4CxB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,sBAAsB,EAC5B,KAAK,EAAE,sBAAsB,GAC5B,sBAAsB,CAqCxB;AAED,wBAAgB,2BAA2B,IAAI,sBAAsB,CAUpE"}