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

package/dist/render.d.ts

@@ -1,62 +1,102 @@
 /**
- * In-memory render store for the reference server.
+ * In-memory GguiSession store for the reference server.
  *
- * Renders are ephemeral and process-local — this is the whole
+ * GguiSessions are ephemeral and process-local — this is the whole
  * point of the reference server. Persistence is explicitly out of
  * scope. Restart drops state; that's documented behavior, not a TODO.
  *
- * Each render carries an actionSpec map that the `register-actionspec`
- * ConformanceHost directive populates. The action router
- * (`./action-router.ts`) consults this map at dispatch time to
- * resolve action-name → tool-name → handler.
+ * Each GguiSession carries:
+ *   - an optional declared `actionSpec` (installed by the
+ *     `create-session` ConformanceHost directive) — the action
+ *     handler (`./action-router.ts`) enforces the declared-action
+ *     contract (name membership + per-entry payload schema) for
+ *     inbound `data:submit` envelopes against it;
+ *   - an event ledger (the consume buffer) — appended actions get a
+ *     monotonic per-session `sequence` the action ack echoes back;
+ *   - an outbound stream-sequence cursor — the `emit-envelope`
+ *     ConformanceHost directive stamps `StreamEnvelope.seq` on
+ *     injected `{type:'data'}` frames from it;
+ *   - an optional persisted `hostContext` — the
+ *     `host_context_observed` Client→Server handler
+ *     (`./host-context.ts`) overwrites it with the iframe-observed
+ *     `HostContextProjection`; the ConformanceHost's
+ *     `readSessionField` seam reads it back for `session-state`
+ *     grading.
  *
  * Wire-shape note: the conformance kit drives the reference server
- * over the SPEC §12.2 wire using the field name `sessionId` (its
- * fixture catalog has not yet been migrated to the canonical
- * `renderId`). The reference server READS that wire field and binds
- * it to a `renderId` internally — the value is a render identity
- * regardless of which spelling the consumer sends.
+ * over the SPEC §12.2 wire using the canonical render-identity field
+ * `sessionId`.
  */
+import type { ActionSpec, HostContextProjection } from '@ggui-ai/protocol';
 /**
- * Actionspec entry maps an action name (the value wired into DOM
- * `data-ggui-action` attributes on real UIs; here sent verbatim on
- * the fixture's inputEnvelope) to the registered tool name the
- * router should dispatch to.
+ * Deployment-level default app id — this server's identity-default
+ * (SPEC §12.2: a subscribe MAY omit `appId`; the server resolves the
+ * caller's identity-default app). The reference server's identity
+ * model is no-auth — every caller is the same anonymous identity — so
+ * the per-identity mapping a real deployment configures collapses to
+ * one deployment-wide constant. The value matches the conformance
+ * kit's conventional tenant (`'conformance'`, the appId the kit's
+ * runner stamps on its subscribe frames) because grading by the kit is
+ * the only deployment context this package has.
  */
-export interface ActionSpecEntry {
-    readonly name: string;
-    readonly tool: string;
-}
+export declare const DEPLOYMENT_DEFAULT_APP_ID = "conformance";
 /**
- * Streamspec entry binds a stream channel to a "refresh tool" — the
- * tool the action-router invokes after a successful wired-action
- * dispatch to produce the channel's next snapshot. Mirrors the real
- * `streamSpec[channel].tool` shape declared by ggui blueprints (SPEC
- * §2.3 StreamSpec refresh triggers): a wired action mutates state,
- * the refresh tool reads fresh state, the stream-update wraps the
- * read into an envelope on the named channel.
- *
- * Reference-server scope: refresh-tool invocation is unconditional
- * — every successful wired-action dispatch fans out through every
- * registered streamSpec for the render. Real ggui servers may
- * filter by which actions touch which channels; the reference
- * server's narrower contract is "any successful action triggers all
- * declared refreshes", which is sufficient for the kit's
- * `stream-refresh-success` proof and stays under the package's
- * 20–50 LOC budget for refresh-stream support.
+ * One appended consume-buffer event. The ledger is the reference
+ * server's stand-in for a real ggui server's persisted event store —
+ * `sequence` is assigned at append time, starts at 1, and increases
+ * monotonically per session. The agent-side drain (`ggui_consume`) is
+ * an MCP surface this WS-only server does not implement; the ledger
+ * exists so the ack's `payload.sequence` is a real persistence proof,
+ * not a fabricated counter.
  */
