@ggui-ai/protocol-conformance 0.2.0-alpha.3 → 0.3.0-rc.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 (83) hide show
  1. package/README.md +32 -13
  2. package/dist/cli.d.ts +11 -1
  3. package/dist/cli.d.ts.map +1 -1
  4. package/dist/cli.js +48 -20
  5. package/dist/conformance-host.d.ts +81 -76
  6. package/dist/conformance-host.d.ts.map +1 -1
  7. package/dist/conformance-host.js +0 -44
  8. package/dist/fixtures/bootstrap-protocol/bootstrap-bundle-fetch-failed.json +3 -3
  9. package/dist/fixtures/bootstrap-protocol/bootstrap-meta-missing.json +3 -3
  10. package/dist/fixtures/bootstrap-protocol/bootstrap-success.json +3 -3
  11. package/dist/fixtures/consume-buffer/action-ack-sequence.json +28 -0
  12. package/dist/fixtures/consume-buffer/action-payload-schema-violation.json +37 -0
  13. package/dist/fixtures/consume-buffer/index.d.ts +6 -0
  14. package/dist/fixtures/consume-buffer/index.d.ts.map +1 -0
  15. package/dist/fixtures/consume-buffer/index.js +41 -0
  16. package/dist/fixtures/consume-buffer/undeclared-action-rejected.json +29 -0
  17. package/dist/fixtures/host-context/host-context-observed-persists.json +34 -0
  18. package/dist/fixtures/host-context/index.d.ts +5 -0
  19. package/dist/fixtures/host-context/index.d.ts.map +1 -0
  20. package/dist/fixtures/host-context/index.js +40 -0
  21. package/dist/fixtures/index.d.ts +28 -9
  22. package/dist/fixtures/index.d.ts.map +1 -1
  23. package/dist/fixtures/index.js +33 -14
  24. package/dist/fixtures/reserved-channel-authority/index.d.ts.map +1 -1
  25. package/dist/fixtures/reserved-channel-authority/index.js +17 -7
  26. package/dist/fixtures/reserved-channel-authority/props-update-roundtrip.json +4 -4
  27. package/dist/fixtures/schema-version-handshake/index.d.ts.map +1 -1
  28. package/dist/fixtures/schema-version-handshake/index.js +12 -4
  29. package/dist/fixtures/schema-version-handshake/version-match.json +7 -5
  30. package/dist/fixtures/schema-version-handshake/version-mismatch.json +9 -10
  31. package/dist/fixtures/subscribe-tenancy/absent-appid-defaults.json +18 -0
  32. package/dist/fixtures/subscribe-tenancy/app-mismatch.json +20 -0
  33. package/dist/fixtures/subscribe-tenancy/index.d.ts +6 -0
  34. package/dist/fixtures/subscribe-tenancy/index.d.ts.map +1 -0
  35. package/dist/fixtures/subscribe-tenancy/index.js +62 -0
  36. package/dist/index.d.ts +4 -4
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +4 -4
  39. package/dist/match-behavior.d.ts +19 -100
  40. package/dist/match-behavior.d.ts.map +1 -1
  41. package/dist/match-behavior.js +289 -246
  42. package/dist/registration-conformance/cases/gate-duplicate-hook.json +26 -0
  43. package/dist/registration-conformance/cases/gate-export-not-registered.json +1 -0
  44. package/dist/registration-conformance/cases/gate-multi-package-distinct-names-accept.json +26 -0
  45. package/dist/registration-conformance/cases/gate-no-gadgets-accept.json +1 -0
  46. package/dist/registration-conformance/cases/gate-package-mismatch.json +1 -0
  47. package/dist/registration-conformance/cases/gate-priority-not-registered-outranks-mismatch.json +1 -0
  48. package/dist/registration-conformance/cases/gate-priority-registry-outranks-public-env.json +22 -0
  49. package/dist/registration-conformance/cases/gate-public-env-missing.json +21 -0
  50. package/dist/registration-conformance/cases/gate-public-env-satisfied-accept.json +21 -0
  51. package/dist/registration-conformance/cases/gate-public-env-undeclared-wrapper-accept.json +26 -0
  52. package/dist/registration-conformance/cases/gate-registered-resolves-accept.json +1 -0
  53. package/dist/registration-conformance/cases/gate-stdlib-hook-accept.json +1 -0
  54. package/dist/registration-conformance/cases/gate-typo-classifies-as-not-registered.json +1 -0
  55. package/dist/registration-conformance/index.d.ts +64 -33
  56. package/dist/registration-conformance/index.d.ts.map +1 -1
  57. package/dist/registration-conformance/index.js +24 -8
  58. package/dist/run-conformance.d.ts +145 -6
  59. package/dist/run-conformance.d.ts.map +1 -1
  60. package/dist/run-conformance.js +531 -93
  61. package/dist/types.d.ts +319 -165
  62. package/dist/types.d.ts.map +1 -1
  63. package/dist/types.js +27 -23
  64. package/dist/ws-transport.d.ts.map +1 -1
  65. package/dist/ws-transport.js +3 -2
  66. package/package.json +3 -3
  67. package/dist/fixtures/observability-events/index.d.ts +0 -5
  68. package/dist/fixtures/observability-events/index.d.ts.map +0 -1
  69. package/dist/fixtures/observability-events/index.js +0 -22
  70. package/dist/fixtures/observability-events/observability-contract-error-emitted.json +0 -28
  71. package/dist/fixtures/observability-events/observability-wired-tool-invoked.json +0 -27
  72. package/dist/fixtures/refresh-semantics/index.d.ts +0 -5
  73. package/dist/fixtures/refresh-semantics/index.d.ts.map +0 -1
  74. package/dist/fixtures/refresh-semantics/index.js +0 -19
  75. package/dist/fixtures/refresh-semantics/stream-refresh-success.json +0 -39
  76. package/dist/fixtures/reserved-channel-authority/stream-schema-violation.json +0 -44
  77. package/dist/fixtures/wired-action-dispatch/index.d.ts +0 -5
  78. package/dist/fixtures/wired-action-dispatch/index.d.ts.map +0 -1
  79. package/dist/fixtures/wired-action-dispatch/index.js +0 -29
  80. package/dist/fixtures/wired-action-dispatch/wired-action-success.json +0 -35
  81. package/dist/fixtures/wired-action-dispatch/wired-action-tool-not-found.json +0 -30
  82. package/dist/fixtures/wired-action-dispatch/wired-action-tool-threw.json +0 -31
  83. package/dist/fixtures/wired-action-dispatch/wired-action-tool-timeout.json +0 -31
