0018. Module boundaries and their automated enforcement
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”Agents work in parallel, and the hexagonal structure of ADR 0008 only holds if wrong imports fail the build. The dashboard must stay a pure API client, and public code must build without cloud/.
Decision
Section titled “Decision”Packages (pnpm workspaces, one package per directory):
core/ domain, ports, engine and steps, actions (registry), auth (sole minter of ProjectScope), ingest, tracking, billing, webhooks, extensionsadapters/sql/ shared Kysely repositories, SQLite and Postgres migrations, the DO dialectadapters/cloudflare/ ProjectDO, WorkspaceBudget DO, rate-limiter DO, D1 ControlStore, Queues, R2, Workers secrets, fetch OutboundHttpadapters/node-sqlite/ executor, timer, and queue for tests and developmentadapters/postgres/ executor (advisory lock and RLS), scheduler poller, jobs table, ControlStore, rate-limiter and budget rowsadapters/aws/ SQS, S3, Secrets Manageradapters/webcrypto/ Signer, SecretCipheradapters/email-ses/ adapters/email-fake/surfaces/http/ Hono app built from the registry: REST and OpenAPI, inbound and provider webhooks, click redirectsurfaces/mcp/ MCP tools built from the registrysurfaces/api-client/ typed client generated from OpenAPItesting/contracts/ port contract suitesapps/workers/ apps/node/ apps/dashboard/cloud/ private: extensions and the cloud composition rootDependency rules:
| Package | May import |
|---|---|
core |
nothing outside core |
adapters/sql |
core |
adapters/cloudflare, adapters/node-sqlite, adapters/postgres |
core, adapters/sql, adapters/webcrypto |
other adapters/* |
core, adapters/webcrypto |
surfaces/http, surfaces/mcp |
core |
surfaces/api-client |
generated code only |
testing/contracts |
core |
tests of adapters/* and apps/* |
also testing/contracts, as a dev dependency |
apps/workers, apps/node |
core, adapters/*, surfaces/* |
apps/dashboard |
surfaces/api-client and UI libraries only |
cloud/ |
public packages’ exports |
- No adapter imports another adapter except
adapters/sqlandadapters/webcryptoas listed. cloudflare:*and Workers types only inadapters/cloudflareandapps/workers.node:*and the AWS SDK only inadapters/node-sqlite,adapters/postgres,adapters/aws, andapps/node. Adapters that run on both targets (adapters/email-ses,adapters/webcrypto) use onlyfetchand WebCrypto.- Public code never imports
cloud/. - Only
core/authmints aProjectScope. - Core does not read time or randomness directly (
Date.now, argument-lessnew Date(),Math.random,crypto.randomUUID); it usesClockandIdGenerator.
Enforcement:
- pnpm strict dependencies and
package.jsonexports(no deep imports). - TypeScript project references (
tsc -b) mirroring the graph; core compiles withtypes: []so platform globals fail. - dependency-cruiser as the source of truth for the rule table (layer matrix, no public-to-cloud, no adapter-to-adapter, platform modules only where allowed, scope minting only from
core/auth, no cycles, no orphans). - ESLint
no-restricted-syntaxin core for the determinism ban. - CI:
oss-builddeletescloud/,AGENTS.cloud.md, anddocs/cloud/and still builds and tests.
Consequences
Section titled “Consequences”- The
check-dependenciesskill explains how to fix a violation by adding a port rather than changing the rule. - Changing a rule needs a new ADR and the configuration change in the same pull request.
- Open: the package for the Node
OutboundHttp(undici with a resolver-pinned address check); it needsnode:*and is security-critical, so it is placed deliberately whenapps/nodeis built. - The earlier proposed layout (
core/workflows/,core/email/adapters/) is replaced bycore/engine/andadapters/email-*.
Amendment (2026-11-18, ADR 0040): adapters/auth-better-auth joins the other adapters/* (imports core and adapters/webcrypto; imported by apps/workers and apps/node) and the adapters that run on both targets. Its dependency Better Auth also uses AsyncLocalStorage from node:async_hooks, which both targets provide; its own code imports no node:* or cloudflare:* module. Only it may import better-auth. surfaces/api-client, generated code and a fetch wrapper with no runtime dependencies, also holds a hand-written auth module under the same rule (api-client-no-npm: no npm import, no other package) (ADR 0028 amendment).
Amendment (2026-11-18, ADR 0040 amendment): the tests of adapters/auth-better-auth may import cloudflare:*, because they run on workerd and D1; its src still imports none.
Amendment (2026-11-20, ADR 0051): adapters/auth-better-auth/src/consent-grant.ts imports AsyncLocalStorage from node:async_hooks, which both targets provide, to hand the consent’s grant ID to the plugin; it is the package’s only node:* import.