@fabrika/builder 0.3.3 → 0.4.0

package/README.md

@@ -17,14 +17,15 @@ The current phase is derived from files in `.fabrika/`; it is not stored as a mu
 
 ## Usage
 
-Install the public CLI and initialize the builder in an application repository:
+Install the public CLI with this package, which it loads but does not install, and initialize the builder in an
+application repository:
 
 ```bash
-bun add --global @fabrika/cli
+bun add --global @fabrika/cli @fabrika/builder
 fabrika builder init
 ```
 
-Initialization installs the Fabrika skill for Claude Code and Codex, starts the local daemon, and opens the dashboard. The coding agent then drives the phase loop.
+Initialization installs the Fabrika skill and the `fabrika-app` application rules (from `@fabrika/app`) for Claude Code and Codex, starts the local daemon, and opens the dashboard. The coding agent then drives the phase loop.
 
 ```text
 fabrika builder next
@@ -70,6 +71,7 @@ Connected initialization uses `zerops-app` for a new project. A person approves
   issues/
 .claude/
 .agents/skills/fabrika/
+.agents/skills/fabrika-app/
 .codex/agents/
 tests/browser/*.test.ts
 ```

package/cli/src/commands/init.ts

@@ -74,6 +74,12 @@ export async function cmdInit(argv: string[]): Promise<number> {
 				+ `${support.written.length} installed, ${support.updated.length} updated, `
 				+ `${support.skipped.length} current, ${support.preserved.length} user-edited preserved`,
 		)
+		if (support.appSkill?.from === 'builder') {
+			console.error(
+				`[fabrika] the application has not installed @fabrika/app: installed the builder's fabrika-app rules `
+					+ `(${support.appSkill.version}); run bun install, then fabrika builder init again for the pinned version`,
+			)
+		}
 	} else {
 		console.error(`[fabrika] agent support: source dir not found, skipped installation`)
 	}

package/cli/src/inject-skills.ts

@@ -1,3 +1,4 @@
+import { APP_AGENT_SKILL_NAME, type AppAgentSkill, installedAppAgentSkill, readAppAgentSkill } from '@fabrika/app/agent-skill'
 import { createHash } from 'crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
 import { dirname, join, relative, resolve } from 'path'
@@ -21,9 +22,16 @@ function isAgentHost(value: string): value is AgentHost {
 	return value === 'claude' || value === 'codex'
 }
 
