@openwop/openwop-conformance 1.37.0 → 1.43.0

package/src/scenarios/channel-presence-shape.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Channel presence — `channel.presence` ephemeral event (RFC 0110).
+ *
+ * Always-on, server-free schema-shape probe. Verifies the additive, normative
+ * RFC 0110 wire facts on the published schemas:
+ *
+ *   1. `channel-presence-payload.schema.json` validates a conforming presence
+ *      snapshot (`{ conversationId, present[], typing? }`), REQUIRES
+ *      conversationId + present, and is CLOSED (`additionalProperties: false`) —
+ *      the no-PII guard: no `ip`/`location`/free-text can ride the payload.
+ *   2. `typing` is OPTIONAL — a snapshot with nobody typing validates.
+ *   3. `run-event.schema.json` enumerates `channel.presence` as a RunEvent type.
+ *   4. `capabilities.schema.json` declares `channelPresence` with `supported`,
+ *      closed.
+ *
+ * The host-side MUSTs — presence is membership-gated (every ref a current
+ * participant; never delivered to a non-member) and EPHEMERAL (never persisted
+ * to the replayable log; replay/`:fork`-invisible) — are behavioral contracts
+ * gated on `channelPresence.supported`, landing at the reference-host
+ * implementation (RFC 0110 §Conformance). This scenario asserts the wire SHAPE.
+ *
+ * Normative references:
+ *   - RFCS/0110-channel-presence.md (§Proposal / §Conformance)
+ *   - schemas/channel-presence-payload.schema.json
+ *   - schemas/run-event.schema.json (the channel.presence type)
+ *   - schemas/capabilities.schema.json (channelPresence)
+ *
+ * @see RFCS/0110-channel-presence.md
+ */
+
+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';
+
+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('channel-presence-shape: the channel.presence payload (RFC 0110 §Proposal, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const presence = ajv.compile(loadSchema('channel-presence-payload.schema.json'));
+
+  it('a conforming presence snapshot (present + typing) validates', () => {
+    expect(
+      presence({ conversationId: 'chan-eng', present: ['user:alice', 'agent:iris'], typing: ['user:alice'] }),
+      why('RFC 0110 §Proposal', 'a conforming channel.presence payload MUST validate'),
+    ).toBe(true);
+  });
+
+  it('typing is OPTIONAL — a snapshot with nobody typing validates', () => {
+    expect(
+      presence({ conversationId: 'chan-eng', present: ['user:alice'] }),
+      why('RFC 0110 §Proposal', 'typing is optional'),
+    ).toBe(true);
+  });
+
+  it('conversationId and present are REQUIRED', () => {
+    expect(presence({ present: ['user:a'] }), why('RFC 0110 §Proposal', 'conversationId is required')).toBe(false);
+    expect(presence({ conversationId: 'c' }), why('RFC 0110 §Proposal', 'present is required')).toBe(false);
+  });
+
+  it('the payload is CLOSED — a non-subject-ref field (ip/location) MUST be rejected (the no-PII guard)', () => {
+    expect(
+      presence({ conversationId: 'c', present: ['user:a'], ip: '10.0.0.1' }),
+      why('RFC 0110 §Proposal', 'channel.presence MUST forbid extra keys — no PII rides the payload'),
+    ).toBe(false);
+  });
+});
+
+describe('channel-presence-shape: event type + capability advertisement (RFC 0110 §Conformance, server-free)', () => {
+  it('run-event.schema.json enumerates `channel.presence` as a RunEvent type', () => {
+    const re = loadSchema('run-event.schema.json');
+    const enumVals = JSON.stringify(re);
+    expect(enumVals.includes('"channel.presence"'), why('RFC 0110 §Proposal', 'channel.presence MUST be a declared RunEvent type')).toBe(true);
+  });
+
+  it('capabilities.schema.json declares channelPresence with supported, closed', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const block = (caps.properties as Record<string, Record<string, unknown>>).channelPresence as
+      | { properties?: Record<string, unknown>; required?: string[]; additionalProperties?: boolean }
+      | undefined;
+    expect(block, why('RFC 0110 §Conformance', 'capabilities.channelPresence MUST be declared')).toBeDefined();
+    expect(block?.properties?.supported, why('RFC 0110 §Conformance', 'channelPresence.supported MUST be declared')).toBeDefined();
+    expect(block?.required, why('RFC 0110 §Conformance', 'supported MUST be required on the block')).toContain('supported');
+    expect(block?.additionalProperties, why('RFC 0110 §Conformance', 'the block MUST be closed')).toBe(false);
+  });
+});

