@fabrika/app 0.3.2 → 0.4.0

package/skill/references/tests.md

@@ -0,0 +1,305 @@
+# references/tests.md — generated tests, seeds and your own tests
+
+## The generated tests
+
+`bunx fabrika db test-scaffold` writes them from the contract and the table policies, and deletes the ones it no
+longer writes. Commit them; never edit, format or import them (`generated-test-hash`).
+
+- `src/db/__tests__/<table>.policy-isolation.test.ts`: the data layer keeps each table's rows in their scope.
+- `src/__tests__/endpoint-access.test.ts`: every `on` and `in` endpoint refuses another scope's object (404 or 403);
+  every `on` and `over` endpoint, and every `in` endpoint that declares `sql`, answers nothing of another scope; a
+  caller with only an endpoint's write action, plus what IAM requires of it (below), reaches its own object (200). An
+  `app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder.
+- Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
+  link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
+  7 days, and an organization's address is refused for an external role (`internal_mailbox`). So the caller of an endpoint with the dimension's `members.manage`
+  holds it on the object itself, with one role the assigned role's `assignableBy` names and the assigned role's
+  actions: the membership roles the input names, or every one of the dimension when it names none. The caller of an
+  endpoint that `issues` also holds the actions its link grants.
+
+Run them after every change of the contract or the tables. The platform runs them at every start, and the
+application is not ready until each passes. A failing generated test is a bug in the handler, the policy or the
+fixtures, never in the test: do not loosen access to make it pass. A case that throws instead of failing an
+assertion names what the generator could not build: an input the schema refuses, an input the handler refused (400),
+which the fixtures below supply, or a `SeedLimitError` of the seed (below). Do not reshape the contract or the schema
+around one; ask the human.
+
+## Fixtures and seeds
+
+`src/__tests__/endpoint-access.fixtures.ts` is yours, read statically (plain literals only):
+
+```ts src/__tests__/endpoint-access.fixtures.ts
+export const seeds = { 'api.tasks.close': { status: 'doing' } }
+export const members = { 'api.tasks.assign': ['assignee'] }
+```
+
+- `export const fixtures = { '<endpoint id>': { … } }` is an input for an endpoint whose schema the scaffold cannot
+  sample, such as a `regex` or a webhook's bind:
+  `{ 'webhooks.github.bind': { scope: 'acme', account: 'installation:1' } }`. The checker names each missing one,
+  and one of an endpoint that does not exist (`endpoint-fixture`). The access form's `from` field is
+  replaced by the seeded scope.
+- `members['<endpoint id>']` lists the input fields that name a picked person the handler checks with
+  `ctx.members.get` (`assign`'s `assignee`). The generated cases send a real member of the object's org there; without
+  it they send a sample, the handler answers 400, and the case fails.
+- `invitations['<endpoint id>']` and `links['<endpoint id>']` list the input fields that name an invitation an endpoint
+  cancels (`ctx.members.revoke(ctx.target, { invitationId })`) or a share link it revokes (`ctx.links.revoke(id)`):
+  `export const invitations = { 'api.members.cancel': ['invitationId'] }`. The generated cases send one their stand-in
+  IAM holds there: an invitation open in the object's value, a link of the endpoint's mount that the case's caller
+  issued. Without it they send a sample, IAM answers 404, and the case fails.
+- `seeds['<endpoint id>']` is the state its precondition needs, written into the row of the table that owns the
+  endpoint's dimension in both scopes: `close` answers 409 for an open task, so the seed makes it `doing`. A seed
+  sets neither a column that places the row nor a text column that holds a marker; a text column a CHECK lists the
+  values of, and a foreign key, it may set.
+- `rows['<endpoint id>']` names the input fields that address a row lying in the endpoint's object, with that row's
+  table: `export const rows = { 'api.tasks.editComment': { commentId: 'task_comments' } }`. The generated cases seed
+  one row of the table in each scope's object and send its key there. The table lies directly in the object: a child
+  table of the table that owns it, or a table it contains; the checker refuses a row further down
+  (`endpoint-fixture`). Without it they send a sample, the handler
+  finds no row (404), and the case fails.
+- The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
+- The seed of the tests fills every text column with a marker and every other required column with a sample of its
+  type: an enum's first label, `1`, `false`, today. A column with a `DEFAULT` keeps it (`status` is `open`). A column
+  a `CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside
+  the containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
+  reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a required
+  key to a dimension or child table outside the chain) fails the test with a `SeedLimitError` that names the
+  constraint: a limit of the generator, not a bug of the handler. Keep the column as the domain needs it, and ask the
+  human when the limit blocks the tests.
+- A generated case's input is a sample of the schema: no optional field, `null` for a nullable one, an enum's first
+  value, the shortest string its bounds admit (`'x'`), the smallest number, `false`, a fixed value for a format
+  (`uuid`, `email`, `iso.date`). When that input meets a precondition (`close` of an `open` task is 409), seed the
+  state, or give the whole input in `fixtures`.
+
+## Your own tests
+
+Test the rules of `logic.ts` as plain functions. Test a handler through `testKit` and the typed client, with each
+allowed call beside its refused twin:
+
+```ts src/tasks/__tests__/tasks.test.ts
+import { createClient } from '@fabrika/app/client'
+import { statusOf, testKit } from '@fabrika/app/testing'
+import { testDatabase } from '@fabrika/db/testing'
+import { afterAll, describe, expect, test } from 'bun:test'
+import { contract } from '../../../fabrika.contract'
+import app from '../../app'
+
+const postgres = await testDatabase({
+	migrations: new URL('../../../db/migrations/', import.meta.url),
+	label: 'tasks.test.ts',
+})
+
+if (postgres !== null) {
+	afterAll(() => postgres.close())
+	const kit = testKit(app, { database: postgres.database })
+	const acme = kit.scope('org', 'acme')
+	const inAcme = (role: 'owner' | 'member') =>
+		kit.testCaller([{ role, scope: acme }])
+	const owner = inAcme('owner')
+	const member = inAcme('member')
+	const ownerApi = createClient(contract, 'api', { fetch: kit.browser(owner) })
+	const memberApi = createClient(contract, 'api', { fetch: kit.browser(member) })
+
+	describe('tasks', () => {
+		test('an owner assigns a task and a member may not; the assignee sees it under mine', async () => {
+			const project = await ownerApi.projects.create({
+				orgId: 'acme',
+				name: 'Launch',
+			})
+			const task = await memberApi.tasks.create({
+				projectId: project.id,
+				title: 'Write the brief',
+			})
+			expect(
+				await statusOf(
+					memberApi.tasks.assign({
+						id: task.id,
+						expectVersion: 1,
+						assignee: member.id,
+					}),
+				),
+			).toBe(403)
+			expect(
+				await ownerApi.tasks.assign({
+					id: task.id,
+					expectVersion: 1,
+					assignee: member.id,
+				}),
+			).toEqual({ id: task.id, version: 2 })
+			expect((await memberApi.tasks.mine({})).items.map((item) => item.id))
+				.toEqual([task.id])
+		})
+
+		test('only a task in progress closes', async () => {
+			const project = await ownerApi.projects.create({
+				orgId: 'acme',
+				name: 'Ops',
+			})
+			const task = await memberApi.tasks.create({
+				projectId: project.id,
+				title: 'Rotate keys',
+				dueOn: '2026-10-20',
+			})
+			expect(
+				await statusOf(memberApi.tasks.close({ id: task.id, expectVersion: 1 })),
+			).toBe(409)
+			await memberApi.tasks.start({ id: task.id, expectVersion: 1 })
+			expect(await memberApi.tasks.close({ id: task.id, expectVersion: 2 }))
+				.toEqual({ id: task.id, version: 3 })
+		})
+
+		test("the member directory lists the org's members", async () => {
+			const listed = await memberApi.members.list({ orgId: 'acme' })
+			expect(listed.items.map((item) => item.principalId).sort()).toEqual(
+				[owner.id, member.id].sort(),
+			)
+		})
+
+		test('a member lists its orgs; a global grant lists none and says all', async () => {
+			expect(await memberApi.members.orgs()).toEqual({
+				all: false,
+				orgs: ['acme'],
+			})
+			const auditor = createClient(contract, 'api', {
+				fetch: kit.browser(kit.testCaller([{ action: 'tasks.read' }])),
+			})
+			expect(await auditor.members.orgs()).toEqual({ all: true, orgs: [] })
+		})
+
+		test('a caller of another org reaches nothing', async () => {
+			const project = await ownerApi.projects.create({
+				orgId: 'acme',
+				name: 'Secret',
+			})
+			const outsider = createClient(contract, 'api', {
+				fetch: kit.browser(
+					kit.testCaller([{
+						role: 'owner',
+						scope: { type: 'org', value: 'other' },
+					}]),
+				),
+			})
+			expect(
+				await statusOf(
+					outsider.tasks.create({ projectId: project.id, title: 'Not mine' }),
+				),
+			).toBe(403)
+			expect((await outsider.tasks.mine({})).items).toEqual([])
+		})
+	})
+}
+```
+
+- `testDatabase` migrates a throwaway schema; without `FABRIKA_TEST_POSTGRES_URL` it answers `null`, prints
+  `<label> skipped: set FABRIKA_TEST_POSTGRES_URL to run the Postgres-backed tests`, and the file registers no test.
+  A skip proves nothing. To confirm a file ran, run it alone (`bun test --isolate src/tasks`) and check that the pass
+  count is its number of tests, or set `FABRIKA_TEST_POSTGRES_REQUIRED=1`: a missing URL then fails the file.
+- `statusOf(call)` answers 200 when the call resolves and the status of the application's refusal otherwise; any other
+  failure (no answer, a bug in the test) is rethrown. Import it beside `testKit`; do not write your own.
+- `kit.testCaller(grants, { kind })` makes a caller: a grant is a role or an action, in one scope or global. A
+  membership role is granted in one value of its scope; an action without `scope` is a global grant, for which
+  `ctx.within.values` is `'all'` (`kit.testCaller([{ action: 'tasks.read' }])`). `kind: 'machine'` presents a `px_`
+  key (`createClient(contract, 'api', { fetch: kit.fetch, key: caller.key })`).
+- Build a scope you reuse with `kit.scope('org', 'acme')` (`acme` above). An object literal stored in a variable
+  widens its `type` to `string`, which tsc refuses as a grant's `scope`; a dimension the contract lacks is a type error.
+- A caller's `id` is `<kind>-<n>` and its `label` `<kind>-<n>@<app>.test`, `n` counting the kit's callers; pass
+  `{ id, label }` to fix either (`kit.testCaller(grants, { label: 'Ann' })`). The label is a `string`, only a link
+  holder's (`kind: 'link'`) is `null`; it is `ctx.principal.label`, and the directory's label where it shows labels.
+  Assert a stored label against `caller.label` or the directory's answer (`members.list` above), never against a
+  literal of the default form.
+- A human's `email` is `ctx.principal.email`: `<kind>-<n>@<app>.test` unless you pass `{ email }`, which the kit
+  lower-cases as IAM does (`kit.testCaller(grants, { email: 'Ann@Example.com' })` mails `ann@example.com`). A
+  `machine`, `app` or `link` caller's `email` is `null`. The SPA's `<prefix>/__fabrika-me.json` answers the caller's
+  label, email and actions in the kit as in production (`kit.browser(caller)('/__fabrika-me.json')`).
+- `kit.browser(caller)` and `kit.fetch` serve one origin, `https://<app>.test` (`kit.origin`). Call a route by its
+  path (`kit.browser(owner)('/api/tasks.get', { method: 'POST', … })`), never with another host.
+- An SPA mount is served from its built `dir` (`dist/web`) when the build exists, as the deploy serves it:
+  `kit.browser(owner)('/')` answers the built `index.html`, a file by its path, and every other path of the mount the
+  `index.html` again. Without a build it is an empty page. The directory is relative to the working directory, the
+  application root under `bun test`; pass `testKit(app, { root })` from elsewhere.
+- The kit stands in for IAM's membership operations. A member directory (`ctx.members.list()` and `get(id)`) answers
+  from the kit's own callers: everyone `testCaller` gave a membership role in that scope, labels only where the
+  dimension declares `directory: 'labels'` (or to a `members.manage` holder). `kit.testCaller(grants, { lastSignInAt })`
+  is a person who signed in then; a `members.manage` holder's `list(ref)` answers it, and `null` for everyone else. The
+  application's own directory (`ctx.members.list()` of an `app: true` endpoint) lists every caller holding a role of the
+  contract, by id. To list someone, make them a caller:
+  `kit.testCaller([{ role: 'member', scope: { type: 'org', value: 'acme' } }])`. A `creates` endpoint, member
+  management and share links answer under IAM's rules for the caller's grants, and a role they give or remove is live
+  from the caller's next request, as in IAM: the creator of a value holds its creator role, a removed member is
+  refused and no longer listed.
+- `kit.acceptInvitation(invitationId)` is the invited person accepting an invitation your handler opened
+  (`ctx.members.assign(ctx.target, { email }, role)`): it answers a new caller labelled by the address, holding the
+  role in that scope (an `external` person for an external role). Pass a caller to make an existing person the
+  member: `kit.acceptInvitation(invitationId, member)`. It throws as IAM refuses: an invitation that is not open, an
+  external person and a role not declared external (`not_eligible`), an inviter that has since lost the authority to
+  give the role (`not_allowed`).
+
+```ts src/members/__tests__/members.test.ts
+import { createClient } from '@fabrika/app/client'
+import { statusOf, testKit } from '@fabrika/app/testing'
+import { testDatabase } from '@fabrika/db/testing'
+import { afterAll, expect, test } from 'bun:test'
+import { contract } from '../../../fabrika.contract'
+import app from '../../app'
+
+const postgres = await testDatabase({
+	migrations: new URL('../../../db/migrations/', import.meta.url),
+	label: 'members.test.ts',
+})
+
+if (postgres !== null) {
+	afterAll(() => postgres.close())
+	const kit = testKit(app, { database: postgres.database })
+	const owner = kit.testCaller([{
+		role: 'owner',
+		scope: kit.scope('org', 'acme'),
+	}])
+	const ownerApi = createClient(contract, 'api', { fetch: kit.browser(owner) })
+
+	test('an invited person accepts and is listed; once removed, it is refused', async () => {
+		const { invitationId } = await ownerApi.members.invite({
+			orgId: 'acme',
+			email: 'ann@example.test',
+			role: 'member',
+		})
+		const ann = kit.acceptInvitation(invitationId)
+		const annApi = createClient(contract, 'api', { fetch: kit.browser(ann) })
+		expect(
+			(await annApi.members.list({ orgId: 'acme' })).items.map((item) =>
+				item.principalId
+			),
+		)
+			.toContain(ann.id)
+		await ownerApi.members.remove({ orgId: 'acme', principalId: ann.id })
+		expect(await statusOf(annApi.members.list({ orgId: 'acme' }))).toBe(403)
+	})
+}
+```
+
+- `testKit(app, { membership })` replaces the stand-in with your own `IamMembershipRpc`; that kit accepts no
+  invitation. `@fabrika/app/testing` exports the types of the options: `IamMembershipRpc` (`membership`),
+  `ChallengeFetch` (`challengeFetch`) and `FileScanner` (`scanner`). Import them from there, beside `testKit`.
+- `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
+  with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
+  a session, 403 for a key).
+- `kit.runJob('<job>')` runs a cron job once and answers `{ status: 'succeeded', attempts }`.
+- An application with files passes `files: new MemoryFileObjects()` (`@fabrika/platform/testing`) to `testKit`;
+  without it the application does not boot. With `scan: true`, an upload stays `quarantined` until
+  `kit.runJob(FILE_SCAN_JOB)` (`@fabrika/app/implement`) runs with a `scanner` passed to `testKit`: a `FileScanner`
+  stand-in, or the real ClamAV one, `clamscanScanner()` of `@fabrika/app/bun`.
+- A form's challenge token is single use: a second submission with the same token answers 400 `challenge_failed`,
+  also when the test's `challengeFetch` answers success. Send a fresh token with each submission
+  (`crypto.randomUUID()`).
+- `testKit` takes no `deps`, and a test may not start a server (`Bun.serve` is `forbidden-global`). Stand in for an
+  outbound dependency through its variables: `env` points it at a test URL, and `spyOn(globalThis, 'fetch')` answers
+  that URL only and passes every other request on (`src/__tests__/mail-stand-in.ts` in `references/public-intake.md`).
+- `defineDeps(build)` runs at every boot, the generated tests' too, which set no application variable: read a variable
+  where it is used, not in `build` (`references/public-intake.md`). A handler that calls an outbound dependency fails its
+  generated cases with 500, so an endpoint they cover writes an outbox row a job sends (`references/endpoint.md`).
+- Run with `bun test --isolate`: the generated test boots the same application, and its data layer binds once per
+  process. Import the test kits from test files only (`test-only-import`).
+- No `.skip`, `.only` or test without an assertion, and no `mock.module` of `bun:test` or `@fabrika/*`.
+
+## Clicking through the screens
+
+`bunx fabrika app dev` serves the application through the same kit, seeded by `dev/seed.ts`, with a caller picker at
+`/__fabrika/dev` and a toolbar on every SPA page: `references/dev.md`.

package/skill/references/webhooks-links-connectors.md

@@ -0,0 +1,190 @@
+# references/webhooks-links-connectors.md — webhooks, share links and connectors
+
+Each of these lets someone in who is not a signed-in member of the scope. Ask the human before you add one, and say
+what it lets that caller do.
+
+## Webhooks (GitHub)
+
+```ts src/github/endpoints.ts
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+
+const RepositoryEvent = z.strictObject({
+	action: z.string(),
+	repository: z.strictObject({ full_name: z.string().max(200) }),
+})
+
+/** A repository created in the bound GitHub account becomes a project of the org the binding is for. */
+export const github = app.webhook('/hooks/github', {
+	scheme: 'github-sha256',
+	boundTo: 'org',
+	actions: ['tasks.write'],
+	input: RepositoryEvent,
+})
+	.handle(async ({ input, ctx }) => {
+		if (input.action !== 'created') return
+		await ctx.db.in(ctx.refs['tasks.write']).projects.insert({
+			name: input.repository.full_name,
+		})
+	})
+```
+
+- Mount it by name in the contract: `github,` beside `api`. It answers `POST /hooks/github/:bindingId`.
+- `boundTo` is a dimension with `members`. A holder of its `members.manage` binds an org to a GitHub account with the
+  generated `POST /api/webhooks.github.bind` (`{ scope, account: 'installation:<id>' | 'repository:<id>' }`), which
+  answers the secret and the URL once. The generated tests need a fixture for it (`references/tests.md`).
+- The framework checks the signature, the account and the input (undeclared fields are dropped).
+  `ctx.refs['<action>']` is a `Ref` of the bound org for each declared action.
+- It records the delivery key (a digest of the binding and the body) before the handler runs, and answers a body it
+  already ran in the last 30 days without running it again. A handler that throws commits nothing, and the key is
+  forgotten, so GitHub's redelivery runs it again from nothing. A process that dies after the record and before the
+  commit keeps the key and loses the delivery. So make every effect idempotent, and key an external effect after the
+  data work on `ctx.delivery.key`; never rely on exactly one run.
+
+## Share links
+
+```ts src/sharing/endpoints.ts
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+import { TaskStatus } from '../schemas'
+
+const ShareTask = z.strictObject({ id: z.uuid(), days: z.int().min(1).max(30) })
+const Shared = z.strictObject({ url: z.string() })
+const SharedTask = z.strictObject({ title: z.string(), status: TaskStatus })
+
+export const sharing = app.group({ callers: ['human'] }, (r) => ({
+	share: r.mutation({
+		input: ShareTask,
+		output: Shared,
+		access: { action: 'tasks.write', on: 'task', from: 'id' },
+		issues: 'shared',
+	})
+		.handle(async ({ input, ctx }) => ({
+			url:
+				(await ctx.links.issue(ctx.target, { mount: 'shared', days: input.days }))
+					.url,
+		})),
+}))
+
+export const shared = app.link('/s', {
+	spa: 'dist/share',
+	dimension: 'task',
+	grants: ['tasks.read'],
+	issuedBy: 'tasks.write',
+	maxDays: 30,
+	procedures: (l) => ({
+		task: l.query({ output: SharedTask, access: { action: 'tasks.read' } })
+			.handle(async ({ ctx }) => {
+				const task = await ctx.db.target.get()
+				return { title: task.title, status: task.status }
+			}),
+	}),
+})
+```
+
+- Mount both: `api: c.rpc('/api', { …, sharing })` and `shared,`. The link's procedures are `POST /s/api/<name>` and
+  its SPA is served under `/s/`.
+- The issuing endpoint declares `issues: '<mount>'` and its action is the mount's `issuedBy`. IAM binds the key to the
+  task's whole chain; the answer is `<prefix>/#<key>`, and a moved task's key reaches nothing.
+- The share SPA reads the key with `shareKey()` of `@fabrika/app/client` and calls
+  `createClient(contract, 'shared', { key })`. Never read `location.hash`.
+- Issue the link after the data work: IAM does not roll back with the transaction.
+- `ctx.links.issue` answers `{ id, url, expiresAt }`. A holder of that link calls with `ctx.principal.kind === 'link'`
+  and `ctx.principal.credentialId` equal to that `id`, so a row that stores the `id` finds what the link was issued
+  for. Keep the `id` (never the key) to end the link later with `ctx.links.revoke(id)`, which the same `issues` declaration gives; its issuer or a holder of `members.manage` on its
+  chain may. A revoked link still works until the proxy's token for it expires, at most 5 minutes.
+- A link procedure acts on the link's own object (`ctx.db.target`), with no `from` and no id in its input. A link
+  that should work once records its use in the row: a `verify` sets `verified_at` once under `getForUpdate`, and a
+  second call answers the same. IAM counts no uses.
+- A cron job may issue links too (`issues` on `app.cron`, `references/jobs.md`): a visitor without an account gets a
+  link by e-mail from a job that drains a form's inbox. `references/public-intake.md` is that recipe end to end, with
+  the files a link holder uploads (`link: true`, or `link: ['<mount>']` for some mounts only, `references/files.md`).
+
+## Connectors: another application's data
+
+A consumer imports an owner's export. The snapshot comes from Control, so this step needs an operator's credential,
+not the application's: `FABRIKA_CONTROL_URL` (or `--url=<control origin>`) and `FABRIKA_CONTROL_KEY`, a machine key
+that holds `deploy.read` on the consumer, both in the shell that runs the command only. Ask the human for them; they
+are CLI credentials, never application variables, and never committed.
+
+```bash
+bunx fabrika connect add catalog/products@1 --consumer=tasks --env=prod    # writes fabrika/connect/catalog.products.v1.ts
+bunx fabrika connect pull catalog/products@1 --consumer=tasks --env=prod   # refreshes it from what the owner approved now
+```
+
+The kit takes the snapshot, and an endpoint that calls it declares `connect`:
+
+```ts src/app-kit.ts
+import { defineApp } from '@fabrika/app/contract'
+import { catalogProductsV1 } from '../fabrika/connect/catalog.products.v1'
+import { tables } from './db/tables'
+import { vocabulary } from './vocabulary'
+
+export const app = defineApp(vocabulary, tables, {
+	imports: { catalog: { snapshot: catalogProductsV1, procedures: ['get'] } },
+})
+```
+
+```ts src/products/endpoints.ts
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+
+const BySku = z.strictObject({
+	orgId: z.string().min(1).max(100),
+	sku: z.string().min(1).max(64),
+})
+const ProductName = z.strictObject({
+	name: z.nullable(z.string()),
+	status: z.enum(['found', 'missing', 'unavailable']),
+})
+
+export const products = app.group({ callers: ['human'] }, (r) => ({
+	name: r.query({
+		input: BySku,
+		output: ProductName,
+		access: { action: 'tasks.read', in: 'org', from: 'orgId' },
+		connect: ['catalog'],
+	})
+		.handle(async ({ input, ctx }) => {
+			const product = await ctx.connect.catalog.get({ sku: input.sku })
+			if (product.outcome !== 'ok') return { name: null, status: 'unavailable' }
+			return product.value === null
+				? { name: null, status: 'missing' }
+				: { name: product.value.name, status: 'found' }
+		}),
+}))
+```
+
+- A call never throws for the owner's answer and never becomes an HTTP error by itself: it resolves to an outcome,
+  `ok`, `denied`, `invalid_input`, `unavailable`, `timeout` or `contract_violation`. Decide what each one answers, as
+  the example does: a missing product and an unreachable owner are different answers.
+- Exports are read-only and carry no per-user data. When the export you need does not exist, ask the owner
+  application's maintainer. The platform writes `FABRIKA_CONNECT_*`; never read or set them.
+
+The owner side is an export, mounted under `exports` in the contract. Its procedures run read-only for the consumer
+applications it names:
+
+```ts src/billing/endpoints.ts
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+
+const ProjectCount = z.strictObject({ projects: z.int() })
+
+export const projectCounts = app.export({
+	version: 1,
+	consumers: ['billing'],
+	audience: 'any consumer user',
+	procedures: (e) => ({
+		count: e.query({
+			output: ProjectCount,
+			access: { action: 'tasks.read', over: 'org' },
+		})
+			.handle(async ({ ctx }) => ({
+				projects: await ctx.db.within.projects.count(),
+			})),
+	}),
+})
+```
+
+Change a published export only by adding to it (a new procedure, a new optional input field) or by a new version
+served beside the old one.

