@openwop/openwop-conformance 1.37.0 → 1.43.0

package/src/scenarios/memory-injection-budget.test.ts

@@ -0,0 +1,188 @@
+/**
+ * RFC 0113 — Memory Injection Budget.
+ *
+ * Verifies the new token-denominated bound on the live injection read:
+ * `MemoryAdapter.list(memoryRef, { tokenBudget, rank, query })`
+ * (`spec/v1/agent-memory.md` §"Injection budget"). The genuinely new
+ * contribution is `tokenBudget`; `rank:'relevance'` DELEGATES to the
+ * existing `memory.search` semantic mode (RFC 0080) — this scenario does
+ * NOT assert a parallel ranking primitive, and the relevance leg soft-skips
+ * unless the host ALSO advertises `memory.search` semantic.
+ *
+ * Capability-gated on `capabilities.memory.injectionBudget.supported === true`
+ * (root-first per RFC 0073) via `behaviorGate`. Driven through the host-sample
+ * memory seam — the `conformance-agent-memory-injection-budget` fixture (the
+ * same `/v1/runs` + run-variable seam the other `agentMemory*` scenarios use to
+ * reach the adapter), which seeds a set whose total exceeds the budget AND
+ * includes one single entry larger than the whole budget, plus a BYOK-redacted
+ * entry and a cross-tenant probe.
+ *
+ * Asserts: cumulative tokens ≤ `tokenBudget`; an over-budget single entry is
+ * omitted (not truncated); `rank:'relevance'` ordering differs from recency on
+ * the crafted fixture (only when `memory.search` semantic is advertised, else
+ * soft-skip); and re-asserts SR-1 (redacted content) + CTI-1 (cross-tenant
+ * probe empty) on the budgeted path as a regression guard.
+ *
+ * @see RFCS/0113-memory-injection-budget.md
+ * @see spec/v1/agent-memory.md §"Injection budget"
+ */
+
+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';
+
+const FIXTURE = 'conformance-agent-memory-injection-budget';
+const PROFILE = 'openwop-memory-injection-budget';
+
+interface MemoryInjectionBudgetCap {
+  readonly supported?: boolean;
+  readonly tokenCounter?: string;
+}
+interface MemorySearchCap {
+  readonly supported?: boolean;
+  readonly modes?: readonly string[];
+}
+interface MemoryCap {
+  readonly injectionBudget?: MemoryInjectionBudgetCap;
+  readonly search?: MemorySearchCap;
+}
+
+// ── 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 isBoolean(v: unknown): v is boolean {
+  return typeof v === 'boolean';
+}
+function stringOf(v: unknown): string | undefined {
+  return isString(v) ? v : undefined;
+}
+function numberOf(v: unknown): number | undefined {
+  return isNumber(v) ? v : undefined;
+}
+function booleanOf(v: unknown): boolean | undefined {
+  return isBoolean(v) ? v : undefined;
+}
+function stringArrayOf(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every(isString) ? v : undefined;
+}
+function recordArrayOf(v: unknown): Record<string, unknown>[] | undefined {
+  return Array.isArray(v) && v.every(isRecord) ? v : undefined;
+}
+function runIdOf(v: unknown): string | undefined {
+  return isRecord(v) ? stringOf(v['runId']) : undefined;
+}
+function variablesOf(v: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(v)) return undefined;
+  const vars = v['variables'];
+  return isRecord(vars) ? vars : undefined;
+}
+
+function advertisesSemanticSearch(mem: MemoryCap | undefined): boolean {
+  const modes = mem?.search?.modes;
+  return mem?.search?.supported === true && Array.isArray(modes) && modes.includes('semantic');
+}
+
+async function driveFixtureVariables(): Promise<Record<string, unknown> | undefined> {
+  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 undefined;
+
+  const terminal = await pollUntilTerminal(runId);
+  expect(terminal.status).toBe('completed');
+
+  const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+  return variablesOf(snap.json);
+}
+
+describe('memory-injection-budget (RFC 0113)', () => {
+  it('token-bounds the injection read, omits the over-budget entry, and preserves SR-1 + CTI-1', async () => {
+    const mem = await readCapabilityFamily<MemoryCap>('memory');
+    if (!behaviorGate(PROFILE, mem?.injectionBudget?.supported === true)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return; // fixture-gated soft-skip
+
+    const v = await driveFixtureVariables();
+    expect(v, 'fixture MUST surface run variables').toBeDefined();
+    if (v === undefined) return;
+
+    // ── tokenBudget bound (the new lever) ──────────────────────────────
+    const tokenBudget = numberOf(v['tokenBudget']);
+    const total = numberOf(v['budgetedTokenTotal']);
+    expect(tokenBudget, 'fixture MUST echo the requested tokenBudget').toBeDefined();
+    expect(total, 'fixture MUST surface the budgeted cumulative token total').toBeDefined();
+    // Cumulative tokens across the returned prefix MUST NOT exceed the budget.
+    if (tokenBudget !== undefined && total !== undefined) {
+      expect(total).toBeLessThanOrEqual(tokenBudget);
+    }
+
+    // ── over-budget single entry omitted (not truncated) ───────────────
+    expect(
+      booleanOf(v['overBudgetEntryOmitted']),
+      'an entry larger than the whole budget MUST be omitted, not truncated mid-entry',
+    ).toBe(true);
+    const entries = recordArrayOf(v['budgetedEntries']);
+    expect(entries, 'fixture MUST surface the budgeted entry slice').toBeDefined();
+    const overId = stringOf(v['overBudgetEntryId']);
+    if (entries !== undefined && overId !== undefined) {
+      const ids = entries.map((e) => stringOf(e['id']));
+      expect(ids, 'the over-budget entry MUST NOT appear in the returned slice').not.toContain(overId);
+    }
+
+    // ── SR-1 re-assertion on the budgeted path ─────────────────────────
+    // A budgeted/ranked read ranks over already-redacted content; the read
+    // surface MUST carry the redaction marker, never the plaintext.
+    const redacted = stringOf(v['redactedContentSample']);
+    expect(redacted, 'budgeted read MUST surface a redacted-content sample').toBeDefined();
+    if (redacted !== undefined) {
+      expect(redacted).toMatch(/\[REDACTED:[^\]]+\]/);
+    }
+
+    // ── CTI-1 re-assertion on the budgeted path ────────────────────────
+    // A budget/rank prefix of an already-single-tenant list stays single-tenant:
+    // the cross-tenant probe under the budgeted path MUST return empty.
+    const probe = v['crossTenantBudgetedProbe'];
+    if (Array.isArray(probe)) {
+      expect(probe.length, 'cross-tenant probe on the budgeted path MUST return []').toBe(0);
+    } else {
+      expect(probe, 'cross-tenant probe on the budgeted path MUST return [] / null').toBeFalsy();
+    }
+  });
+
+  it("rank:'relevance' reorders vs recency — only when memory.search semantic is ALSO advertised", async () => {
+    const mem = await readCapabilityFamily<MemoryCap>('memory');
+    if (!behaviorGate(PROFILE, mem?.injectionBudget?.supported === true)) return;
+    // RFC 0113: rank:'relevance' DELEGATES to memory.search semantic (RFC 0080).
+    // A host that does not advertise memory.search semantic MUST NOT fabricate a
+    // relevance ranking — the relevance leg soft-skips here (it is not a new
+    // ranking surface advertised by injectionBudget).
+    if (!advertisesSemanticSearch(mem)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] memory.search semantic not advertised; relevance leg soft-skipped`);
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) return;
+
+    const v = await driveFixtureVariables();
+    expect(v, 'fixture MUST surface run variables').toBeDefined();
+    if (v === undefined) return;
+
+    const recencyOrder = stringArrayOf(v['recencyOrder']);
+    const relevanceOrder = stringArrayOf(v['relevanceOrder']);
+    expect(recencyOrder, 'fixture MUST surface the recency ordering').toBeDefined();
+    expect(relevanceOrder, 'fixture MUST surface the relevance ordering').toBeDefined();
+    // The crafted fixture pins a query whose semantic top-k differs from the
+    // most-recent-first order — relevance MUST reorder (not echo recency).
+    expect(relevanceOrder).not.toEqual(recencyOrder);
+  });
+});

package/src/scenarios/prompt-prefix-cache.test.ts

@@ -0,0 +1,200 @@
+/**
+ * prompt-prefix-cache — RFC 0116 + SECURITY/invariants.yaml
+ * `prompt-prefix-cache-cross-tenant-isolation`.
+ *
+ * Status: ACTIVE (advertisement-shape + behavioral). The behavioral legs drive
+ * the host's real envelope/provider generate path through the OPTIONAL test
+ * seam `POST /v1/host/sample/ai/generate` (`host-sample-test-seams.md` §16,
+ * env-gated on `OPENWOP_TEST_SEAM_ENABLED=true`). Hosts that don't advertise
+ * `aiProviders.promptPrefixCache.supported` soft-skip; hosts that advertise it
+ * but don't wire the seam (HTTP 404/405) soft-skip the behavioral legs and
+ * verify advertisement shape only.
+ *
+ * RFC 0116 makes the optional `cachePrefixId` generate hint safe + testable via
+ * three pillars, each asserted here:
+ *   (a) outcome-invariance — a generate with `cachePrefixId` and a control
+ *       without produce the same accepted envelope + identical
+ *       `inputTokens`/`outputTokens` (cost-hint-only, replay-invariant).
+ *   (b) cache hit observable — a repeat generate shows
+ *       `provider.usage.cacheReadTokens > 0`.
+ *   (c) cross-tenant isolation — tenant B's first use of tenant A's
+ *       `cachePrefixId` shows `cacheReadTokens == 0` (no cross-tenant share).
+ *       THIS is the public test for the `prompt-prefix-cache-cross-tenant-isolation`
+ *       invariant: the host MUST key its provider cache by `(tenant, cachePrefixId)`.
+ *   (d) secret-free — a `cachePrefixId` is never emitted where SR-1 would
+ *       redact, and the usage block carries no prompt substrings.
+ *
+ * @see RFCS/0116-prompt-prefix-cache.md
+ * @see spec/v1/ai-envelope.md §"Prompt-prefix cache (RFC 0116)"
+ * @see SECURITY/invariants.yaml — prompt-prefix-cache-cross-tenant-isolation
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface PromptPrefixCacheCap {
+  supported?: unknown;
+  providers?: unknown;
+}
+
+interface AiProvidersCap {
+  promptPrefixCache?: PromptPrefixCacheCap;
+}
+
+interface GenerateUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+interface GenerateResponse {
+  envelope?: { envelopeType?: string; payload?: unknown; envelopeId?: string };
+  usage?: GenerateUsage;
+}
+
+async function readCap(): Promise<PromptPrefixCacheCap | null> {
+  const fam = await readCapabilityFamily<AiProvidersCap>('aiProviders');
+  const block = fam?.promptPrefixCache;
+  return block && typeof block === 'object' ? block : null;
+}
+
+async function generate(args: {
+  tenantId: string;
+  cachePrefixId?: string;
+}): Promise<{ status: number; body: GenerateResponse }> {
+  const res = await driver.post('/v1/host/sample/ai/generate', {
+    tenantId: args.tenantId,
+    envelopeType: 'clarification.request',
+    systemPrompt: 'You are a helpful assistant. Answer concisely.',
+    ...(args.cachePrefixId !== undefined ? { cachePrefixId: args.cachePrefixId } : {}),
+  });
+  return { status: res.status, body: (res.json ?? {}) as GenerateResponse };
+}
+
+describe('prompt-prefix-cache: advertisement shape (RFC 0116)', () => {
+  it('aiProviders.promptPrefixCache is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // not advertised — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §aiProviders.promptPrefixCache',
+        'promptPrefixCache.supported MUST be a boolean when the block is present',
+      ),
+    ).toBe('boolean');
+    if (cap.providers !== undefined) {
+      expect(
+        Array.isArray(cap.providers),
+        driver.describe(
+          'capabilities.schema.json §aiProviders.promptPrefixCache',
+          'promptPrefixCache.providers MUST be an array of provider ids when present (provider-scoped)',
+        ),
+      ).toBe(true);
+    }
+  });
+});
+
+describe('prompt-prefix-cache: behavioral (RFC 0116 §"Normative requirements")', () => {
+  it('(a) outcome-invariance — cachePrefixId vs control → same envelope + identical input/output tokens', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `inv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const control = await generate({ tenantId: 'tenant-a' });
+    if (control.status === 404 || control.status === 405) return; // seam not wired
+    expect(control.status, driver.describe('host-sample-test-seams.md §16', 'generate seam MUST return 200')).toBe(200);
+
+    const withPrefix = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    expect(withPrefix.status).toBe(200);
+
+    expect(
+      withPrefix.body.envelope?.envelopeType,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 3',
+        'cachePrefixId is a cost hint, never semantic: the accepted envelope MUST be identical hit-vs-miss',
+      ),
+    ).toBe(control.body.envelope?.envelopeType);
+    expect(withPrefix.body.usage?.inputTokens).toBe(control.body.usage?.inputTokens);
+    expect(
+      withPrefix.body.usage?.outputTokens,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 3',
+        'provider.usage.inputTokens/outputTokens MUST be identical hit-vs-miss (replay-invariant)',
+      ),
+    ).toBe(control.body.usage?.outputTokens);
+  });
+
+  it('(b) cache hit observable — a repeat generate shows cacheReadTokens > 0 while tokens stay invariant', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `hit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const prime = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (prime.status === 404 || prime.status === 405) return; // seam not wired
+    expect(prime.status).toBe(200);
+
+    const repeat = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    expect(repeat.status).toBe(200);
+    expect(
+      repeat.body.usage?.cacheReadTokens ?? 0,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 4',
+        'a repeat generate with the same cachePrefixId for the SAME tenant MUST be an observable cache hit (cacheReadTokens > 0)',
+      ),
+    ).toBeGreaterThan(0);
+    // The cost-only witness MUST NOT have changed the recorded outcome.
+    expect(repeat.body.usage?.inputTokens).toBe(prime.body.usage?.inputTokens);
+    expect(repeat.body.usage?.outputTokens).toBe(prime.body.usage?.outputTokens);
+  });
+
+  it('(c) cross-tenant isolation — tenant B first use of tenant A\'s cachePrefixId → cacheReadTokens == 0', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `xtenant-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Tenant A primes the cache under a shared, predictable cachePrefixId.
+    const aPrime = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (aPrime.status === 404 || aPrime.status === 405) return; // seam not wired
+    expect(aPrime.status).toBe(200);
+
+    // Tenant B's FIRST use of the SAME cachePrefixId MUST be a miss — the host
+    // keys its provider cache by (resolved tenant, cachePrefixId), never global.
+    const bFirst = await generate({ tenantId: 'tenant-b', cachePrefixId: prefixId });
+    expect(bFirst.status).toBe(200);
+    expect(
+      bFirst.body.usage?.cacheReadTokens ?? 0,
+      driver.describe(
+        'SECURITY/invariants.yaml prompt-prefix-cache-cross-tenant-isolation',
+        'tenant B\'s first use of tenant A\'s cachePrefixId MUST be a cache MISS (cacheReadTokens == 0) — the cache MUST be keyed by (tenant, cachePrefixId), never global; cross-tenant sharing is context leakage',
+      ),
+    ).toBe(0);
+  });
+
+  it('(d) secret-free — the response never echoes cachePrefixId in a SR-1-sensitive position', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `secretfree-${Date.now()}`;
+
+    const res = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (res.status === 404 || res.status === 405) return; // seam not wired
+    expect(res.status).toBe(200);
+    // The usage block is cost-only; it MUST NOT carry prompt/response substrings
+    // (SR-1). cachePrefixId is a public cache key, but the cost witness fields
+    // themselves are integers — assert the usage block is shape-clean.
+    const usage = res.body.usage ?? {};
+    for (const k of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'] as const) {
+      const v = usage[k];
+      if (v !== undefined) {
+        expect(
+          typeof v,
+          driver.describe(
+            'run-event-payloads.schema.json §providerUsage',
+            `provider.usage.${k} MUST be a cost-only integer (no prompt substrings per SR-1)`,
+          ),
+        ).toBe('number');
+      }
+    }
+  });
+});

