@openwop/openwop-conformance 1.0.0

package/src/scenarios/agentMemoryRedactionContract.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Multi-Agent Shift Phase 3 — SR-1 secret-redaction invariant.
+ *
+ * Verifies the SR-1 normative invariant: when a memory write contains
+ * a value the run's BYOK vault resolved during the run, the persisted
+ * entry MUST carry `[REDACTED:<secretId>]` in place of the plaintext.
+ * Read-back from MemoryAdapter MUST surface the redacted form.
+ *
+ * Capability-gated: skips when host doesn't advertise long-term memory.
+ * Fixture-gated: requires `conformance-agent-memory-redaction`
+ * (resolves a BYOK secret, writes a memory entry containing the
+ * plaintext, reads it back).
+ *
+ * @see docs/MULTI-AGENT-INTEGRATION-GAPS.md §`Phase 3`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { hasLongTermMemory } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-memory-redaction';
+const SKIP = !hasLongTermMemory() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentMemoryRedactionContract: SR-1 invariant', () => {
+  it('BYOK plaintext is redacted to [REDACTED:<secretId>] at the read surface', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status).toBe('completed');
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const body = snap.json as { variables?: Record<string, unknown> };
+
+    // Fixture convention: writes a memory entry containing a registered
+    // BYOK plaintext, then reads it back into `memoryReadback.content`.
+    // The read-side value MUST contain the redaction marker, not the
+    // plaintext.
+    const readback = body.variables?.memoryReadback as { content?: string } | undefined;
+    expect(readback).toBeDefined();
+    expect(readback!.content).toMatch(/\[REDACTED:[^\]]+\]/);
+  });
+});

package/src/scenarios/agentMemoryRoundTrip.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Multi-Agent Shift Phase 3 — MemoryAdapter list/get round-trip.
+ *
+ * Verifies that a host advertising `capabilities.agents.memoryBackends:
+ * ['long-term']` resolves `AgentRef.memoryRef` to MemoryEntry results
+ * via its MemoryAdapter, and that the entries conform to
+ * `schemas/memory-entry.schema.json`.
+ *
+ * Capability-gated: skips when host doesn't advertise long-term memory.
+ * Fixture-gated: requires `conformance-agent-memory-roundtrip`.
+ *
+ * @see schemas/memory-entry.schema.json
+ * @see schemas/memory-list-options.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { hasLongTermMemory } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-memory-roundtrip';
+const SKIP = !hasLongTermMemory() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentMemoryRoundTrip: write → read via MemoryAdapter', () => {
+  it('memory entries written during a run are readable via the resolved memoryRef', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status).toBe('completed');
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const body = snap.json as {
+      agent?: { memoryRef?: string };
+      variables?: Record<string, unknown>;
+    };
+
+    // Fixture convention: writes an entry then reads it back into a
+    // variable named `memoryReadback`. The variable's value MUST be a
+    // MemoryEntry-shaped object per schemas/memory-entry.schema.json.
+    const readback = body.variables?.memoryReadback as
+      | { id?: string; content?: string; tags?: string[]; createdAt?: string }
+      | undefined;
+    expect(readback).toBeDefined();
+    expect(typeof readback!.id).toBe('string');
+    expect(typeof readback!.content).toBe('string');
+    expect(Array.isArray(readback!.tags)).toBe(true);
+    expect(typeof readback!.createdAt).toBe('string');
+  });
+});

