formula-docx-service Agent Tasks

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

Dispatch type: runtime-adapter

Dispatch ID: SVC-013

Runtime classification: service-agent handoff for the parser adapter/runtime contract only. This is not a deployable services/formula-docx-service boundary unless a later ADR promotes it.

Current implementation: source-controlled runtime at runtimes/go-formula-docx behind docx-import-service; this is not currently services/formula-docx-service and runtime changes require a dedicated Formula-runtime task.

Owns: DOCX/formula/table parsing runtime, conversion metrics, deterministic parser output.

Current adapter status: docx-import-service calls the runtime's POST /v1/import/docx/qas endpoint once per source DOCX and maps questions[].equations into import-owned formula refs. MTEF/OMML source kind, LaTeX/MathML, OLE/preview IDs, package path, parser versions, confidence, and review warnings survive review and approval snapshots. The adapter does not own a converted Word Equation DOCX artifact. docx-import-service owns both the internal direct attachment and durable job metadata; generated bytes remain document-service-owned through its internal artifact boundary. The full QAS envelope carries schemaVersion (current corpus fixtures use go-formula-docx-sdk.qas.v1); the compact /v1/import/docx/simple endpoint is a runtime option, not the adapter contract.

Must read:

• docs/agents/handoff-phase-4-go-formula-docx-runtime.md
• docs/agents/handoff-phase-5-docx-parser-benchmark.md
• docs/agents/service-tasks/import-mathtype-conversion-boundary.md
• legacy formula/MathType modules under /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/ and Go Formula callers under /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/.

Legacy source evidence:

• runtimes/go-formula-docx/** is the canonical source-controlled parser runtime.
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/**

Writable files:

• services/docx-import-service/internal/parser/** only for adapter-facing parser contract tests.
• docs/agents/service-tasks/formula-docx-service.md and handoff notes.

Orchestrator-owned files:

• Compose, Helm, K8s, gateway routes, and public API docs unless explicitly delegated.

Initial tasks:

• Audit whether parser runtime should stay embedded/internal or become a deployable service.
• Do not create services/formula-docx-service unless a later ADR promotes the parser runtime into a formal Go-platform service.
• Add benchmark/corpus tasks for MathType, OMML, tables, images, warnings.
• Done: add explicit adapter coverage for deterministic WMF/EMF/OLE/MathType provenance and review-only fallback images. OLE/WMF previews are preserved as formula metadata rather than materialized as browser images.
• Done: sort eligible word/*.xml package parts before direct MathType conversion so fallback warnings persist in a stable order across document, header, footer, and other Word XML parts. The regression converts two parts with distinct fallbacks 128 times per process.
• Run the Formula runtime repeat-compare proof before accepting a parser determinism claim: DOCX_FORMULA_DETERMINISM_CONFIRM=read-only-formula-runtime make test-docx-formula-determinism. It invokes the versioned QAS endpoint twice for the Math and Physics corpus fixtures, hashes the canonical import-visible response without latency, and requires identical fingerprints. It also runs the Go adapter integration proof, which requires byte-identical persisted-review-visible JSON after latency_ms is removed. The proof asserts Math 22/125 (117 MTEF-OLE plus 8 OMML) and Physics 28/84 formula provenance, deterministic flags, non-empty LaTeX, and non-empty MathML. It writes only local QA artifacts and rejects a deployable services/formula-docx-service directory.
• Keep PDF/OCR and MathType job status/download/accounting routes in import-service. Use import-mathtype-conversion-boundary.md for MathType/OLE adapter evidence unless an ADR promotes a formal parser service boundary.
• If the runtime needs new behavior, preserve the exact import-service adapter contract and use a dedicated Formula-runtime task.
• Keep all business approval/review state out of parser runtime.

Acceptance:

• Runtime output is deterministic and versioned enough for import-service review.
• Parser metrics expose latency/warning counts.
• No frontend route calls formula-docx directly.
• OCR/PDF and MathType conversion status/download routes are owned by import-service or a formal adapter, not by frontend direct runtime calls.
• Formula source stays outside ordinary service-agent writable scopes; service tasks may only change adapter tests/docs unless runtime work is delegated.

Verification:

• sh scripts/test/go-formula-runtime-coverage.sh
• DOCX_FORMULA_DETERMINISM_CONFIRM=read-only-formula-runtime GO_FORMULA_DOCX_URL=http://127.0.0.1:8080 HOCTAPAZ_DOCX_CORPUS_DIR=/Users/velikho/Desktop/test-hoctapaz make test-docx-formula-determinism
• GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/internal/parser/docx -count=1
• GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/internal/parser/docx -run '^TestConvertMathTypePackageOrdersWarningsDeterministicallyAcrossWordParts$' -count=100
• GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/...
• Runtime changes need a dedicated delegated task; this pack otherwise limits work to matching import-service adapter tests and documentation.