Enaptive.Operations

Enaptive-owned operating platform models and catalog abstractions for product portfolio, launch readiness, marketing, sales, services, billing, revenue ledger, lifetime value, and P&L ownership.

This package is intentionally Enaptive-owned and should not move to Core. Product portals and apps consume these projections through the Enaptive API and Enaptive.Api.Clients.

Runtime authority should become the Operations database. Repo-local manifests and seed files are source artifacts that synchronize into the database through a separate sync process.

Billing event imports are Enaptive-owned operational events for usage, subscription, services, license, maintenance, implementation, and launch-pilot revenue review. They are separate from external accounting imports and are designed as the eventual internal authority path for product/runtime billing signals.

Accounting reconciliation contracts are provider-neutral and Enaptive-owned. The first supported external source is QuickBooks lifetime customer revenue. The Operations API supports preview comparison, operator-triggered import batch persistence, reviewable adjustment proposals, and explicit apply for approved proposals.

SaaS factory orchestration contracts are Enaptive-owned operating-platform contracts, not Core package authority. IFactoryTaskService manages durable task creation, claim, completion, attempts, and audit records for Transform, product-scaffold, and Enaptive Ochestrate AgentOps handoffs. The durable implementation stores rows through the Enaptive product database; Core remains limited to thin reusable primitives such as worker loop and wake-signal abstractions.

Production Monitoring

The monitoring product was promoted to top-level Monitor/ as an Enaptive sibling surface (alongside Transform/ and Orchestrate/).

• Core engine: Monitor/Core/Enaptive.Monitor.Core.csproj
• Runner host: Monitor/Runner/Host/Enaptive.Monitor.Runner.Host.csproj
• Tests: Monitor/Tests/Enaptive.Monitor.Tests.csproj

The runner reads Monitor/Runner/Host/production-monitoring.json, checks HTTP and command/process probes, and now supports a flexible provider model (Http, Command/Process, TcpPort, SystemdService, DiskMountFreeSpace, CertificateExpiry, DatabaseQuery, QueueDepth, LogPattern, Heartbeat).

Default critical-incident alerting is Transform app push + email. SMS remains optional/deferred and is only active when routing enables it.

Local dry-run:

dotnet run --project Monitor/Runner/Host/Enaptive.Monitor.Runner.Host.csproj -- --json

Repository Sync

Manual sync proof:

dotnet run --project Operations/SyncRunner/Enaptive.Operations.SyncRunner.csproj -- --workspace ..

Database-backed apply, still manual and local/operator-triggered:

dotnet run --project Operations/SyncRunner/Enaptive.Operations.SyncRunner.csproj -- \
  --workspace .. \
  --store database \
  --migrate \
  --apply

The runner validates area.json and customer.json, produces a deterministic dry-run/apply summary, and writes through IOperationsSyncRepository. The default SyncRunner path remains in-memory for proof/testing. The EF-backed repository lives in Enaptive.Persistence and stores canonical manifests and sync fingerprints through EnaptiveDbContext; the API host uses the same database rows for the Operations catalog, falling back to the proof catalog only when no synced rows are available or the database is unavailable.

Environment registry runtime observations are collected out-of-band by the same runner. Normal API reads use last-known database observations and do not call infrastructure providers inline.

HTTP health/deployment observation sync:

dotnet run --project Operations/SyncRunner/Enaptive.Operations.SyncRunner.csproj -c Release -- \
  --store database \
  --connection-string "$ENAPTIVE_DATABASE_CONNECTION_STRING" \
  --observe-http \
  --apply

DigitalOcean inventory observation sync:

dotnet run --project Operations/SyncRunner/Enaptive.Operations.SyncRunner.csproj -c Release -- \
  --store database \
  --connection-string "$ENAPTIVE_DATABASE_CONNECTION_STRING" \
  --observe-digitalocean \
  --apply

The DigitalOcean mode requires DIGITALOCEAN_TOKEN, DO_API_TOKEN, or --digitalocean-token. The repo wrapper Scripts/run-environment-registry-observation-sync.sh also falls back to the Workspace DigitalOcean loader, which can resolve op://Shared Build Infrastructure/DigitalOcean API Token/credential through the build-stage 1Password service account for unattended local/build-stage runs. It reads droplets, DNS records, and managed database clusters, then writes last-known infrastructure observations. DigitalOcean Spaces bucket listing needs separate S3-compatible Spaces credentials, so Spaces inventory is currently recorded as metadata-only / deferred rather than queried with the DigitalOcean v2 token.

Preferred operator wrapper for local/manual dry-runs:

ENAPTIVE_DATABASE_CONNECTION_STRING='...' \
Scripts/run-environment-registry-observation-sync.sh

