@openwop/openwop-conformance 1.0.0

package/schemas/workflow-definition.schema.json

@@ -0,0 +1,430 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/workflow-definition.schema.json",
+  "title": "WorkflowDefinition",
+  "description": "DAG of typed nodes, edges, triggers, and variables that an OpenWOP host executes. Canonical OpenWOP v1 workflow-definition shape.",
+  "type": "object",
+  "required": ["id", "name", "version", "nodes", "edges", "triggers", "variables", "metadata", "settings"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique workflow identifier. Recommended format: lowercase, hyphen-separated.",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9_-]*$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "description": { "type": "string" },
+    "version": {
+      "type": "string",
+      "description": "Semver-like workflow version. Tracked separately from engineVersion + eventLogSchemaVersion (see version-negotiation.md).",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "description": "Optional category for filtering."
+    },
+    "isActive": { "type": "boolean" },
+    "status": {
+      "type": "string",
+      "enum": ["active", "inactive", "draft", "archived"]
+    },
+    "tenantId": {
+      "type": "string",
+      "description": "Optional tenant/workspace scoping. The protocol uses the neutral term `tenantId`."
+    },
+    "scopeId": {
+      "type": "string",
+      "description": "Optional project/scope correlation. The protocol uses the neutral term `scopeId`."
+    },
+    "slug": {
+      "type": "string",
+      "description": "URL-friendly slug.",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$"
+    },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/WorkflowNode" },
+      "minItems": 1
+    },
+    "edges": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/WorkflowEdge" }
+    },
+    "triggers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/WorkflowTrigger" }
+    },
+    "variables": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/WorkflowVariable" }
+    },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/NodeGroup" },
+      "description": "Visual node groups (organizational only; do not affect execution)."
+    },
+    "channels": {
+      "description": "Optional typed state channels (see channels-and-reducers.md). When present, channel-aware mode applies.",
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/ChannelDeclaration" }
+    },
+    "configurableSchema": {
+      "description": "Optional JSON Schema 2020-12 declaring which RunOptions.configurable keys this workflow accepts. When present, hosts MUST validate POST /v1/runs `configurable` payloads against this schema and reject mismatches with `validation_error`. Hosts MUST surface this schema on GET /v1/workflows/{workflowId} so clients can pre-flight-validate. See run-options.md §'Per-workflow configurableSchema'. Additive in v1.1.",
+      "type": "object"
+    },
+    "metadata": { "$ref": "#/$defs/WorkflowMetadata" },
+    "settings": { "$ref": "#/$defs/WorkflowSettings" },
+    "acceptsInheritedArtifacts": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Declares which inherited artifacts this workflow accepts when run as a child of a sub-workflow."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "WorkflowNode": {
+      "type": "object",
+      "required": ["id", "typeId", "name", "position", "config", "inputs"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "typeId": {
+          "type": "string",
+          "description": "Canonical node type ID (e.g., 'core.ai.callPrompt', 'core.chat.approvalGate'). Reserved prefixes: 'core.*' for spec-canonical, 'vendor.<org>.*' for third-party.",
+          "minLength": 1,
+          "pattern": "^[a-z][a-zA-Z0-9._-]*$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "position": {
+          "type": "object",
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          }
+        },
+        "config": {
+          "type": "object",
+          "description": "Node configuration (pre-execution constants)."
+        },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/PortValue" },
+          "description": "Input port connections. Keys are port names; values are PortValue references."
+        },
+        "credentialsRef": { "type": "string" },
+        "settings": { "type": "object" },
+        "disabled": { "type": "boolean", "default": false },
+        "notes": { "type": "string" },
+        "groupId": { "type": "string" },
+        "agent": {
+          "$ref": "agent-ref.schema.json",
+          "description": "Multi-Agent Shift Phase 1. Optional compile-time pinning of which agent executes this node. When set, the engine surfaces this AgentRef on the `RunSnapshot.agent` field while the node is active, and emits an `agent.handoff` event when control transitions from the prior node's agent (if different). Resolution at runtime: the engine MAY override via dispatch (RFC 0012 / `core.dispatch`) or orchestrator decision (RFC 0011); the node's `agent?` is the default authoring-time pin, not a hard binding."
+        },
+        "envelopeContract": { "type": "object" },
+        "artifactType": {
+          "type": "string",
+          "description": "Artifact type this node produces or reviews (first-class typed field — replaces the deprecated config.outputArtifactType bag entry)."
+        },
+        "cardType": {
+          "type": "string",
+          "description": "Explicit chat card type override (first-class typed field — replaces the deprecated config.chatCard bag entry)."
+        },
+        "outputSensitivity": {
+          "type": "object",
+          "additionalProperties": { "type": "boolean" },
+          "description": "Per-output-port sensitivity overrides. Map of port name → boolean. When true, the engine masks the named output value in `node.completed` event payloads. Layered on top of pack-level `nodes[].outputs[port].sensitive` declarations: workflow-level true takes precedence over pack-level false (and vice versa — last writer wins, but typically pack defaults are conservative and workflow overrides are explicit). See observability.md §Privacy classification (closes O5)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "WorkflowEdge": {
+      "type": "object",
+      "required": ["id", "sourceNodeId", "targetNodeId"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "sourceNodeId": { "type": "string", "minLength": 1 },
+        "sourceOutput": {
+          "type": "string",
+          "description": "Source output port key. Default 'output'."
+        },
+        "targetNodeId": { "type": "string", "minLength": 1 },
+        "targetInput": {
+          "type": "string",
+          "description": "Target input port key. Default 'input'."
+        },
+        "condition": { "$ref": "#/$defs/EdgeCondition" },
+        "label": { "type": "string" },
+        "triggerRule": {
+          "type": "string",
+          "enum": ["all_success", "any_success", "all_complete", "none_failed", "any_failed"],
+          "default": "all_success"
+        }
+      },
+      "additionalProperties": false
+    },
+    "EdgeCondition": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["expression", "equals", "notEquals", "contains", "regex"]
+        },
+        "left": { "type": "string", "description": "Left operand path (e.g., 'status', 'output.approved')." },
+        "right": { "description": "Right operand value (any JSON value)." },
+        "expression": { "type": "string", "description": "Used when type='expression'." }
+      },
+      "additionalProperties": false
+    },
+    "PortValue": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "value"],
+          "properties": {
+            "type": { "const": "static" },
+            "value": {}
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type", "expression"],
+          "properties": {
+            "type": { "const": "expression" },
+            "expression": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type", "nodeId", "outputKey"],
+          "properties": {
+            "type": { "const": "connection" },
+            "nodeId": { "type": "string", "minLength": 1 },
+            "outputKey": { "type": "string", "minLength": 1 },
+            "optional": { "type": "boolean", "default": false }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type", "variableName"],
+          "properties": {
+            "type": { "const": "variable" },
+            "variableName": { "type": "string", "minLength": 1 },
+            "optional": { "type": "boolean", "default": false }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "WorkflowTrigger": {
+      "type": "object",
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": {
+          "type": "string",
+          "enum": ["manual", "schedule", "webhook", "event", "artifact", "canvas", "envelope", "command", "chat-message", "channel-write"],
+          "description": "Trigger discriminator. The `channel-write` variant fires a node when a named channel receives a write (closes C2 — reactive cross-engine pattern). Its `config` shape: `{channel: string, onlyFrom?: 'child'|'parent'|'any', debounceMs?: integer}`. See channels-and-reducers.md §Distributed reducers."
+        },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "config": { "type": "object" },
+        "enabled": { "type": "boolean", "default": true },
+        "nodeId": { "type": "string" },
+        "eventType": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "WorkflowVariable": {
+      "type": "object",
+      "required": ["name", "type"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "object", "array"]
+        },
+        "description": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "defaultValue": {},
+        "sensitive": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, the engine masks this variable's value in persisted `variable.changed` events, `state.snapshot` projections, and `RunSnapshot.variables`. Reads inside NodeModule executors work normally; only persistence + external surfaces mask. See observability.md §Privacy classification (closes O5)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "NodeGroup": {
+      "type": "object",
+      "required": ["id", "name", "nodeIds", "position", "size"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "color": { "type": "string" },
+        "collapsed": { "type": "boolean", "default": false },
+        "nodeIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "position": {
+          "type": "object",
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          }
+        },
+        "size": {
+          "type": "object",
+          "required": ["width", "height"],
+          "properties": {
+            "width": { "type": "number" },
+            "height": { "type": "number" }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ChannelDeclaration": {
+      "type": "object",
+      "required": ["reducer"],
+      "properties": {
+        "reducer": {
+          "type": "string",
+          "description": "Canonical names: 'replace', 'append', 'merge', 'counter', 'votes', 'feedback', 'message' (Multi-Agent Shift Phase 1 — append-only + idempotent on `messageId`). Custom reducers MUST use 'vendor.<org>.<name>'.",
+          "pattern": "^(replace|append|merge|counter|votes|feedback|message|vendor\\.[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_-]*)$"
+        },
+        "schema": { "type": "object" },
+        "default": {},
+        "maxSize": { "type": "integer", "minimum": 1 },
+        "ttlMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 31536000000,
+          "description": "Optional entry-age TTL in milliseconds (closes C3). Applies to `append` / `votes` / `feedback` reducers; ignored on others. Engine drops entries older than this age (lazy: on read or next write). Range: 1..1 year. Replay-safe — uses original event timestamps for comparison. See channels-and-reducers.md §Channel TTL."
+        },
+        "options": { "type": "object" },
+        "access": { "$ref": "#/$defs/ChannelAccess" },
+        "schemaVersion": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Integer version of the current `schema`. Increments whenever the channel author edits `schema`. Each `channel.written` event records this version at write time. (closes C4)"
+        },
+        "compatibleWith": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 },
+          "uniqueItems": true,
+          "description": "Older schema versions whose persisted writes are forward-readable under the CURRENT schema. The engine validates each old write against the current schema during fold; pass = include, fail = hard error `channel_schema_breaking_change`. Empty/omitted = no backward compat (any older write trips the breaking-change error). For breaking edits, authors create a new channel name + a copy node — see channels-and-reducers.md §Channel schema migration."
+        },
+        "sensitive": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, the engine masks `channel.written` event payloads' `value` field. The reduced channel state in `RunSnapshot.channels` is also masked when read via the REST surface. See observability.md §Privacy classification (closes O5)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ChannelAccess": {
+      "description": "Per-channel access control. See channels-and-reducers.md §Channel access control (closes C1). Three forms: 'public' (no restriction; same as omitting), 'private' (lockdown shorthand — equivalent to {readers: [], writers: []}), or an explicit {readers?, writers?} object where each side is independently scoped (omitted = open, present = strict allowlist).",
+      "oneOf": [
+        { "const": "public" },
+        { "const": "private" },
+        {
+          "type": "object",
+          "properties": {
+            "readers": { "$ref": "#/$defs/ChannelAccessList" },
+            "writers": { "$ref": "#/$defs/ChannelAccessList" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "ChannelAccessList": {
+      "type": "array",
+      "description": "Allowlist entries. Each item matches against the requesting node's `nodeId` (exact) OR `typeId` (wildcard). Wildcard format: dotted prefix + '*' (e.g., 'core.ai.*'). Bare '*' matches any node.",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256,
+        "pattern": "^([a-z][a-zA-Z0-9._-]*\\*?|\\*)$"
+      },
+      "uniqueItems": true,
+      "maxItems": 256
+    },
+    "WorkflowMetadata": {
+      "type": "object",
+      "properties": {
+        "createdBy": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "updatedBy": { "type": "string" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1, "maxLength": 256 },
+          "maxItems": 100
+        },
+        "category": { "type": "string" },
+        "author": { "type": "string" },
+        "codeVersion": { "type": "string" },
+        "customizedAt": { "type": "string", "format": "date-time" },
+        "customizedBy": { "type": "string" },
+        "forkedFrom": { "type": "string", "description": "ID of platform template this was forked from." },
+        "clonedFrom": { "type": "string", "description": "ID of workflow this was cloned from (project clone, not template fork)." },
+        "clonedAt": { "type": "string", "format": "date-time" },
+        "customProperties": { "type": "object" },
+        "complianceClass": {
+          "type": "string",
+          "enum": ["public", "pii", "phi", "pci", "regulated"],
+          "default": "public",
+          "description": "Top-level workflow sensitivity tier. Sets the `openwop.compliance_class` span attribute on every span the run produces. Drives default retention / masking / export-gating policy at observability collectors. See observability.md §Privacy classification (closes O5)."
+        },
+        "complianceConfig": {
+          "type": "object",
+          "description": "Optional per-workflow overrides for compliance behavior. The masking mode (`mask` | `omit` | `hash` | `passthrough`) defaults to the server's `Capabilities.compliance.defaultMode`; setting it here forces a specific mode for this workflow. Domain-specific extensions (HIPAA's 18 PHI identifiers, GDPR special categories) can live here as opt-in fields.",
+          "properties": {
+            "maskingMode": {
+              "type": "string",
+              "enum": ["mask", "omit", "hash", "passthrough"],
+              "description": "Per-workflow override of the server's default masking mode."
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    },
+    "WorkflowSettings": {
+      "type": "object",
+      "properties": {
+        "timeout": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum run duration in milliseconds."
+        },
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "logLevel": {
+          "type": "string",
+          "enum": ["debug", "info", "warn", "error"]
+        },
+        "maxLoopbackIterations": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 5
+        }
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * `openwop-conformance` — operator-facing CLI for running the openwop
+ * conformance suite against a deployed server.
+ *
+ * Wraps `vitest` with friendlier args + structured exit codes so it
+ * works as the `npm test` entry for downstream packages.
+ *
+ * Usage:
+ *   openwop-conformance --base-url https://api.example.com --api-key hk_test_123
+ *   openwop-conformance --offline                       # server-free subset only
+ *   openwop-conformance --filter discovery               # category filter
+ *   openwop-conformance --base-url ... --api-key ... --filter "interrupt|cancellation"
+ *
+ * Environment variables override flags (per the conformance harness's
+ * existing convention):
+ *   OPENWOP_BASE_URL, OPENWOP_API_KEY, OPENWOP_IMPLEMENTATION_NAME,
+ *   OPENWOP_IMPLEMENTATION_VERSION, OPENWOP_LIFECYCLE_TIMEOUT_MS
+ *
+ * Exit codes:
+ *   0   all scenarios pass
+ *   1   one or more scenarios failed
+ *   2   suite couldn't start (missing required args, etc)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve as resolvePath } from 'node:path';
+
+interface ParsedArgs {
+  readonly baseUrl: string | undefined;
+  readonly apiKey: string | undefined;
+  readonly offline: boolean;
+  readonly filter: string | undefined;
+  readonly help: boolean;
+  readonly impl: string | undefined;
+  readonly implVersion: string | undefined;
+}
+
+function parseArgs(argv: readonly string[]): ParsedArgs {
+  let baseUrl: string | undefined;
+  let apiKey: string | undefined;
+  let offline = false;
+  let filter: string | undefined;
+  let help = false;
+  let impl: string | undefined;
+  let implVersion: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] ?? '';
+    if (arg === '-h' || arg === '--help') {
+      help = true;
+      continue;
+    }
+    if (arg === '--offline') {
+      offline = true;
+      continue;
+    }
+    const eq = arg.indexOf('=');
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1);
+    const nextValue = (): string | undefined => {
+      if (inlineValue !== undefined) return inlineValue;
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        i++;
+        return next;
+      }
+      return undefined;
+    };
+
+    switch (flag) {
+      case '--base-url':
+        baseUrl = nextValue();
+        break;
+      case '--api-key':
+        apiKey = nextValue();
+        break;
+      case '--filter':
+        filter = nextValue();
+        break;
+      case '--impl':
+      case '--implementation-name':
+        impl = nextValue();
+        break;
+      case '--impl-version':
+      case '--implementation-version':
+        implVersion = nextValue();
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          // Unknown flag — pass through to vitest by ignoring here.
+        }
+    }
+  }
+
+  return { baseUrl, apiKey, offline, filter, help, impl, implVersion };
+}
+
+const HELP_TEXT = `openwop-conformance — run the openwop conformance suite against a server
+
+Usage:
+  openwop-conformance [options]
+
+Required (unless --offline):
+  --base-url <url>      openwop server base URL (or set OPENWOP_BASE_URL env var)
+  --api-key <key>       Bearer-style API key (or set OPENWOP_API_KEY env var)
+
+Filtering:
+  --offline             Run only the server-free subset (fixtures + spec corpus)
+  --filter <pattern>    Pass through to vitest --testNamePattern
+
+Implementation labels (cosmetic — surface in failure messages):
+  --impl <name>             Implementation name        (env: OPENWOP_IMPLEMENTATION_NAME)
+  --impl-version <version>  Implementation version     (env: OPENWOP_IMPLEMENTATION_VERSION)
+
+Other:
+  --help, -h            Show this message
+
+Examples:
+  openwop-conformance --offline
+  openwop-conformance --base-url https://api.example.com --api-key hk_test_abc
+  openwop-conformance --filter "discovery|errors"
+`;
+
+function main(): never {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  }
+
+  // Env vars OVERRIDE flags only when the flag was unset (consistent
+  // with the rest of the harness — env wins on the absence of CLI input).
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (args.baseUrl) env.OPENWOP_BASE_URL = args.baseUrl;
+  if (args.apiKey) env.OPENWOP_API_KEY = args.apiKey;
+  if (args.impl) env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
+  if (args.implVersion) env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
+
+  if (!args.offline && (!env.OPENWOP_BASE_URL || !env.OPENWOP_API_KEY)) {
+    process.stderr.write(
+      'openwop-conformance: --base-url and --api-key are required (or use --offline).\n' +
+        'Run `openwop-conformance --help` for usage.\n',
+    );
+    process.exit(2);
+  }
+
+  // Resolve the conformance directory relative to this script's location
+  // so the CLI works regardless of the caller's cwd. Both the source
+  // path (`src/cli.ts`) and the compiled path (`dist/cli.js`) live ONE
+  // directory below the package root, so the same `..` works either way.
+  const here = dirname(fileURLToPath(import.meta.url));
+  const conformanceRoot = resolvePath(here, '..');
+
+  // Build vitest argv. server-free subset is `fixtures-valid` +
+  // `spec-corpus-validity`; the offline flag scopes the run to those.
+  // Pass --config explicitly so vitest doesn't auto-discover an
+  // ancestor config (e.g., a parent monorepo's vite.config.ts) when
+  // the conformance package is used as a workspace member.
+  const vitestArgs: string[] = ['run', '--config', resolvePath(conformanceRoot, 'vitest.config.ts')];
+  if (args.offline) {
+    vitestArgs.push(
+      'src/scenarios/fixtures-valid.test.ts',
+      'src/scenarios/spec-corpus-validity.test.ts',
+    );
+  }
+  if (args.filter) {
+    vitestArgs.push('--testNamePattern', args.filter);
+  }
+
+  const result = spawnSync('npx', ['vitest', ...vitestArgs], {
+    cwd: conformanceRoot,
+    env,
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    process.stderr.write(`openwop-conformance: failed to spawn vitest: ${String(result.error)}\n`);
+    process.exit(2);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+main();