@mistriwork/engine 1.0.0-rc.32 → 1.0.0-rc.34

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.
@@ -8,14 +8,14 @@
8
8
  * works for both is unlikely to be accidentally Postgres-shaped.
9
9
  */
10
10
  import { statSync } from 'node:fs';
11
- import { waitForLocks, assertIndependentWrite, writeToFile, prepareGuarded, transactionEpoch, storeEpoch } from './sqliteHandles.js';
11
+ import { waitForLocks, assertIndependentWrite, writeToFile, prepareGuarded, transactionEpoch, storeEpoch, schemaFingerprint, } from './sqliteHandles.js';
12
12
  import { captureScopeCatalog, mapScopeCatalog } from '../shared/scopeCatalog.js';
13
13
  import { inlineRows } from '../shared/anyRows.js';
14
14
  import { asksAboutRows } from '../shared/filter.js';
15
15
  import { qualifiedTable } from '../shared/sqlRelation.js';
16
16
  import { DatabaseSync } from 'node:sqlite';
17
17
  import { isPromise, isProxy } from 'node:util/types';
18
- import { ANSI_STYLE, buildWhere, clampLimit, clampOffset, boundStatement, looksWrappable, dedupe, refuseStacked, trimStatement, Refusal, WriteConflict, TransactionOutcomeUnknown, Serial, TransactionOperations, queueRecordLock, recordLockFilter, refuseAnalyze, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, } from './adapter.js';
18
+ import { ANSI_STYLE, buildWhere, clampLimit, clampOffset, boundStatement, looksWrappable, dedupe, refuseStacked, trimStatement, Refusal, WriteConflict, TransactionOutcomeUnknown, Serial, TransactionOperations, queueRecordLock, recordLockFilter, refuseAnalyze, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, batchedRows, chunked, gathered, refuseUpdateMatches, runsOfColumns, sameTable, } from './adapter.js';
19
19
  import { compileAggregate } from '../shared/aggregate.js';
20
20
  import { readExactly, summed } from '../shared/decimals.js';
21
21
  import { buildUpdateGuard } from './scoped/updateGuard.js';
@@ -767,6 +767,97 @@ export class SqliteAdapter {
767
767
  return this.queueWrite(() => this.updateNow(request));
768
768
  }