@@ -0,0 +1,62 @@
1
+ /**
2
+ * `subscribe-tenancy` fixture sub-module.
3
+ *
4
+ * Exercises the subscribe-time tenancy contract (SPEC §12.2 subscribe
5
+ * payload table + §12.2.3 channel-3 error codes):
6
+ *
7
+ * - `app-mismatch` — the GguiSession exists but is bound to a
8
+ * different `appId` than the subscribe claims. §12.2 is explicit
9
+ * MUST language (a present `appId` "MUST match the GguiSession's
10
+ * bound `appId` or subscribe fails `APP_MISMATCH`"), and §12.2.3
11
+ * keeps the code distinct from `SESSION_NOT_FOUND` so clients can
12
+ * route the two recoveries (fix-appId vs re-handshake)
13
+ * differently.
14
+ *
15
+ * - `absent-appid-defaults` — `appId` is OPTIONAL on the subscribe
16
+ * payload: absence resolves the caller's identity-default app
17
+ * (§12.2's resolution rule — token binding, else identity
18
+ * mapping, else the deployment default) and the subscribe acks.
19
+ * Graded as a session-state read-back of the bound `appId` on the
20
+ * provisioned render (hosts expose it via `readSessionField`), so
21
+ * a server that acks but binds an undefined tenant — the
22
+ * corrupt-row failure mode — fails rather than passing on the ack
23
+ * alone.
24
+ *
25
+ * ## Declared gaps — the other subscribe-rejection codes
26
+ *
27
+ * `SESSION_NOT_FOUND` (§12.2.3) is canonical VOCABULARY here, not a
28
+ * graded subscribe obligation: the §12.2 subscribe-payload table
29
+ * attaches a MUST to a PRESENT `appId` only. Whether a subscribe targeting an
30
+ * unknown `sessionId` rejects or provisions is implementation-defined
31
+ * — the first-party `@ggui-ai/mcp-server` channel deliberately
32
+ * PROVISIONS the GguiSession on first subscribe (its dev-mode
33
+ * render-provisioning seam; deployments tighten it via the
34
+ * `AuthAdapter`), and the reference server provisions the same way. A
35
+ * fixture demanding the error frame would fail conformant servers.
36
+ * The first-party emission site for the code is the ACTION path (the
37
+ * GguiSession vanished between subscribe and action) — not drivable
38
+ * by the kit: there is no delete-session directive, by design
39
+ * (renders decay via TTL). Note §12.2.3's provenance column ("emitted
40
+ * by subscribe handlers") contradicts the shipping subscribe
41
+ * behavior; resolving that is an upstream SPEC decision, declared
42
+ * here rather than graded prematurely.
43
+ *
44
+ * `AUTH_REJECTED` is not a §12.2.3 channel-3 code at all. Failing
45
+ * upgrade-auth rejects the HTTP upgrade itself (the WebSocket never
46
+ * opens, so no error frame exists to match), and the in-band
47
+ * `wsToken` path rejects with the dedicated `BOOTSTRAP_INVALID` /
48
+ * `BOOTSTRAP_EXPIRED` codes. There is no wire surface on
49
+ * which a failing-auth subscribe produces an `AUTH_REJECTED` frame
50
+ * today, so no fixture ships and no fixture-level auth-override knob
51
+ * was added — it would be dead vocabulary until such a surface
52
+ * exists.
53
+ */
54
+ import absentAppidDefaults from './absent-appid-defaults.json' with { type: 'json' };
55
+ import appMismatch from './app-mismatch.json' with { type: 'json' };
56
+ /** All fixtures asserting subscribe-time tenancy (SPEC §12.2 field
57
+ * table — identity-default resolution on absent `appId` — and
58
+ * §12.2.3 `APP_MISMATCH`). */
59
+ export const subscribeTenancyFixtures = [
60
+ absentAppidDefaults,
61
+ appMismatch,
62
+ ];
package/dist/index.d.ts CHANGED
@@ -10,9 +10,9 @@
10
10
  * its assertions and `@ggui-ai/protocol`'s types is the canonical
