@1agh/maude 1.2.0 → 1.3.0

package/apps/studio/sync/accepted-link.ts

@@ -0,0 +1,320 @@
+// The studio's side of accepted revisions — DDR-241 §3, plan T13–T17.
+//
+// One object per sync runtime. It knows whether the linked project is in
+// `transactions` mode (asked, never assumed: a hub without the route is a
+// legacy hub), and it turns every persistent change the studio makes into a
+// proposal through the durable transaction client:
+//
+//   • lane values   — text/CSS/meta/comments/annotations, via `laneLink(slug)`
+//                     handed to each canvas's projection;
+//   • the manifest  — canvas create/move/delete and folder create/move/delete.
+//
+// Nothing here writes a Y.Doc. The documents change when the hub publishes the
+// accepted revision, through the same providers that deliver a peer's edit.
+
+import { createActionStage, type StageSummary } from './action-stage.ts';
+import type { AcceptedLaneLink, LaneProposal, ProposalOutcome } from './projection.ts';
+import {
+  type Bootstrap,
+  createTransactionClient,
+  type Operation,
+  type ProposalResult,
+  type TransactionClient,
+  TransactionError,
+  type TransactionStats,
+} from './transaction-client.ts';
+
+export type AcceptedMode = 'unknown' | 'legacy' | 'transactions';
+
+export interface AcceptedLinkOptions {
+  hubUrl: string;
+  token: () => string | null;
+  designRoot: string;
+  docNameFor: (slug: string) => string;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn' | 'error'>;
+  onPending?: (count: number) => void;
+  onStats?: (stats: TransactionStats) => void;
+  onResult?: (result: ProposalResult, action: { label: string; operations: Operation[] }) => void;
+  retryMs?: number;
+  /** Injected client (tests). */
+  client?: TransactionClient;
+  /** T16 — an AI action opened, was held, or ended. */
+  onStage?: (summary: StageSummary | null) => void;
+}
+
+export type StructuralOutcome = ProposalOutcome & { queued?: boolean };
+
+const LANE_LABEL: Record<LaneProposal['lane'], string> = {
+  html: 'Edit canvas',
+  css: 'Edit styles',
+  meta: 'Edit layout',
+  annotations: 'Edit annotations',
+  comments: 'Edit comments',
+};
+
+export function createAcceptedLink(opts: AcceptedLinkOptions) {
+  const log = opts.log ?? console;
+  const client =
+    opts.client ??
+    createTransactionClient({
+      hubUrl: opts.hubUrl,
+      token: opts.token,
+      designRoot: opts.designRoot,
+      fetchImpl: opts.fetchImpl,
+      log,
+      onPending: opts.onPending,
+      onStats: opts.onStats,
+      onResult: opts.onResult,
+      retryMs: opts.retryMs,
+    });
+
+  let mode: AcceptedMode = 'unknown';
+  let manifest: Bootstrap | null = null;
+
+  // T16 — AI and multi-file action boundaries (see action-stage.ts).
+  const stage = createActionStage({
+    designRoot: opts.designRoot,
+    propose: (action) => client.propose(action),
+    newTransactionId: client.newTransactionId,
+    onChange: opts.onStage,
+    log,
+  });
+  stage.restore();
+
+  /**
+   * Ask the hub which protocol this project speaks. A network failure keeps
+   * the previous verdict — flapping into legacy while the hub is unreachable
+   * would let a local write bypass the proposal lane.
+   */
+  async function refresh(): Promise<Bootstrap | null> {
+    try {
+      const b = await client.bootstrap();
+      const next: AcceptedMode = b.mode === 'transactions' ? 'transactions' : 'legacy';
+      if (next !== mode && mode !== 'unknown') {
+        log.log(`[sync/tx] project save mode changed: ${mode} → ${next}`);
+      }
+      mode = next;
+      manifest = b;
+      return b;
+    } catch (err) {
+      if (err instanceof TransactionError && err.code === 'absent') mode = 'legacy';
+      return null;
+    }
+  }
+
+  const on = (): boolean => mode === 'transactions';
+
+  /**
+   * The hub announced a mode change on a document socket. Believed at once —
+   * it is the hub's own word, delivered before it closes the socket — and
+   * confirmed by the next `refresh()`.
+   */
+  function noteMode(next: 'transactions' | 'legacy'): void {
+    if (next !== mode) log.log(`[sync/tx] the project switched its save mode: ${mode} → ${next}`);
+    mode = next;
+  }
+
+  const outcome = (r: ProposalResult): ProposalOutcome => ({
+    status: r.status,
+    ...(r.code ? { code: r.code } : {}),
+    ...(typeof r.head === 'string' ? { head: r.head } : {}),
+    ...(typeof r.actionId === 'string' ? { actionId: r.actionId } : {}),
+  });
+
+  function laneLink(slug: string): AcceptedLaneLink {
+    return {
+      on,
+      newTransactionId: client.newTransactionId,
+      propose: (p) => {
+        const doc = opts.docNameFor(slug);
+        if (stage.captures(slug, p.stageable === true)) return stage.capture(slug, doc, p);
+        const send = (dependsOn: string[] | undefined) =>
+          client
+            .propose({
+              kind: 'edit',
+              label: LANE_LABEL[p.lane],
+              transactionId: p.transactionId,
+              dependsOn,
+              operations: [
+                {
+                  op: 'lane.replace',
+                  doc,
+                  lane: p.lane,
+                  content: p.content,
+                  baseContent: p.baseContent,
+                  ...(p.writeId ? { writeId: p.writeId } : {}),
+                },
+              ],
+            })
+            .then(outcome);
+        if (stage.holdsDependency(p.dependsOn)) {
+          // Authored on top of an agent's unpublished bytes: it waits behind
+          // the stage, and goes out right after the group (or is discarded
+          // with it).
+          return new Promise<ProposalOutcome>((resolve, reject) => {
+            stage.wait({
+              dependsOn: p.dependsOn ?? [],
+              send: (d) => void send(d).then(resolve, reject),
+              drop: resolve,
+            });
+          });
+        }
+        return send(stage.mapDeps(p.dependsOn));
+      },
+    };
+  }
+
+  /**
+   * A structural action, answered within `waitMs` or reported as QUEUED: the
+   * proposal stays in the durable outbox and lands when the hub is reachable
+   * (the client delivers in creation order, so a later edit cannot overtake
+   * it). The caller proceeds with its local change either way — the designer
+   * never waits on the network to move a canvas.
+   */
+  function structural(
+    label: string,
+    kind: string,
+    operations: Operation[],
+    waitMs: number
+  ): Promise<StructuralOutcome> {
+    const answer = client.propose({ kind, label, operations }).then(outcome);
+    if (!Number.isFinite(waitMs)) return answer;
+    return Promise.race([
+      answer,
+      new Promise<StructuralOutcome>((resolve) =>
+        setTimeout(() => resolve({ status: 'accepted', queued: true }), waitMs)
+      ),
+    ]);
+  }
+
+  return {
+    client,
+    refresh,
+    on,
+    get mode(): AcceptedMode {
+      return mode;
+    },
+    /** The last bootstrap answer — manifest dirs and docs at that revision. */
+    get manifest(): Bootstrap | null {
+      return manifest;
+    },
+    laneLink,
+    noteMode,
+    /** T16 — AI action boundaries. */
+    stage,
+    createDoc(
+      slug: string,
+      rel: string,
+      lanes: Partial<Record<LaneProposal['lane'], string>>,
+      waitMs = Number.POSITIVE_INFINITY
+    ): Promise<StructuralOutcome> {
+      const clean: Record<string, string> = {};
+      for (const [lane, v] of Object.entries(lanes)) if (v) clean[lane] = v;
+      return structural(
+        'Create canvas',
+        'canvas.create',
+        [{ op: 'doc.create', doc: opts.docNameFor(slug), path: rel, lanes: clean }],
+        waitMs
+      );
+    },
+    deleteDoc(slug: string, waitMs = 8_000): Promise<StructuralOutcome> {
+      return structural(
+        'Delete canvas',
+        'canvas.delete',
+        [{ op: 'doc.delete', doc: opts.docNameFor(slug) }],
+        waitMs
+      );
+    },
+    moveDoc(slug: string, toRel: string, waitMs = 8_000): Promise<StructuralOutcome> {
+      return structural(
+        'Move canvas',
+        'canvas.move',
+        [{ op: 'doc.move', doc: opts.docNameFor(slug), to: { path: toRel } }],
+        waitMs
+      );
+    },
+    dirCreate(rel: string, waitMs = 8_000): Promise<StructuralOutcome> {
+      return structural(
+        'Create folder',
+        'folder.create',
+        [{ op: 'dir.create', path: rel }],
+        waitMs
+      );
+    },
+    /** Several folders in ONE action (a cold start publishing local folders). */
+    dirsCreate(rels: string[], waitMs = Number.POSITIVE_INFINITY): Promise<StructuralOutcome> {
+      return structural(
+        rels.length === 1 ? 'Create folder' : `Add ${rels.length} folders`,
+        'folder.create',
+        rels.map((path) => ({ op: 'dir.create', path })),
+        waitMs
+      );
+    },
+    dirDelete(rel: string, waitMs = 8_000): Promise<StructuralOutcome> {
+      return structural(
+        'Delete folder',
+        'folder.delete',
+        [{ op: 'dir.delete', path: rel }],
+        waitMs
+      );
+    },
+    dirMove(from: string, to: string, waitMs = 8_000): Promise<StructuralOutcome> {
+      return structural('Move folder', 'folder.move', [{ op: 'dir.move', from, to }], waitMs);
+    },
+    /** Logical history, newest first (optionally one entry's). */
+    history(q: { limit?: number; before?: number | null; entry?: string | null }) {
+      const params: Record<string, string | number> = { limit: q.limit ?? 50 };
+      if (q.before) params.before = q.before;
+      if (q.entry) params.entry = q.entry;
+      return client.read('history', params) as Promise<{ history: HistoryAction[] }>;
+    },
+    /** A canvas lane as it stood at `revision`. */
+    laneAt(slug: string, lane: LaneProposal['lane'], revision: number) {
+      return client.read('lane', { doc: opts.docNameFor(slug), lane, rev: revision }) as Promise<{
+        body: string;
+        hash: string | null;
+      }>;
+    },
+    /** Restore canvases to a revision — a NEW action; nothing is rewound. */
+    restore(slugs: string[], revision: number, label: string): Promise<StructuralOutcome> {
+      return structural(
+        label,
+        'history.restore',
+        [{ op: 'history.restore', revision, docs: slugs.map((s) => opts.docNameFor(s)) }],
+        8_000
+      );
+    },
+    /** Personal undo / redo of one of this actor's actions. */
+    undo(actionId: string, redo = false): Promise<StructuralOutcome> {
+      return structural(
+        redo ? 'Redo' : 'Undo',
+        redo ? 'redo' : 'undo',
+        [{ op: redo ? 'history.redo' : 'history.undo', actionId }],
+        8_000
+      );
+    },
+    stop() {
+      client.stop();
+    },
+  };
+}
+
+export interface HistoryAction {
+  revision: number;
+  actor: string;
+  actionId: string;
+  kind: string;
+  label: string | null;
+  committedAt: number;
+  undoes: string | null;
+  effects: {
+    doc: string | null;
+    lane: string;
+    op: string;
+    beforePath: string | null;
+    afterPath: string | null;
+  }[];
+}
+
+export type AcceptedLink = ReturnType<typeof createAcceptedLink>;

