Import MathType/OLE Conversion Boundary Agent Tasks

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

Status: P4-039 formula provenance bridge, P4-040 direct internal conversion, P4-041 durable MathType artifact jobs, and the isolated candidate Gateway/Teacher browser proof are complete. Accounting, renderer comparison, and default-route/public promotion remain open.

Current native status: DOCX parser integration calls the Go Formula QAS endpoint and maps questions[].equations into import review/approval formula references with LaTeX, MathML, source kind, package path, OLE/preview IDs, parser versions, deterministic/confidence flags, and review-only warnings. POST /v1/import/mathtype/convert now performs a bounded direct conversion: it replaces deterministic mtef-* OLE objects with OMML and returns an ephemeral *-word-equation.docx attachment plus conversion counters. It does not create a job, persist an artifact, expose a download URL, or have a Gateway/frontend route. Unsupported LaTeX produces a linear OMML fallback and requires teacher review; non-deterministic or unmatched formulas remain intact. POST /v1/import/mathtype/jobs now reads the source through document-service, spools it under an import job, stores only a document-service-generated artifact metadata record, and exposes scoped download/reprocess routes. A processing job recovered after restart fails for explicit retry to avoid duplicate artifacts.

Dispatch type: orchestrator

Owner: import-service through services/docx-import-service, with formula-docx-service as a runtime-adapter task pack. This is not permission to create services/formula-docx-service.

Purpose: define the MathType/OLE conversion slice before implementation so formula conversion remains deterministic parser/runtime work and import review/status/download ownership stays in import-service.

Must read:

• docs/architecture/service-responsibility-matrix.md
• docs/agents/service-tasks/import-service.md
• docs/agents/service-tasks/formula-docx-service.md
• docs/agents/handoff-phase-4-go-formula-docx-runtime.md
• docs/agents/handoff-phase-5-docx-parser-benchmark.md
• Legacy formula evidence under:
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/docx-formula-source.service.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/docx-mathtype-equation-converter.service.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/mathtype-mtef-extractor.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/omml-to-latex.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/formula-ocr.service.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/go-formula-docx-import.service.ts
  • /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/go-formula-docx-result-builder.ts

Legacy source evidence:

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/docx-formula-source.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/docx-mathtype-equation-converter.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/mathtype-mtef-extractor.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/omml-to-latex.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/formula-recognition/formula-ocr.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/go-formula-docx-import.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exam-paper-templates/go-formula-docx-result-builder.ts

Writable files:

