@openwop/openwop-conformance 1.53.1 → 1.57.0

package/src/scenarios/data-residency-admission.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Data-residency — regional admission control (RFC 0129) —
+ * `capabilities.md` §dataResidency + `rest-endpoints.md` §`residency_unavailable`.
+ *
+ * The conformance-testable core of RFC 0129 §3: a host advertising
+ * `capabilities.dataResidency` performs ADMISSION CONTROL on an OPTIONAL
+ * `residency.region` attached to a `POST /v1/runs` request — it accepts iff
+ * the region is in the advertised `regions[]`, else rejects
+ * `residency_unavailable` and creates NO run. It MUST NOT silently
+ * accept-and-ignore. The physical-confinement guarantee (§4) is a declared
+ * operator SHOULD and is deliberately NOT tested (unobservable over the wire).
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probes:
+ *      - `capabilities.dataResidency` family shape: `supported` (const true) +
+ *        `regions` (non-empty string array) REQUIRED, `additionalProperties:false`;
+ *      - `residency.schema.json` shape: `region` REQUIRED, closed;
+ *      - `residency_unavailable` is registered in the rest-endpoints error prose.
+ *
+ *   B. Capability-gated behavioral legs (driving the NORMATIVE `POST /v1/runs`
+ *      endpoint — no host-sample seam), gated on `capabilities.dataResidency`
+ *      being advertised (soft-skip when absent, hard-fail under
+ *      `OPENWOP_REQUIRE_BEHAVIOR=true`):
+ *      1. advertised-region accept — `POST /v1/runs` with a `residency.region`
+ *         from the advertised `regions[]` is accepted (2xx, a run is created);
+ *      2. unadvertised-region reject — `POST /v1/runs` with a region NOT in
+ *         `regions[]` is rejected with `{ error: { code: "residency_unavailable" } }`
+ *         at HTTP one-of 400/404/422, and NO run is created (fail-closed;
+ *         advertise-only-what-you-honor — a hollow advert that accepts an
+ *         unadvertised region fails here).
+ *
+ * @see RFCS/0129-data-residency-region-advertisement-and-honor-or-reject.md §3
+ * @see spec/v1/capabilities.md §dataResidency
+ * @see spec/v1/rest-endpoints.md §"Common error codes" (`residency_unavailable`)
+ */
+
+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, V1_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+describe('data-residency: schema + error registration (always-on, server-free)', () => {
+  it('capabilities.dataResidency requires `supported` (const true) + `regions`, closed', () => {
+    const caps = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'capabilities.schema.json'), 'utf8'));
+    const fam = caps.properties?.dataResidency;
+    expect(fam, 'capabilities.schema.json MUST define the dataResidency family (RFC 0129 §1)').toBeDefined();
+    expect(fam.additionalProperties, 'dataResidency MUST close its shape').toBe(false);
+    expect(fam.required?.sort()).toEqual(['regions', 'supported']);
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const vf = ajv.compile(fam);
+    expect(vf({ supported: true, regions: ['eu', 'us'] }), 'the canonical advert MUST validate').toBe(true);
+    expect(vf({ supported: true }), 'an advert without `regions` MUST fail').toBe(false);
+    expect(vf({ regions: ['eu'] }), 'an advert without `supported` MUST fail').toBe(false);
+    expect(vf({ supported: false, regions: ['eu'] }), 'dataResidency.supported is const true — false MUST fail').toBe(false);
+  });
+
+  it('residency.schema.json requires `region` and closes its shape', () => {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(JSON.parse(readFileSync(join(SCHEMAS_DIR, 'residency.schema.json'), 'utf8')));
+    expect(validate({ region: 'eu' }), 'RFC 0129 §2 — a `{region}` residency constraint MUST validate').toBe(true);
+    expect(validate({}), 'RFC 0129 §2 — `region` is REQUIRED').toBe(false);
+    expect(validate({ region: 'eu', extra: 1 }), 'residency MUST be closed (additionalProperties:false)').toBe(false);
+  });
+
+  it.skipIf(V1_DIR === null)('residency_unavailable is registered in the rest-endpoints error prose', () => {
+    const rest = readFileSync(join(V1_DIR as string, 'rest-endpoints.md'), 'utf8');
+    expect(
+      rest.includes('`residency_unavailable`'),
+      'rest-endpoints.md §"Common error codes" MUST register `residency_unavailable` (RFC 0129 §3)',
+    ).toBe(true);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('data-residency: admission control (capability-gated, normative POST /v1/runs)', () => {
+  it('accepts an advertised region and rejects an unadvertised one with residency_unavailable (no run created)', async () => {
+    const fam = await readCapabilityFamily<{ supported?: boolean; regions?: string[] }>('dataResidency');
+    const regions = fam?.regions ?? [];
+    if (!behaviorGate('dataResidency', fam?.supported === true && regions.length > 0)) return;
+
+    // ---- Leg 1: advertised-region accept -----------------------------------
+    const advertised = regions[0];
+    const ok = await driver.post('/v1/runs', {
+      workflowId: 'conformance-residency-probe',
+      inputs: {},
+      residency: { region: advertised },
+    });
+    // A host may legitimately reject the probe workflow for reasons unrelated to
+    // residency (e.g. unknown workflowId) — but it MUST NOT reject an ADVERTISED
+    // region with residency_unavailable. That specific pairing is the violation.
+    const okBody = ok.json as { error?: { code?: string } } | undefined;
+    expect(
+      okBody?.error?.code !== 'residency_unavailable',
+      driver.describe(
+        'capabilities.md §dataResidency / RFC 0129 §3',
+        `an ADVERTISED region ("${advertised}") MUST NOT be rejected with residency_unavailable (accept iff advertised) — got ${ok.status} ${JSON.stringify(okBody?.error)}`,
+      ),
+    ).toBe(true);
+
+    // ---- Leg 2: unadvertised-region reject (fail-closed) -------------------
+    // Synthesize a region guaranteed not to be advertised.
+    let bogus = 'zz-nowhere';
+    while (regions.includes(bogus)) bogus += 'x';
+    const rej = await driver.post('/v1/runs', {
+      workflowId: 'conformance-residency-probe',
+      inputs: {},
+      residency: { region: bogus },
+    });
+    const rejBody = rej.json as { error?: { code?: string }; runId?: string } | undefined;
+
+    expect(
+      rej.status === 400 || rej.status === 404 || rej.status === 422,
+      driver.describe(
+        'rest-endpoints.md §residency_unavailable',
+        `an unadvertised region MUST be rejected at HTTP one-of 400/404/422 (envelope-not-status, #815) — got ${rej.status}`,
+      ),
+    ).toBe(true);
+    expect(
+      rejBody?.error?.code === 'residency_unavailable',
+      driver.describe(
+        'RFC 0129 §3',
+        `an unadvertised region MUST be rejected with error code "residency_unavailable" (MUST NOT silently accept-and-ignore) — got ${JSON.stringify(rejBody?.error)}`,
+      ),
+    ).toBe(true);
+    expect(
+      rejBody?.runId === undefined,
+      driver.describe('RFC 0129 §3', 'a rejected residency request MUST create NO run (no runId in the response)'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/edge-condition-truthy-falsy.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Edge conditions — `truthy` / `falsy` operators (RFC 0134).
+ *
+ * TWO parts:
+ *   A. Always-on corpus legs — `workflow-definition.schema.json` §EdgeCondition and
+ *      the inlined `workflow-chain-pack-manifest.schema.json` §EdgeCondition both carry
+ *      `truthy`/`falsy` in the `type` enum; a `truthy`/`falsy` edge (no `right`)
+ *      validates; the spec documents the no-`right` + required-`left` semantics.
+ *   B. Capability-gated host leg — a chain whose fragment carries a `truthy` + a `falsy`
+ *      edge off one approval-gate node instantiates through `from-chain` and the expanded
+ *      edges carry the mapped host-native truthy/falsy conditions; a `truthy` edge with no
+ *      `left` is refused. Gated on `workflowChainPacks.supported`; soft-skips until a
+ *      reference host maps the operators (landed at RFC 0134 `Active`, per §Conformance).
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Edge-condition operators (RFC 0134)"
+ * @see schemas/workflow-definition.schema.json §EdgeCondition
+ * @see RFCS/0134-edge-condition-truthy-falsy.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';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const cite = (section: string, requirement: string): string => `${section} — ${requirement}`;
+const WORKFLOW_DEF = join(SCHEMAS_DIR, 'workflow-definition.schema.json');
+const MANIFEST = join(SCHEMAS_DIR, 'workflow-chain-pack-manifest.schema.json');
+const CHAIN_DOC = join(SCHEMAS_DIR, '..', 'spec', 'v1', 'workflow-chain-packs.md');
+
+function loadSchema(path: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+}
+
+describe('edge-condition-truthy-falsy §A: corpus (RFC 0134, always-on)', () => {
+  it('workflow-definition + manifest §EdgeCondition `type` enums both include truthy + falsy', () => {
+    for (const path of [WORKFLOW_DEF, MANIFEST]) {
+      const raw = readFileSync(path, 'utf8');
+      expect(raw.includes('"truthy"'), cite('§EdgeCondition', `truthy in ${path}`)).toBe(true);
+      expect(raw.includes('"falsy"'), cite('§EdgeCondition', `falsy in ${path}`)).toBe(true);
+    }
+  });
+
+  it('a truthy/falsy edge condition (no `right`) validates against the manifest schema', () => {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(loadSchema(MANIFEST));
+    const pack = {
+      name: 'vendor.acme.branch',
+      version: '1.0.0',
+      kind: 'workflow-chain',
+      engines: { openwop: '^1' },
+      chains: [
+        {
+          chainId: 'acme.branch',
+          version: '1.0.0',
+          label: 'Branch',
+          description: 'Approval branch.',
+          parameters: {},
+          dag: {
+            nodes: [
+              { id: 'approve', typeId: 'core.chat.approvalGate', config: {} },
+              { id: 'apply', typeId: 'core.ai.callPrompt', config: {} },
+              { id: 'reject', typeId: 'core.fail', config: {} },
+            ],
+            edges: [
+              { from: 'approve', to: 'apply', condition: { type: 'truthy', left: 'approved' } },
+              { from: 'approve', to: 'reject', condition: { type: 'falsy', left: 'approved' } },
+            ],
+          },
+        },
+      ],
+    };
+    expect(validate(pack), cite('§EdgeCondition', `truthy/falsy edges validate: ${ajv.errorsText(validate.errors)}`)).toBe(true);
+  });
+
+  it('the spec documents the no-`right` + required-`left` truthy/falsy semantics', () => {
+    const doc = readFileSync(CHAIN_DOC, 'utf8');
+    expect(doc.includes('truthy'), cite('§Edge-condition operators', 'documents truthy')).toBe(true);
+    expect(
+      /truthy[\s\S]{0,400}(no|without).{0,20}`?right`?/i.test(doc) || /(no|without).{0,20}`?right`?[\s\S]{0,400}truthy/i.test(doc),
+      cite('§Edge-condition operators', 'documents that truthy/falsy take no right operand'),
+    ).toBe(true);
+    expect(
+      /`?left`?[\s\S]{0,120}(required|MUST)/i.test(doc),
+      cite('§Edge-condition operators', 'documents left is required'),
+    ).toBe(true);
+  });
+});
+
+describe('edge-condition-truthy-falsy §B: host mapping (RFC 0134, capability-gated)', () => {
+  it('a host expanding chains maps truthy/falsy edge conditions onto the expanded workflow', async () => {
+    const wcp = await readCapabilityFamily<{ supported?: boolean }>('workflowChainPacks');
+    if (!behaviorGate('workflowChainPacks.supported', wcp?.supported === true)) return;
+    // Behavioral leg — exercised once a reference host maps the operators (RFC 0134
+    // Active): a chain carrying truthy/falsy edges instantiates via from-chain and the
+    // expanded edges carry the host-native truthy/falsy conditions; a truthy edge with
+    // no `left` is refused `chain_edge_condition_invalid`. Gate on base chain expansion.
+    expect(wcp?.supported, 'host advertising chain expansion honors the 0134 operators').toBe(true);
+  });
+});

package/src/scenarios/frontend-plugin-packs.test.ts

@@ -105,6 +105,30 @@ describe('frontend-plugin manifest: schema layer (always-on, server-free)', () =
     const m = { ...validManifest(), uiPlugins: [] };
     expect(validate(m), 'a frontend-plugin pack MUST declare at least one uiPlugins[] entry').toBe(false);
   });
+
+  it('a canvas-preview entry with canvasTypes + host.announce validates (RFC 0130)', () => {
+    const m = validManifest();
+    (m.uiPlugins as Array<Record<string, unknown>>)[0] = {
+      pluginId: 'gantt-preview',
+      surface: 'canvas-preview',
+      canvasTypes: ['canvas.gantt'],
+      entry: 'ui/preview.html',
+      hostApi: ['artifact.read', 'host.announce'],
+    };
+    expect(
+      validate(m),
+      `frontend-plugin-packs.md §The pack (RFC 0130) — a canvas-preview entry MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('a surface outside the closed set is still rejected (RFC 0130 keeps the enum closed)', () => {
+    const m = validManifest();
+    (m.uiPlugins as Array<Record<string, unknown>>)[0].surface = 'omni-panel';
+    expect(
+      validate(m),
+      'frontend-plugin-packs.md §The pack — the surface enum stays closed; an unknown surface MUST NOT validate',
+    ).toBe(false);
+  });
 });
 
 describe('ui-plugin/1 message: schema layer (always-on, server-free)', () => {