@openwop/openwop-conformance 1.1.1 → 1.2.0

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

@@ -0,0 +1,100 @@
+/**
+ * RFC 0022 §B — `core.subWorkflow` `inputMapping` seeding (HVMAP-2).
+ * Normative reference: RFCS/0022-dispatch-input-output-mapping.md §B
+ *   + spec/v1/node-packs.md §"`core.subWorkflow` contract" (post-RFC-0022).
+ *
+ * Verifies that when a `core.subWorkflow` config carries `inputMapping`,
+ * the host seeds the child run's initial variable bag with
+ * `parentVariables[parentKey]` projections AFTER the child's
+ * `variables[].defaultValue` fold (so `inputMapping` overrides matching
+ * defaults). Verified end-to-end against the Postgres reference host on
+ * 2026-05-18 alongside the RFC's `Active` promotion.
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.subWorkflow.inputMapping: true`. Fixture-gated: requires
+ * `conformance-subworkflow-input-mapping` + the matching child fixture.
+ *
+ * @see RFCS/0022-dispatch-input-output-mapping.md §B
+ * @see spec/v1/node-packs.md §"`core.subWorkflow` contract"
+ */
+
+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-subworkflow-input-mapping';
+const CHILD = 'conformance-subworkflow-input-mapping-child';
+const SKIP = !isFixtureAdvertised(PARENT) || !isFixtureAdvertised(CHILD);
+
+interface RunEvent {
+  readonly type: string;
+  readonly nodeId?: string;
+  readonly payload?: { outputs?: { childRunId?: string } } & Record<string, unknown>;
+}
+
+interface RunSnapshot {
+  readonly status: string;
+  readonly variables?: Record<string, unknown>;
+}
+
+describe.skipIf(SKIP)('subworkflow-input-mapping: parent → child variable seeding (RFC 0022 §B)', () => {
+  it('HVMAP-2: inputMapping seeds child variables, overrides defaultValue, child reads parent projection', async () => {
+    // Parent fixture declares currentPrdId='prd-1' as its defaultValue.
+    // The parent's `core.subWorkflow` node carries
+    // `inputMapping: { receivedPrdId: 'currentPrdId' }`. Child fixture
+    // declares `receivedPrdId.defaultValue='baked-in'` — the mapping
+    // MUST override that default per RFC 0022 §B.
+    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 §B',
+      'parent run MUST reach terminal `completed` once the child finishes',
+    )).toBe('completed');
+
+    // Locate the child run via the parent's event log.
+    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 subwfCompleted = events.find(
+      (e) => e.type === 'node.completed' && e.nodeId === 'subwf-call',
+    );
+    expect(subwfCompleted, driver.describe(
+      'spec/v1/node-packs.md §"`core.subWorkflow` contract"',
+      'parent event log MUST contain `node.completed` for the subwf-call node',
+    )).toBeDefined();
+    const childRunId = subwfCompleted?.payload?.outputs?.childRunId;
+    expect(typeof childRunId).toBe('string');
+
+    // Inspect the child run's final variables — receivedPrdId MUST be
+    // the parent's projection ("prd-1"), NOT the child's defaultValue
+    // ("baked-in").
+    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(
+      'spec/v1/node-packs.md §"`core.subWorkflow` contract"',
+      'child run MUST reach terminal `completed`',
+    )).toBe('completed');
+    const childVars = childSnapshot.variables ?? {};
+    expect(childVars.receivedPrdId, driver.describe(
+      'RFCS/0022-dispatch-input-output-mapping.md §B',
+      'child `receivedPrdId` MUST be parent\'s `currentPrdId` projection ("prd-1"), overriding the child\'s defaultValue "baked-in"',
+    )).toBe('prd-1');
+  });
+
+  it.todo(
+    'HVMAP-2-unset: parent.currentPrdId unset; child receivedPrdId MUST surface as `undefined` (NOT omitted, NOT `null`). Requires a second parent fixture variant that omits currentPrdId\'s defaultValue.',
+  );
+
+  it.todo(
+    'HVMAP-2-no-midrun-propagation: child mid-run; parent updates currentPrdId; child receivedPrdId MUST remain at seeded value (one-shot fold per §B normative bullet). Requires a multi-step child that suspends + a parent path that mutates.',
+  );
+
+  it.todo(
+    'HVMAP-2-refusal: host advertises core.subWorkflow surface but NOT capabilities.subWorkflow.inputMapping: true; workflow with non-empty inputMapping MUST fail registration with validation_error + details.requiredCapability === "subWorkflow.inputMapping". Requires a host-capability-toggle hook in the conformance harness.',
+  );
+});

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

