@xdelivered/emberflow 0.2.0

package/src/engine/httpError.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { HttpError, isHttpError } from './httpError';
+
+describe('HttpError', () => {
+  it('carries status and body', () => {
+    const e = new HttpError(404, { error: 'gone' });
+    expect(e.status).toBe(404);
+    expect(e.body).toEqual({ error: 'gone' });
+    expect(isHttpError(e)).toBe(true);
+    expect(isHttpError(new Error('x'))).toBe(false);
+  });
+});

package/src/engine/httpError.ts

@@ -0,0 +1,16 @@
+/** A typed error a node can throw to control the HTTP status/body of its operation. */
+export class HttpError extends Error {
+  readonly status: number;
+  readonly body?: unknown;
+
+  constructor(status: number, body?: unknown) {
+    super(`HTTP ${status}`);
+    this.name = 'HttpError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function isHttpError(e: unknown): e is HttpError {
+  return e instanceof HttpError;
+}

package/src/engine/index.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './registry';
+export * from './validation';
+export * from './trace';
+export * from './executor';
+export * from './output';
+export * from './publish';
+export * from './scenarios';
+export * from './httpError';
+export * from './schemaCheck';
+export * from './authVerify';

package/src/engine/output.ts

@@ -0,0 +1,21 @@
+import type { WorkflowDefinition, WorkflowRun } from './types';
+
+/**
+ * The output a finished run surfaces: the data collected by its Result nodes —
+ * exactly what the Dock's Output tab shows. A run with a single Result that
+ * produced output yields that output directly; multiple Results are keyed by
+ * node label; a run whose Result nodes were all skipped (or has none) yields
+ * undefined. Used to derive a Subflow node's return value on both hosts
+ * (browser store and server run registry), so subflow output follows the same
+ * convention users already see for a run.
+ */
+export function runOutput(run: WorkflowRun, flow: WorkflowDefinition): unknown {
+  const produced = flow.nodes.filter(
+    (n) => n.type === 'Result' && run.nodeStates[n.id]?.output !== undefined,
+  );
+  if (produced.length === 0) return undefined;
+  if (produced.length === 1) return run.nodeStates[produced[0].id]!.output;
+  const out: Record<string, unknown> = {};
+  for (const n of produced) out[n.label] = run.nodeStates[n.id]!.output;
+  return out;
+}

package/src/engine/publish.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest';
+import { NodeRegistry } from './registry';
+import { hashImplementation, isArtifact, publishFlow, verifyArtifact } from './publish';
+import type { NodeImplementation, WorkflowDefinition, WorkflowNode } from './types';
+
+// Two genuinely different Task implementation *sources* — closure capture does
+// not change impl.toString(), so distinct function bodies are what shifts the
+// hash. Keyed by a marker so tests can pick a build.
+const taskImpls: Record<string, NodeImplementation> = {
+  a: async () => ({ result: 'a' }),
+  different: async () => {
+    const doubled = 2 + 2;
+    return { result: 'different', doubled };
+  },
+};
+
+/** A registry whose `Task` implementation body is chosen by `marker`. */
+function makeRegistry(marker: keyof typeof taskImpls): NodeRegistry {
+  const registry = new NodeRegistry();
+  registry.register(
+    { type: 'Input', label: 'Input', category: 'input' },
+    async (ctx) => ({ ...ctx.runInput }),
+  );
+  registry.register({ type: 'Task', label: 'Task' }, taskImpls[marker]);
+  return registry;
+}
+
+const node = (id: string, type: string, extra: Partial<WorkflowNode> = {}): WorkflowNode => ({
+  id, type, label: id, position: { x: 0, y: 0 }, config: {}, ...extra,
+});
+
+function makeFlow(nodes: WorkflowNode[], edges: WorkflowDefinition['edges'] = []): WorkflowDefinition {
+  return {
+    id: 'f', name: 'f', version: 1, nodes, edges,
+    createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
+  };
+}
+
+const loginish = (): WorkflowDefinition =>
+  makeFlow(
+    [
+      node('input', 'Input', {
+        config: {
+          fields: [
+            { name: 'username', type: 'string', required: true },
+            { name: 'password', type: 'string', required: true },
+          ],
+          defaults: { username: 'ada' },
+        },
+      }),
+      node('task', 'Task'),
+    ],
+    [{ id: 'e1', source: 'input', target: 'task' }],
+  );
+
+describe('publishFlow', () => {
+  it('strips metadata.pinnedOutput from every node (dropping empty metadata)', async () => {
+    const flow = makeFlow([
+      node('input', 'Input'),
+      node('task', 'Task', { metadata: { pinnedOutput: { marker: 'pinned' }, note: 'keep' } }),
+    ]);
+    const artifact = await publishFlow(flow, makeRegistry('a'), () => '2026-07-02T00:00:00Z');
+
+    const task = artifact.flow.nodes.find((n) => n.id === 'task')!;
+    expect(task.metadata).toEqual({ note: 'keep' });
+    // Node whose metadata becomes empty loses the key entirely.
+    const inputNode = artifact.flow.nodes.find((n) => n.id === 'input')!;
+    expect(inputNode.metadata).toBeUndefined();
+    // Source flow is untouched (deep copy).
+    expect(flow.nodes.find((n) => n.id === 'task')!.metadata).toHaveProperty('pinnedOutput');
+  });
+
+  it('drops metadata when pinnedOutput was its only key', async () => {
+    const flow = makeFlow([
+      node('input', 'Input'),
+      node('task', 'Task', { metadata: { pinnedOutput: 42 } }),
+    ]);
+    const artifact = await publishFlow(flow, makeRegistry('a'));
+    expect(artifact.flow.nodes.find((n) => n.id === 'task')!.metadata).toBeUndefined();
+  });
+
+  it('lifts the input schema from the Input node config.fields', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'));
+    expect(artifact.inputSchema).toEqual([
+      { name: 'username', type: 'string', required: true },
+      { name: 'password', type: 'string', required: true },
+    ]);
+  });
+
+  it('uses [] when there is no Input node', async () => {
+    const flow = makeFlow([node('task', 'Task')]);
+    const artifact = await publishFlow(flow, makeRegistry('a'));
+    expect(artifact.inputSchema).toEqual([]);
+  });
+
+  it('ignores malformed field entries when lifting the schema', async () => {
+    const flow = makeFlow([
+      node('input', 'Input', { config: { fields: [{ name: 'ok', type: 'string' }, { type: 'string' }, 'nope'] } }),
+    ]);
+    const artifact = await publishFlow(flow, makeRegistry('a'));
+    expect(artifact.inputSchema).toEqual([{ name: 'ok', type: 'string' }]);
+  });
+
+  it('produces the emberflow/v1 envelope with a publishedAt from now()', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'), () => '2026-07-02T12:00:00Z');
+    expect(artifact.$artifact).toBe('emberflow/v1');
+    expect(artifact.publishedAt).toBe('2026-07-02T12:00:00Z');
+    expect(Object.keys(artifact.nodeHashes).sort()).toEqual(['Input', 'Task']);
+  });
+
+  it('hashes are stable for the same registry and change for a different implementation', async () => {
+    const a1 = await publishFlow(loginish(), makeRegistry('a'));
+    const a2 = await publishFlow(loginish(), makeRegistry('a'));
+    const b = await publishFlow(loginish(), makeRegistry('different'));
+    expect(a1.nodeHashes.Task).toBe(a2.nodeHashes.Task);
+    expect(a1.nodeHashes.Task).not.toBe(b.nodeHashes.Task);
+    // The Input node is identical across registries.
+    expect(a1.nodeHashes.Input).toBe(b.nodeHashes.Input);
+  });
+
+  it('strips scenarios on publish without mutating the source flow', async () => {
+    const flow = loginish();
+    flow.scenarios = [{ id: 's1', name: 'Happy path', input: { username: 'ada', password: 'x' } }];
+    const artifact = await publishFlow(flow, makeRegistry('a'));
+    expect(artifact.flow.scenarios).toBeUndefined();
+    expect(flow.scenarios).toEqual([
+      { id: 's1', name: 'Happy path', input: { username: 'ada', password: 'x' } },
+    ]);
+  });
+
+  it('throws on an invalid flow', async () => {
+    const flow = makeFlow([node('ghost', 'Nonexistent')]);
+    await expect(publishFlow(flow, makeRegistry('a'))).rejects.toThrow(/Cannot publish/);
+  });
+});
+
+describe('verifyArtifact', () => {
+  it('returns [] when the registry matches', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'));
+    expect(await verifyArtifact(artifact, makeRegistry('a'))).toEqual([]);
+  });
+
+  it('names the drifted type on an implementation mismatch', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'));
+    expect(await verifyArtifact(artifact, makeRegistry('different'))).toEqual(['Task']);
+  });
+
+  it('names unknown types missing from the registry', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'));
+    const bare = new NodeRegistry();
+    // Same Input body as makeRegistry, but Task is absent entirely.
+    bare.register({ type: 'Input', label: 'Input' }, async (ctx) => ({ ...ctx.runInput }));
+    expect(await verifyArtifact(artifact, bare)).toEqual(['Task']);
+  });
+});
+
+describe('isArtifact', () => {
+  it('accepts a published artifact', async () => {
+    const artifact = await publishFlow(loginish(), makeRegistry('a'));
+    expect(isArtifact(artifact)).toBe(true);
+  });
+
+  it('rejects plain flows and junk', () => {
+    expect(isArtifact(loginish())).toBe(false);
+    expect(isArtifact(null)).toBe(false);
+    expect(isArtifact({ $artifact: 'other' })).toBe(false);
+    expect(isArtifact(42)).toBe(false);
+  });
+});
+
+describe('hashImplementation', () => {
+  it('is a 64-char lowercase hex string', async () => {
+    const hash = await hashImplementation(async () => ({}));
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/engine/publish.ts

@@ -0,0 +1,127 @@
+import type { FieldDefinition, NodeImplementation, WorkflowDefinition } from './types';
+import type { NodeRegistry } from './registry';
+import { validateFlow } from './validation';
+
+/**
+ * A sealed, executable flow artifact. Carries the flow, the input schema lifted
+ * from its Input node, and a SHA-256 hash of every node type's implementation
+ * so the runner can refuse to execute a flow whose code has drifted.
+ */
+export interface PublishedArtifact {
+  $artifact: 'emberflow/v1';
+  publishedAt: string;
+  inputSchema: FieldDefinition[];
+  /** node TYPE -> sha256 hex of implementation.toString() */
+  nodeHashes: Record<string, string>;
+  flow: WorkflowDefinition;
+}
+
+const ARTIFACT_TAG = 'emberflow/v1';
+
+/** SHA-256 hex of an implementation's source text (WebCrypto — browser + Node). */
+export async function hashImplementation(impl: NodeImplementation): Promise<string> {
+  const bytes = new TextEncoder().encode(impl.toString());
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Distinct node types used by a flow, in first-seen order. */
+function distinctTypes(flow: WorkflowDefinition): string[] {
+  const seen: string[] = [];
+  for (const node of flow.nodes) {
+    if (!seen.includes(node.type)) seen.push(node.type);
+  }
+  return seen;
+}
+
+/** Lift the declared input schema from the flow's first Input node (or []). */
+function liftInputSchema(flow: WorkflowDefinition): FieldDefinition[] {
+  const input = flow.nodes.find((n) => n.type === 'Input');
+  const fields = input?.config?.fields;
+  if (!Array.isArray(fields)) return [];
+  return fields.filter(
+    (f): f is FieldDefinition =>
+      f !== null && typeof f === 'object' && typeof (f as { name?: unknown }).name === 'string',
+  );
+}
+
+/**
+ * Deep-copy a flow and strip dev-only fixtures: metadata.pinnedOutput from
+ * every node, and top-level scenarios. Both are authoring aids that have no
+ * business shipping in a published artifact.
+ */
+function sealFlow(flow: WorkflowDefinition): WorkflowDefinition {
+  const copy = structuredClone(flow);
+  for (const node of copy.nodes) {
+    if (!node.metadata) continue;
+    delete node.metadata.pinnedOutput;
+    if (Object.keys(node.metadata).length === 0) delete node.metadata;
+  }
+  delete copy.scenarios;
+  return copy;
+}
+
+/**
+ * Seal a flow into a PublishedArtifact: validate (error-severity issues throw),
+ * strip pins, lift the input schema, and hash each node type's implementation.
+ */
+export async function publishFlow(
+  flow: WorkflowDefinition,
+  registry: NodeRegistry,
+  now: () => string = () => new Date().toISOString(),
+): Promise<PublishedArtifact> {
+  const errors = validateFlow(flow, registry).filter((i) => i.severity === 'error');
+  if (errors.length > 0) {
+    throw new Error(`Cannot publish: ${errors.map((i) => i.message).join('; ')}`);
+  }
+
+  const sealed = sealFlow(flow);
+  const nodeHashes: Record<string, string> = {};
+  for (const type of distinctTypes(sealed)) {
+    nodeHashes[type] = await hashImplementation(registry.get(type).implementation);
+  }
+
+  return {
+    $artifact: ARTIFACT_TAG,
+    publishedAt: now(),
+    inputSchema: liftInputSchema(sealed),
+    nodeHashes,
+    flow: sealed,
+  };
+}
+
+/**
+ * Verify every node hash in an artifact against a live registry. Returns the
+ * list of drifted (hash mismatch) or unknown (unregistered) node types; an
+ * empty list means the artifact is safe to execute on this registry.
+ */
+export async function verifyArtifact(
+  artifact: PublishedArtifact,
+  registry: NodeRegistry,
+): Promise<string[]> {
+  const bad: string[] = [];
+  for (const [type, expected] of Object.entries(artifact.nodeHashes)) {
+    if (!registry.has(type)) {
+      bad.push(type);
+      continue;
+    }
+    const actual = await hashImplementation(registry.get(type).implementation);
+    if (actual !== expected) bad.push(type);
+  }
+  return bad;
+}
+
+/** Structural type guard for a PublishedArtifact envelope. */
+export function isArtifact(value: unknown): value is PublishedArtifact {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.$artifact === ARTIFACT_TAG &&
+    typeof v.publishedAt === 'string' &&
+    Array.isArray(v.inputSchema) &&
+    v.nodeHashes !== null &&
+    typeof v.nodeHashes === 'object' &&
+    v.flow !== null &&
+    typeof v.flow === 'object'
+  );
+}

package/src/engine/registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { NodeRegistry } from './registry';
+import type { NodeDefinition } from './types';
+
+const def = (type: string): NodeDefinition => ({ type, label: type });
+const impl = async () => ({});
+
+describe('NodeRegistry', () => {
+  it('registers and retrieves a node', () => {
+    const r = new NodeRegistry();
+    r.register(def('a'), impl);
+    expect(r.get('a').definition.type).toBe('a');
+    expect(r.has('a')).toBe(true);
+  });
+
+  it('throws on duplicate registration', () => {
+    const r = new NodeRegistry();
+    r.register(def('a'), impl);
+    expect(() => r.register(def('a'), impl)).toThrow(/already registered/);
+  });
+
+  it('throws on unknown type', () => {
+    expect(() => new NodeRegistry().get('nope')).toThrow(/Unknown node type/);
+  });
+
+  it('lists definitions', () => {
+    const r = new NodeRegistry();
+    r.register(def('a'), impl);
+    r.register(def('b'), impl);
+    expect(r.list().map((d) => d.type)).toEqual(['a', 'b']);
+  });
+});
+
+describe('NodeRegistry.registerDefinition', () => {
+  it('adds a metadata-only node whose implementation throws server-required', async () => {
+    const r = new NodeRegistry();
+    r.registerDefinition({ type: 'Remote', label: 'Remote' }, 'async () => ({})');
+    expect(r.has('Remote')).toBe(true);
+    expect(r.list().map((d) => d.type)).toContain('Remote');
+    expect(r.getSource('Remote')).toBe('async () => ({})');
+    await expect(r.get('Remote').implementation({} as never)).rejects.toThrow(/server/i);
+  });
+
+  it('does not overwrite an already-registered node', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'A', label: 'Real' }, async () => ({ real: true }));
+    r.registerDefinition({ type: 'A', label: 'Stub' });
+    expect(r.get('A').definition.label).toBe('Real');
+  });
+
+  it('getSource returns implementation source for real nodes', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'B', label: 'B' }, async () => ({ v: 1 }));
+    expect(r.getSource('B')).toContain('v: 1');
+  });
+
+  it('withSameNodes returns a new instance that shares the same nodes', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'C', label: 'C' }, async () => ({}));
+    const clone = r.withSameNodes();
+    expect(clone).not.toBe(r);
+    expect(clone.has('C')).toBe(true);
+  });
+});

