@mnmal-ai/substrate 1.0.0-alpha.17 → 1.0.0-alpha.19

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 (41) hide show
  1. package/README.md +4 -4
  2. package/dist/{boot-store-DNU0UfX7.js → boot-store-DL2Wkzun.js} +207 -258
  3. package/dist/{bridge-5VHZiH9o.d.ts → bridge-BhiJKwfF.d.ts} +1 -1
  4. package/dist/{cli-CwWUYUMv.js → cli-BYyPsfdY.js} +193 -31
  5. package/dist/client.browser.js +2478 -0
  6. package/dist/client.d.ts +181 -164
  7. package/dist/client.js +5 -5
  8. package/dist/{errors-DHgT7Fa8.d.ts → errors-CYOaWZ8l.d.ts} +1 -1
  9. package/dist/{index-DKJXQ031.d.ts → index-rW7fu2Af.d.ts} +3 -11
  10. package/dist/{node-version-CxqcqECU.js → node-version-BlYrbY2I.js} +8 -1
  11. package/dist/pack.d.ts +59 -11
  12. package/dist/pack.js +2 -2
  13. package/dist/{pg-edges-store-CSJ7sG2l.js → pg-edges-store-B0Krqoac.js} +1 -1
  14. package/dist/{plugin-Dk9RC3LH.js → plugin-Dk9h__NU.js} +2 -2
  15. package/dist/proposals-bootstrap.js +2 -2
  16. package/dist/proposals.d.ts +2 -2
  17. package/dist/proposals.js +1 -1
  18. package/dist/recall-bootstrap.js +2 -2
  19. package/dist/recall.d.ts +1 -1
  20. package/dist/recall.js +2 -2
  21. package/dist/{repl-BNnKFG3y.js → repl-D6_CBsue.js} +1 -1
  22. package/dist/{row-DHxnCnhA.d.ts → row-CfsHSEfB.d.ts} +4 -4
  23. package/dist/{run-NmwNmVUD.js → run-BJMgCcCC.js} +18 -9
  24. package/dist/{schema-B5WBO8yh.d.ts → schema-laGLMvMC.d.ts} +15 -40
  25. package/dist/{script-C6DSa_Na.js → script-DgXaJY1Y.js} +12 -2
  26. package/dist/script-runner.js +78 -0
  27. package/dist/sdk.d.ts +9 -8
  28. package/dist/sdk.js +3 -3
  29. package/dist/{src-CdbUzLhB.js → src-B6nsPVmD.js} +201 -25
  30. package/dist/{src-DV6PcXym.js → src-B_oTGi3X.js} +648 -845
  31. package/dist/{src-DWrFdHrY.js → src-BcigMQdR.js} +7 -4
  32. package/dist/{src-DR_hUj2p.js → src-D3ACIp1y.js} +1 -1
  33. package/dist/{src-DwynOVMk.js → src-Dlmuq32R.js} +3 -3
  34. package/dist/{src-7lp1y4HK.js → src-DreZjBk7.js} +3 -3
  35. package/dist/{src-BHh6UZ7L.js → src-oO0DtS6y.js} +431 -949
  36. package/dist/substrate-admin.js +2 -2
  37. package/dist/substrate.js +2 -2
  38. package/dist/testing.d.ts +13 -47
  39. package/dist/testing.js +6 -167
  40. package/dist/{ws-BL9nSELO.d.ts → ws-BT8kL1IF.d.ts} +4 -4
  41. package/package.json +21 -23
package/dist/client.d.ts CHANGED
@@ -1,7 +1,122 @@
1
- import { W as QualifiedFrame, dn as ResolverStat, f as PackEnvelope, fn as RuntimeErrorEntry, hn as SlowRequest, ln as ProcessStat, m as Schema, mn as RuntimeMetrics, pn as RuntimeErrors, zn as Row } from "./schema-B5WBO8yh.js";
2
- import { A as and, B as SYSTEM_NAMESPACE, C as flattenGrant, D as parseGrantEntries, E as intersectGrants, F as TokenProviderOpts, G as resolveAdminCredential, H as isActiveAdminKeyRow, I as adminClaimCapabilities, K as resolveDefaultKeyPath, L as isEncryptedKey, M as or, N as ADMIN_CAPABILITIES, O as decodeList, P as DEFAULT_CAPABILITIES, R as makeAuthorizationProvider, S as expandFlat, T as grantIsUniform, U as AdminCredential, V as describeGrant, W as AdminEnv, X as NlAskResult, Y as NlAskRequest, _ as newlyGrantedPairs, a as denyAll, at as NlOutcome, b as capabilitiesFor, c as requireIdentity, d as KeyUpdateRefusal, dt as NlServedPack, f as checkRevocable, ft as NlTrailEvent, g as newlyGranted, h as grantEntriesConfer, i as allowVerbs, j as not, k as encodeList, l as requireNamespace, m as grantCovers, mt as NlWireEvent, n as row, o as denyVerbs, p as checkUpdatable, q as resolveDefaultKidPath, r as allowAll, s as requireCapability, t as applyRowFilters, u as KeyMutationRefusal, v as revokedAtIso, w as grantEntryError, x as encodeGrant, y as Grant, z as makeTokenProvider } from "./row-DHxnCnhA.js";
3
- import { s as SchemaDriftError } from "./index-DKJXQ031.js";
1
+ import { Ln as Row, W as QualifiedFrame, dn as RuntimeErrors, f as PackEnvelope, fn as RuntimeMetrics, ln as ResolverStat, m as Schema, pn as SlowRequest, sn as ProcessStat, un as RuntimeErrorEntry } from "./schema-laGLMvMC.js";
2
+ import { A as and, B as SYSTEM_NAMESPACE, C as flattenGrant, D as parseGrantEntries, E as intersectGrants, F as TokenProviderOpts, G as resolveAdminCredential, H as isActiveAdminKeyRow, I as adminClaimCapabilities, K as resolveDefaultKeyPath, L as isEncryptedKey, M as or, N as ADMIN_CAPABILITIES, O as decodeList, P as DEFAULT_CAPABILITIES, R as makeAuthorizationProvider, S as expandFlat, T as grantIsUniform, U as AdminCredential, V as describeGrant, W as AdminEnv, X as NlAskResult, Y as NlAskRequest, _ as newlyGrantedPairs, a as denyAll, at as NlOutcome, b as capabilitiesFor, c as requireIdentity, d as KeyUpdateRefusal, dt as NlServedPack, f as checkRevocable, ft as NlTrailEvent, g as newlyGranted, h as grantEntriesConfer, i as allowVerbs, j as not, k as encodeList, l as requireNamespace, m as grantCovers, mt as NlWireEvent, n as row, o as denyVerbs, p as checkUpdatable, q as resolveDefaultKidPath, r as allowAll, s as requireCapability, t as applyRowFilters, u as KeyMutationRefusal, v as revokedAtIso, w as grantEntryError, x as encodeGrant, y as Grant, z as makeTokenProvider } from "./row-CfsHSEfB.js";
3
+ import { o as SchemaDriftError } from "./index-rW7fu2Af.js";
4
4
  import { Signal } from "@preact/signals-core";
