@ggui-ai/protocol-conformance 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Loqu, Inc. (Guuey)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,89 @@
+# @ggui-ai/protocol-conformance
+
+Conformance test kit for the ggui protocol. Ships a JSON fixture catalog + a runner that drives each fixture against a live implementation over WebSocket and reports scorecard-style pass / fail / skip output.
+
+This kit is the protocol's conformance surface: it lets a third-party MCP builder prove their implementation is protocol-conformant without reimplementing the test harness.
+
+## Transport
+
+**v1.0 is WebSocket-only.** The canonical ggui transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later transports (stdio MCP, HTTP long-poll) can be added post-v1.1 without breaking the public API.
+
+## Path-A vs Path-B matchability
+
+The fixture catalog spans both wire-observable claims and surface-observable claims. The kit's runner (`runConformance()`) handles the **Path-A** subset — behaviors a runner can assert from WS frames alone, with no MCP-Apps-host adapter and no Playwright page.
+
+Path-A-matchable kinds (`matchBehavior` returns `pass` / `fail`):
+
+- `bootstrap-success` — subscribe → `ack` round-trip
+- `version-mismatch` — `error` frame with `code: UPGRADE_REQUIRED`
+- `contract-error` — `_ggui:contract-error` envelope on the reserved channel
+- `stream-update` — `stream` frame on a named channel matching the declared value
+- `no-op` — silence after input dispatch
+- `observability-event` — `wired-tool-invoked` and `contract-error-emitted` arms (the WS evidence the protocol-and-contract bar mandates a conformant host mirror-emit on)
+
+Path-B-only kinds (`matchBehavior` returns `unmatchable-on-ws` → runner records SKIP):
+
+- `bootstrap-failure` — fault surface is the host's bootstrap-fetch + `ui/initialize` postMessage round-trip; `renderer-url-override` / `ui-initialize-response-override` setup directives are MCP-Apps-host concerns, not WS server concerns.
+- `props-update` — assertion is on rendered DOM after `_ggui:props` is emitted; matchable on WS only as "frame was emitted", not as "DOM reflects it".
+- Future `observability-event` arms beyond the two above (e.g. `schema-version-mismatch`, `subscribe-failed`).
+
+A Path-B browser-host harness drives these fixtures via Playwright + `page.route()` fault injection + DOM assertion. A future packaged browser-host adapter will fold that capability into the kit so third-party adopters don't reimplement it.
+
+The partition is intentional: Path-A FAILs are vendor-neutrality bugs the server owns; Path-B SKIPs are not fails — they are claims a different driver is responsible for.
+
+## Pure-function conformance catalogs
+
+The behavioral fixture catalog above asserts what an implementation _does_ over the wire. Some protocol obligations aren't transport-observable at all — they are deterministic _validation functions_: given an input, accept or reject it. SPEC §7.7.2's gadget obligations are exactly this. Modeling them as WebSocket fixtures would mean faking wire frames the protocol never emits; instead the kit ships **pure-function catalogs** — accept/reject cases graded against a caller-supplied function, with no host, session, or transport.
+
+Each catalog ships its cases as raw JSON so a non-TypeScript implementer can grade their own implementation, and each runner takes the implementation as a callback — the kit never hard-binds a concrete one. Three catalogs ship today:
+
+- **`@ggui-ai/protocol-conformance/schema-conformance`** — which `DataContract.clientCapabilities` payloads a conformant parser MUST accept / reject (the gadget wire shape).
+- **`@ggui-ai/protocol-conformance/registration-conformance`** — which `(contract, appGadgets)` pairs the push-time gadget registry gate MUST accept / reject, and with which precise reject code (`gadget_not_registered` / `gadget_package_mismatch`).
+- **`@ggui-ai/protocol-conformance/resolution-conformance`** — which bundle + style URLs the server MUST compute for a gadget descriptor's transport fields (`bundleHost` precedence, default host, loopback `http` scheme).
+
+```ts
+import { runSchemaConformance } from "@ggui-ai/protocol-conformance/schema-conformance";
+import { runRegistrationConformance } from "@ggui-ai/protocol-conformance/registration-conformance";
+import { runResolutionConformance } from "@ggui-ai/protocol-conformance/resolution-conformance";
+
+const schema = runSchemaConformance((clientCapabilities) =>
+  myGadgetWireParser.isValid(clientCapabilities)
+);
+const gate = runRegistrationConformance((contract, appGadgets) =>
+  myGadgetGate(contract, appGadgets)
+);
+const urls = runResolutionConformance((entry) => myGadgetUrlResolver(entry));
+
+if (schema.failed.length + gate.failed.length + urls.failed.length > 0) {
+  process.exit(1);
+}
+```
+
+The `schema-conformance` meta-test binds its catalog to the live `@ggui-ai/protocol` `clientCapabilitiesSpecSchema` — a drift-catch if the wire schema diverges from the §7.7.2 obligations the catalog freezes. The `registration-conformance` and `resolution-conformance` meta-tests verify catalog coherence against faithful in-test implementations (the kit stays vendor-neutral — it does not depend on a server implementation); grading the _shipping_ gate / resolver is an implementation-side test that drives the corresponding runner.
+
+## Public API (target)
+
+```ts
+import { runConformance } from "@ggui-ai/protocol-conformance";
+
+const result = await runConformance({
+  serverUrl: "ws://localhost:3000/ws",
+  auth: { kind: "bearer", token: process.env.TOKEN! },
+});
+
+if (result.failed.length > 0) {
+  process.exit(1);
+}
+```
+
+CLI equivalent:
+
+```
+npx @ggui-ai/protocol-conformance --url ws://localhost:3000/ws --auth bearer:$TOKEN
+```
+
+Full adoption guide + fixture-to-contract mapping table land with the fixture-extraction commit.
+
+## License
+
+Apache 2.0 — see `../LICENSE`.

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import type { AuthConfig } from './types.js';
+interface ParsedArgs {
+    readonly url?: string;
+    readonly auth?: string;
+    readonly only?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly verbose: boolean;
+    readonly help: boolean;
+}
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare function parseAuth(spec: string): AuthConfig;
+declare function main(argv: readonly string[]): Promise<number>;
+export { main, parseArgs, parseAuth };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,UAAU,UAAU;IAClB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,iBAAS,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA8CtD;AAED,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAY3C;AA+BD,iBAAe,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoD5D;AA+BD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC"}