769
769
  async updateNow(request, read = this.db, scoped = false) {
770
+ const { table, meta, pk, applied } = this.updatePlan(request, read);
771
+ const filter = {
772
+ groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
773
+ };
774
+ /* Outside a transaction the count runs first, on the read handle, so the
775
+ check that decides whether to write cannot itself write. Inside one it
776
+ is the UPDATE's own count: the key is the whole primary key, so it
777
+ matches one row or none, and a refusal rolls the transaction back. */
778
+ const transactional = read !== this.db;
779
+ const matches = transactional ? 1 : await this.count(table, filter);
780
+ if (matches !== 1)
781
+ refuseUpdateMatches(request, matches);
782
+ const where = buildWhere(filter, ANSI_STYLE);
783
+ const assignments = Object.keys(applied)
784
+ .map((c) => `${ANSI_STYLE.quote(c)} = ?`)
785
+ .join(', ');
786
+ const guard = buildUpdateGuard(request, Object.fromEntries(meta.map((column) => [column.name, column.type])), ANSI_STYLE, 'sqlite', 1);
787
+ const text = `UPDATE ${scoped ? 'OR ABORT ' : ''}${ANSI_STYLE.quote(table)} SET ${assignments}${where.text}${guard.text}`;
788
+ const params = [...Object.values(applied), ...where.params, ...guard.params];
789
+ const write = read === this.db ? this.writeHandle() : read;
790
+ const result = write.prepare(text).run(...sqliteParams(params));
791
+ if (request.expected !== undefined && Number(result.changes) === 0)
792
+ throw new WriteConflict();
793
+ if (transactional && Number(result.changes) !== 1)
794
+ refuseUpdateMatches(request, Number(result.changes));
795
+ return { affected: Number(result.changes), applied, sql: { text, params } };
796
+ }
797
+ /**
798
+ * Several rows of one table changed by one statement inside a transaction, each as `updateNow` changes one: the
799
+ * same refusals before it, each row's own values and `expected`, one row a key. A `CASE` a column picks each
800
+ * row's value, the WHERE matches each key with its own guard, and RETURNING says which requests matched, so a
801
+ * row whose key or guard missed refuses the batch as it would have refused alone.
802
+ */
803
+ updateManyNow(requests, handle) {
804
+ const plans = requests.map((request) => ({ request, ...this.updatePlan(request, handle) }));
805
+ const table = sameTable(plans.map((plan) => plan.table));
806
+ const pk = plans[0].pk;
807
+ const types = Object.fromEntries(plans[0].meta.map((column) => [column.name, column.type]));
808
+ const keys = new Set();
809
+ for (const { request } of plans) {
810
+ const key = JSON.stringify(pk.map((column) => String(request.key[column])));
811
+ if (keys.has(key))
812
+ throw new Refusal(`A batch changes each row of ${table} once; that key appears twice.`);
813
+ keys.add(key);
814
+ }
815
+ const results = [];
816
+ for (const chunk of chunked(plans, (plan) => pk.length * (Object.keys(plan.applied).length + 3) + 2 * Object.keys(plan.applied).length)) {
817
+ const match = (request) => {
818
+ const where = buildWhere({ groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))] }, ANSI_STYLE);
819
+ return { text: where.text.replace(/^ WHERE /, ''), params: where.params };
820
+ };
821
+ const params = [];
822
+ const columns = [...new Set(chunk.flatMap((plan) => Object.keys(plan.applied)))];
823
+ const assignments = columns.map((column) => {
824
+ const cases = chunk
825
+ .filter((plan) => Object.hasOwn(plan.applied, column))
826
+ .map((plan) => {
827
+ const key = match(plan.request);
828
+ params.push(...key.params, plan.applied[column]);
829
+ return `WHEN ${key.text} THEN ?`;
830
+ });
831
+ const quoted = ANSI_STYLE.quote(column);
832
+ return `${quoted} = CASE ${cases.join(' ')} ELSE ${quoted} END`;
833
+ });
834
+ const wheres = chunk.map((plan) => {
835
+ const key = match(plan.request);
836
+ const guard = buildUpdateGuard(plan.request, types, ANSI_STYLE, 'sqlite', 1);
837
+ params.push(...key.params, ...guard.params);
838
+ return `(${key.text}${guard.text})`;
839
+ });
840
+ const which = chunk.map((plan, index) => {
841
+ const key = match(plan.request);
842
+ params.push(...key.params);
843
+ return `WHEN ${key.text} THEN ${index}`;
844
+ });
845
+ const text = `UPDATE ${ANSI_STYLE.quote(table)} SET ${assignments.join(', ')} WHERE ${wheres.join(' OR ')}` +
846
+ ` RETURNING CASE ${which.join(' ')} END AS ${ANSI_STYLE.quote('mistri_batch_row')}`;
847
+ const matched = new Set(handle.prepare(text).all(...sqliteParams(params)).map((row) => Number(row.mistri_batch_row)));
848
+ chunk.forEach((plan, index) => {
849
+ if (!matched.has(index)) {
850
+ if (plan.request.expected !== undefined)
851
+ throw new WriteConflict();
852
+ refuseUpdateMatches(plan.request, 0);
853
+ }
854
+ results.push({ affected: 1, applied: plan.applied, sql: { text, params } });
855
+ });
856
+ }
857
+ return results;
858
+ }
859
+ /** What `update` refuses before it writes, and the values it writes, coerced to their columns. */
860
+ updatePlan(request, read) {
770
861
  const table = this.assertTable(request.table, read);
771
862
  /* A view with an INSTEAD OF trigger takes an UPDATE, and the trigger
772
863
  decides what changes. Refused as the other dialects refuse it: what the
@@ -808,36 +899,7 @@ export class SqliteAdapter {
808
899
  throw new Refusal(`"${column}" is NOT NULL and cannot be emptied.`);
809
900
  }
810
901
  }
811
- const filter = {
812
- groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
813
- };
814
- /* Outside a transaction the count runs first, on the read handle, so the
815
- check that decides whether to write cannot itself write. Inside one it
816
- is the UPDATE's own count: the key is the whole primary key, so it
817
- matches one row or none, and a refusal rolls the transaction back. */
818
- const transactional = read !== this.db;
819
- const matches = transactional ? 1 : await this.count(table, filter);
820
- const refuseMatches = (count) => {
821
- if (request.expected !== undefined && count === 0)
822
- throw new WriteConflict();
823
- throw new Refusal(`Refused: that key matches ${count} rows, not 1. An update is only allowed when it is certain which row it changes.`);
824
- };
825
- if (matches !== 1)
826
- refuseMatches(matches);
827
- const where = buildWhere(filter, ANSI_STYLE);
828
- const assignments = Object.keys(applied)
829
- .map((c) => `${ANSI_STYLE.quote(c)} = ?`)
830
- .join(', ');
831
- const guard = buildUpdateGuard(request, Object.fromEntries(meta.map((column) => [column.name, column.type])), ANSI_STYLE, 'sqlite', 1);
832
- const text = `UPDATE ${scoped ? 'OR ABORT ' : ''}${ANSI_STYLE.quote(table)} SET ${assignments}${where.text}${guard.text}`;
833
- const params = [...Object.values(applied), ...where.params, ...guard.params];
834
- const write = read === this.db ? this.writeHandle() : read;
835
- const result = write.prepare(text).run(...sqliteParams(params));
836
- if (request.expected !== undefined && Number(result.changes) === 0)
837
- throw new WriteConflict();
838
- if (transactional && Number(result.changes) !== 1)
839
- refuseMatches(Number(result.changes));
840
- return { affected: Number(result.changes), applied, sql: { text, params } };
902
+ return { table, meta, pk, applied };
841
903
  }
