Handoff: SVC-013-formula-adapter-determinism-proof formula-docx-service adapter determinism proof

Scope

• Service/area: formula-docx-service
• Task ID: SVC-013-formula-adapter-determinism-proof
• Dispatch ID: SVC-013
• Task pack: docs/agents/service-tasks/formula-docx-service.md
• Accepted first-slice handoff: docs/agents/handoffs/SVC-013-formula-runtime-boundary-audit.md
• Goal: prove parser/runtime determinism stays behind the external Go Formula adapter without creating a deployable services/formula-docx-service.
• Non-goals: editing legacy source, creating a new Go-platform service directory, public route promotion, default gateway route changes, or claiming formula-docx service completion.

Docs Read

• docs/architecture/service-responsibility-matrix.md
• docs/agents/service-agent-next-slice-queue.json
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-agent-next-slice-spawn-packets.md
• docs/agents/service-agent-closeout-ledger.json
• docs/agents/service-agent-accepted-handoffs.md
• docs/agents/agent-handoff-format.md
• docs/agents/handoffs/SVC-013-formula-runtime-boundary-audit.md
• docs/agents/handoff-phase-4-go-formula-docx-runtime.md
• docs/agents/handoff-phase-5-docx-parser-benchmark.md
• docs/agents/service-tasks/formula-docx-service.md
• docs/agents/service-tasks/import-mathtype-conversion-boundary.md

Legacy Evidence Read

