connector-contract-v3 (B3a): the v3 contract as typed documents over CultNet operations (squash of eureka-body/connector-contract-v3 ec0519d..a0a6ccb)

Each frame is a cultnet.operation_request.v0 / operation_response.v0
(service gamecult.model.connector, operation invoke) over loopback
TcpFramed, carrying the kit's sealed per-caller envelope: named
MessagePack only, unknown fields refused, binary ciphertext, JSON Schema
published from the types (ruling connector-v3-wire-cultnet-operation).
v2 is deleted with its fixtures (ruling connector-v3-only). The request is
provider-neutral, with max_output_tokens required; failure kinds, stop
reasons and usage are typed, and Policy is three typed refusals. Golden
v3 frames pin the carriage and envelope.

Spec eureka-body:cut_spec:cut-connector-contract-v3.r2; reports h1-h2;
Soul s2 holds (verdict eureka-body:verdict:cut-connector-contract-v3.s2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-28 12:26:34 +01:00
commit bf958fc327
49 changed files with 3127 additions and 767 deletions

View file

@ -0,0 +1,229 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ProviderRequest",
"type": "object",
"properties": {
"cache_retention": {
"anyOf": [
{
"$ref": "#/$defs/CacheRetention"
},
{
"type": "null"
}
]
},
"conversation_id": {
"type": "string"
},
"input": {
"type": "array",
"items": {
"$ref": "#/$defs/InputItem"
}
},
"instructions": {
"type": "string"
},
"max_output_tokens": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"model": {
"type": "string"
},
"output_schema_json": {
"type": [
"string",
"null"
]
},
"parallel_tool_calls": {
"type": "boolean"
},
"reasoning_effort": {
"anyOf": [
{
"$ref": "#/$defs/ReasoningEffort"
},
{
"type": "null"
}
]
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
},
"tool_choice": {
"$ref": "#/$defs/ToolChoice"
},
"tools": {
"type": "array",
"items": {
"$ref": "#/$defs/ToolDefinition"
}
}
},
"additionalProperties": false,
"required": [
"schema_id",
"request_id",
"conversation_id",
"model",
"instructions",
"input",
"tools",
"tool_choice",
"parallel_tool_calls",
"max_output_tokens"
],
"$defs": {
"CacheRetention": {
"type": "string",
"enum": [
"short",
"long"
]
},
"InputItem": {
"oneOf": [
{
"type": "object",
"properties": {
"UserText": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
}
},
"additionalProperties": false,
"required": [
"UserText"
]
},
{
"type": "object",
"properties": {
"AssistantText": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
}
},
"additionalProperties": false,
"required": [
"AssistantText"
]
},
{
"type": "object",
"properties": {
"ToolCall": {
"type": "object",
"properties": {
"arguments": {
"type": "string"
},
"call_id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"call_id",
"name",
"arguments"
]
}
},
"additionalProperties": false,
"required": [
"ToolCall"
]
},
{
"type": "object",
"properties": {
"ToolResult": {
"type": "object",
"properties": {
"call_id": {
"type": "string"
},
"output": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"call_id",
"output"
]
}
},
"additionalProperties": false,
"required": [
"ToolResult"
]
}
]
},
"ReasoningEffort": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"max"
]
},
"ToolChoice": {
"type": "string",
"enum": [
"auto",
"required"
]
},
"ToolDefinition": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"name": {
"type": "string"
},
"parameters_json": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name",
"description",
"parameters_json"
]
}
}
}

View file

@ -0,0 +1,53 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TransportEnvelope",
"type": "object",
"properties": {
"caller_runtime_id": {
"type": "string"
},
"ciphertext": {
"description": "MessagePack bin: the raw ciphertext bytes, never an array of integers",
"type": "string",
"format": "binary"
},
"message_kind": {
"$ref": "#/$defs/EnvelopeKind"
},
"nonce": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 12,
"minItems": 12
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"schema_id",
"caller_runtime_id",
"request_id",
"message_kind",
"nonce",
"ciphertext"
],
"$defs": {
"EnvelopeKind": {
"type": "string",
"enum": [
"Invocation",
"Result"
]
}
}
}

View file

