gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/base.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:gateway:connector:primitives:1",
+  "$defs": {
+    "Id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "Label": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "Text": {
+      "type": "string"
+    },
+    "Email": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 254
+    },
+    "Timestamp": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

gatewaysdk/environment/schema/connectors/custom/handlers.py

@@ -0,0 +1,18 @@
+"""Custom connector world tools; edit freely, but keep writes on the store."""
+
+from gateway_env import store, tool
+
+
+@tool(name="list_records")
+def list_records(kind):
+    return [r for r in store.list("records") if r["kind"] == kind]
+
+
+@tool(name="get_record")
+def get_record(id):
+    return store.get("records", {"id": id})
+
+
+@tool(name="create_record")
+def create_record(record):
+    return store.insert("records", record, source={"record": "tool.create_record"})

gatewaysdk/environment/schema/connectors/custom/world.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:gateway:connector:custom",
+  "$defs": {
+    "Record": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "kind": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "name": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "attributes": {
+          "type": "object",
+          "properties": {},
+          "required": [],
+          "additionalProperties": true
+        },
+        "updated_at": {
+          "$ref": "base.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "name",
+        "attributes",
+        "updated_at"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "x-gateway": {
+    "version": 1,
+    "domain_version": "1.0.0",
+    "package": {
+      "id": "gateway-connector-custom",
+      "version": "1.0.0"
+    },
+    "entities": {
+      "records": {
+        "schema": {
+          "$ref": "#/$defs/Record"
+        },
+        "primary_key": [
+          "id"
+        ],
+        "unique": [],
+        "relationships": []
+      }
+    },
+    "tools": {
+      "list_records": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "$ref": "base.json#/$defs/Label"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Record"
+          }
+        },
+        "description": "Records of one kind."
+      },
+      "get_record": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "$ref": "base.json#/$defs/Id"
+            }
+          },
+          "required": [
+            "id"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Record"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "description": "One record, or null."
+      },
+      "create_record": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "record": {
+              "$ref": "#/$defs/Record"
+            }
+          },
+          "required": [
+            "record"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "$ref": "#/$defs/Record"
+        },
+        "description": "Create a record."
+      }
+    }
+  }
+}

gatewaysdk/environment/schema/connectors/github/handlers.py

@@ -0,0 +1,81 @@
+"""GitHub world tools; every mutation goes through the schema store.
+
+Errors mirror the REST error body
+``{"message", "documentation_url", "errors": [{"resource", "field", "code"}]}``:
+404 carries the message ``Not Found``, 422 carries ``Validation Failed`` plus the
+resource/field/code triple. An operation the world does not model raises
+``not_modelled`` with the vendor route rather than fabricating a response.
+"""
+
+from gateway_env import store, tool
+
+ISSUES = "https://docs.github.com/rest/issues/issues"
+LABELS = "https://docs.github.com/rest/issues/labels"
+PULLS = "https://docs.github.com/rest/pulls/pulls"
+
+
+def _not_found(documentation_url):
+    raise ValueError(f"Not Found ({documentation_url})")
+
+
+def _validation_failed(resource, field, code, documentation_url):
+    raise ValueError(f"Validation Failed: {resource}.{field} {code} ({documentation_url})")
+
+
+def _repository(repo_id, documentation_url):
+    repository = store.get("github_repositories", {"id": repo_id})
+    if repository is None:
+        _not_found(documentation_url)
+    return repository
+
+
+@tool(name="list_issues")
+def list_issues(repo_id, state=None):
+    _repository(repo_id, f"{ISSUES}#list-repository-issues")
+    issues = [i for i in store.list("github_issues") if i["repo_id"] == repo_id]
+    return [i for i in issues if state is None or i["state"] == state]
+
+
+@tool(name="get_pull_request")
+def get_pull_request(repo_id, number):
+    pull = store.get("github_pull_requests", {"repo_id": repo_id, "number": number})
+    if pull is None:
+        _not_found(f"{PULLS}#get-a-pull-request")
+    return pull
+
+
+@tool(name="create_issue")
+def create_issue(issue):
+    _repository(issue["repo_id"], f"{ISSUES}#create-an-issue")
+    key = {"repo_id": issue["repo_id"], "number": issue["number"]}
+    if store.get("github_issues", key) is not None:
+        _validation_failed("Issue", "number", "already_exists", f"{ISSUES}#create-an-issue")
+    return store.insert("github_issues", issue, source={"record": "tool.create_issue"})
+
+
+@tool(name="add_label")
+def add_label(repo_id, number, name):
+    key = {"repo_id": repo_id, "number": number}
+    issue = store.get("github_issues", key)
+    if issue is None:
+        _not_found(f"{LABELS}#add-labels-to-an-issue")
+    label = store.get("github_labels", {"repo_id": repo_id, "name": name})
+    if label is None:
+        raise ValueError(
+            "not_modelled: POST /repos/{owner}/{repo}/issues/{issue_number}/labels "
+            "creates an unknown label with a colour the server assigns"
+        )
+    if any(
+        existing == name or (isinstance(existing, dict) and existing.get("name") == name)
+        for existing in issue["labels"]
+    ):
+        return issue
+    # Issue responses use embedded vendor label objects. repo_id is route context,
+    # not part of components/schemas/label, so do not leak the entity projection.
+    embedded_label = {field: value for field, value in label.items() if field != "repo_id"}
+    return store.update(
+        "github_issues",
+        key,
+        {"labels": [*issue["labels"], embedded_label]},
+        source={"record": "tool.add_label"},
+    )