package/src/scenarios/agentMemoryTtlExpiry.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Multi-Agent Shift Phase 3 — TTL expiry semantics for MemoryEntry.
+ *
+ * Verifies that memory entries carrying `expiresAt` in the past are
+ * NOT surfaced by `MemoryAdapter.list()` / `get()`. The fixture writes
+ * an entry with `expiresAt` set in the past and another set in the
+ * future; the read-back surface only includes the future one.
+ *
+ * Capability-gated: skips when host doesn't advertise long-term memory.
+ * Fixture-gated: requires `conformance-agent-memory-ttl`.
+ *
+ * @see schemas/memory-entry.schema.json §`expiresAt`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { hasLongTermMemory } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-memory-ttl';
+const SKIP = !hasLongTermMemory() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentMemoryTtlExpiry: expired entries are excluded from list/get', () => {
+  it('list() excludes entries whose expiresAt is in the past', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status).toBe('completed');
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const body = snap.json as { variables?: Record<string, unknown> };
+
+    // Fixture writes one expired + one fresh entry, then reads via list().
+    // Result MUST include only the fresh entry.
+    const listResult = body.variables?.memoryList as Array<{ id?: string; expiresAt?: string }> | undefined;
+    expect(Array.isArray(listResult)).toBe(true);
+    const now = Date.now();
+    for (const e of listResult!) {
+      if (e.expiresAt) {
+        expect(new Date(e.expiresAt).getTime()).toBeGreaterThan(now);
+      }
+    }
+  });
+});

package/src/scenarios/agentMessageReducer.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Multi-Agent Shift Phase 1 — `message` reducer idempotency invariant.
+ *
+ * Verifies the canonical `message` reducer's contract from
+ * `spec/v1/channels-and-reducers.md` §`message`:
+ *   - Append-only — new messages land at the end of the list.
+ *   - Idempotent on `messageId` — a duplicate emission folds to a
+ *     single entry.
+ *   - Replay-deterministic — the same event sequence produces the
+ *     same final channel value.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.supported: true`. Fixture-gated: requires
+ * `conformance-message-reducer` (intentionally emits duplicate-id
+ * messages to exercise idempotency).
+ *
+ * @see spec/v1/channels-and-reducers.md §`message`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-message-reducer';
+const SKIP = !isAgentSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentMessageReducer: message reducer idempotency + append-only invariant', () => {
+  it('duplicate messageId emissions fold to a single channel entry', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status).toBe('completed');
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const body = snap.json as { channels?: Record<string, unknown> };
+    expect(body.channels).toBeDefined();
+
+    // Find any channel using the `message` reducer (host names vary;
+    // fixture convention is `conversation` or `messages`).
+    const channelEntries = Object.entries(body.channels ?? {});
+    const messageChannel = channelEntries.find(([, val]) => Array.isArray(val));
+    expect(messageChannel, 'fixture MUST expose at least one message-reducer channel').toBeDefined();
+
+    const messages = messageChannel![1] as Array<{ messageId?: string }>;
+    const messageIds = messages
+      .map((m) => m.messageId)
+      .filter((id): id is string => typeof id === 'string');
+
+    // Each messageId appears at most once (idempotency).
+    const uniq = new Set(messageIds);
+    expect(uniq.size).toBe(messageIds.length);
+  });
+});

package/src/scenarios/agentMetadata.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Multi-Agent Shift Phase 1 — agent identity (RunSnapshot.agent / runOrchestrator).
+ *
+ * Verifies:
+ *   1. Hosts advertising `capabilities.agents.supported: true` populate
+ *      `RunSnapshot.agent` and/or `RunSnapshot.runOrchestrator` with
+ *      AgentRef-shaped values when a run carries agent provenance.
+ *   2. The AgentRef shape conforms to `schemas/agent-ref.schema.json`
+ *      (required `agentId`; optional `name`, `modelClass`, `memoryRef`,
+ *      `version`, `sourceManifestId`).
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.supported: true`. Fixture-gated: requires
+ * `conformance-agent-identity` advertised in `capabilities.fixtures`.
+ *
+ * @see spec/v1/capabilities.md §`agents`
+ * @see schemas/agent-ref.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-identity';
+const SKIP = !isAgentSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentMetadata: RunSnapshot.agent + runOrchestrator wire-shape', () => {
+  it('host populates AgentRef-shaped agent identity on RunSnapshot', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(['completed', 'failed']).toContain(terminal.status);
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    expect(snap.status).toBe(200);
+    const body = snap.json as { agent?: { agentId?: string }; runOrchestrator?: { agentId?: string } };
+
+    const hasAgent = body.agent && typeof body.agent.agentId === 'string';
+    const hasOrch = body.runOrchestrator && typeof body.runOrchestrator.agentId === 'string';
+    expect(
+      hasAgent || hasOrch,
+      'fixture-runs MUST populate at least one of RunSnapshot.agent / runOrchestrator',
+    ).toBe(true);
+
+    if (hasAgent) {
+      expect(body.agent!.agentId!.length).toBeGreaterThanOrEqual(3);
+    }
+    if (hasOrch) {
+      expect(body.runOrchestrator!.agentId!.length).toBeGreaterThanOrEqual(3);
+    }
+  });
+});