@ -0,0 +1,279 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TransportInvocation",
"type": "object",
"properties": {
"caller_runtime_id": {
"type": "string"
},
"expires_at_unix_ms": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"native_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"provider_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"request": {
"$ref": "#/$defs/ProviderRequest"
},
"schema_id": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"schema_id",
"caller_runtime_id",
"expires_at_unix_ms",
"native_request_sha256",
"provider_request_sha256",
"request"
],
"$defs": {
"CacheRetention": {
"type": "string",
"enum": [
"short",
"long"
]
},
"InputItem": {
"oneOf": [
{
"type": "object",
"properties": {
"UserText": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
}
},
"additionalProperties": false,
"required": [
"UserText"
]
},
{
"type": "object",
"properties": {
"AssistantText": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
}
},
"additionalProperties": false,
"required": [
"AssistantText"
]
},
{
"type": "object",
"properties": {
"ToolCall": {
"type": "object",
"properties": {
"arguments": {
"type": "string"
},
"call_id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"call_id",
"name",
"arguments"
]
}
},
"additionalProperties": false,
"required": [
"ToolCall"
]
},
{
"type": "object",
"properties": {
"ToolResult": {
"type": "object",
"properties": {
"call_id": {
"type": "string"
},
"output": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"call_id",
"output"
]
}
},
"additionalProperties": false,
"required": [
"ToolResult"
]
}
]
},
"ProviderRequest": {
"type": "object",
"properties": {
"cache_retention": {
"anyOf": [
{
"$ref": "#/$defs/CacheRetention"
},
{
"type": "null"
}
]
},
"conversation_id": {
"type": "string"
},
"input": {
"type": "array",
"items": {
"$ref": "#/$defs/InputItem"
}
},
"instructions": {
"type": "string"
},
"max_output_tokens": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"model": {
"type": "string"
},
"output_schema_json": {
"type": [
"string",
"null"
]
},
"parallel_tool_calls": {
"type": "boolean"
},
"reasoning_effort": {
"anyOf": [
{
"$ref": "#/$defs/ReasoningEffort"
},
{
"type": "null"
}
]
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
},
"tool_choice": {
"$ref": "#/$defs/ToolChoice"
},
"tools": {
"type": "array",
"items": {
"$ref": "#/$defs/ToolDefinition"
}
}
},
"additionalProperties": false,
"required": [
"schema_id",
"request_id",
"conversation_id",
"model",
"instructions",
"input",
"tools",
"tool_choice",
"parallel_tool_calls",
"max_output_tokens"
]
},
"ReasoningEffort": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"max"
]
},
"ToolChoice": {
"type": "string",
"enum": [
"auto",
"required"
]
},
"ToolDefinition": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"name": {
"type": "string"
},
"parameters_json": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name",
"description",
"parameters_json"
]
}
}
}

View file

@ -0,0 +1,186 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TransportReceipt",
"type": "object",
"properties": {
"caller_runtime_id": {
"type": "string"
},
"model": {
"type": "string"
},
"native_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"outcome": {
"$ref": "#/$defs/TransportOutcome"
},
"provider": {
"type": "string"
},
"provider_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"schema_id",
"request_id",
"caller_runtime_id",
"native_request_sha256",
"provider_request_sha256",
"model",
"provider",
"outcome"
],
"$defs": {
"FailureKind": {
"description": "What kind of failure a provider reported. `ResultSize` is the connector's own\nstand-in for a result whose sealed frame cannot be carried.",
"type": "string",
"enum": [
"result_size",
"invalid_request",
"authentication",
"rate_limited",
"unavailable",
"timeout",
"provider"
]
},
"StopReason": {
"description": "Why a provider stopped producing output.",
"type": "string",
"enum": [
"end_turn",
"tool_use",
"max_output_tokens",
"stop_sequence",
"refusal",
"context_window"
]
},
"TransportOutcome": {
"oneOf": [
{
"type": "object",
"properties": {
"Completed": {
"type": "object",
"properties": {
"provider_response_id": {
"type": [
"string",
"null"
]
},
"stop_reason": {
"$ref": "#/$defs/StopReason"
},
"usage": {
"$ref": "#/$defs/Usage"
}
},
"additionalProperties": false,
"required": [
"stop_reason",
"usage"
]
}
},
"additionalProperties": false,
"required": [
"Completed"
]
},
{
"type": "object",
"properties": {
"Failed": {
"type": "object",
"properties": {
"kind": {
"$ref": "#/$defs/FailureKind"
},
"message": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"kind",
"message"
]
}
},
"additionalProperties": false,
"required": [
"Failed"
]
}
]
},
"Usage": {
"description": "Token accounting for one completed request. Cache reads and writes are\ncounted apart from plain input; `reasoning_tokens` is absent when the\nprovider does not report it.",
"type": "object",
"properties": {
"cache_read_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"cache_write_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"input_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"output_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"input_tokens",
"cache_read_tokens",
"cache_write_tokens",
"output_tokens"
]
}
}
}

