@1agh/maude 1.2.0 → 1.3.1

package/apps/studio/sync/accepted-cold-start.ts

@@ -0,0 +1,225 @@
+// Cold start under accepted revisions — DDR-241 §3, plan T13/T14.
+//
+// The legacy cold start (`migrate-seed.ts`) had to CHOOSE a source and write it
+// into the shared document, because the document was writable and whatever a
+// peer put there was the project. Here the document is a read-only replica of
+// the accepted state, so cold start only ever DECIDES, per lane:
+//
+//   agreed       — disk already holds the accepted value;
+//   materialize  — disk is older than the project (or absent): the projection
+//                  writes the accepted value, keeping local bytes in recovery;
+//   propose      — disk carries a change made on top of a known base: it is
+//                  proposed, and the hub merges it three-way from that base;
+//   hold         — disk differs and nothing proves what it was derived from:
+//                  both are kept, the lane stays blocked with a visible
+//                  conflict, and the next save resolves it (T2's rule — never a
+//                  silent overwrite of either side).
+//
+// A canvas the project does not know yet is proposed as `doc.create` with all
+// of its lanes, so it arrives on every peer as ONE action.
+//
+// Comments and annotations are never re-proposed from disk here: every change
+// the studio made to them went through the durable outbox (drained before any
+// cold start), so a difference on disk is an older accepted state the room had
+// not re-projected — the accepted value wins, and the local file is kept in a
+// recovery slot in case a raw edit made while the studio was down lived there.
+
+import { existsSync, readFileSync } from 'node:fs';
+import type * as Y from 'yjs';
+
+import { cssFromDoc, htmlFromDoc, laneValueFromFile, readLaneFromDoc } from './codec.ts';
+import { hashBytes } from './echo-guard.ts';
+import type { SyncJournal } from './journal.ts';
+import type { DocProjection, ProjectionPaths, ProposalLane } from './projection.ts';
+import { readRecoveryBody, saveRecoveryBody } from './source-recovery.ts';
+import { sourceError } from './source-validation.ts';
+
+export type LaneDecision = 'agreed' | 'materialize' | 'propose' | 'hold';
+
+export interface LaneVerdict {
+  lane: ProposalLane;
+  decision: LaneDecision;
+  /** For `propose`: the value the local edit was derived from. For `hold`: the accepted value adopted as the base. */
+  base?: string;
+  local?: string;
+}
+
+function readText(p: string | undefined): string | null {
+  if (!p || !existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure decision for the source lanes. `knownBase` is the last value disk and
+ * the accepted replica agreed on (recovery slot), `baseHash` the journal's
+ * hash of it when the bytes are gone.
+ */
+export function decideSourceLane(input: {
+  local: string | null;
+  accepted: string;
+  knownBase: string | null;
+  baseHash?: string | null;
+}): { decision: LaneDecision; base?: string } {
+  const { local, accepted } = input;
+  if (local === null) return { decision: 'materialize' };
+  if (local === accepted) return { decision: 'agreed' };
+  let base = input.knownBase;
+  if (base === null && input.baseHash) {
+    if (hashBytes(accepted) === input.baseHash) base = accepted;
+    else if (hashBytes(local) === input.baseHash) base = local;
+  }
+  if (base === null) {
+    // The project never had this lane: nothing of anybody's can be lost.
+    if (accepted === '') return { decision: 'propose', base: '' };
+    return { decision: 'hold', base: accepted };
+  }
+  if (base === local) return { decision: 'materialize' }; // an older accepted state
+  return { decision: 'propose', base };
+}
+
+export interface AcceptedColdStartInput {
+  slug: string;
+  doc: Y.Doc;
+  paths: ProjectionPaths;
+  /** Design-root-relative body path (`ui/home.tsx`). */
+  rel: string;
+  /** Is this canvas a live document of the project's accepted state? */
+  inProject: boolean;
+  projection: DocProjection;
+  historyDir?: string;
+  journal?: SyncJournal;
+  createDoc: (lanes: Partial<Record<ProposalLane, string>>) => Promise<{
+    status: 'accepted' | 'rejected';
+    code?: string;
+  }>;
+  log?: Pick<Console, 'log' | 'warn'>;
+}
+
+export type AcceptedColdStartResult =
+  | { kind: 'created' }
+  | { kind: 'create-refused'; code?: string }
+  | { kind: 'reconciled'; verdicts: LaneVerdict[] };
+
+export async function acceptedColdStart(
+  i: AcceptedColdStartInput
+): Promise<AcceptedColdStartResult> {
+  const log = i.log ?? console;
+  const localHtml = readText(i.paths.html);
+
+  if (!i.inProject) {
+    if (localHtml === null) return { kind: 'reconciled', verdicts: [] };
+    const lanes: Partial<Record<ProposalLane, string>> = { html: localHtml };
+    const css = readText(i.paths.css);
+    if (css) lanes.css = css;
+    const metaText = readText(i.paths.meta);
+    const meta = metaText === null ? null : laneValueFromFile('meta', metaText);
+    if (meta && meta !== '{}') lanes.meta = meta;
+    const ann = readText(i.paths.annotations);
+    if (ann) lanes.annotations = ann;
+    const commentsText = readText(i.paths.comments);
+    const comments = commentsText === null ? null : laneValueFromFile('comments', commentsText);
+    if (comments) lanes.comments = comments;
+    const r = await i.createDoc(lanes);
+    if (r.status === 'accepted') {
+      // What the project now holds IS the local file: the next save is based
+      // on it, even if it lands before the publication reaches this replica.
+      i.projection.adoptBase(localHtml);
+      log.log(`[sync/${i.slug}] added to the project (accepted).`);
+      return { kind: 'created' };
+    }
+    log.warn(
+      `[sync/${i.slug}] the project did not accept this canvas (${r.code ?? 'rejected'}) — it stays local.`
+    );
+    return { kind: 'create-refused', code: r.code };
+  }
+
+  const verdicts: LaneVerdict[] = [];
+
+  // ---- html — the canvas source
+  const acceptedHtml = htmlFromDoc(i.doc);
+  if (localHtml !== null && localHtml !== acceptedHtml && sourceError(i.paths.html, localHtml)) {
+    // An invalid local body cannot be proposed; the projection keeps its bytes
+    // in recovery and reports it when it materializes the accepted source.
+    verdicts.push({ lane: 'html', decision: 'materialize', local: localHtml });
+  } else {
+    const d = decideSourceLane({
+      local: localHtml,
+      accepted: acceptedHtml,
+      knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.html, 'base') : null,
+      baseHash: i.journal?.get(i.slug)?.bodyHash ?? null,
+    });
+    verdicts.push({ lane: 'html', ...d, ...(localHtml !== null ? { local: localHtml } : {}) });
+  }
+
+  // ---- css — opaque text, journal-checkpointed
+  if (i.paths.css) {
+    const localCss = readText(i.paths.css);
+    const d = decideSourceLane({
+      local: localCss,
+      accepted: cssFromDoc(i.doc) ?? '',
+      knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.css, 'base') : null,
+      baseHash: i.journal?.get(i.slug)?.cssHash ?? null,
+    });
+    verdicts.push({ lane: 'css', ...d, ...(localCss !== null ? { local: localCss } : {}) });
+  }
+
+  // ---- meta — the shared layout keys (viewport never travels)
+  if (i.paths.meta) {
+    const metaText = readText(i.paths.meta);
+    const local = metaText === null ? null : laneValueFromFile('meta', metaText);
+    const accepted = readLaneFromDoc(i.doc, 'meta');
+    if (local === null || local === accepted || (local === '{}' && accepted === '')) {
+      verdicts.push({ lane: 'meta', decision: local === null ? 'materialize' : 'agreed' });
+    } else if (accepted === '') {
+      verdicts.push({ lane: 'meta', decision: 'propose', base: '', local });
+    } else {
+      // No base is recorded for layout: the project's arrangement wins and the
+      // projection merges it into the local file's private keys.
+      verdicts.push({ lane: 'meta', decision: 'materialize', local });
+    }
+  }
+
+  // ---- comments / annotations — the accepted value wins (see header)
+  for (const lane of ['comments', 'annotations'] as const) {
+    const p = lane === 'comments' ? i.paths.comments : i.paths.annotations;
+    const text = readText(p);
+    const local = text === null ? null : laneValueFromFile(lane, text);
+    const accepted = readLaneFromDoc(i.doc, lane);
+    if (local === null || local === accepted) {
+      verdicts.push({ lane, decision: local === null ? 'materialize' : 'agreed' });
+      continue;
+    }
+    if (i.historyDir && text) {
+      try {
+        saveRecoveryBody(i.historyDir, p, 'local', text);
+      } catch {
+        /* recovery is best-effort for these lanes */
+      }
+    }
+    verdicts.push({ lane, decision: 'materialize', local: text ?? undefined });
+  }
+
+  // ---- act
+  for (const v of verdicts) {
+    if (v.decision === 'propose' && v.local !== undefined) {
+      const value = v.lane === 'meta' ? v.local : (laneValueFromFile(v.lane, v.local) ?? v.local);
+      if (v.lane === 'html') i.projection.adoptBase(v.base ?? '');
+      // Stageable: a restored unfinished AI action (T16) keeps its canvases'
+      // differences for the person's decision instead of publishing them.
+      void i.projection.proposeLane(v.lane, value, { baseContent: v.base ?? '', stageable: true });
+    } else if (v.decision === 'hold' && v.local !== undefined) {
+      i.projection.hold(v.lane, v.base ?? '', v.local);
+    }
+  }
+  const moved = verdicts.filter((v) => v.decision === 'propose' || v.decision === 'hold');
+  if (moved.length) {
+    log.log(
+      `[sync/${i.slug}] cold start: ${moved.map((v) => `${v.lane}=${v.decision}`).join(', ')}`
+    );
+  }
+  return { kind: 'reconciled', verdicts };
+}

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>;