@openwop/openwop-conformance 1.123.0 → 1.124.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.123.0",
+  "version": "1.124.0",
   "description": "Production-ready black-box conformance suite for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",

package/schemas/CORPUS-STAMP.json

@@ -1,5 +1,5 @@
 {
   "_comment": "Provenance of this vendored schemas/ copy. See conformance/README.md \u00a7\"Resolving the contract\". Compare against the stamp in your installed @openwop/openwop-conformance to detect a stale hand-copied contract.",
-  "suiteVersion": "1.123.0",
-  "corpusCommit": "9eb52572cde5f5406ad6ed21a62bb6932cb6bae9"
+  "suiteVersion": "1.124.0",
+  "corpusCommit": "7dffa37f3864f170141130aa0360765ba89b2e7e"
 }

package/src/lib/error-envelope.ts

@@ -0,0 +1,77 @@
+/**
+ * The canonical HTTP error envelope (`schemas/error-envelope.schema.json`,
+ * `rest-endpoints.md` §"Error envelope") is FLAT:
+ *
+ *   { "error": "<code>", "message": "<text>", "details"?: { … } }
+ *
+ * `additionalProperties: false`; `retriable`, `retryAfter`, `correlationId`,
+ * `supported`, `requested`, … live under `details`. Every conforming host,
+ * the TypeScript SDK's `ErrorEnvelope`, and the v1 lock all agree on this.
+ *
+ * Between 2026-06 and 2026-08 a NESTED shape — `{ error: { code, retriable } }`
+ * — crept into a few code-list entries of `rest-endpoints.md`, four
+ * `host-sample-test-seams.md` seam contracts (§19/§20/§22/§23) and ~15
+ * scenarios that read `body.error.code` off an HTTP response (S22, decided
+ * 2026-08-16: flat wins — the schema is authoritative and re-shaping `error`
+ * from string to object would break every conforming host under
+ * COMPATIBILITY.md §2.2). Three OTHER error objects are legitimately nested and
+ * are NOT this envelope: `RunSnapshot.error { code, message, retriable? }`
+ * (run-level), bulk-result items `{ ok:false, error:{ code } }`, and JSON-RPC
+ * bodies (MCP / A2A `{ error: { code, message } }`).
+ *
+ * These helpers read the CODE and the retriable hint from a canonical (flat)
+ * envelope, and — for a deprecation window ending with the first suite minor
+ * after 2026-11-10 — tolerate the legacy nested shape a seam may still emit,
+ * so a host is not made red for a shape the catalog itself prescribed until
+ * today. `assertCanonicalErrorEnvelope` is the strict form for legs that check
+ * the envelope's shape rather than only its code.
+ */
+
+export interface CanonicalErrorEnvelope {
+  readonly error: string;
+  readonly message: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+
+/** The error code from a canonical envelope; the legacy nested `error.code` is tolerated (deprecation window). */
+export function readErrorCode(body: unknown): string | undefined {
+  if (body === null || typeof body !== 'object') return undefined;
+  const e = (body as { error?: unknown }).error;
+  if (typeof e === 'string') return e;
+  if (e !== null && typeof e === 'object') {
+    const code = (e as { code?: unknown }).code;
+    return typeof code === 'string' ? code : undefined;
+  }
+  return undefined;
+}
+
+/** `details.retriable` from a canonical envelope; legacy nested `error.retriable` tolerated. */
+export function readRetriable(body: unknown): boolean | undefined {
+  if (body === null || typeof body !== 'object') return undefined;
+  const d = (body as { details?: unknown }).details;
+  if (d !== null && typeof d === 'object' && typeof (d as { retriable?: unknown }).retriable === 'boolean') {
+    return (d as { retriable: boolean }).retriable;
+  }
+  const e = (body as { error?: unknown }).error;
+  if (e !== null && typeof e === 'object' && typeof (e as { retriable?: unknown }).retriable === 'boolean') {
+    return (e as { retriable: boolean }).retriable;
+  }
+  return undefined;
+}
+
+/** True iff the body is the legacy nested `{ error: { code } }` shape (for reporting, never for asserting a pass). */
+export function isLegacyNestedEnvelope(body: unknown): boolean {
+  if (body === null || typeof body !== 'object') return false;
+  const e = (body as { error?: unknown }).error;
+  return e !== null && typeof e === 'object' && typeof (e as { code?: unknown }).code === 'string';
+}
+
+/** Strict shape check: flat, `error` + `message` strings, only the three top-level keys. */
+export function isCanonicalErrorEnvelope(body: unknown): body is CanonicalErrorEnvelope {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) return false;
+  const b = body as Record<string, unknown>;
+  if (typeof b['error'] !== 'string' || b['error'].length === 0) return false;
+  if (typeof b['message'] !== 'string' || b['message'].length === 0) return false;
+  for (const k of Object.keys(b)) if (k !== 'error' && k !== 'message' && k !== 'details') return false;
+  return b['details'] === undefined || (b['details'] !== null && typeof b['details'] === 'object');
+}

