@frondruntime/devtools 0.3.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.
@@ -0,0 +1,1062 @@
1
+ import { Effect } from 'effect';
2
+ import { Layer } from 'effect';
3
+ import { Rpc } from 'effect/unstable/rpc';
4
+ import { RpcClient } from 'effect/unstable/rpc';
5
+ import { RpcClientError } from 'effect/unstable/rpc/RpcClientError';
6
+ import { RpcGroup } from 'effect/unstable/rpc';
7
+ import type { Runtime } from '@frondruntime/core';
8
+ import { Schema } from 'effect';
9
+ import { Scope } from 'effect/Scope';
10
+ import { Stream } from 'effect/unstable/rpc/RpcSchema';
11
+ import { YieldableError } from 'effect/Cause';
12
+
13
+ /**
14
+ * Opens the attachment and holds it open.
15
+ *
16
+ * The stream's lifetime *is* the attachment's lifetime: when the socket drops,
17
+ * the handler is interrupted, which is how the hub learns about detachment.
18
+ * There is no explicit detach call and there should not be one — a crashed app
19
+ * cannot send it.
20
+ *
21
+ * Unauthenticated on purpose. Browsers do not apply CORS to WebSockets, so any
22
+ * page a developer visits can dial a loopback port — but this direction only
23
+ * carries data *into* the hub, so the worst an uninvited caller achieves is
24
+ * putting junk in a dashboard. The direction where app data leaves is the MCP
25
+ * endpoint, and a secret on this half while that one is open would buy nothing
26
+ * and cost every host app a value to configure.
27
+ *
28
+ * The consequence, stated plainly because something downstream has to honour
29
+ * it: records arriving here are not proof of their own origin, and a consumer
30
+ * that feeds them to an agent is feeding it untrusted text.
31
+ */
32
+ export declare class Attach extends Attach_base {
33
+ }
34
+
35
+ declare const Attach_base: Rpc.Rpc<"Frond.Attach", Schema.Struct<{
36
+ info: Schema.Struct<{
37
+ readonly protocolVersion: Schema.Number;
38
+ /** Stable for the life of the attaching runtime, including across reconnects. */
39
+ readonly instanceId: Schema.String;
40
+ readonly runtimeId: Schema.String;
41
+ /**
42
+ * How many times this runtime had already attached before this connection.
43
+ *
44
+ * Zero on a first attach; anything higher means the socket dropped and came
45
+ * back, which is the same thing as saying the events in between are gone.
46
+ * Devtools are not durable by design — nothing bridges that gap — so this
47
+ * field exists to make the gap visible rather than to let anyone close it.
48
+ */
49
+ readonly generation: Schema.Number;
50
+ /** Human label for the CLI list, e.g. the host app's package name. */
51
+ readonly name: Schema.String;
52
+ /** Free-form origin hint: "bun", "browser", "expo-ios", … */
53
+ readonly platform: Schema.String;
54
+ readonly startedAt: Schema.Number;
55
+ /** The strongest value policy this app is willing to honor. */
56
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
57
+ }>;
58
+ }>, Stream<Schema.Union<readonly [Schema.Struct<{
59
+ readonly _tag: Schema.tag<"Attached">;
60
+ readonly attachmentId: Schema.String;
61
+ /** What the hub is asking for. The app may downgrade, never upgrade. */
62
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
63
+ }>, Schema.Struct<{
64
+ readonly _tag: Schema.tag<"Ping">;
65
+ readonly at: Schema.Number;
66
+ }>, Schema.Struct<{
67
+ readonly _tag: Schema.tag<"Query">;
68
+ readonly requestId: Schema.String;
69
+ readonly query: Schema.Union<readonly [Schema.Struct<{
70
+ readonly _tag: Schema.tag<"Graph">;
71
+ }>, Schema.Struct<{
72
+ readonly _tag: Schema.tag<"Node">;
73
+ readonly nodeId: Schema.String;
74
+ }>]>;
75
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
76
+ }>]>, typeof HubRejection>, Schema.Never, never, never>;
77
+
78
+ /**
79
+ * Streams a runtime's events to a local hub for as long as the app lives.
80
+ *
81
+ * The plain-function front door, as opposed to {@link attachRuntime}: a host
82
+ * app's entry file is not an Effect program, and making one the price of
83
+ * admission would put this behind a rewrite nobody is going to do.
84
+ *
85
+ * Three properties make it safe to leave in an entry file behind nothing but a
86
+ * dev check. It never throws and never rejects, so a devtools client cannot
87
+ * take down the app it is observing. It retries forever, so the hub can be
88
+ * started, stopped and restarted underneath a running app. And it returns
89
+ * before it connects, so it costs the startup path nothing.
90
+ *
91
+ * "Forever" has one deliberate exception. A hub that *refuses* the attachment —
92
+ * today, only a protocol version mismatch — is answering a question about this
93
+ * build, and every retry would ask it again and get the same answer. So a
94
+ * refusal stops the loop and says so out loud, because the alternative is what
95
+ * this used to do: reconnect every two seconds, silently, for the whole life of
96
+ * a process that was never going to attach.
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * if (import.meta.env.DEV) {
101
+ * attachDevtools({ runtime, name: "checkout-web" });
102
+ * }
103
+ * ```
104
+ *
105
+ * @returns A function that detaches. Idempotent, and safe to ignore.
106
+ */
107
+ export declare function attachDevtools(options: DevtoolsOptions): () => void;
108
+
109
+ /**
110
+ * Transport for one attachment.
111
+ *
112
+ * Exported because the hub dials itself over exactly this layer — same
113
+ * protocol, same serialization, same socket code path as a real app. If
114
+ * self-attach works, the transport works.
115
+ */
116
+ export declare function attachLayer(attachUrl: string): Layer.Layer<RpcClient.Protocol>;
117
+
118
+ /**
119
+ * Who is attaching.
120
+ *
121
+ * `runtimeId` is the runtime's own `runtime-N` counter and collides freely
122
+ * across tabs, reloads, and processes; `instanceId` is minted once per
123
+ * `attachDevtools` call and is the only field safe to use as an identity key.
124
+ */
125
+ export declare const AttachmentInfo: Schema.Struct<{
126
+ readonly protocolVersion: Schema.Number;
127
+ /** Stable for the life of the attaching runtime, including across reconnects. */
128
+ readonly instanceId: Schema.String;
129
+ readonly runtimeId: Schema.String;
130
+ /**
131
+ * How many times this runtime had already attached before this connection.
132
+ *
133
+ * Zero on a first attach; anything higher means the socket dropped and came
134
+ * back, which is the same thing as saying the events in between are gone.
135
+ * Devtools are not durable by design — nothing bridges that gap — so this
136
+ * field exists to make the gap visible rather than to let anyone close it.
137
+ */
138
+ readonly generation: Schema.Number;
139
+ /** Human label for the CLI list, e.g. the host app's package name. */
140
+ readonly name: Schema.String;
141
+ /** Free-form origin hint: "bun", "browser", "expo-ios", … */
142
+ readonly platform: Schema.String;
143
+ readonly startedAt: Schema.Number;
144
+ /** The strongest value policy this app is willing to honor. */
145
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
146
+ }>;
147
+
148
+ export declare type AttachmentInfo = typeof AttachmentInfo.Type;
149
+
150
+ export declare type AttachOptions = {
151
+ readonly runtime: Runtime.Runtime;
152
+ readonly attachUrl: string;
153
+ /** Human label for the hub's list, e.g. the host app's package name. */
154
+ readonly name: string;
155
+ readonly platform: string;
156
+ /**
157
+ * The most this app will ever disclose, whatever the hub asks for.
158
+ *
159
+ * `"shape"` by default: structure, key names, lengths and types, but no
160
+ * values. Sending real values is a decision worth making per app rather than
161
+ * inheriting — the runtimes worth debugging are the ones holding tokens and
162
+ * account state, and a default that ships them is a default that ships them
163
+ * the first time someone forgets.
164
+ */
165
+ readonly values?: ValuePolicy | undefined;
166
+ /**
167
+ * Stable identity for this attachment, unique across processes.
168
+ *
169
+ * Defaults to a fresh UUID, which is right for an ordinary app. The hub sets
170
+ * it explicitly so it can recognise its own self-attachment in the list it
171
+ * serves — `runtimeId` cannot do that job, because it comes from a
172
+ * per-process counter and every runtime's first one is `runtime-1`.
173
+ *
174
+ * Minted per *call*, not per attempt: `attachDevtools` reuses one across
175
+ * reconnects, so an app that outlives a hub restart comes back as itself.
176
+ */
177
+ readonly instanceId?: string;
178
+ /** How many times this runtime has already attached. See `AttachmentInfo`. */
179
+ readonly generation?: number;
180
+ /**
181
+ * Called once the hub has accepted this attempt.
182
+ *
183
+ * Exists so the caller can count reconnections without having to guess from
184
+ * the outside which attempts got as far as being accepted.
185
+ */
186
+ readonly onAttached?: (() => void) | undefined;
187
+ /**
188
+ * Return false to leave a record out of the stream entirely.
189
+ *
190
+ * Distinct from the drop counter below, and the difference matters: a drop is
191
+ * a gap the hub must be told about, because an agent reading the feed has to
192
+ * be able to tell "did not happen" from "was lost". A record excluded here
193
+ * was never in scope, so it is not a gap and is not counted as one.
194
+ *
195
+ * Exists for one caller — the hub, which observes the runtime it is also
196
+ * writing into and would otherwise feed itself forever. An ordinary app has
197
+ * no reason to pass this.
198
+ */
199
+ readonly include?: (record: Runtime.RuntimeEventRecord) => boolean;
200
+ };
201
+
202
+ /**
203
+ * Streams a runtime's events to a hub for as long as the connection lives.
204
+ *
205
+ * The returned Effect does not settle while attached — it *is* the attachment.
206
+ * Fork it into a scope and close the scope to detach; the hub learns about the
207
+ * detachment from the socket dying, which is the only mechanism that also works
208
+ * when the app crashes.
209
+ */
210
+ export declare const attachRuntime: (options: AttachOptions) => Effect.Effect<void, HubRejection | RpcClientError, Scope | RpcClient.Protocol>;
211
+
212
+ export declare function createValueEncoder(policy: EncodePolicy): ValueEncoder;
213
+
214
+ export declare type DevtoolsOptions = {
215
+ readonly runtime: Runtime.Runtime;
216
+ /** Human label for the hub's list, e.g. the host app's package name. */
217
+ readonly name: string;
218
+ /**
219
+ * Where to dial. Defaults to the hub's own default port on loopback.
220
+ *
221
+ * Worth setting for a non-default port, and required for anything that is not
222
+ * on the same host as the hub — a real iOS device or an Android emulator
223
+ * cannot reach `127.0.0.1`, and needs the developer machine's LAN address.
224
+ */
225
+ readonly url?: string | undefined;
226
+ /** Free-form origin hint. Guessed from the environment when omitted. */
227
+ readonly platform?: string | undefined;
228
+ /** See {@link import("./attach.ts").AttachOptions.values}. Defaults to `"shape"`. */
229
+ readonly values?: ValuePolicy | undefined;
230
+ readonly instanceId?: string | undefined;
231
+ /** Return false to leave a record out of the stream entirely. */
232
+ readonly include?: ((record: Runtime.RuntimeEventRecord) => boolean) | undefined;
233
+ /**
234
+ * Called instead of failing, on every attempt that ends badly.
235
+ *
236
+ * Silent by default, and that is the right default: not being able to reach
237
+ * the hub is the *normal* state of an app whose developer has not started one
238
+ * yet, and a devtools client that logged about it once every two seconds
239
+ * would be a worse citizen of the console than one that says nothing.
240
+ *
241
+ * The one exception is a hub that *refuses* the attachment, which is terminal
242
+ * rather than normal. Supplying this takes ownership of reporting it: the
243
+ * console fallback below fires only when this is absent.
244
+ */
245
+ readonly onError?: ((cause: unknown) => void) | undefined;
246
+ };
247
+
248
+ /**
249
+ * A runtime event, flattened and already redacted by the sender.
250
+ *
251
+ * `fields` holds JSON-safe shape descriptors, not live values — encoding
252
+ * happens at observe time, because a `RuntimeEventRecord` carries live
253
+ * references that keep mutating after the record is handed out. The descriptor
254
+ * vocabulary is written down once, in `descriptors.ts`, and what each policy
255
+ * produces lives with the walk that produces it — `describeShape` in `shape.ts`,
256
+ * `describeFull` in `full.ts`, `describeError` in `cause.ts`. Nothing on this
257
+ * side should restate any of it and drift.
258
+ */
259
+ export declare const EncodedEventRecord: Schema.Struct<{
260
+ readonly sequence: Schema.Number;
261
+ readonly recordedAt: Schema.Number;
262
+ /** The `RuntimeEvent` `_tag`, e.g. "GraphNodeLiveDemandChanged". */
263
+ readonly tag: Schema.String;
264
+ readonly category: Schema.Literals<readonly ["command", "diagnostic", "input", "lifecycle", "operation", "state"]>;
265
+ readonly severity: Schema.Literals<readonly ["debug", "error", "info", "warning"]>;
266
+ readonly timeline: Schema.Literals<readonly ["live", "state", "system", "work"]>;
267
+ readonly reportable: Schema.Boolean;
268
+ readonly workId: Schema.Number;
269
+ readonly parentWorkId: Schema.optional<Schema.Number>;
270
+ readonly source: Schema.Literals<readonly ["react", "mobx", "node", "manual", "devtools", "runtime", "signal", "test"]>;
271
+ readonly reason: Schema.Literals<readonly ["start", "stop", "readiness", "retry", "preload", "refresh", "action", "args-update", "live", "release", "eviction", "unsafe-update", "input", "signal"]>;
272
+ readonly priority: Schema.Literals<readonly ["blocking", "visible", "background", "idle"]>;
273
+ readonly nodeIds: Schema.$Array<Schema.String>;
274
+ /**
275
+ * Keyed by the event's own field names, minus `_tag`.
276
+ *
277
+ * A record rather than `Unknown`: every consumer — the UI, and shortly the
278
+ * MCP reader — looks fields up by name, and typing the container as unknown
279
+ * only moves that cast to each of them. The *values* stay unknown, which is
280
+ * the honest part: what a field holds depends on the negotiated policy.
281
+ */
282
+ readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
283
+ /**
284
+ * What went wrong, as chains of causes rather than as single errors.
285
+ *
286
+ * Each entry is `{_: "error", message, causes}`, outermost cause first. The
287
+ * runtime lifts these off the event's own fields, so the same failure also
288
+ * appears in `fields` — encoded identically, so one failure never reads as
289
+ * two. Present at every policy: `"none"` is a statement about values, and a
290
+ * feed that cannot say what is failing is not worth reading.
291
+ */
292
+ readonly failures: Schema.$Array<Schema.Unknown>;
293
+ }>;
294
+
295
+ export declare type EncodedEventRecord = typeof EncodedEventRecord.Type;
296
+
297
+ export declare const EncodedGraphEdge: Schema.Struct<{
298
+ readonly from: Schema.String;
299
+ readonly to: Schema.String;
300
+ /** The dependency name the dependent declared, not the target's tag. */
301
+ readonly dependency: Schema.String;
302
+ }>;
303
+
304
+ export declare type EncodedGraphEdge = typeof EncodedGraphEdge.Type;
305
+
306
+ /**
307
+ * One node, as it is right now.
308
+ *
309
+ * Split the same way `EncodedEventRecord` is: the fields a reader filters and
310
+ * branches on are typed, and anything that came out of the app's own data is
311
+ * `Unknown`, because what it holds depends on the negotiated policy. Giving
312
+ * `NodeStatus`, `NodeOperation` and the rest real schemas here would copy core's
313
+ * type surface into the wire contract and guarantee the two drift apart.
314
+ *
315
+ * Every field here has to earn its place in *every row* of a graph read, which
316
+ * is why core's `label` and `key` are not among them: `label` is a formatting of
317
+ * `tag` and `key` is already inside `nodeId`, so both are the same fact charged
318
+ * twice, a few hundred times per snapshot.
319
+ */
320
+ export declare const EncodedNodeSnapshot: Schema.Struct<{
321
+ readonly nodeId: Schema.String;
322
+ /** The spec's tag, e.g. `"orders"`. Shared by every key; `nodeId` is the identity. */
323
+ readonly tag: Schema.String;
324
+ /**
325
+ * `"node"`, `"service"`, `"resource"` or `"facade"` — the one identity field
326
+ * nothing else here implies.
327
+ *
328
+ * It says whether this row owns a release: a resource holds something the app
329
+ * has to give back, and a reader deciding what a leak looks like cannot get
330
+ * that from `tag` or `nodeId`.
331
+ *
332
+ * Carried as a string rather than a literal union so a hub can read an app
333
+ * built against a core that has since grown a kind. Version equality already
334
+ * gates the wire; making this field the second thing that can reject a
335
+ * snapshot would buy nothing.
336
+ */
337
+ readonly kind: Schema.String;
338
+ /**
339
+ * Which arm of core's `NodeSnapshot` this is: `Unwired`, `Idle`, `Pending`,
340
+ * `Ready`, `ReadinessError`, `Releasing`, `Invalid`.
341
+ *
342
+ * Typed and hoisted because it is the one field every reader branches on.
343
+ * Left inside the encoded `status` it would oblige an agent to understand this
344
+ * encoder's descriptors before it could ask which nodes are broken.
345
+ */
346
+ readonly state: Schema.String;
347
+ /**
348
+ * Core's per-node write counter, carried verbatim.
349
+ *
350
+ * The cheap way to tell "still the value I saw last time" from "recomputed,
351
+ * and happens to look the same" — which no amount of comparing encoded
352
+ * results can answer once a policy has redacted them.
353
+ */
354
+ readonly revision: Schema.Number;
355
+ readonly status: Schema.Unknown;
356
+ readonly liveDemand: Schema.Unknown;
357
+ readonly operation: Schema.Unknown;
358
+ readonly resultValidity: Schema.optional<Schema.Unknown>;
359
+ /**
360
+ * Why this node is not usable, as a chain of causes.
361
+ *
362
+ * Same encoding as `EncodedEventRecord.failures`, deliberately: a node failed
363
+ * in the snapshot and the event that failed it should read identically.
364
+ */
365
+ readonly failure: Schema.optional<Schema.Unknown>;
366
+ /**
367
+ * The last operation that failed, as `{operationId, kind, at, error}`.
368
+ *
369
+ * Distinct from `failure`, and the difference is the whole point of keeping
370
+ * it: a node can be `Ready` on a stale-but-valid result while its most recent
371
+ * refresh failed. `failure` would be absent and everything would look fine.
372
+ */
373
+ readonly operationFailure: Schema.optional<Schema.Unknown>;
374
+ /** Why live demand could not be served, as `{at, failures}`. */
375
+ readonly liveFailure: Schema.optional<Schema.Unknown>;
376
+ /**
377
+ * The node's current value.
378
+ *
379
+ * Only ever present on a single-node query. A graph read of a few hundred
380
+ * nodes is a topology question, and answering it with every result attached
381
+ * would put the whole application state on the wire to draw a diagram.
382
+ */
383
+ readonly result: Schema.optional<Schema.Unknown>;
384
+ }>;
385
+
386
+ export declare type EncodedNodeSnapshot = typeof EncodedNodeSnapshot.Type;
387
+
388
+ /**
389
+ * The graph as the app sees it right now, reduced to something sendable.
390
+ *
391
+ * The counterpart to {@link encodeRecord}, and deliberately built from the same
392
+ * {@link ValueEncoder}: a node that is failing in a snapshot and the event that
393
+ * failed it should read identically, and the way to guarantee that is for one
394
+ * piece of code to describe both.
395
+ *
396
+ * Two things in a `NodeSnapshot` cannot cross and are dropped rather than
397
+ * approximated. `Pending.attempt` is a `Promise<NodeRead>` — nothing about it
398
+ * survives serialization, and `state: "Pending"` already says the only thing it
399
+ * would have told a reader. And `Ready.node` is the node facade object, which is
400
+ * mostly methods; `result` is the value someone actually meant to ask about.
401
+ *
402
+ * Two more are dropped for costing a line each in every row of a graph read
403
+ * while saying something the row already said: `label` is core's presentation
404
+ * formatting of `tag`, and `key` is the second half of `nodeId`. `kind` stays —
405
+ * `"node"` against `"resource"` is nowhere in the other fields, and it is what
406
+ * tells a reader whether release semantics apply to this row.
407
+ */
408
+ export declare function encodeGraphSnapshot(snapshot: Runtime.RuntimeSnapshot, request: SnapshotRequest): GraphSnapshot;
409
+
410
+ /**
411
+ * What this encoder can produce. All three policies are implemented.
412
+ *
413
+ * `"full"` is a stub in the sense that it has no per-field allowlist and no
414
+ * redaction — it sends what it finds. It is not a stub in its bounds: cycles,
415
+ * depth, and breadth are enforced, because those three are not polish. A cyclic
416
+ * or unboundedly deep graph result would hang the observed app inside its own
417
+ * devtools, on its own event loop.
418
+ *
419
+ * What those bounds are not is a size budget. This socket is loopback and the
420
+ * eventual reader is an agent's context window, so the scarce resource is the
421
+ * reader's attention rather than the wire — which is why `"shape"` spends real
422
+ * effort being terse and `"full"` spends none.
423
+ */
424
+ export declare type EncodePolicy = ValuePolicy;
425
+
426
+ /**
427
+ * Encodes one runtime event for the wire.
428
+ *
429
+ * Classification, work context, and node ids are metadata the runtime already
430
+ * owns and are copied verbatim — they are ids and enum members, never user
431
+ * data. Only the event body goes through the value encoder.
432
+ */
433
+ export declare function encodeRecord(record: Runtime.RuntimeEventRecord, policy: EncodePolicy): EncodedEventRecord;
434
+
435
+ export declare const FrondHubRpcs: RpcGroup.RpcGroup<typeof Attach | typeof Ingest | typeof Reply>;
436
+
437
+ /** Every node and edge, with statuses but without results. */
438
+ export declare const GraphQuery: Schema.Struct<{
439
+ readonly _tag: Schema.tag<"Graph">;
440
+ }>;
441
+
442
+ /**
443
+ * The graph at one instant.
444
+ *
445
+ * The counterpart to the event stream rather than a replacement for it: events
446
+ * say what happened, this says what is true. `capturedAt` and `sequence` are
447
+ * what let a reader hold both at once — a snapshot taken "as of sequence 4412"
448
+ * can be lined up against the log the reader already has, instead of being a
449
+ * second account of the same system with no way to relate them.
450
+ */
451
+ export declare const GraphSnapshot: Schema.Struct<{
452
+ readonly capturedAt: Schema.Number;
453
+ /**
454
+ * The last event sequence the runtime had recorded when this was taken.
455
+ *
456
+ * Absent on a runtime that has not emitted yet, which is the only honest
457
+ * answer — zero would claim a position in a log that has none.
458
+ */
459
+ readonly sequence: Schema.optional<Schema.Number>;
460
+ readonly runtimeId: Schema.String;
461
+ readonly runtimeStatus: Schema.String;
462
+ readonly graphStatus: Schema.String;
463
+ readonly observedInputs: Schema.Number;
464
+ /**
465
+ * The policy the app actually applied, which may be less than was asked for.
466
+ *
467
+ * Stated per snapshot rather than inferred from the attachment: a reader that
468
+ * finds no `result` on a node needs to tell "redacted" from "not ready", and
469
+ * those are the same absence.
470
+ */
471
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
472
+ readonly nodes: Schema.$Array<Schema.Struct<{
473
+ readonly nodeId: Schema.String;
474
+ /** The spec's tag, e.g. `"orders"`. Shared by every key; `nodeId` is the identity. */
475
+ readonly tag: Schema.String;
476
+ /**
477
+ * `"node"`, `"service"`, `"resource"` or `"facade"` — the one identity field
478
+ * nothing else here implies.
479
+ *
480
+ * It says whether this row owns a release: a resource holds something the app
481
+ * has to give back, and a reader deciding what a leak looks like cannot get
482
+ * that from `tag` or `nodeId`.
483
+ *
484
+ * Carried as a string rather than a literal union so a hub can read an app
485
+ * built against a core that has since grown a kind. Version equality already
486
+ * gates the wire; making this field the second thing that can reject a
487
+ * snapshot would buy nothing.
488
+ */
489
+ readonly kind: Schema.String;
490
+ /**
491
+ * Which arm of core's `NodeSnapshot` this is: `Unwired`, `Idle`, `Pending`,
492
+ * `Ready`, `ReadinessError`, `Releasing`, `Invalid`.
493
+ *
494
+ * Typed and hoisted because it is the one field every reader branches on.
495
+ * Left inside the encoded `status` it would oblige an agent to understand this
496
+ * encoder's descriptors before it could ask which nodes are broken.
497
+ */
498
+ readonly state: Schema.String;
499
+ /**
500
+ * Core's per-node write counter, carried verbatim.
501
+ *
502
+ * The cheap way to tell "still the value I saw last time" from "recomputed,
503
+ * and happens to look the same" — which no amount of comparing encoded
504
+ * results can answer once a policy has redacted them.
505
+ */
506
+ readonly revision: Schema.Number;
507
+ readonly status: Schema.Unknown;
508
+ readonly liveDemand: Schema.Unknown;
509
+ readonly operation: Schema.Unknown;
510
+ readonly resultValidity: Schema.optional<Schema.Unknown>;
511
+ /**
512
+ * Why this node is not usable, as a chain of causes.
513
+ *
514
+ * Same encoding as `EncodedEventRecord.failures`, deliberately: a node failed
515
+ * in the snapshot and the event that failed it should read identically.
516
+ */
517
+ readonly failure: Schema.optional<Schema.Unknown>;
518
+ /**
519
+ * The last operation that failed, as `{operationId, kind, at, error}`.
520
+ *
521
+ * Distinct from `failure`, and the difference is the whole point of keeping
522
+ * it: a node can be `Ready` on a stale-but-valid result while its most recent
523
+ * refresh failed. `failure` would be absent and everything would look fine.
524
+ */
525
+ readonly operationFailure: Schema.optional<Schema.Unknown>;
526
+ /** Why live demand could not be served, as `{at, failures}`. */
527
+ readonly liveFailure: Schema.optional<Schema.Unknown>;
528
+ /**
529
+ * The node's current value.
530
+ *
531
+ * Only ever present on a single-node query. A graph read of a few hundred
532
+ * nodes is a topology question, and answering it with every result attached
533
+ * would put the whole application state on the wire to draw a diagram.
534
+ */
535
+ readonly result: Schema.optional<Schema.Unknown>;
536
+ }>>;
537
+ readonly edges: Schema.$Array<Schema.Struct<{
538
+ readonly from: Schema.String;
539
+ readonly to: Schema.String;
540
+ /** The dependency name the dependent declared, not the target's tag. */
541
+ readonly dependency: Schema.String;
542
+ }>>;
543
+ }>;
544
+
545
+ export declare type GraphSnapshot = typeof GraphSnapshot.Type;
546
+
547
+ export declare const HUB_ATTACH_PATH = "/attach";
548
+
549
+ /** Where an app dials when it was given no explicit URL. */
550
+ export declare const HUB_DEFAULT_ATTACH_URL = "ws://127.0.0.1:17391/attach";
551
+
552
+ export declare const HUB_DEFAULT_HOST = "127.0.0.1";
553
+
554
+ /**
555
+ * Unregistered, and chosen for the band rather than the number.
556
+ *
557
+ * Above 9999 to clear the entire dev-server zone — Vite, Metro, Expo, CRA,
558
+ * Django, Storybook, the node inspector — and below 32768 so it can never
559
+ * collide with an ephemeral source port on Linux, whose range starts there.
560
+ *
561
+ * Stable on purpose. Apps hardcode it, so a hub that drifted to the next free
562
+ * port on a collision would leave them dialing nothing, which presents as "the
563
+ * runtime is not emitting" — the most expensive way to fail.
564
+ */
565
+ export declare const HUB_DEFAULT_PORT = 17391;
566
+
567
+ /**
568
+ * Wire contract between an attached Frond runtime and the hub.
569
+ *
570
+ * Direction of the RPC roles is deliberate and inverted from who dials: the
571
+ * hub listens and is the RPC *server*, the app dials out and is the RPC
572
+ * *client*. That keeps the app free of any listening socket, and it is the only
573
+ * arrangement both `RpcServer.layerHttp` and `RpcClient.layerProtocolSocket`
574
+ * support without a hand-written socket adapter on either side.
575
+ *
576
+ * Hub-to-app work (state reads, and later refresh and action invocation)
577
+ * therefore does not travel as a plain RPC call. It rides the `Attach` response
578
+ * stream as a `Query` command, and the app answers with a separate unary
579
+ * `Reply` correlated by `requestId`. `Attach` is the only long-lived call.
580
+ *
581
+ * Version equality is exact, on both sides, and there is no capability
582
+ * negotiation. That is a deliberate choice rather than an omission: `HubCommand`
583
+ * is a schema union, so an app one version behind would fail to decode a command
584
+ * it has never heard of and drop its socket — presenting as "the runtime stopped
585
+ * emitting", which is the most expensive way this can fail. Refusing the
586
+ * attachment outright says the same thing immediately and in words.
587
+ *
588
+ * The number counts published generations of *this contract*, and moves on its
589
+ * own schedule — it is not derived from, and does not track, the npm version of
590
+ * any package. Tying the two was the earlier arrangement and it was wrong in
591
+ * both directions: a release that touched nothing on the wire still moved the
592
+ * number and refused every app that had not upgraded, while a genuine schema
593
+ * change inside one release moved nothing and let two builds that disagreed
594
+ * attach to each other. Starting at 1 with the first published hub, so what the
595
+ * number counts is generations anyone could have installed.
596
+ */
597
+ export declare const HUB_PROTOCOL_VERSION = 1;
598
+
599
+ /** Hub accepted the attachment and assigned it an id. */
600
+ export declare const HubAttached: Schema.Struct<{
601
+ readonly _tag: Schema.tag<"Attached">;
602
+ readonly attachmentId: Schema.String;
603
+ /** What the hub is asking for. The app may downgrade, never upgrade. */
604
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
605
+ }>;
606
+
607
+ /** Server-to-client commands. */
608
+ export declare const HubCommand: Schema.Union<readonly [Schema.Struct<{
609
+ readonly _tag: Schema.tag<"Attached">;
610
+ readonly attachmentId: Schema.String;
611
+ /** What the hub is asking for. The app may downgrade, never upgrade. */
612
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
613
+ }>, Schema.Struct<{
614
+ readonly _tag: Schema.tag<"Ping">;
615
+ readonly at: Schema.Number;
616
+ }>, Schema.Struct<{
617
+ readonly _tag: Schema.tag<"Query">;
618
+ readonly requestId: Schema.String;
619
+ readonly query: Schema.Union<readonly [Schema.Struct<{
620
+ readonly _tag: Schema.tag<"Graph">;
621
+ }>, Schema.Struct<{
622
+ readonly _tag: Schema.tag<"Node">;
623
+ readonly nodeId: Schema.String;
624
+ }>]>;
625
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
626
+ }>]>;
627
+
628
+ export declare type HubCommand = typeof HubCommand.Type;
629
+
630
+ /** Liveness probe; the app answers by continuing to hold the stream open. */
631
+ export declare const HubPing: Schema.Struct<{
632
+ readonly _tag: Schema.tag<"Ping">;
633
+ readonly at: Schema.Number;
634
+ }>;
635
+
636
+ /**
637
+ * Asks the app what is true right now.
638
+ *
639
+ * Rides this stream because the hub has no way to call the app — it listens and
640
+ * the app dials, so the only open channel in this direction is the `Attach`
641
+ * response. The answer comes back as a separate `Reply` call rather than in
642
+ * band, which is why `requestId` exists.
643
+ *
644
+ * `values` is requested per query, not per attachment. A stream of events and a
645
+ * deliberate read of one node are different acts: the first is a firehose worth
646
+ * keeping cheap, the second is someone asking a specific question. Both are
647
+ * still clamped by the app's own ceiling, so this widens nothing the app has not
648
+ * already agreed to.
649
+ */
650
+ export declare const HubQuery: Schema.Struct<{
651
+ readonly _tag: Schema.tag<"Query">;
652
+ readonly requestId: Schema.String;
653
+ readonly query: Schema.Union<readonly [Schema.Struct<{
654
+ readonly _tag: Schema.tag<"Graph">;
655
+ }>, Schema.Struct<{
656
+ readonly _tag: Schema.tag<"Node">;
657
+ readonly nodeId: Schema.String;
658
+ }>]>;
659
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
660
+ }>;
661
+
662
+ /**
663
+ * The hub refused the attachment.
664
+ *
665
+ * `reason` is prose for a terminal, not a code to branch on. It is the last
666
+ * thing said on a connection that is about to close, and the symptom on the
667
+ * other end — devtools that quietly never appear — carries no information at
668
+ * all, so the string has to carry the diagnosis and the next step instead. The
669
+ * hub's version mismatch names both versions and which side to upgrade.
670
+ *
671
+ * Specific on purpose, where a rejection elsewhere would be deliberately vague:
672
+ * there is no authentication on this call (see `Attach`), so an uninvited
673
+ * caller learns nothing here it could not learn by dialing and observing, and
674
+ * vagueness would cost only the developer who is actually trying to attach.
675
+ */
676
+ export declare class HubRejection extends HubRejection_base {
677
+ }
678
+
679
+ declare const HubRejection_base: Schema.Class<HubRejection, Schema.TaggedStruct<"HubRejection", {
680
+ readonly reason: Schema.String;
681
+ }>, YieldableError>;
682
+
683
+ /**
684
+ * Pushes a batch of events.
685
+ *
686
+ * `droppedSince` is the sender's count of records it could not buffer since the
687
+ * previous batch. It is not optional and not a nicety: a devtools feed that
688
+ * silently loses events is worse than one that admits to a gap, because an
689
+ * agent reasoning over the stream cannot tell "did not happen" from "was
690
+ * dropped".
691
+ */
692
+ export declare class Ingest extends Ingest_base {
693
+ }
694
+
695
+ declare const Ingest_base: Rpc.Rpc<"Frond.Ingest", Schema.Struct<{
696
+ attachmentId: Schema.String;
697
+ records: Schema.$Array<Schema.Struct<{
698
+ readonly sequence: Schema.Number;
699
+ readonly recordedAt: Schema.Number;
700
+ /** The `RuntimeEvent` `_tag`, e.g. "GraphNodeLiveDemandChanged". */
701
+ readonly tag: Schema.String;
702
+ readonly category: Schema.Literals<readonly ["command", "diagnostic", "input", "lifecycle", "operation", "state"]>;
703
+ readonly severity: Schema.Literals<readonly ["debug", "error", "info", "warning"]>;
704
+ readonly timeline: Schema.Literals<readonly ["live", "state", "system", "work"]>;
705
+ readonly reportable: Schema.Boolean;
706
+ readonly workId: Schema.Number;
707
+ readonly parentWorkId: Schema.optional<Schema.Number>;
708
+ readonly source: Schema.Literals<readonly ["react", "mobx", "node", "manual", "devtools", "runtime", "signal", "test"]>;
709
+ readonly reason: Schema.Literals<readonly ["start", "stop", "readiness", "retry", "preload", "refresh", "action", "args-update", "live", "release", "eviction", "unsafe-update", "input", "signal"]>;
710
+ readonly priority: Schema.Literals<readonly ["blocking", "visible", "background", "idle"]>;
711
+ readonly nodeIds: Schema.$Array<Schema.String>;
712
+ /**
713
+ * Keyed by the event's own field names, minus `_tag`.
714
+ *
715
+ * A record rather than `Unknown`: every consumer — the UI, and shortly the
716
+ * MCP reader — looks fields up by name, and typing the container as unknown
717
+ * only moves that cast to each of them. The *values* stay unknown, which is
718
+ * the honest part: what a field holds depends on the negotiated policy.
719
+ */
720
+ readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
721
+ /**
722
+ * What went wrong, as chains of causes rather than as single errors.
723
+ *
724
+ * Each entry is `{_: "error", message, causes}`, outermost cause first. The
725
+ * runtime lifts these off the event's own fields, so the same failure also
726
+ * appears in `fields` — encoded identically, so one failure never reads as
727
+ * two. Present at every policy: `"none"` is a statement about values, and a
728
+ * feed that cannot say what is failing is not worth reading.
729
+ */
730
+ readonly failures: Schema.$Array<Schema.Unknown>;
731
+ }>>;
732
+ droppedSince: Schema.Number;
733
+ }>, Schema.Void, Schema.Never, never, never>;
734
+
735
+ /** One node, with its result and the edges incident on it. */
736
+ export declare const NodeQuery: Schema.Struct<{
737
+ readonly _tag: Schema.tag<"Node">;
738
+ readonly nodeId: Schema.String;
739
+ }>;
740
+
741
+ /**
742
+ * The app's answer to one query.
743
+ *
744
+ * `Failed` rather than an RPC error because the reply is a separate call from
745
+ * the request: an error on this channel would fail the *reply*, which is not
746
+ * the thing that went wrong, and would leave the hub waiting out its timeout
747
+ * for an answer that already came back.
748
+ */
749
+ export declare const QueryOutcome: Schema.Union<readonly [Schema.Struct<{
750
+ readonly _tag: Schema.tag<"Snapshot">;
751
+ readonly snapshot: Schema.Struct<{
752
+ readonly capturedAt: Schema.Number;
753
+ /**
754
+ * The last event sequence the runtime had recorded when this was taken.
755
+ *
756
+ * Absent on a runtime that has not emitted yet, which is the only honest
757
+ * answer — zero would claim a position in a log that has none.
758
+ */
759
+ readonly sequence: Schema.optional<Schema.Number>;
760
+ readonly runtimeId: Schema.String;
761
+ readonly runtimeStatus: Schema.String;
762
+ readonly graphStatus: Schema.String;
763
+ readonly observedInputs: Schema.Number;
764
+ /**
765
+ * The policy the app actually applied, which may be less than was asked for.
766
+ *
767
+ * Stated per snapshot rather than inferred from the attachment: a reader that
768
+ * finds no `result` on a node needs to tell "redacted" from "not ready", and
769
+ * those are the same absence.
770
+ */
771
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
772
+ readonly nodes: Schema.$Array<Schema.Struct<{
773
+ readonly nodeId: Schema.String;
774
+ /** The spec's tag, e.g. `"orders"`. Shared by every key; `nodeId` is the identity. */
775
+ readonly tag: Schema.String;
776
+ /**
777
+ * `"node"`, `"service"`, `"resource"` or `"facade"` — the one identity field
778
+ * nothing else here implies.
779
+ *
780
+ * It says whether this row owns a release: a resource holds something the app
781
+ * has to give back, and a reader deciding what a leak looks like cannot get
782
+ * that from `tag` or `nodeId`.
783
+ *
784
+ * Carried as a string rather than a literal union so a hub can read an app
785
+ * built against a core that has since grown a kind. Version equality already
786
+ * gates the wire; making this field the second thing that can reject a
787
+ * snapshot would buy nothing.
788
+ */
789
+ readonly kind: Schema.String;
790
+ /**
791
+ * Which arm of core's `NodeSnapshot` this is: `Unwired`, `Idle`, `Pending`,
792
+ * `Ready`, `ReadinessError`, `Releasing`, `Invalid`.
793
+ *
794
+ * Typed and hoisted because it is the one field every reader branches on.
795
+ * Left inside the encoded `status` it would oblige an agent to understand this
796
+ * encoder's descriptors before it could ask which nodes are broken.
797
+ */
798
+ readonly state: Schema.String;
799
+ /**
800
+ * Core's per-node write counter, carried verbatim.
801
+ *
802
+ * The cheap way to tell "still the value I saw last time" from "recomputed,
803
+ * and happens to look the same" — which no amount of comparing encoded
804
+ * results can answer once a policy has redacted them.
805
+ */
806
+ readonly revision: Schema.Number;
807
+ readonly status: Schema.Unknown;
808
+ readonly liveDemand: Schema.Unknown;
809
+ readonly operation: Schema.Unknown;
810
+ readonly resultValidity: Schema.optional<Schema.Unknown>;
811
+ /**
812
+ * Why this node is not usable, as a chain of causes.
813
+ *
814
+ * Same encoding as `EncodedEventRecord.failures`, deliberately: a node failed
815
+ * in the snapshot and the event that failed it should read identically.
816
+ */
817
+ readonly failure: Schema.optional<Schema.Unknown>;
818
+ /**
819
+ * The last operation that failed, as `{operationId, kind, at, error}`.
820
+ *
821
+ * Distinct from `failure`, and the difference is the whole point of keeping
822
+ * it: a node can be `Ready` on a stale-but-valid result while its most recent
823
+ * refresh failed. `failure` would be absent and everything would look fine.
824
+ */
825
+ readonly operationFailure: Schema.optional<Schema.Unknown>;
826
+ /** Why live demand could not be served, as `{at, failures}`. */
827
+ readonly liveFailure: Schema.optional<Schema.Unknown>;
828
+ /**
829
+ * The node's current value.
830
+ *
831
+ * Only ever present on a single-node query. A graph read of a few hundred
832
+ * nodes is a topology question, and answering it with every result attached
833
+ * would put the whole application state on the wire to draw a diagram.
834
+ */
835
+ readonly result: Schema.optional<Schema.Unknown>;
836
+ }>>;
837
+ readonly edges: Schema.$Array<Schema.Struct<{
838
+ readonly from: Schema.String;
839
+ readonly to: Schema.String;
840
+ /** The dependency name the dependent declared, not the target's tag. */
841
+ readonly dependency: Schema.String;
842
+ }>>;
843
+ }>;
844
+ }>, Schema.Struct<{
845
+ readonly _tag: Schema.tag<"Failed">;
846
+ readonly reason: Schema.String;
847
+ }>]>;
848
+
849
+ export declare type QueryOutcome = typeof QueryOutcome.Type;
850
+
851
+ /**
852
+ * Answers one `Query`.
853
+ *
854
+ * A unary call in the app-to-hub direction, correlated by `requestId`, because
855
+ * the RPC roles only run that way — see the note at the top of this file. The
856
+ * consequence worth naming: a reply is not causally tied to the stream that
857
+ * asked for it, so the hub has to time its requests out. An app that dies
858
+ * mid-query simply never calls this.
859
+ */
860
+ export declare class Reply extends Reply_base {
861
+ }
862
+
863
+ declare const Reply_base: Rpc.Rpc<"Frond.Reply", Schema.Struct<{
864
+ attachmentId: Schema.String;
865
+ requestId: Schema.String;
866
+ outcome: Schema.Union<readonly [Schema.Struct<{
867
+ readonly _tag: Schema.tag<"Snapshot">;
868
+ readonly snapshot: Schema.Struct<{
869
+ readonly capturedAt: Schema.Number;
870
+ /**
871
+ * The last event sequence the runtime had recorded when this was taken.
872
+ *
873
+ * Absent on a runtime that has not emitted yet, which is the only honest
874
+ * answer — zero would claim a position in a log that has none.
875
+ */
876
+ readonly sequence: Schema.optional<Schema.Number>;
877
+ readonly runtimeId: Schema.String;
878
+ readonly runtimeStatus: Schema.String;
879
+ readonly graphStatus: Schema.String;
880
+ readonly observedInputs: Schema.Number;
881
+ /**
882
+ * The policy the app actually applied, which may be less than was asked for.
883
+ *
884
+ * Stated per snapshot rather than inferred from the attachment: a reader that
885
+ * finds no `result` on a node needs to tell "redacted" from "not ready", and
886
+ * those are the same absence.
887
+ */
888
+ readonly values: Schema.Literals<readonly ["none", "shape", "full"]>;
889
+ readonly nodes: Schema.$Array<Schema.Struct<{
890
+ readonly nodeId: Schema.String;
891
+ /** The spec's tag, e.g. `"orders"`. Shared by every key; `nodeId` is the identity. */
892
+ readonly tag: Schema.String;
893
+ /**
894
+ * `"node"`, `"service"`, `"resource"` or `"facade"` — the one identity field
895
+ * nothing else here implies.
896
+ *
897
+ * It says whether this row owns a release: a resource holds something the app
898
+ * has to give back, and a reader deciding what a leak looks like cannot get
899
+ * that from `tag` or `nodeId`.
900
+ *
901
+ * Carried as a string rather than a literal union so a hub can read an app
902
+ * built against a core that has since grown a kind. Version equality already
903
+ * gates the wire; making this field the second thing that can reject a
904
+ * snapshot would buy nothing.
905
+ */
906
+ readonly kind: Schema.String;
907
+ /**
908
+ * Which arm of core's `NodeSnapshot` this is: `Unwired`, `Idle`, `Pending`,
909
+ * `Ready`, `ReadinessError`, `Releasing`, `Invalid`.
910
+ *
911
+ * Typed and hoisted because it is the one field every reader branches on.
912
+ * Left inside the encoded `status` it would oblige an agent to understand this
913
+ * encoder's descriptors before it could ask which nodes are broken.
914
+ */
915
+ readonly state: Schema.String;
916
+ /**
917
+ * Core's per-node write counter, carried verbatim.
918
+ *
919
+ * The cheap way to tell "still the value I saw last time" from "recomputed,
920
+ * and happens to look the same" — which no amount of comparing encoded
921
+ * results can answer once a policy has redacted them.
922
+ */
923
+ readonly revision: Schema.Number;
924
+ readonly status: Schema.Unknown;
925
+ readonly liveDemand: Schema.Unknown;
926
+ readonly operation: Schema.Unknown;
927
+ readonly resultValidity: Schema.optional<Schema.Unknown>;
928
+ /**
929
+ * Why this node is not usable, as a chain of causes.
930
+ *
931
+ * Same encoding as `EncodedEventRecord.failures`, deliberately: a node failed
932
+ * in the snapshot and the event that failed it should read identically.
933
+ */
934
+ readonly failure: Schema.optional<Schema.Unknown>;
935
+ /**
936
+ * The last operation that failed, as `{operationId, kind, at, error}`.
937
+ *
938
+ * Distinct from `failure`, and the difference is the whole point of keeping
939
+ * it: a node can be `Ready` on a stale-but-valid result while its most recent
940
+ * refresh failed. `failure` would be absent and everything would look fine.
941
+ */
942
+ readonly operationFailure: Schema.optional<Schema.Unknown>;
943
+ /** Why live demand could not be served, as `{at, failures}`. */
944
+ readonly liveFailure: Schema.optional<Schema.Unknown>;
945
+ /**
946
+ * The node's current value.
947
+ *
948
+ * Only ever present on a single-node query. A graph read of a few hundred
949
+ * nodes is a topology question, and answering it with every result attached
950
+ * would put the whole application state on the wire to draw a diagram.
951
+ */
952
+ readonly result: Schema.optional<Schema.Unknown>;
953
+ }>>;
954
+ readonly edges: Schema.$Array<Schema.Struct<{
955
+ readonly from: Schema.String;
956
+ readonly to: Schema.String;
957
+ /** The dependency name the dependent declared, not the target's tag. */
958
+ readonly dependency: Schema.String;
959
+ }>>;
960
+ }>;
961
+ }>, Schema.Struct<{
962
+ readonly _tag: Schema.tag<"Failed">;
963
+ readonly reason: Schema.String;
964
+ }>]>;
965
+ }>, Schema.Void, Schema.Never, never, never>;
966
+
967
+ /**
968
+ * Clamps what the hub asked for to what this app is willing to send.
969
+ *
970
+ * The whole negotiation lives here, in one expression, rather than as a policy
971
+ * check threaded through the encoder: a sender may always answer with less than
972
+ * it was asked for and may never answer with more, and that rule is only
973
+ * trustworthy if there is exactly one place it can be got wrong.
974
+ *
975
+ * Its own module for the same reason. This is the one function in the package
976
+ * whose failure mode is disclosure rather than a bad rendering, and it should be
977
+ * readable — and testable — without the several hundred lines of walking that
978
+ * depend on it.
979
+ */
980
+ export declare function resolvePolicy(requested: ValuePolicy, ceiling: ValuePolicy): EncodePolicy;
981
+
982
+ export declare const RuntimeEventCategory: Schema.Literals<readonly ["command", "diagnostic", "input", "lifecycle", "operation", "state"]>;
983
+
984
+ export declare const RuntimeEventSeverity: Schema.Literals<readonly ["debug", "error", "info", "warning"]>;
985
+
986
+ export declare const RuntimeEventTimeline: Schema.Literals<readonly ["live", "state", "system", "work"]>;
987
+
988
+ export declare const RuntimeWorkPriority: Schema.Literals<readonly ["blocking", "visible", "background", "idle"]>;
989
+
990
+ export declare const RuntimeWorkReason: Schema.Literals<readonly ["start", "stop", "readiness", "retry", "preload", "refresh", "action", "args-update", "live", "release", "eviction", "unsafe-update", "input", "signal"]>;
991
+
992
+ export declare const RuntimeWorkSource: Schema.Literals<readonly ["react", "mobx", "node", "manual", "devtools", "runtime", "signal", "test"]>;
993
+
994
+ export declare type SnapshotRequest = {
995
+ readonly policy: EncodePolicy;
996
+ readonly capturedAt: number;
997
+ /**
998
+ * Narrow to one node and include its result.
999
+ *
1000
+ * The whole difference between the two queries. A graph read answers a
1001
+ * topology question and a few hundred results would drown it; a node read is
1002
+ * someone asking what one value currently is, which is the only question a
1003
+ * result answers.
1004
+ */
1005
+ readonly nodeId?: string | undefined;
1006
+ };
1007
+
1008
+ export declare const StateQuery: Schema.Union<readonly [Schema.Struct<{
1009
+ readonly _tag: Schema.tag<"Graph">;
1010
+ }>, Schema.Struct<{
1011
+ readonly _tag: Schema.tag<"Node">;
1012
+ readonly nodeId: Schema.String;
1013
+ }>]>;
1014
+
1015
+ export declare type StateQuery = typeof StateQuery.Type;
1016
+
1017
+ /**
1018
+ * Applies a policy to a value.
1019
+ *
1020
+ * The three encoders this composes are deliberately separate modules: the clamp
1021
+ * that decides disclosure (`policy.ts`), the walk that says as little as it can
1022
+ * (`shape.ts`), the walk that says as much as it can (`full.ts`), and the one
1023
+ * that describes failures the same way at every policy (`cause.ts`). What is
1024
+ * left here is the wiring — which walk a policy gets, and how one runtime event
1025
+ * is laid out on the wire.
1026
+ */
1027
+ /**
1028
+ * A policy, applied to one answer.
1029
+ *
1030
+ * One of these per record and per snapshot, because the budget it closes over
1031
+ * is the thing worth bounding: what a single answer costs the wire. A record
1032
+ * with one enormous field should spend its own allowance rather than be judged
1033
+ * field by field, and two records should never be able to spend each other's.
1034
+ */
1035
+ export declare type ValueEncoder = {
1036
+ /** Ordinary app data, redacted according to the policy. */
1037
+ readonly value: (value: unknown) => unknown;
1038
+ /**
1039
+ * A failure, as a chain of causes.
1040
+ *
1041
+ * Separate from {@link value} because the runtime already knows which is
1042
+ * which, and sniffing would get it wrong: a failure that is not an `Error`
1043
+ * instance — an Effect `Cause`, a node status — reaches the value encoder as
1044
+ * an anonymous bag of keys.
1045
+ */
1046
+ readonly failure: (value: unknown) => unknown;
1047
+ };
1048
+
1049
+ /**
1050
+ * How much of a value crosses the wire.
1051
+ *
1052
+ * Negotiated in one direction only: the hub asks, and the app answers with the
1053
+ * lesser of the request and its own ceiling. The ceiling defaults to `"shape"`,
1054
+ * so an app sends structure until someone deliberately decides otherwise — the
1055
+ * decision to put real values on a socket should be one somebody made, not one
1056
+ * that came with the default.
1057
+ */
1058
+ export declare const ValuePolicy: Schema.Literals<readonly ["none", "shape", "full"]>;
1059
+
1060
+ export declare type ValuePolicy = typeof ValuePolicy.Type;
1061
+
1062
+ export { }