@fabrika/app 0.9.0-dev.11 → 0.9.0-dev.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/package.json +10 -10
  2. package/skill/SKILL.md +7 -5
  3. package/skill/references/app-setup.md +8 -8
  4. package/skill/references/endpoint.md +12 -4
  5. package/skill/references/files.md +11 -1
  6. package/skill/references/relations.md +558 -0
  7. package/skill/references/table-and-migration.md +30 -0
  8. package/src/contract/artifact-schema.ts +94 -5
  9. package/src/contract/build.ts +127 -34
  10. package/src/contract/compile.ts +1 -0
  11. package/src/contract/declaration.ts +8 -2
  12. package/src/contract/define.ts +18 -1
  13. package/src/contract/group.ts +12 -10
  14. package/src/contract/index.ts +2 -0
  15. package/src/contract/kit.ts +1 -0
  16. package/src/contract/platform.ts +1 -0
  17. package/src/contract/vocabulary.ts +3 -0
  18. package/src/dev/launcher.ts +14 -15
  19. package/src/dev/output.ts +8 -11
  20. package/src/files/kinds.ts +1 -1
  21. package/src/files/sniff.ts +18 -1
  22. package/src/files/treatment.ts +12 -10
  23. package/src/implement/boot.ts +33 -2
  24. package/src/implement/capability.ts +19 -4
  25. package/src/implement/client-address.ts +5 -71
  26. package/src/implement/dispatch.ts +117 -14
  27. package/src/implement/egress.ts +30 -12
  28. package/src/implement/implement.ts +7 -0
  29. package/src/implement/public.ts +3 -3
  30. package/src/jobs/report.ts +32 -5
  31. package/src/jobs/scrub.ts +1 -1
  32. package/src/testing/caller.ts +9 -2
  33. package/src/testing/endpoint-access.ts +2 -1
  34. package/src/testing/sample-file.ts +4 -1
  35. package/types/src/contract/declaration.d.ts +9 -1
  36. package/types/src/contract/define.d.ts +20 -1
  37. package/types/src/contract/group.d.ts +5 -3
  38. package/types/src/contract/index.d.ts +1 -0
  39. package/types/src/contract/vocabulary.d.ts +4 -1
  40. package/types/src/dev/output.d.ts +7 -6
  41. package/types/src/files/treatment.d.ts +4 -3
  42. package/types/src/implement/capability.d.ts +4 -4
  43. package/types/src/implement/client-address.d.ts +0 -5
  44. package/types/src/implement/dispatch.d.ts +11 -0
  45. package/types/src/implement/implement.d.ts +7 -0
  46. package/types/src/testing/caller.d.ts +1 -1
