@openwop/openwop-conformance 1.0.0 → 1.1.1

package/src/scenarios/memory-compaction-event-emitted.test.ts

@@ -0,0 +1,121 @@
+/**
+ * RFC 0012 §B — `memory.compacted` event emission shape.
+ *
+ * Verifies that hosts advertising
+ * `capabilities.memory.compaction.supported: true` emit a canonical
+ * `memory.compacted` event payload per `run-event-payloads.schema.json`
+ * §`memoryCompacted` whenever a compaction run completes.
+ *
+ * Required fields per the schema:
+ *   - `memoryRef` (string, non-empty)
+ *   - `outputId` (string, non-empty)
+ *   - `sourceCount` (integer ≥ 1)
+ *   - `trigger` (closed enum: `host-managed | client-requested | both`)
+ *   - `byteSize` (integer ≥ 0)
+ *
+ * Optional:
+ *   - `sourceIds` (array of non-empty strings; exhaustive within the
+ *     array — no "and N more" semantics — when present)
+ *
+ * Gating identical to `memory-compaction-sr1-carry-forward.test.ts`:
+ * capability advertisement + test seam reachable.
+ *
+ * @see RFCS/0012-memory-compaction-profile.md §B
+ * @see schemas/run-event-payloads.schema.json §memoryCompacted
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-event_longTerm';
+
+interface MemoryCaps {
+  compaction?: { supported?: boolean };
+}
+
+async function isCompactionAdvertised(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  return memory?.compaction?.supported === true;
+}
+
+async function isTestSeamReachable(): Promise<boolean> {
+  const r = await driver.post('/v1/test/memory/compact', {});
+  return r.status !== 404;
+}
+
+describe('memory-compaction-event-emitted: canonical memory.compacted payload shape', () => {
+  it('compaction run returns a canonical memoryCompacted payload', async () => {
+    if (!(await isCompactionAdvertised())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-event] capabilities.memory.compaction.supported not advertised; skipping');
+      return;
+    }
+    if (!(await isTestSeamReachable())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-event] test seam unreachable; skipping');
+      return;
+    }
+
+    const seed = await driver.post('/v1/test/memory/seed', {
+      memoryRef: MEMORY_REF,
+      entries: [
+        { id: `event-src-${Date.now()}-a`, content: 'First memory entry.' },
+        { id: `event-src-${Date.now()}-b`, content: 'Second memory entry.' },
+        { id: `event-src-${Date.now()}-c`, content: 'Third memory entry.' },
+      ],
+    });
+    expect(seed.status).toBe(201);
+
+    const compactRes = await driver.post('/v1/test/memory/compact', {
+      memoryRef: MEMORY_REF,
+    });
+    expect(compactRes.status).toBe(200);
+
+    const event = compactRes.json as {
+      type?: string;
+      payload?: Record<string, unknown>;
+    };
+
+    expect(event.type, driver.describe(
+      'observability.md §"Canonical run lifecycle event names"',
+      'event MUST be type=memory.compacted',
+    )).toBe('memory.compacted');
+
+    const payload = event.payload ?? {};
+
+    expect(typeof payload.memoryRef, driver.describe(
+      'RFC 0012 §B / run-event-payloads.schema.json §memoryCompacted',
+      'memoryRef MUST be a non-empty string',
+    )).toBe('string');
+    expect((payload.memoryRef as string).length).toBeGreaterThan(0);
+
+    expect(typeof payload.outputId, driver.describe(
+      'RFC 0012 §B',
+      'outputId MUST be a string identifying the distilled entry',
+    )).toBe('string');
+    expect((payload.outputId as string).length).toBeGreaterThan(0);
+
+    expect(Number.isInteger(payload.sourceCount), driver.describe(
+      'RFC 0012 §B',
+      'sourceCount MUST be an integer',
+    )).toBe(true);
+    expect(payload.sourceCount as number).toBeGreaterThanOrEqual(1);
+
+    expect(['host-managed', 'client-requested', 'both']).toContain(payload.trigger);
+
+    expect(Number.isInteger(payload.byteSize), driver.describe(
+      'RFC 0012 §B',
+      'byteSize MUST be an integer',
+    )).toBe(true);
+    expect(payload.byteSize as number).toBeGreaterThanOrEqual(0);
+
+    if (payload.sourceIds !== undefined) {
+      expect(Array.isArray(payload.sourceIds)).toBe(true);
+      for (const id of payload.sourceIds as unknown[]) {
+        expect(typeof id, 'sourceIds entries MUST be strings').toBe('string');
+        expect((id as string).length).toBeGreaterThan(0);
+      }
+    }
+  });
+});

package/src/scenarios/memory-compaction-provenance-tag.test.ts

@@ -0,0 +1,116 @@
+/**
+ * RFC 0012 §C — `compacted-from:<id>` provenance tag convention.
+ *
+ * The distilled entry SHOULD (not MUST) carry a tag of the form
+ * `compacted-from:<compactionRunId>` where `<compactionRunId>` is a
+ * host-issued opaque identifier. This lets `MemoryAdapter.list`
+ * consumers detect compacted entries without needing access to the
+ * `memory.compacted` event stream.
+ *
+ * SOFT ASSERTION: log-and-warn if absent, fail only if a present tag
+ * is malformed. Hosts with structurally-constrained tag-spaces (legacy
+ * tag-prefix discipline, fixed-vocabulary tagging) MAY omit this —
+ * the `memory.compacted` event itself remains the canonical provenance
+ * signal.
+ *
+ * Gating identical to the other RFC 0012 scenarios.
+ *
+ * @see RFCS/0012-memory-compaction-profile.md §C
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-tag_longTerm';
+const COMPACTED_FROM_RE = /^compacted-from:[^\s:][^\s]*$/;
+
+interface MemoryCaps {
+  compaction?: { supported?: boolean };
+}
+
+interface MemoryListResponse {
+  entries?: Array<{ id?: string; tags?: string[] }>;
+}
+
+async function isCompactionAdvertised(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  return memory?.compaction?.supported === true;
+}
+
+async function isTestSeamReachable(): Promise<boolean> {
+  const r = await driver.post('/v1/test/memory/compact', {});
+  return r.status !== 404;
+}
+
+describe('memory-compaction-provenance-tag: compacted-from:<id> tag follows §C convention', () => {
+  it('compacted entry carries a well-formed compacted-from tag, OR omits it cleanly (no malformed tags)', async () => {
+    if (!(await isCompactionAdvertised())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-tag] capabilities.memory.compaction.supported not advertised; skipping');
+      return;
+    }
+    if (!(await isTestSeamReachable())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-tag] test seam unreachable; skipping');
+      return;
+    }
+
+    // Seed + compact.
+    const seedStamp = Date.now();
+    const seed = await driver.post('/v1/test/memory/seed', {
+      memoryRef: MEMORY_REF,
+      entries: [
+        { id: `tag-src-${seedStamp}-1`, content: 'Source content alpha.' },
+        { id: `tag-src-${seedStamp}-2`, content: 'Source content beta.' },
+      ],
+    });
+    expect(seed.status).toBe(201);
+
+    const compactRes = await driver.post('/v1/test/memory/compact', {
+      memoryRef: MEMORY_REF,
+    });
+    expect(compactRes.status).toBe(200);
+
+    const event = compactRes.json as { payload?: { outputId?: string } };
+    const outputId = event.payload?.outputId;
+    expect(typeof outputId).toBe('string');
+
+    // Resolve the entry via the wire MemoryAdapter list surface (no
+    // direct get-by-id wire endpoint; we filter list results).
+    // Hosts that don't expose memory:list on the wire skip — this is
+    // a `MemoryAdapter.list` surface check, which the canonical
+    // capabilities.memory.supported claim already covers.
+    const listRes = await driver.get(
+      `/v1/memory/${encodeURIComponent(MEMORY_REF)}?limit=50`,
+    );
+    if (listRes.status === 404) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-tag] host does not expose memory:list at /v1/memory/{ref}; skipping tag inspection (canonical provenance signal remains the memory.compacted event itself)');
+      return;
+    }
+    expect(listRes.status, 'memory:list MUST return 200 when reachable').toBe(200);
+
+    const body = (listRes.json as MemoryListResponse) ?? {};
+    const entries = body.entries ?? [];
+    const output = entries.find((e) => e.id === outputId);
+    if (!output) {
+      // eslint-disable-next-line no-console
+      console.warn(`[rfc0012-tag] outputId ${outputId} not visible via memory:list; cannot inspect tags`);
+      return;
+    }
+    const tags = output.tags ?? [];
+
+    // RFC 0012 §C: SHOULD-tag, soft assertion.
+    const provenance = tags.find((t) => t.startsWith('compacted-from:'));
+    if (provenance === undefined) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-tag] output entry has no compacted-from:<id> tag — RFC 0012 §C is SHOULD, not MUST; pass with warning');
+      return;
+    }
+    expect(provenance, driver.describe(
+      'RFC 0012 §C',
+      'compacted-from tag MUST match `compacted-from:<id>` shape (non-empty id, no whitespace) when present',
+    )).toMatch(COMPACTED_FROM_RE);
+  });
+});

package/src/scenarios/memory-compaction-sr1-carry-forward.test.ts

@@ -0,0 +1,127 @@
+/**
+ * RFC 0012 §D — SR-1 carry-forward through memory compaction.
+ *
+ * Verifies the load-bearing security claim of RFC 0012 (Memory
+ * Compaction Profile, `Active` 2026-05-13 — comment window closes
+ * 2026-05-20): when a host advertising
+ * `capabilities.memory.compaction.supported: true` produces a
+ * compacted `MemoryEntry`, the derived content MUST pass the
+ * same BYOK redaction harness as a fresh `put`. The fact that
+ * source entries were SR-1-compliant at original `put` time is
+ * NOT evidence to skip redaction on derived content — summarization
+ * models can introduce secret-shaped substrings (hallucinated
+ * tokens, format-leaks from in-context examples) not present in
+ * any source.
+ *
+ * Gating:
+ *   - `capabilities.memory.compaction.supported` MUST be `true`.
+ *   - Host MUST expose the test seam at `POST /v1/test/memory/{seed,
+ *     compact}` — gated on the host's `OPENWOP_TEST_TRIGGER_COMPACTION`
+ *     env var. Without it the scenario can't synchronously drive
+ *     compaction (RFC 0012 normates only `trigger: 'host-managed'`).
+ *     The seam itself is host-implementation-specific; the conformance
+ *     suite skips when the seam isn't reachable.
+ *
+ * @see RFCS/0012-memory-compaction-profile.md §D
+ * @see SECURITY/invariants.yaml `memory-compaction-sr-1-carry-forward`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-sr1_longTerm';
+
+interface MemoryCaps {
+  compaction?: { supported?: boolean };
+}
+
+async function isCompactionAdvertised(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  return memory?.compaction?.supported === true;
+}
+
+async function isTestSeamReachable(): Promise<boolean> {
+  // Probe the seam with an empty body — expects 400 if reachable
+  // (validation_error on missing memoryRef), 404 when disabled.
+  const r = await driver.post('/v1/test/memory/compact', {});
+  return r.status !== 404;
+}
+
+describe('memory-compaction-sr1-carry-forward: derived content passes the BYOK redaction harness', () => {
+  it('compacted MemoryEntry content MUST NOT carry source-side form-leak signatures', async () => {
+    if (!(await isCompactionAdvertised())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-sr1] capabilities.memory.compaction.supported not advertised; skipping');
+      return;
+    }
+    if (!(await isTestSeamReachable())) {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-sr1] test seam /v1/test/memory/compact unreachable; skipping (set host\'s OPENWOP_TEST_TRIGGER_COMPACTION=true)');
+      return;
+    }
+
+    // 1. Seed source entries containing:
+    //    - The canonical `[BYOK:...]` form-leak signature (placeholder
+    //      surfaces verbatim — should be caught by SR-1 carry-forward).
+    //    - A non-canonical `<REDACTED:...>` marker that the host's
+    //      redaction harness should re-canonicalize.
+    //    - Plain, non-sensitive prose.
+    const seed = await driver.post('/v1/test/memory/seed', {
+      memoryRef: MEMORY_REF,
+      entries: [
+        { id: `sr1-src-${Date.now()}-1`, content: 'User confirmed: [BYOK:hk_live_canary_42]' },
+        { id: `sr1-src-${Date.now()}-2`, content: 'Resolved <REDACTED:db-prod-creds> outage.' },
+        { id: `sr1-src-${Date.now()}-3`, content: 'Customer asked about pricing tiers.' },
+      ],
+    });
+    expect(seed.status, 'seed endpoint MUST return 201 when reachable').toBe(201);
+
+    // 2. Drive compaction synchronously.
+    const compactRes = await driver.post('/v1/test/memory/compact', {
+      memoryRef: MEMORY_REF,
+    });
+    expect(compactRes.status, 'compact MUST return 200 with ≥2 source entries').toBe(200);
+
+    const event = compactRes.json as {
+      type?: string;
+      payload?: { outputId?: string; memoryRef?: string };
+      // Out-of-band field from the test seam carrying the persisted
+      // entry bytes; the wire-level `memory.compacted` event does NOT
+      // carry content. Required for SR-1 verification — the canonical
+      // event payload is shape-only and would pass this scenario
+      // trivially without it.
+      outputContent?: string;
+    };
+    expect(event.type, 'event payload MUST be type=memory.compacted').toBe('memory.compacted');
+
+    if (typeof event.outputContent !== 'string') {
+      // eslint-disable-next-line no-console
+      console.warn('[rfc0012-sr1] test seam did not return outputContent; the wire-level memory.compacted shape does not surface content so without a host-side seam we cannot verify §D end-to-end. Skipping.');
+      return;
+    }
+
+    // The load-bearing assertion: the PERSISTED entry content (what
+    // future MemoryAdapter.get / list consumers would see) MUST NOT
+    // carry source-side form-leak signatures. A host that skips its
+    // BYOK redaction pass on derived content fails here.
+    expect(event.outputContent.includes('[BYOK:hk_live_canary_42]'), driver.describe(
+      'RFC 0012 §D',
+      'derived MemoryEntry.content MUST NOT carry source-side [BYOK:...] form-leak signatures (SR-1 carry-forward)',
+    )).toBe(false);
+    expect(event.outputContent.includes('<REDACTED:db-prod-creds>'), driver.describe(
+      'RFC 0012 §D',
+      'derived MemoryEntry.content MUST NOT echo non-canonical <REDACTED:...> markers from sources',
+    )).toBe(false);
+
+    // Positive: the canonical `[REDACTED:...]` placeholder MUST be
+    // present where SR-1 carry-forward re-substituted a source-side
+    // leak. Pinning this prevents a host from "passing" by simply
+    // stripping source content rather than redacting it (which would
+    // also lose audit signal).
+    expect(event.outputContent, driver.describe(
+      'RFC 0012 §D',
+      'derived MemoryEntry.content MUST carry canonical [REDACTED:...] placeholders where source-side leaks were re-substituted',
+    )).toMatch(/\[REDACTED:[^\]]+\]/);
+  });
+});

package/src/scenarios/metric-emission.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Track 11: metric-emission verification.
+ *
+ * Verifies that hosts claiming `capabilities.observability.metrics`
+ * emit the canonical `openwop.run.backlog`, `openwop.queue.depth`, and
+ * (after at least one completed run) `openwop.run.duration` metrics
+ * documented in `spec/v1/observability.md`.
+ *
+ * Operator contract (same as `otel-emission.test.ts`):
+ *   1. Start the conformance suite with `OPENWOP_OTEL_COLLECTOR=true`
+ *      and `OPENWOP_OTEL_COLLECTOR_PORT=<port>`.
+ *   2. Boot the host with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>`.
+ *
+ * Skip conditions:
+ *   - Collector disabled (`OPENWOP_OTEL_COLLECTOR` unset / false).
+ *   - Host doesn't advertise `capabilities.observability.metrics.supported`.
+ *
+ * @see spec/v1/observability.md §"Metrics"
+ */
+
+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 { getCollector } from '../lib/otel-collector.js';
+
+const FIXTURE = 'conformance-noop';
+
+interface MetricsCaps {
+  supported?: boolean;
+  names?: ReadonlyArray<string>;
+}
+
+async function metricsAdvertised(): Promise<MetricsCaps | null> {
+  try {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as {
+      capabilities?: { observability?: { metrics?: MetricsCaps } };
+    }).capabilities;
+    return caps?.observability?.metrics ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForMetric(name: string, timeoutMs = 5_000): Promise<boolean> {
+  const collector = getCollector();
+  if (!collector) return false;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (collector.metricByName(name)) return true;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+
+describe('metric-emission: canonical openwop.* metrics arrive at the collector', () => {
+  it('host emits openwop.run.backlog, openwop.queue.depth, and openwop.run.duration', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[metric-emission] collector not started; set OPENWOP_OTEL_COLLECTOR=true to run',
+      );
+      return;
+    }
+    const metricsCaps = await metricsAdvertised();
+    if (!metricsCaps?.supported) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[metric-emission] host does not advertise observability.metrics.supported; skipping',
+      );
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[metric-emission] ${FIXTURE} not advertised; skipping`);
+      return;
+    }
+
+    const collector = getCollector()!;
+    collector.reset();
+
+    // Drive at least one completed run so openwop.run.duration has a sample.
+    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: 10_000 });
+
+    // Wait for the host's metric-emit tick to land at the collector.
+    const sawBacklog = await waitForMetric('openwop.run.backlog', 5_000);
+    expect(sawBacklog, driver.describe(
+      'observability.md §"Metrics"',
+      'host claiming metrics MUST emit openwop.run.backlog',
+    )).toBe(true);
+
+    const sawQueueDepth = await waitForMetric('openwop.queue.depth', 5_000);
+    expect(sawQueueDepth, driver.describe(
+      'observability.md §"Metrics"',
+      'host claiming metrics MUST emit openwop.queue.depth',
+    )).toBe(true);
+
+    const sawDuration = await waitForMetric('openwop.run.duration', 5_000);
+    expect(sawDuration, driver.describe(
+      'observability.md §"Metrics"',
+      'host claiming metrics MUST emit openwop.run.duration after a completed run',
+    )).toBe(true);
+
+    // Shape spot-check: backlog gauge data point has a numeric value.
+    const backlog = collector.metricByName('openwop.run.backlog')!;
+    expect(backlog.kind).toBe('gauge');
+    expect(typeof backlog.dataPoint.value).toBe('number');
+  });
+});

package/src/scenarios/multi-region-idempotency.test.ts

@@ -2,18 +2,29 @@
  * Track 13: multi-region idempotency capability shape (idempotency.md v1.1).
  *
  * Verifies that hosts advertising the multi-region idempotency annex
- * surface a valid `capabilities.idempotency.crossRegion` value. The
- * end-to-end partition behavior cannot be exercised black-box; this
- * scenario validates the discovery-document shape so clients can rely
- * on the capability for routing decisions.
+ * surface a valid `capabilities.idempotency.crossRegion` value AND, when
+ * claiming `'best-effort'` or `'strict'`, expose the operator-tier
+ * metric names per `idempotency.md` §"Operator surface".
+ *
+ * The annex's partition-replay convergence rule cannot be exercised
+ * black-box (it requires multi-region host deployment under a real
+ * partition); the algorithm itself is verified in-process via the
+ * Postgres host's `multi-region-idempotency.test.ts` smoke against
+ * the canonical resolver. This scenario validates the discovery-
+ * document shape so clients can rely on the capability for routing
+ * decisions.
  *
  * @see spec/v1/idempotency.md §"Multi-region idempotency"
+ * @see examples/hosts/postgres/src/multi-region.ts (canonical resolver)
  */
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 
 const ALLOWED = new Set(['single-region', 'best-effort', 'strict']);
+const REQUIRED_METRICS_WHEN_MULTI_REGION = [
+  'openwop.idempotency.cross_region_conflicts_total',
+];
 
 interface IdempotencyCaps {
   supported?: boolean;
@@ -22,6 +33,10 @@ interface IdempotencyCaps {
   crossRegion?: string;
 }
 
+interface ObservabilityCaps {
+  metrics?: { names?: string[] };
+}
+
 describe('multi-region-idempotency: capability shape', () => {
   it('idempotency.crossRegion (when advertised) MUST be one of the closed enum', async () => {
     const disco = await driver.get('/.well-known/openwop');
@@ -49,4 +64,24 @@ describe('multi-region-idempotency: capability shape', () => {
       expect(idem.layer2RetentionSeconds).toBeGreaterThan(0);
     }
   });
+
+  it('multi-region hosts SHOULD expose the cross-region conflict counter per §"Operator surface"', async () => {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as { capabilities?: { idempotency?: IdempotencyCaps; observability?: ObservabilityCaps } })
+      .capabilities;
+    const crossRegion = caps?.idempotency?.crossRegion;
+
+    if (crossRegion !== 'best-effort' && crossRegion !== 'strict') {
+      // Single-region hosts have no conflicts to count — skip.
+      return;
+    }
+
+    const advertised = new Set(caps?.observability?.metrics?.names ?? []);
+    for (const name of REQUIRED_METRICS_WHEN_MULTI_REGION) {
+      expect(advertised.has(name), driver.describe(
+        'idempotency.md §"Operator surface"',
+        `multi-region hosts SHOULD advertise metric "${name}" so operators can monitor conflict frequency`,
+      )).toBe(true);
+    }
+  });
 });

package/src/scenarios/orchestratorConservativePath.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 5 — CP-1 conservative-path orchestrator suspend.
+ * Normative reference: RFCS/0006-orchestrator.md
  *
  * Verifies the CP-1 invariant: when a `core.orchestrator.supervisor`
  * would emit a decision with `confidence < escalationThreshold`, the

package/src/scenarios/orchestratorDispatch.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 5 — orchestrator → dispatch → next-worker round-trip.
+ * Normative reference: RFCS/0006-orchestrator.md
  *
  * Verifies that a workflow with `core.orchestrator.supervisor` →
  * `core.dispatch` topology emits the canonical event sequence:

package/src/scenarios/orchestratorTermination.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 5 — orchestrator terminate decision (CO-3).
+ * Normative reference: RFCS/0006-orchestrator.md
  *
  * Verifies that when an `core.orchestrator.supervisor` emits a decision
  * with `kind: 'terminate'`:

package/src/scenarios/otel-emission-grpc.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Track 11: OTel span emission over OTLP/gRPC.
+ *
+ * Verifies that hosts advertising `capabilities.observability.otel.exportProtocols`
+ * including `"grpc"` can emit `openwop.*` spans over OTLP/gRPC to the
+ * in-suite collector and that the gRPC framing path captures the same
+ * `openwop.run` + `openwop.node.*` shape as the HTTP-JSON path.
+ *
+ * The gRPC collector is the parallel HTTP/2 server inside
+ * `OtelCollector` (started via `startGrpc()` in setup.ts when the
+ * `OPENWOP_OTEL_COLLECTOR=true` flag is set). The host points its
+ * exporter at the printed `:<grpcPort>` (h2c) with
+ * `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`. Spans captured over gRPC land
+ * in the same store as HTTP — `getCollector().spans()` returns the
+ * union.
+ *
+ * Skip conditions:
+ *   - Collector disabled (`OPENWOP_OTEL_COLLECTOR` unset / false).
+ *   - Host does not advertise `capabilities.observability.otel.exportProtocols`
+ *     including `"grpc"` (presumed not configured for gRPC emission).
+ *   - Required fixture (`conformance-noop`) not advertised.
+ *
+ * @see spec/v1/observability.md §"Export protocols"
+ * @see conformance/src/lib/otel-collector.ts §_handleGrpcStream
+ * @see conformance/src/lib/grpc-framing.ts
+ */
+
+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 { getCollector, waitForRunSpans } from '../lib/otel-collector.js';
+
+const FIXTURE = 'conformance-noop';
+
+async function advertisesGrpcExport(): Promise<boolean> {
+  try {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as {
+      capabilities?: {
+        observability?: { otel?: { exportProtocols?: unknown } };
+      };
+    }).capabilities;
+    const protocols = caps?.observability?.otel?.exportProtocols;
+    return Array.isArray(protocols) && protocols.includes('grpc');
+  } catch {
+    return false;
+  }
+}
+
+describe('otel-emission-grpc: OTLP/gRPC export path', () => {
+  it('host emits openwop.run spans over OTLP/gRPC; collector captures them via the shared store', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn('[otel-emission-grpc] collector not started; set OPENWOP_OTEL_COLLECTOR=true to run');
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[otel-emission-grpc] fixture ${FIXTURE} not advertised; skipping`);
+      return;
+    }
+    if (!(await advertisesGrpcExport())) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[otel-emission-grpc] host does not advertise capabilities.observability.otel.exportProtocols including "grpc"; skipping. ' +
+          'Hosts MAY opt into gRPC export by emitting OTLP via the OTLP/gRPC transport and adding `"grpc"` to the array.',
+      );
+      return;
+    }
+
+    const collector = getCollector()!;
+    collector.reset();
+
+    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: 15_000 });
+
+    // gRPC and HTTP-JSON spans both land in `_spans`, so the existing
+    // span-query helpers work transparently. If the host emits over
+    // both transports, we capture both; the assertion only requires
+    // at least one openwop.run span correlated by runId.
+    const runSpans = await waitForRunSpans(runId, { timeoutMs: 5_000, minCount: 1 });
+
+    expect(runSpans.length, driver.describe(
+      'observability.md §"Export protocols" + RFC 0008/0009 Track 11',
+      'host advertising exportProtocols ∋ "grpc" MUST emit openwop.* spans over OTLP/gRPC',
+    )).toBeGreaterThan(0);
+
+    const runSpan = runSpans.find((s) => s.name === 'openwop.run');
+    expect(runSpan?.attributes.get('openwop.run_id'), driver.describe(
+      'observability.md §"Run-level attributes"',
+      'openwop.run span MUST carry openwop.run_id attribute',
+    )).toBe(runId);
+  });
+});