construction-gantt 0.1.0

package/src/calendars/nz-holidays.ts

@@ -0,0 +1,214 @@
+// NZ public-holiday + regional-anniversary pre-seed for the working-time
+// calendar engine. Hybrid generation: pure-TS rules for the holidays whose
+// observed date reduces to a formula; small static tables for the ones
+// that don't (Matariki — set by Act; Canterbury Show Day — set annually).
+//
+// Range supported: 2022 (Matariki Act adoption) through 2052 (last year
+// the Act pre-announces). Calls outside that range throw RangeError.
+
+import type { Calendar, CalendarException, CalendarId, WorkInterval } from '../types.js';
+import { CANTERBURY_DATES, CANTERBURY_RANGE } from './canterbury-table.js';
+import { computeEasterSunday } from './internal/computus.js';
+import { mondayisePair, mondayiseSingle } from './internal/mondayisation.js';
+import {
+  firstMondayAfter,
+  fridayBefore,
+  nearestMondayTo,
+  nthMondayOfMonth,
+} from './internal/month-rules.js';
+import { MATARIKI_DATES, MATARIKI_RANGE } from './matariki-table.js';
+
+/**
+ * The 13 statutory NZ regions with their own anniversary day, plus Northland
+ * which observes Waitangi Day per Holidays Act 2003 (no extra exception
+ * is added for `'northland'` — the region value is accepted, the
+ * national-only set is returned).
+ */
+export type NZRegion =
+  | 'auckland'
+  | 'canterbury'
+  | 'chatham-islands'
+  | 'hawkes-bay'
+  | 'marlborough'
+  | 'nelson'
+  | 'northland'
+  | 'otago'
+  | 'south-canterbury'
+  | 'southland'
+  | 'taranaki'
+  | 'wellington'
+  | 'westland';
+
+export interface NZDefaultCalendarOptions {
+  /** Year (single) or years (array). 2022 ≤ year ≤ 2052. Duplicates deduplicated. */
+  years: number | number[];
+  /** Optional regional anniversary on top of the 11 national holidays. */
+  region?: NZRegion;
+  /**
+   * Override the default Mon–Fri 8am–5pm working week.
+   * 7 entries, Sunday=0 … Saturday=6.
+   */
+  workWeek?: WorkInterval[][];
+  /** Calendar.id. Default: 'nz-default'. */
+  id?: CalendarId;
+  /** Calendar.name. Default: 'New Zealand Standard'. */
+  name?: string;
+}
+
+const MIN_YEAR = MATARIKI_RANGE.minYear; // 2022
+const MAX_YEAR = MATARIKI_RANGE.maxYear; // 2052
+
+const DEFAULT_INTERVAL: WorkInterval = { startMinutes: 8 * 60, endMinutes: 17 * 60 };
+const DEFAULT_WORK_WEEK: WorkInterval[][] = [
+  [], // Sun
+  [DEFAULT_INTERVAL], // Mon
+  [DEFAULT_INTERVAL], // Tue
+  [DEFAULT_INTERVAL], // Wed
+  [DEFAULT_INTERVAL], // Thu
+  [DEFAULT_INTERVAL], // Fri
+  [], // Sat
+];
+
+export function nzPublicHolidays(years: number | number[], region?: NZRegion): CalendarException[] {
+  const yearList = normaliseYears(years);
+  const all: CalendarException[] = [];
+  for (const year of yearList) {
+    all.push(...nationalHolidays(year));
+    if (region) {
+      const regional = regionalAnniversary(year, region);
+      if (regional) all.push(regional);
+    }
+  }
+  return all.sort((a, b) => a.date.getTime() - b.date.getTime());
+}
+
+function normaliseYears(input: number | number[]): number[] {
+  const list = Array.isArray(input) ? [...new Set(input)] : [input];
+  for (const y of list) {
+    if (y < MIN_YEAR || y > MAX_YEAR) {
+      throw new RangeError(
+        `nzPublicHolidays: year ${y} out of supported range ${MIN_YEAR}-${MAX_YEAR}. ` +
+          `Range is bounded by the Te Kāhui o Matariki Public Holiday Act 2022 Schedule 1.`,
+      );
+    }
+  }
+  return list.sort((a, b) => a - b);
+}
+
+function nationalHolidays(year: number): CalendarException[] {
+  const out: CalendarException[] = [];
+
+  // New Year + 2 January (pair rule)
+  const [ny, jan2] = mondayisePair(new Date(year, 0, 1), new Date(year, 0, 2));
+  out.push(makeException(ny, "New Year's Day", new Date(year, 0, 1)));
+  out.push(makeException(jan2, '2 January', new Date(year, 0, 2)));
+
+  // Waitangi Day (single-day mondayisation)
+  const waitangi = mondayiseSingle(new Date(year, 1, 6));
+  out.push(makeException(waitangi, 'Waitangi Day', new Date(year, 1, 6)));
+
+  // Good Friday + Easter Monday (Easter Sunday ± 2 / +1)
+  const easterSun = computeEasterSunday(year);
+  const goodFri = new Date(year, easterSun.getMonth(), easterSun.getDate() - 2);
+  const easterMon = new Date(year, easterSun.getMonth(), easterSun.getDate() + 1);
+  out.push(makeException(goodFri, 'Good Friday'));
+  out.push(makeException(easterMon, 'Easter Monday'));
+
+  // ANZAC Day (single-day mondayisation)
+  const anzac = mondayiseSingle(new Date(year, 3, 25));
+  out.push(makeException(anzac, 'ANZAC Day', new Date(year, 3, 25)));
+
+  // King's Birthday (first Monday of June)
+  out.push(makeException(nthMondayOfMonth(year, 5, 1), "King's Birthday"));
+
+  // Matariki (static table — guaranteed in range by the gate above)
+  // biome-ignore lint/style/noNonNullAssertion: year is range-gated 2022-2052; entry always present
+  out.push(makeException(MATARIKI_DATES[year]!, 'Matariki'));
+
+  // Labour Day (fourth Monday of October)
+  out.push(makeException(nthMondayOfMonth(year, 9, 4), 'Labour Day'));
+
+  // Christmas + Boxing Day (pair rule)
+  const [christmas, boxing] = mondayisePair(new Date(year, 11, 25), new Date(year, 11, 26));
+  out.push(makeException(christmas, 'Christmas Day', new Date(year, 11, 25)));
+  out.push(makeException(boxing, 'Boxing Day', new Date(year, 11, 26)));
+
+  return out;
+}
+
+function regionalAnniversary(year: number, region: NZRegion): CalendarException | null {
+  switch (region) {
+    case 'auckland':
+      return makeException(nearestMondayTo(year, 0, 29), 'Auckland Anniversary');
+    case 'wellington':
+      return makeException(nearestMondayTo(year, 0, 22), 'Wellington Anniversary');
+    case 'nelson':
+      return makeException(nearestMondayTo(year, 1, 1), 'Nelson Anniversary');
+    case 'otago':
+      return makeException(nearestMondayTo(year, 2, 23), 'Otago Anniversary');
+    case 'taranaki':
+      return makeException(nthMondayOfMonth(year, 2, 2), 'Taranaki Anniversary');
+    case 'southland': {
+      const easterSun = computeEasterSunday(year);
+      const easterTue = new Date(year, easterSun.getMonth(), easterSun.getDate() + 2);
+      return makeException(easterTue, 'Southland Anniversary');
+    }
+    case 'south-canterbury':
+      return makeException(nthMondayOfMonth(year, 8, 4), 'South Canterbury Anniversary');
+    case 'hawkes-bay': {
+      const labourDay = nthMondayOfMonth(year, 9, 4);
+      return makeException(fridayBefore(labourDay), "Hawke's Bay Anniversary");
+    }
+    case 'marlborough': {
+      const labourDay = nthMondayOfMonth(year, 9, 4);
+      return makeException(firstMondayAfter(labourDay), 'Marlborough Anniversary');
+    }
+    case 'canterbury': {
+      const date = CANTERBURY_DATES[year];
+      if (!date) {
+        throw new RangeError(
+          `nzPublicHolidays: Canterbury Anniversary Day for ${year} is not in the verified ` +
+            `static table (range ${CANTERBURY_RANGE.minYear}-${CANTERBURY_RANGE.maxYear}). ` +
+            `Show Day is set annually by the Canterbury A&P Association; ` +
+            `add the verified date from employment.govt.nz to canterbury-table.ts to extend coverage.`,
+        );
+      }
+      return makeException(date, 'Canterbury Anniversary');
+    }
+    case 'westland':
+      return makeException(nthMondayOfMonth(year, 11, 1), 'Westland Anniversary');
+    case 'chatham-islands':
+      return makeException(nearestMondayTo(year, 10, 30), 'Chatham Islands Anniversary');
+    case 'northland':
+      // Per Holidays Act 2003: Northland observes Waitangi Day as its
+      // anniversary. No extra exception is added.
+      return null;
+  }
+}
+
+function makeException(
+  observedDate: Date,
+  baseName: string,
+  statutoryDate?: Date,
+): CalendarException {
+  const moved =
+    statutoryDate &&
+    (observedDate.getFullYear() !== statutoryDate.getFullYear() ||
+      observedDate.getMonth() !== statutoryDate.getMonth() ||
+      observedDate.getDate() !== statutoryDate.getDate());
+  return {
+    date: new Date(observedDate.getFullYear(), observedDate.getMonth(), observedDate.getDate()),
+    isWorking: false,
+    name: moved ? `${baseName} (observed)` : baseName,
+  };
+}
+
+export function nzDefaultCalendar(options: NZDefaultCalendarOptions): Calendar {
+  const { years, region, workWeek, id, name } = options;
+  return {
+    id: id ?? 'nz-default',
+    name: name ?? 'New Zealand Standard',
+    workWeek: workWeek ?? DEFAULT_WORK_WEEK,
+    exceptions: nzPublicHolidays(years, region),
+  };
+}

