@whooshbang/contracts 1.0.0-rc.13

package/fixtures/interaction-machine-v1/capabilities/telegram.json

@@ -0,0 +1,52 @@
+{
+  "schema": "whooshbang.provider-capabilities.v1",
+  "provider": "telegram",
+  "text": {
+    "supported": true,
+    "maximum_bytes": 8192
+  },
+  "interaction": {
+    "confirm": {
+      "mode": "native"
+    },
+    "select": {
+      "mode": "native"
+    },
+    "input": {
+      "mode": "conditional",
+      "explanation": "Input requires an exact provider reply context."
+    }
+  },
+  "streaming": {
+    "mode": "edit",
+    "explanation": "Progressive content uses bounded message edits."
+  },
+  "edit": {
+    "supported": true
+  },
+  "receipts": {
+    "provider_accepted": true,
+    "delivered": false,
+    "read": false
+  },
+  "contexts": {
+    "private_chat": {
+      "mode": "supported"
+    },
+    "thread": {
+      "mode": "conditional",
+      "explanation": "Thread support depends on the bound Telegram chat context."
+    },
+    "group": {
+      "mode": "conditional",
+      "explanation": "Group use requires an authenticated subscriber binding and exact reply context."
+    }
+  },
+  "rate_limit": {
+    "strategy": "provider_retry_after",
+    "explanation": "Safe provider retry timing is honored when available."
+  },
+  "degradation": {
+    "active": false
+  }
+}

package/fixtures/interaction-machine-v1/events/confirm-answered.json

@@ -0,0 +1,22 @@
+{
+  "schema": "whooshbang.interaction-event.v1",
+  "id": "event_interaction_confirm_001",
+  "cursor": "mcur_synthetic_001",
+  "type": "interaction.received",
+  "message_id": "msg_interactive_confirm_001",
+  "interaction_id": "interaction_synthetic_confirm",
+  "correlation_id": "request_confirm_001",
+  "answer_retained": true,
+  "response": {
+    "type": "confirm",
+    "value": true
+  },
+  "channel_context": {
+    "binding_id": "binding_synthetic_relay",
+    "channel": "telegram",
+    "conversation_kind": "private_chat",
+    "display_name": "Synthetic operator"
+  },
+  "occurred_at": "2026-07-25T17:47:00Z",
+  "expires_at": "2026-07-25T18:00:00Z"
+}

package/fixtures/interaction-machine-v1/events/input-answered.json

@@ -0,0 +1,22 @@
+{
+  "schema": "whooshbang.interaction-event.v1",
+  "id": "event_interaction_input_001",
+  "cursor": "mcur_synthetic_003",
+  "type": "interaction.received",
+  "message_id": "msg_interactive_input_001",
+  "interaction_id": "interaction_synthetic_input",
+  "correlation_id": "request_input_001",
+  "answer_retained": true,
+  "response": {
+    "type": "input",
+    "value": "Continue with the synthetic verification."
+  },
+  "channel_context": {
+    "binding_id": "binding_synthetic_relay",
+    "channel": "telegram",
+    "conversation_kind": "private_chat",
+    "display_name": "Synthetic operator"
+  },
+  "occurred_at": "2026-07-25T17:49:00Z",
+  "expires_at": "2026-07-25T18:00:00Z"
+}

package/fixtures/interaction-machine-v1/events/input-redacted.json

@@ -0,0 +1,18 @@
+{
+  "schema": "whooshbang.interaction-event.v1",
+  "id": "event_interaction_input_redacted_001",
+  "cursor": "mcur_synthetic_redacted_001",
+  "type": "interaction.received",
+  "message_id": "msg_interactive_input_redacted_001",
+  "interaction_id": "interaction_synthetic_input_redacted",
+  "correlation_id": "request_input_redacted_001",
+  "answer_retained": false,
+  "channel_context": {
+    "binding_id": "binding_synthetic_relay",
+    "channel": "telegram",
+    "conversation_kind": "private_chat",
+    "display_name": "Synthetic operator"
+  },
+  "occurred_at": "2026-07-25T17:49:00Z",
+  "expires_at": "2026-07-25T18:00:00Z"
+}

package/fixtures/interaction-machine-v1/events/select-answered.json

