@openwop/openwop-conformance 1.1.0 → 1.2.0

package/src/scenarios/artifact-auth.test.ts

@@ -0,0 +1,58 @@
+/**
+ * CF-4 close-out (partial) — explicit scope-failure coverage on
+ * `GET /v1/runs/{runId}/artifacts/{artifactId}` per
+ * `plans/openwop-protocol-gap-closure-plan.md` Workstream 2.
+ *
+ * The existing `route-coverage.test.ts` covers 404 / 403 envelope
+ * shape on an unknown artifact. This scenario adds the 401 path —
+ * an unauthenticated request to the artifact endpoint MUST return
+ * 401 with the canonical `unauthenticated` envelope, NEVER 200 (no
+ * cross-tenant leak via missing-auth coercion) and NEVER a redirect.
+ *
+ * Positive-path coverage (reading an artifact a workflow actually
+ * produced) is host-pending — no reference host currently implements
+ * `getArtifact` end-to-end; the path lights up when the first host
+ * advertises an artifact-producing fixture.
+ *
+ * @see api/openapi.yaml §`getArtifact`
+ * @see spec/v1/rest-endpoints.md §"GET /v1/runs/{runId}/artifacts/{artifactId}"
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { driver } from '../lib/driver.js';
+import { loadEnv } from '../lib/env.js';
+
+describe('artifact-auth: unauthenticated artifact requests are rejected', () => {
+  it('GET /v1/runs/{runId}/artifacts/{artifactId} without Authorization returns 401', async () => {
+    const env = loadEnv();
+    // Use node:fetch directly with NO Authorization header — bypass the
+    // driver's auto-auth so we exercise the unauthenticated code path.
+    const res = await fetch(
+      `${env.baseUrl}/v1/runs/openwop-conformance-noauth-run/artifacts/openwop-conformance-noauth-artifact`,
+    );
+    expect(res.status, driver.describe(
+      'rest-endpoints.md GET /v1/runs/{runId}/artifacts/{artifactId}',
+      'artifact endpoint MUST reject unauthenticated requests with 401 (never 200, never redirect)',
+    )).toBe(401);
+    expect(res.status, 'redirect MUST NOT be used to handle missing auth on artifact endpoint').not.toBe(301);
+    expect(res.status, 'redirect MUST NOT be used to handle missing auth on artifact endpoint').not.toBe(302);
+    expect(res.status).not.toBe(200);
+
+    // Canonical error envelope: error: 'unauthenticated', message: string.
+    let body: { error?: string; message?: string };
+    try {
+      body = (await res.json()) as typeof body;
+    } catch {
+      // Some hosts return a bare 401 with no body — acceptable. Skip the
+      // envelope-shape assertion in that case.
+      return;
+    }
+    if (typeof body.error === 'string') {
+      expect(body.error, driver.describe(
+        'auth.md §"Error envelope"',
+        '401 envelope SHOULD carry `error: "unauthenticated"` for missing-auth on artifact endpoint',
+      )).toBe('unauthenticated');
+    }
+  });
+});

package/src/scenarios/blob-cross-tenant-isolation.test.ts

@@ -0,0 +1,66 @@
+/**
+ * blob-cross-tenant-isolation — RFC 0019 §B point 1.
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that blobs put
+ * under tenant A MUST NOT be retrievable under tenant B at the same key.
+ *
+ * @see RFCS/0019-host-blob-cache-capability.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["blobStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function call(tenantId: string, op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId, surface: 'blob', op, args });
+}
+
+describe('blob-cross-tenant-isolation: advertisement shape (RFC 0019)', () => {
+  it('capabilities.blobStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §blobStorage',
+        'capabilities.blobStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('blob-cross-tenant-isolation: behavioral (RFC 0019 §B point 1)', () => {
+  it('put under tenant A → get under tenant B with same key returns found:false', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const key = `xtenant-blob-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+
+    const putRes = await call('tenant-a', 'put', {
+      bucket: 'default',
+      key,
+      contentBase64: Buffer.from('from-A').toString('base64'),
+      contentType: 'text/plain',
+    });
+    if (putRes.status === 404) return;
+    expect(putRes.status, 'put MUST succeed').toBe(200);
+
+    const getRes = await call('tenant-b', 'get', { bucket: 'default', key });
+    expect(getRes.status).toBe(200);
+    const body = getRes.json as { found?: boolean };
+    expect(
+      body.found,
+      driver.describe('RFC 0019 §B point 1', 'tenant B MUST NOT retrieve tenant A blob at same key'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/blob-presign-expiry.test.ts

@@ -0,0 +1,66 @@
+/**
+ * blob-presign-expiry — RFC 0019 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0019 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.blobStorage` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: Presigned URLs MUST expire at the advertised TTL.
+ *
+ * @see RFCS/0019-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["blobStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('blob-presign-expiry: advertisement shape (RFC 0019)', () => {
+  it('capabilities.blobStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §blobStorage',
+        'capabilities.blobStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('presignSupported is a boolean when set', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const subParts = ["presignSupported"];
+    let sub: unknown = cap;
+    for (const p of subParts) {
+      if (sub && typeof sub === 'object') sub = (sub as Record<string, unknown>)[p];
+      else { sub = undefined; break; }
+    }
+    if (sub === undefined) return; // optional sub-field
+    expect(
+      typeof sub,
+      driver.describe(
+        'RFC 0019 §A',
+        'blobStorage.presignSupported MUST be boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('blob-presign-expiry: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("presign with ttl=60 → URL works during the window, returns 403 after");
+});

package/src/scenarios/blob-roundtrip.test.ts

@@ -0,0 +1,48 @@
+/**
+ * blob-roundtrip — RFC 0019 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0019 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.blobStorage` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: put then get returns the same content + size + etag.
+ *
+ * @see RFCS/0019-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["blobStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('blob-roundtrip: advertisement shape (RFC 0019)', () => {
+  it('capabilities.blobStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §blobStorage',
+        'capabilities.blobStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('blob-roundtrip: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("put binary content → get returns identical bytes");
+  it.todo("get of non-existent key returns found:false");
+});

package/src/scenarios/cache-cross-tenant-isolation.test.ts

@@ -0,0 +1,61 @@
+/**
+ * cache-cross-tenant-isolation — RFC 0019 §B point 2.
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that cache entries
+ * put under tenant A MUST NOT hit on get under tenant B at the same key.
+ *
+ * @see RFCS/0019-host-blob-cache-capability.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["cache"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function call(tenantId: string, op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId, surface: 'cache', op, args });
+}
+
+describe('cache-cross-tenant-isolation: advertisement shape (RFC 0019)', () => {
+  it('capabilities.cache is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §cache',
+        'capabilities.cache.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('cache-cross-tenant-isolation: behavioral (RFC 0019 §B point 2)', () => {
+  it('put under tenant A → get under tenant B returns miss', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const key = `xtenant-cache-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+
+    const putRes = await call('tenant-a', 'put', { key, value: 'from-A', ttlSeconds: 60 });
+    if (putRes.status === 404) return;
+    expect(putRes.status, 'put MUST succeed').toBe(200);
+
+    const getRes = await call('tenant-b', 'get', { key });
+    expect(getRes.status).toBe(200);
+    const body = getRes.json as { hit?: boolean };
+    expect(
+      body.hit,
+      driver.describe('RFC 0019 §B point 2', 'tenant B MUST NOT hit tenant A cache entry at same key'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/cache-ttl-expiry.test.ts

@@ -0,0 +1,47 @@
+/**
+ * cache-ttl-expiry — RFC 0019 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0019 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.cache` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: Cache TTL honored with at most 1-second drift.
+ *
+ * @see RFCS/0019-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["cache"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('cache-ttl-expiry: advertisement shape (RFC 0019)', () => {
+  it('capabilities.cache is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §cache',
+        'capabilities.cache.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('cache-ttl-expiry: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("put with ttl=2 → hit within window; miss after");
+});

package/src/scenarios/dispatch-cross-worker-handoff.test.ts

@@ -0,0 +1,98 @@
+/**
+ * RFC 0022 §A + §D — `core.dispatch` sequential cross-worker handoff (HVMAP-1c).
+ * Normative reference: RFCS/0022-dispatch-input-output-mapping.md §A + §D
+ *
+ * Verifies that under `fanOutPolicy: 'sequential'` (v1.x default), the
+ * output mapping of child N MUST be visible to child N+1's input mapping
+ * within the same dispatch loop — they share the parent variable bag.
+ * The scenario routes child-a's `output` variable through the parent's
+ * `sharedVar` slot via per-worker mappings, then child-b reads it back
+ * as `inputs.input`. Verified end-to-end against the Postgres reference
+ * host on 2026-05-18 alongside the supervisor-mock extension (RFC 0022
+ * §"Unresolved questions" #6) that lets fixtures drive multi-worker
+ * `OrchestratorDecision` sequences.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.dispatchMapping: true`. Fixture-gated: requires
+ * `conformance-dispatch-cross-worker-handoff` + the two child fixtures.
+ *
+ * @see RFCS/0022-dispatch-input-output-mapping.md §A + §D
+ * @see schemas/dispatch-config.schema.json #/properties/perWorker*
+ * @see examples/hosts/postgres/src/server.ts (core.dispatch executor)
+ */
+
+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 PARENT = 'conformance-dispatch-cross-worker-handoff';
+const CHILD_A = 'conformance-dispatch-cross-worker-handoff-child-a';
+const CHILD_B = 'conformance-dispatch-cross-worker-handoff-child-b';
+const SKIP =
+  !isFixtureAdvertised(PARENT) ||
+  !isFixtureAdvertised(CHILD_A) ||
+  !isFixtureAdvertised(CHILD_B);
+
+interface RunEvent {
+  readonly type: string;
+  readonly nodeId?: string;
+  readonly payload?: { childRunId?: string; childWorkflowId?: string } & Record<string, unknown>;
+}
+
+interface RunSnapshot {
+  readonly status: string;
+  readonly inputs?: Record<string, unknown>;
+  readonly variables?: Record<string, unknown>;
+}
+
+describe.skipIf(SKIP)('dispatch-cross-worker-handoff: sequential child→parent→child variable flow (RFC 0022 §A + §D)', () => {
+  it('HVMAP-1c: child-a writes via perWorkerOutputMappings; child-b reads via perWorkerInputMappings; shared parent bag is the handoff channel', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: PARENT });
+    expect(create.status).toBe(201);
+    const parentRunId = (create.json as { runId: string }).runId;
+
+    const parentTerminal = (await pollUntilTerminal(parentRunId)) as RunSnapshot;
+    expect(parentTerminal.status, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §D',
+      'parent run MUST reach terminal `completed` once both children finish sequentially',
+    )).toBe('completed');
+
+    // Parent's sharedVar MUST be 'hello' — set by child-a's outputMapping.
+    const parentVars = parentTerminal.variables ?? {};
+    expect(parentVars.sharedVar, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A',
+      'parent `sharedVar` MUST be child-a\'s `output` projection ("hello") via perWorkerOutputMappings',
+    )).toBe('hello');
+
+    // Locate child-b via the parent's `node.dispatched` events.
+    const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(parentRunId)}/events`);
+    expect(eventsRes.status).toBe(200);
+    const events = ((eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? []);
+    const dispatchedB = events.find(
+      (e) => e.type === 'node.dispatched' && e.payload?.childWorkflowId === CHILD_B,
+    );
+    expect(dispatchedB, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §D',
+      'parent event log MUST contain a `node.dispatched` event for child-b after child-a completes (sequential fan-out)',
+    )).toBeDefined();
+    const childBRunId = dispatchedB?.payload?.childRunId;
+    expect(typeof childBRunId).toBe('string');
+
+    // Child-b's inputs MUST reflect child-a's output (via the shared
+    // parent variable bag's sharedVar).
+    const childBSnapshotRes = await driver.get(`/v1/runs/${encodeURIComponent(childBRunId!)}`);
+    expect(childBSnapshotRes.status).toBe(200);
+    const childBSnapshot = childBSnapshotRes.json as RunSnapshot;
+    expect(childBSnapshot.status).toBe('completed');
+    const childBInputs = childBSnapshot.inputs ?? {};
+    expect(childBInputs.input, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A + §D',
+      'child-b `inputs.input` MUST be parent\'s `sharedVar` ("hello") — written by child-a, read by child-b via shared parent variable bag',
+    )).toBe('hello');
+  });
+
+  it.todo(
+    'HVMAP-1c-override: per-worker mapping overrides default mapping. dispatch.inputMapping={input:"defaultX"}; perWorkerInputMappings.child-b={input:"sharedVar"}; child-b MUST receive inputs.input from sharedVar, NOT defaultX. Requires a fixture variant carrying both default + per-worker mappings.',
+  );
+});

package/src/scenarios/dispatch-input-mapping.test.ts

@@ -0,0 +1,94 @@
+/**
+ * RFC 0022 §A — `core.dispatch` `inputMapping` projection (HVMAP-1a).
+ * Normative reference: RFCS/0022-dispatch-input-output-mapping.md §A
+ *
+ * Verifies that when a `core.dispatch` config carries `inputMapping`, the
+ * host builds child inputs by projecting parent variables before invoking
+ * each `nextWorkerIds[i]` child. Per §A: `childInputs[childKey] =
+ * parentVariables.get(parentKey)`. Verified end-to-end against the
+ * Postgres reference host on 2026-05-18 alongside the supervisor-mock
+ * extension that lets fixtures drive `OrchestratorDecision` sequences
+ * (RFC 0022 §"Unresolved questions" #6 — `mockDispatchPlan` config on
+ * `core.orchestrator.supervisor`).
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.dispatchMapping: true`. Fixture-gated: requires
+ * `conformance-dispatch-input-mapping` + the matching child fixture.
+ *
+ * @see RFCS/0022-dispatch-input-output-mapping.md §A
+ * @see schemas/dispatch-config.schema.json #/properties/inputMapping
+ * @see examples/hosts/postgres/src/server.ts (core.dispatch executor)
+ */
+
+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 PARENT = 'conformance-dispatch-input-mapping';
+const CHILD = 'conformance-dispatch-input-mapping-child';
+const SKIP = !isFixtureAdvertised(PARENT) || !isFixtureAdvertised(CHILD);
+
+interface RunEvent {
+  readonly type: string;
+  readonly nodeId?: string;
+  readonly payload?: { childRunId?: string; childWorkflowId?: string } & Record<string, unknown>;
+}
+
+interface RunSnapshot {
+  readonly status: string;
+  readonly inputs?: Record<string, unknown>;
+  readonly variables?: Record<string, unknown>;
+}
+
+describe.skipIf(SKIP)('dispatch-input-mapping: parent → child variable projection (RFC 0022 §A)', () => {
+  it('HVMAP-1a: inputMapping projects parent variables into child inputs', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: PARENT });
+    expect(create.status).toBe(201);
+    const parentRunId = (create.json as { runId: string }).runId;
+
+    const parentTerminal = (await pollUntilTerminal(parentRunId)) as RunSnapshot;
+    expect(parentTerminal.status, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A',
+      'parent run MUST reach terminal `completed` once the dispatch loop terminates',
+    )).toBe('completed');
+
+    // Locate the child run via the parent's `node.dispatched` event.
+    const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(parentRunId)}/events`);
+    expect(eventsRes.status).toBe(200);
+    const events = ((eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? []);
+    const dispatched = events.find(
+      (e) => e.type === 'node.dispatched' && e.payload?.childWorkflowId === CHILD,
+    );
+    expect(dispatched, driver.describe(
+      'RFCS/0007-dispatch.md §D',
+      'parent event log MUST contain a `node.dispatched` event naming the child workflow',
+    )).toBeDefined();
+    const childRunId = dispatched?.payload?.childRunId;
+    expect(typeof childRunId).toBe('string');
+
+    // The child's inputs_json (surfaced as `inputs` on GET /v1/runs)
+    // MUST contain the parent's `parentName` projected onto `childGreeting`
+    // per the dispatch config's inputMapping.
+    const childSnapshotRes = await driver.get(`/v1/runs/${encodeURIComponent(childRunId!)}`);
+    expect(childSnapshotRes.status).toBe(200);
+    const childSnapshot = childSnapshotRes.json as RunSnapshot;
+    expect(childSnapshot.status, driver.describe(
+      'RFCS/0007-dispatch.md',
+      'child run MUST reach terminal `completed`',
+    )).toBe('completed');
+    const childInputs = childSnapshot.inputs ?? {};
+    expect(childInputs.childGreeting, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A',
+      'child `inputs.childGreeting` MUST be parent\'s `parentName` projection ("Alice") per inputMapping',
+    )).toBe('Alice');
+  });
+
+  it.todo(
+    'HVMAP-1a-null: parent variable unset → child input surfaces as `undefined` (NOT omitted, NOT `null`) per §A normative bullet. Requires a fixture variant omitting parentName.defaultValue.',
+  );
+
+  it.todo(
+    'HVMAP-1a-refusal: host advertises capabilities.agents.dispatch: true but NOT capabilities.agents.dispatchMapping: true; workflow with non-empty inputMapping MUST fail registration with validation_error + details.requiredCapability === "agents.dispatchMapping". Requires a host-capability-toggle hook in the conformance harness.',
+  );
+});

package/src/scenarios/dispatch-output-mapping.test.ts

@@ -0,0 +1,65 @@
+/**
+ * RFC 0022 §A — `core.dispatch` `outputMapping` harvesting (HVMAP-1b).
+ * Normative reference: RFCS/0022-dispatch-input-output-mapping.md §A
+ *
+ * Verifies that when a `core.dispatch` config carries `outputMapping` and
+ * a child reaches terminal `completed`, the host projects child variables
+ * back into parent variables: `parentVariables.set(parentKey, childVariables[childKey])`.
+ * Failed / cancelled children MUST skip the mapping; the parent's variable
+ * stays at its pre-dispatch state for that child. Verified end-to-end
+ * against the Postgres reference host on 2026-05-18.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.dispatchMapping: true`. Fixture-gated: requires
+ * `conformance-dispatch-output-mapping` + the matching child fixture.
+ *
+ * @see RFCS/0022-dispatch-input-output-mapping.md §A
+ * @see schemas/dispatch-config.schema.json #/properties/outputMapping
+ * @see examples/hosts/postgres/src/server.ts (core.dispatch executor)
+ */
+
+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 PARENT = 'conformance-dispatch-output-mapping';
+const CHILD = 'conformance-dispatch-output-mapping-child';
+const SKIP = !isFixtureAdvertised(PARENT) || !isFixtureAdvertised(CHILD);
+
+interface RunSnapshot {
+  readonly status: string;
+  readonly variables?: Record<string, unknown>;
+}
+
+describe.skipIf(SKIP)('dispatch-output-mapping: child → parent variable harvest (RFC 0022 §A)', () => {
+  it('HVMAP-1b: outputMapping harvests child variables into parent variables on terminal completed', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: PARENT });
+    expect(create.status).toBe(201);
+    const parentRunId = (create.json as { runId: string }).runId;
+
+    const parentTerminal = (await pollUntilTerminal(parentRunId)) as RunSnapshot;
+    expect(parentTerminal.status, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A',
+      'parent run MUST reach terminal `completed` once the dispatch loop terminates',
+    )).toBe('completed');
+
+    // Parent's `parentResult` MUST equal child's `childOutcome` ("done")
+    // per the dispatch config's outputMapping = { parentResult: 'childOutcome' }.
+    // Child declares childOutcome.defaultValue='done' so the value is
+    // present in the child's variables_json at terminal time.
+    const parentVars = parentTerminal.variables ?? {};
+    expect(parentVars.parentResult, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §A',
+      'parent `parentResult` MUST be child\'s `childOutcome` projection ("done") per outputMapping',
+    )).toBe('done');
+  });
+
+  it.todo(
+    'HVMAP-1b-failed: child terminates with `failed` status; outputMapping MUST be skipped; parent variables stay at pre-dispatch state for that child. Requires a child fixture that fails deterministically.',
+  );
+
+  it.todo(
+    'HVMAP-1b-cancelled: child terminates with `cancelled` status; outputMapping MUST be skipped; parent variables stay at pre-dispatch state for that child. Requires a child fixture that supports external cancellation.',
+  );
+});