@mnmal-ai/substrate 1.0.0-alpha.2 → 1.0.0-alpha.21

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 (53) hide show
  1. package/README.md +64 -14
  2. package/dist/boot-store-Dz6PGwNY.js +4079 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-BeVye_Oj.d.ts} +2 -87
  4. package/dist/cli-CH7M6ZTQ.js +3383 -0
  5. package/dist/client.browser.js +2485 -0
  6. package/dist/client.d.ts +273 -135
  7. package/dist/client.js +6 -6
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-CoHLKAX0.d.ts} +44 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-D7XRAGC6.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/pg-edges-store-Dnaxesmy.js +443 -0
  19. package/dist/{plugin-QuJN9pG_.js → plugin-BIz4Pr5-.js} +132 -8
  20. package/dist/proposals-bootstrap.js +6 -5
  21. package/dist/proposals.config.schema.json +5 -0
  22. package/dist/proposals.d.ts +17 -5
  23. package/dist/proposals.default-config.json +2 -1
  24. package/dist/proposals.js +2 -3
  25. package/dist/recall-bootstrap.js +5 -4
  26. package/dist/recall.config.schema.json +6 -0
  27. package/dist/recall.d.ts +35 -6
  28. package/dist/recall.js +2 -3
  29. package/dist/{repl-C52wyfMs.js → repl-BUkd9DPZ.js} +65 -33
  30. package/dist/{row-ByLFE2Wx.d.ts → row-aEWVHEsf.d.ts} +92 -12
  31. package/dist/run-Cu9w5Y10.js +2435 -0
  32. package/dist/{plugin-t2g2wX0b.d.ts → schema-DwnXxdjk.d.ts} +1293 -63
  33. package/dist/script-A9dxMRZA.js +143 -0
  34. package/dist/script-runner.js +77 -0
  35. package/dist/sdk.d.ts +227 -38
  36. package/dist/sdk.js +5 -110
  37. package/dist/semver-D_zdq0hi.js +17 -0
  38. package/dist/{src-DWm0iA88.js → src--accZ5Ka.js} +188 -87
  39. package/dist/{src-DMzc3HfW.js → src-BNdhH_Hx.js} +745 -851
  40. package/dist/{src-CG7giuHr.js → src-BQnDrs_E.js} +793 -75
  41. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  42. package/dist/src-BbCUeMsI.js +7723 -0
  43. package/dist/{src-CHp3QyqB.js → src-BmJD4ScT.js} +9215 -3376
  44. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  45. package/dist/substrate-admin.js +17 -782
  46. package/dist/substrate.js +4 -5487
  47. package/dist/testing.d.ts +730 -53
  48. package/dist/testing.js +20 -163
  49. package/dist/{ws-C72iVS5T.d.ts → ws-DJaKruX-.d.ts} +4 -5
  50. package/package.json +26 -26
  51. package/dist/dataset-BQ8egGl5.js +0 -1535
  52. package/dist/schema-g4FQLr0V.d.ts +0 -433
  53. package/dist/src-CXKnqeTW.js +0 -2339
@@ -1,5 +1,5 @@
1
- import { l as PackEnvelope, n as FieldDef, s as FieldInput, u as Schema } from "./schema-g4FQLr0V.js";
2
- import { pack as packFrame, unpack as unpackFrame } from "msgpackr";
1
+ import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema } from "./schema-DwnXxdjk.js";
2
+ import * as msgpackr from "msgpackr";
3
3
  //#region ../../packages/substrate-pack/src/decoder.d.ts