@@ -0,0 +1,22 @@
+{
+  "schema": "whooshbang.interaction-event.v1",
+  "id": "event_interaction_select_001",
+  "cursor": "mcur_synthetic_002",
+  "type": "interaction.received",
+  "message_id": "msg_interactive_select_001",
+  "interaction_id": "interaction_synthetic_select",
+  "correlation_id": "request_select_001",
+  "answer_retained": true,
+  "response": {
+    "type": "select",
+    "value": "staging"
+  },
+  "channel_context": {
+    "binding_id": "binding_synthetic_relay",
+    "channel": "telegram",
+    "conversation_kind": "private_chat",
+    "display_name": "Synthetic operator"
+  },
+  "occurred_at": "2026-07-25T17:48:00Z",
+  "expires_at": "2026-07-25T18:00:00Z"
+}

package/fixtures/interaction-machine-v1/requests/ack-processed.json

@@ -0,0 +1,5 @@
+{
+  "cursor": "mcur_synthetic_001",
+  "disposition": "processed",
+  "reason_code": null
+}

package/fixtures/interaction-machine-v1/requests/ack-quarantined.json

@@ -0,0 +1,5 @@
+{
+  "cursor": "mcur_synthetic_002",
+  "disposition": "quarantined",
+  "reason_code": "consumer.unsupported_version"
+}

package/fixtures/interaction-machine-v1/requests/create-machine-client.json

@@ -0,0 +1,6 @@
+{
+  "machine_id": "machine_synthetic_a",
+  "notifier_id": "default",
+  "subscriber_id": "agent_relay_operator",
+  "display_name": "Synthetic local machine"
+}

package/fixtures/interaction-machine-v1/requests/create-message-confirm.json

@@ -0,0 +1,18 @@
+{
+  "to": {
+    "subscriber_id": "agent_relay_operator"
+  },
+  "notifier_id": "default",
+  "content": {
+    "type": "text",
+    "text": "A deployment is waiting for your decision."
+  },
+  "interaction": {
+    "type": "confirm",
+    "prompt": "Approve the synthetic deployment?",
+    "confirm_label": "Approve",
+    "deny_label": "Deny",
+    "expires_at": "2026-07-25T18:00:00Z",
+    "correlation_id": "request_confirm_001"
+  }
+}

package/fixtures/interaction-machine-v1/requests/create-message-input.json

@@ -0,0 +1,16 @@
+{
+  "to": {
+    "subscriber_id": "agent_relay_operator"
+  },
+  "notifier_id": "default",
+  "content": {
+    "type": "text",
+    "text": "A bounded response is required."
+  },
+  "interaction": {
+    "type": "input",
+    "prompt": "What should happen next?",
+    "expires_at": "2026-07-25T18:00:00Z",
+    "correlation_id": "request_input_001"
+  }
+}

package/fixtures/interaction-machine-v1/requests/create-message-select.json

@@ -0,0 +1,26 @@
+{
+  "to": {
+    "subscriber_id": "agent_relay_operator"
+  },
+  "notifier_id": "default",
+  "content": {
+    "type": "text",
+    "text": "Choose a synthetic environment."
+  },
+  "interaction": {
+    "type": "select",
+    "prompt": "Choose an environment",
+    "options": [
+      {
+        "value": "staging",
+        "label": "Staging"
+      },
+      {
+        "value": "production",
+        "label": "Production"
+      }
+    ],
+    "expires_at": "2026-07-25T18:00:00Z",
+    "correlation_id": "request_select_001"
+  }
+}

package/fixtures/interaction-machine-v1/requests/register-machine-credential.json

@@ -0,0 +1,4 @@
+{
+  "credential_id": "mcred_AAECAwQFBgcICQoLDA0ODw",
+  "secret_sha256": "sha256:89c7460452eddff119fea0419e785c74de2ffb139dbe74323aca4a01e198a5dc"
+}

