@tapedb/tapedb 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,691 @@
1
+ interface StorageObject {
2
+ id: string;
3
+ key: string;
4
+ size: number;
5
+ etag: string;
6
+ contentType: string;
7
+ }
8
+ interface StorageClient {
9
+ upload(path: string, file: Blob, signal?: AbortSignal): Promise<StorageObject>;
10
+ download(path: string, signal?: AbortSignal): Promise<Blob>;
11
+ delete(path: string, signal?: AbortSignal): Promise<void>;
12
+ }
13
+ type StorageFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
14
+
15
+ /**
16
+ * Types for the client runtime: engine query documents, wire ops, outbox
17
+ * entries and the runtime facade the model client drives. They mirror the
18
+ * engine's wire contracts without importing the engine, so the client bundle
19
+ * stays free of server code.
20
+ */
21
+ type AttributeType$1 = "string" | "number" | "boolean" | "date" | "json" | "any";
22
+ interface AttributeDefinition$1<T = unknown> {
23
+ readonly type: AttributeType$1;
24
+ readonly isOptional: boolean;
25
+ readonly isIndexed: boolean;
26
+ readonly isUnique: boolean;
27
+ optional(): AttributeDefinition$1<T>;
28
+ indexed(): AttributeDefinition$1<T>;
29
+ unique(): AttributeDefinition$1<T>;
30
+ }
31
+ interface EntityDefinition {
32
+ readonly type: "entity";
33
+ readonly attrs: Record<string, AttributeDefinition$1<unknown>>;
34
+ }
35
+ interface LinkSide {
36
+ on: string;
37
+ has: "one" | "many";
38
+ label: string;
39
+ }
40
+ interface LinkDefinition$1 {
41
+ forward: LinkSide;
42
+ reverse: LinkSide;
43
+ }
44
+ interface SchemaDefinition {
45
+ entities: Record<string, EntityDefinition>;
46
+ links: Record<string, LinkDefinition$1>;
47
+ }
48
+ type QueryScalar$1 = string | number | boolean | null;
49
+ interface QueryComparison$1 {
50
+ $ne?: QueryScalar$1;
51
+ $in?: QueryScalar$1[];
52
+ $nin?: QueryScalar$1[];
53
+ $gt?: QueryScalar$1;
54
+ $gte?: QueryScalar$1;
55
+ $lt?: QueryScalar$1;
56
+ $lte?: QueryScalar$1;
57
+ }
58
+ type QueryWhereValue$1 = QueryScalar$1 | QueryComparison$1;
59
+ interface QueryWhere$1 {
60
+ [attribute: string]: QueryWhereValue$1 | QueryWhere$1 | QueryWhere$1[] | undefined;
61
+ $or?: QueryWhere$1[];
62
+ $and?: QueryWhere$1[];
63
+ $not?: QueryWhere$1;
64
+ }
65
+ interface QueryOptions {
66
+ where?: QueryWhere$1;
67
+ order?: Record<string, "asc" | "desc">;
68
+ limit?: number;
69
+ /**
70
+ * Opaque cursor from a previous page's `pageInfo[namespace].nextCursor`.
71
+ * The engine requires an explicit `order`, because a cursor is only
72
+ * meaningful against a total order. `db.loadMore()` sends this for you.
73
+ */
74
+ after?: string;
75
+ /** Top level only: report the total matching rows as `pageInfo[ns].count`. */
76
+ count?: boolean;
77
+ }
78
+ interface QueryNode {
79
+ $?: QueryOptions;
80
+ [link: string]: unknown;
81
+ }
82
+ type QueryDocument = Record<string, QueryNode>;
83
+ /** One entity as returned by the engine. Nested links are plain properties. */
84
+ type QueryEntity = Record<string, unknown>;
85
+ /** Result payload keyed by the requested top-level namespace names. */
86
+ type QueryResult = Record<string, QueryEntity[]>;
87
+ interface QueryError {
88
+ code: string;
89
+ message: string;
90
+ }
91
+ /** Truncation metadata the engine reports per namespace. */
92
+ interface PageInfo {
93
+ /** The effective limit, or null when the namespace is uncapped. */
94
+ limit: number | null;
95
+ /** Rows the engine returned after row-level view rules, not rows read. */
96
+ returned: number;
97
+ hasMore: boolean;
98
+ /**
99
+ * Opaque keyset cursor for the next page. Emitted only when `hasMore` is
100
+ * true and the query has an explicit `order`; `db.loadMore()` passes it back
101
+ * as `$: { after }`.
102
+ */
103
+ nextCursor?: string;
104
+ /** Total matching rows, when the query asked for `count`. */
105
+ count?: number;
106
+ /** The groups, when the query asked for `aggregate`. */
107
+ aggregate?: AggregateGroup[];
108
+ }
109
+ /** One group of an aggregate, as the engine reports it. */
110
+ interface AggregateGroup {
111
+ /** The group's key values; empty without a groupBy. */
112
+ key: Record<string, unknown>;
113
+ count?: number;
114
+ countOf?: Record<string, number>;
115
+ sum?: Record<string, number | null>;
116
+ avg?: Record<string, number | null>;
117
+ min?: Record<string, unknown>;
118
+ max?: Record<string, unknown>;
119
+ }
120
+ type QueryPageInfo = Record<string, PageInfo>;
121
+ interface QueryState {
122
+ data: QueryResult | null;
123
+ isLoading: boolean;
124
+ error: QueryError | null;
125
+ /**
126
+ * Per top-level namespace truncation metadata from the engine. `returned` is
127
+ * the engine's own visible count; do not re-derive it from `data`.
128
+ */
129
+ pageInfo?: QueryPageInfo;
130
+ }
131
+ interface PresencePeer {
132
+ clientId: string;
133
+ presence: unknown;
134
+ cursor?: unknown;
135
+ drag?: unknown;
136
+ }
137
+ type TxOpKind = "insert" | "patch" | "upsert" | "patchMany" | "deleteMany" | "update" | "merge" | "link" | "unlink" | "delete";
138
+ interface TxOpBase {
139
+ op: TxOpKind;
140
+ namespace: string;
141
+ id: string;
142
+ }
143
+ interface TxUpdateOp extends TxOpBase {
144
+ op: "update";
145
+ values: Record<string, unknown>;
146
+ }
147
+ interface TxInsertOp extends TxOpBase {
148
+ op: "insert";
149
+ values: Record<string, unknown>;
150
+ }
151
+ interface TxPatchOp extends TxOpBase {
152
+ op: "patch";
153
+ values: Record<string, unknown>;
154
+ }
155
+ /**
156
+ * Creates the row from `create` when it is missing, otherwise writes `values`.
157
+ * The engine decides inside the transaction, so the choice cannot race.
158
+ */
159
+ interface TxUpsertOp extends TxOpBase {
160
+ op: "upsert";
161
+ values: Record<string, unknown>;
162
+ create: Record<string, unknown>;
163
+ }
164
+ interface TxMergeOp extends TxOpBase {
165
+ op: "merge";
166
+ values: Record<string, unknown>;
167
+ }
168
+ interface TxLinkOp extends TxOpBase {
169
+ op: "link";
170
+ link: string;
171
+ targetId: string;
172
+ }
173
+ interface TxUnlinkOp extends TxOpBase {
174
+ op: "unlink";
175
+ link: string;
176
+ targetId: string;
177
+ }
178
+ interface TxDeleteOp extends TxOpBase {
179
+ op: "delete";
180
+ }
181
+ interface TxPatchManyOp {
182
+ op: "patchMany";
183
+ namespace: string;
184
+ where: Record<string, unknown>;
185
+ values: Record<string, unknown>;
186
+ /** Resume after this id (engines before one-transaction bulk writes returned a cursor). */
187
+ after?: string;
188
+ }
189
+ interface TxDeleteManyOp {
190
+ op: "deleteMany";
191
+ namespace: string;
192
+ where: Record<string, unknown>;
193
+ after?: string;
194
+ }
195
+ type TxOp = TxPatchManyOp | TxDeleteManyOp | TxInsertOp | TxPatchOp | TxUpsertOp | TxUpdateOp | TxMergeOp | TxLinkOp | TxUnlinkOp | TxDeleteOp;
196
+ /** A group of ops that travels together. */
197
+ interface TxStep {
198
+ readonly ops: readonly TxOp[];
199
+ readonly op: TxOp;
200
+ }
201
+ type TransactInput = ReadonlyArray<TxStep | TxOp | ReadonlyArray<TxStep | TxOp>>;
202
+ interface OutboxEntry {
203
+ clientTxId: string;
204
+ txId: string;
205
+ workspaceId: string;
206
+ ops: TxOp[];
207
+ createdAt: number;
208
+ /** Sends started so far, persisted before each send. Absent means unknown. */
209
+ attempts?: number;
210
+ }
211
+ /** A queued write the server refused for good and the outbox dropped. */
212
+ interface WriteRejection {
213
+ clientTxId: string;
214
+ ops: TxOp[];
215
+ code: string;
216
+ message: string;
217
+ }
218
+ interface InitConfig {
219
+ /** Stable authenticated claim subject; required for default persistent authenticated browser clients. */
220
+ userId?: string;
221
+ /** Workspace UUID. */
222
+ workspaceId?: string;
223
+ /** Engine origin, e.g. http://localhost:8787. */
224
+ apiUrl?: string;
225
+ /** Override the derived `${apiUrl}/engine/workspaces/:id/websocket` URL. */
226
+ websocketUrl?: string;
227
+ /** Returns a short-lived role-claim JWT for every HTTP/WS request. */
228
+ getToken?: () => Promise<string>;
229
+ schema?: SchemaDefinition;
230
+ /**
231
+ * Called when a queued write is refused permanently during a background
232
+ * flush, after the outbox has dropped it.
233
+ */
234
+ onWriteRejected?: (rejection: WriteRejection) => void;
235
+ }
236
+ /** Ephemeral presence channel on this client's workspace socket. */
237
+ interface DataRoom {
238
+ publishPresence(presence: unknown): void;
239
+ publishCursor(cursor: unknown): void;
240
+ publishDrag(drag: unknown): void;
241
+ clearDrag(): void;
242
+ subscribePresence(listener: (peers: PresencePeer[]) => void): () => void;
243
+ /** Clears local presence; subscription disposers remain owned by their callers. */
244
+ leave(): void;
245
+ }
246
+ interface DataClient {
247
+ transact(input: TransactInput): Promise<"applied" | "queued">;
248
+ /** Files scoped to the configured workspace and authenticated by its claim. */
249
+ files: StorageClient;
250
+ /** Reuses the workspace socket and its reconnect/replay behavior. */
251
+ room(target: string): DataRoom;
252
+ /** Test/dev helper: empties the pending outbox for this workspace. */
253
+ clearOutbox(): Promise<void>;
254
+ /** Retries pending writes now (also runs on reconnect and `online`). */
255
+ flushOutbox(): Promise<void>;
256
+ /** Subscribes to a query document; the model client's live reads use it. */
257
+ subscribeQuery(query: QueryDocument, listener: () => void): () => void;
258
+ /** Current cached state for a query, without subscribing to it. */
259
+ getQueryState(query: QueryDocument): QueryState;
260
+ /**
261
+ * Requests the next page for the cached query and appends it.
262
+ *
263
+ * Uses `pageInfo[namespace].nextCursor` for each **top-level** namespace that
264
+ * reported one, re-requests with `$: { ...options, after: cursor }`, appends
265
+ * the new rows deduped by `id`, and updates `pageInfo`. Resolves to `false`
266
+ * when there is no cursor left (first page not loaded yet, or exhausted).
267
+ *
268
+ * Nested link results arrive with the page and are not paginated: a cursor is
269
+ * only defined for the top-level namespace's order.
270
+ *
271
+ * After a page lands the live subscription widens to every loaded row, so a
272
+ * reconnect restores the whole window.
273
+ */
274
+ loadMore(query: QueryDocument): Promise<boolean>;
275
+ /** Opens the shared WebSocket (lazy; safe to call repeatedly). */
276
+ connect(): Promise<void>;
277
+ /** Publishes this client's presence for a target (e.g. a diagram id). */
278
+ publishPresence(target: string, presence: unknown): void;
279
+ /** Publishes this client's cursor for a target. */
280
+ publishCursor(target: string, cursor: unknown): void;
281
+ /** Publishes an ephemeral drag preview for a target. */
282
+ publishDrag(target: string, drag: unknown): void;
283
+ /** Clears this client's drag preview for a target. */
284
+ clearDrag(target: string): void;
285
+ /** Removes this client's presence for a target. */
286
+ clearPresence(target: string): void;
287
+ /** Subscribes to the peer snapshot for a target; immediate first call. */
288
+ subscribePresence(target: string, listener: (peers: PresencePeer[]) => void): () => void;
289
+ /** Stops reconnection timers and closes the socket. */
290
+ close(): void;
291
+ }
292
+ /**
293
+ * Who sent a broadcast message.
294
+ *
295
+ * @experimental May change in a minor release.
296
+ */
297
+ interface TopicSender {
298
+ /** The sending socket's client id: one per open client. */
299
+ clientId: string;
300
+ /** The claim subject (user id) the sender connected with. */
301
+ userId: string;
302
+ }
303
+ interface TopicListener {
304
+ message: (message: unknown, from: TopicSender) => void;
305
+ error?: (error: QueryError) => void;
306
+ }
307
+
308
+ /**
309
+ * Shared role-claim contract between the Worker (JWT verification) and the
310
+ * workspace engine (permission checks).
311
+ * consumes this shape.
312
+ */
313
+ declare const WORKSPACE_ROLE_LEVELS: {
314
+ readonly GUEST: 0;
315
+ readonly USER: 1;
316
+ readonly MEMBER: 2;
317
+ readonly EDITOR: 3;
318
+ readonly MODERATOR: 4;
319
+ readonly ADMIN: 5;
320
+ readonly OWNER: 6;
321
+ readonly FOUNDER: 7;
322
+ readonly DEVELOPER: 8;
323
+ };
324
+ type WorkspaceRole = (typeof WORKSPACE_ROLE_LEVELS)[keyof typeof WORKSPACE_ROLE_LEVELS];
325
+ interface RoleClaim {
326
+ /** Platform user id. */
327
+ sub: string;
328
+ /** Platform workspace id (the DO name). */
329
+ workspaceId: string;
330
+ /** Numeric workspace role level. */
331
+ role: WorkspaceRole;
332
+ /** Expiry, seconds since epoch. */
333
+ exp: number;
334
+ /** Issued at, seconds since epoch. */
335
+ iat: number;
336
+ iss?: string;
337
+ aud?: string;
338
+ }
339
+ declare function hasRoleLevel(role: WorkspaceRole, minimum: WorkspaceRole): boolean;
340
+ declare function hasRole(claim: RoleClaim, minimum: WorkspaceRole): boolean;
341
+
342
+ /**
343
+ * Per-file access rules: who may read, write and delete each file.
344
+ *
345
+ * Installed from the schema's `files` rules by `defineTapeDB`, in the Worker
346
+ * and in every Durable Object. Without rules the defaults are role levels
347
+ * (read: member, write and delete: editor), checked by the Worker alone, as
348
+ * before. With any rule the workspace's Durable Object decides every byte
349
+ * route and filters the file list, because only it holds the index (who
350
+ * uploaded what) and the rows a file can be attached to.
351
+ *
352
+ * A rule is one of:
353
+ * - a role level;
354
+ * - a check over the caller and the file (and, for a write, the file it
355
+ * replaces);
356
+ * - attachment to a row: the file follows the row's own rules. Reading it
357
+ * needs the row to be readable by the caller, writing or deleting it needs
358
+ * the caller to be allowed to update the row. A path that names no row, or
359
+ * a row that does not exist, denies.
360
+ *
361
+ * Every rule fails closed: one that throws denies.
362
+ */
363
+
364
+ /** A file as rules see it. */
365
+ interface FileInfo {
366
+ path: string;
367
+ /** Bytes; null for a write whose size is not known yet. */
368
+ size: number | null;
369
+ contentType: string | null;
370
+ /** The uploader's claim subject. */
371
+ uploadedBy: string;
372
+ }
373
+ interface FileCheckContext {
374
+ auth: {
375
+ sub: string;
376
+ role: number;
377
+ workspaceId: string;
378
+ };
379
+ /** For read and delete, the stored file; for write, the incoming one. */
380
+ file: FileInfo;
381
+ /** For write, the stored file it would replace, if any. */
382
+ existing?: FileInfo;
383
+ }
384
+ type FileRule = {
385
+ readonly decision: "role";
386
+ readonly level: number;
387
+ } | {
388
+ readonly decision: "check";
389
+ readonly test: (context: FileCheckContext) => boolean;
390
+ } | {
391
+ readonly decision: "attachedTo";
392
+ readonly model: string;
393
+ readonly locate: (path: string) => string | null | undefined;
394
+ };
395
+ interface FileRules {
396
+ read?: FileRule;
397
+ write?: FileRule;
398
+ delete?: FileRule;
399
+ }
400
+
401
+ /**
402
+ * Registry mapping model names to workspace SQLite tables.
403
+ *
404
+ * The registry is the runtime contract shared by query compilation, envelope
405
+ * validation, permissions and durability. It is *not* a hardcoded schema: the
406
+ * consumer defines one schema with `defineSchema()` and the Worker hands the
407
+ * resulting registry to `configureRegistry()` before any request is served.
408
+ *
409
+ * Both `NAMESPACES` and `LINKS` are mutated in place rather than reassigned, so
410
+ * modules that imported the binding at load time observe the configured values.
411
+ * A deployment serves exactly one schema, so this configuration is per Worker
412
+ * instance, not per request.
413
+ */
414
+ type AttributeType = "string" | "number" | "boolean" | "date" | "json" | "any";
415
+ type DeleteRule = "CASCADE" | "SET NULL" | "RESTRICT";
416
+ interface AttributeReference {
417
+ table: string;
418
+ column: string;
419
+ onDelete?: DeleteRule;
420
+ }
421
+ interface AttributeDefinition {
422
+ type: AttributeType;
423
+ personal?: {
424
+ subject: string;
425
+ required: boolean;
426
+ defaultValue?: string | number | null;
427
+ };
428
+ optional?: boolean;
429
+ /**
430
+ * Column default, as stored (booleans 0/1, dates epoch ms, json as text).
431
+ * Fills the field for rows written before it existed: replayed inserts and,
432
+ * through the migration, rows already in the table.
433
+ */
434
+ default?: string | number | null;
435
+ indexed?: boolean;
436
+ unique?: boolean;
437
+ references?: AttributeReference;
438
+ }
439
+ interface NamespaceDefinition {
440
+ apiName: string;
441
+ table: string;
442
+ attributes: Record<string, AttributeDefinition>;
443
+ }
444
+ interface OneToManyLink {
445
+ apiName: string;
446
+ kind: "one-to-many";
447
+ forward: {
448
+ namespace: string;
449
+ label: string;
450
+ has: "many";
451
+ };
452
+ reverse: {
453
+ namespace: string;
454
+ label: string;
455
+ has: "one";
456
+ };
457
+ foreignKey: {
458
+ namespace: string;
459
+ attribute: string;
460
+ };
461
+ }
462
+ interface OneToOneLink {
463
+ apiName: string;
464
+ kind: "one-to-one";
465
+ forward: {
466
+ namespace: string;
467
+ label: string;
468
+ has: "one";
469
+ };
470
+ reverse: {
471
+ namespace: string;
472
+ label: string;
473
+ has: "one";
474
+ };
475
+ foreignKey: {
476
+ namespace: string;
477
+ attribute: string;
478
+ unique: true;
479
+ };
480
+ }
481
+ type LinkDefinition = OneToManyLink | OneToOneLink;
482
+ interface RegistryDefinition {
483
+ namespaces: readonly NamespaceDefinition[];
484
+ links: readonly LinkDefinition[];
485
+ }
486
+
487
+ /**
488
+ * Reading old data through later schema changes.
489
+ *
490
+ * Recovery restores a snapshot and replays log lines that were written under
491
+ * whatever schema was current at the time. If a migration since then dropped
492
+ * or renamed a field, an old line still names it, and replaying it against
493
+ * today's registry would fail and leave the workspace unable to boot.
494
+ *
495
+ * Migrations therefore declare what they changed, and recovery projects old
496
+ * rows and ops through every change made after they were written. Only
497
+ * declared changes are tolerated: an attribute or column that no migration
498
+ * accounts for is still an error, so corrupted or foreign data fails closed.
499
+ */
500
+ type SchemaChange = {
501
+ kind: "dropModel";
502
+ model: string;
503
+ table: string;
504
+ } | {
505
+ kind: "renameModel";
506
+ from: string;
507
+ to: string;
508
+ fromTable: string;
509
+ toTable: string;
510
+ }
511
+ /** `table` is the model's table as of this migration. */
512
+ | {
513
+ kind: "dropField";
514
+ model: string;
515
+ table: string;
516
+ field: string;
517
+ column: string;
518
+ } | {
519
+ kind: "renameField";
520
+ model: string;
521
+ table: string;
522
+ from: string;
523
+ to: string;
524
+ fromColumn: string;
525
+ toColumn: string;
526
+ }
527
+ /** The field's type changed; an old value that no longer fits is dropped. */
528
+ | {
529
+ kind: "retypeField";
530
+ model: string;
531
+ field: string;
532
+ };
533
+
534
+ /**
535
+ * Workspace migrations, in two tracks.
536
+ *
537
+ * The engine track belongs to tapedb: `0001_baseline` (its bookkeeping tables,
538
+ * frozen because deployed workspaces hold its checksum) and every
539
+ * `tapedb_NNNN_*` migration after it. The app track belongs to the deployment:
540
+ * its `NNNN_*` migrations, generated from its schema. Engine migrations run
541
+ * first, so app SQL can rely on the engine's tables as they are now.
542
+ *
543
+ * The configured list is mutated in place by `configureMigrations()` so
544
+ * `migrations.ts` can keep its default-argument shape.
545
+ */
546
+
547
+ interface BundledWorkspaceMigration {
548
+ id: string;
549
+ sql: string;
550
+ /**
551
+ * What this migration changed, for reading data written before it. Not part
552
+ * of the checksum: only the SQL changes a workspace.
553
+ */
554
+ changes?: SchemaChange[];
555
+ }
556
+
557
+ /**
558
+ * Query document wire contract for the workspace engine.
559
+ *
560
+ * `where`, `order`, `limit`, `after`, `count`, `select`, `aggregate` and
561
+ * nested link traversal at any depth. This module owns the typed
562
+ * shapes and the registry-independent validation. Registry-specific checks
563
+ * (namespace, attribute and link existence) live in `query-compile.ts`.
564
+ *
565
+ * Values describe the API shape: attribute names are camelCase registry names,
566
+ * booleans are real booleans, dates are epoch milliseconds and `json`/`any`
567
+ * attributes are JSON values. Storage conversion happens in `query-execute.ts`.
568
+ */
569
+
570
+ /** Scalars accepted by `where` and by comparison operators. */
571
+ type QueryScalar = string | number | boolean | null;
572
+ /** Supported comparison operators. Anything else is rejected. */
573
+ interface QueryComparison {
574
+ $ne?: QueryScalar;
575
+ $in?: QueryScalar[];
576
+ /** Not in the list. Like `$ne`, also matches rows where the value is null. */
577
+ $nin?: QueryScalar[];
578
+ $gt?: QueryScalar;
579
+ $gte?: QueryScalar;
580
+ $lt?: QueryScalar;
581
+ $lte?: QueryScalar;
582
+ }
583
+ type QueryWhereValue = QueryScalar | QueryComparison;
584
+ /**
585
+ * Attribute conditions, ANDed. Three reserved keys combine whole filters:
586
+ * `$or` and `$and` take non-empty arrays of filters, `$not` takes one.
587
+ */
588
+ /** How a relation filter matches: the parent row, or some/every/no children. */
589
+ type RelationMode = "parent" | "some" | "every" | "none";
590
+ /**
591
+ * A filter on a linked namespace, by the same label `include` uses. Compiled
592
+ * into a correlated subquery, so the rows are never fetched.
593
+ */
594
+ interface QueryRelationFilter {
595
+ label: string;
596
+ mode: RelationMode;
597
+ where: QueryWhere;
598
+ }
599
+ interface QueryWhere {
600
+ [attribute: string]: QueryWhereValue | QueryWhere | QueryWhere[] | QueryRelationFilter[] | undefined;
601
+ $or?: QueryWhere[];
602
+ $and?: QueryWhere[];
603
+ $not?: QueryWhere;
604
+ $link?: QueryRelationFilter[];
605
+ }
606
+
607
+ /**
608
+ * Permissions.
609
+ *
610
+ * Two kinds of decision, one place:
611
+ *
612
+ * - a **role level** (the default: view=MEMBER, write=EDITOR, delete=MODERATOR)
613
+ * - a **row rule**: a predicate that sees the caller and the row
614
+ *
615
+ * Row rules exist because role levels cannot express "only the author may edit
616
+ * this". They run inside the transaction, next to the write they gate, so the
617
+ * row they judge is the row being changed.
618
+ *
619
+ * `view` accepts two rule forms. A function rule is evaluated per fetched row,
620
+ * so it can express anything but cannot use an index: the executor scans to
621
+ * fill a page, bounded by a cap. A `where` rule returns a query filter for the
622
+ * caller, which is compiled into the SQL of every level that reads the
623
+ * namespace, so it uses indexes and never short-fills a page.
624
+ */
625
+
626
+ type PermissionAction = "view" | "create" | "update" | "delete";
627
+ /** The caller, as far as a rule is concerned. */
628
+ interface PermissionAuth {
629
+ sub: string;
630
+ role: WorkspaceRole;
631
+ workspaceId: string;
632
+ }
633
+ /**
634
+ * What a rule receives.
635
+ *
636
+ * `data` is the stored row for update, delete and link operations, with API
637
+ * attribute names. `next` is the incoming values for create and update.
638
+ */
639
+ interface PermissionContext {
640
+ auth: PermissionAuth;
641
+ data?: Record<string, unknown>;
642
+ next?: Record<string, unknown>;
643
+ /**
644
+ * API attribute names this op writes. Lets a rule gate one field: "only the
645
+ * owner may change `price`" is
646
+ * `changed.includes("price") ? data.ownerId === auth.sub : true`.
647
+ */
648
+ changed?: string[];
649
+ }
650
+ /** A rule returns true to allow. Throw or return false to deny. */
651
+ type PermissionRule = (context: PermissionContext) => boolean;
652
+ /**
653
+ * A `view` rule SQL can evaluate: the rows the caller may see, as a `where`
654
+ * filter. An array is OR of its branches, so "mine or public" is
655
+ * `[{ ownerId: auth.sub }, { isPublic: true }]`. An empty array hides
656
+ * everything. Only valid for `view`.
657
+ */
658
+ interface ViewWhereRule {
659
+ where: (auth: PermissionAuth) => QueryWhere | readonly QueryWhere[];
660
+ }
661
+ type PermissionDecision = WorkspaceRole | PermissionRule | ViewWhereRule;
662
+ type PermissionOverrides = Record<string, Partial<Record<PermissionAction, PermissionDecision>>>;
663
+ interface PermissionConfig {
664
+ overrides?: PermissionOverrides;
665
+ }
666
+
667
+ /**
668
+ * One schema, two artifacts.
669
+ *
670
+ * `defineSchema()` is the single source of truth. It produces:
671
+ *
672
+ * - the server registry (namespaces + links) that the engine compiles
673
+ * queries and validates transactions against,
674
+ * - the SQL migrations that create those tables,
675
+ * - the client schema that resolves link labels.
676
+ *
677
+ * A deployment writes the entity map once; the CLI emits the migration bundle
678
+ * from the same object, so the two can never drift.
679
+ */
680
+
681
+ interface TapeDBSchema {
682
+ registry: RegistryDefinition;
683
+ permissions: PermissionConfig;
684
+ migrations: BundledWorkspaceMigration[];
685
+ clientSchema: SchemaDefinition;
686
+ /** Who may read, write and delete each file; absent means the role defaults. */
687
+ files?: FileRules;
688
+ }
689
+
690
+ export { WORKSPACE_ROLE_LEVELS as W, hasRoleLevel as c, hasRole as h };
691
+ export type { BundledWorkspaceMigration as B, DataClient as D, InitConfig as I, OutboxEntry as O, PresencePeer as P, QueryError as Q, RoleClaim as R, StorageObject as S, TopicSender as T, WorkspaceRole as a, WriteRejection as b, StorageFetch as d, TransactInput as e, TxOp as f, QueryDocument as g, QueryResult as i, QueryPageInfo as j, QueryState as k, TopicListener as l, TapeDBSchema as m };