@openwop/openwop-conformance 1.2.0 → 1.4.0

package/schemas/prompt-pack-manifest.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-pack-manifest.schema.json",
+  "title": "PromptPackManifest",
+  "description": "Manifest for a published OpenWOP prompt pack — `pack.json` at the pack root with `kind: \"prompt\"`. Peer to `node-pack-manifest.schema.json` (RFC 0003) and `workflow-chain-pack-manifest.schema.json` (RFC 0013); disjoint from both via the `kind` discriminator. See `spec/v1/prompts.md` §\"Discovery & distribution\" for the canonical contract and RFC 0028 §B for the rationale.\n\nPrompt packs distribute curated PromptTemplate collections via the same signed-tarball + Ed25519 + SRI pipeline that already serves node and workflow-chain packs. When a host installs a prompt pack and advertises `capabilities.prompts.packsSupported: true`, the templates appear in `GET /v1/prompts` with `meta.source: \"pack\"` + `meta.packName` + `meta.packVersion`.",
+  "type": "object",
+  "required": ["name", "version", "kind", "engines", "prompts"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Reverse-DNS pack name per `node-packs.md` §Naming. Reserved scopes are identical (`core.*` / `vendor.<org>.*` / `community.<author>.*` / `private.<host>.*`). Mirror of `workflow-chain-pack-manifest.schema.json#/properties/name`.",
+      "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "version": {
+      "type": "string",
+      "description": "Pack-level SemVer 2.0.0.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "prompt",
+      "description": "Pack kind discriminator. MUST be the literal string `\"prompt\"` for this schema. Manifests carrying `kind: \"node\"` validate against `node-pack-manifest.schema.json`; `kind: \"workflow-chain\"` against `workflow-chain-pack-manifest.schema.json`."
+    },
+    "description": { "type": "string", "maxLength": 1024 },
+    "author": { "type": "string" },
+    "license": { "type": "string", "description": "SPDX license identifier (e.g., `Apache-2.0`)." },
+    "homepage": { "type": "string", "format": "uri" },
+    "repository": { "type": "string", "format": "uri" },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 64 },
+      "maxItems": 50
+    },
+    "engines": {
+      "type": "object",
+      "required": ["openwop"],
+      "properties": {
+        "openwop": {
+          "type": "string",
+          "description": "SemVer range — which openwop protocol versions this pack works against (e.g., `>=1.1.0 <2.0.0`)."
+        }
+      },
+      "additionalProperties": true,
+      "$comment": "Open by design — packs MAY advertise extra engine constraints (`node`, `python`, etc.) that consumer hosts ignore but operator tooling consumes. Mirrors workflow-chain-pack-manifest."
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Other packs whose templates this pack's templates reference (e.g., via cross-pack `PromptRef.libraryId` lookups, or via a future `extends:` inheritance syntax). Map of pack name → SemVer range. Install-time validation MUST resolve every entry before accepting the install; an unresolvable entry rejects with `prompt_pack_dependency_unresolvable`. The *semantics* of cross-pack composition (template inheritance, transitive `dependencies` closure) are out of scope for RFC 0028 and defer to a follow-up RFC; this RFC ships the field + the install-time resolve MUST only. Shape mirrors `workflow-chain-pack-manifest.schema.json#/properties/dependencies` (RFC 0013)."
+    },
+    "prompts": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "./prompt-template.schema.json" },
+      "description": "PromptTemplate entries per RFC 0027 §A. Each MUST have a unique `(templateId, version)` pair within the pack. Hosts installing this pack expose the templates at `GET /v1/prompts` with `meta.source: \"pack\"` + `meta.packName: <this pack's name>` + `meta.packVersion: <this pack's version>` populated automatically (RFC 0028 §C)."
+    },
+    "signing": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional signing metadata. Reuses the Ed25519 + SRI flow from `node-packs.md §Signing` unchanged. Hosts installing this pack MUST verify the signature before accepting any of `prompts[]` per `registry-operations.md §\"Signature verification\"`.",
+      "properties": {
+        "publicKeyRef": {
+          "type": "string",
+          "description": "Path inside the tarball to the Ed25519 public key (PEM-encoded)."
+        },
+        "signatureRef": {
+          "type": "string",
+          "description": "Path to the detached signature over `pack.json`."
+        },
+        "method": {
+          "type": "string",
+          "enum": ["manual", "sigstore"]
+        }
+      }
+    }
+  }
+}

