@openwop/openwop-conformance 1.123.0 → 1.125.0

package/dist/lib/scenario-disposition.js

@@ -88,7 +88,9 @@ export function fileDisposition(states, gateReason, assertionCount) {
  *   - a zero-assertion "pass" ⇒ the file's noted reason (`softSkip` /
  *     `seamAbsent`: inapplicable | skipped | blocked) or a behaviorGate reason;
  *   - a zero-assertion "pass" with NO reason ⇒ `blocked` + the marker detail —
- *     an early return can never become a pass.
+ *     an early return can never become a pass;
+ *   - every test `ctx.skip()`ped ⇒ the file's noted reason if it wrote one
+ *     BEFORE skipping (`ctx.skip()` throws), else `blocked` + the marker.
  */
 export function resolveFileRecord(states, gateReason, assertionCount, noted) {
     let { disposition, detail } = fileDisposition(states, gateReason, assertionCount);
@@ -102,6 +104,17 @@ export function resolveFileRecord(states, gateReason, assertionCount, noted) {
             detail = UNCLASSIFIED_RETURN_DETAIL;
         }
     }
+    else if (noted !== null &&
+        gateReason === undefined &&
+        states.length > 0 &&
+        states.every((s) => s === 'skip')) {
+        // Every test called `ctx.skip()` (vitest reports them as skipped, not as
+        // zero-assertion passes) and the file noted why first. Note-then-skip is
+        // the required order: `ctx.skip()` throws, so a note written after it is
+        // dead code — which is how seven files carried notes the ledger never saw.
+        disposition = noted.kind;
+        detail = noted.reason;
+    }
     return detail === undefined ? { disposition } : { disposition, detail };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.123.0",
+  "version": "1.125.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.125.0",
+  "corpusCommit": "13ab2a545d4e2a30c8da66354e39d4db7233acae"
 }

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/lib/scenario-disposition.ts

@@ -94,7 +94,9 @@ export function fileDisposition(
  *   - a zero-assertion "pass" ⇒ the file's noted reason (`softSkip` /
  *     `seamAbsent`: inapplicable | skipped | blocked) or a behaviorGate reason;
  *   - a zero-assertion "pass" with NO reason ⇒ `blocked` + the marker detail —
- *     an early return can never become a pass.
+ *     an early return can never become a pass;
+ *   - every test `ctx.skip()`ped ⇒ the file's noted reason if it wrote one
+ *     BEFORE skipping (`ctx.skip()` throws), else `blocked` + the marker.
  */
 export function resolveFileRecord(
   states: readonly FileTestState[],
@@ -111,6 +113,18 @@ export function resolveFileRecord(
       disposition = 'blocked';
       detail = UNCLASSIFIED_RETURN_DETAIL;
     }
+  } else if (
+    noted !== null &&
+    gateReason === undefined &&
+    states.length > 0 &&
+    states.every((s) => s === 'skip')
+  ) {
+    // Every test called `ctx.skip()` (vitest reports them as skipped, not as
+    // zero-assertion passes) and the file noted why first. Note-then-skip is
+    // the required order: `ctx.skip()` throws, so a note written after it is
+    // dead code — which is how seven files carried notes the ledger never saw.
+    disposition = noted.kind;
+    detail = noted.reason;
   }
   return detail === undefined ? { disposition } : { disposition, detail };
 }

package/src/scenarios/conformance-execution-witness.test.ts

@@ -51,6 +51,18 @@ describe('RFC 0148 §A — conformance-execution-witness: the runner record', ()
     expect(resolveFileRecord(['pass'], undefined, 0, { kind: 'skipped', reason: 'operator opt-out' })).toEqual({ disposition: 'skipped', detail: 'operator opt-out' });
   });
 
