feat: prepare ARR for controlled public deployment

.project-docs/50-evidence/topics/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/50-evidence/topics/2026-07-29-live-synthetic-xml-vertical-slice.md

@@ -0,0 +1,50 @@
+# Evidence Topic: Live Synthetic XML Upload Vertical Slice
+
+## Metadata
+
+- Date: 2026-07-29
+- Status: Active
+- Scope: Real Web upload → private OSS → SuperAgent → direct MCP → PostgreSQL Finance facts
+- Confidence: Fact for observed state; strong inference for the platform-cache cause
+- Source: Real browser interaction, Open Agent run metadata, public MCP discovery, PostgreSQL ledger/fact queries, local health checks
+- Last verified: 2026-07-29 15:57 +08:00
+- Stale trigger: Public MCP reachability is restored, SuperAgent enterprise MCP config version exceeds `33`, and a fresh run receives `committed` or `already_committed`
+
+## Question
+
+Can the accepted user flow complete from a real XML upload through SuperAgent and direct MCP into authoritative database facts?
+
+## Evidence
+
+- Input: Synthetic no-PII XML for unused business date `2038-01-19`; deterministic local validation retained two records and was activation-eligible.
+- Web: A controlled instance on `127.0.0.1:8766` reported all readiness gates true. The real page selected the XML, enabled “开始处理”, and submitted exactly once.
+- Processing identity: Job `arrjob-fdc2c1a0695c41b3b372a52033b2f567`, attempt `1`, SuperAgent run `7e1ad2fe-cb59-4d04-b92c-9f09d98f4ef8`.
+- Remote result: Open Agent reported `success` with no final content. Metadata resolved the intended V5 profile but still reported enterprise MCP config version `33`.
+- MCP service: Authenticated read-only discovery advertised one tool, `arr_submit_processing_result`, from gateway version `1.0.1`; its input schema contained no `$ref`, `$defs`, or `$id` keywords.
+- Database after remote completion: No `ingestion.result_submissions` row, the grant was unconsumed, and the target date had no Finance daily version, current pointer, or daily records.
+- Safe cleanup: A serializable, identity-locked transaction marked run `13` and attempt `12` failed with `PROCESSING_RESULT_MISSING`, revoked grant `9`, and inserted the privacy-minimized failure outbox event. An independent read-only query verified submission/version/current/record counts were all zero.
+- Exposure state: The temporary 8766 process was stopped and the port closed. The normal `*:8765` service remained healthy with `processing_ready=false` throughout.
+- Follow-up connection state: The temporary MCP listener on 8890 and ngrok management listener on 4040 later disappeared; their historical PIDs no longer exist and no launchd service owns either process. The configured public host still resolves and has a valid TLS certificate, but `/mcp` now returns ngrok `ERR_NGROK_3200 endpoint offline` before ARR authentication or MCP handling.
+- Recovery state: With user authorization, loopback MCP and the fixed ngrok host were restarted. The first authenticated request returned 421 because the new tunnel preserved the public Host while the gateway allowed only loopback Hosts; the server log explicitly recorded the invalid Host. The gateway was restarted still on loopback with exact loopback/public Host entries. Public unauthorized requests then returned 401, and authenticated initialize/tools-list returned 200 with gateway 1.0.1, protocol 2025-11-25, exactly one tool, and the same 2195-byte reference-free schema.
+- Final process state: MCP PID 34744 listens on `127.0.0.1:8890`; ngrok PID 34569 exposes the existing fixed host and keeps its inspector on `127.0.0.1:4040`. Port 8766 is closed and the normal 8765 service remains database-ready with processing disabled.
+- Repository state: The workspace is not a Git repository, so this evidence is tied to explicit runtime identities and project files rather than a commit hash.
+
+## Finding
+
+The vertical slice did not pass. Upload, OSS registration, processing ledger creation, grant issuance, and SuperAgent dispatch are operational, but SuperAgent did not invoke the database MCP. The public gateway is again online and independently discoverable. The remaining platform action is to refresh and save stale MCP config version `33`, then prove a fresh run actually creates a committed submission.
+
+Remote Agent `success` must not be treated as business success. The required success condition remains an MCP `committed`/`already_committed` receipt plus matching committed Finance facts.
+
+## Impact
+
+- Keep the normal upload mutation disabled until a fresh synthetic vertical slice passes.
+- Do not change MCP URL, bearer headers, OSS configuration, database configuration, or the V5 prompt for this failure.
+- Refresh/reconnect/rediscover the MCP tool in SuperAgent and save the configuration; public connectivity no longer blocks that action.
+- Fix the local `delivery_missing` PostgreSQL status-mapping gap in separately authorized implementation work so future missing-result runs terminate automatically.
+- Automatic monthly post-commit dispatch remains unimplemented and therefore was not testable in this failed pre-commit run.
+
+## Open Items
+
+- Authenticated SuperAgent administrator refresh and save.
+- Fresh no-PII E2E with platform config version greater than `33`.
+- A committed receipt and downstream daily/BI/monthly read-path reconciliation.