package/schemas/prompt-ref.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-ref.schema.json",
+  "title": "PromptRef",
+  "description": "Reference to a PromptTemplate. Two equivalent forms are accepted: a compact stringy URI (`prompt:templateId[@version]`) and a structured object form. The stringy form is canonical for inline use in WorkflowNode.config and AgentManifest.promptOverrides; the object form is canonical when libraryId disambiguation, variable overrides, or pinned versions need to be expressed explicitly. See spec/v1/prompts.md §\"PromptRef\" for the canonical contract and RFC 0027 §B for the rationale.\n\nResolution semantics (host responsibility): the host looks up the referenced template in its library (host built-ins + installed packs + user templates, gated by capabilities.prompts.*). When no `version` is given, the latest version wins. When two installed packs ship the same templateId, the stringy form is rejected with `prompt_ref_ambiguous` and consumers MUST use the object form with `libraryId` to disambiguate (RFC 0028 §B \"Conflict resolution\").",
+  "oneOf": [
+    {
+      "type": "string",
+      "pattern": "^prompt:[a-z0-9][a-z0-9._-]{0,127}(@\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?)?$",
+      "description": "Compact stringy form: `prompt:<templateId>[@<version>]`. Examples: `prompt:writer`, `prompt:writer@1.2.0`, `prompt:vendor.acme.writer.v2@2.0.0`."
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["templateId"],
+      "description": "Structured object form. Use when `libraryId` disambiguation, per-reference variable overrides, or version pinning is needed.",
+      "properties": {
+        "libraryId": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+          "description": "Library scope. Per RFC 0028, the host's default library is identified by `capabilities.prompts.library.id`; pack-sourced templates resolve via the installed pack's `name`."
+        },
+        "templateId": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+          "description": "Same pattern as PromptTemplate.templateId."
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+          "description": "Pinned SemVer. When omitted, the host resolves the latest version available in the named library."
+        },
+        "variableOverrides": {
+          "type": "object",
+          "description": "Per-reference variable bindings, applied at composition time. Take precedence over node-input bindings (matching the four-layer resolution chain in RFC 0029 §A). Bindings are validated against PromptTemplate.variables before composition."
+        }
+      }
+    }
+  ]
+}

