@1agh/maude 0.23.0 → 0.25.0

package/plugins/design/dev-server/sync/materialize.ts

@@ -0,0 +1,62 @@
+// Canonical doc materialization — Phase 9.2 (DDR-064 Task 10, shadow-compare).
+//
+// A deterministic, stable string view of a canvas doc's five synced types. Two
+// docs that have CONVERGED (same comments/annotations/body/meta/css content)
+// produce byte-identical output regardless of CRDT internal structure or apply
+// order. This is the comparison primitive the cutover relies on:
+//
+//   - shadow-compare: materialize the shared-doc path's doc and the legacy
+//     two-doc path's doc; equal strings ⇒ zero divergence ⇒ safe to cut over a
+//     canvas's reads to the shared doc. (The convergence test suite asserts this
+//     law deterministically; the live runtime "shadow mode" — running both paths
+//     simultaneously and logging divergences — is a cutover-time activity layered
+//     on this same primitive.)
+//   - round-trip laws: materialize∘import and import∘materialize for the
+//     projection (test/shared-doc-* suites).
+//
+// Comments are canonicalized via JSON.stringify of the array (the snapshot IS
+// the source of truth — LWW per the codec); the SVG / body / css / meta are
+// taken as their string values. The object is key-ordered so the output is
+// stable.
+
+import type * as Y from 'yjs';
+import { Y_TYPES } from '../collab/persistence.ts';
+import { Y_SYNC_TYPES, annotationsFromDoc, commentsFromDoc } from './codec.ts';
+
+export interface CanonicalMaterialization {
+  html: string;
+  css: string;
+  meta: string;
+  comments: unknown[];
+  annotations: string;
+}
+
+/** Structured canonical view (for assertions that want to compare per-type). */
+export function materialize(doc: Y.Doc): CanonicalMaterialization {
+  return {
+    html: doc.getText(Y_SYNC_TYPES.html).toString(),
+    css: doc.getText(Y_SYNC_TYPES.css).toString(),
+    meta: doc.getText(Y_SYNC_TYPES.meta).toString(),
+    comments: commentsFromDoc(doc),
+    annotations: annotationsFromDoc(doc) ?? '',
+  };
+}
+
+/**
+ * Stable canonical STRING of a doc's synced content. Byte-equal ⟺ converged.
+ * Use for shadow-compare diffing + the round-trip convergence laws.
+ */
+export function materializeCanonical(doc: Y.Doc): string {
+  const m = materialize(doc);
+  // Fixed key order; comments serialized as-is (the JSON snapshot is canonical).
+  return JSON.stringify({
+    html: m.html,
+    css: m.css,
+    meta: m.meta,
+    comments: m.comments,
+    annotations: m.annotations,
+  });
+}
+
+// Re-export so a shadow-compare caller has the type names in one import.
+export { Y_TYPES, Y_SYNC_TYPES };

package/plugins/design/dev-server/sync/migrate-seed.ts