package/src/scenarios/agentPackExport.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Multi-Agent Shift Phase 2 — agent-pack export round-trips workspace agents → AgentManifest.
+ *
+ * Verifies that a host's workspace-scoped agent registry can project
+ * agents into the canonical AgentManifest shape for export/distribution.
+ * Round-trip: install pack → workspace gets agents → export workspace
+ * yields a manifest set that re-installs cleanly.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.supported: true`. Fixture-gated: requires
+ * `conformance-agent-pack-export`.
+ *
+ * @see schemas/agent-manifest.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-pack-export';
+const SKIP = !isAgentSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentPackExport: workspace agents project to AgentManifest', () => {
+  it('exported manifests contain required AgentManifest fields', async () => {
+    const res = await driver.get('/v1/packs/export');
+    if (res.status === 404 || res.status === 501) {
+      // Host doesn't expose pack-export over REST; treated as skip.
+      return;
+    }
+    expect(res.status).toBe(200);
+
+    const body = res.json as {
+      manifests?: Array<{ agentId?: string; modelClass?: string; sourceManifestId?: string }>;
+    };
+    const manifests = body.manifests ?? [];
+    expect(manifests.length).toBeGreaterThan(0);
+
+    for (const m of manifests) {
+      expect(typeof m.agentId).toBe('string');
+      // Exported manifests SHOULD carry sourceManifestId provenance when
+      // they originated from a prior install (covered by agentPackProvenance).
+    }
+  });
+});

package/src/scenarios/agentPackInstall.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Multi-Agent Shift Phase 2 — agent-pack install registers AgentManifest entries.
+ *
+ * Verifies that a pack containing an `agents[]` array surfaces those
+ * agent manifests via the host's pack registry. The wire-shape contract
+ * for AgentManifest entries is `schemas/agent-manifest.schema.json`.
+ *
+ * Capability-gated: skips when host doesn't advertise either
+ * `capabilities.agents.supported: true` OR the pack-registry surface
+ * (registry-operations.md). Fixture-gated: requires
+ * `conformance-agent-pack-install` advertised.
+ *
+ * @see schemas/agent-manifest.schema.json
+ * @see spec/v1/node-packs.md §`Manifest format`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-pack-install';
+const SKIP = !isAgentSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentPackInstall: pack agents[] entries surface as AgentManifest', () => {
+  it('host exposes installed agent manifests with required AgentManifest fields', async () => {
+    // Host-specific pack-listing endpoint. The conformance suite probes
+    // common paths; hosts that don't expose pack listings via REST mark
+    // this scenario as skip via their own capability advertisement.
+    const res = await driver.get('/v1/packs');
+    if (res.status === 404 || res.status === 501) {
+      // Host doesn't expose pack registry over REST; scenario assertion is
+      // skipped (capability surface is host-internal).
+      return;
+    }
+    expect(res.status).toBe(200);
+
+    const body = res.json as {
+      packs?: Array<{ agents?: Array<{ agentId?: string; modelClass?: string }> }>;
+    };
+    const packs = body.packs ?? [];
+    const allAgents = packs.flatMap((p) => p.agents ?? []);
+
+    expect(allAgents.length).toBeGreaterThan(0);
+    for (const a of allAgents) {
+      expect(typeof a.agentId).toBe('string');
+      expect(a.agentId!.length).toBeGreaterThanOrEqual(3);
+    }
+  });
+});

package/src/scenarios/agentPackProvenance.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Multi-Agent Shift Phase 2 — sourceManifestId provenance round-trip.
+ *
+ * Verifies that when a workspace agent originates from a pack install,
+ * the agent's runtime AgentRef AND the exported AgentManifest both
+ * carry the original `sourceManifestId` so audit consumers can trace
+ * agents back to their distribution source.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.supported: true`. Fixture-gated: requires
+ * `conformance-agent-pack-provenance`.
+ *
+ * @see schemas/agent-ref.schema.json §`sourceManifestId`
+ * @see schemas/agent-manifest.schema.json §`sourceManifestId`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-pack-provenance';
+const SKIP = !isAgentSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentPackProvenance: sourceManifestId survives install + run', () => {
+  it('run-level AgentRef carries sourceManifestId pointing back to the install source', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const body = snap.json as {
+      agent?: { agentId?: string; sourceManifestId?: string };
+      runOrchestrator?: { agentId?: string; sourceManifestId?: string };
+    };
+
+    const refs = [body.agent, body.runOrchestrator].filter(
+      (r): r is { agentId?: string; sourceManifestId?: string } => Boolean(r),
+    );
+    expect(refs.length).toBeGreaterThan(0);
+
+    // At least one of the run's AgentRefs MUST carry sourceManifestId
+    // when the fixture's agent originated from a pack install.
+    const withProvenance = refs.filter((r) => typeof r.sourceManifestId === 'string');
+    expect(
+      withProvenance.length,
+      'pack-installed agents MUST surface sourceManifestId on their runtime AgentRef projection',
+    ).toBeGreaterThan(0);
+  });
+});

