Usage, billing, and cost controls

Ethen exposes usage concepts and cost-oriented surfaces, but the repository explicitly states that billing is not implemented. Billing readiness is demo-only, the credit ledger and usage-event availability are false in the billing type, and plans, payment methods, invoices, and a customer portal are absent.

The guidance below separates usage and estimates from charges, contractual quotas, and production financial controls.

Usage model

A usage event records consumption such as requests, tokens, media operations, voice activity, or other product-specific work when the runtime emits it. Ownership may be user, project, organization, or another context, but complete attribution is not established across every product.

Usage surfaces can be useful for operational review even when billing is unavailable. Check whether the data is durable, local, fixture, bridged, or missing before using it for decisions.

A displayed count should not be assumed invoice grade. Validation-count drift and incomplete product coverage remain open issues.

Event ownership and completeness

A useful usage event needs a stable owner, product, operation, unit, amount, timestamp, and source. Token usage can belong to a Gateway request, media generation can belong to a Studio job, and voice usage can belong to a speech request. Those records should not be combined without preserving their unit and producer.

Completeness depends on every runtime writing the event and the store accepting it. A missing row can represent no usage, a failed write, an unsupported runtime, or an unavailable backend. Dashboards should avoid converting missing information into zero.

Where usage is kept only in memory, local storage, or fixtures, state that limitation before using the total for cost or budget decisions.

Reconciliation checks

Compare a sample of Ethen usage records with the closest provider-side record where available. Differences can reveal missing retries, failed writes, unit conversion errors, or ownership gaps. The comparison is an operational check, not a billing reconciliation feature.

Record whether the provider number reflects a request, token, second, image, or another unit. Do not combine units into one total without a defined conversion.

Time and duplication

Usage records need a clear event time and idempotency strategy. Retries in the metering path can duplicate an event, while failures can omit it. Universal usage-event deduplication is not proven.

When a total matters operationally, compare event identifiers and producer behavior rather than assuming every row is unique.

Usage ownership should remain stable enough to support later review. If a record lacks a reliable user, project, or deployment owner, label that gap instead of assigning the event retroactively from the dashboard context.

Billing

Current billing is demo-only. There is no verified Stripe integration, product and price catalog, checkout, subscription lifecycle, invoice generation, payment-method management, customer portal, refund process, or receipt system.

The /billing route can demonstrate a future or placeholder experience. It must not be presented as a way to purchase, cancel, pay, or retrieve an invoice.

Pricing shown on a marketing route is not proof of configured billing or a binding charge.

Demo-only boundary

The billing type identifies readiness: demo-only, creditLedgerAvailable: false, and usageEventsAvailable: false. That posture means the product can present concepts and interface states without processing payment or maintaining a customer financial ledger.

Do not enter real payment information into a demo surface. Do not describe a displayed plan, credit amount, or cost as purchased entitlement. The absence of Stripe, products, prices, webhooks, customers, subscriptions, invoices, payment methods, and a portal prevents a production billing lifecycle.

A future billing implementation will also need customer ownership, tax and refund decisions, reconciliation, webhook integrity, and legal review. None should be inferred from the current route.

Preconditions for live billing

Production billing would require trusted customer ownership, approved products and prices, secure checkout, verified webhooks, subscription state, invoices and receipts, payment-method handling, refunds and cancellations, tax decisions, and durable metering. None of those capabilities is established by the current demo route.

The most accurate current statement is that billing is not implemented. Preserve that boundary in every related page and interface.

Cost attribution

Cost attribution links consumption to a stable owner and a trusted price. Both parts can be incomplete. A runtime may emit tokens without a verified provider price, or a cost estimate may exist without durable user or project ownership.

Observability can aggregate costs when present, but those values remain estimates. They should be labeled with their source and should not be reconciled as invoices.

Provider billing records remain the authoritative external source for charges from a BYOK account.

Attribution chain

To attribute an estimate, connect:

1. the request, job, or run;
2. the product and capability;
3. the selected model or provider;
4. measured units such as input and output tokens;
5. the price source and effective time;
6. the customer, user, or project owner;
7. any fallback or retry attempts.

A gap anywhere in that chain weakens the result. If provider price is unknown, the platform cannot produce a trusted monetary estimate. If ownership is missing, it cannot assign the estimate to a customer project. If retries are omitted, the visible request may understate provider use.

