@mistriwork/engine 1.0.0-rc.16 → 1.0.0-rc.17

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.
@@ -16,11 +16,13 @@
16
16
  *
17
17
  * Three things it deliberately does not do.
18
18
  *
19
- * It is **not persisted**. The browser's undo stack makes this argument and it
20
- * is the right one: a stack that outlives the process invites undoing
21
- * something from an hour ago, by which time the row has very likely moved on
22
- * and the "undo" is an overwrite wearing a friendly name. In-session is the
23
- * honest scope.
19
+ * It is **kept in memory unless the database holds its store**. A stack that
20
+ * outlives the process invites undoing something from an hour ago, by which
21
+ * time the row has very likely moved on and the "undo" is an overwrite
22
+ * wearing a friendly name. Where the store is provisioned (journalStore.ts)
23
+ * the history survives a restart all the same, bounded by depth and a week,
24
+ * and the check below is what keeps an old Undo honest; where it is not, the
25
+ * journal is this process's alone, as it always was.
24
26
  *
25
27
  * It **checks before it writes**. Putting the old value back over a newer one
26
28
  * is not an undo, it is a silent overwrite — so the row is re-read first and
@@ -45,6 +47,60 @@ const entriesFor = (connection) => {
45
47
  journals.set(connection, []);
46
48
  return journals.get(connection);
47
49
  };
50
+ const kept = new Map();
51
+ function persist(connection, work) {
52
+ const at = kept.get(connection);
53
+ if (!at)
54
+ return;
55
+ at.chain = at.chain
56
+ .then(() => work(at.store))
57
+ .catch((error) => at.warn(`"${connection}": the write journal store refused a change: ${error.message}`));
58
+ }
59
+ /**
60
+ * Keep `connection`'s journal in `store` from now on. The first time, what the
61
+ * store holds becomes the history: an Undo the last process left in progress
62
+ * reads as uncertain, since nothing says whether it landed. Again (a
63
+ * reconnect), the store is swapped and memory, already kept, stays.
64
+ */
65
+ export async function attachJournalStore(connection, store, warn = (message) => console.error(message)) {
66
+ const current = kept.get(connection);
67
+ if (current) {
68
+ await current.chain;
69
+ current.store = store;
70
+ current.warn = warn;
71
+ return;
72
+ }
73
+ const loaded = await store.load(connection);
74
+ const ids = new Set(loaded.map((entry) => entry.id));
75
+ const unkept = entriesFor(connection).filter((entry) => !ids.has(entry.id));
76
+ const list = [...loaded, ...unkept].sort((a, b) => a.id - b.id).slice(-DEPTH);
77
+ journals.set(connection, list);
78
+ for (const entry of list)
79
+ nextId = Math.max(nextId, entry.id + 1);
80
+ kept.set(connection, { store, chain: Promise.resolve(), warn });
81
+ for (const entry of loaded) {
82
+ if (entry.undoState !== 'pending')
83
+ continue;
84
+ Object.assign(entry, { undoState: 'unknown', revertible: false, reason: undoUncertain });
85
+ persist(connection, (each) => each.update(entry));
86
+ }
87
+ for (const entry of unkept)
88
+ persist(connection, (each) => each.append(entry));
89
+ await flushJournal(connection);
90
+ }
91
+ /** Every change written behind so far, landed or refused: before a reply that reports one, and before a close. */
92
+ export async function flushJournal(connection) {
93
+ const chains = connection === undefined ? [...kept.values()] : kept.has(connection) ? [kept.get(connection)] : [];
94
+ for (const at of chains) {
95
+ let seen;
96
+ while (seen !== at.chain)
97
+ await (seen = at.chain);
98
+ }
99
+ }
100
+ /** Whether `connection`'s journal is kept in its database. */
101
+ export function journalKept(connection) {
102
+ return kept.has(connection);
103
+ }
48
104
  /** Record a write that landed. Returns the entry, mostly for tests. */
