@tuongaz/seeflow 0.1.25 → 0.1.27

package/src/operations.ts

@@ -7,28 +7,38 @@
 // Helpers extracted in US-003: node lifecycle (add/delete/move/reorder).
 // Future stories add patch_node + connector helpers alongside these.
 
-import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
+import { mergeArchitectureAndStyle, splitFlow } from './merge.ts';
 import { seeflowHome } from './paths.ts';
 import { type Registry, slugify } from './registry.ts';
 import {
   ColorTokenSchema,
-  type Demo,
-  DemoSchema,
   EdgePinSchema,
+  type Flow,
+  FlowSchema,
   SourceHandleIdSchema,
   TargetHandleIdSchema,
 } from './schema.ts';
+import { ArchitectureSchema, StyleSchema } from './schema.ts';
 import { writeSdkEmitIfNeeded } from './sdk-writer.ts';
-import type { DemoSnapshot, DemoWatcher } from './watcher.ts';
+import { type FlowSnapshot, type FlowWatcher, readMergedFlow } from './watcher.ts';
 
-const DEFAULT_DEMO_RELATIVE_PATH = '.seeflow/seeflow.json';
+const DEFAULT_ARCHITECTURE_RELATIVE_PATH = '.seeflow/architecture.json';
 
 export const RegisterBodySchema = z.object({
   name: z.string().min(1).optional(),
   repoPath: z.string().min(1),
-  demoPath: z.string().min(1),
+  architecturePath: z.string().min(1),
 });
 export type RegisterBody = z.infer<typeof RegisterBodySchema>;
 
