@muse-code/sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +270 -0
  3. package/dist/src/connection/connection.d.ts +128 -0
  4. package/dist/src/connection/connection.js +548 -0
  5. package/dist/src/connection/spawn.d.ts +161 -0
  6. package/dist/src/connection/spawn.js +462 -0
  7. package/dist/src/errors.d.ts +54 -0
  8. package/dist/src/errors.js +51 -0
  9. package/dist/src/facade/approval.d.ts +76 -0
  10. package/dist/src/facade/approval.js +165 -0
  11. package/dist/src/facade/client.d.ts +153 -0
  12. package/dist/src/facade/client.js +300 -0
  13. package/dist/src/facade/discarded.d.ts +36 -0
  14. package/dist/src/facade/discarded.js +36 -0
  15. package/dist/src/facade/gap-fill.d.ts +80 -0
  16. package/dist/src/facade/gap-fill.js +375 -0
  17. package/dist/src/facade/host-death.d.ts +139 -0
  18. package/dist/src/facade/host-death.js +96 -0
  19. package/dist/src/facade/session.d.ts +309 -0
  20. package/dist/src/facade/session.js +639 -0
  21. package/dist/src/facade/turn-handle.d.ts +156 -0
  22. package/dist/src/facade/turn-handle.js +271 -0
  23. package/dist/src/facade/turn-submit.d.ts +72 -0
  24. package/dist/src/facade/turn-submit.js +168 -0
  25. package/dist/src/fingerprint.d.ts +37 -0
  26. package/dist/src/fingerprint.js +54 -0
  27. package/dist/src/fold/item-store.d.ts +110 -0
  28. package/dist/src/fold/item-store.js +169 -0
  29. package/dist/src/fold/session-fold.d.ts +455 -0
  30. package/dist/src/fold/session-fold.js +399 -0
  31. package/dist/src/fold/state-store.d.ts +68 -0
  32. package/dist/src/fold/state-store.js +89 -0
  33. package/dist/src/index.d.ts +56 -0
  34. package/dist/src/index.js +52 -0
  35. package/dist/src/pending/pending-command-set.d.ts +361 -0
  36. package/dist/src/pending/pending-command-set.js +468 -0
  37. package/package.json +39 -0
