connector-capability.schema.json

JSON · 58 lines · 5,460 bytes · wiki path 10 Architecture/contracts/connector-capability.schema.json · download the raw file · cited from Contracts

Same folder: Connectors.Abstractions.cs · configuration-change.schema.json · configuration-input.schema.json · eval-set.schema.json · execution-obligations.schema.json · ledger-record.schema.json · message-envelope.schema.json · model-turn.schema.json · module-manifest.schema.json · openapi.yaml · realtime-events.schema.json · runtime-state.schema.json · tool-package.schema.json · validate_case_journeys.py · validate_contracts.py · validate_runtime_contracts.py · validate_tool_packages.py · write-shape.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aisa.ablera.com/contracts/connector-capability.schema.json",
  "title": "Connector capability description (platform seam 2 of 5)",
  "description": "Failure and Recovery § 4 (D66): every connector operation is a versioned CONNECTOR_SCOPES row of kind 'operation'; its absence fails closed. An agent discovers which operations exist and what evidence they return; an unknown operation is a capability gap to escalate, never a reason to improvise. Reach rows (kind 'reach') describe how a target is reached — direct only (D132).",
  "type": "object",
  "additionalProperties": false,
  "required": ["kind", "connector", "environment", "system", "version", "target_identity", "modes"],
  "properties": {
    "kind": { "type": "string", "enum": ["reach", "operation", "ceiling"] },
    "connector": {"type": "string", "minLength": 1, "description": "Registered connector key; customer capability data, not a hard-coded estate list."},
    "customer_code": { "type": "string" },
    "environment": { "type": "string", "description": "PROD · STAGING · QA · DEV — a real credential boundary (Trust and Data § 2)" },
    "system": { "type": "string" },
    "version": { "type": "integer", "minimum": 1 },
    "operation_id": { "type": "string", "pattern": "^[a-z][a-z0-9_.\\-]+$", "description": "e.g. oracle-ipal.select, oracle-ipal.write_a, oracle-ipal.write_b, oracle-ipal.plsql_snapshot, abacus-gateway.get_rates, gitlab.open_merge_request" },
    "input_contract": { "type": "object", "description": "JSON Schema of the operation's input; the runtime validates before the call" },
    "target_identity": {
      "type": "object", "additionalProperties": true,
      "properties": {
        "host": { "type": "string" }, "port": { "type": "integer" }, "service": { "type": "string" },
        "paths": { "type": "array", "items": { "type": "string" } },
        "schema": { "type": "string" }, "objects": { "type": "array", "items": { "type": "string" } },
        "project": { "type": "string" }, "queue": { "type": "string" }, "mailbox": { "type": "string" }
      }
    },
    "effect_class": { "type": "string", "enum": ["read", "transactional", "compensable", "irreversible", "ddl"] },
    "authorization": { "type": "string", "enum": ["read_grant", "write_grant", "gate"] },
    "idempotency_key_shape": { "type": "string", "description": "how a repeat of the same call is recognised, e.g. 'case_id+step_id+statement_hash'" },
    "timeout_ms": { "type": "integer", "minimum": 1 },
    "effect_of_timeout": { "type": "string", "enum": ["none", "unknown", "applied"], "description": "what a timeout means for the target: none (nothing happened), unknown (reconcile first), applied (the effect is there)" },
    "recovery": { "type": "string", "enum": ["retryable", "reconcile_first", "never_retry"] },
    "evidence_returned": { "type": "array", "items": { "type": "string" }, "description": "the fields the envelope carries back: row_count, returned_ids, version_id, commit_sha, pipeline_id, message_id …" },
    "modes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": ["read", "dry_run", "write", "send", "ddl"] } },
    "write_shape": {"type": "string", "enum": ["A", "B", "E"], "description": "Execution form: A collapsed transaction; B deterministic leased transaction; E external/DDL effect. Persisted as CONNECTOR_SCOPES.EXECUTION_FORM."},
    "route": {
      "type": "object", "additionalProperties": false,
      "required": ["kind"],
      "properties": {
        "kind": { "type": "string", "enum": ["direct", "unreachable"], "description": "D132: direct connections only; the tunnel route kind is dropped" },
        "verified_on": { "type": "string", "format": "date-time" },
        "probe": { "type": "string", "description": "the probe that verified it (tns ping, https HEAD, ldap bind …)" }
      }
    },
    "credential_ref": { "type": "string", "description": "Vault path; never a value" },
    "ceiling": { "type": "object", "description": "kind = ceiling: the environment × system × target × mode set no grant may exceed" },
    "health": { "type": "string", "enum": ["green", "amber", "red", "unknown"] },
    "state": { "type": "string", "enum": ["draft", "published", "retired"] }
  },
  "allOf": [
    {"if": {"properties": {"kind": {"const": "operation"}}}, "then": {"required": ["operation_id", "effect_class", "authorization", "timeout_ms", "effect_of_timeout", "recovery", "evidence_returned"]}},
    {"if": {"properties": {"kind": {"const": "operation"}, "effect_class": {"enum": ["transactional", "compensable", "irreversible", "ddl"]}}}, "then": {"required": ["write_shape", "idempotency_key_shape"], "properties": {"authorization": {"enum": ["write_grant", "gate"]}}}},
    {"if": {"properties": {"kind": {"const": "operation"}, "effect_class": {"const": "read"}}}, "then": {"properties": {"authorization": {"const": "read_grant"}, "modes": {"items": {"enum": ["read", "dry_run"]}}}}},
    {"if": {"properties": {"kind": {"const": "reach"}}}, "then": {"required": ["route", "credential_ref"]}},
    {"if": {"properties": {"kind": {"const": "ceiling"}}}, "then": {"required": ["ceiling"]}},
    {"if": {"properties": {"kind": {"const": "operation"}, "effect_class": {"enum": ["ddl", "irreversible"]}}, "required": ["kind", "effect_class"]}, "then": {"properties": {"write_shape": {"const": "E"}}}}
  ]
}