package/src/engine/registry.ts

@@ -0,0 +1,80 @@
+import type { NodeDefinition, NodeImplementation } from './types';
+
+export interface RegisteredNode {
+  definition: NodeDefinition;
+  implementation: NodeImplementation;
+}
+
+export class NodeRegistry {
+  nodes = new Map<string, RegisteredNode>();
+  sources = new Map<string, string>();
+
+  register(definition: NodeDefinition, implementation: NodeImplementation): void {
+    if (this.nodes.has(definition.type)) {
+      throw new Error(`Node type already registered: ${definition.type}`);
+    }
+    this.nodes.set(definition.type, { definition, implementation });
+  }
+
+  get(type: string): RegisteredNode {
+    const node = this.nodes.get(type);
+    if (!node) throw new Error(`Unknown node type: ${type}`);
+    return node;
+  }
+
+  has(type: string): boolean {
+    return this.nodes.has(type);
+  }
+
+  /**
+   * Replace this registry's contents with another's, in place. Keeps this
+   * object's identity, so references held elsewhere (RunRegistry's execution
+   * registry, request-handler closures) immediately see the new node set. Used
+   * by the project-config hot-reload to pick up agent-authored nodes without a
+   * process restart (which would kill in-flight agent runs).
+   */
+  adopt(other: NodeRegistry): void {
+    this.nodes = other.nodes;
+    this.sources = other.sources;
+  }
+
+  list(): NodeDefinition[] {
+    return [...this.nodes.values()].map((n) => n.definition);
+  }
+
+  /**
+   * Register a definition-only node (metadata fetched from the runner). Its
+   * implementation is a stub that fails loudly if browser-executed — such
+   * nodes run on the server. Never overwrites a real registration.
+   */
+  registerDefinition(definition: NodeDefinition, source?: string): void {
+    if (this.nodes.has(definition.type)) return;
+    this.nodes.set(definition.type, {
+      definition,
+      implementation: async () => {
+        throw new Error(
+          `${definition.type} runs on the server — start the runner or switch execution to Server mode`,
+        );
+      },
+    });
+    if (source !== undefined) this.sources.set(definition.type, source);
+  }
+
+  /** Source text for display: stored source for definition-only nodes, else the impl's toString(). */
+  getSource(type: string): string | undefined {
+    if (this.sources.has(type)) return this.sources.get(type);
+    const node = this.nodes.get(type);
+    return node ? node.implementation.toString() : undefined;
+  }
+
+  /**
+   * A fresh registry instance sharing this one's node + source maps — a new
+   * top-level reference (so store subscribers re-render) without copying node data.
+   */
+  withSameNodes(): NodeRegistry {
+    const next = new NodeRegistry();
+    next.nodes = this.nodes;
+    next.sources = this.sources;
+    return next;
+  }
+}