@@ -58,7 +68,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 DemoSchema after the merge — this body schema just
+// the whole demo through FlowSchema after the merge — this body schema just
 // rejects unknown top-level keys to catch typos.
 export const NodePatchBodySchema = z
   .object({
@@ -79,7 +89,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; DemoSchema's
+    // iconNode-only: stroke color token. Lands at data.color; FlowSchema'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
@@ -204,7 +214,7 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
 
 export interface OperationsDeps {
   registry: Registry;
-  watcher?: DemoWatcher;
+  watcher?: FlowWatcher;
   /**
    * Override the base directory for new projects. Defaults to seeflowHome()
    * — `${SEEFLOW_WORKSPACE}/.seeflow` inside Docker, `~/.seeflow` locally.
@@ -213,7 +223,7 @@ export interface OperationsDeps {
   projectBaseDir?: string;
 }
 
-export interface DemoListItem {
+export interface FlowListItem {
   id: string;
   slug: string;
   name: string;
@@ -222,17 +232,17 @@ export interface DemoListItem {
   valid: boolean;
 }
 
-export interface DemoGetResponse {
+export interface FlowGetResponse {
   id: string;
   slug: string;
   name: string;
   filePath: string;
-  demo: Demo | null;
+  flow: Flow | null;
   valid: boolean;
   error: string | null;
 }
 
-export interface RegisterDemoSuccess {
+export interface RegisterFlowSuccess {
   id: string;
   slug: string;
   sdk: { outcome: 'written' | 'present' | 'skipped'; filePath: string | null };
@@ -244,21 +254,21 @@ export interface CreateProjectSuccess {
   scaffolded: boolean;
 }
 
-export type ListDemosOutcome = { kind: 'ok'; data: DemoListItem[] };
+export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
 
-export type GetDemoOutcome =
-  | { kind: 'ok'; data: DemoGetResponse }
+export type GetFlowOutcome =
+  | { kind: 'ok'; data: FlowGetResponse }
   | { kind: 'notFound' }
   | { kind: 'fileNotFound'; path: string };
 
-export type RegisterDemoOutcome =
-  | { kind: 'ok'; data: RegisterDemoSuccess }
+export type RegisterFlowOutcome =
+  | { kind: 'ok'; data: RegisterFlowSuccess }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; detail: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'sdkWriteFailed'; id: string; slug: string; message: string };
 
-export type DeleteDemoOutcome = { kind: 'ok' } | { kind: 'notFound' };
+export type DeleteFlowOutcome = { kind: 'ok' } | { kind: 'notFound' };
 
 export type CreateProjectOutcome =
   | { kind: 'ok'; data: CreateProjectSuccess }
@@ -272,7 +282,7 @@ export type CreateProjectOutcome =
 // same status code + JSON body it used to emit directly.
 export type AddNodeOutcome =
   | { kind: 'ok'; data: { id: string; node: Record<string, unknown> } }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -280,7 +290,7 @@ export type AddNodeOutcome =
 
 export type DeleteNodeOutcome =
   | { kind: 'ok' }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -289,7 +299,7 @@ export type DeleteNodeOutcome =
 
 export type MoveNodeOutcome =
   | { kind: 'ok'; data: { position: PositionBody } }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -298,7 +308,7 @@ export type MoveNodeOutcome =
 
 export type ReorderNodeOutcome =
   | { kind: 'ok' }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -307,7 +317,7 @@ export type ReorderNodeOutcome =
 
 export type PatchNodeOutcome =
   | { kind: 'ok' }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -316,7 +326,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 DemoSchema.
+// are enforced post-merge by re-parsing the whole demo through FlowSchema.
 const ConnectorKindSchema = z.enum(['http', 'event', 'queue', 'default']);
 export const ConnectorPatchBodySchema = z
   .object({
@@ -334,7 +344,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 DemoSchema parse rejects dangling references, so we don't
+    // post-merge FlowSchema 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(),
@@ -368,7 +378,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 DemoSchema would silently strip on parse but leave on disk).
+// behind, which FlowSchema would silently strip on parse but leave on disk).
 const CONNECTOR_KIND_FIELDS = ['method', 'url', 'eventName', 'queueName'] as const;
 
 export const mergeConnectorUpdates = (
@@ -395,7 +405,7 @@ export const mergeConnectorUpdates = (
 
 export type AddConnectorOutcome =
   | { kind: 'ok'; data: { id: string } }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -403,7 +413,7 @@ export type AddConnectorOutcome =
 
 export type PatchConnectorOutcome =
   | { kind: 'ok' }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
@@ -412,28 +422,28 @@ export type PatchConnectorOutcome =
 
 export type DeleteConnectorOutcome =
   | { kind: 'ok' }
-  | { kind: 'demoNotFound' }
+  | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'unknownConnector' }
   | { kind: 'writeFailed'; message: string };
 
-export const resolveDemoPath = (repoPath: string, demoPath: string): string =>
-  isAbsolute(demoPath) ? demoPath : join(repoPath, demoPath);
+export const resolveFilePath = (repoPath: string, architecturePath: string): string =>
+  isAbsolute(architecturePath) ? architecturePath : join(repoPath, architecturePath);
 
 // 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
 // older read clobbers the earlier writer's update). We chain writes per
-// demoId so the read+write sequence is effectively serialized.
-const demoWriteChains = new Map<string, Promise<unknown>>();
-export const withDemoWriteLock = <T>(demoId: string, fn: () => Promise<T>): Promise<T> => {
-  const prev = demoWriteChains.get(demoId) ?? Promise.resolve();
+// flowId so the read+write sequence is effectively serialized.
+const flowWriteChains = new Map<string, Promise<unknown>>();
+export const withFlowWriteLock = <T>(flowId: string, fn: () => Promise<T>): Promise<T> => {
+  const prev = flowWriteChains.get(flowId) ?? Promise.resolve();
   const next = prev.then(fn, fn);
   // Replace with a tail that swallows errors so the chain keeps moving even
   // if one write fails — but the original promise still rejects to its caller.
-  demoWriteChains.set(
-    demoId,
+  flowWriteChains.set(
+    flowId,
     next.catch(() => undefined),
   );
   return next as Promise<T>;
@@ -461,6 +471,127 @@ 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.
+ */
+type ReadRawResult =
+  | { kind: 'ok'; rawArch: Record<string, unknown>; rawStyle: Record<string, unknown> }
+  | { kind: 'badJson'; message: string };
+
+function readRawArchAndStyle(archPath: string): ReadRawResult {
+  let rawArch: unknown;
+  try {
+    rawArch = JSON.parse(readFileSync(archPath, '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' };
+  }
+  const stylePath = join(dirname(archPath), 'style.json');
+  let rawStyle: Record<string, unknown> = {};
+  if (existsSync(stylePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(stylePath, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { kind: 'badJson', message: 'style.json is not an object' };
+      }
+      rawStyle = parsed as Record<string, unknown>;
+    } catch (err) {
+      return {
+        kind: 'badJson',
+        message: `style.json: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+  return { kind: 'ok', rawArch: rawArch 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
+ * 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.
+ */
+type MutateMergedFlowMutator<E> = (flow: {
+  version: number;
+  name: string;
+  resetAction?: unknown;
+  nodes: Array<Record<string, unknown>>;
+  connectors: Array<Record<string, unknown>>;
+}) => { kind: 'ok' } | E;
+
+type MutateMergedFlowResult<E> =
+  | { kind: 'ok' }
+  | { kind: 'badJson'; message: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] }
+  | { kind: 'writeFailed'; message: string }
+  | E;
+
+export async function mutateMergedFlow<E extends { kind: string }>(
+  archPath: string,
+  mutator: MutateMergedFlowMutator<E>,
+): Promise<MutateMergedFlowResult<E>> {
+  const read = readRawArchAndStyle(archPath);
+  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 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 {
+    version: number;
+    name: string;
+    resetAction?: unknown;
+    nodes: Array<Record<string, unknown>>;
+    connectors: Array<Record<string, unknown>>;
+  };
+
+  const outcome = mutator(merged);
+  if (outcome.kind !== 'ok') return outcome;
+
+  // Final FlowSchema parse so per-kind invariants (event needs eventName, etc.)
+  // surface honestly instead of being silently papered over.
+  const finalParse = FlowSchema.safeParse(merged);
+  if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
+
+  const { architecture, 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 };
+  const styleCheck = StyleSchema.safeParse(style);
+  if (!styleCheck.success) return { kind: 'badSchema', issues: styleCheck.error.issues };
+
+  const stylePath = join(dirname(archPath), '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);
+
+  try {
+    writeFileAtomic(archPath, `${JSON.stringify(architecture, null, 2)}\n`);
+  } catch (err) {
+    return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+  }
+
+  try {
+    if (styleIsEmpty) {
+      if (existsSync(stylePath)) unlinkSync(stylePath);
+    } else {
+      writeFileAtomic(stylePath, `${JSON.stringify(style, null, 2)}\n`);
+    }
+  } catch (err) {
+    return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+  }
+
+  return { kind: 'ok' };
+}
+
 export const reorderNodes = (
   nodes: Array<Record<string, unknown>>,
   fromIdx: number,
@@ -511,9 +642,9 @@ export const reorderNodes = (
   }
 };
 
-export function listDemosImpl(deps: OperationsDeps): ListDemosOutcome {
+export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   const data = deps.registry.list().map((e) => {
-    const fullPath = resolveDemoPath(e.repoPath, e.demoPath);
+    const fullPath = resolveFilePath(e.repoPath, e.architecturePath);
     const fileExists = existsSync(fullPath);
     return {
       id: e.id,
@@ -527,20 +658,20 @@ export function listDemosImpl(deps: OperationsDeps): ListDemosOutcome {
   return { kind: 'ok', data };
 }
 
-export async function getDemoImpl(deps: OperationsDeps, demoId: string): Promise<GetDemoOutcome> {
+export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise<GetFlowOutcome> {
   const { registry, watcher } = deps;
-  const entry = registry.getById(demoId);
+  const entry = registry.getById(flowId);
   if (!entry) return { kind: 'notFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
-  const snap = watcher?.snapshot(demoId) ?? watcher?.reparse(demoId) ?? null;
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+  const snap = watcher?.snapshot(flowId) ?? watcher?.reparse(flowId) ?? null;
 
-  const buildResponse = (s: DemoSnapshot): DemoGetResponse => ({
+  const buildResponse = (s: FlowSnapshot): FlowGetResponse => ({
     id: entry.id,
     slug: entry.slug,
     name: entry.name,
     filePath: fullPath,
-    demo: s.demo,
+    flow: s.flow,
     valid: s.valid,
     error: s.valid ? null : s.error,
   });
@@ -551,75 +682,53 @@ export async function getDemoImpl(deps: OperationsDeps, demoId: string): Promise
   // callers without a long-lived watcher still get a current snapshot.
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  let raw: unknown;
-  try {
-    raw = await Bun.file(fullPath).json();
-  } catch (err) {
-    return {
-      kind: 'ok',
-      data: buildResponse({
-        demo: null,
-        valid: false,
-        error: `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
-        filePath: fullPath,
-        parsedAt: Date.now(),
-      }),
-    };
-  }
-  const parsed = DemoSchema.safeParse(raw);
-  if (!parsed.success) {
-    return {
-      kind: 'ok',
-      data: buildResponse({
-        demo: null,
-        valid: false,
-        error: parsed.error.issues
-          .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
-          .join('; '),
-        filePath: fullPath,
-        parsedAt: Date.now(),
-      }),
-    };
-  }
+  const result = readMergedFlow(fullPath);
   return {
     kind: 'ok',
     data: buildResponse({
-      demo: parsed.data,
-      valid: true,
-      error: null,
+      flow: result.flow,
+      valid: result.valid,
+      error: result.error,
       filePath: fullPath,
       parsedAt: Date.now(),
     }),
   };
 }
 
-export async function registerDemoImpl(
+export async function registerFlowImpl(
   deps: OperationsDeps,
   body: RegisterBody,
-): Promise<RegisterDemoOutcome> {
+): Promise<RegisterFlowOutcome> {
   const { registry, watcher } = deps;
-  const { repoPath, demoPath } = body;
-  const fullPath = resolveDemoPath(repoPath, demoPath);
+  const { repoPath, architecturePath } = body;
+  const fullPath = resolveFilePath(repoPath, architecturePath);
 
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  let demo: unknown;
-  try {
-    demo = await Bun.file(fullPath).json();
-  } catch (err) {
-    // REST uses String(err) here (preserves "SyntaxError: ..." prefix) —
-    // keep byte-identical so api.test.ts assertions stay green.
-    return { kind: 'badJson', detail: String(err) };
+  const merged = readMergedFlow(fullPath);
+  if (merged.error && merged.flow === null) {
+    if (merged.error.startsWith('Invalid JSON')) {
+      return { kind: 'badJson', detail: merged.error };
+    }
+    // Schema validation failed — surface the issues as a bad-schema outcome
+    // by re-running parse to get ZodIssue[].
+    let rawArch: unknown;
+    try {
+      rawArch = 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 };
+    return { kind: 'badJson', detail: merged.error };
   }
-
-  const demoParse = DemoSchema.safeParse(demo);
-  if (!demoParse.success) return { kind: 'badSchema', issues: demoParse.error.issues };
+  if (!merged.flow) return { kind: 'badJson', detail: merged.error ?? 'unknown error' };
 
   const lastModified = statSync(fullPath).mtimeMs;
   const entry = registry.upsert({
-    name: body.name ?? demoParse.data.name,
+    name: body.name ?? merged.flow.name,
     repoPath,
-    demoPath,
+    architecturePath,
     valid: true,
     lastModified,
   });
@@ -628,7 +737,7 @@ export async function registerDemoImpl(
 
   let sdkResult: { outcome: 'written' | 'present' | 'skipped'; filePath: string | null };
   try {
-    sdkResult = writeSdkEmitIfNeeded(repoPath, demoParse.data);
+    sdkResult = writeSdkEmitIfNeeded(repoPath, merged.flow);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { kind: 'sdkWriteFailed', id: entry.id, slug: entry.slug, message };
@@ -644,7 +753,7 @@ export async function registerDemoImpl(
   };
 }
 
-export function deleteDemoImpl(deps: OperationsDeps, idOrSlug: string): DeleteDemoOutcome {
+export function deleteFlowImpl(deps: OperationsDeps, idOrSlug: string): DeleteFlowOutcome {
   const { registry, watcher } = deps;
   const entry = registry.getById(idOrSlug) ?? registry.getBySlug(idOrSlug);
   if (!entry) return { kind: 'notFound' };
@@ -662,7 +771,7 @@ export async function createProjectImpl(
   const baseDir = deps.projectBaseDir ?? seeflowHome();
   const folderPath = join(baseDir, slugify(name));
 
-  const demoFullPath = join(folderPath, DEFAULT_DEMO_RELATIVE_PATH);
+  const demoFullPath = join(folderPath, DEFAULT_ARCHITECTURE_RELATIVE_PATH);
 
   if (existsSync(demoFullPath)) {
     let raw: unknown;
@@ -671,14 +780,14 @@ export async function createProjectImpl(
     } catch (err) {
       return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
     }
-    const demoParse = DemoSchema.safeParse(raw);
-    if (!demoParse.success) return { kind: 'badSchema', issues: demoParse.error.issues };
+    const archParse = ArchitectureSchema.safeParse(raw);
+    if (!archParse.success) return { kind: 'badSchema', issues: archParse.error.issues };
 
     const lastModified = statSync(demoFullPath).mtimeMs;
     const entry = registry.upsert({
       name,
       repoPath: folderPath,
-      demoPath: DEFAULT_DEMO_RELATIVE_PATH,
+      architecturePath: DEFAULT_ARCHITECTURE_RELATIVE_PATH,
       valid: true,
       lastModified,
     });
@@ -686,7 +795,8 @@ export async function createProjectImpl(
     return { kind: 'ok', data: { id: entry.id, slug: entry.slug, scaffolded: false } };
   }
 
-  const scaffold: Demo = { version: 1, name, nodes: [], connectors: [] };
+  // Architecture-only scaffold: empty nodes/connectors, no style.json needed.
+  const scaffold: Flow = { version: 2, name, nodes: [], connectors: [] };
 
   try {
     mkdirSync(join(folderPath, '.seeflow'), { recursive: true });
@@ -708,7 +818,7 @@ export async function createProjectImpl(
   const entry = registry.upsert({
     name,
     repoPath: folderPath,
-    demoPath: DEFAULT_DEMO_RELATIVE_PATH,
+    architecturePath: DEFAULT_ARCHITECTURE_RELATIVE_PATH,
     valid: true,
     lastModified,
   });
@@ -716,22 +826,27 @@ 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; DemoSchema
+// Append a new node to the demo. Auto-generates an id when absent; FlowSchema
 // 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(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   nodeBody: Record<string, unknown>,
 ): Promise<AddNodeOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
   const newNode = { ...nodeBody };
   if (typeof newNode.id !== 'string' || newNode.id.length === 0) {
     newNode.id = `node-${crypto.randomUUID()}`;
   }
   const newId = newNode.id as string;
+  // Default position so the post-merge FlowSchema 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 };
+  }
 
   // US-015: for htmlNode without a client-supplied htmlPath, allocate the
   // studio-managed `blocks/<id>.html` path and queue a starter-file write.
@@ -761,47 +876,23 @@ export async function addNodeImpl(
     }
   }
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as { nodes: Array<Record<string, unknown>> };
-    obj.nodes.push(newNode);
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    if (starterFile) {
-      try {
-        mkdirSync(dirname(starterFile.absPath), { recursive: true });
-        writeFileAtomic(starterFile.absPath, starterFile.content);
-      } catch (err) {
-        return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+  const result = await withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'writeFailed'; message: string }>(fullPath, (flow) => {
+      flow.nodes.push(newNode);
+      if (starterFile) {
+        try {
+          mkdirSync(dirname(starterFile.absPath), { recursive: true });
+          writeFileAtomic(starterFile.absPath, starterFile.content);
+        } catch (err) {
+          return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+        }
       }
-    }
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
+      return { kind: 'ok' };
+    }),
+  );
 
   if (result.kind === 'ok') return { kind: 'ok', data: { id: newId, node: newNode } };
   return result;
@@ -821,7 +912,7 @@ const buildHtmlNodeStarter = (nodeId: string): string =>
 `;
 
 // Remove a node and cascade-delete every connector touching it in a single
-// atomic write. Final DemoSchema parse stays in place so a pre-existing
+// atomic write. Final FlowSchema 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
@@ -829,68 +920,44 @@ const buildHtmlNodeStarter = (nodeId: string): string =>
 // with US-015's "client-supplied htmlPath wins, no starter file written").
 export async function deleteNodeImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   nodeId: string,
 ): Promise<DeleteNodeOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok'; managedHtmlAbsPath?: string }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownNode' }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as {
-      nodes: Array<Record<string, unknown>>;
-      connectors: Array<{ source: string; target: string }>;
-    };
-    const idx = obj.nodes.findIndex((n) => n.id === nodeId);
-    if (idx < 0) return { kind: 'unknownNode' };
-    const removed = obj.nodes[idx];
-    const managedHtmlAbsPath = managedHtmlNodePath(entry.repoPath, nodeId, removed);
-    obj.nodes.splice(idx, 1);
-    obj.connectors = obj.connectors.filter((cn) => cn.source !== nodeId && cn.target !== nodeId);
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return managedHtmlAbsPath ? { kind: 'ok', managedHtmlAbsPath } : { kind: 'ok' };
-  });
+  let managedHtmlAbsPath: string | undefined;
+
+  const result = await withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'unknownNode' }>(fullPath, (flow) => {
+      const idx = flow.nodes.findIndex((n) => n.id === nodeId);
+      if (idx < 0) return { kind: 'unknownNode' };
+      const removed = flow.nodes[idx];
+      managedHtmlAbsPath = managedHtmlNodePath(entry.repoPath, nodeId, removed);
+      flow.nodes.splice(idx, 1);
+      flow.connectors = flow.connectors.filter(
+        (cn) => cn.source !== nodeId && cn.target !== nodeId,
+      );
+      return { kind: 'ok' };
+    }),
+  );
 
-  if (result.kind === 'ok' && result.managedHtmlAbsPath) {
+  if (result.kind === 'ok' && managedHtmlAbsPath) {
     try {
-      unlinkSync(result.managedHtmlAbsPath);
+      unlinkSync(managedHtmlAbsPath);
     } catch (err) {
       const code = (err as NodeJS.ErrnoException | undefined)?.code;
       if (code !== 'ENOENT') {
         console.warn(
-          `[operations] failed to remove managed htmlNode file ${result.managedHtmlAbsPath}: ${
+          `[operations] failed to remove managed htmlNode file ${managedHtmlAbsPath}: ${
             err instanceof Error ? err.message : String(err)
           }`,
         );
       }
     }
-    return { kind: 'ok' };
   }
 
   return result;
@@ -918,52 +985,29 @@ const managedHtmlNodePath = (
 // schema doesn't yet recognize survive the round-trip untouched.
 export async function moveNodeImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   nodeId: string,
   position: PositionBody,
 ): Promise<MoveNodeOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownNode' }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as {
-      nodes: Array<{ id: string; position: { x: number; y: number } }>;
-    };
-    const onDiskNode = obj.nodes.find((n) => n.id === nodeId);
-    if (!onDiskNode) return { kind: 'unknownNode' };
-    onDiskNode.position = { x: position.x, y: position.y };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(obj, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
+  const result = await withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'unknownNode' }>(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') {
-    // Eagerly refresh snapshot so a subsequent GET /api/demos/:id (e.g. export)
-    // returns the updated position without waiting for the 100ms FSWatcher debounce.
-    deps.watcher?.reparse(demoId);
+    deps.watcher?.reparse(flowId);
     return { kind: 'ok', data: { position: { x: position.x, y: position.y } } };
   }
   return result;
@@ -971,55 +1015,28 @@ 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 DemoSchema before commit so
+// and the whole demo is re-validated through FlowSchema before commit so
 // partial writes can't break invariants like the connector→node superRefine.
 export async function patchNodeImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   nodeId: string,
   updates: NodePatchBody,
 ): Promise<PatchNodeOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownNode' }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as { nodes: Array<Record<string, unknown>> };
-    const onDiskNode = obj.nodes.find((n) => n.id === nodeId);
-    if (!onDiskNode) return { kind: 'unknownNode' };
-
-    mergeNodeUpdates(onDiskNode, updates);
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
-
-  return result;
+  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' };
+    }),
+  );
 }
 
 // Reorder a node within demo.nodes[] (changes paint order in the canvas).
