example.billingos-france-sme

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 Alcance 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: 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.

Declaration publication uses contractspec-bun-build types through build:types; build runs bundle and declaration generation. The build config preserves declared exports and excludes test-only files from generated build artifacts. Package tests and typecheck remain separate verification gates.

Full build regenerates JavaScript and declarations in one output transaction, restoring previous dist if either stage fails. Standalone build:bundle still preserves declarations; use full build to reconcile obsolete output layouts.