package/src/scenarios/run-transport-economy.test.ts

@@ -0,0 +1,236 @@
+/**
+ * run-transport-economy — RFC 0115 behavioral.
+ *
+ * Status: ACTIVE (capability-gated behavioral). Gated on
+ * `capabilities.restTransport.conditionalRunGet === true` (conditional-GET
+ * leg) and on a non-empty `capabilities.restTransport.contentEncodings`
+ * (compression leg). Both legs soft-skip on hosts that do not advertise the
+ * surface (incl. the reference workflow-engine, which has not yet wired the
+ * sequence-derived `ETag` path), so they light up the moment a host advertises
+ * `restTransport`.
+ *
+ * Asserts (per `spec/v1/rest-endpoints.md` §"`GET /v1/runs/{runId}`
+ * conditional read + Content-Encoding (RFC 0115)"):
+ *
+ *   1. `GET /v1/runs/{runId}` carries a strong `ETag` on the `200`.
+ *   2. A re-`GET` with `If-None-Match: <current ETag>` returns `304 Not
+ *      Modified` with an empty body while the run has NOT advanced (the
+ *      validator is stable while no observable transition occurs).
+ *   3. After the run advances (the `conformance-approval` fixture is resumed
+ *      from `waiting-approval` to `completed`), the `ETag` CHANGES — proving
+ *      it is derived from the run's latest persisted event-log sequence
+ *      number, not a coarser signal that could leave a `304` stale.
+ *   4. For each advertised `contentEncodings` value, requesting it via
+ *      `Accept-Encoding` yields a `Content-Encoding`-tagged response whose
+ *      decoded bytes are byte-identical to the identity body.
+ *
+ * Non-vacuity: the `conformance-approval` fixture gives two deterministic,
+ * stable observable states (suspended → completed), so the ETag-stability and
+ * ETag-change assertions are exact rather than racing a fast run.
+ *
+ * @see RFCS/0115-run-transport-economy.md
+ * @see spec/v1/rest-endpoints.md §"`GET /v1/runs/{runId}` conditional read + Content-Encoding (RFC 0115)"
+ * @see spec/v1/replay.md §"durable event log" (the monotonic sequence the ETag derives from)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { gunzipSync, brotliDecompressSync } from 'node:zlib';
+import * as zlib from 'node:zlib';
+import { driver } from '../lib/driver.js';
+import { loadEnv } from '../lib/env.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+import { pollUntilStatus, pollUntilTerminal } from '../lib/polling.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const APPROVAL_FIXTURE = 'conformance-approval';
+const APPROVAL_NODE_ID = 'gate';
+const NOOP_FIXTURE = 'conformance-noop';
+
+type Encoding = 'gzip' | 'br' | 'zstd';
+
+interface RestTransportCaps {
+  conditionalRunGet?: unknown;
+  contentEncodings?: unknown;
+}
+
+async function readRestTransport(): Promise<RestTransportCaps | undefined> {
+  try {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200) return undefined;
+    return capabilityFamily<RestTransportCaps>(res.json, 'restTransport');
+  } catch {
+    return undefined;
+  }
+}
+
+/** Advertised content-encodings, narrowed to the spec enum. */
+function advertisedEncodings(caps: RestTransportCaps | undefined): Encoding[] {
+  const raw = caps?.contentEncodings;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((e): e is Encoding => e === 'gzip' || e === 'br' || e === 'zstd');
+}
+
+/** Read the run snapshot's ETag header (case-insensitive via Headers). */
+function etagOf(res: { headers: Headers }): string | null {
+  return res.headers.get('etag');
+}
+
+describe.skipIf(HTTP_SKIP)('run-transport-economy: conditional GET on run reads (RFC 0115)', () => {
+  it('emits a sequence-derived strong ETag, honors If-None-Match with 304, and rotates the ETag when the run advances', async (ctx) => {
+    const caps = await readRestTransport();
+    if (caps?.conditionalRunGet !== true) {
+      ctx.skip(); // host does not advertise restTransport.conditionalRunGet
+      return;
+    }
+
+    // Use the approval fixture: it parks at a stable `waiting-approval` state,
+    // then advances to `completed` on resolve — two deterministic snapshots.
+    const create = await driver.post('/v1/runs', { workflowId: APPROVAL_FIXTURE });
+    if (create.status === 404 || create.status === 422) {
+      ctx.skip(); // fixture not advertised by this host
+      return;
+    }
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilStatus(runId, 'waiting-approval', { timeoutMs: 10_000 });
+
+    // (1) Strong ETag present on the 200.
+    const suspendedRead = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    expect(suspendedRead.status).toBe(200);
+    const etagSuspended = etagOf(suspendedRead);
+    expect(
+      etagSuspended,
+      driver.describe(
+        'rest-endpoints.md §GET /v1/runs/{runId} conditional read (RFC 0115)',
+        'a host advertising restTransport.conditionalRunGet MUST return a strong ETag on the 200',
+      ),
+    ).toBeTruthy();
+
+    // (2) If-None-Match with the current ETag → 304, empty body, while unchanged.
+    const revalidate = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`, {
+      headers: { 'If-None-Match': etagSuspended as string },
+    });
+    expect(
+      revalidate.status,
+      driver.describe(
+        'rest-endpoints.md §GET /v1/runs/{runId} conditional read (RFC 0115)',
+        'If-None-Match matching the current ETag MUST return 304 Not Modified',
+      ),
+    ).toBe(304);
+    expect(
+      revalidate.text,
+      driver.describe(
+        'rest-endpoints.md §GET /v1/runs/{runId} conditional read (RFC 0115)',
+        '304 Not Modified MUST carry no body',
+      ),
+    ).toBe('');
+
+    // Advance the run: resolve the approval interrupt → terminal `completed`.
+    const resolve = await driver.post(
+      `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(APPROVAL_NODE_ID)}`,
+      { resumeValue: { action: 'accept' } },
+    );
+    expect(resolve.status).toBe(200);
+    const terminal = await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+    expect(terminal.status).toBe('completed');
+
+    // (3) ETag rotates after the observable state advanced.
+    const completedRead = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    expect(completedRead.status).toBe(200);
+    const etagCompleted = etagOf(completedRead);
+    expect(etagCompleted).toBeTruthy();
+    expect(
+      etagCompleted,
+      driver.describe(
+        'rest-endpoints.md §GET /v1/runs/{runId} conditional read (RFC 0115)',
+        'the ETag MUST change once the run advances (it is derived from the latest event-log sequence); a stable ETag across an observable transition would leave a 304 stale',
+      ),
+    ).not.toBe(etagSuspended);
+
+    // The new ETag is itself stable while the (now terminal) run does not change.
+    const revalidateTerminal = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`, {
+      headers: { 'If-None-Match': etagCompleted as string },
+    });
+    expect(
+      revalidateTerminal.status,
+      driver.describe(
+        'rest-endpoints.md §GET /v1/runs/{runId} conditional read (RFC 0115)',
+        'the terminal ETag MUST be stable — If-None-Match against it returns 304',
+      ),
+    ).toBe(304);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('run-transport-economy: Content-Encoding round-trips byte-identically (RFC 0115)', () => {
+  it('each advertised contentEncodings value decodes to the identity body byte-for-byte', async (ctx) => {
+    const caps = await readRestTransport();
+    const encodings = advertisedEncodings(caps);
+    if (encodings.length === 0) {
+      ctx.skip(); // host advertises no run-read content encodings
+      return;
+    }
+
+    // A terminal run gives a stable body to compare encodings against.
+    const create = await driver.post('/v1/runs', { workflowId: NOOP_FIXTURE });
+    if (create.status === 404 || create.status === 422) {
+      ctx.skip();
+      return;
+    }
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+
+    const env = loadEnv();
+    const url = `${env.baseUrl}/v1/runs/${encodeURIComponent(runId)}`;
+    const auth = { Authorization: `Bearer ${env.apiKey}`, Accept: 'application/json' };
+
+    // Identity baseline — explicit Accept-Encoding: identity so the host does
+    // not compress; raw bytes are the comparison oracle.
+    const identityRes = await fetch(url, { headers: { ...auth, 'Accept-Encoding': 'identity' } });
+    expect(identityRes.status).toBe(200);
+    const identityBytes = Buffer.from(await identityRes.arrayBuffer());
+    expect(identityBytes.length).toBeGreaterThan(0);
+
+    // Feature-detect zstd decode (Node >= 22.15 / 23.8); when absent we still
+    // assert the host negotiated Content-Encoding but defer the byte-compare.
+    // Cast-free: the optional-property view is assignable from the zlib module
+    // namespace under structural typing whether or not @types/node declares it.
+    const zlibMaybeZstd: { zstdDecompressSync?: (b: Buffer) => Buffer } = zlib;
+    const zstdDecode: ((b: Buffer) => Buffer) | undefined =
+      typeof zlibMaybeZstd.zstdDecompressSync === 'function'
+        ? zlibMaybeZstd.zstdDecompressSync
+        : undefined;
+
+    for (const enc of encodings) {
+      // Manually set Accept-Encoding so undici returns the raw compressed
+      // bytes (it only auto-decompresses encodings it negotiated itself).
+      const res = await fetch(url, { headers: { ...auth, 'Accept-Encoding': enc } });
+      expect(res.status).toBe(200);
+      const contentEncoding = res.headers.get('content-encoding');
+      expect(
+        contentEncoding,
+        driver.describe(
+          'rest-endpoints.md §GET /v1/runs/{runId} conditional read + Content-Encoding (RFC 0115)',
+          `a host advertising restTransport.contentEncodings:["...","${enc}"] MUST set Content-Encoding: ${enc} when that encoding is requested`,
+        ),
+      ).toBe(enc);
+
+      const compressedBytes = Buffer.from(await res.arrayBuffer());
+      const decode = enc === 'gzip' ? gunzipSync : enc === 'br' ? brotliDecompressSync : zstdDecode;
+      if (!decode) {
+        // zstd decode unavailable in this runtime: negotiation already
+        // asserted above; skip only the byte-compare for this encoding.
+        expect(compressedBytes.length).toBeGreaterThan(0);
+        continue;
+      }
+      const decoded = Buffer.from(decode(compressedBytes));
+      expect(
+        decoded.equals(identityBytes),
+        driver.describe(
+          'rest-endpoints.md §GET /v1/runs/{runId} conditional read + Content-Encoding (RFC 0115)',
+          `the ${enc}-decoded body MUST be byte-identical to the identity body (Content-Encoding MUST NOT alter decoded bytes or semantics)`,
+        ),
+      ).toBe(true);
+    }
+  });
+});