package/src/agent-skill.ts

@@ -0,0 +1,77 @@
+// @fabrika/app/agent-skill — the one source of the rules every agent that writes an application reads: the builder
+// installs `skill/` as a skill, Control's MCP server answers it from `get_app_rules`, and the template's AGENTS.md is
+// `renderAgentsFile`. Reads files of a package, so only Bun or Node code imports it.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const APP_AGENT_SKILL_NAME = 'fabrika-app'
+
+const SKILL_DIR = fileURLToPath(new URL('../skill', import.meta.url))
+const SKILL_FILE = 'SKILL.md'
+const REFERENCES_DIR = 'references'
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n+/
+const VERSION_LINE = /^version: (\S+)$/m
+
+export interface AppAgentSkillReference {
+	/** The file's path in the skill directory, `references/<topic>.md`: the path `SKILL.md` names it by. */
+	readonly path: string
+	/** The topic `get_app_rules` answers it under: its file name without `.md`. */
+	readonly topic: string
+	readonly text: string
+}
+
+export interface AppAgentSkill {
+	/** The `version` of the frontmatter: the version of the `@fabrika/app` that ships it. */
+	readonly version: string
+	/** The whole `SKILL.md`, frontmatter included: what a skill directory holds. */
+	readonly text: string
+	/** `SKILL.md` without the frontmatter. */
+	readonly body: string
+	/** The reference files, by path. */
+	readonly references: readonly AppAgentSkillReference[]
+}
+
+/** The skill of this package. */
+export function readAppAgentSkill(): AppAgentSkill {
+	return readAppAgentSkillAt(SKILL_DIR)
+}
+
+/** The skill in `skillDir`, the `skill/` directory of an installed `@fabrika/app`. */
+export function readAppAgentSkillAt(skillDir: string): AppAgentSkill {
+	const text = readFileSync(join(skillDir, SKILL_FILE), 'utf-8')
+	const frontmatter = FRONTMATTER.exec(text)
+	if (frontmatter === null) throw new Error('@fabrika/app: skill/SKILL.md has no frontmatter')
+	const version = VERSION_LINE.exec(frontmatter[1] ?? '')?.[1]
+	if (version === undefined) throw new Error('@fabrika/app: skill/SKILL.md has no version in its frontmatter')
+	const referencesDir = join(skillDir, REFERENCES_DIR)
+	const names = existsSync(referencesDir) ? readdirSync(referencesDir).filter((name) => name.endsWith('.md')).sort() : []
+	const references = names.map((name) => ({
+		path: `${REFERENCES_DIR}/${name}`,
+		topic: name.slice(0, -'.md'.length),
+		text: readFileSync(join(referencesDir, name), 'utf-8'),
+	}))
+	return { version, text, body: text.slice(frontmatter[0].length), references }
+}
+
+/**
+ * The skill of the `@fabrika/app` an application installed: the nearest `node_modules/@fabrika/app` from `appRoot`
+ * up, as Bun resolves the package. `null` when the application has not installed it.
+ */
+export function installedAppAgentSkill(appRoot: string): AppAgentSkill | null {
+	let directory = appRoot
+	for (;;) {
+		const skillDir = join(directory, 'node_modules', '@fabrika', 'app', 'skill')
+		if (existsSync(join(skillDir, SKILL_FILE))) return readAppAgentSkillAt(skillDir)
+		const parent = dirname(directory)
+		if (parent === directory) return null
+		directory = parent
+	}
+}
+
+/** The `AGENTS.md` of an application repository: the skill's body, then each reference file. */
+export function renderAgentsFile(skill: AppAgentSkill): string {
+	const marker = `<!-- Generated from skill/ of @fabrika/app ${skill.version}. Change those files, not this one. -->\n\n`
+	return marker + [skill.body, ...skill.references.map((reference) => reference.text)].join('\n---\n\n')
+}

