@rulvar/core 1.20.0 → 1.21.0

package/dist/index.d.ts

@@ -656,7 +656,10 @@ interface PricedUsage {
 * The single pricing fold over one terminal entry, shared by the kernel
 * ledger and the CostReport fold so a run's total and its per-model
 * breakdown can never disagree. Each slice is priced at ITS OWN model's
-* rate.
+* rate. A price function returning NaN or a negative amount (a broken
+* user-supplied rate) is treated exactly like a missing row: the slice
+* folds as unpriced instead of poisoning or crediting the totals
+* (v1.20.0 review follow-up).
 */
 declare function priceEntryUsage(entry: JournalEntry, priceUsd: (servedBy: ModelRef, usage: Usage) => number | undefined): PricedUsage;
 /**
@@ -703,6 +706,21 @@ type JournalEntry = {
   * like usageByModel.
   */
   costAttribution?: CostAttributionFacts;
+  /**
+  * The serving adapters' declared usage-telemetry semantics at write
+  * time (ProviderAdapter.usageSemantics), stamped so cost numbers stay
+  * auditable across normalization corrections: an UNSTAMPED OpenAI
+  * entry with cacheWriteTokens > 0 may have been written by rulvar
+  * v1.19.0, whose adapter double-counted cache writes into inputTokens
+  * (v1.20.0 review P1/P2-2). The stamp unions every adapter that
+  * served a slice of the entry, distinct declarations joined with '+'
+  * in first-appearance order, so a mixed-adapter call whose primary
+  * declares nothing is still dated by its declaring slices. Absent
+  * only when NO serving adapter declares semantics, and on all entries
+  * written before this shipped. Policy, never identity, exactly like
+  * usageByModel.
+  */
+  usageSemantics?: string;
   transcriptRef?: string;
   checkpointRef?: string;
   /**
@@ -854,6 +872,51 @@ declare function maskSecretsDeep<T>(value: T): T;
 /** Convenience for hosts: masks a Json value (alias of the deep walk). */
 declare function maskSecretsJson(value: Json): Json;
 //#endregion
+//#region src/l0/usage.d.ts
+/**
+* Names every rule the given usage violates; an empty array means the
+* usage satisfies the full canonical invariant: each present count is a
+* finite nonnegative integer and
+* `cacheReadTokens + cacheWriteTokens <= inputTokens`. The subset rule
+* is checked with a negated comparison so a NaN operand counts as a
+* violation rather than vacuously passing.
+*/
+declare function usageViolations(usage: Usage): string[];
+/**
+* One count, repaired in the conservative direction: non-numbers and
+* non-finite values floor to zero (no evidence, no charge and no
+* credit), negatives floor to zero (a negative count can only CREDIT
+* the budget, which hostile telemetry must never do), and fractions
+* round UP so a repaired charge is never an undercharge.
+*/
+declare function sanitizeTokenCount(value: number | undefined): number;
+/**
+* One field read per property, returning a detached plain copy. Both
+* accounting boundaries validate and consume THIS snapshot, never the
+* adapter-owned object, so a hostile accessor cannot answer the
+* validator with valid counts and the accumulator with garbage.
+*/
+declare function snapshotUsage(usage: Usage): Usage;
+/**
+* The per-field repair for DELTAS (mid-stream usage reports and other
+* partial increments): each count is repaired like `sanitizeTokenCount`,
+* but the whole-usage subset rule is deliberately NOT applied, because a
+* delta legitimately carries cache counts without restating the full
+* input in the same event; clamping those to the subset rule would
+* silently drop a paid cache debit. Always returns a fresh object and
+* is the identity on valid deltas.
+*/
+declare function sanitizeUsageDelta(delta: Usage): Usage;
+/**
+* Conservative repair for accounting. Pairs with `usageViolations`: the
+* violation fails the call loud, and the sanitized numbers are the only
+* ones the journal, the cost report, and the budget may see. After the
+* per-field repair the cache subsets clamp into the input with reads
+* keeping priority, mirroring the adapter-level subset clamp. Valid
+* usage passes through structurally unchanged.
+*/
+declare function sanitizeUsage(usage: Usage): Usage;
+//#endregion
 //#region src/vendor/standard-schema.d.ts
 // Vendored from @standard-schema/spec@1.1.0 (MIT, Copyright (c) 2024 Colin
 // McDonnell), file dist/index.d.ts, byte-identical below this header.
@@ -1116,6 +1179,20 @@ interface ProviderAdapter {
   * family share retained blocks and projections; default = id.
   */
   provider?: string;
+  /**
+  * Declares WHICH reading of the provider's usage telemetry this
+  * adapter normalizes under; the engine stamps it on usage-bearing
+  * terminal entries so a journal records not only the numbers but the
+  * semantics they were produced under (v1.20.0 review P1/P2-2). Bump
+  * the string whenever the MEANING of a reported Usage field changes,
+  * even when no pricing rate moves; a rate change is a PriceTable
+  * pricingVersion bump instead. Entries persisted before this shipped
+  * carry no stamp, which is itself information: an unstamped OpenAI
+  * entry with cache writes may predate the v1.20.0 cache-subset
+  * correction. Optional; adapters that never changed semantics can
+  * omit it.
+  */
+  usageSemantics?: string;
   caps(model: string): ModelCaps;
   /** Refresh the capability table from live model lists. */
   refreshCaps?(): Promise<void>;
@@ -2130,6 +2207,8 @@ interface TerminalPatch {
   usageByModel?: UsageSlice[];
   /** Attribution facts behind the CostReport breakdowns; see JournalEntry. */
   costAttribution?: CostAttributionFacts;
+  /** The serving adapter's usage-semantics version; see JournalEntry. */
+  usageSemantics?: string;
   transcriptRef?: string;
   checkpointRef?: string;
   /** Terminal agent entries: Artifact list. */
@@ -3472,6 +3551,8 @@ declare class RunBudget {
   private exhaustedInternal;
   /** Models already warned about; the warning fires once per model per run. */
   private readonly unpricedWarned;
+  /** Models whose price function already returned an invalid USD once. */
+  private readonly invalidPriceWarned;
   constructor(options: {
     ceilingUsd?: number;
     lifetimeSpawnCap?: number;
@@ -6438,4 +6519,4 @@ interface SandboxBridge {
 }
 declare function createSandboxBridge(ctx: Ctx<never>, options: SandboxBridgeOptions): SandboxBridge;
 //#endregion
-export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, BUDGET_ABORT_REASON, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildIdentityInput, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DerivedKey, DeriverRegistry, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EntryKind, EntryRef, EntryStatus, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishInfo, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, InvocationRole, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_DEPTH_CEILING, MatchResult, McpConfig, MechanicalGateProfile, MechanicalGateVerdict, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateOptions, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PriceTable, PricedUsage, type Pricing, type PricingTier, type ProviderAdapter, QualityFloors, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RandIdentityInput, RandPayload, RefEntryAppender, RefEntryClassification, RefusalInfo, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStatus, RuntimeEventSink, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, Semaphore, SerializationHook, Settled, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateSchemaSpec, validateTerminationLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, BUDGET_ABORT_REASON, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildIdentityInput, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DerivedKey, DeriverRegistry, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EntryKind, EntryRef, EntryStatus, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishInfo, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, InvocationRole, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_DEPTH_CEILING, MatchResult, McpConfig, MechanicalGateProfile, MechanicalGateVerdict, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateOptions, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PriceTable, PricedUsage, type Pricing, type PricingTier, type ProviderAdapter, QualityFloors, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RandIdentityInput, RandPayload, RefEntryAppender, RefEntryClassification, RefusalInfo, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStatus, RuntimeEventSink, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, Semaphore, SerializationHook, Settled, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateSchemaSpec, validateTerminationLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/dist/index.js

@@ -547,6 +547,105 @@ function createCanonicalIdMinter(options) {
 	return monotonicUlidFactory(options);
 }
 //#endregion
+//#region src/l0/usage.ts
+const COUNT_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"cacheReadTokens",
+	"cacheWriteTokens",
+	"reasoningTokens"
+];
+/**
+* Names every rule the given usage violates; an empty array means the
+* usage satisfies the full canonical invariant: each present count is a
+* finite nonnegative integer and
+* `cacheReadTokens + cacheWriteTokens <= inputTokens`. The subset rule
+* is checked with a negated comparison so a NaN operand counts as a
+* violation rather than vacuously passing.
+*/
+function usageViolations(usage) {
+	const out = [];
+	for (const field of COUNT_FIELDS) {
+		const value = usage[field];
+		if (field === "reasoningTokens" && value === void 0) continue;
+		if (typeof value !== "number" || !Number.isFinite(value)) out.push(`${field} is ${String(value)}, not a finite number`);
+		else if (value < 0) out.push(`${field} is negative (${String(value)})`);
+		else if (!Number.isInteger(value)) out.push(`${field} is fractional (${String(value)})`);
+		else if (!Number.isSafeInteger(value)) out.push(`${field} is beyond the safe integer range (${String(value)})`);
+	}
+	if (!(usage.inputTokens >= usage.cacheReadTokens + usage.cacheWriteTokens)) out.push(`inputTokens (${String(usage.inputTokens)}) < cacheReadTokens + cacheWriteTokens (${String(usage.cacheReadTokens)} + ${String(usage.cacheWriteTokens)})`);
+	return out;
+}
+/**
+* One count, repaired in the conservative direction: non-numbers and
+* non-finite values floor to zero (no evidence, no charge and no
+* credit), negatives floor to zero (a negative count can only CREDIT
+* the budget, which hostile telemetry must never do), and fractions
+* round UP so a repaired charge is never an undercharge.
+*/
+function sanitizeTokenCount(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return 0;
+	return Math.min(Math.ceil(value), Number.MAX_SAFE_INTEGER);
+}
+/**
+* One field read per property, returning a detached plain copy. Both
+* accounting boundaries validate and consume THIS snapshot, never the
+* adapter-owned object, so a hostile accessor cannot answer the
+* validator with valid counts and the accumulator with garbage.
+*/
+function snapshotUsage(usage) {
+	const out = {
+		inputTokens: usage.inputTokens,
+		outputTokens: usage.outputTokens,
+		cacheReadTokens: usage.cacheReadTokens,
+		cacheWriteTokens: usage.cacheWriteTokens
+	};
+	const reasoning = usage.reasoningTokens;
+	if (reasoning !== void 0) out.reasoningTokens = reasoning;
+	return out;
+}
+/**
+* The per-field repair for DELTAS (mid-stream usage reports and other
+* partial increments): each count is repaired like `sanitizeTokenCount`,
+* but the whole-usage subset rule is deliberately NOT applied, because a
+* delta legitimately carries cache counts without restating the full
+* input in the same event; clamping those to the subset rule would
+* silently drop a paid cache debit. Always returns a fresh object and
+* is the identity on valid deltas.
+*/
+function sanitizeUsageDelta(delta) {
+	const snapshot = snapshotUsage(delta);
+	const out = {
+		inputTokens: sanitizeTokenCount(snapshot.inputTokens),
+		outputTokens: sanitizeTokenCount(snapshot.outputTokens),
+		cacheReadTokens: sanitizeTokenCount(snapshot.cacheReadTokens),
+		cacheWriteTokens: sanitizeTokenCount(snapshot.cacheWriteTokens)
+	};
+	if (snapshot.reasoningTokens !== void 0) out.reasoningTokens = sanitizeTokenCount(snapshot.reasoningTokens);
+	return out;
+}
+/**
+* Conservative repair for accounting. Pairs with `usageViolations`: the
+* violation fails the call loud, and the sanitized numbers are the only
+* ones the journal, the cost report, and the budget may see. After the
+* per-field repair the cache subsets clamp into the input with reads
+* keeping priority, mirroring the adapter-level subset clamp. Valid
+* usage passes through structurally unchanged.
+*/
+function sanitizeUsage(usage) {
+	const inputTokens = sanitizeTokenCount(usage.inputTokens);
+	const cacheReadTokens = Math.min(sanitizeTokenCount(usage.cacheReadTokens), inputTokens);
+	const cacheWriteTokens = Math.min(sanitizeTokenCount(usage.cacheWriteTokens), inputTokens - cacheReadTokens);
+	const out = {
+		inputTokens,
+		outputTokens: sanitizeTokenCount(usage.outputTokens),
+		cacheReadTokens,
+		cacheWriteTokens
+	};
+	if (usage.reasoningTokens !== void 0) out.reasoningTokens = sanitizeTokenCount(usage.reasoningTokens);
+	return out;
+}
+//#endregion
 //#region src/vendor/json-schema/deep-compare-strict.ts
 function deepCompareStrict(a, b) {
 	const typeofa = typeof a;
@@ -1772,7 +1871,10 @@ function entryUsageSlices(entry) {
 * The single pricing fold over one terminal entry, shared by the kernel
 * ledger and the CostReport fold so a run's total and its per-model
 * breakdown can never disagree. Each slice is priced at ITS OWN model's
-* rate.
+* rate. A price function returning NaN or a negative amount (a broken
+* user-supplied rate) is treated exactly like a missing row: the slice
+* folds as unpriced instead of poisoning or crediting the totals
+* (v1.20.0 review follow-up).
 */
 function priceEntryUsage(entry, priceUsd) {
 	const result = {
@@ -1782,7 +1884,7 @@ function priceEntryUsage(entry, priceUsd) {
 	};
 	for (const slice of entryUsageSlices(entry)) {
 		const usd = priceUsd(slice.servedBy, slice.usage);
-		if (usd === void 0) {
+		if (usd === void 0 || !Number.isFinite(usd) || usd < 0) {
 			result.unpriced.push(slice);
 			continue;
 		}
@@ -5535,6 +5637,7 @@ var Replayer = class {
 			if (patch.servedBy !== void 0) entry.servedBy = patch.servedBy;
 			if (patch.usageByModel !== void 0) entry.usageByModel = patch.usageByModel;
 			if (patch.costAttribution !== void 0) entry.costAttribution = patch.costAttribution;
+			if (patch.usageSemantics !== void 0) entry.usageSemantics = patch.usageSemantics;
 			if (patch.transcriptRef !== void 0) entry.transcriptRef = patch.transcriptRef;
 			if (patch.checkpointRef !== void 0) entry.checkpointRef = patch.checkpointRef;
 			if (patch.artifacts !== void 0) entry.artifacts = toJournalValue(patch.artifacts, "terminal artifacts");
@@ -7759,8 +7862,17 @@ function addUsage(total, turn) {
 * The Usage invariant is verified at the adapter boundary: inputTokens is
 * the FULL prompt including cache reads and writes.
 */
-function assertUsageInvariant(usage, adapterId) {
-	if (usage.inputTokens < usage.cacheReadTokens + usage.cacheWriteTokens) throw new Error(`adapter '${adapterId}' violated the Usage invariant: inputTokens (${usage.inputTokens}) < cacheReadTokens + cacheWriteTokens (${usage.cacheReadTokens} + ${usage.cacheWriteTokens})`);
+/**
+* The full canonical invariant at the adapter boundary (v1.20.0 review
+* P1-1): every count finite, integral, and nonnegative, and the cache
+* subsets inside the input. One violation message covers every adapter,
+* injected clients and mocks included; the financial invariant never
+* depends on the good faith of an external transport.
+*/
+function usageInvariantViolation(usage, adapterId) {
+	const violations = usageViolations(usage);
+	if (violations.length === 0) return;
+	return `adapter '${adapterId}' violated the Usage invariant: ${violations.join("; ")}`;
 }
 async function streamTurn(adapter, req, options) {
 	const idle = new AbortController();
@@ -7774,6 +7886,7 @@ async function streamTurn(adapter, req, options) {
 	const pendingArgs = /* @__PURE__ */ new Map();
 	let usage = ZERO_USAGE$1;
 	let reported = ZERO_USAGE$1;
+	let usageViolation;
 	let sawFinish = false;
 	let finish;
 	let providerMetadata;
@@ -7817,22 +7930,46 @@ async function streamTurn(adapter, req, options) {
 					break;
 				}
 				case "usage": {
+					if (sawFinish) {
+						usageViolation ??= "a usage event arrived after the finish event";
+						break;
+					}
+					const cleaned = {};
+					for (const field of [
+						"inputTokens",
+						"outputTokens",
+						"cacheReadTokens",
+						"cacheWriteTokens",
+						"reasoningTokens"
+					]) {
+						const value = event.usage[field];
+						if (value === void 0) continue;
+						if (Number.isInteger(value) && value >= 0) cleaned[field] = value;
+						else {
+							usageViolation ??= `mid-stream usage event carried invalid ${field} (${String(value)})`;
+							cleaned[field] = sanitizeTokenCount(value);
+						}
+					}
 					usage = {
 						...usage,
-						...event.usage
+						...cleaned
 					};
 					const delta = {
-						inputTokens: event.usage.inputTokens ?? 0,
-						outputTokens: event.usage.outputTokens ?? 0,
-						cacheReadTokens: event.usage.cacheReadTokens ?? 0,
-						cacheWriteTokens: event.usage.cacheWriteTokens ?? 0
+						inputTokens: cleaned.inputTokens ?? 0,
+						outputTokens: cleaned.outputTokens ?? 0,
+						cacheReadTokens: cleaned.cacheReadTokens ?? 0,
+						cacheWriteTokens: cleaned.cacheWriteTokens ?? 0
 					};
-					if (event.usage.reasoningTokens !== void 0) delta.reasoningTokens = event.usage.reasoningTokens;
+					if (cleaned.reasoningTokens !== void 0) delta.reasoningTokens = cleaned.reasoningTokens;
 					reported = addUsage(reported, delta);
 					options.onUsage?.(delta);
 					break;
 				}
 				case "finish":
+					if (sawFinish) {
+						usageViolation ??= "a second finish event arrived on one stream";
+						break;
+					}
 					sawFinish = true;
 					finish = event.finish;
 					usage = event.usage;
@@ -7864,6 +8001,7 @@ async function streamTurn(adapter, req, options) {
 			aborted
 		};
 		if (finish !== void 0) outcome.finish = finish;
+		if (usageViolation !== void 0) outcome.usageViolation = usageViolation;
 		return outcome;
 	}
 	const outcome = {
@@ -7873,6 +8011,7 @@ async function streamTurn(adapter, req, options) {
 		usageApprox: !sawFinish
 	};
 	if (finish !== void 0) outcome.finish = finish;
+	if (usageViolation !== void 0) outcome.usageViolation = usageViolation;
 	if (providerMetadata !== void 0) outcome.providerMetadata = providerMetadata;
 	if (wireError !== void 0) outcome.wireError = wireError;
 	return outcome;
@@ -8095,17 +8234,18 @@ async function runAgent(options) {
 		messages.length = 0;
 		messages.push(...restored.messages);
 		turns = restored.turns;
-		totalUsage = restored.usage;
+		totalUsage = usageViolations(restored.usage).length === 0 ? restored.usage : sanitizeUsage(restored.usage);
 		toolCallsUsed = restored.toolCallsUsed;
 		schemaAttempts = restored.schemaAttempts;
 		compactionPoints.push(...restored.compaction);
 		const restoredSlices = restored.usageByModel ?? [{
 			servedBy,
-			usage: restored.usage
+			usage: totalUsage
 		}];
 		for (const slice of restoredSlices) {
-			addPhaseUsage(slice.role ?? primaryRole, slice.servedBy, slice.usage);
-			options.budget?.onUsage(slice.usage, slice.servedBy);
+			const sliceUsage = usageViolations(slice.usage).length === 0 ? slice.usage : sanitizeUsage(slice.usage);
+			addPhaseUsage(slice.role ?? primaryRole, slice.servedBy, sliceUsage);
+			options.budget?.onUsage(sliceUsage, slice.servedBy);
 		}
 	}
 	const usageSlices = () => [...usageByPhaseModel.values()].map(({ role, servedBy: sliceServedBy, usage }) => ({
@@ -8122,7 +8262,10 @@ async function runAgent(options) {
 		const price = options.priceUsd;
 		if (price === void 0) return 0;
 		let usd = 0;
-		for (const slice of usageByPhaseModel.values()) usd += price(slice.servedBy, slice.usage) ?? 0;
+		for (const slice of usageByPhaseModel.values()) {
+			const sliceUsd = price(slice.servedBy, slice.usage) ?? 0;
+			if (Number.isFinite(sliceUsd) && sliceUsd > 0) usd += sliceUsd;
+		}
 		return usd;
 	};
 	const saveBoundary = async (pending) => {
@@ -8358,21 +8501,29 @@ async function runAgent(options) {
 		role: primaryRole
 	});
 	let invariantViolation;
-	const recordUsage = (usage, reported, adapterId, ref, role) => {
-		try {
-			assertUsageInvariant(usage, adapterId);
-		} catch (thrown) {
-			invariantViolation = thrown instanceof Error ? thrown.message : String(thrown);
-		}
-		totalUsage = addUsage(totalUsage, usage);
-		addPhaseUsage(role, ref, usage);
+	const recordUsage = (usage, reported, adapterId, ref, role, streamViolation) => {
+		if (streamViolation !== void 0) invariantViolation ??= `adapter '${adapterId}' violated the Usage invariant: ${streamViolation}`;
+		const snapshot = snapshotUsage(usage);
+		const violation = usageInvariantViolation(snapshot, adapterId);
+		if (violation !== void 0) invariantViolation ??= violation;
+		const safe = violation === void 0 ? snapshot : sanitizeUsage(snapshot);
+		totalUsage = addUsage(totalUsage, safe);
+		addPhaseUsage(role, ref, safe);
 		const remainder = {
-			inputTokens: Math.max(0, usage.inputTokens - reported.inputTokens),
-			outputTokens: Math.max(0, usage.outputTokens - reported.outputTokens),
-			cacheReadTokens: Math.max(0, usage.cacheReadTokens - reported.cacheReadTokens),
-			cacheWriteTokens: Math.max(0, usage.cacheWriteTokens - reported.cacheWriteTokens)
+			inputTokens: Math.max(0, safe.inputTokens - reported.inputTokens),
+			outputTokens: Math.max(0, safe.outputTokens - reported.outputTokens),
+			cacheReadTokens: Math.max(0, safe.cacheReadTokens - reported.cacheReadTokens),
+			cacheWriteTokens: Math.max(0, safe.cacheWriteTokens - reported.cacheWriteTokens)
 		};
-		const reasoningRemainder = Math.max(0, (usage.reasoningTokens ?? 0) - (reported.reasoningTokens ?? 0));
+		for (const field of [
+			"inputTokens",
+			"outputTokens",
+			"cacheReadTokens",
+			"cacheWriteTokens"
+		]) if (reported[field] > safe[field]) invariantViolation ??= `adapter '${adapterId}' violated the Usage invariant: mid-stream ${field} (${String(reported[field])}) exceeded the finish total (${String(safe[field])})`;
+		const overReportedReads = Math.max(0, reported.cacheReadTokens - safe.cacheReadTokens);
+		if (overReportedReads > 0) remainder.inputTokens = Math.min(Number.MAX_SAFE_INTEGER, remainder.inputTokens + overReportedReads);
+		const reasoningRemainder = Math.max(0, (safe.reasoningTokens ?? 0) - (reported.reasoningTokens ?? 0));
 		if (reasoningRemainder > 0) remainder.reasoningTokens = reasoningRemainder;
 		if (remainder.inputTokens > 0 || remainder.outputTokens > 0 || remainder.cacheReadTokens > 0 || remainder.cacheWriteTokens > 0) options.budget?.onUsage(remainder, ref);
 	};
@@ -8387,7 +8538,7 @@ async function runAgent(options) {
 			inner: for (;;) {
 				const dispatch = () => streamTurn(target.adapter, site.requestFor(target), site.streamOptionsFor(target));
 				const outcome = await (options.providerSlot === void 0 ? dispatch() : options.providerSlot(target.adapter.id, dispatch));
-				recordUsage(outcome.usage, outcome.reported, target.adapter.id, target.resolved.ref, site.role);
+				recordUsage(outcome.usage, outcome.reported, target.adapter.id, target.resolved.ref, site.role, outcome.usageViolation);
 				tries += 1;
 				const retryClass = outcome.aborted === "idle" ? "transport" : outcome.wireError === void 0 ? void 0 : retryClassOf(outcome.wireError);
 				if (retryClass === void 0) return {
@@ -9109,6 +9260,15 @@ const ZERO_USAGE = {
 	cacheWriteTokens: 0
 };
 /**
+* A ceiling that is NaN or negative silently disarms every layer (each
+* comparison against it is false), which is indistinguishable from
+* uncapped. That must be a loud configuration error, never a silent
+* fail-open (v1.20.0 review P1-1).
+*/
+function requireValidCeiling(ceilingUsd, what) {
+	if (!Number.isFinite(ceilingUsd) || ceilingUsd < 0) throw new ConfigError(`${what} must be a finite nonnegative USD amount, got ${String(ceilingUsd)}`);
+}
+/**
 * The admission reserve for a spawn: opts.estCost, else profile.estCost,
 * else price(countTokens(input) + one turn's worth of output), else the
 * engine flat default. The output term is caps.maxOutputTokens clamped to
@@ -9151,8 +9311,13 @@ var RunBudget = class {
 	exhaustedInternal = false;
 	/** Models already warned about; the warning fires once per model per run. */
 	unpricedWarned = /* @__PURE__ */ new Set();
+	/** Models whose price function already returned an invalid USD once. */
+	invalidPriceWarned = /* @__PURE__ */ new Set();
 	constructor(options) {
-		if (options.ceilingUsd !== void 0) this.ceilingUsd = options.ceilingUsd;
+		if (options.ceilingUsd !== void 0) {
+			requireValidCeiling(options.ceilingUsd, "budget ceiling");
+			this.ceilingUsd = options.ceilingUsd;
+		}
 		this.lifetimeSpawnCap = options.lifetimeSpawnCap ?? 500;
 		if (options.events !== void 0) this.events = options.events;
 		if (options.priceUsd !== void 0) this.priceUsd = options.priceUsd;
@@ -9167,8 +9332,9 @@ var RunBudget = class {
 		if (options.ceilingUsd !== void 0) root.ceilingUsd = options.ceilingUsd;
 		this.accounts.set("run", root);
 		if (options.seed !== void 0) {
+			if (!Number.isFinite(options.seed.usd) || options.seed.usd < 0) throw new ConfigError(`budget resume seed is not a finite nonnegative USD amount: ${String(options.seed.usd)}`);
 			root.spentUsd = options.seed.usd;
-			this.usageInternal = { ...options.seed.usage };
+			this.usageInternal = sanitizeUsage(options.seed.usage);
 			this.agentsSpawnedInternal = options.seed.agentsSpawned;
 		}
 	}
@@ -9208,7 +9374,10 @@ var RunBudget = class {
 			parentScope,
 			controller: new AbortController()
 		};
-		if (options.ceilingUsd !== void 0) account.ceilingUsd = options.ceilingUsd;
+		if (options.ceilingUsd !== void 0) {
+			requireValidCeiling(options.ceilingUsd, `ceiling of budget account '${scope}'`);
+			account.ceilingUsd = options.ceilingUsd;
+		}
 		if (options.kind !== void 0) account.kind = options.kind;
 		this.accounts.set(scope, account);
 	}
@@ -9436,15 +9605,16 @@ var RunBudget = class {
 	* in-flight agent; providers bill severed streams).
 	*/
 	onUsage(usage, servedBy, accountScope = "run") {
+		const safe = sanitizeUsageDelta(usage);
 		this.usageInternal = {
-			inputTokens: this.usageInternal.inputTokens + usage.inputTokens,
-			outputTokens: this.usageInternal.outputTokens + usage.outputTokens,
-			cacheReadTokens: this.usageInternal.cacheReadTokens + usage.cacheReadTokens,
-			cacheWriteTokens: this.usageInternal.cacheWriteTokens + usage.cacheWriteTokens
+			inputTokens: this.usageInternal.inputTokens + safe.inputTokens,
+			outputTokens: this.usageInternal.outputTokens + safe.outputTokens,
+			cacheReadTokens: this.usageInternal.cacheReadTokens + safe.cacheReadTokens,
+			cacheWriteTokens: this.usageInternal.cacheWriteTokens + safe.cacheWriteTokens
 		};
-		const reasoning = (this.usageInternal.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0);
+		const reasoning = (this.usageInternal.reasoningTokens ?? 0) + (safe.reasoningTokens ?? 0);
 		if (reasoning > 0) this.usageInternal.reasoningTokens = reasoning;
-		const priced = this.priceUsd?.(servedBy, usage);
+		const priced = this.priceUsd?.(servedBy, safe);
 		if (priced === void 0 && this.ceilingUsd !== void 0 && !this.unpricedWarned.has(servedBy)) {
 			this.unpricedWarned.add(servedBy);
 			this.events?.emit({
@@ -9453,7 +9623,18 @@ var RunBudget = class {
 				msg: `no price row for '${servedBy}': its usage does not debit the budget, so the ${this.ceilingUsd} USD run ceiling does NOT bound this model. Add it to createEngine({ pricing }) to cap it; its usage is reported under CostReport.unpriced`
 			});
 		}
-		const usd = priced ?? 0;
+		let usd = priced ?? 0;
+		if (!Number.isFinite(usd) || usd < 0) {
+			if (!this.invalidPriceWarned.has(servedBy)) {
+				this.invalidPriceWarned.add(servedBy);
+				this.events?.emit({
+					type: "log",
+					level: "error",
+					msg: `price function returned ${String(usd)} USD for '${servedBy}'; charging 0 for this slice so the budget stays finite and monotone. Fix the pricing row: this usage is NOT debited and any ceiling under-counts it`
+				});
+			}
+			usd = 0;
+		}
 		for (const account of this.chainOf(accountScope)) {
 			account.spentUsd += usd;
 			if (account.ceilingUsd !== void 0 && account.spentUsd >= account.ceilingUsd && !account.controller.signal.aborted) {
@@ -11016,10 +11197,18 @@ function createCtx(internals, rootWorkflow) {
 			result.escalation = report;
 			delete result.escalationRequest;
 		}
+		const adapterOfRef = (ref) => ref.slice(0, ref.indexOf(":"));
+		const declaredSemantics = [];
+		for (const ref of [result.servedBy, ...(result.usageByModel ?? []).map((slice) => slice.servedBy)]) {
+			const declared = internals.adapters.get(adapterOfRef(ref))?.usageSemantics;
+			if (declared !== void 0 && !declaredSemantics.includes(declared)) declaredSemantics.push(declared);
+		}
+		const servedSemantics = declaredSemantics.length === 0 ? void 0 : declaredSemantics.join("+");
 		const terminalPatch = {
 			status: result.status === "skipped" ? "error" : result.status,
 			usage: result.usage,
 			servedBy: result.servedBy,
+			...servedSemantics === void 0 ? {} : { usageSemantics: servedSemantics },
 			...result.usageByModel === void 0 ? {} : { usageByModel: result.usageByModel },
 			costAttribution: {
 				...state.phase === void 0 ? {} : { phase: state.phase },
@@ -11084,7 +11273,7 @@ function createCtx(internals, rootWorkflow) {
 		}];
 		for (const slice of attributionSlices) {
 			const priced = internals.priceUsd(slice.servedBy, slice.usage);
-			if (priced === void 0) {
+			if (priced === void 0 || !Number.isFinite(priced) || priced < 0) {
 				internals.cost.unpriced.push({
 					model: slice.servedBy,
 					usage: slice.usage
@@ -13057,6 +13246,10 @@ function createEngine(options) {
 			}
 			const priorEntries = (await journal.load(runId)).map((entry) => normalizeEntry(entry));
 			scanJournalCompatibility(runId, priorEntries, buildDeriverRegistry(options.extraDerivers));
+			if (priorEntries.some((entry) => entry.usageSemantics === void 0 && (entry.servedBy?.startsWith("openai:") === true && (entry.usage?.cacheWriteTokens ?? 0) > 0 || (entry.usageByModel?.some((slice) => slice.servedBy.startsWith("openai:") && slice.usage.cacheWriteTokens > 0) ?? false)))) process.emitWarning(`resume: run '${runId}' contains OpenAI cache-write usage recorded without a usage-semantics stamp. Entries written by rulvar v1.19.0 double-counted cache writes into inputTokens, so their recorded cost and budget debits are OVERSTATED; unstamped entries from v1.20.0 are correct. Resuming keeps the recorded debits. Audit procedure: https://docs.rulvar.com/guide/providers#openai-legacy-cache-journals`, {
+				code: "RULVAR_LEGACY_CACHE_SEMANTICS",
+				type: "RulvarWarning"
+			});
 			return run(bound, resumeOptions?.args, void 0, {
 				runId,
 				priorEntries,
@@ -13417,4 +13610,4 @@ function createSandboxBridge(ctx, options) {
 	};
 }
 //#endregion
-export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DedupIndex, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FileModelKnowledgeStore, FileTranscriptStore, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateSchemaSpec, validateTerminationLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DedupIndex, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FileModelKnowledgeStore, FileTranscriptStore, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateSchemaSpec, validateTerminationLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",