@fabrika/builder 0.2.0

package/daemon/src/phases.ts

@@ -0,0 +1,221 @@
+import { existsSync, readdirSync, statSync } from 'fs'
+import { basename, dirname, join } from 'path'
+
+export type PhaseId =
+	| 'intake'
+	| 'vision'
+	| 'flows'
+	| 'tech'
+	| 'design'
+	| 'skeletons'
+	| 'issues'
+	| 'build'
+
+export interface Phase {
+	id: PhaseId
+	index: number
+	title: string
+	reads: string[]
+	produces: string[]
+	gate: boolean
+	gateName?: string
+}
+
+export const PHASES: Phase[] = [
+	{
+		id: 'intake',
+		index: 1,
+		title: 'Intake (brief → classification)',
+		reads: ['intent/brief.md'],
+		produces: ['intent/brief.md'],
+		gate: true,
+		gateName: 'intake',
+	},
+	{
+		id: 'vision',
+		index: 2,
+		title: 'Vision + scope + principles',
+		reads: ['intent/brief.md'],
+		produces: ['intent/glossary.md', 'principles/principles.md'],
+		gate: true,
+		gateName: 'vision',
+	},
+	{
+		id: 'flows',
+		index: 3,
+		title: 'User flows',
+		reads: ['intent/*', 'principles/*'],
+		produces: ['architecture/flows/*.flow.md'],
+		gate: true,
+		gateName: 'flows',
+	},
+	{
+		id: 'tech',
+		index: 4,
+		title: 'Tech + scaffold decision',
+		reads: ['architecture/flows/*'],
+		produces: ['architecture/tech.md'],
+		gate: true,
+		gateName: 'tech',
+	},
+	{
+		id: 'design',
+		index: 5,
+		title: 'Design tokens + mockups',
+		reads: ['architecture/flows/*', 'architecture/tech.md'],
+		produces: ['architecture/design.md', 'pages/*.jsx'],
+		gate: true,
+		gateName: 'design',
+	},
+	{
+		id: 'skeletons',
+		index: 6,
+		title: 'Opice skeletons',
+		reads: ['architecture/flows/*', 'architecture/spec/*'],
+		produces: ['../tests/browser/*.test.ts'],
+		gate: true,
+		gateName: 'skeletons',
+	},
+	{
+		id: 'issues',
+		index: 7,
+		title: 'Induce issues (compile step, not a real phase — SPEC §6.4)',
+		reads: ['../tests/browser/*'],
+		produces: ['issues/ISSUE-*.md'],
+		gate: false,
+	},
+	{
+		id: 'build',
+		index: 8,
+		title: 'Build (agent-assisted, supervised subagents)',
+		reads: ['issues/*'],
+		produces: [],
+		gate: true,
+		gateName: 'build',
+	},
+]
+
+export interface PhaseState {
+	current: PhaseId
+	index: number
+	completed: PhaseId[]
+	reads: string[]
+	produces: string[]
+	gate: boolean
+	gateName?: string
+	satisfied: boolean
+}
+
+export interface GateOracle {
+	getLatestUnconsumedFeedback(sessionId: string): { revision: number; feedback: string } | null
+	hasGateRevision?(sessionId: string, gateName: string): boolean
+}
+
+function expandGlob(fabrikaDir: string, glob: string): string[] {
+	const abs = join(fabrikaDir, glob)
+	if (!abs.includes('*')) {
+		return existsSync(abs) ? [abs] : []
+	}
+	const dir = dirname(abs)
+	const pattern = basename(abs) // e.g. "*.flow.md", "ISSUE-*.md", "*"
+	if (!existsSync(dir)) return []
+
+	const re = globToRegExp(pattern)
+	const out: string[] = []
+	for (const name of readdirSync(dir)) {
+		if (re.test(name)) out.push(join(dir, name))
+	}
+	return out
+}
+
+function globToRegExp(pattern: string): RegExp {
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+		.replace(/\*/g, '.*')
+	return new RegExp(`^${escaped}$`)
+}
+
+function isNonEmptyFile(p: string): boolean {
+	try {
+		const s = statSync(p)
+		return s.isFile() && s.size > 0
+	} catch {
+		return false
+	}
+}
+
+export function producesSatisfied(phase: Phase, fabrikaDir: string): boolean {
+	if (phase.produces.length === 0) return false
+	for (const glob of phase.produces) {
+		const matches = expandGlob(fabrikaDir, glob).filter(isNonEmptyFile)
+		if (matches.length === 0) return false
+	}
+	return true
+}
+
+export function gateSatisfied(
+	phase: Phase,
+	sessionId: string,
+	oracle?: GateOracle,
+): boolean {
+	if (!phase.gate) return true
+	if (!oracle) return true
+	if (oracle.getLatestUnconsumedFeedback(sessionId) !== null) return false
+	if (oracle.hasGateRevision && phase.gateName) {
+		return oracle.hasGateRevision(sessionId, phase.gateName)
+	}
+	return true
+}
+
+function resolveReads(phase: Phase, fabrikaDir: string): string[] {
+	const out: string[] = []
+	for (const glob of phase.reads) {
+		out.push(
+			...expandGlob(fabrikaDir, glob).filter(p => {
+				try {
+					return statSync(p).size > 0 || statSync(p).isDirectory()
+				} catch {
+					return false
+				}
+			}),
+		)
+	}
+	return out
+}
+
+export function derivePhaseState(
+	fabrikaDir: string,
+	sessionId = '',
+	oracle?: GateOracle,
+): PhaseState {
+	const completed: PhaseId[] = []
+
+	for (const phase of PHASES) {
+		if (producesSatisfied(phase, fabrikaDir) && gateSatisfied(phase, sessionId, oracle)) {
+			completed.push(phase.id)
+			continue
+		}
+		return {
+			current: phase.id,
+			index: phase.index,
+			completed,
+			reads: resolveReads(phase, fabrikaDir),
+			produces: phase.produces,
+			gate: phase.gate,
+			...(phase.gateName ? { gateName: phase.gateName } : {}),
+			satisfied: producesSatisfied(phase, fabrikaDir),
+		}
+	}
+
+	const build = PHASES[PHASES.length - 1]!
+	return {
+		current: build.id,
+		index: build.index,
+		completed: completed.filter(id => id !== build.id),
+		reads: resolveReads(build, fabrikaDir),
+		produces: build.produces,
+		gate: build.gate,
+		...(build.gateName ? { gateName: build.gateName } : {}),
+		satisfied: false,
+	}
+}