package/dist/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * `ggui-protocol-conformance` — CLI entry point.
+ *
+ * Usage:
+ *
+ *     npx @ggui-ai/protocol-conformance \
+ *       --url http://localhost:3000 \
+ *       --auth bearer:TOKEN
+ *
+ * Exits with code 0 if every fixture passed OR skipped; exits 1 if
+ * ANY fixture failed. Skips are not failures — an implementation may
+ * legitimately not provide every `ConformanceHost` directive in
+ * v1.0. Operators who want skip-is-failure semantics can pair
+ * `--require-host` (future) with a host that implements every known
+ * directive.
+ *
+ * Honest scope of the bundled CLI: no `host` wiring. The CLI runs
+ * the runner with an absent host, meaning every fixture with non-empty
+ * `setup` skips cleanly with the "no host provided" reason. To get
+ * real pass/fail signal against an implementation, consumers call
+ * `runConformance({ host: myImpl })` programmatically. The CLI is the
+ * lowest-friction entry point for a smoke check, and for CI jobs where
+ * the server under test is exercised directly over the wire via a
+ * subprocess harness rather than a `ConformanceHost` injection.
+ */
+import { createDefaultReporter, formatFailures, formatSkips } from './reporter.js';
+import { runConformance } from './run-conformance.js';
+function parseArgs(argv) {
+    let url;
+    let auth;
+    const only = [];
+    let timeoutMs;
+    let verbose = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const flag = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`missing value for '${flag}'`);
+            }
+            i += 1;
+            return value;
+        };
+        switch (flag) {
+            case '--url':
+                url = next();
+                break;
+            case '--auth':
+                auth = next();
+                break;
+            case '--only':
+                only.push(next());
+                break;
+            case '--timeout-ms':
+                timeoutMs = Number.parseInt(next(), 10);
+                if (Number.isNaN(timeoutMs))
+                    throw new Error('--timeout-ms must be an integer');
+                break;
+            case '--verbose':
+            case '-v':
+                verbose = true;
+                break;
+            case '--help':
+            case '-h':
+                help = true;
+                break;
+            default:
+                throw new Error(`unknown flag '${flag}' — run with --help for usage`);
+        }
+    }
+    return { url, auth, only, timeoutMs, verbose, help };
+}
+function parseAuth(spec) {
+    const idx = spec.indexOf(':');
+    if (idx === -1) {
+        throw new Error(`--auth expects 'kind:value'; received '${spec}'`);
+    }
+    const kind = spec.slice(0, idx);
+    const value = spec.slice(idx + 1);
+    if (kind === 'bearer')
+        return { kind: 'bearer', token: value };
+    if (kind === 'session-cookie')
+        return { kind: 'session-cookie', cookie: value };
+    throw new Error(`--auth kind '${kind}' is not recognized; supported: 'bearer', 'session-cookie'`);
+}
+// =============================================================================
+// Entry point
+// =============================================================================
+const USAGE = `
+ggui-protocol-conformance — run the protocol conformance kit against a live server
+
+Usage:
+  ggui-protocol-conformance --url <URL> --auth <kind:value> [options]
+
+Required:
+  --url <URL>              Base URL of the server (http://… or https://…).
+                           The runner derives ws://…/ws from this.
+  --auth <kind:value>      Auth carried on the WS upgrade.
+                             bearer:TOKEN          — Authorization header
+                             session-cookie:COOKIE — Cookie header
+
+Options:
+  --only <fixture-name>    Run only this fixture. May be repeated.
+  --timeout-ms <N>         Per-fixture observation window. Default 2000.
+  --verbose, -v            Print failure details + skip reasons at the end.
+  --help, -h               Show this help.
+
+Exit codes:
+  0  — all fixtures passed or skipped.
+  1  — at least one fixture failed.
+  2  — invocation error (bad args, cannot reach server, etc.).
+`.trimStart();
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`error: ${String(err.message ?? err)}\n\n`);
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    if (parsed.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (parsed.url === undefined) {
+        process.stderr.write('error: --url is required\n\n');
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    if (parsed.auth === undefined) {
+        process.stderr.write('error: --auth is required\n\n');
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    let auth;
+    try {
+        auth = parseAuth(parsed.auth);
+    }
+    catch (err) {
+        process.stderr.write(`error: ${String(err.message ?? err)}\n\n`);
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    const reporter = createDefaultReporter();
+    const result = await runConformance({
+        serverUrl: parsed.url,
+        auth,
+        only: parsed.only !== undefined && parsed.only.length > 0 ? parsed.only : undefined,
+        observationTimeoutMs: parsed.timeoutMs,
+        reporter,
+    });
+    if (parsed.verbose) {
+        const failures = formatFailures(result.failed);
+        if (failures.length > 0)
+            process.stdout.write(`${failures}\n`);
+        const skips = formatSkips(result.skipped);
+        if (skips.length > 0)
+            process.stdout.write(`${skips}\n`);
+    }
+    return result.failed.length > 0 ? 1 : 0;
+}
+// Immediately-invoked — this module IS the bin entry. Tests import
+// `parseArgs` / `parseAuth` / `main` via named exports without
+// triggering the run.
+if (isEntryPoint()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`fatal: ${String(err.message ?? err)}\n`);
+        process.exit(2);
+    });
+}
+function isEntryPoint() {
+    // Node ESM entry-point check. `import.meta.url` equals
+    // `pathToFileURL(process.argv[1])` when this module was invoked as
+    // the script. Guards against running `main()` when the module is
+    // imported (e.g., from meta-tests).
+    if (typeof import.meta.url !== 'string')
+        return false;
+    const scriptPath = process.argv[1];
+    if (typeof scriptPath !== 'string' || scriptPath.length === 0)
+        return false;
+    try {
+        const scriptUrl = new URL(`file://${scriptPath}`);
+        return import.meta.url === scriptUrl.href;
+    }
+    catch {
+        return false;
+    }
+}
+export { main, parseArgs, parseAuth };

