@openwop/openwop-conformance 1.6.1 → 1.10.0

package/src/lib/heartbeat.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared helper for the RFC 0060 host.heartbeat conformance scenarios.
+ * Lives in lib/ (not a *.test.ts) so scenarios import it via `../lib/heartbeat.js`.
+ */
+import { driver } from './driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+/** Reads `capabilities.heartbeat` from discovery; null when unadvertised. */
+export async function readHeartbeatCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const caps = (res.json as DiscoveryDoc | undefined)?.capabilities;
+  const hb = caps && typeof caps === 'object' ? (caps as Record<string, unknown>)['heartbeat'] : undefined;
+  return hb && typeof hb === 'object' ? (hb as Record<string, unknown>) : null;
+}
+
+/** True when the host advertises a working heartbeat surface. */
+export function heartbeatSupported(cap: Record<string, unknown> | null): boolean {
+  return cap?.['supported'] === true;
+}
+
+/** Drives one heartbeat tick via the host-sample seam, or null (soft-skip)
+ *  when the host doesn't expose it. The seam is host-extension surface —
+ *  hosts wiring RFC 0060 expose `POST /v1/host/sample/heartbeat/tick`. */
+export async function tickHeartbeat(body: Record<string, unknown>): Promise<{ status: number; json: unknown } | null> {
+  const res = await driver.post('/v1/host/sample/heartbeat/tick', body);
+  if (res.status === 404 || res.status === 405) return null; // seam absent — soft-skip
+  return { status: res.status, json: res.json };
+}

package/src/lib/memoryAttribution.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared helpers for the RFC 0057 memory write-attribution scenarios.
+ * Lives in lib/ (not a *.test.ts) so scenarios import it via `../lib/memoryAttribution.js`.
+ */
+import { driver } from './driver.js';
+import { isFixtureAdvertised } from './fixtures.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+/** Reads `capabilities.memory.attribution` from discovery; null when unadvertised. */
+export async function readMemoryAttributionCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const caps = (res.json as DiscoveryDoc | undefined)?.capabilities;
+  const mem = caps && typeof caps === 'object' ? (caps as Record<string, unknown>)['memory'] : undefined;
+  const attr = mem && typeof mem === 'object' ? (mem as Record<string, unknown>)['attribution'] : undefined;
+  return attr && typeof attr === 'object' ? (attr as Record<string, unknown>) : null;
+}
+
+/** True when the host commits to emitting `memory.written`. */
+export function emitsWriteEvents(cap: Record<string, unknown> | null): boolean {
+  return cap?.['supported'] === true && cap?.['emitsWriteEvents'] === true;
+}
+
+const SEED_FIXTURE = 'conformance-noop';
+
+/** Seeds a basic run (the host writes a run-summary on completion); null
+ *  (soft-skip) when the fixture isn't advertised or creation fails. */
+export async function seedRun(tenantId: string): Promise<string | null> {
+  if (!isFixtureAdvertised(SEED_FIXTURE)) return null;
+  const r = await driver.post('/v1/runs', { workflowId: SEED_FIXTURE, tenantId, inputs: {} });
+  if (r.status !== 200 && r.status !== 201) return null;
+  return (r.json as { runId?: string } | undefined)?.runId ?? null;
+}
+
+interface RunEventLike {
+  type: string;
+  runId?: string;
+  payload?: Record<string, unknown>;
+}
+
+/** Fetches a run's events and returns only the `memory.written` ones. */
+export async function memoryWrittenEvents(runId: string): Promise<RunEventLike[]> {
+  const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+  const events = (res.json as { events?: RunEventLike[] } | undefined)?.events ?? [];
+  return events.filter((e) => e.type === 'memory.written');
+}