package/src/engine/scenarios.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { findScenario, scenarioNames } from './scenarios';
+import type { WorkflowDefinition, WorkflowNode } from './types';
+
+const node = (id: string, type = 'plain'): WorkflowNode => ({
+  id, type, label: id, position: { x: 0, y: 0 }, config: {},
+});
+
+const flow = (scenarios?: WorkflowDefinition['scenarios']): WorkflowDefinition => ({
+  id: 'f', name: 'f', version: 1, nodes: [node('a')], edges: [],
+  createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
+  ...(scenarios ? { scenarios } : {}),
+});
+
+describe('findScenario', () => {
+  const scenarios = [
+    { id: 's1', name: 'Happy path', input: { userId: 'u1' } },
+    { id: 's2', name: 'Empty note', input: { userId: 'u2', note: '' } },
+  ];
+
+  it('finds a scenario by exact name', () => {
+    const f = flow(scenarios);
+    expect(findScenario(f, 'Happy path')).toEqual(scenarios[0]);
+  });
+
+  it('finds a scenario by id', () => {
+    const f = flow(scenarios);
+    expect(findScenario(f, 's2')).toEqual(scenarios[1]);
+  });
+
+  it('returns undefined when no scenario matches', () => {
+    const f = flow(scenarios);
+    expect(findScenario(f, 'nope')).toBeUndefined();
+  });
+
+  it('returns undefined when the flow has no scenarios array', () => {
+    const f = flow();
+    expect(findScenario(f, 'Happy path')).toBeUndefined();
+  });
+});
+
+describe('scenarioNames', () => {
+  it('lists names in order', () => {
+    const f = flow([
+      { id: 's1', name: 'Happy path', input: {} },
+      { id: 's2', name: 'Empty note', input: {} },
+    ]);
+    expect(scenarioNames(f)).toEqual(['Happy path', 'Empty note']);
+  });
+
+  it('returns an empty array when the flow has no scenarios', () => {
+    const f = flow();
+    expect(scenarioNames(f)).toEqual([]);
+  });
+});