842
904
  /**
843
905
  * Add one row.
@@ -860,21 +922,7 @@ export class SqliteAdapter {
860
922
  return this.queueWrite(() => this.insertNow(request));
861
923
  }
862
924
  async insertNow(request, read = this.db, scoped = false) {
863
- const table = this.assertTable(request.table, read);
864
- const meta = this.tableInfo(table, read);
865
- const entries = Object.entries(request.values ?? {});
866
- const applied = {};
867
- for (const [column, raw] of entries) {
868
- const declared = meta.find((c) => c.name === column);
869
- if (!declared)
870
- throw new Refusal(`${table} has no column called "${column}".`);
871
- if (generated(declared))
872
- throw new Refusal(`"${column}" is generated by the database and cannot be written.`);
873
- applied[column] = coerceForColumn(declared.type || '', raw);
874
- if (applied[column] === null && declared.notnull === 1) {
875
- throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
876
- }
877
- }
925
+ const { table, meta, applied } = this.insertPlan(request, read);
878
926
  const columns = Object.keys(applied);
879
927
  // A schema-level ON CONFLICT REPLACE must never turn creation/restoration
880
928
  // into deletion of an existing row. This statement overrides that policy.
@@ -908,6 +956,72 @@ export class SqliteAdapter {
908
956
  const key = Object.fromEntries(pk.map((c) => [c, (scoped ? raw : safe)[c]]));
909
957
  return { key, row: safe, applied, sql: { text, params } };
910
958
  }
959
+ /** What `insert` refuses before it writes, and the values it writes, coerced to their columns. */
960
+ insertPlan(request, read) {
961
+ const table = this.assertTable(request.table, read);
962
+ const meta = this.tableInfo(table, read);
963
+ const applied = {};
964
+ for (const [column, raw] of Object.entries(request.values ?? {})) {
965
+ const declared = meta.find((c) => c.name === column);
966
+ if (!declared)
967
+ throw new Refusal(`${table} has no column called "${column}".`);
968
+ if (generated(declared))
969
+ throw new Refusal(`"${column}" is generated by the database and cannot be written.`);
970
+ applied[column] = coerceForColumn(declared.type || '', raw);
971
+ if (applied[column] === null && declared.notnull === 1) {
972
+ throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
973
+ }
974
+ }
975
+ return { table, meta, applied };
976
+ }
977
+ /**
978
+ * Several rows of one table added by one statement inside a transaction, each as `insertNow` adds one: one
979
+ * multi-row `INSERT OR ABORT … RETURNING *` for each run of rows naming the same columns. SQLite does not promise
980
+ * the order RETURNING answers in, so each row is matched back to the request whose values it holds (batchedRows).
981
+ */
982
+ insertManyNow(requests, handle) {
983
+ const plans = requests.map((request) => this.insertPlan(request, handle));
984
+ const table = sameTable(plans.map((plan) => plan.table));
985
+ const pk = plans[0].meta.filter((c) => c.pk > 0).map((c) => c.name);
986
+ const results = [];
987
+ for (const run of runsOfColumns(plans)) {
988
+ const columns = Object.keys(run[0].applied);
989
+ for (const chunk of chunked(run, () => Math.max(1, columns.length))) {
990
+ const params = chunk.flatMap((plan) => Object.values(plan.applied));
991
+ const text = `INSERT OR ABORT INTO ${ANSI_STYLE.quote(table)}` +
992
+ (columns.length
993
+ ? ` (${columns.map((c) => ANSI_STYLE.quote(c)).join(', ')}) VALUES ${chunk.map(() => `(${columns.map(() => '?').join(', ')})`).join(', ')}`
994
+ : ` DEFAULT VALUES`) +
995
+ ' RETURNING *';
996
+ if (!columns.length && chunk.length > 1) {
997
+ /* DEFAULT VALUES is one row; rows that name no column are added one statement each. */
998
+ for (const plan of chunk)
999
+ results.push(this.insertOne(pk, text, [], plan.applied, handle));
1000
+ continue;
1001
+ }
1002
+ const inserted = handle.prepare(text);
1003
+ inserted.setReadBigInts(true);
1004
+ const described = inserted.columns();
1005
+ const stored = inserted.all(...sqliteParams(params));
1006
+ const rows = batchedRows(chunk.map((plan) => plan.applied), stored);
1007
+ rows.forEach((row, index) => {
1008
+ const safe = toJsonSafe(scaleRows([{ ...row }], described.map((c) => c.name), scalesOf(described))[0]);
1009
+ const key = Object.fromEntries(pk.map((c) => [c, safe[c]]));
1010
+ results.push({ key, row: safe, applied: chunk[index].applied, sql: { text, params } });
1011
+ });
1012
+ }
1013
+ }
1014
+ return results;
1015
+ }
1016
+ insertOne(pk, text, params, applied, handle) {
1017
+ const inserted = handle.prepare(text);
1018
+ inserted.setReadBigInts(true);
1019
+ const described = inserted.columns();
1020
+ const stored = inserted.get(...sqliteParams(params));
1021
+ const safe = toJsonSafe(scaleRows([{ ...stored }], described.map((c) => c.name), scalesOf(described))[0]);
1022
+ const key = Object.fromEntries(pk.map((c) => [c, safe[c]]));
1023
+ return { key, row: safe, applied, sql: { text, params } };
1024
+ }
911
1025
  /**
912
1026
  * Run a statement the user wrote.
913
1027
  *
@@ -1279,19 +1393,56 @@ export class SqliteAdapter {
1279
1393
  insert: history ? (r) => history.insert(r, insert) : insert,
1280
1394
  remove: history ? (r) => history.remove(r, remove) : remove,
1281
1395
  update: history ? (r) => history.update(r, update) : update,
1396
+ /* A batch only beneath the plain facade: a row scope proves each row's statement on its own. History still
1397
+ records each row, around the one statement (gathered). */
1398
+ ...(scope === undefined
1399
+ ? {
1400
+ insertMany: (rs) => {
1401
+ const many = async (rs) => this.insertManyNow(rs, handle);
1402
+ return history ? gathered(rs, (r, write) => history.insert(r, write), many) : many(rs);
1403
+ },
1404
+ updateMany: (rs) => {
1405
+ const many = async (rs) => this.updateManyNow(rs, handle);
1406
+ return history ? gathered(rs, (r, write) => history.update(r, write), many) : many(rs);
1407
+ },
1408
+ }
1409
+ : {}),
1282
1410
  };
