@openwop/openwop-conformance 1.10.0 → 1.11.0

package/src/scenarios/trigger-bridge-shape.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Durable trigger + channel bridge — subscription + events + profile shapes (RFC 0083).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `trigger-subscription.schema.json` round-trips a conforming
+ *     `TriggerSubscription` and rejects the malformed (missing REQUIRED `state`;
+ *     an out-of-enum `source`; an unknown property under
+ *     `additionalProperties:false`).
+ *   - the four-state vocabulary (`active`/`paused`/`failed`/`dead-lettered`) is
+ *     stable on the subscription `state` + the event `fromState`/`toState`.
+ *   - the `trigger.subscription.state.changed` + `trigger.delivery.attempted`
+ *     payload $defs validate conforming content-free records and reject malformed
+ *     ones (a missing `outcome`; an out-of-enum `outcome`), and both event names
+ *     appear in the RunEventType enum.
+ *   - `capabilities.triggerBridge` (+ `webhooks.durable`) is declared.
+ *   - `deriveProfiles` surfaces `openwop-trigger-bridge` for a host advertising
+ *     the bridge + a dead-letter sink + a durable source, and withholds it when
+ *     the dead-letter sink is absent (the §D predicate's OR + sink requirement).
+ *
+ * Behavioral assertions (the dedup → retry → dead-letter → causation delivery
+ * loop) are gated on the `openwop-trigger-bridge` profile and land in
+ * `trigger-bridge-delivery.test.ts` (deferred per RFC 0083 §Conformance —
+ * reference host deferred). This scenario asserts the wire contract, not host
+ * behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/trigger-bridge.md
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/profiles.md (§`openwop-trigger-bridge`)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0083-durable-trigger-and-channel-bridge-profile.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 { deriveProfiles } from '../lib/profiles.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>;
+}
+
+const STATES = ['active', 'paused', 'failed', 'dead-lettered'] as const;
+
+describe('trigger-bridge-shape: TriggerSubscription (RFC 0083 §B, server-free)', () => {
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const sub = loadSchema('trigger-subscription.schema.json');
+  const validate = ajv.compile(sub);
+
+  it('a conforming subscription validates', () => {
+    expect(
+      validate({ subscriptionId: 'sub-1', source: 'webhook', state: 'active', dedupEnabled: true, retryPolicy: { maxAttempts: 8, backoff: 'exponential' }, webhookId: 'wh-1', secretFingerprint: 'fp-abc' }),
+      why('trigger-bridge.md §B', 'a conforming TriggerSubscription MUST validate'),
+    ).toBe(true);
+  });
+
+  it('rejects a missing REQUIRED state, an out-of-enum source, and an unknown property', () => {
+    expect(validate({ subscriptionId: 's', source: 'webhook' }), why('trigger-bridge.md §B', 'state is REQUIRED')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'carrier-pigeon', state: 'active' }), why('trigger-bridge.md §B', 'source is a closed enum')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', body: 'inbound' }), why('trigger-bridge.md §B', 'TriggerSubscription MUST be additionalProperties:false')).toBe(false);
+  });
+
+  it('secretFingerprint MUST be bounded — a full 64-hex (unsalted-hash-smelling) digest is rejected', () => {
+    const truncated = 'a1b2c3d4e5f6a7b8';      // 16 hex — a truncated host-keyed fingerprint
+    const fullDigest = 'a'.repeat(64);          // 64 hex — smells like an unsalted SHA256(secret)
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: truncated }), why('trigger-bridge.md §B', 'a truncated fingerprint MUST validate')).toBe(true);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: fullDigest }), why('SR-1', 'a full 64-hex digest MUST be rejected (brute-force oracle)')).toBe(false);
+  });
+
+  it('the state enum is exactly the four §B states', () => {
+    const stateEnum = ((sub.properties as Record<string, { enum?: string[] }>).state?.enum) ?? [];
+    expect([...stateEnum].sort(), why('trigger-bridge.md §B', 'the four-state vocabulary MUST be stable')).toEqual([...STATES].sort());
+  });
+});
+
+describe('trigger-bridge-shape: trigger.* events (RFC 0083 §C, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const compile = (defName: string) => ajv.compile({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $defs: (payloads as { $defs: Record<string, unknown> }).$defs,
+    $ref: `#/$defs/${defName}`,
+  } as Record<string, unknown>);
+
+  it('trigger.subscription.state.changed validates + reason is a CLOSED enum (no URL-bearing free text)', () => {
+    const v = compile('triggerSubscriptionStateChanged');
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'dead-lettered', reason: 'retry-exhausted' }), why('trigger-bridge.md §C', 'state-changed MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active' }), why('trigger-bridge.md §C', 'toState is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'failed', reason: 'https://attacker.example/leak?token=sk' }), why('SR-1', 'a free-form / URL-bearing reason MUST be rejected')).toBe(false);
+  });
+
+  it('trigger.delivery.attempted validates + enforces the outcome enum', () => {
+    const v = compile('triggerDeliveryAttempted');
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'delivered', runId: 'run_x' }), why('trigger-bridge.md §C', 'delivery-attempted MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1 }), why('trigger-bridge.md §C', 'outcome is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'exploded' }), why('trigger-bridge.md §C', 'outcome is a closed enum')).toBe(false);
+  });
+
+  it('both trigger event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = ((runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum) ?? [];
+    for (const name of ['trigger.subscription.state.changed', 'trigger.delivery.attempted']) {
+      expect(enumVals.includes(name), why('run-event.schema.json', `${name} MUST be in the RunEventType enum`)).toBe(true);
+    }
+  });
+});
+
+describe('trigger-bridge-shape: capability + profile derivation (RFC 0083 §A/§D, server-free)', () => {
+  it('capabilities.triggerBridge + webhooks.durable are declared', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const props = caps.properties as Record<string, { properties?: Record<string, unknown> }>;
+    expect(props.triggerBridge?.properties?.supported, why('trigger-bridge.md §A', 'triggerBridge.supported MUST be declared')).toBeDefined();
+    expect(props.webhooks?.properties?.durable, why('trigger-bridge.md §A', 'webhooks.durable MUST be declared')).toBeDefined();
+  });
+
+  const coreBase = {
+    protocolVersion: '1.0',
+    supportedEnvelopes: ['clarification.request'],
+    schemaVersions: {},
+    limits: { clarificationRounds: 1, schemaRounds: 1, envelopesPerTurn: 1 },
+  };
+
+  it('deriveProfiles surfaces openwop-trigger-bridge for bridge + deadLetter + a durable source', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, deadLetter: { supported: true }, queueBus: { supported: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'bridge + sink + durable source MUST derive the profile')).toBe(true);
+  });
+
+  it('deriveProfiles withholds openwop-trigger-bridge when the dead-letter sink is absent', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, webhooks: { durable: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'no deadLetter sink ⇒ MUST NOT derive the profile')).toBe(false);
+  });
+});