package/src/scenarios/agentReasoningEvents.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Multi-Agent Shift Phase 1 — agent.* reasoning event family.
+ *
+ * Verifies that hosts emit the canonical `agent.*` event types per
+ * `run-event.schema.json` + per-event payload contract in
+ * `run-event-payloads.schema.json` §`agentReasoned` / `agentToolCalled` /
+ * `agentToolReturned` / `agentHandoff` / `agentDecided`.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.supported: true` OR when reasoning verbosity
+ * is `'off'` (no `agent.reasoned` events expected).
+ *
+ * @see schemas/run-event-payloads.schema.json
+ * @see spec/v1/capabilities.md §`agents.reasoning`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import {
+  isAgentSupported,
+  getReasoningVerbosity,
+} from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-reasoning';
+const SKIP =
+  !isAgentSupported() ||
+  getReasoningVerbosity() === 'off' ||
+  !isFixtureAdvertised(FIXTURE);
+
+const REASONING_EVENT_TYPES = new Set([
+  'agent.reasoned',
+  'agent.toolCalled',
+  'agent.toolReturned',
+  'agent.handoff',
+  'agent.decided',
+]);
+
+describe.skipIf(SKIP)('agentReasoningEvents: agent.* event family emission', () => {
+  it('host emits at least one canonical agent.* event during a reasoning-fixture run', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    expect(events.status).toBe(200);
+    const list = (events.json as { events?: Array<{ type: string; payload?: Record<string, unknown> }> })
+      .events ?? [];
+
+    const agentEvents = list.filter((e) => REASONING_EVENT_TYPES.has(e.type));
+    expect(agentEvents.length).toBeGreaterThan(0);
+
+    // Every agent.* event payload MUST carry `agentId` (per RFC 0002 §C).
+    for (const ev of agentEvents) {
+      expect(typeof ev.payload?.agentId).toBe('string');
+      expect((ev.payload!.agentId as string).length).toBeGreaterThanOrEqual(3);
+    }
+
+    // agent.toolCalled / agent.toolReturned MUST share a `callId` correlation.
+    const calls = agentEvents.filter((e) => e.type === 'agent.toolCalled');
+    const returns = agentEvents.filter((e) => e.type === 'agent.toolReturned');
+    for (const ret of returns) {
+      const callId = ret.payload?.callId as string | undefined;
+      if (callId === undefined) continue;
+      const matched = calls.find((c) => c.payload?.callId === callId);
+      expect(matched, `agent.toolReturned.callId=${callId} MUST pair with a prior agent.toolCalled`).toBeDefined();
+    }
+  });
+});

package/src/scenarios/append-ordering.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Track 13: append-reducer ordering (channels-and-reducers.md v1.1).
+ *
+ * Verifies the intra-engine total-order rule: for the `append` reducer
+ * (and its bounded variants `votes`/`feedback`), the folded array MUST
+ * reflect the per-run `sequence` order of the backing `channel.written`
+ * events. Replays MUST NOT reorder.
+ *
+ * Capability gating: skips unless a host advertises a fixture that
+ * writes to an append-reducer channel. `conformance-multi-node` is the
+ * primary candidate; hosts MAY seed a dedicated
+ * `conformance-append-ordering` fixture.
+ *
+ * @see spec/v1/channels-and-reducers.md §"Append ordering"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const CANDIDATES = ['conformance-append-ordering', 'conformance-multi-node'] as const;
+const FIXTURE = CANDIDATES.find((id) => isFixtureAdvertised(id)) ?? null;
+const SKIP = !FIXTURE;
+
+interface ChannelWrittenPayload {
+  channel?: string;
+  value?: unknown;
+}
+
+interface RunEvent {
+  type: string;
+  sequence: number;
+  payload?: ChannelWrittenPayload;
+}
+
+describe.skipIf(SKIP)('append-ordering: folded channel reflects event sequence', () => {
+  it('append-reducer channels project entries in event-sequence order', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE! });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId, { timeoutMs: 30_000 });
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events?: RunEvent[] }).events ?? [];
+
+    // Group channel.written events by channel.
+    const byChannel = new Map<string, RunEvent[]>();
+    for (const e of list) {
+      if (e.type !== 'channel.written') continue;
+      const ch = e.payload?.channel;
+      if (typeof ch !== 'string') continue;
+      const arr = byChannel.get(ch) ?? [];
+      arr.push(e);
+      byChannel.set(ch, arr);
+    }
+
+    if (byChannel.size === 0) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[append-ordering] fixture emitted no channel.written events; skipping ordering assertions',
+      );
+      return;
+    }
+
+    // For each channel, sequence MUST be strictly increasing within the run.
+    for (const [channel, writes] of byChannel) {
+      for (let i = 1; i < writes.length; i++) {
+        expect(writes[i].sequence, driver.describe(
+          'channels-and-reducers.md §"Append ordering"',
+          `channel '${channel}': channel.written events MUST appear in sequence order in the event log`,
+        )).toBeGreaterThan(writes[i - 1].sequence);
+      }
+    }
+
+    // Cross-check against the projected channel state on the run snapshot
+    // (when surfaced) — projected array length MUST equal the number of writes.
+    const snapshot = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const channels = (snapshot.json as { channels?: Record<string, unknown> }).channels ?? {};
+    for (const [channel, writes] of byChannel) {
+      const projected = (channels as Record<string, unknown>)[channel];
+      if (Array.isArray(projected)) {
+        expect(projected.length, driver.describe(
+          'channels-and-reducers.md §"Append ordering"',
+          `channel '${channel}': projected array length MUST equal #channel.written events`,
+        )).toBe(writes.length);
+      }
+    }
+  });
+});