@openwop/openwop-conformance 2.45.14 → 2.45.16

package/src/lib/provider-usage-witness.ts

@@ -0,0 +1,63 @@
+/**
+ * The `provider.usage` emission witness (`events.md` §`providerUsage`): "A
+ * host advertising `providerUsage` MUST emit exactly one `provider.usage` per
+ * LLM provider invocation, before that node's `node.completed`."
+ *
+ * Driven on `conformance-context-budget-live` — a supervisor on the host's LIVE
+ * model (the fixture's catalog entry forbids a mock), so a completed run made
+ * at least one provider invocation. From outside, the number of invocations
+ * is unknowable, so "exactly one per invocation" is NOT asserted; what is:
+ *   emitted   at least one `provider.usage` is on the log;
+ *   ordering  each one precedes a `node.completed` of the node it names (or,
+ *             when it names none, some `node.completed`);
+ *   payload   each payload validates against the v2 `providerUsage` def (whose
+ *             closed shape also keeps credential refs and prompt text out).
+ *
+ * {@link driveUsage} observes and asserts nothing; {@link judgeUsage} is pure,
+ * proven in `provider-usage-witness.test.ts`.
+ */
+
+import { isFixtureAdvertised } from './fixtures.js';
+import type { MajorProfile } from './major-profile.js';
+import { finding, observed, observeRun, skip, type ObservedRun, type ObserveOpts, type Outcome, type Skip, type Validate } from './fixture-run-observer.js';
+
+export const LIVE_FIXTURE = 'conformance-context-budget-live';
+const DOC = 'events.md §providerUsage';
+
+export interface UsageObservation { readonly run: ObservedRun; readonly usageType: string }
+
+/** The `providerUsage` record, the live fixture, and this major's event name. */
+export function usageGate(profile: MajorProfile, doc: unknown): Skip | { usageType: string } {
+  if (profile.family(doc, 'providerUsage') === null) return skip('inapplicable', 'the host does not advertise providerUsage');
+  if (!isFixtureAdvertised(LIVE_FIXTURE)) return skip('inapplicable', `fixture ${LIVE_FIXTURE} is not advertised — the fixture is the opt-in (a host whose supervisor has no live model must not advertise it)`);
+  const usageType = profile.eventType('provider.usage');
+  if (usageType === undefined) return skip('blocked', 'the event codemap is not on disk in this layout — the suite will not guess an event name');
+  return { usageType };
+}
+
+/** Run the live fixture. Asserts nothing. */
+export async function driveUsage(profile: MajorProfile, doc: unknown, opts: ObserveOpts = {}): Promise<Skip | UsageObservation> {
+  const g = usageGate(profile, doc);
+  if ('kind' in g) return g;
+  return { run: await observeRun(profile, LIVE_FIXTURE, { timeoutMs: 300_000, pollMs: 1000, ...opts }), ...g };
+}
+
+/** Emission, ordering and payload shape. Pure. */
+export function judgeUsage(o: UsageObservation, validate: Validate): Outcome {
+  const usage = o.run.events.filter((e) => e.type === o.usageType);
+  const completions = o.run.events.filter((e) => e.type === 'node.completed');
+  if (o.run.createStatus !== 201 && o.run.createStatus !== 202) {
+    return observed([finding(false, 'runs.md createRun', `createRun of ${LIVE_FIXTURE} MUST be accepted (got ${o.run.createStatus})`)]);
+  }
+  if (usage.length === 0 && o.run.terminalStatus !== 'completed') {
+    return skip('blocked', `the live run ended ${String(o.run.terminalStatus)} with no ${o.usageType} — no provider invocation is shown to have happened`);
+  }
+  return observed([
+    finding(usage.length > 0, DOC, `a completed run of a live-model supervisor MUST carry at least one ${o.usageType} (got none)`),
+    ...usage.map((u) => {
+      const after = completions.some((c) => c.sequence > u.sequence && (u.nodeId === undefined || c.nodeId === u.nodeId));
+      return finding(after, DOC, `${o.usageType} (seq ${u.sequence}${u.nodeId === undefined ? '' : `, node ${u.nodeId}`}) MUST precede that node's node.completed`);
+    }),
+    ...usage.map((u) => { const v = validate(u.payload); return finding(v.ok, 'schemas run-event-payloads providerUsage', `every ${o.usageType} payload MUST validate (seq ${u.sequence}): ${v.errors}`); }),
+  ]);
+}

package/src/lib/run-bounds-witness.ts