package/src/scenarios/x-openwop-form-pack-manifest.test.ts

@@ -0,0 +1,155 @@
+/**
+ * `x-openwop-form` vendor-extension shape validation — `node-packs.md`
+ * §"`x-openwop-form` UX hints" (RFC 0066).
+ *
+ * Server-free, no host-advertisement gate: `x-openwop-form` is a
+ * CONSUMER-SIDE rendering hint that a pack author places on `configSchema`
+ * properties. Hosts do not advertise it; the contract is purely the shape a
+ * pack author targets. This scenario asserts the two shape-level guarantees
+ * the RFC's §Conformance pins:
+ *
+ *   1. A pack `configSchema` carrying `x-openwop-form` annotations remains a
+ *      VALID JSON Schema 2020-12 document — the annotation is an ignored
+ *      vendor keyword, so a schema validator (Ajv2020) compiles it without
+ *      error. This is the load-bearing additive promise: a consumer that
+ *      doesn't understand the keyword still validates config against the
+ *      schema unchanged.
+ *   2. The annotation OBJECT itself matches the §A vocabulary shape: `kind`
+ *      is REQUIRED and a string; the documented sub-fields (`dependsOn`,
+ *      `promptKind`, `provider`, `credentialProvider`) are optional strings.
+ *
+ * Forward-compat (RFC §A + §B, both `MUST`): an UNKNOWN `kind` value is still
+ * a structurally valid annotation — a renderer MUST treat it as if the hint
+ * were absent rather than reject it. So the shape schema accepts any string
+ * `kind`, NOT a closed enum; the four reserved kinds
+ * (`prompt-picker`/`provider-picker`/`model-picker`/`credential-picker`) are
+ * a renderer-routing vocabulary, not a validation constraint.
+ *
+ * NOTE: the renderer behavior matrix (which picker each `kind` produces, the
+ * `dependsOn` sibling-resolution + graceful fallback) is a reference-FRONTEND
+ * concern unit-tested in the workflow-engine sample, NOT a protocol wire
+ * shape — it is intentionally out of scope for this server-free scenario.
+ *
+ * @see spec/v1/node-packs.md §"`x-openwop-form` UX hints"
+ * @see RFCS/0066-x-openwop-form-vendor-extension.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import type { ErrorObject } from 'ajv';
+
+/** The §A `x-openwop-form` annotation shape. `kind` is the only required
+ *  field; it is an OPEN string (unknown kinds are valid per the forward-compat
+ *  MUST), with the documented sub-fields typed as optional strings. */
+const X_OPENWOP_FORM_SHAPE = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  required: ['kind'],
+  properties: {
+    kind: { type: 'string' },
+    dependsOn: { type: 'string' },
+    promptKind: { type: 'string' },
+    provider: { type: 'string' },
+    credentialProvider: { type: 'string' },
+  },
+  additionalProperties: false,
+} as const;
+
+/** A pack `configSchema` annotated for picker UX — the RFC §A positive
+ *  example (`core.ai.chatCompletion`-style): provider/model/credential/prompt
+ *  pickers with a `dependsOn` cascade. */
+function annotatedConfigSchema() {
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: {
+      provider: {
+        type: 'string',
+        'x-openwop-form': { kind: 'provider-picker' },
+      },
+      model: {
+        type: 'string',
+        'x-openwop-form': { kind: 'model-picker', dependsOn: 'provider' },
+      },
+      credential: {
+        type: 'string',
+        'x-openwop-form': { kind: 'credential-picker', dependsOn: 'provider' },
+      },
+      systemPrompt: {
+        type: 'string',
+        'x-openwop-form': { kind: 'prompt-picker', promptKind: 'system' },
+      },
+      temperature: { type: 'number', minimum: 0, maximum: 2 },
+    },
+    additionalProperties: false,
+  };
+}
+
+describe('category: x-openwop-form pack-manifest shape (RFC 0066)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validateShape = ajv.compile<Record<string, unknown>>(X_OPENWOP_FORM_SHAPE);
+
+  const shapeFailsWith = (annotation: unknown, keyword: string): ErrorObject[] => {
+    const ok = validateShape(annotation);
+    expect(ok).toBe(false);
+    return (validateShape.errors ?? []).filter((e) => e.keyword === keyword);
+  };
+
+  it('positive: a configSchema carrying x-openwop-form remains a valid JSON Schema 2020-12 document', () => {
+    // The annotation is an ignored vendor keyword — compiling MUST NOT throw,
+    // and the schema MUST still validate/reject instance config normally.
+    let validateConfig: ReturnType<typeof ajv.compile> | undefined;
+    expect(() => {
+      validateConfig = ajv.compile(annotatedConfigSchema());
+    }, 'node-packs.md §x-openwop-form: an annotated configSchema MUST remain a valid 2020-12 schema').not.toThrow();
+    // The annotations do not alter schema semantics: valid config passes…
+    expect(
+      validateConfig!({ provider: 'anthropic', model: 'claude', temperature: 1 }),
+      'x-openwop-form is advisory — it MUST NOT change what the schema accepts',
+    ).toBe(true);
+    // …and a type violation on an annotated field still rejects.
+    expect(validateConfig!({ provider: 123 })).toBe(false);
+  });
+
+  it('positive: each documented x-openwop-form annotation matches the §A shape', () => {
+    const cfg = annotatedConfigSchema();
+    for (const [name, prop] of Object.entries(cfg.properties)) {
+      const ann = (prop as Record<string, unknown>)['x-openwop-form'];
+      if (ann === undefined) continue;
+      expect(
+        validateShape(ann),
+        `node-packs.md §x-openwop-form: the annotation on "${name}" MUST match the §A shape. Errors: ${JSON.stringify(validateShape.errors)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('forward-compat: an unknown kind is a structurally valid annotation (renderer falls back per the §A MUST)', () => {
+    expect(
+      validateShape({ kind: 'unknown-future-picker' }),
+      'node-packs.md §x-openwop-form: an unknown kind MUST validate (kind is an open string, not a closed enum) so future vocabulary is forward-compatible',
+    ).toBe(true);
+  });
+
+  it('negative: an annotation missing kind is rejected', () => {
+    expect(
+      shapeFailsWith({ dependsOn: 'provider' }, 'required').length,
+      'node-packs.md §x-openwop-form: kind is the one REQUIRED sub-field',
+    ).toBeGreaterThan(0);
+  });
+
+  it('negative: a non-string kind is rejected', () => {
+    expect(
+      shapeFailsWith({ kind: 42 }, 'type').length,
+      'node-packs.md §x-openwop-form: kind MUST be a string',
+    ).toBeGreaterThan(0);
+  });
+
+  it('negative: a non-string dependsOn is rejected', () => {
+    expect(
+      shapeFailsWith({ kind: 'model-picker', dependsOn: ['provider'] }, 'type').length,
+      'node-packs.md §x-openwop-form: dependsOn names a sibling property — it MUST be a string',
+    ).toBeGreaterThan(0);
+  });
+});