package/src/lib/subRunAttestation.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared helper for the RFC 0063 sub-run output-attestation conformance
+ * scenarios. Lives in lib/ (not a *.test.ts) so scenarios import it via
+ * `../lib/subRunAttestation.js`.
+ */
+import { driver } from './driver.js';
+import { readCapabilityFamily } from './discovery-capabilities.js';
+
+/** Reads `agents.subRunAttestation` from discovery (root-first per RFC 0073);
+ *  null when the host advertises no `agents` block (treated as no support). */
+export async function readSubRunAttestationCap(): Promise<boolean | null> {
+  const agents = await readCapabilityFamily<Record<string, unknown>>('agents');
+  if (!agents || typeof agents !== 'object') return null;
+  const flag = agents['subRunAttestation'];
+  return flag === undefined ? null : flag === true;
+}
+
+interface AttestResult {
+  attestation?: { checksum?: unknown; algorithm?: unknown };
+  harvestedEvent?: Record<string, unknown>;
+  merged?: unknown;
+  mergedValues?: Record<string, unknown>;
+}
+
+/** Drives one sub-run harvest-then-merge via the host-sample seam, or null
+ *  (soft-skip) when the host doesn't expose it. The seam is host-extension
+ *  surface specified in host-sample-test-seams.md §"Open seams":
+ *  `POST /v1/host/sample/subrun/attest` returns the `attestation` the host
+ *  would surface on `core.workflowChain.event { phase: 'output.harvested' }`,
+ *  plus whether the merge proceeded. */
+export async function invokeSubRunAttest(body: Record<string, unknown>): Promise<AttestResult | null> {
+  const res = await driver.post('/v1/host/sample/subrun/attest', body);
+  if (res.status === 404 || res.status === 405) return null; // seam absent — soft-skip
+  return (res.json as AttestResult | undefined) ?? {};
+}

package/src/lib/toolHooks.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared helper for the RFC 0064 host.toolHooks conformance scenarios.
+ * Lives in lib/ (not a *.test.ts) so scenarios import it via `../lib/toolHooks.js`.
+ */
+import { driver } from './driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+/** Reads `capabilities.toolHooks` from discovery; null when unadvertised. */
+export async function readToolHooksCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const caps = (res.json as DiscoveryDoc | undefined)?.capabilities;
+  const th = caps && typeof caps === 'object' ? (caps as Record<string, unknown>)['toolHooks'] : undefined;
+  return th && typeof th === 'object' ? (th as Record<string, unknown>) : null;
+}
+
+interface ToolHookResult {
+  toolCalled?: Record<string, unknown>;
+  toolReturned?: Record<string, unknown>;
+}
+
+/** Drives one gated tool invocation via the host-sample seam, or null
+ *  (soft-skip) when the host doesn't expose it. The seam is host-extension
+ *  surface specified in host-sample-test-seams.md §"Open seams":
+ *  `POST /v1/host/sample/toolhooks/invoke` returns the `agent.toolCalled` /
+ *  `agent.toolReturned` payload pair the host would emit for the call. */
+export async function invokeToolHook(body: Record<string, unknown>): Promise<ToolHookResult | null> {
+  const res = await driver.post('/v1/host/sample/toolhooks/invoke', body);
+  if (res.status === 404 || res.status === 405) return null; // seam absent — soft-skip
+  return (res.json as ToolHookResult | undefined) ?? {};
+}

package/src/scenarios/agent-loop-iteration-monotonic.test.ts