1283
1411
  let evidence;
1284
1412
  let physicalCatalog;
1413
+ /* The schema the last whole verification saw (schemaFingerprint). Unset until one passes, and again while one
1414
+ runs, so a verification that threw is never taken as passed. */
1415
+ let settled;
1416
+ const fingerprint = verify ? schemaFingerprint(handle) : undefined;
1285
1417
  const verified = () => {
1286
1418
  if (!verify)
1287
1419
  return;
1288
1420
  if (!handle.isTransaction || !physicalCatalog)
1289
1421
  throw new Refusal('The verified transaction is no longer active.');
1422
+ settled = undefined;
1290
1423
  const result = verify(handle, physicalCatalog);
1291
1424
  if (isPromise(result))
1292
1425
  void Promise.prototype.then.call(result, undefined, () => { });
1293
1426
  if (result !== undefined || !handle.isTransaction)
1294
1427
  throw new Refusal('Transaction verification must be synchronous.');
1428
+ settled = fingerprint();
1429
+ };
1430
+ /* Around each operation, the whole verification only when the schema moved since the last one passed. It runs
1431
+ whole when the transaction opens and again before COMMIT, which is what decides; between, nothing a handler can
1432
+ ask for changes what it attests. BEGIN IMMEDIATE holds the write lock, so no other connection changes the main
1433
+ schema; an operation runs no DDL; and the attested rows (a store's meta row, a membership) are runtime tables a
1434
+ handler cannot write. A schema change on this handle all the same (a TEMP shadow, an index, a trigger) moves the
1435
+ fingerprint, and the next operation verifies whole and refuses before anything reaches COMMIT. Verifying whole
1436
+ around every operation read the catalog twice a call: with forty tables, 100 to 150 ms of a command's every
1437
+ database call (a field report). */
1438
+ const verifiedStep = () => {
1439
+ if (!verify)
1440
+ return;
1441
+ if (!handle.isTransaction || !physicalCatalog)
1442
+ throw new Refusal('The verified transaction is no longer active.');
1443
+ if (settled !== undefined && fingerprint() === settled)
1444
+ return;
1445
+ verified();
1295
1446
  };
