@whooshbang/contracts 1.0.0-rc.13

package/schemas/machine-v1.schema.json

@@ -0,0 +1,430 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whooshbang.flowxo.com/schemas/machine-v1.schema.json",
+  "x-contract-version": "1.0.0-rc.13",
+  "title": "MachineV1ContractDocument",
+  "description": "Machine-client administration, locally generated credential metadata, durable long-poll, and contiguous acknowledgement contracts.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/CreateMachineClientRequest"
+    },
+    {
+      "$ref": "#/$defs/MachineClient"
+    },
+    {
+      "$ref": "#/$defs/RegisterMachineCredentialRequest"
+    },
+    {
+      "$ref": "#/$defs/MachineCredential"
+    },
+    {
+      "$ref": "#/$defs/MachineEventPollResponse"
+    },
+    {
+      "$ref": "#/$defs/MachineEventAckRequest"
+    },
+    {
+      "$ref": "#/$defs/MachineEventAckResponse"
+    },
+    {
+      "$ref": "#/$defs/MachineCredentialBearer"
+    }
+  ],
+  "$defs": {
+    "OpaqueIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "Timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]+)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$"
+    },
+    "Environment": {
+      "type": "string",
+      "enum": ["test", "live"]
+    },
+    "MachineCredentialId": {
+      "type": "string",
+      "pattern": "^mcred_[A-Za-z0-9_-]{21}[AQgw]$",
+      "description": "mcred_ followed by the canonical unpadded base64url encoding of exactly 16 random bytes."
+    },
+    "MachineSecretDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "The only secret-derived value accepted by the administration API."
+    },
+    "MachineCredentialBearer": {
+      "type": "string",
+      "pattern": "^wb_mc1\\.mcred_[A-Za-z0-9_-]{21}[AQgw]\\.[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$",
+      "description": "The exact runtime bearer syntax. The final segment is canonical unpadded base64url for exactly 32 locally generated random bytes."
+    },
+    "MachineScope": {
+      "type": "string",
+      "enum": [
+        "machine-messages:write",
+        "machine-messages:read",
+        "machine-events:read",
+        "machine-events:ack"
+      ]
+    },
+    "MachineScopeSummary": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/MachineScope"
+      },
+      "minItems": 4,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "description": "Fixed least-privilege capabilities, each constrained to this client's bound destination or stream."
+    },
+    "CreateMachineClientRequest": {
+      "type": "object",
+      "required": ["machine_id", "notifier_id", "subscriber_id"],
+      "properties": {
+        "machine_id": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "notifier_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "subscriber_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        }
+      },
+      "additionalProperties": false
+    },
+    "MachineClient": {
+      "type": "object",
+      "required": [
+        "id",
+        "project_id",
+        "environment",
+        "machine_id",
+        "notifier_id",
+        "subscriber_id",
+        "binding_id",
+        "status",
+        "scope_summary",
+        "created_at",
+        "updated_at"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "project_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "environment": {
+          "$ref": "#/$defs/Environment"
+        },
+        "machine_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "notifier_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "subscriber_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "binding_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        "status": {
+          "type": "string",
+          "enum": ["provisioning", "active", "revoked"]
+        },
+        "scope_summary": {
+          "$ref": "#/$defs/MachineScopeSummary"
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "updated_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "last_used_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "revoked_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "revoked"
+              }
+            },
+            "required": ["status"]
+          },
+          "then": {
+            "required": ["revoked_at"],
+            "properties": {
+              "revoked_at": {}
+            }
+          },
+          "else": {
+            "properties": {
+              "revoked_at": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "RegisterMachineCredentialRequest": {
+      "type": "object",
+      "required": ["credential_id", "secret_sha256"],
+      "properties": {
+        "credential_id": {
+          "$ref": "#/$defs/MachineCredentialId"
+        },
+        "secret_sha256": {
+          "$ref": "#/$defs/MachineSecretDigest"
+        }
+      },
+      "additionalProperties": false
+    },
+    "MachineCredential": {
+      "type": "object",
+      "required": [
+        "credential_id",
+        "machine_client_id",
+        "status",
+        "scope_summary",
+        "created_at"
+      ],
+      "properties": {
+        "credential_id": {
+          "$ref": "#/$defs/MachineCredentialId"
+        },
+        "machine_client_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "revoked"]
+        },
+        "scope_summary": {
+          "$ref": "#/$defs/MachineScopeSummary"
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "last_used_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "revoked_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "revoked"
+              }
+            },
+            "required": ["status"]
+          },
+          "then": {
+            "required": ["revoked_at"],
+            "properties": {
+              "revoked_at": {}
+            }
+          },
+          "else": {
+            "properties": {
+              "revoked_at": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "MachineCursor": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^mcur_[A-Za-z0-9_-]+$",
+      "description": "An opaque position within only the authenticated machine stream."
+    },
+    "MachineEventPollResponse": {
+      "type": "object",
+      "required": ["schema", "events", "committed_cursor", "server_time"],
+      "properties": {
+        "schema": {
+          "const": "whooshbang.machine-events.v1"
+        },
+        "events": {
+          "type": "array",
+          "maxItems": 50,
+          "x-unique-property": "cursor",
+          "items": {
+            "$ref": "interaction-v1.schema.json#/$defs/InteractionEvent"
+          }
+        },
+        "committed_cursor": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/MachineCursor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "server_time": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      },
+      "additionalProperties": false
+    },
+    "MachineEventAckDisposition": {
+      "type": "string",
+      "enum": ["processed", "quarantined"]
+    },
+    "QuarantineReasonCode": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    },
+    "MachineEventAckRequest": {
+      "type": "object",
+      "required": ["cursor", "disposition"],
+      "properties": {
+        "cursor": {
+          "$ref": "#/$defs/MachineCursor"
+        },
+        "disposition": {
+          "$ref": "#/$defs/MachineEventAckDisposition"
+        },
+        "reason_code": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/QuarantineReasonCode"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "disposition": {
+                "const": "quarantined"
+              }
+            },
+            "required": ["disposition"]
+          },
+          "then": {
+            "required": ["reason_code"],
+            "properties": {
+              "reason_code": {
+                "$ref": "#/$defs/QuarantineReasonCode"
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "reason_code": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "MachineEventAckResponse": {
+      "type": "object",
+      "required": [
+        "event_id",
+        "cursor",
+        "disposition",
+        "acknowledgement_status",
+        "committed_cursor",
+        "advanced"
+      ],
+      "properties": {
+        "event_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "cursor": {
+          "$ref": "#/$defs/MachineCursor"
+        },
+        "disposition": {
+          "$ref": "#/$defs/MachineEventAckDisposition"
+        },
+        "reason_code": {
+          "$ref": "#/$defs/QuarantineReasonCode"
+        },
+        "acknowledgement_status": {
+          "type": "string",
+          "enum": ["recorded", "existing"]
+        },
+        "committed_cursor": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/MachineCursor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "advanced": {
+          "type": "boolean"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "disposition": {
+                "const": "quarantined"
+              }
+            },
+            "required": ["disposition"]
+          },
+          "then": {
+            "required": ["reason_code"],
+            "properties": {
+              "reason_code": {}
+            }
+          },
+          "else": {
+            "properties": {
+              "reason_code": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/provider-capabilities-v1.schema.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
+  "x-contract-version": "1.0.0-rc.13",
+  "title": "ProviderCapabilitiesV1",
+  "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
+  "type": "object",
+  "required": [
+    "schema",
+    "provider",
+    "text",
+    "interaction",
+    "streaming",
+    "edit",
+    "receipts",
+    "contexts",
+    "rate_limit",
+    "degradation"
+  ],
+  "properties": {
+    "schema": {
+      "const": "whooshbang.provider-capabilities.v1"
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9_-]*$"
+    },
+    "text": {
+      "type": "object",
+      "required": ["supported", "maximum_bytes"],
+      "properties": {
+        "supported": {
+          "type": "boolean"
+        },
+        "maximum_bytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576
+        }
+      },
+      "additionalProperties": false
+    },
+    "interaction": {
+      "type": "object",
+      "required": ["confirm", "select", "input"],
+      "properties": {
+        "confirm": {
+          "$ref": "#/$defs/InteractionCapability"
+        },
+        "select": {
+          "$ref": "#/$defs/InteractionCapability"
+        },
+        "input": {
+          "$ref": "#/$defs/InteractionCapability"
+        }
+      },
+      "additionalProperties": false
+    },
+    "streaming": {
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "native",
+            "edit",
+            "typing_then_final",
+            "final_only",
+            "unsupported"
+          ]
+        },
+        "explanation": {
+          "$ref": "#/$defs/SafeExplanation"
+        }
+      },
+      "additionalProperties": false
+    },
+    "edit": {
+      "type": "object",
+      "required": ["supported"],
+      "properties": {
+        "supported": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "receipts": {
+      "type": "object",
+      "required": ["provider_accepted", "delivered", "read"],
+      "properties": {
+        "provider_accepted": {
+          "type": "boolean"
+        },
+        "delivered": {
+          "type": "boolean"
+        },
+        "read": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "contexts": {
+      "type": "object",
+      "required": ["private_chat", "thread", "group"],
+      "properties": {
+        "private_chat": {
+          "$ref": "#/$defs/ContextSupport"
+        },
+        "thread": {
+          "$ref": "#/$defs/ContextSupport"
+        },
+        "group": {
+          "$ref": "#/$defs/ContextSupport"
+        }
+      },
+      "additionalProperties": false
+    },
+    "rate_limit": {
+      "type": "object",
+      "required": ["strategy"],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "provider_retry_after",
+            "token_bucket",
+            "fixed_window",
+            "adaptive",
+            "unknown"
+          ]
+        },
+        "explanation": {
+          "$ref": "#/$defs/SafeExplanation"
+        }
+      },
+      "additionalProperties": false
+    },
+    "degradation": {
+      "$ref": "#/$defs/Degradation"
+    }
+  },
+  "$defs": {
+    "SafeExplanation": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "InteractionCapability": {
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["native", "fallback", "unsupported", "conditional"]
+        },
+        "explanation": {
+          "$ref": "#/$defs/SafeExplanation"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "enum": ["fallback", "conditional"]
+              }
+            },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["explanation"],
+            "properties": {
+              "explanation": {}
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "ContextSupport": {
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["supported", "unsupported", "conditional"]
+        },
+        "explanation": {
+          "$ref": "#/$defs/SafeExplanation"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "conditional"
+              }
+            },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["explanation"],
+            "properties": {
+              "explanation": {}
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "Degradation": {
+      "type": "object",
+      "required": ["active"],
+      "properties": {
+        "active": {
+          "type": "boolean"
+        },
+        "code": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "explanation": {
+          "$ref": "#/$defs/SafeExplanation"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "active": {
+                "const": true
+              }
+            },
+            "required": ["active"]
+          },
+          "then": {
+            "required": ["code", "explanation"],
+            "properties": {
+              "code": {},
+              "explanation": {}
+            }
+          },
+          "else": {
+            "properties": {
+              "code": false,
+              "explanation": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}