package/apps/studio/sync/action-stage.ts

@@ -0,0 +1,343 @@
+// AI and multi-file action boundaries — plan T16 (DDR-241).
+//
+// An agent turn (the in-app chat) or a `/design:edit` run changes several
+// files, one tool call at a time. Proposed as they land, the project would
+// accept a canvas edited against a module the agent has not written yet, and
+// an agent that fails half way would leave that half published. So while an
+// AI action is OPEN, the file changes it makes are STAGED here instead of
+// proposed: kept on disk, remembered with the value each was derived from,
+// and proposed together — one transaction, one history action — when the
+// action ends well.
+//
+// When it does not (the agent errors, is cancelled, stops at its token limit,
+// or its heartbeat goes silent) the stage is HELD: nothing is published and
+// nothing is thrown away. The person decides — publish it as it stands, or
+// discard it (the accepted version returns; the candidate stays in the
+// recovery slots). A held stage survives a restart (`_state/ai-stage.json`),
+// so a crash can never turn into a partial publish by the next cold start.
+//
+// What is staged is only a WATCHER change (a tool writing a file). An edit the
+// person makes in the UI is theirs and is proposed at once — unless it is made
+// on top of a staged file, in which case it carries the agent's unpublished
+// bytes and waits behind the stage (`dependents`), exactly as U2 waits on U1.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type { LaneProposal, ProposalOutcome } from './projection.ts';
+import type { Operation, ProposalResult } from './transaction-client.ts';
+
+export type StageState = 'open' | 'held';
+
+export interface StagedLane {
+  slug: string;
+  doc: string;
+  lane: LaneProposal['lane'];
+  /** The value the FIRST staged change was derived from — the group's base. */
+  baseContent: string;
+  /** The latest staged value. */
+  content: string;
+  writeId?: string;
+  /** Every staged proposal's transaction id — aliased to the group's on commit. */
+  txs: string[];
+  resolvers: Array<(o: ProposalOutcome) => void>;
+}
+
+export interface StageSummary {
+  state: StageState;
+  label: string;
+  canvases: string[];
+  since: number;
+}
+
+interface Dependent {
+  send: (dependsOn: string[] | undefined) => void;
+  drop: (o: ProposalOutcome) => void;
+  dependsOn: string[];
+}
+
+export interface ActionStageOptions {
+  designRoot: string;
+  /** Send one grouped action; resolves with the final result. */
+  propose: (action: {
+    label: string;
+    kind: string;
+    operations: Operation[];
+    transactionId: string;
+  }) => Promise<ProposalResult>;
+  newTransactionId: () => string;
+  onChange?: (summary: StageSummary | null) => void;
+  log?: Pick<Console, 'log' | 'warn'>;
+  now?: () => number;
+}
+
+export function createActionStage(opts: ActionStageOptions) {
+  const log = opts.log ?? console;
+  const now = opts.now ?? Date.now;
+  const file = path.join(opts.designRoot, '_state', 'ai-stage.json');
+
+  let state: StageState | null = null;
+  let label = '';
+  let since = 0;
+  const keys = new Set<string>();
+  let failed = false;
+  const lanes = new Map<string, StagedLane>();
+  const dependents: Dependent[] = [];
+  /** A staged transaction id → the group transaction that carried it. */
+  const alias = new Map<string, string>();
+  /** Slugs a restored (held) stage covers — cold-start changes to them are staged. */
+  const restoredSlugs = new Set<string>();
+  /** Bases restored from disk after a restart: `${slug}|${lane}` → baseContent. */
+  const restoredBases = new Map<string, string>();
+
+  function summary(): StageSummary | null {
+    if (!state) return null;
+    const canvases = new Set<string>([...restoredSlugs]);
+    for (const l of lanes.values()) canvases.add(l.slug);
+    return { state, label, canvases: [...canvases].sort(), since };
+  }
+
+  function persist(): void {
+    try {
+      if (!state || (lanes.size === 0 && restoredSlugs.size === 0)) {
+        rmSync(file, { force: true });
+        return;
+      }
+      mkdirSync(path.dirname(file), { recursive: true });
+      const body = {
+        v: 1,
+        state,
+        label,
+        since,
+        lanes: [...lanes.values()].map((l) => ({
+          slug: l.slug,
+          doc: l.doc,
+          lane: l.lane,
+          baseContent: l.baseContent,
+        })),
+        restored: [...restoredBases.entries()].map(([k, baseContent]) => {
+          const [slug, lane] = k.split('|');
+          return { slug, lane, baseContent };
+        }),
+      };
+      writeFileSync(`${file}.tmp`, JSON.stringify(body));
+      renameSync(`${file}.tmp`, file);
+    } catch (err) {
+      log.warn(`[sync/ai] could not record the unfinished action: ${(err as Error).message}`);
+    }
+  }
+
+  function changed(): void {
+    persist();
+    opts.onChange?.(summary());
+  }
+
+  /** A previous process left a stage: it comes back HELD. */
+  function restore(): void {
+    if (!existsSync(file)) return;
+    try {
+      const body = JSON.parse(readFileSync(file, 'utf8')) as {
+        label?: string;
+        since?: number;
+        lanes?: { slug: string; lane: string; baseContent: string }[];
+        restored?: { slug: string; lane: string; baseContent: string }[];
+      };
+      const all = [...(body.lanes ?? []), ...(body.restored ?? [])];
+      if (all.length === 0) return;
+      state = 'held';
+      label = typeof body.label === 'string' ? body.label : 'AI edit';
+      since = typeof body.since === 'number' ? body.since : now();
+      for (const l of all) {
+        restoredSlugs.add(l.slug);
+        restoredBases.set(`${l.slug}|${l.lane}`, l.baseContent);
+      }
+      log.warn(
+        `[sync/ai] an unfinished AI edit (${label}) to ${restoredSlugs.size} canvas(es) was kept from the last session — it is not published until you choose.`
+      );
+      opts.onChange?.(summary());
+    } catch {
+      /* unreadable → nothing to restore */
+    }
+  }
+
+  function begin(key: string, nextLabel: string): void {
+    keys.add(key);
+    if (state === 'open') return;
+    if (state === 'held') {
+      // A new action on top of an unfinished one continues it: its files may
+      // already carry the held bytes. It stays one decision for the person.
+      state = 'open';
+      failed = false;
+      changed();
+      return;
+    }
+    state = 'open';
+    failed = false;
+    label = nextLabel.slice(0, 120) || 'AI edit';
+    since = now();
+    changed();
+  }
+
+  /** Should this proposal be staged instead of sent? */
+  function captures(slug: string, stageable: boolean): boolean {
+    if (!stageable || !state) return false;
+    return (
+      state === 'open' ||
+      restoredSlugs.has(slug) ||
+      [...lanes.values()].some((l) => l.slug === slug)
+    );
+  }
+
+  function capture(slug: string, doc: string, p: LaneProposal): Promise<ProposalOutcome> {
+    const k = `${slug}|${p.lane}`;
+    return new Promise((resolve) => {
+      const existing = lanes.get(k);
+      if (existing) {
+        existing.content = p.content;
+        existing.txs.push(p.transactionId);
+        existing.resolvers.push(resolve);
+        if (p.writeId) existing.writeId = p.writeId;
+      } else {
+        lanes.set(k, {
+          slug,
+          doc,
+          lane: p.lane,
+          baseContent: restoredBases.get(k) ?? p.baseContent,
+          content: p.content,
+          ...(p.writeId ? { writeId: p.writeId } : {}),
+          txs: [p.transactionId],
+          resolvers: [resolve],
+        });
+        changed();
+      }
+    });
+  }
+
+  function isStagedTx(id: string): boolean {
+    for (const l of lanes.values()) if (l.txs.includes(id)) return true;
+    return false;
+  }
+
+  /** A non-staged proposal authored on top of a staged one waits behind the stage. */
+  function holdsDependency(dependsOn: string[] | undefined): boolean {
+    return !!dependsOn?.some((id) => isStagedTx(id));
+  }
+
+  function wait(dep: Dependent): void {
+    dependents.push(dep);
+  }
+
+  /** Rewrite a dependency on a staged proposal to the group that carried it. */
+  function mapDeps(dependsOn: string[] | undefined): string[] | undefined {
+    if (!dependsOn?.length) return dependsOn;
+    return dependsOn.map((id) => alias.get(id) ?? id);
+  }
+
+  function laneOutcome(r: ProposalResult, l: StagedLane): ProposalOutcome {
+    const mine = r.doc === l.doc && r.lane === l.lane;
+    return {
+      status: r.status,
+      ...(r.code ? { code: r.code } : {}),
+      ...(mine && typeof r.head === 'string' ? { head: r.head } : {}),
+      ...(typeof r.actionId === 'string' ? { actionId: r.actionId } : {}),
+    };
+  }
+
+  function reset(): void {
+    state = null;
+    label = '';
+    since = 0;
+    keys.clear();
+    failed = false;
+    lanes.clear();
+    restoredSlugs.clear();
+    restoredBases.clear();
+    changed();
+  }
+
+  /** Propose everything staged as ONE action. */
+  async function publish(): Promise<ProposalResult | null> {
+    if (!state) return null;
+    const staged = [...lanes.values()];
+    const waiting = dependents.splice(0);
+    const groupLabel = label || 'AI edit';
+    if (staged.length === 0) {
+      reset();
+      for (const d of waiting) d.send(mapDeps(d.dependsOn));
+      return null;
+    }
+    const transactionId = opts.newTransactionId();
+    for (const l of staged) for (const tx of l.txs) alias.set(tx, transactionId);
+    const operations: Operation[] = staged.map((l) => ({
+      op: 'lane.replace',
+      doc: l.doc,
+      lane: l.lane,
+      content: l.content,
+      baseContent: l.baseContent,
+      ...(l.writeId ? { writeId: l.writeId } : {}),
+    }));
+    // The stage is closed before the answer: the next action starts clean,
+    // and the dependents go out right behind the group (same ordered outbox).
+    reset();
+    const sent = opts.propose({ label: groupLabel, kind: 'ai', operations, transactionId });
+    for (const d of waiting) d.send(mapDeps(d.dependsOn));
+    const r = await sent.catch((err: unknown) => {
+      const code = (err as { code?: string })?.code ?? 'retryable';
+      return { protocol: 1, status: 'rejected', code, transactionId } as ProposalResult;
+    });
+    for (const l of staged) for (const fn of l.resolvers) fn(laneOutcome(r, l));
+    log.log(
+      `[sync/ai] ${groupLabel}: ${staged.length} change(s) ${r.status === 'accepted' ? 'published as one action' : `refused (${r.code ?? 'rejected'})`}.`
+    );
+    return r;
+  }
+
+  /** End one participant. The last `done` publishes; any failure holds. */
+  async function end(key: string, outcome: 'done' | 'failed'): Promise<ProposalResult | null> {
+    if (!keys.has(key)) return null;
+    keys.delete(key);
+    if (outcome === 'failed') failed = true;
+    if (keys.size > 0 || state !== 'open') return null;
+    if (failed) {
+      state = 'held';
+      changed();
+      log.warn(
+        `[sync/ai] ${label}: the action did not finish — ${lanes.size} change(s) kept on this device, not published.`
+      );
+      return null;
+    }
+    return publish();
+  }
+
+  /** Throw the held changes away: every lane returns to the accepted version. */
+  function discard(): number {
+    if (state !== 'held') return 0;
+    const staged = [...lanes.values()];
+    const waiting = dependents.splice(0);
+    const slugs = new Set([...restoredSlugs, ...staged.map((l) => l.slug)]);
+    reset();
+    for (const l of staged)
+      for (const fn of l.resolvers) fn({ status: 'rejected', code: 'discarded' });
+    for (const d of waiting) d.drop({ status: 'rejected', code: 'discarded' });
+    return slugs.size;
+  }
+
+  return {
+    restore,
+    begin,
+    end,
+    publish,
+    discard,
+    captures,
+    capture,
+    holdsDependency,
+    wait,
+    mapDeps,
+    summary,
+    get state() {
+      return state;
+    },
+  };
+}
+
+export type ActionStage = ReturnType<typeof createActionStage>;