ezship 0.1.11 → 0.1.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.
package/schema.mjs ADDED
@@ -0,0 +1,3099 @@
1
+ // The App Database rules (docs/adr/0007, 0020, 0021, 0046): what a Site
2
+ // may declare in db/schema.sql, how a declaration becomes DDL, and what a Builder may run with `ez db sql`.
3
+ // Zero dependencies, plain JavaScript, Node 20+ and the browser. RULES is the single source: the parser, the
4
+ // planner, `ez help db` and every error message read it, so documentation cannot drift from behaviour.
5
+
6
+ import { isCalendarDate, parseShape, printShape, shapeError } from "./shape.mjs";
7
+
8
+ /**
9
+ * The one file in a Site's workspace the platform reads for tables. Nothing else under db/ is read or served.
10
+ * @type {typeof import("./schema.d.mts").SCHEMA_FILE}
11
+ */
12
+ export const SCHEMA_FILE = "db/schema.sql";
13
+ /** @type {typeof import("./schema.d.mts").RESERVED_DIR} */
14
+ export const RESERVED_DIR = "db/";
15
+ /**
16
+ * A declared table `tickets` of Instance `nike` is physically `data_nike_tickets`; the platform's own
17
+ * app-side tables are data_ez_*.
18
+ * @type {typeof import("./schema.d.mts").TABLE_PREFIX}
19
+ */
20
+ export const TABLE_PREFIX = "data_";
21
+ /** @type {typeof import("./schema.d.mts").PLATFORM_PREFIX} */
22
+ export const PLATFORM_PREFIX = "data_ez_";
23
+ /**
24
+ * The App Database operations a server function's or job's `db` sends to the Host, each with the argument
25
+ * counts the Host accepts (docs/adr/0041). The guest's `db` is built from these keys and the Host validates
26
+ * against them; the page `db` has the same methods plus `upload`, and both derive `count` from `aggregate`.
27
+ * A Global lib module's `Database` type is exactly these and `count` (docs/adr/0077).
28
+ * @type {typeof import("./schema.d.mts").DATABASE_OPERATIONS}
29
+ */
30
+ export const DATABASE_OPERATIONS = Object.freeze({
31
+ list: Object.freeze([1, 2]),
32
+ query: Object.freeze([1, 2]),
33
+ aggregate: Object.freeze([1, 2]),
34
+ get: Object.freeze([2]),
35
+ // A write's optional last argument is its options, `{ why }` (docs/adr/0093).
36
+ insert: Object.freeze([2, 3]),
37
+ update: Object.freeze([3, 4]),
38
+ delete: Object.freeze([2, 3]),
39
+ // A workflow action on a row (docs/adr/0103): table, id, action, then an optional patch and options.
40
+ transition: Object.freeze([3, 4, 5]),
41
+ });
42
+ /**
43
+ * The longest Push message and write reason (docs/adr/0093), in characters.
44
+ * @type {typeof import("./schema.d.mts").MAX_MESSAGE_CHARS}
45
+ */
46
+ export const MAX_MESSAGE_CHARS = 500;
47
+ /**
48
+ * A Push message or write reason as stored (docs/adr/0093): trimmed, null when absent or blank, an error
49
+ * when it is not a string or too long.
50
+ * @type {typeof import("./schema.d.mts").messageText}
51
+ */
52
+ export function messageText(value, what) {
53
+ if (value === undefined || value === null) return { text: null };
54
+ if (typeof value !== "string") return { error: `${what} must be a string` };
55
+ const text = value.trim();
56
+ if (text.length > MAX_MESSAGE_CHARS)
57
+ return { error: `${what} is too long (max ${MAX_MESSAGE_CHARS} characters)` };
58
+ return { text: text || null };
59
+ }
60
+ /**
61
+ * Present on every table, stamped by the platform, never declared.
62
+ * @type {typeof import("./schema.d.mts").SYSTEM_COLUMNS}
63
+ */
64
+ export const SYSTEM_COLUMNS = Object.freeze([
65
+ "id",
66
+ "created_at",
67
+ "created_by",
68
+ "updated_at",
69
+ "updated_by",
70
+ ]);
71
+ /**
72
+ * Table History (docs/adr/0040): every Table `t` has a read-only `t_history` the platform writes.
73
+ * @type {typeof import("./schema.d.mts").HISTORY_SUFFIX}
74
+ */
75
+ export const HISTORY_SUFFIX = "_history";
76
+ /**
77
+ * An open History period ends here (9999-12-31T23:59:59.999Z): "as of T" is valid_from <= T AND valid_to > T.
78
+ * @type {typeof import("./schema.d.mts").HISTORY_OPEN}
79
+ */
80
+ export const HISTORY_OPEN = 253402300799999;
81
+ /** @type {typeof import("./schema.d.mts").HISTORY_OPS} */
82
+ export const HISTORY_OPS = Object.freeze(["seed", "insert", "update", "delete"]);
83
+ /**
84
+ * The History's own columns (declared types), reserved as column names; the rest are the Table's.
85
+ * @type {typeof import("./schema.d.mts").HISTORY_COLUMNS}
86
+ */
87
+ export const HISTORY_COLUMNS = Object.freeze({
88
+ row_id: "TEXT",
89
+ op: "TEXT",
90
+ valid_from: "TIMESTAMP",
91
+ valid_to: "TIMESTAMP",
92
+ by: "TEXT",
93
+ version: "INTEGER",
94
+ why: "TEXT",
95
+ transition: "TEXT",
96
+ });
97
+ /** @type {typeof import("./schema.d.mts").historyName} */
98
+ export const historyName = (table) => `${table}${HISTORY_SUFFIX}`;
99
+ /**
100
+ * The Table a History name belongs to, when `names` (the Instance's table names) holds it; else null.
101
+ * @type {typeof import("./schema.d.mts").historyParent}
102
+ */
103
+ export function historyParent(name, names) {
104
+ if (!name.endsWith(HISTORY_SUFFIX)) return null;
105
+ const parent = name.slice(0, -HISTORY_SUFFIX.length);
106
+ return parent !== "" && names.includes(parent) ? parent : null;
107
+ }
108
+ /** @type {typeof import("./schema.d.mts").NAME_RE} */
109
+ export const NAME_RE = /^[a-z][a-z0-9_]{0,62}$/;
110
+ /**
111
+ * A CHECK value: readable, quotable without escaping, short enough for a union type.
112
+ * @type {typeof import("./schema.d.mts").VALUE_RE}
113
+ */
114
+ export const VALUE_RE = /^[A-Za-z0-9_ .-]{1,64}$/;
115
+ /**
116
+ * What a FILE column holds (docs/adr/0047): an Attachment id, the platform's random id, URL-safe.
117
+ * @type {typeof import("./schema.d.mts").ATTACHMENT_ID_RE}
118
+ */
119
+ export const ATTACHMENT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
120
+ /**
121
+ * What a MEMBER column holds (docs/adr/0098): a Member's actor id, the form of `created_by` and `actors.id`.
122
+ * @type {typeof import("./schema.d.mts").MEMBER_ID_RE}
123
+ */
124
+ export const MEMBER_ID_RE = /^user:[A-Za-z0-9_-]{1,128}$/;
125
+ /**
126
+ * A Member group's name (docs/adr/0098): on the Instance's roster, named by `group(<name>)` in access rules.
127
+ * @type {typeof import("./schema.d.mts").GROUP_RE}
128
+ */
129
+ export const GROUP_RE = /^[a-z][a-z0-9-]{0,39}$/;
130
+ /** @type {typeof import("./schema.d.mts").MAX_GROUPS} */
131
+ export const MAX_GROUPS = 50;
132
+ /**
133
+ * The Host's own groups (docs/adr/0110): `ez-admin` is held by the Instance's Admins, `ez-builder` by every
134
+ * Builder, each through the Member identity with their email. Tested like any group, never assigned or
135
+ * declared; every other `ez-` name is reserved and held by no one.
136
+ * @type {typeof import("./schema.d.mts").RESERVED_GROUPS}
137
+ */
138
+ export const RESERVED_GROUPS = Object.freeze(["ez-admin", "ez-builder"]);
139
+ /** @type {typeof import("./schema.d.mts").isReservedGroup} */
140
+ export const isReservedGroup = (name) => name.startsWith("ez-");
141
+
142
+ /** @type {typeof import("./schema.d.mts").RULES} */
143
+ export const RULES = Object.freeze({
144
+ /** Declared type -> storage type. */
145
+ types: Object.freeze({
146
+ TEXT: "TEXT",
147
+ INTEGER: "INTEGER",
148
+ REAL: "REAL",
149
+ BOOLEAN: "INTEGER",
150
+ TIMESTAMP: "INTEGER",
151
+ DATE: "TEXT",
152
+ MONEY: "INTEGER",
153
+ JSON: "TEXT",
154
+ FILE: "TEXT",
155
+ MEMBER: "TEXT",
156
+ }),
157
+ policies: Object.freeze(/** @type {const} */ (["member", "none"])),
158
+ /** Constructs the parser refuses, with the reason an agent needs. Keys are matched as whole words, in order. */
159
+ refused: Object.freeze({
160
+ "PRIMARY KEY": "every table gets an `id` primary key automatically",
161
+ "FOREIGN KEY": "put `REFERENCES <table>` on the column instead",
162
+ FOREIGN: "put `REFERENCES <table>` on the column instead",
163
+ UNIQUE:
164
+ "declare CREATE UNIQUE INDEX ON <table> (<columns>) below the table instead (docs/adr/0046)",
165
+ AUTOINCREMENT:
166
+ "write <name> INTEGER SEQUENCE: the platform numbers rows per Table (docs/adr/0046)",
167
+ COLLATE: "collations are not supported",
168
+ "WITHOUT ROWID": "not supported",
169
+ STRICT: "every table is strict already",
170
+ DROP: "tables and columns are never dropped; remove the declaration and the data stays",
171
+ ALTER: "columns are added by declaring them in CREATE TABLE; deploy adds what is missing",
172
+ TRIGGER: "triggers are not supported",
173
+ VIEW: "views are not supported",
174
+ INSERT: "db/schema.sql declares tables only; insert rows with `ez db sql`",
175
+ UPDATE: "db/schema.sql declares tables only; change rows with `ez db sql`",
176
+ DELETE: "db/schema.sql declares tables only; delete rows with `ez db sql`",
177
+ SELECT: "db/schema.sql declares tables only; query with `ez db sql`",
178
+ }),
179
+ /** Names of control-plane tables. A declared table or column may not use one: Builder SQL refuses every
180
+ * identifier that names a control-plane table, so such a column could never be queried. */
181
+ reservedNames: Object.freeze([
182
+ "actors",
183
+ "sites",
184
+ "site_files",
185
+ "site_builders",
186
+ "site_tables",
187
+ "platform_user",
188
+ "platform_session",
189
+ "platform_account",
190
+ "platform_verification",
191
+ "platform_tokens",
192
+ "cli_device_codes",
193
+ "user",
194
+ "session",
195
+ "account",
196
+ "verification",
197
+ "ratelimit",
198
+ "app_members",
199
+ ]),
200
+ limits: Object.freeze({ tablesPerInstance: 500, columnsPerTable: 200, valuesPerCheck: 50 }),
201
+ });
202
+
203
+ // ---- tokenizer ------------------------------------------------------------------------------------------
204
+
205
+ /**
206
+ * @typedef {import("./schema.d.mts").Column} Column
207
+ * @typedef {import("./schema.d.mts").Table} Table
208
+ * @typedef {import("./schema.d.mts").ParseError} ParseError
209
+ * @typedef {{kind: "word" | "comment" | "string", text: string, line: number} | {kind: "(" | ")" | "," | ";", text?: never, line: number}} Token
210
+ */
211
+
212
+ /**
213
+ * @param {string} sql
214
+ * @returns {{tokens: Token[]} | ParseError}
215
+ */
216
+ function tokenize(sql) {
217
+ /** @type {Token[]} */
218
+ const tokens = [];
219
+ let line = 1;
220
+ let i = 0;
221
+ while (i < sql.length) {
222
+ const c = sql[i];
223
+ if (c === "\n") {
224
+ line++;
225
+ i++;
226
+ continue;
227
+ }
228
+ if (c === " " || c === "\t" || c === "\r") {
229
+ i++;
230
+ continue;
231
+ }
232
+ if (c === "-" && sql[i + 1] === "-") {
233
+ const end = sql.indexOf("\n", i);
234
+ const text = sql.slice(i + 2, end === -1 ? sql.length : end).trim();
235
+ tokens.push({ kind: "comment", text, line });
236
+ i = end === -1 ? sql.length : end;
237
+ continue;
238
+ }
239
+ if (c === "'") {
240
+ // A single-quoted string: only CHECK (col IN ('a', 'b')) may hold one; '' is an escaped quote.
241
+ let j = i + 1;
242
+ let text = "";
243
+ for (; j < sql.length; j++) {
244
+ if (sql[j] === "'" && sql[j + 1] === "'") {
245
+ text += "'";
246
+ j++;
247
+ } else if (sql[j] === "'") break;
248
+ else if (sql[j] === "\n") return { error: "unterminated string", line };
249
+ else text += sql[j];
250
+ }
251
+ if (j >= sql.length) return { error: "unterminated string", line };
252
+ tokens.push({ kind: "string", text, line });
253
+ i = j + 1;
254
+ continue;
255
+ }
256
+ if (c === '"' || c === "`" || c === "[")
257
+ return { error: `unexpected character ${c}: names are bare lowercase words`, line };
258
+ if (c === "(" || c === ")" || c === "," || c === ";") {
259
+ tokens.push({ kind: c, line });
260
+ i++;
261
+ continue;
262
+ }
263
+ // A number (a DEFAULT, docs/adr/0097) may carry a sign and a fraction; a name never starts with a digit.
264
+ const m = /^-?[0-9]+\.[0-9]+(?![A-Za-z0-9_])|^-[0-9]+(?![A-Za-z0-9_.])|^[A-Za-z0-9_]+/.exec(
265
+ sql.slice(i),
266
+ );
267
+ if (!m) return { error: `unexpected character ${c}`, line };
268
+ tokens.push({ kind: "word", text: m[0], line });
269
+ i += m[0].length;
270
+ }
271
+ return { tokens };
272
+ }
273
+
274
+ /** @param {Token | undefined} t @param {string} w */
275
+ const isWord = (t, w) => t !== undefined && t.kind === "word" && t.text.toUpperCase() === w;
276
+ /** @param {Token | undefined} t */
277
+ const upper = (t) =>
278
+ t && t.kind === "word" ? t.text.toUpperCase() : t ? t.kind : "end of statement";
279
+
280
+ /**
281
+ * The refused construct a token sequence starts with, if any: "PRIMARY KEY" before "PRIMARY", etc.
282
+ * @param {Token[]} tokens @param {number} i
283
+ */
284
+ function refusedAt(tokens, i) {
285
+ for (const key of Object.keys(RULES.refused)) {
286
+ const words = key.split(" ");
287
+ if (words.every((w, k) => isWord(tokens[i + k], w))) return key;
288
+ }
289
+ return null;
290
+ }
291
+
292
+ /** @param {string} key @param {number} line */
293
+ const refuse = (key, line) => ({ error: `${key} is not allowed: ${RULES.refused[key]}`, line });
294
+
295
+ /** @param {string} name @param {string} what @param {number} line */
296
+ function checkName(name, what, line) {
297
+ if (!NAME_RE.test(name))
298
+ return {
299
+ error: `${what} "${name}" must be lowercase letters, digits and underscores (at most 63, starting with a letter)`,
300
+ line,
301
+ };
302
+ if (name.startsWith("ez_"))
303
+ return { error: `${what} "${name}": the ez_ prefix is reserved`, line };
304
+ if (SYSTEM_COLUMNS.includes(name))
305
+ return {
306
+ error: `${what} "${name}" is a system column and is present on every table already`,
307
+ line,
308
+ };
309
+ if (what === "table" && name.endsWith(HISTORY_SUFFIX))
310
+ return {
311
+ error: `${what} "${name}": the ${HISTORY_SUFFIX} suffix is reserved for History (docs/adr/0040)`,
312
+ line,
313
+ };
314
+ if (name in HISTORY_COLUMNS)
315
+ return { error: `${what} "${name}" is a History column and is reserved`, line };
316
+ if (RULES.reservedNames.includes(name))
317
+ return { error: `${what} "${name}" is reserved by the platform; pick another name`, line };
318
+ return null;
319
+ }
320
+
321
+ // ---- statements -----------------------------------------------------------------------------------------
322
+
323
+ /**
324
+ * Splits tokens into statements, each with the comment lines directly above it and the comments inside it.
325
+ * @param {Token[]} tokens @returns {{statements: {tokens: Token[], comments: Token[], inner: Token[]}[]} | ParseError}
326
+ */
327
+ function splitStatements(tokens) {
328
+ const statements = [];
329
+ let comments = [];
330
+ /** The comments inside a statement: a column's doc is the one on its line (docs/adr/0109). */
331
+ let inner = [];
332
+ let current = [];
333
+ let lastLine = 0;
334
+ for (const t of tokens) {
335
+ if (t.kind === "comment") {
336
+ if (current.length === 0) comments.push(t);
337
+ else inner.push(t);
338
+ continue;
339
+ }
340
+ if (t.kind === ";") {
341
+ if (current.length > 0) statements.push({ tokens: current, comments, inner });
342
+ current = [];
343
+ comments = [];
344
+ inner = [];
345
+ continue;
346
+ }
347
+ // A blank line separates a comment block from the statement it would otherwise apply to.
348
+ if (
349
+ current.length === 0 &&
350
+ comments.length > 0 &&
351
+ comments[comments.length - 1].line < t.line - 1
352
+ )
353
+ comments = [];
354
+ current.push(t);
355
+ lastLine = t.line;
356
+ }
357
+ if (current.length > 0) return { error: "every statement must end with ;", line: lastLine };
358
+ return { statements };
359
+ }
360
+
361
+ /** @param {Token[]} comments @returns {{policies: Pick<Table, "read" | "write">} | ParseError} */
362
+ function parsePolicies(comments) {
363
+ /** @type {Pick<Table, "read" | "write">} */
364
+ const out = {};
365
+ for (const c of comments) {
366
+ const m = /^(read|write)\s*:\s*(\S+)$/i.exec(c.text ?? "");
367
+ if (!m) continue;
368
+ const value = RULES.policies.find((policy) => policy === m[2].toLowerCase());
369
+ if (!value)
370
+ return {
371
+ error: `${m[1].toLowerCase()} policy "${m[2]}" must be member or none; public access is no longer supported.`,
372
+ line: c.line,
373
+ };
374
+ out[/** @type {"read" | "write"} */ (m[1].toLowerCase())] = value;
375
+ }
376
+ return { policies: out };
377
+ }
378
+
379
+ /** The longest TEXT default, in characters. */
380
+ const DEFAULT_MAX_CHARS = 256;
381
+
382
+ /**
383
+ * The token after DEFAULT (docs/adr/0097): a quoted string, a number, true/false, now or me. Checked against
384
+ * the column's type once the whole definition is read.
385
+ * @param {Token | undefined} t @param {string} column @param {number} line
386
+ * @returns {{value: import("./schema.d.mts").ColumnDefault, quoted: boolean} | ParseError}
387
+ */
388
+ function parseDefault(t, column, line) {
389
+ const shape = `column "${column}": DEFAULT takes a quoted string, a number, true, false, now or me`;
390
+ if (!t) return { error: shape, line };
391
+ if (t.kind === "string") return { value: { kind: "value", value: t.text }, quoted: true };
392
+ if (t.kind !== "word") return { error: shape, line };
393
+ const word = t.text.toLowerCase();
394
+ if (word === "now") return { value: { kind: "now" }, quoted: false };
395
+ if (word === "me") return { value: { kind: "me" }, quoted: false };
396
+ if (word === "true" || word === "false")
397
+ return { value: { kind: "value", value: word === "true" }, quoted: false };
398
+ if (word === "null")
399
+ return { error: `column "${column}": every column defaults to null already`, line };
400
+ if (/^-?[0-9]+(\.[0-9]+)?$/.test(t.text) && Number.isFinite(Number(t.text)))
401
+ return { value: { kind: "value", value: Number(t.text) }, quoted: false };
402
+ return { error: shape, line };
403
+ }
404
+
405
+ /**
406
+ * Whether a parsed default suits its column: a string for TEXT (one of its CHECK values when it has them), a
407
+ * date for DATE, an integer for INTEGER and MONEY (cents), a number for REAL, true/false for BOOLEAN, now or an integer for
408
+ * TIMESTAMP; never JSON, FILE or a SEQUENCE.
409
+ * @param {Omit<Column, "default">} col @param {{value: import("./schema.d.mts").ColumnDefault, quoted: boolean}} d
410
+ * @param {string} column @param {number} line @returns {ParseError | null}
411
+ */
412
+ function defaultError(col, d, column, line) {
413
+ const wrong = (/** @type {string} */ what) => ({
414
+ error: `column "${column}": a ${col.type} column's DEFAULT is ${what}`,
415
+ line,
416
+ });
417
+ if (col.sequence)
418
+ return {
419
+ error: `column "${column}": a SEQUENCE is numbered by the platform; no DEFAULT`,
420
+ line,
421
+ };
422
+ if (col.type === "JSON" || col.type === "FILE")
423
+ return { error: `column "${column}": a ${col.type} column takes no DEFAULT`, line };
424
+ const v = d.value;
425
+ if (v.kind === "me")
426
+ return col.type === "MEMBER"
427
+ ? null
428
+ : { error: `column "${column}": DEFAULT me needs a MEMBER column (docs/adr/0098)`, line };
429
+ if (col.type === "MEMBER")
430
+ return { error: `column "${column}": a MEMBER column's DEFAULT is me`, line };
431
+ if (v.kind === "now")
432
+ return col.type === "TIMESTAMP" ? null : wrong("never now (TIMESTAMP only)");
433
+ const value = v.value;
434
+ switch (col.type) {
435
+ case "TEXT":
436
+ if (!d.quoted || typeof value !== "string") return wrong("a quoted string");
437
+ if (value.length > DEFAULT_MAX_CHARS)
438
+ return wrong(`a string of at most ${DEFAULT_MAX_CHARS} characters`);
439
+ if (col.values && !col.values.includes(value))
440
+ return wrong(`one of its CHECK values (${col.values.join(", ")})`);
441
+ return null;
442
+ case "DATE":
443
+ return d.quoted && typeof value === "string" && isCalendarDate(value)
444
+ ? null
445
+ : wrong("a quoted date, 'YYYY-MM-DD'");
446
+ case "BOOLEAN":
447
+ return typeof value === "boolean" ? null : wrong("true or false");
448
+ case "INTEGER":
449
+ return typeof value === "number" && Number.isSafeInteger(value) ? null : wrong("an integer");
450
+ case "MONEY":
451
+ return typeof value === "number" && Number.isSafeInteger(value)
452
+ ? null
453
+ : wrong("a whole number of cents");
454
+ case "TIMESTAMP":
455
+ return typeof value === "number" && Number.isSafeInteger(value)
456
+ ? null
457
+ : wrong("now or an integer of milliseconds");
458
+ case "REAL":
459
+ return typeof value === "number" ? null : wrong("a number");
460
+ }
461
+ return wrong("not supported");
462
+ }
463
+
464
+ /**
465
+ * One column definition: `<name> [<type>] [NOT NULL] [REFERENCES <table>] [CHECK (<name> IN (...))] [DEFAULT <value>] [SEQUENCE]`.
466
+ * @param {Token[]} tokens @param {number} line @returns {{name: string, column: Column} | ParseError}
467
+ */
468
+ function parseColumn(tokens, line) {
469
+ const [nameTok, ...rest] = tokens;
470
+ if (!nameTok || nameTok.kind !== "word") return { error: "expected a column name", line };
471
+ const bad = refusedAt(tokens, 0);
472
+ if (bad) return refuse(bad, line);
473
+ const nameErr = checkName(nameTok.text, "column", line);
474
+ if (nameErr) return nameErr;
475
+ if (isWord(nameTok, "DEFAULT"))
476
+ return { error: `column "${nameTok.text}": DEFAULT is a keyword; pick another name`, line };
477
+ /** @type {{value: import("./schema.d.mts").ColumnDefault, quoted: boolean} | null} */
478
+ let fallback = null;
479
+ /** @type {Omit<Column, "type"> & {type: Column["type"] | null}} */
480
+ const col = { type: null, required: false, ref: null, values: null };
481
+ let sequence = false;
482
+ /** @type {string | undefined} */
483
+ let label;
484
+ /** @type {"restrict" | undefined} */
485
+ let onDelete;
486
+ let i = 0;
487
+ if (rest[i] && rest[i].kind === "word" && upper(rest[i]) in RULES.types) {
488
+ col.type = /** @type {Column["type"]} */ (upper(rest[i]));
489
+ i++;
490
+ }
491
+ /** @type {string | undefined} */
492
+ let shape;
493
+ // `JSON TYPE '<shape>'` (docs/adr/0078): the column's TypeScript type and what every write must match.
494
+ if (isWord(rest[i], "TYPE")) {
495
+ const text = rest[i + 1];
496
+ if (col.type !== "JSON")
497
+ return { error: `column "${nameTok.text}": TYPE '...' declares a JSON column's shape`, line };
498
+ if (!text || text.kind !== "string")
499
+ return {
500
+ error: `column "${nameTok.text}": TYPE is followed by the shape in quotes, TYPE '{ rate: number }'`,
501
+ line,
502
+ };
503
+ const parsed = parseShape(text.text);
504
+ if ("error" in parsed) return { error: `column "${nameTok.text}": ${parsed.error}`, line };
505
+ shape = printShape(parsed.shape);
506
+ i += 2;
507
+ }
508
+ while (i < rest.length) {
509
+ const key = refusedAt(rest, i);
510
+ if (key) return refuse(key, line);
511
+ if (isWord(rest[i], "NOT") && isWord(rest[i + 1], "NULL")) {
512
+ col.required = true;
513
+ i += 2;
514
+ continue;
515
+ }
516
+ const referenced = rest[i + 1];
517
+ if (isWord(rest[i], "REFERENCES") && referenced?.kind === "word") {
518
+ const refErr = checkName(referenced.text, "referenced table", line);
519
+ if (refErr) return refErr;
520
+ col.ref = referenced.text;
521
+ i += 2;
522
+ continue;
523
+ }
524
+ // `REFERENCES <table> ON DELETE RESTRICT` (docs/adr/0109): the referenced row cannot be deleted while
525
+ // this column holds its id. DELETE is otherwise a refused word, so the clause is read whole here.
526
+ if (isWord(rest[i], "ON") && isWord(rest[i + 1], "DELETE")) {
527
+ if (col.ref === null)
528
+ return {
529
+ error: `column "${nameTok.text}": ON DELETE follows REFERENCES <table>`,
530
+ line,
531
+ };
532
+ if (!isWord(rest[i + 2], "RESTRICT"))
533
+ return {
534
+ error: `column "${nameTok.text}": ON DELETE takes RESTRICT only (CASCADE and SET NULL are not supported, docs/adr/0109)`,
535
+ line,
536
+ };
537
+ onDelete = "restrict";
538
+ i += 3;
539
+ continue;
540
+ }
541
+ if (isWord(rest[i], "LABEL")) {
542
+ const text = labelText(rest[i + 1], `column "${nameTok.text}"`, line);
543
+ if (typeof text !== "string") return text;
544
+ label = text;
545
+ i += 2;
546
+ continue;
547
+ }
548
+ if (isWord(rest[i], "CHECK")) {
549
+ const r = parseCheck(rest, i + 1, nameTok.text, line);
550
+ if ("error" in r) return r;
551
+ col.values = r.values;
552
+ i = r.next;
553
+ continue;
554
+ }
555
+ if (isWord(rest[i], "SEQUENCE")) {
556
+ sequence = true;
557
+ i++;
558
+ continue;
559
+ }
560
+ if (isWord(rest[i], "DEFAULT")) {
561
+ const d = parseDefault(rest[i + 1], nameTok.text, line);
562
+ if ("error" in d) return d;
563
+ fallback = d;
564
+ i += 2;
565
+ continue;
566
+ }
567
+ return {
568
+ error: `unexpected ${upper(rest[i])} in column "${nameTok.text}": a column is <name> <type> [TYPE '<shape>'] [NOT NULL] [REFERENCES <table> [ON DELETE RESTRICT]] [CHECK (<name> IN ('a', 'b'))] [DEFAULT <value>] [SEQUENCE] [LABEL '<label>']`,
569
+ line,
570
+ };
571
+ }
572
+ if (col.type === null) {
573
+ if (col.ref === null)
574
+ return {
575
+ error: `column "${nameTok.text}" needs a type (${Object.keys(RULES.types).join(", ")})`,
576
+ line,
577
+ };
578
+ col.type = "TEXT";
579
+ }
580
+ if (col.values && col.type !== "TEXT")
581
+ return { error: `column "${nameTok.text}": CHECK (... IN (...)) needs a TEXT column`, line };
582
+ // `<name> JSON REFERENCES <table>` (docs/adr/0102): a list of ids, stored as JSON TYPE 'string[]'.
583
+ if (col.type === "JSON" && col.ref !== null) {
584
+ if (shape !== undefined && shape !== "string[]")
585
+ return {
586
+ error: `column "${nameTok.text}": a JSON column that REFERENCES a table holds a list of ids, TYPE 'string[]'`,
587
+ line,
588
+ };
589
+ shape = "string[]";
590
+ }
591
+ if (col.type === "FILE" && col.ref !== null)
592
+ return {
593
+ error: `column "${nameTok.text}": a FILE column holds an Attachment id and cannot REFERENCES a table (docs/adr/0047)`,
594
+ line,
595
+ };
596
+ if (onDelete && col.type === "JSON")
597
+ return {
598
+ error: `column "${nameTok.text}": an id list takes no ON DELETE; only a single reference can restrict deletes (docs/adr/0109)`,
599
+ line,
600
+ };
601
+ if (col.type === "MEMBER" && col.ref !== null)
602
+ return {
603
+ error: `column "${nameTok.text}": a MEMBER column holds a Member and cannot REFERENCES a table (docs/adr/0098)`,
604
+ line,
605
+ };
606
+ if (sequence && (col.type !== "INTEGER" || col.ref !== null))
607
+ return {
608
+ error: `column "${nameTok.text}": SEQUENCE needs a plain INTEGER column (the platform numbers rows per Table, docs/adr/0046)`,
609
+ line,
610
+ };
611
+ const typed = {
612
+ ...col,
613
+ type: col.type,
614
+ ...(sequence ? { sequence: /** @type {const} */ (true) } : {}),
615
+ };
616
+ if (fallback) {
617
+ const bad = defaultError(typed, fallback, nameTok.text, line);
618
+ if (bad) return bad;
619
+ }
620
+ return {
621
+ name: nameTok.text,
622
+ column: {
623
+ ...typed,
624
+ ...(shape ? { shape } : {}),
625
+ ...(fallback ? { default: fallback.value } : {}),
626
+ ...(onDelete ? { onDelete } : {}),
627
+ ...(label ? { label } : {}),
628
+ },
629
+ };
630
+ }
631
+
632
+ /** The longest LABEL, in characters (docs/adr/0109). */
633
+ const LABEL_MAX_CHARS = 80;
634
+ /** The longest column doc, in characters (docs/adr/0109). */
635
+ const DOC_MAX_CHARS = 500;
636
+
637
+ /**
638
+ * The quoted text after LABEL (docs/adr/0109): one line, at most LABEL_MAX_CHARS.
639
+ * @param {Token | undefined} t @param {string} what @param {number} line @returns {string | ParseError}
640
+ */
641
+ function labelText(t, what, line) {
642
+ if (!t || t.kind !== "string" || !t.text.trim())
643
+ return {
644
+ error: `${what}: LABEL is followed by the label in quotes, LABEL 'Customer ID'`,
645
+ line,
646
+ };
647
+ if (t.text.length > LABEL_MAX_CHARS)
648
+ return { error: `${what}: a LABEL is at most ${LABEL_MAX_CHARS} characters`, line };
649
+ return t.text.trim();
650
+ }
651
+
652
+ /**
653
+ * `( <col> IN ( 'a', 'b' ) )` starting at tokens[i]; returns the values and the index after the closing ")".
654
+ * @param {Token[]} tokens @param {number} i @param {string} column @param {number} line @returns {{values: string[], next: number} | ParseError}
655
+ */
656
+ function parseCheck(tokens, i, column, line) {
657
+ const shape = `column "${column}": CHECK is written CHECK (${column} IN ('a', 'b'))`;
658
+ if (!tokens[i] || tokens[i].kind !== "(") return { error: shape, line };
659
+ if (!tokens[i + 1] || tokens[i + 1].kind !== "word" || tokens[i + 1].text !== column)
660
+ return { error: `${shape}: CHECK names its own column`, line };
661
+ if (!isWord(tokens[i + 2], "IN") || !tokens[i + 3] || tokens[i + 3].kind !== "(")
662
+ return { error: shape, line };
663
+ /** @type {string[]} */
664
+ const values = [];
665
+ let j = i + 4;
666
+ while (tokens[j] && tokens[j].kind !== ")") {
667
+ const token = tokens[j];
668
+ if (token.kind !== "string") return { error: shape, line };
669
+ const v = token.text;
670
+ if (!VALUE_RE.test(v))
671
+ return {
672
+ error: `column "${column}": CHECK values are letters, digits, spaces, _ . - (at most 64 characters)`,
673
+ line,
674
+ };
675
+ if (values.includes(v))
676
+ return { error: `column "${column}": duplicate CHECK value '${v}'`, line };
677
+ values.push(v);
678
+ j++;
679
+ if (tokens[j] && tokens[j].kind === ",") j++;
680
+ }
681
+ if (!tokens[j] || !tokens[j + 1] || tokens[j + 1].kind !== ")") return { error: shape, line };
682
+ if (values.length === 0)
683
+ return { error: `column "${column}": CHECK needs at least one value`, line };
684
+ if (values.length > RULES.limits.valuesPerCheck)
685
+ return {
686
+ error: `column "${column}": at most ${RULES.limits.valuesPerCheck} CHECK values`,
687
+ line,
688
+ };
689
+ return { values, next: j + 2 };
690
+ }
691
+
692
+ /**
693
+ * Splits the tokens between "(" and its matching ")" on top-level commas.
694
+ * @param {Token[]} tokens @param {number} i @param {number} line @returns {{groups: Token[][], next: number} | ParseError}
695
+ */
696
+ function parseList(tokens, i, line) {
697
+ if (!tokens[i] || tokens[i].kind !== "(")
698
+ return { error: `expected ( after ${upper(tokens[i - 1])}`, line };
699
+ const groups = [];
700
+ let depth = 0;
701
+ let current = [];
702
+ let j = i + 1;
703
+ for (; j < tokens.length; j++) {
704
+ const t = tokens[j];
705
+ if (t.kind === "(") depth++;
706
+ if (t.kind === ")") {
707
+ if (depth === 0) break;
708
+ depth--;
709
+ }
710
+ if (t.kind === "," && depth === 0) {
711
+ groups.push(current);
712
+ current = [];
713
+ continue;
714
+ }
715
+ current.push(t);
716
+ }
717
+ if (j >= tokens.length) return { error: "missing )", line };
718
+ if (current.length > 0 || groups.length > 0) groups.push(current);
719
+ return { groups, next: j + 1 };
720
+ }
721
+
722
+ /** @param {Token[]} tokens @param {Token[]} comments @param {Record<string, Table>} tables @param {Token[]} [inner] @returns {{name: string, table: Table} | ParseError} */
723
+ function parseCreateTable(tokens, comments, tables, inner = []) {
724
+ const line = tokens[0].line;
725
+ let i = 2;
726
+ if (isWord(tokens[i], "IF") && isWord(tokens[i + 1], "NOT") && isWord(tokens[i + 2], "EXISTS"))
727
+ i += 3;
728
+ const nameTok = tokens[i];
729
+ if (!nameTok || nameTok.kind !== "word")
730
+ return { error: "expected a table name after CREATE TABLE", line };
731
+ const nameErr = checkName(nameTok.text, "table", line);
732
+ if (nameErr) return nameErr;
733
+ if (nameTok.text in tables) return { error: `table "${nameTok.text}" is declared twice`, line };
734
+ const list = parseList(tokens, i + 1, line);
735
+ if ("error" in list) return list;
736
+ if (list.groups.length === 0 || list.groups.every((g) => g.length === 0))
737
+ return { error: `table "${nameTok.text}" needs at least one column`, line };
738
+ /** @type {Record<string, Column>} */
739
+ const columns = {};
740
+ for (const g of list.groups) {
741
+ if (g.length === 0) return { error: `table "${nameTok.text}": empty column definition`, line };
742
+ const col = parseColumn(g, g[0].line);
743
+ if ("error" in col) return col;
744
+ if (col.name in columns)
745
+ return {
746
+ error: `column "${col.name}" is declared twice in "${nameTok.text}"`,
747
+ line: g[0].line,
748
+ };
749
+ // A column's doc is the comment on its own line (docs/adr/0109).
750
+ const last = g[g.length - 1].line;
751
+ const doc = inner
752
+ .filter((c) => c.line >= g[0].line && c.line <= last)
753
+ .map((c) => c.text ?? "")
754
+ .join(" ")
755
+ .trim();
756
+ if (doc.length > DOC_MAX_CHARS)
757
+ return {
758
+ error: `column "${col.name}": its doc comment is at most ${DOC_MAX_CHARS} characters`,
759
+ line: g[0].line,
760
+ };
761
+ columns[col.name] = doc ? { ...col.column, doc } : col.column;
762
+ }
763
+ if (Object.keys(columns).length > RULES.limits.columnsPerTable)
764
+ return {
765
+ error: `table "${nameTok.text}" declares more than ${RULES.limits.columnsPerTable} columns`,
766
+ line,
767
+ };
768
+ const options = parseTableOptions(tokens, list.next, nameTok.text, columns, line);
769
+ if ("error" in options) return options;
770
+ const policies = parsePolicies(comments);
771
+ if ("error" in policies) return policies;
772
+ /** @type {Table} */
773
+ const table = { columns, indexes: [], ...options.options };
774
+ if (policies.policies.read) table.read = policies.policies.read;
775
+ if (policies.policies.write) table.write = policies.policies.write;
776
+ return { name: nameTok.text, table };
777
+ }
778
+
779
+ /** The most columns EXACTLY ONE OF names (docs/adr/0109). */
780
+ const EXACTLY_ONE_MAX = 8;
781
+
782
+ /**
783
+ * What follows a Table's column list (docs/adr/0109), in any order: `LABEL '<singular>' ['<plural>']`,
784
+ * `DISPLAY (<columns>)`, `SINGLETON` and `EXACTLY ONE OF (<columns>)`.
785
+ * @param {Token[]} tokens @param {number} i @param {string} name @param {Record<string, Column>} columns @param {number} line
786
+ * @returns {{options: Pick<Table, "label" | "plural" | "display" | "singleton" | "exactlyOne">} | ParseError}
787
+ */
788
+ function parseTableOptions(tokens, i, name, columns, line) {
789
+ /** @type {Pick<Table, "label" | "plural" | "display" | "singleton" | "exactlyOne">} */
790
+ const options = {};
791
+ /** @param {string} what @param {number} at @returns {{names: string[], next: number} | ParseError} */
792
+ const names = (what, at) => {
793
+ const list = parseList(tokens, at, line);
794
+ if ("error" in list) return list;
795
+ /** @type {string[]} */
796
+ const out = [];
797
+ for (const g of list.groups) {
798
+ if (g.length !== 1 || g[0].kind !== "word")
799
+ return { error: `table "${name}": ${what} lists bare column names`, line };
800
+ const c = g[0].text;
801
+ if (!Object.hasOwn(columns, c))
802
+ return { error: `table "${name}": ${what} names "${c}", which it does not declare`, line };
803
+ if (out.includes(c)) return { error: `table "${name}": ${what} names "${c}" twice`, line };
804
+ out.push(c);
805
+ }
806
+ return { names: out, next: list.next };
807
+ };
808
+ const twice = (/** @type {string} */ what) => ({
809
+ error: `table "${name}": ${what} is given twice`,
810
+ line,
811
+ });
812
+ while (i < tokens.length) {
813
+ if (isWord(tokens[i], "LABEL")) {
814
+ if (options.label) return twice("LABEL");
815
+ const singular = labelText(tokens[i + 1], `table "${name}"`, line);
816
+ if (typeof singular !== "string") return singular;
817
+ options.label = singular;
818
+ i += 2;
819
+ if (tokens[i]?.kind === "string") {
820
+ const plural = labelText(tokens[i], `table "${name}"`, line);
821
+ if (typeof plural !== "string") return plural;
822
+ options.plural = plural;
823
+ i++;
824
+ }
825
+ continue;
826
+ }
827
+ if (isWord(tokens[i], "DISPLAY")) {
828
+ if (options.display) return twice("DISPLAY");
829
+ const r = names("DISPLAY", i + 1);
830
+ if ("error" in r) return r;
831
+ if (r.names.length === 0 || r.names.length > 2)
832
+ return { error: `table "${name}": DISPLAY names one or two columns`, line };
833
+ options.display = r.names;
834
+ i = r.next;
835
+ continue;
836
+ }
837
+ if (isWord(tokens[i], "SINGLETON")) {
838
+ if (options.singleton) return twice("SINGLETON");
839
+ options.singleton = true;
840
+ i++;
841
+ continue;
842
+ }
843
+ if (
844
+ isWord(tokens[i], "EXACTLY") &&
845
+ isWord(tokens[i + 1], "ONE") &&
846
+ isWord(tokens[i + 2], "OF")
847
+ ) {
848
+ if (options.exactlyOne) return twice("EXACTLY ONE OF");
849
+ const r = names("EXACTLY ONE OF", i + 3);
850
+ if ("error" in r) return r;
851
+ if (r.names.length < 2 || r.names.length > EXACTLY_ONE_MAX)
852
+ return {
853
+ error: `table "${name}": EXACTLY ONE OF names 2 to ${EXACTLY_ONE_MAX} columns`,
854
+ line,
855
+ };
856
+ options.exactlyOne = r.names;
857
+ i = r.next;
858
+ continue;
859
+ }
860
+ const key = refusedAt(tokens, i);
861
+ return key
862
+ ? refuse(key, line)
863
+ : {
864
+ error: `unexpected ${upper(tokens[i])} after the column list of "${name}": a Table may end with LABEL '<singular>' ['<plural>'], DISPLAY (<columns>), SINGLETON and EXACTLY ONE OF (<columns>)`,
865
+ line,
866
+ };
867
+ }
868
+ return { options };
869
+ }
870
+
871
+ /**
872
+ * `CREATE [UNIQUE] INDEX [IF NOT EXISTS] [<name>] ON <table> (<columns>)`; a unique index is enforced by the
873
+ * engine (docs/adr/0046).
874
+ * @param {Token[]} tokens @param {Record<string, Table>} tables @param {boolean} unique @returns {{} | ParseError}
875
+ */
876
+ function parseCreateIndex(tokens, tables, unique) {
877
+ const line = tokens[0].line;
878
+ let i = unique ? 3 : 2;
879
+ if (isWord(tokens[i], "IF") && isWord(tokens[i + 1], "NOT") && isWord(tokens[i + 2], "EXISTS"))
880
+ i += 3;
881
+ if (tokens[i] && tokens[i].kind === "word" && !isWord(tokens[i], "ON")) i++; // an index name: ignored
882
+ if (!isWord(tokens[i], "ON"))
883
+ return {
884
+ error: `expected ON <table> (<columns>) after CREATE ${unique ? "UNIQUE " : ""}INDEX`,
885
+ line,
886
+ };
887
+ const tableTok = tokens[i + 1];
888
+ if (!tableTok || tableTok.kind !== "word")
889
+ return { error: "expected a table name after ON", line };
890
+ const table = tables[tableTok.text];
891
+ if (!table)
892
+ return {
893
+ error: `CREATE INDEX: no table "${tableTok.text}" is declared above it in this file`,
894
+ line,
895
+ };
896
+ const list = parseList(tokens, i + 2, line);
897
+ if ("error" in list) return list;
898
+ const cols = [];
899
+ for (const g of list.groups) {
900
+ if (g.length !== 1 || g[0].kind !== "word")
901
+ return { error: "an index lists bare column names", line };
902
+ if (!(g[0].text in table.columns) && !SYSTEM_COLUMNS.includes(g[0].text))
903
+ return { error: `CREATE INDEX: no column "${g[0].text}" in "${tableTok.text}"`, line };
904
+ cols.push(g[0].text);
905
+ }
906
+ if (cols.length === 0) return { error: "an index needs at least one column", line };
907
+ if (list.next < tokens.length)
908
+ return { error: `unexpected ${upper(tokens[list.next])} after the index columns`, line };
909
+ if (unique) (table.unique ??= []).push(cols);
910
+ else table.indexes.push(cols);
911
+ return {};
912
+ }
913
+
914
+ /**
915
+ * Parses a Site's db/schema.sql. Returns the Declaration, or `{ error, line }` naming the rule that refused it.
916
+ * @type {typeof import("./schema.d.mts").parseSchema}
917
+ */
918
+ export function parseSchema(sql) {
919
+ const tok = tokenize(sql);
920
+ if ("error" in tok) return tok;
921
+ const split = splitStatements(tok.tokens);
922
+ if ("error" in split) return split;
923
+ /** @type {Record<string, Table>} */
924
+ const tables = {};
925
+ for (const { tokens, comments, inner } of split.statements) {
926
+ const first = tokens[0];
927
+ if (isWord(first, "CREATE") && isWord(tokens[1], "TABLE")) {
928
+ const r = parseCreateTable(tokens, comments, tables, inner);
929
+ if ("error" in r) return r;
930
+ tables[r.name] = r.table;
931
+ continue;
932
+ }
933
+ if (isWord(first, "CREATE") && isWord(tokens[1], "INDEX")) {
934
+ const r = parseCreateIndex(tokens, tables, false);
935
+ if ("error" in r) return r;
936
+ continue;
937
+ }
938
+ if (isWord(first, "CREATE") && isWord(tokens[1], "UNIQUE") && isWord(tokens[2], "INDEX")) {
939
+ const r = parseCreateIndex(tokens, tables, true);
940
+ if ("error" in r) return r;
941
+ continue;
942
+ }
943
+ const key = refusedAt(tokens, 0) ?? (isWord(first, "CREATE") ? refusedAt(tokens, 1) : null);
944
+ if (key) return refuse(key, first.line);
945
+ return {
946
+ error: `unexpected ${upper(first)}: db/schema.sql holds CREATE TABLE, CREATE INDEX and CREATE UNIQUE INDEX statements only`,
947
+ line: first.line,
948
+ };
949
+ }
950
+ return { tables };
951
+ }
952
+
953
+ // ---- the planner ----------------------------------------------------------------------------------------
954
+ //
955
+ // From what is live (tables, their storage columns, their index names, every Site's registered Declaration)
956
+ // and what this Site declares, the additive DDL to run at deploy. Never a DROP, never an ALTER other than ADD
957
+ // COLUMN. A column two Sites declare must be declared identically: a difference is a conflict, the deploy is
958
+ // refused, and the other Site changes its declaration first. Table and column names are validated by
959
+ // parseSchema, so they are interpolated bare; nothing here comes from a request.
960
+
961
+ /**
962
+ * A declared table `tickets` of Instance `nike` is physically `data_nike_tickets`. Instance ids hold no `_`.
963
+ * @type {typeof import("./schema.d.mts").physicalName}
964
+ */
965
+ export const physicalName = (instance, table) => `${TABLE_PREFIX}${instance}_${table}`;
966
+ /**
967
+ * `data_nike_t__a__b`; a unique index is `data_nike_t__unique__a__b` (`unique` is a refused column name, so
968
+ * the marker is unambiguous).
969
+ * @type {typeof import("./schema.d.mts").indexName}
970
+ */
971
+ export const indexName = (instance, table, cols, unique = false) =>
972
+ `${physicalName(instance, table)}__${unique ? `${UNIQUE_MARK}__` : ""}${cols.join("__")}`;
973
+ const UNIQUE_MARK = "unique";
974
+ /**
975
+ * The column list an index name encodes and whether it is unique, or null when it is not one of this table's.
976
+ * @type {typeof import("./schema.d.mts").indexColumns}
977
+ */
978
+ export function indexColumns(instance, table, name) {
979
+ const prefix = `${physicalName(instance, table)}__`;
980
+ if (!name.startsWith(prefix)) return null;
981
+ const parts = name.slice(prefix.length).split("__");
982
+ if (parts[0] === UNIQUE_MARK && parts.length > 1)
983
+ return { columns: parts.slice(1), unique: true };
984
+ return { columns: parts, unique: false };
985
+ }
986
+ /** The columns of a Declaration that are sequences (docs/adr/0046). @param {Table} def */
987
+ const sequenceColumns = (def) =>
988
+ Object.entries(def.columns)
989
+ .filter(([, c]) => c.sequence)
990
+ .map(([c]) => c);
991
+ /** @param {string[]} cols */
992
+ const indexKey = (cols) => cols.join("\0");
993
+ /** @param {string[]} values */
994
+ const quoted = (values) => values.map((v) => `'${v}'`).join(", ");
995
+ /**
996
+ * A column as it is written in a declaration; `name` is needed to render a CHECK.
997
+ * @type {typeof import("./schema.d.mts").describeColumn}
998
+ */
999
+ export const describeColumn = (c, name = "value") =>
1000
+ `${c.type}${c.shape ? ` TYPE '${c.shape.replaceAll("'", "''")}'` : ""}${c.required ? " NOT NULL" : ""}${c.ref ? ` REFERENCES ${c.ref}${c.onDelete ? " ON DELETE RESTRICT" : ""}` : ""}${c.values ? ` CHECK (${name} IN (${quoted(c.values)}))` : ""}${c.default ? ` DEFAULT ${printDefault(c.default)}` : ""}${c.sequence ? " SEQUENCE" : ""}`;
1001
+
1002
+ /**
1003
+ * A declared default as it is written (docs/adr/0097): `'open'`, `0`, `true`, `now`, `me`.
1004
+ * @type {typeof import("./schema.d.mts").printDefault}
1005
+ */
1006
+ export function printDefault(d) {
1007
+ if (d.kind !== "value") return d.kind;
1008
+ return typeof d.value === "string" ? `'${d.value.replaceAll("'", "''")}'` : String(d.value);
1009
+ }
1010
+
1011
+ /**
1012
+ * The value an insert that omits the column stores (docs/adr/0097), in storage form: booleans as 0/1, `now`
1013
+ * as milliseconds, `me` as the inserting Member's actor id or null.
1014
+ * @type {typeof import("./schema.d.mts").storedDefault}
1015
+ */
1016
+ export function storedDefault(d, context) {
1017
+ if (d.kind === "now") return context.now;
1018
+ if (d.kind === "me") return context.me ?? null;
1019
+ return typeof d.value === "boolean" ? (d.value ? 1 : 0) : d.value;
1020
+ }
1021
+
1022
+ /**
1023
+ * The defaults a Global Push adds, changes or removes (docs/adr/0096, 0097): Live definitions, listed under
1024
+ * "Takes effect now". A Table or column new in `next` counts when it declares a default.
1025
+ * @type {typeof import("./schema.d.mts").defaultChanges}
1026
+ */
1027
+ export function defaultChanges(before, next) {
1028
+ /** @type {import("./schema.d.mts").DefaultChange[]} */
1029
+ const out = [];
1030
+ for (const [table, def] of Object.entries(next.tables))
1031
+ for (const [column, col] of Object.entries(def.columns)) {
1032
+ const was = before.tables[table]?.columns[column]?.default;
1033
+ const from = was ? printDefault(was) : null;
1034
+ const to = col.default ? printDefault(col.default) : null;
1035
+ if (from !== to) out.push({ table, column, from, to });
1036
+ }
1037
+ return out;
1038
+ }
1039
+
1040
+ // ---- SQLite dialect: every engine-specific statement template ------------------------------------------
1041
+ //
1042
+ // The only SQLite-flavoured text in the contract: default expressions, STRICT, the bookkeeping triggers and
1043
+ // the CHECK-enforcement triggers (SQLite cannot alter a table's own CHECK once created, so a value set that
1044
+ // grows over deploys lives in triggers that deploy drops and recreates). A Postgres backend replaces this
1045
+ // section and nothing else.
1046
+
1047
+ const NOW = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
1048
+ const VERSIONS = `${PLATFORM_PREFIX}versions`;
1049
+ const CONTEXT = `${PLATFORM_PREFIX}context`;
1050
+ /** The actor of the write batch in flight (docs/adr/0040); app-db.ts sets it first in every write batch. */
1051
+ const ACTOR = `(SELECT actor FROM ${CONTEXT} WHERE id = 1)`;
1052
+ /** The write's reason (docs/adr/0093), set beside the actor; null when the write gave none. */
1053
+ const WHY = `(SELECT why FROM ${CONTEXT} WHERE id = 1)`;
1054
+ /** The workflow action that wrote the version (docs/adr/0103), or null. */
1055
+ const TRANSITION = `(SELECT transition FROM ${CONTEXT} WHERE id = 1)`;
1056
+ /** @param {string} instance @param {string} table */
1057
+ const versionOf = (instance, table) =>
1058
+ `(SELECT version FROM ${VERSIONS} WHERE instance_id = '${instance}' AND name = '${table}')`;
1059
+ /** @param {string} instance @param {string} table */
1060
+ const versionRow = (instance, table) =>
1061
+ `INSERT INTO ${VERSIONS} (instance_id, name, version) VALUES ('${instance}', '${table}', 0) ON CONFLICT(instance_id, name) DO NOTHING`;
1062
+ /**
1063
+ * The snapshot columns a History row copies from its Table, in storage order.
1064
+ * @param {Record<string, import("./schema.d.mts").StorageType>} columns
1065
+ */
1066
+ const snapshotColumns = (columns) => [
1067
+ "created_at",
1068
+ "created_by",
1069
+ "updated_at",
1070
+ "updated_by",
1071
+ ...Object.keys(columns),
1072
+ ];
1073
+
1074
+ /**
1075
+ * A Declaration's columns as storage types: what the DDL generators take, so live tables can feed them too.
1076
+ * @type {typeof import("./schema.d.mts").storageColumns}
1077
+ */
1078
+ export const storageColumns = (def) =>
1079
+ Object.fromEntries(Object.entries(def.columns).map(([c, d]) => [c, RULES.types[d.type]]));
1080
+
1081
+ /**
1082
+ * The indexes the platform gives every Table and its History, whatever the Declaration says: `created_at` for
1083
+ * a live query's default order, and `(row_id, version)` / `(row_id, valid_to)` for the bookkeeping triggers,
1084
+ * which find a row's latest History entry and its open one on every update and delete. Without the last two,
1085
+ * SQLite answers `valid_to = <open>` from the `(valid_to)` index, which holds every open row of the Table.
1086
+ * `IF NOT EXISTS` throughout: a Declaration's `CREATE INDEX ON t (created_at)` names the same index.
1087
+ * @type {typeof import("./schema.d.mts").lookupIndexStatements}
1088
+ */
1089
+ export function lookupIndexStatements(instance, table) {
1090
+ return [
1091
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, table, ["created_at"])} ON ${physicalName(instance, table)} (created_at)`,
1092
+ ...historyLookupIndexStatements(instance, table),
1093
+ ];
1094
+ }
1095
+
1096
+ /** @param {string} instance @param {string} table */
1097
+ function historyLookupIndexStatements(instance, table) {
1098
+ const history = historyName(table);
1099
+ const h = physicalName(instance, history);
1100
+ return [
1101
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, history, ["row_id", "version"])} ON ${h} (row_id, version)`,
1102
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, history, ["row_id", "valid_to"])} ON ${h} (row_id, valid_to)`,
1103
+ // A History read's default order, and a feed's or the guard replay's newest first, without a sort.
1104
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, history, ["version"])} ON ${h} (version)`,
1105
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, history, ["valid_from"])} ON ${h} (valid_from)`,
1106
+ ];
1107
+ }
1108
+
1109
+ /**
1110
+ * The History table and its indexes (docs/adr/0040). `columns` are the Table's, name -> storage type.
1111
+ * @type {typeof import("./schema.d.mts").historyStatements}
1112
+ */
1113
+ export function historyStatements(instance, table, columns) {
1114
+ const h = physicalName(instance, historyName(table));
1115
+ const cols = Object.entries(columns)
1116
+ .map(([c, t]) => `, ${c} ${t}`)
1117
+ .join("");
1118
+ return [
1119
+ `CREATE TABLE IF NOT EXISTS ${h} (id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))), created_at INTEGER NOT NULL, created_by TEXT, updated_at INTEGER NOT NULL, updated_by TEXT, row_id TEXT NOT NULL, op TEXT NOT NULL, valid_from INTEGER NOT NULL, valid_to INTEGER NOT NULL, by TEXT, version INTEGER NOT NULL, why TEXT, transition TEXT${cols}) STRICT`,
1120
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, historyName(table), ["row_id", "valid_from"])} ON ${h} (row_id, valid_from)`,
1121
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, historyName(table), ["valid_to"])} ON ${h} (valid_to)`,
1122
+ ...historyLookupIndexStatements(instance, table),
1123
+ ];
1124
+ }
1125
+
1126
+ /**
1127
+ * The three bookkeeping triggers: the version bump live queries poll, `updated_at`, the actor stamps and
1128
+ * the History rows. They enumerate columns, so a plan that changes the column list drops and recreates
1129
+ * them (like the CHECK triggers). SQLite runs them with recursive triggers off, so a trigger's own UPDATE
1130
+ * of the Table never re-fires that trigger; the insert trigger's actor stamp would fire the update
1131
+ * trigger, though, so that one listens to every column but `created_by` and `updated_by`. An update
1132
+ * that sets only those two is not a change and leaves no History row. A sequence column (docs/adr/0046) is
1133
+ * assigned by the insert trigger the same way, before the History row is written, so it is left out of the
1134
+ * watched list too: a backfill that sets only a sequence column leaves no History row.
1135
+ * @type {typeof import("./schema.d.mts").bookkeepingTriggerStatements}
1136
+ */
1137
+ export function bookkeepingTriggerStatements(instance, table, columns, sequences = []) {
1138
+ const p = physicalName(instance, table);
1139
+ const h = physicalName(instance, historyName(table));
1140
+ const watched = [
1141
+ "id",
1142
+ "created_at",
1143
+ "updated_at",
1144
+ ...Object.keys(columns).filter((c) => !sequences.includes(c)),
1145
+ ].join(", ");
1146
+ const assign = sequences
1147
+ .map(
1148
+ (c) =>
1149
+ `UPDATE ${p} SET ${c} = (SELECT COALESCE(MAX(${c}), 0) + 1 FROM ${p}) WHERE id = NEW.id AND ${c} IS NULL; `,
1150
+ )
1151
+ .join("");
1152
+ const list = snapshotColumns(columns).join(", ");
1153
+ const oldList = snapshotColumns(columns)
1154
+ .map((c) => `OLD.${c}`)
1155
+ .join(", ");
1156
+ const bump = `UPDATE ${VERSIONS} SET version = version + 1 WHERE instance_id = '${instance}' AND name = '${table}';`;
1157
+ const close = `UPDATE ${h} SET valid_to = ${NOW} WHERE row_id = OLD.id AND valid_to = ${HISTORY_OPEN};`;
1158
+ const closedAt = `COALESCE((SELECT valid_to FROM ${h} WHERE row_id = OLD.id ORDER BY version DESC LIMIT 1), ${NOW})`;
1159
+ /** @param {string} op @param {string} from */
1160
+ const snapshot = (op, from) =>
1161
+ `INSERT INTO ${h} (${list}, row_id, op, valid_from, valid_to, by, version, why, transition) SELECT ${list}, id, '${op}', ${from}, ${HISTORY_OPEN}, ${ACTOR}, ${versionOf(instance, table)}, ${WHY}, ${TRANSITION} FROM ${p} WHERE id = NEW.id;`;
1162
+ return [
1163
+ `DROP TRIGGER IF EXISTS ${p}__ai`,
1164
+ `CREATE TRIGGER ${p}__ai AFTER INSERT ON ${p} BEGIN ${bump} ${assign}UPDATE ${p} SET created_by = COALESCE(created_by, ${ACTOR}), updated_by = COALESCE(updated_by, ${ACTOR}) WHERE id = NEW.id; ${snapshot("insert", NOW)} END`,
1165
+ `DROP TRIGGER IF EXISTS ${p}__au`,
1166
+ `CREATE TRIGGER ${p}__au AFTER UPDATE OF ${watched} ON ${p} BEGIN ${bump} UPDATE ${p} SET updated_at = ${NOW} WHERE id = NEW.id AND NEW.updated_at = OLD.updated_at; UPDATE ${p} SET updated_by = ${ACTOR} WHERE id = NEW.id AND NEW.updated_by IS OLD.updated_by AND ${ACTOR} IS NOT NULL; ${close} ${snapshot("update", closedAt)} END`,
1167
+ `DROP TRIGGER IF EXISTS ${p}__ad`,
1168
+ `CREATE TRIGGER ${p}__ad AFTER DELETE ON ${p} BEGIN ${bump} ${close} INSERT INTO ${h} (${list}, row_id, op, valid_from, valid_to, by, version, why, transition) SELECT ${oldList}, OLD.id, 'delete', c, c, ${ACTOR}, ${versionOf(instance, table)}, ${WHY}, ${TRANSITION} FROM (SELECT ${closedAt} AS c); END`,
1169
+ ];
1170
+ }
1171
+
1172
+ /**
1173
+ * One History row per Table row that has none yet: `op = 'seed'`, no actor, an open period from now.
1174
+ * @type {typeof import("./schema.d.mts").seedHistoryStatement}
1175
+ */
1176
+ export function seedHistoryStatement(instance, table, columns) {
1177
+ const p = physicalName(instance, table);
1178
+ const h = physicalName(instance, historyName(table));
1179
+ const list = snapshotColumns(columns).join(", ");
1180
+ return `INSERT INTO ${h} (${list}, row_id, op, valid_from, valid_to, by, version) SELECT ${list}, id, 'seed', ${NOW}, ${HISTORY_OPEN}, NULL, ${versionOf(instance, table)} FROM ${p} WHERE NOT EXISTS (SELECT 1 FROM ${h} WHERE ${h}.row_id = ${p}.id)`;
1181
+ }
1182
+
1183
+ /**
1184
+ * Everything a Table that exists without a History needs, from its live columns.
1185
+ * @type {typeof import("./schema.d.mts").installHistoryStatements}
1186
+ */
1187
+ export function installHistoryStatements(instance, table, columns) {
1188
+ return [
1189
+ versionRow(instance, table),
1190
+ ...historyStatements(instance, table, columns),
1191
+ ...bookkeepingTriggerStatements(instance, table, columns),
1192
+ seedHistoryStatement(instance, table, columns),
1193
+ ];
1194
+ }
1195
+
1196
+ /**
1197
+ * The statements that bring a new table into existence: the strict table, its `created_at` index, its versions row,
1198
+ * its History, its triggers.
1199
+ * @type {typeof import("./schema.d.mts").createTableStatements}
1200
+ */
1201
+ export function createTableStatements(instance, table, def) {
1202
+ const p = physicalName(instance, table);
1203
+ const columns = storageColumns(def);
1204
+ const cols = Object.entries(columns)
1205
+ .map(([c, t]) => `, ${c} ${t}`)
1206
+ .join("");
1207
+ const statements = [
1208
+ `CREATE TABLE ${p} (id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))), created_at INTEGER NOT NULL DEFAULT (${NOW}), created_by TEXT, updated_at INTEGER NOT NULL DEFAULT (${NOW}), updated_by TEXT${cols}) STRICT`,
1209
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, table, ["created_at"])} ON ${p} (created_at)`,
1210
+ versionRow(instance, table),
1211
+ ...historyStatements(instance, table, columns),
1212
+ ...bookkeepingTriggerStatements(instance, table, columns, sequenceColumns(def)),
1213
+ ];
1214
+ for (const [c, d] of Object.entries(def.columns)) {
1215
+ if (d.values) statements.push(...checkTriggerStatements(instance, table, c, d.values));
1216
+ if (d.sequence) statements.push(...sequenceTriggerStatements(instance, table, c));
1217
+ }
1218
+ return statements;
1219
+ }
1220
+
1221
+ /**
1222
+ * The trigger that holds an assigned sequence value (docs/adr/0046): only null may change, on every path,
1223
+ * so a Builder can backfill rows older than the column and nothing can renumber. Recreated on every deploy.
1224
+ * @type {typeof import("./schema.d.mts").sequenceTriggerStatements}
1225
+ */
1226
+ export function sequenceTriggerStatements(instance, table, column) {
1227
+ const p = physicalName(instance, table);
1228
+ return [
1229
+ `DROP TRIGGER IF EXISTS ${p}__sq_${column}`,
1230
+ `CREATE TRIGGER ${p}__sq_${column} BEFORE UPDATE OF ${column} ON ${p} WHEN OLD.${column} IS NOT NULL AND NEW.${column} IS NOT OLD.${column} BEGIN SELECT RAISE(ABORT, '${column} is a sequence and cannot be changed once assigned'); END`,
1231
+ ];
1232
+ }
1233
+
1234
+ /**
1235
+ * The two triggers that hold a CHECK column to its values; dropped and recreated on every deploy.
1236
+ * @type {typeof import("./schema.d.mts").checkTriggerStatements}
1237
+ */
1238
+ export function checkTriggerStatements(instance, table, column, values) {
1239
+ const p = physicalName(instance, table);
1240
+ const list = quoted(values);
1241
+ const raise = `SELECT RAISE(ABORT, '${column} must be one of: ${values.join(", ")}');`;
1242
+ const when = `WHEN NEW.${column} IS NOT NULL AND NEW.${column} NOT IN (${list})`;
1243
+ return [
1244
+ `DROP TRIGGER IF EXISTS ${p}__ck_${column}_i`,
1245
+ `CREATE TRIGGER ${p}__ck_${column}_i BEFORE INSERT ON ${p} ${when} BEGIN ${raise} END`,
1246
+ `DROP TRIGGER IF EXISTS ${p}__ck_${column}_u`,
1247
+ `CREATE TRIGGER ${p}__ck_${column}_u BEFORE UPDATE OF ${column} ON ${p} ${when} BEGIN ${raise} END`,
1248
+ ];
1249
+ }
1250
+
1251
+ /** @param {string[] | null} a @param {string[] | null} b */
1252
+ const sameValues = (a, b) =>
1253
+ (a === null && b === null) ||
1254
+ (a !== null && b !== null && a.length === b.length && a.every((v, i) => v === b[i]));
1255
+ /**
1256
+ * A DATE is a validated TEXT (docs/adr/0078) and MONEY an INTEGER of cents (docs/adr/0107): each pair never
1257
+ * conflicts, and a column may move between them.
1258
+ */
1259
+ const typeKind = (/** @type {Column["type"]} */ t) =>
1260
+ t === "DATE" ? "TEXT" : t === "MONEY" ? "INTEGER" : t;
1261
+ /**
1262
+ * Whether two declarations of one column agree. A JSON column's TYPE and DATE vs TEXT are left out: they
1263
+ * change what writes accept, never storage, and a Push checks the rows before tightening them.
1264
+ * @param {Column} a @param {Column} b
1265
+ */
1266
+ const sameColumn = (a, b) =>
1267
+ typeKind(a.type) === typeKind(b.type) &&
1268
+ // A JSON column may gain REFERENCES, becoming an id list (docs/adr/0102); its rows are checked as string[].
1269
+ (a.ref === b.ref || (a.type === "JSON" && a.ref === null && b.ref !== null)) &&
1270
+ sameValues(a.values ?? null, b.values ?? null) &&
1271
+ (a.sequence ?? false) === (b.sequence ?? false);
1272
+
1273
+ /**
1274
+ * The authored global schema. The older parser remains able to read retained Site declarations.
1275
+ * @type {typeof import("./schema.d.mts").parseGlobalSchema}
1276
+ */
1277
+ export function parseGlobalSchema(sql) {
1278
+ const declaration = parseSchema(sql);
1279
+ if ("error" in declaration) return declaration;
1280
+ for (const [table, def] of Object.entries(declaration.tables))
1281
+ for (const [name, column] of Object.entries(def.columns))
1282
+ if (column.required)
1283
+ return {
1284
+ error: `${table}.${name}: all user-defined columns are nullable; NOT NULL is not supported. Require values in the app's workflow.`,
1285
+ line: 1,
1286
+ };
1287
+ return declaration;
1288
+ }
1289
+
1290
+ /**
1291
+ * A global Push cannot remove or redefine anything already published, even before the first build.
1292
+ * @type {typeof import("./schema.d.mts").schemaChangeError}
1293
+ */
1294
+ export function schemaChangeError(previous, next) {
1295
+ for (const [name, table] of Object.entries(previous.tables)) {
1296
+ const added = next.tables[name];
1297
+ if (!added) return `${name}: published Tables cannot be removed or renamed.`;
1298
+ for (const [column, def] of Object.entries(table.columns)) {
1299
+ const other = added.columns[column];
1300
+ if (!other) return `${name}.${column}: published columns cannot be removed or renamed.`;
1301
+ if (!sameColumn(def, other))
1302
+ return `${name}.${column}: published types, references, enum values and sequences cannot change. Add a new column instead.`;
1303
+ }
1304
+ if (table.read !== added.read || table.write !== added.write)
1305
+ return `${name}: published read/write policies cannot change in a schema addition.`;
1306
+ // Indexed columns stay indexed. A plain index may become unique (the plain index is kept physically); a
1307
+ // unique index may become plain, the one relaxation the rule permits (docs/adr/0046).
1308
+ const stillIndexed = (/** @type {string[]} */ index) =>
1309
+ [...added.indexes, ...(added.unique ?? [])].some(
1310
+ (columns) => indexKey(columns) === indexKey(index),
1311
+ );
1312
+ for (const index of table.indexes)
1313
+ if (!stillIndexed(index)) return `${name}: published indexes cannot be removed or changed.`;
1314
+ for (const index of table.unique ?? [])
1315
+ if (!stillIndexed(index))
1316
+ return `${name}: a published unique index may become a plain index (CREATE INDEX) but cannot be removed.`;
1317
+ }
1318
+ return null;
1319
+ }
1320
+
1321
+ /**
1322
+ * @type {typeof import("./schema.d.mts").planSchema}
1323
+ */
1324
+ export function planSchema(schema, mine, instance, siteId) {
1325
+ const statements = [];
1326
+ const conflicts = [];
1327
+ /** @type {import("./schema.d.mts").PlanSummary} */
1328
+ const summary = { created: [], added: [], indexed: [] };
1329
+ const others = Object.entries(schema.declarations).filter(([s]) => s !== siteId);
1330
+
1331
+ for (const [t, def] of Object.entries(mine.tables)) {
1332
+ const live = schema.live.tables[t];
1333
+ for (const [c, col] of Object.entries(def.columns)) {
1334
+ let found = false;
1335
+ for (const [site, tables] of others) {
1336
+ const theirs = tables[t]?.columns?.[c];
1337
+ if (!theirs) continue;
1338
+ found = true;
1339
+ if (!sameColumn(col, theirs))
1340
+ conflicts.push({
1341
+ table: t,
1342
+ column: c,
1343
+ mine: describeColumn(col, c),
1344
+ theirs: describeColumn(theirs, c),
1345
+ site,
1346
+ });
1347
+ }
1348
+ if (!found && live && c in live.columns && live.columns[c] !== RULES.types[col.type])
1349
+ conflicts.push({
1350
+ table: t,
1351
+ column: c,
1352
+ mine: describeColumn(col, c),
1353
+ theirs: `stored as ${live.columns[c]}`,
1354
+ site: null,
1355
+ });
1356
+ }
1357
+ // Values are add-only: a value any registered declaration (this Site's previous one included) has must stay.
1358
+ for (const [c, col] of Object.entries(def.columns)) {
1359
+ const values = col.values;
1360
+ if (!values) continue;
1361
+ for (const [site, tables] of Object.entries(schema.declarations)) {
1362
+ const prev = tables[t]?.columns?.[c]?.values;
1363
+ if (!prev) continue;
1364
+ const missing = prev.find((v) => !values.includes(v));
1365
+ if (missing !== undefined)
1366
+ return {
1367
+ error: `${t}.${c}: CHECK values are add-only; '${missing}' is declared${site === siteId ? "" : ` by site "${site}"`} and cannot be removed`,
1368
+ };
1369
+ }
1370
+ }
1371
+ if (!live) {
1372
+ statements.push(...createTableStatements(instance, t, def));
1373
+ summary.created.push(t);
1374
+ } else {
1375
+ // The History mirrors every physical column, declared today or not (docs/adr/0040).
1376
+ const columns = { ...live.columns };
1377
+ let grown = false;
1378
+ for (const [c, col] of Object.entries(def.columns)) {
1379
+ if (c in live.columns) continue;
1380
+ statements.push(
1381
+ `ALTER TABLE ${physicalName(instance, t)} ADD COLUMN ${c} ${RULES.types[col.type]}`,
1382
+ );
1383
+ columns[c] = RULES.types[col.type];
1384
+ grown = true;
1385
+ summary.added.push(`${t}.${c}`);
1386
+ }
1387
+ const history = schema.live.tables[historyName(t)];
1388
+ if (!history) statements.push(...installHistoryStatements(instance, t, columns));
1389
+ else if (grown) {
1390
+ for (const [c, type] of Object.entries(columns))
1391
+ if (!(c in history.columns))
1392
+ statements.push(
1393
+ `ALTER TABLE ${physicalName(instance, historyName(t))} ADD COLUMN ${c} ${type}`,
1394
+ );
1395
+ statements.push(
1396
+ ...bookkeepingTriggerStatements(instance, t, columns, sequenceColumns(def)),
1397
+ );
1398
+ }
1399
+ // The enforcement triggers are recreated on every deploy so a grown value set takes effect.
1400
+ for (const [c, col] of Object.entries(def.columns)) {
1401
+ if (col.values) statements.push(...checkTriggerStatements(instance, t, c, col.values));
1402
+ if (col.sequence) statements.push(...sequenceTriggerStatements(instance, t, c));
1403
+ }
1404
+ }
1405
+ const liveIndexes = new Set((live?.indexes ?? []).map(indexKey));
1406
+ const liveUnique = new Set((live?.unique ?? []).map(indexKey));
1407
+ // A sequence column always has a unique index (docs/adr/0046).
1408
+ const unique = [...(def.unique ?? []), ...sequenceColumns(def).map((c) => [c])];
1409
+ const wantUnique = new Set(unique.map(indexKey));
1410
+ // Demotion: a live unique index the declaration now lists as a plain index is dropped, the one DROP the
1411
+ // planner emits (docs/adr/0046); the columns stay indexed by the plain index created below.
1412
+ for (const cols of live?.unique ?? []) {
1413
+ const key = indexKey(cols);
1414
+ if (wantUnique.has(key) || !def.indexes.some((c) => indexKey(c) === key)) continue;
1415
+ statements.push(`DROP INDEX IF EXISTS ${indexName(instance, t, cols, true)}`);
1416
+ liveUnique.delete(key);
1417
+ summary.indexed.push(`${t} (${cols.join(", ")}) no longer unique`);
1418
+ }
1419
+ for (const cols of def.indexes) {
1420
+ const key = indexKey(cols);
1421
+ if (liveIndexes.has(key)) continue;
1422
+ liveIndexes.add(key);
1423
+ statements.push(
1424
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, t, cols)} ON ${physicalName(instance, t)} (${cols.join(", ")})`,
1425
+ );
1426
+ summary.indexed.push(`${t} (${cols.join(", ")})`);
1427
+ }
1428
+ for (const cols of unique) {
1429
+ const key = indexKey(cols);
1430
+ if (liveUnique.has(key)) continue;
1431
+ liveUnique.add(key);
1432
+ statements.push(
1433
+ `CREATE UNIQUE INDEX IF NOT EXISTS ${indexName(instance, t, cols, true)} ON ${physicalName(instance, t)} (${cols.join(", ")})`,
1434
+ );
1435
+ summary.indexed.push(`${t} (${cols.join(", ")}) UNIQUE`);
1436
+ }
1437
+ // ADR 0143: a delete checks every ON DELETE RESTRICT column for the row's id, inside the writer; an index
1438
+ // the Declaration does not give it, the platform does, under the name a declared one would have.
1439
+ for (const [c, col] of Object.entries(def.columns)) {
1440
+ if (col.onDelete !== "restrict" || leadsIndex(def, c)) continue;
1441
+ const key = indexKey([c]);
1442
+ if (liveIndexes.has(key) || liveUnique.has(key)) continue;
1443
+ liveIndexes.add(key);
1444
+ statements.push(
1445
+ `CREATE INDEX IF NOT EXISTS ${indexName(instance, t, [c])} ON ${physicalName(instance, t)} (${c})`,
1446
+ );
1447
+ summary.indexed.push(`${t} (${c}) for ON DELETE RESTRICT`);
1448
+ }
1449
+ }
1450
+
1451
+ const liveNames = Object.keys(schema.live.tables);
1452
+ const total =
1453
+ liveNames.filter((n) => historyParent(n, liveNames) === null).length + summary.created.length;
1454
+ if (total > RULES.limits.tablesPerInstance)
1455
+ return {
1456
+ error: `this would make ${total} tables; the instance allows ${RULES.limits.tablesPerInstance} tables`,
1457
+ };
1458
+ return { statements: conflicts.length > 0 ? [] : statements, conflicts, summary };
1459
+ }
1460
+
1461
+ /**
1462
+ * The unique indexes a Declaration adds to Tables that already exist (docs/adr/0046): the ones whose rows the
1463
+ * platform checks for duplicates before a Push, a Preview or a Deploy. Sequence columns count, since each
1464
+ * carries a unique index.
1465
+ * @type {typeof import("./schema.d.mts").newUniqueIndexes}
1466
+ */
1467
+ export function newUniqueIndexes(live, decl) {
1468
+ const out = [];
1469
+ for (const [table, def] of Object.entries(decl.tables)) {
1470
+ const existing = live.tables[table];
1471
+ if (!existing) continue;
1472
+ const have = new Set((existing.unique ?? []).map(indexKey));
1473
+ for (const columns of [...(def.unique ?? []), ...sequenceColumns(def).map((c) => [c])])
1474
+ if (!have.has(indexKey(columns))) out.push({ table, columns });
1475
+ }
1476
+ return out;
1477
+ }
1478
+
1479
+ // ---- the page API's language --------------------------------------------------------------------------
1480
+ //
1481
+ // Pages read and write rows through <prefix>/_ez/db/<table> (app-data.ts in the platform). These validators
1482
+ // are pure: the platform runs them against the Site's registered Declaration before touching the store, and
1483
+ // the same rules describe the API in `ez help db`. Values leave here in storage form (booleans as 0/1, JSON as
1484
+ // text, timestamps as milliseconds); fromStorage() converts rows back.
1485
+
1486
+ const SYSTEM_TYPES = Object.freeze({
1487
+ id: "TEXT",
1488
+ created_at: "TIMESTAMP",
1489
+ created_by: "TEXT",
1490
+ updated_at: "TIMESTAMP",
1491
+ updated_by: "TEXT",
1492
+ });
1493
+
1494
+ /** @type {typeof import("./schema.d.mts").QUERY_MAX_LIMIT} */
1495
+ export const QUERY_MAX_LIMIT = 1000;
1496
+ /** @type {typeof import("./schema.d.mts").QUERY_DEFAULT_LIMIT} */
1497
+ export const QUERY_DEFAULT_LIMIT = 100;
1498
+ /** @type {typeof import("./schema.d.mts").ACTORS_TABLE} */
1499
+ export const ACTORS_TABLE = {
1500
+ view: "actors",
1501
+ columns: Object.fromEntries(
1502
+ ["id", "kind", "name", "email"].map((name) => [
1503
+ name,
1504
+ { type: "TEXT", required: true, ref: null, values: null },
1505
+ ]),
1506
+ ),
1507
+ indexes: [],
1508
+ read: "member",
1509
+ write: "none",
1510
+ };
1511
+ const OPS = Object.freeze(
1512
+ /** @type {const} */ (["eq", "ne", "lt", "lte", "gt", "gte", "in", "nin", "like", "null", "has"]),
1513
+ );
1514
+ /** How deep a where path or an include may follow references (docs/adr/0102). */
1515
+ const MAX_PATH = 3;
1516
+ /** How many includes one query may carry, nested ones counted. */
1517
+ const MAX_INCLUDES = 12;
1518
+ /** How deep `or` and `and` may nest. */
1519
+ const MAX_OR = 4;
1520
+ /** The children a reverse include brings per row, at most (docs/adr/0102). */
1521
+ export const MAX_CHILDREN = 100;
1522
+
1523
+ /**
1524
+ * A table's read and write policy for End Users: declared, or the defaults.
1525
+ * @type {typeof import("./schema.d.mts").effectivePolicies}
1526
+ */
1527
+ export function effectivePolicies(table) {
1528
+ return {
1529
+ read: table.read ?? "member",
1530
+ write: table.write ?? "member",
1531
+ };
1532
+ }
1533
+
1534
+ /**
1535
+ * The Table a page sees for `<table>_history` (docs/adr/0040): the History's own columns, then the Table's
1536
+ * as nullable snapshots; read under the Table's policy, never written. `history` names the Table.
1537
+ * @type {typeof import("./schema.d.mts").historyTable}
1538
+ */
1539
+ export function historyTable(parent, def) {
1540
+ /** @type {Record<string, Column>} */
1541
+ const columns = {};
1542
+ for (const [c, type] of Object.entries(HISTORY_COLUMNS))
1543
+ columns[c] = {
1544
+ type,
1545
+ required: c !== "by" && c !== "why" && c !== "transition",
1546
+ ref: c === "row_id" ? parent : null,
1547
+ values: c === "op" ? [...HISTORY_OPS] : null,
1548
+ };
1549
+ for (const [c, d] of Object.entries(def.columns)) columns[c] = { ...d, required: false };
1550
+ return {
1551
+ columns,
1552
+ indexes: [["row_id", "valid_from"], ["valid_to"]],
1553
+ read: def.read,
1554
+ write: "none",
1555
+ history: parent,
1556
+ };
1557
+ }
1558
+
1559
+ /**
1560
+ * A page's Declaration plus the History of every Table in it.
1561
+ * @type {typeof import("./schema.d.mts").withHistory}
1562
+ */
1563
+ export function withHistory(declared) {
1564
+ const out = { ...declared };
1565
+ for (const [t, def] of Object.entries(declared)) out[historyName(t)] = historyTable(t, def);
1566
+ return out;
1567
+ }
1568
+
1569
+ /**
1570
+ * The declared type of a declared or system column, or null.
1571
+ * @type {typeof import("./schema.d.mts").columnTypeOf}
1572
+ */
1573
+ export function columnTypeOf(table, name) {
1574
+ if (!table.view && Object.hasOwn(SYSTEM_TYPES, name))
1575
+ return SYSTEM_TYPES[/** @type {keyof typeof SYSTEM_TYPES} */ (name)];
1576
+ return Object.hasOwn(table.columns, name) ? table.columns[name].type : null;
1577
+ }
1578
+
1579
+ /** @type {Map<string, import("./shape.d.mts").Shape>} */
1580
+ const shapes = new Map();
1581
+ /**
1582
+ * A declared TYPE, parsed once per process. Declarations hold the printed form, which always parses.
1583
+ * @param {string} text
1584
+ */
1585
+ function shapeOf(text) {
1586
+ let shape = shapes.get(text);
1587
+ if (!shape) {
1588
+ const parsed = parseShape(text);
1589
+ shape = "error" in parsed ? { kind: "unknown" } : parsed.shape;
1590
+ shapes.set(text, shape);
1591
+ }
1592
+ return shape;
1593
+ }
1594
+
1595
+ /**
1596
+ * Why a stored value would not be accepted by a column today, or null: a DATE that is no calendar date, a
1597
+ * JSON value that does not match its TYPE. A Push that tightens a column checks its rows with this.
1598
+ * @type {typeof import("./schema.d.mts").storedValueError}
1599
+ */
1600
+ export function storedValueError(column, stored, name) {
1601
+ if (stored === null) return null;
1602
+ if (column.type === "DATE")
1603
+ return isCalendarDate(stored) ? null : `${name} must be a date written YYYY-MM-DD (DATE)`;
1604
+ if (column.type !== "JSON" || !column.shape) return null;
1605
+ let value;
1606
+ try {
1607
+ value = JSON.parse(/** @type {string} */ (stored));
1608
+ } catch {
1609
+ return `${name} is not valid JSON`;
1610
+ }
1611
+ return value === null ? null : shapeError(shapeOf(column.shape), value, name);
1612
+ }
1613
+
1614
+ /**
1615
+ * The columns `next` makes stricter than `previous` for values already stored (docs/adr/0078): a TEXT column
1616
+ * that became DATE, a JSON column whose TYPE was added or changed. A Push checks their rows first.
1617
+ * @type {typeof import("./schema.d.mts").tightenedColumns}
1618
+ */
1619
+ export function tightenedColumns(previous, next) {
1620
+ const out = [];
1621
+ for (const [table, def] of Object.entries(next.tables)) {
1622
+ const before = previous.tables[table];
1623
+ if (!before) continue;
1624
+ for (const [column, col] of Object.entries(def.columns)) {
1625
+ const was = before.columns[column];
1626
+ if (!was) continue;
1627
+ const toDate = col.type === "DATE" && was.type !== "DATE";
1628
+ const reshaped = col.type === "JSON" && col.shape !== undefined && col.shape !== was.shape;
1629
+ if (toDate || reshaped) out.push({ table, column, def: col });
1630
+ }
1631
+ }
1632
+ return out;
1633
+ }
1634
+
1635
+ const ENUM_NAME_RE = /^(?:status|type|[a-z0-9_]+_type)$/;
1636
+
1637
+ /**
1638
+ * `schema-untyped-enum` (docs/adr/0078): TEXT columns named status, type or *_type that `next` adds without a
1639
+ * CHECK list, so their type is string. Only columns `previous` does not have: a published column cannot gain
1640
+ * one. `line` is 1-based in `sql`, the column's line inside its CREATE TABLE.
1641
+ * @type {typeof import("./schema.d.mts").untypedEnums}
1642
+ */
1643
+ export function untypedEnums(next, previous, sql) {
1644
+ return newColumns(
1645
+ next,
1646
+ previous,
1647
+ sql,
1648
+ (column, col) => col.type === "TEXT" && !col.values && !col.ref && ENUM_NAME_RE.test(column),
1649
+ );
1650
+ }
1651
+
1652
+ /**
1653
+ * The columns `next` adds over `previous` that `pick` selects, each with its 1-based line in `sql`: the
1654
+ * column's line inside its CREATE TABLE, or the table's line.
1655
+ * @param {import("./schema.d.mts").Declaration} next @param {import("./schema.d.mts").Declaration} previous
1656
+ * @param {string} sql
1657
+ * @param {(column: string, col: Column) => boolean} pick
1658
+ */
1659
+ function newColumns(next, previous, sql, pick) {
1660
+ const lines = sql.split("\n");
1661
+ const out = [];
1662
+ for (const [table, def] of Object.entries(next.tables)) {
1663
+ const start = lines.findIndex((l) =>
1664
+ new RegExp(`\\bTABLE\\s+(?:IF NOT EXISTS\\s+)?${table}\\b`, "i").test(l),
1665
+ );
1666
+ for (const [column, col] of Object.entries(def.columns)) {
1667
+ if (!pick(column, col) || previous.tables[table]?.columns[column]) continue;
1668
+ const at = lines.findIndex((l, i) => i >= start && new RegExp(`^\\s*${column}\\b`).test(l));
1669
+ out.push({ table, column, line: (at === -1 ? Math.max(start, 0) : at) + 1 });
1670
+ }
1671
+ }
1672
+ return out;
1673
+ }
1674
+
1675
+ /** Name parts that say a column holds money, and parts that say it holds a ratio or count of it instead. */
1676
+ const MONEY_PARTS = new Set(
1677
+ "price amount cost total subtotal fee fees tax balance paid due credit debit charge payment refund discount revenue salary wage".split(
1678
+ " ",
1679
+ ),
1680
+ );
1681
+ const RATIO_PARTS = new Set("rate pct percent ratio qty quantity hours weight factor".split(" "));
1682
+
1683
+ /**
1684
+ * `schema-real-money` (docs/adr/0107): REAL columns `next` adds whose name has a money part (`price`,
1685
+ * `amount_due`) and no ratio part (`tax_rate`). Only columns `previous` does not have: a published REAL column
1686
+ * cannot become MONEY.
1687
+ * @type {typeof import("./schema.d.mts").realMoney}
1688
+ */
1689
+ export function realMoney(next, previous, sql) {
1690
+ return newColumns(next, previous, sql, (column, col) => {
1691
+ const parts = column.split("_");
1692
+ return (
1693
+ col.type === "REAL" &&
1694
+ parts.some((p) => MONEY_PARTS.has(p)) &&
1695
+ !parts.some((p) => RATIO_PARTS.has(p))
1696
+ );
1697
+ });
1698
+ }
1699
+
1700
+ /** @param {unknown} v @returns {v is Record<string, unknown>} */
1701
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
1702
+
1703
+ /**
1704
+ * One page value -> storage form for the given declared type, or `{ error }`. Null passes through.
1705
+ * @param {import("./schema.d.mts").ColumnType} type @param {unknown} value @param {string} column @returns {{value: string | number | null} | {error: string}}
1706
+ */
1707
+ function toStorage(type, value, column) {
1708
+ if (value === null) return { value: null };
1709
+ /** @param {string} want */
1710
+ const wrong = (want) => ({ error: `${column} must be ${want}` });
1711
+ switch (type) {
1712
+ case "TEXT":
1713
+ return typeof value === "string" ? { value } : wrong("a string (TEXT)");
1714
+ case "FILE":
1715
+ return typeof value === "string" && ATTACHMENT_ID_RE.test(value)
1716
+ ? { value }
1717
+ : wrong("an attachment id (FILE), from db.upload");
1718
+ case "MEMBER":
1719
+ return typeof value === "string" && MEMBER_ID_RE.test(value)
1720
+ ? { value }
1721
+ : wrong("a Member id, user:<id> (MEMBER), from useAuth().user or the actors view");
1722
+ case "INTEGER":
1723
+ return typeof value === "number" && Number.isInteger(value)
1724
+ ? { value }
1725
+ : wrong("an integer (INTEGER)");
1726
+ case "MONEY":
1727
+ return typeof value === "number" && Number.isSafeInteger(value)
1728
+ ? { value }
1729
+ : wrong("a whole number of cents (MONEY); convert with toCents()");
1730
+ case "REAL":
1731
+ return typeof value === "number" && Number.isFinite(value)
1732
+ ? { value }
1733
+ : wrong("a number (REAL)");
1734
+ case "BOOLEAN":
1735
+ return typeof value === "boolean"
1736
+ ? { value: value ? 1 : 0 }
1737
+ : wrong("true or false (BOOLEAN)");
1738
+ case "DATE":
1739
+ return isCalendarDate(value) ? { value } : wrong("a date written YYYY-MM-DD (DATE)");
1740
+ case "TIMESTAMP": {
1741
+ if (typeof value === "number" && Number.isInteger(value)) return { value };
1742
+ const t = typeof value === "string" ? Date.parse(value) : NaN;
1743
+ return Number.isNaN(t)
1744
+ ? wrong("milliseconds or an ISO date string (TIMESTAMP)")
1745
+ : { value: t };
1746
+ }
1747
+ case "JSON":
1748
+ try {
1749
+ return { value: JSON.stringify(value) };
1750
+ } catch {
1751
+ return wrong("JSON-serialisable (JSON)");
1752
+ }
1753
+ default:
1754
+ return wrong(type);
1755
+ }
1756
+ }
1757
+
1758
+ /**
1759
+ * Where a column of `table` leads (docs/adr/0102): a referenced Table's row, a list of them (a JSON id
1760
+ * list), an `actors` row (a MEMBER column, created_by, updated_by), or nowhere (null).
1761
+ * @param {Table} table @param {string} column
1762
+ * @returns {{kind: "row" | "rows" | "actor", table: string} | null}
1763
+ */
1764
+ function referenceOf(table, column) {
1765
+ if (table.view || table.history) return null;
1766
+ if (column === "created_by" || column === "updated_by") return { kind: "actor", table: "actors" };
1767
+ const col = Object.hasOwn(table.columns, column) ? table.columns[column] : undefined;
1768
+ if (!col) return null;
1769
+ if (col.type === "MEMBER") return { kind: "actor", table: "actors" };
1770
+ if (col.ref) return { kind: col.type === "JSON" ? "rows" : "row", table: col.ref };
1771
+ return null;
1772
+ }
1773
+
1774
+ /** Whether a column leads an index of the Table. @param {Table} def @param {string} column */
1775
+ const leadsIndex = (def, column) =>
1776
+ [...def.indexes, ...(def.unique ?? [])].some((cols) => cols[0] === column);
1777
+
1778
+ /** A Table a path names, from the Declaration's Tables. @param {Record<string, Table> | undefined} tables @param {string} name */
1779
+ const tableIn = (tables, name) =>
1780
+ name === "actors"
1781
+ ? (tables?.actors ?? ACTORS_TABLE)
1782
+ : tables && Object.hasOwn(tables, name)
1783
+ ? tables[name]
1784
+ : undefined;
1785
+
1786
+ /**
1787
+ * One where object: columns of `table`, `or`, `and`, and paths through references.
1788
+ * @param {unknown} spec @param {Table} table @param {Record<string, Table> | undefined} tables @param {number} depth @param {number} ors
1789
+ * @returns {import("./schema.d.mts").Where[] | {error: string}}
1790
+ */
1791
+ function checkWhere(spec, table, tables, depth, ors) {
1792
+ if (!isObject(spec)) return { error: "where must be an object of column: value" };
1793
+ /** @type {import("./schema.d.mts").Where[]} */
1794
+ const where = [];
1795
+ for (const [key, value] of Object.entries(spec)) {
1796
+ if (key === "or" || key === "and") {
1797
+ if (ors >= MAX_OR) return { error: `or and and nest at most ${MAX_OR} deep` };
1798
+ if (!Array.isArray(value) || value.length === 0)
1799
+ return { error: `${key} takes a non-empty array of where objects` };
1800
+ /** @type {import("./schema.d.mts").Where[][]} */
1801
+ const items = [];
1802
+ for (const branch of value) {
1803
+ const checked = checkWhere(branch, table, tables, depth, ors + 1);
1804
+ if ("error" in checked) return checked;
1805
+ items.push(checked);
1806
+ }
1807
+ // Every branch of an `and` must pass, as the rest of the where does, so its items join it (docs/adr/0115).
1808
+ if (key === "and") where.push(...items.flat());
1809
+ else where.push({ op: "or", items });
1810
+ continue;
1811
+ }
1812
+ const dot = key.indexOf(".");
1813
+ if (dot >= 0) {
1814
+ // `"sample_id.status": ...`: rows whose referenced row passes (docs/adr/0102).
1815
+ const column = key.slice(0, dot);
1816
+ const ref = referenceOf(table, column);
1817
+ if (!columnTypeOf(table, column)) return { error: `no column "${column}"` };
1818
+ if (!ref || ref.kind === "actor")
1819
+ return {
1820
+ error: `${key}: ${column} does not REFERENCES a Table, so it has no columns to filter on`,
1821
+ };
1822
+ if (depth >= MAX_PATH)
1823
+ return { error: `${key}: a path follows at most ${MAX_PATH} references` };
1824
+ const target = tableIn(tables, ref.table);
1825
+ if (!target) return { error: `${key}: no Table "${ref.table}" is declared by this app` };
1826
+ const inner = checkWhere({ [key.slice(dot + 1)]: value }, target, tables, depth + 1, ors);
1827
+ if ("error" in inner) return { error: `${column} -> ${inner.error}` };
1828
+ where.push({ column, op: "via", table: ref.table, many: ref.kind === "rows", where: inner });
1829
+ continue;
1830
+ }
1831
+ const column = key;
1832
+ const type = columnTypeOf(table, column);
1833
+ if (!type) return { error: `no column "${column}"` };
1834
+ const def = Object.hasOwn(table.columns, column) ? table.columns[column] : undefined;
1835
+ const list = type === "JSON" && (def?.shape === "string[]" || def?.ref);
1836
+ /** @type {[string, unknown][]} */
1837
+ const entries = isObject(value) ? Object.entries(value) : [["eq", value]];
1838
+ for (const [operator, raw] of entries) {
1839
+ const op = OPS.find((allowed) => allowed === operator);
1840
+ if (!op) return { error: `"${operator}" is not an operator (${OPS.join(", ")})` };
1841
+ if (op === "has") {
1842
+ if (!list)
1843
+ return { error: `${column}: has needs an id list or a JSON TYPE 'string[]' column` };
1844
+ if (typeof raw !== "string") return { error: `${column}: has takes a string` };
1845
+ where.push({ column, op, value: raw });
1846
+ continue;
1847
+ }
1848
+ if (type === "JSON")
1849
+ return {
1850
+ error: `${column} is JSON and cannot be filtered on${list ? "; use { has: value }" : ""}`,
1851
+ };
1852
+ if (op === "null") {
1853
+ if (typeof raw !== "boolean") return { error: `${column}: null takes true or false` };
1854
+ where.push({ column, op, value: raw });
1855
+ continue;
1856
+ }
1857
+ if (op === "like" && type !== "TEXT") return { error: `${column}: like needs a TEXT column` };
1858
+ if (type === "BOOLEAN" && op !== "eq" && op !== "ne")
1859
+ return { error: `${column}: a BOOLEAN column takes eq or ne only` };
1860
+ if (op === "in" || op === "nin") {
1861
+ // An empty in matches nothing (docs/adr/0102); nin passes NULL and an empty nin every row (docs/adr/0115).
1862
+ if (!Array.isArray(raw)) return { error: `${column}: ${op} takes an array` };
1863
+ if (raw.length > QUERY_MAX_LIMIT)
1864
+ return { error: `${column}: ${op} takes at most ${QUERY_MAX_LIMIT} values` };
1865
+ const values = [];
1866
+ for (const v of raw) {
1867
+ const c = toStorage(type, v, column);
1868
+ if ("error" in c) return c;
1869
+ if (c.value === null)
1870
+ return {
1871
+ error:
1872
+ op === "in"
1873
+ ? `${column}: in cannot contain null; use { null: true }`
1874
+ : `${column}: nin cannot contain null; it passes NULL already, and { null: false } drops it`,
1875
+ };
1876
+ values.push(c.value);
1877
+ }
1878
+ where.push({ column, op, value: values });
1879
+ continue;
1880
+ }
1881
+ // `{ col: null }` and `{ col: { eq: null } }` mean IS NULL, `{ ne: null }` IS NOT NULL: what an author
1882
+ // writes first, and what the Framework's Query type already permits. Ordering operators keep refusing null.
1883
+ if (raw === null && (op === "eq" || op === "ne")) {
1884
+ where.push({ column, op: "null", value: op === "eq" });
1885
+ continue;
1886
+ }
1887
+ const c = toStorage(type, raw, column);
1888
+ if ("error" in c) return c;
1889
+ if (c.value === null) return { error: `${column}: compare with null using { null: true }` };
1890
+ where.push({ column, op, value: c.value });
1891
+ }
1892
+ }
1893
+ return where;
1894
+ }
1895
+
1896
+ /**
1897
+ * Where an include lands on its row (docs/adr/0102): `<name>_id` -> `<name>`, `<name>_ids` -> `<name>`,
1898
+ * any other column `c` -> `c_row` (`c_rows` for a list), and `<column>_row(s)` when the short name is a
1899
+ * column already. A reverse include lands on its child Table's name, or `<child>_rows` when that is a column.
1900
+ * @type {typeof import("./schema.d.mts").includeField}
1901
+ */
1902
+ export function includeField(table, key, kind) {
1903
+ const taken = (/** @type {string} */ name) => columnTypeOf(table, name) !== null;
1904
+ const plural = kind === "rows" || kind === "children";
1905
+ const fallback = `${key}_${plural ? "rows" : "row"}`;
1906
+ if (kind === "children") return taken(key) ? fallback : key;
1907
+ const short = key.endsWith("_ids")
1908
+ ? key.slice(0, -4)
1909
+ : key.endsWith("_id")
1910
+ ? key.slice(0, -3)
1911
+ : null;
1912
+ return short && !taken(short) ? short : fallback;
1913
+ }
1914
+
1915
+ /**
1916
+ * The columns an include asks for: true (all) or a list. `id` always comes.
1917
+ * @param {unknown} value @param {Table} target @param {string} key @returns {string[] | null | {error: string}}
1918
+ */
1919
+ function includeColumns(value, target, key) {
1920
+ if (value === true) return null;
1921
+ if (!Array.isArray(value)) return { error: `include ${key}: true or a list of columns` };
1922
+ /** @type {string[]} */
1923
+ const out = [];
1924
+ for (const c of value) {
1925
+ if (typeof c !== "string" || !columnTypeOf(target, c))
1926
+ return { error: `include ${key}: no column "${String(c)}"` };
1927
+ if (c !== "id" && !out.includes(c)) out.push(c);
1928
+ }
1929
+ return out;
1930
+ }
1931
+
1932
+ /**
1933
+ * `include` (docs/adr/0102): forward paths through references and reverse child Tables, as a tree.
1934
+ * @param {unknown} spec @param {Table} table @param {Record<string, Table> | undefined} tables @param {boolean} reverse whether child Tables may be named here
1935
+ * @param {{count: number}} budget
1936
+ * @returns {import("./schema.d.mts").Include[] | {error: string}}
1937
+ */
1938
+ function checkInclude(spec, table, tables, reverse, budget) {
1939
+ if (!isObject(spec)) return { error: "include must be an object of path: true | [columns]" };
1940
+ /** @type {import("./schema.d.mts").Include[]} */
1941
+ const out = [];
1942
+ const fields = new Set();
1943
+ /** @param {import("./schema.d.mts").Include} node */
1944
+ const add = (node) => {
1945
+ if (fields.has(node.field)) return { error: `include: two includes land on "${node.field}"` };
1946
+ fields.add(node.field);
1947
+ out.push(node);
1948
+ return null;
1949
+ };
1950
+ // Forward keys sorted so "a" comes before "a.b" and the shorter path gives the node its columns.
1951
+ for (const key of Object.keys(spec).sort()) {
1952
+ const value = spec[key];
1953
+ if (++budget.count > MAX_INCLUDES)
1954
+ return { error: `a query includes at most ${MAX_INCLUDES} paths` };
1955
+ const segments = key.split(".");
1956
+ const first = segments[0];
1957
+ const ref = referenceOf(table, first);
1958
+ if (ref) {
1959
+ if (segments.length > MAX_PATH)
1960
+ return { error: `include ${key}: a path follows at most ${MAX_PATH} references` };
1961
+ /** @type {import("./schema.d.mts").Include[]} */
1962
+ let level = out;
1963
+ let at = table;
1964
+ /** @type {import("./schema.d.mts").Include | null} */
1965
+ let node = null;
1966
+ for (let i = 0; i < segments.length; i++) {
1967
+ const column = segments[i];
1968
+ const r = referenceOf(at, column);
1969
+ if (!r) return { error: `include ${key}: ${column} does not REFERENCES a Table` };
1970
+ const target = tableIn(tables, r.table);
1971
+ if (!target)
1972
+ return { error: `include ${key}: no Table "${r.table}" is declared by this app` };
1973
+ if (r.kind === "actor" && i < segments.length - 1)
1974
+ return { error: `include ${key}: an actors row references nothing further` };
1975
+ node = level.find((n) => n.kind !== "children" && n.column === column) ?? null;
1976
+ if (!node) {
1977
+ node = {
1978
+ field: includeField(at, column, r.kind),
1979
+ kind: r.kind,
1980
+ column,
1981
+ table: r.table,
1982
+ columns: [],
1983
+ include: [],
1984
+ };
1985
+ if (level === out) {
1986
+ const clash = add(node);
1987
+ if (clash) return clash;
1988
+ } else {
1989
+ if (level.some((n) => n.field === node?.field))
1990
+ return { error: `include ${key}: two includes land on "${node.field}"` };
1991
+ level.push(node);
1992
+ }
1993
+ }
1994
+ if (i === segments.length - 1) {
1995
+ const columns = includeColumns(value, target, key);
1996
+ if (columns !== null && "error" in columns) return columns;
1997
+ node.columns = columns;
1998
+ }
1999
+ level = node.include;
2000
+ at = target;
2001
+ }
2002
+ continue;
2003
+ }
2004
+ // A child Table: `<child>` when one of its columns references this one, else `<child>.<column>`.
2005
+ const child = tableIn(tables, first);
2006
+ if (!reverse || !child || child.view || child.history || segments.length > 2) {
2007
+ if (columnTypeOf(table, first))
2008
+ return { error: `include ${key}: ${first} does not REFERENCES a Table` };
2009
+ return { error: `include ${key}: no column or child Table "${first}"` };
2010
+ }
2011
+ const owner = Object.entries(tables ?? {}).find(([, d]) => d === table)?.[0];
2012
+ const columns = Object.entries(child.columns)
2013
+ .filter(([, c]) => c.ref !== null && c.ref === owner && c.type !== "JSON")
2014
+ .map(([c]) => c);
2015
+ const column = segments[1] ?? (columns.length === 1 ? columns[0] : undefined);
2016
+ if (!column)
2017
+ return {
2018
+ error: columns.length
2019
+ ? `include ${key}: ${first} references this Table through ${columns.join(", ")}; name one, "${first}.${columns[0]}"`
2020
+ : `include ${key}: no column of ${first} REFERENCES this Table`,
2021
+ };
2022
+ if (!columns.includes(column))
2023
+ return { error: `include ${key}: ${first}.${column} does not REFERENCES this Table` };
2024
+ if (!leadsIndex(child, column))
2025
+ return {
2026
+ error: `include ${key}: ${first}.${column} needs an index to find each row's children: CREATE INDEX ON ${first} (${column});`,
2027
+ };
2028
+ /** @type {import("./schema.d.mts").Include} */
2029
+ const node = {
2030
+ field: includeField(table, first, "children"),
2031
+ kind: "children",
2032
+ column,
2033
+ table: first,
2034
+ columns: null,
2035
+ include: [],
2036
+ };
2037
+ if (isObject(value)) {
2038
+ const nested = checkInclude(value, child, tables, false, budget);
2039
+ if ("error" in nested) return nested;
2040
+ node.include = nested;
2041
+ } else {
2042
+ const picked = includeColumns(value, child, key);
2043
+ if (picked !== null && "error" in picked) return picked;
2044
+ node.columns = picked;
2045
+ }
2046
+ const clash = add(node);
2047
+ if (clash) return clash;
2048
+ }
2049
+ return out;
2050
+ }
2051
+
2052
+ const ORDER_RE = /^(-?)([a-z][a-z0-9_]*)(?:\s+nulls\s+(first|last))?$/i;
2053
+
2054
+ /**
2055
+ * Validates a page query `{ where?, order?, limit?, offset?, include? }` against a Declaration. `tables` are
2056
+ * the Declaration's Tables, which paths through references and includes cross (docs/adr/0102); `table` is
2057
+ * one of them, the same object.
2058
+ * @type {typeof import("./schema.d.mts").checkQuery}
2059
+ */
2060
+ export function checkQuery(q, table, tables) {
2061
+ if (!isObject(q)) return { error: "the query must be an object" };
2062
+ const relational = !table.view && !table.history;
2063
+ /** @type {import("./schema.d.mts").Where[]} */
2064
+ let where = [];
2065
+ if (q.where !== undefined) {
2066
+ const checked = checkWhere(q.where, table, relational ? tables : undefined, 0, 0);
2067
+ if ("error" in checked) return checked;
2068
+ where = checked;
2069
+ }
2070
+ /** @type {import("./schema.d.mts").Query["order"]} */
2071
+ const order = [];
2072
+ if (q.order !== undefined) {
2073
+ if (!Array.isArray(q.order))
2074
+ return { error: 'order must be an array like ["-created_at", "name nulls last"]' };
2075
+ for (const o of q.order) {
2076
+ const m = typeof o === "string" ? ORDER_RE.exec(o.trim()) : null;
2077
+ if (!m)
2078
+ return {
2079
+ error: "order entries are column names, with - for descending and nulls first|last after",
2080
+ };
2081
+ const [, desc, column, nulls] = m;
2082
+ if (!columnTypeOf(table, column)) return { error: `no column "${column}"` };
2083
+ const dir = desc ? /** @type {const} */ ("desc") : /** @type {const} */ ("asc");
2084
+ order.push(
2085
+ nulls
2086
+ ? [column, dir, /** @type {"first" | "last"} */ (nulls.toLowerCase())]
2087
+ : [column, dir],
2088
+ );
2089
+ }
2090
+ }
2091
+ /** @type {number} */
2092
+ let limit = QUERY_DEFAULT_LIMIT;
2093
+ if (q.limit !== undefined) {
2094
+ if (typeof q.limit !== "number" || !Number.isInteger(q.limit))
2095
+ return { error: "limit must be an integer" };
2096
+ limit = Math.min(QUERY_MAX_LIMIT, Math.max(1, q.limit));
2097
+ }
2098
+ let offset = 0;
2099
+ if (q.offset !== undefined) {
2100
+ if (typeof q.offset !== "number" || !Number.isInteger(q.offset) || q.offset < 0)
2101
+ return { error: "offset must be a non-negative integer" };
2102
+ offset = q.offset;
2103
+ }
2104
+ // `scope: false` reads past the active scope (docs/adr/0098); the access rules still apply.
2105
+ if (q.scope !== undefined && q.scope !== false)
2106
+ return { error: "scope takes false only: read past the active scope" };
2107
+ /** @type {import("./schema.d.mts").Include[]} */
2108
+ let include = [];
2109
+ if (q.include !== undefined) {
2110
+ if (!relational)
2111
+ return { error: "include reads the references of a Table, not of a History or actors" };
2112
+ const checked = checkInclude(q.include, table, tables, true, { count: 0 });
2113
+ if ("error" in checked) return checked;
2114
+ include = checked;
2115
+ }
2116
+ return {
2117
+ where,
2118
+ order,
2119
+ limit,
2120
+ offset,
2121
+ ...(q.scope === false ? { unscoped: true } : {}),
2122
+ ...(include.length ? { include } : {}),
2123
+ };
2124
+ }
2125
+
2126
+ /**
2127
+ * Every Table a checked query reads besides its own: included ones (actors for an actor include) and those
2128
+ * its where goes through. Each is read under its own READ rule, and its version makes the query live.
2129
+ * @type {typeof import("./schema.d.mts").queryTables}
2130
+ */
2131
+ export function queryTables(q) {
2132
+ /** @type {Set<string>} */
2133
+ const out = new Set();
2134
+ /** @param {import("./schema.d.mts").Where[]} items */
2135
+ const where = (items) => {
2136
+ for (const w of items) {
2137
+ if (w.op === "or") w.items.forEach(where);
2138
+ else if (w.op === "via") {
2139
+ out.add(w.table);
2140
+ where(w.where);
2141
+ }
2142
+ }
2143
+ };
2144
+ /** @param {import("./schema.d.mts").Include[]} nodes */
2145
+ const include = (nodes) => {
2146
+ for (const n of nodes) {
2147
+ out.add(n.table);
2148
+ include(n.include);
2149
+ }
2150
+ };
2151
+ where(q.where);
2152
+ include(q.include ?? []);
2153
+ return [...out].sort();
2154
+ }
2155
+
2156
+ /** Counts and sums scan all matching input; limits apply to the resulting groups only.
2157
+ * @type {typeof import("./schema.d.mts").checkAggregate}
2158
+ */
2159
+ export function checkAggregate(q, table, tables) {
2160
+ if (!isObject(q)) return { error: "the aggregate query must be an object" };
2161
+ for (const key of Object.keys(q)) {
2162
+ if (!["where", "group", "sum", "limit", "offset", "scope"].includes(key))
2163
+ return { error: `unknown aggregate option "${key}"` };
2164
+ }
2165
+ const query = checkQuery(q, table, tables);
2166
+ if ("error" in query) return query;
2167
+ /** @type {Record<"group" | "sum", string[]>} */
2168
+ const columns = { group: [], sum: [] };
2169
+ for (const key of /** @type {const} */ (["group", "sum"])) {
2170
+ const names = q[key] ?? [];
2171
+ if (!Array.isArray(names) || names.length > RULES.limits.columnsPerTable)
2172
+ return { error: `${key} must be a bounded array of column names` };
2173
+ for (const name of names) {
2174
+ if (typeof name !== "string") return { error: `${key} takes column names` };
2175
+ const type = columnTypeOf(table, name);
2176
+ if (!type) return { error: `no column "${name}"` };
2177
+ if (type === "JSON") return { error: `${name} is JSON and cannot be aggregated` };
2178
+ if (key === "sum" && typeKind(type) !== "INTEGER" && type !== "REAL")
2179
+ return { error: `${name}: sum needs an INTEGER, MONEY or REAL column` };
2180
+ if (columns[key].includes(name)) return { error: `${key}: duplicate column "${name}"` };
2181
+ columns[key].push(name);
2182
+ }
2183
+ }
2184
+ if (!columns.group.length && (q.limit !== undefined || q.offset !== undefined))
2185
+ return { error: "limit and offset require grouping; an ungrouped aggregate returns one row" };
2186
+ return { ...query, ...columns };
2187
+ }
2188
+
2189
+ /**
2190
+ * Validates a row from a page for insert (every required column present) or update (only what is given, and
2191
+ * a required column may not become null). Returns the row in storage form.
2192
+ * @type {typeof import("./schema.d.mts").checkRow}
2193
+ */
2194
+ export function checkRow(body, table, mode) {
2195
+ if (!isObject(body)) return { error: "the row must be an object" };
2196
+ /** @type {import("./schema.d.mts").StorageRow} */
2197
+ const row = {};
2198
+ for (const [column, raw] of Object.entries(body)) {
2199
+ if (SYSTEM_COLUMNS.includes(column)) return { error: `${column} is set by the platform` };
2200
+ const def = table.columns[column];
2201
+ if (!def) return { error: `no column "${column}"` };
2202
+ if (raw === undefined) continue;
2203
+ if (mode === "update" && def.sequence)
2204
+ return { error: `${column} is a sequence and cannot be changed once assigned` };
2205
+ if (raw === null && def.required) return { error: `${column} is required` };
2206
+ const c = toStorage(def.type, raw, column);
2207
+ if ("error" in c) return c;
2208
+ const bad = raw !== null && def.shape ? shapeError(shapeOf(def.shape), raw, column) : null;
2209
+ if (bad) return { error: bad };
2210
+ if (def.values && raw !== null && !def.values.some((value) => value === raw))
2211
+ return { error: `${column} must be one of: ${def.values.join(", ")}` };
2212
+ row[column] = c.value;
2213
+ }
2214
+ if (mode === "insert") {
2215
+ for (const [column, def] of Object.entries(table.columns))
2216
+ if (def.required && !(column in row)) return { error: `${column} is required` };
2217
+ } else if (Object.keys(row).length === 0) {
2218
+ return { error: "nothing to update" };
2219
+ }
2220
+ return { row };
2221
+ }
2222
+
2223
+ /**
2224
+ * A stored row -> what a page sees: BOOLEAN as booleans, JSON parsed (null if it is not valid JSON).
2225
+ * @type {typeof import("./schema.d.mts").fromStorage}
2226
+ */
2227
+ export function fromStorage(row, table) {
2228
+ /** @type {Record<string, unknown>} */
2229
+ const out = {};
2230
+ for (const [column, value] of Object.entries(row)) {
2231
+ const type = columnTypeOf(table, column);
2232
+ if (value === null || type === null) {
2233
+ out[column] = value;
2234
+ } else if (type === "BOOLEAN") {
2235
+ out[column] = value === 1;
2236
+ } else if (type === "JSON") {
2237
+ try {
2238
+ out[column] = JSON.parse(/** @type {string} */ (value));
2239
+ } catch {
2240
+ out[column] = null;
2241
+ }
2242
+ } else {
2243
+ out[column] = value;
2244
+ }
2245
+ }
2246
+ return out;
2247
+ }
2248
+
2249
+ // ---- Builder SQL ----------------------------------------------------------------------------------------
2250
+ //
2251
+ // `ez db sql` hands the engine a statement a person or an agent wrote. The App Database shares a physical
2252
+ // database with the control plane (session tokens included) and every other Instance, so this check is a
2253
+ // security boundary, not a convenience: one statement, DML only, and no identifier may name anything but
2254
+ // one of the Instance's own tables, named as declared (never the physical data_<instance>_<table> name).
2255
+ // SQLite can reach a table through an identifier token or a single-quoted string, so both are scanned. The
2256
+ // cost is that a column or alias may not be named like a control-plane table, which parseSchema already
2257
+ // refuses (RULES.reservedNames).
2258
+
2259
+ /** @type {typeof import("./schema.d.mts").SQL_MAX_ROWS} */
2260
+ export const SQL_MAX_ROWS = 10000;
2261
+ const SQL_WRITE = Object.freeze(/** @type {const} */ (["INSERT", "UPDATE", "DELETE"]));
2262
+
2263
+ /**
2264
+ * Blanks out string literals and comments so neither can hide a `;` or an identifier. Keeps the length.
2265
+ * @param {string} sql
2266
+ */
2267
+ function blankSql(sql) {
2268
+ return sql.replace(/'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g, (m) => " ".repeat(m.length));
2269
+ }
2270
+
2271
+ // Classifies every region of a statement in one pass, so a comment can never make an odd apostrophe pair
2272
+ // with a later real quote and hide a forbidden literal from the check (a `--`/`/* */` comment is matched
2273
+ // and consumed whole, before the string-literal branch ever gets a chance to start mid-comment). In order:
2274
+ // a line or block comment (no group; copied through untouched); a single-quoted string (group 1: checked,
2275
+ // then copied through untouched, even when it names one of the Instance's own tables); a quoted identifier
2276
+ // (groups 2-4) or bare word (group 5): checked. Table rewriting is a separate pass below.
2277
+ const TOKEN =
2278
+ /--[^\n]*|\/\*[\s\S]*?\*\/|'((?:[^']|'')*)'|"([^"]*)"|\[([^\]]*)\]|`([^`]*)`|([A-Za-z_][A-Za-z0-9_]*)/g;
2279
+
2280
+ // Locate table positions separately from the conservative identifier security scan. Parentheses form
2281
+ // scopes for CTEs; expressions and column lists never become table references. `literalTables` holds the
2282
+ // offsets of single-quoted strings in a table position, where SQLite reads a string as a table name.
2283
+ /** @param {string} sql @param {Map<string, string>} app */
2284
+ function sqlTableReplacements(sql, app) {
2285
+ /**
2286
+ * @typedef {{parent: SqlScope | null, ctes: Set<string>, from?: boolean}} SqlScope
2287
+ * @type {SqlScope}
2288
+ */
2289
+ const root = { parent: null, ctes: new Set() };
2290
+ /** @type {{raw: string, at: number, name: string, scope: SqlScope, close?: number, tableGroup?: boolean}[]} */
2291
+ const tokens = [
2292
+ ...sql.matchAll(
2293
+ /--[^\n]*|\/\*[\s\S]*?\*\/|'(?:[^']|'')*'|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]|[A-Za-z_][A-Za-z0-9_]*|[^\s]/g,
2294
+ ),
2295
+ ]
2296
+ .filter((m) => !m[0].startsWith("--") && !m[0].startsWith("/*"))
2297
+ .map((m) => ({
2298
+ scope: root,
2299
+ raw: m[0],
2300
+ at: m.index,
2301
+ name: m[0].replace(/^['"`[]|['"`\]]$/g, "").toLowerCase(),
2302
+ }));
2303
+ let scope = root;
2304
+ const stack = [];
2305
+ for (let i = 0; i < tokens.length; i++) {
2306
+ const t = tokens[i];
2307
+ t.scope = scope;
2308
+ if (t.raw === "(") {
2309
+ stack.push(i);
2310
+ scope = { parent: scope, ctes: new Set() };
2311
+ } else if (t.raw === ")") {
2312
+ const open = stack.pop();
2313
+ if (open !== undefined) tokens[open].close = i;
2314
+ scope = scope.parent ?? root;
2315
+ t.scope = scope;
2316
+ }
2317
+ }
2318
+ /** @param {number} i @param {string} name */
2319
+ const word = (i, name) => tokens[i]?.raw.toLowerCase() === name;
2320
+ for (let i = 0; i < tokens.length; i++) {
2321
+ if (!word(i, "with")) continue;
2322
+ let j = i + 1;
2323
+ if (word(j, "recursive")) j++;
2324
+ while (tokens[j]) {
2325
+ const name = tokens[j++].name;
2326
+ if (word(j, "(")) j = (tokens[j].close ?? tokens.length) + 1;
2327
+ if (!word(j++, "as")) break;
2328
+ if (word(j, "not")) j++;
2329
+ if (word(j, "materialized")) j++;
2330
+ const close = tokens[j]?.close;
2331
+ if (!word(j, "(") || close === undefined) break;
2332
+ tokens[i].scope.ctes.add(name);
2333
+ j = close + 1;
2334
+ if (!word(j++, ",")) break;
2335
+ }
2336
+ }
2337
+ /** @param {SqlScope | null} s @param {string} name @returns {boolean} */
2338
+ const cte = (s, name) => s !== null && (s.ctes.has(name) || cte(s.parent, name));
2339
+ const replacements = new Map();
2340
+ /** @type {Set<number>} */
2341
+ const literalTables = new Set();
2342
+ const clauses = new Set([
2343
+ "where",
2344
+ "group",
2345
+ "having",
2346
+ "order",
2347
+ "limit",
2348
+ "union",
2349
+ "except",
2350
+ "intersect",
2351
+ "returning",
2352
+ "set",
2353
+ "values",
2354
+ "window",
2355
+ ]);
2356
+ const reserved = new Set([
2357
+ ...clauses,
2358
+ "on",
2359
+ "using",
2360
+ "join",
2361
+ "left",
2362
+ "right",
2363
+ "full",
2364
+ "inner",
2365
+ "outer",
2366
+ "cross",
2367
+ "natural",
2368
+ "indexed",
2369
+ "not",
2370
+ "do",
2371
+ ]);
2372
+ for (let i = 0; i < tokens.length; i++) {
2373
+ const t = tokens[i];
2374
+ const s = t.scope;
2375
+ const keyword = t.raw.toLowerCase();
2376
+ if (clauses.has(keyword)) s.from = false;
2377
+ let target = t.tableGroup ?? false;
2378
+ if (target && tokens[i + 1]) tokens[i + 1].scope.from = true;
2379
+ if (keyword === "from" || keyword === "join") {
2380
+ s.from = true;
2381
+ target = true;
2382
+ }
2383
+ if (keyword === "," && s.from) target = true;
2384
+ if (keyword === "into" || (keyword === "update" && !word(i + 1, "set"))) target = true;
2385
+ if (!target) continue;
2386
+ let j = i + 1;
2387
+ if (word(j, "or")) j += 2;
2388
+ let table = tokens[j];
2389
+ if (!table) continue;
2390
+ if (table.raw === "(") {
2391
+ table.tableGroup = !word(j + 1, "select") && !word(j + 1, "with");
2392
+ continue;
2393
+ } else {
2394
+ if (word(j + 1, ".")) table = tokens[(j += 2)];
2395
+ j++;
2396
+ }
2397
+ if (!table) continue;
2398
+ if (table.raw.startsWith("'")) literalTables.add(table.at);
2399
+ if (word(j, "as")) j++;
2400
+ const next = tokens[j];
2401
+ const namedAlias =
2402
+ next && /^[A-Za-z_'"`[]/.test(next.raw) && !reserved.has(next.raw.toLowerCase());
2403
+ // CTEs shadow read sources, but SQLite still resolves mutation targets as real tables.
2404
+ const writeTarget =
2405
+ keyword === "into" || keyword === "update" || (keyword === "from" && word(i - 1, "delete"));
2406
+ const physical = !writeTarget && cte(s, table.name) ? null : app.get(table.name);
2407
+ if (physical)
2408
+ replacements.set(table.at, {
2409
+ length: table.raw.length,
2410
+ value: physical + (namedAlias ? "" : ` AS "${table.name}"`),
2411
+ table: table.name,
2412
+ write: writeTarget,
2413
+ });
2414
+ }
2415
+ // Keep the logical name as an alias so qualifiers retain SQLite scope semantics, including
2416
+ // correlated subqueries and different aliases in each arm of a compound SELECT.
2417
+ return { replacements, literalTables };
2418
+ }
2419
+
2420
+ /**
2421
+ * One DML statement on the Instance's tables, named as declared. Every identifier is checked: one of the
2422
+ * Instance's tables is allowed; anything else that is a table or view in the database
2423
+ * is refused; columns, aliases and functions pass through. Comments and string literals are classified by
2424
+ * the same pass as identifiers, so neither can hide a forbidden table name from the check. Only table
2425
+ * positions are rewritten, with logical aliases preserving column qualifiers.
2426
+ * `tables` are the Instance tables the statement names; `verb` is a write's statement kind (after any WITH).
2427
+ * @type {typeof import("./schema.d.mts").checkSql}
2428
+ */
2429
+ export function checkSql(statement, tables, instance) {
2430
+ const trimmed = statement.trim().replace(/;\s*$/, "");
2431
+ const blank = blankSql(trimmed);
2432
+ if (blank.trim() === "") return { error: "empty statement" };
2433
+ if (blank.includes(";")) return { error: "one statement at a time" };
2434
+ const first = (/^\s*([A-Za-z]+)/.exec(blank)?.[1] ?? "").toUpperCase();
2435
+ /** @type {"read" | "write"} */
2436
+ let kind;
2437
+ if (SQL_WRITE.some((verb) => verb === first)) kind = "write";
2438
+ else if (first === "WITH") kind = /\b(INSERT|UPDATE|DELETE)\b/i.test(blank) ? "write" : "read";
2439
+ else if (first === "SELECT") kind = "read";
2440
+ else
2441
+ return {
2442
+ error: `${first || "that"} is not allowed: ez db sql runs one SELECT, WITH, INSERT, UPDATE or DELETE. Tables are shaped by db/schema.sql and deploy, never by SQL.`,
2443
+ };
2444
+
2445
+ const app = new Map(tables.app.map((t) => [t.toLowerCase(), physicalName(instance, t)]));
2446
+ const other = new Set(tables.other.map((t) => t.toLowerCase()));
2447
+ const located = sqlTableReplacements(trimmed, app);
2448
+ for (const m of trimmed.matchAll(TOKEN)) {
2449
+ if (m[1] !== undefined) {
2450
+ // A single-quoted string. SQLite reads one as an identifier where only an identifier fits: a table
2451
+ // position ("SELECT * FROM 'user'") or a qualifier ("'user'.email"), so there a literal naming a
2452
+ // foreign table is refused. Anywhere else it is a value ("VALUES ('Account')") and passes; a string
2453
+ // is never rewritten, even when it names one of the Instance's own tables. SQLite's authorizer in the
2454
+ // Builder SQL process enforces the same boundary whatever this pass concludes (ADR 0052).
2455
+ const literal = m[1].replaceAll("''", "'").toLowerCase();
2456
+ if (literal.startsWith("sqlite_") || literal.startsWith("pragma_"))
2457
+ return { error: `${literal} is not allowed: only your tables can be named` };
2458
+ const identifier =
2459
+ located.literalTables.has(m.index) || /^\s*\./.test(trimmed.slice(m.index + m[0].length));
2460
+ if (identifier && other.has(literal))
2461
+ return { error: `${literal} is not one of your tables: run \`ez db tables\`` };
2462
+ continue;
2463
+ }
2464
+ const ident = (m[2] ?? m[3] ?? m[4] ?? m[5])?.toLowerCase();
2465
+ if (ident === undefined) continue; // a comment
2466
+ if (ident.startsWith("sqlite_") || ident.startsWith("pragma_"))
2467
+ return { error: `${ident} is not allowed: only your tables can be named` };
2468
+ if (other.has(ident))
2469
+ return { error: `${ident} is not one of your tables: run \`ez db tables\`` };
2470
+ }
2471
+ const replacements = [...located.replacements].sort((a, b) => a[0] - b[0]);
2472
+ // A History is read-only for everyone (docs/adr/0040): only the platform's triggers write it.
2473
+ const appNames = [...app.keys()];
2474
+ for (const [, r] of replacements) {
2475
+ const parent = r.write ? historyParent(r.table, appNames) : null;
2476
+ if (parent)
2477
+ return {
2478
+ error: `${r.table} is read-only: it is the History of ${parent}, written by the platform on every change. Query it; never write it.`,
2479
+ };
2480
+ }
2481
+ let sql = "";
2482
+ let at = 0;
2483
+ for (const [index, replacement] of replacements) {
2484
+ sql += trimmed.slice(at, index) + replacement.value;
2485
+ at = index + replacement.length;
2486
+ }
2487
+ sql += trimmed.slice(at);
2488
+ const named = [...new Set(replacements.map(([, r]) => r.table))].sort();
2489
+ if (kind === "read") return { kind, sql, tables: named };
2490
+ const verb = (
2491
+ first === "WITH" ? (/\b(INSERT|UPDATE|DELETE)\b/i.exec(blank)?.[1] ?? "") : first
2492
+ ).toUpperCase();
2493
+ return { kind, sql, tables: named, verb: /** @type {typeof SQL_WRITE[number]} */ (verb) };
2494
+ }
2495
+
2496
+ // ---- ez help access (the access.sql part) -----------------------------------------------------------------
2497
+
2498
+ /**
2499
+ * global/db/access.sql as an agent reads it, the second half of `ez help access`.
2500
+ * @type {typeof import("./schema.d.mts").helpAccess}
2501
+ */
2502
+ export function helpAccess() {
2503
+ return `global/db/access.sql says who reads and writes which rows; Admins push it and it
2504
+ takes effect for every deployed Site at once. A Table it does not name keeps its policy (every Member).
2505
+ READ timesheet WHERE owner OR group(managers); owner = created_by is the viewer
2506
+ WRITE timesheet WHERE owner AND status = 'draft'; a write's row must pass before and after
2507
+ READ load WHERE driver = me OR company IN my(membership.company WHERE roles HAS 'dispatch');
2508
+ WRITE membership BY functions; pages refused; server functions and jobs write
2509
+ READ audit_note BY none; Builders only
2510
+ Atoms: owner, group(<name>), <col> = me (a MEMBER column), <col> = 'v' | 1 | true, <col> IS [NOT] NULL,
2511
+ <col> IN my(<table>.<col> [WHERE <col> = 'v' | <col> HAS 'v' | ...]) through that Table's one MEMBER column;
2512
+ AND binds tighter than OR; parentheses group. Every column a condition tests needs an index (created_by for
2513
+ owner), and a my() Table must be WRITE BY functions, BY none or WHERE group(...), or Members could grant
2514
+ themselves rows. Reads, counts, aggregates, Histories and attachments see only admitted rows; a row outside
2515
+ them is "Not found". Members' groups: ez user group add <who> <name>. Check what someone sees with
2516
+ \`ez db query <table> --as <who>\`; \`ez global push --dry-run\` reports what a change does to each Member.
2517
+ READ lookup, department, sample_type WHERE group(staff); one rule for several Tables
2518
+ GROUP analyst; a group server code may assign (docs/adr/0101)
2519
+ GROUP lab-manager IMPLIES analyst, verifier; holding it confers those too, wherever groups are tested
2520
+ Keep roles in groups, not in a Table: group() needs no column on the row and the Host checks it without a
2521
+ read. ez-admin (the Instance's Admins) and ez-builder (every Builder) are the Host's groups, held through
2522
+ the Builder roster: test them like any group, never declare or assign them (docs/adr/0110). Server code
2523
+ with Site authority (authority "site", jobs, Listeners) manages the roster: context.members.list() (status
2524
+ invited | active | blocked, invitedAt, lastSignInAt, builder), .invite(email, { name, groups, send })
2525
+ (emailed once the function commits; send: false emails no one), .resend(memberId), .setGroups(memberId,
2526
+ groups) (declared groups only; an Admin's others stay), .block, .unblock and .remove(memberId) (never a
2527
+ Builder's Member row). A Restricted Site admits a group's Members: ez site access add group <name>.
2528
+ SCOPE company_id FROM activeCompanyId IN my(membership.company_id); one active scope (optional)
2529
+ The scope keeps page and function queries of Tables with company_id to the value the viewer chose (a Saved
2530
+ key of session.ts, offered in the Framework's menu, useScope() in a Shell); inserts that omit it take it;
2531
+ { scope: false } in a query reads past it. It narrows; it never grants.`;
2532
+ }
2533
+
2534
+ // ---- ez help db -----------------------------------------------------------------------------------------
2535
+
2536
+ /**
2537
+ * The App Database rules as an agent reads them: rendered from RULES so it cannot drift from the parser.
2538
+ * @type {typeof import("./schema.d.mts").helpDb}
2539
+ */
2540
+ export function helpDb() {
2541
+ const types = Object.entries(RULES.types)
2542
+ .map(([t, s]) => ` ${t.padEnd(10)}${t === s ? "" : `stored as ${s}`}`)
2543
+ .join("\n");
2544
+ const refused = Object.entries(RULES.refused)
2545
+ .map(([k, why]) => ` ${k.padEnd(14)}${why}`)
2546
+ .join("\n");
2547
+ return `The App Database (one per Instance, shared by every Site in it).
2548
+
2549
+ The Instance declares its schema once in global/${SCHEMA_FILE}. Run \`ez global pull\`, then
2550
+ \`ez global cat ${SCHEMA_FILE}\` and \`ez global cat db/types.d.ts\`. Every Site gets the whole
2551
+ published schema on its next Preview or Deploy; existing deployments keep their schema snapshots.
2552
+ Admins and Builders add Tables, columns and indexes; a Limited Builder reads the schema only.
2553
+ All user-defined columns are nullable, even on new Tables: NOT NULL is not supported. Inserts may
2554
+ omit columns; reads return null for missing values. Require values in the app's workflow.
2555
+ Defaults (docs/adr/0097): <name> <type> DEFAULT <value> fills the column when an insert omits it, for
2556
+ every page, function and job, including deployments built before the default (it takes effect at Push).
2557
+ An explicit null stays null; updates and \`ez db sql\` never apply defaults; existing rows are not
2558
+ backfilled (the push says how many are null). Values: 'text' (one of its CHECK values, if any), 'YYYY-MM-DD'
2559
+ for DATE, a number, true/false, now for TIMESTAMP. A default may be added, changed or removed later.
2560
+
2561
+ Labels and integrity (docs/adr/0109): the schema says how records read and hold together, once.
2562
+ CREATE TABLE dealers (
2563
+ customer_code TEXT LABEL 'Customer ID', -- The NextGen id_customer. (a column's doc: the comment on its line)
2564
+ name TEXT,
2565
+ terms REFERENCES payment_terms ON DELETE RESTRICT
2566
+ ) LABEL 'Dealer' DISPLAY (customer_code, name);
2567
+ CREATE TABLE addresses (dealer REFERENCES dealers, vendor REFERENCES vendors, city TEXT)
2568
+ LABEL 'Address' 'Addresses' EXACTLY ONE OF (dealer, vendor);
2569
+ CREATE TABLE company_settings (company_name TEXT, books_closed_through DATE) SINGLETON;
2570
+ LABEL names a column or a row (and its plural); DISPLAY is how a reference to a row reads ("60-1 — North");
2571
+ without them, names are humanised and a row reads by its first TEXT column. Labels, docs and DISPLAY change
2572
+ freely. ON DELETE RESTRICT refuses deleting a row while that column holds its id; SINGLETON allows one row;
2573
+ EXACTLY ONE OF requires exactly one of the columns set. The Host enforces them for every page, function and
2574
+ job write (not \`ez db sql\`) from the Push on; a Push adding SINGLETON or EXACTLY ONE OF lists rows that break
2575
+ it. A refused write is a 409 with \`code\` ("unique", "restricted", "singleton", "exactly-one"): in a page,
2576
+ \`e instanceof WriteError && e.code === "restricted"\`. Never check references or owners in page code.
2577
+
2578
+ Access (docs/adr/0098): global/db/access.sql says who reads and writes which rows; \`ez help access\`.
2579
+
2580
+ Rules (docs/adr/0099): global/rules/<table>.ts runs for every page, function and job write of that Table
2581
+ (never Builder SQL), inside the write:
2582
+ import { rules } from "@ezship/react/server";
2583
+ export default rules<"orders">({
2584
+ watch: ["lines"], a write to lines re-derives the order it references, once
2585
+ async derive({ row, before, op, db }) { return { total: ... }; }, changes to this row only
2586
+ async guard({ before, after, op, db }) { if (...) throw new Error("why"); }, refuses the write (400)
2587
+ });
2588
+ A rule reads with db (every row, Site authority) and never writes; derive runs after defaults, then guard,
2589
+ then the access condition. Push compiles them; a changed guard is replayed over the last 7 days of writes and
2590
+ refusing any needs an Admin's --force (see --dry-run). Keep them fast: they run while the write holds the
2591
+ database (250 ms). Put shared logic in global/lib and call it from both rules and functions.
2592
+
2593
+ Workflows (docs/adr/0103): global/workflows/<table>.ts makes a TEXT status column a state machine the Host
2594
+ runs for every page, function and job write (never Builder SQL):
2595
+ import { workflow } from "@ezship/react/server";
2596
+ export default workflow<"sample">({
2597
+ column: "status",
2598
+ initial: "registered", inserts start here; also the column's type, never null
2599
+ states: { registered: { label: "Registered" }, due: { tone: "info" }, received: {}, verified: {} },
2600
+ actions: {
2601
+ receive: { from: ["due"], to: "received", groups: ["lab-clerk"],
2602
+ guard: ({ row, patch, db }) => (row.code ? null : "No code.") }, a string refuses (400)
2603
+ restore: { from: ["received"], to: "@previous" }, the state before, from History
2604
+ retest: { from: ["@new"], to: "due" }, db.insert("sample", row, { action: "retest" })
2605
+ verify: { auto: true, from: ["received"], to: "verified", children: { analysis: "sample_id" },
2606
+ when: ({ children }) => children.analysis.every((a) => a.status === "done") },
2607
+ },
2608
+ });
2609
+ Write states, actions and their names out as object literals (the contract reads them to type the column).
2610
+ db.transition("sample", id, "receive", patch?, { why }) checks the row's state (409), the groups (403, Site
2611
+ authority skips them) and the guard, then writes patch and the new state in one History row whose
2612
+ transition column names the action. db.update naming the column is refused; an automatic action runs after
2613
+ any write to a child it names, in that write, up to 10 steps and 3 Tables up. Pages: useActions(table, row)
2614
+ lists what the viewer could run now ({ name, label, to, enabled, reason }), useCan(table,
2615
+ "transition:<action>", row) answers without a request, useWorkflow(table) gives labels and tones.
2616
+ Names and types become permanent at the first global Push, before any Preview or Deploy. Published
2617
+ columns, references, enum values, sequences, indexes and policies cannot be removed or changed; the one
2618
+ relaxation is that a unique index may become a plain index. Correct a typo by adding a column.
2619
+ Backfilling rows does not synchronize old and new writers.
2620
+ After editing, run \`ez global check\` and \`ez global push\`. Push records definitions without DDL;
2621
+ a successful Site Preview or Deploy creates missing Tables, columns and indexes. Unpushed schema
2622
+ changes cannot be previewed against production storage. Preview data writes remain real.
2623
+ For an existing Site schema, start from \`ez db schema\`, review table read/write policies, move
2624
+ its definitions into global, remove NOT NULL, push global, and delete the Site's schema/types copies.
2625
+ Import row aliases with \`import type { Order } from "global/db/types"\`.
2626
+
2627
+ ${SCHEMA_FILE} holds only CREATE TABLE, CREATE INDEX and CREATE UNIQUE INDEX statements, each ending with ;
2628
+ -- read: member (policy comments go directly above CREATE TABLE; values: ${RULES.policies.join(", ")})
2629
+ -- write: member (read and write both default to member; every Site requires sign-in)
2630
+ CREATE TABLE tickets (
2631
+ title TEXT, every user-defined column is nullable
2632
+ assignee REFERENCES people, REFERENCES = a TEXT column holding another table's id
2633
+ details JSON, any JSON value; typed unknown
2634
+ pay JSON TYPE '{ kind: "mile" | "hour"; rate: number; tags?: string[] }', a typed JSON column (see Typed JSON)
2635
+ due_on DATE, a calendar date, 'YYYY-MM-DD'; typed DateString
2636
+ price MONEY, whole cents, never REAL dollars; typed Cents (see Money)
2637
+ receipt FILE, an Attachment id: pages upload with db.upload(table, column, file), show with attachment(id)
2638
+ owner MEMBER DEFAULT me, a Member, 'user:<id>' (useAuth().user.id prefixed, or actors.id); DEFAULT me = the inserting Member
2639
+ status TEXT CHECK (status IN ('open', 'done')) DEFAULT 'open', CHECK = allowed non-null values; fixed at Push
2640
+ urgent BOOLEAN DEFAULT false, filled when an insert omits it (see Defaults)
2641
+ number INTEGER SEQUENCE, numbered by the platform per Table: 1, 2, 3 ... (see Sequences)
2642
+ );
2643
+ CREATE INDEX ON tickets (assignee);
2644
+ CREATE UNIQUE INDEX ON tickets (title); a unique business key, enforced by the database; may span columns
2645
+ Types:
2646
+ ${types}
2647
+ Names: lowercase letters, digits, underscores; not ez_*, not a system column, not a platform table name.
2648
+ CHECK: only on TEXT columns; values are letters, digits, spaces, _ . - ; published value sets are fixed; enum evolution is a separate decision.
2649
+ Unique keys (docs/adr/0046): CREATE UNIQUE INDEX ON <table> (<columns>) after the table. Matching is exact
2650
+ (normalize case in the form); NULLs are distinct, so require the value in the app. An insert or update that
2651
+ repeats a key is refused: pages get a rejected promise "<table>: <columns> must be unique" (409); in a
2652
+ function the failed write makes the whole call roll back, so check before you insert. Pushing a unique index
2653
+ over a Table that already holds duplicates is refused with the duplicate values; fix the rows with SQL first.
2654
+ Sequences (docs/adr/0046): <name> INTEGER SEQUENCE numbers rows per Table: an insert that omits the column
2655
+ gets max + 1 (from 1) inside its own write, whoever writes; a value you supply wins and later numbers continue
2656
+ above it. Assigned once: updates are refused. Numbers increase and are never reused; deleted rows leave gaps;
2657
+ there is no periodic reset (format SO-000123 or a yearly prefix in the app). Rows older than the column stay
2658
+ null until you backfill them with SQL. A sequence column always has a unique index.
2659
+ Typed JSON (docs/adr/0078): JSON TYPE '<shape>' gives a JSON column its TypeScript type and checks every page
2660
+ and function write against it. A shape is string, number, boolean, null, unknown, DateString, EpochMs, Cents,
2661
+ "literal" values, { name: T; optional?: T }, T[], Array<T>, Record<string, T>, unions with | and parentheses,
2662
+ on one line. Objects are exact: a key the shape does not list is refused. A refused write names the path:
2663
+ "pay.rate must be a number". ez db sql is not checked. Add or change a shape at any Push; Push first checks
2664
+ every stored value and lists the rows that do not match. A JSON column without TYPE stays unknown.
2665
+ Dates and times: DATE holds a local calendar date, TEXT 'YYYY-MM-DD', and orders and filters as text;
2666
+ TIMESTAMP (and created_at, updated_at) holds epoch milliseconds. Pages and functions get DateString and EpochMs
2667
+ and build them with today(), toDate(year, month, day) or toDate(date), toEpoch(dateString) and now() from
2668
+ @ezship/react (or @ezship/react/server). A published TEXT column may become DATE once every stored value is a date.
2669
+ Money (docs/adr/0107): MONEY holds whole cents as an INTEGER, so sums are exact; never declare money REAL.
2670
+ Pages and functions write Cents: toCents("1,234.50") (or toCents(12.5)) rounds to the cent, null when
2671
+ unreadable; fromCents(cents) gives units for arithmetic; global Money draws it. A published INTEGER column may
2672
+ become MONEY; a REAL one cannot: add a MONEY column and backfill it with ROUND(price * 100) in ez db sql.
2673
+ Every table gets id, created_at, created_by, updated_at, updated_by from the platform; never declare them.
2674
+ Not allowed in ${SCHEMA_FILE}:
2675
+ ${refused}
2676
+
2677
+ Rows: pages use the helper (see \`ez help\`); you use \`ez db sql\` with one SELECT, WITH, INSERT, UPDATE or DELETE.
2678
+ SQL is SQLite; name tables as you declared them (tickets), never any other table in the database.
2679
+ Table references are rewritten per Instance; column names, aliases and CTE names keep their meaning.
2680
+ Never DDL: tables change only through ${SCHEMA_FILE} and \`ez deploy\`. Reads return at most ${SQL_MAX_ROWS} rows.
2681
+ A statement runs in its own process: a read is stopped after 10 seconds and a write after 5 (a stopped write
2682
+ leaves nothing), and a result over 16 MB is refused. Page through large Tables with LIMIT and a WHERE on id.
2683
+ Rows you insert with SQL get id, created_at, created_by, updated_at and updated_by automatically (the actor is
2684
+ you, 'builder:<your id>'); a value you set yourself wins. The changed-row count of a write is the statement's
2685
+ own rows.
2686
+
2687
+ History: every Table keeps its own past automatically in <table>_history, read-only, never declared: the row's
2688
+ columns as they stood plus row_id, op (seed | insert | update | delete), valid_from, valid_to (an open period
2689
+ ends at ${HISTORY_OPEN}), by (user:<id>, builder:<id>, null for a seed), version (the Table's write counter,
2690
+ monotonic), why (the reason the write gave, or null) and transition (the workflow action that wrote it, or null). An update closes the open row and opens the next with the same timestamp; a delete closes it and
2691
+ adds a zero-length 'delete' row; an update that sets only created_by or updated_by is not recorded.
2692
+ Never declare a log table, a *_history name or those column names.
2693
+ Only Admins change a History, and only to erase: \`ez db redact tickets --columns email,phone <row-id>...\` (or
2694
+ --where '{"status":"closed"}', or --all) sets those columns to NULL in the rows and in all their History, audited.
2695
+ the timeline of one row: SELECT op, valid_from, by, why, status FROM tickets_history WHERE row_id = ? ORDER BY version
2696
+ the Table as of T: SELECT * FROM tickets_history WHERE valid_from <= T AND valid_to > T
2697
+ changes since version v: SELECT * FROM tickets_history WHERE version > v ORDER BY version
2698
+ Pages: useLive("tickets_history", { where: { row_id: id }, order: ["version"] }); HISTORY_OPEN comes from @ezship/react.
2699
+ Reasons: every page and function write takes an optional last argument { why } (at most ${MAX_MESSAGE_CHARS} characters),
2700
+ stored in that write's History row: db.update("tickets", id, { status: "closed" }, { why: "Resolved by phone" }).
2701
+ A row's timeline with its reasons is the app's activity feed; whoever reads the Table reads its reasons.
2702
+
2703
+ Complete totals: useLive.count("tickets", { where: { status: "open" } }) is undefined until loaded.
2704
+ useLive.aggregate("tickets", { group: ["status"] }) returns { rows: [{ group: { status }, count, sum: {} }], truncated, loading, version }.
2705
+ Add sum: ["amount"] for INTEGER/MONEY/REAL columns; db.aggregate has the same query in handlers and Functions.
2706
+ Filters cover all input rows. limit/offset bound only grouped output, which reports truncated.
2707
+ Row queries default to ${QUERY_DEFAULT_LIMIT} and cap at ${QUERY_MAX_LIMIT}; never reduce them into a total.
2708
+ Use useLive.query / db.query to inspect rows and truncated instead of the legacy array-only results.
2709
+ Builders: ez db aggregate tickets '{"group":["status"]}'.
2710
+
2711
+ Relations (docs/adr/0102): a query follows REFERENCES. include: { sample_id: ["code"], "sample_id.client_id": ["name"],
2712
+ analyst: ["name"] (MEMBER, created_by, updated_by -> actors), method_instrument: { instrument_id: true } (child rows) }
2713
+ brings the rows with each row, each under its Table's READ rule; where: { "sample_id.status": "received", or: [...] }
2714
+ filters through them before paging. An id list is <name> JSON REFERENCES <table> (stored as JSON TYPE 'string[]',
2715
+ which an existing column may gain): { has: id } filters it and include brings its rows.
2716
+ Builders: ez db query <table> --as <who> '{"include": {...}}' shows what one Member gets.
2717
+
2718
+ Actor names: useLive("actors", { where: { id: { in: actorIds } } }) resolves History.by to current
2719
+ { id, kind, name, email } rows for this Instance's enrolled Builders and active Members. Read-only,
2720
+ no auth fields or system columns, never declared. A removed person is absent; display their id as fallback.
2721
+ Builders: ez db actors '{"where":{"kind":"builder"}}'.`;
2722
+ }
2723
+
2724
+ // ---- ez db schema ---------------------------------------------------------------------------------------
2725
+
2726
+ /**
2727
+ * The live schema as declarations a site can copy into db/schema.sql, with who declares each table.
2728
+ * @type {typeof import("./schema.d.mts").renderSchema}
2729
+ */
2730
+ export function renderSchema(schema) {
2731
+ const names = Object.keys(schema.live.tables).sort();
2732
+ if (names.length === 0) return "-- no tables yet\n";
2733
+ /** @param {string} t */
2734
+ const declarers = (t) =>
2735
+ Object.entries(schema.declarations)
2736
+ .filter(([, tables]) => t in tables)
2737
+ .map(([site]) => site)
2738
+ .sort();
2739
+ /** @param {string} t @param {string} c @param {string} storage */
2740
+ const columnOf = (t, c, storage) => {
2741
+ for (const site of declarers(t)) {
2742
+ const col = schema.declarations[site][t].columns[c];
2743
+ if (col) return describeColumn({ ...col, required: false }, c);
2744
+ }
2745
+ return storage;
2746
+ };
2747
+ const out = [];
2748
+ for (const t of names) {
2749
+ const live = schema.live.tables[t];
2750
+ const sites = declarers(t);
2751
+ const parent = historyParent(t, names);
2752
+ out.push(
2753
+ parent
2754
+ ? `-- ${t}: the History of ${parent} (read-only; every change to ${parent}, see ez help db)`
2755
+ : `-- ${t}: declared by ${sites.length ? sites.join(", ") : "no site"}`,
2756
+ );
2757
+ out.push(`CREATE TABLE ${t} (`);
2758
+ out.push(
2759
+ Object.entries(live.columns)
2760
+ .map(([c, s]) => ` ${c} ${columnOf(t, c, s)}`)
2761
+ .join(",\n"),
2762
+ );
2763
+ out.push(");");
2764
+ for (const cols of live.indexes) out.push(`CREATE INDEX ON ${t} (${cols.join(", ")});`);
2765
+ for (const cols of live.unique ?? [])
2766
+ out.push(`CREATE UNIQUE INDEX ON ${t} (${cols.join(", ")});`);
2767
+ out.push("");
2768
+ }
2769
+ return out.join("\n");
2770
+ }
2771
+
2772
+ // ---- db/types.d.ts --------------------------------------------------------------------------------------
2773
+ //
2774
+ // The declaration, as TypeScript, for Site code: `Tables` (augmenting the Framework) and one alias per table.
2775
+ // Generated by the contract, so both bindings produce the same bytes; push refuses a hand-edited file.
2776
+
2777
+ /** @type {typeof import("./schema.d.mts").TYPES_HEADER} */
2778
+ export const TYPES_HEADER =
2779
+ "// Generated by ez from global/db/schema.sql. Do not edit. All user-defined columns are nullable.";
2780
+
2781
+ const TS_TYPES = Object.freeze({
2782
+ TEXT: "string",
2783
+ INTEGER: "number",
2784
+ REAL: "number",
2785
+ BOOLEAN: "boolean",
2786
+ TIMESTAMP: "EpochMs",
2787
+ DATE: "DateString",
2788
+ MONEY: "Cents",
2789
+ JSON: "unknown",
2790
+ FILE: "FileId",
2791
+ MEMBER: "MemberId",
2792
+ });
2793
+
2794
+ /** @param {string} s */
2795
+ const pascal = (s) =>
2796
+ s
2797
+ .split("_")
2798
+ .filter(Boolean)
2799
+ .map((w) => w[0].toUpperCase() + w.slice(1))
2800
+ .join("");
2801
+
2802
+ /**
2803
+ * `order_items` -> `OrderItem`: PascalCase, last word singularised when that is safe.
2804
+ * @type {typeof import("./schema.d.mts").aliasName}
2805
+ */
2806
+ export function aliasName(table) {
2807
+ const words = table.split("_").filter(Boolean);
2808
+ return pascal([...words.slice(0, -1), singular(words[words.length - 1])].join("_"));
2809
+ }
2810
+
2811
+ /** `orders` -> `order`, `categories` -> `category`, when that is safe; else the word as it is. @param {string} word */
2812
+ function singular(word) {
2813
+ if (word.endsWith("ies") && word.length > 4) return word.slice(0, -3) + "y";
2814
+ if (word.endsWith("s") && !/(ss|us|is)$/.test(word) && word.length > 3) return word.slice(0, -1);
2815
+ return word;
2816
+ }
2817
+
2818
+ // ---- the descriptor (docs/adr/0109) -------------------------------------------------------------------
2819
+ //
2820
+ // What the Framework's record components read at run time: each Table's labels, display columns,
2821
+ // constraints and columns in declared order, and every scalar reference pointing at it. The Pipeline bundles
2822
+ // it from the build's Global schema snapshot.
2823
+
2824
+ /**
2825
+ * `customer_code` -> "Customer code": the label of a name that declares none.
2826
+ * @type {typeof import("./schema.d.mts").humanize}
2827
+ */
2828
+ export function humanize(name) {
2829
+ const text = name.split("_").filter(Boolean).join(" ");
2830
+ return text ? text[0].toUpperCase() + text.slice(1) : name;
2831
+ }
2832
+
2833
+ /**
2834
+ * The plural of a label: "Dealer" -> "Dealers", "Category" -> "Categories", "Address" -> "Addresses".
2835
+ * @type {typeof import("./schema.d.mts").pluralLabel}
2836
+ */
2837
+ export function pluralLabel(label) {
2838
+ if (/[^aeiou]y$/i.test(label)) return label.slice(0, -1) + "ies";
2839
+ if (/(s|x|z|ch|sh)$/i.test(label)) return label + "es";
2840
+ return label + "s";
2841
+ }
2842
+
2843
+ /**
2844
+ * The integrity constraints a Push adds or removes (docs/adr/0109): SINGLETON, EXACTLY ONE OF and each ON
2845
+ * DELETE RESTRICT. Live definitions (docs/adr/0096): they apply to every write from the Push on.
2846
+ * @type {typeof import("./schema.d.mts").integrityChanges}
2847
+ */
2848
+ export function integrityChanges(previous, next) {
2849
+ /** @type {import("./types.d.mts").IntegrityChange[]} */
2850
+ const out = [];
2851
+ const names = [...new Set([...Object.keys(previous.tables), ...Object.keys(next.tables)])].sort();
2852
+ for (const table of names) {
2853
+ const a = previous.tables[table];
2854
+ const b = next.tables[table];
2855
+ if ((a?.singleton ?? false) !== (b?.singleton ?? false))
2856
+ out.push({ kind: "integrity", table, constraint: "singleton", added: b?.singleton === true });
2857
+ const one = (/** @type {Table | undefined} */ t) => (t?.exactlyOne ?? []).join(",");
2858
+ if (one(a) !== one(b)) {
2859
+ if (a?.exactlyOne)
2860
+ out.push({
2861
+ kind: "integrity",
2862
+ table,
2863
+ constraint: "exactly-one",
2864
+ columns: a.exactlyOne,
2865
+ added: false,
2866
+ });
2867
+ if (b?.exactlyOne)
2868
+ out.push({
2869
+ kind: "integrity",
2870
+ table,
2871
+ constraint: "exactly-one",
2872
+ columns: b.exactlyOne,
2873
+ added: true,
2874
+ });
2875
+ }
2876
+ const columns = new Set([...Object.keys(a?.columns ?? {}), ...Object.keys(b?.columns ?? {})]);
2877
+ for (const column of columns) {
2878
+ const was = a?.columns[column]?.onDelete === "restrict";
2879
+ const is = b?.columns[column]?.onDelete === "restrict";
2880
+ if (was !== is)
2881
+ out.push({ kind: "integrity", table, constraint: "restrict", column, added: is });
2882
+ }
2883
+ }
2884
+ return out;
2885
+ }
2886
+
2887
+ /**
2888
+ * The run-time descriptor of a Declaration's Tables (docs/adr/0109). Histories and the actors view are left
2889
+ * out: the record components draw declared Tables.
2890
+ * @type {typeof import("./schema.d.mts").describeSchema}
2891
+ */
2892
+ export function describeSchema(decl) {
2893
+ const names = Object.keys(decl.tables)
2894
+ .filter((t) => !decl.tables[t].history && !decl.tables[t].view)
2895
+ .sort();
2896
+ /** @type {import("./schema.d.mts").SchemaDescriptor["tables"]} */
2897
+ const tables = {};
2898
+ for (const t of names) {
2899
+ const def = decl.tables[t];
2900
+ const words = t.split("_").filter(Boolean);
2901
+ const label =
2902
+ def.label ?? humanize([...words.slice(0, -1), singular(words[words.length - 1])].join("_"));
2903
+ const firstText = Object.entries(def.columns).find(
2904
+ ([, c]) => c.type === "TEXT" && c.ref === null,
2905
+ )?.[0];
2906
+ tables[t] = {
2907
+ name: t,
2908
+ label,
2909
+ plural: def.plural ?? (def.label ? pluralLabel(def.label) : humanize(t)),
2910
+ display: def.display ?? (firstText ? [firstText] : []),
2911
+ singleton: def.singleton === true,
2912
+ exactlyOne: def.exactlyOne ?? [],
2913
+ unique: def.unique ?? [],
2914
+ columns: Object.entries(def.columns).map(([name, c]) => ({
2915
+ name,
2916
+ type: c.type,
2917
+ label: c.label ?? humanize(name),
2918
+ ...(c.doc ? { doc: c.doc } : {}),
2919
+ ...(c.ref ? { ref: c.ref } : {}),
2920
+ ...(c.ref && c.type === "JSON" ? { many: /** @type {const} */ (true) } : {}),
2921
+ ...(c.values ? { values: c.values } : {}),
2922
+ ...(c.shape ? { shape: c.shape } : {}),
2923
+ ...(c.default ? { default: c.default } : {}),
2924
+ ...(c.sequence ? { sequence: /** @type {const} */ (true) } : {}),
2925
+ ...(c.onDelete ? { restrict: /** @type {const} */ (true) } : {}),
2926
+ })),
2927
+ referencedBy: [],
2928
+ };
2929
+ }
2930
+ for (const t of names)
2931
+ for (const [column, c] of Object.entries(decl.tables[t].columns))
2932
+ if (c.ref && c.type !== "JSON" && Object.hasOwn(tables, c.ref))
2933
+ tables[c.ref].referencedBy.push({ table: t, column, restrict: c.onDelete === "restrict" });
2934
+ return { tables };
2935
+ }
2936
+
2937
+ /** @param {Column} c */
2938
+ const tsType = (c) => {
2939
+ const base = c.values
2940
+ ? c.values.map((v) => JSON.stringify(v)).join(" | ")
2941
+ : c.ref
2942
+ ? `Id<${JSON.stringify(c.ref)}>${c.type === "JSON" ? "[]" : ""}`
2943
+ : c.shape
2944
+ ? c.shape.includes("|")
2945
+ ? `(${c.shape})`
2946
+ : c.shape
2947
+ : TS_TYPES[c.type];
2948
+ return `${base} | null`;
2949
+ };
2950
+
2951
+ /** A column's label and doc as JSDoc (docs/adr/0109), or nothing. @param {Column} c */
2952
+ const jsDoc = (c) => {
2953
+ const text = [c.label, c.doc].filter(Boolean).join(": ").replaceAll("*/", "* /");
2954
+ return text ? `/** ${text} */ ` : "";
2955
+ };
2956
+
2957
+ /** A History's own columns as TypeScript (docs/adr/0040); never optional, never null but `by`, `why` and `transition`. */
2958
+ const HISTORY_TS = Object.freeze({
2959
+ /** @param {string} t */
2960
+ row_id: (t) => `Id<${JSON.stringify(t)}>`,
2961
+ op: () => HISTORY_OPS.map((v) => JSON.stringify(v)).join(" | "),
2962
+ valid_from: () => "EpochMs",
2963
+ valid_to: () => "EpochMs",
2964
+ by: () => "string | null",
2965
+ version: () => "number",
2966
+ why: () => "string | null",
2967
+ transition: () => "string | null",
2968
+ });
2969
+
2970
+ /**
2971
+ * The References and Children interfaces of db/types.d.ts (docs/adr/0102), from the same rules the Host
2972
+ * includes by: each forward column's target Table and the field it lands on, each indexed child Table.
2973
+ * @param {import("./schema.d.mts").Declaration} decl @param {string[]} tables
2974
+ */
2975
+ function relationTypes(decl, tables) {
2976
+ const references = tables.map((t) => {
2977
+ const def = decl.tables[t];
2978
+ const entries = ["created_by", "updated_by", ...Object.keys(def.columns)].flatMap((c) => {
2979
+ const ref = referenceOf(def, c);
2980
+ if (!ref) return [];
2981
+ const many = ref.kind === "rows" ? "; many: true" : "";
2982
+ return [
2983
+ `${c}: { to: ${JSON.stringify(ref.table)}; as: ${JSON.stringify(includeField(def, c, ref.kind))}${many} }`,
2984
+ ];
2985
+ });
2986
+ return ` ${t}: { ${entries.join("; ")} };`;
2987
+ });
2988
+ const children = tables.flatMap((parent) => {
2989
+ const entries = tables.flatMap((child) => {
2990
+ const def = decl.tables[child];
2991
+ const columns = Object.entries(def.columns)
2992
+ .filter(([c, col]) => col.ref === parent && col.type !== "JSON" && leadsIndex(def, c))
2993
+ .map(([c]) => c);
2994
+ const as = JSON.stringify(includeField(decl.tables[parent], child, "children"));
2995
+ return [
2996
+ ...(columns.length === 1
2997
+ ? [`${child}: { from: ${JSON.stringify(child)}; as: ${as} }`]
2998
+ : []),
2999
+ ...columns.map(
3000
+ (c) =>
3001
+ `${JSON.stringify(`${child}.${c}`)}: { from: ${JSON.stringify(child)}; as: ${as} }`,
3002
+ ),
3003
+ ];
3004
+ });
3005
+ return entries.length ? [` ${parent}: { ${entries.join("; ")} };`] : [];
3006
+ });
3007
+ return [
3008
+ ...(references.length
3009
+ ? [" interface References {", ...references, " }"]
3010
+ : [" interface References {}"]),
3011
+ ...(children.length
3012
+ ? [" interface Children {", ...children, " }"]
3013
+ : [" interface Children {}"]),
3014
+ ];
3015
+ }
3016
+
3017
+ /**
3018
+ * @type {typeof import("./schema.d.mts").generateTypes}
3019
+ */
3020
+ export function generateTypes(decl, workflows = {}) {
3021
+ const tables = Object.keys(decl.tables).sort();
3022
+ /** The workflows whose Table and column the declaration has: their column is typed by their states. */
3023
+ const flows = Object.fromEntries(
3024
+ Object.entries(workflows).filter(
3025
+ ([t, w]) =>
3026
+ Object.hasOwn(decl.tables, t) &&
3027
+ Object.hasOwn(decl.tables[t].columns, w.column) &&
3028
+ w.states.length > 0,
3029
+ ),
3030
+ );
3031
+ /** @param {string[]} names */
3032
+ const union = (names) => names.map((n) => JSON.stringify(n)).join(" | ");
3033
+ // MemberId is imported only where a MEMBER column needs it, so earlier schemas' types stay as they were.
3034
+ const member = tables.some((t) =>
3035
+ Object.values(decl.tables[t].columns).some((c) => c.type === "MEMBER"),
3036
+ );
3037
+ // Cents likewise, for MONEY columns and JSON shapes that name it (docs/adr/0107).
3038
+ const cents = tables.some((t) =>
3039
+ Object.values(decl.tables[t].columns).some(
3040
+ (c) => c.type === "MONEY" || /\bCents\b/.test(c.shape ?? ""),
3041
+ ),
3042
+ );
3043
+ const lines = [
3044
+ TYPES_HEADER,
3045
+ `import type { Row, Id, FileId, ${member ? "MemberId, " : ""}DateString, EpochMs${cents ? ", Cents" : ""} } from "@ezship/react";`,
3046
+ "",
3047
+ `declare module "@ezship/react" {`,
3048
+ ];
3049
+ if (tables.length === 0) lines.push(" interface Tables {}");
3050
+ else {
3051
+ lines.push(" interface Tables {");
3052
+ for (const t of tables) {
3053
+ const cols = Object.entries(decl.tables[t].columns)
3054
+ .map(([c, d]) => `${c}?: ${tsType(d)}`)
3055
+ .join("; ");
3056
+ const flow = flows[t];
3057
+ // A labelled or documented column carries its JSDoc (docs/adr/0109); the rest stay as they were.
3058
+ const own = Object.entries(decl.tables[t].columns)
3059
+ .map(
3060
+ ([c, d]) =>
3061
+ `${jsDoc(d)}${c}?: ${flow && c === flow.column ? union(flow.states) : tsType(d)}`,
3062
+ )
3063
+ .join("; ");
3064
+ lines.push(` ${t}: { ${own} };`);
3065
+ const meta = Object.entries(HISTORY_TS)
3066
+ .map(([c, type]) => `${c}: ${type(t)}`)
3067
+ .join("; ");
3068
+ lines.push(` ${historyName(t)}: { ${meta}${cols ? `; ${cols}` : ""} };`);
3069
+ }
3070
+ lines.push(" }");
3071
+ }
3072
+ // What a query may include (docs/adr/0102): each column's target and where it lands, each child Table.
3073
+ lines.push(...relationTypes(decl, tables));
3074
+ // Each workflow's column, states and the actions a caller may name (docs/adr/0103).
3075
+ const flowTables = Object.keys(flows).sort();
3076
+ if (flowTables.length) {
3077
+ lines.push(" interface Workflows {");
3078
+ for (const t of flowTables) {
3079
+ const w = flows[t];
3080
+ lines.push(
3081
+ ` ${t}: { column: ${JSON.stringify(w.column)}; state: ${union(w.states)}; action: ${w.actions.length ? union(w.actions) : "never"} };`,
3082
+ );
3083
+ }
3084
+ lines.push(" }");
3085
+ }
3086
+ lines.push("}", "");
3087
+ const aliases = new Map();
3088
+ for (const t of tables) {
3089
+ const a = aliasName(t);
3090
+ aliases.set(a, (aliases.get(a) ?? 0) + 1);
3091
+ }
3092
+ for (const t of tables) {
3093
+ const a = aliasName(t);
3094
+ const alias = aliases.get(a) > 1 ? pascal(t) : a;
3095
+ lines.push(`export type ${alias} = Row<${JSON.stringify(t)}>;`);
3096
+ lines.push(`export type ${alias}History = Row<${JSON.stringify(historyName(t))}>;`);
3097
+ }
3098
+ return lines.join("\n") + "\n";
3099
+ }