11
11
  * bug.
12
12
  */
13
- export type { TransportConfig, WebSocketTransportConfig, UnknownTransportConfig, AuthConfig, TestCase, SetupStep, CreateRenderStep, RegisterToolStep, EmitEnvelopeStep, SeedChannelStep, UnknownSetupStep, TeardownStep, UnregisterToolStep, UnknownTeardownStep, ExpectedBehavior, ContractErrorBehavior, StreamUpdateBehavior, ObservabilityBehavior, BootstrapFailureBehavior, BootstrapSuccessBehavior, VersionMismatchBehavior, PropsUpdateBehavior, NoOpBehavior, UnknownBehavior, ExpectedObservabilityEvent, ProtocolError, BootstrapFailureReason, ContractErrorCode, } from './types.js';
14
- export type { ConformanceHost, SetupStep as HostSetupStep, CreateRenderSetup, RegisterToolSetup, RegisterActionSpecSetup, EmitEnvelopeSetup, RendererUrlOverrideSetup, UiInitializeResponseOverrideSetup, ServerVersionOverrideSetup, UnknownSetupStep as HostUnknownSetupStep, TeardownStep as HostTeardownStep, UnregisterToolTeardown, UnknownTeardownStep as HostUnknownTeardownStep, } from './conformance-host.js';
15
- export { allFixtures, fixturesByContract, bootstrapProtocolFixtures, observabilityEventsFixtures, refreshSemanticsFixtures, reservedChannelAuthorityFixtures, schemaVersionHandshakeFixtures, wiredActionDispatchFixtures, } from './fixtures/index.js';
13
+ export type { TransportConfig, WebSocketTransportConfig, UnknownTransportConfig, AuthConfig, TestCase, SubscribeFrameShaping, SetupStep, CreateGguiSessionStep, ActionSpecEntryDecl, JsonSchemaDecl, RendererUrlOverrideStep, ServerVersionOverrideStep, UiInitializeResponseOverrideStep, EmitEnvelopeStep, TeardownStep, ExpectedBehavior, ActionAckBehavior, ErrorFrameBehavior, StreamUpdateBehavior, BootstrapFailureBehavior, BootstrapSuccessBehavior, VersionMismatchBehavior, PropsUpdateBehavior, SessionStateBehavior, NoOpBehavior, UnknownBehavior, ProtocolError, BootstrapFailureReason, } from './types.js';
14
+ export type { ConformanceHost, SetupStep as HostSetupStep, CreateGguiSessionSetup, RendererUrlOverrideSetup, ServerVersionOverrideSetup, UiInitializeResponseOverrideSetup, EmitEnvelopeSetup, TeardownStep as HostTeardownStep, } from './conformance-host.js';
15
+ export { allFixtures, fixturesByContract, bootstrapProtocolFixtures, consumeBufferFixtures, hostContextFixtures, reservedChannelAuthorityFixtures, schemaVersionHandshakeFixtures, subscribeTenancyFixtures, } from './fixtures/index.js';
16
16
  export type { ContractSlug } from './fixtures/index.js';