5
+ //#region ../../packages/substrate-client/src/transport/h2-fetch.d.ts
6
+ /**
7
+ * A fetch-shaped function over `node:http2`: the transport seam's HTTP/2
8
+ * adapter for Node and Bun (Todo #1850, Decision #625).
9
+ *
10
+ * One `ClientHttp2Session` per origin, opened on first use and shared by every
11
+ * request to it; concurrent first calls share the pending connect. A session is
12
+ * dropped on GOAWAY, close or error, and the next request opens a new one. An
13
+ * idle session is unref'd, so a short-lived process exits without `close()`.
14
+ * `http:` origins use HTTP/2 with prior knowledge (h2c); `https:` origins verify
15
+ * the server against `ca`, or the process's default trust (which includes
16
+ * NODE_EXTRA_CA_CERTS). Certificate checks are never turned off.
17
+ *
18
+ * Imports node builtins only.
19
+ */
20
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
21
+ interface H2FetchOptions {
22
+ /** PEM of a CA to trust for `https:` origins, beside the default trust. */
23
+ ca?: string | Uint8Array;
24
+ /** Give up on opening a session after this long. Default 10 000 ms. */
25
+ connectTimeoutMs?: number;
26
+ }
27
+ type H2Fetch = FetchLike & {
28
+ close(): Promise<void>;
29
+ };
30
+ export declare function createH2Fetch(opts?: H2FetchOptions): H2Fetch;
31
+ //#endregion
32
+ //#region ../../packages/substrate-client/src/admin/diagnose.d.ts
33
+ /**
34
+ * `ok` — asked and answered yes. `no` — asked and answered no. `skip` — NOT
35
+ * ASKED, because a precondition failed.
36
+ */
37
+ type DoctorStatus = 'ok' | 'no' | 'skip';
38
+ interface DoctorCheck {
39
+ /** Stable short label, safe to grep for in a support thread. */
40
+ readonly name: string;
41
+ readonly status: DoctorStatus;
42
+ /** What was measured, in the terms the operator typed. */
43
+ readonly detail: string;
44
+ /** Present on `no` — the next command, not a restatement of the failure. */
45
+ readonly fix?: string;
46
+ /** The HTTP status that decided this verdict, when a response decided it. Match on this,
47
+ * never on `detail`, which is prose for an operator and free to change. */
48
+ readonly httpStatus?: number;
49
+ }
50
+ interface DoctorReport {
51
+ readonly checks: readonly DoctorCheck[];
52
+ /** 0 when nothing answered `no`. Skips do not fail the run; they are visible. */
53
+ readonly exitCode: number;
54
+ }
55
+ interface DirectoryReconciliation {
56
+ /** Inactive directory row, live signing credential — the dangerous direction. */
57
+ readonly retiredWithLiveKey: readonly string[];
58
+ /** Live credential, no directory row, not admin-exempt. */
59
+ readonly liveKeyWithoutRow: readonly string[];
60
+ /** Active directory row with a live credential that is not admin-capable. */
61
+ readonly agentKids: readonly string[];
62
+ }
63
+ /**
64
+ * Reconciles live Key rows against AgentIdentity rows, returning retired
65
+ * identities that still hold a live key and live keys with no directory row.
66
+ *
67
+ * Admin keys are exempt from the second list by CAPABILITY, never by kid: the
68
+ * bootstrap root of trust has no directory row by design.
69
+ *
70
+ * A row whose `active` is absent counts as ACTIVE — only an explicit `false`
71
+ * deactivates. Rows predating the field must not read as decommissioned.
72
+ * A key row with no string kid is unmatchable and ignored (doctor is not a
73
+ * corruption scanner).
74
+ */
75
+ export declare function reconcileIdentities(keys: readonly Row[], identities: readonly Row[], adminCapability: string): DirectoryReconciliation;
76
+ /**
77
+ * What diagnose measured, as data. A field is ABSENT when the check that measures it did not
78
+ * run — absent never means empty, so a reader cannot take "not looked" for "none found".
79
+ */
80
+ interface DiagnoseFacts {
81
+ readonly adminKids?: readonly string[];
82
+ readonly liveKeyCount?: number;
83
+ readonly retiredWithLiveKey?: readonly string[];
84
+ readonly liveKeyWithoutRow?: readonly string[];
85
+ readonly agentKids?: readonly string[];
86
+ }
87
+ /** The identity the server resolved, when the identity check passed; else null. */
88
+ interface DiagnoseResult extends DoctorReport {
89
+ readonly identity: string | null;
90
+ readonly facts: DiagnoseFacts;
91
+ }
92
+ type DiagnoseCredential = {
93
+ readonly authorization: () => string;
94
+ readonly label: string;
95
+ } |
96
+ /** `fix` replaces the default advice, which names the admin env: a caller diagnosing some
97
+ * other identity knows what that identity needs. */
98
+ {
99
+ readonly error: string;
100
+ readonly fix?: string;
101
+ };
102
+ interface DiagnoseOpts {
103
+ readonly baseUrl: string;
104
+ readonly credential: DiagnoseCredential;
105
+ /** Default 'admin'. */
106
+ readonly adminCapability?: string;
107
+ /** Default true. False: the admin-only checks are skipped as not asked, not failed. */
108
+ readonly expectAdmin?: boolean;
109
+ readonly fetch?: FetchLike;
110
+ }
111
+ /** Every check `diagnose` can emit, in dependency order: what a caller marks NOT ASKED when it
112
+ * cannot run diagnose at all (the CLI's direct-to-postgres target). */
113
+ export declare const DIAGNOSE_CHECKS: readonly string[];
114
+ /**
115
+ * Runs every check against `opts.baseUrl`, in dependency order. A failure
116
+ * short-circuits its dependants into explicit skips.
117
+ */
118
+ export declare function diagnose(opts: DiagnoseOpts): Promise<DiagnoseResult>;
119
+ //#endregion
5
120
  //#region ../../packages/substrate-client/src/admin/surgery.d.ts
