@lssm-tech/lib.billing-runtime
Pure, backend-neutral BillingOS runtime helpers over @lssm-tech/lib.billing-spec.
France readiness metadata is not PA accreditation, production PA submission, legal advice, or tax advice.
Runtime helpers
@lssm-tech/lib.billing-runtime provides pure helper engines over @lssm-tech/lib.billing-spec:
- quote/order/invoice/payment/reconciliation lifecycle projections;
- deterministic pricing totals with an injected synchronous tax-calculation port;
- local workflow event creation/appending;
- payment-state reconciliation hints;
- draft accounting export shaping;
- deterministic quote-to-cash cockpit projections with lifecycle, approval-packet, surface, and finance-review handoff metadata; and
- agent planning guards that produce approval packets instead of executing high-impact billing actions.
The package performs no network calls, filesystem access, provider SDK calls, credential handling, persistence writes, PA submission, or autonomous production billing execution.
BillingOS truth and FinanceOS handoff
The additive ./truth surface projects normalized billing facts into the append-only economic-evidence lifecycle, provides a tenant-isolated in-memory reference store with revision and idempotency guards, records superseding corrections without deleting history, and validates balanced, company-scoped posting handoffs. A posting handoff remains a proposal until an explicit ContractSpec Connect authorization reference is supplied.
Persistence ports (additive)
Backend-neutral port interfaces that a host implements against its store; the package defines the contracts, never the adapters:
InvoiceRepositoryPort — persist and read issued invoices.EventLogAppendPort — append-only billing workflow event log.InvoiceChainAppendPort — append entries to the per-period invoice hash-chain.CreditNoteRepositoryPort — persist and read credit notes (avoir).
Observability (additive)
BillingObservabilityPort — structured, correlation-id-propagating observability hook for issuance and submission.- Field-level redaction of SIREN/SIRET/VAT identifiers, secrets, and amounts so no sensitive payload is logged; redaction is applied before any sink receives the record.
Service agreements (./service-agreement, additive)
Pure engines and host ports for @lssm-tech/lib.billing-spec/service-agreement:
recordServiceUsage / correctServiceUsage over ServiceUsageLedgerPort: atomic usage + outbox + work-completion transaction; identical replay returns the stored receipt, a changed payload conflicts, corrections supersede the current head without deleting history.recordMeteredServiceUsage over ServicePriceTablePort and
MeteredServiceUsageStorePort: meters one platform service call exactly once per tenant and usage ref, rated by selectServicePriceVersion /
rateServiceUsage against the version effective at the occurrence. It never guesses a price: the call is unpriced until the owner sets one. An optional MeteredServiceBillingPort appends the call to the service usage ledger through recordServiceUsage when the tenant's agreement sells the meter; a replay returns the stored receipt and a changed payload conflicts.
occurredAt is metadata: the first recorded occurrence wins, and a retry after a crash that left the call in the ledger only adopts that ledger event. The bound ledger must scope event ids (usage:<usageRef>) by tenant.
toMeterServiceUsageOutput projects a result onto the
billing.service.usage.meter output; the host emits its
billing.service.usage.metered audit record.
InMemoryServicePriceTable and InMemoryMeteredServiceUsageStore are the reference adapters.computeServiceInvoiceDraft: deterministic, digest-bound drafts per cadence period with frozen price editions; late usage and post-issue corrections become adjustment or credit lines for the earlier period instead of rewriting issued invoices; BYOK never yields passthrough.reserveServiceCapacity / settleServiceReservation / resumeServiceBudget
over a compare-and-set ServiceBudgetStorePort: allowance, approved overage ceiling, bounded grace and pause, plus a separate internal provider budget.buildOnPremUsageBatch / importOnPremUsageBatch: signed digest-only batches with replay, gap, fork, instance-change, key-rotation and clock checks.submitServiceInvoiceOnce / issueServiceInvoice / applyServicePaymentEvent: approved, exactly-once submission (unique per tenant and merchant), approved issue, and idempotent, order-safe payment evidence.openServiceCollection / issueStoredServiceInvoice /
receiveServicePaymentEvent over ServiceCollectionStorePort: collection state per invoice under a row lock; a verified webhook is stored once per merchant and provider event id (redelivery is a duplicate, a changed payload conflicts), and events that arrive before issuance are held and applied at issuance.requireServiceApproval: consequential actions verify an
OperationApprovalReceipt through the host's OperationApprovalPort
(subject, operation key/version, input digest, consumed nonce). A caller-supplied decision string is never authority; with no port bound the action fails closed.
In-memory reference adapters mirror the required host semantics for tests; they are not durable storage. Hosts bind the ports to their database.
