feat(P02): docker image channel — image, honest degrade, registry push, smoke gate (v0.7.2)

Multi-stage Dockerfile (web-export SEA+export / venv production deps /
slim non-root runtime, AI_WEB_STATIC_DIR mount, NC_CONTAINER=1,
/health healthcheck, state volume) — 487MB. Honest sandbox degrade
(D-068): capability.py real-userns probe (cached per process), boot
notice + 503 arm sharing the G-208 remediation constant, structural
backends exempt. In-container CLI (D-066): doctor/verify container
branches, honest refusals, marker-only detection. Release lane builds +
pushes to git.coreci.dev/coreci/nextcraft (tag + latest) with the
G-204 five-assertion smoke gate — which caught two real image bugs
(state-root permissions, probe slice) before any release shipped.

---ci---
phase: 2
milestone: v0.8
status: complete
requirements:
  covered: [REQ-8-002]
  partial: []
---/ci---

.ciagent/ARCHITECTURE.md

@@ -6,6 +6,59 @@ Nextcraft is a TypeScript monorepo (pnpm workspaces + turborepo) with a Next.js
 
 **v0.3 additions (Credential Engines):** real credential engines replace v0.2 mock inputs — a sandbox fabric (isolated per-learner coding environments via Linux user/mount/pid/net namespaces), a live build-telemetry pipeline (WebSocket ingest + SQLite-ordered event log), a process-trace grading engine, seeded per-learner variant task generation, and a voice-based oral defense (STT/TTS via a new provider-agnostic voice layer). **First real persistence introduced: SQLite** (`ai_service/telemetry/`, grading, variant, defense stores). Lab/Assessor/Proctor agents are re-grounded onto real telemetry/traces. **Identity/age-gating (KYC) deferred per founder directive** — no security engineer persona; secrets-hygiene checklist only.
 
+**v0.4 additions (Distribution & Bootstrap CLI, founder directive D-016):** a new `apps/cli` package — the `nextcraft` bootstrap CLI (`doctor`/`bootstrap`/`verify`/`dev`) compiled to a self-contained linux x64 binary via **Node SEA** (probe-verified: Go/Rust absent, node v24.15.0 SEA-capable), installed by a repo-served one-liner script that resolves the latest Gitea release, downloads binary + sha256 sidecar, verifies, and installs to `~/.local/bin`. Every release from v0.4 onward attaches the binary + checksum as release assets (the "ongoing binaries" requirement). The CLI is a thin wrapper: all orchestration logic stays in `apps/ai-service/scripts/` (bootstrap.sh/dev.sh) — the CLI composes them via subprocess (A-202), duplicating nothing. Previously-planned v0.4 seams (real STT/TTS, KYC, design/sim envs, seq-lease) move to v0.5.
+
+### v0.6 Research Conclusions (Phase 0 RESEARCH)
+
+32. **D-048 Marketplace module layout mirrors D-031** — one new engine module `ai_service/marketplace/` inside apps/ai-service (no new apps, no new ports): `base.py` (pydantic contracts: `Posting`, `Employer`, `PostingTags`, `IngestPosting`), `store.py` (6th D-027 store family, D-049), `ingest.py` (PostingSource adapters, D-050), `tagging.py` (D-052), `embedding/` (protocol + mock + openai_compat + factory, D-051), `search.py` (hybrid facet+cosine ranking, A-405), `enrichment.py` (D-053), `resume.py` (D-054), with the HTTP surface in `ai_service/api/marketplace.py` (`/v1/marketplace/*` router) + `api/marketplace_admin.py` (`/v1/marketplace/admin/*`, D-057) composed via `deps.py` app.state DI (`get_marketplace_store`, `get_embedding_provider`). Boundary rules identical to identity/voice: `marketplace/` never imports `agents/` or `api/`; settings in `config.py` (backend-engineer territory); the G-18 stub MOVES from `api/identity.py` into the new router and becomes real (D-058) — `identity/` keeps only the `require_verified_adult` gate dependency it exports today.
+33. **D-049 Sixth store = one SQLite DB, five tables, DefenseStore conventions** — the marketplace store joins the shared `~/.nextcraft/data/nextcraft.db` (all 5 prior stores already share it; `Settings().db_path`). Tables: `posting` (id PK, source, external_id, employer_id, title, description, skills/seniority/category/location/remote/salary JSON+portable columns, status `draft|published|closed`, posted_at, unique constraint on (source, external_id) for idempotent upsert per A-402); `employer` (id PK, ingested raw fields, unique per source); `embedding` (posting_id PK, `vector` BLOB of struct-packed little-endian float32, `model`, `dim` — A-403/A-404 per-row provenance so lazy re-embed on provider change works); `application` (id PK, posting_id, learner_id, status `submitted`, created_at, unique (posting_id, learner_id) for A-408 idempotent apply); `employer_enrichment` (append-only: id PK, employer_id, field, value, source `llm|manual`, model, created_at — A-409). **[AMENDED by grill G-104: SIX tables — the `learner_profile` table (learner_id PK, profile JSON, confirmed_at, model) replaces the filesystem sidecar the plan draft proposed; the D-027 store family is the only persistence mechanism. Shipped six-table in P1.]** All tables mirror the probe-verified identity/store.py mechanics: WAL/synchronous=NORMAL/busy_timeout/foreign_keys pragmas, `sa_type=String/JSON` portable columns, `_validate()` hooks, Protocol + SQLite impl pair, surfaced IntegrityError, tz normalization. `VectorStore` is a protocol method-group on the marketplace store (pgvector-swap-ready, D-019/D-027 pattern).
+34. **D-050 PostingSource = protocol + two adapters, no scheduler** — `PostingSource` protocol: `fetch() -> Iterable[IngestPosting]` (pydantic, A-402 shape: source, external_id, employer + posting fields). Two v0.6 implementations: `seeded_corpus` (in-repo JSON seed ported ONCE from `packages/mock-data/jobs.ts` (20 jobs) + `employers.ts` (10 employers) per D-021 convention — shared IDs, mock `matchScore` DROPPED since D-051 computes real ones) and `admin_api` (the founder-authored path; the admin router calls ingest directly rather than an HTTP hop). Ingest upserts idempotent on (source, external_id); a `POST /v1/marketplace/admin/ingest` route triggers a source run explicitly (founder-invoked — no cron/crawler, A-401/A-402). The 3M+ external corpus lands later as a third adapter with zero store/route changes.
+35. **D-051 EmbeddingProvider = D-030 mirror with a corrected real path** — protocol `embed(texts: list[str]) -> list[EmbeddingVector]` (frozen pydantic: `values: list[float]`, `model`, `dim`) in `marketplace/embedding/base.py`. Deterministic mock: 256-dim feature-hash of normalized tokens (pure stdlib, similarity deterministic — tests never call the cloud). Real: `OpenAIEmbedProvider` on the shared httpx pool posting `{"model", "input": [texts]}` to `{AI_EMBED_BASE_URL}/embeddings` (OpenAI-compatible; `_sanitize` key redaction mirroring `openai_audio.py`). **Probe correction to A-404:** ollama-cloud does NOT expose `/v1/embeddings` (404 path-not-found; chat/completions auth-gates 401) — so `AI_EMBED_BASE_URL` must point at a different OpenAI-compatible endpoint (local ollama `:11434/v1` supports it, or any embeddings cloud); provider selection `AI_EMBED_PROVIDER=mock|openai-embed` (default mock, G-11 boot-safe fallback with loud log — exact `voice/factory.py` pattern, `AI_EMBED_MODEL`/`AI_EMBED_API_KEY` env-only). Storage per A-403: struct-packed `<{dim}f` float32 BLOB + model + dim per row; cosine in pure Python (sum of products / norm product, ≤10⁴ postings); candidate side embeds competency-profile text on demand, never stored. Confidence in A-404's parenthetical drops it to ~0.5 but the protocol design is unaffected (endpoint-agnostic by config is the D-014 pattern anyway).
+36. **D-052 Tagging = D-020 structured_completion, no new agent** — `marketplace/tagging.py` composes the EXISTING `structured_completion(provider, messages, model, schema, schema_hint)` (agents/structured.py, all 4 layers) with a `PostingTags` pydantic schema (skills: list[str] ≤10, seniority enum, category enum) + a versioned prompt constant in `prompts/` (or module-local, matching variants' pattern); no BaseAgent needed — tagging is a one-shot extraction like grading's rubric call. Mock-first for free: `settings.provider` defaults to `mock` and `structured_completion` runs against `MockLLMProvider.chat`, so tests stay cloud-free. Tags persisted as a JSON column on the posting row (D-049); tag facets feed the search filter sidebar (A-405 hard filters); re-tagging on posting update overwrites the tags column (single source of truth, no append-only need — unlike enrichment D-053, tags are derived data).
+37. **D-053 Enrichment = append-only provenance table + merge-on-read** — per A-409: `employer_enrichment` rows are append-only `(employer_id, field, value, source: llm|manual, model, created_at)`; read precedence **manual > llm > ingested-raw** computed at API-response time (a small `merge_employer()` over rows, raw fields last); every enriched field carries `{value, source}` provenance markers in the API response (A-304 honesty — LLM copy visibly marked). Trigger: a new employer's first published posting fires a one-shot LLM structured extraction (D-020, same layering as D-052, schema: description, social_links, logo_ref) — founder override = upsert a `manual`-source row, never a mutation of `llm` rows. No employer self-serve anywhere (A-407).
+38. **D-054 Resume parse = pypdf (probe-verified) → D-020 draft extraction** — pypdf 6.19.0 pip-reachable through the existing venv channel (probe 1; the ONLY new dependency, pinned `pypdf>=6.19,<7` in pyproject.toml). Pipeline: upload guard (PDF/TXT/MD only, ≤2 MB, A-410) → text extraction (`pypdf.PdfReader` page-text join for PDFs; raw decode for TXT/MD) → empty-extract on a PDF = honest 422 "text layer required" (no OCR) → cap ~100K chars → D-020 structured extraction into a `ParsedProfile` pydantic schema mapped to the competency-profile shape (competencies, skills, experience bands) → response returns as **DRAFT** (`status: "draft"`) — nothing persists to the learner profile until an explicit confirm call (REQ-6-005 review gate). Raw resume bytes never stored, never logged (A-305 pattern; the existing `_scrub_pii_validation` handler precedent applies). Tests use small generated PDFs or TXT fixtures — cloud-free.
+39. **D-055 Web migration = client shells + engine-client extension; remove 2 generateStaticParams** — board/detail/employer-profile become one static client shell each fetching at runtime per A-406 (the proven build/defend pattern): `marketplace/page.tsx` keeps its server shell but `JobFilters` receives fetch-backed data (it already owns all filter logic client-side — the facet contract survives unchanged); `jobs/[jobId]` and `employers/[employerId]` drop `generateStaticParams` (the ONLY two removals — learner catalog/learn/build/defend keep theirs, their data stays mock) and render a client shell that fetches then renders (or `notFound()` on 404). `engine-client.ts` gains a marketplace section: `listPostings(filters)`, `getPosting(id)`, `getEmployer(id)`, `searchPostings(query)` → typed against new `packages/types` marketplace wire shapes (data-engineer dual-schema sync); 403 discrimination (verify-CTA vs allowlist) already works. `packages/mock-data` jobs.ts/employers.ts go dormant for the marketplace path (still imported by employer/admin mockups — NOT deleted, A-406/A-407); the seed port (D-050) copies values once. No build-time DB reads — D-039 export build stays repo-only.
+40. **D-056 SEO = build-time metadata on static set + client JSON-LD on runtime set + ai-service sitemap/robots** — per A-411, split: (a) build-time-static pages (landing, catalog/stack detail, marketplace board, pricing) get `export const metadata` (probe 7: the static-export-compatible API the app already uses in layout.tsx/enroll) + OG tags + server-rendered JSON-LD (`Organization` on employer-adjacent static, `ItemList` on the board) rendered into the export; (b) runtime-data pages (job detail, employer profile) inject `JobPosting`/`Organization` JSON-LD + title client-side after fetch — accepted JS-crawler limitation, recorded; (c) `/sitemap.xml` + `/robots.txt` as plain FastAPI GET routes on the api app enumerating the static page list + all `published` postings — **probe 6 verified mount order: API routes beat the `StaticFiles("/")` mount**, so they win over the export even in single-port production; do NOT use Next `app/sitemap.ts` (it enumerates at build time and cannot see runtime postings under `output: 'export'`). robots.txt points at `/sitemap.xml`; sitemap URLs use the deployed origin (env-configured `AI_PUBLIC_BASE_URL`-style setting, backend-engineer territory).
+41. **D-057 Admin guard = AI_ADMIN_TOKEN header check, env-only, fail-closed** — all `/v1/marketplace/admin/*` routes (postings create + lifecycle transitions draft→published→closed, ingest trigger, enrichment manual-override, applications review) take a FastAPI dependency `require_admin` comparing `X-Admin-Token` (or `Authorization: Bearer`) against `Settings().admin_token` (`AI_ADMIN_TOKEN`, env-only per D-014, probe: no admin token exists in config today — greenfield). Unset token = admin routes 403-fail-closed (never open; a loud boot warning tells the founder to set it, G-11 doctrine). This is the A-401 operator surface; D-043 learner gate composition is untouched — admin routes do NOT pass the learner allowlist/identity gates (different principal class).
+42. **D-058 Apply route goes real, composition unchanged** — `POST /v1/marketplace/apply` (moved from api/identity.py into api/marketplace.py, D-048) keeps the exact D-043 order (G-5 allowlist → `require_verified_adult` → rate caps), then: posting must exist and be `published` (404/409 otherwise), insert an `application` row (status `submitted`, unique (posting_id, learner_id) → duplicate apply is idempotent 200-with-existing, A-408), return an honest confirmation payload `{application_id, posting_id, status: "submitted"}` (the `stub/mock` markers die). Founder reviews via `GET /v1/marketplace/admin/applications` (D-057-guarded); no notification infra. Body becomes `{posting_id}` + the learner identity from the verified record rather than a client-asserted `job_id`.
+43. **D-059 v0.6 wave order = ROADMAP order confirmed with two couplings** — P1 postings backend must ship WITH the web client shells in the same phase (a live store behind mock-reading pages proves nothing — REQ-6-001's success criterion is surfaces reading real data); P2 tagging before P3 search because facets drive the sidebar filters AND the posting text embedded in P3 should include the normalized tags; P4's two workstreams (enrichment REQ-6-004, resume REQ-6-005) are independent of each other — parallelizable within the phase; P5 SEO depends only on P1 (routes exist to enumerate) but stays last-before-final per ROADMAP since sitemap needs `published` postings and the board metadata should reflect final facets; P6 final review + ship. Tagging/enrichment/resume all route through the same D-020 call site — one prompt-review pass covers all three.
+
+### v0.5 Research Conclusions (Phase 0 RESEARCH)
+
+25. **D-040 Voice real path = `OpenAIAudioProvider` on the shared httpx pool (D-R01)** — implements the D-030 protocol: `transcribe()` = multipart `POST {AI_VOICE_BASE_URL}/audio/transcriptions` (`file` + `model`, response_format=json → `TranscriptSegment`), `synthesize()` = streaming `POST /audio/speech` (JSON body, raw byte stream, `input` ≤4096 chars). Carries `descriptor = VoiceDescriptor(mode="server", ...)` which defense.py:143 already prefers — mode selection drops in with zero API changes. Constructor takes the lifespan `httpx.AsyncClient` (D-017; read=300s already tolerates multi-minute clips). Factory signature becomes `voice_provider_from_settings(settings, http_client)`. Errors sanitized with key redaction (mirror `llm/openai_compat.py:_sanitize`).
+26. **D-041 Voice route fixes (D-R02)** — defense.py:189 fmt derivation must strip codec params (`"webm;codecs=opus"` → `webm`, else real STT 400s); ~10 MB audio guard (422/413) before provider call; TTS route media_type becomes format-aware (or force `response_format=wav`). Web: defense-session POSTs the recorded blob (FormData), engine-client gains the audio-answer variant.
+27. **D-042 Identity = 5th D-027 store + provider protocol (D-R03)** — `ai_service/identity/` (D-031): `IdentityProvider` protocol (submit/poll/verify), deterministic mock, SQLite store modeled on DefenseStore (WAL, FK on, portable columns). Stores **derived age_band** (`16-17`/`18+`, never raw DOB) + document **refs** (never raw docs); mock verdicts carry a `mock` marker so downstream never displays them as production-verified (A-304). PII hygiene pinned by caplog sentinel test. **Negative finding:** no age-gate UI or enrollment API exists today — the flow is built, not swapped (D-010's "visual flow" is vestigial: one mock field).
+28. **D-043 Gate composition (D-R04)** — api/-layer dependencies in order: G-5 allowlist (403 pilot guard, retained) → identity verdict (403 + verify-CTA payload) → rate caps (429). School 16+ gates variant generation + sandbox create + defense start; marketplace 18+ via reusable `require_verified_adult` demonstrated on one minimal gated route (marketplace has no backend today — the thin route proves the contract end-to-end). All middleware-layer, never in the manager.
+29. **D-044 Environment registry at the template/variant layer (D-R05)** — `TaskTemplate.environment: Literal["build","design","simulation"]` → carried through VariantRecord → API → TS `TaskVariant`; surfaces the existing-but-dead `test_command` field (Run/Test buttons stop hardcoding pytest). Manager/backend/workdir unchanged (D-024 untouched — A-307: an environment is a typing over starter files + command policy). Per-kind exec command policy at the api/ exec route (template-declared harness + generic file/nav commands, 422 on violation). Grading digest stays kind-agnostic by construction (features derive from event kinds — pinned with a digest test over a synthetic design-kind trace). Starter contents: design = SVG/HTML/schematic artifacts + validate/render harness (stack-designer c001/c002 already sanctioned); simulation = parameterized benchmark script + dataset files (stack-science, stack-operator).
+30. **D-045 Seq-ack protocol (D-R06/D-R07)** — new WS frame `{"type":"seq_ack","seq":N}` emitted per successful append from `IngestSession._append` (durable `latest_seq`; O(1); advisory — gap detection stays authoritative, G-3/G-4 unchanged). The capture agent's supervisor loop (which today discards all non-close frames) parses text frames and trims spool+pending to `seq > ack` under `_emit_lock` via atomic `Spool.rewrite` — closing the one-line replay-margin gap (`_flush_locked` pops N in-flight frames but `replay_margin()` requeues only `_last_sent`). An explicit spool bound is added (A-309's "spool cap exists" premise was factually wrong on disk). Regression test: mid-burst kill in the test_durability.py real-server harness (uvicorn + KillableProxy) — the exact scenario the P07 de-flake documented as uncovered.
+31. **D-046 v0.5 wave order (D-R08)** — P1 seq-lease (smallest, protocol-only, fixes transport before env phases add reconnecting producers), P2 voice, P3 identity, P4 environments, P5 final. Phase numbers renumbered accordingly (was 1=voice..4=seq-lease in the initial ROADMAP draft).
+
+### v0.7 Research Conclusions (Phase 0 RESEARCH — Test Harness Review, NFR)
+
+44. **Harness baseline (probe-verified, 2026-09-26)** — 785 tests all green: pytest 671 (64 files, ~15.4K LOC), web node:test 53 (7 files, 1,379 LOC), CLI node:test 61 (11 files, 1,284 LOC). Zero coverage tooling, zero framework timeouts (ad-hoc 20-30s polling deadlines + a 600s CLI bootstrap), zero markers despite a real three-tier split (fast-unit / real-uvicorn / real-userns), zero `filterwarnings` policy. Web tests are OUTSIDE the turbo pipeline (no `@nextcraft/web#test` task; no root test/web:test script). PLAN.md verification counts stale (488/22/61 vs actual 671/53/61). `packages/{types,mock-data,ui}` have zero tests (cross-package contracts pinned only via other apps' source-read tests).
+45. **Warning census (probe-verified)** — 1,716 warnings per pytest run: ~99% from 14 `session.query()` sites (SQLModel deprecation: `marketplace/store.py` ×12 lines 490-952, `identity/store.py` ×2 lines 172/189); 14 ResourceWarning sites (unclosed `UploadFile` multipart ×10 from `api/defense.py:214` + `api/marketplace.py:446`; unclosed sockets ×3 `scripts/sandbox-agent.py:559`; unclosed file ×1 `tests/grading/test_engine.py:428`); 2 upstream import-time deprecations (fastapi/starlette TestClient httpx, anyio BlockingPortal). First-party deprecated-API audit CLEAN: no `datetime.utcnow`, no distutils/pkg_resources, no pydantic-v1 idioms, no legacy Next APIs. `next build` warning-free; no `ignoreBuildErrors`/`ignoreDuringBuilds` flags; ruff passes clean; all 5 tsc projects pass.
+46. **Suppression census** — 81 Python `# noqa` ALL inert (RUF100: suppressed codes not in the enabled select-set — SLF001 ×57, ANN001 ×12, E402 ×5 stale-positions, rest scattered); 5 orphaned `eslint-disable` comments (no ESLint exists — turbo lint is a no-op for 5 of 6 packages; `next lint` deprecated); 27 Python `# type: ignore` (11 src, 16 tests) with no type checker; zero `@ts-ignore`/`any` in TS. Dead exports: `packages/mock-data/ai-scenarios.ts` module, `NavItem`/`ThemeConfig` types, `Spawn` type, unused `MicControl` primitive. `FastAPI(version="0.3.0")` hardcoded vs pyproject "0.2.0" vs shipped v0.6 — version drift.
+47. **Duplicated harness infrastructure** — `KillableProxy` ×2 (`tests/sandbox/test_sandbox_agent.py:275`, `tests/telemetry/test_durability.py:45`); `_free_port()` ×4; userns probe ×4; real-uvicorn serve-loop boilerplate ×5; full-app state-injection boilerplate ×6; `wirePosting()` ×2 (web). 18 one-off MockProvider scripted subclasses (some consolidation possible, low priority). Flakiness already documented in-tree: `test_sandbox_agent.py:542` "8s was flaky" — timeout-widening is the current mitigation strategy, replaced by D-054's bounds + deterministic waits where possible.
+48. **Low-value test census** — web: 21/53 are source-text regex pins (`readFileSync` + literal-string asserts, e.g. "openGraph exists in a file"), triaged per D-057 (keep iff documented regression lesson or invisible cross-boundary wiring; cut tautologies); `test_budget_constant_defined` asserts a literal defined in its own file; `tests/llm/test_mock.py` + `identity/test_identity.py::TestMockProvider` are mock-meta tests (defensible: the mock is the suite-wide engine — keep). Silent skips: `apps/cli/tests/path-invocation.test.ts:14` returns early (passes silently when binary missing); `doctor.integration.test.ts` accepts either exit code. Env leak: `tests/conftest.py:80` mutates `os.environ["AI_PROVIDER"]` without restore; `seed_verified_identity` swallows all exceptions (`conftest.py:74-75`). Web source-pin tests depend on CWD = `apps/web` (breaks from monorepo root).
+49. **D-052 tooling conclusions** — coverage: pytest-cov (Python) + c8 wrapped around existing `tsx --test` (no runner swap, no vitest); markers `fast`/`real_server`/`userns` under `--strict-markers`, unmarked defaults to fast, fast run = `-m "not real_server and not userns"`; pytest-timeout `signal` method, 60s global / 180s real-server+userns via collection hook (D-054); CLI fresh-clone E2E env-gated (`CLI_E2E=1`) into `cli:test:e2e` with a 900s budget (D-055); `filterwarnings = ["error", <narrow module+message-scoped upstream ignores>]` (D-056); mypy relaxed-first baseline (`check_untyped_defs`, `warn_unused_ignores`, no full strict) (D-058); recharts 2→3 verified by tsc + static build + existing tests (D-059); shared Python helpers in `tests/helpers/` package, fixtures stay in conftest (D-060); pyproject.toml is the single version source, `FastAPI(version=)` reads package metadata (D-061).
+50. **D-062 v0.7 wave order = dependency-ordered: wiring before composition before elimination before hardening** — P1 harness wiring (coverage/timeout/markers/turbo tasks/leak fixes) MUST precede P2 suite composition because the cut/consolidate decisions are evidence-based (P1's coverage data tells P2 what to cut); P3 warning elimination is independent of P1/P2 but ordered after them to avoid rebasing `session.exec()` conversions over moved test files; P4 lint hygiene (ESLint + noqa RUF100) after P3 so the eslint-disable resolutions happen under a warning-clean tree; P5 type+dependency hardening last (mypy adoption and recharts 3 are the riskiest changes — they run against a fully-stabilized harness, and recharts gets the fresh coverage/ESLint net as its safety net); P6 final review. ESLint adoption (D-048) rides P4 because the orphaned eslint-disable comments only become meaningful once a config exists.
+
+### v0.8 Distribution & Release Architecture (Phase 0 RESEARCH — Ship Anywhere, D-063..D-072 binding)
+
+**Runner fleet topology (CT 113, 10.0.0.113):** three org-level gitea-runner containers (official image `docker.io/gitea/runner:3` — the Docker Hub `gitea/act_runner` repo is deprecated, renamed `gitea/runner`) in **sibling-container mode**: each mounts the host `/var/run/docker.sock`, has its OWN `/data` volume holding the `.runner` registration file (identity + credentials; shared state = re-registration), registers once against `https://git.coreci.dev` (Gitea 1.26.1, probe-verified) with the founder-provided org-level registration token (chat-only, reset after fleet green). Hybrid labels via `GITEA_RUNNER_LABELS`: `node` → `docker://node:24-bookworm`, `python` → `docker://python:3.11-bookworm`, `release` → `docker://node:24-bookworm`, `ubuntu-latest` → `docker://docker.gitea.com/runner-images:ubuntu-latest` (label format `name[:schema[:args]]`; a job's `runs-on` matches label names, the `docker://` image selects the job container). Per-runner `runner.capacity: 1` (default; also caps per-job docker subnet consumption) → fleet concurrency 3. Cache: each runner's built-in cache server must be pinned to a job-reachable `cache.host` + fixed published port (dockerized runners otherwise create per-job networks the cache address is unreachable in — `actions/cache` fails ETIMEDOUT); 32 GB disk guarded by `cache.repo_size_limit`, `health_check.min_free_disk_space_mb`, and a host-side `docker system prune` cron. Workspace-path alignment inside/outside the runner container is NOT needed for our jobs (no `container.bind_workdir`; `docker build` TARS the context over the API) — documented as the known sibling-mode gotcha if a future workflow bind-mounts.
+
+**Workflow lanes (`.gitea/workflows/`):** push lane on `on: push` (all branches) — node lane (label `node`): corepack pnpm 12.3.4 → `pnpm install --frozen-lockfile` → eslint + tsc via `pnpm --filter` over the 5 TS workspaces (never wholesale `turbo lint`, which pulls the venv-dependent ai-service task) → `pnpm web:test` + `pnpm cli:test`; python lane (label `python`): `scripts/bootstrap.sh` venv → `scripts/lint.sh` (ruff) → `scripts/typecheck.sh` (mypy) → `FAST=1 scripts/test.sh` (fast subset `-m "not real_server and not userns"` per D-063 — real_server/userns NEVER in job containers; docker's default seccomp blocks nested `unshare --user` there anyway); ubuntu-latest lane: workflow_dispatch hello-world only (fleet verification, REQ-8-001). Tag lane on `on: push: tags: ['v*']` is the EXCLUSIVE owner of release assets + registry push (D-064): builds from the tag checkout (jobs never have `dist/`), stamps `build:binary` with `gitea.ref_name`, attaches binaries + debs + checksums via the same REST API scripts/release-assets.sh uses (`GET /releases/tags/{tag}` → `POST /releases/{id}/assets`), never `actions/upload-artifact`. Secrets: `REGISTRY_TOKEN` + `GITEA_TOKEN` as org/repo Actions secrets (self-serve `PUT /api/v1/repos/…/actions/secrets/{name}` first, founder UI fallback); the automatic per-job `GITEA_TOKEN` CANNOT publish packages (upstream-confirmed) — the PAT secret is the only viable registry credential. pnpm/pip caches via `actions/cache@v4` (runner 3.x serves cache v2 + self-patches stock actions ≥4.2/4.4) once cache-host pinning is live; deterministic fallback = volume-mounted stores via `container.options` + `valid_volumes`.
+
+**Image layers (multi-stage Dockerfile, `git.coreci.dev/coreci/nextcraft`, amd64 only per D-069):** deps/build stages — web export stage (`node:24-bookworm`, `NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build` → `apps/web/out`, ~16 MB; the URL is build-time-only, inlined by engine-base-url.ts) + venv stage (`python:3.11-bookworm`, `pip install` prod deps from pyproject — no dev extras); runtime stage `python:3.11-slim-bookworm` (~400–500 MB total with the venv ~130 MB + web export + the D-066 CLI-binary embed at `/usr/local/bin/nextcraft`, ~117 MB): non-root `USER nextcraft`, `AI_WEB_STATIC_DIR=/opt/nextcraft/web` (single-port StaticFiles mount, D-039), `NC_CONTAINER=1` entrypoint marker, `HEALTHCHECK CMD` urllib `GET /health` (slim has no curl), `VOLUME /home/nextcraft/.nextcraft` (state root `~/.nextcraft` = DB `data/nextcraft.db` + `sandboxes/`, env-overridable via `AI_DB_PATH`/`AI_SANDBOX_DIR` with `~` expansion — config.py:39/77/86-93), `CMD uvicorn ai_service.main:app --host 0.0.0.0 --port 8420`. Zero AI_* env needed at build; all real-provider keys stay optional at runtime (G-11 fallbacks). Unprivileged by default; the sandbox fabric honestly degrades inside docker (below).
+
+**Deb/binary asset matrix (every release, tag-workflow-built):** `nextcraft-linux-x64` + `.sha256` (existing pipeline, build-binary.mjs SEA), `nextcraft-linux-arm64` + `.sha256` (cross-build: esbuild bundle is arch-agnostic; the ONLY arch-specific step is `copyFileSync(process.execPath, out)` — replaced by a copy from the official `node-v<ver>-linux-arm64.tar.xz` base, probe-verified 200/30 MB; postject adds an ELF note, pure file surgery, never runs the target — QEMU-free per D-69, optional binfmt `--version` smoke if binfmt is registered on CT 113), `nextcraft_<ver>_amd64.deb` / `nextcraft_<ver>_arm64.deb` + `.sha256` (`dpkg-deb --root-owner-group -Zxz`, never executes payload → cross-arch safe; control fields: Package nextcraft, Version = tag minus `v` (policy-clean), Architecture per build, empty Depends, `Recommends: nodejs (>= 18), python3 (>= 3.11), git, util-linux` — soft deps, D-067), binary at `/usr/bin/nextcraft`, postinst = advisory `nextcraft doctor` (never fails dpkg) + next-steps, NO systemd unit (`deploy --service` owns unit generation) + NO proxy fragments. install.sh arch-gate becomes arch-resolve (`x86_64`→x64, `aarch64|arm64`→arm64; sha256 + version integrity gates unchanged). Image tags per D-065: semver `<tag>` + `latest` on newest release, no per-push tags.
+
+**Channel upgrade semantics (D-071):** docker = `docker pull git.coreci.dev/coreci/nextcraft:<tag>` + recreate the container (state persists in the named `nc-state` volume); `deploy`/`bootstrap`/`dev` refuse in-container (D-066 — container check before the repo-root checks, pointer to the docker paths; `doctor`/`verify`/`guide` remain allowed, `verify` gains a container-mode branch checking the mounted web dir + `/health` instead of a repo clone). deb = `dpkg -i` the new deb + `nextcraft deploy --service` (idempotent v0.4.6 rail). binary = re-run install.sh + `nextcraft deploy --service`. doctor detects the channel (NC_CONTAINER/`/.dockerenv` for docker; `dpkg -s`/`/usr/bin/nextcraft` for deb) and describes its upgrade path; `nextcraft guide` serves offline-first embedded man-page text channel-appropriately (D-072 — TS constants bundled by esbuild into the SEA binary, zero runtime fetches).
+
+**Sandbox degrade in containers (D-068):** capability probe promoted verbatim from tests/helpers/userns.py into `ai_service/sandbox/capability.py` (`userns_available()` = `shutil.which("unshare")` guard + real `subprocess.run(["unshare","--user","--map-root-user","true"])`) — the truth source at boot + per-create; container markers (`/.dockerenv`, `NC_CONTAINER=1`, cgroup string) only flavor remediation text. Degrade: boot notice (the main.py:404 mount-less / main.py:202 admin-token G-11 warning pattern), learner sandbox create rejects honestly with 503 + remediation pointer (a new `except SandboxUnavailableError` arm beside the existing `PoolFullError→503` in api/sandboxes.py:157-160 — today it would 500), doctor surfaces the degraded capability via a real userns attempt (upgrading the `which unshare` check, doctor.ts:138-150); chat/agents/grading untouched. Supersedes A-101's cwd-jail fallback for deployed schools (never implemented — no code removal needed).
+
+**Pre-commit rails (D-070):** ONE root `.pre-commit-config.yaml`, local hooks only (ruff on Python paths; eslint/tsc via workspace-scoped invocations), no network at hook run; missing toolchain = loud failure, never silent skip; CI is the authoritative backstop.
+
 ### Confirmed Technology Stack (v0.2)
 
 | Technology | Version | Purpose |
@@ -26,6 +79,8 @@ Nextcraft is a TypeScript monorepo (pnpm workspaces + turborepo) with a Next.js
 | pydantic | 2.13.x | Request/response models, structured outputs |
 | pydantic-settings | 2.15.x | Settings + env-file loading (replaces python-dotenv) |
 | httpx | 0.28.x | Async LLM HTTP client (ollama-cloud + local providers) |
+| sqlmodel / sqlalchemy | 0.0.24 / 2.x | Typed SQLite persistence for the v0.3 engine stores (D-027) |
+| python-multipart | 0.0.x | Multipart audio upload for the defense answer route (REQ-3-006) |
 | sse-starlette | 3.4.x | SSE framing, ping keep-alive |
 | pytest | 9.x | Test runner |
 | pytest-asyncio | 1.4.x | Async tests (auto mode) |
@@ -45,6 +100,16 @@ Deliberately **not** used: openai-python SDK (the `LLMProvider` protocol is the
 7. **D-022 Monorepo integration** — zero-dependency shim `package.json` in apps/ai-service + `ai#*` turbo passthrough tasks (`cache:false, outputs:[]`) + root `ai:dev`/`ai:test` scripts + idempotent venv bootstrap.
 8. **D-023 Testing** — pytest-asyncio auto mode; TestClient `client.stream()` for SSE; httpx MockTransport for byte-exact provider parser tests; scripted mock provider incl. failure modes. Tests never call the cloud.
 
+### v0.4 Architecture Decisions (from Research — Distribution & Bootstrap CLI)
+
+18. **D-033 Binary toolchain = Node SEA (probe-verified)** — Go and Rust are absent from this box; node v24.15.0 ships SEA support (`--experimental-sea-config`, postject-free on linux via `cp node nextcraft && node sea-config` … blob injection with the system `dd`/`npx postject` if needed). CLI source lives in `apps/cli` (TypeScript, compiled to a single CJS bundle by esbuild, then SEA-injected into a copy of the node binary → `nextcraft-linux-x64`). Fallback if SEA breaks: python3 `zipapp` (3.11.2 available). No new toolchain deps beyond dev-scoped esbuild.
+19. **D-034 CLI = thin wrapper, orchestration stays in scripts/** — `nextcraft` composes `apps/ai-service/scripts/bootstrap.sh` and `scripts/dev.sh` equivalents via `spawn` with inherited stdio and timeout guards (A-202/A-209). doctor/bootstrap/verify implement only *checking* logic (prereqs, env template, health) — never re-implement installs. This keeps one source of truth for bootstrap semantics.
+20. **D-035 Install path = repo raw `install.sh` + Gitea latest-release API** — the one-liner `curl -fsSL <forge>/coreci/nextcraft/raw/main/scripts/install.sh | bash` resolves `GET /api/v1/repos/coreci/nextcraft/releases/latest`, downloads the `nextcraft-linux-x64` + `nextcraft-linux-x64.sha256` assets, verifies sha256 (`shasum -a 256`), installs to `~/.local/bin` (PATH hint), and degrades to printed source-bootstrap instructions when no binary asset exists or the platform mismatches (A-203/A-204/A-206).
+21. **D-036 Ongoing binaries = ship-workflow asset step** — the release pipeline (v0.3's `ShipWorkflow.createRelease` equivalent, executed as the ship step's asset stage) builds the binary + checksum and attaches both to every Gitea release from v0.4 onward (A-205). Token resolution stays `.env*`-only (D-006/D-014); binaries are linux x64 only for v0.4 (macOS arm64 deferred — unverifiable on this box).
+22. **D-037 CLI package layout** — `apps/cli` is a pnpm workspace package (`@nextcraft/cli`): `src/` (entry, commands/, checks/, lib/), `scripts/build-binary.mjs` (esbuild bundle → SEA inject), unit tests runnable via `pnpm --filter @nextcraft/cli test` (node:test, no new test framework). Root `package.json` gains `cli:*` passthrough scripts mirroring the `ai:*` pattern (D-022).
+23. **D-038 Network mode (v0.3.5)** — dev binds 0.0.0.0 (`AI_HOST`, default 0.0.0.0, revert via 127.0.0.1); CORS + WS-origin gates read `AI_CORS_ORIGINS` (default `*` — any origin, safe only because credentials are never enabled; explicit comma list restricts); the web client derives the API base URL from the browser hostname at runtime (`engine-base-url.ts`: `NEXT_PUBLIC_AI_SERVICE_URL` override → `http://${window.location.hostname}:8420` → `localhost` server-side). Hotfix also fixes: SEA direct-run detection (`require("node:sea").isSea()` — argv shape differs by invocation style), installer honesty gate (silent `--version` = hard fail), bootstrap venv recovery (poisoned partial `.venv` removal + distro-specific `apt install python3.XX-venv` hint), and doctor venv-capability probe with bootstrap preflight.
+24. **D-039 Single-port deploy + unattended dev (v0.3.6)** — only :8420 is reachable behind HAProxy, so the web app ships as a **static export** (`output: 'export'`, `NEXT_PUBLIC_AI_SERVICE_URL=self` → relative same-origin fetches) served by the ai-service itself (`AI_WEB_STATIC_DIR` StaticFiles mount, default off; `nextcraft dev` auto-wires it when `apps/web/out` exists). Daemon surface: `dev -d` (detached, `~/.nextcraft/run/<clone-hash>/dev.{pid,log}`), `stop`, `log [-n N|-f]`. Durable state (DB `~/.nextcraft/data/`, sandbox workdirs `~/.nextcraft/sandboxes/`) moves **out of the repo** (founder directive; `expanduser` validator makes `AI_DB_PATH=~/...` env overrides work). API routes beat the static mount; unknown paths serve the export's 404.html.
+
 ### v0.3 Architecture Decisions (from Research — Credential Engines)
 
 9. **D-024 Sandbox isolation = Linux namespaces via `unshare`** — per-learner sandbox runs as a subprocess entered into fresh user+mount+pid+network namespaces (`unshare --user --map-root-user --mount --pid --fork --net`). Probe-verified on this box: in-namespace uid=0, **network fully isolated** (0 interfaces), learner writes land in a per-sandbox directory; proc-remount not permitted here but not required. Chosen because no container runtime (docker/podman/bwrap/firejail) exists on the box and there is no sudo. A `SandboxBackend` protocol abstracts the spawner so a future containerd/runc backend can replace namespace-spawning without touching callers.
@@ -65,14 +130,14 @@ Deliberately **not** used: openai-python SDK (the `LLMProvider` protocol is the
 
 | Component | Description | Boundaries | Depends On |
 |-----------|-------------|------------|------------|
-| `ai_service/main.py` | FastAPI app factory, lifespan (httpx client pool, provider factory), CORS (localhost only), /health | App entry | config, llm, agents, api |
+| `ai_service/main.py` | FastAPI app factory, lifespan (httpx client pool, provider factory, SandboxManager + reaper loop, SQLite engine stores on app.state), CORS (localhost only, incl. PUT for file writes), /health; v0.3.6: optional StaticFiles mount of the exported web app when `AI_WEB_STATIC_DIR` is set (single-port deploy, D-039) | App entry | config, llm, agents, api, engines |
 | `ai_service/config.py` | pydantic-settings Settings (env_prefix="AI_", env_file, SecretStr key) | Configuration only | None |
-| `ai_service/api/` | Endpoints: chat.py (POST /v1/chat/stream, SSE), lab.py, assessment.py, proctor.py, mentor.py; deps.py (DI) | Composes agents + sessions; never imported by llm/ or agents/ | agents, llm |
+| `ai_service/api/` | Endpoints: chat.py (POST /v1/chat/stream, SSE), lab.py, assessment.py (POST /v1/assessment/evaluate v0.2 + POST /v1/assessment/grade v0.3), proctor.py, mentor.py, sandboxes.py (lifecycle + files/exec routes, G-5 abuse gates), telemetry.py (WS ingest + trace/gaps reads), variants.py (seeded per-learner variants), defense.py (defense loop, REQ-3-006); deps.py (DI) | Composes agents + sessions + engines; never imported by llm/ or agents/ | agents, llm, sandbox, telemetry, grading, variants, voice |
 | `ai_service/llm/` | types.py (Message; ChatDelta/ChoiceDelta removed in P3 — no consumers), base.py (LLMProvider protocol), openai_compat.py (ollama-cloud + local), mock.py (deterministic), factory.py | Never imports agents/ or api/ | config |
-| `ai_service/agents/` | base.py (BaseAgent ABC), registry.py, session.py (SessionStore), structured.py (JSON defense), coach/tutor/lab/assessor/proctor/mentor.py | Never imports api/ | llm, prompts, corpus |
+| `ai_service/agents/` | base.py (BaseAgent ABC), registry.py, session.py (SessionStore), structured.py (JSON defense), coach/tutor/lab/assessor/proctor/mentor.py + examiner.py (seventh agent, v0.3) | Never imports api/ | llm, prompts, corpus, telemetry |
 | `ai_service/prompts/` | Per-agent system prompt constants + render_context functions (str.format_map) | Data only | None |
-| `ai_service/corpus/` | Mock engine inputs: learner_context.py, telemetry.py (Lab/Proctor scenarios), artifacts.py (pre-baked artifacts, rubrics, transcripts) | Pydantic-typed; aligned with TS packages/mock-data by convention | None |
-| `scripts/` | bootstrap.sh (venv + pip install idempotent), dev.sh (exports keys from .ciagent/.env.secrets → uvicorn), test.sh (pytest), lint.sh (ruff check, G-3) | Dev entry points | pyproject.toml |
+| `ai_service/corpus/` | Mock engine inputs: learner_context.py, telemetry.py (Lab/Proctor scenarios), artifacts.py (pre-baked artifacts, rubrics, transcripts). Since v0.3 P6 these are DORMANT, test-only fixtures (dormant-header noted) — the live learner path uses real engine inputs | Pydantic-typed; aligned with TS packages/mock-data by convention | None |
+| `scripts/` | bootstrap.sh (venv + pip install idempotent), dev.sh (exports keys from .ciagent/.env.secrets → uvicorn), test.sh (pytest), lint.sh (ruff check, v0.2 G-3) | Dev entry points | pyproject.toml |
 | `tests/` | conftest.py (mock provider, settings override, TestClient), health, llm (MockTransport parser), agents (framework + per-agent), api (SSE stream tests) | Mock provider only — no cloud | all |
 
 **Module boundary rules:** `llm/` never imports `agents/` or `api/`; `agents/` never imports `api/`; `api/` composes both via DI. `corpus/` is the only home of mock engine data. Prompts are code — versioned and reviewed in git.
@@ -82,35 +147,51 @@ Deliberately **not** used: openai-python SDK (the `LLMProvider` protocol is the
 | Component | Description | Boundaries | Depends On |
 |-----------|-------------|------------|------------|
 | `ai_service/sandbox/` | `backend.py` (SandboxBackend protocol), `unshare_backend.py` (userns/mount/pid/net spawner, D-024), `manager.py` (lifecycle: create/list/snapshot/destroy + concurrency guard D-032), `workdir.py` (per-sandbox fs layout) | Never imports api/ or agents/; spawns subprocesses only | config |
-| `ai_service/telemetry/` | `models.py` (TelemetryEvent, TraceSpan), `store.py` (TraceStore protocol + SQLite impl D-027), `ingest.py` (WebSocket /v1/telemetry/ingest, seq gap detection D-026) | Persistence; never imports agents/ | config |
-| `ai_service/grading/` | `features.py` (deterministic trace digest D-028), `engine.py` (rubric scoring orchestration), `store.py` (GradeStore) | LLM only via digest; never sees raw trace | llm, telemetry, prompts |
-| `ai_service/variants/` | `templates.py` (task template library), `generator.py` (seeded LLM instantiation D-029), `store.py` (VariantStore) | LLM via structured output | llm, grading |
-| `ai_service/voice/` | `base.py` (VoiceProvider protocol D-030), `openai_audio.py` (STT/TTS vs compatible endpoint), `browser.py` (native SR/TTS fallback descriptor), `mock.py` (deterministic) | Never imports agents/ or api/ | config |
+| `ai_service/telemetry/` | `models.py` (TelemetryEvent, TraceSpan), `store.py` (TraceStore protocol + SQLite impl D-027), `ingest.py` (WebSocket /v1/telemetry/ingest, seq gap detection D-026; v0.5 REQ-5-007/D-045: emits advisory `seq_ack` frames — highest-contiguous received seq per successful append; capture agent trims its spool to the ack, closing the replay-margin gap) | Persistence; never imports agents/ | config |
+| `ai_service/grading/` | `features.py` (deterministic trace digest D-028 — kind-agnostic by construction, pinned over design/sim traces in v0.5), `engine.py` (rubric scoring orchestration), `store.py` (GradeStore) | LLM only via digest; never sees raw trace | llm, telemetry, prompts |
+| `ai_service/variants/` | `templates.py` (task template library; v0.5 REQ-5-005/D-044: `environment: Literal[build,design,simulation]` registry + per-kind starter files + harness/test commands, G-15 shlex-roundtrip validation), `generator.py` (seeded LLM instantiation D-029), `store.py` (VariantStore; idempotent `_ensure_v05_columns` backfill for pre-v0.5 DBs) | LLM via structured output | llm, grading |
+| `ai_service/voice/` | `base.py` (VoiceProvider protocol D-030), `browser.py` (native SR/TTS fallback descriptor), `mock.py` (deterministic), `openai_audio.py` (v0.5 REQ-5-001, D-040: real server STT/TTS against OpenAI-compatible `/audio/transcriptions` + `/audio/speech` on the shared httpx pool — CUT-1/G-7 seam CLOSED), `factory.py` (provider selection by `AI_VOICE_PROVIDER`, G-11 boot-safe fallback to mock), `defense_store.py` (DefenseStore: transcripts + integrity signals, D-027) | Never imports agents/ or api/ | config |
+| `ai_service/identity/` | **v0.5 NEW (REQ-5-003/004, D-042/43):** `base.py` (IdentityProvider protocol: submit/poll/verify), `mock.py` (deterministic approve-on-policy mock; verdicts carry a `mock` marker, A-304), `store.py` (5th D-027 store: identity_record table — derived `age_band`, document **refs**, PII never stored raw); age-gate dependencies `require_verified_age`/`require_verified_adult` (gate composition D-043: G-5 allowlist → identity verdict → rate caps; mounted on variants/sandbox-create/defense-start + the G-18 marketplace stub), exposed via `api/identity.py` (`/v1/identity/*`) | Never imports agents/; api/ composes it via DI | config |
+| `ai_service/marketplace/` | **v0.6 NEW (REQ-6-001..006, D-048..D-056):** `base.py` (pydantic contracts: Posting/Employer/PostingTags/IngestPosting), `store.py` (6th D-027 store, SIX tables per G-104: posting/employer/embedding/application/employer_enrichment/learner_profile), `ingest.py` (PostingSource protocol + seeded corpus, idempotent upserts G-102), `tagging.py` (D-020 one-shot tag extraction, overwrite semantics D-052), `embedding/` (EmbeddingProvider protocol + deterministic feature-hash mock + OpenAI-compatible real path + G-11 factory, D-051), `search.py` (hybrid facet+cosine ranking, embed-on-publish, skill_breakdown), `enrichment.py` (append-only provenance rows + merge-on-read manual>llm>raw, D-053), `resume.py` (pypdf text extraction + bounds + D-020 draft extraction, D-054); HTTP surface in `api/marketplace.py` (public + apply + resume), `api/marketplace_admin.py` (fail-closed D-057), `api/marketplace_shells.py` (G-101 catch-all), `api/sitemap.py` (dynamic sitemap/robots, D-056) | Never imports agents/ or api/; api/ composes via DI | config |
 | `ai_service/agents/examiner.py` | Seventh agent: oral defense examiner; streams over existing SSE, consumes process traces + emits integrity signals | reuses BaseAgent (D-018) | llm, prompts, telemetry |
-| `ai_service/data/*.db` | SQLite databases (telemetry/grades/variants/defenses) | gitignored | — |
+| `ai_service/data/*.db` | SQLite databases (telemetry/grades/variants/defenses) — **v0.3.6: default moved to `~/.nextcraft/data/nextcraft.db` (state out of the repo; AI_DB_PATH overrides, ~ expanded)** | outside repo (home) | — |
 | `scripts/sandbox-agent.py` | Tiny in-namespace capture process shipped into the sandbox; streams telemetry to ingest | standalone | stdlib only |
 
 **Boundary additions:** `sandbox/`, `telemetry/`, `grading/`, `variants/`, `voice/` are engine modules — they never import `api/` (which composes them via DI) and never import `agents/` (agents call engines through narrow interfaces, not vice versa).
 
+### apps/cli — Nextcraft Bootstrap CLI (v0.4 NEW)
+
+| Component | Description | Boundaries | Depends On |
+|-----------|-------------|------------|------------|
+| `src/index.ts` | Entry: arg parsing (no deps beyond node stdlib at runtime), command dispatch, `--help`/`--version`, exit-code contract (0 ok / 1 failure / 2 usage) | CLI surface only | commands/ |
+| `src/commands/` | `doctor.ts` (prereq checks + actionable errors), `bootstrap.ts` (pnpm install + scripts/bootstrap.sh wrapper + env template copy + key validation), `verify.ts` (health: venv imports, ports, env, build readiness), `dev.ts` (thin passthrough to scripts/dev.sh) | Compose checks/ + lib/; spawn scripts — never re-implement them | checks/, lib/ |
+| `src/checks/` | Pure check functions: `check-command.ts` (binary-on-PATH + version compare), `check-env.ts` (template diff, required/optional key classification) | Pure logic, unit-testable, no fs side effects at import | None |
+| `src/lib/` | `spawn.ts` (subprocess with timeout + inherited stdio), `log.ts` (✓/✗/warn output formatter) | Shared utilities | None |
+| `scripts/build-binary.mjs` | esbuild → CJS bundle → Node SEA injection → `dist/nextcraft-linux-x64` + sha256 sidecar | Build-time only | esbuild (dev dep) |
+| `scripts/install.sh` | The one-liner install script served from repo raw: Gitea latest-release resolve → download + checksum verify → ~/.local/bin; source-bootstrap fallback | Standalone POSIX sh | forge API |
+| `tests/` | node:test unit tests: command dispatch, check logic, env template diff, install-script shellcheck-style assertions | Fixtures only — never mutate repo state | src/ |
+
+**Boundary rules:** the CLI never imports from `apps/web`, `packages/*`, or `ai_service` Python modules — it orchestrates them exclusively via subprocess/filesystem. Runtime deps: node stdlib only (no runtime npm deps; esbuild is dev-only). The binary embeds the bundle; `scripts/bootstrap.sh` remains the single source of bootstrap truth (D-034).
+
 ### apps/web — Next.js Application
 
 | Component | Description | Boundaries | Depends On |
 |-----------|-------------|------------|------------|
-| `app/(learner)/` | Learner surface route group: landing, catalog, competency stack, dashboard, byte viewer, sandbox mockup, assessment mockup | Learner-only routes and layouts | packages/ui, packages/mock-data, packages/types |
+| `app/(learner)/` | Learner surface route group: landing, catalog, competency stack, dashboard, byte viewer, build surface (`/build/[competencyId]` — real in-browser build), defense surface (`/defend/[competencyId]` — live oral defense + grading) | Learner-only routes and layouts | packages/ui, packages/mock-data, packages/types |
 | `app/(marketplace)/` | Marketplace surface route group: job board, job detail, employer profile, search/filter, pricing | Marketplace-only routes and layouts | packages/ui, packages/mock-data, packages/types |
 | `app/(employer)/` | Employer dashboard route group: overview, talent search, candidate profile, posting management | Employer-only routes and layouts | packages/ui, packages/mock-data, packages/types |
 | `app/(admin)/` | Admin surface route group: overview, learner management, competency graph viewer, moderation | Admin-only routes and layouts | packages/ui, packages/mock-data, packages/types |
 | `app/layout.tsx` | Root layout: theme provider, navigation shell, responsive container | All routes | packages/ui |
-| `components/` | Surface-specific components (learner/, marketplace/, employer/, admin/) plus shared chrome (navigation-shell, header/footer, role-switcher, theme-provider, breadcrumbs, dark-mode-toggle) | App-level components | packages/ui |
-| `hooks/` | use-chat-stream.ts — SSE client hook: fetch + ReadableStream, byte buffering + frame reassembly, idempotent AbortController cleanup | Client components only | ai-service SSE |
-| `lib/` | sse.ts (shared SSE frame parser — CRLF normalization + `: ping` immunity, G-1), breadcrumbs.ts, format.ts | Pure utilities | None |
+| `components/` | Surface-specific components (learner/, marketplace/, employer/, admin/) plus shared chrome (navigation-shell, header/footer, role-switcher, theme-provider, breadcrumbs, dark-mode-toggle); v0.3 learner: build-surface, sandbox-terminal (read-only exec output), defense-session | App-level components | packages/ui |
+| `hooks/` | use-chat-stream.ts — SSE client hook: fetch + ReadableStream, byte buffering + frame reassembly, idempotent AbortController cleanup; use-sandbox-session.ts (v0.3) — sandbox lifecycle for the build session: create on task open, destroy on unmount, mid-start failure cleanup, 503/403/429 honest surfaces | Client components only | ai-service SSE / engine API |
+| `lib/` | sse.ts (shared SSE frame parser — CRLF normalization + `: ping` immunity, v0.2 G-1), breadcrumbs.ts, format.ts, engine-base-url.ts (v0.3.5: runtime API base — env override → browser hostname → localhost), engine-client.ts (v0.3: typed fetch client for /v1/sandboxes, files/exec, variants, grade, defense, traces) | Pure utilities | None |
 
 ### packages/ui — Shared Component Library
 
 | Component | Description | Boundaries | Depends On |
 |-----------|-------------|------------|------------|
 | `tokens/` | Design tokens as TS constants: colors, spacing, radii, shadows, breakpoints (mirrored as Tailwind v4 `@theme` tokens in apps/web globals.css) | Foundation layer — no dependencies | None |
-| `primitives/` | Button, Input, Card, Badge, Avatar — each with a Storybook story | Atomic UI components | tokens, packages/types |
+| `primitives/` | Button, Input, Card, Badge, Avatar (v0.1) + TerminalFrame, TelemetryStatus, MicControl, GradeBadge, TranscriptViewer (v0.3 build/defense surfaces) — each with a Storybook story | Atomic UI components | tokens, packages/types |
 
 Composite/layout/theme components (navigation shell, tables, chat panels, graph viewer, theme provider) live in `apps/web/components/` as app-level components, not in packages/ui.
 
@@ -134,11 +215,42 @@ Composite/layout/theme components (navigation shell, tables, chat panels, graph
 | `marketplace.ts` | Job, Employer, Candidate, JobPosting, TalentMatch, SearchFilter | Marketplace types | None |
 | `user.ts` | Learner, Admin, EmployerUser, AgeGroup, Role | User types | None |
 | `ui.ts` | Component props, theme config, breakpoint definitions | UI types | None |
+| `telemetry.ts` | TelemetryEvent/ExecResult wire shapes for the live build surface (v0.3) | Engine types | None |
+| `variants.ts` | Variant/TaskTemplate shapes for per-learner task statements (v0.3) | Engine types | None |
+| `grading.ts` | GradeRecord/RubricScore shapes for live grading display (v0.3) | Engine types | None |
+| `defense.ts` | DefenseSession/transcript/integrity-signal shapes for the defense surface (v0.3) | Engine types | None |
 
 ---
 
 ## Data Flow
 
+### v0.3 credential flow (current)
+
+```
+[learner build surface /build/*]                [learner defense surface /defend/*]
+   file CRUD + Run/Test (HTTP)                     mic MediaRecorder / typed + TTS playback
+        │                                                  │
+        ▼                                                  ▼
+[api/sandboxes files/exec] ──exec──▶ [namespace sandbox]    [api/defense start/answer/finish]
+        │                            │ capture agent        │
+        │                            ▼ (WS telemetry)      ▼
+        │                    [api/telemetry ingest]   [DefenseStore (SQLite)]
+        │                            │ SQLite               │ transcript + integrity signals
+        │                            ▼                      │
+        │                      [TraceStore] ────▶ [GradingEngine: digest (grading/features)
+        │                            │                + rubric LLM (D-028)] ──▶ [GradeStore]
+        │                            ▼                      ▼
+        └──▶ Lab agent (live digest)          Assessor (grade output) / Proctor (integrity)
+                                             Examiner agent (SSE) ◀── defense sessions
+   variants: [api/variants] ◀── [VariantStore (seeded, D-029)] ── per-learner task statements
+```
+
+- Lab consumes the live trace digest; Assessor consumes grading-engine output; Proctor consumes telemetry + defense integrity signals (REQ-3-007) — no mock fallback in the learner path (v0.2 corpus scenarios are dormant test-only fixtures).
+- The learner's path is: variant task → in-sandbox build (telemetry streams to SQLite) → grade My Work (rubric scores from the real trace) → oral defense → verdict.
+- Flooded/gapped traces are terminal: ingest closes 1008 and marks INCOMPLETE_FLOODED (G-3); the grader returns UNGRADABLE_TRACE_INCOMPLETE (G-4) — no credential from an incomplete trace.
+
+### v0.2 chat flow (complete, still live)
+
 ```
 [packages/mock-data + packages/types]      [ai_service/corpus]
         │ (TS, web surfaces)                      │ (Python, agent inputs)
@@ -153,21 +265,27 @@ Composite/layout/theme components (navigation shell, tables, chat panels, graph
                                                (https://ollama.com/v1)
 ```
 
-- Web surfaces remain server-component-first; client components (chat, filters, graph viewer, dark mode toggle) fetch directly from ai-service over SSE (A-002: no Next.js API-route proxy in v0.2).
-- The LLM provider layer is a dumb pipe — OpenAI-compatible chunks pass through byte-identical; envelope logic (meta/done/error) lives only in the API layer (D-016).
-- Lab/Assessor/Proctor read mock scenarios from `ai_service/corpus/` — real engines are v0.3+.
+- Web surfaces remain server-component-first; client components (chat, filters, graph viewer, dark mode toggle) fetch directly from ai-service over SSE (A-002: no Next.js API-route proxy).
+- The LLM provider layer is a dumb pipe — OpenAI-compatible chunks pass through byte-identically; envelope logic (meta/done/error) lives only in the API layer (D-016).
+- The v0.2 corpus scenarios (`ai_service/corpus/`) are retained as dormant, test-only fixtures (dormant-header noted); they are no longer inputs to the live learner path.
 - All automated tests use the deterministic mock provider; the cloud is for manual probes only.
 
 ---
 
-## Build Order (v0.3)
+## Build Order (v0.4)
+
+1. **Bootstrap CLI core** — apps/cli package: doctor checks (node/pnpm/python3/git/unshare), bootstrap wrapper (pnpm install + scripts/bootstrap.sh + .env template + key validation), verify health check, dev passthrough; unit tests
+2. **Binary build + release pipeline** — esbuild bundle → Node SEA binary (`nextcraft-linux-x64`) + sha256 sidecar; install.sh one-liner (Gitea latest-release resolve + checksum verify + PATH install); release-asset upload wired into the ship flow (ongoing binaries from v0.4 onward)
+3. **Install docs + fresh-clone E2E** — README quickstart (one-liner → doctor → bootstrap → dev), CLI reference, fresh-clone end-to-end test proving a clean clone reaches a running stack
+
+## Build Order (v0.3 — complete)
 
 1. **Sandbox fabric** — SandboxBackend protocol + unshare namespace spawner + lifecycle manager (create/list/snapshot/destroy) + concurrency guard + per-sandbox workdir; isolation + resource-limit probes
 2. **Live build telemetry** — TelemetryEvent models + SQLite TraceStore + WebSocket ingest endpoint + seq gap detection + in-sandbox capture agent
 3. **Process-trace grading engine** — deterministic feature/digest computation + rubric scoring via LLM structured output + GradeStore; calibrated against v0.2 mock corpora
 4. **Variant task generation** — template library + seeded LLM instantiation + VariantStore + difficulty normalization anchors
 5. **Oral / voice defense** — VoiceProvider protocol + STT/TTS + mock + browser fallback + Examiner agent + transcript/integrity-signal capture
-6. **Agent re-grounding + learner surface integration** — Lab/Assessor/Proctor consume real telemetry/grades/defense signals; learner sandbox mockup → real in-browser xterm.js build/run; assessment mockup → live defense + live grading
+6. **Agent re-grounding + learner surface integration** — Lab/Assessor/Proctor consume real telemetry/grades/defense signals; learner sandbox mockup → real in-browser build/run (Run/Test buttons executing in a namespace sandbox, read-only exec-output panel — no interactive shell, CUT-2/G-8); assessment mockup → live defense + live grading
 
 ---
 
@@ -184,16 +302,19 @@ The v0.1 build order (monorepo → types → mock data → tokens → primitives
 
 ---
 
-## Future Architecture (Post-v0.3, for reference)
+## Future Architecture (Post-v0.4, for reference)
 
-v0.3 delivers the real credential engines; later milestones fill in the remaining platform:
+v0.4 delivers distribution (CLI + binary releases); later milestones fill in the remaining platform:
 
 - **In-memory sessions → PostgreSQL + Drizzle/SQLModel** — SessionStore + v0.3 TraceStore/GradeStore/VariantStore/DefenseStore protocols swap SQLite→Postgres with no API changes
 - **userns subprocess sandboxes → containerd/runc backend** — D-024 `SandboxBackend` protocol swap; same lifecycle API
-- **Coding-IDE sandbox → design tool + simulation environments** — REQ-F-021 full scope (v0.4)
+- **Coding-IDE sandbox → design tool + simulation environments** — REQ-F-021 full scope (v0.5)
 - **Mock provider → per-agent model routing** — provider factory already selects by config; per-agent `AI_<AGENT>_MODEL` overrides
-- **No auth → real KYC + sessions** — **deferred per founder directive**; REQ-F-017 identity/age-gating lands post-v0.3 (v0.4+). Age-gating remains the v0.1 visual flow mockup
+- **No auth → real KYC + sessions** — **deferred per founder directive; moved to v0.5 with D-016**; REQ-F-017 identity/age-gating lands post-v0.4. Age-gating remains the v0.1 visual flow mockup
+- **Mock voice → real server STT/TTS (openai-audio provider)** — CUT-1/G-7 seam moved to v0.5 per D-016; VoiceProvider protocol is the drop-in point
+- **linux x64 binary → macOS arm64 + auto-update** — D-036 defers non-linux targets (unverifiable on this box); `nextcraft upgrade` (self-replace from latest release) is the natural v0.5+ follow-up
+- **Exec-telemetry seq-lease / replay-margin fix** — the P6-lesson one-line ACK gap moves to v0.5 per D-016
 - **No search → Semantic vector search (pgvector)** — Filter UI replaced with vector similarity search
 - **No payments → Payment processing** — Pricing page replaced with real subscription/payment flows
 
-The monorepo structure (apps/web + apps/ai-service + packages/*) accommodates further apps without restructuring.
+The monorepo structure (apps/web + apps/ai-service + apps/cli + packages/*) accommodates further apps without restructuring.

.ciagent/CHECKPOINT.json

@@ -1,8 +1,9 @@
 {
-  "phase": 1,
-  "stage": "complete",
-  "milestone": "v0.3",
+  "phase": 2,
+  "stage": "ship",
+  "milestone": "v0.8",
+  "milestone_name": "ship-anywhere",
   "phase_role": "execution",
   "attempts": 0,
-  "updated_at": "2026-09-11T18:43:22Z"
-}
+  "updated_at": "2026-09-29T14:50:00Z"
+}

.ciagent/GRILL.md

@@ -1,3 +1,51 @@
+# Nextcraft v0.6 — GRILL.md (Adversarial Review Verdict)
+
+**Stage:** GRILL, Phase 0 pre-execution · **Verdict:** GO-WITH-BINDINGS · **Confidence:** 0.72 · **Date:** 2026-09-21
+
+## Summary
+
+The v0.6 Marketplace Engine plan (46 tasks, 6 phases) is well-researched and tightly scoped, but its central P1 web-migration mechanism — removing `generateStaticParams` from the two marketplace dynamic routes — is **provably build-breaking**: Next 15.5.25 (installed `node_modules/next/dist/build/index.js:1244`) hard-throws error E87 for any dynamic route without `generateStaticParams` under `output: 'export'`, and even a function returning `[]` throws (`length > 0` check). The claimed "proven build/defend pattern" precedent does not exist as described — build/defend routes KEPT their `generateStaticParams`. Four quieter gaps (ingest status semantics, pagination-vs-client-filters, learner-profile sidecar persistence, sitemap origin) each ship a broken happy path or an audit flag. All fixed via binding decisions G-101..G-110 + 8 plan edits applied by the orchestrator before execute.
+
+## Per-Axis Findings
+
+| Axis | Verdict | Rationale |
+|------|---------|-----------|
+| Feasibility | PASS | Personas/territories match proven patterns (voice factory, identity store, D-020 layer); 46 tasks comparable to shipped v0.5. |
+| Scope discipline | PASS | Pricing/employer-auth/scheduler/crawler all absent (MH-M6, A-407/A-412, D-050); only borderline add is admin posting-edit, defensible as the re-tag trigger within A-401. |
+| Vertical-slice integrity | FAIL → fixed | P1 backend+shells coupling is right, but the shell mechanism threw E87 at build and runtime-created postings would get no exported page — fixed by G-101 (placeholder param + FastAPI catch-all shell routes). |
+| Testability | AT-RISK → fixed | MH-1e pinned a build that could not emit; MH-3d's "matchScore exists nowhere" overclaimed (mock-data retains it for employer/admin mockups) — scoped by G-107/G-110. |
+| Security posture | PASS | Fail-closed admin, D-043 gate order, upload bounds, PII sentinel tests verified against existing code; hardening added by G-105/G-108. |
+| Performance/capacity | PASS | Brute-force cosine ≤10⁴ honest; SQLite WAL/busy_timeout verified in the identity store; sitemap fine to 50k URLs. |
+| Operational readiness | AT-RISK → fixed | D-039 deploy fabric intact (mount order verified), pypdf via bootstrap channel sound; founder workflow breaks at ingest-status (G-102) and sitemap-origin (G-105) — now defined. |
+| Dependency risk | PASS | pypdf verified as the only new dep; JSON-LD/sitemap hand-rolled; embedding mock stdlib-only. A-404's stale "ollama-cloud exposes /embeddings" parenthetical annotated as superseded by D-051. |
+| Adoption/UX | AT-RISK → fixed | Happy-path steps 2-4 contradicted until ingest status defined (G-102); verify-CTA/404/409 states well-specified; sitemap URL-resolvability pinned (G-109). |
+
+## Binding Decisions (applied to PLAN.md before execute)
+
+- **G-101** — Do NOT remove `generateStaticParams` (E87 build break under `output:'export'`). Keep it returning one placeholder param per route; export one client shell; add FastAPI catch-all `GET /marketplace/jobs/{id}` + `/employers/{id}` (trailing-slash variants) serving the shell — same routes-beat-the-mount mechanism as sitemap. [Vertical-slice integrity]
+- **G-102** — Ingest-status contract: seed-port postings enter `published` with original `postedAt`; admin-authored start `draft`. [Adoption/UX]
+- **G-103** — Board fetch = paged fetch-all (≤10⁴ documented); API returns `total_published`; "Showing X of Y" over the fetched set with honest truncation notice. [Performance]
+- **G-104** — Confirmed learner profiles persist in the marketplace store as a 6th table `learner_profile` (learner_id PK, profile JSON, confirmed_at, model) — NOT a filesystem sidecar. D-049 amended five→six tables. [Scope discipline]
+- **G-105** — Unset `AI_PUBLIC_BASE_URL`: loud G-11 boot warning; sitemap serves empty static set + warning (never malformed/relative URLs); robots omits the Sitemap directive; boot never crashes. [Security]
+- **G-106** — Match scores appear only in search context; cards without an active query show no score; per-learner profile-driven card scores post-v0.6; REQ-6-003 "scores on job cards" satisfied conditionally — recorded. [Adoption/UX]
+- **G-107** — "Mock matchScore absent" scoped to marketplace-path API payloads + marketplace surfaces; grep excludes packages/mock-data and employer/admin route groups. [Testability]
+- **G-108** — `admin_token` as `SecretStr`; compare via `secrets.compare_digest`. [Security]
+- **G-109** — Every sitemap job/employer URL must serve 200 on the single-port app (G-101 shells); board ItemList JSON-LD enumerates static structure only — never runtime postings. [Operability]
+- **G-110** — P1 web tests pin the E87 regression class itself (shells emitted; catch-all serves arbitrary ids; `notFound()` at non-placeholder id via full page load); the honest-501 stub pin at tests/identity/test_identity.py:444 rewritten onto the marketplace router in the same phase. [Testability]
+
+## Plan Edits Applied
+
+1. Task 1-3-04 + MH-1e rewritten per G-101 (placeholder shells + catch-all routes; E87 test class; stub-pin rewrite)
+2. Task 1-2-01 + MH-1f ingest-status contract (G-102)
+3. Task 1-3-02 paged fetch-all + total_published (G-103)
+4. Task 4-B-03 learner_profile table replaces the JSON sidecar (G-104; D-049 → six tables)
+5. Task 5-2-01 + MH-5a/5b unset-origin behavior + URL-resolvability (G-105/G-109)
+6. Task 3-3-01 + MH-3d matchScore scope + no-query-no-score (G-106/G-107)
+7. Task 1-2-03 SecretStr + compare_digest (G-108)
+8. PROJECT.md A-404 stale parenthetical annotated as superseded by D-051 probe
+
+---
+
 # Nextcraft v0.3 — GRILL.md (Adversarial Review Verdict)
 
 **Stage:** GRILL, Phase 0 pre-execution · **Verdict:** GO-WITH-CHANGES · **Confidence:** 0.72
@@ -46,3 +94,127 @@ The credential-pipeline architecture (telemetry → trace → grade → defense)
 ## Outcome
 
 **GO** — all six binding decisions and both scope cuts applied to PLAN.md / REQUIREMENTS.md / ROADMAP.md / PROJECT.md before Phase 1 execution. No axis requires escalation (all resolvable at confidence ≥ 0.85). The milestone no longer claims resource enforcement it cannot deliver, and the no-auth abuse vector is closed at MVP scale.
+
+---
+# Nextcraft v0.4 — GRILL.md (Adversarial Review Verdict)
+
+**Stage:** GRILL, Phase 0 pre-execution · **Verdict:** GO-WITH-CHANGES · **Confidence:** 0.83
+
+## Summary
+
+The distribution milestone is small, founder-directed (D-016, confidence 0.99), and additive (zero changes to the running credential pipeline). The plan's central risk: **Node SEA was probe-verified as a flag, not as a working build** — the v0.3 lesson (A-101: probe the mechanism, not the existence) applies. Second gap: a binary whose `--version` lies (stale package.json) would poison the "ongoing binaries" contract. Third: sed-based JSON parsing in install.sh is a fragility + integrity risk. Fourth: "ongoing binaries" has no enforcement mechanism beyond prose. All four closed by binding decisions G-101..G-104 below. No scope cuts required — the milestone is already minimal.
+
+## Per-Axis Findings
+
+| Axis | Verdict | Rationale |
+|------|---------|-----------|
+| Business case | PASS | Founder directive explicit + recorded (D-016). Evidence of need: live Gitea probe shows latest release v0.2.8 with ZERO assets; bootstrap requires repo archaeology (scripts found only via package.json spelunking). |
+| Scope | PASS | 5 REQs, 3 execution phases, one focused surface (apps/cli + scripts). Smallest milestone yet. macOS arm64 already cut (D-036, unverifiable here). |
+| Feasibility | CONCERN (fixed) | SEA flag exists on node v24.15.0, but no end-to-end SEA binary was built during RESEARCH. postject availability assumed (`npx postject` — needs npm registry reachability, unproven). Zipapp fallback requires python3 on target — an honest-degradation ladder, not a silent downgrade. → G-101. |
+| Honest versioning | CONCERN (fixed) | `--version` from package.json would print a stale hardcoded version inside a per-release binary — breaks upgrade detection + the one-liner's re-run-to-upgrade promise. → G-102. |
+| Install integrity | CONCERN (fixed) | sed/grep JSON parsing is brittle; a parse failure must never fall through to installing an unverified artifact. Exact asset-name matching + hard-degrade to source instructions. → G-103. |
+| Sequencing | PASS | P1 CLI (source-runnable) → P2 binary+pipeline → P3 docs+E2E matches dependency order; each phase ships independently. |
+| Cost/quota | PASS | Zero new paid infra; binaries built on-box; Gitea releases free. Dev-only esbuild dep. |
+| Risks | CONCERN (fixed) | Top 3: SEA end-to-end (→ G-101 live probe FIRST in P2), npm registry reachability for esbuild (→ proven by P1's pnpm install must-have), Gitea asset-upload token scope (→ live-proven at the v0.3.2 ship itself). |
+| Adoption/operability | PASS | Consumer = founder + future pilots; one command replaces README archaeology. Rollback trivial (rm ~/.local/bin/nextcraft). No server changes. |
+
+## Binding Decisions (applied to PLAN.md)
+
+- **G-101 (BINDING) — SEA live-build probe is the FIRST P2 action.** Task 2-1-01 builds a real binary before anything depends on it; the build script encodes the fallback ladder explicitly (SEA → zipapp with "requires python3" honesty). If SEA fails on this box, zipapp becomes primary with the docs stating the requirement — no silent claim of node-less operation.
+- **G-102 (BINDING) — Version stamping at build time.** `build-binary` accepts the shipping tag and stamps it into the bundle (`NEXTCRAFT_VERSION` replace); `--version` prints it; install E2E asserts the installed binary reports the tag it was downloaded from. A binary may never report a version it was not built as.
+- **G-103 (BINDING) — Install-script integrity hard-degrade.** install.sh matches assets by EXACT name (`nextcraft-linux-x64`, `nextcraft-linux-x64.sha256`); any parse/lookup/download failure degrades to source-bootstrap instructions (exit 0) — never installs unverified or name-approximate artifacts. Checksum mismatch = hard stop, exit 1, explicit do-not-run message. dash-safe POSIX sh, no jq.
+- **G-104 (BINDING) — Ongoing-binaries enforcement.** Every ship from v0.3.2 onward MUST run `scripts/release-assets.sh <tag>` after tag+merge (best-effort, non-blocking, `release_pending` escalation on failure — but attempted + logged every release). The final-phase audit gate includes "milestone release carries both assets" as a check. This makes the founder's "ongoing binaries" directive a pipeline property, not prose.
+
+## Escalations
+
+None. All four concerns resolved at confidence ≥ 0.85. No axis requires founder escalation (directive already explicit).
+
+## Outcome
+
+**GO** — G-101..G-104 applied to PLAN.md before Phase 1 execution. The milestone claims only what its probes prove, and the ongoing-binaries contract has an enforcement mechanism.
+
+---
+
+# v0.5 GRILL (Phase 0, 2026-09-13) — Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease
+
+**Verdict: GO-WITH-CHANGES · Confidence: 0.78** — CUT-3 + G-9..G-18 binding; applied to PLAN.md before P1 execution.
+
+**Evidence:** every load-bearing plan claim verified against ground-truth code and held (fmt bug defense.py:189, descriptor flow defense.py:143, supervisor frame discard sandbox-agent.py:487-496, no spool cap, dead test_command field, one-line replay margin sandbox-agent.py:416-431, factory rejection). The research layer (D-040..D-046) sold no vapor; the misses were all *interaction* surface.
+
+## Binding items (all applied to PLAN.md)
+
+- **CUT-3**: MH-3e identity E2E downgraded from real-app uvicorn harness to `TestClient(create_app(...))` — identity is plain JSON HTTP; the uvicorn harness stays where transport matters (P1 durability, P4 in-ns exec).
+- **G-9**: `verified_pilot` conftest fixture MUST land with the identity gates (Wave 3-2) — variants/defense are ungated today; without the fixture the existing 413-test suite 403s en masse. MH-M6 reworded: regressions zero *for verified allowlisted pilot learners*.
+- **G-10**: engine-client must discriminate 403 reasons (`verify_cta` → new `VerifyRequiredError`; allowlist detail → existing `NotAllowlistedError`) — today every 403 collapses into NotAllowlistedError, which would render a verify-CTA as an allowlist lie.
+- **G-11**: misconfigured `openai-audio` must never crash the boot — lifespan catches the factory error, logs loudly, falls back to mock (descriptor honestly reads mock). Unattended deploy (D-039) survival rule.
+- **G-12**: client recording bound — auto-stop at 180s default + visible timer + timeslice; 413 renders "re-record" honestly (never silent answer loss).
+- **G-13**: identity submit caps — one active pending per learner (409 on resubmit) + per-learner rate cap (429); each submission becomes vendor money later.
+- **G-14**: spool-bound overflow is by-design gap creation — pinned: dropped-counter > 0 → replayed trace gapped → ungradable (never silently-truncated-but-gradable); worst-case spool ≈256MB documented against the 512MB G-2 sweep.
+- **G-15**: argv contract — templates validate shlex-roundtrip at definition (no quotes/globs); TS splits whitespace-only (no shlex in browsers); exec policy matches EXACT argv tokens (never prefix); `sh -c` passthrough disallowed for design/sim kinds (the digest-gaming vector).
+- **G-16**: `voice_tts_format` is a `Literal["mp3","wav","opus"]` enum, not a free string — it feeds a Content-Type.
+- **G-17**: MH-4e "seq-ack intact" was hope-shaped; merged into MH-4d as concrete assertions (stored seqs contiguous 0..N exactly once; spool ≤ ack margin; or cite the P1 suite where a fake agent runs).
+- **G-18**: the marketplace gated stub proves the gate then returns 501 + `stub: true` + mock markers — never a fabricated "applied" outcome (A-304 honesty house rule).
+
+## Advisories (recorded)
+
+a-6 ack on dedup'd appends too (tight margin); a-7 MH-1d 3× runs = one-time ship validation, not per-CI; a-8 manual voice probe must be executable-by-anyone-with-keys (fixture wav + fixed phrase, falsifiable asserts); a-9 413 Content-Length fast path before buffering; a-10 ROADMAP P4 "Depends On: 4" self-typo → fix to 0; a-11 TS `TaskVariant` fields required on the wire; a-12 identity insert-only growth fine at pilot scale; a-13 `recorder.start(1000)`; a-14 do NOT build ack batching unless a flood test shows drainer stall; a-15 provider must always carry `descriptor` (missing it would badge server as mock).
+
+## Escalations
+
+None. All four seams remain founder-locked via D-016 / REQ-5-001..007; every finding resolved at confidence ≥ 0.65.
+
+---
+
+# v0.8 GRILL (Phase 0, 2026-09-27) — Ship Anywhere
+
+**Verdict: GO-WITH-BINDINGS · Confidence: 0.74** — G-201..G-210 binding (3×P0, 7×P1); applied to PLAN.md before P1 execution. (Inline orchestrator grill — three delegated griller runs returned empty; logged per Step 4 error recovery at full autonomy.)
+
+**Evidence:** every load-bearing plan claim re-verified against RESEARCH.md's probe-backed census (R-1..R-32), the existing v0.4 pipeline code (build-binary.mjs, release-assets.sh, install.sh), and Gitea 1.26.1 live state. The research layer held; findings are interaction-surface and lifecycle gaps.
+
+## Per-Axis Findings
+
+| Axis | Verdict | Rationale |
+|------|---------|-----------|
+| Goal coverage | PASS | All four founder options map to REQ-8-001..005 with falsifiable MHs; docker-per-phase-upload honored by the release workflow design. |
+| Feasibility | AT-RISK → fixed | QEMU-free arm64 SEA (R-25/26) probe-first is honest, but the plan pinned no failure exit; G-201 forces a decided fallback ladder. Runner fleet on 4GB is bounded by capacity=1 + label routing (R-4). |
+| Vertical-slice integrity | PASS | P1 ships a green fleet + live pipelines; P2 ships a pullable image; P3 ships installable assets; P4 ships channel-aware CLI; P5 ships the runbook. Each independently real. |
+| Wave ordering | AT-RISK → fixed | P2→P3 ordering claimed "forced" but both only extend P1's workflow; G-202 makes the true dependency explicit (asset-matrix ownership) and permits P2/P3 work within the same release lane without re-ordering phases. |
+| Testability | AT-RISK → fixed | MH-1d asserted workflow-built release assets but the release job runs on the tag push — which exists only at ship time; G-203 defines the within-phase proof (temporary tag on the phase branch). MH-2b smoke gate had no in-container test harness; G-204 pins the concrete assertions. |
+| Security posture | AT-RISK → fixed | Secrets chain mostly sound (R-6/R-13), but the REGISTRY_TOKEN self-serve PUT needs a value the .env token cannot mint — G-205 forces founder-side PAT creation with scoped package-write, closing a plan-time fantasy. CT root password rotation was "ask founder"; G-206 makes it a recorded P0 completion condition. |
+| Performance/capacity | PASS | Image budget ~400-500MB (R-18) asserted in smoke gate; 32GB disk bounded by prune cron + cache caps + health_check floor (R-5). |
+| Operational readiness | AT-RISK → fixed | The runbook (P5) would document a fleet whose bring-up lives only on CT 113; G-207 requires the compose/config/cron committed as fleet-as-code in-repo. Degrade remediation text must name the privileged variant precisely (G-208). |
+| Dependency risk | PASS | No new product deps; docker.io engine on release lane accepted-risk with documented future fix; corepack fallback decided (R-11). |
+| Adoption/UX | PASS | Three channels each end at doctor/verify green; guide offline-first with parity test; refusals honest. |
+
+## Binding Decisions (applied to PLAN.md)
+
+- **G-201 (P0)** — arm64 build has a decided fallback ladder: probe QEMU-free cross-arch SEA on the runner first; if the blob fails to run under emulation, fall back to binfmt+qemu for FULL arm64 builds (not just blob generation); if the runner can't install binfmt, ship v0.8 with x64-only debs/binaries and record the arm64 deferral — never leave the release lane red or blocked.
+- **G-202 (P1)** — dependency truth: P2 and P3 both consume P1's release workflow as their extension point; P2 precedes P3 for founder-priority (docker is the headline channel), not technical force. PLAN wave-order paragraph corrected; no phase reorder.
+- **G-203 (P1)** — release-workflow within-phase proof: MH-1d/D-3d prove via a temporary `v0.7.1-rc1`-style tag pushed to the phase branch head at verify time, workflow observed building + attaching to the (pre-release/draft or immediately-deleted) release, tag then deleted. The phase ship tag remains the real artifact.
+- **G-204 (P1)** — smoke gate pinned: container starts → /health 200 within timeout → `GET /` content-type text/html AND contains a known marker (not just non-JSON-404) → degrade boot notice present in logs → fabric create returns 503 with remediation → clean stop. All five assertions in the workflow step; failure = red release job.
+- **G-205 (P0)** — REGISTRY_TOKEN is a founder-minted PAT with package-write scope (the .env GITEA_TOKEN may lack it): P1's self-serve attempt becomes "PUT the secret IF the existing token can mint it — else escalate to founder with the exact scope needed (write:package + write:repository)". The plan must not assume the PUT succeeds; escalation path has a founder question, not a silent wait.
+- **G-206 (P0)** — CT 113 root password rotation is a P0 completion condition of Wave 1-1: after deploy-key install, the founder is asked to rotate; if not confirmed by Wave 1-2, an `escalation: ct_root_password_still_live` commit lands and the ship notes carry it. Never silently carried.
+- **G-207 (P1)** — fleet-as-code: the compose file, per-runner configs, and prune cron are committed in-repo (e.g. `deploy/ci/`) as the reproducible fleet definition; CT 113 deployment is a copy + `docker compose up -d` — the runbook's fleet recipe references the committed files, not box memory.
+- **G-208 (P1)** — degrade remediation text must be exact: name the unprivileged default, the seccomp constraint, the documented privileged/seccomp-override variant (docker run flags), and the host-side alternative (run the stack binary-side); the boot notice and 503 payload carry the same text (single remediation constant, tested).
+- **G-209 (P1)** — pre-commit hooks must not break contributor boxes lacking the toolchain silently in the other direction either: hooks fail-loud (D-070) but the README dev section documents the exact skip path (`pre-commit run --no-skip` semantics never needed; SKIP=env documented) — a contributor with no ruff gets a loud pointer, not a broken commit flow.
+- **G-210 (P1)** — the guide parity test (MH-5b) needs a defined source of truth: the runbook's channel sections are the canonical text; `nextcraft guide` renders them via an extracted shared snippet (single source file, generated or duplicated-with-test); divergence = test failure. PLAN Task 5-1-02 mechanism named.
+
+## Plan Edits Applied
+
+1. G-201 → Task 3-1-01 fallback ladder + MH-3a reworded (probe → binfmt-full → deferral, never red lane)
+2. G-202 → Overview wave-order paragraph corrected (P2 precedes P3 for founder priority, not technical force)
+3. G-203 → Task 1-2-02 + Task 3-2-03 verification mechanism (temporary rc tag, deleted after proof)
+4. G-204 → Task 2-2-02 five-assertion smoke gate pinned
+5. G-205 → Task 1-2-04 reworded (founder-minted PAT with package-write; escalation question not silent wait)
+6. G-206 → Task 1-1-01/1-1-03 rotation condition + ship-notes carry
+7. G-207 → new P1 Wave 1-1 task (fleet-as-code committed in deploy/ci/)
+8. G-208 → Task 2-1-02 single remediation constant, tested
+9. G-209 → Task 1-2-05 README dev-section skip path documented
+10. G-210 → Task 5-1-02 parity mechanism named (single source, divergence = test failure)
+
+## Advisories (recorded, no action)
+
+- a-201: docker.io rate limits on the release lane — bookworm main is fine; watch anonymous pull quotas on job-image pulls (runner-images:ubuntu-latest is docker.gitea.com, not docker.io).
+- a-202: `GITEA_TOKEN` naming collision (automatic job token vs repo secret of the same name) — Gitea precedent lowest-level-wins; keep the repo secret name `GITEA_TOKEN` per R-13 but document the collision in the workflow comments.
+- a-203: cache.host on CT 113 IP — if the LXC ever changes IP, cache breaks; fleet-as-code (G-207) documents the IP as a bring-up variable.
+- a-204: image `latest` tag vs immutable release tags — `latest` is convenience-only; runbook always pins the release tag.

.ciagent/PERSONAS.md

@@ -2,19 +2,18 @@
 
 ## Persona Roster
 
-> **v0.3 update (RESEARCH, lead-developer assessment):** backend-engineer territory extended to the new engine modules (telemetry/grading/variants persistence + APIs). New phase-relevant custom personas added: **sandbox-engineer** (Linux-namespace isolation infra) and **voice-engineer** (STT/TTS + Examiner agent audio pipeline). ai-engineer re-scoped to LLM/agents/prompts + grading/variant/voice *model-facing* logic. **security-auditor stays inactive** (KYC deferred per founder directive). frontend-engineer gains real-sandbox (xterm.js), live-telemetry, and live-defense surfaces.
-
+> **v0.8 update (RESEARCH, lead-developer assessment):** milestone = Ship Anywhere (Feature — release/distribution rails: runner fleet, docker image, deb/arm64 packaging, CLI onboarding glue, admin guides). **Activated:** devops-engineer (NEW custom persona — the runner fleet on CT 113, docker-compose + labels + cache hygiene, .gitea/workflows push + tag lanes, Dockerfile + registry push, pre-commit config; the whole release-consistency surface REQ-8-001/002), cli-engineer (re-activated from its v0.4/v0.4.6 territory — build-binary.mjs arch parameter + arm64 node base, install.sh arch-resolve, deb packaging scripts, doctor container/deb-channel awareness, `guide` embedded text, bootstrap/deploy/dev container refusal — REQ-8-003/004), sandbox-engineer (re-activated for the D-068 capability probe promotion into sandbox/capability.py + the 503 degrade arm in api/sandboxes.py — its unshare_backend/manager/api-surface territory), lead-developer (coordination + wave order + the P5 admin-guide assembly), security-auditor (phase-specific: release secrets handling REGISTRY_TOKEN/GITEA_TOKEN/registration token, image non-root + healthcheck, sibling-mode blast radius, deb postinst). **Deactivated:** backend-engineer (no config/api surface work beyond what sandbox-engineer owns — the D-068 wiring lives in sandbox+main.py boot notice, owned by sandbox-engineer this milestone), frontend-engineer (no web-app changes; apps/web is only a BUILD INPUT to the image), ai-engineer, data-engineer, identity-engineer, voice-engineer, design-system-engineer.
 ### lead-developer
 ```yaml
 active: true
 phase_specific: false
-reason: Coordinates task decomposition across web, AI service, engine, and sandbox territories; resolves conflicts between frontend, backend, AI, sandbox, and voice personas
+reason: Coordinates the v0.8 Ship Anywhere milestone (fleet → container → debian → onboarding → guides waves); owns the admin-guide assembly (P5) as the single cross-channel runbook; owns wave-order + the release-asset matrix consistency check (every release: x64/arm64 binaries + debs + image tag per D-064/D-065)
 domain: coordination
 frameworks:
-  - next.js
   - turborepo
   - pnpm
-  - fastapi
+  - gitea-actions
+  - docker
 constraints:
   - pragmatic
   - battle-tested defaults
@@ -22,104 +21,163 @@ constraints:
 territory:
   - "**/package.json"
   - "**/turbo.json"
-  - "**/pnpm-workspace.yaml"
-  - "**/tsconfig.json"
+  - "deploy/README.md"
+  - "README.md"
+```
+
+### devops-engineer
+```yaml
+active: true
+phase_specific: false
+reason: NEW v0.8 custom persona — owns the entire release-consistency surface: 3 org-level gitea/runner:3 containers on CT 113 (sibling mode, host docker.sock, per-runner /data, GITEA_RUNNER_LABELS, capacity 1, cache.host pinning + 32 GB prune cron — REQ-8-001), .gitea/workflows push lane (node/python lanes with the repo's own scripts, D-063 fast-only test lanes) + tag lane (exclusive release owner D-064), multi-stage Dockerfile + git.coreci.dev/coreci/nextcraft push (semver + latest per D-065 — REQ-8-002), root .pre-commit-config.yaml (D-070)
+domain: devops
+frameworks:
+  - docker
+  - docker-compose
+  - gitea-runner
+  - github-actions-syntax (gitea-compatible subset)
+  - bash
+constraints:
+  - sibling-mode-socket-trust (org-scoped private repos only; accepted-risk documented)
+  - secrets-via-actions-secrets-or-founder (registration token never in files; REGISTRY_TOKEN self-serve PUT first, founder UI fallback)
+  - job-token-cannot-publish-packages (upstream-confirmed; registry push needs the PAT secret)
+  - cache-host-pinning (dockerized runner cache server must be job-reachable or actions/cache ETIMEDOUTs)
+  - fast-lanes-only-in-ci (real_server/userns never in job containers, D-063)
+territory:
+  - ".gitea/workflows/**"
+  - "Dockerfile"
+  - ".dockerignore"
+  - ".pre-commit-config.yaml"
+  - "deploy/runner/**"          # compose + config for CT 113 (admin-guide artifacts, not CT state)
+```
+
+### cli-engineer
+```yaml
+active: true
+phase_specific: false
+reason: v0.8 re-activation — owns the distribution artifacts of its own binary: build-binary.mjs arch parameter (--arch x64|arm64; arm64 node-base download replacing process.execPath copy, postject unchanged — D-069 QEMU-free cross-build), scripts/build-deb.sh + postinst advisory doctor (D-067), install.sh arch-gate→arch-resolve (x86_64/aarch64, sha256+version gates byte-identical), doctor container/deb-channel awareness (real userns probe + NC_CONTAINER//.dockerenv//usr/bin/nextcraft detection — REQ-8-004/D-066), `nextcraft guide` offline-first embedded text (D-072), bootstrap/deploy/dev in-container refusal (D-066/D-071), verify container-mode branch
+domain: cli
+frameworks:
+  - node
+  - typescript
+  - node-sea
+  - esbuild
+  - postject
+  - dpkg-deb
+  - posix-sh
+constraints:
+  - stdlib-only-runtime
+  - thin-wrapper
+  - fail-loud-exit-codes
+  - postinst-never-fails-dpkg (advisory doctor, D-067)
+  - deb-no-systemd-unit (deploy --service owns units, D-067)
+  - guide-offline-first (zero runtime fetches, D-072)
+  - deb-version-policy (tag minus leading v)
+territory:
+  - "apps/cli/**"
+  - "scripts/install.sh"
+  - "scripts/release-assets.sh"
+  - "scripts/build-deb.sh"
+```
+
+### sandbox-engineer
+```yaml
+active: true
+phase_specific: false
+reason: v0.8 re-activation — owns the D-068 degrade detection in its sandbox fabric: promote tests/helpers/userns.py's probe into ai_service/sandbox/capability.py (verbatim semantics), the boot notice in main.py lifespan (the G-11 mount-less-warning pattern), the per-create 503 + remediation arm (SandboxUnavailableError mapping beside PoolFullError in api/sandboxes.py) — the honest container-degrade path for REQ-8-002; real_server/userns test tiers stay OUT of CI lanes per D-063
+domain: infra
+frameworks:
+  - python
+  - linux-namespaces
+  - docker (degrade semantics only — no docker backend)
+  - pytest
+constraints:
+  - capability-probe-is-truth-source (markers only flavor remediation, D-068)
+  - reject-not-fallback (unisolated learner code unacceptable in deployed schools; supersedes A-101)
+  - degrade-keeps-core-features (chat/agents/grading untouched)
+  - probe-semantics-verbatim (unshare --user --map-root-user true, 10s timeout)
+territory:
+  - "apps/ai-service/ai_service/sandbox/**"
+  - "apps/ai-service/ai_service/main.py"
+  - "apps/ai-service/ai_service/api/sandboxes.py"
+  - "apps/ai-service/tests/sandbox/**"
+  - "apps/ai-service/tests/helpers/userns.py"
+```
+
+### security-auditor
+```yaml
+active: true
+phase_specific: true
+reason: v0.8 re-activated (phase-specific) — P1 release secrets review (registration token flow, REGISTRY_TOKEN/GITEA_TOKEN Actions secrets, the .env-only resolution of release-assets.sh preserved as manual fallback), P2 image review (non-root user, healthcheck without curl, state volume ownership, sibling-mode socket blast-radius row), P3 deb review (postinst never fails dpkg, empty Depends + honest Recommends), P6 final review (channel consistency: every recipe backed by a test or live-box evidence)
+domain: security
+frameworks:
+  - pytest
+  - httpx
+constraints:
+  - STRIDE-classified
+  - secrets-never-in-workflow-env (Actions secrets only; never files)
+  - secrets-never-logged
+  - registration-token-reset-after-fleet-green (founder directive)
+  - fail-closed-degrades (unprivileged default; privileged variant documented opt-in)
+territory:
+  - ".gitea/workflows/**"
+  - "Dockerfile"
+  - "scripts/build-deb.sh"
+  - "scripts/release-assets.sh"
+  - "apps/cli/src/commands/deploy.ts"
+```
+
+### backend-engineer
+```yaml
+active: false
+phase_specific: false
+reason: v0.8 DEACTIVATED — the only backend-adjacent work (D-068 probe wiring + boot notice) is owned by sandbox-engineer whose fabric it extends; config.py/pyproject need zero changes (NC_CONTAINER is a CLI-layer marker; the AI_* env surface is untouched). Roster retained; the v0.7 pytest/mypy territory is stable.
+domain: backend
+frameworks:
+  - fastapi
+  - pydantic-settings
+  - bash
+  - turborepo
+  - pnpm
+constraints:
+  - secrets-via-env-only (D-014)
+  - idempotent-scripts
+  - fail-closed-admin
+territory:
+  - "apps/ai-service/ai_service/config.py"
+  - "apps/ai-service/ai_service/main.py"
+  - "apps/ai-service/ai_service/api/**"
+  - "apps/ai-service/scripts/**"
+  - "apps/ai-service/.env.example"
   - "apps/ai-service/pyproject.toml"
+  - "package.json"
+  - "turbo.json"
 ```
 
 ### frontend-engineer
 ```yaml
-active: true
+active: false
 phase_specific: false
-reason: Phase 6 real-engine learner-surface integration — xterm.js in-browser terminal, file-tree/run/test controls, live telemetry panels, live voice defense UI, live grading display. Owns all page components, layouts, surface-specific UI.
+reason: v0.8 DEACTIVATED — no apps/web changes; the web app is only a BUILD INPUT to the docker image (NEXT_PUBLIC_AI_SERVICE_URL=self export, unchanged since D-039). ESLint/c8/pins territory stable from v0.7.
 domain: frontend
 frameworks:
   - react
   - next.js
   - tailwindcss
-  - lucide-react
-  - recharts
-  - react-flow
-  - "@xterm/xterm"
-  - "@xterm/addon-fit"
 constraints:
   - component-first
   - server-components-default
-  - minimal-client-js
-  - sse-client-buffering (buffer bytes, split frames on \n\n, join data: lines)
-  - abortcontroller-cleanup (idempotent abort in effect cleanup)
-  - websocket-lifecycle (typed messages, reconnect backoff, cleanup)
-  - mediarecorder-permission-ux (mic consent, graceful no-mic fallback)
-  - responsive-all-breakpoints
-  - dark-mode-support
+  - no-build-time-db-reads (D-039 export build stays repo-only)
 territory:
   - "apps/web/**"
   - "packages/ui/**"
-  - "packages/mock-data/**"
-  - "packages/types/**"
-```
-
-### data-engineer
-```yaml
-active: true
-phase_specific: false
-reason: Owns TS mock data layer schema and typed definitions + TS types for telemetry/trace/grade/variant/defense shapes the web surfaces consume. Does NOT own the Python corpus or engine stores — aligned by convention (D-021).
-domain: data
-frameworks:
-  - typescript
-constraints:
-  - schema-first
-  - type-safe
-  - migration-ready
-  - mock-data-only
-territory:
-  - "packages/types/**"
-  - "packages/mock-data/**"
-```
-
-### backend-engineer
-```yaml
-active: true
-phase_specific: false
-reason: Owns apps/ai-service app shell, config, API endpoints (incl. WebSocket telemetry ingest), engine persistence (SQLite stores), scripts, and test harness. Extended for v0.3 engine modules.
-domain: backend
-frameworks:
-  - fastapi
-  - uvicorn
-  - pydantic
-  - pydantic-settings
-  - httpx
-  - pytest
-  - sqlmodel
-  - sqlalchemy
-  - websockets
-  - aiofiles
-constraints:
-  - provider-agnostic-boundaries (engine modules import nothing from agents/ or api/)
-  - streaming-first
-  - sqlite-first-persistence (protocol-wrapped stores, Postgres-ready, D-027)
-  - secrets-via-env-only
-  - mock-provider-in-tests
-  - websocket-contract (typed envelopes, seq gap detection, D-026)
-territory:
-  - "apps/ai-service/ai_service/main.py"
-  - "apps/ai-service/ai_service/config.py"
-  - "apps/ai-service/ai_service/api/**"
-  - "apps/ai-service/ai_service/telemetry/store.py"
-  - "apps/ai-service/ai_service/telemetry/ingest.py"
-  - "apps/ai-service/ai_service/grading/store.py"
-  - "apps/ai-service/ai_service/variants/store.py"
-  - "apps/ai-service/scripts/**"
-  - "apps/ai-service/package.json"
-  - "apps/ai-service/tests/api/**"
-  - "turbo.json"
 ```
 
 ### ai-engineer
 ```yaml
-active: true
+active: false
 phase_specific: false
-reason: Owns the LLM provider layer, agent framework, prompt library, structured outputs, and the model-facing logic of v0.3 engines — trace-digest→rubric grading prompts (grading/features.py+engine.py), variant instantiation (variants/templates.py+generator.py), and the Examiner agent. Owns the deterministic-mock corpora.
+reason: v0.8 DEACTIVATED — no LLM-facing work; the provider layers ship unchanged inside the docker image (G-11 fallbacks are the only runtime-config behavior).
 domain: ai
 frameworks:
   - pydantic
@@ -127,116 +185,108 @@ frameworks:
   - pytest
 constraints:
   - provider-agnostic-protocol
-  - prompts-are-code
-  - json-defensive-parsing
   - never-call-cloud-in-tests
-  - delta-passthrough
-  - llm-sees-digest-not-raw-trace (D-028)
-  - seeded-variant-reproducibility (D-029)
+  - mock-first
 territory:
   - "apps/ai-service/ai_service/llm/**"
   - "apps/ai-service/ai_service/agents/**"
+  - "apps/ai-service/ai_service/marketplace/**"
   - "apps/ai-service/ai_service/prompts/**"
-  - "apps/ai-service/ai_service/corpus/**"
-  - "apps/ai-service/ai_service/grading/features.py"
-  - "apps/ai-service/ai_service/grading/engine.py"
-  - "apps/ai-service/ai_service/variants/templates.py"
-  - "apps/ai-service/ai_service/variants/generator.py"
-  - "apps/ai-service/tests/llm/**"
-  - "apps/ai-service/tests/agents/**"
 ```
 
-### sandbox-engineer
+### data-engineer
 ```yaml
-active: true
-phase_specific: true
-reason: v0.3 custom persona (RESEARCH) — owns the sandbox fabric: SandboxBackend protocol, unshare-based Linux user/mount/pid/net namespace spawner, per-sandbox workdir, resource limits, lifecycle manager, concurrency guard, and the in-sandbox capture agent. Probe-verified isolation on this box (D-024).
-domain: infra
+active: false
+phase_specific: false
+reason: v0.8 DEACTIVATED — zero schema/store changes; the ~/.nextcraft/data/nextcraft.db path rides into the docker volume via config.py's existing home-dir default (no code change).
+domain: data
 frameworks:
-  - python
-  - linux-namespaces
-  - asyncio
+  - sqlmodel
+  - pydantic
+  - typescript
+constraints:
+  - schema-first
+  - type-safe
+  - dual-schema-sync
+territory:
+  - "apps/ai-service/ai_service/marketplace/base.py"
+  - "apps/ai-service/ai_service/marketplace/store.py"
+  - "apps/ai-service/ai_service/marketplace/ingest.py"
+  - "packages/types/**"
+  - "packages/mock-data/**"
+```
+
+### identity-engineer
+```yaml
+active: false
+phase_specific: false
+reason: v0.5 custom persona — module shipped complete; no v0.8 identity-domain work.
+domain: identity
+frameworks:
+  - fastapi
+  - sqlmodel
   - pytest
 constraints:
-  - isolation-verified (probe must show in-ns uid=0, network isolated, writes to workdir only)
-  - backend-protocol-swap (no containerd assumption; D-024)
-  - resource-limits-enforced (cpu/mem/time quotas observable)
-  - no-daemon (subprocess-only; no docker/containerd service)
-  - capacity-guard (1-5 concurrent; 503 when full, D-032)
+  - pii-never-stored-raw
+  - pii-never-logged
+  - gate-composition-order
 territory:
-  - "apps/ai-service/ai_service/sandbox/**"
-  - "apps/ai-service/scripts/sandbox-agent.py"
-  - "apps/ai-service/tests/sandbox/**"
+  - "apps/ai-service/ai_service/identity/**"
+  - "apps/ai-service/tests/identity/**"
 ```
 
 ### voice-engineer
 ```yaml
-active: true
-phase_specific: true
-reason: v0.3 custom persona (RESEARCH) — owns the voice layer: VoiceProvider protocol, STT/TTS against a compatible endpoint, deterministic mock (tests never call a voice API), browser-native fallback, and the media-path wiring consumed by the Examiner agent and assessment UI.
+active: false
+phase_specific: false
+reason: v0.5 territory — voice shipped complete; no v0.8 voice work.
 domain: ai-media
 frameworks:
-  - pydantic
   - httpx
+  - fastapi
   - pytest
-  - web-mediarecorder
+  - react
 constraints:
-  - provider-agnostic-protocol (D-030)
-  - never-call-voice-api-in-tests
-  - browser-native-fallback (no-key path still functions)
-  - bounded-turn-latency (conversational feel budget)
+  - provider-agnostic-protocol
+  - never-call-cloud-in-tests
+  - key-redaction
 territory:
   - "apps/ai-service/ai_service/voice/**"
   - "apps/ai-service/tests/voice/**"
+  - "apps/web/components/learner/defense-session.tsx"
 ```
 
 ### design-system-engineer
 ```yaml
-active: true
+active: false
 phase_specific: false
-reason: Owns the shared component library, design tokens, and visual consistency. v0.3 duty: new primitives for the real build/assessment surfaces (terminal frame, telemetry status indicator, mic/record control, grade badge, defense transcript viewer).
+reason: No design-token or primitive work in v0.8; roster retained.
 domain: frontend
 frameworks:
   - tailwindcss
   - storybook
-  - lucide-react
 constraints:
   - design-token-driven
   - wcag-aa-contrast
-  - dark-mode-required
-  - consistent-across-surfaces
 territory:
   - "packages/ui/**"
 ```
 
-### security-auditor
-```yaml
-active: false
-phase_specific: false
-reason: Identity/age-gating (KYC) deferred beyond v0.3 per founder directive (A-110) — no real auth or PII backend lands this milestone. Security coverage remains: verifier's STRIDE layer + Phase 7 secrets-hygiene checklist (keys absent from code/logs/commits/errors, localhost-only CORS, no PII in prompts). Sandbox isolation safety is owned by sandbox-engineer's probe-verified constraint.
-domain: security
-frameworks: []
-constraints: []
-territory: []
-```
-
 ## Phase-Specific Personas
 
 | Persona | Phases | Removed After |
 |---------|--------|---------------|
-| sandbox-engineer | 1 (primary), 2, 6 | persists while sandbox fabric exists |
-| voice-engineer | 5 (primary), 6 | persists while voice defense exists |
+| security-auditor | 1 (runner + secrets), 2 (image non-root/volumes), 3 (deb postinst), 6 (final channel-consistency review) | milestone complete |
 
-All other active personas span the entire milestone. data-engineer and design-system-engineer are light-touch outside their phases.
+All other personas span the milestone. Deactivated personas receive no tasks.
 
 ## Territory Conflict Resolution
 
 | Conflict | Resolution |
 |----------|------------|
-| frontend-engineer vs data-engineer (packages/types, packages/mock-data) | data-engineer owns type definitions and mock data schema (incl. new telemetry/grade/variant/defense TS types); frontend-engineer consumes them. |
-| frontend-engineer vs design-system-engineer (packages/ui) | design-system-engineer owns design tokens and primitive components (terminal frame, mic control, grade badge); frontend-engineer owns composite components and page-level UI. |
-| ai-engineer vs backend-engineer (grading/variants) | ai-engineer owns the model-facing files (features/engine/templates/generator = LLM logic + prompts); backend-engineer owns the persistence stores + API endpoints. Boundary: stores are pure SQLite; engine logic is pure compute. |
-| sandbox-engineer vs backend-engineer (sandbox/) | sandbox-engineer owns `ai_service/sandbox/**` + capture agent; backend-engineer owns the API route that composes `sandbox/manager.py` via DI. manager.py has a narrow typed interface consumed by api/. |
-| voice-engineer vs ai-engineer (Examiner agent) | ai-engineer owns `agents/examiner.py` + its prompt; voice-engineer owns `voice/**` (audio in/out). Examiner calls `voice/` through the `VoiceProvider` protocol — never imports concrete providers. |
-| ai-engineer vs data-engineer (mock duplication) | ai-engineer owns `ai_service/corpus/` (Python); data-engineer owns `packages/mock-data` (TS). Shared IDs/shapes aligned by convention (D-021). |
-| lead-developer vs any | lead-developer coordinates only, does not directly modify code files. |
+| devops-engineer vs cli-engineer (build-binary.mjs invocation) | devops-engineer owns the WORKFLOW steps that invoke `pnpm --filter @nextcraft/cli build:binary`; cli-engineer owns the SCRIPT itself (arch parameter, arm64 base, sidecars) — the workflow never patches build scripts |
+| devops-engineer vs sandbox-engineer (D-068 in Dockerfile) | devops-engineer owns the Dockerfile layers (base, user, healthcheck, volume); sandbox-engineer owns the runtime capability probe + degrade semantics the image merely runs; NC_CONTAINER marker name is a shared contract (devops sets it in the entrypoint, cli-engineer + sandbox-engineer read it) |
+| cli-engineer vs devops-engineer (doctor container facts) | cli-engineer owns doctor/verify/guide implementations; devops-engineer supplies the documented facts (volume path, privileged variant recipe) via deploy/README.md |
+| sandbox-engineer vs backend-engineer (main.py boot notice) | sandbox-engineer owns the D-068 boot notice + api/sandboxes.py degrade arm this milestone; backend-engineer is deactivated but its config.py territory is NOT modified (NC_CONTAINER lives in the CLI layer, not Settings) |
+| cli-engineer vs security-auditor (postinst/secrets) | cli-engineer implements; security-auditor reviews fail-never-postinst + token resolution and may patch security defects directly in scripts/build-deb.sh + release-assets.sh (its territory) |
+| lead-developer vs any | lead-developer coordinates only, does not directly modify code files |

.ciagent/PLAN.md

@@ -1,438 +1,239 @@
-# Nextcraft v0.3 — PLAN.md
+# Nextcraft — PLAN.md (v0.8 Ship Anywhere)
 
 ## Overview
 
-This plan covers execution phases 1-6 of milestone v0.3 (Credential Engines): the real engines that replace v0.2's mock inputs — a namespace-isolated sandbox fabric, live build telemetry over WebSocket + SQLite, a process-trace grading engine, seeded per-learner variant task generation, and an oral/voice defense with a seventh Examiner agent — plus re-grounding the Lab/Assessor/Proctor agents onto real engine inputs and wiring the v0.1 learner surfaces to the real build/defense/grading paths. Phases are strictly sequential (P1→P6); within each phase, Wave 1 tasks are parallelizable (no cross-file dependencies) and later waves depend on earlier ones.
+**Milestone:** v0.8 — Ship Anywhere (Feature): nextcraft installable on any Debian-based Linux server via every mainstream channel — docker image from the Gitea registry, .deb packages, one-liner binary (x64 + arm64) — with release consistency enforced by pre-commit hooks + Gitea Actions pipelines, and the CLI carrying the full suite for zero → running onboarding. Admin guides document all of it.
+**Tag line:** phase tags advance the v0.7.x line (P0 → v0.7.0 … P6 → v0.7.6 = milestone release), continuing from the v0.6.6 milestone release
+**Branch:** milestone/v0.8-ship-anywhere
 
-**Environment facts (apply throughout):** Python 3.11.2 via `python3 -m venv` (no uv, no system pip); pnpm 12.3.4 via corepack; turborepo; ai-service port **8420**; default model `gemma4:31b` (config via `AI_TUTOR_MODEL`); ollama-cloud base `https://ollama.com/v1` (OpenAI-compatible, Bearer auth); keys live only in gitignored `.ciagent/.env.secrets` (exported by `scripts/dev.sh`) — never in code, commits, or logs; all automated tests use the deterministic mock LLM and mock voice providers and **never call cloud or voice APIs**. New ai-service deps this milestone: `sqlmodel`, `sqlalchemy`, `websockets`, `aiofiles` (all PyPI-verified; added in Task 1-1-02). SQLite data (`apps/ai-service/ai_service/data/`) and sandbox dirs (`apps/ai-service/sandboxes/`) are already gitignored. **KYC/age-gating is deferred per founder directive (A-110)** — no identity work; age-gating stays the v0.1 visual flow mockup. **GRILL scope decisions (this revision):** real server STT/TTS (`OpenAIAudioProvider`) deferred to v0.4 — voice defense is mock+browser-first (CUT-1/G-7); the interactive xterm.js shell relay is deferred to v0.4 — the build panel is run/test-buttons + read-only exec output (CUT-2/G-8), so `@xterm/*` is NOT a v0.3 dependency; sandbox abuse control (per-learner caps + allowlist, G-5) ships even though KYC is deferred; sandbox resource limits are partially enforced (memory/CPU/wall-clock + workdir-size sweep; per-sandbox pids and hard disk quota are accepted gaps, G-1/G-2).
+**Phase list (requirement mapping):**
 
-| Phase | Name | Requirements | Waves | Personas |
-|-------|------|-------------|-------|----------|
-| 1 | Sandbox fabric | REQ-3-001, 002 | 3 | sandbox-engineer, backend-engineer, ai-engineer (W1 lint only) |
-| 2 | Live build telemetry | REQ-3-003 | 4 | sandbox-engineer, backend-engineer, data-engineer |
-| 3 | Process-trace grading engine | REQ-3-004 | 3 | ai-engineer, backend-engineer |
-| 4 | Variant task generation | REQ-3-005 | 3 | ai-engineer, backend-engineer, data-engineer |
-| 5 | Oral / voice defense | REQ-3-006 | 4 | voice-engineer, ai-engineer, backend-engineer |
-| 6 | Agent re-grounding + learner surface integration | REQ-3-007, 008 | 5 | ai-engineer, frontend-engineer, design-system-engineer, data-engineer, backend-engineer, lead-developer |
+| Phase | Requirement | Focus |
+|-------|-------------|-------|
+| P1 | REQ-8-001 | Release-consistency rails: runner fleet on CT 113, push/tag workflows, pre-commit, hello-world verification |
+| P2 | REQ-8-002 | Docker image: multi-stage build, unprivileged runtime + honest sandbox degrade, registry push on every release |
+| P3 | REQ-8-003 | Debian-native: arm64 cross-build, .deb packages (x64+arm64), install.sh arch-resolve, release assets extended |
+| P4 | REQ-8-004 | CLI onboarding: doctor channel awareness, `nextcraft guide`, in-container refusals, per-channel E2E |
+| P5 | REQ-8-005 | Admin guides: the full deploy runbook (three channels × install/upgrade), README quickstart |
+| P6 | — | Final review + audit + milestone ship (v0.7.6 = milestone release) |
+
+**Wave order (binding): rails before artifacts before onboarding before guides.** P1 builds the rails everything else ships through — P2/P3 extend the release workflow P1 creates; P4 onboarding needs all artifact channels to exist; P5 guides document the final shape. Within P1, the runner fleet gates the workflow verification (workflows are inert config until a runner registers). P2 precedes P3 for founder priority (docker is the headline channel), not technical force — both consume P1's release workflow as their extension point (G-202).
+
+**Research decisions R-1..R-32 (RESEARCH.md) and clarify decisions D-063..D-072 (PROJECT.md) are binding design contracts.** This plan operationalizes them; it does not re-litigate them.
+
+**Environment facts (probe-verified):** Gitea 1.26.1 at git.coreci.dev; OCI registry `/v2/` live (401 unauth); Actions enabled, zero runs to date; CT 113 gitea-runner LXC (10.0.0.113, 4c/4GB/32GB, root SSH, founder-provided credentials — never committed); registration token founder-provided in chat, reset after fleet green; latest release v0.6.6 (id 909) carries nextcraft-linux-x64 + .sha256; runner image is `docker.io/gitea/runner:3` (act_runner renamed, R-1); jobs run as siblings via host docker.sock; v0.7 toolchain (eslint flat config, ruff + RUF100, mypy relaxed-first, pytest markers fast/real_server/userns with `ai:test:fast`, c8, turbo pipeline) is the CI surface.
+
+**Secrets policy (binding, v1.8 lesson):** tokens never in shell env, never committed, never echoed. Registration token = compose env at bring-up only (R-6). REGISTRY_TOKEN = Gitea Actions secret (self-serve `PUT /repos/coreci/nextcraft/actions/secrets/REGISTRY_TOKEN` attempt with the `.ciagent/.env.secrets` GITEA_TOKEN first; founder UI fallback — R-13). The automatic job `GITEA_TOKEN` cannot publish packages (R-13, upstream-confirmed). CT 113 root credentials: use once at P1 bring-up, install repo-owned access thereafter, founder rotates the password.
+
+**NFR note:** this is a Feature milestone — no purity gate; `feat:` commits are expected and scoped to the four channels + guides.
 
 ---
 
-## Phase 1: Sandbox Fabric
+## Phase 1: Release-Consistency Rails (REQ-8-001)
 
-**Requirements:** REQ-3-001, REQ-3-002
-**Goal:** `SandboxBackend` protocol + `unshare`-based namespace spawner (D-024) + lifecycle manager with concurrency guard (D-032) + per-sandbox workdir; isolation and resources probe-verified on this box; `/v1/sandboxes` API live; deps + gitignore landed
+**Goal:** Three org-level runner containers green on CT 113; push-lane workflows (node/python lanes per D-063) and a tag-triggered release workflow live; pre-commit hooks enforce local hygiene; the fleet proven by hello-world dispatch across all three labels.
 
-### Wave 1: Foundations (parallel — no shared files)
+### Wave 1-1: Runner fleet bring-up on CT 113 (devops-engineer)
 
-#### Task 1-1-01: SandboxBackend protocol + unshare spawner + probe test
-- **Persona:** sandbox-engineer — **REQ:** REQ-3-001, REQ-3-002
-- **Files:** `apps/ai-service/ai_service/sandbox/__init__.py`, `apps/ai-service/ai_service/sandbox/backend.py`, `apps/ai-service/ai_service/sandbox/workdir.py`, `apps/ai-service/ai_service/sandbox/unshare_backend.py`, `apps/ai-service/tests/sandbox/__init__.py`, `apps/ai-service/tests/sandbox/test_isolation.py`
-- **Action:** `backend.py`: `SandboxBackend` protocol + `SandboxSpec` (sandbox_id, learner_id, workdir, resource limits) + `SandboxHandle` (id, pid, workdir, created_at); `spawn(spec)`, `exec(handle, cmd)`, `snapshot(handle) -> Path`, `destroy(handle)`. `workdir.py`: per-sandbox layout under `apps/ai-service/sandboxes/<id>/` (workspace/ writable, snapshot() = recursive copy to `snapshots/<ts>/`) — no symlinks as the snapshot mechanism. `unshare_backend.py`: subprocess spawner — `unshare --user --map-root-user --mount --pid --fork --net` with the per-sandbox dir bind-mounted (`--bind <dir> /work`) and `chdir /work` (D-024); pipes for stdout/stderr; async wrappers. `test_isolation.py` — **re-verify box isolation properties (runs on this box, guarded by probe skip):** (a) `id -u` inside namespace prints `0`; (b) `ip link` inside namespace shows 0 usable interfaces (loopback-only/no carrier) — network isolated; (c) file written to `/work/inside.txt` lands at `sandboxes/<id>/workspace/inside.txt` on the host; (d) attempt to write outside the mount (e.g. host tmp path via bind) does not escape the per-sandbox dir; (e) `/proc` visibility degraded (proc-remount not permitted per A-101 — assert the probe documents this, not that it fails).
-- **Verify:** `pnpm ai:test` — `tests/sandbox/test_isolation.py` green on this box (probe-gated: skips with an explicit reason if userns unavailable); `lint` clean
+- **Task 1-1-01** (devops-engineer): CT 113 bring-up probes — SSH to root@10.0.0.113 (founder creds, use once), verify docker daemon (`docker info`), LXC nesting health (cgroup/ns errors), egress (`curl -fsSL https://git.coreci.dev/api/v1/version` → 200; docker.io reachability for `gitea/runner:3` + job images; github.com reachability for actions/checkout per R-8 — record verdict, it selects the checkout strategy). Install an ed25519 deploy key for subsequent phases; founder rotates root password after this task — **rotation is a Wave 1-1 completion condition (G-206): if unconfirmed by Wave 1-2, commit `escalation: ct_root_password_still_live` and carry it in the ship notes — never silently.**
+- **Task 1-1-01b** (devops-engineer): **Fleet-as-code (G-207)** — the compose file, per-runner config.yaml snippets, and the prune cron land in-repo under `deploy/ci/` (compose with `${REGISTRATION_TOKEN}` env interpolation, configs with `${CT_IP}` documented as bring-up variables); CT 113 deployment = copy + `docker compose up -d`. The runbook's fleet recipe references these committed files, never box memory.
+- **Task 1-1-02** (devops-engineer): Fleet deployment per R-1..R-5 — `/srv/nc-ci/docker-compose.yaml` with three services (nc-runner-node / nc-runner-python / nc-runner-release), image `docker.io/gitea/runner:3`, per-runner `./data-runner-*` volumes (never shared — lock refusal), host `/var/run/docker.sock` mount, `GITEA_INSTANCE_URL=https://git.coreci.dev`, `GITEA_RUNNER_NAME`, `GITEA_RUNNER_LABELS` per the R-3 hybrid map (node → node:24-bookworm; python → python:3.11-bookworm; release → node:24-bookworm; ubuntu-latest → docker.gitea.com/runner-images:ubuntu-latest, carried by runner-node), registration token via compose env (from founder chat, never a file). Per-runner config.yaml with `capacity: 1`, `cache.enabled/host: 10.0.0.113/port` published per runner (R-5 — else actions/cache ETIMEDOUTs), `health_check.min_free_disk_space_mb: 4096`. systemd unit for the compose stack (`restart: always`, reboot-persistent — house pattern).
+- **Task 1-1-03** (devops-engineer): Fleet verification — all three runners visible + idle at org level (`/org/coreci/settings/actions/runners`); registration token reset by founder after this task (ask; do not hold the pipeline — the token's job is done once three `.runner` files exist); host-side cache-hygiene cron (daily `docker system prune -af --filter until=168h` + `docker volume prune -f`).
 
-#### Task 1-1-02: v0.3 dependencies + gitignore + config additions
-- **Persona:** backend-engineer — **REQ:** REQ-3-001
-- **Files:** `apps/ai-service/pyproject.toml` (update), `apps/ai-service/ai_service/config.py` (update), `apps/ai-service/.env.example` (update), `apps/ai-service/scripts/bootstrap.sh` (update if needed), root `package.json` (no change), `turbo.json` (no change)
-- **Action:** Add pinned deps: `sqlmodel`, `sqlalchemy`, `websockets`, `aiofiles` to pyproject. `config.py` additions (env_prefix `AI_`): `AI_SANDBOX_DIR` (default `apps/ai-service/sandboxes`), `AI_SANDBOX_MAX_CONCURRENT` (default 5, D-032), `AI_SANDBOX_CPU_LIMIT` (default 1 core / cpu.max), `AI_SANDBOX_MEM_LIMIT_MB` (default 512), `AI_SANDBOX_PIDS_LIMIT` (default 256), `AI_SANDBOX_TIMEOUT_S` (default 1800), `AI_DB_PATH` (default `ai_service/data/nextcraft.db`), `AI_VOICE_BASE_URL` / `AI_VOICE_API_KEY` / `AI_VOICE_STT_MODEL` / `AI_VOICE_TTS_MODEL` (all **optional**, default empty — mock-first, D-030; documented in `.env.example` and README). Confirm `.gitignore` already covers `ai_service/data/` + `sandboxes/` (it does — v0.3 block present). Re-run bootstrap idempotently to install new deps.
-- **Verify:** `pnpm ai:bootstrap` re-installs cleanly (no-op venv, new wheels land); `python -c "import sqlmodel, sqlalchemy, websockets, aiofiles"` succeeds in the venv; settings parse with new keys unset
+### Wave 1-2: Workflows + secrets + hello-world (devops-engineer)
 
-#### Task 1-1-03: Resource-limit probe documentation + harness ruff pass
-- **Persona:** ai-engineer — **REQ:** REQ-3-001
-- **Files:** `apps/ai-service/README.md` (update: sandbox section + probe transcript), `apps/ai-service/pyproject.toml` (no change), `apps/ai-service/tests/sandbox/test_isolation.py` (no change)
-- **Action:** Record the A-101 probe transcript in README (verbatim commands + observed output from this box: `unshare --user --map-root-user --mount --pid --fork --net id -u` → `0`; `ip link` → loopback only; write containment). Document the v0.3 resource-limit mechanism choice: cgroup-v2 delegation via per-sandbox scope files is **not available** on this box without sudo → enforcement = subprocess-level (`ulimit`-equivalent via `preexec_fn`: RLIMIT_AS for memory, RLIMIT_CPU for CPU-seconds, RLIMIT_NPROC for pids) + hard wall-clock timeout kill in the manager. This is the locked v0.3 mechanism (D-024 + no-sudo constraint). Run ruff over the new tree; fix all findings.
-- **Verify:** `pnpm ai:lint` exits 0; README shows the probe transcript and the rlimit mechanism note
+- **Task 1-2-01** (devops-engineer): `.gitea/workflows/ci.yaml` — `on: push` (all branches), two jobs: node lane (`runs-on: node`: corepack pnpm 12.3.4 — probe corepack-on-node24, `npm i -g pnpm@12.3.4` fallback per R-11 — `pnpm install --frozen-lockfile`, lint + typecheck via `pnpm --filter` over the 5 TS workspaces (never wholesale `turbo lint` per R-8), `pnpm web:test`, `pnpm cli:test` with E2E env-gated out per D-063) and python lane (`runs-on: python`: bootstrap.sh → lint.sh → typecheck.sh → `FAST=1 test.sh`). checkout via `actions/checkout@v4` if Task 1-1-01 found github.com egress; else raw `git fetch` steps with the job token (R-8). pnpm store + pip cache via `actions/cache@v4` (R-12; volume-mount fallback if cache server unreachable).
+- **Task 1-2-02** (devops-engineer): `.gitea/workflows/release.yaml` — `on: push: tags: ['v*']`, `runs-on: release`: build the x64 SEA binary stamped `${{ gitea.ref_name }}` (`pnpm --filter @nextcraft/cli build:binary $TAG`), sha256 sidecar, attach both to the tag's release via the REST API (`scripts/release-assets.sh` mechanics per R-14 — call the API directly in the workflow step; the script itself stays untouched as the manual fallback with its .env-only resolution, per D-064/R-14). **Within-phase proof (G-203):** at verify time push a temporary `v0.7.1-rc1`-style tag to the phase-branch head, observe the workflow build + attach green (draft/pre-release or immediately-deleted release), then delete the tag — the phase ship tag remains the real artifact.
+- **Task 1-2-03** (devops-engineer): `.gitea/workflows/hello.yaml` — `workflow_dispatch` one-step echo job × 3 (`runs-on: node|python|ubuntu-latest`) — the REQ-8-001 fleet proof. Dispatch all three, observe green in the Actions tab.
+- **Task 1-2-04** (devops-engineer): REGISTRY_TOKEN setup per G-205 — the secret is a **founder-minted PAT with package-write scope** (write:package + write:repository); first attempt the self-serve PUT (`PUT /repos/coreci/nextcraft/actions/secrets/REGISTRY_TOKEN` with the `.ciagent/.env.secrets` token, R-13); if the token's scope cannot mint it, escalate to the founder with the exact scope needed — a founder question, never a silent wait. P2's registry push blocks on this secret existing; P1 does not.
+- **Task 1-2-05** (devops-engineer): `.pre-commit-config.yaml` at repo root (D-070): directory-scoped hooks — ruff (ai-service globs), eslint flat-config run (web/cli/packages globs), tsc `--noEmit` per TS workspace, basic hygiene (trailing whitespace, merge conflicts, large files). Local-only, no network, fail-loud on missing toolchain (per D-070 — CI backstops). Document the opt-in install AND the no-toolbox skip path in the README dev section (G-209 — a contributor without ruff gets a loud pointer, not a broken commit flow).
 
-### Wave 2: Lifecycle manager (depends on Wave 1)
+### Wave 1-3: P1 verification (lead-developer + security-auditor)
 
-#### Task 1-2-01: Sandbox manager + concurrency guard + snapshots
-- **Persona:** sandbox-engineer — **REQ:** REQ-3-001, REQ-3-002
-- **Files:** `apps/ai-service/ai_service/sandbox/manager.py`, `apps/ai-service/tests/sandbox/test_manager.py`
-- **Action:** `SandboxManager`: `create(learner_id) -> SandboxHandle` (guard: active count ≥ `AI_SANDBOX_MAX_CONCURRENT` → raise `PoolFullError` → API maps to **503**, D-032; no queue); `list() -> list[SandboxHandle]`; `get(id)`; `snapshot(id) -> Path` (delegates to workdir); `destroy(id)` (kill process tree, keep or purge workdir per flag); `reap_expired()` background hook for `AI_SANDBOX_TIMEOUT_S` which also performs a **workdir-size sweep**: any sandbox whose `workdir` exceeds `AI_SANDBOX_MAX_WORKDIR_MB` (new config, default 512) is snapshotted-then-destroyed and the event logged as an integrity signal (G-2 — soft disk cap, best-effort, not kernel-enforced); the sweep runs on the same timer as the timeout reaper. Enforce rlimits per spawner (Task 1-1-03: RLIMIT_AS + RLIMIT_CPU + RLIMIT_FSIZE=50MB as a cheap single-file disk guard (a-2); RLIMIT_NPROC noted as shared-per-host-uid, not relied on (G-1)) at exec time. Handle registry persisted **in-memory** (v0.3, single process; not a store — see D-019 precedent) with a clear note that handles are process-local. Startup reaper (a-1): on lifespan boot, scan `AI_SANDBOX_DIR` for workdirs whose recorded pid is dead and reap them, logging a warning. Narrow typed interface only — manager never imports api/ (boundary rule).
-- **Verify:** `pnpm ai:test` — test_manager covers create/list/destroy/snapshot, 6th create raises PoolFullError (503 path), destroy kills the namespace process (pid gone), snapshot dir exists with workspace contents, timeout reaper removes a stale handle
+- **Task 1-3-01** (security-auditor): Secrets audit of P1 — no token/credential in any committed file (compose, workflows, pre-commit, docs); registration token lifecycle honored (brought up via env, reset requested); CT root password absent from repo + rotated by founder; workflow env scrubbed (no `GITEA_TOKEN` echo steps).
+- **Task 1-2-05 → verification hook** (lead-developer): push-lane proof — a deliberate commit touching both lanes lands green runs in the Actions tab; hello-world dispatch green × 3 labels; pre-commit blocks a deliberately broken lint file and passes a clean tree (both directions proven locally).
 
-#### Task 1-2-02: Resource-limit enforcement test
-- **Persona:** sandbox-engineer — **REQ:** REQ-3-002
-- **Files:** `apps/ai-service/tests/sandbox/test_resource_limits.py`
-- **Action:** Concrete enforcement probes (guarded like isolation tests): (a) spawn a process that allocates > `RLIMIT_AS` → assert it dies with MemoryError/killed within a bound; (b) spawn a CPU spinner past `RLIMIT_CPU` → assert SIGXCPU/kill; (c) single huge file > `RLIMIT_FSIZE` → assert write failure (a-2 partial disk guard); (d) wall-clock: spawn `sleep 9999` with a small manager timeout → reaper destroys it; (e) **disk sweep (G-2)**: write > `AI_SANDBOX_MAX_WORKDIR_MB` across many files → assert the manager sweep destroys the sandbox and logs the integrity signal. Assert limits are observable (handle reports its limit set). NOTE (G-1): per-sandbox `RLIMIT_NPROC` is shared at the host uid — the fork-bomb probe is documented as shared-budget behavior, NOT asserted as per-sandbox isolation.
-- **Verify:** `pnpm ai:test` — test_resource_limits green; limits proven enforced and observable
-
-### Wave 3: API exposure (depends on Wave 2)
-
-#### Task 1-3-01: Sandboxes API module
-- **Persona:** backend-engineer — **REQ:** REQ-3-001, REQ-3-002
-- **Files:** `apps/ai-service/ai_service/api/sandboxes.py`, `apps/ai-service/ai_service/main.py` (update: include router + lifespan manager), `apps/ai-service/ai_service/api/deps.py` (update), `apps/ai-service/tests/api/test_sandboxes.py`
-- **Action:** DI exposes a singleton `SandboxManager`. Endpoints: `POST /v1/sandboxes {learner_id}` → 201 handle (503 when pool full); `GET /v1/sandboxes` → list; `GET /v1/sandboxes/{id}` → handle; `POST /v1/sandboxes/{id}/snapshot` → snapshot path; `DELETE /v1/sandboxes/{id}` → 204. All behind localhost CORS (A-008). Lifespan creates/destroys the manager; on shutdown destroys any live sandboxes (no orphans). **Abuse control (G-5, NOT KYC):** even in no-auth v0.3 the sandbox API enforces per-`learner_id` rate limiting (`AI_SANDBOX_MAX_PER_LEARNER`, default 1 active → 429) and a global create-rate cap (`AI_SANDBOX_CREATES_PER_MIN`, default 10 → 429); `learner_id` is validated against a server-side allowlist from config (`AI_LEARNER_ALLOWLIST`, default the single mock pilot id → unknown ids rejected 403). This ships in the no-auth milestone so a rogue local process can't exhaust shared NPROC/disk.
-- **Verify:** `pnpm ai:test` — test_sandboxes green (create→list→snapshot→delete roundtrip via TestClient; 6th create → 503; delete of unknown id → 404; abuse control (G-5): non-allowlisted learner_id → 403; >1 active sandbox for one learner → 429; burst of >10 creates/min → 429); manual probe: `curl -X POST localhost:8420/v1/sandboxes -d '{"learner_id":"l1"}'` returns a handle id
-
-### Must-Haves (Phase 1)
-- [ ] Isolation probe test green on this box: in-namespace uid=0, network isolated (0 usable interfaces), host writes confined to the per-sandbox bind dir (A-101 re-verified as an automated test, not just research notes)
-- [ ] Resource limits enforced + observable: memory (RLIMIT_AS) + CPU (RLIMIT_CPU) rlimits kill violating processes; wall-clock reaper destroys stale sandboxes; disk usage capped by a periodic workdir-size sweep in the manager (soft cap, configurable `AI_SANDBOX_MAX_WORKDIR_MB`, default 512MB — NOT kernel-enforced); per-sandbox NPROC is shared across sandboxes at the host uid — documented, not relied on for isolation (G-1, G-2 — test_resource_limits green)
-- [ ] No cross-tenant access: sandbox A cannot read sandbox B's workdir (isolation test asserts containment)
-- [ ] Lifecycle API works end-to-end: create/list/snapshot/destroy via TestClient; pool full → **503** (D-032, no queue)
-- [ ] Snapshot produces a restorable directory copy under the sandbox's own snapshots/ dir
-- [ ] `pnpm ai:test` and `pnpm ai:lint` green; new deps (`sqlmodel`, `sqlalchemy`, `websockets`, `aiofiles`) installed via idempotent bootstrap
-- [ ] Boundary rules hold: `sandbox/` imports nothing from `api/` or `agents/`; only `api/sandboxes.py` composes the manager via DI
-- [ ] No docker/podman/sudo anywhere in the spawner path (D-024); `SandboxBackend` protocol is the only coupling to the spawner (containerd swap possible later)
+**Verification hooks P1:** ci.yaml green on a fresh push (both lanes); hello.yaml green × 3 labels; release.yaml exercised at P1 ship (the v0.7.1 tag's release carries binary + checksum, built by the workflow — not by the local ship path); pre-commit both-direction proof; secrets audit clean; runners idle-registered at org level.
 
 ---
 
-## Phase 2: Live Build Telemetry
+## Phase 2: Docker Image Channel (REQ-8-002)
 
-**Requirements:** REQ-3-003
-**Goal:** First real persistence (D-027: SQLite via SQLModel) with a `TraceStore` protocol; `TelemetryEvent` model with per-(learner,task) monotonic `seq`; WebSocket ingest endpoint (D-026) with gap detection; stdlib-only in-sandbox capture agent streams real sandbox activity into ai-service; trace retrievable by learner+task
+**Goal:** The full stack as one unprivileged container — deps pre-loaded, single-port topology preserved, honest sandbox degrade, pushed to the Gitea registry on every phase release.
 
-### Wave 1: Models + stores + TS types (parallel — no shared files)
+### Wave 2-1: Image + degrade (devops-engineer + sandbox-engineer)
 
-#### Task 2-1-01: Telemetry event models
-- **Persona:** backend-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/ai_service/telemetry/__init__.py`, `apps/ai-service/ai_service/telemetry/models.py`, `apps/ai-service/tests/telemetry/__init__.py`, `apps/ai-service/tests/telemetry/test_models.py`
-- **Action:** Pydantic/SQLModel `TelemetryEvent`: `learner_id`, `task_id`, `seq` (int, monotonic per (learner,task)), `kind` (`command` | `file_diff` | `run_result` | `test_result` | `activity` | `stdin` | `stdout`), `payload` (JSON), `ts` (datetime, monotonic-envelope), `sandbox_id`. `TraceSpan` derived view (ordered events for one (learner,task)). Validation: seq ≥ 0, kind enum, non-empty ids.
-- **Verify:** `pnpm ai:test` — test_models green (validation rules enforced, JSON payload roundtrip)
+- **Task 2-1-01** (devops-engineer): Multi-stage Dockerfile per R-16..R-19 — web-export stage (node:24-bookworm, corepack pnpm, `NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build`, outputs `apps/web/out`), venv stage (python:3.11-bookworm, bootstrap.sh mechanics), runtime stage (python:3.11-slim-bookworm, non-root `nextcraft` user, uvicorn :8420, `AI_WEB_STATIC_DIR` → export, `NC_CONTAINER=1` marker, `EXPOSE 8420`, `HEALTHCHECK` GET /health, state volume `/home/nextcraft/.nextcraft`). CLI embedded per D-066 (`doctor`/`verify`/`guide` usable in-container; image tag stamped `NEXTCRAFT_VERSION_STAMP`).
+- **Task 2-1-02** (sandbox-engineer): Honest degrade per D-068/R-27..R-29 — `ai_service/sandbox/capability.py` promoting `tests/helpers/userns.py::userns_available()` verbatim (real probe, truth source: attempt userns + report), boot notice at startup when degraded (main.py G-11 loud-warning pattern), 503 arm beside PoolFullError in sandboxes.py (env creation rejected with remediation payload; web surfaces already render honest errors — additive only). **Remediation text is a single tested constant (G-208):** names the unprivileged default, the seccomp constraint, the documented privileged/seccomp-override variant (exact docker run flags), and the host-side alternative — the boot notice and the 503 payload carry the same constant. Tests: degraded-mode unit tests (probe mocked false → 503 + notice asserted); real userns path unchanged.
+- **Task 2-1-03** (cli-engineer): In-container CLI refusals per D-066/R-30 — `bootstrap`/`deploy`/`dev` detect `NC_CONTAINER` (or `.dockerenv` + marker) and refuse with honest exit 1 + remediation text (image is immutable; upgrade = docker pull per D-071); `doctor` gains container-mode branch (skips repo-root checks, verifies mount + /health); `verify` container semantics (probe the live listener + export presence).
 
-#### Task 2-1-02: TraceStore protocol + SQLite implementation
-- **Persona:** backend-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/ai_service/telemetry/store.py`, `apps/ai-service/tests/telemetry/test_store.py`, `apps/ai-service/ai_service/data/.gitkeep`
-- **Action:** `TraceStore` protocol (D-027, Postgres-migration-ready): `append(event) -> None` (idempotent on (learner,task,seq) — at-least-once dedup), `get_trace(learner_id, task_id) -> list[TelemetryEvent]` (ordered by seq), `gaps(learner_id, task_id) -> list[int]` (missing seqs), `latest_seq(learner_id, task_id) -> int`, `list_tasks(learner_id) -> list[str]`, `close()`. `SQLiteTraceStore(SQLModel)`: single `telemetry_event` table, composite PK ((learner_id, task_id, seq)), indexes on (learner_id, task_id). Engine creation from `AI_DB_PATH`; `SQLModel.metadata.create_all` at app lifespan. Enable `PRAGMA journal_mode=WAL` + `synchronous=NORMAL` at engine creation (a-3) so concurrent ingest (writer) and trace reads (grader) don't hit `database is locked` under concurrent sandboxes.
-- **Verify:** `pnpm ai:test` — test_store green (append/ordered-get/dedup-on-retry/gap detection/latest_seq; tmp-path SQLite per test)
+### Wave 2-2: Registry push + release integration (devops-engineer)
 
-#### Task 2-1-03: TS types for telemetry/traces
-- **Persona:** data-engineer — **REQ:** REQ-3-003
-- **Files:** `packages/types/telemetry.ts` (new), `packages/types/index.ts` (update)
-- **Action:** TS `TelemetryEvent`, `TraceSpan`, `TelemetryKind` mirroring the Python model field-for-field (cross-referencing header, same string enums). Consumed by Phase 6 web surfaces; no runtime code.
-- **Verify:** `pnpm typecheck` passes; TS type keys match Python model keys exactly
+- **Task 2-2-01** (devops-engineer): Release workflow registry step per R-20/D-065 — `docker build` on the tag ref, `docker login git.coreci.dev` with `secrets.REGISTRY_TOKEN`, push `git.coreci.dev/coreci/nextcraft:$TAG` + `:latest`. Blocks on Task 1-2-04's secret existing (escalation if still pending: ship proceeds, push step marked `continue-on-error: false` + release notes note the missing image).
+- **Task 2-2-02** (devops-engineer): `docker run` smoke gate in the workflow — five pinned assertions (G-204): container starts → `/health` 200 within timeout → `GET /` is content-type text/html AND contains a known page marker (not merely non-JSON-404) → degrade boot notice present in container logs → fabric env-create returns 503 with the remediation payload → clean stop. A broken image = failed release job.
+- **Task 2-2-03** (security-auditor): Image audit — non-root confirmed, no secrets in layers (`.env*`/`.ciagent/` excluded via `.dockerignore`), healthcheck present, minimal runtime (no build toolchain in the final layer).
 
-### Wave 2: Capture agent + ingest (depends on Wave 1)
-
-#### Task 2-2-01: In-sandbox capture agent (stdlib-only)
-- **Persona:** sandbox-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/scripts/sandbox-agent.py`, `apps/ai-service/tests/sandbox/test_sandbox_agent.py`
-- **Action:** Tiny standalone process (D-031, **stdlib only** — no deps shipped into the namespace): wraps a shell inside the sandbox; captures commands, file diffs (mtime/content polling of `workspace/` at 250ms), run/test results, activity; assigns per-(learner,task) `seq`; buffers to a local spool file on disconnect (at-least-once, D-026); reconnects with **exponential backoff** and flushes spool in order; small WebSocket client implemented over raw `socket` (RFC6455 client handshake + frames — stdlib only, no `websockets` in-namespace). Configured via env baked at spawn (`NC_LEARNER_ID`, `NC_TASK_ID`, `NC_INGEST_URL`).
-- **Verify:** `pnpm ai:test` — unit tests with a loopback fake WS server: ordered seq emission, spool-on-disconnect, reconnect flush preserves order (no loss, dupes deduped server-side), no third-party imports in the file (asserted by AST scan)
-
-#### Task 2-2-02: WebSocket ingest endpoint
-- **Persona:** backend-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/ai_service/telemetry/ingest.py`, `apps/ai-service/ai_service/api/sandboxes.py` (update: register WS route), `apps/ai-service/ai_service/main.py` (update), `apps/ai-service/tests/api/test_telemetry_ingest.py`
-- **Action:** `WS /v1/telemetry/ingest` (D-026): accepts connections carrying learner_id/task_id/sandbox_id; validates + appends events to `TraceStore` (idempotent — server-side dedup on (learner,task,seq)); emits **gap warnings** when seq skips (logged + surfaced in a per-connection status); ping/pong keepalive. **Backpressure / flood control (G-3 — replaces silent drop):** bounded inbound queue; on overflow OR when a per-connection cap `AI_TELEMETRY_MAX_EVENTS_PER_TASK` (default 50000) is exceeded → **reject with a 1008 policy-violation close and mark the (learner,task) trace `INCOMPLETE_FLOODED`** (an integrity signal consumed by Proctor). Silent drop-oldest is FORBIDDEN because it corrupts grading input and is indistinguishable from trace-gaming. `GET /v1/telemetry/traces/{learner_id}/{task_id}` returns the ordered trace; `GET /v1/telemetry/gaps/{learner_id}/{task_id}` returns missing seqs.
-- **Verify:** `pnpm ai:test` — test_telemetry_ingest green (TestClient websocket: connect → send 3 events → trace retrievable ordered; resend event 2 → deduped; skip seq 5 → gap reported; unknown sandbox tolerated in v0.3 no-auth mode)
-
-### Wave 3: Sandbox telemetry wiring (depends on Wave 2)
-
-#### Task 2-3-01: Spawn sandboxes with the capture agent
-- **Persona:** sandbox-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/ai_service/sandbox/manager.py` (update), `apps/ai-service/ai_service/sandbox/unshare_backend.py` (update), `apps/ai-service/tests/sandbox/test_telemetry_wiring.py`
-- **Action:** `create()` gains optional `task_id`; when set the spawner copies `scripts/sandbox-agent.py` into the sandbox workdir, injects `NC_*` env, and launches the agent as a child of the namespace process (agent lifecycle tied to sandbox lifecycle; destroy kills the agent). No capture when task_id absent (pure shell sandbox).
-- **Verify:** `pnpm ai:test` — end-to-end on this box: create sandbox with task_id → run 2 commands via exec → events arrive at the ingest endpoint and land in SQLite in order
-
-### Wave 4: Reliability probe (depends on Wave 3)
-
-#### Task 2-4-01: Dropped-connection durability probe
-- **Persona:** backend-engineer — **REQ:** REQ-3-003
-- **Files:** `apps/ai-service/tests/telemetry/test_durability.py`
-- **Action:** Integration probe: run a capture agent against ingest, kill the WS connection mid-stream (simulate network failure), keep generating events, reconnect, assert the SQLite trace contains **every** event exactly once in order (spool + dedup). Document at-least-once semantics + replay path in README.
-- **Verify:** `pnpm ai:test` — test_durability green; README documents semantics
-
-### Must-Haves (Phase 2)
-- [ ] Real telemetry from a live sandbox arrives at ai-service: shell commands, file diffs, run/test results appear as ordered events in SQLite (end-to-end, no mocks)
-- [ ] Per-(learner,task) monotonic `seq`; gap detection reports missing seqs; replay yields the complete ordered trace
-- [ ] At-least-once proven: transient disconnect + reconnect loses no events; duplicates deduped server-side (durability probe green)
-- [ ] Capture agent is stdlib-only (AST-verified) and its lifecycle is tied to the sandbox (destroy kills it)
-- [ ] Trace retrievable by learner+task via `GET /v1/telemetry/traces/...`; unknown trace → 404
-- [ ] `TraceStore` protocol respected: no api/ code touches SQLite directly; `telemetry/` never imports `agents/` (D-027)
-- [ ] Flood control (G-3): burst past `AI_TELEMETRY_MAX_EVENTS_PER_TASK` → connection closed 1008 + trace marked `INCOMPLETE_FLOODED`; no silent event drop on overflow
-- [ ] `pnpm ai:test` green; `packages/types` telemetry TS types compile (`pnpm typecheck`)
+**Verification hooks P2:** image builds locally + on the runner; pushed to the registry under the phase tag + latest; smoke gate green (HTML at /, degraded fabric reported honestly); degrade tests green in the fast pytest lane; in-container doctor/verify/refusals green (CLI tests); `.dockerignore` excludes secrets; all existing suites stay green (no regressions from capability.py promotion — the real userns suites unchanged).
 
 ---
 
-## Phase 3: Process-Trace Grading Engine
+## Phase 3: Debian-Native Channel (REQ-8-003)
 
-**Requirements:** REQ-3-004
-**Goal:** Deterministic feature computation over traces (D-028) → compact digest → LLM rubric scoring via existing D-020 JSON defense → validated structured scores stored in `GradeStore`; LLM never sees the raw trace; engine calibrated against v0.2 mock corpora so process quality separates paste-and-run from iterative debugging
+**Goal:** arm64 binaries + .deb packages for x64 + arm64, attached to every release; install.sh resolves arch; every channel ends at doctor/verify green.
 
-### Wave 1: Features + grades store (parallel — no shared files)
+### Wave 3-1: arm64 cross-build (cli-engineer)
 
-#### Task 3-1-01: Deterministic trace digest (features)
-- **Persona:** ai-engineer — **REQ:** REQ-3-004
-- **Files:** `apps/ai-service/ai_service/grading/__init__.py`, `apps/ai-service/ai_service/grading/features.py`, `apps/ai-service/tests/grading/__init__.py`, `apps/ai-service/tests/grading/test_features.py`
-- **Action:** Pure compute module (D-028): `compute_digest(trace: list[TelemetryEvent]) -> TraceDigest`. Deterministic features: test pass/fail counts + final status; edit count; error/fix cycle count + mean fix latency; idle gaps (>Ns, count + total); command category histogram (build/test/file/nav/debug/other); session duration; first-test-pass offset. `TraceDigest` pydantic model — compact (bounded size, no raw commands), LLM-safe.
-- **Verify:** `pnpm ai:test` — test_features green over synthetic traces: paste-and-run trace (0 error/fix cycles, single test pass at end) vs iterative trace (many cycles) produce observably different digests
+- **Task 3-1-01** (cli-engineer): `build-binary.mjs` arch parameter per R-25 — `--arch x64|arm64`; the ONLY arch-specific step (copy of `process.execPath`) replaced by the official arm64 node tarball download (probe-verified 200/30MB) for arm64; esbuild bundle + postject injection unchanged (arch-agnostic file surgery); output `nextcraft-linux-arm64` + `.sha256`. **Decided fallback ladder (G-201):** probe QEMU-free cross-arch SEA on the runner first; if the blob fails under emulation, fall back to binfmt+qemu for FULL arm64 builds; if the runner cannot install binfmt, ship v0.8 x64-only (arm64 deferral recorded in ship notes + REQUIREMENTS) — never leave the release lane red or blocked.
+- **Task 3-1-02** (cli-engineer): Binary contract tests — arm64 binary `--version` reports the stamped tag (under emulation in CI); x64 path byte-identical to the v0.4 pipeline (checksum + version gates unchanged).
 
-#### Task 3-1-02: GradeStore protocol + SQLite implementation
-- **Persona:** backend-engineer — **REQ:** REQ-3-004
-- **Files:** `apps/ai-service/ai_service/grading/store.py`, `apps/ai-service/tests/grading/test_store.py`
-- **Action:** `GradeStore` protocol (D-027): `save(grade)`, `get(learner_id, task_id)`, `list_for_learner(learner_id)`, `close()`. SQLModel `GradeRecord`: learner_id, task_id, variant_seed (null until P4), digest (JSON), scores (JSON), verdict, model, created_at. PK (learner_id, task_id). Postgres-migration-ready.
-- **Verify:** `pnpm ai:test` — test_store green (save/get/list roundtrip, overwrite-on-regrade documented)
+### Wave 3-2: deb packages + installer + release extension (cli-engineer + devops-engineer)
 
-### Wave 2: Grading engine + calibration (depends on Wave 1)
+- **Task 3-2-01** (cli-engineer): `scripts/build-deb.sh` per R-22/R-23 — `dpkg-deb --root-owner-group -Zxz`, package `nextcraft` Version = tag minus `v`, empty Depends + `Recommends: nodejs, python3, git, util-linux`, contents: `/usr/bin/nextcraft` (arch-matched binary) + `/usr/share/doc/nextcraft/` (README + guide); postinst = advisory doctor (`|| echo` → always exit 0, never fails dpkg per D-067); outputs `nextcraft_<ver>_<arch>.deb` + sidecars.
+- **Task 3-2-02** (cli-engineer): `install.sh` arch-resolve per R-24 — `uname -m` x86_64 → x64 asset, aarch64/arm64 → arm64 asset; checksum + version integrity gates byte-identical for both; degradation messaging unchanged.
+- **Task 3-2-03** (devops-engineer): Release workflow extension — arm64 binary build + both debs join the release-asset attach step (x64 binary, arm64 binary, 2× sha256, 2× deb — full asset matrix per D-064); smoke: deb installs in a fresh debian container, `nextcraft --version` + advisory doctor run. **Proof via the G-203 temporary-rc-tag mechanism.**
+- **Task 3-2-04** (security-auditor): Asset audit — all 6 release assets checksum-verified, version stamps match the tag, no secrets in debs.
 
-#### Task 3-2-01: Rubric scoring engine
-- **Persona:** ai-engineer — **REQ:** REQ-3-004
-- **Files:** `apps/ai-service/ai_service/grading/engine.py`, `apps/ai-service/ai_service/prompts/grading.py` (new), `apps/ai-service/tests/grading/test_engine.py`
-- **Action:** `GradingEngine.grade(learner_id, task_id) -> GradeRecord`: **trace-completeness gate (G-4)** — first call `TraceStore.gaps()` + check the trace `INCOMPLETE_FLOODED` flag; if gaps are non-empty OR the trace is flagged incomplete → return `verdict=UNGRADABLE_TRACE_INCOMPLETE` (a first-class verdict, not an exception) surfacing the gap list; a credential is NEVER issued from a gapped/incomplete trace. Otherwise: load trace via `TraceStore` → `compute_digest` → render rubric prompt (`prompts/grading.py`: criteria + level anchors for process quality, correctness, debugging discipline, test usage; a-4: treat high edit/command churn with no test-progress as a process-quality negative) → LLM structured output through the **existing D-020 4-layer defense** (`agents/structured.py` reused — engine composes it, never duplicates it) → validate `RubricScore` model (per-criterion 0-4 + strengths + gaps + verdict) → persist via `GradeStore`. Grading depends on `llm/` + `telemetry/` + `prompts/` only (boundary). Mock provider scripts deterministic rubric JSON for tests, including the INCOMPLETE path.
-- **Verify:** `pnpm ai:test` — test_engine green (mock provider: digest-only prompt asserted — **raw trace string absent from prompt**; validated scores returned; malformed JSON exercises D-020 retry; unknown trace → error)
-
-#### Task 3-2-02: Calibration against v0.2 mock corpora
-- **Persona:** ai-engineer — **REQ:** REQ-3-004
-- **Files:** `apps/ai-service/ai_service/corpus/trace_fixtures.py` (new), `apps/ai-service/tests/grading/test_calibration.py`
-- **Action:** Synthetic trace fixtures aligned with v0.2 `corpus/telemetry.py` + `corpus/artifacts.py` scenario IDs (strong/lazy/struggling builder archetypes). Assert grading separates them: strong archetype scores ≥ lazy archetype on process-quality criterion (mock provider maps digest shape → scripted scores; test asserts the ordering contract + that fixture IDs align with existing corpus IDs, D-021).
-- **Verify:** `pnpm ai:test` — test_calibration enforces the ordering contract
-
-### Wave 3: Grading endpoint (depends on Wave 2)
-
-#### Task 3-3-01: Assessment grade endpoint (real traces)
-- **Persona:** backend-engineer — **REQ:** REQ-3-004
-- **Files:** `apps/ai-service/ai_service/api/assessment.py` (update), `apps/ai-service/tests/api/test_grading.py`
-- **Action:** `POST /v1/assessment/grade {learner_id, task_id}` → `GradingEngine` → validated `RubricScore` JSON; `GET /v1/assessment/grade/{learner_id}/{task_id}` → stored grade; unknown trace → 404. Composed via DI (api/ owns wiring; engine knows nothing of FastAPI).
-- **Verify:** `pnpm ai:test` — test_grading green (grade roundtrip via TestClient with mock provider; 404 on unknown; GET after POST returns same scores)
-
-### Must-Haves (Phase 3)
-- [ ] Engine emits structured rubric-aligned scores from a **real process trace** (not pre-baked input) — TestClient roundtrip green
-- [ ] Deterministic features computed in code (test pass/fail, edit count, error/fix cycles, idle gaps, command categories); LLM receives the **digest only** — test asserts the raw trace never reaches the prompt (D-028)
-- [ ] Scores distinguish process quality: iterative-debugging archetype out-scores paste-and-run on the process criterion (calibration contract test)
-- [ ] Grades persisted + retrievable by learner+task via GradeStore (SQLite, protocol-wrapped, D-027)
-- [ ] Boundary rules hold: `grading/` imports no `api/`/`agents/` internals except the shared D-020 structured defense; `pnpm ai:test` + `pnpm ai:lint` green
-- [ ] Incomplete-trace gate (G-4): gapped or `INCOMPLETE_FLOODED` trace → `verdict=UNGRADABLE_TRACE_INCOMPLETE` with the gap list; no credential issued from an incomplete trace (test green)
+**Verification hooks P3:** arm64 binary + 2 debs build in CI (release lane green on the phase tag); install.sh fetches the right asset per arch (fixture-server test extended, tamper-rejection unchanged); deb installs → binary on PATH → advisory doctor runs; x64 pipeline byte-identical (no regression); asset matrix complete on the v0.7.3 release.
 
 ---
 
-## Phase 4: Variant Task Generation
+## Phase 4: CLI Onboarding (REQ-8-004)
 
-**Requirements:** REQ-3-005
-**Goal:** Template library with typed parameter slots (D-029) + seeded LLM instantiation + per-learner variant registry (SQLite) with difficulty-normalization anchors; two learners on the same competency get provably distinct, reproducible, auditable tasks
+**Goal:** `nextcraft` alone takes an admin zero → running — channel-aware doctor, `guide`, honest refusals, per-channel E2E.
 
-### Wave 1: Templates + store (parallel — no shared files)
+### Wave 4-1: Channel awareness + guide (cli-engineer)
 
-#### Task 4-1-01: Task template library
-- **Persona:** ai-engineer — **REQ:** REQ-3-005
-- **Files:** `apps/ai-service/ai_service/variants/__init__.py`, `apps/ai-service/ai_service/variants/templates.py`, `apps/ai-service/tests/variants/__init__.py`, `apps/ai-service/tests/variants/test_templates.py`
-- **Action:** ≥3 initial task templates bound to existing competency IDs (D-021 alignment). `TaskTemplate`: id, competency_id, statement skeleton with `{slot}` placeholders, `ParameterSlot[]` (name, type: enum/int-range/string-set, allowed values), `rubric anchors` (difficulty normalization: expected feature envelope — e.g. expected edit-count band — used by grading context), starter-file scaffolds served to the sandbox. Seeded slot sampler is pure code (`random.Random(seed)`), fully reproducible.
-- **Verify:** `pnpm ai:test` — test_templates green (slot validation: bad value rejected; seeded sampling reproducible across runs; all templates bind to real competency IDs)
+- **Task 4-1-01** (cli-engineer): Doctor channel awareness per R-30 — container-mode branch (from P2), deb-install detection (`dpkg -s nextcraft` or binary-at-/usr/bin heuristics; report channel + its upgrade semantics per D-071), binary-install default. Each channel's doctor outputs the right next-step line (deploy --service vs docker pull + recreate).
+- **Task 4-1-02** (cli-engineer): `nextcraft guide` per D-072 — offline-first embedded man-page text (no runtime fetches): sections per channel (first install, upgrade, troubleshooting pointers), forge URLs as pointers. `guide [topic]` optional arg (guide deploy / guide docker / guide deb / guide troubleshooting).
+- **Task 4-1-03** (cli-engineer): CLI tests for the new surface — dispatch tests (guide routing, refusals, doctor branches per detected channel via env/fixtures); exit-code contract unchanged (0 ok / 1 failure / 2 usage).
 
-#### Task 4-1-02: VariantStore protocol + SQLite implementation
-- **Persona:** backend-engineer — **REQ:** REQ-3-005
-- **Files:** `apps/ai-service/ai_service/variants/store.py`, `apps/ai-service/tests/variants/test_store.py`
-- **Action:** `VariantStore` protocol (D-027): `save(variant)`, `get(learner_id, template_id_or_task_id)`, `list_for_learner(learner_id)`, `list_by_template(template_id)`, `close()`. SQLModel `VariantRecord`: learner_id, task_id (the grading/telemetry task key), template_id, seed, params (JSON), statement (rendered), created_at. Unique (learner_id, template_id).
-- **Verify:** `pnpm ai:test` — test_store green (roundtrip, unique constraint, audit listing)
+### Wave 4-2: Per-channel E2E (cli-engineer + devops-engineer)
 
-### Wave 2: Generator (depends on Wave 1)
+- **Task 4-2-01** (cli-engineer): Docker-channel E2E (env-gated like the v0.4 E2E): pull the released image, run, in-container doctor/verify green, refusals honest, teardown. Wired as `cli:test:e2e:docker`, excluded from default lanes.
+- **Task 4-2-02** (cli-engineer): deb-channel E2E (env-gated): fresh debian container, install the released deb, advisory doctor, `nextcraft guide`, teardown. `cli:test:e2e:deb`.
+- **Task 4-2-03** (lead-developer): The binary channel E2E already exists (fresh-clone, v0.4) — verify it still passes with the arch-resolve installer; wire the three E2E names into the docs so admins can reproduce them.
 
-#### Task 4-2-01: Seeded LLM variant generator
-- **Persona:** ai-engineer — **REQ:** REQ-3-005
-- **Files:** `apps/ai-service/ai_service/variants/generator.py`, `apps/ai-service/ai_service/prompts/variant.py` (new), `apps/ai-service/tests/variants/test_generator.py`
-- **Action:** `VariantGenerator.generate(learner_id, template_id) -> VariantRecord`: derive seed (`sha256(template_id|learner_id|milestone)` — reproducible, D-029); sample typed slots in code; render a fill prompt (statement skeleton + concrete slot values) → LLM via D-020 structured defense → unique task statement + starter files → validate → persist (seed + params + statement) via `VariantStore`. Cache: existing (learner,template) returns the stored variant (no duplicate work). Mock provider scripts deterministic statements per seed for tests.
-- **Verify:** `pnpm ai:test` — test_generator green: two different learner_ids → distinct statements for the same template; same learner twice → identical stored variant (reproducible); params JSON contains only schema-valid slot values; **fairness envelope (a-5):** two variants of one template compute digests within the template's expected feature envelope (comparable slot complexity/difficulty features) — "same bar" is testable, not asserted
-
-### Wave 3: Variant endpoint + TS types (depends on Wave 2)
-
-#### Task 4-3-01: Variant task endpoint
-- **Persona:** backend-engineer — **REQ:** REQ-3-005
-- **Files:** `apps/ai-service/ai_service/api/variants.py` (new), `apps/ai-service/ai_service/main.py` (update), `apps/ai-service/tests/api/test_variants.py`
-- **Action:** `POST /v1/variants {learner_id, template_id or competency_id}` → generated (or cached) variant: statement, starter files, task_id, seed; `GET /v1/variants/{task_id}` → stored variant; `GET /v1/variants?learner_id=` → learner's variants. DI wiring in api/ only.
-- **Verify:** `pnpm ai:test` — test_variants green (generate→get roundtrip; cache hit on regenerate; distinct learners → distinct statements asserted at the API layer)
-
-#### Task 4-3-02: TS types for variants (+ grades)
-- **Persona:** data-engineer — **REQ:** REQ-3-005
-- **Files:** `packages/types/variants.ts` (new), `packages/types/grading.ts` (new), `packages/types/index.ts` (update)
-- **Action:** TS `TaskVariant`, `VariantParams`, `RubricScore`, `GradeRecord` matching Python models (cross-referencing headers; same field names). Consumed by Phase 6 surfaces.
-- **Verify:** `pnpm typecheck` passes
-
-### Must-Haves (Phase 4)
-- [ ] Two learners requesting the same competency receive **provably distinct** task variants (API-level test)
-- [ ] Seed derivation reproducible: same (template, learner) → same variant, served from cache without a second LLM call (D-029)
-- [ ] Variant seed + typed params persisted + auditable (VariantStore listing; proctoring cross-check path exists)
-- [ ] Difficulty normalization anchors present per template and shipped to the grader prompt context
-- [ ] Starter-file scaffolds defined per template (P6 wires them into the sandbox workdir)
-- [ ] `pnpm ai:test` + `pnpm typecheck` green; `variants/` imports no api/ (boundary)
+**Verification hooks P4:** all CLI suites green at current counts; guide renders offline (no network mock asserted); doctor reports the right channel in all three modes (fixture tests); docker + deb E2E green when env-gated on; existing binary E2E green; no regression in the 61-test CLI baseline surface (net new tests allowed).
 
 ---
 
-## Phase 5: Oral / Voice Defense
+## Phase 5: Admin Guides (REQ-8-005)
 
-**Requirements:** REQ-3-006
-**Goal:** `VoiceProvider` protocol with mock + browser fallback (D-030) + seventh `Examiner` agent streaming over existing SSE + `DefenseStore` persisting transcript + integrity signals. **Real server STT/TTS (`OpenAIAudioProvider`) is DEFERRED to v0.4 (with KYC, when there's a real key + real users)** — voice is mock-first (D-030) and the `/audio/*` real path could never be exercised in CI, so v0.3 proves the full defense *dialogue* + integrity-signal pipeline over mock + browser-native fallback only; the protocol seam keeps the real provider a drop-in later.
+**Goal:** The admin runbook — every channel's first-install + upgrade recipe, evidence-backed, one entry point.
 
-### Wave 1: Voice provider layer (parallel — no shared files)
+### Wave 5-1: The runbook (lead-developer + cli-engineer)
 
-#### Task 5-1-01: VoiceProvider protocol + mock provider + browser fallback
-- **Persona:** voice-engineer — **REQ:** REQ-3-006
-- **Files:** `apps/ai-service/ai_service/voice/__init__.py`, `apps/ai-service/ai_service/voice/base.py`, `apps/ai-service/ai_service/voice/mock.py`, `apps/ai-service/ai_service/voice/browser.py`, `apps/ai-service/ai_service/voice/factory.py`, `apps/ai-service/tests/voice/__init__.py`, `apps/ai-service/tests/voice/test_mock.py`, `apps/ai-service/tests/voice/test_factory.py`
-- **Action:** `VoiceProvider` protocol mirroring `LLMProvider` (D-030): `transcribe(audio: bytes, fmt) -> TranscriptSegment` + `synthesize(text, voice) -> AsyncIterator[bytes]`. `MockVoiceProvider`: deterministic canned transcript (scripted per test), canned 1kHz-tone WAV bytes, scripted failure modes. `browser.py`: fallback **descriptor** (`sr_available: true`, endpoint hints) the web client uses to select browser-native `SpeechRecognition`/`speechSynthesis` when no server provider. `factory.py`: `AI_VOICE_PROVIDER=browser | mock` (default mock when no key). **`OpenAIAudioProvider` (real server STT/TTS) intentionally NOT built in v0.3 — deferred to v0.4**; the protocol is its future seam. `voice/` never imports `agents/` or `api/`.
-- **Verify:** `pnpm ai:test` — test_mock + test_factory green (deterministic transcribe/synthesize; failure modes; factory selects mock with empty key, browser when provider=browser; zero network calls)
+- **Task 5-1-01** (lead-developer): `deploy/README.md` → the full admin runbook per R-31/R-32 — structure: pick-your-channel matrix → docker channel (docker run, volumes, privileged variant for full in-container sandboxes, upgrade = pull + recreate per D-071) → deb channel (dpkg -i, advisory doctor, deploy --service integration) → binary channel (install.sh one-liner, existing recipe preserved) → upgrade matrix table → HAProxy/systemd recipes (existing content preserved) → troubleshooting tables (runner/registry/docker-degrade/deb — extended from the CLI README's) → evidence appendix (which test or live probe backs each recipe).
+- **Task 5-1-02** (cli-engineer): `nextcraft guide` content parity — the runbook's channel sections are the canonical text, extracted to a single shared source (G-210); the guide renders from that source; divergence = parity test failure (never doc drift).
+- **Task 5-1-03** (lead-developer): README quickstart updated — three channels listed with one command each; the v0.8 milestone line added to the history table.
 
-#### Task 5-1-03: DefenseStore protocol + SQLite implementation
-- **Persona:** backend-engineer — **REQ:** REQ-3-006
-- **Files:** `apps/ai-service/ai_service/voice/defense_store.py`, `apps/ai-service/tests/voice/test_defense_store.py`
-- **Action:** `DefenseStore` protocol (D-027): `start(defense)`, `append_turn(defense_id, turn)`, `finalize(defense_id, integrity_signals)`, `get(defense_id)`, `list_for_learner(learner_id)`, `close()`. SQLModel `DefenseRecord` (id, learner_id, task_id, status, created/finished_at) + `DefenseTurn` (defense_id FK, turn seq, role examiner|learner, text, ts, latency_ms) + integrity signals JSON on the record (long pauses, off-scope cadence markers — A-109).
-- **Verify:** `pnpm ai:test` — test_defense_store green (start→append turns→finalize→get roundtrip; ordered turns by seq)
+### Wave 5-2: Guide verification (lead-developer)
 
-### Wave 2: Examiner agent (depends on Wave 1)
+- **Task 5-2-01** (lead-developer): Every runbook recipe evidence-checked — each recipe carries a pointer to its backing test (E2E name, workflow job, or live-box probe from prior phases); the parity test proves guide ↔ runbook agreement; doc lint (markdown structure) if cheap.
 
-#### Task 5-2-01: Examiner agent (seventh agent)
-- **Persona:** ai-engineer — **REQ:** REQ-3-006
-- **Files:** `apps/ai-service/ai_service/agents/examiner.py`, `apps/ai-service/ai_service/prompts/examiner.py` (new), `apps/ai-service/ai_service/agents/registry.py` (update: central registration, G-4 pattern), `apps/ai-service/tests/agents/test_examiner.py`
-- **Action:** `ExaminerAgent(BaseAgent)` (D-030/A-109): builds questions from learner transcript + trace digest + (P4) variant statement; probes understanding + challenges process choices ("why did you choose X at step N?"); streams questions over the existing SSE pipeline; `structured` verdict mode returns verdict + per-answer integrity signal list (long pause flags, off-scope answers) computed from turn metadata; calls voice **only through the `VoiceProvider` protocol** (PERSONAS conflict rule — never concrete providers). Session-scoped history reused from v0.2.
-- **Verify:** `pnpm ai:test` — test_examiner green (question stream references trace-digest facts; verdict structured output validates via D-020 defense; registry resolves all seven agents; mock-VoiceProvider wiring through protocol only — asserted by import scan in test)
-
-### Wave 3: Defense endpoints (depends on Wave 2)
-
-#### Task 5-3-01: Defense session + audio endpoints
-- **Persona:** backend-engineer — **REQ:** REQ-3-006
-- **Files:** `apps/ai-service/ai_service/api/defense.py` (new), `apps/ai-service/ai_service/main.py` (update), `apps/ai-service/tests/api/test_defense.py`
-- **Action:** `POST /v1/defense/start {learner_id, task_id}` → creates DefenseRecord + streams the first examiner question (SSE, agent=examiner); `POST /v1/defense/{id}/answer` (multipart audio from browser MediaRecorder, or `{text}` for typed fallback) → STT via VoiceProvider → append learner turn → stream examiner follow-up (SSE) → TTS audio chunks over `GET /v1/defense/{id}/audio/{turn_id}`; `POST /v1/defense/{id}/finish` → verdict + integrity signals persisted; `GET /v1/defense/{id}` → full transcript + signals. Browser-fallback mode: when provider=browser, start returns the fallback descriptor instead of server audio.
-- **Verify:** `pnpm ai:test` — test_defense green (full loop with mock voice + mock LLM: start → answer(text) → answer(audio bytes) → finish → transcript retrievable with per-turn latency; unknown id → 404; `GET` signals present after finish)
-
-### Wave 4: Examiner latency instrumentation (depends on Wave 3)
-
-#### Task 5-4-01: Per-turn latency instrumentation (mock-based)
-- **Persona:** voice-engineer — **REQ:** REQ-3-006
-- **Files:** `apps/ai-service/tests/voice/test_latency.py`, `apps/ai-service/README.md` (update: conversational-budget doc + v0.4 voice note)
-- **Action:** Instrument per-turn latency (STT ms + LLM TTFT ms + TTS ms) recorded on each DefenseTurn; deterministic test over mock providers asserts instrumentation presence + `latency_ms` populated + budget constant defined (mock runs are near-instant — wall-clock asserted in v0.4 against a real endpoint). README documents the conversational-latency target as a v0.4 acceptance criterion (real STT/TTS deferred per CUT-1/G-7).
-- **Verify:** `pnpm ai:test` — test_latency green (latency_ms fields populated on every turn; budget constant defined); README documents the deferred real-voice acceptance probe
-
-### Must-Haves (Phase 5)
-- [ ] Spoken defense runs end-to-end over HTTP with mock providers: start → answer (audio + typed fallback) → examiner follow-up streams → verdict + transcript persisted (automated)
-- [ ] Examiner is the seventh registered agent; streams over the existing SSE envelope (meta agent=examiner)
-- [ ] Instrumented per-turn latency fields populated on every DefenseTurn (STT ms + LLM TTFT ms + TTS ms); conversational budget named (A-109)
-- [ ] `VoiceProvider` protocol respected: examiner + api touch voice only via the protocol; mock-first — **no task requires a real voice key to pass**
-- [ ] Browser-native SR/TTS fallback descriptor returned when no server voice provider configured (mock/browser are first-class, D-030)
-- [ ] Real server STT/TTS (`OpenAIAudioProvider`) explicitly deferred to v0.4 (with real keys/users); the defense pipeline is fully proven over mock+browser — documented in README + release note
-- [ ] Optional future voice config noted for v0.4 (`AI_VOICE_BASE_URL` / `AI_VOICE_API_KEY`) in `.env.example` + README; keys only in gitignored `.ciagent/.env.secrets`; tests never call a voice API
-- [ ] Boundary rules hold: `voice/` imports no `agents/`/`api/`; `pnpm ai:test` + `pnpm ai:lint` green
+**Verification hooks P5:** runbook complete (all channels, upgrade matrix, troubleshooting, evidence appendix); parity test green; README quickstart accurate; no unevidenced recipe claims (each has a pointer); existing deploy recipes (systemd/HAProxy) preserved verbatim-accurate.
 
 ---
 
-## Phase 6: Agent Re-grounding + Learner Surface Integration
+## Phase 6: Final Review + Ship (milestone release, v0.7.x line)
 
-**Requirements:** REQ-3-007, REQ-3-008
-**Goal:** Lab/Assessor/Proctor consume real engine inputs (live telemetry, grading output, defense signals) with **no mock fallback in the learner path**; the v0.1 sandbox + assessment mockups become real — in-browser build/run (Run/Test buttons + read-only exec output, CUT-2 — no interactive shell), live telemetry panel, browser/typed voice defense, live grading; `pnpm build` + `pnpm typecheck` + full `pnpm ai:test` green
-**Note:** E2E verification runs against the real engines over HTTP with `AI_PROVIDER=mock` + `AI_VOICE_PROVIDER=mock` permitted (G-2 precedent) — the requirement is real engine plumbing (sandbox/telemetry/grading/defense over real endpoints, no corpus mocks in the learner path); a cloud outage must not block P6.
-
-### Wave 1: Agent re-grounding (parallel — no shared files)
-
-#### Task 6-1-01: Lab agent on live telemetry
-- **Persona:** ai-engineer — **REQ:** REQ-3-007
-- **Files:** `apps/ai-service/ai_service/agents/lab.py` (update), `apps/ai-service/ai_service/prompts/lab.py` (update: render real trace digest), `apps/ai-service/tests/agents/test_lab_live.py` (new)
-- **Action:** Lab consumes a **live trace digest** (grading/features `compute_digest` over `TraceStore` events) instead of `corpus/telemetry.py`. build_messages renders digest facts (recent commands, failing tests, idle). Mock-provider scripts assert digest-derived content. v0.2 corpus path removed from the agent (dormant corpus retained until Task 6-1-04 check).
-- **Verify:** `pnpm ai:test` — test_lab_live green: feedback references events actually present in a seeded SQLite trace (not corpus fixtures); no `corpus.telemetry` import in `agents/lab.py` (AST-asserted)
-
-#### Task 6-1-02: Assessor agent on grading output
-- **Persona:** ai-engineer — **REQ:** REQ-3-007
-- **Files:** `apps/ai-service/ai_service/agents/assessor.py` (update), `apps/ai-service/ai_service/prompts/assessor.py` (update), `apps/ai-service/tests/agents/test_assessor_live.py` (new)
-- **Action:** Assessor consumes `GradeStore` output (validated `RubricScore` + digest) for learner+task instead of pre-baked artifacts/transcripts; renders strengths/gaps/verdict with rubric-anchored coaching framing. Structured output unchanged (D-020).
-- **Verify:** `pnpm ai:test` — test_assessor_live green: given a real stored grade, Assessor output reflects its scores; corpus artifact path gone from the agent (AST-asserted)
-
-#### Task 6-1-03: Proctor agent on telemetry + defense signals
-- **Persona:** ai-engineer — **REQ:** REQ-3-007
-- **Files:** `apps/ai-service/ai_service/agents/proctor.py` (update), `apps/ai-service/ai_service/prompts/proctor.py` (update), `apps/ai-service/tests/agents/test_proctor_live.py` (new)
-- **Action:** Proctor consumes real integrity inputs: idle gaps + command cadence from the trace digest + defense integrity signals from `DefenseStore` → classified signals + coaching interventions (supportive tone retained). Cross-checks variant seed params (P4) for off-template work.
-- **Verify:** `pnpm ai:test` — test_proctor_live green: signals derived from seeded real trace + defense records; corpus proctor scenarios no longer imported (AST-asserted)
-
-#### Task 6-1-04: Corpus dormancy + mockup removal verification
-- **Persona:** lead-developer — **REQ:** REQ-3-007
-- **Files:** `apps/ai-service/ai_service/corpus/telemetry.py`, `apps/ai-service/ai_service/corpus/artifacts.py`, `apps/ai-service/ai_service/corpus/` (README note), `apps/ai-service/tests/test_corpus_dormancy.py` (new)
-- **Action:** Verify no production code path imports `corpus/telemetry.py` or `corpus/artifacts.py` anymore (test scans imports across `agents/`, `api/`, engines). Retain files as Phase-3 calibration history with a header note marking them **dormant — v0.2 mocks, not used at runtime**; learner-context corpus stays (agents still need learner context). Disposes v0.2's G-5-class dead-code risk deliberately.
-- **Verify:** `pnpm ai:test` — test_corpus_dormancy green (zero runtime importers); suite otherwise unchanged
-
-### Wave 2: Client plumbing + design primitives (parallel — no shared files)
-
-#### Task 6-2-01: Sandbox build-panel engine client (run/test-only — no raw shell relay)
-- **Persona:** frontend-engineer — **REQ:** REQ-3-008
-- **Files:** `apps/web/hooks/use-sandbox-session.ts` (new), `apps/web/lib/engine-client.ts` (new), `apps/web/.env.example` (update)
-- **Action:** `engine-client.ts`: typed fetch client for `/v1/sandboxes` (create/destroy — learner_id from the v0.3 mock session constant, allowlisted server-side per G-5), `/v1/sandboxes/{id}/files` (workspace CRUD), `/v1/sandboxes/{id}/exec` (run/test), `/v1/variants`, `/v1/assessment/grade`, `/v1/telemetry/traces`, `/v1/defense/*`; base `NEXT_PUBLIC_AI_SERVICE_URL`. `use-sandbox-session.ts`: create sandbox+variant on task open → destroy on unmount (idempotent cleanup, AbortController pattern); 503 pool-full → user-facing "environment busy, retry" (D-032); 403/429 abuse-control surfaced honestly (G-5). **CUT-2 (G-8): NO raw interactive WS terminal relay (keystroke-level stdin/stdout) in v0.3** — the credential pipeline needs *process events* (from Run/Test + file edits), not a live shell; the interactive xterm relay is the most fragile real-time piece and is deferred to v0.4. The build panel is a **Run/Test output viewer** (exec results + telemetry pulse render), not an interactive shell. `@xterm/xterm` is therefore NOT a dependency in v0.3.
-- **Verify:** `pnpm install && pnpm typecheck` pass; hook unmount destroys the sandbox (manual probe: `curl localhost:8420/v1/sandboxes` shows count drop after navigation); RUN/TEST buttons produce streamed output + telemetry events in the trace
-
-#### Task 6-2-02: New design primitives
-- **Persona:** design-system-engineer — **REQ:** REQ-3-008
-- **Files:** `packages/ui/src/primitives/terminal-frame.tsx` (new), `packages/ui/src/primitives/mic-control.tsx` (new), `packages/ui/src/primitives/grade-badge.tsx` (new), `packages/ui/src/primitives/telemetry-status.tsx` (new), `packages/ui/src/primitives/transcript-viewer.tsx` (new), `packages/ui/src/primitives/index.ts` (update), `packages/ui/src/index.ts` (update)
-- **Action:** Token-driven primitives: TerminalFrame (CUT-2: a read-only exec-output viewer chrome — streams Run/Test results, NOT an interactive shell), MicControl (record/stop with consent state + no-mic fallback state, MediaRecorder permission UX), GradeBadge (verdict rendering), TelemetryStatus (live event pulse / disconnected indicator), TranscriptViewer (examiner/learner turn list). Dark mode + WCAG AA; stories for each.
-- **Verify:** primitives import from `@nextcraft/ui`; Storybook stories render dark + light; `pnpm build` (ui package) passes
-
-#### Task 6-2-03: Defense TS types
-- **Persona:** data-engineer — **REQ:** REQ-3-008
-- **Files:** `packages/types/defense.ts` (new), `packages/types/index.ts` (update)
-- **Action:** TS `DefenseSession`, `DefenseTurn`, `IntegritySignal`, `Verdict` mirroring P5 Python models (cross-referencing header).
-- **Verify:** `pnpm typecheck` passes
-
-### Wave 3: Real build surface (depends on Wave 2)
-
-#### Task 6-3-01: Sandbox mockup → real in-browser IDE
-- **Persona:** frontend-engineer — **REQ:** REQ-3-008
-- **Files:** `apps/web/app/(learner)/build/[competencyId]/page.tsx` (rewrite), `apps/web/components/learner/sandbox-terminal.tsx` (new), `apps/web/components/learner/file-tree.tsx` (new), `apps/web/components/learner/run-controls.tsx` (new), `apps/web/components/learner/lab-feedback-panel.tsx` (update: live trace)
-- **Action:** Replace the mockup with the real build environment (A-103, CUT-2): file tree (HTTP CRUD into the sandbox workdir via `/v1/sandboxes/{id}/files` routes added to api/sandboxes — read/write/list workspace files), syntax-highlight editor (existing), **Run**/**Test** buttons (exec in sandbox; results stream to a read-only TerminalFrame output panel — no interactive shell), starter files from the P4 variant scaffold. Lab panel posts `learner_id+task_id` → streams Lab feedback over the **live** trace (no scenario IDs). Telemetry sidebar shows live TelemetryStatus. Pool-full 503 → busy state with retry; 403/429 surfaced.
-- **Verify:** with ai-service up: open `/build/comp-01` → variant statement + starter files load → edit a file → **Run** executes the command in-sandbox and output renders in the panel → **Test** runs the test suite in-sandbox → Lab panel streams digest-derived feedback → telemetry status shows live events. Manual probe documented; `pnpm typecheck` green
-
-### Wave 4: Live defense + grading surfaces (depends on Waves 2-3)
-
-#### Task 6-4-01: Assessment mockup → live defense + live grading
-- **Persona:** frontend-engineer — **REQ:** REQ-3-008
-- **Files:** `apps/web/app/(learner)/defend/[competencyId]/page.tsx` (rewrite), `apps/web/components/learner/defense-session.tsx` (new), `apps/web/components/learner/assessor-results-panel.tsx` (update), `apps/web/components/learner/proctor-banner.tsx` (update), `apps/web/components/learner/oral-defense-interface.tsx` (rewrite or remove)
-- **Action:** Real assessment flow: **Start Defense** → POST `/v1/defense/start` → examiner question streams → learner answers via MicControl (MediaRecorder webm/opus → multipart POST) with typed fallback when mic denied or `provider=browser` (native `SpeechRecognition`/`speechSynthesis` path per fallback descriptor) → follow-ups stream → **Finish** → verdict + integrity signals panel (TranscriptViewer, GradeBadge) + **Grade My Work** → POST `/v1/assessment/grade` → structured rubric bars render. Proctor banner reads signals for task_id. Loading + error states throughout; no mock defense data remains in the learner path.
-- **Verify:** with ai-service up: full defense loop runs in-browser (typed fallback acceptable in CI-less manual probe; mic path exercised manually with permission granted); grade panel renders real rubric scores; `pnpm typecheck` green
-
-### Wave 5: End-to-end verification (depends on Waves 3-4)
-
-#### Task 6-5-01: Full learner-path E2E probe + green builds
-- **Persona:** backend-engineer — **REQ:** REQ-3-007, REQ-3-008
-- **Files:** `apps/ai-service/tests/api/test_e2e_credential_flow.py` (new), `apps/ai-service/README.md` (update: E2E probe doc)
-- **Action:** Endpoint-level E2E (mock LLM/voice providers, real engines): create variant → create sandbox with task_id → ingest trace events via real sandbox exec → POST grade → start defense (typed answers) → finish → assert: trace persisted, grade stored + digest-linked, defense transcript + signals stored, Proctor/Assessor endpoints serve them. No corpus fixture anywhere in the flow (AST-asserted). Run `pnpm build` + `pnpm typecheck` + full `pnpm ai:test` at repo root; fix all failures before phase ship.
-- **Verify:** `pnpm ai:test` green incl. test_e2e_credential_flow; `pnpm build` + `pnpm typecheck` green; README E2E probe section documents the manual browser pass
-
-### Must-Haves (Phase 6)
-- [ ] Lab/Assessor/Proctor operate on real inputs with **no mock fallback in the learner path** (AST-verified: no corpus telemetry/artifact/proctor imports in production paths)
-- [ ] Learner builds in-browser for real (CUT-2): Run/Test buttons execute in a namespace sandbox and stream output to a read-only panel; file tree CRUD works; starter files come from the learner's variant scaffold
-- [ ] Live telemetry: build activity streams to ai-service and the sidebar shows live status (TelemetryStatus); trace persisted in SQLite
-- [ ] Live defense: start → answer (mic or typed fallback) → examiner follow-ups → finish → transcript + integrity signals + verdict rendered; browser-native path works with no server voice key
-- [ ] Live grading: grade request returns structured rubric scores computed from the real trace digest; grade panel renders them
-- [ ] 503 pool-full surfaced honestly in UI; navigating away destroys the sandbox (no leaked sandboxes — `GET /v1/sandboxes` manual probe)
-- [ ] Examiner remains protocol-clean (voice only via `VoiceProvider`); module boundary rules hold across all new code
-- [ ] `pnpm build` and `pnpm typecheck` pass; full `pnpm ai:test` green; no cloud/voice calls in any automated test
-- [ ] Release-note input (for P7): v0.3 ships real engines; **identity/age-gating (KYC) remains deferred — age-gating is still a visual mockup** (A-110); sandbox scope is coding-IDE only (design tool/simulation deferred to v0.4, D-025)
+- **Task 6-1-01** (lead-developer → ci-review personas): multi-persona review of the full milestone branch diff (all phases — workflows correctness, Dockerfile hardening, deb packaging, CLI surface, docs accuracy); security-auditor confirms secrets policy end-to-end (no token in any layer/asset/workflow), image non-root, deb postinst advisory-only.
+- **Task 6-2-01** (ci-audit): reconstruction test (git log ↔ .ciagent/ files), file/branch/commit discipline, tag hygiene; critical fixes in-phase.
+- **Task 6-2-02** (lead-developer → ci-ship): merge milestone → main; tag the milestone release (final v0.7.x phase tag = v0.7.6); Gitea release with full summary + the complete asset matrix (x64/arm64 binaries + checksums + 2 debs) + registry image tags; delete milestone branches; mark REQ-8-001..005 complete; clear checkpoint.
 
 ---
 
-## Phase 7: Final Review + Ship (no planned tasks)
+## Must-Haves (per phase — concrete, falsifiable, test-linked)
 
-Orchestrated by the SHIP stage, not this plan: multi-persona code review (correctness, testing, module boundaries, secrets hygiene — keys absent from code/logs/commits/errors, localhost-only CORS, no PII in prompts), project health audit (reconstruction, .ciagent/ discipline, branch/commit hygiene), then merge milestone → main, tag the final v0.2.x patch, create the Gitea release, mark all 8 v0.3 requirements complete.
+### Phase 1
 
-**Release-note honesty:** the release note must state (a) Lab/Assessor/Proctor now run on real engine inputs (v0.2 mock-input caveat retired), (b) sandbox scope = coding IDE only — design tool + simulation environments deferred to v0.4 (D-025), (c) identity/age-gating (KYC) deferred per founder directive — age-gating remains the v0.1 visual flow mockup; abuse control (per-learner sandbox caps + server-side learner allowlist, G-5) ships in place of auth (A-110), (d) voice runs mock-first with browser-native fallback — real server STT/TTS deferred to v0.4 (CUT-1), (e) sandbox resource limits are partially enforced (memory/CPU/wall-clock kernel-enforced via rlimits; per-sandbox pids + hard disk quota are NOT — mitigated by a workdir-size sweep and per-learner caps; full enforcement requires cgroup delegation, deferred to the post-MVP containerd backend, D-024/G-1/G-2).
+- **MH-1a**: Three runners visible + idle at org level (`/org/coreci/settings/actions/runners`) — named nc-runner-node/python/release, hybrid labels declared per the R-3 map; registration token reset requested from founder after green fleet.
+- **MH-1b**: `ci.yaml` green on a fresh push — node lane (lint+typecheck via per-workspace filters, web:test, cli:test) + python lane (bootstrap/lint/typecheck/FAST test) both observed in the Actions tab.
+- **MH-1c**: `hello.yaml` dispatch green × 3 labels (node/python/ubuntu-latest) — the fleet proof.
+- **MH-1d**: `release.yaml` exercised via the G-203 temporary rc tag on the phase branch — workflow observed building binary + checksum and attaching them green; the phase ship release (v0.7.1) carries the same machine-made assets.
+- **MH-1e**: pre-commit proven both directions — blocks a deliberately broken lint file, passes a clean tree; config is local-only (no network hooks); the no-toolbox skip path is documented in README dev (G-209).
+- **MH-1f**: Secrets audit clean — grep-verifiable: no token/credential in any committed file; CT root password used once, founder rotation requested as a Wave 1-1 completion condition and confirmed or escalated (G-206); workflows carry no shell-env token echoes.
 
-**Secrets-hygiene checklist (P7):** `.ciagent/.env.secrets` gitignored and never committed; `AI_VOICE_API_KEY` / `AI_TUTOR_API_KEY` referenced only via env; SQLite DBs + sandbox dirs gitignored; no keys in logs, error messages, or test fixtures.
+### Phase 2
 
-**Disposal checks (G-5 class):** v0.2 dormant corpus files carry the dormant-header note (Task 6-1-04); any now-unused mock-data exports for the old sandbox/defense mockups (e.g. `aiTutorResponses`-class leftovers) must be removed or deprecated by review.
+- **MH-2a**: Image builds (local + release lane) and pushes to `git.coreci.dev/coreci/nextcraft` under the phase tag + `latest`; `/v2/` manifest probe-verified after push.
+- **MH-2b**: Smoke gate green with the five pinned assertions (G-204) — container start → /health 200 → `GET /` HTML with known marker → degrade notice in logs → 503 with remediation on env-create → clean stop; a broken image fails the release job.
+- **MH-2c**: Degrade is honest — capability probe is a real userns attempt (not an env-var guess); degraded boot notice logged once with remediation text; env-create rejected 503 with remediation payload; real userns path unchanged (userns suites green locally).
+- **MH-2d**: In-container CLI semantics — doctor/verify/guide work; bootstrap/deploy/dev refuse with remediation (exit 1); all pinned by tests.
+- **MH-2e**: Image hygiene — non-root runtime, `.dockerignore` excludes `.env*` + `.ciagent/`, no build toolchain in the final layer (auditor-verified).
 
----
+### Phase 3
+
+- **MH-3a**: arm64 binary builds per the G-201 ladder — QEMU-free cross-arch SEA if the probe passes; binfmt+qemu full build if not; x64-only deferral (recorded) if binfmt is impossible — the ladder's outcome is recorded either way, `--version` reports the stamped tag under emulation, sha256 sidecar matches.
+- **MH-3b**: Both debs build + install in fresh debian containers — `nextcraft --version` + advisory doctor run; postinst never fails dpkg (proven with missing-Recommends environment).
+- **MH-3c**: install.sh arch-resolve — x86_64 → x64 asset, aarch64 → arm64 asset, checksum + version gates byte-identical; fixture-server tests extended to both arches.
+- **MH-3d**: v0.7.3 release carries the complete asset matrix: 2 binaries + 2 checksums + 2 debs (6 assets), all verified — or the recorded G-201 deferral outcome (x64-only) with the arm64 rows explicitly marked deferred, never silently missing.
+
+### Phase 4
+
+- **MH-4a**: Doctor reports the detected channel (container/deb/binary) with the channel-correct next-step line, in fixture tests covering all three.
+- **MH-4b**: `nextcraft guide` renders offline (no network calls — asserted), topics route (`guide docker|deb|troubleshooting|deploy`), exit-code contract intact.
+- **MH-4c**: Refusals honest — in-container bootstrap/deploy/dev exit 1 with remediation text (pinned by tests).
+- **MH-4d**: Both new E2Es (docker, deb) exist env-gated, green when run; the binary-channel E2E still green; guide ↔ runbook parity test green.
+
+### Phase 5
+
+- **MH-5a**: Runbook covers all three channels (first-install + upgrade each), the upgrade matrix, HAProxy/systemd recipes, and the four troubleshooting tables — every recipe carries an evidence pointer (test name / workflow job / live probe).
+- **MH-5b**: Parity test green — `nextcraft guide` content and the runbook agree section-by-section.
+- **MH-5c**: README quickstart lists all three channels accurately; milestone history updated.
+
+### Phase 6
+
+- **MH-6a**: Multi-persona review of the full diff clean (P0s fixed in-phase); secrets policy confirmed end-to-end by security-auditor.
+- **MH-6b**: ci-audit reconstruction + discipline checks green.
+- **MH-6c**: Milestone shipped — v0.7.6 tagged, merged to main, release carries the full asset matrix + image tags, REQ-8-001..005 complete, branches deleted, checkpoint cleared.
+
+## Milestone Must-Haves
+
+- **MH-M1**: All five requirements complete per their REQUIREMENTS.md rows (REQ-8-001..005).
+- **MH-M2**: A push to any branch runs lint + typecheck + fast tests on the runner fleet, green (the release-consistency rail the founder asked for).
+- **MH-M3**: Every phase release from v0.7.1 onward is machine-made the same way: tag push → workflow builds → binary + checksum (+ image from P2, + arm64/deb from P3) attached + registry pushed.
+- **MH-M4**: Each channel takes a fresh Debian server to a running verified stack: docker run → /health + HTML; dpkg -i → doctor → deploy --service; install.sh → deploy --service (proven by E2E/workflow smoke or live-box evidence).
+- **MH-M5**: The admin runbook exists as one entry point with per-channel recipes and upgrade paths, every recipe evidence-backed; `nextcraft guide` mirrors it offline.
+- **MH-M6**: Zero silent failures: honest sandbox degrade (loud notice + 503 remediation), honest in-container refusals, honest channel reporting in doctor — the v0.5+ honesty pattern extended to distribution.
+
+## Risks
+
+- **CT 113 single point of failure** (fleet host) — mitigation: compose + config + cron committed as documentation-in-repo (the runbook reproduces the fleet from scratch); founder access path recorded.
+- **Registration token expiry mid-P1** — mitigation: bring-up is Wave 1-1's first task; the token's job (3 registrations) completes before anything else depends on it; reset requested immediately after.
+- **Cache-server reachability from job containers** (R-5) — mitigation: cache.host + published ports verified at bring-up; volume-mounted pnpm/pip stores are the deterministic fallback (R-12).
+- **actions/checkout needs CT egress to github.com** (R-8) — mitigation: probe at 1-1-01; raw git fetch steps as the fallback lane.
+- **SEA blob cross-arch behavior** (R-26) — mitigation: probe-first in P3; binfmt fallback scoped to blob generation.
+- **Registry push auth failure** (REGISTRY_TOKEN 401/403 on self-serve) — mitigation: founder UI fallback (escalation commits, P2 marks push step as the only blocked piece; ship still completes).
+- **docker.io pulls on the release lane** (R-21 note) — bookworm ships docker.io; accepted for v0.8, pre-baked release image documented as the future fix.
+- **Runner 3.x config drift** (cache.host/bind_workdir/health_check keys) — mitigation: `gitea-runner generate-config` is the authority at bring-up (R-9 risk 9).
+- **Image size growth over releases** (~400-500MB budget, R-18) — mitigation: budget asserted in the smoke gate; multi-stage keeps toolchains out of the runtime layer.
+- **Existing v0.4 binary pipeline regression** — mitigation: x64 path byte-identical (checksums + install.sh gates unchanged, pinned by the existing fixture tests).
 
 ## User-Facing Surface
 
-The primary user-facing surface is the **learner build + defend flow** at `http://localhost:3000`, backed by the real engines in ai-service at `http://localhost:8420`:
+1. **Gitea Actions tab** — every push runs the lanes; every tag builds a release (visible, green, machine-made).
+2. **`docker run git.coreci.dev/coreci/nextcraft`** — the whole stack, one port, /health, honest degrade notice.
+3. **Release downloads** — x64 + arm64 binaries, checksums, .deb packages — every release.
+4. **`nextcraft guide`** — offline man-page for admins: channel recipes, upgrade paths, troubleshooting.
+5. **`nextcraft doctor`** — channel-aware (container/deb/binary) with the right next-step line.
+6. **`deploy/README.md`** — the one-entry-point admin runbook.
+7. **Pre-commit** (opt-in for devs) — local hygiene mirroring CI.
 
-- `/dashboard` — AI tutor chat (Coach/Tutor, streaming) + Mentor panel (unchanged from v0.2)
-- `/learn/[competencyId]` — byte viewer with streaming Tutor explanations (unchanged)
-- `/build/[competencyId]` — **real in-browser build environment**: file tree, syntax editor, **Run/Test buttons that execute in a namespace sandbox and stream output to a read-only panel** (CUT-2 — no interactive shell), live telemetry status, live Lab feedback, per-learner variant task statement
-- `/defend/[competencyId]` — **live oral defense + live grading**: Examiner voice/typed dialogue, transcript + integrity signals, real rubric scores from the process trace
+## Happy Path (end-to-end, written BEFORE execute)
 
-The marketplace, employer, and admin surfaces are unchanged from v0.1/v0.2.
-
-## Happy Path
-
-1. Learner opens `/build/comp-01` → a per-learner **variant statement** and starter files load; a namespace sandbox is created for the session
-2. Learner edits files in the tree and clicks **Run**/**Test** → commands execute in the sandbox and real output renders in the build panel; the telemetry sidebar pulses as events stream to ai-service and persist in SQLite
-3. The Lab panel streams feedback derived from the **live trace digest** (real commands, real failures)
-4. Learner opens `/defend/comp-01` → **Start Defense**: the Examiner streams an opening question ("Walk me through your build — why did you structure it this way?")
-5. Learner answers by voice (mic consent → MediaRecorder → STT) or typed fallback → examiner follow-ups probe the trace ("You hit three test failures before passing — what changed?"); TTS plays examiner audio (or browser speech in fallback)
-6. Learner finishes the defense → transcript + integrity signals appear; verdict renders in a GradeBadge
-7. Learner clicks **Grade My Work** → the grading engine computes the digest from the real trace, rubric-scores it, and the panel renders per-criterion bars + strengths/gaps/verdict
-8. Proctor banner shows integrity signals from the live trace + defense in coaching tone; Mentor panel on `/dashboard` can narrate the real outcome
-9. Navigating away destroys the sandbox (pool slot freed); killing ai-service shows inline error + retry states on every panel, with no crashes
+1. **Founder/rails:** tag push → release workflow builds binary + checksum, attaches to the release, pushes the image (from P2), adds arm64 + debs (from P3) — no human touches an artifact.
+2. **Admin, docker channel:** fresh Debian box → `docker run -d -p 8420:8420 -v nextcraft-state:/home/nextcraft/.nextcraft git.coreci.dev/coreci/nextcraft:v0.7.x` → /health green, site HTML at :8420, boot notice explains the sandbox degrade + the privileged variant pointer.
+3. **Admin, deb channel:** `dpkg -i nextcraft_0.7.x_amd64.deb` → advisory doctor → `nextcraft deploy --service` → verified single-port stack.
+4. **Admin, binary channel:** `curl … install.sh | sh` → `nextcraft doctor` → `nextcraft deploy --service` (the existing path, unchanged).
+5. **Admin, any channel, stuck:** `nextcraft guide` → offline recipe + troubleshooting pointers → resolved or forge link.
+6. **Upgrades:** docker = pull + recreate; deb = new deb + deploy --service; binary = install.sh re-run — all idempotent per D-071.
+7. **Developer:** clone → pre-commit install → push → CI lanes green before review.
 
 ## UX Acceptance Criteria
 
-1. Run/Test output visibly reflects the real sandbox execution (command round-trip to the sandbox, real stdout/stderr), not a replay animation
-2. The learner path contains **no mock engine data** — scenarios, canned artifacts, and scripted defense transcripts from v0.2 are gone from runtime
-3. Variant statements visibly differ between two learner sessions on the same competency
-4. Mic permission flow is graceful: consent prompt, recording indicator, no-mic/typed fallback, and browser-native speech path when no server voice key is configured
-5. Defense transcript renders turn-by-turn with latency shown; integrity signals render in coaching (supportive) tone
-6. Grade results render as structured per-criterion bars with verdict, from the real trace — not from final-output-only heuristics
-7. Pool-full (503) shows an honest "environment busy — retry" state; navigation/unmount destroys sandboxes with no leaks
-8. When ai-service is unreachable: inline error + retry on every panel — no crashes, no console errors, no blank UI
-9. All new UI uses design tokens, supports dark mode, meets WCAG AA contrast, responsive at 375px / 768px / 1280px
-10. `pnpm build` and `pnpm typecheck` pass with zero errors; `pnpm ai:test` green cloud-free and voice-key-free
+1. No silent failures anywhere in the new surface: image can't sandbox → loud notice + 503 remediation; in-container miscommands refuse with remediation; doctor names the channel and the correct next step.
+2. Every channel ends at the same place: doctor/verify green on a running stack — the admin doesn't need to know the internals.
+3. Releases are uniform and machine-made: same asset matrix, same gates (checksum + version), no manual artifact steps.
+4. The guide works offline and agrees with the runbook (parity-tested — divergence is a test failure, not a doc drift).
+5. Docs match reality: every recipe carries an evidence pointer; stale docs are a P0 at final review, not a footnote.

.ciagent/PROJECT.md

@@ -8,45 +8,207 @@ Nextcraft is an AI-native outcome school where graduates prove what they can bui
 
 ---
 
-## Current Milestone: v0.3 — Credential Engines
+## Hotfix Round (2026-09-21, founder directive)
 
-**Scope:** Replace v0.2's mock engine inputs with real credential engines. Build the sandbox fabric (sandboxed IDE / design tool / simulation), the live in-environment build-telemetry pipeline, the process-trace grading engine, per-learner variant task generation, and the oral/voice defense with AI examiner. Lab/Assessor/Proctor agents move from mock inputs to real engine inputs; the six tutor agents operate on authentic telemetry and artifacts.
+**v0.4.6 — deploy-static-404 + dev experience.** Third attempt at the site-down issue (domain root → API JSON 404). Root cause found by host probe (10.0.0.105): the deployed uvicorn ran mount-less — `apps/web/out` was never built on the host, `dev -d` auto-wiring silently skipped `AI_WEB_STATIC_DIR`, node/pnpm were invisible to non-interactive shells, and NOTHING detected the mount-less boot. Founder directive: fix the deploy experience so the one-liner install handles all of it — smooth first run, upgrades, and reboot persistence. Delivered: `nextcraft deploy` (clone/update → install → venv → export build → restart → verify, idempotent), `deploy --service` (generated systemd unit, enabled), toolchain discovery (PATH → nvm → PNPM_HOME → corepack; prefix carries node+pnpm dirs for split installs), loud mount-less boot warning, `verify` live mount probe (GET / must be HTML), install.sh next-steps rewritten. Deployed live on the host via the new command; site 200, service active+enabled.
+
+**v0.4.7 — pre-public hardening (the 4 P1 flags).** WS ingest HMAC tokens (grading input no longer LAN-poisonable; manager mints into NC_INGEST_URL, endpoint verifies, per-boot secret default), nonce+counter defense-id mint (same-ms collision → permanent 500 closed), browser-mode SR/TTS client implementation (the descriptor's v0.5 contract finally honored — recognizeOnce/speakText pure module + defense-session wiring + honest unsupported state), 8 module pins. All P1 flags from the v0.5 final review are now closed; the recorded pre-public hardening backlog is empty.
+
+---
+
+## Milestone v0.8 — Ship Anywhere (ACTIVE, Feature, started 2026-09-27)
+
+**Scope (founder directive 2026-09-26, options 1–4 confirmed + scope decisions answered 2026-09-26/27):** Release and deployment guides for admins. nextcraft must be installable on any Debian-based Linux server, via every mainstream channel, with release consistency enforced by automation:
+
+1. **Docker container** (Option 1): packaged image with all dependencies pre-loaded, built and uploaded to the Gitea container registry on every phase release
+2. **Release binaries** (Option 2, extends the existing v0.4 line): the CLI published as binaries in every release's downloads — x64 (existing) plus arm64, plus .deb packages
+3. **CLI full suite** (Option 3): the CLI contains the full application suite for easy onboarding — one binary takes an admin zero → running
+4. **Release consistency** (Option 4): pre-commit hooks + Gitea Actions pipelines so every release is made the same way
+
+**Founder scope decisions (2026-09-26/27):** deb + arm64 both added (packaging breadth); docker container unprivileged-by-default with honest sandbox degrade (userns conflict documented, privileged variant documented); Gitea act_runner stood up by this milestone on founder-provided LXC CT 113; one milestone, 6 phases (P0 + P1–P5 + P6 final). Three org-level runners on CT 113 as docker containers (gitea/act_runner, sibling-container mode, host docker.sock, hybrid labels ubuntu-latest + node/python/release).
+
+**Out of scope:** Windows/macOS targets, apt repository hosting (debs ship as release assets), Helm/K8s deployment, Postgres migration, browser E2E tooling.
+
+**Success (milestone-level):** `docker run` / `.deb install` / one-liner binary each take a fresh Debian server to a running verified stack; every release carries binary + checksum + deb + image tag automatically; a push to any branch runs lint/typecheck/tests on the runner fleet; admins have a single deploy guide covering all channels with upgrade + troubleshooting paths.
+
+## Clarify decisions (D-063+, CLARIFY stage full autonomy, 2026-09-27)
+
+| ID | Decision | Rationale | Confidence |
+|----|-----------|-----------|------------|
+| D-063 | CI push lane = lint + typecheck + **fast lanes only**: `ai:test:fast` (`-m "not real_server and not userns"`), default `web:test` + `cli:test` (E2E stays env-gated out). `real_server`/`userns` NEVER run in job containers. | `userns` is blocked by docker's default seccomp in the sibling-container runners (nested `unshare --user` fails — infeasible, not merely slow); `real_server` is feasible (plain uvicorn processes) but the locked spec wording is "pytest fast lane" and push feedback stays minutes-scale; both lanes remain local/verify-lane surfaces. The CLI E2E (900s real bootstrap) is already env-gated out of `cli:test` (D-055) and stays out | 0.85 |
+| D-064 | Tag-triggered Actions workflow is the **exclusive owner** of release assets + registry push (builds x64/arm64 binaries, checksums, debs from the tag checkout; consumes Actions secrets `GITEA_TOKEN`/`REGISTRY_TOKEN` set via the self-serve PUT mechanism). The local ship path stops calling `scripts/release-assets.sh` once the workflow is green; the script remains as the manual fallback (its .env-only token resolution unchanged). | Exclusive ownership kills the double-attach race (ship workflow + tag trigger would both upload the same asset names); the job must build from a clean tag checkout anyway (dist/ artifacts don't exist in the job), so the script's attach-what-exists logic can't serve the workflow; "release consistency enforced by automation" (founder Option 4) means the pipeline, not the founder's box, is the release maker | 0.75 |
+| D-065 | Image = `git.coreci.dev/coreci/nextcraft`, tags = the release semver (`v0.7.x`) on every phase ship + `latest` moved to the newest release. No per-push/branch tags. Admin guides pin semver; `latest` is a convenience alias only. | The Gitea registry is owner/repo-scoped (`{instance}/{owner}/{repo}`) — no other image name is addressable, so the naming question has exactly one answer; per-push tags would churn the 32 GB runner disk for zero admin value while the release-consistency scope is phase releases | 0.85 |
+| D-066 | The runtime image embeds the CLI binary (`/usr/local/bin/nextcraft`): `docker exec` gives admins in-container `doctor`/`verify`/`guide`; `bootstrap`/`deploy`/`dev` detect the container env and refuse honestly, pointing at the docker-channel paths. | REQ-8-004's "detects container env + suggests volume/privileged facts" is only truthful from inside the container (uid_map/seccomp/userns reality lives there — a host-side CLI cannot probe it without knowing the container name); ~117 MB on an image already carrying a venv + static export is acceptable; refusing beats repo-surgery-in-container (git clone + rebuild inside an immutable image is the anti-pattern the docker channel exists to remove) | 0.80 |
+| D-067 | deb = CLI binary at `/usr/bin/nextcraft` + package docs, nothing else. NO systemd unit in the deb — `deploy --service` owns service-unit generation (it bakes the real clone + binary paths; a deb unit would be stale/wrong). No proxy config fragments (HAProxy recipes are per-box, live in the deploy guide). postinst runs `nextcraft doctor` best-effort as an **advisory** summary (output printed, exit never fails the dpkg transaction) + prints next-steps (`doctor` → `deploy --service`). | The deb packages the CLI, not the stack — the unit's paths only exist after deploy chooses a clone dir; postinst failing on missing node/pnpm would brick unattended installs while advisory doctor output still tells the admin what to fix (honest-loud, never blocking — the install.sh degradation pattern) | 0.75 |
+| D-068 | Degrade detection = **capability probe**, not markers: at boot + per environment-create the backend attempts a real `unshare --user --map-root-user` (the proven `tests/helpers/userns.py` pattern promoted into the sandbox module); `/.dockerenv` + an `NC_CONTAINER=1` entrypoint var only flavor the remediation text. Degrade semantics: learner environment creation **rejects honestly** (503 + pointer to the documented privileged/seccomp variant) + loud boot notice + doctor surfaces the degraded capability; chat/agents/grading keep working. This supersedes A-101's cwd-jail fallback for deployed schools. | The probe is the truth source — `/.dockerenv` says "docker" but not "userns blocked" (a privileged container passes userns and must NOT degrade; a non-docker host with userns disabled must); unisolated learner code would run as the service user next to provider keys + network — the namespace fabric exists precisely to prevent that, so the A-101 fallback (founder-box convenience) is unacceptable for untrusted multi-learner deployments; reject-with-remediation is the honest degrade | 0.70 |
+| D-069 | arm64 = **cross-build on the x64 runner, no QEMU for the build**: the SEA pipeline is arch-agnostic file surgery (esbuild bundle + postject into an arm64 node base binary fetched as a build input); x64 + arm64 binaries and debs build in one release job in minutes. QEMU binfmt (if registered on CT 113) adds an optional `--version` smoke of the arm64 binary; `dpkg-deb` never executes its payload, so the deb needs no emulation. No multi-arch docker image in v0.8 (spec scope is binaries + debs; image stays amd64). RESEARCH verifies the arm64 node base + binfmt availability. | Emulated builds are the slow path and unnecessary: SEA injection never runs the target binary; the only execution need is a smoke, which binfmt provides opportunistically; multi-arch manifests would pull image-arm64 into a scope the spec never asked for | 0.70 |
+| D-070 | pre-commit = ONE root `.pre-commit-config.yaml` for the whole monorepo, directory-scoped (ruff on Python paths, eslint/tsc via workspace-scoped invocations), local-only, no network at hook run. On boxes without the toolchain, hooks **fail loudly** — never silently skip; `--no-verify` is the visible deliberate bypass and CI is the authoritative backstop. | A silently-skipped hook lies about release consistency (Option 4's whole point); pre-commit is inherently a repo-root single config — per-workspace configs buy nothing; CI remains the enforcement gate so a bypassed local hook cannot ship unlinted code | 0.80 |
+| D-071 | Docker-channel upgrade = `docker pull <tag>` + **recreate** the container (state persists via the `~/.nextcraft` volume) — `deploy`/`bootstrap` never run in-container (D-066 refuse). Binary channel = re-run install.sh + `deploy --service`; deb channel = `dpkg -i` the new deb + `deploy --service` (both idempotent). doctor/guide describe the detected channel's upgrade path. | The image is immutable — deploy-from-repo inside a container is meaningless by construction; the other two channels keep the v0.4.6 idempotent deploy as their upgrade rail (proven on the live box) | 0.85 |
+| D-072 | `nextcraft guide` = **offline-first embedded text** (man-page style): channel-aware sections checked into the CLI source (mirrored from deploy/README.md at build time), zero runtime fetches; forge URLs print as pointers to the living runbook. | Fresh-box and degraded installs (no network, no clone) are exactly when guidance is needed; the binary is self-contained by design (SEA) — embedding honors that; runtime fetching would make the guide fail precisely on broken boxes | 0.80 |
+
+## v0.8 research conclusions (Phase 0 RESEARCH, 2026-09-27)
+
+Full evidence + concrete commands live in `.ciagent/RESEARCH.md` (R-1..R-32); architecture in ARCHITECTURE.md's "v0.8 Distribution & Release Architecture" section. Brief conclusions:
+
+1. **Runner image = `gitea/runner:3`** — Docker Hub's `gitea/act_runner` is deprecated/renamed; runner 3.x needs Gitea ≥1.21 (instance probe-verified at 1.26.1). Basic flavour + host docker.sock = exactly sibling mode.
+2. **3 containers, one per lane, each with its OWN `/data` volume** (`.runner` registration file — shared = lock refusal + identity loss). Registration token via env at bring-up only (founder chat-provided, reset after fleet green, never in any repo file). Org-level scope comes from the token itself.
+3. **Labels via `GITEA_RUNNER_LABELS` env** (passed to both register + daemon): `node:docker://node:24-bookworm`, `python:docker://python:3.11-bookworm`, `release:docker://node:24-bookworm`, `ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest`. Unmatched `runs-on` silently runs on a default image — always pin our labels.
+4. **Capacity 1 per runner** (config default; also bounds docker subnet consumption). Fleet concurrency = 3.
+5. **Cache requires `cache.host` + published port** on dockerized runners (per-job networks make the auto-detected cache address unreachable — actions/cache ETIMEDOUTs otherwise); 32 GB guarded by cache caps + health_check disk floor + host prune cron. `actions/cache@v4` works on runner 3.x (cache v2 API, stock action self-patched).
+6. **Sibling-mode path alignment NOT needed for our jobs** (no bind_workdir; `docker build` TARS context over the API); documented as the gotcha if a future workflow bind-mounts.
+7. **Push lane = repo's own scripts, no turbo lint wholesale** (it pulls venv-dependent ai-service tasks): node lane (corepack pnpm 12.3.4, eslint+tsc per TS workspace, web/cli node:test) + python lane (bootstrap.sh venv, ruff, mypy, FAST=1 test.sh). D-063's fast-only rule is both policy and physical (docker default seccomp blocks nested unshare). ubuntu-latest lane = dispatch verification only.
+8. **Release lane = tag-triggered exclusive owner**: builds from the tag checkout, stamps with `gitea.ref_name`, attaches assets via the same REST API scripts/release-assets.sh uses (NOT actions/upload-artifact); reuses the API in-workflow, script untouched as manual fallback (.env-only token resolution preserved).
+9. **Automatic job GITEA_TOKEN cannot publish packages (upstream-confirmed)** — registry push needs the `REGISTRY_TOKEN` PAT secret (self-serve PUT first, founder UI fallback). `docker/build-push-action` unnecessary: plain login+build+push for a single-arch amd64 image.
+10. **Dockerfile**: web-export stage (NEXT_PUBLIC_AI_SERVICE_URL=self, build-time-only) + venv stage (prod deps) + `python:3.11-slim-bookworm` runtime (~400-500 MB incl. the ~117 MB CLI embed, D-066): non-root, urllib `/health` healthcheck (no curl in slim), `VOLUME /home/nextcraft/.nextcraft` (state root is `~/.nextcraft` by config default, env-overridable with ~-expansion), zero AI_* env at build, all keys optional at runtime (G-11).
+11. **deb**: `dpkg-deb --root-owner-group -Zxz` staging build (never executes payload — cross-arch free), Version = tag minus `v`, empty Depends + `Recommends: nodejs, python3, git, util-linux` (soft deps), postinst advisory doctor (exit 0 always), no unit, no proxy fragments (D-067).
+12. **arm64 cross-build QEMU-free**: the only arch-specific step in build-binary.mjs is `copyFileSync(process.execPath, out)` — replaced by a copy from the official arm64 node tarball (probe: nodejs.org dist 200, 30 MB); esbuild bundle + postject ELF-note injection are arch-agnostic file surgery. SEA blob cross-arch needs a P3 probe (config has no useCodeCache/useSnapshot — good sign); binfmt `--version` smoke optional per D-069.
+13. **D-068 degrade**: probe promoted verbatim from tests/helpers/userns.py into `ai_service/sandbox/capability.py`; boot notice copies the main.py G-11 warning pattern; per-create rejects 503 via a new SandboxUnavailableError arm beside the existing PoolFullError→503 (today it 500s); doctor upgrades `which unshare` to a real userns attempt. Markers only flavor text.
+14. **install.sh arch-resolve**: `x86_64`→x64, `aarch64|arm64`→arm64; sha256+version integrity gates stay byte-identical per arch.
+15. **Admin-guide structure** (REQ-8-005): per-channel chapters (docker/deb/binary) each ending in the SAME verification checklist, an upgrade matrix table (D-071 semantics), symptom/cause/fix troubleshooting tables, where-state-lives table per channel, sibling-mode accepted-risk row, SEA/corepack/cache-egress probe outcomes recorded. Ecosystem scan: Ollama installer UX, Tailscale per-channel doc skeleton, Gitea/act_runner's own dual distribution, Miniflux binary+image+deb shape.
+
+## Milestone v0.7 — Test Harness Review (COMPLETE, shipped as v0.6.6, 2026-09-26)
+
+**Scope (founder directive post-v0.6, scope decisions answered 2026-09-26):** Once v0.6 shipped, review the entire test harness — make sure the right tests are being run, make them effective, cut tests that provide no real value, review all warnings, and address all of it within this single milestone. NFR refinement-only: zero `feat:` commits (D-001 purity gate at final phase).
+
+**Baseline research (completed at phase 0, 2026-09-26):** 785 tests (671 pytest / 53 web node:test / 61 CLI node:test), all green. Coverage unmeasured anywhere. No framework-level timeouts (20-30s polling loops, 600s CLI bootstrap step). Zero pytest markers despite a real split (fast-unit vs real-uvicorn vs real-userns). Web tests outside the turbo pipeline. 1,716 warnings per pytest run (~99% from 14 `session.query()` SQLModel deprecation sites; 14 ResourceWarning sites from unclosed UploadFile/sockets/file). All 81 Python `# noqa` inert (rules not in the ruff select-set); 5 orphaned eslint-disable comments; **no ESLint exists at all** (turbo lint is a no-op for 5 of 6 packages). `recharts@2.15.4` deprecated direct dep. No Python type checker (27 inert `# type: ignore`). Stale PLAN.md counts (488/22/61 vs actual 671/53/61).
+
+**Founder scope decisions:** D-048 ESLint included; D-049 recharts 2→3 included; D-050 source-pin triage (cut trivial, keep real regression pins); D-051 mypy included.
+
+**Out of scope:** Gitea Actions CI YAML (the CIAgent verify hooks are the CI), Playwright/browser E2E tooling, new features of any kind.
+
+**Success (milestone-level):** pytest runs green with zero first-party warnings; the fast-subset (`-m fast`) completes in seconds; coverage measured and reported in all three workspaces; `turbo lint` exercises all 6 packages; all suppressions (noqa/eslint-disable/ts-ignore/type:ignore) are enforced-and-meaningful or gone; the suite is smaller (trivial tests cut) with no loss of regression value.
+
+**Clarify decisions (D-052+, CLARIFY stage full autonomy, 2026-09-26):**
+
+| ID | Decision | Rationale | Confidence |
+|----|----------|-----------|------------|
+| D-052 | Coverage tooling: **pytest-cov for ai-service; c8 for web/cli** wrapping the existing `tsx --test` runner — no vitest/nyc/istanbul, no runner swap | c8 handles tsx source maps and adds one devDep per workspace; node's `--experimental-test-coverage` mis-reports through the tsx loader; vitest adoption is a framework swap, not NFR refinement | 0.85 |
+| D-053 | Marker taxonomy: registered `fast`/`real_server`/`userns` under `--strict-markers`; **unmarked tests default to fast**; canonical fast run = `-m "not real_server and not userns"` (aliased `ai:test:fast`); `real_server`/`userns` always exclude from the fast subset | Zero-churn — no need to stamp ~600 unit tests with `fast`; the exclusion markers carry the selection; strict mode catches typo'd markers that would silently deselect | 0.85 |
+| D-054 | pytest-timeout: **`signal` method**, global 60s (comfortably above the 20-30s polling loops), conftest collection hook bumps to 180s for `real_server`/`userns`-marked tests; `@pytest.mark.timeout` for known outliers | Linux-only target makes SIGALRM safe and accurate; the thread method can't cancel blocked calls; 60s bounds a hang without false-positiving real polling | 0.80 |
+| D-055 | CLI fresh-clone E2E: **keep the 600s real bootstrap as-is** (the real path is the value), give it an explicit per-test 900s budget (600 + slack), env-gate it out of the default `cli:test` run with a dedicated `cli:test:e2e` script for the verify/ship path | A 10-minute E2E on every run is wrong for feedback loops but too valuable to cut; opt-in keeps both properties | 0.85 |
+| D-056 | filterwarnings: **`error` as the base action** (new first-party warnings fail) + a narrow enumerated allowlist of upstream ignores each scoped by exact message + emitting module (fastapi/starlette TestClient httpx warning, anyio BlockingPortal); no blanket category ignores, no ignores on `ai_service.*`; first-party ResourceWarnings fixed at source, never ignored | Error-by-default makes warning hygiene self-enforcing; module-scoped ignores cannot mask first-party regressions; after REQ-7-003 cleanups the non-ignored set is empty so no dedup machinery needed | 0.85 |
+| D-057 | Source-pin triage rule (operationalizes D-050): **KEEP a pin iff** it encodes a documented regression lesson (E87-style) or verifies cross-boundary wiring invisible to typecheck/build/behavioral tests (runtime fetch wiring, env keys, gate composition, JSON-LD presence); **CUT a pin** whose assertion duplicates another test or merely asserts code says what it says; kept pins move to a single `pins.test.ts` naming their regression | Falsifiable per-assertion; expected outcome ~5-8 kept of the 21 pin sites; cuts tautologies with zero regression loss | 0.75 |
+| D-058 | mypy strictness: **relaxed-first baseline** — `check_untyped_defs`, `warn_unused_ignores` (each of the 27 ignores either types or is removed), `no_implicit_optional`, `warn_redundant_casts`, `warn_unreachable`; NOT `strict=true`; per-module tightening via `[[tool.mypy.overrides]]` available later | Full strict on a never-myped codebase turns P5 into an annotation retrofit; `warn_unused_ignores` delivers the milestone goal (suppressions meaningful or gone) at realistic cost | 0.85 |
+| D-059 | recharts 2→3 chart-surface verification = **`tsc --noEmit` green + `next build` static export green (SSR-renders the chart pages) + existing web tests green**; no jsdom/happy-dom render harness (new deps = framework addition); live mount probe on the deployed site as the operational smoke | Build+typecheck exercise the real React 19/recharts 3 integration through SSR; browser/render tooling is explicitly out of scope for v0.7 | 0.80 |
+| D-060 | Shared Python test helpers: **`tests/helpers/` package** (`KillableProxy`, `free_port`, userns probe, real-uvicorn `serve`, `wirePosting`) imported as `from tests.helpers...`; fixtures stay in conftest.py; changes are test-internal import paths only — no public/test-facing API beyond that | Helpers are direct utilities, conftest is for fixtures — explicit imports keep call-site dependency honest; `tests/` is already a package (`__init__.py` present) | 0.90 |
+| D-061 | Version drift: **pyproject.toml is the single version source** — bumped to `0.5.6` (the shipped line); `FastAPI(version=)` derives from `importlib.metadata.version("nextcraft-ai-service")` (safe fallback for un-installed runs); stale version comments removed in the same sweep | One hardcoded "0.3.0", one pyproject "0.2.0", and a shipped 0.5.x all drifted — metadata lookup makes drift structurally impossible | 0.90 |
+
+## Milestone v0.6 — Marketplace Engine (COMPLETE, shipped as v0.5.6, 2026-09-26)
+
+**Scope (auto-decided at SPECIFY per full autonomy — founder scope question left unanswered 2026-09-21):**
+
+The marketplace has no backend today: every job board, job detail, employer profile, search, and pricing surface reads `packages/mock-data` directly; the only live route is the G-18 `POST /v1/marketplace/apply` gated stub (18+ verified, honest 501). The guiding outcome — ≥1,000 learners placed in AI-orchestration roles via the Nextcraft marketplace — runs *through* this surface, so the marketplace engine is the highest-leverage next build.
+
+**Scope decision (D-047):** Activate **REQ-F-011..016** as REQ-6-001..006 — the real marketplace backend behind the existing UI:
+
+1. **Job aggregation pipeline** (REQ-6-001, from REQ-F-011): job ingestion from employer postings + a seeded/synthetic corpus (3M+ external jobs is post-MVP — the pipeline ingests at pilot scale with the same adapter contract); postings store (6th D-027 store family); posting lifecycle (draft → published → closed).
+2. **AI-powered tagging** (REQ-6-002, from REQ-F-012): skills/seniority/category extraction from posting text via the existing LLM structured-output layer (D-020), provider-agnostic, mock-first.
+3. **Semantic vector search** (REQ-6-003, from REQ-F-013): embedding-backed role matching — candidate-competency vs posting-requirement similarity; SQLite-local at pilot scale (no pgvector before Postgres migration), deterministic embedding provider protocol (mock-first, real provider env-configured).
+4. **Company enrichment** (REQ-6-004, from REQ-F-014): employer profile enrichment from posting/company data (descriptions, social links, logo refs) — LLM-assisted, human-in-the-loop founder review deferred to post-pilot.
+5. **Resume/profile parsing** (REQ-6-005, from REQ-F-015): learner profile auto-fill from an uploaded resume — LLM structured extraction mapping to the competency profile shape.
+6. **SEO-optimized programmatic pages** (REQ-6-006, from REQ-F-016): server-rendered job/stack/landing pages with metadata, sitemap, structured data — built on the existing Next.js static-export single-port deploy (D-039-compatible).
+
+**Deferred beyond v0.6 (unchanged):** REQ-F-018 payments/subscriptions, REQ-F-019 human tutor marketplace, REQ-F-020 CIRR placement tracking.
+
+**Success (milestone-level):** the marketplace surfaces read from a real backend (postings, search, matching, employer profiles) instead of mock data; job posting + tagging + search work end-to-end for a pilot employer; the deploy stays one-command on the v0.4.x/v0.5.x fabric.
+
+## Prior Milestone: v0.5 — Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease (COMPLETE, shipped as v0.4.5; hotfixes v0.4.6 deploy-static-404, v0.4.7 pre-public hardening)
+
+**Scope (the four seams D-016 deferred out of v0.4, locked at v0.5 Phase 0 SPECIFY):**
+
+1. **Real server STT/TTS** (CUT-1/G-7 seam): implement the `openai-audio` VoiceProvider against OpenAI-compatible `/audio/transcriptions` (STT) + `/audio/speech` (TTS) — the D-030 protocol drop-in; mock stays first-class for tests; browser fallback stays for the no-key path. Voice defense (Examiner flows) gains the real server path end-to-end.
+2. **KYC/identity + age-gating backend** (REQ-F-017): real identity verification behind a provider protocol (mock-first, D-014 pattern), age-gate enforcement (school 16+, marketplace 18+ with verified identity) replacing the v0.1 visual-only flow, session/learner identity wired into the API surface (the G-5 allowlist evolves toward real identity).
+3. **Design/simulation sandbox environments** (REQ-F-021 remainder): extend the D-024/D-025 namespace fabric beyond the coding IDE — design-tool and simulation environment types alongside the existing build environment, one lifecycle, per-type telemetry.
+4. **Exec-telemetry seq-lease / replay-margin fix**: the one-line ACK gap documented in the P6 lesson (P07 review): reconnect replay margin so at-least-once ingest acknowledges received seqs and the capture agent resumes from the ack — closing the documented gap.
+
+**Success (milestone-level):** voice defense runs on real server STT/TTS when keys exist; age-gating is enforced by the backend (not a mockup page); the sandbox fabric provisions design/sim environments; the reconnect-replay gap is closed with a regression test.
+
+## Prior Milestone: v0.4 — Distribution & Bootstrap CLI (COMPLETE, shipped as v0.3.4; hotfixes v0.3.5 fresh-box experience, v0.3.6 single-port unattended deploy)
+
+**Scope (founder directive, 2026-09-12):** Streamline installing Nextcraft. Ship a bootstrap CLI with a single-liner install script, and publish release binaries on an ongoing basis for every release going forward.
+
+**Delivered:** `nextcraft` CLI — `doctor` (prerequisite checks), `bootstrap` (deps + venv + env from templates + key validation), `verify` (health check), `dev` (thin passthrough to scripts/dev.sh); one-liner install script downloading the linux x64 binary from the latest Gitea release with sha256 + version integrity gates; binary release pipeline attached to every ship from v0.3.2 onward; install/quickstart documentation backed by a fresh-clone E2E test. All 5 requirements (REQ-4-001..005) complete.
+
+**Status of v0.3:** Complete and shipped (v0.2.8). Credential engines live: namespace-isolated sandbox fabric, live build telemetry, process-trace grading, seeded variants, oral defense; real learner build/defense/grading surfaces.
 
 **Status of v0.2:** Complete and shipped (v0.2.0). Six AI tutor agents live over mockengine inputs (D-015).
 
-**Deferred from earlier plan:** REQ-F-017 (identity verification + 16+/18+ age-gating) is explicitly deferred to a later milestone per founder directive. Age-gating remains the v0.1-style visual flow mockup; no real KYC backend is built in v0.3.
+**Deferred from earlier plan:** REQ-F-017 (identity verification + age-gating KYC), real server STT/TTS, design/simulation sandbox environments, and the exec-telemetry seq-lease are all deferred to v0.5. Age-gating remains the v0.1-style visual flow mockup.
 
 **Tech stack:** v0.1 TS monorepo (pnpm/turborepo, Next.js) + v0.2 Python FastAPI ai-service + new credential-engine services (sandbox fabric orchestrator, telemetry ingest, grading engine) in Python/TypeScript as determined at RESEARCH.
 
 ---
 
-## Requirements (Validated)
+## v0.4 Requirements (Complete)
 
-The following requirements have been validated during specification and are locked for milestone v0.3 (REQ-F-007..010 and REQ-F-021 activated from the deferred pool; REQ-F-017 deferred per founder directive):
+All 5 v0.4 requirements (REQ-4-001..005) are complete and shipped as v0.3.4:
+1. Bootstrap CLI — `nextcraft` executable with `doctor` / `bootstrap` / `verify` / `dev` (REQ-4-001, REQ-4-002)
+2. One-liner install — `curl | sh` fetching the linux x64 binary from the latest Gitea release with sha256 + version integrity verification (REQ-4-003)
+3. Ongoing release binaries — every release from v0.3.2 onward ships the CLI binary + checksum as release assets (REQ-4-004)
+4. Install documentation — README quickstart + CLI reference verified by a fresh-clone E2E test (REQ-4-005)
 
-1. Sandbox fabric — sandboxed IDE, design tool, and simulation environments with isolated execution and lifecycle management (REQ-F-021)
-2. Live build telemetry — in-environment capture of process events (keystrokes, commands, file diffs, run/test results) streamed to ai-service (REQ-F-010)
-3. Process-trace grading engine — grade artifacts from their process traces, not just final output (REQ-F-007); feeds the Assessor agent real inputs
-4. Variant task generation — per-learner task variants so no two learners receive identical prompts (REQ-F-008)
-5. Oral/voice defense — AI examiner conducts spoken defense of submitted work (REQ-F-009); feeds the Proctor/Mentor agents
-6. Agent re-grounding — Lab/Assessor/Proctor consume real engine inputs (telemetry, traces, defenses) instead of v0.2 mocks
-7. Learner surface integration — wire the v0.1 sandbox + assessment mockups to the real engines (build/run in-browser, live telemetry, live defense)
+## v0.3 Requirements (Complete)
 
-## v0.2 Requirements (Complete)
-
-All 12 v0.2 requirements (REQ-2-001..012) are complete and shipped as v0.2.0. See REQUIREMENTS.md traceability matrix.
+All 8 v0.3 requirements (REQ-3-001..008) are complete and shipped as v0.2.8. See REQUIREMENTS.md traceability matrix.
 
 ## v0.1 Requirements (Complete)
 
 All 28 v0.1 requirements (REQ-001..028) are complete and shipped as v0.1.0. See REQUIREMENTS.md traceability matrix.
 
+## Clarified Assumptions (v0.6 CLARIFY stage, full autonomy — auto-resolved)
+
+| # | Ambiguity | Resolution | Confidence |
+|---|-----------|------------|-------------|
+| A-401 | Who authors postings at pilot (no employer auth exists)? | **Founder-authored; employer self-serve deferred.** Postings enter via founder/admin API routes (`/v1/marketplace/admin/postings` create + lifecycle transitions draft→published→closed), guarded by an `AI_ADMIN_TOKEN` env-header check (keys env-only, D-014; operator route — D-043 learner gate composition untouched). The employer dashboard's posting-management mockup stays mock; real employer self-serve lands with the deferred B2B employer network milestone. | 0.85 |
+| A-402 | Ingestion adapter contract shape? | **`PostingSource` protocol in `ai_service/marketplace/`** (D-031 module, D-014 mock-first): `fetch() -> Iterable[IngestPosting]` — pydantic-typed with `source`, `external_id`, employer + posting fields. Two v0.6 implementations: `seeded_corpus` (in-repo JSON seed, ported once from packages/mock-data jobs.ts/employers.ts per D-021 convention) and `admin_api` (A-401 founder path). Upserts idempotent on `(source, external_id)`. No scheduler/crawler — the 3M+ external corpus drops in later as a new adapter with zero store/route changes. | 0.80 |
+| A-403 | Where do embeddings live at SQLite scale (pip-only venv, no pgvector)? | **`embedding` table inside the marketplace SQLite store (6th D-027 family)**: posting_id → BLOB of struct-packed float32 + model + dim columns; the candidate side embeds the learner's competency profile text on demand (not stored). **Brute-force cosine in pure Python** at query time (pilot scale ≤ ~10⁴ postings — no numpy, no FAISS/chromadb, no new deps). `VectorStore` protocol-wrapped so the Postgres migration swaps to pgvector with no API changes (D-027/D-019 pattern). | 0.85 |
+| A-404 | Embedding provider + dimensionality? | **`EmbeddingProvider` protocol (mirror of D-030 VoiceProvider)**: deterministic mock (256-dim feature-hash of posting/profile tokens — similarity is deterministic; tests never call the cloud) + real OpenAI-compatible `POST {AI_EMBED_BASE_URL}/embeddings` via `AI_EMBED_MODEL`/`AI_EMBED_API_KEY` (env-only; ollama-cloud exposes /embeddings). Dimension is **not hardcoded** — persisted per row with the model name; on provider/model change, postings re-embed lazily. **[SUPERSEDED by D-051 probe: ollama-cloud does NOT expose /embeddings (404 path-not-found) — `AI_EMBED_BASE_URL` must target another OpenAI-compatible endpoint (e.g. local ollama `:11434/v1`); protocol design unaffected, default stays mock]** | 0.75 |
+| A-405 | Does semantic search replace the filter sidebar? | **Hybrid — augments, not replaces.** REQ-6-002 tag facets (skills/seniority/category + location/remote/salary) remain hard filters driving the existing sidebar; the semantic query + similarity compose as a **ranking layer over the facet-filtered set** (no facets selected → pure semantic ranking). Match score on job cards = cosine(candidate-competency vector, posting vector), replacing the mock `matchScore`; skill-breakdown panel derives from tag overlap + per-skill vector contribution. ARCHITECTURE.md's old "filter UI replaced" future-note is superseded by this hybrid. | 0.80 |
+| A-406 | What happens to packages/mock-data jobs.ts/employers.ts (runtime data vs static export)? | **Marketplace web surfaces switch from build-time mock imports to runtime client fetch** (A-002 direct-fetch + engine-client pattern, proven by build/defend surfaces): board/detail/employer-profile become client shells fetching `/v1/marketplace/*`; `generateStaticParams` on jobs/[jobId] and employers/[employerId] is removed (one static shell per route, data at runtime). jobs.ts/employers.ts are ported **once** into the Python seed fixture (A-402) and go dormant for the marketplace path (mock-data remains for admin/employer-dashboard mockups + shared types). No build-time DB reads — the D-039 deploy export build stays repo-only. | 0.80 |
+| A-407 | Employer auth model at pilot? | **None — employers are data, not principals, in v0.6.** Employer records are ingested/enriched entities keyed by `employer_id` on postings; no employer login, sessions, or accounts. The employer dashboard surface stays the v0.1 mockup; enrichment is founder-triggered/admin-reviewed (A-409), never employer-edited. Real employer auth lands post-payments with the B2B employer network. | 0.85 |
+| A-408 | Apply-flow shape beyond the 501 stub? | **The existing `POST /v1/marketplace/apply` route becomes real, D-043 composition unchanged** (G-5 allowlist → verified-18+ verdict → rate caps): body `{posting_id}` → posting must be `published` → insert an `application` row (status `submitted`, identity ref, timestamp) in the marketplace store → honest confirmation payload. Duplicate apply (same learner + posting) is idempotent. **No notification infra**: founder reviews applications via `/v1/marketplace/admin/applications` and contacts employers out-of-band. | 0.75 |
+| A-409 | Enrichment provenance rules? | **Separate `employer_enrichment` table — raw fields never overwritten** (REQ-6-004): append-only rows `(employer_id, field, value, source: llm\|manual, model, created_at)`. Read precedence **manual > llm > ingested-raw**; API responses merge and carry per-field provenance markers (A-304 honesty pattern — LLM-authored copy visibly marked). Enrich-on-post: new employer's first published posting triggers LLM structured extraction (D-020, mock-first) of description/social links/logo refs. Founder override = upsert a `manual`-source row, never a mutation of `llm` rows. | 0.85 |
+| A-410 | Resume upload format bounds? | **PDF/TXT/MD only, ≤2 MB, text-layer required.** PDF text via `pypdf` (pure-Python, pip-reachable through the A-009 venv-pip channel — the only new dep); extracted text capped ~100K chars before the D-020 structured-extraction call mapping to the competency-profile shape. Image-only/scanned PDFs → honest 422 ("text layer required") — **no OCR in v0.6**. Parsed result returns as a DRAFT: nothing persists to the learner profile until explicit learner confirm (REQ-6-005 review gate); raw resume bytes never stored, never logged (A-305 pattern). | 0.80 |
+| A-411 | Which pages get programmatic SEO treatment under static export — and how? | **Build-time-static set: landing, catalog/stack detail, marketplace board, pricing** — full server-component metadata (title/desc/OG) + JSON-LD (Organization, stack/Course, ItemList) rendered at export (D-039 build unchanged). **Runtime-data set: job detail + employer profile** — client shells (A-406) inject `JobPosting`/`Organization` JSON-LD + title client-side after fetch (best-effort per-job SEO at pilot; recorded as an accepted limitation — JS-less crawlers see the shell). **Sitemap/robots: `/sitemap.xml` + `/robots.txt` served dynamically by ai-service** (API routes beat the static mount, D-039), enumerating static pages + published postings; robots points at `/sitemap.xml`. | 0.70 |
+| A-412 | Pricing page — real or mock? | **Stays mock — zero backend.** Payments/subscriptions are REQ-F-018, explicitly deferred beyond v0.6 (D-047). The pricing page gains only build-time metadata/OG (A-411 static set); no pricing API routes, no package enforcement — posting is free at pilot (founder-mediated). | 0.95 |
+
+## Clarified Assumptions (v0.5 CLARIFY stage, full autonomy — auto-resolved)
+
+| # | Ambiguity | Resolution | Confidence |
+|---|-----------|------------|------------|
+| A-301 | Which STT/TTS endpoint for `openai-audio`? | **OpenAI-compatible `/audio/transcriptions` + `/audio/speech`** via `AI_VOICE_BASE_URL` (ollama-cloud does not expose audio endpoints; any OpenAI-compatible audio API works — the provider is endpoint-agnostic by config, D-014 pattern). Model via `AI_VOICE_MODEL` (default `whisper-1` STT / `tts-1` TTS class names, configurable). Keys env-only, never committed. | 0.75 |
+| A-302 | Does real voice replace browser fallback? | **No — layered.** `openai-audio` when configured, browser-native second-class fallback (CUT-1 keeps it first-class for the no-key path), deterministic mock for tests. The defense surface probes provider capability and degrades with a visible badge (mic mock vs browser vs server). | 0.85 |
+| A-303 | KYC vendor in v0.5? | **No vendor — protocol + mock-first backend.** `IdentityProvider` protocol (submit/poll/verify), deterministic mock (approve-on-policy), SQLite store. A real vendor (Stripe Identity/Persona/Onfido class) drops in later without API changes. Solo-founder economics: no vendor spend before pilot. | 0.85 |
+| A-304 | What counts as "verified 18+" for marketplace? | **Provider verdict = DOB-verified 18+; until a real vendor exists the mock verdict is explicit and marked `mock` in API responses** so downstream surfaces can label unverified state honestly (never display mock-verified as production-verified). | 0.80 |
+| A-305 | PII storage? | **Server-side only, minimal**: document refs + provider verdicts in SQLite; raw documents NEVER stored, NEVER logged (payload scrubbing pinned by test). Enrollment DOB stored as derived age-band, not raw DOB where possible. | 0.85 |
+| A-306 | Age-gate enforcement points? | **School enrollment (16+)**: identity submit → verify → age check at enrollment API. **Marketplace (18+ verified)**: gated marketplace routes check verified-identity verdict; unverified → 403 with verify-CTA payload. G-5 learner allowlist REMAINS as a pilot guard (identity doesn't replace sandbox rate caps). | 0.82 |
+| A-307 | What are "design" and "simulation" environments concretely? | **Same namespace fabric, typed starter contents + allowed commands.** `design`: canvas-style artifacts (files the learner edits: SVG/HTML/schematic text), Run = validator/renderer harness command; `simulation`: parameterized run harness (benchmark scripts + dataset files), Run = bounded harness execution. No new isolation tech — D-024 unchanged; the ENVIRONMENT is a typing over starter files + command policy. | 0.78 |
+| A-308 | Does the learner UI need new surfaces for design/sim? | **Reuse the build surface.** The existing /build flow accepts `environment` kind; the file tree, editor, Run/Test buttons, and read-only output panel (CUT-2) all carry over; only starter contents and command policy differ per kind. No new route groups; variants carry the kind. | 0.80 |
+| A-309 | Seq-lease protocol shape? | **Ingest acks highest-contiguous received seq per (learner, task) on the existing WS (JSON ack frame); the capture agent trims its spool to the ack and replays from there on reconnect.** Replay margin bounded (spool cap already exists). No new endpoint; G-3 flood semantics unchanged; acks are advisory hints, gap detection stays authoritative. | 0.80 |
+| A-310 | Where does identity live in the app? | **New `ai_service/identity/` module (D-031 pattern — extend ai-service, no new apps)**: provider protocol + mock, SQLite store (D-027 family), `/v1/identity/*` router. Web enrollment + marketplace surfaces call it via engine-client. | 0.85 |
+
+## Clarified Assumptions (v0.4 CLARIFY stage, full autonomy — auto-resolved)
+
+| # | Ambiguity | Resolution | Confidence |
+|---|-----------|------------|-------------|
+| A-201 | CLI language/toolchain for the binary? | **Probe-driven at RESEARCH** — Go → Rust → Node SEA → Python zipapp fallback chain; spec stays toolchain-agnostic so PLAN locks the probe-verified toolchain | 0.70 |
+| A-202 | Does bootstrap replace scripts/bootstrap.sh? | **No — reuse it.** CLI wraps existing `scripts/bootstrap.sh` + `scripts/dev.sh` via subprocess; zero orchestration logic duplicated in the CLI (thin passthrough pattern) | 0.85 |
+| A-203 | Where does the one-liner fetch the binary? | **Gitea latest-release API** (`/repos/{owner}/{repo}/releases/latest`) → download `nextcraft-linux-x64` + `.sha256` asset; repo raw serves `install.sh` as the stable URL | 0.80 |
+| A-204 | Install target + PATH? | **~/.local/bin** (XDG-style, no sudo), PATH hint printed when missing; `--dest` override flag | 0.85 |
+| A-205 | Binary "ongoing releases" scope? | **Every ship from v0.4 onward** attaches `nextcraft-linux-x64` + sha256 sidecar to the Gitea release — the ship workflow gains an asset step; retroactive binaries for old releases NOT required | 0.90 |
+| A-206 | No binary available yet / non-linux? | **Graceful degradation**: install script prints source-bootstrap instructions (git clone + scripts/bootstrap.sh) — never a hard fail | 0.88 |
+| A-207 | Checksum trust root? | **sha256 sidecar shipped as a release asset next to the binary** (same release, same channel); script verifies download against it. Signature/PKI out of scope for v0.4 (single forge, TLS transport) | 0.75 |
+| A-208 | Which prerequisites does doctor check? | node ≥18, pnpm ≥8, python3 ≥3.11, git, `unshare` availability (sandbox fabric needs it) — versions from the existing bootstrap tooling, not invented | 0.85 |
+| A-209 | Does `dev` manage multiple processes? | **No.** Thin passthrough to scripts/dev.sh only — the CLI stays bootstrap-scoped (D-016); orchestration remains in dev.sh | 0.82 |
+| A-210 | `.env.secrets` handling by bootstrap? | **Template copy only for `.env.example` → `.env`; secrets NEVER generated, NEVER committed; bootstrap validates presence of optional keys and warns (not blocks) when missing — mock-first providers keep the stack runnable** | 0.90 |
+
 ## Clarified Assumptions (v0.3 CLARIFY stage, full autonomy — auto-resolved)
 
 | # | Ambiguity | Resolution | Confidence |
 |---|-----------|------------|-------------|
 | A-101 | Sandbox isolation technology? | **`unshare` user+mount+pid+net namespace subprocess isolation** per sandbox (probe-verified: in-ns uid=0, network fully isolated with 0 interfaces, writes land in an isolated bind-mounted workdir; proc-remount is not permitted in this context but is not required). No Docker/Podman/VMs — none present on the box; no sudo. A `SandboxBackend` protocol keeps a future containerd swap possible. Falls back further to a plain chroot-free subprocess with a cwd-jail if userns ever unavailable (tested path is userns). | 0.8 |
 | A-102 | Sandbox scope in v0.3? | **Coding IDE only** (web terminal + file tree + run/test). The "design tool" and "simulation" environments specified in REQ-F-021 are deferred to v0.4 — a single real build environment is enough to prove the credential pipeline end-to-end (telemetry → trace → grade → defense). | 0.75 |
-| A-103 | Live in-browser build UX? | **WebSocket xterm.js terminal** attached to the bwrap sandbox shell + HTTP file-tree/CRUD + run/test buttons. No full Monaco LSP in v0.3 — a code editor with syntax highlight (existing) + real shell is sufficient and far cheaper. | 0.72 |
+| A-103 | Live in-browser build UX? | **Run/Test buttons executing in the namespace sandbox + HTTP file-tree/CRUD + read-only exec-output panel** (CUT-2/G-8 — the interactive xterm.js shell relay is deferred to v0.4; `@xterm/*` is not a v0.3 dependency). No full Monaco LSP in v0.3 — a code editor with syntax highlight (existing) is sufficient and far cheaper. | 0.72 |
 | A-104 | Telemetry transport? | **WebSocket** from sandbox to a new ingestion endpoint on ai-service for live events; **SQLite-backed** ordered event log (`ai_service/telemetry/`) gives durability + at-least-once delivery + replay. Events carry monotonic `seq` per (learner,task) so gaps are detectable. | 0.8 |
 | A-105 | Where do traces live? | **SQLite** (`ai_service` data dir), introducing the first real persistence. SQLModel/SQLAlchemy for typed access. Chosen over Postgres because solo-founder + single box + low write volume; the `TraceStore` protocol is Postgres-migration-ready like SessionStore was. | 0.75 |
 | A-106 | Process-trace grading model? | **LLM-based grader**: structure the trace into a compact timeline digest (command categories, error/fix cycles, idle gaps, test passes) → Assessor-style rubric prompt → structured score via existing D-020 JSON defense. Deterministic features (test pass/fail, edit count) computed in code, not left to the LLM. | 0.7 |
@@ -54,7 +216,7 @@ All 28 v0.1 requirements (REQ-001..028) are complete and shipped as v0.1.0. See
 | A-108 | Voice defense — STT/TTS providers? | **Provider-agnostic, mock-first like the LLM layer (D-014).** Real path: browser `MediaRecorder` → audio to ai-service → **OpenAI-compatible `/audio/transcriptions`** (Whisper STT) and **`/audio/speech`** (TTS) against ollama-cloud or a compatible endpoint; fallbacks: browser `SpeechRecognition`/`speechSynthesis` when no server keys. `VoiceProvider` protocol + deterministic mock (returns canned transcript) so tests never call a voice API. | 0.62 |
 | A-109 | Defense dialogue shape? | Reuse BaseAgent: an `Examiner` agent (seventh agent) streams examiner questions over the existing SSE pipeline; integrity signals (long pauses, off-scope answers, reading-from-notes cadence) emitted alongside the transcript to Proctor. | 0.8 |
 | A-110 | KYC / age-gating in v0.3? | **Deferred per founder directive.** No real identity backend. Age-gating stays the v0.1 visual flow mockup. Personas omit a security-engineer; security review via verifier + Phase 7 secrets-hygiene checklist. **Abuse control is NOT deferred with KYC (G-5):** v0.3 ships per-learner sandbox caps (`AI_SANDBOX_MAX_PER_LEARNER`), a global create-rate cap, and a server-side `learner_id` allowlist (`AI_LEARNER_ALLOWLIST`) so the unauthenticated surface cannot exhaust shared NPROC/disk. Documented in the release note. | 0.98 |
-| A-111 | New services vs extend ai-service? | **Extend ai-service**, don't fork new Python apps. Telemetry ingestion, trace grading, variant generation, voice, and sandbox orchestration all live as new modules in `apps/ai-service` (they share the LLM provider pool + config + session infra). Only the in-sandbox capture agent is a separate tiny Python process shipped into the bwrap environment. | 0.82 |
+| A-111 | New services vs extend ai-service? | **Extend ai-service**, don't fork new Python apps. Telemetry ingestion, trace grading, variant generation, voice, and sandbox orchestration all live as new modules in `apps/ai-service` (they share the LLM provider pool + config + session infra). Only the in-sandbox capture agent is a separate tiny Python process shipped into the namespace sandbox. | 0.82 |
 | A-112 | Sandbox on a single dev/school box — capacity? | v0.3 targets **1–5 concurrent sandboxes** (founder + pilot learners). No horizontal scaling, no queue. Concurrency guard returns 503 when full. Scaling is post-MVP. | 0.8 |
 
 ## Clarified Assumptions (v0.2 CLARIFY stage, full autonomy — auto-resolved)
@@ -133,6 +295,9 @@ The following remain deferred beyond v0.3 and will be activated in subsequent mi
 | D-013 | v0.1 prototype founder-agreed; D-001 business-logic gate unlocked | Founder approved starting v0.2 with AI Tutor Architecture, which constitutes agreement of the v0.1 prototype per D-001. Recorded at v0.2 SPECIFY. | Business logic authorized from v0.2 onward |
 | D-014 | Provider-agnostic LLM layer; ollama-cloud as initial provider | OpenAI-compatible client abstraction with pluggable providers: ollama-cloud (https://ollama.com/v1, default), local OpenAI-compatible endpoint, deterministic mock (tests/CI). Keys in gitignored .ciagent/.env.secrets, never in code or commits. | apps/ai-service llm package with 3 providers; default=ollama-cloud |
 | D-015 | All six agents implemented as real LLM services; engines mocked | Coach/Tutor/Mentor fully real. Lab/Assessor/Proctor are real LLM logic over mock inputs (simulated telemetry, pre-baked artifacts) since sandbox fabric, assessment engine, and identity verification are v0.3+. Consistent with v0.1's mock-data approach. | REQ-F-001..006 complete in v0.2; real engines deferred to v0.3+ |
+| D-016 | v0.4 = Distribution & Bootstrap CLI (founder directive supersedes previously-named v0.4 seams) | Founder directive 2026-09-12: focus this milestone on streamlining install, a bootstrap CLI with a one-liner install script, ongoing release binaries. Real server STT/TTS, KYC, design/simulation envs, seq-lease move to v0.5. | Milestone scope locked at SPECIFY; binary = CLI-only, linux x64 |
+| D-047 | v0.6 = Marketplace Engine (auto-decided at SPECIFY, full autonomy; founder scope question left unanswered 2026-09-21) | Activates REQ-F-011..016 as REQ-6-001..006: real marketplace backend (aggregation, tagging, vector search, enrichment, resume parsing, SEO pages). Rationale: the guiding outcome (≥1,000 placements via the marketplace) runs through the only surface with zero backend; every prior milestone fed the credential side, placement side is the bottleneck. Confidence 0.80 ≥ threshold 0.60 (D-007). External 3M+ job corpus scaled to pilot (adapter contract preserves the full-scale path). | Milestone scope locked at SPECIFY; tags on v0.5.x line; feature milestone |
+| D-039 | Single-port deploy + unattended dev (v0.3.6 hotfix, founder directive) | Only :8420 reachable behind HAProxy; site was down (domain root hit the API 404). Web app = static export served same-origin by the ai-service (`AI_WEB_STATIC_DIR`); `dev -d`/`stop`/`log` daemonize ops; durable state (DB, sandboxes, pid/log) moves to `~/.nextcraft/` out of the repo. | One port serves UI+API; unattended deploy recipe in deploy/README.md |
 
 ---
 
@@ -140,4 +305,4 @@ The following remain deferred beyond v0.3 and will be activated in subsequent mi
 
 Nextcraft is being built by a solo founder using the CIAgent v0.7.0 autonomous pipeline. The vision document defines a 36-month, 3-phase roadmap to ≥1,000 placements. The first CIAgent milestone (v0.1) is intentionally scoped to UI/UX only — validating the product vision through interactive prototypes before any backend or business logic investment.
 
-The four surfaces (Learner, Marketplace, Employer Dashboard, Admin) map directly to the four audiences in the vision: learners, employers, marketplace operators, and platform administrators. The prototype will demonstrate the complete user journey across all surfaces with realistic mock data reflecting the AI-era competency stacks, AI-orchestration job listings, and artifact+process trace+oral defense credential model.
+The four surfaces (Learner, Marketplace, Employer Dashboard, Admin) map directly to the four audiences in the vision: learners, employers, marketplace operators, and platform administrators. The prototype will demonstrate the complete user journey across all surfaces with realistic mock data reflecting the AI-era competency stacks, AI-orchestration job listings, and artifact+process trace+oral defense credential model.

.ciagent/REQUIREMENTS.md

@@ -1,5 +1,147 @@
 # Nextcraft — REQUIREMENTS.md
 
+## v0.8 Requirements (ACTIVE — Ship Anywhere, Feature)
+
+**Milestone type: Feature** — new distribution channels (docker image, deb packages, arm64 binaries) and release automation (Gitea Actions, pre-commit). Tags on the v0.7.x line (P0 → v0.7.0 … P6 → v0.7.6 = milestone release); branch `milestone/v0.8-ship-anywhere`.
+
+### Release Consistency Rails
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-8-001 | Release-consistency rails: three org-level Gitea act_runners stood up on founder LXC CT 113 (10.0.0.113, docker containers in sibling-container mode via host /var/run/docker.sock, hybrid labels ubuntu-latest/node/python/release, org-level coreci scope, registration token founder-provided and reset after fleet green), `.gitea/workflows/` lint+typecheck+test pipeline on push (v0.7 toolchain: eslint, ruff, mypy, pytest fast lane, web/cli node:test; CI test lanes = fast only per D-063: `ai:test:fast` `-m "not real_server and not userns"`, default web/cli node:test, CLI E2E env-gated out — real_server/userns never run in job containers), tag-triggered release workflow as the exclusive owner of release assets + registry push (D-064; local release-assets.sh remains manual fallback), single root `.pre-commit-config.yaml` (ruff + eslint + tsc local-only fast hooks, directory-scoped whole-monorepo, no network, secrets never in hooks or workflow env; hooks fail loudly on missing toolchain, never silently skip — D-070; CI is the authoritative backstop), runner cache-hygiene (docker prune cron + cache caps, 32 GB disk), hello-world dispatch verification across all three labels | critical | 1 | complete |
+
+### Container Channel
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-8-002 | Docker image channel: multi-stage Dockerfile (deps layer: pnpm store + pip wheels pre-loaded; build layer: web static export with NEXT_PUBLIC_AI_SERVICE_URL=self; runtime: uvicorn :8420 serving API + export — single-port topology preserved; runtime image embeds the CLI binary at /usr/local/bin/nextcraft for in-container doctor/verify/guide — D-066), unprivileged default + honest degrade (capability probe at boot + per create — a real `unshare --user --map-root-user` attempt as the truth source, `/.dockerenv`/NC_CONTAINER only flavor remediation text; degraded = learner environment creation rejects 503 with privileged/seccomp remediation pointer + loud boot notice + doctor surfacing — D-068), healthcheck on /health, `~/.nextcraft` state volume, image pushed to the Gitea container registry as `git.coreci.dev/coreci/nextcraft` tagged semver release `v0.7.x` + `latest` on newest release (D-065), REGISTRY_TOKEN as Gitea Actions secret (self-serve PUT attempt first, founder UI fallback) | critical | 2 | pending |
+
+### Debian-Native Channel
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-8-003 | Debian packaging: arm64 SEA binary + sha256 sidecar cross-built on the x64 runner without QEMU for the build (arch-agnostic esbuild+postject file surgery into an arm64 node base; optional binfmt `--version` smoke — D-069), .deb packages (dpkg-deb) for x64+arm64 = CLI binary at /usr/bin/nextcraft + package docs only, NO systemd unit (deploy --service owns unit generation) and no proxy fragments; postinst runs `nextcraft doctor` best-effort advisory (never fails dpkg) + prints next-steps (D-067); all attached to every release's downloads by the tag-triggered workflow (D-064); install.sh arch-gate becomes arch-resolve (x64 + arm64 binary paths); deb install + binary install both end at `nextcraft doctor` verify | high | 3 | pending |
+
+### CLI Onboarding
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-8-004 | CLI full-suite onboarding: `nextcraft` alone takes an admin zero → running — doctor gains deb/docker-channel awareness (detects container env + suggests volume/privileged facts; detects deb install + knows its binary location; embedded in-container binary per D-066), `nextcraft guide` surfaces the admin runbook channel-appropriately as offline-first embedded text with forge pointers (D-072), docker-channel upgrade = docker pull + recreate (deploy/bootstrap refuse in-container — D-066/D-071), onboarding glue verified by an E2E test per channel (binary one-liner path exists from v0.4; docker + deb paths new) | high | 4 | pending |
+
+### Admin Guides
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-8-005 | Admin release & deployment guides: deploy/README.md expanded into the full admin runbook — three install channels (docker / deb / binary+install.sh) first-install recipes, per-channel upgrade paths (docker pull + recreate / deb reinstall via dpkg -i + deploy --service / install.sh re-run + deploy --service, all idempotent — D-071), HAProxy + systemd recipes preserved, troubleshooting tables extended (runner, registry, docker degrade, deb), every recipe backed by a test or verified live-box evidence (house rule) | critical | 5 | pending |
+
+## v0.7 Requirements (Complete — Test Harness Review, NFR; shipped as v0.6.6)
+
+**Milestone type: NFR — refinement-only (D-001 purity gate: zero `feat:` commits).** Review the entire test harness: make sure the right tests are being run, make them effective, cut tests that provide no real value, eliminate all warnings, and address the findings within this single milestone. Founder scope decisions locked 2026-09-26: ESLint included (D-048), recharts 2→3 included (D-049), source-pin triage cut-trivial-keep-real (D-050), mypy included (D-051).
+
+### Harness Wiring
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-7-001 | Test harness infrastructure: coverage measurement wired (pytest-cov for ai-service, c8 around the existing `tsx --test` for web/cli — D-052), pytest-timeout safety net (`signal` method, 60s global / 180s for `real_server`+`userns` via conftest collection hook — D-054; CLI fresh-clone E2E keeps its real 600s bootstrap, env-gated out of the default `cli:test` into a `cli:test:e2e` script with a 900s budget — D-055), markers `fast`/`real_server`/`userns` registered under `--strict-markers` with fast subset = `-m "not real_server and not userns"` (`ai:test:fast` script; unmarked tests default to fast — D-053), web tests inside the turbo pipeline (`web#test` task — package name is `web` + root `test`/`web:test` scripts), silent-skip fixes (path-invocation reports skip; env/global leaks fixed — `AI_PROVIDER` env mutation restored, conftest exception swallow narrowed), stale PLAN.md test counts corrected | critical | 1 | complete |
+
+### Suite Composition
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-7-002 | Evidence-based suite composition: trivial/no-value tests cut per the D-057 rule (keep a source pin only if it encodes a documented regression lesson or cross-boundary wiring invisible to typecheck/build/behavioral tests — e.g. E87, runtime fetch wiring, gate composition; cut pins that merely assert the code says what it says; kept pins named after their regression), duplicated harness infrastructure consolidated (KillableProxy ×2, `_free_port` ×4, userns probe ×4, real-uvicorn serve boilerplate ×5, wirePosting ×2 → `tests/helpers/` package — D-060; fixtures stay in conftest), flake strategy replaces timeout-widening with deterministic waits where possible, leaked sandbox-droppings cleanup + `tests/sandboxes/` anchoring fixed | critical | 2 | complete |
+
+### Warning Elimination
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-7-003 | Zero-warning pytest runs: `session.query()` → `session.exec()` at all 14 sites (marketplace/store.py ×12, identity/store.py ×2), resource cleanup for the 14 ResourceWarning sites (UploadFile close ×10 in api/defense.py + api/marketplace.py, socket close ×3 in scripts/sandbox-agent.py, file handle in tests/grading/test_engine.py), pytest `filterwarnings` policy (base action `error`; narrow module+message-scoped upstream ignores for the fastapi/starlette TestClient httpx warning and anyio BlockingPortal — no blanket category ignores, nothing ignored for `ai_service.*` — D-056), `fixture_loop_scope` pinned, dead `if False` branch removed | critical | 3 | complete |
+
+### Lint & Suppression Hygiene
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-7-004 | Lint toolchain completion: ESLint flat config (typescript-eslint + react-hooks) for all JS/TS workspaces wired into `turbo lint` (currently a no-op for 5 of 6 packages, D-048), all 81 inert Python `# noqa` reconciled via RUF100 (dead ones removed), the 5 orphaned eslint-disable comments resolved under the real config, dead exports removed (ai-scenarios.ts, NavItem/ThemeConfig, Spawn, MicControl), stale version comments + `FastAPI(version="0.3.0")` drift fixed (pyproject.toml as single version source bumped to the shipped line; FastAPI version read from package metadata — D-061), `engines` fields added to package.jsons | high | 4 | complete |
+
+### Type & Dependency Hardening
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-7-005 | Static typing for ai-service (D-051): mypy wired with `ai:typecheck` script + turbo task at a relaxed-first baseline (D-058: `check_untyped_defs`, `warn_unused_ignores`, `no_implicit_optional`, `warn_redundant_casts`, `warn_unreachable` — not full strict; per-module overrides available later), all 27 `# type: ignore` comments made meaningful or removed; recharts 2→3 upgrade (D-049) with chart-surface verification = `tsc --noEmit` + static-export `next build` + existing web tests green, live mount probe as the operational smoke (D-059 — no browser/render harness, out of scope); deprecated transitive deps resolved where toolchain allows | high | 5 | complete |
+
+## v0.6 Requirements (Complete — Marketplace Engine; shipped as v0.5.6)
+
+### Job Aggregation & Postings
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-6-001 | Job posting backend (from REQ-F-011, pilot-scaled): postings store (6th D-027 store family — SQLite, insert-safe, protocol-wrapped), employer posting lifecycle (draft → published → closed), ingestion adapter contract (employer-authored postings + seeded corpus at pilot scale; 3M+ external aggregation preserved by the adapter interface), marketplace API routes replacing the mock-data reads on job board/detail/employer surfaces, 18+ verified identity gate on apply/post flows (D-043 composition retained) | critical | 1 | complete |
+| REQ-6-002 | AI-powered tagging (from REQ-F-012): skills/seniority/category extraction from posting text via the LLM structured-output layer (D-020) — deterministic mock-first, provider-agnostic; tags persisted with the posting; tag facets drive the search filter sidebar | high | 2 | complete |
+
+### Search & Matching
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-6-003 | Semantic vector search (from REQ-F-013): embedding provider protocol (mock-first, deterministic; real provider env-configured per D-014), vector store at pilot scale (SQLite-local — no pgvector before the Postgres migration), candidate-competency ↔ posting-requirement similarity ranking, match-score surfacing on job cards + candidate matches (replaces mock match scores) | critical | 3 | complete |
+
+### Enrichment & Parsing
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-6-004 | Company enrichment (from REQ-F-014): employer profile enrichment from posting/company data (descriptions, social links, logo refs) via LLM structured output; enrich-on-post with manual founder override path; enriched data stored separately from raw (provenance marked) | medium | 4 | complete |
+| REQ-6-005 | Resume/profile parsing (from REQ-F-015): learner profile auto-fill from an uploaded resume — LLM structured extraction mapping to the competency-profile shape, learner-review-before-save (never silently overwrite), upload bounded (size/format guard, house pattern) | medium | 4 | complete |
+
+### SEO & Programmatic Pages
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-6-006 | SEO-optimized programmatic pages (from REQ-F-016): server-rendered job/stack/landing pages with metadata (title/description/OG), sitemap.xml + robots.txt, JSON-LD structured data (JobPosting schema), static-export compatible (D-039 single-port deploy unchanged) | high | 5 | complete |
+
+## v0.5 Requirements (Complete — Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease; shipped as v0.4.5)
+
+### Real Server Voice
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-5-001 | `openai-audio` VoiceProvider: server STT (`/audio/transcriptions`) + TTS (`/audio/speech`) against an OpenAI-compatible endpoint via the existing D-030 protocol; provider selection by `AI_VOICE_PROVIDER` (+ base URL/key from env, never committed); deterministic mock stays first-class; browser fallback unchanged | critical | 2 | complete |
+| REQ-5-002 | Voice defense real path end-to-end: examiner dialogue answers transcribed server-side (audio upload → transcript), examiner questions spoken via server TTS (audio returned to the client); transcripts + integrity signals unchanged | critical | 2 | complete |
+
+### Identity & Age-Gating
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-5-003 | Identity provider protocol + mock-first backend (REQ-F-017): verify-identity flow (submit → pending → verified/rejected with document refs), provider-agnostic (mock default; a real KYC vendor drops in later), PII stored server-side only, never logged | critical | 3 | complete |
+| REQ-5-004 | Age-gating enforced by the backend: school floor 16+ verified at enrollment, marketplace 18+ with verified identity — API surfaces reject under-age/unverified callers on gated routes (replaces the v0.1 visual-only flow; G-5 allowlist evolves toward real identity, allowlist remains as pilot guard) | critical | 3 | complete |
+
+### Sandbox Environments
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-5-005 | Design + simulation sandbox environment types (REQ-F-021 remainder): extend the namespace fabric with environment kinds beyond the coding IDE (design-tool: canvas/editor surfaces with file artifacts; simulation: run/benchmark harnesses) — one lifecycle, one telemetry path, per-type starter contents + allowed commands | high | 4 | complete |
+| REQ-5-006 | Environment-typed learner surface: the build/defend flow accepts environment kind, telemetry captures per-kind events, grading digest stays kind-agnostic | high | 4 | complete |
+
+### Telemetry Durability
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-5-007 | Exec-telemetry seq-lease/replay-margin fix: WS ingest acknowledges received seqs; capture agent resumes from the ack on reconnect (bounded replay margin) — closes the P6-lesson one-line ACK gap with a real-server regression test | high | 1 | complete |
+
+## v0.4 Requirements (Complete — Distribution & Bootstrap CLI, shipped as v0.3.4)
+
+### Bootstrap CLI
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-4-001 | `nextcraft` CLI (linux x64 binary): `doctor` command checking prerequisites (node, pnpm, python3, git, unshare) with actionable error messages | critical | 1 | complete |
+| REQ-4-002 | `bootstrap` command: pnpm install, ai-service venv + pinned deps, .env from templates, key validation, .env.secrets handling; `verify` health check (ports, imports, builds); `dev` thin passthrough to scripts/dev.sh | critical | 1 | complete |
+
+### Distribution
+
+| ID | Description | Priority | Phase | Status |
+|----|-------------|----------|-------|--------|
+| REQ-4-003 | One-liner install script (`curl -fsSL <url> \| bash`): detects linux x64, resolves latest release from Gitea API, downloads binary + checksum, verifies sha256, installs to ~/.local/bin (PATH hint), degrades to source-bootstrap instructions when no binary | critical | 2 | complete |
+| REQ-4-004 | Binary release pipeline: reproducible linux x64 build script, sha256 checksum sidecar, upload as release assets on every ship from v0.4 onward (ongoing binaries requirement) | critical | 2 | complete |
+| REQ-4-005 | Install + quickstart documentation: README one-liner quickstart, CLI command reference, fresh-clone-to-running-stack end-to-end verification | high | 3 | complete |
+
 ## v0.3 Requirements (Credential Engines)
 
 ### Sandbox & Telemetry
@@ -8,22 +150,22 @@
 |----|-------------|----------|-------|--------|
 | REQ-3-001 | Sandbox fabric: isolated per-learner execution environments (sandboxed IDE, design tool, simulation) with lifecycle management | critical | 1 | complete |
 | REQ-3-002 | Sandbox isolation + resource limits: per-learner isolation boundary, CPU/memory quotas (rlimits), wall-clock time quota, disk-quota via per-sandbox workdir usage sweep (best-effort, not kernel-enforced), no cross-tenant access, snapshot support. **Known gap (v0.3): per-sandbox pids and hard disk caps are NOT kernel-enforceable without cgroup delegation/sudo — documented as accepted risk** | critical | 1 | complete |
-| REQ-3-003 | Live build telemetry: in-environment capture of process events (commands, file diffs, run/test results, activity) streamed reliably to ai-service with per-learner trace persistence | critical | 2 | pending |
+| REQ-3-003 | Live build telemetry: in-environment capture of process events (commands, file diffs, run/test results, activity) streamed reliably to ai-service with per-learner trace persistence | critical | 2 | complete |
 
 ### Credential Engines
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-3-004 | Process-trace grading engine: grade artifacts from their full process traces; rubric-aligned structured scores; feeds Assessor real inputs | critical | 3 | pending |
-| REQ-3-005 | Variant task generation: per-learner task variants (no two learners get identical prompts); variant seed registry; difficulty normalization | high | 4 | pending |
-| REQ-3-006 | Oral/voice defense: AI examiner conducts spoken defense (STT → dialogue → TTS); transcript + integrity signals captured; feeds Proctor/Mentor | high | 5 | pending |
+| REQ-3-004 | Process-trace grading engine: grade artifacts from their full process traces; rubric-aligned structured scores; feeds Assessor real inputs | critical | 3 | complete |
+| REQ-3-005 | Variant task generation: per-learner task variants (no two learners get identical prompts); variant seed registry; difficulty normalization | high | 4 | complete |
+| REQ-3-006 | Oral/voice defense: AI examiner conducts spoken defense (STT → dialogue → TTS); transcript + integrity signals captured; feeds Proctor/Mentor | high | 5 | complete |
 
 ### Agent Re-grounding & Integration
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-3-007 | Agent re-grounding: Lab consumes live telemetry; Assessor consumes grading-engine output; Proctor consumes telemetry + defense integrity signals (replace v0.2 mocks) | critical | 6 | pending |
-| REQ-3-008 | Learner surface integration: sandbox mockup → real in-browser build/run with live telemetry; assessment mockup → live defense + live grading | critical | 6 | pending |
+| REQ-3-007 | Agent re-grounding: Lab consumes live telemetry; Assessor consumes grading-engine output; Proctor consumes telemetry + defense integrity signals (replace v0.2 mocks) | critical | 6 | complete |
+| REQ-3-008 | Learner surface integration: sandbox mockup → real in-browser build/run with live telemetry; assessment mockup → live defense + live grading | critical | 6 | complete |
 
 ---
 
@@ -65,58 +207,58 @@
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
 | REQ-001 | Monorepo scaffolding: pnpm workspaces, turborepo, Next.js app, TypeScript config, ESLint, Prettier | critical | 1 | complete |
-| REQ-002 | Shared component library: design tokens, Button, Input, Card, Badge, Avatar, Dialog, Navigation, Table, Tabs, Progress, Tooltip, Skeleton, Toast | critical | 1 | pending |
-| REQ-003 | Mock data layer: typed mock data for competency stacks, job listings, candidate profiles, employers, learner progress | critical | 1 | pending |
-| REQ-004 | Routing and navigation: App Router route groups for (learner), (marketplace), (employer), (admin); shared layout components; cross-surface navigation | critical | 1 | pending |
-| REQ-005 | Responsive layout system: mobile, tablet, desktop breakpoints; container components; grid system | high | 1 | pending |
+| REQ-002 | Shared component library: design tokens, Button, Input, Card, Badge, Avatar, Dialog, Navigation, Table, Tabs, Progress, Tooltip, Skeleton, Toast | critical | 1 | complete |
+| REQ-003 | Mock data layer: typed mock data for competency stacks, job listings, candidate profiles, employers, learner progress | critical | 1 | complete |
+| REQ-004 | Routing and navigation: App Router route groups for (learner), (marketplace), (employer), (admin); shared layout components; cross-surface navigation | critical | 1 | complete |
+| REQ-005 | Responsive layout system: mobile, tablet, desktop breakpoints; container components; grid system | high | 1 | complete |
 
 ### Learner Surface
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-006 | Landing page: hero, value proposition, program highlights, how-it-works (Byte→Build→Demonstrate→Defend), testimonials mockup, CTA to program catalog | critical | 2 | pending |
-| REQ-007 | Program catalog: grid of competency stacks (AI Orchestration Engineer, AI Safety & Governance Lead, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences Practitioner); stack cards with role descriptions | critical | 2 | pending |
-| REQ-008 | Competency stack view: selected stack detail with 12-18 competencies listed, progress indicators, microcredential badges, mastery status | critical | 2 | pending |
-| REQ-009 | Learner dashboard: active competencies, progress graph, recent artifacts, upcoming defenses, AI tutor chat mockup, milestone tracker | critical | 2 | pending |
-| REQ-010 | Byte tutorial viewer: 3-7 minute micro-tutorial layout with concept panel, worked example panel, code/design/simulation viewer mockup | high | 2 | pending |
-| REQ-011 | Build sandbox mockup: sandboxed IDE/design tool/simulation UI mockup with toolbar, file explorer, editor area, telemetry sidebar (process capture indicators) | high | 2 | pending |
-| REQ-012 | Assessment/defense mockup: rubric display, AI reviewer panel, oral defense interface (voice/mic mockup), process trace timeline, artifact viewer | high | 2 | pending |
+| REQ-006 | Landing page: hero, value proposition, program highlights, how-it-works (Byte→Build→Demonstrate→Defend), testimonials mockup, CTA to program catalog | critical | 2 | complete |
+| REQ-007 | Program catalog: grid of competency stacks (AI Orchestration Engineer, AI Safety & Governance Lead, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences Practitioner); stack cards with role descriptions | critical | 2 | complete |
+| REQ-008 | Competency stack view: selected stack detail with 12-18 competencies listed, progress indicators, microcredential badges, mastery status | critical | 2 | complete |
+| REQ-009 | Learner dashboard: active competencies, progress graph, recent artifacts, upcoming defenses, AI tutor chat mockup, milestone tracker | critical | 2 | complete |
+| REQ-010 | Byte tutorial viewer: 3-7 minute micro-tutorial layout with concept panel, worked example panel, code/design/simulation viewer mockup | high | 2 | complete |
+| REQ-011 | Build sandbox mockup: sandboxed IDE/design tool/simulation UI mockup with toolbar, file explorer, editor area, telemetry sidebar (process capture indicators) | high | 2 | complete |
+| REQ-012 | Assessment/defense mockup: rubric display, AI reviewer panel, oral defense interface (voice/mic mockup), process trace timeline, artifact viewer | high | 2 | complete |
 
 ### Marketplace Surface
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-013 | Job board listing: searchable grid of AI-era job listings, filter sidebar (skills, seniority, location, salary), result cards with match score | critical | 3 | pending |
-| REQ-014 | Job detail page: full job description, required competencies, employer info, application CTA, related jobs, AI-matched skills breakdown | critical | 3 | pending |
-| REQ-015 | Employer profile: company overview, logo, description, social links, open positions, company culture mockup | high | 3 | pending |
-| REQ-016 | Search/filter UI: semantic search bar, skill tags, category filters, seniority filter, remote/on-site toggle, saved searches mockup | critical | 3 | pending |
-| REQ-017 | Pricing page: job posting packages (single, bundle, enterprise), talent access plans, subscription tiers, feature comparison table | high | 3 | pending |
+| REQ-013 | Job board listing: searchable grid of AI-era job listings, filter sidebar (skills, seniority, location, salary), result cards with match score | critical | 3 | complete |
+| REQ-014 | Job detail page: full job description, required competencies, employer info, application CTA, related jobs, AI-matched skills breakdown | critical | 3 | complete |
+| REQ-015 | Employer profile: company overview, logo, description, social links, open positions, company culture mockup | high | 3 | complete |
+| REQ-016 | Search/filter UI: semantic search bar, skill tags, category filters, seniority filter, remote/on-site toggle, saved searches mockup | critical | 3 | complete |
+| REQ-017 | Pricing page: job posting packages (single, bundle, enterprise), talent access plans, subscription tiers, feature comparison table | high | 3 | complete |
 
 ### Employer Dashboard
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-018 | Employer dashboard overview: active postings, applicant pipeline, talent matches, analytics mockup (charts, placement stats) | critical | 4 | pending |
-| REQ-019 | Talent search: searchable candidate database with AI-matched filters, candidate cards showing competency stack, microcredentials, artifact count, defense score | critical | 4 | pending |
-| REQ-020 | Candidate profile view: full candidate profile with artifact gallery, process trace summary, oral defense transcripts, competency graph, microcredential verification | high | 4 | pending |
-| REQ-021 | Posting management: create/edit/delete job postings, posting status tracking, applicant list per posting, interview pipeline mockup | high | 4 | pending |
+| REQ-018 | Employer dashboard overview: active postings, applicant pipeline, talent matches, analytics mockup (charts, placement stats) | critical | 4 | complete |
+| REQ-019 | Talent search: searchable candidate database with AI-matched filters, candidate cards showing competency stack, microcredentials, artifact count, defense score | critical | 4 | complete |
+| REQ-020 | Candidate profile view: full candidate profile with artifact gallery, process trace summary, oral defense transcripts, competency graph, microcredential verification | high | 4 | complete |
+| REQ-021 | Posting management: create/edit/delete job postings, posting status tracking, applicant list per posting, interview pipeline mockup | high | 4 | complete |
 
 ### Admin Surface
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-022 | Admin overview: platform metrics (learners, employers, placements, completion rate, NPS), recent activity feed, system health mockup | critical | 5 | pending |
-| REQ-023 | Learner management: searchable learner table, learner detail view, progress tracking, competency completion status, credential issuance log | high | 5 | pending |
-| REQ-024 | Competency graph viewer: interactive visualization of competency stacks and their relationships, node/edge graph using react-flow, stack details on node click | high | 5 | pending |
-| REQ-025 | Marketplace moderation: job posting review queue, employer verification queue, flagged content, content moderation tools mockup | high | 5 | pending |
+| REQ-022 | Admin overview: platform metrics (learners, employers, placements, completion rate, NPS), recent activity feed, system health mockup | critical | 5 | complete |
+| REQ-023 | Learner management: searchable learner table, learner detail view, progress tracking, competency completion status, credential issuance log | high | 5 | complete |
+| REQ-024 | Competency graph viewer: interactive visualization of competency stacks and their relationships, node/edge graph using react-flow, stack details on node click | high | 5 | complete |
+| REQ-025 | Marketplace moderation: job posting review queue, employer verification queue, flagged content, content moderation tools mockup | high | 5 | complete |
 
 ### Polish & Integration
 
 | ID | Description | Priority | Phase | Status |
 |----|-------------|----------|-------|--------|
-| REQ-026 | Cross-surface navigation: role switcher (learner/employer/admin), breadcrumbs, consistent header/footer across all surfaces | critical | 6 | pending |
-| REQ-027 | Visual consistency audit: typography scale, color palette, spacing system, dark mode toggle, accessibility baseline (WCAG AA contrast) | high | 6 | pending |
-| REQ-028 | Component library finalization: Storybook setup, component documentation, prop tables, usage examples | medium | 6 | pending |
+| REQ-026 | Cross-surface navigation: role switcher (learner/employer/admin), breadcrumbs, consistent header/footer across all surfaces | critical | 6 | complete |
+| REQ-027 | Visual consistency audit: typography scale, color palette, spacing system, dark mode toggle, accessibility baseline (WCAG AA contrast) | high | 6 | complete |
+| REQ-028 | Component library finalization: Storybook setup, component documentation, prop tables, usage examples | medium | 6 | complete |
 
 ---
 
@@ -136,18 +278,18 @@
 
 | ID | Description | Priority | Milestone | Status |
 |----|-------------|----------|-----------|--------|
-| REQ-F-011 | AI job aggregation pipeline (3M+ jobs from 120K companies) | high | v0.4+ | deferred |
-| REQ-F-012 | AI-powered tagging (skills, categories, seniority) | high | v0.4+ | deferred |
-| REQ-F-013 | Semantic vector search for role matching | high | v0.4+ | deferred |
-| REQ-F-014 | AI company enrichment (logos, descriptions, social links) | medium | v0.4+ | deferred |
-| REQ-F-015 | AI resume parsing (profile auto-fill) | medium | v0.4+ | deferred |
-| REQ-F-016 | SEO-optimized programmatic pages | medium | v0.4+ | deferred |
+| REQ-F-011 | AI job aggregation pipeline (3M+ jobs from 120K companies) | high | v0.6 | activated → REQ-6-001 (pilot-scaled; adapter contract preserves full scale) |
+| REQ-F-012 | AI-powered tagging (skills, categories, seniority) | high | v0.6 | activated → REQ-6-002 |
+| REQ-F-013 | Semantic vector search for role matching | high | v0.6 | activated → REQ-6-003 |
+| REQ-F-014 | AI company enrichment (logos, descriptions, social links) | medium | v0.6 | activated → REQ-6-004 |
+| REQ-F-015 | AI resume parsing (profile auto-fill) | medium | v0.6 | activated → REQ-6-005 |
+| REQ-F-016 | SEO-optimized programmatic pages | medium | v0.6 | activated → REQ-6-006 |
 
 ### Platform Infrastructure
 
 | ID | Description | Priority | Milestone | Status |
 |----|-------------|----------|-----------|--------|
-| REQ-F-017 | Identity verification and age-gating (16+/18+) — real KYC backend | high | v0.4+ | deferred (deferred from v0.3 per founder directive) |
+| REQ-F-017 | Identity verification and age-gating (16+/18+) — real KYC backend | high | v0.5 | activated → complete (REQ-5-003/004) |
 | REQ-F-018 | Payment processing and subscription management | high | v0.3+ | deferred |
 | REQ-F-019 | Human tutor marketplace (third-party courses) | medium | v0.4+ | deferred |
 | REQ-F-020 | CIRR-style placement tracking and audit | medium | v0.5+ | deferred |
@@ -170,18 +312,51 @@
 
 ## Traceability Matrix
 
-### v0.3 (current milestone)
+### v0.6 (complete)
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| REQ-6-001 | 1 | complete |
+| REQ-6-002 | 2 | complete |
+| REQ-6-003 | 3 | complete |
+| REQ-6-004 | 4 | complete |
+| REQ-6-005 | 4 | complete |
+| REQ-6-006 | 5 | complete |
+
+### v0.5 (complete)
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| REQ-5-007 | 1 | complete |
+| REQ-5-001 | 2 | complete |
+| REQ-5-002 | 2 | complete |
+| REQ-5-003 | 3 | complete |
+| REQ-5-004 | 3 | complete |
+| REQ-5-005 | 4 | complete |
+| REQ-5-006 | 4 | complete |
+
+### v0.4 (complete)
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| REQ-4-001 | 1 | complete |
+| REQ-4-002 | 1 | complete |
+| REQ-4-003 | 2 | complete |
+| REQ-4-004 | 2 | complete |
+| REQ-4-005 | 3 | complete |
+
+### v0.3 (complete)
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
 | REQ-3-001 | 1 | complete |
 | REQ-3-002 | 1 | complete |
-| REQ-3-003 | 2 | pending |
-| REQ-3-004 | 3 | pending |
-| REQ-3-005 | 4 | pending |
-| REQ-3-006 | 5 | pending |
-| REQ-3-007 | 6 | pending |
-| REQ-3-008 | 6 | pending |
+| REQ-3-003 | 2 | complete |
+| REQ-3-004 | 3 | complete |
+| REQ-3-005 | 4 | complete |
+| REQ-3-006 | 5 | complete |
+| REQ-3-007 | 6 | complete |
+| REQ-3-008 | 6 | complete |
 
 ### v0.2 (complete)
 
@@ -231,4 +406,4 @@
 | REQ-025 | 5 | complete |
 | REQ-026 | 6 | complete |
 | REQ-027 | 6 | complete |
-| REQ-028 | 6 | complete |
+| REQ-028 | 6 | complete |

.ciagent/RESEARCH.md

@@ -0,0 +1,699 @@
+# Nextcraft — RESEARCH.md (v0.8 Phase 0 RESEARCH — Ship Anywhere)
+
+Probe-verified census of the release/distribution surface, 2026-09-27.
+Every conclusion carries evidence (file paths probed in this repo, live HTTP
+probes, upstream docs). Binding founder decisions D-063..D-072 are NOT
+re-litigated; this research operationalizes them. Upstream docs consulted:
+docs.gitea.com runner 3.x (install/labels/configuration/cache/registration),
+Gitea Actions design/FAQ/comparison/secrets/token-permissions/container-registry,
+postject README, nodejs.org dist index. Live probes against the actual
+instance: `git.coreci.dev` reports **Gitea 1.26.1** (`/api/v1/version`), the
+OCI registry endpoint `/v2/` is live (401 unauth = up), the latest release
+(v0.6.6, id 909) carries `nextcraft-linux-x64` + `.sha256`.
+
+---
+
+## R-1..R-7 — Runner fleet on CT 113 (question 1)
+
+**R-1. Use the `docker.io/gitea/runner:3` image, not `gitea/act_runner`.**
+The Docker Hub `gitea/act_runner` repository is marked *Deprecated Gitea
+runner. Moved to gitea/runner* (hub.docker.com/r/gitea/act_runner, last push
+5 months ago); the current series is runner `3.x` (docs dropdown: develop /
+3.3.0 / 2.3.0 / 1.0.8 / 0.6.1) with the binary renamed `gitea-runner`. The
+founder's "gitea/act_runner docker containers" intent (PROJECT.md line 28)
+maps to the renamed official image. Pin `gitea/runner:3` (follows newest
+3.x); runner versioning is independent of Gitea's and requires Gitea ≥1.21 —
+1.26.1 is fine. The *basic* flavour (alpine base, no bundled daemon, tini,
+root) is exactly sibling mode: jobs share the host daemon via the mounted
+socket. The `dind` flavours are NOT wanted (D-decision: sibling mode).
+
+**R-2. Concrete compose shape (3 sibling containers, one per lane).**
+Each runner needs its OWN `/data` volume (holds the `.runner` registration
+file + config; two runners sharing one file refuse to start via an advisory
+lock) and the host socket:
+
+```yaml
+# /srv/nc-ci/docker-compose.yaml on CT 113 (10.0.0.113)
+x-runner-base: &runner-base
+  image: docker.io/gitea/runner:3
+  restart: always
+  environment:
+    GITEA_INSTANCE_URL: "https://git.coreci.dev"
+    GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"  # founder-provided, NEVER committed
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock
+    - ./data:/data            # per-runner, see below
+    - ./cache:/data-cache     # optional shared actcache mount (R-5 alt)
+
+services:
+  runner-node:
+    <<: *runner-base
+    container_name: nc-runner-node
+    environment:
+      GITEA_INSTANCE_URL: "https://git.coreci.dev"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "nc-runner-node"
+      GITEA_RUNNER_LABELS: "node:docker://node:24-bookworm,ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./data-runner-node:/data
+
+  runner-python:
+    <<: *runner-base
+    container_name: nc-runner-python
+    environment:
+      GITEA_INSTANCE_URL: "https://git.coreci.dev"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "nc-runner-python"
+      GITEA_RUNNER_LABELS: "python:docker://python:3.11-bookworm"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./data-runner-python:/data
+
+  runner-release:
+    <<: *runner-base
+    container_name: nc-runner-release
+    environment:
+      GITEA_INSTANCE_URL: "https://git.coreci.dev"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "nc-runner-release"
+      GITEA_RUNNER_LABELS: "release:docker://node:24-bookworm"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./data-runner-release:/data
+```
+
+(YAML anchors with per-service volume overrides: write volumes per service
+explicitly — compose merges maps; keep the literal per-service form in the
+final guide.) The entrypoint registers on first start (when `/data/.runner`
+absent), unsets the registration token from the env, then execs
+`gitea-runner daemon`. Org-level scope comes from the TOKEN itself
+(obtained at `/org/coreci/settings/actions/runners`) — one token registers
+all three and stays valid until reset (founder directive: reset after the
+fleet is green).
+
+**R-3. Labels: `GITEA_RUNNER_LABELS` env, not config file, for first
+registration.** Format `name[:schema[:args]]`, comma-separated; our shapes
+are all `docker://<image>`. Precedence (runner docs, Labels):
+`--labels`/`GITEA_RUNNER_LABELS` > `runner.labels` in the config file >
+labels stored in `.runner`; the entrypoint passes `GITEA_RUNNER_LABELS` to
+both `register` and `daemon`, and later label changes are written back and
+re-declared without re-registering. The hybrid-label fleet map (above):
+`node` = node:24-bookworm; `python` = python:3.11-bookworm; `release` =
+node:24-bookworm (the release job needs node + dpkg-deb + git + curl —
+bookworm ships dpkg-deb and git; docker CLI installed in-job, R-21);
+`ubuntu-latest` = `docker.gitea.com/runner-images:ubuntu-latest` (official
+Gitea runner image; community `catthehacker/ubuntu:act-latest` is the
+documented alternative) carried by runner-node so the dispatch
+verification lane (REQ-8-001) has a generic home. A job whose `runs-on`
+matches NO runner label still runs, on the runner's default image — always
+pin our own labels (runner docs: "first match wins… unmatched jobs run in
+the default image").
+
+**R-4. Capacity = 1 per runner (config default), giving fleet concurrency 3.**
+`runner.capacity` default is `1` in the example config; with
+`container.network` empty each concurrent docker job takes a subnet from
+the daemon address pool, so 1-per-runner is also the safe default for the
+docker daemon. One config file per runner is optional — defaults are safe;
+if we mount one, set only what deviates:
+
+```yaml
+# config-runner-release.yaml (mounted at /config.yaml + CONFIG_FILE=/config.yaml)
+runner:
+  capacity: 1
+  timeout: 3h          # Gitea instance also enforces 3h default
+cache:
+  enabled: true
+  host: "10.0.0.113"    # R-5 — job containers must reach the cache server
+  port: 8088
+health_check:
+  enabled: true
+  min_free_disk_space_mb: 4096   # half the disk floor for a 32 GB CT
+```
+
+**R-5. Cache + 32 GB disk hygiene.** Every runner starts its own cache
+server (`actions/cache` works with zero config), but a dockerized runner
+creates a per-job network, so the auto-detected cache address is
+UNREACHABLE from job containers → `actions/cache` fails with
+`connect ETIMEDOUT` (runner docs, Caching → Dockerized runners). Concrete
+fix: set `cache.host` to an address job containers can reach (CT 113's own
+IP/hostname — NOT `0.0.0.0`, invalid) + `cache.port` to a fixed port and
+publish it from the runner container (`-p 8081:8088` etc., one per runner),
+or put job containers on a shared `container.network`. Disk caps for the
+32 GB CT: `cache.retention: 168h` (default), `cache.repo_size_limit: 10GB`
+(default), plus `health_check.enabled: true` + `min_free_disk_space_mb`
+(pausing new-task fetch when low). Host-side cron per REQ-8-001:
+`docker system prune -af --filter until=168h` + `docker volume prune -f`
+daily; the runner's own idle cleanup (workdir_cleanup_age 24h,
+idle_cleanup_interval 10m) removes stale workspaces and orphaned per-job
+networks by itself. A shared cache across runners via
+`gitea-runner cache-server` + `external_server`/`external_secret` is
+available later; not needed at fleet size 3.
+
+**R-6. `/data` volume is the only per-runner state that matters.** It holds
+the `.runner` registration file (identity + API credentials). Losing it =
+re-registration as a NEW runner + stale entry + outright failure if the
+token was reset (runner docs, Registration). So: named dirs per runner
+(`data-runner-{node,python,release}/`), persisted on the CT; the token is
+NEVER written to any repo file (compose reads it from an env var on the CT
+or a `.env` beside the compose file, founder-provided out-of-band).
+
+**R-7. Sibling-mode path alignment: NOT needed for our workloads.** The
+alignment requirement ("identical paths inside/outside the runner
+container") applies only when workflows bind-mount the workspace into
+sibling containers (`container.bind_workdir: true` — e.g.
+`docker run -v "$PWD":/app`). Our jobs (a) run plain build/test commands in
+the job container, (b) run `docker build` in the release lane — `docker
+build` TARS UP the context dir inside the job container and streams it to
+the daemon over the API, so the daemon never needs to resolve the workspace
+path. By default the runner creates the workspace as a docker volume,
+mounts it at `/workspace` in the job container, and (with
+`container.docker_host` empty) auto-detects the host daemon and mounts
+`/var/run/docker.sock` INTO job containers + sets `DOCKER_HOST` — docker
+CLI in the job just works. If a future workflow needs sibling bind mounts,
+flip `container.bind_workdir: true` + mount the workspace parent into the
+runner container at the IDENTICAL host path + allow it in
+`container.valid_volumes` (glob syntax) — document in the admin guide as
+the known sibling-mode gotcha.
+
+---
+
+## R-8..R-15 — Workflow syntax + CI lanes (questions 2–3)
+
+**R-8. Workflows live at `.gitea/workflows/*.yaml`** (`.github/workflows`
+also honored; we use `.gitea/`). `runs-on` values match label NAMES; a
+label's `docker://` image selects the job container. Gitea-specific
+extensions exist (absolute action URLs, `@daily` schedules) but the
+core syntax is GitHub-compatible. Supported triggers include `push` (with
+`tags:` filters) and `release`, plus `workflow_dispatch` — the FAQ's event
+table confirms `push`/`create`/`release` all supported on 1.26.
+Recommended triggers: push lane `on: push` (all branches; the fleet is
+private to the org), release lane `on: push: tags: ['v*']`.
+
+**R-9. Lanes are plain `run:` steps — zero external actions required
+(except checkout).** Every CI command already exists as a repo script
+(root package.json: `web:test`, `cli:test`, `ai:test:fast`, turbo lint /
+typecheck tasks; apps/ai-service/scripts/{lint,typecheck,test}.sh are
+self-contained venv-relative bash). `actions/checkout@v4` is the one stock
+action worth keeping (shallow fetch of the triggering ref); it downloads
+from github.com by default (`DEFAULT_ACTIONS_URL=github` since 1.21) so the
+CT needs internet — Connection 3/4 in the Actions design doc. If CT 113 has
+no internet: set the instance's `DEFAULT_ACTIONS_URL=self` + mirror
+actions, or replace checkout with a raw `git fetch` step using the
+auto-provided `GITHUB_TOKEN`. Concrete lanes:
+
+```yaml
+# node lane (runner label: node → container node:24-bookworm)
+- run: corepack enable && corepack prepare pnpm@12.3.4 --activate
+- run: pnpm install --frozen-lockfile
+- run: pnpm --filter web --filter @nextcraft/cli --filter @nextcraft/ui
+       --filter @nextcraft/types --filter @nextcraft/mock-data lint
+- run: pnpm --filter web --filter @nextcraft/cli --filter @nextcraft/ui
+       --filter @nextcraft/types --filter @nextcraft/mock-data typecheck
+- run: pnpm web:test    # tsx --test tests/*.test.ts (node:test)
+- run: pnpm cli:test    # E2E stays env-gated OUT (D-055/D-063)
+```
+
+```yaml
+# python lane (runner label: python → container python:3.11-bookworm)
+- run: bash apps/ai-service/scripts/bootstrap.sh   # venv + pip install -e .[dev]
+- run: bash apps/ai-service/scripts/lint.sh        # ruff check .
+- run: bash apps/ai-service/scripts/typecheck.sh    # mypy (D-058 baseline)
+- run: FAST=1 bash apps/ai-service/scripts/test.sh  # -m "not real_server and not userns" (D-063)
+```
+
+Note the lane split is FORCED by the repo's own scripts: `turbo lint` /
+`turbo typecheck` include `ai-service#lint/typecheck`, which require the
+venv (scripts/lint.sh:8, typecheck.sh:13 refuse without it) — so the python
+lane invokes the three bash scripts DIRECTLY (no pnpm needed in that
+container at all), and the node lane invokes eslint/tsc per TS workspace
+(`pnpm --filter <5 TS workspaces>`), never `turbo lint` wholesale. This
+matches D-063 exactly: fast pytest lane, default web/cli node:test,
+`real_server`/`userns` never in job containers (also genuinely BLOCKED
+there — docker's default seccomp denies the nested `unshare --user` the
+backend needs; the userns suites stay local/verify-lane surfaces).
+
+**R-10. ubuntu-latest lane = dispatch verification only.** Nothing in the
+CI matrix needs the generic image for correctness (node/python cover the
+lanes; release needs node:24-bookworm per R-3). The ubuntu-latest label
+exists to satisfy REQ-8-001's hello-world dispatch verification across all
+three runners — a workflow_dispatch-triggered one-step job per label
+(`runs-on: [node|python|ubuntu-latest]`, `run: echo ok`), proving each
+runner registers, pulls, and executes.
+
+**R-11. Toolchain/base-image recommendations.** `node:24-bookworm`
+(production runs v24.15.0; engines node≥20; bookworm = Debian 12, ships
+git/curl/dpkg-deb), pnpm 12.3.4 via **corepack** (root package.json
+`packageManager: "pnpm@12.3.4"` pins it; `corepack enable pnpm` is the
+doctor's own hint, doctor.ts:42) — probe in P1 that node:24-bookworm still
+bundles corepack (Node ≥25 dropped it; 24.x retains it, deprecated) and
+fall back to `npm i -g pnpm@12.3.4` if not. `python:3.11-bookworm`
+(requires-python ≥3.11; production 3.11.2; the venv script's
+`--without-pip` + get-pip fallback, bootstrap.sh:34-71, covers
+Debian-without-ensurepip, though the full image has ensurepip).
+`docker.gitea.com/runner-images:ubuntu-latest` for the generic label
+(official, small; `catthehacker/ubuntu:act-latest` documented as the
+community alternative). Pin by tag — the runner docs advise pinned tags
+for reproducible jobs; our lanes pin exact image tags in the compose
+labels.
+
+**R-12. pnpm/pip caching strategy.** Primary: `actions/cache@v4` is
+Gitea-compatible on runner 3.x (runner serves the cache v2 API and
+self-patches the stock action ≥v4.2; `actions/upload-artifact` ≥v4.4.0
+likewise patched by the runner) — but ONLY works once R-5's
+`cache.host`+published-port fix is live on the dockerized fleet. Concrete
+steps: cache `~/.local/share/pnpm/store` keyed on `pnpm-lock.yaml` hash
+(pnpm 12 default store dir; verify with `pnpm store path` in-job) and
+`~/.cache/pip` keyed on `apps/ai-service/pyproject.toml` hash. Fallback if
+cache networking proves flaky in P1: mount a host dir into job containers
+as the store via `container.options: --volume /srv/nc-ci/pnpm-store:/root/.local/share/pnpm/store`
+(listed in `container.valid_volumes`) — deterministic, no cache server
+involved. The venv itself is cheap (~40s with warm pip cache) and not
+worth caching.
+
+**R-13. Secrets: `${{ secrets.REGISTRY_TOKEN }}` + `${{ secrets.GITEA_TOKEN }}`.**
+Gitea 1.26 supports repo- and org-level Actions secrets (names alphanumeric
++ underscore, not starting with `GITEA_`/`GITHUB_`/digit, case-insensitive);
+precedence lowest-level wins. The self-serve PUT exists:
+`PUT /api/v1/repos/{owner}/{repo}/actions/secrets/{secretname}` with
+`{"data": "..."}` (probed: 401 unauthenticated — auth'd PUT is the
+self-serve path per D-064; founder UI fallback if the token's scope can't
+PUT secrets). CRITICAL upstream fact: the automatic per-job `GITEA_TOKEN`
+CANNOT publish packages — "Package repository authorization… is not
+implemented in Gitea Actions now. A workaround… is to use a Personal
+Access Token" (Actions comparison doc, confirmed by the token-permissions
+page). So the registry push MUST use the `REGISTRY_TOKEN` secret (a PAT
+with package write), exactly as D-064 specifies. The job token's `releases`
+scope CAN create releases/attach assets, but D-064 pins the `GITEA_TOKEN`
+secret (PAT) as the release owner too — one credential class, founder-set.
+
+**R-14. Release assets attach via the REST API — the same call
+scripts/release-assets.sh already makes.** Evidence:
+scripts/release-assets.sh:32-49 resolves the release id via
+`GET /repos/coreci/nextcraft/releases/tags/{tag}` then POSTs multipart to
+`/repos/{owner}/{repo}/releases/{id}/assets?name={asset}` — that API works
+from a workflow with `secrets.GITEA_TOKEN` verbatim. `actions/upload-artifact`
+is a DIFFERENT mechanism (job artifacts via the runner's cache server, not
+release downloads) — do NOT use it for release files. `tea` CLI is
+unnecessary. The tag-triggered workflow therefore: build all assets from
+the tag checkout → reuse the script's upload function (env-resolved token:
+the workflow exports the secret into the script's env — NOTE the script
+currently resolves tokens from .env files ONLY by design
+(release-assets.sh:15-25, "v1.8 root cause"); for workflow use either
+(a) call the API directly in a workflow step, or (b) extend the script with
+an explicit `GITEA_TOKEN` env override flagged for CI-only use. Recommend
+(a) for the workflow + script untouched as the manual fallback, per D-064's
+"script remains as the manual fallback (its .env-only token resolution
+unchanged)". Version stamping: `gitea.ref_name` (the tag, e.g. `v0.7.3`)
+feeds `build:binary <tag>` (build-binary.mjs:15-20 already validates + the
+installer verifies `--version == tag`, install.sh:83-85).
+
+**R-15. Event triggers + ref semantics.** `on: push` fires per branch
+push (lane runs on any branch — founder scope: "a push to any branch runs
+lint/typecheck/tests"); `on: push: tags: ['v*']` fires the release lane on
+tag push only. `gitea.ref_name` = tag name on tag events. The release
+lane builds from the tag checkout (checkout@v4 with the triggering ref)
+— dist/ artifacts never exist in a fresh job workspace, which is exactly
+why D-064 made the workflow the exclusive release maker.
+
+---
+
+## R-16..R-21 — Dockerfile + registry push (questions 4–5)
+
+**R-16. Multi-stage Dockerfile shape for THIS repo.** No Dockerfile exists
+today (probe: no Dockerfile/.dockerignore in the tree). The build is
+verified against the actual scripts:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+# Stage 1 — web export (NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build, deploy/README.md:33)
+FROM node:24-bookworm AS web
+WORKDIR /repo
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml .npmrc ./
+COPY apps/web/package.json apps/web/
+COPY apps/ai-service/package.json apps/ai-service/
+COPY apps/cli/package.json apps/cli/
+COPY packages/ui/package.json packages/ui/
+COPY packages/types/package.json packages/types/
+COPY packages/mock-data/package.json packages/mock-data/
+RUN corepack enable && corepack prepare pnpm@12.3.4 --activate \
+ && pnpm install --frozen-lockfile
+COPY . .
+RUN NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build     # turbo build → apps/web/out (16 MB, probe-verified)
+
+# Stage 2 — ai-service venv (prod deps only; scripts/bootstrap.sh semantics)
+FROM python:3.11-bookworm AS venv
+COPY apps/ai-service /src/apps/ai-service
+RUN python3 -m venv /opt/venv \
+ && /opt/venv/bin/pip install --no-cache-dir --upgrade pip \
+ && /opt/venv/bin/pip install --no-cache-dir /src/apps/ai-service \
+ && sed -i 's|--mount=old-styleeditable --no-index ||' /opt/venv/pyvenv.cfg || true
+# (non-editable install keeps the runtime image path-stable; if editable
+#  install is preferred for exact-parity with dev.sh, COPY the source to the
+#  same /src path in the runtime stage instead — pip install -e bakes the path)
+
+# Stage 3 — runtime (single-port: uvicorn serves API + export; D-039/D-066)
+FROM python:3.11-slim-bookworm
+RUN useradd --system --create-home nextcraft
+COPY --from=venv /opt/venv /opt/venv
+COPY --from=web /repo/apps/web/out /opt/nextcraft/web
+COPY apps/cli/dist/nextcraft-linux-x64 /usr/local/bin/nextcraft   # D-066 embed
+COPY apps/ai-service/ai_service /opt/nextcraft/ai_service         # source for exec + editable parity
+ENV PATH=/opt/venv/bin:$PATH \
+    AI_WEB_STATIC_DIR=/opt/nextcraft/web \
+    AI_HOST=0.0.0.0 \
+    NC_CONTAINER=1
+RUN mkdir -p /home/nextcraft/.nextcraft && chown -R nextcraft:nextcraft \
+      /home/nextcraft/.nextcraft /opt/nextcraft
+USER nextcraft
+WORKDIR /opt/nextcraft
+EXPOSE 8420
+VOLUME /home/nextcraft/.nextcraft
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8420/health', timeout=4)" || exit 1
+CMD ["uvicorn", "ai_service.main:app", "--host", "0.0.0.0", "--port", "8420"]
+```
+
+Key facts baked from the code: `NEXT_PUBLIC_AI_SERVICE_URL=self` is
+BUILD-time only — engine-base-url.ts inlines it at build (relative
+same-origin fetches); zero AI_* env is needed at build. Runtime needs
+`AI_WEB_STATIC_DIR` (config.py:84, main.py:377 mounts StaticFiles) and
+nothing else mandatory — provider keys/admin token/public base URL are all
+optional with G-11 fallbacks (main.py:142-219). `.dockerignore` must allow
+`apps/web/out` is NOT copied (built in-stage) but must NOT exclude
+`apps/cli/dist/nextcraft-linux-x64` (the CLI embed input) — and the
+release workflow must build the binary BEFORE `docker build`. Healthcheck
+uses venv python urllib (slim has no curl); `/health` returns
+`{"status":"ok",...}` (main.py:286-292). Non-root `USER nextcraft` — but
+note `VOLUME` + chown ordering: chown BEFORE the VOLUME declaration to
+seed ownership (VOLUME after chown preserves it on named volumes' first
+use).
+
+**R-17. State volume mapping is env-overridable by design.** config.py:17
+`_STATE_ROOT = Path.home() / ".nextcraft"` → for USER nextcraft that is
+`/home/nextcraft/.nextcraft` (DB at `data/nextcraft.db`, sandbox workdirs
+at `sandboxes/`, config.py:39/77). Both `AI_DB_PATH` and `AI_SANDBOX_DIR`
+carry the `~`-expanduser validator (config.py:86-93) — operators can
+relocate freely. Volume recipe: `-v nc-state:/home/nextcraft/.nextcraft`.
+On the degraded userns path (R-24) the sandboxes/ subtree simply never
+gets populated.
+
+**R-18. Image size budget ≈ 400–500 MB.** python:3.11-slim-bookworm ≈
+120 MB base; prod venv (fastapi/uvicorn/pydantic/sqlmodel/httpx/pypdf etc.,
+NO dev extras) ≈ 130 MB (the dev venv with mypy/pytest-cov measures 179 MB
+on this box; prod-only is smaller); web export 16 MB (probed du);
+CLI binary ~117 MB (apps/cli/README.md:23, dist probe 118 MB — D-066 accepts
+it). Total well under the 32 GB CT disk and reasonable for `docker pull` on
+a LAN; document the budget in the guide with the breakdown table.
+
+**R-19. Unprivileged-by-default + honest degrade is already half-built.**
+The container needs no capabilities for the API/chat/grading path; the
+sandbox fabric (unshare --user --map-root-user) is BLOCKED by docker's
+default seccomp in an unprivileged container — that is D-068's whole
+premise. The privileged variant (`--privileged` or
+`--security-opt seccomp=unconfined` + userns tweaks) is the documented
+opt-in for full sandbox capability, per the founder decision.
+
+**R-20. Registry push mechanics = raw docker login + build + push.** The
+Gitea container registry follows `{registry}/{owner}/{image}` naming
+(docs: Container Registry) → `git.coreci.dev/coreci/nextcraft` is the ONLY
+addressable name (confirms D-065); the live endpoint probed at
+`https://git.coreci.dev/v2/` (401 unauth = serving). `docker/build-push-action`
+would drag buildx + GitHub-context assumptions for a single-arch amd64
+image we don't need (D-069: no multi-arch in v0.8). Concrete release steps
+(label `release`, container node:24-bookworm + `apt-get install -y
+--no-install-recommends docker.io` in-job — bookworm main ships docker.io;
+the runner mounts the host socket + DOCKER_HOST per R-7):
+
+```yaml
+- run: |
+    echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.coreci.dev -u coreci --password-stdin
+    docker build -t git.coreci.dev/coreci/nextcraft:${{ gitea.ref_name }} \
+                 -t git.coreci.dev/coreci/nextcraft:latest .
+    docker push git.coreci.dev/coreci/nextcraft:${{ gitea.ref_name }}
+    docker push git.coreci.dev/coreci/nextcraft:latest
+```
+
+Tag policy per D-065: semver tag per phase release + `latest` moved to the
+newest release; no per-push/branch tags. Note `docker.io` pull-through for
+the base images requires CT internet (node/python/slim from Docker Hub) —
+same Connection-3 assumption as R-8's checkout.
+
+**R-21. Sibling-mode job→daemon trust note for the guide.** Jobs reach the
+host daemon via the socket: a job (or a malicious workflow) COULD touch
+other containers/images on CT 113 (runner docs flag this trade-off on the
+basic flavour). Mitigations to document: fleet is org-scoped to coreci
+private repos (the gitea.com hardening recipe: org-level runners only,
+isolated containers, PR-approval gates for forks — our repo has no fork PRs);
+the CT hosts nothing else. This is an accepted-risk table row in the admin
+guide, not a code change.
+
+---
+
+## R-22..R-26 — deb packaging + arm64 cross-build (questions 6–7)
+
+**R-22. deb = dpkg-deb build of a staging tree; control fields concrete.**
+`dpkg-deb --build` exists on this box (1.21.23, probed) and never executes
+payload → cross-arch safe (D-069). Build script home: `scripts/build-deb.sh`
+(sibling of install.sh/release-assets.sh in scripts/). Layout:
+
+```
+stage/
+  DEBIAN/control
+  DEBIAN/postinst          # advisory doctor (D-067)
+  usr/bin/nextcraft        # the SEA binary
+  usr/share/doc/nextcraft/copyright
+  usr/share/doc/nextcraft/README.md.gz
+```
+
+control fields (per Debian policy, all satisfiable):
+`Package: nextcraft`, `Version: <tag minus leading v>` (e.g. v0.7.3 →
+0.7.3; upstream-version policy forbids leading `v`), `Section: utils`,
+`Priority: optional`, `Architecture: amd64|arm64` (passed by the workflow
+per build), `Maintainer: Nextcraft <founder@coreci.dev>`,
+`Depends:` — NOTHING hard (the binary is self-contained; doctor checks are
+advisory), `Recommends: nodejs (>= 18), python3 (>= 3.11), git,
+util-linux` (honest soft deps so `apt install` pulls the toolchain the CLI
+orchestrates without bricking unattended installs — the D-067 rationale),
+`Description: ...`. Build invocation:
+`dpkg-deb --root-owner-group -Zxz --build stage nextcraft_<ver>_<arch>.deb`
+(root-owner-group = deterministic ownership; xz default compression).
+Asset names: `nextcraft_<ver>_amd64.deb` / `nextcraft_<ver>_arm64.deb` +
+per-deb `.sha256` sidecars, attached by the tag workflow (D-064).
+
+**R-23. postinst = advisory doctor + next-steps, NEVER fails dpkg.**
+Concrete:
+
+```sh
+#!/bin/sh
+set -e
+echo "nextcraft: running advisory environment check (never blocks this install)…"
+if command -v nextcraft >/dev/null 2>&1; then
+  nextcraft doctor || echo "nextcraft: doctor reported issues above — advisory only."
+fi
+cat <<'EOF'
+Next steps:
+  nextcraft doctor    # full preflight (node, pnpm, python3, git, unshare)
+  nextcraft deploy --service   # one-command stack deploy (clone→build→restart→verify + systemd)
+EOF
+exit 0
+```
+
+`|| echo` keeps exit 0 through a failing doctor (D-067's "exit never fails
+the dpkg transaction" — the install.sh degradation pattern). NO systemd
+unit, NO proxy fragments in the deb (D-067: `deploy --service` owns unit
+generation with real paths).
+
+**R-24. install.sh: arch-gate → arch-resolve.** Current gate:
+`uname -s = Linux && uname -m = x86_64` else degrade (install.sh:19-25).
+Change: map `x86_64 → nextcraft-linux-x64`, `aarch64/arm64 →
+nextcraft-linux-arm64`, anything else keeps the source-bootstrap
+degradation. The asset/sum URL sed patterns (install.sh:40-41) gain an
+arch-parameterized asset name; the sha256-verify-BEFORE-install and
+`--version == tag` integrity gates (install.sh:64-85) stay byte-identical
+per arch. Keep POSIX sh (dash-safe).
+
+**R-25. arm64 cross-build: the ONLY arch-specific step in build-binary.mjs
+is the node-binary copy.** Evidence from the script: esbuild bundle is
+arch-agnostic JS (build-binary.mjs:23-35, `--target=node18` CJS);
+`node --experimental-sea-config` produces the SEA blob (line 43);
+`copyFileSync(process.execPath, out)` (lines 45-46) copies the HOST node
+binary — THE arch-specific part; postject injects `NODE_SEA_BLOB` into the
+copied binary with the sentinel fuse (lines 47-51). postject on Linux adds
+an ELF **note** (postject README: "For ELF executables, the resources are
+added as notes") — pure file surgery, arch-agnostic by construction; it
+never runs the target binary. Arm64 node base: official tarball
+`https://nodejs.org/dist/v24.15.0/node-v24.15.0-linux-arm64.tar.xz` —
+**probed live: HTTP 200, 30.1 MB** (version-matched to the production
+node). Concrete change: `build-binary.mjs` gains an arch parameter
+(`build:binary <tag> [--arch x64|arm64]`): x64 keeps `process.execPath`;
+arm64 downloads + extracts the arm64 tarball (cache under
+`~/.cache/nextcraft/node-arm64/`) and copies `bin/node` from it; output
+`dist/nextcraft-linux-arm64` + `.sha256` sidecar (the script's existing
+checksum block, lines 54-56, retargeted). Both binaries + debs build in one
+release job in minutes (esbuild ~5s, download ~30 MB once, postject ~1s).
+
+**R-26. SEA blob cross-arch feasibility: default config is
+arch-independent — verify with a P3 probe.** build-binary.mjs's sea config
+is `{main, output, disableExperimentalSEAWarning}` (lines 37-42) — it does
+NOT enable `useCodeCache`/`useSnapshot`, the two options that tie a blob to
+an architecture; the default blob is the script + metadata, which is why
+cross-generation is workable. Honesty requirement: this is
+upstream-doc-implicit, not doc-explicit, so P3 ships a probe: generate the
+blob on the x64 runner node 24.15.0, inject into the arm64 base, and
+`--version`-smoke it under binfmt (one-time CT registration:
+`docker run --privileged --rm multiarch/qemu-user-static --reset -p yes`,
+D-069's optional opportunistic path). If the probe fails, the fallback
+keeps the build QEMU-free where it matters: run `--experimental-sea-config`
+under the DOWNLOADED arm64 node binary via binfmt (one emulated invocation
+for blob generation only — esbuild/pip/deb still native x64). The deb
+never executes its payload (R-22) so packaging needs no emulation at all.
+Record the probe result in the P3 ship notes.
+
+---
+
+## R-27..R-29 — Sandbox degrade detection (question 8, D-068)
+
+**R-27. The userns probe exists and is exactly promotable.**
+tests/helpers/userns.py:28-40 — `userns_available()`: `shutil.which("unshare")`
+guard, then `subprocess.run(["unshare", "--user", "--map-root-user", "true"],
+capture_output=True, timeout=10)`, True iff returncode==0. D-068 says
+promote "the proven tests/helpers/userns.py pattern into the sandbox
+module" — concrete home: `ai_service/sandbox/capability.py` exporting
+`userns_available()` (verbatim semantics; importable by main.py boot
+wiring, the API layer, and doctor-adjacent code) while tests keep importing
+the test helper (which can delegate to the promoted one to avoid drift).
+A "real userns capability probe" means exactly this: kernel says yes/no to
+`unshare --user --map-root-user`, NOT a marker file — markers only flavor
+remediation (D-068's own rationale: `/.dockerenv` says docker, not
+userns-blocked; a privileged container passes and must NOT degrade).
+
+**R-28. Integration points, all with in-repo precedents.**
+(1) **Boot notice**: main.py lifespan — the mount-less warning at
+main.py:404 and the admin-token warning at main.py:202 are the G-11
+pattern to copy: after provider wiring, run the probe once; on failure
+`logger.warning("user namespaces unavailable (probe failed) — learner
+sandbox creation will be rejected 503; running inside Docker? see the
+deploy guide's privileged/seccomp variant …")`. (2) **Per-create 503**:
+api/sandboxes.py create_sandbox already maps `PoolFullError → 503`
+(sandboxes.py:157-160); add an `except SandboxUnavailableError` arm in the
+same try with a remediation `detail` (pointer to the documented
+privileged/seccomp variant). SandboxUnavailableError is raised by the
+backend on missing/blocked unshare (unshare_backend.py:90, 256, 344-355)
+and currently would 500 — the degrade must be the honest 503. (3) **doctor
+surfaces it**: doctor.ts checkUnshare (doctor.ts:138-150) currently only
+`which unshare` — upgrade to attempt the real
+`unshare --user --map-root-user true` (mirroring userns.py) and report
+container context. (4) **Container detection flavors only**: the marker
+set is `/.dockerenv` file + `NC_CONTAINER=1` (entrypoint sets it, R-16) +
+optional `/proc/self/cgroup` containerd/docker string — used ONLY to pick
+docker-specific vs generic remediation text. Chat/agents/grading need zero
+changes (they never touch the fabric). This supersedes A-101's cwd-jail
+fallback for deployed schools (D-068 rationale: unisolated learner code
+next to provider keys is unacceptable) — note the A-101 fallback text stays
+in PROJECT.md history as superseded, no code change needed (no cwd-jail
+fallback was ever implemented — probe: backend.py has no such fallback
+class).
+
+**R-29. Degrade semantics are additive to existing honest-refusal
+plumbing.** The manager's create already refuses loudly (PoolFullError
+"no queue (D-032)"); the degrade adds a capability-class refusal with the
+same shape (503 + actionable detail). The web client's use-sandbox-session
+already renders 503 honestly (v0.3 surfaces per ARCHITECTURE.md hooks
+row) — no web work in scope beyond what P4's channel-aware doctor/guide
+does.
+
+---
+
+## R-30..R-31 — CLI onboarding + admin guides (D-066/D-071/D-072 anchors)
+
+**R-30. Channel-aware doctor/guide/refuse: concrete hooks.** doctor gains a
+container-env section: detect `NC_CONTAINER=1`/`/.dockerenv` → print
+volume + privileged/seccomp facts (state at
+`/home/nextcraft/.nextcraft` on the `nc-state` volume; userns verdict from
+R-27's probe) and the docker-channel upgrade path (R-31). deb detection:
+`dpkg -s nextcraft` or binary path `/usr/bin/nextcraft` → print
+deb-channel facts. `bootstrap`/`deploy`/`dev` refuse in-container
+(D-066): each command already starts with repo-root checks
+(deploy.ts:94-131, dev.ts:9-14) — add a container check BEFORE them,
+exit 1 with the pointer text (`docker pull + recreate` per D-071).
+`guide` = offline-first embedded text (D-072): man-page-style sections
+checked into `apps/cli/src/guide/` as TS string constants (mirrored from
+deploy/README.md at build time — a build step or a copy discipline; the SEA
+binary embeds whatever esbuild bundles, so the text lands in the binary for
+free), channel-aware section selection at runtime, forge URLs printed as
+pointers. `doctor`/`verify`/`guide` remain the allowed in-container
+commands (D-066) — `verify` needs a container-mode variant (its venv/
+export checks assume a repo clone, verify.ts:7-14 — in-container it should
+check the mounted web dir + `/health` instead).
+
+**R-31. Channel upgrade semantics (D-071, to be tabulated in the admin
+guide).** docker: `docker pull git.coreci.dev/coreci/nextcraft:<tag>` +
+`docker rm -f` + recreate with the same volume (state persists;
+`deploy`/`bootstrap` never run in-container). deb: `dpkg -i
+nextcraft_<ver>_<arch>.deb` + `nextcraft deploy --service` (idempotent
+clone-update→build→restart→verify, v0.4.6-proven). binary: re-run
+install.sh one-liner (fetches latest release binary, checksum+version
+gates) + `nextcraft deploy --service`. doctor/guide describe the detected
+channel's path. All three keep the `~/.nextcraft` state layout compatible
+(deploy/README.md:85-94 table) — the docker channel relocates it into the
+named volume (R-17).
+
+---
+
+## R-32 — Ecosystem/prior-art scan (question 10, brief)
+
+Comparable "single binary + web + API monorepo" distributions:
+**Ollama** (single static binary + docker image; `curl | sh` installer that
+already does arch-resolve x64/arm64 — steal the installer UX: detect
+`uname -m`, pick the asset, verify, PATH hint — exactly our install.sh
+shape), **Tailscale** (static binary + per-platform packages + apt repo;
+their docs structure "Requirements → Install → Verify → Upgrade →
+Troubleshoot" per channel is the admin-guide skeleton), **Gitea itself**
+(docker image + binary releases + Actions runner: the upstream we're
+consuming — its docs' "Volumes" and cache sections shaped R-5/R-6),
+**act_runner** (docker + binary dual distribution), **Miniflux** (single
+Go binary + minimal docker image + deb in distro repos — closest analog to
+"CLI binary + slim runtime image"). Takeaways for the admin guide
+structure: (1) per-channel chapters each ending in the SAME verification
+checklist (`/health` 200, `/` HTML, `nextcraft doctor` clean — the
+deploy/README.md verification checklist already exists, extend it);
+(2) an upgrade matrix table (channel × step × idempotency note) instead of
+prose; (3) troubleshooting tables with symptom/cause/fix rows
+(apps/cli/README.md + install.sh degradation strings are the house style);
+(4) a "where state lives" table per channel (deploy/README.md:85-94 is
+the precedent — add the docker volume row); (5) deb users expect a
+`/usr/share/doc` README + copyright — cheap Debian-politeness win.
+
+---
+
+## Open risks (tracked into PLAN)
+
+1. **SEA blob cross-arch** (R-26): probe-first in P3; fallback keeps the
+   heavy build native and emulates only blob generation via binfmt.
+   Confidence 0.7.
+2. **corepack on node:24-bookworm** (R-11): Node ≥25 dropped corepack;
+   24.x still ships it. P1 probe; `npm i -g pnpm@12.3.4` fallback.
+3. **Cache-server reachability** from job containers on dockerized runners
+   (R-5/R-12): needs `cache.host` + published ports live-verified on CT 113;
+   volume-mounted pnpm store is the deterministic fallback.
+4. **actions/checkout needs CT internet** (R-8): DEFAULT_ACTIONS_URL=github;
+   fallback = instance-level `self` + mirror, or raw git steps. Probe CT
+   113 egress in P1.
+5. **`docker.io` apt package** on the release lane (R-20): bookworm main
+   ships it (engine+cli); if the pull is too heavy, pre-bake a
+   `git.coreci.dev/coreci/runner-release` image later — out of v0.8 scope.
+6. **Token handling**: registration token founder-provided in chat only,
+   reset after fleet green (R-2/R-6); REGISTRY_TOKEN self-serve PUT first,
+   founder UI fallback (R-13). GITEA_TOKEN job token can't push packages —
+   upstream-confirmed, not a bug.
+7. **Sibling-mode shared-daemon blast radius** (R-21): org-scoped private
+   repos only; accepted-risk row in the guide.
+8. **deb Version policy**: strip the leading `v` (upstream-version must not
+   start with `v`) — a `--nocheck` escape hatch exists but staying policy-
+   clean is free.
+9. **Runner 3.x config drift**: config keys cited here (cache.host,
+   bind_workdir, health_check) are runner 3.x — verify the deployed 3.x
+   minor accepts them at P1 bring-up (generate-config is the authority).
+10. **In-container `verify`** semantics (R-30): repo-clone assumptions need
+    a container-mode branch — P4 must cover it with a test, not prose.

.ciagent/ROADMAP.md

@@ -2,30 +2,82 @@
 
 ## Overview
 
-**Milestone v0.3** — Credential Engines: Replace v0.2's mock engine inputs with real credential engines. Build the sandbox fabric (sandboxed IDE / design tool / simulation), the live in-environment build-telemetry pipeline, the process-trace grading engine, per-learner variant task generation, and the oral/voice defense with AI examiner. Lab/Assessor/Proctor agents move from mock inputs to real engine inputs.
+**Milestone v0.7 — Test Harness Review (COMPLETE, shipped as v0.6.6, 2026-09-27).** NFR refinement-only milestone reviewing the entire test harness: coverage/timeouts/markers wired, trivial tests cut with recorded triage, duplicated infra consolidated, 1,716 warnings/run eliminated to zero, ESLint+RUF100+mypy toolchain completed, recharts 3. Founder scope decisions D-048..D-051; clarify D-052..D-061; grill G-101..G-110. Tags on the v0.6.x line (v0.6.0 phase 0 → v0.6.6 final = milestone release); branch `milestone/v0.7-test-harness-review`.
 
-**Deferred per founder directive:** REQ-F-017 identity verification + age-gating (real KYC backend) is deferred beyond v0.3. Age-gating remains the v0.1 visual flow mockup.
+**Milestone v0.6 — Marketplace Engine (COMPLETE, shipped as v0.5.6, 2026-09-26).** The real marketplace backend behind the existing surfaces: job posting backend + aggregation adapter (REQ-6-001), AI tagging (REQ-6-002), semantic vector search + match scoring (REQ-6-003), company enrichment + resume parsing (REQ-6-004/005), SEO programmatic pages (REQ-6-006). Scope decision D-047 (auto-decided at SPECIFY, full autonomy). Tags on the v0.5.x line (v0.5.0 phase 0 → v0.5.N final = milestone release); branch `milestone/v0.6-marketplace-engine`.
+
+**Hotfix v0.4.7 (2026-09-21) — pre-public hardening.** The 4 P1 flags from the v0.5 final review closed: HMAC ingest tokens on the WS grading input (LAN poisoning closed), nonce+counter defense-id mint (same-ms collision closed), browser-mode client SR/TTS per the descriptor contract (gap closed), 8 browser-voice module pins. Deployed via `nextcraft deploy --service`; site 200, service enabled.
+
+**Hotfix v0.4.6 (2026-09-21) — site-down + deploy experience.** The domain root (nextcraft.coreci.dev) served the API's JSON 404 for three releases: the deployed service ran mount-less (web export never built on the host; dev -d auto-wiring silently skipped; nothing detected it). Fixed the class: `nextcraft deploy` (one-command clone/update → install → venv → export build → restart → verify), `deploy --service` (generated systemd unit, reboot-persistent), toolchain discovery (nvm/PNPM_HOME/corepack, incl. split installs — the host's exact layout), loud mount-less boot warning, verify live mount probe. Deployed live on the host via the new command; site 200, service enabled.
+
+**Hotfix v0.3.5/v0.3.6 (2026-09-13) — fresh-box + single-port unattended deploy.**
+
+**Milestone v0.5 — COMPLETE (shipped as v0.4.5, 2026-09-13).** Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease: the four seams D-016 deferred out of v0.4. Server STT/TTS for voice defense (`openai-audio` VoiceProvider), identity verification + backend-enforced age-gating (REQ-F-017), design/simulation sandbox environments (REQ-F-021 remainder), and the exec-telemetry seq-lease/replay-margin fix.
+
+**Milestone v0.4 — COMPLETE (shipped as v0.3.4, 2026-09-13; hotfixes v0.3.5 fresh-box, v0.3.6 single-port unattended deploy).** Distribution & Bootstrap CLI: `nextcraft` CLI (doctor/bootstrap/verify/dev) shipped as a linux x64 SEA binary, one-liner install script with checksum + version integrity gates, and binaries published on **every ongoing release** (v0.3.2 onward). v0.3.6 adds the single-port same-origin deploy (static export served by the ai-service on :8420) and unattended ops (`dev -d`/`stop`/`log`), with runtime state moved to `~/.nextcraft/`.
+
+**Milestone v0.3** — Credential Engines: complete, shipped as v0.2.8 (2026-09-12). Real sandbox fabric, live build telemetry, process-trace grading, per-learner variants, oral defense, real learner surfaces.
+
+**Deferred per founder directive (D-016):** REQ-F-017 identity verification + age-gating (real KYC backend), real server STT/TTS, design/simulation sandbox environments, and the exec-telemetry seq-lease are deferred to v0.5. Age-gating remains the v0.1 visual flow mockup.
 
 **Prior milestone:** v0.2 (ai-tutor-architecture) — complete, shipped as v0.2.0, six tutor agents live over mock engine inputs (D-015).
 
-**Milestone type:** Feature (new credential-engine services + real agent inputs)
-**Tag line:** v0.2.x (patches on the v0.2 line; milestone release as the final v0.2.x patch)
-**Branch:** milestone/v0.3-credential-engines
+**Milestone type:** Feature (voice provider + identity backend + new env types + ingest protocol fix)
+**Tag line:** v0.4.x (patches on the v0.4 line; milestone release as the final v0.4.x patch)
+**Branch:** milestone/v0.5-real-voice-identity-envs
 
 ---
 
 ## Phase List
 
+### v0.8 (in progress)
+
 | # | Name | Status | Depends On | Requirements | Success Criteria |
 |---|------|--------|------------|--------------|------------------|
-| 0 | Pre-execution | in-progress | — | — | Specification, clarify, research, plan complete; .ciagent/ files updated for v0.3 |
-| 1 | Sandbox fabric | complete | 0 | REQ-3-001, REQ-3-002 | Isolated per-learner sandbox environments provisioned (IDE / design / simulation); lifecycle API (create/destroy/snapshot); resource limits enforced; no cross-tenant access |
-| 2 | Live build telemetry | pending | 1 | REQ-3-003 | In-environment capture of process events (commands, file diffs, run/test results, keystroke-level activity) streamed to ai-service; reliable transport; per-learner trace persistence |
-| 3 | Process-trace grading engine | pending | 2 | REQ-3-004 | Grades artifacts from their full process traces (not just final output); emits structured rubric-aligned scores; feeds Assessor real inputs |
-| 4 | Variant task generation | pending | 1 | REQ-3-005 | Per-learner task variants generated so no two learners receive identical prompts; variant seed recorded for grading fairness |
-| 5 | Oral / voice defense | pending | 3 | REQ-3-006 | AI examiner conducts spoken defense of submitted work; STT → dialogue → TTS; transcript + integrity signals captured; feeds Proctor/Mentor |
-| 6 | Agent re-grounding + learner surface integration | pending | 2,3,4,5 | REQ-3-007, REQ-3-008 | Lab/Assessor/Proctor consume real engine inputs; v0.1 sandbox + assessment mockups wired to real engines (in-browser build/run, live telemetry, live defense) |
-| 7 | Final review + ship | pending | 6 | — | Code review clean; audit passes; milestone tagged (v0.2.x final patch); release created on Gitea |
+| 0 | Pre-execution | complete (v0.7.0) | — | — | Specification, clarify (D-063..D-072), research (R-1..R-32), plan (rails→artifacts→onboarding→guides), grill (G-201..G-210), MVP/UX check complete (shipped as v0.7.0, release 913) |
+| 1 | Release-consistency rails | complete (v0.7.1) | 0 | REQ-8-001 | 3 org-level runners green on CT 113 (hybrid labels, sibling mode); ci.yaml push lanes green; hello-world × 3 labels; release.yaml builds assets on tag (v0.7.1 release machine-made); pre-commit both-direction proof; secrets audit clean |
+| 2 | Docker image channel | pending | 1 | REQ-8-002 | Multi-stage image (unprivileged, /health, state volume) pushed to the Gitea registry on every phase release; honest sandbox degrade (probe + notice + 503 remediation); in-container CLI semantics; smoke gate in workflow |
+| 3 | Debian-native channel | pending | 2 | REQ-8-003 | arm64 QEMU-free cross-build; .deb x64+arm64 (advisory postinst); install.sh arch-resolve; full asset matrix (2 binaries + 2 checksums + 2 debs) on every release |
+| 4 | CLI onboarding | pending | 3 | REQ-8-004 | Channel-aware doctor; nextcraft guide offline; honest in-container refusals; docker/deb E2Es env-gated green; guide↔runbook parity test |
+| 5 | Admin guides | pending | 4 | REQ-8-005 | deploy/README.md full runbook (3 channels × install/upgrade, upgrade matrix, troubleshooting, evidence appendix); README quickstart; every recipe evidence-backed |
+| 6 | Final review + ship | pending | 1-5 | — | Review clean; audit pass; milestone tagged v0.7.6 (final v0.7.x patch = milestone release); release with full asset matrix + image tags; milestone merged to main |
+
+### v0.7 (complete)
+
+| # | Name | Status | Depends On | Requirements | Success Criteria |
+|---|------|--------|------------|--------------|------------------|
+| 0 | Pre-execution | complete | — | — | Specify, clarify (D-052..D-061), research (44-50), plan (D-062 waves), grill (G-101..G-110), MVP/UX check complete (shipped as v0.6.0) |
+| 1 | Harness wiring | complete (v0.6.1) | 0 | REQ-7-001 | Coverage in all 3 workspaces; timeouts 60s/180s probe-proven; markers fast/real_server/userns strict; web tests in turbo; leaks fixed; fast subset <60s |
+| 2 | Suite composition | complete (v0.6.2) | 1 | REQ-7-002 | 10 trivial tests cut with recorded per-assertion triage; 8 cross-boundary pins kept (CWD-independent); tests/helpers/ consolidation zero-behavior-change; droppings swept |
+| 3 | Warning elimination | complete (v0.6.3) | 2 | REQ-7-003 | session.exec ×14; ResourceWarning sites closed at source; filterwarnings=error + 2 scoped ignores; full suite ZERO warnings |
+| 4 | Lint & suppression hygiene | complete (v0.6.4) | 3 | REQ-7-004 | ESLint 6/6 workspaces; 20 violations fixed; 80 noqa removed (6 live fixed at source); dead exports gone; version single-source; engines |
+| 5 | Type & dependency hardening | complete (v0.6.5) | 4 | REQ-7-005 | mypy relaxed-first green (178 files, 27 ignores dispositioned); recharts 3.10.1 proven; transitive audit recorded |
+| 6 | Final review + ship | complete (v0.6.6) | 1-5 | — | Purity gate zero feat:; review SHIP verdict; audit PASS; milestone tagged v0.6.6; release with binary assets; milestone merged to main |
+
+### v0.6 (complete)
+
+| # | Name | Status | Depends On | Requirements | Success Criteria |
+|---|------|--------|------------|--------------|------------------|
+| 0 | Pre-execution | complete | — | — | Specification, clarify, research, plan, grill, MVP/UX check complete; .ciagent/ files updated for v0.6 (shipped as v0.5.0) |
+| 1 | Postings backend + aggregation adapter | complete (v0.5.1) | 0 | REQ-6-001 | Postings store + lifecycle + `/v1/marketplace/*` routes live; job board/detail/employer surfaces read real data; 18+ gates composed per D-043; seeded ingestion adapter proven |
+| 2 | AI tagging | complete (v0.5.2) | 1 | REQ-6-002 | Posting text → skills/seniority/category tags via LLM structured output (mock-first); tag facets drive search filters; tags persisted |
+| 3 | Semantic vector search | complete (v0.5.3) | 2 | REQ-6-003 | Embedding provider protocol (mock-first) + SQLite-local vectors; competency↔posting similarity ranking; match scores surface on job cards + candidate matches |
+| 4 | Enrichment + resume parsing | complete (v0.5.4) | 3 | REQ-6-004, REQ-6-005 | Employer enrichment from posting data with provenance; resume upload → profile auto-fill with learner review gate; bounded uploads |
+| 5 | SEO programmatic pages | complete (v0.5.5) | 4 | REQ-6-006 | Metadata + JSON-LD + sitemap/robots on job/stack/landing pages; static-export compatible (single-port deploy unchanged) |
+| 6 | Final review + ship | complete (v0.5.6) | 1-5 | — | Review clean; audit passes; milestone tagged (final v0.5.x patch); release with binary assets on Gitea; milestone merged to main |
+
+---
+
+## Phase List (v0.5 — complete)
+
+| # | Name | Status | Depends On | Requirements | Success Criteria |
+|---|------|--------|------------|--------------|------------------|
+| 0 | Pre-execution | complete | — | — | Specification, clarify, research, plan, grill complete; .ciagent/ files updated for v0.5 |
+| 1 | Seq-lease + replay margin | complete | 0 | REQ-5-007 | Ingest acks received seqs (`seq_ack` frame); capture agent trims spool to ack on reconnect (bounded margin); real-server mid-burst regression test closes the P07-documented gap |
+| 2 | Real server voice | complete | 0 | REQ-5-001, REQ-5-002 | `openai-audio` provider passes STT/TTS contract tests (MockTransport); voice defense runs server-side end-to-end when keys exist; mock/browser paths unchanged; suite green |
+| 3 | Identity + age-gating | complete | 0 | REQ-5-003, REQ-5-004 | Identity protocol + mock backend + verification flow API; gated routes enforce 16+/18+ (allowlist → identity → rate caps); PII hygiene pinned by caplog test |
+| 4 | Design/sim environments | complete | 0 | REQ-5-005, REQ-5-006 | Template-layer env registry (build/design/simulation); per-kind starter contents + exec policy; test_command surfaced; grading digest kind-agnostic (pinned) |
+| 5 | Final review + ship | complete | 1-4 | — | Code review clean; audit passes; milestone tagged (final v0.4.x patch); release with binary assets on Gitea |
 
 ---
 
@@ -33,147 +85,97 @@
 
 ### Phase 0: Pre-execution
 
-**Goal:** Establish v0.3 specification, clarify ambiguities, research credential-engine architecture (sandbox isolation, telemetry transport, trace grading, variant generation, voice IO), create detailed plans.
+**Goal:** Lock the v0.5 specification (four deferred seams), clarify ambiguities, research the audio endpoint contract + KYC provider landscape + env-type design + the seq-lease protocol, plan waves, grill adversarially.
 
 **Stages:** SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL → MVP/UX CHECK → SHIP
 
 **Deliverables:**
 - Updated .ciagent/config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, ARCHITECTURE.md, PERSONAS.md, PLAN.md
 
-**Success criteria:** All .ciagent/ files updated for v0.3; phase 0 shipped as first v0.2.x patch.
+**Success criteria:** All .ciagent/ files updated for v0.5; phase 0 shipped as v0.4.0.
 
----
+### Phase 1: Seq-Lease + Replay Margin (REQ-5-007)
 
-### Phase 1: Sandbox Fabric
-
-**Goal:** Provision and manage isolated per-learner execution environments.
-
-**Requirements:** REQ-3-001, REQ-3-002
+**Goal:** Close the reconnect-replay ACK gap from the v0.3 P6 lesson.
 
 **Key deliverables:**
-- Sandbox orchestrator service: create/list/destroy/snapshot sandbox instances (IDE, design tool, simulation)
-- Isolation boundary: per-learner containerization or VM-grade isolation; no cross-tenant filesystem/network access
-- Resource limits: CPU/memory/disk/time quotas per sandbox
-- Sandbox lifecycle API consumed by ai-service and the web learner surface
+- Ingest WS: ack frames carrying highest-contiguous received seq per (learner, task); capture agent tracks ack and resumes spool replay from acked position (bounded replay margin)
+- Real-server regression test: mid-burst kill → reconnect → no loss/dup exactly-once within margin (deterministic — waits for server-side observation like the P07 fix)
 
-**Success criteria:**
-- A sandbox can be created, written to, snapshotted, and destroyed via API
-- Isolation verified: a sandbox cannot read another learner's data
-- Resource limits enforced and observable — enforcement mechanism: rlimits (memory/CPU) + wall-clock reaper + workdir-size sweep; per-sandbox pids and hard-disk-quota are accepted v0.3 gaps (no cgroup delegation/sudo on this box, G-1)
+**Success criteria:** regression test green on repeated runs; margin documented; flood/gap semantics (G-3/G-4) unchanged.
 
----
+### Phase 2: Real Server Voice (REQ-5-001, REQ-5-002)
 
-### Phase 2: Live Build Telemetry
-
-**Goal:** Capture in-environment process events and stream them to ai-service reliably.
-
-**Requirements:** REQ-3-003
+**Goal:** The `openai-audio` VoiceProvider against OpenAI-compatible STT/TTS endpoints; voice defense real path end-to-end.
 
 **Key deliverables:**
-- Telemetry capture agent (in-sandbox): commands, file diffs, run/test results, keystroke-level/activity events
-- Telemetry transport: durable, ordered, resumable stream to ai-service ingestion endpoint
-- Trace persistence: per-learner, per-task process traces stored for grading and proctoring
-- Transport hardening: retries, backpressure, exactly-once-or-at-least-once semantics documented
+- `ai_service/voice/openai_audio.py` — provider per D-030 protocol (STT: multipart upload → transcript; TTS: text → audio bytes); httpx via the app pool; timeouts; error mapping
+- `AI_VOICE_BASE_URL`/`AI_VOICE_API_KEY`/`AI_VOICE_MODEL` settings resolution (env-only, never committed); `AI_VOICE_PROVIDER=openai-audio|browser|mock` selection in factory
+- Defense answer route: real STT path (audio upload transcribed server-side when provider=openai-audio; browser/mock paths unchanged); examiner TTS question audio
+- Tests: MockTransport byte-contract tests (multipart shape, response parse, error modes); defense-flow tests stay mock-only (never call the cloud)
 
-**Success criteria:**
-- Sandbox activity produces a complete ordered process trace in ai-service
-- Stream survives transient network failure without trace loss
-- Trace retrievable by learner+task ID for grading
+**Success criteria:** provider contract pinned by tests; voice defense works against a scripted audio endpoint; `pnpm ai:test` green; manual cloud probe documented.
 
----
+### Phase 3: Identity + Age-Gating (REQ-5-003, REQ-5-004)
 
-### Phase 3: Process-Trace Grading Engine
-
-**Goal:** Grade learner artifacts from their full process traces.
-
-**Requirements:** REQ-3-004
+**Goal:** Real identity verification backend behind a provider protocol; backend-enforced age gates.
 
 **Key deliverables:**
-- Trace analyzer: reconstructs build/decision timeline from a process trace
-- Grading engine: rubric-aligned scoring over the trace (process quality, not just final artifact)
-- Structured score output consumable by the Assessor agent
-- Calibration against v0.2 mock corpora to validate grading dimensions
+- `ai_service/identity/` — IdentityProvider protocol (submit/poll/verify), mock provider (deterministic), store (SQLite, D-027 family), API router (`/v1/identity/*`)
+- Age-gate enforcement: school 16+ (enrollment), marketplace 18+ verified (gated routes reject under-age/unverified with 403) — dependency-injected gate, allowlist (G-5) retained as pilot guard
+- PII hygiene: document refs stored, never raw docs in logs; secrets-hygiene checklist extended
 
-**Success criteria:**
-- Engine emits structured rubric-aligned scores from a real process trace
-- Scores distinguish process quality (e.g., iterative debugging vs. paste-and-run)
-- Output feeds Assessor; replaces pre-baked artifact corpus inputs
+**Success criteria:** verification flow API green under mock; gated routes enforce ages in tests; zero PII in captured logs (pinned by test).
 
----
+### Phase 4: Design/Sim Environments (REQ-5-005, REQ-5-006)
 
-### Phase 4: Variant Task Generation
-
-**Goal:** Generate per-learner task variants so no two learners receive identical prompts.
-
-**Requirements:** REQ-3-005
+**Goal:** Environment kinds beyond the coding IDE on the existing namespace fabric.
 
 **Key deliverables:**
-- Variant generator: parameterized task templates → unique per-learner instances
-- Variant seed registry: record variant parameters for grading fairness and proctoring
-- Difficulty normalization: variants calibrated to equivalent difficulty
+- Environment-type registry in the sandbox fabric: `build` (existing), `design` (canvas/file artifacts), `simulation` (run/benchmark harness) — per-type starter contents + allowed exec commands, one lifecycle, one telemetry path
+- Learner surface + engine-client accept environment kind; telemetry events carry kind; grading digest stays kind-agnostic (D-028 unchanged)
 
-**Success criteria:**
-- Two learners requesting the same competency receive distinct task variants
-- Variant parameters persisted and auditable
-- Grading engine scores variants equitably
+**Success criteria:** all three kinds provisionable + provable isolation; per-kind starter files land; kind flows through telemetry to the digest.
+
+### Phase 5: Final Review + Ship
+
+**Goal:** Code review, audit, milestone release with binary assets.
+
+**Success criteria:** review P0s fixed in-phase; audit reconstruction clean; final v0.4.x patch tagged; Gitea release with `nextcraft-linux-x64` + `.sha256`; milestone merged to main; branches deleted.
 
 ---
 
-### Phase 5: Oral / Voice Defense
+## Hotfixes (v0.4.x line, post-v0.5)
 
-**Goal:** AI examiner conducts a spoken defense of the learner's submitted work.
+| Tag | Date | Summary |
+|-----|------|---------|
+| v0.4.7 | 2026-09-21 | Pre-public hardening (the 4 P1 flags from the v0.5 final review): HMAC ingest tokens on the WS grading input (LAN trace-poisoning closed, per-boot secret, manager mints / endpoint verifies), nonce+counter defense-id mint (same-ms PK collision closed), browser-mode client SR/TTS implemented per the descriptor contract (the v0.5 gap), 8 browser-voice module pins. 488 backend (+10), web 22/22 (+8), CLI 61/61. Deployed via `nextcraft deploy --service`; site 200, service enabled. |
+| v0.4.6 | 2026-09-21 | Site-down hotfix + one-command deploy: `nextcraft deploy [--service]` (clone/update → install → venv → export build → restart → verify), systemd unit generation (reboot persistence), toolchain discovery (nvm/PNPM_HOME/corepack + split installs), loud mount-less boot, verify live mount probe, subcommand flag dispatch. Deployed live via the command itself; nextcraft.coreci.dev → 200 HTML. |
 
-**Requirements:** REQ-3-006
+## v0.7 (Complete — Shipped as v0.6.6)
 
-**Key deliverables:**
-- Voice pipeline: STT → defense dialogue (LLM examiner) → TTS
-- Examiner agent: probes understanding, challenges process choices from the trace
-- Transcript + integrity signals captured for Proctor/Mentor
-- Latency budget: defense feels conversational (bounded turn latency)
+Test Harness Review (NFR refinement-only, founder directive post-v0.6): coverage measured in all three workspaces (pytest-cov 95% branch, c8 web 95.9%/cli 76.9%); pytest-timeout safety net (60s/180s dual-tier, signal method, both probe-proven); markers fast/real_server/userns under --strict-markers with a 620-test fast subset completing in ~56s; web tests inside the turbo pipeline; CLI E2E env-gated. Suite composition: 10 trivial tests cut with per-assertion recorded triage (D-057), 8 cross-boundary/regression pins kept in CWD-independent pins.test.ts; duplicated harness infra consolidated into tests/helpers/ (KillableProxy split into two semantics-distinct helpers per G-101); deterministic waits replace sleeps where hooks exist; sandbox droppings swept + session-end fixtures. Warning elimination: 1,716 warnings/run → ZERO (14 session.query→session.exec sites, 14 ResourceWarning sites closed at source, filterwarnings=error with exactly 2 scoped upstream ignores). Lint hygiene: ESLint live in all 6 workspaces (was none), 20 violations fixed, 80 inert noqa removed (6 live ones fixed at source), RUF100 enforced, dead exports gone, version single-sourced 0.6.5, engines everywhere. Type & dependency hardening: mypy 2.3.1 relaxed-first green over 178 files (215 errors found: ~140 fixed at source incl. 8+ genuine bugs, 34 scoped suppressions; all 27 original ignores dispositioned); recharts 2.15.4→3.10.1 (deprecated direct dep resolved); transitive audit recorded (4 dev-only remain, none actionable). 7 phases (P0-P6). All 5 requirements (REQ-7-001..005) complete. Tags v0.6.0-v0.6.5 per phase, milestone release v0.6.6.
 
-**Success criteria:**
-- A spoken defense runs end-to-end (speak → examiner question → learner response → verdict)
-- Transcript + integrity signals persisted and consumable by Proctor
-- Turn latency within the documented budget
+## v0.6 (Complete — Shipped as v0.5.6)
 
----
+Real backend behind the marketplace surfaces: postings store + aggregation adapter + marketplace API (REQ-6-001), AI tagging (REQ-6-002), embedding-backed semantic search + match scores (REQ-6-003), company enrichment + resume parsing (REQ-6-004/005), SEO programmatic pages (REQ-6-006). 7 phases (P0–P6), all 6 requirements complete. Tags v0.5.0–v0.5.5 per phase, milestone release v0.5.6. Final review CLEAN (all G-101..G-110 honored, MH-M1..M6 met); audit PASS.
 
-### Phase 6: Agent Re-grounding + Learner Surface Integration
+## v0.5 (Complete — Shipped as v0.4.5)
 
-**Goal:** Move Lab/Assessor/Proctor to real engine inputs; wire learner surface to the real engines.
+Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease: real server STT/TTS (`openai-audio` VoiceProvider with boot-safe fallback), the identity module (5th D-027 store, provider protocol + mock, D-043 age-gate composition on variants/sandboxes/defense/marketplace), design/simulation environment kinds at the template layer with per-kind exec policy, and the seq-ack protocol closing the P07 replay-margin gap. 6 phases (P0–P5). All 7 requirements (REQ-5-001..007) complete. Tags v0.4.0–v0.4.4 per phase, milestone release v0.4.5.
 
-**Requirements:** REQ-3-007, REQ-3-008
+## v0.4 (Complete — Shipped as v0.3.4)
 
-**Key deliverables:**
-- Lab agent consumes live sandbox telemetry (replaces v0.2 mock telemetry)
-- Assessor agent consumes grading-engine output (replaces pre-baked artifacts)
-- Proctor consumes telemetry + defense integrity signals (replaces mock telemetry)
-- Learner sandbox mockup → real in-browser build/run; assessment mockup → live defense + live grading
+Distribution & Bootstrap CLI: `nextcraft` CLI (doctor/bootstrap/verify/dev) as a self-contained linux x64 SEA binary, one-liner install with sha256 + version integrity gates, release-asset pipeline attaching binaries to every ongoing release (v0.3.2 onward), install/quickstart docs backed by a fresh-clone E2E test. 5 phases (P0–P4). All 5 requirements (REQ-4-001..005) complete. Tags v0.3.0–v0.3.3 per phase, milestone release v0.3.4.
 
-**Success criteria:**
-- Lab/Assessor/Proctor operate on real inputs with no mock fallback in the learner path
-- Learner can build in-browser and see live telemetry + live feedback
-- Assessment surface runs a live defense and shows live grading
-- `pnpm build` and `pnpm typecheck` pass
+## v0.3 (Complete — Shipped as v0.2.8)
 
----
-
-### Phase 7: Final Review + Ship
-
-**Goal:** Code review, audit, milestone release.
-
-**Key deliverables:**
-- Multi-persona code review (correctness, testing, security, performance, maintainability)
-- Project health audit (reconstruction test, .ciagent/ file discipline, branch hygiene, commit discipline)
-- Milestone ship: merge milestone → main, tag final v0.2.x patch, create Gitea release
-
-**Success criteria:**
-- Code review: P0 fixes applied, P1+ documented
-- Audit: all checks pass, project state reconstructable from git log
-- Ship: milestone tagged, branch merged to main, Gitea release created — release note states identity/age-gating (KYC) is deferred and age-gating remains a visual mockup
-- All v0.3 requirements marked complete
-
----
+Credential Engines: real sandbox fabric (Linux namespaces), live build telemetry
+(at-least-once/exactly-once), process-trace grading (G-4 gated), seeded per-learner
+variants (fairness anchors wired to grading), oral defense with integrity signals
+(mock-first voice, browser fallback), and real learner build/defense/grading surfaces.
+8 phases. All 8 requirements (REQ-3-001..008) complete. Tags v0.2.1–v0.2.7 per phase,
+milestone release v0.2.8.
 
 ## v0.2 (Complete — Shipped as v0.2.0)
 
@@ -181,4 +183,4 @@ AI Tutor Architecture: Six AI tutor agents (Coach, Tutor, Lab, Assessor, Proctor
 
 ## v0.1 (Complete — Shipped as v0.1.0)
 
-UI/UX Prototype: High-fidelity interactive prototype of all four Nextcraft surfaces. 7 phases (P0 + P1-P6 execution + P7 final). All 28 requirements complete. Tags v0.0.1–v0.0.7, milestone release v0.1.0.
+UI/UX Prototype: High-fidelity interactive prototype of all four Nextcraft surfaces. 7 phases (P0 + P1-P6 execution + P7 final). All 28 requirements complete. Tags v0.0.1–v0.0.7, milestone release v0.1.0.

.ciagent/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.0",
+  "version": "0.8.0",
   "autonomy": {
     "level": "full",
     "decision_confidence_threshold": 0.6,
@@ -46,9 +46,9 @@
   "projects": [],
   "active_project": null,
   "milestone": {
-    "version": "v0.3",
-    "name": "credential-engines",
+    "version": "v0.8",
+    "name": "ship-anywhere",
     "type": "feature",
-    "branch": "milestone/v0.3-credential-engines"
+    "branch": "milestone/v0.8-ship-anywhere"
   }
-}
+}

.dockerignore

@@ -0,0 +1,29 @@
+# Build context hygiene (v0.8 P2): secrets and runtime droppings never
+# enter an image layer. The .env* exclusion is the hard rule — the v1.8
+# class of leak (tokens) must be structurally impossible here.
+.git
+.gitignore
+.dockerignore
+.env
+.env.*
+**/.env
+**/.env.*
+!.env.example
+.ciagent
+**/.ciagent
+**/.venv
+**/node_modules
+**/__pycache__
+**/*.pyc
+**/.pytest_cache
+**/.mypy_cache
+**/.ruff_cache
+**/.turbo
+**/coverage
+**/dist
+apps/web/out
+apps/web/.next
+**/*.tsbuildinfo
+.turbo
+node_modules
+*.log

.gitea/workflows/ci.yaml

@@ -0,0 +1,130 @@
+# Push lanes — every branch, every push (REQ-8-001, D-063).
+#
+# Two jobs, two runner labels, NEVER wholesale `turbo lint`/`turbo typecheck`
+# in the node lane (RESEARCH R-8): those turbo tasks pull in
+# @nextcraft/ai-service#lint/typecheck, which hard-fail without the Python
+# venv (apps/ai-service/scripts/lint.sh:8, typecheck.sh:13) — a venv that
+# does not exist in the node:24-bookworm job container. The node lane runs
+# lint/typecheck via `pnpm --filter` over the 5 TS workspaces only; the
+# python lane invokes the three ai-service bash scripts directly (no pnpm
+# needed in that container at all).
+#
+# Concurrency: serialize per-ref so a rapid-fire branch push reuses one lane
+# instead of stacking jobs on the capacity-1 runners (R-4).
+name: CI
+
+on: push
+
+concurrency:
+  group: ci-${{ gitea.ref }}
+  cancel-in-progress: true
+
+jobs:
+  node:
+    # Fleet label `node` -> container docker.io/library/node:24-bookworm
+    # (deploy/ci/docker-compose.yaml, R-3 label map).
+    runs-on: node
+    steps:
+      # actions/checkout@v4 downloads from github.com (DEFAULT_ACTIONS_URL
+      # default). github.com egress is verified reachable from the LAN;
+      # the CT-local probe is still pending (Wave 1-1 blocked on founder
+      # deploy-key install). If checkout fails at the first real run, the
+      # fallback is raw git fetch steps using the automatic job token:
+      #   - run: |
+      #       git init -q .
+      #       git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git"
+      #       git fetch --depth=1 origin "$GITHUB_SHA"
+      #       git checkout FETCH_HEAD
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Optional pnpm store cache (R-12). Depends on the runner cache server
+      # being reachable from job containers (R-5: cache.host = CT IP + a
+      # published port — configured in deploy/ci/). If the cache server
+      # ETIMEDOUTs on first real runs, drop this block (fallback: a
+      # volume-mounted pnpm store per R-12, or no cache at all — install is
+      # affordable on the LAN). continue-on-error keeps cache flakiness
+      # from ever turning the lane red; repeated timeouts = delete.
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/pnpm/store
+          key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: pnpm-${{ runner.os }}-
+        continue-on-error: true
+
+      # pnpm 12.3.4 is pinned by root package.json `packageManager`.
+      # node:24-bookworm still bundles corepack (24.x retains it, deprecated
+      # — Node >= 25 dropped it; R-11). Fallback if corepack is absent:
+      #   npm i -g pnpm@12.3.4
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Lint: per-workspace filters over the 5 TS workspaces ONLY — never
+      # `turbo lint` (see header note).
+      - name: Lint (TS workspaces)
+        run: >-
+          pnpm --filter web --filter @nextcraft/cli --filter @nextcraft/ui
+          --filter @nextcraft/types --filter @nextcraft/mock-data lint
+
+      # Typecheck: same filter set, per-workspace tsc --noEmit.
+      - name: Typecheck (TS workspaces)
+        run: >-
+          pnpm --filter web --filter @nextcraft/cli --filter @nextcraft/ui
+          --filter @nextcraft/types --filter @nextcraft/mock-data typecheck
+
+      - name: Web tests (node:test via tsx)
+        run: pnpm web:test
+
+      # CLI default test script (tsx --test tests/*.test.ts) excludes the
+      # env-gated E2E (apps/cli/package.json `test:e2e`, CLI_E2E=1) — the
+      # fresh-clone E2E stays out of job containers per D-063.
+      - name: CLI tests (node:test via tsx, E2E env-gated out)
+        run: pnpm cli:test
+
+  python:
+    # Fleet label `python` -> container docker.io/library/python:3.11-bookworm
+    # (R-3). The three scripts below are self-contained venv-relative bash
+    # (R-9) — no pnpm, no node, no turbo in this lane.
+    #
+    # P1 CI finding: actions/checkout@v4 is a NODE-based action — it cannot
+    # exec in the python:3.11-bookworm container (exit 127: "node" not in
+    # $PATH). This lane checks out via raw git steps with the automatic job
+    # token instead (the R-8 fallback path, promoted to primary here).
+    runs-on: python
+    steps:
+      - name: Checkout (raw git — node actions cannot run in this container)
+        run: |
+          git init -q .
+          git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git"
+          git fetch --depth=1 origin "$GITHUB_SHA"
+          git checkout FETCH_HEAD
+
+      # NOTE: no actions/cache here — it is a node-based action and this
+      # container has no node (exit 127; same class as the checkout finding).
+      # The venv rebuild is ~25s warm — acceptable without cache; pip's own
+      # HTTP cache is cold but the LAN is fast. Revisit only if the lane
+      # slows materially (volume-mounted store per R-12, or a pip download
+      # cache directory via container options).
+
+      # bootstrap.sh is idempotent: creates .venv (with the --without-pip +
+      # get-pip fallback for Debian-without-ensurepip) and pip-installs
+      # the project with [dev] extras (ruff, mypy, pytest).
+      - name: Bootstrap ai-service venv
+        run: bash apps/ai-service/scripts/bootstrap.sh
+
+      - name: Lint (ruff)
+        run: bash apps/ai-service/scripts/lint.sh
+
+      - name: Typecheck (mypy, D-058 baseline)
+        run: bash apps/ai-service/scripts/typecheck.sh
+
+      # Fast pytest lane per D-063: -m "not real_server and not userns"
+      # (scripts/test.sh FAST=1). real_server/userns tiers stay local-only
+      # — job containers genuinely cannot run them (docker default seccomp
+      # denies the nested `unshare --user` the backend needs; R-8).
+      - name: Tests (fast lane)
+        run: FAST=1 bash apps/ai-service/scripts/test.sh

.gitea/workflows/hello.yaml

@@ -0,0 +1,28 @@
+# Fleet proof (REQ-8-001, MH-1c): workflow_dispatch one-step echo job per
+# fleet label. Dispatching this workflow proves all three runners
+# register, pull their job image, and execute a job. Observed green in the
+# Actions tab = the runner fleet is verified end-to-end.
+#
+# Labels (R-3 fleet map, deploy/ci/docker-compose.yaml):
+#   node        -> node:24-bookworm               (nc-runner-node)
+#   ubuntu-latest -> runner-images:ubuntu-latest (nc-runner-node, hybrid)
+#   python      -> python:3.11-bookworm           (nc-runner-python)
+name: Hello fleet
+
+on: workflow_dispatch
+
+jobs:
+  node:
+    runs-on: node
+    steps:
+      - run: echo "hello from node"
+
+  python:
+    runs-on: python
+    steps:
+      - run: echo "hello from python"
+
+  ubuntu-latest:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "hello from ubuntu-latest"

.gitea/workflows/release.yaml

@@ -0,0 +1,220 @@
+# Release lane — tag push only (REQ-8-001, D-063, R-14/R-15).
+#
+# Fires on `v*` tag pushes. Builds the x64 SEA binary stamped with the tag,
+# generates the sha256 sidecar, and attaches both to the tag's Gitea
+# release via the REST API (the same mechanics as scripts/release-assets.sh
+# — that script stays untouched as the MANUAL fallback with its
+# .env-only token resolution, per D-064/R-14).
+#
+# Within-phase proof (G-203): at verify time push a temporary
+# `v0.7.1-rc1`-style tag to the phase-branch head, observe this workflow
+# build + attach green (release immediately deleted or pre-release), then
+# delete the tag. The phase ship tag remains the real artifact.
+#
+# Token precedence (R-13): the automatic job token (auto-provided as the
+# GITHUB_TOKEN env / `${{ github.token }}` / `${{ gitea.token }}`) HAS
+# releases scope and can create releases + attach assets, but it CANNOT
+# publish packages (upstream-confirmed). The repo secret GITEA_TOKEN (a
+# founder-set PAT), when present, WINS (lowest level wins). This workflow
+# uses `${{ secrets.GITEA_TOKEN }}` when set, else the automatic token.
+#
+# Extension points (P2/P3, G-202: this workflow is the shared rail):
+#   [P2] after "Build binary": docker build + login + push to
+#        git.coreci.dev/coreci/nextcraft:$TAG + :latest with
+#        secrets.REGISTRY_TOKEN, plus the five-assertion smoke gate (G-204).
+#   [P3] arm64 cross-build (G-201 ladder) + both .deb packages (R-22/R-23)
+#        join the attach step below — full asset matrix per D-064.
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    # Fleet label `release` -> container node:24-bookworm (R-3: node +
+    # dpkg-deb + git + curl; the deb toolchain ships with bookworm).
+    runs-on: release
+    env:
+      # Token precedence per R-13: repo secret GITEA_TOKEN (PAT) wins when
+      # present; else the automatic job token (releases scope is enough for
+      # release-id resolution + asset upload — R-14). Never echo this.
+      RELEASE_TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v4
+
+      # P2: the release lane builds/pushes the docker image. The job
+      # container (node:24-bookworm) has no docker CLI and no daemon — the
+      # host daemon is bind-mounted into this job via the runner's
+      # container.options (deploy/ci/config-runner-release.yaml, sibling
+      # mode); only the CLI is missing. Bookworm main ships docker.io
+      # (engine+cli — the engine stays dormant; the socket is the host's).
+      - name: Install docker CLI (host daemon is socket-mounted)
+        run: |
+          apt-get update -qq && apt-get install -y -qq docker.io >/dev/null
+          docker version --format 'client {{.Client.Version}} / server {{.Server.Version}}'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # build:binary stamps NEXTCRAFT_VERSION_STAMP from the tag argument
+      # (build-binary.mjs validates it; `--version` reports it — G-102).
+      - name: Build x64 binary (SEA)
+        run: pnpm --filter @nextcraft/cli build:binary ${{ gitea.ref_name }}
+
+      - name: Verify artifacts
+        run: |
+          set -euo pipefail
+          BIN="apps/cli/dist/nextcraft-linux-x64"
+          SUM="$BIN.sha256"
+          [ -f "$BIN" ] || { echo "missing $BIN"; exit 1; }
+          [ -f "$SUM" ] || { echo "missing $SUM"; exit 1; }
+          # The sidecar names the bare file (build-binary.mjs) — verify from
+          # the dist dir so sha256sum -c resolves it (first CI run caught the
+          # repo-root CWD mismatch).
+          (cd "$(dirname "$BIN")" && sha256sum -c "$(basename "$SUM")")
+          echo "artifact size: $(stat -c%s "$BIN") bytes"
+
+      # Resolve the release id for the tag (the release is auto-created by
+      # Gitea on tag push if the repo setting is on; if not, create it
+      # first). Same call as scripts/release-assets.sh:32-49 (R-14).
+      - name: Resolve release id
+        run: |
+          set -euo pipefail
+          TAG="${{ gitea.ref_name }}"
+          BASE="https://git.coreci.dev/api/v1/repos/coreci/nextcraft"
+          RESPONSE="$(curl -sS -w '\n%{http_code}' \
+            -H "Authorization: token $RELEASE_TOKEN" \
+            "$BASE/releases/tags/$TAG")"
+          BODY="$(echo "$RESPONSE" | sed '$d')"
+          CODE="$(echo "$RESPONSE" | tail -1)"
+          if [ "$CODE" = "404" ]; then
+            echo "release for $TAG not found — creating it"
+            BODY="$(curl -sS -f -X POST \
+              -H "Authorization: token $RELEASE_TOKEN" \
+              -H 'Content-Type: application/json' \
+              -d "{\"tag_name\": \"$TAG\", \"name\": \"$TAG\"}" \
+              "$BASE/releases")"
+          else
+            echo "$CODE" | grep -q '^2' || { echo "release lookup failed: $CODE"; echo "$BODY"; exit 1; }
+          fi
+          RELEASE_ID="$(echo "$BODY" | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')"
+          echo "release id: $RELEASE_ID"
+          echo "RELEASE_ID=$RELEASE_ID" >> "$GITHUB_ENV"
+
+      # Attach binary + checksum. actions/upload-artifact is a DIFFERENT
+      # mechanism (job artifacts via the cache server, not release
+      # downloads) — do NOT use it here (R-14). curl multipart is the API.
+      - name: Attach binary + sha256 to release
+        run: |
+          set -euo pipefail
+          BASE="https://git.coreci.dev/api/v1/repos/coreci/nextcraft"
+          upload() {
+            local file="$1" name="$2"
+            curl -sS -f -X POST \
+              -H "Authorization: token $RELEASE_TOKEN" \
+              -F "attachment=@$file" \
+              "$BASE/releases/$RELEASE_ID/assets?name=$name" >/dev/null
+            echo "attached $name"
+          }
+          upload "apps/cli/dist/nextcraft-linux-x64" "nextcraft-linux-x64"
+          upload "apps/cli/dist/nextcraft-linux-x64.sha256" "nextcraft-linux-x64.sha256"
+
+      # -- P2 extension (REQ-8-002, R-20, D-065): build + push the docker
+      # image to the Gitea registry on every phase release ----------------
+      # The job token cannot publish packages (R-13, upstream-confirmed);
+      # REGISTRY_TOKEN (repo Actions secret, self-served at P1: G-205) is
+      # the PAT with package-write.
+      - name: Build docker image
+        run: |
+          set -euo pipefail
+          TAG="${{ gitea.ref_name }}"
+          docker build \
+            --build-arg NEXTCRAFT_VERSION="$TAG" \
+            -t "git.coreci.dev/coreci/nextcraft:$TAG" \
+            -t "git.coreci.dev/coreci/nextcraft:latest" \
+            .
+
+      - name: Push image to the Gitea registry
+        run: |
+          set -euo pipefail
+          echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.coreci.dev \
+            -u coreci --password-stdin
+          TAG="${{ gitea.ref_name }}"
+          docker push "git.coreci.dev/coreci/nextcraft:$TAG"
+          docker push "git.coreci.dev/coreci/nextcraft:latest"
+
+      # Smoke gate (G-204, five pinned assertions): a red image = red
+      # release. Probes run via docker exec INSIDE the container — the
+      # job container's 127.0.0.1 is not the host, and the smoke container
+      # publishes no ports (the admin-facing port map is the admin's call,
+      # not the gate's).
+      - name: Smoke gate — unprivileged run proves the honest degrade
+        run: |
+          set -euo pipefail
+          TAG="${{ gitea.ref_name }}"
+          CID=""
+          cleanup() { [ -n "$CID" ] && docker rm -f "$CID" >/dev/null 2>&1 || true; }
+          trap cleanup EXIT
+          CID="$(docker run -d "git.coreci.dev/coreci/nextcraft:$TAG")"
+          echo "container $CID up"
+
+          # 1. /health 200 within the window (in-container urllib — slim
+          #    has no curl; the HEALTHCHECK does the same)
+          ok=""
+          for i in $(seq 1 30); do
+            if docker exec "$CID" python3 -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8420/health', timeout=3).status == 200 else 1)" 2>/dev/null; then ok=1; break; fi
+            sleep 2
+          done
+          [ -n "$ok" ] || { echo "FAIL: /health never returned 200"; docker logs "$CID" 2>&1 | tail -30; exit 1; }
+          echo "assert 1/5: /health 200"
+
+          # 2. GET / is HTML with a real document marker (not just non-JSON
+          #    — the v0.4.6 lesson; G-204). One-line python: checks the
+          #    doctype/html prefix on the FULL lowered head, not a 6-char
+          #    slice (rc6 finding — the slice truncated the marker).
+          docker exec "$CID" python3 -c "import urllib.request,sys; body = urllib.request.urlopen('http://127.0.0.1:8420/', timeout=5).read(); head = body.lstrip()[:32].lower(); sys.exit(0 if (head.startswith(b'<!doctype') or head.startswith(b'<html')) else 1)" \
+            || { echo "FAIL: / is not HTML"; exit 1; }
+          echo "assert 2/5: / serves HTML"
+
+          # 3. degrade boot notice present in container logs (unprivileged
+          #    default → seccomp blocks userns → loud notice, D-068)
+          docker logs "$CID" 2>&1 | grep -q "SANDBOX FABRIC DEGRADED" \
+            || { echo "FAIL: degrade boot notice absent"; docker logs "$CID" 2>&1 | tail -30; exit 1; }
+          echo "assert 3/5: degrade notice logged"
+
+          # 4. fabric env-create is refused BEFORE the fabric (503 degraded
+          #    or 403 gate-first — both prove the degrade path short-circuits
+          #    learner env creation; a 201 would prove the fabric ran, which
+          #    an unprivileged container cannot allow). The probe python is
+          #    written to a file first (a yaml block scalar cannot embed
+          #    unindented command substitution continuations).
+          cat > /tmp/smoke_probe.py << 'PYEOF'
+          import urllib.request, urllib.error, json, sys
+          req = urllib.request.Request('http://127.0.0.1:8420/v1/sandboxes',
+              data=json.dumps({'learner_id':'smoke','task_id':'t'}).encode(),
+              headers={'Content-Type':'application/json'}, method='POST')
+          try:
+              print(urllib.request.urlopen(req, timeout=5).status)
+          except urllib.error.HTTPError as e:
+              print(e.code)
+          except Exception:
+              print('ERR')
+          sys.stdout.flush()
+          PYEOF
+          docker cp /tmp/smoke_probe.py "$CID":/tmp/smoke_probe.py
+          STATUS="$(docker exec "$CID" python3 /tmp/smoke_probe.py)"
+          [ "$STATUS" = "503" ] || [ "$STATUS" = "403" ] \
+            || { echo "FAIL: env-create was $STATUS (expected 503 degraded or 403 gate)"; exit 1; }
+          echo "assert 4/5: degraded env-create refused ($STATUS)"
+
+          # 5. in-container CLI speaks (embedded doctor reports the docker
+          #    channel — D-066) + clean stop
+          docker exec "$CID" nextcraft --version \
+            || { echo "FAIL: embedded CLI does not run"; exit 1; }
+          echo "assert 5/5: embedded CLI alive + clean stop"
+          docker rm -f "$CID" >/dev/null && CID=""

.gitignore

@@ -20,6 +20,8 @@ dist/
 .next/
 .turbo/
 *.tsbuildinfo
+# Next.js static export (v0.3.6 build output, served by the ai-service)
+apps/web/out/
 
 # Storybook
 storybook-static/
@@ -42,6 +44,7 @@ yarn-error.log*
 
 # Test coverage
 coverage/
+.coverage
 .nyc_output/
 
 # Python tooling caches
@@ -55,3 +58,6 @@ apps/ai-service/ai_service/data/
 apps/ai-service/**/sandboxes/
 *.db
 *.db-journal
+
+# in-sandbox capture agent runtime spool
+.nc-agent/

.npmrc

@@ -1,3 +1,3 @@
 shamefully-hoist=true
 strict-peer-dependencies=false
-pnpm-approved-builds=esbuild,core-js-pure
+pnpm-approved-builds=esbuild,core-js-pure

.pre-commit-config.yaml

@@ -0,0 +1,84 @@
+# Pre-commit hooks (D-070) — local hygiene mirroring the CI lanes.
+#
+# Design contract (G-209): every hook is LOCAL-ONLY (no network at hook
+# time — the mirror-style hooks below are fetched once at `pre-commit
+# install`/`pre-commit run` time from github.com, which this LAN reaches;
+# the language:system hooks run zero network). Hooks FAIL LOUD when the
+# toolchain is missing (D-070: a contributor without the toolbox gets an
+# explicit pointer, not a silent skip) — the no-toolbox escape is
+# `git commit --no-verify` (or `SKIP=...`), documented in README.md with
+# the loud note that CI still gates every push.
+#
+# Scope discipline mirrors .gitea/workflows/ci.yaml: ruff only touches
+# ai-service python; eslint/tsc only touch the TS workspaces; hygiene is
+# repo-wide.
+repos:
+  # ---- basic hygiene (repo-wide, zero toolchain required)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  # ---- ruff (ai-service python, D-063 lane parity)
+  # Runs the venv-relative binary exactly like apps/ai-service/scripts/lint.sh
+  # (venv is the repo's authority for the python toolchain). FAILS LOUD with
+  # a bootstrap hint if the venv is missing — never a silent skip.
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff check (ai-service)
+        entry: apps/ai-service/scripts/lint.sh
+        language: system
+        types: [python]
+        files: ^apps/ai-service/
+        pass_filenames: false
+
+      # ---- eslint (TS workspaces, ONE root flat config at eslint.config.mjs)
+      # Each workspace's `lint` script is `eslint .` resolving that config
+      # upward, so a single root invocation is exact parity with the node
+      # lane's per-workspace runs. `pnpm` resolves via PATH or corepack
+      # (same discovery as nextcraft doctor); FAILS LOUD if neither exists.
+      - id: eslint
+        name: eslint (TS workspaces)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM exec eslint apps/web apps/cli packages/ui packages/types packages/mock-data'
+        language: system
+        files: ^(apps/web|apps/cli|packages/ui|packages/types|packages/mock-data)/.*\.(ts|tsx|mjs|cjs)$
+        pass_filenames: false
+
+      # ---- tsc --noEmit per TS workspace (node-lane parity: pnpm --filter
+      # over the same five workspaces; the tsconfig graph stays per-project)
+      # (the shared PCMD discovery is repeated per hook because pre-commit
+      # hooks run isolated entries)
+      - id: tsc-web
+        name: tsc --noEmit (web)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM --filter web typecheck'
+        language: system
+        files: ^apps/web/.*\.tsx?$
+        pass_filenames: false
+      - id: tsc-cli
+        name: tsc --noEmit (cli)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM --filter @nextcraft/cli typecheck'
+        language: system
+        files: ^apps/cli/.*\.tsx?$
+        pass_filenames: false
+      - id: tsc-ui
+        name: tsc --noEmit (ui)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM --filter @nextcraft/ui typecheck'
+        language: system
+        files: ^packages/ui/.*\.tsx?$
+        pass_filenames: false
+      - id: tsc-types
+        name: tsc --noEmit (types)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM --filter @nextcraft/types typecheck'
+        language: system
+        files: ^packages/types/.*\.tsx?$
+        pass_filenames: false
+      - id: tsc-mock-data
+        name: tsc --noEmit (mock-data)
+        entry: bash -c 'PNPM="$(command -v pnpm || echo "corepack pnpm")"; $PNPM --filter @nextcraft/mock-data typecheck'
+        language: system
+        files: ^packages/mock-data/.*\.tsx?$
+        pass_filenames: false

Dockerfile

@@ -0,0 +1,111 @@
+# Nextcraft — single-port docker image (v0.8 P2, REQ-8-002, R-16..R-19)
+#
+# Topology: uvicorn :8420 serves BOTH the API (/v1/*, /health) and the
+# exported web UI (everything else) — the same single-port production
+# shape as `nextcraft deploy` (D-039). Deps are pre-loaded in image
+# layers; runtime is unprivileged by default (honest sandbox degrade:
+# ai_service/sandbox/capability.py probes + api/sandboxes.py 503s with
+# remediation — D-068/G-208).
+#
+# Build context is the repo root. Build args:
+#   NEXTCRAFT_VERSION  — stamped into the embedded CLI (`--version`)
+#
+# Stages:
+#   1. web-export — node:24-bookworm: pnpm workspace install, static
+#      export (NEXT_PUBLIC_AI_SERVICE_URL=self), SEA CLI binary build
+#   2. venv — python:3.11-bookworm: production deps only (no [dev])
+#   3. runtime — python:3.11-slim-bookworm: non-root, venv + package +
+#      export + CLI, /health healthcheck, state volume
+
+# -- stage 1: web export + CLI binary ---------------------------------------
+FROM node:24-bookworm AS web-export
+ARG NEXTCRAFT_VERSION=0.0.0-dev
+WORKDIR /repo
+
+# Toolchain: corepack ships with node 24 (deprecated but present).
+RUN corepack enable pnpm
+
+# Workspace manifests first (layer-cacheable install).
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml .npmrc tsconfig.json ./
+COPY apps/web/package.json apps/web/
+COPY apps/cli/package.json apps/cli/
+COPY packages/types/package.json packages/types/
+COPY packages/ui/package.json packages/ui/
+COPY packages/mock-data/package.json packages/mock-data/
+RUN pnpm install --frozen-lockfile
+
+# Sources (web build needs all workspaces; CLI build needs its tree).
+COPY apps ./apps
+COPY packages ./packages
+
+# Static export (same command as the deploy path): the export lands in
+# apps/web/out and is served same-origin by uvicorn.
+ENV NEXT_PUBLIC_AI_SERVICE_URL=self
+RUN pnpm --filter web build
+
+# Embedded CLI (D-066): doctor/verify/guide work in-container; the daemon
+# commands refuse honestly (see apps/cli/src — NC_CONTAINER detection).
+RUN pnpm --filter @nextcraft/cli build:binary "$NEXTCRAFT_VERSION"
+
+# -- stage 2: python venv ----------------------------------------------------
+FROM python:3.11-bookworm AS venv
+WORKDIR /repo
+# The full source tree installs the package (bootstrap.sh's mechanism
+# without [dev]: production deps only — the image runs the app, it never
+# lints/tests it; the runner lanes own that).
+COPY apps/ai-service /repo/apps/ai-service
+RUN python3 -m venv /opt/venv && \
+    /opt/venv/bin/pip install --no-cache-dir --upgrade pip && \
+    /opt/venv/bin/pip install --no-cache-dir /repo/apps/ai-service
+
+# -- stage 3: runtime --------------------------------------------------------
+FROM python:3.11-slim-bookworm AS runtime
+WORKDIR /opt/nextcraft
+
+# Non-root user; home carries the state volume (~/.nextcraft semantics —
+# config.py anchors db/sandboxes under $HOME/.nextcraft, R-17).
+RUN useradd --create-home --uid 10001 nextcraft
+
+# venv from stage 2 (production deps only).
+COPY --from=venv /opt/venv /opt/venv
+ENV PATH=/opt/venv/bin:$PATH
+
+# The installed ai_service package is IN the venv's site-packages; the
+# source tree rides along for transparency (PYTHONPATH prefers the
+# installed package).
+COPY --from=venv /repo/apps/ai-service /opt/nextcraft/ai-service-src
+RUN rm -rf /opt/nextcraft/ai-service-src/.venv
+
+# Web export from stage 1.
+COPY --from=web-export /repo/apps/web/out /opt/nextcraft/web-out
+ENV AI_WEB_STATIC_DIR=/opt/nextcraft/web-out
+
+# Image marker: NC_CONTAINER=1 (context for the CLI container-mode
+# branches and the degrade boot notice; the capability PROBE — not this
+# marker — decides degrade, D-068).
+ENV NC_CONTAINER=1
+
+# Embedded CLI (D-066).
+COPY --from=web-export /repo/apps/cli/dist/nextcraft-linux-x64 /usr/local/bin/nextcraft
+RUN chmod 0755 /usr/local/bin/nextcraft
+
+# App dir + state: db/sandboxes under /home/nextcraft/.nextcraft (R-17).
+# The state root is pre-created with correct ownership BEFORE the VOLUME
+# declaration — an anonymous volume copies the image's directory CONTENTS
+# and ownership at first use, so the app (uid 10001) can mkdir its data/
+# and sandboxes/ subdirs on a clean boot (rc5 smoke-gate finding: the
+# bare useradd home did not carry a writable .nextcraft).
+RUN mkdir -p /home/nextcraft/.nextcraft/data \
+    && chown -R nextcraft:nextcraft /opt/nextcraft /home/nextcraft/.nextcraft
+WORKDIR /opt/nextcraft/ai-service-src
+USER nextcraft
+ENV AI_HOST=0.0.0.0 AI_PORT=8420
+
+EXPOSE 8420
+# slim has no curl — the healthcheck speaks python (stdlib urllib).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD ["python3", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8420/health', timeout=4).status == 200 else 1)"]
+
+VOLUME ["/home/nextcraft/.nextcraft"]
+
+CMD ["python3", "-m", "uvicorn", "ai_service.main:app", "--host", "0.0.0.0", "--port", "8420"]

README.md

@@ -2,8 +2,117 @@
 
 AI-native outcome school + marketplace — graduates prove what they can build, not what they can write.
 
+## Quickstart
+
+One-liner install (linux x64):
+
+```sh
+curl -fsSL https://git.coreci.dev/coreci/nextcraft/raw/main/scripts/install.sh | sh
+```
+
+That downloads the latest release's `nextcraft` CLI binary, verifies its sha256 checksum, and installs it to `~/.local/bin` (PATH hint printed if needed). Every release ships fresh binaries — re-run the one-liner to upgrade.
+
+### Server (deploy the whole stack, one command)
+
+```sh
+nextcraft deploy --service
+```
+
+That clones (or updates) the repo, installs deps, builds the web UI, restarts the service, verifies the site is served, and installs a systemd unit so the stack survives reboots. Idempotent — same command for first install and upgrades. Toolchain discovery included: node/pnpm behind nvm/PNPM_HOME/corepack are found even when non-interactive shells can't see them.
+
+### Development (from a clone of this repo)
+
+```sh
+nextcraft doctor      # check prerequisites: node >= 18, pnpm >= 8, python3 >= 3.11, git, unshare
+nextcraft bootstrap   # pnpm install + ai-service venv + .env from template (idempotent)
+nextcraft verify      # health check: venv imports, uvicorn, ports, env, web export, live mount probe
+nextcraft dev         # run the ai-service dev server on :8420 (web dev server: pnpm dev)
+```
+
+The E2E test (`apps/cli/tests/fresh-clone-e2e.test.ts`) proves this exact sequence on a fresh clone.
+
+#### Pre-commit hooks (optional, recommended)
+
+The repo ships a `.pre-commit-config.yaml` that mirrors the CI lanes locally: ruff over the ai-service python, eslint over the five TS workspaces (one root flat config), `tsc --noEmit` per workspace, plus whitespace/merge-conflict/large-file hygiene. Hooks are local-only and fail loud.
+
+```sh
+pip install pre-commit   # or: pipx install pre-commit
+pre-commit install
+```
+
+From then on every `git commit` runs the hooks on the staged changes. First run may fetch the hygiene hook repo (github.com, reachable from this LAN).
+
+**No toolbox? The honest skip path:** if you don't have the ruff/eslint/tsc toolchain set up (e.g. no ai-service venv yet — run `nextcraft bootstrap` first), hooks will fail loud with a pointer. The simplest honest escape for a contributor without the toolbox is:
+
+```sh
+git commit --no-verify
+```
+
+or skip specific hooks for one commit:
+
+```sh
+SKIP=ruff,eslint,tsc-web,tsc-cli,tsc-ui,tsc-types,tsc-mock-data git commit
+```
+
+**Loud note: CI still gates.** Skipping locally changes nothing about the push lanes — `.gitea/workflows/ci.yaml` runs lint + typecheck + tests on every push to every branch. A `--no-verify` commit that breaks lint gets caught at push time, just later and more publicly.
+
+### No binary / non-linux?
+
+The installer degrades to printed source instructions. Manual equivalent:
+
+```sh
+git clone https://git.coreci.dev/coreci/nextcraft.git && cd nextcraft
+pnpm install
+bash apps/ai-service/scripts/bootstrap.sh
+cp apps/ai-service/.env.example apps/ai-service/.env
+pnpm ai:dev
+```
+
+## CLI reference (`nextcraft`)
+
+| Command | What it does | Exit codes |
+|---------|--------------|------------|
+| `doctor` | Checks prerequisites: node >= 18, pnpm >= 8 (discovered via PATH/nvm/PNPM_HOME/corepack), python3 >= 3.11, git, unshare (sandbox fabric). Every ✗ prints a fix hint. | 0 all pass, 1 any fail |
+| `bootstrap` | Sets up the monorepo from a fresh clone: (1) locates the repo root, (2) `pnpm install` (discovered toolchain), (3) ai-service venv via `apps/ai-service/scripts/bootstrap.sh`, (4) copies `.env.example` → `.env` if absent, (5) warns on missing optional keys. Idempotent — safe to re-run. | 0 ok, 1 step failed |
+| `verify` | Health check: ai-service venv + `import ai_service`, uvicorn importable, `.env` present (warn-only), `AI_PORT` state — free, or **busy + serving the web UI** (live mount probe: `/` must return HTML, not the API's JSON 404), web export present (`apps/web/out`), workspace `node_modules`. | 0 ok, 1 failures |
+| `deploy` | One-command deploy/upgrade: clone-or-update repo (`--dir`, `--ref`), `pnpm install`, ai-service venv, `NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build`, restart, verify. Fails loudly if the site isn't served. | 0 ok, 1 step failed |
+| `deploy --service` | Same, plus generates + installs a systemd unit (real paths, `Restart=always`, enabled) so the stack survives reboots; systemd becomes the supervisor. | 0 ok, 1 step failed |
+| `dev` | Thin passthrough to `apps/ai-service/scripts/dev.sh` (exports secrets from `.ciagent/.env.secrets` if present, runs uvicorn on :8420). Ctrl+C stops it. The web dev server is separate: `pnpm dev`. | child's exit code |
+| `dev -d` / `dev --detach` | Same, but as an **unattended daemon**: detached, output appended to `~/.nextcraft/run/<clone>/dev.log`, pidfile beside it. Refuses to double-start (and refuses when the systemd service is active). Auto-serves the built web UI same-origin when `apps/web/out` exists. | 0 started, 1 already running |
+| `stop` | Stops the systemd service when it supervises the stack; otherwise stops the daemon started by `dev -d` (SIGTERM, SIGKILL after 5s) and cleans the pidfile. | 0 stopped/clean, 1 kill failed |
+| `log` | Tails the daemon log: last 50 lines by default, `-n N` for more, `-f`/`--follow` to stream. | 0 ok, 1 no log yet |
+| `--help` / `-h` | Usage for the CLI or any command. | 0 |
+| `--version` | Prints the version this binary was built as (matches the release tag). | 0 |
+
+Exit-code contract: `0` success, `1` check/step failure (hint printed), `2` usage error.
+
+### Remote server / single-port deployment
+
+`nextcraft dev` binds the API on **0.0.0.0:8420** (and `pnpm dev` serves the web app on all interfaces), so the stack works from other machines out of the box:
+
+- Browse `http://<your-host>:3000` — the web app targets `http://<your-host>:8420` automatically (derived from the browser's hostname).
+- CORS admits any origin (`AI_CORS_ORIGINS=*` in `apps/ai-service/.env`). This is safe **only** because credentials are never enabled; to restrict, set an explicit list: `AI_CORS_ORIGINS=http://<your-host>:3000`.
+- To revert to loopback-only: `AI_HOST=127.0.0.1` in `apps/ai-service/.env`.
+- Security note: this is an unauthenticated dev API reachable from any network the box exposes. Mitigations that still apply: per-learner sandbox caps + global rate caps + learner allowlist (G-5), telemetry flood control (traces marked `INCOMPLETE_FLOODED` are refused by the grader). Expose only on trusted networks until identity/KYC lands (v0.5).
+
+**Production behind one port (v0.3.6):** when only one port is reachable (e.g. behind HAProxy), the one-command deploy builds the web app as a static export and lets the ai-service serve it same-origin on :8420 — UI and API on one port, no CORS, no mixed content:
+
+```sh
+nextcraft deploy --service   # install/upgrade + web export + restart + verify + systemd unit
+```
+
+Durable state (SQLite DB, sandbox workdirs, daemon pid/log) lives in `~/.nextcraft/` — never inside the repo. Full recipe incl. HAProxy timeouts and a systemd unit: [deploy/README.md](deploy/README.md).
+
+## Docs
+
+- [apps/cli/README.md](apps/cli/README.md) — CLI internals: build, binary pipeline, troubleshooting
+- [.ciagent/PROJECT.md](.ciagent/PROJECT.md) — product spec and milestone history
+- [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) — system architecture
+
 ## Status
 
-**Milestone v0.1** — UI/UX Prototype (high-fidelity interactive, all mock data)
+**Milestone v0.6** — Marketplace Engine (shipped as v0.5.6): real job-postings backend behind the marketplace surfaces (6th SQLite store family + seeded ingestion adapter + admin authoring surface), AI tagging with facet-driven filters, embedding-backed semantic search with computed match scores, employer enrichment with per-field provenance, resume-to-profile auto-fill with an explicit confirm gate, and SEO programmatic pages (metadata, JSON-LD, dynamic sitemap/robots).
 
-Initialized via CIAgent v0.7.0
+Prior: v0.5 Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease (shipped as v0.4.5) · v0.3 Credential Engines (v0.2.8) · v0.2 AI Tutor Architecture (v0.2.0) · v0.1 UI/UX Prototype (v0.1.0)
+
+Initialized via CIAgent v0.7.0

apps/ai-service/.env.example

@@ -2,6 +2,13 @@
 # Real keys live in .ciagent/.env.secrets (gitignored) and are exported by scripts/dev.sh
 
 AI_PORT=8420
+# Network mode (v0.3.5, D-038): dev server binds 0.0.0.0 so remote machines can
+# reach the stack. Set to 127.0.0.1 to revert to loopback-only.
+AI_HOST=0.0.0.0
+# CORS + WS-origin policy: '*' (default) admits any origin — safe because
+# credentials are never enabled. Restrict with a comma list, e.g.:
+#   AI_CORS_ORIGINS=http://nextcraft-1:3000
+AI_CORS_ORIGINS=*
 AI_PROVIDER=ollama-cloud
 AI_MODEL=gemma4:31b
 AI_OLLAMA_CLOUD_BASE_URL=https://ollama.com/v1
@@ -9,8 +16,10 @@ AI_OLLAMA_CLOUD_API_KEY=
 AI_LOCAL_BASE_URL=http://localhost:11434/v1
 AI_JSON_MODE=auto
 
-# Sandbox fabric (v0.3)
-AI_SANDBOX_DIR=sandboxes
+# Sandbox fabric (v0.3). v0.3.6: durable state defaults to ~/.nextcraft/ —
+# OUTSIDE the repo (the old repo-relative 'sandboxes' default polluted the
+# git tree). Set an absolute path (~/ works) or a repo-relative one only for
+# throwaway dev clones.
 AI_SANDBOX_MAX_CONCURRENT=5
 AI_SANDBOX_TIMEOUT_S=900
 AI_SANDBOX_MAX_WORKDIR_MB=512
@@ -23,5 +32,74 @@ AI_SANDBOX_MAX_PER_LEARNER=1
 # global creates per rolling 60s window (in-memory) → 429 when exceeded
 AI_SANDBOX_CREATES_PER_MIN=10
 
-# Persistence (SQLite)
-AI_DB_PATH=ai_service/data/nextcraft.db
+# Persistence (SQLite). v0.3.6: default moved out of the repo to
+# ~/.nextcraft/data/nextcraft.db (~/ paths in env overrides are expanded).
+# Uncomment + edit ONLY to relocate:
+# AI_DB_PATH=~/.nextcraft/data/nextcraft.db
+
+# Single-port deploy (v0.3.6): directory of the exported web app
+# (apps/web/out). When set, the UI is served from this same service on :8420
+# — build it with `NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build`. The
+# `nextcraft dev` command auto-sets this when apps/web/out exists.
+# AI_WEB_STATIC_DIR=../../web/out
+# --- Identity (REQ-5-003, D-042) ---
+# 'mock' (default — deterministic, no vendor spend pre-pilot; verdicts carry
+# mock=True forever per A-304). A real KYC vendor drops in via the
+# IdentityProvider protocol without API changes.
+AI_IDENTITY_PROVIDER=mock
+# G-13: identity submit caps — one active pending per learner (409), and a
+# per-learner submit rate ceiling (429 over a rolling 60s window).
+AI_IDENTITY_SUBMITS_PER_MIN=3
+
+# --- Voice (REQ-3-006 D-030; real server path REQ-5-001, D-040) ---
+# 'mock' (default; no key needed — tests/dev), 'browser' (client-native
+# SR/TTS), or 'openai-audio' (real server STT/TTS, live since v0.5).
+AI_VOICE_PROVIDER=mock
+# openai-audio requires BOTH (unconfigured → app boots, voice falls back to
+# mock with a loud log — G-11; the badge then honestly reports mock):
+# AI_VOICE_BASE_URL=https://your-audio-endpoint/v1
+# AI_VOICE_API_KEY=
+# Optional model/voice/format knobs (defaults shown):
+# AI_VOICE_STT_MODEL=whisper-1
+# AI_VOICE_TTS_MODEL=tts-1
+# AI_VOICE_TTS_VOICE=alloy
+# AI_VOICE_TTS_FORMAT=mp3      (enum: mp3 | wav | opus)
+# AI_VOICE_MAX_AUDIO_MB=10
+# Manual probe recipe (executable by anyone with the keys; never CI):
+#   STT: curl -sS $AI_VOICE_BASE_URL/audio/transcriptions \
+#          -H "Authorization: Bearer $AI_VOICE_API_KEY" \
+#          -F file=@test/fixtures/answer.wav -F model=whisper-1 | jq -e '.text'
+#   TTS: curl -sS $AI_VOICE_BASE_URL/audio/speech \
+#          -H "Authorization: Bearer $AI_VOICE_API_KEY" \
+#          -H 'Content-Type: application/json' \
+#          -d '{"model":"tts-1","input":"Nextcraft","voice":"alloy"}' \
+#          -o /tmp/probe.mp3 && file /tmp/probe.mp3 | grep -i audio
+
+# --- Marketplace (REQ-6-001, D-057) ---
+# Founder/admin surface guard (/v1/marketplace/admin/*): send as the
+# 'X-Admin-Token' header OR 'Authorization: Bearer <token>'; compared
+# constant-time (G-108). UNSET = every admin route 403s (fail-closed,
+# never open) and the boot log warns loudly. Never commit real tokens.
+# AI_ADMIN_TOKEN=
+# P5 (D-056) placeholder: the deployed origin for sitemap.xml / robots.txt
+# absolute URLs (e.g. https://nextcraft.example). Unset → SEO phase
+# serves the empty static-page set with a boot warning (G-105).
+# AI_PUBLIC_BASE_URL=
+
+# --- Semantic search embeddings (REQ-6-003, D-051) ---
+# 'mock' (default — deterministic 256-dim feature-hash, pure stdlib, no
+# key needed; tests never call a real embeddings API) or 'openai-embed'.
+AI_EMBED_PROVIDER=mock
+# openai-embed requires ALL THREE below; unconfigured → the app boots and
+# embeddings fall back to mock with a loud log (G-11).
+# PROBE CORRECTION (D-051): ollama-cloud does NOT expose /embeddings —
+# point AI_EMBED_BASE_URL at any OTHER OpenAI-compatible endpoint,
+# e.g. a LOCAL ollama at http://localhost:11434/v1, or any embeddings cloud.
+# AI_EMBED_BASE_URL=http://localhost:11434/v1
+# AI_EMBED_API_KEY=
+# AI_EMBED_MODEL=nomic-embed-text
+# Manual probe recipe (executable by anyone with the keys; never CI):
+#   curl -sS $AI_EMBED_BASE_URL/embeddings \
+#     -H "Authorization: Bearer $AI_EMBED_API_KEY" \
+#     -H 'Content-Type: application/json' \
+#     -d '{"model":"'"$AI_EMBED_MODEL"'","input":["Nextcraft probe"]}' | jq -e '.data[0].embedding | length'

apps/ai-service/README.md

@@ -194,6 +194,65 @@ Unprivileged user namespaces are on the box's kernel and need neither a
 daemon, nor suid helpers, nor network access — they are the only isolation
 primitive that works here, so that's what v0.3 uses.
 
+## Telemetry delivery semantics (v0.3, REQ-3-003)
+
+Delivery is **at-least-once**; storage is **exactly-once** — the two compose:
+
+- The in-sandbox capture agent (stdlib-only, `scripts/sandbox-agent.py`)
+  spools every event to a durable JSONL file (fsync per append) BEFORE any
+  send attempt, so no event can be lost to a dead socket or a SIGKILL.
+- The WS ingest endpoint (`WS /v1/telemetry/ingest?learner_id&task_id`,
+  D-026) dedups server-side on the `(learner_id, task_id, seq)` primary key:
+  re-sends (reconnect flushes, replay margin) are collapsed, never upserted.
+- On disconnect the agent reconnects with exponential backoff and flushes
+  the spool in `seq` order; a transient outage therefore loses nothing and
+  stores each event exactly once (`tests/telemetry/test_durability.py`
+  proves this end-to-end against a real namespace sandbox + live server).
+- Replay/read path: `GET /v1/telemetry/traces/{learner}/{task}` returns the
+  complete ordered trace; `GET /v1/telemetry/gaps/{learner}/{task}` returns
+  missing seqs for gap detection.
+- Flood boundary (G-3): a connection exceeding `AI_TELEMETRY_MAX_EVENTS_PER_TASK`
+  (default 50,000) is closed with WS code 1008 and its trace is marked
+  `INCOMPLETE_FLOODED` — a terminal integrity flag the grader refuses to
+  grade. Silent event dropping is forbidden: it would corrupt grading input.
+
+## Voice defense (v0.3, REQ-3-006)
+
+Voice is **mock-first** (D-030): the defense pipeline is fully proven over
+the deterministic `MockVoiceProvider` + browser-native fallback — no task
+requires a real voice key. Real server STT/TTS (`OpenAIAudioProvider` over
+OpenAI-compatible `/audio/transcriptions` + `/audio/speech`) is **deferred
+to v0.4** together with KYC (GRILL CUT-1 / G-7): it could never be exercised
+in CI, so v0.3 ships the protocol seam instead of an unverifiable claim.
+
+- `AI_VOICE_PROVIDER=mock` (default) — deterministic canned STT/TTS
+- `AI_VOICE_PROVIDER=browser` — the web client uses SpeechRecognition +
+  speechSynthesis; the server keeps text-turn persistence
+- Conversational budget: a defense turn should complete in **< 4s**
+  (`DEFENSE_TURN_BUDGET_MS` in `tests/voice/test_latency.py`). v0.3
+  asserts instrumentation (stt_ms/llm_ms/tts_ms populated per turn); the
+  wall-clock acceptance probe against a real voice endpoint is a v0.4
+  criterion, run manually with `AI_VOICE_PROVIDER` set to the real
+  provider and keys in `.ciagent/.env.secrets` (never in code/commits).
+
+## End-to-end credential flow (v0.3, REQ-3-007/008)
+
+`tests/api/test_e2e_credential_flow.py` runs the full pipeline against a REAL
+uvicorn server with REAL namespace sandboxes (mock LLM/voice per G-2
+precedent): variant -> telemetry-wired sandbox -> in-sandbox exec -> trace
+persistence -> process-trace grade (variant seed stamped) -> assessor
+coaching -> oral defense -> verdict + integrity signals -> proctor. It
+asserts no corpus fixture appears anywhere in the learner path.
+
+Manual browser pass (documented, not automated): `pnpm ai:dev` + `pnpm dev`,
+then open `/build/stack-orchestration-c007` — variant statement + starter
+files load, edit a file, Run/Test execute in the sandbox with output in the
+read-only panel, the telemetry status pulses, Lab streams feedback from the
+live digest; then `/defend/stack-orchestration-c007` — Start Defense, typed
+answers (mic path needs permission), Finish, Grade My Work renders the real
+rubric bars. Navigating away destroys the sandbox
+(`curl localhost:8420/v1/sandboxes` shows the count drop).
+
 ## Layout
 
 ```
@@ -206,4 +265,4 @@ scripts/        bootstrap.sh dev.sh test.sh lint.sh
 tests/          pytest — mock provider only
 ```
 
-Boundary rules: `llm/` imports nothing from `agents/` or `api/`; `agents/` imports nothing from `api/`.
+Boundary rules: `llm/` imports nothing from `agents/` or `api/`; `agents/` imports nothing from `api/`.

apps/ai-service/ai_service/__init__.py

@@ -1,3 +1,38 @@
-"""Nextcraft AI tutor service — six LLM agents behind a provider-agnostic layer."""
+"""Nextcraft AI tutor service — six LLM agents behind a provider-agnostic layer.
 
-__version__ = "0.2.0"
+Version single-source (D-061): pyproject.toml is the ONE place the version
+literal lives. `__version__` (and FastAPI's `version=`) resolve from, in order:
+
+  1. the installed distribution metadata (pip install -e builds it from
+     pyproject at install time), falling back to
+  2. the source tree's pyproject.toml via tomllib (un-installed source runs).
+
+No fallback literal exists — drift is structurally impossible: if pyproject
+bumps, both paths follow. Path 2 only degrades when neither metadata nor a
+pyproject.toml exists (a bare directory copy), reported as "unknown".
+"""
+
+import tomllib
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from pathlib import Path
+
+_DIST_NAME = "nextcraft-ai-service"
+
+
+def _resolve_version() -> str:
+    try:
+        return _dist_version(_DIST_NAME)
+    except PackageNotFoundError:
+        pass
+    # Un-installed source run: read the source tree's pyproject.toml
+    # (ai_service/__init__.py → ../pyproject.toml).
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        return str(data["project"]["version"])
+    except (OSError, KeyError, tomllib.TOMLDecodeError):
+        return "unknown"
+
+
+__version__ = _resolve_version()

apps/ai-service/ai_service/agents/assessor.py

@@ -1,53 +1,34 @@
-"""AssessorAgent — rubric application to pre-baked artifacts (REQ-2-008).
+"""AssessorAgent — rubric coaching over REAL grading output (REQ-3-007).
 
-Structured-output showcase: applies the 4-layer defense (D-020) to return
-a pydantic-validated rubric score. Mock engine inputs (corpus artifacts +
-transcripts); real process-trace grading is v0.3+.
+v0.3 re-grounding: the Assessor no longer invents scores from corpus
+artifacts — the process-trace grading engine (Phase 3) computes and
+persists the validated RubricScore. This agent now renders the STORED
+grade as rubric-anchored coaching: explains the criteria, cites strengths
+and gaps, and frames next steps. Corpus artifacts are retired from this
+path (corpus dormancy, Task 6-1-04).
 """
 
 from pydantic import BaseModel, Field
 
-from ..corpus.artifacts import (
-    ArtifactSubmission,
-    AssessmentRubric,
-    DefenseTranscript,
-    render_rubric,
-    render_transcript,
-)
 from ..corpus.learner_context import LearnerContext, get_learner_context
+from ..grading.store import GradeRecord
 from ..prompts.assessor import SYSTEM_PROMPT, render_context
 from .base import BaseAgent
 
 
-class CriterionScore(BaseModel):
-    criterion_id: str
-    name: str
-    score: int = Field(ge=0, le=100)
-    evidence: str
+class GradeCoaching(BaseModel):
+    """Rubric-anchored coaching rendered FROM the stored grade (not invented)."""
+
+    summary: str = Field(min_length=1)
+    strengths: list[str] = Field(min_length=1, max_length=3)
+    gaps: list[str] = Field(min_length=1, max_length=3)
+    next_steps: list[str] = Field(min_length=1, max_length=3)
 
 
-class RubricScore(BaseModel):
-    rubric_id: str
-    artifact_id: str
-    competency_id: str
-    scores: list[CriterionScore]
-    strengths: list[str] = Field(min_length=1, max_length=2)
-    gaps: list[str] = Field(min_length=1, max_length=2)
-    verdict: str  # "mastered" | "developing" | "not_yet"
-
-    def weighted_total(self, rubric: AssessmentRubric) -> float:
-        by_id = {c.criterion_id: c for c in rubric.criteria}
-        total = 0.0
-        for s in self.scores:
-            total += s.score * by_id[s.criterion_id].weight
-        return total
-
-
-RUBRIC_SCORE_SCHEMA_HINT = (
-    '{"rubric_id": "<id>", "artifact_id": "<id>", "competency_id": "<id>", '
-    '"scores": [{"criterion_id": "<id>", "name": "<name>", "score": <0-100>, '
-    '"evidence": "<one sentence>"}], "strengths": ["<one sentence>"], '
-    '"gaps": ["<one sentence>"], "verdict": "mastered"|"developing"|"not_yet"}'
+GRADE_COACHING_SCHEMA_HINT = (
+    '{"summary": "<two sentences on the grade>", '
+    '"strengths": ["<one sentence>"], "gaps": ["<one sentence>"], '
+    '"next_steps": ["<one sentence>"]}'
 )
 
 
@@ -58,35 +39,25 @@ class AssessorAgent(BaseAgent):
         ctx = learner_context or get_learner_context()
         return SYSTEM_PROMPT.format_map(render_context(ctx))
 
-    def build_evaluation_input(
+    async def coach_grade(
         self,
-        artifact: ArtifactSubmission,
-        rubric: AssessmentRubric,
-        transcript: DefenseTranscript | None,
-    ) -> str:
-        parts = [
-            f"ARTIFACT: {artifact.name} ({artifact.artifact_id})",
-            f"Evidence excerpt: {artifact.evidence_excerpt}",
-            "",
-            render_rubric(rubric),
-        ]
-        if transcript is not None:
-            parts += ["", render_transcript(transcript)]
-        return "\n".join(parts)
-
-    async def evaluate(
-        self,
-        artifact: ArtifactSubmission,
-        rubric: AssessmentRubric,
-        transcript: DefenseTranscript | None,
+        grade: GradeRecord,
         learner_context: LearnerContext | None = None,
-    ) -> RubricScore:
-        evaluation_input = self.build_evaluation_input(artifact, rubric, transcript)
-        score: RubricScore = await self.structured_reply(
+    ) -> GradeCoaching:
+        """Render the STORED grade as coaching via the D-020 defense."""
+        grade_json = {
+            "verdict": grade.verdict,
+            "scores": grade.scores,
+            "digest": grade.digest,
+        }
+        coaching: GradeCoaching = await self.structured_reply(
             history=None,
-            user_input=evaluation_input,
+            user_input=(
+                "The learner's process-trace grade (computed by the grading "
+                f"engine) is:\n{grade_json!r}\nExplain it as coaching."
+            ),
             learner_context=learner_context,
-            schema=RubricScore,
-            schema_hint=RUBRIC_SCORE_SCHEMA_HINT,
+            schema=GradeCoaching,
+            schema_hint=GRADE_COACHING_SCHEMA_HINT,
         )
-        return score
+        return coaching

apps/ai-service/ai_service/agents/base.py

@@ -6,6 +6,7 @@ The default pipeline: build_messages() → provider.stream_chat()/chat().
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
+from typing import TypeVar
 
 from pydantic import BaseModel
 
@@ -15,6 +16,8 @@ from ..llm.base import LLMProvider
 from ..llm.types import Message
 from .structured import structured_completion
 
+T = TypeVar("T", bound=BaseModel)
+
 
 class BaseAgent(ABC):
     """A tutor agent: system prompt + message assembly + provider delegation."""
@@ -64,10 +67,15 @@ class BaseAgent(ABC):
         history: list[Message] | None = None,
         user_input: str = "",
         learner_context: LearnerContext | None = None,
-        schema: type[BaseModel] | None = None,
+        schema: type[T] | None = None,
         schema_hint: str = "",
-    ) -> BaseModel:
-        """Non-streaming completion parsed into a pydantic model (D-020 defense)."""
+    ) -> T:
+        """Non-streaming completion parsed into a pydantic model (D-020 defense).
+
+        P5: generic over `schema` — the returned model is the schema's own
+        type, so callers (assessor/proctor) get concrete types, no casts.
+        `schema=None` raises before T is ever produced.
+        """
         if schema is None:
             raise ValueError("structured_reply requires a schema")
         messages = self.build_messages(history, user_input, learner_context)

apps/ai-service/ai_service/agents/examiner.py

@@ -0,0 +1,104 @@
+"""ExaminerAgent — the seventh agent: oral-defense examiner (REQ-3-006, A-109).
+
+BOUNDARY DECISION (PERSONAS conflict rule, honored by construction): the
+examiner is a TEXT agent. It composes the LLM provider through BaseAgent and
+consumes defense transcript turns; it NEVER imports voice/ — STT/TTS belong
+to the API endpoints (they move audio bytes; the agent moves question text).
+Integrity signals (long pauses, off-scope cadence) are computed by the
+endpoint layer from turn metadata (latency_ms etc.), not by the agent.
+
+Digest discipline (D-028 mirror): questions are grounded in the compact
+TraceDigest + variant statement — never the raw trace, never learner ids.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..grading.features import TraceDigest
+from ..llm.types import Message
+from ..prompts.examiner import SYSTEM_PROMPT, VERDICT_SCHEMA_HINT, render_digest_context
+from .base import BaseAgent
+
+
+class DefenseVerdict(BaseModel):
+    """D-20-validated final defense verdict (structured mode)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    verdict: str = Field(pattern="^(mastered|developing|not_yet)$")
+    understanding: str = Field(min_length=1)
+    process_justification: str = Field(min_length=1)
+    communication: str = Field(min_length=1)
+    strengths: list[str] = Field(min_length=1, max_length=2)
+    gaps: list[str] = Field(min_length=1, max_length=2)
+
+
+class ExaminerAgent(BaseAgent):
+    """Conducts the oral defense: next_question + final_verdict."""
+
+    name = "examiner"
+
+    def system_prompt(self, learner_context=None) -> str:
+        """Examiner is context-free (digest-anonymous, D-028 mirror)."""
+        return SYSTEM_PROMPT
+
+    def build_defense_messages(
+        self,
+        trace_digest: TraceDigest | None = None,
+        variant_statement: str | None = None,
+        history: list[Message] | None = None,
+    ) -> list[Message]:
+        """System + grounding + defense transcript (no learner id — D-028)."""
+        digest_json = (
+            trace_digest.model_dump_json() if trace_digest is not None else "{}"
+        )
+        messages: list[Message] = [
+            Message(role="system", content=SYSTEM_PROMPT),
+            Message(role="user", content=render_digest_context(digest_json, variant_statement)),
+            Message(
+                role="assistant",
+                content="Understood. I will question the learner about this build session.",
+            ),
+        ]
+        for m in history or []:
+            messages.append(m)
+        return messages
+
+    async def next_question(
+        self,
+        history: list[Message],
+        trace_digest: TraceDigest | None = None,
+        variant_statement: str | None = None,
+    ) -> str:
+        """One examiner question (streamed over SSE by the endpoints)."""
+        messages = self.build_defense_messages(trace_digest, variant_statement, history)
+        messages.append(
+            Message(role="user", content="Ask the learner your next question now.")
+        )
+        reply = await self.provider.chat(messages, model=self.settings.model)
+        return reply
+
+    async def final_verdict(
+        self,
+        history: list[Message],
+        trace_digest: TraceDigest | None = None,
+        variant_statement: str | None = None,
+    ) -> DefenseVerdict:
+        """Structured verdict via the D-020 4-layer defense."""
+        from .structured import structured_completion  # module-direct (G-4)
+
+        messages = self.build_defense_messages(trace_digest, variant_statement, history)
+        messages.append(
+            Message(
+                role="user",
+                content="The defense is finished. Return the final verdict JSON now.",
+            )
+        )
+        return await structured_completion(
+            self.provider,
+            messages,
+            model=self.settings.model,
+            schema=DefenseVerdict,
+            schema_hint=VERDICT_SCHEMA_HINT,
+        )

apps/ai-service/ai_service/agents/lab.py

@@ -1,17 +1,18 @@
-"""LabAgent — in-flow feedback over simulated sandbox telemetry (REQ-2-007).
+"""LabAgent — in-flow feedback over LIVE sandbox telemetry (REQ-3-007).
 
-Scenario-driven: consumes a LabTelemetryScenario from the corpus, renders
-the event timeline into the conversation, streams concrete feedback.
-No session chat — each request is one scenario read.
+v0.3 re-grounding: consumes a TraceDigest computed from the learner's real
+trace (grading/features.compute_digest over TraceStore events) — the v0.2
+corpus scenarios are retired from this path (corpus dormancy, Task 6-1-04).
+No session chat — each request is one live-trace read.
 """
 
 from collections.abc import AsyncIterator
 
 from ..config import Settings
 from ..corpus.learner_context import LearnerContext, get_learner_context
-from ..corpus.telemetry import LabTelemetryScenario, summarize_scenario
+from ..grading.features import TraceDigest
 from ..llm.base import LLMProvider
-from ..prompts.lab import SYSTEM_PROMPT, render_context
+from ..prompts.lab import SYSTEM_PROMPT, render_context, render_digest_timeline
 from .base import BaseAgent
 
 
@@ -27,10 +28,11 @@ class LabAgent(BaseAgent):
 
     async def stream_feedback(
         self,
-        scenario: LabTelemetryScenario,
+        digest: TraceDigest | None,
         learner_context: LearnerContext | None = None,
     ) -> AsyncIterator[str]:
-        timeline = summarize_scenario(scenario)
+        """Feedback grounded in the learner's live trace digest."""
+        timeline = render_digest_timeline(digest)
         async for token in self.stream_reply(
             history=None, user_input=timeline, learner_context=learner_context
         ):

apps/ai-service/ai_service/agents/proctor.py

@@ -1,33 +1,41 @@
-"""ProctorAgent — integrity signals + coaching interventions (REQ-2-009).
+"""ProctorAgent — integrity signals + coaching over REAL inputs (REQ-3-007).
 
-Consumes a ProctorScenario from the corpus, returns pydantic-validated
-signal classifications via structured_reply (4-layer defense).
-Mock engine inputs; real identity/attention signals are v0.3+.
+v0.3 re-grounding: consumes the learner's live trace digest (idle gaps,
+command cadence), the DefenseStore integrity signals (long pauses from the
+oral defense), and the variant seed cross-check — NOT v0.2 corpus
+scenarios. The proctor COACHES: it classifies signals supportively and
+recommends one intervention; it never punishes and never accuses.
+
+Integrity inputs (computed server-side, passed in by the API layer):
+- trace digest: idle_gap_count/total, command_categories histogram,
+  error/fix cycles, huge-burst indicators (edit_count vs test runs)
+- defense signals: long_pauses list from the finished defense (A-109)
+- variant: seed + params when the task is variant-derived (off-template
+  work is a cross-check input, not an accusation)
 """
 
 from pydantic import BaseModel, Field
 
 from ..corpus.learner_context import LearnerContext, get_learner_context
-from ..corpus.telemetry import ProctorScenario, summarize_proctor_scenario
+from ..grading.features import TraceDigest
 from ..prompts.proctor import SYSTEM_PROMPT, render_context
 from .base import BaseAgent
 
 
 class IntegritySignal(BaseModel):
-    signal_type: str  # e.g. "context_switch" | "idle_gap" | "large_paste"
+    signal_type: str  # "idle_gap" | "long_pause" | "burst_edit" | "off_template"
     severity: str  # "low" | "medium" | "high"
     note: str
 
 
 class ProctorAssessment(BaseModel):
-    scenario_id: str
     signals: list[IntegritySignal] = Field(min_length=0)
     intervention: str  # ONE supportive coaching recommendation
     summary: str
 
 
 PROCTOR_ASSESSMENT_SCHEMA_HINT = (
-    '{"scenario_id": "<id>", "signals": [{"signal_type": "<type>", '
+    '{"signals": [{"signal_type": "<type>", '
     '"severity": "low"|"medium"|"high", "note": "<one sentence>"}], '
     '"intervention": "<one supportive recommendation>", '
     '"summary": "<one sentence>"}'
@@ -43,13 +51,27 @@ class ProctorAgent(BaseAgent):
 
     async def assess(
         self,
-        scenario: ProctorScenario,
+        digest: TraceDigest | None,
+        defense_signals: dict | None = None,
+        variant_context: dict | None = None,
         learner_context: LearnerContext | None = None,
     ) -> ProctorAssessment:
-        timeline = summarize_proctor_scenario(scenario)
+        """Classify REAL integrity inputs into supportive signals + coaching."""
+        parts: list[str] = []
+        if digest is not None:
+            parts.append(f"Build-session digest:\n{digest.model_dump_json()}")
+        else:
+            parts.append("No build telemetry recorded for this task yet.")
+        if defense_signals:
+            parts.append(f"Oral-defense integrity signals:\n{defense_signals}")
+        if variant_context:
+            parts.append(f"Variant audit context (seed + params):\n{variant_context}")
         assessment: ProctorAssessment = await self.structured_reply(
             history=None,
-            user_input=timeline,
+            user_input=(
+                "Assess this learner's integrity signals supportively.\n\n"
+                + "\n\n".join(parts)
+            ),
             learner_context=learner_context,
             schema=ProctorAssessment,
             schema_hint=PROCTOR_ASSESSMENT_SCHEMA_HINT,

apps/ai-service/ai_service/agents/registry.py

@@ -14,13 +14,14 @@ AgentFactory = Callable[[LLMProvider, Settings], BaseAgent]
 
 
 def register_builtin_agents(registry: "AgentRegistry") -> None:
-    """Central registration of all six shipped tutor agents (G-4: one pattern).
+    """Central registration of all seven shipped agents (G-4: one pattern).
 
-    coach, tutor, lab, assessor, proctor, mentor. New agents register here
-    in their landing phase.
+    coach, tutor, lab, assessor, proctor, mentor, examiner (Phase 5).
+    New agents register here in their landing phase.
     """
     from .assessor import AssessorAgent
     from .coach import CoachAgent
+    from .examiner import ExaminerAgent
     from .lab import LabAgent
     from .mentor import MentorAgent
     from .proctor import ProctorAgent
@@ -38,6 +39,9 @@ def register_builtin_agents(registry: "AgentRegistry") -> None:
     registry.register(
         "mentor", lambda provider, settings: MentorAgent(provider, settings)
     )
+    registry.register(
+        "examiner", lambda provider, settings: ExaminerAgent(provider, settings)
+    )
 
 
 class UnknownAgentError(KeyError):

apps/ai-service/ai_service/agents/session.py

@@ -28,15 +28,19 @@ class AgentSession:
 
 
 class SessionStore(Protocol):
-    def get(self, session_id: str) -> AgentSession | None: ...
-    def create(
+    # P5 (D-058): the protocol was previously declared sync while the
+    # shipped implementation is async — every API call site awaited a
+    # non-awaitable per the old signature. The protocol now tells the
+    # truth: all five methods are async (InMemorySessionStore's shape).
+    async def get(self, session_id: str) -> AgentSession | None: ...
+    async def create(
         self, session_id: str, agent: str, learner_id: str = "seed-learner-1"
     ) -> AgentSession: ...
-    def append(self, session_id: str, message: Message) -> None: ...
-    def history_window(
+    async def append(self, session_id: str, message: Message) -> None: ...
+    async def history_window(
         self, session_id: str, max_messages: int = DEFAULT_WINDOW
     ) -> list[Message]: ...
-    def delete(self, session_id: str) -> None: ...
+    async def delete(self, session_id: str) -> None: ...
 
 
 class InMemorySessionStore:

apps/ai-service/ai_service/api/__init__.py

@@ -5,10 +5,13 @@ Boundary rule: api/ composes agents/ and llm/; they never import api/.
 
 from .assessment import router as assessment_router
 from .chat import router as chat_router
+from .defense import router as defense_router
 from .lab import router as lab_router
 from .mentor import router as mentor_router
 from .proctor import router as proctor_router
 from .sandboxes import router as sandboxes_router
+from .telemetry import router as telemetry_router
+from .variants import router as variants_router
 
 __all__ = [
     "assessment_router",
@@ -17,4 +20,7 @@ __all__ = [
     "mentor_router",
     "proctor_router",
     "sandboxes_router",
+    "telemetry_router",
+    "variants_router",
+    "defense_router",
 ]

apps/ai-service/ai_service/api/assessment.py

@@ -1,47 +1,193 @@
-"""POST /v1/assessment/evaluate — structured rubric scores (REQ-2-008).
+"""/v1/assessment — rubric evaluation + trace grading endpoints (REQ-2-008, REQ-3-004).
 
-JSON response (not SSE): a pydantic-validated RubricScore. Unknown
-artifact → 404. The Assessor's structured output IS the payload.
+Two endpoint families share this router:
+
+    POST /v1/assessment/evaluate                  (v0.2, REQ-2-008) — corpus
+                                                 artifact evaluation through
+                                                 the Assessor agent.
+    POST /v1/assessment/grade                     (v0.3, REQ-3-004) — grade a
+                                                 REAL process trace through
+                                                 the GradingEngine.
+    GET  /v1/assessment/grade/{learner_id}/{task_id} — stored latest grade.
+
+Grading status-code mapping (the engine's outcomes are CONTRACT, not errors):
+
+    GradeRecord(verdict=GRADED)                    → 200 — rubric scores +
+                                                    verdict (in scores.verdict)
+                                                    + digest summary.
+    GradeRecord(UNGRADABLE_TRACE_INCOMPLETE)       → 200 — the ungradable
+                                                    record IS a valid result:
+                                                    the trace cannot be graded,
+                                                    and the gate surfaces WHY
+                                                    (scores.missing_seqs +
+                                                    scores.integrity_flag).
+                                                    Persisted like any grade.
+    GradeRecord(UNGRADABLE_EMPTY_TRACE)           → 200 — no events stored for
+                                                    the pair. This covers BOTH
+                                                    a known pair whose trace
+                                                    ended up empty AND a task
+                                                    that never had a trace at
+                                                    all: the engine cannot
+                                                    distinguish them (zero
+                                                    stored events is zero
+                                                    events), and grading an
+                                                    absent trace genuinely has
+                                                    the empty-trace outcome —
+                                                    a 404 here would erase the
+                                                    durable gate record the
+                                                    engine persists for the
+                                                    pair. PLAN's 404 applies to
+                                                    GET of a never-graded pair.
+    StructuredOutputError                          → 502 — the trace was
+                                                    gradable but the provider
+                                                    failed the D-020 budget;
+                                                    provider failure (bad
+                                                    gateway to the model), same
+                                                    mapping as evaluate.
+    GET of an unknown (never-graded) pair          → 404.
+
+DI (D-027/D-032 house pattern): engine + store arrive via deps.get_grading_engine
+/ get_grade_store from app.state; this module owns all FastAPI wiring — the
+engine knows nothing of HTTP. UNGRADABLE_* bodies are rendered by the same
+GradeResponse model as GRADED ones (a gate record's `scores` holds the gate
+detail instead of rubric scores), so consumers read ONE shape.
 """
 
+from datetime import datetime
+from typing import Any, cast
+
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 
-from ..agents.assessor import RubricScore
+from ..agents.assessor import AssessorAgent
 from ..agents.registry import AgentRegistry
+from ..agents.structured import StructuredOutputError
 from ..config import Settings
-from ..corpus.artifacts import get_artifact_bundle, get_transcript_for_artifact
 from ..corpus.learner_context import get_learner_context
-from .deps import get_agent_registry, get_provider, get_settings
+from ..grading.engine import GradingEngine
+from ..grading.store import GradeRecord, GradeStore
+from .deps import (
+    get_agent_registry,
+    get_grade_store,
+    get_grading_engine,
+    get_provider,
+    get_settings,
+)
 
 router = APIRouter(prefix="/v1")
 
 
-class AssessmentRequest(BaseModel):
-    artifact_id: str = Field(min_length=1)
-    learner_id: str | None = None
+# --- v0.2 artifact evaluation (REQ-2-008) --------------------------------------
 
 
-@router.post("/assessment/evaluate", response_model=RubricScore)
+class EvaluateRequest(BaseModel):
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
+
+
+@router.post("/assessment/evaluate")
 async def assessment_evaluate(
-    body: AssessmentRequest,
+    body: EvaluateRequest,
     registry: AgentRegistry = Depends(get_agent_registry),
     settings: Settings = Depends(get_settings),
     provider=Depends(get_provider),
-) -> RubricScore:
-    bundle = get_artifact_bundle(body.artifact_id)
-    if bundle is None:
+    grade_store=Depends(get_grade_store),
+) -> dict:
+    """Assessor coaching rendered FROM the learner's stored grade (REQ-3-007).
+
+    The grading engine computes the scores (POST /assessment/grade); this
+    endpoint explains them. No stored grade yet -> 404 (grade first).
+    """
+    grade = grade_store.get(body.learner_id, body.task_id)
+    if grade is None:
         raise HTTPException(
-            status_code=404, detail=f"unknown artifact {body.artifact_id!r}"
+            status_code=404,
+            detail=f"no stored grade for {body.learner_id}/{body.task_id} - grade first",
         )
-    artifact, rubric = bundle
-    transcript = get_transcript_for_artifact(artifact.artifact_id)
-    agent = registry.get(provider, settings, "assessor")
+    # P5: registry.get returns BaseAgent; "assessor" is registered as
+    # AssessorAgent (register_builtin_agents) — the cast states that mapping.
+    agent = cast(AssessorAgent, registry.get(provider, settings, "assessor"))
     learner_context = get_learner_context(body.learner_id)
     try:
-        return await agent.evaluate(artifact, rubric, transcript, learner_context)
+        coaching = await agent.coach_grade(grade, learner_context)
     except Exception as exc:
         raise HTTPException(
             status_code=502,
             detail=f"assessment evaluation failed: {exc}",
         ) from exc
+    return {
+        "learner_id": grade.learner_id,
+        "task_id": grade.task_id,
+        "grade_verdict": grade.verdict,
+        "grade_scores": grade.scores,
+        "coaching": coaching.model_dump(),
+    }
+
+
+# --- # --- v0.3 trace grading (REQ-3-004) ---------------------------------------------
+
+
+class GradeRequest(BaseModel):
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
+
+
+class GradeResponse(BaseModel):
+    """GradeRecord over HTTP — one shape for GRADED and UNGRADABLE_* alike.
+
+    `scores` holds the validated rubric (criteria 0-4, strengths, gaps,
+    rubric verdict) for a GRADED record, or the gate detail
+    ({integrity_flag, missing_seqs}) for an UNGRADABLE_* record — never both.
+    `digest` is the compact trace summary that fed the rubric prompt (empty
+    for gate records: nothing was graded).
+    """
+
+    learner_id: str
+    task_id: str
+    variant_seed: str | None
+    digest: dict[str, Any]
+    scores: dict[str, Any]
+    verdict: str
+    model: str
+    created_at: datetime
+
+
+def _grade_response(record: GradeRecord) -> GradeResponse:
+    return GradeResponse.model_validate(record, from_attributes=True)
+
+
+@router.post("/assessment/grade", response_model=GradeResponse)
+async def assessment_grade(
+    body: GradeRequest,
+    engine: GradingEngine = Depends(get_grading_engine),
+) -> GradeResponse:
+    """Run the grading engine for one (learner_id, task_id) trace.
+
+    Gate outcomes (UNGRADABLE_*) are 200s — they are first-class results the
+    engine persists, not failures. Only a provider that exhausts the D-020
+    budget turns into a 502; nothing is persisted on that path.
+    """
+    try:
+        record = await engine.grade(body.learner_id, body.task_id)
+    except StructuredOutputError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"grading failed: {exc}",
+        ) from exc
+    return _grade_response(record)
+
+
+@router.get("/assessment/grade/{learner_id}/{task_id}", response_model=GradeResponse)
+async def assessment_get_grade(
+    learner_id: str,
+    task_id: str,
+    store: GradeStore = Depends(get_grade_store),
+) -> GradeResponse:
+    """Latest stored grade for the pair; 404 when none was ever stored."""
+    record = store.get(learner_id, task_id)
+    if record is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"no stored grade for {learner_id!r}/{task_id!r}",
+        )
+    return _grade_response(record)

apps/ai-service/ai_service/api/defense.py

@@ -0,0 +1,401 @@
+"""Oral-defense endpoints (Task 5-3-01, REQ-3-006, A-109).
+
+Full defense loop over HTTP with mock-first voice (D-030) and the seventh
+Examiner agent (SSE question streaming happens through the chat pipeline;
+these endpoints are the session orchestration + transcript persistence):
+
+    POST /v1/defense/start          {learner_id, task_id}
+    POST /v1/defense/{id}/answer    {text} | multipart audio (STT)
+    GET  /v1/defense/{id}/audio/{turn_id}      TTS bytes (streaming)
+    POST /v1/defense/{id}/finish    verdict + integrity signals
+    GET  /v1/defense/{id}           transcript + signals
+
+Integrity signals (A-109) are computed server-side from turn metadata:
+long pauses = learner turns whose latency_ms exceeds PAUSE_THRESHOLD_MS.
+The defense does NOT gate on trace completeness (the grader does, G-4);
+an incomplete trace is surfaced as `trace_complete: false` so the UI can
+disclose it before the learner defends.
+"""
+
+from __future__ import annotations
+
+import itertools
+import secrets
+import time
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from ..agents.examiner import ExaminerAgent
+from ..grading.features import TraceDigest, compute_digest
+from ..llm.types import Message
+from ..voice.base import VoiceDescriptor
+from ..voice.browser import BROWSER_FALLBACK_DESCRIPTOR
+from ..voice.defense_store import DefenseRecord, DefenseStore, DefenseTurn
+from .deps import (
+    get_examiner,
+    get_settings,
+    get_trace_store,
+    get_variant_store,
+    get_voice_provider,
+    get_voice_store,
+)
+from .identity import require_verified_age
+
+router = APIRouter(prefix="/v1/defense", tags=["defense"])
+
+#: A-109: learner turns slower than this are flagged as long pauses (ms).
+PAUSE_THRESHOLD_MS = 15_000
+
+_ROLE_EXAMINER = "examiner"
+_ROLE_LEARNER = "learner"
+
+# v0.4.7 (P1, final-review flag): the old id mint `dfn-{ms:x}` collided on
+# same-millisecond starts — the insert-only store's PK then 500'd the second
+# start permanently (the identity-resubmit P0-C1 class). Nonce + counter
+# keeps ids unique within and across process restarts (the identity/mock.py
+# pattern); ids stay opaque handles, never derived from PII.
+_DEFENSE_NONCE = secrets.randbits(32)
+_DEFENSE_COUNTER = itertools.count(1)
+
+
+def mint_defense_id(learner_id: str) -> str:
+    seq = next(_DEFENSE_COUNTER)
+    return f"dfn-{_DEFENSE_NONCE:08x}{seq:08x}-{learner_id[:8]}"
+
+
+class StartRequest(BaseModel):
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
+
+
+class StartResponse(BaseModel):
+    defense_id: str
+    voice_descriptor: dict
+    trace_complete: bool
+    first_question: str
+
+
+class AnswerResponse(BaseModel):
+    question: str
+    turn_latency: dict[str, int | None]
+
+
+class FinishResponse(BaseModel):
+    verdict: dict
+    integrity_signals: dict
+
+
+async def _digest_for_task(
+    trace_store, learner_id: str, task_id: str
+) -> tuple[TraceDigest | None, bool]:
+    """Digest of the learner's trace for this task + completeness flag."""
+    if not trace_store.list_tasks(learner_id) or task_id not in trace_store.list_tasks(
+        learner_id
+    ):
+        return None, True  # no trace at all is "complete" for defense purposes
+    trace = trace_store.get_trace(learner_id, task_id)
+    gaps = trace_store.gaps(learner_id, task_id)
+    return (compute_digest(trace) if trace else None), (len(gaps) == 0)
+
+
+def _voice_descriptor(settings) -> VoiceDescriptor:
+    """The capability descriptor for the configured voice mode (D-030).
+
+    Must-Have #6: browser mode returns BROWSER_FALLBACK_DESCRIPTOR so the
+    web client selects native SpeechRecognition/speechSynthesis; mock mode
+    returns the mock descriptor. (A real server provider returns
+    mode="server" — the protocol seam.)
+    """
+    if (settings.voice_provider or "mock").strip().lower() == "browser":
+        return BROWSER_FALLBACK_DESCRIPTOR
+    return VoiceDescriptor(
+        mode="mock", sr_available=True, tts_available=True, hint=""
+    )
+
+
+@router.post("/start", response_model=StartResponse)
+async def start_defense(
+    body: StartRequest,
+    request: Request,
+    examiner: ExaminerAgent = Depends(get_examiner),
+    voice_store: DefenseStore = Depends(get_voice_store),
+    voice_provider=Depends(get_voice_provider),
+    trace_store=Depends(get_trace_store),
+    variant_store=Depends(get_variant_store),
+    settings=Depends(get_settings),
+) -> StartResponse:
+    # v0.5 identity gate (D-043): allowlist first (G-5), then the school
+    # 16+ verified verdict, before any defense machinery runs.
+    if body.learner_id not in settings.learner_allowlist:
+        raise HTTPException(
+            status_code=403,
+            detail=(
+                f"learner_id {body.learner_id!r} is not on the sandbox "
+                "allowlist (G-5)"
+            ),
+        )
+    await require_verified_age(
+        16, body.learner_id, request.app.state.identity_store
+    )
+    record = voice_store.start(
+        DefenseRecord(
+            id=mint_defense_id(body.learner_id),
+            learner_id=body.learner_id,
+            task_id=body.task_id,
+            status="in_progress",
+            created_at=datetime.now(UTC),
+        )
+    )
+    digest, trace_complete = await _digest_for_task(trace_store, body.learner_id, body.task_id)
+    variant = variant_store.get_by_task(body.task_id)
+    statement = variant.statement if variant is not None else None
+
+    started = time.perf_counter()
+    question = await examiner.next_question(
+        history=[], trace_digest=digest, variant_statement=statement
+    )
+    llm_ms = int((time.perf_counter() - started) * 1000)
+    voice_store.append_turn(
+        record.id,
+        DefenseTurn(
+            defense_id=record.id,
+            seq=0,
+            role=_ROLE_EXAMINER,
+            text=question,
+            ts=datetime.now(UTC),
+            latency_ms=llm_ms,
+            created_at=datetime.now(UTC),
+        ),
+    )
+    descriptor = getattr(voice_provider, "descriptor", None) or _voice_descriptor(
+        settings
+    )
+    return StartResponse(
+        defense_id=record.id,
+        voice_descriptor=descriptor.model_dump(),
+        trace_complete=trace_complete,
+        first_question=question,
+    )
+
+
+@router.post("/{defense_id}/answer", response_model=AnswerResponse)
+async def answer_defense(
+    defense_id: str,
+    text: str | None = Form(default=None),
+    audio: UploadFile | None = File(default=None),
+    voice_store: DefenseStore = Depends(get_voice_store),
+    voice_provider=Depends(get_voice_provider),
+    examiner: ExaminerAgent = Depends(get_examiner),
+    trace_store=Depends(get_trace_store),
+    variant_store=Depends(get_variant_store),
+    settings=Depends(get_settings),
+) -> AnswerResponse:
+    record = voice_store.get(defense_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
+    if record.status == "finished":
+        # The store owns the finished transition but does NOT police turn
+        # sequencing (defense_store.py: "turns after finalize are a sequencing
+        # bug for the endpoints to prevent") — this is the endpoint half of
+        # that contract: a sealed transcript is append-only-no-more.
+        raise HTTPException(
+            status_code=409, detail="defense is finished; start a new defense"
+        )
+    if text is None and audio is None:
+        raise HTTPException(status_code=422, detail="provide {text} or audio")
+
+    # STT (typed fallback bypasses the voice provider entirely).
+    stt_ms: int | None = None
+    if audio is not None:
+        stt_started = time.perf_counter()
+        raw = await audio.read()
+        # P3 (Task 3-2-01): the upload is fully consumed into memory —
+        # no streaming path exists (G-107), so close the spooled file
+        # HERE, before any guard below can raise (422 empty / 413
+        # oversize / 502 provider all operate on `raw` only). FastAPI's
+        # request-end file stack would also close it — close() is
+        # idempotent on the spooled file — but the route must not rely
+        # on GC-timing cleanup.
+        await audio.close()
+        if not raw:
+            # Empty upload is a client error (422), not a provider crash
+            # (500): validate before the provider call so every provider
+            # sees the same contract.
+            raise HTTPException(status_code=422, detail="audio upload is empty")
+        max_bytes = settings.voice_max_audio_mb * 1024 * 1024
+        if len(raw) > max_bytes:
+            # D-041/G-12: bounded audio BEFORE the provider call — the
+            # client renders this as an honest re-record prompt.
+            raise HTTPException(
+                status_code=413,
+                detail=(
+                    f"audio exceeds {settings.voice_max_audio_mb}MB "
+                    "— re-record a shorter answer"
+                ),
+            )
+        # D-041: strip codec params — MediaRecorder sends
+        # 'audio/webm;codecs=opus'; the bare extension is the provider
+        # contract ('webm'), else real STT endpoints reject the multipart.
+        fmt = (audio.content_type or "audio/wav").split("/")[-1].split(";")[0].strip()
+        try:
+            segment = await voice_provider.transcribe(raw, fmt)
+        except RuntimeError as exc:
+            # Provider failure is the 502 house pattern (assessment.py /
+            # proctor.py), not a 500: a real endpoint outage (or the
+            # default mock's unscripted queue — final-review cross-phase
+            # P0) must surface as an honest upstream error. Both providers
+            # raise RuntimeError with sanitized text (mock: MockVoiceFailure;
+            # openai-audio: key-redacted _sanitize).
+            raise HTTPException(
+                status_code=502, detail=f"voice transcription failed: {exc}"
+            ) from exc
+        stt_ms = int((time.perf_counter() - stt_started) * 1000)
+        text = segment.text
+
+    turns = record.turns if hasattr(record, "turns") else []
+    history = [
+        Message(role="assistant" if t.role == _ROLE_EXAMINER else "user", content=t.text)
+        for t in turns
+    ]
+    next_seq = len(turns)
+
+    voice_store.append_turn(
+        defense_id,
+        DefenseTurn(
+            defense_id=defense_id,
+            seq=next_seq,
+            role=_ROLE_LEARNER,
+            text=text or "",
+            ts=datetime.now(UTC),
+            latency_ms=stt_ms,
+            created_at=datetime.now(UTC),
+        ),
+    )
+
+    digest, _ = await _digest_for_task(trace_store, record.learner_id, record.task_id)
+    variant = variant_store.get_by_task(record.task_id)
+
+    llm_started = time.perf_counter()
+    question = await examiner.next_question(
+        history=history + [Message(role="user", content=text or "")],
+        trace_digest=digest,
+        variant_statement=variant.statement if variant is not None else None,
+    )
+    llm_ms = int((time.perf_counter() - llm_started) * 1000)
+
+    voice_store.append_turn(
+        defense_id,
+        DefenseTurn(
+            defense_id=defense_id,
+            seq=next_seq + 1,
+            role=_ROLE_EXAMINER,
+            text=question,
+            ts=datetime.now(UTC),
+            latency_ms=llm_ms,
+            created_at=datetime.now(UTC),
+        ),
+    )
+    return AnswerResponse(
+        question=question,
+        turn_latency={"stt_ms": stt_ms, "llm_ms": llm_ms, "tts_ms": None},
+    )
+
+
+@router.get("/{defense_id}/audio/{turn_id}")
+async def defense_audio(
+    defense_id: str,
+    turn_id: int,
+    voice_store: DefenseStore = Depends(get_voice_store),
+    voice_provider=Depends(get_voice_provider),
+    settings=Depends(get_settings),
+):
+    record = voice_store.get(defense_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
+    turn = next((t for t in record.turns if t.seq == turn_id), None)
+    if turn is None or turn.role != _ROLE_EXAMINER:
+        raise HTTPException(status_code=404, detail=f"no examiner turn {turn_id!r}")
+
+    async def stream():
+        async for chunk in voice_provider.synthesize(turn.text):
+            yield chunk
+
+    # G-16/D-041: the TTS format is a settings enum; the media_type maps
+    # from it (was hardcoded audio/wav — wrong for every real format).
+    return StreamingResponse(
+        stream(), media_type=f"audio/{settings.voice_tts_format}"
+    )
+
+
+@router.post("/{defense_id}/finish", response_model=FinishResponse)
+async def finish_defense(
+    defense_id: str,
+    voice_store: DefenseStore = Depends(get_voice_store),
+    examiner: ExaminerAgent = Depends(get_examiner),
+    trace_store=Depends(get_trace_store),
+    variant_store=Depends(get_variant_store),
+) -> FinishResponse:
+    record = voice_store.get(defense_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
+
+    turns = record.turns if hasattr(record, "turns") else []
+    history = [
+        Message(role="assistant" if t.role == _ROLE_EXAMINER else "user", content=t.text)
+        for t in turns
+    ]
+    digest, _ = await _digest_for_task(trace_store, record.learner_id, record.task_id)
+    variant = variant_store.get_by_task(record.task_id)
+    verdict = await examiner.final_verdict(
+        history=history,
+        trace_digest=digest,
+        variant_statement=variant.statement if variant is not None else None,
+    )
+
+    signals: dict = {
+        "long_pauses": [
+            {"turn": t.seq, "latency_ms": t.latency_ms}
+            for t in turns
+            if t.role == _ROLE_LEARNER and (t.latency_ms or 0) > PAUSE_THRESHOLD_MS
+        ],
+        "pause_threshold_ms": PAUSE_THRESHOLD_MS,
+        # Must-Have #1: "verdict + transcript persisted" — the verdict is
+        # stored INSIDE integrity_signals so GET /{id} after finish can
+        # re-serve it (the finish response alone would lose it). Signals
+        # are a JSON object dict (DefenseStore.finalize contract), so the
+        # verdict nests under the "verdict" key alongside the A-109
+        # markers the Proctor/Mentor feeds read.
+        "verdict": verdict.model_dump(),
+    }
+    voice_store.finalize(defense_id, signals)
+    return FinishResponse(verdict=verdict.model_dump(), integrity_signals=signals)
+
+
+@router.get("/{defense_id}")
+async def get_defense(
+    defense_id: str,
+    voice_store: DefenseStore = Depends(get_voice_store),
+):
+    record = voice_store.get(defense_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
+    return {
+        "defense_id": record.id,
+        "learner_id": record.learner_id,
+        "task_id": record.task_id,
+        "status": record.status,
+        "turns": [
+            {
+                "seq": t.seq,
+                "role": t.role,
+                "text": t.text,
+                "ts": t.ts,
+                "latency_ms": t.latency_ms,
+            }
+            for t in record.turns
+        ],
+        "integrity_signals": record.integrity_signals or {},
+    }

apps/ai-service/ai_service/api/deps.py

@@ -2,12 +2,23 @@
 
 from fastapi import Request
 
+from ..agents.examiner import ExaminerAgent
 from ..agents.registry import AgentRegistry
 from ..agents.session import SessionStore
 from ..config import Settings
+from ..grading.engine import GradingEngine
+from ..grading.store import GradeStore
 from ..llm.base import LLMProvider
+from ..marketplace.embedding.base import EmbeddingProvider
+from ..marketplace.store import MarketplaceStore
 from ..sandbox.manager import SandboxManager
 from ..sandbox.workdir import SandboxDir
+from ..telemetry.ingest import TraceIntegrityMap
+from ..telemetry.store import TraceStore
+from ..variants.generator import VariantGenerator
+from ..variants.store import VariantStore
+from ..voice.base import VoiceProvider
+from ..voice.defense_store import DefenseStore
 
 
 def get_settings(request: Request) -> Settings:
@@ -33,3 +44,50 @@ def get_sandbox_manager(request: Request) -> SandboxManager:
 def get_sandbox_test_layout(request: Request) -> SandboxDir | None:
     """Optional test seam (app.state.sandbox_test_layout); always None in prod."""
     return getattr(request.app.state, "sandbox_test_layout", None)
+
+
+def get_trace_store(request: Request) -> TraceStore:
+    return request.app.state.trace_store
+
+
+def get_trace_integrity(request: Request) -> TraceIntegrityMap:
+    return request.app.state.trace_integrity
+
+
+def get_grade_store(request: Request) -> GradeStore:
+    return request.app.state.grade_store
+
+
+def get_grading_engine(request: Request) -> GradingEngine:
+    return request.app.state.grading_engine
+
+
+def get_variant_generator(request: Request) -> VariantGenerator:
+    return request.app.state.variant_generator
+
+
+def get_variant_store(request: Request) -> VariantStore:
+    return request.app.state.variant_store
+
+def get_voice_store(request: Request) -> DefenseStore:
+    return request.app.state.defense_store
+
+
+def get_voice_provider(request: Request) -> VoiceProvider:
+    return request.app.state.voice_provider
+
+
+def get_examiner(request: Request) -> ExaminerAgent:
+    return request.app.state.examiner_agent
+
+
+def get_marketplace_store(request: Request) -> MarketplaceStore:
+    """v0.6 marketplace (D-049): routes NEVER import the store directly —
+    the api/ layer composes it via app.state DI (territory rule)."""
+    return request.app.state.marketplace_store
+
+
+def get_embedding_provider(request: Request) -> EmbeddingProvider:
+    """v0.6 P3 (D-051): the embedding port via app.state DI — the
+    search route + publish hooks compose it, never import it."""
+    return request.app.state.embedding_provider

apps/ai-service/ai_service/api/identity.py

@@ -0,0 +1,265 @@
+"""Identity API + age-gate dependencies (REQ-5-003/004, D-042/43).
+
+Flow (all under mock provider by default; A-304 mock markers ride every
+response so downstream surfaces never treat mock-verified as real):
+    POST /v1/identity/submit          submission → pending (G-13 caps first)
+    GET  /v1/identity/status/{lid}    latest record + mock marker
+    POST /v1/identity/verify/{sid}    poll provider → terminal transition
+
+Gate dependencies (D-043 binding composition order, mounted by the gated
+routes — variants/sandbox-create/defense-start for school 16+; the
+marketplace 18+ apply route in api/marketplace.py):
+    allowlist (403, G-5 pilot guard) → identity verdict (403 + verify-CTA)
+    → rate caps (429, owned by the calling routes)
+
+PII (A-305): raw DOB enters via the submission, is used to derive the
+band, and is NEVER stored or logged (caplog sentinel test pins it).
+
+v0.6 (D-048/D-058): the G-18 marketplace stub MOVED to api/marketplace.py
+and became the real apply route; identity keeps ONLY the gate exports.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field, field_validator
+
+from ..config import Settings
+from ..identity.base import IdentityProvider, IdentitySubmission
+from ..identity.store import IdentityRecord, IdentityStore
+from .deps import get_settings
+
+router = APIRouter(prefix="/v1/identity", tags=["identity"])
+
+
+# -- DI ------------------------------------------------------------------------
+
+
+def get_identity_store(request: Request) -> IdentityStore:
+    return request.app.state.identity_store
+
+
+def get_identity_provider(request: Request) -> IdentityProvider:
+    return request.app.state.identity_provider
+
+
+# -- models ----------------------------------------------------------------------
+
+
+class SubmitBody(BaseModel):
+    learner_id: str = Field(min_length=1)
+    #: ISO date. Validated AT THE BOUNDARY (D1 verifier fix): a malformed
+    #: value would otherwise blow up as a 500 inside derive_age_band on the
+    #: verify path — echoing the raw DOB into the traceback (A-305) and
+    #: leaving a poisoned pending record that G-13 turns into a permanent
+    #: learner lockout.
+    date_of_birth: str = Field(description="ISO date; never stored or logged")
+    document_refs: list[str] = Field(default_factory=list)
+
+    @field_validator("date_of_birth")
+    @classmethod
+    def _validate_dob(cls, value: str) -> str:
+        try:
+            datetime.fromisoformat(value)
+        except ValueError as exc:
+            # 422 with the input scrubbed (A-305/D1 — the app-level
+            # RequestValidationError handler redacts PII field inputs).
+            raise ValueError("date_of_birth must be an ISO date (YYYY-MM-DD)") from exc
+        return value
+
+
+class SubmitResponse(BaseModel):
+    submission_id: str
+    status: str
+    #: A-304: honesty marker — a mock verdict is NEVER production-verified.
+    mock: bool = True
+    detail: str = ""
+
+
+class StatusResponse(BaseModel):
+    learner_id: str
+    status: str
+    age_band: str | None
+    mock: bool
+    verified_at: str | None
+
+
+class VerifyResponse(SubmitResponse):
+    age_band: str | None
+
+
+# -- G-13 submit caps ---------------------------------------------------------------
+
+
+class _SubmitRateLimiter:
+    """Per-learner submit rate cap (in-memory, process-local — the G-5
+    creates-per-min pattern from the sandboxes route)."""
+
+    def __init__(self) -> None:
+        self._window: dict[str, list[float]] = {}
+
+    def check(self, learner_id: str, per_min: int) -> None:
+        now = time.monotonic()
+        window = self._window.setdefault(learner_id, [])
+        window[:] = [t for t in window if now - t < 60.0]
+        if len(window) >= per_min:
+            raise HTTPException(
+                status_code=429,
+                detail="identity submit rate exceeded — wait a minute",
+            )
+        window.append(now)
+
+
+_rate_limiter = _SubmitRateLimiter()
+
+
+# -- verification flow ------------------------------------------------------------
+
+
+@router.post("/submit", response_model=SubmitResponse)
+async def submit_identity(
+    body: SubmitBody,
+    store: IdentityStore = Depends(get_identity_store),
+    provider: IdentityProvider = Depends(get_identity_provider),
+    settings: Settings = Depends(get_settings),
+) -> SubmitResponse:
+    # G-13: one active pending submission per learner — resubmit while
+    # pending echoes the pending state (409), not a second submission.
+    if store.count_pending_for_learner(body.learner_id) > 0:
+        latest = store.latest_for_learner(body.learner_id)
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "reason": "submission_pending",
+                "submission_id": latest.id if latest else None,
+                "status": "pending",
+            },
+        )
+    _rate_limiter.check(body.learner_id, settings.identity_submits_per_min)
+
+    submission = IdentitySubmission(
+        learner_id=body.learner_id,
+        date_of_birth=body.date_of_birth,
+        document_refs=body.document_refs,
+    )
+    submission_id = await provider.submit(submission)
+
+    record = store.insert(
+        IdentityRecord(
+            id=submission_id,
+            learner_id=body.learner_id,
+            status="pending",
+            provider="mock" if settings.identity_provider == "mock" else settings.identity_provider,
+            document_refs=body.document_refs,  # A-305: opaque handles, never contents
+            submitted_at=datetime.now(UTC),
+        )
+    )
+    return SubmitResponse(
+        submission_id=record.id, status=record.status, mock=record.mock
+    )
+
+
+@router.get("/status/{learner_id}", response_model=StatusResponse)
+async def identity_status(
+    learner_id: str,
+    store: IdentityStore = Depends(get_identity_store),
+) -> StatusResponse:
+    record = store.latest_for_learner(learner_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="no identity record")
+    return StatusResponse(
+        learner_id=learner_id,
+        status=record.status,
+        age_band=record.age_band,
+        mock=record.mock,
+        verified_at=record.verified_at.isoformat() if record.verified_at else None,
+    )
+
+
+@router.post("/verify/{submission_id}", response_model=VerifyResponse)
+async def verify_identity(
+    submission_id: str,
+    store: IdentityStore = Depends(get_identity_store),
+    provider: IdentityProvider = Depends(get_identity_provider),
+) -> VerifyResponse:
+    record = store.get(submission_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="no such submission")
+    if record.status != "pending":
+        raise HTTPException(
+            status_code=409,
+            detail=f"submission already {record.status}",
+        )
+
+    verdict = await provider.poll(submission_id)
+    # A-305: derive the band from the provider's verdict; the raw DOB never
+    # entered the store and is not logged here.
+    updated = store.mark_verified(
+        submission_id, verdict.model_dump(), verdict.age_band
+    )
+    assert updated is not None  # record existed a moment ago
+    return VerifyResponse(
+        submission_id=updated.id,
+        status=updated.status,
+        age_band=updated.age_band,
+        mock=updated.mock,
+        detail=verdict.detail,
+    )
+
+
+# -- age-gate dependencies (D-043 composition) -------------------------------------
+
+
+def _verify_cta_payload(
+    reason: str, min_age: int, record: IdentityRecord | None
+) -> dict:
+    """A-306/UX acceptance #2: an actionable 403 — never a bare error."""
+    return {
+        "reason": reason,
+        "min_age": min_age,
+        "current_status": record.status if record else "none",
+        "verify_cta": "/enroll",
+    }
+
+
+async def require_verified_age(
+    min_age: int,
+    learner_id: str,
+    store: IdentityStore,
+) -> IdentityRecord:
+    """The identity half of the D-043 composition (allowlist runs FIRST in
+    the calling routes; this is the second gate; caps come after).
+
+    School 16+ → min_age=16; marketplace 18+ verified → min_age=18.
+    """
+    record = store.latest_for_learner(learner_id)
+    if record is None or record.status != "verified":
+        raise HTTPException(
+            status_code=403,
+            detail=_verify_cta_payload("identity_verification_required", min_age, record),
+        )
+    # D2 (verifier): FAIL CLOSED. Only canonical bands can pass — None,
+    # unknown, or under-16 bands reject (the gate is the security boundary
+    # for the future vendor and direct store writes; it never trusts a
+    # band it does not recognize).
+    if record.age_band not in ("16-17", "18+"):
+        raise HTTPException(
+            status_code=403,
+            detail=_verify_cta_payload("identity_verification_required", min_age, record),
+        )
+    if min_age > 16 and record.age_band != "18+":
+        raise HTTPException(
+            status_code=403,
+            detail=_verify_cta_payload("age_gate_18_plus", 18, record),
+        )
+    return record
+
+
+#: Convenience alias for the marketplace 18+ composition (D-043's
+#: `require_verified_adult` — direct calls use require_verified_age(18, ...)).
+#: v0.6 (D-058): the marketplace surface itself moved to api/marketplace.py;
+#: identity keeps ONLY this gate export (D-048).
+require_verified_adult = require_verified_age

apps/ai-service/ai_service/api/lab.py

@@ -1,27 +1,38 @@
-"""POST /v1/lab/feedback — SSE stream of Lab in-flow feedback (REQ-2-007).
+"""POST /v1/lab/feedback — SSE stream of Lab in-flow feedback (REQ-3-007).
 
-D-016 envelope with agent=lab. Unknown scenario → 404 before streaming.
+v0.3 re-grounding: LIVE trace digest. Request carries {learner_id, task_id};
+the digest is computed from the learner's real TraceStore events (D-028)
+and handed to the Lab agent. No corpus scenarios. Empty/unknown trace is NOT
+an error — Lab gets a "no telemetry yet" timeline and coaches the baseline.
+D-016 envelope with agent=lab.
 """
 
 import json
 from collections.abc import AsyncIterator
+from typing import cast
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel, Field
 from sse_starlette.sse import EventSourceResponse
 
+from ..agents.lab import LabAgent
 from ..agents.registry import AgentRegistry
 from ..config import Settings
 from ..corpus.learner_context import get_learner_context
-from ..corpus.telemetry import get_lab_scenario
-from .deps import get_agent_registry, get_provider, get_settings
+from ..grading.features import compute_digest
+from .deps import (
+    get_agent_registry,
+    get_provider,
+    get_settings,
+    get_trace_store,
+)
 
 router = APIRouter(prefix="/v1")
 
 
 class LabFeedbackRequest(BaseModel):
-    scenario_id: str = Field(min_length=1)
-    learner_id: str | None = None
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
 
 
 @router.post("/lab/feedback")
@@ -30,25 +41,29 @@ async def lab_feedback(
     registry: AgentRegistry = Depends(get_agent_registry),
     settings: Settings = Depends(get_settings),
     provider=Depends(get_provider),
+    trace_store=Depends(get_trace_store),
 ) -> EventSourceResponse:
-    scenario = get_lab_scenario(body.scenario_id)
-    if scenario is None:
-        raise HTTPException(
-            status_code=404, detail=f"unknown scenario {body.scenario_id!r}"
-        )
-    agent = registry.get(provider, settings, "lab")
+    # P5: registry.get returns BaseAgent; "lab" is registered as LabAgent
+    # (register_builtin_agents) — the cast states that mapping.
+    agent = cast(LabAgent, registry.get(provider, settings, "lab"))
     learner_context = get_learner_context(body.learner_id)
+    trace = (
+        trace_store.get_trace(body.learner_id, body.task_id)
+        if body.task_id in trace_store.list_tasks(body.learner_id)
+        else []
+    )
+    digest = compute_digest(trace) if trace else None
 
     async def event_stream() -> AsyncIterator[dict]:
         yield {"event": "message", "data": json.dumps({
             "type": "meta",
             "agent": "lab",
-            "scenario_id": body.scenario_id,
+            "task_id": body.task_id,
             "model": settings.model,
         })}
         first_byte = True
         try:
-            async for token in agent.stream_feedback(scenario, learner_context):
+            async for token in agent.stream_feedback(digest, learner_context):
                 first_byte = False
                 yield {"event": "message", "data": json.dumps({
                     "type": "delta", "content": token

apps/ai-service/ai_service/api/marketplace.py

@@ -0,0 +1,540 @@
+"""/v1/marketplace — public postings API (REQ-6-001, D-048, D-058).
+
+The board's runtime data source (published-only, honest 404s, no
+matchScore anywhere — G-106/G-107) + the REAL apply route: the v0.5
+placeholder that lived in api/identity.py moved here and became this
+module's /apply (D-058) — gate composition UNCHANGED (D-043 binding
+order): G-5 allowlist (403) → require_verified_adult (403 + verify-CTA)
+→ rate caps (429), then posting exists (404) and is published (409),
+then an idempotent insert (A-408: duplicate apply → 200 with the
+EXISTING application).
+
+Routes never import the store directly — deps.py app.state DI only.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel, Field, ValidationError
+
+from ..config import Settings
+from ..identity.store import IdentityStore
+from ..marketplace.base import Employer, Posting
+from ..marketplace.embedding.base import EmbeddingProvider
+from ..marketplace.enrichment import merge_employer
+from ..marketplace.resume import (
+    MAX_RESUME_BYTES,
+    ParsedProfile,
+    ResumeFormatError,
+    extract_resume_text,
+    parse_resume,
+)
+from ..marketplace.search import FacetFilters, rank_postings
+from .deps import get_embedding_provider, get_marketplace_store, get_provider, get_settings
+from .identity import require_verified_age
+
+router = APIRouter(prefix="/v1/marketplace", tags=["marketplace"])
+
+
+def _identity_store(request: Request) -> IdentityStore:
+    return request.app.state.identity_store
+
+
+def _enforce_allowlist(learner_id: str, settings: Settings) -> None:
+    """G-5 pilot guard — allowlist runs FIRST in the composition (D-043)."""
+    if learner_id not in settings.learner_allowlist:
+        raise HTTPException(
+            status_code=403,
+            detail=f"learner_id {learner_id!r} is not on the sandbox allowlist (G-5)",
+        )
+
+
+# In-memory apply-rate window (monotonic timestamps, process-local) — the
+# G-5 creates-per-min pattern from the sandboxes route (module state is
+# acceptable: one process, one box, D-019/D-027 precedent).
+_APPLY_TIMES: dict[str, deque[float]] = {}
+
+#: Applies per rolling 60s window per learner (A-408 anti-spam; the
+#: idempotent duplicate makes honest retries free — only DISTINCT
+#: posting applies consume budget).
+_APPLY_PER_LEARNER_PER_MIN = 5
+
+
+def _check_apply_rate(learner_id: str) -> None:
+    now = time.monotonic()
+    window = _APPLY_TIMES.setdefault(learner_id, deque())
+    while window and now - window[0] > 60.0:
+        window.popleft()
+    if len(window) >= _APPLY_PER_LEARNER_PER_MIN:
+        raise HTTPException(
+            status_code=429,
+            detail="marketplace apply rate exceeded — wait a minute",
+        )
+    window.append(now)
+
+
+# -- response contracts -------------------------------------------------------
+
+
+class PostingResponse(BaseModel):
+    """One posting over HTTP. G-107: `matchScore` is deliberately absent
+    from the schema — scores are computed search-time context (P3),
+    never list/detail payload fields."""
+
+    id: str
+    source: str
+    external_id: str
+    employer_id: str
+    title: str
+    description: str
+    required_competencies: list[str]
+    skills: list[str]
+    seniority: str | None
+    category: str | None
+    location: str
+    remote: bool
+    salary_min: int | None
+    salary_max: int | None
+    status: str
+    tags: dict | None
+    posted_at: str | None
+
+
+class PostingListResponse(BaseModel):
+    """G-103: the page + the honest total_published so the board's paged
+    fetch-all can render "Showing X of Y" with an honest truncation. P2
+    (MH-2c): facets — value counts over stored tags of published-only
+    postings, data-driving the filter sidebar."""
+
+    postings: list[PostingResponse]
+    total_published: int
+    facets: dict
+
+
+class ProvenanceField(BaseModel):
+    """P4-A (D-053/A-304): one merged employer field with its honest
+    provenance — raw | llm | manual (+ the model that wrote llm copy)."""
+
+    value: object
+    source: str
+    model: str | None = None
+
+
+class EmployerResponse(BaseModel):
+    """Raw ingested fields (P1) + the P4-A `merged` section: per-field
+    provenance-marked view (manual > llm > raw on read, D-053)."""
+
+    id: str
+    source: str
+    external_id: str
+    name: str
+    logo: str
+    description: str
+    industry: str
+    size: str
+    location: str
+    website: str
+    social_links: dict[str, str]
+    culture: str
+    merged: dict[str, ProvenanceField] | None = None
+
+
+class SkillBreakdownEntry(BaseModel):
+    """One skill's deterministic explanation (MH-3f): tag-overlap with
+    the query (0/1) + the skill's vector contribution share."""
+
+    skill: str
+    overlap: int
+    contribution: float
+
+
+class SearchEntry(BaseModel):
+    """P3 search result (G-106): `match_score` exists ONLY in this
+    search context — a no-query facet listing carries None (honest
+    absence, never a fabricated number)."""
+
+    posting: PostingResponse
+    match_score: float | None
+    skill_breakdown: list[SkillBreakdownEntry]
+
+
+class SearchResponse(BaseModel):
+    results: list[SearchEntry]
+    query: str
+    ranked: int
+
+
+class ApplyBody(BaseModel):
+    """D-058: the learner identity comes from the VERIFIED record, not a
+    client assertion — but the pilot surface passes learner_id in the
+    body like every other gated route (G-5 composition unchanged)."""
+
+    learner_id: str = Field(min_length=1)
+    posting_id: str = Field(min_length=1)
+
+
+class ApplyResponse(BaseModel):
+    """Honest confirmation (D-058): exactly the application state, no
+    stub/mock markers, no fabricated outcome."""
+
+    application_id: str
+    posting_id: str
+    status: str
+
+
+def _posting_response(posting: Posting) -> PostingResponse:
+    return PostingResponse(
+        id=posting.id,
+        source=posting.source,
+        external_id=posting.external_id,
+        employer_id=posting.employer_id,
+        title=posting.title,
+        description=posting.description,
+        required_competencies=posting.required_competencies,
+        skills=posting.skills,
+        seniority=posting.seniority,
+        category=posting.category,
+        location=posting.location,
+        remote=posting.remote,
+        salary_min=posting.salary_min,
+        salary_max=posting.salary_max,
+        status=posting.status,
+        tags=dict(posting.tags) if posting.tags else None,
+        posted_at=posting.posted_at.isoformat() if posting.posted_at else None,
+    )
+
+
+def _employer_response(
+    employer: Employer, merged: dict[str, ProvenanceField] | None = None
+) -> EmployerResponse:
+    return EmployerResponse(
+        id=employer.id,
+        source=employer.source,
+        external_id=employer.external_id,
+        name=employer.name,
+        logo=employer.logo,
+        description=employer.description,
+        industry=employer.industry,
+        size=employer.size,
+        location=employer.location,
+        website=employer.website,
+        social_links=dict(employer.social_links),
+        culture=employer.culture,
+        merged=merged,
+    )
+
+
+# -- public endpoints ---------------------------------------------------------
+
+
+@router.get("/postings", response_model=PostingListResponse)
+async def list_postings(
+    store=Depends(get_marketplace_store),
+    limit: int = Query(default=20, ge=1, le=100),
+    offset: int = Query(default=0, ge=0),
+) -> PostingListResponse:
+    """Published postings only (draft/closed never board), posted_at DESC,
+    with the honest total (G-103) + facets from published-only stored
+    tags (MH-2c — facets computed once per page request, identical on
+    every page of the fetch-all)."""
+    postings, total = store.list_postings(limit=limit, offset=offset)
+    return PostingListResponse(
+        postings=[_posting_response(p) for p in postings],
+        total_published=total,
+        facets=store.facets(),
+    )
+
+
+@router.get("/search", response_model=SearchResponse)
+async def search_postings(
+    store=Depends(get_marketplace_store),
+    embedder: EmbeddingProvider = Depends(get_embedding_provider),
+    q: str = Query(default=""),
+    skills: list[str] = Query(default=[]),
+    seniority: str | None = Query(default=None),
+    category: str | None = Query(default=None),
+    location: str | None = Query(default=None),
+    remote: bool | None = Query(default=None),
+    salary_min: int | None = Query(default=None, ge=0),
+    salary_max: int | None = Query(default=None, ge=0),
+    limit: int = Query(default=20, ge=1, le=100),
+) -> SearchResponse:
+    """P3 semantic search (REQ-6-003, D-051/A-405): facet hard-filters
+    SQL-side FIRST, then cosine ranking DESC over the filtered set; no
+    facets → pure semantic rank. `match_score` exists ONLY here (G-106)
+    — an empty `q` with facets is a facet-only listing (posted_at DESC,
+    match_score null — no query → no fabricated scores)."""
+    filters = FacetFilters(
+        skills=skills,
+        seniority=seniority,
+        category=category,
+        location=location,
+        remote=remote,
+        salary_min=salary_min,
+        salary_max=salary_max,
+    )
+    ranked = await rank_postings(store, embedder, q, filters, limit=limit)
+    has_query = bool(q.strip())
+    return SearchResponse(
+        results=[
+            SearchEntry(
+                posting=_posting_response(r.posting),
+                match_score=round(r.score, 6) if has_query else None,
+                # P5 scoped: search.skill_breakdown() yields raw dicts in the
+                # exact entry shape (marketplace/ may not import api/ models —
+                # D-048 boundary); pydantic coerces them into
+                # SkillBreakdownEntry at this SearchEntry boundary.
+                skill_breakdown=r.skill_breakdown if has_query else [],  # type: ignore[arg-type]
+            )
+            for r in ranked
+        ],
+        query=q,
+        ranked=len(ranked),
+    )
+
+
+@router.get("/postings/{posting_id}", response_model=PostingResponse)
+async def get_posting(
+    posting_id: str,
+    store=Depends(get_marketplace_store),
+) -> PostingResponse:
+    """Honest 404 on any unknown id — never a fabricated job."""
+    posting = store.get_posting(posting_id)
+    if posting is None:
+        raise HTTPException(
+            status_code=404, detail=f"no posting with id {posting_id!r}"
+        )
+    return _posting_response(posting)
+
+
+@router.get("/employers/{employer_id}", response_model=EmployerResponse)
+async def get_employer(
+    employer_id: str,
+    store=Depends(get_marketplace_store),
+) -> EmployerResponse:
+    """Honest 404 on unknown employers. Raw fields stay as-is; the P4-A
+    `merged` section carries the per-field provenance view (manual >
+    llm > raw, D-053/A-304 — LLM copy is visibly marked, never
+    displayed as ingested fact)."""
+    employer = store.get_employer(employer_id)
+    if employer is None:
+        raise HTTPException(
+            status_code=404, detail=f"no employer with id {employer_id!r}"
+        )
+    rows = store.list_enrichment(employer_id)
+    merged_raw = merge_employer(employer, rows) if rows else None
+    merged = (
+        {
+            field: ProvenanceField(
+                value=entry["value"], source=entry["source"], model=entry["model"]
+            )
+            for field, entry in merged_raw.items()
+        }
+        if merged_raw
+        else None
+    )
+    return _employer_response(employer, merged=merged)
+
+
+# -- the real apply route (D-058; the G-18 stub's replacement) ------------------
+
+
+@router.post("/apply", response_model=ApplyResponse)
+async def apply_posting(
+    body: ApplyBody,
+    request: Request,
+    store=Depends(get_marketplace_store),
+    settings: Settings = Depends(get_settings),
+) -> ApplyResponse:
+    """Apply to a posting. Gate composition (D-043, unchanged order):
+    G-5 allowlist → require_verified_adult (18+ verified, verify-CTA
+    403) → rate caps → posting exists (404) + published (409) →
+    idempotent insert (A-408: a duplicate returns the EXISTING
+    application with 200)."""
+    _enforce_allowlist(body.learner_id, settings)
+    await require_verified_age(18, body.learner_id, _identity_store(request))
+    _check_apply_rate(body.learner_id)
+
+    posting = store.get_posting(body.posting_id)
+    if posting is None:
+        raise HTTPException(
+            status_code=404, detail=f"no posting with id {body.posting_id!r}"
+        )
+    if posting.status != "published":
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "reason": "posting_not_published",
+                "status": posting.status,
+            },
+        )
+
+    application, _created = store.insert_application(
+        posting_id=body.posting_id, learner_id=body.learner_id
+    )
+    return ApplyResponse(
+        application_id=application.id,
+        posting_id=application.posting_id,
+        status=application.status,
+    )
+
+
+# -- P4-B: resume upload + confirm (REQ-6-005, D-054, A-410) --------------------
+
+
+class ResumeDraftResponse(BaseModel):
+    """The parse result — a DRAFT. Nothing persists without the explicit
+    confirm call (the REQ-6-005 review gate)."""
+
+    status: str = "draft"
+    profile: dict
+
+
+class ResumeConfirmBody(BaseModel):
+    """The learner's explicit save decision: the draft profile rides the
+    body VERBATIM from the parse and the server RE-VALIDATES the shape
+    against ParsedProfile before persisting (verifier P1 — a bare dict
+    would accept arbitrary/type-confused payloads)."""
+
+    learner_id: str = Field(min_length=1)
+    profile: dict
+
+
+class ResumeConfirmResponse(BaseModel):
+    status: str = "confirmed"
+    learner_id: str
+    confirmed_at: str
+
+
+async def _require_verified_marketplace_learner(
+    learner_id: str,
+    settings: Settings,
+    request: Request,
+) -> None:
+    """Learner-gated resume surface (D-043 composition order): G-5
+    allowlist → verified identity → rate caps — same order as apply."""
+    _enforce_allowlist(learner_id, settings)
+    await require_verified_age(18, learner_id, _identity_store(request))
+    _check_apply_rate(learner_id)
+
+
+@router.post("/resume", response_model=ResumeDraftResponse)
+async def upload_resume(
+    request: Request,
+    store=Depends(get_marketplace_store),
+    settings: Settings = Depends(get_settings),
+    provider=Depends(get_provider),
+) -> ResumeDraftResponse:
+    """Parse an uploaded resume into a profile DRAFT (multipart: `file`
+    + `learner_id` form field). Bounds (A-410): PDF/TXT/MD only, ≤2 MB,
+    text-layer required (empty PDF extract → honest 422; no OCR in
+    v0.6). Raw bytes never stored, never logged (A-305). The response
+    is a DRAFT — the confirm route is the only persistence path."""
+
+    from starlette.datastructures import UploadFile as StarletteUploadFile
+
+    form = await request.form()
+    try:
+        learner_id = form.get("learner_id")
+        if not isinstance(learner_id, str) or not learner_id:
+            raise HTTPException(
+                status_code=422, detail="learner_id form field required"
+            )
+        await _require_verified_marketplace_learner(learner_id, settings, request)
+
+        upload = form.get("file")
+        # starlette's UploadFile base (fastapi's is a subclass — the raw
+        # request.form() yields the base, so isinstance must use it).
+        if not isinstance(upload, StarletteUploadFile):
+            raise HTTPException(status_code=422, detail="file form field required")
+        data = await upload.read()
+        if len(data) > MAX_RESUME_BYTES:
+            raise HTTPException(
+                status_code=413,
+                detail=f"resume too large ({len(data)} bytes; max {MAX_RESUME_BYTES})",
+            )
+        if len(data) == 0:
+            raise HTTPException(status_code=422, detail="empty file")
+        content_type = upload.content_type or ""
+        try:
+            text = extract_resume_text(data, content_type)
+        except ResumeFormatError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        try:
+            parsed = await parse_resume(provider, model=settings.model, text=text)
+        except Exception as exc:
+            raise HTTPException(
+                status_code=502,
+                detail="profile extraction failed — try again or edit manually",
+            ) from exc
+        draft = ResumeDraftResponse(
+            status="draft",
+            profile={
+                "name": parsed.name,
+                "headline": parsed.headline,
+                "skills": list(parsed.skills),
+                "experience_bands": [
+                    b.model_dump() for b in parsed.experience_bands
+                ],
+                "competencies": list(parsed.competencies),
+            },
+        )
+    finally:
+        # P3 (Task 3-2-01): this route parses the form manually (raw
+        # request.form()), so FastAPI's request-end auto-close — which it
+        # pushes ONLY for param-injected multipart bodies — never runs
+        # here. The multipart parser has already spooled every file open
+        # by the time any guard raises (learner_id 422, allowlist 403,
+        # verified 403, rate 429 — the pre-read guards included), so the
+        # close must span ALL paths. form.close() is starlette's
+        # canonical cleanup for manually-parsed forms: it closes every
+        # UploadFile the form carries. The bytes are fully in `data`
+        # before any raise (G-107: no streaming path exists); the
+        # response is materialized in `draft` — nothing reads the
+        # spooled file after this point.
+        await form.close()
+    return draft
+
+
+@router.post("/resume/confirm", response_model=ResumeConfirmResponse)
+async def confirm_resume(
+    body: ResumeConfirmBody,
+    request: Request,
+    store=Depends(get_marketplace_store),
+    settings: Settings = Depends(get_settings),
+) -> ResumeConfirmResponse:
+    """The REQ-6-005 review gate: persist the learner-CONFIRMED profile
+    to the learner_profile store table (G-104 — the D-027 family is the
+    only persistence mechanism). G-5 → verified 18+ → rate caps, then
+    a SHAPE RE-VALIDATION against ParsedProfile (verifier P1 — the
+    confirm must never persist arbitrary/type-confused payloads the
+    parse never produced), then an UPSERT (re-confirm replaces; the
+    draft never persisted)."""
+    await _require_verified_marketplace_learner(body.learner_id, settings, request)
+    try:
+        validated = ParsedProfile.model_validate(body.profile)
+    except ValidationError as exc:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "reason": "invalid_profile_shape",
+                "message": "the profile must match the parsed draft shape",
+                "errors": [
+                    {"loc": list(e.get("loc", [])), "msg": e.get("msg", "")}
+                    for e in exc.errors()
+                ],
+            },
+        ) from exc
+    stored = store.save_learner_profile(
+        body.learner_id, validated.model_dump(mode="json"), model=settings.model
+    )
+    return ResumeConfirmResponse(
+        status="confirmed",
+        learner_id=stored["learner_id"],
+        confirmed_at=stored["confirmed_at"].isoformat()
+        if stored["confirmed_at"]
+        else "",
+    )

apps/ai-service/ai_service/api/marketplace_admin.py

@@ -0,0 +1,423 @@
+"""/v1/marketplace/admin — founder/operator surface (REQ-6-001, D-057).
+
+Guard: `require_admin` compares X-Admin-Token OR Authorization: Bearer
+against Settings().admin_token via secrets.compare_digest (G-108).
+UNSET token → every admin route 403s — fail-closed, NEVER open (a loud
+boot warning in main.py names the fix, G-11). Admin routes do NOT pass
+the learner gates (different principal class, D-057/D-043 untouched).
+
+Routes: create draft posting, publish/close lifecycle (invalid
+transition → 409), seeded-corpus ingest trigger, applications review
+(filterable by posting). No cron/crawler — ingest is founder-invoked
+(A-401/A-402).
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+import uuid
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Header, HTTPException
+from pydantic import BaseModel, Field
+
+from ..config import Settings
+from ..llm.base import LLMProvider
+from ..marketplace.base import Posting
+from ..marketplace.embedding.base import EmbeddingProvider
+from ..marketplace.enrichment import ENRICHABLE_FIELDS, maybe_enrich_on_publish
+from ..marketplace.ingest import SeededCorpusSource, run_ingest
+from ..marketplace.search import embed_posting
+from ..marketplace.store import InvalidTransition, MarketplaceStore
+from ..marketplace.tagging import TaggingUnavailable, tag_posting
+from .deps import (
+    get_embedding_provider,
+    get_marketplace_store,
+    get_provider,
+    get_settings,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/v1/marketplace/admin", tags=["marketplace-admin"])
+
+
+def _extract_admin_token(
+    x_admin_token: Annotated[str | None, Header(include_in_schema=False)] = None,
+    authorization: Annotated[str | None, Header(include_in_schema=False)] = None,
+) -> str | None:
+    """Bearer of the request: X-Admin-Token wins; else Authorization:
+    Bearer <token>. None when neither header carries a candidate."""
+    if x_admin_token:
+        return x_admin_token
+    if authorization:
+        scheme, _, token = authorization.partition(" ")
+        if scheme.strip().lower() == "bearer" and token.strip():
+            return token.strip()
+    return None
+
+
+def require_admin(
+    request_token: Annotated[str | None, Depends(_extract_admin_token)],
+    settings: Annotated[Settings, Depends(get_settings)],
+) -> Settings:
+    """D-057 fail-closed guard: constant-time compare (G-108) against the
+    env-only AI_ADMIN_TOKEN (SecretStr — never repr'd/logged); UNSET → 403
+    for EVERY request (never open). Returns the settings for the route
+    handlers.
+
+    Bytes compare: `secrets.compare_digest` raises TypeError on
+    non-ASCII str candidates (final-review F-1 — an attacker-triggerable
+    unhandled 500, fail-closed in outcome but noisy); comparing the
+    UTF-8 encodings accepts ANY candidate bytes honestly (403 on
+    mismatch) and stays constant-time."""
+    configured = settings.admin_token.get_secret_value()
+    if not configured or request_token is None:
+        # Fail-closed: no configured token, or no candidate at all — the
+        # surface is locked, not open (D-057).
+        raise HTTPException(status_code=403, detail="admin token required")
+    if not secrets.compare_digest(
+        request_token.encode("utf-8", "surrogatepass"),
+        configured.encode("utf-8"),
+    ):
+        raise HTTPException(status_code=403, detail="invalid admin token")
+    return settings
+
+
+# -- contracts ----------------------------------------------------------------
+
+
+class AdminPostingCreate(BaseModel):
+    """Admin-authored posting body. Starts as a DRAFT (G-102: only
+    seed-port postings enter published); publish is an explicit call."""
+
+    employer_id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    description: str = ""
+    required_competencies: list[str] = Field(default_factory=list)
+    skills: list[str] = Field(default_factory=list)
+    seniority: str | None = None
+    category: str | None = None
+    location: str = ""
+    remote: bool = False
+    salary_min: int | None = None
+    salary_max: int | None = None
+
+
+class AdminPostingResponse(BaseModel):
+    id: str
+    source: str
+    external_id: str
+    employer_id: str
+    title: str
+    status: str
+
+
+class IngestResponse(BaseModel):
+    postings_upserted: int
+    employers_upserted: int
+
+
+class AdminPostingEdit(BaseModel):
+    """P2 (Task 2-1-03): partial content edit; fields omitted stay put.
+    A successful edit RE-TAGS the posting (tags are derived data,
+    D-052 — the tagger overwrites)."""
+
+    title: str | None = Field(default=None, min_length=1)
+    description: str | None = None
+    skills: list[str] | None = None
+
+
+class AdminEnrichmentOverride(BaseModel):
+    """P4-A (D-053): manual-override body — appends a manual-source row
+    (never mutates llm rows). `value` for social_links is a JSON object
+    string; the other fields are plain text."""
+
+    employer_id: str = Field(min_length=1)
+    field: str = Field(min_length=1)
+    value: str = Field(min_length=1)
+
+
+class AdminApplication(BaseModel):
+    id: str
+    posting_id: str
+    learner_id: str
+    status: str
+    created_at: str
+
+
+class AdminApplicationsResponse(BaseModel):
+    applications: list[AdminApplication]
+
+
+# -- routes --------------------------------------------------------------------
+
+
+@router.post("/postings", status_code=201, response_model=AdminPostingResponse)
+async def create_posting(
+    body: AdminPostingCreate,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+) -> AdminPostingResponse:
+    """Create a DRAFT posting (founder authoring path, D-050 admin_api
+    adapter — source=admin). Publish is a separate lifecycle call."""
+    posting = Posting(
+        id=f"adm-{uuid.uuid4().hex[:16]}",
+        source="admin",
+        external_id=f"adm-{uuid.uuid4().hex[:16]}",
+        employer_id=body.employer_id,
+        title=body.title,
+        description=body.description,
+        required_competencies=body.required_competencies,
+        skills=body.skills,
+        # P5: admin body carries str; Posting's Literal contract — the
+        # store's validates hook rejects out-of-taxonomy values.
+        seniority=body.seniority,  # type: ignore[arg-type]
+        category=body.category,
+        location=body.location,
+        remote=body.remote,
+        salary_min=body.salary_min,
+        salary_max=body.salary_max,
+        status="draft",
+    )
+    try:
+        stored = store.insert_posting(posting)
+    except Exception as exc:  # surfaced IntegrityError from the store
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    return AdminPostingResponse(
+        id=stored.id,
+        source=stored.source,
+        external_id=stored.external_id,
+        employer_id=stored.employer_id,
+        title=stored.title,
+        status=stored.status,
+    )
+
+
+@router.post(
+    "/postings/{posting_id}/publish", response_model=AdminPostingResponse
+)
+async def publish_posting(
+    posting_id: str,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+    embedder: EmbeddingProvider = Depends(get_embedding_provider),
+    provider: LLMProvider = Depends(get_provider),
+) -> AdminPostingResponse:
+    """draft → published (the only valid move from draft; anything else
+    409s). Stamps posted_at NOW when the row has none (G-102: seed-port
+    postings keep their original postedAt).
+
+    P3 embed-on-publish (Task 3-2-01): the published posting embeds
+    now; failure = honest warning — the posting still publishes, the
+    vector stays absent (search skips it).
+
+    P4-A enrich-on-first-publish (D-053): the employer's FIRST publish
+    fires the one-shot profile extraction (no existing llm rows → run;
+    re-publishing the same employer does not re-run). Failure = honest
+    warning — the publish stands, no rows written."""
+    try:
+        stored = store.set_posting_status(posting_id, "published")
+    except InvalidTransition as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    if stored is None:
+        raise HTTPException(
+            status_code=404, detail=f"no posting with id {posting_id!r}"
+        )
+    await embed_posting(store, embedder, stored)
+    try:
+        await maybe_enrich_on_publish(
+            store, provider, model=settings.model, employer_id=stored.employer_id
+        )
+    except Exception:  # pragma: no cover - maybe_enrich swallows; belt+braces
+        logger.exception("enrich-on-publish failed; publish stands")
+    return AdminPostingResponse(
+        id=stored.id,
+        source=stored.source,
+        external_id=stored.external_id,
+        employer_id=stored.employer_id,
+        title=stored.title,
+        status=stored.status,
+    )
+
+
+@router.post("/enrichment", status_code=201)
+async def manual_enrichment_override(
+    body: AdminEnrichmentOverride,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+) -> dict:
+    """P4-A (D-053): founder manual override — APPENDS a manual-source
+    row (read precedence manual > llm > raw picks it up); llm rows are
+    NEVER mutated. Valid fields: description | social_links | logo."""
+    if body.field not in ENRICHABLE_FIELDS:
+        raise HTTPException(
+            status_code=422,
+            detail=f"field must be one of {ENRICHABLE_FIELDS}",
+        )
+    employer = store.get_employer(body.employer_id)
+    if employer is None:
+        raise HTTPException(
+            status_code=404, detail=f"no employer with id {body.employer_id!r}"
+        )
+    row = store.append_enrichment(
+        body.employer_id,
+        field=body.field,
+        value=body.value,
+        source="manual",
+    )
+    return {"stored": True, "row": row}
+
+
+@router.post(
+    "/postings/{posting_id}/close", response_model=AdminPostingResponse
+)
+async def close_posting(
+    posting_id: str,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+) -> AdminPostingResponse:
+    """published → closed (the only valid move from published; 409 on
+    closing a draft or re-closing)."""
+    try:
+        stored = store.set_posting_status(posting_id, "closed")
+    except InvalidTransition as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    if stored is None:
+        raise HTTPException(
+            status_code=404, detail=f"no posting with id {posting_id!r}"
+        )
+    return AdminPostingResponse(
+        id=stored.id,
+        source=stored.source,
+        external_id=stored.external_id,
+        employer_id=stored.employer_id,
+        title=stored.title,
+        status=stored.status,
+    )
+
+
+@router.put("/postings/{posting_id}", response_model=AdminPostingResponse)
+async def edit_posting(
+    posting_id: str,
+    body: AdminPostingEdit,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+    provider: LLMProvider = Depends(get_provider),
+) -> AdminPostingResponse:
+    """P2 (Task 2-1-03): edit title/description/skills → RE-TAG the
+    posting (D-052: tags are derived data — the new extraction
+    OVERWRITES the old tags column; old tags gone). Tag failure is
+    honest: the edit persists, tags stay as they were, a warning logs."""
+    updated = store.update_posting_fields(
+        posting_id,
+        title=body.title,
+        description=body.description,
+        skills=body.skills,
+    )
+    if updated is None:
+        raise HTTPException(
+            status_code=404, detail=f"no posting with id {posting_id!r}"
+        )
+    try:
+        tags = await tag_posting(
+            provider,
+            model=settings.model,
+            title=updated.title,
+            description=updated.description,
+            skills_hint=updated.skills,
+        )
+        updated = store.set_posting_tags(posting_id, tags) or updated
+    except TaggingUnavailable:
+        # Honest: the EDIT landed; tags keep their previous value (the
+        # warning already logged in tagging.py). Never 500 on tag failure.
+        pass
+    return AdminPostingResponse(
+        id=updated.id,
+        source=updated.source,
+        external_id=updated.external_id,
+        employer_id=updated.employer_id,
+        title=updated.title,
+        status=updated.status,
+    )
+
+
+@router.post("/ingest", response_model=IngestResponse)
+async def ingest(
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+    provider: LLMProvider = Depends(get_provider),
+    embedder: EmbeddingProvider = Depends(get_embedding_provider),
+) -> IngestResponse:
+    """Run the seeded corpus source now (founder-invoked — no scheduler,
+    A-401/A-402). Idempotent on (source, external_id): a double-run
+    yields identical rows (MH-1b). Every posting is TAGGED after
+    upsert (P2, D-052) — a tag failure leaves the posting UNTAGGED with
+    a warning, never a crashed ingest. Published seed postings EMBED
+    after tagging (P3 embed-on-publish path, Task 3-2-01) — an embed
+    failure is the same honest warning."""
+    source = SeededCorpusSource()
+    result = run_ingest(source, store)
+    tagged = 0
+    untagged = 0
+    embedded = 0
+    for posting in source.fetch():
+        stored = store.get_posting(posting.id)
+        if stored is None:  # pragma: no cover - upsert just ran
+            continue
+        try:
+            tags = await tag_posting(
+                provider,
+                model=settings.model,
+                title=stored.title,
+                description=stored.description,
+                skills_hint=stored.skills,
+            )
+            store.set_posting_tags(stored.id, tags)
+            stored = store.get_posting(stored.id) or stored
+            tagged += 1
+        except TaggingUnavailable:
+            untagged += 1
+        if stored.status == "published":
+            # Embed-on-publish for the published seed postings (G-102).
+            if await embed_posting(store, embedder, stored):
+                embedded += 1
+    if untagged:
+        logger.warning(
+            "marketplace ingest tagged %s/%s postings — %s left untagged "
+            "(provider failures are honest None, never fabricated)",
+            tagged,
+            tagged + untagged,
+            untagged,
+        )
+    return IngestResponse(
+        postings_upserted=result.postings_upserted,
+        employers_upserted=result.employers_upserted,
+    )
+
+
+@router.get(
+    "/applications", response_model=AdminApplicationsResponse
+)
+async def list_applications(
+    posting_id: str | None = None,
+    store: MarketplaceStore = Depends(get_marketplace_store),
+    settings: Settings = Depends(require_admin),
+) -> AdminApplicationsResponse:
+    """Applications review list (newest first), filterable by posting.
+    The founder contacts employers out-of-band (no notification infra,
+    A-408)."""
+    rows: list[Any] = store.list_applications(posting_id=posting_id)
+    return AdminApplicationsResponse(
+        applications=[
+            AdminApplication(
+                id=a.id,
+                posting_id=a.posting_id,
+                learner_id=a.learner_id,
+                status=a.status,
+                created_at=a.created_at.isoformat() if a.created_at else "",
+            )
+            for a in rows
+        ]
+    )

apps/ai-service/ai_service/api/marketplace_shells.py

@@ -0,0 +1,54 @@
+"""G-101 placeholder-shell serving (v0.6).
+
+Next 15's static export emits exactly one placeholder page per dynamic
+marketplace route (`out/marketplace/jobs/_/index.html`). Under the
+single-port deploy (D-039) these routes serve that shell for ANY id so
+runtime-created postings stay reachable and every sitemap URL resolves
+(G-109). The shell client-fetches the real data by path id and
+notFound()s on 404.
+
+Registered before the StaticFiles mount so the routes win (the same
+routes-beat-the-mount mechanism the sitemap relies on). In dev mode
+(web_static_dir unset) the Next dev server handles routing itself —
+no-op.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from fastapi.responses import FileResponse
+
+from ..config import Settings
+
+_SHELL_ROUTES = (
+    ("/marketplace/jobs/{job_id}", "marketplace/jobs/_/index.html"),
+    ("/marketplace/jobs/{job_id}/", "marketplace/jobs/_/index.html"),
+    ("/marketplace/employers/{employer_id}", "marketplace/employers/_/index.html"),
+    ("/marketplace/employers/{employer_id}/", "marketplace/employers/_/index.html"),
+)
+
+
+def register_marketplace_shell_routes(app: FastAPI, settings: Settings) -> None:
+    web_dir = Path(str(settings.web_static_dir or ""))
+    if str(settings.web_static_dir) in ("", ".") or not web_dir.is_dir():
+        # Dev/no-mount boots: the Next dev server or a separate web origin
+        # handles these paths. Nothing to serve here.
+        return
+
+    router = APIRouter()
+
+    for path, shell in _SHELL_ROUTES:
+
+        def _serve(shell_file: str = shell) -> FileResponse:
+            page = web_dir / shell_file
+            if page.is_file():
+                return FileResponse(page, media_type="text/html")
+            raise RuntimeError(  # pragma: no cover - deploy misconfig
+                f"marketplace shell missing: {page} — rebuild the web export"
+            )
+
+        router.get(path, include_in_schema=False)(_serve)
+
+    app.include_router(router)

apps/ai-service/ai_service/api/proctor.py

@@ -1,25 +1,35 @@
-"""POST /v1/proctor/signals — structured integrity signals (REQ-2-009).
+"""POST /v1/proctor/signals — integrity signals over REAL inputs (REQ-3-007).
 
-JSON response (not SSE): a pydantic-validated ProctorAssessment.
-Unknown scenario → 404. Coaching-shaped interventions only.
+v0.3 re-grounding: live trace digest + DefenseStore long-pause signals +
+variant seed cross-check, no corpus scenarios. The proctor coaches:
+a pydantic-validated ProctorAssessment (JSON response, not SSE).
 """
 
+from typing import cast
+
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 
-from ..agents.proctor import ProctorAssessment
+from ..agents.proctor import ProctorAgent, ProctorAssessment
 from ..agents.registry import AgentRegistry
 from ..config import Settings
 from ..corpus.learner_context import get_learner_context
-from ..corpus.telemetry import get_proctor_scenario
-from .deps import get_agent_registry, get_provider, get_settings
+from ..grading.features import compute_digest
+from .deps import (
+    get_agent_registry,
+    get_provider,
+    get_settings,
+    get_trace_store,
+    get_variant_store,
+    get_voice_store,
+)
 
 router = APIRouter(prefix="/v1")
 
 
 class ProctorRequest(BaseModel):
-    scenario_id: str = Field(min_length=1)
-    learner_id: str | None = None
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
 
 
 @router.post("/proctor/signals", response_model=ProctorAssessment)
@@ -28,16 +38,42 @@ async def proctor_signals(
     registry: AgentRegistry = Depends(get_agent_registry),
     settings: Settings = Depends(get_settings),
     provider=Depends(get_provider),
+    trace_store=Depends(get_trace_store),
+    variant_store=Depends(get_variant_store),
+    voice_store=Depends(get_voice_store),
 ) -> ProctorAssessment:
-    scenario = get_proctor_scenario(body.scenario_id)
-    if scenario is None:
-        raise HTTPException(
-            status_code=404, detail=f"unknown scenario {body.scenario_id!r}"
-        )
-    agent = registry.get(provider, settings, "proctor")
+    """Real integrity inputs: live digest + defense signals + variant context."""
+    # P5: registry.get returns BaseAgent; "proctor" is registered as
+    # ProctorAgent (register_builtin_agents) — the cast states that mapping.
+    agent = cast(ProctorAgent, registry.get(provider, settings, "proctor"))
     learner_context = get_learner_context(body.learner_id)
+
+    trace = (
+        trace_store.get_trace(body.learner_id, body.task_id)
+        if body.task_id in trace_store.list_tasks(body.learner_id)
+        else []
+    )
+    digest = compute_digest(trace) if trace else None
+
+    defense_signals = None
+    for record in voice_store.list_for_learner(body.learner_id):
+        if record.task_id == body.task_id and record.status == "finished":
+            defense_signals = record.integrity_signals or None
+            break
+
+    variant = variant_store.get_by_task(body.task_id)
+    variant_context = (
+        {"template_id": variant.template_id, "seed": variant.seed, "params": variant.params}
+        if variant is not None
+        else None
+    )
     try:
-        return await agent.assess(scenario, learner_context)
+        return await agent.assess(
+            digest,
+            defense_signals=defense_signals,
+            variant_context=variant_context,
+            learner_context=learner_context,
+        )
     except Exception as exc:
         raise HTTPException(
             status_code=502, detail=f"proctor assessment failed: {exc}"

apps/ai-service/ai_service/api/sandboxes.py

@@ -23,11 +23,14 @@ never part of the API contract.
 
 import time
 from collections import deque
+from collections.abc import Set as AbstractSet
+from pathlib import Path
 
-from fastapi import APIRouter, Depends, HTTPException, Response
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..config import Settings
+from ..sandbox.capability import DEGRADE_REMEDIATION, sandbox_fabric_degraded
 from ..sandbox.manager import (
     PoolFullError,
     SandboxHandleInfo,
@@ -35,7 +38,9 @@ from ..sandbox.manager import (
     SandboxNotFoundError,
 )
 from ..sandbox.workdir import SandboxDir
+from ..variants.templates import get_template
 from .deps import get_sandbox_manager, get_sandbox_test_layout, get_settings
+from .identity import require_verified_age
 
 router = APIRouter(prefix="/v1/sandboxes", tags=["sandboxes"])
 
@@ -50,6 +55,9 @@ _CREATE_TIMES: deque[float] = deque()
 
 class SandboxCreateRequest(BaseModel):
     learner_id: str = Field(min_length=1)
+    # Optional task key: when set, the sandbox is telemetry-wired (REQ-3-003)
+    # — the in-sandbox capture agent streams workspace events to the ingest.
+    task_id: str | None = None
 
 
 class SandboxResponse(BaseModel):
@@ -135,14 +143,33 @@ def _check_global_create_rate(settings: Settings) -> None:
 @router.post("", status_code=201, response_model=SandboxResponse)
 async def create_sandbox(
     body: SandboxCreateRequest,
+    request: Request,
     manager: SandboxManager = Depends(get_sandbox_manager),
     settings: Settings = Depends(get_settings),
 ) -> SandboxResponse:
+    # v0.5 identity gate (D-043, REQ-5-004): allowlist (G-5) → identity
+    # verdict (403 + verify-CTA) → caps (429) — the binding composition.
     _enforce_allowlist(body.learner_id, settings)
+    await require_verified_age(
+        16, body.learner_id, request.app.state.identity_store
+    )
     _check_per_learner_cap(await manager.list(), body.learner_id, settings)
     _check_global_create_rate(settings)
+    # v0.8 honest degrade (D-068/G-208): when the namespace fabric cannot
+    # work on this host (unprivileged container under docker's default
+    # seccomp), env creation is rejected BEFORE the manager is touched —
+    # same 503 class as PoolFullError, carrying the shared remediation
+    # constant (the boot notice logs the same text; they cannot drift).
+    # Structural backends (test stubs — no userns involved) declare
+    # `structural = True` and are exempt: the stub-backed suite must stay
+    # green inside job containers (D-063) while the REAL fabric degrades
+    # honestly everywhere.
+    manager_backend = getattr(manager, "_backend", None)
+    structural = getattr(manager_backend, "structural", False)
+    if not structural and sandbox_fabric_degraded():
+        raise HTTPException(status_code=503, detail=DEGRADE_REMEDIATION)
     try:
-        info = await manager.create(body.learner_id)
+        info = await manager.create(body.learner_id, task_id=body.task_id)
     except PoolFullError as exc:
         raise HTTPException(status_code=503, detail=str(exc)) from exc
     return _to_response(info)
@@ -217,3 +244,194 @@ async def delete_sandbox(
     if test_layout is not None:
         result.headers["X-Workspace-Copy"] = str(test_layout.workspace)
     return result
+
+
+# -- workspace files + exec (Phase 6, REQ-3-008; CUT-2) -------------------------
+#
+# The build surface reads/writes/list workspace files and runs Run/Test
+# commands through the manager's backend. NO interactive shell relay (CUT-2:
+# keystroke-level stdin/stdout is v0.4) — each exec is a bounded command with
+# captured output. Paths are WORKSPACE-RELATIVE; traversal outside the
+# workspace is rejected (the workdir bind is the boundary, but the API adds
+# its own containment check — defense in depth).
+
+
+class FileWriteRequest(BaseModel):
+    path: str = Field(min_length=1)
+    content: str
+
+
+class ExecRequest(BaseModel):
+    cmd: list[str] = Field(min_length=1)
+
+
+class ExecResponse(BaseModel):
+    cmd: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    duration_s: float
+
+
+async def _workspace_dir(manager: SandboxManager, sandbox_id: str):
+    """Resolve the sandbox workspace (tracked layout or shell layout)."""
+    info = await manager.get(sandbox_id)  # raises SandboxNotFoundError -> 404
+    backend = manager._backend
+    tracked = getattr(backend, "_tracked", {}).get(sandbox_id)
+    if tracked is not None:
+        return tracked.workspace, info
+    return info.workdir / "workspace", info
+
+
+def _safe_rel_path(raw: str) -> Path:
+    """Workspace-relative path; reject absolute/traversal paths."""
+    candidate = Path(raw)
+    if candidate.is_absolute() or ".." in candidate.parts:
+        raise HTTPException(status_code=422, detail=f"invalid workspace path {raw!r}")
+    return candidate
+
+
+def _resolve_in_workspace(workspace: Path, rel: Path) -> Path:
+    """Resolve `rel` under `workspace`, refusing symlink escapes (P7).
+
+    The lexical check in `_safe_rel_path` cannot see symlinks: an exec can
+    plant `ln -s /etc target` in the workspace and a follow-up read/write
+    would follow it OUT of the bind. Resolve with the workspace as the
+    anchor (strict: a symlink chain escaping raises) and confirm the
+    normalized target still sits inside the workspace — defense in depth
+    for both read_file and write_file.
+    """
+    try:
+        target = (workspace / rel).resolve(strict=False)
+        target.relative_to(workspace.resolve(strict=False))
+    except ValueError:
+        raise HTTPException(
+            status_code=422, detail=f"path escapes the workspace: {rel.as_posix()!r}"
+        ) from None
+    return target
+
+
+@router.get("/{sandbox_id}/files")
+async def list_files(
+    sandbox_id: str,
+    manager: SandboxManager = Depends(get_sandbox_manager),
+) -> dict:
+    try:
+        workspace, _ = await _workspace_dir(manager, sandbox_id)
+    except SandboxNotFoundError:
+        raise HTTPException(status_code=404, detail=f"no sandbox {sandbox_id!r}") from None
+    return {"files": sorted(p.name for p in workspace.iterdir()) if workspace.is_dir() else []}
+
+
+@router.get("/{sandbox_id}/files/{path:path}")
+async def read_file(
+    sandbox_id: str,
+    path: str,
+    manager: SandboxManager = Depends(get_sandbox_manager),
+) -> dict:
+    try:
+        workspace, _ = await _workspace_dir(manager, sandbox_id)
+    except SandboxNotFoundError:
+        raise HTTPException(status_code=404, detail=f"no sandbox {sandbox_id!r}") from None
+    rel = _safe_rel_path(path)
+    target = _resolve_in_workspace(workspace, rel)
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail=f"no file {path!r}")
+    return {"path": path, "content": target.read_text(errors="replace")}
+
+
+@router.put("/{sandbox_id}/files/{path:path}")
+async def write_file(
+    sandbox_id: str,
+    path: str,
+    body: FileWriteRequest,
+    manager: SandboxManager = Depends(get_sandbox_manager),
+) -> dict:
+    try:
+        workspace, _ = await _workspace_dir(manager, sandbox_id)
+    except SandboxNotFoundError:
+        raise HTTPException(status_code=404, detail=f"no sandbox {sandbox_id!r}") from None
+    rel = _safe_rel_path(body.path)
+    target = _resolve_in_workspace(workspace, rel)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(body.content)
+    return {"path": body.path, "written": True}
+
+
+#: G-15 (REQ-5-005): per-kind exec command policy — EXACT argv[0] token
+#: matching, never prefix/substring (trivially bypassed via flags/-c
+#: passthrough). 'sh -c' passthrough is DISALLOWED for design/simulation
+#: kinds: the gaming vector would be faking build-style test cycles into a
+#: kind-agnostic digest. Build kinds keep v0.3 behavior (any command —
+#: the CUT-2 surface is Run/Test buttons, not a shell relay).
+#: python (bare) is deliberately absent — in-ns PATH resolves only python3
+#: (verifier P1); pip is absent (no network in the namespace).
+_GENERIC_FIRST_TOKENS = frozenset(
+    {"ls", "cat", "pwd", "echo", "python3", "pytest"}
+)
+
+
+def _enforce_exec_policy(
+    # P5: AbstractSet[str] — the caller unions frozenset + set; membership
+    # is all this function does with it.
+    cmd: list[str], environment: str | None, allowed: AbstractSet[str] | None = None
+) -> None:
+    """422 with the allowed set when a design/sim command is out of policy.
+
+    `allowed` defaults to the generic set; the exec route unions in the
+    template's DECLARED harness argv[0] (a future non-python harness
+    template must not reject its own Run command)."""
+    if environment not in ("design", "simulation"):
+        return  # build kind: unchanged v0.3 semantics
+    if allowed is None:
+        allowed = _GENERIC_FIRST_TOKENS
+    first = cmd[0] if cmd else ""
+    if first in ("sh", "bash"):
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"shell passthrough is not allowed in a {environment} "
+                f"environment; allowed commands: {sorted(allowed)}"
+            ),
+        )
+    if first not in allowed:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"command {first!r} is not allowed in a {environment} "
+                f"environment; allowed commands: {sorted(allowed)}"
+            ),
+        )
+
+
+@router.post("/{sandbox_id}/exec", response_model=ExecResponse)
+async def exec_command(
+    sandbox_id: str,
+    body: ExecRequest,
+    request: Request,
+    manager: SandboxManager = Depends(get_sandbox_manager),
+) -> ExecResponse:
+    try:
+        await manager.get(sandbox_id)
+    except SandboxNotFoundError:
+        raise HTTPException(status_code=404, detail=f"no sandbox {sandbox_id!r}") from None
+    backend = manager._backend
+    handle = manager._handles.get(sandbox_id)
+    if handle is None:
+        raise HTTPException(status_code=404, detail=f"no live handle {sandbox_id!r}")
+    # REQ-5-005 (G-15): resolve the sandbox's variant environment by its
+    # task_id (manager side-table) and enforce the per-kind command policy
+    # BEFORE execution.
+    task_id = manager._task_ids.get(sandbox_id)
+    if task_id:
+        variant = request.app.state.variant_store.get_by_task(task_id)
+        if variant is not None:
+            template = get_template(variant.template_id)
+            declared = (
+                {template.run_command.split()[0]} if template is not None else set()
+            )
+            _enforce_exec_policy(
+                body.cmd, variant.environment, _GENERIC_FIRST_TOKENS | declared
+            )
+    result = await backend.exec(handle, body.cmd)
+    return ExecResponse(**result.model_dump())

apps/ai-service/ai_service/api/sitemap.py

@@ -0,0 +1,118 @@
+"""Dynamic sitemap.xml + robots.txt (REQ-6-006, D-056, A-411).
+
+Next `app/sitemap.ts` cannot work under `output: 'export'` — it
+enumerates at BUILD time and cannot see runtime postings. These plain
+FastAPI routes enumerate at REQUEST time: the static page list (a code
+constant) + every PUBLISHED posting (via the G-101 catch-all shells,
+each URL resolves — G-109, the sitemap never advertises what the
+deploy 404s).
+
+Mount order (probe 6, verified): API routes beat the StaticFiles("/")
+export mount, so these win in single-port production. robots.txt
+points at the sitemap; per the robots spec the Sitemap directive must
+be an ABSOLUTE URL.
+
+Unset AI_PUBLIC_BASE_URL (G-105): loud G-11 boot warning (main.py);
+the sitemap serves the EMPTY static-page set with a warning comment
+(never malformed or relative URLs) and robots omits the Sitemap
+directive; fail honest at request time; boot never crashes.
+
+Pilot scale bound (A-403): postings are enumerated with limit=5000 —
+the tail beyond 5000 published postings is NOT listed (no sitemap
+pagination in v0.6; a sitemap index lands with the third adapter).
+"""
+
+from __future__ import annotations
+
+from xml.sax.saxutils import escape as _xml_escape
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import Response
+
+from ..config import Settings
+from .deps import get_marketplace_store, get_settings
+
+router = APIRouter(include_in_schema=False)
+
+#: The static page set (A-411 build-time-static pages) — code constant;
+#: runtime postings append at request time. G-109: every path is the
+#: page's real export path (the pricing page exports under
+#: /marketplace/pricing/, never /pricing/).
+STATIC_PAGES: tuple[str, ...] = (
+    "/",
+    "/catalog",
+    "/marketplace",
+    "/marketplace/pricing",
+)
+
+
+def _origin(settings: Settings) -> str | None:
+    raw = (settings.public_base_url or "").strip().rstrip("/")
+    if not raw:
+        return None
+    if not raw.startswith(("http://", "https://")):
+        return None  # malformed origin — never emit a bad absolute URL
+    return raw
+
+
+@router.get("/sitemap.xml")
+async def sitemap(
+    store=Depends(get_marketplace_store),
+    settings: Settings = Depends(get_settings),
+) -> Response:
+    """Published postings + the static page set, as absolute URLs from
+    AI_PUBLIC_BASE_URL. Unset origin → the honest empty set (G-105)."""
+    origin = _origin(settings)
+    if origin is None:
+        # G-105: fail honest — never relative/malformed URLs in a
+        # sitemap (spec requires absolute).
+        return Response(
+            content="<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
+            "<!-- sitemap disabled: AI_PUBLIC_BASE_URL is unset — "
+            "set the deployed origin to serve this sitemap -->\n"
+            "<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n"
+            "</urlset>\n",
+            media_type="application/xml",
+        )
+    urls: list[str] = []
+    for page in STATIC_PAGES:
+        urls.append(f"{origin}{page}")
+    # Runtime postings — every published one resolves via the G-101
+    # catch-all shells (trailingSlash: true → /marketplace/jobs/{id}/).
+    # Pilot cap (A-403, ≤10⁴ postings): a single sitemap page holds
+    # ≤50,000 URLs; beyond 5000 postings the tail is dropped — the
+    # honest bound recorded in the module docstring (no pagination in
+    # v0.6; a sitemap index lands with the 3M-corpus adapter).
+    postings, _total = store.list_postings(limit=5000, offset=0)
+    for posting in postings:
+        urls.append(f"{origin}/marketplace/jobs/{posting.id}/")
+    body = ["<?xml version=\"1.0\" encoding=\"UTF-8\"?>"]
+    body.append(
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+    )
+    for url in urls:
+        # XML-escape the loc text — the origin is founder-set env, but
+        # defense-in-depth: metacharacters in it must never break out
+        # of the <loc> element (verified: raw <script> would otherwise
+        # inject into the response body).
+        body.append("<url>")
+        body.append(f"<loc>{_xml_escape(url)}</loc>")
+        body.append("</url>")
+    body.append("</urlset>")
+    return Response(content="\n".join(body) + "\n", media_type="application/xml")
+
+
+@router.get("/robots.txt")
+async def robots(settings: Settings = Depends(get_settings)) -> Response:
+    """Crawl policy: allow all; the Sitemap directive is ABSOLUTE
+    (spec) — omitted entirely when the origin is unset (G-105)."""
+    lines = ["User-agent: *", "Allow: /"]
+    origin = _origin(settings)
+    if origin is not None:
+        # The origin is founder-set env, but defense-in-depth: strip
+        # control characters (newline smuggling could forge extra
+        # robots directives — a newline in the origin once appended
+        # "Disallow: /admin" as a directive line).
+        safe = "".join(c for c in origin if ord(c) >= 32)
+        lines.append(f"Sitemap: {safe}/sitemap.xml")
+    return Response(content="\n".join(lines) + "\n", media_type="text/plain")

apps/ai-service/ai_service/api/telemetry.py

@@ -0,0 +1,190 @@
+"""/v1/telemetry — WS ingest + trace read endpoints (REQ-3-003, D-026, G-3).
+
+The router composes the telemetry engine via DI: `telemetry/ingest.py` owns
+the WS protocol (frame contract + flood control + keepalive) and this module
+only wires `app.state.trace_store` / `app.state.trace_integrity` /
+`app.state.settings` into it, plus the two HTTP read faces:
+
+    WS   /v1/telemetry/ingest?learner_id&task_id[&sandbox_id]   (D-026)
+    GET  /v1/telemetry/traces/{learner_id}/{task_id}            ordered trace; 404 unknown
+    GET  /v1/telemetry/gaps/{learner_id}/{task_id}              missing seqs   ; 404 unknown
+
+The WS route is a thin DI shell: it validates the query-param identity and
+the Origin (browser pages are gated to the localhost dev origins — CORS
+middleware does not cover WS upgrades; the stdlib capture agent sends no
+Origin and is unaffected), pulls store/integrity/settings from `app.state`,
+and calls `telemetry_ingest_endpoint(...)` — the engine stays
+FastAPI-DI-free so it's testable without a router and the api/ layer owns
+all composition.
+
+Unknown-trace contract: a trace is KNOWN when it has >=1 stored event OR
+carries an integrity flag — a flooded trace with zero stored rows still 200s
+so Proctor/grader can read WHY it's unusable (G-4 consumes
+`integrity_reason`). `TraceResponse.incomplete` / `.integrity_reason` mirror
+the map so HTTP consumers never touch process internals.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, WebSocket
+from pydantic import BaseModel
+
+from ..telemetry.ingest import (
+    TraceIntegrityMap,
+    telemetry_ingest_endpoint,
+)
+from ..telemetry.models import TelemetryEvent
+from ..telemetry.store import TraceStore
+from ..telemetry.tokens import IngestToken
+from .deps import get_trace_integrity, get_trace_store
+
+router = APIRouter(prefix="/v1/telemetry", tags=["telemetry"])
+
+#: Browser Origins allowed to open the ingest socket (A-008 mirror, D-038).
+#: The stdlib capture agent sends NO Origin header (it is not a browser) and
+#: stays allowed; a malicious page loaded in the learner's browser would
+#: carry an Origin and must not be able to poison/flood the trace. CORS
+#: middleware does NOT cover WebSocket upgrades, so this gate is explicit.
+#: In network mode the configured CORS list governs (default '*' — any
+#: origin, since credentials are never used); an explicit list still rejects
+#: unlisted origins with 1008.
+_LOCAL_WS_ORIGINS = frozenset(
+    {"http://localhost:3000", "http://127.0.0.1:3000", "http://localhost:8420"}
+)
+
+
+def _allowed_ws_origins(settings: object) -> frozenset[str]:
+    configured = getattr(settings, "cors_origin_list", None)
+    if configured is None:
+        return _LOCAL_WS_ORIGINS
+    if configured == ["*"]:
+        return frozenset()  # empty = wildcard = every Origin passes
+    return frozenset(configured) | _LOCAL_WS_ORIGINS
+
+
+# --- WS ingest (D-026) ---------------------------------------------------------
+
+
+@router.websocket("/ingest")
+async def telemetry_ingest_ws(websocket: WebSocket) -> None:
+    """DI shell: resolve app.state services, then hand the socket to the engine.
+
+    The engine's session + flood logic is fully typed and testable without
+    FastAPI; this shim is the only place the two layers meet.
+    """
+    origin = (websocket.headers.get("origin") or "").strip()
+    allowed = _allowed_ws_origins(getattr(websocket.app.state, "settings", None))
+    if origin and allowed and origin not in allowed:
+        # Same-origin dev pages (Next.js on :3000, the service itself on
+        # :8420) pass; anything else is refused pre-accept. Non-browser
+        # producers (the capture agent, tests) send no Origin and pass.
+        # Wildcard (empty frozenset) passes every Origin in network mode.
+        await websocket.close(
+            code=1008, reason=f"origin {origin!r} not allowed for telemetry ingest"
+        )
+        return
+    query = websocket.query_params
+    learner_id = query.get("learner_id", "")
+    task_id = query.get("task_id", "")
+    if not learner_id or not task_id:
+        # Reject BEFORE accept: closing the pre-accept handshake is the
+        # cheapest denial and unambiguous for the stdlib capture agent.
+        await websocket.close(code=1008, reason="learner_id/task_id query params required")
+        return
+    # v0.4.7 (P1): HMAC ingest token. The socket is a grading input; in
+    # network mode it is LAN-reachable and identity params were self-
+    # asserted — anyone could poison/flood a learner's trace (grading DoS).
+    # The manager bakes mint tokens into NC_INGEST_URL; verify here. The
+    # token binds (learner_id, task_id, sandbox_id) to the process secret.
+    token = query.get("token", "")
+    verifier: IngestToken | None = getattr(websocket.app.state, "ingest_token", None)
+    if verifier is None or not verifier.verify(
+        token, learner_id, task_id, query.get("sandbox_id", "")
+    ):
+        await websocket.close(
+            code=1008, reason="missing or invalid ingest token"
+        )
+        return
+    await telemetry_ingest_endpoint(
+        websocket=websocket,
+        learner_id=learner_id,
+        task_id=task_id,
+        sandbox_id=query.get("sandbox_id", ""),
+        store=websocket.app.state.trace_store,
+        integrity=websocket.app.state.trace_integrity,
+        settings=websocket.app.state.settings,
+    )
+
+
+# --- HTTP reads -----------------------------------------------------------------
+
+
+class TraceResponse(BaseModel):
+    """Ordered trace + integrity signal (G-4 reads incomplete/reason)."""
+
+    learner_id: str
+    task_id: str
+    events: list[TelemetryEvent]
+    incomplete: bool
+    integrity_reason: str | None
+
+
+class GapsResponse(BaseModel):
+    """Missing seqs + integrity signal."""
+
+    learner_id: str
+    task_id: str
+    gaps: list[int]
+    incomplete: bool
+    integrity_reason: str | None
+
+
+def _is_known_trace(
+    store: TraceStore, integrity: TraceIntegrityMap, learner_id: str, task_id: str
+) -> bool:
+    """Known = has stored events OR carries an integrity flag (a flooded trace
+    with zero rows must still be readable — Proctor needs the reason)."""
+    return (
+        store.latest_seq(learner_id, task_id) >= 0
+        or integrity.is_incomplete(learner_id, task_id)
+    )
+
+
+@router.get("/traces/{learner_id}/{task_id}", response_model=TraceResponse)
+async def get_trace(
+    learner_id: str,
+    task_id: str,
+    store: TraceStore = Depends(get_trace_store),
+    integrity: TraceIntegrityMap = Depends(get_trace_integrity),
+) -> TraceResponse:
+    if not _is_known_trace(store, integrity, learner_id, task_id):
+        raise HTTPException(
+            status_code=404, detail=f"unknown trace {learner_id!r}/{task_id!r}"
+        )
+    return TraceResponse(
+        learner_id=learner_id,
+        task_id=task_id,
+        events=store.get_trace(learner_id, task_id),
+        incomplete=integrity.is_incomplete(learner_id, task_id),
+        integrity_reason=integrity.reason(learner_id, task_id),
+    )
+
+
+@router.get("/gaps/{learner_id}/{task_id}", response_model=GapsResponse)
+async def get_gaps(
+    learner_id: str,
+    task_id: str,
+    store: TraceStore = Depends(get_trace_store),
+    integrity: TraceIntegrityMap = Depends(get_trace_integrity),
+) -> GapsResponse:
+    if not _is_known_trace(store, integrity, learner_id, task_id):
+        raise HTTPException(
+            status_code=404, detail=f"unknown trace {learner_id!r}/{task_id!r}"
+        )
+    return GapsResponse(
+        learner_id=learner_id,
+        task_id=task_id,
+        gaps=store.gaps(learner_id, task_id),
+        incomplete=integrity.is_incomplete(learner_id, task_id),
+        integrity_reason=integrity.reason(learner_id, task_id),
+    )

apps/ai-service/ai_service/api/variants.py

@@ -0,0 +1,216 @@
+"""/v1/variants — seeded per-learner task variant endpoints (REQ-3-005, D-029).
+
+Three faces over the variant engine (the generator + store stay FastAPI-free;
+this module owns all HTTP wiring — the D-027/D-032 house pattern):
+
+    POST /v1/variants {learner_id, template_id | competency_id}
+        → 200 the learner's variant — GENERATED on the first request,
+          CACHED (store read, zero LLM calls) on every repeat: D-029
+          reproducibility means one (learner_id, template_id) is ONE
+          variant forever, so a regenerate is always a 200 of the SAME
+          variant, never a second render.
+        → 404 unknown template_id, or competency_id with no bound template.
+        → 422 neither template_id nor competency_id given.
+    GET  /v1/variants/{task_id}
+        → 200 the stored variant owning the task key (the grading and
+          telemetry join path); 404 when no variant was ever generated
+          for the task.
+    GET  /v1/variants?learner_id=...
+        → 200 the learner's variants, chronological; [] when none.
+
+Template resolution: an explicit `template_id` wins; without it the FIRST
+template bound to `competency_id` is used (`template_for_competency`,
+D-021 corpus alignment). The response carries `competency_id` resolved
+from the template library at read time — an enrichment, not a persisted
+column (the seed re-derives the whole variant, D-029) — so the learner
+surface can bind a variant to its competency without a library round-trip.
+
+Distinctness (REQ-3-005): different learners on the same template draw
+different seeded params and receive distinct statements and task_ids;
+tests/api/test_variants.py asserts this end-to-end through the API.
+"""
+
+from datetime import datetime
+from typing import Self
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field, model_validator
+
+from ..config import Settings
+from ..identity.store import IdentityStore
+from ..variants.generator import VariantGenerator
+from ..variants.store import VariantRecord, VariantStore
+from ..variants.templates import TaskTemplate, get_template, template_for_competency
+from .deps import get_settings, get_variant_generator, get_variant_store
+from .identity import require_verified_age
+
+
+def _identity_store(request: Request) -> IdentityStore:
+    return request.app.state.identity_store
+
+
+def _enforce_allowlist(learner_id: str, settings: Settings) -> None:
+    """G-5 pilot guard — allowlist runs FIRST in the composition (D-043)."""
+    if learner_id not in settings.learner_allowlist:
+        raise HTTPException(
+            status_code=403,
+            detail=f"learner_id {learner_id!r} is not on the sandbox allowlist (G-5)",
+        )
+
+router = APIRouter(prefix="/v1/variants", tags=["variants"])
+
+
+# -- contracts ------------------------------------------------------------------
+
+
+class VariantGenerateRequest(BaseModel):
+    """One variant identity: an explicit `template_id`, or the first
+    template bound to a `competency_id` (D-021). `template_id` wins when
+    both are given (explicit identity beats derived); at least one is
+    required — 422 otherwise.
+    """
+
+    learner_id: str = Field(min_length=1)
+    template_id: str | None = None
+    competency_id: str | None = None
+
+    @model_validator(mode="after")
+    def _require_template_or_competency(self) -> Self:
+        if self.template_id is None and self.competency_id is None:
+            raise ValueError("template_id or competency_id is required")
+        return self
+
+
+class VariantResponse(BaseModel):
+    """VariantRecord over HTTP, plus the `competency_id` enrichment.
+
+    Every field except `competency_id` mirrors `VariantRecord` exactly
+    (snake_case; `created_at` is an ISO 8601 UTC datetime) — the wire shape
+    typed as `TaskVariant` in packages/types/variants.ts.
+    """
+
+    learner_id: str
+    task_id: str
+    template_id: str
+    competency_id: str
+    seed: str
+    params: dict[str, str | int]
+    statement: str
+    starter_files: dict[str, str]
+    #: REQ-5-005 (a-11): REQUIRED on the wire — always emitted.
+    environment: str
+    test_command: str
+    created_at: datetime
+
+
+class VariantListResponse(BaseModel):
+    variants: list[VariantResponse]
+
+
+# -- resolution + rendering -----------------------------------------------------
+
+
+def _resolve_template(body: VariantGenerateRequest) -> TaskTemplate:
+    """Template for the request: the explicit id, else the first template
+    bound to the competency; 404 when neither resolves."""
+    if body.template_id is not None:
+        template = get_template(body.template_id)
+        if template is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"no task template with id {body.template_id!r}",
+            )
+        return template
+    # The request validator guarantees the disjunction, so reaching here
+    # means a competency_id was given (never None).
+    assert body.competency_id is not None
+    templates = template_for_competency(body.competency_id)
+    if not templates:
+        raise HTTPException(
+            status_code=404,
+            detail=f"no task template for competency {body.competency_id!r}",
+        )
+    return templates[0]
+
+
+def _competency_for(template_id: str) -> str:
+    """competency_id enrichment for stored records (read paths)."""
+    template = get_template(template_id)
+    if template is None:
+        # Integrity guard: a stored variant referencing a template that is
+        # no longer in the library cannot be enriched; fail loudly rather
+        # than fabricate a competency binding.
+        raise HTTPException(
+            status_code=500,
+            detail=f"stored variant references unknown template {template_id!r}",
+        )
+    return template.competency_id
+
+
+def _to_response(record: VariantRecord, competency_id: str) -> VariantResponse:
+    return VariantResponse(
+        learner_id=record.learner_id,
+        task_id=record.task_id,
+        template_id=record.template_id,
+        competency_id=competency_id,
+        seed=record.seed,
+        params=dict(record.params),
+        statement=record.statement,
+        starter_files=dict(record.starter_files),
+        # a-11: REQUIRED on the wire — the server always emits both (v0.5).
+        environment=record.environment or "build",
+        test_command=record.test_command or "pytest -q",
+        created_at=record.created_at,
+    )
+
+
+# -- endpoints ------------------------------------------------------------------
+
+
+@router.post("", response_model=VariantResponse)
+async def generate_variant(
+    body: VariantGenerateRequest,
+    request: Request,
+    generator: VariantGenerator = Depends(get_variant_generator),
+    settings: Settings = Depends(get_settings),
+) -> VariantResponse:
+    """The learner's variant for the resolved template — generated on the
+    first request, cached (no LLM call) on every repeat: D-029 makes a
+    regenerate a 200 of the SAME stored variant.
+
+    v0.5 identity gate (D-043, REQ-5-004): the school floor is 16+ verified.
+    Composition order: G-5 allowlist (403) → identity verdict (403 + CTA).
+    """
+    _enforce_allowlist(body.learner_id, settings)
+    await require_verified_age(16, body.learner_id, _identity_store(request))
+    template = _resolve_template(body)
+    record = await generator.generate(body.learner_id, template.id)
+    return _to_response(record, competency_id=template.competency_id)
+
+
+@router.get("", response_model=VariantListResponse)
+async def list_variants(
+    learner_id: str,
+    store: VariantStore = Depends(get_variant_store),
+) -> VariantListResponse:
+    """All stored variants for the learner, chronological; [] when none."""
+    variants = [
+        _to_response(record, competency_id=_competency_for(record.template_id))
+        for record in store.list_for_learner(learner_id)
+    ]
+    return VariantListResponse(variants=variants)
+
+
+@router.get("/{task_id}", response_model=VariantResponse)
+async def get_variant(
+    task_id: str,
+    store: VariantStore = Depends(get_variant_store),
+) -> VariantResponse:
+    """The stored variant owning the task key — the grading and telemetry
+    join path; 404 when no variant was ever generated for the task."""
+    record = store.get_by_task(task_id)
+    if record is None:
+        raise HTTPException(
+            status_code=404, detail=f"no stored variant for task {task_id!r}"
+        )
+    return _to_response(record, competency_id=_competency_for(record.template_id))

apps/ai-service/ai_service/config.py

@@ -1,14 +1,24 @@
 """Service settings — pydantic-settings, env prefix AI_, .env support."""
 
+import logging
 from pathlib import Path
 from typing import Annotated
 
-from pydantic import field_validator
+from pydantic import SecretStr, field_validator
 from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
 
 # apps/ai-service/  (sandbox dir default is relative to the app, not the CWD)
 _SERVICE_ROOT = Path(__file__).resolve().parent.parent
 
+# v0.3.6: durable runtime state lives OUTSIDE the repo (founder directive —
+# the repo is a git tree, not a data dir; old defaults under apps/ai-service/
+# polluted the working copy). ~/.nextcraft is the state root for DB + sandbox
+# workdirs; env overrides may use ~/ paths (expanded by the validator below).
+_STATE_ROOT = Path.home() / ".nextcraft"
+
+# G-16: TTS response-format whitelist (feeds the TTS route's Content-Type).
+_TTS_FORMATS = ("mp3", "wav", "opus")
+
 
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(env_prefix="AI_", env_file=".env", extra="ignore")
@@ -26,7 +36,7 @@ class Settings(BaseSettings):
 
     # v0.3 sandbox fabric (REQ-3-001): root holding per-sandbox workdirs.
     # Relative paths resolve against the app dir (apps/ai-service/), not the CWD.
-    sandbox_dir: Path = _SERVICE_ROOT / "sandboxes"
+    sandbox_dir: Path = _STATE_ROOT / "sandboxes"
 
     # D-032: single-box capacity, no queue — pool full → API maps to 503.
     sandbox_max_concurrent: int = 5
@@ -63,4 +73,143 @@ class Settings(BaseSettings):
         return value
 
     # D-027: SQLite path for telemetry/grades/variants/defenses stores.
-    db_path: Path = _SERVICE_ROOT / "ai_service" / "data" / "nextcraft.db"
+    # v0.3.6: default moved out of the repo to the home state root.
+    db_path: Path = _STATE_ROOT / "data" / "nextcraft.db"
+
+    # v0.3.6 single-port deploy: directory of the exported Next.js app
+    # (apps/web/out). When set, the app serves it at / (StaticFiles) so the
+    # whole site — UI + API — answers on one port behind HAProxy; the web
+    # build bakes NEXT_PUBLIC_AI_SERVICE_URL=self (relative same-origin
+    # fetches). Empty default → no mount; dev/tests unchanged.
+    web_static_dir: Path = Path("")
+
+    @field_validator("db_path", "sandbox_dir", "web_static_dir", mode="before")
+    @classmethod
+    def _expanduser_paths(cls, value: object) -> object:
+        # Env-set paths may use ~ (e.g. AI_DB_PATH=~/.nextcraft/x.db);
+        # pydantic Path does not expand it natively.
+        if isinstance(value, str):
+            return Path(value).expanduser()
+        return value
+
+    @field_validator("voice_tts_format")
+    @classmethod
+    def _validate_tts_format(cls, value: str) -> str:
+        # G-16 + G-11 consistency: unknown values NEVER crash the boot —
+        # fall back to the default with a loud warning (the boot-survival
+        # log lives in main.py's voice fallback; this validator normalizes).
+        v = value.strip().lower()
+        if v not in _TTS_FORMATS:
+            logging.getLogger(__name__).warning(
+                "AI_VOICE_TTS_FORMAT=%r is not one of %s — falling back to 'mp3'",
+                value,
+                _TTS_FORMATS,
+            )
+            return "mp3"
+        return v
+
+    # G-3 flood control (NOT backpressure-by-silence): max events ingested per
+    # (learner_id, task_id) trace before the WS endpoint closes the connection
+    # with 1008 and marks the trace INCOMPLETE_FLOODED. Drop-oldest is
+    # FORBIDDEN — it corrupts grading input (GRILL G-3).
+    telemetry_max_events_per_task: int = 50000
+
+    # Sandbox telemetry wiring (REQ-3-003): loopback host the in-sandbox capture
+    # agent dials to reach this service's WS ingest (the agent joins the sandbox
+    # mount ns but NOT the net ns — exec namespaces are offline, so the agent
+    # shares the host network and reaches the app over loopback). Port reuses
+    # `port` (A-004); only the host is configurable — never a second port.
+    telemetry_ingest_host: str = "127.0.0.1"
+
+    # v0.4.7 (P1, final-review flag): HMAC secret for WS ingest tokens. The
+    # ingest socket is reachable on the LAN in network mode; without a token
+    # check anyone could dial with arbitrary learner_id/task_id and poison or
+    # flood traces (grading DoS). The manager bakes an HMAC of
+    # (learner_id, task_id, sandbox_id) into NC_INGEST_URL; the WS endpoint
+    # verifies it. Unset → per-boot random secret (in-process mint/verify
+    # agree; restart invalidates stale URLs — sandboxes are not reboot-
+    # persistent, so that is harmless). Env-set for multi-process deploys.
+    telemetry_ingest_secret: str = ""
+
+    # v0.3.5 network mode (D-038): dev.sh binds 0.0.0.0 so remote browsers can
+    # reach the stack; '*' (default) lets any origin call the API (safe ONLY
+    # because credentials are never enabled — A-008). Set a comma-separated
+    # origin list (e.g. 'http://nextcraft-1:3000') to restrict instead.
+    # NOTE (v0.3.6): with the UI served same-origin from 8420 this is moot in
+    # production (same-origin requests skip CORS); it stays for the two-port
+    # dev topology.
+    cors_origins: str = "*"
+
+    @property
+    def cors_origin_list(self) -> list[str]:
+        value = self.cors_origins.strip()
+        if value == "*":
+            return ["*"]
+        return [o.strip() for o in value.split(",") if o.strip()]
+
+    # Identity provider selection (REQ-5-003, A-303): 'mock' (default —
+    # deterministic, no vendor spend pre-pilot; verdicts carry mock=True
+    # forever per A-304). A real KYC vendor drops in via the
+    # IdentityProvider protocol without API changes.
+    identity_provider: str = "mock"
+    # G-13: identity submit caps — one active pending per learner (409 on
+    # resubmit) and a per-learner submit rate ceiling.
+    identity_submits_per_min: int = 3
+
+    # v0.6 marketplace (REQ-6-001, D-057): the founder/admin surface is
+    # guarded by a shared secret — X-Admin-Token or Authorization: Bearer
+    # compared via secrets.compare_digest (G-108). Env-only (D-014), never
+    # logged; SecretStr keeps it out of accidental repr/logs. UNSET =
+    # every /v1/marketplace/admin/* route 403s — fail closed, NEVER open
+    # (a loud boot warning names the fix, G-11).
+    admin_token: SecretStr = SecretStr("")
+
+    # v0.6 P5 placeholder (D-056): the deployed origin for sitemap.xml /
+    # robots.txt absolute URLs (consumed by the SEO phase; documented
+    # now so operators see it beside the admin token).
+    public_base_url: str = ""
+
+    # Embedding provider selection (REQ-6-003, D-051): 'mock' (default —
+    # deterministic 256-dim feature-hash, pure stdlib; tests never call
+    # a real embeddings API) or 'openai-embed' (real embeddings against
+    # an OpenAI-compatible endpoint). openai-embed requires
+    # embed_base_url + embed_api_key + embed_model; when unconfigured the
+    # lifespan falls back to mock with a loud log (G-11 — a typo'd env
+    # must never crash the unattended boot).
+    embed_provider: str = "mock"
+
+    # Real embeddings (D-051, probe-corrected): ollama-cloud does NOT
+    # expose /embeddings — point AI_EMBED_BASE_URL at another
+    # OpenAI-compatible endpoint (e.g. LOCAL ollama at :11434/v1, or any
+    # embeddings cloud). Keys env-only, never committed, never logged
+    # (SecretStr; mirrors the admin token).
+    embed_base_url: str = ""
+    embed_api_key: SecretStr = SecretStr("")
+    embed_model: str = ""
+
+    # Voice provider selection (REQ-5-001, D-040): 'mock' (default — the
+    # no-key path is first-class; tests never call a real voice API),
+    # 'browser' (client-native SR/TTS; the descriptor tells the web client),
+    # or 'openai-audio' (real server STT/TTS against an OpenAI-compatible
+    # audio endpoint). openai-audio requires voice_base_url + voice_api_key;
+    # when unconfigured the lifespan falls back to mock with a loud log
+    # (G-11 — a typo'd env must never crash the unattended boot).
+    voice_provider: str = "mock"
+
+    # Real server voice (D-040, A-301): endpoint-agnostic by config (D-014
+    # pattern) — any OpenAI-compatible audio API works. Keys env-only,
+    # never committed, never logged (mirrors ollama_cloud_api_key).
+    voice_base_url: str = ""
+    voice_api_key: str = ""
+    voice_stt_model: str = "whisper-1"
+    voice_tts_model: str = "tts-1"
+    voice_tts_voice: str = "alloy"
+    # G-16: whitelist, not free string — this feeds the TTS route's
+    # Content-Type. A str + mode-after validator (NOT a pydantic Literal):
+    # a Literal would raise ValidationError at Settings construction, before
+    # main.py's G-11 fallback could catch it — crashing the unattended boot
+    # on a typo'd env. Invalid values fall back to the default LOUDLY.
+    voice_tts_format: str = "mp3"
+    # A-302/D-041: upload guard before the provider call (webm/opus is
+    # ~0.5-1MB/min, so 10MB tolerates very long answers).
+    voice_max_audio_mb: int = 10

apps/ai-service/ai_service/corpus/artifacts.py

@@ -1,8 +1,15 @@
 """Pre-baked artifacts + rubrics + defense transcripts — Assessor mock inputs (REQ-2-008).
 
-Counterpart: packages/mock-data/ai-scenarios.ts (artifact IDs string-identical,
-D-021). Real process-trace grading is a v0.3+ engine (assessment engine);
-these pre-baked submissions stand in for artifact + defense evaluation.
+v0.2 mock engine inputs (pre-baked artifacts/rubrics/transcripts) — DORMANT as of v0.3 re-
+grounding (Task 6-1-04): no production code path imports this module. Retained as Phase-3
+calibration history.
+
+
+Historical note: artifact IDs were once string-synced with a TS counterpart
+(packages/mock-data/ai-scenarios.ts, D-021) — that module was deleted in
+v0.7 P4 (dead export); this corpus is the single source. Real process-trace
+grading is a v0.3+ engine (assessment engine); these pre-baked submissions
+stand in for artifact + defense evaluation.
 """
 
 from pydantic import BaseModel

apps/ai-service/ai_service/corpus/telemetry.py

@@ -1,8 +1,15 @@
 """Simulated sandbox telemetry corpus — Lab agent mock engine inputs (REQ-2-007).
 
-Counterpart: packages/mock-data/ai-scenarios.ts (scenario IDs string-identical,
-D-021). Real sandbox telemetry is a v0.3+ engine (sandbox fabric); these
-scripted event streams stand in for the build-session process trace.
+v0.2 mock engine inputs (Lab/Proctor scenarios) — DORMANT as of v0.3 re-grounding (Task 6-1-04):
+no production code path imports this module. Retained as Phase-3 calibration history
+(corpus/trace_fixtures.py references it from TESTS only).
+
+
+Historical note: scenario IDs were once string-synced with a TS counterpart
+(packages/mock-data/ai-scenarios.ts, D-021) — that module was deleted in
+v0.7 P4 (dead export); this corpus is the single source. Real sandbox
+telemetry is a v0.3+ engine (sandbox fabric); these scripted event streams
+stand in for the build-session process trace.
 """
 
 from pydantic import BaseModel

apps/ai-service/ai_service/corpus/trace_fixtures.py

@@ -0,0 +1,230 @@
+"""Synthetic trace fixtures for grading calibration (Task 3-2-02, REQ-3-004).
+
+Three builder archetypes as REAL `TelemetryEvent` traces (the grading
+engine's native input — these are NOT the v0.2 corpus's simplified
+`{timestamp, kind, detail}` event shapes):
+
+    strong builder     — iterative debugging: small edits, tests early,
+                          failed runs closed by targeted fixes, eventual pass.
+    lazy builder       — one large paste, a single late test run, pass.
+                          (v0.2 alignment: the `lab-scenario-flagged` paste-
+                          and-run archetype; D-021.)
+    struggling builder — many edit/test cycles, failures never close,
+                          never reaches a pass.
+
+ID convention (D-021 alignment, documented in each fixture):
+v0.2 corpus scenario IDs are `<domain>-scenario-<slug>` (`lab-scenario-strong`,
+`lab-scenario-struggling`, `lab-scenario-flagged`, `proctor-scenario-*` — see
+corpus/telemetry.py). Grading fixtures carry ids string-aligned to that
+convention:
+
+    fixture id = "<scenario id>::<archetype>-trace"
+    learner id = "learner-003" (a member of the corpus learner-00N id space;
+                                 learner-001/002 exist in learner_context.py)
+
+so a fixture is greppable against its v0.2 scenario counterpart while staying
+a distinct id space (a grading trace is a real event stream, not the v0.2
+mock scenario timeline — same convention, richer event kind set).
+
+Instance hygiene: fixtures store event SPECS (plain tuples) and materialize
+FRESH `TelemetryEvent` instances on every `fixture.events` access. SQLModel
+rows carry SQLAlchemy instance state once a session has flushed them —
+re-adding the SAME instance to another store is a silent no-op, which would
+poison sequential test runs (a fixture ingested by test N would vanish for
+test N+1). Materializing per access keeps every consumer independent.
+
+These fixtures exist for the CALIBRATION CONTRACT (tests/grading/
+test_calibration.py): the mock provider scripts archetype-mapped scores and
+the test asserts the ORDERING the rubric must eventually enforce. They are
+NOT an LLM quality benchmark — see the test module docstring for the honest
+scope statement.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Final
+
+from pydantic import BaseModel, Field
+
+from ..telemetry.models import TelemetryEvent
+
+_T0: Final = datetime(2026, 9, 12, 0, 0, 0, tzinfo=UTC)
+
+#: Event spec: (seq, kind, payload, seconds-since-session-start).
+EventSpec = tuple[int, str, dict, float]
+
+
+class TraceFixture(BaseModel):
+    """One named synthetic trace + its v0.2 scenario alignment (D-021).
+
+    `event_specs` is the durable, session-state-free description; `events`
+    materializes fresh TelemetryEvent rows from it on every access.
+    """
+
+    model_config = {"frozen": True}
+
+    fixture_id: str  # "<v0.2 scenario id>::<archetype>-trace"
+    archetype: str  # "strong" | "lazy" | "struggling"
+    aligned_scenario_id: str  # the v0.2 corpus scenario this fixture mirrors
+    competency_id: str  # corpus competency id space (stack-orchestration-c00N)
+    task_id: str  # trace task id (grading operates on (learner, task))
+    learner_id: str
+    event_specs: tuple[EventSpec, ...] = Field(default=())
+
+    @property
+    def events(self) -> list[TelemetryEvent]:
+        """FRESH TelemetryEvent instances — safe to ingest into any store.
+
+        Never cache these: an instance flushed by one SQLite session
+        carries persistent identity, and re-appending it elsewhere no-ops.
+        """
+        return [
+            TelemetryEvent(
+                learner_id=self.learner_id,
+                task_id=self.task_id,
+                seq=seq,
+                kind=kind,
+                payload=payload,
+                ts=_T0 + timedelta(seconds=offset_s),
+                sandbox_id="sbx-calibration",
+            )
+            for seq, kind, payload, offset_s in self.event_specs
+        ]
+
+    def description(self) -> str:
+        return (
+            f"{self.fixture_id} (archetype={self.archetype}, aligned="
+            f"{self.aligned_scenario_id}, competency={self.competency_id})"
+        )
+
+
+class _Builder:
+    """Seq-accurate event-spec builder for one (learner, task) pair."""
+
+    def __init__(self) -> None:
+        self.specs: list[EventSpec] = []
+        self._seq = 0
+
+    def add(self, kind: str, payload: dict | None, at: float) -> None:
+        self.specs.append((self._seq, kind, payload or {}, at))
+        self._seq += 1
+
+
+def _strong_builder_specs() -> list[EventSpec]:
+    """Iterative debugging: tests early, tight edit→test loops, eventual pass.
+
+    Mirrors `lab-scenario-strong` (v0.2: keystrokes → file_save → run_tests →
+    test_pass, c002) at full telemetry fidelity — every failed cycle is
+    closed by a targeted edit followed by a re-run that passes.
+    """
+    b = _Builder()
+    b.add("activity", {"state": "starting"}, 0)
+    b.add("file_diff", {"path": "planner.py", "added": 14}, 95)        # small edit
+    b.add("command", {"cmd": "pytest -q tests/test_planner.py"}, 120)  # tests EARLY
+    b.add("test_result", {"passed": True, "exit_code": 0}, 126)
+    b.add("file_diff", {"path": "tool_node.py", "added": 22}, 180)
+    b.add("command", {"cmd": "pytest -q"}, 275)
+    b.add("test_result", {"passed": False, "exit_code": 1}, 281)      # honest failure
+    b.add("file_diff", {"path": "tool_node.py", "added": 6, "removed": 2}, 340)  # targeted fix
+    b.add("command", {"cmd": "pytest -q"}, 430)
+    b.add("test_result", {"passed": True, "exit_code": 0}, 436)       # cycle CLOSED
+    b.add("command", {"cmd": "git commit -m 'tool node with retries'"}, 500)
+    return b.specs
+
+
+def _lazy_builder_specs() -> list[EventSpec]:
+    """Paste-and-run: one large paste, a single LATE test run, instant pass.
+
+    Mirrors `lab-scenario-flagged` (v0.2: paste of 2,400 chars → run_tests →
+    instant 6/6 pass, c003) at full telemetry fidelity — zero iteration, zero
+    verification during construction, one terminal test run only.
+    """
+    b = _Builder()
+    b.add("activity", {"state": "starting"}, 0)
+    b.add("file_diff", {"path": "eval.py", "added": 240, "removed": 0}, 30)  # one bulk paste
+    b.add("file_diff", {"path": "README.md", "added": 12}, 40)
+    b.add("command", {"cmd": "npm run build"}, 45)
+    b.add("run_result", {"exit_code": 0, "ok": True}, 60)
+    b.add("command", {"cmd": "pytest -q"}, 520)                       # single LATE test run
+    b.add("test_result", {"passed": True, "exit_code": 0}, 540)        # instant pass
+    return b.specs
+
+
+def _struggling_builder_specs() -> list[EventSpec]:
+    """Many cycles, none close: repeated failures, no eventual pass.
+
+    Mirrors `lab-scenario-struggling` (v0.2: repeated identical ImportErrors,
+    idle gaps, no checkpoint, c002) at full telemetry fidelity — edits happen
+    between failures, but the same failure recurs; no pass is ever reached.
+    """
+    b = _Builder()
+    b.add("activity", {"state": "starting"}, 0)
+    b.add("file_diff", {"path": "main.py", "added": 40}, 20)
+    b.add("command", {"cmd": "pytest -q"}, 210)
+    b.add("test_result", {"passed": False, "exit_code": 1}, 215)     # ImportError
+    b.add("file_diff", {"path": "main.py", "added": 8, "removed": 3}, 300)
+    b.add("command", {"cmd": "pytest -q"}, 520)
+    b.add("test_result", {"passed": False, "exit_code": 1}, 525)      # SAME error
+    b.add("file_diff", {"path": "main.py", "added": 5}, 610)
+    b.add("command", {"cmd": "pytest -q"}, 960)
+    b.add("test_result", {"passed": False, "exit_code": 1}, 965)     # STILL failing
+    b.add("activity", {"state": "idle"}, 1500)                       # long idle
+    b.add("activity", {"state": "idle"}, 2200)
+    return b.specs
+
+
+#: Calibration learner — a member of the corpus learner-00N id space (D-021;
+#: learner-001/002 live in corpus/learner_context.py; grading fixtures use
+#: a third id so calibration traces never collide with mock-context reads).
+CALIBRATION_LEARNER_ID: Final = "learner-003"
+
+
+STRONG_BUILDER: Final = TraceFixture(
+    fixture_id="lab-scenario-strong::strong-trace",
+    archetype="strong",
+    aligned_scenario_id="lab-scenario-strong",
+    competency_id="stack-orchestration-c002",
+    task_id="task-calibration-strong",
+    learner_id=CALIBRATION_LEARNER_ID,
+    event_specs=tuple(_strong_builder_specs()),
+)
+
+LAZY_BUILDER: Final = TraceFixture(
+    # v0.2's paste-and-run archetype is the "flagged" lab scenario (D-021):
+    # large paste → instant test pass. "lazy builder" is that behavior
+    # without the proctor flag; the alignment is behavioral, documented here.
+    fixture_id="lab-scenario-flagged::lazy-trace",
+    archetype="lazy",
+    aligned_scenario_id="lab-scenario-flagged",
+    competency_id="stack-orchestration-c003",
+    task_id="task-calibration-lazy",
+    learner_id=CALIBRATION_LEARNER_ID,
+    event_specs=tuple(_lazy_builder_specs()),
+)
+
+STRUGGLING_BUILDER: Final = TraceFixture(
+    fixture_id="lab-scenario-struggling::struggling-trace",
+    archetype="struggling",
+    aligned_scenario_id="lab-scenario-struggling",
+    competency_id="stack-orchestration-c002",
+    task_id="task-calibration-struggling",
+    learner_id=CALIBRATION_LEARNER_ID,
+    event_specs=tuple(_struggling_builder_specs()),
+)
+
+TRACE_FIXTURES: Final[dict[str, TraceFixture]] = {
+    f.fixture_id: f
+    for f in (STRONG_BUILDER, LAZY_BUILDER, STRUGGLING_BUILDER)
+}
+
+
+def get_trace_fixture(fixture_id: str) -> TraceFixture | None:
+    return TRACE_FIXTURES.get(fixture_id)
+
+
+def digest_of(fixture: TraceFixture):
+    """Compute the digest for a fixture (pure compute; test-side helper)."""
+    from ..grading.features import compute_digest
+
+    return compute_digest(fixture.events)

apps/ai-service/ai_service/grading/__init__.py

@@ -0,0 +1,27 @@
+"""Process-trace grading — trace digest, rubric engine, GradeStore (REQ-3-004).
+
+Boundary rule (D-027): grading/ is an engine module — it never imports
+api/; the single sanctioned agents/ dependency is the shared D-020
+structured defense (agents/structured.py), imported module-direct in
+engine.py (see its docstring for why). features.py imports telemetry/;
+store.py imports config only; engine.py composes llm/ + telemetry/ +
+prompts/ + agents.structured.
+
+Wave status: features.py (TraceDigest, compute_digest) + store.py
+(GradeRecord, GradeStore, SQLiteGradeStore) landed in Wave 1 (3-1-01 +
+3-1-02); engine.py (GradingEngine, RubricScore) is Wave 2 (3-2-01).
+"""
+
+from .engine import GradingEngine, RubricScore
+from .features import TraceDigest, compute_digest
+from .store import GradeRecord, GradeStore, SQLiteGradeStore
+
+__all__ = [
+    "GradeRecord",
+    "GradeStore",
+    "GradingEngine",
+    "RubricScore",
+    "SQLiteGradeStore",
+    "TraceDigest",
+    "compute_digest",
+]

apps/ai-service/ai_service/grading/engine.py

@@ -0,0 +1,313 @@
+"""GradingEngine — rubric scoring over real process traces (REQ-3-004).
+
+The Wave-2 composition of the grading stack:
+
+    trace completeness gate (G-4, FIRST — nothing is sent to any LLM
+    when the gate trips) → TraceStore.get_trace → compute_digest (D-028)
+    → prompts.grading.render_trace_digest → D-020 4-layer structured
+    defense (agents/structured.py — REUSED, composed, never duplicated)
+    → RubricScore validation → GradeStore persistence → GradeRecord.
+
+Gate verdicts are FIRST-CLASS RESULTS, not exceptions (G-4 is binding):
+    UNGRADABLE_TRACE_INCOMPLETE — seq gaps in the store OR the trace is
+        flagged by TraceIntegrityMap (INCOMPLETE_FLOODED). The gap list /
+        flag reason is surfaced in `scores` for API rendering, and the
+        record is PERSISTED like any grade so a learner sees why no
+        credential can be issued for this trace — the gate outcome is
+        durable and auditable, not a transient error string.
+    UNGRADABLE_EMPTY_TRACE      — no events stored for the pair.
+On either verdict `scores.criteria` is empty and the LLM is never called.
+
+DI (D-027/D-032 house pattern): the engine receives trace_store,
+grade_store, integrity and provider through the constructor and knows
+NOTHING of FastAPI — api/ composes it (Task 3-3-01). `model` is injected
+alongside the provider so tests script the mock against the production
+wiring without touching Settings.
+
+Boundary (D-027): grading/ imports llm/ (provider protocol + Message
+type), telemetry/ (store + integrity map), prompts/ (rubric text) and
+ONLY agents.structured — the sanctioned shared D-020 defense. We import
+the MODULE directly (`from ..agents.structured import structured_completion`)
+rather than the `agents` package, mirroring how agents/base.py consumes
+it (same direct-module import): that keeps the dependency surface to
+exactly the two names the engine needs (structured_completion,
+StructuredOutputError) and avoids executing agents/__init__ re-exports
+(BaseAgent, registry, session store) that grading has no business
+loading — a side-effect-hygiene choice that keeps this import line
+grep-auditable as "the one agents dependency". grading/ never imports api/.
+
+RubricScore placement (documented decision): the validated output model
+lives HERE, not in prompts/. The pydantic model is the engine's return
+CONTRACT (the shape GradeStore.scores must hold), while prompts/grading.py
+is pure prompt text + its mirror schema HINT string — the same split as
+agents/assessor.py (model + hint) but with the model owned by the engine
+module that validates it. Prompt files hold text, per the prompts/ house
+style; engine files hold typed contracts.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Final
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ..agents.structured import StructuredOutputError, structured_completion
+from ..llm.base import LLMProvider
+from ..llm.types import Message
+from ..prompts.grading import (
+    RUBRIC_CRITERIA,
+    RUBRIC_SCORE_SCHEMA_HINT,
+    SYSTEM_PROMPT,
+    render_trace_digest,
+)
+from ..telemetry.ingest import TraceIntegrityMap
+from ..telemetry.store import TraceStore
+from .features import compute_digest
+from .store import GradeRecord, GradeStore
+
+if TYPE_CHECKING:  # pragma: no cover - protocol-only import for the optional
+    from ..variants.store import VariantStore
+
+logger = logging.getLogger(__name__)
+
+#: First-class gate verdicts (G-4). GradeRecord.verdict values; non-empty
+#: by store contract. Rubric verdicts (mastered/developing/not_yet) ride in
+#: `scores.verdict` — `record.verdict` stays the machine-readable outcome.
+VERDICT_UNGRADABLE_INCOMPLETE: Final = "UNGRADABLE_TRACE_INCOMPLETE"
+VERDICT_UNGRADABLE_EMPTY: Final = "UNGRADABLE_EMPTY_TRACE"
+#: record.verdict for a successfully LLM-graded trace (the rubric verdict
+#: travels inside scores); keeps verdict non-empty for every persisted row.
+VERDICT_GRADED: Final = "GRADED"
+
+#: Gate-detail keys surfaced in GradeRecord.scores (tests assert on these).
+_INTEGRITY_FLAG_KEY: Final = "integrity_flag"
+
+
+def _anchors_context(variant) -> str:
+    """Render the variant template's difficulty anchors for the grader prompt.
+
+    Contains only the template id + anchor numbers — no learner-identifying
+    material (D-028 anonymity preserved; the digest-leak tests keep holding).
+    Lazy template import: grading must not import variants/ at module load
+    (variants/prompts import-cycle safety mirrors llm/ rules).
+    """
+    from ..variants.templates import get_template
+
+    template = get_template(variant.template_id)
+    if template is None:
+        return f"template={variant.template_id} (anchors unavailable)"
+    a = template.rubric_anchors
+    return (
+        f"template={template.id}; "
+        f"expected_edit_count_band={list(a.expected_edit_count_band)}; "
+        f"expected_min_test_runs={a.expected_min_test_runs}; "
+        f"expected_error_fix_cycles_band={list(a.expected_error_fix_cycles_band)}"
+    )
+_MISSING_SEQS_KEY: Final = "missing_seqs"
+
+
+class RubricScore(BaseModel):
+    """Validated LLM output: per-criterion 0-4 scores + strengths + gaps + verdict.
+
+    The D-020 schema for the grader: `structured_completion` parses the
+    model reply into THIS shape (layer 3), retrying once with the
+    validation error fed back (layer 4). Exact criteria set + 0-4 ranges
+    are enforced here, so the scores dict persisted to GradeStore is
+    always rubric-shaped no matter what the model produced.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    criteria: dict[str, int]
+    strengths: list[str] = Field(min_length=1, max_length=2)
+    gaps: list[str] = Field(min_length=1, max_length=2)
+    verdict: str  # "mastered" | "developing" | "not_yet"
+
+    @field_validator("criteria")
+    @classmethod
+    def _criteria_rubric_shaped(cls, value: dict[str, int]) -> dict[str, int]:
+        """Exact criteria keys (no extras, no omissions) and 0-4 scores."""
+        expected = set(RUBRIC_CRITERIA)
+        got = set(value)
+        if got != expected:
+            raise ValueError(
+                f"criteria keys must be exactly {sorted(expected)}, got {sorted(got)}"
+            )
+        for key, score in value.items():
+            if not 0 <= score <= 4:
+                raise ValueError(f"criterion {key!r} must be within 0-4, got {score}")
+        return value
+
+    @field_validator("verdict")
+    @classmethod
+    def _verdict_known(cls, value: str) -> str:
+        allowed = {"mastered", "developing", "not_yet"}
+        if value not in allowed:
+            raise ValueError(f"verdict must be one of {sorted(allowed)}, got {value!r}")
+        return value
+
+
+class GradingEngine:
+    """Scores a (learner_id, task_id) trace into a persisted GradeRecord."""
+
+    def __init__(
+        self,
+        trace_store: TraceStore,
+        grade_store: GradeStore,
+        integrity: TraceIntegrityMap,
+        provider: LLMProvider,
+        *,
+        model: str = "gemma4:31b",
+        variant_store: "VariantStore | None" = None,
+    ) -> None:
+        self._trace_store = trace_store
+        self._grade_store = grade_store
+        self._integrity = integrity
+        self._provider = provider
+        self._model = model
+        # Phase 4 (MH#4): optional variant lookup — when the graded task
+        # derives from a generated variant, its template's difficulty anchors
+        # ship to the grader prompt (same bar for every variant of the
+        # template, a-5) and the variant seed is stamped on the record.
+        # Optional so engine tests stay decoupled; main.py lifespan wires it.
+        self._variant_store = variant_store
+
+    async def grade(self, learner_id: str, task_id: str) -> GradeRecord:
+        """Grade one trace; persist latest-state (GradeStore upserts); return it.
+
+        Gate FIRST (G-4): the LLM is only ever reached from the fully
+        guarded path — no gate state can be masked by an LLM error.
+        """
+        record = await self._grade(learner_id, task_id)
+        self._grade_store.save(record)
+        return record
+
+    # ------------------------------------------------------------------ core
+
+    async def _grade(self, learner_id: str, task_id: str) -> GradeRecord:
+        # -- G-4 gate FIRST: integrity flag OR seq gaps. Ordering matters:
+        # gaps() returns [] for an EMPTY trace, so the empty check below is
+        # reachable only when no rows exist at all; a gapped or flooded
+        # trace can never fall through to the LLM path.
+        if self._integrity.is_incomplete(learner_id, task_id):
+            reason = self._integrity.reason(learner_id, task_id) or "unknown"
+            gaps = self._trace_store.gaps(learner_id, task_id)
+            logger.info(
+                "grade gate (G-4): %s/%s integrity-flagged (%s) — ungradable",
+                learner_id,
+                task_id,
+                reason,
+            )
+            return self._ungradable(
+                learner_id,
+                task_id,
+                detail={_INTEGRITY_FLAG_KEY: reason, _MISSING_SEQS_KEY: gaps},
+                verdict=VERDICT_UNGRADABLE_INCOMPLETE,
+            )
+        gaps = self._trace_store.gaps(learner_id, task_id)
+        if gaps:
+            logger.info(
+                "grade gate (G-4): %s/%s seq gaps %s — ungradable",
+                learner_id,
+                task_id,
+                gaps,
+            )
+            return self._ungradable(
+                learner_id,
+                task_id,
+                detail={_INTEGRITY_FLAG_KEY: None, _MISSING_SEQS_KEY: gaps},
+                verdict=VERDICT_UNGRADABLE_INCOMPLETE,
+            )
+
+        trace = self._trace_store.get_trace(learner_id, task_id)
+        if not trace:
+            logger.info(
+                "grade gate: %s/%s empty trace — ungradable", learner_id, task_id
+            )
+            return self._ungradable(
+                learner_id,
+                task_id,
+                detail={_INTEGRITY_FLAG_KEY: None, _MISSING_SEQS_KEY: []},
+                verdict=VERDICT_UNGRADABLE_EMPTY,
+            )
+
+        # -- Guarded path: digest (D-028) → prompt → D-020 4-layer defense.
+        digest = compute_digest(trace)
+        variant = self._lookup_variant(task_id)
+        anchors_context = (
+            _anchors_context(variant) if variant is not None else None
+        )
+        messages = [
+            Message(role="system", content=SYSTEM_PROMPT),
+            Message(
+                role="user",
+                content=render_trace_digest(digest, anchors_context=anchors_context),
+            ),
+        ]
+        try:
+            rubric = await structured_completion(
+                self._provider,
+                messages,
+                model=self._model,
+                schema=RubricScore,
+                schema_hint=RUBRIC_SCORE_SCHEMA_HINT,
+            )
+        except StructuredOutputError as exc:
+            # The trace was gradable but the model failed to produce valid
+            # JSON within the D-020 budget (two attempts). Raise — the API
+            # layer maps this to a 502 (assessor precedent). Persisting a
+            # fabricated or partial grade here would violate the no-silent-
+            # fallback rule: no credential-worthy record without a validated
+            # RubricScore.
+            raise StructuredOutputError(f"grading LLM failed for {task_id}: {exc}") from exc
+
+        logger.debug(
+            "graded %s/%s: %s (model=%s)",
+            learner_id,
+            task_id,
+            rubric.verdict,
+            self._model,
+        )
+        return GradeRecord(
+            learner_id=learner_id,
+            task_id=task_id,
+            variant_seed=variant.seed if variant is not None else None,  # D-029
+            digest=digest.model_dump(),
+            scores=rubric.model_dump(),
+            verdict=VERDICT_GRADED,
+            model=self._model,
+            created_at=datetime.now(tz=UTC),
+        )
+
+    def _lookup_variant(self, task_id: str):
+        """MH#4: resolve the graded task's variant (None when not variant-derived)."""
+        if self._variant_store is None:
+            return None
+        return self._variant_store.get_by_task(task_id)
+
+    # ------------------------------------------------------------ gate record
+
+    @staticmethod
+    def _ungradable(
+        learner_id: str,
+        task_id: str,
+        *,
+        detail: dict,
+        verdict: str,
+    ) -> GradeRecord:
+        """Build a gate record: no digest (nothing was graded), gate detail
+        surfaced in `scores` (the store allows an empty scores dict, but
+        G-4 requires the gap list / flag reason surfaced — the detail IS the
+        verdict's payload), model="none" (no LLM was involved; provenance
+        stays honest).
+        """
+        return GradeRecord(
+            learner_id=learner_id,
+            task_id=task_id,
+            variant_seed=None,
+            digest={},
+            scores=detail,
+            verdict=verdict,
+            model="none",
+            created_at=datetime.now(tz=UTC),
+        )

apps/ai-service/ai_service/grading/features.py

@@ -0,0 +1,246 @@
+"""Deterministic process-trace digest (D-028, REQ-3-004).
+
+Pure compute — no LLM, no I/O. `compute_digest` reduces an ordered
+TelemetryEvent trace to a compact, bounded `TraceDigest` that is safe to
+embed in a grading prompt:
+
+- FIXED fields + small histograms only; NO raw commands, NO file contents,
+  NO payloads — the raw trace NEVER reaches the LLM (D-028), which also
+  bounds the prompt-injection surface.
+- Tolerant to both live trace mixes: daemon-topology traces carry
+  `activity` + `file_diff` kinds (workspace watcher), while REPL-driven
+  traces carry `command`/`stdin`/`stdout`/`run_result`/`test_result`
+  (P2 verification P1). Features derive from whatever kinds are present and
+  never crash on absent kinds.
+
+Feature semantics (conservative, deterministic):
+- test pass/fail counts + final status derive from `test_result` payloads
+  when present, falling back to `run_result` exit codes (0 = pass).
+- an error/fix CYCLE = a failing run/test followed by >= 1 edit and then a
+  later run/test (pass or fail) — the next observed result closes the cycle.
+- idle gaps = wall-clock gaps between consecutive events exceeding
+  `idle_threshold_s` (default 120s): count + total seconds.
+- command category histogram classifies `command`-kind payloads: build /
+  test / file / nav / debug / other.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from pydantic import BaseModel, Field
+
+from ..telemetry.models import TelemetryEvent
+
+_IDLE_DEFAULT_S: float = 120.0
+
+_TEST_HINTS = ("test", "pytest", "vitest", "jest", "mocha", "unittest", "go test", "npm test")
+_BUILD_HINTS = ("make", "npm run build", "pip install", "pnpm", "cargo build", "gcc", "tsc")
+_DEBUG_HINTS = ("gdb", "pdb", "print(", "debug", "strace", "ltrace", "curl", "ping")
+_NAV_HINTS = ("ls", "cd", "pwd", "cat ", "grep ", "find", "rg ", "tree", "head", "tail", "less")
+_FILE_HINTS = ("mv ", "cp ", "rm ", "mkdir", "touch", "chmod", "nano", "vim", "sed -i", "tee ")
+
+
+class TraceDigest(BaseModel):
+    """Compact, bounded, LLM-safe summary of a process trace (D-028).
+
+    Fixed fields + small histograms. Serializes well under 4 KB; contains no
+    raw commands, file contents, or event payloads.
+    """
+
+    model_config = {"frozen": True}
+
+    event_count: int = Field(ge=0)
+    session_duration_s: float = Field(ge=0.0)
+    edit_count: int = Field(ge=0)
+    command_count: int = Field(ge=0)
+    run_count: int = Field(ge=0)
+    test_pass_count: int = Field(ge=0)
+    test_fail_count: int = Field(ge=0)
+    final_test_status: str = Field(pattern="^(pass|fail|none)$")
+    first_test_pass_offset_s: float | None = None
+    error_fix_cycles: int = Field(ge=0)
+    mean_fix_latency_s: float | None = None
+    idle_gap_count: int = Field(ge=0)
+    idle_gap_total_s: float = Field(ge=0.0)
+    command_categories: dict[str, int] = Field(default_factory=dict)
+    kind_histogram: dict[str, int] = Field(default_factory=dict)
+
+
+def _event_pass_status(event: TelemetryEvent) -> bool | None:
+    """True (pass) / False (fail) / None (not a result event) for one event."""
+    payload = event.payload or {}
+    if event.kind == "test_result":
+        if "passed" in payload:
+            return bool(payload["passed"])
+        if "exit_code" in payload:
+            return int(payload["exit_code"]) == 0
+        if "status" in payload:
+            return str(payload["status"]).lower() in ("pass", "passed", "ok", "success")
+        return None
+    if event.kind == "run_result":
+        if "exit_code" in payload:
+            return int(payload["exit_code"]) == 0
+        if "ok" in payload:
+            return bool(payload["ok"])
+        return None
+    return None
+
+
+def _classify_command(text: str) -> str:
+    lowered = text.lower()
+    if any(h in lowered for h in _TEST_HINTS):
+        return "test"
+    if any(h in lowered for h in _BUILD_HINTS):
+        return "build"
+    if any(h in lowered for h in _DEBUG_HINTS):
+        return "debug"
+    if any(h in lowered for h in _NAV_HINTS):
+        return "nav"
+    if any(h in lowered for h in _FILE_HINTS):
+        return "file"
+    return "other"
+
+
+def _command_text(event: TelemetryEvent) -> str:
+    payload = event.payload or {}
+    return str(payload.get("cmd") or payload.get("command") or payload.get("line") or "")
+
+
+def compute_digest(
+    trace: list[TelemetryEvent], *, idle_threshold_s: float = _IDLE_DEFAULT_S
+) -> TraceDigest:
+    """Reduce an ordered trace to a bounded digest. Never raises on odd input."""
+    events = sorted(trace, key=lambda e: (e.seq, e.ts))
+    if not events:
+        return TraceDigest(
+            event_count=0,
+            session_duration_s=0.0,
+            edit_count=0,
+            command_count=0,
+            run_count=0,
+            test_pass_count=0,
+            test_fail_count=0,
+            final_test_status="none",
+            first_test_pass_offset_s=None,
+            error_fix_cycles=0,
+            mean_fix_latency_s=None,
+            idle_gap_count=0,
+            idle_gap_total_s=0.0,
+            command_categories={},
+            kind_histogram={},
+        )
+
+    kind_histogram = Counter(e.kind for e in events)
+    start_ts = events[0].ts
+    end_ts = events[-1].ts
+    duration = max(0.0, (end_ts - start_ts).total_seconds())
+
+    edit_count = kind_histogram.get("file_diff", 0)
+    command_count = kind_histogram.get("command", 0)
+    run_count = kind_histogram.get("run_result", 0)
+
+    # Tests: prefer test_result events; fall back to run_result exit codes.
+    test_statuses: list[tuple[TelemetryEvent, bool]] = []
+    for e in events:
+        if e.kind == "test_result":
+            ok = _event_pass_status(e)
+            if ok is not None:
+                test_statuses.append((e, ok))
+    if not test_statuses:
+        for e in events:
+            if e.kind == "run_result":
+                ok = _event_pass_status(e)
+                if ok is not None:
+                    test_statuses.append((e, ok))
+
+    test_pass_count = sum(1 for _, ok in test_statuses if ok)
+    test_fail_count = len(test_statuses) - test_pass_count
+    if not test_statuses:
+        final_test_status = "none"
+    else:
+        final_test_status = "pass" if test_statuses[-1][1] else "fail"
+    first_pass = next((e for e, ok in test_statuses if ok), None)
+    first_pass_offset = (
+        max(0.0, (first_pass.ts - start_ts).total_seconds()) if first_pass is not None else None
+    )
+
+    # Error/fix cycles: a failing result starts a pending cycle; the NEXT
+    # observed result closes it (regardless of outcome) — a fix attempt that
+    # fails again is itself another iteration of debugging, so it closes the
+    # previous cycle and opens a new one. Edits since the fail mark the
+    # close as a genuine fix attempt; latency = first edit -> closing result.
+    cycles = 0
+    fix_latencies: list[float] = []
+    pending_fail_ts: float | None = None  # seconds since start
+    edits_since_fail = 0
+    first_edit_ts: float | None = None
+    for e in events:
+        t = max(0.0, (e.ts - start_ts).total_seconds())
+        if e.kind == "file_diff":
+            if pending_fail_ts is not None:
+                if edits_since_fail == 0:
+                    first_edit_ts = t
+                edits_since_fail += 1
+            continue
+        ok = _event_pass_status(e)
+        if ok is None:
+            continue
+        if ok is False:
+            if pending_fail_ts is not None and edits_since_fail > 0 and first_edit_ts is not None:
+                # failed fix attempt: closes the previous cycle, opens a new one
+                cycles += 1
+                fix_latencies.append(t - first_edit_ts)
+            pending_fail_ts = t
+            edits_since_fail = 0
+            first_edit_ts = None
+            continue
+        if ok is True and pending_fail_ts is not None:
+            if edits_since_fail > 0 and first_edit_ts is not None:
+                cycles += 1
+                fix_latencies.append(t - first_edit_ts)
+            pending_fail_ts = None
+            edits_since_fail = 0
+            first_edit_ts = None
+
+    mean_fix_latency = (
+        sum(fix_latencies) / len(fix_latencies) if fix_latencies else None
+    )
+
+    # Idle gaps between consecutive events.
+    idle_gap_count = 0
+    idle_gap_total = 0.0
+    prev_ts = None
+    for e in events:
+        if prev_ts is not None:
+            gap = (e.ts - prev_ts).total_seconds()
+            if gap > idle_threshold_s:
+                idle_gap_count += 1
+                idle_gap_total += gap
+        prev_ts = e.ts
+
+    # Command category histogram (command-kind events only).
+    categories: Counter[str] = Counter()
+    for e in events:
+        if e.kind == "command":
+            categories[_classify_command(_command_text(e))] += 1
+
+    return TraceDigest(
+        event_count=len(events),
+        session_duration_s=round(duration, 3),
+        edit_count=edit_count,
+        command_count=command_count,
+        run_count=run_count,
+        test_pass_count=test_pass_count,
+        test_fail_count=test_fail_count,
+        final_test_status=final_test_status,
+        first_test_pass_offset_s=(
+            round(first_pass_offset, 3) if first_pass_offset is not None else None
+        ),
+        error_fix_cycles=cycles,
+        mean_fix_latency_s=(round(mean_fix_latency, 3) if mean_fix_latency is not None else None),
+        idle_gap_count=idle_gap_count,
+        idle_gap_total_s=round(idle_gap_total, 3),
+        command_categories=dict(sorted(categories.items())),
+        kind_histogram=dict(sorted(kind_histogram.items())),
+    )

apps/ai-service/ai_service/grading/store.py

@@ -0,0 +1,239 @@
+"""GradeStore — grade persistence protocol + SQLite implementation (REQ-3-004, D-027).
+
+Postgres-migration-ready (D-027): the protocol is the only surface the
+grading engine and API layers touch; swapping SQLiteGradeStore for a
+Postgres-backed implementation must not change call sites. The
+`grade_record` table uses only portable column types (str / JSON /
+datetime), so the same SQLModel schema stands up unchanged on Postgres.
+
+Upsert, NOT append: (learner_id, task_id) is the grade identity — one row
+per learner per task holding the LATEST grade. `save` overwrites the whole
+row when the pair already exists, so a regrade replaces scores, verdict,
+created_at, digest, model and variant_seed wholesale. That is deliberately
+the opposite of TraceStore.append's dedup-keep-first contract: a trace is an
+append-only event log, a grade is latest-state, so the engine can re-grade
+a task idempotently as its rubric or input evolves.
+
+Concurrency (a-3): the engine enables WAL + synchronous=NORMAL and a busy
+timeout at connection time, so a regrade writer and API readers do not hit
+`database is locked` on the single-box pilot.
+
+`created_at` contract: callers stamp UTC (datetime.now(UTC)); SQLite stores
+it naive and the read paths re-label it tz-aware UTC (same boundary
+normalization as TelemetryEvent.ts, so the contract holds on any backend).
+
+Boundary (D-027): `grading/` never imports `agents/` / `api/`; this module
+imports config only.
+"""
+
+import logging
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+import sqlalchemy as sa
+from sqlalchemy import JSON, Index
+from sqlalchemy.orm import validates
+from sqlmodel import Field, Session, SQLModel, col, create_engine, select
+
+from ..config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class GradeRecord(SQLModel, table=True):
+    """A persisted grade; (learner_id, task_id) is the PK — latest wins.
+
+    Written by the grading engine (one save per grade attempt), read by the
+    API layer through the GradeStore protocol. Constraint enforcement
+    mirrors TelemetryEvent: sqlmodel 0.0.42's metaclass drops pydantic
+    constraints on table models, so SQLAlchemy `@validates` hooks enforce
+    instead and the column types stay Postgres-ready (D-027).
+
+    Field contract:
+        learner_id   — non-empty learner identifier (same id space as traces).
+        task_id      — non-empty task identifier; grade identity is the
+                       (learner_id, task_id) pair — the same pair as trace
+                       identity, so a grade is keyed by the exact trace it
+                       was computed from.
+        variant_seed — task-variant seed (D-029); None when the graded task
+                        is not variant-derived. Since Phase 4 the engine
+                        stamps the graded variant's seed here (MH#4) and the
+                        template's difficulty anchors ship to the grader
+                        prompt — this column is the audit join for that.
+        digest       — compact deterministic trace digest (D-028) that fed
+                       the rubric prompt; persisted for auditability so the
+                       LLM's input stays reproducible.
+        scores       — validated rubric scores (per-criterion 0-4,
+                       strengths, gaps); JSON dict. An empty dict is legal
+                       (e.g. an UNGRADABLE_TRACE_INCOMPLETE record carries a
+                       verdict but no scores).
+        verdict      — first-class verdict string (rubric verdict or
+                       UNGRADABLE_TRACE_INCOMPLETE); non-empty.
+        model        — provider model that produced the scores (provenance).
+        created_at   — UTC grade timestamp; a regrade replaces it (latest
+                       save wins).
+    """
+
+    __tablename__ = "grade_record"
+    # The composite PK covers (learner_id, task_id) point lookups; this
+    # secondary index covers list_for_learner ordered by created_at without
+    # a sort step (Postgres migration target D-027).
+    __table_args__ = (
+        Index("ix_grade_record_learner_created", "learner_id", "created_at"),
+    )
+
+    learner_id: str = Field(primary_key=True)
+    task_id: str = Field(primary_key=True)
+    # None only for non-variant tasks (MH#4 stamps variant seeds since P4).
+    variant_seed: str | None = Field(default=None)
+    # JSON columns: stored as TEXT on SQLite, native JSONB on Postgres (D-027).
+    digest: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    scores: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    verdict: str
+    model: str
+    created_at: datetime
+
+    @validates("learner_id", "task_id")
+    def _ids_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty identifier")
+        return value
+
+    @validates("verdict")
+    def _verdict_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty verdict string")
+        return value
+
+
+class GradeStore(Protocol):
+    """Persistence contract for latest-state grades per (learner_id, task_id).
+
+    Implemented by SQLiteGradeStore (v0.3, D-027); a Postgres implementation
+    must satisfy the same surface.
+    """
+
+    def save(self, grade: GradeRecord) -> None:
+        """Persist a grade. UPSERT on (learner_id, task_id): a regrade with
+        the same pair REPLACES the stored row wholesale — the latest grade
+        wins. NOT append-only; contrast TraceStore.append, which is
+        dedup-keep-first for at-least-once ingest.
+        """
+        ...
+
+    def get(self, learner_id: str, task_id: str) -> GradeRecord | None:
+        """Latest stored grade for the pair; None when none exists.
+
+        Detached from any DB session — safe to pass across layers.
+        """
+        ...
+
+    def list_for_learner(self, learner_id: str) -> list[GradeRecord]:
+        """All stored grades for the learner, ordered by created_at
+        ascending (chronological). Empty list when the learner has none.
+        """
+        ...
+
+    def close(self) -> None:
+        """Release DB connections. Store must not be used after close."""
+        ...
+
+
+def _sqlite_connect(dbapi_connection: sqlite3.Connection, _: object) -> None:
+    """Per-connection pragma setup (a-3). Mirrors telemetry/store.py.
+
+    journal_mode=WAL  — readers never block the single writer.
+    synchronous=NORMAL — safe in WAL mode, avoids full fsync-per-commit.
+    busy_timeout=5000  — retry briefly under contention instead of
+                         `OperationalError: database is locked`.
+    """
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.close()
+
+
+def _as_utc(ts: datetime) -> datetime:
+    """Timestamps travel as naive datetime on SQLite, tz-aware elsewhere.
+
+    SQLite (via SQLModel) drops tzinfo; Postgres TIMESTAMP WITH TIME ZONE
+    keeps it. Normalizing on the read path makes the store's contract
+    tz-aware UTC regardless of the backend (D-027).
+    """
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=UTC)  # naive UTC read-side: label as UTC
+    return ts.astimezone(UTC)
+
+
+class SQLiteGradeStore:
+    """SQLite-backed GradeStore (SQLModel). Second protocol-wrapped store
+    of the D-027 family (first: SQLiteTraceStore).
+    """
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path: Path = db_path if db_path is not None else Settings().db_path
+        self._engine = create_engine(f"sqlite:///{self._db_path}")
+        sa.event.listen(self._engine, "connect", _sqlite_connect)
+        SQLModel.metadata.create_all(self._engine)
+
+    @contextmanager
+    def _session(self) -> Iterator[Session]:
+        # expire_on_commit=False: identical session behavior to
+        # SQLiteTraceStore. save() discards the merged instance and the read
+        # paths never commit, but a uniform flag across the D-027 stores
+        # keeps their detachment guarantees from diverging.
+        with Session(self._engine, expire_on_commit=False) as session:
+            yield session
+
+    def save(self, grade: GradeRecord) -> None:
+        # `merge` = SELECT-by-PK then UPDATE or INSERT — exactly the upsert
+        # contract. The trace store deliberately avoids merge (its append is
+        # dedup-keep-first); here latest-wins IS the contract, so merge is
+        # the right tool. The caller's object is never attached to the
+        # session and stays usable (unexpired) after save.
+        with self._session() as session:
+            session.merge(grade)
+            session.commit()
+        logger.debug(
+            "grade saved (regrade overwrites): %s/%s verdict=%s model=%s",
+            grade.learner_id,
+            grade.task_id,
+            grade.verdict,
+            grade.model,
+        )
+
+    def get(self, learner_id: str, task_id: str) -> GradeRecord | None:
+        with self._session() as session:
+            record = session.get(GradeRecord, (learner_id, task_id))
+            if record is None:
+                return None
+            record.created_at = _as_utc(record.created_at)
+            # Detach from the session: callers must not depend on
+            # open-session ORM magic (lazy loads fail once it closes).
+            session.expunge(record)
+            return record
+
+    def list_for_learner(self, learner_id: str) -> list[GradeRecord]:
+        with self._session() as session:
+            stmt = (
+                select(GradeRecord)
+                .where(GradeRecord.learner_id == learner_id)
+                # Chronological; task_id is a deterministic tie-break for
+                # grades stamped within the same instant.
+                # P5: col() — SQLModel class attrs are Mapped[T], the
+                # column reference rides col() in order_by.
+                .order_by(col(GradeRecord.created_at), GradeRecord.task_id)
+            )
+            results = session.exec(stmt).all()
+            for row in results:
+                row.created_at = _as_utc(row.created_at)
+                session.expunge(row)
+            return list(results)
+
+    def close(self) -> None:
+        self._engine.dispose()

apps/ai-service/ai_service/identity/__init__.py

@@ -0,0 +1,24 @@
+"""Identity engine package — provider protocol + store (REQ-5-003, D-042)."""
+
+from .base import (
+    AgeBand,
+    IdentityProvider,
+    IdentityStatus,
+    IdentitySubmission,
+    IdentityVerdict,
+)
+from .mock import MockIdentityProvider, derive_age_band
+from .store import IdentityRecord, IdentityStore, SQLiteIdentityStore
+
+__all__ = [
+    "AgeBand",
+    "IdentityStatus",
+    "IdentitySubmission",
+    "IdentityVerdict",
+    "IdentityProvider",
+    "IdentityRecord",
+    "IdentityStore",
+    "SQLiteIdentityStore",
+    "MockIdentityProvider",
+    "derive_age_band",
+]

apps/ai-service/ai_service/identity/base.py

@@ -0,0 +1,64 @@
+"""Identity verification protocol (REQ-5-003, D-042, A-303).
+
+Provider-agnostic like LLMProvider/VoiceProvider (D-014/D-030): a narrow
+protocol the identity API composes via DI, a deterministic mock, and a
+future real KYC vendor (Stripe Identity / Persona / Onfido class) that
+drops in without API changes. PII rules (A-305): the provider sees
+document REFERENCES, never raw documents; verdicts carry a mock marker
+(A-304) so downstream surfaces never display mock-verified as
+production-verified.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+AgeBand = Literal["16-17", "18+"]
+IdentityStatus = Literal["pending", "verified", "rejected"]
+
+
+class IdentitySubmission(BaseModel):
+    """What a learner submits: derived data + document refs only.
+
+    `date_of_birth` is a REAL date (the provider derives the age band) but
+    raw DOB is NEVER persisted — only the derived band (A-305). Document
+    refs are opaque handles (upload ids), never contents.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    learner_id: str = Field(min_length=1)
+    date_of_birth: str = Field(description="ISO date; used to derive age_band, never stored")
+    document_refs: list[str] = Field(
+        default_factory=list,
+        description="Opaque upload handles; raw documents are never stored",
+    )
+
+
+class IdentityVerdict(BaseModel):
+    """Provider verdict — what gets stored + surfaced."""
+
+    model_config = ConfigDict(frozen=True)
+
+    status: IdentityStatus
+    age_band: AgeBand | None = None
+    provider: str
+    #: A-304 honesty: mock verdicts carry mock=True forever — downstream
+    #: surfaces must never treat a mock verdict as production-verified.
+    mock: bool = True
+    detail: str = ""
+
+
+@runtime_checkable
+class IdentityProvider(Protocol):
+    """The KYC port: submit → (poll) → verdict. Never imports api/."""
+
+    async def submit(self, submission: IdentitySubmission) -> str:
+        """Start verification; returns a submission id (minted once)."""
+        ...
+
+    async def poll(self, submission_id: str) -> IdentityVerdict:
+        """Fetch the (possibly pending) verdict for a submission."""
+        ...

apps/ai-service/ai_service/identity/mock.py

@@ -0,0 +1,96 @@
+"""Deterministic mock identity provider (REQ-5-003, A-303).
+
+Approve-on-policy: every submission verifies unless the caller scripts a
+rejection (by learner id) or the derived age band fails the floor
+(under-16 → rejected with an age detail). Verdicts are mock-marked (A-304)
+— the marker rides every verdict so no downstream surface can ever
+display mock-verified as production-verified. Never calls the network.
+"""
+
+from __future__ import annotations
+
+import itertools
+import secrets
+from datetime import UTC, datetime
+
+from .base import IdentitySubmission, IdentityVerdict
+
+
+def derive_age_band(date_of_birth: str, today: datetime | None = None) -> str:
+    """Derive the age band from an ISO date. Under-16 returns "under-16".
+
+    Pure + deterministic; used by the store test and the API alike.
+    """
+    dob = datetime.fromisoformat(date_of_birth)
+    now = today or datetime.now(UTC)
+    age = now.year - dob.year - (
+        (now.month, now.day) < (dob.month, dob.day)
+    )
+    if age < 16:
+        return "under-16"
+    if age < 18:
+        return "16-17"
+    return "18+"
+
+
+class MockIdentityProvider:
+    """Scriptable, deterministic; no network, no vendor calls.
+
+    Submission ids are minted UNIQUELY per submit() call (a monotonic
+    counter + the per-process seed from `secrets`): the id is the PK of
+    the insert-only IdentityStore, and a deterministic id derived from
+    (learner_id, date_of_birth) collides on any resubmit-after-terminal
+    (e.g. a rejected learner retrying with the same DOB) — the store
+    surfaces IntegrityError and the API would 500 (cross-phase P0,
+    final review). Uniqueness per call is the contract; determinism of
+    VERDICTS (what tests actually pin) is preserved — poll() derives the
+    band purely from the stored submission.
+    """
+
+    def __init__(self, reject_learners: set[str] | None = None) -> None:
+        self._submissions: dict[str, IdentitySubmission] = {}
+        self._reject_learners = reject_learners or set()
+        # Per-process nonce: ids are opaque handles (A-305) — never
+        # derived from PII. Counter + nonce keeps ids unique within and
+        # across provider instances on one box.
+        self._nonce = secrets.randbits(32)
+        self._counter = itertools.count()
+
+    async def submit(self, submission: IdentitySubmission) -> str:
+        submission_id = f"idc-{self._nonce:08x}{next(self._counter):08x}"
+        self._submissions[submission_id] = submission
+        return submission_id
+
+    async def poll(self, submission_id: str) -> IdentityVerdict:
+        submission = self._submissions.get(submission_id)
+        if submission is None:
+            return IdentityVerdict(
+                status="rejected",
+                provider="mock",
+                mock=True,
+                detail="unknown submission id",
+            )
+        if submission.learner_id in self._reject_learners:
+            return IdentityVerdict(
+                status="rejected",
+                provider="mock",
+                mock=True,
+                detail="scripted rejection (test)",
+            )
+        band = derive_age_band(submission.date_of_birth)
+        if band == "under-16":
+            return IdentityVerdict(
+                status="rejected",
+                provider="mock",
+                mock=True,
+                detail="under 16 — the AI school floor is 16+ (COPPA avoidance)",
+            )
+        return IdentityVerdict(
+            status="verified",
+            # P5: derive_age_band returns str; the verdict's Literal contract —
+            # the derived bands are in-contract by construction.
+            age_band=band,  # type: ignore[arg-type]
+            provider="mock",
+            mock=True,
+            detail="mock verdict — not production verification",
+        )

apps/ai-service/ai_service/identity/store.py

@@ -0,0 +1,218 @@
+"""IdentityStore — verification records (REQ-5-003, D-042, D-027 FIFTH store).
+
+Insert-only + latest-per-learner lookup, modeled on the DefenseStore
+conventions: WAL + synchronous=NORMAL + busy_timeout + foreign_keys=ON
+pragmas at connect time, portable column types (str/datetime/JSON) for
+Postgres parity, @validates hooks for constraints sqlmodel's metaclass
+drops, tz-aware→naive→tz-aware boundary normalization.
+
+PII contract (A-305): stores the DERIVED age_band (16-17 | 18+), NEVER a
+raw date of birth; document_refs are opaque handles, NEVER contents.
+Verdict provenance is audit data: every record carries provider + the
+mock marker (A-304) so downstream surfaces can label unverified state
+honestly.
+
+Insert-only growth is fine at pilot scale (a-12): learner_id indexed,
+latest-per-learner lookup, no compaction pre-vendor.
+
+Boundary (D-027): `identity/` never imports `agents/` / `api/`; this
+module imports config only.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+from sqlalchemy import event, func, text
+from sqlalchemy.types import JSON, String
+from sqlmodel import Field, Session, SQLModel, col, create_engine, select
+
+from ..config import Settings
+from .base import IdentityStatus
+
+logger = logging.getLogger(__name__)
+
+
+class IdentityRecord(SQLModel, table=True):
+    """One verification submission's lifecycle + verdict provenance."""
+
+    __tablename__ = "identity_record"
+
+    #: PK = the submission id minted once by the provider's submit().
+    id: str = Field(primary_key=True)
+    learner_id: str = Field(index=True)
+    # Bare Literal annotations crash sqlmodel's column inference; explicit
+    # sa_type + the validates hook below give the same contract
+    # (VARCHAR column, Literal-rejected values — DefenseStore pattern).
+    status: IdentityStatus = Field(default="pending", sa_type=String)
+    provider: str
+    #: Verdict provenance: the provider's raw verdict (mock-marked).
+    verdict: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    #: DERIVED band only — raw DOB is never persisted (A-305).
+    age_band: str | None = Field(default=None, sa_type=String)
+    #: Opaque document handles — raw documents never stored (A-305).
+    document_refs: list[str] = Field(default_factory=list, sa_type=JSON)
+    submitted_at: datetime
+    verified_at: datetime | None = Field(default=None)
+
+    @property
+    def mock(self) -> bool:
+        """A-304: the mock marker rides every surface (record + API)."""
+        return bool(self.verdict.get("mock", True))
+
+    def _validate(self) -> None:
+        if not self.id or not self.learner_id:
+            raise ValueError("id and learner_id must be non-empty")
+        if self.status not in ("pending", "verified", "rejected"):
+            raise ValueError(f"invalid identity status {self.status!r}")
+        # D3 (verifier): a stored band must be canonical or None (pending).
+        # The gate fails closed on anything else; the store refuses to
+        # create it in the first place.
+        if self.age_band is not None and self.age_band not in (
+            "16-17",
+            "18+",
+            "under-16",
+        ):
+            raise ValueError(f"invalid age_band {self.age_band!r}")
+
+    def _normalize(self) -> None:
+        self.submitted_at = _as_utc(self.submitted_at)
+        if self.verified_at is not None:
+            self.verified_at = _as_utc(self.verified_at)
+
+
+def _as_utc(ts: datetime) -> datetime:
+    """SQLite stores naive; read paths re-label tz-aware UTC (D-027 pattern)."""
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=UTC)
+    return ts
+
+
+def _sqlite_connect(dbapi_connection: sqlite3.Connection, _: object) -> None:
+    """Per-connection pragmas — mirrors the other D-027 stores (P5: the
+    concrete sqlite3.Connection type removes the two attr-defined ignores
+    the loose `object` annotation needed)."""
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.execute("PRAGMA foreign_keys=ON")
+    cursor.close()
+
+
+class IdentityStore(Protocol):
+    """Persistence contract for identity records."""
+
+    def insert(self, record: IdentityRecord) -> IdentityRecord:
+        """INSERT-ONLY: a duplicate id raises IntegrityError (surfaced, not
+        swallowed — a submission id is minted once)."""
+        ...
+
+    def get(self, submission_id: str) -> IdentityRecord | None:
+        """Point lookup by submission id."""
+        ...
+
+    def latest_for_learner(self, learner_id: str) -> IdentityRecord | None:
+        """Newest record for the learner (or None)."""
+        ...
+
+    def count_pending_for_learner(self, learner_id: str) -> int:
+        """G-13: active pending submissions (cap = 1)."""
+        ...
+
+    def mark_verified(
+        self, submission_id: str, verdict: dict[str, Any], age_band: str | None
+    ) -> IdentityRecord | None:
+        """Terminal transition (verified or rejected): stamp + store the
+        provider verdict + derived band. Unknown id → None."""
+        ...
+
+
+class SQLiteIdentityStore:
+    """SQLite implementation of IdentityStore (D-027)."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path: Path = db_path if db_path is not None else Settings().db_path
+        self._engine = create_engine(
+            f"sqlite:///{self._db_path}",
+            connect_args={"check_same_thread": False},
+        )
+        event.listen(self._engine, "connect", _sqlite_connect)
+        SQLModel.metadata.create_all(self._engine)
+
+    def insert(self, record: IdentityRecord) -> IdentityRecord:
+        record._validate()
+        record._normalize()
+        with Session(self._engine) as session:
+            session.add(record)
+            session.commit()  # IntegrityError SURFACES (insert-only, minted-once)
+            session.refresh(record)
+            return record
+
+    def get(self, submission_id: str) -> IdentityRecord | None:
+        with Session(self._engine) as session:
+            rec = session.get(IdentityRecord, submission_id)
+            if rec is None:
+                return None
+            session.refresh(rec)
+            rec.submitted_at = _as_utc(rec.submitted_at)
+            if rec.verified_at is not None:
+                rec.verified_at = _as_utc(rec.verified_at)
+            return rec
+
+    def latest_for_learner(self, learner_id: str) -> IdentityRecord | None:
+        with Session(self._engine) as session:
+            # D4 (verifier): submitted_at alone can tie at microsecond
+            # resolution — sqlite rowid breaks the tie deterministically
+            # (last inserted wins, mirroring insert-only chronology).
+            # rowid is a SQLite physical column, not a SQLModel field — it
+            # rides the query as raw text.
+            rec = session.exec(
+                select(IdentityRecord)
+                .where(IdentityRecord.learner_id == learner_id)
+                .order_by(
+                    # P5: col() — SQLModel class attrs are Mapped[T], the
+                    # column operators (.desc()) ride col().
+                    col(IdentityRecord.submitted_at).desc(),
+                    text("rowid DESC"),
+                )
+            ).first()
+            if rec is not None:
+                rec.submitted_at = _as_utc(rec.submitted_at)
+                if rec.verified_at is not None:
+                    rec.verified_at = _as_utc(rec.verified_at)
+            return rec
+
+    def count_pending_for_learner(self, learner_id: str) -> int:
+        with Session(self._engine) as session:
+            return session.exec(
+                select(func.count())
+                .select_from(IdentityRecord)
+                .where(
+                    IdentityRecord.learner_id == learner_id,
+                    IdentityRecord.status == "pending",
+                )
+            ).one()
+
+    def mark_verified(
+        self, submission_id: str, verdict: dict[str, Any], age_band: str | None
+    ) -> IdentityRecord | None:
+        with Session(self._engine) as session:
+            rec = session.get(IdentityRecord, submission_id)
+            if rec is None:
+                return None
+            rec.verdict = verdict
+            rec.age_band = age_band
+            rec.verified_at = datetime.now(UTC)
+            rec.status = "verified" if verdict.get("status") == "verified" else "rejected"
+            rec._validate()  # D3: transitions validate like inserts
+            session.commit()
+            session.refresh(rec)
+            return rec
+
+    def close(self) -> None:
+        self._engine.dispose()

apps/ai-service/ai_service/llm/base.py

@@ -12,7 +12,11 @@ from .types import Message
 
 
 class LLMProvider(Protocol):
-    async def stream_chat(
+    # P5 (D-058): plain `def` returning AsyncIterator — the honest shape for
+    # async-generator implementations. `async def -> AsyncIterator` makes mypy
+    # see a coroutine WRAPPING the iterator (every call site would need an
+    # extra await); async generators ARE functions returning AsyncIterator.
+    def stream_chat(
         self,
         messages: list[Message],
         *,

apps/ai-service/ai_service/main.py

@@ -9,19 +9,40 @@ import httpx
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from . import __version__
 from .agents.registry import AgentRegistry, register_builtin_agents
 from .agents.session import InMemorySessionStore
 from .api import (
     assessment_router,
     chat_router,
+    defense_router,
     lab_router,
     mentor_router,
     proctor_router,
     sandboxes_router,
+    telemetry_router,
+    variants_router,
 )
 from .config import Settings
+from .grading.engine import GradingEngine
+from .grading.store import SQLiteGradeStore
+from .identity.mock import MockIdentityProvider
+from .identity.store import SQLiteIdentityStore
 from .llm import create_provider
 from .sandbox import SandboxManager, UnshareBackend
+from .sandbox.capability import (
+    DEGRADE_REMEDIATION,
+    container_detected,
+    sandbox_fabric_degraded,
+)
+from .telemetry.ingest import TraceIntegrityMap
+from .telemetry.store import SQLiteTraceStore
+from .telemetry.tokens import IngestToken
+from .variants.generator import VariantGenerator
+from .variants.store import SQLiteVariantStore
+from .voice.defense_store import SQLiteDefenseStore
+from .voice.factory import voice_provider_from_settings
+from .voice.mock import MockVoiceProvider
 
 logger = logging.getLogger(__name__)
 
@@ -39,7 +60,11 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         timeout = httpx.Timeout(connect=10.0, read=300.0, write=30.0, pool=10.0)
         app.state.http_client = httpx.AsyncClient(timeout=timeout)
         app.state.settings = settings
-        app.state.provider = create_provider(settings, app.state.http_client)
+        # State-injection override (same pattern as the stores): tests may
+        # pre-set app.state.provider with a scripted mock; only construct the
+        # configured provider when none is present.
+        if getattr(app.state, "provider", None) is None:
+            app.state.provider = create_provider(settings, app.state.http_client)
         app.state.session_store = InMemorySessionStore()
         app.state.agent_registry = AgentRegistry()
         register_builtin_agents(app.state.agent_registry)
@@ -48,12 +73,178 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         # app.state. Tests may pre-set app.state.sandbox_manager (dependency
         # override by state injection) to swap the backend; the lifespan then
         # adopts it instead of constructing the real UnshareBackend one.
+        # v0.4.7 (P1): the ingest token is created BEFORE the manager (the
+        # manager MINTS into NC_INGEST_URL; the WS endpoint VERIFIES) and
+        # shared via app.state — one instance, so the per-boot random secret
+        # (unset AI_TELEMETRY_INGEST_SECRET) agrees on both sides.
+        if getattr(app.state, "ingest_token", None) is None:
+            app.state.ingest_token = IngestToken(settings.telemetry_ingest_secret)
         manager = getattr(app.state, "sandbox_manager", None)
         if manager is None:
-            manager = SandboxManager(backend=UnshareBackend(), settings=settings)
+            manager = SandboxManager(
+                backend=UnshareBackend(),
+                settings=settings,
+                ingest_token=app.state.ingest_token,
+            )
             app.state.sandbox_manager = manager
         await manager.start()  # a-1: reap on-disk orphans from a previous process
 
+        # Telemetry persistence (REQ-3-003, D-027): TraceStore wired through
+        # app.state. Tests may pre-set app.state.trace_store (state-injection
+        # override, same pattern as sandbox_manager) — the lifespan adopts it.
+        trace_store = getattr(app.state, "trace_store", None)
+        if trace_store is None:
+            settings.db_path.parent.mkdir(parents=True, exist_ok=True)
+            trace_store = SQLiteTraceStore(db_path=settings.db_path)
+            app.state.trace_store = trace_store
+        # Trace-integrity flags (G-3 INCOMPLETE_FLOODED): process-local map is
+        # intentional (D-019 registry precedent); the lifespan owns it so the
+        # grader and the ingest endpoint share one instance.
+        if getattr(app.state, "trace_integrity", None) is None:
+            app.state.trace_integrity = TraceIntegrityMap()
+
+        # Variant generation (REQ-3-005): VariantStore from the same
+        # SQLite file as traces/grades (D-027), one VariantGenerator singleton
+        # wired through app.state — the generator receives store + provider
+        # via constructor DI and knows nothing of FastAPI (api/ composes it,
+        # same pattern as GradingEngine). Tests may pre-set
+        # app.state.variant_store / app.state.variant_generator (the same
+        # state-injection override); the lifespan adopts a pre-set store but
+        # NEVER rebuilds a pre-set generator (its provider binding is part
+        # of the test fixture).
+        # ORDER NOTE: built BEFORE the grading engine — the engine takes the
+        # variant store (Phase 4 MH#4: variant anchors ship to the grader
+        # prompt; variant_seed stamped on graded records).
+        variant_store = getattr(app.state, "variant_store", None)
+        if variant_store is None:
+            settings.db_path.parent.mkdir(parents=True, exist_ok=True)
+            variant_store = SQLiteVariantStore(db_path=settings.db_path)
+            app.state.variant_store = variant_store
+        if getattr(app.state, "variant_generator", None) is None:
+            app.state.variant_generator = VariantGenerator(
+                variant_store,
+                app.state.provider,
+                model=settings.model,
+            )
+
+        # Oral defense (REQ-3-006): DefenseStore (same SQLite file) + the
+        # mock-first voice provider (D-030) + the seventh Examiner agent.
+        # Tests may pre-set app.state.defense_store / voice_provider /
+        # examiner_agent (state-injection override; never rebuilt if pre-set).
+        defense_store = getattr(app.state, "defense_store", None)
+        if defense_store is None:
+            defense_store = SQLiteDefenseStore(db_path=settings.db_path)
+            app.state.defense_store = defense_store
+        if getattr(app.state, "voice_provider", None) is None:
+            # G-11 (boot survival): a misconfigured real provider must never
+            # crash the unattended deploy — fall back to mock loudly. The
+            # mock provider's descriptor honestly reports mode='mock' so the
+            # UI badge cannot lie about which path is live.
+            try:
+                app.state.voice_provider = voice_provider_from_settings(
+                    settings, app.state.http_client
+                )
+            except Exception as exc:
+                logger.warning(
+                    "voice provider %r unavailable (%s); falling back to mock "
+                    "— fix the AI_VOICE_* settings and restart",
+                    settings.voice_provider,
+                    exc,
+                )
+                app.state.voice_provider = MockVoiceProvider()
+        if getattr(app.state, "examiner_agent", None) is None:
+            from .agents.examiner import ExaminerAgent
+
+            app.state.examiner_agent = ExaminerAgent(app.state.provider, settings)
+
+        # Identity verification (REQ-5-003): 5th D-027 store (same SQLite
+        # file) + mock-first provider (A-303). State-injection overrides
+        # preserved — tests may pre-set either.
+        identity_store = getattr(app.state, "identity_store", None)
+        if identity_store is None:
+            identity_store = SQLiteIdentityStore(db_path=settings.db_path)
+            app.state.identity_store = identity_store
+        if getattr(app.state, "identity_provider", None) is None:
+            app.state.identity_provider = MockIdentityProvider()
+
+        # Marketplace engine (v0.6, REQ-6-001): 6th D-027 store family on
+        # the same SQLite file. State-injection override preserved.
+        if getattr(app.state, "marketplace_store", None) is None:
+            from .marketplace.store import SQLiteMarketplaceStore
+
+            app.state.marketplace_store = SQLiteMarketplaceStore(
+                db_path=settings.db_path
+            )
+
+        # Embedding provider (v0.6 P3, REQ-6-003, D-051): mock-first
+        # feature-hash default; openai-embed against any OpenAI-compatible
+        # embeddings endpoint. State-injection override preserved (the
+        # voice pattern). G-11 (boot survival): a misconfigured real
+        # provider must never crash the unattended deploy — fall back to
+        # mock loudly.
+        if getattr(app.state, "embedding_provider", None) is None:
+            from .marketplace.embedding.factory import (
+                embedding_provider_from_settings,
+            )
+            from .marketplace.embedding.mock import MockEmbedProvider
+
+            try:
+                app.state.embedding_provider = embedding_provider_from_settings(
+                    settings, app.state.http_client
+                )
+            except Exception as exc:
+                logger.warning(
+                    "embedding provider %r unavailable (%s); falling back to "
+                    "mock — fix the AI_EMBED_* settings and restart",
+                    settings.embed_provider,
+                    exc,
+                )
+                app.state.embedding_provider = MockEmbedProvider()
+
+        # G-11/D-057: admin routes fail CLOSED on an unset token, and the
+        # founder must be told loudly at boot (never a silent lockout).
+        if not settings.admin_token.get_secret_value():
+            logger.warning(
+                "AI_ADMIN_TOKEN is unset — /v1/marketplace/admin/* routes "
+                "are 403 (fail-closed). Set AI_ADMIN_TOKEN in .env to "
+                "author postings, run ingest, and review applications."
+            )
+
+        # G-105 (P5/D-056): an unset origin makes the sitemap serve the
+        # honest empty set and robots omit the Sitemap directive — the
+        # founder must be told loudly at boot (G-11 doctrine; the
+        # request-time fallback never emits malformed/relative URLs).
+        if not (settings.public_base_url or "").strip():
+            logger.warning(
+                "AI_PUBLIC_BASE_URL is unset — /sitemap.xml serves the "
+                "empty static-page set and robots.txt omits the Sitemap "
+                "directive (spec requires absolute URLs). Set the deployed "
+                "origin (e.g. https://nextcraft.example) in .env to serve "
+                "the full sitemap."
+            )
+
+        # Grading persistence + engine (REQ-3-004): GradeStore from the same
+        # SQLite file as traces (D-027), one GradingEngine singleton wired
+        # through app.state — the engine receives its stores via constructor
+        # DI and knows nothing of FastAPI (api/ owns composition). Tests may
+        # pre-set app.state.grade_store / app.state.grading_engine (the same
+        # state-injection override as sandbox_manager/trace_store) to swap
+        # either; the lifespan adopts a pre-set store but NEVER rebuilds a
+        # pre-set engine (its provider binding is part of the test fixture).
+        grade_store = getattr(app.state, "grade_store", None)
+        if grade_store is None:
+            grade_store = SQLiteGradeStore(db_path=settings.db_path)
+            app.state.grade_store = grade_store
+        if getattr(app.state, "grading_engine", None) is None:
+            app.state.grading_engine = GradingEngine(
+                trace_store,
+                grade_store,
+                app.state.trace_integrity,
+                app.state.provider,
+                model=settings.model,
+                variant_store=variant_store,  # MH#4: anchors + seed (D-029)
+            )
+
         async def _reaper_loop() -> None:
             # Wall-clock timeout + G-2 workdir-size sweep, one pass per tick.
             while True:
@@ -64,6 +255,24 @@ def create_app(settings: Settings | None = None) -> FastAPI:
                     logger.exception("sandbox reaper pass failed; retrying next tick")
 
         reaper = asyncio.create_task(_reaper_loop())
+
+        # v0.8 honest degrade (D-068/G-208): probe once at boot; if the
+        # namespace fabric cannot work on this host (unprivileged container
+        # under docker's default seccomp), say so LOUDLY once with the shared
+        # remediation constant — the 503 arm in api/sandboxes.py carries the
+        # same text, so the surfaces cannot drift. The probe is the truth
+        # source; the container marker only tailors the message.
+        if sandbox_fabric_degraded():
+            if container_detected():
+                logger.warning(
+                    "SANDBOX FABRIC DEGRADED (container detected): %s",
+                    DEGRADE_REMEDIATION,
+                )
+            else:
+                logger.warning(
+                    "SANDBOX FABRIC DEGRADED: %s", DEGRADE_REMEDIATION
+                )
+
         try:
             yield
         finally:
@@ -73,15 +282,26 @@ def create_app(settings: Settings | None = None) -> FastAPI:
             # No orphans outlive the process (a-1, shutdown half): destroy
             # everything live; workdirs stay on disk for snapshot restore.
             await manager.destroy_all()
+            trace_store.close()
+            grade_store.close()
+            variant_store.close()
+            defense_store.close()
+            identity_store.close()
             await app.state.http_client.aclose()
 
-    app = FastAPI(title="Nextcraft AI Service", version="0.3.0", lifespan=lifespan)
+    app = FastAPI(title="Nextcraft AI Service", version=__version__, lifespan=lifespan)
 
-    # A-008: localhost-only CORS, no credentials
+    # A-008 + D-038: no-credentials CORS. Default '*' admits remote-browser
+    # origins in network mode (safe only because allow_credentials stays
+    # False — never enable credentials with a wildcard). AI_CORS_ORIGINS
+    # restricts to an explicit list. PUT is CONTRACT, not trivia: the learner
+    # build surface writes workspace files with PUT (engine-client writeFile)
+    # — v0.3 initially shipped without it and every cross-origin Save failed
+    # preflight (caught in P7 review; tests/api/test_cors.py pins the policy).
     app.add_middleware(
         CORSMiddleware,
-        allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
-        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_origins=settings.cors_origin_list,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
         allow_headers=["Content-Type"],
         allow_credentials=False,
     )
@@ -100,6 +320,117 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     app.include_router(mentor_router)
     app.include_router(proctor_router)
     app.include_router(sandboxes_router)
+    app.include_router(telemetry_router)
+    app.include_router(variants_router)
+    app.include_router(defense_router)
+
+    # v0.5 identity (REQ-5-003/004): verification flow + age-gate deps.
+    # v0.6: the G-18 marketplace stub moved to api/marketplace.py and is
+    # REAL (D-058) — identity keeps only its own router + gate exports.
+    from .api.identity import router as identity_router
+    from .api.marketplace import router as marketplace_public_router
+    from .api.marketplace_admin import router as marketplace_admin_router
+
+    app.include_router(identity_router)
+    app.include_router(marketplace_public_router)
+    app.include_router(marketplace_admin_router)
+
+    # v0.6 P5 (REQ-6-006, D-056): dynamic sitemap/robots — request-time
+    # enumeration (build-time Next sitemap.ts cannot see runtime
+    # postings under output:'export'); API routes beat the static mount.
+    from .api.sitemap import router as sitemap_router
+
+    app.include_router(sitemap_router)
+
+    # A-305/D1: PII-safe 422s — FastAPI echoes the offending `input` in
+    # validation errors by default; for the identity submit body that
+    # leaks the raw DOB into responses + client logs. The handler scrubs
+    # PII field inputs (scoped app-wide; harmless elsewhere).
+    from fastapi.exceptions import RequestValidationError
+    from fastapi.responses import JSONResponse
+
+    def _scrub_pii_validation(request, exc):
+        # P5: the old `# type: ignore[unused-arg]` was inert (the unused-arg
+        # code is not enabled by this baseline); removed per D-058.
+        pii_fields = frozenset({"date_of_birth"})
+        scrubbed = []
+        for err in exc.errors():
+            err = dict(err)
+            if err.get("loc") and err["loc"][-1] in pii_fields:
+                # A-305/D1: never echo the submitted value (input) or the
+                # ctx payload (carries the ValueError); the msg is the
+                # constraint text and is safe.
+                err["input"] = "[redacted]"
+                err.pop("ctx", None)
+            else:
+                # FastAPI's default 422s are JSON-safe EXCEPT ctx payloads
+                # carrying raw ValueError objects (pydantic model_validator
+                # errors); strip ctx body-wide so non-PII routes keep their
+                # 422 shape (msg + loc carry the meaning).
+                ctx = err.get("ctx")
+                if isinstance(ctx, dict):
+                    err["ctx"] = {
+                        k: v for k, v in ctx.items() if isinstance(v, (str, int, float, bool))
+                    }
+            scrubbed.append(err)
+        return JSONResponse(status_code=422, content={"detail": scrubbed})
+
+    app.add_exception_handler(RequestValidationError, _scrub_pii_validation)
+
+    # v0.6 G-101: Next 15 output:'export' hard-throws (E87) for dynamic
+    # routes without generateStaticParams, so jobs/[jobId] and
+    # employers/[employerId] export exactly ONE placeholder shell
+    # (out/marketplace/jobs/_/index.html). These catch-all routes serve
+    # that shell for ANY id — registered BEFORE the StaticFiles mount so
+    # they win (the same routes-beat-the-mount mechanism the sitemap
+    # relies on, G-109). The shell client-fetches the real posting by
+    # the path id and notFound()s on 404 — a resolvable URL for every
+    # sitemap entry.
+    from .api.marketplace_shells import register_marketplace_shell_routes
+
+    register_marketplace_shell_routes(app, settings)
+
+    # v0.3.6 single-port deploy: serve the exported web app (apps/web/out)
+    # from the SAME origin as the API when AI_WEB_STATIC_DIR is set. Mounted
+    # AFTER all routers, so /v1/*, /health, /docs win; StaticFiles(html=True)
+    # then resolves / → index.html, /dashboard/ → dashboard/index.html. A
+    # 404 handler below serves the export's 404.html for unknown paths so
+    # browsers see the site's not-found page instead of FastAPI's JSON.
+    # Default unset → no mount, dev/tests see the plain API app.
+    if str(settings.web_static_dir) not in ("", "."):
+        from fastapi.responses import FileResponse
+        from fastapi.staticfiles import StaticFiles
+
+        web_dir = settings.web_static_dir
+        if not web_dir.is_dir():
+            raise RuntimeError(
+                f"AI_WEB_STATIC_DIR is set but {web_dir} does not exist — "
+                "build the web app first (pnpm build) or unset the setting"
+            )
+
+        @app.exception_handler(404)
+        async def _spa_404(request, exc):
+            # P5: the old `# type: ignore[unused]` was inert (the unused code
+            # is not enabled by this baseline); removed per D-058.
+            not_found_page = web_dir / "404.html"
+            if not_found_page.is_file():
+                return FileResponse(not_found_page, status_code=404)
+            raise exc
+
+        app.mount("/", StaticFiles(directory=web_dir, html=True), name="web")
+    else:
+        # v0.4.6: the v0.3.6/v0.4-era "site down" root cause was a silently
+        # mount-less boot — behind HAProxy, / answers this app's JSON 404
+        # and nothing detects it. Unattended deploys MUST be loud (G-11
+        # doctrine). Dev/tests keep the no-mount default; production boxes
+        # see a warning naming the fix.
+        logger.warning(
+            "AI_WEB_STATIC_DIR is unset — the exported web UI is NOT served; "
+            "/ answers the API's JSON 404. For single-port deploys, build the "
+            "web app (NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build) and run it "
+            "via `nextcraft dev`/`dev -d` (auto-wires apps/web/out) or set "
+            "AI_WEB_STATIC_DIR explicitly."
+        )
     return app
 
 

apps/ai-service/ai_service/marketplace/__init__.py

@@ -0,0 +1,12 @@
+"""Marketplace engine package (REQ-6-001, D-048/D-049).
+
+The 6th engine module inside apps/ai-service (no new apps, no new ports,
+D-031 boundary): pydantic contracts (`base.py`), the D-027 store family's
+sixth SQLite store (`store.py`), and PostingSource ingest adapters
+(`ingest.py`). Tagging (P2), embedding (P3), enrichment + resume (P4)
+extend this package; the HTTP surface lives in `api/marketplace*.py`
+which composes this module via DI.
+
+Boundary (D-031/D-048): `marketplace/` never imports `agents/` or
+`api/`; this package imports config + stdlib only.
+"""

apps/ai-service/ai_service/marketplace/base.py

@@ -0,0 +1,174 @@
+"""Marketplace pydantic contracts (REQ-6-001, D-048, A-402).
+
+The wire + store shapes for the postings backend. `IngestPosting` is the
+A-402 adapter shape (what every PostingSource yields); `Posting` is the
+full row shape (status lifecycle + tags); `Employer` carries the raw
+ingested fields (enrichment + provenance merge is P4's read-time job).
+
+D-051/D-053 note: the mock `matchScore` from the TS fixtures is NOT part
+of any contract — P3 computes real scores at search time; absent score =
+absent query context (G-106).
+
+Boundary (D-048): mirrors D-031 — never imports `agents/` or `api/`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+PostingStatus = Literal["draft", "published", "closed"]
+
+#: Lifecycle edge set (D-049/D-057): draft → published → closed. A
+#: transition not in this map is invalid (admin route → 409).
+VALID_TRANSITIONS: dict[str, str] = {
+    "draft": "published",
+    "published": "closed",
+}
+
+Seniority = Literal["entry", "mid", "senior", "staff", "principal"]
+
+#: P2 (D-052) enumerates the category taxonomy; the seed corpus carries
+#: category=null and P2's tagging pass fills it. The store accepts any
+#: short string (validation lands with the tagger); `None` = not yet
+#: tagged.
+Category = str | None
+
+
+class PostingTags(BaseModel):
+    """Derived tags on a posting row (D-052 schema, persisted as the
+    posting's JSON `tags` column in P2; the column exists from day one).
+
+    `skills` is bounded at 10 by the tagger (D-052); the schema itself
+    keeps the bound so the store can validate a hand-authored payload.
+    `extra="forbid"`: a non-tag JSON object (e.g. the mock provider's
+    canned {"summary":...}) must NOT silently validate as all-default
+    tags — the untagged signal stays honest (verifier P2-3; P3
+    embeddings must not treat empty-default parses as real tags).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    skills: list[str] = Field(default_factory=list, max_length=10)
+    seniority: Seniority | None = None
+    category: Category = None
+
+
+class Employer(BaseModel):
+    """Raw ingested employer fields (D-049 `employer` table row shape).
+
+    P4 (D-053) enriches on read with per-field `{value, source}`
+    provenance; P1 surfaces the raw fields only.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    source: str = Field(min_length=1)
+    external_id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    logo: str = ""
+    description: str = ""
+    industry: str = ""
+    size: str = ""
+    location: str = ""
+    website: str = ""
+    social_links: dict[str, str] = Field(default_factory=dict)
+    culture: str = ""
+
+
+class IngestPosting(BaseModel):
+    """The A-402 PostingSource payload: (source, external_id) identity +
+    employer binding + the raw posting fields. Idempotent upsert key is
+    (source, external_id) — a re-fetch overwrites the same row in place.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    source: str = Field(min_length=1)
+    external_id: str = Field(min_length=1)
+    employer_id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    description: str = ""
+    required_competencies: list[str] = Field(default_factory=list)
+    skills: list[str] = Field(default_factory=list)
+    seniority: Seniority | None = None
+    category: Category = None
+    location: str = ""
+    remote: bool = False
+    salary_min: int | None = None
+    salary_max: int | None = None
+    #: G-102: seed-port postings carry their ORIGINAL postedAt; the
+    #: store applies it verbatim (status=published via the ingest
+    #: contract, not the field).
+    posted_at: datetime | None = None
+
+
+class Posting(BaseModel):
+    """Full posting row (D-049 `posting` table). Status is the lifecycle
+    column (draft|published|closed, D-057); `tags` is the P2-derived
+    JSON column (D-052 — empty until the tagger runs). `matchScore` is
+    deliberately absent (G-106/G-107).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    source: str = Field(min_length=1)
+    external_id: str = Field(min_length=1)
+    employer_id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    description: str = ""
+    required_competencies: list[str] = Field(default_factory=list)
+    skills: list[str] = Field(default_factory=list)
+    seniority: Seniority | None = None
+    category: Category = None
+    location: str = ""
+    remote: bool = False
+    salary_min: int | None = None
+    salary_max: int | None = None
+    status: PostingStatus = "draft"
+    tags: PostingTags | None = None
+    posted_at: datetime | None = None
+
+
+class Application(BaseModel):
+    """A learner's application to a posting (D-049 `application` table).
+    Unique (posting_id, learner_id) → duplicate apply is idempotent
+    200-with-existing (A-408/D-058). P1 status is always `submitted`;
+    richer states are post-v0.6.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    posting_id: str = Field(min_length=1)
+    learner_id: str = Field(min_length=1)
+    status: str = "submitted"
+    created_at: datetime | None = None
+
+
+class PostingPage(BaseModel):
+    """Published-only list response (G-103): the page + the honest
+    total so the board can render "Showing X of Y" over a paged
+    fetch-all without fabrication."""
+
+    postings: list[Posting]
+    total_published: int
+
+
+class IngestResult(BaseModel):
+    """Honest ingest run summary (founder surface)."""
+
+    postings_upserted: int = 0
+    employers_upserted: int = 0
+
+
+def posting_summary(posting: Posting) -> dict[str, Any]:
+    """Serialization helper shared by the list + detail responses — one
+    shape so the G-107 pin (no `matchScore` in any marketplace-path
+    payload) covers both surfaces."""
+    return posting.model_dump(mode="json")

apps/ai-service/ai_service/marketplace/embedding/__init__.py

@@ -0,0 +1,33 @@
+"""Marketplace embedding providers (D-051, REQ-6-003).
+
+Protocol + deterministic feature-hash mock + OpenAI-compatible real
+provider + factory. Mirrors the voice/ layout (base/mock/openai_compat/
+factory) — embeddings need NO descriptor: match scores are computed
+server-side in search.py, never shipped as client capability hints.
+"""
+
+from __future__ import annotations
+
+from .base import EmbeddingProvider, EmbeddingResult
+from .factory import UnknownEmbedProviderError, embedding_provider_from_settings
+from .mock import (
+    MOCK_EMBED_DIM,
+    MOCK_EMBED_MODEL,
+    MockEmbedProvider,
+    embed_text,
+    normalize_tokens,
+)
+from .openai_compat import OpenAIEmbedProvider
+
+__all__ = [
+    "MOCK_EMBED_DIM",
+    "MOCK_EMBED_MODEL",
+    "EmbeddingProvider",
+    "EmbeddingResult",
+    "MockEmbedProvider",
+    "OpenAIEmbedProvider",
+    "UnknownEmbedProviderError",
+    "embed_text",
+    "embedding_provider_from_settings",
+    "normalize_tokens",
+]

apps/ai-service/ai_service/marketplace/embedding/base.py

@@ -0,0 +1,46 @@
+"""EmbeddingProvider protocol + shared embedding contracts (D-051, REQ-6-003).
+
+Mirrors the D-030/D-014 provider seam: a narrow protocol the search
+pipeline and publish hooks compose via DI, with a deterministic
+feature-hash mock (pure stdlib) and an OpenAI-compatible real provider.
+No descriptor — unlike voice, embeddings are consumed SERVER-side only
+(match scores are computed in search.py, never shipped as capability
+hints), so there is nothing for a client to badge.
+
+Boundary (D-048): `marketplace/embedding/` never imports `agents/` or
+`api/`.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EmbeddingResult(BaseModel):
+    """One embedded text (D-051): the vector + its provenance.
+
+    `model`/`dim` ride every result so the store can persist per-row
+    provenance (A-403/A-404: lazy re-embed on provider change works).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    values: list[float] = Field(min_length=1)
+    model: str = Field(min_length=1)
+    dim: int = Field(ge=1)
+
+
+@runtime_checkable
+class EmbeddingProvider(Protocol):
+    """The embedding port (D-051): texts in, vectors out. Never imports
+    agents/api; never stores anything (storage is the store's job)."""
+
+    async def embed(self, texts: list[str]) -> list[EmbeddingResult]:
+        """Embed a batch of texts; result[i] corresponds to texts[i].
+
+        Implementations MUST be deterministic per provider config so
+        stored vectors stay comparable across re-embeds.
+        """
+        ...

apps/ai-service/ai_service/marketplace/embedding/factory.py

@@ -0,0 +1,66 @@
+"""Embedding provider factory (D-051, REQ-6-003).
+
+`AI_EMBED_PROVIDER = mock | openai-embed` (default: mock — the no-key
+path is first-class; tests never call a real embeddings API).
+`openai-embed` requires embed_base_url + embed_api_key + embed_model:
+the factory raises `UnknownEmbedProviderError` with an actionable
+message for direct callers (tests), while the lifespan in main.py
+CATCHES it and falls back to mock with a loud log — a typo'd env must
+never crash the unattended boot (G-11; the exact voice/factory.py
+pattern).
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from ...config import Settings
+from .base import EmbeddingProvider
+from .mock import MockEmbedProvider
+from .openai_compat import OpenAIEmbedProvider
+
+
+class UnknownEmbedProviderError(ValueError):
+    """Raised for a provider name outside the contract, or a real provider
+    selected without its required configuration."""
+
+
+def embedding_provider_from_settings(
+    settings: Settings, http_client: httpx.AsyncClient | None = None
+) -> EmbeddingProvider:
+    """Select the embedding provider by settings (env `AI_EMBED_PROVIDER`).
+
+    `http_client` is required for the `openai-embed` branch (D-017 shared
+    pool); mock ignores it.
+    """
+    name = (settings.embed_provider or "mock").strip().lower()
+    if name == "mock":
+        return MockEmbedProvider()
+    if name in ("openai-embed", "openai", "server"):
+        if (
+            not settings.embed_base_url
+            or not settings.embed_api_key.get_secret_value()
+            or not settings.embed_model
+        ):
+            raise UnknownEmbedProviderError(
+                "AI_EMBED_PROVIDER=openai-embed requires AI_EMBED_BASE_URL, "
+                "AI_EMBED_API_KEY, and AI_EMBED_MODEL — set all three, or use "
+                "'mock'. NOTE (D-051 probe): ollama-cloud does NOT expose "
+                "/embeddings; point AI_EMBED_BASE_URL at another "
+                "OpenAI-compatible endpoint (e.g. local ollama :11434/v1). "
+                "(main.py falls back to mock when these are missing — G-11)"
+            )
+        if http_client is None:
+            raise UnknownEmbedProviderError(
+                "openai-embed requires the shared httpx client "
+                "(embedding_provider_from_settings(settings, http_client))"
+            )
+        return OpenAIEmbedProvider(
+            http_client=http_client,
+            base_url=settings.embed_base_url,
+            api_key=settings.embed_api_key.get_secret_value(),
+            model=settings.embed_model,
+        )
+    raise UnknownEmbedProviderError(
+        f"unknown AI_EMBED_PROVIDER {name!r}: use 'mock' or 'openai-embed'"
+    )

apps/ai-service/ai_service/marketplace/embedding/mock.py

@@ -0,0 +1,102 @@
+"""Deterministic MockEmbedProvider (D-051, REQ-6-003).
+
+256-dim feature-hash of normalized tokens — pure stdlib (hashlib, math;
+NO numpy, NO python hash() — the builtin is salted per process).
+Same text → identical vector, ALWAYS (across processes, reboots,
+machines). Related texts share tokens → higher cosine than unrelated
+texts, so pinned similarity numbers stay meaningful in tests.
+
+Algorithm (documented — search.py's skill_breakdown depends on it):
+1. normalize: lowercase, split on non-alphanumeric ([^a-z0-9]+)
+2. every token hashes (SHA-256 of its UTF-8 bytes) to an index
+   idx = int.from_bytes(digest[:4], "little") % 256
+3. sign alternation on token-position collisions: the k-th OCCURRENCE
+   of a token at the same index flips sign — (+1, -1, +1, ...) — so
+   repeated tokens cannot monotonically inflate one component
+   (hash("ab") == hash("ba") collisions cancel, not stack).
+   occurrence = the token's own prior count at that index.
+4. accumulate counts into the 256-dim vector
+5. L2-normalize (a zero vector — no tokens — stays all-zeros so the
+   cosine guard in search.py can be exercised; honest, never a fabricated
+   direction).
+
+`embed` embeds the WHOLE batch in one call (no state between calls —
+per-text vectors are independent), returning EmbeddingResult rows with
+model="mock-feature-hash-256".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+
+from .base import EmbeddingProvider, EmbeddingResult
+
+#: The mock's fixed dimensionality (D-051) — also its model identity.
+MOCK_EMBED_DIM = 256
+MOCK_EMBED_MODEL = "mock-feature-hash-256"
+
+_SPLIT = re.compile(r"[^a-z0-9]+")
+
+
+def normalize_tokens(text: str) -> list[str]:
+    """lowercase + split on non-alphanumeric; empty pieces dropped."""
+    return [tok for tok in _SPLIT.split(text.lower()) if tok]
+
+
+def token_index(token: str) -> int:
+    """Stable, process-independent index: first 4 SHA-256 digest bytes,
+    little-endian, mod 256 (never the salted builtin hash())."""
+    digest = hashlib.sha256(token.encode("utf-8")).digest()
+    return int.from_bytes(digest[:4], "little") % MOCK_EMBED_DIM
+
+
+def embed_text(text: str) -> list[float]:
+    """The deterministic feature-hash vector for one text (pure function).
+
+    Exposed for search.py's per-skill contribution shares — the same
+    formula must produce the mock's vectors and the breakdown math.
+    """
+    vec = [0.0] * MOCK_EMBED_DIM
+    for token in normalize_tokens(text):
+        idx = token_index(token)
+        # Sign alternation per token OCCURRENCE at its index: the token's
+        # own running count at idx (not its position in the text).
+        vec[idx] += 1.0 if vec[idx] >= 0 else -1.0 if vec[idx] <= 0 else 0.0
+    # L2-normalize; all-zero (no tokens) stays all-zero (honest zero
+    # vector — the cosine guard downstream treats it as unrankable).
+    norm = math.sqrt(sum(v * v for v in vec))
+    if norm > 0.0:
+        vec = [v / norm for v in vec]
+    return vec
+
+
+class MockEmbedProvider:
+    """Deterministic 256-dim feature-hash embedding (D-051 mock).
+
+    Cloud-free by construction; identical inputs → identical outputs
+    forever (hashlib-based, no PYTHONHASHSEED dependence)."""
+
+    model = MOCK_EMBED_MODEL
+    dim = MOCK_EMBED_DIM
+
+    async def embed(self, texts: list[str]) -> list[EmbeddingResult]:
+        return [
+            EmbeddingResult(
+                values=embed_text(text),
+                model=MOCK_EMBED_MODEL,
+                dim=MOCK_EMBED_DIM,
+            )
+            for text in texts
+        ]
+
+
+# Protocol-shape parity guard (mock must satisfy the D-051 port).
+
+
+def _assert_protocol() -> None:
+    assert isinstance(MockEmbedProvider(), EmbeddingProvider)
+
+
+_assert_protocol()

apps/ai-service/ai_service/marketplace/embedding/openai_compat.py

@@ -0,0 +1,94 @@
+"""OpenAI-compatible embedding provider (D-051, REQ-6-003).
+
+One implementation serves any OpenAI-compatible embeddings endpoint:
+`POST {base_url}/embeddings` with `{"model", "input": [texts]}` →
+`{"data": [{"embedding": [...]}, ...], "model": ...}`. Raw httpx on the
+shared lifespan client (D-017). base_url is config, never code — the
+D-014 endpoint-agnostic pattern.
+
+PROBE CORRECTION (D-051): ollama-cloud does NOT expose /embeddings
+(404 path-not-found) — AI_EMBED_BASE_URL must point at another
+OpenAI-compatible endpoint (e.g. LOCAL ollama at :11434/v1, which does).
+
+Boundary rules (mirror voice/openai_audio.py):
+- embedding/ imports nothing from agents/ or api/
+- api_key NEVER appears in exceptions, logs, or error messages
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from .base import EmbeddingResult
+
+
+class OpenAIEmbedProvider:
+    """POST {base_url}/embeddings {"model", "input": [texts]}."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient,
+        base_url: str,
+        api_key: str,
+        model: str = "",
+    ) -> None:
+        self._client = http_client
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._model = model
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    def _sanitize(self, exc: Exception) -> RuntimeError:
+        text = str(exc)
+        if self._api_key and self._api_key in text:
+            text = text.replace(self._api_key, "[REDACTED]")
+        return RuntimeError(f"embedding provider error: {text}")
+
+    async def embed(self, texts: list[str]) -> list[EmbeddingResult]:
+        """Batch-embed texts; result[i] corresponds to texts[i].
+
+        Parses the OpenAI-format response: `{"data": [{"embedding":
+        [...]}], "model": ...}` — index-order preserved (the spec orders
+        data by input position).
+        """
+        payload = {"model": self._model, "input": list(texts)}
+        try:
+            resp = await self._client.post(
+                f"{self._base_url}/embeddings",
+                json=payload,
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            body = resp.json()
+        except httpx.HTTPError as exc:
+            raise self._sanitize(exc) from exc
+        if not isinstance(body, dict):
+            raise RuntimeError(
+                "embedding provider error: unexpected embeddings response shape"
+            )
+        data = body.get("data")
+        if not isinstance(data, list) or len(data) != len(texts):
+            raise RuntimeError(
+                "embedding provider error: embeddings response/data length "
+                f"mismatch (expected {len(texts)} entries)"
+            )
+        model = str(body.get("model") or self._model)
+        results: list[EmbeddingResult] = []
+        for entry in data:
+            if not isinstance(entry, dict) or not isinstance(
+                entry.get("embedding"), list
+            ):
+                raise RuntimeError(
+                    "embedding provider error: embeddings response/data entry "
+                    "missing the 'embedding' array"
+                )
+            values = [float(v) for v in entry["embedding"]]
+            results.append(
+                EmbeddingResult(values=values, model=model, dim=len(values))
+            )
+        return results

apps/ai-service/ai_service/marketplace/enrichment.py

@@ -0,0 +1,215 @@
+"""Employer enrichment (REQ-6-004, D-053, A-409).
+
+One-shot LLM extraction of employer description/social-links/logo from
+the employer's own posting data, composed through the D-020 pipeline
+(the D-052 tagging pattern) — no new agent. Enrichment rows are
+APPEND-ONLY with per-field provenance; merge-on-read precedence is
+manual > llm > ingested-raw, and every enriched field carries a
+visible {value, source} marker in API responses (A-304 honesty —
+LLM-authored copy is never displayed as ingested fact).
+
+Trigger semantics (enrich-on-first-publish approximation): the publish
+route fires enrichment when the employer has NO existing llm-source
+rows — re-publishing the same employer does not re-run (the rows
+exist). Failure is honest: a warning logs, the publish still succeeds,
+no rows are written.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from pydantic import BaseModel, ConfigDict
+
+from ..agents.structured import structured_completion
+from ..llm.base import LLMProvider
+from ..llm.types import Message
+from .base import Employer
+from .store import MarketplaceStore
+
+logger = logging.getLogger(__name__)
+
+#: Prompt version — bump on any wording change (prompts are code).
+ENRICHMENT_PROMPT_VERSION = 1
+
+ENRICHMENT_PROMPT = """You are an employer-profile writer for an AI-era
+roles marketplace. From the employer's own data below, write concise
+factual profile copy.
+
+Rules:
+- description: 1-3 sentences summarizing what the company does, grounded
+  ONLY in the provided data — never invent employers, products, or
+  numbers.
+- social_links: an object of platform → URL, ONLY for platforms the
+  data names (website, github, linkedin, twitter/x). Empty object if
+  none.
+- logo_ref: a short reference to the logo source named in the data
+  (e.g. a URL or file name); empty string if none.
+
+Respond with ONLY the JSON object."""
+
+_SCHEMA_HINT = (
+    '{"description": "1-3 sentence string", '
+    '"social_links": {"platform": "url"}, '
+    '"logo_ref": "string"}'
+)
+
+#: The enrichable field set (D-053) — the manual-override route validates
+#: against this and the merge walks exactly these keys.
+ENRICHABLE_FIELDS = ("description", "social_links", "logo")
+
+_PRECEDENCE = ("manual", "llm")
+
+
+class EnrichmentUnavailable(Exception):
+    """The extractor could not produce valid enrichment (provider/parse
+    failure). The publish proceeds; no rows are written (D-053 honesty)."""
+
+
+class EnrichmentPayload(BaseModel):
+    """The D-020 extraction schema. extra=forbid keeps the honesty
+    contract (the verifier P2-3 lesson): a non-matching LLM reply must
+    fail validation, not silently parse as all-defaults."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    description: str = ""
+    social_links: dict[str, str] = {}
+    logo_ref: str = ""
+
+async def enrich_employer(
+    provider: LLMProvider,
+    *,
+    model: str,
+    employer: Employer,
+    postings_hint: list[str] | None = None,
+) -> EnrichmentPayload:
+    """One-shot profile extraction via D-020 structured completion.
+
+    `postings_hint` (the employer's posting titles) grounds the copy in
+    the employer's own data. Failures raise EnrichmentUnavailable —
+    honest, never a crash, never fabricated copy."""
+    hint = ""
+    if postings_hint:
+        hint = "\nPosting titles: " + "; ".join(postings_hint[:10])
+    messages = [
+        Message(role="system", content=ENRICHMENT_PROMPT),
+        Message(
+            role="user",
+            content=(
+                f"Employer name: {employer.name}\n"
+                f"Industry: {employer.industry}\n"
+                f"Known description: {employer.description}\n"
+                f"Website: {employer.website}\n"
+                f"Social links: {json.dumps(employer.social_links)}\n"
+                f"Logo: {employer.logo}{hint}"
+            ),
+        ),
+    ]
+    try:
+        return await structured_completion(
+            provider,
+            messages,
+            model=model,
+            schema=EnrichmentPayload,
+            schema_hint=_SCHEMA_HINT,
+        )
+    except Exception as exc:
+        logger.warning(
+            "marketplace enrichment failed for %r: %s — no rows written "
+            "(honest absence, never fabricated copy)",
+            employer.name[:60],
+            exc,
+        )
+        raise EnrichmentUnavailable(str(exc)) from exc
+
+
+def merge_employer(
+    employer: Employer, rows: list[dict]
+) -> dict[str, dict]:
+    """Merge-on-read with per-field provenance (D-053/A-409).
+
+    Precedence per FIELD: manual > llm > ingested-raw — a manual
+    description + llm social_links is legal. Every field carries
+    {value, source, model?}; `social_links` values are dicts (the row
+    stores JSON), the others strings. Newest row per (field, source)
+    wins within a source (append-only, newest-last).
+    """
+    best: dict[str, dict] = {}
+    for row in rows:
+        field = row.get("field")
+        if field not in ENRICHABLE_FIELDS:
+            continue
+        source = row.get("source")
+        rank = _PRECEDENCE.index(source) if source in _PRECEDENCE else len(_PRECEDENCE)
+        existing = best.get(field)
+        if existing is None or rank < existing["_rank"]:
+            best[field] = {
+                "_rank": rank,
+                "value": row.get("value"),
+                "source": source,
+                "model": row.get("model") or None,
+            }
+    merged: dict[str, dict] = {}
+    for field in ENRICHABLE_FIELDS:
+        raw_value = {
+            "description": employer.description,
+            "social_links": dict(employer.social_links),
+            "logo": employer.logo,
+        }[field]
+        if field in best:
+            entry = best[field]
+            merged[field] = {
+                "value": entry["value"],
+                "source": entry["source"],
+                "model": entry["model"],
+            }
+        else:
+            # No enrichment rows for this field — the ingested raw value
+            # with the honest raw marker (A-304: LLM copy never
+            # masquerades as ingested fact, and vice versa).
+            merged[field] = {"value": raw_value, "source": "raw", "model": None}
+    return merged
+
+
+async def maybe_enrich_on_publish(
+    store: MarketplaceStore,
+    provider: LLMProvider,
+    *,
+    model: str,
+    employer_id: str,
+) -> bool:
+    """Enrich-on-first-publish trigger: fires when the employer has NO
+    existing llm-source rows (re-publishing does not re-run — the rows
+    exist). Returns True when enrichment rows landed. Failures are
+    honest: warning + False, the publish itself already succeeded."""
+    if store.count_enrichment(employer_id, source="llm") > 0:
+        return False
+    employer = store.get_employer(employer_id)
+    if employer is None:
+        return False  # dangling employer ref (the seed carries 3) — skip
+    titles = store.employer_posting_titles(employer_id)
+    try:
+        payload = await enrich_employer(
+            provider, model=model, employer=employer, postings_hint=titles
+        )
+    except EnrichmentUnavailable:
+        return False
+    stamp = {"model": model}
+    rows = [
+        ("description", payload.description, "llm", stamp),
+        (
+            "social_links",
+            json.dumps(payload.social_links),
+            "llm",
+            stamp,
+        ),
+        ("logo", payload.logo_ref, "llm", stamp),
+    ]
+    for field, value, source, meta in rows:
+        if value not in ("", "{}"):
+            store.append_enrichment(
+                employer_id, field=field, value=value, source=source, **meta
+            )
+    return True

apps/ai-service/ai_service/marketplace/ingest.py

@@ -0,0 +1,97 @@
+"""PostingSource adapters + ingest runner (REQ-6-001, D-050, A-402).
+
+`PostingSource` is the adapter port: `fetch() -> Iterable[IngestPosting]`.
+v0.6 ships ONE implementation, `SeededCorpusSource` over the in-repo
+`seed_corpus.json` (ported ONCE from packages/mock-data/jobs.ts +
+employers.ts per D-021 — shared ids, mock matchScore DROPPED: D-051
+computes real scores at search time, G-106/G-107). The 3M+ external
+corpus lands later as a third adapter with zero store/route changes.
+
+Ingest-status contract (G-102): SEED-PORT postings enter as `published`
+with their ORIGINAL postedAt — otherwise the board/facets/P1's success
+criterion sit empty after ingest. ADMIN-AUTHORED postings start
+`draft` (the admin route's create path, not this runner).
+
+No scheduler/crawler (A-401/A-402): ingest runs when the founder POSTs
+/v1/marketplace/admin/ingest; `run_ingest` is idempotent on
+(source, external_id) — a double-run yields identical row counts.
+
+Boundary (D-048): never imports `agents/` or `api/`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .base import Employer, IngestPosting, IngestResult
+from .store import MarketplaceStore
+
+logger = logging.getLogger(__name__)
+
+#: The ported TS fixture corpus ships IN THE PACKAGE (importlib-free
+#: path resolution: this file's parent) — one JSON file, no codegen.
+_SEED_PATH = Path(__file__).resolve().parent / "seed_corpus.json"
+
+
+@runtime_checkable
+class PostingSource(Protocol):
+    """The ingest port (D-050): yields IngestPosting payloads. Employers
+    ride the corpus alongside postings (the seeded source exposes both;
+    a pure-posting adapter simply fetches postings and leaves employers
+    to a separate source)."""
+
+    def fetch(self) -> Iterable[IngestPosting]:
+        ...
+
+    def fetch_employers(self) -> Iterable[Employer]:
+        ...
+
+
+class SeededCorpusSource:
+    """The seeded corpus adapter over seed_corpus.json (D-050).
+
+    Pure + deterministic: reads the JSON fixture once per fetch; the
+    runner upserts idempotently. Raw fields map 1:1 from the TS shapes
+    (camelCase → snake_case port, matchScore dropped — G-102/G-107)."""
+
+    def __init__(self, path: Path = _SEED_PATH) -> None:
+        self._path = path
+
+    def _load(self) -> dict:
+        with self._path.open(encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def fetch(self) -> Iterable[IngestPosting]:
+        for raw in self._load().get("postings", []):
+            yield IngestPosting.model_validate(raw)
+
+    def fetch_employers(self) -> Iterable[Employer]:
+        for raw in self._load().get("employers", []):
+            yield Employer.model_validate(raw)
+
+
+def run_ingest(source: PostingSource, store: MarketplaceStore) -> IngestResult:
+    """Idempotent upsert run: every (source, external_id) overwrites its
+    row in place — a second run yields identical counts (MH-1b)."""
+
+    result = IngestResult()
+    # Employers first: postings reference employer ids (no FK today, but
+    # the reference ordering keeps the board honest mid-run).
+    for employer in source.fetch_employers():
+        store.upsert_employer(employer)
+        result.employers_upserted += 1
+    for posting in source.fetch():
+        # G-102: seed-port postings enter PUBLISHED with their original
+        # postedAt (the IngestPosting carries it verbatim).
+        store.upsert_posting(posting, status="published")
+        result.postings_upserted += 1
+    logger.info(
+        "marketplace ingest: %s postings, %s employers (idempotent upserts)",
+        result.postings_upserted,
+        result.employers_upserted,
+    )
+    return result

apps/ai-service/ai_service/marketplace/resume.py

@@ -0,0 +1,155 @@
+"""Resume → profile draft extraction (REQ-6-005, D-054, A-410).
+
+Pipeline: upload guard (PDF/TXT/MD only, ≤2 MB, text-layer required —
+empty pypdf extract → honest 422, NO OCR in v0.6) → text extraction →
+~100K char cap → D-020 structured extraction into ParsedProfile →
+response carries status="draft" — NOTHING persists to the learner
+profile until the explicit confirm route (the REQ-6-005 review gate).
+
+Raw resume bytes are never stored, never logged (A-305 pattern; the
+existing _scrub_pii_validation handler precedent). The only new
+dependency is pypdf (probe-verified 6.19.0, pip-reachable via the
+venv channel).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..agents.structured import structured_completion
+from ..llm.base import LLMProvider
+from ..llm.types import Message
+
+logger = logging.getLogger(__name__)
+
+#: Prompt version — bump on any wording change (prompts are code).
+RESUME_PROMPT_VERSION = 1
+
+#: Upload bounds (A-410).
+MAX_RESUME_BYTES = 2 * 1024 * 1024  # 2 MB
+ALLOWED_CONTENT_TYPES = ("pdf", "txt", "md")
+#: Extracted-text cap before the LLM call (A-410: ~100K chars).
+MAX_EXTRACTED_CHARS = 100_000
+
+RESUME_PROMPT = """You are a profile parser for an AI-era skills
+platform. Extract structured profile data from the resume text.
+
+Rules:
+- name: the person's name as written, or "" if absent.
+- headline: a one-line professional headline, or "".
+- skills: up to 20 concrete skills named in the resume (lowercase,
+  the resume's own vocabulary preferred).
+- experience_bands: list of {role, years} objects — years is a number
+  (round down; 0 if under a year); [] if none determinable.
+- competencies: up to 10 competency areas the resume evidences, each a
+  short noun phrase; [] if none.
+
+Respond with ONLY the JSON object."""
+
+_SCHEMA_HINT = (
+    '{"name": "string", "headline": "string", '
+    '"skills": ["up to 20 lowercase strings"], '
+    '"experience_bands": [{"role": "string", "years": 0}], '
+    '"competencies": ["up to 10 short phrases"]}'
+)
+
+
+class ExperienceBand(BaseModel):
+    """One role/tenure band the resume evidences."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    role: str = ""
+    years: float = 0
+
+
+class ParsedProfile(BaseModel):
+    """The D-020 extraction schema mapped to the competency-profile
+    shape (D-054). extra=forbid keeps the honesty contract — a
+    non-matching reply fails validation, never silently all-defaults
+    (the verifier P2-3 lesson)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str = ""
+    headline: str = ""
+    skills: list[str] = Field(default_factory=list, max_length=20)
+    experience_bands: list[ExperienceBand] = Field(default_factory=list)
+    competencies: list[str] = Field(default_factory=list, max_length=10)
+
+
+class ResumeFormatError(Exception):
+    """Honest upload rejection (422 at the route): unsupported format,
+    missing text layer (empty PDF extract — no OCR in v0.6), or empty
+    file."""
+
+
+def extract_resume_text(data: bytes, content_type: str) -> str:
+    """Extract text from an uploaded resume (A-410 bounds enforced by
+    the route BEFORE this call; this handles the decode/parse).
+
+    PDF via pypdf page-text join; TXT/MD raw decode. An empty PDF
+    extract raises ResumeFormatError("text layer required") — the
+    honest no-OCR contract. Raises ResumeFormatError on garbage text
+    bytes too (the honest 422, never a 500)."""
+    ctype = content_type.strip().lower()
+    # Accept both bare and full content types ("application/pdf").
+    if "pdf" in ctype or ctype == "pdf":
+        from io import BytesIO
+
+        from pypdf import PdfReader
+
+        try:
+            reader = PdfReader(BytesIO(data))
+            pages = [(page.extract_text() or "") for page in reader.pages]
+        except Exception as exc:
+            raise ResumeFormatError(
+                "could not read the PDF — is it a valid PDF file?"
+            ) from exc
+        text = "\n".join(pages)
+        if not text.strip():
+            raise ResumeFormatError(
+                "text layer required — image-only/scanned PDFs are not "
+                "supported (no OCR in v0.6); upload a text-based PDF, "
+                "TXT, or MD file"
+            )
+        return text
+    if "markdown" in ctype or ctype in ("txt", "md", "text/plain", "text/markdown"):
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ResumeFormatError(
+                "could not decode the file as UTF-8 text"
+            ) from exc
+        if not text.strip():
+            raise ResumeFormatError("file has no text content")
+        return text
+    raise ResumeFormatError(
+        f"unsupported resume format {content_type!r} — PDF, TXT, or MD only"
+    )
+
+
+async def parse_resume(
+    provider: LLMProvider,
+    *,
+    model: str,
+    text: str,
+) -> ParsedProfile:
+    """Draft extraction via D-020 (never persists — the confirm route
+    is the only write path, D-054/REQ-6-005 review gate)."""
+    capped = text[:MAX_EXTRACTED_CHARS]
+    messages = [
+        Message(role="system", content=RESUME_PROMPT),
+        Message(role="user", content=f"Resume text:\n{capped}"),
+    ]
+    # Raw resume text never logs (A-305): only the failure reason rides
+    # the warning below — structured_completion raises on its own path.
+    return await structured_completion(
+        provider,
+        messages,
+        model=model,
+        schema=ParsedProfile,
+        schema_hint=_SCHEMA_HINT,
+    )

apps/ai-service/ai_service/marketplace/search.py

@@ -0,0 +1,250 @@
+"""Hybrid facet+cosine search over published postings (REQ-6-003, A-405).
+
+Pure-Python cosine (sum of products / norm product; ≤10⁴ postings —
+NO numpy, A-403). Hybrid ordering per D-059: facet hard-filters
+SQL-side on portable columns FIRST, then cosine ranking over the
+filtered set; no facets → pure semantic rank over all published
+postings.
+
+Candidate side: the query text embeds ON DEMAND via the provider and
+is NEVER stored (A-404 — only posting vectors persist).
+
+Lazy re-embed (A-403/A-404): a stored row whose model/dim ≠ the
+provider's current model/dim is re-embedded + re-stored on access, so
+a provider switch self-heals the corpus row-by-row without a
+backfill pass.
+
+skill_breakdown formula (deterministic, documented for the pin):
+- overlap = does the skill string (normalized: lowercase, split on
+  non-alphanumeric, rejoined) share a token with the QUERY's normalized
+  token set → overlap ∈ {0, 1}
+- contribution = the share of the posting-vector dot-product carried by
+  the skill's own feature-hash tokens: for the mock provider,
+  contribution(skill) = Σ_components of mock.embed_text(skill) mapped
+  to the same (index, sign) bucket in the mock formula — computed as
+  cosine(embed_text(skill), posting_vector) when overlap=1, else 0.0.
+  Both operands are mock-formula vectors, so the number is
+  deterministic and provider-independent to pin (with the openai-embed
+  provider the contribution uses the SAME skill-text side via the
+  provider on demand; the mock pin is the MH-3f pin).
+
+Boundary (D-048): never imports `agents/` or `api/`.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass, field
+
+from .base import Posting
+from .embedding.base import EmbeddingProvider, EmbeddingResult
+from .embedding.mock import embed_text as _mock_embed_text
+from .embedding.mock import normalize_tokens as _normalize
+from .store import MarketplaceStore
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class FacetFilters:
+    """Hard filters applied SQL-side BEFORE ranking (A-405). Any facet
+    may be empty — an empty filter set means pure semantic rank."""
+
+    skills: list[str] = field(default_factory=list)
+    seniority: str | None = None
+    category: str | None = None
+    location: str | None = None
+    remote: bool | None = None
+    salary_min: int | None = None
+    salary_max: int | None = None
+
+
+@dataclass(frozen=True)
+class RankedPosting:
+    """One ranked search result. `match_score` is the computed cosine
+    (G-106: computed scores exist ONLY in search context)."""
+
+    posting: Posting
+    score: float
+    skill_breakdown: list[dict]
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Pure-Python cosine: sum(a·b) / (‖a‖·‖b‖); 0.0 on a zero vector
+    (guard: an unrankable vector scores an honest zero, never a
+    ZeroDivisionError) or a length mismatch (defensive — the store
+    codec enforces dim parity)."""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = 0.0
+    norm_a = 0.0
+    norm_b = 0.0
+    for x, y in zip(a, b, strict=False):
+        dot += x * y
+        norm_a += x * x
+        norm_b += y * y
+    if norm_a <= 0.0 or norm_b <= 0.0:
+        return 0.0
+    return dot / math.sqrt(norm_a * norm_b)
+
+
+def posting_embedding_text(posting: Posting) -> str:
+    """D-051 posting text: title + description + tag skills joined —
+    the P2 tags ride the vector so facets and semantics agree."""
+    parts = [posting.title, posting.description or ""]
+    if posting.tags and posting.tags.skills:
+        parts.extend(posting.tags.skills)
+    return "\n".join(p for p in parts if p)
+
+
+async def embed_posting(
+    store: MarketplaceStore, provider: EmbeddingProvider, posting: Posting
+) -> bool:
+    """Embed-on-publish hook (Task 3-2-01): embed the posting text and
+    store the vector. Failure is HONEST, never fatal: returns False with
+    a logged warning — the posting still publishes, search skips it
+    (no stored vector = honest absence, never a fabricated direction)."""
+    try:
+        results = await provider.embed([posting_embedding_text(posting)])
+        result = results[0]
+        store.put_vector(posting.id, result.values, result.model, result.dim)
+        return True
+    except Exception as exc:
+        logger.warning(
+            "marketplace embedding failed for posting %r: %s — posting stays "
+            "published WITHOUT a vector (search skips it, honest absence)",
+            posting.id,
+            exc,
+        )
+        return False
+
+
+async def _current_embedding(
+    provider: EmbeddingProvider, text: str
+) -> EmbeddingResult:
+    """Embed one text via the provider (candidate side: on demand,
+    never stored)."""
+    results = await provider.embed([text])
+    return results[0]
+
+
+async def rank_postings(
+    store: MarketplaceStore,
+    provider: EmbeddingProvider,
+    query_text: str,
+    facet_filters: FacetFilters | None = None,
+    limit: int = 20,
+) -> list[RankedPosting]:
+    """Hybrid rank (A-405): facets hard-filter SQL-side first, then
+    cosine ranking DESC over the filtered set.
+
+    - empty query → facet-only listing ordered by posted_at DESC (no
+      query → no match scores — G-106 honesty; scores are 0.0 and the
+      route reports match_score: null).
+    - postings whose stored model/dim ≠ the provider's are re-embedded
+      + re-stored lazily (A-403/A-404).
+    - postings with NO stored vector are SKIPPED (honest absence — an
+      embed-on-publish failure must not fabricate a direction).
+    """
+    filters = facet_filters or FacetFilters()
+    candidates = store.search_candidates(
+        skills=filters.skills or None,
+        seniority=filters.seniority,
+        category=filters.category,
+        location=filters.location,
+        remote=filters.remote,
+        salary_min=filters.salary_min,
+        salary_max=filters.salary_max,
+    )
+    if not query_text.strip():
+        # Facet-only listing: posted_at DESC (the list_postings order),
+        # no match scores — the route carries match_score: null.
+        return [
+            RankedPosting(posting=p, score=0.0, skill_breakdown=[])
+            for p in candidates[:limit]
+        ]
+
+    query_result = await _current_embedding(provider, query_text)
+    q_values = query_result.values
+    q_tokens = set(_normalize(query_text))
+    q_model = query_result.model
+    q_dim = query_result.dim
+
+    # Lazy re-embed: collect stale rows (model/dim ≠ provider's) and
+    # refresh them in one batch before ranking.
+    stale: list[Posting] = [
+        p for p in candidates if _is_stale(store, p.id, q_model, q_dim)
+    ]
+    if stale:
+        texts = [posting_embedding_text(p) for p in stale]
+        try:
+            refreshed = await provider.embed(texts)
+            for posting, result in zip(stale, refreshed, strict=True):
+                store.put_vector(posting.id, result.values, result.model, result.dim)
+        except Exception as exc:  # honest: stale rows keep old vectors
+            logger.warning(
+                "lazy re-embed of %s postings failed (%s) — ranking against "
+                "existing vectors",
+                len(stale),
+                exc,
+            )
+
+    ranked: list[RankedPosting] = []
+    for posting in candidates:
+        stored = store.get_vector(posting.id)
+        if stored is None:
+            continue  # embed-on-publish failed → honest skip
+        values, model, dim = stored
+        if (model, dim) != (q_model, q_dim):
+            continue  # re-embed failed above → incomparable, honest skip
+        score = cosine_similarity(q_values, values)
+        ranked.append(
+            RankedPosting(
+                posting=posting,
+                score=score,
+                skill_breakdown=skill_breakdown(posting, q_tokens, values),
+            )
+        )
+    ranked.sort(key=lambda r: (-r.score, r.posting.id))
+    return ranked[:limit]
+
+
+def _is_stale(
+    store: MarketplaceStore, posting_id: str, model: str, dim: int
+) -> bool:
+    stored = store.get_vector(posting_id)
+    if stored is None:
+        return False  # absent ≠ stale (no direction to refresh)
+    _, row_model, row_dim = stored
+    return (row_model, row_dim) != (model, dim)
+
+
+def skill_breakdown(
+    posting: Posting, query_tokens: set[str], posting_vector: list[float]
+) -> list[dict]:
+    """Per-skill explanation (MH-3f): tag-skill overlap with the query
+    + the skill's vector contribution — both deterministic.
+
+    overlap: 1 when any normalized token of the skill string appears
+    in the query's normalized token set, else 0.
+    contribution: cosine(embed_text(skill), posting_vector) when
+    overlap=1 — the mock feature-hash formula's share of the posting
+    dot-product that the skill's own tokens carry; 0.0 otherwise.
+    Sorted by contribution DESC then skill ASC (deterministic order).
+    """
+    skills: list[str] = list(posting.tags.skills) if posting.tags else []
+    breakdown: list[dict] = []
+    for skill in skills:
+        tokens = _normalize(skill)
+        overlap = 1 if any(t in query_tokens for t in tokens) else 0
+        contribution = 0.0
+        if overlap:
+            contribution = cosine_similarity(
+                _mock_embed_text(skill), posting_vector
+            )
+        breakdown.append(
+            {"skill": skill, "overlap": overlap, "contribution": contribution}
+        )
+    breakdown.sort(key=lambda e: (-e["contribution"], e["skill"]))
+    return breakdown

apps/ai-service/ai_service/marketplace/seed_corpus.json

@@ -0,0 +1,695 @@
+{
+  "employers": [
+    {
+      "id": "emp-openai",
+      "source": "seed-corpus",
+      "external_id": "emp-openai",
+      "name": "OpenAI Labs",
+      "logo": "https://placehold.co/80x80/indigo/white?text=OA",
+      "description": "Mock employer building frontier AI systems. We build and deploy large language models and agentic tools used by millions of developers and consumers.",
+      "industry": "Artificial Intelligence",
+      "size": "2,000+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/openai",
+      "social_links": {
+        "twitter": "https://example.com/openai/x",
+        "linkedin": "https://example.com/openai/li"
+      },
+      "culture": "Research-driven, shipping-paced, safety-conscious. We pair frontier research with product rigor."
+    },
+    {
+      "id": "emp-anthropic",
+      "source": "seed-corpus",
+      "external_id": "emp-anthropic",
+      "name": "Anthropic Research",
+      "logo": "https://placehold.co/80x80/amber/white?text=AN",
+      "description": "Mock employer focused on AI safety and alignment. We build reliable, interpretable, and steerable AI systems.",
+      "industry": "AI Safety",
+      "size": "1,000+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/anthropic",
+      "social_links": {
+        "twitter": "https://example.com/anthropic/x",
+        "linkedin": "https://example.com/anthropic/li"
+      },
+      "culture": "Safety-first, evidence-based, calm-paced. We value thoroughness over speed when stakes are high."
+    },
+    {
+      "id": "emp-huggingface",
+      "source": "seed-corpus",
+      "external_id": "emp-huggingface",
+      "name": "Hugging Face",
+      "logo": "https://placehold.co/80x80/yellow/black?text=HF",
+      "description": "Mock employer building the open-source AI community. We host models, datasets, and demos for the global ML community.",
+      "industry": "Open Source AI",
+      "size": "500+",
+      "location": "New York, NY",
+      "website": "https://example.com/hf",
+      "social_links": {
+        "twitter": "https://example.com/hf/x",
+        "linkedin": "https://example.com/hf/li"
+      },
+      "culture": "Community-first, open-by-default, remote-friendly. We ship in the open with thousands of contributors."
+    },
+    {
+      "id": "emp-scaleai",
+      "source": "seed-corpus",
+      "external_id": "emp-scaleai",
+      "name": "Scale AI",
+      "logo": "https://placehold.co/80x80/violet/white?text=SC",
+      "description": "Mock employer providing data and evaluation infrastructure for frontier AI. We power the RLHF and eval pipelines behind many model releases.",
+      "industry": "AI Infrastructure",
+      "size": "1,500+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/scale",
+      "social_links": {
+        "twitter": "https://example.com/scale/x",
+        "linkedin": "https://example.com/scale/li"
+      },
+      "culture": "Infrastructure-minded, quality-obsessed, enterprise-aware. We bridge research and production data."
+    },
+    {
+      "id": "emp-perplexity",
+      "source": "seed-corpus",
+      "external_id": "emp-perplexity",
+      "name": "Perplexity",
+      "logo": "https://placehold.co/80x80/teal/white?text=PX",
+      "description": "Mock employer building an AI-powered answer engine. We combine retrieval, generation, and citations for trustworthy answers.",
+      "industry": "AI Search",
+      "size": "300+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/perplexity",
+      "social_links": {
+        "twitter": "https://example.com/perplexity/x",
+        "linkedin": "https://example.com/perplexity/li"
+      },
+      "culture": "Answer-focused, fast-iterating, citation-proud. We treat groundedness as a product feature."
+    },
+    {
+      "id": "emp-cohere",
+      "source": "seed-corpus",
+      "external_id": "emp-cohere",
+      "name": "Cohere",
+      "logo": "https://placehold.co/80x80/pink/white?text=CO",
+      "description": "Mock employer building enterprise-grade language models. We specialize in retrieval, multilinguality, and data privacy for regulated industries.",
+      "industry": "Enterprise LLMs",
+      "size": "400+",
+      "location": "Toronto, Canada",
+      "website": "https://example.com/cohere",
+      "social_links": {
+        "twitter": "https://example.com/cohere/x",
+        "linkedin": "https://example.com/cohere/li"
+      },
+      "culture": "Enterprise-aware, research-active, multilingual. We ship models that work in 100+ languages."
+    },
+    {
+      "id": "emp-mistral",
+      "source": "seed-corpus",
+      "external_id": "emp-mistral",
+      "name": "Mistral AI",
+      "logo": "https://placehold.co/80x80/red/white?text=MI",
+      "description": "Mock employer building open-weight frontier models in Europe. We push efficiency and openness in large language models.",
+      "industry": "Open-Weight LLMs",
+      "size": "200+",
+      "location": "Paris, France",
+      "website": "https://example.com/mistral",
+      "social_links": {
+        "twitter": "https://example.com/mistral/x",
+        "linkedin": "https://example.com/mistral/li"
+      },
+      "culture": "European-rooted, efficiency-driven, open-weight-proud. We ship small models that punch above their size."
+    },
+    {
+      "id": "emp-replicate",
+      "source": "seed-corpus",
+      "external_id": "emp-replicate",
+      "name": "Replicate",
+      "logo": "https://placehold.co/80x80/orange/white?text=RE",
+      "description": "Mock employer making ML deployment delightful. We host, serve, and scale models with a few lines of code.",
+      "industry": "ML Deployment",
+      "size": "150+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/replicate",
+      "social_links": {
+        "twitter": "https://example.com/replicate/x",
+        "linkedin": "https://example.com/replicate/li"
+      },
+      "culture": "Developer-experience-obsessed, pragmatic, remote-friendly. We make shipping models feel like shipping software."
+    },
+    {
+      "id": "emp-pinecone",
+      "source": "seed-corpus",
+      "external_id": "emp-pinecone",
+      "name": "Pinecone",
+      "logo": "https://placehold.co/80x80/green/white?text=PC",
+      "description": "Mock employer building the vector database for AI applications. We power retrieval for thousands of production RAG systems.",
+      "industry": "Vector Databases",
+      "size": "300+",
+      "location": "New York, NY",
+      "website": "https://example.com/pinecone",
+      "social_links": {
+        "twitter": "https://example.com/pinecone/x",
+        "linkedin": "https://example.com/pinecone/li"
+      },
+      "culture": "Infra-focused, latency-obsessed, distributed-first. We treat retrieval as the heart of grounded AI."
+    },
+    {
+      "id": "emp-langchain",
+      "source": "seed-corpus",
+      "external_id": "emp-langchain",
+      "name": "LangChain",
+      "logo": "https://placehold.co/80x80/blue/white?text=LC",
+      "description": "Mock employer building the orchestration layer for LLM applications. We provide frameworks for agents, retrieval, and evaluation.",
+      "industry": "AI Orchestration",
+      "size": "200+",
+      "location": "San Francisco, CA",
+      "website": "https://example.com/langchain",
+      "social_links": {
+        "twitter": "https://example.com/langchain/x",
+        "linkedin": "https://example.com/langchain/li"
+      },
+      "culture": "Framework-minded, community-driven, abstractions-first. We build primitives others compose into products."
+    }
+  ],
+  "postings": [
+    {
+      "id": "job-001",
+      "source": "seed-corpus",
+      "external_id": "job-001",
+      "employer_id": "emp-langchain",
+      "title": "AI Orchestration Engineer",
+      "description": "Design and operate multi-agent systems that automate complex knowledge workflows. You will own agent topology, tool integration, and evaluation harnesses for production deployments serving millions of queries.",
+      "required_competencies": [
+        "stack-orchestration-c001",
+        "stack-orchestration-c002",
+        "stack-orchestration-c005"
+      ],
+      "skills": [
+        "LangGraph",
+        "Multi-agent systems",
+        "RAG",
+        "Python",
+        "Evaluation"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": true,
+      "salary_min": 160000,
+      "salary_max": 240000,
+      "posted_at": "2026-08-21T10:00:00Z"
+    },
+    {
+      "id": "job-002",
+      "source": "seed-corpus",
+      "external_id": "job-002",
+      "employer_id": "emp-openai",
+      "title": "LLM Application Developer",
+      "description": "Build delightful LLM-powered features end-to-end. You will work on retrieval, function calling, streaming UX, and robust output validation for consumer-facing products.",
+      "required_competencies": [
+        "stack-orchestration-c003",
+        "stack-orchestration-c004",
+        "stack-orchestration-c005"
+      ],
+      "skills": [
+        "Python",
+        "TypeScript",
+        "RAG",
+        "Function calling",
+        "Streaming"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": true,
+      "salary_min": 140000,
+      "salary_max": 210000,
+      "posted_at": "2026-08-28T09:30:00Z"
+    },
+    {
+      "id": "job-003",
+      "source": "seed-corpus",
+      "external_id": "job-003",
+      "employer_id": "emp-anthropic",
+      "title": "AI Safety Researcher",
+      "description": "Research alignment, interpretability, and robustness of frontier models. Design experiments, run evaluations, and publish findings that improve the safety of deployed AI systems.",
+      "required_competencies": [
+        "stack-safety-c001",
+        "stack-safety-c007",
+        "stack-safety-c002"
+      ],
+      "skills": [
+        "Alignment",
+        "Interpretability",
+        "Red teaming",
+        "Python",
+        "Research"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": false,
+      "salary_min": 180000,
+      "salary_max": 280000,
+      "posted_at": "2026-08-15T12:00:00Z"
+    },
+    {
+      "id": "job-004",
+      "source": "seed-corpus",
+      "external_id": "job-004",
+      "employer_id": "emp-perplexity",
+      "title": "Prompt Engineer",
+      "description": "Craft, test, and ship prompt strategies that power answer-engine features. Own prompt libraries, regression suites, and A/B experiments across product surfaces.",
+      "required_competencies": [
+        "stack-orchestration-c004",
+        "stack-orchestration-c001"
+      ],
+      "skills": [
+        "Prompt engineering",
+        "Evaluation",
+        "A/B testing",
+        "Python"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Remote",
+      "remote": true,
+      "salary_min": 110000,
+      "salary_max": 175000,
+      "posted_at": "2026-09-02T14:15:00Z"
+    },
+    {
+      "id": "job-005",
+      "source": "seed-corpus",
+      "external_id": "job-005",
+      "employer_id": "emp-huggingface",
+      "title": "AI Product Manager",
+      "description": "Own the roadmap for AI-powered developer tools. Translate model capabilities into customer value, define success metrics, and ship agentic features with engineering.",
+      "required_competencies": [
+        "stack-designer-c001",
+        "stack-orchestration-c001"
+      ],
+      "skills": [
+        "Product strategy",
+        "AI UX",
+        "Roadmapping",
+        "Stakeholder mgmt"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "New York, NY",
+      "remote": true,
+      "salary_min": 150000,
+      "salary_max": 220000,
+      "posted_at": "2026-08-30T08:00:00Z"
+    },
+    {
+      "id": "job-006",
+      "source": "seed-corpus",
+      "external_id": "job-006",
+      "employer_id": "emp-pinecone",
+      "title": "RAG Infrastructure Engineer",
+      "description": "Build the retrieval substrate behind knowledge-grounded AI. Optimize indexing, query latency, and hybrid retrieval across billion-vector workloads.",
+      "required_competencies": [
+        "stack-orchestration-c005",
+        "stack-orchestration-c006"
+      ],
+      "skills": [
+        "Vector databases",
+        "Embeddings",
+        "Go",
+        "Distributed systems"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Remote",
+      "remote": true,
+      "salary_min": 130000,
+      "salary_max": 200000,
+      "posted_at": "2026-09-05T11:00:00Z"
+    },
+    {
+      "id": "job-007",
+      "source": "seed-corpus",
+      "external_id": "job-007",
+      "employer_id": "emp-scaleai",
+      "title": "AI Governance Lead",
+      "description": "Stand up the AI governance program for enterprise customers. Map controls to NIST AI RMF and EU AI Act, run audits, and author model cards at scale.",
+      "required_competencies": [
+        "stack-safety-c005",
+        "stack-safety-c003",
+        "stack-safety-c013"
+      ],
+      "skills": [
+        "AI policy",
+        "NIST AI RMF",
+        "Audit",
+        "Documentation"
+      ],
+      "seniority": "staff",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": true,
+      "salary_min": 170000,
+      "salary_max": 230000,
+      "posted_at": "2026-08-18T16:45:00Z"
+    },
+    {
+      "id": "job-008",
+      "source": "seed-corpus",
+      "external_id": "job-008",
+      "employer_id": "emp-anthropic",
+      "title": "Human-AI Interaction Designer",
+      "description": "Design how users collaborate with Claude across products. Own transparency patterns, trust calibration, and agentic interaction for assistant surfaces.",
+      "required_competencies": [
+        "stack-designer-c001",
+        "stack-designer-c003",
+        "stack-designer-c008"
+      ],
+      "skills": [
+        "Figma",
+        "AI UX",
+        "Prototyping",
+        "User research"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": true,
+      "salary_min": 125000,
+      "salary_max": 190000,
+      "posted_at": "2026-08-25T10:30:00Z"
+    },
+    {
+      "id": "job-009",
+      "source": "seed-corpus",
+      "external_id": "job-009",
+      "employer_id": "emp-cohere",
+      "title": "Evaluation Engineer",
+      "description": "Build and operate the eval platform for LLM-powered products. Design LLM-as-judge pipelines, regression suites, and human-eval panels for production models.",
+      "required_competencies": [
+        "stack-orchestration-c007",
+        "stack-safety-c002"
+      ],
+      "skills": [
+        "LLM evaluation",
+        "Python",
+        "Statistics",
+        "Data labeling"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Toronto, Canada",
+      "remote": true,
+      "salary_min": 120000,
+      "salary_max": 180000,
+      "posted_at": "2026-09-01T13:20:00Z"
+    },
+    {
+      "id": "job-010",
+      "source": "seed-corpus",
+      "external_id": "job-010",
+      "employer_id": "emp-replicate",
+      "title": "Robotics Operations Specialist",
+      "description": "Supervise a fleet of AI-augmented robotic units in a warehouse environment. Interpret anomaly alerts, perform calibrations, and intervene on exceptions.",
+      "required_competencies": [
+        "stack-operator-c002",
+        "stack-operator-c011",
+        "stack-operator-c003"
+      ],
+      "skills": [
+        "Robotics",
+        "Safety protocols",
+        "IoT",
+        "Predictive maintenance"
+      ],
+      "seniority": "entry",
+      "category": null,
+      "location": "Austin, TX",
+      "remote": false,
+      "salary_min": 80000,
+      "salary_max": 115000,
+      "posted_at": "2026-08-22T09:00:00Z"
+    },
+    {
+      "id": "job-011",
+      "source": "seed-corpus",
+      "external_id": "job-011",
+      "employer_id": "emp-recursion",
+      "title": "Computational Biologist",
+      "description": "Apply ML to drug discovery. Build pipelines for phenotype prediction, active learning on assay data, and molecular generation for novel targets.",
+      "required_competencies": [
+        "stack-science-c005",
+        "stack-science-c002",
+        "stack-science-c011"
+      ],
+      "skills": [
+        "Bioinformatics",
+        "Python",
+        "PyTorch",
+        "Drug discovery"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "Boston, MA",
+      "remote": true,
+      "salary_min": 145000,
+      "salary_max": 215000,
+      "posted_at": "2026-08-12T15:00:00Z"
+    },
+    {
+      "id": "job-012",
+      "source": "seed-corpus",
+      "external_id": "job-012",
+      "employer_id": "emp-deepmind",
+      "title": "Climate ML Scientist",
+      "description": "Develop ML models for climate forecasting and energy grid optimization. Work with earth system scientists to downscale GCM output and quantify uncertainty.",
+      "required_competencies": [
+        "stack-science-c004",
+        "stack-science-c014",
+        "stack-science-c010"
+      ],
+      "skills": [
+        "Climate modeling",
+        "PyTorch",
+        "Data assimilation",
+        "PINNs"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "London, UK",
+      "remote": true,
+      "salary_min": 135000,
+      "salary_max": 200000,
+      "posted_at": "2026-08-27T11:45:00Z"
+    },
+    {
+      "id": "job-013",
+      "source": "seed-corpus",
+      "external_id": "job-013",
+      "employer_id": "emp-langchain",
+      "title": "Agent Reliability Engineer",
+      "description": "Own observability and reliability for production agent workloads. Build tracing, alerting, and rollback systems for multi-step agent pipelines.",
+      "required_competencies": [
+        "stack-orchestration-c013",
+        "stack-orchestration-c015",
+        "stack-orchestration-c008"
+      ],
+      "skills": [
+        "Observability",
+        "Python",
+        "SRE",
+        "Distributed tracing"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Remote",
+      "remote": true,
+      "salary_min": 140000,
+      "salary_max": 205000,
+      "posted_at": "2026-09-04T09:00:00Z"
+    },
+    {
+      "id": "job-014",
+      "source": "seed-corpus",
+      "external_id": "job-014",
+      "employer_id": "emp-mistral",
+      "title": "AI Red Team Lead",
+      "description": "Lead adversarial testing of frontier and open-weight models. Build automated red-team suites, track vulnerabilities, and coordinate disclosure.",
+      "required_competencies": [
+        "stack-safety-c002",
+        "stack-safety-c010",
+        "stack-safety-c001"
+      ],
+      "skills": [
+        "Red teaming",
+        "Prompt injection",
+        "Python",
+        "Leadership"
+      ],
+      "seniority": "staff",
+      "category": null,
+      "location": "Paris, France",
+      "remote": true,
+      "salary_min": 160000,
+      "salary_max": 230000,
+      "posted_at": "2026-08-19T10:30:00Z"
+    },
+    {
+      "id": "job-015",
+      "source": "seed-corpus",
+      "external_id": "job-015",
+      "employer_id": "emp-huggingface",
+      "title": "Conversation Designer",
+      "description": "Design dialogue flows, personas, and repair strategies for AI assistants across open-source products. Partner with ML engineers to align tone with model behavior.",
+      "required_competencies": [
+        "stack-designer-c002",
+        "stack-designer-c010",
+        "stack-designer-c011"
+      ],
+      "skills": [
+        "Conversation design",
+        "Figma",
+        "Voice UX",
+        "Prototyping"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Remote",
+      "remote": true,
+      "salary_min": 105000,
+      "salary_max": 160000,
+      "posted_at": "2026-08-29T14:00:00Z"
+    },
+    {
+      "id": "job-016",
+      "source": "seed-corpus",
+      "external_id": "job-016",
+      "employer_id": "emp-anduril",
+      "title": "Field AI Technician",
+      "description": "Deploy and maintain AI vision systems on defense hardware in the field. Calibrate sensors, interpret model alerts, and escalate edge cases to engineering.",
+      "required_competencies": [
+        "stack-operator-c004",
+        "stack-operator-c009",
+        "stack-operator-c001"
+      ],
+      "skills": [
+        "Computer vision",
+        "Sensor calibration",
+        "Field ops",
+        "Python"
+      ],
+      "seniority": "entry",
+      "category": null,
+      "location": "Costa Mesa, CA",
+      "remote": false,
+      "salary_min": 90000,
+      "salary_max": 130000,
+      "posted_at": "2026-08-14T08:30:00Z"
+    },
+    {
+      "id": "job-017",
+      "source": "seed-corpus",
+      "external_id": "job-017",
+      "employer_id": "emp-deepmind",
+      "title": "Materials ML Engineer",
+      "description": "Discover novel materials with ML. Train property-prediction models, run active-learning loops over DFT calculations, and validate candidates experimentally.",
+      "required_competencies": [
+        "stack-science-c003",
+        "stack-science-c002",
+        "stack-science-c006"
+      ],
+      "skills": [
+        "Materials science",
+        "PyTorch",
+        "DFT",
+        "Active learning"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "London, UK",
+      "remote": true,
+      "salary_min": 140000,
+      "salary_max": 210000,
+      "posted_at": "2026-08-26T12:15:00Z"
+    },
+    {
+      "id": "job-018",
+      "source": "seed-corpus",
+      "external_id": "job-018",
+      "employer_id": "emp-openai",
+      "title": "AI Trust & Safety Analyst",
+      "description": "Investigate misuse patterns, triage safety incidents, and improve policy enforcement for consumer AI products. Author postmortems and recommend mitigations.",
+      "required_competencies": [
+        "stack-safety-c008",
+        "stack-safety-c006",
+        "stack-safety-c002"
+      ],
+      "skills": [
+        "Trust & safety",
+        "Incident response",
+        "Policy",
+        "Investigation"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "San Francisco, CA",
+      "remote": true,
+      "salary_min": 115000,
+      "salary_max": 170000,
+      "posted_at": "2026-09-03T10:45:00Z"
+    },
+    {
+      "id": "job-019",
+      "source": "seed-corpus",
+      "external_id": "job-019",
+      "employer_id": "emp-replicate",
+      "title": "Edge AI Engineer",
+      "description": "Optimize and deploy models to edge hardware. Quantize, distill, and compile models for low-latency inference on field devices with constrained budgets.",
+      "required_competencies": [
+        "stack-operator-c008",
+        "stack-orchestration-c012",
+        "stack-orchestration-c014"
+      ],
+      "skills": [
+        "Edge ML",
+        "TensorRT",
+        "C++",
+        "Quantization"
+      ],
+      "seniority": "mid",
+      "category": null,
+      "location": "Remote",
+      "remote": true,
+      "salary_min": 130000,
+      "salary_max": 195000,
+      "posted_at": "2026-08-24T11:30:00Z"
+    },
+    {
+      "id": "job-020",
+      "source": "seed-corpus",
+      "external_id": "job-020",
+      "employer_id": "emp-cohere",
+      "title": "AI Research Engineer",
+      "description": "Push the frontier of language model capabilities. Prototype new architectures, run large-scale experiments, and contribute to publications and open-source releases.",
+      "required_competencies": [
+        "stack-orchestration-c001",
+        "stack-science-c010",
+        "stack-science-c011"
+      ],
+      "skills": [
+        "PyTorch",
+        "Research",
+        "Transformers",
+        "Distributed training"
+      ],
+      "seniority": "senior",
+      "category": null,
+      "location": "Berlin, Germany",
+      "remote": true,
+      "salary_min": 155000,
+      "salary_max": 235000,
+      "posted_at": "2026-08-20T09:00:00Z"
+    }
+  ]
+}

apps/ai-service/ai_service/marketplace/tagging.py

@@ -0,0 +1,107 @@
+"""Posting text → skills/seniority/category tags (REQ-6-002, D-052).
+
+Composes the EXISTING structured_completion 4-layer pipeline (D-020)
+with the PostingTags schema — no new agent, a one-shot extraction like
+grading's rubric call. Mock-first for free: the mock provider's
+json_object path (or ScriptedJSONProvider) keeps tests cloud-free.
+
+Tags are DERIVED data (D-052): re-tagging overwrites the posting's tags
+column — single source of truth; no append-only semantics (unlike P4's
+enrichment provenance).
+
+Tag failure is HONEST, never fatal: a provider error leaves the posting
+UNTAGGED (tags=None) with a logged warning — facets treat untagged
+postings honestly (they simply do not contribute counts).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..agents.structured import structured_completion
+from ..llm.base import LLMProvider
+from ..llm.types import Message
+from .base import PostingTags
+
+logger = logging.getLogger(__name__)
+
+#: Prompt version — bump on any wording change (prompts are code).
+TAGGING_PROMPT_VERSION = 1
+
+TAGGING_PROMPT = """You are a job-posting tagger for an AI-era roles
+marketplace. Extract structured tags from the posting.
+
+Rules:
+- skills: 3-10 concrete, lowercase technology/role skills actually named
+  or clearly required by the posting (e.g. "python", "llm evaluation",
+  "kubernetes"). Prefer the posting's own vocabulary.
+- seniority: exactly one of "entry", "mid", "senior", "staff",
+  "principal" — infer from title + experience language; omit (null) if
+  genuinely undeterminable.
+- category: exactly one of "ai-orchestration", "ai-safety", "product",
+  "data", "field-operations", "research" — the role's primary domain;
+  omit (null) if genuinely undeterminable.
+
+Respond with ONLY the JSON object."""
+
+_SCHEMA_HINT = (
+    '{"skills": ["up to 10 lowercase skill strings"], '
+    '"seniority": "entry|mid|senior|staff|principal|null", '
+    '"category": "ai-orchestration|ai-safety|product|data|'
+    'field-operations|research|null"}'
+)
+
+
+class TaggingUnavailable(Exception):
+    """The tagger could not produce valid tags (provider/parse failure).
+
+    The caller persists the posting UNTAGGED — never a crash, never a
+    fabricated tag set (D-052 honesty).
+    """
+
+
+async def tag_posting(
+    provider: LLMProvider,
+    *,
+    model: str,
+    title: str,
+    description: str,
+    skills_hint: list[str] | None = None,
+) -> PostingTags:
+    """One-shot tag extraction via D-020 structured completion.
+
+    `skills_hint` (the posting's declared skills) rides the prompt so
+    the tagger anchors on the author's own vocabulary; the schema bound
+    (≤10) is the enforcement — an 11-skill response fails validation,
+    runs the single bounded retry, and surfaces TaggingUnavailable if
+    the retry also misses.
+    """
+    hint = ""
+    if skills_hint:
+        hint = "\nDeclared skills: " + ", ".join(skills_hint[:15])
+    messages = [
+        Message(role="system", content=TAGGING_PROMPT),
+        Message(
+            role="user",
+            content=f"Title: {title}\n\nDescription:\n{description}{hint}",
+        ),
+    ]
+    try:
+        return await structured_completion(
+            provider,
+            messages,
+            model=model,
+            schema=PostingTags,
+            schema_hint=_SCHEMA_HINT,
+        )
+    except Exception as exc:
+        # Provider failures (RuntimeError from mock/loud providers) and
+        # parse failures (StructuredOutputError) both land here: honest
+        # untagged, loud log.
+        logger.warning(
+            "marketplace tagging failed for %r: %s — posting stays "
+            "untagged (honest None, never fabricated)",
+            title[:60],
+            exc,
+        )
+        raise TaggingUnavailable(str(exc)) from exc

apps/ai-service/ai_service/prompts/assessor.py

@@ -1,24 +1,21 @@
-"""Assessor agent prompt — rubric application to artifacts + defenses (REQ-2-008).
+"""Assessor agent prompt — rubric coaching over REAL grades (REQ-3-007).
 
-Final persona (Phase 4). Assessor is a rigorous, fair grader: scores each
-criterion with evidence, cites what the learner did, returns ONLY valid
-JSON matching the rubric schema.
-Version: assessor-v2 (final for v0.2).
+v0.3 re-grounding: the grading engine (Phase 3) computes the rubric scores
+from the process trace; Assessor EXPLAINS the stored grade as coaching —
+it never invents or re-scores. Rigorous, fair, actionable.
+Version: assessor-v3 (v0.3 live).
 """
 
 SYSTEM_PROMPT = """You are Assessor, the grading agent of Nextcraft, an AI-native competency school.
 Learner: {learner_name}.
 
-You receive: (a) an artifact evidence excerpt, (b) its defense transcript,
-and (c) the rubric for the competency. Your job:
-- Score EVERY rubric criterion from 0-100, justified by evidence you can
-  point to in the artifact or transcript.
-- Cite what the learner did ("the 3-retry loop in the tool node"), not
-  what they should have done — except in gaps, where the missed work goes.
-- Strengths: the two strongest evidence points, each one sentence.
-- Gaps: the two most important missed opportunities, each one sentence.
-- Verdict: "mastered" | "developing" | "not_yet" — judged against the
-  rubric weights, honestly.
+You receive the learner's STORED process-trace grade (verdict, per-criterion
+scores, and the build digest) computed by the grading engine. Your job:
+- Explain what the grade means in plain language (summary).
+- Strengths: cite what the digest + scores show the learner did well.
+- Gaps: name the missed opportunities the scores point to.
+- Next steps: concrete, buildable actions that would move the weakest
+  criterion up one level.
 
 Rules:
 - Rigorous but fair. A polished artifact with a weak defense is NOT mastery.

apps/ai-service/ai_service/prompts/examiner.py

@@ -0,0 +1,60 @@
+"""Examiner agent prompt — oral defense questioning + final verdict (REQ-3-006).
+
+The examiner is the seventh agent (Phase 5). It conducts a Socratic oral
+defense of the learner's submitted work: probes understanding, challenges
+process choices grounded in the trace digest ("why did you take that
+approach at that point?"), one question per turn, adapting to answers.
+It never reveals rubric internals; tone is rigorous but supportive.
+
+Digest discipline (D-028 mirror): the examiner's variable inputs are the
+compact TraceDigest JSON, the variant task statement, and the defense
+transcript — never the raw trace, never learner-identifying material.
+
+Version: examiner-v1.
+"""
+
+SYSTEM_PROMPT = """You are Examiner, the oral-defense agent of Nextcraft,
+an AI-native competency school.
+
+You receive: (a) a compact build-process digest (deterministic counters of the
+learner's build session), (b) the learner's task statement, and (c) the defense
+transcript so far. Your job:
+- Ask ONE question per turn: probe understanding and challenge process
+  choices, grounded in the digest facts ("you hit N failed runs before
+  passing — walk me through what changed") or the task statement.
+- Adapt: follow up on the learner's answers; drill into vague responses.
+- Never reveal rubric details or scoring internals.
+- Tone: rigorous, precise, supportive. A defense is a conversation, not an
+  interrogation.
+
+When asked for a FINAL VERDICT (the structured mode), judge:
+- understanding: can the learner explain their own work?
+- process_justification: are the build-session choices defensible from the
+  digest facts and the answers?
+- communication: are answers clear, specific, and on-topic?
+Score honestly; a weak defense of strong work is NOT mastery.
+
+Rules:
+- Respond with ONLY what the turn requires: a single question (question mode)
+  or a valid JSON object matching the provided schema (verdict mode).
+- If the digest shows error_fix_cycles > 0, at least one question should ask
+  about the debugging path.
+- If the learner's answer is off-topic, redirect once, then move on.
+"""
+
+VERDICT_SCHEMA_HINT = (
+    '{"verdict": "mastered" | "developing" | "not_yet", '
+    '"understanding": "<one sentence>", '
+    '"process_justification": "<one sentence>", '
+    '"communication": "<one sentence>", '
+    '"strengths": ["<one sentence>"], '
+    '"gaps": ["<one sentence>"]}'
+)
+
+
+def render_digest_context(digest_json: str, statement: str | None) -> str:
+    """The examiner's per-session grounding: digest JSON + task statement."""
+    parts = [f"Build-process digest:\n{digest_json}"]
+    if statement:
+        parts.append(f"Learner's task statement:\n{statement}")
+    return "\n\n".join(parts)

apps/ai-service/ai_service/prompts/grading.py

@@ -0,0 +1,140 @@
+"""Grading rubric prompt — criteria, level anchors, digest render (REQ-3-004).
+
+The grading prompt is deliberately learner-anonymous and trace-bare: the
+model receives ONLY the fixed rubric text and the compact numeric digest
+(TraceDigest JSON, D-028) — never a raw command, file path, payload
+string, learner id, or task id. Everything variable the LLM sees is
+deterministic counters, which both bounds the prompt-injection surface
+and makes "no raw trace reaches the prompt" assert-able in tests (plant
+a distinctive marker in a command payload; assert it absent from every
+message the provider received).
+
+Rubric (four criteria, each scored 0-4 — the ids are the validated
+RubricScore keys enforced by grading/engine.py):
+  process_quality       — iterative building in small, verified steps.
+  correctness          — where the session ended (test/run outcomes).
+  debugging_discipline — how failures were handled.
+  test_usage           — when and how often tests were run.
+
+Advisory a-4 (embedded in the process_quality anchors): high edit/command
+churn with NO test progress is a process-quality NEGATIVE — churn is not
+work. A session with many edits/commands whose test state never moves is
+thrashing, not iterating, and must score low on process quality.
+
+House-style deviation, documented: unlike the tutor prompts, this module
+has no SYSTEM_PROMPT placeholders and no render_context(learner_context)
+— grading is context-free by design (learner anonymity; the digest is the
+only variable input). Runtime imports are TYPE_CHECKING-only so this
+module stays pure text and can never import-cycle with grading/engine.py
+(engine imports this module; if this module imported grading.* at runtime
+while grading/__init__ pulls engine, the package init would deadlock on a
+partially-initialized module).
+
+Version: grader-v1.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:  # pragma: no cover - typing only; keeps this module pure text
+    from ..grading.features import TraceDigest
+
+PROMPT_VERSION = "grader-v1"
+
+#: Canonical criterion ids. The engine validates RubricScore criteria keys
+#: against this tuple; the schema hint and anchors below speak the same ids.
+RUBRIC_CRITERIA: Final[tuple[str, ...]] = (
+    "process_quality",
+    "correctness",
+    "debugging_discipline",
+    "test_usage",
+)
+
+#: Sentinel line the engine's user turn is rendered around. Tests (and the
+#: calibration mock) split on it to locate the digest JSON in the prompt.
+DIGEST_MARKER: Final = "PROCESS TRACE DIGEST (JSON):"
+
+SYSTEM_PROMPT = """You are the Grader of Nextcraft, an AI-native competency school.
+You score a learner's build session from a compact numeric digest of their
+process trace. You NEVER see the raw trace — commands, file contents, and
+payloads do not exist on your side; every number you need is in the digest.
+
+Rubric — score each criterion 0-4:
+
+process_quality — iterative building in small, verified steps.
+  4: tight edit→test loops throughout; small verified increments; healthy pacing.
+  3: steady small edits with regular runs; progress mostly verified.
+  2: some iteration, but large unverified leaps or long idle stretches.
+  1: a single bulk change (e.g. one large paste) then a single run; no iteration.
+  0: no meaningful work visible.
+  ADVISORY: high edit/command churn with NO test progress (no runs, no
+  movement in pass counts) is a process-quality NEGATIVE — churn is not
+  work. Cap such a session at 1 on this criterion no matter how many
+  edits or commands were counted.
+
+correctness — where the session ended up.
+  4: final test status pass, with tests passing early and consistently.
+  3: final pass, reached through fail→fix→pass cycles that closed.
+  2: final pass, but preceded by a long unresolved failure streak.
+  1: final fail, but partial passes observed along the way.
+  0: final fail, or no test/run evidence at all.
+
+debugging_discipline — how failures were handled.
+  4: every failure cycle closes; targeted fixes with low mean fix latency.
+  3: most fail→edit→re-run cycles close with a pass.
+  2: failures followed by edits, but cycles rarely close.
+  1: repeated failures with no targeted edits between runs (flailing).
+  0: failures with no fix attempts at all.
+
+test_usage — when and how often tests were run.
+  4: tests run early (small first-pass offset) and throughout the session.
+  3: regular test runs interleaved with edits.
+  2: sparse tests; long stretches of unverified edits.
+  1: a single late test run only.
+  0: no test or run evidence.
+
+Rules:
+- Judge STRICTLY from the digest numbers; cite the fields you used.
+- Strengths: the two strongest digest observations, one sentence each.
+- Gaps: the two most important missed opportunities, one sentence each
+  (a clean session names its next-level improvement instead).
+- Be rigorous but fair: a session that ends green was not necessarily
+  well built, and a struggling session that never passed may still show
+  real debugging discipline.
+- Respond with ONLY a valid JSON object matching the provided schema —
+  no markdown fences, no prose outside the JSON."""
+
+RUBRIC_SCORE_SCHEMA_HINT = (
+    '{"criteria": {"process_quality": <0-4 int>, "correctness": <0-4 int>, '
+    '"debugging_discipline": <0-4 int>, "test_usage": <0-4 int>}, '
+    '"strengths": ["<one sentence>"], "gaps": ["<one sentence>"], '
+    '"verdict": "mastered" | "developing" | "not_yet"}'
+)
+
+
+def render_trace_digest(
+    digest: TraceDigest,
+    anchors_context: str | None = None,
+) -> str:
+    """Render the grader's user turn: a marker line + the digest JSON — nothing else.
+
+    This is the ONLY per-session content that ever reaches the LLM (D-028):
+    the engine composes [system: SYSTEM_PROMPT, user: render_trace_digest(digest)]
+    and the D-020 defense appends its generic schema instruction to this
+    user turn at request time. No learner id, task id, or raw trace material
+    is injected — assert-able by tests.
+
+    `anchors_context` (Phase 4, MH#4): when the graded task derives from a
+    variant, the engine passes the template's difficulty-normalization
+    anchors (the expected effort envelope) so the rubric is applied against
+    the SAME bar for every variant of that template (a-5). It contains only
+    the anchor numbers + the template id — no learner-identifying material.
+    """
+    base = (
+        "Score this build session against the rubric.\n"
+        f"{DIGEST_MARKER}\n{digest.model_dump_json()}"
+    )
+    if anchors_context:
+        base = f"{base}\n\nExpected effort envelope for this task variant:\n{anchors_context}"
+    return base

apps/ai-service/ai_service/prompts/lab.py

@@ -1,9 +1,11 @@
-"""Lab agent prompt — in-flow feedback over sandbox telemetry (REQ-2-007).
+"""Lab agent prompt — in-flow feedback over LIVE telemetry (REQ-3-007).
 
-Final persona (Phase 4). Lab is a pragmatic build partner: reads the
-telemetry timeline, names the one most useful adjustment, gives one
-concrete next step. Scenario-driven; no session chat.
-Version: lab-v2 (final for v0.2).
+v0.3 re-grounding: the timeline is the learner's real TraceDigest (D-028
+compact counters — commands, test outcomes, idle gaps, edit cadence), not
+v0.2 corpus scenarios. Lab is a pragmatic build partner: reads the live
+digest, names the one most useful adjustment, gives one concrete next
+step. No session chat.
+Version: lab-v3 (v0.3 live).
 """
 
 SYSTEM_PROMPT = """You are Lab, the in-flow feedback agent watching a learner
@@ -25,7 +27,17 @@ Rules:
   self-check that would prove understanding.
 - Three short paragraphs maximum. No headers, no bullet lists."""
 
-PROMPT_VERSION = "lab-v2"
+PROMPT_VERSION = "lab-v3"
+
+
+def render_digest_timeline(digest) -> str:
+    """Live-trace timeline: the compact TraceDigest JSON (D-028)."""
+    if digest is None:
+        return (
+            "No telemetry yet for this build session. Ask the learner to run "
+            "the task's starter test to establish a baseline."
+        )
+    return f"Live build-session digest:\n{digest.model_dump_json()}"
 
 
 def render_context(learner_context) -> dict:

apps/ai-service/ai_service/prompts/proctor.py

@@ -1,24 +1,27 @@
-"""Proctor agent prompt — integrity signals with coaching interventions (REQ-2-009).
+"""Proctor agent prompt — integrity signals with coaching interventions (REQ-3-007).
 
-Final persona (Phase 5). Proctor is a supportive observer, never punitive:
-classifies signals, recommends ONE coaching intervention. Assume good
-faith — most signals have innocent explanations.
-Version: proctor-v2 (final for v0.2).
+v0.3 re-grounding: inputs are REAL — the live trace digest (idle gaps,
+command cadence, edit bursts), the oral-defense integrity signals (long
+pauses), and the variant audit context (seed + params). Proctor is a
+supportive observer, never punitive: classifies signals, recommends ONE
+coaching intervention. Assume good faith.
+Version: proctor-v3 (v0.3 live).
 """
 
 SYSTEM_PROMPT = """You are Proctor, the integrity-support agent of Nextcraft,
 an AI-native competency school.
 Learner: {learner_name}.
 
-You receive a telemetry timeline of defense-session events (tab switches,
-idle gaps, large pastes, focus loss, keystroke bursts). Your job:
-- Classify EACH notable signal: type (e.g. "context_switch", "idle_gap",
-  "large_paste"), severity ("low" | "medium" | "high"), and a one-sentence
-  note citing the event (timestamps and details).
+You receive the learner's REAL build-session digest (idle gaps, command
+categories, edit/test cadence), oral-defense integrity signals (long
+pauses), and — when the task is variant-derived — the variant seed context.
+Your job:
+- Classify EACH notable signal: type ("idle_gap" | "long_pause" |
+  "burst_edit" | "off_template"), severity ("low" | "medium" | "high"),
+  and a one-sentence note citing the numbers.
 - Recommend exactly ONE supportive coaching intervention for the session
   overall — never punitive, never accusatory. Frame around helping the
-  learner succeed, e.g. "offer a short break", "invite them to explain
-  the pasted section in their own words".
+  learner succeed.
 
 Rules:
 - Assume good faith. Tab switches to documentation are normal engineering.
@@ -28,7 +31,7 @@ Rules:
 - Respond with ONLY a valid JSON object matching the provided schema —
   no markdown fences, no prose outside the JSON."""
 
-PROMPT_VERSION = "proctor-v2"
+PROMPT_VERSION = "proctor-v3"
 
 
 def render_context(learner_context) -> dict:

apps/ai-service/ai_service/prompts/variant.py

@@ -0,0 +1,46 @@
+"""Variant instantiation prompt (D-029, REQ-3-005).
+
+The model's ONLY job is to render already-sampled slot values into a task
+statement — it never invents parameters (the seeded sampler is pure code)
+and never changes difficulty. Prompt-injection surface is bounded: the
+variable inputs are the skeleton text, the seeded slot values, and the
+template title — nothing from the learner's environment.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..llm.types import Message
+
+if TYPE_CHECKING:  # pragma: no cover - keeps this module pure text
+    from ..variants.templates import TaskTemplate
+
+VARIANT_SYSTEM_PROMPT = (
+    "You instantiate per-learner task variants for a competency-based AI school. "
+    "You receive a task statement skeleton and ALREADY-SAMPLED slot values. "
+    "Render the slot values into the skeleton, producing a complete, unambiguous "
+    "task statement a learner can build against. Rules:\n"
+    "- Use EXACTLY the given slot values; do not invent, rename, or add parameters.\n"
+    "- Keep the engineering depth IDENTICAL across draws: slot values change the "
+    "scenario, never the difficulty or scope.\n"
+    "- Keep the statement in the same language and register as the skeleton.\n"
+    "- Output STRICT JSON only: {\"statement\": \"<rendered statement>\"}.\n"
+)
+
+VARIANT_SCHEMA_HINT = '{"statement": "<complete rendered task statement string>"}'
+
+
+def render_variant_prompt(template: TaskTemplate, params: dict[str, str | int]) -> list[Message]:
+    """Messages for one seeded instantiation (D-020 defense drives the call)."""
+    slot_lines = "\n".join(f"  {{{slot.name}}} = {params[slot.name]!r}" for slot in template.slots)
+    user = (
+        f"Template: {template.title} (id={template.id})\n"
+        f"Statement skeleton:\n{template.statement_skeleton}\n\n"
+        f"Seeded slot values (use EXACTLY these):\n{slot_lines}\n\n"
+        "Render the complete task statement now."
+    )
+    return [
+        Message(role="system", content=VARIANT_SYSTEM_PROMPT),
+        Message(role="user", content=user),
+    ]

apps/ai-service/ai_service/sandbox/backend.py

@@ -46,7 +46,14 @@ class SandboxHandle(BaseModel):
 
 
 class SandboxSpec(BaseModel):
-    """Immutable description of the sandbox to lay out on disk."""
+    """Immutable description of the sandbox to lay out on disk.
+
+    `capture_env` (REQ-3-003): when non-empty, the backend starts a persistent
+    telemetry-wired sandbox — helper + inner namespaces + the stdlib capture
+    agent, launched with these env vars (NC_LEARNER_ID, NC_TASK_ID,
+    NC_INGEST_URL, NC_SANDBOX_ID). When None (default), spawn keeps the pure
+    shell semantics (REQ-3-001): disk layout only, fresh namespaces per exec.
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -54,6 +61,7 @@ class SandboxSpec(BaseModel):
     learner_id: str
     workdir: Path
     limits: ResourceLimits = ResourceLimits()
+    capture_env: dict[str, str] | None = None
 
 
 class ExecResult(BaseModel):

apps/ai-service/ai_service/sandbox/capability.py

@@ -0,0 +1,86 @@
+"""Sandbox capability probe — the honest degrade truth source (D-068, v0.8).
+
+Runtime promotion of the test-tier userns probe (``tests/helpers/userns.py``
+mechanism, verbatim): a REAL ``unshare --user --map-root-user`` attempt is
+the truth source for whether the namespace fabric can provision learner
+environments on this host. Container detection (``/.dockerenv`` or the
+``NC_CONTAINER`` marker the image sets) is belt-and-suspenders context for
+the remediation text — the degrade decision itself is ALWAYS the probe,
+never a guess from the marker (a privileged container with working userns
+must NOT report degraded).
+
+The single remediation constant (G-208) is shared by the boot notice
+(``main.py`` lifespan) and the 503 arm (``api/sandboxes.py``) so the two
+surfaces can never drift.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+#: Remediation text (G-208): names the unprivileged default, the seccomp
+#: constraint, the privileged variant with exact flags, and the host-side
+#: alternative. One constant — boot notice and 503 payload import it, so
+#: they cannot drift apart.
+DEGRADE_REMEDIATION = (
+    "learner sandbox builds are unavailable on this host: the namespace "
+    "fabric needs unprivileged user namespaces and the capability probe "
+    "failed. The nextcraft container runs unprivileged by default and "
+    "docker's default seccomp profile denies the nested `unshare --user` "
+    "the fabric requires. Options: (1) run the image with "
+    "`--security-opt seccomp=unconfined` (and `--security-opt "
+    "apparmor=unconfined` where apparmor applies) on a host that allows "
+    "unprivileged userns; or (2) run the stack binary-side on the host "
+    "(`nextcraft deploy --service`) where the fabric works natively. "
+    "Everything else in this deployment is unaffected."
+)
+
+_probe_result: bool | None = None
+
+
+def userns_available() -> bool:
+    """True only if `unshare` exists AND `--user --map-root-user` works here.
+
+    The result is cached per process (the probe spawns a subprocess; one
+    answer per boot is the contract — the boot notice and every 503 read
+    the same truth).
+    """
+    global _probe_result
+    if _probe_result is None:
+        _probe_result = _probe()
+    return _probe_result
+
+
+def _probe() -> bool:
+    if shutil.which("unshare") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["unshare", "--user", "--map-root-user", "true"],
+            capture_output=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def container_detected() -> bool:
+    """Context marker (not the degrade truth): /.dockerenv or NC_CONTAINER.
+
+    Used by the boot notice to tailor the message and by the CLI's
+    container-mode branches. A privileged container with working userns
+    is NOT degraded — the probe alone decides that.
+    """
+    if Path("/.dockerenv").exists():
+        return True
+    import os
+
+    return os.environ.get("NC_CONTAINER") == "1"
+
+
+def sandbox_fabric_degraded() -> bool:
+    """The degrade decision: the probe fails. Marker never overrides it."""
+    return not userns_available()

apps/ai-service/ai_service/sandbox/manager.py

@@ -38,6 +38,7 @@ BOUNDARY: this module NEVER imports `api/` or `agents/`.
 from __future__ import annotations
 
 import asyncio
+import builtins
 import json
 import logging
 import os
@@ -50,6 +51,7 @@ from pathlib import Path
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..config import Settings
+from ..telemetry.tokens import IngestToken
 from . import workdir as workdir_mod
 from .backend import SandboxBackend, SandboxHandle
 
@@ -119,12 +121,21 @@ class SandboxManager:
         backend: SandboxBackend,
         settings: Settings,
         clock: Callable[[], datetime] | None = None,
+        ingest_token: IngestToken | None = None,
     ) -> None:
         self._backend = backend
         self._settings = settings
         self._clock = clock or (lambda: datetime.now(UTC))
+        # v0.4.7 (P1): shared with the WS endpoint via app.state — mint and
+        # verify MUST use one instance while the secret is per-boot random.
+        self._ingest_token = ingest_token or IngestToken(
+            getattr(settings, "telemetry_ingest_secret", "") or ""
+        )
         self._handles: dict[str, SandboxHandle] = {}
         self._learner_ids: dict[str, str] = {}  # sandbox_id -> learner_id
+        #: REQ-5-005 (G-15): sandbox_id -> task_id side-table — the exec
+        #: policy resolves the variant's environment kind by task_id.
+        self._task_ids: dict[str, str | None] = {}
         self._lock = asyncio.Lock()
         self._integrity_events: list[SandboxIntegrityEvent] = []
         self._started = False
@@ -142,8 +153,18 @@ class SandboxManager:
 
     # -- lifecycle ----------------------------------------------------------
 
-    async def create(self, learner_id: str) -> SandboxHandleInfo:
-        """Spawn a sandbox for `learner_id`, or raise `PoolFullError` (D-032)."""
+    async def create(
+        self, learner_id: str, task_id: str | None = None
+    ) -> SandboxHandleInfo:
+        """Spawn a sandbox for `learner_id`, or raise `PoolFullError` (D-032).
+
+        `task_id` (REQ-3-003): when set, the sandbox is telemetry-wired — the
+        backend copies `scripts/sandbox-agent.py` into the workdir and starts
+        the stdlib capture agent inside the sandbox with the `NC_*` env baked
+        here (identity + WS ingest URL). The agent's lifecycle is tied to the
+        sandbox: `destroy()` reaps it (agent → inner → helper). When `task_id`
+        is None the sandbox is a pure shell sandbox (no capture).
+        """
         async with self._lock:
             if len(self._handles) >= self._settings.sandbox_max_concurrent:
                 raise PoolFullError(
@@ -153,13 +174,57 @@ class SandboxManager:
                 )
             sandbox_id = f"sbx-{uuid.uuid4().hex[:12]}"
             spec = workdir_mod.spec_for(sandbox_id, learner_id, self._settings)
+            if task_id is not None:
+                spec = spec.model_copy(
+                    update={
+                        "capture_env": self._capture_env(sandbox_id, learner_id, task_id)
+                    }
+                )
             handle = await self._backend.spawn(spec)
             self._handles[handle.id] = handle
             self._learner_ids[handle.id] = learner_id
+            self._task_ids[handle.id] = task_id
             self._write_pid_marker(handle, learner_id)
-            logger.info("sandbox created: id=%s learner=%s", handle.id, learner_id)
+            logger.info(
+                "sandbox created: id=%s learner=%s task=%s",
+                handle.id,
+                learner_id,
+                task_id or "-",
+            )
             return self._info_for(handle)
 
+    def _capture_env(self, sandbox_id: str, learner_id: str, task_id: str) -> dict[str, str]:
+        """Env baked for the in-sandbox capture agent (REQ-3-003).
+
+        The agent joins the sandbox mount namespace but NOT its (offline)
+        network namespace, so it reaches this service over loopback
+        (`telemetry_ingest_host`, A-004 port). v0.4.7: the URL carries an
+        HMAC ingest token (P1) — the WS endpoint rejects dials without a
+        valid one, so LAN peers cannot poison traces with forged identity
+        params.
+        """
+        from urllib.parse import urlencode
+
+        token = self._ingest_token.mint(learner_id, task_id, sandbox_id)
+        query = urlencode(
+            {
+                "learner_id": learner_id,
+                "task_id": task_id,
+                "sandbox_id": sandbox_id,
+                "token": token,
+            }
+        )
+        ingest_url = (
+            f"ws://{self._settings.telemetry_ingest_host}:{self._settings.port}"
+            f"/v1/telemetry/ingest?{query}"
+        )
+        return {
+            "NC_LEARNER_ID": learner_id,
+            "NC_TASK_ID": task_id,
+            "NC_SANDBOX_ID": sandbox_id,
+            "NC_INGEST_URL": ingest_url,
+        }
+
     async def list(self) -> list[SandboxHandleInfo]:
         """All live sandboxes (idle + busy; the backend has no busy flag)."""
         async with self._lock:
@@ -198,6 +263,7 @@ class SandboxManager:
         async with self._lock:
             handle = self._handles.pop(sandbox_id, None)
             learner_id = self._learner_ids.pop(sandbox_id, "unknown")
+            self._task_ids.pop(sandbox_id, None)
         if handle is not None:
             await self._backend.destroy(handle)
             logger.info(
@@ -216,7 +282,7 @@ class SandboxManager:
 
     # -- reapers ------------------------------------------------------------
 
-    async def reap_expired(self) -> list[str]:
+    async def reap_expired(self) -> builtins.list[str]:
         """One reaper pass: wall-clock timeout + G-2 workdir-size sweep.
 
         Destroys sandboxes older than `settings.sandbox_timeout_s`, then sweeps
@@ -225,9 +291,14 @@ class SandboxManager:
         signal). Returns the ids destroyed this pass. Invoke on an async timer
         (the app lifespan owns the loop interval); both checks deliberately
         share one pass so the periodic work is O(live sandboxes) once.
+
+        P5: the return annotation is `builtins.list` because this class's
+        own `list()` method shadows the `list[...]` subscript form in
+        annotations below it (a mypy scoping quirk — the method name is
+        public API and stays).
         """
         now = self._clock()
-        destroyed: list[str] = []
+        destroyed: builtins.list[str] = []
         timeout_s = float(self._settings.sandbox_timeout_s)
         cap_bytes = int(self._settings.sandbox_max_workdir_mb) * 1024 * 1024
 

apps/ai-service/ai_service/sandbox/unshare_backend.py

@@ -1,24 +1,42 @@
 """UnshareBackend — D-024 Linux-namespace sandboxing via util-linux `unshare`.
 
-Each `exec` spawns:
+Two execution modes share one backend:
 
-    unshare --user --map-root-user --mount --pid --fork --net  sh -c '<shim>'
+1. Pure shell sandbox (`task_id is None`, REQ-3-001): isolation is established
+   PER-EXEC — every `exec` spawns a fresh namespace:
 
-The in-namespace shim (this util-linux build, 2.38, has no `unshare --bind`,
-so the bind happens as the first mount op inside the namespace) is:
+       unshare --user --map-root-user --mount --pid --fork --net  sh -c '<shim>'
 
-    mount -t tmpfs tmpfs /tmp            # private scratch, discarded on exit
-    mkdir -p /tmp/work
-    mount --bind <host workspace> /tmp/work
-    cd /tmp/work
-    ulimit -v/-t/-f  …                   # applied AFTER the bind, so rlimits
-    exec <cmd>                           # constrain the PAYLOAD, not unshare
+   There is no persistent process; the in-namespace shim is:
 
-Guarantees after this shim:
-  * uid 0 inside (mapped to the unprivileged host UID outside)
-  * no network: the fresh net namespace has no `lo` and no veth — zero links
-  * writes under `/work` land in the per-sandbox host workspace dir
-  * rlimits (RLIMIT_AS / RLIMIT_CPU / RLIMIT_FSIZE) constrain the payload only
+       mount -t tmpfs tmpfs /tmp            # private scratch, discarded on exit
+       mkdir -p /tmp/work
+       mount --bind <host workspace> /tmp/work
+       cd /tmp/work
+       ulimit -v/-t/-f  …                   # applied AFTER the bind, so rlimits
+       exec <cmd>                           # constrain the PAYLOAD, not unshare
+
+2. Telemetry-wired task sandbox (REQ-3-003, `capture_env` set): a PERSISTENT,
+   TRACKED topology so the stdlib capture agent can live inside the sandbox and
+   still stream events to ai-service. Per exec a fresh OFFLINE namespace would
+   leave the agent nowhere to run and (on this host, where a userns can't
+   bring `lo` up) no loopback to reach `ws://127.0.0.1`. So spawn creates a
+   long-lived helper (outer user+mount ns, ONLINE) and an inner sandbox
+   (mount+pid+fork+net — OFFLINE), both rooted at a private `ns/` subtree:
+
+       helper : unshare --user --map-root-user --mount  (mounts ns/ private)
+       inner  : unshare --mount --pid --fork --net      (tmpfs on ns/, bind
+                <workdir>/host/workspace -> <ns>/work)   <- the sandbox
+       exec   : nsenter -t <inner sleep> -m -- sh -c …  (joins inner mount ns;
+                offline + pid-isolated, uid 0, writes land on the host workspace)
+       agent  : nsenter -t <inner sleep> -m -- python3 <agent>  (joins the inner
+                MOUNT ns only — NOT pid/net — so it watches the live workspace
+                and stays ONLINE, reaching the app's WS ingest on loopback)
+
+   The agent is deliberately pid/net-exempt from the sandbox: it is OUR trusted
+   capture process, and isolating its network would cut the very link it needs.
+   `destroy` reaps agent → inner → helper (in that order). The handle's `pid`
+   is the agent's host pid (None for a pure shell sandbox).
 
 Why rlimits are applied in the shim, not Python's preexec_fn: setting
 RLIMIT_AS on the *unshare* process itself can trip the memory ceiling on the
@@ -30,16 +48,18 @@ Containment honesty (D-024 / G-1): a user namespace is NOT a write barrier.
 Writes made OUTSIDE the bind fall through to host paths, and because inner
 uid 0 maps to the invoking host uid, a sandboxed process can write anywhere
 that host uid can write. Isolation here is: private PIDs/MNT/NET/UTS, tmpfs
-scratch at /tmp, payload rlimits, and a uid map yielding no privilege the
-host uid did not already have. A per-sandbox runtime uid (D-025) is the
-follow-up that hardens DAC.
+scratch, payload rlimits, and a uid map yielding no privilege the host uid
+did not already have. A per-sandbox runtime uid (D-025) is the follow-up that
+hardens DAC.
 """
 
 from __future__ import annotations
 
 import asyncio
+import os
 import shlex
 import shutil
+import signal
 import time
 from datetime import UTC, datetime
 from pathlib import Path
@@ -48,22 +68,27 @@ from .backend import ExecResult, ResourceLimits, SandboxHandle, SandboxSpec
 from .workdir import create_layout
 from .workdir import snapshot as workdir_snapshot
 
-#: Args shared by every namespace we spawn (D-024). No `unshare --bind` on
-#: util-linux 2.38 — the bind is done from inside the namespace instead.
+#: Args shared by every PURE shell namespace we spawn (D-024). No
+#: `unshare --bind` on util-linux 2.38 — the bind is done from inside instead.
 UNSHARE_ARGS: tuple[str, ...] = (
     "--user",  # new user namespace …
     "--map-root-user",  # … in which we are uid 0 (mapped to host uid outside)
     "--mount",  # private mount table
     "--pid",  # private PID table
     "--fork",  # child is PID 1 in its namespace (reaps zombies, gets signals)
-    "--net",  # fresh net namespace: no lo, no veth → fully offline
+    "--net",  # fresh net namespace: no usable route → effectively offline
 )
 
-IN_NS_WORKDIR = "/tmp/work"  # where the workspace is bound inside the namespace
+IN_NS_WORKDIR = "/tmp/work"  # where the workspace is bound inside a pure shell ns
+
+#: Sentinels the long-lived namespace supervisors print once their mounts are
+#: laid out. exec()/the manager must not run before the bind exists.
+_HELPER_READY = "NC_HELPER_READY"
+_INNER_READY = "NC_INNER_READY"
 
 
 class SandboxUnavailableError(RuntimeError):
-    """`unshare` missing or user namespaces blocked on this host."""
+    """`unshare`/`nsenter` missing or user namespaces blocked on this host."""
 
 
 def _build_shim(workspace: Path, limits: ResourceLimits, cmd: list[str]) -> str:
@@ -90,35 +115,286 @@ def _build_shim(workspace: Path, limits: ResourceLimits, cmd: list[str]) -> str:
     )
 
 
+class _Tracked:
+    """The process tree + paths for one persistent (telemetry-wired) sandbox."""
+
+    def __init__(
+        self,
+        *,
+        helper: asyncio.subprocess.Process,
+        inner: asyncio.subprocess.Process,
+        agent: asyncio.subprocess.Process | None,
+        inner_pid: int,  # host pid of the SANDBOXED init (sleep) — ns enter target
+        host_dir: Path,
+        workspace: Path,
+        ns_root: Path,
+        ns_workdir: Path,
+    ) -> None:
+        self.helper = helper
+        self.inner = inner
+        self.agent = agent
+        self.inner_pid = inner_pid
+        self.host_dir = host_dir
+        self.workspace = workspace
+        self.ns_root = ns_root
+        self.ns_workdir = ns_workdir
+
+
 class UnshareBackend:  # satisfies SandboxBackend structurally (Protocol)
-    """D-024 backend: subprocess-per-exec inside fresh Linux namespaces."""
+    """D-024 backend: namespace subprocesses; persistent tree for task sandboxes."""
 
     def __init__(
         self,
         unshare_path: str | None = None,
         limits: ResourceLimits | None = None,  # per-spec override lands in 1-04
+        nsenter_path: str | None = None,
+        agent_script: Path | None = None,
     ) -> None:
         self._unshare = unshare_path or shutil.which("unshare") or "unshare"
+        self._nsenter = nsenter_path or shutil.which("nsenter") or "nsenter"
         self._limits = limits or ResourceLimits()
+        # The stdlib-only capture agent script, copied into each tracked
+        # workdir's host/ tree so nsenter can reach it inside the sandbox.
+        # ai_service/sandbox/unshare_backend.py -> parents[2] = apps/ai-service.
+        self._agent_script = agent_script or (
+            Path(__file__).resolve().parents[2] / "scripts" / "sandbox-agent.py"
+        )
+        # Tracked (persistent) sandboxes by id; pure shell sandboxes are absent.
+        self._tracked: dict[str, _Tracked] = {}
+
+    # -- spawn ------------------------------------------------------------------
 
     async def spawn(self, spec: SandboxSpec) -> SandboxHandle:
-        """Lay out the workdir and return a handle.
+        """Lay out the workdir; if `spec.capture_env` is set, start the sandbox.
 
-        Isolation is established per-`exec` (each exec = fresh namespaces), so
-        spawn only prepares on-disk state; there is no long-lived init process.
+        A spec WITHOUT capture_env keeps REQ-3-001 semantics: spawn only
+        prepares disk state and each exec forks a fresh (offline) namespace.
+        A spec WITH capture_env starts the persistent helper/inner tree and the
+        capture agent, and `handle.pid` carries the agent's host pid.
         """
         create_layout(spec)
+        if not spec.capture_env:
+            return SandboxHandle(
+                id=spec.sandbox_id,
+                pid=None,  # no persistent process; each exec forks short-lived PIDs
+                workdir=spec.workdir,
+                created_at=datetime.now(UTC),
+            )
+        tracked = await self._spawn_tracked(spec)
+        self._tracked[spec.sandbox_id] = tracked
         return SandboxHandle(
             id=spec.sandbox_id,
-            pid=None,  # no persistent process; each exec forks short-lived PIDs
+            pid=tracked.agent.pid if tracked.agent is not None else tracked.inner_pid,
             workdir=spec.workdir,
             created_at=datetime.now(UTC),
         )
 
+    async def _spawn_tracked(self, spec: SandboxSpec) -> _Tracked:
+        """Bring up helper + inner + agent for a telemetry-wired task sandbox."""
+        host_dir = spec.workdir / "host"
+        workspace = host_dir / "workspace"
+        ns_root = host_dir / "ns"
+        ns_workdir = ns_root / "work"
+        for d in (workspace, ns_root):
+            d.mkdir(parents=True, exist_ok=True)
+        # The agent script must live INSIDE the workspace: the inner ns bind
+        # mounts <host_dir>/workspace -> <ns_root>/work, so only workspace
+        # content is visible in-namespace at /work.
+        agent_host_path = workspace / "sandbox-agent.py"
+        shutil.copyfile(self._agent_script, agent_host_path)
+
+        helper = await self._launch_ns(
+            [
+                self._unshare,
+                "--user",
+                "--map-root-user",
+                "--mount",
+                "sh",
+                "-c",
+                (
+                    # Isolate ns/ so the inner tmpfs never propagates back to the
+                    # host mount table (make-private is best-effort on this host).
+                    f"mount --bind {shlex.quote(str(ns_root))} {shlex.quote(str(ns_root))}; "
+                    f"mount --make-private {shlex.quote(str(ns_root))} 2>/dev/null; "
+                    f"echo {_HELPER_READY}; exec sleep 3600"
+                ),
+            ],
+            sentinel=_HELPER_READY,
+            label="helper",
+        )
+        try:
+            inner = await self._launch_ns(
+                [
+                    *self._helper_join_argv(helper),
+                    self._unshare,
+                    "--mount",
+                    "--pid",
+                    "--fork",
+                    "--net",
+                    "sh",
+                    "-c",
+                    (
+                        f"mount -t tmpfs tmpfs {shlex.quote(str(ns_root))}; "
+                        f"mkdir -p {shlex.quote(str(ns_workdir))}; "
+                        f"mount --bind {shlex.quote(str(workspace))} "
+                        f"{shlex.quote(str(ns_workdir))}; "
+                        f"echo {_INNER_READY}; exec sleep 3600"
+                    ),
+                ],
+                sentinel=_INNER_READY,
+                label="inner",
+            )
+        except Exception:
+            await self._reap(helper)
+            raise
+
+        await asyncio.sleep(0)  # let the inner child's sleep fork settle
+        inner_pid = await asyncio.to_thread(self._find_child_pid, inner.pid)
+        if inner_pid is None:
+            await self._reap(inner)
+            await self._reap(helper)
+            raise SandboxUnavailableError(
+                f"could not resolve sandboxed init pid for {spec.sandbox_id}"
+            )
+
+        tracked = _Tracked(
+            helper=helper,
+            inner=inner,
+            agent=None,
+            inner_pid=inner_pid,
+            host_dir=host_dir,
+            workspace=workspace,
+            ns_root=ns_root,
+            ns_workdir=ns_workdir,
+        )
+        if spec.capture_env:
+            tracked.agent = await self._launch_agent(spec, tracked, agent_host_path)
+        return tracked
+
+    # -- process launch helpers --------------------------------------------------
+
+    def _helper_join_argv(self, helper: asyncio.subprocess.Process) -> list[str]:
+        """nsenter argv that runs a command inside the helper's user+mount ns."""
+        if helper.pid is None:
+            raise SandboxUnavailableError("helper namespace process is not running")
+        return [
+            self._nsenter,
+            "-t",
+            str(helper.pid),
+            "-m",
+            "-U",
+            "--preserve-credentials",
+            "--",
+        ]
+
+    def _sandbox_join_argv(self, tracked: _Tracked) -> list[str]:
+        """nsenter argv that joins the inner sandbox MOUNT namespace (uid 0)."""
+        return [self._nsenter, "-t", str(tracked.inner_pid), "-m", "--"]
+
+    async def _launch_agent(
+        self, spec: SandboxSpec, tracked: _Tracked, agent_host_path: Path
+    ) -> asyncio.subprocess.Process:
+        """Launch the capture agent: joins the sandbox mount ns, NOT pid/net.
+
+        The nsenter chain swaps the mount table under the process, so a HOST
+        cwd/relative path is invalid after the join (observed: python3
+        resolved ``sandbox-agent.py`` against a stale root → ``//…`` and
+        exited rc=2). The launch therefore happens through ``sh -c`` INSIDE
+        the joined namespace, using only in-namespace absolute paths: the
+        workspace is bind-mounted at ``<ns_root>/work``, the agent script was
+        copied into the host workspace, so ``/work/sandbox-agent.py`` exists
+        after the join. The agent runs ONLINE (joins mount ns only, not the
+        offline net ns) so it can dial the ai-service WS ingest loopback.
+        """
+        env = dict(spec.capture_env or {})
+        in_ns_script = f"{tracked.ns_root / 'work' / 'sandbox-agent.py'}"
+        in_ns_cwd = f"{tracked.ns_root / 'work'}"
+        launch = f"cd {shlex.quote(in_ns_cwd)} && exec python3 {shlex.quote(in_ns_script)}"
+        try:
+            return await asyncio.create_subprocess_exec(
+                *self._helper_join_argv(tracked.helper),
+                *self._sandbox_join_argv(tracked),
+                "sh",
+                "-c",
+                launch,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+                env=env,
+            )
+        except FileNotFoundError as exc:  # pragma: no cover - env-dependent
+            raise SandboxUnavailableError("python3 unavailable for capture agent") from exc
+
+    async def _launch_ns(
+        self, argv: list[str], *, sentinel: str, label: str
+    ) -> asyncio.subprocess.Process:
+        """Spawn a namespace supervisor and wait for its `sentinel` line."""
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+
+        async def _wait_ready() -> None:
+            if proc.stdout is None:  # pragma: no cover (stdout is a PIPE)
+                raise SandboxUnavailableError(f"{label} namespace missing stdout pipe")
+            async for raw in proc.stdout:
+                if raw.decode(errors="replace").strip() == sentinel:
+                    return
+            raise SandboxUnavailableError(
+                f"{label} namespace exited before signalling readiness: {argv[:3]}"
+            )
+
+        try:
+            await asyncio.wait_for(_wait_ready(), timeout=10.0)
+        except TimeoutError as exc:
+            await self._reap(proc)
+            raise SandboxUnavailableError(
+                f"{label} namespace never became ready (timeout): {argv[:3]}"
+            ) from exc
+        except SandboxUnavailableError:
+            await self._reap(proc)
+            raise
+        return proc
+
+    @staticmethod
+    def _find_child_pid(parent_pid: int | None) -> int | None:
+        """First direct child of `parent_pid` (the pid-namespaced `sleep`).
+
+        The helper→unshare shim is inner.pid's parent chain head, but the
+        SANDBOXED mount/pid namespaces belong to its forked child (the
+        `sleep`). nsenter must target THAT pid to land inside the sandbox.
+        Reads /proc directly — best-effort, host-local, no subprocess.
+        """
+        if parent_pid is None:
+            return None
+        for entry in os.listdir("/proc"):
+            if not entry.isdigit():
+                continue
+            try:
+                with open(f"/proc/{entry}/stat") as fh:
+                    # ppid is field 4; comm (field 2) may contain spaces, so
+                    # parse relative to the LAST ')'.
+                    rest = fh.read().rsplit(") ", 1)[1].split()
+                if int(rest[1]) == parent_pid:  # state=rest[0], ppid=rest[1]
+                    return int(entry)
+            except (OSError, IndexError, ValueError):
+                continue
+        return None
+
+    # -- exec --------------------------------------------------------------------
+
     async def exec(self, handle: SandboxHandle, cmd: list[str]) -> ExecResult:
-        """Run `cmd` in a fresh namespace rooted at the sandbox workspace."""
+        """Run `cmd` in the sandbox workspace (cwd = the bound workspace)."""
         if not cmd:
             raise ValueError("exec requires a non-empty cmd")
+        tracked = self._tracked.get(handle.id)
+        if tracked is not None:
+            return await self._exec_tracked(handle, tracked, cmd)
+        return await self._exec_fresh(handle, cmd)
+
+    async def _exec_fresh(self, handle: SandboxHandle, cmd: list[str]) -> ExecResult:
+        """Pure shell sandbox: spawn one fresh offline namespace per exec."""
         workspace = handle.workdir / "workspace"
         if not workspace.is_dir():
             raise SandboxUnavailableError(f"spawn() first: no workspace at {workspace}")
@@ -129,7 +405,6 @@ class UnshareBackend:  # satisfies SandboxBackend structurally (Protocol)
             "-c",
             _build_shim(workspace, self._limits, cmd),
         ]
-
         started = time.monotonic()
         proc = await asyncio.create_subprocess_exec(
             *argv,
@@ -146,13 +421,128 @@ class UnshareBackend:  # satisfies SandboxBackend structurally (Protocol)
             duration_s=time.monotonic() - started,
         )
 
+    async def _exec_tracked(
+        self, handle: SandboxHandle, tracked: _Tracked, cmd: list[str]
+    ) -> ExecResult:
+        """Task sandbox: join the persistent inner namespace (offline, uid 0).
+
+        rlimits apply in the joining subshell so only the payload is limited;
+        cwd is the bound workspace (`<ns>/work`).
+        """
+        if tracked.inner.returncode is not None:
+            raise SandboxUnavailableError(
+                f"sandbox {handle.id} is not running (inner namespace exited)"
+            )
+        quoted_cmd = " ".join(shlex.quote(part) for part in cmd)
+        rlimit_prefix = (
+            f"ulimit -v {self._limits.memory_bytes // 1024}; "
+            f"ulimit -t {self._limits.cpu_seconds}; "
+            f"ulimit -f {self._limits.file_size_bytes // 512}; "
+        )
+        shell = (
+            f"cd {shlex.quote(str(tracked.ns_workdir))}; "
+            f"{rlimit_prefix}"
+            f"exec {quoted_cmd}"
+        )
+        argv = [
+            *self._helper_join_argv(tracked.helper),
+            *self._sandbox_join_argv(tracked),
+            "sh",
+            "-c",
+            shell,
+        ]
+        started = time.monotonic()
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        out, err = await proc.communicate()
+        return ExecResult(
+            cmd=cmd,
+            returncode=proc.returncode if proc.returncode is not None else -1,
+            stdout=out.decode(errors="replace"),
+            stderr=err.decode(errors="replace"),
+            duration_s=time.monotonic() - started,
+        )
+
+    # -- snapshot / destroy --------------------------------------------------------
+
     async def snapshot(self, handle: SandboxHandle) -> Path:
-        return workdir_snapshot(handle.workdir)
+        workspace_root = handle.workdir
+        tracked = self._tracked.get(handle.id)
+        if tracked is not None:
+            # Copy the tracked workspace, not the legacy <workdir>/workspace.
+            dest_parent = handle.workdir / "snapshots"
+            dest_parent.mkdir(parents=True, exist_ok=True)
+            return workdir_snapshot_from_workspace(tracked.workspace, dest_parent)
+        return workdir_snapshot(workspace_root)
 
     async def destroy(self, handle: SandboxHandle) -> None:
-        """Best-effort teardown. Namespaces die with their process; nothing to kill.
+        """Best-effort teardown. Pure shell sandboxes die with their exec; for a
+        tracked task sandbox reap AGENT → INNER → HELPER so no capture process
+        or namespace supervisor outlives the handle (REQ-3-003 lifecycle).
 
         Keeping the workdir is deliberate: snapshots must survive destroy so a
         learner's last state can be restored by the manager layer.
         """
+        tracked = self._tracked.pop(handle.id, None)
+        if tracked is not None:
+            # Agent first (it must not flush a "stopped" event into a dead
+            # sandbox), then the namespace tree. The inner `unshare --fork`
+            # shim is NOT the namespace init: killing it orphans its child
+            # (the `sleep` that is PID 1 of the sandbox pid+mnt+net ns),
+            # which reparents to host init and holds the tmpfs + bind for
+            # a full hour (observed: ~30 leaked `sleep 3600` after a test
+            # run). `--kill-child` does not reach it either (util-linux
+            # 2.38 leaks the same child under this flag combo — the child
+            # is reparented before unshare's signal handler runs). The
+            # deterministic kill is SIGKILL on the ns-init's HOST pid,
+            # which we already track as `tracked.inner_pid` (nsenter uses
+            # it for exec); the kernel then tears down the namespace with
+            # its init (no processes remain).
+            for proc in (tracked.agent, tracked.inner, tracked.helper):
+                if proc is not None:
+                    await self._reap(proc)
+            self._kill_pid(tracked.inner_pid)
         handle.pid = None
+
+    @staticmethod
+    def _kill_pid(pid: int | None, sig: int = signal.SIGKILL) -> None:
+        """Best-effort host-side signal; pid recycled or gone is not an error."""
+        if pid is None:
+            return
+        try:
+            os.kill(pid, sig)
+        except (ProcessLookupError, PermissionError):
+            pass  # already dead, or not ours — nothing to do
+
+    @staticmethod
+    async def _reap(proc: asyncio.subprocess.Process) -> None:
+        """SIGTERM then SIGKILL, tolerant of an already-dead process."""
+        if proc.returncode is not None:
+            return
+        try:
+            proc.terminate()
+        except ProcessLookupError:
+            return
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=5.0)
+        except TimeoutError:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                return
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5.0)
+            except TimeoutError:  # pragma: no cover - SIGKILL always wins
+                pass
+
+
+def workdir_snapshot_from_workspace(workspace: Path, snapshots_dir: Path) -> Path:
+    """Snapshot helper for tracked sandboxes whose workspace is `<workdir>/host/workspace`
+    instead of the legacy `<workdir>/workspace` layout."""
+    dest = snapshots_dir / datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    shutil.copytree(workspace, dest, symlinks=False)
+    return dest

apps/ai-service/ai_service/telemetry/__init__.py

@@ -0,0 +1,21 @@
+"""Live build telemetry — event models and the TraceStore protocol (REQ-3-003).
+
+Boundary rule (D-027): telemetry/ imports from config only — never from
+agents/ or api/ (agents call engines through narrow interfaces, never
+the reverse; api/ composes stores via DI).
+"""
+
+from .ingest import IngestSession, TraceIntegrityMap, telemetry_ingest_endpoint
+from .models import EventKind, TelemetryEvent, TraceSpan
+from .store import SQLiteTraceStore, TraceStore
+
+__all__ = [
+    "EventKind",
+    "IngestSession",
+    "SQLiteTraceStore",
+    "TelemetryEvent",
+    "TraceIntegrityMap",
+    "TraceSpan",
+    "TraceStore",
+    "telemetry_ingest_endpoint",
+]

apps/ai-service/ai_service/telemetry/ingest.py

@@ -0,0 +1,458 @@
+"""WS ingest protocol for learner telemetry (REQ-3-003, D-026, G-3).
+
+Frame contract — trace identity travels as QUERY PARAMS on the WS upgrade
+(`WS /v1/telemetry/ingest?learner_id=...&task_id=...&sandbox_id=...`), NOT as
+a first init frame. Rationale: the in-sandbox capture agent (Task 2-2-01) is a
+stdlib-only RFC6455 client where the URL is the cheapest thing to parametrize
+(`NC_INGEST_URL` carries the query string); identity is also visible to the
+server BEFORE accept(), so a malformed handshake can be rejected without an
+accept/close round-trip. Client messages are then ONE event per JSON text
+frame — no envelope:
+
+    {"seq": 0, "kind": "command", "payload": {...}, "ts": "...",
+     "sandbox_id": "..."}   # learner_id / task_id forbidden (URL owns them)
+
+Server → client frames are typed status envelopes:
+
+    {"type": "ack_total",      "count": N}                 — final flush summary, then close 1000
+    {"type": "seq_ack",        "seq": N}                  — advisory: durable latest_seq after
+                                                       each successful append (D-045; the
+                                                       agent trims its spool to seq > ack)
+    {"type": "gap_warning",    "missing_seqs": [...]}      — seq skipped ahead
+    {"type": "event_rejected", "detail": "..."}       — one frame failed validation
+                                                        (seq echoed when parseable)
+    {"type": "event_rejected", "seq": N, "detail": "..."}  — stored-field rejected (bad kind)
+    {"type": "flooded",        "reason": "cap_exceeded"|"queue_overflow",
+     "count": N}                                           — sent before close(1008)
+
+Keepalive: the server sends an opaque ping frame every `PING_INTERVAL_S` (the
+capture agent auto-pongs at the frame layer); a peer that is silent past
+`PONG_TIMEOUT_S` is assumed wedged, but the keepalive half only LOGS — the
+receiver half owns disconnect detection (single-box pilot: TCP EOF is
+reliable; an aggressive pong-watchdog would false-positive on loaded boxes).
+
+Flood control (GRILL G-3, BINDING — silent drop-oldest is FORBIDDEN):
+  * per-connection inbound queue bounded at `INBOUND_QUEUE_MAX` frames; on
+    overflow → close code 1008 (policy violation) + trace marked
+    INCOMPLETE_FLOODED via `TraceIntegrityMap`.
+  * total events for the (learner, task) exceeding
+    `Settings.telemetry_max_events_per_task` → same 1008 + INCOMPLETE_FLOODED.
+  `INCOMPLETE_FLOODED` is an integrity signal Proctor/Phase-3 grader read via
+  `TraceIntegrityMap.is_incomplete()` (the G-4 gate): a flooded trace can
+  never yield a credential.
+
+Boundary (D-027): telemetry/ never imports agents/ or api/. This module
+imports only `fastapi.WebSocket` for the socket type (a protocol surface, not
+a DI framework); the session engine below depends only on the TraceStore
+protocol + Settings, and api/telemetry.py injects both through plain
+parameters.
+"""
+
+import asyncio
+import contextlib
+import json
+import logging
+from datetime import datetime
+from typing import Any, Final
+
+from fastapi import WebSocket, WebSocketDisconnect
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from ..config import Settings
+from .models import TelemetryEvent
+from .store import TraceStore
+
+logger = logging.getLogger(__name__)
+
+#: WebSocket close code 1008 — policy violation (RFC 6455 §7.4.1).
+WS_CLOSE_POLICY_VIOLATION: Final = 1008
+
+#: Bounded inbound queue depth per connection (G-3). Sized for burst-tolerance
+#: well above the capture agent's emission rate; overflow is a flood signal,
+#: not a backpressure knob.
+INBOUND_QUEUE_MAX: Final = 256
+
+PING_INTERVAL_S: Final = 20.0
+
+
+class InboundEventFrame(BaseModel):
+    """Client → server event frame (one TelemetryEvent minus URL-owned ids).
+
+    `extra="forbid"`: learner_id/task_id arriving in the frame body is a
+    contract violation — identity comes from the query params only, so a
+    replayed frame can never lie about which trace it belongs to.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    seq: int = Field(ge=0)
+    kind: str = Field(min_length=1)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    ts: datetime
+    sandbox_id: str = ""
+
+
+class TraceIntegrityMap:
+    """Integrity flags for traces that can never be graded (G-3/G-4).
+
+    Process-local and deliberately small: v0.3 runs ONE ai-service process per
+    box, and the Phase-3 grader reads this flag through the same DI container
+    — D-019-style in-memory registry precedent (the sandbox handle registry is
+    the same shape). The flag is terminal within the process: a reconnect
+    sending legal events does NOT clear it — the trace is already untrusted as
+    grading input. Restarting ai-service resets flags; grading runs against a
+    live service, and the SQLite trace rows themselves are durable.
+
+    All methods are sync: mutation is a dict write, reads are dict lookups —
+    no await needed, so callers from any layer (API handlers, the grader)
+    don't inherit an async surface for a nanosecond operation.
+    """
+
+    def __init__(self) -> None:
+        # (learner_id, task_id) -> machine-readable reason (INCOMPLETE_FLOODED)
+        self._flags: dict[tuple[str, str], str] = {}
+
+    def mark(self, learner_id: str, task_id: str, reason: str) -> None:
+        """Set an integrity flag. Presence of the flag is the signal; the
+        reason is informational (last write wins)."""
+        self._flags[(learner_id, task_id)] = reason
+
+    def clear(self, learner_id: str, task_id: str) -> None:
+        """Test seam: reset a flag (production ingest never clears)."""
+        self._flags.pop((learner_id, task_id), None)
+
+    def is_incomplete(self, learner_id: str, task_id: str) -> bool:
+        """True when the trace carries ANY terminal integrity flag."""
+        return (learner_id, task_id) in self._flags
+
+    def reason(self, learner_id: str, task_id: str) -> str | None:
+        """The flag's reason (INCOMPLETE_FLOODED), or None when unflagged."""
+        return self._flags.get((learner_id, task_id))
+
+
+class IngestSession:
+    """One WebSocket ingest connection: receive → queue → drain → store.
+
+    Two tasks per connection:
+      * `_receiver` — reads frames, validates shape, enqueues (bounded queue,
+        G-3). Receives never block on SQLite.
+      * `_drainer` — pops frames in arrival order, appends via TraceStore
+        (idempotent on (learner,task,seq)), emits gap warnings, enforces the
+        per-trace event cap.
+    Either task detecting a flood closes the WS with 1008 and marks the trace
+    INCOMPLETE_FLOODED. The events queue carries `None` as the client-
+    disconnect sentinel.
+
+    - `telemetry_max_events_per_task` is consulted at connect and re-checked
+      per append against the DURABLE row count (cap compares against stored
+      events, so a skipped-ahead seq cannot burn budget that was never sent).
+      Durable count via `TraceStore.count()` (COUNT(*)) — a single aggregate
+      per append, never materializing trace rows (the pre-P7 code read
+      `len(get_trace(...))` which was O(trace) per event / O(n²) per session).
+    """
+
+    def __init__(
+        self,
+        websocket: WebSocket,
+        store: TraceStore,
+        integrity: TraceIntegrityMap,
+        settings: Settings,
+        learner_id: str,
+        task_id: str,
+        sandbox_id: str,
+    ) -> None:
+        self._ws = websocket
+        self._store = store
+        self._integrity = integrity
+        # Snapshot of the one setting ingest consults: read once at connect so
+        # a hot-reloaded Settings object mid-session can't move the cap.
+        self._max_events = settings.telemetry_max_events_per_task
+        self.learner_id = learner_id
+        self.task_id = task_id
+        self.sandbox_id = sandbox_id
+
+        self._queue: asyncio.Queue[InboundEventFrame | None] = asyncio.Queue(
+            maxsize=INBOUND_QUEUE_MAX
+        )
+        self._seen: set[int] = set()
+        self._next_expected: int | None = None  # in-connection monotonic hint
+        self._received = 0
+        self._stored = 0
+        self._deduped = 0
+        self._rejected = 0
+        self._flooded = False
+        self._flood_reason = ""
+
+    # -- receive half ----------------------------------------------------------
+
+    async def run(self) -> None:
+        """Accept, run receiver+drainer, close cleanly. Owns the WS lifecycle."""
+        await self._ws.accept()
+        logger.info(
+            "telemetry ingest connected: %s/%s sandbox=%s",
+            self.learner_id,
+            self.task_id,
+            self.sandbox_id or "(none)",
+        )
+        pinger = asyncio.create_task(self._keepalive())
+        receiver = asyncio.create_task(self._receiver())
+        drainer = asyncio.create_task(self._drainer())
+        # First terminal outcome shuts the session down: client disconnect
+        # (receiver ends) → drainer flushes; drainer ended (clean close after
+        # flush or a 1008 flood close) → receiver must not linger.
+        pending: set[asyncio.Task[None]] = {receiver, drainer}
+        try:
+            done, pending = await asyncio.wait(
+                pending, return_when=asyncio.FIRST_COMPLETED
+            )
+            if receiver in done and drainer in pending:
+                try:
+                    await drainer  # final flush → sends ack_total, close 1000
+                finally:
+                    pending.discard(drainer)
+        finally:
+            for task in (pinger, *pending):
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+
+    async def _receiver(self) -> None:
+        """Read frames; parse+enqueue. Overflow → flood shutdown (G-3).
+
+        RuntimeError from receive_text is benign here: it fires when the
+        socket was closed by the drainer (1008 flood close) while this task
+        was parked in receive — a terminal condition, not a bug.
+        """
+        try:
+            while True:
+                raw = await self._ws.receive_text()
+                frame = self._parse(raw)
+                if frame is None:
+                    # Rejected frame — keep the connection open; the producer
+                    # gets an event_rejected status frame so a malformed batch
+                    # is visible (and its seq is never stored). Yield so the
+                    # status frame flushes before we block on the next receive.
+                    await self._reject_frame(raw)
+                    await asyncio.sleep(0)
+                    continue
+                self._received += 1
+                try:
+                    self._queue.put_nowait(frame)
+                except asyncio.QueueFull:
+                    # Bounded queue — overflow is a flood, never drop-oldest.
+                    # _trigger_flood closes the socket; fall through to the
+                    # tail so the disconnect sentinel is still enqueued — the
+                    # drainer is never left parked on an empty queue after a
+                    # flood (P7 review: the pre-fix code `return`ed from the
+                    # QueueFull branch WITHOUT the sentinel, leaking the
+                    # session task set — one per flooded trace).
+                    await self._trigger_flood("queue_overflow")
+                    return
+        except WebSocketDisconnect:
+            pass
+        except RuntimeError:
+            logger.debug(
+                "ingest receiver: socket already closed (flood path) %s/%s",
+                self.learner_id,
+                self.task_id,
+            )
+        # Client gone (clean close, drop, or flood close): sentinel unblocks
+        # the drainer for a final flush. put_nowait can only fail under flood,
+        # which already terminated the session.
+        with contextlib.suppress(asyncio.QueueFull):
+            self._queue.put_nowait(None)
+
+    def _parse(self, raw: str) -> InboundEventFrame | None:
+        """Validate one frame; None means malformed (caller rejects it)."""
+        try:
+            return InboundEventFrame.model_validate_json(raw)
+        except ValidationError:
+            return None
+
+    async def _reject_frame(self, raw: str) -> None:
+        """Malformed envelope: log + event_rejected status frame (never stored)."""
+        self._rejected += 1
+        detail = "invalid event frame"
+        try:
+            InboundEventFrame.model_validate_json(raw)
+        except ValidationError as exc:
+            detail = exc.errors()[0].get("msg", "validation error")
+        logger.warning(
+            "telemetry frame rejected: %s/%s: %s", self.learner_id, self.task_id, detail
+        )
+        seq: int | None = None
+        with contextlib.suppress(Exception):
+            seq = int(json.loads(raw).get("seq"))  # best-effort echo for the producer
+        payload: dict[str, Any] = {"type": "event_rejected", "detail": detail}
+        if seq is not None:
+            payload["seq"] = seq
+        await self._send_json(payload)
+
+    # -- drain half --------------------------------------------------------------
+
+    async def _drainer(self) -> None:
+        """Pop queued frames, append to the store, then close 1000 + summary."""
+        while True:
+            frame = await self._queue.get()
+            if frame is None:  # disconnect sentinel → flush complete
+                await self._send_json(
+                    {
+                        "type": "ack_total",
+                        "count": self._stored,
+                        "deduped": self._deduped,
+                        "rejected": self._rejected,
+                    }
+                )
+                with contextlib.suppress(RuntimeError, WebSocketDisconnect):
+                    await self._ws.close(code=1000)
+                return
+            await self._append(frame)
+
+    async def _append(self, frame: InboundEventFrame) -> None:
+        # Precedence: a trace already flagged INCOMPLETE_FLOODED is terminal —
+        # the connection that triggered it is being torn down, and any stray
+        # queued frames must not resurrect the trace's intake.
+        if self._integrity.is_incomplete(self.learner_id, self.task_id):
+            await self._trigger_flood("already_flagged")
+            return
+
+        # Per-trace cap (G-3): checked against the DURABLE row count so a
+        # reconnect resumes the budget instead of resetting it, and a
+        # skipped-ahead seq cannot burn budget that was never sent.
+        if self._flood_breached():
+            await self._trigger_flood("cap_exceeded")
+            return
+
+        # TelemetryEvent's @validates hooks fire on CONSTRUCTION (setattr), so
+        # the try must wrap building the model too — an unknown kind raises
+        # before `store.append` is ever reached.
+        event: TelemetryEvent
+        before = self._store.latest_seq(self.learner_id, self.task_id)
+        try:
+            event = TelemetryEvent(
+                learner_id=self.learner_id,
+                task_id=self.task_id,
+                seq=frame.seq,
+                kind=frame.kind,
+                payload=frame.payload,
+                ts=frame.ts,
+                sandbox_id=frame.sandbox_id or self.sandbox_id,
+            )
+            self._store.append(event)
+        except ValueError as exc:  # unknown kind / invalid field
+            self._rejected += 1
+            await self._send_json(
+                {"type": "event_rejected", "seq": frame.seq, "detail": str(exc)}
+            )
+            return
+        after = self._store.latest_seq(self.learner_id, self.task_id)
+
+        if after == before and frame.seq in self._seen:
+            self._deduped += 1  # at-least-once retry; stored once (idempotent)
+        else:
+            self._stored += 1
+        self._seen.add(frame.seq)
+        # Seq-ack (D-045, REQ-5-007): advisory hint carrying the durable
+        # latest_seq AFTER this append — the capture agent trims its spool to
+        # seq > ack on receipt, bounding the replay margin to the in-flight
+        # window. Emitted on dedup'd appends too (a-6) so a replay flush
+        # tightens the margin immediately. Gap detection stays authoritative
+        # (_check_gap below); G-3 flood semantics untouched.
+        await self._send_json({"type": "seq_ack", "seq": after})
+        await self._check_gap(frame.seq)
+        # SQLite appends are sync and fast; on a burst the drainer can hold
+        # the loop between receives. Yield so the WS writer flushes the close
+        # and the pinger/interleave stay live under the eventlet-free portal.
+        await asyncio.sleep(0)
+
+    def _flood_breached(self) -> bool:
+        """True when this append would exceed the per-trace event budget."""
+        # Durable count (NOT latest_seq+1 — a skipped-ahead seq must not burn
+        # un-sent events' budget) via COUNT(*): never materialize the trace
+        # per append (P7 review — the old len(get_trace(...)) built every row
+        # object per event, O(trace) per append / O(n²) per session).
+        durable = self._store.count(learner_id=self.learner_id, task_id=self.task_id)
+        return durable >= self._max_events
+
+    async def _check_gap(self, incoming_seq: int) -> None:
+        """Seq skipped ahead → log + per-connection gap_warning status frame."""
+        if self._next_expected is not None and incoming_seq > self._next_expected:
+            missing = list(range(self._next_expected, incoming_seq))
+            logger.warning(
+                "telemetry gap: %s/%s missing seqs %s (arrived seq=%d)",
+                self.learner_id,
+                self.task_id,
+                missing,
+                incoming_seq,
+            )
+            await self._send_json({"type": "gap_warning", "missing_seqs": missing})
+        if self._next_expected is None or incoming_seq >= self._next_expected:
+            self._next_expected = incoming_seq + 1
+
+    # -- flood + keepalive ------------------------------------------------------
+
+    async def _trigger_flood(self, reason: str) -> None:
+        """G-3: 1008 close + INCOMPLETE_FLOODED mark. Exactly once."""
+        if self._flooded:
+            return
+        self._flooded = True
+        self._flood_reason = reason
+        self._integrity.mark(self.learner_id, self.task_id, "INCOMPLETE_FLOODED")
+        logger.warning(
+            "telemetry flood: %s/%s reason=%s — closing 1008, trace marked "
+            "INCOMPLETE_FLOODED (G-3; Proctor/grade gate will refuse it)",
+            self.learner_id,
+            self.task_id,
+            reason,
+        )
+        await self._send_json(
+            {"type": "flooded", "reason": reason, "count": self._received}
+        )
+        with contextlib.suppress(RuntimeError, WebSocketDisconnect):
+            await self._ws.close(
+                code=WS_CLOSE_POLICY_VIOLATION,
+                reason=f"telemetry flood control (G-3): {reason}",
+            )
+
+    async def _keepalive(self) -> None:
+        """Protocol-level ping on an interval (agent auto-pongs at frame level).
+
+        A send failure means the socket is already gone — the receiver half
+        independently surfaces the disconnect; we just stop pinging.
+        """
+        while True:
+            await asyncio.sleep(PING_INTERVAL_S)
+            try:
+                await self._ws.send_bytes(b"\x89ping-nextcraft")
+            except (RuntimeError, WebSocketDisconnect):
+                return
+
+    async def _send_json(self, payload: dict[str, Any]) -> None:
+        """Best-effort status frame; the socket may already be gone."""
+        with contextlib.suppress(RuntimeError, WebSocketDisconnect):
+            await self._ws.send_json(payload)
+
+
+async def telemetry_ingest_endpoint(
+    websocket: WebSocket,
+    learner_id: str,
+    task_id: str,
+    store: TraceStore,
+    integrity: TraceIntegrityMap,
+    settings: Settings,
+    sandbox_id: str = "",
+) -> None:
+    """Engine entry: build the session and run it. api/telemetry.py calls this
+    with query params + app.state services already resolved — this signature
+    is deliberately Depends-free (telemetry/ never knows FastAPI DI exists).
+    """
+    session = IngestSession(
+        websocket=websocket,
+        store=store,
+        integrity=integrity,
+        settings=settings,
+        learner_id=learner_id,
+        task_id=task_id,
+        sandbox_id=sandbox_id,
+    )
+    await session.run()

apps/ai-service/ai_service/telemetry/models.py

@@ -0,0 +1,110 @@
+"""Telemetry event record — the row the trace store persists (REQ-3-003, D-027).
+
+One model serves both as the JSON payload sent by producers and as the SQLite
+row schema. `payload` is stored as a JSON column (native JSONB on Postgres —
+no migration-time shape change, D-027).
+
+Field contract (consumed by the trace store and the grader):
+    learner_id  — non-empty learner identifier.
+    task_id     — non-empty task/session identifier; trace identity is the
+                  (learner_id, task_id) pair.
+    seq         — sequence number per trace, >= 0. Monotonicity per
+                  (learner, task) is enforced by the store (Task 2-1-02);
+                  this model only rejects negative seqs.
+    kind        — event discriminator: command | file_diff | run_result |
+                  test_result | activity | stdin | stdout.
+    payload     — free-form JSON detail blob.
+    ts          — envelope timestamp (UTC); monotonicity enforced at ingest.
+    sandbox_id  — originating sandbox ("" for non-sandbox sources).
+
+Boundary (D-027): telemetry/ never imports agents/ or api/.
+"""
+
+from datetime import datetime
+from typing import Any, Literal, get_args
+
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import JSON, Index, String
+from sqlalchemy.orm import validates
+from sqlmodel import Field as SQLField
+from sqlmodel import SQLModel
+
+EventKind = Literal[
+    "command",
+    "file_diff",
+    "run_result",
+    "test_result",
+    "activity",
+    "stdin",
+    "stdout",
+]
+# P5: get_args() is the typed accessor for Literal values (bare __args__
+# trips mypy on the typing special form).
+_EVENT_KINDS: frozenset[str] = frozenset(get_args(EventKind))
+
+
+class TelemetryEvent(SQLModel, table=True):
+    """A single durable telemetry event; (learner_id, task_id, seq) is PK.
+
+    Constraint enforcement uses SQLAlchemy `@validates` hooks: sqlmodel
+    0.0.42's metaclass drops pydantic `Field(ge=...)`/`field_validator`
+    constraints for table models (the decorators register but never make it
+    into the core schema), while `@validates` fires on every attribute set —
+    construction included — and raises ValueError on violation. seq >= 0 plus
+    a VARCHAR kind column keep the DB shape Postgres-ready (D-027).
+    """
+
+    __tablename__ = "telemetry_event"
+    # PK columns already produce a unique index; this secondary index covers
+    # trace reads ordered by seq without depending on the PK column order
+    # (Postgres migration target D-027).
+    __table_args__ = (Index("ix_telemetry_event_trace", "learner_id", "task_id"),)
+
+    learner_id: str = SQLField(primary_key=True)
+    task_id: str = SQLField(primary_key=True)
+    seq: int = SQLField(primary_key=True)
+    # Bare Literal annotations crash sqlmodel<=0.0.42's column inference
+    # (issubclass(TypeAlias, Enum)); an explicit sa_type + the validates hook
+    # below gives the same contract: VARCHAR column, Literal-rejected values.
+    kind: EventKind = SQLField(sa_type=String)
+    # JSON column: stored as TEXT on SQLite, native JSONB on Postgres (D-027).
+    payload: dict[str, Any] = SQLField(default_factory=dict, sa_type=JSON)
+    ts: datetime
+    sandbox_id: str = SQLField(default="")
+
+    @validates("learner_id", "task_id")
+    def _ids_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty identifier")
+        return value
+
+    @validates("seq")
+    def _seq_non_negative(self, key: str, value: int) -> int:
+        if value < 0:
+            raise ValueError("seq must be >= 0 (monotonicity is the store's job)")
+        return value
+
+    @validates("kind")
+    def _kind_is_known(self, key: str, value: str) -> str:
+        if value not in _EVENT_KINDS:
+            raise ValueError(f"unknown event kind: {value!r}")
+        return value
+
+
+class TraceSpan(BaseModel):
+    """Derived view: the ordered event trace for one (learner_id, task_id).
+
+    NOT a table — materialized by the store from persisted TelemetryEvents
+    (grader/Lab consume this shape; replay order is the seq column).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    learner_id: str = Field(min_length=1)
+    task_id: str = Field(min_length=1)
+    events: tuple[TelemetryEvent, ...] = ()
+
+    @property
+    def latest_seq(self) -> int:
+        """Highest seq in the span; -1 when empty (store convention)."""
+        return self.events[-1].seq if self.events else -1

apps/ai-service/ai_service/telemetry/store.py

@@ -0,0 +1,220 @@
+"""TraceStore — telemetry persistence protocol + SQLite implementation (REQ-3-003, D-027).
+
+Postgres-migration-ready (D-027): the protocol is the only surface the API /
+grader layers touch; swapping SQLiteTraceStore for a Postgres-backed
+implementation must not change call sites. The `telemetry_event` table uses
+only portable column types (str / int / datetime / JSON), so the same SQLModel
+schema stands up unchanged on Postgres.
+
+Ingest is at-least-once: duplicates carry the same (learner_id, task_id, seq)
+idempotency key, so `append` with a triplet that is already stored is a no-op.
+The pair (learner_id, task_id) identifies a trace; `seq` numbers events in it
+starting at 0.
+
+Concurrency (a-3): the engine enables WAL + synchronous=NORMAL and a busy
+timeout at connection time, so the ingest writer and grader readers do not hit
+`database is locked` on the single-box pilot.
+
+Boundary: `telemetry/` never imports `agents/` / `api/` and has no FastAPI
+dependency.
+"""
+
+import logging
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+import sqlalchemy as sa
+from sqlmodel import Session, SQLModel, col, create_engine, select
+
+from ..config import Settings
+from .models import TelemetryEvent
+
+logger = logging.getLogger(__name__)
+
+
+class TraceStore(Protocol):
+    """Persistence contract for ordered per-learner task trace streams.
+
+    Implemented by SQLiteTraceStore (v0.3, D-027); a Postgres implementation
+    must satisfy the same surface.
+    """
+
+    def append(self, event: TelemetryEvent) -> None:
+        """Store one event. IDEMPOTENT on (learner_id, task_id, seq):
+
+        at-least-once ingest retries with the same triplet are deduped
+        (stored once), not rejected. Later events must not overwrite an
+        existing row.
+        """
+        ...
+
+    def get_trace(self, learner_id: str, task_id: str) -> list[TelemetryEvent]:
+        """All stored events for the trace, ordered by seq ascending.
+
+        Detached from any DB session — safe to pass across layers. Empty list
+        when the trace has no events.
+        """
+        ...
+
+    def gaps(self, learner_id: str, task_id: str) -> list[int]:
+        """Missing seqs in 0..latest for the trace ([0,2,3] stored -> [1])."""
+        ...
+
+    def latest_seq(self, learner_id: str, task_id: str) -> int:
+        """Highest stored seq for the trace; -1 when no events exist."""
+        ...
+
+    def count(self, learner_id: str, task_id: str) -> int:
+        """Number of stored events for the trace (COUNT(*), never
+        materializes rows — the ingest cap consults this per append, so
+        an O(trace) implementation would make ingest O(n²) per session).
+        """
+        ...
+
+    def list_tasks(self, learner_id: str) -> list[str]:
+        """Distinct task_ids with at least one event for the learner."""
+        ...
+
+    def close(self) -> None:
+        """Release DB connections. Store must not be used after close."""
+        ...
+
+
+def _sqlite_connect(dbapi_connection: sqlite3.Connection, _: object) -> None:
+    """Per-connection pragma setup (a-3).
+
+    journal_mode=WAL  — readers never block the single writer.
+    synchronous=NORMAL — safe in WAL mode, avoids full fsync-per-commit.
+    busy_timeout=5000  — retry briefly under contention instead of
+                         `OperationalError: database is locked`.
+    """
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.close()
+
+
+def _as_utc(ts: datetime) -> datetime:
+    """Timestamps travel as naive datetime on SQLite, tz-aware elsewhere.
+
+    SQLite (via SQLModel) drops tzinfo; Postgres TIMESTAMP WITH TIME ZONE
+    keeps it. Normalizing on the read/write boundary makes the store's
+    contract tz-aware UTC regardless of the backend (D-027).
+    """
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=UTC)  # naive UTC read-side: label as UTC
+    return ts.astimezone(UTC)
+
+
+class SQLiteTraceStore:
+    """SQLite-backed TraceStore (SQLModel). First real persistence (D-027)."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path: Path = db_path if db_path is not None else Settings().db_path
+        self._engine = create_engine(f"sqlite:///{self._db_path}")
+        sa.event.listen(self._engine, "connect", _sqlite_connect)
+        SQLModel.metadata.create_all(self._engine)
+
+    @contextmanager
+    def _session(self) -> Iterator[Session]:
+        # expire_on_commit=False: ORM objects returned from `append`'s
+        # IntegrityError path stay usable without a refresh round-trip.
+        with Session(self._engine, expire_on_commit=False) as session:
+            yield session
+
+    def append(self, event: TelemetryEvent) -> None:
+        # INSERT-if-absent via PK: sqlite3 raises IntegrityError on a
+        # duplicate (learner_id, task_id, seq); swallow it — the row is
+        # already stored, which is the dedup contract for at-least-once
+        # ingest. `session.merge` would upsert instead; wrong semantics here.
+        with self._session() as session:
+            try:
+                session.add(event)
+                session.commit()
+            except sa.exc.IntegrityError:
+                session.rollback()
+                logger.debug(
+                    "trace event dedup: %s/%s seq=%d already stored",
+                    event.learner_id,
+                    event.task_id,
+                    event.seq,
+                )
+
+    def get_trace(self, learner_id: str, task_id: str) -> list[TelemetryEvent]:
+        with self._session() as session:
+            stmt = (
+                select(TelemetryEvent)
+                .where(TelemetryEvent.learner_id == learner_id)
+                .where(TelemetryEvent.task_id == task_id)
+                # P5: col() — SQLModel class attrs are Mapped[T], the
+                # column reference rides col() in order_by/func.count.
+                .order_by(col(TelemetryEvent.seq))
+            )
+            results = session.exec(stmt).all()
+            # Detach from the session: callers must not depend on open-session
+            # ORM magic (lazy loads fail once the session is closed).
+            for row in results:
+                row.ts = _as_utc(row.ts)
+                session.expunge(row)
+            return list(results)
+
+    def _stored_seqs(self, learner_id: str, task_id: str) -> list[int]:
+        with self._session() as session:
+            stmt = (
+                select(TelemetryEvent.seq)
+                .where(TelemetryEvent.learner_id == learner_id)
+                .where(TelemetryEvent.task_id == task_id)
+                .order_by(col(TelemetryEvent.seq))
+            )
+            # sqlmodel scalar select: rows are plain ints, not 1-tuples.
+            return [int(seq) for seq in session.exec(stmt).all()]
+
+    def gaps(self, learner_id: str, task_id: str) -> list[int]:
+        seqs = self._stored_seqs(learner_id, task_id)
+        if not seqs:
+            return []
+        present = set(seqs)
+        # seq numbering starts at 0; a gap is any seq in 0..latest not stored.
+        return [seq for seq in range(seqs[-1] + 1) if seq not in present]
+
+    def latest_seq(self, learner_id: str, task_id: str) -> int:
+        with self._session() as session:
+            stmt = (
+                select(sa.func.max(TelemetryEvent.seq))
+                .where(TelemetryEvent.learner_id == learner_id)
+                .where(TelemetryEvent.task_id == task_id)
+            )
+            latest: Any = session.exec(stmt).one()
+        return -1 if latest is None else int(latest)
+
+    def count(self, learner_id: str, task_id: str) -> int:
+        # COUNT(*) at the DB — no row materialization. The ingest flood cap
+        # calls this per append (telemetry/ingest._flood_breached); the
+        # docstring-free body keeps it obvious what the query shape is.
+        with self._session() as session:
+            stmt = (
+                select(sa.func.count(col(TelemetryEvent.seq)))
+                .where(TelemetryEvent.learner_id == learner_id)
+                .where(TelemetryEvent.task_id == task_id)
+            )
+            total: Any = session.exec(stmt).one()
+        return int(total or 0)
+
+    def list_tasks(self, learner_id: str) -> list[str]:
+        with self._session() as session:
+            stmt = (
+                select(TelemetryEvent.task_id)
+                .where(TelemetryEvent.learner_id == learner_id)
+                .distinct()
+                .order_by(TelemetryEvent.task_id)
+            )
+            # sqlmodel scalar select: rows are plain strs, not 1-tuples.
+            return [str(task_id) for task_id in session.exec(stmt).all()]
+
+    def close(self) -> None:
+        self._engine.dispose()

apps/ai-service/ai_service/telemetry/tokens.py

@@ -0,0 +1,62 @@
+"""HMAC tokens for the WS ingest socket (v0.4.7, P1 final-review flag).
+
+The ingest WS is a grading input: events land in the trace store the
+Assessor/Proctor consume. In network mode the socket is reachable on the
+LAN, and the endpoint accepted any ``learner_id``/``task_id`` query params —
+anyone on the network could poison or flood a learner's trace (grading
+DoS, the G-3 flood cap only limits volume, not identity).
+
+The sandbox manager bakes ``token=<hmac>`` into ``NC_INGEST_URL``; the WS
+endpoint recomputes the HMAC from the presented identity and rejects on
+mismatch. Nonce-free and stateless: the token binds (learner_id, task_id,
+sandbox_id) to the process's secret — nothing to store, nothing to leak
+beyond the URL the manager already owns. Restart rotates the secret when
+unset (per-boot random); sandboxes are not reboot-persistent, so stale
+URLs dying with the boot is the correct lifecycle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+_TOKEN_TTL_BIND_FIELDS = ("learner_id", "task_id", "sandbox_id")
+
+
+class IngestToken:
+    """Mint/verify HMAC ingest tokens bound to the settings secret."""
+
+    def __init__(self, secret: str = "") -> None:
+        # Empty/short configured secrets are REPLACED per boot (never warn-
+        # and-accept a guessable secret on an unauthenticated socket).
+        self._secret = (
+            secret.encode("utf-8")
+            if secret
+            else secrets.token_bytes(32)
+        )
+
+    def mint(self, learner_id: str, task_id: str, sandbox_id: str) -> str:
+        msg = _bind_message(learner_id, task_id, sandbox_id)
+        return hmac.new(self._secret, msg, hashlib.sha256).hexdigest()
+
+    def verify(
+        self, token: str, learner_id: str, task_id: str, sandbox_id: str
+    ) -> bool:
+        expected = self.mint(learner_id, task_id, sandbox_id)
+        # compare_digest guards the timing channel; an empty token never
+        # matches (mint always yields 64 hex chars).
+        return bool(token) and hmac.compare_digest(expected, token)
+
+
+def _bind_message(learner_id: str, task_id: str, sandbox_id: str) -> bytes:
+    # Length-prefixed concat — no delimiter injection: a (learner, task)
+    # pair cannot be re-spelled into another valid binding.
+    parts = [learner_id, task_id, sandbox_id]
+    return b"\x00".join(
+        f"{len(p)}:{p}".encode() for p in parts
+    )
+
+
+#: Field names bound into the token (docs + tests import this).
+TOKEN_BIND_FIELDS = tuple(_TOKEN_TTL_BIND_FIELDS)

apps/ai-service/ai_service/variants/__init__.py

@@ -0,0 +1,31 @@
+"""Per-learner variant task generation — templates, generator, VariantStore (REQ-3-005).
+
+Boundary rule (D-027): variants/ is an engine module — it never imports
+api/; its ONLY agents/ dependency is the module-direct
+agents.structured import in generator.py (the sanctioned shared D-020
+structured defense, same exception as grading/engine.py). api/ composes
+the generator and store via DI; store.py imports config only.
+
+CO-ORDINATION NOTE (ADD, don't REMOVE — same convention as grading/):
+This __init__.py is a minimal placeholder created by the VariantStore
+task (4-1-02). The templates task (4-1-01) owns this file's final shape
+— when templates.py lands, ADD its exports alongside these; do not
+remove the store exports below.
+
+Wave status: store.py (VariantRecord, VariantStore, SQLiteVariantStore)
+landed in Wave 1 (task 4-1-02); templates.py is Wave 1 task 4-1-01;
+generator.py is Wave 2 (4-2-01).
+"""
+
+from .store import SQLiteVariantStore, VariantRecord, VariantStore
+from .templates import TEMPLATES, TaskTemplate, get_template, template_for_competency
+
+__all__ = [
+    "SQLiteVariantStore",
+    "TEMPLATES",
+    "TaskTemplate",
+    "VariantRecord",
+    "VariantStore",
+    "get_template",
+    "template_for_competency",
+]

apps/ai-service/ai_service/variants/generator.py

@@ -0,0 +1,138 @@
+"""Seeded per-learner variant generator (D-029, REQ-3-005).
+
+Contract (binding, from GRILL + PLAN Must-Haves):
+- REPRODUCIBLE: seed = sha256(template_id|learner_id|milestone); the same
+  (template, learner) re-derives the same seed, params, task_id — and the
+  second generate() call is a cache hit with NO LLM call.
+- DISTINCT: different learners on the same template draw different params
+  (the sampler is seeded per-learner) and receive distinct statements.
+- NEVER BLOCKS ON THE LLM: the deterministic skeleton render
+  (`template.render(params)`) is a complete, valid statement; if the D-020
+  LLM render fails after its bounded retry, the fallback is used — and
+  because the fallback is exactly `template.render(seed-params)`, it is
+  auditable from the persisted seed + params without a provenance column.
+- AUDITABLE: seed + params + statement persist via VariantStore
+  (insert-only first-wins) — the proctoring cross-check path.
+- FAIR (a-5): slot draws change the scenario, never the difficulty; the
+  template's rubric anchors bound the expected effort envelope, so every
+  variant of one template is held to the same bar.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..agents.structured import StructuredOutputError, structured_completion
+from ..llm.types import Message
+from ..prompts.variant import VARIANT_SCHEMA_HINT, render_variant_prompt
+from .store import VariantRecord
+from .templates import TaskTemplate, get_template
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..llm.base import LLMProvider
+    from .store import VariantStore
+
+MILESTONE = "v0.3"
+
+
+class RenderedVariant(BaseModel):
+    """D-20-validated LLM render output (statement only — files come from the template)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    statement: str = Field(min_length=20)
+
+
+class UnknownTemplateError(ValueError):
+    """Raised when generate() is asked for a template id not in the library."""
+
+
+def derive_seed(template_id: str, learner_id: str, milestone: str = MILESTONE) -> str:
+    """Reproducible per-(template, learner, milestone) seed (D-029)."""
+    return hashlib.sha256(f"{template_id}|{learner_id}|{milestone}".encode()).hexdigest()
+
+
+def derive_task_id(seed: str) -> str:
+    """Deterministic grading/telemetry task key from the seed (16 hex chars)."""
+    return f"task-{seed[:16]}"
+
+
+class VariantGenerator:
+    """Seeded instantiation over the template library. DI: store + provider."""
+
+    def __init__(self, store: VariantStore, provider: LLMProvider, model: str) -> None:
+        self._store = store
+        self._provider = provider
+        self._model = model
+
+    async def generate(self, learner_id: str, template_id: str) -> VariantRecord:
+        template = get_template(template_id)
+        if template is None:
+            raise UnknownTemplateError(f"no task template with id {template_id!r}")
+
+        # Cache: D-029 reproducibility — same (learner, template) is served
+        # from the store with no LLM call.
+        cached = self._store.get(learner_id, template_id)
+        if cached is not None:
+            return cached
+
+        seed_hex = derive_seed(template_id, learner_id)
+        task_id = derive_task_id(seed_hex)
+        params = template.sample_params(_seed_int(seed_hex))
+        _validate_params(template, params)
+
+        statement = await self._render(template, params)
+        record = VariantRecord(
+            learner_id=learner_id,
+            task_id=task_id,
+            template_id=template_id,
+            seed=seed_hex,
+            params=dict(params),
+            statement=statement,
+            starter_files=dict(template.starter_files),
+            environment=template.environment,
+            test_command=template.test_command,
+            created_at=datetime.now(UTC),
+        )
+        self._store.save(record)
+        return record
+
+    async def _render(self, template: TaskTemplate, params: dict[str, str | int]) -> str:
+        """LLM render via D-020; deterministic fallback never blocks task work.
+
+        Provenance note: unlike grades, variants carry no `model` column —
+        the deterministic fallback is exactly `template.render(params)`,
+        re-derivable from the persisted seed + params, so a fallback render is
+        auditable without storing provenance (the seed IS the provenance).
+        """
+        messages: list[Message] = render_variant_prompt(template, params)
+        try:
+            rendered = await structured_completion(
+                self._provider,
+                messages,
+                model=self._model,
+                schema=RenderedVariant,
+                schema_hint=VARIANT_SCHEMA_HINT,
+            )
+        except StructuredOutputError:
+            # Deterministic fallback: the skeleton + seeded slots is already a
+            # complete statement, re-derivable from the persisted seed.
+            return template.render(params)
+        return rendered.statement
+
+
+def _seed_int(seed_hex: str) -> int:
+    """Stable int for random.Random from the hex seed."""
+    return int(seed_hex[:16], 16)
+
+
+def _validate_params(template: TaskTemplate, params: dict[str, str | int]) -> None:
+    """Defense in depth: every sampled value must be schema-valid (a-5)."""
+    for slot in template.slots:
+        value = params.get(slot.name)
+        if value is None or not slot.validate_value(value):
+            raise ValueError(f"sampled params invalid for slot {slot.name!r}: {value!r}")

apps/ai-service/ai_service/variants/store.py

@@ -0,0 +1,353 @@
+"""VariantStore — variant persistence protocol + SQLite implementation (REQ-3-005, D-027).
+
+Postgres-migration-ready (D-027): the protocol is the only surface the
+variant generator and API layers touch; swapping SQLiteVariantStore for a
+Postgres-backed implementation must not change call sites. The
+`variant_record` table uses only portable column types (str / JSON /
+datetime), so the same SQLModel schema stands up unchanged on Postgres.
+
+Insert-only, NOT upsert: (learner_id, template_id) is the variant identity
+and the FIRST generation is authoritative — reproducibility (D-029) means
+the seed re-derives the same variant, so the generator's cache path serves
+`get` instead of saving again. `save` is a plain INSERT; a duplicate pair
+raises sqlalchemy.exc.IntegrityError to the caller (documented behavior).
+`task_id` is unique too — it is the grading/telemetry trace key, so a
+trace or grade can never silently join to a different variant. Both
+rejections are deliberate: overwriting a stored variant would swap a
+learner's graded task underneath its trace and grade (audit corruption).
+Contrast TraceStore.append (dedup-keep-first, swallowed — at-least-once
+ingest) and GradeStore.save (upsert-latest-wins — a regrade is
+latest-state); this store is the third contract of the D-027 family.
+
+Concurrency (a-3): the store enables WAL + synchronous=NORMAL and a busy
+timeout at connection time, so a generation writer and API readers do not
+hit `database is locked` on the single-box pilot.
+
+`created_at` contract: callers stamp UTC (datetime.now(UTC)); SQLite
+stores it naive and the read paths re-label it tz-aware UTC (same
+boundary normalization as TelemetryEvent.ts / GradeRecord.created_at, so
+the contract holds on any backend).
+
+Boundary (D-027): `variants/` never imports `agents/` / `api/`; this
+module imports config only.
+"""
+
+import logging
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+import sqlalchemy as sa
+from sqlalchemy import JSON, Index, String, UniqueConstraint
+from sqlalchemy.orm import validates
+from sqlmodel import Field, Session, SQLModel, col, create_engine, select
+
+from ..config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class VariantRecord(SQLModel, table=True):
+    """A persisted task variant; (learner_id, template_id) is the PK — first wins.
+
+    Written once by the variant generator (Task 4-2-01), read by the API
+    layer and proctoring cross-checks through the VariantStore protocol.
+    Constraint enforcement mirrors TelemetryEvent / GradeRecord: sqlmodel
+    0.0.42's metaclass drops pydantic constraints on table models, so
+    SQLAlchemy `@validates` hooks enforce instead and the column types
+    stay Postgres-ready (D-027).
+
+    Field contract:
+        learner_id     — non-empty learner identifier (same id space as
+                         traces and grades).
+        template_id    — non-empty task template identifier; variant
+                         identity is the (learner_id, template_id) pair —
+                         the pair the generator caches on (exactly one
+                         variant per learner per template).
+        task_id        — non-empty, GLOBALLY unique task identifier; the
+                         grading/telemetry trace key (the (learner_id,
+                         task_id) pair TraceStore / GradeStore key on),
+                         stamped at generation so a variant's trace and
+                         grade join back to it exactly once.
+        seed           — non-empty variant seed (D-029); derived from
+                         (template_id, learner_id, milestone) so the
+                         variant is reproducible and auditable.
+        params         — typed parameter-slot values the generator filled;
+                         JSON dict. An empty dict is legal (a slotless
+                         template).
+        statement      — non-empty rendered task statement shown to the
+                         learner (distinct per learner by construction,
+                         REQ-3-005).
+        starter_files  — workspace scaffold: filename -> file content;
+                         JSON dict. An empty dict is legal (no scaffold).
+        created_at     — UTC generation timestamp.
+    """
+
+    __tablename__ = "variant_record"
+    # The composite PK covers (learner_id, template_id) point lookups; the
+    # unique task_id covers get_by_task (the grading/telemetry join path);
+    # the two secondary indexes cover list_for_learner / list_by_template
+    # ordered by created_at without a sort step (Postgres target D-027).
+    __table_args__ = (
+        UniqueConstraint("task_id", name="uq_variant_record_task_id"),
+        Index("ix_variant_record_learner_created", "learner_id", "created_at"),
+        Index("ix_variant_record_template_created", "template_id", "created_at"),
+    )
+
+    learner_id: str = Field(primary_key=True)
+    template_id: str = Field(primary_key=True)
+    task_id: str
+    seed: str
+    # JSON columns: stored as TEXT on SQLite, native JSONB on Postgres (D-027).
+    params: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    statement: str
+    starter_files: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    #: REQ-5-005 (D-044): the environment kind rides the record to the API
+    #: and TS client; defaults keep pre-v0.5 rows 'build'.
+    environment: str = Field(default="build", sa_type=String)
+    #: The variant's real test command (was a dead template field — v0.5
+    #: surfaces it so the Run/Test buttons stop hardcoding pytest).
+    test_command: str = Field(default="", sa_type=String)
+    created_at: datetime
+
+    @validates("learner_id", "template_id", "task_id")
+    def _ids_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty identifier")
+        return value
+
+    @validates("seed")
+    def _seed_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty seed string")
+        return value
+
+    @validates("statement")
+    def _statement_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty statement string")
+        return value
+
+
+class VariantStore(Protocol):
+    """Persistence contract for reproducible per-learner task variants.
+
+    Implemented by SQLiteVariantStore (v0.3, D-027); a Postgres
+    implementation must satisfy the same surface.
+    """
+
+    def save(self, variant: VariantRecord) -> None:
+        """Persist a new variant. INSERT-ONLY on (learner_id, template_id):
+        the FIRST generated variant is authoritative (reproducibility,
+        D-029); a duplicate pair raises sqlalchemy.exc.IntegrityError to
+        the caller — the generator serves cached variants via `get`
+        instead of saving again. `task_id` is unique too: claiming an
+        existing trace key for a different variant is equally rejected.
+        NOT upsert; contrast GradeStore.save (latest-wins) and
+        TraceStore.append (dedup-keep-first, swallowed).
+        """
+        ...
+
+    def get(self, learner_id: str, template_id: str) -> VariantRecord | None:
+        """The learner's stored variant for the template; None when none
+        exists. Detached from any DB session — safe to pass across layers.
+        """
+        ...
+
+    def get_by_task(self, task_id: str) -> VariantRecord | None:
+        """The variant owning the task key (the grading/telemetry join
+        path); None when none exists. Detached from any DB session.
+        """
+        ...
+
+    def list_for_learner(self, learner_id: str) -> list[VariantRecord]:
+        """All stored variants for the learner, ordered by created_at
+        ascending (chronological; task_id breaks same-instant ties).
+        Empty list when the learner has none.
+        """
+        ...
+
+    def list_by_template(self, template_id: str) -> list[VariantRecord]:
+        """All stored variants generated from the template — one row per
+        learner — ordered by created_at ascending (chronological;
+        learner_id breaks same-instant ties). Empty list when the
+        template has none. The proctoring cross-check path (seed params
+        per learner) reads through this.
+        """
+        ...
+
+    def close(self) -> None:
+        """Release DB connections. Store must not be used after close."""
+        ...
+
+
+def _sqlite_connect(dbapi_connection: sqlite3.Connection, _: object) -> None:
+    """Per-connection pragma setup (a-3). Mirrors telemetry/grading stores.
+
+    journal_mode=WAL  — readers never block the single writer.
+    synchronous=NORMAL — safe in WAL mode, avoids full fsync-per-commit.
+    busy_timeout=5000  — retry briefly under contention instead of
+                         `OperationalError: database is locked`.
+    """
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.close()
+
+
+def _as_utc(ts: datetime) -> datetime:
+    """Timestamps travel as naive datetime on SQLite, tz-aware elsewhere.
+
+    SQLite (via SQLModel) drops tzinfo; Postgres TIMESTAMP WITH TIME ZONE
+    keeps it. Normalizing on the read path makes the store's contract
+    tz-aware UTC regardless of the backend (D-027).
+    """
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=UTC)  # naive UTC read-side: label as UTC
+    return ts.astimezone(UTC)
+
+
+class SQLiteVariantStore:
+    """SQLite-backed VariantStore (SQLModel). Third protocol-wrapped store
+    of the D-027 family (first: SQLiteTraceStore, second: SQLiteGradeStore).
+    """
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path: Path = db_path if db_path is not None else Settings().db_path
+        self._engine = create_engine(f"sqlite:///{self._db_path}")
+        sa.event.listen(self._engine, "connect", _sqlite_connect)
+        SQLModel.metadata.create_all(self._engine)
+        # v0.5 schema (D-044) added two columns to an existing table.
+        # create_all does NOT ALTER existing tables: on a box with a
+        # pre-v0.5 ~/.nextcraft/data/nextcraft.db, every variant read/write
+        # would raise OperationalError("no such column: variant_record.
+        # environment") — a silent total breakage of the variant path
+        # (final-review P0, verified empirically). Backfill the missing
+        # columns with the model defaults ('build' keeps pre-v0.5 rows
+        # build-kind per the field contract; '' falls back to pytest at
+        # the API seam, api/variants._to_response). Idempotent: the
+        # PRAGMA table_info check makes re-runs no-ops.
+        self._ensure_v05_columns()
+
+    def _ensure_v05_columns(self) -> None:
+        """Add v0.5 columns to a pre-v0.5 variant_record table (idempotent)."""
+        from sqlalchemy import text
+
+        with self._engine.begin() as conn:
+            columns = {row[1] for row in conn.execute(text("PRAGMA table_info(variant_record)"))}
+            if "environment" not in columns:
+                conn.execute(
+                    text(
+                        "ALTER TABLE variant_record ADD COLUMN environment "
+                        "VARCHAR DEFAULT 'build' NOT NULL"
+                    )
+                )
+                logger.info("variant store: backfilled 'environment' (pre-v0.5 schema)")
+            if "test_command" not in columns:
+                conn.execute(
+                    text(
+                        "ALTER TABLE variant_record ADD COLUMN test_command "
+                        "VARCHAR DEFAULT '' NOT NULL"
+                    )
+                )
+                logger.info("variant store: backfilled 'test_command' (pre-v0.5 schema)")
+
+    @contextmanager
+    def _session(self) -> Iterator[Session]:
+        # expire_on_commit=False: identical session behavior to the other
+        # D-027 stores. save() never commits on the error path and the read
+        # paths never commit, but a uniform flag across the family keeps
+        # their detachment guarantees from diverging.
+        with Session(self._engine, expire_on_commit=False) as session:
+            yield session
+
+    def save(self, variant: VariantRecord) -> None:
+        # Plain INSERT, no merge: overwriting a stored variant would swap a
+        # learner's graded task underneath its trace and grade (audit
+        # corruption), so a duplicate identity is a race or bug to SURFACE,
+        # not paper over. The generator's cache path (get before generate)
+        # makes duplicate saves a programming error, not a normal flow.
+        # The trace store swallows its IntegrityError (dedup is the
+        # contract there); the grade store merges (latest-wins is the
+        # contract there); this store re-raises (first-wins is the
+        # contract here).
+        with self._session() as session:
+            try:
+                session.add(variant)
+                session.commit()
+            except sa.exc.IntegrityError:
+                session.rollback()
+                logger.debug(
+                    "variant insert rejected (identity already stored): "
+                    "learner=%s template=%s task=%s",
+                    variant.learner_id,
+                    variant.template_id,
+                    variant.task_id,
+                )
+                raise
+        logger.debug(
+            "variant saved: %s/%s task=%s seed=%s",
+            variant.learner_id,
+            variant.template_id,
+            variant.task_id,
+            variant.seed,
+        )
+
+    def get(self, learner_id: str, template_id: str) -> VariantRecord | None:
+        with self._session() as session:
+            record = session.get(VariantRecord, (learner_id, template_id))
+            if record is None:
+                return None
+            record.created_at = _as_utc(record.created_at)
+            # Detach from the session: callers must not depend on
+            # open-session ORM magic (lazy loads fail once it closes).
+            session.expunge(record)
+            return record
+
+    def get_by_task(self, task_id: str) -> VariantRecord | None:
+        with self._session() as session:
+            stmt = select(VariantRecord).where(VariantRecord.task_id == task_id)
+            record = session.exec(stmt).first()
+            if record is None:
+                return None
+            record.created_at = _as_utc(record.created_at)
+            session.expunge(record)
+            return record
+
+    def list_for_learner(self, learner_id: str) -> list[VariantRecord]:
+        with self._session() as session:
+            stmt = (
+                select(VariantRecord)
+                .where(VariantRecord.learner_id == learner_id)
+                # Chronological; task_id is a deterministic tie-break for
+                # variants stamped within the same instant.
+                # P5: col() — SQLModel class attrs are Mapped[T], the
+                # column reference rides col() in order_by.
+                .order_by(col(VariantRecord.created_at), VariantRecord.task_id)
+            )
+            results = session.exec(stmt).all()
+            for row in results:
+                row.created_at = _as_utc(row.created_at)
+                session.expunge(row)
+            return list(results)
+
+    def list_by_template(self, template_id: str) -> list[VariantRecord]:
+        with self._session() as session:
+            stmt = (
+                select(VariantRecord)
+                .where(VariantRecord.template_id == template_id)
+                # Chronological; learner_id is a deterministic tie-break.
+                .order_by(col(VariantRecord.created_at), VariantRecord.learner_id)
+            )
+            results = session.exec(stmt).all()
+            for row in results:
+                row.created_at = _as_utc(row.created_at)
+                session.expunge(row)
+            return list(results)
+
+    def close(self) -> None:
+        self._engine.dispose()

apps/ai-service/ai_service/variants/templates.py

@@ -0,0 +1,474 @@
+"""Task template library for seeded variant generation (D-029, REQ-3-005).
+
+A `TaskTemplate` binds a competency (D-021-aligned corpus ID), a statement
+skeleton with `{slot}` placeholders, typed `ParameterSlot`s, difficulty-
+normalization rubric anchors (the expected feature envelope that bounds
+variant fairness in the a-5 envelope test — grader-prompt shipment is the
+tracked P4 follow-up; grading is variant-blind today), and starter-file
+scaffolds served into the sandbox workdir (wired in P6).
+
+Slot sampling is PURE CODE: `random.Random(seed)` over typed slots — fully
+reproducible for a given seed, independent of the LLM. The LLM only renders
+the seeded slot values into the statement skeleton (D-020 defense).
+"""
+
+from __future__ import annotations
+
+import random
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+#: REQ-5-005 environment kinds (D-044): one namespace fabric, typed starter
+#: contents + command policy. 'build' = the v0.3 coding IDE; 'design' =
+#: artifact editing with a validator/renderer harness; 'simulation' = a
+#: parameterized run harness (benchmark scripts + datasets).
+EnvironmentKind = Literal["build", "design", "simulation"]
+
+
+def validate_simple_argv(value: str) -> str:
+    """G-15: command fields must roundtrip shlex.split → join → split.
+
+    No quotes, no shell metachars — the TS client splits on whitespace only
+    (no shlex in browsers), so anything quote-aware would split differently
+    on the two sides. A violation is a template-AUTHORING bug caught here,
+    at definition time, in Python where shlex exists.
+    """
+    import shlex
+
+    parts = shlex.split(value)
+    if not parts:
+        raise ValueError("command must not be empty")
+    joined = " ".join(parts)
+    if shlex.split(joined) != parts:
+        raise ValueError(f"command is not whitespace-joinable: {value!r}")
+    return joined
+
+SlotType = Literal["enum", "int_range", "string_set"]
+
+
+class ParameterSlot(BaseModel):
+    """One typed fill-in for a statement skeleton."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(min_length=1)
+    type: SlotType
+    values: list[str] = Field(default_factory=list)  # enum/string_set options
+    lo: int | None = None  # int_range bounds
+    hi: int | None = None
+
+    @field_validator("values")
+    @classmethod
+    def _values_nonempty_for_enums(cls, v: list[str], info) -> list[str]:
+        if info.data.get("type") in ("enum", "string_set") and not v:
+            raise ValueError(f"slot {info.data.get('name')!r} needs values")
+        return v
+
+    def sample(self, rng: random.Random) -> str | int:
+        """Deterministic sample from the seeded RNG. Validated after sampling."""
+        if self.type == "enum" or self.type == "string_set":
+            return rng.choice(self.values)
+        if self.type == "int_range":
+            lo = self.lo if self.lo is not None else 0
+            hi = self.hi if self.hi is not None else lo
+            if hi < lo:
+                raise ValueError(f"slot {self.name!r}: hi < lo")
+            return rng.randint(lo, hi)
+        raise ValueError(f"unsupported slot type: {self.type!r}")
+
+    def validate_value(self, value: str | int) -> bool:
+        """Is `value` schema-valid for this slot? (params JSON gate, a-5.)"""
+        if self.type in ("enum", "string_set"):
+            return isinstance(value, str) and value in self.values
+        if self.type == "int_range":
+            lo = self.lo if self.lo is not None else 0
+            hi = self.hi if self.hi is not None else lo
+            return isinstance(value, int) and lo <= value <= hi
+        return False
+
+
+class RubricAnchors(BaseModel):
+    """Difficulty-normalization anchors for the grader (a-5).
+
+    Expected FEATURE ENVELOPE (digest-space): the expected effort band
+    for this template, so two variants of one template are held to the
+    same bar regardless of which slot values a learner drew. The a-5
+    envelope test (tests/variants/test_generator.py) binds variants to
+    these bands in code, and — since Phase 4 (MH#4) — the grading engine
+    ships this envelope into the grader prompt
+    (grading/engine._anchors_context) and stamps the variant seed on the
+    GradeRecord, so the anchors gate variant fairness in BOTH tests and
+    the live rubric.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    expected_edit_count_band: tuple[int, int]
+    expected_min_test_runs: int
+    expected_error_fix_cycles_band: tuple[int, int]
+    notes: str = ""
+
+
+class TaskTemplate(BaseModel):
+    """A reusable task shape; variants instantiate it per learner."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    competency_id: str = Field(min_length=1)  # D-021 corpus alignment
+    title: str
+    statement_skeleton: str = Field(min_length=1)  # {slot} placeholders
+    slots: list[ParameterSlot] = Field(min_length=1)
+    rubric_anchors: RubricAnchors
+    starter_files: dict[str, str] = Field(default_factory=dict)  # path -> content
+    test_command: str
+    #: REQ-5-005 (D-044): the environment kind rides the variant through
+    #: the API to the TS client; 'build' default keeps v0.3 behavior.
+    environment: EnvironmentKind = "build"
+    #: The kind's Run harness (design: validator/renderer; simulation:
+    #: benchmark script). Defaults to the test_command for build kinds.
+    harness_command: str = ""
+
+    @field_validator("statement_skeleton")
+    @classmethod
+    def _skeleton_placeholders(cls, v: str) -> str:
+        if "{" not in v or "}" not in v:
+            raise ValueError("statement_skeleton needs at least one {slot}")
+        return v
+
+    @field_validator("test_command", "harness_command")
+    @classmethod
+    def _simple_argv(cls, v: str) -> str:
+        return validate_simple_argv(v) if v else v
+
+    @property
+    def run_command(self) -> str:
+        """The Run button's command: kind harness when declared, else tests."""
+        return self.harness_command or self.test_command
+
+    def render(self, params: dict[str, str | int]) -> str:
+        """Fill the skeleton with validated params."""
+        for slot in self.slots:
+            if slot.name not in params:
+                raise ValueError(f"missing param for slot {slot.name!r}")
+            if not slot.validate_value(params[slot.name]):
+                raise ValueError(f"invalid value for slot {slot.name!r}: {params[slot.name]!r}")
+        return self.statement_skeleton.format(**params)
+
+    def sample_params(self, seed: int) -> dict[str, str | int]:
+        """Seeded, reproducible, schema-valid slot values (pure code)."""
+        rng = random.Random(seed)
+        return {slot.name: slot.sample(rng) for slot in self.slots}
+
+
+# --- Template library (v0.3 initial set) --------------------------------------
+# Competency IDs are D-021-aligned with the Python corpus
+# (ai_service/corpus/learner_context.py) and the TS mock-data layer
+# (packages/mock-data/competency-stacks.ts: deterministic cid() scheme).
+
+TEMPLATES: dict[str, TaskTemplate] = {
+    "tpl-llm-judge": TaskTemplate(
+        id="tpl-llm-judge",
+        competency_id="stack-orchestration-c007",
+        title="Build an LLM-as-Judge Evaluator",
+        statement_skeleton=(
+            "Build a small LLM-as-judge evaluator for {domain} answers. "
+            "The judge must score each answer on {criterion} using a 0-4 scale, "
+            "return structured JSON, and handle at least {edge_cases} edge-case "
+            "answer classes (empty, off-topic, adversarial). Include a tiny "
+            "repro test set of at least {test_size} examples and print a summary "
+            "table of scores."
+        ),
+        slots=[
+            ParameterSlot(
+                name="domain",
+                type="enum",
+                values=["customer-support", "code-review", "summarization", "tutoring"],
+            ),
+            ParameterSlot(
+                name="criterion",
+                type="enum",
+                values=["factual-accuracy", "helpfulness", "safety", "completeness"],
+            ),
+            ParameterSlot(name="edge_cases", type="int_range", lo=2, hi=4),
+            ParameterSlot(name="test_size", type="int_range", lo=3, hi=8),
+        ],
+        rubric_anchors=RubricAnchors(
+            expected_edit_count_band=(3, 25),
+            expected_min_test_runs=2,
+            expected_error_fix_cycles_band=(0, 4),
+            notes="Slot draw changes the SCENARIO, not the engineering depth.",
+        ),
+        starter_files={
+            "README.md": (
+                "# LLM-as-Judge Evaluator\n\n"
+                "Implement `judge.py`:\n"
+                "- `score(answer: str) -> dict` — 0-4 on the named criterion\n"
+                "- structured JSON output (schema below)\n"
+                "- edge-case classes handled explicitly\n"
+                "- `pytest` must pass\n"
+            ),
+            "judge.py": "def score(answer: str) -> dict:\n    raise NotImplementedError\n",
+            "test_judge.py": "def test_placeholder():\n    assert True\n",
+        },
+        test_command="pytest -q",
+    ),
+    "tpl-guardrail-schema": TaskTemplate(
+        id="tpl-guardrail-schema",
+        competency_id="stack-orchestration-c008",
+        title="Schema Guardrail Pipeline",
+        statement_skeleton=(
+            "Implement an output-validation guardrail for a model returning "
+            "{entity} records. Validate against a typed schema with {field_count} "
+            "required fields, coerce or reject {failure_mode} failures, and emit "
+            "a fallback response for invalid payloads. Cover with at least "
+            "{test_size} unit tests including malformed JSON."
+        ),
+        slots=[
+            ParameterSlot(
+                name="entity",
+                type="enum",
+                values=["user-profile", "job-posting", "candidate", "invoice"],
+            ),
+            ParameterSlot(
+                name="failure_mode",
+                type="enum",
+                values=["strict-reject", "coerce-when-safe"],
+            ),
+            ParameterSlot(name="field_count", type="int_range", lo=4, hi=8),
+            ParameterSlot(name="test_size", type="int_range", lo=4, hi=10),
+        ],
+        rubric_anchors=RubricAnchors(
+            expected_edit_count_band=(3, 30),
+            expected_min_test_runs=2,
+            expected_error_fix_cycles_band=(0, 5),
+            notes="All slot draws land in the same engineering band.",
+        ),
+        starter_files={
+            "README.md": (
+                "# Schema Guardrail\n\nImplement `guardrail.py`:\n"
+                "- `validate(payload: dict) -> dict | Fallback`\n"
+                "- required-field checks, failure policy, fallback emission\n"
+            ),
+            "guardrail.py": "def validate(payload: dict):\n    raise NotImplementedError\n",
+            "test_guardrail.py": "def test_placeholder():\n    assert True\n",
+        },
+        test_command="pytest -q",
+    ),
+    "tpl-rag-chunker": TaskTemplate(
+        id="tpl-rag-chunker",
+        competency_id="stack-orchestration-c005",
+        title="RAG Chunking Strategy",
+        statement_skeleton=(
+            "Implement a document chunker for {doc_type} retrieval. Support "
+            "{strategy} chunking with a target size of ~{chunk_size} tokens, "
+            "preserve {invariant} across chunk boundaries, and evaluate overlap "
+            "quality with at least {test_size} fixture documents."
+        ),
+        slots=[
+            ParameterSlot(
+                name="doc_type",
+                type="enum",
+                values=["technical-docs", "legal-contracts", "transcripts"],
+            ),
+            ParameterSlot(
+                name="strategy",
+                type="enum",
+                values=["fixed-window", "semantic-boundary", "hybrid"],
+            ),
+            ParameterSlot(
+                name="invariant",
+                type="enum",
+                values=["code-block-integrity", "section-headers", "sentence-completeness"],
+            ),
+            ParameterSlot(name="chunk_size", type="int_range", lo=200, hi=800),
+            ParameterSlot(name="test_size", type="int_range", lo=3, hi=6),
+        ],
+        rubric_anchors=RubricAnchors(
+            expected_edit_count_band=(4, 35),
+            expected_min_test_runs=2,
+            expected_error_fix_cycles_band=(0, 6),
+            notes="Strategy draw changes implementation shape, not depth.",
+        ),
+        starter_files={
+            "README.md": (
+                "# RAG Chunker\n\nImplement `chunker.py`:\n"
+                "- `chunk(text: str) -> list[str]`\n- invariant preserved\n- tests green\n"
+            ),
+            "chunker.py": "def chunk(text: str) -> list[str]:\n    raise NotImplementedError\n",
+            "test_chunker.py": "def test_placeholder():\n    assert True\n",
+        },
+        test_command="pytest -q",
+    ),
+    # -- REQ-5-005 design environment (D-044): artifact editing with a
+    # -- validator/renderer harness - same fabric, typed starter contents.
+    "tpl-conversation-flow-design": TaskTemplate(
+        id="tpl-conversation-flow-design",
+        competency_id="stack-designer-c001",
+        title="Conversational Flow Artifact",
+        statement_skeleton=(
+            "Design a conversational flow for a {persona} assistant helping "
+            "users accomplish {goal}. Author the flow as a structured artifact "
+            "with at least {turn_count} conversation turns, explicit fallback "
+            "paths for misunderstandings, and an AI-transparency disclosure "
+            "pattern. The flow must render validly (the harness validates "
+            "structure) and read naturally end to end."
+        ),
+        slots=[
+            ParameterSlot(
+                name="persona",
+                type="enum",
+                values=["travel-planner", "homework-tutor", "fitness-coach", "recipe-guide"],
+            ),
+            ParameterSlot(
+                name="goal",
+                type="enum",
+                values=["book-a-trip", "master-a-concept", "start-a-routine", "cook-a-meal"],
+            ),
+            ParameterSlot(name="turn_count", type="int_range", lo=6, hi=12),
+        ],
+        rubric_anchors=RubricAnchors(
+            expected_edit_count_band=(3, 20),
+            expected_min_test_runs=1,
+            expected_error_fix_cycles_band=(0, 3),
+            notes="Design kind: artifact quality + iteration cadence, not code depth.",
+        ),
+        starter_files={
+            "README.md": (
+                "# Conversational Flow Design\n\n"
+                "Edit flow.md - the structured flow artifact. python3 "
+                "validate_flow.py checks structure (turn headings, fallback "
+                "sections, a transparency disclosure) and reports issues.\n"
+            ),
+            "flow.md": (
+                "# Flow: your persona here\n\n"
+                "## Turn 1\n- **AI:** (opening)\n- **User (expected):** ...\n\n"
+                "## Fallback\n- (misunderstanding handling)\n\n"
+                "## AI Transparency Disclosure\n- (disclosure pattern)\n"
+            ),
+            "validate_flow.py": (
+                "import re, sys\n"
+                "text = open('flow.md').read()\n"
+                "issues = []\n"
+                "turns = len(re.findall(r'^## Turn', text, re.M))\n"
+                "if turns < 3:\n"
+                "    issues.append(f'expected at least 3 turn sections, found {turns}')\n"
+                "if not re.search(r'^## Fallback', text, re.M):\n"
+                "    issues.append('missing Fallback section')\n"
+                "if not re.search(r'^## AI Transparency', text, re.M):\n"
+                "    issues.append('missing AI Transparency Disclosure')\n"
+                "print('VALID' if not issues else 'ISSUES: ' + '; '.join(issues))\n"
+                "sys.exit(0 if not issues else 1)\n"
+            ),
+        },
+        test_command="python3 validate_flow.py",
+        environment="design",
+        harness_command="python3 validate_flow.py",
+    ),
+    # -- REQ-5-005 simulation environment (D-044): parameterized benchmark
+    # -- harness with dataset generation.
+    "tpl-sensor-benchmark": TaskTemplate(
+        id="tpl-sensor-benchmark",
+        competency_id="stack-orchestration-c011",
+        title="Sensor Data Simulation Harness",
+        statement_skeleton=(
+            "Build a simulation harness for {sensor} readings over {duration_min} "
+            "minutes at {sample_hz} Hz. Generate a synthetic dataset with a "
+            "realistic noise profile, run the analysis pipeline, and print a "
+            "metrics summary (mean, p95, anomaly count at {anomaly_sigma} sigma). "
+            "The harness must be reproducible from the committed seed."
+        ),
+        slots=[
+            ParameterSlot(
+                name="sensor",
+                type="enum",
+                values=["temperature", "vibration", "luminosity", "pressure"],
+            ),
+            ParameterSlot(name="duration_min", type="int_range", lo=5, hi=60),
+            ParameterSlot(name="sample_hz", type="int_range", lo=1, hi=10),
+            ParameterSlot(name="anomaly_sigma", type="int_range", lo=2, hi=4),
+        ],
+        rubric_anchors=RubricAnchors(
+            expected_edit_count_band=(3, 25),
+            expected_min_test_runs=2,
+            expected_error_fix_cycles_band=(0, 3),
+            notes="Simulation kind: pipeline correctness + reproducibility.",
+        ),
+        starter_files={
+            "README.md": (
+                "# Sensor Simulation Harness\n\n"
+                "Edit simulate.py - python3 simulate.py runs the full pipeline: "
+                "generate, analyze, print metrics. pytest covers the analysis "
+                "functions.\n"
+            ),
+            "simulate.py": (
+                "import random, statistics\n\n"
+                "def generate(n=300, seed=42):\n"
+                "    rng = random.Random(seed)\n"
+                "    return [rng.gauss(20.0, 1.5) for _ in range(n)]\n\n"
+                "def analyze(samples, sigma=3):\n"
+                "    mean = statistics.fmean(samples)\n"
+                "    stdev = statistics.pstdev(samples)\n"
+                "    anomalies = [s for s in samples if abs(s - mean) > sigma * stdev]\n"
+                "    p95 = sorted(samples)[int(0.95 * len(samples))]\n"
+                "    return {'mean': mean, 'p95': p95, 'anomalies': len(anomalies)}\n\n"
+                "if __name__ == '__main__':\n"
+                "    print(analyze(generate()))\n"
+            ),
+            "test_simulate.py": (
+                "from simulate import generate, analyze\n\n"
+                "def test_reproducible():\n"
+                "    assert generate() == generate()\n\n"
+                "def test_metrics_shape():\n"
+                "    m = analyze(generate())\n"
+                "    assert set(m) == {'mean', 'p95', 'anomalies'}\n"
+            ),
+        },
+        test_command="pytest -q",
+        environment="simulation",
+        harness_command="python3 simulate.py",
+    ),
+}
+
+
+_KNOWN_COMPETENCY_IDS: set[str] = {
+    # D-021: mirrored from ai_service/corpus/learner_context.py — the Python
+    # source of truth for stack-orchestration competencies used by v0.2 agents.
+    "stack-orchestration-c001",
+    "stack-orchestration-c002",
+    "stack-orchestration-c003",
+    "stack-orchestration-c004",
+    "stack-orchestration-c005",
+    "stack-orchestration-c007",
+    "stack-orchestration-c008",
+    "stack-orchestration-c011",
+    "stack-designer-c001",
+    "stack-designer-c002",
+    "stack-safety-c021",
+}
+
+
+def get_template(template_id: str) -> TaskTemplate | None:
+    return TEMPLATES.get(template_id)
+
+
+def template_for_competency(competency_id: str) -> list[TaskTemplate]:
+    return [t for t in TEMPLATES.values() if t.competency_id == competency_id]
+
+
+def validate_competency_binding() -> None:
+    """All templates must bind to known D-021 corpus competency IDs."""
+    for t in TEMPLATES.values():
+        if t.competency_id not in _KNOWN_COMPETENCY_IDS:
+            raise ValueError(
+                f"template {t.id!r} binds unknown competency {t.competency_id!r}"
+            )
+
+
+def slots_pattern_ok(skeleton: str, slots: list[ParameterSlot]) -> bool:
+    """Every {placeholder} in the skeleton has a matching slot and vice versa."""
+    placeholders = set(re.findall(r"\{([a-z_][a-z0-9_]*)\}", skeleton))
+    slot_names = {s.name for s in slots}
+    return placeholders == slot_names

apps/ai-service/ai_service/voice/__init__.py

@@ -0,0 +1,35 @@
+"""VoiceProvider protocol (D-030, REQ-3-006) — mirrors the LLMProvider seam.
+
+Two implementations in v0.3:
+- MockVoiceProvider — deterministic canned transcripts + canned tone WAV
+  chunks + scripted failure modes (tests + no-key default; tests NEVER call
+  a real voice API).
+- browser descriptor — not a provider but a FALLBACK HINT: the web client
+  selects browser-native SpeechRecognition/speechSynthesis when the server
+  reports no real voice backend.
+
+OpenAIAudioProvider (real server STT/TTS over OpenAI-compatible
+/audio/transcriptions + /audio/speech) is INTENTIONALLY NOT BUILT in v0.3 —
+deferred to v0.4 with KYC, when there is a real key and real users
+(GRILL CUT-1 / G-7). This protocol is its future drop-in seam.
+
+Boundary: `voice/` never imports `agents/` or `api/`.
+"""
+
+from ai_service.voice.base import (
+    TranscriptSegment,
+    VoiceDescriptor,
+    VoiceProvider,
+)
+from ai_service.voice.browser import BROWSER_FALLBACK_DESCRIPTOR
+from ai_service.voice.factory import voice_provider_from_settings
+from ai_service.voice.mock import MockVoiceProvider
+
+__all__ = [
+    "BROWSER_FALLBACK_DESCRIPTOR",
+    "MockVoiceProvider",
+    "TranscriptSegment",
+    "VoiceDescriptor",
+    "VoiceProvider",
+    "voice_provider_from_settings",
+]

apps/ai-service/ai_service/voice/base.py

@@ -0,0 +1,62 @@
+"""VoiceProvider protocol + shared voice contracts (D-030, REQ-3-006).
+
+Mirrors the LLMProvider seam (D-014 pattern): a narrow protocol the Examiner
+agent and the defense API compose via DI, with a deterministic mock and a
+browser-fallback descriptor. No network in this module — concrete providers
+live in their own modules and are selected by factory/config.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+VoiceRole = Literal["examiner", "learner"]
+
+
+class TranscriptSegment(BaseModel):
+    """One STT result: the transcribed text + timing metadata."""
+
+    model_config = ConfigDict(frozen=True)
+
+    text: str = Field(min_length=1)
+    language: str = "en"
+    duration_ms: int | None = None
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+
+
+class VoiceDescriptor(BaseModel):
+    """Capability descriptor served to the web client (D-030).
+
+    The assessment UI reads this to decide HOW the learner speaks/hears:
+    - `mode="server"`    → server-side STT/TTS (openai-audio, live since v0.5)
+    - `mode="browser"`   → browser-native SpeechRecognition/speechSynthesis
+    - `mode="mock"`      → deterministic no-op path (tests / no-key dev)
+    The descriptor never contains secrets — only capability hints.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    mode: Literal["server", "browser", "mock"]
+    sr_available: bool
+    tts_available: bool
+    hint: str = ""
+
+
+@runtime_checkable
+class VoiceProvider(Protocol):
+    """The voice port (D-030): STT in, TTS out. Never imports agents/api."""
+
+    async def transcribe(self, audio: bytes, fmt: str) -> TranscriptSegment:
+        """STT: audio bytes (fmt: 'wav' | 'webm' | 'mp3') → transcript."""
+        ...
+
+    def synthesize(self, text: str, voice: str = "default") -> AsyncIterator[bytes]:
+        """TTS: text -> async byte chunks (audio stream).
+
+        Implementations may be async generators (async-def + yield) — the
+        consumer contract is `async for chunk in provider.synthesize(text)`.
+        """
+        ...

apps/ai-service/ai_service/voice/browser.py

@@ -0,0 +1,33 @@
+"""Browser-native fallback descriptor (D-030, CUT-1 / G-7, REQ-3-006).
+
+Browser-native SR/TTS is the no-key CLIENT-side path. When the factory
+selects `browser` mode, the defense endpoints return this descriptor and the
+WEB CLIENT performs SpeechRecognition + speechSynthesis natively; the server
+persists text turns as usual. Real server STT/TTS (openai-audio) is live
+since v0.5 — this descriptor is the no-key fallback.
+"""
+
+from __future__ import annotations
+
+from .base import VoiceDescriptor
+
+BROWSER_FALLBACK_DESCRIPTOR = VoiceDescriptor(
+    mode="browser",
+    sr_available=True,
+    tts_available=True,
+    hint=(
+        "No server voice backend configured. Use browser-native "
+        "SpeechRecognition for STT and speechSynthesis for TTS; send the "
+        "transcribed text to POST /v1/defense/{id}/answer ({text} form)."
+    ),
+)
+
+MOCK_DESCRIPTOR = VoiceDescriptor(
+    mode="mock",
+    sr_available=True,
+    tts_available=True,
+    hint=(
+        "Deterministic mock voice (tests / no-key dev). Real server "
+        "STT/TTS is live since v0.5 (AI_VOICE_PROVIDER=openai-audio)."
+    ),
+)

apps/ai-service/ai_service/voice/defense_store.py

@@ -0,0 +1,510 @@
+"""DefenseStore — oral-defense persistence: protocol + SQLite impl (REQ-3-006, D-027).
+
+FOURTH protocol-wrapped store of the D-027 family and the first spanning
+TWO related tables: `defense_record` (the defense session + integrity
+signals) and `defense_turn` (the ordered examiner/learner transcript,
+FK → defense_record.id).
+
+Postgres-migration-ready (D-027): the protocol is the only surface the
+Examiner pipeline (task 5-2-01) and the defense endpoints (task 5-3-01)
+touch; swapping SQLiteDefenseStore for a Postgres implementation must
+not change call sites. Both tables use only portable column types
+(str / int / datetime / JSON), so the same SQLModel schema stands up
+unchanged on Postgres.
+
+Save semantics — where this sits among the D-027 stores (each has a
+deliberately different contract):
+    TraceStore.append   dedup-keep-first; IntegrityError SWALLOWED
+                        (at-least-once event ingest).
+    GradeStore.save     upsert-latest-wins (a regrade is latest-state).
+    VariantStore.save   insert-only first-wins; IntegrityError RAISED
+                        (reproducibility; a duplicate is a bug).
+    DefenseStore         a LIFECYCLE store:
+      start()           insert-only; a duplicate id raises
+                        (a defense id is minted once per session).
+      append_turn()      insert-only per (defense_id, seq); a duplicate
+                        seq raises AND an unknown defense_id raises (FK
+                        enforced) — a transcript turn must never silently
+                        vanish (it is the integrity/grading input) nor
+                        attach to a defense that does not exist.
+      finalize()         targeted UPDATE (status → finished; finished_at +
+                        integrity_signals JSON). Unknown id → None
+                        (documented below). Re-finalize overwrites
+                        signals + finished_at — latest-wins, mirroring
+                        GradeStore.save: a recomputed verdict replaces
+                        the previous one wholesale.
+
+append_turn does NOT police status (turns after finalize are a
+sequencing bug for the endpoints to prevent, task 5-3-01): the store
+enforces DATA integrity (FK + PK + non-empty), not workflow.
+
+integrity_signals (A-109): JSON dict on the record — long pauses,
+off-scope cadence markers and friends, computed by the Examiner over
+turn metadata and persisted by finalize for the Proctor/Mentor feed.
+An empty dict is legal (defense not finished, or a clean defense).
+
+Concurrency (a-3): WAL + synchronous=NORMAL + busy timeout at
+connection time (mirrors the other D-027 stores), PLUS foreign_keys=ON
+— this is the family's first real foreign key and it is actually
+enforced on SQLite, matching Postgres's native behavior (D-027 parity).
+
+`created_at` / `ts` contract: callers stamp UTC (datetime.now(UTC));
+SQLite stores them naive and read paths re-label tz-aware UTC (same
+boundary normalization as TelemetryEvent.ts / GradeRecord.created_at,
+so the contract holds on any backend).
+
+Boundary (D-027): `voice/` never imports `agents/` / `api/`; this
+module imports config only.
+"""
+
+import logging
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal, Protocol, get_args
+
+import sqlalchemy as sa
+from sqlalchemy import JSON, Index, String
+from sqlalchemy.orm import validates
+from sqlmodel import Field, Session, SQLModel, col, create_engine, select
+
+from ..config import Settings
+
+logger = logging.getLogger(__name__)
+
+DefenseStatus = Literal["in_progress", "finished"]
+# P5: get_args() is the typed accessor for Literal values (bare __args__
+# trips mypy on the typing special form).
+_DEFENSE_STATUSES: frozenset[str] = frozenset(get_args(DefenseStatus))
+
+TurnRole = Literal["examiner", "learner"]
+_TURN_ROLES: frozenset[str] = frozenset(get_args(TurnRole))
+
+
+class DefenseRecord(SQLModel, table=True):
+    """A persisted oral-defense session; id is the PK.
+
+    Written by the defense endpoints (task 5-3-01) through the
+    DefenseStore protocol; read back by the endpoints, the Examiner
+    pipeline and the Proctor/Mentor feeds. Constraint enforcement
+    mirrors TelemetryEvent / GradeRecord / VariantRecord: sqlmodel
+    0.0.42's metaclass drops pydantic constraints on table models, so
+    SQLAlchemy `@validates` hooks enforce instead and the column types
+    stay Postgres-ready (D-027).
+
+    Field contract:
+        id                — non-empty defense identifier, minted once
+                            per session (a duplicate start raises).
+        learner_id        — non-empty learner identifier (same id space
+                            as traces, grades and variants).
+        task_id           — non-empty task identifier; the defense
+                            defends the submitted work for this trace
+                            key ((learner_id, task_id) joins to the
+                            trace/grade/variant the defense is about).
+        status            — in_progress | finished; the STORE owns the
+                            transition: start() forces in_progress,
+                            finalize() sets finished. Validated.
+        integrity_signals — A-109 signal dict (long pauses, off-scope
+                            cadence markers, ...); {} until finalize;
+                            JSON column. An empty dict is legal.
+        created_at        — UTC start timestamp.
+        finished_at       — UTC finalize timestamp; None while in
+                            progress.
+
+    `turns` (property): the seq-ordered DefenseTurn transcript, attached
+    ONLY by DefenseStore.get(); records from list_for_learner carry
+    turns == [] — call get() for a full transcript.
+    """
+
+    __tablename__ = "defense_record"
+    # The id PK covers point lookups; this secondary index covers
+    # list_for_learner ordered by created_at without a sort step
+    # (Postgres migration target D-027).
+    __table_args__ = (
+        Index("ix_defense_record_learner_created", "learner_id", "created_at"),
+    )
+
+    id: str = Field(primary_key=True)
+    learner_id: str
+    task_id: str
+    # Bare Literal annotations crash sqlmodel<=0.0.42's column inference
+    # (issubclass(TypeAlias, Enum)); an explicit sa_type + the validates
+    # hook below give the same contract: VARCHAR column, Literal-rejected
+    # values (same pattern as TelemetryEvent.kind).
+    status: DefenseStatus = Field(default="in_progress", sa_type=String)
+    # JSON column: stored as TEXT on SQLite, native JSONB on Postgres (D-027).
+    integrity_signals: dict[str, Any] = Field(default_factory=dict, sa_type=JSON)
+    created_at: datetime
+    finished_at: datetime | None = Field(default=None)
+
+    @property
+    def turns(self) -> list["DefenseTurn"]:
+        """Seq-ordered transcript; [] unless attached by get().
+
+        Table models reject ad-hoc attributes (pydantic __setattr__
+        raises on non-fields), so the store stashes the detached turn
+        list via object.__setattr__ and this read-only property surfaces
+        it. The returned list is a copy — caller mutations cannot
+        corrupt the stash.
+        """
+        return list(self.__dict__.get("_turns", []))
+
+    @validates("id", "learner_id", "task_id")
+    def _ids_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty identifier")
+        return value
+
+    @validates("status")
+    def _status_is_known(self, key: str, value: str) -> str:
+        if value not in _DEFENSE_STATUSES:
+            raise ValueError(f"unknown defense status: {value!r}")
+        return value
+
+
+class DefenseTurn(SQLModel, table=True):
+    """One examiner/learner dialogue turn; (defense_id, seq) is the PK.
+
+    Rows are append-only transcript entries written through
+    DefenseStore.append_turn. seq numbers the dialogue within one
+    defense starting at 0; monotonic assignment is the endpoints' job
+    (task 5-3-01), this model only rejects negatives — the same split
+    as TelemetryEvent.seq (model rejects < 0, store owns ordering).
+
+    Field contract:
+        defense_id  — non-empty; FK → defense_record.id. ENFORCED on
+                      SQLite via foreign_keys=ON (first real FK in the
+                      D-027 family; Postgres enforces FKs natively, so
+                      this keeps the backends equivalent, D-027).
+        seq         — turn index within the defense, >= 0. (defense_id,
+                      seq) is the PK: a duplicate raises instead of
+                      silently overwriting — the transcript is the
+                      integrity/grading input, a vanishing turn is
+                      audit corruption.
+        role        — examiner | learner (who spoke). Validated.
+        text        — non-empty utterance text (examiner question, or
+                      STT output for learner answers).
+        ts          — UTC utterance timestamp.
+        latency_ms  — per-turn pipeline latency in ms (STT + LLM TTFT +
+                      TTS, A-109); int or None. Populated by the
+                      endpoints (task 5-4-01); None allowed here — the
+                      store persists, it does not measure.
+        created_at  — UTC row-write timestamp.
+    """
+
+    __tablename__ = "defense_turn"
+    # The composite PK (defense_id, seq) doubles as the covering index
+    # for the per-defense seq-ordered read in get() — no secondary index
+    # needed (contrast defense_record's learner-listing index).
+
+    defense_id: str = Field(foreign_key="defense_record.id", primary_key=True)
+    seq: int = Field(primary_key=True)
+    role: TurnRole = Field(sa_type=String)
+    text: str
+    ts: datetime
+    latency_ms: int | None = Field(default=None)
+    created_at: datetime
+
+    @validates("defense_id")
+    def _defense_id_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty identifier")
+        return value
+
+    @validates("seq")
+    def _seq_non_negative(self, key: str, value: int) -> int:
+        if value < 0:
+            raise ValueError("seq must be >= 0 (ordering is the endpoints' job)")
+        return value
+
+    @validates("role")
+    def _role_is_known(self, key: str, value: str) -> str:
+        if value not in _TURN_ROLES:
+            raise ValueError(f"unknown turn role: {value!r}")
+        return value
+
+    @validates("text")
+    def _text_non_empty(self, key: str, value: str) -> str:
+        if not value:
+            raise ValueError(f"{key} must be a non-empty utterance string")
+        return value
+
+    @validates("latency_ms")
+    def _latency_non_negative(self, key: str, value: int | None) -> int | None:
+        # None is legal (not yet instrumented); a NEGATIVE latency is
+        # nonsense and surfaces as a construction error.
+        if value is not None and value < 0:
+            raise ValueError("latency_ms must be >= 0 or None")
+        return value
+
+
+class DefenseStore(Protocol):
+    """Persistence contract for oral-defense sessions + transcripts.
+
+    Implemented by SQLiteDefenseStore (v0.3, D-027); a Postgres
+    implementation must satisfy the same surface.
+    """
+
+    def start(self, defense: DefenseRecord) -> DefenseRecord:
+        """Insert a new defense. INSERT-ONLY: a duplicate id raises
+        sqlalchemy.exc.IntegrityError (a defense id is minted once per
+        session — surfacing, not swallowing, mirrors VariantStore).
+        The store owns the lifecycle: status is forced to "in_progress"
+        and finished_at to None, whatever the caller passed — only
+        finalize() may move a defense to finished. Returns the stored
+        record, detached from any DB session.
+        """
+        ...
+
+    def append_turn(self, defense_id: str, turn: DefenseTurn) -> DefenseTurn:
+        """Insert one transcript turn, ordered by (defense_id, seq).
+        turn.defense_id MUST equal the defense_id argument — a mismatch
+        raises ValueError (the defense identity must never be
+        ambiguous). A duplicate (defense_id, seq) raises
+        IntegrityError; an unknown defense_id raises IntegrityError
+        (FK enforced). Does NOT police status — sequencing turns vs
+        finalize is the endpoints' job (task 5-3-01). Returns the
+        stored turn, detached.
+        """
+        ...
+
+    def finalize(
+        self, defense_id: str, integrity_signals: dict[str, Any]
+    ) -> DefenseRecord | None:
+        """Seal the defense: status → "finished", finished_at = now(UTC),
+        integrity_signals stored as JSON. UNKNOWN defense_id → None
+        (documented choice: the API layer maps it to 404 without an
+        exception dance; contrast start/append_turn where IntegrityError
+        IS the contract — those are inserts, this is an update on a key
+        the caller may legitimately not hold). Re-finalize overwrites
+        signals + finished_at: latest-wins, mirroring GradeStore.save
+        (a recomputed verdict replaces the previous one wholesale).
+        Returns the updated record, detached, WITHOUT turns — get() is
+        the with-turns path.
+        """
+        ...
+
+    def get(self, defense_id: str) -> DefenseRecord | None:
+        """The defense with its FULL transcript (turns in seq order,
+        detached) and integrity signals; None when it does not exist.
+        Safe to pass across layers — no open-session ORM magic.
+        """
+        ...
+
+    def list_for_learner(self, learner_id: str) -> list[DefenseRecord]:
+        """All stored defenses for the learner, ordered by created_at
+        ascending (chronological; id breaks same-instant ties), WITHOUT
+        turns — records carry turns == []; call get() for a transcript.
+        Empty list when the learner has none.
+        """
+        ...
+
+    def close(self) -> None:
+        """Release DB connections. Store must not be used after close."""
+        ...
+
+
+def _sqlite_connect(dbapi_connection: sqlite3.Connection, _: object) -> None:
+    """Per-connection pragma setup (a-3). Mirrors the other D-027 stores.
+
+    journal_mode=WAL  — readers never block the single writer.
+    synchronous=NORMAL — safe in WAL mode, avoids full fsync-per-commit.
+    busy_timeout=5000  — retry briefly under contention instead of
+                         `OperationalError: database is locked`.
+    foreign_keys=ON    — NEW vs the family: defense_turn is the first
+                         real FK among the D-027 stores; SQLite leaves
+                         FKs OFF by default while Postgres enforces them
+                         natively, so the pragma keeps the backends
+                         equivalent (D-027 parity).
+    """
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.execute("PRAGMA foreign_keys=ON")
+    cursor.close()
+
+
+def _as_utc(ts: datetime) -> datetime:
+    """Timestamps travel as naive datetime on SQLite, tz-aware elsewhere.
+
+    SQLite (via SQLModel) drops tzinfo; Postgres TIMESTAMP WITH TIME ZONE
+    keeps it. Normalizing on the read path makes the store's contract
+    tz-aware UTC regardless of the backend (D-027).
+    """
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=UTC)  # naive UTC read-side: label as UTC
+    return ts.astimezone(UTC)
+
+
+class SQLiteDefenseStore:
+    """SQLite-backed DefenseStore (SQLModel). Fourth protocol-wrapped
+    store of the D-027 family (first: SQLiteTraceStore, second:
+    SQLiteGradeStore, third: SQLiteVariantStore) and the first spanning
+    two related tables.
+    """
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path: Path = db_path if db_path is not None else Settings().db_path
+        self._engine = create_engine(f"sqlite:///{self._db_path}")
+        sa.event.listen(self._engine, "connect", _sqlite_connect)
+        SQLModel.metadata.create_all(self._engine)
+
+    @contextmanager
+    def _session(self) -> Iterator[Session]:
+        # expire_on_commit=False: identical session behavior to the other
+        # D-027 stores. start/append_turn return the caller's instance
+        # after commit and get/finalize return rows expunged mid-session;
+        # a uniform flag across the family keeps their detachment
+        # guarantees from diverging.
+        with Session(self._engine, expire_on_commit=False) as session:
+            yield session
+
+    def start(self, defense: DefenseRecord) -> DefenseRecord:
+        # The store owns the lifecycle: a defense is BORN in_progress and
+        # only finalize() may move it to finished. A smuggled "finished"
+        # status is normalized away, not rejected — the insert itself
+        # stays insert-only, and a duplicate id raises to the caller
+        # (mirroring VariantStore: the id is minted once per session).
+        defense.status = "in_progress"
+        defense.finished_at = None
+        with self._session() as session:
+            try:
+                session.add(defense)
+                session.commit()
+            except sa.exc.IntegrityError:
+                session.rollback()
+                logger.debug("defense start rejected (id already stored): %s", defense.id)
+                raise
+        logger.debug(
+            "defense started: %s learner=%s task=%s",
+            defense.id,
+            defense.learner_id,
+            defense.task_id,
+        )
+        return defense
+
+    def append_turn(self, defense_id: str, turn: DefenseTurn) -> DefenseTurn:
+        # The explicit defense_id argument is the defense identity for
+        # this write; a turn object claiming another defense is a
+        # programming error — surface it before touching the DB.
+        if turn.defense_id != defense_id:
+            raise ValueError(
+                f"turn.defense_id {turn.defense_id!r} does not match the "
+                f"defense_id argument {defense_id!r}"
+            )
+        with self._session() as session:
+            try:
+                session.add(turn)
+                session.commit()
+            except sa.exc.IntegrityError:
+                # Two possible causes, both surfaced, neither swallowed:
+                # duplicate (defense_id, seq) PK — a transcript turn must
+                # never silently vanish; unknown defense_id — the FK
+                # (foreign_keys=ON) rejects the orphan.
+                session.rollback()
+                logger.debug(
+                    "defense turn rejected (duplicate (defense_id, seq) "
+                    "or unknown defense_id): defense=%s seq=%s",
+                    defense_id,
+                    turn.seq,
+                )
+                raise
+        logger.debug(
+            "defense turn appended: %s seq=%d role=%s",
+            defense_id,
+            turn.seq,
+            turn.role,
+        )
+        return turn
+
+    def finalize(
+        self, defense_id: str, integrity_signals: dict[str, Any]
+    ) -> DefenseRecord | None:
+        # A None signals blob would break the read contract (signals are
+        # a dict, {} until finalize); reject before writing.
+        if not isinstance(integrity_signals, dict):
+            raise ValueError(
+                "integrity_signals must be a JSON-object dict, got "
+                f"{type(integrity_signals).__name__}"
+            )
+        with self._session() as session:
+            record = session.get(DefenseRecord, defense_id)
+            if record is None:
+                # Documented unknown-id behavior: None, not a raise — the
+                # defense endpoints map this to 404. Contrast start() /
+                # append_turn(), where IntegrityError IS the contract.
+                return None
+            # Latest-wins re-finalize, mirroring GradeStore.save: a
+            # recomputed verdict (fresh signals) replaces the stored one
+            # wholesale; status just stays finished.
+            record.status = "finished"
+            record.finished_at = datetime.now(UTC)
+            record.integrity_signals = integrity_signals
+            session.commit()
+            record.created_at = _as_utc(record.created_at)
+            if record.finished_at is not None:
+                record.finished_at = _as_utc(record.finished_at)
+            # Detach from the session: callers must not depend on
+            # open-session ORM magic (lazy loads fail once it closes).
+            session.expunge(record)
+        logger.debug(
+            "defense finalized: %s signals=%s", defense_id, sorted(integrity_signals)
+        )
+        return record
+
+    def get(self, defense_id: str) -> DefenseRecord | None:
+        with self._session() as session:
+            record = session.get(DefenseRecord, defense_id)
+            if record is None:
+                return None
+            record.created_at = _as_utc(record.created_at)
+            if record.finished_at is not None:
+                record.finished_at = _as_utc(record.finished_at)
+            stmt = (
+                select(DefenseTurn)
+                .where(DefenseTurn.defense_id == defense_id)
+                # P5: col() — SQLModel class attrs are Mapped[T], the
+                # column reference rides col() in order_by.
+                .order_by(col(DefenseTurn.seq))
+            )
+            turns = session.exec(stmt).all()
+            for turn in turns:
+                turn.ts = _as_utc(turn.ts)
+                turn.created_at = _as_utc(turn.created_at)
+                # Detach each turn: the transcript must be usable once
+                # the session closes (no lazy-load magic).
+                session.expunge(turn)
+            session.expunge(record)
+            # Table models reject ad-hoc attributes (pydantic __setattr__
+            # raises on non-fields), so the seq-ordered transcript is
+            # stashed via object.__setattr__ and surfaced through the
+            # read-only `turns` property. Rows are detached either way —
+            # safe to pass across layers.
+            object.__setattr__(record, "_turns", list(turns))
+            return record
+
+    def list_for_learner(self, learner_id: str) -> list[DefenseRecord]:
+        with self._session() as session:
+            stmt = (
+                select(DefenseRecord)
+                .where(DefenseRecord.learner_id == learner_id)
+                # Chronological; id is a deterministic tie-break for
+                # defenses stamped within the same instant.
+                .order_by(col(DefenseRecord.created_at), DefenseRecord.id)
+            )
+            results = session.exec(stmt).all()
+            for row in results:
+                row.created_at = _as_utc(row.created_at)
+                if row.finished_at is not None:
+                    row.finished_at = _as_utc(row.finished_at)
+                # Turns are deliberately NOT loaded here: the list feed
+                # (Proctor/Mentor) needs session headers, not full
+                # transcripts — get() is the with-turns path.
+                session.expunge(row)
+            return list(results)
+
+    def close(self) -> None:
+        self._engine.dispose()

apps/ai-service/ai_service/voice/factory.py

@@ -0,0 +1,72 @@
+"""Voice provider factory (D-030; REQ-5-001 real path, D-040).
+
+`AI_VOICE_PROVIDER = mock | browser | openai-audio` (default: mock — the
+no-key path is first-class). `openai-audio` requires voice_base_url +
+voice_api_key: the factory raises `UnknownVoiceProviderError` with an
+actionable message for direct callers (tests), while the lifespan in
+main.py CATCHES it and falls back to mock with a loud log — a typo'd env
+must never crash the unattended boot (G-11), and the mock provider's
+descriptor then honestly reports mode='mock' so the UI badge cannot lie.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import httpx
+
+from ..config import Settings
+from .base import VoiceProvider
+from .mock import MockVoiceProvider
+from .openai_audio import OpenAIAudioProvider, TtsFormat
+
+
+class UnknownVoiceProviderError(ValueError):
+    """Raised for a provider name outside the contract, or a real provider
+    selected without its required configuration."""
+
+
+def voice_provider_from_settings(
+    settings: Settings, http_client: httpx.AsyncClient | None = None
+) -> VoiceProvider:
+    """Select the voice provider by settings (env `AI_VOICE_PROVIDER`).
+
+    `http_client` is required for the `openai-audio` branch (D-017 shared
+    pool); mock/browser ignore it.
+    """
+    name = (settings.voice_provider or "mock").strip().lower()
+    if name == "mock":
+        return MockVoiceProvider()
+    if name == "browser":
+        # Browser mode is a CLIENT-side capability: the server composes the
+        # same MockVoiceProvider (typed fallback answers still work; the UI
+        # uses the descriptor for mic/speech). See browser.py.
+        return MockVoiceProvider()
+    if name in ("openai-audio", "openai", "server"):
+        if not settings.voice_base_url or not settings.voice_api_key:
+            raise UnknownVoiceProviderError(
+                "AI_VOICE_PROVIDER=openai-audio requires AI_VOICE_BASE_URL "
+                "and AI_VOICE_API_KEY — set both, or use 'mock'/'browser'. "
+                "(main.py falls back to mock when these are missing; the "
+                "voice badge then honestly reports mock — G-11)"
+            )
+        if http_client is None:
+            raise UnknownVoiceProviderError(
+                "openai-audio requires the shared httpx client "
+                "(voice_provider_from_settings(settings, http_client))"
+            )
+        return OpenAIAudioProvider(
+            http_client=http_client,
+            base_url=settings.voice_base_url,
+            api_key=settings.voice_api_key,
+            stt_model=settings.voice_stt_model,
+            tts_model=settings.voice_tts_model,
+            tts_voice=settings.voice_tts_voice,
+            # P5: Settings.voice_tts_format is str, but its pydantic
+            # validator normalizes to exactly mp3|wav|opus (invalid → mp3
+            # with a warning) — the cast states that provenance.
+            tts_format=cast(TtsFormat, settings.voice_tts_format),
+        )
+    raise UnknownVoiceProviderError(
+        f"unknown AI_VOICE_PROVIDER {name!r}: use 'mock', 'browser', or 'openai-audio'"
+    )

apps/ai-service/ai_service/voice/mock.py

@@ -0,0 +1,95 @@
+"""Deterministic MockVoiceProvider (D-030, REQ-3-006).
+
+Canned transcripts (scripted per test via queue) + canned 1kHz-tone WAV bytes
++ scripted failure modes. Two identical transcribe calls yield identical
+segments; tests NEVER touch a real voice API (conftest cloud-free rule).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import math
+import struct
+import wave
+from collections.abc import AsyncIterator
+
+from .base import TranscriptSegment, VoiceProvider
+
+
+def _tone_wav(duration_ms: int = 250, freq_hz: float = 1000.0) -> bytes:
+    """A small, deterministic 16-bit mono WAV: a sine tone (stdlib only)."""
+    rate = 8000
+    n_samples = max(1, int(rate * duration_ms / 1000))
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        for i in range(n_samples):
+            sample = int(12000 * math.sin(2 * math.pi * freq_hz * i / rate))
+            w.writeframes(struct.pack("<h", sample))
+    return buf.getvalue()
+
+
+class MockVoiceFailure(RuntimeError):
+    """Scripted failure mode for tests."""
+
+
+class MockVoiceProvider:
+    """Deterministic voice provider: scripted STT, canned-tone TTS.
+
+    - `transcribe`: pops the next scripted transcript from a queue (or a
+      default); two identical calls with the same queue state are identical.
+      Failure mode: raise MockVoiceFailure when the queue holds a failure
+      marker (the string "FAIL") or `audio` is empty.
+    - `synthesize`: yields the canned tone WAV in fixed-size chunks; failure
+      mode: empty text raises MockVoiceFailure.
+    """
+
+    def __init__(self, transcripts: list[str] | None = None) -> None:
+        self._transcripts = list(transcripts or [])
+        self._cursor = 0
+        self.transcribe_calls = 0
+        self.synthesize_calls = 0
+
+    def script(self, transcripts: list[str]) -> None:
+        """Replace the scripted queue (tests set expectations up front)."""
+        self._transcripts = list(transcripts)
+        self._cursor = 0
+
+    async def transcribe(self, audio: bytes, fmt: str) -> TranscriptSegment:
+        self.transcribe_calls += 1
+        if not audio:
+            raise MockVoiceFailure("no audio bytes provided")
+        if not self._transcripts:
+            raise MockVoiceFailure("transcript queue exhausted — script it")
+        item = self._transcripts[self._cursor]
+        self._cursor = (self._cursor + 1) % len(self._transcripts)
+        if item == "FAIL":
+            raise MockVoiceFailure("scripted STT failure")
+        return TranscriptSegment(
+            text=item,
+            duration_ms=max(1, len(audio) // 32),  # deterministic pseudo-duration
+        )
+
+    async def synthesize(self, text: str, voice: str = "default") -> AsyncIterator[bytes]:
+        # NOTE: protocol parity matters more than the async-generator purity
+        # lint; the real provider (openai_audio.py) streams over HTTP.
+        self.synthesize_calls += 1
+        if not text:
+            raise MockVoiceFailure("cannot synthesize empty text")
+        wav = _tone_wav(duration_ms=min(2000, max(120, len(text) * 12)))
+        for i in range(0, len(wav), 1024):
+            yield wav[i : i + 1024]
+            await asyncio.sleep(0)  # yield to the loop like a network stream
+
+
+# Protocol-shape parity guard (mock must satisfy the D-030 port).
+
+
+def _assert_protocol() -> None:
+    assert isinstance(MockVoiceProvider(), VoiceProvider)
+
+
+_assert_protocol()

apps/ai-service/ai_service/voice/openai_audio.py

@@ -0,0 +1,137 @@
+"""OpenAI-compatible audio provider — real server STT/TTS (D-040, REQ-5-001).
+
+One implementation serves any OpenAI-compatible audio endpoint (base_url is
+config; A-301 endpoint-agnostic by config, D-014 pattern). Raw httpx on the
+shared lifespan client (D-017; read=300s tolerates multi-minute clips).
+
+Boundary rules (mirror llm/openai_compat.py):
+- voice/ imports nothing from agents/ or api/
+- api_key NEVER appears in exceptions, logs, or error messages
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Literal
+
+import httpx
+
+from .base import TranscriptSegment, VoiceDescriptor
+
+#: TTS response formats the OpenAI audio endpoint accepts (P5: named so
+#: the factory can type-honestly pass the config-normalized value through).
+TtsFormat = Literal["mp3", "wav", "opus"]
+
+
+class OpenAIAudioProvider:
+    """Server STT (`/audio/transcriptions`) + TTS (`/audio/speech`)."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient,
+        base_url: str,
+        api_key: str,
+        stt_model: str = "whisper-1",
+        tts_model: str = "tts-1",
+        tts_voice: str = "alloy",
+        tts_format: TtsFormat = "mp3",
+    ) -> None:
+        self._client = http_client
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._stt_model = stt_model
+        self._tts_model = tts_model
+        self._tts_voice = tts_voice
+        self._tts_format = tts_format
+        # a-15: the descriptor is what defense.py prefers; a missing one
+        # would badge the real server path as "mock".
+        self.descriptor = VoiceDescriptor(
+            mode="server",
+            sr_available=True,
+            tts_available=True,
+            hint="server STT/TTS via AI_VOICE_BASE_URL",
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    def _sanitize(self, exc: Exception) -> RuntimeError:
+        text = str(exc)
+        if self._api_key and self._api_key in text:
+            text = text.replace(self._api_key, "[REDACTED]")
+        return RuntimeError(f"voice provider error: {text}")
+
+    async def transcribe(self, audio: bytes, fmt: str) -> TranscriptSegment:
+        """STT: multipart upload (`file` + `model`) → TranscriptSegment.
+
+        `fmt` is a bare extension ('wav' | 'webm' | 'mp3') — the defense
+        route strips codec params before this call (D-041).
+        """
+        files = {"file": (f"answer.{fmt}", audio, f"audio/{fmt}")}
+        data = {"model": self._stt_model, "response_format": "json"}
+        try:
+            resp = await self._client.post(
+                f"{self._base_url}/audio/transcriptions",
+                files=files,
+                data=data,
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            body = resp.json()
+        except httpx.HTTPError as exc:
+            raise self._sanitize(exc) from exc
+        if not isinstance(body, dict):
+            # P2 (verifier): a non-dict 200 body is a contract break —
+            # context-wrap instead of a raw AttributeError.
+            raise RuntimeError(
+                "voice provider error: unexpected transcription response shape"
+            )
+        text = str(body.get("text", "")).strip()
+        if not text:
+            # 200 with an empty transcript is a provider contract break —
+            # TranscriptSegment(min_length=1) would raise a bare pydantic
+            # error; wrap it with provider context instead.
+            raise RuntimeError("voice provider error: empty transcription")
+        return TranscriptSegment(text=text)
+
+    def synthesize(
+        self, text: str, voice: str = "default"
+    ) -> AsyncIterator[bytes]:
+        """TTS: JSON body → raw audio byte stream.
+
+        OpenAI's TTS caps `input` at 4096 chars; examiner questions are
+        short, but enforce the guard so a long question fails loudly at the
+        seam instead of as an opaque provider 400.
+        """
+        return self._synthesize_stream(text, voice)
+
+    async def _synthesize_stream(
+        self, text: str, voice: str
+    ) -> AsyncIterator[bytes]:
+        if len(text) > 4096:
+            raise RuntimeError(
+                f"voice provider error: TTS input exceeds 4096 chars ({len(text)})"
+            )
+        payload = {
+            "model": self._tts_model,
+            "input": text,
+            "voice": voice if voice != "default" else self._tts_voice,
+            "response_format": self._tts_format,
+        }
+        try:
+            async with self._client.stream(
+                "POST",
+                f"{self._base_url}/audio/speech",
+                content=json.dumps(payload),
+                headers={**self._headers(), "Content-Type": "application/json"},
+            ) as resp:
+                resp.raise_for_status()
+                async for chunk in resp.aiter_bytes():
+                    if chunk:
+                        yield chunk
+        except httpx.HTTPError as exc:
+            raise self._sanitize(exc) from exc

apps/ai-service/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@nextcraft/ai-service",
   "private": true,
-  "version": "0.2.0",
+  "version": "0.6.5",
   "scripts": {
     "dev": "bash scripts/dev.sh",
     "test": "bash scripts/test.sh",
     "bootstrap": "bash scripts/bootstrap.sh",
-    "lint": "bash scripts/lint.sh"
+    "lint": "bash scripts/lint.sh",
+    "typecheck": "bash scripts/typecheck.sh"
   }
-}
+}

apps/ai-service/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nextcraft-ai-service"
-version = "0.2.0"
+version = "0.6.5"
 description = "Nextcraft AI tutor service — six LLM agents behind a provider-agnostic layer"
 requires-python = ">=3.11"
 dependencies = [
@@ -14,17 +14,32 @@ dependencies = [
     "pydantic-settings>=2.15,<2.16",
     "httpx>=0.28,<0.29",
     "sse-starlette>=3.4,<3.5",
-    "sqlmodel>=0.0.24,<0.1",
+    "sqlmodel>=0.0.24,<0.0.43",
+    # ^ P1 CI finding: sqlmodel 0.0.43+ (up to 0.0.47 resolved in fresh CI
+    # venvs) tightens Literal-arg inference on pydantic models — 15 mypy
+    # arg-type errors surface (DefenseRecord/TelemetryEvent/DefenseTurn).
+    # The v0.7-shipped line was 0.0.42; cap below .43 until the Literal
+    # annotations are tightened deliberately (per-module overrides later).
     "sqlalchemy>=2.0,<2.1",
     "websockets>=13,<16",
     "aiofiles>=24.1,<26",
+    # POST /v1/defense/{id}/answer multipart audio (REQ-3-006): FastAPI
+    # form/File parsing requires python-multipart at runtime.
+    "python-multipart>=0.0.32,<0.1",
+    # P4-B resume parse (REQ-6-005, D-054, A-410): PDF text extraction.
+    # Pure-Python, probe-verified 6.19.0 — the ONLY new v0.6 dependency.
+    "pypdf>=6.19,<7",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=9.1,<10",
     "pytest-asyncio>=1.4,<2",
+    "pytest-cov>=7.1,<8",
+    "pytest-timeout>=2.4,<3",
     "ruff>=0.14",
+    # P5 type hardening (D-058): mypy relaxed-first baseline. Resolved 2.3.1.
+    "mypy>=2.3,<2.4",
 ]
 
 [tool.setuptools.packages.find]
@@ -32,13 +47,105 @@ include = ["ai_service*"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+# D-056: pin the fixture loop scope — pytest-asyncio 1.4 warns at configure
+# time when this is unset and a future default flip would change loop reuse
+# for async fixtures. "function" is the current-effective default semantics.
+asyncio_default_fixture_loop_scope = "function"
 testpaths = ["tests"]
+# P1 harness wiring (D-053/D-054): strict markers + a 60s global timeout.
+# `timeout` also ships its own marker (`pytest.mark.timeout`); the 180s
+# override for real_server/userns tests is applied by the collection hook
+# in tests/conftest.py — marker-level values beat this global default.
+markers = [
+    "fast: in-process unit test (default tier — unmarked tests are fast)",
+    "real_server: spins a real uvicorn server process",
+    "userns: enters a real unshare user namespace",
+]
+addopts = "--strict-markers --timeout=60 --timeout-method=signal"
+# P3 zero-warning policy (D-056): base action `error` — every warning fails
+# the run; new first-party warnings can never pass silently. The ONLY
+# entries after "error" are the 2 known upstream import-time deprecations,
+# each scoped by exact message prefix + emitting module (the module whose
+# import triggers the warning, i.e. the frame the warning is attributed to
+# after stacklevel adjustment — NOT the package the warning text mentions):
+#
+#   1. fastapi.testclient re-exports starlette's TestClient, and importing
+#      it emits starlette's httpx→httpx2 migration warning (stacklevel=2
+#      attributes it to fastapi/testclient.py's import line).
+#   2. starlette.testclient resolves `anyio.abc.BlockingPortal` in a
+#      module-level type alias; anyio's lazy-import __getattr__ emits the
+#      alias-deprecation (stacklevel=3 attributes it to starlette's
+#      testclient.py).
+#
+# G-104 invariant: category-scoped ignores and ANY ignore matching
+# ai_service.* are forbidden forever; new upstream deprecations may join
+# this list only as module+message-scoped entries, justified in ship notes.
+# Fields: action:message-regex:category:module-regex:lineno (pytest parses
+# ini entries as raw regex — dots below are explicitly escaped).
+filterwarnings = [
+    "error",
+    # Upstream (1/2): starlette 1.6 httpx→httpx2 migration notice, raised
+    # while importing fastapi.testclient (importer frame is fastapi's).
+    "ignore:Using `httpx` with `starlette\\.testclient` is deprecated:starlette.exceptions.StarletteDeprecationWarning:fastapi\\.testclient",
+    # Upstream (2/2): anyio 4.x lazy-import alias deprecation, raised while
+    # starlette.testclient evaluates its `_PortalFactoryType` alias.
+    "ignore:The anyio\\.abc\\.BlockingPortal alias is deprecated:DeprecationWarning:starlette\\.testclient",
+]
+
+[tool.coverage.run]
+source = ["ai_service"]  # tests/ excluded by construction — only the package is measured
+branch = true
+
+[tool.coverage.report]
+# exclude_also APPENDS to coverage.py's built-ins (which already cover
+# `pragma: no cover` and `if TYPE_CHECKING:`); these add the __main__
+# entry-point guard (none in ai_service today — future-proof).
+exclude_also = [
+    "if __name__ == [\"']__main__[\"']:",
+    "if TYPE_CHECKING:",
+    "pragma: no cover",
+]
 
 [tool.ruff]
 line-length = 100
 target-version = "py311"
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "UP", "B"]
+select = ["E", "F", "W", "I", "UP", "B", "RUF100"]
 # B008: Depends() in argument defaults is the idiomatic FastAPI DI pattern
-ignore = ["B008"]
+ignore = ["B008"]
+
+# P5 mypy relaxed-first baseline (D-058) — NOT full strict. The flags
+# below are the binding set from the decision; per-module tightening via
+# [[tool.mypy.overrides]] is available later (the plan's Wave-5 follow-up
+# form). Scope decision (recorded per the task's pragmatic clause): ALL
+# THREE trees pass — ai_service/ + scripts/sandbox-agent.py + tests/ —
+# so tests are NOT excluded; every test violation was either fixed at
+# source or scoped with a coded ignore + reason inline. Tests remain
+# fully checked; a future tests.* per-module relaxation override stays
+# available (D-058) if the annotation burden grows.
+[tool.mypy]
+python_version = "3.11"
+files = [
+    "ai_service",
+    "scripts/sandbox-agent.py",
+    "tests",
+]
+# Untracked runtime droppings under tests/ (gitignored via
+# `apps/ai-service/**/sandboxes/`) must never be type-checked.
+exclude = ["tests/sandboxes"]
+# D-058 relaxed-first baseline:
+check_untyped_defs = true        # real bugs hide in unannotated bodies too
+no_implicit_optional = true      # implicit Optional is a genuine bug class
+warn_unused_ignores = true      # stale `# type: ignore` becomes an error (self-eliminating suppressions)
+warn_redundant_casts = true
+warn_unreachable = true
+warn_unused_configs = true
+# Start strict on imports: every runtime dep checked code imports ships
+# stubs (verified py.typed: fastapi/uvicorn/pydantic/pydantic-settings/
+# httpx/sse-starlette/sqlmodel/sqlalchemy/websockets/python-multipart/
+# pypdf/pytest/pytest-asyncio; aiofiles + pytest-timeout/pytest-cov are
+# never imported by checked code). Overrides are reserved for deps that
+# genuinely lack stubs — currently NONE, so no ignore_missing_imports
+# overrides are listed; warn_unused_configs would flag any added no-op.
+ignore_missing_imports = false

apps/ai-service/scripts/bootstrap.sh

@@ -1,30 +1,75 @@
 #!/usr/bin/env bash
 # Idempotent bootstrap: create venv + install deps.
-# Handles Debian systems without python3-venv/ensurepip via --without-pip + get-pip.
+# Handles Debian/Ubuntu systems without python3-venv/ensurepip via --without-pip + get-pip.
+# v2 (v0.3.5): recovers from a poisoned partial .venv left by a failed earlier
+# attempt, cleans before each retry, and dies with a distro-specific fix hint
+# when venv creation is impossible (e.g. missing python3.XX-venv package).
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 APP_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 VENV="$APP_DIR/.venv"
 
+venv_usable() {
+  [ -x "$VENV/bin/python3" ]
+}
+
+rm_broken_venv() {
+  echo "bootstrap: removing broken partial .venv from a failed earlier attempt" >&2
+  rm -rf "$VENV"
+}
+
 mkdir -p "$HOME/.cache/ciagent"
 
-if [ ! -x "$VENV/bin/python3" ]; then
-  if python3 -m venv "$VENV" 2>/dev/null; then
+if venv_usable && [ ! -x "$VENV/bin/pip" ]; then
+  # A usable python3 without pip means the --without-pip fallback half-ran and
+  # the get-pip step never completed: start over cleanly.
+  rm_broken_venv
+fi
+
+if ! venv_usable; then
+  if [ -d "$VENV" ]; then
+    # Directory exists but no working python3: remains of a crashed venv create.
+    rm_broken_venv
+  fi
+  if python3 -m venv "$VENV" 2>/tmp/venv-create.err; then
     :
   else
-    # No ensurepip available — create bare venv and bootstrap pip separately.
-    python3 -m venv --without-pip "$VENV"
+    rm -rf "$VENV"
+    if python3 -m venv --without-pip "$VENV" 2>>/tmp/venv-create.err; then
+      :
+    else
+      rm -rf "$VENV"
+      PYVER="$(python3 -c 'import sys; print("%d.%d" % sys.version_info[:2])' 2>/dev/null || true)"
+      PKG="python3-venv"
+      [ -n "$PYVER" ] && PKG="python${PYVER}-venv"
+      echo "bootstrap: could not create a virtual environment." >&2
+      echo "  python3 reported:" >&2
+      sed 's/^/    /' /tmp/venv-create.err >&2 || true
+      echo "  fix (Debian/Ubuntu): install the venv support package, then re-run nextcraft bootstrap:" >&2
+      echo "    apt install $PKG" >&2
+      exit 1
+    fi
   fi
 fi
 
 if [ ! -x "$VENV/bin/pip" ]; then
   GET_PIP="$HOME/.cache/ciagent/get-pip.py"
   if [ ! -f "$GET_PIP" ]; then
-    curl -sSf --max-time 60 https://bootstrap.pypa.io/get-pip.py -o "$GET_PIP"
+    if ! curl -sSf --max-time 60 https://bootstrap.pypa.io/get-pip.py -o "$GET_PIP"; then
+      rm -rf "$VENV"
+      echo "bootstrap: get-pip.py download failed (no network?)." >&2
+      echo "  fix: restore network access and re-run nextcraft bootstrap" >&2
+      exit 1
+    fi
+  fi
+  if ! "$VENV/bin/python3" "$GET_PIP" --quiet; then
+    rm -rf "$VENV"
+    echo "bootstrap: pip installation into the venv failed." >&2
+    echo "  fix: re-run nextcraft bootstrap (the venv was cleaned; this retry is safe)" >&2
+    exit 1
   fi
-  "$VENV/bin/python3" "$GET_PIP" --quiet
 fi
 
 "$VENV/bin/pip" install --quiet --upgrade pip
 "$VENV/bin/pip" install --quiet -e "$APP_DIR[dev]"
-echo "bootstrap complete: $VENV"
+echo "bootstrap complete: $VENV"