@tuongaz/seeflow 0.1.31 → 0.1.40

package/src/operations.ts

@@ -18,7 +18,7 @@ import {
 } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
-import { mergeArchitectureAndStyle, splitFlow } from './merge.ts';
+import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import { seeflowHome } from './paths.ts';
 import { type Registry, slugify } from './registry.ts';
 import {
@@ -26,19 +26,21 @@ import {
   EdgePinSchema,
   type Flow,
   FlowSchema,
+  type ResolvedFlow,
+  ResolvedFlowSchema,
   SourceHandleIdSchema,
+  StyleSchema,
   TargetHandleIdSchema,
 } from './schema.ts';
-import { ArchitectureSchema, StyleSchema } from './schema.ts';
 import { writeSdkEmitIfNeeded } from './sdk-writer.ts';
 import { type FlowSnapshot, type FlowWatcher, readMergedFlow } from './watcher.ts';
 
-const DEFAULT_ARCHITECTURE_RELATIVE_PATH = '.seeflow/architecture.json';
+const DEFAULT_FLOW_RELATIVE_PATH = '.seeflow/flow.json';
 
 export const RegisterBodySchema = z.object({
   name: z.string().min(1).optional(),
   repoPath: z.string().min(1),
-  architecturePath: z.string().min(1),
+  flowPath: z.string().min(1),
 });
 export type RegisterBody = z.infer<typeof RegisterBodySchema>;
 
@@ -68,7 +70,7 @@ export type ReorderBody = z.infer<typeof ReorderBodySchema>;
 
 // Partial node update body. Top-level `position` lands on node.position; every
 // other key lands inside node.data. Final validity is enforced by re-parsing
-// the whole demo through FlowSchema after the merge — this body schema just
+// the whole demo through ResolvedFlowSchema after the merge — this body schema just
 // rejects unknown top-level keys to catch typos.
 export const NodePatchBodySchema = z
   .object({
@@ -89,7 +91,7 @@ export const NodePatchBodySchema = z
     // that autoSize:true never coexists with persisted width/height.
     autoSize: z.boolean().optional(),
     shape: z.enum(['rectangle', 'ellipse', 'sticky', 'text']).optional(),
-    // iconNode-only: stroke color token. Lands at data.color; FlowSchema's
+    // iconNode-only: stroke color token. Lands at data.color; ResolvedFlowSchema's
     // post-merge reparse gates that this is only valid on an iconNode.
     color: ColorTokenSchema.optional(),
     // iconNode-only: glyph stroke width. Lands at data.strokeWidth; the
@@ -103,9 +105,6 @@ export const NodePatchBodySchema = z
     // clears the field (mergeNodeUpdates strips the key from disk) — mirrors
     // the empty-string clear convention used for description / detail.
     icon: z.string().min(1).nullable().optional(),
-    // US-019: lock state. Lands at data.locked; persists across save/reload.
-    // Absent → unlocked default (no badge, all gestures work).
-    locked: z.boolean().optional(),
     // Three-field consolidation: free-text metadata on every node variant.
     // Empty string on `description` or `detail` is the documented clear-on-
     // serialize signal — `mergeNodeUpdates` strips the key from disk.
@@ -137,7 +136,6 @@ const NODE_DATA_PATCH_KEYS = [
   'strokeWidth',
   'alt',
   'icon',
-  'locked',
   'description',
   'detail',
 ] as const satisfies ReadonlyArray<keyof NodePatchBody>;
@@ -156,7 +154,7 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
     if (updates[key] === undefined) continue;
     // Empty string on the two free-text metadata fields is the documented
     // clear-on-serialize signal — strip the key instead of writing "" to disk
-    // so seeflow.json stays compact and round-tripping a cleared node doesn't
+    // so flow.json stays compact and round-tripping a cleared node doesn't
     // reintroduce the field.
     if ((key === 'description' || key === 'detail') && updates[key] === '') {
       if (key in data) {
@@ -237,7 +235,7 @@ export interface FlowGetResponse {
   slug: string;
   name: string;
   filePath: string;
-  flow: Flow | null;
+  flow: ResolvedFlow | null;
   valid: boolean;
   error: string | null;
 }
@@ -326,7 +324,7 @@ export type PatchNodeOutcome =
 
 // Partial connector update body. Strict at the top level so client typos
 // surface as 400. Per-kind invariants (e.g. kind='event' requires eventName)
-// are enforced post-merge by re-parsing the whole demo through FlowSchema.
+// are enforced post-merge by re-parsing the whole demo through ResolvedFlowSchema.
 const ConnectorKindSchema = z.enum(['http', 'event', 'queue', 'default']);
 export const ConnectorPatchBodySchema = z
   .object({
@@ -344,7 +342,7 @@ export const ConnectorPatchBodySchema = z
     method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
     url: z.string().optional(),
     // Reconnect: drag an edge endpoint onto another node's handle. The
-    // post-merge FlowSchema parse rejects dangling references, so we don't
+    // post-merge ResolvedFlowSchema parse rejects dangling references, so we don't
     // need a referential check here.
     source: z.string().min(1).optional(),
     target: z.string().min(1).optional(),
@@ -378,7 +376,7 @@ export type ConnectorPatchBody = z.infer<typeof ConnectorPatchBodySchema>;
 // Kind-specific connector fields. When `kind` changes via PATCH, these are
 // dropped first so the resulting connector doesn't carry phantom payloads
 // from the previous kind (e.g. an event→default change leaving eventName
-// behind, which FlowSchema would silently strip on parse but leave on disk).
+// behind, which ResolvedFlowSchema would silently strip on parse but leave on disk).
 const CONNECTOR_KIND_FIELDS = ['method', 'url', 'eventName', 'queueName'] as const;
 
 export const mergeConnectorUpdates = (
@@ -429,8 +427,8 @@ export type DeleteConnectorOutcome =
   | { kind: 'unknownConnector' }
   | { kind: 'writeFailed'; message: string };
 
-export const resolveFilePath = (repoPath: string, architecturePath: string): string =>
-  isAbsolute(architecturePath) ? architecturePath : join(repoPath, architecturePath);
+export const resolveFilePath = (repoPath: string, flowPath: string): string =>
+  isAbsolute(flowPath) ? flowPath : join(repoPath, flowPath);
 
 // Per-demo serialization: read-modify-write of the demo file isn't atomic
 // across multiple PATCHes, so two concurrent drags would race (later writer's
@@ -472,25 +470,25 @@ export const writeFileAtomic = (filePath: string, content: string): void => {
 };
 
 /**
- * Read architecture.json + optional style.json, return the raw parsed JSON
- * so operations can mutate the merged-flow shape without losing forward-compat
- * fields. Returns null if the architecture file is missing or invalid JSON.
+ * Read flow.json + optional style.json, return the raw parsed JSON so
+ * operations can mutate the merged-flow shape without losing forward-compat
+ * fields. Returns null if the flow file is missing or invalid JSON.
  */
 type ReadRawResult =
-  | { kind: 'ok'; rawArch: Record<string, unknown>; rawStyle: Record<string, unknown> }
+  | { kind: 'ok'; rawFlow: Record<string, unknown>; rawStyle: Record<string, unknown> }
   | { kind: 'badJson'; message: string };
 
-function readRawArchAndStyle(archPath: string): ReadRawResult {
-  let rawArch: unknown;
+function readRawFlowAndStyle(flowPath: string): ReadRawResult {
+  let rawFlow: unknown;
   try {
-    rawArch = JSON.parse(readFileSync(archPath, 'utf8'));
+    rawFlow = JSON.parse(readFileSync(flowPath, 'utf8'));
   } catch (err) {
     return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
   }
-  if (!rawArch || typeof rawArch !== 'object' || Array.isArray(rawArch)) {
-    return { kind: 'badJson', message: 'architecture.json is not an object' };
+  if (!rawFlow || typeof rawFlow !== 'object' || Array.isArray(rawFlow)) {
+    return { kind: 'badJson', message: 'flow.json is not an object' };
   }
-  const stylePath = join(dirname(archPath), 'style.json');
+  const stylePath = join(dirname(flowPath), 'style.json');
   let rawStyle: Record<string, unknown> = {};
   if (existsSync(stylePath)) {
     try {
@@ -506,12 +504,12 @@ function readRawArchAndStyle(archPath: string): ReadRawResult {
       };
     }
   }
-  return { kind: 'ok', rawArch: rawArch as Record<string, unknown>, rawStyle };
+  return { kind: 'ok', rawFlow: rawFlow as Record<string, unknown>, rawStyle };
 }
 
 /**
  * Mutate-in-place helper: read both files into a merged Flow shape, hand it
- * to the mutator, then split back into architecture + style and atomically
+ * to the mutator, then split back into flow + style and atomically
  * write both. The mutator returns either { kind: 'ok' } or a discriminated
  * outcome for early-exits (e.g. unknownNode). On schema-validation failure,
  * neither file is written.
@@ -524,26 +522,36 @@ type MutateMergedFlowMutator<E> = (flow: {
   connectors: Array<Record<string, unknown>>;
 }) => { kind: 'ok' } | E;
 
+type MutateMergedFlowOk = {
+  kind: 'ok';
+  /** Validated post-write merged flow — hand straight to watcher.notifyWritten. */
+  snap: FlowSnapshot;
+  /** Exact bytes written to flow.json — used for own-write hash dedupe. */
+  flowContent: string;
+  /** Exact bytes written to style.json, or '' when style.json was deleted / never existed. */
+  styleContent: string;
+};
+
 type MutateMergedFlowResult<E> =
-  | { kind: 'ok' }
+  | MutateMergedFlowOk
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'writeFailed'; message: string }
   | E;
 
 export async function mutateMergedFlow<E extends { kind: string }>(
-  archPath: string,
+  flowPath: string,
   mutator: MutateMergedFlowMutator<E>,
 ): Promise<MutateMergedFlowResult<E>> {
-  const read = readRawArchAndStyle(archPath);
+  const read = readRawFlowAndStyle(flowPath);
   if (read.kind === 'badJson') return { kind: 'badJson', message: read.message };
 
-  const archParse = ArchitectureSchema.safeParse(read.rawArch);
-  if (!archParse.success) return { kind: 'badSchema', issues: archParse.error.issues };
+  const flowParse = FlowSchema.safeParse(read.rawFlow);
+  if (!flowParse.success) return { kind: 'badSchema', issues: flowParse.error.issues };
   const styleParse = StyleSchema.safeParse(read.rawStyle);
   if (!styleParse.success) return { kind: 'badSchema', issues: styleParse.error.issues };
 
-  const merged = mergeArchitectureAndStyle(archParse.data, styleParse.data) as unknown as {
+  const merged = mergeFlowAndStyle(flowParse.data, styleParse.data) as unknown as {
     version: number;
     name: string;
     resetAction?: unknown;
@@ -552,29 +560,36 @@ export async function mutateMergedFlow<E extends { kind: string }>(
   };
 
   const outcome = mutator(merged);
-  if (outcome.kind !== 'ok') return outcome;
+  // E is generic — TS can't prove the narrowed branch isn't `{ kind: 'ok' }`,
+  // so we cast. By convention, E never reuses `'ok'` as a discriminant.
+  if (outcome.kind !== 'ok') return outcome as E;
 
-  // Final FlowSchema parse so per-kind invariants (event needs eventName, etc.)
+  // Final ResolvedFlowSchema parse so per-kind invariants (event needs eventName, etc.)
   // surface honestly instead of being silently papered over.
-  const finalParse = FlowSchema.safeParse(merged);
+  const finalParse = ResolvedFlowSchema.safeParse(merged);
   if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
 
-  const { architecture, style } = splitFlow(merged);
+  const { flow, style } = splitFlow(merged);
   // Re-validate the post-split files to catch the rare case where a forward-
   // compat field landed in the wrong bucket. Style validation is a no-op for
-  // empty maps; architecture revalidation rejects unknown keys via strict().
-  const archCheck = ArchitectureSchema.safeParse(architecture);
-  if (!archCheck.success) return { kind: 'badSchema', issues: archCheck.error.issues };
+  // empty maps; flow revalidation rejects unknown keys via strict().
+  const flowCheck = FlowSchema.safeParse(flow);
+  if (!flowCheck.success) return { kind: 'badSchema', issues: flowCheck.error.issues };
   const styleCheck = StyleSchema.safeParse(style);
   if (!styleCheck.success) return { kind: 'badSchema', issues: styleCheck.error.issues };
 
-  const stylePath = join(dirname(archPath), 'style.json');
+  const stylePath = join(dirname(flowPath), 'style.json');
   const styleIsEmpty =
     (!style.nodes || Object.keys(style.nodes as Record<string, unknown>).length === 0) &&
     (!style.connectors || Object.keys(style.connectors as Record<string, unknown>).length === 0);
 
+  // Pre-compute the bytes we're about to write so the caller can hand them
+  // straight to watcher.notifyWritten without re-reading the file.
+  const flowContent = `${JSON.stringify(flow, null, 2)}\n`;
+  const styleContent = styleIsEmpty ? '' : `${JSON.stringify(style, null, 2)}\n`;
+
   try {
-    writeFileAtomic(archPath, `${JSON.stringify(architecture, null, 2)}\n`);
+    writeFileAtomic(flowPath, flowContent);
   } catch (err) {
     return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
   }
@@ -583,13 +598,48 @@ export async function mutateMergedFlow<E extends { kind: string }>(
     if (styleIsEmpty) {
       if (existsSync(stylePath)) unlinkSync(stylePath);
     } else {
-      writeFileAtomic(stylePath, `${JSON.stringify(style, null, 2)}\n`);
+      writeFileAtomic(stylePath, styleContent);
     }
   } catch (err) {
     return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  return { kind: 'ok' };
+  const snap: FlowSnapshot = {
+    flow: finalParse.data as ResolvedFlow,
+    valid: true,
+    error: null,
+    filePath: flowPath,
+    parsedAt: Date.now(),
+  };
+  return { kind: 'ok', snap, flowContent, styleContent };
+}
+
+/**
+ * Wrap a mutation in the write lock AND broadcast a flow:reload directly
+ * from the post-write snapshot. Every mutation endpoint that updates flow
+ * state should go through this so:
+ *   1. The watcher's content-hash dedupe suppresses the fs-watcher echo for
+ *      this same write — no double broadcast, no double reparse.
+ *   2. The SSE event reaches the client without waiting for the fs debounce.
+ *
+ * For mutators whose ok branch carries no payload, `E` should be `never`.
+ */
+export async function mutateMergedFlowAndBroadcast<E extends { kind: string }>(
+  deps: OperationsDeps,
+  flowId: string,
+  flowPath: string,
+  mutator: MutateMergedFlowMutator<E>,
+): Promise<MutateMergedFlowResult<E>> {
+  return withFlowWriteLock(flowId, async () => {
+    const result = await mutateMergedFlow(flowPath, mutator);
+    if (result.kind === 'ok') {
+      // E is generic, so TS can't prove the ok branch is MutateMergedFlowOk —
+      // cast here, parallel to the cast inside mutateMergedFlow itself.
+      const ok = result as MutateMergedFlowOk;
+      deps.watcher?.notifyWritten(flowId, ok.snap, ok.flowContent, ok.styleContent);
+    }
+    return result;
+  });
 }
 
 export const reorderNodes = (
@@ -644,7 +694,7 @@ export const reorderNodes = (
 
 export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   const data = deps.registry.list().map((e) => {
-    const fullPath = resolveFilePath(e.repoPath, e.architecturePath);
+    const fullPath = resolveFilePath(e.repoPath, e.flowPath);
     const fileExists = existsSync(fullPath);
     return {
       id: e.id,
@@ -663,7 +713,7 @@ export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise
   const entry = registry.getById(flowId);
   if (!entry) return { kind: 'notFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   const snap = watcher?.snapshot(flowId) ?? watcher?.reparse(flowId) ?? null;
 
   const buildResponse = (s: FlowSnapshot): FlowGetResponse => ({
@@ -700,8 +750,8 @@ export async function registerFlowImpl(
   body: RegisterBody,
 ): Promise<RegisterFlowOutcome> {
   const { registry, watcher } = deps;
-  const { repoPath, architecturePath } = body;
-  const fullPath = resolveFilePath(repoPath, architecturePath);
+  const { repoPath, flowPath } = body;
+  const fullPath = resolveFilePath(repoPath, flowPath);
 
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
@@ -712,14 +762,14 @@ export async function registerFlowImpl(
     }
     // Schema validation failed — surface the issues as a bad-schema outcome
     // by re-running parse to get ZodIssue[].
-    let rawArch: unknown;
+    let rawFlow: unknown;
     try {
-      rawArch = JSON.parse(readFileSync(fullPath, 'utf8'));
+      rawFlow = JSON.parse(readFileSync(fullPath, 'utf8'));
     } catch (err) {
       return { kind: 'badJson', detail: String(err) };
     }
-    const archParse = ArchitectureSchema.safeParse(rawArch);
-    if (!archParse.success) return { kind: 'badSchema', issues: archParse.error.issues };
+    const flowParse = FlowSchema.safeParse(rawFlow);
+    if (!flowParse.success) return { kind: 'badSchema', issues: flowParse.error.issues };
     return { kind: 'badJson', detail: merged.error };
   }
   if (!merged.flow) return { kind: 'badJson', detail: merged.error ?? 'unknown error' };
@@ -728,7 +778,7 @@ export async function registerFlowImpl(
   const entry = registry.upsert({
     name: body.name ?? merged.flow.name,
     repoPath,
-    architecturePath,
+    flowPath,
     valid: true,
     lastModified,
   });
@@ -771,7 +821,7 @@ export async function createProjectImpl(
   const baseDir = deps.projectBaseDir ?? seeflowHome();
   const folderPath = join(baseDir, slugify(name));
 
-  const demoFullPath = join(folderPath, DEFAULT_ARCHITECTURE_RELATIVE_PATH);
+  const demoFullPath = join(folderPath, DEFAULT_FLOW_RELATIVE_PATH);
 
   if (existsSync(demoFullPath)) {
     let raw: unknown;
@@ -780,14 +830,14 @@ export async function createProjectImpl(
     } catch (err) {
       return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
     }
-    const archParse = ArchitectureSchema.safeParse(raw);
-    if (!archParse.success) return { kind: 'badSchema', issues: archParse.error.issues };
+    const flowParse = FlowSchema.safeParse(raw);
+    if (!flowParse.success) return { kind: 'badSchema', issues: flowParse.error.issues };
 
     const lastModified = statSync(demoFullPath).mtimeMs;
     const entry = registry.upsert({
       name,
       repoPath: folderPath,
-      architecturePath: DEFAULT_ARCHITECTURE_RELATIVE_PATH,
+      flowPath: DEFAULT_FLOW_RELATIVE_PATH,
       valid: true,
       lastModified,
     });
@@ -795,7 +845,7 @@ export async function createProjectImpl(
     return { kind: 'ok', data: { id: entry.id, slug: entry.slug, scaffolded: false } };
   }
 
-  // Architecture-only scaffold: empty nodes/connectors, no style.json needed.
+  // Flow-only scaffold: empty nodes/connectors, no style.json needed.
   const scaffold: Flow = { version: 2, name, nodes: [], connectors: [] };
 
   try {
@@ -818,7 +868,7 @@ export async function createProjectImpl(
   const entry = registry.upsert({
     name,
     repoPath: folderPath,
-    architecturePath: DEFAULT_ARCHITECTURE_RELATIVE_PATH,
+    flowPath: DEFAULT_FLOW_RELATIVE_PATH,
     valid: true,
     lastModified,
   });
@@ -826,7 +876,7 @@ export async function createProjectImpl(
   return { kind: 'ok', data: { id: entry.id, slug: entry.slug, scaffolded: true } };
 }
 
-// Append a new node to the demo. Auto-generates an id when absent; FlowSchema
+// Append a new node to the demo. Auto-generates an id when absent; ResolvedFlowSchema
 // is re-run on the post-mutation raw object before commit so a malformed
 // payload never produces a half-written file.
 export async function addNodeImpl(
@@ -842,7 +892,7 @@ export async function addNodeImpl(
     newNode.id = `node-${crypto.randomUUID()}`;
   }
   const newId = newNode.id as string;
-  // Default position so the post-merge FlowSchema parse passes. Position lives
+  // Default position so the post-merge ResolvedFlowSchema parse passes. Position lives
   // on style.json after the split — callers who care set it explicitly.
   if (!newNode.position || typeof newNode.position !== 'object') {
     newNode.position = { x: 0, y: 0 };
@@ -876,11 +926,14 @@ export async function addNodeImpl(
     }
   }
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  const result = await withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'writeFailed'; message: string }>(fullPath, (flow) => {
+  const result = await mutateMergedFlowAndBroadcast<{ kind: 'writeFailed'; message: string }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       flow.nodes.push(newNode);
       if (starterFile) {
         try {
@@ -891,7 +944,7 @@ export async function addNodeImpl(
         }
       }
       return { kind: 'ok' };
-    }),
+    },
   );
 
   if (result.kind === 'ok') return { kind: 'ok', data: { id: newId, node: newNode } };
@@ -912,11 +965,11 @@ const buildHtmlNodeStarter = (nodeId: string): string =>
 `;
 
 // Remove a node and cascade-delete every connector touching it in a single
-// atomic write. Final FlowSchema parse stays in place so a pre-existing
+// atomic write. Final ResolvedFlowSchema parse stays in place so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
 // US-016: when the removed node is an htmlNode whose data.htmlPath matches the
 // studio-managed shape `blocks/<id>.html`, the companion file is removed AFTER
-// the seeflow.json write succeeds. Hand-edited paths are left alone (symmetric
+// the flow.json write succeeds. Hand-edited paths are left alone (symmetric
 // with US-015's "client-supplied htmlPath wins, no starter file written").
 export async function deleteNodeImpl(
   deps: OperationsDeps,
@@ -926,13 +979,16 @@ export async function deleteNodeImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
   let managedHtmlAbsPath: string | undefined;
 
-  const result = await withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownNode' }>(fullPath, (flow) => {
+  const result = await mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       const idx = flow.nodes.findIndex((n) => n.id === nodeId);
       if (idx < 0) return { kind: 'unknownNode' };
       const removed = flow.nodes[idx];
@@ -942,7 +998,7 @@ export async function deleteNodeImpl(
         (cn) => cn.source !== nodeId && cn.target !== nodeId,
       );
       return { kind: 'ok' };
-    }),
+    },
   );
 
   if (result.kind === 'ok' && managedHtmlAbsPath) {
@@ -992,22 +1048,24 @@ export async function moveNodeImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  const result = await withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownNode' }>(fullPath, (flow) => {
+  const result = await mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       const node = flow.nodes.find((n) => n.id === nodeId) as
         | { id: string; position?: { x: number; y: number } }
         | undefined;
       if (!node) return { kind: 'unknownNode' };
       node.position = { x: position.x, y: position.y };
       return { kind: 'ok' };
-    }),
+    },
   );
 
   if (result.kind === 'ok') {
-    deps.watcher?.reparse(flowId);
     return { kind: 'ok', data: { position: { x: position.x, y: position.y } } };
   }
   return result;
@@ -1015,7 +1073,7 @@ export async function moveNodeImpl(
 
 // Apply a partial PATCH body to a single node. Mutation runs against the
 // raw parsed JSON (so unknown forward-compat fields survive a round-trip),
-// and the whole demo is re-validated through FlowSchema before commit so
+// and the whole demo is re-validated through ResolvedFlowSchema before commit so
 // partial writes can't break invariants like the connector→node superRefine.
 export async function patchNodeImpl(
   deps: OperationsDeps,
@@ -1026,17 +1084,15 @@ export async function patchNodeImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  return withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownNode' }>(fullPath, (flow) => {
-      const node = flow.nodes.find((n) => n.id === nodeId);
-      if (!node) return { kind: 'unknownNode' };
-      mergeNodeUpdates(node, updates);
-      return { kind: 'ok' };
-    }),
-  );
+  return mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' }>(deps, flowId, fullPath, (flow) => {
+    const node = flow.nodes.find((n) => n.id === nodeId);
+    if (!node) return { kind: 'unknownNode' };
+    mergeNodeUpdates(node, updates);
+    return { kind: 'ok' };
+  });
 }
 
 // Reorder a node within demo.nodes[] (changes paint order in the canvas).
@@ -1051,17 +1107,20 @@ export async function reorderNodeImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  const result = await withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownNode' } | { kind: 'noop' }>(fullPath, (flow) => {
+  const result = await mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' } | { kind: 'noop' }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       const fromIdx = flow.nodes.findIndex((n) => n.id === nodeId);
       if (fromIdx < 0) return { kind: 'unknownNode' };
       const moved = reorderNodes(flow.nodes, fromIdx, body);
       if (!moved) return { kind: 'noop' };
       return { kind: 'ok' };
-    }),
+    },
   );
 
   if (result.kind === 'noop') return { kind: 'ok' };
@@ -1070,7 +1129,7 @@ export async function reorderNodeImpl(
 
 // Append a new connector to demo.connectors. `id` is auto-generated when
 // absent and `kind` defaults to 'default' (the no-semantics user-drawn
-// variant). Source/target referential integrity is enforced by FlowSchema's
+// variant). Source/target referential integrity is enforced by ResolvedFlowSchema's
 // superRefine on the post-mutation parse.
 export async function addConnectorImpl(
   deps: OperationsDeps,
@@ -1089,15 +1148,13 @@ export async function addConnectorImpl(
   }
   const newId = newConn.id as string;
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  const result = await withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<never>(fullPath, (flow) => {
-      flow.connectors.push(newConn);
-      return { kind: 'ok' };
-    }),
-  );
+  const result = await mutateMergedFlowAndBroadcast<never>(deps, flowId, fullPath, (flow) => {
+    flow.connectors.push(newConn);
+    return { kind: 'ok' };
+  });
 
   if (result.kind === 'ok') return { kind: 'ok', data: { id: newId } };
   return result;
@@ -1108,7 +1165,7 @@ export async function addConnectorImpl(
 // When `kind` changes, the previous kind's payload fields are dropped first
 // so the connector doesn't carry phantom data; explicit `null` in the patch
 // clears the field on disk (used by reconnect-to-body to drop a pinned
-// handle id). The whole demo is re-validated through FlowSchema before
+// handle id). The whole demo is re-validated through ResolvedFlowSchema before
 // commit so the discriminated union catches missing-required-fields
 // (e.g. kind='event' without eventName) and the superRefine gates
 // source/target referential integrity + handle role invariants.
@@ -1121,21 +1178,24 @@ export async function patchConnectorImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  return withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownConnector' }>(fullPath, (flow) => {
+  return mutateMergedFlowAndBroadcast<{ kind: 'unknownConnector' }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       const conn = flow.connectors.find((cn) => cn.id === connectorId);
       if (!conn) return { kind: 'unknownConnector' };
       mergeConnectorUpdates(conn, updates);
       return { kind: 'ok' };
-    }),
+    },
   );
 }
 
 // Remove a connector by id. No cascade — node deletion is what cascades,
-// not connector deletion. Final FlowSchema parse still runs so a pre-existing
+// not connector deletion. Final ResolvedFlowSchema parse still runs so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
 export async function deleteConnectorImpl(
   deps: OperationsDeps,
@@ -1145,16 +1205,19 @@ export async function deleteConnectorImpl(
   const entry = deps.registry.getById(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  return withFlowWriteLock(flowId, () =>
-    mutateMergedFlow<{ kind: 'unknownConnector' }>(fullPath, (flow) => {
+  return mutateMergedFlowAndBroadcast<{ kind: 'unknownConnector' }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
       const idx = flow.connectors.findIndex((cn) => cn.id === connectorId);
       if (idx < 0) return { kind: 'unknownConnector' };
       flow.connectors.splice(idx, 1);
       return { kind: 'ok' };
-    }),
+    },
   );
 }
 
@@ -1165,12 +1228,12 @@ export async function deleteConnectorImpl(
 // =============================================================================
 
 export interface ValidateBody {
-  architecture: unknown;
+  flow: unknown;
   style?: unknown;
 }
 
 export interface ValidationIssue {
-  scope: 'architecture' | 'style' | 'cross';
+  scope: 'flow' | 'style' | 'cross';
   path: (string | number)[];
   message: string;
   code: string;
@@ -1181,11 +1244,11 @@ export type ValidateOutcome = { ok: true } | { ok: false; issues: ValidationIssu
 export function validateImpl(body: ValidateBody): ValidateOutcome {
   const issues: ValidationIssue[] = [];
 
-  const archParse = ArchitectureSchema.safeParse(body.architecture);
-  if (!archParse.success) {
-    for (const i of archParse.error.issues) {
+  const flowParse = FlowSchema.safeParse(body.flow);
+  if (!flowParse.success) {
+    for (const i of flowParse.error.issues) {
       issues.push({
-        scope: 'architecture',
+        scope: 'flow',
         path: [...i.path],
         message: i.message,
         code: i.code,
@@ -1212,11 +1275,11 @@ export function validateImpl(body: ValidateBody): ValidateOutcome {
     }
   }
 
-  if (archParse.success && styleData) {
-    const archNodeIds = new Set(archParse.data.nodes.map((n) => n.id));
-    const archConnIds = new Set(archParse.data.connectors.map((c) => c.id));
+  if (flowParse.success && styleData) {
+    const flowNodeIds = new Set(flowParse.data.nodes.map((n) => n.id));
+    const flowConnIds = new Set(flowParse.data.connectors.map((c) => c.id));
     for (const id of Object.keys(styleData.nodes ?? {})) {
-      if (!archNodeIds.has(id)) {
+      if (!flowNodeIds.has(id)) {
         issues.push({
           scope: 'cross',
           path: ['nodes', id],
@@ -1226,7 +1289,7 @@ export function validateImpl(body: ValidateBody): ValidateOutcome {
       }
     }
     for (const id of Object.keys(styleData.connectors ?? {})) {
-      if (!archConnIds.has(id)) {
+      if (!flowConnIds.has(id)) {
         issues.push({
           scope: 'cross',
           path: ['connectors', id],