+  it('every test ctx.skip()ped takes the noted reason when one was written before the skip, else stays the blocked marker', () => {
+    // `ctx.skip()` throws — a `softSkip(...)` AFTER it is dead code. Seven files
+    // carried exactly that dead note and reported as unclassified for a suite minor.
+    expect(resolveFileRecord(['skip', 'skip'], undefined, 0, { kind: 'inapplicable', reason: 'sandbox not advertised' })).toEqual({ disposition: 'inapplicable', detail: 'sandbox not advertised' });
+    expect(resolveFileRecord(['skip'], undefined, 0, { kind: 'blocked', reason: 'simulator seam 404' })).toEqual({ disposition: 'blocked', detail: 'simulator seam 404' });
+    const bare = resolveFileRecord(['skip', 'skip'], undefined, 0, null);
+    expect(bare.disposition).toBe('blocked');
+    expect(bare.detail).toMatch(/every test skipped with no recorded reason/);
+    // A behaviorGate reason still wins over a note — the gate is the more specific record.
+    expect(resolveFileRecord(['skip'], 'inapplicable', 0, { kind: 'blocked', reason: 'x' }).disposition).toBe('inapplicable');
+  });
+
   it('a behaviorGate reason resolves a zero-assertion pass to inapplicable/skipped; a note outranks nothing but never a witnessed pass', () => {
     expect(resolveFileRecord(['pass'], 'inapplicable', 0, null).disposition).toBe('inapplicable');
     expect(resolveFileRecord(['pass'], 'skipped', 0, null).disposition).toBe('skipped');

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/cross-engine-append-behavior.test.ts

@@ -29,7 +29,8 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { softSkip } from '../lib/soft-skip.js';
+import { softSkip, seamAbsent } from '../lib/soft-skip.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 import { driver } from '../lib/driver.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
@@ -69,12 +70,29 @@ async function resetLog(): Promise<number> {
   return res.status;
 }
 
+/**
+ * The cross-engine harness seam answered 404. Whether that is `blocked` (the host
+ * advertises `eventLog.crossEngineOrdering.supported: true` and so made a claim
+ * this file cannot check) or `inapplicable` (no such advertisement) depends on
+ * discovery — record the honest one (RFC 0148 §A).
+ */
+async function noteHarnessAbsent(): Promise<void> {
+  const disco = await driver.get('/.well-known/openwop');
+  const el = capabilityFamily<{ crossEngineOrdering?: { supported?: unknown } }>(disco.json, 'eventLog');
+  if (el?.crossEngineOrdering?.supported === true) {
+    seamAbsent('host advertises `eventLog.crossEngineOrdering.supported: true` but `POST /v1/host/sample/test/cross-engine/reset` answered 404 — the ordering claim is unobservable (host-sample-test-seams.md)');
+  } else {
+    softSkip('inapplicable', 'optional advertisement — `eventLog.crossEngineOrdering` not advertised by this host, and the cross-engine harness seam is absent (RFC 0036 §B)');
+  }
+}
+
 describe.skipIf(HTTP_SKIP)('cross-engine-append-behavior: §B cross-engine ordering (RFC 0036)', () => {
   it('interleaved appends from two engines converge to a single globally-ordered sequence', async (ctx) => {
     const resetStatus = await resetLog();
     if (resetStatus === 404) {
+      await noteHarnessAbsent();
       ctx.skip(); // host doesn't expose the cross-engine harness seam
-      return softSkip('blocked', 'precondition not met — `resetStatus === 404` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     expect(resetStatus).toBe(200);
 
@@ -125,8 +143,9 @@ describe.skipIf(HTTP_SKIP)('cross-engine-append-behavior: §B cross-engine order
   it('lamport clocks monotonically advance across engines', async (ctx) => {
     const resetStatus = await resetLog();
     if (resetStatus === 404) {
+      await noteHarnessAbsent();
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `resetStatus === 404` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     expect(resetStatus).toBe(200);
 
@@ -153,8 +172,9 @@ describe.skipIf(HTTP_SKIP)('cross-engine-append-behavior: §B cross-engine order
   it('lamport hint from engine A advances engine B past it', async (ctx) => {
     const resetStatus = await resetLog();
     if (resetStatus === 404) {
+      await noteHarnessAbsent();
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `resetStatus === 404` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     expect(resetStatus).toBe(200);
 
@@ -180,8 +200,9 @@ describe.skipIf(HTTP_SKIP)('cross-engine-append-behavior: §B cross-engine order
   it('linearization is deterministic — same appends → same total order', async (ctx) => {
     const resetStatus = await resetLog();
     if (resetStatus === 404) {
+      await noteHarnessAbsent();
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `resetStatus === 404` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     expect(resetStatus).toBe(200);
 

package/src/scenarios/cross-host-ancestry-endpoint.test.ts

@@ -69,8 +69,9 @@ describe.skipIf(HTTP_SKIP)('cross-host-ancestry-endpoint: behavioral (RFC 0040
     const d = await readDiscovery();
     const chc = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.crossHostCausation;
     if (chc?.ancestryEndpointSupported !== true) {
+      softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc?.ancestryEndpointSupported !== true` returned early');
       ctx.skip();
-      return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc?.ancestryEndpointSupported !== true` returned early');
+      return;
     }
 
     // Create a fresh top-level run via the host's conformance-dispatch-loop
@@ -78,8 +79,9 @@ describe.skipIf(HTTP_SKIP)('cross-host-ancestry-endpoint: behavioral (RFC 0040
     // depend on the specific workflow).
     const create = await driver.post('/v1/runs', { workflowId: 'conformance-dispatch-loop' });
     if (create.status !== 201) {
+      softSkip('blocked', 'precondition not met — `create.status !== 201` returned early (seam, prior step, or fixture unavailable)');
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `create.status !== 201` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     const runId = (create.json as { runId: string }).runId;
 
@@ -116,12 +118,14 @@ describe.skipIf(HTTP_SKIP)('cross-host-ancestry-endpoint: behavioral (RFC 0040
     const d = await readDiscovery();
     const chc = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.crossHostCausation;
     if (chc?.supported !== true) {
+      softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc?.supported !== true` returned early');
       ctx.skip();
-      return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc?.supported !== true` returned early');
+      return;
     }
     if (chc.ancestryEndpointSupported === true) {
+      softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc.ancestryEndpointSupported === true` returned early');
       ctx.skip(); // covered by the test above
-      return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `chc.ancestryEndpointSupported === true` returned early');
+      return;
     }
 
     // Use any runId — even a synthetic non-existent one. The endpoint should

package/src/scenarios/cross-host-causation-shape.test.ts

@@ -62,13 +62,15 @@ describe.skipIf(HTTP_SKIP)('cross-host-causation-shape: advertisement shape (RFC
   it('crossHostCausation (when present) conforms to RFC 0040 §D', async (ctx) => {
     const d = await readDiscovery();
     if (d === null) {
+      softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     const chc = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.crossHostCausation;
     if (chc === undefined) {
+      softSkip('inapplicable', 'optional advertisement — `multiAgent.executionModel.crossHostCausation` not advertised by this host (RFC 0040 §D)');
       ctx.skip(); // host doesn't advertise — soft-skip
-      return softSkip('blocked', 'precondition not met — `chc === undefined` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
 
     expect(

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/multi-agent-memory-lifecycle.test.ts

@@ -80,13 +80,15 @@ describe.skipIf(HTTP_SKIP)('multi-agent-memory-lifecycle: advertisement shape (R
   it('crossChildMemoryConcurrency (when advertised) MUST be one of {strict, advisory}', async (ctx) => {
     const d = await readDiscovery();
     if (d === null) {
+      softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     const ccmc = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.crossChildMemoryConcurrency;
     if (ccmc === undefined) {
+      softSkip('inapplicable', 'optional advertisement — `multiAgent.executionModel.crossChildMemoryConcurrency` not advertised by this host');
       ctx.skip(); // optional advertisement — host hasn't opted in
-      return softSkip('blocked', 'precondition not met — `ccmc === undefined` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     expect(
       ccmc === 'strict' || ccmc === 'advisory',
@@ -134,16 +136,18 @@ describe.skipIf(HTTP_SKIP)('multi-agent-memory-lifecycle: behavioral (RFC 0039
   it('MAE-3 replay snapshot refusal: fork mode:replay against a past-retention runId MUST return 422 replay_memory_snapshot_unavailable with documented envelope; silent substitution is non-conformant', async (ctx) => {
     const d = await readDiscovery();
     if (d === null) {
+      softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
       ctx.skip();
-      return softSkip('blocked', 'precondition not met — `d === null` returned early (seam, prior step, or fixture unavailable)');
+      return;
     }
     const v = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.version;
     const memorySupported = capabilityFamily<{ supported?: unknown }>(d, 'memory')?.supported;
     const phase2OrLater = typeof v === 'number' && v >= 2;
     const expiredRunId = process.env.OPENWOP_TEST_EXPIRED_REPLAY_RUN_ID;
     if (!phase2OrLater || memorySupported !== true || !expiredRunId) {
+      softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!phase2OrLater || memorySupported !== true || !expiredRunId` returned early');
       ctx.skip();
-      return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!phase2OrLater || memorySupported !== true || !expiredRunId` returned early');
+      return;
     }
 
     const fromSeq = 0;