• services/docx-import-service/internal/parser/**
• services/docx-import-service/internal/usecase/** only when the slice needs import-owned status/review/download state.
• contracts/openapi/services/docx-import-service.yaml
• docs/api/docx-import-service.md
• docs/agents/service-tasks/import-mathtype-conversion-boundary.md
• docs/agents/service-tasks/formula-docx-service.md

Orchestrator-owned files:

• Default gateway route table, shared deploy manifests, VitePress navigation, root Makefile, and route smoke scripts unless explicitly delegated.
• External legacy runtime source under runtimes/go-formula-docx/** is read-only evidence.

Boundary:

• Deterministic formula-source metadata is required: token, source kind, source part path, media/object id, parser version, confidence/review flags, and materialized media refs.
• Supported source kinds must distinguish at least OMML, MathType OLE, MTEF, WMF/EMF/GIF/EPS-carried MTEF, fallback image, and OCR-derived formula candidates.
• Import-service owns conversion job status, review-only warnings, materialized refs, and downloads. Parser runtime owns conversion output and metrics only.
• Business approval and canonical question writes remain question-service/exam-service handoffs.
• OCR/PDF and MathType routes stay under import-service or a documented adapter; frontend must not call parser runtime directly.
• Do not create a deployable services/formula-docx-service without a later ADR.

Initial tasks:

1. Audit legacy MathType/OLE/OMML/MTEF conversion tests and identify the smallest deterministic parity corpus.
2. Done: define native parser contract structs for formula source metadata, conversion warnings, parser version, and OLE/preview media references using the QAS equations[] envelope.
3. Done: add focused parser tests for deterministic MTEF/OLE source metadata, OLE/WMF preview non-materialization, and review-only fallback images. The real Physics/Math corpus keeps 84/125 per-question formula metrics.
4. Done: add a direct internal Word Equation conversion endpoint with a synthetic OLE/preview regression and a real Math fixture structural smoke.
5. Done: add import-service status/download/reprocess and document-service generated artifact ownership for MathType jobs; no service writes object storage directly.
6. Done: add a disposable PostgreSQL browser/Gateway proof for the owner-scoped Teacher candidate. It must upload an opaque sourceAssetId, poll the native job detail, download the artifact, reject cross-teacher operations and raw storageKey, and verify DOCX ZIP/OMML structure. This remains non-default local evidence, not public promotion.
7. Add usage/wallet accounting and visual renderer comparison before any public MathType workflow.
8. Add an ADR request if the current Go Formula runtime must become a deployable Go-platform service; until then, keep it as an adapter runtime behind import-service.

Acceptance:

• MathType/OLE parser output produces deterministic LaTeX/source markers suitable for review save/reload and approval snapshots. The direct endpoint returns a converted DOCX attachment, while the job route persists only document-service-owned artifact metadata and supports scoped download/reprocess.
• Review warnings distinguish converted formulas from unresolved formula images without falsely marking valid WMF/OLE previews as missing display images.
• Parser/runtime metrics include latency, formula count, converted count, unresolved count, and warning count.
• Materialized media refs flow through document/file-service ownership.
• No frontend route or public gateway route points directly at formula-docx runtime.

Verification:

• sh scripts/test/go-formula-runtime-coverage.sh
• make test-docx-corpus test-docx-materialization test-docx-warning-capture test-docx-warning-parity
• DOCX_MATERIALIZATION_SELF_TEST=1 make test-docx-materialization joins the read-only Physics corpus parser output to the materializer without starting import or document services; the normal target remains the live read-back smoke.
• 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/...
• Focused tests for this slice include:
  • TestMapGoFormulaQASResultPreservesMathTypeSourceWithoutMaterializingOLEPreview
  • TestMapGoFormulaQASResultMarksUnresolvedFormulaForReview
  • TestSnapshotFormulaRefsPreservesParserProvenanceAndReviewFlags
  • TestConvertMathTypePackageReplacesDeterministicOLEObjectWithOMML
  • TestMathTypeConvertReturnsConvertedDOCXWithReviewStats
  • TestImportJobServiceEnqueueMathTypeStoresGeneratedArtifact
  • TestMathTypeJobPersistsArtifactAndStreamsScopedDownload
• Real-fixture job smoke (requires the read-only local Go Formula runtime): HOCTAPAZ_MATHTYPE_JOB_INTEGRATION=1 HOCTAPAZ_DOCX_CORPUS_DIR=/Users/velikho/Desktop/test-hoctapaz GO_FORMULA_DOCX_URL=http://127.0.0.1:8080 GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/internal/http -run TestMathTypeJobRealFixtureArtifactWorkflow -count=1
• docs/qa/docx-formula-provenance-runtime-proof.md records the real Math fixture structural smoke and its review constraints.
• MATHTYPE_ARTIFACT_BROWSER_LOCAL_POSTGRES_CONFIRM=local-postgres HOCTAPAZ_DOCX_CORPUS_DIR=/Users/velikho/Desktop/test-hoctapaz make test-mathtype-artifact-browser-local-postgres runs the local candidate Gateway/Teacher browser proof. It intentionally rewrites the candidate route table to fresh loopback ports and leaves the default table unchanged.
• Shared guards: make test-service-task-packs, pnpm docs:build, and git diff --check.

Rollback:

• Keep public import routes on legacy proxy.
• Remove the internal direct/job/download/reprocess routes from the service route table; no public Gateway/default route depends on them.
• Do not edit or delete legacy formula-recognition or go-formula runtime source as rollback.