@openwop/openwop-conformance 1.106.1 → 1.124.0

package/src/lib/workflow-chain-expansion.ts

@@ -306,6 +306,195 @@ export function expandChain(chain: WorkflowChain, ctx: ExpansionContext): Expand
 // If it is gated on an advertised capability, it goes below.
 // ─────────────────────────────────────────────────────────────────────────────
 
+// ---------------------------------------------------------------------------
+// RFC 0157 (RFC 0013 revision × RFC 0151 §B) — chain fragments carry
+// compensation.
+//
+// A workflow that is "a chain or a stack" could not own an inverse action:
+// `FragmentNode` had no `compensation` and the chain had no policy, so RFC 0151
+// §B was reachable only through a hand-authored `POST /v1/workflows`. This pass
+// carries the node-level `compensation` declaration and the chain-level policy
+// through expansion into the registered `WorkflowDefinition`.
+//
+// It sits BELOW the mirrored core deliberately: the core is byte-mirrored by
+// the in-memory reference host and gated in CI, and this pass composes on the
+// core's output rather than editing it — a host runs `expandChain` then
+// `carryCompensation` (or `expandChainWithCompensation`). It is NOT capability
+// gated on the host's `compensation` advert: a host that does not advertise
+// `capabilities.compensation` still MUST carry the declaration verbatim (it is
+// descriptive) and MUST refuse a chain-level POLICY with `capability_required`
+// per `compensation.md` §"Workflow policy" — the same rule as for a hand-authored
+// `settings.compensation`.
+//
+// Normative reference: `spec/v1/workflow-chain-packs.md` §"Compensation
+// (RFC 0157)"; error code `chain_compensation_policy_conflict`.
+// ---------------------------------------------------------------------------
+
+/** Mirror of `WorkflowNode.compensation` (workflow-definition.schema.json). */
+export interface FragmentNodeCompensation {
+  nodeTypeId: string;
+  inputMapping?: Record<string, unknown>;
+  retry?: { maxAttempts?: number; backoffMs?: number };
+  requiresApproval?: boolean;
+}
+
+/** Mirror of `compensation-policy.schema.json` (RFC 0151 §B). */
+export interface ChainCompensationPolicy {
+  profileVersion?: string;
+  orderingModel?: 'reverse-completion' | 'dependency-graph';
+  triggers: ReadonlyArray<'node-failure' | 'run-cancel' | 'cap-breach' | 'operator-request'>;
+  retry?: { maxAttempts?: number; backoffMs?: number };
+  timeoutMs?: number;
+  exhaustedDisposition?: 'record-outcome' | 'manual-intervention';
+  approvalScope?: 'declared' | 'all';
+  onParentCancel?: 'continue' | 'pause' | 'manual';
+}
+
+/** A chain as RFC 0157 sees it: the RFC 0013 shape plus the two optional
+ *  compensation surfaces. */
+export type WorkflowChainWithCompensation = Omit<WorkflowChain, 'dag'> & {
+  dag: { nodes: ReadonlyArray<FragmentNode & { compensation?: FragmentNodeCompensation }>; edges?: ReadonlyArray<FragmentEdge> };
+  compensation?: ChainCompensationPolicy;
+};
+
+/** Thrown when the parent already carries a `settings.compensation` policy that
+ *  is not deep-equal to the chain's. Wire code
+ *  `chain_compensation_policy_conflict` (`workflow-chain-packs.md` §"Error
+ *  codes"). Fail closed: a merged policy nobody wrote is exactly the
+ *  guess-at-a-contract failure the policy exists to prevent. */
+export class ChainCompensationPolicyConflictError extends Error {
+  readonly code = 'chain_compensation_policy_conflict' as const;
+  constructor(
+    public readonly chainId: string,
+  ) {
+    super(
+      `chain_compensation_policy_conflict: chain "${chainId}" declares a compensation policy that differs ` +
+        'from the parent workflow\'s settings.compensation; expansion MUST NOT merge policies',
+    );
+    this.name = 'ChainCompensationPolicyConflictError';
+  }
+}
+
+/** Rewrite fragment node-id references inside an `inputMapping` value the same
+ *  way edge refs are rewritten: any string of the form
+ *  `${nodes.<fragmentNodeId>.<path>}` (or bare `nodes.<id>.<path>` / `<id>.<port>`)
+ *  gets its node-id segment prefixed. Everything else passes through. Recurses
+ *  through objects/arrays. Deliberately conservative: only ids that ARE
+ *  fragment node ids are rewritten, so a reference to a parent-workflow node
+ *  survives verbatim (same rule as `rewriteEdgeRef`). */
+function rewriteInputMappingRefs(value: unknown, fragmentNodeIds: ReadonlySet<string>, prefix: string): unknown {
+  if (typeof value === 'string') {
+    // `${nodes.<id>.…}` template form (RFC 0151 §B example) and `nodes.<id>.…`
+    return value.replace(/(\$\{\s*nodes\.|\bnodes\.)([A-Za-z0-9_.-]+?)(\.)/g, (m, lead: string, id: string, dot: string) =>
+      fragmentNodeIds.has(id) ? `${lead}${prefix}${id}${dot}` : m,
+    );
+  }
+  if (Array.isArray(value)) return value.map((v) => rewriteInputMappingRefs(v, fragmentNodeIds, prefix));
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = rewriteInputMappingRefs(v, fragmentNodeIds, prefix);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Stable deep equality for policy comparison (key order insensitive). */
+function canonicalJson(v: unknown): string {
+  if (Array.isArray(v)) return '[' + v.map(canonicalJson).join(',') + ']';
+  if (v !== null && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    return '{' + Object.keys(o).sort().map((k) => JSON.stringify(k) + ':' + canonicalJson(o[k])).join(',') + '}';
+  }
+  return JSON.stringify(v);
+}
+
+export interface CarriedCompensation {
+  /** The expanded fragment with `compensation` carried onto each node that
+   *  declared one (typeIds validated, params substituted, id refs rewritten). */
+  nodes: ReadonlyArray<ExpandedFragment['nodes'][number] & { compensation?: FragmentNodeCompensation }>;
+  /** The `settings.compensation` the registered definition MUST carry after
+   *  this expansion: the parent's when the chain declares none; the chain's
+   *  when the parent had none; the (equal) shared policy when both agree.
+   *  `undefined` when neither side declares one. */
+  settingsCompensation: ChainCompensationPolicy | undefined;
+}
+
+/**
+ * RFC 0157 — carry the chain's compensation surfaces through expansion.
+ *
+ * Steps (numbered to slot into `workflow-chain-packs.md` §"Expansion
+ * semantics"):
+ *   3b. every `compensation.nodeTypeId` MUST resolve exactly as `typeId` does
+ *       (`chain_unresolvable_typeid`) — an unwind must not fail on a typo first
+ *       discovered during a failure;
+ *   5b. `{{params.*}}` inside `inputMapping` are substituted (author-time
+ *       literals; the recorded-facts rule is unaffected);
+ *   6b. fragment node-id references inside `inputMapping` are rewritten with
+ *       the expansion prefix, exactly as edge refs are;
+ *   9b. the chain-level policy becomes the definition's `settings.compensation`
+ *       — copied when the parent has none, accepted when equal, otherwise
+ *       `chain_compensation_policy_conflict`.
+ *
+ * @throws ChainUnresolvableTypeIdError, ChainCompensationPolicyConflictError
+ */
+export function carryCompensation(
+  chain: WorkflowChainWithCompensation,
+  expanded: ExpandedFragment,
+  ctx: ExpansionContext,
+  parentSettingsCompensation?: ChainCompensationPolicy,
+): CarriedCompensation {
+  const prefix = computePrefix(chain.chainId, ctx.expansionId);
+  const srcNodes = chain.dag.nodes;
+  const fragmentNodeIds = new Set(srcNodes.map((n) => n.id));
+  const byOriginalId = new Map(srcNodes.map((n) => [n.id, n] as const));
+
+  // 3b
+  for (const n of srcNodes) {
+    if (n.compensation !== undefined && !ctx.isTypeIdResolvable(n.compensation.nodeTypeId)) {
+      throw new ChainUnresolvableTypeIdError(n.compensation.nodeTypeId, chain.chainId);
+    }
+  }
+
+  // 5b + 6b
+  const nodes = expanded.nodes.map((en) => {
+    const originalId = en.id.startsWith(prefix) ? en.id.slice(prefix.length) : en.id;
+    const src = byOriginalId.get(originalId);
+    if (src?.compensation === undefined) return en;
+    const c: FragmentNodeCompensation = { nodeTypeId: src.compensation.nodeTypeId };
+    if (src.compensation.inputMapping !== undefined) {
+      const substituted = substitute(src.compensation.inputMapping, ctx.params) as Record<string, unknown>;
+      c.inputMapping = rewriteInputMappingRefs(substituted, fragmentNodeIds, prefix) as Record<string, unknown>;
+    }
+    if (src.compensation.retry !== undefined) c.retry = { ...src.compensation.retry };
+    if (src.compensation.requiresApproval !== undefined) c.requiresApproval = src.compensation.requiresApproval;
+    return { ...en, compensation: c };
+  });
+
+  // 9b
+  let settingsCompensation: ChainCompensationPolicy | undefined = parentSettingsCompensation;
+  if (chain.compensation !== undefined) {
+    if (parentSettingsCompensation === undefined) {
+      settingsCompensation = { ...chain.compensation, triggers: [...chain.compensation.triggers] };
+    } else if (canonicalJson(parentSettingsCompensation) !== canonicalJson(chain.compensation)) {
+      throw new ChainCompensationPolicyConflictError(chain.chainId);
+    }
+  }
+  return { nodes, settingsCompensation };
+}
+
+/** Convenience: `expandChain` followed by `carryCompensation`. */
+export function expandChainWithCompensation(
+  chain: WorkflowChainWithCompensation,
+  ctx: ExpansionContext,
+  parentSettingsCompensation?: ChainCompensationPolicy,
+): ExpandedFragment & CarriedCompensation {
+  const expanded = expandChain(chain, ctx);
+  const carried = carryCompensation(chain, expanded, ctx, parentSettingsCompensation);
+  return { ...expanded, nodes: carried.nodes, settingsCompensation: carried.settingsCompensation };
+}
+
 // ---------------------------------------------------------------------------
 // RFC 0124 (WCP4) — Portable per-run parameter deferral.
 //

package/src/scenarios/a2a-1-0-agent-card.test.ts

@@ -0,0 +1,179 @@
+/**
+ * RFC 0152 §A/§B/§C/§D — the suite's own A2A peer at 1.0, pinned.
+ *
+ * `A2AFakePeer` became dual-era at suite 1.112.0 (1.0 + 0.3-legacy). This file
+ * boots a private instance and asserts, from the wire, that it actually speaks
+ * A2A 1.0 as `a2a-integration.md` §"A2A 1.0 versioned composition" defines it
+ * — because a fake peer that is 1.0-shaped only in its comments would let every
+ * §C/§D host leg pass against a 0.3 wire and prove nothing (the "detector that
+ * could never go green" failure, inverted).
+ *
+ * Pinned here (all server-free; the peer is in-process on 127.0.0.1):
+ *   - the Agent Card is 1.0-shaped: `supportedInterfaces[]{url,protocolBinding,
+ *     protocolVersion}` (one per spoken revision), no top-level `url` /
+ *     `protocolVersion`, `capabilities.extendedAgentCard`;
+ *   - a legacy-only peer serves the 0.3 card (so the shape follows the revision,
+ *     not the calendar);
+ *   - `A2A-Version` absent ⇒ 0.3 semantics; unsupported ⇒ `-32009`
+ *     `VERSION_NOT_SUPPORTED` with `supportedVersions[]`; a 1.0-only peer
+ *     rejects header-less requests;
+ *   - `SendMessage` returns `{ task }` (the `SendMessageResponse` oneof) with
+ *     `TASK_STATE_*`, `ROLE_*`, `Part` as a `oneof` (no `kind`), `status.timestamp`;
+ *   - `GetTask` / `CancelTask` / `ListTasks` behave per §D.1, incl.
+ *     `TASK_NOT_CANCELABLE` on a terminal task;
+ *   - a 0.3 method name under a 1.0 header is a method-not-found, loudly.
+ *
+ * This is the peer half of the RFC-named `a2a-1.0-agent-card` and
+ * `a2a-1.0-task-roundtrip` scenarios; the host halves are
+ * `a2a-card-runtime-consistency.test.ts` and `a2a-1-0-task-roundtrip.test.ts`,
+ * gated on the host claiming `a2a-1.0`.
+ *
+ * @see spec/v1/a2a-integration.md §"A2A 1.0 versioned composition" §A–§D
+ * @see conformance/src/lib/a2a-fake-peer.ts
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { A2AFakePeer } from '../lib/a2a-fake-peer.js';
+
+export const HOST_CALLBACK_NOT_REQUIRED = 'the suite drives both ends itself: it boots the dual-era A2AFakePeer in-process and reads its agent card directly; no host connection is originated';
+
+async function rpc(endpoint: string, method: string, params: unknown, version?: string, id = 1) {
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (version !== undefined) headers['A2A-Version'] = version;
+  const res = await fetch(`${endpoint}/a2a/jsonrpc`, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }) });
+  const body = (await res.json()) as { result?: Record<string, unknown>; error?: { code: number; message: string; data?: Record<string, unknown> } };
+  return { status: res.status, ...body };
+}
+
+describe('RFC 0152 — the suite peer speaks A2A 1.0 (dual-era A2AFakePeer)', () => {
+  // Explicit 1.0-first so a header-less GET returns the 1.0 card (the default
+  // is 0.3-first for today's 0.3 clients; both eras are spoken either way).
+  const peer = new A2AFakePeer({ protocolVersions: ['1.0', '0.3'] });
+  beforeAll(async () => peer.start(0));
+  afterAll(async () => peer.stop());
+
+  it('the Agent Card is 1.0-shaped: supportedInterfaces[], no top-level url/protocolVersion', async () => {
+    const res = await fetch(`${peer.endpoint()}/.well-known/agent-card.json`);
+    expect(res.status).toBe(200);
+    const card = (await res.json()) as Record<string, unknown>;
+    const ifaces = card['supportedInterfaces'] as Array<{ url: string; protocolBinding: string; protocolVersion: string }>;
+    expect(Array.isArray(ifaces) && ifaces.length > 0, '1.0 REQUIRES supportedInterfaces[]').toBe(true);
+    expect(ifaces.map((i) => i.protocolVersion)).toEqual(['1.0', '0.3']);
+    for (const i of ifaces) {
+      expect(i.protocolBinding).toBe('JSONRPC');
+      expect(i.url.startsWith(peer.endpoint())).toBe(true);
+    }
+    expect(card['url'], '1.0 removed top-level url').toBeUndefined();
+    expect(card['protocolVersion'], '1.0 removed top-level protocolVersion (it is per interface)').toBeUndefined();
+    const caps = card['capabilities'] as Record<string, unknown>;
+    expect(caps['extendedAgentCard']).toBe(false);
+    expect(Array.isArray(card['skills']) && (card['skills'] as unknown[]).length > 0, 'skills[] REQUIRED').toBe(true);
+    for (const k of ['name', 'description', 'version', 'defaultInputModes', 'defaultOutputModes']) expect(card[k], `${k} REQUIRED`).toBeDefined();
+  });
+
+  it('the card shape follows the era asked for: A2A-Version: 0.3 on the GET returns the 0.3 card from the same peer', async () => {
+    const res = await fetch(`${peer.endpoint()}/.well-known/agent-card.json`, { headers: { 'A2A-Version': '0.3' } });
+    const card = (await res.json()) as Record<string, unknown>;
+    expect(card['protocolVersion']).toBe('0.3.0');
+    expect(typeof card['url']).toBe('string');
+    expect(card['supportedInterfaces']).toBeUndefined();
+    // and the default-constructed peer (0.3-first) serves the 0.3 card to a header-less GET
+    const dflt = new A2AFakePeer();
+    await dflt.start(0);
+    try {
+      const c = (await (await fetch(`${dflt.endpoint()}/.well-known/agent-card.json`)).json()) as Record<string, unknown>;
+      expect(c['protocolVersion']).toBe('0.3.0');
+      const c10 = (await (await fetch(`${dflt.endpoint()}/.well-known/agent-card.json`, { headers: { 'A2A-Version': '1.0' } })).json()) as Record<string, unknown>;
+      expect(Array.isArray(c10['supportedInterfaces'])).toBe(true);
+    } finally {
+      await dflt.stop();
+    }
+  });
+
+  it('a legacy-only peer serves the 0.3 card — shape follows revision, not calendar', async () => {
+    const legacy = new A2AFakePeer({ protocolVersions: ['0.3'] });
+    await legacy.start(0);
+    try {
+      const card = (await (await fetch(`${legacy.endpoint()}/.well-known/agent-card.json`)).json()) as Record<string, unknown>;
+      expect(card['protocolVersion']).toBe('0.3.0');
+      expect(typeof card['url']).toBe('string');
+      expect(card['supportedInterfaces']).toBeUndefined();
+    } finally {
+      await legacy.stop();
+    }
+  });
+
+  it('A2A-Version absent ⇒ 0.3 semantics; message/send returns a 0.3 task', async () => {
+    const r = await rpc(peer.endpoint(), 'message/send', { message: { kind: 'message', messageId: 'm1', role: 'user', parts: [{ kind: 'text', text: 'hi' }] } });
+    expect(r.error).toBeUndefined();
+    expect(r.result?.['kind']).toBe('task');
+    expect((r.result?.['status'] as { state: string }).state).toBe('submitted');
+  });
+
+  it('an unsupported version fails -32009 VERSION_NOT_SUPPORTED with supportedVersions[] (HTTP 400)', async () => {
+    const r = await rpc(peer.endpoint(), 'SendMessage', { message: { messageId: 'm2', role: 'ROLE_USER', parts: [{ text: 'hi' }] } }, '99.0');
+    expect(r.status).toBe(400);
+    expect(r.error?.code).toBe(-32009);
+    expect(r.error?.data?.['reason']).toBe('VERSION_NOT_SUPPORTED');
+    expect(r.error?.data?.['supportedVersions']).toEqual(['1.0', '0.3']); // constructor order
+  });
+
+  it('a 1.0-only peer rejects a header-less request (which is 0.3 by rule)', async () => {
+    const only10 = new A2AFakePeer({ protocolVersions: ['1.0'] });
+    await only10.start(0);
+    try {
+      const r = await rpc(only10.endpoint(), 'message/send', { message: { parts: [] } });
+      expect(r.error?.code).toBe(-32009);
+      expect(r.error?.data?.['requested']).toBe('0.3');
+    } finally {
+      await only10.stop();
+    }
+  });
+
+  it('SendMessage @1.0 returns { task } with TASK_STATE_*, ROLE_*, Part oneof, no kind, status.timestamp', async () => {
+    peer.reset();
+    const r = await rpc(peer.endpoint(), 'SendMessage', { message: { messageId: 'm3', role: 'ROLE_USER', parts: [{ text: 'hello 1.0' }] } }, '1.0');
+    expect(r.error).toBeUndefined();
+    const task = r.result?.['task'] as Record<string, unknown>;
+    expect(task, 'SendMessageResponse is a oneof payload: { task } | { message }').toBeDefined();
+    expect(task['kind'], '1.0 removed the kind discriminator').toBeUndefined();
+    const status = task['status'] as { state: string; timestamp?: string };
+    expect(status.state).toBe('TASK_STATE_SUBMITTED');
+    expect(typeof status.timestamp).toBe('string');
+    const history = task['history'] as Array<Record<string, unknown>>;
+    expect(history[0]?.['role']).toBe('ROLE_USER');
+    const part = (history[0]?.['parts'] as Array<Record<string, unknown>>)[0]!;
+    expect(part['text']).toBe('hello 1.0');
+    expect(part['kind'], 'Part is a oneof — discriminate by member presence').toBeUndefined();
+    expect(Array.isArray(task['artifacts'])).toBe(true);
+  });
+
+  it('GetTask / CancelTask / ListTasks per §D.1, incl. TASK_NOT_CANCELABLE on a terminal task', async () => {
+    peer.reset();
+    const sent = await rpc(peer.endpoint(), 'SendMessage', { message: { messageId: 'm4', role: 'ROLE_USER', parts: [{ text: 'x' }] } }, '1.0');
+    const id = (sent.result?.['task'] as { id: string }).id;
+    const got = await rpc(peer.endpoint(), 'GetTask', { id }, '1.0');
+    expect((got.result as { status: { state: string } }).status.state).toBe('TASK_STATE_SUBMITTED');
+    const listed = await rpc(peer.endpoint(), 'ListTasks', { status: 'TASK_STATE_SUBMITTED' }, '1.0');
+    expect((listed.result as { totalSize: number }).totalSize).toBe(1);
+    const cancelled = await rpc(peer.endpoint(), 'CancelTask', { id }, '1.0');
+    expect((cancelled.result as { status: { state: string } }).status.state).toBe('TASK_STATE_CANCELED');
+    const again = await rpc(peer.endpoint(), 'CancelTask', { id }, '1.0');
+    expect(again.error?.code).toBe(-32002);
+    expect(again.error?.data?.['reason']).toBe('TASK_NOT_CANCELABLE');
+    const missing = await rpc(peer.endpoint(), 'GetTask', { id: 'nope' }, '1.0');
+    expect(missing.error?.code).toBe(-32001);
+    expect(missing.error?.data?.['reason']).toBe('TASK_NOT_FOUND');
+  });
+
+  it('a 0.3 method name under a 1.0 header is method-not-found — loudly', async () => {
+    const r = await rpc(peer.endpoint(), 'message/send', { message: { parts: [] } }, '1.0');
+    expect(r.status).toBe(404);
+    expect(r.error?.code).toBe(-32601);
+  });
+
+  it('streaming is honestly unsupported: SubscribeToTask ⇒ UNSUPPORTED_OPERATION, matching capabilities.streaming=false', async () => {
+    const r = await rpc(peer.endpoint(), 'SubscribeToTask', { id: 'task-1' }, '1.0');
+    expect(r.error?.code).toBe(-32004);
+  });
+});

package/src/scenarios/a2a-1-0-task-roundtrip.test.ts

@@ -0,0 +1,109 @@
+/**
+ * RFC 0152 §D — the host as an A2A 1.0 SERVER: `SendMessage` → Task → `GetTask`
+ * (the task/event translation leg, host half of the RFC-named
+ * `a2a-1.0-task-roundtrip`).
+ *
+ * `a2a-integration.md` §"A2A 1.0 versioned composition" §D.1/§D.4: `SendMessage`
+ * (JSON-RPC method name, `A2A-Version: 1.0`) with no `taskId` creates a run and
+ * returns `{ task }`; `Task.id` IS the backing `runId` (RFC 0100); `status.state`
+ * is the 1.0 spelling projected via the D.4 bijection; `Part` is a oneof (no
+ * `kind`); `history[].role` is `ROLE_*`; `GetTask` reads it back; an unknown id
+ * is `TASK_NOT_FOUND` (`-32001`) — the same answer a cross-tenant id gets (§E,
+ * no enumeration).
+ *
+ * The endpoint is discovered the way a peer would: from the host's own Agent
+ * Card, `supportedInterfaces[]` with `protocolBinding: "JSONRPC"` and
+ * `protocolVersion: "1.0"`. Auth: the host's normal API credential is sent as
+ * the bearer, so the peer principal resolves to the conformance caller.
+ *
+ * Gate: `capabilities.a2a.profiles` contains `a2a-1.0` — a 0.3 host soft-skips
+ * (`blocked`) and this becomes its witness when it flips. Hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`.
+ *
+ * @see spec/v1/a2a-integration.md §"A2A 1.0 versioned composition" §D.1, §D.4, §E
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+const PROFILE = 'a2a-1.0';
+const STATES_10 = [
+  'TASK_STATE_SUBMITTED', 'TASK_STATE_WORKING', 'TASK_STATE_INPUT_REQUIRED', 'TASK_STATE_AUTH_REQUIRED',
+  'TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED',
+];
+
+interface A2ACaps {
+  readonly supported?: boolean;
+  readonly agentCardUrl?: string;
+  readonly profiles?: readonly string[];
+}
+
+async function a2a(): Promise<A2ACaps | undefined> {
+  const disco = await driver.get('/.well-known/openwop');
+  return capabilityFamily<A2ACaps>(disco.json, 'a2a');
+}
+
+async function claims10(): Promise<boolean> {
+  const caps = await a2a();
+  return caps?.supported === true && (caps.profiles ?? []).includes('a2a-1.0');
+}
+
+async function jsonrpc10Url(): Promise<string | null> {
+  const caps = await a2a();
+  if (typeof caps?.agentCardUrl !== 'string') return null;
+  const res = await fetch(caps.agentCardUrl, { headers: { accept: 'application/json' } });
+  if (res.status !== 200) return null;
+  const card = (await res.json()) as { supportedInterfaces?: Array<{ url?: string; protocolBinding?: string; protocolVersion?: string }> };
+  const iface = (card.supportedInterfaces ?? []).find((i) => i.protocolBinding === 'JSONRPC' && i.protocolVersion === '1.0');
+  return typeof iface?.url === 'string' ? iface.url : null;
+}
+
+async function rpc10(url: string, method: string, params: unknown, id: number) {
+  const headers: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json', 'A2A-Version': '1.0' };
+  const key = process.env.OPENWOP_API_KEY;
+  if (key) headers['authorization'] = `Bearer ${key}`;
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }) });
+  const body = (await res.json().catch(() => ({}))) as { result?: Record<string, unknown>; error?: { code: number; message: string; data?: Record<string, unknown> } };
+  return { status: res.status, ...body };
+}
+
+describe('RFC 0152 §D — a2a-1.0-task-roundtrip (host as A2A 1.0 server, gated on a2a.profiles ∋ a2a-1.0)', () => {
+  it('SendMessage @1.0 creates a task whose id is the runId, in 1.0 spelling; GetTask reads it back; unknown id is TASK_NOT_FOUND', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const url = await jsonrpc10Url();
+    expect(url, driver.describe('a2a-integration.md §C', 'a `a2a-1.0` host MUST publish a JSONRPC/1.0 interface in its card')).not.toBeNull();
+    const sent = await rpc10(url!, 'SendMessage', {
+      message: { messageId: `conf-${Date.now()}`, role: 'ROLE_USER', parts: [{ text: 'openwop conformance a2a-1.0 roundtrip' }] },
+      configuration: { returnImmediately: true },
+    }, 1);
+    expect(sent.status, driver.describe('a2a-integration.md §D.1', 'SendMessage MUST be accepted on the 1.0 interface')).toBe(200);
+    expect(sent.error, driver.describe('a2a-integration.md §D.1', `SendMessage MUST NOT error: ${JSON.stringify(sent.error)}`)).toBeUndefined();
+    const result = sent.result ?? {};
+    // SendMessageResponse is a oneof: { task } | { message }. A run-creating host answers with a task.
+    const task = (result['task'] ?? (result['id'] !== undefined ? result : undefined)) as { id?: string; contextId?: string; status?: { state?: string; timestamp?: string }; history?: Array<{ role?: string; parts?: Array<Record<string, unknown>> }>; kind?: unknown } | undefined;
+    expect(task, driver.describe('a2a-integration.md §D.1', 'SendMessage without taskId MUST create a run and return `{ task }`')).toBeDefined();
+    expect(task!.kind, driver.describe('a2a-integration.md §D.5', '1.0 has no `kind` discriminator')).toBeUndefined();
+    expect(typeof task!.id).toBe('string');
+    expect(STATES_10, driver.describe('a2a-integration.md §D.4', 'status.state MUST use the 1.0 TASK_STATE_* spelling')).toContain(task!.status?.state);
+    for (const m of task!.history ?? []) {
+      expect(['ROLE_USER', 'ROLE_AGENT'], driver.describe('a2a-integration.md §D.2', 'history roles are ROLE_*')).toContain(m.role);
+      for (const p of m.parts ?? []) expect(p['kind'], driver.describe('a2a-integration.md §D.3', 'Part is a oneof — no `kind`')).toBeUndefined();
+    }
+    // Task.id IS the runId (RFC 0100): the OpenWOP snapshot for it MUST exist for the same caller.
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(task!.id!)}`);
+    expect(snap.status, driver.describe('a2a-integration.md §D.4', '`Task.id` MUST be the backing runId — GET /v1/runs/{id} resolves it for the same principal')).toBe(200);
+    // GetTask reads it back with the same id and a valid 1.0 state.
+    const got = await rpc10(url!, 'GetTask', { id: task!.id }, 2);
+    expect(got.error).toBeUndefined();
+    const gotTask = (got.result ?? {}) as { id?: string; status?: { state?: string } };
+    expect(gotTask.id).toBe(task!.id);
+    expect(STATES_10).toContain(gotTask.status?.state);
+    // Unknown id — and, per §E, a cross-tenant id — MUST be TASK_NOT_FOUND, never forbidden.
+    const missing = await rpc10(url!, 'GetTask', { id: `run_does_not_exist_${Date.now()}` }, 3);
+    expect(missing.error?.code, driver.describe('a2a-integration.md §D.7/§E', 'an unknown or unreadable task MUST be TASK_NOT_FOUND (-32001) — no enumeration')).toBe(-32001);
+    // Tidy: cancel the run we created (best effort; terminal runs answer TASK_NOT_CANCELABLE which is fine).
+    await rpc10(url!, 'CancelTask', { id: task!.id }, 4);
+  });
+});

package/src/scenarios/a2a-card-runtime-consistency.test.ts

@@ -0,0 +1,167 @@
+/**
+ * RFC 0152 §C — Agent Card ↔ runtime consistency (invariant
+ * `a2a-card-runtime-consistent`, named by RFC 0152 §E).
+ *
+ * `a2a-integration.md` §"A2A 1.0 versioned composition" §C: the card and
+ * `capabilities.a2a` MUST be generated from the same source the runtime routes
+ * on — the SET of `supportedInterfaces[].protocolVersion` MUST equal
+ * `capabilities.a2a.protocolVersions`, `capabilities.streaming` /
+ * `pushNotifications` MUST equal the discovery flags, the interface carrying
+ * `preferredVersion` SHOULD be listed first, `skills[]` MUST be non-empty, and
+ * a `a2a-1.0` host MUST serve the JSON-RPC binding at 1.0 (the mandatory floor).
+ *
+ * This is a BLACK-BOX leg against the host's own two documents — no peer, no
+ * seam: `GET /.well-known/openwop` (`capabilities.a2a`) and
+ * `GET <agentCardUrl>`. Two documents that describe one fact and disagree are
+ * card/runtime drift, which is what the invariant forbids.
+ *
+ * Gate: `capabilities.a2a.profiles` contains `a2a-1.0`. Written against the
+ * 1.0 card shape ONLY (per the host maintainers' explicit ask: do NOT
+ * dual-shape it to pass on 0.3) — a 0.3-card host soft-skips here and records
+ * `blocked`, and this leg becomes its witness the moment it flips the card.
+ * Hard-fails under `OPENWOP_REQUIRE_BEHAVIOR=true`.
+ *
+ * @see spec/v1/a2a-integration.md §"A2A 1.0 versioned composition" §C
+ */
+
+import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+const PROFILE = 'a2a-1.0';
+
+interface A2ACaps {
+  readonly supported?: boolean;
+  readonly agentCardUrl?: string;
+  readonly streaming?: boolean;
+  readonly pushNotifications?: boolean;
+  readonly protocolVersions?: readonly string[];
+  readonly preferredVersion?: string;
+  readonly profiles?: readonly string[];
+}
+
+interface Card10 {
+  name?: string;
+  description?: string;
+  version?: string;
+  supportedInterfaces?: Array<{ url?: string; protocolBinding?: string; protocolVersion?: string; tenant?: string }>;
+  capabilities?: { streaming?: boolean; pushNotifications?: boolean; extensions?: unknown[]; extendedAgentCard?: boolean };
+  skills?: Array<{ id?: string; name?: string }>;
+  url?: unknown;
+  protocolVersion?: unknown;
+}
+
+async function a2a(): Promise<A2ACaps | undefined> {
+  const disco = await driver.get('/.well-known/openwop');
+  return capabilityFamily<A2ACaps>(disco.json, 'a2a');
+}
+
+async function claims10(): Promise<boolean> {
+  const caps = await a2a();
+  return caps?.supported === true && (caps.profiles ?? []).includes('a2a-1.0');
+}
+
+async function fetchCard(caps: A2ACaps): Promise<Card10 | null> {
+  if (typeof caps.agentCardUrl !== 'string') return null;
+  // A 1.0 client MUST declare the version on the card GET too (a2a-integration.md
+  // §C, decided 2026-08-16 — S18 Q1): header-less means 0.3 by the receiver rule,
+  // so a host that still advertises `a2a-0.3-legacy` serves the 0.3-shaped card
+  // header-less and the 1.0 card only when asked for it. Fetching header-less
+  // and asserting the 1.0 shape (as this leg did until today) forced the host to
+  // break every 0.3 client reading `card.url` NOW instead of at the legacy sunset.
+  const res = await fetch(caps.agentCardUrl, { headers: { accept: 'application/json', 'A2A-Version': '1.0' } });
+  if (res.status !== 200) return null;
+  return (await res.json()) as Card10;
+}
+
+describe('RFC 0152 §C — a2a-card-runtime-consistent (gated on a2a.profiles ∋ a2a-1.0)', () => {
+  it('the card is 1.0-shaped and reachable at agentCardUrl', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const caps = (await a2a())!;
+    const card = await fetchCard(caps);
+    expect(card, driver.describe('a2a-integration.md §C', '`agentCardUrl` MUST resolve to the Agent Card (200)')).not.toBeNull();
+    expect(
+      Array.isArray(card!.supportedInterfaces) && card!.supportedInterfaces!.length > 0,
+      driver.describe('a2a-integration.md §C', 'a host claiming `a2a-1.0` MUST publish a 1.0 card: `supportedInterfaces[]` REQUIRED (≥1)'),
+    ).toBe(true);
+    expect(card!.url, driver.describe('a2a-integration.md §C', '1.0 removed the top-level `url` — a card with both shapes is neither')).toBeUndefined();
+    expect(card!.protocolVersion, driver.describe('a2a-integration.md §C', '1.0 removed the top-level `protocolVersion` (per interface now)')).toBeUndefined();
+    expect(Array.isArray(card!.skills) && card!.skills!.length > 0, driver.describe('a2a-integration.md §C', '`skills[]` MUST be non-empty — one per invocable workflow')).toBe(true);
+  });
+
+  it('a header-less card GET returns the 0.3-shaped card while a2a-0.3-legacy is advertised (§B receiver rule applied to discovery — S18 Q1)', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const caps = (await a2a())!;
+    if (typeof caps.agentCardUrl !== 'string') return softSkip('blocked', 'no agentCardUrl advertised');
+    const legacy = (caps.protocolVersions ?? []).includes('0.3');
+    const res = await fetch(caps.agentCardUrl, { headers: { accept: 'application/json' } });
+    expect(res.status, driver.describe('a2a-integration.md §C', 'a header-less card GET MUST succeed — discovery must not fail')).toBe(200);
+    const card = (await res.json()) as Card10 & { url?: string; protocolVersion?: string };
+    if (legacy) {
+      // While 0.3 is advertised the header-less card is the 0.3 shape: an
+      // external 0.3 client reading `card.url` keeps working through the
+      // legacy window — the point of advertising `a2a-0.3-legacy` at all.
+      expect(typeof card.url, driver.describe('a2a-integration.md §C', 'header-less = 0.3 (§B receiver rule): the card MUST carry the 0.3 top-level `url` while `protocolVersions ∋ 0.3`')).toBe('string');
+      expect(card.supportedInterfaces, driver.describe('a2a-integration.md §C', 'the header-less card MUST NOT be the 1.0 shape while 0.3 is advertised (a card with both shapes is neither)')).toBeUndefined();
+    } else {
+      // 0.3 dropped: the preferred-version (1.0) card is served header-less.
+      expect(Array.isArray(card.supportedInterfaces) && card.supportedInterfaces!.length > 0, driver.describe('a2a-integration.md §C', 'with 0.3 dropped, the header-less card is the preferredVersion (1.0) card')).toBe(true);
+    }
+  });
+
+  it('the set of supportedInterfaces[].protocolVersion equals capabilities.a2a.protocolVersions', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const caps = (await a2a())!;
+    const card = await fetchCard(caps);
+    if (card === null) return; // asserted above
+    const fromCard = [...new Set((card.supportedInterfaces ?? []).map((i) => i.protocolVersion).filter((v): v is string => typeof v === 'string'))].sort();
+    const fromDiscovery = [...new Set(caps.protocolVersions ?? [])].sort();
+    expect(
+      fromCard,
+      driver.describe(
+        'a2a-integration.md §C',
+        'the SET of `supportedInterfaces[].protocolVersion` MUST equal `capabilities.a2a.protocolVersions` — two documents, one fact; ' +
+          'a version advertised in one and not the other is card/runtime drift (`a2a-card-runtime-consistent`)',
+      ),
+    ).toEqual(fromDiscovery);
+  });
+
+  it('a2a-1.0 MUST serve the JSON-RPC binding at 1.0 (the mandatory floor), and SHOULD list the preferred interface first', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const caps = (await a2a())!;
+    const card = await fetchCard(caps);
+    if (card === null) return;
+    const ifaces = card.supportedInterfaces ?? [];
+    expect(
+      ifaces.some((i) => i.protocolBinding === 'JSONRPC' && i.protocolVersion === '1.0' && typeof i.url === 'string'),
+      driver.describe('a2a-integration.md §C', 'the `a2a-1.0` profile floor is the JSON-RPC binding at 1.0; HTTP+JSON / gRPC are optional additions'),
+    ).toBe(true);
+    for (const i of ifaces) {
+      expect(['JSONRPC', 'GRPC', 'HTTP+JSON'], driver.describe('a2a-integration.md §C', 'protocolBinding uses the upstream binding names')).toContain(i.protocolBinding);
+    }
+    if (typeof caps.preferredVersion === 'string' && ifaces.length > 0) {
+      // SHOULD, so a soft expectation: report, do not fail.
+      if (ifaces[0]?.protocolVersion !== caps.preferredVersion) {
+        // eslint-disable-next-line no-console
+        console.warn(`[a2a-card-runtime-consistency] SHOULD: the interface carrying preferredVersion (${caps.preferredVersion}) is not listed first`);
+      }
+    }
+  });
+
+  it('card capabilities.streaming / pushNotifications equal the discovery flags', async () => {
+    if (!behaviorGate(PROFILE, await claims10())) return;
+    const caps = (await a2a())!;
+    const card = await fetchCard(caps);
+    if (card === null) return;
+    expect(
+      card.capabilities?.streaming === true,
+      driver.describe('a2a-integration.md §C', '`capabilities.streaming` on the card MUST equal `capabilities.a2a.streaming` on discovery'),
+    ).toBe(caps.streaming === true);
+    expect(
+      card.capabilities?.pushNotifications === true,
+      driver.describe('a2a-integration.md §C', '`capabilities.pushNotifications` on the card MUST equal `capabilities.a2a.pushNotifications`'),
+    ).toBe(caps.pushNotifications === true);
+  });
+});