package/src/editing/command-history.ts

@@ -0,0 +1,78 @@
+import type { Project } from '../types.js';
+import type { EditCommand } from './commands.js';
+
+/**
+ * Past/future command stacks for undo/redo. Immutable value type;
+ * every operation returns a new CommandHistory.
+ *
+ * Per ADR-006: a new pushCommand after undo clears the future stack
+ * (standard editor behaviour — new edit branches off).
+ */
+export interface CommandHistory {
+  readonly past: ReadonlyArray<EditCommand>;
+  readonly future: ReadonlyArray<EditCommand>;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+}
+
+export function newHistory(): CommandHistory {
+  return { past: [], future: [], canUndo: false, canRedo: false };
+}
+
+export function pushCommand(h: CommandHistory, command: EditCommand): CommandHistory {
+  return {
+    past: [...h.past, command],
+    future: [],
+    canUndo: true,
+    canRedo: false,
+  };
+}
+
+export interface UndoResult {
+  readonly nextHistory: CommandHistory;
+  readonly nextProject: Project;
+  readonly undoneCommand: EditCommand;
+}
+
+export function undo(h: CommandHistory, project: Project): UndoResult | null {
+  if (h.past.length === 0) return null;
+  const cmd = h.past[h.past.length - 1];
+  if (!cmd) return null; // unreachable under noUncheckedIndexedAccess; preserves type narrowing
+  const inverse = cmd.inverse(project);
+  const nextProject = inverse.apply(project);
+  const nextPast = h.past.slice(0, -1);
+  return {
+    nextHistory: {
+      past: nextPast,
+      future: [...h.future, cmd],
+      canUndo: nextPast.length > 0,
+      canRedo: true,
+    },
+    nextProject,
+    undoneCommand: cmd,
+  };
+}
+
+export interface RedoResult {
+  readonly nextHistory: CommandHistory;
+  readonly nextProject: Project;
+  readonly redoneCommand: EditCommand;
+}
+
+export function redo(h: CommandHistory, project: Project): RedoResult | null {
+  if (h.future.length === 0) return null;
+  const cmd = h.future[h.future.length - 1];
+  if (!cmd) return null; // unreachable under noUncheckedIndexedAccess; preserves type narrowing
+  const nextProject = cmd.apply(project);
+  const nextFuture = h.future.slice(0, -1);
+  return {
+    nextHistory: {
+      past: [...h.past, cmd],
+      future: nextFuture,
+      canUndo: true,
+      canRedo: nextFuture.length > 0,
+    },
+    nextProject,
+    redoneCommand: cmd,
+  };
+}

