feat(sdk): Effect v4 + @effect/openapi-generator; typed pf.api & example ladder

Drop Orval for the first-party @effect/openapi-generator (OpenAPI 3.1 ->
Effect Schema + a typed HttpClient client) and bump effect 3.19 ->
4.0.0-beta.98. Port the hand-written surfaces to the v4 API (Result over
Either, Context.Service, Codec, Literals/Union arrays, Stream/Schedule/
Effect renames). Transport (CA-pinning fetch) and the reconnecting SSE
source are kept intact.

Make the SDK approachable for non-Effect users:
- Add pf.api.* on the Promise facade: the generated client surfaced as
  typed, Promise-native methods (await pf.api.listPairedClients()), so REST
  calls are autocompleted and checked instead of stringly-typed
  pf.request(method, path, body) + `as` casts. Zero-drift veneer over
  make(httpClient), backed by the same pinning fetch. pf.request stays as
  the untyped escape hatch.
- Re-tier examples into a 1-4 complexity ladder, rewritten onto pf.api.*
  (the typed payloads caught a wrong `launch` shape in provider-sync);
  the Effect example is labelled advanced. Add examples/ to tsconfig so
  they are typechecked (stops rot).

typecheck + 19 tests green.

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

sdk/src/client.ts

@@ -8,7 +8,7 @@ import {
 	Data,
 	Effect,
 	Layer,
-	Option,
+	Result,
 	Schema as S,
 	Stream,
 } from "effect";
@@ -62,7 +62,7 @@ export interface PunktfunkHostService {
 	/** GET + schema-validate (the generated schemas from `@punktfunk/host/effect`'s `api`). */
 	readonly get: <A, I>(
 		path: string,
-		schema: S.Schema<A, I>,
+		schema: S.Codec<A, I>,
 	) => Effect.Effect<A, RequestError | VersionSkew>;
 	/**
 	 * The lifecycle-event stream: decoded [`HostEvent`]s with automatic reconnect +
@@ -78,10 +78,10 @@ export interface PunktfunkHostService {
 	) => Stream.Stream<SseFrame, EventStreamError>;
 }
 
-export class PunktfunkHost extends Context.Tag("@punktfunk/host/PunktfunkHost")<
+export class PunktfunkHost extends Context.Service<
 	PunktfunkHost,
 	PunktfunkHostService
->() {}
+>()("@punktfunk/host/PunktfunkHost") {}
 
 const toRequestError = (path: string, cause: unknown): RequestError => {
 	if (cause instanceof HttpStatusError) {
@@ -98,10 +98,10 @@ export const makeService = (cfg: ResolvedConfig): PunktfunkHostService => {
 			try: () => httpRequest(cfg, method, path, body),
 			catch: (cause) => toRequestError(path, cause),
 		});
-	const get = <A, I>(path: string, schema: S.Schema<A, I>) =>
+	const get = <A, I>(path: string, schema: S.Codec<A, I>) =>
 		request("GET", path).pipe(
 			Effect.flatMap((body) =>
-				S.decodeUnknown(schema)(body).pipe(
+				S.decodeUnknownEffect(schema)(body).pipe(
 					Effect.mapError(
 						(e) => new VersionSkew({ path, issue: String(e) }),
 					),
@@ -119,29 +119,32 @@ export const makeService = (cfg: ResolvedConfig): PunktfunkHostService => {
 	const events = (opts?: EventStreamOptions) => {
 		const warn =
 			opts?.onWarning ?? ((m: string) => console.warn(`[punktfunk] ${m}`));
+		// Drop-or-emit per frame. v4's `Stream.filterMap` wants a `Filter`; flat-mapping to
+		// `Stream.empty` (drop) / `Stream.succeed` (emit) expresses the same in stable
+		// primitives and keeps the `warn` side effects exactly where they were.
 		return eventsRaw(opts).pipe(
-			Stream.filterMap((frame) => {
+			Stream.flatMap((frame) => {
 				if (frame.event === "dropped") {
 					warn(
 						"event cursor fell off the host's ring — resync via the REST snapshots",
 					);
-					return Option.none();
+					return Stream.empty;
 				}
 				let json: unknown;
 				try {
 					json = JSON.parse(frame.data);
 				} catch {
 					warn(`unparseable event frame (${frame.event})`);
-					return Option.none();
+					return Stream.empty;
 				}
 				const decoded = decodeHostEvent(json);
-				if (decoded._tag === "Left") {
+				if (Result.isFailure(decoded)) {
 					// An unknown kind from a NEWER host is expected (additive-only wire) —
 					// it rides the raw channel; a consumer that wants it uses eventsRaw.
 					warn(`unknown/undecodable event kind "${frame.event}"`);
-					return Option.none();
+					return Stream.empty;
 				}
-				return Option.some(decoded.right);
+				return Stream.succeed(decoded.success);
 			}),
 		);
 	};