@openwop/openwop-conformance 1.2.0 → 1.4.0

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

@@ -16,20 +16,30 @@ import { FIXTURES_DIR, SCHEMAS_DIR } from '../lib/paths.js';
 // checkouts (schemas one level above the conformance package) and the
 // published tarball (schemas vendored at the package root by `prepack`).
 const PACK_MANIFEST_FIXTURES_DIR = join(FIXTURES_DIR, 'pack-manifests');
+const PROMPT_TEMPLATE_FIXTURES_DIR = join(FIXTURES_DIR, 'prompt-templates');
 const SCHEMA_PATH = join(SCHEMAS_DIR, 'workflow-definition.schema.json');
 const PACK_MANIFEST_SCHEMA_PATH = join(SCHEMAS_DIR, 'node-pack-manifest.schema.json');
+const PROMPT_TEMPLATE_SCHEMA_PATH = join(SCHEMAS_DIR, 'prompt-template.schema.json');
 
 describe('fixtures: workflow-definition schema validity', () => {
   const ajv = new Ajv2020({ allErrors: true, strict: false });
   addFormats(ajv);
-  // Pre-load the agent-ref peer schema so cross-schema `$ref` in
-  // workflow-definition (Phase 1 — `WorkflowNode.agent`) resolves.
-  // The relative file-name `agent-ref.schema.json` is how
-  // workflow-definition references it; register under that name so
-  // Ajv's $ref resolver finds it.
-  const agentRefPath = join(SCHEMAS_DIR, 'agent-ref.schema.json');
-  const agentRefSchema = JSON.parse(readFileSync(agentRefPath, 'utf8'));
+  // 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);
 
@@ -85,14 +95,19 @@ describe('fixtures: node-pack-manifest schema validity', () => {
   // `private.<host>.*` scope is accepted by the canonical schema).
   const ajv = new Ajv2020({ allErrors: true, strict: false });
   addFormats(ajv);
-  // Pre-load the agent-manifest peer schema so the Phase 2 `agents[]`
-  // $ref in node-pack-manifest resolves under the same name the
-  // manifest schema uses.
-  const agentManifestPath = join(SCHEMAS_DIR, 'agent-manifest.schema.json');
-  ajv.addSchema(
-    JSON.parse(readFileSync(agentManifestPath, 'utf8')),
-    'agent-manifest.schema.json',
-  );
+  // Pre-load peer schemas. agent-manifest references prompt-ref (RFC 0029
+  // §B `AgentManifest.promptOverrides[kind]` + `promptLibraryRef`); prompt-ref
+  // transitively references prompt-kind. Register each under both the
+  // canonical $id and the relative file name so Ajv resolves either way
+  // the consumer schema spelled the ref.
+  const agentManifestSchema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'agent-manifest.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(agentManifestSchema, 'agent-manifest.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(PACK_MANIFEST_SCHEMA_PATH, 'utf8'));
   const validate = ajv.compile(schema);
 
@@ -138,3 +153,96 @@ describe('fixtures: node-pack-manifest schema validity', () => {
     ).toBeGreaterThan(0);
   });
 });
