@mistriwork/engine 1.0.0-rc.10 → 1.0.0-rc.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/dist/adapters/adapter.d.ts +33 -0
  2. package/dist/adapters/postgres.d.ts +21 -16
  3. package/dist/adapters/postgres.js +199 -223
  4. package/dist/adapters/postgresCatalog.d.ts +12 -1
  5. package/dist/adapters/postgresCatalog.js +57 -23
  6. package/dist/adapters/postgresCatalogDigest.js +40 -34
  7. package/dist/adapters/postgresCatalogRows.d.ts +2 -0
  8. package/dist/adapters/postgresWriteAhead.d.ts +47 -0
  9. package/dist/adapters/postgresWriteAhead.js +209 -0
  10. package/dist/adapters/scoped/keyRows.js +9 -3
  11. package/dist/adapters/scoped/keyTypes.d.ts +34 -0
  12. package/dist/adapters/scoped/keyTypes.js +66 -0
  13. package/dist/adapters/scoped/postgresScopeCatalog.d.ts +40 -1
  14. package/dist/adapters/scoped/postgresScopeCatalog.js +417 -13
  15. package/dist/adapters/scoped/postgresTriggers.d.ts +137 -0
  16. package/dist/adapters/scoped/postgresTriggers.js +1545 -0
  17. package/dist/adapters/scoped/scopeTriggers.d.ts +122 -0
  18. package/dist/adapters/scoped/scopeTriggers.js +131 -0
  19. package/dist/adapters/scoped/scopedReads.d.ts +3 -1
  20. package/dist/adapters/scoped/scopedReads.js +28 -8
  21. package/dist/adapters/scoped/scopedTransaction.d.ts +95 -6
  22. package/dist/adapters/scoped/scopedTransaction.js +308 -34
  23. package/dist/adapters/scoped/sqliteScopeCatalog.d.ts +17 -1
  24. package/dist/adapters/scoped/sqliteScopeCatalog.js +197 -18
  25. package/dist/adapters/scoped/sqliteTriggerSession.d.ts +64 -0
  26. package/dist/adapters/scoped/sqliteTriggerSession.js +245 -0
  27. package/dist/adapters/scoped/sqliteTriggers.d.ts +20 -0
  28. package/dist/adapters/scoped/sqliteTriggers.js +822 -0
  29. package/dist/adapters/scoped/storedText.d.ts +45 -0
  30. package/dist/adapters/scoped/storedText.js +61 -0
  31. package/dist/adapters/scoped/triggerEffects.d.ts +98 -0
  32. package/dist/adapters/scoped/triggerEffects.js +189 -0
  33. package/dist/adapters/scoped/triggerProof.d.ts +124 -0
  34. package/dist/adapters/scoped/triggerProof.js +366 -0
  35. package/dist/adapters/snapshotRead.d.ts +8 -0
  36. package/dist/adapters/snapshotRead.js +37 -0
  37. package/dist/adapters/sqlite.d.ts +13 -2
  38. package/dist/adapters/sqlite.js +139 -16
  39. package/dist/adapters/sqliteDecimals.d.ts +2 -2
  40. package/dist/adapters/sqliteDecimals.js +2 -8
  41. package/dist/adapters/storeHost.d.ts +4 -1
  42. package/dist/adapters/writeCapture.d.ts +7 -0
  43. package/dist/server/cli/args.d.ts +6 -0
  44. package/dist/server/cli/args.js +6 -0
  45. package/dist/server/columnGrants.d.ts +3 -0
  46. package/dist/server/columnGrants.js +12 -1
  47. package/dist/server/config/profile.d.ts +123 -0
  48. package/dist/server/config/profile.js +236 -0
  49. package/dist/server/connections.d.ts +5 -0
  50. package/dist/server/connections.js +11 -1
  51. package/dist/server/hiddenColumns.js +6 -0
  52. package/dist/server/http/refusalReport.js +16 -4
  53. package/dist/server/http/router.d.ts +11 -22
  54. package/dist/server/http/router.js +0 -15
  55. package/dist/server/migrate/cli.d.ts +50 -3
  56. package/dist/server/migrate/cli.js +199 -14
  57. package/dist/server/migrate/runner.js +5 -1
  58. package/dist/server/shapeonly.js +5 -0
  59. package/dist/shared/addressParams.d.ts +2 -0
  60. package/dist/shared/addressParams.js +2 -0
  61. package/dist/shared/aggregate.d.ts +49 -0
  62. package/dist/shared/aggregate.js +107 -0
  63. package/dist/shared/breakdown.js +19 -6
  64. package/dist/shared/decimals.d.ts +37 -0
  65. package/dist/shared/decimals.js +148 -0
  66. package/dist/shared/displayDefaults.js +15 -1
  67. package/dist/shared/filter.d.ts +39 -1
  68. package/dist/shared/filter.js +96 -15
  69. package/dist/shared/listPresentations.d.ts +2 -0
  70. package/dist/shared/listQuestion.d.ts +3 -1
  71. package/dist/shared/money.d.ts +9 -0
  72. package/dist/shared/money.js +17 -0
  73. package/dist/shared/moneyEntry.d.ts +6 -3
  74. package/dist/shared/moneyEntry.js +14 -7
  75. package/dist/shared/pageModel.d.ts +1 -1
  76. package/dist/shared/recordview.d.ts +1 -1
  77. package/dist/shared/refusal.d.ts +16 -0
  78. package/dist/shared/refusal.js +40 -0
  79. package/dist/shared/rowScope.js +12 -4
  80. package/dist/shared/schema.d.ts +6 -0
  81. package/dist/shared/schematext.d.ts +22 -6
  82. package/dist/shared/schematext.js +18 -2
  83. package/dist/shared/scopeCatalog.js +4 -0
  84. package/dist/shared/servedApp.d.ts +15 -4
  85. package/dist/shared/view.js +4 -4
  86. package/dist/shared/viewLabels.d.ts +1 -0
  87. package/dist/shared/viewLabels.js +8 -2
  88. package/dist/shared/viewPaths.d.ts +3 -0
  89. package/dist/shared/viewPaths.js +8 -0
  90. package/package.json +5 -2
  91. package/schema/model.d.ts +1 -1
  92. package/dist/shared/order.d.ts +0 -59
  93. package/dist/shared/order.js +0 -133