-export interface StreamSpecEntry {
-    readonly channel: string;
-    readonly tool: string;
+export interface SessionEvent {
+    readonly sequence: number;
+    /** Event type, e.g. `'user.submitted'` for inbound actions. */
+    readonly type: string;
+    /** The appended envelope body, verbatim. */
+    readonly data: unknown;
 }
-export interface Render {
-    readonly renderId: string;
+export interface GguiSession {
+    readonly sessionId: string;
     readonly appId: string;
-    readonly actionSpecs: Map<string, ActionSpecEntry>;
-    readonly streamSpecs: Map<string, StreamSpecEntry>;
+    /**
+     * Declared actionSpec — the protocol's `ActionSpec` (action name →
+     * `ActionEntry`, including each entry's optional payload `schema`).
+     * `undefined` means no contract is declared and the action handler
+     * accepts every action (mirroring the first-party
+     * `assertActionContract` no-op on undeclared specs). Installed by
+     * the `create-session` directive's `actionSpec` field (the
+     * ConformanceHost adapter maps the kit's declaration onto the
+     * protocol type); never mutated after install.
+     */
+    actionSpec?: ActionSpec;
+    /** Consume-buffer event ledger. Append via {@link appendEvent}. */
+    readonly events: SessionEvent[];
+    /**
+     * Outbound stream-delivery sequence cursor — the `seq` stamped on
+     * the most recent `{type:'data'}` StreamEnvelope emitted for this
+     * render. Starts at 0 (nothing emitted yet); advanced by
+     * {@link GguiSessionStore.nextStreamSeq}. Per-render and monotonic,
+     * mirroring the StreamEnvelope sequencing contract (`seq` starts at
+     * 1, gap-free within a render). Distinct from the consume-buffer
+     * ledger's `sequence` — that counts INBOUND appended actions; this
+     * counts OUTBOUND stream deliveries.
+     */
+    streamSeq: number;
+    /**
+     * Persisted `HostContextProjection` — written by the
+     * `host_context_observed` Client→Server handler
+     * (`./host-context.ts`) as an idempotent overwrite (re-delivery
+     * replaces, never merges). `undefined` until the client's first
+     * observation lands. Read back through the ConformanceHost's
+     * `readSessionField('hostContext')` introspection seam, which is how
+     * the kit's `session-state` fixtures grade the persistence
+     * obligation.
+     */
+    hostContext?: HostContextProjection;
     readonly subscribers: Set<Subscriber>;
     /**
-     * Per-render protocol-version override. When set, the WS subscribe
+     * Per-GguiSession protocol-version override. When set, the WS subscribe
      * + UPGRADE_REQUIRED paths advertise this value in place of the
      * server-instance-level `versionOverride`.
      *
@@ -65,85 +105,109 @@ export interface Render {
      * `server-version-override` setup directive in the conformance host
      * adapter — production code paths leave this `undefined`.
      *
-     * Why per-render, not per-instance: parallel kit fixtures share
+     * Why per-GguiSession, not per-instance: parallel kit fixtures share
      * one `ReferenceServer`. Mutating the instance-level override would
-     * leak across renders; the per-render field scopes the mismatch
+     * leak across GguiSessions; the per-GguiSession field scopes the mismatch
      * to the one fixture that asked for it.
      */
     versionOverride?: string;
 }
 /**
- * Minimal subscriber handle — the action router calls `send()` to
- * emit stream frames (including `_ggui:contract-error`) back to the
- * subscribed WebSocket.
+ * Minimal subscriber handle — the server calls `send()` to emit
+ * frames (acks, errors, stream envelopes) back to the subscribed
+ * WebSocket.
  */
 export interface Subscriber {
     send(frame: unknown): void;
 }
 /**
- * In-memory render store. Wraps a `Map<renderId, Render>` with
+ * Append one event to the session's consume-buffer ledger and return
+ * the monotonic sequence it was assigned. The action handler calls
+ * this BEFORE acking — append-then-ack is the ordering contract the
+ * kit's `action-ack-sequence` fixture grades.
+ */
+export declare function appendEvent(render: GguiSession, event: {
+    readonly type: string;
+    readonly data: unknown;
+}): number;
+/**
+ * In-memory GguiSession store. Wraps a `Map<sessionId, GguiSession>` keyed by sessionId with
  * the operations the ConformanceHost adapter + WS subscribe handler
  * need. No locking — JS single-threaded; all calls originate from
  * the event loop.
  */
-export declare class RenderStore {
+export declare class GguiSessionStore {
     private readonly renders;
     private lastCreated;
-    create(renderId: string, appId: string): Render;
+    create(sessionId: string, appId: string): GguiSession;
     /**
-     * The renderId most recently passed to `create()`. Used by the
-     * ConformanceHost's `register-actionspec` dispatcher — that
-     * directive doesn't carry a renderId in its JSON shape, so the
-     * adapter needs the "most recently created" scope to bind the
-     * actionspec to. This matches the fixture-authoring convention that
-     * create-render always precedes register-actionspec.
+     * The sessionId most recently passed to `create()`. Used by the
+     * ConformanceHost's directive dispatchers whose JSON shapes don't
+     * carry a sessionId (`server-version-override`, `emit-envelope`) —
+     * the adapter scopes them to the "most recently created" render,
+     * matching the fixture-authoring convention that create-session
+     * always precedes the scoped directive.
      */
-    lastCreatedRenderId(): string | undefined;
-    get(renderId: string): Render | undefined;
-    close(renderId: string): boolean;
-    addSubscriber(renderId: string, subscriber: Subscriber): Render;
-    removeSubscriber(renderId: string, subscriber: Subscriber): void;
-    registerActionSpec(renderId: string, entry: ActionSpecEntry): void;
+    lastCreatedSessionId(): string | undefined;
+    get(sessionId: string): GguiSession | undefined;
+    close(sessionId: string): boolean;
+    addSubscriber(sessionId: string, subscriber: Subscriber): GguiSession;
+    removeSubscriber(sessionId: string, subscriber: Subscriber): void;
     /**
-     * Register a stream channel ↔ refresh-tool binding on the named
-     * render. Same "create-if-missing" semantics as
-     * {@link registerActionSpec} so the ConformanceHost adapter can
-     * dispatch this directive before subscribe lands. Keyed by
-     * `entry.channel` — registering the same channel twice replaces
-     * the prior binding, matching the action-spec map's behavior.
+     * Install the declared actionSpec on the named render. Same
+     * "create-if-missing" semantics as the other setters so directive
+     * ordering relative to subscribe doesn't matter. Called by the
+     * `create-session` ConformanceHost directive when the fixture
+     * authors an `actionSpec` — actions are part of the render's
+     * identity, so the declaration rides session creation rather than a
+     * separate registration directive.
      */
-    registerStreamSpec(renderId: string, entry: StreamSpecEntry): void;
+    declareActionSpec(sessionId: string, actionSpec: ActionSpec): void;
     /**
      * Set the per-render protocol-version override. Used by the
      * `server-version-override` ConformanceHost directive — populates
-     * {@link Render.versionOverride} so the WS subscribe handler
+     * {@link GguiSession.versionOverride} so the WS subscribe handler
      * advertises this value (and emits UPGRADE_REQUIRED keyed off it)
-     * for THIS render only, leaving parallel renders on the instance-
+     * for THIS GguiSession only, leaving parallel GguiSessions on the instance-
      * level default.
      *
-     * Same "create-if-missing" semantics as the other register* setters
-     * so directive ordering relative to subscribe doesn't matter.
+     * Same "create-if-missing" semantics as the other setters so
+     * directive ordering relative to subscribe doesn't matter.
+     */
+    setVersionOverride(sessionId: string, version: string): void;
+    /**
+     * Assign the next outbound stream sequence for the named render —
+     * advances {@link GguiSession.streamSeq} and returns the new value
+     * (first assignment = 1). Called by the `emit-envelope`
+     * ConformanceHost directive when stamping the `StreamEnvelope` it
+     * injects. Sequence assignment is emission-scoped, not
+     * delivery-scoped: a frame emitted with zero subscribers attached
+     * still consumes its sequence number, mirroring buffer-backed
+     * servers that assign `seq` at append time regardless of who is
+     * connected.
+     *
+     * Same "create-if-missing" semantics as the other setters so
+     * directive ordering relative to subscribe doesn't matter.
      */
-    setVersionOverride(renderId: string, version: string): void;
+    nextStreamSeq(sessionId: string): number;
     /**
      * Fan out a frame to every subscriber on the named render. Used by
      * the `emit-envelope` ConformanceHost directive — kit fixtures use
      * it to inject WS-observable side-effects (envelopes the server
      * would not normally emit on its own) so the kit can assert
-     * downstream consequences (sequencing, fan-out, observability).
+     * downstream consequences (sequencing, fan-out).
      *
-     * Returns `true` if the render existed and at least one subscriber
-     * received the frame; `false` if the render is unknown OR has no
+     * Returns `true` if the GguiSession existed and at least one subscriber
+     * received the frame; `false` if the GguiSession is unknown OR has no
      * subscribers attached. Caller may use the boolean to log a warning
      * when a fixture's directive-injection lands before any subscribe
      * — the directive then has no observable effect, which is usually
      * a fixture-authoring bug worth surfacing.
      *
      * Subscriber-level send failures (closed socket, etc.) are
-     * swallowed per the same convention as the action router's
-     * `broadcast()` — one bad subscriber must not block fan-out to the
+     * swallowed — one bad subscriber must not block fan-out to the
      * rest.
      */
-    injectFrame(renderId: string, frame: unknown): boolean;
+    injectFrame(sessionId: string, frame: unknown): boolean;
 }
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,WAAW,CAAqB;IAExC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAkB/C;;;;;;;OAOG;IACH,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAIzC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIhC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM;IAM/D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAMhE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAKlE;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAKlE;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3D;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;CAcvD"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAChC;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACvD,MAAM,CAIR;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,WAAW,CAAqB;IAExC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW;IAkBrD;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM,GAAG,SAAS;IAI1C,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI/C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIjC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,WAAW;IAMrE,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAMjE;;;;;;;;OAQG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAKlE;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK5D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAMxC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;CAcxD"}

package/dist/render.js

@@ -1,128 +1,147 @@
 /**
- * In-memory render store for the reference server.
- *
- * Renders are ephemeral and process-local — this is the whole
- * point of the reference server. Persistence is explicitly out of
- * scope. Restart drops state; that's documented behavior, not a TODO.
- *
- * Each render carries an actionSpec map that the `register-actionspec`
- * ConformanceHost directive populates. The action router
- * (`./action-router.ts`) consults this map at dispatch time to
- * resolve action-name → tool-name → handler.
- *
- * Wire-shape note: the conformance kit drives the reference server
- * over the SPEC §12.2 wire using the field name `sessionId` (its
- * fixture catalog has not yet been migrated to the canonical
- * `renderId`). The reference server READS that wire field and binds
- * it to a `renderId` internally — the value is a render identity
- * regardless of which spelling the consumer sends.
+ * Deployment-level default app id — this server's identity-default
+ * (SPEC §12.2: a subscribe MAY omit `appId`; the server resolves the
+ * caller's identity-default app). The reference server's identity
+ * model is no-auth — every caller is the same anonymous identity — so
+ * the per-identity mapping a real deployment configures collapses to
+ * one deployment-wide constant. The value matches the conformance
+ * kit's conventional tenant (`'conformance'`, the appId the kit's
+ * runner stamps on its subscribe frames) because grading by the kit is
+ * the only deployment context this package has.
  */
+export const DEPLOYMENT_DEFAULT_APP_ID = 'conformance';
 /**
- * In-memory render store. Wraps a `Map<renderId, Render>` with
+ * Append one event to the session's consume-buffer ledger and return
+ * the monotonic sequence it was assigned. The action handler calls
+ * this BEFORE acking — append-then-ack is the ordering contract the
+ * kit's `action-ack-sequence` fixture grades.
+ */
+export function appendEvent(render, event) {
+    const sequence = render.events.length + 1;
+    render.events.push({ sequence, type: event.type, data: event.data });
+    return sequence;
+}
+/**
+ * In-memory GguiSession store. Wraps a `Map<sessionId, GguiSession>` keyed by sessionId with
  * the operations the ConformanceHost adapter + WS subscribe handler
  * need. No locking — JS single-threaded; all calls originate from
  * the event loop.
  */
-export class RenderStore {
+export class GguiSessionStore {
     renders = new Map();
     lastCreated;
-    create(renderId, appId) {
-        const existing = this.renders.get(renderId);
+    create(sessionId, appId) {
+        const existing = this.renders.get(sessionId);
         if (existing !== undefined) {
-            this.lastCreated = renderId;
+            this.lastCreated = sessionId;
             return existing;
         }
         const render = {
-            renderId,
+            sessionId,
             appId,
-            actionSpecs: new Map(),
-            streamSpecs: new Map(),
+            events: [],
+            streamSeq: 0,
             subscribers: new Set(),
         };
-        this.renders.set(renderId, render);
-        this.lastCreated = renderId;
+        this.renders.set(sessionId, render);
+        this.lastCreated = sessionId;
         return render;
     }
     /**
-     * The renderId most recently passed to `create()`. Used by the
-     * ConformanceHost's `register-actionspec` dispatcher — that
-     * directive doesn't carry a renderId in its JSON shape, so the
-     * adapter needs the "most recently created" scope to bind the
-     * actionspec to. This matches the fixture-authoring convention that
-     * create-render always precedes register-actionspec.
+     * The sessionId most recently passed to `create()`. Used by the
+     * ConformanceHost's directive dispatchers whose JSON shapes don't
+     * carry a sessionId (`server-version-override`, `emit-envelope`) —
+     * the adapter scopes them to the "most recently created" render,
+     * matching the fixture-authoring convention that create-session
+     * always precedes the scoped directive.
      */
-    lastCreatedRenderId() {
+    lastCreatedSessionId() {
         return this.lastCreated;
     }
-    get(renderId) {
-        return this.renders.get(renderId);
+    get(sessionId) {
+        return this.renders.get(sessionId);
     }
-    close(renderId) {
-        return this.renders.delete(renderId);
+    close(sessionId) {
+        return this.renders.delete(sessionId);
     }
-    addSubscriber(renderId, subscriber) {
-        const render = this.create(renderId, 'conformance');
+    addSubscriber(sessionId, subscriber) {
+        const render = this.create(sessionId, DEPLOYMENT_DEFAULT_APP_ID);
         render.subscribers.add(subscriber);
         return render;
     }
-    removeSubscriber(renderId, subscriber) {
-        const render = this.renders.get(renderId);
+    removeSubscriber(sessionId, subscriber) {
+        const render = this.renders.get(sessionId);
         if (render === undefined)
             return;
         render.subscribers.delete(subscriber);
     }
-    registerActionSpec(renderId, entry) {
-        const render = this.create(renderId, 'conformance');
-        render.actionSpecs.set(entry.name, entry);
-    }
     /**
-     * Register a stream channel ↔ refresh-tool binding on the named
-     * render. Same "create-if-missing" semantics as
-     * {@link registerActionSpec} so the ConformanceHost adapter can
-     * dispatch this directive before subscribe lands. Keyed by
-     * `entry.channel` — registering the same channel twice replaces
-     * the prior binding, matching the action-spec map's behavior.
+     * Install the declared actionSpec on the named render. Same
+     * "create-if-missing" semantics as the other setters so directive
+     * ordering relative to subscribe doesn't matter. Called by the
+     * `create-session` ConformanceHost directive when the fixture
+     * authors an `actionSpec` — actions are part of the render's
+     * identity, so the declaration rides session creation rather than a
+     * separate registration directive.
      */
-    registerStreamSpec(renderId, entry) {
-        const render = this.create(renderId, 'conformance');
-        render.streamSpecs.set(entry.channel, entry);
+    declareActionSpec(sessionId, actionSpec) {
+        const render = this.create(sessionId, DEPLOYMENT_DEFAULT_APP_ID);
+        render.actionSpec = actionSpec;
     }
     /**
      * Set the per-render protocol-version override. Used by the
      * `server-version-override` ConformanceHost directive — populates
-     * {@link Render.versionOverride} so the WS subscribe handler
+     * {@link GguiSession.versionOverride} so the WS subscribe handler
      * advertises this value (and emits UPGRADE_REQUIRED keyed off it)
-     * for THIS render only, leaving parallel renders on the instance-
+     * for THIS GguiSession only, leaving parallel GguiSessions on the instance-
      * level default.
      *
-     * Same "create-if-missing" semantics as the other register* setters
-     * so directive ordering relative to subscribe doesn't matter.
+     * Same "create-if-missing" semantics as the other setters so
+     * directive ordering relative to subscribe doesn't matter.
      */
-    setVersionOverride(renderId, version) {
-        const render = this.create(renderId, 'conformance');
+    setVersionOverride(sessionId, version) {
+        const render = this.create(sessionId, DEPLOYMENT_DEFAULT_APP_ID);
         render.versionOverride = version;
     }
+    /**
+     * Assign the next outbound stream sequence for the named render —
+     * advances {@link GguiSession.streamSeq} and returns the new value
+     * (first assignment = 1). Called by the `emit-envelope`
+     * ConformanceHost directive when stamping the `StreamEnvelope` it
+     * injects. Sequence assignment is emission-scoped, not
+     * delivery-scoped: a frame emitted with zero subscribers attached
+     * still consumes its sequence number, mirroring buffer-backed
+     * servers that assign `seq` at append time regardless of who is
+     * connected.
+     *
+     * Same "create-if-missing" semantics as the other setters so
+     * directive ordering relative to subscribe doesn't matter.
+     */
+    nextStreamSeq(sessionId) {
+        const render = this.create(sessionId, DEPLOYMENT_DEFAULT_APP_ID);
+        render.streamSeq += 1;
+        return render.streamSeq;
+    }
     /**
      * Fan out a frame to every subscriber on the named render. Used by
      * the `emit-envelope` ConformanceHost directive — kit fixtures use
      * it to inject WS-observable side-effects (envelopes the server
      * would not normally emit on its own) so the kit can assert
-     * downstream consequences (sequencing, fan-out, observability).
+     * downstream consequences (sequencing, fan-out).
      *
-     * Returns `true` if the render existed and at least one subscriber
-     * received the frame; `false` if the render is unknown OR has no
+     * Returns `true` if the GguiSession existed and at least one subscriber
+     * received the frame; `false` if the GguiSession is unknown OR has no
      * subscribers attached. Caller may use the boolean to log a warning
      * when a fixture's directive-injection lands before any subscribe
      * — the directive then has no observable effect, which is usually
      * a fixture-authoring bug worth surfacing.
      *
      * Subscriber-level send failures (closed socket, etc.) are
-     * swallowed per the same convention as the action router's
-     * `broadcast()` — one bad subscriber must not block fan-out to the
+     * swallowed — one bad subscriber must not block fan-out to the
      * rest.
      */
-    injectFrame(renderId, frame) {
-        const render = this.renders.get(renderId);
+    injectFrame(sessionId, frame) {
+        const render = this.renders.get(sessionId);
         if (render === undefined)
             return false;
         if (render.subscribers.size === 0)

package/dist/server.d.ts

@@ -1,5 +1,4 @@
-import { RenderStore } from './render.js';
-import { ToolRegistry } from './tool-registry.js';
+import { GguiSessionStore } from './render.js';
 export interface ReferenceServerOptions {
     /** Port to bind. `0` = ephemeral — use {@link ReferenceServer.port}
      *  to read the resolved port after start. */
@@ -31,8 +30,7 @@ export interface ReferenceServerOptions {
     readonly versionOverride?: string;
 }
 export declare class ReferenceServer {
-    readonly renders: RenderStore;
-    readonly tools: ToolRegistry;
+    readonly renders: GguiSessionStore;
     private readonly options;
     private http;
     private wss;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC;iDAC6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,cAAqB;IACrC,QAAQ,CAAC,KAAK,eAAsB;IAEpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,EAAE,sBAAsB;IAS3C;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,4DAA4D;IAC5D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,OAAO,CAAC,gBAAgB;YAoCV,aAAa;IAyC3B,OAAO,CAAC,eAAe;CA4ExB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA+BA,OAAO,EAEL,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACrC;iDAC6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,mBAA0B;IAE1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,EAAE,sBAAsB;IAS3C;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,4DAA4D;IAC5D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,OAAO,CAAC,gBAAgB;IAoCxB,OAAO,CAAC,aAAa;IAyDrB,OAAO,CAAC,eAAe;CA6GxB"}