Architecture: Codex TypeScript MCP

Context and Scope

• Capability identity: apps/wiki/content/docs/project/specs/cli/codex-typescript-mcp. The capability is Baseline-delivered native TypeScript 7 semantic reads for Codex agents: the hi CLI provisions a pinned Typegraph runtime, discovers compiler projects, probes them, writes Codex MCP entries, and reports health.
• Actors and outcome: the Codex agent working in one checkout needs definition, reference, type, export and symbol answers about TypeScript source without guessing from text. The human operator needs hi to set this up, keep it current, and say truthfully whether it works. Today the runtime is installed locally and answers through the SDK, but Codex has zero Typegraph entries (S1 "Current Round"; S4 "Runtime replay").
• In scope: Q10 to Q20 in the grill log (S2, section "R5 — Accepted decisions"). Premises C1 to C4 (S2, "Imported direction"). Non-goals: other languages and harnesses, semantic mutations, graph and Effect diagnostics, LSP hover, an HI router server, automatic recovery, runtime pruning, changes to global Codex approval policy (S1 "Outside Active Scope").
• Spec: sibling SPEC.md in this folder, retained in the commit that follows this architecture's retention.

Canonical Terms

Canonical terms reused unchanged from the Codex TypeScript MCP Glossary (S3): Pack, Baseline, Registry, Installed Record, Recorded Shape, Built Artifact, Authored Artifact, Software Scope, Effective Lint Policy.

Working labels, parked under Glossary Q21 and not canonical: Compiler Project (program and options of one tsconfig.json), Tool Runtime (the pinned Typegraph installation on one machine), Semantic Session (one live Typegraph process for one Compiler Project in one worktree).

Axioms used below: Pack is the only selection unit (C4); semantic reads never replace format, lint or typecheck evidence (C2); installed, registered, probe-passing and answered are four distinct facts (Q18); "compatible" means the bundled compiler loads the project (Q16); "fresh" covers source edits only (Q17).

Sources

S1 to S3 record accepted design. S4 to S7 record observed current behavior. S8 records vendor documentation, not proof of host behavior.

Source Disposition

Whole System

The CLI is the only writer of the capability's state on a machine and in a repository. The Registry says which repositories get it (Pack). The CLI turns that into a Tool Runtime on the machine, a set of Compiler Projects in the worktree, probe results, and Codex entries. Codex owns the running Semantic Sessions and applies approval. Existing hooks keep owning formatting and lint.

Anchors: Q10 to Q20 (S2 R5); E1, E2, E5 (S2); S4 A to D; S7. Conclusion: the Pack decides who, the CLI decides what is installed, discovered, probed and written, Codex decides what runs. Nothing in the Registry or Installed Record proves semantic readiness; only ARC-006 does.

Critical Flows and Boundaries

FLOW-001 Scaffold or update makes the capability current

FLOW-001-STEP-001  Pack resolved: TypeScript Pack selected -> capability applies (Q10)
FLOW-001-STEP-002  provision Tool Runtime: pinned version + exact lock on the machine;
                   already present and matching -> reuse; install failure -> reason recorded (Q11, Q19)
FLOW-001-STEP-003  discover Compiler Projects in this worktree:
                   source-bearing tsconfigs; skip wiki and solution-only; ambiguous -> report, use override (Q12)
FLOW-001-STEP-004  probe each Compiler Project under bundled TS 7.0.2:
                   pass -> eligible; fail -> unavailable + reason (Q16)
FLOW-001-STEP-005  write Codex entries: one per eligible project, five reads always approved;
                   restore drifted generated entries; leave other tables untouched (Q13, Q14, Q15)
FLOW-001-STEP-006  record health facts for hi check: installed | registered | probe per project (Q18)

Anchors: Q10 to Q16, Q18 (S2 R5); S4 A to D. Conclusion: every step produces a fact the next step consumes, and every failure stops at its own step with a reason. No step changes project dependencies, tsconfig content, or unrelated Codex tables.

Side-effect boundaries: STEP-002 writes outside the repository (machine). STEP-005 writes one Authored file inside the repository. STEP-006 writes no file it does not already own. There is no cross-file transaction (S4 D); partial completion is visible through STEP-006.

FLOW-002 Codex session answers a semantic question

Anchors: E1, E3, E6 (S2); Q13, Q15 (S2 R5); S8 keys. Conclusion: the agent picks the server whose Compiler Project owns the file; approval is decided by the generated entry, not by a prompt; the answer reflects disk at call time. Observed historical values: startup timeout 20 s, tool timeout 60 s (E3); these are evidence, not accepted limits.

FLOW-003 Change and deselection lifecycle

FLOW-003-STEP-001  ordinary source edit (hook-formatted) -> watcher -> next answer fresh (E4)
FLOW-003-STEP-002  tsconfig, dependency or branch change -> documented: start a new Codex session (Q17)
FLOW-003-STEP-003  repository deselects the TypeScript Pack -> next hi update removes this repo's
                   generated entries; Tool Runtime stays on the machine (Q20)

Anchors: E4 (S2); Q17, Q20 (S2 R5). Conclusion: freshness is guaranteed only for STEP-001; STEP-002 is an operator action by decision; STEP-003 is the only removal path and it never touches the machine runtime.

Accepted Detail Coverage

Spec Traceability

• State: complete. Spec codes OUT-001 to OUT-010 and AC-001 to AC-032 from the sibling SPEC.md (sections "Requirements and Outcomes" and "Acceptance Criteria") map below. Completed by create-spec on 2026-09-28 without changing accepted design.

Retired or Superseded Selectors

Flow Failure Coverage

Parked Work and Non-material Unknowns

Validation

• Decision/source/glossary reconciliation: S1 status shows R5 closed with Q10 to Q20 answered and Q21 parked; S2 log entries under "R5 — Accepted decisions" match S1 row by row; S3 glossary reuses existing canonical terms and marks the three labels as working. Retired Q1 to Q9 appear only in Source Disposition.
• Exact-detail and cross-level coverage: every Q10 to Q20 row in Accepted Detail Coverage names a selector and a served constraint; user overrides Q15 and Q19 are marked as such with their recorded wording.
• Relative links, selector targets, and visual source/order checks: all links use routed /docs/project/... paths that exist in the working tree; ARC-001 to ARC-008, FLOW-001 to FLOW-003 and their steps are defined once each; the system map and sequence diagram carry selector labels and Q anchors.
• Spec-code -> architecture -> grill coverage: complete; every OUT-001 to OUT-010 and AC-001 to AC-032 maps to at least one architecture selector and an accepted R5 entry (validated by script on 2026-09-28).
• Mermaid parsing/rendering: mermaid@11.15.0 parse() under a jsdom shim on 2026-09-28 accepted both blocks (flowchart-v2, sequence) after replacing a statement-splitting semicolon in FLOW-002-STEP-005. No rendered image was produced; the wiki app renders at build time.
• Existing spec agreement: sibling SPEC.md compiled from the same R5 entries; no conflicting constraint found.
• Remaining limits: unknowns listed above are non-material; no approval stamp is implied by status: compiled.