@@ -0,0 +1,65 @@
+/**
+ * table-cross-tenant-isolation — RFC 0016 §B point 1.
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that rows inserted
+ * under tenant A MUST NOT appear in queries under tenant B against the
+ * same table+filter.
+ *
+ * @see RFCS/0016-host-table-storage-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>)["tableStorage"] : 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: 'table', op, args });
+}
+
+describe('table-cross-tenant-isolation: advertisement shape (RFC 0016)', () => {
+  it('capabilities.tableStorage 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 §tableStorage',
+        'capabilities.tableStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('table-cross-tenant-isolation: behavioral (RFC 0016 §B point 1)', () => {
+  it('insert under tenant A → query under tenant B returns 0 rows', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const table = `xtenant_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+
+    const insertRes = await call('tenant-a', 'insert', {
+      table,
+      row: { id: 'r1', body: 'from-A' },
+    });
+    if (insertRes.status === 404) return; // seam not exposed
+    expect(insertRes.status, 'insert MUST succeed').toBe(200);
+
+    const queryRes = await call('tenant-b', 'query', { table, filter: {} });
+    expect(queryRes.status).toBe(200);
+    const body = queryRes.json as { rows?: unknown[] };
+    expect(
+      Array.isArray(body.rows) ? body.rows.length : -1,
+      driver.describe('RFC 0016 §B point 1', 'tenant B MUST see 0 rows in tenant A table'),
+    ).toBe(0);
+  });
+});

package/src/scenarios/table-cursor-pagination.test.ts

@@ -0,0 +1,47 @@
+/**
+ * table-cursor-pagination — RFC 0016 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0016 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.tableStorage` 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: query MUST support filter + cursor pagination.
+ *
+ * @see RFCS/0016-*.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>)["tableStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('table-cursor-pagination: advertisement shape (RFC 0016)', () => {
+  it('capabilities.tableStorage 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 §tableStorage',
+        'capabilities.tableStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('table-cursor-pagination: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("first page returns N rows + nextCursor; second page resumes; final page returns nextCursor=null");
+});

package/src/scenarios/table-schema-enforcement.test.ts

@@ -0,0 +1,47 @@
+/**
+ * table-schema-enforcement — RFC 0016 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0016 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.tableStorage` 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: Subsequent rows MUST conform to the schema established on first insert.
+ *
+ * @see RFCS/0016-*.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>)["tableStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('table-schema-enforcement: advertisement shape (RFC 0016)', () => {
+  it('capabilities.tableStorage 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 §tableStorage',
+        'capabilities.tableStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('table-schema-enforcement: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("first insert declares schema; subsequent insert with wrong column type is rejected");
+});

package/src/scenarios/vector-knn-roundtrip.test.ts

@@ -0,0 +1,48 @@
+/**
+ * vector-knn-roundtrip — RFC 0018 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0018 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.vectorStore` 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: upsert then query returns the same vectors in top-k order.
+ *
+ * @see RFCS/0018-*.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>)["vectorStore"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('vector-knn-roundtrip: advertisement shape (RFC 0018)', () => {
+  it('capabilities.vectorStore 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 §vectorStore',
+        'capabilities.vectorStore.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('vector-knn-roundtrip: behavioral assertions (placeholders — need host test seam)', () => {
+  it.todo("upsert 10 vectors → query with one of them returns it as top-1");
+  it.todo("topK respects the configured limit");
+});

package/src/scenarios/webhook-receiver-adversarial.test.ts

@@ -0,0 +1,210 @@
+/**
+ * CF-5 close-out — receiver-side rejection contract per
+ * `spec/v1/webhooks.md` §"Signature recipe" + §"Replay-attack
+ * resistance". The companion to `webhook-signed-delivery.test.ts`
+ * (which verifies the FORWARD direction: host signs correctly) —
+ * this scenario verifies the REVERSE direction: a properly-
+ * implemented receiver MUST reject five named adversarial inputs.
+ *
+ * The reference receiver implementation lives at
+ * `conformance/src/lib/webhook-receiver.ts`. The SDK ships an
+ * identical-behavior `verifyWebhookSignature` helper across all
+ * three reference SDKs (SDK-3 close-out).
+ *
+ * Five adversarial cases:
+ *
+ *   1. Tampered body — host's HMAC is valid for body B; adversary
+ *      delivers body B'. Receiver MUST reject with
+ *      `signature_mismatch`.
+ *   2. Tampered HMAC — body is valid; adversary flips a byte of the
+ *      v1=<hex> signature. Receiver MUST reject with
+ *      `signature_mismatch`.
+ *   3. Stale timestamp — body + HMAC are valid but timestamp is
+ *      older than the default 5-minute window. Receiver MUST reject
+ *      with `timestamp_expired`.
+ *   4. Replayed signature — adversary resends a previously-accepted
+ *      delivery within the window. Receiver MUST reject with
+ *      `duplicate_signature`.
+ *   5. Wrong algorithm — host sends `algorithm: v2` (a future
+ *      version a v1-only receiver doesn't recognize). Receiver MUST
+ *      reject with `wrong_algorithm`.
+ *
+ * This scenario is purely receiver-side; it does NOT touch the host
+ * under test. It runs unconditionally (no capability gating).
+ *
+ * @see spec/v1/webhooks.md
+ * @see conformance/src/lib/webhook-receiver.ts
+ * @see sdk/typescript/src/webhook-helpers.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createReceiverState,
+  signPayload,
+  verifyWebhookDelivery,
+} from '../lib/webhook-receiver.js';
+
+describe('webhook-receiver-adversarial: receiver rejects five canonical attacks', () => {
+  const secret = 'test-secret-do-not-use-in-prod';
+  const body = JSON.stringify({ runId: 'r-conformance', type: 'run.completed' });
+  const nowSec = 1_715_775_600;
+  const ts = nowSec;
+
+  it('positive control: receiver accepts a freshly-signed valid delivery', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(
+      result.accepted,
+      'webhooks.md §"Signature recipe": valid signature + fresh timestamp + correct algorithm MUST be accepted',
+    ).toBe(true);
+  });
+
+  it('case 1: tampered body → signature_mismatch', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const tamperedBody = JSON.stringify({ runId: 'r-conformance', type: 'run.failed' });
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      tamperedBody,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Signature recipe": tampered body MUST be rejected with signature_mismatch',
+      ).toBe('signature_mismatch');
+    }
+  });
+
+  it('case 2: tampered HMAC → signature_mismatch', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    // Flip one hex character of the v1=<hex> signature.
+    const flipIndex = 5;
+    const orig = signatureHeader[flipIndex]!;
+    const replacement = orig === '0' ? '1' : '0';
+    const tampered = signatureHeader.slice(0, flipIndex) + replacement + signatureHeader.slice(flipIndex + 1);
+    const result = verifyWebhookDelivery(
+      secret,
+      tampered,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(result.reason).toBe('signature_mismatch');
+    }
+  });
+
+  it('case 3: stale timestamp → timestamp_expired', () => {
+    const state = createReceiverState();
+    const staleTs = nowSec - 10_000; // way past the 5-minute window
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, staleTs, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Replay-attack resistance": timestamp older than freshness window MUST be rejected with timestamp_expired',
+      ).toBe('timestamp_expired');
+    }
+  });
+
+  it('case 4: replayed signature → duplicate_signature', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    // First delivery accepted.
+    const first = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(first.accepted).toBe(true);
+    // Replay — same signature, same body, same timestamp, still
+    // within the window.
+    const replay = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(replay.accepted).toBe(false);
+    if (!replay.accepted) {
+      expect(
+        replay.reason,
+        'webhooks.md §"Replay-attack resistance": replay of an already-accepted signature MUST be rejected with duplicate_signature',
+      ).toBe('duplicate_signature');
+    }
+  });
+
+  it('case 5: wrong algorithm → wrong_algorithm', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      'v2',
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Signature algorithm versioning": algorithm other than v1 MUST be rejected with wrong_algorithm by a v1-only receiver',
+      ).toBe('wrong_algorithm');
+    }
+  });
+
+  it('case 6: malformed signature header → malformed_signature_header', () => {
+    const state = createReceiverState();
+    const { timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      'not-a-canonical-header',
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(result.reason).toBe('malformed_signature_header');
+    }
+  });
+});