49
105
  export function recordWrite(connection, entry) {
50
106
  const full = {
@@ -57,6 +113,7 @@ export function recordWrite(connection, entry) {
57
113
  list.push(full);
58
114
  if (list.length > DEPTH)
59
115
  list.shift();
116
+ persist(connection, (store) => store.append(full));
60
117
  return full;
61
118
  }
62
119
  /** The most recent first, which is the order anyone asks about them in. */
@@ -82,13 +139,19 @@ export function forget(connection, id) {
82
139
  const at = list.findIndex((e) => e.id === id);
83
140
  if (at !== -1)
84
141
  list.splice(at, 1);
142
+ persist(connection, (store) => store.remove(connection, id));
85
143
  }
86
- /** Testing seam: a fresh process is the normal state, and tests want it too. */
144
+ /** Testing seam: a fresh process is the normal state, and tests want it too.
145
+ * What a store keeps is left there, as a process that ended leaves it. */
87
146
  export function clearJournal(connection) {
88
- if (connection === undefined)
147
+ if (connection === undefined) {
89
148
  journals.clear();
90
- else
149
+ kept.clear();
150
+ }
151
+ else {
91
152
  journals.delete(connection);
153
+ kept.delete(connection);
154
+ }
92
155
  }
93
156
  /** Fail closed without publishing another entry (or consulting a clock). The
94
157
  * caller supplies already verified ownership; no record values are introduced. */
@@ -99,6 +162,7 @@ export function quarantineHistory(connection, owner) {
99
162
  entry.revertible = false;
100
163
  entry.undoState = 'unknown';
101
164
  entry.reason = 'Newer write history could not be confirmed. Refresh and reconcile before further editing.';
165
+ persist(connection, (store) => store.update(entry));
102
166
  }
103
167
  }
104
168
  const keyFilter = (key) => ({
@@ -171,6 +235,9 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
171
235
  return { reverted: false, outcome: 'not_applied', entry, errors: [errorMessage(error)] };
172
236
  }
173
237
  canonical.undoState = 'pending';
238
+ // Kept before the inverse runs: a process that stops mid-Undo leaves it uncertain, never offered again as if untried.
239
+ persist(connection, (store) => store.update(canonical));
240
+ await flushJournal(connection);
174
241
  try {
175
242
  const result = await revertOwned(adapter, connection, owned, errorMessage);
176
243
  if (result.outcome === 'unknown') {
@@ -189,6 +256,10 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
189
256
  finally {
190
257
  if (canonical.undoState === 'pending')
191
258
  delete canonical.undoState;
259
+ // An applied Undo was forgotten (revertOwned); anything else says its state again.
260
+ if (entriesFor(connection).includes(canonical))
261
+ persist(connection, (store) => store.update(canonical));
262
+ await flushJournal(connection);
192
263
  }
193
264
  }
194
265
  const undoUncertain = 'The Undo outcome could not be confirmed. Refresh and reconcile the records; do not retry this Undo.';
@@ -0,0 +1,37 @@
1
+ import { DatabaseSync } from 'node:sqlite';
2
+ import { type Adapter } from '../adapters/adapter.js';
3
+ import type { PgQuery } from '../adapters/postgresPool.js';
4
+ declare const WRITE_JOURNAL_VERSION = 1;
5
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
6
+ export declare const WRITE_JOURNAL_RETENTION: Readonly<{
7
+ entries: 50;
8
+ days: 7;
9
+ bytes: number;
10
+ }>;
11
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
12
+ export declare function sqliteWriteJournalReady(db: DatabaseSync): boolean;
13
+ /**
14
+ * Explicit maintenance, never run when a connection opens: a file without the
15
+ * store gets this version; the same layout again changes nothing; anything
16
+ * else under the prefix is refused unchanged.
17
+ */
18
+ export declare function provisionSqliteWriteJournal(existingPath: string): {
19
+ version: typeof WRITE_JOURNAL_VERSION;
20
+ provisioned: boolean;
21
+ };
22
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
23
+ export declare function postgresWriteJournalReady(client: PgQuery): Promise<boolean>;
24
+ /** Explicit maintenance, under the shared migration lock: creates this version
25
+ * where no store exists, changes nothing where it does, refuses anything else. */
26
+ export declare function provisionPostgresWriteJournal(url: string): Promise<{
27
+ version: typeof WRITE_JOURNAL_VERSION;
28
+ provisioned: boolean;
29
+ }>;
30
+ /**
31
+ * Keep `connection`'s journal in its database when the database holds the
32
+ * store: what it held is read back, and every write from here on is kept
33
+ * there too. Never fatal: a store that cannot be read leaves the journal in
34
+ * memory, said through `warn`. Resolves to whether the store is now used.
35
+ */
36
+ export declare function keepWriteJournal(connection: string, adapter: Adapter, warn?: (message: string) => void): Promise<boolean>;
37
+ export {};
@@ -0,0 +1,352 @@
1
+ /**
2
+ * The write journal's store: where a connection's Undo history is kept when
3
+ * the database holds it, so a restart does not forget the writes it could
4
+ * still put back (journal.ts).
5
+ *
6
+ * The store is opt-in, like every reserved store: provisioned by an explicit
7
+ * step (`mistri migrate stores`, `provisionStores({ only: ['undo-journal'] })`,
8
+ * or the provisioning functions here for a host that has no App framework),
9
+ * never by opening a connection. A writable connection whose database holds
10
+ * this build's layout keeps its journal there; one that holds none keeps it in
11
+ * memory, as before, and one that holds another layout keeps it in memory and
12
+ * says why once.
13
+ *
14
+ * It sits in the business database, beside the rows it describes, under the
15
+ * reserved prefix: the catalog never lists it, and a copy of the database
16
+ * carries the history that belongs to it. What is kept is what memory holds —
17
+ * the entry the hidden-column wrapper already stripped — so a hidden value is
18
+ * no more in the store than it was in the journal.
19
+ *
20
+ * Retention is the journal's own depth (the newest `entries` per connection)
21
+ * and an age (`days`): an Undo a week later is an overwrite more often than
22
+ * not, and the revert's check-before-write is the only thing that would stop
23
+ * it. An entry too large to keep is kept as a barrier instead, which is what
24
+ * it is after a restart: a write whose inverse is gone, so no older Undo is
25
+ * offered past it.
26
+ */
27
+ import { statSync } from 'node:fs';
28
+ import { DatabaseSync } from 'node:sqlite';
29
+ import { Refusal } from '../adapters/adapter.js';
30
+ import { layoutRefusal, postgresLayoutVersion, sqliteLayoutVersion } from '../adapters/layoutRefusal.js';
31
+ import { withPostgresMaintenanceTransaction } from '../adapters/postgresMaintenance.js';
32
+ import { storeHostOf, writeViewOf } from '../adapters/storeHost.js';
33
+ import { runtimeName, runtimeSchema, runtimeTable } from '../shared/runtimeTables.js';
34
+ import { attachJournalStore } from './journal.js';
35
+ const WRITE_JOURNAL_VERSION = 1;
36
+ /** The reserved prefix of its tables (`mistri.undo_*` on PostgreSQL). */
37
+ const WRITE_JOURNAL_PREFIX = '__mistri_undo_';
38
+ const META = '__mistri_undo_meta';
39
+ const ENTRY = '__mistri_undo_entry';
40
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
41
+ export const WRITE_JOURNAL_RETENTION = Object.freeze({ entries: 50, days: 7, bytes: 4 * 1024 * 1024 });
42
+ const DAY_MS = 86_400_000;
43
+ /** Why the store cannot be used: an unprovisioned database is not this; a layout that is not this build's is. */
44
+ class WriteJournalUnavailable extends Refusal {
45
+ constructor(message = 'The write journal store is missing or is not the layout this version expects.') {
46
+ super(message);
47
+ this.name = 'WriteJournalUnavailable';
48
+ }
49
+ }
50
+ /* ---------- SQLite ---------- */
51
+ const sqliteDefinitions = new Map([
52
+ [
53
+ META,
54
+ `CREATE TABLE "${META}" (
55
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
56
+ version INTEGER NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
57
+ )`,
58
+ ],
59
+ [
60
+ ENTRY,
61
+ `CREATE TABLE "${ENTRY}" (
62
+ connection TEXT COLLATE BINARY NOT NULL,
63
+ id INTEGER NOT NULL,
64
+ at INTEGER NOT NULL,
65
+ entry_json TEXT NOT NULL CHECK (json_valid(entry_json)),
66
+ PRIMARY KEY (connection, id)
67
+ )`,
68
+ ],
69
+ ]);
70
+ const underPrefix = `substr(name, 1, ?) = ? COLLATE NOCASE OR substr(tbl_name, 1, ?) = ? COLLATE NOCASE`;
71
+ const prefixArgs = [WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX, WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX];
72
+ const sqliteCatalog = (db) => db
73
+ .prepare(`SELECT type, name, tbl_name, sql FROM main.sqlite_schema WHERE ${underPrefix}`)
74
+ .all(...prefixArgs);
75
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
76
+ export function sqliteWriteJournalReady(db) {
77
+ try {
78
+ if (db.prepare(`SELECT 1 FROM temp.sqlite_schema WHERE ${underPrefix} LIMIT 1`).get(...prefixArgs))
79
+ return false;
80
+ const entries = sqliteCatalog(db);
81
+ const tables = entries.filter((entry) => entry.type === 'table');
82
+ if (tables.length !== sqliteDefinitions.size ||
83
+ tables.some((entry) => sqliteDefinitions.get(entry.name) !== entry.sql) ||
84
+ entries.some((entry) => entry.type !== 'table' && !(entry.type === 'index' && entry.sql === null && sqliteDefinitions.has(entry.tbl_name))))
85
+ return false;
86
+ const rows = db.prepare(`SELECT singleton, version FROM main."${META}"`).all();
87
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
88
+ }
89
+ catch {
90
+ return false;
91
+ }
92
+ }
93
+ const inMain = (ddl) => ddl.replace('CREATE TABLE ', 'CREATE TABLE main.');
94
+ /**
95
+ * Explicit maintenance, never run when a connection opens: a file without the
96
+ * store gets this version; the same layout again changes nothing; anything
97
+ * else under the prefix is refused unchanged.
98
+ */
99
+ export function provisionSqliteWriteJournal(existingPath) {
100
+ if (!statSync(existingPath).isFile())
101
+ throw new Refusal('Write journal provisioning requires an existing SQLite file.');
102
+ const db = new DatabaseSync(existingPath);
103
+ try {
104
+ db.exec('PRAGMA busy_timeout = 5000');
105
+ db.exec('BEGIN IMMEDIATE');
106
+ try {
107
+ let provisioned = false;
108
+ if (sqliteCatalog(db).length === 0) {
109
+ for (const ddl of sqliteDefinitions.values())
110
+ db.exec(inMain(ddl));
111
+ db.prepare(`INSERT INTO main."${META}" (singleton, version) VALUES (1, ?)`).run(WRITE_JOURNAL_VERSION);
112
+ provisioned = true;
113
+ }
114
+ if (!sqliteWriteJournalReady(db))
115
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
116
+ db.exec('COMMIT');
117
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
118
+ }
119
+ catch (error) {
120
+ try {
121
+ db.exec('ROLLBACK');
122
+ }
123
+ catch {
124
+ /* Preserve the provisioning failure. */
125
+ }
126
+ throw error;
127
+ }
128
+ }
129
+ finally {
130
+ db.close();
131
+ }
132
+ }
133
+ /* ---------- PostgreSQL ---------- */
134
+ const pgMeta = runtimeTable('postgres', META);
135
+ const pgEntry = runtimeTable('postgres', ENTRY);
136
+ const pgPrefix = runtimeName('postgres', WRITE_JOURNAL_PREFIX.slice(0, -1)) + '_';
137
+ const pgDefinitions = [
138
+ `CREATE TABLE ${pgMeta} (
139
+ singleton integer PRIMARY KEY CHECK (singleton = 1),
140
+ version integer NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
141
+ )`,
142
+ `CREATE TABLE ${pgEntry} (
143
+ connection text COLLATE "C" NOT NULL,
144
+ id bigint NOT NULL,
145
+ at bigint NOT NULL,
146
+ entry jsonb NOT NULL,
147
+ PRIMARY KEY (connection, id)
148
+ )`,
149
+ ];
150
+ /* What the DDL above reads back as, pinned so the attestation is of this layout and not of whatever is there. */
151
+ const PG_LAYOUT = JSON.stringify([
152
+ {
153
+ name: runtimeName('postgres', ENTRY),
154
+ kind: 'r',
155
+ columns: ['connection text C t', 'id bigint - t', 'at bigint - t', 'entry jsonb - t'],
156
+ constraints: ['PRIMARY KEY (connection, id)'],
157
+ },
158
+ {
159
+ name: `${runtimeName('postgres', ENTRY)}_pkey`,
160
+ kind: 'i',
161
+ columns: ['connection text C f', 'id bigint - f'],
162
+ constraints: [],
163
+ },
164
+ {
165
+ name: runtimeName('postgres', META),
166
+ kind: 'r',
167
+ columns: ['singleton integer - t', 'version integer - t'],
168
+ constraints: ['CHECK ((singleton = 1))', `CHECK ((version = ${WRITE_JOURNAL_VERSION}))`, 'PRIMARY KEY (singleton)'],
169
+ },
170
+ {
171
+ name: `${runtimeName('postgres', META)}_pkey`,
172
+ kind: 'i',
173
+ columns: ['singleton integer - f'],
174
+ constraints: [],
175
+ },
176
+ ]);
177
+ /** Every relation under the prefix in the runtime schema, with its columns and constraints, in a fixed order; triggers, rules and row security disqualify it. */
178
+ async function pgRelations(client) {
179
+ const rows = (await client.query(`SELECT c.relname AS name, c.relkind::text AS kind,
180
+ c.relrowsecurity OR c.relhastriggers OR c.relhasrules AS guarded,
181
+ coalesce((SELECT json_agg(a.attname || ' ' || format_type(a.atttypid, a.atttypmod) || ' ' ||
182
+ coalesce((SELECT co.collname FROM pg_collation co WHERE co.oid = a.attcollation AND a.attcollation <> 0
183
+ AND a.attcollation <> (SELECT t.typcollation FROM pg_type t WHERE t.oid = a.atttypid)), '-') || ' ' ||
184
+ CASE WHEN a.attnotnull THEN 't' ELSE 'f' END ORDER BY a.attnum)
185
+ FROM pg_attribute a WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped), '[]') AS columns,
186
+ coalesce((SELECT json_agg(pg_get_constraintdef(k.oid) ORDER BY pg_get_constraintdef(k.oid) COLLATE "C")
187
+ FROM pg_constraint k WHERE k.conrelid = c.oid), '[]') AS constraints,
188
+ (SELECT count(*) FROM pg_attrdef d WHERE d.adrelid = c.oid)::int AS defaults
189
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
190
+ WHERE n.nspname = $1 AND substr(c.relname, 1, $2) = $3
191
+ ORDER BY c.relname COLLATE "C"`, [runtimeSchema('postgres'), pgPrefix.length, pgPrefix])).rows;
192
+ if (rows.some((row) => row.guarded || row.defaults))
193
+ return { text: '', count: rows.length };
194
+ return {
195
+ text: JSON.stringify(rows.map(({ name, kind, columns, constraints }) => ({ name, kind, columns, constraints }))),
196
+ count: rows.length,
197
+ };
198
+ }
199
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
200
+ export async function postgresWriteJournalReady(client) {
201
+ try {
202
+ if ((await pgRelations(client)).text !== PG_LAYOUT)
203
+ return false;
204
+ const rows = (await client.query(`SELECT singleton, version FROM ${pgMeta}`)).rows;
205
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
206
+ }
207
+ catch {
208
+ return false;
209
+ }
210
+ }
211
+ /** Explicit maintenance, under the shared migration lock: creates this version
212
+ * where no store exists, changes nothing where it does, refuses anything else. */
213
+ export async function provisionPostgresWriteJournal(url) {
214
+ if (typeof url !== 'string' || !/^postgres(ql)?:\/\//i.test(url))
215
+ throw new Refusal('Write journal provisioning requires a postgres:// URL.');
216
+ return withPostgresMaintenanceTransaction(url, async (client) => {
217
+ let provisioned = false;
218
+ if (!(await pgRelations(client)).count) {
219
+ for (const ddl of pgDefinitions)
220
+ await client.query(ddl);
221
+ await client.query(`INSERT INTO ${pgMeta} (singleton, version) VALUES (1, $1)`, [WRITE_JOURNAL_VERSION]);
222
+ provisioned = true;
223
+ }
224
+ if (!(await postgresWriteJournalReady(client)))
225
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
226
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
227
+ });
228
+ }
229
+ /* ---------- what is kept ---------- */
230
+ /** The stored form: the entry without the columns that say where and when it is. */
231
+ function stored(entry) {
232
+ const { id: _id, connection: _connection, at: _at, ...rest } = entry;
233
+ const json = JSON.stringify(rest);
234
+ if (Buffer.byteLength(json) <= WRITE_JOURNAL_RETENTION.bytes)
235
+ return json;
236
+ // Kept as what it is after a restart: a write with no inverse left, which blocks every older Undo.
237
+ const { steps, ...plain } = rest;
238
+ return JSON.stringify({
239
+ ...plain,
240
+ revertible: false,
241
+ blocksUndo: true,
242
+ reason: 'This write was too large to keep its Undo across a restart.',
243
+ steps: steps.length ? [{ table: steps[0].table }] : [],
244
+ });
245
+ }
246
+ function revived(connection, id, at, json) {
247
+ const body = (typeof json === 'string' ? JSON.parse(json) : json);
248
+ return { ...body, id: Number(id), connection, at: new Date(Number(at)).toISOString() };
249
+ }
250
+ const atOf = (entry) => {
251
+ const at = Date.parse(entry.at);
252
+ return Number.isFinite(at) ? at : Date.now();
253
+ };
254
+ const oldest = () => Date.now() - WRITE_JOURNAL_RETENTION.days * DAY_MS;
255
+ function sqliteStore(host) {
256
+ const prune = (db, connection) => db
257
+ .prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND (at < ? OR id NOT IN
258
+ (SELECT id FROM main."${ENTRY}" WHERE connection = ? ORDER BY id DESC LIMIT ?))`)
259
+ .run(connection, oldest(), connection, WRITE_JOURNAL_RETENTION.entries);
260
+ return {
261
+ load: (connection) => host.queueWrite((db) => {
262
+ prune(db, connection);
263
+ return db.prepare(`SELECT id, at, entry_json FROM main."${ENTRY}" WHERE connection = ? ORDER BY id`).all(connection).map((row) => revived(connection, row.id, row.at, row.entry_json));
264
+ }),
265
+ append: (entry) => host.queueWrite((db) => {
266
+ db.prepare(`INSERT INTO main."${ENTRY}" (connection, id, at, entry_json) VALUES (?, ?, ?, ?)`).run(entry.connection, entry.id, atOf(entry), stored(entry));
267
+ prune(db, entry.connection);
268
+ }),
269
+ update: (entry) => host.queueWrite((db) => {
270
+ db.prepare(`UPDATE main."${ENTRY}" SET entry_json = ? WHERE connection = ? AND id = ?`).run(stored(entry), entry.connection, entry.id);
271
+ }),
272
+ remove: (connection, id) => host.queueWrite((db) => {
273
+ db.prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND id = ?`).run(connection, id);
274
+ }),
275
+ };
276
+ }
277
+ function postgresStore(host) {
278
+ const prune = (client, connection) => client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND (at < $2 OR id NOT IN
279
+ (SELECT id FROM ${pgEntry} WHERE connection = $1 ORDER BY id DESC LIMIT $3))`, [connection, oldest(), WRITE_JOURNAL_RETENTION.entries]);
280
+ return {
281
+ load: (connection) => host.withWriteClient(async (client) => {
282
+ await prune(client, connection);
283
+ const rows = (await client.query(`SELECT id, at, entry FROM ${pgEntry} WHERE connection = $1 ORDER BY id`, [connection]))
284
+ .rows;
285
+ return rows.map((row) => revived(connection, row.id, row.at, row.entry));
286
+ }),
287
+ append: (entry) => host.withWriteClient(async (client) => {
288
+ await client.query(`INSERT INTO ${pgEntry} (connection, id, at, entry) VALUES ($1, $2, $3, $4::jsonb)`, [
289
+ entry.connection,
290
+ entry.id,
291
+ atOf(entry),
292
+ stored(entry),
293
+ ]);
294
+ await prune(client, entry.connection);
295
+ }),
296
+ update: (entry) => host.withWriteClient(async (client) => {
297
+ await client.query(`UPDATE ${pgEntry} SET entry = $1::jsonb WHERE connection = $2 AND id = $3`, [
298
+ stored(entry),
299
+ entry.connection,
300
+ entry.id,
301
+ ]);
302
+ }),
303
+ remove: (connection, id) => host.withWriteClient(async (client) => {
304
+ await client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND id = $2`, [connection, id]);
305
+ }),
306
+ };
307
+ }
308
+ /**
309
+ * The store an adapter's database holds, or undefined where it holds none of
310
+ * it (the journal then stays in memory). An adapter a wrapper narrowed is
311
+ * looked through to the one it wraps. Throws WriteJournalUnavailable for a
312
+ * layout that is not this build's.
313
+ */
314
+ async function writeJournalStoreOf(adapter) {
315
+ const host = storeHostOf(adapter) ?? storeHostOf(writeViewOf(adapter)?.over);
316
+ if (!host)
317
+ return undefined;
318
+ if (host.dialect === 'sqlite') {
319
+ const db = host.reader();
320
+ if (!sqliteCatalog(db).length)
321
+ return undefined;
322
+ if (!sqliteWriteJournalReady(db))
323
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
324
+ return sqliteStore(host);
325
+ }
326
+ return host.withReadClient(async (client) => {
327
+ if (!(await pgRelations(client)).count)
328
+ return undefined;
329
+ if (!(await postgresWriteJournalReady(client)))
330
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
331
+ return postgresStore(host);
332
+ });
333
+ }
334
+ /**
335
+ * Keep `connection`'s journal in its database when the database holds the
336
+ * store: what it held is read back, and every write from here on is kept
337
+ * there too. Never fatal: a store that cannot be read leaves the journal in
338
+ * memory, said through `warn`. Resolves to whether the store is now used.
339
+ */
340
+ export async function keepWriteJournal(connection, adapter, warn = (message) => console.error(message)) {
341
+ try {
342
+ const store = await writeJournalStoreOf(adapter);
343
+ if (!store)
344
+ return false;
345
+ await attachJournalStore(connection, store, warn);
346
+ return true;
347
+ }
348
+ catch (error) {
349
+ warn(`"${connection}": Undo history is kept in memory for this run: ${error.message}`);
350
+ return false;
351
+ }
352
+ }
@@ -1,3 +1,10 @@
1
1
  import type { AppListPresentation } from './listPresentations.js';
