Handoff: SVC-018-quota-caller-contract-fixtures usage-service quota caller contract fixtures

Scope

• Service/area: usage-service
• Task pack: docs/agents/service-tasks/usage-service.md
• Goal: accept the bounded SVC-018 quota caller contract fixture slice for AI/import/file/question/course callers while keeping wallet debit and workload execution outside usage-service.
• Non-goals: public/default route promotion, live browser proof, wallet AZ Credit debit/grant orchestration, billing renewal mutation, payment provider reconciliation, workload service integration code, rolling-window parity, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/architecture/legacy-api-map.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-tasks/usage-service.md
• go-platform/docs/agents/service-tasks/billing-service.md
• go-platform/docs/agents/service-tasks/wallet-service.md
• go-platform/docs/agents/service-tasks/monetization-broker-transport.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/api/usage-service.md
• go-platform/docs/qa/monetization-broker-live-smoke.md
• go-platform/docs/qa/service-agent-readiness-smoke.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/wallet/az-credit.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/wallet/az-credit-business.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/questions/question-generation.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/questions/question-solution.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exams/exam-core.service.ts
• Legacy source was read-only evidence only; no legacy files were changed.

Files Changed

• go-platform/docs/agents/handoffs/SVC-018-quota-caller-contract-fixtures.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• none in this handoff.
• Existing audited usage-service fixtures cover the named HocTapAZ quota callers through POST /v1/usage/check: AI credits/tokens, OCR/import pages, storage bytes, question bank size, course/import concurrency, and admin limit overrides.
• Existing audited consume path covers idempotent usage event replay and quota denial without double-incrementing counters.
• Existing audited entitlement ingestion covers billing billing.entitlements.updated.v1 event replay, stale snapshot rejection, and sourceSubscriptionEventId audit linkage.
• Existing audited docs state wallet debit/grant orchestration remains outside usage-service; usage-service returns feature gate/check/consume decisions only and does not move money or execute workload jobs.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/usage-service/... -count=1
• Result: passed.
• Evidence: usage-service packages passed, including HTTP, usecase, repository, and eventfanout tests.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/usage-service/internal/http -run 'TestUsageFeatureKeyFixturesCoverHocTapAZCallers|TestUsageConsumeReplayAndQuotaDenial|TestUsageOverridePrecedenceAndReset' -count=1 -v
• Result: passed.
• Evidence: focused caller fixtures covered AI monthly/weekly/hourly credits, AI tokens, OCR pages, batch import pages, storage bytes, question count, concurrent jobs, override precedence, reset, consume replay, and quota denial.
• Command: make test-monetization-event-chain
• Result: passed.
• Evidence: payment, billing, wallet, and usage event-chain packages and coverage script passed.
• Command: make test-monetization-broker-transport
• Result: passed.
• Evidence: broker transport coverage, broker smoke self-test, eventfanout package tests, and monetization outbox tool tests passed.
• Command: USAGE_SERVICE_POSTGRES_TEST_DATABASE_URL=postgres://... GOTOOLCHAIN=go1.25.11 go test ./services/usage-service/internal/repository -run TestPostgresUsageConsumeReplayIntegration -count=1 -v
• Result: not run.
• Evidence: optional Postgres integration requires an external DSN that was not provided in this local handoff run.

Route State

• Legacy route: public wallet, subscription, payment hook, AI/import, file/storage, and question routes remain legacy-proxied by default.
• Native route: /v1/usage/check, /v1/usage/consume, /v1/entitlements/*, /v1/limit-overrides, /v1/usage/reset, and /v1/events/billing-entitlements-updated remain service-to-service/native rehearsal routes.
• Gateway state: no default route table was changed. The first public quota caller route still needs an explicit gateway/service rehearsal and live/browser proof before promotion.
• Rollback: keep deploy/gateway/routes.json as the active route table. If caller contract regressions appear, revert caller fixtures or usage-service check/consume behavior without moving debit logic into usage-service.

Data Notes

• Tables touched: none in this handoff run; tests used in-memory stores unless package tests exercised repository code without a live Postgres URL.
• Migration run: none.
• Validation report: not applicable because no live data was migrated or backfilled.

Risks / Blockers

• SVC-016 now has accepted bounded renewal-mutation evidence, but billing remains not-complete; this handoff relies only on existing billing entitlement event-chain proof, not a completed public renewal flow.
• Wallet debit/grant orchestration remains future wallet/workload integration work and must not be added to usage-service.
• Current native period behavior is UTC bucketed windows, not legacy rolling-window parity. Route cutovers that require exact rolling behavior need a separate migration slice.
• The disposable Postgres entitlement/replay runner removes the external-DSN blocker for repository persistence checks. Its dynamic-loopback database and cleanup are isolated. Its current advisory-lock test is fresh Postgres proof that concurrent old/new entitlement snapshots retain the newer final limit, but it does not prove real broker runtime delivery, public/default routes, browser behavior, production data behavior, or legacy rolling-window parity.
• No public/default route promotion or browser proof is accepted here.

Disposable Postgres Replay Runner

Run USAGE_ENTITLEMENT_REPLAY_POSTGRES_CONFIRM=disposable-postgres ./scripts/test/usage-entitlement-replay-postgres-isolated.sh to create a postgres:16-alpine container on a dynamic 127.0.0.1 port and execute ^TestPostgresUsage.*(Entitlement|Replay).*$. The runner unsets DATABASE_URL, does not accept a caller test DSN, and removes the container on exit. This scope is limited to usage-service repository entitlement/replay persistence; it does not extend the accepted caller-fixture or route proof.

Next Step

• Pick one real workload caller, such as AI generation or OCR import, add a non-default gateway/service rehearsal against usage-service, and attach live request/response plus rollback artifacts before considering any public route change.