@skrr-ai/signals 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- First stable public release of the CloudEvents 1.0 Signal contracts and
+  generic publisher SDK.
+
+## 0.1.0-alpha.0
+
+- Initial CloudEvents 1.0 Signal contract, source contracts, receipt contracts,
+  and generic publisher SDK.

package/README.md

@@ -0,0 +1,41 @@
+# `@skrr-ai/signals`
+
+CloudEvents-native public contracts and a small, transport-only publisher for
+the OverSky Signal Plane.
+
+This package submits immutable facts to `POST /v1/signals`. It does **not**
+create a Commitment, select a Monitor, wake an Agent, or grant any execution
+authority. Those are server-owned control-plane decisions.
+
+```ts
+import { SignalPublisher } from '@skrr-ai/signals';
+
+const signals = new SignalPublisher({
+  endpoint: 'https://api.oversky.ai/v1/signals',
+  source: 'urn:oversky:signal-source:src_payments_production',
+  token: process.env.OVERSKY_SIGNAL_TOKEN!,
+});
+
+await signals.emit({
+  type: 'io.acme.payments.http-request-failed.v1',
+  subject: 'service/payments-api',
+  dataschema:
+    'https://schemas.acme.example/signals/http-request-failed/1.0.0.json',
+  data: {
+    'service.name': 'payments-api',
+    'deployment.environment.name': 'production',
+    'http.route': 'POST /payments',
+    'http.response.status_code': 500,
+    'error.type': 'db-connection-timeout',
+  },
+});
+```
+
+Use the versioned JSON Schema and AsyncAPI files under [`contracts/`](./contracts)
+to integrate non-JavaScript producers. The package serializes structured-mode
+CloudEvents (`application/cloudevents+json`) and keeps the CloudEvents `id`
+stable across retries.
+
+The Signal Source credential determines the tenant and allowed source. Never
+put workspace, Commitment, Agent, authorization, request bodies, cookies,
+access tokens, or arbitrary stack traces in an event payload.

package/contracts/README.md

@@ -0,0 +1,28 @@
+# Signal Plane public contracts
+
+These versioned artifacts are the public, partner-facing contract for the
+OverSky Signal Plane. They are shipped with `@skrr-ai/signals` so a producer
+can pin an exact version without scraping application documentation.
+
+- `signal-envelope.v1.schema.json` — CloudEvents 1.0 structured JSON envelope
+  accepted by `POST /v1/signals`.
+- `signal-type-definition.v1.schema.json` — source-owned type registry entry
+  and safe field classifications for the Monitor builder.
+- `public-signal-source.v1.schema.json` — safe source and credential result
+  shapes; it intentionally excludes credential secrets.
+- `signal-source-credential-grant.v1.schema.json` — one-time credential
+  creation/rotation result. Its secret is write-only and must never be stored
+  or logged by a client.
+- `signal-receipt.v1.schema.json` — the durable-acceptance response shape.
+- `asyncapi.v1.json` — AsyncAPI 2.6 description of the HTTP publish channel.
+
+Versioning policy:
+
+1. Every schema `$id` is immutable once released.
+2. Breaking data changes require a new major Signal `type` (`…v2`) and a new
+   schema URI.
+3. Compatible optional-field additions create a new immutable schema version;
+   active Monitors remain pinned to their approved compatibility range.
+4. A source credential, not any event payload field, determines tenancy and
+   source identity. These contracts never accept Monitor, Commitment, Agent,
+   workspace, or authorization selectors in Signal data.

package/contracts/asyncapi.v1.json

