DOCX Question Bank Approval Usage Proof

Status: local code-level contract proof. It is not a Gateway, browser, provider, or production billing promotion.

Ownership

docx-import-service owns the approval saga checkpoint. question-bank-service owns canonical questions. usage-service owns the questions entitlement and counter. wallet-service is not called by this approval slice.

Legacy evidence is read-only:

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.exam-import-approval.ts checks questions using preparedQuestionPlans.length before approval.
• The legacy DOCX Fast worker only parses and enqueues approval; it has no direct AZ Credit dependency.

Contract

With DOCX_IMPORT_APPROVAL_USAGE_ENABLED=true, import-service requires USAGE_SERVICE_BASE_URL or USAGE_SERVICE_URL and fails closed at startup when the configuration is invalid. The older DOCX_FAST_AUTO_APPROVAL_USAGE_ENABLED flag is a compatibility alias. Every Question Bank approval, including native Teacher review and trusted automatic approval, performs:

1. POST /v1/usage/check for resource questions before Question Bank ingest.
2. Canonical Question Bank ingest with the durable approval operation key.
3. POST /v1/usage/consume with import-approval:usage:questions:{requestDigest}, reference import.approval, and the completed reviewed question count.
4. Persisted APPROVAL_USAGE_CONSUMED before the approval becomes completed.

If quota preflight denies, Question Bank is not called. If consume fails after Question Bank succeeds, a retry resumes from that checkpoint, reuses the same usage idempotency key, and does not re-ingest questions. A completed operation is replay-only.

This deliberately does not add a wallet debit. The legacy approval path gates the questions entitlement but does not debit AZ Credits; OCR is the separate usage/wallet workload.

Deployment Configuration

Compose, raw K8s, and Helm all set DOCX_IMPORT_APPROVAL_USAGE_ENABLED=false and DOCX_IMPORT_APPROVAL_USAGE_TIMEOUT_MS=3000. Enabling the feature requires an explicit deployment override plus a reachable usage-service; an invalid enabled configuration stops import-service before it accepts approval work. make test-docx-approval-usage-config renders Compose and Helm and verifies the canonical defaults alongside the raw K8s manifest.

Teacher Workflow Boundary

The Teacher Gateway candidate intentionally creates DOCX Fast jobs without autoApproveToQuestionBank. It polls the owner-scoped job, opens the native review editor, saves the teacher-reviewed answers/types, then calls the existing Gateway approval route. That preserves the missing-answer guard for real DOCX content. The automatic flag remains an explicit trusted-client/API option; it must not be enabled merely to bypass teacher review.

Verification

GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/internal/usecase ./services/docx-import-service/internal/http \
  -run '^(TestHTTPApprovalUsage.*|TestApprovalUsage.*|TestCreateLegacyDocxFastJobAutoApprovesQuestionBank|TestNewApprovalUsageClientFromEnv)$' \
  -count=1 -v

The focused suite verifies quota denial, stable consume keys, replay behavior, no Question Bank ingest on denial, consume retry without re-ingest, fail-closed configuration, and the HTTP DOCX Fast completion hook.