6
121
  type AdminDropCascade = 'refuse' | 'delete';
7
122
  interface AdminDropNamespaceInput {
@@ -276,94 +391,6 @@ interface AdminApi extends SurgeryApi {
276
391
  }): Promise<AdminInviteResult>;
277
392
  }
278
393
  //#endregion
279
- //#region ../../packages/substrate-client/src/admin/diagnose.d.ts
280
- /**
281
- * `ok` — asked and answered yes. `no` — asked and answered no. `skip` — NOT
282
- * ASKED, because a precondition failed.
283
- */
284
- type DoctorStatus = 'ok' | 'no' | 'skip';
285
- interface DoctorCheck {
286
- /** Stable short label, safe to grep for in a support thread. */
287
- readonly name: string;
288
- readonly status: DoctorStatus;
289
- /** What was measured, in the terms the operator typed. */
290
- readonly detail: string;
291
- /** Present on `no` — the next command, not a restatement of the failure. */
292
- readonly fix?: string;
293
- /** The HTTP status that decided this verdict, when a response decided it. Match on this,
294
- * never on `detail`, which is prose for an operator and free to change. */
295
- readonly httpStatus?: number;
296
- }
297
- interface DoctorReport {
298
- readonly checks: readonly DoctorCheck[];
299
- /** 0 when nothing answered `no`. Skips do not fail the run; they are visible. */
300
- readonly exitCode: number;
301
- }
302
- interface DirectoryReconciliation {
303
- /** Inactive directory row, live signing credential — the dangerous direction. */
304
- readonly retiredWithLiveKey: readonly string[];
305
- /** Live credential, no directory row, not admin-exempt. */
306
- readonly liveKeyWithoutRow: readonly string[];
307
- /** Active directory row with a live credential that is not admin-capable. */
308
- readonly agentKids: readonly string[];
309
- }
310
- /**
311
- * Reconciles live Key rows against AgentIdentity rows, returning retired
312
- * identities that still hold a live key and live keys with no directory row.
313
- *
314
- * Admin keys are exempt from the second list by CAPABILITY, never by kid: the
315
- * bootstrap root of trust has no directory row by design.
316
- *
317
- * A row whose `active` is absent counts as ACTIVE — only an explicit `false`
318
- * deactivates. Rows predating the field must not read as decommissioned.
319
- * A key row with no string kid is unmatchable and ignored (doctor is not a
320
- * corruption scanner).
321
- */
322
- export declare function reconcileIdentities(keys: readonly Row[], identities: readonly Row[], adminCapability: string): DirectoryReconciliation;
323
- /**
324
- * What diagnose measured, as data. A field is ABSENT when the check that measures it did not
325
- * run — absent never means empty, so a reader cannot take "not looked" for "none found".
326
- */
327
- interface DiagnoseFacts {
328
- readonly adminKids?: readonly string[];
329
- readonly liveKeyCount?: number;
330
- readonly retiredWithLiveKey?: readonly string[];
331
- readonly liveKeyWithoutRow?: readonly string[];
332
- readonly agentKids?: readonly string[];
333
- }
334
- /** The identity the server resolved, when the identity check passed; else null. */
335
- interface DiagnoseResult extends DoctorReport {
336
- readonly identity: string | null;
337
- readonly facts: DiagnoseFacts;
338
- }
339
- type DiagnoseCredential = {
340
- readonly authorization: () => string;
341
- readonly label: string;
342
- } |
343
- /** `fix` replaces the default advice, which names the admin env: a caller diagnosing some
344
- * other identity knows what that identity needs. */
345
- {
346
- readonly error: string;
347
- readonly fix?: string;
348
- };
349
- interface DiagnoseOpts {
350
- readonly baseUrl: string;
351
- readonly credential: DiagnoseCredential;
352
- /** Default 'admin'. */
353
- readonly adminCapability?: string;
354
- /** Default true. False: the admin-only checks are skipped as not asked, not failed. */
355
- readonly expectAdmin?: boolean;
356
- readonly fetch?: typeof fetch;
357
- }
358
- /** Every check `diagnose` can emit, in dependency order: what a caller marks NOT ASKED when it
359
- * cannot run diagnose at all (the CLI's direct-to-postgres target). */
360
- export declare const DIAGNOSE_CHECKS: readonly string[];
361
- /**
362
- * Runs every check against `opts.baseUrl`, in dependency order. A failure
363
- * short-circuits its dependants into explicit skips.
364
- */
365
- export declare function diagnose(opts: DiagnoseOpts): Promise<DiagnoseResult>;
366
- //#endregion
367
394
  //#region ../../packages/substrate-client/src/admin/onboard.d.ts
