Rulvar API reference / @rulvar/rulvar / EngineQuotaConfig
Interface: EngineQuotaConfig
Defined in: packages/core/dist/index.d.ts
createEngine quota config: the limiter plus its engine-scoped knobs.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
declaredRules? | readonly QuotaRule[] | 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. | packages/core/dist/index.d.ts |
limiter | QuotaLimiter | - | packages/core/dist/index.d.ts |
maxDenials? | number | The denial retry budget (RV1601): how many pre-wire quota denials one dispatch tolerates per serving target before the denial takes the exhaustion path (failover when the chain names a rate-limit trigger, else the typed rate-limit terminal). Denials stopped consuming RetryPolicy.attempts in RV1601: that budget counts DISPATCHED tries only, so a busy window can no longer exhaust the transport budget before the wire ever opens (the eighteenth comparison benchmark measured 21 denials riding the transport namespaces). Each denied turn still waits the limiter's own retryAfterMs first. Default DEFAULT_MAX_QUOTA_DENIALS. | packages/core/dist/index.d.ts |
onLimiterError? | "allow" | "deny" | What a limiter infrastructure FAILURE (reserve throwing) means: 'deny' (default, fail closed) converts it into a retryable transport-class denial; 'allow' logs a warning and dispatches without a reservation. A limiter DENIAL is unaffected by this knob. reconcile failures only ever warn. | packages/core/dist/index.d.ts |
reserveContinuations? | boolean | The opt-in hard mode for provider-side continuations (RV1013). Default off: a dispatch reserves ONE request and a multi-wire absorption (pause_turn) settles its true wire count post-hoc, which is accounting, not admission: the continuations already left. With reserveContinuations: true the engine reserves each continuation in the limiter BEFORE its egress through the adapter-side StreamHooks seam: under a hard provider RPM cap the over-cap wire never leaves (the denial rides the provider-429 machinery), a granted admission whose wire never left is released back to the window where the limiter implements release, and the post-hoc settlement stops re-adding individually admitted segments so the window is never double-counted. Adapters unaware of the hook keep the post-hoc semantics exactly. | packages/core/dist/index.d.ts |
tenant? | string | Stamped on every reservation of this engine's runs. | packages/core/dist/index.d.ts |
tenantFrom? | "scope" | "engine" | Where the reservation tenant comes from (RV4205). 'engine' (the default, historical bytes): the tenant above. 'scope': the RUN's recorded ExecutionScope.tenant, so one engine serving many tenants debits each run's reservations to the tenant the run declared; a run whose scope names no tenant reserves tenant-less, exactly like an engine that set none. | packages/core/dist/index.d.ts |