package/daemon/src/static.ts

@@ -0,0 +1,72 @@
+import type { Route } from '@fabrika/daemon-kit'
+import { dirname, join } from 'path'
+
+const MIME_TYPES: Record<string, string> = {
+	js: 'application/javascript',
+	mjs: 'application/javascript',
+	css: 'text/css',
+	html: 'text/html',
+	svg: 'image/svg+xml',
+	png: 'image/png',
+	jpg: 'image/jpeg',
+	jpeg: 'image/jpeg',
+	gif: 'image/gif',
+	ico: 'image/x-icon',
+	woff: 'font/woff',
+	woff2: 'font/woff2',
+	json: 'application/json',
+	map: 'application/json',
+}
+
+function resolveDistDir(): string {
+	const override = process.env['FABRIKA_UI_DIST']
+	if (override) return override
+	return join(dirname(import.meta.dir), '..', 'ui', 'dist')
+}
+
+function mimeFor(path: string): string {
+	const ext = path.split('.').pop()?.toLowerCase() ?? ''
+	return MIME_TYPES[ext] ?? 'application/octet-stream'
+}
+
+export function createStaticHandlers(): Route[] {
+	const distDir = resolveDistDir()
+
+	async function serveSpaIndex(): Promise<Response> {
+		const file = Bun.file(join(distDir, 'index.html'))
+		if (await file.exists()) {
+			return new Response(file, {
+				headers: { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache' },
+			})
+		}
+		return new Response(
+			'Builder dashboard not found. Reinstall @fabrika/builder or run its build script.',
+			{ status: 503, headers: { 'Content-Type': 'text/plain' } },
+		)
+	}
+
+	async function serveAsset(_req: Request, url: URL): Promise<Response> {
+		const rel = url.pathname.replace(/^\//, '')
+		const assetPath = join(distDir, rel)
+		if (!assetPath.startsWith(distDir)) {
+			return new Response('Forbidden', { status: 403 })
+		}
+		const file = Bun.file(assetPath)
+		if (!(await file.exists())) return new Response('Not found', { status: 404 })
+		const basename = assetPath.slice(assetPath.lastIndexOf('/') + 1)
+		const isHashed = /\.[a-z0-9]{8,}\.[a-z0-9]+$/i.test(basename)
+		return new Response(file, {
+			headers: {
+				'Content-Type': mimeFor(url.pathname),
+				'Cache-Control': isHashed
+					? 'public, max-age=31536000, immutable'
+					: 'no-cache',
+			},
+		})
+	}
+
+	return [
+		{ method: 'GET', pattern: new URLPattern({ pathname: '/s/:id' }), handler: serveSpaIndex },
+		{ method: 'GET', pattern: new URLPattern({ pathname: '/assets/*' }), handler: serveAsset },
+	]
+}

package/decisions/README.md

@@ -0,0 +1,133 @@
+# Decisions catalog
+
+A **catalog of atomic, self-contained stack decisions** plus thin **stack presets**
+(`../stacks/`) that compose them. Replaces the old monolithic `profiles/*/profile.ts`
+(where cf-fat had to copy ~80% of cf-lightweight): each choice is one referenceable
+`.md`, and a stack is just a list of decision ids.
+
+fabrika core stays **stack-neutral** and consumes this as data — a **curated
+reference, not a code generator** (no templates). There is **no resolver code**: the
+graph is consumed _pure-reference_ by the **tech phase** (`phases.ts` phase 4) — the
+agent reads the selected stack's decisions, resolves the graph by reading, composes
+the concrete stack into `.fabrika/architecture/tech.md`, and the human edits it at the gate.
+
+This catalog is **not copied** into the target repo at `init`. It lives here in the
+fabrika tree and is delivered by **absolute path**: `fabrika builder next` (tech) and `fabrika
+build` resolve the active `profile` to `stacks/<profile>.md` + this `decisions/` dir
+and emit them as a `Stack:` pointer in the packet (see `cli/src/catalog.ts`).
+
+> **Team preference: Bun, lopata, non-vite.** When composing a stack, default to
+> `bun` (runtime/toolchain) and `lopata` (local CF runtime, over `cloudflare-vite-plugin`),
+> and prefer Bun-native bundling (`@buzola/bun-plugin`, pletivo's Bun build) over `vite`
+> wherever a decision offers it. `vite` stays a scoped exception for libs that mandate it
+> (React Router v7).
+
+## Two orthogonal axes: `kind` and `status`
+
+Every decision is classified on two independent axes.
+
+**`kind`** — _what sort of thing it is_ (and which subfolder it lives in):
+
+| kind         | folder          | what it is                                                                                                                                                                   | has a package?     |
+| ------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `technology` | `technologies/` | a concrete lib / service / framework you **adopt & install** (cloudflare, react, contember, pletivo, opice…)                                                                 | yes (`npm`/binary) |
+| `pattern`    | `patterns/`     | an architectural recipe you **apply** _over_ technologies — no package; it `requires` the technologies it composes (count-store, write-split, named-seeds, auth-password-kv) | no                 |
+| `tooling`    | `tooling/`      | an **additive** dev tool outside the runtime stack (deptective, edvabe) — never part of a preset's closure                                                                   | yes                |
+
+`kind` is **orthogonal to `slot`**: a pattern can still fill a slot (`named-seeds`→`seed-strategy`, `auth-password-kv`→`authentication`).
+
+**`status`** — _how prod-ready it is_: `stable` | `wip` | `experimental`.
+
+> **Selection policy.** The tech phase **defaults to `stable`**. `wip`/`experimental`
+> are opt-in: surface them only when the goal specifically calls for one, flag them as
+> not-prod-ready, and **never auto-recommend** them. A preset that includes a non-stable
+> decision must say so.
+
+## A decision file
+
+`decisions/<kind>/<id>.md` — ids are **globally unique** across the subfolders (a stack
+references a decision by bare id, never by path). Frontmatter is the machine-readable
+graph; the body is the human/agent reference (what it is, when/why, tradeoffs, impacts,
+gotchas, sources). Patterns use the same schema minus `npm`, and their body says what
+they **apply to** rather than how to install. Schema:
+
+```yaml
+---
+id: <kebab-case>          # == filename; globally unique
+kind: technology|pattern|tooling
+title: <human title>
+slot: <slot|null>         # exclusive slot it fills (router, platform, relational-db…).
+                          # two decisions in the same slot conflict implicitly.
+provides: [capability]    # capability tags this decision fulfills
+requires: [id, …]         # HARD deps — must also be in the stack
+recommends: [id, …]       # SOFT suggestions — offer, don't force
+conflicts: [id, …]        # explicit incompatibilities (beyond same-slot)
+npm: [pkg@^baseline, …]   # technologies/tooling only; REFERENCE baseline (verify against installed)
+status: stable|wip|experimental
+sources:                  # live truth to READ before scaffolding (anti-staleness)
+  - where: <repo path / npm pkg / URL>
+    read: <what to read it for>
+---
+```
+
+## The three edge types (everything the graph needs)
+
+- **`requires`** — hard dependency. Pick A ⇒ B must be in the stack. `vozka →
+  {cloudflare, oblaka, wrangler, propustka}`, `buzola → react`, `write-split → analytics-engine`.
+- **`recommends`** — soft suggestion. Pick A ⇒ offer B. `cloudflare → d1, durable-objects`.
+- **`conflicts`** — declared incompatibility. `buzola ✕ react-router` (both routers).
+  Often _implied_ by two decisions sharing an exclusive **`slot`**, so `conflicts` is
+  only written where same-slot detection isn't enough.
+
+`provides` is the capability vocabulary the edges talk about; `slot` is the
+single-occupancy version of a capability (a stack has one `router`, one `platform`).
+
+## Dangling references are fine
+
+A `requires`/`recommends`/`conflicts` id that has no file yet is a **TODO marker**,
+not an error — same convention as memory `[[links]]`.
+
+## Stack presets (`../stacks/`)
+
+A preset is **thin**: a one-line goal + a list of decision ids (technologies + patterns;
+tooling is additive, not part of closure). All gotchas/conventions live on the decisions.
+See `../stacks/README.md`.
+
+## Catalog
+
+### Technologies (`technologies/`)
+
+| slot / area                        | decisions                                                                        |
+| ---------------------------------- | -------------------------------------------------------------------------------- |
+| platform / edge auth               | `cloudflare`, `cloudflare-access` (legacy alternative to native Propustka)       |
+| relational store (`relational-db`) | `d1`, `postgres`                                                                 |
+| storage / state                    | `kv`, `r2`, `durable-objects`, `analytics-engine`                                |
+| messaging / jobs                   | `queue`, `cron-triggers`                                                         |
+| AI runtime                         | `workers-ai`                                                                     |
+| runtime / build / iac / deploy     | `bun`, `vite`, `lopata`, `cloudflare-vite-plugin`, `oblaka`, `wrangler`, `vozka` |
+| ui framework                       | `react`, `preact`                                                                |
+| router                             | `react-router`, `buzola`                                                         |
+| styling                            | `tailwind`                                                                       |
+| backend / data API (`backend`)     | `contember`, `bindx`                                                             |
+| site / content (`site-framework`)  | `pletivo`, `nuasite`                                                             |
+| agents (`agent-sdk`)               | `roj`                                                                            |
+| native authn/authz                 | `propustka`                                                                      |
+| error tracking (`error-tracking`)  | `sentry`                                                                         |
+| testing                            | `opice`                                                                          |
+
+### Patterns (`patterns/`)
+
+Applied _over_ the technologies they `require` (no package; `kind: pattern`).
+
+| theme                   | patterns                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| architecture / delivery | `monorepo`, `di-container`, `feature-architecture`, `single-worker-spa`, `typed-worker-rpc` |
+| data / seeds            | `named-seeds`                                                                               |
+| CF write patterns       | `count-store`, `write-split`                                                                |
+| auth                    | `auth-password-kv`                                                                          |
+| CI / CD                 | `app-deploy` (direct), `vozka-app-deploy` (control plane), `lib-publish`                    |
+| observability           | `structured-logging`, `observability`                                                       |
+
+### Tooling (`tooling/`)
+
+`deptective`, `edvabe` — additive dev tools (`slot: null`), not part of preset closure.

package/decisions/patterns/app-deploy.md

@@ -0,0 +1,55 @@
+---
+id: app-deploy
+kind: pattern
+title: Direct app deploy — push-to-branch → oblaka → wrangler (Cloudflare)
+slot: null
+provides: [ci-deploy, cf-deploy, infra-provisioning]
+requires: [cloudflare, oblaka, wrangler]
+recommends: []
+conflicts: [vozka-app-deploy]
+status: stable
+sources:
+  - where: "opice — .github/workflows/deploy.yml (the canonical app-deploy workflow)"
+    read: "The branch triggers, oblaka --remote provisioning, D1 migrate, and wrangler deploy steps."
+  - where: "oblaka — README / CLAUDE.md (the `bunx oblaka <file> --remote --env=…` deploy story)"
+    read: "How oblaka provisions bindings + emits wrangler.jsonc, idempotently, keyed by a state namespace."
+---
+
+# App deploy (Cloudflare)
+
+## What it is
+
+A Cloudflare app deploys via **GitHub Actions on a branch push**: `main` → **stage**,
+`deploy/prod` (or `prod`) → **production**, plus `workflow_dispatch` for manual runs.
+The job runs **`bunx oblaka oblaka.ts --remote --env=<stage|prod>`** to provision
+bindings (D1/KV/R2/DO/AE) via the CF API and emit `wrangler.jsonc`, then
+**`wrangler d1 migrations apply DB --remote`**, then **`wrangler deploy`**. Auth is
+`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` secrets; the GitHub `environment` is
+chosen from the branch, with a concurrency lock per environment.
+
+This is the **direct per-repository alternative** for accounts/apps not managed by
+Vozka. Do not scaffold it alongside `vozka-app-deploy`.
+
+## When & why to use
+
+- A Cloudflare app whose target account is **not** managed by Vozka — deploy is a
+  git push to the env branch, with infra-as-code and no dashboard clicking.
+- Prefer `vozka-app-deploy` when the target account already has Vozka + Propustka.
+
+## When NOT to use
+
+- Non-CF deploy targets (a Node/Postgres backend like `contember` deploys differently — container/VPS, not wrangler).
+
+## Gotchas
+
+- **oblaka is idempotent via a state namespace** — it tracks resource IDs across runs; don't hand-create the same resources or you'll drift.
+- **Migrations run at deploy time** (`--remote`), not before — a failed migration fails the deploy; keep them idempotent.
+- **Per-env from the branch** — `main`→stage, `deploy/prod`→prod; the GitHub `environment` gates secrets + serializes concurrent deploys.
+- Never hand-edit the generated `wrangler.jsonc` — change `oblaka.ts`.
+- Never run this workflow and Vozka against the same target during normal
+  operation; their locks do not coordinate.
+
+## Relationships — why
+
+- **requires `cloudflare` + `oblaka` + `wrangler`** — it's exactly the oblaka→wrangler.jsonc→wrangler-deploy chain on CF. Pairs with `lib-publish` (the other half of CI) in a monorepo.
+- **conflicts `vozka-app-deploy`** — one app/environment must have one deploy owner.

package/decisions/patterns/auth-password-kv.md

@@ -0,0 +1,45 @@
+---
+id: auth-password-kv
+kind: pattern
+title: Password + session-in-KV auth (app-owned)
+slot: authentication
+provides: [authentication, sessions, invites]
+requires: [kv]
+recommends: [d1]
+conflicts: [cloudflare-access]
+npm: []
+status: stable
+sources:
+  - where: "Pattern. Reference: the cf-fat stack (app/auth.ts) + WebCrypto PBKDF2/scrypt."
+    read: "Password hashing with WebCrypto, session token in a cookie backed by KV, invite tokens, route guards."
+---
+
+# Password + session-in-KV auth
+
+## What it is
+
+App-owned authentication: **password hashing** (WebCrypto PBKDF2/scrypt) + a
+**session token in a cookie backed by KV** + admin bootstrap + invite tokens + route
+guards. The simplest correct self-hosted login when you're not behind Cloudflare
+Access.
+
+## When & why to use
+
+- Self-hosted single-team tool with admin bootstrap + invites, no IdP/SSO needed in M1.
+- You can't put users behind Access (e.g. external invitees) but don't need full OAuth.
+
+## When NOT to use
+
+- You have an IdP / want managed SSO → `cloudflare-access`.
+- Consumer product needing OAuth / magic-link at scale → a dedicated auth provider.
+
+## Impacts & gotchas
+
+- **Never store plaintext** — hash with WebCrypto (PBKDF2/scrypt); compare in constant time.
+- Session token in an HttpOnly cookie, validated against `kv` (with TTL); guard protected routes server-side.
+- User records / membership in `d1`; session/invite ephemera in `kv`.
+
+## Relationships — why
+
+- **requires `kv`** — session + invite tokens live there. **recommends `d1`** — user/membership records.
+- **conflicts `cloudflare-access`** — both fill the `authentication` slot; app-owned password vs managed SSO. Pick one.

package/decisions/patterns/count-store.md

@@ -0,0 +1,44 @@
+---
+id: count-store
+kind: pattern
+title: CountStore abstraction (counts: local vs Analytics Engine)
+slot: null
+provides: [count-abstraction]
+requires: [d1]
+recommends: [analytics-engine]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "Pattern (no library). Reference: the cf-fat stack + app/lib/count-store.ts it prescribes."
+    read: "The interface shape and the two impls (local/in-memory/D1 vs Analytics Engine)."
+---
+
+# CountStore abstraction
+
+## What it is
+
+A pattern, not a library: a `CountStore` interface — `record(event)` +
+`query(filters) -> {fingerprint, count, first, last}` — with **two impls selected
+by env**: a local one (in-memory in tests, D1 aggregation in dev) and an
+**Analytics Engine** one (writes `env.AE.writeDataPoint`, queries the AE SQL HTTP
+API with `SUM(_sample_interval)`) for prod.
+
+## When & why to use
+
+- You chose `analytics-engine` for counts but need build + opice tests to run **locally with no CF account** (AE has no local runtime).
+- Any "swap the metrics backend by env" requirement.
+
+## When NOT to use
+
+- Counts are exact, low-volume, and fine to keep in D1 → just use `d1`, skip the abstraction.
+
+## Impacts & gotchas
+
+- The interface is the contract; loaders/handlers depend on it, **never** call `env.AE` directly so dev/test never need a token.
+- Local impl must produce the same shape the AE impl does (count + first/last seen), so tests assert behavior, not backend.
+
+## Relationships — why
+
+- **requires `d1`** — the local/dev impl aggregates counts from a D1 table.
+- **recommends `analytics-engine`** — the production backend this abstraction exists to hide. (It's also `analytics-engine`'s hard requirement, reciprocally.)

package/decisions/patterns/di-container.md

@@ -0,0 +1,47 @@
+---
+id: di-container
+kind: pattern
+title: DI container / IoC (Proxy-based lazy-memoized container)
+slot: null
+provides: [dependency-injection, ioc, service-composition]
+requires: []
+recommends: []
+conflicts: []
+status: stable
+sources:
+  - where: "MDN Proxy documentation"
+    read: "Language semantics for lazy getters, memoization, and circular-dependency detection."
+  - where: "Martin Fowler — Inversion of Control Containers and the Dependency Injection pattern"
+    read: "Composition-root ownership and dependency lifetimes."
+---
+
+# DI container / IoC
+
+## What it is
+
+A lightweight **dependency-injection container**: a class whose services are **getter
+properties**; the constructor `return createContainer(this)` wraps it in a Proxy that
+**memoizes each getter on first access** and **detects circular dependencies**. No
+external lib, no decorators/reflection. Scope = container lifetime (one per request,
+one per Durable Object). Eliminates `new Service(db, logger, clock, …)` chains — you
+write `this.serviceA` and lazy resolution does the rest.
+
+## When & why to use
+
+- Tightly-coupled services sharing resources (db, logger, config, clock) that should init once per request/actor.
+- You want lazy instantiation (only used services are built) + cheap cycle detection, without a heavy framework.
+
+## When NOT to use
+
+- You need constructor factory params, lifecycle hooks (`onDestroy`), or reflective metadata → a full container (inversify/awilix/tsyringe).
+
+## Gotchas
+
+- **Constructor must be only `return createContainer(this)`** — no field assignments.
+- **Use getters, not class fields** — an arrow-function field captures `this` before the Proxy wraps it and bypasses memoization/cycle detection.
+- **Mocks via `setService()`** (test API) pin a service for the container's life.
+- **Cycle errors are lazy** — thrown at access time, not container creation; an unused cycle stays hidden until that path runs.
+
+## Relationships — why
+
+- A pure TS pattern (no tech deps). Pairs with `feature-architecture` (the container is where adapters get wired into domain services).

package/decisions/patterns/feature-architecture.md

@@ -0,0 +1,48 @@
+---
+id: feature-architecture
+kind: pattern
+title: Feature-split + light hexagonal (ports & adapters)
+slot: null
+provides: [feature-modules, hexagonal, ports-adapters, testable-domain]
+requires: []
+recommends: [di-container, opice]
+conflicts: []
+status: stable
+sources:
+  - where: "AWS Prescriptive Guidance — hexagonal architecture pattern"
+    read: "Domain/application core, ports, adapters, and composition boundaries."
+  - where: "roj — packages/sdk/src/ports/ (session/event-store/runtime ports) + adapters"
+    read: "The same ports/adapters split for an agent SDK that runs on Bun, E2B, or local."
+---
+
+# Feature-split + light hexagonal
+
+## What it is
+
+The app is organized **by feature/domain** (`model/<feature>/` — pure logic, no
+platform imports), platform concerns sit behind **ports** (`ports/` — interfaces:
+storage, llm, actors, observability, schedule), implemented by **adapters**
+(`adapters/cloudflare/` for prod, `adapters/inmemory/` for tests), and an **app/**
+composition layer wires adapters into services (via the DI container) and exposes
+transport (HTTP/RPC/cron). Dependency direction is enforced: **domain → ports;
+adapters implement ports; nothing in `model/` imports an adapter or a CF value**.
+
+## When & why to use
+
+- Multiple targets/backends (cloud vs local, CF vs in-process, swappable LLM/storage providers).
+- You want the domain **testable without the platform SDK** — unit tests run on in-memory adapters (no CF account, fast).
+
+## When NOT to use
+
+- Single platform forever, no local testing — the indirection isn't worth it. Only pays off with ≥2 implementations of a port.
+
+## Gotchas
+
+- **Ports are interfaces** — don't add classes/subclasses; if it doesn't fit, add a port or an adapter method.
+- **Adapters are implementation details** — tests know only the port; `instanceof MapObjectStore` is a leak.
+- **Enforce the dependency direction in lint** — `model/**` may only `import type` from `cloudflare:workers`; never a value import or an `adapters/` import.
+- **Port signatures are a contract** — once multiple adapters + call sites depend on one, changing it is a breaking change; lock it with contract tests early.
+
+## Relationships — why
+
+- **recommends `di-container`** (wires adapters → domain services) and **`opice`** (the in-memory adapters make the running app cheap to drive in tests).