feat(sdk): @punktfunk/host — the Effect TypeScript SDK (M3)

New top-level sdk/ package (RFC §7): a typed management-API client plus
the lifecycle event stream, built on Effect, two surfaces over one core:

- @punktfunk/host — the Promise facade front door: connect() resolves
  URL/token/TLS pin from the host's own files (zero config on the box),
  fails fast on bad credentials, pf.events.on() with typed callbacks
  (exact kinds, domain.* prefixes, "*", "dropped", "unknown"),
  pf.request() for the REST surface. Effect never required.
- @punktfunk/host/effect — the PunktfunkHost service + PunktfunkHostLive
  layer, Stream-based events()/eventsRaw(), typed errors
  (AuthError | ApiError | TransportError | VersionSkew — a 2xx that
  fails its schema is a typed skew, not undefined later), and every
  wire shape as an effect/Schema: REST generated via orval
  client:'effect' from api/openapi.json (S3 spike: works well; the
  text/event-stream payload is out of its reach), events hand-mirrored
  from the host's snapshot-tested wire format as a kind-discriminated
  union.

One reconnecting SSE core under both surfaces: spec-shaped parser,
exponential+jittered backoff (capped, resets after a healthy
connection), Last-Event-ID resume, 401 terminal. Default is LIVE tail
only — a fresh notify script must not re-fire on the host's replayed
ring (since: 0 opts into full replay).

TLS: the pin trusts exactly the host's self-signed identity cert
(chain-verified; hostname check waived — the cert is deliberately
CN-only for fingerprint pinning). Bun via fetch tls, Node via an undici
dispatcher (optionalDependency).

definePlugin() accepts both main shapes (async fn | Effect requiring
PunktfunkHost). Examples in both styles; README carries the compat
contract + systemd/Task Scheduler templates.

11 bun tests green (wire decode against the Rust snapshot strings,
SSE parser/reconnect/Last-Event-ID/401, both surfaces vs a mock host).
Live-verified against a real host on Bun AND Node through the pinned
loopback hop: connect → REST mutate → live event received → resume
cursor advanced; a wrong CA is rejected. npm publish + CI wiring
deferred (npm org = RFC open question 1).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sdk/test/wire.test.ts

@@ -0,0 +1,63 @@
+// The wire schemas must decode EXACTLY what the host emits — the JSON literals here are the
+// Rust side's snapshot-test strings (crates/punktfunk-host/src/events.rs), the schema gate.
+import { describe, expect, test } from "bun:test";
+import { decodeHostEvent, kindMatches } from "../src/wire.js";
+
+describe("wire", () => {
+	test("decodes the host's snapshot frames", () => {
+		const stream = decodeHostEvent(
+			JSON.parse(
+				'{"seq":4182,"ts_ms":1700000000000,"schema":1,"kind":"stream.started","stream":{"mode":"3840x2160@120","hdr":true,"client":"Living Room TV","app":"steam:570","plane":"native"}}',
+			),
+		);
+		expect(stream._tag).toBe("Right");
+		if (stream._tag === "Right" && stream.right.kind === "stream.started") {
+			expect(stream.right.stream.mode).toBe("3840x2160@120");
+			expect(stream.right.stream.app).toBe("steam:570");
+		}
+
+		const disc = decodeHostEvent(
+			JSON.parse(
+				'{"seq":1,"ts_ms":1700000000000,"schema":1,"kind":"client.disconnected","client":{"name":"Deck","fingerprint":"b1c2","plane":"gamestream"},"reason":"timeout"}',
+			),
+		);
+		expect(disc._tag).toBe("Right");
+		if (disc._tag === "Right" && disc.right.kind === "client.disconnected") {
+			expect(disc.right.reason).toBe("timeout");
+		}
+
+		const stopping = decodeHostEvent(
+			JSON.parse('{"seq":2,"ts_ms":1700000000000,"schema":1,"kind":"host.stopping"}'),
+		);
+		expect(stopping._tag).toBe("Right");
+	});
+
+	test("tolerates unknown keys (additive-only wire)", () => {
+		const r = decodeHostEvent({
+			seq: 9,
+			ts_ms: 1,
+			schema: 1,
+			kind: "library.changed",
+			source: "manual",
+			future_field: { anything: true },
+		});
+		expect(r._tag).toBe("Right");
+	});
+
+	test("unknown kinds fail decode (they ride the raw channel)", () => {
+		const r = decodeHostEvent({
+			seq: 9,
+			ts_ms: 1,
+			schema: 1,
+			kind: "totally.new",
+		});
+		expect(r._tag).toBe("Left");
+	});
+
+	test("kindMatches mirrors the host filter semantics", () => {
+		expect(kindMatches("stream.started", "stream.started")).toBe(true);
+		expect(kindMatches("stream.*", "stream.stopped")).toBe(true);
+		expect(kindMatches("stream.*", "streamx.started")).toBe(false);
+		expect(kindMatches("stream.started", "stream.stopped")).toBe(false);
+	});
+});