ADR-003 — No runtime dependencies in the core

Date: 2026-09-02 · Status: accepted · Scope: stack

Context

After ADR-001, 160 ms is left for everything the CLI does. The cost of merely importing each candidate was measured (best of 3, Node v25.8.2, unbundled):

zod alone costs 15% of the entire budget — to validate an object with seven fields.

So the alternative was measured too:

Both are about 30 lines.

Decision

The core has no runtime dependency at all. ULID and event validation are hand-rolled and under test.

This is not "not invented here". The argument is measurable and singular: general validation libraries exist for schemas described at runtime that change. Our event shape is fixed in types at compile time, and the check is needed at exactly one boundary — reading a file a person or a merge could have corrupted. For that, a 5.8 MB engine gives nothing a 20-line function does not, and costs a fifth of the startup budget.

ULID was chosen over UUIDv4 for a separate reason: the first 10 characters are a timestamp in Crockford base32, so sorting ids lexicographically matches sorting them chronologically. Event order becomes a property of the id rather than of how far apart machine clocks have drifted.

Consequences

• About 34 ms of budget saved; npm audit has nothing to report on the core; the supply chain has zero links.
• ~60 lines of cryptographically sensitive (ULID uses node:crypto) and validation code that we must test ourselves — with property tests, not just examples.
• What would make us revisit it: if the event schema becomes extensible by plugins with their own fields, fixed validation stops working, and valibot becomes the cheapest engine to fall back to.