@mnmal-ai/substrate 0.0.0 → 1.0.0-alpha.0

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 (46) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +118 -1
  3. package/dist/agent-token-BIboWOU0.js +200 -0
  4. package/dist/client.d.ts +782 -0
  5. package/dist/client.js +7 -0
  6. package/dist/cluster-worker.js +35 -0
  7. package/dist/content-type-C7T28xNb.js +25 -0
  8. package/dist/dataset-BXkus75W.js +1527 -0
  9. package/dist/env-utils-B7SGmoeJ.js +21 -0
  10. package/dist/errors-D4vKuwz8.d.ts +130 -0
  11. package/dist/fake-DUVtKVSE.js +36 -0
  12. package/dist/index-D7mSOFlM.d.ts +69 -0
  13. package/dist/pack.d.ts +192 -0
  14. package/dist/pack.js +5 -0
  15. package/dist/plugin-j1jt1l3n.js +3844 -0
  16. package/dist/plugin-t2g2wX0b.d.ts +1568 -0
  17. package/dist/proposals-bootstrap.js +37 -0
  18. package/dist/proposals.config.schema.json +20 -0
  19. package/dist/proposals.d.ts +118 -0
  20. package/dist/proposals.default-config.json +4 -0
  21. package/dist/proposals.js +4 -0
  22. package/dist/recall-bootstrap.js +451 -0
  23. package/dist/recall.config.schema.json +232 -0
  24. package/dist/recall.d.ts +1981 -0
  25. package/dist/recall.default-config.json +4 -0
  26. package/dist/recall.js +5 -0
  27. package/dist/repl-C52wyfMs.js +2213 -0
  28. package/dist/row-ByLFE2Wx.d.ts +719 -0
  29. package/dist/row-DK7lPZVe.js +732 -0
  30. package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
  31. package/dist/schema-g4FQLr0V.d.ts +433 -0
  32. package/dist/sdk.d.ts +694 -0
  33. package/dist/sdk.js +112 -0
  34. package/dist/src-C4DzaIQZ.js +837 -0
  35. package/dist/src-CrEgiMJQ.js +1015 -0
  36. package/dist/src-CzxvmhFn.js +2327 -0
  37. package/dist/src-D88LvCX8.js +1797 -0
  38. package/dist/src-D91yij6C.js +13523 -0
  39. package/dist/src-DuopV8u7.js +2408 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5477 -0
  42. package/dist/testing.d.ts +1240 -0
  43. package/dist/testing.js +702 -0
  44. package/dist/types-8c0gtnd2.d.ts +35 -0
  45. package/dist/ws-C72iVS5T.d.ts +143 -0
  46. package/package.json +117 -4
