OCR Usage Wallet Contract Proof

Scope

This proof covers the disabled-by-default accounting path for internal ocr-document jobs in docx-import-service:

docx-import-service -> usage-service check -> wallet balance read
  -> Mistral OCR provider -> usage-service check + wallet balance read
  -> wallet USAGE_DEBIT -> usage-service consume

It does not make import-service the owner of usage counters, AZ Credits, or provider credentials. It does not add a public Gateway/BFF route.

Contract

• The adapter is disabled unless DOCX_IMPORT_OCR_USAGE_WALLET_ENABLED=true.
• Before the provider call it checks one ocr_pages_monthly unit and verifies at least DOCX_IMPORT_OCR_CREDITS_PER_PAGE available AZ Credits.
• A quota denial happens before Mistral is called.
• After a usable result, settlement uses the actual len(result.Pages) count, not the preflight estimate. Its exact-page quota check and wallet-balance read run concurrently because both are read-only owner-service calls; a usage error or denial still takes precedence, and neither mutation starts until both checks pass. It then writes a wallet USAGE_DEBIT and consumes the same ocr_pages_monthly amount through the owner APIs.
• The job ID is the idempotency boundary: ocr-import:wallet:{jobId} and ocr-import:usage:ocr_pages_monthly:{jobId}. A reprocess therefore reuses completed owner-service mutations instead of debiting twice.
• If settlement fails after a provider result, the job is failed without a review payload. An explicit retry can call the provider again, but it retains the owner-service idempotency keys.

Enabled configuration requires USAGE_SERVICE_BASE_URL, WALLET_SERVICE_BASE_URL, a positive DOCX_IMPORT_OCR_CREDITS_PER_PAGE, and a positive DOCX_IMPORT_OCR_MONETIZATION_TIMEOUT_MS. Invalid enabled configuration exits the process before it serves OCR work.

Verification

make test-import-pdf-ocr-workflow
GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/... -count=1

The target uses in-process HTTP owner-service doubles and a Mistral-compatible provider adapter. It verifies the concurrent settlement reads, exact two-page settlement, stable debit/consume keys, preflight denial before provider execution, and a failed settlement after provider execution. It does not require a Mistral API key or mutate a real wallet, entitlement, import, question-bank, or exam database.

Rollback

Keep DOCX_IMPORT_OCR_USAGE_WALLET_ENABLED=false to disable the adapter. This does not change deploy/gateway/routes.json, default legacy import routes, stored OCR jobs, or legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.