@hraness/dawg 0.7.0 → 0.8.0

package/src/session/protocol.ts

@@ -12,12 +12,38 @@ import {
 } from "./meta.ts";
 import type { SessionEvent, SessionPaths, SessionRecord } from "./store.ts";
 
+/** Same shape as src/identity/actor.ts ACTOR_ID; kept here to stay leaf. */
+const ACTOR_ID = /^a_[a-z2-7]{22}$/;
+
 /**
  * dawgd wire protocol: newline-delimited JSON over a Unix domain socket.
  * Every frame carries `v`; every inbound frame is parsed from `unknown` and
  * bounded before it can reach the reducer, the store, or the transport.
  */
 export const PROTOCOL_VERSION = 1 as const;
+/**
+ * Negotiated protocol revisions. Frames keep `v: 1` (the framing); `hello`
+ * offers `{vMin, vMax, caps}` and `welcome` answers with the chosen revision
+ * and the daemon's capabilities. A v1-only client sends neither and gets the
+ * original behaviour. Revision 2 adds actors, per-client `seq`, ops on
+ * events and transport `quantum`.
+ */
+export const PROTOCOL_MIN = 1;
+export const PROTOCOL_MAX = 2;
+/** What this build's dawgd offers in `welcome.caps`. */
+export const DAEMON_CAPS = [
+  "actor",
+  "seq",
+  "ops-log",
+  "quantum",
+  "opaque-kinds",
+  "panes",
+  "live",
+] as const;
+const MAX_CAPS = 32;
+const MAX_CAP_LENGTH = 32;
+/** Default musical cycle when a transport frame predates `quantum`. */
+export const DEFAULT_QUANTUM = 4;
 /** Client intents carry at most one composition plus a bounded payload. */
 export const MAX_CLIENT_FRAME_BYTES = 2 * 1024 * 1024;
 /** Snapshots carry a full session record, which the store bounds at 4 MiB. */
@@ -38,16 +64,98 @@ export type TransportState = {
   /** Beat position at `atMs`. */
   beat: number;
   bpm: number;
-  /** Daemon monotonic clock expressed on the epoch (timeOrigin + now). */
+  /**
+   * When `beat` held, on the *authority's host clock*: dawgd's monotonic
+   * clock expressed on the epoch (timeOrigin + now). On one machine every
+   * process shares it; a remote reader must convert with its per-client
+   * offset (`SessionPort` applies `clockOffsetMs`, 0 locally) before use.
+   */
   atMs: number;
+  /** Beats per phase cycle (bar or loop), Link-style; defaults to 4. */
+  quantum: number;
 };
 
 /** One live window. dawgd drops the entry when the client disconnects. */
 export type PresenceEntry = {
   clientId: string;
+  /** Who is at this window (src/identity/actor.ts); absent for v1 clients. */
+  actorId?: string;
+  /** Machine-local process id: display only, never identity. */
   pid: number;
   label: string;
   focusedTrackId: string | null;
+  /**
+   * Pane letter (A, B, C in join order, reused when freed), assigned by
+   * dawgd. Display only: identity and per-pane undo key on `clientId`.
+   */
+  pane?: string;
+  /** What the pane shows (see `PaneView`); absent until it reports. */
+  screen?: string;
+  /** The drawer parameter or page the pane has open. */
+  param?: string;
+  /** Recording a pass on `focusedTrackId`, and in which mode. */
+  recording?: "overdub" | "replace";
+  /** In PLAY (live keys) on `focusedTrackId`. */
+  playing?: boolean;
+  /** Locked to its screen and track (`pin`). */
+  pinned?: boolean;
+  /** Follows another pane's focus: its letter, or `*` for the latest. */
+  follow?: string;
+};
+
+/** The per-pane view fields a client reports with `view`. */
+export type PaneView = Pick<
+  PresenceEntry,
+  "screen" | "param" | "recording" | "playing" | "pinned" | "follow"
+>;
+
+/** A live click: on while any pane wants it; count-in from the last arm. */
+export type LiveClick = {
+  on: boolean;
+  volume: number;
+  /** A count-in before the transport starts, on the authority's clock. */
+  countIn?: {
+    startAtMs: number;
+    startBeat: number;
+    beats: number;
+    barBeats: number;
+    clickBeats: number;
+    bpm: number;
+  };
+};
+
+/**
+ * Live notes go to the one engine on this machine. A window never sends
+ * audio: dawgd renders the voice from the score it already holds.
+ */
+export type LiveMessage =
+  | { v: 1; type: "live"; action: "monitor"; id: string; on: boolean }
+  | {
+      v: 1;
+      type: "live";
+      action: "on";
+      /** Window-local voice id; dawgd namespaces it by client. */
+      voice: number;
+      trackId: string;
+      pitch: number;
+      /** 0..1, as score notes store it. */
+      velocity: number;
+      /** How long the key is held (or the longest live note). */
+      seconds: number;
+      /** Transport beat of the press, unwrapped. */
+      beat: number;
+      /** When pressed, on the authority's clock (local clock + offset). */
+      atMs: number;
+    }
+  | { v: 1; type: "live"; action: "off"; voice: number; atMs: number }
+  | ({ v: 1; type: "live"; action: "click" } & LiveClick);
+
+/** dawgd's answer to `live monitor`: how the shared engine sounds. */
+export type LiveStatus = {
+  canMonitor: boolean;
+  sampleRate: number;
+  leadMs: number;
+  note?: string;
 };
 
 export type ClientMessage =