@@ -0,0 +1,111 @@
+/**
+ * The run execution-bounds witness (`runs.md` §`run` section; RFC 0058), shared
+ * by every major that gives a run a wire surface for `runTimeoutMs`.
+ *
+ * Three legs:
+ *   shape       advertised `limits.maxRunDurationMs` is an integer ≥ 1000 and
+ *               `limits.maxLoopIterations` an integer ≥ 1, when present;
+ *   refused     an out-of-range `runTimeoutMs` (0, below the schema minimum of 1)
+ *               is refused `400 validation_error` at create — unaided;
+ *   breach      a run of the `conformance-run-duration-breach` fixture with a
+ *               1 s `runTimeoutMs` ends `failed` with `run_timeout` and emits
+ *               `cap.breached { kind: 'run-duration' }` with `observed > limit`.
+ *
+ * Two halves: the drivers observe and assert nothing; {@link judgeBreach} is pure,
+ * proven in `run-bounds-witness.test.ts`.
+ */
+
+import { driver } from './driver.js';
+import { readErrorCode } from './error-envelope.js';
+import { isFixtureAdvertised } from './fixtures.js';
+import type { MajorProfile } from './major-profile.js';
+
+export const TIMEOUT_FIXTURE = 'conformance-run-duration-breach';
+const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export interface BoundsFinding { readonly ok: boolean; readonly doc: string; readonly message: string }
+export type BoundsOutcome =
+  | { readonly kind: 'skip'; readonly disposition: 'inapplicable' | 'blocked'; readonly reason: string }
+  | { readonly kind: 'observed'; readonly findings: readonly BoundsFinding[] };
+
+const DOC = 'runs.md §run section';
+const f = (ok: boolean, message: string): BoundsFinding => ({ ok, doc: DOC, message });
+
+/** The `run` section fragment that carries a `runTimeoutMs` at this major. */
+function runTimeout(profile: MajorProfile, ms: number): Record<string, unknown> {
+  return profile.major >= 2 ? { configurable: { version: 1, run: { runTimeoutMs: ms } } } : { configurable: { runTimeoutMs: ms } };
+}
+
+/** Leg 1, shape: judged from the discovery record alone. */
+export function shapeLeg(profile: MajorProfile, discovery: unknown): BoundsOutcome {
+  const limits = profile.family(discovery, 'limits');
+  if (limits === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise limits' };
+  const findings: BoundsFinding[] = [];
+  const dur = limits['maxRunDurationMs'];
+  const loops = limits['maxLoopIterations'];
+  if (dur !== undefined) findings.push(f(Number.isInteger(dur) && (dur as number) >= 1000, `limits.maxRunDurationMs MUST be an integer >= 1000 when present (got ${JSON.stringify(dur)})`));
+  if (loops !== undefined) findings.push(f(Number.isInteger(loops) && (loops as number) >= 1, `limits.maxLoopIterations MUST be an integer >= 1 when present (got ${JSON.stringify(loops)})`));
+  if (findings.length === 0) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host advertises neither limits.maxRunDurationMs nor limits.maxLoopIterations' };
+  return { kind: 'observed', findings };
+}
+
+/** Leg 2, refused: an out-of-range runTimeoutMs is refused at create. Unaided: any advertised fixture names a valid workflow. */
+export async function refusedLeg(profile: MajorProfile, workflowId: string | undefined): Promise<BoundsOutcome> {
+  if (workflowId === undefined) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host advertises no fixture workflow to name in a create, so a refusal cannot be told from an unknown workflow' };
+  const res = await driver.post(profile.runsPath, { workflowId, ...runTimeout(profile, 0) });
+  if (res.status === 201 || res.status === 202) {
+    const runId = isRecord(res.json) ? res.json['runId'] : undefined;
+    if (typeof runId === 'string') await driver.post(`${profile.runsPath}/${profile.idSegment(runId)}/cancel`, {}).catch(() => undefined);
+  }
+  return { kind: 'observed', findings: [
+    f(res.status === 400, `runTimeoutMs: 0 (below the minimum of 1) MUST be refused 400 at create (got ${res.status})`),
+    f(readErrorCode(res.json) === 'validation_error', `the refusal MUST carry validation_error (got ${String(readErrorCode(res.json))})`),
+  ] };
+}
+
+export interface BreachObservation {
+  readonly createStatus: number;
+  readonly terminalStatus: string | undefined;
+  readonly errorCode: string | undefined;
+  readonly breach: Record<string, unknown> | undefined;
+}
+
+/** Leg 3, breach, observed: a fixture run with a 1 s runTimeoutMs. Asserts nothing. */
+export async function driveBreach(profile: MajorProfile, opts: { timeoutMs?: number; pollMs?: number } = {}): Promise<Extract<BoundsOutcome, { kind: 'skip' }> | BreachObservation> {
+  if (!isFixtureAdvertised(TIMEOUT_FIXTURE)) return { kind: 'skip', disposition: 'inapplicable', reason: `fixture ${TIMEOUT_FIXTURE} is not advertised — the host does not claim a run long enough to breach a 1 s timeout` };
+  const created = await driver.post(profile.runsPath, { workflowId: TIMEOUT_FIXTURE, ...runTimeout(profile, 1000) });
+  const runId = isRecord(created.json) ? created.json['runId'] : undefined;
+  if ((created.status !== 201 && created.status !== 202) || typeof runId !== 'string') {
+    return { createStatus: created.status, terminalStatus: undefined, errorCode: readErrorCode(created.json), breach: undefined };
+  }
+  const deadline = Date.now() + (opts.timeoutMs ?? 20_000);
+  let snap: Record<string, unknown> = {};
+  for (;;) {
+    const r = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}`);
+    snap = isRecord(r.json) ? r.json : {};
+    if (['completed', 'failed', 'cancelled'].includes(String(snap['status'])) || Date.now() > deadline) break;
+    await new Promise((res) => setTimeout(res, opts.pollMs ?? 500));
+  }
+  const poll = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}/events/poll`);
+  const events = ((poll.json as { events?: unknown } | undefined)?.events as Array<Record<string, unknown>> | undefined) ?? [];
+  const capType = profile.eventType('cap.breached') ?? 'cap.breached';
+  const breach = events.find((e) => e['type'] === capType);
+  const err = isRecord(snap['error']) ? snap['error'] : undefined;
+  return { createStatus: created.status, terminalStatus: typeof snap['status'] === 'string' ? (snap['status'] as string) : undefined, errorCode: typeof err?.['code'] === 'string' ? (err['code'] as string) : undefined, breach: isRecord(breach?.['payload']) ? (breach!['payload'] as Record<string, unknown>) : undefined };
+}
+
+/** Leg 3, breach, judged. Pure. */
+export function judgeBreach(o: BreachObservation): BoundsFinding[] {
+  const out = [f(o.createStatus === 201 || o.createStatus === 202, `a create with runTimeoutMs: 1000 MUST be accepted (got ${o.createStatus})`)];
+  if (!out[0]!.ok) return out;
+  const observed = o.breach?.['observed'];
+  const limit = o.breach?.['limit'];
+  out.push(
+    f(o.terminalStatus === 'failed', `a run exceeding runTimeoutMs MUST end failed (got ${String(o.terminalStatus)})`),
+    f(o.errorCode === 'run_timeout', `the run's error.code MUST be run_timeout (got ${String(o.errorCode)})`),
+    f(o.breach !== undefined, 'a cap.breached event MUST be emitted on the breach'),
+    f(o.breach?.['kind'] === 'run-duration', `cap.breached.kind MUST be run-duration (got ${String(o.breach?.['kind'])})`),
+    f(typeof observed === 'number' && typeof limit === 'number' && observed > limit, `cap.breached.observed MUST exceed limit (got observed=${String(observed)}, limit=${String(limit)})`),
+  );
+  return out;
+}