@@ -0,0 +1,80 @@
+{
+  "asyncapi": "2.6.0",
+  "info": {
+    "title": "OverSky Signal Plane API",
+    "version": "1.0.0",
+    "description": "Source-scoped CloudEvents ingestion. A successful receipt only proves durable acceptance; it does not directly invoke a Monitor, Commitment, or Agent."
+  },
+  "servers": {
+    "production": {
+      "url": "api.oversky.ai",
+      "protocol": "https",
+      "description": "OverSky public API"
+    }
+  },
+  "channels": {
+    "/v1/signals": {
+      "description": "Submit a single Signal as CloudEvents 1.0 structured JSON.",
+      "publish": {
+        "operationId": "publishSignal",
+        "summary": "Durably submit one source-scoped Signal",
+        "message": {
+          "$ref": "#/components/messages/Signal"
+        },
+        "bindings": {
+          "http": {
+            "type": "request",
+            "method": "POST"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "sourceBearer": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "OverSky Signal Source Token",
+        "description": "A source-scoped token. It binds tenant and source identity; it is not a user API key."
+      }
+    },
+    "messages": {
+      "Signal": {
+        "name": "Signal",
+        "title": "CloudEvents Signal v1",
+        "contentType": "application/cloudevents+json",
+        "payload": {
+          "$ref": "./signal-envelope.v1.schema.json"
+        },
+        "examples": [
+          {
+            "name": "httpRequestFailed",
+            "payload": {
+              "specversion": "1.0",
+              "id": "evt_01JABC",
+              "source": "urn:oversky:signal-source:src_payments_production",
+              "type": "io.acme.payments.http-request-failed.v1",
+              "subject": "service/payments-api",
+              "time": "2026-08-24T22:00:00Z",
+              "datacontenttype": "application/json",
+              "dataschema": "https://schemas.acme.example/signals/http-request-failed/1.0.0.json",
+              "data": {
+                "service.name": "payments-api",
+                "deployment.environment.name": "production",
+                "http.route": "POST /payments",
+                "http.response.status_code": 500,
+                "error.type": "db-connection-timeout"
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "security": [
+    {
+      "sourceBearer": []
+    }
+  ]
+}

package/contracts/public-signal-source.v1.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.oversky.dev/signals/public-signal-source/1.0.0.json",
+  "title": "OverSky Public Signal Source v1",
+  "description": "Safe Signal Source API response. Credential secrets are excluded and appear only in a separate one-time grant.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceId", "workspaceId", "label", "transport", "status", "cloudEventSource", "typeDefinitions", "credentialCount", "policy", "health", "createdAt", "updatedAt"],
+  "properties": {
+    "sourceId": { "type": "string", "minLength": 1 },
+    "workspaceId": { "type": "string", "minLength": 1 },
+    "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "transport": { "enum": ["sdk", "direct_api", "webhook", "oauth_connector", "otel", "pull_connector"] },
+    "status": { "enum": ["active", "paused", "disabled"] },
+    "cloudEventSource": { "type": "string", "format": "uri" },
+    "typeDefinitions": {
+      "type": "array",
+      "items": { "$ref": "signal-type-definition.v1.schema.json" }
+    },
+    "credentialCount": { "type": "integer", "minimum": 0, "maximum": 20 },
+    "policy": {
+      "type": "object",
+      "required": ["limits", "rateLimit", "redaction", "retention"],
+      "properties": {
+        "limits": { "type": "object", "required": ["maxEventBytes", "maxDataBytes", "maxDataDepth", "maxDataFields"], "properties": { "maxEventBytes": { "type": "integer", "minimum": 1 }, "maxDataBytes": { "type": "integer", "minimum": 1 }, "maxDataDepth": { "type": "integer", "minimum": 1 }, "maxDataFields": { "type": "integer", "minimum": 1 } } },
+        "rateLimit": { "type": "object", "required": ["maxPerMinute"], "properties": { "maxPerMinute": { "type": "integer", "minimum": 1 } } },
+        "redaction": { "type": "object", "required": ["additionalSensitiveKeys", "retainTracestate"], "properties": { "additionalSensitiveKeys": { "type": "array", "items": { "type": "string" } }, "retainTracestate": { "type": "boolean" } } },
+        "retention": { "type": "object", "required": ["normalizedSignalDays"], "properties": { "normalizedSignalDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "residency": { "type": "string", "maxLength": 80 } } }
+      }
+    },
+    "health": { "type": "object", "properties": { "lastAcceptedAt": { "type": "string", "format": "date-time" }, "lastRejectedAt": { "type": "string", "format": "date-time" }, "lastErrorCode": { "type": "string", "maxLength": 120 } } },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "publicCredential": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "credentialId", "sourceId", "kind", "status", "label", "algorithm", "notBefore", "createdAt"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "credentialId": { "type": "string", "minLength": 1 },
+        "sourceId": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["bearer_token", "webhook_hmac"] },
+        "status": { "enum": ["active", "revoked", "expired"] },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "algorithm": { "enum": ["bearer-token", "hmac-sha256"] },
+        "notBefore": { "type": "string", "format": "date-time" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "lastUsedAt": { "type": "string", "format": "date-time" },
+        "expiresAt": { "type": "string", "format": "date-time" },
+        "revokedAt": { "type": "string", "format": "date-time" },
+        "revokeReason": { "type": "string", "maxLength": 240 },
+        "lastRotatedAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/contracts/signal-envelope.v1.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.oversky.dev/signals/signal-envelope/1.0.0.json",
+  "title": "OverSky Signal Envelope v1",
+  "description": "CloudEvents 1.0 structured JSON Signal accepted by POST /v1/signals. The source credential determines tenant and source authorization.",
+  "type": "object",
+  "required": [
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "time",
+    "datacontenttype",
+    "dataschema",
+    "data"
+  ],
+  "properties": {
+    "specversion": {
+      "const": "1.0"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "Stable occurrence identity. Source plus id is the deduplication key."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "^\\S+$",
+      "description": "Canonical Signal Source URI. It must match the source-scoped credential."
+    },
+    "type": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9][a-z0-9-]*)+\\.v[1-9][0-9]*$",
+      "description": "Producer-owned reverse-DNS type that carries its major version."
+    },
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the observed fact occurred; receipt time is server-owned and separate."
+    },
+    "datacontenttype": {
+      "const": "application/json"
+    },
+    "dataschema": {
+      "type": "string",
+      "format": "uri",
+      "minLength": 1,
+      "description": "Immutable URI for the data schema version."
+    },
+    "data": {
+      "$ref": "#/$defs/jsonValue",
+      "description": "Bounded, structured fact data. Source policy and the registered data schema add stricter limits."
+    },
+    "traceparent": {
+      "type": "string",
+      "pattern": "^[\u0021-\u007E]+$",
+      "description": "W3C Trace Context correlation only; it is never an authorization value."
+    },
+    "tracestate": {
+      "type": "string",
+      "maxLength": 512
+    }
+  },
+  "not": {
+    "required": ["data_base64"]
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "jsonValue": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    }
+  }
+}

package/contracts/signal-receipt.v1.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.oversky.dev/signals/signal-receipt/1.0.0.json",
+  "title": "OverSky Signal Receipt v1",
+  "description": "A durable Signal acceptance response. Accepted or duplicate confirms receipt ownership, not that a Monitor or Agent has executed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "receiptId",
+    "sourceId",
+    "canonicalSource",
+    "eventId",
+    "outcome",
+    "processingStatus",
+    "receivedAt"
+  ],
+  "properties": {
+    "receiptId": { "type": "string", "minLength": 1 },
+    "sourceId": { "type": "string", "minLength": 1 },
+    "canonicalSource": { "type": "string", "minLength": 1 },
+    "eventId": { "type": "string", "minLength": 1 },
+    "outcome": { "enum": ["accepted", "duplicate"] },
+    "processingStatus": { "enum": ["pending", "processing", "completed"] },
+    "receivedAt": { "type": "string", "format": "date-time" },
+    "requestId": { "type": "string", "minLength": 1 }
+  }
+}

package/contracts/signal-source-credential-grant.v1.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.oversky.dev/signals/signal-source-credential-grant/1.0.0.json",
+  "title": "OverSky Signal Source Credential Grant v1",
+  "description": "One-time source credential creation/rotation response. The secret must not be retained in source read responses, logs, or analytics.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["credential", "secret", "secretKind", "shownOnce"],
+  "properties": {
+    "credential": {
+      "$ref": "public-signal-source.v1.schema.json#/$defs/publicCredential"
+    },
+    "secret": {
+      "type": "string",
+      "minLength": 1,
+      "writeOnly": true,
+      "description": "Display exactly once over an authenticated TLS response. Never include in a PublicSignalSource response."
+    },
+    "secretKind": {
+      "enum": ["bearer_token", "webhook_hmac"]
+    },
+    "shownOnce": {
+      "const": true
+    }
+  }
+}

package/contracts/signal-type-definition.v1.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.oversky.dev/signals/signal-type-definition/1.0.0.json",
+  "title": "OverSky Signal Type Definition v1",
+  "description": "A source-approved type, immutable data schema URI, and safe field catalogue. Field names are declared semantic names, never arbitrary JSONPath expressions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "type",
+    "dataschema",
+    "displayName",
+    "description",
+    "subjectKinds",
+    "fields",
+    "compatibility"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9][a-z0-9-]*)+\\.v[1-9][0-9]*$"
+    },
+    "dataschema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000
+    },
+    "subjectKinds": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 80
+      }
+    },
+    "fields": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/field" }
+    },
+    "compatibility": {
+      "const": "backward_compatible_additions"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120,
+      "description": "Source-local reviewed schema revision label."
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether this registered type/schema pair may currently be ingested."
+    },
+    "deprecatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "migrationGuide": {
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "$defs": {
+    "field": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "displayName",
+        "dataType",
+        "classifications",
+        "cardinality"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$",
+          "description": "Declared semantic field name, for example service.name or http.route."
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "dataType": {
+          "enum": ["string", "number", "integer", "boolean", "timestamp", "uri"]
+        },
+        "classifications": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": ["filterable", "groupable", "displayable", "sensitive", "evidence_only"]
+          }
+        },
+        "required": { "type": "boolean" },
+        "cardinality": {
+          "enum": ["low", "bounded", "high"]
+        },
+        "maxLength": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 16384
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 2000
+        }
+      },
+      "allOf": [
+        {
+          "not": {
+            "properties": {
+              "cardinality": { "const": "high" },
+              "classifications": { "contains": { "const": "groupable" } }
+            },
+            "required": ["cardinality", "classifications"]
+          }
+        },
+        {
+          "not": {
+            "properties": {
+              "classifications": {
+                "allOf": [
+                  { "contains": { "const": "sensitive" } },
+                  { "contains": { "const": "groupable" } }
+                ]
+              }
+            },
+            "required": ["classifications"]
+          }
+        }
+      ]
+    }
+  }
+}