refactor(adapter): one IoBinding per biz and no version markers in IDs or tool formats - #172
Merged
Merged
Conversation
A biz now identifies one external contract. Registering a second binding for the same biz_name is a registry conflict, so SDK init fails closed (-6). This replaces the cross-binding contract comparison (CheckBizContract, ValidateBizContract and the BIZ_IO_CONTRACT_MISMATCH preflight diagnostic), which only existed to let several bindings share one biz. The documented release policy contradicted that check: it asked for a new versioned binding under the same biz on incompatible changes, which the check rejected. CONTRIBUTING now says incompatible changes after release are made in place and shipped in a new SDK release, and a new biz is added only when both contracts must coexist. Tests that attached extra bindings to production bizs now use dedicated test bizs or replace the binding. The duplicate unselected-binding audit test is removed; the equivalent-carrier test goes with the feature. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With one binding per biz, binding_id only repeated the biz name with a fixed ".operator.v1" suffix. IoBindingDefinition loses binding_id and the registry is keyed by biz_name: Pipeline deployment.io.io_binding and the CLI --io-binding flag now take the biz name, and a duplicate biz registration is the same conflict as before. Converter IDs drop the ".operator.v1" suffix (text.plain.operator.v1 -> text.plain). Catalog io_bindings and validate-io no longer report binding_id; Studio selects bindings by biz_name. All Pipeline configs, Demo fixtures, tests and docs are updated in place (pre-release, no aliases). The naming table drops the binding_id row. OperatorSafetyTest's unknown/missing binding cases used a long-removed .conf format and failed for that reason only; they now use a valid .conf with a passing control case, and the obsolete cabi-name checks are removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The project is pre-release and has a single format for each developer tool document, so the version fields and their checks only added ceremony: every format change required bumping a number and updating the readers that enforced it. Removed from alg_pipeline_tool envelopes, Catalog (was 4), validation reports and remediation, edit requests/responses (a request that still sends schema_version is rejected as an unknown field), Pipeline Studio endpoints and web checks, Demo profiles (was 2) and result files, dev_recipe and verify_selection reports, effects specs, asset manifests and acceptance evidence. Tests that only checked version numbers or rejected old wrappers are removed or now check generic unknown fields. The kiteLLM run config keeps its schema_version: the file is passed unchanged to the pinned third-party runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Model instance IDs in Pipeline configs, Demo fixtures, the asset manifest, docs and tests lose their version suffixes (embed_model_v1 and embed_model_v2 -> embed_model, llm_model_v1 -> llm_model, and so on); no Pipeline used two of them, so the shorter names stay unique per file. Test-only names follow (new_domain, other_biz, test_prompt). Pipeline Studio's HTTP endpoints move from /api/v1/... to /api/...; the server and web client ship together, so no version prefix is needed. Left as is: the external bge_base_zh_v1.5 model file name, CI cache-key salts, and the legacy-name denylist in the docs drift gate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The documented release policy contradicted the registry. CONTRIBUTING said an incompatible external change after release adds a new versioned IoBinding under the same biz (
<root>.operator.v2), butCheckBizContractrejects bindings of one biz whose external contracts differ, and the registry audit runs at SDK init, so following the policy would have failed initialization for every biz. In practice every production biz had exactly one binding, nov2existed anywhere, and the binding ID was always the biz name plus.operator.v1. The project is pre-release, so version markers on identifiers and developer-tool formats carried no information.Design, one commit per stage:
biz_nameis a registry conflict, so SDK init fails closed (-6). The cross-binding contract comparison (CheckBizContract,ValidateBizContract, deployment diagnosticBIZ_IO_CONTRACT_MISMATCH) is removed. CONTRIBUTING now says an incompatible external change after release is made in place and shipped in a new SDK release, and a new biz is added only when both contracts must be served side by side.IoBindingDefinition::binding_idis removed and the registry is keyed bybiz_name. Pipelinedeployment.io.io_bindingand--io-bindingtake the biz name ("io_binding": "keyword_match"). Converter IDs drop.operator.v1(text.plain). Catalogio_bindingsandvalidate-iono longer reportbinding_id.schema_versionis removed from developer-tool JSON:alg_pipeline_tooloutputs, Catalog, validation reports and remediation,editrequests and responses, Pipeline Studio, Demo profiles and result files,dev_recipeandverify_selectionreports, effects specs, asset manifests and acceptance evidence. Aneditrequest that still sendsschema_versionis rejected as an unknown field.embed_model_v1andembed_model_v2becomeembed_model; no Pipeline used both). Pipeline Studio's HTTP endpoints move from/api/v1/...to/api/....Contract impact: the Operator C ABI and
.confformat are unchanged. Pipeline JSON keeps its structure, butio_bindingvalues and model IDs change, and all in-repo configs and fixtures are updated with no aliases, per the pre-release rule. Tool JSON consumers loseschema_versionandbinding_id.Trade-offs: a biz can no longer switch between equivalent converters through a second binding; nothing used that, and per-deployment batch limits remain available through the host
max_frame_depth.schema_idstays as an exported, informational protocol ID. Developer tools mixed across builds now fail with missing or unknown fields instead of a version-mismatch message. Out of scope by design: the product and ABI versions, the kiteLLM run config (a third-party format passed through unchanged, so it keeps itsschema_version), external model file names, CI cache-key salts, and the docs-drift legacy-name denylist.Tests: suites that attached extra bindings to production bizs now use dedicated test bizs or replace the binding. The equivalent-carrier test, a duplicate unselected-binding audit test, the catalog and remediation version checks, and the old-wrapper rejection cases are removed; unknown-field rejection keeps generic coverage.
OperatorSafetyTest's unknown and missing binding cases previously wrote a long-removed.confformat and failed for that reason alone. They now use a valid.confwith a passing control case.Validation: each commit passed the canonical local gate (103/103 CTest tests), and the delivery script reruns it before push. The full adapter test binary also passes in a single process (247 tests), which checks that test-registered bizs and bindings do not leak conflicts. Browser workflows were skipped because STUDIO_PLAYWRIGHT_MODULE is unset, so the Studio page changes (binding selector by
biz_name, the removed "Binding ID" row, the/apipaths) are covered by server and unit tests only. Real-model, sanitizer and target-hardware acceptance were not run locally.🤖 Generated with Claude Code