package/dist/conformance-host.d.ts

@@ -0,0 +1,155 @@
+/**
+ * `ConformanceHost` — the seam between the kit's authored fixtures
+ * and the implementation under test.
+ *
+ * Most fixtures declare `setup` / `teardown` directives (see
+ * {@link SetupStep} / {@link TeardownStep} in `./types`) that the host
+ * dispatches against its live server. v1.0 of the kit does NOT
+ * require implementations to ship a host — fixtures that need setup
+ * directives skip cleanly when `runConformance()` is called without
+ * a `host`.
+ *
+ * When a host IS provided, the runner calls `dispatchSetup()` for
+ * every step before driving the fixture's `inputEnvelope`, then
+ * `dispatchTeardown()` for every step after the assertion. Unknown
+ * `kind` values MUST throw so unimplemented directives surface as a
+ * test SKIP with a clear "host does not implement X" reason — never
+ * a silent pass.
+ *
+ * ## Extensibly-closed
+ *
+ * The concrete step vocabulary below mirrors `./types`' vocabulary
+ * but is re-exported here as a host-facing narrower form:
+ *   - Every arm carries the full semantic payload (not the JSON-
+ *     loader's `unknown`-fields view).
+ *   - The tail `(Record<string, unknown> & { readonly kind: string & {} })`
+ *     catches fixture-JSON directives the host hasn't wired — the host
+ *     returns by throwing, the runner maps it to a skip.
+ *
+ * Third-party hosts MAY extend either union with additional arms by
+ * augmenting the declaration in their own module. v1.0 of the kit
+ * does not require exhaustive coverage — it requires *honest*
+ * coverage: either implement the directive OR throw, never silently
+ * succeed on an unknown kind.
+ *
+ * ## Relation to `./types`
+ *
+ * `./types` defines the JSON-authoring surface: every directive has
+ * optional-by-default fields so JSON authors don't have to think
+ * about shape. This module defines the *runtime* surface: once the
+ * loader has validated a directive, the host receives a narrowed
+ * form. The two are intentionally parallel but not identical — JSON
+ * loaders accept what the author wrote; hosts receive what the
+ * runner confirmed is shape-valid.
+ */
+/**
+ * Setup directive the host dispatches BEFORE a fixture's input
+ * envelope drives the system under test.
+ *
+ * Extensibly-closed: a host that receives a `kind` it doesn't
+ * recognize MUST throw `Error('conformance-host: unknown setup kind: <kind>')`
+ * so the runner records the fixture as SKIPPED with that reason —
+ * never silently succeed.
+ */
+export type SetupStep = CreateSessionSetup | RegisterToolSetup | RegisterActionSpecSetup | EmitEnvelopeSetup | RendererUrlOverrideSetup | UiInitializeResponseOverrideSetup | ServerVersionOverrideSetup | UnknownSetupStep;
+export interface CreateSessionSetup {
+    readonly kind: 'create-session';
+    readonly sessionId: string;
+    readonly appId?: string;
+}
+/**
+ * Register a tool on the session by symbolic handler name. Known
+ * handlers the reference implementation supports:
+ *   - `'echo'`     — returns `{received: args}`.
+ *   - `'throw'`    — rejects with `Error('tool_threw_for_fixture')`.
+ *   - `'timeout'`  — never resolves; runner times out per policy.
+ *   - `'malformed'`— returns `{wrong:'shape'}` to exercise
+ *                    `SCHEMA_VIOLATION`.
+ */
+export interface RegisterToolSetup {
+    readonly kind: 'register-tool';
+    readonly name: string;
+    readonly handler: 'echo' | 'throw' | 'timeout' | 'malformed' | (string & {});
+}
+export interface RegisterActionSpecSetup {
+    readonly kind: 'register-actionspec';
+    readonly name: string;
+    readonly tool: string;
+}
+export interface EmitEnvelopeSetup {
+    readonly kind: 'emit-envelope';
+    readonly channel: string;
+    readonly payload: unknown;
+}
+export interface RendererUrlOverrideSetup {
+    readonly kind: 'renderer-url-override';
+    readonly url: string;
+}
+export interface UiInitializeResponseOverrideSetup {
+    readonly kind: 'ui-initialize-response-override';
+    readonly response: unknown;
+}
+export interface ServerVersionOverrideSetup {
+    readonly kind: 'server-version-override';
+    readonly version: string;
+}
+/**
+ * Future-compat catch. A host that reaches this arm MUST throw rather
+ * than return silently — the runner interprets the throw as a skip
+ * with the error message as the reason.
+ */
+export type UnknownSetupStep = Record<string, unknown> & {
+    readonly kind: string & {};
+};
+export type TeardownStep = CloseSessionTeardown | UnregisterToolTeardown | UnknownTeardownStep;
+export interface CloseSessionTeardown {
+    readonly kind: 'close-session';
+    readonly sessionId: string;
+}
+export interface UnregisterToolTeardown {
+    readonly kind: 'unregister-tool';
+    readonly name: string;
+}
+export type UnknownTeardownStep = Record<string, unknown> & {
+    readonly kind: string & {};
+};
+/**
+ * Adapter the implementation under test provides to the runner. An
+ * implementation MAY:
+ *
+ *   - Implement every directive the kit authors (full coverage — the
+ *     reference `@ggui-ai/mcp-server`-backed host target).
+ *   - Implement a subset + throw on unknown kinds (partial coverage
+ *     — the kit records unimplemented directives as SKIPPED rather
+ *     than failed).
+ *   - Not be provided at all (the runner drops every fixture with a
+ *     non-empty `setup` or `teardown` as skip-with-reason).
+ *
+ * The runner invokes `dispatchSetup()` once per setup step, in order,
+ * before driving the fixture's `inputEnvelope`; invokes
+ * `dispatchTeardown()` once per teardown step, in order, after the
+ * assertion (pass or fail). Teardown runs unconditionally — the host
+ * is responsible for its own idempotency under partial setup.
+ *
+ * Throwing from either dispatcher is the signal for "I don't
+ * implement this directive" — the runner records the fixture as
+ * SKIPPED with the error's `message` as the skip reason. A host MUST
+ * NOT treat a fixture as passed after throwing from setup — the
+ * runner does not call the assertion if setup throws.
+ */
+export interface ConformanceHost {
+    /**
+     * Dispatch one setup step. Throws `Error` to signal "directive not
+     * implemented" — the runner maps this to a skip with the error's
+     * message as the skip reason. Throws are NOT treated as failures.
+     */
+    dispatchSetup(step: SetupStep): Promise<void>;
+    /**
+     * Dispatch one teardown step. Same contract as `dispatchSetup`.
+     * Teardown errors do NOT flip a passed fixture to failed — they
+     * emit a warning-level event to the reporter so operators can see
+     * the cleanup gap without corrupting the pass/fail tally.
+     */
+    dispatchTeardown(step: TeardownStep): Promise<void>;
+}
+//# sourceMappingURL=conformance-host.d.ts.map

package/dist/conformance-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance-host.d.ts","sourceRoot":"","sources":["../src/conformance-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,wBAAwB,GACxB,iCAAiC,GACjC,0BAA0B,GAC1B,gBAAgB,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC;CAC5B,CAAC;AAMF,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,mBAAmB,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC;CAC5B,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD"}