@hraness/dawg 0.2.0 → 0.4.0

package/src/session/attach.ts

@@ -38,8 +38,8 @@ export class SessionLookupError extends Error {
 }
 
 /**
- * Maps `--session <name|id>` to a session id. Unknown values pass through
- * unchanged when they are valid ids (a new session with that id is created);
+ * Maps `--session <name|id>` to the id of an existing session. An unknown
+ * value throws (a typo must not create a new session; `--new` does that);
  * an ambiguous name throws with the candidate list.
  */
 export async function resolveSessionArg(
@@ -54,8 +54,7 @@ export async function resolveSessionArg(
     throw new SessionLookupError(
       ambiguousSessionMessage(query, result.candidates),
     );
-  if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(query)) return query;
-  throw new SessionLookupError(`no session named "${query}"`);
+  throw new SessionLookupError(`no session named "${query}" · dawg sessions`);
 }
 
 export type TrackAttachment = {

package/src/session/daemon.ts

@@ -95,6 +95,21 @@ export class DawgDaemon {
     this.graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
     this.audio = new AudioEngine({
       lockPath: `${this.paths.record}.audio.lock`,
+      projectRoot: options.workspace,
+      onStatus: (status) => {
+        void this.log(`audio: ${status.message}`);
+        // A player that keeps dying must not leave a silent "playing" transport.
+        if (status.state === "stopped" && this.clock.playing) {
+          this.clock.pause();
+          this.broadcastTransport();
+        }
+        this.broadcast({
+          v: 1,
+          type: "error",
+          code: "audio",
+          message: status.message,
+        });
+      },
     });
   }
 
@@ -158,7 +173,7 @@ export class DawgDaemon {
   private async shutdown(reason: string): Promise<void> {
     if (this.graceTimer) clearTimeout(this.graceTimer);
     if (this.diskTimer) clearInterval(this.diskTimer);
-    await this.audio.stopAsync();
+    await this.audio.dispose();
     for (const client of this.clients) client.socket.destroy();
     this.clients.clear();
     await this.queue.catch(() => undefined);
@@ -427,18 +442,16 @@ export class DawgDaemon {
         message: error instanceof Error ? error.message : String(error),
       };
     }
-    // Every event records the score it replaced (`before`) so undo and later
-    // rebases can recover it; after a rebase that is the score replayed on.
+    // The store records how to rewind every event, so undo and later rebases
+    // can recover the score it replaced; a rebased event also notes its base.
     const payload =
+      rebased &&
       typeof message.payload === "object" &&
       message.payload !== null &&
       !Array.isArray(message.payload)
         ? {
             ...(message.payload as Record<string, unknown>),
-            ...(rebased || !("before" in message.payload)
-              ? { before: this.record.composition }
-              : {}),
-            ...(rebased ? { rebasedFrom: message.base } : {}),
+            rebasedFrom: message.base,
           }
         : message.payload;
     const previousTempo = this.score.tempoBpm;
@@ -506,7 +519,7 @@ export class DawgDaemon {
       this.record.revision - revision > MAX_REBASE_DISTANCE
     )
       return undefined;
-    const composition = compositionAt(this.record.events, revision);
+    const composition = compositionAt(this.record, revision);
     if (composition === undefined) return undefined;
     try {
       return scoreFromJSON(composition);
@@ -678,6 +691,10 @@ const OPERATION_TYPES = new Set([
   "updateTrack",
   "setAutomation",
   "clearTrack",
+  "removeTrack",
+  "moveTrack",
+  "setKey",
+  "setMeter",
 ]);
 
 /** Shape gate before the reducer, which validates every field it reads. */

package/src/session/delta.ts

@@ -0,0 +1,249 @@
+/**
+ * Reverse deltas for session history.
+ *
+ * Every event stores a `rewind`: how to turn the composition it produced back
+ * into the one it replaced, instead of the whole previous composition.
+ * Objects diff per key, arrays of `{id}` objects diff per id and position,
+ * and anything else is replaced wholesale. Applying the rewinds of the newest
+ * events in reverse order recovers any older composition, which is what undo
+ * and the daemon's rebase need. A single-note edit costs about 150 bytes
+ * instead of a full copy of the score, so the record stays small and the
+ * session never becomes un-editable.
+ */
+export type Rewind =
+  /** The value in the earlier composition (also used for a key that was removed). */
+  | { set: unknown }
+  /** The key did not exist in the earlier composition. */
+  | { del: true }
+  /** Per-key rewinds for a plain object. */
+  | { obj: Record<string, Rewind> }
+  /**
+   * An array of `{id}` objects: remove the items at `drop` (indices into the
+   * later array), then place `put` values at their earlier indices.
+   */
+  | { arr: { drop: number[]; put: [number, unknown][] } };
+
+const MAX_DEPTH = 16;
+
+/** Applying this rewind changes nothing. */
+export const IDENTITY_REWIND: Rewind = Object.freeze({ obj: {} }) as Rewind;
+
+export function isIdentityRewind(value: Rewind | undefined): boolean {
+  return (
+    value !== undefined && "obj" in value && Object.keys(value.obj).length === 0
+  );
+}
+
+/** The rewind that turns `after` back into `before`; identity when equal. */
+export function diffRewind(before: unknown, after: unknown): Rewind {
+  return diff(before, after, 0) ?? IDENTITY_REWIND;
+}
+
+function diff(
+  before: unknown,
+  after: unknown,
+  depth: number,
+): Rewind | undefined {
+  if (depth >= MAX_DEPTH)
+    return deepEqual(before, after) ? undefined : { set: before };
+  if (isPlainObject(before) && isPlainObject(after)) {
+    const obj: Record<string, Rewind> = {};
+    for (const key of Object.keys(before)) {
+      if (!(key in after) || after[key] === undefined)
+        obj[key] = { set: before[key] };
+      else {
+        const child = diff(before[key], after[key], depth + 1);
+        if (child) obj[key] = child;
+      }
+    }
+    for (const key of Object.keys(after))
+      if (!(key in before) || before[key] === undefined)
+        obj[key] = { del: true };
+    return Object.keys(obj).length === 0 ? undefined : { obj };
+  }
+  if (isKeyedArray(before) && isKeyedArray(after)) {
+    const beforeIndex = new Map<string, number>();
+    before.forEach((item, index) => beforeIndex.set(item.id, index));
+    // Greedy common subsequence by id: an item is kept when it is unchanged
+    // and keeps its relative order. Edits touch few items, so this is near
+    // optimal and always correct; a full reorder degrades to a full copy.
+    const kept = new Set<number>();
+    const drop: number[] = [];
+    let last = -1;
+    after.forEach((item, index) => {
+      const at = beforeIndex.get(item.id);
+      if (at !== undefined && at > last && deepEqual(before[at], item)) {
+        kept.add(at);
+        last = at;
+      } else drop.push(index);
+    });
+    const put: [number, unknown][] = [];
+    before.forEach((item, index) => {
+      if (!kept.has(index)) put.push([index, item]);
+    });
+    return drop.length === 0 && put.length === 0
+      ? undefined
+      : { arr: { drop, put } };
+  }
+  return deepEqual(before, after) ? undefined : { set: before };
+}
+
+/** The earlier value: `rewind` applied to `after`. Throws on a shape mismatch. */
+export function applyRewind(after: unknown, rewind: Rewind): unknown {
+  if ("set" in rewind) return rewind.set;
+  if ("del" in rewind) return undefined;
+  if ("obj" in rewind) {
+    // The identity rewind applies to any value, not only objects.
+    if (isIdentityRewind(rewind)) return after;
+    if (!isPlainObject(after)) throw new Error("rewind expects an object");
+    const result: Record<string, unknown> = { ...after };
+    for (const [key, child] of Object.entries(rewind.obj)) {
+      if ("del" in child) delete result[key];
+      else result[key] = applyRewind(result[key], child);
+    }
+    return result;
+  }
+  if (!Array.isArray(after)) throw new Error("rewind expects an array");
+  const dropped = new Set(rewind.arr.drop);
+  const kept: unknown[] = [];
+  after.forEach((item, index) => {
+    if (!dropped.has(index)) kept.push(item);
+  });
+  const put = new Map(rewind.arr.put);
+  const length = kept.length + put.size;
+  const result: unknown[] = [];
+  let next = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (put.has(index)) result.push(put.get(index));
+    else {
+      if (next >= kept.length) throw new Error("rewind indices are invalid");
+      result.push(kept[next]);
+      next += 1;
+    }
+  }
+  if (next !== kept.length) throw new Error("rewind indices are invalid");
+  return result;
+}
+
+/**
+ * The composition before `events[index]`, by rewinding `composition` (the
+ * one after the last event) through every later event. Undefined when any
+ * event in that range has no usable rewind.
+ */
+export function rewindComposition(
+  composition: unknown,
+  events: readonly { rewind?: Rewind | undefined }[],
+  index: number,
+): unknown {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= events.length)
+    return undefined;
+  let value = composition;
+  try {
+    for (let at = events.length - 1; at >= index; at -= 1) {
+      const rewind = events[at]!.rewind;
+      if (rewind === undefined) return undefined;
+      value = applyRewind(value, rewind);
+    }
+  } catch {
+    return undefined;
+  }
+  return value;
+}
+
+/** Validates a stored rewind from `unknown`; `undefined` when absent. */
+export function parseRewind(value: unknown): Rewind | undefined {
+  if (value === undefined) return undefined;
+  return parse(value, 0);
+}
+
+function parse(value: unknown, depth: number): Rewind {
+  if (!isPlainObject(value) || depth > MAX_DEPTH)
+    throw new Error("session event rewind is invalid");
+  const keys = Object.keys(value);
+  if (keys.length !== 1) throw new Error("session event rewind is invalid");
+  if ("set" in value) {
+    if (value.set === undefined)
+      throw new Error("session event rewind is invalid");
+    return { set: value.set };
+  }
+  if ("del" in value) {
+    if (value.del !== true) throw new Error("session event rewind is invalid");
+    return { del: true };
+  }
+  if ("obj" in value) {
+    if (!isPlainObject(value.obj))
+      throw new Error("session event rewind is invalid");
+    const obj: Record<string, Rewind> = {};
+    for (const [key, child] of Object.entries(value.obj))
+      obj[key] = parse(child, depth + 1);
+    return { obj };
+  }
+  if ("arr" in value && isPlainObject(value.arr)) {
+    const { drop, put } = value.arr;
+    if (
+      !Array.isArray(drop) ||
+      !Array.isArray(put) ||
+      !drop.every((index) => Number.isSafeInteger(index) && index >= 0) ||
+      !put.every(
+        (entry) =>
+          Array.isArray(entry) &&
+          entry.length === 2 &&
+          Number.isSafeInteger(entry[0]) &&
+          entry[0] >= 0 &&
+          entry[1] !== undefined,
+      )
+    )
+      throw new Error("session event rewind is invalid");
+    return {
+      arr: {
+        drop: drop as number[],
+        put: put.map((entry) => [entry[0], entry[1]] as [number, unknown]),
+      },
+    };
+  }
+  throw new Error("session event rewind is invalid");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isKeyedArray(value: unknown): value is { id: string }[] {
+  if (!Array.isArray(value)) return false;
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (!isPlainObject(item) || typeof item.id !== "string") return false;
+    if (seen.has(item.id)) return false;
+    seen.add(item.id);
+  }
+  return true;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  )
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const other = b as unknown[];
+    if (a.length !== other.length) return false;
+    for (let index = 0; index < a.length; index += 1)
+      if (!deepEqual(a[index], other[index])) return false;
+    return true;
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left).filter((key) => left[key] !== undefined);
+  const otherKeys = Object.keys(right).filter(
+    (key) => right[key] !== undefined,
+  );
+  if (keys.length !== otherKeys.length) return false;
+  for (const key of keys)
+    if (!(key in right) || !deepEqual(left[key], right[key])) return false;
+  return true;
+}