1296
1447
  if (scope !== undefined) {
1297
1448
  const catalog = this.catalogCache.throughSync(epoch, 'scope', () => readSqliteScopeCatalog(handle, effects?.resolveTriggerEffects));
@@ -1393,7 +1544,7 @@ export class SqliteAdapter {
1393
1544
  }
1394
1545
  verified();
1395
1546
  verifyOrdinary();
1396
- const invoke = scopedCommandInvoker(operations, scope !== undefined, journal !== undefined, isRuntimeTable, verified);
1547
+ const invoke = scopedCommandInvoker(operations, scope !== undefined, journal !== undefined, isRuntimeTable, verifiedStep);
1397
1548
  const out = maintenance
1398
1549
  ? await maintenance(handle, operations, verified)
1399
1550
  : await run(Object.freeze({
@@ -1407,9 +1558,15 @@ export class SqliteAdapter {
1407
1558
  insert: (r) => invoke(r, (r) => records.insert(r)),
1408
1559
  remove: (r) => invoke(r, (r) => records.remove(r)),
1409
1560
  update: (r) => invoke(r, (r) => records.update(r)),
1561
+ ...(scope === undefined && records.insertMany && records.updateMany
1562
+ ? {
1563
+ insertMany: (rs) => invoke(rs, (rs) => records.insertMany(rs)),
1564
+ updateMany: (rs) => invoke(rs, (rs) => records.updateMany(rs)),
1565
+ }
1566
+ : {}),
1410
1567
  // Beneath the row scope: the flows' command tells only of its own target, which it read through the scope.
1411
1568
  ...(history ? { tell: (r) => invoke(r, (r) => history.tell(r)) } : {}),
1412
- }), journal?.open(handle, operations, verify ? verified : undefined), evidence);
1569
+ }), journal?.open(handle, operations, verify ? verifiedStep : undefined), evidence);
1413
1570
  await operations.finish();
1414
1571
  witness?.settle();
1415
1572
  await finishWriteCapture(history);
