@openwop/openwop-conformance 1.106.1 → 1.124.0

package/src/scenarios/cross-workspace-isolation.test.ts

@@ -21,6 +21,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 
 const ISOLATION_CODES: ReadonlySet<string> = new Set(['run_forbidden', 'not_found']);
@@ -35,9 +36,9 @@ describe('cross-workspace-isolation: run-ownership echo shape (RFC 0048 §C)', (
   it('owner, when present on a run snapshot, carries a non-empty tenant', async () => {
     // Best-effort: probe a sample run if the host exposes one; otherwise skip.
     const res = await driver.get('/v1/host/sample/identity/owned-run');
-    if (res.status === 404) return; // no sample-run seam — soft-skip
+    if (res.status === 404) return softSkip('blocked', 'no sample-run seam — soft-skip');
     const owner = (res.json as { owner?: OwnerTriple } | undefined)?.owner;
-    if (owner === undefined) return; // single-tenant host — owner omitted
+    if (owner === undefined) return softSkip('blocked', 'single-tenant host — owner omitted (owner === undefined)');
     expect(
       typeof owner.tenant === 'string' && owner.tenant.length > 0,
       driver.describe('RFC 0048 §C', 'RunSnapshot.owner MUST carry a non-empty tenant when present'),
@@ -50,7 +51,7 @@ describe('cross-workspace-isolation: a principal MUST NOT read another workspace
     // Seam contract: a principal scoped to workspace A requests a run owned
     // by workspace B. The host MUST refuse rather than return B's run.
     const res = await driver.post('/v1/host/sample/identity/cross-workspace-read', {});
-    if (res.status === 404) return; // seam unwired — soft-skip
+    if (res.status === 404) return softSkip('blocked', 'seam unwired — soft-skip');
 
     expect(
       res.status,

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/deadletter-retry-exhaustion.test.ts

@@ -22,6 +22,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
@@ -36,9 +37,9 @@ async function deadLetterSupported(): Promise<boolean> {
 
 describe('deadletter-retry-exhaustion: retry exhaustion → dead-lettered + fork-eligible (RFC 0053 §C)', () => {
   it('a retry-exhausted run emits run.dead_lettered with attempts', async () => {
-    if (!(await deadLetterSupported())) return; // capability-gated
+    if (!(await deadLetterSupported())) return softSkip('inapplicable', 'capability-gated');
     const res = await driver.post('/v1/host/sample/deadletter/exhaust', { scenario: 'exhaust-retries' });
-    if (res.status === 404) return; // seam unwired — soft-skip
+    if (res.status === 404) return softSkip('blocked', 'seam unwired — soft-skip');
     const body = res.json as { event?: { type?: string; payload?: { attempts?: number; runId?: string } } } | undefined;
     expect(
       body?.event?.type,
@@ -51,9 +52,9 @@ describe('deadletter-retry-exhaustion: retry exhaustion → dead-lettered + fork
   });
 
   it('the dead-lettered run is fork-eligible (RFC 0011)', async () => {
-    if (!(await deadLetterSupported())) return; // capability-gated
+    if (!(await deadLetterSupported())) return softSkip('inapplicable', 'capability-gated');
     const res = await driver.post('/v1/host/sample/deadletter/exhaust', { scenario: 'fork-after-dead-letter' });
-    if (res.status === 404) return; // seam unwired — soft-skip
+    if (res.status === 404) return softSkip('blocked', 'seam unwired — soft-skip');
     const body = res.json as { forkEligible?: boolean } | undefined;
     expect(
       body?.forkEligible,

package/src/scenarios/distillation-index-roundtrip.test.ts

@@ -14,15 +14,16 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readDistillationCap, invokeDistill } from '../lib/distillation.js';
 
 describe('distillation-index-roundtrip (RFC 0062 §B)', () => {
   it('an indexEmitted run updates a retrievable memory-index manifest', async () => {
     const cap = await readDistillationCap();
-    if (cap?.supported !== true || cap?.indexEmitted !== true) return;
+    if (cap?.supported !== true || cap?.indexEmitted !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true || cap?.indexEmitted !== true` returned early');
     const res = await invokeDistill({ memoryRef: 'conformance-distill', tokenBudget: 8000, indexEmitted: true });
-    if (res === null) return; // seam absent — soft-skip
+    if (res === null) return softSkip('blocked', 'seam absent — soft-skip');
     expect(
       res.body.indexUpdated === true || res.body.event?.distillation?.indexUpdated === true,
       driver.describe('RFC 0062 §B', 'an indexEmitted distillation MUST report updating the memory index'),

package/src/scenarios/distillation-secret-carryforward.test.ts

@@ -12,6 +12,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readDistillationCap, invokeDistill } from '../lib/distillation.js';
 
@@ -19,14 +20,14 @@ const CANARY = 'sk-canary-rfc0062-do-not-leak-qrs456';
 
 describe('distillation-secret-carryforward (RFC 0062 §B)', () => {
   it('a redacted secret in source memory never appears in the distilled output', async () => {
-    if ((await readDistillationCap())?.supported !== true) return;
+    if ((await readDistillationCap())?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `(await readDistillationCap())?.supported !== true` returned early');
     const res = await invokeDistill({
       memoryRef: 'conformance-distill',
       tokenBudget: 8000,
       includeSecretCanary: true,
       sources: [{ content: `notes with embedded secret ${CANARY}` }],
     });
-    if (res === null) return; // seam absent — soft-skip
+    if (res === null) return softSkip('blocked', 'seam absent — soft-skip');
     expect(
       JSON.stringify(res.body).includes(CANARY),
       driver.describe('RFC 0062 §B', 'SR-1 carry-forward: a redacted secret MUST NOT re-appear in the archive or memory.compacted event'),

package/src/scenarios/distillation-shape.test.ts

@@ -12,13 +12,14 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readDistillationCap } from '../lib/distillation.js';
 
 describe('distillation-shape: advertisement (RFC 0062 §A)', () => {
   it('capabilities.memory.distillation is absent or a well-formed object', async () => {
     const cap = await readDistillationCap();
-    if (cap === null) return; // not advertised — valid
+    if (cap === null) return softSkip('inapplicable', 'not advertised — valid');
     expect(
       typeof cap.supported,
       driver.describe('capabilities.schema.json §memory.distillation', 'distillation.supported MUST be a boolean when the block is present'),

package/src/scenarios/distillation-stable-archive.test.ts

@@ -10,21 +10,22 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readDistillationCap, invokeDistill } from '../lib/distillation.js';
 
 describe('distillation-stable-archive (RFC 0062 §B)', () => {
   it('identical sources + budget produce an identical archive checksum', async () => {
-    if ((await readDistillationCap())?.supported !== true) return;
+    if ((await readDistillationCap())?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `(await readDistillationCap())?.supported !== true` returned early');
     const req = {
       memoryRef: 'conformance-distill',
       tokenBudget: 8000,
       sources: ['s1', 's2', 's3'],
     };
     const a = await invokeDistill(req);
-    if (a === null) return; // seam absent — soft-skip
+    if (a === null) return softSkip('blocked', 'seam absent — soft-skip');
     const b = await invokeDistill(req);
-    if (b === null) return;
+    if (b === null) return softSkip('blocked', 'precondition not met — `b === null` returned early (seam, prior step, or fixture unavailable)');
     expect(
       typeof a.body.archiveChecksum === 'string' && (a.body.archiveChecksum as string).length > 0,
       driver.describe('RFC 0062 §B', 'a distillation run MUST produce a non-empty archive checksum'),

package/src/scenarios/distillation-token-budget.test.ts

@@ -11,15 +11,16 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readDistillationCap, invokeDistill } from '../lib/distillation.js';
 
 describe('distillation-token-budget (RFC 0062 §B)', () => {
   it('within budget tokensUsed ≤ tokenBudget; an un-meetable budget fails atomically', async () => {
-    if ((await readDistillationCap())?.supported !== true) return;
+    if ((await readDistillationCap())?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `(await readDistillationCap())?.supported !== true` returned early');
 
     const ok = await invokeDistill({ memoryRef: 'conformance-distill', tokenBudget: 8000 });
-    if (ok === null) return; // seam absent — soft-skip
+    if (ok === null) return softSkip('blocked', 'seam absent — soft-skip');
     const dist = ok.body.event?.distillation ?? {};
     expect(
       typeof dist.tokenBudget === 'number' && typeof dist.tokensUsed === 'number',
@@ -32,7 +33,7 @@ describe('distillation-token-budget (RFC 0062 §B)', () => {
 
     // A budget too small to distill the corpus MUST fail closed, no partial archive.
     const tooSmall = await invokeDistill({ memoryRef: 'conformance-distill', tokenBudget: 1 });
-    if (tooSmall === null) return;
+    if (tooSmall === null) return softSkip('blocked', 'precondition not met — `tooSmall === null` returned early (seam, prior step, or fixture unavailable)');
     expect(
       tooSmall.status >= 400 && tooSmall.body.error === 'token_budget_exceeded',
       driver.describe('RFC 0062 §B', 'an un-meetable budget MUST fail with token_budget_exceeded'),

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/feedback-correction-redaction.test.ts

@@ -9,6 +9,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readFeedbackCap, seedRun } from '../lib/feedback.js';
 
@@ -17,14 +18,14 @@ const CANARY = 'sk-canary-rfc0056-do-not-leak-abc123';
 describe('feedback-correction-redaction (RFC 0056 §E)', () => {
   it('secret-shaped material in correction/note is redacted in the annotation list', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported !== true) return;
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
     const runId = await seedRun('feedback-redact');
-    if (!runId) return;
+    if (!runId) return softSkip('blocked', 'precondition not met — `!runId` returned early (seam, prior step, or fixture unavailable)');
     const post = await driver.post(`/v1/runs/${runId}/annotations`, {
       signal: { kind: 'correction', correction: `please use ${CANARY}` },
       note: CANARY,
     });
-    if (post.status === 501 || post.status === 404) return;
+    if (post.status === 501 || post.status === 404) return softSkip('blocked', 'precondition not met — `post.status === 501 || post.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(post.status).toBe(201);
     const list = await driver.get(`/v1/runs/${runId}/annotations`);
     expect(

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

@@ -13,17 +13,18 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readFeedbackCap, seedRun } from '../lib/feedback.js';
 
 describe('feedback-cross-tenant-isolation (RFC 0056 §E)', () => {
   it('a run\'s annotation list contains only that run\'s annotations', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported !== true) return;
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
     const runId = await seedRun('feedback-cti');
-    if (!runId) return;
+    if (!runId) return softSkip('blocked', 'precondition not met — `!runId` returned early (seam, prior step, or fixture unavailable)');
     const post = await driver.post(`/v1/runs/${runId}/annotations`, { signal: { kind: 'label', label: 'cti-probe' } });
-    if (post.status === 501 || post.status === 404) return;
+    if (post.status === 501 || post.status === 404) return softSkip('blocked', 'precondition not met — `post.status === 501 || post.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(post.status).toBe(201);
     const list = await driver.get(`/v1/runs/${runId}/annotations`);
     const ann = (list.json as { annotations?: Array<{ target?: { runId?: string } }> } | undefined)?.annotations ?? [];

package/src/scenarios/feedback-fork-not-copied.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { readFeedbackCap, seedRun } from '../lib/feedback.js';
@@ -15,11 +16,11 @@ import { readFeedbackCap, seedRun } from '../lib/feedback.js';
 describe('feedback-fork-not-copied (RFC 0056 §D)', () => {
   it('a fork of an annotated run starts with zero annotations', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported !== true) return;
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
     const runId = await seedRun('feedback-fork');
-    if (!runId) return;
+    if (!runId) return softSkip('blocked', 'precondition not met — `!runId` returned early (seam, prior step, or fixture unavailable)');
     const post = await driver.post(`/v1/runs/${runId}/annotations`, { signal: { kind: 'flag' } });
-    if (post.status === 501 || post.status === 404) return;
+    if (post.status === 501 || post.status === 404) return softSkip('blocked', 'precondition not met — `post.status === 501 || post.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(post.status).toBe(201);
     try {
       await pollUntilTerminal(runId, { timeoutMs: 10_000 });
@@ -27,9 +28,9 @@ describe('feedback-fork-not-copied (RFC 0056 §D)', () => {
       return;
     }
     const fork = await driver.post(`/v1/runs/${runId}:fork`, { fromSeq: 0, mode: 'branch' });
-    if (fork.status !== 200 && fork.status !== 201) return; // fork unsupported — soft-skip
+    if (fork.status !== 200 && fork.status !== 201) return softSkip('inapplicable', 'fork unsupported — soft-skip (fork.status !== 200 && fork.status !== 201)');
     const forkId = (fork.json as { runId?: string } | undefined)?.runId;
-    if (!forkId) return;
+    if (!forkId) return softSkip('blocked', 'precondition not met — `!forkId` returned early (seam, prior step, or fixture unavailable)');
     const list = await driver.get(`/v1/runs/${forkId}/annotations`);
     const ann = (list.json as { annotations?: unknown[] } | undefined)?.annotations ?? [];
     expect(

package/src/scenarios/feedback-on-terminal-run.test.ts

@@ -7,6 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { readFeedbackCap, seedRun } from '../lib/feedback.js';
@@ -14,16 +15,16 @@ import { readFeedbackCap, seedRun } from '../lib/feedback.js';
 describe('feedback-on-terminal-run (RFC 0056 §C)', () => {
   it('annotating a terminal run is accepted', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported !== true) return;
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
     const runId = await seedRun('feedback-terminal');
-    if (!runId) return;
+    if (!runId) return softSkip('blocked', 'precondition not met — `!runId` returned early (seam, prior step, or fixture unavailable)');
     try {
       await pollUntilTerminal(runId, { timeoutMs: 10_000 });
     } catch {
       return; // run didn't reach terminal in time — soft-skip
     }
     const post = await driver.post(`/v1/runs/${runId}/annotations`, { signal: { kind: 'flag' }, note: 'post-hoc review' });
-    if (post.status === 501 || post.status === 404) return;
+    if (post.status === 501 || post.status === 404) return softSkip('blocked', 'precondition not met — `post.status === 501 || post.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(
       post.status,
       driver.describe('RFC 0056 §C', 'a host MUST accept an annotation on a terminal run'),

package/src/scenarios/feedback-record-and-list.test.ts

@@ -7,17 +7,18 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readFeedbackCap, seedRun } from '../lib/feedback.js';
 
 describe('feedback-record-and-list (RFC 0056 §C)', () => {
   it('POST an annotation then GET returns it', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported !== true) return;
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
     const runId = await seedRun('feedback-rl');
-    if (!runId) return;
+    if (!runId) return softSkip('blocked', 'precondition not met — `!runId` returned early (seam, prior step, or fixture unavailable)');
     const post = await driver.post(`/v1/runs/${runId}/annotations`, { signal: { kind: 'rating', rating: 5 } });
-    if (post.status === 501 || post.status === 404) return;
+    if (post.status === 501 || post.status === 404) return softSkip('blocked', 'precondition not met — `post.status === 501 || post.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(
       post.status,
       driver.describe('RFC 0056 §C', 'POST annotation returns 201 with the persisted annotation'),

package/src/scenarios/feedback-unsupported-501.test.ts

@@ -11,17 +11,18 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readFeedbackCap } from '../lib/feedback.js';
 
 describe('feedback-unsupported-501 (RFC 0056 §C)', () => {
   it('POST annotations returns 501 capability_not_provided when feedback is unadvertised', async () => {
     const cap = await readFeedbackCap();
-    if (cap?.supported === true) return; // host supports feedback — 501 N/A
+    if (cap?.supported === true) return softSkip('inapplicable', 'host supports feedback — 501 N/A (cap?.supported === true)');
     const res = await driver.post('/v1/runs/probe-run-rfc0056/annotations', {
       signal: { kind: 'flag' },
     });
-    if (res.status === 404 || res.status === 405) return; // route absent — host predates RFC 0056
+    if (res.status === 404 || res.status === 405) return softSkip('blocked', 'route absent — host predates RFC 0056');
     expect(
       res.status,
       driver.describe('rest-endpoints.md / RFC 0056 §C', 'unadvertised feedback MUST return 501, not 404'),

package/src/scenarios/fixtures-valid.test.ts

@@ -24,24 +24,22 @@ const PROMPT_TEMPLATE_SCHEMA_PATH = join(SCHEMAS_DIR, 'prompt-template.schema.js
 describe('fixtures: workflow-definition schema validity', () => {
   const ajv = new Ajv2020({ allErrors: true, strict: false });
   addFormats(ajv);
-  // Pre-load peer schemas that workflow-definition cross-`$ref`s:
-  //   - agent-ref.schema.json — `WorkflowNode.agent` (Phase 1 multi-agent)
-  //   - prompt-ref.schema.json — `WorkflowDefinition.defaults.promptRefs.*`
-  //     (RFC 0029 §B resolution-chain layer 3)
-  //   - prompt-kind.schema.json — transitively referenced by prompt-ref's
-  //     object form when validating PromptRef variants
-  // Register each under both the canonical $id and the relative file
-  // name so Ajv resolves either way the host schema spelled the ref.
-  const agentRefSchema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'agent-ref.schema.json'), 'utf8'));
-  const promptRefSchema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'prompt-ref.schema.json'), 'utf8'));
-  const promptKindSchema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'prompt-kind.schema.json'), 'utf8'));
-  ajv.addSchema(agentRefSchema, 'agent-ref.schema.json');
-  ajv.addSchema(promptRefSchema, 'prompt-ref.schema.json');
-  ajv.addSchema(promptRefSchema, './prompt-ref.schema.json');
-  ajv.addSchema(promptKindSchema, 'prompt-kind.schema.json');
-  ajv.addSchema(promptKindSchema, './prompt-kind.schema.json');
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const validate = ajv.compile(schema);
+  // Pre-load EVERY schema in the corpus (S14, 2026-08-16). This used to be a
+  // fixed list of the peer schemas workflow-definition cross-`$ref`s (agent-ref,
+  // prompt-ref, prompt-kind) — and when `compensation-policy.schema.json` became
+  // the fourth cross-file `$ref` (#1009), `ajv.compile` threw at describe time
+  // here and in every downstream runner that resolves the sibling corpus with a
+  // pinned suite. A fixed list is a claim about the schema graph that nothing
+  // keeps true; enumerating the directory is not. Each schema is registered
+  // under both its bare file name and `./<name>` so Ajv resolves either spelling
+  // of a relative ref (canonical `$id`s resolve on their own).
+  for (const file of readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.schema.json'))) {
+    const s = JSON.parse(readFileSync(join(SCHEMAS_DIR, file), 'utf8')) as { $id?: string };
+    ajv.addSchema(s, file);
+    ajv.addSchema(s, `./${file}`);
+  }
+  // The root schema is already registered under its $id above; compile via getSchema.
+  const validate = ajv.getSchema('workflow-definition.schema.json') ?? ajv.compile(JSON.parse(readFileSync(SCHEMA_PATH, 'utf8')));
 
   const files = readdirSync(FIXTURES_DIR)
     .filter((f) => f.endsWith('.json')) // top-level only — sub-dirs hold non-workflow fixtures

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/heartbeat-capability-shape.test.ts

@@ -11,13 +11,14 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readHeartbeatCap } from '../lib/heartbeat.js';
 
 describe('heartbeat-capability-shape: advertisement (RFC 0060 §A)', () => {
   it('capabilities.heartbeat is absent or a well-formed object', async () => {
     const cap = await readHeartbeatCap();
-    if (cap === null) return; // not advertised — valid
+    if (cap === null) return softSkip('inapplicable', 'not advertised — valid');
     expect(
       typeof cap.supported,
       driver.describe('capabilities.schema.json §heartbeat', 'heartbeat.supported MUST be a boolean when the block is present'),

package/src/scenarios/heartbeat-fires-once-per-tick.test.ts

@@ -10,16 +10,17 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { readHeartbeatCap, heartbeatSupported, tickHeartbeat } from '../lib/heartbeat.js';
 
 describe('heartbeat-fires-once-per-tick (RFC 0060 §B.1)', () => {
   it('one tick emits exactly one heartbeat.evaluated', async () => {
-    if (!heartbeatSupported(await readHeartbeatCap())) return;
+    if (!heartbeatSupported(await readHeartbeatCap())) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!heartbeatSupported(await readHeartbeatCap())` returned early');
     const res = await tickHeartbeat({ heartbeatId: 'conformance-hb', observedState: { n: 0 } });
-    if (res === null) return; // seam absent — soft-skip
+    if (res === null) return softSkip('blocked', 'seam absent — soft-skip');
     const evaluated = (res.json as { evaluated?: unknown[] } | undefined)?.evaluated;
-    if (!Array.isArray(evaluated)) return; // host doesn't surface per-tick events on the seam
+    if (!Array.isArray(evaluated)) return softSkip('blocked', 'host doesn\'t surface per-tick events on the seam');
     expect(
       evaluated.length,
       driver.describe('RFC 0060 §B.1', 'a single tick MUST emit exactly one heartbeat.evaluated'),