.project-docs/50-evidence/topics/2026-07-29-public-deployment-repository.md

@@ -0,0 +1,39 @@
+# Evidence Topic: Controlled public deployment repository
+
+## Metadata
+
+- Date: 2026-07-29
+- Status: Active
+- Scope: Source publication and public-server deployment handoff
+- Confidence: Fact
+- Source: Local candidate snapshot, automated tests and static configuration checks
+- Last verified: 2026-07-29
+- Stale trigger: Any change to Dockerfile, Compose, Caddy, Web processing flags, authentication, dependency pins or public topology
+
+## Question
+
+Does the publishable source snapshot open XML processing through an explicit authenticated HTTPS deployment entry without exposing local state, credentials or unfinished report claims?
+
+## Evidence
+
+- Files: `Dockerfile`, `compose.yaml`, `deploy/Caddyfile`, `deploy/.env.production.example`, `deploy/README.md`, `arr_web/app.py`, `arr_web/run.py`, `tests/test_arr_web.py`.
+- Deployment command inspection: Compose Web command contains `--enable-processing` and `--secure-cookies`; only Caddy maps host ports 80/443, Web and MCP use internal `expose` ports.
+- Tests: Python 3.12 full discovery ran 259 tests successfully; 2 environment-dependent tests were skipped.
+- Integrity: every entry in `CHECKSUMS.sha256` passed and 10 JSON contracts parsed.
+- Snapshot audit: 271 final candidate files, about 2.0 MiB, zero files over 1 MiB, zero symlinks, eight ZIP/XLSX archives inspected and zero detected secret/private-endpoint hits after documented placeholder allowlisting.
+- Configuration: Compose YAML parsed and assertions confirmed both required Web flags. Docker/Caddy executables are absent locally, so no image build or public TLS runtime result is claimed.
+
+## Finding
+
+The repository snapshot provides a fail-closed deployment profile that opens XML upload only when the database, guarded OSS and SuperAgent processing runtime initialize. Web traffic is protected by Caddy HTTPS plus Basic Auth, MCP traffic retains application bearer authentication, and application defaults remain closed outside this profile.
+
+## Impact
+
+The next test should use the stable deployed domains, not the temporary ngrok endpoint. `processing_ready=true` is a deployment prerequisite, but business completion still requires SuperAgent tool rediscovery and an MCP `committed`/`already_committed` receipt with matching database facts.
+
+## Open Items
+
+- Build and start the containers on the public Linux server; verify DNS, ACME, health and logs.
+- Rebind and republish the SuperAgent MCP configuration against the stable MCP domain.
+- Execute one no-PII XML end-to-end commit test.
+- Implement automatic post-commit monthly dispatch and the required `TOTAL PRICE` formula in separately authorized work.