Monetization Scaffold Wave

Agent workflow: follow README.md for Audit -> Investigate -> Code -> Test -> Fix; keep this pack's writable scope and verification commands authoritative.

Dispatch type: orchestrator

Owner: orchestrator plus one worker per service after this plan is accepted.

Goal:

Scaffold billing, wallet, usage, and payment services before any AZ Credits, subscription, payment, or quota route cutover. Public /api/wallet, /api/hooks, subscription, and payment routes remain legacy-proxied until parity evidence is complete.

Legacy source evidence:

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/wallet/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/payment/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
• monetization frontend callers under /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web.
• shared native event contract in contracts/events/README.md.

Writable files:

• services/billing-service/**
• services/wallet-service/**
• services/usage-service/**
• services/payment-service/**
• contracts/openapi/services/billing-service.yaml
• contracts/openapi/services/wallet-service.yaml
• contracts/openapi/services/usage-service.yaml
• contracts/openapi/services/payment-service.yaml
• docs/api/billing-service.md
• docs/api/wallet-service.md
• docs/api/usage-service.md
• docs/api/payment-service.md
• docs/agents/service-tasks/monetization-scaffold-wave.md

Orchestrator-owned files:

• Gateway route cutovers, shared Compose/Helm/K8s/migrator/Prometheus wiring, cross-service event contracts, and frontend/browser smoke artifacts. Use docs/agents/service-tasks/monetization-broker-transport.md for the separate shared broker transport handoff after the HTTP sink rehearsal is stable.

Service order:

1. payment-service: payment orders, provider transactions, webhooks, idempotency, reconcile. Foundation scaffold is now present with memory store, pgx/Postgres store, migration, OpenAPI, and focused webhook replay tests. It records payment.order.paid.v1 with the contract payload; external event bus wiring remains pending.
2. wallet-service: immutable AZ Credit ledger, balances, grants/debits/refunds, admin review states. Foundation scaffold is now present with memory store, pgx/Postgres store, migration, OpenAPI, and focused ledger replay tests; payment.order.paid.v1 top-up consumer replay is covered; top-up request, withdrawal, and admin review workflows are present. The opt-in NATS subscriber now reuses the same payment/top-up and billing/subscription-credit handlers while HTTP event endpoints remain rollback fallback.
3. billing-service: plans, subscriptions, invoices, commercial entitlements. Foundation scaffold is now present with memory store, pgx/Postgres store, migration, OpenAPI, and focused subscription/payment replay tests. It consumes payment.order.paid.v1 for subscription activation and records billing.subscription.activated.v1 plus billing.entitlements.updated.v1 outbox rows; plan seeding and outbox publishing are present. The opt-in NATS subscriber now reuses the same payment.order.paid.v1 activation handler while HTTP event endpoints remain rollback fallback.
4. usage-service: feature gates, quota counters, check/consume/reset APIs. Foundation scaffold is now present with memory store, pgx/Postgres store, migration, OpenAPI, focused consume replay/quota/override tests, and service-owned limit override/counter tables. It consumes billing.entitlements.updated.v1 with processed-event replay and stale snapshot guards. The opt-in NATS subscriber now reuses the same entitlement sync handler while gateway rehearsal and runtime parity remain pending.

Shared scaffold requirements:

• cmd/server, internal/domain, internal/usecase, internal/repository, internal/http, service-local migrations, README.md, api/openapi.yaml.
• Contract mirror in contracts/openapi/services/<service>.yaml.
• Dockerfile/Compose/Helm/K8s/migrator/Prometheus wiring only after the service builds and has focused tests.
• Default gateway routes stay legacy.
• Broker replacement work is delegated to docs/agents/service-tasks/monetization-broker-transport.md; do not promote the HTTP event sink as the final transport.

Acceptance:

• No service reads another service database.
• Webhook replay and wallet ledger operations are idempotent.
• Billing activation flows through payment events and is idempotent.
• Usage/quota checks do not leak into AI/import/file/IAM/Profile services.
• Integrated event-chain proof covers payment.order.paid.v1 fanout to billing and wallet, billing.entitlements.updated.v1 fanout to usage, and billing.subscription.activated.v1 fanout to wallet before public payment, wallet, subscription, or quota routes move native.
• Route guards prove /api/wallet*, /api/hooks/sepay-payment, /api/wallet/webhooks/sepay, and public subscription routes remain legacy-proxied until the named gateway rehearsal, browser/runtime proof, and rollback evidence exist.
• The first monetization wave has native foundations for payment, wallet, billing, and usage, but public route groups remain legacy until adapters and live parity evidence exist.
• The HTTP sink is a rehearsal/fallback path only; broker transport selection, replay, dead-letter, Compose/K8s runtime proof, and rollback notes are tracked in docs/agents/service-tasks/monetization-broker-transport.md.

Verification:

• GOTOOLCHAIN=go1.25.11 go test ./services/payment-service/...
• GOTOOLCHAIN=go1.25.11 go test ./services/wallet-service/...
• GOTOOLCHAIN=go1.25.11 go test ./services/billing-service/...
• GOTOOLCHAIN=go1.25.11 go test ./services/usage-service/...
• make test-monetization-event-chain
• make test-monetization-routes
• OpenAPI YAML parse/diff, docker compose -f deploy/docker-compose.yml config --quiet, Helm template/lint, K8s service/migration/observability coverage.