2
+ /**
3
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
4
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
5
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
6
+ * so where a subtitled column stands there (`subtitle-unseen`).
7
+ */
8
+ export declare function listSecondLineColumns(list: AppListPresentation): string[];
2
9
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
3
10
  export declare function listPresentationColumns(list: AppListPresentation): string[];
@@ -6,6 +6,19 @@
6
6
  * homes it installs at load — into the first script it downloads.
7
7
  */
8
8
  import { cardsColumns } from './appCards.js';
9
+ /**
10
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
11
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
12
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
13
+ * so where a subtitled column stands there (`subtitle-unseen`).
14
+ */
15
+ export function listSecondLineColumns(list) {
16
+ if (list.kind === 'cards')
17
+ return [...new Set([list.primary, ...(list.value ? [list.value] : []), ...(list.lines ?? [])])];
18
+ if (list.kind === 'board')
19
+ return [list.primary];
20
+ return [];
21
+ }
9
22
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
10
23
  export function listPresentationColumns(list) {
11
24
  if (list.kind === 'split') {
@@ -13,7 +13,7 @@
13
13
  */
14
14
  import { andQuery } from './query.js';
15
15
  import { splitQuery } from './clauses.js';
16
- import { listPresentationColumns } from './appListColumns.js';
16
+ import { listPresentationColumns, listSecondLineColumns } from './appListColumns.js';
17
17
  import { findTable, labelPath, primaryKey } from './schema.js';
18
18
  import { referenceProjection } from './referenceModel.js';
19
19
  import { tableAtPrefix } from './viewPaths.js';
@@ -109,7 +109,7 @@ export function showClause(rules, spec) {
109
109
  ...(naming ? [naming] : []),
110
110
  ...named,
111
111
  ...(spec.order ? [spec.order] : []),
112
- ...subtitleColumns(rules, spec.table, names),
112
+ ...subtitleColumns(rules, spec.table, [...names, ...(spec.presentation ? listSecondLineColumns(spec.presentation) : [])]),
113
113
  ...editedReferences(rules, spec),
114
114
  ...(spec.opens ? [spec.opens] : []),
115
115
  ...(spec.group ? [spec.group] : []),
@@ -28,6 +28,7 @@
28
28
  * (pageFieldsRead.ts).
29
29
  */
30
30
  import { subtitlePath } from './subtitlePath.js';
31
+ import { listSecondLineColumns } from './appListColumns.js';
31
32
  import { findTable, labelPath, primaryKey } from './schema.js';
32
33
  import { DEFAULT_HISTORY_LIMIT, kindReading } from './pageModel.js';
33
34
  import { assertNever } from './model.js';
@@ -74,6 +75,21 @@ export function defaultFieldPaths(base, app) {
74
75
  const read = base.columns.filter((c) => !app || !(surrogate(c) || version(c))).map((c) => c.name);
75
76
  return read.length ? read : base.columns.map((c) => c.name);
76
77
  }
78
+ /**
79
+ * The second lines of the columns at `paths`: a column whose rule has a `subtitle` is drawn with it wherever it is a
80
+ * field, a header's fact or a card's title, so the record reads it too (the same rule a list's cell reads,
81
+ * listQuestion.ts subtitleColumns). A path through a reference reads it from the table it reaches.
82
+ */
83
+ function secondLines(names, base, paths) {
84
+ if (!names.display)
85
+ return [];
86
+ return paths.flatMap((path) => {
87
+ const hop = path.lastIndexOf('.');
88
+ const owner = hop < 0 ? base.id : tableAtPrefix(names.schema, base.id, path.slice(0, hop))?.id;
89
+ const second = owner ? subtitlePath(names.display(owner, path.slice(hop + 1)), path) : undefined;
90
+ return second ? [second] : [];
91
+ });
92
+ }
77
93
  /** A fields section's columns: what it shows, the names of what it references, the record's name, and its workflow's field. */
78
94
  export function fieldsColumns(names, base, section) {
79
95
  const paths = section.paths?.length ? [...section.paths] : defaultFieldPaths(base, names.app);
@@ -91,16 +107,7 @@ export function fieldsColumns(names, base, section) {
91
107
  ]),
92
108
  ].filter((path) => !paths.includes(path))
93
109
  : [];
94
- /* A column whose rule has a `subtitle` is drawn with it wherever it is a field, so the record reads it too
95
- (the same rule a list's cell reads, listQuestion.ts subtitleColumns). */
96
- const seconds = names.display
97
- ? [...new Set([...paths, ...(section.presentation === 'headline' ? extra : [])])].flatMap((path) => {
98
- const hop = path.lastIndexOf('.');
99
- const owner = hop < 0 ? base.id : tableAtPrefix(names.schema, base.id, path.slice(0, hop))?.id;
100
- const second = owner ? subtitlePath(names.display(owner, path.slice(hop + 1)), path) : undefined;
101
- return second ? [second] : [];
102
- })
103
- : [];
110
+ const seconds = secondLines(names, base, [...new Set([...paths, ...(section.presentation === 'headline' ? extra : [])])]);
104
111
  const projection = referenceProjection(names.schema, base, [...new Set([...paths, ...extra, ...seconds])], section.names !== false && names.app, (table) => namePathOf(names, table));
105
112
  const fetched = projection.fetched;
106
113
  if (namePath && !fetched.includes(namePath))
@@ -141,6 +148,10 @@ export function headerColumns(names, base, section) {
141
148
  const namePath = namePathOf(names, base);
142
149
  if (namePath && !fetched.includes(namePath))
143
150
  fetched.push(namePath);
151
+ /* A fact's second line is drawn under its value, as a field's is. */
152
+ for (const second of secondLines(names, base, section.paths ?? []))
153
+ if (!fetched.includes(second))
154
+ fetched.push(second);
144
155
  return { fetched, labels: projection.labels };
145
156
  }
146
157
  /** The key as a filter on the record's own row, one equality per key column. */
@@ -166,11 +177,18 @@ function probeColumns(names, base) {
166
177
  const namePath = namePathOf(names, base);
167
178
  return [...primaryKey(base), ...(namePath ? [namePath] : [])];
168
179
  }
180
+ const isCards = (presentation) => typeof presentation === 'object' && presentation !== null && presentation.kind === 'cards';
169
181
  /** A related list's first request: its planned view at the reader's page size, with the names and keys a row needs. */
170
182
  export function listView(names, section, plan, rows) {
171
183
  const table = names.table ? names.table(section.from ?? '') : findTable(names.schema, section.from ?? '');
172
184
  const limit = section.limit ?? rows;
173
- const view = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
185
+ const sized = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
186
+ /* Cards read the second lines of the columns they draw with one (appListColumns.ts listSecondLineColumns). */
187
+ const drawn = sized?.columns;
188
+ const seconds = table && drawn && isCards(section.presentation)
189
+ ? secondLines(names, table, listSecondLineColumns(section.presentation)).filter((path) => !drawn.some((c) => c.path === path))
190
+ : [];
191
+ const view = seconds.length ? { ...sized, columns: [...drawn, ...seconds.map((path) => ({ path }))] } : sized;
174
192
  const explicit = (target) => (names.recordLabel(target.id) === undefined ? undefined : namePathOf(names, target));
175
193
  return view && table
176
194
  ? recordView(names.schema, table, view, names.app, (target) => namePathOf(names, target), explicit)
@@ -329,7 +329,7 @@ export interface AppDisplayRule {
329
329
  /** Every value no `values` key names said as words (`IN_REVIEW` → "In review"): the authored `values: true`,
330
330
  and implied by `values: { … }`, so a vocabulary never reads half in words and half in codes. */
331
331
  humanize?: true;
332
- /** Another column of the same record, said as a muted second line under the value in lists. */
332
+ /** Another column of the same record, said as a muted second line under the value wherever it has room (appListColumns.ts listSecondLineColumns). */
333
333
  subtitle?: string;
334
334
  /** A value renderer: the author's component draws the value in an App (appComponents.ts); sort, filter,
335
335
  totals and export keep the raw value, and the rest of the rule dresses it until the renderer arrives. */