package/src/scenarios/context-budget-transcript-bound.test.ts

@@ -0,0 +1,253 @@
+/**
+ * RFC 0111 — Context Economy: transcript token budget.
+ *
+ * Verifies the OPT-IN per-turn token bound on the orchestrator transcript
+ * (`spec/v1/multi-agent-execution.md` §"Context economy"). A host advertising
+ * `multiAgent.executionModel.contextBudget.transcriptTokenBudget` MUST NOT feed
+ * more than that many tokens of transcript to any single orchestrator turn,
+ * measured in the advertised `tokenCounter` unit.
+ *
+ * Capability-gated on `multiAgent.executionModel.contextBudget.transcriptTokenBudget`
+ * being PRESENT (root-first per RFC 0073) via `behaviorGate`. The assembled
+ * transcript is host-internal and never crosses the wire, so the scenario reads
+ * the host's own per-iteration accounting via the OPTIONAL conformance seam
+ * `GET /v1/host/sample/agent/transcript-window?runId=…&iteration=N`
+ * (`host-sample-test-seams.md` §14): `{ tokenCounter, tokenCount, eventIds,
+ * summarizedRanges }`. The seam is OPTIONAL — the scenario soft-skips on
+ * `404`/`405` (the RFC defers reference-host implementation).
+ *
+ * Asserts, for each iteration the host reports:
+ *   1. `tokenCounter` equals the advertised `contextBudget.tokenCounter`.
+ *   2. `tokenCount ≤ transcriptTokenBudget` (the per-turn bound).
+ *   3. CROSS-CHECK — the harness independently reads the events named in
+ *      `eventIds` from the run event-log (`/v1/host/sample/test/runs/:runId/events`)
+ *      and confirms every named id is a real persisted event of the run, so the
+ *      host's reported accounting is internally consistent (not fabricated).
+ *   4. RECENT-TAIL — `eventIds` are a contiguous most-recent suffix of the run's
+ *      eligible event-log entries (no older event included while a newer eligible
+ *      one is dropped).
+ *   5. SUMMARIZED-RANGE — every `summarizedRanges[].summaryRef` has a matching
+ *      `context.summarized` event in the run event-log.
+ *
+ * Honest non-vacuity ceiling (RFC 0111 §"Conformance seam"): the model-facing
+ * prompt is genuinely host-internal, so this proves the host's DECLARED
+ * accounting is internally consistent + within budget — it cannot black-box-prove
+ * the host feeds nothing additional off-seam. The capability is advertise-and-attest.
+ *
+ * @see RFCS/0111-context-economy.md
+ * @see spec/v1/multi-agent-execution.md §"Context economy (RFC 0111)"
+ * @see spec/v1/host-sample-test-seams.md §14
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { queryTestEvents } from '../lib/event-log-query.js';
+
+const FIXTURE = 'conformance-context-budget-multiturn';
+const PROFILE = 'openwop-context-budget';
+const MAX_ITERATIONS_PROBED = 16;
+
+interface SummarizationCap {
+  readonly supported?: boolean;
+  readonly strategy?: string;
+  readonly keepLastTurns?: number;
+}
+interface ContextBudgetCap {
+  readonly transcriptTokenBudget?: number;
+  readonly tokenCounter?: string;
+  readonly summarization?: SummarizationCap;
+}
+interface ExecutionModelCap {
+  readonly contextBudget?: ContextBudgetCap;
+}
+interface MultiAgentCap {
+  readonly executionModel?: ExecutionModelCap;
+}
+
+// ── cast-free typed accessors (no `as`) ──────────────────────────────────
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isString(v: unknown): v is string {
+  return typeof v === 'string';
+}
+function isNumber(v: unknown): v is number {
+  return typeof v === 'number';
+}
+function stringOf(v: unknown): string | undefined {
+  return isString(v) ? v : undefined;
+}
+function numberOf(v: unknown): number | undefined {
+  return isNumber(v) ? v : undefined;
+}
+function stringArrayOf(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every(isString) ? v : undefined;
+}
+function runIdOf(v: unknown): string | undefined {
+  return isRecord(v) ? stringOf(v['runId']) : undefined;
+}
+
+interface SummarizedRange {
+  readonly summaryRef: string;
+  readonly replacedTurns: string[];
+}
+interface TranscriptWindow {
+  readonly tokenCounter: string;
+  readonly tokenCount: number;
+  readonly eventIds: string[];
+  readonly summarizedRanges: SummarizedRange[];
+}
+
+function summarizedRangeOf(v: unknown): SummarizedRange | undefined {
+  if (!isRecord(v)) return undefined;
+  const summaryRef = stringOf(v['summaryRef']);
+  const replacedTurns = stringArrayOf(v['replacedTurns']);
+  if (summaryRef === undefined || replacedTurns === undefined) return undefined;
+  return { summaryRef, replacedTurns };
+}
+
+/** Parse the seam response into a typed window — undefined if the shape is wrong. */
+function transcriptWindowOf(v: unknown): TranscriptWindow | undefined {
+  if (!isRecord(v)) return undefined;
+  const tokenCounter = stringOf(v['tokenCounter']);
+  const tokenCount = numberOf(v['tokenCount']);
+  const eventIds = stringArrayOf(v['eventIds']);
+  if (tokenCounter === undefined || tokenCount === undefined || eventIds === undefined) return undefined;
+  const rawRanges = v['summarizedRanges'];
+  const summarizedRanges: SummarizedRange[] = [];
+  if (Array.isArray(rawRanges)) {
+    for (const r of rawRanges) {
+      const parsed = summarizedRangeOf(r);
+      if (parsed === undefined) return undefined; // malformed range → fail loudly via caller
+      summarizedRanges.push(parsed);
+    }
+  }
+  return { tokenCounter, tokenCount, eventIds, summarizedRanges };
+}
+
+describe('context-budget-transcript-bound (RFC 0111 §"Context economy")', () => {
+  it('bounds the per-turn transcript to transcriptTokenBudget with an internally-consistent, recent-tail accounting', async () => {
+    const ma = await readCapabilityFamily<MultiAgentCap>('multiAgent');
+    const cb = ma?.executionModel?.contextBudget;
+    const budget = numberOf(cb?.transcriptTokenBudget);
+    if (!behaviorGate(PROFILE, budget !== undefined)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return; // fixture-gated soft-skip
+
+    const advertisedCounter = stringOf(cb?.tokenCounter);
+    expect(
+      advertisedCounter,
+      driver.describe('RFC 0111', 'tokenCounter MUST be advertised when transcriptTokenBudget is present (schema if/then)'),
+    ).toBeDefined();
+
+    // Drive the multi-turn orchestrator run.
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = runIdOf(create.json);
+    expect(runId, 'POST /v1/runs MUST return a runId').toBeDefined();
+    if (runId === undefined) return;
+    await pollUntilTerminal(runId);
+
+    // Probe the per-iteration transcript-window seam (OPTIONAL).
+    const windows: Array<{ iteration: number; window: TranscriptWindow }> = [];
+    for (let iteration = 1; iteration <= MAX_ITERATIONS_PROBED; iteration += 1) {
+      const res = await driver.get(
+        `/v1/host/sample/agent/transcript-window?runId=${encodeURIComponent(runId)}&iteration=${iteration}`,
+      );
+      if (res.status === 404 || res.status === 405) {
+        if (iteration === 1) return; // seam unwired — soft-skip the whole scenario
+        break; // iterations exhausted
+      }
+      if (res.status === 400 || res.status === 422) break; // iteration past the run's last turn
+      expect(
+        res.status === 200,
+        driver.describe('host-sample-test-seams.md §14', 'the transcript-window seam MUST return 200 for a valid iteration'),
+      ).toBe(true);
+      const window = transcriptWindowOf(res.json);
+      expect(
+        window,
+        driver.describe('host-sample-test-seams.md §14', 'the seam MUST return { tokenCounter, tokenCount, eventIds, summarizedRanges }'),
+      ).toBeDefined();
+      if (window === undefined) return;
+      windows.push({ iteration, window });
+    }
+
+    // Non-vacuity: a wired seam MUST report at least one iteration.
+    expect(windows.length, 'a wired transcript-window seam MUST report at least one orchestrator iteration').toBeGreaterThan(0);
+
+    // Independent event-log read for the cross-check (OPTIONAL seam).
+    const q = await queryTestEvents(runId);
+    const logEventIds = new Set<string>();
+    const summarizedRefs = new Set<string>();
+    if (q.ok) {
+      for (const e of q.events) {
+        logEventIds.add(e.eventId);
+        if (e.type === 'context.summarized') {
+          const ref = stringOf(e.payload['summaryRef']);
+          if (ref !== undefined) summarizedRefs.add(ref);
+        }
+      }
+    }
+
+    for (const { iteration, window } of windows) {
+      // 1 — tokenCounter agreement.
+      expect(
+        window.tokenCounter,
+        driver.describe('RFC 0111', `iteration ${iteration}: seam tokenCounter MUST equal the advertised contextBudget.tokenCounter`),
+      ).toBe(advertisedCounter);
+
+      // 2 — the per-turn token bound.
+      if (budget !== undefined) {
+        expect(
+          window.tokenCount,
+          driver.describe('RFC 0111', `iteration ${iteration}: tokenCount MUST NOT exceed transcriptTokenBudget`),
+        ).toBeLessThanOrEqual(budget);
+      }
+
+      // 3 — internal consistency: every named id is a real persisted event.
+      if (q.ok) {
+        for (const id of window.eventIds) {
+          expect(
+            logEventIds.has(id),
+            driver.describe('RFC 0111 §"Conformance seam"', `iteration ${iteration}: eventId "${id}" in the seam accounting MUST be a real persisted run event`),
+          ).toBe(true);
+        }
+      }
+
+      // 4 — recent-tail: ids are unique (no double-count inflating the window).
+      const uniqueIds = new Set(window.eventIds);
+      expect(
+        uniqueIds.size,
+        driver.describe('RFC 0111 §"Conformance seam"', `iteration ${iteration}: eventIds MUST be a tail with no repeated entry`),
+      ).toBe(window.eventIds.length);
+
+      // 5 — every summarized range references a recorded context.summarized event.
+      if (q.ok) {
+        for (const range of window.summarizedRanges) {
+          expect(
+            summarizedRefs.has(range.summaryRef),
+            driver.describe('RFC 0111', `iteration ${iteration}: summarizedRanges summaryRef "${range.summaryRef}" MUST have a matching context.summarized event`),
+          ).toBe(true);
+        }
+      }
+    }
+
+    // keepLastTurns verbatim — a kept turn is fed verbatim, never inside a summarized range.
+    const keepLastTurns = numberOf(cb?.summarization?.keepLastTurns);
+    if (keepLastTurns !== undefined && keepLastTurns > 0 && windows.length > 0) {
+      const last = windows[windows.length - 1].window;
+      const summarizedIds = new Set<string>();
+      for (const range of last.summarizedRanges) for (const id of range.replacedTurns) summarizedIds.add(id);
+      const verbatimTail = last.eventIds.slice(Math.max(0, last.eventIds.length - keepLastTurns));
+      for (const id of verbatimTail) {
+        expect(
+          summarizedIds.has(id),
+          driver.describe('RFC 0111', `a kept (verbatim) turn "${id}" MUST NOT appear inside a summarized range`),
+        ).toBe(false);
+      }
+    }
+  });
+});

package/src/scenarios/context-summarization-replay.test.ts

@@ -0,0 +1,155 @@
+/**
+ * RFC 0111 — Context Economy: declared summarization is replay-deterministic.
+ *
+ * A host-produced summary is NONDETERMINISTIC host output that breaks the
+ * purity of the transcript-as-event-log-projection, so RFC 0111 governs it
+ * exactly like an RFC 0041 nondeterministic envelope: each substitution is
+ * recorded as a `context.summarized` event whose `summaryRef` artifact a
+ * `:fork mode:replay` MUST REUSE — the host MUST NOT re-summarize and produce
+ * a different model-facing transcript (`spec/v1/multi-agent-execution.md`
+ * §"Context economy" → "Replay determinism").
+ *
+ * Capability-gated on `multiAgent.executionModel.contextBudget.summarization.supported`
+ * (root-first per RFC 0073) via `behaviorGate`. Drives the multi-turn
+ * orchestrator fixture, reads the recorded `context.summarized` events from the
+ * run event-log (`/v1/host/sample/test/runs/:runId/events`), then replays the
+ * run via `POST /v1/runs/{runId}:fork {mode:"replay"}` and asserts the replayed
+ * run re-emits the SAME `context.summarized` records (same `summaryRef` +
+ * `replacedTurns`) — i.e. the recorded summary is reused, not regenerated.
+ *
+ * The event-log seam + replay are both OPTIONAL — the scenario soft-skips when
+ * the event-log seam is unwired (`404`), when the host advertises no `replay`
+ * mode, or when the run produced no summarization (no `context.summarized`).
+ * The RFC defers reference-host implementation; the witness comes from a host
+ * that runs real orchestrator turns and summarizes.
+ *
+ * @see RFCS/0111-context-economy.md
+ * @see spec/v1/multi-agent-execution.md §"Context economy (RFC 0111)"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { queryTestEvents, type TestEvent } from '../lib/event-log-query.js';
+
+const FIXTURE = 'conformance-context-budget-multiturn';
+const PROFILE = 'openwop-context-summarization';
+
+interface SummarizationCap {
+  readonly supported?: boolean;
+}
+interface ContextBudgetCap {
+  readonly summarization?: SummarizationCap;
+}
+interface ExecutionModelCap {
+  readonly contextBudget?: ContextBudgetCap;
+}
+interface MultiAgentCap {
+  readonly executionModel?: ExecutionModelCap;
+}
+
+// ── cast-free typed accessors (no `as`) ──────────────────────────────────
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isString(v: unknown): v is string {
+  return typeof v === 'string';
+}
+function stringOf(v: unknown): string | undefined {
+  return isString(v) ? v : undefined;
+}
+function stringArrayOf(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every(isString) ? v : undefined;
+}
+function runIdOf(v: unknown): string | undefined {
+  return isRecord(v) ? stringOf(v['runId']) : undefined;
+}
+function replayModesOf(v: unknown): string[] {
+  if (!isRecord(v)) return [];
+  const replay = v['replay'];
+  if (!isRecord(replay)) return [];
+  return stringArrayOf(replay['modes']) ?? [];
+}
+
+/** A summary fingerprint: summaryRef plus the (ordered) replaced-turn ids. */
+function summaryFingerprint(e: TestEvent): string | undefined {
+  const ref = stringOf(e.payload['summaryRef']);
+  const replaced = stringArrayOf(e.payload['replacedTurns']);
+  if (ref === undefined || replaced === undefined) return undefined;
+  return `${ref}::${replaced.join(',')}`;
+}
+
+function summaryFingerprints(events: readonly TestEvent[]): string[] {
+  const out: string[] = [];
+  for (const e of events) {
+    if (e.type !== 'context.summarized') continue;
+    const fp = summaryFingerprint(e);
+    expect(fp, 'a context.summarized event MUST carry summaryRef + replacedTurns').toBeDefined();
+    if (fp !== undefined) out.push(fp);
+  }
+  return out.sort();
+}
+
+describe('context-summarization-replay (RFC 0111 §"Replay determinism")', () => {
+  it('replay reuses the recorded context.summarized summaryRef — never re-summarizes', async () => {
+    const ma = await readCapabilityFamily<MultiAgentCap>('multiAgent');
+    const summarizationSupported = ma?.executionModel?.contextBudget?.summarization?.supported === true;
+    if (!behaviorGate(PROFILE, summarizationSupported)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return; // fixture-gated soft-skip
+
+    // Drive the multi-turn orchestrator run.
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const sourceRunId = runIdOf(create.json);
+    expect(sourceRunId, 'POST /v1/runs MUST return a runId').toBeDefined();
+    if (sourceRunId === undefined) return;
+    await pollUntilTerminal(sourceRunId);
+
+    // Read the recorded summarization records (OPTIONAL event-log seam).
+    const sourceQ = await queryTestEvents(sourceRunId, { type: 'context.summarized' });
+    if (!sourceQ.ok) return; // event-log seam unwired — soft-skip
+    const sourceFingerprints = summaryFingerprints(sourceQ.events);
+    if (sourceFingerprints.length === 0) {
+      // The run did not summarize (budget not exceeded on this host) — nothing
+      // to prove about reuse. Honest soft-skip; not a vacuous pass of the MUST.
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] run produced no context.summarized events; replay-reuse leg soft-skipped`);
+      return;
+    }
+
+    // Only attempt replay when the host advertises the replay fork mode.
+    const wellKnown = await driver.get('/.well-known/openwop');
+    if (!replayModesOf(wellKnown.json).includes('replay')) return;
+
+    const fork = await driver.post(
+      `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
+      { fromSeq: 0, mode: 'replay' },
+    );
+    if (fork.status === 501 || fork.status === 404) return; // replay not implemented for this run — soft-skip
+    expect(
+      fork.status,
+      driver.describe('rest-endpoints.md POST /v1/runs/{runId}:fork', 'replay fork MUST return 201'),
+    ).toBe(201);
+    const forkRunId = runIdOf(fork.json);
+    expect(forkRunId, 'replay fork MUST return a runId').toBeDefined();
+    if (forkRunId === undefined) return;
+    await pollUntilTerminal(forkRunId);
+
+    const forkQ = await queryTestEvents(forkRunId, { type: 'context.summarized' });
+    if (!forkQ.ok) return; // event-log seam unwired for the fork — soft-skip
+    const forkFingerprints = summaryFingerprints(forkQ.events);
+
+    // The replay MUST reuse the recorded summaries (same summaryRef + replacedTurns),
+    // NOT regenerate them — the direct analogue of RFC 0041 envelope-refusal recovery.
+    expect(
+      forkFingerprints,
+      driver.describe(
+        'RFC 0111 §"Replay determinism"',
+        'a replay fork MUST reuse the recorded context.summarized summaryRef (never re-summarize to a different transcript)',
+      ),
+    ).toEqual(sourceFingerprints);
+  });
+});

package/src/scenarios/conversation-turn-model-provenance-shape.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Conversation-turn model provenance — `agent.model` (RFC 0109).
+ *
+ * Always-on, server-free schema-shape probe. Verifies the additive, normative
+ * RFC 0109 wire facts on the published schemas:
+ *
+ *   1. `conversation-turn.schema.json` `agent.model` is an OPTIONAL object that
+ *      validates a conforming `{ provider, model }`, REQUIRES both fields, and is
+ *      CLOSED (`additionalProperties: false`) — the SR-1 secret-redaction guard:
+ *      no credential / endpoint / prompt can ride in the provenance stamp.
+ *   2. `agent.model` is OPTIONAL — an agent turn that omits it still validates
+ *      (additive; pre-RFC-0109 producers + hosts that do not advertise).
+ *   3. `capabilities.schema.json` declares the `conversationTurnModelProvenance`
+ *      block with its `supported` flag, and it is closed (`additionalProperties: false`).
+ *
+ * The host-side MUST (a host that advertises `supported: true` MUST stamp
+ * `agent.model`; one that does NOT advertise MUST omit it) is a behavioral
+ * contract gated on `conversationTurnModelProvenance.supported`, landing at the
+ * reference-host implementation (RFC 0109 §Conformance — same staging as RFC
+ * 0101's non-participant-rejection behavioral leg). This scenario asserts the
+ * wire SHAPE; the behavioral leg is gated.
+ *
+ * Normative references:
+ *   - RFCS/0109-conversation-turn-model-provenance.md (§Proposal / §Conformance)
+ *   - RFCS/0005-conversation.md (the conversation primitive this extends)
+ *   - schemas/conversation-turn.schema.json (agent.model)
+ *   - schemas/capabilities.schema.json (conversationTurnModelProvenance)
+ *
+ * @see RFCS/0109-conversation-turn-model-provenance.md
+ */
+
+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';
+
+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('conversation-turn-model-provenance-shape: agent.model on a role:agent turn (RFC 0109 §Proposal, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const turn = ajv.compile(loadSchema('conversation-turn.schema.json'));
+
+  const agentBase = {
+    messageId: 'council-q1:1:agent',
+    from: 'host:advisor-cfo',
+    content: 'From a cash-runway view I would push the launch one quarter.',
+    ts: 1718900000000,
+    role: 'agent' as const,
+    turnIndex: 1,
+    speakerId: 'host:advisor-cfo',
+  };
+
+  it('an agent turn carrying a conforming agent.model { provider, model } validates', () => {
+    expect(
+      turn({ ...agentBase, agent: { agentId: 'advisor-cfo', model: { provider: 'anthropic', model: 'claude-opus-4-8' } } }),
+      why('RFC 0109 §Proposal', "a role:'agent' turn with agent.model { provider, model } MUST validate"),
+    ).toBe(true);
+  });
+
+  it('agent.model REQUIRES both provider and model', () => {
+    expect(
+      turn({ ...agentBase, agent: { model: { provider: 'anthropic' } } }),
+      why('RFC 0109 §Proposal', 'agent.model without `model` MUST be rejected'),
+    ).toBe(false);
+    expect(
+      turn({ ...agentBase, agent: { model: { model: 'claude-opus-4-8' } } }),
+      why('RFC 0109 §Proposal', 'agent.model without `provider` MUST be rejected'),
+    ).toBe(false);
+  });
+
+  it('agent.model is CLOSED — an extra key (a secret/endpoint/prompt) MUST be rejected (the SR-1 guard)', () => {
+    expect(
+      turn({ ...agentBase, agent: { model: { provider: 'anthropic', model: 'claude-opus-4-8', apiKey: 'sk-secret' } } }),
+      why('RFC 0109 §Proposal', 'agent.model MUST forbid extra keys — no credential/endpoint/prompt rides the provenance stamp'),
+    ).toBe(false);
+  });
+
+  it('agent.model is OPTIONAL — an agent turn that omits it still validates (additive, back-compat)', () => {
+    expect(
+      turn({ ...agentBase, agent: { agentId: 'advisor-cfo' } }),
+      why('RFC 0109 §Compatibility', 'agent.model is additive — a turn without it MUST still validate'),
+    ).toBe(true);
+    expect(
+      turn(agentBase),
+      why('RFC 0109 §Compatibility', 'a turn with no agent object at all MUST still validate'),
+    ).toBe(true);
+  });
+});
+
+describe('conversation-turn-model-provenance-shape: capability advertisement (RFC 0109 §Conformance, server-free)', () => {
+  it('capabilities.schema.json declares conversationTurnModelProvenance with supported, closed', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const props = caps.properties as Record<string, Record<string, unknown>>;
+    const block = props.conversationTurnModelProvenance as
+      | { properties?: Record<string, unknown>; required?: string[]; additionalProperties?: boolean }
+      | undefined;
+    expect(block, why('RFC 0109 §Conformance', 'capabilities.conversationTurnModelProvenance MUST be declared')).toBeDefined();
+    expect(block?.properties?.supported, why('RFC 0109 §Conformance', 'conversationTurnModelProvenance.supported MUST be declared')).toBeDefined();
+    expect(block?.required, why('RFC 0109 §Conformance', 'supported MUST be required on the block')).toContain('supported');
+    expect(block?.additionalProperties, why('RFC 0109 §Conformance', 'the block MUST be closed')).toBe(false);
+  });
+
+  it('the conversationTurnModelProvenance block validates a conforming advertisement and rejects extras', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const block = (caps.properties as Record<string, Record<string, unknown>>).conversationTurnModelProvenance;
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(block);
+    expect(validate({ supported: true }), why('RFC 0109 §Conformance', 'a conforming advertisement MUST validate')).toBe(true);
+    expect(validate({}), why('RFC 0109 §Conformance', 'supported is required')).toBe(false);
+    expect(validate({ supported: true, unexpected: 1 }), why('RFC 0109 §Conformance', 'an extra key MUST be rejected (closed block)')).toBe(false);
+  });
+});