package/src/scenarios/conversationCapabilityNegotiation.test.ts

@@ -17,6 +17,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { isConversationPrimitiveSupported } from '../lib/multi-agent-capabilities.js';
@@ -33,8 +34,8 @@ describe.skipIf(SKIP)('conversationCapabilityNegotiation: refusal contract', ()
     // or at run-create (400). What MUST NOT happen is a successful
     // 201 followed by silent fallback.
     expect([400, 404, 422]).toContain(create.status);
-    const body = create.json as { error?: { code?: string }; code?: string };
-    const code = body.error?.code ?? body.code ?? '';
+    const body = create.json as { code?: string };
+    const code = readErrorCode(create.json) ?? body.code ?? '';
     expect(typeof code).toBe('string');
   });
 });

package/src/scenarios/data-residency-admission.test.ts

@@ -36,6 +36,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
@@ -96,12 +97,11 @@ describe.skipIf(HTTP_SKIP)('data-residency: admission control (capability-gated,
     // A host may legitimately reject the probe workflow for reasons unrelated to
     // residency (e.g. unknown workflowId) — but it MUST NOT reject an ADVERTISED
     // region with residency_unavailable. That specific pairing is the violation.
-    const okBody = ok.json as { error?: { code?: string } } | undefined;
     expect(
-      okBody?.error?.code !== 'residency_unavailable',
+      readErrorCode(ok.json) !== 'residency_unavailable',
       driver.describe(
         'capabilities.md §dataResidency / RFC 0129 §3',
-        `an ADVERTISED region ("${advertised}") MUST NOT be rejected with residency_unavailable (accept iff advertised) — got ${ok.status} ${JSON.stringify(okBody?.error)}`,
+        `an ADVERTISED region ("${advertised}") MUST NOT be rejected with residency_unavailable (accept iff advertised) — got ${ok.status} ${JSON.stringify(ok.json).slice(0, 200)}`,
       ),
     ).toBe(true);
 
@@ -114,7 +114,7 @@ describe.skipIf(HTTP_SKIP)('data-residency: admission control (capability-gated,
       inputs: {},
       residency: { region: bogus },
     });
-    const rejBody = rej.json as { error?: { code?: string }; runId?: string } | undefined;
+    const rejBody = rej.json as { runId?: string } | undefined;
 
     expect(
       rej.status === 400 || rej.status === 404 || rej.status === 422,
@@ -124,10 +124,10 @@ describe.skipIf(HTTP_SKIP)('data-residency: admission control (capability-gated,
       ),
     ).toBe(true);
     expect(
-      rejBody?.error?.code === 'residency_unavailable',
+      readErrorCode(rej.json) === 'residency_unavailable',
       driver.describe(
         'RFC 0129 §3',
-        `an unadvertised region MUST be rejected with error code "residency_unavailable" (MUST NOT silently accept-and-ignore) — got ${JSON.stringify(rejBody?.error)}`,
+        `an unadvertised region MUST be rejected with error code "residency_unavailable" (MUST NOT silently accept-and-ignore) — got ${JSON.stringify(rej.json).slice(0, 200)}`,
       ),
     ).toBe(true);
     expect(

package/src/scenarios/envelope-recovery-applied.test.ts

@@ -17,6 +17,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
@@ -83,7 +84,7 @@ describe.skipIf(HTTP_SKIP)('envelope-recovery-applied: SECURITY invariant envelo
         'envelope.recovery.applied payload MUST NOT carry pre-recovery output substrings; only the canonical {nodeId, path, byteOffset?} keys per RFC 0032 §B.6 + §G — the recovered content rides on downstream RunEventDoc, not on the recovery event',
       ),
     ).toBe(400);