@@ -58,6 +166,12 @@ export type ClientMessage =
       label: string;
       clientId: string;
       focusedTrackId: string | null;
+      /** Protocol revisions this client speaks; absent means 1..1. */
+      vMin?: number;
+      vMax?: number;
+      caps?: string[];
+      actorId?: string;
+      actorName?: string;
     }
   | { v: 1; type: "focus"; id: string; trackId: string | null }
   /** `draft` asks dawgd to reserve a new `track-N` id when all are open. */
@@ -72,6 +186,12 @@ export type ClientMessage =
       base: number;
       kind: string;
       payload: unknown;
+      /**
+       * Per-(actor, client) sequence number, strictly increasing per intent
+       * and reused on retry: dawgd dedupes on (actorId, clientId, seq) across
+       * restarts, the same way it dedupes on `key`.
+       */
+      seq?: number;
       operations?: unknown[];
       composition?: unknown;
     }
@@ -84,7 +204,10 @@ export type ClientMessage =
       bpm?: number;
     }
   | { v: 1; type: "sync"; id: string }
-  | { v: 1; type: "ping"; id: string };
+  | { v: 1; type: "ping"; id: string }
+  /** Updates this pane's presence view fields; no reply. */
+  | ({ v: 1; type: "view" } & PaneView)
+  | LiveMessage;
 
 export type ApplyResult =
   | { status: "accepted"; revision: number }
@@ -106,6 +229,9 @@ export type ServerMessage =
       record: SessionRecord<unknown>;
       digest: string;
       transport: TransportState;
+      /** Negotiated revision; absent from a v1-only daemon. */
+      protocol?: number;
+      caps?: string[];
     }
   | {
       v: 1;
@@ -133,6 +259,7 @@ export type ServerMessage =
     }
   | ({ v: 1; type: "result"; id: string } & ApplyResult)
   | { v: 1; type: "pong"; id: string }
+  | ({ v: 1; type: "liveStatus"; id: string } & LiveStatus)
   | { v: 1; type: "error"; code: string; message: string };
 
 export class ProtocolError extends Error {
@@ -192,7 +319,7 @@ export function parseClientMessage(line: string): ClientMessage {
       throw new ProtocolError("invalid", "hello pid is invalid");
     if (typeof label !== "string" || label.length > MAX_KIND_LENGTH)
       throw new ProtocolError("invalid", "hello label is invalid");
-    return {
+    const message: ClientMessage = {
       v: 1,
       type,
       pid: pid as number,
@@ -200,6 +327,31 @@ export function parseClientMessage(line: string): ClientMessage {
       clientId: requireId(value.clientId, "client id"),
       focusedTrackId: optionalTrackId(value.focusedTrackId),
     };
+    if (value.vMin !== undefined || value.vMax !== undefined) {
+      const vMin = value.vMin ?? 1;
+      const vMax = value.vMax ?? vMin;
+      if (
+        !Number.isSafeInteger(vMin) ||
+        !Number.isSafeInteger(vMax) ||
+        (vMin as number) < 1 ||
+        (vMax as number) < (vMin as number)
+      )
+        throw new ProtocolError("invalid", "hello versions are invalid");
+      message.vMin = vMin as number;
+      message.vMax = vMax as number;
+    }
+    if (value.caps !== undefined) message.caps = requireCaps(value.caps);
+    if (value.actorId !== undefined) {
+      if (typeof value.actorId !== "string" || !ACTOR_ID.test(value.actorId))
+        throw new ProtocolError("invalid", "hello actor is invalid");
+      message.actorId = value.actorId;
+    }
+    if (value.actorName !== undefined) {
+      if (typeof value.actorName !== "string")
+        throw new ProtocolError("invalid", "hello actor name is invalid");
+      message.actorName = value.actorName.slice(0, MAX_ID_LENGTH);
+    }
+    return message;
   }
   if (type === "focus")
     return {
@@ -267,6 +419,11 @@ export function parseClientMessage(line: string): ClientMessage {
       kind,
       payload: value.payload,
     };
+    if (value.seq !== undefined) {
+      if (!Number.isSafeInteger(value.seq) || (value.seq as number) < 1)
+        throw new ProtocolError("invalid", "apply seq is invalid");
+      message.seq = value.seq as number;
+    }
     if (hasOperations) {
       if (
         !Array.isArray(value.operations) ||
@@ -304,9 +461,129 @@ export function parseClientMessage(line: string): ClientMessage {
   }
   if (type === "sync" || type === "ping")
     return { v: 1, type, id: requireId(value.id, "request id") };
+  if (type === "view") return { v: 1, type, ...parsePaneView(value) };
+  if (type === "live") return parseLive(value);
   throw new ProtocolError("unknown-type", "unknown message type");
 }
 
+const SCREEN = /^[a-z][a-z0-9-]{0,31}$/;
+const PANE_LETTER = /^[A-Z]$/;
+
+/** The view fields of a `view` frame or a presence entry; junk is dropped. */
+export function parsePaneView(value: Record<string, unknown>): PaneView {
+  const view: PaneView = {};
+  if (typeof value.screen === "string" && SCREEN.test(value.screen))
+    view.screen = value.screen;
+  if (typeof value.param === "string" && value.param.length > 0)
+    view.param = value.param.slice(0, MAX_ID_LENGTH);
+  if (value.recording === "overdub" || value.recording === "replace")
+    view.recording = value.recording;
+  if (value.playing === true) view.playing = true;
+  if (value.pinned === true) view.pinned = true;
+  if (
+    typeof value.follow === "string" &&
+    (value.follow === "*" || PANE_LETTER.test(value.follow))
+  )
+    view.follow = value.follow;
+  return view;
+}
+
+function parseLive(value: Record<string, unknown>): LiveMessage {
+  const action = value.action;
+  if (action === "monitor") {
+    if (typeof value.on !== "boolean")
+      throw new ProtocolError("invalid", "live monitor is invalid");
+    return {
+      v: 1,
+      type: "live",
+      action,
+      id: requireId(value.id, "request id"),
+      on: value.on,
+    };
+  }
+  if (action === "on") {
+    const voice = value.voice;
+    const pitch = value.pitch;
+    if (
+      !Number.isSafeInteger(voice) ||
+      !Number.isSafeInteger(pitch) ||
+      (pitch as number) < 0 ||
+      (pitch as number) > 127 ||
+      !isFiniteNonNegative(value.velocity) ||
+      (value.velocity as number) > 1 ||
+      !isFiniteNonNegative(value.seconds) ||
+      (value.seconds as number) > 600 ||
+      !Number.isFinite(value.beat) ||
+      !isFiniteNonNegative(value.atMs)
+    )
+      throw new ProtocolError("invalid", "live note is invalid");
+    return {
+      v: 1,
+      type: "live",
+      action,
+      voice: voice as number,
+      trackId: requireId(value.trackId, "track id"),
+      pitch: pitch as number,
+      velocity: value.velocity as number,
+      seconds: value.seconds as number,
+      beat: value.beat as number,
+      atMs: value.atMs as number,
+    };
+  }
+  if (action === "off") {
+    if (!Number.isSafeInteger(value.voice) || !isFiniteNonNegative(value.atMs))
+      throw new ProtocolError("invalid", "live note-off is invalid");
+    return {
+      v: 1,
+      type: "live",
+      action,
+      voice: value.voice as number,
+      atMs: value.atMs as number,
+    };
+  }
+  if (action === "click") {
+    if (
+      typeof value.on !== "boolean" ||
+      !isFiniteNonNegative(value.volume) ||
+      (value.volume as number) > 1
+    )
+      throw new ProtocolError("invalid", "live click is invalid");
+    const message: LiveMessage = {
+      v: 1,
+      type: "live",
+      action,
+      on: value.on,
+      volume: value.volume as number,
+    };
+    const count = value.countIn as Record<string, unknown> | undefined;
+    if (count !== undefined) {
+      if (
+        typeof count !== "object" ||
+        count === null ||
+        !isFiniteNonNegative(count.startAtMs) ||
+        !Number.isFinite(count.startBeat) ||
+        !isFiniteNonNegative(count.beats) ||
+        !isFiniteNonNegative(count.barBeats) ||
+        !isFiniteNonNegative(count.clickBeats) ||
+        !isFiniteNonNegative(count.bpm) ||
+        (count.bpm as number) <= 0 ||
+        (count.beats as number) > 64
+      )
+        throw new ProtocolError("invalid", "live count-in is invalid");
+      message.countIn = {
+        startAtMs: count.startAtMs as number,
+        startBeat: count.startBeat as number,
+        beats: count.beats as number,
+        barBeats: count.barBeats as number,
+        clickBeats: count.clickBeats as number,
+        bpm: count.bpm as number,
+      };
+    }
+    return message;
+  }
+  throw new ProtocolError("invalid", "live action is invalid");
+}
+
 export function parseServerMessage(line: string): ServerMessage {
   const value = parseObject(line);
   const type = value.type;
@@ -315,7 +592,7 @@ export function parseServerMessage(line: string): ServerMessage {
       throw new ProtocolError("invalid", "welcome session is invalid");
     if (!Number.isSafeInteger(value.pid))
       throw new ProtocolError("invalid", "welcome pid is invalid");
-    return {
+    const message: ServerMessage = {
       v: 1,
       type,
       sessionId: value.sessionId,
@@ -324,6 +601,16 @@ export function parseServerMessage(line: string): ServerMessage {
       digest: requireDigest(value.digest),
       transport: requireTransport(value.transport),
     };
+    if (value.protocol !== undefined) {
+      if (
+        !Number.isSafeInteger(value.protocol) ||
+        (value.protocol as number) < 1
+      )
+        throw new ProtocolError("invalid", "welcome protocol is invalid");
+      message.protocol = value.protocol as number;
+    }
+    if (value.caps !== undefined) message.caps = requireCaps(value.caps);
+    return message;
   }
   if (type === "commit") {
     const event = value.event;
@@ -408,6 +695,24 @@ export function parseServerMessage(line: string): ServerMessage {
   }
   if (type === "pong")
     return { v: 1, type, id: requireId(value.id, "request id") };
+  if (type === "liveStatus") {
+    if (
+      typeof value.canMonitor !== "boolean" ||
+      !isFiniteNonNegative(value.sampleRate) ||
+      !isFiniteNonNegative(value.leadMs)
+    )
+      throw new ProtocolError("invalid", "live status is invalid");
+    const message: ServerMessage = {
+      v: 1,
+      type,
+      id: requireId(value.id, "request id"),
+      canMonitor: value.canMonitor,
+      sampleRate: value.sampleRate as number,
+      leadMs: value.leadMs as number,
+    };
+    if (typeof value.note === "string") message.note = boundedText(value.note);
+    return message;
+  }
   if (type === "error")
     return {
       v: 1,
@@ -487,12 +792,45 @@ export function requirePresence(value: unknown): PresenceEntry {
   const entry = value as Record<string, unknown>;
   if (!Number.isSafeInteger(entry.pid) || (entry.pid as number) <= 0)
     throw new ProtocolError("invalid", "presence pid is invalid");
-  return {
+  const parsed: PresenceEntry = {
     clientId: requireId(entry.clientId, "client id"),
     pid: entry.pid as number,
     label: boundedText(entry.label).slice(0, MAX_KIND_LENGTH),
     focusedTrackId: optionalTrackId(entry.focusedTrackId),
   };
+  if (typeof entry.actorId === "string" && ACTOR_ID.test(entry.actorId))
+    parsed.actorId = entry.actorId;
+  if (typeof entry.pane === "string" && PANE_LETTER.test(entry.pane))
+    parsed.pane = entry.pane;
+  return { ...parsed, ...parsePaneView(entry) };
+}
+
+/**
+ * Capability names: short tokens. Unknown names are kept (a peer may know
+ * more than we do); callers test membership only.
+ */
+function requireCaps(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length > MAX_CAPS)
+    throw new ProtocolError("invalid", "caps are invalid");
+  return value.map((cap) => {
+    if (
+      typeof cap !== "string" ||
+      cap.length === 0 ||
+      cap.length > MAX_CAP_LENGTH ||
+      !/^[a-z0-9][a-z0-9.-]*$/.test(cap)
+    )
+      throw new ProtocolError("invalid", "caps are invalid");
+    return cap;
+  });
+}
+
+/**
+ * The revision both sides speak: the highest in the overlap of
+ * [vMin, vMax] and [PROTOCOL_MIN, PROTOCOL_MAX], or undefined when none.
+ */
+export function negotiateProtocol(vMin = 1, vMax = vMin): number | undefined {
+  const high = Math.min(vMax, PROTOCOL_MAX);
+  return high >= Math.max(vMin, PROTOCOL_MIN) ? high : undefined;
 }
 
 /**
@@ -596,7 +934,9 @@ function requireTransport(value: unknown): TransportState {
     !isFiniteNonNegative(state.beat) ||
     !isFiniteNonNegative(state.bpm) ||
     (state.bpm as number) <= 0 ||
-    !isFiniteNonNegative(state.atMs)
+    !isFiniteNonNegative(state.atMs) ||
+    (state.quantum !== undefined &&
+      (!isFiniteNonNegative(state.quantum) || (state.quantum as number) <= 0))
   )
     throw new ProtocolError("invalid", "transport is invalid");
   return {
@@ -605,6 +945,7 @@ function requireTransport(value: unknown): TransportState {
     beat: state.beat as number,
     bpm: state.bpm as number,
     atMs: state.atMs as number,
+    quantum: (state.quantum as number | undefined) ?? DEFAULT_QUANTUM,
   };
 }
 
@@ -616,6 +957,19 @@ function boundedText(value: unknown): string {
   return typeof value === "string" ? value.slice(0, 512) : "";
 }
 
+/**
+ * Rebases a transport anchor from the authority's host clock to this
+ * client's. `offsetMs` is (authority clock - local clock): 0 for every
+ * process on one machine, measured by a future relay for remote peers.
+ */
+export function toLocalTransport(
+  state: TransportState,
+  offsetMs: number,
+): TransportState {
+  if (offsetMs === 0) return state;
+  return { ...state, atMs: Math.max(0, state.atMs - offsetMs) };
+}
+
 /** Epoch-anchored monotonic milliseconds, comparable across local processes. */
 export function monotonicEpochMs(): number {
   return performance.timeOrigin + performance.now();

package/src/session/rebase.ts

@@ -2,17 +2,20 @@
  * Server-side rebase of agent operation intents.
  *
  * An agent validates its operations against the score at `base`. When other
- * windows committed in the meantime, dawgd replays the operations on the
+ * panes committed in the meantime, dawgd replays the operations on the
  * current score instead of rejecting, but only when nothing they touch
- * changed since `base`: the notes they update or remove, the tracks whose
- * settings or contents they rewrite, the tracks they add notes to, and the
+ * changed since `base`: the notes they update or remove, the track
+ * properties they patch (per track and field, so two panes can set
+ * different properties of one track), the tracks whose contents they clear, the tracks they add notes to, and the
  * tempo or length they set. Anything else is a conflict and the caller gets
  * the usual `rebase` reply. The reducer still validates every operation.
  */
 import {
   applyScoreOperation,
+  automationPoints,
   scoreFromJSON,
   type ScoreOperation,
+  type Track,
   type TrackScore,
 } from "../../core/score.ts";
 import { rewindComposition, type Rewind } from "./delta.ts";
@@ -83,12 +86,43 @@ export function rebaseOperations(
           return { ok: false, reason: `note ${operation.noteId} changed` };
         break;
       }
-      case "updateTrack":
-      case "setClips":
+      // Track settings conflict per (track, property): another pane's
+      // volume change never blocks this pane's pan, only its volume.
+      case "updateTrack": {
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const before = trackSettings(base, id);
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        for (const field of Object.keys(operation.patch) as (keyof Track)[])
+          if (!same(before?.[field] ?? null, now[field] ?? null))
+            return { ok: false, reason: `${id} ${String(field)} changed` };
+        break;
+      }
+      case "setClips": {
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        if (!same(trackSettings(base, id)?.clips ?? null, now.clips ?? null))
+          return { ok: false, reason: `${id} clips changed` };
+        break;
+      }
       case "setAutomation": {
-        if (added.tracks.has(operation.trackId)) break;
-        if (!settingsUnchanged(operation.trackId))
-          return { ok: false, reason: `track ${operation.trackId} changed` };
+        const id = operation.trackId;
+        if (added.tracks.has(id)) break;
+        const now = trackSettings(current, id);
+        if (!now) return { ok: false, reason: `track ${id} was removed` };
+        if (
+          !same(
+            automationPoints(trackSettings(base, id), operation.parameter),
+            automationPoints(now, operation.parameter),
+          )
+        )
+          return {
+            ok: false,
+            reason: `${id} ${operation.parameter} automation changed`,
+          };
         break;
       }
       case "clearTrack": {
@@ -144,6 +178,10 @@ export function rebaseOperations(
         )
           return { ok: false, reason: "sections changed" };
         break;
+      case "setLoop":
+        if (!deepEqual(base.loop, current.loop))
+          return { ok: false, reason: "loop changed" };
+        break;
       case "removeTrack": {
         if (added.tracks.has(operation.trackId)) break;
         if (

package/src/session/receipt.ts

@@ -151,6 +151,13 @@ export function receiptParts(
       case "setSections":
         parts.push(plural(op.sections.length, "section"));
         break;
+      case "setLoop":
+        parts.push(
+          op.loop
+            ? `loop ${op.loop.startBar + 1}–${op.loop.startBar + op.loop.bars}`
+            : "loop off",
+        );
+        break;
       case "setCalibration":
         break;
       case "addTrack": {