The wrapper validates the registry first, runs dry-run mode by default, loads a DigitalOcean token from already-exported environment variables or the 1Password-backed Workspace helper when available, and requires --apply before any database writes.

Accounting Imports

Accounting import persistence stores approved import batches and reconciliation rows in the Enaptive product database:

• accounting_import_batches
• accounting_import_customer_revenue
• accounting_reconciliation_rows
• accounting_adjustment_proposals
• accounting_applied_adjustments
• external_accounting_customer_links
• accounting_fact_import_batches
• accounting_fact_import_invoices
• accounting_fact_import_payments
• accounting_fact_reconciliation_rows
• billing_event_import_batches
• billing_event_import_rows
• factory_tasks
• factory_task_attempts
• factory_task_audit

BillingEventImportService validates internal billing events against known customer, product area, and P&L owner codes, checks amount math, and persists idempotent import batches for operator review. It does not create invoices, payments, or revenue-ledger entries by itself.

Ready billing events can generate review-only proposals. Operators must explicitly approve or reject each proposal; only approved proposals can be applied. Applying an approved proposal is idempotent and creates an immutable applied billing event that the database-backed Operations catalog projects into the revenue ledger and billing summary. This is still not a production accounting cutover and does not create external accounting records.

The import persistence route is idempotent for the same source export and remains separate from revenue-ledger adjustment approval.

QuickBooksLifetimeRevenueImportParser handles the approved CSV export shape for lifetime customer revenue. It produces ExternalAccountingImportBatch contracts that can be previewed and, after operator review, persisted through the import-batch API.

QuickBooksAccountingFactImportParser handles approved invoice and payment CSV exports. It produces provider-neutral ExternalAccountingFactImportBatch records that can be previewed against known operational invoices/payments and persisted as idempotent import batches. Fact import persistence does not update billing projections or the revenue ledger by itself.

Operations/PayloadGenerator/Enaptive.Operations.PayloadGenerator.csproj provides the local/offline operator command that converts reviewed sample CSV or JSON inputs into provider-neutral JSON payloads for the existing preview/import endpoints. It writes JSON to stdout, can also write to a file, validates reviewed internal billing-event batches offline, and does not call the API, persist data, approve proposals, or apply proposals.

The service generates proposals only for amount mismatches on known operational customers. Proposal approval records operator intent; applying an approved proposal is the separate write action that creates immutable applied-adjustment records. The database-backed Operations catalog appends those applied adjustments into operational Adjustments and RevenueLedger projections and recomputes billing summary values. Proposed and rejected proposals are blocked from apply, and repeated apply calls return the original applied record.

External accounting customer links are operator cleanup records for reconciliation findings such as MissingExternalAccountingLink. The API stores source-system/customer-code links, projects QuickBooks customer IDs into database-backed customer records, and then uses those links for future reconciliation matching.

Reviewed sample import artifacts live under Samples/README.md. Operators should use the reviewed files as the source inputs for parser preview and validation, then move to the API import routes only after the reviewed samples produce the expected preview results.

Operator walkthrough highlights:

• Validate reviewed sample parsing using SampleImportArtifactTests in Operations/Tests.
• Generate reviewed API payload JSON locally with dotnet run --project Operations/PayloadGenerator/Enaptive.Operations.PayloadGenerator.csproj -- ... before calling preview/import routes.
• Use reviewed QuickBooks sample data for preview (/api/enaptive/billing/accounting/reconciliation-preview, /api/enaptive/billing/accounting/facts-preview) and explicit import-batch persistence (/api/enaptive/billing/accounting/import-batches, /api/enaptive/billing/accounting/fact-import-batches).
• Use reviewed internal billing-event JSON for preview and explicit import-batch persistence (/api/enaptive/billing/events-preview, /api/enaptive/billing/event-import-batches).
• Worker ingestion supports dry-run and apply modes for reviewed internal billing-event JSON, but proposal review and proposal apply remain explicit operator API actions.
• There is no live QuickBooks sync and no automatic billing apply/cutover path in this walkthrough lane.

SaaS Factory Orchestration

The first concrete factory queue lives in Enaptive:

• API: /api/enaptive/factory/tasks, /claim, /claim-next, /complete, /attempts, /audit
• Typed client: IEnaptiveOperationsClient factory methods
• Portal: Transform /factory/queue
• Worker: Enaptive:FactoryWorker in Worker/Modules/Factory

The queue uses PostgreSQL-backed task, attempt, and audit tables. RabbitMQ wake support is optional acceleration only and does not store orchestration state. This V1 does not introduce Redis, Kafka, NATS, Azure Service Bus, Ollama, Claude, or any LLM provider integration.

See SaaS-Factory-Orchestration-V1.md.