@@ -0,0 +1,558 @@
1
+ # references/relations.md — relation grants and conditions
2
+
3
+ A relation gives a role its actions at the nodes where a row of the application names the person: "the assistants of
4
+ this project, until their assignment ends". A condition (`when`) narrows an action to the rows it admits: "no task is
5
+ written in a project past its end". Both are declarations the approver reads; the data layer applies them to every
6
+ statement. This file is an application of its own (`tasks` with assistants); its `package.json`, `tsconfig.json`,
7
+ `src/app-kit.ts`, `src/app.ts` and `src/schemas.ts` are those of `app-setup.md` and `endpoint.md`.
8
+
9
+ Ask the human before you add a relation, a role's `via`, a table's `confers` or its `assign`: each lets someone reach
10
+ more, and the approver sees each as a widening. A `when` only narrows; removing or changing one widens. They need
11
+ `@fabrika/app` `0.9.0-dev.13` or later: Control refuses to publish them for an application pinned to an earlier release.
12
+
13
+ ## The vocabulary: a relation and a role's `via`
14
+
15
+ ```ts src/vocabulary.ts
16
+ import { defineVocabulary } from '@fabrika/app/contract'
17
+
18
+ export const vocabulary = defineVocabulary({
19
+ app: 'tasks',
20
+ dimensions: {
21
+ org: { members: { manage: 'members.manage', list: 'tasks.read' } },
22
+ project: { in: 'org' },
23
+ task: { in: 'project' },
24
+ },
25
+ actions: {
26
+ 'tasks.read': 'Read projects and tasks',
27
+ 'tasks.write': 'Create projects and tasks, and finish tasks',
28
+ 'assistants.assign': 'Assign an assistant to a project',
29
+ 'members.manage': 'Invite and remove members',
30
+ },
31
+ relations: {
32
+ assisting: { dimension: 'project' },
33
+ },
34
+ roles: {
35
+ owner: {
36
+ grants: ['tasks.read', 'tasks.write', 'assistants.assign', 'members.manage'],
37
+ member: { scope: 'org', assignableBy: ['owner'] },
38
+ },
39
+ coordinator: {
40
+ grants: ['tasks.read', 'assistants.assign'],
41
+ member: { scope: 'org', assignableBy: ['owner'] },
42
+ },
43
+ assistant: {
44
+ grants: [],
45
+ via: { assisting: ['tasks.read', 'tasks.write'] },
46
+ },
47
+ },
48
+ })
49
+ ```
50
+
51
+ - `relations: { <name>: { dimension } }` names a relation and the dimension of the node its rows name.
52
+ - `via: { <relation>: [<action>, …] }` on a role: a holder of the role holds those actions at each node where a source
53
+ row names them, and nowhere else. Its `grants` still hold globally, so an assistant's are empty.
54
+ - `via` is only for a global, internal role without `member`: IAM grants `assistant` application-wide (an operator,
55
+ in IAM's console), and the rows say where it applies. A grant of the role in a scope value carries no relation, so
56
+ the proxy refuses its holder (403). A person from outside the organization (`external: true`) holds no relation.
57
+ - The token says only that the role holds those actions through `assisting`. The data layer reads the source rows on
58
+ every statement, so an inserted row grants at the next request and a deleted one stops access at the next request.
59
+ Nothing caches it.
60
+ - A principal a row names reaches nothing unless IAM grants it a role whose `via` names the relation.
61
+
62
+ ## The migration
63
+
64
+ ```sql db/migrations/20261104090000_assistants.sql
65
+ CREATE TABLE projects (
66
+ id UUID PRIMARY KEY,
67
+ org_id TEXT NOT NULL,
68
+ name TEXT NOT NULL,
69
+ ends_at TIMESTAMPTZ,
70
+ created_by TEXT NOT NULL,
71
+ version INTEGER NOT NULL,
72
+ UNIQUE (id, org_id)
73
+ );
74
+ CREATE INDEX projects_org ON projects (org_id);
75
+
76
+ -- A condition's path follows a single-column foreign key: project_id carries one beside the composite key.
77
+ CREATE TABLE tasks (
78
+ id UUID PRIMARY KEY,
79
+ project_id UUID NOT NULL REFERENCES projects (id),
80
+ org_id TEXT NOT NULL,
81
+ title TEXT NOT NULL,
82
+ done BOOLEAN NOT NULL DEFAULT false,
83
+ created_by TEXT NOT NULL,
84
+ version INTEGER NOT NULL,
85
+ FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE
86
+ );
87
+ CREATE INDEX tasks_project ON tasks (project_id);
88
+
89
+ -- A relation source: each row names one principal at one project until it expires.
90
+ CREATE TABLE project_assistants (
91
+ id UUID PRIMARY KEY,
92
+ project_id UUID NOT NULL,
93
+ org_id TEXT NOT NULL,
94
+ principal_id TEXT NOT NULL,
95
+ expires_at TIMESTAMPTZ NOT NULL,
96
+ created_by TEXT NOT NULL,
97
+ FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE ON DELETE CASCADE
98
+ );
99
+ CREATE INDEX project_assistants_principal ON project_assistants (principal_id, project_id);
100
+ ```
101
+
102
+ - A source table is an ordinary child or dimension table with a principal column (`TEXT`, an IAM principal id), the
103
+ node column (by default the table's column of the relation's dimension: `project_id`) and, for a bounded
104
+ delegation, an expiry (`TIMESTAMPTZ NOT NULL`).
105
+ - Give it an index on `(principal, node)`. Every statement under the relation runs
106
+ `node in (select node from <source> where principal = $me …)`, and nothing creates the index for you.
107
+ - After the migration run `fabrika db migrate` and `fabrika db codegen` (on Cloudflare `codegen` only): the policies
108
+ below read the generated `columns`, its foreign keys and which columns are `NOT NULL`.
109
+
110
+ ## The policies
111
+
112
+ ```ts src/db/tables.ts
113
+ import { defineTables } from '@fabrika/db/tables'
114
+ import { vocabulary } from '../vocabulary'
115
+ import { columns } from './schema.generated'
116
+
117
+ export const tables = defineTables(vocabulary, columns)({
118
+ projects: {
119
+ scope: { dimension: 'project' },
120
+ actions: { read: 'tasks.read', insert: 'tasks.write' },
121
+ insert: ['name', 'ends_at'],
122
+ version: 'version',
123
+ createdBy: 'created_by',
124
+ },
125
+ tasks: {
126
+ scope: { dimension: 'task' },
127
+ actions: { read: 'tasks.read', insert: 'tasks.write', update: 'tasks.write' },
128
+ insert: ['title'],
129
+ update: ['done'],
130
+ version: 'version',
131
+ createdBy: 'created_by',
132
+ when: {
133
+ 'tasks.write': {
134
+ anyOf: [
135
+ { 'project_id.ends_at': { isNull: true } },
136
+ { 'project_id.ends_at': { gt: { now: true } } },
137
+ ],
138
+ },
139
+ },
140
+ },
141
+ project_assistants: {
142
+ scope: { child: 'projects' },
143
+ actions: {
144
+ read: 'tasks.read',
145
+ insert: 'assistants.assign',
146
+ delete: 'assistants.assign',
147
+ },
148
+ insert: ['principal_id', 'expires_at'],
149
+ createdBy: 'created_by',
150
+ confers: {
151
+ assisting: {
152
+ principal: 'principal_id',
153
+ expires: 'expires_at',
154
+ assign: { maxDays: 30 },
155
+ },
156
+ },
157
+ },
158
+ })
159
+ ```
160
+
161
+ ### `confers`: the rows that grant a relation
162
+
163
+ - `confers: { <relation>: { principal, node?, expires?, when?, assign? } }`. `node` defaults to the table's column of
164
+ the relation's dimension. A row confers nothing once `expires` passed, nor while its own `when` does not admit it.
165
+ A source's `when` never reads its `version`. It may follow one foreign key to the row the source names, such as
166
+ `{ 'person_id.active': { eq: true } }`, the far side of a many-to-many table: no update of that table may write the
167
+ column it tests, and the table is no view, queue or top-level dimension table. It takes no second foreign key and no
168
+ `some`. That table joins the source table among those `ctx.sql` of a writing endpoint never names, so a writing
169
+ statement that already names it fails at run time once the condition is added: move that write to `ctx.db` first.
170
+ - Inserting a row is delegation: the coordinator gives the assistant `tasks.read` and `tasks.write` without holding
171
+ `tasks.write` itself. The insert's own action (`assistants.assign`) decides who may write it, and the layer bounds
172
+ what it gives instead:
173
+ - the node is stamped from the writer's `Ref`, so a coordinator delegates only in a project it reaches;
174
+ - `assign.maxDays` caps the expiry; a later or a missing expiry is a 409, and `maxDays` needs `expires`;
175
+ - a row naming its writer is a 409 unless `assign.self: true` allows it. `principal` may name the table's
176
+ `createdBy`: then every row names its writer at the row's node. On `projects`, a relation at `project` makes a
177
+ creator hold it at that project, and one at `org` at the project's org; on a child table such as
178
+ `project_assistants` the writer holds it at the parent project, not at the row. So a table with an insert states
179
+ `assign: { self: true }`, and the policy is refused without it;
180
+ - a table that confers without `assign` takes no insert.
181
+ - `principal` may be read through one foreign key, `'<column>.<principal column>'`: `principal: 'person_id.principal_id'`
182
+ on a staff row that names a person of a directory table, whose own row holds the principal id. `<column>` needs a
183
+ single-column `REFERENCES <table> (id)` to the key of a contained dimension, child or application table (no view, no
184
+ queue table, no top-level dimension), and is not the source's own key, version, file or containment column (an
185
+ `org_id` a move rewrites). No other foreign key holds that column, but a composite one to the same row, such as
186
+ `(person_id, org_id) REFERENCES people (id, org_id)`, and the referenced table's key references nothing. No update of that table may write the principal column, so a person row is replaced, never edited:
187
+ deleting it, or the source row, ends the access at the next request. A row whose person names its writer is a 409
188
+ without `assign.self`, as above. The foreign key needs only the referenced table's key, not a key that holds the
189
+ tenant: a writer may name a person of another organization, which gives no more than naming that principal id
190
+ directly. Index the referenced table on `(principal column, id)` too.
191
+ - A column that holds a principal, on the source or on the table a path reads, has no `REFERENCES`: a key that
192
+ cascades on update would change whom every row names.
193
+ - A source row never moves, and no update writes its principal, node, expiry or a column its `when` reads. Change an
194
+ assignment by deleting the row and inserting a new one. `ctx.sql` of a writing endpoint never names a source table,
195
+ `unscoped` never writes one, and a queue table confers nothing.
196
+
197
+ ### `when`: a condition narrows an action
198
+
199
+ - `when: { <action>: <condition> }` is ANDed onto every grant of that action on the table: global, IAM-scoped and
200
+ through a relation alike. The owner cannot add a task to a project past its end either. A row the condition does
201
+ not admit is not there for that action: a read or an update `on` it is 404, a list leaves it out, and an insert
202
+ it refuses is a 409 with nothing written.
203
+ - A condition is data, never SQL: `{ <column>: { <operator>: <value> } }` with `eq`, `notEq`, `in`, `notIn`,
204
+ `isNull`, `lt`, `lte`, `gt` and `gte`; several columns in one object must all hold; `allOf`, `anyOf` and `not` stand
205
+ alone in their object. `{ now: true }` is the statement's clock (`{ gt: { now: true } }`), never the text `now`. A
206
+ JSON column is never compared: extract the value into a typed column.
207
+ - A path follows foreign keys: `'project_id.ends_at'` reads the task's project. The column needs a single-column
208
+ `REFERENCES <table> (id)`, and the hop must stay in the row's tenant: the row's own container or parent column, a
209
+ key into a reference table, or a key that holds every ancestor the two tables share (below). A view's path starts at
210
+ its parent column, which needs no foreign key.
211
+ - `{ some: { <table>: <condition> } }` holds when a row of `<table>` whose single-column foreign key names this row
212
+ meets the condition, `none` when no such row does: on `projects`, `{ some: { tasks: { done: { eq: false } } } }` is
213
+ a project with an open task. The rows' foreign key is held like a path's hop, so it keeps to the row's tenant, and
214
+ a key into a reference table is not followed back: `{ tag_id: { some: { project_tags: … } } }` would count every
215
+ tenant's rows that name the tag, so the policy refuses it.
216
+ - A path may end in `some` or `none`: on `tasks`, `{ project_id: { some: { project_tags: { 'tag_id.name': { eq:
217
+ 'urgent' } } } } }` is a task of a project tagged urgent, through the link table `project_tags`. A `null` foreign key
218
+ reaches no row, so neither `some` nor `none` holds there. A `some` nests in a `some`.
219
+ - A `not` follows a path only through columns declared `NOT NULL`, at any depth: on a null key the path's lookup
220
+ would turn on rows of every tenant. `{ not: { 'client_id.active': { eq: true } } }` with a nullable `client_id` is
221
+ refused and names the column: declare it `NOT NULL` in a migration and run `fabrika db codegen`, or say what a row
222
+ without a client gets, `{ anyOf: [{ client_id: { isNull: true } }, { 'client_id.active': { eq: false } }] }`. Like
223
+ the `not`, it leaves out a row whose client's `active` is null.
224
+ - A path follows at most three foreign keys, the path before a `some`, the `some` and every hop inside it counted
225
+ together. Each hop is one more subquery in every statement of the action; shorten a longer path with a stored column.
226
+ - An insert's condition is judged on the written row. One with a path runs in the insert's transaction, every row on
227
+ its paths locked `FOR SHARE` first, so nobody changes the project while the task goes in. An insert action's
228
+ condition may end a path in `some` (`{ project_id: { some: … } }`), whose rows are locked too. It takes no `none`,
229
+ no `some` under `not`, no `some` straight on the inserted row, and no `some` of the inserted table's own rows
230
+ (`{ project_id: { some: { tasks: … } } }` on `tasks`): a row inserted meanwhile could make the first two false,
231
+ nothing names the new row yet, and the last would count the new task itself, since the condition is judged after
232
+ the write. An upsert's conflict update is judged on the stored row.
233
+
234
+ ### A key that holds the tenant needs its ancestors NOT NULL
235
+
236
+ A path into another scoped table, other than the container or parent, and a `readThrough` follow a foreign key of
237
+ exactly the column and every ancestor the two tables share, `(team_id, org_id) REFERENCES teams (id, org_id)`, beside
238
+ the column's single-column key. Each ancestor column of that key must be `NOT NULL`: under SQL's matching a null
239
+ `org_id` skips the whole key, so a row written with one could point at another org's team. A policy over a nullable
240
+ one is refused and names the column: add a migration that sets it `NOT NULL`, then run `fabrika db migrate` and
241
+ `fabrika db codegen`, which writes the `notNull` list the policy is checked against.
242
+
243
+ ### `readThrough`, `reveals` and `memberReveals`
244
+
245
+ - `readThrough: { <dimension>: <column> }` lets a `Within` of a dimension outside the table's chain, or a relation at
246
+ it, read the row through that column's tenant-holding key: a task in a project, read by the members of the team its
247
+ `team_id` names. Every write still follows the task's containment, and no update writes the column. When the key
248
+ lives on the row's container, name the container's path from the row's own containment column:
249
+ `readThrough: { team: 'task_id.team_id' }` on a task's comments. The container declares `readThrough.team` through
250
+ a column of its own; the row follows it wherever the container's column points now. Such a table takes no reveal
251
+ matched through that path: declare the reveal on the container.
252
+ - `reveals: { <relation>: { to, actions, when? } }` on a table the relation reaches: such a row also gives the
253
+ relation `actions` (those its roles name in `via`) at its ancestor node in `to` while `when` admits the row: an
254
+ assignee of an open task reads its project. A reveal matched through `readThrough` on a table with an insert needs
255
+ `assign: {}` (or `{ self: true }`), because the writer picks the node.
256
+ - `memberReveals: { <own dimension>: { to, actions, when? } }`: a grant at the row's own node holds `actions` at its
257
+ ancestor in `to` too, for an `over` list's reads. Such a row is never written unscoped or by `ctx.sql`, and never
258
+ moves.
259
+ - A view under a parent takes none of them: it is read through its parent row, so a relation, a reveal, a member
260
+ reveal or a secondary path that reaches the parent reaches the view's rows of that parent.
261
+
262
+ ## The endpoints
263
+
264
+ ```ts src/projects/endpoints.ts
265
+ import { z } from 'zod/v4'
266
+ import { app } from '../app-kit'
267
+ import { Saved } from '../schemas'
268
+
269
+ const DAY_MS = 86_400_000
270
+ const NewProject = z.strictObject({
271
+ orgId: z.string().min(1).max(100),
272
+ name: z.string().min(1).max(200),
273
+ endsAt: z.iso.datetime().optional(),
274
+ })
275
+ const Assign = z.strictObject({
276
+ id: z.uuid(),
277
+ assistant: z.string().min(1).max(200),
278
+ days: z.int().min(1).max(30),
279
+ })
280
+ const Unassign = z.strictObject({ id: z.uuid(), assignment: z.uuid() })
281
+ const Assignment = z.strictObject({ id: z.uuid() })
282
+
283
+ export const projects = app.group({ callers: ['human'] }, (r) => ({
284
+ create: r.mutation({
285
+ input: NewProject,
286
+ output: Saved,
287
+ access: { action: 'tasks.write', in: 'org', from: 'orgId' },
288
+ })
289
+ .handle(({ input, ctx }) =>
290
+ ctx.db.target.projects.insert({
291
+ name: input.name,
292
+ ends_at: input.endsAt ?? null,
293
+ })
294
+ ),
295
+ assign: r.mutation({
296
+ input: Assign,
297
+ output: Assignment,
298
+ access: { action: 'assistants.assign', on: 'project', from: 'id' },
299
+ })
300
+ .handle(({ input, ctx }) =>
301
+ ctx.db.target.project_assistants.insert({
302
+ principal_id: input.assistant,
303
+ expires_at: new Date(Date.now() + input.days * DAY_MS),
304
+ })
305
+ ),
306
+ unassign: r.mutation({
307
+ input: Unassign,
308
+ output: Assignment,
309
+ access: { action: 'assistants.assign', on: 'project', from: 'id' },
310
+ })
311
+ .handle(async ({ input, ctx }) => {
312
+ await ctx.db.target.project_assistants.remove(input.assignment)
313
+ return { id: input.assignment }
314
+ }),
315
+ }))
316
+ ```
317
+
318
+ ```ts src/tasks/endpoints.ts
319
+ import { fromPage } from '@fabrika/app'
320
+ import { z } from 'zod/v4'
321
+ import { app } from '../app-kit'
322
+ import { Cursor, Saved, Versioned } from '../schemas'
323
+
324
+ const Task = z.strictObject({
325
+ id: z.uuid(),
326
+ title: z.string(),
327
+ done: z.boolean(),
328
+ version: z.int(),
329
+ })
330
+ const TaskPage = z.strictObject({
331
+ items: z.array(Task),
332
+ next: z.nullable(z.string()),
333
+ })
334
+ const ListTasks = z.strictObject({
335
+ projectId: z.uuid(),
336
+ after: Cursor.optional(),
337
+ })
338
+ const MyTasks = z.strictObject({ after: Cursor.optional() })
339
+ const NewTask = z.strictObject({
340
+ projectId: z.uuid(),
341
+ title: z.string().min(1).max(200),
342
+ })
343
+
344
+ export const tasks = app.group({ callers: ['human'] }, (r) => ({
345
+ list: r.query({
346
+ input: ListTasks,
347
+ output: TaskPage,
348
+ access: { action: 'tasks.read', in: 'project', from: 'projectId' },
349
+ })
350
+ .handle(async ({ input, ctx }) =>
351
+ fromPage(
352
+ Task,
353
+ await ctx.db.target.tasks.list({
354
+ orderBy: [['title', 'asc']],
355
+ after: input.after,
356
+ }),
357
+ )
358
+ ),
359
+ mine: r.query({
360
+ input: MyTasks,
361
+ output: TaskPage,
362
+ access: { action: 'tasks.read', over: 'project' },
363
+ })
364
+ .handle(async ({ input, ctx }) =>
365
+ fromPage(
366
+ Task,
367
+ await ctx.db.within.tasks.list({
368
+ where: [['done', '=', false]],
369
+ orderBy: [['title', 'asc']],
370
+ after: input.after,
371
+ }),
372
+ )
373
+ ),
374
+ create: r.mutation({
375
+ input: NewTask,
376
+ output: Saved,
377
+ access: { action: 'tasks.write', in: 'project', from: 'projectId' },
378
+ })
379
+ .handle(({ input, ctx }) =>
380
+ ctx.db.target.tasks.insert({ title: input.title })
381
+ ),
382
+ finish: r.mutation({
383
+ input: Versioned,
384
+ output: Saved,
385
+ access: { action: 'tasks.write', on: 'task', from: 'id' },
386
+ })
387
+ .handle(({ input, ctx }) =>
388
+ ctx.db.target.update({ done: true }, {
389
+ expectVersion: input.expectVersion,
390
+ })
391
+ ),
392
+ }))
393
+ ```
394
+
395
+ ```ts fabrika.contract.ts
396
+ import { app } from './src/app-kit'
397
+ import { projects } from './src/projects/endpoints'
398
+ import { tasks } from './src/tasks/endpoints'
399
+
400
+ export const contract = app.contract((c) => ({
401
+ api: c.rpc('/api', { projects, tasks }),
402
+ health: c.health('/healthz'),
403
+ }))
404
+ ```
405
+
406
+ - The handlers know nothing of relations. An assistant's `on`, `in` and `over` calls reach a project and its tasks
407
+ exactly while a row names it there. Elsewhere an `on` call is 404, an `in` call 403 and an `over` list leaves the
408
+ project out, as for any caller without the action there.
409
+ - `assign` takes the assistant's principal id from the input: that is the person picked, never the caller. `days`
410
+ stops at the policy's `maxDays`, so of the layer's bounds only the writer naming itself answers 409.
411
+
412
+ ## Tests
413
+
414
+ Grant the role app-wide (`{ role: 'assistant' }`, no scope), as IAM does, and let the endpoints write the rows:
415
+
416
+ ```ts src/__tests__/assistants.test.ts
417
+ import { createClient } from '@fabrika/app/client'
418
+ import { statusOf, testKit } from '@fabrika/app/testing'
419
+ import { testDatabase } from '@fabrika/db/testing'
420
+ import { afterAll, describe, expect, test } from 'bun:test'
421
+ import { contract } from '../../fabrika.contract'
422
+ import app from '../app'
423
+
424
+ const postgres = await testDatabase({
425
+ migrations: new URL('../../db/migrations/', import.meta.url),
426
+ label: 'assistants.test.ts',
427
+ })
428
+
429
+ if (postgres !== null) {
430
+ afterAll(() => postgres.close())
431
+ const kit = testKit(app, { database: postgres.database })
432
+ const acme = kit.scope('org', 'acme')
433
+ const assistant = kit.testCaller([{ role: 'assistant' }])
434
+ const coordinator = kit.testCaller([{ role: 'coordinator', scope: acme }])
435
+ const ownerApi = createClient(contract, 'api', {
436
+ fetch: kit.browser(kit.testCaller([{ role: 'owner', scope: acme }])),
437
+ })
438
+ const coordinatorApi = createClient(contract, 'api', {
439
+ fetch: kit.browser(coordinator),
440
+ })
441
+ const assistantApi = createClient(contract, 'api', {
442
+ fetch: kit.browser(assistant),
443
+ })
444
+
445
+ describe('an assistant', () => {
446
+ test('reaches a project only while a row names it there', async () => {
447
+ const launch = await ownerApi.projects.create({
448
+ orgId: 'acme',
449
+ name: 'Launch',
450
+ })
451
+ const other = await ownerApi.projects.create({
452
+ orgId: 'acme',
453
+ name: 'Other',
454
+ })
455
+ expect(await statusOf(assistantApi.tasks.list({ projectId: launch.id })))
456
+ .toBe(403)
457
+ const assignment = await coordinatorApi.projects.assign({
458
+ id: launch.id,
459
+ assistant: assistant.id,
460
+ days: 7,
461
+ })
462
+ const task = await assistantApi.tasks.create({
463
+ projectId: launch.id,
464
+ title: 'Brief',
465
+ })
466
+ expect((await assistantApi.tasks.mine({})).items.map((item) => item.id))
467
+ .toEqual([task.id])
468
+ expect(await assistantApi.tasks.finish({ id: task.id, expectVersion: 1 }))
469
+ .toEqual({ id: task.id, version: 2 })
470
+ expect(
471
+ await statusOf(
472
+ assistantApi.tasks.create({ projectId: other.id, title: 'No' }),
473
+ ),
474
+ ).toBe(403)
475
+ await coordinatorApi.projects.unassign({
476
+ id: launch.id,
477
+ assignment: assignment.id,
478
+ })
479
+ expect(
480
+ await statusOf(
481
+ assistantApi.tasks.finish({ id: task.id, expectVersion: 2 }),
482
+ ),
483
+ ).toBe(404)
484
+ expect((await assistantApi.tasks.mine({})).items).toEqual([])
485
+ })
486
+
487
+ test('a coordinator does not assign itself', async () => {
488
+ const project = await ownerApi.projects.create({
489
+ orgId: 'acme',
490
+ name: 'Self',
491
+ })
492
+ expect(
493
+ await statusOf(coordinatorApi.projects.assign({
494
+ id: project.id,
495
+ assistant: coordinator.id,
496
+ days: 1,
497
+ })),
498
+ ).toBe(409)
499
+ })
500
+
501
+ test('a grant of the role in a scope value reaches nothing through the relation', async () => {
502
+ const project = await ownerApi.projects.create({
503
+ orgId: 'acme',
504
+ name: 'Scoped',
505
+ })
506
+ const scoped = kit.testCaller([{ role: 'assistant', scope: acme }])
507
+ await coordinatorApi.projects.assign({
508
+ id: project.id,
509
+ assistant: scoped.id,
510
+ days: 1,
511
+ })
512
+ const scopedApi = createClient(contract, 'api', {
513
+ fetch: kit.browser(scoped),
514
+ })
515
+ expect(await statusOf(scopedApi.tasks.list({ projectId: project.id }))).toBe(
516
+ 403,
517
+ )
518
+ })
519
+ })
520
+
521
+ describe('a project past its end', () => {
522
+ test('is read, and takes no new task from anyone', async () => {
523
+ const ended = await ownerApi.projects.create({
524
+ orgId: 'acme',
525
+ name: 'Ended',
526
+ endsAt: '2026-01-01T00:00:00Z',
527
+ })
528
+ await coordinatorApi.projects.assign({
529
+ id: ended.id,
530
+ assistant: assistant.id,
531
+ days: 7,
532
+ })
533
+ expect((await assistantApi.tasks.list({ projectId: ended.id })).items)
534
+ .toEqual([])
535
+ expect(
536
+ await statusOf(
537
+ assistantApi.tasks.create({ projectId: ended.id, title: 'Late' }),
538
+ ),
539
+ ).toBe(409)
540
+ expect(
541
+ await statusOf(
542
+ ownerApi.tasks.create({ projectId: ended.id, title: 'Late' }),
543
+ ),
544
+ ).toBe(409)
545
+ })
546
+ })
547
+ }
548
+ ```
549
+
550
+ ## Not built yet
551
+
552
+ - No widening condition (`admits`): a `when` only narrows. A row that some other rule should open to more people is
553
+ reached by a grant, a relation or an off-road declaration, never by a condition.
554
+ - A relation holds only through a global grant of an internal role without `member`. A relation inside the node of a
555
+ scoped grant, and a relation for a person from outside the organization, are not built.
556
+ - A view is never a relation source: write the source rows to a table, under `assign`.
557
+ - An assignment never changes in place: delete the row and insert a new one.
558
+ - No raw SQL and no JSON column in a condition, and no path longer than three foreign keys.
@@ -328,3 +328,33 @@ export const tables = defineTables(vocabulary, columns)({
328
328
  - IAM already audits sign-ins (its auth log, refusals included) and every grant and revocation (its admin events
329
329
  `iam.grant.create` and `iam.grant.revoke`): do not rebuild either in the application. An operator's access to the
330
330
  database or to the provider's console is outside Fabrika.
331
+
332
+ ## A view read as a table
333
+
334
+ `fabrika db codegen` reads every view a migration creates (not a materialized view: read one with `ctx.sql`): its
335
+ interface is `<Pascal>View`, every column is `| null`, and its column list entry says `view: true`. A view needs no
336
+ policy; without one only `ctx.sql` reads it. With one, `ctx.db` reads it like a child table, typed and scoped, and nothing writes it:
337
+
338
+ - `scope: { child: '<parent>' }` puts it under its parent: the view selects the parent column (`<parent dimension>_id`,
339
+ or `column: '<name>'`), and needs none of the parent's chain columns. A view of one row per parent states
340
+ `key: '<parent column>'` (`{ child: 'deals', key: 'deal_id' }`), and a handler `on` the parent reads that row with
341
+ `ctx.db.target.<view>.get(ctx.target.value)`.
342
+ - `scope: { reference: '<why>' }` is a view every endpoint reads, through `ctx.db.reference.<view>`.
343
+ - A child view takes a `when` on its read actions, as a table does (`references/relations.md`): a path may start at
344
+ its parent column (`'deal_id.stage'`), though no foreign key declares it, and follows the parent's foreign keys from
345
+ there. The parent's own `when` does not narrow the view; state the view's. Every view column is nullable, so a
346
+ `not` over such a path is refused: state the condition without the `not`.
347
+ - It takes `actions: { read, appRead?, appCount? }`, column `read` actions and a child view's `when` only. `insert`, `update`, `delete`,
348
+ `version`, `createdBy`, `queue`, `files`, a column `write` and `unscoped: { <view>: 'write' }` are refused by tsc and
349
+ the checker; its handles' writes are `Unavailable`, and the data layer refuses them.
350
+ - Every read reaches a view's rows through the parent row their parent column names: a `Ref` of the parent, a
351
+ `Within` that reaches the parent (its relations and reveals included) and `ctx.db.within.<view>` wherever the
352
+ parent is listed, under the parent's own dimension too (a view of `deals` under a `Within` of `deal`). A row whose
353
+ parent column is null, or names a parent that does not exist or that the capability does not reach, is never read
354
+ through a `Ref` or a `Within`, one of every value included (only `ctx.db.app` lists every row of a view); a chain
355
+ column the view carries does not place a row. The view's SQL decides which parent each row names, and the approver
356
+ reviews it. `ctx.sql.scope` refuses a `Ref` or a `Within` of a view: read it through `ctx.db`.
357
+ - A column of a type the data layer does not read (an array, `numeric` on SQLite) is left out, and every codegen run
358
+ names it. On SQLite an expression has a type only through `CAST(… AS INTEGER | REAL | TEXT)`; on Postgres cast a
359
+ count you want as a number (`count(*)::int4`).
360
+ - `fabrika db test-scaffold` writes no policy isolation test for a view: its parent's cases cover the rows it reads.