@@ -0,0 +1,33 @@
+/**
+ * agent-loop-iteration-monotonic — RFC 0061 §B. Across a multi-turn loop,
+ * `runOrchestrator.decided.iteration` increments 1, 2, 3 … exactly once per turn
+ * (1-based, monotonic) — the observable counter `maxLoopIterations` bounds.
+ *
+ * Gated on `executionModel.version >= 5` + the host agent-loop seam; soft-skips
+ * when either is absent.
+ *
+ * @see RFCS/0061-agent-loop-lifecycle.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readExecutionModelCap, isVersion5, invokeAgentLoop } from '../lib/agentLoop.js';
+
+describe('agent-loop-iteration-monotonic (RFC 0061 §B)', () => {
+  it('iteration increments by exactly 1 per orchestrator turn, 1-based', async () => {
+    if (!isVersion5(await readExecutionModelCap())) return;
+    const res = await invokeAgentLoop({ turns: 3 });
+    if (res === null) return; // seam absent — soft-skip
+    const decisions = res.decisions ?? [];
+    expect(
+      decisions.length >= 1,
+      driver.describe('RFC 0061 §B', 'a multi-turn loop MUST emit one runOrchestrator.decided per turn'),
+    ).toBe(true);
+    const iterations = decisions.map((d) => d.iteration);
+    const expected = decisions.map((_, k) => k + 1);
+    expect(
+      JSON.stringify(iterations),
+      driver.describe('RFC 0061 §B', 'iteration MUST be 1-based + monotonic, incrementing by exactly 1 per turn'),
+    ).toBe(JSON.stringify(expected));
+  });
+});

package/src/scenarios/agent-loop-stateful-resume.test.ts

@@ -0,0 +1,28 @@
+/**
+ * agent-loop-stateful-resume — RFC 0061 §D. A loop suspended on a clarify/escalate
+ * HITL interrupt resumes at the SAME iteration — the counter does not reset or
+ * skip — with the snapshot lineage intact.
+ *
+ * Gated on `executionModel.statefulResume: true` + the host agent-loop seam;
+ * soft-skips when either is absent.
+ *
+ * @see RFCS/0061-agent-loop-lifecycle.md §D
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readExecutionModelCap, invokeAgentLoop } from '../lib/agentLoop.js';
+
+describe('agent-loop-stateful-resume (RFC 0061 §D)', () => {
+  it('a mid-loop suspend resumes at the same iteration, counter intact', async () => {
+    const em = await readExecutionModelCap();
+    if (em?.statefulResume !== true) return;
+    // Suspend at turn 2, then resume: the resumed iteration MUST be 2, not 1 or 3.
+    const res = await invokeAgentLoop({ turns: 4, suspendAtTurn: 2, resume: true });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.resumedIteration,
+      driver.describe('RFC 0061 §D', 'a stateful resume MUST continue at the suspend iteration — the counter does not reset or skip'),
+    ).toBe(2);
+  });
+});

package/src/scenarios/agent-loop-version5-shape.test.ts

@@ -0,0 +1,41 @@
+/**
+ * agent-loop-version5-shape — RFC 0061 §A/§B. The `executionModel.statefulResume`
+ * + `transcriptWindow` advertisement fields are well-formed when present, and a
+ * host advertising `version >= 5` carries a sane version ceiling.
+ *
+ * Status: ACTIVE (advertisement-shape; always runs). Behavioral coverage lives
+ * in the sibling agent-loop-*.test.ts scenarios, gated on `version >= 5` + the
+ * host agent-loop seam.
+ *
+ * @see RFCS/0061-agent-loop-lifecycle.md §A
+ * @see spec/v1/multi-agent-execution.md §"Stateful agent-loop lifecycle"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readExecutionModelCap } from '../lib/agentLoop.js';
+
+describe('agent-loop-version5-shape: advertisement (RFC 0061 §A)', () => {
+  it('executionModel.statefulResume/transcriptWindow are well-formed when present', async () => {
+    const em = await readExecutionModelCap();
+    if (em === null) return; // no execution model — valid
+    if (em.statefulResume !== undefined) {
+      expect(
+        typeof em.statefulResume,
+        driver.describe('capabilities.schema.json §multiAgent.executionModel', 'statefulResume MUST be a boolean when present'),
+      ).toBe('boolean');
+    }
+    if (em.transcriptWindow !== undefined) {
+      expect(
+        typeof em.transcriptWindow === 'number' && (em.transcriptWindow as number) >= 1,
+        driver.describe('capabilities.schema.json §multiAgent.executionModel', 'transcriptWindow MUST be a positive integer when present'),
+      ).toBe(true);
+    }
+    if (typeof em.version === 'number') {
+      expect(
+        (em.version as number) >= 1 && (em.version as number) <= 5,
+        driver.describe('capabilities.schema.json §multiAgent.executionModel', 'version MUST be within the 1–5 ladder'),
+      ).toBe(true);
+    }
+  });
+});

package/src/scenarios/agent-loop-workspace-snapshot.test.ts

@@ -0,0 +1,33 @@
+/**
+ * agent-loop-workspace-snapshot — RFC 0061 §C. A workspace PUT during turn i is
+ * invisible to turn i's snapshot and visible to turn i+1 — per-iteration
+ * snapshot immutability (writes land next turn, never retroactively).
+ *
+ * Gated on `executionModel.version >= 5` AND `host.workspace.supported` + the
+ * host agent-loop seam; soft-skips when any is absent.
+ *
+ * @see RFCS/0061-agent-loop-lifecycle.md §C
+ * @see RFCS/0059-agent-workspace.md §D — the workspace read snapshot
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readExecutionModelCap, isVersion5, hasWorkspace, invokeAgentLoop } from '../lib/agentLoop.js';
+
+describe('agent-loop-workspace-snapshot (RFC 0061 §C)', () => {
+  it('a turn-i workspace write is invisible to turn i, visible to turn i+1', async () => {
+    if (!isVersion5(await readExecutionModelCap())) return;
+    if (!(await hasWorkspace())) return; // workspace optional — soft-skip
+    const res = await invokeAgentLoop({ turns: 2, workspaceWriteAtTurn: 1 });
+    if (res === null) return; // seam absent — soft-skip
+    const vis = res.workspaceVisible ?? {};
+    expect(
+      vis.atWriteTurn,
+      driver.describe('RFC 0061 §C', 'a workspace write during turn i MUST be invisible to turn i\'s snapshot'),
+    ).toBe(false);
+    expect(
+      vis.atNextTurn,
+      driver.describe('RFC 0061 §C', 'a workspace write during turn i MUST be visible to turn i+1'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/agent-manifest-runtime.test.ts

@@ -0,0 +1,85 @@
+/**
+ * agent-manifest-runtime — RFC 0070. When a host advertises
+ * `capabilities.agents.manifestRuntime.supported`, it has loaded pack `agents[]`
+ * (RFC 0003) into an AgentRegistry and can dispatch a manifest agent on the
+ * existing core.dispatch/orchestrator loop, enforcing toolAllowlist (RFC 0002
+ * §A14) and confidence escalation (§F).
+ *
+ * The inventory leg is exercised against the NORMATIVE `GET /v1/agents` surface
+ * (RFC 0072 §A), so it runs black-box against any conformant host. The dispatch
+ * leg uses the sample-extension seam and soft-skips on hosts that don't expose
+ * it (full black-box dispatch is the sequenced executor-integration tier). Both
+ * legs gate on `capabilities.agents.manifestRuntime.supported`.
+ *
+ * @see RFCS/0070-agent-manifest-runtime.md, RFCS/0072-agent-inventory-and-dispatch.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readManifestRuntimeCap, listManifestAgents, dispatchAgent } from '../lib/agentRuntime.js';
+
+describe('agent-manifest-runtime (RFC 0070)', () => {
+  it('lists installed manifest agents and dispatches one with attributed events', async () => {
+    const cap = await readManifestRuntimeCap();
+    if (cap?.supported !== true) return; // unadvertised — soft-skip
+
+    // RFC 0074 §B — installScope governs how GET /v1/agents is scoped.
+    const installScope = typeof cap.installScope === 'string' ? cap.installScope : 'host';
+    expect(
+      installScope === 'host' || installScope === 'tenant',
+      driver.describe('RFC 0074 §B', "agents.manifestRuntime.installScope (when present) MUST be 'host' or 'tenant'"),
+    ).toBe(true);
+
+    const inv = await listManifestAgents();
+    if (inv === null) return; // seam absent — soft-skip
+    const agents = inv.agents ?? [];
+    expect(
+      Array.isArray(agents),
+      driver.describe('RFC 0072 §A', 'GET /v1/agents MUST return an agents[] array'),
+    ).toBe(true);
+
+    if (installScope === 'host') {
+      // Host-global inventory (RFC 0072 §A): a manifestRuntime host MUST surface ≥1 agent.
+      expect(
+        agents.length > 0,
+        driver.describe('RFC 0070 §A', 'a host-scoped manifestRuntime host MUST surface ≥1 installed manifest agent'),
+      ).toBe(true);
+    } else if (agents.length === 0) {
+      // RFC 0074 §A + Unresolved Q3 — tenant-scoped: GET /v1/agents is the
+      // authenticated principal's workspace set, which MAY be empty (the workspace
+      // approved no agent packs) while manifestRuntime is advertised host-wide.
+      // Empty is conformant; the cross-tenant no-disclosure 404 is covered by the
+      // owner-triple isolation harness (RFC 0048/0059), not re-probed here. Nothing
+      // to dispatch.
+      return;
+    }
+
+    const agentId = agents[0]?.agentId;
+    if (typeof agentId !== 'string') return;
+
+    // Opaque-payload dispatch (validateHandoff:false) so the assertion is
+    // independent of the chosen agent's handoff schema.
+    const res = await dispatchAgent(agentId, { task: {}, validateHandoff: false, availableTools: [] });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.status === 'completed' || res.status === 'escalated',
+      driver.describe('RFC 0070', 'dispatch MUST resolve to a terminal status (completed | escalated)'),
+    ).toBe(true);
+    const types = (res.events ?? []).map((e) => e.type);
+    expect(
+      types.includes('agent.reasoned') && types.includes('agent.decided'),
+      driver.describe('RFC 0002 §A', 'dispatch MUST emit attributed agent.reasoned + agent.decided events'),
+    ).toBe(true);
+    expect(
+      (res.events ?? []).every((e) => e.agentId === agentId),
+      driver.describe('RFC 0002 §A', 'every emitted agent.* event MUST carry the dispatched agentId'),
+    ).toBe(true);
+  });
+
+  // NOTE: RFC 0002 §F confidence escalation is NOT asserted here. Forcing a
+  // sub-threshold decision black-box would require a non-normative test hook
+  // (the reference host's `simulateConfidence`); a conformant host need not
+  // expose one, so asserting it here would wrongly fail conformant peers.
+  // Escalation is covered against the reference host in
+  // apps/workflow-engine/backend/typescript/test/{agents,agent-dispatch-route}.test.ts.
+});

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

@@ -23,15 +23,10 @@ import Ajv2020 from 'ajv/dist/2020.js';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
 
-interface DiscoveryDoc {
-  capabilities?: {
-    aiProviders?: { supported?: unknown };
-    supportedEnvelopes?: unknown;
-  };
-  supportedEnvelopes?: unknown;
-}
+type DiscoveryDoc = Record<string, unknown>;
 
 const UNIVERSAL_KINDS = [
   'clarification.request',
@@ -47,19 +42,19 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function aiProvidersSupported(d: DiscoveryDoc | null): boolean {
-  if (!d?.capabilities?.aiProviders?.supported) return false;
+  // Root-first per RFC 0073; `capabilities.aiProviders` is the deprecated wrapper shape.
+  const ap = capabilityFamily<{ supported?: unknown }>(d ?? undefined, 'aiProviders');
+  if (!ap?.supported) return false;
   // aiProviders.supported can be `true` or an array per the capabilities schema.
-  const v = d.capabilities.aiProviders.supported;
+  const v = ap.supported;
   return v === true || (Array.isArray(v) && v.length > 0);
 }
 
 function supportedEnvelopes(d: DiscoveryDoc | null): string[] {
-  // supportedEnvelopes is at the top level per the capabilities schema, but
-  // some hosts nest it under capabilities — tolerate both.
-  const top = d?.supportedEnvelopes;
-  const nested = d?.capabilities?.supportedEnvelopes;
-  const raw = Array.isArray(top) ? top : Array.isArray(nested) ? nested : [];
-  return raw.filter((s): s is string => typeof s === 'string');
+  // supportedEnvelopes is a document-root field per capabilities.md §"Document-root
+  // layout" (RFC 0073); a `capabilities.*` wrapper is the deprecated fallback.
+  const raw = capabilityFamily<unknown>(d ?? undefined, 'supportedEnvelopes');
+  return Array.isArray(raw) ? raw.filter((s): s is string => typeof s === 'string') : [];
 }
 
 // HTTP-driven blocks soft-skip when no base URL is configured (gate's
@@ -76,9 +71,10 @@ describe.skipIf(HTTP_SKIP)('ai-envelope-shape: advertisement contract (RFC 0021
     for (const k of env) {
       expect(typeof k, driver.describe('capabilities.md §supportedEnvelopes', 'each entry MUST be a string')).toBe('string');
     }
-    // Re-affirm shape: array if present.
-    if (d.capabilities?.supportedEnvelopes !== undefined) {
-      expect(Array.isArray(d.capabilities.supportedEnvelopes), 'supportedEnvelopes MUST be an array').toBe(true);
+    // Re-affirm shape: array if present (root-first per RFC 0073).
+    const advertised = capabilityFamily<unknown>(d, 'supportedEnvelopes');
+    if (advertised !== undefined) {
+      expect(Array.isArray(advertised), 'supportedEnvelopes MUST be an array').toBe(true);
     }
   });
 });

package/src/scenarios/aiEnvelope.capBreached.test.ts

@@ -33,7 +33,7 @@ interface DiscoveryDoc {
 async function readLimits(): Promise<Record<string, number> | null> {
   const res = await driver.get('/.well-known/openwop');
   const body = res.json as DiscoveryDoc | undefined;
-  const limits = body?.limits ?? body?.capabilities?.limits ?? null;
+  const limits = body?.limits ?? capabilityFamily(body, 'limits') ?? null;
   return limits && typeof limits === 'object' ? (limits as Record<string, number>) : null;
 }
 
@@ -166,6 +166,7 @@ describe('aiEnvelope.capBreached: behavioral cap enforcement (FINAL v1.1)', () =
 // node.failed per capabilities.md §"Engine-enforced limits". Tests
 // soft-skip on HTTP 404 when the seam isn't exposed.
 import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 describe('aiEnvelope.capBreached: engine projection via event-log seam (capabilities.md §"cap.breached")', () => {
   it('breached outcome projects to cap.breached { kind: "envelopes" } event with causationId chain', async () => {

package/src/scenarios/aiEnvelope.schemaDrift.test.ts

@@ -54,7 +54,7 @@ describe('aiEnvelope.schemaDrift: advertisement shape (FINAL v1.1)', () => {
     if (!(await isEnvelopeContractsAdvertised())) return; // not opted in — skip
     const res = await driver.get('/.well-known/openwop');
     const body = res.json as { schemaVersions?: Record<string, number>; capabilities?: { schemaVersions?: Record<string, number> } } | undefined;
-    const versions = body?.schemaVersions ?? body?.capabilities?.schemaVersions ?? {};
+    const versions = body?.schemaVersions ?? capabilityFamily(body, 'schemaVersions') ?? {};
     expect(
       Object.keys(versions).length > 0,
       driver.describe(
@@ -189,6 +189,7 @@ describe('aiEnvelope.schemaDrift: behavioral strictness gate (FINAL v1.1)', () =
 // E.2 OTel scrape seam.
 import { queryTestSpans, isOtelSeamAvailable } from '../lib/otel-scrape.js';
 import { resetTestSeam } from '../lib/event-log-query.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 describe('aiEnvelope.schemaDrift: OTel drift attribute projection (E.2)', () => {
   it('below-floor + strictness:warn → OTel span MUST carry envelope_schema_version_drift attribute', async () => {

package/src/scenarios/aiEnvelope.universalKinds.test.ts

@@ -166,6 +166,7 @@ describe('aiEnvelope.universalKinds: behavioral accept via /v1/host/sample/envel
 
 // E.1 engine-projection via the test-only event-log seam.
 import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 describe('aiEnvelope.universalKinds: engine projection via event-log seam', () => {
   it('clarification.request MUST be lifted to interrupt.requested { kind: "clarification" } per interrupt.md', async () => {
@@ -254,7 +255,7 @@ describe('aiEnvelope.universalKinds: schema.response counter-policy advertisemen
     // advertising a policy field use a documented value.
     const res = await driver.get('/.well-known/openwop');
     const body = res.json as { capabilities?: { aiEnvelope?: { schemaResponseCounterPolicy?: string } } } | undefined;
-    const policy = body?.capabilities?.aiEnvelope?.schemaResponseCounterPolicy;
+    const policy = capabilityFamily<{ schemaResponseCounterPolicy?: string }>(body, 'aiEnvelope')?.schemaResponseCounterPolicy;
     if (policy === undefined) return; // no policy advertised — host MAY omit
     expect(
       ['counted', 'exempt'].includes(policy),

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

@@ -22,14 +22,12 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
-
-interface DiscoveryDoc {
-  capabilities?: { authorization?: { supported?: boolean } };
-}
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
 
 async function authorizationSupported(): Promise<boolean> {
-  const res = await driver.get('/.well-known/openwop');
-  return (res.json as DiscoveryDoc | undefined)?.capabilities?.authorization?.supported === true;
+  // Root-first per RFC 0073 (`capabilities.authorization` is the deprecated wrapper shape).
+  const authz = await readCapabilityFamily<{ supported?: unknown }>('authorization');
+  return authz?.supported === true;
 }
 
 describe('approval-gate-flow: role-gated, audited approval (RFC 0051 §A)', () => {

package/src/scenarios/artifact-schema-compile-bounded.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Bounded artifact-schema compilation (RFC 0071, `Active`).
+ *
+ * Always-on, server-free assertion for the SECURITY invariant
+ * `artifact-schema-compile-bounded`. Artifact-type packs ship third-party
+ * JSON Schemas that the engine compiles (Ajv) at install + validation time;
+ * an unbounded compile is a denial-of-service vector (schema bombs:
+ * pathological `$ref` recursion, keyword-count explosion, oversized payloads,
+ * catastrophic-backtracking `pattern`s). This scenario asserts two things
+ * that must hold for every release regardless of which host runs it:
+ *
+ *   PART 1 — contract present. `artifact-type-packs.md` carries the normative
+ *   bounded-compilation MUST (serialized-size, `$ref`-depth, keyword-count
+ *   bounds + wall-clock timeout), and `host-capabilities.md` §host.artifactTypes
+ *   references it. Guards against the requirement being silently dropped.
+ *
+ *   PART 2 — defense is well-defined + implementable. A reference bounding
+ *   predicate built from representative finite limits rejects three schema
+ *   bombs and admits a benign artifact schema. The specific numeric limits are
+ *   host-configurable per the spec (advertised, not protocol-mandated); the
+ *   point is that *some* finite bound exists and catches the bombs while
+ *   passing legitimate schemas.
+ *
+ * The behavioral end-to-end form (a host rejects an over-bounds pack at
+ * registry `PUT` with `pack_validation_failed`) is capability-gated on
+ * `host.artifactTypes.supported` and is `host-pending` until a reference host
+ * lands; this server-free scenario is the always-on floor.
+ *
+ * @see spec/v1/artifact-type-packs.md §"Bounded schema compilation (normative)"
+ * @see SECURITY/threat-model-node-packs.md §"Distributed artifact schemas"
+ * @see RFCS/0071-artifact-type-and-chat-card-packs.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { V1_DIR } from '../lib/paths.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+describe('artifact-schema-compile-bounded: contract present in the corpus (RFC 0071, server-free)', () => {
+  const artifactDoc = V1_DIR ? readFileSync(join(V1_DIR, 'artifact-type-packs.md'), 'utf8') : '';
+  const hostCaps = V1_DIR ? readFileSync(join(V1_DIR, 'host-capabilities.md'), 'utf8') : '';
+
+  it.skipIf(V1_DIR === null)('artifact-type-packs.md declares the bounded-compilation MUST', () => {
+    expect(
+      /Bounded schema compilation/i.test(artifactDoc),
+      why('artifact-type-packs.md', 'a "Bounded schema compilation" section MUST exist'),
+    ).toBe(true);
+    expect(
+      /MUST bound/i.test(artifactDoc) && /MUST reject/i.test(artifactDoc),
+      why('artifact-type-packs.md §"Bounded schema compilation"', 'host MUST bound + MUST reject over-limit schemas'),
+    ).toBe(true);
+    // The three structural axes + the timeout MUST all be named.
+    for (const axis of [/byte size/i, /\$ref/i, /keyword/i, /timeout/i]) {
+      expect(axis.test(artifactDoc), why('artifact-type-packs.md', `bound axis ${axis} MUST be named`)).toBe(true);
+    }
+  });
+
+  it.skipIf(V1_DIR === null)('host-capabilities.md §host.artifactTypes references the bound', () => {
+    expect(
+      /artifact-schema-compile-bounded/.test(hostCaps),
+      why('host-capabilities.md §host.artifactTypes', 'MUST reference the bounded-compilation invariant'),
+    ).toBe(true);
+  });
+});
+
+describe('artifact-schema-compile-bounded: a finite bound catches schema bombs (RFC 0071, server-free)', () => {
+  // Representative, host-configurable limits (the spec leaves the exact values
+  // to host advertisement; these stand in for "some finite bound").
+  const LIMITS = { maxBytes: 64 * 1024, maxRefDepth: 16, maxKeywords: 2000 };
+
+  function refDepth(node: unknown, seen = 0): number {
+    if (node === null || typeof node !== 'object') return seen;
+    const obj = node as Record<string, unknown>;
+    const here = '$ref' in obj ? seen + 1 : seen;
+    let max = here;
+    for (const v of Object.values(obj)) max = Math.max(max, refDepth(v, here));
+    return max;
+  }
+  function keywordCount(node: unknown): number {
+    if (node === null || typeof node !== 'object') return 0;
+    const obj = node as Record<string, unknown>;
+    let n = Object.keys(obj).length;
+    for (const v of Object.values(obj)) n += keywordCount(v);
+    return n;
+  }
+  /** Reference bound predicate — the shape a conformant host applies at PUT/install. */
+  function exceedsBounds(schema: unknown): boolean {
+    const bytes = Buffer.byteLength(JSON.stringify(schema), 'utf8');
+    if (bytes > LIMITS.maxBytes) return true;
+    if (refDepth(schema) > LIMITS.maxRefDepth) return true;
+    if (keywordCount(schema) > LIMITS.maxKeywords) return true;
+    return false;
+  }
+
+  it('admits a benign artifact schema', () => {
+    const benign = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: 'https://h.example/schemas/artifacts/vendor.acme.cad.model.schema.json',
+      type: 'object',
+      additionalProperties: false,
+      required: ['name'],
+      properties: { name: { type: 'string' }, dims: { type: 'array', items: { type: 'number' } } },
+    };
+    expect(exceedsBounds(benign), why('artifact-type-packs.md', 'a legitimate artifact schema MUST NOT be rejected')).toBe(false);
+  });
+
+  it('rejects a $ref-depth bomb', () => {
+    // Nest $ref-bearing objects deeper than maxRefDepth so resolution depth accumulates.
+    let node: Record<string, unknown> = { type: 'string' };
+    for (let i = 0; i < LIMITS.maxRefDepth + 4; i++) node = { $ref: '#/x', properties: { nested: node } };
+    expect(exceedsBounds({ type: 'object', properties: { deep: node } }), why('threat-model-node-packs.md', 'a $ref-depth bomb MUST be rejected')).toBe(true);
+  });
+
+  it('rejects a keyword-count bomb', () => {
+    const props: Record<string, unknown> = {};
+    for (let i = 0; i < LIMITS.maxKeywords + 100; i++) props[`p${i}`] = { type: 'string' };
+    expect(exceedsBounds({ type: 'object', properties: props }), why('threat-model-node-packs.md', 'a keyword-count bomb MUST be rejected')).toBe(true);
+  });
+
+  it('rejects an oversized schema', () => {
+    const huge = { type: 'object', description: 'x'.repeat(LIMITS.maxBytes + 1) };
+    expect(exceedsBounds(huge), why('threat-model-node-packs.md', 'an over-size schema MUST be rejected')).toBe(true);
+  });
+});