-    expect(r.body.error?.code).toBe('envelope_recovery_content_leak');
+    expect(readErrorCode(r.body)).toBe('envelope_recovery_content_leak');
   });
 
   it('rejects payloads carrying any extra field outside {nodeId, path, byteOffset}', async () => {
@@ -104,7 +105,7 @@ describe.skipIf(HTTP_SKIP)('envelope-recovery-applied: SECURITY invariant envelo
         'envelope.recovery.applied has additionalProperties: false on the payload — any extra field MUST be rejected to prevent regression carriers for pre-recovery output (defense-in-depth on top of envelope-recovery-no-content-leak)',
       ),
     ).toBe(400);
-    expect(r.body.error?.code).toBe('envelope_recovery_content_leak');
+    expect(readErrorCode(r.body)).toBe('envelope_recovery_content_leak');
   });
 });
 

package/src/scenarios/envelope-refusal-shape.test.ts

@@ -27,6 +27,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
@@ -115,7 +116,7 @@ describe.skipIf(HTTP_SKIP)('envelope-refusal-shape: seam emission (RFC 0032 §B.
         'envelope.refusal.refusalText MUST be passed through the host BYOK redaction harness; seam refuses payloads carrying secret-canary-* substrings (defense-in-depth CI gate per RFC 0032 §B.3 + §G)',
       ),
     ).toBe(400);
-    expect(r.body.error?.code).toBe('envelope_reliability_credential_leak');
+    expect(readErrorCode(r.body)).toBe('envelope_reliability_credential_leak');
   });
 
   it('rejects payloads with a top-level `credentialRef` field', async () => {
@@ -131,7 +132,7 @@ describe.skipIf(HTTP_SKIP)('envelope-refusal-shape: seam emission (RFC 0032 §B.
     });
     if (r.status === 404) return;
     expect(r.status).toBe(400);
-    expect(r.body.error?.code).toBe('envelope_reliability_credential_leak');
+    expect(readErrorCode(r.body)).toBe('envelope_reliability_credential_leak');
   });
 
   it('rejects payloads missing required `provider` field', async () => {
@@ -146,7 +147,7 @@ describe.skipIf(HTTP_SKIP)('envelope-refusal-shape: seam emission (RFC 0032 §B.
     });
     if (r.status === 404) return;
     expect(r.status).toBe(400);
-    expect(r.body.error?.code).toBe('invalid_argument');
+    expect(readErrorCode(r.body)).toBe('invalid_argument');
   });
 });
 

package/src/scenarios/error-envelope-canonical-shape.test.ts

