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

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 (73) 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 +174 -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 +18 -0
  14. package/dist/adapters/scoped/postgresScopeCatalog.js +353 -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 +23 -5
  21. package/dist/adapters/scoped/scopedTransaction.d.ts +76 -6
  22. package/dist/adapters/scoped/scopedTransaction.js +278 -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/migrate/cli.d.ts +50 -3
  54. package/dist/server/migrate/cli.js +199 -14
  55. package/dist/server/migrate/runner.js +5 -1
  56. package/dist/server/shapeonly.js +5 -0
  57. package/dist/shared/aggregate.d.ts +49 -0
  58. package/dist/shared/aggregate.js +107 -0
  59. package/dist/shared/breakdown.js +17 -4
  60. package/dist/shared/decimals.d.ts +37 -0
  61. package/dist/shared/decimals.js +148 -0
  62. package/dist/shared/displayDefaults.js +15 -1
  63. package/dist/shared/filter.d.ts +22 -1
  64. package/dist/shared/filter.js +36 -9
  65. package/dist/shared/money.d.ts +9 -0
  66. package/dist/shared/money.js +17 -0
  67. package/dist/shared/pageModel.d.ts +1 -1
  68. package/dist/shared/refusal.d.ts +16 -0
  69. package/dist/shared/refusal.js +40 -0
  70. package/dist/shared/schema.d.ts +6 -0
  71. package/dist/shared/scopeCatalog.js +4 -0
  72. package/dist/shared/servedApp.d.ts +7 -2
  73. package/package.json +5 -1
@@ -1,7 +1,9 @@
1
1
  import { ANSI_STYLE, Refusal } from '../adapter.js';
2
2
  import { chooseColumnReference, deleteRuleOf, } from '../../shared/schema.js';
3
3
  import { mapScopeCatalog } from '../../shared/scopeCatalog.js';
4
- import { triggerNames } from './scopedTransaction.js';
4
+ import { referenceKey } from './scopedTransaction.js';
5
+ import { keyTypeRefusal, sqliteAffinity, sqliteKeyType, sqliteTypeSaid } from './keyTypes.js';
6
+ import { readSqliteTrigger, sqliteColumnCollations, sqliteConflictClauses } from './sqliteTriggers.js';
5
7
  /* `table_xinfo`'s hidden: 0 a plain column, 1 a virtual table's own (its module's plumbing), 2 and 3 generated
6
8
  (virtual, stored). A generated column keeps its table in scope: it is computed from the row the policy or the
7
9
  tenant predicate already bounds, so a scoped read reads it and a scoped write leaves it to the database (sqlite.ts
@@ -29,9 +31,178 @@ function identities(items) {
29
31
  * estimates or data scans: the lease's physical metadata is the authority.
30
32
  * A non-writable table remains in the graph so hidden dependents cannot vanish.
31
33
  */
