Skip to content
Agent Platform

ADR-0002: TypeScript strict mode (all flags)

ADR-0002: TypeScript strict mode (all flags)

Section titled “ADR-0002: TypeScript strict mode (all flags)”

Status: Accepted Date: 2026-04-20

Context

Section titled “Context”

The platform deals with security-critical domain concepts: immutable context layers, typed task delegation between agents, tool input validation. Small type-level mistakes can translate to real failure modes — a bug that lets a delegated task override an agent’s core context is a security issue, not just a correctness issue.

TypeScript offers several strictness dials beyond strict: true. Most projects leave them off by default.

Decision

Section titled “Decision”

Enable every available strictness flag in tsconfig.base.json, inherited by all packages:

  • strict: true (baseline)
  • noUncheckedIndexedAccess: true — array/record access returns T | undefined
  • noImplicitOverride: true
  • noImplicitReturns: true
  • noFallthroughCasesInSwitch: true
  • exactOptionalPropertyTypes: true — distinguishes { x?: T } from { x: T | undefined }
  • useUnknownInCatchVariables: true
  • isolatedModules: true
  • verbatimModuleSyntax: true — requires import type where applicable; prevents accidental runtime imports

Consequences

Section titled “Consequences”
  • More annotations required. Worth it; explicit types are documentation.
  • noUncheckedIndexedAccess adds | undefined to record/array reads. Forces us to handle the “missing key” case at the type level — exactly what we want for things like tool lookup and memory retrieval.
  • exactOptionalPropertyTypes makes “field absent” and “field set to undefined” different at the type level. This matches our intent in ContextBundle where delegated is either present or absent, never explicitly undefined.
  • verbatimModuleSyntax prevents surprising runtime effects from imports — critical when a Platform Core type accidentally causing a runtime import would pull e.g. Zod into every consumer.
  • Packages may locally relax rules if they have a good reason. We don’t relax the base.
  • Some third-party .d.ts files violate strict rules. skipLibCheck: true is already set to avoid this.

Alternatives considered

Section titled “Alternatives considered”
  • Default strict: true only: misses the bugs that actually bite us — index access, catch-variable typing, optional vs undefined.
  • Gradual adoption (strict on new files, loose on old): we have no old files. Adopt strict now and keep it.
  • noPropertyAccessFromIndexSignature: considered but not enabled — too noisy for JSON-like payloads we’ll inevitably work with. Might revisit.