ADR-0009: Types-only Platform Core package

Status: Accepted Date: 2026-04-20

Context

@agent-platform/core is imported by every runtime package and by every Business Pack. If core pulls in a runtime library — Zod, an LLM SDK, Cloudflare types — every consumer inherits that dependency and any version constraints that come with it. A Zod upgrade in core becomes a coordinated upgrade across the whole repo.

Separately, if core mixes “type definitions” and “helper functions,” the line between contract and implementation blurs. Tests that should target runtime packages end up testing shapes that live in core. Abstractions creep. Over time it becomes hard to say what core is.

Decision

@agent-platform/core has zero runtime dependencies and zero runtime code. The only declared dependency is typescript (dev). Exports are type-only re-exports from a set of files under src/.

Factory helpers, validation schemas, and any code that does work at runtime live in sibling packages — a future @agent-platform/runtime, @agent-platform/schemas, etc.

Consequences

Tiny footprint. Consuming core costs nothing beyond type-checking time.
A forcing function for good design. If something needs to ship with core, it’s either a type or it doesn’t belong in core. That discipline keeps the contract clean.
Branded ID types (ADR-0007) can’t come with makeAgentId() helpers here — those live in the runtime packages that have validation logic anyway.
If we adopt Zod or another schema library later, there’s a separate decision to make: do schemas go in core (violating this ADR and requiring supersession), or in a separate @agent-platform/schemas package? See open-questions. Leaning toward the separate package.
The exports map in package.json points at src/*.ts directly, which works under moduleResolution: bundler. No build step needed for the types-only package. If we ever publish externally, we’ll add a build step to emit .d.ts files.

Alternatives considered

Core includes Zod schemas and derives types via z.infer: single source of truth, appealing. Rejected for now because it pins core to Zod and exposes every consumer to Zod’s bundle cost. Reconsider if we adopt Zod and decide the ergonomics outweigh the coupling.
Core includes runtime helpers (factories, assemblers): mixes contract with implementation. Harder to reason about where a behavior lives. Rejected.
Core exports a mix of types and plain-function utilities (no heavy deps): tempting — a few helpers wouldn’t hurt — but it’s a slippery slope. Draw the line at zero.
Skip a types package entirely; put types inline in each runtime package: creates duplication and drift. Business Packs must agree on the shape of an AgentDefinition. A shared types package is the only sane answer.