gatewaysdk/environment/schema/connectors/github/parity.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "connector": "github",
+  "status": "subset",
+  "world_tools": ["add_label", "create_issue", "get_pull_request", "list_issues"],
+  "registration": {
+    "mode": "managed",
+    "provider": "merge",
+    "managed_tool_allowlist": ["create_issue", "get_pull_request"]
+  },
+  "surfaces": [
+    {
+      "name": "GitHub MCP server",
+      "kind": "official_hosted_mcp",
+      "auth": "OAuth or GitHub token",
+      "manifest_validation": "unauthenticated",
+      "supported_world_tools": ["create_issue", "get_pull_request", "list_issues"],
+      "limitations": [
+        "Credentialed tools/list was not available.",
+        "Official tool names and request envelopes are broader than this world.",
+        "add_label has no verified managed-provider name match."
+      ],
+      "evidence": ["https://github.com/github/github-mcp-server"]
+    },
+    {
+      "name": "Merge Agent Handler",
+      "kind": "managed_provider",
+      "auth": "Merge managed connection",
+      "manifest_validation": "public_catalog",
+      "supported_world_tools": ["create_issue", "get_pull_request"],
+      "limitations": [
+        "Only exact world-tool name matches are exposed by Gateway."
+      ],
+      "evidence": ["https://docs.merge.dev/agent-handler/overview/"]
+    }
+  ]
+}

gatewaysdk/environment/schema/connectors/github/provenance.json