package/src/engine/scenarios.ts

@@ -0,0 +1,29 @@
+import type { ScenarioDefinition, WorkflowDefinition } from './types';
+
+/** Find a scenario by name (exact) or id. Returns undefined when absent. */
+export function findScenario(
+  flow: WorkflowDefinition,
+  nameOrId: string,
+): ScenarioDefinition | undefined {
+  return flow.scenarios?.find((s) => s.name === nameOrId || s.id === nameOrId);
+}
+
+/** Names of a flow's scenarios, for error messages. */
+export function scenarioNames(flow: WorkflowDefinition): string[] {
+  return (flow.scenarios ?? []).map((s) => s.name);
+}
+
+/** Merge an op's flow-level `mocks` with a scenario's `mocks` (scenario wins
+ *  per nodeId) into the map an executor mock run consults. ONE merge shared
+ *  by both places that start a mock run: the live serving path
+ *  (server/index.ts POST /runs, when servingMode === 'mock') and the CLI test
+ *  runner's `--mock` flag (server/testRunner.ts) — so mock semantics can't
+ *  drift between "serve mock" and "test mock". */
+export function mergeMocks(
+  flow: WorkflowDefinition,
+  scenario?: ScenarioDefinition,
+): Record<string, unknown> {
+  const opMocks = (flow.mocks ?? {}) as Record<string, unknown>;
+  const scenarioMocks = (scenario?.mocks ?? {}) as Record<string, unknown>;
+  return { ...opMocks, ...scenarioMocks };
+}