BYOK provider dashboards can supply account-level charges, but Ethen must not present those external charges as its own invoice.

Retry and fallback effects

One customer-visible request can create several provider attempts. A retry against the same provider and a fallback to another provider can each consume billable resources. Cost attribution should include attempts when the runtime emits them.

If attempt data is missing, label the estimate incomplete instead of assigning the final response cost as the total by assumption.

If ownership changes after usage occurred, preserve the historical owner used at event time and record the later transfer separately. Rewriting earlier usage under the new owner can distort investigations and future financial reconciliation.

Budgets

Budget concepts can stop or warn about usage in some routes, but atomic enforcement is not proven. A missing backend row, concurrent requests, delayed usage writes, or fail-open behavior can allow actual use to differ from the displayed budget.

Treat a budget as an application control under review, not a guaranteed financial boundary. For strict control, also configure limits in the external provider account where available and monitor provider usage.

Document what happens when the budget store is unavailable and whether the route fails open, fails closed, or becomes setup required.

Concurrency and failure behavior

Suppose two requests check the same remaining budget at nearly the same time. If the check and usage write are not atomic, both can proceed and exceed the intended amount. A dashboard can then show an overage even though each request separately passed its check.

Backend unavailability creates another decision. A fail-open route preserves availability but weakens the budget. A fail-closed route protects the budget but can stop legitimate work. The chosen behavior should be explicit and tested for the route.

Until those guarantees are verified, treat budgets as advisory or best-effort application controls. Use provider-account limits and operational alerts where available for additional protection.

Budget changes are governance events because they alter the amount of work a route can perform. Record the requester, owner, old value, new value, reason, and verification where a durable process exists. The sample audit surface does not prove that these changes are captured automatically.

Ownership and change control

Assign each budget to a stable user, project, or organization owner before relying on it. An unowned budget cannot be reviewed or reconciled when project ownership changes.

Budget increases should receive the level of approval appropriate to the workload. That governance process is not a live billing feature and should remain separate from the demo-only billing surface.

Limits

A limit may be input validation, provider restriction, application guard, rate limit, concurrency bound, or commercial quota. Those categories should not be merged.

No complete platform quota or rate-limit contract is approved. Product-specific handlers may enforce current values, but those values should not be published as permanent plans unless approved.

When a request is rejected, identify the layer that imposed the limit before changing configuration.

Diagnose the rejecting layer

A validation error can indicate an input field or payload is unsupported. A rate limit controls request frequency. A quota controls accumulated allowance. A provider entitlement determines whether the account can use a capability. A budget is a customer-configured spending or usage boundary. A concurrency limit controls simultaneous work.

The remediation differs for each one. Retrying an invalid request will not help; raising an application guard may not change a provider quota; increasing a budget does not grant model entitlement.

Preserve the returned code and route, then consult the product-specific guide. Do not publish a current internal value as an evergreen plan or contractual allowance.

Provider rate and quota errors can change over time with account tier and service conditions. Preserve the provider’s returned error and current account context rather than documenting one temporary value as an Ethen-wide limit.

Optimization

Optimize by selecting the appropriate product, provider, model, modality, and context for the task. Remove unnecessary input, avoid repeated failed requests, and use previews or simulations where they prevent expensive live work.

Use usage and observability records only when their data source is trustworthy. A lower estimate is not a savings claim until the same workload and provider pricing are comparable.

Optimization should not bypass policy, approval, quality, or security boundaries.

Compare like with like

When comparing two routes or providers, use the same input, output requirement, quality threshold, and measurement window. A cheaper result that omits required context or quality is not an equivalent optimization.

Separate controllable waste from necessary work. Repeated invalid requests, oversized context, unnecessary high-cost models, duplicate media generations, and retries caused by misconfiguration are common candidates. Provider fallback can improve availability while increasing cost, so include all attempts.

Use estimates to guide engineering decisions, then confirm external provider charges through the provider account. No Ethen invoice or production credit ledger is available.

Optimization should also consider operational reliability. A route with frequent retries, missing telemetry, or unclear provider selection can cost more to operate even when the nominal model estimate is lower. Fix configuration and evidence gaps before drawing conclusions from a narrow price comparison.

Keep a baseline before changing models or routing. Compare quality, failure rate, latency, and total attempts as well as the estimated unit cost, and state when any metric is unavailable.