View file

@ -0,0 +1,342 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TransportResult",
"type": "object",
"properties": {
"caller_runtime_id": {
"type": "string"
},
"disposition": {
"$ref": "#/$defs/TransportDisposition"
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"schema_id",
"request_id",
"caller_runtime_id",
"disposition"
],
"$defs": {
"FailureKind": {
"description": "What kind of failure a provider reported. `ResultSize` is the connector's own\nstand-in for a result whose sealed frame cannot be carried.",
"type": "string",
"enum": [
"result_size",
"invalid_request",
"authentication",
"rate_limited",
"unavailable",
"timeout",
"provider"
]
},
"Refusal": {
"type": "string",
"enum": [
"Expired",
"IdentitySubstitution",
"ProviderDigestSubstitution",
"ModelNotAllowed",
"OutputBound",
"PayloadBound",
"Capacity",
"InFlight",
"Indeterminate",
"ReplayConflict",
"Malformed"
]
},
"StopReason": {
"description": "Why a provider stopped producing output.",
"type": "string",
"enum": [
"end_turn",
"tool_use",
"max_output_tokens",
"stop_sequence",
"refusal",
"context_window"
]
},
"TransportDisposition": {
"oneOf": [
{
"type": "object",
"properties": {
"Refused": {
"$ref": "#/$defs/Refusal"
}
},
"additionalProperties": false,
"required": [
"Refused"
]
},
{
"type": "object",
"properties": {
"Transported": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/TransportEvent"
}
},
"receipt": {
"$ref": "#/$defs/TransportReceipt"
}
},
"additionalProperties": false,
"required": [
"events",
"receipt"
]
}
},
"additionalProperties": false,
"required": [
"Transported"
]
}
]
},
"TransportEvent": {
"type": "object",
"properties": {
"payload": {
"$ref": "#/$defs/TransportEventPayload"
},
"sequence": {
"type": "integer",
"format": "uint64",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"sequence",
"payload"
]
},
"TransportEventPayload": {
"oneOf": [
{
"type": "object",
"properties": {
"TextDelta": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
}
},
"additionalProperties": false,
"required": [
"TextDelta"
]
},
{
"type": "object",
"properties": {
"ToolCall": {
"type": "object",
"properties": {
"arguments": {
"type": "string"
},
"call_id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"call_id",
"name",
"arguments"
]
}
},
"additionalProperties": false,
"required": [
"ToolCall"
]
}
]
},
"TransportOutcome": {
"oneOf": [
{
"type": "object",
"properties": {
"Completed": {
"type": "object",
"properties": {
"provider_response_id": {
"type": [
"string",
"null"
]
},
"stop_reason": {
"$ref": "#/$defs/StopReason"
},
"usage": {
"$ref": "#/$defs/Usage"
}
},
"additionalProperties": false,
"required": [
"stop_reason",
"usage"
]
}
},
"additionalProperties": false,
"required": [
"Completed"
]
},
{
"type": "object",
"properties": {
"Failed": {
"type": "object",
"properties": {
"kind": {
"$ref": "#/$defs/FailureKind"
},
"message": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"kind",
"message"
]
}
},
"additionalProperties": false,
"required": [
"Failed"
]
}
]
},
"TransportReceipt": {
"type": "object",
"properties": {
"caller_runtime_id": {
"type": "string"
},
"model": {
"type": "string"
},
"native_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"outcome": {
"$ref": "#/$defs/TransportOutcome"
},
"provider": {
"type": "string"
},
"provider_request_sha256": {
"type": "array",
"items": {
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"maxItems": 32,
"minItems": 32
},
"request_id": {
"type": "string"
},
"schema_id": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"schema_id",
"request_id",
"caller_runtime_id",
"native_request_sha256",
"provider_request_sha256",
"model",
"provider",
"outcome"
]
},
"Usage": {
"description": "Token accounting for one completed request. Cache reads and writes are\ncounted apart from plain input; `reasoning_tokens` is absent when the\nprovider does not report it.",
"type": "object",
"properties": {
"cache_read_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"cache_write_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"input_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"output_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"input_tokens",
"cache_read_tokens",
"cache_write_tokens",
"output_tokens"
]
}
}
}