@rulvar/core 1.72.0 → 1.74.0

package/dist/index.d.ts

@@ -3111,12 +3111,33 @@ interface EngineQuotaConfig {
   * knob. reconcile failures only ever warn.
   */
   onLimiterError?: "deny" | "allow";
+  /**
+  * The drift telemetry opt-in (the v1.71 experiment review, P0.5
+  * resized): the SAME rule declaration `preflightEstimate` takes as
+  * `quotaRules`, mirrored here so the engine can hold it against what
+  * providers actually REPORT. When a live 429 carries
+  * provider-normalized limits (the openai and anthropic adapters
+  * parse the x-ratelimit headers into
+  * `WireError.data.reportedLimits`) and a declared per-minute cap
+  * EXCEEDS the reported one, the run journals a `quota_drift`
+  * decision (provider, model, tenant, dimension, declared, reported;
+  * one per invocation and dimension) and emits a warn log, because a
+  * limiter configured above the provider's real ceiling
+  * under-throttles and live denials follow: the experiment inflated
+  * 12M TPM over a real 1M and paid seven live 429s with nothing
+  * recording the mismatch. Purely observational: nothing clamps, the
+  * limiter keeps enforcing the declaration (clamping is host policy).
+  * Absent = byte identical journals and events.
+  */
+  declaredRules?: readonly QuotaRule[];
 }
 /** The resolved engine-side quota runtime threaded into every run. */
 interface EngineQuotaRuntime {
   limiter: QuotaLimiter;
   tenant?: string;
   onLimiterError: "deny" | "allow";
+  /** The declared rule mirror for drift telemetry; see {@link EngineQuotaConfig}. */
+  declaredRules?: readonly QuotaRule[];
 }
 /**
 * Validates createEngine's quota config as a typed ConfigError before
@@ -4136,6 +4157,16 @@ interface AgentResult<T> {
   */
   transportRetries?: number;
   /**
+  * Provider-reported rate limits observed on this invocation's 429s
+  * (the v1.71 experiment review, P0.5): one entry per (provider,
+  * model), the latest observation winning, parsed by the adapters
+  * into `WireError.data.reportedLimits`. Live telemetry only, exactly
+  * like transportRetries: never journaled, absent on a replayed
+  * result; the ctx layer holds it against `quota.declaredRules` and
+  * journals the drift verdicts, which ARE durable.
+  */
+  rateLimitObservations?: RateLimitObservation[];
+  /**
   * The exploration guard counters (RV-210): present whenever any of
   * the exploration limits (toolBudgetNotices, maxRepeatedToolSignature,
   * maxNoNewEvidenceCalls) was configured. Journaled inside the terminal
@@ -4157,6 +4188,24 @@ interface AgentResult<T> {
   */
   partial?: ProgressReport;
 }
+/** One 429's provider-normalized limits, per (provider, model). */
+interface RateLimitObservation {
+  provider: string;
+  model: string;
+  /**
+  * Per-minute limits the provider REPORTED in its rate-limit
+  * headers, normalized by the adapter: openai fills
+  * requestsPerMinute and tokensPerMinute; anthropic fills
+  * requestsPerMinute plus the split inputTokensPerMinute and
+  * outputTokensPerMinute.
+  */
+  reportedLimits: {
+    requestsPerMinute?: number;
+    tokensPerMinute?: number;
+    inputTokensPerMinute?: number;
+    outputTokensPerMinute?: number;
+  };
+}
 type EscalatedResult<T> = AgentResult<T> & {
   status: "escalated";
   escalation: EscalationReport;
@@ -4405,6 +4454,18 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
       ok: false;
       feedback: Record<string, unknown>;
     }>;
+    /**
+    * The repair reserve (the v1.71 experiment review, P0.4): max EXTRA
+    * turns the loop may grant past limits.maxTurns, one per rejected
+    * terminal-tool exchange, schema-invalid arguments and host
+    * validation rejections alike. The grant count derives from the
+    * message window itself (error tool results named after the
+    * terminal tool, clamped to the reserve), so a resumed segment that
+    * restored the window mid-exchange re-derives the same grants and
+    * nothing needs journaling. Zero (or absent) keeps the ceiling
+    * byte identical to the pre 1.73 loop.
+    */
+    repairTurnReserve?: number;
   };
   agentType?: string;
   /** The primary invocation role of the tool loop; default 'loop' (M6-T05; RV-211 adds synthesize). */