@@ -0,0 +1,163 @@
+// One-time authoritative seed for the shared-doc cutover — Phase 9.2 (DDR-064
+// Task 9). The fix for Risk 1 (the duplication-on-merge trap).
+//
+// The trap (dmonad-confirmed, discuss.yjs.dev/t/.../2538): if a shared doc is
+// populated from TWO independent sources — the local file-seed (room.seed
+// pushing `_comments/<slug>.json` as fresh Y.Array items) AND the hub provider
+// (syncing the hub's canonical items) — the two item-sets have different client
+// IDs, so the CRDT merge CONCATENATES them: comment "c1" appears twice. You
+// cannot fix this with `applyUpdate` of two docs; you must pick ONE authoritative
+// source and build the doc from it.
+//
+// This module is that decision, run ONCE per canvas at cutover, AFTER the
+// provider's first sync (so the doc already holds hub state if the hub had any):
+//
+//   - hub HAD state (doc non-empty)  → HUB WINS. Leave the doc; the projection
+//     materializes hub state to disk. Local divergent files are snapshotted to
+//     `_history/` first (rollback) then overwritten by the room persist.
+//   - hub was EMPTY (doc empty)      → ADOPT. Clear+rebuild the doc from the
+//     local files inside `transact(fn, MIGRATION)` (the apply* codecs already
+//     delete-then-insert, so this is a true rebuild, not an append). The
+//     provider then pushes it up as the canonical first version.
+//
+// Idempotent: re-running with hub state present is a no-op (doc already holds
+// it); re-running an adopt rebuilds from the same files → byte-identical, no
+// duplicate items. The companion guard is the room's seed being disabled for
+// pinned (provider-attached) slugs under sharedDoc (see collab/index.ts
+// `shouldSeed`), so the file-seed can never re-introduce duplicate items after
+// this runs.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import {
+  Y_SYNC_TYPES,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyCssToDoc,
+  applyHtmlToDoc,
+  applyMetaToDoc,
+} from './codec.ts';
+import { ORIGINS } from './origins.ts';
+
+export interface MigrateSeedPaths {
+  html: string;
+  comments: string;
+  annotations: string;
+  meta?: string;
+  css?: string;
+}
+
+export interface MigrateSeedOptions {
+  slug: string;
+  doc: Y.Doc;
+  paths: MigrateSeedPaths;
+  /** `_history/<slug>/` (or any dir) — when set, local files are snapshotted
+   *  here before a hub-wins overwrite, for rollback. Best-effort. */
+  historyDir?: string;
+}
+
+export type MigrateSeedResult = 'hub-wins' | 'local-adopt' | 'empty';
+
+/** True when the shared doc holds no synced content for any of the five types. */
+export function docIsEmpty(doc: Y.Doc): boolean {
+  if (doc.getText(Y_SYNC_TYPES.html).length > 0) return false;
+  if (doc.getText(Y_SYNC_TYPES.css).length > 0) return false;
+  if (doc.getText(Y_SYNC_TYPES.meta).length > 0) return false;
+  if (doc.getArray(Y_TYPES.comments).length > 0) return false;
+  const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
+  if (typeof svg === 'string' && svg.length > 0) return false;
+  return true;
+}
+
+/**
+ * Run the one-time authoritative seed. Returns which source won so the caller
+ * can log / surface a conflict. Safe to call on every boot (idempotent).
+ */
+export function migrateSeed(opts: MigrateSeedOptions): MigrateSeedResult {
+  const { doc, paths } = opts;
+
+  // Hub had canonical state → it wins. The doc already holds it; the projection
+  // will materialize it to disk. Snapshot any divergent local files first so the
+  // overwrite is recoverable.
+  if (!docIsEmpty(doc)) {
+    snapshotLocal(opts);
+    return 'hub-wins';
+  }
+
+  // Hub was empty → adopt local. Build the doc from the local files ONCE, inside
+  // a single MIGRATION transaction. The apply* codecs delete-then-insert, so
+  // this is a clear+rebuild (re-running is a no-op once content matches).
+  const localHtml = readLocal(paths.html);
+  const localComments = readLocal(paths.comments);
+  const localAnnotations = readLocal(paths.annotations);
+  const localMeta = paths.meta ? readLocal(paths.meta) : null;
+  const localCss = paths.css ? readLocal(paths.css) : null;
+
+  const hasLocal =
+    !!localHtml || !!localComments || !!localAnnotations || !!localMeta || !!localCss;
+  if (!hasLocal) return 'empty';
+
+  doc.transact(() => {
+    if (localHtml) applyHtmlToDoc(doc, localHtml, ORIGINS.MIGRATION);
+    if (localComments) {
+      const parsed = tryParseJsonArray(localComments);
+      if (parsed) applyCommentsToDoc(doc, parsed, ORIGINS.MIGRATION);
+    }
+    if (localAnnotations) applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
+    if (paths.meta && localMeta) applyMetaToDoc(doc, localMeta, ORIGINS.MIGRATION);
+    if (paths.css && localCss) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
+  }, ORIGINS.MIGRATION);
+
+  return 'local-adopt';
+}
+
+/* ---------------------------------------------------------------- helpers */
+
+function snapshotLocal(opts: MigrateSeedOptions): void {
+  if (!opts.historyDir) return;
+  try {
+    const dir = path.join(opts.historyDir, 'pre-shared-doc-migration');
+    mkdirSync(dir, { recursive: true });
+    for (const p of [
+      opts.paths.html,
+      opts.paths.comments,
+      opts.paths.annotations,
+      opts.paths.meta,
+      opts.paths.css,
+    ]) {
+      if (p && existsSync(p)) {
+        copyFileSync(p, path.join(dir, path.basename(p)));
+      }
+    }
+  } catch {
+    /* best-effort — a snapshot failure must not block the cutover */
+  }
+}
+
+function readLocal(p: string): string | null {
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Proto-pollution-safe (DDR-054 §2g), mirroring the agent + projection comments
+// parse — a planted local `_comments/<slug>.json` must not seed dangerous keys
+// during adopt.
+function tryParseJsonArray(s: string): unknown[] | null {
+  try {
+    const parsed = JSON.parse(s, (key, value) => {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
+      return value;
+    });
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/plugins/design/dev-server/sync/origins.ts

@@ -0,0 +1,57 @@
+// Central transaction-origin sentinels for the shared-doc path — Phase 9.2
+// (DDR-064 Task 5).
+//
+// Once a SINGLE Y.Doc per canvas has multiple writers attached (the browser
+// collab WS, the hub HocuspocusProvider, the disk projector, and — at cutover —
+// the one-time migration seed), every writer MUST tag its transactions with a
+// distinct origin and every consumer MUST filter its own, or a write echoes
+// back into the system and loops. This module is the one place those origins
+// are defined so the discipline is auditable in one read.
+//
+// Two of the origins are inherently PER-INSTANCE and are NOT exported here:
+//
+//   HUB       — the HocuspocusProvider applies hub updates tagged with its own
+//               internal origin (the provider instance). Consumers detect "this
+//               came from the hub" as "origin is neither a RoomConn nor one of
+//               the sentinels below".
+//   LOCAL_WS  — a browser edit arrives through the collab Room as a RoomConn
+//               object (it has an `id` field — see room.ts). That object IS the
+//               origin; the Room's own broadcaster already keys off it.
+//
+// The remaining origins are process-wide singletons (frozen so identity
+// comparison `===` is stable and a consumer can't accidentally reconstruct an
+// equal-but-different object):
+
+export const ORIGINS = {
+  /**
+   * The disk projector materializing the doc to files (doc→file). The projector
+   * writes FILES, not the doc, so this is not normally applied as a Y
+   * transaction origin — it exists for symmetry + so any future doc-touching
+   * projection step (e.g. a normalization write-back) is filterable.
+   */
+  DISK_PROJECTION: Object.freeze({ origin: 'disk-projection' as const }),
+  /**
+   * An external file edit (`/design:edit`, a human, a git pull) imported INTO
+   * the doc as a minimal diff (file→doc). The projector tags its import with
+   * this so its OWN doc.on('update') handler skips it — the file is already
+   * current, re-projecting it back would be a redundant write.
+   */
+  FILE_IMPORT: Object.freeze({ origin: 'file-import' as const }),
+  /**
+   * The one-time authoritative clear-and-rebuild seed at per-canvas cutover
+   * (Phase E migrate-seed). Distinct so the projector can choose to debounce or
+   * suppress disk writes during the seed transaction (it's already on disk).
+   */
+  MIGRATION: Object.freeze({ origin: 'migration' as const }),
+} as const;
+
+export type OriginSentinel = (typeof ORIGINS)[keyof typeof ORIGINS];
+
+/** True when `origin` is one of this module's projector/seed sentinels. */
+export function isProjectorOrigin(origin: unknown): boolean {
+  return (
+    origin === ORIGINS.DISK_PROJECTION ||
+    origin === ORIGINS.FILE_IMPORT ||
+    origin === ORIGINS.MIGRATION
+  );
+}

package/plugins/design/dev-server/sync/projection.ts

@@ -0,0 +1,368 @@
+// Loop-free bidirectional disk projection for the shared-doc path — Phase 9.2
+// (DDR-064 Tasks 6 + 7).
+//
+// In the two-doc world (flag OFF) the sync AGENT mirrored a SECOND doc to disk.
+// Under MAUDE_SHARED_DOC there is ONE doc per canvas (the collab room's), so the
+// file stops being a reconciliation medium and becomes a materialized
+// PROJECTION of the doc (Zed's principle). This module owns that projection:
+//
+//   doc → file  (browser/hub edits converged): debounced, hash-gated, writes the
+//                human-readable files. The projector writes html/css/meta ONLY —
+//                the collab room already persists comments + annotations doc→file
+//                (persistence.ts), so projecting them here too would double-write.
+//   file → doc  (external edit by /design:edit, a human, git): diff the file
+//                against the doc's current materialization and apply ONLY the
+//                delta as Yjs ops tagged ORIGINS.FILE_IMPORT — never a wholesale
+//                replace (that was the Phase 9.1 clobber). All 5 types import.
+//
+// Loop freedom rests on two guards, exactly as the agent's:
+//   1. echo hash — every doc→file write records sha256(bytes); the fs event it
+//      triggers carries the same hash → consume() drops it.
+//   2. origin    — a file→doc import is tagged FILE_IMPORT; the projector's own
+//      doc.on('update') skips that origin so it doesn't re-project what it just
+//      imported.
+// Plus a per-path circuit breaker: a file that fails to PARSE 3× in a row is
+// quarantined until its checksum changes, so an unparseable file can't spin.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import type * as Y from 'yjs';
+
+import { atomicWrite } from './atomic-write.ts';
+import {
+  MAX_CSS_BYTES,
+  MAX_HTML_BYTES,
+  MAX_META_BYTES,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyCssToDoc,
+  applyHtmlToDoc,
+  applyMetaToDoc,
+  cssFromDoc,
+  htmlFromDoc,
+  mergeSharedMetaIntoLocal,
+  metaFromDoc,
+} from './codec.ts';
+import { type EchoGuard, hashBytes } from './echo-guard.ts';
+import { ORIGINS } from './origins.ts';
+
+export const PROJECT_FLUSH_MS = 800;
+export const CIRCUIT_MAX_STRIKES = 3;
+
+export interface ProjectionPaths {
+  /** Absolute path to the canvas body (`.html` or opted-in `.tsx`). */
+  html: string;
+  /** Absolute path to `_comments/<slug>.json`. */
+  comments: string;
+  /** Absolute path to `<slug>.annotations.svg`. */
+  annotations: string;
+  /** Absolute path to the canvas `.meta.json` sibling (optional). */
+  meta?: string;
+  /** Absolute path to the canvas `.css` sibling (optional). */
+  css?: string;
+}
+
+export interface DocProjectionOptions {
+  slug: string;
+  doc: Y.Doc;
+  paths: ProjectionPaths;
+  /**
+   * Echo guard shared with the rest of the sync runtime so a doc→file write here
+   * is recognized as an echo when its fs event arrives. Optional — a standalone
+   * test can omit it (echo handling then relies on the hash-equality drop only).
+   */
+  echoGuard?: EchoGuard;
+  /** Injected for tests — defaults to atomicWrite. */
+  writer?: (path: string, bytes: string | Uint8Array) => void;
+  /** Override the 800 ms debounce. Tests use 0 to flush on the next microtask. */
+  flushMs?: number;
+  /** Circuit-breaker threshold (consecutive parse failures per path). */
+  maxStrikes?: number;
+}
+
+export interface DocProjection {
+  readonly slug: string;
+  /** Subscribe to doc updates (doc→file). Idempotent. */
+  start(): void;
+  /**
+   * Apply an external file edit to the doc (file→doc). Returns true when the doc
+   * changed. Mirrors the agent's `applyFromFs` signature so the runtime's
+   * fs-reader can dispatch to either uniformly.
+   */
+  applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean;
+  /** Project the doc's current html/css/meta to disk now (initial materialize).
+   *  SAFE: never writes an empty doc value over non-empty local content — the
+   *  authoritative push-local-up seed is Phase E (migrate-seed). */
+  reconcile(): void;
+  /** Force the pending doc→file flush immediately. */
+  flush(): Promise<void>;
+  /** Stop the doc listener + timers. */
+  stop(): void;
+  /** Test/inspection — the origin used on file→doc imports. */
+  readonly importOrigin: object;
+}
+
+export function createDocProjection(opts: DocProjectionOptions): DocProjection {
+  const { slug, doc, paths } = opts;
+  const flushMs = opts.flushMs ?? PROJECT_FLUSH_MS;
+  const writer = opts.writer ?? atomicWrite;
+  const maxStrikes = opts.maxStrikes ?? CIRCUIT_MAX_STRIKES;
+  const importOrigin = ORIGINS.FILE_IMPORT;
+
+  let started = false;
+  let stopped = false;
+  let dirty = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // doc→file last-written hashes (skip redundant writes).
+  let lastHtml: string | null = null;
+  let lastMeta: string | null = null;
+  let lastCss: string | null = null;
+
+  // Circuit breaker: per-path { hash, strikes }. A file that fails to PARSE
+  // maxStrikes times in a row is quarantined until its checksum changes.
+  const quarantine = new Map<string, { hash: string; strikes: number }>();
+
+  function onDocUpdate(_u: Uint8Array, origin: unknown): void {
+    if (stopped) return;
+    // Skip our own file→doc import — the file is already current, re-projecting
+    // would be a redundant write. (Migration seed is on disk already too.)
+    if (origin === ORIGINS.FILE_IMPORT || origin === ORIGINS.MIGRATION) return;
+    scheduleFlush();
+  }
+
+  function scheduleFlush(): void {
+    dirty = true;
+    if (flushMs === 0) {
+      queueMicrotask(() => void flush());
+      return;
+    }
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, flushMs);
+  }
+
+  function recordEcho(path: string, value: string): void {
+    opts.echoGuard?.record(path, hashBytes(value));
+  }
+
+  // Security re-audit (Phase D, finding A2 / DDR-054 §2d): the codec's
+  // MAX_*_BYTES caps guard the file→doc *import* lane, but hub-pushed content
+  // arrives as raw Yjs updates through the provider (NOT via applyXToDoc), so it
+  // bypasses those caps. This doc→file lane is the consumer's guard on that
+  // direction — refuse to materialize an oversized hub-pushed body to disk
+  // (disk-fill DoS). Returns true when the write is allowed.
+  function withinCap(path: string, value: string, max: number): boolean {
+    if (Buffer.byteLength(value, 'utf8') <= max) return true;
+    console.warn(
+      `[projection/${slug}] refusing doc→file write of ${path} > ${max} bytes (hub-pushed oversize). DDR-054 §2d.`
+    );
+    return false;
+  }
+
+  // ----- doc → file (html / css / meta only; room owns comments/annotations)
+
+  function writeHtmlIfChanged(): void {
+    const next = htmlFromDoc(doc);
+    if (next === lastHtml) return;
+    // Don't clobber a non-empty local body with an empty doc (cold-start before
+    // the doc is seeded — the safe-reconcile invariant; full adopt is Phase E).
+    if (next === '') {
+      lastHtml = next;
+      return;
+    }
+    if (!withinCap(paths.html, next, MAX_HTML_BYTES)) return;
+    recordEcho(paths.html, next);
+    writer(paths.html, next);
+    lastHtml = next;
+  }
+
+  function writeCssIfChanged(): void {
+    if (!paths.css) return;
+    const next = cssFromDoc(doc);
+    if (next === lastCss) return;
+    lastCss = next;
+    if (next === null) return; // doc carries no css yet — nothing to write
+    if (!withinCap(paths.css, next, MAX_CSS_BYTES)) return;
+    recordEcho(paths.css, next);
+    writer(paths.css, next);
+  }
+
+  function writeMetaIfChanged(): void {
+    if (!paths.meta) return;
+    const shared = metaFromDoc(doc);
+    if (shared === lastMeta) return;
+    lastMeta = shared;
+    if (shared === null) return; // doc carries no shared meta yet
+    const local = readLocal(paths.meta);
+    const merged = mergeSharedMetaIntoLocal(local, shared);
+    if (merged === null || merged === local) return; // unparseable / disk matches
+    if (!withinCap(paths.meta, merged, MAX_META_BYTES)) return;
+    recordEcho(paths.meta, merged);
+    writer(paths.meta, merged);
+  }
+
+  async function flush(): Promise<void> {
+    if (!dirty || stopped) return;
+    dirty = false;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    try {
+      writeHtmlIfChanged();
+      writeCssIfChanged();
+      writeMetaIfChanged();
+    } catch (err) {
+      dirty = true;
+      console.error(`[projection/${slug}] flush failed:`, err);
+    }
+  }
+
+  // ----- file → doc (all five types; diff-import, FILE_IMPORT origin)
+
+  /** Returns true if the path is currently quarantined for `hash`. */
+  function isQuarantined(path: string, hash: string): boolean {
+    const q = quarantine.get(path);
+    return !!q && q.hash === hash && q.strikes >= maxStrikes;
+  }
+
+  /** Record a parse failure; quarantine after maxStrikes for this exact hash. */
+  function strike(path: string, hash: string): void {
+    const q = quarantine.get(path);
+    if (q && q.hash === hash) q.strikes += 1;
+    else quarantine.set(path, { hash, strikes: 1 });
+    if ((quarantine.get(path)?.strikes ?? 0) >= maxStrikes) {
+      console.warn(
+        `[projection/${slug}] quarantined ${path} after ${maxStrikes} parse failures; ignoring until its checksum changes.`
+      );
+    }
+  }
+
+  /** Clear any circuit-breaker state for a path (it parsed / changed). */
+  function clearStrike(path: string): void {
+    quarantine.delete(path);
+  }
+
+  function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
+    if (stopped) return false;
+    // Echo of our own doc→file write — drop.
+    if (opts.echoGuard?.consume(evt.path, evt.hash)) return false;
+    // Circuit breaker — a file that won't parse can't spin the loop.
+    if (isQuarantined(evt.path, evt.hash)) return false;
+
+    const str = bytesToString(evt.bytes);
+
+    if (evt.path === paths.html) {
+      clearStrike(evt.path);
+      const changed = applyHtmlToDoc(doc, str, importOrigin);
+      if (changed) lastHtml = htmlFromDoc(doc);
+      return changed;
+    }
+    if (paths.css && evt.path === paths.css) {
+      clearStrike(evt.path);
+      const changed = applyCssToDoc(doc, str, importOrigin);
+      if (changed) lastCss = str;
+      return changed;
+    }
+    if (paths.meta && evt.path === paths.meta) {
+      // applyMetaToDoc parses internally; a parse failure returns false. Detect
+      // it explicitly so the circuit breaker can quarantine a broken sidecar.
+      if (!isParseableJsonObject(str)) {
+        strike(evt.path, evt.hash);
+        return false;
+      }
+      clearStrike(evt.path);
+      const changed = applyMetaToDoc(doc, str, importOrigin);
+      if (changed) lastMeta = metaFromDoc(doc);
+      return changed;
+    }
+    if (evt.path === paths.comments) {
+      const parsed = tryParseJsonArray(str);
+      if (parsed === null) {
+        strike(evt.path, evt.hash);
+        return false;
+      }
+      clearStrike(evt.path);
+      return applyCommentsToDoc(doc, parsed, importOrigin);
+    }
+    if (evt.path === paths.annotations) {
+      clearStrike(evt.path);
+      return applyAnnotationsToDoc(doc, str, importOrigin);
+    }
+    return false;
+  }
+
+  function reconcile(): void {
+    if (stopped) return;
+    // Materialize the converged doc to disk (html/css/meta). The *IfChanged
+    // writers already guard against clobbering non-empty local with empty doc
+    // values, so this is safe to run at cold start before the authoritative
+    // seed (Phase E) — it only writes what the doc actually holds.
+    writeHtmlIfChanged();
+    writeCssIfChanged();
+    writeMetaIfChanged();
+  }
+
+  return {
+    slug,
+    importOrigin,
+    start() {
+      if (started) return;
+      doc.on('update', onDocUpdate);
+      started = true;
+    },
+    applyFromFs,
+    reconcile,
+    flush,
+    stop() {
+      stopped = true;
+      doc.off('update', onDocUpdate);
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+    },
+  };
+}
+
+/* ---------------------------------------------------------------- helpers */
+
+function readLocal(p: string): string | null {
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function bytesToString(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function isParseableJsonObject(s: string): boolean {
+  try {
+    const v = JSON.parse(s);
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+  } catch {
+    return false;
+  }
+}
+
+// Same proto-pollution-safe reviver the agent uses (DDR-054 §2g): strip
+// dangerous keys at parse time so a hostile file can't seed __proto__ into the
+// comment objects yjs serializes to peers.
+function tryParseJsonArray(s: string): unknown[] | null {
+  try {
+    const parsed = JSON.parse(s, (key, value) => {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
+      return value;
+    });
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}