package/src/editing/commands.ts

@@ -0,0 +1,327 @@
+import type { Link, LinkId, Project, Task, TaskId } from '../types.js';
+import { EditError } from './errors.js';
+
+/**
+ * The contract every edit command must satisfy. apply must be pure
+ * (no mutation, no I/O) — returns a new Project. inverse(project)
+ * captures the state needed to reverse the edit when applied to the
+ * post-edit Project.
+ *
+ * Per ADR-006: every edit flows through schedule() recompute at the
+ * hook layer, not inside apply(). Commands operate on raw data only.
+ */
+export interface EditCommand {
+  /** Discriminator for command kind. */
+  readonly kind: string;
+  /** Human-readable label for UI undo text (e.g. "Rename Foundation pour"). */
+  readonly label: string;
+  /** Pure: applies the edit to a Project, returning a new Project. Throws EditError on invalid input. */
+  apply(project: Project): Project;
+  /**
+   * Returns an inverse command: applying inverse(P) on apply(P) yields P.
+   *
+   * Pre-edit state capture timing varies by command kind:
+   * - Create*Command: constructor argument is the inverse's only input
+   * - Update*Command, Delete*Command: snapshot pre-state internally during
+   *   apply() (single-use per instance). The `project` argument is
+   *   accepted for interface consistency but ignored.
+   *
+   * Consumers (CompositeCommand, CommandHistory) only need to call apply()
+   * before inverse() and pass the current project to inverse().
+   */
+  inverse(project: Project): EditCommand;
+}
+
+export class CreateTaskCommand implements EditCommand {
+  readonly kind = 'create-task';
+  readonly label: string;
+
+  constructor(
+    private readonly task: Task,
+    private readonly insertAt?: number,
+  ) {
+    this.label = `Create task "${task.text}"`;
+  }
+
+  apply(project: Project): Project {
+    if (project.tasks.some((t) => t.id === this.task.id)) {
+      throw new EditError(`duplicate task id ${String(this.task.id)}`, this.kind);
+    }
+    const tasks = [...project.tasks];
+    if (this.insertAt === undefined) {
+      tasks.push(this.task);
+    } else {
+      tasks.splice(this.insertAt, 0, this.task);
+    }
+    return { ...project, tasks };
+  }
+
+  inverse(_project: Project): EditCommand {
+    return new DeleteTaskCommand(this.task.id);
+  }
+}
+
+export class UpdateTaskCommand implements EditCommand {
+  readonly kind = 'update-task';
+  readonly label: string;
+  // Snapshot the pre-edit task state during apply() rather than reading it
+  // in inverse(project). Required because the patched fields in `project`
+  // at inverse() time are the post-edit values; the originals only survive
+  // via this capture. Side effect: each command instance is effectively
+  // single-use — calling apply() twice overwrites the snapshot, which
+  // is fine for the redo-then-undo flow but means consumers should not
+  // share a command instance across unrelated apply-sites.
+  private originalTask?: Task;
+
+  constructor(
+    private readonly taskId: TaskId,
+    private readonly patch: Partial<Task>,
+    customLabel?: string,
+  ) {
+    if (customLabel !== undefined) {
+      this.label = customLabel;
+    } else {
+      const keys = Object.keys(patch);
+      this.label =
+        keys.length === 1
+          ? `Update task "${String(taskId)}" (${keys[0]})`
+          : `Update task "${String(taskId)}"`;
+    }
+  }
+
+  apply(project: Project): Project {
+    const idx = project.tasks.findIndex((t) => t.id === this.taskId);
+    if (idx === -1) {
+      throw new EditError(`missing task ${String(this.taskId)}`, this.kind);
+    }
+    const tasks = [...project.tasks];
+    this.originalTask = tasks[idx];
+    tasks[idx] = Object.assign({}, tasks[idx], this.patch);
+    return { ...project, tasks };
+  }
+
+  inverse(_project: Project): EditCommand {
+    if (!this.originalTask) {
+      throw new EditError(`inverse: apply() was not called on this command`, this.kind);
+    }
+    // Capture the value of each patched key from the original task.
+    const previousPatch: Partial<Task> = {};
+    for (const key of Object.keys(this.patch)) {
+      const k = key as keyof Task;
+      (previousPatch as Record<keyof Task, unknown>)[k] = (
+        this.originalTask as Record<keyof Task, unknown>
+      )[k];
+    }
+    return new UpdateTaskCommand(this.taskId, previousPatch);
+  }
+}
+
+export class DeleteTaskCommand implements EditCommand {
+  readonly kind = 'delete-task';
+  readonly label: string;
+  // Snapshot pre-state during apply() — same pattern as UpdateTaskCommand.
+  // Required because CommandHistory.undo calls cmd.inverse(currentProject)
+  // where currentProject is the POST-delete state (no longer has the task
+  // or its incident links to read from).
+  private snapshot?: {
+    task: Task;
+    taskIndex: number;
+    // Captured as (linkIndex, link) pairs to restore at original positions.
+    incidentLinkPositions: Array<[number, Link]>;
+  };
+
+  constructor(private readonly taskId: TaskId) {
+    this.label = `Delete task "${String(taskId)}"`;
+  }
+
+  apply(project: Project): Project {
+    const target = project.tasks.find((t) => t.id === this.taskId);
+    if (!target) {
+      throw new EditError(`missing task ${String(this.taskId)}`, this.kind);
+    }
+    const taskIndex = project.tasks.indexOf(target);
+    // Capture incident links with their original indices.
+    const incidentLinkPositions: Array<[number, Link]> = [];
+    for (let i = 0; i < project.links.length; i++) {
+      const link = project.links[i];
+      if (link && (link.source === this.taskId || link.target === this.taskId)) {
+        incidentLinkPositions.push([i, link]);
+      }
+    }
+    this.snapshot = { task: target, taskIndex, incidentLinkPositions };
+
+    const tasks = project.tasks.filter((t) => t.id !== this.taskId);
+    const links = project.links.filter((l) => l.source !== this.taskId && l.target !== this.taskId);
+    return { ...project, tasks, links };
+  }
+
+  inverse(_project: Project): EditCommand {
+    if (!this.snapshot) {
+      throw new EditError(`inverse: apply() was not called on this command`, this.kind);
+    }
+    const snapshotData = this.snapshot;
+    const { task: snapshotTask, taskIndex, incidentLinkPositions } = snapshotData;
+
+    // Return an ad-hoc EditCommand that restores both task + links atomically.
+    // Not exported — only reachable as the inverse of DeleteTaskCommand.
+    const restoreCommand: EditCommand = {
+      kind: 'restore-task',
+      label: `Restore task "${String(this.taskId)}"`,
+      apply(p: Project): Project {
+        if (p.tasks.some((t) => t.id === snapshotTask.id)) {
+          throw new EditError(`duplicate task id ${String(snapshotTask.id)}`, 'restore-task');
+        }
+        // Restore task at original index (clamped to current length).
+        const tasks = [...p.tasks];
+        const insertTaskAt = Math.min(taskIndex, tasks.length);
+        tasks.splice(insertTaskAt, 0, snapshotTask);
+
+        // Restore links at their original indices, adjusting for deletions.
+        // INVARIANT: incidentLinkPositions is guaranteed ascending-by-index
+        // because the capture loop in apply() walks 0..N. Splice-in-place
+        // only produces the correct final order when fed sorted-ascending
+        // positions — if a future refactor breaks the capture order, this
+        // restoration breaks silently. If insertion order ever becomes
+        // unsortable, switch to a single-pass rebuild keyed on original idx.
+        const links = [...p.links];
+        for (const [originalIdx, link] of incidentLinkPositions) {
+          links.splice(originalIdx, 0, link);
+        }
+
+        return {
+          ...p,
+          tasks,
+          links,
+        };
+      },
+      inverse(_p: Project): EditCommand {
+        return new DeleteTaskCommand(snapshotTask.id);
+      },
+    };
+    return restoreCommand;
+  }
+}
+
+export class CreateLinkCommand implements EditCommand {
+  readonly kind = 'create-link';
+  readonly label: string;
+
+  constructor(private readonly link: Link) {
+    this.label = `Link ${String(link.source)} → ${String(link.target)}`;
+  }
+
+  apply(project: Project): Project {
+    if (this.link.source === this.link.target) {
+      throw new EditError(`self-link not allowed (${String(this.link.source)})`, this.kind);
+    }
+    if (project.links.some((l) => l.id === this.link.id)) {
+      throw new EditError(`duplicate link id ${String(this.link.id)}`, this.kind);
+    }
+    if (!project.tasks.some((t) => t.id === this.link.source)) {
+      throw new EditError(`source task ${String(this.link.source)} not found`, this.kind);
+    }
+    if (!project.tasks.some((t) => t.id === this.link.target)) {
+      throw new EditError(`target task ${String(this.link.target)} not found`, this.kind);
+    }
+    return { ...project, links: [...project.links, this.link] };
+  }
+
+  inverse(_project: Project): EditCommand {
+    return new DeleteLinkCommand(this.link.id);
+  }
+}
+
+export class UpdateLinkCommand implements EditCommand {
+  readonly kind = 'update-link';
+  readonly label: string;
+  // Snapshot pre-edit link state during apply() — same pattern as
+  // UpdateTaskCommand. Required for snapshot-at-apply inverse semantics.
+  private originalLink?: Link;
+
+  constructor(
+    private readonly linkId: LinkId,
+    private readonly patch: Partial<Link>,
+    customLabel?: string,
+  ) {
+    this.label = customLabel ?? `Update link "${String(linkId)}"`;
+  }
+
+  apply(project: Project): Project {
+    const target = project.links.find((l) => l.id === this.linkId);
+    if (!target) {
+      throw new EditError(`missing link ${String(this.linkId)}`, this.kind);
+    }
+    const idx = project.links.indexOf(target);
+    const links = [...project.links];
+    this.originalLink = target;
+    links[idx] = Object.assign({}, target, this.patch);
+    return { ...project, links };
+  }
+
+  inverse(_project: Project): EditCommand {
+    if (!this.originalLink) {
+      throw new EditError(`inverse: apply() was not called on this command`, this.kind);
+    }
+    const previousPatch: Partial<Link> = {};
+    for (const key of Object.keys(this.patch)) {
+      const k = key as keyof Link;
+      (previousPatch as Record<keyof Link, unknown>)[k] = (
+        this.originalLink as Record<keyof Link, unknown>
+      )[k];
+    }
+    return new UpdateLinkCommand(this.linkId, previousPatch);
+  }
+}
+
+export class DeleteLinkCommand implements EditCommand {
+  readonly kind = 'delete-link';
+  readonly label: string;
+  // Snapshot link + original index during apply() so inverse restores at
+  // its original position in the array (preserving order).
+  private snapshot?: { link: Link; linkIndex: number };
+
+  constructor(private readonly linkId: LinkId) {
+    this.label = `Delete link "${String(linkId)}"`;
+  }
+
+  apply(project: Project): Project {
+    const target = project.links.find((l) => l.id === this.linkId);
+    if (!target) {
+      throw new EditError(`missing link ${String(this.linkId)}`, this.kind);
+    }
+    const linkIndex = project.links.indexOf(target);
+    this.snapshot = { link: target, linkIndex };
+    return {
+      ...project,
+      links: project.links.filter((l) => l.id !== this.linkId),
+    };
+  }
+
+  inverse(_project: Project): EditCommand {
+    if (!this.snapshot) {
+      throw new EditError(`inverse: apply() was not called on this command`, this.kind);
+    }
+    const { link: snapshotLink, linkIndex } = this.snapshot;
+    const linkId = this.linkId;
+    // Ad-hoc 'restore-link' command — not exported. Unlike DeleteTaskCommand's
+    // 'restore-task' (which also restores incident links), a link has no
+    // incident dependencies — just re-insert it at its original index.
+    const restoreCommand: EditCommand = {
+      kind: 'restore-link',
+      label: `Restore link "${String(linkId)}"`,
+      apply(p: Project): Project {
+        if (p.links.some((l) => l.id === snapshotLink.id)) {
+          throw new EditError(`duplicate link id ${String(snapshotLink.id)}`, 'restore-link');
+        }
+        const links = [...p.links];
+        const insertAt = Math.min(linkIndex, links.length);
+        links.splice(insertAt, 0, snapshotLink);
+        return { ...p, links };
+      },
+      inverse(_p: Project): EditCommand {
+        return new DeleteLinkCommand(snapshotLink.id);
+      },
+    };
+    return restoreCommand;
+  }
+}