@@ -1,7 +1,86 @@
1
1
  import { Refusal } from '../adapter.js';
2
+ import { buildWhere } from '../../shared/filter.js';
2
3
  import { recordRefusalCause } from '../../shared/refusal.js';
4
+ import { coerceForColumn, columnKind } from '../../shared/schema.js';
5
+ import { blockingTriggers, firedBy, sayRuns, sayTriggers, sayWrite } from './scopeTriggers.js';
6
+ import { detachStoredText, overlaid, storedText, storedTextOf } from './storedText.js';
7
+ /** A foreign key's name in ScopeCatalog.references: its table, name and columns, each side. */
8
+ export const referenceKey = (fk) => JSON.stringify([fk.from.table, fk.name, fk.from.columns, fk.to.table, fk.to.columns]);
9
+ /** Whether a failure is the database's foreign key refusing a write: SQLite's SQLITE_CONSTRAINT_FOREIGNKEY, PostgreSQL's 23503. */
10
+ export const isForeignKeyViolation = (error) => {
11
+ const { code, errcode } = (error ?? {});
12
+ return errcode === 787 || code === '23503';
13
+ };
14
+ /**
15
+ * A foreign key's refusal of a scoped write, said as a hidden parent's is: the database's own error says whether the
16
+ * row it points at exists (and, on PostgreSQL, its key, a default's part of it included), which the principal's rows
17
+ * may hide. Whichever statement it came from, at the statement or at COMMIT for a deferred one, it is the one
18
+ * refusal; what the operator reads names the constraint and nothing of the row.
19
+ */
20
+ export const foreignKeyRefusal = (error) => {
21
+ const constraint = error?.constraint;
22
+ return recordRefusalCause(new ScopeRefusal('This operation is not available in the current row scope.'), `The database's foreign key${typeof constraint === 'string' ? ` ${JSON.stringify(constraint)}` : ''} refused the write: a row it points at is not in the principal's rows, or does not exist.`);
23
+ };
3
24
  /** A table's triggers as a refusal names them: `the trigger "audit_order"`, `the triggers "a", "b"`. */
4
25
  export const triggerNames = (names) => `the trigger${names.length === 1 ? '' : 's'} ${names.map((name) => JSON.stringify(name)).join(', ')}`;
