@peridotvault/peridotbase-sdk 0.0.0-stage → 0.2.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.
package/dist/v3.js ADDED
@@ -0,0 +1,1649 @@
1
+ "use strict";
2
+ /**
3
+ * v3 (record-PDA) client helpers.
4
+ *
5
+ * A v3 table stores one logical row per PDA, so the planner is deterministic:
6
+ *
7
+ * - primary-key equality → derive the record PDA, one `getAccountInfo`
8
+ * - UNIQUE equality → claim PDA → owner record
9
+ * - non-unique equality → posting lanes for the value → owner records
10
+ * - full scan → directory lanes/pages → record PDAs
11
+ *
12
+ * `scan()` is a resumable cursor over the on-chain directory. It never calls
13
+ * `getProgramAccounts` for row data and never materialises the whole table.
14
+ */
15
+ var __importDefault = (this && this.__importDefault) || function (mod) {
16
+ return (mod && mod.__esModule) ? mod : { "default": mod };
17
+ };
18
+ Object.defineProperty(exports, "__esModule", { value: true });
19
+ exports.V3Table = exports.DEFAULT_SCAN_PAGE = void 0;
20
+ exports.decodeDirectoryLane = decodeDirectoryLane;
21
+ exports.decodeDirectoryPage = decodeDirectoryPage;
22
+ exports.decodeUniqueClaim = decodeUniqueClaim;
23
+ exports.decodePostingPage = decodePostingPage;
24
+ exports.migrateV2TableToV3 = migrateV2TableToV3;
25
+ exports.verifyV3Coverage = verifyV3Coverage;
26
+ exports.activateV3Table = activateV3Table;
27
+ exports.verifyV3Invariants = verifyV3Invariants;
28
+ const web3_js_1 = require("@solana/web3.js");
29
+ const bn_js_1 = __importDefault(require("bn.js"));
30
+ const values_1 = require("./values");
31
+ const pda_1 = require("./pda");
32
+ const errors_1 = require("./errors");
33
+ /** Default result page size for `scan()`. */
34
+ exports.DEFAULT_SCAN_PAGE = 500;
35
+ function decodePartition(descriptor) {
36
+ const strategy = Number(descriptor.partitionStrategy ?? 0);
37
+ const name = strategy === 1 ? "range" : strategy === 2 ? "list" : null;
38
+ if (!name)
39
+ return null;
40
+ const length = Number(descriptor.partitionBoundsLen ?? 0);
41
+ const bounds = (descriptor.partitionBounds ?? [])
42
+ .slice(0, length)
43
+ .map((value) => BigInt(value.toString()));
44
+ return {
45
+ strategy: name,
46
+ column: Number(descriptor.partitionColumn),
47
+ bounds,
48
+ hasDefault: Boolean(descriptor.partitionDefault),
49
+ };
50
+ }
51
+ // ---------------------------------------------------------------------------
52
+ // Raw decoders for accounts Anchor does not emit into the IDL
53
+ // ---------------------------------------------------------------------------
54
+ class RawReader {
55
+ constructor(data) {
56
+ this.data = data;
57
+ this.offset = 8;
58
+ }
59
+ u8() {
60
+ const value = this.data.readUInt8(this.offset);
61
+ this.offset += 1;
62
+ return value;
63
+ }
64
+ u32() {
65
+ const value = this.data.readUInt32LE(this.offset);
66
+ this.offset += 4;
67
+ return value;
68
+ }
69
+ u64() {
70
+ const value = this.data.readBigUInt64LE(this.offset);
71
+ this.offset += 8;
72
+ return value;
73
+ }
74
+ bytes(length) {
75
+ const value = this.data.subarray(this.offset, this.offset + length);
76
+ this.offset += length;
77
+ return value;
78
+ }
79
+ skip(length) {
80
+ this.offset += length;
81
+ }
82
+ }
83
+ function decodeDirectoryLane(data) {
84
+ const r = new RawReader(data);
85
+ r.u8();
86
+ r.u8();
87
+ const table = new web3_js_1.PublicKey(r.bytes(32));
88
+ const epoch = r.u64();
89
+ const lane = r.u32();
90
+ const tailPage = r.u64();
91
+ const entries = r.u64();
92
+ return { table, epoch, lane, tailPage, entries };
93
+ }
94
+ function decodeDirectoryPage(data) {
95
+ const r = new RawReader(data);
96
+ r.u8();
97
+ r.u8();
98
+ r.skip(32);
99
+ r.skip(8);
100
+ const lane = r.u32();
101
+ const page = r.u64();
102
+ const count = r.u32();
103
+ const digests = [];
104
+ for (let i = 0; i < count; i += 1)
105
+ digests.push(r.bytes(32));
106
+ return { lane, page, digests };
107
+ }
108
+ function decodeUniqueClaim(data) {
109
+ const r = new RawReader(data);
110
+ r.u8();
111
+ r.u8();
112
+ r.skip(32);
113
+ r.skip(8);
114
+ r.skip(8);
115
+ const keyLen = r.u32();
116
+ const key = r.bytes(keyLen);
117
+ const coveringLen = r.u32();
118
+ const covering = Buffer.from(coveringLen > 0 ? r.bytes(coveringLen) : new Uint8Array(0));
119
+ const owner = new web3_js_1.PublicKey(r.bytes(32));
120
+ return { key, covering, owner };
121
+ }
122
+ function decodePostingPage(data) {
123
+ const r = new RawReader(data);
124
+ r.u8();
125
+ r.u8();
126
+ r.skip(32);
127
+ r.skip(8);
128
+ r.skip(8);
129
+ r.skip(32);
130
+ const lane = r.u32();
131
+ r.skip(8);
132
+ const count = r.u32();
133
+ const members = [];
134
+ for (let i = 0; i < count; i += 1) {
135
+ const record = new web3_js_1.PublicKey(r.bytes(32));
136
+ const slot = r.u32();
137
+ const live = r.u8() !== 0;
138
+ const coveringLen = r.u32();
139
+ const covering = Buffer.from(coveringLen > 0 ? r.bytes(coveringLen) : new Uint8Array(0));
140
+ members.push({ record, slot, live, covering });
141
+ }
142
+ return { lane, members };
143
+ }
144
+ function rowObject(table, values) {
145
+ const row = {};
146
+ table.columns.forEach((column, index) => {
147
+ row[column.name] = values[index];
148
+ });
149
+ return row;
150
+ }
151
+ /** Scalar equality used by the unindexed reverse-FK fallback. */
152
+ function scalarEqual(a, b) {
153
+ if (a === null || a === undefined || b === null || b === undefined) {
154
+ return (a ?? null) === (b ?? null);
155
+ }
156
+ if (typeof a === "object" || typeof b === "object") {
157
+ try {
158
+ return (0, values_1.canonicalTypedKeyV3)(a).equals((0, values_1.canonicalTypedKeyV3)(b));
159
+ }
160
+ catch {
161
+ return false;
162
+ }
163
+ }
164
+ return a === b;
165
+ }
166
+ /** True when the error is the named on-chain `DbError`. */
167
+ function isAnchorError(error, code) {
168
+ const candidate = error;
169
+ if (candidate?.error?.errorCode?.code === code)
170
+ return true;
171
+ return typeof candidate?.message === "string" && candidate.message.includes(`Error Code: ${code}`);
172
+ }
173
+ // ---------------------------------------------------------------------------
174
+ // V3Table
175
+ // ---------------------------------------------------------------------------
176
+ class V3Table {
177
+ constructor(client, address, tableId, storage, config, columns, primaryKey, primaryKeyColumns, indexes, foreignKeys = [], inboundForeignKeys = []) {
178
+ this.client = client;
179
+ this.address = address;
180
+ this.tableId = tableId;
181
+ this.storage = storage;
182
+ this.config = config;
183
+ this.columns = columns;
184
+ this.primaryKey = primaryKey;
185
+ this.primaryKeyColumns = primaryKeyColumns;
186
+ this.indexes = indexes;
187
+ this.foreignKeys = foreignKeys;
188
+ this.inboundForeignKeys = inboundForeignKeys;
189
+ this.parentEpochs = new Map();
190
+ }
191
+ /** Loads the table catalog and its v3 storage descriptor. */
192
+ static async load(client, tableId) {
193
+ const anyProgram = client.program;
194
+ const address = tableId instanceof web3_js_1.PublicKey ? tableId : client.tableAddress(tableId);
195
+ const table = await anyProgram.account.tableCatalog.fetch(address);
196
+ const [storage] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("pd"), Buffer.from("storage-v3"), address.toBuffer()], client.programId);
197
+ const descriptor = await anyProgram.account.storageDescriptorV3.fetch(storage);
198
+ const columns = table.columns.map((column) => {
199
+ const type = Object.keys(column.ty)[0];
200
+ return {
201
+ name: column.name,
202
+ type,
203
+ scale: column.scale,
204
+ maxLen: column.maxLen,
205
+ default: null,
206
+ };
207
+ });
208
+ const composite = table.constraints.find((constraint) => Object.keys(constraint.kind)[0] === "compositePrimaryKey");
209
+ const primaryKeyColumns = composite
210
+ ? Array.from(composite.expr)
211
+ : [Number(table.primaryKey)];
212
+ const compositeIndexes = new Map();
213
+ for (const constraint of table.constraints) {
214
+ if (Object.keys(constraint.kind)[0] !== "compositeIndex")
215
+ continue;
216
+ const expr = Buffer.from(constraint.expr);
217
+ if (expr.length < 10)
218
+ continue;
219
+ compositeIndexes.set(expr.readBigUInt64LE(0), Array.from(expr.subarray(8)));
220
+ }
221
+ const coveringIndexes = new Map();
222
+ for (const constraint of table.constraints) {
223
+ if (Object.keys(constraint.kind)[0] !== "coveringIndex")
224
+ continue;
225
+ const expr = Buffer.from(constraint.expr);
226
+ if (expr.length < 9)
227
+ continue;
228
+ coveringIndexes.set(expr.readBigUInt64LE(0), Array.from(expr.subarray(8)));
229
+ }
230
+ const indexes = table.indexes.map((index) => {
231
+ const indexId = BigInt(index.indexId.toString());
232
+ return {
233
+ indexId,
234
+ name: index.name,
235
+ column: index.column,
236
+ columns: compositeIndexes.get(indexId) ?? [Number(index.column)],
237
+ includes: coveringIndexes.get(indexId) ?? [],
238
+ unique: index.unique,
239
+ nullsNotDistinct: index.nullsNotDistinct,
240
+ };
241
+ });
242
+ const foreignKeys = [];
243
+ const inboundForeignKeys = [];
244
+ for (const constraint of table.constraints) {
245
+ const kind = Object.keys(constraint.kind)[0];
246
+ const expr = Buffer.from(constraint.expr);
247
+ if (kind === "foreignKey" && expr.length >= 32) {
248
+ const composite = expr.length >= 54;
249
+ const count = composite ? expr[52] : 0;
250
+ foreignKeys.push({
251
+ column: constraint.column,
252
+ parentTable: new web3_js_1.PublicKey(expr.subarray(0, 32)),
253
+ parentColumn: expr.length >= 51 ? expr[42] : 0xff,
254
+ parentIndexId: expr.length >= 51 ? expr.readBigUInt64LE(43) : 0n,
255
+ childColumns: composite
256
+ ? Array.from(expr.subarray(53, 53 + count))
257
+ : [constraint.column],
258
+ matchType: composite ? expr[51] : 0,
259
+ });
260
+ }
261
+ else if (kind === "hasInboundForeignKeys" && expr.length >= 42) {
262
+ inboundForeignKeys.push({
263
+ childTable: new web3_js_1.PublicKey(expr.subarray(0, 32)),
264
+ fkId: expr.length >= 40 ? expr.readBigUInt64LE(32) : 0n,
265
+ parentColumn: expr.length >= 50 ? expr[40] : table.primaryKey,
266
+ parentIndexId: expr.length >= 50 ? expr.readBigUInt64LE(41) : 0n,
267
+ childColumn: expr.length >= 50 ? expr[49] : constraint.column,
268
+ });
269
+ }
270
+ }
271
+ return new V3Table(client, address, BigInt(table.tableId.toString()), storage, {
272
+ epoch: BigInt(descriptor.epoch.toString()),
273
+ laneCount: descriptor.laneCount,
274
+ pageCap: descriptor.pageCap,
275
+ postingLanes: descriptor.postingLanes,
276
+ historyLimit: Number(descriptor.historyLimit ?? 0),
277
+ partition: decodePartition(descriptor),
278
+ }, columns, table.primaryKey, primaryKeyColumns, indexes, foreignKeys, inboundForeignKeys);
279
+ }
280
+ /** Canonical primary-key digest used for the record PDA and directory lane. */
281
+ digestOf(primaryKey) {
282
+ return (0, values_1.pkDigestV3)(this.canonicalPk(primaryKey));
283
+ }
284
+ /**
285
+ * Partition index for a row, or `null` when the table is unpartitioned.
286
+ * The partition column is a primary-key column, so this value never changes
287
+ * for an existing row.
288
+ */
289
+ partitionOf(values) {
290
+ const partition = this.config.partition;
291
+ if (!partition)
292
+ return null;
293
+ const raw = values[partition.column];
294
+ if (raw === null || raw === undefined) {
295
+ throw new errors_1.PeridotBaseError("PartitionOutOfRange", "partition key is NULL");
296
+ }
297
+ const key = typeof raw === "bigint" ? raw : BigInt(raw.toString());
298
+ let index = partition.strategy === "range"
299
+ ? partition.bounds.findIndex((bound) => key < bound)
300
+ : partition.bounds.findIndex((bound) => bound === key);
301
+ if (index < 0) {
302
+ if (!partition.hasDefault) {
303
+ throw new errors_1.PeridotBaseError("PartitionOutOfRange", `no partition covers ${key.toString()}`);
304
+ }
305
+ index = partition.bounds.length;
306
+ }
307
+ if (index >= this.config.laneCount) {
308
+ throw new errors_1.PeridotBaseError("InvalidPartitionSpec", "partition exceeds lane count");
309
+ }
310
+ return index;
311
+ }
312
+ /** Number of declared partitions, including the optional default one. */
313
+ get partitionCount() {
314
+ const partition = this.config.partition;
315
+ if (!partition)
316
+ return 0;
317
+ return partition.bounds.length + (partition.hasDefault ? 1 : 0);
318
+ }
319
+ canonicalPk(primaryKey) {
320
+ if (this.primaryKeyColumns.length === 1) {
321
+ const column = this.columns[this.primaryKeyColumns[0]];
322
+ const value = Array.isArray(primaryKey) ? primaryKey[0] : primaryKey;
323
+ return (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, column));
324
+ }
325
+ if (!Array.isArray(primaryKey) || primaryKey.length !== this.primaryKeyColumns.length) {
326
+ throw new Error("composite primary key requires one value per key column");
327
+ }
328
+ const values = this.columns.map(() => null);
329
+ this.primaryKeyColumns.forEach((column, index) => {
330
+ values[column] = (0, values_1.coerceValue)(primaryKey[index], this.columns[column]);
331
+ });
332
+ return (0, values_1.primaryKeyCanonicalV3)(values, this.primaryKeyColumns);
333
+ }
334
+ recordAddress(primaryKey) {
335
+ return (0, pda_1.recordPdaV3)(this.address, this.config.epoch, this.digestOf(primaryKey))[0];
336
+ }
337
+ /** Direct primary-key lookup: one account fetch, no directory or index walk. */
338
+ async get(primaryKey) {
339
+ const record = this.recordAddress(primaryKey);
340
+ const info = await this.client.connection.getAccountInfo(record, "confirmed");
341
+ if (!info)
342
+ return null;
343
+ return this.decodeRecord(record, info.data);
344
+ }
345
+ decodeRecord(address, data) {
346
+ const anyProgram = this.client.program;
347
+ // Match by discriminator: the coder's name index is not stable across
348
+ // Anchor versions, but the discriminator is.
349
+ const decoded = anyProgram.coder.accounts.decodeAny(data);
350
+ if (!decoded || decoded.values === undefined) {
351
+ throw new errors_1.PeridotBaseError("MalformedAccount", "account is not a v3 record");
352
+ }
353
+ return {
354
+ address,
355
+ revision: BigInt(decoded.revision.toString()),
356
+ live: decoded.status === 1,
357
+ values: decoded.values.map((value) => {
358
+ const key = Object.keys(value)[0];
359
+ const payload = value[key];
360
+ const unwrap = Array.isArray(payload) ? payload[0] : payload?.["0"] ?? payload;
361
+ if (key === "null")
362
+ return null;
363
+ if (key === "bool")
364
+ return Boolean(unwrap);
365
+ if (key === "i64")
366
+ return BigInt(unwrap.toString());
367
+ if (key === "text")
368
+ return String(unwrap);
369
+ if (key === "uuid")
370
+ return Uint8Array.from(unwrap);
371
+ if (key === "decimal") {
372
+ const scaled = Array.isArray(payload) ? payload[0] : payload["0"];
373
+ const scale = Array.isArray(payload) ? payload[1] : payload["1"];
374
+ return { decimal: BigInt(scaled.toString()), scale: Number(scale) };
375
+ }
376
+ return null;
377
+ }),
378
+ accruedFee: BigInt(decoded.accruedFee.toString()),
379
+ };
380
+ }
381
+ /**
382
+ * Ensures the directory lane/page that the next append targets exists, and
383
+ * returns both addresses. A full tail page triggers a rollover.
384
+ */
385
+ async ensureDirectory(digest, values = []) {
386
+ const lane = this.partitionOf(values) ?? (0, pda_1.laneForDigest)(digest, this.config.laneCount);
387
+ const [lanePda] = (0, pda_1.dirLanePdaV3)(this.address, this.config.epoch, lane);
388
+ const laneInfo = await this.client.connection.getAccountInfo(lanePda, "confirmed");
389
+ let tail = 0n;
390
+ if (laneInfo) {
391
+ tail = decodeDirectoryLane(laneInfo.data).tailPage;
392
+ const [tailPda] = (0, pda_1.dirPagePdaV3)(this.address, this.config.epoch, lane, tail);
393
+ const pageInfo = await this.client.connection.getAccountInfo(tailPda, "confirmed");
394
+ if (pageInfo && decodeDirectoryPage(pageInfo.data).digests.length >= this.config.pageCap) {
395
+ const next = tail + 1n;
396
+ await this.createDirPage(lane, next, tailPda);
397
+ tail = next;
398
+ }
399
+ }
400
+ const [pagePda] = (0, pda_1.dirPagePdaV3)(this.address, this.config.epoch, lane, tail);
401
+ return { lane, lanePda, pagePda, page: tail };
402
+ }
403
+ async createDirPage(lane, page, currentPage) {
404
+ const [lanePda] = (0, pda_1.dirLanePdaV3)(this.address, this.config.epoch, lane);
405
+ const [pagePda] = (0, pda_1.dirPagePdaV3)(this.address, this.config.epoch, lane, page);
406
+ await this.client.program.methods
407
+ .createDirPageV3({
408
+ tableId: new bn_js_1.default(this.tableId.toString()),
409
+ epoch: new bn_js_1.default(this.config.epoch.toString()),
410
+ lane,
411
+ page: new bn_js_1.default(page.toString()),
412
+ })
413
+ .accounts({
414
+ protocol: this.client.protocolAddress,
415
+ database: this.client.databaseAddress(),
416
+ authority: this.client.wallet,
417
+ table: this.address,
418
+ storage: this.storage,
419
+ payer: this.client.wallet,
420
+ laneAccount: lanePda,
421
+ pageAccount: pagePda,
422
+ systemProgram: web3_js_1.SystemProgram.programId,
423
+ })
424
+ .remainingAccounts([{ pubkey: currentPage, isWritable: true, isSigner: false }])
425
+ .rpc();
426
+ }
427
+ /** Claim and posting accounts a mutation must supply, all pre-derived. */
428
+ indexAccounts(values, digest) {
429
+ const accounts = [];
430
+ const seen = new Set();
431
+ const push = (pubkey) => {
432
+ const key = pubkey.toBase58();
433
+ if (seen.has(key))
434
+ return;
435
+ seen.add(key);
436
+ accounts.push(pubkey);
437
+ };
438
+ for (const index of this.indexes) {
439
+ const parts = [];
440
+ let anyNull = false;
441
+ for (const column of index.columns) {
442
+ const value = values[column];
443
+ if (value === null || value === undefined) {
444
+ anyNull = true;
445
+ parts.push(Buffer.from([0x00]));
446
+ }
447
+ else {
448
+ parts.push((0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[column])));
449
+ }
450
+ }
451
+ if (anyNull && !index.nullsNotDistinct)
452
+ continue;
453
+ const key = index.columns.length === 1 ? parts[0] : (0, values_1.compositeIndexKeyV3)(parts);
454
+ if (index.unique) {
455
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
456
+ push((0, pda_1.uniqueClaimPdaV3)(this.address, idxDigest, (0, values_1.uniqueDigestV3)(key))[0]);
457
+ }
458
+ else {
459
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
460
+ const valueDigest = (0, values_1.postingDigestV3)(key);
461
+ const lane = (0, pda_1.laneForDigest)(digest, this.config.postingLanes);
462
+ push((0, pda_1.postLanePdaV3)(this.address, idxDigest, valueDigest, lane)[0]);
463
+ push((0, pda_1.postPagePdaV3)(this.address, idxDigest, valueDigest, lane, 0n)[0]);
464
+ }
465
+ }
466
+ return accounts;
467
+ }
468
+ /**
469
+ * Audit accounts for a mutation. When the database enforces auditing the
470
+ * program rejects a write without them, so this reads the trail head and
471
+ * derives the event PDA for the next sequence.
472
+ */
473
+ async auditAccounts() {
474
+ const database = await this.client.databaseInfo();
475
+ if (!database.requireAudit)
476
+ return { auditTrail: null, auditEvent: null };
477
+ const databaseKey = this.client.databaseAddress();
478
+ const trail = (0, pda_1.auditTrailPda)(databaseKey, this.client.programId)[0];
479
+ const info = await this.client.connection.getAccountInfo(trail, "confirmed");
480
+ let sequence = 0n;
481
+ if (info) {
482
+ const decoded = this.client.program.coder.accounts.decodeAny(info.data);
483
+ sequence = BigInt(decoded.sequence.toString());
484
+ }
485
+ return {
486
+ auditTrail: trail,
487
+ auditEvent: (0, pda_1.auditEventPda)(databaseKey, sequence + 1n, this.client.programId)[0],
488
+ };
489
+ }
490
+ /**
491
+ * History accounts for a mutation. Returns nulls when the table keeps no
492
+ * history; otherwise the account for the superseded revision plus the one
493
+ * leaving the retention window (closed on-chain).
494
+ */
495
+ historyAccounts(pkDigest, revision) {
496
+ const limit = BigInt(this.config.historyLimit);
497
+ if (limit === 0n)
498
+ return { history: null, historyExpired: null };
499
+ const history = (0, pda_1.historyPdaV3)(this.address, pkDigest, revision, this.client.programId)[0];
500
+ const historyExpired = revision >= limit
501
+ ? (0, pda_1.historyPdaV3)(this.address, pkDigest, revision - limit, this.client.programId)[0]
502
+ : null;
503
+ return { history, historyExpired };
504
+ }
505
+ /** Coerces a partial row into a full, schema-aligned value vector. */
506
+ coerceRow(row) {
507
+ return this.columns.map((column) => (0, values_1.coerceValue)(row[column.name] === undefined ? column.default ?? null : row[column.name], column));
508
+ }
509
+ async parentEpoch(parent) {
510
+ const key = parent.toBase58();
511
+ const cached = this.parentEpochs.get(key);
512
+ if (cached !== undefined)
513
+ return cached;
514
+ const account = await this.client.program.account.storageDescriptorV3.fetch((0, pda_1.storagePdaV3)(parent, this.client.programId)[0]);
515
+ const epoch = BigInt(account.epoch.toString());
516
+ this.parentEpochs.set(key, epoch);
517
+ return epoch;
518
+ }
519
+ /**
520
+ * Parent helper accounts for child-side foreign keys: parent storage, the
521
+ * referenced record (PK target) or UNIQUE claim, and the writable counter.
522
+ * Old and new tuples are unioned so an FK move is one transaction.
523
+ */
524
+ async foreignKeyAccounts(oldValues, newValues) {
525
+ if (this.foreignKeys.length === 0)
526
+ return [];
527
+ const accounts = new Map();
528
+ const put = (pubkey, writable) => {
529
+ const key = pubkey.toBase58();
530
+ const seen = accounts.get(key);
531
+ accounts.set(key, {
532
+ pubkey,
533
+ isWritable: writable || Boolean(seen?.isWritable),
534
+ isSigner: false,
535
+ });
536
+ };
537
+ for (const fk of this.foreignKeys) {
538
+ const columns = fk.childColumns;
539
+ const read = (values) => columns.map((column) => values?.[column] ?? null);
540
+ const tuples = new Map();
541
+ for (const tuple of [read(oldValues), read(newValues)]) {
542
+ // A NULL component means no reference (MATCH SIMPLE). MATCH FULL
543
+ // partial NULLs are rejected by the program before accounts matter.
544
+ if (tuple.some((value) => value === null || value === undefined))
545
+ continue;
546
+ const key = tuple.map((value) => String(value)).join("\u0000");
547
+ tuples.set(key, tuple);
548
+ }
549
+ if (tuples.size === 0)
550
+ continue;
551
+ const epoch = await this.parentEpoch(fk.parentTable);
552
+ put((0, pda_1.storagePdaV3)(fk.parentTable, this.client.programId)[0], false);
553
+ for (const tuple of tuples.values()) {
554
+ const parts = tuple.map((value, offset) => (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[columns[offset]])));
555
+ const key = parts.length === 1 ? parts[0] : (0, values_1.compositeIndexKeyV3)(parts);
556
+ if (fk.parentIndexId === 0n) {
557
+ put((0, pda_1.recordPdaV3)(fk.parentTable, epoch, (0, values_1.pkDigestV3)(key))[0], false);
558
+ }
559
+ else {
560
+ const idxDigest = (0, pda_1.indexIdDigestV3)(fk.parentTable, epoch, fk.parentIndexId);
561
+ // Claim helpers are re-serialized on every write, so they must be
562
+ // writable even though the child path only reads them.
563
+ put((0, pda_1.uniqueClaimPdaV3)(fk.parentTable, idxDigest, (0, values_1.uniqueDigestV3)(key))[0], true);
564
+ }
565
+ put((0, pda_1.fkCounterPdaV3)(fk.parentTable, (0, pda_1.fkKeyDigest)(key), this.client.programId)[0], true);
566
+ }
567
+ }
568
+ return [...accounts.values()];
569
+ }
570
+ /** Writable counters for every inbound FK tuple an update/delete removes. */
571
+ inboundForeignKeyAccounts(oldValues, newValues) {
572
+ if (this.inboundForeignKeys.length === 0)
573
+ return [];
574
+ const accounts = new Map();
575
+ for (const reference of this.inboundForeignKeys) {
576
+ const index = reference.parentIndexId === 0n
577
+ ? undefined
578
+ : this.indexes.find((candidate) => candidate.indexId === reference.parentIndexId);
579
+ const columns = index ? index.columns : [reference.parentColumn];
580
+ const read = (values) => columns.map((column) => values?.[column] ?? null);
581
+ for (const tuple of [read(oldValues), read(newValues)]) {
582
+ if (tuple.some((value) => value === null || value === undefined))
583
+ continue;
584
+ const parts = tuple.map((value, offset) => (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[columns[offset]])));
585
+ const key = parts.length === 1 ? parts[0] : (0, values_1.compositeIndexKeyV3)(parts);
586
+ const counter = (0, pda_1.fkCounterPdaV3)(this.address, (0, pda_1.fkKeyDigest)(key), this.client.programId)[0];
587
+ accounts.set(counter.toBase58(), {
588
+ pubkey: counter,
589
+ isWritable: true,
590
+ isSigner: false,
591
+ });
592
+ }
593
+ }
594
+ return [...accounts.values()];
595
+ }
596
+ /** Writable helper that routes mutation fees to the sponsor allowance. */
597
+ sponsorAllowanceAccount() {
598
+ const allowance = this.client.sponsorAllowance;
599
+ return allowance ? [{ pubkey: allowance, isWritable: true, isSigner: false }] : [];
600
+ }
601
+ /**
602
+ * Inserts one row. One record per transaction; no implicit batching.
603
+ *
604
+ * A tombstoned identity is revived with `reinsert_record_v3`, which keeps the
605
+ * same PDA/directory slot and increments the revision (PRD §3.1). The create
606
+ * path is attempted first so the common case costs no extra RPC.
607
+ */
608
+ async insert(row) {
609
+ const values = this.coerceRow(row);
610
+ const digest = (0, values_1.pkDigestV3)((0, values_1.primaryKeyCanonicalV3)(values, this.primaryKeyColumns));
611
+ const [record] = (0, pda_1.recordPdaV3)(this.address, this.config.epoch, digest);
612
+ const { lanePda, pagePda } = await this.ensureDirectory(digest, values);
613
+ const extras = this.indexAccounts(values, digest);
614
+ const anyProgram = this.client.program;
615
+ const encoded = values.map((value) => (0, values_1.toAnchorValue)(value));
616
+ try {
617
+ const signature = await anyProgram.methods
618
+ .insertRecordV3({
619
+ tableId: new bn_js_1.default(this.tableId.toString()),
620
+ epoch: new bn_js_1.default(this.config.epoch.toString()),
621
+ pkDigest: Array.from(digest),
622
+ values: encoded,
623
+ })
624
+ .accounts({
625
+ protocol: this.client.protocolAddress,
626
+ database: this.client.databaseAddress(),
627
+ authority: this.client.wallet,
628
+ table: this.address,
629
+ storage: this.storage,
630
+ payer: this.client.wallet,
631
+ record,
632
+ externalGate: await this.externalGateAccount(),
633
+ ...(await this.auditAccounts()),
634
+ systemProgram: web3_js_1.SystemProgram.programId,
635
+ })
636
+ .remainingAccounts([
637
+ ...(await this.client.roleHelpers()),
638
+ ...this.sponsorAllowanceAccount(),
639
+ { pubkey: lanePda, isWritable: true, isSigner: false },
640
+ { pubkey: pagePda, isWritable: true, isSigner: false },
641
+ ...extras.map((pubkey) => ({ pubkey, isWritable: true, isSigner: false })),
642
+ ...(await this.foreignKeyAccounts(null, values)),
643
+ ])
644
+ .rpc();
645
+ return { address: record, signature };
646
+ }
647
+ catch (error) {
648
+ if (!isAnchorError(error, "DuplicateKey"))
649
+ throw error;
650
+ const compositeKey = this.primaryKeyColumns.length === 1
651
+ ? values[this.primaryKeyColumns[0]]
652
+ : this.primaryKeyColumns.map((column) => values[column]);
653
+ const current = await this.get(compositeKey);
654
+ // A LIVE row is a real duplicate: never overwrite it.
655
+ if (!current || current.live)
656
+ throw error;
657
+ const signature = await anyProgram.methods
658
+ .reinsertRecordV3({
659
+ tableId: new bn_js_1.default(this.tableId.toString()),
660
+ epoch: new bn_js_1.default(this.config.epoch.toString()),
661
+ pkDigest: Array.from(digest),
662
+ expectedRevision: new bn_js_1.default(current.revision.toString()),
663
+ values: encoded,
664
+ })
665
+ .accounts({
666
+ protocol: this.client.protocolAddress,
667
+ database: this.client.databaseAddress(),
668
+ authority: this.client.wallet,
669
+ table: this.address,
670
+ storage: this.storage,
671
+ record,
672
+ externalGate: await this.externalGateAccount(),
673
+ ...(await this.auditAccounts()),
674
+ systemProgram: web3_js_1.SystemProgram.programId,
675
+ })
676
+ .remainingAccounts([
677
+ ...(await this.client.roleHelpers()),
678
+ ...this.sponsorAllowanceAccount(),
679
+ ...extras.map((pubkey) => ({ pubkey, isWritable: true, isSigner: false })),
680
+ ])
681
+ .rpc();
682
+ return { address: record, signature };
683
+ }
684
+ }
685
+ /** Updates one row using its current revision as the optimistic lock. */
686
+ async update(primaryKey, assignments) {
687
+ const current = await this.get(primaryKey);
688
+ if (!current || !current.live) {
689
+ throw new errors_1.PeridotBaseError("RowNotFound", "row is missing or tombstoned");
690
+ }
691
+ const digest = this.digestOf(primaryKey);
692
+ const newValues = current.values.slice();
693
+ for (const assignment of assignments) {
694
+ const column = typeof assignment.column === "number"
695
+ ? assignment.column
696
+ : this.columns.findIndex((candidate) => candidate.name === assignment.column);
697
+ newValues[column] = (0, values_1.coerceValue)(assignment.value, this.columns[column]);
698
+ }
699
+ const extras = [
700
+ ...new Set([
701
+ ...this.indexAccounts(current.values, digest),
702
+ ...this.indexAccounts(newValues, digest),
703
+ ].map((pubkey) => pubkey.toBase58())),
704
+ ].map((key) => new web3_js_1.PublicKey(key));
705
+ return this.client.program.methods
706
+ .updateRecordV3({
707
+ tableId: new bn_js_1.default(this.tableId.toString()),
708
+ epoch: new bn_js_1.default(this.config.epoch.toString()),
709
+ pkDigest: Array.from(digest),
710
+ expectedRevision: new bn_js_1.default(current.revision.toString()),
711
+ assignments: assignments.map((assignment) => ({
712
+ column: typeof assignment.column === "number"
713
+ ? assignment.column
714
+ : this.columns.findIndex((candidate) => candidate.name === assignment.column),
715
+ value: (0, values_1.toAnchorValue)((0, values_1.coerceValue)(assignment.value, this.columns[typeof assignment.column === "number"
716
+ ? assignment.column
717
+ : this.columns.findIndex((candidate) => candidate.name === assignment.column)])),
718
+ })),
719
+ })
720
+ .accounts({
721
+ protocol: this.client.protocolAddress,
722
+ database: this.client.databaseAddress(),
723
+ authority: this.client.wallet,
724
+ table: this.address,
725
+ storage: this.storage,
726
+ record: this.recordAddress(primaryKey),
727
+ externalGate: await this.externalGateAccount(),
728
+ ...(await this.auditAccounts()),
729
+ ...this.historyAccounts(digest, current.revision),
730
+ systemProgram: web3_js_1.SystemProgram.programId,
731
+ })
732
+ .remainingAccounts([
733
+ ...(await this.client.roleHelpers()),
734
+ ...this.sponsorAllowanceAccount(),
735
+ ...extras.map((pubkey) => ({ pubkey, isWritable: true, isSigner: false })),
736
+ ...(await this.foreignKeyAccounts(current.values, newValues)),
737
+ ...this.inboundForeignKeyAccounts(current.values, newValues),
738
+ ])
739
+ .rpc();
740
+ }
741
+ /** Tombstones one row. The address and revision history are preserved. */
742
+ /**
743
+ * Atomic counter increment: reads the record, applies `delta`, and submits an
744
+ * update with the observed revision. A concurrent writer causes a retry.
745
+ */
746
+ async increment(primaryKey, column, delta = 1n, retries = 5) {
747
+ const index = typeof column === "number"
748
+ ? column
749
+ : this.columns.findIndex((candidate) => candidate.name === column);
750
+ if (index < 0 || index >= this.columns.length)
751
+ throw new Error(`unknown column: ${String(column)}`);
752
+ for (let attempt = 0; attempt < retries; attempt += 1) {
753
+ const current = await this.get(primaryKey);
754
+ if (!current || !current.live)
755
+ throw new Error("row not found");
756
+ const value = current.values[index];
757
+ if (typeof value !== "bigint" && typeof value !== "number") {
758
+ throw new Error("increment requires a numeric column");
759
+ }
760
+ const next = BigInt(value.toString()) + delta;
761
+ try {
762
+ await this.update(primaryKey, [{ column: index, value: next }]);
763
+ return next;
764
+ }
765
+ catch (error) {
766
+ const code = error?.error?.errorCode?.code ?? "";
767
+ if (attempt + 1 < retries && code === "WriteConflict")
768
+ continue;
769
+ throw error;
770
+ }
771
+ }
772
+ throw new Error("increment retries exhausted");
773
+ }
774
+ async delete(primaryKey) {
775
+ const current = await this.get(primaryKey);
776
+ if (!current || !current.live) {
777
+ throw new errors_1.PeridotBaseError("RowNotFound", "row is missing or tombstoned");
778
+ }
779
+ const digest = this.digestOf(primaryKey);
780
+ const extras = this.indexAccounts(current.values, digest);
781
+ return this.client.program.methods
782
+ .deleteRecordV3({
783
+ tableId: new bn_js_1.default(this.tableId.toString()),
784
+ epoch: new bn_js_1.default(this.config.epoch.toString()),
785
+ pkDigest: Array.from(digest),
786
+ expectedRevision: new bn_js_1.default(current.revision.toString()),
787
+ })
788
+ .accounts({
789
+ protocol: this.client.protocolAddress,
790
+ database: this.client.databaseAddress(),
791
+ authority: this.client.wallet,
792
+ table: this.address,
793
+ storage: this.storage,
794
+ record: this.recordAddress(primaryKey),
795
+ externalGate: await this.externalGateAccount(),
796
+ ...(await this.auditAccounts()),
797
+ ...this.historyAccounts(digest, current.revision),
798
+ systemProgram: web3_js_1.SystemProgram.programId,
799
+ })
800
+ .remainingAccounts([
801
+ ...(await this.client.roleHelpers()),
802
+ ...extras.map((pubkey) => ({ pubkey, isWritable: true, isSigner: false })),
803
+ ...(await this.foreignKeyAccounts(current.values, null)),
804
+ ...this.inboundForeignKeyAccounts(current.values, null),
805
+ ])
806
+ .rpc();
807
+ }
808
+ /** UNIQUE equality lookup: claim → owner record → recheck. */
809
+ async lookupUnique(indexName, value) {
810
+ const index = this.indexes.find((candidate) => candidate.name === indexName);
811
+ if (!index || !index.unique) {
812
+ throw new errors_1.PeridotBaseError("UnsupportedValue", `${indexName} is not a UNIQUE index`);
813
+ }
814
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
815
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
816
+ const [claim] = (0, pda_1.uniqueClaimPdaV3)(this.address, idxDigest, (0, values_1.uniqueDigestV3)(key));
817
+ const info = await this.client.connection.getAccountInfo(claim, "confirmed");
818
+ if (!info)
819
+ return null;
820
+ const decoded = decodeUniqueClaim(info.data);
821
+ if (decoded.owner.equals(web3_js_1.PublicKey.default))
822
+ return null;
823
+ const recordInfo = await this.client.connection.getAccountInfo(decoded.owner, "confirmed");
824
+ if (!recordInfo)
825
+ return null;
826
+ const record = this.decodeRecord(decoded.owner, recordInfo.data);
827
+ return record.live ? record : null;
828
+ }
829
+ /** Non-unique equality lookup: union every posting lane for the value. */
830
+ async lookupIndex(indexName, value) {
831
+ const index = this.indexes.find((candidate) => candidate.name === indexName);
832
+ if (!index)
833
+ throw new errors_1.PeridotBaseError("UnsupportedValue", `unknown index ${indexName}`);
834
+ if (index.unique) {
835
+ const one = await this.lookupUnique(indexName, value);
836
+ return one ? [one] : [];
837
+ }
838
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
839
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
840
+ const valueDigest = (0, values_1.postingDigestV3)(key);
841
+ const laneAddresses = [];
842
+ for (let lane = 0; lane < this.config.postingLanes; lane += 1) {
843
+ laneAddresses.push((0, pda_1.postLanePdaV3)(this.address, idxDigest, valueDigest, lane)[0]);
844
+ }
845
+ const owners = new Set();
846
+ const infos = await this.fetchBatched(laneAddresses);
847
+ for (let lane = 0; lane < infos.length; lane += 1) {
848
+ const info = infos[lane];
849
+ if (!info)
850
+ continue;
851
+ let page = 0n;
852
+ // Walk the lane's pages until one is missing.
853
+ for (;;) {
854
+ const [pagePda] = (0, pda_1.postPagePdaV3)(this.address, idxDigest, valueDigest, lane, page);
855
+ const pageInfo = await this.client.connection.getAccountInfo(pagePda, "confirmed");
856
+ if (!pageInfo)
857
+ break;
858
+ for (const member of decodePostingPage(pageInfo.data).members) {
859
+ if (member.live)
860
+ owners.add(member.record.toBase58());
861
+ }
862
+ page += 1n;
863
+ }
864
+ }
865
+ const records = [];
866
+ for (const owner of owners) {
867
+ const recordInfo = await this.client.connection.getAccountInfo(new web3_js_1.PublicKey(owner), "confirmed");
868
+ if (!recordInfo)
869
+ continue;
870
+ const record = this.decodeRecord(new web3_js_1.PublicKey(owner), recordInfo.data);
871
+ if (record.live)
872
+ records.push(record);
873
+ }
874
+ return records;
875
+ }
876
+ /**
877
+ * Reverse foreign-key lookup: rows of a child table that reference this row.
878
+ * Uses a child index on the FK column when one exists, otherwise scans the
879
+ * child table (bounded by `limit`).
880
+ */
881
+ async childrenOf(fkId, parentKey, options = {}) {
882
+ const inbound = this.inboundForeignKeys.find((candidate) => candidate.fkId === BigInt(fkId.toString()));
883
+ if (!inbound) {
884
+ throw new errors_1.PeridotBaseError("UnsupportedValue", `no inbound foreign key ${String(fkId)} on ${this.address.toBase58()}`);
885
+ }
886
+ const child = await V3Table.load(this.client, inbound.childTable);
887
+ const limit = options.limit ?? 1000;
888
+ const index = child.indexes.find((candidate) => candidate.column === inbound.childColumn && !candidate.unique);
889
+ if (index) {
890
+ const rows = await child.lookupIndex(index.name, parentKey);
891
+ return {
892
+ childTableId: child.tableId.toString(),
893
+ rows: rows.slice(0, limit).map((row) => rowObject(child, row.values)),
894
+ };
895
+ }
896
+ const rows = [];
897
+ let cursor = null;
898
+ while (rows.length < limit) {
899
+ const page = await child.scan({ limit: Math.min(500, limit - rows.length), cursor });
900
+ for (const row of page.rows) {
901
+ if (scalarEqual(row.values[inbound.childColumn], parentKey)) {
902
+ rows.push(rowObject(child, row.values));
903
+ }
904
+ }
905
+ cursor = page.cursor;
906
+ if (page.done || !cursor)
907
+ break;
908
+ }
909
+ return { childTableId: child.tableId.toString(), rows };
910
+ }
911
+ /** Column indices an index can answer without reading the record. */
912
+ coveredColumns(index) {
913
+ return [...index.columns, ...index.includes];
914
+ }
915
+ /**
916
+ * Planner for an equality lookup. `COVERING_INDEX_ONLY` means every requested
917
+ * column is in the index key or its INCLUDE payload, so the record accounts
918
+ * are never fetched.
919
+ */
920
+ async explainLookup(indexName, columns) {
921
+ const index = this.indexes.find((candidate) => candidate.name === indexName);
922
+ if (!index)
923
+ throw new errors_1.PeridotBaseError("UnsupportedValue", `unknown index ${indexName}`);
924
+ const covered = new Set(this.coveredColumns(index));
925
+ const uncovered = columns.filter((name) => {
926
+ const position = this.columns.findIndex((column) => column.name === name);
927
+ return position < 0 || !covered.has(position);
928
+ });
929
+ return {
930
+ strategy: uncovered.length === 0 ? "COVERING_INDEX_ONLY" : "INDEX_LOOKUP",
931
+ index: index.name,
932
+ uncovered,
933
+ };
934
+ }
935
+ /**
936
+ * Equality lookup served from the index alone. Returns `null` when the index
937
+ * does not cover every requested column (or when an entry predates covering
938
+ * payloads), so the caller falls back to `lookupIndex` + record fetch.
939
+ */
940
+ async lookupIndexCovered(indexName, value, columns) {
941
+ const index = this.indexes.find((candidate) => candidate.name === indexName);
942
+ if (!index)
943
+ throw new errors_1.PeridotBaseError("UnsupportedValue", `unknown index ${indexName}`);
944
+ if (index.columns.length !== 1)
945
+ return null;
946
+ const plan = await this.explainLookup(indexName, columns);
947
+ if (plan.strategy !== "COVERING_INDEX_ONLY")
948
+ return null;
949
+ if (columns.length === 0)
950
+ return null;
951
+ const keyColumn = index.columns[0];
952
+ const key = (0, values_1.coerceValue)(value, this.columns[keyColumn]);
953
+ if (key === null)
954
+ return [];
955
+ const includePositions = index.includes;
956
+ const build = (covering) => {
957
+ if (includePositions.length === 0)
958
+ return null;
959
+ const decoded = (0, values_1.decodeCoveringPayload)(covering, includePositions.length);
960
+ const row = {};
961
+ for (const name of columns) {
962
+ const position = this.columns.findIndex((column) => column.name === name);
963
+ if (position === keyColumn) {
964
+ row[name] = key;
965
+ continue;
966
+ }
967
+ const includeAt = includePositions.indexOf(position);
968
+ if (includeAt < 0)
969
+ return null;
970
+ row[name] = decoded[includeAt];
971
+ }
972
+ return row;
973
+ };
974
+ if (index.unique) {
975
+ const canonical = (0, values_1.canonicalTypedKeyV3)(key);
976
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
977
+ const [claim] = (0, pda_1.uniqueClaimPdaV3)(this.address, idxDigest, (0, values_1.uniqueDigestV3)(canonical));
978
+ const info = await this.client.connection.getAccountInfo(claim, "confirmed");
979
+ if (!info)
980
+ return [];
981
+ const decodedClaim = decodeUniqueClaim(info.data);
982
+ if (decodedClaim.owner.equals(web3_js_1.PublicKey.default))
983
+ return [];
984
+ const row = build(decodedClaim.covering);
985
+ return row ? [row] : null;
986
+ }
987
+ const canonical = (0, values_1.canonicalTypedKeyV3)(key);
988
+ const idxDigest = (0, pda_1.indexIdDigestV3)(this.address, this.config.epoch, index.indexId);
989
+ const valueDigest = (0, values_1.postingDigestV3)(canonical);
990
+ const laneAddresses = [];
991
+ for (let lane = 0; lane < this.config.postingLanes; lane += 1) {
992
+ laneAddresses.push((0, pda_1.postLanePdaV3)(this.address, idxDigest, valueDigest, lane)[0]);
993
+ }
994
+ const rows = [];
995
+ const infos = await this.fetchBatched(laneAddresses);
996
+ for (let lane = 0; lane < infos.length; lane += 1) {
997
+ if (!infos[lane])
998
+ continue;
999
+ for (let page = 0n;; page += 1n) {
1000
+ const [pagePda] = (0, pda_1.postPagePdaV3)(this.address, idxDigest, valueDigest, lane, page);
1001
+ const pageInfo = await this.client.connection.getAccountInfo(pagePda, "confirmed");
1002
+ if (!pageInfo)
1003
+ break;
1004
+ for (const member of decodePostingPage(pageInfo.data).members) {
1005
+ if (!member.live)
1006
+ continue;
1007
+ const row = build(member.covering);
1008
+ if (!row)
1009
+ return null;
1010
+ rows.push(row);
1011
+ }
1012
+ }
1013
+ }
1014
+ return rows;
1015
+ }
1016
+ /**
1017
+ * Resumable directory scan. Returns at most `limit` live rows and a cursor
1018
+ * that resumes exactly after the last visited entry. Tombstones are skipped
1019
+ * but still advance the cursor.
1020
+ */
1021
+ /**
1022
+ * Bounded traversal over the frozen directory.
1023
+ *
1024
+ * Lane headers, directory pages and record accounts are all fetched with
1025
+ * `getMultipleAccounts` (100 addresses per request). A row is only emitted
1026
+ * after its record account was read, so a missing page below the committed
1027
+ * tail is an integrity error rather than a silent skip.
1028
+ */
1029
+ async scan(options = {}) {
1030
+ const limit = options.limit ?? exports.DEFAULT_SCAN_PAGE;
1031
+ if (options.cursor && options.cursor.epoch !== this.config.epoch.toString()) {
1032
+ throw new errors_1.PeridotBaseError("StorageEpochMismatch", "cursor belongs to another storage epoch");
1033
+ }
1034
+ const firstLane = options.partition ?? 0;
1035
+ const lastLane = options.partition === undefined ? this.config.laneCount - 1 : options.partition;
1036
+ if (firstLane < 0 || lastLane >= this.config.laneCount) {
1037
+ throw new errors_1.PeridotBaseError("InvalidPartitionSpec", `partition ${firstLane} is out of range`);
1038
+ }
1039
+ const epoch = this.config.epoch;
1040
+ const rows = [];
1041
+ let lane = options.cursor?.lane ?? firstLane;
1042
+ let page = options.cursor?.page ?? 0n;
1043
+ let entry = options.cursor?.entry ?? 0;
1044
+ if (lane < firstLane || lane > lastLane) {
1045
+ throw new errors_1.PeridotBaseError("StorageEpochMismatch", "cursor is outside the requested partition");
1046
+ }
1047
+ if (lane > lastLane)
1048
+ return { rows, cursor: null, done: true };
1049
+ // Header cache: one request per 100 lanes, so 4.096 lanes cost ~41 requests.
1050
+ const laneCache = new Map();
1051
+ let loadedThrough = -1;
1052
+ const ensureLanes = async (index) => {
1053
+ const from = Math.floor(index / 100) * 100;
1054
+ if (loadedThrough >= from + 99 || laneCache.has(index))
1055
+ return;
1056
+ const to = Math.min(from + 100, lastLane + 1);
1057
+ const addresses = [];
1058
+ for (let current = from; current < to; current += 1) {
1059
+ addresses.push((0, pda_1.dirLanePdaV3)(this.address, epoch, current)[0]);
1060
+ }
1061
+ const infos = await this.fetchBatched(addresses);
1062
+ for (let offset = 0; offset < infos.length; offset += 1) {
1063
+ laneCache.set(from + offset, infos[offset]);
1064
+ }
1065
+ loadedThrough = Math.max(loadedThrough, to - 1);
1066
+ };
1067
+ // Directory pages and records travel in waves so the function never needs
1068
+ // more than a bounded number of accounts in flight.
1069
+ const PAGE_WAVE = 8;
1070
+ while (lane <= lastLane) {
1071
+ await ensureLanes(lane);
1072
+ const laneInfo = laneCache.get(lane) ?? (await this.fetchOneLane(lane));
1073
+ if (!laneInfo) {
1074
+ lane += 1;
1075
+ page = 0n;
1076
+ entry = 0;
1077
+ continue;
1078
+ }
1079
+ const tail = decodeDirectoryLane(laneInfo).tailPage;
1080
+ while (page <= tail) {
1081
+ const take = Math.min(PAGE_WAVE, Number(tail - page) + 1);
1082
+ const pageKeys = [];
1083
+ for (let offset = 0; offset < take; offset += 1) {
1084
+ pageKeys.push((0, pda_1.dirPagePdaV3)(this.address, epoch, lane, page + BigInt(offset))[0]);
1085
+ }
1086
+ const pageInfos = await this.fetchBatched(pageKeys);
1087
+ // Flatten this wave into ordered (page, index, digest) entries.
1088
+ const wave = [];
1089
+ for (let offset = 0; offset < take; offset += 1) {
1090
+ const info = pageInfos[offset];
1091
+ const pageNo = page + BigInt(offset);
1092
+ if (!info) {
1093
+ throw new errors_1.PeridotBaseError("MalformedAccount", `directory page ${pageNo} of lane ${lane} is missing below the committed tail`);
1094
+ }
1095
+ const digests = decodeDirectoryPage(info).digests;
1096
+ digests.forEach((digest, index) => {
1097
+ if (pageNo === page && index < entry)
1098
+ return;
1099
+ wave.push({ page: pageNo, index, digest });
1100
+ });
1101
+ }
1102
+ for (let offset = 0; offset < wave.length; offset += 100) {
1103
+ const chunk = wave.slice(offset, offset + 100);
1104
+ const recordKeys = chunk.map((item) => (0, pda_1.recordPdaV3)(this.address, epoch, item.digest)[0]);
1105
+ const recordInfos = await this.fetchBatched(recordKeys);
1106
+ for (let cursorIndex = 0; cursorIndex < chunk.length; cursorIndex += 1) {
1107
+ if (rows.length >= limit) {
1108
+ const item = chunk[cursorIndex];
1109
+ return {
1110
+ rows,
1111
+ cursor: { epoch: epoch.toString(), lane, page: item.page, entry: item.index },
1112
+ done: false,
1113
+ };
1114
+ }
1115
+ const info = recordInfos[cursorIndex];
1116
+ if (!info)
1117
+ continue;
1118
+ const record = this.decodeRecord(recordKeys[cursorIndex], info);
1119
+ if (record.live)
1120
+ rows.push(record);
1121
+ }
1122
+ }
1123
+ page += BigInt(take);
1124
+ entry = 0;
1125
+ }
1126
+ lane += 1;
1127
+ page = 0n;
1128
+ entry = 0;
1129
+ }
1130
+ return { rows, cursor: null, done: true };
1131
+ }
1132
+ /**
1133
+ * Gate account for Member writes, or null for the owner/admin path.
1134
+ *
1135
+ * Only an organization member without an elevated project grant must record
1136
+ * the external-write evidence, and the first such insert creates the gate
1137
+ * atomically with the record (PRD §6.2).
1138
+ */
1139
+ async externalGateAccount() {
1140
+ const anyProgram = this.client.program;
1141
+ const database = await anyProgram.account.databaseCatalog.fetch(this.client.databaseAddress());
1142
+ const organization = new web3_js_1.PublicKey(database.organization);
1143
+ try {
1144
+ const org = await anyProgram.account.organization.fetch(organization);
1145
+ if (new web3_js_1.PublicKey(org.owner).equals(this.client.wallet))
1146
+ return null;
1147
+ }
1148
+ catch {
1149
+ return null;
1150
+ }
1151
+ try {
1152
+ const grant = await anyProgram.account.roleGrant.fetch(this.client.roleAddress(this.client.wallet));
1153
+ const kind = Object.keys(grant.role ?? {})[0];
1154
+ if (kind === "owner" || kind === "admin")
1155
+ return null;
1156
+ }
1157
+ catch {
1158
+ // No project grant: organization membership alone makes this a Member.
1159
+ }
1160
+ return (0, pda_1.extGatePdaV3)(this.client.databaseAddress(), this.client.programId)[0];
1161
+ }
1162
+ /** `query.page()` equivalent: one bounded page of results. */
1163
+ async page(options = {}) {
1164
+ return this.scan(options);
1165
+ }
1166
+ /** `query.stream()` equivalent: yields rows without materializing the table. */
1167
+ async *stream(options = {}) {
1168
+ const pageSize = options.limit ?? exports.DEFAULT_SCAN_PAGE;
1169
+ let cursor = null;
1170
+ do {
1171
+ const result = await this.scan({
1172
+ limit: pageSize,
1173
+ cursor,
1174
+ partition: options.partition,
1175
+ });
1176
+ for (const row of result.rows)
1177
+ yield row;
1178
+ cursor = result.cursor;
1179
+ if (!cursor)
1180
+ return;
1181
+ } while (true);
1182
+ }
1183
+ async fetchOneLane(lane) {
1184
+ const [pda] = (0, pda_1.dirLanePdaV3)(this.address, this.config.epoch, lane);
1185
+ const info = await this.client.connection.getAccountInfo(pda, "confirmed");
1186
+ return info ? info.data : null;
1187
+ }
1188
+ /** Drains `scan()` into memory, honouring a hard cap. */
1189
+ async scanAll(options = {}) {
1190
+ const cap = options.cap ?? 10000;
1191
+ const rows = [];
1192
+ let cursor = null;
1193
+ for (;;) {
1194
+ const page = await this.scan({
1195
+ limit: exports.DEFAULT_SCAN_PAGE,
1196
+ cursor,
1197
+ partition: options.partition,
1198
+ });
1199
+ rows.push(...page.rows);
1200
+ if (rows.length > cap) {
1201
+ throw new errors_1.PeridotBaseError("ROW_TOO_LARGE", `scan exceeded cap ${cap}; stream instead`);
1202
+ }
1203
+ if (page.done || !page.cursor)
1204
+ return rows;
1205
+ cursor = page.cursor;
1206
+ }
1207
+ }
1208
+ /**
1209
+ * Raw-state invariant audit (PRD §12).
1210
+ *
1211
+ * Re-derives everything from directory/record/claim/posting accounts, never
1212
+ * from SDK caches: one directory slot per identity, no duplicate digest, no
1213
+ * missing record below the committed tail, locator agreement, exactly one
1214
+ * LIVE claim per LIVE unique value, and exactly one LIVE posting membership
1215
+ * per LIVE indexed value.
1216
+ */
1217
+ async auditInvariants() {
1218
+ const epoch = this.config.epoch;
1219
+ const table = this.address;
1220
+ const anyProgram = this.client.program;
1221
+ const report = {
1222
+ directoryEntries: 0,
1223
+ liveRecords: 0,
1224
+ tombstones: 0,
1225
+ duplicateDirectoryDigests: [],
1226
+ missingRecords: [],
1227
+ locatorMismatches: [],
1228
+ revisionProblems: [],
1229
+ uniqueClaimProblems: [],
1230
+ postingProblems: [],
1231
+ checkedConstraints: true,
1232
+ };
1233
+ // ---- directory -------------------------------------------------------
1234
+ const entries = [];
1235
+ const seen = new Map();
1236
+ for (let base = 0; base < this.config.laneCount; base += 100) {
1237
+ const laneAddrs = [];
1238
+ const laneIds = [];
1239
+ for (let lane = base; lane < Math.min(base + 100, this.config.laneCount); lane += 1) {
1240
+ laneAddrs.push((0, pda_1.dirLanePdaV3)(table, epoch, lane)[0]);
1241
+ laneIds.push(lane);
1242
+ }
1243
+ const laneInfos = await this.fetchBatched(laneAddrs);
1244
+ for (let slot = 0; slot < laneInfos.length; slot += 1) {
1245
+ const info = laneInfos[slot];
1246
+ if (!info)
1247
+ continue;
1248
+ const lane = laneIds[slot];
1249
+ const tail = decodeDirectoryLane(info).tailPage;
1250
+ let pageNo = 0n;
1251
+ while (pageNo <= tail) {
1252
+ const take = Math.min(8, Number(tail - pageNo) + 1);
1253
+ const pageAddrs = [];
1254
+ for (let offset = 0; offset < take; offset += 1) {
1255
+ pageAddrs.push((0, pda_1.dirPagePdaV3)(table, epoch, lane, pageNo + BigInt(offset))[0]);
1256
+ }
1257
+ const pageInfos = await this.fetchBatched(pageAddrs);
1258
+ for (let offset = 0; offset < take; offset += 1) {
1259
+ const current = pageNo + BigInt(offset);
1260
+ const pageInfo = pageInfos[offset];
1261
+ if (!pageInfo) {
1262
+ report.missingRecords.push(`lane ${lane} page ${current}: missing directory page`);
1263
+ continue;
1264
+ }
1265
+ const decoded = decodeDirectoryPage(pageInfo);
1266
+ if (decoded.lane !== lane || decoded.page !== current) {
1267
+ report.locatorMismatches.push(`lane ${lane} page ${current}: header says ${decoded.lane}/${decoded.page}`);
1268
+ }
1269
+ decoded.digests.forEach((digest, index) => {
1270
+ const hex = Buffer.from(digest).toString("hex");
1271
+ report.directoryEntries += 1;
1272
+ const previous = seen.get(hex);
1273
+ if (previous) {
1274
+ report.duplicateDirectoryDigests.push(`${hex} at ${previous} and ${lane}/${current}/${index}`);
1275
+ }
1276
+ else {
1277
+ seen.set(hex, `${lane}/${current}/${index}`);
1278
+ }
1279
+ entries.push({ lane, page: current, index, digest: Buffer.from(digest) });
1280
+ });
1281
+ }
1282
+ pageNo += BigInt(take);
1283
+ }
1284
+ }
1285
+ }
1286
+ // ---- records ---------------------------------------------------------
1287
+ const live = [];
1288
+ const dead = [];
1289
+ for (let offset = 0; offset < entries.length; offset += 100) {
1290
+ const chunk = entries.slice(offset, offset + 100);
1291
+ const addrs = chunk.map((entry) => (0, pda_1.recordPdaV3)(table, epoch, entry.digest)[0]);
1292
+ const infos = await this.fetchBatched(addrs);
1293
+ for (let slot = 0; slot < chunk.length; slot += 1) {
1294
+ const entry = chunk[slot];
1295
+ const info = infos[slot];
1296
+ if (!info) {
1297
+ report.missingRecords.push(`lane ${entry.lane} page ${entry.page} slot ${entry.index}: record missing`);
1298
+ continue;
1299
+ }
1300
+ const record = this.decodeRecord(addrs[slot], info);
1301
+ const raw = anyProgram.coder.accounts.decodeAny(info);
1302
+ if (!Buffer.from(raw.pkDigest).equals(entry.digest)) {
1303
+ report.locatorMismatches.push(`${addrs[slot].toBase58()}: digest mismatch`);
1304
+ }
1305
+ if (Number(raw.dirLane) !== entry.lane || BigInt(raw.dirPage) !== entry.page || Number(raw.dirSlot) !== entry.index) {
1306
+ report.locatorMismatches.push(`${addrs[slot].toBase58()}: locator mismatch`);
1307
+ }
1308
+ if (record.live) {
1309
+ report.liveRecords += 1;
1310
+ live.push({ address: addrs[slot], values: record.values, entry });
1311
+ }
1312
+ else {
1313
+ report.tombstones += 1;
1314
+ dead.push({ address: addrs[slot], values: record.values });
1315
+ }
1316
+ }
1317
+ }
1318
+ // ---- unique claims ---------------------------------------------------
1319
+ for (const index of this.indexes.filter((candidate) => candidate.unique)) {
1320
+ const idxDigest = (0, pda_1.indexIdDigestV3)(table, epoch, index.indexId);
1321
+ const probes = [];
1322
+ const consider = (row) => {
1323
+ const value = row.values[index.column];
1324
+ if (value === null || value === undefined)
1325
+ return;
1326
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
1327
+ probes.push({
1328
+ pda: (0, pda_1.uniqueClaimPdaV3)(table, idxDigest, (0, values_1.uniqueDigestV3)(key))[0],
1329
+ key: Buffer.from(key),
1330
+ owner: row.address,
1331
+ label: row.address.toBase58(),
1332
+ });
1333
+ };
1334
+ live.forEach(consider);
1335
+ for (let offset = 0; offset < probes.length; offset += 100) {
1336
+ const chunk = probes.slice(offset, offset + 100);
1337
+ const infos = await this.fetchBatched(chunk.map((probe) => probe.pda));
1338
+ chunk.forEach((probe, slot) => {
1339
+ const info = infos[slot];
1340
+ if (!info) {
1341
+ report.uniqueClaimProblems.push(`${probe.label}: missing claim for ${index.name}`);
1342
+ return;
1343
+ }
1344
+ const claim = decodeUniqueClaim(info);
1345
+ if (!claim.owner.equals(probe.owner)) {
1346
+ report.uniqueClaimProblems.push(`${probe.label}: claim for ${index.name} owned by ${claim.owner.toBase58()}`);
1347
+ }
1348
+ if (!Buffer.from(claim.key).equals(probe.key)) {
1349
+ report.uniqueClaimProblems.push(`${probe.label}: claim key mismatch on ${index.name}`);
1350
+ }
1351
+ });
1352
+ }
1353
+ // Tombstones must not keep a LIVE claim.
1354
+ for (const row of dead) {
1355
+ const value = row.values[index.column];
1356
+ if (value === null || value === undefined)
1357
+ continue;
1358
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
1359
+ const [pda] = (0, pda_1.uniqueClaimPdaV3)(table, idxDigest, (0, values_1.uniqueDigestV3)(key));
1360
+ const info = await this.client.connection.getAccountInfo(pda, "confirmed");
1361
+ if (info && decodeUniqueClaim(info.data).owner.equals(row.address)) {
1362
+ report.uniqueClaimProblems.push(`${row.address.toBase58()}: tombstone still owns claim on ${index.name}`);
1363
+ }
1364
+ }
1365
+ }
1366
+ // ---- posting memberships --------------------------------------------
1367
+ for (const index of this.indexes.filter((candidate) => !candidate.unique)) {
1368
+ const idxDigest = (0, pda_1.indexIdDigestV3)(table, epoch, index.indexId);
1369
+ for (const row of live) {
1370
+ const value = row.values[index.column];
1371
+ if (value === null || value === undefined)
1372
+ continue;
1373
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
1374
+ const valueDigest = (0, values_1.postingDigestV3)(key);
1375
+ const laneAddrs = [];
1376
+ for (let lane = 0; lane < this.config.postingLanes; lane += 1) {
1377
+ laneAddrs.push((0, pda_1.postLanePdaV3)(table, idxDigest, valueDigest, lane)[0]);
1378
+ }
1379
+ const laneInfos = await this.fetchBatched(laneAddrs);
1380
+ let memberships = 0;
1381
+ for (let lane = 0; lane < laneInfos.length; lane += 1) {
1382
+ if (!laneInfos[lane])
1383
+ continue;
1384
+ let pageNo = 0n;
1385
+ for (;;) {
1386
+ const [pda] = (0, pda_1.postPagePdaV3)(table, idxDigest, valueDigest, lane, pageNo);
1387
+ const info = await this.client.connection.getAccountInfo(pda, "confirmed");
1388
+ if (!info)
1389
+ break;
1390
+ for (const member of decodePostingPage(info.data).members) {
1391
+ if (member.live && member.record.equals(row.address))
1392
+ memberships += 1;
1393
+ }
1394
+ pageNo += 1n;
1395
+ }
1396
+ }
1397
+ if (memberships !== 1) {
1398
+ report.postingProblems.push(`${row.address.toBase58()}: ${memberships} live memberships on ${index.name}`);
1399
+ }
1400
+ }
1401
+ for (const row of dead) {
1402
+ const value = row.values[index.column];
1403
+ if (value === null || value === undefined)
1404
+ continue;
1405
+ const key = (0, values_1.canonicalTypedKeyV3)((0, values_1.coerceValue)(value, this.columns[index.column]));
1406
+ const valueDigest = (0, values_1.postingDigestV3)(key);
1407
+ for (let lane = 0; lane < this.config.postingLanes; lane += 1) {
1408
+ const [lanePda] = (0, pda_1.postLanePdaV3)(table, idxDigest, valueDigest, lane);
1409
+ if (!(await this.client.connection.getAccountInfo(lanePda, "confirmed")))
1410
+ continue;
1411
+ let pageNo = 0n;
1412
+ for (;;) {
1413
+ const [pda] = (0, pda_1.postPagePdaV3)(table, idxDigest, valueDigest, lane, pageNo);
1414
+ const info = await this.client.connection.getAccountInfo(pda, "confirmed");
1415
+ if (!info)
1416
+ break;
1417
+ for (const member of decodePostingPage(info.data).members) {
1418
+ if (member.live && member.record.equals(row.address)) {
1419
+ report.postingProblems.push(`${row.address.toBase58()}: tombstone still posted on ${index.name}`);
1420
+ }
1421
+ }
1422
+ pageNo += 1n;
1423
+ }
1424
+ }
1425
+ }
1426
+ }
1427
+ return report;
1428
+ }
1429
+ async fetchBatched(addresses) {
1430
+ const out = [];
1431
+ for (let offset = 0; offset < addresses.length; offset += 100) {
1432
+ const chunk = addresses.slice(offset, offset + 100);
1433
+ const infos = await this.client.connection.getMultipleAccountsInfo(chunk, "confirmed");
1434
+ for (const info of infos)
1435
+ out.push(info ? info.data : null);
1436
+ }
1437
+ return out;
1438
+ }
1439
+ }
1440
+ exports.V3Table = V3Table;
1441
+ /**
1442
+ * Copies a frozen v2 table into this v3 table.
1443
+ *
1444
+ * The caller must pause the protocol first: `paused` is the program-enforced
1445
+ * write freeze, and both v2 DML and these migration instructions reject writes
1446
+ * while it is set. Every row is read from the on-chain v2 page by the program,
1447
+ * so this driver only supplies addresses and slot numbers.
1448
+ */
1449
+ async function migrateV2TableToV3(client, tableId, options = {}) {
1450
+ const table = await V3Table.load(client, tableId);
1451
+ const anyProgram = client.program;
1452
+ const [manifest] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("pd"), Buffer.from("migrate-v3"), table.address.toBuffer()], client.programId);
1453
+ const signatures = [];
1454
+ const existing = await client.connection.getAccountInfo(manifest, "confirmed");
1455
+ if (!existing) {
1456
+ const signature = await anyProgram.methods
1457
+ .beginMigrationV3({
1458
+ tableId: new bn_js_1.default(tableId.toString()),
1459
+ epoch: new bn_js_1.default(table.config.epoch.toString()),
1460
+ })
1461
+ .accounts({
1462
+ protocol: client.protocolAddress,
1463
+ database: client.databaseAddress(),
1464
+ authority: client.wallet,
1465
+ table: table.address,
1466
+ storage: table.storage,
1467
+ manifest,
1468
+ systemProgram: web3_js_1.SystemProgram.programId,
1469
+ })
1470
+ .remainingAccounts(await client.roleHelpers())
1471
+ .rpc();
1472
+ signatures.push(signature);
1473
+ }
1474
+ else if (!options.resume) {
1475
+ throw new errors_1.PeridotBaseError("AlreadyInitialized", "migration manifest already exists");
1476
+ }
1477
+ const pages = await anyProgram.account.dataPage.all([
1478
+ { memcmp: { offset: 10, bytes: table.address.toBase58() } },
1479
+ ]);
1480
+ pages.sort((a, b) => a.account.shardId - b.account.shardId || a.account.pageNo - b.account.pageNo);
1481
+ let rows = 0;
1482
+ for (const entry of pages) {
1483
+ const page = entry.account;
1484
+ for (let slot = 0; slot < page.rows.length; slot += 1) {
1485
+ const row = page.rows[slot];
1486
+ if ((row.flags & 0x01) === 0)
1487
+ continue;
1488
+ const pk = row.values[table.primaryKey];
1489
+ const digest = table.digestOf(decodeV2Value(pk));
1490
+ const [record] = (0, pda_1.recordPdaV3)(table.address, table.config.epoch, digest);
1491
+ const decodedValues = row.values.map((value) => decodeV2Value(value));
1492
+ const extras = table.indexAccounts(decodedValues, digest);
1493
+ const { lane, lanePda, pagePda } = await table.ensureDirectory(digest, decodedValues);
1494
+ const signature = await anyProgram.methods
1495
+ .migrateRowV3({
1496
+ tableId: new bn_js_1.default(tableId.toString()),
1497
+ epoch: new bn_js_1.default(table.config.epoch.toString()),
1498
+ shardId: page.shardId,
1499
+ pageNo: page.pageNo,
1500
+ slot,
1501
+ pkDigest: Array.from(digest),
1502
+ })
1503
+ .accounts({
1504
+ protocol: client.protocolAddress,
1505
+ database: client.databaseAddress(),
1506
+ authority: client.wallet,
1507
+ table: table.address,
1508
+ storage: table.storage,
1509
+ manifest,
1510
+ sourcePage: entry.publicKey,
1511
+ payer: client.wallet,
1512
+ record,
1513
+ systemProgram: web3_js_1.SystemProgram.programId,
1514
+ })
1515
+ .remainingAccounts([
1516
+ ...(await client.roleHelpers()),
1517
+ { pubkey: lanePda, isWritable: true, isSigner: false },
1518
+ { pubkey: pagePda, isWritable: true, isSigner: false },
1519
+ ...extras.map((pubkey) => ({ pubkey, isWritable: true, isSigner: false })),
1520
+ ])
1521
+ .rpc();
1522
+ signatures.push(signature);
1523
+ rows += 1;
1524
+ void lane;
1525
+ }
1526
+ }
1527
+ signatures.push(await anyProgram.methods
1528
+ .finishMigrationV3({
1529
+ tableId: new bn_js_1.default(tableId.toString()),
1530
+ epoch: new bn_js_1.default(table.config.epoch.toString()),
1531
+ expectedRows: new bn_js_1.default(rows.toString()),
1532
+ })
1533
+ .accounts({
1534
+ protocol: client.protocolAddress,
1535
+ database: client.databaseAddress(),
1536
+ table: table.address,
1537
+ manifest,
1538
+ })
1539
+ .rpc());
1540
+ return { pages: pages.length, rows, manifest, signatures };
1541
+ }
1542
+ /** Converts a decoded v2 `Value` enum into the SDK's canonical shape. */
1543
+ function decodeV2Value(value) {
1544
+ const key = Object.keys(value)[0];
1545
+ const payload = value[key];
1546
+ const unwrap = Array.isArray(payload) ? payload[0] : payload?.["0"] ?? payload;
1547
+ switch (key) {
1548
+ case "null":
1549
+ return null;
1550
+ case "bool":
1551
+ return Boolean(unwrap);
1552
+ case "i64":
1553
+ return BigInt(unwrap.toString());
1554
+ case "text":
1555
+ return String(unwrap);
1556
+ case "uuid":
1557
+ return Uint8Array.from(unwrap);
1558
+ case "decimal":
1559
+ return {
1560
+ decimal: BigInt((Array.isArray(payload) ? payload[0] : payload["0"]).toString()),
1561
+ scale: Number(Array.isArray(payload) ? payload[1] : payload["1"]),
1562
+ };
1563
+ default:
1564
+ return null;
1565
+ }
1566
+ }
1567
+ function migrationManifestPda(client, table) {
1568
+ return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("pd"), Buffer.from("migrate-v3"), table.toBuffer()], client.programId)[0];
1569
+ }
1570
+ /**
1571
+ * Re-reads every copied v2 row from v3 and advances the manifest checkpoint.
1572
+ *
1573
+ * The program recomputes each PK digest and requires a LIVE record with the same
1574
+ * digest, so a client cannot declare coverage it did not actually achieve.
1575
+ */
1576
+ async function verifyV3Coverage(client, tableId) {
1577
+ const table = await V3Table.load(client, tableId);
1578
+ const anyProgram = client.program;
1579
+ const manifest = migrationManifestPda(client, table.address);
1580
+ const pages = await anyProgram.account.dataPage.all([
1581
+ { memcmp: { offset: 10, bytes: table.address.toBase58() } },
1582
+ ]);
1583
+ pages.sort((a, b) => a.account.shardId - b.account.shardId || a.account.pageNo - b.account.pageNo);
1584
+ const signatures = [];
1585
+ let rows = 0;
1586
+ for (const entry of pages) {
1587
+ const page = entry.account;
1588
+ const records = [];
1589
+ for (const row of page.rows) {
1590
+ if ((row.flags & 0x01) === 0)
1591
+ continue;
1592
+ const digest = table.digestOf(decodeV2Value(row.values[table.primaryKey]));
1593
+ records.push((0, pda_1.recordPdaV3)(table.address, table.config.epoch, digest)[0]);
1594
+ }
1595
+ const signature = await anyProgram.methods
1596
+ .verifyMigrationPageV3({
1597
+ tableId: new bn_js_1.default(tableId.toString()),
1598
+ epoch: new bn_js_1.default(table.config.epoch.toString()),
1599
+ shardId: page.shardId,
1600
+ pageNo: page.pageNo,
1601
+ })
1602
+ .accounts({
1603
+ protocol: client.protocolAddress,
1604
+ database: client.databaseAddress(),
1605
+ authority: client.wallet,
1606
+ table: table.address,
1607
+ storage: table.storage,
1608
+ manifest,
1609
+ sourcePage: entry.publicKey,
1610
+ })
1611
+ .remainingAccounts(records.map((pubkey) => ({ pubkey, isWritable: false, isSigner: false })))
1612
+ .rpc();
1613
+ signatures.push(signature);
1614
+ rows += records.length;
1615
+ }
1616
+ return { pages: pages.length, rows, signatures };
1617
+ }
1618
+ /**
1619
+ * Atomic cutover: publishes the v3 storage and retires the v2 layout in one
1620
+ * transaction. Requires a READY manifest with complete coverage and a paused
1621
+ * protocol.
1622
+ */
1623
+ async function activateV3Table(client, tableId) {
1624
+ const table = await V3Table.load(client, tableId);
1625
+ const anyProgram = client.program;
1626
+ const manifest = migrationManifestPda(client, table.address);
1627
+ const [activation] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("pd"), Buffer.from("active-v3"), table.address.toBuffer()], client.programId);
1628
+ const signature = await anyProgram.methods
1629
+ .activateStorageV3({
1630
+ tableId: new bn_js_1.default(tableId.toString()),
1631
+ epoch: new bn_js_1.default(table.config.epoch.toString()),
1632
+ })
1633
+ .accounts({
1634
+ protocol: client.protocolAddress,
1635
+ database: client.databaseAddress(),
1636
+ authority: client.wallet,
1637
+ table: table.address,
1638
+ storage: table.storage,
1639
+ manifest,
1640
+ activation,
1641
+ systemProgram: web3_js_1.SystemProgram.programId,
1642
+ })
1643
+ .rpc();
1644
+ return { activation, signature };
1645
+ }
1646
+ /** Convenience wrapper: loads the table and audits its raw on-chain state. */
1647
+ async function verifyV3Invariants(client, tableId) {
1648
+ return (await V3Table.load(client, tableId)).auditInvariants();
1649
+ }