create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/wf-ui-server/__tests__/workflow-node-store-utils.test.mjs

@@ -0,0 +1,125 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { makeHarnessTempRoot } from '../../../tests/support/temp-root.js';
+import { readJsonFile, writeJsonFileAtomic } from '../json-store-utils.mjs';
+import { createComponentNode, getComponentNode, listLiveComponentNodes } from '../component-node-store.mjs';
+import { createEventNode, getEventNode } from '../workflow-event-node-store.mjs';
+import { createCapabilityNode, getCapabilityNode } from '../workflow-capability-node-store.mjs';
+import { getGoalNode } from '../workflow-goal-node-store.mjs';
+
+function makeProject(prefix = 'wf-node-store-utils-') {
+  const projectRoot = makeHarnessTempRoot(prefix);
+  fs.mkdirSync(path.join(projectRoot, 'Harness', 'tasks'), { recursive: true });
+  return projectRoot;
+}
+
+function writeActiveTask(projectRoot, taskId = 'task-store-utils') {
+  fs.mkdirSync(path.join(projectRoot, 'Harness', 'tasks', taskId), { recursive: true });
+  fs.writeFileSync(path.join(projectRoot, 'Harness', 'PROGRESS.md'), `# PROGRESS.md\n\n## Active Task\n\n- ${taskId}\n`, 'utf8');
+  fs.writeFileSync(path.join(projectRoot, 'Harness', 'tasks', taskId, 'STATE.json'), JSON.stringify({
+    schemaVersion: 1,
+    taskId,
+    status: 'active',
+    phase: 'implement',
+    gate: 'VERIFY',
+    nextAction: 'Verify node store utilities.',
+    acceptance: [{ id: 'AC-001', text: 'Strict JSON reads', status: 'tracked' }],
+    links: { dependsOn: [], blocks: [] },
+  }, null, 2), 'utf8');
+  fs.writeFileSync(path.join(projectRoot, 'Harness', 'tasks', taskId, 'PLAN.md'), '# Plan\n', 'utf8');
+  fs.writeFileSync(path.join(projectRoot, 'Harness', 'tasks', taskId, 'PROGRESS.md'), '# Progress\n', 'utf8');
+  return `goal-${taskId}`;
+}
+
+test('W39-ATOMIC-WRITE writes pretty JSON through the shared atomic writer', () => {
+  const projectRoot = makeProject();
+  try {
+    const target = path.join(projectRoot, 'Harness', 'a2a', 'store', 'state.json');
+    writeJsonFileAtomic(target, { alpha: 1, nested: { beta: true } });
+
+    const body = fs.readFileSync(target, 'utf8');
+    assert.equal(body.endsWith('\n'), true);
+    assert.match(body, /\n  "alpha": 1,/);
+    assert.deepEqual(JSON.parse(body), { alpha: 1, nested: { beta: true } });
+    const leftovers = fs.readdirSync(path.dirname(target)).filter(name => name.endsWith('.tmp'));
+    assert.deepEqual(leftovers, []);
+  } finally {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test('W39-STRICT-READ distinguishes missing fallback from corrupt JSON', () => {
+  const projectRoot = makeProject();
+  try {
+    const missing = path.join(projectRoot, 'Harness', 'a2a', 'missing.json');
+    assert.deepEqual(readJsonFile(missing, { fallback: true }), { fallback: true });
+
+    const corrupt = path.join(projectRoot, 'Harness', 'a2a', 'corrupt.json');
+    fs.mkdirSync(path.dirname(corrupt), { recursive: true });
+    fs.writeFileSync(corrupt, '{', 'utf8');
+    assert.throws(() => readJsonFile(corrupt, null), (error) => {
+      assert.equal(error.code, 'CORRUPT_JSON');
+      assert.match(error.message, /Corrupt JSON store file/);
+      return true;
+    });
+  } finally {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test('W39-STRICT-READ keeps direct component reads strict while stale live lists skip missing state refs', () => {
+  const projectRoot = makeProject();
+  try {
+    const live = createComponentNode(projectRoot, {
+      type: 'markdown',
+      title: 'Live',
+      markdown: 'live',
+    });
+    const stale = createComponentNode(projectRoot, {
+      type: 'markdown',
+      title: 'Stale',
+      markdown: 'stale',
+    });
+    fs.rmSync(path.join(projectRoot, stale.node.statePath), { force: true });
+
+    assert.throws(() => getComponentNode(projectRoot, stale.node.nodeId), /STATE_MISMATCH|missing|out of sync/i);
+    assert.deepEqual(listLiveComponentNodes(projectRoot).map(node => node.nodeId), [live.node.nodeId]);
+
+    fs.writeFileSync(path.join(projectRoot, live.node.statePath), '{', 'utf8');
+    assert.throws(() => getComponentNode(projectRoot, live.node.nodeId), /Corrupt JSON store file/);
+    assert.throws(() => listLiveComponentNodes(projectRoot), /Corrupt JSON store file/);
+  } finally {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test('W39-STRICT-READ direct event, capability, and goal store reads reject corrupt JSON', () => {
+  const projectRoot = makeProject();
+  try {
+    const event = createEventNode(projectRoot, {
+      type: 'timer',
+      title: 'Strict Timer',
+    });
+    fs.writeFileSync(path.join(projectRoot, event.node.statePath), '{', 'utf8');
+    assert.throws(() => getEventNode(projectRoot, event.node.nodeId), /Corrupt JSON store file/);
+
+    const capability = createCapabilityNode(projectRoot, {
+      type: 'skill-group',
+      title: 'Strict Skills',
+      skills: [{ id: 'skill:wf-ui', name: 'wf-ui' }],
+    });
+    fs.writeFileSync(path.join(projectRoot, capability.node.statePath), '{', 'utf8');
+    assert.throws(() => getCapabilityNode(projectRoot, capability.node.nodeId), /Corrupt JSON store file/);
+
+    const goalNodeId = writeActiveTask(projectRoot);
+    getGoalNode(projectRoot, goalNodeId);
+    const sidecarPath = path.join(projectRoot, 'Harness', 'a2a', 'goal-nodes', goalNodeId, 'state.json');
+    fs.mkdirSync(path.dirname(sidecarPath), { recursive: true });
+    fs.writeFileSync(sidecarPath, '{', 'utf8');
+    assert.throws(() => getGoalNode(projectRoot, goalNodeId), /Corrupt JSON store file/);
+  } finally {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  }
+});

package/src/wf-ui-server/__tests__/workflow-registry-drift.test.mjs

@@ -0,0 +1,296 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { loadActionRegistry } from '../action-registry.mjs';
+import { workflowOntology } from '../workflow-ontology.mjs';
+
+// ── Two-way registry drift guard ─────────────────────────────────────────────
+// Harness/a2a/action-registry.json is the single source of truth for the
+// typed workflow-node action surface. This test keeps the registry and the
+// implementations in lockstep in BOTH directions forever:
+//
+//   Direction 1 (ghost guard): every adapter function export that matches the
+//     action-dispatch convention must be registered — an implemented-but-
+//     unregistered action (the audit's 6 ghost actions) fails here.
+//   Direction 2 (phantom guard): every registered non-special action must map
+//     to a real adapter module function; every special action must be on the
+//     hardcoded allowlist — a registered-but-unimplemented action (the audit's
+//     capability:read phantom) fails here.
+//   Direction 3 (surface guard): every action id surfaced by the ontology
+//     catalog (readable/writable/control/runtime) must be registered.
+//
+// The audit previously flagged 6 ghost actions: file.meta (const alias of
+// readMeta), agent.trackTerminalSpawn / markTerminalReady / clearTerminalState
+// (PTY terminal tracking), timer.isTimerControlAction /
+// timerControlActionsForState (timer control predicates). These are module
+// infrastructure, NOT action handlers: they are never dispatched as
+// "<type>.<name>" typed actions, and the test asserts they are NOT registered
+// (see D0 below).
+
+// ── Paths ──────────────────────────────────────────────────────────────────
+// This test lives at src/wf-ui-server/__tests__/; the repo root is 3 levels up.
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const ADAPTER_DIR = path.join(REPO_ROOT, 'src', 'wf-ui-server', 'workflow-node-types');
+const ADAPTER_FILE_SUFFIX = '-node.mjs';
+
+// ── Registry membership helper ─────────────────────────────────────────────
+// loadActionRegistry validates the legacy mainOnly actor shape that the P1
+// data layer replaced with spawnGate; the loader's actor validation update is
+// a later wave (backend gates). The drift guards below only read
+// id/nodeType/implementation, so fall back to the raw parsed file instead of
+// failing the whole suite on the stale actor rule.
+function loadRegistryForDrift(root) {
+  try {
+    return loadActionRegistry(root);
+  } catch {
+    const registryPath = path.join(root, 'Harness', 'a2a', 'action-registry.json');
+    return JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  }
+}
+
+const REGISTRY = loadRegistryForDrift(REPO_ROOT);
+const REGISTRY_IDS = new Set(REGISTRY.actions.map((action) => action.id));
+
+function registryHas(id) {
+  return REGISTRY_IDS.has(String(id));
+}
+
+// ── Hardcoded special-case allowlist ────────────────────────────────────────
+// Pairs permitted to exist as registered actions without adapter-backed
+// implementation (implementation.special === true). Every id on this list must
+// stay in the registry (D2a), and every registry special must be on this list
+// (D2b) — the two sets are asserted equal, so the list cannot rot.
+const SPECIAL_CASE_IDS = new Set([
+  // Server-intercepted in server.mjs before adapter dispatch (routes to
+  // sendRuntimeSessionInput / startWorkflowGraphNode / restartWorkflowGraphNode
+  // / stopRuntimeSession / setWorkflowNodeModel / executeGraphLayoutAction).
+  'agent.start',
+  'agent.restart',
+  'agent.stop',
+  'agent.sendInput',
+  'agent.setModel',
+  'agent.layout',
+  // Runtime-special-cased in workflow-node-runtime executeNodeAction before
+  // adapter dispatch.
+  'node.delete',
+  'node.restore',
+  'agent.readContext',
+  // Main-Agent graph action surface (executeAgentGraphAction).
+  'agent.createNode',
+  'agent.connectNodes',
+  'agent.disconnectNodes',
+  'agent.moveNode',
+  'agent.deleteNode',
+  'agent.deleteNodes',
+  'agent.readGraph',
+  // Server-special-cased in server.mjs before adapter dispatch (routes to
+  // executeGraphHistoryAction → undoGraphOp / redoGraphOp).
+  'graph.undo',
+  'graph.redo',
+]);
+
+// ── Documented non-action adapter exports (the audit's 6 ghost actions) ────
+// Adapter module exports that are module infrastructure rather than typed
+// action handlers. They are excluded from the ghost enumeration in D1 and must
+// never be registered (D0b keeps this honest in both directions).
+const NON_ACTION_EXPORTS = new Set([
+  'file.meta', // `export const meta = readMeta` — legacy alias, not a typed action
+  'agent.trackTerminalSpawn', // PTY terminal tracking helpers
+  'agent.markTerminalReady',
+  'agent.clearTerminalState',
+  'timer.isTimerControlAction', // timer control-predicate helpers
+  'timer.timerControlActionsForState',
+  'display.defaultDisplayTemplate', // display helper: themed fallback template
+  'display.renderHtml', // display helper: serve-time render + placeholder expansion
+  'display.reportHtmlPath', // display helper: html file location
+  'goal.updateTaskCapsuleOnComplete', // goal internal callback: auto-close task capsule on completion
+  'goal.updateTaskCapsuleOnReopen', // goal internal callback: restore phase on reopen
+]);
+
+// ── Adapter module enumeration ─────────────────────────────────────────────
+// ACTION_ADAPTERS in workflow-node-runtime.mjs is module-local, but its
+// surface is exactly the workflow-node-types/*-node.mjs files (the -node.mjs
+// suffix naturally excludes role-profile-store.mjs). The derived set is pinned
+// to the registry's adapter values in D1a, so a divergence on either side
+// fails the lockstep check.
+function listAdapterTypes() {
+  return fs
+    .readdirSync(ADAPTER_DIR)
+    .filter((file) => file.endsWith(ADAPTER_FILE_SUFFIX))
+    .map((file) => file.slice(0, -ADAPTER_FILE_SUFFIX.length))
+    .sort();
+}
+
+function adapterModuleUrl(type) {
+  return pathToFileURL(path.join(ADAPTER_DIR, `${type}${ADAPTER_FILE_SUFFIX}`)).href;
+}
+
+async function loadAdapterFunctionExports(type) {
+  const module = await import(adapterModuleUrl(type));
+  const names = [];
+  for (const name of Object.keys(module)) {
+    if (name === 'default') continue;
+    if (typeof module[name] === 'function') names.push(name);
+  }
+  return names.sort();
+}
+
+function adapterActionId(type, exportName) {
+  return `${type}.${exportName}`;
+}
+
+function registryAdapters(registry) {
+  return new Set(registry.actions.map((action) => action.implementation?.adapter).filter((a) => typeof a === 'string'));
+}
+
+// ── D0: detector calibration (negative self-check) ─────────────────────────
+test('D0a registry membership helper works both ways (negative self-check)', () => {
+  // A registered id is detected…
+  assert.equal(registryHas('agent.sendMessage'), true);
+  // …an unregistered id is detected (simulated ghost)…
+  assert.equal(registryHas('agent.fakeAction'), false);
+  // …and the audit's phantom is impossible: capability:read is not registered.
+  assert.equal(registryHas('capability.read'), false);
+  assert.equal(registryHas(''), false);
+  assert.equal(registryHas('markdown'), false);
+});
+
+test('D0b documented non-action exports: functions that must never be registered', async () => {
+  assert.ok(NON_ACTION_EXPORTS.size > 0);
+  for (const id of NON_ACTION_EXPORTS) {
+    const separator = id.indexOf('.');
+    const type = id.slice(0, separator);
+    const exportName = id.slice(separator + 1);
+    // The exclusion list stays load-bearing: the helper must still exist as a
+    // function export (or the list must be cleaned up)…
+    const module = await import(adapterModuleUrl(type));
+    assert.equal(
+      typeof module[exportName],
+      'function',
+      `${id} is listed as a non-action helper but is no longer a function export of the ${type} adapter`,
+    );
+    // …and it must never drift into the registry (a promoted helper becomes a
+    // real action and must be audited through D1/D2 instead).
+    assert.equal(
+      registryHas(id),
+      false,
+      `${id} is a non-action helper export but has a registry entry; remove it from NON_ACTION_EXPORTS and audit it as a real action`,
+    );
+  }
+});
+
+// ── Direction 1: adapters → registry (ghost guard) ─────────────────────────
+test('D1a adapter module set matches the registry adapter set', () => {
+  const diskAdapters = listAdapterTypes();
+  assert.deepEqual(diskAdapters, [...registryAdapters(REGISTRY)].sort());
+});
+
+test('D1b every adapter function export is registered (ghost guard)', async () => {
+  const unregistered = [];
+  for (const type of listAdapterTypes()) {
+    const exportNames = await loadAdapterFunctionExports(type);
+    for (const exportName of exportNames) {
+      const id = adapterActionId(type, exportName);
+      if (NON_ACTION_EXPORTS.has(id)) continue;
+      // Registered as "<type>.<export>", or explicitly allowed as a
+      // special-cased surface (SPECIAL_CASE_IDS).
+      if (!registryHas(id) && !SPECIAL_CASE_IDS.has(id)) {
+        unregistered.push(id);
+      }
+    }
+  }
+  assert.deepEqual(
+    unregistered,
+    [],
+    `implemented-but-unregistered action(s) (ghost actions): ${unregistered.join(', ')}`,
+  );
+});
+
+// ── Direction 2: registry → implementations (phantom guard) ────────────────
+test('D2a special registry entries are exactly the hardcoded allowlist', () => {
+  const registrySpecials = new Set(
+    REGISTRY.actions.filter((action) => action.implementation?.special === true).map((action) => action.id),
+  );
+  // Every special entry must be on the allowlist (no undocumented special).
+  const specialNotAllowed = [...registrySpecials].filter((id) => !SPECIAL_CASE_IDS.has(id));
+  assert.deepEqual(specialNotAllowed, [], `special action(s) missing from the allowlist: ${specialNotAllowed.join(', ')}`);
+  // Every allowlist id must be a registered special (no stale allowlist).
+  const allowedNotSpecial = [...SPECIAL_CASE_IDS].filter((id) => !registrySpecials.has(id));
+  assert.deepEqual(allowedNotSpecial, [], `allowlist id(s) not registered as special: ${allowedNotSpecial.join(', ')}`);
+});
+
+test('D2b every non-special registry entry is implemented (phantom guard)', async () => {
+  const diskAdapters = new Set(listAdapterTypes());
+  const missing = [];
+  for (const action of REGISTRY.actions) {
+    const impl = action.implementation;
+    if (impl.special === true) continue; // covered by D2a
+    const id = action.id;
+    if (!diskAdapters.has(impl.adapter)) {
+      missing.push(`${id} (adapter module ${impl.adapter}-node.mjs does not exist)`);
+      continue;
+    }
+    const module = await import(adapterModuleUrl(impl.adapter));
+    if (typeof module[impl.export] !== 'function') {
+      missing.push(`${id} (adapter ${impl.adapter} has no function export '${impl.export}')`);
+    }
+  }
+  assert.deepEqual(
+    missing,
+    [],
+    `registered-but-unimplemented action(s) (phantom actions): ${missing.join(', ')}`,
+  );
+});
+
+// ── Direction 3: ontology surface consistency (light) ──────────────────────
+test('D3 every ontology catalog action id (readable/writable/control/runtime) is registered', () => {
+  const catalog = workflowOntology(REPO_ROOT);
+  const surfaceIds = new Set();
+  for (const [type, entry] of Object.entries(catalog.nodeTypes || {})) {
+    for (const bucket of ['readableActions', 'writableActions', 'controlActions', 'runtimeActions']) {
+      if (Array.isArray(entry[bucket])) {
+        for (const id of entry[bucket]) surfaceIds.add(`${id} (${type}.${bucket})`);
+      }
+    }
+  }
+  assert.ok(surfaceIds.size > 0, 'ontology catalog exposes an empty action surface; nothing was checked');
+  const missing = [...surfaceIds].filter((labeled) => {
+    const id = labeled.slice(0, labeled.lastIndexOf(' ('));
+    return !registryHas(id);
+  });
+  assert.deepEqual(
+    missing,
+    [],
+    `ontology action id(s) outside the registry: ${missing.join(', ')}`,
+  );
+});
+
+test('D3b registry spawnGate "root" matches the ontology spawnRules in both directions', () => {
+  const catalog = workflowOntology(REPO_ROOT);
+  const gatedIds = new Set(
+    REGISTRY.actions.filter((action) => action.actor?.spawnGate === 'root').map((action) => action.id),
+  );
+  const ruleActionIds = new Set();
+  for (const [type, entry] of Object.entries(catalog.nodeTypes || {})) {
+    for (const rule of entry.spawnRules || []) {
+      assert.equal(rule.spawnRule, 'root-only', `ontology spawnRule for ${type}/${rule.actionId} must be root-only`);
+      assert.equal(rule.gate, 'root', `ontology spawnRule gate for ${type}/${rule.actionId} must be root`);
+      ruleActionIds.add(rule.actionId);
+    }
+  }
+  const missingRules = [...gatedIds].filter((id) => !ruleActionIds.has(id));
+  assert.deepEqual(
+    missingRules,
+    [],
+    `registry spawnGate "root" action(s) without an ontology spawnRule: ${missingRules.join(', ')}`,
+  );
+  const missingGates = [...ruleActionIds].filter((id) => !gatedIds.has(id));
+  assert.deepEqual(
+    missingGates,
+    [],
+    `ontology spawnRules action(s) without registry spawnGate "root": ${missingGates.join(', ')}`,
+  );
+});

package/src/wf-ui-server/__tests__/workflow-resource-handle-four-side.test.mjs

@@ -0,0 +1,217 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// ── Helpers (mirror workflow-node-runtime.test.mjs / workflow-magnetic-topology.test.mjs) ──
+function tempProjectRoot() {
+  const id = crypto.randomBytes(4).toString('hex');
+  const dir = path.join(process.cwd(), '.tmp-fourside-test-' + id);
+  fs.mkdirSync(path.join(dir, 'Harness', 'a2a', 'component-nodes'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'Harness', 'a2a', 'component-nodes', 'index.json'), JSON.stringify({ schemaVersion: 1, nodes: [] }));
+  fs.mkdirSync(path.join(dir, 'Harness', 'a2a'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'Harness', 'a2a', 'workflow-map.json'), JSON.stringify({ schemaVersion: 1, version: 1, nodes: [], edges: [], positions: {}, undoStack: [], redoStack: [], deletedNodes: [] }));
+  return dir;
+}
+
+function cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+}
+
+let store;
+let runtime;
+
+before(async () => {
+  store = await import('../a2a-store.mjs');
+  runtime = await import('../workflow-node-runtime.mjs');
+});
+
+// Node index passed to normalizeWorkflowGraphEdge so the normalizer can resolve
+// each endpoint's semantic type without persisting component-node state.
+const TYPED_NODES = [
+  { nodeId: 'md1', type: 'markdown' },
+  { nodeId: 'md2', type: 'markdown' },
+  { nodeId: 'ex1', type: 'excalidraw' },
+  { nodeId: 'fi1', type: 'file' },
+];
+
+function typedNodeIdFor(type) {
+  if (type === 'markdown') return 'md1';
+  if (type === 'excalidraw') return 'ex1';
+  if (type === 'file') return 'fi1';
+  throw new Error(`unknown typed node for ${type}`);
+}
+
+// Normalize a single handle on a typed resource node from a given endpoint role.
+function normalizeResourceHandle(root, type, handle, role) {
+  const typedId = typedNodeIdFor(type);
+  const edge = role === 'source'
+    ? { id: 'e1', from: typedId, to: 'md2', sourceHandle: handle, relation: 'wf-bridge' }
+    : { id: 'e1', from: 'md2', to: typedId, targetHandle: handle, relation: 'wf-bridge' };
+  const out = store.normalizeWorkflowGraphEdge(root, edge, TYPED_NODES);
+  return role === 'source' ? out.sourceHandle : out.targetHandle;
+}
+
+// ── Edge handle normalization (a2a-store) ──
+describe('Resource four-side handle normalization (a2a-store)', () => {
+  let root;
+  before(() => { root = tempProjectRoot(); });
+  after(() => cleanup(root));
+
+  it('accepts markdown:top and markdown:bottom as physical sides (source + target)', () => {
+    // Newly added top/bottom sides must be preserved verbatim.
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:top', 'source'), 'markdown:top');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:top', 'target'), 'markdown:top');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:bottom', 'source'), 'markdown:bottom');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:bottom', 'target'), 'markdown:bottom');
+  });
+
+  it('still accepts markdown:left and markdown:right (no regression)', () => {
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:left', 'source'), 'markdown:left');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'markdown:right', 'target'), 'markdown:right');
+  });
+
+  it('accepts scene:top and scene:bottom as physical sides', () => {
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'scene:top', 'source'), 'scene:top');
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'scene:top', 'target'), 'scene:top');
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'scene:bottom', 'source'), 'scene:bottom');
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'scene:bottom', 'target'), 'scene:bottom');
+  });
+
+  it('accepts file:top and file:bottom as physical sides', () => {
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:top', 'source'), 'file:top');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:top', 'target'), 'file:top');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:bottom', 'source'), 'file:bottom');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:bottom', 'target'), 'file:bottom');
+  });
+
+  it('treats file:left and file:right as bidirectional (role-independent, no input/output split)', () => {
+    // W6 + file input/output removal: the same physical side must be returned
+    // regardless of whether the file node is the source or target endpoint.
+    // Previously left=input / right=output; now both are plain bidirectional sides.
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:left', 'source'), 'file:left');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:left', 'target'), 'file:left');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:right', 'source'), 'file:right');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file:right', 'target'), 'file:right');
+    // A semantic alias like "file" still resolves, but to a physical side (not an input/output).
+    assert.equal(normalizeResourceHandle(root, 'file', 'file', 'source'), 'file:right');
+    assert.equal(normalizeResourceHandle(root, 'file', 'file', 'target'), 'file:left');
+  });
+
+  it('keeps bare top/right/bottom/left aliases as physical sides before semantic fallback (W10)', () => {
+    // Bare side strings must map to the primary semantic port on that physical
+    // side, for ALL four sides, across all three resource kinds.
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'top', 'source'), 'markdown:top');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'bottom', 'target'), 'markdown:bottom');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'left', 'source'), 'markdown:left');
+    assert.equal(normalizeResourceHandle(root, 'markdown', 'right', 'target'), 'markdown:right');
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'top', 'source'), 'scene:top');
+    assert.equal(normalizeResourceHandle(root, 'excalidraw', 'bottom', 'source'), 'scene:bottom');
+    assert.equal(normalizeResourceHandle(root, 'file', 'top', 'source'), 'file:top');
+    assert.equal(normalizeResourceHandle(root, 'file', 'bottom', 'target'), 'file:bottom');
+    assert.equal(normalizeResourceHandle(root, 'file', 'left', 'source'), 'file:left');
+    assert.equal(normalizeResourceHandle(root, 'file', 'right', 'target'), 'file:right');
+  });
+
+  it('strips physical-side suffix from relation (W6: relation carries no side)', () => {
+    // relation must never carry a physical-side suffix; it stays semantic-only.
+    const edge = {
+      id: 'rel-e1',
+      from: 'md1',
+      to: 'md2',
+      relation: 'markdown:top',
+      sourceHandle: 'markdown:top',
+      targetHandle: 'markdown:bottom',
+    };
+    const out = store.normalizeWorkflowGraphEdge(root, edge, TYPED_NODES);
+    assert.equal(out.relation, 'markdown', 'relation suffix :top must be stripped');
+    assert.equal(out.sourceHandle, 'markdown:top');
+    assert.equal(out.targetHandle, 'markdown:bottom');
+
+    // scene / file side suffixes are stripped too.
+    const sceneOut = store.normalizeWorkflowGraphEdge(root, {
+      id: 'rel-e2', from: 'ex1', to: 'md2',
+      relation: 'scene:bottom', sourceHandle: 'scene:bottom',
+    }, TYPED_NODES);
+    assert.equal(sceneOut.relation, 'scene');
+
+    const fileOut = store.normalizeWorkflowGraphEdge(root, {
+      id: 'rel-e3', from: 'fi1', to: 'md2',
+      relation: 'file:left', sourceHandle: 'file:left',
+    }, TYPED_NODES);
+    assert.equal(fileOut.relation, 'file');
+  });
+
+  it('rejects undirected duplicate edges regardless of which side they use', () => {
+    // Duplicate detection is unordered (A->B == B->A). The four-side expansion
+    // must not weaken this: the same endpoint pair is still a duplicate.
+    assert.throws(
+      () => store.assertUniqueWorkflowEdgePairs([
+        { id: 'a', from: 'md1', to: 'md2', relation: 'wf-bridge' },
+        { id: 'b', from: 'md2', to: 'md1', relation: 'wf-bridge' },
+      ]),
+      (err) => err.code === 'DUPLICATE_EDGE',
+    );
+    // Even when handles are normalized to specific sides, the bidirectional
+    // pair key collapses to the same unordered endpoint pair.
+    const e1 = store.normalizeWorkflowGraphEdge(root, {
+      id: 'x', from: 'md1', to: 'md2', sourceHandle: 'markdown:top', targetHandle: 'markdown:bottom',
+    }, TYPED_NODES);
+    const e2 = store.normalizeWorkflowGraphEdge(root, {
+      id: 'y', from: 'md2', to: 'md1', sourceHandle: 'markdown:left', targetHandle: 'markdown:right',
+    }, TYPED_NODES);
+    assert.throws(
+      () => store.assertUniqueWorkflowEdgePairs([e1, e2]),
+      (err) => err.code === 'DUPLICATE_EDGE',
+    );
+  });
+});
+
+// ── Snapshot handles (workflow-node-runtime) ──
+describe('Resource node snapshots expose 4 physical handles (workflow-node-runtime)', () => {
+  let root;
+  before(() => { root = tempProjectRoot(); });
+  after(() => cleanup(root));
+
+  const FOUR_SIDES = ['left', 'right', 'top', 'bottom'];
+
+  it('markdown snapshot exposes markdown:{top,right,bottom,left} on one bidirectional port', async () => {
+    const result = await runtime.createNode(root, { type: 'markdown', title: 'Four-side MD' });
+    assert.ok(result.ok);
+    const handles = result.node.graph.handles;
+    assert.deepEqual(handles.bidirectional, ['markdown']);
+    assert.deepEqual(handles.ports, ['markdown']);
+    assert.deepEqual(handles.inputs, []);
+    assert.deepEqual(handles.outputs, []);
+    assert.deepEqual(handles.physical.sort(), FOUR_SIDES.map(side => `markdown:${side}`).sort());
+  });
+
+  it('excalidraw snapshot exposes scene:{top,right,bottom,left} on one bidirectional port', async () => {
+    const result = await runtime.createNode(root, { type: 'excalidraw', title: 'Four-side Scene' });
+    assert.ok(result.ok);
+    const handles = result.node.graph.handles;
+    assert.deepEqual(handles.bidirectional, ['scene']);
+    assert.deepEqual(handles.ports, ['scene']);
+    assert.deepEqual(handles.inputs, []);
+    assert.deepEqual(handles.outputs, []);
+    assert.deepEqual(handles.physical.sort(), FOUR_SIDES.map(side => `scene:${side}`).sort());
+  });
+
+  it('file snapshot exposes file:{top,right,bottom,left} with NO input/output split', async () => {
+    const result = await runtime.createNode(root, {
+      type: 'file',
+      title: 'Four-side File',
+      file: { source: 'workspace', path: 'README.md', name: 'README.md', mime: 'text/markdown', size: 100 },
+    });
+    assert.ok(result.ok);
+    assert.equal(result.node.kind, 'file');
+    const handles = result.node.graph.handles;
+    // The input/output split is removed: file is a single bidirectional port.
+    assert.deepEqual(handles.bidirectional, ['file']);
+    assert.deepEqual(handles.ports, ['file']);
+    assert.deepEqual(handles.inputs, []);
+    assert.deepEqual(handles.outputs, []);
+    assert.deepEqual(handles.physical.sort(), FOUR_SIDES.map(side => `file:${side}`).sort());
+  });
+});