17
17
  export { gadgetWireSchemaCases, runSchemaConformance, } from './schema-conformance/index.js';
18
18
  export type { SchemaConformanceCase, SchemaConformanceMismatch, SchemaConformanceResult, } from './schema-conformance/index.js';
@@ -22,7 +22,7 @@ export { gadgetResolutionCases, runResolutionConformance, } from './resolution-c
22
22
  export type { GadgetUrlEntry, ResolvedGadgetUrls, ResolutionConformanceCase, ResolutionConformanceMismatch, ResolutionConformanceResult, } from './resolution-conformance/index.js';
23
23
  export { loadFixture, listFixtures, loadAllFixtures } from './loader.js';
24
24
  export { runConformance } from './run-conformance.js';
25
- export type { RunConformanceConfig, ConformanceResult, ConformanceFailure, SkippedFixture, ConformanceReporter, } from './run-conformance.js';
25
+ export type { RunConformanceConfig, ConformanceResult, ConformanceFailure, SkippedFixture, ConformanceReporter, InputEnvelopeDispatch, HostContextObservedInputEnvelope, } from './run-conformance.js';
26
26
  export { createDefaultReporter, formatScorecard, formatSummary, formatFailures, formatSkips, } from './reporter.js';
27
27
  export type { DefaultReporterOptions } from './reporter.js';
28
28
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,YAAY,EAEV,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,UAAU,EAEV,QAAQ,EAER,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAEhB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EAEnB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,0BAA0B,EAE1B,aAAa,EACb,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAMpB,YAAY,EACV,eAAe,EAEf,SAAS,IAAI,aAAa,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,wBAAwB,EACxB,iCAAiC,EACjC,0BAA0B,EAC1B,gBAAgB,IAAI,oBAAoB,EAExC,YAAY,IAAI,gBAAgB,EAChC,sBAAsB,EACtB,mBAAmB,IAAI,uBAAuB,GAC/C,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,gCAAgC,EAChC,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,2BAA2B,EAC3B,+BAA+B,EAC/B,6BAA6B,GAC9B,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,YAAY,EAEV,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,UAAU,EAEV,QAAQ,EACR,qBAAqB,EAErB,SAAS,EACT,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,yBAAyB,EACzB,gCAAgC,EAChC,gBAAgB,EAEhB,YAAY,EAEZ,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,eAAe,EAEf,aAAa,EACb,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAMpB,YAAY,EACV,eAAe,EAEf,SAAS,IAAI,aAAa,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,EAC1B,iCAAiC,EACjC,iBAAiB,EAEjB,YAAY,IAAI,gBAAgB,GACjC,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,mBAAmB,EACnB,gCAAgC,EAChC,8BAA8B,EAC9B,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,2BAA2B,EAC3B,+BAA+B,EAC/B,6BAA6B,GAC9B,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EAInB,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}
package/dist/index.js CHANGED
@@ -13,7 +13,7 @@
13
13
  // Fixture catalog — every authored conformance case, classified by
14
14
  // contract. Third-party runners + the kit's own `runConformance()`
15
15
  // consume this surface.
16
- export { allFixtures, fixturesByContract, bootstrapProtocolFixtures, observabilityEventsFixtures, refreshSemanticsFixtures, reservedChannelAuthorityFixtures, schemaVersionHandshakeFixtures, wiredActionDispatchFixtures, } from './fixtures/index.js';
16
+ export { allFixtures, fixturesByContract, bootstrapProtocolFixtures, consumeBufferFixtures, hostContextFixtures, reservedChannelAuthorityFixtures, schemaVersionHandshakeFixtures, subscribeTenancyFixtures, } from './fixtures/index.js';
17
17
  // Pure-function conformance catalogs — SPEC §7.7.2's gadget
18
18
  // obligations are deterministic validation functions, not transport-
19
19
  // observable behaviors. Each catalog grades a caller-supplied function
