@native-sdk/core 0.0.0 → 0.5.1

package/sdk/core.ts

@@ -0,0 +1,694 @@
+// @native-sdk/core — the SDK module an app core imports. The subset program
+// maps the "@native-sdk/core" specifier onto this file, so stock tsc types
+// it; the transpiler lowers references to it onto the rt kernel and never
+// emits this module's own code.
+//
+// `Cmd` is the typed-effects surface (spec section 2): `update` (and, since
+// v2, `initialModel`) may return `[model, cmd]`, where the cmd is INERT DATA
+// describing effects for the runtime to perform after the returned model
+// commits. Commands are built only from these factories, and only in that
+// return path (NS1017) — they never live in the Model, in a Msg, in a local,
+// or in a helper.
+//
+// The v2 command set:
+//
+//   Cmd.none                     no effects (what a bare `return model` means)
+//   Cmd.persist()                ask the host to persist the committed model
+//   Cmd.now("tick")              request a timestamp; the runtime dispatches
+//                                the named Msg arm with the time (ms) as its
+//                                single number payload field
+//   Cmd.host(name, ...args)      a host command by name with scalar args —
+//                                the host interprets the name
+//   Cmd.host(name, payload)      the same, carrying one bytes payload — a
+//                                Uint8Array, or a flat record of number /
+//                                boolean / Uint8Array fields that lowers to
+//                                bytes (hostRecordBytes below)
+//   Cmd.request(name, payload,   a routed host command: the host performs it
+//               { key?, ok, err })  and dispatches the `ok` Msg arm with the
+//                                result bytes, or the `err` arm with the error
+//                                bytes — each arm carries exactly one
+//                                Uint8Array payload field, checked by tsc. The
+//                                optional `key` names the in-flight effect:
+//                                re-issuing a live key replaces it, and
+//                                Cmd.cancel(key) drops it.
+//   Cmd.cancel(key)              drop the in-flight keyed effect — request,
+//                                readFile/writeFile/fetch/clipboardRead, or
+//                                delay — SILENTLY (no terminal arm dispatch).
+//                                Aimed at a live spawn it stays LOUD: the
+//                                child dies and the err arm runs with
+//                                "cancelled" — killing a process is an
+//                                observable event
+//   Cmd.batch([a, b, ...])       several commands from one dispatch
+//
+// The named engine ops (each maps onto the host's effect engine directly;
+// routing follows the request rules — string-literal arm names, tsc-checked
+// arm shapes):
+//
+//   Cmd.readFile(path, { key?, ok, err })
+//                                whole-file read; ok arm carries the bytes
+//                                (one Uint8Array field), err arm the reason
+//                                bytes ("not_found", "io_failed", "truncated",
+//                                "rejected")
+//   Cmd.writeFile(path, bytes, { key?, ok, err })
+//                                whole-file write (parents created, replaced
+//                                whole); ok arm carries NOTHING (an arm with
+//                                no payload fields), err arm the reason bytes
+//   Cmd.fetch({ url, method?, headers?, body?, timeoutMs? }, { key?, ok, err })
+//                                buffered HTTP(S) exchange; ok arm carries a
+//                                two-field record — one number field (the real
+//                                HTTP status, non-2xx included) and one
+//                                Uint8Array field (the whole body) — err arm
+//                                the reason bytes ("connect_failed",
+//                                "tls_failed", "protocol_failed", "timed_out",
+//                                "rejected", "truncated")
+//   Cmd.clipboardWrite(bytes)    fire-and-forget clipboard write
+//   Cmd.clipboardRead({ key?, ok, err })
+//                                clipboard read; ok arm carries the text bytes,
+//                                err arm the reason bytes ("failed",
+//                                "rejected")
+//   Cmd.delay(key, ms, "fired")  a keyed ONE-SHOT timer: dispatches the named
+//                                arm once after `ms`, with the fire time (ms)
+//                                as its single number payload; re-issuing a
+//                                live key re-arms from now (debounce), and
+//                                Cmd.cancel(key) drops it silently
+//
+// The streaming ops (one issue, MANY result Msgs across dispatches, a keyed
+// lifecycle the app drives):
+//
+//   Cmd.spawn(argv, { key?, stdin?, line?, exit, err })
+//   Cmd.spawn(argv, { key?, stdin?, collect: true, exit, err })
+//                                run a subprocess. Line mode streams each
+//                                stdout line to the `line` arm (one Uint8Array
+//                                field; omit `line` to drop lines); collect
+//                                mode buffers whole stdout instead. Exactly one
+//                                terminal follows: a clean exit dispatches
+//                                `exit` — line mode: one number field (the exit
+//                                code); collect mode: a two-field record, one
+//                                number (the code) and one Uint8Array (the
+//                                collected stdout), matched by type — and every
+//                                other end dispatches `err` with the reason
+//                                bytes ("signaled", "cancelled", "rejected",
+//                                "spawn_failed", "truncated"). Cmd.cancel(key)
+//                                ends the child mid-stream (err arm
+//                                "cancelled" — never silent).
+//   Cmd.audioPlay(key, { path?, url?, cachePath?, expectedBytes? }, { event })
+//                                open (or replace — one player is the whole
+//                                surface) the audio event stream: every
+//                                playback event dispatches the `event` arm (the
+//                                six-field record below) until Cmd.audioStop
+//                                closes the stream.
+//   Cmd.audioPause(key) / audioResume(key) / audioStop(key)
+//   Cmd.audioSeek(key, ms) / Cmd.audioSetVolume(key, volume)
+//                                drive the open stream in place — fire-and-
+//                                forget control verbs whose consequences arrive
+//                                on the event stream; aimed at a key with no
+//                                open stream they no-op.
+//
+// The keyed-effect discipline is ONE rule: a keyed effect REPLACES its live
+// predecessor (the superseded effect's result is dropped — no message), and
+// Cmd.cancel drops it silently. That holds for request, readFile, writeFile,
+// fetch, clipboardRead, and delay alike. The ONE exception is a live spawn
+// key: a duplicate REJECTS the new spawn (err arm "rejected") — a running
+// subprocess is never killed implicitly; cancel it first. And spawn's cancel
+// stays loud (err arm "cancelled"): killing a process is an observable event.
+//
+// `Sub` is the recurring-effects surface: an app may export
+// `subscriptions(model): Sub<Msg>` returning declarative descriptors the
+// host reconciles after every commit (Sub.timer fires the named arm with the
+// current time on each interval). Like Cmd, Sub values are inert data, legal
+// only in that function's return path (NS1025). Sub and the streaming Cmds
+// are different animals on purpose: a Sub is DECLARED from the model (the
+// host starts/stops it by reconciliation; the app never opens one), while
+// spawn/audioPlay streams are Cmd-INITIATED — imperative opens with a keyed
+// lifecycle the app drives and cancels.
+//
+// The factories return plain frozen-shape objects so the same core runs
+// under node: a dev harness can interpret the `op` tags directly.
+
+// The byte-text method surface (s.toUpperCase(), s.split(sep), ... on
+// Uint8Array): the transpiler adds the ambient file to every core's program
+// itself; this reference carries the same surface into EDITORS of apps that
+// import "@native-sdk/core", so tsc-in-the-editor and `native check` agree.
+/// <reference path="./bytes_text_methods.d.ts" />
+
+/// The text intrinsic: turn a string literal or template into bytes. The
+/// transpiler recognizes calls BY IDENTITY (this import, renames honored)
+/// and folds them at compile time — a literal argument becomes rodata, a
+/// template becomes frame-arena bytes via bufPrint — so no string ever
+/// exists at native runtime. Under node this body runs as-is, byte for
+/// byte the same result. Arguments must be literals or templates; dynamic
+/// text lives in the model as Uint8Array from the start.
+export function asciiBytes(s: string): Uint8Array {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+/// Every app Msg is a discriminated union on a string `kind` tag.
+export type Msgish = { readonly kind: string };
+
+/// The Msg arms `Cmd.now` may target: arms whose payload is exactly one
+/// number-typed field (the runtime dispatches the arm with the timestamp in
+/// that field). Anything else is unrepresentable — the runtime has only a
+/// number to give back.
+export type TimestampKind<M extends Msgish> = M extends Msgish
+  ? {
+      [K in Exclude<keyof M, "kind">]-?: M[K] extends number
+        ? [Exclude<keyof M, "kind">] extends [K]
+          ? M["kind"]
+          : never
+        : never;
+    }[Exclude<keyof M, "kind">]
+  : never;
+
+/// The Msg arms a routed host result may target: arms whose payload is
+/// exactly one Uint8Array-typed field (the runtime dispatches the arm with
+/// the result/error bytes in that field).
+export type BytesKind<M extends Msgish> = M extends Msgish
+  ? {
+      [K in Exclude<keyof M, "kind">]-?: M[K] extends Uint8Array
+        ? [Exclude<keyof M, "kind">] extends [K]
+          ? M["kind"]
+          : never
+        : never;
+    }[Exclude<keyof M, "kind">]
+  : never;
+
+/// The Msg arms a payload-less routed result may target: arms with no
+/// payload fields at all (`Cmd.writeFile`'s ok route — a successful write
+/// has nothing to report beyond success).
+export type EmptyKind<M extends Msgish> = M extends Msgish
+  ? [Exclude<keyof M, "kind">] extends [never]
+    ? M["kind"]
+    : never
+  : never;
+
+/// The Msg arms a buffered fetch response may target: arms whose payload is
+/// exactly two fields — one number (the HTTP status) and one Uint8Array (the
+/// body). The runtime matches the fields by TYPE, so their names are yours.
+export type FetchedKind<M extends Msgish> = M extends Msgish
+  ? {
+      [K in Exclude<keyof M, "kind">]-?: M[K] extends Uint8Array
+        ? Exclude<keyof M, "kind" | K> extends infer O
+          ? O extends keyof M
+            ? M[O] extends number
+              ? [Exclude<keyof M, "kind" | K | O>] extends [never]
+                ? M["kind"]
+                : never
+              : never
+            : never
+          : never
+        : never;
+    }[Exclude<keyof M, "kind">]
+  : never;
+
+// ------------------------------------------------- wiring channel shapes
+// The generated wiring's opt-in host-event channels: export the channel
+// and it is wired (`commandMsg(name: string): Msg | null` is the same
+// family — menus, shortcuts, chrome tabs — and predates these). Event
+// RECORD shapes (`frameMsg`'s FrameEvent, `keyMsg`'s KeyEvent, the
+// appearanceMsg/chromeMsg arm payloads) are DECLARED IN YOUR CORE and
+// matched by field name, the TextInputEvent rule — they must emit as your
+// module's own records, so an SDK interface cannot stand in for them.
+
+/// One `envMsgs` entry: `export const envMsgs = [{ env: "NAME", msg:
+/// "<arm>" }] as const` — each named environment variable present at launch
+/// dispatches its value through the arm (exactly one `Uint8Array` field) as
+/// an ordinary journaled Msg right after the boot command. The core itself
+/// never reads the environment (NS1005); replay carries the recorded values.
+export interface EnvMsg<M extends Msgish> {
+  readonly env: string;
+  readonly msg: BytesKind<M>;
+}
+
+/// The audio event states, mirroring the engine's event vocabulary: `loaded`
+/// acknowledges a successful load with the player's duration estimate;
+/// `position` ticks at the platform's honest cadence (~500ms) while playing;
+/// `completed` fires exactly once at the natural end; `failed` reports a
+/// load/decode/device failure; `rejected` a command the effects layer refused
+/// (an empty or over-long source); `spectrum` carries a band-magnitude
+/// analysis frame from hosts that analyze their playback.
+export type AudioState = "loaded" | "position" | "completed" | "failed" | "rejected" | "spectrum";
+
+/// The payload shape of an audio event arm — six fields, matched by NAME (the
+/// one SDK-fixed record shape, so the host can build it from your union).
+/// `state` must be a named string-literal-union alias carrying exactly the
+/// six AudioState members (any declaration order — the host matches members
+/// by name). `positionMs`/`durationMs` are milliseconds; `playing` is the
+/// player's transport state; `buffering` is true while a streamed source is
+/// stalled waiting for network bytes; `bands` is the 32 spectrum band
+/// magnitudes (0..255 each, all zeros outside "spectrum" events).
+export type AudioEventArm = {
+  readonly state: AudioState;
+  readonly positionMs: number;
+  readonly durationMs: number;
+  readonly playing: boolean;
+  readonly buffering: boolean;
+  readonly bands: Uint8Array;
+};
+
+/// The Msg arms an audio event stream may target: arms whose payload is
+/// exactly the six AudioEventArm fields.
+export type AudioEventKind<M extends Msgish> = M extends Msgish
+  ? [Exclude<keyof M, "kind">] extends [keyof AudioEventArm]
+    ? [keyof AudioEventArm] extends [Exclude<keyof M, "kind">]
+      ? M extends Msgish & AudioEventArm
+        ? M["kind"]
+        : never
+      : never
+    : never
+  : never;
+
+/// One field of a host record payload; see hostRecordBytes for the encoding.
+export type HostScalar = number | boolean | Uint8Array;
+
+/// A structured host payload: a flat record of scalar/bytes fields, lowered
+/// to one bytes payload at build time (natively) and by hostRecordBytes
+/// (under node) — the same bytes either way.
+export type HostRecord = { readonly [field: string]: HostScalar };
+
+/// How a `Cmd.request` result comes back: the host dispatches the `ok` arm
+/// with the result bytes on success, or the `err` arm with the error bytes.
+/// Arm names are string literals — the routing is data, never a callback.
+/// `key` (optional) names the in-flight effect for replace/cancel semantics.
+export interface RequestRoute<M extends Msgish> {
+  readonly key?: string;
+  readonly ok: BytesKind<M>;
+  readonly err: BytesKind<M>;
+}
+
+/// `Cmd.writeFile` routing: the ok arm carries no payload (success has
+/// nothing to report); the err arm carries the reason bytes.
+export interface WriteRoute<M extends Msgish> {
+  readonly key?: string;
+  readonly ok: EmptyKind<M>;
+  readonly err: BytesKind<M>;
+}
+
+/// `Cmd.fetch` routing: the ok arm carries `{ status, body }` (one number
+/// field, one bytes field — matched by type); the err arm the reason bytes.
+export interface FetchRoute<M extends Msgish> {
+  readonly key?: string;
+  readonly ok: FetchedKind<M>;
+  readonly err: BytesKind<M>;
+}
+
+/// `Cmd.spawn` routing, line mode: each stdout line dispatches the optional
+/// `line` arm (one bytes field; omitted = lines dropped), a clean exit the
+/// `exit` arm (one number field — the exit code), every other end the `err`
+/// arm with the reason bytes.
+export interface SpawnRoute<M extends Msgish> {
+  readonly key?: string;
+  readonly stdin?: Uint8Array;
+  readonly line?: BytesKind<M>;
+  readonly exit: TimestampKind<M>;
+  readonly err: BytesKind<M>;
+}
+
+/// `Cmd.spawn` routing, collect mode: whole stdout buffers until the exit,
+/// which dispatches the `exit` arm as a two-field record — one number field
+/// (the exit code) and one bytes field (the collected stdout), matched by
+/// type so the names are yours. No line arm: there is no line framing.
+export interface SpawnCollectRoute<M extends Msgish> {
+  readonly key?: string;
+  readonly stdin?: Uint8Array;
+  readonly collect: true;
+  readonly exit: FetchedKind<M>;
+  readonly err: BytesKind<M>;
+}
+
+/// A `Cmd.audioPlay` source: the resolution cascade of the engine underneath.
+/// The local `path` is tried first; a missing file falls through to `url`
+/// (streamed progressively, cached at `cachePath` when given and verified
+/// against `expectedBytes` — 0/omitted means unknown size, existence alone
+/// qualifies a cache entry). At least one of path/url must be present.
+export interface AudioSource {
+  readonly path?: Uint8Array;
+  readonly url?: Uint8Array;
+  readonly cachePath?: Uint8Array;
+  readonly expectedBytes?: number;
+}
+
+/// `Cmd.audioPlay` routing: every playback event dispatches the `event` arm
+/// (the six-field AudioEventArm record, matched by field name).
+export interface AudioRoute<M extends Msgish> {
+  readonly event: AudioEventKind<M>;
+}
+
+/// The closed HTTP verb set of `Cmd.fetch` (wire value = declaration order).
+export type FetchMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD";
+
+/// A `Cmd.fetch` request. `url` is bytes (asciiBytes for literals); headers
+/// are a flat record whose NAMES are compile-time text and whose VALUES are
+/// string literals or runtime bytes (`Uint8Array` — how a launch-supplied
+/// credential rides an `Authorization` header); `timeoutMs` omitted means
+/// the host engine's default.
+export interface FetchSpec {
+  readonly url: Uint8Array;
+  readonly method?: FetchMethod;
+  readonly headers?: { readonly [name: string]: string | Uint8Array };
+  readonly body?: Uint8Array;
+  readonly timeoutMs?: number;
+}
+
+/// An inert command value, parameterized by the app's Msg union so the
+/// factories can validate message targets. Opaque to app code: build with
+/// the `Cmd.*` factories, return from `update`/`initialModel`, never inspect
+/// or store.
+export type Cmd<M extends Msgish> =
+  | { readonly op: "none" }
+  | { readonly op: "persist" }
+  | { readonly op: "now"; readonly msgKind: string }
+  | { readonly op: "host"; readonly name: string; readonly args: readonly number[] }
+  | { readonly op: "host_bytes"; readonly name: string; readonly payload: Uint8Array }
+  | {
+      readonly op: "request";
+      readonly name: string;
+      readonly key: string;
+      readonly okKind: string;
+      readonly errKind: string;
+      readonly payload: Uint8Array;
+    }
+  | { readonly op: "cancel"; readonly key: string }
+  | {
+      readonly op: "read_file";
+      readonly key: string;
+      readonly okKind: string;
+      readonly errKind: string;
+      readonly path: Uint8Array;
+    }
+  | {
+      readonly op: "write_file";
+      readonly key: string;
+      readonly okKind: string;
+      readonly errKind: string;
+      readonly path: Uint8Array;
+      readonly bytes: Uint8Array;
+    }
+  | {
+      readonly op: "fetch";
+      readonly key: string;
+      readonly okKind: string;
+      readonly errKind: string;
+      readonly method: FetchMethod;
+      readonly timeoutMs: number;
+      readonly url: Uint8Array;
+      /// Header pairs, already in TS-field-name (code-unit) sort order.
+      /// A string value is compile-time text; a Uint8Array value is
+      /// runtime bytes (both encode as the record's length-prefixed
+      /// value field).
+      readonly headers: readonly { readonly name: string; readonly value: string | Uint8Array }[];
+      readonly body: Uint8Array;
+    }
+  | { readonly op: "clip_write"; readonly bytes: Uint8Array }
+  | { readonly op: "clip_read"; readonly key: string; readonly okKind: string; readonly errKind: string }
+  | { readonly op: "delay"; readonly key: string; readonly afterMs: number; readonly msgKind: string }
+  | {
+      readonly op: "spawn";
+      readonly key: string;
+      /// "" = no line routing (collect mode, or a line spawn that only
+      /// cares about the exit).
+      readonly lineKind: string;
+      readonly exitKind: string;
+      readonly errKind: string;
+      readonly collect: boolean;
+      readonly argv: readonly Uint8Array[];
+      readonly stdin: Uint8Array;
+    }
+  | {
+      readonly op: "audio_play";
+      readonly key: string;
+      readonly eventKind: string;
+      readonly path: Uint8Array;
+      readonly url: Uint8Array;
+      readonly cachePath: Uint8Array;
+      readonly expectedBytes: number;
+    }
+  | {
+      readonly op: "audio_ctl";
+      readonly key: string;
+      readonly verb: "pause" | "resume" | "stop" | "seek" | "volume";
+      /// Seek position (ms) / volume (0..1); 0 for the value-less verbs.
+      readonly value: number;
+    }
+  | { readonly op: "batch"; readonly cmds: readonly Cmd<M>[] };
+
+/// The wire encoding of a host record payload, byte-identical to what the
+/// transpiler derives from the record's TS shape at build time: fields
+/// sorted by name (code-unit order), concatenated with no field headers —
+/// number -> f64 little-endian (8 bytes), boolean -> one 0/1 byte,
+/// Uint8Array -> u32 little-endian length + bytes.
+export function hostRecordBytes(payload: HostRecord): Uint8Array {
+  const names = Object.keys(payload).sort();
+  let len = 0;
+  for (const n of names) {
+    const v = payload[n];
+    if (typeof v === "number") len += 8;
+    else if (typeof v === "boolean") len += 1;
+    else len += 4 + v.length;
+  }
+  const out = new Uint8Array(len);
+  const dv = new DataView(out.buffer);
+  let off = 0;
+  for (const n of names) {
+    const v = payload[n];
+    if (typeof v === "number") {
+      dv.setFloat64(off, v, true);
+      off += 8;
+    } else if (typeof v === "boolean") {
+      out[off] = v ? 1 : 0;
+      off += 1;
+    } else {
+      dv.setUint32(off, v.length, true);
+      off += 4;
+      out.set(v, off);
+      off += v.length;
+    }
+  }
+  return out;
+}
+
+function lowerHostPayload(payload: Uint8Array | HostRecord): Uint8Array {
+  return payload instanceof Uint8Array ? payload : hostRecordBytes(payload);
+}
+
+/// A host command by name; the host decides what the name means. The name is
+/// a string literal. Args are scalar numbers, or exactly one bytes payload
+/// (a Uint8Array, or a flat record that lowers to bytes).
+function hostCmd(name: string, payload: Uint8Array | HostRecord): Cmd<never>;
+function hostCmd(name: string, ...args: readonly number[]): Cmd<never>;
+function hostCmd(name: string, ...rest: readonly (number | Uint8Array | HostRecord)[]): Cmd<never> {
+  const first = rest[0];
+  if (rest.length === 1 && typeof first === "object" && first !== null) {
+    return { op: "host_bytes", name, payload: lowerHostPayload(first) };
+  }
+  return { op: "host", name, args: rest as readonly number[] };
+}
+
+export const Cmd = {
+  /// No effects. `return model` is sugar for `return [model, Cmd.none]`.
+  none: { op: "none" } as Cmd<never>,
+
+  /// Ask the host to persist the committed model.
+  persist(): Cmd<never> {
+    return { op: "persist" };
+  },
+
+  /// Request the current time. The runtime dispatches the named Msg arm with
+  /// the timestamp (milliseconds, a plain number) as its single payload field.
+  now<M extends Msgish>(msgKind: TimestampKind<M>): Cmd<M> {
+    return { op: "now", msgKind };
+  },
+
+  host: hostCmd,
+
+  /// A routed host command: the host performs `name` with the payload and
+  /// dispatches exactly one result Msg back — the `ok` arm with the result
+  /// bytes, or the `err` arm with the error bytes. Both arms must carry
+  /// exactly one Uint8Array payload field (tsc checks that). An optional
+  /// `key` names the in-flight effect: re-issuing a live key replaces it,
+  /// and Cmd.cancel(key) drops it.
+  request<M extends Msgish>(
+    name: string,
+    payload: Uint8Array | HostRecord,
+    route: RequestRoute<M>,
+  ): Cmd<M> {
+    return {
+      op: "request",
+      name,
+      key: route.key ?? "",
+      okKind: route.ok,
+      errKind: route.err,
+      payload: lowerHostPayload(payload),
+    };
+  },
+
+  /// Drop the in-flight keyed effect — request, named engine op, or delay —
+  /// with this key, if any, SILENTLY (neither routing arm is dispatched for
+  /// it). The exception is a live spawn: cancel ends the child and its err
+  /// arm runs with "cancelled" — killing a process is an observable event.
+  cancel(key: string): Cmd<never> {
+    return { op: "cancel", key };
+  },
+
+  /// Read a whole file. Exactly one terminal Msg: the `ok` arm with the
+  /// content bytes (one Uint8Array field), or the `err` arm with the reason
+  /// bytes ("not_found", "io_failed", "truncated", "rejected").
+  readFile<M extends Msgish>(path: Uint8Array, route: RequestRoute<M>): Cmd<M> {
+    return { op: "read_file", key: route.key ?? "", okKind: route.ok, errKind: route.err, path };
+  },
+
+  /// Write a whole file (parent directories created, an existing file
+  /// replaced whole). Exactly one terminal Msg: the `ok` arm — which carries
+  /// no payload — or the `err` arm with the reason bytes.
+  writeFile<M extends Msgish>(path: Uint8Array, bytes: Uint8Array, route: WriteRoute<M>): Cmd<M> {
+    return { op: "write_file", key: route.key ?? "", okKind: route.ok, errKind: route.err, path, bytes };
+  },
+
+  /// A buffered HTTP(S) exchange. Exactly one terminal Msg: the `ok` arm
+  /// with `{ status, body }` (one number field, one bytes field — a non-2xx
+  /// status is still ok: an HTTP-level error is a delivered response), or
+  /// the `err` arm with the reason bytes.
+  fetch<M extends Msgish>(spec: FetchSpec, route: FetchRoute<M>): Cmd<M> {
+    const names = Object.keys(spec.headers ?? {}).sort();
+    return {
+      op: "fetch",
+      key: route.key ?? "",
+      okKind: route.ok,
+      errKind: route.err,
+      method: spec.method ?? "GET",
+      timeoutMs: spec.timeoutMs ?? 0,
+      url: spec.url,
+      headers: names.map((n) => ({ name: n, value: spec.headers![n] })),
+      body: spec.body ?? new Uint8Array(0),
+    };
+  },
+
+  /// Put bytes on the system clipboard, fire-and-forget (an over-bound or
+  /// refused write is dropped — there is no route to report on).
+  clipboardWrite(bytes: Uint8Array): Cmd<never> {
+    return { op: "clip_write", bytes };
+  },
+
+  /// Read the system clipboard. Exactly one terminal Msg: the `ok` arm with
+  /// the text bytes, or the `err` arm with the reason bytes ("failed",
+  /// "rejected").
+  clipboardRead<M extends Msgish>(route: RequestRoute<M>): Cmd<M> {
+    return { op: "clip_read", key: route.key ?? "", okKind: route.ok, errKind: route.err };
+  },
+
+  /// A keyed one-shot delay: dispatch the named Msg arm once, `ms` from now,
+  /// with the fire time (milliseconds) as its single number payload field.
+  /// Re-issuing a live key re-arms it from now (the debounce discipline);
+  /// `Cmd.cancel(key)` drops it silently.
+  delay<M extends Msgish>(key: string, ms: number, msgKind: TimestampKind<M>): Cmd<M> {
+    return { op: "delay", key, afterMs: ms, msgKind };
+  },
+
+  /// Run a subprocess as a STREAM: each stdout line dispatches the `line`
+  /// arm as it arrives (line mode), or whole stdout buffers to the exit
+  /// (`collect: true`); exactly one terminal follows — the `exit` arm on a
+  /// clean exit, the `err` arm with the reason bytes on every other end.
+  /// The key stays live for the whole stream: `Cmd.cancel(key)` ends the
+  /// child mid-stream (err arm "cancelled" — loud on purpose: killing a
+  /// process is an observable event), and a spawn whose key is already
+  /// streaming is rejected, never replaced — a running subprocess is never
+  /// killed implicitly; cancel it first.
+  spawn<M extends Msgish>(
+    argv: readonly Uint8Array[],
+    route: SpawnRoute<M> | SpawnCollectRoute<M>,
+  ): Cmd<M> {
+    const collect = "collect" in route && route.collect === true;
+    return {
+      op: "spawn",
+      key: route.key ?? "",
+      lineKind: collect ? "" : ((route as SpawnRoute<M>).line ?? ""),
+      exitKind: route.exit,
+      errKind: route.err,
+      collect,
+      argv,
+      stdin: route.stdin ?? new Uint8Array(0),
+    };
+  },
+
+  /// Open (or replace — one player is the whole surface) the keyed audio
+  /// event stream: resolve the source cascade (local path, then url, cached
+  /// and integrity-gated) and start playback. Every playback event
+  /// dispatches the `event` arm until `Cmd.audioStop(key)` closes the
+  /// stream. Failure is never silent: an unplayable source arrives as a
+  /// "failed" event, a refused command as "rejected".
+  audioPlay<M extends Msgish>(key: string, source: AudioSource, route: AudioRoute<M>): Cmd<M> {
+    return {
+      op: "audio_play",
+      key,
+      eventKind: route.event,
+      path: source.path ?? new Uint8Array(0),
+      url: source.url ?? new Uint8Array(0),
+      cachePath: source.cachePath ?? new Uint8Array(0),
+      expectedBytes: source.expectedBytes ?? 0,
+    };
+  },
+
+  /// Pause the keyed playback in place (no event echo — the caller
+  /// commanded it). A key with no open stream no-ops.
+  audioPause(key: string): Cmd<never> {
+    return { op: "audio_ctl", key, verb: "pause", value: 0 };
+  },
+
+  /// Resume the keyed playback. A player that can no longer resume reports
+  /// one "failed" event on the stream instead of silence.
+  audioResume(key: string): Cmd<never> {
+    return { op: "audio_ctl", key, verb: "resume", value: 0 };
+  },
+
+  /// Stop the keyed playback and CLOSE its event stream: no events for the
+  /// key after this. Stop is the audio stream's cancel.
+  audioStop(key: string): Cmd<never> {
+    return { op: "audio_ctl", key, verb: "stop", value: 0 };
+  },
+
+  /// Jump the keyed playback to `ms` (the platform clamps to the duration).
+  /// No event echo — the next position tick reports from there.
+  audioSeek(key: string, ms: number): Cmd<never> {
+    return { op: "audio_ctl", key, verb: "seek", value: ms };
+  },
+
+  /// Set playback volume, clamped to 0..1 and remembered across tracks: the
+  /// next audioPlay re-applies it.
+  audioSetVolume(key: string, volume: number): Cmd<never> {
+    return { op: "audio_ctl", key, verb: "volume", value: volume };
+  },
+
+  /// Several commands from one dispatch, performed in order.
+  batch<M extends Msgish>(cmds: readonly Cmd<M>[]): Cmd<M> {
+    return { op: "batch", cmds };
+  },
+};
+
+/// An inert subscription descriptor: recurring effects declared FROM the
+/// model. An app that needs them exports `subscriptions(model): Sub<Msg>`;
+/// after every commit the host reconciles the returned set against its
+/// active timers by key (new key or changed interval re-arms; a missing key
+/// cancels). Like Cmd, Sub values are data, legal only in that function's
+/// return path (NS1025).
+export type Sub<M extends Msgish> =
+  | { readonly op: "none" }
+  | { readonly op: "timer"; readonly key: string; readonly everyMs: number; readonly msgKind: string }
+  | { readonly op: "batch"; readonly subs: readonly Sub<M>[] };
+
+export const Sub = {
+  /// No subscriptions (e.g. everything paused).
+  none: { op: "none" } as Sub<never>,
+
+  /// A repeating timer named by `key`, firing every `everyMs` milliseconds.
+  /// Each fire dispatches the named Msg arm with the current time (ms) as
+  /// its single number payload field.
+  timer<M extends Msgish>(key: string, everyMs: number, msgKind: TimestampKind<M>): Sub<M> {
+    return { op: "timer", key, everyMs, msgKind };
+  },
+
+  /// Several subscriptions at once.
+  batch<M extends Msgish>(subs: readonly Sub<M>[]): Sub<M> {
+    return { op: "batch", subs };
+  },
+};