+
+describe('fixtures: prompt-template schema validity', () => {
+  // PromptTemplate fixtures live in `fixtures/prompt-templates/` per
+  // RFC 0027 §A. Like pack manifests, they're schema-level proof points,
+  // not seeded into a workflow store. They exist so the conformance
+  // suite has canonical positive fixtures for the prompt-template-shape
+  // scenario, and so future RFCs (0028 prompt packs, 0029 resolution
+  // chain) can reference a stable fixture set.
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  // Pre-load prompt-kind so the cross-schema `$ref` in
+  // prompt-template.schema.json resolves. The template references
+  // prompt-kind via `./prompt-kind.schema.json` (relative URI; see
+  // RFC 0027 commit notes for the redocly compatibility rationale).
+  // Register under both the canonical `$id` and the relative form so
+  // Ajv resolves either way.
+  const promptKindPath = join(SCHEMAS_DIR, 'prompt-kind.schema.json');
+  const promptKindSchema = JSON.parse(readFileSync(promptKindPath, 'utf8'));
+  ajv.addSchema(promptKindSchema, 'prompt-kind.schema.json');
+  ajv.addSchema(promptKindSchema, './prompt-kind.schema.json');
+  const schema = JSON.parse(readFileSync(PROMPT_TEMPLATE_SCHEMA_PATH, 'utf8'));
+  const validate = ajv.compile(schema);
+
+  const files = readdirSync(PROMPT_TEMPLATE_FIXTURES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .sort();
+
+  it('finds at least one prompt-template fixture', () => {
+    expect(
+      files.length,
+      'Expected at least one PromptTemplate fixture under fixtures/prompt-templates/',
+    ).toBeGreaterThan(0);
+  });
+
+  for (const file of files) {
+    it(`prompt-templates/${file} validates against prompt-template.schema.json`, () => {
+      const data = JSON.parse(
+        readFileSync(join(PROMPT_TEMPLATE_FIXTURES_DIR, file), 'utf8'),
+      );
+      const ok = validate(data);
+      const errors = (validate.errors ?? [])
+        .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
+        .join('\n');
+      expect(
+        ok,
+        `Fixture prompt-templates/${file} fails prompt-template schema:\n${errors}`,
+      ).toBe(true);
+    });
+  }
+
+  it('every fixture templateId matches its filename', () => {
+    // Filename convention: `<templateId-dot-form-with-dots-as-dashes>.json`.
+    // The fixture set uses dot-prefixed templateIds (e.g.,
+    // `conformance.prompt.writer-system`) which map directly to filenames
+    // with dots preserved (`conformance-prompt-writer-system.json`). The
+    // file→id mapping is loose (the suite doesn't enforce it) but we
+    // assert templateId presence so each fixture is self-describing.
+    for (const file of files) {
+      const data = JSON.parse(
+        readFileSync(join(PROMPT_TEMPLATE_FIXTURES_DIR, file), 'utf8'),
+      ) as { templateId: string };
+      expect(
+        typeof data.templateId,
+        `Fixture prompt-templates/${file} MUST declare a templateId`,
+      ).toBe('string');
+      expect(data.templateId.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every secret-source variable lives in a fixture tagged for the secret-redaction scenario', () => {
+    // SECURITY regression pin: a fixture that declares a `secret`-source
+    // variable but isn't visible to the prompt-composed-secret-redaction
+    // scenario could mask a redaction failure. We require every
+    // fixture carrying secret-source variables to advertise the
+    // `secret-redaction` tag so the scenario discovers it.
+    for (const file of files) {
+      const data = JSON.parse(
+        readFileSync(join(PROMPT_TEMPLATE_FIXTURES_DIR, file), 'utf8'),
+      ) as {
+        templateId: string;
+        variables?: Array<{ name: string; source?: string }>;
+        tags?: string[];
+      };
+      const hasSecretSource = (data.variables ?? []).some((v) => v.source === 'secret');
+      if (hasSecretSource) {
+        expect(
+          (data.tags ?? []).includes('secret-redaction'),
+          `Fixture prompt-templates/${file} declares a secret-source variable but lacks the 'secret-redaction' tag`,
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/scenarios/kv-ttl-expiry.test.ts

@@ -1,12 +1,12 @@
 /**
- * kv-ttl-expiry — RFC 0015 advertisement-shape verification + behavioral placeholders.
+ * kv-ttl-expiry — RFC 0015 advertisement-shape verification + behavioral roundtrip.
  *
- * Status: ACTIVE (advertisement-shape). RFC 0015 promoted to `Active`
- * 2026-05-17. The matching `capabilities.kvStorage` block has landed in
- * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
- * shape against any host that boots the conformance suite, and keeps the
- * deeper behavioral assertions as `it.todo()` until a reference host wires
- * a test seam.
+ * Status: ACTIVE (advertisement-shape + behavioral). RFC 0015 promoted to
+ * `Active` 2026-05-17. The matching `capabilities.kvStorage` block has
+ * landed in `schemas/capabilities.schema.json`. This scenario asserts the
+ * advertisement shape against any host that boots the conformance suite, and
+ * exercises the behavioral surface through the `/v1/host/sample/test/surface`
+ * seam (soft-skip with HTTP 404 on hosts that don't expose it).
  *
  * Summary: TTL honored with at most a 1-second drift on expiry visibility.
  *
@@ -42,6 +42,37 @@ describe('kv-ttl-expiry: advertisement shape (RFC 0015)', () => {
   });
 });
 
-describe('kv-ttl-expiry: behavioral assertions (placeholders — need host test seam)', () => {
-  it.todo("set with ttl=2 → get at t+1 returns the value; get at t+3 returns not-found");
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'kv', op, args });
+}
+
+describe('kv-ttl-expiry: behavioral (RFC 0015 §B point 3 — 1s TTL drift)', () => {
+  it('set with ttlSeconds=2 → get before expiry returns value; get after expiry returns found:false', async () => {
+    const probe = await call('get', { key: '__ttl-probe__' });
+    if (probe.status === 404) return; // host doesn't expose the seam
+    const key = `ttl-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const setRes = await call('set', { key, value: 'expires-soon', ttlSeconds: 2 });
+    expect(setRes.status).toBe(200);
+
+    // Read within the window
+    const within = await call('get', { key });
+    expect(within.status).toBe(200);
+    const withinBody = within.json as { value?: unknown; found?: boolean };
+    expect(
+      withinBody.value,
+      driver.describe('RFC 0015 §B point 3', 'get within TTL window MUST return the stored value'),
+    ).toBe('expires-soon');
+    expect(withinBody.found).toBe(true);
+
+    // Wait past expiry (2s TTL + 1s drift allowance per RFC 0015 §B point 3)
+    await new Promise((r) => setTimeout(r, 3000));
+
+    const after = await call('get', { key });
+    expect(after.status).toBe(200);
+    const afterBody = after.json as { value?: unknown; found?: boolean };
+    expect(
+      afterBody.found,
+      driver.describe('RFC 0015 §B point 3', 'get after TTL expiry MUST surface as found:false (≤1s drift)'),
+    ).toBe(false);
+  });
 });

package/src/scenarios/model-capability-insufficient.test.ts

@@ -0,0 +1,221 @@
+/**
+ * model-capability-insufficient — RFC 0031 §B step 4 + §D runtime behavior.
+ *
+ * Capability-gated on `capabilities.modelCapabilities.supported: true`.
+ * Drives the host's `POST /v1/host/sample/test/evaluate-model-capability-gate`
+ * seam through the refusal branches of the §B 4-step dispatch flow.
+ *
+ * @see RFCS/0031-envelope-variants-and-model-capabilities.md §B step 4 + §D
+ * @see schemas/run-event-payloads.schema.json §modelCapabilityInsufficient
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface GateResponse {
+  outcome?: {
+    route?: 'dispatch' | 'substitute' | 'refuse';
+    missingCapabilities?: string[];
+    fallbackAttempted?: boolean;
+  };
+  event?: { type?: string; payload?: Record<string, unknown> } | null;
+}
+
+async function evaluateGate(input: Record<string, unknown>): Promise<{ status: number; body: GateResponse }> {
+  const res = await driver.post('/v1/host/sample/test/evaluate-model-capability-gate', input);
+  return { status: res.status, body: res.json as GateResponse };
+}
+
+describe.skipIf(HTTP_SKIP)('model-capability-insufficient: dispatch refusal (RFC 0031 §B step 4 + §D)', () => {
+  it('unmet + NO fallbackModel declared → refuse with fallbackAttempted: false', async () => {
+    const r = await evaluateGate({
+      module: { requiredModelCapabilities: ['structured-output', 'reasoning'] },
+      // no fallbackModel
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: true,
+      supportedProviders: ['unknown-vendor'],
+      nodeId: 'editor-node',
+    });
+    if (r.status === 404) return;
+    expect(
+      r.body.outcome?.route,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 4',
+        'unmet capability + no fallbackModel declared → host MUST refuse',
+      ),
+    ).toBe('refuse');
+    expect(
+      r.body.outcome?.fallbackAttempted,
+      driver.describe(
+        'schemas/run-event-payloads.schema.json §modelCapabilityInsufficient',
+        'fallbackAttempted MUST be false when no fallbackModel was declared on the NodeModule',
+      ),
+    ).toBe(false);
+    expect(
+      r.body.event?.type,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §D',
+        'refuse path MUST emit `model.capability.insufficient` BEFORE the node failure',
+      ),
+    ).toBe('model.capability.insufficient');
+    const payload = (r.body.event?.payload ?? {}) as Record<string, unknown>;
+    expect(payload.nodeId).toBe('editor-node');
+    expect(payload.provider).toBe('unknown-vendor');
+    expect(payload.fallbackAttempted).toBe(false);
+    expect(Array.isArray(payload.missingCapabilities)).toBe(true);
+  });
+
+  it('unmet + fallback declared but provider NOT in supportedProviders → refuse with fallbackAttempted: true', async () => {
+    const r = await evaluateGate({
+      module: {
+        requiredModelCapabilities: ['structured-output'],
+        fallbackModel: { provider: 'unauthenticated-vendor', model: 'foo' },
+      },
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: true,
+      // Fallback's provider is NOT in supportedProviders — host cannot
+      // authenticate per RFC 0031 §B step 3 final clause.
+      supportedProviders: ['anthropic', 'unknown-vendor'],
+    });
+    if (r.status === 404) return;
+    expect(r.body.outcome?.route).toBe('refuse');
+    expect(
+      r.body.outcome?.fallbackAttempted,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 3',
+        'fallback provider NOT in capabilities.aiProviders.supported[] → host cannot authenticate → fallbackAttempted MUST be true (the attempt failed at credential resolution)',
+      ),
+    ).toBe(true);
+    expect(r.body.event?.type).toBe('model.capability.insufficient');
+  });
+
+  it('unmet + substitutionSupported: false (host posture) → refuse with fallbackAttempted: false', async () => {
+    const r = await evaluateGate({
+      module: {
+        requiredModelCapabilities: ['structured-output'],
+        fallbackModel: { provider: 'anthropic', model: 'claude-opus-4-7' },
+      },
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: false,
+      supportedProviders: ['anthropic', 'unknown-vendor'],
+    });
+    if (r.status === 404) return;
+    expect(r.body.outcome?.route).toBe('refuse');
+    expect(
+      r.body.outcome?.fallbackAttempted,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §E',
+        'capabilities.modelCapabilities.substitutionSupported: false → host MUST NOT attempt fallback even when NodeModule.fallbackModel is declared → fallbackAttempted MUST be false (no attempt was made)',
+      ),
+    ).toBe(false);
+  });
+
+  it('recursive fallback NOT permitted — fallback that itself fails capability check → refuse with fallbackAttempted: true', async () => {
+    // Construct a scenario where fallback's provider is in supportedProviders
+    // BUT the fallback provider itself doesn't advertise the required capability.
+    // The probe map's 'unknown-vendor-2' has empty capabilities; the gate
+    // refuses with fallbackAttempted: true (RFC 0031 §"Unresolved questions" #3).
+    const r = await evaluateGate({
+      module: {
+        requiredModelCapabilities: ['structured-output'],
+        fallbackModel: { provider: 'unknown-vendor-2', model: 'fallback-model' },
+      },
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: true,
+      supportedProviders: ['unknown-vendor', 'unknown-vendor-2'],
+    });
+    if (r.status === 404) return;
+    expect(r.body.outcome?.route).toBe('refuse');
+    expect(
+      r.body.outcome?.fallbackAttempted,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §"Unresolved questions" #3',
+        'recursive fallback NOT permitted — when the declared fallback model itself fails the capability check, host MUST refuse with fallbackAttempted: true (NOT chain to another fallback)',
+      ),
+    ).toBe(true);
+  });
+});
+
+// End-to-end pipeline: a fixture-declared workflow whose only node carries a
+// NodeModule with `requiredModelCapabilities: ['nonexistent-capability-9b3f']`
+// (registered as `conformance.modelCapability.insufficient` on the reference
+// host). The executor's model-capability gate at dispatch time refuses with
+// `capability_not_provided` AND emits `model.capability.insufficient` into
+// the run event log per RFC 0031 §D. Capability-gated AND fixture-gated:
+// soft-skips when either is absent.
+
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const E2E_FIXTURE = 'conformance-model-capability-insufficient';
+
+describe.skipIf(HTTP_SKIP)('model-capability-insufficient: end-to-end refusal through executor', () => {
+  it('workflow with a node declaring requiredModelCapabilities the active provider does not satisfy fails with RunSnapshot.error.code = "capability_not_provided" AND emits model.capability.insufficient into the run event log BEFORE node.failed', async () => {
+    if (!isFixtureAdvertised(E2E_FIXTURE)) return; // fixture not seeded — soft-skip
+
+    const create = await driver.post('/v1/runs', { workflowId: E2E_FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+    expect(terminal.status).toBe('failed');
+    expect(
+      (terminal as { error?: { code?: string } }).error?.code,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 4',
+        'unmet capability without viable fallback MUST fail with error.code = "capability_not_provided"',
+      ),
+    ).toBe('capability_not_provided');
+
+    const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    expect(eventsRes.status).toBe(200);
+    const events = ((eventsRes.json as { events?: Array<{ type: string }> } | undefined)?.events ?? []);
+    const insufficientIdx = events.findIndex((e) => e.type === 'model.capability.insufficient');
+    const nodeFailedIdx = events.findIndex((e) => e.type === 'node.failed');
+    expect(insufficientIdx, 'model.capability.insufficient MUST appear in the event log').toBeGreaterThanOrEqual(0);
+    expect(nodeFailedIdx, 'node.failed MUST appear in the event log').toBeGreaterThanOrEqual(0);
+    expect(
+      insufficientIdx < nodeFailedIdx,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §D',
+        'model.capability.insufficient MUST be emitted BEFORE node.failed (cause precedes effect)',
+      ),
+    ).toBe(true);
+  });
+
+  it('NO envelope emission occurs after the refusal (no node.completed, provider.usage, or envelope-reliability events)', async () => {
+    if (!isFixtureAdvertised(E2E_FIXTURE)) return; // fixture not seeded — soft-skip
+
+    const create = await driver.post('/v1/runs', { workflowId: E2E_FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+
+    const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const events = ((eventsRes.json as { events?: Array<{ type: string }> } | undefined)?.events ?? []);
+    const forbidden = [
+      'node.completed',
+      'provider.usage',
+      'envelope.retry.attempted',
+      'envelope.retry.exhausted',
+      'envelope.refusal',
+      'envelope.truncated',
+      'envelope.nlToFormat.engaged',
+      'envelope.recovery.applied',
+    ];
+    const leaked = events.filter((e) => forbidden.includes(e.type)).map((e) => e.type);
+    expect(
+      leaked,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 4',
+        'a refused dispatch MUST NOT emit any downstream envelope-emission events — the node never ran',
+      ),
+    ).toEqual([]);
+  });
+});

package/src/scenarios/model-capability-substituted.test.ts

@@ -0,0 +1,203 @@
+/**
+ * model-capability-substituted — RFC 0031 §B step 3 + §D + §F runtime behavior.
+ *
+ * Capability-gated on `capabilities.modelCapabilities.supported: true`.
+ *
+ * Drives the host's `POST /v1/host/sample/test/evaluate-model-capability-gate`
+ * seam with synthetic inputs that hit each branch of the §B 4-step dispatch
+ * flow. The seam runs the pure `evaluateModelCapabilityGate()` evaluator
+ * and returns both the routing outcome AND the event payload the host
+ * would emit. Conformance asserts the decision-matrix + the event payload
+ * shape per RFC 0031 §D `modelCapabilitySubstituted`.
+ *
+ * @see RFCS/0031-envelope-variants-and-model-capabilities.md §B + §D + §F
+ * @see spec/v1/host-capabilities.md §"Model-capability declarations"
+ * @see schemas/run-event-payloads.schema.json §modelCapabilitySubstituted
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface DiscoveryDoc {
+  capabilities?: {
+    modelCapabilities?: {
+      supported?: unknown;
+      substitutionSupported?: unknown;
+      advertised?: unknown;
+    };
+  };
+}
+
+interface GateOutcome {
+  route?: 'dispatch' | 'substitute' | 'refuse';
+  originalProvider?: string;
+  originalModel?: string;
+  fallbackProvider?: string;
+  fallbackModel?: string;
+  missingCapabilities?: string[];
+  fallbackAttempted?: boolean;
+}
+
+interface GateResponse {
+  outcome?: GateOutcome;
+  event?: { type?: string; payload?: Record<string, unknown> } | null;
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  try {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200) return null;
+    return res.json as DiscoveryDoc;
+  } catch {
+    return null;
+  }
+}
+
+async function evaluateGate(input: Record<string, unknown>): Promise<{ status: number; body: GateResponse }> {
+  const res = await driver.post('/v1/host/sample/test/evaluate-model-capability-gate', input);
+  return { status: res.status, body: res.json as GateResponse };
+}
+
+describe.skipIf(HTTP_SKIP)('model-capability-substituted: advertisement shape (RFC 0031 §E)', () => {
+  it('capabilities.modelCapabilities (when present) conforms to RFC 0031 §E', async () => {
+    const d = await readDiscovery();
+    if (d === null) return;
+    const mc = d.capabilities?.modelCapabilities;
+    if (mc === undefined) return;
+    expect(
+      typeof mc.supported,
+      driver.describe(
+        'schemas/capabilities.schema.json §modelCapabilities',
+        'capabilities.modelCapabilities.supported MUST be boolean when the block is advertised',
+      ),
+    ).toBe('boolean');
+    if (mc.advertised !== undefined) {
+      expect(
+        Array.isArray(mc.advertised),
+        driver.describe('RFCS/0031-envelope-variants-and-model-capabilities.md §E', 'modelCapabilities.advertised MUST be an array of capability identifiers'),
+      ).toBe(true);
+      const SPEC_RESERVED = ['structured-output', 'discriminator-enum', 'long-context', 'reasoning', 'function-calling'];
+      for (const id of mc.advertised as unknown[]) {
+        expect(typeof id, 'each advertised identifier MUST be a string').toBe('string');
+        const idStr = String(id);
+        const isReserved = SPEC_RESERVED.includes(idStr);
+        const isHostExt = /^x-host-[a-z][a-z0-9-]*-[a-z][a-z0-9-]*$/.test(idStr);
+        expect(
+          isReserved || isHostExt,
+          driver.describe(
+            'RFCS/0031-envelope-variants-and-model-capabilities.md §C',
+            `advertised identifier "${idStr}" MUST be spec-reserved (structured-output, discriminator-enum, long-context, reasoning, function-calling) or match the x-host-<host>-<key> extension pattern`,
+          ),
+        ).toBe(true);
+      }
+    }
+    if (mc.substitutionSupported !== undefined) {
+      expect(typeof mc.substitutionSupported, 'substitutionSupported MUST be boolean').toBe('boolean');
+    }
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('model-capability-substituted: dispatch behavior (RFC 0031 §B step 3 + §D)', () => {
+  it('all required capabilities met → outcome: dispatch (no event emitted)', async () => {
+    const r = await evaluateGate({
+      module: { requiredModelCapabilities: ['structured-output', 'function-calling'] },
+      activeProvider: 'anthropic',
+      activeModel: 'claude-3-5-sonnet',
+      substitutionSupported: true,
+      supportedProviders: ['anthropic', 'openai'],
+    });
+    if (r.status === 404) return; // host doesn't expose the seam
+    expect(
+      r.body.outcome?.route,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 2',
+        'all required model capabilities met → route MUST be "dispatch" (gate is a no-op)',
+      ),
+    ).toBe('dispatch');
+    expect(r.body.event, 'no event emitted when gate is a no-op').toBeNull();
+  });
+
+  it('unmet + fallback declared + authenticatable → outcome: substitute + event with originalProvider/originalModel/fallbackProvider/fallbackModel/missingCapabilities', async () => {
+    const r = await evaluateGate({
+      module: {
+        requiredModelCapabilities: ['structured-output', 'long-context'],
+        fallbackModel: { provider: 'anthropic', model: 'claude-opus-4-7' },
+      },
+      // Simulate an active provider that doesn't advertise long-context.
+      // The seam's probe map returns the spec-known capability set for
+      // known providers; we use an unknown provider id here so the gate
+      // sees an empty advertised set and refuses to substitute (no — wait,
+      // we declare a fallback that IS in supportedProviders, so the gate
+      // substitutes). Use 'unknown-vendor' as the original provider and
+      // 'anthropic' as the fallback (which IS in the host's known
+      // providers and advertises structured-output + long-context).
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: true,
+      supportedProviders: ['anthropic', 'openai', 'unknown-vendor'],
+      nodeId: 'writer-node',
+    });
+    if (r.status === 404) return;
+    expect(
+      r.body.outcome?.route,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §B step 3',
+        'unmet capability + declared fallback + fallback provider authenticatable → route MUST be "substitute"',
+      ),
+    ).toBe('substitute');
+    expect(
+      r.body.event?.type,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §D',
+        'substitute path MUST emit `model.capability.substituted`',
+      ),
+    ).toBe('model.capability.substituted');
+    const payload = (r.body.event?.payload ?? {}) as Record<string, unknown>;
+    expect(payload.nodeId, 'payload.nodeId MUST mirror the request').toBe('writer-node');
+    expect(payload.originalProvider).toBe('unknown-vendor');
+    expect(payload.originalModel).toBe('unknown-model');
+    expect(payload.fallbackProvider).toBe('anthropic');
+    expect(payload.fallbackModel).toBe('claude-opus-4-7');
+    expect(
+      Array.isArray(payload.missingCapabilities) &&
+        (payload.missingCapabilities as string[]).includes('structured-output'),
+      driver.describe(
+        'schemas/run-event-payloads.schema.json §modelCapabilitySubstituted',
+        'missingCapabilities[] MUST include the subset of required capabilities the active model did not satisfy',
+      ),
+    ).toBe(true);
+  });
+
+  it('unmet + substitutionSupported: false → outcome: refuse with fallbackAttempted: false (host posture override)', async () => {
+    const r = await evaluateGate({
+      module: {
+        requiredModelCapabilities: ['structured-output'],
+        // Fallback declared but the gate refuses BEFORE attempting because the
+        // host's posture is "no substitution" per RFC 0031 §E.
+        fallbackModel: { provider: 'anthropic', model: 'claude-opus-4-7' },
+      },
+      activeProvider: 'unknown-vendor',
+      activeModel: 'unknown-model',
+      substitutionSupported: false,
+      supportedProviders: ['anthropic', 'unknown-vendor'],
+    });
+    if (r.status === 404) return;
+    expect(
+      r.body.outcome?.route,
+      driver.describe(
+        'RFCS/0031-envelope-variants-and-model-capabilities.md §E',
+        'capabilities.modelCapabilities.substitutionSupported: false → host MUST refuse on any unmet capability even when NodeModule.fallbackModel is declared',
+      ),
+    ).toBe('refuse');
+    expect(r.body.event?.type).toBe('model.capability.insufficient');
+    expect(
+      (r.body.event?.payload as { fallbackAttempted?: boolean }).fallbackAttempted,
+      driver.describe(
+        'schemas/run-event-payloads.schema.json §modelCapabilityInsufficient',
+        'fallbackAttempted MUST be false when the refusal is driven by substitutionSupported: false (host posture, not fallback failure)',
+      ),
+    ).toBe(false);
+  });
+});