0002 — Agents own their own code, zero shared TypeScript

• Status: Accepted
• Date: 2026-04-17
• Deciders: Fede
• Related: ADR-0001

Context

Given ADR-0001 (decouple web from agents), the next question is how much code they may share.

Decision

Zero shared TypeScript files. src/ (Vercel web) and agents/** (AWS runtimes) do not import from each other. There is no packages/ folder of common code.

Each side maintains its own:

• DynamoDB repository implementations
• TypeScript interfaces / types for DDB entities
• SQS message type definitions
• Claude/Twilio/SendGrid client wrappers

Schema coordination happens via human-readable documentation in docs/architecture/data-contract.md (to be written), not via compile-time types. The DDB tables are the source of truth. Schema changes are a two-sided PR across both runtimes, reviewed explicitly.

Consequences

Easier

• Either side deploys on its own schedule without waiting on the other.
• A bug in agents' type definitions can't cascade into a broken Vercel build.
• Boundaries are obvious — you can't accidentally reach across because the import doesn't resolve.

Harder

• DDB entity types exist twice. Accepted because they're small, stable, and rarely change.
• Schema changes require discipline — both sides updated and deployed in a coordinated order.

Enforcement

• tsconfig.json paths in src/ exclude agents/**.
• tsconfig.json in each agent excludes src/** and peer agents.
• ESLint rule: no-restricted-imports blocks cross-runtime imports with a clear error message linking to this ADR.

Alternatives considered

Shared types package (packages/types). Rejected because it still creates a deploy-coordination burden: when types change, both sides must consume the new version before deploying consumers of the changed field.

Agents import from src/lib/data/types.ts only. Status quo. Rejected because it's how we got drift — any "just one import" turns into dozens.

Generate types from a schema source of truth. Overengineered for a 4-person team. Revisit later.