package/schemas/prompt-template.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-template.schema.json",
+  "title": "PromptTemplate",
+  "description": "Canonical wire shape for a named, versioned, variable-bound prompt body referenced by workflow nodes and agent manifests. See spec/v1/prompts.md §\"PromptTemplate\" for the canonical contract, RFC 0027 for the rationale, and prompt-ref.schema.json for the reference type that points at instances of this shape. Variable interpolation MUST use Mustache-compatible `{{varName}}` placeholders; unresolved required variables MUST cause the node to fail with `prompt_variable_unresolved`; unresolved optional variables render as the empty string per RFC 0027 §A.\n\nThe `text` field MAY contain `<UNTRUSTED>...</UNTRUSTED>` markers verbatim — hosts MUST preserve them through composition per SECURITY/threat-model-prompt-injection.md. Variables sourced from `secret` MUST be replaced with `[REDACTED:<secretId>]` markers in any observability output (e.g., `prompt.composed` events) per SECURITY/threat-model-secret-leakage.md §SR-1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["templateId", "version", "kind", "text"],
+  "properties": {
+    "templateId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+      "description": "Stable identifier. Convention: vendor-prefixed for portable templates (`vendor.acme.writer.v2`) or unprefixed for host-resident templates (`writer`). Same naming discipline as node-pack typeIds (host-extensions.md §\"Canonical-prefix table\")."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "Semantic Versioning 2.0.0. Bumping major implies a breaking variable-schema or text change; consumers MUST pin to a specific version via PromptRef.version if they care about exact bodies."
+    },
+    "kind": {
+      "$ref": "./prompt-kind.schema.json",
+      "description": "Role this template plays when composed into an LLM call. A node MAY reference one template of each kind. Relative $ref resolves to the shared enum file for redocly's local-file walker; Ajv resolves it equivalently via the schema registry."
+    },
+    "text": {
+      "type": "string",
+      "maxLength": 65536,
+      "description": "Template body. Mustache-compatible `{{varName}}` placeholders are substituted at compose time using bindings from PromptVariable.source + variableOverrides. Hosts MAY cap below 65536 via capabilities.prompts.maxTemplateBytes, but MUST NOT exceed it."
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 200,
+      "description": "Human-readable display name surfaced in authoring UIs and template pickers."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "One-paragraph description of what the template is for. Surfaced in authoring UI hover-text and library-list cards."
+    },
+    "variables": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PromptVariable" },
+      "description": "Typed interpolation slots. Hosts MUST validate runtime bindings against this array before composing. A `{{varName}}` placeholder that has no matching entry in `variables[]` MAY appear (treated as an optional variable with source `input` and no default) — hosts SHOULD warn at install time."
+    },
+    "modelHints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Non-normative authoring hints. Hosts MAY surface these in editor UI (default temperature, suggested model class). They do NOT override per-node config or per-run RunOptions.configurable values.",
+      "properties": {
+        "modelClass": {
+          "type": "string",
+          "description": "Per AgentRef.modelClass enum + vendor extensions (e.g., `reasoning`, `writing`, `vendor.openwop.creative-writing`)."
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Suggested sampling temperature."
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Suggested max-tokens ceiling."
+        },
+        "envelopeType": {
+          "type": "string",
+          "description": "Suggested AI Envelope kind to use with this template, per RFC 0021. Opaque string in v1.x; future RFC MAY cross-validate against capabilities.supportedEnvelopes."
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 64 },
+      "maxItems": 32,
+      "description": "Free-form classification labels. Used by authoring UIs to group templates; not normative."
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Provenance + lifecycle metadata. Optional; hosts SHOULD populate it for any persistent storage. When `source: \"pack\"`, the host MUST populate `packName` + `packVersion` so clients can disambiguate templates that share a `templateId` across multiple installed packs (per RFC 0028 §B \"Conflict resolution\").",
+      "properties": {
+        "author": { "type": "string", "description": "Free-form author identifier (handle, email, etc.)." },
+        "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of initial creation." },
+        "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of most recent update." },
+        "source": {
+          "type": "string",
+          "enum": ["host", "pack", "user"],
+          "description": "Provenance discriminator. `host`: ships with the host's built-in library; immutable. `pack`: installed via RFC 0028 prompt pack; immutable; MUST carry `packName` + `packVersion`. `user`: created at run time via mutating endpoints; mutable iff `capabilities.prompts.mutableLibrary: true`."
+        },
+        "packName": {
+          "type": "string",
+          "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+          "description": "RFC 0028 §C. When `source: \"pack\"`, the installed pack's `name` (matches `PromptPackManifest.name`). Required when `source: \"pack\"`; absent otherwise. Lets clients pass a structured `PromptRef` with `libraryId` set to this value to disambiguate templates that share a `templateId` across packs."
+        },
+        "packVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+          "description": "RFC 0028 §C. When `source: \"pack\"`, the installed pack's `version`. Required when `source: \"pack\"`; absent otherwise."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "source": { "const": "pack" } }, "required": ["source"] },
+          "then": { "required": ["source", "packName", "packVersion"] }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "PromptVariable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "required"],
+      "description": "Typed interpolation slot. Bindings are validated against this declaration before composition; unresolved required slots MUST fail the node with `prompt_variable_unresolved`. Variables sourced from `secret` MUST be redacted to `[REDACTED:<secretId>]` markers in observability output per SECURITY/threat-model-secret-leakage.md §SR-1.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,63}$",
+          "description": "Variable identifier. MUST match the `{{name}}` placeholder pattern in `text`. Pattern aligns with common templating engines (Mustache, Handlebars, Liquid) — no dashes, no dotted paths."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "array", "object"],
+          "description": "JSON-Schema-style type hint. Hosts SHOULD validate the bound value's type against this declaration; type-mismatch MAY warn or fail per host policy (no normative MUST yet — see RFC 0027 §A)."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "When true, an absent binding fails the node with `prompt_variable_unresolved`. When false, the variable renders as `defaultValue` (if present) or the empty string."
+        },
+        "source": {
+          "type": "string",
+          "enum": ["input", "variable", "secret", "context"],
+          "description": "Where the binding comes from. `input`: node input port. `variable`: run-scoped variable (`ctx.variables.get`). `secret`: BYOK secret reference — MUST be redacted in observability events per RFC 0027 §E. `context`: host-provided implicit context (current user id, run id, etc.). Default when omitted: `input`."
+        },
+        "extractPath": {
+          "type": "string",
+          "description": "JSONPath into the source. When omitted, the entire source value binds to `name`. Hosts that don't support JSONPath MAY treat this as opaque dotted-path and surface an `unsupported_extract_path` warning."
+        },
+        "defaultValue": {
+          "description": "Used when `required: false` and the source resolves to undefined. Any JSON-serializable value."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Human-readable explanation. Surfaced in authoring UIs."
+        }
+      }
+    }
+  }
+}