@@ -36,6 +36,14 @@ export declare function transactionEpoch(db: DatabaseSync, journal?: {
36
36
  epoch?: string;
37
37
  journal: boolean;
38
38
  };
39
+ /**
40
+ * The schema a write handle sees, cheaply, for asking between a verified transaction's operations whether it moved:
41
+ * main's `schema_version` and the handle's own TEMP `schema_version`, each bumped by any schema change. The statement
42
+ * form `PRAGMA temp.schema_version` reads the TEMP schema's own counter, where the table-valued
43
+ * `temp.pragma_schema_version` (SCHEMA_EPOCH) answers main's. A manual `PRAGMA schema_version = …` reset is outside
44
+ * this contract, as it is for captureSchemaLifetime: no business operation can send one.
45
+ */
46
+ export declare function schemaFingerprint(db: DatabaseSync): () => string;
39
47
  /** The schema and whether a store's meta row says its version, in one statement; undefined when the store is not there. */
40
48
  export declare function storeEpoch(db: DatabaseSync, meta: {
41
49
  table: string;
@@ -128,6 +128,17 @@ export function transactionEpoch(db, journal) {
128
128
  return { journal: false };
129
129
  }
130
130
  }
131
+ /**
132
+ * The schema a write handle sees, cheaply, for asking between a verified transaction's operations whether it moved:
133
+ * main's `schema_version` and the handle's own TEMP `schema_version`, each bumped by any schema change. The statement
134
+ * form `PRAGMA temp.schema_version` reads the TEMP schema's own counter, where the table-valued
135
+ * `temp.pragma_schema_version` (SCHEMA_EPOCH) answers main's. A manual `PRAGMA schema_version = …` reset is outside
136
+ * this contract, as it is for captureSchemaLifetime: no business operation can send one.
137
+ */
138
+ export function schemaFingerprint(db) {
139
+ const main = db.prepare('PRAGMA main.schema_version'), temp = db.prepare('PRAGMA temp.schema_version');
140
+ return () => `${main.get()?.schema_version}.${temp.get()?.schema_version}`;
141
+ }
131
142
  /** The schema and whether a store's meta row says its version, in one statement; undefined when the store is not there. */
132
143
  export function storeEpoch(db, meta) {
133
144
  try {
@@ -31,6 +31,8 @@ export interface Options {
31
31
  noLive?: boolean;
32
32
  /** `--db-latency <ms>`: each database round trip waits this long first, in development (adapters/dbLatency.ts). */
33
33
  dbLatency?: string;
34
+ /** `--as-of <date>`: App logic's clock starts at this moment, in development and tests (http/clock.ts). */
35
+ asOf?: string;
34
36
  /** Extra names the `Host` header may carry. See `doorRefusal`. */
35
37
  allowedHosts: string[];
36
38
  /** Speak MCP over stdio instead of serving HTTP. For coding agents. */
@@ -122,6 +122,8 @@ export function parseArgs(argv) {
122
122
  opts.noLive = true;
123
123
  else if (arg === '--db-latency')
124
124
  opts.dbLatency = argv[++i] ?? '';
125
+ else if (arg === '--as-of')
126
+ opts.asOf = argv[++i] ?? '';
125
127
  else if (arg === '--app')
126
128
  (opts.apps ??= []).push(argv[++i] ?? '');
127
129
  else if (arg === '--mount') {
@@ -143,7 +143,7 @@ const writesHead = (head) => Boolean(head?.title ||
143
143
  /** Generate only registered token names and validated theme values. Row text
144
144
  * exists only in escaped JSON; it can never close a style/script element. */
145
145
  function brandingHead(html, presentation, base) {
146
- const theme = parseThemes([presentation.value.theme], 'Request branding')[0];
146
+ const theme = parseThemes([presentation.value.theme], 'Request branding', 'themes', { platform: true })[0];
147
147
  const declarations = (mode) => {
148
148
  const pairs = [];
149
149
  for (const [key, token] of Object.entries(PALETTE_TOKENS)) {
@@ -94,17 +94,19 @@ export type ResourceChecks = ReturnType<typeof resourceChecks>;
94
94
  * App's validation, transitions, stamps, fixed actions and what a line
95
95
  * consumes). Each runs once the grant's own checks have passed, and writes
96
96
  * through the transaction the checks were given; left out, the write is that
97
- * transaction's own.
97
+ * transaction's own. Where a rule is handed `write`, the row's own write goes
98
+ * through it rather than the transaction: that is how a batch carries each
99
+ * row's rules around one statement (adapter.ts `gathered`).
98
100
  */
99
101
  export interface WriteRules<G extends ColumnGrant> {
100
102
  /** This call's grant, kept stable across its awaits: `captureGrant`, with the product's own rules copied beside it. */
101
103
  capture(grant: G): G;
102
104
  /** A lock on a table the grant does not write, which the reader may still update some other way. */
103
105
  locksUnwritable?(table: string, grant: G): boolean;
104
- insert?(request: InsertRequest, grant: G, server: boolean): ReturnType<WriteTransaction['insert']>;
106
+ insert?(request: InsertRequest, grant: G, server: boolean, write?: WriteTransaction['insert']): ReturnType<WriteTransaction['insert']>;
105
107
  /** An update to a table outside `writable`: what answers it instead of the grant's refusal, or undefined. */
106
- unwritable?(request: UpdateRequest, grant: G): ReturnType<WriteTransaction['update']> | undefined;
107
- update?(request: UpdateRequest, grant: G): ReturnType<WriteTransaction['update']>;
108
+ unwritable?(request: UpdateRequest, grant: G, write?: WriteTransaction['update']): ReturnType<WriteTransaction['update']> | undefined;
109
+ update?(request: UpdateRequest, grant: G, write?: WriteTransaction['update']): ReturnType<WriteTransaction['update']>;
108
110
  remove?(request: DeleteRequest, grant: G): ReturnType<WriteTransaction['remove']>;
109
111
  }
110
112
  /** Apply the same graph-aware checks to an already-owned transaction handle. */
@@ -8,7 +8,7 @@
8
8
  * `WriteRules`) and a connection's hidden columns (hiddenColumns.ts), which
9
9
  * has no App in it to ask.
10
10
  */
11
- import { ANSI_STYLE, Refusal, } from '../adapters/adapter.js';
11
+ import { ANSI_STYLE, gathered, Refusal, } from '../adapters/adapter.js';
12
12
  import { freezeDerivedCatalog, isCapturedScopeCatalog, isFixedScopeCatalog } from '../shared/scopeCatalog.js';
13
13
  import { compileView, resolveAggregate, tryResolvePath } from '../shared/view.js';
14
14
  import { rollupReads } from '../shared/rollups.js';
@@ -669,6 +669,41 @@ export function authorizeColumnWrites(full, grant, writer, rules) {
669
669
  const product = rules?.(checks);
670
670
  // Keep each call's rules stable across its awaits; the next call reads current grants.
671
671
  const capture = (current) => (product ? product.capture(current) : captureGrant(current));
672
+ const insertVia = (input, write) => {
673
+ const server = isServerRequest(input);
674
+ const request = jsonWritten(full, requestData(input));
675
+ const operation = capture(grant);
676
+ assertWrite(request.table);
677
+ if (operation.creatable && !operation.creatable.has(request.table))
678
+ throw new AppAccessDenied();
679
+ recordFields(request.table, request.values, 'write', server);
680
+ const written = product?.insert ? product.insert(request, operation, server, write) : (async () => write(request))();
681
+ return written.then((result) => {
682
+ const readable = operation.fields?.get(request.table)?.read;
683
+ if (!readable || !result.row)
684
+ return result;
685
+ return { ...result, row: Object.fromEntries(Object.entries(result.row).filter(([column]) => readable.has(column))) };
686
+ });
687
+ };
688
+ const updateVia = (input, write) => {
689
+ const request = jsonWritten(full, requestData(input));
690
+ const operation = capture(grant);
691
+ if (!operation.writable.has(request.table)) {
692
+ const answered = product?.unwritable?.(request, operation, write);
693
+ if (answered)
694
+ return answered;
695
+ }
696
+ assertWrite(request.table);
697
+ recordFields(request.table, request.values, 'write', isServerRequest(input));
698
+ keyFields(request.table, request.key);
699
+ if (request.expected !== undefined) {
700
+ recordFields(request.table, request.expected, 'read');
701
+ if (!expectedCovers(full, request))
702
+ throw new AppAccessDenied();
703
+ }
704
+ assertRelatedWrites(request.table, Object.keys(request.values));
705
+ return product?.update ? product.update(request, operation, write) : (async () => write(request))();
706
+ };
672
707
  return {
673
708
  ...(writer.lockRecord
674
709
  ? {
@@ -697,41 +732,15 @@ export function authorizeColumnWrites(full, grant, writer, rules) {
697
732
  query: (request) => writer.query(queryFor(request)),
698
733
  count: (table, filter) => writer.count(table, filterFor(table, filter)),
699
734
  ...(writer.aggregate ? { aggregate: (request) => writer.aggregate(aggregateFor(request)) } : {}),
700
- insert: (input) => {
701
- const server = isServerRequest(input);
702
- const request = jsonWritten(full, requestData(input));
703
- const operation = capture(grant);
704
- assertWrite(request.table);
705
- if (operation.creatable && !operation.creatable.has(request.table))
706
- throw new AppAccessDenied();
707
- recordFields(request.table, request.values, 'write', server);
708
- const written = product?.insert ? product.insert(request, operation, server) : (async () => writer.insert(request))();
709
- return written.then((result) => {
710
- const readable = operation.fields?.get(request.table)?.read;
711
- if (!readable || !result.row)
712
- return result;
713
- return { ...result, row: Object.fromEntries(Object.entries(result.row).filter(([column]) => readable.has(column))) };
714
- });
715
- },
716
- update: (input) => {
717
- const request = jsonWritten(full, requestData(input));
718
- const operation = capture(grant);
719
- if (!operation.writable.has(request.table)) {
720
- const answered = product?.unwritable?.(request, operation);
721
- if (answered)
722
- return answered;
723
- }
724
- assertWrite(request.table);
725
- recordFields(request.table, request.values, 'write', isServerRequest(input));
726
- keyFields(request.table, request.key);
727
- if (request.expected !== undefined) {
728
- recordFields(request.table, request.expected, 'read');
729
- if (!expectedCovers(full, request))
730
- throw new AppAccessDenied();
731
- }
732
- assertRelatedWrites(request.table, Object.keys(request.values));
733
- return product?.update ? product.update(request, operation) : (async () => writer.update(request))();
734
- },
735
+ insert: (input) => insertVia(input, (request) => writer.insert(request)),
736
+ update: (input) => updateVia(input, (request) => writer.update(request)),
737
+ // A batch: each row through the same checks, its write one row of one statement.
738
+ ...(writer.insertMany
739
+ ? { insertMany: (inputs) => gathered(inputs, insertVia, (requests) => writer.insertMany(requests)) }
740
+ : {}),
741
+ ...(writer.updateMany
742
+ ? { updateMany: (inputs) => gathered(inputs, updateVia, (requests) => writer.updateMany(requests)) }
743
+ : {}),
735
744
  remove: (input) => {
736
745
  const request = requestData(input);
737
746
  assertWrite(request.table);
@@ -1 +1,60 @@
1
+ /**
2
+ * App logic's clock: what a command's `now()`, a loader, a dashboard's "last 30 days", a job's due check and a
3
+ * stamp an action writes read. The real time, unless
4
+ *
5
+ * - a test has pinned it: MISTRI_CLOCK holds an instant the browser suite fixes so that "last 90 days" over a
6
+ * database seeded for a known day reads the same on every run, and a stamp an action writes ('now') is the same
7
+ * instant on every run. Never set in use.
8
+ * - a development or test process was started as of another moment (`mistri dev --as-of 2026-01-05`, or
9
+ * MISTRI_AS_OF): the clock then reads that moment at start and moves on in real time from it, so seed data dated
10
+ * for one day reads as it was written on every later one. A field report: moving the machine's clock instead
11
+ * broke sign-in, and moving the browser's paused a tenant's access.
12
+ *
13
+ * Only App logic reads it. Sign-in, sessions, one-time codes, tokens and their expiry, rate limits, the read audit,
14
+ * receipts and history, caches and the job scheduler's own timers keep the real clock, so an as-of moment never
15
+ * expires a session or holds a lease past its time.
16
+ */
17
+ import { appClockOffset } from '../../shared/appClock.js';
18
+ /**
19
+ * The pin wins over an as-of moment: a browser suite that pins the clock asks for the same instant on every run, and
20
+ * an offset from the real time would undo that.
21
+ */
1
22
  export declare function clockNow(): Date;
23
+ /**
24
+ * A real instant as App logic reads it: moved by the as-of offset. For code handed a real clock (a tenant
25
+ * deployment's, a job host's) and for a default that read `new Date()`; it never applies the MISTRI_CLOCK pin, so
26
+ * what read the real time under the browser suite still does.
27
+ */
28
+ export declare function appTime(real?: number | Date): Date;
29
+ /** The as-of offset in milliseconds, 0 for the real clock: what an App's chrome carries to the browser. */
30
+ export { appClockOffset };
31
+ /**
32
+ * The moment an as-of value names, or undefined when it names none. A date alone (2026-01-05) is midnight in
33
+ * `zone` (the caller passes the App's declared zone, else the server's own; UTC when none is given at all);
34
+ * a date and time without an offset (2026-01-05T09:30) is that wall clock in the same zone; one with an offset
35
+ * (…Z, …-05:00) is that instant.
36
+ */
37
+ export declare function parseAsOf(given: string, zone?: string): Date | undefined;
38
+ interface AsOfProcess {
39
+ /** The process is `mistri dev` (`--dev`). */
40
+ readonly dev: boolean;
41
+ /** The process serves a build, which is what is deployed. */
42
+ readonly build?: boolean;
43
+ /**
44
+ * The App's declared zone, which a date alone is midnight in. Undefined (the Apps name none, or differ) is the
45
+ * server's own zone: it is the one a query's `today` is counted in for an App that names none (zonedNow), so
46
+ * `--as-of 2026-01-05` on a laptop in Chicago reads the 5th as today, not the 4th.
47
+ */
48
+ readonly zone?: string;
49
+ readonly env?: NodeJS.ProcessEnv;
50
+ /** The real time to count the offset from; the real clock's when absent. */
51
+ readonly now?: number;
52
+ }
53
+ /**
54
+ * Read the as-of moment the flag or MISTRI_AS_OF asks for (the flag wins), and set App logic's clock to start at
55
+ * it. Development and tests only: refused, with a message naming what asked, under NODE_ENV=production, when
56
+ * serving a build, and in any process that is neither `mistri dev` nor NODE_ENV=test — never ignored, since a
57
+ * server quietly running on another day's clock is worse than one that will not start. Returns the moment, or
58
+ * undefined when nothing asked for one.
59
+ */
60
+ export declare function configureAsOf(flag: string | undefined, asked: AsOfProcess): Date | undefined;