+/** Where the installed `fabrika-app` skill came from: the application's own `@fabrika/app`, or the builder's. */
+export interface AppSkillSource {
+	from: 'application' | 'builder'
+	version: string
+}
+
 export interface InjectResult {
 	sourceDir: string | null
 	hosts: AgentHost[]
+	appSkill: AppSkillSource | null
 	written: string[]
 	updated: string[]
 	skipped: string[]
@@ -72,6 +80,7 @@ export function injectAgentSupport(repoRoot: string, opts: InjectOptions = {}):
 	const result: InjectResult = {
 		sourceDir,
 		hosts,
+		appSkill: null,
 		written: [],
 		updated: [],
 		skipped: [],
@@ -80,7 +89,11 @@ export function injectAgentSupport(repoRoot: string, opts: InjectOptions = {}):
 	if (!sourceDir) return result
 
 	const root = resolve(repoRoot)
-	const desired = renderDesiredFiles(sourceDir, hosts)
+	// The application's pinned `@fabrika/app` is the version its code compiles against; before `bun install` there is none.
+	const pinned = installedAppAgentSkill(root)
+	const appSkill = pinned ?? readAppAgentSkill()
+	result.appSkill = { from: pinned === null ? 'builder' : 'application', version: appSkill.version }
+	const desired = renderDesiredFiles(sourceDir, hosts, appSkill)
 	const manifestPath = join(root, MANIFEST_RELATIVE_PATH)
 	const manifest = readManifest(manifestPath)
 
@@ -100,21 +113,25 @@ function normalizeHosts(hosts?: AgentHost[]): AgentHost[] {
 	return [...new Set(selected)].sort()
 }
 
-function renderDesiredFiles(sourceDir: string, hosts: AgentHost[]): DesiredFile[] {
+function renderDesiredFiles(sourceDir: string, hosts: AgentHost[], appSkill: AppAgentSkill): DesiredFile[] {
 	const skill = readFileSync(join(sourceDir, 'SKILL.md'), 'utf-8')
 	const agents = readAgentSources(join(sourceDir, 'agents'))
 	const resources = readSkillResources(sourceDir)
 	const files: DesiredFile[] = []
 
 	for (const host of hosts) {
-		const skillRoot = host === 'claude'
-			? join('.claude', 'skills', 'fabrika')
-			: join('.agents', 'skills', 'fabrika')
+		const skillsDir = host === 'claude' ? join('.claude', 'skills') : join('.agents', 'skills')
+		const skillRoot = join(skillsDir, 'fabrika')
 		files.push({
 			relativePath: join(skillRoot, 'SKILL.md'),
 			content: host === 'claude' ? renderClaudeSkill(skill) : skill,
 			host,
 		})
+		const appSkillRoot = join(skillsDir, APP_AGENT_SKILL_NAME)
+		files.push({ relativePath: join(appSkillRoot, 'SKILL.md'), content: appSkill.text, host })
+		for (const reference of appSkill.references) {
+			files.push({ relativePath: join(appSkillRoot, reference.path), content: reference.text, host })
+		}
 		for (const resource of resources) {
 			if (host === 'claude' && resource.relativePath === join('agents', 'openai.yaml')) continue
 			files.push({

package/daemon/src/platform-remote.ts

@@ -31,6 +31,11 @@ const environmentsSchema = z.object({
 		domain: storedTextSchema.nullable(),
 		publicOrigin: storedTextSchema.nullable(),
 		triggerRef: storedTextSchema.nullable(),
+		authoring: z.boolean(),
+		protected: z.boolean(),
+		publishedRunId: storedTextSchema.nullable(),
+		// A Control older than the field lists none.
+		deviations: z.array(storedTextSchema).default([]),
 		namespaceId: storedTextSchema.nullable(),
 		provider: storedTextSchema,
 		target: envelopeSchema,
@@ -44,7 +49,7 @@ const runSchema = z.object({
 	env: storedTextSchema,
 	ref: storedTextSchema,
 	commitSha: storedTextSchema.nullable(),
-	status: z.enum(['pending', 'running', 'succeeded', 'failed']),
+	status: z.enum(['pending', 'running', 'awaiting_approval', 'succeeded', 'failed']),
 })
 
 export async function boundedJson(response: Response): Promise<unknown> {

package/daemon/src/platform.ts

@@ -470,10 +470,13 @@ export class BuilderPlatform {
 					? 'Deployment succeeded. The configured URL has not been checked for reachability.'
 					: run.status === 'failed'
 					? 'Platform deployment failed. See the console for details.'
+					: run.status === 'awaiting_approval'
+					? 'The deployment changes access on a protected environment and waits for a person to approve it in the console.'
 					: 'Platform deployment is in progress.',
 			}
 			this.storage.saveProject(project)
-			if (terminal) return
+			// A parked run waits for a person, not for the platform; the builder key cannot approve it.
+			if (terminal || run.status === 'awaiting_approval') return
 			await this.sleep(3000, signal)
 		}
 		throw new ObservationError('Deployment polling timed out. Inspect the saved run in the platform console.')

package/decisions/patterns/zerops-control-deploy.md

@@ -13,6 +13,8 @@ sources:
     read: "Current Control deployment contract and provider lifecycle; do not infer builder command syntax."
   - where: "examples/zerops-app/README.md + fabrika.config.ts + zerops.yaml in fabrika-platform"
     read: "Application-owned source artifacts versus platform-owned deployment and secrets."
+  - where: "docs/decisions/0050-approved-access.md in fabrika-platform"
+    read: "The access snapshot Control reads from each commit, and which changes wait for a person's approval."
 ---
 
 # Deploy through installed Control
@@ -35,6 +37,12 @@ prerequisites are a handoff to that administrator.
 - Control and the Zerops provider supply credentials server-side, deliver source
   and trigger Zerops' build/deploy pipeline. The local coding agent does not need
   a Zerops account token or an installation provisioning credential.
+- Control reads the contract, `src/db/tables.ts` and the migration list from the
+  deployed commit and publishes only that approved snapshot to the proxy and IAM.
+  A widening (a new endpoint, caller, role grant, table policy change or migration)
+  on a protected environment (`prod` by default) parks the run in
+  `awaiting_approval` until a person approves it in the console. The agent cannot
+  approve; it reports the parked run and what the change lets someone do.
 - Follow the Control run to its terminal result and verify its requested revision
   and public proxy URL. A successful build, a trigger response or a local emulator
   result alone is not proof of a successful production release.

package/decisions/patterns/zerops-local-app.md

@@ -9,8 +9,10 @@ recommends: [tailwind, opice]
 conflicts: [single-worker-spa]
 status: wip
 sources:
-  - where: "examples/zerops-app/src/server.ts + src/app.ts + README.md in fabrika-platform"
-    read: "Bun backend composition and the limits of the example's local run instructions."
+  - where: "examples/zerops-app/fabrika.contract.ts + src/notes/endpoints.ts + src/app.ts + README.md in fabrika-platform"
+    read: "The contract's mounts, `serve` over the data layer, the SPA build, and the limits of the example's local run instructions."
+  - where: "docs/reference/application-runtime.md (Serving a contract, Testing a contract application) in fabrika-platform"
+    read: "The generated entrypoint, the framework variables `boot` needs, `testKit` and the generated tests."
   - where: "docs/reference/local-development.md + packages/local-stack/CLAUDE.md in fabrika-platform"
     read: "Real IAM/proxy/Postgres topology, local endpoints and IAM-owned login bypass."
   - where: "packages/local-stack/src/app-registration.ts in fabrika-platform"
@@ -19,16 +21,28 @@ sources:
 
 # Local Bun SPA and API
 
-Apply this to a client-rendered React/Buzola app served with its API by a Bun
-process. Use Bun-native asset bundling and Buzola codegen. API namespaces must
-return their own errors and 404s; only UI routes receive SPA fallback.
+Apply this to a client-rendered React/Buzola app served with its API by the
+generated Bun entrypoint of a contract application. The contract declares both:
+the SPA as `c.spa(prefix, { dir, access })`, served from the built asset
+directory for signed-in people, and the API as a `c.rpc` mount. An unknown
+procedure under an RPC prefix is 404, never the SPA. Use Bun-native asset bundling
+and Buzola codegen; the SPA's build commands are the only commands the authored
+`zerops.yaml` may add. The SPA reads no `import.meta.env` other than
+`FABRIKA_PUBLIC_*` and calls the API through `createClient(contract, 'api')` of
+`@fabrika/app/client`.
 
 ## Local composition to scaffold
 
 The development loop needs PostgreSQL, real IAM, a proxy with this application's
-gates and a private Bun upstream. Register the application's schema and exact
-local proxy return origin with local IAM. The app's configured issuer and audience
-must match the tokens IAM mints. Keep the local database and credentials separate
+endpoint table (`contractProxyTable` of the compiled contract) and a private Bun
+upstream started the way the platform starts it: `fabrika db migrate`, then
+`fabrika/entry.generated.ts` (`fabrika app build` writes it) with the framework
+variables `boot` refuses to start without: `FABRIKA_APP_ID`,
+`FABRIKA_APP_DATABASE_URL`, `FABRIKA_IAM_ISSUER`, `FABRIKA_IAM_APP_ID`,
+`FABRIKA_CONTRACT_DIGEST`, a `FABRIKA_PROXY_SECRET` of at least 32 characters that
+the proxy sends, and, for a `c.files` collection, `FABRIKA_APP_STORAGE_*`.
+Register the application's `schemaFromContract` schema and exact local proxy
+return origin with local IAM. Keep the local database and credentials separate
 from the installed production platform.
 
 Use the existing Fabrika local-stack composition as the reference. From the
@@ -37,12 +51,16 @@ services, and `bun run local:status` reports them. It pre-registers the fixture
 apps, not every new builder project. The public notes fixture is available at
 `http://notes.fabrika.localhost:18081` through its proxy.
 
-A new app needs its own documented local service wiring and registration; the
-example's bare server command does not provide those. Establish that wiring as
-the app's foundation work and verify it before reporting a working preview.
-If the local runtime cannot reach IAM, or a required registration cannot be made,
-report the missing prerequisite rather than adding fake auth or bypassing the
-proxy.
+A new app needs its own documented local service wiring and registration. Establish
+that wiring as the app's foundation work and verify it before reporting a working
+preview. If the local runtime cannot reach IAM, or a required registration cannot
+be made, report the missing prerequisite rather than adding fake auth or bypassing
+the proxy.
+
+Before the browser loop, run the application's own checks: `bun test` with
+`FABRIKA_TEST_POSTGRES_URL` set (a database test that skips proves nothing),
+`fabrika db test-scaffold` after every contract or table change, and
+`fabrika-check`.
 
 ## Preview and acceptance
 

package/decisions/patterns/zerops-postgres-seeds.md

@@ -11,16 +11,26 @@ status: stable
 sources:
   - where: "packages/builder/decisions/technologies/opice.md in fabrika-platform"
     read: "Scenario seeds metadata and its filename contract."
-  - where: "examples/zerops-app/src/migrate.ts + src/notes.ts in fabrika-platform"
-    read: "PostgreSQL access through Bun SQL and repeatable migration behavior."
+  - where: "examples/zerops-app/db/migrations/ + src/db/tables.ts in fabrika-platform"
+    read: "The application schema, its scope columns, and the table policies a seeded row must satisfy."
+  - where: "packages/cli/CLAUDE.md (the `db` area) in fabrika-platform"
+    read: "`fabrika db migrate` and its environment: `FABRIKA_APP_ID`, `FABRIKA_APP_DATABASE_URL`, schema `app_<id>`."
 ---
 
 # Named PostgreSQL fixtures
 
 Apply this to the preset's local PostgreSQL database. An opice scenario naming
-`seeds: ['example']` requires `seeds/example.sql`. Run migrations first, then apply
-the named SQL files through the application's PostgreSQL driver or `psql` before
-the scenario. Document that local seed command in the scaffold.
+`seeds: ['example']` requires `seeds/example.sql`. Run `fabrika db migrate` first,
+then apply the named SQL files with `psql` against the application's schema
+`app_<id>` (`SET search_path`) before the scenario. Document that local seed
+command in the scaffold. Seeds are a local test tool, not application code: the
+application reaches rows only through its scoped stores, and the checker refuses
+raw SQL and database drivers in it.
+
+A seeded row must look like one the data layer wrote: it carries its whole
+containment chain (every scope column of its table policy) and its `createdBy` and
+`version` columns where the policy names them, so the access forms find it in the
+scope the scenario's principal is granted.
 
 Use stable fixture IDs and PostgreSQL `INSERT ... ON CONFLICT` semantics so
 repeated application is safe. Tests that mutate fixtures must restore their

package/decisions/technologies/cloudflare-access.md

@@ -46,5 +46,5 @@ adopted native Propustka sessions.
 ## Relationships — why
 
 - **conflicts `propustka`** — current Propustka owns native SSO sessions and
-  in-process path gates; it no longer expects a Cloudflare Access edge.
+  request authorization; it no longer expects a Cloudflare Access edge.
 - **conflicts `auth-password-kv`** — both fill the `authentication` slot. Access = managed SSO; auth-password-kv = app-owned password+session. Pick one.

package/decisions/technologies/zerops-fabrika-auth.md

@@ -1,53 +1,72 @@
 ---
 id: zerops-fabrika-auth
 kind: technology
-title: Fabrika IAM with proxy-only enforcement on Zerops
+title: Fabrika IAM with contract enforcement at the proxy on Zerops
 slot: authz
 provides: [authentication, authorization, proxy-enforcement]
 requires: [zerops-platform]
 recommends: []
 conflicts: [propustka, cloudflare-access, auth-password-kv]
-npm: ["@fabrika/auth@^0.0.4", "@fabrika/auth-core@^0.0.4"]
+npm: ["@fabrika/app@^0.0.4", "@fabrika/db@^0.0.4", "zod@^3.25.76"]
 status: wip
 sources:
-  - where: "packages/auth/CLAUDE.md + src/index.ts + src/iam.ts in fabrika-platform"
-    read: "Verify-only SDK, real IAM requirements, negative versus unavailable results."
-  - where: "examples/zerops-app/fabrika.gates.ts + fabrika.schema.ts + src/authz.ts in fabrika-platform"
-    read: "Proxy gate declarations, app vocabulary and the example's direct JWKS verification."
+  - where: "packages/app/skill/SKILL.md in fabrika-platform (the `fabrika-app` skill)"
+    read: "The application rules: contract first, access forms, table policies, what the checker refuses, what is not built."
+  - where: "examples/zerops-app/src/vocabulary.ts + src/db/tables.ts + src/notes/endpoints.ts + fabrika.contract.ts in fabrika-platform"
+    read: "A worked contract: the vocabulary, the `/api` mount, the access forms and the handlers beside them."
+  - where: "docs/reference/application-runtime.md (Contracts, Serving a contract) in fabrika-platform"
+    read: "What the proxy and `boot` check per request, in order, and what `boot` refuses to start with."
   - where: "docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md + 0023-one-session-per-host.md in fabrika-platform"
-    read: "Single gate evaluator, per-host session handoff and application-owned object authorization."
+    read: "One evaluator at the proxy, the endpoint table, per-host session handoff."
 ---
 
-# Fabrika IAM with proxy-only enforcement
+# Fabrika IAM with contract enforcement at the proxy
 
-Declare the application's `AppSchema` vocabulary and ordered `AppGates` in source.
-Attach the gates to `target.proxy` in `fabrika.config.ts`. Control reconciles the
-schema and registers deployment return origins; the application does not assert
-its own trusted return origins through its schema.
+The application declares its whole access surface in `fabrika.contract.ts`:
+`defineContract(vocabulary, (c) => surface)` from `@fabrika/app/contract`. The
+vocabulary is its dimensions (e.g. `workspace` → `note`), exact action names and
+roles that list actions (no `*`). Every endpoint is a procedure under a mount
+(`c.rpc('/api', { callers: ['human', 'machine'] }, …)`) with an access form, plus
+`c.health('/healthz')`, which Zerops requires. There are no other routes,
+middleware, `authenticate` or custom server.
 
-The proxy alone evaluates gates, handles login and the reserved
-`/__fabrika/auth/callback` route, and injects `X-Fabrika-Token`. App services remain
-private. Never implement another gate evaluator in the app, frontend or Caddy
-route configuration.
+`fabrika.config.ts` compiles it with `compileContract(contract, tables)` and hands
+the provider the artifact (`target.contract`), the endpoint table
+(`target.proxy: { upstream, ...contractProxyTable(artifact) }`) and the IAM
+schema (`schema: schemaFromContract(artifact)`). The proxy reads only that
+endpoint table; its manifest parser refuses any other form. Control reads the
+contract from the deployed commit, and a widening on a protected environment
+(`prod` by default) waits for a person to approve it in the console.
 
-The application verifies the injected token's signature, issuer, audience and
-expiry against IAM's JWKS. Prefer the `@fabrika/auth` SDK's `createIam` and
-`authenticate` contract where its IAM binding is available; read the installed
-types when composing the HTTP transport. The public notes example demonstrates
-direct JWKS verification with `@fabrika/auth-core` claim parsing. Neither path
-trusts an unverified header or gives the app a session-to-token exchange.
+The proxy alone selects the endpoint, handles login and the reserved
+`/__fabrika/auth/callback` route, checks the caller kind and the requirement, and
+injects `X-Fabrika-Token` and `X-Fabrika-Endpoint`. App services stay private.
+Never implement a second enforcement decision in the app, the frontend or a Caddy
+route.
 
-Keep per-object authorization in feature handlers using the verified context and
-validated object scope (`can`, `requirePermission`, or the example's `Caller`).
-Public-gated routes use an anonymous context with no permissions. Preserve SDK
-failure semantics: a decided invalid credential differs from IAM unavailability,
-which refuses with 503 rather than pretending the credential was checked.
+The framework, not application code, verifies the injected token (signature,
+issuer, audience `<app>@<env>`, expiry), checks the proxy secret and the endpoint
+header, then the caller kind, the requirement, admission and the strict input.
+Per-object authorization is the access form: `on` (one object, 404 when missing
+or not the caller's), `over` (a list, `ctx.within`), `in` (creation inside a
+scope, 403 when not held). Handlers reach rows only through the stores of
+`src/db/tables.ts` with the `Ref` or `Within` they are handed; they never take an
+owner, user or tenant id from the input and never read `process.env`.
+
+On Zerops an endpoint with `creates`, `ctx.members` or `ctx.links` reaches IAM
+through the membership transport the platform writes (`FABRIKA_IAM_RPC_URL`,
+`FABRIKA_IAM_RPC_KEY`). The key only pins the application; the caller's token
+carries the authority, with the proxy's delegation grant for scope creation and
+membership changes.
 
 ## Local authentication is the same model
 
 Run real IAM and the proxy locally. IAM's own `LOCAL_DEV_LOGIN` mechanism can
 create a real local session; it is not an application dev flag. Restricted-role
 tests need real IAM principals and grants, not the bootstrap admin for every
-scenario. Never synthesize a caller, mint tokens in the app, add `FakeIamClient`,
-or disable gates to make local previews work. Credentials and raw request headers
-must not enter logs or committed fixtures.
+scenario. In unit tests, use `testKit` of `@fabrika/app/testing`, which runs the
+production proxy decision and `boot` with a stand-in IAM; never synthesize a
+caller in application code. When a request answers 401 or 403, report the missing
+action or role; never loosen the contract, a role or a table policy to make it
+pass. Credentials and raw request headers must not enter logs or committed
+fixtures.

package/decisions/technologies/zerops-platform.md

@@ -7,11 +7,13 @@ provides: [platform, private-services, managed-deploy]
 requires: [bun, postgres]
 recommends: []
 conflicts: [cloudflare]
-npm: ["@fabrika/provider-zerops@^0.0.4", "@fabrika/app@^0.0.4"]
+npm: ["@fabrika/provider-zerops@^0.0.4", "@fabrika/app@^0.0.4", "@fabrika/cli@^0.0.4"]
 status: wip
 sources:
   - where: "examples/zerops-app/fabrika.config.ts + zerops.yaml in fabrika-platform"
-    read: "Current defineApp shape, private runtime, database references and repository-root build descriptor."
+    read: "Current defineApp shape with `target.contract`, the private runtime and the locked repository-root descriptor."
+  - where: "packages/provider-zerops/src/execution.ts + CLAUDE.md in fabrika-platform"
+    read: "The generated build, start script, readiness check and crontab of a contract application."
   - where: "packages/provider-zerops/src/types.ts + src/index.ts in fabrika-platform"
     read: "Provider-owned authoring contract and exports; verify installed versions before use."
   - where: "docs/reference/zerops-platform.md in fabrika-platform"
@@ -25,40 +27,60 @@ Use this for applications deployed by an existing Fabrika installation. Import
 `@fabrika/provider-zerops`. Keep `fabrika.config.ts` as the app's deploy source of
 truth: stable `id`, `schema`, `pipeline` and `target` with `platform: 'zerops'`.
 
-## Application contract
+## Deploy configuration
 
 - Declare services through `target.services(ctx)`. Select the runtime explicitly
   with `target.deployService` when declaring multiple services. Set
   `target.zeropsSetup` to the matching setup in repository-root `zerops.yaml`.
-- Declare `target.proxy: { upstream, gates }` with the private runtime address.
-  Set runtime `enableSubdomainAccess: false`; only the namespace proxy has public
-  routing. A custom domain belongs on the proxy, never the app service.
+- A contract application hands `target.contract` (the compiled
+  `fabrika.contract.ts`) and `target.proxy: { upstream, ...contractProxyTable(artifact) }`
+  with the private runtime address (port 3000). Set runtime
+  `enableSubdomainAccess: false`; only the namespace proxy has public routing. A
+  custom domain belongs on the proxy, never the app service.
 - Leave project placement to Control's environment/namespace registry. Keep
   provider tokens and concrete project coordinates out of application source.
-- Use the public example's Bun adapter (`@fabrika/app/bun`) for the long-running
-  Fetch application. Serve built SPA assets from the private application; preserve
-  API errors instead of falling through to `index.html`.
-- Commit `zerops.yaml` and the Bun lockfile at the app repository root. Zerops
-  performs its build; the descriptor declares build/deploy files, start command,
-  ports and probes. Probe durations are Go duration strings bounded to 10s–1h.
-- Run repeatable, concurrency-safe PostgreSQL migrations in `run.initCommands`,
-  which runs on every container start. A readiness check gates deployment;
-  `run.healthCheck` is the separate runtime liveness mechanism.
+- The platform owns the setup of a contract application (ADR-0043). The authored
+  `zerops.yaml` keeps only `setup`, `build.base`, `build.os` and the SPA's
+  `build.buildCommands`; every other key is refused. The platform generates the
+  rest: a frozen install, the application's `bun test`, a reinstall, the
+  generated entrypoint, `fabrika-check`, `tsc`, the deploy gate on the contract's
+  health path, and the `run` section. Its start script runs `fabrika db migrate`,
+  `fabrika db codegen --verify` and `fabrika db test-isolation`, then
+  `fabrika/entry.generated.ts`; each `c.cron` job becomes a crontab entry
+  `fabrika job run <name>`. The build has no database, so the database tests skip
+  there and run at container start.
+- Commit the Bun lockfile at the app repository root, and commit what
+  `fabrika db codegen` and `fabrika db test-scaffold` write. Never edit a
+  generated file (`fabrika/entry.generated.ts`, `src/db/schema.generated.ts`, the
+  generated tests) by hand; regenerate it with its command.
 
 ## Data and configuration
 
 The default public config declares an app-owned PostgreSQL service. A cheap
 namespace can instead supply the typed shared PostgreSQL binding: consult
-`examples/zerops-app/fabrika.cheap.config.ts` and its matching descriptor before
-selecting that variant. Preserve the administrator's namespace assignment.
+`examples/zerops-app/fabrika.cheap.config.ts` before selecting that variant.
+Preserve the administrator's namespace assignment. A contract application has
+one PostgreSQL database: the platform writes `FABRIKA_APP_DATABASE_URL` (the TLS
+reference with the database name and `sslmode=require`) and `FABRIKA_APP_ID`, and
+the application's tables live in the schema `app_<id>`. The application names no
+connection string; `@fabrika/app/bun` opens the data layer for it.
 
-Use the provider's PostgreSQL TLS reference including the database name and
-`sslmode=require`; do not infer a connection string from a hostname. Service names
-must satisfy `^[a-z0-9]{1,25}$` and references may address only owned services and
-declared namespace resources.
+Service names must satisfy `^[a-z0-9]{1,25}$` and references may address only
+owned services and declared namespace resources.
 
 The provider owns isolation fields. Secret values live at service level in Zerops,
 not in config, YAML or project-level environment variables. `pipeline.secrets`
 names requirements; it does not add a deploy-time secret synchronization step.
-Control supplies reserved managed variables such as `FABRIKA_IAM_ISSUER`,
-`FABRIKA_OPERATIONS_DSN` and `FABRIKA_RELEASE`; do not redeclare them.
+Control supplies the reserved `FABRIKA_*` variables (`FABRIKA_IAM_ISSUER`,
+`FABRIKA_IAM_APP_ID`, `FABRIKA_OPERATIONS_DSN`, `FABRIKA_RELEASE`,
+`FABRIKA_CONTRACT_DIGEST`, `FABRIKA_PROXY_SECRET`, …); do not redeclare them. The
+framework takes every `FABRIKA_*` name out of the process before the application
+loads; handlers get their own variables through `deps`.
+
+A `c.files` collection needs one `object-storage` service in `fabrika.config.ts`;
+the provider writes `FABRIKA_APP_STORAGE_*` from it as references Zerops resolves,
+and refuses a second bucket.
+
+An endpoint with `creates`, `ctx.members` or `ctx.links` reaches IAM through the
+membership transport: the platform writes `FABRIKA_IAM_RPC_URL` and the
+environment's own `FABRIKA_IAM_RPC_KEY`, and refuses an app config that sets them.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/builder",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "Local-first guided application design and agent-assisted implementation.",
 	"license": "MIT",
@@ -47,13 +47,13 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/annotations": "^0.3.3",
-		"@fabrika/app": "^0.3.3",
-		"@fabrika/auth-core": "^0.3.3",
-		"@fabrika/canvas-kernel": "^0.3.3",
-		"@fabrika/control-contract": "^0.3.3",
-		"@fabrika/daemon-kit": "^0.3.3",
-		"@fabrika/provider-zerops": "^0.3.3",
+		"@fabrika/annotations": "^0.4.0",
+		"@fabrika/app": "^0.4.0",
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/canvas-kernel": "^0.4.0",
+		"@fabrika/control-contract": "^0.4.0",
+		"@fabrika/daemon-kit": "^0.4.0",
+		"@fabrika/provider-zerops": "^0.4.0",
 		"preact": "^10.25.0"
 	}
 }

package/shared/index.ts

@@ -30,7 +30,8 @@ export type BuilderPairingState =
 	| { status: 'connected' }
 
 export interface BuilderDeploymentState {
-	status: 'preparing' | 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
+	/** `awaiting_approval`: the deploy widens access on a protected environment and waits for a person (ADR-0050). */
+	status: 'preparing' | 'pending' | 'running' | 'awaiting_approval' | 'succeeded' | 'failed' | 'cancelled'
 	runId: string | null
 	commitSha: string | null
 	message: string | null
@@ -290,7 +291,7 @@ export const builderPairingStateSchema = z.discriminatedUnion('status', [
 	z.object({ status: z.literal('connected') }).strict(),
 ])
 export const builderDeploymentStateSchema = z.object({
-	status: z.enum(['preparing', 'pending', 'running', 'succeeded', 'failed', 'cancelled']),
+	status: z.enum(['preparing', 'pending', 'running', 'awaiting_approval', 'succeeded', 'failed', 'cancelled']),
 	runId: nonemptyStringSchema.nullable(),
 	commitSha: nonemptyStringSchema.nullable(),
 	message: nonemptyStringSchema.nullable(),

package/skill/agents/implementer.md

@@ -18,6 +18,8 @@ hints. Do not coordinate other issues and do not spawn more agents.
 1. Read the complete issue body, its dependency outputs, relevant
    `tests/browser/*.test.ts`, `.fabrika/architecture/tech.md`, and the absolute
    stack/decision sources supplied by the parent.
+   When the app has a `fabrika.contract.ts`, apply the `fabrika-app` skill and
+   follow its rules.
 2. Implement the smallest complete vertical slice required by `goal` and
    `satisfies`: route, data operation, UI, migration, and seed where applicable.
 3. Start the app using the selected stack's current run recipe. Apply the

package/stacks/zerops-app.md

@@ -1,7 +1,7 @@
 ---
 id: zerops-app
 title: "Platform-managed Zerops app — Bun + PostgreSQL + Fabrika IAM"
-goal: "Build and verify a local React/Buzola app behind real IAM and proxy gates, then deploy its available Git revision through installed Fabrika Control."
+goal: "Build and verify a local React/Buzola contract application behind real IAM and the proxy's endpoint table, then deploy its available Git revision through installed Fabrika Control."
 decisions:
   - zerops-platform
   - bun
@@ -31,8 +31,10 @@ Read installed contracts and the linked public examples before scaffolding.
 ## Composition
 
 - `zerops-platform` owns provider configuration and private runtime services.
-- `zerops-fabrika-auth` supplies IAM token verification and proxy-only gates.
-- `zerops-local-app` composes the Bun application, SPA and local IAM/proxy loop.
+- `zerops-fabrika-auth` supplies the contract (`fabrika.contract.ts`), which the
+  proxy enforces as an endpoint table and the framework serves through `serve`.
+- `zerops-local-app` composes the generated Bun entrypoint, the SPA mount and the
+  local IAM/proxy loop.
 - `zerops-control-deploy` defines the human/admin/agent deployment boundary.
 - `zerops-postgres-seeds` preserves opice's named SQL fixture contract on PostgreSQL.
 
@@ -52,15 +54,23 @@ or choose a replacement destination when prerequisites are missing.
 ## Local verification
 
 1. Install with Bun and typecheck the actual provider config and application.
-2. Start the app's documented local composition: PostgreSQL, IAM, proxy and Bun
-   runtime. Apply migrations and the scenario's PostgreSQL seeds locally.
+   After any change to the contract or `src/db/tables.ts`, run `fabrika db migrate`,
+   `fabrika db codegen` and `fabrika db test-scaffold`, and commit what they write.
+2. Start the app's documented local composition: PostgreSQL, IAM, proxy and the
+   generated Bun entrypoint. Apply migrations and the scenario's PostgreSQL seeds
+   locally.
 3. Open the app's **proxy URL**, complete IAM login, and run the targeted opice
    scenario against that URL. Verify denied access with a real restricted identity.
-4. Run application unit tests, typechecking and its production asset build.
-   Include the built assets in the root `zerops.yaml` deploy files.
+4. Run application tests with `FABRIKA_TEST_POSTGRES_URL` set, `fabrika-check`,
+   typechecking and the production asset build. The SPA's build commands go in
+   `build.buildCommands` of the root `zerops.yaml`; the platform generates every
+   other key and deploys the checked build.
 5. Report the actual local preview URL and checks. Production deployment follows
    `zerops-control-deploy`; a passing local test is not a successful remote run.
 
-The public notes example supplies the backend/config reference, not a ready-made
-SPA or arbitrary-project dev launcher. Scaffold and verify the local composition
+The public notes example (`src/vocabulary.ts`, `src/db/tables.ts`, the `src/notes/` slice,
+`fabrika.contract.ts`, `db/migrations/`, `src/app.ts` and its generated tests, plus an
+`attachments` file collection, a `purge` job and a minimal SPA) supplies the backend/config
+reference, not an arbitrary-project dev launcher. Its `AGENTS.md` carries the
+`fabrika-app` rules. Scaffold and verify the local composition
 described in `zerops-local-app` before claiming the application runs locally.