@@ -7038,6 +7099,23 @@ interface FinishValidationSpec {
   */
   maxRepairs?: number;
   /**
+  * The repair turn reserve (the v1.71 experiment review, P0.4; the
+  * reserve RV-204 deliberately deferred). A nonnegative integer,
+  * default 0: max EXTRA turns the invocation the validators bind (the
+  * synthesis invocation when `synthesis` is configured, the
+  * coordination loop otherwise) may consume past its `maxTurns`, one
+  * granted per rejected finish exchange, schema-invalid finish
+  * arguments and host validation rejections alike. Without it, repair
+  * exchanges and generation compete for the same turn budget: the
+  * v1.71 experiment lost its whole run to one malformed finish plus
+  * one validator rejection inside maxTurns 3. The reserve is bounded,
+  * spends from the ordinary budget ceilings (a granted turn is a paid
+  * provider turn), and folds into the preflight turn projection
+  * (`projectedProviderTurns` and the run ceiling) when declared
+  * there. Zero keeps the pre 1.73 ceiling byte identical.
+  */
+  repairTurnReserve?: number;
+  /**
   * The unified output contract this validator set enforces (the v1.71
   * experiment review, P0.1/P0.2). Construction then runs the golden
   * self test with the contract's fixtures as defaults, the contract's
@@ -8626,6 +8704,17 @@ interface InvoiceRow {
   responseId?: string;
   usage: Usage;
   usageApprox?: boolean;
+  /**
+  * Present and true when this `unconfirmed` row recorded ZERO usage
+  * on every counter (the v1.71 experiment review, P1.4): a failed
+  * attempt whose usage this ledger never saw. The zeros mean
+  * "nothing recorded", never "the provider metered nothing": the
+  * provider may have billed prompt processing before the failure, so
+  * a statement join must treat this row's usage as unknown, not as
+  * zero. Derived at export time from the journaled record; rows with
+  * any recorded usage, and every other verdict, never carry it.
+  */
+  usageUnknown?: true;
   /** This row priced at its own model's rate; absent when no price row covers it. */
   usd?: number;
   /**
@@ -8670,6 +8759,8 @@ interface InvoiceExport {
   }>;
   /** Rows whose reconciliation is not 'provider-id-present'. */
   reconciliationFailures: number;
+  /** Rows carrying `usageUnknown`; present when at least one does. */
+  usageUnknownRows?: number;
   /** Present and true when any contributing entry carried approximate usage. */
   usageApprox?: boolean;
 }
@@ -8749,6 +8840,23 @@ interface PreflightOrchestratorSpec {
   * root, so only they subtract it from spawn-admission headroom.
   */
   extension?: boolean;
+  /**
+  * The separate synthesis invocation (RV-211), when the orchestration
+  * configures one (the v1.71 experiment review: the run ceiling used
+  * to stop at the coordination loop, undercounting the synthesis
+  * turns). `limits` mirrors OrchestrateSynthesis.limits exactly
+  * (absent = the DEFAULT_SYNTHESIS_MAX_TURNS invocation), `model`
+  * mirrors its model override (absent = defaults.routing.synthesize),
+  * and `estInputTokens` is the prompt-size stand-in for the derived
+  * synthesis prompt. When `finishValidation.repairTurnReserve` is
+  * declared, the reserve folds into THIS invocation's projected turns,
+  * because the validators bind the synthesis finish.
+  */
+  synthesis?: {
+    model?: ModelSpec;
+    limits?: UsageLimits;
+    estInputTokens?: number;
+  };
 }
 /** The full input: engine surface, run surface, and the declared wave. */
 interface PreflightInput {
@@ -8780,6 +8888,15 @@ interface PreflightInput {
     validators: FinishValidator[];
     contract?: FinishContract;
     selfTest?: FinishSelfTestFixtures;
+    /**
+    * Mirrors FinishValidationSpec.repairTurnReserve: folds the
+    * declared repair headroom into the projected turns of the
+    * invocation the validators bind (the synthesis invocation when
+    * orchestrator.synthesis is declared, the coordination loop
+    * otherwise), so the run ceiling prices the repair exchange the
+    * runtime would actually grant.
+    */
+    repairTurnReserve?: number;
   };
 }
 /** One linter verdict; `spawn` names the wave entry it is about. */