package/schemas/registry-version-manifest.schema.json

@@ -135,6 +135,11 @@
       "maxLength": 512,
       "description": "Optional one-line rationale shown by clients when an install of a deprecated version is attempted. Typically names the replacement version + migration link."
     },
+    "supersededBy": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "Optional pointer to the version (or `<name>@<version>`) that replaces this one. Per spec/v1/registry-operations.md, engine consumers in `open` / `verified` mode MUST surface this value in any deprecation warning when set."
+    },
     "advisoryUrl": {
       "type": "string",
       "format": "uri",

package/schemas/run-ancestry-response.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/run-ancestry-response.schema.json",
+  "title": "RunAncestryResponse",
+  "description": "RFC 0040 §C — response shape for `GET /v1/runs/{runId}/ancestry`. Returns the cross-host parent chain for a run. When the parent is on the same host, `parent.wellKnownUrl` is absent (existing single-host case). When the parent is on a different host, `parent.wellKnownUrl` MUST be set so a client can resolve the chain by walking the URLs. `parent: null` means the current run is a top-level run (not dispatched from another host). Hosts advertising `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true` MUST serve this shape on a 200 response.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["runId", "hostId", "parent"],
+  "properties": {
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The runId from the request path."
+    },
+    "hostId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The host's own `crossHostCausation.hostId` advertisement. Identifies which host this run belongs to."
+    },
+    "parent": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["runId", "hostId", "cause"],
+          "properties": {
+            "runId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The parent run's runId."
+            },
+            "hostId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The parent run's hostId. MAY equal the current host's hostId (same-host parent) or differ (cross-host parent)."
+            },
+            "wellKnownUrl": {
+              "type": "string",
+              "format": "uri",
+              "description": "When the parent is on a different host, the parent's `/.well-known/openwop` URL so a client can walk the chain. ABSENT when the parent is on the same host as this run (existing single-host case)."
+            },
+            "cause": {
+              "type": "string",
+              "enum": ["mcp-tool-call", "a2a-message", "core.subWorkflow", "core.dispatch"],
+              "description": "What composition mechanism the parent used to dispatch this run. `core.dispatch` + `core.subWorkflow` are same-host (existing primitives); `mcp-tool-call` + `a2a-message` are cross-host (RFC 0040)."
+            }
+          }
+        }
+      ],
+      "description": "The run's immediate parent — `null` for top-level runs (not dispatched from any other run); otherwise the parent's identifiers + composition mechanism."
+    }
+  }
+}