368
395
  type OnboardStepStatus = 'done' | 'todo' | 'blocked' | 'skipped';
369
396
  type OnboardAction = {
@@ -472,18 +499,7 @@ export declare function collectDiagnostics(envDiagnostics: EnvelopeDiagnostics |
472
499
  */
473
500
  export declare function createDefaultDiagnosticsSink(): DiagnosticsSink;
474
501
  //#endregion
475
- //#region ../../packages/substrate-client/src/transport/ws.d.ts
476
- type WsEncoding = 'json' | 'pack';
477
- /**
478
- * Minimal constructor shape for an injectable WebSocket implementation.
479
- * Must be node-ws-compatible when headers are needed: `(url, protocols?,
480
- * { headers })`. The WHATWG/browser constructor matches the first two
481
- * parameters and simply cannot receive headers.
482
- */
483
- type WebSocketImpl = new (url: string, protocols?: string | string[], options?: {
484
- headers?: Record<string, string>;
485
- }) => unknown;
486
- /** Bounded auto-resubscribe policy for overload teardowns (contract class 1). */
502
+ //#region ../../packages/substrate-client/src/transport/frame-event.d.ts
487
503
  interface WsOverloadResubscribeOpts {
488
504
  /** Master switch. Default true. `false` restores terminal-on-overload. */
489
505
  enabled?: boolean;
@@ -604,35 +620,30 @@ interface SubstrateClientOptions {
604
620
  * Sync providers are accepted so `@mnmal-ai/substrate-policy`'s synchronous
605
621
  * `makeTokenProvider` is usable directly; the transports `await` either way.
606
622
  */
607
- getToken?: () => string | Promise<string>;
608
- fetch?: typeof fetch;
623
+ getToken?: () => string | undefined | Promise<string | undefined>;
624
+ fetch?: FetchLike;
609
625
  reconnect?: {
610
626
  baseDelayMs?: number;
611
627
  maxDelayMs?: number;
612
628
  jitter?: number;
613
629
  };
614
630
  /**
615
- * Wire encoding for the WS surface (subscribe + stream). Default `json`.
616
- * `pack` advertises the `substrate-pack` subprotocol at handshake; the connection
617
- * then exclusively speaks msgpack frames with positionally-encoded `data`,
618
- * which the client decodes back to named-object rows using the cached
619
- * federated schema. Negotiated once per WS connection — distinct from the
620
- * per-call HTTP `wire` opt because the WS subprotocol is a handshake-time
621
- * choice.
631
+ * Wire encoding of subscribe and stream bodies: length-prefixed JSON frames,
632
+ * or substrate-pack frames decoded back to named rows with the cached
633
+ * federated schema. Default `json`; `CallOpts.wire` overrides it per call.
634
+ */
635
+ streamWire?: 'json' | 'pack';
636
+ /**
637
+ * Drop and re-subscribe a frame stream that sends nothing, heartbeats
638
+ * included, for this many milliseconds: a connection that died without
639
+ * closing. Default 65 000, a little over three server heartbeats. `0` disables.
622
640
  */
623
- wsEncoding?: WsEncoding;
641
+ streamIdleMs?: number;
624
642
  /**
625
643
  * Auto-resubscribe policy for `subscription_overloaded` teardowns. Default:
626
644
  * enabled with 3 attempts. See the README "Terminal-aware resubscribe" section.
627
645
  */
628
646
  overloadResubscribe?: WsOverloadResubscribeOpts;
629
- /**
630
- * Explicit WebSocket implementation for the subscribe/stream surface. Must
631
- * be node-ws-compatible (`new (url, protocols?, { headers })`) so the
632
- * bearer can ride the upgrade. Defaults to node-ws under Node and the
633
- * global WebSocket elsewhere — see WsTransportOpts.webSocket.
634
- */
635
- webSocket?: WebSocketImpl;
636
647
  /**
637
648
  * Sink for non-fatal envelope diagnostics (`_diagnostics`) on query/mutate
638
649
  * responses: projection keys the type does not declare, a where-clause that
@@ -652,15 +663,17 @@ interface CallOpts {
652
663
  export declare class SubstrateClient {
653
664
  #private;
654
665
  constructor(opts: SubstrateClientOptions);
655
- /** Natural-language ask (SSE or JSON) and the served namespace pack. Requires the substrate-nl plugin. */
666
+ /** Natural-language ask (frame stream or JSON) and the served namespace pack. Requires the substrate-nl plugin. */
656
667
  get nl(): NlApi;
657
668
  /** The admin-gated routes. Needs an identity whose grant confers `admin`. */
658
669
  get admin(): AdminApi;
659
670
  federatedSchema(): Promise<Record<string, Schema>>;
660
671
  query(frame: QualifiedFrame, opts?: CallOpts): Promise<PackEnvelope>;
661
672
  mutate(frame: QualifiedFrame, opts?: CallOpts): Promise<PackEnvelope>;
662
- subscribe(frame: QualifiedFrame, _opts?: CallOpts): AsyncIterable<SubscribeEvent>;
663
- stream(frame: QualifiedFrame, _opts?: CallOpts): AsyncIterable<SubscribeEvent>;
673
+ /** A live query: a snapshot, then deltas. `opts.wire` and `opts.signal` apply. */
674
+ subscribe(frame: QualifiedFrame, opts?: CallOpts): AsyncIterable<SubscribeEvent>;
675
+ /** A one-shot streamed resolver: chunks, then `end`. `opts.wire` and `opts.signal` apply. */
676
+ stream(frame: QualifiedFrame, opts?: CallOpts): AsyncIterable<SubscribeEvent>;
664
677
  /**
665
678
  * Live typed-row view over a single-key subscription. Subscribes under the
666
679
  * hood, folds snapshot/add/update/remove into the current row-set, and yields
@@ -670,7 +683,7 @@ export declare class SubstrateClient {
670
683
  *
671
684
  * Completes when the subscription ends; throws on an error frame — the same
672
685
  * contract as `subscribe`. Breaking the consuming `for await` cancels the
673
- * underlying WS subscription. Reconnect / overload-resubscribe are handled by
686
+ * underlying subscription. Reconnect / overload-resubscribe are handled by
674
687
  * `subscribe`; each fresh snapshot atomically replaces the row-set.
675
688
  *
676
689
  * Single-qualified-key only: multi-key frames throw; use `subscribe` for
@@ -740,39 +753,6 @@ export declare class SubscribeError extends Error {
740
753
  constructor(message: string, code: string);
741
754
  }
742
755
  //#endregion
743
- //#region ../../packages/substrate-client/src/from-env.d.ts
744
- /**
745
- * The capabilities a client asks for, from `SUBSTRATE_AGENT_CAPABILITIES` (csv),
746
- * defaulting to `substrate-policy`'s default.
747
- *
748
- * Not `ADMIN_CAPABILITIES`: a dataset-registry key intersects the claim, but a
749
- * file-registry key takes it verbatim, so a wider default would promote every
750
- * agent on such a deployment to admin.
751
- */
752
- export declare function resolveAgentCapabilities(env: NodeJS.ProcessEnv): ReadonlyArray<string>;
753
- interface ClientFromEnvOptions extends Omit<SubstrateClientOptions, 'endpoint' | 'token' | 'getToken'> {
754
- env?: NodeJS.ProcessEnv;
755
- /** Allow an unsigned client when no signing key is configured. Default false. */
756
- allowAnonymous?: boolean;
757
- }
758
- interface ClientFromEnv {
759
- client: SubstrateClient;
760
- endpoint: string;
761
- /** The signing kid, or null for an anonymous client. */
762
- kid: string | null;
763
- }
764
- /**
765
- * Builds a client from `SUBSTRATE_URL` and `SUBSTRATE_AGENT_KEY_ID` +
766
- * `SUBSTRATE_AGENT_KEY_PATH`, signing every request as that kid.
767
- *
768
- * Redirects are refused and the token's audience is the endpoint's origin.
769
- *
770
- * @throws Error when `SUBSTRATE_URL` is unset or unsafe for a credential, when
771
- * only one of the key pair is set, when the key cannot be read, or when no
772
- * key is set and `allowAnonymous` is not.
773
- */
774
- export declare function createClientFromEnv(opts?: ClientFromEnvOptions): ClientFromEnv;
775
- //#endregion
776
756
  //#region ../../packages/substrate-client/src/script.d.ts
777
757
  /**
778
758
  * `read` refuses every mutation, `dry-run` records mutations without sending
@@ -824,6 +804,11 @@ interface ScriptContext {
824
804
  }): Promise<Record<string, unknown>[]>;
825
805
  /** Recall hits, best first, through the `recall/Hit` frame. */
826
806
  recall(input: ScriptRecallInput): Promise<ScriptRecallHit[]>;
807
+ /**
808
+ * The federated schema, one namespace's schema, or one type's. Throws naming
809
+ * an unknown namespace or type.
810
+ */
811
+ schema(namespace?: string, type?: string): Promise<unknown>;
827
812
  /**
828
813
  * One mutate payload (one transaction). Returns null in `dry-run`, and throws
829
814
  * in `read`, past `maxWrites`, or when the server refuses any frame.
@@ -883,21 +868,53 @@ export declare function reduceSubscribeRows<T>(current: T[], qualifiedKey: strin
883
868
  * A delta that does not change the set (e.g. an `update` whose row has no id) is
884
869
  * not re-yielded. Cancellation: breaking the consuming `for await` (or calling
885
870
  * `.return()`) propagates to the source iterable's `return()` through the inner
886
- * `for await`, cancelling the underlying WS subscription.
871
+ * `for await`, cancelling the underlying subscription.
887
872
  */
888
873
  export declare function watchRows<T>(events: AsyncIterable<SubscribeEvent>, qualifiedKey: string): AsyncGenerator<T[]>;
889
874
  //#endregion
890
875
  //#region ../../packages/substrate-client/src/token-target.d.ts
891
- /**
892
- * Where a freshly minted credential may be sent: an https origin, or plain
893
- * http only to a loopback host, where nothing on the network can read it.
894
- */
895
876
  /**
896
877
  * @returns the origin of `baseUrl`, which a token for it names as its `aud`.
897
878
  * @throws Error when `baseUrl` is not a URL, or is plain http to a non-loopback host.
898
879
  */
899
880
  export declare function tokenAudience(baseUrl: string): string;
900
881
  /** `fetchImpl` with redirects refused: a redirect would carry the credential to wherever it points. */
901
- export declare function noRedirectFetch(fetchImpl?: typeof fetch): typeof fetch;
882
+ export declare function noRedirectFetch(fetchImpl?: FetchLike): FetchLike;
883
+ //#endregion
884
+ //#region ../../packages/substrate-client/src/transport/default-fetch.d.ts
885
+ export declare const substrateFetch: FetchLike;
886
+ //#endregion
887
+ //#region ../../packages/substrate-client/src/from-env.d.ts
888
+ /**
889
+ * The capabilities a client asks for, from `SUBSTRATE_AGENT_CAPABILITIES` (csv),
890
+ * defaulting to `substrate-policy`'s default.
891
+ *
892
+ * Not `ADMIN_CAPABILITIES`: a dataset-registry key intersects the claim, but a
893
+ * file-registry key takes it verbatim, so a wider default would promote every
894
+ * agent on such a deployment to admin.
895
+ */
896
+ export declare function resolveAgentCapabilities(env: NodeJS.ProcessEnv): ReadonlyArray<string>;
897
+ interface ClientFromEnvOptions extends Omit<SubstrateClientOptions, 'endpoint' | 'token' | 'getToken'> {
898
+ env?: NodeJS.ProcessEnv;
899
+ /** Allow an unsigned client when no signing key is configured. Default false. */
900
+ allowAnonymous?: boolean;
901
+ }
902
+ interface ClientFromEnv {
903
+ client: SubstrateClient;
904
+ endpoint: string;
905
+ /** The signing kid, or null for an anonymous client. */
906
+ kid: string | null;
907
+ }
908
+ /**
909
+ * Builds a client from `SUBSTRATE_URL` and `SUBSTRATE_AGENT_KEY_ID` +
910
+ * `SUBSTRATE_AGENT_KEY_PATH`, signing every request as that kid.
911
+ *
912
+ * Redirects are refused and the token's audience is the endpoint's origin.
913
+ *
914
+ * @throws Error when `SUBSTRATE_URL` is unset or unsafe for a credential, when
915
+ * only one of the key pair is set, when the key cannot be read, or when no
916
+ * key is set and `allowAnonymous` is not.
917
+ */
918
+ export declare function createClientFromEnv(opts?: ClientFromEnvOptions): ClientFromEnv;
902
919
  //#endregion
903
- export { ADMIN_CAPABILITIES, type AdminApi, type AdminBackfillChunk, type AdminBackfillInput, type AdminBackfillSummary, type AdminCredential, type AdminDropCascade, type AdminDropNamespaceInput, type AdminDropResult, type AdminDropTypeInput, type AdminEmbedStats, type AdminEnv, type AdminGrantChange, type AdminInviteInput, type AdminInviteResult, type AdminKeyAlgorithm, type AdminKeyRow, type AdminNormaliseInput, type AdminNormaliseResult, type AdminRegisterInput, type AdminRegisterResult, type AdminReindexInput, type AdminReindexPage, type AdminRevokeResult, type AdminUpdateResult, type CallOpts, type ClientFromEnv, type ClientFromEnvOptions, DEFAULT_CAPABILITIES, type DiagnoseCredential, type DiagnoseFacts, type DiagnoseOpts, type DiagnoseResult, type Diagnostic, type DiagnosticsSink, type DirectoryReconciliation, type DoctorCheck, type DoctorReport, type DoctorStatus, type Grant, type KeyMutationRefusal, type KeyUpdateRefusal, type NlApi, type NlAskRequest, type NlAskResult, type NlOutcome, type NlServedPack, type NlTrailEvent, type NlWireEvent, type OnboardAction, type OnboardStep, type OnboardStepStatus, type PlanOnboardingOpts, type ProcessStat, type QualifiedFrame, type ResolverStat, type RunScriptOptions, type RuntimeErrorEntry, type RuntimeErrors, type RuntimeMetrics, SYSTEM_NAMESPACE, SchemaDriftError, type ScriptContext, type ScriptMode, type ScriptMutation, type ScriptRecallHit, type ScriptRecallInput, type ScriptReport, type SlowRequest, type SubscribeEvent, type SubstrateClientOptions, type SurgeryApi, type TokenProviderOpts, type WebSocketImpl, type WsOverloadResubscribeOpts, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, decodeList, denyAll, denyVerbs, describeGrant, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, not, or, parseGrantEntries, requireCapability, requireIdentity, requireNamespace, resolveAdminCredential, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row };
920
+ export { ADMIN_CAPABILITIES, type AdminApi, type AdminBackfillChunk, type AdminBackfillInput, type AdminBackfillSummary, type AdminCredential, type AdminDropCascade, type AdminDropNamespaceInput, type AdminDropResult, type AdminDropTypeInput, type AdminEmbedStats, type AdminEnv, type AdminGrantChange, type AdminInviteInput, type AdminInviteResult, type AdminKeyAlgorithm, type AdminKeyRow, type AdminNormaliseInput, type AdminNormaliseResult, type AdminRegisterInput, type AdminRegisterResult, type AdminReindexInput, type AdminReindexPage, type AdminRevokeResult, type AdminUpdateResult, type CallOpts, type ClientFromEnv, type ClientFromEnvOptions, DEFAULT_CAPABILITIES, type DiagnoseCredential, type DiagnoseFacts, type DiagnoseOpts, type DiagnoseResult, type Diagnostic, type DiagnosticsSink, type DirectoryReconciliation, type DoctorCheck, type DoctorReport, type DoctorStatus, type FetchLike, type Grant, type H2Fetch, type H2FetchOptions, type KeyMutationRefusal, type KeyUpdateRefusal, type NlApi, type NlAskRequest, type NlAskResult, type NlOutcome, type NlServedPack, type NlTrailEvent, type NlWireEvent, type OnboardAction, type OnboardStep, type OnboardStepStatus, type PlanOnboardingOpts, type ProcessStat, type QualifiedFrame, type ResolverStat, type RunScriptOptions, type RuntimeErrorEntry, type RuntimeErrors, type RuntimeMetrics, SYSTEM_NAMESPACE, SchemaDriftError, type ScriptContext, type ScriptMode, type ScriptMutation, type ScriptRecallHit, type ScriptRecallInput, type ScriptReport, type SlowRequest, type SubscribeEvent, type SubstrateClientOptions, type SurgeryApi, type TokenProviderOpts, type WsOverloadResubscribeOpts, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, decodeList, denyAll, denyVerbs, describeGrant, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, not, or, parseGrantEntries, requireCapability, requireIdentity, requireNamespace, resolveAdminCredential, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row };
package/dist/client.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
2
  import { a as adminClaimCapabilities, c as makeTokenProvider, d as resolveDefaultKidPath, i as DEFAULT_CAPABILITIES, l as resolveAdminCredential, o as isEncryptedKey, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
3
- import { A as expandFlat, C as not, D as isActiveAdminKeyRow, E as describeGrant, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, N as grantIsUniform, O as capabilitiesFor, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, _ as grantCovers, a as denyAll, b as newlyGrantedPairs, c as requireIdentity, g as checkUpdatable, h as checkRevocable, i as allowVerbs, j as flattenGrant, k as encodeGrant, l as requireNamespace, n as row, o as denyVerbs, r as allowAll, s as requireCapability, t as applyRowFilters, v as grantEntriesConfer, w as or, x as revokedAtIso, y as newlyGranted } from "./src-DR_hUj2p.js";
4
- import { f as SchemaDriftError } from "./src-CdbUzLhB.js";
5
- import { C as diagnose, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, a as SubstrateClient, b as planOnboarding, c as reduceSubscribeRows, d as NetworkError, f as SubscribeError, g as ONBOARD_STEPS, h as CURRENT_MARK, i as tokenAudience, l as watchRows, m as BACKFILL_CHUNK, n as resolveAgentCapabilities, o as collectDiagnostics, p as AdminBackfillError, r as noRedirectFetch, s as createDefaultDiagnosticsSink, t as createClientFromEnv, u as AuthError, v as STEP_MARKS, w as reconcileIdentities, x as requiredOutstanding, y as currentStep } from "./src-DV6PcXym.js";
6
- import { n as runScript, t as DEFAULT_MAX_WRITES } from "./script-C6DSa_Na.js";
3
+ import { A as expandFlat, C as not, D as isActiveAdminKeyRow, E as describeGrant, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, N as grantIsUniform, O as capabilitiesFor, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, _ as grantCovers, a as denyAll, b as newlyGrantedPairs, c as requireIdentity, g as checkUpdatable, h as checkRevocable, i as allowVerbs, j as flattenGrant, k as encodeGrant, l as requireNamespace, n as row, o as denyVerbs, r as allowAll, s as requireCapability, t as applyRowFilters, v as grantEntriesConfer, w as or, x as revokedAtIso, y as newlyGranted } from "./src-D3ACIp1y.js";
4
+ import { C as SchemaDriftError } from "./src-B6nsPVmD.js";
5
+ import { C as diagnose, E as substrateFetch, S as DIAGNOSE_CHECKS, T as createH2Fetch, _ as SKIPPABLE_STEPS, a as SubstrateClient, b as planOnboarding, c as reduceSubscribeRows, d as NetworkError, f as SubscribeError, g as ONBOARD_STEPS, h as CURRENT_MARK, i as tokenAudience, l as watchRows, m as BACKFILL_CHUNK, n as resolveAgentCapabilities, o as collectDiagnostics, p as AdminBackfillError, r as noRedirectFetch, s as createDefaultDiagnosticsSink, t as createClientFromEnv, u as AuthError, v as STEP_MARKS, w as reconcileIdentities, x as requiredOutstanding, y as currentStep } from "./src-B_oTGi3X.js";
6
+ import { n as runScript, t as DEFAULT_MAX_WRITES } from "./script-DgXaJY1Y.js";
7
7
 
8
- export { ADMIN_CAPABILITIES, AdminBackfillError, AuthError, BACKFILL_CHUNK, CURRENT_MARK, DEFAULT_CAPABILITIES, DEFAULT_MAX_WRITES, DIAGNOSE_CHECKS, NetworkError, ONBOARD_STEPS, SKIPPABLE_STEPS, STEP_MARKS, SYSTEM_NAMESPACE, SchemaDriftError, SubscribeError, SubstrateClient, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, collectDiagnostics, createClientFromEnv, createDefaultDiagnosticsSink, currentStep, decodeList, denyAll, denyVerbs, describeGrant, diagnose, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, noRedirectFetch, not, or, parseGrantEntries, planOnboarding, reconcileIdentities, reduceSubscribeRows, requireCapability, requireIdentity, requireNamespace, requiredOutstanding, resolveAdminCredential, resolveAgentCapabilities, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row, runScript, tokenAudience, watchRows };
8
+ export { ADMIN_CAPABILITIES, AdminBackfillError, AuthError, BACKFILL_CHUNK, CURRENT_MARK, DEFAULT_CAPABILITIES, DEFAULT_MAX_WRITES, DIAGNOSE_CHECKS, NetworkError, ONBOARD_STEPS, SKIPPABLE_STEPS, STEP_MARKS, SYSTEM_NAMESPACE, SchemaDriftError, SubscribeError, SubstrateClient, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, collectDiagnostics, createClientFromEnv, createDefaultDiagnosticsSink, createH2Fetch, currentStep, decodeList, denyAll, denyVerbs, describeGrant, diagnose, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, noRedirectFetch, not, or, parseGrantEntries, planOnboarding, reconcileIdentities, reduceSubscribeRows, requireCapability, requireIdentity, requireNamespace, requiredOutstanding, resolveAdminCredential, resolveAgentCapabilities, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row, runScript, substrateFetch, tokenAudience, watchRows };
@@ -1,4 +1,4 @@
1
- import { En as Edge, On as EdgeRef } from "./schema-B5WBO8yh.js";
1
+ import { En as EdgeRef, wn as Edge } from "./schema-laGLMvMC.js";
2
2
  //#region ../../packages/substrate-types/src/errors.d.ts
3
3
  /** A by-filter write matched more rows than `SUBSTRATE_FILTER_WRITE_MAX_MATCH`; nothing changed. */
4
4
  declare const FILTER_TOO_BROAD = "filter_too_broad";
@@ -1,4 +1,4 @@
1
- import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema } from "./schema-B5WBO8yh.js";
1
+ import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema } from "./schema-laGLMvMC.js";
2
2
  import { pack as packFrame, unpack as unpackFrame } from "msgpackr";
3
3
  //#region ../../packages/substrate-pack/src/decoder.d.ts
4
4
  interface DecodeContext {
@@ -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,4 @@ 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";
68
- //#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 };
61
+ export { PackDecodeError as a, decodePositional as c, DecodeEnvelopeCtx as i, decodePositionalFromFieldDef as l, unpackFrame as n, SchemaDriftError as o, DecodeContext as r, decodeEnvelope as s, packFrame as t };
@@ -14,9 +14,16 @@ function nodeVersionRefusal(version) {
14
14
  }
15
15
  return null;
16
16
  }
17
+ /**
18
+ * The refusal for this runtime, or null. Bun is exempt: it reports a Node
19
+ * compatibility version (24.x) that says nothing about its own security fixes.
20
+ */
21
+ function runtimeRefusal(versions) {
22
+ return versions.bun !== void 0 ? null : nodeVersionRefusal(versions.node);
23
+ }
17
24
  /** Exits the process with a refusal when the running Node is below the minimum. */
18
25
  function assertNodeVersion() {
19
- const refusal = nodeVersionRefusal(process.versions.node);
26
+ const refusal = runtimeRefusal(process.versions);
20
27
  if (refusal === null) return;
21
28
  process.stderr.write(`${refusal}\n`);
22
29
  process.exit(1);
package/dist/pack.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema } from "./schema-B5WBO8yh.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-DKJXQ031.js";
1
+ import { f as PackEnvelope, i as FieldDef, l as FieldInput, m as Schema, u as MutationSchema } from "./schema-laGLMvMC.js";
2
+ import { a as PackDecodeError, c as decodePositional, i as DecodeEnvelopeCtx, l as decodePositionalFromFieldDef, n as unpackFrame, o as SchemaDriftError, r as DecodeContext, s as decodeEnvelope, t as packFrame } from "./index-rW7fu2Af.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>;
@@ -78,6 +79,15 @@ export declare function withData(envelope: PackEnvelope, data: Record<string, un
78
79
  */
79
80
  export declare function packEnvelopeParts(wire: PackEnvelope, rowsPerPart: number): Generator<Uint8Array>;
80
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;
90
+ //#endregion
81
91
  //#region ../../packages/substrate-pack/src/stream-chunk.d.ts
82
92
  /**
83
93
  * Per §7.4. `shape` is fixed to `'single'`; chunks never carry a list.
@@ -135,14 +145,13 @@ export declare function decodeStreamChunk<T = unknown>(bytes: Buffer | Uint8Arra
135
145
  //#region ../../packages/substrate-pack/src/wire.d.ts
136
146
  type WireMode = 'json' | 'pack';
137
147
  /**
138
- * Encode an outbound WS frame. Pack mode returns msgpack bytes; JSON mode
139
- * returns stringified text. The `mode` argument is the wire-format discriminant
140
- * — call sites can route the result to the right `WebSocket.send` overload via
141
- * 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'`.
142
151
  */
143
152
  export declare function encodeWsFrame(value: unknown, mode: WireMode): string | Uint8Array;
144
153
  /**
145
- * Decode an inbound WS message envelope (the outer `{ id, kind, data?, ... }`
154
+ * Decode an inbound frame envelope (the outer `{ id, kind, data?, ... }`
146
155
  * shape — positional `data` reconstruction is a separate concern handled by
147
156
  * `applyDecodePlanInPlace`).
148
157
  *
@@ -163,7 +172,7 @@ export declare function decodeWsEnvelope<T = unknown>(raw: unknown, mode: WireMo
163
172
  */
164
173
  export declare function isPlainRequestData(value: unknown, depth?: number): boolean;
165
174
  /**
166
- * 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
167
176
  * (parseQualifiedKey, schema probe, fields narrow) happen once at plan-build
168
177
  * time; per-frame decoding then iterates the plan directly.
169
178
  *
@@ -205,4 +214,43 @@ export declare function buildDecodePlan(frameSpec: Record<string, FrameSpecEntry
205
214
  */
206
215
  export declare function applyDecodePlanInPlace(envelope: unknown, plan: DecodePlanEntry[]): void;
207
216
  //#endregion
208
- 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, packFrame, unpackFrame };
package/dist/pack.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { S as withData, _ as encodeEnvelope, a as buildDecodePlan, b as packEnvelopeParts, c as isPlainRequestData, d as PackDecodeError, f as SchemaDriftError, g as PackEncodeError, h as decodePositionalFromFieldDef, i as applyDecodePlanInPlace, l as decodeStreamChunk, m as decodePositional, n as packFrame, o as decodeWsEnvelope, p as decodeEnvelope, r as unpackFrame, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, u as encodeStreamChunk, v as encodePositional, x as positionValue, y as encodePositionalFromFieldDef } from "./src-CdbUzLhB.js";
2
+ import { A as encodePositionalFromFieldDef, C as SchemaDriftError, D as PackEncodeError, E as decodePositionalFromFieldDef, M as positionValue, N as withData, O as encodeEnvelope, S as PackDecodeError, T as decodePositional, _ as isPlainRequestData, a as FRAMES_JSON_MIME, b as MUTATION_ACK_FIELDS, c as HEARTBEAT_FRAME, d as framesEncodingFromAccept, f as withIdleTimeout, g as encodeWsFrame, h as decodeWsEnvelope, i as DEFAULT_STREAM_IDLE_MS, j as packEnvelopeParts, k as encodePositional, l as decodeStreamFrames, m as buildDecodePlan, n as unpackFrame, o as FRAMES_PACK_MIME, p as applyDecodePlanInPlace, r as DEFAULT_MAX_FRAME_BYTES, s as FrameStreamError, t as packFrame, u as encodeStreamFrame, v as decodeStreamChunk, w as decodeEnvelope, x as mutationReturns, y as encodeStreamChunk } from "./src-B6nsPVmD.js";
3
3
  import { n as acceptsPack, t as PACK_MIME } from "./content-type-C7T28xNb.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, packEnvelopeParts, packFrame, positionValue, unpackFrame, withData };
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, packFrame, positionValue, unpackFrame, withData, withIdleTimeout };