package/fixtures/interaction-machine-v1/scenarios/ack-conflict.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "ack-conflict",
+  "category": "machine_ack",
+  "given": {
+    "recorded_disposition": "processed",
+    "replayed_disposition": "quarantined"
+  },
+  "expected": {
+    "outcome": "conflict",
+    "status": 409,
+    "committed_cursor_unchanged": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/ack-cross-machine.json

@@ -0,0 +1,15 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "ack-cross-machine",
+  "category": "machine_authorization",
+  "given": {
+    "authenticated_machine_id": "machine_synthetic_b",
+    "event_machine_id": "machine_synthetic_a"
+  },
+  "expected": {
+    "status": 404,
+    "existence_disclosed": false,
+    "ack_recorded": false,
+    "committed_cursor": null
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/ack-out-of-order.json

@@ -0,0 +1,15 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "ack-out-of-order",
+  "category": "machine_ack",
+  "given": {
+    "earlier_cursor": "mcur_synthetic_001",
+    "earlier_acknowledged": false,
+    "ack_cursor": "mcur_synthetic_002"
+  },
+  "expected": {
+    "ack_recorded": true,
+    "committed_cursor": null,
+    "gap_skipped": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/ack-replay.json

@@ -0,0 +1,17 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "ack-replay",
+  "category": "machine_ack",
+  "given": {
+    "event_id": "event_interaction_confirm_001",
+    "cursor": "mcur_synthetic_001",
+    "disposition": "processed",
+    "same_ack_replayed": true
+  },
+  "expected": {
+    "outcome": "existing",
+    "status": 200,
+    "committed_cursor": "mcur_synthetic_001",
+    "events_skipped": 0
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/ambiguous-free-text.json

@@ -0,0 +1,15 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "ambiguous-free-text",
+  "category": "interaction_resolution",
+  "given": {
+    "eligible_open_inputs": 2,
+    "exact_reply_context": false
+  },
+  "expected": {
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "ambiguous",
+    "routed_by_recency": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/callback-token-opacity.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "callback-token-opacity",
+  "category": "callback_token",
+  "given": {
+    "token": "itok_AAECAwQFBgcICQoLDA0ODw",
+    "random_bytes": 16
+  },
+  "expected": {
+    "opaque": true,
+    "contains_identity": false,
+    "contains_answer": false,
+    "contains_command": false,
+    "contains_business_parameter": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/credential-registration-conflict.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "credential-registration-conflict",
+  "category": "machine_credential",
+  "given": {
+    "same_credential_id": true,
+    "same_digest": false
+  },
+  "expected": {
+    "outcome": "conflict",
+    "status": 409,
+    "credentials_created": 0,
+    "secret_returned": false,
+    "digest_returned": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/credential-registration-replay.json

@@ -0,0 +1,15 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "credential-registration-replay",
+  "category": "machine_credential",
+  "given": {
+    "same_credential_id": true,
+    "same_digest": true
+  },
+  "expected": {
+    "outcome": "existing",
+    "credentials_created": 0,
+    "secret_returned": false,
+    "digest_returned": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/credential-revocation-replay.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "credential-revocation-replay",
+  "category": "machine_credential",
+  "given": {
+    "credential_status": "revoked",
+    "same_revocation_replayed": true
+  },
+  "expected": {
+    "outcome": "existing",
+    "credential_status": "revoked",
+    "authorized": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/credential-rotation.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "credential-rotation",
+  "category": "machine_credential",
+  "given": {
+    "new_registered": true,
+    "new_smoke_tested": true,
+    "old_revoked_after_smoke_test": true,
+    "registration_response_lost": true
+  },
+  "expected": {
+    "valid_credentials": 1,
+    "machine_locked_out": false,
+    "old_credential_authorized": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/first-credential-activates.json

@@ -0,0 +1,15 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "first-credential-activates",
+  "category": "machine_credential",
+  "given": {
+    "client_state": "provisioning",
+    "active_credentials": 0,
+    "registration_accepted": true
+  },
+  "expected": {
+    "client_state": "active",
+    "active_credentials": 1,
+    "readable_secret_received": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/interaction-duplicate.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "interaction-duplicate",
+  "category": "interaction_resolution",
+  "given": {
+    "state": "answered",
+    "provider_update": "duplicate"
+  },
+  "expected": {
+    "state": "answered",
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "duplicate",
+    "safe_diagnostic": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/interaction-expired.json

@@ -0,0 +1,17 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "interaction-expired",
+  "category": "interaction_resolution",
+  "given": {
+    "state": "open",
+    "expires_at": "2026-07-25T18:00:00Z",
+    "response_at": "2026-07-25T18:00:00Z"
+  },
+  "expected": {
+    "state": "expired",
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "expired",
+    "safe_diagnostic": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/interaction-mismatch.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "interaction-mismatch",
+  "category": "interaction_resolution",
+  "given": {
+    "state": "open",
+    "provider_binding_matches": false
+  },
+  "expected": {
+    "state": "open",
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "identity_mismatch",
+    "trusted_provider_identity": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/interaction-retired.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "interaction-retired",
+  "category": "interaction_resolution",
+  "given": {
+    "state": "retired",
+    "provider_update": "late_answer"
+  },
+  "expected": {
+    "state": "retired",
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "stale",
+    "safe_diagnostic": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/interaction-stale.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "interaction-stale",
+  "category": "interaction_resolution",
+  "given": {
+    "state": "cancelled",
+    "provider_update": "late_answer"
+  },
+  "expected": {
+    "state": "cancelled",
+    "answers_created": 0,
+    "events_created": 0,
+    "outcome": "stale",
+    "safe_diagnostic": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-admin-denied.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-admin-denied",
+  "category": "machine_authorization",
+  "given": {
+    "credential_kind": "machine",
+    "operation_id": "registerMachineCredential"
+  },
+  "expected": {
+    "status": 403,
+    "authorized": false,
+    "required_project_scope": "machine-clients:write"
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-bound-message-create.json

@@ -0,0 +1,22 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-bound-message-create",
+  "category": "machine_authorization",
+  "given": {
+    "credential_kind": "machine",
+    "credential_status": "active",
+    "operation_id": "createMessage",
+    "scope": "machine-messages:write",
+    "authenticated_project_id": "project_synthetic",
+    "authenticated_environment": "test",
+    "bound_notifier_id": "default",
+    "bound_subscriber_id": "agent_relay_operator",
+    "request_notifier_id": "default",
+    "request_subscriber_id": "agent_relay_operator"
+  },
+  "expected": {
+    "authorized": true,
+    "target_bound": true,
+    "provider_call_allowed": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-cancel-denied.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-cancel-denied",
+  "category": "machine_authorization",
+  "given": {
+    "credential_kind": "machine",
+    "operation_id": "cancelMessage"
+  },
+  "expected": {
+    "status": 403,
+    "authorized": false,
+    "required_project_scope": "messages:write"
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-crash-before-ack.json

@@ -0,0 +1,16 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-crash-before-ack",
+  "category": "machine_poll",
+  "given": {
+    "committed_cursor": null,
+    "polled_event_id": "event_interaction_confirm_001",
+    "acknowledged": false,
+    "client_restarted": true
+  },
+  "expected": {
+    "event_repeated": true,
+    "event_id": "event_interaction_confirm_001",
+    "committed_cursor": null
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-notifier-mismatch.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-notifier-mismatch",
+  "category": "machine_authorization",
+  "given": {
+    "credential_notifier_id": "default",
+    "request_notifier_id": "another_notifier"
+  },
+  "expected": {
+    "authorized": false,
+    "provider_called": false,
+    "existence_disclosed": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-other-message-read.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-other-message-read",
+  "category": "machine_authorization",
+  "given": {
+    "credential_machine_client_id": "machine_client_synthetic_001",
+    "message_machine_client_id": "machine_client_synthetic_002"
+  },
+  "expected": {
+    "status": 404,
+    "authorized": false,
+    "existence_disclosed": false
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-owned-message-read.json

@@ -0,0 +1,22 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-owned-message-read",
+  "category": "machine_authorization",
+  "given": {
+    "credential_kind": "machine",
+    "credential_status": "active",
+    "operation_id": "getMessage",
+    "scope": "machine-messages:read",
+    "authenticated_project_id": "project_synthetic",
+    "authenticated_environment": "test",
+    "credential_machine_client_id": "machine_client_synthetic_001",
+    "message_project_id": "project_synthetic",
+    "message_environment": "test",
+    "message_machine_client_id": "machine_client_synthetic_001"
+  },
+  "expected": {
+    "authorized": true,
+    "own_message_only": true,
+    "message_returned": true
+  }
+}

package/fixtures/interaction-machine-v1/scenarios/machine-subscriber-mismatch.json

@@ -0,0 +1,14 @@
+{
+  "contract_version": "1.0.0-rc.13",
+  "id": "machine-subscriber-mismatch",
+  "category": "machine_authorization",
+  "given": {
+    "credential_subscriber_id": "agent_relay_operator",
+    "request_subscriber_id": "another_subscriber"
+  },
+  "expected": {
+    "authorized": false,
+    "provider_called": false,
+    "existence_disclosed": false
+  }
+}