@@ -1027,65 +1044,41 @@ export async function patchNodeImpl(
 // writing so we don't trigger a watcher echo for nothing.
 export async function reorderNodeImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   nodeId: string,
   body: ReorderBody,
 ): Promise<ReorderNodeOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownNode' }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as { nodes: Array<Record<string, unknown>> };
-    const fromIdx = obj.nodes.findIndex((n) => n.id === nodeId);
-    if (fromIdx < 0) return { kind: 'unknownNode' };
-
-    const moved = reorderNodes(obj.nodes, fromIdx, body);
-    if (!moved) return { kind: 'ok' };
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
+  const result = await withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'unknownNode' } | { kind: 'noop' }>(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' };
+    }),
+  );
 
-  return result;
+  if (result.kind === 'noop') return { kind: 'ok' };
+  return result as ReorderNodeOutcome;
 }
 
 // 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 DemoSchema's
+// variant). Source/target referential integrity is enforced by FlowSchema's
 // superRefine on the post-mutation parse.
 export async function addConnectorImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   connBody: Record<string, unknown>,
 ): Promise<AddConnectorOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
   const newConn = { ...connBody };
   if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
@@ -1096,38 +1089,15 @@ export async function addConnectorImpl(
   }
   const newId = newConn.id as string;
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as { connectors: Array<Record<string, unknown>> };
-    obj.connectors.push(newConn);
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
+  const result = await withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<never>(fullPath, (flow) => {
+      flow.connectors.push(newConn);
+      return { kind: 'ok' };
+    }),
+  );
 
   if (result.kind === 'ok') return { kind: 'ok', data: { id: newId } };
   return result;