package/src/session/naming.ts

@@ -13,6 +13,9 @@
 import { createHash } from "node:crypto";
 import type { TrackScore } from "../../core/score.ts";
 import { isDrumInstrument } from "../../core/drums.ts";
+import { estimateKey } from "../../core/key.ts";
+
+export { estimateKey };
 import type { ProviderSelection } from "../agent/provider.ts";
 import {
   DEFAULT_SESSION_NAME,
@@ -27,22 +30,6 @@ import {
 export const NAME_MAX_TOKENS = 12;
 export const NAME_TEMPERATURE = 0.3;
 const PROMPT_SNIPPET_CHARS = 60;
-const NOTE_NAMES = [
-  "c",
-  "c#",
-  "d",
-  "eb",
-  "e",
-  "f",
-  "f#",
-  "g",
-  "ab",
-  "a",
-  "bb",
-  "b",
-] as const;
-const MAJOR = [0, 2, 4, 5, 7, 9, 11];
-const MINOR = [0, 2, 3, 5, 7, 8, 10];
 
 export type TrackRole = "drums" | "bass" | "keys" | "lead";
 
@@ -102,13 +89,15 @@ export function musicalFingerprint(score: TrackScore): Fingerprint {
     if (track.filter) effects.add("filter");
     if (track.delay) effects.add("delay");
     if (track.reverb) effects.add("reverb");
+    for (const name of Object.keys(track.fx ?? {})) effects.add(name);
     if (track.volumeAutomation.length || track.panAutomation.length)
       effects.add("automation");
     if (
       track.filterAutomation?.length ||
       track.resonanceAutomation?.length ||
       track.delayFeedbackAutomation?.length ||
-      track.delayMixAutomation?.length
+      track.delayMixAutomation?.length ||
+      Object.keys(track.fxAutomation ?? {}).length
     )
       effects.add("sweep");
     const instrument = track.instrument.toLowerCase().slice(0, 24);
@@ -141,27 +130,6 @@ export function musicalFingerprint(score: TrackScore): Fingerprint {
   };
 }
 
-/** Best-fitting major or minor scale for a pitch-class histogram, or null. */
-export function estimateKey(histogram: readonly number[]): string | null {
-  const total = histogram.reduce((sum, value) => sum + value, 0);
-  if (total <= 0) return null;
-  let best: { key: string; score: number } | undefined;
-  for (let tonic = 0; tonic < 12; tonic += 1) {
-    for (const [mode, scale] of [
-      ["major", MAJOR],
-      ["minor", MINOR],
-    ] as const) {
-      let fit = 0;
-      for (const step of scale) fit += histogram[(tonic + step) % 12]!;
-      // Tonic and fifth weigh extra so relative keys separate.
-      fit += histogram[tonic]! * 0.75 + histogram[(tonic + 7) % 12]! * 0.25;
-      if (!best || fit > best.score + 1e-9)
-        best = { key: `${NOTE_NAMES[tonic]} ${mode}`, score: fit };
-    }
-  }
-  return best!.key;
-}
-
 /** Deterministic offline name, e.g. "a minor bass groove" or "128 bpm drums + keys". */
 export function localName(fingerprint: Fingerprint): string {
   const roles = fingerprint.roles;

package/src/session/port.ts

@@ -56,6 +56,8 @@ export type WindowPlayer = {
   /** Start at `beat`, or swap a playing loop in place (gapless engine). */
   play(score: TrackScore, beat?: number): Promise<void>;
   stop(): void;
+  /** Stops and releases the render worker; the player is done for good. */
+  dispose(): Promise<void>;
 };
 
 /**
@@ -65,6 +67,8 @@ export type WindowPlayer = {
  */
 export interface SessionPort<T> {
   readonly mode: "daemon" | "file";
+  /** This window's presence id, to exclude itself from `presence()`. */
+  readonly clientId: string;
   /** Human-readable status for the activity line. */
   readonly status: string;
   readonly player: WindowPlayer;
@@ -157,10 +161,12 @@ export async function openSessionPort<T>(
 const silentPlayer: WindowPlayer = {
   play: async () => undefined,
   stop: () => undefined,
+  dispose: async () => undefined,
 };
 
 class DaemonPort<T> implements SessionPort<T> {
   public readonly mode = "daemon" as const;
+  public readonly clientId: string;
   public readonly player = silentPlayer;
   public status: string;
   public sync: SyncStatus = "synced";
@@ -168,6 +174,7 @@ class DaemonPort<T> implements SessionPort<T> {
 
   public constructor(private readonly client: DaemonClient) {
     this.status = `dawgd pid ${client.daemonPid}`;
+    this.clientId = client.clientId;
   }
 
   private setSync(sync: SyncStatus): void {
@@ -303,17 +310,24 @@ class DaemonPort<T> implements SessionPort<T> {
 
 class FilePort<T> implements SessionPort<T> {
   public readonly mode = "file" as const;
+  public readonly clientId = randomUUID();
   public status = "file session";
   public readonly sync = "local" as const;
   public readonly player: WindowPlayer;
   private readonly presenceStore: FilePresence;
+  private readonly statusListeners = new Set<(update: PortUpdate<T>) => void>();
 
   private constructor(private readonly options: OpenPortOptions) {
     this.player = new AudioEngine({
       lockPath: `${options.paths.record}.audio.lock`,
+      projectRoot: dirname(options.paths.root),
+      onStatus: (status) => {
+        for (const listener of this.statusListeners)
+          listener({ type: "status", message: status.message });
+      },
     });
     this.presenceStore = new FilePresence(options.paths, {
-      clientId: randomUUID(),
+      clientId: this.clientId,
       pid: process.pid,
       label: options.label.slice(0, 128),
       focusedTrackId: options.focusedTrackId,
@@ -393,13 +407,17 @@ class FilePort<T> implements SessionPort<T> {
         });
     };
     const recordName = basename(this.options.paths.record);
+    // macOS coalesces the temp write and the rename into events named after
+    // the temp file (`<record>.<pid>.tmp`), so match that too, but not the
+    // sibling `.audio.lock` / `.daemon.log` files that share the prefix.
+    const recordFile = new RegExp(
+      `^${recordName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\.\\d+\\.tmp)?$`,
+    );
     let watcher: FSWatcher | undefined;
     try {
       watcher = watch(dirname(this.options.paths.record), (_event, file) => {
-        // macOS coalesces the temp write and the rename into events named
-        // after the temp file (`<record>.<pid>.tmp`), so match the prefix and
-        // re-check shortly after in case the event preceded the rename.
-        if (file !== null && !String(file).startsWith(recordName)) return;
+        // Re-check shortly after in case the event preceded the rename.
+        if (file !== null && !recordFile.test(String(file))) return;
         check();
         setTimeout(check, 40).unref?.();
       });
@@ -412,9 +430,11 @@ class FilePort<T> implements SessionPort<T> {
       watcher = undefined;
     }
     const timer = setInterval(check, watcher ? WATCHED_POLL_MS : POLL_MS);
+    this.statusListeners.add(listener);
     check();
     return () => {
       closed = true;
+      this.statusListeners.delete(listener);
       clearInterval(timer);
       watcher?.close();
     };
@@ -455,7 +475,7 @@ class FilePort<T> implements SessionPort<T> {
   }
 
   public async close(): Promise<void> {
-    this.player.stop();
+    void this.player.dispose();
     await this.presenceStore.stop();
   }
 }

package/src/session/rebase.ts

@@ -15,6 +15,7 @@ import {
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
+import { rewindComposition, type Rewind } from "./delta.ts";
 
 /** How far behind a base may be and still be rebased. */
 export const MAX_REBASE_DISTANCE = 64;
@@ -105,6 +106,30 @@ export function rebaseOperations(
         if (base.bars !== current.bars)
           return { ok: false, reason: "loop length changed" };
         break;
+      case "setKey":
+        if (base.key !== current.key)
+          return { ok: false, reason: "key changed" };
+        break;
+      case "setMeter":
+        if (base.beatsPerBar !== current.beatsPerBar)
+          return { ok: false, reason: "meter changed" };
+        break;
+      case "removeTrack": {
+        if (added.tracks.has(operation.trackId)) break;
+        if (
+          !settingsUnchanged(operation.trackId) ||
+          !notesUnchanged(operation.trackId)
+        )
+          return { ok: false, reason: `track ${operation.trackId} changed` };
+        break;
+      }
+      case "moveTrack": {
+        const order = (score: TrackScore) =>
+          score.tracks.map((track) => track.id).join("\u0000");
+        if (order(base) !== order(current))
+          return { ok: false, reason: "track order changed" };
+        break;
+      }
       default:
         return { ok: false, reason: "unsupported operation" };
     }
@@ -123,16 +148,21 @@ export function rebaseOperations(
 }
 
 /**
- * The composition at revision `revision`, recovered from the `before` of the
- * event that replaced it. Undefined when the log cannot vouch for it.
+ * The composition at revision `revision`, recovered by rewinding the current
+ * composition through every later event's `rewind`. Undefined when the log
+ * cannot vouch for it (a gap in revisions, or a rewind compacted away).
  */
 export function compositionAt(
-  events: readonly { revision: number; payload: unknown }[],
+  record: {
+    composition: unknown;
+    events: readonly { revision: number; rewind?: Rewind | undefined }[];
+  },
   revision: number,
 ): unknown {
-  const event = events[revision];
-  if (event === undefined || event.revision !== revision + 1) return undefined;
-  const payload = event.payload;
-  if (typeof payload !== "object" || payload === null) return undefined;
-  return (payload as { before?: unknown }).before;
+  const { events } = record;
+  if (!Number.isSafeInteger(revision) || revision < 0) return undefined;
+  if (revision >= events.length) return undefined;
+  for (let index = revision; index < events.length; index += 1)
+    if (events[index]!.revision !== index + 1) return undefined;
+  return rewindComposition(record.composition, events, revision);
 }