docs consolidation work

2025-12-25 10:53:53 +02:00
parent b9f71fc7e9
commit deb82b4f03
117 changed files with 852 additions and 847 deletions
--- a/docs/modules/notify/schemas/README.md
+++ b/docs/modules/notify/schemas/README.md
@@ -0,0 +1,3 @@
+# Notify Schemas Catalog
+
+Placeholder for NR1 deliverables: versioned JSON Schemas for Notify event envelopes, rules, templates, channels, receipts, and webhooks. Publish `notify-schemas-catalog.json` + `.dsse.json` here with canonicalization recipe (BLAKE3-256 over normalized JSON) and `inputs.lock` capturing digests.
--- a/docs/modules/notify/schemas/channel.schema.json
+++ b/docs/modules/notify/schemas/channel.schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/channel.schema.json",
+  "title": "Notify Channel Configuration",
+  "type": "object",
+  "required": ["schema_version", "tenant_id", "channel_id", "kind", "config"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "channel_id": { "type": "string", "pattern": "^[A-Z0-9_-]{4,64}$" },
+    "kind": { "type": "string", "enum": ["email", "slack", "teams", "webhook", "sms"] },
+    "config": { "type": "object" },
+    "secrets_ref": { "type": "object", "additionalProperties": { "type": "string" } },
+    "rate_limit": { "type": "object" },
+    "enabled": { "type": "boolean", "default": true },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/dlq-notify.schema.json
+++ b/docs/modules/notify/schemas/dlq-notify.schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/dlq-notify.schema.json",
+  "title": "Notify Dead Letter Entry",
+  "type": "object",
+  "required": ["schema_version", "tenant_id", "delivery_id", "reason", "payload", "first_failed_at"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "delivery_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{18,36}$" },
+    "reason": { "type": "string" },
+    "payload": { "type": "object" },
+    "backoff_attempts": { "type": "integer", "minimum": 0 },
+    "dedupe_key": { "type": "string" },
+    "first_failed_at": { "type": "string", "format": "date-time" },
+    "last_failed_at": { "type": "string", "format": "date-time" },
+    "redrive_after": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/event-envelope.schema.json
+++ b/docs/modules/notify/schemas/event-envelope.schema.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/event-envelope.schema.json",
+  "title": "Notify Event Envelope",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "tenant_id",
+    "event_id",
+    "occurred_at",
+    "kind",
+    "payload"
+  ],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "event_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{18,36}$" },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "kind": { "type": "string", "minLength": 1 },
+    "correlation_id": { "type": "string" },
+    "source": { "type": "string" },
+    "payload": { "type": "object" },
+    "attributes": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean", "null"] } }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/inputs.lock
+++ b/docs/modules/notify/schemas/inputs.lock
@@ -0,0 +1,14 @@
+{
+  "catalog": "notify-schemas-catalog.json",
+  "hash_algorithm": "blake3-256",
+  "canonicalization": "json-normalized-utf8",
+  "entries": [
+    { "file": "event-envelope.schema.json", "digest": "0534e778a7e24dfdcbdc66cec2902f24684ec0bdf26d708ab9bca98e6674a318" },
+    { "file": "rule.schema.json", "digest": "34d4f1c2ba97b76acf85ad61f4e8de4591664eefecbc7ebb6d168aa5a998ddd1" },
+    { "file": "template.schema.json", "digest": "e0a8f9bb5e5f29a11b040e7cb0e7e9a8c5d42256f9a4bd72f79460eb613dac52" },
+    { "file": "channel.schema.json", "digest": "bd9e2dfb4e6e7e7a38f26cc94ae8bcdf9b8c44b1e97bf78c146711783fe8fa2b" },
+    { "file": "receipt.schema.json", "digest": "fb4431019b3803081983b215fc9ca2e7618c3cf91f8274baedf72cacad8dfe46" },
+    { "file": "webhook.schema.json", "digest": "54a6e0d956fd6af7e88f6508bda78221ca04cfedea4112bfefc7fa5dbfa45c09" },
+    { "file": "dlq-notify.schema.json", "digest": "1330e589245b923f6e1fea6af080b7b302a97effa360a90dbef4ba3b06021b2f" }
+  ]
+}
--- a/docs/modules/notify/schemas/notify-schemas-catalog.dsse.json
+++ b/docs/modules/notify/schemas/notify-schemas-catalog.dsse.json
@@ -0,0 +1,11 @@
+{
+  "payloadType": "application/vnd.notify.schema-catalog+json",
+  "payload": "eyJjYW5vbmljYWxpemF0aW9uIjoianNvbi1ub3JtYWxpemVkLXV0ZjgiLCJjYXRhbG9nX3ZlcnNpb24iOiJ2MS4wIiwiZ2VuZXJhdGVkX2F0IjoiMjAyNS0xMi0wNFQwMDowMDowMFoiLCJoYXNoX2FsZ29yaXRobSI6ImJsYWtlMy0yNTYiLCJzY2hlbWFzIjpbeyJkaWdlc3QiOiIwNTM0ZTc3OGE3ZTI0ZGZkY2JkYzY2Y2VjMjkwMmYyNDY4NGVjMGJkZjI2ZDcwOGFiOWJjYTk4ZTY2NzRhMzE4IiwiZmlsZSI6ImV2ZW50LWVudmVsb3BlLnNjaGVtYS5qc29uIiwiaWQiOiJldmVudC1lbnZlbG9wZSIsInZlcnNpb24iOiJ2MS4wIn0seyJkaWdlc3QiOiIzNGQ0ZjFjMmJhOTdiNzZhY2Y4NWFkNjFmNGU4ZGU0NTkxNjY0ZWVmZWNiYzdlYmI2ZDE2OGFhNWE5OThkZGQxIiwiZmlsZSI6InJ1bGUuc2NoZW1hLmpzb24iLCJpZCI6InJ1bGUiLCJ2ZXJzaW9uIjoidjEuMCJ9LHsiZGlnZXN0IjoiZTBhOGY5YmI1ZTVmMjlhMTFiMDQwZTdjYjBlN2U5YThjNWQ0MjI1NmY5YTRiZDcyZjc5NDYwZWI2MTNkYWM1MiIsImZpbGUiOiJ0ZW1wbGF0ZS5zY2hlbWEuanNvbiIsImlkIjoidGVtcGxhdGUiLCJ2ZXJzaW9uIjoidjEuMCJ9LHsiZGlnZXN0IjoiYmQ5ZTJkZmI0ZTZlN2U3YTM4ZjI2Y2M5NGFlOGJjZGY5YjhjNDRiMWU5N2JmNzhjMTQ2NzExNzgzZmU4ZmEyYiIsImZpbGUiOiJjaGFubmVsLnNjaGVtYS5qc29uIiwiaWQiOiJjaGFubmVsIiwidmVyc2lvbiI6InYxLjAifSx7ImRpZ2VzdCI6ImZiNDQzMTAxOWIzODAzMDgxOTgzYjIxNWZjOWNhMmU3NjE4YzNjZjkxZjgyNzRiYWVkZjcyY2FjYWQ4ZGZlNDYiLCJmaWxlIjoicmVjZWlwdC5zY2hlbWEuanNvbiIsImlkIjoicmVjZWlwdCIsInZlcnNpb24iOiJ2MS4wIn0seyJkaWdlc3QiOiI1NGE2ZTBkOTU2ZmQ2YWY3ZTg4ZjY1MDhiZGE3ODIyMWNhMDRjZmVkZWE0MTEyYmZlZmM3ZmE1ZGJmYTQ1YzA5IiwiZmlsZSI6IndlYmhvb2suc2NoZW1hLmpzb24iLCJpZCI6IndlYmhvb2siLCJ2ZXJzaW9uIjoidjEuMCJ9LHsiZGlnZXN0IjoiMTMzMGU1ODkyNDViOTIzZjZlMWZlYTZhZjA4MGI3YjMwMmE5N2VmZmEzNjBhOTBkYmVmNGJhM2IwNjAyMWIyZiIsImZpbGUiOiJkbHEtbm90aWZ5LnNjaGVtYS5qc29uIiwiaWQiOiJkbHEiLCJ2ZXJzaW9uIjoidjEuMCJ9XX0=",
+  "signatures": [
+    {
+      "sig": "99WPzzc6sCaEQHXk2B15aLxtG/Ics6qsgHYa2oDTI1g=",
+      "keyid": "notify-dev-hmac-001",
+      "signedAt": "2025-12-04T21:12:53+00:00"
+    }
+  ]
+}
--- a/docs/modules/notify/schemas/notify-schemas-catalog.json
+++ b/docs/modules/notify/schemas/notify-schemas-catalog.json
@@ -0,0 +1,15 @@
+{
+  "catalog_version": "v1.0",
+  "hash_algorithm": "blake3-256",
+  "canonicalization": "json-normalized-utf8",
+  "generated_at": "2025-12-04T00:00:00Z",
+  "schemas": [
+    { "id": "event-envelope", "file": "event-envelope.schema.json", "version": "v1.0", "digest": "0534e778a7e24dfdcbdc66cec2902f24684ec0bdf26d708ab9bca98e6674a318" },
+    { "id": "rule", "file": "rule.schema.json", "version": "v1.0", "digest": "34d4f1c2ba97b76acf85ad61f4e8de4591664eefecbc7ebb6d168aa5a998ddd1" },
+    { "id": "template", "file": "template.schema.json", "version": "v1.0", "digest": "e0a8f9bb5e5f29a11b040e7cb0e7e9a8c5d42256f9a4bd72f79460eb613dac52" },
+    { "id": "channel", "file": "channel.schema.json", "version": "v1.0", "digest": "bd9e2dfb4e6e7e7a38f26cc94ae8bcdf9b8c44b1e97bf78c146711783fe8fa2b" },
+    { "id": "receipt", "file": "receipt.schema.json", "version": "v1.0", "digest": "fb4431019b3803081983b215fc9ca2e7618c3cf91f8274baedf72cacad8dfe46" },
+    { "id": "webhook", "file": "webhook.schema.json", "version": "v1.0", "digest": "54a6e0d956fd6af7e88f6508bda78221ca04cfedea4112bfefc7fa5dbfa45c09" },
+    { "id": "dlq", "file": "dlq-notify.schema.json", "version": "v1.0", "digest": "1330e589245b923f6e1fea6af080b7b302a97effa360a90dbef4ba3b06021b2f" }
+  ]
+}
--- a/docs/modules/notify/schemas/receipt.schema.json
+++ b/docs/modules/notify/schemas/receipt.schema.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/receipt.schema.json",
+  "title": "Notify Delivery Receipt",
+  "type": "object",
+  "required": ["schema_version", "tenant_id", "delivery_id", "rule_id", "channel", "status", "sent_at"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "delivery_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{18,36}$" },
+    "rule_id": { "type": "string" },
+    "channel": { "type": "string" },
+    "status": { "type": "string", "enum": ["sent", "delivered", "failed", "queued", "acknowledged"] },
+    "attempt": { "type": "integer", "minimum": 1 },
+    "sent_at": { "type": "string", "format": "date-time" },
+    "ack_url": { "type": "string", "format": "uri" },
+    "response": { "type": "object" },
+    "errors": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/rule.schema.json
+++ b/docs/modules/notify/schemas/rule.schema.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/rule.schema.json",
+  "title": "Notify Rule",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "tenant_id",
+    "rule_id",
+    "name",
+    "sources",
+    "predicates",
+    "actions",
+    "approvals_required"
+  ],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "rule_id": { "type": "string", "pattern": "^[A-Z0-9_-]{4,64}$" },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "severity": { "type": "string", "enum": ["info", "low", "medium", "high", "critical"] },
+    "sources": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "predicates": { "type": "array", "items": { "type": "object" }, "minItems": 1 },
+    "actions": {
+      "type": "array",
+      "items": { "type": "object" },
+      "minItems": 1
+    },
+    "approvals_required": { "type": "integer", "minimum": 0, "maximum": 3 },
+    "quiet_hours": { "type": "array", "items": { "type": "string" } },
+    "simulation_required": { "type": "boolean", "default": true },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/template.schema.json
+++ b/docs/modules/notify/schemas/template.schema.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/template.schema.json",
+  "title": "Notify Template",
+  "type": "object",
+  "required": ["schema_version", "tenant_id", "template_id", "channel", "locale", "body"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "template_id": { "type": "string", "pattern": "^[A-Z0-9_-]{4,64}$" },
+    "channel": { "type": "string", "enum": ["email", "slack", "teams", "webhook", "sms"] },
+    "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+    "subject": { "type": "string" },
+    "body": { "type": "string" },
+    "helpers": { "type": "object", "additionalProperties": { "type": "string" } },
+    "merge_fields": { "type": "array", "items": { "type": "string" } },
+    "preview_hash": { "type": "string" },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
--- a/docs/modules/notify/schemas/webhook.schema.json
+++ b/docs/modules/notify/schemas/webhook.schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella-ops.org/notify/schemas/webhook.schema.json",
+  "title": "Notify Webhook Payload",
+  "type": "object",
+  "required": ["schema_version", "tenant_id", "delivery_id", "signature", "body"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+$" },
+    "tenant_id": { "type": "string", "minLength": 1 },
+    "delivery_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{18,36}$" },
+    "signature": { "type": "string" },
+    "hmac_id": { "type": "string" },
+    "body": { "type": "object" },
+    "sent_at": { "type": "string", "format": "date-time" },
+    "nonce": { "type": "string" },
+    "audience": { "type": "string" },
+    "expires_at": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}