package/src/engine/schemaCheck.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { validateAgainstSchema } from './schemaCheck';
+
+describe('validateAgainstSchema', () => {
+  it('passes when no schema', () => {
+    expect(validateAgainstSchema(undefined, { a: 1 })).toBeNull();
+  });
+  it('flags a missing required field', () => {
+    const s = { type: 'object', required: ['name'] };
+    expect(validateAgainstSchema(s, {})).toMatch(/name/);
+    expect(validateAgainstSchema(s, { name: 'x' })).toBeNull();
+  });
+  it('flags a wrong property type', () => {
+    const s = { type: 'object', properties: { age: { type: 'number' } } };
+    expect(validateAgainstSchema(s, { age: 'not a number' })).toMatch(/age/);
+    expect(validateAgainstSchema(s, { age: 5 })).toBeNull();
+  });
+  it('requires an object at the top when type is object', () => {
+    expect(validateAgainstSchema({ type: 'object' }, 'nope')).toMatch(/object/);
+  });
+});

package/src/engine/schemaCheck.ts

@@ -0,0 +1,35 @@
+type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+interface ObjectSchema {
+  type?: 'object';
+  required?: string[];
+  properties?: Record<string, { type?: PropType }>;
+}
+
+const typeOfValue = (v: unknown): PropType | 'null' | 'undefined' => {
+  if (v === null) return 'null';
+  if (v === undefined) return 'undefined';
+  if (Array.isArray(v)) return 'array';
+  return typeof v as PropType;
+};
+
+/** Minimal subset validator: object type, required keys, per-property primitive
+ *  type. Returns null when valid, else the first error message. Unknown schema
+ *  shapes impose no constraint (valid) — extend as real schemas demand. */
+export function validateAgainstSchema(schema: unknown, value: unknown): string | null {
+  if (!schema || typeof schema !== 'object') return null;
+  const s = schema as ObjectSchema;
+  if (s.type === 'object') {
+    if (typeOfValue(value) !== 'object') return 'expected an object';
+    const obj = value as Record<string, unknown>;
+    for (const key of s.required ?? []) {
+      if (!(key in obj) || obj[key] === undefined) return `missing required field: ${key}`;
+    }
+    for (const [key, spec] of Object.entries(s.properties ?? {})) {
+      if (obj[key] === undefined) continue;
+      if (spec.type && typeOfValue(obj[key]) !== spec.type) {
+        return `field ${key} must be a ${spec.type}`;
+      }
+    }
+  }
+  return null;
+}

package/src/engine/trace.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { InMemoryTraceSink } from './trace';
+import type { NodeExecutionSample } from './types';
+
+const sample = (id: string, nodeId: string): NodeExecutionSample => ({
+  id, workflowId: 'w', runId: 'r', nodeId, nodeType: 't', nodeLabel: 'T',
+  input: { id }, status: 'succeeded', startedAt: '2026-01-01T00:00:00Z',
+});
+
+describe('InMemoryTraceSink', () => {
+  it('records and filters by node, newest first', () => {
+    const sink = new InMemoryTraceSink();
+    sink.record(sample('s1', 'a'));
+    sink.record(sample('s2', 'b'));
+    sink.record(sample('s3', 'a'));
+    expect(sink.samplesFor('a').map((s) => s.id)).toEqual(['s3', 's1']);
+    expect(sink.all().map((s) => s.id)).toEqual(['s3', 's2', 's1']);
+  });
+});