@@ -0,0 +1,455 @@
1
+ /**
2
+ * `SessionFold` — the SS4 client fold, bound to the generated wire types
3
+ * (spec 14990 FR-007, tasks.md T019).
4
+ *
5
+ * `ItemStore` and `SessionStateStore` are generic because they were written
6
+ * before the session-view plane entered the generated declarations. This
7
+ * module is where the generic parameters are BOUND: items are `@muse-code/msp`'s
8
+ * `Item`, state-family values are the generated `session/*` params objects,
9
+ * and every event this fold accepts is typed as the params object the wire
10
+ * actually carries. Nothing here restates a wire shape (INV-001).
11
+ *
12
+ * Beyond the two-store composition, the fold owns the parts of the view that
13
+ * are neither an item nor a state family:
14
+ *
15
+ * - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
16
+ * `turn/unqueued`, and the non-terminal `turn/retryScheduled`;
17
+ * - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
18
+ * sets and their first durable terminal. The decision flow (choosing and
19
+ * sending a resolution) is the facade's, not the fold's;
20
+ * - the DELIVERY marker `view/gap` — it seeds no store, it moves the fold's
21
+ * CURRENCY (`pendingGap`/`current`, FM-003). The recovery that fills the
22
+ * hole needs client→server I/O and is therefore the facade's (T032).
23
+ *
24
+ * INV-006 governs all of it: the fold never invents a terminal. A retract and
25
+ * a reclaim are not `TurnTerminal` values and are never rendered as one, an
26
+ * unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
27
+ * displaces the first durable one.
28
+ */
29
+ import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "@muse-code/msp";
30
+ import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
31
+ import type { StateApplyOutcome, StateValue } from "./state-store.js";
32
+ /** The session-state families, each keyed in the store by its method name. */
33
+ export type SessionStateParams = SessionApprovalModeChangedParams | SessionBranchChangedParams | SessionContextUsageParams | SessionGoalChangedParams | SessionModelChangedParams | SessionTodoListChangedParams | SessionTokenUsageParams;
34
+ /** A view notification, paired with the generated params object it carries. */
35
+ export type ViewEvent = {
36
+ readonly method: "item/started";
37
+ readonly params: ItemStartedParams;
38
+ } | {
39
+ readonly method: "item/updated";
40
+ readonly params: ItemUpdatedParams;
41
+ } | {
42
+ readonly method: "item/completed";
43
+ readonly params: ItemCompletedParams;
44
+ } | {
45
+ readonly method: "item/delta";
46
+ readonly params: ItemDeltaParams;
47
+ } | {
48
+ readonly method: "turn/started";
49
+ readonly params: TurnStartedParams;
50
+ } | {
51
+ readonly method: "turn/completed";
52
+ readonly params: TurnCompletedParams;
53
+ } | {
54
+ readonly method: "turn/retracted";
55
+ readonly params: TurnRetractedParams;
56
+ } | {
57
+ readonly method: "turn/retryScheduled";
58
+ readonly params: TurnRetryScheduledParams;
59
+ } | {
60
+ readonly method: "turn/unqueued";
61
+ readonly params: TurnUnqueuedParams;
62
+ } | {
63
+ readonly method: "approval/requested";
64
+ readonly params: ApprovalRequestParams;
65
+ } | {
66
+ readonly method: "approval/updated";
67
+ readonly params: ApprovalUpdatedParams;
68
+ } | {
69
+ readonly method: "approval/resolved";
70
+ readonly params: ApprovalResolvedParams;
71
+ } | {
72
+ readonly method: "userInput/requested";
73
+ readonly params: UserInputRequestParams;
74
+ } | {
75
+ readonly method: "userInput/settled";
76
+ readonly params: UserInputSettledParams;
77
+ } | {
78
+ readonly method: "session/modelChanged";
79
+ readonly params: SessionModelChangedParams;
80
+ } | {
81
+ readonly method: "session/goalChanged";
82
+ readonly params: SessionGoalChangedParams;
83
+ } | {
84
+ readonly method: "session/todoListChanged";
85
+ readonly params: SessionTodoListChangedParams;
86
+ } | {
87
+ readonly method: "session/branchChanged";
88
+ readonly params: SessionBranchChangedParams;
89
+ } | {
90
+ readonly method: "session/tokenUsage";
91
+ readonly params: SessionTokenUsageParams;
92
+ } | {
93
+ readonly method: "session/contextUsage";
94
+ readonly params: SessionContextUsageParams;
95
+ } | {
96
+ readonly method: "session/approvalModeChanged";
97
+ readonly params: SessionApprovalModeChangedParams;
98
+ }
99
+ /**
100
+ * The delivery-plane marker (tdd SS4.8). A `ViewEvent` since spec 14990
101
+ * T032, and the ONE arm that changes no session state: it names a hole in
102
+ * DELIVERY rather than a change in the view, so what it moves is the fold's
103
+ * CURRENCY — see `pendingGap` below.
104
+ *
105
+ * D-24021-1 excluded it deliberately and left the flip to this lane
106
+ * ("that lane owns removing the exclusion"). The flip is recorded in
107
+ * `specs/14990-muse-sdk/decisions/23980-fold-the-view-gap-marker.md`. What
108
+ * changed is not the structural fact D-24021-1 named — the marker still
109
+ * carries no `viewCursor` and no `sourceRange`, and still seeds nothing into
110
+ * either store — but the SDK's answer to it: a frame this package fully
111
+ * recognizes may not be reported as `ignoredUnrecognizedMethod`, because
112
+ * that is the report reserved for a NEWER host's method this SDK has never
113
+ * heard of (SS1.5.4), and a consumer told that cannot tell a tolerated
114
+ * unknown from an unfilled hole.
115
+ */
116
+ | {
117
+ readonly method: "view/gap";
118
+ readonly params: ViewGapParams;
119
+ };
120
+ /**
121
+ * Compile-time coverage: every `MspNotification` except the handshake's
122
+ * `initialized` is a fold input. A #206 enrollment that adds a view
123
+ * notification fails HERE rather than being silently ignored at runtime.
124
+ *
125
+ * `initialized` is the sole remaining exclusion, and it is a HANDSHAKE
126
+ * notification rather than a view one — it is answered by `MspHandshake`
127
+ * before this fold exists. The `view/gap` exclusion D-24021-1 recorded was
128
+ * removed by spec 14990 T032 when the marker became the `ViewEvent` arm above.
129
+ */
130
+ type AssertNever<T extends never> = T;
131
+ type UnfoldedViewNotification = Exclude<MspNotification, "initialized" | ViewEvent["method"]>;
132
+ export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
133
+ /**
134
+ * The reverse direction: every `ViewEvent` arm names a REAL generated
135
+ * notification. `Exclude` silently ignores excluder members outside the
136
+ * union, so without this a typo'd or later-retired arm would compile clean
137
+ * as dead code (PR #23087 review round).
138
+ */
139
+ type StaleViewArm = Exclude<ViewEvent["method"], MspNotification>;
140
+ export type NoStaleViewArm = AssertNever<StaleViewArm>;
141
+ /**
142
+ * The same reverse pin for the hand-typed exclusion literal above:
143
+ * `Exclude` silently ignores excluder members outside the union, so a
144
+ * retired or renamed `initialized` would otherwise compile clean as dead
145
+ * vocabulary (the PR #23087 rule, applied to this file's only other
146
+ * hand-typed method set).
147
+ */
148
+ type StaleExclusion = Exclude<"initialized", MspNotification>;
149
+ export type NoStaleExclusion = AssertNever<StaleExclusion>;
150
+ /**
151
+ * A recursively read-only view of a value.
152
+ *
153
+ * The fold's snapshot getters hand back its OWN stored objects — copying
154
+ * every read would cost more than the fold saves — and the generated wire
155
+ * types carry no `readonly`, so without this a consumer could write through
156
+ * a snapshot into fold state. This is composition over the generated types,
157
+ * never a restatement of one (INV-001).
158
+ *
159
+ * `readonly` is compile-time only; this is a type-level seal against
160
+ * accidental writes, not a runtime freeze. The alternative — deep-freezing
161
+ * or cloning on every read — would be a real cost on the hot path for a
162
+ * hazard the compiler can price at zero (PR #23087 review round).
163
+ */
164
+ export type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends ReadonlyArray<infer U> ? readonly DeepReadonly<U>[] : T extends object ? {
165
+ readonly [K in keyof T]: DeepReadonly<T[K]>;
166
+ } : T;
167
+ /** The session-state family keys: the `session/*` half of `ViewEvent`. */
168
+ export type SessionStateMethod = ViewEvent["method"] & `session/${string}`;
169
+ /**
170
+ * The methods whose arms can drop a frame as stale. Narrow rather than the
171
+ * whole `ViewEvent["method"]`: a consumer switching on a stale drop would
172
+ * otherwise have to "handle" cases like `item/delta` that no arm produces,
173
+ * and could never match exhaustively. A future arm that starts dropping
174
+ * widens this deliberately (PR #23087 review round).
175
+ */
176
+ export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/retryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested";
177
+ /**
178
+ * The `NoStaleViewArm` sibling for the union above: these are hand-typed
179
+ * literals, so without this pin a typo'd or later-retired member compiles
180
+ * clean and a consumer told to match `ignoredStaleFrame` exhaustively has to
181
+ * "handle" a case no arm can produce (PR #23087 review round).
182
+ */
183
+ type StrayStaleDroppable = Exclude<StaleDroppableMethod, ViewEvent["method"]>;
184
+ export type EveryStaleDroppableIsWireVocabulary = AssertNever<StrayStaleDroppable>;
185
+ /** Where a turn stands. Client fold state — not a wire vocabulary. */
186
+ export type TurnState = "running" | "settled" | "retracted" | "unqueued";
187
+ /** A turn as the fold has observed it. */
188
+ export interface TurnEntry {
189
+ readonly turnId: string;
190
+ /** The submitting command, when an event carried it. */
191
+ readonly commandId?: string;
192
+ readonly state: TurnState;
193
+ /** The server's terminal, verbatim. Absent unless `turn/completed` folded. */
194
+ readonly terminal?: TurnTerminal;
195
+ /** Present iff the terminal was `"failed"` (tdd SS4.5.1). */
196
+ readonly error?: TurnError;
197
+ /** The latest scheduled model retry; non-terminal (tdd SS4.5.1, D-026). */
198
+ readonly retryScheduled?: TurnRetryScheduledParams;
199
+ }
200
+ /** An approval awaiting its first durable terminal. */
201
+ export interface PendingApproval {
202
+ readonly approvalId: string;
203
+ readonly requested: ApprovalRequestParams;
204
+ /** The most recent `approval/updated` refresh, if any. */
205
+ readonly latestUpdate?: ApprovalUpdatedParams;
206
+ }
207
+ /** What one `apply` did — enough to drive a render without re-diffing. */
208
+ export type FoldOutcome = {
209
+ readonly kind: "item";
210
+ readonly outcome: ItemApplyOutcome;
211
+ } | {
212
+ readonly kind: "itemDelta";
213
+ readonly outcome: DeltaApplyOutcome;
214
+ } | {
215
+ readonly kind: "turn";
216
+ readonly turnId: string;
217
+ readonly state: TurnState;
218
+ } | {
219
+ readonly kind: "sessionState";
220
+ readonly outcome: StateApplyOutcome<SessionStateParams>;
221
+ } | {
222
+ readonly kind: "approvalPending";
223
+ readonly approvalId: string;
224
+ } | {
225
+ readonly kind: "approvalResolved";
226
+ readonly approvalId: string;
227
+ /** False when a durable terminal had already landed; the first wins. */
228
+ readonly firstTerminal: boolean;
229
+ } | {
230
+ readonly kind: "userInputPending";
231
+ readonly userInputId: string;
232
+ } | {
233
+ readonly kind: "userInputSettled";
234
+ readonly userInputId: string;
235
+ readonly firstSettlement: boolean;
236
+ } | {
237
+ /**
238
+ * A `view/gap` folded: push delivery dropped everything in the open
239
+ * interval `(after, next)`, so this fold is no longer current until a
240
+ * sanctioned recovery fills it (tdd SS4.8, FM-003).
241
+ *
242
+ * The bounds are the FRAME's own, verbatim — the coalesced outstanding
243
+ * hole is `pendingGap`, which is what a recovery walks. Reported rather
244
+ * than dropped because the SDK recognizes this frame completely: an
245
+ * `ignoredUnrecognizedMethod` here would be indistinguishable from a
246
+ * newer host's genuinely unknown method (SS1.5.4).
247
+ */
248
+ readonly kind: "deliveryGap";
249
+ readonly after: string;
250
+ readonly next: string;
251
+ } | {
252
+ readonly kind: "ignoredUnrecognizedMethod";
253
+ readonly method: string;
254
+ } | {
255
+ /**
256
+ * A frame that carried no `params`. The generated `Notification`
257
+ * declares `params` optional ("omitted entirely when empty"), so the
258
+ * wire can legally deliver one — but no `ViewEvent` arm is foldable
259
+ * without its params object, every one of them reads at least a
260
+ * `sessionId`. Dropped rather than thrown: SS1.5.4's posture is that a
261
+ * frame this SDK cannot fold leaves the rest of the fold intact, and
262
+ * throwing here would kill the consumer's notification pump
263
+ * (PR #23087 review round).
264
+ */
265
+ readonly kind: "ignoredMissingParams";
266
+ readonly method: string;
267
+ } | {
268
+ /**
269
+ * A recognized frame the fold deliberately dropped, leaving state
270
+ * unchanged: a `turn/started` or `turn/completed` for a turn that
271
+ * already left `running`, an `approval/updated` for an approval it
272
+ * never saw requested (or whose entry a resolution already deleted),
273
+ * or a redelivered `approval/requested` / `userInput/requested` for an
274
+ * approval/prompt that already has its durable terminal. Truthful by
275
+ * contract: a "pending" kind here would make a renderer show an entry
276
+ * the fold does not hold (PR #23087 review round).
277
+ *
278
+ * SCOPE. "Dropped" means only that THIS fold's state is unchanged; it
279
+ * does not mean the frame carried nothing. The one known post-terminal
280
+ * frame that carries a first-delivery fact — an `approval/updated`
281
+ * whose `policyPersistence` reports a FAILED `localPersistent` store
282
+ * write, which the server sends AFTER `approval/resolved` (tdd
283
+ * SS5.5/SS6.8) — is dropped here with no accessor holding the reason.
284
+ * Surfacing it is deferred to the facade slice: issue #23379.
285
+ */
286
+ readonly kind: "ignoredStaleFrame";
287
+ readonly method: StaleDroppableMethod;
288
+ readonly id: string;
289
+ };
290
+ /**
291
+ * The fold's read-only view of its `ItemStore`. Every mutation goes through
292
+ * `apply()`; a directly reachable `seed`/`applyDelta` would let a consumer
293
+ * desync the composite view (items cleared, turn/pending maps not), breaking
294
+ * INV-002 replay equality (PR #23087 review round).
295
+ *
296
+ * An ALLOWLIST, stated explicitly: TypeScript never checks `Omit`'s keys
297
+ * against the type, so a renamed or newly added `ItemStore` mutator would
298
+ * land on this exported surface silently. An explicit member list admits
299
+ * only what is written here, in both drift directions.
300
+ *
301
+ * Hiding the mutator METHODS is only half the job. The values these
302
+ * accessors return ARE the fold's stored objects and the generated wire
303
+ * types carry no `readonly`, so `fold.items.get(id).revision = 0` used to
304
+ * typecheck AND stick — defeating the INV-003 revision guard and breaking
305
+ * INV-002 replay equality through the read surface the mutator allowlist
306
+ * was supposed to seal. Every accessor therefore returns `DeepReadonly`
307
+ * (PR #23087 review round).
308
+ */
309
+ export interface FoldItems {
310
+ accumulated(itemId: string, field?: string): string | undefined;
311
+ accumulatedFields(itemId: string): readonly string[];
312
+ readonly ephemeralSessionDiscarded: boolean;
313
+ get(itemId: string): DeepReadonly<Item> | undefined;
314
+ has(itemId: string): boolean;
315
+ isTerminalUnknown(itemId: string): boolean;
316
+ lastOpenedItemId(): string | undefined;
317
+ list(): readonly DeepReadonly<Item>[];
318
+ readonly size: number;
319
+ }
320
+ /**
321
+ * The fold's read-only view of its `SessionStateStore`, stated explicitly
322
+ * rather than derived: the store's `get`/`has` take a bare `string`, so
323
+ * `get("session/modelchanged")` would typecheck and silently read
324
+ * `undefined`. The family key IS protocol vocabulary, so name it — this
325
+ * surface goes public in this PR, and narrowing it later is a break.
326
+ */
327
+ export interface FoldSessionState {
328
+ /**
329
+ * GENERIC in the family, so the return type is that family's params
330
+ * object rather than the 7-way union. With the union, a wrong-family cast
331
+ * (`get("session/goalChanged") as SessionTokenUsageParams`) was a legal
332
+ * narrowing and read the wrong shape silently — the same invisible-miss
333
+ * class the key narrowing closed on the argument side. The method→params
334
+ * map already exists in `ViewEvent`; this just reuses it.
335
+ */
336
+ get<M extends SessionStateMethod>(family: M): DeepReadonly<StateValue<Extract<ViewEvent, {
337
+ method: M;
338
+ }>["params"]>> | undefined;
339
+ has(family: SessionStateMethod): boolean;
340
+ /**
341
+ * Every family that holds a value, in insertion order. Narrowed in the
342
+ * RETURN position too, so the obvious consumer loop —
343
+ * `for (const f of families()) get(f)` — round-trips against this same
344
+ * interface instead of forcing the bare-string cast the parameter
345
+ * narrowing exists to forbid.
346
+ */
347
+ families(): readonly SessionStateMethod[];
348
+ }
349
+ /**
350
+ * The whole client-side session view: items, session state, turns, and the
351
+ * pending approval/user-input sets.
352
+ */
353
+ export declare class SessionFold {
354
+ #private;
355
+ /** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
356
+ get items(): FoldItems;
357
+ /**
358
+ * Discharge the SS2.13.3b ephemeral host-death obligation over the item
359
+ * half: every item still in progress becomes terminal-unknown and the fold
360
+ * refuses further events (spec FM-002; slice 3's T030b).
361
+ *
362
+ * A FOLD-level method rather than a `FoldItems` entry on purpose. `items` is
363
+ * snapshot-only — an allowlist whose whole job is that a store mutator can
364
+ * never leak onto the consumer surface (PR #23087 review round) — and this
365
+ * IS a mutator. Widening the allowlist to reach it would undo that; routing
366
+ * it here keeps exactly one caller (`Session.hostExited`) and leaves the
367
+ * read surface untouched. The in-progress probe stays the caller's, so the
368
+ * store remains wire-shape-blind (INV-001).
369
+ */
370
+ markEphemeralHostDeath(isInProgress: (item: Item) => boolean): readonly TerminalUnknownItemAnnotation[];
371
+ /**
372
+ * The session-state families, keyed by notification method name. Named
373
+ * `sessionState` rather than `state` because the surface contract reserves
374
+ * `state` for the FR-008 aggregate that arrives with snapshot ingestion.
375
+ * Snapshot-only, like `items`.
376
+ */
377
+ get sessionState(): FoldSessionState;
378
+ /** The turn currently running, if one is. */
379
+ get activeTurnId(): string | undefined;
380
+ /**
381
+ * The outstanding delivery hole, or `undefined` when there is none (tdd
382
+ * SS4.8, FM-003).
383
+ *
384
+ * COALESCED, keeping the FIRST `after`: consecutive overflows are one hole
385
+ * from a filler's point of view, which is the client mirror of the server's
386
+ * own D-16487-1 bracket rule. A recovery walks `(after, next)` and calls
387
+ * `gapFilled(next)` with the target it actually reached, so a hole that grew
388
+ * while the walk was in flight cannot be reported filled.
389
+ */
390
+ get pendingGap(): DeepReadonly<ViewGapParams> | undefined;
391
+ /**
392
+ * Is this fold current with the session view?
393
+ *
394
+ * FM-003's "only then reports current": false from the moment a `view/gap`
395
+ * folds until its hole is filled. Live events keep folding meanwhile — they
396
+ * are real facts and dropping them would add a second hole — so this flag is
397
+ * the ONLY statement that the transcript has a hole in it.
398
+ */
399
+ get current(): boolean;
400
+ /**
401
+ * A recovery filled the hole up to `next`. Returns whether it cleared.
402
+ *
403
+ * EQUALITY, never a relational compare (tdd SS4.1): the argument is the
404
+ * target the walk reached, and it clears only when that is still the
405
+ * outstanding target. A gap that arrived mid-walk left a newer `next`, so
406
+ * this answers `false` and the fold stays not-current — the truthful answer,
407
+ * since the second hole is unfilled.
408
+ *
409
+ * A fold-level mutator with the same rationale as `markEphemeralHostDeath`:
410
+ * `items`/`sessionState` are snapshot-only allowlists, and this belongs to
411
+ * neither store.
412
+ */
413
+ gapFilled(next: string): boolean;
414
+ /**
415
+ * Fold one view event.
416
+ *
417
+ * The `default` arm is not defensive padding: the wire is an external
418
+ * boundary and SS1.5.4 makes a NEW notification additive evolution, so a
419
+ * host newer than this SDK really does reach it. Ignoring the frame keeps
420
+ * the rest of the fold intact, which is what tolerance means. The second
421
+ * overload is how such a frame gets in: the wire's actual shape is
422
+ * `{ method: string, params }`, and the ONE tolerance cast lives here
423
+ * rather than at every call site — a hand-written literal for a KNOWN
424
+ * method should use the `ViewEvent` overload and keep its typo checking
425
+ * (PR #23087 review round).
426
+ *
427
+ * `params` is OPTIONAL on the wide overload because the generated
428
+ * `Notification` — the exact type this package's own `NotificationHandler`
429
+ * hands consumers — declares it optional. Requiring it here would make
430
+ * `fold.apply(notification)` a TS2769 and force every wiring site to
431
+ * re-wrap the frame, which is the ceremony this overload exists to remove.
432
+ */
433
+ apply(event: ViewEvent): FoldOutcome;
434
+ apply(event: {
435
+ readonly method: string;
436
+ readonly params?: unknown;
437
+ }): FoldOutcome;
438
+ /** Turns in first-observed order. */
439
+ turns(): readonly DeepReadonly<TurnEntry>[];
440
+ turn(turnId: string): DeepReadonly<TurnEntry> | undefined;
441
+ /** Approvals awaiting a durable terminal, in first-observed order. */
442
+ pendingApprovals(): readonly DeepReadonly<PendingApproval>[];
443
+ /** The winning durable terminal per approval, in first-observed order. */
444
+ resolvedApprovals(): readonly DeepReadonly<ApprovalResolvedParams>[];
445
+ /**
446
+ * Prompts awaiting a durable settlement, in first-observed order. The
447
+ * entries ARE the generated request params — the wire shape already carries
448
+ * `userInputId`, so a wrapper would only duplicate it (unlike
449
+ * `PendingApproval`, which earns its wrapper with `latestUpdate`).
450
+ */
451
+ pendingUserInputs(): readonly DeepReadonly<UserInputRequestParams>[];
452
+ /** The winning durable settlement per prompt, in first-observed order. */
453
+ settledUserInputs(): readonly DeepReadonly<UserInputSettledParams>[];
454
+ }
455
+ export {};