package/src/build.ts

@@ -0,0 +1,53 @@
+// @fabrika/app/build — the generated entrypoint of a contract application, which `fabrika app build` writes. It is
+// the only module that reads `process.env` and the only caller of `boot`, through the runtime adapter, and it imports
+// the application only after the adapter took the framework's variables out of the process.
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+/** An application root with this file is a contract application. The paths equal `@fabrika/check`'s layout. */
+export const CONTRACT_FILE = 'fabrika.contract.ts'
+
+/** Relative to the application root. */
+export const GENERATED_ENTRY_FILE = 'fabrika/entry.generated.ts'
+
+/** The module whose default export is `serve(contract, …)`, relative to the application root. */
+export const IMPLEMENTATION_FILE = 'src/app.ts'
+
+export type EntryRuntime = 'bun' | 'cloudflare'
+
+const HEADER = '// @generated by `fabrika app build` from src/app.ts. Do not edit: every build rewrites it.'
+
+/** The entrypoint source for one runtime. */
+export function generatedEntry(runtime: EntryRuntime): string {
+	switch (runtime) {
+		case 'bun':
+			return [
+				HEADER,
+				"import { markProductionProcess, serveContract } from '@fabrika/app/bun'",
+				'',
+				'// The test kits refuse to load from here on; the application is imported only after the framework took its variables.',
+				'markProductionProcess()',
+				"await serveContract(() => import('../src/app'), process.env)",
+				'',
+			].join('\n')
+		case 'cloudflare':
+			return [
+				HEADER,
+				"import { createContractWorker, markProductionProcess } from '@fabrika/app/cloudflare'",
+				'',
+				'// The test kits refuse to load from here on; the application is imported only after the framework took its variables.',
+				'markProductionProcess()',
+				"export default createContractWorker(() => import('../src/app'))",
+				'',
+			].join('\n')
+	}
+}
+
+/** Writes the entrypoint under `root` and returns its path. */
+export async function writeGeneratedEntry(root: string, runtime: EntryRuntime): Promise<string> {
+	const path = join(root, GENERATED_ENTRY_FILE)
+	await mkdir(dirname(path), { recursive: true })
+	await writeFile(path, generatedEntry(runtime))
+	return path
+}