@@ -1138,105 +1108,134 @@ 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 DemoSchema before
+// handle id). The whole demo is re-validated through FlowSchema 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.
 export async function patchConnectorImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   connectorId: string,
   updates: ConnectorPatchBody,
 ): Promise<PatchConnectorOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownConnector' }
-    | { kind: 'writeFailed'; message: string };
-
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
-
-    const obj = raw as { connectors: Array<Record<string, unknown>> };
-    const onDiskConn = obj.connectors.find((cn) => cn.id === connectorId);
-    if (!onDiskConn) return { kind: 'unknownConnector' };
-
-    mergeConnectorUpdates(onDiskConn, updates);
-
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
-
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
-    }
-    return { kind: 'ok' };
-  });
-
-  return result;
+  return withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'unknownConnector' }>(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 DemoSchema parse still runs so a pre-existing
+// not connector deletion. Final FlowSchema parse still runs so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
 export async function deleteConnectorImpl(
   deps: OperationsDeps,
-  demoId: string,
+  flowId: string,
   connectorId: string,
 ): Promise<DeleteConnectorOutcome> {
-  const entry = deps.registry.getById(demoId);
-  if (!entry) return { kind: 'demoNotFound' };
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
 
-  const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+  const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  type Inner =
-    | { kind: 'ok' }
-    | { kind: 'badJson'; message: string }
-    | { kind: 'badSchema'; issues: ZodIssue[] }
-    | { kind: 'unknownConnector' }
-    | { kind: 'writeFailed'; message: string };
+  return withFlowWriteLock(flowId, () =>
+    mutateMergedFlow<{ kind: 'unknownConnector' }>(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' };
+    }),
+  );
+}
+
+// =============================================================================
+// validateImpl — stateless schema validator. Powers POST /api/validate +
+// the validate_seeflow MCP tool. Schema-only: no file:// resolution, no
+// registry side-effects.
+// =============================================================================
 
