@openwop/openwop-conformance 1.6.1 → 1.11.0

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/profiles.ts

@@ -30,6 +30,8 @@ export const PROFILE_NAMES = [
   'openwop-node-packs',
   'openwop-replay-fork',
   'openwop-fixtures',
+  'openwop-memory',
+  'openwop-trigger-bridge',
 ] as const;
 
 export type ProfileName = (typeof PROFILE_NAMES)[number];
@@ -211,6 +213,155 @@ export function isFixtures(c: DiscoveryPayload): boolean {
   return c.fixtures.every((id) => typeof id === 'string' && id.length > 0);
 }
 
+/**
+ * `openwop-memory` predicate (RFC 0080). Host implements the reconciled
+ * memory-capability model at the core tier: a read/write `MemoryAdapter`
+ * (`memory.supported: true` and `memory.writable !== false`) plus a cross-run
+ * durable store (`agents.memoryBackends` includes `'long-term'`). Capability
+ * families are document-root properties of the discovery payload (RFC 0073),
+ * so this reads `c.memory` / `c.agents`, matching `isReplayFork`.
+ *
+ * @see spec/v1/profiles.md §`openwop-memory`
+ * @see spec/v1/agent-memory.md §"Memory capability model"
+ */
+export function isMemory(c: DiscoveryPayload): boolean {
+  if (!isCore(c)) return false;
+  const memory = c.memory as { supported?: unknown; writable?: unknown } | undefined;
+  if (memory == null || typeof memory !== 'object') return false;
+  if (memory.supported !== true) return false;
+  if (memory.writable === false) return false;
+  const agents = c.agents as { memoryBackends?: unknown } | undefined;
+  if (agents == null || !isStringArray(agents.memoryBackends)) return false;
+  return agents.memoryBackends.includes('long-term');
+}
+
+/**
+ * `openwop-trigger-bridge` predicate (RFC 0083). Host composes the durable
+ * inbound-work contract: advertises the `triggerBridge`, has a `deadLetter`
+ * sink for exhausted deliveries, and has at least one durable inbound source
+ * (queue bus, durable webhooks, or scheduling). Capability families are
+ * document-root properties (RFC 0073), so this reads `c.triggerBridge` /
+ * `c.deadLetter` / `c.queueBus` / `c.webhooks` / `c.scheduling`.
+ *
+ * @see spec/v1/profiles.md §`openwop-trigger-bridge`
+ * @see spec/v1/trigger-bridge.md
+ */
+export function isTriggerBridge(c: DiscoveryPayload): boolean {
+  if (!isCore(c)) return false;
+  const supported = (v: unknown): boolean =>
+    v != null && typeof v === 'object' && (v as { supported?: unknown }).supported === true;
+  if (!supported(c.triggerBridge)) return false;
+  if (!supported(c.deadLetter)) return false;
+  const webhooks = c.webhooks as { durable?: unknown } | undefined;
+  const durableSource =
+    supported(c.queueBus) ||
+    supported(c.scheduling) ||
+    (webhooks != null && typeof webhooks === 'object' && webhooks.durable === true);
+  return durableSource;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Operational annex: openwop-agent-platform (RFC 0085).
+//
+// NOT part of the closed `profiles.md` predicate catalog (PROFILE_NAMES /
+// deriveProfiles above) — it is an operational ANNEX (the production-profile.md /
+// auth-profiles.md pattern) combining a discovery predicate with required runtime
+// conformance evidence + documentation + a badge. These helpers compute only the
+// discovery-PREDICATE part; the live aggregate-evidence assertion (does every
+// constituent scenario actually pass?) lives in agent-platform-profile.test.ts.
+//
+// @see spec/v1/agent-platform-profile.md
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Narrow helper: a capability sub-block with `supported === true`. */
+function blockSupported(v: unknown): boolean {
+  return v != null && typeof v === 'object' && (v as { supported?: unknown }).supported === true;
+}
+
+/** The `openwop-agent-platform` FLOOR (`partial`) discovery predicate — RFC 0085 §B. */
+export function isAgentPlatformPartial(c: DiscoveryPayload): boolean {
+  if (!isCore(c)) return false;
+  const agents = c.agents as { manifestRuntime?: unknown; liveRuntime?: unknown } | undefined;
+  const httpClient = c.httpClient as { safeFetch?: unknown; egressPolicy?: unknown } | undefined;
+  const replay = c.replay as { supported?: unknown } | undefined;
+  const nondet = c.nondeterminismPolicy as { declared?: unknown } | undefined;
+  return (
+    blockSupported(agents?.manifestRuntime) &&
+    blockSupported(agents?.liveRuntime) &&
+    blockSupported(c.toolCatalog) &&
+    blockSupported(c.toolHooks) &&
+    blockSupported(httpClient?.safeFetch) &&
+    blockSupported(c.providerUsage) &&
+    blockSupported(c.prompts) &&
+    blockSupported(c.memory) &&
+    blockSupported(c.feedback) &&
+    (replay?.supported === true || nondet?.declared === true)
+  );
+}
+
+/** The `openwop-agent-platform` `full` discovery predicate (floor + governance tier) — RFC 0085 §B. */
+export function isAgentPlatformFull(c: DiscoveryPayload): boolean {
+  if (!isAgentPlatformPartial(c)) return false;
+  const agents = c.agents as { manifestRuntime?: { installScope?: unknown } } | undefined;
+  const memory = c.memory as { attribution?: unknown } | undefined;
+  // Debug bundle is advertised at `capabilities.debugBundle.supported` (debug-bundle.md /
+  // RFC 0009), NOT under `production.*` — the production block only adds stricter truncation MUSTs.
+  const httpClient = c.httpClient as { egressPolicy?: unknown } | undefined;
+  return (
+    blockSupported(c.authorization) &&
+    agents?.manifestRuntime?.installScope === 'tenant' &&
+    blockSupported(memory?.attribution) &&
+    blockSupported(c.debugBundle) &&
+    blockSupported(c.triggerBridge) &&
+    blockSupported(httpClient?.egressPolicy)
+  );
+}
+
+/** The host-reported annex status: `full` ⊃ `partial` ⊃ `none` (discovery-predicate only). */
+export function agentPlatformStatus(c: DiscoveryPayload): 'none' | 'partial' | 'full' {
+  if (isAgentPlatformFull(c)) return 'full';
+  if (isAgentPlatformPartial(c)) return 'partial';
+  return 'none';
+}
+
+/**
+ * The per-term satisfaction breakdown (RFC 0085 §D) — the richer interop signal
+ * alongside the flat `none`/`partial`/`full` ladder. Adoption is NON-CONTIGUOUS:
+ * a real host built feature-by-feature can satisfy `full`-tier terms (RBAC,
+ * memory-attribution, tenant-scoping) while still failing `floor` terms, so the
+ * flat status would understate it (reads identical to a do-nothing host). This
+ * returns exactly the term ids a host satisfies, so a `none` host honoring 6/16
+ * terms is distinguishable from one honoring 0/16.
+ */
+export function agentPlatformSatisfiedTerms(c: DiscoveryPayload): readonly string[] {
+  const agents = c.agents as { manifestRuntime?: { installScope?: unknown }; liveRuntime?: unknown } | undefined;
+  const httpClient = c.httpClient as { safeFetch?: unknown; egressPolicy?: unknown } | undefined;
+  const memory = c.memory as { attribution?: unknown } | undefined;
+  const replay = c.replay as { supported?: unknown } | undefined;
+  const nondet = c.nondeterminismPolicy as { declared?: unknown } | undefined;
+  const checks: ReadonlyArray<readonly [string, boolean]> = [
+    // floor
+    ['floor:agents.manifestRuntime', blockSupported(agents?.manifestRuntime)],
+    ['floor:agents.liveRuntime', blockSupported(agents?.liveRuntime)],
+    ['floor:toolCatalog', blockSupported(c.toolCatalog)],
+    ['floor:toolHooks', blockSupported(c.toolHooks)],
+    ['floor:httpClient.safeFetch', blockSupported(httpClient?.safeFetch)],
+    ['floor:providerUsage', blockSupported(c.providerUsage)],
+    ['floor:prompts', blockSupported(c.prompts)],
+    ['floor:memory', blockSupported(c.memory)],
+    ['floor:feedback', blockSupported(c.feedback)],
+    ['floor:replay-or-nondeterminism', replay?.supported === true || nondet?.declared === true],
+    // full (governance)
+    ['full:authorization', blockSupported(c.authorization)],
+    ['full:tenant-installScope', agents?.manifestRuntime?.installScope === 'tenant'],
+    ['full:memory.attribution', blockSupported(memory?.attribution)],
+    ['full:debugBundle', blockSupported(c.debugBundle)],
+    ['full:triggerBridge', blockSupported(c.triggerBridge)],
+    ['full:egressPolicy', blockSupported(httpClient?.egressPolicy)],
+  ];
+  return checks.filter(([, ok]) => ok).map(([id]) => id);
+}
+
 /**
  * Derive the full profile set from a discovery payload.
  *
@@ -228,6 +379,8 @@ export function deriveProfiles(c: DiscoveryPayload): readonly ProfileName[] {
   if (isNodePacksDiscovery(c)) result.push('openwop-node-packs');
   if (isReplayFork(c)) result.push('openwop-replay-fork');
   if (isFixtures(c)) result.push('openwop-fixtures');
+  if (isMemory(c)) result.push('openwop-memory');
+  if (isTriggerBridge(c)) result.push('openwop-trigger-bridge');
   return result;
 }
 
@@ -254,5 +407,9 @@ export function hasProfile(c: DiscoveryPayload, profile: ProfileName): boolean {
       return isReplayFork(c);
     case 'openwop-fixtures':
       return isFixtures(c);
+    case 'openwop-memory':
+      return isMemory(c);
+    case 'openwop-trigger-bridge':
+      return isTriggerBridge(c);
   }
 }

package/src/lib/runtimeRequires.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared helper for the RFC 0076 §A `runtime.requires[]` install-gate
+ * conformance scenarios. Lives in lib/ (not a *.test.ts) so scenarios import it
+ * via `../lib/runtimeRequires.js`.
+ *
+ * Drives the conformance-only host seam specified in host-sample-test-seams.md
+ * §"Open seams": `POST /v1/host/sample/packs/install-gate`. The seam evaluates a
+ * manifest's `runtime.requires[]` against a simulated host grant-set and returns
+ * the install-time outcome the host would produce — letting a single seam
+ * exercise the grant / refuse / non-sandbox-projection behaviors deterministically.
+ */
+import { driver } from './driver.js';
+
+export interface InstallGateRequest {
+  /** The candidate pack manifest (carrying runtime.requires[]). */
+  manifest: Record<string, unknown>;
+  /** Primitives the simulated sandbox grants. Ignored when `gating === false`. */
+  grantSet?: string[];
+  /** Whether the simulated host gates platform access. Default true (sandbox host). */
+  gating?: boolean;
+}
+
+export interface InstallGateResponse {
+  /** HTTP status the seam returned (200 install, 400 refuse). */
+  status: number;
+  /** Parsed response body. */
+  body: Record<string, unknown>;
+}
+
+/**
+ * Drives one install-gate evaluation via the host-sample seam, or null
+ * (soft-skip) when the host doesn't expose it.
+ */
+export async function installGate(req: InstallGateRequest): Promise<InstallGateResponse | null> {
+  const res = await driver.post('/v1/host/sample/packs/install-gate', req as unknown as Record<string, unknown>);
+  if (res.status === 404 || res.status === 405) return null; // seam absent — soft-skip
+  return { status: res.status, body: (res.json as Record<string, unknown> | undefined) ?? {} };
+}

package/src/lib/safeFetch.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared helper for the RFC 0076 §B `ctx.http.safeFetch` conformance scenarios.
+ * Lives in lib/ (not a *.test.ts) so scenarios import it via `../lib/safeFetch.js`.
+ *
+ * Reads `capabilities.httpClient.safeFetch` (root-first, wrapper-fallback) and
+ * drives the conformance-only host seam `POST /v1/host/sample/http/safe-fetch`
+ * (host-sample-test-seams.md §"Open seams").
+ */
+import { driver } from './driver.js';
+import { capabilityFamily } from './discovery-capabilities.js';
+
+interface HttpClientCap {
+  supported?: boolean;
+  safeFetch?: { supported?: boolean };
+}
+
+/** True when the host advertises `capabilities.httpClient.safeFetch.supported`. */
+export async function isSafeFetchSupported(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  return capabilityFamily<HttpClientCap>(disco.json, 'httpClient')?.safeFetch?.supported === true;
+}
+
+/** True when the host also advertises `capabilities.toolHooks.prePostEvents`. */
+export async function isToolHookAuditOn(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  return capabilityFamily<{ prePostEvents?: boolean }>(disco.json, 'toolHooks')?.prePostEvents === true;
+}
+
+export interface SafeFetchResult {
+  outcome?: 'fetched' | 'blocked';
+  status?: number;
+  blocked?: 'ssrf' | 'upgrade' | string;
+  toolCalled?: Record<string, unknown>;
+  toolReturned?: Record<string, unknown>;
+}
+
+/**
+ * Drives one safeFetch evaluation via the host-sample seam, or null (soft-skip)
+ * when the host doesn't expose it.
+ */
+export async function safeFetch(body: Record<string, unknown>): Promise<SafeFetchResult | null> {
+  const res = await driver.post('/v1/host/sample/http/safe-fetch', body);
+  if (res.status === 404 || res.status === 405) return null; // seam absent — soft-skip
+  return (res.json as SafeFetchResult | undefined) ?? {};
+}
+
+/**
+ * True when the host advertises BOTH `httpClient.safeFetch.supported` AND
+ * `toolHooks.prePostEvents` — the co-advertisement that, per
+ * `host-capabilities.md` §host.http + RFC 0076 §B, makes live audit-pair
+ * emission a MUST. One discovery fetch (the two single-flag helpers above each
+ * fetch; this avoids the double round-trip for the live-audit gate).
+ */
+export async function isSafeFetchLiveAuditAdvertised(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const safeFetchOn =
+    capabilityFamily<HttpClientCap>(disco.json, 'httpClient')?.safeFetch?.supported === true;
+  const auditOn =
+    capabilityFamily<{ prePostEvents?: boolean }>(disco.json, 'toolHooks')?.prePostEvents === true;
+  return safeFetchOn && auditOn;
+}
+
+/** Result of the live-run safe-fetch seam: the host executed one
+ *  `ctx.http.safeFetch` call inside a real run via the production injection
+ *  path, and returns the run's id so the caller can read the durable event
+ *  log. `null` ⇒ the run seam is unwired (soft-skip, host-pending). */
+export interface SafeFetchRunResult {
+  runId?: string;
+  outcome?: 'fetched' | 'blocked';
+}
+
+/**
+ * Drives one `ctx.http.safeFetch` call **inside a real run** via the open seam
+ * `POST /v1/host/sample/http/safe-fetch-run`, returning `{ runId, outcome }`,
+ * or null (soft-skip) when the run seam isn't wired. Distinct from `safeFetch`
+ * (which returns the audit pair INLINE from the seam): this exercises the
+ * production per-ctx `ctx.http.safeFetch` path so the caller can assert the
+ * `agent.toolCalled`/`agent.toolReturned` pair landed in the DURABLE run event
+ * log — closing the seam-vs-production gap in `safefetch-behavior.test.ts`.
+ */
+export async function safeFetchViaRun(
+  body: Record<string, unknown>,
+): Promise<SafeFetchRunResult | null> {
+  const res = await driver.post('/v1/host/sample/http/safe-fetch-run', body);
+  if (res.status === 404 || res.status === 405) return null; // run seam unwired — soft-skip
+  return (res.json as SafeFetchRunResult | undefined) ?? {};
+}

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-deployment-shape.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Agent deployment lifecycle — record + binding + event shapes (RFC 0082).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `capabilities.agents.deployment` is declared with its `supported` /
+ *     `channels` / `canary` / `rollback` / `states` sub-flags.
+ *   - `agent-deployment.schema.json` compiles and round-trips a conforming
+ *     deployment record, and rejects malformed ones (an out-of-enum `state`;
+ *     `canaryPercent` out of 0..100).
+ *   - the `AgentRef` `channel` XOR `version` rule holds: each alone (and
+ *     neither) validates; both together is rejected (the `not` clause).
+ *   - the four `deployment.*` payload $defs validate conforming content-free
+ *     payloads and reject malformed ones.
+ *   - the four `deployment.*` payloads are CONTENT-FREE: a `deployment.promoted`
+ *     carrying a `manifestBody`, and a `deployment.state.changed` carrying a
+ *     `prompt`, are rejected (`additionalProperties:false`). This is the public
+ *     test for the protocol-tier SECURITY invariant `deployment-event-no-content-leak`.
+ *   - `agent.invocation.started` carries the additive recorded-fact
+ *     `resolvedAgentVersion` / `resolvedChannel` fields (RFC 0082 §B).
+ *   - all four event names appear in the RunEventType enum.
+ *
+ * Behavioral assertions (the authz → approvalGate → eval-verify → promotion path,
+ * the fail-closed denial, the §B replay re-read of `resolvedAgentVersion`) are
+ * gated on `capabilities.agents.deployment.supported` and land in
+ * `agent-deployment-lifecycle.test.ts` (deferred per RFC 0082 §Conformance —
+ * reference host deferred). This scenario asserts the wire contract, not host
+ * behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-deployment.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0082-agent-deployment-lifecycle.md
+ *   - https://github.com/openwop/openwop/blob/main/SECURITY/invariants.yaml (deployment-event-no-content-leak)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+/** Server-free assertion-message helper. */
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+describe('agent-deployment-shape: capability advertisement (RFC 0082, server-free)', () => {
+  it('the capabilities schema declares agents.deployment with its sub-flags', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const agents = (caps.properties as Record<string, { properties?: Record<string, { properties?: Record<string, unknown> }> }>).agents;
+    const deployment = agents?.properties?.deployment;
+    expect(deployment, why('capabilities.md §agents', 'agents.deployment MUST be declared')).toBeDefined();
+    for (const flag of ['supported', 'channels', 'canary', 'rollback', 'states']) {
+      expect(
+        deployment?.properties?.[flag],
+        why('agent-deployment.md §F', `agents.deployment.${flag} MUST be declared`),
+      ).toBeDefined();
+    }
+  });
+});
+
+describe('agent-deployment-shape: deployment record + AgentRef binding (RFC 0082, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const record = ajv.compile(loadSchema('agent-deployment.schema.json'));
+  const agentRef = ajv.compile(loadSchema('agent-ref.schema.json'));
+
+  it('AgentDeployment validates a conforming record and rejects a bad state / out-of-range canary', () => {
+    const good = { agentId: 'core.openwop.agents.support-resolver', version: '2.4.0', state: 'active', canaryPercent: 10, channels: ['stable'] };
+    expect(record(good), why('RFC 0082 §C', 'a conforming deployment record MUST validate')).toBe(true);
+    expect(record({ ...good, state: 'live' }), why('RFC 0082 §C', 'an out-of-enum state MUST be rejected')).toBe(false);
+    expect(record({ ...good, canaryPercent: 150 }), why('RFC 0082 §C', 'canaryPercent > 100 MUST be rejected')).toBe(false);
+  });
+
+  it('AgentRef channel XOR version: each alone and neither validate; both is rejected (RFC 0082 §A)', () => {
+    expect(agentRef({ agentId: 'core.x.y.z', version: '1.0.0' }), why('RFC 0082 §A', 'version-only AgentRef MUST validate')).toBe(true);
+    expect(agentRef({ agentId: 'core.x.y.z', channel: 'stable' }), why('RFC 0082 §A', 'channel-only AgentRef MUST validate')).toBe(true);
+    expect(agentRef({ agentId: 'core.x.y.z' }), why('RFC 0082 §A', 'a ref with neither version nor channel MUST validate (host default)')).toBe(true);
+    expect(agentRef({ agentId: 'core.x.y.z', version: '1.0.0', channel: 'stable' }), why('RFC 0082 §A', 'a ref with BOTH version and channel MUST be rejected')).toBe(false);
+  });
+});
+
+describe('agent-deployment-shape: deployment.* event payloads (RFC 0082, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  ajv.addSchema(payloads, 'payloads');
+
+  const promoted = ajv.getSchema('payloads#/$defs/deploymentPromoted');
+  const rolledBack = ajv.getSchema('payloads#/$defs/deploymentRolledBack');
+  const canary = ajv.getSchema('payloads#/$defs/deploymentCanaryAdjusted');
+  const stateChanged = ajv.getSchema('payloads#/$defs/deploymentStateChanged');
+
+  it('deployment.promoted validates a content-free promotion record and requires toVersion + toState', () => {
+    expect(promoted, 'the deploymentPromoted $def MUST exist').toBeTruthy();
+    expect(
+      promoted!({ agentId: 'core.openwop.agents.support-resolver', toVersion: '2.4.0', toState: 'active', channel: 'stable', canaryPercent: 10, evalRunId: 'run_abc' }),
+      why('RFC 0082 §D', 'a conforming deployment.promoted payload MUST validate'),
+    ).toBe(true);
+    expect(promoted!({ agentId: 'a' }), why('RFC 0082 §D', 'deployment.promoted without toVersion/toState MUST be rejected')).toBe(false);
+  });
+
+  it('deployment.rolled-back / canary.adjusted / state.changed validate conforming records', () => {
+    expect(rolledBack!({ agentId: 'a', fromVersion: '2.4.0', toVersion: '2.3.1', rollbackPointer: '2.3.1' }), why('RFC 0082 §D', 'a conforming deployment.rolled-back MUST validate')).toBe(true);
+    expect(canary!({ agentId: 'a', version: '2.4.0', fromPercent: 10, toPercent: 50 }), why('RFC 0082 §D', 'a conforming deployment.canary.adjusted MUST validate')).toBe(true);
+    expect(stateChanged!({ agentId: 'a', version: '2.4.0', fromState: 'active', toState: 'paused' }), why('RFC 0082 §D', 'a conforming deployment.state.changed MUST validate')).toBe(true);
+    expect(stateChanged!({ agentId: 'a', version: '2.4.0', fromState: 'active', toState: 'live' }), why('RFC 0082 §D', 'an out-of-enum toState MUST be rejected')).toBe(false);
+  });
+
+  it('deployment.* events are content-free — a manifest body and a prompt are rejected (deployment-event-no-content-leak)', () => {
+    expect(
+      promoted!({ agentId: 'a', toVersion: '2.4.0', toState: 'active', manifestBody: '{...}' }),
+      why('SECURITY invariant deployment-event-no-content-leak', 'a deployment.promoted MUST NOT carry a manifest body'),
+    ).toBe(false);
+    expect(
+      stateChanged!({ agentId: 'a', version: '2.4.0', fromState: 'active', toState: 'paused', prompt: 'system: …' }),
+      why('SECURITY invariant deployment-event-no-content-leak', 'a deployment.state.changed MUST NOT carry prompt content'),
+    ).toBe(false);
+  });
+});
+
+describe('agent-deployment-shape: §B recorded-fact pin + enum (RFC 0082, server-free)', () => {
+  it('agent.invocation.started carries the additive recorded-fact resolvedAgentVersion / resolvedChannel', () => {
+    const payloads = loadSchema('run-event-payloads.schema.json');
+    const started = ((payloads.$defs as Record<string, { properties?: Record<string, unknown> }>).agentInvocationStarted)?.properties ?? {};
+    expect(started.resolvedAgentVersion, why('RFC 0082 §B', 'agent.invocation.started.resolvedAgentVersion MUST be declared (the channel pin)')).toBeDefined();
+    expect(started.resolvedChannel, why('RFC 0082 §B', 'agent.invocation.started.resolvedChannel MUST be declared')).toBeDefined();
+  });
+
+  it('all four deployment event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = (runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum ?? [];
+    for (const e of ['deployment.promoted', 'deployment.rolled-back', 'deployment.canary.adjusted', 'deployment.state.changed']) {
+      expect(enumVals).toContain(e);
+    }
+  });
+});