4 files changed, 257 insertions, 0 deletions
diff --git a/src/core/protocol/index.ts b/src/core/protocol/index.ts
new file mode 100644
index 0000000..25174ea
--- /dev/null
+++ b/src/core/protocol/index.ts
@@ -0,0 +1,2 @@
+export { applyServerMessage, initialState, invoke, subscribe, unsubscribe } from "./reducer";
+export type { ProtocolResult, ProtocolState } from "./types";
diff --git a/src/core/protocol/reducer.test.ts b/src/core/protocol/reducer.test.ts
new file mode 100644
index 0000000..57e12f2
--- /dev/null
+++ b/src/core/protocol/reducer.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { applyServerMessage, initialState, invoke, subscribe, unsubscribe } from "./reducer";
+
+const makeSpec = (id: string, title = id) => ({
+	id,
+	region: "test",
+	title,
+	fields: [],
+});
+
+describe("initialState", () => {
+	it("returns empty catalog, no subscriptions, no error", () => {
+		const s = initialState();
+		expect(s.catalog).toEqual([]);
+		expect(s.subscriptions.size).toBe(0);
+		expect(s.lastError).toBeNull();
+	});
+});
+
+describe("applyServerMessage — catalog", () => {
+	it("replaces the catalog", () => {
+		const s = initialState();
+		const catalog = [
+			{ id: "a", region: "r", title: "A" },
+			{ id: "b", region: "r", title: "B" },
+		];
+		const next = applyServerMessage(s, { type: "catalog", catalog });
+		expect(next.catalog).toEqual(catalog);
+	});
+});
+
+describe("applyServerMessage — surface", () => {
+	it("sets the spec for a subscribed surface", () => {
+		let s = initialState();
+		const result = subscribe(s, "s1");
+		s = result.state;
+		const spec = makeSpec("s1", "Surface 1");
+		const next = applyServerMessage(s, { type: "surface", spec });
+		expect(next.subscriptions.get("s1")).toEqual(spec);
+	});
+
+	it("ignores a surface message for a non-subscribed surface", () => {
+		const s = initialState();
+		const spec = makeSpec("unknown");
+		const next = applyServerMessage(s, { type: "surface", spec });
+		expect(next.subscriptions.has("unknown")).toBe(false);
+	});
+});
+
+describe("applyServerMessage — update", () => {
+	it("replaces spec for a subscribed surface", () => {
+		let s = initialState();
+		s = subscribe(s, "s1").state;
+		s = applyServerMessage(s, { type: "surface", spec: makeSpec("s1", "V1") });
+		const next = applyServerMessage(s, {
+			type: "update",
+			update: { surfaceId: "s1", spec: makeSpec("s1", "V2") },
+		});
+		expect(next.subscriptions.get("s1")?.title).toBe("V2");
+	});
+
+	it("ignores an update for a non-subscribed surface", () => {
+		const s = initialState();
+		const next = applyServerMessage(s, {
+			type: "update",
+			update: { surfaceId: "nope", spec: makeSpec("nope") },
+		});
+		expect(next.subscriptions.has("nope")).toBe(false);
+	});
+});
+
+describe("applyServerMessage — error", () => {
+	it("records the error without throwing", () => {
+		const s = initialState();
+		const err = { type: "error" as const, surfaceId: "s1", message: "boom" };
+		const next = applyServerMessage(s, err);
+		expect(next.lastError).toEqual(err);
+	});
+
+	it("records error without surfaceId", () => {
+		const s = initialState();
+		const err = { type: "error" as const, message: "global boom" };
+		const next = applyServerMessage(s, err);
+		expect(next.lastError).toEqual(err);
+	});
+});
+
+describe("subscribe", () => {
+	it("emits exactly one subscribe message", () => {
+		const s = initialState();
+		const result = subscribe(s, "s1");
+		expect(result.outgoing).toEqual([{ type: "subscribe", surfaceId: "s1" }]);
+		expect(result.outgoing).toHaveLength(1);
+	});
+
+	it("adds the surface to subscriptions with null spec", () => {
+		const s = initialState();
+		const result = subscribe(s, "s1");
+		expect(result.state.subscriptions.get("s1")).toBeNull();
+	});
+
+	it("is idempotent — second subscribe is a no-op", () => {
+		let s = initialState();
+		s = subscribe(s, "s1").state;
+		const result = subscribe(s, "s1");
+		expect(result.outgoing).toEqual([]);
+		expect(result.state).toBe(s);
+	});
+});
+
+describe("unsubscribe", () => {
+	it("emits unsubscribe and drops the spec", () => {
+		let s = initialState();
+		s = subscribe(s, "s1").state;
+		s = applyServerMessage(s, { type: "surface", spec: makeSpec("s1") });
+		const result = unsubscribe(s, "s1");
+		expect(result.outgoing).toEqual([{ type: "unsubscribe", surfaceId: "s1" }]);
+		expect(result.state.subscriptions.has("s1")).toBe(false);
+	});
+
+	it("is a no-op if not subscribed", () => {
+		const s = initialState();
+		const result = unsubscribe(s, "nope");
+		expect(result.outgoing).toEqual([]);
+		expect(result.state).toBe(s);
+	});
+});
+
+describe("invoke", () => {
+	it("emits the correct InvokeMessage", () => {
+		const s = initialState();
+		const result = invoke(s, "s1", "toggle", true);
+		expect(result.outgoing).toEqual([
+			{ type: "invoke", surfaceId: "s1", actionId: "toggle", payload: true },
+		]);
+	});
+
+	it("omits payload when not provided", () => {
+		const s = initialState();
+		const result = invoke(s, "s1", "click");
+		expect(result.outgoing).toEqual([
+			{ type: "invoke", surfaceId: "s1", actionId: "click", payload: undefined },
+		]);
+	});
+
+	it("does not mutate state", () => {
+		const s = initialState();
+		const result = invoke(s, "s1", "a1");
+		expect(result.state).toBe(s);
+	});
+});
diff --git a/src/core/protocol/reducer.ts b/src/core/protocol/reducer.ts
new file mode 100644
index 0000000..992a918
--- /dev/null
+++ b/src/core/protocol/reducer.ts
@@ -0,0 +1,82 @@
+import type {
+	InvokeMessage,
+	SubscribeMessage,
+	SurfaceServerMessage,
+	UnsubscribeMessage,
+} from "@dispatch/ui-contract";
+import type { ProtocolResult, ProtocolState } from "./types";
+
+/** The initial protocol state: empty catalog, no subscriptions, no error. */
+export function initialState(): ProtocolState {
+	return {
+		catalog: [],
+		subscriptions: new Map(),
+		lastError: null,
+	};
+}
+
+/** Fold an inbound server message into the next protocol state. */
+export function applyServerMessage(state: ProtocolState, msg: SurfaceServerMessage): ProtocolState {
+	switch (msg.type) {
+		case "catalog":
+			return { ...state, catalog: msg.catalog };
+
+		case "surface": {
+			const surfaceId = msg.spec.id;
+			if (!state.subscriptions.has(surfaceId)) return state;
+			const subs = new Map(state.subscriptions);
+			subs.set(surfaceId, msg.spec);
+			return { ...state, subscriptions: subs };
+		}
+
+		case "update": {
+			const surfaceId = msg.update.surfaceId;
+			if (!state.subscriptions.has(surfaceId)) return state;
+			const subs = new Map(state.subscriptions);
+			subs.set(surfaceId, msg.update.spec);
+			return { ...state, subscriptions: subs };
+		}
+
+		case "error":
+			return { ...state, lastError: msg };
+	}
+}
+
+/**
+ * Subscribe to a surface. Idempotent: if already subscribed, returns the same
+ * state with no outgoing message.
+ */
+export function subscribe(state: ProtocolState, surfaceId: string): ProtocolResult {
+	if (state.subscriptions.has(surfaceId)) {
+		return { state, outgoing: [] };
+	}
+	const subs = new Map(state.subscriptions);
+	subs.set(surfaceId, null);
+	const outgoing: SubscribeMessage = { type: "subscribe", surfaceId };
+	return { state: { ...state, subscriptions: subs }, outgoing: [outgoing] };
+}
+
+/**
+ * Unsubscribe from a surface. Drops the local spec and emits one unsubscribe.
+ * If not subscribed, returns the same state with no outgoing.
+ */
+export function unsubscribe(state: ProtocolState, surfaceId: string): ProtocolResult {
+	if (!state.subscriptions.has(surfaceId)) {
+		return { state, outgoing: [] };
+	}
+	const subs = new Map(state.subscriptions);
+	subs.delete(surfaceId);
+	const outgoing: UnsubscribeMessage = { type: "unsubscribe", surfaceId };
+	return { state: { ...state, subscriptions: subs }, outgoing: [outgoing] };
+}
+
+/** Invoke a field's action on a surface. Emits an InvokeMessage; no state change. */
+export function invoke(
+	state: ProtocolState,
+	surfaceId: string,
+	actionId: string,
+	payload?: unknown,
+): ProtocolResult {
+	const outgoing: InvokeMessage = { type: "invoke", surfaceId, actionId, payload };
+	return { state, outgoing: [outgoing] };
+}
diff --git a/src/core/protocol/types.ts b/src/core/protocol/types.ts
new file mode 100644
index 0000000..effec0d
--- /dev/null
+++ b/src/core/protocol/types.ts
@@ -0,0 +1,22 @@
+import type {
+	SurfaceCatalog,
+	SurfaceClientMessage,
+	SurfaceErrorMessage,
+	SurfaceSpec,
+} from "@dispatch/ui-contract";
+
+/** The client-side view of the surface protocol state. */
+export interface ProtocolState {
+	/** The latest catalog received from the server (empty until first CatalogMessage). */
+	readonly catalog: SurfaceCatalog;
+	/** Surfaces the client intends to be subscribed to; null = subscribed but no spec yet. */
+	readonly subscriptions: ReadonlyMap<string, SurfaceSpec | null>;
+	/** The last error received from the server, if any. */
+	readonly lastError: SurfaceErrorMessage | null;
+}
+
+/** A state transition result: the next state plus any outgoing messages to send. */
+export interface ProtocolResult {
+	readonly state: ProtocolState;
+	readonly outgoing: readonly SurfaceClientMessage[];
+}