@openwop/openwop-conformance 1.6.0 → 1.10.0

package/src/scenarios/spec-corpus-validity.test.ts

@@ -1016,7 +1016,10 @@ describe('spec-corpus: AsyncAPI 3.1 spec is structurally valid', () => {
     const messageNames = extractAsyncApiMessageNames(raw);
     const runEventSchema = readJson(join(SCHEMAS_DIR, 'run-event.schema.json'));
     const runEventTypes = new Set(findRunEventTypeEnum(runEventSchema));
-    const syntheticMessageNames = new Set(['state.snapshot', 'ai.message.chunk', 'any']);
+    // `run.annotated` (RFC 0056) is a live SSE notification carrying an
+    // Annotation — NOT a RunEventDoc and deliberately NOT in the RunEventType
+    // enum (annotations are a side-resource, excluded from fork/replay).
+    const syntheticMessageNames = new Set(['state.snapshot', 'ai.message.chunk', 'any', 'run.annotated', 'heartbeat.evaluated', 'heartbeat.stateChanged']);
 
     expect(messageNames.length, 'AsyncAPI MUST declare named SSE messages').toBeGreaterThan(0);
 

package/src/scenarios/subrun-approval-fail-closed.test.ts

@@ -0,0 +1,33 @@
+/**
+ * subrun-approval-fail-closed — RFC 0063 §C. A parent that terminates or whose
+ * approval interrupt expires WITHOUT an `accept`/`edit-accept` MUST NOT merge the
+ * child outputs. Absence of an approval is denial — backs the proposed
+ * protocol-tier SECURITY invariant `subrun-merge-approval-fail-closed` (lands
+ * with this test promoted to load-bearing at reference-host implementation).
+ *
+ * Gated on `capabilities.agents.subRunAttestation` + the host sub-run attestation
+ * seam; soft-skips when either is absent.
+ *
+ * @see RFCS/0063-subrun-output-attestation-and-merge-gating.md §C
+ * @see SECURITY/invariants.yaml — subrun-merge-approval-fail-closed (lands at impl)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readSubRunAttestationCap, invokeSubRunAttest } from '../lib/subRunAttestation.js';
+
+describe('subrun-approval-fail-closed (RFC 0063 §C)', () => {
+  it('no accept/edit-accept (terminated or expired) MUST NOT merge', async () => {
+    if ((await readSubRunAttestationCap()) !== true) return;
+    // approvalAction omitted models a run that terminated without a response.
+    const res = await invokeSubRunAttest({
+      childOutputs: { artifact: 'unverified' },
+      outputAttestation: { requireApproval: true },
+    });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.merged,
+      driver.describe('RFC 0063 §C', 'an unresolved approval MUST fail closed — outputs MUST NOT be merged'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/subrun-approval-gate.test.ts

@@ -0,0 +1,35 @@
+/**
+ * subrun-approval-gate — RFC 0063 §C. When `requireApproval: true`, the host
+ * suspends before merge; `accept` merges the child outputs, `reject` does not.
+ *
+ * Gated on `capabilities.agents.subRunAttestation` + the host sub-run attestation
+ * seam; soft-skips when either is absent.
+ *
+ * @see RFCS/0063-subrun-output-attestation-and-merge-gating.md §C
+ * @see spec/v1/interrupt.md — `approval` kind + resume actions (RFC 0051, reused)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readSubRunAttestationCap, invokeSubRunAttest } from '../lib/subRunAttestation.js';
+
+describe('subrun-approval-gate (RFC 0063 §C)', () => {
+  it('accept merges the child outputs; reject does not', async () => {
+    if ((await readSubRunAttestationCap()) !== true) return;
+    const base = { childOutputs: { artifact: 'x' }, outputAttestation: { requireApproval: true } };
+
+    const accepted = await invokeSubRunAttest({ ...base, approvalAction: 'accept' });
+    if (accepted === null) return; // seam absent — soft-skip
+    expect(
+      accepted.merged,
+      driver.describe('RFC 0063 §C', 'an `accept` approval MUST merge the child outputs'),
+    ).toBe(true);
+
+    const rejected = await invokeSubRunAttest({ ...base, approvalAction: 'reject' });
+    if (rejected === null) return;
+    expect(
+      rejected.merged,
+      driver.describe('RFC 0063 §C', 'a `reject` approval MUST NOT merge the child outputs'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/subrun-attestation-shape.test.ts

@@ -0,0 +1,30 @@
+/**
+ * subrun-attestation-shape — RFC 0063 §A. The `capabilities.agents.subRunAttestation`
+ * advertisement flag is either absent or a boolean.
+ *
+ * Status: ACTIVE (advertisement-shape; always runs). Behavioral coverage lives
+ * in the sibling subrun-*.test.ts scenarios, gated on the flag + the host
+ * sub-run attestation seam.
+ *
+ * @see RFCS/0063-subrun-output-attestation-and-merge-gating.md §A
+ * @see spec/v1/node-packs.md §"`outputAttestation` — verify-before-merge"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readSubRunAttestationCap } from '../lib/subRunAttestation.js';
+
+describe('subrun-attestation-shape: advertisement (RFC 0063 §A)', () => {
+  it('capabilities.agents.subRunAttestation is absent or a boolean', async () => {
+    const cap = await readSubRunAttestationCap();
+    // null = unadvertised (no agents block OR flag omitted) — valid.
+    if (cap === null) return;
+    expect(
+      typeof cap,
+      driver.describe(
+        'capabilities.schema.json §agents.subRunAttestation',
+        'agents.subRunAttestation MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});

package/src/scenarios/subrun-checksum-stable.test.ts

@@ -0,0 +1,43 @@
+/**
+ * subrun-checksum-stable — RFC 0063 §B. A child's output checksum is byte-stable
+ * for identical outputs and host-independent (the RFC 8785 JCS + SHA-256 recipe
+ * pinned in replay.md), and is surfaced as the `attestation` object on the
+ * existing `core.workflowChain.event { phase: 'output.harvested' }`.
+ *
+ * Gated on `capabilities.agents.subRunAttestation` + the host sub-run attestation
+ * seam; soft-skips when either is absent.
+ *
+ * @see RFCS/0063-subrun-output-attestation-and-merge-gating.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readSubRunAttestationCap, invokeSubRunAttest } from '../lib/subRunAttestation.js';
+
+describe('subrun-checksum-stable (RFC 0063 §B)', () => {
+  it('identical child outputs produce an identical sha256 attestation checksum', async () => {
+    if ((await readSubRunAttestationCap()) !== true) return;
+    const childOutputs = { report: 'done', score: 0.9, tags: ['a', 'b'] };
+    const a = await invokeSubRunAttest({ childOutputs, outputAttestation: { checksum: true } });
+    if (a === null) return; // seam absent — soft-skip
+    // Key-reordered but value-identical: JCS canonicalization MUST yield the same hash.
+    const b = await invokeSubRunAttest({
+      childOutputs: { tags: ['a', 'b'], score: 0.9, report: 'done' },
+      outputAttestation: { checksum: true },
+    });
+    if (b === null) return;
+    const att = a.attestation ?? {};
+    expect(
+      typeof att.checksum === 'string' && (att.checksum as string).length > 0,
+      driver.describe('RFC 0063 §B', 'output.harvested MUST carry a non-empty attestation.checksum when checksum:true'),
+    ).toBe(true);
+    expect(
+      att.algorithm,
+      driver.describe('RFC 0063 §B', 'attestation.algorithm MUST be "sha256" (the v1 recipe)'),
+    ).toBe('sha256');
+    expect(
+      (b.attestation ?? {}).checksum,
+      driver.describe('RFC 0063 §B', 'JCS canonicalization MUST make the checksum invariant to key order — same content, same hash'),
+    ).toBe(att.checksum);
+  });
+});

package/src/scenarios/tool-hooks-authorization-fail-closed.test.ts

@@ -0,0 +1,39 @@
+/**
+ * tool-hooks-authorization-fail-closed — RFC 0064 §C. A principal lacking a
+ * tool's required scope (or whose authorization cannot be evaluated) gets
+ * `agent.toolReturned { status: 'forbidden' }` and the tool is never invoked —
+ * the per-tool application of RFC 0049's `authorization-fail-closed` invariant.
+ *
+ * Gated on `capabilities.toolHooks.perToolAuthorization` + the host tool-hooks
+ * seam; soft-skips when either is absent.
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §C
+ * @see SECURITY/invariants.yaml — authorization-fail-closed (RFC 0049, reused)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap, invokeToolHook } from '../lib/toolHooks.js';
+
+describe('tool-hooks-authorization-fail-closed (RFC 0064 §C)', () => {
+  it('a principal lacking a tool scope is denied and the tool is not invoked', async () => {
+    const cap = await readToolHooksCap();
+    if (cap?.perToolAuthorization !== true) return;
+    // A principal with no scopes against a tool requiring one MUST be denied.
+    const res = await invokeToolHook({
+      principal: 'conformance-unprivileged',
+      toolName: 'db.delete',
+      requiredScopes: ['db:write'],
+      args: {},
+    });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      (res.toolReturned ?? {}).status,
+      driver.describe('RFC 0064 §C', 'a missing/unevaluable tool scope MUST fail closed → status:"forbidden"'),
+    ).toBe('forbidden');
+    expect(
+      (res.toolReturned ?? {}).durationMs,
+      driver.describe('RFC 0064 §C', 'a forbidden call never starts, so durationMs MUST be absent'),
+    ).toBeUndefined();
+  });
+});

package/src/scenarios/tool-hooks-content-free.test.ts

@@ -0,0 +1,40 @@
+/**
+ * tool-hooks-content-free — RFC 0064 §B. When `prePostEvents`, a tool call's
+ * `agent.toolCalled` carries `argsHash` (the content-free, SIEM-safe
+ * alternative to raw `inputs`) + `agent.toolReturned` carries `status` +
+ * `durationMs`.
+ *
+ * Gated on `capabilities.toolHooks.prePostEvents` + the host tool-hooks seam;
+ * soft-skips when either is absent.
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap, invokeToolHook } from '../lib/toolHooks.js';
+
+describe('tool-hooks-content-free (RFC 0064 §B)', () => {
+  it('toolCalled carries argsHash; toolReturned carries status + durationMs', async () => {
+    const cap = await readToolHooksCap();
+    if (cap?.prePostEvents !== true) return;
+    const res = await invokeToolHook({ principal: 'core.system', toolName: 'web.search', args: { q: 'openwop' } });
+    if (res === null) return; // seam absent — soft-skip
+    const called = res.toolCalled ?? {};
+    const returned = res.toolReturned ?? {};
+    expect(
+      typeof called.argsHash === 'string' && (called.argsHash as string).length > 0,
+      driver.describe('RFC 0064 §B', 'agent.toolCalled MUST carry a non-empty argsHash when prePostEvents'),
+    ).toBe(true);
+    expect(
+      ['ok', 'error', 'forbidden', 'rate_limited'].includes(returned.status as string),
+      driver.describe('RFC 0064 §B', 'agent.toolReturned MUST carry a tool-hooks status'),
+    ).toBe(true);
+    if (returned.status === 'ok') {
+      expect(
+        typeof returned.durationMs === 'number' && (returned.durationMs as number) >= 0,
+        driver.describe('RFC 0064 §B', 'a completed tool call MUST record a non-negative durationMs'),
+      ).toBe(true);
+    }
+  });
+});

package/src/scenarios/tool-hooks-rate-limit.test.ts

@@ -0,0 +1,32 @@
+/**
+ * tool-hooks-rate-limit — RFC 0064 §D. Exhausting a `(principal, tool)` token
+ * bucket → `agent.toolReturned { status: 'rate_limited' }` and the tool is not
+ * invoked, surfacing the existing `rate_limited` (429) error.
+ *
+ * Gated on `capabilities.toolHooks.perToolRateLimit` + the host tool-hooks
+ * seam; soft-skips when either is absent.
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §D
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap, invokeToolHook } from '../lib/toolHooks.js';
+
+describe('tool-hooks-rate-limit (RFC 0064 §D)', () => {
+  it('an exhausted (principal, tool) bucket yields status:"rate_limited"', async () => {
+    const cap = await readToolHooksCap();
+    if (cap?.perToolRateLimit !== true) return;
+    const res = await invokeToolHook({
+      principal: 'core.system',
+      toolName: 'web.search',
+      args: { q: 'x' },
+      simulateRateLimitExhausted: true,
+    });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      (res.toolReturned ?? {}).status,
+      driver.describe('RFC 0064 §D', 'an exhausted token bucket MUST yield status:"rate_limited" without invoking the tool'),
+    ).toBe('rate_limited');
+  });
+});

package/src/scenarios/tool-hooks-secret-redaction.test.ts

@@ -0,0 +1,34 @@
+/**
+ * tool-hooks-secret-redaction — RFC 0064 §B/§E. A tool arg containing a
+ * resolved secret is redacted (SR-1) before hashing; the raw value never
+ * appears in `argsHash` or anywhere in the emitted `agent.toolCalled` /
+ * `agent.toolReturned` pair.
+ *
+ * Gated on `capabilities.toolHooks.prePostEvents` + the host tool-hooks seam;
+ * soft-skips when either is absent.
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §B (argsHash SR-1 redaction), §E (credentials)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap, invokeToolHook } from '../lib/toolHooks.js';
+
+const CANARY = 'sk-canary-rfc0064-do-not-leak-xyz789';
+
+describe('tool-hooks-secret-redaction (RFC 0064 §E)', () => {
+  it('a secret-shaped tool arg never appears in the emitted events', async () => {
+    const cap = await readToolHooksCap();
+    if (cap?.prePostEvents !== true) return;
+    const res = await invokeToolHook({
+      principal: 'core.system',
+      toolName: 'web.search',
+      args: { apiKey: CANARY, q: 'openwop' },
+    });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      JSON.stringify(res).includes(CANARY),
+      driver.describe('RFC 0064 §B', 'a resolved secret MUST be redacted before hashing; the raw value MUST NOT appear in argsHash or any emitted field (SR-1)'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/tool-hooks-shape.test.ts

@@ -0,0 +1,34 @@
+/**
+ * tool-hooks-shape — RFC 0064 §A. The `capabilities.toolHooks` advertisement
+ * block is either absent or a well-formed object.
+ *
+ * Status: ACTIVE (advertisement-shape; always runs). Behavioral coverage lives
+ * in the sibling tool-hooks-*.test.ts scenarios, gated on the sub-flags + the
+ * host tool-hooks seam.
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §A
+ * @see spec/v1/host-capabilities.md §host.toolHooks
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap } from '../lib/toolHooks.js';
+
+describe('tool-hooks-shape: advertisement (RFC 0064 §A)', () => {
+  it('capabilities.toolHooks is absent or a well-formed object', async () => {
+    const cap = await readToolHooksCap();
+    if (cap === null) return; // not advertised — valid
+    expect(
+      typeof cap.supported,
+      driver.describe('capabilities.schema.json §toolHooks', 'toolHooks.supported MUST be a boolean when the block is present'),
+    ).toBe('boolean');
+    for (const k of ['prePostEvents', 'perToolAuthorization', 'perToolRateLimit'] as const) {
+      if (cap[k] !== undefined) {
+        expect(
+          typeof cap[k],
+          driver.describe('capabilities.schema.json §toolHooks', `toolHooks.${k} MUST be a boolean when present`),
+        ).toBe('boolean');
+      }
+    }
+  });
+});

package/src/scenarios/wasm-pack-abi-version-rejection.test.ts

@@ -26,6 +26,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const MISBEHAVING_PACK_NAME = 'vendor.openwop.misbehaving-abi';
 const WELL_BEHAVED_PACK_NAME = 'vendor.openwop.rust-hello';
@@ -34,9 +35,7 @@ describe('wasm-pack-abi-version-rejection: host advertises supported ABI version
   it('abiVersions[] contains positive integers; loader rejects unsupported versions', async () => {
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean; abiVersions?: unknown } } };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 
@@ -62,13 +61,7 @@ describe('wasm-pack-abi-version-rejection: positive path via misbehaving pack',
   it('misbehaving-abi pack (declares ABI 999) MUST NOT appear in loadedPacks[]', async () => {
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: {
-          nodePackRuntimes?: {
-            wasm?: { supported?: boolean; loadedPacks?: unknown };
-          };
-        };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 

package/src/scenarios/wasm-pack-invoke-completed.test.ts

@@ -16,14 +16,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const FIXTURE = 'conformance-wasm-pack-roundtrip';
 
 async function isWasmSupported(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
   return Boolean(
-    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } } })
-      .capabilities?.nodePackRuntimes?.wasm?.supported,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

package/src/scenarios/wasm-pack-invoke-suspended.test.ts

@@ -20,14 +20,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const FIXTURE = 'conformance-wasm-pack-roundtrip';
 
 async function isWasmSupported(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
   return Boolean(
-    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } } })
-      .capabilities?.nodePackRuntimes?.wasm?.supported,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

package/src/scenarios/wasm-pack-load.test.ts

@@ -15,6 +15,7 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const FIXTURE = 'conformance-wasm-pack-roundtrip';
 
@@ -28,8 +29,7 @@ interface WasmCaps {
 async function getWasmCaps(): Promise<WasmCaps | null> {
   const disco = await driver.get('/.well-known/openwop');
   const caps =
-    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: WasmCaps } } })
-      .capabilities?.nodePackRuntimes?.wasm ?? null;
+    capabilityFamily<{ wasm?: WasmCaps }>(disco.json, 'nodePackRuntimes')?.wasm ?? null;
   return caps;
 }
 

package/src/scenarios/wasm-pack-memory-cap.test.ts

@@ -26,6 +26,7 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const CAP_BREACH_FIXTURE = 'conformance-wasm-pack-memory-cap-breach';
 
@@ -33,9 +34,7 @@ describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
   it('capabilities.nodePackRuntimes.wasm.maxMemoryBytes is a plausible number', async () => {
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean; maxMemoryBytes?: unknown } } };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 
@@ -64,9 +63,7 @@ describe('wasm-pack-memory-cap: positive path via misbehaving pack', () => {
     }
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
     if (!wasm?.supported) return;
 
     const create = await driver.post('/v1/runs', {

package/src/scenarios/wasm-pack-replay-determinism.test.ts

@@ -14,14 +14,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const FIXTURE = 'conformance-wasm-pack-roundtrip';
 
 async function isWasmSupported(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
   return Boolean(
-    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } } })
-      .capabilities?.nodePackRuntimes?.wasm?.supported,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

package/src/scenarios/workflow-primary-output-annotation.test.ts

@@ -0,0 +1,142 @@
+/**
+ * workflow-primary-output-annotation — RFC 0065 schema shape conformance.
+ *
+ * Server-free schema assertions that the optional `outputRole` field on
+ * `WorkflowNode` is exactly that — optional, additive, and a closed enum:
+ *   1. A WorkflowDefinition with one node declaring `outputRole: "primary"`
+ *      and another declaring `outputRole: "secondary"` validates.
+ *   2. A WorkflowDefinition with the field absent (legacy shape) still
+ *      validates — preserves the additive promise.
+ *   3. An unknown `outputRole` value is rejected by the closed enum.
+ *   4. The field set to a non-string is rejected.
+ *
+ * Always runs (pure on-disk Ajv2020 validation; no host involvement —
+ * the field has no engine-observable effect by design).
+ *
+ * @see RFCS/0065-workflow-node-primary-output-annotation.md
+ * @see schemas/workflow-definition.schema.json ($defs.WorkflowNode.outputRole)
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+function compileWorkflowDefinition(): ReturnType<Ajv2020['compile']> {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  // Register cross-file `$ref` targets — same pattern as
+  // `fixtures-valid.test.ts`. Without these, Ajv throws
+  // `missingRef` when compiling `workflow-definition.schema.json`
+  // because it references agent-ref + prompt-ref by URL.
+  const agentRefSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'agent-ref.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  const promptRefSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'prompt-ref.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  const promptKindSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'prompt-kind.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  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(join(SCHEMAS_DIR, 'workflow-definition.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  return ajv.compile(schema);
+}
+
+/** Build the minimal-required shape of a WorkflowDefinition. Tests
+ *  inject per-case node overrides via the `nodes` arg. */
+function baseDefinition(nodes: Array<Record<string, unknown>>): Record<string, unknown> {
+  return {
+    id: 'wf-test',
+    name: 'Test',
+    version: '1.0.0',
+    nodes,
+    edges: [],
+    triggers: [],
+    variables: [],
+    metadata: { createdAt: '2026-05-25T00:00:00Z' },
+    settings: {},
+  };
+}
+
+function baseNode(id: string, extras: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id,
+    typeId: 'core.test.noop',
+    name: id,
+    position: { x: 0, y: 0 },
+    config: {},
+    inputs: {},
+    ...extras,
+  };
+}
+
+describe('workflow-primary-output-annotation: outputRole shape (RFC 0065)', () => {
+  const validate = compileWorkflowDefinition();
+
+  it('accepts a workflow with one node declaring outputRole="primary"', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('accepts primary AND secondary annotations on different nodes', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b', { outputRole: 'secondary' }),
+      baseNode('c'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('accepts a workflow with the field absent (additive promise)', () => {
+    const def = baseDefinition([
+      baseNode('a'),
+      baseNode('b'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('rejects an unknown outputRole enum value', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'tertiary' }),
+    ]);
+    const ok = validate(def);
+    expect(ok).toBe(false);
+    expect(validate.errors).toBeTruthy();
+  });
+
+  it('rejects outputRole set to a non-string', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 1 }),
+    ]);
+    const ok = validate(def);
+    expect(ok).toBe(false);
+  });
+
+  it('permits multiple nodes declaring outputRole="primary" (tooling decides)', () => {
+    // The schema doesn't reject multiple primaries — tooling MAY pick
+    // any (lexicographic node id is the RFC's recommended tiebreaker).
+    // This test pins that the schema-layer doesn't enforce uniqueness,
+    // matching the RFC's "schema permits N primaries" promise.
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b', { outputRole: 'primary' }),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+});