@@ -0,0 +1,134 @@
+{
+  "connector": "github",
+  "shape": "base",
+  "fidelity": {
+    "label": "subset",
+    "target_label": "mimic",
+    "entity_count": 8,
+    "recursive_field_count": 1662,
+    "golden_replay": {
+      "status": "skipped",
+      "reason": "No syntheticized GitHub sandbox capture is available."
+    },
+    "sandbox_round_trip": {
+      "status": "skipped",
+      "reason": "A free test organization plus the Gateway GitHub App was not available to this reconstruction."
+    }
+  },
+  "domain_version": "3.0.0",
+  "source": [
+    {
+      "kind": "openapi",
+      "url": "https://raw.githubusercontent.com/github/rest-api-description/3cef12e8a02d612ad032473d4fb87266f2befeae/descriptions/api.github.com/api.github.com.json",
+      "version": "OpenAPI 3.0.3; info.version 1.1.4; github/rest-api-description commit 3cef12e8a02d612ad032473d4fb87266f2befeae (2026-09-04)",
+      "sha256": "531b05749a9f86c7be01330e6d89d052fd3102ff31df4e0c765d9550b11bbad8",
+      "verified_at": "2026-09-06T21:35:38Z",
+      "verification": "Fetched 12927758 bytes from the pinned raw URL and computed SHA-256.",
+      "used_for": [
+        "simple-user, private-user, public-user, webhooks_user and webhooks_user_mannequin read forms",
+        "repository and minimal-repository read forms",
+        "label, webhooks_label and label-search-result-item read forms",
+        "issue, pull-request, pull-request-simple, pull-request-review, webhooks_review, check-run and commit read forms",
+        "all recursively referenced component schemas",
+        "declared issue state/state_reason, pull-request state, author-association, check-run status/conclusion and nested enum blocks"
+      ]
+    },
+    {
+      "kind": "graphql-schema",
+      "url": "https://raw.githubusercontent.com/octokit/graphql-schema/82ff2d4780080e6929ebb95608cefa22dfa05ac7/schema.graphql",
+      "version": "octokit/graphql-schema commit 82ff2d4780080e6929ebb95608cefa22dfa05ac7",
+      "sha256": "3c62d0526d133cee53221c89de9b455ade24db78b9e7ad56d642c4c15bce2654",
+      "verified_at": "2026-09-06T21:35:38Z",
+      "verification": "Fetched 1223842 bytes from the pinned raw URL and computed SHA-256.",
+      "used_for": [
+        "PullRequestReviewState values APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED and PENDING in declared order"
+      ]
+    },
+    {
+      "kind": "docs",
+      "url": "https://docs.github.com/en/rest",
+      "version": "secondary unpinned documentation landing page",
+      "sha256": null,
+      "verified_at": null,
+      "used_for": [
+        "Existing handler error wording and documentation_url route fragments only; no entity field is sourced from this page"
+      ]
+    }
+  ],
+  "authored_by": "connector-template-author reconstruction from pinned machine-readable declarations",
+  "importer": null,
+  "scope_hash": "sha256:4e1ec679802e119d31ed5d1471b1db125f9a4e6d882e857937f0a9e4a455912a",
+  "world_sha256": "sha256:1936e3350d77b28cf331d2881a08bee8b8e1a4546ab89ee6a9a017023550370e",
+  "generated_at": "2026-09-06T22:27:40Z",
+  "coverage": {
+    "entity_components": {
+      "github_users": [
+        "simple-user",
+        "private-user",
+        "public-user",
+        "webhooks_user",
+        "webhooks_user_mannequin"
+      ],
+      "github_repositories": [
+        "repository",
+        "minimal-repository"
+      ],
+      "github_labels": [
+        "label",
+        "webhooks_label",
+        "label-search-result-item"
+      ],
+      "github_issues": [
+        "issue"
+      ],
+      "github_pull_requests": [
+        "pull-request",
+        "pull-request-simple"
+      ],
+      "github_reviews": [
+        "pull-request-review",
+        "webhooks_review"
+      ],
+      "github_check_runs": [
+        "check-run"
+      ],
+      "github_commits": [
+        "commit"
+      ]
+    },
+    "merge_policy": "For multiple response forms, recursively union properties and intersect required names. A property absent from one form remains optional; nullable remains independent of optionality.",
+    "nested_fidelity": "Embedded users, repositories, labels, milestones, teams, integrations, check suites, outputs, deployments, Git identities, trees, verification, parents, stats and files are retained rather than flattened away.",
+    "root_closure": "Entity roots reject fields outside the union of their pinned read forms plus documented containment/relationship projections. Nested objects preserve the source's additionalProperties behavior."
+  },
+  "dialect_transform": {
+    "nullable": "OpenAPI nullable is represented as type plus null or an anyOf null branch.",
+    "formats": "date-time is retained. The selected source closure contains 159 uri, 14 uri-template, 4 email and 24 int64 format occurrences that gateway-world/1 cannot express; scalar types are retained and those format annotations are omitted.",
+    "examples": "415 singular OpenAPI example annotations in the selected unique source schemas are omitted because gateway-world/1 supports examples arrays, not example.",
+    "extensions": "Five x-github-breaking-changes annotations in the selected unique source schemas are omitted because the dialect has no vendor-extension keyword.",
+    "schema_valued_additional_properties": "nullable-integration.permissions is widened to additionalProperties true because the dialect only supports boolean additionalProperties.",
+    "reserved_names": "Safe vendor root fields beginning with '_' are supported. pull-request._links and pull-request-review._links retain their declared href objects; _key, payload, and storage prefixes remain reserved."
+  },
+  "notes": [
+    "This replaces the shallow projection with the pinned REST component closure while retaining exactly eight state entities and four existing tools.",
+    "Pull-request and review _links objects are retained from the pinned OpenAPI rather than omitted for their vendor field name.",
+    "The direct repo_id/pull_number containment fields come from REST route context. Direct *_id/ref/sha/message/comment_count fields are relationship or key projections; the original nested vendor fields remain present.",
+    "Requiredness for a single read form follows that component. Requiredness for merged forms is the intersection, preventing fields from one valid endpoint form from being required on another.",
+    "github_users.type intentionally remains an unconstrained string: the webhook forms declare Bot/User/Organization/Mannequin, but simple-user, public-user and private-user do not declare a closed value block. Applying the webhook enum to all user responses would over-constrain the model.",
+    "github_issues.state uses the declared webhooks_issue enum; state_reason uses the declared issue enum including duplicate and null. github_reviews.state uses the pinned GraphQL declaration because both REST review forms expose an unconstrained string.",
+    "No fixture or golden data was added: the template layout does not copy connector-local data, and no sandbox response was available to syntheticize."
+  ],
+  "unverified": [
+    "Projection equality is not enforceable: gateway-world/1 requires primary keys to be direct and cannot assert that owner_id equals owner.id, for example. Ingestion must derive documented route-context and key projections.",
+    "github_users.login uniqueness is a service invariant but is not declared by the OpenAPI component schema.",
+    "github_repositories.full_name uniqueness and github_labels id uniqueness are not declared as JSON Schema uniqueness constraints by the OpenAPI source.",
+    "The documentation_url strings and ValueError formatting in handlers.py have not been replayed against live 404/422 responses.",
+    "create_issue still accepts the complete read entity rather than GitHub's distinct create request schema; tool behavior remains a subset of the vendor API.",
+    "No sandbox/test-organization round trip, relationship exercise, syntheticized golden replay, or production evidence capture was run."
+  ],
+  "mimic_blockers": [
+    "Provision the free test organization and Gateway GitHub App, seed synthetic records through GitHub, ingest the returned records, and audit every relationship/enum/unique constraint.",
+    "Capture and syntheticize golden responses, then reach the mimic replay threshold.",
+    "Resolve or accept the remaining compiler gaps for unsupported formats, schema-valued maps, and nested projection equality.",
+    "Model create-request tool inputs separately from complete read entities if tool parity is in scope."
+  ]
+}

