ADR 0006 · Package and runtime layout

2 min readAcceptedRecorded 2026-05-02

What this ADR decides

That Craik groups implementation files by concern under runtime.providers, runtime.memory, runtime.policy, runtime.work, runtime.runners, runtime.channels, runtime.sandbox, and companion packages — while keeping craik.contracts.models and common craik.runtime.* imports as compatibility surfaces.

Status: Accepted.

Ownership and review scope live in the package layout, not in a flat runtime namespace.

Context

Craik started with broad runtime and contract modules because early milestones were contract-heavy and issue-driven. That made discovery easy at first, but it created god files and a flat runtime namespace that hid ownership boundaries. The runtime now contains providers, memory, policy, work execution, companions, channels, voice, sandboxing, and project workflows with different change rates and risk profiles.

Decision

runtime.providers

runtime.memory

runtime.policy

runtime.work

runtime.runners

runtime.channels

runtime.sandbox

Companion packages

Compatibility surface preserved.

The root runtime package maintains lazy legacy module aliases for moved public modules. No runtime package should grow beyond 15 sibling Python modules without a new layout decision or a deeper package split.

Consequences

This makes ownership and review scope clearer while preserving existing imports. It also adds a compatibility layer that must be tested whenever modules move. New work should choose the package that matches the runtime concern rather than creating one module per issue at the root.

Alternatives considered

Alternative

Disposition

Why rejected

Leave compatibility shim files at the runtime root

rejected

Would preserve the flat sibling-module problem.

Break legacy imports and update every caller

rejected

The public import surface is already used by tests, docs, and downstream automation.

Retraction: none active.

Retract this ADR if Craik adopts a generated API layer or a plugin loader that replaces direct runtime package imports.

What's next

ReadArchitectureThe seven runtime layers this layout backs.ADR0001 · Record MVP runner scopeThe framing decision that shaped the runtime cleanup.ReadImplementation planThe repo-shape recommendation that aligns with this ADR.