package/src/editing/composite-command.ts

@@ -0,0 +1,64 @@
+import type { Project } from '../types.js';
+import type { EditCommand } from './commands.js';
+
+/**
+ * Wraps N EditCommands into a single history entry. Apply runs each
+ * member in order; if any throws, the whole composite throws (caller
+ * sees a single error — the no-partial-output guarantee). Inverse walks
+ * members in REVERSE order, collecting each member's inverse — which
+ * reads from the snapshot captured during the member's apply.
+ *
+ * Single-use semantics: composite.apply() MUST be called before
+ * composite.inverse(), because the stateful member commands
+ * (Update*Command, Delete*Command) only have their snapshots after
+ * apply(). Calling inverse() without apply() throws the underlying
+ * member's "apply() was not called" EditError.
+ *
+ * **Contract caveat for members.** This implementation assumes every
+ * member is either stateless (Create*Command — its inverse derives
+ * from constructor args) or uses the snapshot-at-apply pattern (the
+ * built-in Update*Command and Delete*Command). The `_project` arg
+ * passed to each member's `inverse()` here is the composite's `_project`
+ * (the post-composite-apply state), NOT the post-member-apply state
+ * for that particular member. Built-in stateful commands ignore the
+ * arg and read their own snapshot, so this works correctly.
+ *
+ * If a future EditCommand implementation needs the actual post-member-
+ * apply state inside a composite, the implementation must either:
+ *   (a) adopt snapshot-at-apply itself (recommended — matches built-ins),
+ *   (b) extend CompositeCommand to walk the apply chain and pass each
+ *       member its specific post-state to inverse().
+ *
+ * Produced by DraftProject.commit() when N>1 pending commands need to
+ * land as one history entry. Single-pending-command commits return
+ * the member directly without wrapping (per DraftProject contract).
+ */
+export class CompositeCommand implements EditCommand {
+  readonly kind = 'composite';
+  readonly label: string;
+  readonly members: ReadonlyArray<EditCommand>;
+
+  constructor(members: ReadonlyArray<EditCommand>, label: string) {
+    this.members = members;
+    this.label = label;
+  }
+
+  apply(project: Project): Project {
+    let cur = project;
+    for (const cmd of this.members) {
+      cur = cmd.apply(cur);
+    }
+    return cur;
+  }
+
+  inverse(_project: Project): EditCommand {
+    // Members store their own pre-state via snapshot-at-apply. We just
+    // collect each member's inverse in reverse order.
+    const inverses: EditCommand[] = [];
+    const reversed = [...this.members].reverse();
+    for (const cmd of reversed) {
+      inverses.push(cmd.inverse(_project));
+    }
+    return new CompositeCommand(inverses, `Undo: ${this.label}`);
+  }
+}