package/src/lib/run-graph-double.ts

@@ -0,0 +1,144 @@
+/**
+ * A run-graph double: the smallest HTTP server the wave-2 fixture witnesses
+ * (sub-workflow linkage and input mapping, dispatch input mapping, the
+ * dispatch loop, provider usage) and the artifact schema-URL witness can be
+ * proven against, in both directions.
+ *
+ * `ScratchHost` plays one run per create. These witnesses follow a parent run
+ * to the child it started, read the child's snapshot (`variables`, `inputs`)
+ * and its `getRunAncestry` answer, and fetch paths outside the run surface,
+ * so this double lets a case script a parent that spawns children, and answer
+ * any other GET.
+ *
+ * It is a test double, not a host: it executes nothing, and nothing it does is
+ * evidence about any implementation. Ids are tenant-bound (`<tenant>/<opaque>`,
+ * `ids.schema.json#/$defs/runId`) and accepted `~`-projected or percent-encoded.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { unprojectBoundId } from './bound-id.js';
+
+export interface DoubleEvent {
+  readonly type: string;
+  /** The envelope's top-level `nodeId`. */
+  readonly nodeId?: string | undefined;
+  readonly payload?: Record<string, unknown> | undefined;
+}
+export interface DoubleRun {
+  readonly workflowId?: string;
+  readonly status: string;
+  readonly variables?: Record<string, unknown> | undefined;
+  readonly inputs?: Record<string, unknown> | undefined;
+  readonly events?: readonly DoubleEvent[];
+  /** The `GET /runs/{runId}/ancestry` answer, given the run's own id. Unset: 404. */
+  readonly ancestry?: ((self: string) => { readonly status: number; readonly body: unknown }) | undefined;
+}
+export interface RawAnswer { readonly status: number; readonly headers?: Readonly<Record<string, string>>; readonly body: string }
+export interface DoubleOptions {
+  readonly discovery: Readonly<Record<string, unknown>>;
+  /**
+   * The run a create makes. `spawn` stores a further run (a child) and returns
+   * its id; `self` is the id the created run will carry. Unset: every create is 404.
+   */
+  readonly onCreate?: ((workflowId: string, spawn: (run: DoubleRun) => string, self: string) => DoubleRun | undefined) | undefined;
+  /** Any other GET, by path. `undefined` is 404. */
+  readonly onGet?: ((path: string) => RawAnswer | undefined) | undefined;
+}
+
+export const DOUBLE_TENANT = 'tenant-a';
+
+export class RunGraphDouble {
+  private server: Server | undefined;
+  private readonly runs = new Map<string, DoubleRun>();
+  private seq = 0;
+  url = '';
+
+  constructor(private opts: DoubleOptions) {}
+
+  /** Swap behaviour between cases. The address stays the same, since the driver caches its base URL per file. */
+  reconfigure(next: Partial<DoubleOptions>): void {
+    this.opts = { ...this.opts, ...next };
+    this.runs.clear();
+  }
+
+  get discovery(): Readonly<Record<string, unknown>> { return this.opts.discovery; }
+
+  async start(): Promise<string> {
+    this.server = createServer((req, res) => { void this.handle(req, res); });
+    await new Promise<void>((r) => this.server!.listen(0, '127.0.0.1', r));
+    this.url = `http://127.0.0.1:${(this.server.address() as AddressInfo).port}`;
+    return this.url;
+  }
+
+  async stop(): Promise<void> {
+    const s = this.server;
+    if (s === undefined) return;
+    s.closeAllConnections();
+    await new Promise<void>((r) => s.close(() => r()));
+  }
+
+  private mint(): string { return `${DOUBLE_TENANT}/run-${String(++this.seq).padStart(16, '0')}`; }
+
+  private send(res: ServerResponse, status: number, body: unknown, headers: Readonly<Record<string, string>> = {}): void {
+    res.writeHead(status, { 'content-type': 'application/json', ...headers });
+    res.end(typeof body === 'string' ? body : JSON.stringify(body));
+  }
+
+  private async body(req: IncomingMessage): Promise<Record<string, unknown>> {
+    const chunks: Buffer[] = [];
+    for await (const c of req) chunks.push(c as Buffer);
+    try {
+      const v: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+    } catch { return {}; }
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const path = (req.url ?? '/').split('?')[0] ?? '/';
+    if (req.method === 'GET' && path === '/.well-known/openwop') return this.send(res, 200, this.opts.discovery);
+
+    if (req.method === 'POST' && path === '/runs') {
+      const workflowId = String((await this.body(req))['workflowId'] ?? '');
+      const self = this.mint();
+      const run = this.opts.onCreate?.(workflowId, (child) => { const id = this.mint(); this.runs.set(id, child); return id; }, self);
+      if (run === undefined) return this.send(res, 404, { error: 'not_found', message: `no workflow ${workflowId}` });
+      this.runs.set(self, { workflowId, ...run });
+      return this.send(res, 201, { runId: self, status: 'running' });
+    }
+
+    const m = /^\/runs\/([^/]+)(\/events\/poll|\/ancestry)?$/.exec(path);
+    if (req.method === 'GET' && m) {
+      const seg = m[1] as string;
+      const id = seg.includes('~') ? unprojectBoundId(seg) : decodeURIComponent(seg);
+      const run = this.runs.get(id);
+      if (run === undefined) return this.send(res, 404, { error: 'not_found', message: 'no such run' });
+      if (m[2] === '/ancestry') {
+        const a = run.ancestry?.(id);
+        return a === undefined ? this.send(res, 404, { error: 'not_found', message: 'ancestry not served' }) : this.send(res, a.status, a.body);
+      }
+      if (m[2] === '/events/poll') {
+        const events = (run.events ?? []).map((e, i) => ({
+          eventId: `e${i + 1}`, runId: id, type: e.type, ...(e.nodeId === undefined ? {} : { nodeId: e.nodeId }),
+          payload: e.payload ?? {}, sequence: i + 1, schemaVersion: 2, timestamp: new Date(0).toISOString(),
+        }));
+        return this.send(res, 200, { events });
+      }
+      return this.send(res, 200, {
+        runId: id, workflowId: run.workflowId ?? 'double', status: run.status,
+        ...(run.variables === undefined ? {} : { variables: run.variables }),
+        ...(run.inputs === undefined ? {} : { inputs: run.inputs }),
+      });
+    }
+
+    if (req.method === 'GET') {
+      const raw = this.opts.onGet?.(path);
+      if (raw !== undefined) {
+        res.writeHead(raw.status, { ...(raw.headers ?? {}) });
+        res.end(raw.body);
+        return;
+      }
+    }
+    return this.send(res, 404, { error: 'not_found', message: 'no such route' });
+  }
+}