@@ -22,9 +22,9 @@ export { allFixtures, fixturesByContract, bootstrapProtocolFixtures, observabili
22
22
  // Schema-conformance — which `DataContract.clientCapabilities`
23
23
  // payloads a conformant parser MUST accept / reject.
24
24
  export { gadgetWireSchemaCases, runSchemaConformance, } from './schema-conformance/index.js';
25
- // Registration-conformance — which `(contract, appGadgets)` pairs the
26
- // push-time gadget registry gate MUST accept / reject, with which
27
- // precise reject code.
25
+ // Registration-conformance — which `(contract, appGadgets, appPublicEnv)`
26
+ // triples the push-time gadget gate stack MUST accept / reject, with
27
+ // which precise SPEC §7.9 reject code.
28
28
  export { gadgetRegistrationCases, runRegistrationConformance, } from './registration-conformance/index.js';
29
29
  // Resolution-conformance — which bundle + style URLs the server MUST
30
30
  // compute for a gadget descriptor's transport fields (`bundleHost`
@@ -1,103 +1,3 @@
1
- /**
2
- * Match observed WS frames against a fixture's {@link ExpectedBehavior}.
3
- *
4
- * Each matcher is pure — it consumes a read-only array of frames the
5
- * runner collected from the transport and returns either a pass or a
6
- * {@link MatchFailure} the runner lifts into a
7
- * {@link ConformanceFailure}. No side-effects, no hidden state — the
8
- * runner owns orchestration.
9
- *
10
- * ## Path-A vs Path-B partition
11
- *
12
- * The kit's behavior vocabulary spans both wire-observable claims (the
13
- * subscribe ack, contract-error envelopes on reserved channels, stream
14
- * updates) AND surface-observable claims (DOM state after a props
15
- * update, browser-side bootstrap failure modes). This file matches the
16
- * **Path-A** subset — the wire-observable behaviors a runner can
17
- * assert from frames alone, with no MCP-Apps-host adapter and no
18
- * Playwright page. The Path-B subset (browser-host harness) is
19
- * inherently NOT WS-reducible: bootstrap-failure modes are caused by
20
- * the renderer-bundle fetch + `ui/initialize` round-trip the host
21
- * speaks over postMessage; props-update assertions are assertions on
22
- * the rendered DOM the renderer paints, not on WS frames the server
23
- * emits. For these kinds we return `unmatchable-on-ws` with a sharp
24
- * reason and the runner records SKIP — they are NOT failures of the
25
- * server, they are claims a different driver must drive.
26
- *
27
- * The Path-B driver is a separate Playwright-based test suite — it
28
- * picks up the `bootstrap-failure` fixtures and asserts on the
29
- * iframe-host's `data-ggui-console-iframe-error` pane after
30
- * route-based fault injection. A future packaged browser-host adapter
31
- * will fold that capability into the kit so third-party adopters
32
- * don't have to reimplement it. Until then, the partition is honest:
33
- * Path A handles wire claims, Path B (out-of-process) handles
34
- * browser claims, and `unmatchable-on-ws` is the partition seam.
35
- *
36
- * v1 Path-A scope:
37
- *
38
- * - `bootstrap-success` — subscribe produced an `ack` frame.
39
- * - `version-mismatch` — subscribe produced an `error` frame with
40
- * `code: 'UPGRADE_REQUIRED'`.
41
- * - `contract-error` — stream frame on `_ggui:contract-error`
42
- * channel matches `code` + `toolName` (+ optional `actionName` +
43
- * `sourceAction`).
44
- * - `stream-update` — stream frame on named channel matches
45
- * declared value.
46
- * - `no-op` — no frames observed after input dispatch.
47
- * - `observability-event` — see below.
48
- *
49
- * v1 Path-B-only kinds (return `unmatchable-on-ws`):
50
- *
51
- * - `bootstrap-failure` — the fault surface lives in the host's
52
- * bootstrap-fetch + `ui/initialize` round-trip; the fixture's
53
- * `renderer-url-override` / `ui-initialize-response-override`
54
- * setup directives are MCP-Apps-host concerns, not WS server
55
- * concerns. The reference server's host adapter correctly throws
56
- * "out of scope" on these directives — that's not a bug, it's
57
- * the partition being respected.
58
- * - `props-update` — the assertion is on rendered DOM after the
59
- * server emits a `_ggui:props` frame; matchable on WS only as
60
- * "frame was emitted", not as "DOM reflects it" — and the fixture
61
- * vocabulary asserts the latter.
62
- *
63
- * ## `observability-event` — WS-evidence matcher
64
- *
65
- * The ggui protocol bar mandates that observability events follow
66
- * from WS-observable evidence. The bar's claim is "any conformant host
67
- * MUST emit `wired-tool-invoked` when the WS observes a wired-action's
68
- * tool dispatch + result frame; any conformant host MUST emit
69
- * `contract-error-emitted` when the WS observes a `_ggui:contract-
70
- * error` envelope." So a Path-A pass on an `observability-event`
71
- * fixture is the kit certifying "WS evidence the bar mandates a host
72
- * mirror-emission for is present" — a true vendor-neutral conformance
73
- * claim, not a renderer-internal probe.
74
- *
75
- * Two recognized event arms (extensibly closed via `(string & {})`):
76
- *
77
- * - `wired-tool-invoked` — assert a `stream` frame on the
78
- * `_ggui:wired-tool-invoked` channel carrying
79
- * `value: {toolName, actionName?}` matching `event.toolName`
80
- * (+ optional `event.actionName`). The reference server emits
81
- * this signal from `action-router.ts::dispatchAction()` after a
82
- * successful handler resolution — every conformant host MUST
83
- * produce equivalent WS evidence (or a richer mirror-emission a
84
- * Path-B browser host can observe).
85
- *
86
- * - `contract-error-emitted` — assert a `stream` frame on the
87
- * `_ggui:contract-error` channel whose canonical SPEC §4.4
88
- * `ContractErrorPayload` carries `error.code === event.code` and
89
- * `toolName === event.toolName` (+ optional `event.actionName`).
90
- * This is the SAME frame {@link matchContractError} matches; the
91
- * observability arm asserts the bar's "every live-channel envelope
92
- * becomes an observability event" mirror without requiring a
93
- * postMessage-capture harness.
94
- *
95
- * Other arms (`schema-version-mismatch`, `subscribe-failed`,
96
- * future `(string & {})` tails) the matcher cannot ground in current
97
- * WS evidence — return `unmatchable-on-ws` with a sharp reason so the
98
- * runner records SKIP, not FAIL. These are Path-B candidates for the
99
- * future browser-host adapter.
100
- */
101
1
  import type { ExpectedBehavior } from './types.js';
102
2
  import type { ObservedFrame } from './ws-transport.js';
103
3
  /**
@@ -117,5 +17,24 @@ export type MatchResult = {
117
17
  readonly kind: 'unmatchable-on-ws';
118
18
  readonly reason: string;
119
19
  };
20
+ /**
21
+ * Discriminant narrowing for the extensibly-closed
22
+ * {@link ExpectedBehavior} union. The `UnknownBehavior` arm's
23
+ * `kind: string & {}` deliberately widens the discriminant (future
24
+ * fixture vocabulary must flow through as opaque records), which also
25
+ * stops TS narrowing on direct literal checks — so the kit dispatches
26
+ * through this predicate instead of per-site casts. The runtime check
27
+ * is exactly the literal comparison the predicate claims.
28
+ */
29
+ export declare function behaviorIs<K extends ExpectedBehavior['kind']>(behavior: ExpectedBehavior, kind: K): behavior is Extract<ExpectedBehavior, {
30
+ readonly kind: K;
31
+ }>;
120
32
  export declare function matchBehavior(behavior: ExpectedBehavior, frames: readonly ObservedFrame[]): MatchResult;
33
+ /**
34
+ * Exact deep-equal — objects must have identical key sets, arrays
35
+ * identical length + ordered contents. Exported so the runner grades
36
+ * `session-state` read-backs with the SAME comparison the frame
37
+ * matchers use — one equality, no matcher/runner drift.
38
+ */
39
+ export declare function deepEqual(a: unknown, b: unknown): boolean;
121
40
  //# sourceMappingURL=match-behavior.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"match-behavior.d.ts","sourceRoot":"","sources":["../src/match-behavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,OAAO,KAAK,EAGV,gBAAgB,EAMjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,WAAW,CA2Cb"}
1
+ {"version":3,"file":"match-behavior.d.ts","sourceRoot":"","sources":["../src/match-behavior.ts"],"names":[],"mappings":"AA6FA,OAAO,KAAK,EAIV,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,EAC3D,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,CAAC,GACN,QAAQ,IAAI,OAAO,CAAC,gBAAgB,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAE7D;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,WAAW,CAkDb;AAgRD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAgBzD"}