@@ -8861,6 +8978,16 @@ interface PreflightReport {
       finalizeTurns: number; /** Whether the finalize reserve is committed against the run root (extension runs). */
       reserveCommitted: boolean; /** The orchestrator agent's own loop ceiling, derived exactly like a spawn's. */
       projectedProviderTurns: number;
+      /**
+      * The separate synthesis invocation's projection, present when
+      * input.orchestrator.synthesis was declared and the role
+      * resolves: its turn ceiling (the repair turn reserve folded in
+      * when declared) and its serving model.
+      */
+      synthesis?: {
+        projectedProviderTurns: number;
+        servedBy?: ModelRef;
+      };
     };
   };
   quota: {
@@ -9431,4 +9558,4 @@ interface SandboxBridge {
 declare const SANDBOX_AGENT_OPT_KEYS: readonly string[];
 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, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentProfileTemplateOptions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditCategory, AuditRecord, AuditRunsOptions, BUDGET_ABORT_REASON, BaseAppend, 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, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, type CriticalPath, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_CITATION_SAMPLE, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, 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, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DataKeyProvider, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DedupedClaims, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EngineQuotaConfig, EngineQuotaRuntime, EntryKind, EntryRef, EntryStatus, EnvelopeEncryption, EnvelopeEncryptionOptions, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, type ExecutorRegistry, type ExplorationSummary, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishContract, FinishContractCitations, FinishContractManifest, FinishInfo, FinishSelfTestFailure, FinishSelfTestFixtures, FinishSelfTestReport, FinishValidationChild, FinishValidationInput, FinishValidationSpec, FinishValidationVerdict, FinishValidator, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, IMPLEMENTATION_PROFILE_LIMITS, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, IncrementalSynthesisResult, InvalidResolutionError, InvocationRole, type InvocationTable, InvoiceExport, InvoiceReconciliation, InvoiceRow, type IsolatedExecContext, type IsolatedExecRequest, type IsolatedExecutorTag, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JOURNAL_ENVELOPE_MARKER, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationContext, 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_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, MemoryQuotaLimiter, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestrateSynthesis, OrchestrateSynthesisSkipReason, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, PROGRESS_REPORT_TOOL_NAME, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PreflightAdmissionRow, PreflightFinding, PreflightInput, PreflightOrchestratorSpec, PreflightReport, PreflightSpawnReport, PreflightSpawnSpec, PreflightToolCeiling, PriceTable, PricedUsage, type Pricing, type PricingTier, ProgressReport, type ProviderAdapter, ProviderCallRecord, QUOTA_WINDOW_MS, QualityFloors, QuotaCounters, type QuotaDecision, type QuotaEstimate, type QuotaLimiter, type QuotaReservationRequest, QuotaRule, QuotaWindowSnapshot, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, RESEARCH_PROFILE_LIMITS, REVIEW_PROFILE_LIMITS, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, ReconcileOptions, ReconcileResult, RefEntryAppender, RefEntryClassification, RefusalInfo, RepeatedClaim, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, RepositoryResearchToolset, RepositoryResearchToolsetOptions, ResearchAgentProfileOptions, ResearchAgentProfileResult, ResearchEvidenceEntry, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunAuditVerdict, RunBudget, RunEventSink, RunExport, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, SecretMasker, Semaphore, SerializationHook, Settled, SettlementError, 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, type ToolExecutorProvider, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, compileSecretMasker, compileVerifiedLayer, constantTimeEqual, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createEnvelopeEncryption, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispatchProjectionReserveUsd, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, finishContract, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, implementationAgentProfile, invoiceFromJournal, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, latestProgressReport, lexShellCommand, liftRetainedParts, lineageWeightOf, localKeyProvider, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, memoryQuotaLimiter, mergeQuotaDenial, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, orchestratorAdmissionEstCostUsd, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, preflightEstimate, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, progressReportTool, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, readRunMeta, readTerminationInit, reconcileRunMeta, reduceAuditTrail, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, requiredFieldsValidator, requiredSectionsValidator, researchAgentProfile, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, reviewAgentProfile, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, sectionCitationsValidator, selectStructuredOutputTier, selfTestFinishValidation, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEngineQuotaConfig, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateQuotaRules, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, wordCountValidator, 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, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentProfileTemplateOptions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditCategory, AuditRecord, AuditRunsOptions, BUDGET_ABORT_REASON, BaseAppend, 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, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, type CriticalPath, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_CITATION_SAMPLE, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, 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, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DataKeyProvider, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DedupedClaims, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EngineQuotaConfig, EngineQuotaRuntime, EntryKind, EntryRef, EntryStatus, EnvelopeEncryption, EnvelopeEncryptionOptions, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, type ExecutorRegistry, type ExplorationSummary, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishContract, FinishContractCitations, FinishContractManifest, FinishInfo, FinishSelfTestFailure, FinishSelfTestFixtures, FinishSelfTestReport, FinishValidationChild, FinishValidationInput, FinishValidationSpec, FinishValidationVerdict, FinishValidator, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, IMPLEMENTATION_PROFILE_LIMITS, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, IncrementalSynthesisResult, InvalidResolutionError, InvocationRole, type InvocationTable, InvoiceExport, InvoiceReconciliation, InvoiceRow, type IsolatedExecContext, type IsolatedExecRequest, type IsolatedExecutorTag, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JOURNAL_ENVELOPE_MARKER, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationContext, 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_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, MemoryQuotaLimiter, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestrateSynthesis, OrchestrateSynthesisSkipReason, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, PROGRESS_REPORT_TOOL_NAME, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PreflightAdmissionRow, PreflightFinding, PreflightInput, PreflightOrchestratorSpec, PreflightReport, PreflightSpawnReport, PreflightSpawnSpec, PreflightToolCeiling, PriceTable, PricedUsage, type Pricing, type PricingTier, ProgressReport, type ProviderAdapter, ProviderCallRecord, QUOTA_WINDOW_MS, QualityFloors, QuotaCounters, type QuotaDecision, type QuotaEstimate, type QuotaLimiter, type QuotaReservationRequest, QuotaRule, QuotaWindowSnapshot, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, RESEARCH_PROFILE_LIMITS, REVIEW_PROFILE_LIMITS, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, RateLimitObservation, ReconcileOptions, ReconcileResult, RefEntryAppender, RefEntryClassification, RefusalInfo, RepeatedClaim, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, RepositoryResearchToolset, RepositoryResearchToolsetOptions, ResearchAgentProfileOptions, ResearchAgentProfileResult, ResearchEvidenceEntry, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunAuditVerdict, RunBudget, RunEventSink, RunExport, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, SecretMasker, Semaphore, SerializationHook, Settled, SettlementError, 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, type ToolExecutorProvider, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, compileSecretMasker, compileVerifiedLayer, constantTimeEqual, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createEnvelopeEncryption, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispatchProjectionReserveUsd, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, finishContract, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, implementationAgentProfile, invoiceFromJournal, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, latestProgressReport, lexShellCommand, liftRetainedParts, lineageWeightOf, localKeyProvider, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, memoryQuotaLimiter, mergeQuotaDenial, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, orchestratorAdmissionEstCostUsd, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, preflightEstimate, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, progressReportTool, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, readRunMeta, readTerminationInit, reconcileRunMeta, reduceAuditTrail, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, requiredFieldsValidator, requiredSectionsValidator, researchAgentProfile, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, reviewAgentProfile, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, sectionCitationsValidator, selectStructuredOutputTier, selfTestFinishValidation, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEngineQuotaConfig, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateQuotaRules, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, wordCountValidator, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/dist/index.js

@@ -8361,6 +8361,8 @@ function invoiceFromJournal(entries, priceUsd) {
 		const records = entry.providerCalls ?? [];
 		for (const record of records) {
 			const usd = rowUsd(priceUsd, record.servedBy, record.usage);
+			const reconciliation = record.responseId !== void 0 ? "provider-id-present" : record.outcome === "ok" ? "missing-provider-id" : "unconfirmed";
+			const usageUnknown = reconciliation === "unconfirmed" && USAGE_FIELDS.every((field) => record.usage[field] === 0) && (record.usage.reasoningTokens ?? 0) === 0;
 			rows.push({
 				...base,
 				ordinal: record.ordinal,
@@ -8371,10 +8373,11 @@ function invoiceFromJournal(entries, priceUsd) {
 				...record.responseId === void 0 ? {} : { responseId: record.responseId },
 				usage: record.usage,
 				...record.usageApprox === true ? { usageApprox: true } : {},
+				...usageUnknown ? { usageUnknown: true } : {},
 				...usd === void 0 ? {} : { usd },
 				allocatedUsd: 0,
 				...mark,
-				reconciliation: record.responseId !== void 0 ? "provider-id-present" : record.outcome === "ok" ? "missing-provider-id" : "unconfirmed"
+				reconciliation
 			});
 		}
 		if (records.length === 0) {
@@ -8424,6 +8427,10 @@ function invoiceFromJournal(entries, priceUsd) {
 		rowUsdNonAdditive: true,
 		unpriced: [...report.unpriced, ...report.abandoned.unpriced],
 		reconciliationFailures: rows.filter((row) => row.reconciliation !== "provider-id-present").length,
+		...(() => {
+			const count = rows.filter((row) => row.usageUnknown === true).length;
+			return count === 0 ? {} : { usageUnknownRows: count };
+		})(),
 		...usageApprox ? { usageApprox: true } : {}
 	};
 }
@@ -8954,6 +8961,8 @@ function validateEngineQuotaConfig(config, site = "createEngine quota") {
 	if (typeof limiter !== "object" || limiter === null || typeof limiter.reserve !== "function" || typeof limiter.reconcile !== "function") throw new ConfigError(`${site}.limiter must implement QuotaLimiter (reserve and reconcile functions)`);
 	if (candidate.tenant !== void 0 && (typeof candidate.tenant !== "string" || candidate.tenant === "")) throw new ConfigError(`${site}.tenant must be a nonempty string when given`);
 	if (candidate.onLimiterError !== void 0 && candidate.onLimiterError !== "deny" && candidate.onLimiterError !== "allow") throw new ConfigError(`${site}.onLimiterError must be 'deny' or 'allow' when given`);
+	const declared = candidate.declaredRules;
+	if (declared !== void 0) validateQuotaRules(declared, `${site}.declaredRules`);
 }
 //#endregion
 //#region src/runtime/usage-limits.ts
@@ -10340,6 +10349,7 @@ async function runAgent(options) {
 	const providerCalls = [];
 	let invocationCounter = 0;
 	let transportRetries = 0;
+	const rateLimitObservations = /* @__PURE__ */ new Map();
 	const roleUsageSnapshot = (role) => {
 		const snapshot = /* @__PURE__ */ new Map();
 		for (const [key, slice] of usageByPhaseModel) if (slice.role === role) snapshot.set(key, slice.usage);
@@ -11017,6 +11027,12 @@ async function runAgent(options) {
 					if (outcome.aborted !== void 0) record.aborted = outcome.aborted;
 					else if (outcome.wireError !== void 0) record.errorCode = outcome.wireError.code;
 					providerCalls.push(record);
+					const limited = outcome.wireError?.data;
+					if (limited?.kind === "rate-limit" && typeof limited.reportedLimits === "object" && limited.reportedLimits !== null) rateLimitObservations.set(`${target.adapter.id}:${target.resolved.model}`, {
+						provider: target.adapter.id,
+						model: target.resolved.model,
+						reportedLimits: limited.reportedLimits
+					});
 				}
 				tries += 1;
 				const retryClass = outcome.aborted === "idle" ? "transport" : outcome.wireError === void 0 ? void 0 : retryClassOf(outcome.wireError);
@@ -11087,7 +11103,9 @@ async function runAgent(options) {
 			status = "limit";
 			break;
 		}
-		if (turns >= limits.maxTurns) {
+		const repairReserve = options.terminalTool?.repairTurnReserve ?? 0;
+		const grantedRepairTurns = repairReserve === 0 ? 0 : Math.min(repairReserve, messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === options.terminalTool?.name && part.isError === true).length, 0));
+		if (turns >= limits.maxTurns + grantedRepairTurns) {
 			status = "limit";
 			break;
 		}
@@ -11837,6 +11855,7 @@ async function runAgent(options) {
 	if (limitPartial !== void 0) result.partial = limitPartial;
 	if (usageApprox) result.usageApprox = true;
 	if (transportRetries > 0) result.transportRetries = transportRetries;
+	if (rateLimitObservations.size > 0) result.rateLimitObservations = [...rateLimitObservations.values()];
 	return result;
 }
 //#endregion
@@ -13989,6 +14008,59 @@ function createCtx(internals, rootWorkflow) {
 			exitActivity?.();
 		}
 		internals.budget.releaseReserve(reserve, budgetAccount);
+		const declaredRules = internals.quota?.declaredRules;
+		if (declaredRules !== void 0 && result.rateLimitObservations !== void 0) for (const observation of result.rateLimitObservations) {
+			const probe = {
+				provider: observation.provider,
+				model: observation.model,
+				...internals.quota?.tenant === void 0 ? {} : { tenant: internals.quota.tenant },
+				estimate: {
+					requests: 1,
+					inputTokens: 0
+				}
+			};
+			const matching = declaredRules.filter((rule) => quotaRuleMatches(rule, probe));
+			const declaredOf = (pick) => {
+				const caps = matching.map(pick).filter((cap) => cap !== void 0);
+				return caps.length === 0 ? void 0 : Math.min(...caps);
+			};
+			const reported = observation.reportedLimits;
+			const reportedTokens = reported.tokensPerMinute ?? (reported.inputTokensPerMinute !== void 0 && reported.outputTokensPerMinute !== void 0 ? reported.inputTokensPerMinute + reported.outputTokensPerMinute : void 0);
+			const dimensions = [{
+				dimension: "requests",
+				declared: declaredOf((rule) => rule.requestsPerMinute),
+				observed: reported.requestsPerMinute
+			}, {
+				dimension: "tokens",
+				declared: declaredOf((rule) => rule.tokensPerMinute),
+				observed: reportedTokens
+			}];
+			for (const { dimension, declared, observed } of dimensions) {
+				if (declared === void 0 || observed === void 0 || declared <= observed) continue;
+				const key = `quota-drift:${dimension}:${observation.provider}:${observation.model}`;
+				if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.scope === state.scope && entry.key === key)) await internals.replayer.appendSinglePhase({
+					scope: state.scope,
+					key,
+					kind: "decision",
+					status: "ok",
+					spanId,
+					value: {
+						decisionType: "quota_drift",
+						provider: observation.provider,
+						model: observation.model,
+						...internals.quota?.tenant === void 0 ? {} : { tenant: internals.quota.tenant },
+						dimension,
+						declaredPerMinute: declared,
+						reportedPerMinute: observed
+					}
+				});
+				internals.events.emit({
+					type: "log",
+					level: "warn",
+					msg: `declared quota exceeds the provider-reported limit: ${observation.provider}:${observation.model} ${dimension} declared ${String(declared)}/min, the provider reports ${String(observed)}/min; the limiter under-throttles and live 429s follow (journaled decision 'quota_drift')`
+				}, spanId);
+			}
+		}
 		const collectAndDisposeWorktree = async () => {
 			if (acquired === void 0) return;
 			try {
@@ -15651,6 +15723,7 @@ function validateOrchestrateOptions(opts) {
 			seen.add(validator.name);
 		}
 		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "orchestrate finishValidation.maxRepairs");
+		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "orchestrate finishValidation.repairTurnReserve");
 		const contract = fv.contract;
 		if (contract !== void 0) {
 			const shape = contract;
@@ -16756,7 +16829,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			},
 			[kTerminalTool]: {
 				name: FINISH_TOOL_NAME,
-				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : { validate: validateFinish }
+				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : {
+					validate: validateFinish,
+					...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
+				}
 			},
 			...(() => {
 				const priorCancelledRoot = internals.replayer.snapshot().filter((entry) => entry.kind === "agent" && entry.scope === callingState.scope && entry.status === "cancelled" && entry.checkpointRef !== void 0).at(-1);
@@ -17056,7 +17132,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...spec.estCost === void 0 ? {} : { estCost: spec.estCost },
 				[kTerminalTool]: {
 					name: FINISH_TOOL_NAME,
-					...validationSpec === void 0 ? {} : { validate: validateFinish }
+					...validationSpec === void 0 ? {} : {
+						validate: validateFinish,
+						...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
+					}
 				}
 			};
 			const synthesized = await runtime.runInScope(synthesisState, () => ctx.agent(prompt, synthesisOpts));
@@ -17136,7 +17215,40 @@ function makeOrchestratorWorkflow(goal, opts) {
 		if (validationTermination !== void 0) throw validationTermination;
 		if (orchestratorAccount !== void 0) internals.cost.orchestrator.spentUsd = internals.budget.accountView(orchestratorAccount)?.spentUsd ?? 0;
 		if (result.status !== "ok") throw new ConfigError(`the orchestrator agent terminated with status '${result.status}'` + (result.errorMessage === void 0 ? "" : `: ${result.errorMessage}`));
-		if (opts?.acceptance === void 0) return await runSynthesis(result.output);
+		/**
+		* The synthesis failure enrichment (the v1.71 experiment review,
+		* P0.8 remainder + P1.7): every typed failure a synthesis
+		* invocation throws gains the verdict-derived repair taxonomy read
+		* from the JOURNALED validation decisions (identical live and on
+		* replay), and, when an acceptance verdict exists, the acceptance
+		* snapshot the children already earned; the completion mirror then
+		* lifts completion and childStatusCounts onto the error outcome,
+		* exactly like the acceptance rejection path. The experiment's
+		* outcome showed completion null beside four accepted children;
+		* these are the fields that say "the fan-out work is complete, the
+		* failure is downstream". The rejection-past-the-bound error keeps
+		* its own repairsUsed/maxRepairs/failed untouched.
+		*/
+		const enrichSynthesisFailure = (thrown, snapshot) => {
+			if (!(thrown instanceof FailRunError)) throw thrown;
+			const base = thrown.data ?? {};
+			const spent = validationDecisions().filter((candidate) => candidate.verdict !== "accepted");
+			const rejectedValidators = [...new Set(spent.flatMap((candidate) => candidate.failed.map((f) => f.name)))];
+			throw new FailRunError(thrown.message, { data: {
+				...base,
+				...snapshot ?? {},
+				...spent.length === 0 || base.repairsUsed !== void 0 ? {} : {
+					repairsUsed: spent.length,
+					maxRepairs: validationSpec?.maxRepairs ?? 1,
+					rejectedValidators
+				}
+			} });
+		};
+		if (opts?.acceptance === void 0) try {
+			return await runSynthesis(result.output);
+		} catch (thrown) {
+			return enrichSynthesisFailure(thrown);
+		}
 		const acceptanceKey = "acceptance";
 		const priorAcceptance = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === acceptanceKey);
 		let decision;
@@ -17209,8 +17321,17 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...decision.synthesisSkipped === void 0 ? {} : { synthesisSkipped: decision.synthesisSkipped }
 			} });
 		}
