Skip to content

feat(sdk): include Connectivity in the stack API contract - #2012

Open
Dav-14 wants to merge 6 commits into
mainfrom
codex/stack-connectivity-sdk
Open

Dav-14 wants to merge 6 commits into
mainfrom
codex/stack-connectivity-sdk

Conversation

@Dav-14

@Dav-14 Dav-14 commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add Connectivity to the unified Stack SDK contract using the existing component composition pattern.

  • Fetch misc/connectivity-api/openapi.yaml from Connectivity main using CONNECTIVITY_VERSION and authenticated GitHub CLI access. Connectivity releases do not currently publish an OpenAPI asset.
  • Add /api/connectivity, the connectivity.v1 SDK group and the connectivity model namespace. Preserve source bearer authentication and scope descriptions, as for Ledger.
  • Qualify only Connectivity's _info operation as connectivityInfo. Without this exception Speakeasy renames the existing Ledger info to info_ledgerV3. The other 13 Connectivity operation IDs remain unchanged.
  • Remove the added composition documentation and README link. No dedicated Connectivity preparation/validation/test scripts or OpenAPI-version assertion.

Enum validation fix

Connectivity has a schema property named enum, whose value is a schema object ({"type":"array","items":{"type":"string"}}). The existing recursive filter passes this object to unique and fails:

object cannot be sorted, as it is not an array

Selecting only enum values of type array preserves the duplicate-enum check without confusing this property with an enumeration list. On the same generated contract the original filter exits 5; the corrected filter exits 0.

Evidence

  • Rebased onto 88d6ee9264fa1189bbe5584c23c2fea7be1283b5 at 8f3ef8ec6a9cbeb9411e8b6d1b6c3f1a0084fc03: all six commits are patch-equivalent. Fresh full precommit (temporary no-upload mode), baseline comparison and cd events && go test ./... passed. Independent rebase review found no new static findings.
  • Full precommit recipe passed against Connectivity main: composition, existing invariants and event generation. Verification used a temporary Justfile with --skip-upload-spec; the committed build command remains speakeasy run -s all, and registry upload was not exercised.
  • Baseline comparison: all 271 existing paths, including their operation IDs, are identical. All 891 existing component entries are identical except the appended Connectivity description on the shared bearer scheme. All 14 Connectivity operations are retained. The merged document remains OpenAPI 3.0.3; source prerequisite Connectivity feat: add nats logging callbacks and webhooks logging #493 is merged.
  • Final independent static review covers naming, preparation consistency, the operation-ID collision and removal of the documentation. It is a technical review, not human approval.
  • Unified Go SDK compilation remains unqualified: earlier generation with the official workflow failed on an empty pkg/models/shared, also reproduced with the original Stack main contract. This PR does not fix that baseline issue.

Merge Danger

Door: two-way. No server behavior or stored-data migration.

Blast Radius: SDKs. Local builds now need private Connectivity read access; anonymous builds cannot fetch that input. Release CI uses NUMARY_GITHUB_TOKEN, whose private-repository access remains unverified. Following main means rebuilding an older Stack revision may consume a newer Connectivity contract. A future authorized release exposes this private contract in public release assets and the shared SDK source. Other SDK languages and deployed routing remain unqualified. No Stack merge, tag, registry upload, SDK release or deployment was performed.

@NumaryBot NumaryBot added risk: high NumaryBot classified this pull request as high risk. bot-reviewed NumaryBot completed its review workflow for the current head. draft-reviewed NumaryBot reviewed this draft, but published no readiness signal. labels Oct 28, 2026
@Dav-14
Dav-14 marked this pull request as ready for review October 28, 2026 12:34
@NumaryBot NumaryBot added human-review-required and removed draft-reviewed NumaryBot reviewed this draft, but published no readiness signal. labels Oct 28, 2026
Comment thread Justfile Outdated
Comment thread Justfile Outdated

# Prepend API path prefix to each component spec
prepend-paths: download-specs
yq -i '.paths |= (to_entries | map(.key = "/api/connectivity" + .key) | from_entries) | (.paths[] | .. | select(has("operationId"))) |= (.operationId = "connectivity_" + .operationId | .tags = ["connectivity.v1"])' components/connectivity.openapi.yaml

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aligned the path/tag transformation with Ledger and removed the blanket operation-ID prefix in f43a918. One exception remains: Connectivity _info uses connectivityInfo. Without this, Speakeasy renames the existing Ledger info to info_ledgerV3. With the exception, all 271 existing paths, including operation IDs, remain identical and all 14 Connectivity operations are retained. Full local precommit passed without registry upload. Could you confirm this compatibility-preserving exception?

Comment thread Justfile
# Composition cleanups must remain applied when component specs change.
jq -e '.components.schemas.auth_Scope == null and .components.schemas.auth_ScopeOptions == null' releases/build/generate.json >/dev/null
jq -e '[.. | objects | select(.enum? != null) | .enum | select(length != (unique | length))] | length == 0' releases/build/generate.json >/dev/null
jq -e '[.. | objects | select(.enum? | type == "array") | .enum | select(length != (unique | length))] | length == 0' releases/build/generate.json >/dev/null

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why ?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Connectivity has a schema property named enum, whose value is the schema object {"type":"array","items":{"type":"string"}}. The old recursive filter selects that object and passes it to unique, failing with object cannot be sorted, as it is not an array (exit 5). Selecting only enum values of type array preserves the existing duplicate-value check and avoids this property-name collision; the corrected filter exits 0 on the same contract. The PR description includes the reproduction.

Comment thread docs/sdk-contract-composition.md Outdated
@Dav-14
Dav-14 force-pushed the codex/stack-connectivity-sdk branch from f43a918 to 8f3ef8e Compare October 28, 2026 13:50
@Dav-14
Dav-14 requested a review from flemzord October 28, 2026 14:21

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot-reviewed NumaryBot completed its review workflow for the current head. human-review-required risk: high NumaryBot classified this pull request as high risk.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants