@hraness/dawg 0.6.1 → 0.8.0

package/src/session/presence.ts

@@ -4,6 +4,7 @@ import {
   readFile,
   rename,
   rm,
+  stat,
   writeFile,
 } from "node:fs/promises";
 import { join } from "node:path";
@@ -34,6 +35,7 @@ export class FilePresence {
   private timer: ReturnType<typeof setInterval> | undefined;
   private writing: Promise<void> = Promise.resolve();
   private writes = 0;
+  private stopped = false;
 
   public constructor(paths: SessionPaths, entry: PresenceEntry) {
     this.dir = `${paths.record}.presence`;
@@ -42,6 +44,7 @@ export class FilePresence {
   }
 
   public async start(): Promise<void> {
+    this.stopped = false;
     await this.write();
     this.timer = setInterval(
       () => void this.write().catch(() => {}),
@@ -51,8 +54,12 @@ export class FilePresence {
   }
 
   public async stop(): Promise<void> {
+    // A heartbeat already queued would otherwise rename its file back after
+    // the removal and leave a ghost entry.
+    this.stopped = true;
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
+    await this.writing;
     await rm(this.file(), { force: true });
   }
 
@@ -101,14 +108,17 @@ export class FilePresence {
 
   /** Live entries; stale or dead-process heartbeats are removed. */
   public async list(now = Date.now()): Promise<PresenceEntry[]> {
-    let names: string[];
+    let all: string[];
     try {
-      names = (await readdir(this.dir)).filter((name) =>
-        name.endsWith(".json"),
-      );
+      all = await readdir(this.dir);
     } catch {
       return [];
     }
+    // A writer that crashed between write and rename leaves its temp file.
+    for (const name of all.slice(0, MAX_PRESENCE_FILES))
+      if (name.endsWith(".tmp"))
+        await sweepTemporary(join(this.dir, name), now);
+    const names = all.filter((name) => name.endsWith(".json"));
     const entries: PresenceEntry[] = [];
     for (const name of names.slice(0, MAX_PRESENCE_FILES)) {
       const path = join(this.dir, name);
@@ -147,6 +157,7 @@ export class FilePresence {
   }
 
   private async writeNow(): Promise<void> {
+    if (this.stopped) return;
     await mkdir(this.dir, { recursive: true });
     const temporary = `${this.file()}.${process.pid}.${++this.writes}.tmp`;
     await writeFile(
@@ -154,10 +165,29 @@ export class FilePresence {
       JSON.stringify({ ...this.entry, at: Date.now() }),
       "utf8",
     );
+    if (this.stopped) {
+      await rm(temporary, { force: true });
+      return;
+    }
     await rename(temporary, this.file());
   }
 }
 
+/** Removes a temp file left by a dead writer, or one older than the stale window. */
+async function sweepTemporary(path: string, now: number): Promise<void> {
+  const pid = Number(/\.(\d+)\.\d+\.tmp$/.exec(path)?.[1]);
+  try {
+    const { mtimeMs } = await stat(path);
+    if (
+      now - mtimeMs > PRESENCE_STALE_MS ||
+      (Number.isSafeInteger(pid) && pid > 0 && !alive(pid))
+    )
+      await rm(path, { force: true });
+  } catch {
+    // Already renamed or removed by its writer.
+  }
+}
+
 function alive(pid: number): boolean {
   try {
     process.kill(pid, 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;
 }
 
 /**
@@ -551,7 +889,11 @@ function requireRecord(value: unknown): SessionRecord<unknown> {
     !Number.isSafeInteger(record.revision) ||
     typeof record.updatedAt !== "string" ||
     !Array.isArray(record.events) ||
-    record.events.length !== record.revision ||
+    (record.folded !== undefined &&
+      (!Number.isSafeInteger(record.folded) ||
+        (record.folded as number) < 1)) ||
+    record.events.length + ((record.folded as number | undefined) ?? 0) !==
+      record.revision ||
     record.composition === undefined
   )
     throw new ProtocolError("invalid", "record is invalid");
@@ -592,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 {
@@ -601,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,
   };
 }
 
@@ -612,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();