+		let synthesizedFinal;
+		try {
+			synthesizedFinal = await runSynthesis(result.output);
+		} catch (thrown) {
+			enrichSynthesisFailure(thrown, {
+				completion: decision.completion,
+				childStatusCounts: decision.childStatusCounts
+			});
+		}
 		return {
-			result: await runSynthesis(result.output),
+			result: synthesizedFinal,
 			completion: decision.completion,
 			childStatusCounts: decision.childStatusCounts,
 			degradedReasons: decision.degradedReasons,
@@ -17351,6 +17472,8 @@ function preflightEstimate(input) {
 	const maxDepth = engine.budgetDefaults?.maxDepth ?? 1;
 	const perRun = engine.concurrency?.perRun ?? 12;
 	const runLimits = mergeUsageLimits(void 0, input.run?.limits, defaults.limits);
+	const finishRepairReserve = input.finishValidation?.repairTurnReserve ?? 0;
+	const coordinationRepairReserve = input.orchestrator?.synthesis === void 0 ? finishRepairReserve : 0;
 	let orchestratorEcho;
 	let reservedForFinalizationUsd = 0;
 	let effectiveCapUsd;
@@ -17371,7 +17494,7 @@ function preflightEstimate(input) {
 			finalizeReserveUsd,
 			finalizeTurns,
 			reserveCommitted,
-			projectedProviderTurns: projectedProviderTurnsOf(echoLimits, overallExecutedCeiling(echoLimits, toolCeilingsOf(echoLimits)))
+			projectedProviderTurns: projectedProviderTurnsOf(echoLimits, overallExecutedCeiling(echoLimits, toolCeilingsOf(echoLimits))) + coordinationRepairReserve
 		};
 		if (spec?.capUsd !== void 0 && spec.capFraction === void 0 && effectiveCapUsd !== void 0 && effectiveCapUsd < spec.capUsd) say({
 			severity: "warning",
@@ -17589,7 +17712,7 @@ function preflightEstimate(input) {
 				model,
 				inputFloor: input.orchestrator.estInputTokens ?? 0,
 				outputBound: outputBound ?? 0,
-				turns: projectedProviderTurnsOf(orchLimits, overallExecutedCeiling(orchLimits, toolCeilingsOf(orchLimits))),
+				turns: projectedProviderTurnsOf(orchLimits, overallExecutedCeiling(orchLimits, toolCeilingsOf(orchLimits))) + coordinationRepairReserve,
 				count: 1
 			});
 			if (effectiveCapUsd !== void 0) orchestratorReserveUsd = Math.max(0, orchestratorAdmissionEstCostUsd(effectiveCapUsd, reservedForFinalizationUsd));
@@ -17601,6 +17724,38 @@ function preflightEstimate(input) {
 				flatReserveUsd
 			});
 		}
+		if (input.orchestrator.synthesis !== void 0) {
+			const synthesis = input.orchestrator.synthesis;
+			if (synthesis.limits !== void 0) validateUsageLimits(synthesis.limits, "preflight orchestrator.synthesis.limits");
+			if (synthesis.estInputTokens !== void 0) requireNonNegativeInteger(synthesis.estInputTokens, "preflight orchestrator.synthesis.estInputTokens");
+			const servedBy = resolveServing(synthesis.model) ?? resolveServing(defaults.routing?.synthesize);
+			if (servedBy === void 0) say({
+				severity: "error",
+				code: "unrouted-role",
+				message: "the synthesis invocation resolves no model for role 'synthesize': set defaults.routing.synthesize or a synthesis model on the call",
+				spawn: "synthesis"
+			});
+			else {
+				const caps = capsOf(servedBy);
+				const merged = mergeUsageLimits(synthesis.limits ?? { maxTurns: 4 }, void 0, defaults.limits);
+				const outputBound = caps === void 0 ? merged.maxOutputTokensPerTurn : merged.maxOutputTokensPerTurn === void 0 ? caps.maxOutputTokens : Math.min(caps.maxOutputTokens, merged.maxOutputTokensPerTurn);
+				const projected = projectedProviderTurnsOf(merged, overallExecutedCeiling(merged, toolCeilingsOf(merged))) + finishRepairReserve;
+				if (orchestratorEcho !== void 0) orchestratorEcho.synthesis = {
+					projectedProviderTurns: projected,
+					servedBy
+				};
+				const { adapterId, model } = parseModelRef(servedBy);
+				shapes.push({
+					label: "synthesis",
+					provider: adapterId,
+					model,
+					inputFloor: synthesis.estInputTokens ?? 0,
+					outputBound: outputBound ?? 0,
+					turns: projected,
+					count: 1
+				});
+			}
+		}
 	}
 	const wave = [];
 	let committed = 0;
@@ -17807,6 +17962,7 @@ function preflightEstimate(input) {
 			if (typeof validator.validate !== "function") throw new ConfigError(`preflight finish validator '${validator.name}' has no validate function`);
 			names.add(validator.name);
 		}
+		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "preflight finishValidation.repairTurnReserve");
 		if (fv.contract !== void 0) {
 			for (const contractValidator of fv.contract.validators) if (!names.has(contractValidator.name)) findings.push({
 				severity: "error",
@@ -18744,7 +18900,8 @@ function createEngine(options) {
 	const quotaRuntime = options.quota === void 0 ? void 0 : {
 		limiter: options.quota.limiter,
 		...options.quota.tenant === void 0 ? {} : { tenant: options.quota.tenant },
-		onLimiterError: options.quota.onLimiterError ?? "deny"
+		onLimiterError: options.quota.onLimiterError ?? "deny",
+		...options.quota.declaredRules === void 0 ? {} : { declaredRules: options.quota.declaredRules }
 	};
 	const knowledgeStore = options.stores?.modelKnowledge;
 	const knowledge = knowledgeStore === void 0 ? void 0 : { current: () => knowledgeStore.current() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.72.0",
+  "version": "1.74.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",