32
- export function readSqliteScopeCatalog(db) {
33
- const { schema, writable, blockedBy } = scanSqliteScopeCatalog(db);
34
- return { schema, writable, ...(blockedBy.size ? { blockedBy } : {}) };
34
+ export function readSqliteScopeCatalog(db, resolve) {
35
+ const scanned = scanSqliteScopeCatalog(db);
36
+ const { schema, writable } = scanned;
37
+ /* Keyed effects are judged against the catalog they run in (triggerEffects.ts, which the caller loads); a database
38
+ without them asks nothing more. Unjudged, none is accepted. */
39
+ const keyed = [...scanned.triggered.values()].some((triggers) => triggers.some((trigger) => trigger.effects));
40
+ const triggered = !keyed
41
+ ? scanned.triggered
42
+ : resolve
43
+ ? resolve({ schema, writable, triggered: scanned.triggered, foldCase: true, ...sqliteKeyFacts(db) })
44
+ : new Map([...scanned.triggered].map(([id, triggers]) => [
45
+ id,
46
+ triggers.map((trigger) => trigger.effects ? { ...trigger, unaccepted: 'its effects were not judged against the catalog' } : trigger),
47
+ ]));
48
+ const unkeyed = sqliteUnkeyed(schema);
49
+ return {
50
+ schema,
51
+ writable,
52
+ ...(triggered.size ? { triggered } : {}),
53
+ references: sqliteReferences(schema),
54
+ ...(unkeyed.size ? { unkeyed } : {}),
55
+ };
56
+ }
57
+ /** The tables whose primary key has a column of a type a scoped write does not take as a row's identity (keyTypes.ts), with why. */
58
+ function sqliteUnkeyed(schema) {
59
+ const unkeyed = new Map();
60
+ for (const table of schema.tables) {
61
+ const column = table.columns.find((candidate) => candidate.primaryKey && !sqliteKeyType(candidate.type));
62
+ if (column)
63
+ unkeyed.set(table.id, keyTypeRefusal('sqlite', table.id, column.name, sqliteTypeSaid(column.type)));
64
+ }
65
+ return unkeyed;
66
+ }
67
+ /**
68
+ * Whether SQLite's foreign key can find another parent than a check before the write, for a child column of affinity
69
+ * `child` and a parent key of `parent`, each of a type a key may be (keyTypes.ts: INTEGER or TEXT, and a typeless
70
+ * child). The foreign key applies the parent's affinity to what the child column stored (its own affinity applied to
71
+ * the value written, datatype3.html 3.0); the check applies the parent's affinity to the value written. The two part
72
+ * only where the child's affinity changes a value in a way the parent's does not undo:
73
+ *
74
+ * - BLOB (a typeless column) converts nothing: what it stores is what was written. Never.
75
+ * - The same affinity twice: applying one affinity again changes nothing. Never.
76
+ * - TEXT against an INTEGER key: a number stored as its text reads back as that number under the key's affinity, and
77
+ * a text stays the text it was. Never.
78
+ * - INTEGER against a TEXT key: "7.0" is stored as 7 and the key reads "7". The check, given "7.0", reads otherwise,
79
+ * and a number read back is the number given, so nothing after the statement tells them apart. Refused.
80
+ */
81
+ const affinitiesPart = (child, parent) => {
82
+ const [c, p] = [sqliteAffinity(child), sqliteAffinity(parent)];
83
+ return c !== 'BLOB' && c !== p && p === 'TEXT';
84
+ };
85
+ /**
86
+ * How each foreign key compares a reference (ScopeCatalog.references). SQLite's applies the parent column's affinity
87
+ * to the value the child column stored, which that column's own affinity made of what was written; a parent check
88
+ * binds what was written and the parent column applies its affinity to that. The two agree unless the child's
89
+ * affinity changes the value first in a way the parent's does not undo (affinitiesPart): an INTEGER column stores
90
+ * "7.0" as 7, which a TEXT key reads as '7', where the check's '7.0' found '7.0'. A write through such a foreign key
91
+ * cannot be checked, and is refused, as is one where either side is of a type a key may not be (keyTypes.ts); one
92
+ * through a typeless reference, or a TEXT one to an INTEGER key, is checked.
93
+ */
94
+ function sqliteReferences(schema) {
95
+ const typeOf = (table, name) => schema.tables.find((candidate) => candidate.id === table)?.columns.find((column) => column.name === name)?.type;
96
+ const references = new Map();
97
+ for (const fk of schema.foreignKeys) {
98
+ const types = fk.from.columns.map((column) => typeOf(fk.from.table, column));
99
+ const parents = fk.to.columns.map((column) => typeOf(fk.to.table, column));
100
+ /* Each side of a reference is a row's identity (keyTypes.ts): the key it points at of a type on the list, and the
101
+ reference too, or typeless (BLOB affinity), which stores what was written and so compares as the check does. */
102
+ const unkeyed = parents.findIndex((type) => type !== undefined && !sqliteKeyType(type));
103
+ const unkeyedChild = types.findIndex((type) => type !== undefined && !sqliteKeyType(type) && sqliteAffinity(type) !== 'BLOB');
104
+ const differ = types.findIndex((type, index) => type === undefined || parents[index] === undefined || affinitiesPart(type, parents[index]));
105
+ references.set(referenceKey(fk), unkeyed !== -1
106
+ ? { refused: `${keyTypeRefusal('sqlite', fk.to.table, fk.to.columns[unkeyed], sqliteTypeSaid(parents[unkeyed]))}.` }
107
+ : unkeyedChild !== -1
108
+ ? { refused: `${keyTypeRefusal('sqlite', fk.from.table, fk.from.columns[unkeyedChild], sqliteTypeSaid(types[unkeyedChild]))}.` }
109
+ : differ === -1 && types.length === parents.length
110
+ ? { columns: types.map((type) => ({ type: type })) }
111
+ : {
112
+ refused: `"${fk.from.table}".${fk.from.columns[differ] ?? fk.from.columns.join('+')} references "${fk.to.table}".${fk.to.columns[differ] ?? fk.to.columns.join('+')}, ` +
113
+ "a column of another affinity that changes the value before the foreign key compares it: SQLite's foreign key compares it as no check before the write can, so a scoped write that sets it is refused.",
114
+ });
115
+ }
116
+ return references;
117
+ }
118
+ /**
119
+ * How a key equality in a trigger compares on SQLite (triggerEffects.ts): each column's affinity, which decides what
120
+ * a value is converted to before it is compared, and its collation, which `NEW.code = code` takes from the column on
121
+ * its left; and the primary key as a key only where its index compares each column under that column's own
122
+ * collation (`PRIMARY KEY (code COLLATE NOCASE)` on a BINARY column is unique under one and found under the other).
123
+ * And the conflict clause a table declares other than ABORT, which a trigger's write runs under when the statement
124
+ * that fired it is a delete (triggerEffects.ts). Read where effects are judged, inside the writer's BEGIN IMMEDIATE.
125
+ */
126
+ export function sqliteKeyFacts(db) {
127
+ const definitions = new Map();
128
+ const definitionOf = (table) => {
129
+ if (!definitions.has(table.id)) {
130
+ const row = db.prepare("SELECT sql FROM main.sqlite_schema WHERE type = 'table' AND name = ?").get(table.name);
131
+ definitions.set(table.id, typeof row?.sql === 'string' ? row.sql : undefined);
132
+ }
133
+ return definitions.get(table.id);
134
+ };
135
+ const collations = new Map();
136
+ const collationsOf = (table) => {
137
+ if (!collations.has(table.id)) {
138
+ const sql = definitionOf(table);
139
+ collations.set(table.id, sql === undefined ? undefined : sqliteColumnCollations(sql));
140
+ }
141
+ return collations.get(table.id);
142
+ };
143
+ const conflicts = (table) => {
144
+ const sql = definitionOf(table);
145
+ const clauses = sql === undefined ? undefined : sqliteConflictClauses(sql);
146
+ if (!clauses)
147
+ return 'a conflict clause mistri cannot read';
148
+ // ABORT is what the statement's own OR ABORT would say; any other changes what a conflicting write does.
149
+ return clauses.find((clause) => clause !== 'ON CONFLICT ABORT');
150
+ };
151
+ const comparison = (table, name) => {
152
+ const column = table.columns.find((candidate) => folded(candidate.name) === folded(name));
153
+ const collation = column && collationsOf(table)?.get(folded(column.name));
154
+ if (!column || !collation)
155
+ return undefined;
156
+ const type = sqliteAffinity(column.type);
157
+ return {
158
+ type,
159
+ collation,
160
+ exact: true,
161
+ said: `${type} affinity, COLLATE ${collation}`,
162
+ keyable: sqliteKeyType(column.type),
163
+ declared: sqliteTypeSaid(column.type),
164
+ };
165
+ };
166
+ const keys = (table) => {
167
+ const primary = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
168
+ if (!primary.length)
169
+ return [];
170
+ // A rowid alias holds integers alone, compared by no collation; it has no index of its own.
171
+ if (primary.length === 1 && table.columns.find((column) => column.name === primary[0])?.identity)
172
+ return [primary];
173
+ const index = db
174
+ .prepare(`PRAGMA main.index_list(${ANSI_STYLE.quote(table.name)})`)
175
+ .all()
176
+ .find((row) => row.origin === 'pk');
177
+ if (typeof index?.name !== 'string')
178
+ return [];
179
+ const indexed = db
180
+ .prepare(`PRAGMA main.index_xinfo(${ANSI_STYLE.quote(index.name)})`)
181
+ .all()
182
+ .filter((row) => row.key === 1);
183
+ const same = primary.every((name) => {
184
+ const at = indexed.find((row) => typeof row.name === 'string' && folded(row.name) === folded(name));
185
+ const own = comparison(table, name);
186
+ return typeof at?.coll === 'string' && own !== undefined && at.coll.toUpperCase() === own.collation;
187
+ });
188
+ return same && indexed.length === primary.length ? [primary] : [];
189
+ };
190
+ return { keys, comparison, conflicts };
191
+ }
192
+ /**
193
+ * For `mistri check`: the tables a scoped write cannot target for what they are rather than their triggers — a
194
+ * virtual table and its shadow tables, whose module writes them (scanSqliteScopeCatalog keeps them out of
195
+ * `writable`) — read on the reader, so check refuses an effect on one as the write does.
196
+ */
197
+ export function sqliteBlockedTables(db) {
198
+ const blocked = new Map();
199
+ for (const table of db.prepare('PRAGMA main.table_list').all()) {
200
+ if (table.schema !== 'main' || typeof table.name !== 'string')
201
+ continue;
202
+ if (table.type === 'virtual' || table.type === 'shadow')
203
+ blocked.set(table.name, "a virtual table's module, whose writes the policy cannot bound");
204
+ }
205
+ return blocked;
35
206
  }
36
207
  /** Metadata-only read attestation inside the caller's owned snapshot. Exposes
37
208
  * no writer eligibility. Keep every non-engine table and dependency, including
@@ -56,25 +227,27 @@ function scanSqliteScopeCatalog(db) {
56
227
  if (!listed.some((table) => table.schema === 'main' && table.name === 'sqlite_schema' && table.type === 'table'))
57
228
  return refuse();
58
229
  const kinds = identities(listed.filter((table) => table.schema === 'main'));
59
- const blocked = new Set();
60
- const triggered = new Map();
230
+ /* Each table's triggers, main and TEMP, with the statement that made them: which writes fire each, and whether
231
+ it only validates its row, is read from that text per table below (sqliteTriggers.ts, scopeTriggers.ts). */
232
+ const definitions = new Map();
61
233
  for (const namespace of ['main', 'temp']) {
62
234
  const triggers = db
63
- .prepare(`SELECT tbl_name AS name, name AS trigger FROM ${namespace}.sqlite_schema WHERE type = 'trigger' ORDER BY name`)
235
+ .prepare(`SELECT tbl_name AS name, name AS trigger, sql FROM ${namespace}.sqlite_schema WHERE type = 'trigger' ORDER BY name`)
64
236
  .all();
65
237
  for (const trigger of triggers) {
66
238
  if (typeof trigger.name !== 'string' || typeof trigger.trigger !== 'string')
67
239
  return refuse();
68
- blocked.add(folded(trigger.name));
69
- triggered.set(folded(trigger.name), [...(triggered.get(folded(trigger.name)) ?? []), trigger.trigger]);
240
+ definitions.set(folded(trigger.name), [
241
+ ...(definitions.get(folded(trigger.name)) ?? []),
242
+ { name: trigger.trigger, sql: trigger.sql },
243
+ ]);
70
244
  }
71
245
  }
72
- const blockedBy = new Map();
246
+ const triggered = new Map();
73
247
  const shadowed = new Set();
74
248
  for (const table of db.prepare("SELECT name FROM temp.sqlite_schema WHERE type IN ('table', 'view')").all()) {
75
249
  if (typeof table.name !== 'string')
76
250
  return refuse();
77
- blocked.add(folded(table.name));
78
251
  shadowed.add(folded(table.name));
79
252
  }
80
253
  const tables = [];
@@ -134,12 +307,18 @@ function scanSqliteScopeCatalog(db) {
134
307
  columnsByTable.set(entry.name, columns);
135
308
  if (kind.type === 'table' &&
136
309
  !folded(entry.name).startsWith('sqlite_') &&
137
- !blocked.has(folded(entry.name)) &&
138
- columns.every((column) => column.hidden !== 1))
139
- writable.add(entry.name);
140
- const triggers = kind.type === 'table' ? triggered.get(folded(entry.name)) : undefined;
141
- if (triggers)
142
- blockedBy.set(entry.name, triggerNames(triggers));
310
+ !shadowed.has(folded(entry.name)) &&
311
+ columns.every((column) => column.hidden !== 1)) {
312
+ /* A table with triggers is written only by the writes that fire none of them but validation-only ones
313
+ (scopedTransaction.ts target): it stays out of `writable`, which says every write may run. */
314
+ const triggers = definitions.get(folded(entry.name));
315
+ if (!triggers)
316
+ writable.add(entry.name);
317
+ else {
318
+ const computed = new Set(columns.filter(generated).map((column) => folded(column.name)));
319
+ triggered.set(entry.name, triggers.map((trigger) => readSqliteTrigger(trigger.name, trigger.sql, computed)));
320
+ }
321
+ }
143
322
  if (kind.type === 'table' &&
144
323
  !folded(entry.name).startsWith('sqlite_') &&
145
324
  !shadowed.has(folded(entry.name)) &&
@@ -225,7 +404,7 @@ function scanSqliteScopeCatalog(db) {
225
404
  schema: { dialect: 'sqlite', label: 'SQLite scoped transaction', readAt: new Date().toISOString(), tables, foreignKeys },
226
405
  writable,
227
406
  readable,
228
- blockedBy,
407
+ triggered,
229
408
  };
230
409
  }
231
410
  catch (error) {
@@ -0,0 +1,64 @@
1
+ /**
2
+ * SQLite's second look at what an accepted trigger wrote (docs/trigger-effects.md, decision 2): the proof
3
+ * (triggerProof.ts) reaches every row an effect names before and after its statement, and this checks that the
4
+ * database did no more. From the first write that fires an accepted trigger, a session records the transaction's
5
+ * changes; before COMMIT its changeset is read, and every change SQLite marks indirect — made by a trigger, not by
6
+ * the transaction's own statements — must be a row the proof reached. One that is not refuses the transaction
7
+ * whole, so a trigger the grammar misread cannot write past it.
8
+ *
9
+ * A change is matched by what it did as well as by its key: an insert the proof reached is no warrant for an update
10
+ * of a row with that key. A table's `ON CONFLICT REPLACE` turns an insert into an overwrite of the row already
11
+ * there, which the changeset records as an update (triggerEffects.ts refuses such a table as an effect's; this
12
+ * would still see it). A changeset folds the changes to one row into one: an insert then an update is an insert, an
13
+ * update then a delete a delete, and a delete then an insert of the same key an update.
14
+ *
15
+ * A change SQLite calls direct is not always only the transaction's own: one to a row the transaction wrote itself
16
+ * stays direct however many triggers write that row after (sqlite3session_indirect), so a trigger the proof never
17
+ * reached could rewrite such a row unseen. After each of the transaction's own statements the witness keeps what the
18
+ * changeset says of the row it wrote, and from then on that row's change must stay as kept unless the proof reached
19
+ * it since: checked after every later statement and before COMMIT. What a trigger writes to that row within the very
20
+ * statement that writes it folds into the statement's own change and is not told apart.
21
+ *
22
+ * A scoped delete never cascades (scopedTransaction.ts refuses one others reference), so a trigger is the only
23
+ * source of an indirect change here. A session sees only tables with a primary key, so an effect on one without is
24
+ * refused when it is proven.
25
+ */
26
+ import type { DatabaseSync } from 'node:sqlite';
27
+ import type { TableMeta } from '../../shared/schema.js';
28
+ import type { TriggerChange } from './triggerProof.js';
29
+ export interface TriggerWitness {
30
+ /** Before a statement that fires an accepted trigger: from here on, the transaction's changes are recorded. */
31
+ watch(): void;
32
+ /** A row the proof reached. */
33
+ proven(change: TriggerChange): void;
34
+ /**
35
+ * After one of the transaction's own statements, the row it wrote: its table and primary key, and for an update the
36
+ * values it set (a key it changed is the row's key now). Every row an earlier statement wrote is still as that
37
+ * statement left it, or the proof reached it since, or `refuse` throws.
38
+ */
39
+ wrote(table: string, key: Readonly<Record<string, unknown>>, values?: Readonly<Record<string, unknown>>): void;
40
+ /**
41
+ * A row's key as its table stores it, read by the key a write names (or that key, where no row has it): what a
42
+ * delete is told by, read before the row is gone. `wrote` reads the stored key itself after an insert or update.
43
+ */
44
+ stored(table: string, key: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
45
+ /** Before COMMIT: every indirect change is one the proof reached, and every row the transaction wrote is as it last
46
+ * left it or reached since, or `refuse` throws. Ends the session. */
47
+ settle(): void;
48
+ /** Ends the session without a look: the transaction is rolling back. */
49
+ close(): void;
50
+ }
51
+ type Value = string | number | null | undefined;
52
+ /** One change of a changeset: its table, its operation, whether a trigger made it, its primary key's values by column
53
+ * position, and every value it records (an update's old values then its new, undefined where a column is unchanged). */
54
+ interface Change {
55
+ readonly table: string;
56
+ readonly op: 'insert' | 'update' | 'delete';
57
+ readonly indirect: boolean;
58
+ readonly key: ReadonlyMap<number, Value>;
59
+ readonly values: readonly Value[];
60
+ }
61
+ /** The changes of a changeset (sqlite.org/sessionintro.html, "changeset format"). */
62
+ export declare function readChangeset(bytes: Uint8Array): Change[];
63
+ export declare function sqliteTriggerWitness(db: DatabaseSync, tables: readonly TableMeta[]): TriggerWitness;
64
+ export {};
@@ -0,0 +1,245 @@
1
+ import { recordRefusalCause } from '../../shared/refusal.js';
2
+ import { ScopeRefusal } from './scopedTransaction.js';
3
+ const OPS = { 18: 'insert', 23: 'update', 9: 'delete' };
4
+ /** The changes of a changeset (sqlite.org/sessionintro.html, "changeset format"). */
5
+ export function readChangeset(bytes) {
6
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
7
+ const text = new TextDecoder('utf-8', { fatal: false });
8
+ let at = 0;
9
+ const varint = () => {
10
+ let value = 0;
11
+ for (let i = 0; i < 9; i++) {
12
+ const byte = bytes[at++];
13
+ if (i === 8)
14
+ return value * 256 + byte;
15
+ value = value * 128 + (byte & 0x7f);
16
+ if (!(byte & 0x80))
17
+ return value;
18
+ }
19
+ return value;
20
+ };
21
+ const value = () => {
22
+ const type = bytes[at++];
23
+ switch (type) {
24
+ case 0:
25
+ return undefined;
26
+ case 1: {
27
+ const big = view.getBigInt64(at);
28
+ at += 8;
29
+ return big >= BigInt(Number.MIN_SAFE_INTEGER) && big <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(big) : big.toString();
30
+ }
31
+ case 2: {
32
+ const float = view.getFloat64(at);
33
+ at += 8;
34
+ return float;
35
+ }
36
+ case 3:
37
+ case 4: {
38
+ const length = varint();
39
+ const part = bytes.subarray(at, at + length);
40
+ at += length;
41
+ return type === 3 ? text.decode(part) : `x'${Buffer.from(part).toString('hex')}'`;
42
+ }
43
+ case 5:
44
+ return null;
45
+ default:
46
+ throw new Error(`a changeset value of type ${type}`);
47
+ }
48
+ };
49
+ const changes = [];
50
+ let table = '';
51
+ let pk = [];
52
+ while (at < bytes.length) {
53
+ const marker = bytes[at++];
54
+ if (marker === 0x54) {
55
+ const columns = varint();
56
+ pk = [...bytes.subarray(at, at + columns)];
57
+ at += columns;
58
+ const end = bytes.indexOf(0, at);
59
+ table = text.decode(bytes.subarray(at, end));
60
+ at = end + 1;
61
+ continue;
62
+ }
63
+ const op = OPS[marker];
64
+ if (!op)
65
+ throw new Error(`a changeset operation of ${marker}`);
66
+ const indirect = bytes[at++] !== 0;
67
+ const record = () => pk.map(() => value());
68
+ const first = record();
69
+ const second = op === 'update' ? record() : [];
70
+ // An update's old record carries its primary key; an insert's new and a delete's old carry every column.
71
+ const key = new Map();
72
+ pk.forEach((flag, index) => flag && key.set(index, first[index]));
73
+ changes.push({ table, op, indirect, key, values: [...first, ...second] });
74
+ }
75
+ return changes;
76
+ }
77
+ /** What a change did to its row, comparable: an undefined (unchanged) value is told from a null. */
78
+ const signature = (change) => JSON.stringify([change.op, change.values.map((value) => (value === undefined ? { unchanged: true } : value))]);
79
+ /* A key's values as the changeset says them (readChangeset): a BLOB as its `x'…'` hex, which String() said as its
80
+ bytes' digits ("1,2"), so a row the transaction wrote by a BLOB key was never found in the changeset. */
81
+ const keyText = (columns, values) => JSON.stringify(columns
82
+ .map((column, index) => {
83
+ const value = values[index];
84
+ return [
85
+ column.toLowerCase(),
86
+ value === null ? null : value instanceof Uint8Array ? `x'${Buffer.from(value).toString('hex')}'` : String(value),
87
+ ];
88
+ })
89
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
90
+ /* Said as every row-scope refusal is (scopedTransaction.ts), the reason recorded beneath for the operator. */
91
+ const refuse = (reason) => {
92
+ throw recordRefusalCause(new ScopeRefusal('This operation is not available in the current row scope.'), reason);
93
+ };
94
+ export function sqliteTriggerWitness(db, tables) {
95
+ let session;
96
+ /** Keys the proof reached, by lower-cased table and what it did to each; and the inserts it proved whose key the database assigned. */
97
+ const reached = new Map();
98
+ const did = (op, key) => `${op}\u0000${key}`;
99
+ const keyless = new Map();
100
+ /** Rows the proof reached since the transaction's own rows were last looked at, as `table\u0000key`. */
101
+ let recent = new Set();
102
+ /** The transaction's own rows, as `table\u0000key`, with what the changeset said of each after the statement that wrote it last. */
103
+ const own = new Map();
104
+ const columnsOf = new Map();
105
+ const tableOf = (name) => tables.find((table) => table.id.toLowerCase() === name.toLowerCase());
106
+ const end = () => {
107
+ try {
108
+ session?.close();
109
+ }
110
+ catch {
111
+ /* A session over a closed handle has nothing left to say. */
112
+ }
113
+ session = undefined;
114
+ };
115
+ return {
116
+ watch() {
117
+ session ??= db.createSession();
118
+ },
119
+ proven(change) {
120
+ const table = tableOf(change.table);
121
+ if (!table?.columns.some((column) => column.primaryKey))
122
+ return refuse(`The trigger ${JSON.stringify(change.trigger)} writes "${change.table}", which has no primary key: SQLite cannot witness its rows.`);
123
+ const name = table.id.toLowerCase();
124
+ if (!change.key) {
125
+ keyless.set(name, (keyless.get(name) ?? 0) + 1);
126
+ return;
127
+ }
128
+ const key = keyText(Object.keys(change.key), Object.values(change.key));
129
+ const keys = reached.get(name) ?? new Set();
130
+ keys.add(did(change.kind, key));
131
+ reached.set(name, keys);
132
+ recent.add(`${name}\u0000${key}`);
133
+ },
134
+ wrote(name, key, values) {
135
+ if (!session)
136
+ return;
137
+ const table = tableOf(name);
138
+ if (!table)
139
+ return;
140
+ const columns = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
141
+ const at = (named) => `${table.id.toLowerCase()}\u0000${keyText(columns, columns.map((column) => named[column]))}`;
142
+ // An update that changes the key leaves the old key deleted and the new one inserted: both are its own.
143
+ const moved = {
144
+ ...key,
145
+ ...Object.fromEntries(columns.filter((column) => values && column in values).map((column) => [column, values[column]])),
146
+ };
147
+ const written = new Set([at(storedKey(table, key)), at(storedKey(table, moved))]);
148
+ const changes = current(session.changeset());
149
+ ownStill(changes, written);
150
+ for (const row of written)
151
+ own.set(row, changes.get(row)?.signature ?? 'absent');
152
+ },
153
+ settle() {
154
+ if (!session)
155
+ return;
156
+ const bytes = session.changeset();
157
+ end();
158
+ const changes = current(bytes);
159
+ ownStill(changes);
160
+ for (const { change, name, key } of changes.values()) {
161
+ if (!change.indirect)
162
+ continue;
163
+ const proven = reached.get(name);
164
+ // An update in the changeset is the proof's update, or its delete and then its insert of the same key.
165
+ if (proven?.has(did(change.op, key)) ||
166
+ (change.op === 'update' && proven?.has(did('delete', key)) && proven.has(did('insert', key))))
167
+ continue;
168
+ const left = keyless.get(name) ?? 0;
169
+ if (change.op === 'insert' && left > 0) {
170
+ keyless.set(name, left - 1);
171
+ continue;
172
+ }
173
+ return refuse(`A trigger ${change.op === 'insert' ? 'inserted' : change.op === 'update' ? 'updated' : 'deleted'} a row of "${change.table}" ` +
174
+ "that no accepted effect reached: SQLite's session saw it, the proof did not, and nothing the transaction wrote is kept.");
175
+ }
176
+ },
177
+ stored(name, key) {
178
+ const table = tableOf(name);
179
+ return session && table ? storedKey(table, key) : key;
180
+ },
181
+ close: end,
182
+ };
183
+ /**
184
+ * `key` as the row it names stores it, read back by the table's own comparison, or `key` where no row has it. The
185
+ * changeset names a row by what is stored: a NOCASE key written as "ABC" is the row "abc", an INTEGER one written as
186
+ * "1.0" the row 1, and kept under the key as sent, the transaction's own row was never found in it.
187
+ */
188
+ function storedKey(table, key) {
189
+ const columns = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
190
+ const bound = columns.map((column) => key[column]);
191
+ if (bound.some((value) => value === undefined || value === null))
192
+ return key;
193
+ const quote = (name) => `"${name.replaceAll('"', '""')}"`;
194
+ const statement = db.prepare(`SELECT ${columns.map(quote).join(', ')} FROM ${quote(table.id)} WHERE ${columns.map((column) => `${quote(column)} = ?`).join(' AND ')}`);
195
+ // Read as the changeset reads them (readChangeset): an integer past 2^53 is its digits.
196
+ statement.setReadBigInts(true);
197
+ const rows = statement.all(...bound);
198
+ if (rows.length !== 1)
199
+ return key;
200
+ return Object.fromEntries(columns.map((column) => {
201
+ const value = rows[0][column];
202
+ return [
203
+ column,
204
+ typeof value === 'bigint'
205
+ ? value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
206
+ ? Number(value)
207
+ : value.toString()
208
+ : value,
209
+ ];
210
+ }));
211
+ }
212
+ /** A changeset's changes by `table\u0000key`, each with its lower-cased table, its key as `keyText` says it, and its signature. */
213
+ function current(bytes) {
214
+ const result = new Map();
215
+ for (const change of readChangeset(bytes)) {
216
+ const name = change.table.toLowerCase();
217
+ let columns = columnsOf.get(name);
218
+ if (!columns) {
219
+ columns = db.prepare('SELECT name FROM pragma_table_info(?)').all(change.table).map((row) => row.name);
220
+ columnsOf.set(name, columns);
221
+ }
222
+ const positions = [...change.key.keys()];
223
+ const key = keyText(positions.map((index) => columns[index]), positions.map((index) => change.key.get(index)));
224
+ result.set(`${name}\u0000${key}`, { change, name, key, signature: signature(change) });
225
+ }
226
+ return result;
227
+ }
228
+ /** Every row of the transaction's own, but those in `except`, as the statement that wrote it left it, or reached by the proof
229
+ * since it was last looked at (and kept as it is now). */
230
+ function ownStill(changes, except) {
231
+ for (const [row, kept] of own) {
232
+ if (except?.has(row))
233
+ continue;
234
+ const now = changes.get(row)?.signature ?? 'absent';
235
+ if (now === kept)
236
+ continue;
237
+ // The session is kept: a command that caught this refusal and went on is refused again before COMMIT.
238
+ if (!recent.has(row))
239
+ return refuse(`A trigger wrote a row of "${row.slice(0, row.indexOf('\u0000'))}" that the transaction wrote itself and no accepted effect ` +
240
+ "reached: SQLite's session saw it, the proof did not, and nothing the transaction wrote is kept.");
241
+ own.set(row, now);
242
+ }
243
+ recent = new Set();
244
+ }
245
+ }
@@ -0,0 +1,20 @@
1
+ import { type ScopeTrigger } from './scopeTriggers.js';
2
+ /**
3
+ * The trigger `name`, from its `CREATE TRIGGER` text. `generated` holds the
4
+ * table's generated columns, folded: an `UPDATE OF` naming one is taken to
5
+ * fire on every update, rather than trusting when the engine recomputes it.
6
+ */
7
+ export declare function readSqliteTrigger(name: string, sql: unknown, generated: ReadonlySet<string>): ScopeTrigger;
8
+ /**
9
+ * Each column's collation, by its name folded, as a table's `CREATE TABLE` text declares it: a `COLLATE` among the
10
+ * column's own constraints (outside any parenthesis), or BINARY. SQLite keeps no other record of it (no PRAGMA says
11
+ * a column's collation), and a trigger's `NEW.code = code` compares under the left column's. Undefined where the
12
+ * text is not one this reads; a column it cannot read is missing, and either way a key over it is refused.
13
+ */
14
+ export declare function sqliteColumnCollations(sql: string): Map<string, string> | undefined;
15
+ /**
16
+ * The conflict clauses a table's `CREATE TABLE` text declares (`PRIMARY KEY ON CONFLICT REPLACE`, `NOT NULL ON
17
+ * CONFLICT IGNORE`), each as `ON CONFLICT <resolution>`, upper-cased, in order. SQLite keeps no other record of them.
18
+ * Undefined where the text is not one this reads.
19
+ */
20
+ export declare function sqliteConflictClauses(sql: string): string[] | undefined;