4
4
  interface DecodeContext {
5
5
  schemas?: Record<string, Schema>;
@@ -12,7 +12,7 @@ interface DecodeEnvelopeCtx {
12
12
  * A key listed here is decoded using `decodePositionalFromFieldDef` instead
13
13
  * of the client-sent FieldInput.
14
14
  */
15
- returnsByKey?: Record<string, FieldDef>;
15
+ returnsByKey?: Record<string, FieldDef | readonly FieldDef[]>;
16
16
  typeByKey: Record<string, string>;
17
17
  schemas: Record<string, Schema>;
18
18
  currentNsByKey: Record<string, string>;
@@ -58,12 +58,8 @@ declare function decodePositional<T = unknown>(encoded: unknown, fields: FieldIn
58
58
  declare function decodePositionalFromFieldDef<T = unknown>(encoded: unknown, def: FieldDef, schema: Schema, ctx: DecodeContext, path?: string[]): T;
59
59
  declare function decodeEnvelope(bytes: Buffer | Uint8Array, ctx: DecodeEnvelopeCtx): PackEnvelope;
60
60
  //#endregion
61
- //#region ../../packages/substrate-pack/src/index.d.ts
62
- /**
63
- * WebSocket subprotocol advertised in `Sec-WebSocket-Protocol` at handshake
64
- * time. Connections negotiating this subprotocol receive msgpack frames with
65
- * positionally-encoded `data`; anything else falls back to JSON.
66
- */
67
- declare const WS_SUBPROTOCOL_SUBSTRATE_PACK = "substrate-pack";
61
+ //#region ../../packages/substrate-pack/src/msgpackr.d.ts
62
+ declare const pack: (...args: Parameters<typeof msgpackr.pack>) => ReturnType<typeof msgpackr.pack>;
63
+ declare const unpack: (...args: Parameters<typeof msgpackr.unpack>) => ReturnType<typeof msgpackr.unpack>;
68
64
  //#endregion
69
- export { DecodeEnvelopeCtx as a, decodeEnvelope as c, DecodeContext as i, decodePositional as l, packFrame as n, PackDecodeError as o, unpackFrame as r, SchemaDriftError as s, WS_SUBPROTOCOL_SUBSTRATE_PACK as t, decodePositionalFromFieldDef as u };
65
+ export { PackDecodeError as a, decodePositional as c, DecodeEnvelopeCtx as i, decodePositionalFromFieldDef as l, unpack as n, SchemaDriftError as o, DecodeContext as r, decodeEnvelope as s, pack as t };
@@ -0,0 +1,16 @@
1
+ import * as msgpackr from "msgpackr";
2
+
3
+ //#region ../../packages/substrate-pack/src/msgpackr.ts
4
+ /**
5
+ * The one module that imports msgpackr. The published bundle gives it a chunk
6
+ * of its own, so a consumer that never packs or unpacks drops msgpackr, which
7
+ * does not declare itself free of load-time side effects. These are wrappers,
8
+ * not re-exports: a bundler resolves a re-export straight to msgpackr, which
9
+ * would leave every importer of this module importing msgpackr itself.
10
+ */
11
+ const pack = (...args) => msgpackr.pack(...args);
12
+ const unpack = (...args) => msgpackr.unpack(...args);
13
+ const createUnpackr = (options) => new msgpackr.Unpackr(options);
14
+
15
+ //#endregion
16
+ export { pack as n, unpack as r, createUnpackr as t };
@@ -0,0 +1,32 @@
1
+ //#region src/node-version.ts
2
+ /** The oldest Node the binaries run on; matches `engines.node` in package.json. */
3
+ const MIN_NODE_VERSION = "26.13.1";
4
+ /** Returns a refusal message when `version` (e.g. `process.versions.node`) is below the minimum, else null. */
5
+ function nodeVersionRefusal(version) {
6
+ const have = version.split(".").map(Number);
7
+ const want = MIN_NODE_VERSION.split(".").map(Number);
8
+ for (let i = 0; i < 3; i++) {
9
+ const a = have[i] ?? 0;
10
+ const b = want[i] ?? 0;
11
+ if (a > b) return null;
12
+ if (a < b) return `substrate requires Node ${MIN_NODE_VERSION} or newer; this is Node ${version}`;
13
+ }
14
+ return null;
15
+ }
16
+ /**
17
+ * The refusal for this runtime, or null. Bun is exempt: it reports a Node
18
+ * compatibility version (24.x) that says nothing about its own security fixes.
19
+ */
20
+ function runtimeRefusal(versions) {
21
+ return versions.bun !== void 0 ? null : nodeVersionRefusal(versions.node);
22
+ }
23
+ /** Exits the process with a refusal when the running Node is below the minimum. */
24
+ function assertNodeVersion() {
25
+ const refusal = runtimeRefusal(process.versions);
26
+ if (refusal === null) return;
27
+ process.stderr.write(`${refusal}\n`);
28
+ process.exit(1);
29
+ }
30
+
31
+ //#endregion
32
+ export { assertNodeVersion as t };
package/dist/pack.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { l as PackEnvelope, n as FieldDef, s as FieldInput, u as Schema } from "./schema-g4FQLr0V.js";
2
- import { a as DecodeEnvelopeCtx, c as decodeEnvelope, i as DecodeContext, l as decodePositional, n as packFrame, o as PackDecodeError, r as unpackFrame, s as SchemaDriftError, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, u as decodePositionalFromFieldDef } from "./index-D7mSOFlM.js";
1
+ import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema, u as MutationSchema } from "./schema-DwnXxdjk.js";
2
+ import { a as PackDecodeError, c as decodePositional, i as DecodeEnvelopeCtx, l as decodePositionalFromFieldDef, n as unpack, o as SchemaDriftError, r as DecodeContext, s as decodeEnvelope, t as pack } from "./index-D7XRAGC6.js";
3
3
  //#region ../../packages/substrate-pack/src/content-type.d.ts
4
4
  /**
5
5
  * Content-type negotiation. Spec: §7.0.
@@ -26,9 +26,10 @@ interface EncodeEnvelopeCtx {
26
26
  /**
27
27
  * Mutation-path return-shape map — keyed by envelope key. Mutation responses
28
28
  * don't carry a client-sent FieldInput; their shape is declared at registry
29
- * time as `MutationSchema.returns` and wired through here.
29
+ * time as `MutationSchema.returns` and wired through here. An array gives a
30
+ * batched key one shape per frame.
30
31
  */
31
- returnsByKey?: Record<string, FieldDef>;
32
+ returnsByKey?: Record<string, FieldDef | readonly FieldDef[]>;
32
33
  /** Query-path type-name map — keyed by envelope key. */
33
34
  typeByKey: Record<string, string>;
34
35
  schemas: Record<string, Schema>;
@@ -61,6 +62,31 @@ export declare function encodePositional(value: unknown, fields: FieldInput, sch
61
62
  */
62
63
  export declare function encodePositionalFromFieldDef(value: unknown, def: FieldDef, schema: Schema, ctx: EncodeContext, path?: string[]): unknown;
63
64
  export declare function encodeEnvelope(envelope: PackEnvelope, ctx: EncodeEnvelopeCtx): Buffer;
65
+ /**
66
+ * The wire form of `envelope.data[key]`, or of `value` in its place: rows as
67
+ * positional tuples, or the value as-is when nothing positions it. A `list`
68
+ * value's rows encode one by one, so a slice of its rows gives that slice of
69
+ * the whole value's wire form.
70
+ */
71
+ export declare function positionValue(envelope: PackEnvelope, ctx: EncodeEnvelopeCtx, key: string, value?: unknown): unknown;
72
+ /** `envelope` with `data` replaced by its wire form; `pack` of it is the response body. */
73
+ export declare function withData(envelope: PackEnvelope, data: Record<string, unknown>): PackEnvelope;
74
+ /**
75
+ * `pack(wire)` in pieces, a long row list `rowsPerPart` rows per piece, for a
76
+ * `wire` envelope from `withData`. msgpackr's default `pack` writes every
77
+ * object as a map16 (`de`) and records no shared state between values, so
78
+ * the pieces concatenate to the same bytes.
79
+ */
80
+ export declare function packEnvelopeParts(wire: PackEnvelope, rowsPerPart: number): Generator<Uint8Array>;
81
+ //#endregion
82
+ //#region ../../packages/substrate-pack/src/mutation-returns.d.ts
83
+ /** What a row-writing mutation answers when the frame names no `fields`. */
84
+ export declare const MUTATION_ACK_FIELDS: {
85
+ readonly id: true;
86
+ readonly shortId: true;
87
+ };
88
+ /** The `returns` a mutation's result is positioned by, given the frame's `fields` (`true` selects everything). */
89
+ export declare function mutationReturns(mutation: Pick<MutationSchema, 'returns' | 'writesRows'>, fields: FieldInput | true | undefined): FieldDef;
64
90
  //#endregion
65
91
  //#region ../../packages/substrate-pack/src/stream-chunk.d.ts
66
92
  /**
@@ -119,14 +145,13 @@ export declare function decodeStreamChunk<T = unknown>(bytes: Buffer | Uint8Arra
119
145
  //#region ../../packages/substrate-pack/src/wire.d.ts
120
146
  type WireMode = 'json' | 'pack';
121
147
  /**
122
- * Encode an outbound WS frame. Pack mode returns msgpack bytes; JSON mode
123
- * returns stringified text. The `mode` argument is the wire-format discriminant
124
- * — call sites can route the result to the right `WebSocket.send` overload via
125
- * a typed `typeof wire === 'string'` branch.
148
+ * Encode an outbound frame. Pack mode returns msgpack bytes; JSON mode
149
+ * returns stringified text. The `mode` argument is the wire-format discriminant;
150
+ * callers branch on `typeof wire === 'string'`.
126
151
  */
127
152
  export declare function encodeWsFrame(value: unknown, mode: WireMode): string | Uint8Array;
128
153
  /**
129
- * Decode an inbound WS message envelope (the outer `{ id, kind, data?, ... }`
154
+ * Decode an inbound frame envelope (the outer `{ id, kind, data?, ... }`
130
155
  * shape — positional `data` reconstruction is a separate concern handled by
131
156
  * `applyDecodePlanInPlace`).
132
157
  *
@@ -147,7 +172,7 @@ export declare function decodeWsEnvelope<T = unknown>(raw: unknown, mode: WireMo
147
172
  */
148
173
  export declare function isPlainRequestData(value: unknown, depth?: number): boolean;
149
174
  /**
150
- * A single precomputed entry in a WS pack-decode plan. All per-key lookups
175
+ * A single precomputed entry in a pack-decode plan. All per-key lookups
151
176
  * (parseQualifiedKey, schema probe, fields narrow) happen once at plan-build
152
177
  * time; per-frame decoding then iterates the plan directly.
153
178
  *
@@ -189,4 +214,43 @@ export declare function buildDecodePlan(frameSpec: Record<string, FrameSpecEntry
189
214
  */
190
215
  export declare function applyDecodePlanInPlace(envelope: unknown, plan: DecodePlanEntry[]): void;
191
216
  //#endregion
192
- export { type DecodeContext, type DecodeEnvelopeCtx, type DecodePlanEntry, type DecodeStreamChunkInput, type EncodeContext, type EncodeEnvelopeCtx, type EncodeStreamChunkInput, type FrameSpecEntry, PackDecodeError, type PackStreamChunk, SchemaDriftError, WS_SUBPROTOCOL_SUBSTRATE_PACK, type WireMode, decodeEnvelope, decodePositional, decodePositionalFromFieldDef, packFrame, unpackFrame };
217
+ //#region ../../packages/substrate-pack/src/stream-frames.d.ts
218
+ export declare const FRAMES_JSON_MIME = "application/vnd.substrate.frames+json";
219
+ export declare const FRAMES_PACK_MIME = "application/vnd.substrate.frames+pack";
220
+ /** Largest payload a decoder accepts unless told otherwise. */
221
+ export declare const DEFAULT_MAX_FRAME_BYTES: number;
222
+ /** A frame of length 0: keeps an idle stream alive, and decoders skip it. */
223
+ export declare const HEARTBEAT_FRAME: Uint8Array;
224
+ type FrameStreamErrorCode = 'frame_too_large' | 'truncated_frame' | 'stream_idle';
225
+ export declare class FrameStreamError extends Error {
226
+ readonly code: FrameStreamErrorCode;
227
+ constructor(code: FrameStreamErrorCode, message: string);
228
+ }
229
+ /** A little over three of the server's 20 s heartbeats. */
230
+ export declare const DEFAULT_STREAM_IDLE_MS = 65000;
231
+ /**
232
+ * `body`, failing with `stream_idle` when a read waits `ms` for bytes,
233
+ * heartbeats included. It times only reads the consumer is waiting on, so a
234
+ * slow consumer never trips it; a connection that died without closing does.
235
+ * The underlying reader is cancelled on timeout, which settles its pending read.
236
+ */
237
+ export declare function withIdleTimeout(body: ReadableStream<Uint8Array>, ms: number): ReadableStream<Uint8Array>;
238
+ /** The frames encoding an `Accept` header asks for, or undefined when it asks for none. */
239
+ export declare function framesEncodingFromAccept(accept: string | undefined): WireMode | undefined;
240
+ /**
241
+ * One frame: u32 BE length, then `value` as JSON or msgpack.
242
+ *
243
+ * @throws FrameStreamError `frame_too_large` when the payload is over `maxFrameBytes`,
244
+ * which a decoder with the same limit would refuse
245
+ */
246
+ export declare function encodeStreamFrame(value: unknown, mode: WireMode, maxFrameBytes?: number): Uint8Array;
247
+ /**
248
+ * The payloads of a frame stream, in order, heartbeats skipped. A length above
249
+ * `maxFrameBytes` throws `frame_too_large` before any of that payload is read
250
+ * or allocated; a body that ends inside a frame throws `truncated_frame`.
251
+ */
252
+ export declare function decodeStreamFrames(body: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>, opts?: {
253
+ maxFrameBytes?: number;
254
+ }): AsyncGenerator<Uint8Array>;
255
+ //#endregion
256
+ export { type DecodeContext, type DecodeEnvelopeCtx, type DecodePlanEntry, type DecodeStreamChunkInput, type EncodeContext, type EncodeEnvelopeCtx, type EncodeStreamChunkInput, type FrameSpecEntry, type FrameStreamErrorCode, PackDecodeError, type PackStreamChunk, SchemaDriftError, type WireMode, decodeEnvelope, decodePositional, decodePositionalFromFieldDef, pack as packFrame, unpack as unpackFrame };
package/dist/pack.js CHANGED
@@ -1,5 +1,5 @@
1
- import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { _ as decodeEnvelope, a as buildDecodePlan, c as isPlainRequestData, d as PackEncodeError, f as encodeEnvelope, g as SchemaDriftError, h as PackDecodeError, i as applyDecodePlanInPlace, l as decodeStreamChunk, m as encodePositionalFromFieldDef, n as packFrame, o as decodeWsEnvelope, p as encodePositional, r as unpackFrame, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, u as encodeStreamChunk, v as decodePositional, y as decodePositionalFromFieldDef } from "./src-BLgbLq2k.js";
3
- import { n as acceptsPack, t as PACK_MIME } from "./content-type-C7T28xNb.js";
1
+ import { A as positionValue, C as decodePositional, D as encodePositional, E as encodeEnvelope, O as encodePositionalFromFieldDef, S as decodeEnvelope, T as PackEncodeError, _ as encodeStreamChunk, a as FrameStreamError, b as PackDecodeError, c as encodeStreamFrame, d as applyDecodePlanInPlace, f as buildDecodePlan, g as decodeStreamChunk, h as isPlainRequestData, i as FRAMES_PACK_MIME, j as withData, k as packEnvelopeParts, l as framesEncodingFromAccept, m as encodeWsFrame, n as DEFAULT_STREAM_IDLE_MS, o as HEARTBEAT_FRAME, p as decodeWsEnvelope, r as FRAMES_JSON_MIME, s as decodeStreamFrames, t as DEFAULT_MAX_FRAME_BYTES, u as withIdleTimeout, v as MUTATION_ACK_FIELDS, w as decodePositionalFromFieldDef, x as SchemaDriftError, y as mutationReturns } from "./src-B_kHkbsr.js";
2
+ import { n as acceptsPack, t as PACK_MIME } from "./content-type-wLljot5M.js";
3
+ import { n as pack, r as unpack } from "./msgpackr-Dq18g6Ds.js";
4
4
 
5
- export { PACK_MIME, PackDecodeError, PackEncodeError, SchemaDriftError, WS_SUBPROTOCOL_SUBSTRATE_PACK, acceptsPack, applyDecodePlanInPlace, buildDecodePlan, decodeEnvelope, decodePositional, decodePositionalFromFieldDef, decodeStreamChunk, decodeWsEnvelope, encodeEnvelope, encodePositional, encodePositionalFromFieldDef, encodeStreamChunk, encodeWsFrame, isPlainRequestData, packFrame, unpackFrame };
5
+ export { DEFAULT_MAX_FRAME_BYTES, DEFAULT_STREAM_IDLE_MS, FRAMES_JSON_MIME, FRAMES_PACK_MIME, FrameStreamError, HEARTBEAT_FRAME, MUTATION_ACK_FIELDS, PACK_MIME, PackDecodeError, PackEncodeError, SchemaDriftError, acceptsPack, applyDecodePlanInPlace, buildDecodePlan, decodeEnvelope, decodePositional, decodePositionalFromFieldDef, decodeStreamChunk, decodeStreamFrames, decodeWsEnvelope, encodeEnvelope, encodePositional, encodePositionalFromFieldDef, encodeStreamChunk, encodeStreamFrame, encodeWsFrame, framesEncodingFromAccept, isPlainRequestData, mutationReturns, packEnvelopeParts, pack as packFrame, positionValue, unpack as unpackFrame, withData, withIdleTimeout };
@@ -0,0 +1,443 @@
1
+ import { r as txScopeIdFor } from "./src-BbCUeMsI.js";
2
+ import { randomUUID } from "node:crypto";
3
+
4
+ //#region ../../packages/substrate-dataset-pg/src/pg-edges-store.ts
5
+ /**
6
+ * PgEdgesStore — PostgreSQL-backed reference implementation of EdgesStore.
7
+ * Spec: §4.6, §6.2, §6.3.
8
+ *
9
+ * One table (`edges`) keyed by a text PK, no namespace scoping — edges
10
+ * are engine-scoped (§4.6), not per-ns. The caller owns the `postgres` Sql
11
+ * connection; this class never opens or closes pools.
12
+ *
13
+ * Edge ids are `crypto.randomUUID()`: unique, so cursor pagination works, but
14
+ * not time-ordered. The sweep walks the whole table, so it doesn't need order.
15
+ *
16
+ * Edge.from/to .id is `string | number`, stored and read back as text (unlike
17
+ * PgDataset, which preserves numeric ids).
18
+ *
19
+ * SQL safety: postgres.js tagged templates parameterise every value slot.
20
+ * Never string-concat caller input — the `update` dynamic column list uses a
21
+ * fixed allowlist of column names, not user-supplied keys.
22
+ */
23
+ const MUTABLE_PATCH_FIELDS = /* @__PURE__ */ new Set([
24
+ "id",
25
+ "lastSweptAt",
26
+ "blocked"
27
+ ]);
28
+ /**
29
+ * Batch size for chunked admin deletes (`dropEdgesByNamespace`,
30
+ * `dropEdgesByType`): bounds per-statement lock hold on large tables.
31
+ */
32
+ const DEFAULT_DROP_BATCH_SIZE = 5e3;
33
+ const VALID_POLICIES = /* @__PURE__ */ new Set([
34
+ "set_null",
35
+ "cascade",
36
+ "restrict",
37
+ "orphan"
38
+ ]);
39
+ const refToId = (id) => typeof id === "number" ? String(id) : id;
40
+ var PgEdgesStore = class PgEdgesStore {
41
+ #sql;
42
+ #now;
43
+ #inTx;
44
+ #dropBatchSize;
45
+ txScopeId;
46
+ get #edgeCols() {
47
+ return this.#sql`id, from_ns, from_type, from_id, from_bridged, to_ns, to_type, to_id, to_bridged, field_name, policy, created_at, deleted_at, last_swept_at, blocked`;
48
+ }
49
+ constructor(options) {
50
+ this.#sql = options.sql;
51
+ this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
52
+ this.#inTx = "inTx" in options ? options.inTx : false;
53
+ const explicit = "txScopeId" in options ? options.txScopeId : void 0;
54
+ this.txScopeId = explicit ?? txScopeIdFor(options.sql);
55
+ const batch = options.dropBatchSize;
56
+ if (batch !== void 0 && (!Number.isFinite(batch) || batch <= 0)) throw new Error(`PgEdgesStore: dropBatchSize must be a positive finite number, got ${batch}`);
57
+ this.#dropBatchSize = batch ?? DEFAULT_DROP_BATCH_SIZE;
58
+ }
59
+ async write(input) {
60
+ const id = randomUUID();
61
+ const createdAt = this.#now();
62
+ const fromBridged = input.from.bridged === true;
63
+ const toBridged = input.to.bridged === true;
64
+ await this.#sql`
65
+ INSERT INTO edges (
66
+ id, from_ns, from_type, from_id, from_bridged,
67
+ to_ns, to_type, to_id, to_bridged,
68
+ field_name, policy, created_at, deleted_at, last_swept_at, blocked
69
+ )
70
+ VALUES (
71
+ ${id},
72
+ ${input.from.ns}, ${input.from.type}, ${refToId(input.from.id)}, ${fromBridged},
73
+ ${input.to.ns}, ${input.to.type}, ${refToId(input.to.id)}, ${toBridged},
74
+ ${input.fieldName}, ${input.policy}, ${createdAt},
75
+ NULL, NULL, false
76
+ )
77
+ `;
78
+ return {
79
+ id,
80
+ from: buildRef(input.from.ns, input.from.type, refToId(input.from.id), fromBridged),
81
+ to: buildRef(input.to.ns, input.to.type, refToId(input.to.id), toBridged),
82
+ fieldName: input.fieldName,
83
+ policy: input.policy,
84
+ createdAt
85
+ };
86
+ }
87
+ async writeMany(inputs) {
88
+ if (inputs.length === 0) return [];
89
+ const edges = inputs.map((input) => {
90
+ return {
91
+ id: randomUUID(),
92
+ from: buildRef(input.from.ns, input.from.type, refToId(input.from.id), input.from.bridged === true),
93
+ to: buildRef(input.to.ns, input.to.type, refToId(input.to.id), input.to.bridged === true),
94
+ fieldName: input.fieldName,
95
+ policy: input.policy,
96
+ createdAt: this.#now()
97
+ };
98
+ });
99
+ await this.#sql`
100
+ INSERT INTO edges (
101
+ id, from_ns, from_type, from_id, from_bridged,
102
+ to_ns, to_type, to_id, to_bridged,
103
+ field_name, policy, created_at, deleted_at, last_swept_at, blocked
104
+ )
105
+ SELECT t.id, t.from_ns, t.from_type, t.from_id, t.from_bridged::boolean,
106
+ t.to_ns, t.to_type, t.to_id, t.to_bridged::boolean,
107
+ t.field_name, t.policy, t.created_at::timestamptz, NULL, NULL, false
108
+ FROM unnest(
109
+ ${edges.map((e) => e.id)}::uuid[],
110
+ ${edges.map((e) => e.from.ns)}::text[],
111
+ ${edges.map((e) => e.from.type)}::text[],
112
+ ${edges.map((e) => String(e.from.id))}::text[],
113
+ ${edges.map((e) => String(e.from.bridged === true))}::text[],
114
+ ${edges.map((e) => e.to.ns)}::text[],
115
+ ${edges.map((e) => e.to.type)}::text[],
116
+ ${edges.map((e) => String(e.to.id))}::text[],
117
+ ${edges.map((e) => String(e.to.bridged === true))}::text[],
118
+ ${edges.map((e) => e.fieldName)}::text[],
119
+ ${edges.map((e) => e.policy)}::text[],
120
+ ${edges.map((e) => e.createdAt.toISOString())}::text[]
121
+ ) AS t(id, from_ns, from_type, from_id, from_bridged,
122
+ to_ns, to_type, to_id, to_bridged, field_name, policy, created_at)
123
+ `;
124
+ return edges;
125
+ }
126
+ async tombstoneMany(ids, at) {
127
+ if (ids.length === 0) return;
128
+ await this.#sql`
129
+ UPDATE edges
130
+ SET deleted_at = ${at ?? this.#now()}
131
+ WHERE id = ANY(${ids}::uuid[])
132
+ AND deleted_at IS NULL
133
+ `;
134
+ }
135
+ async tombstone(id, at) {
136
+ const stamp = at ?? this.#now();
137
+ await this.#sql`
138
+ UPDATE edges
139
+ SET deleted_at = ${stamp}
140
+ WHERE id = ${id}
141
+ AND deleted_at IS NULL
142
+ `;
143
+ }
144
+ /**
145
+ * Hard-deletes tombstoned edges whose `deleted_at` is older than
146
+ * `olderThan`. Called by the sweep loop. Returns the number deleted.
147
+ */
148
+ async purgeTombstonedEdges(opts) {
149
+ return { deleted: (await this.#sql`
150
+ DELETE FROM edges
151
+ WHERE deleted_at IS NOT NULL
152
+ AND deleted_at < ${opts.olderThan}
153
+ RETURNING id
154
+ `).length };
155
+ }
156
+ async update(patch) {
157
+ for (const key of Object.keys(patch)) if (!MUTABLE_PATCH_FIELDS.has(key)) throw new Error(`EdgesStore.update: field '${key}' is immutable`);
158
+ const hasLastSweptAt = Object.hasOwn(patch, "lastSweptAt");
159
+ const hasBlocked = Object.hasOwn(patch, "blocked");
160
+ if (!hasLastSweptAt && !hasBlocked) return;
161
+ if (hasLastSweptAt && hasBlocked) {
162
+ await this.#sql`
163
+ UPDATE edges
164
+ SET last_swept_at = ${patch.lastSweptAt ?? null},
165
+ blocked = ${patch.blocked ?? false}
166
+ WHERE id = ${patch.id}
167
+ `;
168
+ return;
169
+ }
170
+ if (hasLastSweptAt) {
171
+ await this.#sql`
172
+ UPDATE edges
173
+ SET last_swept_at = ${patch.lastSweptAt ?? null}
174
+ WHERE id = ${patch.id}
175
+ `;
176
+ return;
177
+ }
178
+ await this.#sql`
179
+ UPDATE edges
180
+ SET blocked = ${patch.blocked ?? false}
181
+ WHERE id = ${patch.id}
182
+ `;
183
+ }
184
+ async readNextBatch(cursorId, size) {
185
+ const edges = (cursorId === null ? await this.#sql`
186
+ SELECT ${this.#edgeCols}
187
+ FROM edges
188
+ ORDER BY id ASC
189
+ LIMIT ${size}
190
+ ` : await this.#sql`
191
+ SELECT ${this.#edgeCols}
192
+ FROM edges
193
+ WHERE id > ${cursorId}
194
+ ORDER BY id ASC
195
+ LIMIT ${size}
196
+ `).map(rowToEdge);
197
+ const last = edges[edges.length - 1];
198
+ return {
199
+ edges,
200
+ lastId: last ? last.id : null
201
+ };
202
+ }
203
+ async findEdgesTo(ref) {
204
+ return (await this.#sql`
205
+ SELECT ${this.#edgeCols}
206
+ FROM edges
207
+ WHERE to_ns = ${ref.ns}
208
+ AND to_type = ${ref.type}
209
+ AND to_id = ${refToId(ref.id)}
210
+ AND deleted_at IS NULL
211
+ `).map(rowToEdge);
212
+ }
213
+ async findEdgesToMany(refs) {
214
+ return this.#findMany("to", refs);
215
+ }
216
+ async findEdgesFromMany(refs) {
217
+ return this.#findMany("from", refs);
218
+ }
219
+ async #findMany(side, refs) {
220
+ if (refs.length === 0) return [];
221
+ const sql = this.#sql;
222
+ const seenRef = /* @__PURE__ */ new Set();
223
+ const seekNs = [];
224
+ const seekType = [];
225
+ const seekId = [];
226
+ for (const r of refs) {
227
+ const id = refToId(r.id);
228
+ const k = `${r.ns}\u0000${r.type}\u0000${id}`;
229
+ if (seenRef.has(k)) continue;
230
+ seenRef.add(k);
231
+ seekNs.push(r.ns);
232
+ seekType.push(r.type);
233
+ seekId.push(id);
234
+ }
235
+ const [colNs, colType, colId] = side === "to" ? [
236
+ sql("to_ns"),
237
+ sql("to_type"),
238
+ sql("to_id")
239
+ ] : [
240
+ sql("from_ns"),
241
+ sql("from_type"),
242
+ sql("from_id")
243
+ ];
244
+ return (await sql`
245
+ SELECT ${this.#edgeCols}
246
+ FROM edges
247
+ JOIN unnest(${seekNs}::text[], ${seekType}::text[], ${seekId}::text[])
248
+ AS seek(seek_ns, seek_type, seek_id)
249
+ ON ${colNs} = seek.seek_ns AND ${colType} = seek.seek_type AND ${colId} = seek.seek_id
250
+ WHERE deleted_at IS NULL
251
+ `).map(rowToEdge);
252
+ }
253
+ async findEdgesFrom(ref) {
254
+ return (await this.#sql`
255
+ SELECT ${this.#edgeCols}
256
+ FROM edges
257
+ WHERE from_ns = ${ref.ns}
258
+ AND from_type = ${ref.type}
259
+ AND from_id = ${refToId(ref.id)}
260
+ AND deleted_at IS NULL
261
+ `).map(rowToEdge);
262
+ }
263
+ async findEdgesTouchingNamespace(namespace, limit) {
264
+ return (await this.#sql`
265
+ SELECT ${this.#edgeCols}
266
+ FROM edges
267
+ WHERE deleted_at IS NULL
268
+ AND (from_ns = ${namespace} OR to_ns = ${namespace})
269
+ ORDER BY id ASC
270
+ LIMIT ${limit}
271
+ `).map(rowToEdge);
272
+ }
273
+ async findEdgesTouchingType(namespace, type, limit) {
274
+ return (await this.#sql`
275
+ SELECT ${this.#edgeCols}
276
+ FROM edges
277
+ WHERE deleted_at IS NULL
278
+ AND ((from_ns = ${namespace} AND from_type = ${type})
279
+ OR (to_ns = ${namespace} AND to_type = ${type}))
280
+ ORDER BY id ASC
281
+ LIMIT ${limit}
282
+ `).map(rowToEdge);
283
+ }
284
+ async namespacesLinkedTo(namespace, type) {
285
+ const fromMatch = type === void 0 ? this.#sql`from_ns = ${namespace}` : this.#sql`(from_ns = ${namespace} AND from_type = ${type})`;
286
+ const toMatch = type === void 0 ? this.#sql`to_ns = ${namespace}` : this.#sql`(to_ns = ${namespace} AND to_type = ${type})`;
287
+ return (await this.#sql`
288
+ SELECT ns FROM (
289
+ SELECT to_ns AS ns FROM edges WHERE ${fromMatch}
290
+ UNION
291
+ SELECT from_ns AS ns FROM edges WHERE ${toMatch}
292
+ ) linked
293
+ WHERE ns <> ${namespace}
294
+ ORDER BY ns
295
+ `).map((r) => r.ns);
296
+ }
297
+ /**
298
+ * Chunked physical delete of every edge touching `namespace`, at most
299
+ * `dropBatchSize` rows per statement, so a large delete does not hold every
300
+ * row lock at once. Returns the number deleted.
301
+ *
302
+ * Outside a tx each batch auto-commits. Inside a caller's tx the batches
303
+ * stay in it, so a throw still rolls back the whole drop.
304
+ */
305
+ async dropEdgesByNamespace(namespace, within) {
306
+ const batchSize = this.#dropBatchSize;
307
+ const farEnd = this.#farEndWithin(namespace, within, this.#sql`from_ns = ${namespace}`, this.#sql`to_ns = ${namespace}`);
308
+ let total = 0;
309
+ while (true) {
310
+ const rows = await this.#sql`
311
+ DELETE FROM edges
312
+ WHERE id IN (
313
+ SELECT id FROM edges
314
+ WHERE (from_ns = ${namespace} OR to_ns = ${namespace}) ${farEnd}
315
+ LIMIT ${batchSize}
316
+ )
317
+ RETURNING id
318
+ `;
319
+ total += rows.length;
320
+ if (rows.length < batchSize) return total;
321
+ await this.#yieldBetweenBatches();
322
+ }
323
+ }
324
+ /**
325
+ * Chunked physical delete of every edge touching `(namespace, type)`.
326
+ * See {@link dropEdgesByNamespace} for the lock-hold + tx semantics.
327
+ */
328
+ async dropEdgesByType(namespace, type, within) {
329
+ const batchSize = this.#dropBatchSize;
330
+ const fromMatch = this.#sql`(from_ns = ${namespace} AND from_type = ${type})`;
331
+ const toMatch = this.#sql`(to_ns = ${namespace} AND to_type = ${type})`;
332
+ const farEnd = this.#farEndWithin(namespace, within, fromMatch, toMatch);
333
+ let total = 0;
334
+ while (true) {
335
+ const rows = await this.#sql`
336
+ DELETE FROM edges
337
+ WHERE id IN (
338
+ SELECT id FROM edges
339
+ WHERE (${fromMatch} OR ${toMatch}) ${farEnd}
340
+ LIMIT ${batchSize}
341
+ )
342
+ RETURNING id
343
+ `;
344
+ total += rows.length;
345
+ if (rows.length < batchSize) return total;
346
+ await this.#yieldBetweenBatches();
347
+ }
348
+ }
349
+ /** `AND` clause keeping only edges whose far end is `namespace` or in `within`. */
350
+ #farEndWithin(namespace, within, fromMatch, toMatch) {
351
+ if (within === void 0) return this.#sql``;
352
+ const allowed = this.#sql([namespace, ...within]);
353
+ return this.#sql`AND ((${fromMatch} AND to_ns IN ${allowed}) OR (${toMatch} AND from_ns IN ${allowed}))`;
354
+ }
355
+ /**
356
+ * Yields to the event loop between drop batches outside a tx; no-op inside one.
357
+ */
358
+ async #yieldBetweenBatches() {
359
+ if (!this.#inTx) await new Promise((resolve) => setImmediate(resolve));
360
+ }
361
+ async canDelete(ref) {
362
+ const rows = await this.#sql`
363
+ SELECT ${this.#edgeCols}
364
+ FROM edges
365
+ WHERE to_ns = ${ref.ns}
366
+ AND to_type = ${ref.type}
367
+ AND to_id = ${refToId(ref.id)}
368
+ AND policy = 'restrict'
369
+ AND deleted_at IS NULL
370
+ `;
371
+ if (rows.length === 0) return { ok: true };
372
+ return {
373
+ ok: false,
374
+ blockedBy: rows.map(rowToEdge)
375
+ };
376
+ }
377
+ async findBlocked() {
378
+ return (await this.#sql`
379
+ SELECT ${this.#edgeCols}
380
+ FROM edges
381
+ WHERE blocked = true
382
+ AND deleted_at IS NULL
383
+ `).map(rowToEdge);
384
+ }
385
+ /**
386
+ * `sql.begin`-backed atomicity. Same flattening pattern as PgDataset —
387
+ * nested re-entry skips the inner begin and runs on the existing tx handle
388
+ * so an inner throw propagates to the outer `sql.begin` for rollback.
389
+ */
390
+ async withTransaction(fn) {
391
+ if (this.#inTx) return fn(this);
392
+ return this.#sql.begin(async (txSql) => {
393
+ return fn(new PgEdgesStore({
394
+ sql: txSql,
395
+ now: this.#now,
396
+ inTx: true,
397
+ txScopeId: this.txScopeId,
398
+ dropBatchSize: this.#dropBatchSize
399
+ }));
400
+ });
401
+ }
402
+ /**
403
+ * Engine-only. Returns a tx-bound clone on the supplied `TransactionSql`,
404
+ * for `PgDataset.withScopedTransaction`. The caller has verified
405
+ * the txScopeIds match.
406
+ */
407
+ _enlistInTx(txSql) {
408
+ return new PgEdgesStore({
409
+ sql: txSql,
410
+ now: this.#now,
411
+ inTx: true,
412
+ txScopeId: this.txScopeId,
413
+ dropBatchSize: this.#dropBatchSize
414
+ });
415
+ }
416
+ };
417
+ function buildRef(ns, type, id, bridged) {
418
+ const ref = {
419
+ ns,
420
+ type,
421
+ id
422
+ };
423
+ if (bridged) ref.bridged = true;
424
+ return ref;
425
+ }
426
+ function rowToEdge(row) {
427
+ if (!VALID_POLICIES.has(row.policy)) throw new Error(`PgEdgesStore: unknown policy '${row.policy}' on edge id=${row.id}`);
428
+ const edge = {
429
+ id: row.id,
430
+ from: buildRef(row.from_ns, row.from_type, row.from_id, row.from_bridged),
431
+ to: buildRef(row.to_ns, row.to_type, row.to_id, row.to_bridged),
432
+ fieldName: row.field_name,
433
+ policy: row.policy,
434
+ createdAt: row.created_at
435
+ };
436
+ if (row.deleted_at !== null) edge.deletedAt = row.deleted_at;
437
+ if (row.last_swept_at !== null) edge.lastSweptAt = row.last_swept_at;
438
+ if (row.blocked) edge.blocked = true;
439
+ return edge;
440
+ }
441
+
442
+ //#endregion
443
+ export { PgEdgesStore as t };