-  const result = await withDemoWriteLock<Inner>(demoId, async () => {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(fullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', message: err instanceof Error ? err.message : String(err) };
-    }
-    const demoParsed = DemoSchema.safeParse(raw);
-    if (!demoParsed.success) return { kind: 'badSchema', issues: demoParsed.error.issues };
+export interface ValidateBody {
+  architecture: unknown;
+  style?: unknown;
+}
 
-    const obj = raw as { connectors: Array<{ id: string }> };
-    const idx = obj.connectors.findIndex((cn) => cn.id === connectorId);
-    if (idx < 0) return { kind: 'unknownConnector' };
-    obj.connectors.splice(idx, 1);
+export interface ValidationIssue {
+  scope: 'architecture' | 'style' | 'cross';
+  path: (string | number)[];
+  message: string;
+  code: string;
+}
 
-    const finalParse = DemoSchema.safeParse(raw);
-    if (!finalParse.success) return { kind: 'badSchema', issues: finalParse.error.issues };
+export type ValidateOutcome = { ok: true } | { ok: false; issues: ValidationIssue[] };
 
-    try {
-      writeFileAtomic(fullPath, `${JSON.stringify(raw, null, 2)}\n`);
-    } catch (err) {
-      return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+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) {
+      issues.push({
+        scope: 'architecture',
+        path: [...i.path],
+        message: i.message,
+        code: i.code,
+      });
     }
-    return { kind: 'ok' };
-  });
+  }
 
