@openwop/openwop-conformance 1.36.0 → 1.43.0

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);
+    }
+  });
+});

package/src/scenarios/tool-catalog-compact-projection.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Compact tool projection — `GET /v1/tools?view=compact` (RFC 0112) — behavioral.
+ *
+ * Capability-gated on `capabilities.toolCatalog.compactView === true` (root-first
+ * per RFC 0073). Soft-skips when unadvertised (default) / hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`. The standard projection coverage lives in
+ * `tool-catalog-projection.test.ts`; this asserts the OPT-IN compact view per
+ * `spec/v1/tool-catalog.md` §compact (and the new
+ * `compact-tool-descriptor.schema.json`):
+ *
+ *   1. ENVELOPE (§compact) — `GET /v1/tools?view=compact` returns the
+ *      `{ tools: CompactToolDescriptor[] }` envelope (NOT a bare array).
+ *   2. SCHEMA — every compact descriptor validates against
+ *      `compact-tool-descriptor.schema.json` (closed field set; the heavy
+ *      `ToolDescriptor` fields — `outputSchema`/`auth`/`egress`/`approval`/
+ *      `replayPolicy`/`costHint`/`latencyHint` — are ABSENT).
+ *   3. STRUCTURAL SUBSET — every present `inputSchema` satisfies the compact
+ *      structural subset: top-level `type: "object"` with `properties`, and
+ *      none of `$ref`/`oneOf`/`allOf`/`anyOf`/`not`/`patternProperties`/
+ *      `dependentSchemas`. Validated against the schema (no dereference of the
+ *      informative RFC 0030 Tier-1 table).
+ *   4. PROJECTION COMPLETENESS — the compact `tools[]` `toolId` set EQUALS the
+ *      standard `tools[]` `toolId` set for the same principal (a compact catalog
+ *      that drops a tool the standard view shows is non-conformant;
+ *      authorization-scoping preserved).
+ *   5. BY-ID — `GET /v1/tools/{toolId}?view=compact` returns one schema-valid
+ *      CompactToolDescriptor.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/tool-catalog.md (§compact)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0112-compact-tool-projection.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 { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import {
+  readToolCatalogCap,
+  listToolsCompact,
+  COMPACT_DROPPED_FIELDS,
+  findBannedInputSchemaKeyword,
+  type CompactToolDescriptor,
+} from '../lib/toolCatalog.js';
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+/** Extract the `toolId` set from a `GET /v1/tools` body, tolerating both the
+ *  bare-array and `{ tools: [] }` envelope standard shapes (cast-free). */
+function toolIdSet(body: unknown): Set<string> {
+  const ids = new Set<string>();
+  const arr: unknown[] = Array.isArray(body)
+    ? body
+    : body && typeof body === 'object' && Array.isArray((body as { tools?: unknown }).tools)
+      ? ((body as { tools: unknown[] }).tools)
+      : [];
+  for (const t of arr) {
+    if (t && typeof t === 'object') {
+      const id = (t as { toolId?: unknown }).toolId;
+      if (typeof id === 'string') ids.add(id);
+    }
+  }
+  return ids;
+}
+
+describe('tool-catalog-compact-projection (RFC 0112 §compact)', () => {
+  it('serves the { tools: CompactToolDescriptor[] } projection — closed shape, bounded inputSchema, same toolId set as standard', async () => {
+    const cap = await readToolCatalogCap();
+    if (!behaviorGate('openwop-tool-catalog-compact', cap?.compactView === true)) return;
+
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(loadSchema('compact-tool-descriptor.schema.json'));
+
+    // ---- Leg 1: the compact envelope (§compact) -------------------------
+    const compact = await listToolsCompact();
+    if (compact === null) return; // advertises the cap but doesn't serve the read — soft-skip the rest
+
+    for (const t of compact) {
+      // ---- Leg 2: schema validity + heavy fields dropped ----------------
+      expect(
+        validate(t),
+        driver.describe('compact-tool-descriptor.schema.json', `each CompactToolDescriptor MUST validate (${ajv.errorsText(validate.errors)})`),
+      ).toBe(true);
+      for (const f of COMPACT_DROPPED_FIELDS) {
+        expect(
+          !(f in t),
+          driver.describe('tool-catalog.md §compact', `CompactToolDescriptor MUST drop the heavy field "${f}"`),
+        ).toBe(true);
+      }
+
+      // ---- Leg 3: the compact structural subset on inputSchema ----------
+      const input = (t as CompactToolDescriptor).inputSchema;
+      if (input !== undefined) {
+        expect(
+          input.type === 'object' && typeof input.properties === 'object' && input.properties !== null,
+          driver.describe('tool-catalog.md §compact', 'compact inputSchema MUST be top-level type:"object" with a properties map'),
+        ).toBe(true);
+        // Total (any-depth), schema-aware: a nested oneOf/$ref under a property
+        // schema is exactly the verbosity the compact view exists to drop.
+        const banned = findBannedInputSchemaKeyword(input);
+        expect(
+          banned,
+          driver.describe('tool-catalog.md §compact', `compact inputSchema MUST NOT use $ref/oneOf/allOf/anyOf/not/patternProperties/dependentSchemas at any nesting depth (found "${banned ?? 'none'}")`),
+        ).toBe(null);
+      }
+    }
+
+    // ---- Leg 4: projection completeness vs the standard view -------------
+    const standardRes = await driver.get('/v1/tools');
+    const standardIds = toolIdSet(standardRes.json);
+    const compactIds = new Set<string>();
+    for (const t of compact) {
+      if (typeof t.toolId === 'string') compactIds.add(t.toolId);
+    }
+    const sameSet =
+      standardIds.size === compactIds.size && [...standardIds].every((id) => compactIds.has(id));
+    expect(
+      sameSet,
+      driver.describe(
+        'tool-catalog.md §compact',
+        `compact tools[] MUST carry the same toolId set as the standard view (standard=${[...standardIds].sort().join(',')} compact=${[...compactIds].sort().join(',')})`,
+      ),
+    ).toBe(true);
+
+    // ---- Leg 5: by-id compact round-trip --------------------------------
+    if (compact.length > 0 && typeof compact[0]!.toolId === 'string') {
+      const id = compact[0]!.toolId;
+      const one = await driver.get(`/v1/tools/${encodeURIComponent(id)}?view=compact`);
+      if (one.status === 200) {
+        expect(
+          validate(one.json),
+          driver.describe('compact-tool-descriptor.schema.json', `GET /v1/tools/{toolId}?view=compact MUST return a valid CompactToolDescriptor (${ajv.errorsText(validate.errors)})`),
+        ).toBe(true);
+        const got = one.json;
+        expect(
+          got && typeof got === 'object' && (got as { toolId?: unknown }).toolId === id,
+          driver.describe('tool-catalog.md §compact', 'GET /v1/tools/{toolId}?view=compact MUST return the requested descriptor'),
+        ).toBe(true);
+      }
+    }
+  });
+});