@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/certification-bundle.schema.json

@@ -0,0 +1,401 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/certification-bundle.schema.json",
+  "title": "Certification bundle v3 (RFC 0168 §E)",
+  "description": "Closed root. witnessSha256 covers the reporter record (RFC 0148 §C); signature is an Ed25519 attestation over the canonical JSON of {witnessSha256, host.build, suite.version, discovery.sha256}; evidenceTier independent requires a verifier keyId distinct from the host's. A bundle with blocked > 0 does not certify; a relaxed obligation cannot certify its profile (RFC 0173 §A.2).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "bundleVersion",
+    "generatedAt",
+    "suite",
+    "host",
+    "discovery",
+    "claimedProfiles",
+    "results",
+    "witnessSha256",
+    "assertionCount",
+    "signature"
+  ],
+  "properties": {
+    "bundleVersion": {
+      "const": "3"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "suite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "version",
+        "targetMajor",
+        "specArtifactsVersion"
+      ],
+      "properties": {
+        "name": {
+          "const": "@openwop/openwop-conformance"
+        },
+        "version": {
+          "type": "string"
+        },
+        "targetMajor": {
+          "type": "integer",
+          "enum": [
+            1,
+            2
+          ]
+        },
+        "specArtifactsVersion": {
+          "type": "string"
+        },
+        "stampSha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "version",
+        "build"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "id"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "image-digest",
+                "commit",
+                "artifact-sha256"
+              ]
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "signingKeyId": {
+          "$ref": "ids.schema.json#/$defs/keyId"
+        },
+        "relaxations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "obligation",
+              "durability",
+              "reason"
+            ],
+            "properties": {
+              "obligation": {
+                "type": "string"
+              },
+              "durability": {
+                "type": "string",
+                "enum": [
+                  "session",
+                  "deployment",
+                  "persisted"
+                ],
+                "description": "RFC 0173 §A.2 — session (lost on restart), deployment (set at deploy time), persisted (survives restarts and is auditable)."
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "RFC 0173 §A.2 — operator relaxations; a relaxed obligation's profile cannot certify."
+        }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "url",
+        "sha256",
+        "protocolVersions",
+        "preferredVersion"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "protocolVersions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "preferredVersion": {
+          "type": "string"
+        }
+      }
+    },
+    "claimedProfiles": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "evidenceTier",
+          "witnessCount",
+          "certified"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^openwop-[a-z0-9-]+$"
+          },
+          "evidenceTier": {
+            "type": "string",
+            "enum": [
+              "self",
+              "steward",
+              "independent"
+            ]
+          },
+          "witnessCount": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "certified": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "results": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "totals",
+        "requirements"
+      ],
+      "properties": {
+        "totals": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "executedPass",
+            "executedFail",
+            "skipped",
+            "inapplicable",
+            "blocked"
+          ],
+          "properties": {
+            "executedPass": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "executedFail": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "skipped": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "inapplicable": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "blocked": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "requirements": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "scenario",
+              "result"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^openwop\\.requirement\\."
+              },
+              "scenario": {
+                "type": "string"
+              },
+              "result": {
+                "type": "string",
+                "enum": [
+                  "executed-pass",
+                  "executed-fail",
+                  "skipped",
+                  "inapplicable",
+                  "blocked"
+                ]
+              },
+              "assertions": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "detail": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "witnessSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "assertionCount": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "detail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "nonPass"
+      ],
+      "properties": {
+        "nonPass": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "result",
+              "reason"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "result": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "description": "Required when any result is not executed-pass (allOf below)."
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "alg",
+        "keyId",
+        "sig",
+        "over"
+      ],
+      "properties": {
+        "alg": {
+          "const": "ed25519"
+        },
+        "keyId": {
+          "$ref": "ids.schema.json#/$defs/keyId"
+        },
+        "sig": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{86}$"
+        },
+        "over": {
+          "type": "array",
+          "const": [
+            "witnessSha256",
+            "host.build",
+            "suite.version",
+            "discovery.sha256"
+          ]
+        },
+        "verifierKeyId": {
+          "$ref": "ids.schema.json#/$defs/keyId"
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "results": {
+            "properties": {
+              "totals": {
+                "anyOf": [
+                  {
+                    "properties": {
+                      "executedFail": {
+                        "minimum": 1
+                      }
+                    }
+                  },
+                  {
+                    "properties": {
+                      "skipped": {
+                        "minimum": 1
+                      }
+                    }
+                  },
+                  {
+                    "properties": {
+                      "blocked": {
+                        "minimum": 1
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "detail"
+        ]
+      }
+    }
+  ]
+}

package/schemas/v2/channel-presence-payload.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/channel-presence-payload.schema.json",
+  "title": "ChannelPresencePayload",
+  "description": "Payload of the OPTIONAL `channel.presence` RunEvent (RFC 0110). EPHEMERAL live presence for a `type:'channel'` conversation — who is currently present + (optionally) who is typing. A host MUST NOT persist this event to the replayable event log / transcript, and it MUST NOT affect replay or `:fork` determinism (presence is live state, the load-bearing distinction from the persisted `conversation.exchanged` turn — see replay.md). Membership-gated: every ref MUST be a current channel participant and the event MUST NOT be delivered to a non-member (the same DEFAULT-DENY visibility as the channel's messages; cross-tenant delivery is forbidden, CTI-1). NON-PII: subject refs are the opaque RFC 0041 vocabulary only — no IP/location/device. A host MAY emit; if it advertises `channelPresence.supported` it MUST. Gated on `channelPresence.supported` (capabilities.schema.json). See RFC 0110.",
+  "type": "object",
+  "required": [
+    "conversationId",
+    "present"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "conversationId": {
+      "type": "string",
+      "description": "The `type:'channel'` conversation this presence is for.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "present": {
+      "type": "array",
+      "description": "Subject refs (RFC 0041 vocabulary `user:<id>` / `agent:<id>` — opaque, non-PII) of members CURRENTLY present in the channel. MUST be a subset of the channel's current participants; a non-member MUST NOT appear.",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      }
+    },
+    "typing": {
+      "type": "array",
+      "description": "OPTIONAL subset of `present` that is currently typing. Boolean-by-presence: a ref appears iff that member is typing. No payload beyond the subject refs (no free text, no PII).",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      }
+    }
+  },
+  "examples": [
+    {
+      "$comment": "RFC 0110 POSITIVE — two members present in a channel, one typing.",
+      "conversationId": "chan-eng",
+      "present": [
+        "user:alice",
+        "agent:iris"
+      ],
+      "typing": [
+        "user:alice"
+      ]
+    },
+    {
+      "$comment": "RFC 0110 POSITIVE — typing is OPTIONAL; a presence snapshot with no one typing.",
+      "conversationId": "chan-eng",
+      "present": [
+        "user:alice"
+      ]
+    }
+  ],
+  "$comment": "RFC 0110 NEGATIVE (not validatable as an examples[] entry, which must be VALID): a payload carrying any field beyond conversationId/present/typing (e.g. `ip`, `location`) MUST FAIL validation via `additionalProperties: false` — the no-PII guard; see conformance/src/scenarios/channel-presence-shape.test.ts.",
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/channel-written-payload.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/channel-written-payload.schema.json",
+  "title": "ChannelWrittenPayload",
+  "description": "Payload of the `channel.written` RunEvent. Carries the WRITE INPUT (pre-reduction), NOT the post-reduction channel state. Replay reconstructs the post-reduction state by folding all `channel.written` events through the declared reducer. See channels-and-reducers.md §Channel write event.",
+  "type": "object",
+  "required": [
+    "channel",
+    "value",
+    "reducer",
+    "writtenAt"
+  ],
+  "properties": {
+    "channel": {
+      "type": "string",
+      "description": "Channel name. MUST match a key declared under `WorkflowDefinition.channels`.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "value": {
+      "description": "The write payload (any JSON value). Validated against `ChannelDeclaration.schema` if declared. The semantic shape depends on the channel's reducer — see per-reducer §Examples below.",
+      "type": [
+        "object",
+        "array",
+        "string",
+        "number",
+        "boolean",
+        "null"
+      ]
+    },
+    "reducer": {
+      "type": "string",
+      "description": "The reducer name in effect at write time. Persisted on the event so replays remain deterministic even if the channel's reducer is later renamed/swapped. Canonical names: `replace`, `append`, `merge`, `counter`, `votes`, `feedback`. Custom reducers MUST use `vendor.<org>.<name>`.",
+      "pattern": "^(replace|append|merge|counter|votes|feedback|vendor\\.[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_-]*)$"
+    },
+    "nodeId": {
+      "$ref": "ids.schema.json#/$defs/nodeId",
+      "description": "Optional — node that performed the write. Set for writes from `ctx.channels.write(...)`; absent for system-initiated writes."
+    },
+    "writtenAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp. The engine MAY normalize between this canonical form and platform-specific representations (e.g., Firestore Timestamp)."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The `ChannelDeclaration.schemaVersion` that was live at write time. Persisted on the event so replays + later folds can detect breaking schema changes — the engine validates each event's value against the channel's CURRENT schema and refuses with `channel_schema_breaking_change` when the event's version is older than `current` AND not in `compatibleWith`. Defaults to 1 when omitted (back-compat with pre-C4 servers that didn't track versions). See channels-and-reducers.md §Channel schema migration. (closes C4)"
+    },
+    "sourceEngineId": {
+      "type": "string",
+      "description": "Identifier of the engine instance that performed the write. Set when the writing engine differs from the engine that owns the parent run (e.g., a sub-workflow / cross-canvas-invoke writing to a parent's channel). Absent when the parent's own engine wrote. The fold side uses this to disambiguate origins for `channel-write` trigger filtering (`onlyFrom: 'child'` matches when this field is set and references a known child engine). See channels-and-reducers.md §Distributed reducers. (closes C2)",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "sourceRunId": {
+      "$ref": "ids.schema.json#/$defs/runId",
+      "description": "RunId of the cross-engine writer when `sourceEngineId` is set. Absent for owner-engine writes. Lets debugging surfaces (Run Timeline View per replay.md) link the write back to the originating sub-workflow / invoke run. (closes C2)"
+    }
+  },
+  "additionalProperties": false,
+  "$comment": "Per-reducer expectations on the `value` field (informative — not enforced at this schema level; servers SHOULD validate against `ChannelDeclaration.schema` if declared):\n\n  - `replace`: any value; supersedes prior state.\n  - `append`:  any value; appended to the channel's array. Bounded by `ChannelDeclaration.maxSize` if set.\n  - `merge`:   MUST be a JSON object (`{...}`); shallow-merged into prior state.\n  - `counter`: MUST be a number; added to the running total. Negative allowed.\n  - `votes`:   typically `{voter: string, vote: string|boolean|number, ...}`; the reducer accumulates per-voter latest-wins.\n  - `feedback`: typically `{author: string, text: string, timestamp: string, ...}`; the reducer appends bounded by `maxSize`.\n  - `vendor.*`: implementation-defined; external clients SHOULD treat as `replace` if the reducer name is unknown.",
+  "x-openwop-seeded-from": "v1"
+}