package/src/lib/scratch-host.ts

@@ -16,6 +16,7 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import type { MajorProfile } from './major-profile.js';
+import { unprojectBoundId } from './bound-id.js';
 
 export interface ScriptedEvent { readonly type: string; readonly payload?: Record<string, unknown> | undefined }
 export interface ScriptedRun {
@@ -112,7 +113,9 @@ export class ScratchHost {
     if (req.method === 'POST' && path === `${runs}:bulk-cancel`) return this.send(res, 200, { results: [] });
 
     const m = new RegExp(`^${runs}/([^/]+)(/events/poll|/events|/cancel)?$`).exec(path);
-    const stored = m ? this.runs.get(decodeURIComponent(m[1] as string)) : undefined;
+    // A bound id arrives `~`-projected (identity.md §5) or percent-encoded; accept both.
+    const seg = m ? (m[1] as string) : '';
+    const stored = m ? this.runs.get(seg.includes('~') ? unprojectBoundId(seg) : decodeURIComponent(seg)) : undefined;
     if (!m || stored === undefined) return this.send(res, 404, { error: 'not_found', message: 'no such route or run' });
     const tail = m[2];
     if (tail === '/cancel') return this.send(res, 200, { status: 'cancelled' });

package/src/lib/subworkflow-witness.ts

@@ -0,0 +1,192 @@
+/**
+ * The `core.subWorkflow` witness (`execution.md` §`subWorkflow`), a fixture
+ * port through `POST /runs` and `events/poll`. No seam.
+ *
+ * Linkage, on `conformance-subworkflow-parent` → `conformance-subworkflow-child`:
+ *   output         the parent's `node.completed` for `subwf-call` carries
+ *                  `outputs.childRunId` and `outputs.childStatus`
+ *                  (`completed | failed | cancelled`), and the status names the
+ *                  child's real terminal status;
+ *   outputMapping  after the child completes, the mapped variable is copied
+ *                  into the parent (`childOutcome` ← child `childResult`);
+ *   ancestry       where `getRunAncestry` is served (advertised by
+ *                  `multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported`),
+ *                  the child's `parent` is the parent run with
+ *                  `cause: "core.subWorkflow"`.
+ * The v1 `parentRunId`/`parentNodeId` child-linkage leg is RETIRED at v2
+ * (`spec/v1/migrations.json` C4.18): `parentRunId` is fork lineage, not this link.
+ *
+ * Input mapping, on `conformance-subworkflow-input-mapping[-no-default]` →
+ * `conformance-subworkflow-input-mapping-child` (child default `receivedPrdId: "baked-in"`):
+ *   seed      the child's variable bag is seeded: `receivedPrdId` is present;
+ *   override  the mapping lands after and over the default: `"prd-1"`;
+ *   unset     an unset parent variable arrives undefined, never an error or
+ *             `null` (the run completes; the child's value is absent or its
+ *             own default).
+ *
+ * The drivers observe and assert nothing; the judges are pure, proven in
+ * `subworkflow-witness.test.ts`.
+ */
+
+import { driver } from './driver.js';
+import { isFixtureAdvertised } from './fixtures.js';
+import type { MajorProfile } from './major-profile.js';
+import {
+  completionsOf, finding, isRecord, observed, observeRun, readRun, runCompleted, skip,
+  type Finding, type ObservedRun, type ObserveOpts, type Outcome, type RunRead, type Skip, type Validate,
+} from './fixture-run-observer.js';
+
+export const PARENT_FIXTURE = 'conformance-subworkflow-parent';
+export const CHILD_FIXTURE = 'conformance-subworkflow-child';
+export const IM_PARENT_FIXTURE = 'conformance-subworkflow-input-mapping';
+export const IM_NO_DEFAULT_FIXTURE = 'conformance-subworkflow-input-mapping-no-default';
+export const IM_CHILD_FIXTURE = 'conformance-subworkflow-input-mapping-child';
+export const SUBWF_NODE = 'subwf-call';
+
+const DOC = 'execution.md §subWorkflow';
+const CHILD_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+
+/** The child a `core.subWorkflow` node started, as its `node.completed` names it. */
+export interface ChildLink {
+  readonly outputs: Record<string, unknown> | undefined;
+  readonly childRunId: string | undefined;
+  readonly child: RunRead | undefined;
+}
+
+export interface LinkageObservation extends ChildLink {
+  readonly parent: ObservedRun;
+  /** `undefined`: the host does not advertise `getRunAncestry`, so the leg does not bind. */
+  readonly ancestry: { readonly status: number; readonly json: unknown } | undefined;
+}
+export interface MappingObservation extends ChildLink { readonly parent: ObservedRun }
+
+/** Whether the host advertises `getRunAncestry` (`runs.md` §Surface gate). */
+export function ancestryAdvertised(profile: MajorProfile, doc: unknown): boolean {
+  const ma = profile.family(doc, 'multiAgent');
+  const em = isRecord(ma?.['executionModel']) ? ma['executionModel'] : undefined;
+  const chc = isRecord(em?.['crossHostCausation']) ? em['crossHostCausation'] : undefined;
+  return chc?.['ancestryEndpointSupported'] === true;
+}
+
+function fixturesGate(...ids: string[]): Skip | null {
+  for (const id of ids) if (!isFixtureAdvertised(id)) return skip('inapplicable', `fixture ${id} is not advertised — the fixture is the opt-in`);
+  return null;
+}
+
+async function followChild(profile: MajorProfile, parent: ObservedRun): Promise<ChildLink> {
+  const done = completionsOf(parent.events, SUBWF_NODE)[0];
+  const outputs = isRecord(done?.payload['outputs']) ? done.payload['outputs'] : undefined;
+  const childRunId = typeof outputs?.['childRunId'] === 'string' && outputs['childRunId'].length > 0 ? outputs['childRunId'] : undefined;
+  return { outputs, childRunId, child: childRunId === undefined ? undefined : await readRun(profile, childRunId) };
+}
+
+/** Run the linkage fixture and follow it to the child. Asserts nothing. */
+export async function driveLinkage(profile: MajorProfile, doc: unknown, opts: ObserveOpts = {}): Promise<Skip | LinkageObservation> {
+  const g = fixturesGate(PARENT_FIXTURE, CHILD_FIXTURE);
+  if (g) return g;
+  const parent = await observeRun(profile, PARENT_FIXTURE, opts);
+  const link = await followChild(profile, parent);
+  let ancestry: LinkageObservation['ancestry'];
+  if (ancestryAdvertised(profile, doc) && link.childRunId !== undefined) {
+    const r = await driver.get(`${profile.runsPath}/${profile.idSegment(link.childRunId)}/ancestry`);
+    ancestry = { status: r.status, json: r.json };
+  }
+  return { parent, ...link, ancestry };
+}
+
+/** Run an input-mapping fixture and follow it to the child. Asserts nothing. */
+export async function driveInputMapping(profile: MajorProfile, fixture: string, opts: ObserveOpts = {}): Promise<Skip | MappingObservation> {
+  const g = fixturesGate(fixture, IM_CHILD_FIXTURE);
+  if (g) return g;
+  const parent = await observeRun(profile, fixture, opts);
+  return { parent, ...(await followChild(profile, parent)) };
+}
+
+/** Leg: `node.completed` carries `outputs.childRunId` and `outputs.childStatus`. Pure. */
+export function judgeOutput(o: LinkageObservation): Outcome {
+  const out: Finding[] = runCompleted(o.parent);
+  const status = o.outputs?.['childStatus'];
+  const childStatus = o.child?.snapshot['status'];
+  out.push(
+    finding(completionsOf(o.parent.events, SUBWF_NODE).length > 0, `${DOC} (Output)`, `the parent log MUST carry node.completed for the core.subWorkflow node ${SUBWF_NODE}`),
+    finding(o.childRunId !== undefined, `${DOC} (Output)`, `node.completed MUST carry outputs.childRunId (got ${JSON.stringify(o.outputs?.['childRunId'])})`),
+    finding(typeof status === 'string' && CHILD_STATUSES.has(status), `${DOC} (Output)`, `node.completed MUST carry outputs.childStatus, one of completed | failed | cancelled (got ${JSON.stringify(status)})`),
+  );
+  if (o.child !== undefined) {
+    out.push(
+      finding(o.child.status === 200, `${DOC} (Output)`, `outputs.childRunId MUST name a readable run (GET answered ${o.child.status})`),
+      finding(o.child.status !== 200 || status === childStatus, `${DOC} (Output)`, `outputs.childStatus MUST be the child's terminal status (got ${JSON.stringify(status)}, child is ${JSON.stringify(childStatus)})`),
+    );
+  }
+  return observed(out);
+}
+
+/** Leg: the mapped child variable is copied into the parent. Pure. */
+export function judgeOutputMapping(o: LinkageObservation): Outcome {
+  const vars = isRecord(o.parent.snapshot['variables']) ? o.parent.snapshot['variables'] : {};
+  return observed([
+    ...runCompleted(o.parent),
+    finding(vars['childOutcome'] === 'child-completed', `${DOC} (outputMapping)`, `after the child completes, the host MUST copy childResult into the parent's childOutcome ("child-completed"; got ${JSON.stringify(vars['childOutcome'])})`),
+  ]);
+}
+
+/** Leg: the child's ancestry names the parent with `cause: "core.subWorkflow"`. Pure. */
+export function judgeAncestry(o: LinkageObservation, validate: Validate): Outcome {
+  if (o.childRunId === undefined) return skip('blocked', 'the child run id is unobserved (node.completed carried no outputs.childRunId — the output leg convicts that), so its ancestry cannot be read');
+  if (o.ancestry === undefined) return skip('inapplicable', 'the host does not advertise multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported, so getRunAncestry is not served');
+  const body = o.ancestry.json;
+  const parent = isRecord(body) && isRecord(body['parent']) ? body['parent'] : undefined;
+  const v = validate(body);
+  return observed([
+    finding(o.ancestry.status === 200, `${DOC} (Parent link); runs.md §Diff and ancestry`, `getRunAncestry of the child MUST answer 200 (got ${o.ancestry.status})`),
+    finding(v.ok, 'schemas run-ancestry-response', `the ancestry body MUST validate: ${v.errors}`),
+    finding(parent !== undefined && parent['runId'] === o.parent.runId, `${DOC} (Parent link)`, `the child's parent MUST be the parent run ${String(o.parent.runId)} (got ${JSON.stringify(parent?.['runId'] ?? (isRecord(body) ? body['parent'] : undefined))})`),
+    finding(parent?.['cause'] === 'core.subWorkflow', `${DOC} (Parent link)`, `the child's parent.cause MUST be core.subWorkflow (got ${JSON.stringify(parent?.['cause'])})`),
+  ]);
+}
+
+const childVars = (o: MappingObservation): Record<string, unknown> | undefined =>
+  o.child !== undefined && o.child.status === 200 ? (isRecord(o.child.snapshot['variables']) ? o.child.snapshot['variables'] : {}) : undefined;
+
+function childReached(o: MappingObservation): Finding[] {
+  return [
+    ...runCompleted(o.parent),
+    finding(o.childRunId !== undefined, `${DOC} (Output)`, `the parent's node.completed for ${SUBWF_NODE} MUST carry outputs.childRunId`),
+    finding(o.child?.status === 200, `${DOC} (Output)`, `outputs.childRunId MUST name a readable run (GET answered ${String(o.child?.status)})`),
+    finding(o.child?.snapshot['status'] === 'completed', `fixtures.md ${IM_CHILD_FIXTURE}`, `the child run MUST end completed (got ${JSON.stringify(o.child?.snapshot['status'])})`),
+  ];
+}
+
+/** Leg: the child's variable bag is seeded at creation — `receivedPrdId` is present. Pure. */
+export function judgeSeed(o: MappingObservation): Outcome {
+  const v = childVars(o)?.['receivedPrdId'];
+  return observed([
+    ...childReached(o),
+    finding(v !== undefined && v !== null, `${DOC} (inputMapping: defaultValue MUST seed first)`, `the child's receivedPrdId MUST be seeded at creation (got ${JSON.stringify(v)})`),
+  ]);
+}
+
+/** Leg: the mapping lands after and over the child's default. Pure. */
+export function judgeOverride(o: MappingObservation): Outcome {
+  const vars = childVars(o);
+  if (vars === undefined) return skip('blocked', 'the child run is unread (no outputs.childRunId, or GET failed — the seed leg convicts that)');
+  const v = vars['receivedPrdId'];
+  return observed([
+    finding(v !== 'baked-in', `${DOC} (inputMapping: after and over defaultValue)`, 'the child\'s defaultValue "baked-in" MUST NOT win over the mapped parent value'),
+    finding(v === 'prd-1', `${DOC} (inputMapping)`, `the child's receivedPrdId MUST be the parent's currentPrdId projection "prd-1" (got ${JSON.stringify(v)})`),
+  ]);
+}
+
+/** Leg: an unset parent variable arrives undefined — no error, no `null`. Pure. */
+export function judgeUnset(o: MappingObservation): Outcome {
+  const vars = childVars(o);
+  const out = childReached(o);
+  if (vars !== undefined) {
+    const v = vars['receivedPrdId'];
+    out.push(
+      finding(v !== null, `${DOC} (inputMapping: never null)`, 'an unset parent variable MUST NOT arrive as null'),
+      finding(!('receivedPrdId' in vars) || v === 'baked-in', `${DOC} (inputMapping: arrives undefined)`, `an unset parent variable MUST arrive undefined: the child's value is absent or its own default (got ${JSON.stringify(v)})`),
+    );
+  }
+  return observed(out);
+}

package/src/lib/table-schema-witness.ts

@@ -18,6 +18,7 @@
  * nothing; {@link judge} is pure.
  */
 
+import { projectBoundId } from './bound-id.js';
 import { randomUUID } from 'node:crypto';
 import { driver, type OpenWOPResponse } from './driver.js';
 import { readErrorCode } from './error-envelope.js';
@@ -52,7 +53,8 @@ const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typ
 async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
   try { return await fn(); } catch { return null; }
 }
-const enc = (id: string): string => encodeURIComponent(id);
+/** A v2 bound id as one path segment: the `~` projection (identity.md §5). */
+const enc = (id: string): string => projectBoundId(id);
 
 async function probe(action: ProbeAction, timeoutMs: number): Promise<ProbeOutcome | string> {
   const table = `conformance_schema_${randomUUID().replace(/-/g, '').slice(0, 16)}`;

package/src/scenarios/v2-agent-runtime-advertisement.test.ts

@@ -0,0 +1,51 @@
+/**
+ * v2 — the `agentRuntime` advertisement (`spec/v2/core/host-services.md` §`agentRuntime`): the agent runtime claim. It had no v1 witness;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   implies-manifest-runtime advertising agentRuntime also advertises agents.manifestRuntime;
+ *
+ * Not here: the `ctx` surface (`spawn`, `delegate`, `consensus`, `messageSend`) cannot be observed from outside a node.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `agentRuntime` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/host-services.md §`agentRuntime`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import { agentRuntimeImpliesManifestRuntimeLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'host-services.md §agentRuntime';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.agent-runtime.advert-record-schema';
+const ID_IMPLIES_MANIFEST_RUNTIME = 'openwop.requirement.agent-runtime.implies-manifest-runtime';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 agentRuntime advertisement (host-services.md §agentRuntime)', () => {
+  it('the agentRuntime record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('agentRuntime'))) return softSkip('inapplicable', 'the host does not advertise agentRuntime');
+    const out = recordSchemaLeg(PROFILE, doc, 'agentRuntime', DOC);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RECORD, x.doc, x.message)).toBe(true);
+  });
+
+  it('advertising agentRuntime also advertises agents.manifestRuntime', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('agentRuntime'))) return softSkip('inapplicable', 'the host does not advertise agentRuntime');
+    const out = agentRuntimeImpliesManifestRuntimeLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_IMPLIES_MANIFEST_RUNTIME, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-ai-envelope-advertisement.test.ts

@@ -0,0 +1,43 @@
+/**
+ * v2 — the `aiEnvelope` advertisement (`spec/v2/core/host-services.md`
+ * §aiEnvelope; RFC 0144). The v1 twin is the record shape `aiEnvelope` carried
+ * at v1; the legs live in `lib/family-advert-witness.ts`.
+ *
+ *   record         the record (with its optional `await` boolean) validates against
+ *                  its capabilities-schema seat.
+ *
+ * Not here: exposing `ctx.aiEnvelope.generate` / `await` to pack code is a
+ * pack-runtime surface with no wire witness.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `aiEnvelope` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/host-services.md §aiEnvelope
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import { recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'host-services.md §aiEnvelope';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.ai-envelope.advert-record-schema';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 aiEnvelope advertisement (host-services.md §aiEnvelope)', () => {
+  it('the aiEnvelope record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('aiEnvelope'))) return softSkip('inapplicable', 'the host does not advertise aiEnvelope');
+    const out = recordSchemaLeg(PROFILE, doc, 'aiEnvelope', DOC);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RECORD, x.doc, x.message)).toBe(true);
+  });
+});