26
+ /* The trigger vocabulary, for `mistri check` (commandTriggerChecks.ts), which says the same refusal ahead of time. */
27
+ export { blocksEveryWrite, sayBlocked, sayRuns, sayTriggers } from './scopeTriggers.js';
28
+ /** The keyed-effect judge (triggerEffects.ts), loaded where it is used: a process that never meets a named trigger never loads it. */
29
+ export const loadTriggerEffects = () => import('./triggerEffects.js');
30
+ /**
31
+ * The count of rows of `fk.from.table` that reference the `fk.to.table` row
32
+ * `key` names, as the database's own foreign key matches them, and so as its
33
+ * cascade would reach them.
34
+ *
35
+ * A foreign key compares a reference as the parent key compares: SQLite
36
+ * applies the parent column's affinity and collation to the child's value
37
+ * (an untyped child column holding the number 7 references the text key
38
+ * '7'), PostgreSQL the parent's collation where the child's is the default.
39
+ * The child counted by its own column (`child.col = ?`) compares as the child
40
+ * does, and missed such a reference, which the delete's cascade then reached.
41
+ * Here each parent column is the left side of a join, where both engines take
42
+ * its affinity and collation as the foreign key does; where two collations
43
+ * conflict, PostgreSQL refuses the count, and the delete with it. On
44
+ * PostgreSQL the join compares by the constraint's own operator
45
+ * (`conpfeqop`), each side cast as ri_triggers.c casts it: the comparison the
46
+ * catalog read for the parent check (ScopeCatalog.references,
47
+ * Condition.equality), so a `char(3)` key reaches the `text` reference 'ab '
48
+ * the cascade reaches, and no `=` on the search_path decides what is counted.
49
+ * A key whose comparison the catalog refused refuses the count.
50
+ */
51
+ export function referencesStatement(catalog, fk, key, style) {
52
+ const { schema } = catalog;
53
+ const tableOf = (id) => {
54
+ const table = schema.tables.find((table) => table.id === id);
55
+ if (!table)
56
+ throw new Refusal('This operation is not available in the current row scope.');
57
+ return table;
58
+ };
59
+ const relation = (table) => `${style.quote(table.schema)}.${style.quote(table.name)}`;
60
+ const compared = catalog.references?.get(referenceKey(fk));
61
+ if (catalog.references && !compared)
62
+ refuse(`"${fk.from.table}" has a foreign key whose comparison was not read with the catalog.`);
63
+ if (compared && 'refused' in compared)
64
+ refuse(compared.refused);
65
+ const columns = compared && 'columns' in compared ? compared.columns : undefined;
66
+ const parent = tableOf(fk.to.table);
67
+ const on = buildWhere({
68
+ groups: [
69
+ fk.to.columns.map((column, index) => {
70
+ const equality = columns?.[index]?.equality;
71
+ return { column, op: '=', other: fk.from.columns[index], ...(equality ? { equality } : {}) };
72
+ }),
73
+ ],
74
+ }, style, 1, (name) => `p.${style.quote(name)}`, (name) => `c.${style.quote(name)}`, undefined, undefined, true);
75
+ const typeOf = (name) => parent.columns.find((column) => column.name === name)?.type;
76
+ const where = buildWhere(key, style, 1, (name) => `p.${style.quote(name)}`, undefined, undefined, undefined, false, typeOf);
77
+ if (!where.text)
78
+ throw new Refusal('This operation is not available in the current row scope.');
79
+ return {
80
+ text: `SELECT COUNT(*) AS n FROM ${relation(tableOf(fk.from.table))} AS c JOIN ${relation(parent)} AS p ON ${on.text.replace(/^ WHERE /, '')}${where.text}`,
81
+ params: where.params,
82
+ };
83
+ }
5
84
  /** The tables where `scope` is exactly `bound`, and the bound admits rows at all: nothing in it is hidden there. */
6
85
  export function wholeWithin(scope, bound) {
7
86
  return new Set(Object.keys(bound).filter((table) => bound[table] !== false && Object.hasOwn(scope, table) && JSON.stringify(scope[table]) === JSON.stringify(bound[table])));
@@ -27,6 +106,21 @@ const keyText = (key) => Object.entries(key)
27
106
  .map(([column, value]) => `${column} ${JSON.stringify(value)}`)
28
107
  .join(', ');
29
108
  const comparable = (value) => typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value));
109
+ /* A value for a number column as the write sends it: "" is NULL, "7.0" is 7 (sqlite.ts and postgres.ts coerce every
110
+ value by its column's type before binding it). Only numbers: a parent check binds what it is given, and a number
111
+ is where the given text and the written value part. */
112
+ const asWritten = (type, value) => type !== undefined && columnKind(type) === 'number' && typeof value === 'string' ? coerceForColumn(type, value) : value;
113
+ /* A value a PostgreSQL reference compared through its foreign key's equality (Condition.equality) is bound as text and
114
+ read by the column's type: a boolean as its word. Every other type a reference may be (keyTypes.ts) the driver reads
115
+ as a string or a number already, which is its text. */
116
+ const asBound = (value) => (typeof value === 'boolean' ? String(value) : value);
117
+ /* Two values a check binds name the same parent: identical, or, where both are bound as text read by the column's type
118
+ (Condition.equality), the same text — a given 7 and the stored "7" are the one parameter. */
119
+ const sameBound = (a, b, equality) => a === b ||
120
+ (equality &&
121
+ (typeof a === 'string' || typeof a === 'number') &&
122
+ (typeof b === 'string' || typeof b === 'number') &&
123
+ String(a) === String(b));
30
124
  /** `scope` with each child rule's key conditions on a reference to a table in `made` extended by those rows' keys. */