-  return result;
+  let styleData:
+    | { nodes?: Record<string, unknown>; connectors?: Record<string, unknown> }
+    | undefined;
+  if (body.style !== undefined) {
+    const styleParse = StyleSchema.safeParse(body.style);
+    if (!styleParse.success) {
+      for (const i of styleParse.error.issues) {
+        issues.push({
+          scope: 'style',
+          path: [...i.path],
+          message: i.message,
+          code: i.code,
+        });
+      }
+    } else {
+      styleData = styleParse.data as never;
+    }
+  }
+
+  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));
+    for (const id of Object.keys(styleData.nodes ?? {})) {
+      if (!archNodeIds.has(id)) {
+        issues.push({
+          scope: 'cross',
+          path: ['nodes', id],
+          message: `Style entry references unknown node id: ${id}`,
+          code: 'orphan_style_node',
+        });
+      }
+    }
+    for (const id of Object.keys(styleData.connectors ?? {})) {
+      if (!archConnIds.has(id)) {
+        issues.push({
+          scope: 'cross',
+          path: ['connectors', id],
+          message: `Style entry references unknown connector id: ${id}`,
+          code: 'orphan_style_connector',
+        });
+      }
+    }
+  }
+
+  return issues.length === 0 ? { ok: true } : { ok: false, issues };
 }