FamReynaBrain/projects/factory/emi-local-translation-production-readiness-2026-08-18.md

# EMI local translation production readiness — 2026-08-18

## Goal
Read-only production-readiness discovery for EMI’s local MarianMT translation service and deployed backend integration.

## Scope and boundaries
- **Project / hosts:** EMI; Mac mini `.102` as Factory/Paseo control host and EMI production server `.119` as the intended runtime host.
- **Repository / runtime:** Mac-mini backend workspace `/Users/adolforeyna/Projects/EMI/EMI-Backend`; intended production checkout `/home/aeroreyna/EMI-Backend` and its Docker Compose backend/translation containers.
- **Allowed:** explicit `auto-review` Paseo verifier; non-mutating source/runtime inspection and bounded non-persistent HTTP only where runtime access is available.
- **Forbidden:** edits, commits, pushes, pulls, stashes/resets/cleans, image build/pull/rebuild, service/container restart/recreate/deploy, migrations, credential or configuration changes, and proxy/firewall changes.
- **Approval gate:** human approval before any isolated worktree, source/configuration change, merge, deployment, restart, or container lifecycle action.

## Coordinator continuity
- Feature session: `emi: local-translation-production-readiness` (Factory profile).
- Existing production Paseo workspace recorded by project definition: `wks_fc39b6c9d2ebc9e0` on `.119`; it was not reachable from this Factory control session because the production daemon is loopback-only and direct SSH as `aeroreyna@emi-server` was denied.

## Paseo evidence

| Role | Agent ID | Workspace ID | Provider / mode | Terminal state |
|---|---|---|---|---|
| Read-only runtime verifier | `9b8ca9a7-193f-4162-bd3d-d9f861a518d9` | `wks_740a1fe0494b5cc9` (`EMI · Backend — Mac mini Checkout`) | `codex/gpt-5.6-terra`, explicitly `auto-review` | `idle` / completed |

The agent located/read the applicable parent workspace guidance before source inspection. Paseo inspection confirmed its available mode included `auto-review`, no pending permissions, and no worktree was created. No source or runtime mutation was requested or reported.

## Observed contract (static only — not production runtime verification)

The verifier’s read-only source inspection found:
- Compose intends an internal `app` ↔ `translation` connection on `emi-network`; app upstream is `http://translation:8000`. Translation has no published host port.
- The app defaults to `TRANSLATION_PROVIDER=openai`; local MarianMT is used only when the runtime provider is explicitly `marian`.
- `GET /health` is implemented as `200 application/json` with `{"status":"ok","provider":"marianmt","loadedModels":[...]}`. This is a liveness/in-memory model-name signal only; it does not prove required-model cache availability, successful inference, or readiness.
- `POST /translate` accepts `text`, `sourceLang`, and `targetLang`. Missing/invalid text or target and unsupported languages are intended to return `400`; unhandled translation failures are intended to return `502 {"status":"Translation failed"}`.
- Models load lazily on first translation into `/models`; the app’s upstream timeout is 30 seconds.
- Compose declares neither a container healthcheck nor CPU/memory limits.

## Runtime-verification result and blocker

The verifier attempted only read-only runtime-discovery commands (`docker compose ps --all`, filtered `docker ps`, and filtered `docker volume ls`) and found `docker: command not found`; `docker-compose`, `podman`, and `nerdctl` were also unavailable. Process inspection was restricted (`ps: operation not permitted`), and no listener on local ports 8000 or 3001 was observable.

Accordingly, it did **not** install tools, alter permissions, authenticate, enter containers, inspect caches, invoke a translation request, or induce a model download. The only completed evidence is the static contract above. The following production facts remain unverified: running container identity/network/upstream; actual provider value; app-to-translation DNS/TCP/HTTP; `/health` response from the deployed service; functional translation; first-download/cache behavior; live invalid/upstream-timeout behavior; current resource use; and deployed resource limits.

## Exact production-readiness acceptance criteria

Production readiness is not met until a read-only verifier with access to the actual `.119` Compose runtime records all of the following:

1. **Runtime identity and isolation:** exact app and translation container IDs/images, Compose project, Docker network membership, and non-secret app upstream mapping; translation is reachable only through the intended internal path unless explicitly approved otherwise.
2. **Provider correctness:** runtime evidence that the app is configured to use `marian`, not the static default `openai`, and that its upstream resolves to the intended translation service.
3. **Connectivity:** a non-mutating request from the running app container resolves `translation`, completes TCP/HTTP to port 8000, and receives the expected response within the configured bound.
4. **Health/readiness semantics:** exact deployed `/health` status, headers, and body are captured; a readiness criterion explicitly proves every required model is locally available for inference without triggering a download. A liveness-only `200` is insufficient.
5. **Functional translation:** one bounded, innocuous translation for each approved language direction succeeds through the app’s real translation path; response schema/text and elapsed time are recorded, with no user data persisted.
6. **First-model/cache behavior:** cache volume/path, ownership, persistence across planned container recreation, and required model artifacts are evidenced. First-download latency, network dependency, disk impact, and failure behavior are measured in a controlled approved environment—not by deleting a production cache.
7. **Errors and timeouts:** invalid request returns a documented non-5xx client error; upstream unavailable/timeout behavior is tested without stopping production (or in an approved equivalent environment) and returns the documented bounded error without crashing/retrying indefinitely; the app’s 30-second upstream bound is verified.
8. **Resources:** deployed CPU/memory reservation/limit and current idle/translation peak CPU, RSS, disk/cache consumption are recorded; observed peaks stay below an owner-approved host budget with headroom. No configured resource limits is a blocker.
9. **Operational controls:** Compose/service healthchecks, logs/metrics sufficient to distinguish model download, model load, inference failure, timeout, and resource exhaustion, plus an approved rollback procedure, are documented and independently checked.
10. **Release integrity:** all implementation changes exist in one isolated worktree, pass declared checks, receive independent review, and obtain explicit human approval before merge/build/recreate/deploy.

## Proposed isolated-worktree implementation plan (not authorized or started)

1. Obtain a read-only production-runtime observability path (Paseo agent on `.119` or authorized Docker metadata/log/exec access) and complete acceptance items 1–8 without lifecycle changes.
2. After human approval and protection/review of the dirty production Compose state, create one isolated backend worktree from the approved committed base, e.g. branch `factory/emi-local-translation-readiness`; do not use either dirty main checkout.
3. Implement a non-downloading readiness endpoint/check that verifies configured required models are present and loadable; keep existing liveness semantics separate and document status/error contracts.
4. Add Compose healthchecks and explicit, owner-approved CPU/memory constraints; make model-cache volume persistence, permissions, and prewarming strategy explicit.
5. Add deterministic tests for provider selection, health/readiness distinction, validation errors, upstream timeout/error mapping, and cache-present/cache-absent behavior without external model downloads in ordinary CI.
6. In an approved non-production environment, measure cold first-download, warm-cache translation, resource peaks, timeout behavior, and recovery; document production rollout and rollback steps.
7. Dispatch an independent reviewer and verifier against that isolated worktree. Present exact diff, checks, measured evidence, deployment/recreate impact, and rollback plan for explicit human approval; only then may a named deployment executor act.