31
125
  function withOwnRows(schema, scope, made) {
32
126
  const out = { ...scope };
@@ -66,7 +160,7 @@ function withOwnRows(schema, scope, made) {
66
160
  /** Runs INSIDE a single queued operation. The supplied guards retain actual
67
161
  * stored scalar types, not display conversions (a blob label is not a key).
68
162
  * This capability deliberately refuses side effects it cannot bound. */
69
- export function createScopedTransaction(catalog, records, reads, guards, locks, bound, own) {
163
+ export function createScopedTransaction(catalog, records, reads, guards, locks, bound, own, triggers) {
70
164
  /* The rows this transaction inserted inside the principal's rows, by table, and the reads that count them in
71
165
  (ScopeOwnRows). Rebuilt on each such insert; until the first, the reads are the ones resolved for the request. */
72
166
  const made = new Map();
@@ -78,13 +172,29 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
78
172
  reads = own.reads(scope, false);
79
173
  guards = own.reads(scope, true);
80
174
  };
81
- const target = (id) => {
175
+ const target = (id, write) => {
82
176
  const table = catalog.schema.tables.find((table) => table.id === id);
83
177
  if (!table)
84
178
  return refuse(`"${id}" is not in this write's footprint: a command writes only the tables it declares.`);
85
- if (!catalog.writable.has(id)) {
86
- /* A trigger writes what no row policy bounds, so a scoped write never fires one: name it, or the owner is left
87
- guessing why a table they declared written is not. */
179
+ if (catalog.hierarchy?.has(id))
180
+ return refuse(`"${id}" is part of a partition or inheritance hierarchy, which writes under a row policy do not support yet.`);
181
+ const triggers = catalog.writable.has(id) ? undefined : catalog.triggered?.get(id);
182
+ if (triggers) {
183
+ /* A trigger does what no row policy bounds, so a scoped write fires none but those proven to validate their own
184
+ row. Decided per write: an update of a column no `UPDATE OF` names fires nothing. The refusal names the
185
+ trigger, or the owner is left guessing why a table they declared written is not. */
186
+ const foldCase = catalog.schema.dialect === 'sqlite';
187
+ // A trigger the App names and the proof accepts runs, its effects proven per write (triggerProof.ts).
188
+ const blocking = blockingTriggers(triggers, write, foldCase)
189
+ .filter((trigger) => !proof?.accepts(id, trigger))
190
+ .map((trigger) => ({ ...trigger, why: proof?.unaccepted(id, trigger) ?? trigger.why }));
191
+ if (blocking.length)
192
+ return refuse(`"${id}" cannot be written under a row policy: ${sayWrite(write)} ${sayRuns(blocking)} ${sayTriggers(blocking)}, whose effects the policy cannot bound. ` +
193
+ `A trigger that only checks NEW and OLD and raises does not block a write; mistri check names each command one blocks.`);
194
+ if (firedBy(triggers, write, foldCase).length)
195
+ locks?.relied?.(table);
196
+ }
197
+ else if (!catalog.writable.has(id)) {
88
198
  const by = catalog.blockedBy?.get(id);
89
199
  return refuse(by
90
200
  ? `"${id}" cannot be written under a row policy: it has ${by}, whose writes the policy cannot bound.`
@@ -92,6 +202,10 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
92
202
  }
93
203
  if (!table.columns.some((column) => column.primaryKey))
94
204
  return refuse(`"${id}" has no primary key, so a scoped write cannot prove which row it changed.`);
205
+ const unkeyed = catalog.unkeyed?.get(id);
206
+ if (unkeyed)
207
+ return refuse(`${unkeyed}.`);
208
+ locks?.written?.(table);
95
209
  return table;
96
210
  };
97
211
  const keyFilter = (table, key) => {
@@ -106,9 +220,16 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
106
220
  ends, so what the scope checks is what the write will change. Where the
107
221
  writer sends together, the read leaves right behind the lock, in its
108
222
  flight; the server runs it only once the lock is granted. */
223
+ /* A row by its key, with its reference columns' stored text beside it where the engine reads one (storedText.ts):
224
+ every check that takes a value from a stored row binds that text, never the driver's reading of it. */
225
+ const readStored = async (table, filter, within) => {
226
+ const texts = storedTextOf(catalog.schema, table);
227
+ const result = await within.query({ table: table.id, filter, limit: 2, offset: 0, ...(texts ? { storedText: true } : {}) });
228
+ return { ...result, rows: result.rows.map((row) => detachStoredText(texts, row)) };
229
+ };
109
230
  const lockedRead = async (table, filter, within) => {
110
231
  const locked = locks?.target(table, filter);
111
- const read = () => within.query({ table: table.id, filter, limit: 2, offset: 0 });
232
+ const read = () => readStored(table, filter, within);
112
233
  if (!locks?.together) {
113
234
  await locked;
114
235
  return read();
@@ -138,21 +259,92 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
138
259
 
139
260
  Each reference is checked by its parent's lock, then that parent's count
140
261
  under the principal's rows; a reference that cannot be checked ends the
141
- list, refused there, so the checks before it still speak first. */
142
- const parentChecks = (table, row, set) => {
262
+ list, refused there, so the checks before it still speak first.
263
+
264
+ The references a write names are checked before it is sent, not only
265
+ after: the database's own foreign key answers a parent that does not
266
+ exist with its error, at the statement, while a parent that exists and
267
+ is hidden passed the statement and was refused after it. The two
268
+ answers told a hidden row from a missing one. Checked first, both are
269
+ the one refusal below. `given` keeps to the references whose every
270
+ column the write names; the rest (a default, a value a trigger sets)
271
+ are checked after the statement as before.
272
+
273
+ A reference is checked as the database's foreign key compares it
274
+ (ScopeCatalog.references), with the value the write sends: a check that
275
+ compared otherwise found one parent where the foreign key found
276
+ another, a hidden one (a char(3) value against a text key on
277
+ PostgreSQL, whose foreign key drops its padding; a REAL column's 7.0
278
+ against a TEXT key on SQLite). A value the write sends as NULL ("" for
279
+ a number) points at nothing. And a row that names itself as its own
280
+ parent by the key it gives (`{id: 1, parent_id: 1}`) is that parent:
281
+ it exists once the statement has run, and is checked after it. */
282
+ const comparisonOf = (fk) => {
283
+ const said = catalog.references?.get(referenceKey(fk));
284
+ if (said)
285
+ return said;
286
+ if (catalog.references)
287
+ return {
288
+ refused: `"${fk.from.table}".${fk.from.columns.join('+')} has a foreign key whose comparison was not read with the catalog.`,
289
+ };
290
+ const child = catalog.schema.tables.find((table) => table.id === fk.from.table);
291
+ return { columns: fk.from.columns.map((name) => ({ type: child?.columns.find((column) => column.name === name)?.type ?? '' })) };
292
+ };
293
+ /* A reference with a generated column (the catalog marks one unwritable: PostgreSQL's attgenerated, SQLite's
294
+ table_xinfo hidden 2 or 3) moves with whatever column its expression reads, which no update names: an update of
295
+ `x` re-pointed `k GENERATED ALWAYS AS (x + 1) REFERENCES p` at a hidden parent, checked by nobody. So every update
296
+ touches it, and it is checked after the statement, from the row as stored; before the statement its value is not
297
+ known (what the row held is not what the update leaves), so a check of what a write gives leaves it out. */
298
+ const generated = (table, name) => table.columns.find((column) => column.name === name)?.writable === false;
299
+ const generatedIn = (table, fk) => fk.from.columns.some((name) => generated(table, name));
300
+ const parentChecks = (table, row, set, given = false) => {
143
301
  const checks = [];
144
- for (const fk of catalog.schema.foreignKeys.filter((fk) => fk.from.table === table.id && (!set || fk.from.columns.some((column) => set.has(column))))) {
145
- const values = fk.from.columns.map((column) => row[column]);
302
+ for (const fk of catalog.schema.foreignKeys.filter((fk) => fk.from.table === table.id &&
303
+ (!set || fk.from.columns.some((column) => set.has(column)) || (!given && generatedIn(table, fk))) &&
304
+ (!given || (!generatedIn(table, fk) && fk.from.columns.every((column) => Object.hasOwn(row, column) && row[column] !== undefined))))) {
305
+ const compared = comparisonOf(fk);
306
+ // A value the row holds as stored is bound as the text it was read as (storedText.ts); one given, as given.
307
+ const texts = storedText(row);
308
+ const values = fk.from.columns.map((column, index) => {
309
+ const compares = 'columns' in compared ? compared.columns[index] : undefined;
310
+ if (compares?.equality && texts && Object.hasOwn(texts, column) && Object.hasOwn(row, column))
311
+ return texts[column];
312
+ const value = asWritten(compares?.type, row[column]);
313
+ return compares?.equality ? asBound(value) : value;
314
+ });
146
315
  if (values.some((value) => value === null))
147
316
  continue;
148
- if (!values.every(comparable)) {
149
- checks.push({ refused: `"${table.id}".${fk.from.columns.join('+')} holds a value that is not a text or a number.` });
317
+ if (catalog.inheritanceParents?.has(fk.to.table)) {
318
+ checks.push({
319
+ refused: `"${table.id}" references "${fk.to.table}", an inheritance parent: its foreign key reads the parent's own rows and a parent check its children's too, which writes under a row policy do not support yet.`,
320
+ });
321
+ break;
322
+ }
323
+ if ('refused' in compared) {
324
+ checks.push({ refused: compared.refused });
325
+ break;
326
+ }
327
+ const unsupported = values.findIndex((value) => !comparable(value));
328
+ if (unsupported !== -1) {
329
+ checks.push({
330
+ refused: `"${table.id}".${fk.from.columns[unsupported]} holds a value of a type a scoped write does not support for a reference: a check could not bind it as the foreign key compares it.`,
331
+ });
150
332
  break;
151
333
  }
334
+ if (given &&
335
+ fk.to.table === table.id &&
336
+ fk.to.columns.every((column, index) => Object.hasOwn(row, column) &&
337
+ asWritten(table.columns.find((candidate) => candidate.name === column)?.type, row[column]) === values[index]))
338
+ continue;
152
339
  // Parent columns stay on the SQL left-hand side so SQLite's parent
153
340
  // affinity and collation, rather than JavaScript equality, decide.
154
341
  const filter = {
155
- groups: [fk.to.columns.map((column, index) => ({ column, op: '=', value: values[index] }))],
342
+ groups: [
343
+ fk.to.columns.map((column, index) => {
344
+ const equality = compared.columns[index]?.equality;
345
+ return { column, op: '=', value: values[index], ...(equality ? { equality } : {}) };
346
+ }),
347
+ ],
156
348
  };
157
349
  const parent = catalog.schema.tables.find((table) => table.id === fk.to.table);
158
350
  if (!parent) {
@@ -165,6 +357,8 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
165
357
  }
166
358
  return checks;
167
359
  };
360
+ /** Whether a check binds every value as text read by its column's type (Condition.equality): PostgreSQL's. */
361
+ const bindsText = (check) => check.filter.groups[0].every((condition) => condition.equality);
168
362
  const unseen = (check) => `"${check.fk.from.table}".${check.fk.from.columns.join('+')} points at the "${check.fk.to.table}" row ${keyText(Object.fromEntries(check.fk.to.columns.map((column, index) => [column, check.values[index]])))}, which the principal's rows do not include (or the command does not declare "${check.fk.to.table}" read).`;
169
363
  /** The checks sent at once (locks.together): each parent's lock, then its count, every answer heard. */
170
364
  const ask = (checks) => checks.map((check) => {
@@ -184,10 +378,14 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
184
378
  const check = checks[index];
185
379
  if ('refused' in guess || 'refused' in check)
186
380
  return 'refused' in guess && 'refused' in check && guess.refused === check.refused;
187
- return guess.fk === check.fk && guess.values.every((value, at) => value === check.values[at]);
381
+ return guess.fk === check.fk && guess.values.every((value, at) => sameBound(value, check.values[at], bindsText(check)));
188
382
  });
189
- const parents = async (table, row, set, guessed) => {
190
- const checks = parentChecks(table, row, set);
383
+ /* References this transaction has proven: each parent locked and counted inside the principal's rows, which holds
384
+ until COMMIT (the lock), so the same reference is not asked again after the write that made it. */
385
+ const proven = [];
386
+ const unproven = (checks) => checks.filter((check) => 'refused' in check ||
387
+ !proven.some((done) => done.fk === check.fk && done.values.every((value, at) => sameBound(value, check.values[at], bindsText(check)))));
388
+ const verify = async (checks, guessed) => {
191
389
  if (!locks?.together) {
192
390
  for (const check of checks) {
193
391
  if ('refused' in check)
@@ -196,6 +394,7 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
196
394
  await locks?.parent(check.parent, check.filter);
197
395
  if ((await guards.count(check.fk.to.table, check.filter)) !== 1)
198
396
  return refuse(unseen(check));
397
+ proven.push(check);
199
398
  }
200
399
  return;
201
400
  }
@@ -208,14 +407,74 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
208
407
  await check.locked;
209
408
  if ((await check.counted) !== 1)
210
409
  return refuse(unseen(check));
410
+ proven.push(check);
211
411
  }
212
412
  };
413
+ const parents = async (table, row, set, guessed, given = false) => verify(unproven(parentChecks(table, row, set, given)), guessed);
414
+ /**
415
+ * Before a write: the references it names, checked as `parents` checks them. Where the writer sends together, the
416
+ * checks leave ahead of the write, in its flight, and `write` is sent behind them before any is judged: the server
417
+ * runs them first, and a refused one is said whatever the write then answered (a foreign key's error included).
418
+ */
419
+ const parentsFirst = async (checks, write) => {
420
+ if (!locks?.together) {
421
+ await verify(checks);
422
+ return write();
423
+ }
424
+ const asked = ask(checks);
425
+ const sent = write();
426
+ await Promise.allSettled([sent, ...asked.flatMap((check) => ('refused' in check ? [] : [check.locked, check.counted]))]);
427
+ await verify(checks, asked);
428
+ return sent;
429
+ };
430
+ /* Triggers the App names: each write that fires one proves its effects' keys first and the rest right after the
431
+ statement, with the transaction's own locks and guards (triggerProof.ts). */
432
+ const proof = triggers
433
+ ? triggers.prove(triggers.acceptance, {
434
+ tables: catalog.schema.tables,
435
+ foreignKeys: catalog.schema.foreignKeys,
436
+ triggered: catalog.triggered,
437
+ foldCase: catalog.schema.dialect === 'sqlite',
438
+ scope: triggers.scope,
439
+ guards: () => guards,
440
+ lockedRead,
441
+ read: (table, filter) => readStored(table, filter, guards),
442
+ parents: (table, row, set) => parents(table, row, set),
443
+ parentsBefore: (table, row, set) => parents(table, row, set, undefined, true),
444
+ ...(locks ? { holdParent: (table, filter) => locks.parent(table, filter) } : {}),
445
+ ...(locks?.relied ? { relied: (table) => locks.relied(table) } : {}),
446
+ ...(triggers.watch ? { watch: triggers.watch } : {}),
447
+ refuse,
448
+ })
449
+ : undefined;
450
+ /* The statements themselves. A foreign key that refuses one answers as a hidden parent does (foreignKeyRefusal):
451
+ the checks before a write compare what it names, and this is everything they cannot see — a default's part of a
452
+ reference, a value a trigger writes, a deferred check. */
453
+ const statement = (sent) => sent.catch((error) => {
454
+ throw isForeignKeyViolation(error) ? foreignKeyRefusal(error) : error;
455
+ });
456
+ const insertRow = (request) => statement(records.insert(request));
457
+ const updateRow = (request) => statement(records.update(request));
458
+ const afterward = async (afterwards, images) => {
459
+ for (const next of afterwards ?? [])
460
+ await next(images);
461
+ };
213
462
  return Object.freeze({
214
463
  query: (request) => reads.query(request),
215
464
  count: (table, filter) => reads.count(table, filter),
465
+ /* Under the principal's rows, as `count` reads: never the writer's own unscoped aggregate. */
466
+ ...(reads.aggregate
467
+ ? {
468
+ aggregate: (request) => reads.aggregate ? reads.aggregate(request) : refuse('This scope cannot aggregate.'),
469
+ }
470
+ : {}),
216
471
  async insert(request) {
217
- const table = target(request.table);
218
- const result = await records.insert(request);
472
+ const table = target(request.table, { kind: 'insert' });
473
+ const afterwards = proof && (await proof.before(table, { kind: 'insert' }, proof.images.insert(table, request.values)));
474
+ const given = unproven(parentChecks(table, request.values ?? {}, undefined, true));
475
+ if (!locks?.together)
476
+ await verify(given);
477
+ const result = locks?.together ? await parentsFirst(given, () => insertRow(request)) : await insertRow(request);
219
478
  const filter = keyFilter(table, result.key);
220
479
  /* The new row locked and read back, and where the writer sends together
221
480
  its references checked in the same flight, from the row the INSERT
@@ -223,21 +482,24 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
223
482
  those). No other transaction can see this row yet, so its lock is
224
483
  granted at once and the read answers what a count before it would. */
225
484
  const read = lockedRead(table, filter, guards);
226
- const guessed = locks?.together && result.row ? ask(parentChecks(table, result.row)) : undefined;
485
+ const guessed = locks?.together && result.row ? ask(unproven(parentChecks(table, result.row))) : undefined;
227
486
  read.catch(() => { });
228
487
  const found = await read;
229
488
  // Inside the bound and outside the principal's rows: the command's own row, answered by its key and what it wrote.
230
489
  if (bound && found.rows.length !== 1) {
231
- await parents(table, await stored(table, result.key, bound.reads), undefined, guessed);
490
+ const within = await stored(table, result.key, bound.reads);
491
+ await parents(table, within, undefined, guessed);
492
+ await afterward(afterwards, { new: within, old: null });
232
493
  return { key: result.key, applied: result.applied, sql: result.sql };
233
494
  }
234
495
  const row = one(table, result.key, found);
235
496
  await parents(table, row, undefined, guessed);
497
+ await afterward(afterwards, { new: row, old: null });
236
498
  madeBy(table, row);
237
499
  return result;
238
500
  },
239
501
  async update(request) {
240
- const table = target(request.table);
502
+ const table = target(request.table, { kind: 'update', set: Object.keys(request.values ?? {}) });
241
503
  const protectedColumns = new Set([
242
504
  ...table.columns.filter((column) => column.primaryKey).map((column) => column.name),
243
505
  ...catalog.schema.foreignKeys.filter((fk) => fk.to.table === table.id).flatMap((fk) => fk.to.columns),
@@ -247,32 +509,44 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
247
509
  return refuse(`A scoped update may not change "${table.id}".${moved.join(', ')}: a key, or a column another table references.`);
248
510
  const before = await stored(table, request.key);
249
511
  const set = new Set(Object.keys(request.values ?? {}));
512
+ const afterwards = proof && (await proof.before(table, { kind: 'update', set: [...set] }, proof.images.update(table, before, request.values)));
513
+ // What the update sets is given; every other column of a reference it sets in part is as stored, bound as its text.
514
+ const given = unproven(parentChecks(table, overlaid(before, request.values), set, true));
515
+ if (!locks?.together)
516
+ await verify(given);
250
517
  /* The row read again after the write, sent the moment the write is: it
251
518
  reads what the write wrote, and leaves in the write's round trip, with
252
- the references the write sets checked behind it, as the row will hold
253
- them. A write that fails aborts them too, and the write's failure is
254
- the one thrown. */
519
+ the references the write sets checked ahead of it, as the row will
520
+ hold them. A reference refused is the answer whatever the write said;
521
+ otherwise a write that fails aborts the read too, and the write's
522
+ failure is the one thrown. */
255
523
  const after = {};
256
524
  const withdraw = locks?.behind?.(table, () => {
257
525
  after.row = stored(table, request.key);
258
526
  after.row.catch(() => { });
259
- if (locks.together)
260
- after.guessed = ask(parentChecks(table, { ...before, ...request.values }, set));
261
527
  });
262
528
  let result;
263
529
  try {
264
- result = await records.update(request);
530
+ // The references it sets leave ahead of it, in its flight (parentsFirst).
531
+ result = locks?.together ? await parentsFirst(given, () => updateRow(request)) : await updateRow(request);
265
532
  }
266
533
  finally {
267
534
  withdraw?.();
268
535
  }
269
536
  if (result.affected !== 1)
270
537
  return refuse(`The update of "${table.id}" changed ${result.affected} rows, not one.`);
271
- await parents(table, await (after.row ?? stored(table, request.key)), set, after.guessed);
538
+ const now = await (after.row ?? stored(table, request.key));
539
+ /* A key or a referenced column the database generates moves with the columns its expression reads, which the
540
+ names above cannot catch: one that moved is refused, whatever a cascade or the foreign key made of it. */
541
+ const shifted = [...protectedColumns].filter((column) => generated(table, column) && JSON.stringify(before[column]) !== JSON.stringify(now[column]));
542
+ if (shifted.length)
543
+ return refuse(`A scoped update may not change "${table.id}".${shifted.join(', ')}: a key, or a column another table references, generated from the columns it sets.`);
544
+ await parents(table, now, set);
545
+ await afterward(afterwards, { new: now, old: before });
272
546
  return result;
273
547
  },
274
548
  async remove(request) {
275
- const table = target(request.table);
549
+ const table = target(request.table, { kind: 'delete' });
276
550
  const children = catalog.schema.foreignKeys.filter((fk) => fk.to.table === table.id);
277
551
  const hidden = children.find((fk) => !bound?.whole.has(fk.from.table));
278
552
  if (hidden)
@@ -288,15 +562,15 @@ export function createScopedTransaction(catalog, records, reads, guards, locks,
288
562
  continue;
289
563
  if (!values.every(comparable))
290
564
  return refuse(`"${table.id}".${fk.to.columns.join('+')} holds a value that is not a text or a number.`);
291
- const filter = {
292
- groups: [fk.from.columns.map((column, index) => ({ column, op: '=', value: values[index] }))],
293
- };
294
- if ((await records.count(fk.from.table, filter)) !== 0)
565
+ const key = { groups: [Object.entries(request.key).map(([column, value]) => ({ column, op: '=', value }))] };
566
+ if ((await bound?.references(fk, key)) !== 0)
295
567
  return refuse(`A scoped command may not delete the "${table.id}" row ${keyText(request.key)}: "${fk.from.table}" still references it.`);
296
568
  }
297
- const result = await records.remove(request);
569
+ const afterwards = proof && (await proof.before(table, { kind: 'delete' }, proof.images.delete(row)));
570
+ const result = await statement(records.remove(request));
298
571
  if (result.affected !== 1)
299
572
  return refuse(`The delete from "${table.id}" removed ${result.affected} rows, not one.`);
573
+ await afterward(afterwards, { new: null, old: row });
300
574
  return result;
301
575
  },
302
576
  });
@@ -1,12 +1,28 @@
1
1
  import type { DatabaseSync } from 'node:sqlite';
2
2
  import { type DatabaseSchema } from '../../shared/schema.js';
3
3
  import { type ScopeCatalog } from './scopedTransaction.js';
4
+ import type { EffectCatalog, resolveTriggerEffects } from './triggerEffects.js';
4
5
  export type SqliteScopeCatalog = ScopeCatalog;
5
6
  /** Call only on the writer inside BEGIN IMMEDIATE. No cached/public catalog,
6
7
  * estimates or data scans: the lease's physical metadata is the authority.
7
8
  * A non-writable table remains in the graph so hidden dependents cannot vanish.
8
9
  */
9
- export declare function readSqliteScopeCatalog(db: DatabaseSync): SqliteScopeCatalog;
10
+ export declare function readSqliteScopeCatalog(db: DatabaseSync, resolve?: typeof resolveTriggerEffects): SqliteScopeCatalog;
11
+ /**
12
+ * How a key equality in a trigger compares on SQLite (triggerEffects.ts): each column's affinity, which decides what
13
+ * a value is converted to before it is compared, and its collation, which `NEW.code = code` takes from the column on
14
+ * its left; and the primary key as a key only where its index compares each column under that column's own
15
+ * collation (`PRIMARY KEY (code COLLATE NOCASE)` on a BINARY column is unique under one and found under the other).
16
+ * And the conflict clause a table declares other than ABORT, which a trigger's write runs under when the statement
17
+ * that fired it is a delete (triggerEffects.ts). Read where effects are judged, inside the writer's BEGIN IMMEDIATE.
18
+ */
19
+ export declare function sqliteKeyFacts(db: DatabaseSync): Pick<EffectCatalog, 'keys' | 'comparison' | 'conflicts'>;
20
+ /**
21
+ * For `mistri check`: the tables a scoped write cannot target for what they are rather than their triggers — a
22
+ * virtual table and its shadow tables, whose module writes them (scanSqliteScopeCatalog keeps them out of
23
+ * `writable`) — read on the reader, so check refuses an effect on one as the write does.
24
+ */
25
+ export declare function sqliteBlockedTables(db: DatabaseSync): ReadonlyMap<string, string>;
10
26
  /** Metadata-only read attestation inside the caller's owned snapshot. Exposes
11
27
  * no writer eligibility. Keep every non-engine table and dependency, including
12
28
  * private/unmapped objects, so an unknown business edge cannot disappear. */