gatewaysdk/environment/schema/connectors/github/scope.toml

@@ -0,0 +1,158 @@
+# Import/reconstruction scope for the GitHub base connector.
+#
+# Primary evidence is the exact github/rest-api-description commit and SHA-256
+# recorded in provenance.json. The repository importer is not implemented, so
+# world.json is a deterministic dialect transcription of the component schemas
+# and read forms below.
+
+[import]
+kind = "openapi"
+prefix = "github_"
+shape = "base"
+source_component_path = "descriptions/api.github.com/api.github.com.json"
+allowlist = [
+  "simple-user",
+  "repository",
+  "label",
+  "issue",
+  "pull-request",
+  "pull-request-review",
+  "check-run",
+  "commit",
+]
+
+[coverage]
+entity_count = 8
+recursive_field_count = 1662
+label = "subset"
+reason = "The pinned machine-readable read shapes are modelled, but no test-organization round trip or syntheticized golden replay has been run."
+
+[entities."simple-user"]
+entity = "github_users"
+primary_key = ["id"]
+unique = [["login"]]
+read_forms = ["simple-user", "private-user", "public-user", "webhooks_user", "webhooks_user_mannequin"]
+merge = "union properties recursively; intersect required fields"
+notes = "The merged type property remains open because simple-user/public-user/private-user declare an unconstrained string even though webhook user schemas declare enum blocks."
+
+[entities.repository]
+entity = "github_repositories"
+primary_key = ["id"]
+unique = [["full_name"]]
+read_forms = ["repository", "minimal-repository"]
+merge = "union properties recursively; intersect required fields"
+relationship_projections = { owner_id = "owner.id" }
+relationships = [{ fields = ["owner_id"], target = "github_users" }]
+
+[entities.label]
+entity = "github_labels"
+primary_key = ["repo_id", "name"]
+unique = [["id"]]
+read_forms = ["label", "webhooks_label", "label-search-result-item"]
+merge = "union properties recursively; intersect required fields"
+containment = { repo_id = "repository.id from route context" }
+relationships = [{ fields = ["repo_id"], target = "github_repositories" }]
+notes = "Search-only score and text_matches remain optional on ordinary label responses."
+
+[entities.issue]
+entity = "github_issues"
+primary_key = ["repo_id", "number"]
+unique = [["id"]]
+read_forms = ["issue"]
+containment = { repo_id = "repository.id from route context" }
+relationship_projections = { user_id = "user.id", assignee_id = "assignee.id" }
+enum_sources = { state = "components/schemas/webhooks_issue/properties/state", state_reason = "components/schemas/issue/properties/state_reason" }
+relationships = [
+  { fields = ["repo_id"], target = "github_repositories" },
+  { fields = ["user_id"], target = "github_users" },
+  { fields = ["assignee_id"], target = "github_users" },
+]
+notes = "labels preserves the vendor oneOf string-or-label-object item shape; it is not reduced to label names."
+
+[entities."pull-request"]
+entity = "github_pull_requests"
+primary_key = ["repo_id", "number"]
+unique = [["id"]]
+read_forms = ["pull-request", "pull-request-simple"]
+merge = "union properties recursively; intersect required fields"
+containment = { repo_id = "repository.id from route context" }
+relationship_projections = { user_id = "user.id", assignee_id = "assignee.id", merged_by_id = "merged_by.id", head_user_id = "head.user.id", base_user_id = "base.user.id", head_ref = "head.ref", head_sha = "head.sha", base_ref = "base.ref", base_sha = "base.sha" }
+relationships = [
+  { fields = ["repo_id"], target = "github_repositories" },
+  { fields = ["user_id"], target = "github_users" },
+  { fields = ["assignee_id"], target = "github_users" },
+  { fields = ["merged_by_id"], target = "github_users" },
+  { fields = ["head_user_id"], target = "github_users" },
+  { fields = ["base_user_id"], target = "github_users" },
+]
+notes = "Nested user, head, base, repository, label, milestone, team, auto_merge and stack objects remain intact; direct projections only make selected keys and relationships enforceable."
+
+[entities."pull-request-review"]
+entity = "github_reviews"
+primary_key = ["id"]
+read_forms = ["pull-request-review", "webhooks_review"]
+merge = "union properties recursively; intersect required fields"
+containment = { repo_id = "repository.id from route context", pull_number = "pull_request.number from route context" }
+relationship_projections = { user_id = "user.id" }
+enum_sources = { state = "PullRequestReviewState in the pinned GraphQL schema" }
+relationships = [
+  { fields = ["repo_id", "pull_number"], target = "github_pull_requests" },
+  { fields = ["user_id"], target = "github_users" },
+]
+
+[entities."check-run"]
+entity = "github_check_runs"
+primary_key = ["id"]
+read_forms = ["check-run"]
+containment = { repo_id = "repository.id from route context" }
+relationships = [{ fields = ["repo_id"], target = "github_repositories" }]
+
+[entities.commit]
+entity = "github_commits"
+primary_key = ["repo_id", "sha"]
+read_forms = ["commit"]
+containment = { repo_id = "repository.id from route context" }
+relationship_projections = { message = "commit.message", comment_count = "commit.comment_count", author_id = "author.id", committer_id = "committer.id" }
+relationships = [
+  { fields = ["repo_id"], target = "github_repositories" },
+  { fields = ["author_id"], target = "github_users" },
+  { fields = ["committer_id"], target = "github_users" },
+]
+notes = "The nested commit object, Git author/committer, tree, verification, parents, stats and files are preserved alongside direct relationship projections."
+
+# GitHub REST has no polymorphic lookup in these entity roots. commit.author and
+# commit.committer are declared as simple-user or empty-object; nullable direct
+# account-id projections preserve that distinction without claiming every Git
+# identity maps to a GitHub account.
+polymorphic = []
+
+[transform]
+nullable = "OpenAPI nullable is converted to a type-plus-null union or anyOf with null."
+non_date_time_formats = "uri, uri-template, email, and int64 format annotations are dropped because gateway-world/1 does not support them; underlying scalar types are preserved."
+examples = "OpenAPI example annotations are omitted because gateway-world/1 accepts examples arrays, not singular example."
+schema_additional_properties = "nullable-integration.permissions has schema-valued additionalProperties in OpenAPI and is widened to additionalProperties = true because gateway-world/1 only accepts a boolean."
+root_closure = "Entity roots are additionalProperties = false; nested objects retain the source's open/closed behavior."
+
+[compiler_limitations]
+nested_constraints = "Primary keys remain direct entity properties. Nested scalar uniqueness and relationships are supported, but the compiler cannot enforce equality between a documented direct projection and its nested source."
+uri_formats = "The compiler cannot carry GitHub's uri, uri-template, email, or int64 OpenAPI format annotations."
+schema_valued_maps = "The compiler cannot constrain values of schema-valued additionalProperties maps."
+
+[exclusions]
+"other OpenAPI components" = "The bundle intentionally has eight state entities from the connector brief; comments, milestones, teams, apps, deployments, check suites and other GitHub resources are retained when nested but are not independently keyed entities."
+"GraphQL object model" = "Only PullRequestReviewState is used. Importing the full parallel GraphQL graph would duplicate REST resources and is outside this eight-entity base scope."
+
+[sandbox]
+requirement = "Free test organization plus the Gateway GitHub App."
+status = "not provisioned or not available to this reconstruction"
+round_trip = "skipped"
+goldens = "skipped; no customer or production payloads are included"
+
+[fidelity]
+shape = "base"
+label = "subset"
+mimic_blockers = [
+  "No sandbox/test-organization round trip.",
+  "No syntheticized golden replay.",
+  "Several vendor formats and one schema-valued map constraint are outside the compiler dialect.",
+]