Handoff: SVC-012-import-route-proof-bundle

Scope

• Dispatch ID: SVC-012
• Service: import-service, implemented by docx-import-service
• Task pack: docs/agents/service-tasks/import-service.md
• Next task: SVC-012-import-route-proof-bundle
• Goal: prove the matching import route rehearsal and review roundtrip before public import route promotion.
• Status: accepted bounded contract slice, not service completion.

Docs Read

• docs/agents/service-tasks/import-service.md
• docs/agents/handoffs/SVC-012-import-list-repository-pagination.md
• docs/agents/service-agent-next-slice-queue.json
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-tasks/import-pdf-ocr-boundary.md
• docs/agents/service-tasks/import-mathtype-conversion-boundary.md
• docs/qa/import-route-rehearsals.md
• docs/qa/import-review-browser-smoke.md
• docs/qa/import-route-proof-bundle.md
• docs/api/docx-import-service.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/ai-import/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/exam-paper-templates.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.import-jobs.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.exam-import-*.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/**
• Legacy source was read-only evidence. No legacy file was changed.

Files Changed

• docs/qa/import-route-proof-bundle.md
• docs/agents/handoffs/SVC-012-import-route-proof-bundle.md
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-agent-next-slice-closeout-ledger.md
• docs/agents/service-agent-accepted-handoffs.md
• docs/agents/service-tasks/import-service.md
• docs/api/docx-import-service.md
• docs/index.md
• docs/.vitepress/config.ts
• docs/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md

Behavior Implemented

• Existing tests prove import create/queue/parse/review save/reload/approve, reviewed parse output precedence, manual question-type overrides, source-location/warning preservation, queue summary ownership, and organization-aware repository pagination.
• Non-default route guards prove matching status, approval, detail, review-save, and combined roundtrip route mappings without changing default traffic.
• On 2026-07-13, the real Teacher editor loaded a completed 28-question Physics job through the non-default Gateway, saved review state, and reloaded it with the manual question-type markers intact. The UI calls only the Gateway route; it does not call docx-import-service directly.
• On 2026-07-14, a fresh local PostgreSQL runtime seeded an unapproved Physics job from an owner-scoped sourceAssetId. The real Teacher editor selected question 7, observed a 200 image/png response through the scoped DOCX Fast asset route, rendered its authenticated Blob URL, then saved and reloaded the first-question review. The source-asset path now issues the native materialized draft token and serves its referenced media asset.
• The same 2026-07-14 disposable browser run selected formula-bearing question 4 and rendered R=8,31J/mol.K with mtef-ole provenance, deterministic confidence, and DOCX OLE source path as plain review text. It then saved and reloaded the identical formula id, LaTeX, and source kind without rendering parser-supplied formula HTML.
• The current Physics candidate also reads exam-import-job-status through the dynamically served route immediately after DOCX Fast creation and after completion. Its two artifacts retain only route/state, echoed correlation ID, and status counters; bearer, organization, job ID, warning, and error text remain redacted.
• The same disposable runtime now begins at the actual Teacher file input. It proves source upload -> matching opaque asset in DOCX Fast create -> native job-detail polling -> native editor, with all four observed API requests at Gateway. The 2026-07-14 run reached the editor in 2,465 ms; the browser artifact stores only route/state, timing, and an opaque asset hash.
• Required evidence: matching import route proof, live/browser proof, and rollback proof. Route and local browser proof are passed; rollback notes are bounded and default-safe.

Tests And Verification

• GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/... -count=1
• make test-import-status-routes test-import-approval-routes
• make test-import-review-roundtrip-routes test-import-review-roundtrip-live
• IMPORT_REVIEW_ROUNDTRIP_SELF_TEST=1 make test-import-review-roundtrip-live
• WEB_BASE_URL=http://127.0.0.1:<isolated-port> GATEWAY_BASE_URL=http://127.0.0.1:<isolated-port> IMPORT_REVIEW_BROWSER_JOB_ID=<completed-job> IMPORT_REVIEW_BROWSER_AUTHORIZATION='Bearer <teacher-token>' IMPORT_REVIEW_BROWSER_ORGANIZATION_ID=<org> make test-import-review-browser
• DOCX_PHYSICS_GATEWAY_ATTEMPT_LOCAL_POSTGRES_CONFIRM=local-postgres make test-docx-physics-attempt-local-postgres

All bounded commands passed. The current browser artifacts are recorded under output/qa/docx-physics-gateway-attempt-local-postgres-20260714232214/teacher-import-create-browser/ and output/qa/docx-physics-gateway-attempt-local-postgres-20260714232214/import-review-browser/; they are local non-default evidence and do not claim public promotion.

Route State

• Default /api/exam-import* routes remain legacy-proxied.
• Native import status/approval/detail/review routes remain non-default.
• Route state: import route promotion requires matching route, live, browser, and rollback proof.
• Rollback is GATEWAY_ROUTE_TABLE=deploy/gateway/routes.json; remove native rehearsal entries and rerun route coverage plus the matching smoke.

Risks / Blockers

• A deployment-environment rollback rehearsal remains required before a default-route change.
• PDF/OCR/MathType status/download/accounting parity remains future work.
• Import-service must not become the source of truth for approved questions or exam snapshots.

Next Step

Keep the default import routes legacy-proxied, then run the rollback-after- candidate rehearsal in the intended deployment environment before promotion.