@ggui-ai/protocol-reference-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/conformance-host.js

@@ -1,123 +1,129 @@
+/**
+ * `ConformanceHost` adapter — wires the `@ggui-ai/protocol-conformance`
+ * setup/teardown directive dispatcher onto this package's
+ * `ReferenceServer` instance.
+ *
+ * Directives split into "implement" and "throw":
+ *
+ *   Implement:
+ *     - create-session            → `renders.create()` (+
+ *       `renders.declareActionSpec()` when the directive carries one,
+ *       mapped onto the protocol's `ActionSpec` — declared entry
+ *       schemas included, via `toReferenceActionSpec`)
+ *     - server-version-override   → `renders.setVersionOverride()`
+ *     - emit-envelope             → wrap the directive's body in the
+ *       SPEC §12.2 channel-3 delivery frame `{type:'data', payload:
+ *       StreamEnvelope}` → `renders.injectFrame()`
+ *
+ *   Throw (kit records SKIP, not FAIL):
+ *     - renderer-url-override     — unimplemented (browser-level)
+ *     - ui-initialize-response-override — unimplemented
+ *
+ * The "throw" set matches the conformance kit's `unmatchable-on-ws`
+ * skip expectations — browser-level fault injection that requires a
+ * richer host harness. Throwing surfaces "directive not implemented"
+ * with the error message as the skip reason.
+ *
+ * Beyond directives, the host implements the kit's `readSessionField`
+ * introspection seam — `session-state` fixtures (stateful obligations
+ * with no wire response, e.g. `host-context-observed-persists`) grade
+ * by reading the GguiSession field back after the observation window.
+ * Readable fields: `hostContext`, `appId` (the tenancy column the
+ * `absent-appid-defaults` fixture grades identity-default resolution
+ * against). Unknown fields throw with a clear message so the kit
+ * records an honest SKIP, never a weakened pass.
+ *
+ * The kit validates every fixture-authored directive against its
+ * closed `SetupStep` vocabulary before dispatch, so this adapter only
+ * ever receives shape-valid steps of a known kind — narrowing is by
+ * the `kind` discriminant; no defensive re-parsing.
+ *
+ * Note: render-termination directive (`close-render`) is intentionally
+ * absent — render lifecycle is implicit (created → active → TTL-expired);
+ * there is no agent-facing close tool, and no kit directive to invoke.
+ */
+import { DEFAULT_STREAM_CHANNEL_MODE, jsonSchemaSchema, makeStreamEnvelope, } from '@ggui-ai/protocol';
+import { DEPLOYMENT_DEFAULT_APP_ID } from './render.js';
 /**
  * Build a `ConformanceHost` bound to the given `ReferenceServer`
  * instance. Pass the return value to `runConformance({host})` to
  * drive the kit against the server.
  *
  * The server MUST be `start()`-ed before the first dispatch — the
- * kit calls `create-render` via `dispatchSetup` before any subscribe,
- * so the render store must be reachable. The caller owns the
+ * kit calls `create-session` via `dispatchSetup` before any subscribe,
+ * so the GguiSession store must be reachable. The caller owns the
  * server lifecycle (`start()` + `stop()`).
  */
 export function createReferenceConformanceHost({ serverInstance, }) {
     return {
         async dispatchSetup(step) {
-            // Discriminant-narrow via explicit casts — the extensibly-closed
-            // `HostUnknownSetupStep` arm (`kind: string & {}`) widens the
-            // discriminant and blocks literal-narrowing on the union.
-            if (step.kind === 'create-render') {
-                const s = step;
-                serverInstance.renders.create(s.renderId, s.appId ?? 'conformance');
-                return;
-            }
-            if (step.kind === 'register-tool') {
-                // Fixture JSON authors the field as `toolName`; the kit's
-                // runtime narrowing (`run-conformance.ts::narrowSetupStep`)
-                // only renames `type → kind` and passes other fields verbatim,
-                // so the runtime object carries `toolName` not `name`.
-                // Tolerate both for forward-compat with a kit fix.
-                const raw = step;
-                const toolName = raw.toolName ?? raw.name;
-                if (typeof toolName !== 'string' || toolName.length === 0) {
-                    throw new Error(`register-tool directive missing toolName/name: ${JSON.stringify(step)}`);
+            if (step.kind === 'create-session') {
+                serverInstance.renders.create(step.sessionId, step.appId ?? DEPLOYMENT_DEFAULT_APP_ID);
+                if (step.actionSpec !== undefined) {
+                    serverInstance.renders.declareActionSpec(step.sessionId, toReferenceActionSpec(step.actionSpec));
                 }
-                serverInstance.tools.register(toolName, raw.handler);
                 return;
             }
-            if (step.kind === 'register-actionspec') {
-                const s = step;
-                // register-actionspec doesn't carry a renderId in the
-                // directive shape — it's scoped to the most-recently-created
-                // render, matching the fixture-authoring convention that
-                // create-render → register-tool → register-actionspec all
-                // land in order on the same render.
-                const lastRenderId = serverInstance.renders.lastCreatedRenderId();
-                if (lastRenderId === undefined) {
-                    throw new Error('reference-server: register-actionspec invoked before create-render — no render scope to bind to');
-                }
-                serverInstance.renders.registerActionSpec(lastRenderId, {
-                    name: s.name,
-                    tool: s.tool,
-                });
-                return;
-            }
-            if (step.kind === 'register-streamspec') {
-                // register-streamspec is the streamSpec analogue of register-
-                // actionspec — binds a stream channel to a refresh tool. The
-                // kit does not export a `RegisterStreamSpecSetup` type today
-                // (the directive is reference-server-specific scaffolding for
-                // Slice I refresh-stream support); the runtime shape is
-                // narrowed locally, matching the same convention as the
-                // pre-existing `register-tool` branch above. Same most-
-                // recently-created render scoping as register-actionspec.
-                const raw = step;
-                if (typeof raw.channel !== 'string' || raw.channel.length === 0) {
-                    throw new Error(`register-streamspec directive missing channel: ${JSON.stringify(step)}`);
-                }
-                if (typeof raw.tool !== 'string' || raw.tool.length === 0) {
-                    throw new Error(`register-streamspec directive missing tool: ${JSON.stringify(step)}`);
-                }
-                const lastRenderId = serverInstance.renders.lastCreatedRenderId();
-                if (lastRenderId === undefined) {
-                    throw new Error('reference-server: register-streamspec invoked before create-render — no render scope to bind to');
-                }
-                serverInstance.renders.registerStreamSpec(lastRenderId, {
-                    channel: raw.channel,
-                    tool: raw.tool,
-                });
+            if (step.kind === 'server-version-override') {
+                serverInstance.renders.setVersionOverride(step.sessionId, step.advertiseVersion);
                 return;
             }
             if (step.kind === 'emit-envelope') {
-                // The directive carries `channel` + `payload` but no
-                // renderId — it's scoped to the most-recently-created
-                // render, matching the same fixture-authoring convention as
-                // register-actionspec / register-streamspec / server-version-
-                // override (the kit's `narrowSetupStep` is a flat `type → kind`
-                // rename pass-through, so any renderId on the directive JSON
-                // would survive, but the canonical EmitEnvelopeSetup shape
-                // doesn't declare one).
-                //
-                // Wire-format wrapping: the directive's `payload: unknown` is
-                // the envelope body; the host wraps it in the SPEC §12.2
-                // `{type:'stream', payload:{channel, value}}` shape (matching
-                // the existing reference-server stream emissions in
-                // action-router.ts) before fan-out. Per the kit type docstring,
-                // "Host is responsible for wrapping in the wire format
-                // (sequence stamp, timestamp, etc.)" — the kit does NOT
-                // expect the directive to carry a fully-formed wire frame.
-                const s = step;
-                if (typeof s.channel !== 'string' || s.channel.length === 0) {
+                // The directive carries `channel` + `payload` but no sessionId
+                // — it's scoped to the most-recently-created render (the
+                // fixture-authoring convention is that `create-session`
+                // immediately precedes it).
+                if (step.channel.length === 0) {
                     throw new Error(`emit-envelope directive missing channel: ${JSON.stringify(step)}`);
                 }
-                const lastRenderId = serverInstance.renders.lastCreatedRenderId();
-                if (lastRenderId === undefined) {
-                    throw new Error('reference-server: emit-envelope invoked before create-render — no render scope to bind to');
+                // The directive types `payload` as `unknown` (opaque to the
+                // runner) but `StreamEnvelope.payload` is `JsonValue`.
+                // Fixture-sourced bodies are JSON by construction; direct host
+                // embedders could pass anything — validate, never cast.
+                const body = step.payload;
+                if (!isJsonValue(body)) {
+                    throw new Error('emit-envelope payload must be a JSON value (string / finite number / boolean / null / array / object)');
+                }
+                const sessionId = serverInstance.renders.lastCreatedSessionId();
+                if (sessionId === undefined) {
+                    throw new Error('reference-server: emit-envelope invoked before create-session — no render scope to bind to');
                 }
-                const fanned = serverInstance.renders.injectFrame(lastRenderId, {
-                    type: 'stream',
-                    payload: {
-                        channel: s.channel,
-                        value: s.payload,
-                    },
+                // Wire-format wrapping: the directive's `payload` is the
+                // envelope body; the host wraps it in the SPEC §12.2 channel-3
+                // delivery frame `{type:'data', payload: StreamEnvelope}`
+                // before fan-out. Per the kit directive contract, the host
+                // owns the wire framing — sequence stamp + schema-version
+                // stamp included:
+                //   - `mode`: the server declares no streamSpec, so each
+                //     delivery carries the protocol's declared default.
+                //   - `seq`: per-render monotonic outbound cursor, assigned at
+                //     emission time (mirrors buffer-backed servers that assign
+                //     `seq` at append, regardless of who is subscribed).
+                //   - `schemaVersion`: the version this server advertises for
+                //     THIS render — same per-render-override precedence the
+                //     subscribe handler uses.
+                const envelope = makeStreamEnvelope({
+                    sessionId,
+                    channel: step.channel,
+                    mode: DEFAULT_STREAM_CHANNEL_MODE,
+                    payload: body,
+                    seq: serverInstance.renders.nextStreamSeq(sessionId),
+                    schemaVersion: serverInstance.renders.get(sessionId)?.versionOverride ??
+                        serverInstance.advertisedVersion,
+                });
+                const fanned = serverInstance.renders.injectFrame(sessionId, {
+                    type: 'data',
+                    payload: envelope,
                 });
                 if (!fanned) {
                     // No subscribers attached — the directive's emission is
                     // unobservable. Surface for fixture-authoring debuggability
-                    // (the canonical sequence is create-render → subscribe →
+                    // (the canonical sequence is create-session → subscribe →
                     // emit-envelope; fixtures that swap order silently lose the
                     // injection). Not a throw — the directive itself succeeded;
                     // the unobservability is a fixture concern.
                     // eslint-disable-next-line no-console
-                    console.warn(`[@ggui-ai/protocol-reference-server] emit-envelope on render '${lastRenderId}' channel '${s.channel}' had no subscribers — frame dropped`);
+                    console.warn(`[@ggui-ai/protocol-reference-server] emit-envelope on render '${sessionId}' channel '${step.channel}' had no subscribers — frame dropped`);
                 }
                 return;
             }
@@ -127,54 +133,100 @@ export function createReferenceConformanceHost({ serverInstance, }) {
             if (step.kind === 'ui-initialize-response-override') {
                 throw new Error('reference server does not implement ui-initialize-response-override — MCP Apps host concern, out of scope');
             }
-            if (step.kind === 'server-version-override') {
-                // Fixture JSON authors `advertiseVersion` (matches the
-                // semantic — "advertise this version on the wire"); the kit's
-                // exported `ServerVersionOverrideSetup` interface uses
-                // `version`. Tolerate both for forward-compat with the kit's
-                // own type, mirroring the same name-tolerance pattern in
-                // register-tool above. The runtime `narrowSetupStep` only
-                // renames `type → kind` and passes other fields verbatim, so
-                // whichever the fixture authors arrives unchanged.
-                const raw = step;
-                const advertise = raw.advertiseVersion ?? raw.version;
-                if (typeof advertise !== 'string' || advertise.length === 0) {
-                    throw new Error(`server-version-override directive missing advertiseVersion/version: ${JSON.stringify(step)}`);
-                }
-                // Same most-recently-created render scope as register-
-                // actionspec / register-streamspec — the fixture authoring
-                // convention is `create-render` immediately precedes this
-                // directive, and the kit's narrowSetupStep doesn't surface a
-                // renderId on the directive object even when the fixture
-                // JSON includes one (only `type → kind` is renamed; the rest
-                // is a flat passthrough, so a `renderId` field WOULD survive
-                // — but the canonical ServerVersionOverrideSetup type doesn't
-                // declare one, so fixtures may omit it. Falling back to
-                // `lastCreatedRenderId()` keeps the host robust to either.
-                const lastRenderId = serverInstance.renders.lastCreatedRenderId();
-                if (lastRenderId === undefined) {
-                    throw new Error('reference-server: server-version-override invoked before create-render — no render scope to bind to');
-                }
-                serverInstance.renders.setVersionOverride(lastRenderId, advertise);
-                return;
-            }
-            // Unknown kind — extensibly-closed. Throw so the kit records
-            // SKIP with an honest reason.
-            const unknownKind = step.kind ?? 'unknown';
-            throw new Error(`reference server does not implement setup kind '${String(unknownKind)}'`);
+            return unreachableSetupStep(step);
         },
-        async dispatchTeardown(step) {
-            if (step.kind === 'unregister-tool') {
-                // Same toolName/name tolerance as register-tool.
-                const raw = step;
-                const toolName = raw.toolName ?? raw.name;
-                if (typeof toolName === 'string' && toolName.length > 0) {
-                    serverInstance.tools.unregister(toolName);
-                }
-                return;
+        async readSessionField(sessionId, field) {
+            // Honest-grade contract: return the GguiSession's TRUE
+            // post-dispatch state. A render that never received the
+            // observation message returns `undefined` here — the kit's
+            // deep-equal then FAILS the fixture (a server that drops the
+            // message must not pass), while an unknown field throws so the
+            // kit records a SKIP ("cannot observe" is not "observed and
+            // matched").
+            const render = serverInstance.renders.get(sessionId);
+            if (render === undefined) {
+                throw new Error(`reference server has no GguiSession '${sessionId}' — readSessionField cannot introspect a render that was never created`);
+            }
+            if (field === 'hostContext') {
+                return render.hostContext;
+            }
+            if (field === 'appId') {
+                // The tenancy column on the live render row — the kit's
+                // `absent-appid-defaults` fixture reads it back to grade the
+                // SPEC §12.2 identity-default resolution (a subscribe that
+                // omits `appId` binds the deployment default, never an
+                // undefined tenant).
+                return render.appId;
             }
-            const unknownKind = step.kind ?? 'unknown';
-            throw new Error(`reference server does not implement teardown kind '${String(unknownKind)}'`);
+            throw new Error(`reference server does not expose GguiSession field '${field}' via readSessionField — readable fields: hostContext, appId`);
+        },
+        async dispatchTeardown() {
+            // The kit's teardown vocabulary is empty (`HostTeardownStep` is
+            // `never`) — the runner rejects any fixture-authored teardown
+            // directive before dispatch, so this is statically unreachable
+            // today. Throw so a future kit version that grows a teardown
+            // vocabulary surfaces here as an honest "not implemented"
+            // (reporter warning) rather than a silent success.
+            throw new Error('reference server does not implement any teardown directive');
         },
     };
 }
+/**
+ * Compile-time exhaustiveness lock: the kit's setup vocabulary is a
+ * closed union. When a future kit version adds a directive arm, this
+ * call stops compiling — forcing this host to either implement the
+ * directive or throw "not implemented" explicitly. Silently ignoring
+ * a directive (the fall-through default) is the one behavior the
+ * `ConformanceHost` contract forbids.
+ */
+function unreachableSetupStep(step) {
+    throw new Error(`reference server received a setup directive outside the kit's closed vocabulary: ${JSON.stringify(step)}`);
+}
+/**
+ * Map the kit's declared actionSpec (name → `ActionSpecEntryDecl`)
+ * onto the protocol's `ActionSpec` the server's action router
+ * enforces with (`validateActionData`). `ActionEntry.label` is
+ * required by the protocol type, so the action name doubles as its
+ * label; an entry's declared `schema` installs as the action's
+ * payload contract (`ActionEntry.schema`) through the protocol's
+ * `jsonSchemaSchema` validating parse. A declared schema the
+ * protocol's grammar rejects throws — the kit records the fixture as
+ * SKIPPED — rather than silently downgrading the declaration to
+ * name-membership.
+ */
+function toReferenceActionSpec(decl) {
+    const spec = {};
+    for (const [action, entry] of Object.entries(decl)) {
+        if (entry.schema === undefined) {
+            spec[action] = { label: action };
+            continue;
+        }
+        const parsed = jsonSchemaSchema.safeParse(entry.schema);
+        if (!parsed.success) {
+            throw new Error(`reference server cannot install the entry schema declared on action '${action}' — not a valid protocol JsonSchema node: ${parsed.error.message}`);
+        }
+        spec[action] = { label: action, schema: parsed.data };
+    }
+    return spec;
+}
+/**
+ * Validating narrower: is `value` representable as a protocol
+ * `JsonValue`? Rejects functions, symbols, bigints, `undefined`, and
+ * non-finite numbers anywhere in the tree. Used to gate the
+ * `emit-envelope` directive's opaque body before it's stamped into a
+ * `StreamEnvelope`.
+ */
+function isJsonValue(value) {
+    if (value === null)
+        return true;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (typeof value === 'object') {
+        return Object.values(value).every(isJsonValue);
+    }
+    return false;
+}

package/dist/host-context.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Inbound `host_context_observed` frame handling — parse the canonical
+ * Client→Server observation message and persist its
+ * `HostContextProjection` onto the named GguiSession.
+ *
+ * Obligation (mirrors the first-party `@ggui-ai/mcp-server` channel
+ * handler): the message is fire-and-forget — NO response frame — and
+ * the server persists `payload.hostContext` onto
+ * `GguiSession.hostContext` as an idempotent overwrite (no merge), so
+ * later agent-facing reads (`ggui_handshake` / `ggui_consume` in a
+ * full server) surface the host's capabilities. The conformance kit
+ * grades exactly this persistence: the `host-context-observed-persists`
+ * fixture reads the field back via
+ * `ConformanceHost.readSessionField('hostContext')` after the
+ * observation window and deep-equals it against the authored
+ * projection.
+ *
+ * Trust boundary: the frame crosses the wire, so every field is
+ * re-validated against the protocol's `HostContextProjection` shape
+ * (`@ggui-ai/protocol`, `types/host-context`) before anything is
+ * persisted. Malformed frames — wrong payload shape, mistyped fields,
+ * keys outside the projection vocabulary (e.g. `theme`, which flows
+ * through ggui's theming pipeline, never host context) — drop
+ * silently, matching this server's posture for malformed `action`
+ * frames (`parseActionFrame` returns `undefined`). A dropped frame
+ * persists NOTHING: a partial write from half-valid input would
+ * fabricate state the client never coherently observed.
+ *
+ * Tenancy note: the first-party handler scopes the write through its
+ * subscriber binding (`NOT_SUBSCRIBED` / `SESSION_MISMATCH` error
+ * frames). The reference server has no auth identity by design
+ * (accepts any bearer), so its tenancy scope is the render lookup
+ * itself — the caller drops frames whose `payload.sessionId` names an
+ * unknown render, mirroring the action path's unknown-render posture.
+ */
+import type { HostContextObservedPayload } from '@ggui-ai/protocol';
+import type { GguiSession } from './render.js';
+/**
+ * One inbound `host_context_observed` message — the canonical wire
+ * shape from `@ggui-ai/protocol` (`transport/websocket`):
+ * `{type: 'host_context_observed', payload: {sessionId, hostContext},
+ * requestId?}`.
+ */
+export interface IncomingHostContextObservedMessage {
+    readonly type: 'host_context_observed';
+    readonly requestId?: string;
+    readonly payload: HostContextObservedPayload;
+}
+/**
+ * Parse + validate an inbound `host_context_observed` frame. Returns
+ * the normalized typed message on success, `undefined` on ANY
+ * malformed input — the server drops malformed frames silently (same
+ * posture as {@link parseActionFrame}); fire-and-forget messages have
+ * no rejection channel a conformant client would be listening on.
+ *
+ * Validation is strict against the protocol type: every present
+ * `hostContext` field must carry the projection's shape, and unknown
+ * keys reject the whole frame.
+ */
+export declare function parseHostContextObservedFrame(frame: unknown): IncomingHostContextObservedMessage | undefined;
+/**
+ * Handle one parsed `host_context_observed` message: persist the
+ * validated projection onto the render. Idempotent overwrite — the
+ * protocol declares re-delivery (e.g. after a reconnect) replaces the
+ * stored value with no merge logic. No response frame is emitted; the
+ * obligation is purely stateful and is graded by the kit through the
+ * `readSessionField('hostContext')` introspection seam.
+ */
+export declare function handleHostContextObserved(message: IncomingHostContextObservedMessage, render: GguiSession): void;
+//# sourceMappingURL=host-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.d.ts","sourceRoot":"","sources":["../src/host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EACV,0BAA0B,EAG3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,kCAAkC,GAAG,SAAS,CAgBhD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kCAAkC,EAC3C,MAAM,EAAE,WAAW,GAClB,IAAI,CAEN"}

package/dist/host-context.js

@@ -0,0 +1,139 @@
+import { isRecord } from '@ggui-ai/protocol';
+/**
+ * Parse + validate an inbound `host_context_observed` frame. Returns
+ * the normalized typed message on success, `undefined` on ANY
+ * malformed input — the server drops malformed frames silently (same
+ * posture as {@link parseActionFrame}); fire-and-forget messages have
+ * no rejection channel a conformant client would be listening on.
+ *
+ * Validation is strict against the protocol type: every present
+ * `hostContext` field must carry the projection's shape, and unknown
+ * keys reject the whole frame.
+ */
+export function parseHostContextObservedFrame(frame) {
+    if (!isRecord(frame))
+        return undefined;
+    if (frame['type'] !== 'host_context_observed')
+        return undefined;
+    const requestId = frame['requestId'];
+    if (requestId !== undefined && typeof requestId !== 'string')
+        return undefined;
+    const payload = frame['payload'];
+    if (!isRecord(payload))
+        return undefined;
+    const sessionId = payload['sessionId'];
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return undefined;
+    const hostContext = parseHostContextProjection(payload['hostContext']);
+    if (hostContext === undefined)
+        return undefined;
+    return {
+        type: 'host_context_observed',
+        ...(requestId !== undefined ? { requestId } : {}),
+        payload: { sessionId, hostContext },
+    };
+}
+/**
+ * Handle one parsed `host_context_observed` message: persist the
+ * validated projection onto the render. Idempotent overwrite — the
+ * protocol declares re-delivery (e.g. after a reconnect) replaces the
+ * stored value with no merge logic. No response frame is emitted; the
+ * obligation is purely stateful and is graded by the kit through the
+ * `readSessionField('hostContext')` introspection seam.
+ */
+export function handleHostContextObserved(message, render) {
+    render.hostContext = message.payload.hostContext;
+}
+/**
+ * Validating narrower for the wire `hostContext` body against the live
+ * `HostContextProjection` (`@ggui-ai/protocol`, `types/host-context`).
+ * Every field is optional, so presence is never required — but a
+ * present field MUST carry the projection's shape, and unknown keys
+ * reject the value (returns `undefined`): a key outside the projection
+ * is state no conformant server is obligated to hold, and persisting
+ * it would require erasing the protocol type.
+ */
+function parseHostContextProjection(value) {
+    if (!isRecord(value))
+        return undefined;
+    const out = {};
+    for (const [key, field] of Object.entries(value)) {
+        switch (key) {
+            case 'availableDisplayModes': {
+                if (!Array.isArray(field))
+                    return undefined;
+                const modes = [];
+                for (const item of field) {
+                    if (!isDisplayMode(item))
+                        return undefined;
+                    modes.push(item);
+                }
+                out.availableDisplayModes = modes;
+                break;
+            }
+            case 'currentDisplayMode': {
+                if (!isDisplayMode(field))
+                    return undefined;
+                out.currentDisplayMode = field;
+                break;
+            }
+            case 'containerDimensions': {
+                if (!isRecord(field))
+                    return undefined;
+                const dims = {};
+                for (const [dimKey, dimValue] of Object.entries(field)) {
+                    if (dimKey !== 'width' &&
+                        dimKey !== 'maxWidth' &&
+                        dimKey !== 'height' &&
+                        dimKey !== 'maxHeight') {
+                        return undefined;
+                    }
+                    if (typeof dimValue !== 'number')
+                        return undefined;
+                    dims[dimKey] = dimValue;
+                }
+                out.containerDimensions = dims;
+                break;
+            }
+            case 'platform': {
+                if (field !== 'web' && field !== 'desktop' && field !== 'mobile') {
+                    return undefined;
+                }
+                out.platform = field;
+                break;
+            }
+            case 'deviceCapabilities': {
+                if (!isRecord(field))
+                    return undefined;
+                const caps = {};
+                for (const [capKey, capValue] of Object.entries(field)) {
+                    if (capKey !== 'touch' && capKey !== 'hover')
+                        return undefined;
+                    if (typeof capValue !== 'boolean')
+                        return undefined;
+                    caps[capKey] = capValue;
+                }
+                out.deviceCapabilities = caps;
+                break;
+            }
+            case 'locale': {
+                if (typeof field !== 'string' || field.length === 0)
+                    return undefined;
+                out.locale = field;
+                break;
+            }
+            case 'timeZone': {
+                if (typeof field !== 'string' || field.length === 0)
+                    return undefined;
+                out.timeZone = field;
+                break;
+            }
+            default:
+                return undefined;
+        }
+    }
+    return out;
+}
+function isDisplayMode(value) {
+    return value === 'inline' || value === 'fullscreen' || value === 'pip';
+}

package/dist/index.d.ts

@@ -16,5 +16,6 @@
 export declare const REFERENCE_SERVER_VERSION = "0.1.0";
 export { ReferenceServer } from './server.js';
 export type { ReferenceServerOptions } from './server.js';
+export { DEPLOYMENT_DEFAULT_APP_ID } from './render.js';
 export { createReferenceConformanceHost, type CreateReferenceConformanceHostInput, } from './conformance-host.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAahD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,8BAA8B,EAC9B,KAAK,mCAAmC,GACzC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAahD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAK1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,8BAA8B,EAC9B,KAAK,mCAAmC,GACzC,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -26,4 +26,9 @@ export const REFERENCE_SERVER_VERSION = '0.1.0';
 //     `ConformanceHost` to pass into `runConformance({host})`.
 //   - Throws on unimplemented directives — kit maps them to SKIP.
 export { ReferenceServer } from './server.js';
+// Deployment-level identity-default app id (SPEC §12.2: a subscribe
+// MAY omit `appId`; this no-auth server resolves every caller to this
+// deployment-wide tenant). Exported so external runners can assert
+// the bound default without restating the literal.
+export { DEPLOYMENT_DEFAULT_APP_ID } from './render.js';
 export { createReferenceConformanceHost, } from './conformance-host.js';