• runtimes/go-formula-docx/**
• /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/**
• Legacy source and the external Go Formula runtime were read-only evidence only. No files under /Users/velikho/Desktop/WORKING/HOCTAPAZ/ were changed.

Files Changed

• services/docx-import-service/internal/parser/docx/go_formula.go
• services/docx-import-service/internal/parser/docx/go_formula_test.go
• docs/api/docx-import-service.md
• docs/agents/handoffs/SVC-013-formula-adapter-determinism-proof.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/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md
• scripts/test/service-agent-next-slice-closeout-coverage.sh
• services/docx-import-service/internal/parser/docx/go_formula_corpus_integration_test.go
• scripts/test/docx-formula-determinism-runtime.mjs
• Makefile
• docs/qa/docx-formula-determinism-runtime-proof.md
• docs/.vitepress/config.ts
• docs/agents/service-workflow-test-matrix.md

Behavior Implemented

• The adapter now prevents an unbounded Go Formula request when a caller injects an http.Client with Timeout == 0: it copies that client and uses the configured GO_FORMULA_DOCX_TIMEOUT_MS value or the 180-second default. A caller-supplied positive timeout and all transport settings remain intact.
• Verified the external adapter path exists: runtimes/go-formula-docx.
• Verified services/formula-docx-service does not exist, preserving the runtime-adapter boundary.
• Verified the adapter/runtime wiring guard still treats Go Formula as internal runtime evidence behind docx-import-service, not a deployable service row.
• Verified parser package determinism through the current docx parser test suite.
• Added a QAS adapter regression that varies only parser latency over 24 runs and requires byte-identical import-visible JSON after latency_ms is removed. It covers question IDs/types/options/answers, media, MathType provenance, formulas, warnings, and aggregate stats without modifying the external runtime.
• Added a bounded request invariant: GO_FORMULA_DOCX_TIMEOUT_MS defaults to 180 seconds even when a caller injects an http.Client with Timeout == 0. The adapter clones that client instead of mutating it, preserving any custom transport while preventing a stalled parser request from waiting indefinitely.
• Added a read-only two-call corpus proof for Math and Physics. The JavaScript artifact hashes versioned, import-visible QAS content without latency, while TestGoFormulaCorpusImportVisibleDeterminism executes the actual Go adapter and requires byte-identical JSON after clearing latency_ms.
• The proof deliberately filters raw OLE/WMF non-display diagnostics in the same way as mapGoFormulaQASImages; these assets cannot become persisted browser media. Formula LaTeX/MathML/MTEF provenance remains in the compared payload.

Required evidence covered:

• external adapter evidence
• parser/runtime determinism proof
• no services/formula-docx-service directory

Tests And Verification

• Command: sh scripts/test/go-formula-runtime-coverage.sh

• Result: passed.

• Output: ok go-formula runtime coverage: compose=/tmp/hoctapaz-go-compose-rendered.yaml helm=/tmp/hoctapaz-go-formula-helm-rendered.yaml

• Evidence: runtime coverage keeps go-formula-docx in Compose/Helm internal runtime wiring and outside canonical deployable service rows.

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/internal/parser/docx -count=1

• Result: passed.

• Output: ok github.com/hongochai10/hoctapaz/go-platform/services/docx-import-service/internal/parser/docx 0.490s

• Evidence: adapter-facing DOCX parser package tests passed.

• Determinism regression: TestMapGoFormulaQASResultIsDeterministicApartFromLatency maps the same versioned QAS payload 24 times. latency_ms may differ, but all import-visible JSON used by review/approval must remain byte-identical.

• Timeout regressions: TestNewParserFromEnv proves an injected timeout-free client receives the configured 250 ms request deadline without mutation, and a directly constructed adapter falls back to the 180-second default.

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/... -count=1

• Result: passed.

• Output: all current docx-import-service packages passed; packages without tests reported [no test files].

• Evidence: broader import-service adapter boundary still passes.

• Command: 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

• Result: passed.

• Output: Math fingerprint cae23f6583080f5c6e1f41abf2664fbf1690dcc4b2d7c8ca45ceae5e6d6c91d7 for 22 questions and 125 formulas; Physics fingerprint 11b1bd26d1a8ee2d5501f95c66a4e3a7670778e4ef8a9e5e4440c1467282f892 for 28 questions and 84 formulas. The integration test passed both fixtures.

• Evidence: output/qa/docx-formula-determinism-runtime-20260714122647510/summary.json plus the Go adapter integration result. Runtime latency was observed, not compared (Math 58/33 ms; Physics 30/31 ms).

• Command: if [ -d services/formula-docx-service ]; then printf 'exists\n'; exit 1; else printf 'missing services/formula-docx-service as expected\n'; fi

• Result: passed.

• Output: missing services/formula-docx-service as expected

• Evidence: no deployable services/formula-docx-service directory exists.

• Command: if [ -d runtimes/go-formula-docx ]; then printf 'external runtime exists: runtimes/go-formula-docx\n'; else printf 'missing external runtime\n'; exit 1; fi

• Result: passed.

• Output: external runtime exists: runtimes/go-formula-docx

• Evidence: external adapter evidence path exists and was not edited.

Route State

• Route/default state: runtime-adapter only; no deployable service or default route promotion.
• Delegated gateway verification scope: none; no gateway route edits delegated.
• Public frontend state: no frontend or gateway route should call formula-docx-service directly.
• Rollback notes: keep the current docx-import-service adapter fallback and internal runtime wiring. If parser runtime changes are needed, request a separate user-approved task for the external runtime instead of editing it from this Go-platform service-agent slice.

Data Notes

• Tables touched: none.
• Migrations: none.
• Data validation report: not applicable because this proof changed no data.

Risks / Blockers

• Raw runtime diagnostic OLE/WMF asset paths are not bit-identical in every envelope; they are excluded by the adapter before review persistence. The import-visible adapter response is deterministic for the checked corpus.
• Materialized formula-reference and deployed/runtime-version parity outside this local external runtime remain future import-service adapter work.
• No public API, default route, or deployable formula-docx-service promotion is accepted by this handoff.
• The broad rollout remains active-not-complete.

Next Step

• Use docs/agents/service-tasks/import-mathtype-conversion-boundary.md for the next MathType/OLE parser contract slice, keeping conversion status/download ownership in import-service unless a later ADR promotes a formal parser service boundary.