@@ -0,0 +1,2327 @@
1
+ import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
+ import { Ct as ReservedField, Et as UnsupportedFilterError, H as assertJsonPathPredicate, J as fullBuiltinOperators, K as decodeCursor, St as NamespaceMismatch, U as isJsonPathPredicate, V as preResolveExtensionOperatorsDetailed, X as fieldRequested, Y as applyExtensionResultMeta, _t as createKeyedMutex, q as encodeCursor } from "./src-D91yij6C.js";
3
+ import { createHash, randomUUID } from "node:crypto";
4
+
5
+ //#region ../../packages/substrate-dataset-pg/src/advisory-lock.ts
6
+ /**
7
+ * Session advisory lock on one reserved connection, for
8
+ * `PgDataset.withAdvisoryLock`.
9
+ */
10
+ const LOCAL_LOCKS = /* @__PURE__ */ new WeakMap();
11
+ /**
12
+ * Unlock `key` on `conn`. True when `conn` may go back to the pool. If the
13
+ * unlock throws, the session may still hold the lock, so it is terminated
14
+ * from another pooled connection instead, which drops every lock it holds and
15
+ * retires the connection; a reserved handle has no `end()`, and a backend
16
+ * terminating itself mid-query leaves postgres.js a stale error that surfaces
17
+ * uncaught on the connection's next use. The session is matched on
18
+ * `backend_start` as well as `pid`, because once it has ended its pid can
19
+ * name another session.
20
+ */
21
+ async function unlock(sql, conn, key, session) {
22
+ try {
23
+ await conn`SELECT pg_advisory_unlock(hashtext(${key}))`;
24
+ return true;
25
+ } catch {
26
+ if (sql.options.max <= 1) return true;
27
+ try {
28
+ return (await sql`
29
+ SELECT pg_terminate_backend(pid) FROM pg_stat_activity
30
+ WHERE pid = ${session.pid} AND backend_start = ${session.started}::timestamptz`).length === 0;
31
+ } catch {
32
+ return true;
33
+ }
34
+ }
35
+ }
36
+ /**
37
+ * Run `fn` while holding `pg_advisory_lock(hashtext(key))`, waiting until it
38
+ * is free. Lock and unlock share one reserved connection, because an unlock
39
+ * through the pool can land on another session and leave the lock held.
40
+ *
41
+ * Callers in this process queue on a local mutex first, so waiters for one key
42
+ * occupy at most one pooled connection per process; otherwise enough blocked
43
+ * waiters could take every connection and starve the holder's own `fn`.
44
+ *
45
+ * @returns whatever `fn` resolves to
46
+ * @throws whatever `fn` throws, after the lock is released
47
+ */
48
+ function withPgAdvisoryLock(sql, key, fn) {
49
+ let local = LOCAL_LOCKS.get(sql);
50
+ if (local === void 0) {
51
+ local = createKeyedMutex();
52
+ LOCAL_LOCKS.set(sql, local);
53
+ }
54
+ return local(key, async () => {
55
+ const conn = await sql.reserve();
56
+ let reusable = true;
57
+ try {
58
+ const [row] = await conn`
59
+ SELECT pg_advisory_lock(hashtext(${key})), pg_backend_pid() AS pid,
60
+ (SELECT backend_start::text FROM pg_stat_activity WHERE pid = pg_backend_pid()) AS started`;
61
+ try {
62
+ return await fn();
63
+ } finally {
64
+ reusable = await unlock(sql, conn, key, row ?? {
65
+ pid: 0,
66
+ started: "-infinity"
67
+ });
68
+ }
69
+ } finally {
70
+ if (reusable) conn.release();
71
+ }
72
+ });
73
+ }
74
+ /**
75
+ * Run `fn` only if `pg_try_advisory_lock(hashtext(key))` is free right now,
76
+ * on one reserved connection like `withPgAdvisoryLock`. A held lock resolves
77
+ * `{ acquired: false }` without running `fn` and without waiting.
78
+ *
79
+ * @throws whatever `fn` throws, after the lock is released
80
+ */
81
+ async function tryWithPgAdvisoryLock(sql, key, fn) {
82
+ const conn = await sql.reserve();
83
+ let reusable = true;
84
+ try {
85
+ const [row] = await conn`
86
+ SELECT pg_try_advisory_lock(hashtext(${key})) AS ok, pg_backend_pid() AS pid,
87
+ (SELECT backend_start::text FROM pg_stat_activity WHERE pid = pg_backend_pid()) AS started`;
88
+ if (row?.ok !== true) return { acquired: false };
89
+ try {
90
+ return {
91
+ acquired: true,
92
+ value: await fn()
93
+ };
94
+ } finally {
95
+ reusable = await unlock(sql, conn, key, row);
96
+ }
97
+ } finally {
98
+ if (reusable) conn.release();
99
+ }
100
+ }
101
+
102
+ //#endregion
103
+ //#region ../../packages/substrate-dataset-pg/src/migrations/0001_baseline.ts
104
+ /**
105
+ * 0001_baseline — the engine's schema: rows, edges, the idempotency cache and
106
+ * the short-id sidecar.
107
+ *
108
+ * Plugins own their tables and any columns they promote out of `rows.body`
109
+ * (see `PgDatasetOptions.promotedColumns`), and add them in their own kernel
110
+ * migrations. Idempotent, so re-running it changes nothing. `TX_STATEMENTS`
111
+ * run in one transaction; `CONCURRENT_STATEMENTS` run one by one after it
112
+ * commits, because Postgres refuses `CREATE INDEX CONCURRENTLY` in a
113
+ * transaction.
114
+ */
115
+ const TX_STATEMENTS$1 = [
116
+ `CREATE TABLE IF NOT EXISTS rows (
117
+ namespace text NOT NULL,
118
+ type text NOT NULL,
119
+ id text NOT NULL,
120
+ body jsonb NOT NULL,
121
+ deleted_at timestamptz NULL,
122
+ created_at timestamptz NULL,
123
+ updated_at timestamptz NULL,
124
+ created_by_kind text NULL,
125
+ created_by_id text NULL,
126
+ updated_by_kind text NULL,
127
+ updated_by_id text NULL,
128
+ PRIMARY KEY (namespace, type, id),
129
+ CONSTRAINT rows_created_by_kind_check
130
+ CHECK (created_by_kind IS NULL OR created_by_kind IN ('agent','user','system')),
131
+ CONSTRAINT rows_updated_by_kind_check
132
+ CHECK (updated_by_kind IS NULL OR updated_by_kind IN ('agent','user','system'))
133
+ )`,
134
+ `CREATE TABLE IF NOT EXISTS edges (
135
+ id uuid PRIMARY KEY,
136
+ from_ns text NOT NULL,
137
+ from_type text NOT NULL,
138
+ from_id text NOT NULL,
139
+ from_bridged boolean NOT NULL DEFAULT false,
140
+ to_ns text NOT NULL,
141
+ to_type text NOT NULL,
142
+ to_id text NOT NULL,
143
+ to_bridged boolean NOT NULL DEFAULT false,
144
+ field_name text NOT NULL,
145
+ policy text NOT NULL,
146
+ created_at timestamptz NOT NULL,
147
+ deleted_at timestamptz NULL,
148
+ last_swept_at timestamptz NULL,
149
+ blocked boolean NOT NULL DEFAULT false,
150
+ CONSTRAINT edges_policy_check
151
+ CHECK (policy IN ('set_null','cascade','restrict','orphan'))
152
+ )`,
153
+ `CREATE TABLE IF NOT EXISTS idempotency (
154
+ key text PRIMARY KEY,
155
+ envelope jsonb NOT NULL,
156
+ expires_at timestamptz NOT NULL,
157
+ created_at timestamptz NOT NULL DEFAULT now()
158
+ )`,
159
+ `CREATE TABLE IF NOT EXISTS short_ids (
160
+ namespace text NOT NULL,
161
+ type text NOT NULL,
162
+ short_id bigint NOT NULL,
163
+ row_id text NOT NULL,
164
+ PRIMARY KEY (namespace, type, short_id),
165
+ CONSTRAINT short_ids_row_id_fkey FOREIGN KEY (namespace, type, row_id)
166
+ REFERENCES rows (namespace, type, id) ON DELETE CASCADE
167
+ )`,
168
+ `CREATE UNIQUE INDEX IF NOT EXISTS substrate_key_live_kid_uniq
169
+ ON rows ((body ->> 'kid'))
170
+ WHERE namespace = '_system'
171
+ AND type = 'Key'
172
+ AND deleted_at IS NULL
173
+ AND (body ->> 'revokedAt') IS NULL`
174
+ ];
175
+ const CONCURRENT_STATEMENTS = [
176
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS rows_ns_type_created_at_idx
177
+ ON rows (namespace, type, created_at DESC NULLS LAST) WHERE deleted_at IS NULL`,
178
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS rows_ns_type_updated_at_idx
179
+ ON rows (namespace, type, updated_at DESC NULLS LAST) WHERE deleted_at IS NULL`,
180
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS rows_tombstoned_idx
181
+ ON rows (deleted_at) WHERE deleted_at IS NOT NULL`,
182
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS edges_to_live_idx
183
+ ON edges (to_ns, to_type, to_id) WHERE deleted_at IS NULL`,
184
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS edges_from_live_idx
185
+ ON edges (from_ns, from_type, from_id) WHERE deleted_at IS NULL`,
186
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS edges_cursor_idx
187
+ ON edges (id) WHERE deleted_at IS NULL`,
188
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS edges_tombstoned_idx
189
+ ON edges (deleted_at) WHERE deleted_at IS NOT NULL`,
190
+ `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS edges_logical_identity_unique_idx
191
+ ON edges (from_ns, from_type, from_id, field_name, to_ns, to_type, to_id)
192
+ WHERE deleted_at IS NULL`,
193
+ `CREATE INDEX CONCURRENTLY IF NOT EXISTS idempotency_expires_at_idx
194
+ ON idempotency (expires_at)`,
195
+ `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS short_ids_row_uniq_idx
196
+ ON short_ids (namespace, type, row_id)`
197
+ ];
198
+
199
+ //#endregion
200
+ //#region ../../packages/substrate-dataset-pg/src/migrations/0002_uuid_format_check.ts
201
+ /**
202
+ * 0002_uuid_format_check — CHECK constraints enforcing UUID format on
203
+ * `rows.id`, `short_ids.row_id`, `edges.from_id` and `edges.to_id`.
204
+ * (`edges.id` is a native uuid.)
205
+ *
206
+ * OPT-IN via `SUBSTRATE_ENFORCE_UUID_CHECK=true`: the test corpus uses synthetic
207
+ * non-UUID ids. Production enables it.
208
+ *
209
+ * The CHECK is the primary enforcement: a direct `dataset.write` bypasses
210
+ * autoCRUD's `randomUUID()` and must supply a UUID-shape id itself.
211
+ */
212
+ const UUID_REGEX = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
213
+ const TX_STATEMENTS = [
214
+ `DO $$ BEGIN
215
+ ALTER TABLE rows ADD CONSTRAINT rows_id_uuid_format
216
+ CHECK (id ~ '${UUID_REGEX}');
217
+ EXCEPTION WHEN duplicate_object THEN NULL;
218
+ END $$`,
219
+ `DO $$ BEGIN
220
+ ALTER TABLE short_ids ADD CONSTRAINT short_ids_row_id_uuid_format
221
+ CHECK (row_id ~ '${UUID_REGEX}');
222
+ EXCEPTION WHEN duplicate_object THEN NULL;
223
+ END $$`,
224
+ `DO $$ BEGIN
225
+ ALTER TABLE edges ADD CONSTRAINT edges_from_id_uuid_format
226
+ CHECK (from_id ~ '${UUID_REGEX}');
227
+ EXCEPTION WHEN duplicate_object THEN NULL;
228
+ END $$`,
229
+ `DO $$ BEGIN
230
+ ALTER TABLE edges ADD CONSTRAINT edges_to_id_uuid_format
231
+ CHECK (to_id ~ '${UUID_REGEX}');
232
+ EXCEPTION WHEN duplicate_object THEN NULL;
233
+ END $$`
234
+ ];
235
+
236
+ //#endregion
237
+ //#region ../../packages/substrate-dataset-pg/src/migrate.ts
238
+ /**
239
+ * Schema migrations for the pg Dataset + EdgesStore. Spec: §4.5, §4.6,
240
+ * §5.13.
241
+ *
242
+ * Each migration is a numbered module under `migrations/` exporting two
243
+ * statement buckets:
244
+ *
245
+ * - `txStatements` (or legacy `statements`) — DDL/DML safe inside a single
246
+ * transaction. The runner wraps the whole bucket in `BEGIN ... COMMIT`,
247
+ * so a partial-apply rolls back cleanly. Most migrations use this bucket
248
+ * exclusively.
249
+ * - `concurrentStatements` — `CREATE INDEX CONCURRENTLY`,
250
+ * `DROP INDEX CONCURRENTLY`, `REINDEX CONCURRENTLY`, etc. Postgres rejects
251
+ * these inside a transaction, so the runner executes them one-by-one
252
+ * AFTER the tx commits. A failure in this phase leaves the tx-phase work
253
+ * durable; re-running the migration is safe as long as each statement is
254
+ * `IF NOT EXISTS` / `IF EXISTS` guarded (idempotent), which is the
255
+ * convention for the concurrent bucket.
256
+ *
257
+ * The runner records applied versions in `migrations(version,
258
+ * applied_at, checksum)` and skips already-applied migrations on re-run.
259
+ * Crucially, the version is only marked applied AFTER both the tx phase
260
+ * commits AND the concurrent phase finishes successfully — a concurrent
261
+ * failure throws and the migration is left "in progress" so a re-run picks
262
+ * up where it left off (idempotent statements absorb the partial state).
263
+ *
264
+ * New migrations go in `migrations/` and are registered in MIGRATIONS below.
265
+ * Shipped migration files are IMMUTABLE — change schema only via a new file.
266
+ */
267
+ const MIGRATION_INPUTS = [{
268
+ version: "0001_baseline",
269
+ txStatements: TX_STATEMENTS$1,
270
+ concurrentStatements: CONCURRENT_STATEMENTS
271
+ }];
272
+ function normalise(input) {
273
+ if ("statements" in input && input.statements !== void 0) return {
274
+ version: input.version,
275
+ txStatements: input.statements,
276
+ concurrentStatements: []
277
+ };
278
+ return {
279
+ version: input.version,
280
+ txStatements: input.txStatements ?? [],
281
+ concurrentStatements: input.concurrentStatements ?? []
282
+ };
283
+ }
284
+ /**
285
+ * Opt-in migration: UUID-format CHECKs on row, short-id and edge ids.
286
+ * Registered only when `SUBSTRATE_ENFORCE_UUID_CHECK=true`, because the test
287
+ * corpus uses synthetic non-UUID ids.
288
+ */
289
+ const UUID_CHECK_INPUT = {
290
+ version: "0002_uuid_format_check",
291
+ txStatements: TX_STATEMENTS
292
+ };
293
+ /**
294
+ * @internal — the always-on migration list, exported for unit tests. The
295
+ * gated 0002 is appended by `getMigrationList`.
296
+ */
297
+ const MIGRATIONS = MIGRATION_INPUTS.map(normalise);
298
+ /**
299
+ * @internal — returns the migration list including the gated 0002 when
300
+ * `SUBSTRATE_ENFORCE_UUID_CHECK=true` (or the explicit override is true). Used by
301
+ * `runMigrations` and exported for the focused test that exercises the
302
+ * CHECK constraint.
303
+ */
304
+ function getMigrationList(enforceUuidCheck = process.env.SUBSTRATE_ENFORCE_UUID_CHECK === "true") {
305
+ if (enforceUuidCheck !== true) return MIGRATIONS;
306
+ return [...MIGRATIONS, normalise(UUID_CHECK_INPUT)];
307
+ }
308
+ /**
309
+ * sha256 across both buckets in fixed order (tx then concurrent).
310
+ */
311
+ /**
312
+ * @internal — exported for unit tests. Not re-exported from the package index.
313
+ */
314
+ function checksum(migration) {
315
+ const hasher = createHash("sha256");
316
+ for (const s of migration.txStatements) {
317
+ hasher.update(s);
318
+ hasher.update(" ");
319
+ }
320
+ for (const s of migration.concurrentStatements) {
321
+ hasher.update(s);
322
+ hasher.update(" ");
323
+ }
324
+ return hasher.digest("hex");
325
+ }
326
+ async function runMigrations(sql, opts = {}) {
327
+ await withMigrationLock(sql, (conn) => runMigrationsLocked(conn, opts));
328
+ }
329
+ /**
330
+ * Runs `fn` while holding the migration advisory lock on one reserved connection.
331
+ *
332
+ * The lock and unlock must share a session: through the pool, the unlock can
333
+ * land on another connection and leave the lock held. `fn` is handed that same
334
+ * connection, so a pool of one cannot deadlock waiting for a second. It has no
335
+ * `begin()`; open transactions with `BEGIN`/`COMMIT` statements.
336
+ */
337
+ /**
338
+ * Versions of the core migration list not yet applied to `sql`'s database,
339
+ * read without applying or creating anything. All of them when the
340
+ * `migrations` table does not exist.
341
+ */
342
+ async function pendingMigrations(sql) {
343
+ const [ledger] = await sql`
344
+ SELECT to_regclass('migrations') IS NOT NULL AS present
345
+ `;
346
+ const applied = ledger?.present === true ? new Set((await sql`SELECT version FROM migrations`).map((r) => r.version)) : /* @__PURE__ */ new Set();
347
+ return getMigrationList().map((m) => m.version).filter((v) => !applied.has(v));
348
+ }
349
+ async function withMigrationLock(sql, fn) {
350
+ const lockConn = await sql.reserve();
351
+ try {
352
+ await acquireMigrationLock(lockConn);
353
+ try {
354
+ return await fn(lockConn);
355
+ } finally {
356
+ const [row] = await lockConn`
357
+ SELECT pg_advisory_unlock(hashtext('substrate-migrations')) AS released
358
+ `;
359
+ if (row?.released === false) process.stderr.write("substrate migrations: advisory unlock reported the lock was not held by this session\n");
360
+ }
361
+ } finally {
362
+ lockConn.release();
363
+ }
364
+ }
365
+ async function acquireMigrationLock(sql) {
366
+ while (true) {
367
+ if ((await sql`
368
+ SELECT pg_try_advisory_lock(hashtext('substrate-migrations')) AS acquired
369
+ `)[0]?.acquired === true) return;
370
+ await new Promise((resolve) => setTimeout(resolve, 250));
371
+ }
372
+ }
373
+ async function runMigrationsLocked(sql, opts) {
374
+ if (opts.force === true) await sql`DROP TABLE IF EXISTS migrations`;
375
+ await sql`
376
+ CREATE TABLE IF NOT EXISTS migrations (
377
+ version text PRIMARY KEY,
378
+ applied_at timestamptz NOT NULL DEFAULT now(),
379
+ checksum text NOT NULL
380
+ )
381
+ `;
382
+ await sql`
383
+ CREATE TABLE IF NOT EXISTS migrations_audit (
384
+ id bigserial PRIMARY KEY,
385
+ version text NOT NULL,
386
+ previous_checksum text NOT NULL,
387
+ new_checksum text NOT NULL,
388
+ observed_at timestamptz NOT NULL DEFAULT now(),
389
+ reason text NOT NULL DEFAULT 'rehash',
390
+ build_sha text
391
+ )
392
+ `;
393
+ const applied = await sql`
394
+ SELECT version, checksum FROM migrations
395
+ `;
396
+ const appliedByVersion = new Map(applied.map((r) => [r.version, r.checksum]));
397
+ const REHASH_LIST = getMigrationList(true);
398
+ const buildSha = process.env.SUBSTRATE_BUILD_SHA ?? "unknown";
399
+ for (const migration of REHASH_LIST) {
400
+ const recorded = appliedByVersion.get(migration.version);
401
+ if (recorded === void 0) continue;
402
+ const current = checksum(migration);
403
+ if (recorded === current) continue;
404
+ process.stderr.write(`⚠️ migrations rehash: ${migration.version} (was=${recorded.slice(0, 12)} now=${current.slice(0, 12)} build=${buildSha}) — framework hash-format change masquerading as drift; recurring WARNs for the same version across deploys signal a true file edit.\n`);
405
+ await sql`
406
+ INSERT INTO migrations_audit (version, previous_checksum, new_checksum, build_sha)
407
+ VALUES (${migration.version}, ${recorded}, ${current}, ${buildSha})
408
+ `;
409
+ await sql`
410
+ UPDATE migrations SET checksum = ${current} WHERE version = ${migration.version}
411
+ `;
412
+ appliedByVersion.set(migration.version, current);
413
+ }
414
+ for (const migration of getMigrationList(opts.enforceUuidCheck)) {
415
+ if (appliedByVersion.get(migration.version) !== void 0) continue;
416
+ await applyOneMigration(sql, migration);
417
+ }
418
+ }
419
+ /**
420
+ * Apply one migration through the tracked machinery: tx-safe statements in a
421
+ * single BEGIN/COMMIT bucket, then concurrent statements one-by-one OUTSIDE any
422
+ * tx (Postgres rejects `CREATE INDEX CONCURRENTLY` in a transaction), then the
423
+ * `migrations` row. The version lands only after the concurrent phase
424
+ * succeeds, so a partial concurrent failure leaves the migration "in progress"
425
+ * and a re-run (statements are IF [NOT] EXISTS guarded) resumes it.
426
+ */
427
+ async function applyOneMigration(sql, migration) {
428
+ if (migration.txStatements.length > 0) {
429
+ await sql.unsafe("BEGIN");
430
+ try {
431
+ for (const stmt of migration.txStatements) await sql.unsafe(stmt);
432
+ await sql.unsafe("COMMIT");
433
+ } catch (err) {
434
+ await sql.unsafe("ROLLBACK");
435
+ throw err;
436
+ }
437
+ }
438
+ for (const stmt of migration.concurrentStatements) try {
439
+ await dropInvalidIndexFor(sql, stmt);
440
+ await sql.unsafe(stmt);
441
+ } catch (err) {
442
+ process.stderr.write(`migration ${migration.version}: concurrent-phase failure on statement; tx-phase changes are durable, re-run to resume concurrent phase: ${err instanceof Error ? err.message : String(err)}\n`);
443
+ throw err;
444
+ }
445
+ await sql`
446
+ INSERT INTO migrations (version, checksum)
447
+ VALUES (${migration.version}, ${checksum(migration)})
448
+ `;
449
+ }
450
+ const CONCURRENT_INDEX_RE = /^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+CONCURRENTLY\s+IF\s+NOT\s+EXISTS\s+([a-z_][a-z0-9_]*)\s/i;
451
+ /**
452
+ * A failed `CREATE INDEX CONCURRENTLY` leaves an INVALID index behind, which
453
+ * `IF NOT EXISTS` would accept forever. Drops the statement's index first when
454
+ * it exists and is invalid, so the re-run builds it again.
455
+ */
456
+ async function dropInvalidIndexFor(sql, stmt) {
457
+ const name = CONCURRENT_INDEX_RE.exec(stmt)?.[1];
458
+ if (name === void 0) return;
459
+ const [row] = await sql`
460
+ SELECT NOT indisvalid AS invalid FROM pg_index WHERE indexrelid = to_regclass(${name})
461
+ `;
462
+ if (row?.invalid === true) await sql.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${name}`);
463
+ }
464
+ /**
465
+ * `rows_<ns>_<type>_<field>_<hash>_<suffix>`, within pg's 63-byte identifier
466
+ * limit. The readable part is folded to `[a-z0-9_]` and capped, so it can
467
+ * collide (`my-tags` and `my_tags`, or a long shared prefix); the hash of the
468
+ * raw names keeps such fields from sharing one index or constraint.
469
+ */
470
+ function generatedIdentifier(namespace, type, field, suffix) {
471
+ const fold = (s) => s.toLowerCase().replace(/[^a-z0-9_]/g, "_");
472
+ const tail = `_${createHash("sha256").update(JSON.stringify([
473
+ namespace,
474
+ type,
475
+ field
476
+ ])).digest("hex").slice(0, 8)}_${suffix}`;
477
+ return `rows_${fold(namespace)}_${fold(type)}_${fold(field)}`.slice(0, 63 - tail.length) + tail;
478
+ }
479
+ /** Escape a value embedded in a single-quoted SQL string literal (defense-in-depth). */
480
+ function sqlStringLiteral(s) {
481
+ return s.replace(/'/g, "''");
482
+ }
483
+ /**
484
+ * Derives the tracked, idempotent CONCURRENTLY GIN migration for one indexed
485
+ * field. The version key uses the raw ns/type/field.
486
+ */
487
+ function deriveListIndexMigration(f) {
488
+ const name = generatedIdentifier(f.namespace, f.type, f.field, "gin");
489
+ const ns = sqlStringLiteral(f.namespace);
490
+ const type = sqlStringLiteral(f.type);
491
+ const field = sqlStringLiteral(f.field);
492
+ return {
493
+ version: `list-gin:${f.namespace}:${f.type}:${f.field}`,
494
+ txStatements: [],
495
+ concurrentStatements: [`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${name}\n ON rows USING GIN ((body -> '${field}') jsonb_path_ops)\n WHERE namespace = '${ns}' AND type = '${type}' AND deleted_at IS NULL`]
496
+ };
497
+ }
498
+ /**
499
+ * Applies migrations derived from field definitions through the same tracked,
500
+ * advisory-locked machinery as the static list. Called after plugins load,
501
+ * since `runMigrations` has no field-def knowledge. Idempotent: applied
502
+ * versions are skipped.
503
+ */
504
+ async function runDerivedMigrations(sql, derived) {
505
+ if (derived.length === 0) return;
506
+ await withMigrationLock(sql, async (conn) => {
507
+ await conn`
508
+ CREATE TABLE IF NOT EXISTS migrations (
509
+ version text PRIMARY KEY,
510
+ applied_at timestamptz NOT NULL DEFAULT now(),
511
+ checksum text NOT NULL
512
+ )
513
+ `;
514
+ const applied = await conn`SELECT version FROM migrations`;
515
+ const appliedVersions = new Set(applied.map((r) => r.version));
516
+ for (const input of derived) {
517
+ const migration = normalise(input);
518
+ if (appliedVersions.has(migration.version)) continue;
519
+ await applyOneMigration(conn, migration);
520
+ }
521
+ });
522
+ }
523
+
524
+ //#endregion
525
+ //#region ../../packages/substrate-dataset-pg/src/pg-short-id-store.ts
526
+ /**
527
+ * Derives a sequence name from (ns, type): lowercased, non-alphanumerics
528
+ * replaced with `_`, joined with a `__` separator. Safe for double-quoted
529
+ * identifier use.
530
+ *
531
+ * Distinct pairs can still share a sequence (`Foo` and `foo`, `a-` and `a_`,
532
+ * ('foo_', 'bar') and ('foo', '_bar') through the separator, names past pg's
533
+ * 63-byte limit). That only leaves gaps: numbers stay unique per (ns, type),
534
+ * the `short_ids` primary key. The name is not changed to avoid it, because
535
+ * renaming would restart existing sequences at 1. Underscore-led namespaces
536
+ * such as `_system_proposals` are therefore fine.
537
+ *
538
+ * @internal Exported for unit testing. Not part of the public package API.
539
+ */
540
+ function seqName(ns, type) {
541
+ const sanitize = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "_");
542
+ return `${sanitize(ns)}__${sanitize(type)}_short_id_seq`;
543
+ }
544
+ /**
545
+ * Parses a `bigint` column value (postgres.js returns a string) into a JS
546
+ * number. Throws if it exceeds `Number.MAX_SAFE_INTEGER`, where parsing
547
+ * would silently round into collisions. `undefined` (no row) returns `0`.
548
+ *
549
+ * @internal Exported for unit testing of the safe-integer assertion. Not
550
+ * part of the public package API.
551
+ */
552
+ function parseShortId(raw) {
553
+ if (raw === void 0) return 0;
554
+ const n = Number.parseInt(raw, 10);
555
+ if (!Number.isSafeInteger(n)) throw new Error(`PgShortIdStore: short_id ${raw} exceeds JS safe integer range`);
556
+ return n;
557
+ }
558
+ var PgShortIdStore = class {
559
+ sql;
560
+ #ensuredSequences = /* @__PURE__ */ new Set();
561
+ /** Wraps a single PG handle (Sql or TransactionSql); does not own the connection. */
562
+ constructor(sql) {
563
+ this.sql = sql;
564
+ }
565
+ async ensureSequence(ns, type) {
566
+ const name = seqName(ns, type);
567
+ const cacheKey = `${ns}\0${type}`;
568
+ if (this.#ensuredSequences.has(cacheKey)) return name;
569
+ await this.sql.unsafe(`CREATE SEQUENCE IF NOT EXISTS "${name}"`);
570
+ this.#ensuredSequences.add(cacheKey);
571
+ return name;
572
+ }
573
+ /**
574
+ * Allocate a new short-id for `rowId` and persist the mapping in a single
575
+ * round-trip via a CTE that calls `nextval` and INSERTs atomically.
576
+ * `ensureSequence` is called first (cached after the first call per (ns, type)).
577
+ */
578
+ async allocate(ns, type, rowId) {
579
+ const name = await this.ensureSequence(ns, type);
580
+ return parseShortId((await this.sql.unsafe(`WITH n AS (SELECT nextval('"${name}"') AS s)
581
+ INSERT INTO short_ids (namespace, type, short_id, row_id)
582
+ SELECT $1, $2, n.s, $3 FROM n
583
+ ON CONFLICT DO NOTHING
584
+ RETURNING short_id`, [
585
+ ns,
586
+ type,
587
+ rowId
588
+ ]))[0]?.short_id);
589
+ }
590
+ /**
591
+ * Allocate a new short-id without binding it to a row. The caller is
592
+ * responsible for calling `bind` before the row is visible to consumers.
593
+ * Used by the migrate backfill's preload path.
594
+ */
595
+ async allocateUnbound(ns, type) {
596
+ const name = await this.ensureSequence(ns, type);
597
+ return parseShortId((await this.sql.unsafe(`SELECT nextval('"${name}"') AS nextval`))[0]?.nextval);
598
+ }
599
+ /**
600
+ * Bind a previously-allocated short-id to a row. `ON CONFLICT DO NOTHING`
601
+ * covers both the PK `(namespace, type, short_id)` and the UNIQUE index
602
+ * `(namespace, type, row_id)` — idempotent for backfill re-runs.
603
+ */
604
+ async bind(ns, type, shortId, rowId) {
605
+ await this.sql`
606
+ INSERT INTO short_ids (namespace, type, short_id, row_id)
607
+ VALUES (${ns}, ${type}, ${shortId}, ${rowId})
608
+ ON CONFLICT DO NOTHING
609
+ `;
610
+ }
611
+ /**
612
+ * Resolve a numeric short-id to its row UUID. Returns `null` when no
613
+ * binding exists for the given `(ns, type, shortId)` triple.
614
+ */
615
+ async resolveShortId(ns, type, shortId) {
616
+ return (await this.sql`
617
+ SELECT row_id FROM short_ids
618
+ WHERE namespace = ${ns} AND type = ${type} AND short_id = ${shortId}
619
+ `)[0]?.row_id ?? null;
620
+ }
621
+ /**
622
+ * Look up the short-id assigned to a row UUID. Returns `null` when the row
623
+ * has no short-id binding yet.
624
+ */
625
+ async getShortIdForRow(ns, type, rowId) {
626
+ const rows = await this.sql`
627
+ SELECT short_id FROM short_ids
628
+ WHERE namespace = ${ns} AND type = ${type} AND row_id = ${rowId}
629
+ `;
630
+ if (!rows[0]) return null;
631
+ return parseShortId(rows[0].short_id);
632
+ }
633
+ /**
634
+ * Hard-delete all short-id rows for a specific (ns, type). Returns the count
635
+ * of rows deleted. The sequence for that type is left in place — sequences
636
+ * are schema objects and the caller can recreate one if needed.
637
+ */
638
+ async dropType(ns, type) {
639
+ return (await this.sql`
640
+ DELETE FROM short_ids
641
+ WHERE namespace = ${ns} AND type = ${type}
642
+ RETURNING short_id
643
+ `).length;
644
+ }
645
+ /**
646
+ * Hard-delete all short-id rows for every type in a namespace. Returns the
647
+ * total count of rows deleted across all types.
648
+ */
649
+ async dropNamespace(ns) {
650
+ return (await this.sql`
651
+ DELETE FROM short_ids
652
+ WHERE namespace = ${ns}
653
+ RETURNING short_id
654
+ `).length;
655
+ }
656
+ /**
657
+ * Bulk-insert pre-existing mappings and advance the sequence past the max
658
+ * shortId seen. Used by substrate-migrate backfill. Idempotent — re-runs are
659
+ * no-ops via ON CONFLICT DO NOTHING + GREATEST on setval.
660
+ */
661
+ async preload(ns, type, entries) {
662
+ if (entries.length === 0) return;
663
+ await this.sql`
664
+ INSERT INTO short_ids ${this.sql(entries.map((e) => ({
665
+ namespace: ns,
666
+ type,
667
+ short_id: e.shortId,
668
+ row_id: e.rowId
669
+ })), "namespace", "type", "short_id", "row_id")}
670
+ ON CONFLICT (namespace, type, short_id) DO NOTHING
671
+ `;
672
+ const max = entries.reduce((m, e) => e.shortId > m ? e.shortId : m, 0);
673
+ const name = await this.ensureSequence(ns, type);
674
+ await this.sql.unsafe(`SELECT setval('"${name}"', GREATEST((SELECT last_value FROM "${name}"), ${max}))`);
675
+ }
676
+ };
677
+
678
+ //#endregion
679
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/primitives.ts
680
+ const idToText = (id) => typeof id === "number" ? String(id) : id;
681
+ /**
682
+ * Row-metadata field → native column. Predicates on these fields use the
683
+ * indexed columns rather than `body ->> field`. The `r.` alias matches
684
+ * `read()`'s SELECT.
685
+ */
686
+ const METADATA_COLUMNS = {
687
+ createdAt: "r.created_at",
688
+ updatedAt: "r.updated_at",
689
+ createdById: "r.created_by_id",
690
+ createdByKind: "r.created_by_kind",
691
+ updatedById: "r.updated_by_id",
692
+ updatedByKind: "r.updated_by_kind"
693
+ };
694
+ function isMetadataField(field) {
695
+ return Object.hasOwn(METADATA_COLUMNS, field);
696
+ }
697
+ /**
698
+ * Legal bare column identifier: lower-snake, no quoting, no qualifier. This
699
+ * allow-list is what stands between a caller-supplied map and `sql.unsafe`.
700
+ */
701
+ const COLUMN_NAME_PATTERN = /^[a-z_][a-z0-9_]*$/;
702
+ /**
703
+ * Validates a caller-supplied map and returns the lookup the SQL builders use.
704
+ * Throws if any column is not a bare identifier.
705
+ *
706
+ * The validation is load-bearing: the builders interpolate the column through
707
+ * `sql.unsafe`, and the map may come from config.
708
+ */
709
+ function resolvePromotedColumns(map) {
710
+ const resolved = /* @__PURE__ */ new Map();
711
+ for (const [field, def] of Object.entries(map)) {
712
+ if (!COLUMN_NAME_PATTERN.test(def.column)) throw new Error(`promotedColumns['${field}']: column '${def.column}' is not a bare identifier (expected ${COLUMN_NAME_PATTERN.source}). The table qualifier is added internally; pass 'severity', not 'r.severity'.`);
713
+ resolved.set(field, def);
714
+ }
715
+ return (field) => resolved.get(field);
716
+ }
717
+ /** The qualified expression source for a promoted column — `r.<column>`. */
718
+ function promotedColumnSql(def) {
719
+ return `r.${def.column}`;
720
+ }
721
+ /**
722
+ * Row-shape keys that DO NOT live in `r.body` — they're synthesised from
723
+ * dedicated columns (`_metadata`, `shortId`, `_deletedAt`) or extracted by
724
+ * `materialize()` (`id` lives both in the column and in body, but is force-
725
+ * included by the projection builder regardless of whether the caller asked).
726
+ *
727
+ * Used by `buildBodyProjection` to filter caller-supplied `fields` keys when
728
+ * deciding which body keys to materialise from JSONB.
729
+ */
730
+ const NON_BODY_FIELD_KEYS = /* @__PURE__ */ new Set([
731
+ "_metadata",
732
+ "_deletedAt",
733
+ "shortId"
734
+ ]);
735
+ const asJsonValue = (v) => v;
736
+ function scalarParam(value) {
737
+ if (value instanceof Date) return value.toISOString();
738
+ if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
739
+ return String(value);
740
+ }
741
+ function escapeLike(s) {
742
+ return s.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
743
+ }
744
+ /** Operand-shape guard for string operands. See UnsupportedFilterError. */
745
+ function metaStr(field, op, v) {
746
+ if (typeof v !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
747
+ return v;
748
+ }
749
+ /**
750
+ * Join a list of boolean fragments with AND. Returns a degenerate `TRUE`
751
+ * fragment when the list is empty so callers can always drop it into a
752
+ * `WHERE ${whereSql}` slot without a branch.
753
+ *
754
+ * Composition is flat: postgres.js joins an interpolated Fragment[] with
755
+ * spaces, so interleaving `AND` fragments yields one template with no nested
756
+ * PendingQuery per predicate.
757
+ */
758
+ function combineAnd(sql, fragments) {
759
+ if (fragments.length === 0) return sql`TRUE`;
760
+ if (fragments.length === 1) return sql`(${fragments[0]})`;
761
+ return sql`(${interleaveOperator(sql, fragments, " AND ")})`;
762
+ }
763
+ function combineOr(sql, fragments) {
764
+ if (fragments.length === 0) return sql`FALSE`;
765
+ if (fragments.length === 1) return sql`(${fragments[0]})`;
766
+ return sql`(${interleaveOperator(sql, fragments, " OR ")})`;
767
+ }
768
+ /**
769
+ * Build `[frag0, sql`<op>`, frag1, sql`<op>`, ...]` so postgres.js's
770
+ * Fragment[] interpolation produces `frag0 <op> frag1 <op> ...` in a single
771
+ * flat template. Callers handle the empty and single-fragment cases.
772
+ */
773
+ function interleaveOperator(sql, fragments, op) {
774
+ const opFragment = op === " AND " ? sql`AND` : sql`OR`;
775
+ const out = [fragments[0]];
776
+ for (let i = 1; i < fragments.length; i++) out.push(opFragment, fragments[i]);
777
+ return out;
778
+ }
779
+
780
+ //#endregion
781
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/projection.ts
782
+ /**
783
+ * Returns the body SELECT expression for a read.
784
+ *
785
+ * - `fields === undefined` → the full body.
786
+ * - `fields` supplied → `jsonb_build_object(...)` over `id` plus the
787
+ * requested top-level body keys. `id` is always included because
788
+ * `materialize()` reads `body.id` to preserve numeric ids.
789
+ *
790
+ * Keys are bound as parameters, never concatenated.
791
+ */
792
+ function buildBodyProjection(sql, fields) {
793
+ if (fields === void 0) return sql`r.body`;
794
+ const bodyKeys = /* @__PURE__ */ new Set(["id"]);
795
+ for (const key of Object.keys(fields)) {
796
+ if (NON_BODY_FIELD_KEYS.has(key)) continue;
797
+ bodyKeys.add(key);
798
+ }
799
+ const keyArr = Array.from(bodyKeys);
800
+ if (keyArr.length === 0) return sql`'{}'::jsonb`;
801
+ const pairs = keyArr.map((k) => sql`${k}::text, r.body->${k}`);
802
+ const commaFrag = sql`,`;
803
+ const interleaved = [pairs[0]];
804
+ for (let i = 1; i < pairs.length; i++) interleaved.push(commaFrag, pairs[i]);
805
+ return sql`jsonb_build_object(${interleaved})`;
806
+ }
807
+ function assembleRowMetadata(record) {
808
+ if (record.created_at === null && record.updated_at === null && record.created_by_kind === null && record.created_by_id === null && record.updated_by_kind === null && record.updated_by_id === null) return;
809
+ const createdBy = record.created_by_kind !== null && record.created_by_id !== null ? {
810
+ kind: record.created_by_kind,
811
+ id: record.created_by_id
812
+ } : null;
813
+ const updatedBy = record.updated_by_kind !== null && record.updated_by_id !== null ? {
814
+ kind: record.updated_by_kind,
815
+ id: record.updated_by_id
816
+ } : null;
817
+ return {
818
+ createdAt: record.created_at !== null ? record.created_at.toISOString() : null,
819
+ updatedAt: record.updated_at !== null ? record.updated_at.toISOString() : null,
820
+ createdBy,
821
+ updatedBy
822
+ };
823
+ }
824
+
825
+ //#endregion
826
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/sorting.ts
827
+ function normalizeOrderBy(orderBy) {
828
+ const out = [];
829
+ if (orderBy !== void 0) for (const clause of orderBy) for (const [field, dir] of Object.entries(clause)) out.push([field, dir]);
830
+ if (!out.some(([f]) => f === "id")) out.push(["id", "asc"]);
831
+ return out;
832
+ }
833
+ /**
834
+ * Maps a FieldDef to the pg cast applied to its `body ->> field` text
835
+ * extraction. Returns `null` for kinds where text compare is correct (string),
836
+ * opaque (json), structural (struct/list/crossRef), or undeclared.
837
+ *
838
+ * Type → cast table:
839
+ * field.number() / 'number' → 'numeric'
840
+ * field.date() / 'date' → 'timestamptz'
841
+ * field.boolean() / 'boolean' → 'boolean'
842
+ * field.string() / 'string' → null (text compare is correct)
843
+ * field.json() / 'json' → null (opaque body — orderBy is rejected
844
+ * by the validator anyway)
845
+ * crossRef / struct / list → null (orderBy on these isn't a scalar
846
+ * comparison; let text-compare
847
+ * surface the bug at validation)
848
+ */
849
+ function resolveBodyOrderByCast(def) {
850
+ if (def === void 0) return null;
851
+ if (def.kind !== "scalar") return null;
852
+ switch (def.type) {
853
+ case "number": return "numeric";
854
+ case "date": return "timestamptz";
855
+ case "boolean": return "boolean";
856
+ default: return null;
857
+ }
858
+ }
859
+ function buildOrderBy(sql, orderBy, castFor, promotedFor) {
860
+ if (orderBy.length === 0) return sql``;
861
+ const parts = [];
862
+ for (const [field, dir] of orderBy) parts.push(orderByFragment(sql, field, dir, castFor(field), promotedFor));
863
+ if (parts.length === 1) return sql`ORDER BY ${parts[0]}`;
864
+ const commaFragment = sql`,`;
865
+ const interleaved = [parts[0]];
866
+ for (let i = 1; i < parts.length; i++) interleaved.push(commaFragment, parts[i]);
867
+ return sql`ORDER BY ${interleaved}`;
868
+ }
869
+ /**
870
+ * The SQL expression a field SORTS BY — the single source for ORDER BY and for
871
+ * both halves of the keyset cursor comparison.
872
+ *
873
+ * Do not case out field kinds anywhere else: if sorting and paging use
874
+ * different expressions, rows silently vanish from later pages.
875
+ */
876
+ function sortExpr(sql, field, bodyCast, promotedFor) {
877
+ if (field === "id") return sql`id`;
878
+ if (field === "shortId") return sql`s.short_id`;
879
+ if (isMetadataField(field)) return sql.unsafe(METADATA_COLUMNS[field]);
880
+ const promoted = promotedFor(field);
881
+ if (promoted !== void 0) return sql.unsafe(promotedColumnSql(promoted));
882
+ return bodyOrderByExpr(sql, field, bodyCast);
883
+ }
884
+ /**
885
+ * Projects each non-`id` ORDER BY field's sort expression alongside the row,
886
+ * so the keyset cursor's value comes from the expression that sorted, not the
887
+ * materialized row (which holds only the projected fields). Returns the SELECT
888
+ * fragment and the field → alias map.
889
+ *
890
+ * Aliases are POSITIONAL (`__sort_0`, ...), not field-derived: pg truncates
891
+ * identifiers at 63 bytes, so long field names could collide.
892
+ */
893
+ function buildSortKeyProjection(sql, orderBy, castFor, promotedFor) {
894
+ const aliases = /* @__PURE__ */ new Map();
895
+ const fragments = [];
896
+ for (const [field] of orderBy) {
897
+ if (field === "id" || aliases.has(field)) continue;
898
+ const alias = `__sort_${aliases.size}`;
899
+ aliases.set(field, alias);
900
+ fragments.push(sql`, ${sortExpr(sql, field, castFor(field), promotedFor)} AS ${sql(alias)}`);
901
+ }
902
+ if (fragments.length === 0) return {
903
+ fragment: sql``,
904
+ aliases
905
+ };
906
+ return {
907
+ fragment: fragments,
908
+ aliases
909
+ };
910
+ }
911
+ /**
912
+ * The parameter side of a comparison against `sortExpr(field)`, cast to match
913
+ * it. Keep its cases in step with `sortExpr`.
914
+ */
915
+ function sortParam(sql, field, value, bodyCast, promotedFor) {
916
+ if (field === "id") return sql`${idToText(value)}`;
917
+ if (field === "shortId") return sql`${value}`;
918
+ if (isMetadataField(field)) return field === "createdAt" || field === "updatedAt" ? sql`${value}::timestamptz` : sql`${value}`;
919
+ const promoted = promotedFor(field);
920
+ if (promoted !== void 0) return promoted.kind === "boolean" ? sql`${Boolean(value)}::boolean` : sql`${String(value)}::text`;
921
+ return castParam(sql, value, bodyCast);
922
+ }
923
+ function orderByFragment(sql, field, dir, bodyCast, promotedFor) {
924
+ const expr = sortExpr(sql, field, bodyCast, promotedFor);
925
+ return dir === "asc" ? sql`${expr} ASC NULLS LAST` : sql`${expr} DESC NULLS LAST`;
926
+ }
927
+ /**
928
+ * The body-field extraction expression for a sort, with the cast applied when
929
+ * one is given. `sql.unsafe` emits only the closed `BodyOrderByCast` suffix;
930
+ * `field` is parameterised.
931
+ */
932
+ function bodyOrderByExpr(sql, field, cast) {
933
+ if (cast === null) return sql`(body ->> ${field}) COLLATE "C"`;
934
+ return sql`(body ->> ${field})${sql.unsafe(`::${cast}`)}`;
935
+ }
936
+ /**
937
+ * Cursor tuple compare. For `ORDER BY a ASC, b DESC, id ASC`, the "next page"
938
+ * predicate is:
939
+ * (a > cursor.a)
940
+ * OR (a = cursor.a AND b < cursor.b)
941
+ * OR (a = cursor.a AND b = cursor.b AND id > cursor.id)
942
+ *
943
+ * We build the OR of equality-prefixes explicitly — postgres's ROW(...) tuple
944
+ * compare would be simpler but doesn't honour per-column direction mixing.
945
+ */
946
+ function buildCursorCompare(sql, orderBy, values, cursorId, castFor, promotedFor) {
947
+ if (orderBy.length === 0) return null;
948
+ const resolved = [];
949
+ let nonIdIdx = 0;
950
+ for (const [field, dir] of orderBy) if (field === "id") resolved.push({
951
+ field,
952
+ dir,
953
+ value: cursorId
954
+ });
955
+ else {
956
+ resolved.push({
957
+ field,
958
+ dir,
959
+ value: values[nonIdIdx]
960
+ });
961
+ nonIdIdx++;
962
+ }
963
+ const orParts = [];
964
+ for (let i = 0; i < resolved.length; i++) {
965
+ const parts = [];
966
+ for (let j = 0; j < i; j++) {
967
+ const prior = resolved[j];
968
+ parts.push(cursorEqFragment(sql, prior.field, prior.value, castFor(prior.field), promotedFor));
969
+ }
970
+ const cur = resolved[i];
971
+ parts.push(cursorCmpFragment(sql, cur.field, cur.dir, cur.value, castFor(cur.field), promotedFor));
972
+ orParts.push(combineAnd(sql, parts));
973
+ }
974
+ return combineOr(sql, orParts);
975
+ }
976
+ /**
977
+ * Equality against the sort key, for the `eq₁ AND ... AND cmpᵢ` prefix of the
978
+ * keyset disjunction. A NULL sort key compares with `IS NULL`, never `= NULL`.
979
+ */
980
+ function cursorEqFragment(sql, field, value, bodyCast, promotedFor) {
981
+ const expr = sortExpr(sql, field, bodyCast, promotedFor);
982
+ if (value === null || value === void 0) return sql`${expr} IS NULL`;
983
+ return sql`${expr} = ${sortParam(sql, field, value, bodyCast, promotedFor)}`;
984
+ }
985
+ /**
986
+ * "Strictly after the cursor" for one sort key, under `NULLS LAST`. A bare
987
+ * `expr > $1` would exclude null rows, since `NULL > x` is NULL. The two cases:
988
+ *
989
+ * cursor value NOT NULL — the rows after it are the ones further along in
990
+ * direction, PLUS the entire null tail, hence the `OR ... IS NULL`.
991
+ * cursor value IS NULL — nothing sorts after a null, so no row qualifies on
992
+ * THIS key and the disjunction must fall through to the next one. `false`
993
+ * is the correct answer, not `IS NULL`: the outer construction pairs this
994
+ * with `eq` on the preceding keys, and returning `IS NULL` here would
995
+ * re-emit every null row that has already been served.
996
+ */
997
+ function cursorCmpFragment(sql, field, dir, value, bodyCast, promotedFor) {
998
+ const expr = sortExpr(sql, field, bodyCast, promotedFor);
999
+ if (value === null || value === void 0) return sql`false`;
1000
+ const param = sortParam(sql, field, value, bodyCast, promotedFor);
1001
+ return dir === "asc" ? sql`(${expr} > ${param} OR ${expr} IS NULL)` : sql`(${expr} < ${param} OR ${expr} IS NULL)`;
1002
+ }
1003
+ /**
1004
+ * The parameter side of a body-field cursor compare, with the cast matching
1005
+ * the orderBy expression: `castParam(sql, 5, 'numeric')` → `$N::numeric`.
1006
+ * Returns the bare parameter when `cast === null`.
1007
+ */
1008
+ function castParam(sql, value, cast) {
1009
+ const param = scalarParam(value);
1010
+ if (cast === null) return sql`${param}`;
1011
+ return sql`${param}${sql.unsafe(`::${cast}`)}`;
1012
+ }
1013
+
1014
+ //#endregion
1015
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-json-path.ts
1016
+ /**
1017
+ * Compiles `{ field: { path: [...], <op> } }` on a json field.
1018
+ *
1019
+ * Must return exactly the rows `@mnmal-ai/substrate-filter`'s json-path.ts
1020
+ * evaluator does. Three compilation choices carry that:
1021
+ *
1022
+ * - `eq` / `in` / `has` are containment, `(body -> field) @> doc`. Type-strict
1023
+ * by construction (1995 does not contain "1995"). Written against the
1024
+ * FIELD, not the body, so it matches the scoped GIN that
1025
+ * `field.json({ indexed: true })` derives.
1026
+ * - Everything typed is `COALESCE(CASE WHEN jsonb_typeof(x) = … THEN … END,
1027
+ * FALSE)`. CASE because SQL does not promise AND short-circuits, so a
1028
+ * guarded `::numeric` could still meet 'unknown' and fail the whole query;
1029
+ * COALESCE because a bare CASE yields NULL on a mismatch and `NOT NULL` is
1030
+ * NULL, which would silently drop rows from a caller's `NOT`.
1031
+ * - The walk is the `->` chain, never `#>`: `#>` treats "0" as an array
1032
+ * index, and the evaluator walks objects only. `->` with a text key on an
1033
+ * array is NULL, which agrees.
1034
+ */
1035
+ /** `{ p0: { … pN: leaf } }` — the document `(body -> field) @>` tests for. */
1036
+ function nestPath(path, leaf) {
1037
+ let doc = leaf;
1038
+ for (let i = path.length - 1; i >= 0; i--) doc = { [path[i]]: doc };
1039
+ return doc;
1040
+ }
1041
+ function buildJsonPathPredicate(sql, field, predicate) {
1042
+ assertJsonPathPredicate(field, predicate);
1043
+ const path = predicate.path;
1044
+ let x = sql`body -> ${field}`;
1045
+ for (const seg of path) x = sql`${x} -> ${seg}`;
1046
+ x = sql`(${x})`;
1047
+ const text = sql`(${x} #>> '{}')`;
1048
+ const fieldExpr = sql`(body -> ${field})`;
1049
+ const containsDoc = (leaf) => sql`${fieldExpr} @> ${sql.json(asJsonValue(nestPath(path, leaf)))}`;
1050
+ const contains = (leaf) => sql`(${fieldExpr} IS NOT NULL AND ${containsDoc(leaf)})`;
1051
+ const isNull = sql`(${x} IS NULL OR jsonb_typeof(${x}) = 'null')`;
1052
+ const eq = (v) => v === null ? isNull : contains(v);
1053
+ const inList = (vs) => {
1054
+ const members = vs.filter((v) => v !== null);
1055
+ const parts = [];
1056
+ if (members.length > 0) parts.push(sql`(${fieldExpr} IS NOT NULL AND ${combineOr(sql, members.map(containsDoc))})`);
1057
+ if (members.length < vs.length) parts.push(isNull);
1058
+ return parts.length === 0 ? sql`FALSE` : combineOr(sql, parts);
1059
+ };
1060
+ const guarded = (jsonType, cond) => sql`COALESCE(CASE WHEN jsonb_typeof(${x}) = ${jsonType} THEN ${cond} END, FALSE)`;
1061
+ const cmp = (op, operand) => {
1062
+ if (typeof operand === "number") {
1063
+ const n = sql`${text}::numeric`;
1064
+ switch (op) {
1065
+ case ">": return guarded("number", sql`${n} > ${operand}`);
1066
+ case ">=": return guarded("number", sql`${n} >= ${operand}`);
1067
+ case "<": return guarded("number", sql`${n} < ${operand}`);
1068
+ case "<=": return guarded("number", sql`${n} <= ${operand}`);
1069
+ }
1070
+ }
1071
+ const s = sql`${text} COLLATE "C"`;
1072
+ switch (op) {
1073
+ case ">": return guarded("string", sql`${s} > ${operand}`);
1074
+ case ">=": return guarded("string", sql`${s} >= ${operand}`);
1075
+ case "<": return guarded("string", sql`${s} < ${operand}`);
1076
+ case "<=": return guarded("string", sql`${s} <= ${operand}`);
1077
+ }
1078
+ };
1079
+ const fragments = [];
1080
+ for (const [op, operand] of Object.entries(predicate)) switch (op) {
1081
+ case "path": break;
1082
+ case "eq":
1083
+ fragments.push(eq(operand));
1084
+ break;
1085
+ case "neq":
1086
+ fragments.push(sql`NOT (${eq(operand)})`);
1087
+ break;
1088
+ case "in":
1089
+ fragments.push(inList(operand));
1090
+ break;
1091
+ case "nin":
1092
+ fragments.push(sql`NOT (${inList(operand)})`);
1093
+ break;
1094
+ case "gt":
1095
+ fragments.push(cmp(">", operand));
1096
+ break;
1097
+ case "gte":
1098
+ fragments.push(cmp(">=", operand));
1099
+ break;
1100
+ case "lt":
1101
+ fragments.push(cmp("<", operand));
1102
+ break;
1103
+ case "lte":
1104
+ fragments.push(cmp("<=", operand));
1105
+ break;
1106
+ case "between": {
1107
+ const [lo, hi] = operand;
1108
+ fragments.push(typeof lo === "number" ? guarded("number", sql`${text}::numeric BETWEEN ${lo} AND ${hi}`) : guarded("string", sql`${text} COLLATE "C" BETWEEN ${lo} AND ${hi}`));
1109
+ break;
1110
+ }
1111
+ case "contains":
1112
+ fragments.push(guarded("string", sql`${text} ILIKE ${`%${escapeLike(operand)}%`}`));
1113
+ break;
1114
+ case "startsWith":
1115
+ fragments.push(guarded("string", sql`${text} ILIKE ${`${escapeLike(operand)}%`}`));
1116
+ break;
1117
+ case "endsWith":
1118
+ fragments.push(guarded("string", sql`${text} ILIKE ${`%${escapeLike(operand)}`}`));
1119
+ break;
1120
+ default: fragments.push(contains([operand]));
1121
+ }
1122
+ return combineAnd(sql, fragments);
1123
+ }
1124
+
1125
+ //#endregion
1126
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-metadata.ts
1127
+ /**
1128
+ * WHERE predicates against the native row-metadata columns on `rows`,
1129
+ * rather than `body ->> field` extraction.
1130
+ */
1131
+ /**
1132
+ * Builds WHERE predicates against a metadata column (e.g. `r.created_at`).
1133
+ * Returns null when no operator produced a predicate; throws
1134
+ * `UnsupportedFilterError` on an unknown operator.
1135
+ *
1136
+ * Timestamp columns take equality and range operators; the `*ByKind` /
1137
+ * `*ById` text columns take equality, range and pattern operators. The column
1138
+ * comes from the constant `METADATA_COLUMNS`, so `sql.unsafe` is safe here.
1139
+ */
1140
+ function buildMetadataColumnPredicate(sql, field, predicate) {
1141
+ const colName = METADATA_COLUMNS[field];
1142
+ const isTimestamp = field === "createdAt" || field === "updatedAt";
1143
+ const fragments = [];
1144
+ for (const [op, operand] of Object.entries(predicate)) {
1145
+ let frag = null;
1146
+ const col = sql.unsafe(colName);
1147
+ if (isTimestamp) switch (op) {
1148
+ case "eq":
1149
+ if (operand === null) frag = sql`${col} IS NULL`;
1150
+ else if (typeof operand === "string") frag = sql`${col} = ${operand}::timestamptz`;
1151
+ else if (operand instanceof Date) frag = sql`${col} = ${operand.toISOString()}::timestamptz`;
1152
+ break;
1153
+ case "neq":
1154
+ if (operand === null) frag = sql`${col} IS NOT NULL`;
1155
+ else if (typeof operand === "string") frag = sql`${col} IS DISTINCT FROM ${operand}::timestamptz`;
1156
+ else if (operand instanceof Date) frag = sql`${col} IS DISTINCT FROM ${operand.toISOString()}::timestamptz`;
1157
+ break;
1158
+ case "gt":
1159
+ if (typeof operand === "string") frag = sql`${col} > ${operand}::timestamptz`;
1160
+ else if (operand instanceof Date) frag = sql`${col} > ${operand.toISOString()}::timestamptz`;
1161
+ break;
1162
+ case "gte":
1163
+ if (typeof operand === "string") frag = sql`${col} >= ${operand}::timestamptz`;
1164
+ else if (operand instanceof Date) frag = sql`${col} >= ${operand.toISOString()}::timestamptz`;
1165
+ break;
1166
+ case "lt":
1167
+ if (typeof operand === "string") frag = sql`${col} < ${operand}::timestamptz`;
1168
+ else if (operand instanceof Date) frag = sql`${col} < ${operand.toISOString()}::timestamptz`;
1169
+ break;
1170
+ case "lte":
1171
+ if (typeof operand === "string") frag = sql`${col} <= ${operand}::timestamptz`;
1172
+ else if (operand instanceof Date) frag = sql`${col} <= ${operand.toISOString()}::timestamptz`;
1173
+ break;
1174
+ case "between":
1175
+ if (Array.isArray(operand) && operand.length === 2) frag = sql`${col} BETWEEN ${operand[0] instanceof Date ? operand[0].toISOString() : String(operand[0])}::timestamptz AND ${operand[1] instanceof Date ? operand[1].toISOString() : String(operand[1])}::timestamptz`;
1176
+ break;
1177
+ case "in":
1178
+ case "nin":
1179
+ if (Array.isArray(operand)) {
1180
+ const member = memberOf(sql, col, sql`${operand.filter((v) => v !== null).map((v) => v instanceof Date ? v.toISOString() : String(v))}::timestamptz[]`, operand);
1181
+ frag = op === "in" ? member : sql`NOT ${member}`;
1182
+ }
1183
+ break;
1184
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
1185
+ }
1186
+ else switch (op) {
1187
+ case "eq":
1188
+ if (operand === null) frag = sql`${col} IS NULL`;
1189
+ else if (typeof operand === "string") frag = sql`${col} = ${operand}`;
1190
+ break;
1191
+ case "neq":
1192
+ if (operand === null) frag = sql`${col} IS NOT NULL`;
1193
+ else if (typeof operand === "string") frag = sql`${col} IS DISTINCT FROM ${operand}`;
1194
+ break;
1195
+ case "in":
1196
+ case "nin":
1197
+ if (Array.isArray(operand)) {
1198
+ const member = memberOf(sql, col, sql`${operand.filter((v) => typeof v === "string")}::text[]`, operand);
1199
+ frag = op === "in" ? member : sql`NOT ${member}`;
1200
+ }
1201
+ break;
1202
+ case "contains":
1203
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}%`}`;
1204
+ break;
1205
+ case "startsWith":
1206
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`${escapeLike(operand)}%`}`;
1207
+ break;
1208
+ case "endsWith":
1209
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}`}`;
1210
+ break;
1211
+ case "gt":
1212
+ frag = sql`${col} > ${metaStr(field, op, operand)}`;
1213
+ break;
1214
+ case "gte":
1215
+ frag = sql`${col} >= ${metaStr(field, op, operand)}`;
1216
+ break;
1217
+ case "lt":
1218
+ frag = sql`${col} < ${metaStr(field, op, operand)}`;
1219
+ break;
1220
+ case "lte":
1221
+ frag = sql`${col} <= ${metaStr(field, op, operand)}`;
1222
+ break;
1223
+ case "between":
1224
+ if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
1225
+ frag = sql`${col} BETWEEN ${metaStr(field, op, operand[0])} AND ${metaStr(field, op, operand[1])}`;
1226
+ break;
1227
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
1228
+ }
1229
+ if (frag !== null) fragments.push(frag);
1230
+ }
1231
+ if (fragments.length === 0) return null;
1232
+ return combineAnd(sql, fragments);
1233
+ }
1234
+ /**
1235
+ * Membership of `col` in `operand`, never NULL: an empty list matches nothing,
1236
+ * and a null element matches a null column, as the memory evaluator does.
1237
+ */
1238
+ function memberOf(sql, col, values, operand) {
1239
+ const parts = [sql`COALESCE(${col} = ANY(${values}), FALSE)`];
1240
+ if (operand.includes(null)) parts.push(sql`${col} IS NULL`);
1241
+ return combineOr(sql, parts);
1242
+ }
1243
+
1244
+ //#endregion
1245
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-promoted.ts
1246
+ /**
1247
+ * WHERE predicates against body-promoted columns. These read the column
1248
+ * ONLY, with no body fallback — see `PgDatasetOptions.promotedColumns`.
1249
+ */
1250
+ /**
1251
+ * Builds the WHERE predicate for a promoted column. Returns null for an empty
1252
+ * predicate; throws `UnsupportedFilterError` on an unknown operator or a
1253
+ * wrong-typed operand.
1254
+ *
1255
+ * Per value V: `col = V::T`, or `col IS NULL` when V is null. `in` / `nin`
1256
+ * OR/AND the per-value predicates.
1257
+ */
1258
+ function buildPromotedBodyColumnPredicate(sql, field, meta, predicate) {
1259
+ const col = sql.unsafe(promotedColumnSql(meta));
1260
+ const isBool = meta.kind === "boolean";
1261
+ const fragments = [];
1262
+ /** Operand-shape guard. A wrong-typed operand is a caller error, not a non-match. */
1263
+ const str = (op, v) => {
1264
+ if (typeof v !== "string") throw new UnsupportedFilterError(field, op, `requires a string value on a ${meta.kind} column`);
1265
+ return v;
1266
+ };
1267
+ const singleEq = (value) => {
1268
+ if (value === null) return sql`${col} IS NULL`;
1269
+ if (isBool) {
1270
+ if (typeof value !== "boolean") throw new UnsupportedFilterError(field, "eq", "requires a boolean value");
1271
+ return sql`${col} = ${value}::boolean`;
1272
+ }
1273
+ return sql`${col} = ${str("eq", value)}::text`;
1274
+ };
1275
+ /**
1276
+ * `neq` ADMITS NULLs, matching the body path and the memory substrate, so
1277
+ * `eq` and `neq` partition the rows. `neq: null` is the is-not-null filter.
1278
+ */
1279
+ const singleNeq = (value) => {
1280
+ if (value === null) return sql`${col} IS NOT NULL`;
1281
+ if (isBool) {
1282
+ if (typeof value !== "boolean") throw new UnsupportedFilterError(field, "neq", "requires a boolean value");
1283
+ return sql`${col} IS DISTINCT FROM ${value}::boolean`;
1284
+ }
1285
+ return sql`${col} IS DISTINCT FROM ${str("neq", value)}::text`;
1286
+ };
1287
+ /**
1288
+ * Range / pattern operators are text-column only; throws on a boolean column.
1289
+ */
1290
+ const textOnly = (op) => {
1291
+ if (isBool) throw new UnsupportedFilterError(field, op, `is not applicable to a boolean column`);
1292
+ };
1293
+ for (const [op, operand] of Object.entries(predicate)) {
1294
+ let frag;
1295
+ switch (op) {
1296
+ case "eq":
1297
+ frag = singleEq(operand);
1298
+ break;
1299
+ case "neq":
1300
+ frag = singleNeq(operand);
1301
+ break;
1302
+ case "in":
1303
+ if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
1304
+ if (operand.length === 0) {
1305
+ frag = sql`FALSE`;
1306
+ break;
1307
+ }
1308
+ frag = combineOr(sql, operand.map(singleEq));
1309
+ break;
1310
+ case "nin":
1311
+ if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
1312
+ if (operand.length === 0) {
1313
+ frag = sql`TRUE`;
1314
+ break;
1315
+ }
1316
+ frag = combineAnd(sql, operand.map(singleNeq));
1317
+ break;
1318
+ case "gt":
1319
+ textOnly(op);
1320
+ frag = sql`${col} > ${str(op, operand)}::text`;
1321
+ break;
1322
+ case "gte":
1323
+ textOnly(op);
1324
+ frag = sql`${col} >= ${str(op, operand)}::text`;
1325
+ break;
1326
+ case "lt":
1327
+ textOnly(op);
1328
+ frag = sql`${col} < ${str(op, operand)}::text`;
1329
+ break;
1330
+ case "lte":
1331
+ textOnly(op);
1332
+ frag = sql`${col} <= ${str(op, operand)}::text`;
1333
+ break;
1334
+ case "between":
1335
+ textOnly(op);
1336
+ if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
1337
+ frag = sql`${col} BETWEEN ${str(op, operand[0])}::text AND ${str(op, operand[1])}::text`;
1338
+ break;
1339
+ case "contains":
1340
+ textOnly(op);
1341
+ frag = sql`${col} ILIKE ${`%${escapeLike(str(op, operand))}%`}`;
1342
+ break;
1343
+ case "startsWith":
1344
+ textOnly(op);
1345
+ frag = sql`${col} ILIKE ${`${escapeLike(str(op, operand))}%`}`;
1346
+ break;
1347
+ case "endsWith":
1348
+ textOnly(op);
1349
+ frag = sql`${col} ILIKE ${`%${escapeLike(str(op, operand))}`}`;
1350
+ break;
1351
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
1352
+ }
1353
+ fragments.push(frag);
1354
+ }
1355
+ if (fragments.length === 0) return null;
1356
+ return combineAnd(sql, fragments);
1357
+ }
1358
+
1359
+ //#endregion
1360
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/where.ts
1361
+ /**
1362
+ * WHERE-clause → SQL translation: logical combinators, per-field predicate
1363
+ * dispatch (id / shortId / metadata / promoted-column / body-path), the
1364
+ * operator-fragment compiler, and the `conditionalUpdate` match fragment.
1365
+ */
1366
+ function buildWhere(sql, where, castFor, promotedFor) {
1367
+ if (where === null || typeof where !== "object" || Array.isArray(where)) return null;
1368
+ const keys = Object.keys(where);
1369
+ if (keys.length === 0) return null;
1370
+ const fragments = [];
1371
+ for (const k of keys) {
1372
+ const child = where[k];
1373
+ if (k === "AND" || k === "OR") {
1374
+ if (!Array.isArray(child)) continue;
1375
+ const subs = [];
1376
+ for (const sub of child) {
1377
+ const frag = buildWhere(sql, sub, castFor, promotedFor);
1378
+ if (frag !== null) subs.push(frag);
1379
+ }
1380
+ if (subs.length > 0) fragments.push(k === "AND" ? combineAnd(sql, subs) : combineOr(sql, subs));
1381
+ } else if (k === "NOT") {
1382
+ const inner = buildWhere(sql, child, castFor, promotedFor);
1383
+ if (inner !== null) fragments.push(sql`NOT (${inner})`);
1384
+ } else {
1385
+ const frag = buildFieldPredicate(sql, k, child, castFor, promotedFor);
1386
+ if (frag !== null) fragments.push(frag);
1387
+ }
1388
+ }
1389
+ if (fragments.length === 0) return null;
1390
+ return combineAnd(sql, fragments);
1391
+ }
1392
+ function buildFieldPredicate(sql, field, predicate, castFor, promotedFor) {
1393
+ if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) throw new UnsupportedFilterError(field, "<none>", `expected a predicate object such as { eq: ... }, got ${Array.isArray(predicate) ? "an array" : typeof predicate}`);
1394
+ if (field === "id") return buildIdPredicate(sql, predicate);
1395
+ if (field === "shortId") return buildShortIdPredicate(sql, predicate);
1396
+ if (isMetadataField(field)) return buildMetadataColumnPredicate(sql, field, predicate);
1397
+ const promotedField = promotedFor(field);
1398
+ if (promotedField !== void 0) return buildPromotedBodyColumnPredicate(sql, field, promotedField, predicate);
1399
+ if (isJsonPathPredicate(predicate)) return buildJsonPathPredicate(sql, field, predicate);
1400
+ return buildFieldPredicateForPath(sql, [field], predicate, castFor);
1401
+ }
1402
+ function buildFieldPredicateForPath(sql, path, predicate, castFor) {
1403
+ const field = path.join(".");
1404
+ const entries = Object.entries(predicate);
1405
+ if (entries.length > 0 && !entries.some(([k]) => KNOWN_BODY_OPS.has(k)) && entries.every(([, v]) => v !== null && typeof v === "object" && !Array.isArray(v))) {
1406
+ const subs = [];
1407
+ for (const [subField, subPredicate] of entries) {
1408
+ const frag = buildBodyPathPredicate(sql, [...path, subField], subPredicate, castFor);
1409
+ if (frag !== null) subs.push(frag);
1410
+ }
1411
+ if (subs.length === 0) return null;
1412
+ return combineAnd(sql, subs);
1413
+ }
1414
+ const declaredCast = path.length === 1 ? castFor(field) : null;
1415
+ const fragments = [];
1416
+ for (const [op, operand] of entries) {
1417
+ const frag = buildOpFragment(sql, path, op, operand, declaredCast);
1418
+ if (frag !== null) fragments.push(frag);
1419
+ }
1420
+ if (fragments.length === 0) return null;
1421
+ return combineAnd(sql, fragments);
1422
+ }
1423
+ /**
1424
+ * Operators the generic body compiler recognises. Used only to tell an operator
1425
+ * predicate from a nested-struct sub-clause; the authoritative per-operator
1426
+ * handling is `buildOpFragment`'s switch.
1427
+ */
1428
+ const KNOWN_BODY_OPS = /* @__PURE__ */ new Set([
1429
+ "eq",
1430
+ "neq",
1431
+ "gt",
1432
+ "gte",
1433
+ "lt",
1434
+ "lte",
1435
+ "between",
1436
+ "in",
1437
+ "nin",
1438
+ "contains",
1439
+ "startsWith",
1440
+ "endsWith",
1441
+ "has"
1442
+ ]);
1443
+ /** Recurse into a struct sub-clause, carrying the accumulated body path. */
1444
+ function buildBodyPathPredicate(sql, path, predicate, castFor) {
1445
+ if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) throw new UnsupportedFilterError(path.join("."), "<none>", `expected a predicate object such as { eq: ... }, got ${Array.isArray(predicate) ? "an array" : typeof predicate}`);
1446
+ return buildFieldPredicateForPath(sql, path, predicate, castFor);
1447
+ }
1448
+ /**
1449
+ * Build WHERE predicates against the native `id` column (the row PK).
1450
+ *
1451
+ * Range operators compare the text ids lexicographically. Numeric ids
1452
+ * stringify cleanly.
1453
+ */
1454
+ function buildIdPredicate(sql, predicate) {
1455
+ const fragments = [];
1456
+ for (const [op, operand] of Object.entries(predicate)) {
1457
+ let frag = null;
1458
+ switch (op) {
1459
+ case "eq":
1460
+ if (operand === null || operand === void 0) frag = sql`id IS NULL`;
1461
+ else frag = sql`id = ${idToText(operand)}`;
1462
+ break;
1463
+ case "neq":
1464
+ if (operand === null || operand === void 0) frag = sql`id IS NOT NULL`;
1465
+ else frag = sql`id IS DISTINCT FROM ${idToText(operand)}`;
1466
+ break;
1467
+ case "in":
1468
+ if (Array.isArray(operand) && operand.length > 0) frag = sql`id IN ${sql(operand.map((v) => idToText(v)))}`;
1469
+ else if (Array.isArray(operand) && operand.length === 0) frag = sql`FALSE`;
1470
+ break;
1471
+ case "nin":
1472
+ if (Array.isArray(operand) && operand.length > 0) frag = sql`id NOT IN ${sql(operand.map((v) => idToText(v)))}`;
1473
+ break;
1474
+ case "contains":
1475
+ if (typeof operand === "string") frag = sql`id ILIKE ${`%${escapeLike(operand)}%`}`;
1476
+ break;
1477
+ case "startsWith":
1478
+ if (typeof operand === "string") frag = sql`id ILIKE ${`${escapeLike(operand)}%`}`;
1479
+ break;
1480
+ case "endsWith":
1481
+ if (typeof operand === "string") frag = sql`id ILIKE ${`%${escapeLike(operand)}`}`;
1482
+ break;
1483
+ case "gt":
1484
+ frag = sql`id > ${metaStr("id", op, operand)}`;
1485
+ break;
1486
+ case "gte":
1487
+ frag = sql`id >= ${metaStr("id", op, operand)}`;
1488
+ break;
1489
+ case "lt":
1490
+ frag = sql`id < ${metaStr("id", op, operand)}`;
1491
+ break;
1492
+ case "lte":
1493
+ frag = sql`id <= ${metaStr("id", op, operand)}`;
1494
+ break;
1495
+ case "between":
1496
+ if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError("id", op, "requires a two-element [low, high] array");
1497
+ frag = sql`id BETWEEN ${metaStr("id", op, operand[0])} AND ${metaStr("id", op, operand[1])}`;
1498
+ break;
1499
+ default: throw new UnsupportedFilterError("id", op, "is not a recognised filter operator");
1500
+ }
1501
+ if (frag !== null) fragments.push(frag);
1502
+ }
1503
+ if (fragments.length === 0) return null;
1504
+ return combineAnd(sql, fragments);
1505
+ }
1506
+ /** Operand-shape guards for the numeric shortId column: anything else is refused, never dropped. */
1507
+ function num(field, op, v) {
1508
+ if (typeof v !== "number") throw new UnsupportedFilterError(field, op, "requires a number");
1509
+ return v;
1510
+ }
1511
+ function numArray(field, op, v) {
1512
+ if (!Array.isArray(v) || v.some((e) => typeof e !== "number")) throw new UnsupportedFilterError(field, op, "requires an array of numbers");
1513
+ return v;
1514
+ }
1515
+ /** Build WHERE predicates against `s.short_id` (the LEFT-joined sidecar column). */
1516
+ function buildShortIdPredicate(sql, predicate) {
1517
+ const col = sql`s.short_id`;
1518
+ const fragments = [];
1519
+ for (const [op, operand] of Object.entries(predicate)) {
1520
+ let frag = null;
1521
+ switch (op) {
1522
+ case "eq":
1523
+ frag = sql`${col} = ${num("shortId", op, operand)}`;
1524
+ break;
1525
+ case "neq":
1526
+ frag = sql`${col} IS DISTINCT FROM ${num("shortId", op, operand)}`;
1527
+ break;
1528
+ case "gt":
1529
+ frag = sql`${col} > ${num("shortId", op, operand)}`;
1530
+ break;
1531
+ case "gte":
1532
+ frag = sql`${col} >= ${num("shortId", op, operand)}`;
1533
+ break;
1534
+ case "lt":
1535
+ frag = sql`${col} < ${num("shortId", op, operand)}`;
1536
+ break;
1537
+ case "lte":
1538
+ frag = sql`${col} <= ${num("shortId", op, operand)}`;
1539
+ break;
1540
+ case "between": {
1541
+ const range = numArray("shortId", op, operand);
1542
+ if (range.length !== 2) throw new UnsupportedFilterError("shortId", op, "requires a two-element [low, high] array");
1543
+ frag = sql`${col} BETWEEN ${range[0]} AND ${range[1]}`;
1544
+ break;
1545
+ }
1546
+ case "in":
1547
+ frag = numArray("shortId", op, operand).length === 0 ? sql`FALSE` : sql`${col} = ANY(${numArray("shortId", op, operand)})`;
1548
+ break;
1549
+ case "nin":
1550
+ frag = numArray("shortId", op, operand).length === 0 ? sql`TRUE` : sql`${col} <> ALL(${numArray("shortId", op, operand)})`;
1551
+ break;
1552
+ default: throw new UnsupportedFilterError("shortId", op, "is not a recognised filter operator");
1553
+ }
1554
+ if (frag !== null) fragments.push(frag);
1555
+ }
1556
+ if (fragments.length === 0) return null;
1557
+ return combineAnd(sql, fragments);
1558
+ }
1559
+ /**
1560
+ * Build a single SQL comparison for (field, op, operand). Values come from
1561
+ * callers (attacker-controlled in principle) so every operand MUST be passed
1562
+ * through a parameterised slot. `sql.unsafe()` is deliberately avoided.
1563
+ *
1564
+ * Case-sensitivity note (design call): `contains` / `startsWith` / `endsWith`
1565
+ * use ILIKE for case-INSENSITIVE matching. Memory dataset mirrors this.
1566
+ */
1567
+ /**
1568
+ * `body ->> 'a'` for one segment, `body -> 'a' -> 'b' ->> 'c'` for a path.
1569
+ * Segments are parameterised, never concatenated.
1570
+ */
1571
+ function buildBodyTextExpr(sql, path) {
1572
+ let expr = sql`body`;
1573
+ for (let i = 0; i < path.length - 1; i++) expr = sql`${expr} -> ${path[i]}`;
1574
+ return sql`(${expr} ->> ${path[path.length - 1]})`;
1575
+ }
1576
+ /** Same walk, but landing on `->` so the leaf stays jsonb (for `@>` containment). */
1577
+ function buildBodyJsonExpr(sql, path) {
1578
+ let expr = sql`body`;
1579
+ for (const seg of path) expr = sql`${expr} -> ${seg}`;
1580
+ return sql`(${expr})`;
1581
+ }
1582
+ function buildOpFragment(sql, path, op, operand, declaredCast) {
1583
+ const field = path.join(".");
1584
+ const textExpr = buildBodyTextExpr(sql, path);
1585
+ const jsonExpr = buildBodyJsonExpr(sql, path);
1586
+ const num = sql`(${textExpr})::numeric`;
1587
+ const isTs = (v) => v instanceof Date || declaredCast === "timestamptz" && typeof v === "string";
1588
+ const tsIso = (v) => v instanceof Date ? v.toISOString() : String(v);
1589
+ const anyOf = (values) => {
1590
+ const nums = values.filter((v) => typeof v === "number");
1591
+ const rest = values.filter((v) => typeof v !== "number");
1592
+ const parts = [];
1593
+ if (nums.length > 0) parts.push(ifJsonNumber(sql, jsonExpr, sql`${num} = ANY(${nums})`));
1594
+ if (rest.length > 0) parts.push(isTs(rest[0]) ? sql`COALESCE((${textExpr})::timestamptz = ANY(${rest.map(tsIso)}), FALSE)` : sql`COALESCE(${textExpr} = ANY(${rest.map(scalarParam)}), FALSE)`);
1595
+ return combineOr(sql, parts);
1596
+ };
1597
+ switch (op) {
1598
+ case "eq":
1599
+ if (operand === null) return sql`${textExpr} IS NULL`;
1600
+ if (typeof operand === "boolean") return sql`${textExpr} = ${operand ? "true" : "false"}`;
1601
+ if (typeof operand === "number") return ifJsonNumber(sql, jsonExpr, sql`${num} = ${operand}`);
1602
+ if (isTs(operand)) return sql`(${textExpr})::timestamptz = ${tsIso(operand)}`;
1603
+ return sql`${textExpr} = ${scalarParam(operand)}`;
1604
+ case "neq":
1605
+ if (operand === null) return sql`${textExpr} IS NOT NULL`;
1606
+ if (typeof operand === "boolean") return sql`${textExpr} IS DISTINCT FROM ${operand ? "true" : "false"}`;
1607
+ if (typeof operand === "number") return sql`NOT ${ifJsonNumber(sql, jsonExpr, sql`${num} = ${operand}`)}`;
1608
+ if (isTs(operand)) return sql`(${textExpr})::timestamptz IS DISTINCT FROM ${tsIso(operand)}`;
1609
+ return sql`${textExpr} IS DISTINCT FROM ${scalarParam(operand)}`;
1610
+ case "gt": return numericCmp(sql, field, textExpr, jsonExpr, operand, ">", declaredCast);
1611
+ case "gte": return numericCmp(sql, field, textExpr, jsonExpr, operand, ">=", declaredCast);
1612
+ case "lt": return numericCmp(sql, field, textExpr, jsonExpr, operand, "<", declaredCast);
1613
+ case "lte": return numericCmp(sql, field, textExpr, jsonExpr, operand, "<=", declaredCast);
1614
+ case "between": {
1615
+ if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
1616
+ const low = operand[0];
1617
+ const high = operand[1];
1618
+ if (typeof low === "number" && typeof high === "number") return ifJsonNumber(sql, jsonExpr, sql`${num} BETWEEN ${low} AND ${high}`);
1619
+ if (isTs(low) || isTs(high)) return sql`(${textExpr})::timestamptz BETWEEN ${tsIso(low)} AND ${tsIso(high)}`;
1620
+ return sql`${textExpr} COLLATE "C" BETWEEN ${scalarParam(low)} AND ${scalarParam(high)}`;
1621
+ }
1622
+ case "in": {
1623
+ if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
1624
+ const values = operand.filter((v) => v !== null && v !== void 0);
1625
+ const wantsNull = values.length < operand.length;
1626
+ const any = values.length === 0 ? sql`FALSE` : anyOf(values);
1627
+ return wantsNull ? sql`(${any} OR ${textExpr} IS NULL)` : any;
1628
+ }
1629
+ case "nin": {
1630
+ if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
1631
+ if (operand.length === 0) return sql`TRUE`;
1632
+ const values = operand.filter((v) => v !== null && v !== void 0);
1633
+ if (values.length < operand.length) {
1634
+ if (values.length === 0) return sql`${textExpr} IS NOT NULL`;
1635
+ return sql`(${textExpr} IS NOT NULL AND NOT ${anyOf(values)})`;
1636
+ }
1637
+ return sql`(${textExpr} IS NULL OR NOT ${anyOf(values)})`;
1638
+ }
1639
+ case "contains":
1640
+ if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
1641
+ return sql`${textExpr} ILIKE ${`%${escapeLike(operand)}%`}`;
1642
+ case "startsWith":
1643
+ if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
1644
+ return sql`${textExpr} ILIKE ${`${escapeLike(operand)}%`}`;
1645
+ case "endsWith":
1646
+ if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
1647
+ return sql`${textExpr} ILIKE ${`%${escapeLike(operand)}`}`;
1648
+ case "has": {
1649
+ const elem = operand instanceof Date ? operand.toISOString() : operand;
1650
+ return sql`${buildBodyJsonExpr(sql, path)} @> ${sql.json(asJsonValue([elem]))}`;
1651
+ }
1652
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
1653
+ }
1654
+ }
1655
+ /**
1656
+ * `cond` only where the jsonb value is a number, else FALSE. CASE because SQL
1657
+ * does not promise AND short-circuits, so one non-numeric value could still
1658
+ * reach `::numeric` and abort the whole query; COALESCE so a mismatch is
1659
+ * FALSE, never NULL under a caller's NOT.
1660
+ */
1661
+ function ifJsonNumber(sql, jsonExpr, cond) {
1662
+ return sql`COALESCE(CASE WHEN jsonb_typeof(${jsonExpr}) = 'number' THEN ${cond} END, FALSE)`;
1663
+ }
1664
+ /**
1665
+ * Compare `(body ->> field)` with a cast appropriate to the value. Numbers use
1666
+ * `::numeric`, Dates (or ISO-string operands on a `date`-declared field) use
1667
+ * `::timestamptz`, plain strings use text.
1668
+ */
1669
+ function numericCmp(sql, field, textExpr, jsonExpr, operand, cmp, declaredCast) {
1670
+ if (typeof operand === "number") {
1671
+ const n = sql`(${textExpr})::numeric`;
1672
+ switch (cmp) {
1673
+ case ">": return ifJsonNumber(sql, jsonExpr, sql`${n} > ${operand}`);
1674
+ case ">=": return ifJsonNumber(sql, jsonExpr, sql`${n} >= ${operand}`);
1675
+ case "<": return ifJsonNumber(sql, jsonExpr, sql`${n} < ${operand}`);
1676
+ case "<=": return ifJsonNumber(sql, jsonExpr, sql`${n} <= ${operand}`);
1677
+ }
1678
+ }
1679
+ if (operand instanceof Date || declaredCast === "timestamptz" && typeof operand === "string") {
1680
+ const iso = operand instanceof Date ? operand.toISOString() : String(operand);
1681
+ switch (cmp) {
1682
+ case ">": return sql`(${textExpr})::timestamptz > ${iso}`;
1683
+ case ">=": return sql`(${textExpr})::timestamptz >= ${iso}`;
1684
+ case "<": return sql`(${textExpr})::timestamptz < ${iso}`;
1685
+ case "<=": return sql`(${textExpr})::timestamptz <= ${iso}`;
1686
+ }
1687
+ }
1688
+ if (typeof operand === "string") {
1689
+ const s = sql`${textExpr} COLLATE "C"`;
1690
+ switch (cmp) {
1691
+ case ">": return sql`${s} > ${operand}`;
1692
+ case ">=": return sql`${s} >= ${operand}`;
1693
+ case "<": return sql`${s} < ${operand}`;
1694
+ case "<=": return sql`${s} <= ${operand}`;
1695
+ }
1696
+ }
1697
+ throw new UnsupportedFilterError(field, cmp, `cannot compare against a ${operand === null ? "null" : typeof operand} value`);
1698
+ }
1699
+ /**
1700
+ * Predicate fragment used by `conditionalUpdate`. Mirrors the equality rules
1701
+ * of `read()`'s `eq` operator so a `conditionalUpdate({ consumedAt: null })`
1702
+ * matches the same rows a subsequent `read({ where: { consumedAt: { eq: null } } })`
1703
+ * would. `null` maps to `IS NULL`; `Date` is compared on the `::timestamptz`
1704
+ * cast of the extracted text; scalars compare via the textual representation
1705
+ * pg's JSONB `->>` operator returns.
1706
+ */
1707
+ function conditionalMatchFragment(sql, field, expected) {
1708
+ const textExpr = sql`(body ->> ${field})`;
1709
+ if (expected === null || expected === void 0) return sql`${textExpr} IS NULL`;
1710
+ if (typeof expected === "boolean") return sql`${textExpr} = ${expected ? "true" : "false"}`;
1711
+ if (typeof expected === "number") return ifJsonNumber(sql, sql`(body -> ${field})`, sql`(${textExpr})::numeric = ${expected}`);
1712
+ if (expected instanceof Date) return sql`(${textExpr})::timestamptz = ${expected.toISOString()}`;
1713
+ return sql`${textExpr} = ${String(expected)}`;
1714
+ }
1715
+
1716
+ //#endregion
1717
+ //#region ../../packages/substrate-dataset-pg/src/tx-scope.ts
1718
+ /**
1719
+ * Substrate identity for pg-backed stores: stores built on the same
1720
+ * `postgres.Sql` pool reference share a `txScopeId`, which lets the engine
1721
+ * run their mutations in one transaction.
1722
+ *
1723
+ * Keyed by `Sql` reference, not connection options: two pools on the same
1724
+ * database cannot share a transaction, so they are distinct substrates.
1725
+ * `TransactionSql` handles inherit their parent's id via constructor options.
1726
+ */
1727
+ const SUBSTRATE_IDS = /* @__PURE__ */ new WeakMap();
1728
+ function txScopeIdFor(sql) {
1729
+ const existing = SUBSTRATE_IDS.get(sql);
1730
+ if (existing !== void 0) return existing;
1731
+ const id = `pg:${randomUUID()}`;
1732
+ SUBSTRATE_IDS.set(sql, id);
1733
+ return id;
1734
+ }
1735
+
1736
+ //#endregion
1737
+ //#region ../../packages/substrate-dataset-pg/src/pg-dataset.ts
1738
+ /**
1739
+ * PgDataset — PostgreSQL-backed reference implementation of Dataset.
1740
+ * Spec: §4.5, §5.2.
1741
+ *
1742
+ * One instance per namespace; rows live in a single `rows` table keyed
1743
+ * by (namespace, type, id). The caller owns the `postgres` Sql connection —
1744
+ * this class never opens or closes pools.
1745
+ *
1746
+ * Reserved field policy (mirrors MemoryDataset):
1747
+ * - `_deletedAt` is managed exclusively by tombstone() / purge().
1748
+ * - write() strips `_deletedAt` (including explicit null) from inputs before
1749
+ * persisting; the column is the only source of truth on read.
1750
+ * - updateField() with fieldName === '_deletedAt' throws ReservedField.
1751
+ *
1752
+ * Id-type preservation: `Id` is `string | number`. The PK column is `text`
1753
+ * (so we can coerce either shape through one column), but the *original*
1754
+ * runtime type is mirrored inside `body.id` during write() and read back out
1755
+ * of the body on read() — this keeps numeric ids round-tripping as numbers.
1756
+ *
1757
+ * Filter contract (§5.2): where / orderBy / cursor are translated to SQL via
1758
+ * postgres.js tagged templates — every caller-supplied value goes through
1759
+ * parameterised interpolation. Never string-concatenate user input into the
1760
+ * clause; that's the one SQL-injection surface in this file.
1761
+ */
1762
+ const RESERVED_DELETED_AT = "_deletedAt";
1763
+ var PgDataset = class PgDataset {
1764
+ namespace;
1765
+ capabilities = {
1766
+ operators: fullBuiltinOperators(),
1767
+ orderBy: true,
1768
+ cursor: true
1769
+ };
1770
+ txScopeId;
1771
+ #sql;
1772
+ #inTx;
1773
+ #shortIds;
1774
+ #edgesStore;
1775
+ /** Stored so tx-bound and forNamespace clones inherit it. */
1776
+ #fieldDefLookup;
1777
+ /**
1778
+ * Validated once at construction. The raw map is kept so clones inherit it
1779
+ * rather than reverting to the default.
1780
+ */
1781
+ #promotedColumns;
1782
+ #promotedFor;
1783
+ constructor(options) {
1784
+ this.namespace = options.namespace;
1785
+ this.#sql = options.sql;
1786
+ this.#inTx = "inTx" in options ? options.inTx : false;
1787
+ const explicit = "txScopeId" in options ? options.txScopeId : void 0;
1788
+ this.txScopeId = explicit ?? txScopeIdFor(options.sql);
1789
+ this.#shortIds = new PgShortIdStore(this.#sql);
1790
+ const edgesOpt = options.edgesStore;
1791
+ if (edgesOpt !== void 0 && edgesOpt.txScopeId !== this.txScopeId) throw new Error(`PgDataset: edgesStore txScopeId '${edgesOpt.txScopeId}' does not match dataset txScopeId '${this.txScopeId}' — both must wrap the same Sql pool`);
1792
+ this.#edgesStore = edgesOpt ?? null;
1793
+ this.#fieldDefLookup = options.fieldDefLookup ?? null;
1794
+ this.#promotedColumns = options.promotedColumns ?? {};
1795
+ this.#promotedFor = resolvePromotedColumns(this.#promotedColumns);
1796
+ }
1797
+ /**
1798
+ * Reads rows of `type` per the §5.2 filter contract (where / orderBy /
1799
+ * cursor / limit). Every value is bound through a parameterised slot.
1800
+ *
1801
+ * Body values extract as text and are cast for comparison only; the filter
1802
+ * validator has already rejected type mismatches.
1803
+ */
1804
+ async read(type, params) {
1805
+ const sql = this.#sql;
1806
+ const includeDeleted = params.includeDeleted === true;
1807
+ const limit = typeof params.limit === "number" && Number.isFinite(params.limit) && params.limit >= 0 ? Math.floor(params.limit) : void 0;
1808
+ if (limit === 0) return {
1809
+ rows: [],
1810
+ hasMore: false
1811
+ };
1812
+ const idList = [];
1813
+ let hasIdFilter = false;
1814
+ if (params.id !== void 0) {
1815
+ idList.push(idToText(params.id));
1816
+ hasIdFilter = true;
1817
+ }
1818
+ if (params.ids !== void 0) {
1819
+ for (const id of params.ids) idList.push(idToText(id));
1820
+ hasIdFilter = true;
1821
+ }
1822
+ const clauses = [];
1823
+ clauses.push(sql`r.namespace = ${this.namespace}`);
1824
+ clauses.push(sql`r.type = ${type}`);
1825
+ if (hasIdFilter) clauses.push(sql`r.id = ANY(${idList})`);
1826
+ if (!includeDeleted) clauses.push(sql`r.deleted_at IS NULL`);
1827
+ const bodyCastFor = (field) => {
1828
+ if (this.#fieldDefLookup === null) return null;
1829
+ return resolveBodyOrderByCast(this.#fieldDefLookup(type, field));
1830
+ };
1831
+ let extMeta = null;
1832
+ if (params.where !== void 0) {
1833
+ const detailed = await preResolveExtensionOperatorsDetailed(params.where, {
1834
+ namespace: this.namespace,
1835
+ type,
1836
+ k: limit,
1837
+ ...fieldRequested(params.fields, "_vector") ? { returnVector: true } : {}
1838
+ });
1839
+ extMeta = detailed.meta;
1840
+ const whereFragment = buildWhere(sql, detailed.where, bodyCastFor, this.#promotedFor);
1841
+ if (whereFragment !== null) clauses.push(whereFragment);
1842
+ }
1843
+ const orderBy = normalizeOrderBy(params.orderBy);
1844
+ const orderByCastFor = bodyCastFor;
1845
+ if (params.cursor !== void 0 && params.cursor !== "") {
1846
+ const cursor = decodeCursor(params.cursor);
1847
+ const cursorFragment = buildCursorCompare(sql, orderBy, cursor.orderByValues, cursor.id, orderByCastFor, this.#promotedFor);
1848
+ if (cursorFragment !== null) clauses.push(cursorFragment);
1849
+ }
1850
+ const whereSql = combineAnd(sql, clauses);
1851
+ const orderBySql = buildOrderBy(sql, orderBy, orderByCastFor, this.#promotedFor);
1852
+ const fetchLimit = limit !== void 0 ? limit + 1 : void 0;
1853
+ const bodyProjection = buildBodyProjection(sql, params.fields);
1854
+ const { fragment: sortKeyProjection, aliases: sortKeyAliases } = buildSortKeyProjection(sql, orderBy, bodyCastFor, this.#promotedFor);
1855
+ const rows = await sql`
1856
+ SELECT r.id, ${bodyProjection} AS body, r.deleted_at, s.short_id,
1857
+ r.created_at, r.updated_at,
1858
+ r.created_by_kind, r.created_by_id,
1859
+ r.updated_by_kind, r.updated_by_id${sortKeyProjection}
1860
+ FROM rows r
1861
+ LEFT JOIN short_ids s
1862
+ ON s.namespace = r.namespace
1863
+ AND s.type = r.type
1864
+ AND s.row_id = r.id
1865
+ WHERE ${whereSql}
1866
+ ${orderBySql}
1867
+ ${fetchLimit !== void 0 ? sql`LIMIT ${fetchLimit}` : sql``}
1868
+ `;
1869
+ const materialised = rows.map((r) => this.materialize(r));
1870
+ let hasMore = false;
1871
+ let sliced = materialised;
1872
+ if (limit !== void 0 && materialised.length > limit) {
1873
+ hasMore = true;
1874
+ sliced = materialised.slice(0, limit);
1875
+ }
1876
+ const out = {
1877
+ rows: sliced,
1878
+ hasMore
1879
+ };
1880
+ const last = sliced[sliced.length - 1];
1881
+ const lastRaw = rows[sliced.length - 1];
1882
+ if (hasMore && last !== void 0) out.nextCursor = encodeCursor({
1883
+ orderByValues: orderBy.filter(([f]) => f !== "id").map(([field]) => {
1884
+ const alias = sortKeyAliases.get(field);
1885
+ return alias === void 0 ? null : lastRaw?.[alias] ?? null;
1886
+ }),
1887
+ id: last.id
1888
+ });
1889
+ if (extMeta !== null) out.rows = applyExtensionResultMeta(out.rows, extMeta, {
1890
+ hasExplicitOrderBy: params.orderBy !== void 0 && params.orderBy.length > 0,
1891
+ fields: params.fields
1892
+ });
1893
+ return out;
1894
+ }
1895
+ async write(type, rows, options) {
1896
+ const ids = [];
1897
+ if (rows.length === 0) return {
1898
+ written: 0,
1899
+ ids,
1900
+ rows: []
1901
+ };
1902
+ const sql = this.#sql;
1903
+ const fallbackNow = (options?.now ?? /* @__PURE__ */ new Date()).toISOString();
1904
+ const fallbackActor = options?.identity ?? null;
1905
+ const namespaces = [];
1906
+ const types = [];
1907
+ const idsCol = [];
1908
+ const bodies = [];
1909
+ const createdAts = [];
1910
+ const updatedAts = [];
1911
+ const createdByKinds = [];
1912
+ const createdByIds = [];
1913
+ const updatedByKinds = [];
1914
+ const updatedByIds = [];
1915
+ for (const row of rows) {
1916
+ if (row.id === void 0 || row.id === null) throw new Error(`write: row.id is required (type='${type}')`);
1917
+ const meta = row._metadata ?? {
1918
+ createdAt: fallbackNow,
1919
+ updatedAt: fallbackNow,
1920
+ createdBy: fallbackActor,
1921
+ updatedBy: fallbackActor
1922
+ };
1923
+ const sanitised = { id: row.id };
1924
+ for (const [k, v] of Object.entries(row)) {
1925
+ if (k === RESERVED_DELETED_AT) continue;
1926
+ if (k === "_metadata") continue;
1927
+ if (k === "id") continue;
1928
+ sanitised[k] = v;
1929
+ }
1930
+ ids.push(row.id);
1931
+ namespaces.push(this.namespace);
1932
+ types.push(type);
1933
+ idsCol.push(idToText(row.id));
1934
+ bodies.push(JSON.stringify(sanitised));
1935
+ createdAts.push(meta.createdAt);
1936
+ updatedAts.push(meta.updatedAt);
1937
+ createdByKinds.push(meta.createdBy?.kind ?? null);
1938
+ createdByIds.push(meta.createdBy?.id ?? null);
1939
+ updatedByKinds.push(meta.updatedBy?.kind ?? null);
1940
+ updatedByIds.push(meta.updatedBy?.id ?? null);
1941
+ }
1942
+ const insertColumnParts = [];
1943
+ const insertValueParts = [];
1944
+ const conflictParts = [];
1945
+ for (const [field, meta] of Object.entries(this.#promotedColumns)) {
1946
+ const colRef = sql.unsafe(meta.column);
1947
+ const absentDefault = meta.kind === "boolean" ? sql`false` : sql`NULL`;
1948
+ const cast = meta.kind === "boolean" ? sql`::boolean` : sql``;
1949
+ insertColumnParts.push(sql`, ${colRef}`);
1950
+ insertValueParts.push(sql`, CASE WHEN bod::jsonb ? ${field} THEN (bod::jsonb->>${field})${cast} ELSE ${absentDefault} END`);
1951
+ conflictParts.push(sql`, ${colRef} = CASE WHEN EXCLUDED.body ? ${field} THEN (EXCLUDED.body->>${field})${cast} ELSE ${sql.unsafe(`rows.${meta.column}`)} END`);
1952
+ }
1953
+ const insertColumnList = insertColumnParts.length === 0 ? sql`` : insertColumnParts;
1954
+ const insertColumnValues = insertValueParts.length === 0 ? sql`` : insertValueParts;
1955
+ const conflictColumnUpdates = conflictParts.length === 0 ? sql`` : conflictParts;
1956
+ const merged = (await sql`
1957
+ WITH input AS (
1958
+ SELECT *
1959
+ FROM UNNEST(
1960
+ ${namespaces}::text[],
1961
+ ${types}::text[],
1962
+ ${idsCol}::text[],
1963
+ ${bodies}::text[],
1964
+ ${createdAts}::text[],
1965
+ ${updatedAts}::text[],
1966
+ ${createdByKinds}::text[],
1967
+ ${createdByIds}::text[],
1968
+ ${updatedByKinds}::text[],
1969
+ ${updatedByIds}::text[]
1970
+ ) WITH ORDINALITY AS t(ns, ty, rid, bod, ca, ua, cbk, cbi, ubk, ubi, ord)
1971
+ ),
1972
+ upserted AS (
1973
+ INSERT INTO rows (namespace, type, id, body, deleted_at,
1974
+ created_at, updated_at, created_by_kind, created_by_id,
1975
+ updated_by_kind, updated_by_id${insertColumnList})
1976
+ SELECT
1977
+ ns, ty, rid, bod::jsonb, NULL::timestamptz,
1978
+ ca::timestamptz, ua::timestamptz, cbk, cbi, ubk, ubi${insertColumnValues}
1979
+ FROM input
1980
+ ${options?.insertOnly === true ? sql`ON CONFLICT (namespace, type, id) DO NOTHING` : sql`ON CONFLICT (namespace, type, id)
1981
+ DO UPDATE SET
1982
+ body = rows.body || EXCLUDED.body,
1983
+ created_at = COALESCE(rows.created_at, EXCLUDED.created_at),
1984
+ updated_at = COALESCE(EXCLUDED.updated_at, rows.updated_at),
1985
+ created_by_kind = COALESCE(rows.created_by_kind, EXCLUDED.created_by_kind),
1986
+ created_by_id = COALESCE(rows.created_by_id, EXCLUDED.created_by_id),
1987
+ updated_by_kind = COALESCE(EXCLUDED.updated_by_kind, rows.updated_by_kind),
1988
+ updated_by_id = COALESCE(EXCLUDED.updated_by_id, rows.updated_by_id)${conflictColumnUpdates}`}
1989
+ RETURNING namespace, type, id, body, deleted_at,
1990
+ created_at, updated_at, created_by_kind, created_by_id,
1991
+ updated_by_kind, updated_by_id
1992
+ )
1993
+ SELECT u.id, u.body, u.deleted_at, s.short_id,
1994
+ u.created_at, u.updated_at,
1995
+ u.created_by_kind, u.created_by_id,
1996
+ u.updated_by_kind, u.updated_by_id
1997
+ FROM upserted u
1998
+ JOIN input i ON i.rid = u.id
1999
+ LEFT JOIN short_ids s
2000
+ ON s.namespace = u.namespace
2001
+ AND s.type = u.type
2002
+ AND s.row_id = u.id
2003
+ ORDER BY i.ord
2004
+ `).map((r) => this.materialize(r));
2005
+ if (options?.insertOnly === true) return {
2006
+ written: merged.length,
2007
+ ids: merged.map((r) => r.id),
2008
+ rows: merged
2009
+ };
2010
+ return {
2011
+ written: ids.length,
2012
+ ids,
2013
+ rows: merged
2014
+ };
2015
+ }
2016
+ async tombstone(type, ids) {
2017
+ if (ids.length === 0) return {
2018
+ deleted: 0,
2019
+ ids: []
2020
+ };
2021
+ const textIds = ids.map(idToText);
2022
+ const stamped = (await this.#sql`
2023
+ UPDATE rows
2024
+ SET deleted_at = now()
2025
+ WHERE namespace = ${this.namespace}
2026
+ AND type = ${type}
2027
+ AND id = ANY(${textIds})
2028
+ AND deleted_at IS NULL
2029
+ RETURNING id, body
2030
+ `).map((r) => this.extractOriginalId(r.id, r.body));
2031
+ return {
2032
+ deleted: stamped.length,
2033
+ ids: stamped
2034
+ };
2035
+ }
2036
+ async purge(type, ids) {
2037
+ if (ids.length === 0) return {
2038
+ deleted: 0,
2039
+ ids: []
2040
+ };
2041
+ const textIds = ids.map(idToText);
2042
+ const removed = (await this.#sql`
2043
+ DELETE FROM rows
2044
+ WHERE namespace = ${this.namespace}
2045
+ AND type = ${type}
2046
+ AND id = ANY(${textIds})
2047
+ RETURNING id, body
2048
+ `).map((r) => this.extractOriginalId(r.id, r.body));
2049
+ return {
2050
+ deleted: removed.length,
2051
+ ids: removed
2052
+ };
2053
+ }
2054
+ /**
2055
+ * Hard-deletes tombstoned rows whose `deleted_at` is older than `olderThan`,
2056
+ * across ALL namespaces (the table is substrate-shared). Called by the sweep
2057
+ * loop. Returns the number of rows deleted.
2058
+ *
2059
+ * Short-id mappings are left in place, as in `purge()`: a row id can
2060
+ * reappear after a tombstone + rewrite.
2061
+ */
2062
+ async purgeTombstonedRows(opts) {
2063
+ return { deleted: (await this.#sql`
2064
+ DELETE FROM rows
2065
+ WHERE deleted_at IS NOT NULL
2066
+ AND deleted_at < ${opts.olderThan}
2067
+ RETURNING id
2068
+ `).length };
2069
+ }
2070
+ /**
2071
+ * Hard-delete every row for `type` in this namespace, including tombstoned
2072
+ * rows (`deleted_at IS NOT NULL`). Short-id mappings for that type are
2073
+ * removed in the same logical operation. Both deletes run through `this.#sql`
2074
+ * so they participate in any surrounding `withTransaction` boundary.
2075
+ */
2076
+ async dropType(type) {
2077
+ return {
2078
+ rowsDeleted: (await this.#sql`
2079
+ DELETE FROM rows
2080
+ WHERE namespace = ${this.namespace} AND type = ${type}
2081
+ RETURNING id
2082
+ `).length,
2083
+ shortIdsDeleted: await this.#shortIds.dropType(this.namespace, type)
2084
+ };
2085
+ }
2086
+ /**
2087
+ * Hard-delete every row across all types in this namespace, including
2088
+ * tombstoned rows. Short-id mappings for all types are removed too.
2089
+ */
2090
+ async dropNamespace() {
2091
+ return {
2092
+ rowsDeleted: (await this.#sql`
2093
+ DELETE FROM rows
2094
+ WHERE namespace = ${this.namespace}
2095
+ RETURNING id
2096
+ `).length,
2097
+ shortIdsDeleted: await this.#shortIds.dropNamespace(this.namespace)
2098
+ };
2099
+ }
2100
+ /**
2101
+ * Compare-and-update (spec §5.12): merges `updates` into the live row only
2102
+ * if every `match` field equals its expected value. Returns `matched` and
2103
+ * the updated row.
2104
+ *
2105
+ * One `UPDATE ... WHERE <pk> AND <match>`, so the row lock makes exactly one
2106
+ * of N concurrent callers match. `_deletedAt` and `id` are dropped from
2107
+ * `updates`.
2108
+ */
2109
+ async conditionalUpdate(type, id, match, updates, actor, now) {
2110
+ const sql = this.#sql;
2111
+ const sanitisedUpdates = {};
2112
+ for (const [k, v] of Object.entries(updates)) {
2113
+ if (k === RESERVED_DELETED_AT) continue;
2114
+ if (k === "id") continue;
2115
+ sanitisedUpdates[k] = v;
2116
+ }
2117
+ const matchClauses = [];
2118
+ for (const [field, expected] of Object.entries(match)) matchClauses.push(conditionalMatchFragment(sql, field, expected));
2119
+ const matchSql = matchClauses.length === 0 ? sql`TRUE` : combineAnd(sql, matchClauses);
2120
+ const updatesJson = sql.json(asJsonValue(sanitisedUpdates));
2121
+ const deletedGuard = sql`deleted_at IS NULL`;
2122
+ const updatedBy = actor ?? {
2123
+ kind: "system",
2124
+ id: "anonymous"
2125
+ };
2126
+ const columnMirrors = [];
2127
+ for (const field of Object.keys(this.#promotedColumns)) {
2128
+ if (!(field in sanitisedUpdates)) continue;
2129
+ const meta = this.#promotedFor(field);
2130
+ if (meta === void 0) continue;
2131
+ const raw = sanitisedUpdates[field];
2132
+ const colIdent = sql(meta.column);
2133
+ if (raw === null) columnMirrors.push(sql`${colIdent} = NULL`);
2134
+ else if (meta.kind === "boolean") columnMirrors.push(sql`${colIdent} = ${String(raw)}::text::boolean`);
2135
+ else columnMirrors.push(sql`${colIdent} = ${String(raw)}::text`);
2136
+ }
2137
+ const setFragments = [
2138
+ sql`body = body || ${updatesJson}`,
2139
+ now === void 0 ? sql`updated_at = now()` : sql`updated_at = ${now}`,
2140
+ sql`updated_by_kind = ${updatedBy.kind}`,
2141
+ sql`updated_by_id = ${updatedBy.id}`,
2142
+ ...columnMirrors
2143
+ ];
2144
+ const commaFrag = sql`,`;
2145
+ const interleaved = [setFragments[0]];
2146
+ for (let i = 1; i < setFragments.length; i++) interleaved.push(commaFrag, setFragments[i]);
2147
+ const row = (await sql`
2148
+ WITH updated AS (
2149
+ UPDATE rows
2150
+ SET ${interleaved}
2151
+ WHERE namespace = ${this.namespace}
2152
+ AND type = ${type}
2153
+ AND id = ${idToText(id)}
2154
+ AND ${deletedGuard}
2155
+ AND ${matchSql}
2156
+ RETURNING namespace, type, id, body, deleted_at, created_at, updated_at,
2157
+ created_by_kind, created_by_id, updated_by_kind, updated_by_id
2158
+ )
2159
+ SELECT u.id, u.body, u.deleted_at, s.short_id,
2160
+ u.created_at, u.updated_at,
2161
+ u.created_by_kind, u.created_by_id,
2162
+ u.updated_by_kind, u.updated_by_id
2163
+ FROM updated u
2164
+ LEFT JOIN short_ids s
2165
+ ON s.namespace = u.namespace
2166
+ AND s.type = u.type
2167
+ AND s.row_id = u.id
2168
+ `)[0];
2169
+ if (row === void 0) return {
2170
+ matched: false,
2171
+ row: null
2172
+ };
2173
+ return {
2174
+ matched: true,
2175
+ row: this.materialize(row)
2176
+ };
2177
+ }
2178
+ async updateField(ref, fieldName, value) {
2179
+ if (ref.ns !== void 0 && ref.ns !== this.namespace) throw new NamespaceMismatch(this.namespace, ref.ns);
2180
+ if (fieldName === RESERVED_DELETED_AT) throw new ReservedField(fieldName);
2181
+ if (fieldName === "_metadata") {
2182
+ const meta = value;
2183
+ await this.#sql`
2184
+ UPDATE rows
2185
+ SET created_at = ${meta?.createdAt ?? null},
2186
+ updated_at = ${meta?.updatedAt ?? null},
2187
+ created_by_kind = ${meta?.createdBy?.kind ?? null},
2188
+ created_by_id = ${meta?.createdBy?.id ?? null},
2189
+ updated_by_kind = ${meta?.updatedBy?.kind ?? null},
2190
+ updated_by_id = ${meta?.updatedBy?.id ?? null}
2191
+ WHERE namespace = ${this.namespace}
2192
+ AND type = ${ref.type}
2193
+ AND id = ${idToText(ref.id)}
2194
+ `;
2195
+ return;
2196
+ }
2197
+ const setFragments = [value === null || value === void 0 ? this.#sql`body = jsonb_set(body, ${[fieldName]}, 'null'::jsonb, true)` : this.#sql`body = jsonb_set(body, ${[fieldName]}, ${this.#sql.json(asJsonValue(value))}, true)`];
2198
+ const promotedMeta = this.#promotedFor(fieldName);
2199
+ if (promotedMeta !== void 0) {
2200
+ const meta = promotedMeta;
2201
+ const colIdent = this.#sql(meta.column);
2202
+ if (value === null || value === void 0) setFragments.push(this.#sql`${colIdent} = NULL`);
2203
+ else if (meta.kind === "boolean") setFragments.push(this.#sql`${colIdent} = ${String(value)}::text::boolean`);
2204
+ else setFragments.push(this.#sql`${colIdent} = ${String(value)}::text`);
2205
+ }
2206
+ const commaFrag = this.#sql`,`;
2207
+ const interleaved = [setFragments[0]];
2208
+ for (let i = 1; i < setFragments.length; i++) interleaved.push(commaFrag, setFragments[i]);
2209
+ await this.#sql`
2210
+ UPDATE rows
2211
+ SET ${interleaved}
2212
+ WHERE namespace = ${this.namespace}
2213
+ AND type = ${ref.type}
2214
+ AND id = ${idToText(ref.id)}
2215
+ `;
2216
+ }
2217
+ /**
2218
+ * `sql.begin`-backed atomicity. Spec §5.3 / G1.
2219
+ *
2220
+ * Nested calls flatten: postgres.js's `begin` inside a `begin` would create
2221
+ * a savepoint (inner rolls back independently of outer), which is stricter
2222
+ * than the G1 contract promises. To match the memory impl — where an inner
2223
+ * throw tears down outer writes too — we detect the re-entry via `#inTx`
2224
+ * and skip the nested begin entirely. The inner throw then propagates to
2225
+ * the outer `sql.begin`, which rolls back the whole thing.
2226
+ */
2227
+ async withTransaction(fn) {
2228
+ if (this.#inTx) return fn(this);
2229
+ return this.#sql.begin(async (txSql) => {
2230
+ return fn(new PgDataset({
2231
+ namespace: this.namespace,
2232
+ sql: txSql,
2233
+ inTx: true,
2234
+ txScopeId: this.txScopeId,
2235
+ ...this.#fieldDefLookup !== null ? { fieldDefLookup: this.#fieldDefLookup } : {},
2236
+ promotedColumns: this.#promotedColumns
2237
+ }));
2238
+ });
2239
+ }
2240
+ /**
2241
+ * Runs `fn` in one pg transaction with a tx-bound dataset per requested
2242
+ * namespace (and the edges store, when wired), all on one `TransactionSql`.
2243
+ * A throw rolls back every namespace. Spec §5.3.
2244
+ *
2245
+ * Nested calls flatten onto the current transaction rather than opening a
2246
+ * savepoint.
2247
+ */
2248
+ async withScopedTransaction(namespaces, fn) {
2249
+ const buildHandles = (handle) => {
2250
+ const datasets = /* @__PURE__ */ new Map();
2251
+ for (const ns of namespaces) datasets.set(ns, new PgDataset({
2252
+ namespace: ns,
2253
+ sql: handle,
2254
+ inTx: true,
2255
+ txScopeId: this.txScopeId,
2256
+ ...this.#edgesStore !== null ? { edgesStore: this.#edgesStore } : {},
2257
+ ...this.#fieldDefLookup !== null ? { fieldDefLookup: this.#fieldDefLookup } : {},
2258
+ promotedColumns: this.#promotedColumns
2259
+ }));
2260
+ return {
2261
+ datasets,
2262
+ edges: this.#edgesStore !== null ? this.#edgesStore._enlistInTx(handle) : null
2263
+ };
2264
+ };
2265
+ if (this.#inTx) return fn(buildHandles(this.#sql));
2266
+ return this.#sql.begin(async (txSql) => {
2267
+ return fn(buildHandles(txSql));
2268
+ });
2269
+ }
2270
+ /**
2271
+ * See `Dataset.withAdvisoryLock`. Excludes every session on the
2272
+ * database, across processes. On a tx-bound instance the lock is
2273
+ * `pg_advisory_xact_lock` on the transaction's own connection, held until
2274
+ * it commits or rolls back: a session lock would need a second connection
2275
+ * beside the open transaction.
2276
+ */
2277
+ async withAdvisoryLock(key, fn) {
2278
+ if (!this.#inTx) return withPgAdvisoryLock(this.#sql, key, fn);
2279
+ await this.#sql`SELECT pg_advisory_xact_lock(hashtext(${key}))`;
2280
+ return fn();
2281
+ }
2282
+ async allocateShortId(type) {
2283
+ return this.#shortIds.allocateUnbound(this.namespace, type);
2284
+ }
2285
+ async bindShortId(type, shortId, rowId) {
2286
+ await this.#shortIds.bind(this.namespace, type, shortId, rowId);
2287
+ }
2288
+ async resolveShortId(type, shortId) {
2289
+ return this.#shortIds.resolveShortId(this.namespace, type, shortId);
2290
+ }
2291
+ async getShortIdForRow(type, rowId) {
2292
+ return this.#shortIds.getShortIdForRow(this.namespace, type, rowId);
2293
+ }
2294
+ forNamespace(namespace) {
2295
+ if (this.#inTx) throw new Error("PgDataset.forNamespace cannot be called on a tx-bound instance");
2296
+ return new PgDataset({
2297
+ namespace,
2298
+ sql: this.#sql,
2299
+ ...this.#edgesStore !== null ? { edgesStore: this.#edgesStore } : {},
2300
+ ...this.#fieldDefLookup !== null ? { fieldDefLookup: this.#fieldDefLookup } : {},
2301
+ promotedColumns: this.#promotedColumns
2302
+ });
2303
+ }
2304
+ materialize(record) {
2305
+ const body = record.body ?? {};
2306
+ const out = { id: this.extractOriginalId(record.id, body) };
2307
+ for (const [k, v] of Object.entries(body)) {
2308
+ if (k === "id") continue;
2309
+ if (k === RESERVED_DELETED_AT) continue;
2310
+ if (k === "_metadata") continue;
2311
+ out[k] = v;
2312
+ }
2313
+ if (record.deleted_at !== null) out._deletedAt = record.deleted_at;
2314
+ if (record.short_id !== null && record.short_id !== void 0) out.shortId = Number(record.short_id);
2315
+ const meta = assembleRowMetadata(record);
2316
+ if (meta !== void 0) out._metadata = meta;
2317
+ return out;
2318
+ }
2319
+ extractOriginalId(textId, body) {
2320
+ const bodyId = body.id;
2321
+ if (typeof bodyId === "number" || typeof bodyId === "string") return bodyId;
2322
+ return textId;
2323
+ }
2324
+ };
2325
+
2326
+ //#endregion
2327
+ export { runDerivedMigrations as a, pendingMigrations as i, txScopeIdFor as n, runMigrations as o, deriveListIndexMigration as r, tryWithPgAdvisoryLock as s, PgDataset as t };