@muse-code/sdk 1.4.15 → 1.4.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +78 -2
- package/dist/src/connection/connection.d.ts +83 -6
- package/dist/src/connection/connection.js +113 -14
- package/dist/src/connection/spawn.d.ts +50 -4
- package/dist/src/connection/spawn.js +161 -33
- package/dist/src/connection/surface.d.ts +49 -0
- package/dist/src/connection/surface.js +8 -0
- package/dist/src/errors.d.ts +6 -5
- package/dist/src/errors.js +7 -6
- package/dist/src/facade/approval.js +1 -1
- package/dist/src/facade/client.d.ts +158 -17
- package/dist/src/facade/client.js +370 -74
- package/dist/src/facade/gap-fill.d.ts +2 -0
- package/dist/src/facade/gap-fill.js +11 -2
- package/dist/src/facade/host-death.d.ts +5 -1
- package/dist/src/facade/host-death.js +5 -1
- package/dist/src/facade/session.d.ts +133 -5
- package/dist/src/facade/session.js +419 -13
- package/dist/src/facade/turn-handle.d.ts +23 -0
- package/dist/src/facade/turn-handle.js +1 -1
- package/dist/src/fingerprint.d.ts +79 -4
- package/dist/src/fingerprint.js +110 -11
- package/dist/src/fingerprint.stamped.d.ts +2 -1
- package/dist/src/fingerprint.stamped.js +2 -1
- package/dist/src/fold/extension.d.ts +39 -0
- package/dist/src/fold/extension.js +49 -0
- package/dist/src/fold/session-fold.d.ts +11 -0
- package/dist/src/fold/session-fold.js +13 -0
- package/dist/src/index.d.ts +6 -5
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +319 -10
- package/package.json +1 -1
|
@@ -1,4 +1,17 @@
|
|
|
1
1
|
export declare const EXPECTED_SCHEMA_FINGERPRINT: string;
|
|
2
|
+
/**
|
|
3
|
+
* The compatibility epoch this SDK was built against (ADR 22936 D3): the
|
|
4
|
+
* stable bundle's declared count of non-additive advances of the stable
|
|
5
|
+
* surface, stamped by the same `prebuild` step from the same bundle bytes
|
|
6
|
+
* as the fingerprint (the bundle records it at its root, ADR 22936 D5).
|
|
7
|
+
* Never a committed literal, for the same reasons as the fingerprint.
|
|
8
|
+
*/
|
|
9
|
+
export declare const EXPECTED_SCHEMA_COMPATIBILITY_EPOCH: number;
|
|
10
|
+
/** What a host advertises in `InitializeResult.schema`: the epoch is absent on a host that predates it. */
|
|
11
|
+
export interface ServedSchemaIdentity {
|
|
12
|
+
readonly fingerprint: string;
|
|
13
|
+
readonly compatibilityEpoch?: number | undefined;
|
|
14
|
+
}
|
|
2
15
|
/**
|
|
3
16
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
4
17
|
*
|
|
@@ -9,15 +22,77 @@ export declare const EXPECTED_SCHEMA_FINGERPRINT: string;
|
|
|
9
22
|
* plainly.
|
|
10
23
|
*/
|
|
11
24
|
export declare function fingerprintMismatchMessage(pinned: string, actual: string): string;
|
|
12
|
-
/**
|
|
13
|
-
|
|
25
|
+
/**
|
|
26
|
+
* The runtime arm (tdd SS1.4.1, ADR 22936 D3): a surfaced mismatch with its
|
|
27
|
+
* tier. The additive tier is advisory only; the declared-breaking tier is a
|
|
28
|
+
* warning by default and a connect-time refusal behind
|
|
29
|
+
* `refuseDeclaredBreakingSchema`. The tier reads `additive` when the served
|
|
30
|
+
* epoch equals the pin or the host omits it (every difference is additive,
|
|
31
|
+
* SS1.5.4) and `declaredBreaking` when the epochs differ (a declared
|
|
32
|
+
* non-additive advance lies between). A union on `tier`: the
|
|
33
|
+
* declared-breaking member always knows the served epoch, so a caller that
|
|
34
|
+
* narrows on the tier needs no second check.
|
|
35
|
+
*/
|
|
36
|
+
interface FingerprintWarningBase {
|
|
14
37
|
readonly kind: "schemaFingerprintMismatch";
|
|
15
38
|
readonly pinned: string;
|
|
16
39
|
readonly served: string;
|
|
40
|
+
readonly pinnedEpoch: number;
|
|
17
41
|
readonly message: string;
|
|
18
42
|
}
|
|
43
|
+
/** The additive tier: an equal or absent served epoch; today's warning. */
|
|
44
|
+
export interface AdditiveFingerprintWarning extends FingerprintWarningBase {
|
|
45
|
+
readonly tier: "additive";
|
|
46
|
+
/** `undefined` when the host omits the member: unknown, never a substituted value. */
|
|
47
|
+
readonly servedEpoch: number | undefined;
|
|
48
|
+
}
|
|
49
|
+
/** The declared-breaking tier: a served epoch that differs from the pin. */
|
|
50
|
+
export interface DeclaredBreakingFingerprintWarning extends FingerprintWarningBase {
|
|
51
|
+
readonly tier: "declaredBreaking";
|
|
52
|
+
readonly servedEpoch: number;
|
|
53
|
+
}
|
|
54
|
+
export type FingerprintWarning = AdditiveFingerprintWarning | DeclaredBreakingFingerprintWarning;
|
|
55
|
+
/**
|
|
56
|
+
* FR-22936-8's one reading of a served `compatibilityEpoch`, shared by the
|
|
57
|
+
* handshake and the classifier so the two cannot drift apart: absent, or a
|
|
58
|
+
* non-negative integer. Package-internal: not exported from the root.
|
|
59
|
+
*/
|
|
60
|
+
export declare function isWellFormedEpoch(raw: unknown): raw is number | undefined;
|
|
61
|
+
/**
|
|
62
|
+
* Classify a host's advertised schema identity against the pin (ADR 22936
|
|
63
|
+
* D3). Equal fingerprints: no check at all, whatever the epochs. A served
|
|
64
|
+
* epoch that is not a non-negative integer reads as absent (FR-22936-8), so
|
|
65
|
+
* this call on `initializeResult.schema` reports the tier the handshake
|
|
66
|
+
* reported. Returns `undefined` when there is nothing to say — a mismatch is
|
|
67
|
+
* surfaced, not thrown; the refusal is the connection's decision, not this
|
|
68
|
+
* function's.
|
|
69
|
+
*/
|
|
70
|
+
export declare function classifyServedSchema(served: ServedSchemaIdentity): FingerprintWarning | undefined;
|
|
19
71
|
/**
|
|
20
|
-
* Compare a host's advertised fingerprint against the pin
|
|
21
|
-
*
|
|
72
|
+
* Compare a host's advertised fingerprint against the pin, with no epoch:
|
|
73
|
+
* the pre-#22936 reading, kept for callers that have only the fingerprint.
|
|
74
|
+
* `pinned` overrides the fingerprint only: the pin's epoch is always this
|
|
75
|
+
* build's `EXPECTED_SCHEMA_COMPATIBILITY_EPOCH`, so the warning's
|
|
76
|
+
* `pinnedEpoch` names this build whatever `pinned` names. Returns
|
|
77
|
+
* `undefined` when they agree — a mismatch is surfaced, not thrown.
|
|
22
78
|
*/
|
|
23
79
|
export declare function checkServedFingerprint(served: string, pinned?: string): FingerprintWarning | undefined;
|
|
80
|
+
/**
|
|
81
|
+
* The connect-time refusal of the declared-breaking tier (ADR 22936 D3):
|
|
82
|
+
* one error naming the served fingerprint and epoch as the bundle to rebuild
|
|
83
|
+
* against, and the SDK's own pin. Thrown only when the caller opted in with
|
|
84
|
+
* `refuseDeclaredBreakingSchema`; the SDK has already closed the host it
|
|
85
|
+
* spawned when this reaches the caller, so a refusal orphans nothing. Its
|
|
86
|
+
* fields are the warning's flat fields (`served`, `servedEpoch`, `pinned`,
|
|
87
|
+
* `pinnedEpoch`), so code that handles both sees one shape.
|
|
88
|
+
*/
|
|
89
|
+
export declare class SchemaCompatibilityError extends Error {
|
|
90
|
+
readonly kind: "schemaCompatibilityRefused";
|
|
91
|
+
readonly tier: "declaredBreaking";
|
|
92
|
+
readonly served: string;
|
|
93
|
+
readonly servedEpoch: number;
|
|
94
|
+
readonly pinned: string;
|
|
95
|
+
readonly pinnedEpoch: number;
|
|
96
|
+
constructor(warning: DeclaredBreakingFingerprintWarning);
|
|
97
|
+
}
|
|
98
|
+
export {};
|
package/dist/src/fingerprint.js
CHANGED
|
@@ -21,8 +21,25 @@
|
|
|
21
21
|
* error (tdd SS1.4.1) — additive-optional evolution means an older SDK
|
|
22
22
|
* keeps working against a newer host.
|
|
23
23
|
*/
|
|
24
|
-
import { STAMPED_SCHEMA_FINGERPRINT } from "./fingerprint.stamped.js";
|
|
24
|
+
import { STAMPED_SCHEMA_COMPATIBILITY_EPOCH, STAMPED_SCHEMA_FINGERPRINT, } from "./fingerprint.stamped.js";
|
|
25
25
|
export const EXPECTED_SCHEMA_FINGERPRINT = STAMPED_SCHEMA_FINGERPRINT;
|
|
26
|
+
/**
|
|
27
|
+
* The compatibility epoch this SDK was built against (ADR 22936 D3): the
|
|
28
|
+
* stable bundle's declared count of non-additive advances of the stable
|
|
29
|
+
* surface, stamped by the same `prebuild` step from the same bundle bytes
|
|
30
|
+
* as the fingerprint (the bundle records it at its root, ADR 22936 D5).
|
|
31
|
+
* Never a committed literal, for the same reasons as the fingerprint.
|
|
32
|
+
*/
|
|
33
|
+
export const EXPECTED_SCHEMA_COMPATIBILITY_EPOCH = STAMPED_SCHEMA_COMPATIBILITY_EPOCH;
|
|
34
|
+
/**
|
|
35
|
+
* The default pin of `classifyServedSchema`: module-private, because the two
|
|
36
|
+
* members are already the package's public pins and a third root export
|
|
37
|
+
* would bind the sibling SDKs to mirror it.
|
|
38
|
+
*/
|
|
39
|
+
const EXPECTED_SCHEMA_IDENTITY = {
|
|
40
|
+
fingerprint: EXPECTED_SCHEMA_FINGERPRINT,
|
|
41
|
+
compatibilityEpoch: EXPECTED_SCHEMA_COMPATIBILITY_EPOCH,
|
|
42
|
+
};
|
|
26
43
|
/**
|
|
27
44
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
28
45
|
*
|
|
@@ -47,18 +64,100 @@ export function fingerprintMismatchMessage(pinned, actual) {
|
|
|
47
64
|
].join("\n");
|
|
48
65
|
}
|
|
49
66
|
/**
|
|
50
|
-
*
|
|
51
|
-
*
|
|
67
|
+
* FR-22936-8's one reading of a served `compatibilityEpoch`, shared by the
|
|
68
|
+
* handshake and the classifier so the two cannot drift apart: absent, or a
|
|
69
|
+
* non-negative integer. Package-internal: not exported from the root.
|
|
52
70
|
*/
|
|
53
|
-
export function
|
|
54
|
-
|
|
71
|
+
export function isWellFormedEpoch(raw) {
|
|
72
|
+
return raw === undefined || (typeof raw === "number" && Number.isInteger(raw) && raw >= 0);
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Classify a host's advertised schema identity against the pin (ADR 22936
|
|
76
|
+
* D3). Equal fingerprints: no check at all, whatever the epochs. A served
|
|
77
|
+
* epoch that is not a non-negative integer reads as absent (FR-22936-8), so
|
|
78
|
+
* this call on `initializeResult.schema` reports the tier the handshake
|
|
79
|
+
* reported. Returns `undefined` when there is nothing to say — a mismatch is
|
|
80
|
+
* surfaced, not thrown; the refusal is the connection's decision, not this
|
|
81
|
+
* function's.
|
|
82
|
+
*/
|
|
83
|
+
export function classifyServedSchema(served) {
|
|
84
|
+
return classify(served, EXPECTED_SCHEMA_IDENTITY);
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* The classifier's body, with the pin as an argument. Module-private: the
|
|
88
|
+
* pin is the SDK's own (FR-22936-6), never a public parameter; the one
|
|
89
|
+
* other caller is `checkServedFingerprint`.
|
|
90
|
+
*/
|
|
91
|
+
function classify(served, pinned) {
|
|
92
|
+
if (served.fingerprint === pinned.fingerprint)
|
|
55
93
|
return undefined;
|
|
56
|
-
|
|
94
|
+
// A present member that is not a non-negative integer is read as absent
|
|
95
|
+
// (FR-22936-8), here as in the handshake, and nothing is substituted for
|
|
96
|
+
// the value; the handshake alone decides whether to refuse it.
|
|
97
|
+
const raw = served.compatibilityEpoch;
|
|
98
|
+
const servedEpoch = isWellFormedEpoch(raw) ? raw : undefined;
|
|
99
|
+
const base = {
|
|
57
100
|
kind: "schemaFingerprintMismatch",
|
|
58
|
-
pinned,
|
|
59
|
-
served,
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
101
|
+
pinned: pinned.fingerprint,
|
|
102
|
+
served: served.fingerprint,
|
|
103
|
+
pinnedEpoch: pinned.compatibilityEpoch,
|
|
104
|
+
};
|
|
105
|
+
if (servedEpoch === undefined || servedEpoch === pinned.compatibilityEpoch) {
|
|
106
|
+
return {
|
|
107
|
+
...base,
|
|
108
|
+
tier: "additive",
|
|
109
|
+
servedEpoch,
|
|
110
|
+
message: `host schema fingerprint ${served.fingerprint} differs from the fingerprint this ` +
|
|
111
|
+
`SDK was built against (${pinned.fingerprint}); proceeding under additive-optional ` +
|
|
112
|
+
`evolution (SS1.5.4). Rebuild after a schema advance.`,
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
return {
|
|
116
|
+
...base,
|
|
117
|
+
tier: "declaredBreaking",
|
|
118
|
+
servedEpoch,
|
|
119
|
+
message: `host schema fingerprint ${served.fingerprint} at compatibility epoch ${String(servedEpoch)} ` +
|
|
120
|
+
`differs from the fingerprint this SDK was built against (${pinned.fingerprint}, epoch ` +
|
|
121
|
+
`${String(pinned.compatibilityEpoch)}) across a declared non-additive advance (ADR 22936 D3). ` +
|
|
122
|
+
`Rebuild the SDK against the served bundle.`,
|
|
63
123
|
};
|
|
64
124
|
}
|
|
125
|
+
/**
|
|
126
|
+
* Compare a host's advertised fingerprint against the pin, with no epoch:
|
|
127
|
+
* the pre-#22936 reading, kept for callers that have only the fingerprint.
|
|
128
|
+
* `pinned` overrides the fingerprint only: the pin's epoch is always this
|
|
129
|
+
* build's `EXPECTED_SCHEMA_COMPATIBILITY_EPOCH`, so the warning's
|
|
130
|
+
* `pinnedEpoch` names this build whatever `pinned` names. Returns
|
|
131
|
+
* `undefined` when they agree — a mismatch is surfaced, not thrown.
|
|
132
|
+
*/
|
|
133
|
+
export function checkServedFingerprint(served, pinned = EXPECTED_SCHEMA_FINGERPRINT) {
|
|
134
|
+
return classify({ fingerprint: served }, { fingerprint: pinned, compatibilityEpoch: EXPECTED_SCHEMA_COMPATIBILITY_EPOCH });
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* The connect-time refusal of the declared-breaking tier (ADR 22936 D3):
|
|
138
|
+
* one error naming the served fingerprint and epoch as the bundle to rebuild
|
|
139
|
+
* against, and the SDK's own pin. Thrown only when the caller opted in with
|
|
140
|
+
* `refuseDeclaredBreakingSchema`; the SDK has already closed the host it
|
|
141
|
+
* spawned when this reaches the caller, so a refusal orphans nothing. Its
|
|
142
|
+
* fields are the warning's flat fields (`served`, `servedEpoch`, `pinned`,
|
|
143
|
+
* `pinnedEpoch`), so code that handles both sees one shape.
|
|
144
|
+
*/
|
|
145
|
+
export class SchemaCompatibilityError extends Error {
|
|
146
|
+
kind = "schemaCompatibilityRefused";
|
|
147
|
+
tier = "declaredBreaking";
|
|
148
|
+
served;
|
|
149
|
+
servedEpoch;
|
|
150
|
+
pinned;
|
|
151
|
+
pinnedEpoch;
|
|
152
|
+
constructor(warning) {
|
|
153
|
+
super(`refused at connect: the host serves stable schema ${warning.served} at compatibility ` +
|
|
154
|
+
`epoch ${String(warning.servedEpoch)}, a declared non-additive advance from the bundle this ` +
|
|
155
|
+
`SDK was built against (${warning.pinned}, epoch ${String(warning.pinnedEpoch)}). Rebuild the ` +
|
|
156
|
+
`SDK against the served bundle (ADR 22936 D3). The spawned host was closed.`);
|
|
157
|
+
this.name = "SchemaCompatibilityError";
|
|
158
|
+
this.served = warning.served;
|
|
159
|
+
this.servedEpoch = warning.servedEpoch;
|
|
160
|
+
this.pinned = warning.pinned;
|
|
161
|
+
this.pinnedEpoch = warning.pinnedEpoch;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
@@ -1 +1,2 @@
|
|
|
1
|
-
export declare const STAMPED_SCHEMA_FINGERPRINT = "sha256:
|
|
1
|
+
export declare const STAMPED_SCHEMA_FINGERPRINT = "sha256:b7fb9137267aa35c92424df37a5ac56287006a0e546b197bf0930d593fecbdb1";
|
|
2
|
+
export declare const STAMPED_SCHEMA_COMPATIBILITY_EPOCH = 0;
|
|
@@ -3,4 +3,5 @@
|
|
|
3
3
|
// schema/msp/stable/msp.schema.json through the port in
|
|
4
4
|
// scripts/msp-fingerprint.mjs. A schema advance moves this value at the
|
|
5
5
|
// next build; the file itself is gitignored and never committed.
|
|
6
|
-
export const STAMPED_SCHEMA_FINGERPRINT = "sha256:
|
|
6
|
+
export const STAMPED_SCHEMA_FINGERPRINT = "sha256:b7fb9137267aa35c92424df37a5ac56287006a0e546b197bf0930d593fecbdb1";
|
|
7
|
+
export const STAMPED_SCHEMA_COMPATIBILITY_EPOCH = 0;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one fold extension hook (FR-97527-3): a neutral, method-name-keyed
|
|
3
|
+
* registration consulted for BOTH connection-level state and the
|
|
4
|
+
* per-session fold.
|
|
5
|
+
*
|
|
6
|
+
* An extension runs INSIDE the single apply path — never a second pump —
|
|
7
|
+
* so gap buffering, twin-claiming and resume behave exactly as today. The
|
|
8
|
+
* hook names no experimental feature: it matches on the method string, and
|
|
9
|
+
* the extension keeps its own state in its own instance.
|
|
10
|
+
*
|
|
11
|
+
* A throw never escapes: both loops catch an extension's throw and report
|
|
12
|
+
* it to that extension's `onError` (the `ApprovalFailure` "reported, not
|
|
13
|
+
* thrown" rule — the call site is a notification pump with nothing to
|
|
14
|
+
* catch it). Without an `onError` the failure is swallowed, deliberately:
|
|
15
|
+
* one bad add-on must not drop every session. An `onError` that itself
|
|
16
|
+
* throws is swallowed too, for the same reason the approval observer's is.
|
|
17
|
+
*/
|
|
18
|
+
export interface FoldExtension {
|
|
19
|
+
/** The exact notification method this extension handles. */
|
|
20
|
+
readonly method: string;
|
|
21
|
+
/**
|
|
22
|
+
* Fold one frame's params. Called in registration order with the other
|
|
23
|
+
* extensions for the same method, before the fold's own arm for that
|
|
24
|
+
* method runs.
|
|
25
|
+
*/
|
|
26
|
+
apply(params: unknown): void;
|
|
27
|
+
/** Receives this extension's throws; absent means swallow. */
|
|
28
|
+
readonly onError?: (error: unknown) => void;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Run every extension registered for `method`, in registration order.
|
|
32
|
+
*
|
|
33
|
+
* The ONE call-and-report loop both planes share (fold + client `#route`),
|
|
34
|
+
* so guard and reporting changes land once. Objects only — a frame without
|
|
35
|
+
* usable params has nothing to fold. A throw is reported to that
|
|
36
|
+
* extension's `onError` (absent means swallow); an `onError` that itself
|
|
37
|
+
* throws is swallowed too. Returns how many extensions fired.
|
|
38
|
+
*/
|
|
39
|
+
export declare function fireExtensions(extensions: readonly FoldExtension[], method: string, params: unknown): number;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one fold extension hook (FR-97527-3): a neutral, method-name-keyed
|
|
3
|
+
* registration consulted for BOTH connection-level state and the
|
|
4
|
+
* per-session fold.
|
|
5
|
+
*
|
|
6
|
+
* An extension runs INSIDE the single apply path — never a second pump —
|
|
7
|
+
* so gap buffering, twin-claiming and resume behave exactly as today. The
|
|
8
|
+
* hook names no experimental feature: it matches on the method string, and
|
|
9
|
+
* the extension keeps its own state in its own instance.
|
|
10
|
+
*
|
|
11
|
+
* A throw never escapes: both loops catch an extension's throw and report
|
|
12
|
+
* it to that extension's `onError` (the `ApprovalFailure` "reported, not
|
|
13
|
+
* thrown" rule — the call site is a notification pump with nothing to
|
|
14
|
+
* catch it). Without an `onError` the failure is swallowed, deliberately:
|
|
15
|
+
* one bad add-on must not drop every session. An `onError` that itself
|
|
16
|
+
* throws is swallowed too, for the same reason the approval observer's is.
|
|
17
|
+
*/
|
|
18
|
+
/**
|
|
19
|
+
* Run every extension registered for `method`, in registration order.
|
|
20
|
+
*
|
|
21
|
+
* The ONE call-and-report loop both planes share (fold + client `#route`),
|
|
22
|
+
* so guard and reporting changes land once. Objects only — a frame without
|
|
23
|
+
* usable params has nothing to fold. A throw is reported to that
|
|
24
|
+
* extension's `onError` (absent means swallow); an `onError` that itself
|
|
25
|
+
* throws is swallowed too. Returns how many extensions fired.
|
|
26
|
+
*/
|
|
27
|
+
export function fireExtensions(extensions, method, params) {
|
|
28
|
+
if (params === null || typeof params !== "object" || Array.isArray(params))
|
|
29
|
+
return 0;
|
|
30
|
+
let fired = 0;
|
|
31
|
+
for (const extension of extensions) {
|
|
32
|
+
if (extension.method !== method)
|
|
33
|
+
continue;
|
|
34
|
+
fired += 1;
|
|
35
|
+
try {
|
|
36
|
+
extension.apply(params);
|
|
37
|
+
}
|
|
38
|
+
catch (error) {
|
|
39
|
+
try {
|
|
40
|
+
extension.onError?.(error);
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
// The failure observer threw. Swallowed, deliberately — same rule
|
|
44
|
+
// as the approval observer: there is no one left to tell.
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
return fired;
|
|
49
|
+
}
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
* displaces the first durable one.
|
|
30
30
|
*/
|
|
31
31
|
import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MonitorInboxItemAdmittedParams, MonitorInboxItemDrainedParams, MonitorInboxItemVoidedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelAttemptStartedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
|
|
32
|
+
import type { FoldExtension } from "./extension.js";
|
|
32
33
|
import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
|
|
33
34
|
import type { StateApplyOutcome, StateValue } from "./state-store.js";
|
|
34
35
|
/** The session-state families, each keyed in the store by its method name. */
|
|
@@ -395,6 +396,15 @@ export type FoldOutcome = {
|
|
|
395
396
|
} | {
|
|
396
397
|
readonly kind: "ignoredUnrecognizedMethod";
|
|
397
398
|
readonly method: string;
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* An otherwise-unrecognized method a registered extension handled
|
|
402
|
+
* (FR-97527-3). Ids only, like its ignored twin: the extension keeps
|
|
403
|
+
* its own state in its own instance, so nothing here needs sealing.
|
|
404
|
+
*/
|
|
405
|
+
| {
|
|
406
|
+
readonly kind: "extension";
|
|
407
|
+
readonly method: string;
|
|
398
408
|
} | {
|
|
399
409
|
/**
|
|
400
410
|
* A frame that carried no `params`. The generated `Notification`
|
|
@@ -504,6 +514,7 @@ export interface FoldSessionState {
|
|
|
504
514
|
*/
|
|
505
515
|
export declare class SessionFold {
|
|
506
516
|
#private;
|
|
517
|
+
constructor(extensions?: readonly FoldExtension[]);
|
|
507
518
|
/** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
|
|
508
519
|
get items(): FoldItems;
|
|
509
520
|
/**
|
|
@@ -28,6 +28,7 @@
|
|
|
28
28
|
* unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
|
|
29
29
|
* displaces the first durable one.
|
|
30
30
|
*/
|
|
31
|
+
import { fireExtensions } from "./extension.js";
|
|
31
32
|
import { ItemStore } from "./item-store.js";
|
|
32
33
|
import { SessionStateStore } from "./state-store.js";
|
|
33
34
|
/**
|
|
@@ -37,6 +38,10 @@ import { SessionStateStore } from "./state-store.js";
|
|
|
37
38
|
export class SessionFold {
|
|
38
39
|
#itemStore = new ItemStore();
|
|
39
40
|
#sessionStateStore = new SessionStateStore();
|
|
41
|
+
#extensions;
|
|
42
|
+
constructor(extensions = []) {
|
|
43
|
+
this.#extensions = extensions;
|
|
44
|
+
}
|
|
40
45
|
/** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
|
|
41
46
|
get items() {
|
|
42
47
|
return this.#itemStore;
|
|
@@ -151,6 +156,12 @@ export class SessionFold {
|
|
|
151
156
|
if (event.params === null || typeof event.params !== "object" || Array.isArray(event.params)) {
|
|
152
157
|
return { kind: "ignoredMissingParams", method: event.method };
|
|
153
158
|
}
|
|
159
|
+
// FR-97527-3: extensions registered for this frame's method run first,
|
|
160
|
+
// in registration order — for known methods they observe alongside the
|
|
161
|
+
// stable arm below (experimental fields ride here); for unknown methods
|
|
162
|
+
// they are the only handler. Inside this one apply path, never a second
|
|
163
|
+
// pump, so gap buffering and resume behave exactly as today.
|
|
164
|
+
const extensionsFired = fireExtensions(this.#extensions, event.method, event.params);
|
|
154
165
|
const typed = event;
|
|
155
166
|
switch (typed.method) {
|
|
156
167
|
case "item/started":
|
|
@@ -213,6 +224,8 @@ export class SessionFold {
|
|
|
213
224
|
};
|
|
214
225
|
default: {
|
|
215
226
|
const unrecognized = event;
|
|
227
|
+
if (extensionsFired > 0)
|
|
228
|
+
return { kind: "extension", method: unrecognized.method };
|
|
216
229
|
return { kind: "ignoredUnrecognizedMethod", method: unrecognized.method };
|
|
217
230
|
}
|
|
218
231
|
}
|
package/dist/src/index.d.ts
CHANGED
|
@@ -26,12 +26,13 @@
|
|
|
26
26
|
* regeneration, not behind a shape.
|
|
27
27
|
* - Corpus replay + checkpoint equality (slice 1c) — runnable now; own PR.
|
|
28
28
|
*/
|
|
29
|
-
export { EXPECTED_SCHEMA_FINGERPRINT, checkServedFingerprint, fingerprintMismatchMessage, } from "./fingerprint.js";
|
|
30
|
-
export type { FingerprintWarning } from "./fingerprint.js";
|
|
29
|
+
export { EXPECTED_SCHEMA_COMPATIBILITY_EPOCH, EXPECTED_SCHEMA_FINGERPRINT, SchemaCompatibilityError, checkServedFingerprint, classifyServedSchema, fingerprintMismatchMessage, } from "./fingerprint.js";
|
|
30
|
+
export type { AdditiveFingerprintWarning, DeclaredBreakingFingerprintWarning, FingerprintWarning, ServedSchemaIdentity, } from "./fingerprint.js";
|
|
31
31
|
export { ItemStore } from "./fold/item-store.js";
|
|
32
32
|
export type { DeltaApplyOutcome, ItemApplyOutcome, RevisionedItem, TerminalUnknownItemAnnotation, } from "./fold/item-store.js";
|
|
33
33
|
export { SessionStateStore } from "./fold/state-store.js";
|
|
34
34
|
export type { StateApplyOutcome, StateValue } from "./fold/state-store.js";
|
|
35
|
+
export type { FoldExtension } from "./fold/extension.js";
|
|
35
36
|
export { SessionFold } from "./fold/session-fold.js";
|
|
36
37
|
export type {
|
|
37
38
|
/**
|
|
@@ -44,10 +45,10 @@ DeepReadonly, FoldItems, FoldOutcome, FoldSessionState, PendingApproval, Session
|
|
|
44
45
|
export { COMMAND_REJECTED_CODE, COMMAND_REJECTED_KIND, PendingCommandSet, } from "./pending/pending-command-set.js";
|
|
45
46
|
export type { CommandErrorResponse, PendingCommandAck, PendingCommandEntry, PendingCommandSetOptions, PendingDisposition, PendingJoinPlan, PendingRetirement, ReplayAnswer, SnapshotJoinFacts, } from "./pending/pending-command-set.js";
|
|
46
47
|
export { Connection, createUuidV7Mint, MspError, ProtocolError, } from "./connection/connection.js";
|
|
47
|
-
export type { CommandOptions, ConnectionOptions, DuplexTransport, NotificationHandler, ProtocolErrorHandler, ServerRequestHandler, } from "./connection/connection.js";
|
|
48
|
+
export type { CommandOptions, ConnectionOptions, DuplexTransport, NotificationHandler, NotificationListener, ProtocolErrorHandler, ServerRequestHandler, } from "./connection/connection.js";
|
|
48
49
|
export { MspHandshake, MuseServeChild, SpawnedMspConnection, spawnMspConnection, } from "./connection/spawn.js";
|
|
49
50
|
export { MuseClient } from "./facade/client.js";
|
|
50
|
-
export type { MuseClientOptions, MuseClientSpawnOptions, ResumeSessionOptions, StartSessionOptions, } from "./facade/client.js";
|
|
51
|
+
export type { MuseClientOptions, MuseClientSpawnOptions, NotificationFailureHandler, NotificationObserver, ResumeSessionOptions, StartSessionOptions, } from "./facade/client.js";
|
|
51
52
|
export type { ExitClassification, MuseServeChildOptions, ProcessExit, SpawnMspConnectionOptions, } from "./connection/spawn.js";
|
|
52
53
|
export { DiscardedSessions } from "./facade/discarded.js";
|
|
53
54
|
export { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseForeignSessionError, MuseGapFillError, MuseHostDiscoveryError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
|
|
@@ -58,7 +59,7 @@ export { MuseHostStartError } from "./facade/host-start.js";
|
|
|
58
59
|
export type { HostStartFailure } from "./facade/host-start.js";
|
|
59
60
|
export type { AbnormalExit, HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile, TransportEof, } from "./facade/host-death.js";
|
|
60
61
|
export { Session } from "./facade/session.js";
|
|
61
|
-
export type { PendingCommandView, SessionApplyOutcome, SessionApplyRefusal, SessionFoldView, SessionGapBuffered, SessionGapOverlap, SessionOpening, SessionOptions, SubagentReasonOptions, } from "./facade/session.js";
|
|
62
|
+
export type { PendingCommandView, ReloadOptions, SessionApplyOutcome, SessionApplyRefusal, SessionEvent, SessionEventSubagent, SessionEventsOptions, SessionFoldView, SessionGapBuffered, SessionGapOverlap, SessionOpening, SessionOptions, SessionReplayDuplicate, SubagentReasonOptions, ViewFrame, } from "./facade/session.js";
|
|
62
63
|
export type { ApprovalDecisionInput, ApprovalFailure, ApprovalFailureHandler, ApprovalHandler, } from "./facade/approval.js";
|
|
63
64
|
export type { SendUserTurnOptions, SteerTurnOptions } from "./facade/turn-submit.js";
|
|
64
65
|
export type { RunOptions, RunResult } from "./facade/run.js";
|
package/dist/src/index.js
CHANGED
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
* regeneration, not behind a shape.
|
|
27
27
|
* - Corpus replay + checkpoint equality (slice 1c) — runnable now; own PR.
|
|
28
28
|
*/
|
|
29
|
-
export { EXPECTED_SCHEMA_FINGERPRINT, checkServedFingerprint, fingerprintMismatchMessage, } from "./fingerprint.js";
|
|
29
|
+
export { EXPECTED_SCHEMA_COMPATIBILITY_EPOCH, EXPECTED_SCHEMA_FINGERPRINT, SchemaCompatibilityError, checkServedFingerprint, classifyServedSchema, fingerprintMismatchMessage, } from "./fingerprint.js";
|
|
30
30
|
export { ItemStore } from "./fold/item-store.js";
|
|
31
31
|
export { SessionStateStore } from "./fold/state-store.js";
|
|
32
32
|
export { SessionFold } from "./fold/session-fold.js";
|