@@ -0,0 +1,64 @@
+/**
+ * S22 (2026-08-16) — the HTTP error envelope is FLAT, and the suite reads it
+ * through one helper.
+ *
+ * `rest-endpoints.md` §"Error response shape" and `schemas/error-envelope.schema.json`
+ * lock `{ error: <string code>, message, details? }` with `additionalProperties:
+ * false`. A nested `{ error: { code, retriable } }` shape had crept into three
+ * code-list entries, four seam contracts and ~15 scenarios; this scenario pins
+ * the decision at the three places it lives — the schema, the helper that every
+ * HTTP-envelope leg now reads through, and the prose — so it cannot re-open
+ * quietly. Server-free, always-on.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { SCHEMAS_DIR, V1_DIR } from '../lib/paths.js';
+import { readErrorCode, readRetriable, isCanonicalErrorEnvelope, isLegacyNestedEnvelope } from '../lib/error-envelope.js';
+
+export const HOST_CALLBACK_NOT_REQUIRED = 'server-free: pins the flat error-envelope decision against the schema, the helper and the prose';
+
+describe('S22 — the canonical HTTP error envelope is flat', () => {
+  const schema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'error-envelope.schema.json'), 'utf8')) as Record<string, unknown>;
+  const validate = new Ajv2020({ allErrors: true, strict: false }).compile(schema);
+
+  it('the schema says `error` is a string, requires `message`, and forbids other top-level keys', () => {
+    expect(validate({ error: 'runner_unavailable', message: 'no runner', details: { retriable: true } })).toBe(true);
+    expect(validate({ error: { code: 'runner_unavailable', retriable: true } })).toBe(false);
+    expect(validate({ error: 'x', message: 'y', retriable: true })).toBe(false); // top-level retriable is illegal
+    expect(validate({ error: 'x' })).toBe(false); // message required
+  });
+
+  it('readErrorCode / readRetriable read the canonical shape, and tolerate the legacy nested shape only as legacy', () => {
+    const flat = { error: 'interop_version_unsupported', message: 'peer offers 0.3', details: { retriable: false, protocol: 'a2a' } };
+    expect(readErrorCode(flat)).toBe('interop_version_unsupported');
+    expect(readRetriable(flat)).toBe(false);
+    expect(isCanonicalErrorEnvelope(flat)).toBe(true);
+    expect(isLegacyNestedEnvelope(flat)).toBe(false);
+    const nested = { error: { code: 'runner_unavailable', retriable: true } };
+    expect(readErrorCode(nested)).toBe('runner_unavailable');
+    expect(readRetriable(nested)).toBe(true);
+    expect(isCanonicalErrorEnvelope(nested)).toBe(false);
+    expect(isLegacyNestedEnvelope(nested)).toBe(true);
+    expect(readErrorCode({ message: 'no code' })).toBeUndefined();
+    expect(readErrorCode(null)).toBeUndefined();
+    expect(readRetriable({ error: 'x', message: 'y' })).toBeUndefined();
+  });
+
+  it.skipIf(V1_DIR === null)('rest-endpoints.md states the precedence, the details.retriable convention, and carries no nested code-list entry', () => {
+    const prose = readFileSync(join(V1_DIR as string, 'rest-endpoints.md'), 'utf8');
+    expect(prose).toContain('flat** shape above');
+    expect(prose).toContain('### `details.retriable` convention');
+    // the three formerly-nested code-list entries are flat now
+    for (const code of ['runner_unavailable', 'residency_unavailable', 'interop_version_unsupported']) {
+      const line = prose.split('\n').find((l) => l.startsWith('- `' + code + '`')) ?? '';
+      expect(line, code + ' code-list entry MUST exist').not.toBe('');
+      expect(line, code + ' MUST NOT be described with the nested envelope').not.toMatch(/\{\s*"error"\s*:\s*\{/);
+    }
+    // the seam catalog too
+    const seams = readFileSync(join(V1_DIR as string, 'host-sample-test-seams.md'), 'utf8');
+    expect(seams).not.toMatch(/"error":\s*\{\s*"code"/);
+  });
+});

package/src/scenarios/fs-path-traversal.test.ts

@@ -26,6 +26,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
@@ -97,7 +98,7 @@ describe('fs-path-traversal: MUST-NOT escape sandboxRoot (RFC 0014 §C)', () =>
         'absolute paths outside sandboxRoot MUST be rejected with a 4xx envelope',
       ),
     ).toBeGreaterThanOrEqual(400);
-    const code = (res.json as { error?: { code?: string } } | undefined)?.error?.code;
+    const code = readErrorCode(res.json);
     expect(
       code !== undefined && PATH_REJECTION_CODES.has(code),
       driver.describe(
@@ -113,7 +114,7 @@ describe('fs-path-traversal: MUST-NOT escape sandboxRoot (RFC 0014 §C)', () =>
     const res = await driver.post('/v1/host/sample/fs/read', { path: '../../etc/passwd' });
     if (res.status === 404) return;
     expect(res.status).toBeGreaterThanOrEqual(400);
-    const code = (res.json as { error?: { code?: string } } | undefined)?.error?.code;
+    const code = readErrorCode(res.json);
     expect(
       code !== undefined && PATH_REJECTION_CODES.has(code),
       driver.describe(

package/src/scenarios/provider-usage.test.ts

@@ -20,6 +20,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import Ajv2020 from 'ajv/dist/2020.js';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -179,8 +180,7 @@ describe('provider-usage: event presence via emit-seam + event-log query (RFC 00
       res.status,
       driver.describe('SECURITY/invariants.yaml provider-usage-no-credential-leak', 'payload with credentialRef-shaped content MUST be refused'),
     ).toBe(400);
-    const body = res.json as { error?: { code?: string } };
-    expect(body.error?.code).toBe('provider_usage_credential_leak');
+    expect(readErrorCode(res.json)).toBe('provider_usage_credential_leak');
     await resetTestSeam();
   });
 });

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

@@ -14,6 +14,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 
 interface DiscoveryDoc {
@@ -74,8 +75,7 @@ describe('table-schema-enforcement: behavioral (RFC 0016 §B point 2)', () => {
       bad.status >= 400 && bad.status < 500,
       driver.describe('RFC 0016 §B point 2', 'type-divergent insert MUST be rejected with 4xx'),
     ).toBe(true);
-    const body = bad.json as { error?: { code?: string } | string };
-    const code = typeof body.error === 'string' ? body.error : body.error?.code;
+    const code = readErrorCode(bad.json);
     expect(
       code,
       driver.describe('RFC 0016 §B point 2', 'rejection MUST carry the table_schema_violation error code'),

package/src/scenarios/voice-streamref-tenant-bound.test.ts

@@ -18,6 +18,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
@@ -29,7 +30,7 @@ function realtimeVoiceOf(ai: Record<string, unknown> | undefined): Record<string
   return rv && typeof rv === 'object' ? (rv as Record<string, unknown>) : undefined;
 }
 function errCode(json: unknown): string | undefined {
-  return (json as { error?: { code?: string } })?.error?.code;
+  return readErrorCode(json);
 }
 
 describe('voice-streamref-tenant-bound (RFC 0106 §F INV-4)', () => {

package/src/scenarios/voice-transcription-streaming.test.ts

@@ -19,6 +19,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
@@ -30,7 +31,7 @@ function realtimeVoiceOf(ai: Record<string, unknown> | undefined): Record<string
   return rv && typeof rv === 'object' ? (rv as Record<string, unknown>) : undefined;
 }
 function errCode(json: unknown): string | undefined {
-  return (json as { error?: { code?: string } })?.error?.code;
+  return readErrorCode(json);
 }
 function eventsOf(json: unknown): Array<{ type?: string; payload?: Record<string, unknown> }> {
   const e = (json as { events?: unknown })?.events;

package/src/scenarios/voice-transcription-unadvertised.test.ts

@@ -14,6 +14,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
@@ -25,7 +26,7 @@ function realtimeVoiceOf(ai: Record<string, unknown> | undefined): Record<string
   return rv && typeof rv === 'object' ? (rv as Record<string, unknown>) : undefined;
 }
 function errCode(json: unknown): string | undefined {
-  return (json as { error?: { code?: string } })?.error?.code;
+  return readErrorCode(json);
 }
 
 describe('voice-transcription-unadvertised (RFC 0106 §B)', () => {

package/src/scenarios/workload-identity-behavior.test.ts

@@ -33,6 +33,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { readErrorCode, readRetriable } from '../lib/error-envelope.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
@@ -76,7 +77,7 @@ async function resolve(body: Record<string, unknown>): Promise<{ status: number;
 }
 
 function reasonOf(json: unknown): string | undefined {
-  return (json as { error?: { code?: string } })?.error?.code;
+  return readErrorCode(json);
 }
 
 const IDENTITY = { scheme: 'spiffe', subject: 'spiffe://example/dispatcher', issuer: 'spiffe://example' };
@@ -154,9 +155,11 @@ describe('RFC 0154 §A — workload identity resolution (capability-gated behavi
     if (!behaviorGate(PROFILE, (await caps())?.supported === true)) return;
     const r = await resolve({ identity: { scheme: 'spiffe', subject: 'spiffe://example/unknown' } });
     if (r === null || r.status < 400) return;
-    const err = (r.json as { error?: { code?: string; retriable?: boolean } }).error;
+    // canonical flat envelope: code = `error`, retriable = `details.retriable`
+    // (the legacy nested `error.{code,retriable}` the §20 catalog prescribed until
+    // 2026-08-16 is tolerated by the helpers for the deprecation window)
     expect(
-      err?.retriable,
+      readRetriable(r.json),
       driver.describe(
         'spec/v1/host-sample-test-seams.md §20',
         'an identity that does not resolve will not resolve on retry. Marking it retriable invites ' +
@@ -166,7 +169,7 @@ describe('RFC 0154 §A — workload identity resolution (capability-gated behavi
     expect(
       ['identity_unverified', 'identity_unresolvable', 'audience_mismatch', 'delegation_expired', 'sender_constraint_missing'],
       driver.describe('RFCS/0154 §A', 'failures use a closed reason vocabulary'),
-    ).toContain(err?.code);
+    ).toContain(readErrorCode(r.json));
   });
 
   it('a resolution response carries no credential material', async () => {