# BillingOS V0 package

Additive BillingOS V0 surface. Core contracts stay country-neutral; France-specific readiness lives only in `@lssm-tech/lib.billing-france`. Runtime helpers are deterministic, backend-neutral, provider-free, and do not execute high-impact billing actions.

France readiness metadata is not PA accreditation, production PA submission, legal advice, or tax advice.

## CompanyOS module proof

The example exports `./companyos` as a first-class CompanyOS V1 operating-loop composition for BillingOS France SME. It models finance-owner authority, draft/dry-run-only agent operations, operator inbox routing, work graph hooks, and weekly review evidence around the replayed quote -> invoice -> payment -> France readiness path. Production invoice submission and France e-invoicing submission stay approval-gated; the module contains no provider credentials, network calls, or autonomous high-impact execution.

## Preview / export workflow

BillingOS France SME previews must stay deterministic, backend-neutral, provider-free, and approval-gated. The current `./ui` export wraps local quote-to-invoice, payment/reconciliation, France readiness, and CompanyOS approval-packet screens in the shared `NestedCommandShell` from `@lssm-tech/lib.example-shared-ui`; keep that reusable nested-safe shell as the outer preview frame for compatible BillingOS UI work. Preview screens must not introduce production PA submission, provider credentials, payment processing, legal/tax advice, or autonomous high-impact billing execution.

Keep the France readiness pack as metadata and replay proof only. Preview docs, release notes, and `/llms*` guidance must repeat that the package is not PA accreditation and does not execute production e-invoicing.

## Data-fetching engine integration

`src/proof/data-fetching-integration.test.ts` proves BillingOS drives the canonical data-fetching engine (`@lssm-tech/lib.contracts-runtime-core` + `@lssm-tech/lib.contracts-runtime-server-rest`) end-to-end without weakening the safety model. All engine wiring lives in that `.test.ts` harness on purpose: the production example files must stay free of `fetch(`/`process.env`/credential literals (enforced by `safety.test.ts`), so the proof uses the real `createRestTransport` driven by an in-memory `fetch` double — deterministic, provider-free, no network.

The proof asserts: the `QueryResultEnvelope` read path (no `422`); one admitted draft mutation via `submitBillingMutation`; the admission gate parametrized over the **entire** `BillingActionKind` union (only `read`/`draft_quote`/`draft_invoice` reach `engine.mutate`; all 11 approval-gated kinds fail closed to a `pending approval` operator-review with no optimistic write); server-wins conflict rollback (never a silent overwrite); and offline queue-then-replay on reconnect.

Two decisions are load-bearing and documented in [`specs/billingos-consumer-guide/09-data-fetching-integration.md`](../../../specs/billingos-consumer-guide/09-data-fetching-integration.md): **draft writes carry no `versionToken` this pass** (the event-log `version` is never mapped to the engine etag), and **pending-approval is not an optimistic / read-your-writes state** (approval-gated actions perform no local write). Production hosts inject a real `Transport`; the example never executes providers or production PA submission.

## UI boundary

The preview UI is intentionally thin. It adapts the French SME fixture data into reusable workspaces from `@lssm-tech/module.billing-os/ui`, including quote creation/editing, invoice review, payment reconciliation, France readiness, and CompanyOS review screens. Example-local UI should stay limited to data mapping and preview shell wiring.