Let clients adopt published SDK versions independently

.agents/skills/change-opensecret-api/SKILL.md

@@ -104,11 +104,12 @@ not one shared wire-field edit. Trace request construction, provider handoff,
 persistence, and usage in each affected path.
 
 Use the SDK source and application dependency resolutions recorded by the
-selected Maple revision. `apps/maple-research/frontend/package.json` is
-authoritative for the browser client's in-tree `file:../../../sdk` dependency.
-Research desktop, the proxy, and the GPUI prototype consume `sdk/rust` through
-versioned path dependencies in their component `Cargo.toml` files. Update SDK
-types, custom-fetch adaptation, native
+selected Maple revision. The frontend's `package.json` and `bun.lock`, and each
+Rust consumer's Cargo manifest and lockfile, select a published SDK or local
+source. Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy).
+Validate SDK source changes separately from consumers pinned to a published
+version; update only the consumers intended to adopt the changed contract.
+Update SDK types, custom-fetch adaptation, native
 transport allowlists, call sites, mocks, and fixtures only where the contract
 reaches them. Test old-client/new-server and new-client/old-server behavior.
 Prefer server-first rollout for compatible additions; use an explicit

.agents/skills/develop-maple-agent/SKILL.md

@@ -12,9 +12,12 @@ identify an arbitrary running development instance.
 
 `app/src/backend.rs` adapts the transport-neutral runtime under
 `crates/maple-agent/` to GPUI. Keep window/UI concerns in `app`, and shared
-account/session/tool policy in the runtime. The runtime consumes the existing
-local `maple-sdk` and `maple-proxy` packages; registry publication is separate
-work. Research's Tauri runtime remains independently owned.
+account/session/tool policy in the runtime. The runtime consumes the in-tree
+`maple-proxy` library and independently selects `maple-sdk` in the workspace
+manifest and lockfile. Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy):
+prefer a published pin and allow local links during active development. Keep
+the runtime and embedded proxy on one SDK source/version. Research's Tauri
+runtime remains independently owned.
 
 ## Build with the component environment
 
@@ -33,9 +36,10 @@ build and performance evidence. Root `just agent-check`, `agent-build`, and
 --no-update-lock-file` additionally validates workflow selection and security
 contracts when CI, Nix, or routing changes.
 
-Agent has its own Cargo and Nix lockfiles. Shared Rust SDK/proxy runtime
-changes must select Agent as well as the Research consumer; component-only
-changes must not unnecessarily select Research packaging. Maintain the root
+Agent has its own Cargo and Nix lockfiles. CI conservatively selects Agent for
+shared Rust SDK/proxy runtime changes even when its SDK is registry-pinned;
+passing that build does not validate unpublished SDK source. Component-only
+changes should not unnecessarily select Research packaging. Maintain the root
 selectors, their tests, and `.github/workflows/agent-ci.yml` together.
 
 Linux Nix packages use a pure source fileset rooted at the monorepo, including

.agents/skills/develop-maple-proxy/SKILL.md

@@ -14,14 +14,20 @@ The source is part of Maple but keeps distinct public package and runtime
 boundaries:
 
 - `proxy/` builds the `maple-proxy` crate and binary.
-- `proxy/Cargo.toml` consumes the in-tree OpenSecret Rust SDK at `../sdk/rust`
-  with a registry version retained for Cargo publishing.
-- desktop Maple consumes `../../proxy` and `../../sdk/rust` from
-  `apps/maple-research/frontend/src-tauri/Cargo.toml`; iOS and Android do not compile the proxy.
+- `proxy/Cargo.toml` uses a compatible `maple-sdk` registry requirement;
+  `proxy/Cargo.lock` selects the standalone binary's version. Local SDK links
+  are also supported during active development.
+- Research desktop and Maple Agent consume the in-tree proxy library and
+  choose their SDK versions independently in their own Cargo manifests/locks.
+  iOS and Android do not compile Research's proxy.
 - `apps/maple-research/frontend/src-tauri/src/proxy.rs` owns Maple's account-scoped listener,
   configuration, key storage, and lifecycle around the library. Do not move
   that application behavior into the reusable crate incidentally.
 
+Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy).
+Keep the embedded proxy and its host on the same SDK source/version; avoid
+exact-pinning the reusable library in a way that forces all hosts to upgrade.
+
 Do not commit, push, open a PR, publish, tag, release, or change live
 infrastructure unless the user authorizes that action.
 
@@ -40,8 +46,8 @@ nix develop --no-update-lock-file ./proxy -c bash -lc '
 '
 ```
 
-For Rust SDK or dependency-wiring changes, also prove the application resolves
-one local SDK and one local proxy:
+For Rust SDK or dependency-wiring changes, also prove Research resolves one
+SDK from its selected source and the in-tree proxy:
 
 ```sh
 nix develop --no-update-lock-file .#ci -c \
@@ -52,8 +58,10 @@ Root workflows own proxy Rust, daily supply-chain, non-publishing container,
 and native-release rehearsal checks. `proxy/src/**`, `proxy/Cargo.toml`, and
 unknown proxy build inputs are desktop application inputs; tests, examples,
 docs, the standalone lockfile, and container-only files do not by themselves
-route expensive Maple app builds. `sdk/rust` runtime changes affect both proxy
-checks and desktop Maple. When a new input changes either graph, update
+route expensive Maple app builds. `sdk/rust` runtime changes conservatively
+select proxy checks and desktop Maple even with a published SDK pin; verify
+the selected source when testing an SDK edit. When a new input changes either
+graph, update
 `scripts/ci/change_detection.py`, its table-driven tests, and workflow paths in
 the same change.
 

.agents/skills/develop-maple/SKILL.md

@@ -43,6 +43,10 @@ just install
 
 The flake pins Bun, Rust, and platform tooling. Use Bun for frontend dependencies; do not create npm, Yarn, or pnpm lockfiles.
 
+Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy).
+Prefer published pins; use local SDK links when developing across that boundary,
+and update only the consumers intended to adopt a new SDK version.
+
 Configure a local API without committing secrets:
 
 ```bash

.agents/skills/develop-opensecret-sdk/SKILL.md

@@ -16,9 +16,15 @@ package boundaries remain independently versioned and publishable:
 - `rust/` builds the `maple-sdk` crate (imported as `maple_sdk`) for native consumers.
 - `apps/maple-research/frontend/package.json` is authoritative for whether Maple's browser client
   consumes a published TypeScript version or the in-tree `file:../../../sdk` package.
-- desktop Maple and `proxy/` consume the in-tree Rust crate through versioned
-  path dependencies. iOS and Android do not compile those desktop-only
-  consumers.
+- Research desktop, Maple Agent, and `proxy/` select their Rust SDK through
+  their own manifests and lockfiles. iOS and Android do not compile Research's
+  desktop-only SDK/proxy consumers.
+
+Follow the [consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy).
+Prefer published pins without upgrading unrelated consumers. Local links are
+allowed during active development, including on `master`; a registry-pinned
+client build does not exercise an SDK source edit. Test an affected consumer
+with the local SDK when that integration is part of the change.
 
 Do not commit, push, open a PR, publish, or alter Maple's application dependency
 wiring unless the user authorizes that action.
@@ -89,8 +95,8 @@ cargo package --locked --manifest-path rust/Cargo.toml
 
 These commands validate package contents; they do not publish them. For Rust
 SDK changes, also run the root `scripts/ci/verify-local-rust-deps.sh` check and
-the applicable desktop/proxy validation before claiming Maple consumes the
-result.
+the applicable desktop/proxy validation. Check its selected SDK source before
+claiming Maple consumes the result.
 
 ## Publishing boundary
 

.agents/skills/release-maple/SKILL.md

@@ -112,19 +112,34 @@ newer version and unused tag, and successful required workflows for the exact
 commit. Stop on any failure; correct it through the normal reviewed process.
 Never overwrite or move a release tag.
 
-Record the proxy version and whether proxy or Rust SDK runtime inputs changed
-since `previous_tag`:
+Review the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy)
+for the clients being released. Record the frontend's selected SDK from its
+manifest/lockfile and each Rust consumer's resolved version/source using the
+policy's `cargo metadata --locked` command. Local links are allowed. If those
+clients will ship unpublished SDK changes, recommend publishing the SDK and
+pinning those consumers first; an intentional local-source release can proceed
+with the exact monorepo commit recorded. Unrelated SDK source changes do not
+require a pinned client to upgrade, and this preference adds no release gate.
+
+Record the proxy version and inspect its own runtime inputs since `previous_tag`:
 
 ```bash
 proxy_version="$(sed -n 's/^version = "\([^"]*\)"/\1/p' proxy/Cargo.toml | head -n 1)"
-git diff --name-only "$previous_tag".."$head_sha" -- proxy sdk/rust
+git diff --name-only "$previous_tag".."$head_sha" -- proxy
 printf 'proxy_version=%s\n' "$proxy_version"
 ```
 
-If runtime inputs changed without a proxy version change, stop and make the
-version decision explicit before publishing. A normal Maple Release always
-builds the checked-in proxy version, but that does not implicitly authorize a
-crates.io or GHCR publish.
+Inspect the proxy's manifest and lockfile at both revisions. Include changes
+under `sdk/rust` in its runtime comparison when either revision uses that local
+SDK. With registry dependencies at both revisions, compare the selected SDK
+versions/checksums in `proxy/Cargo.lock`; unrelated `sdk/rust` edits are not
+proxy runtime changes. The embedding app's SDK selection is separate from the
+standalone proxy's lockfile.
+
+If consumed runtime inputs changed without a proxy version change, stop and
+make the version decision explicit before publishing. A normal Maple Release
+always builds the checked-in proxy version, but that does not implicitly
+authorize a crates.io or GHCR publish.
 
 Preview GitHub's generated notes:
 

.agents/skills/review-maple-security/SKILL.md

@@ -289,10 +289,12 @@ Preserve the OpenSecret SDK's encrypted and attested transport. Do not replace `
 
 Review development and production enclave URLs and PCR/attestation allowlists together. Reject an endpoint that is not HTTPS unless it is an explicit loopback development address. Reject URL credentials and unexpected paths, queries, or fragments at the native authority boundary. Treat source-configured PCR values as policy, not proof that a live enclave currently matches; perform live attestation before making deployment claims.
 
-The SDK source is in this repository. The browser uses `file:../../../sdk`, while
-desktop Maple and `proxy/` use versioned path dependencies on `sdk/rust`.
-Review source changes and resolved application dependencies as distinct
-boundaries, and verify the local Cargo graph before claiming coverage. Do not assume
+The SDK source is in this repository, but each consumer selects a published
+version or local source through its manifest and lockfile. Follow the
+[SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy).
+Review SDK source changes and resolved application dependencies as distinct
+boundaries: a registry-pinned client does not exercise unpublished SDK edits.
+Verify the selected source and Cargo graph before claiming coverage. Do not assume
 the browser and native SDKs have identical features, request schemas, refresh
 behavior, attestation behavior, or error handling. For an OpenSecret API
 contract change, validate both clients. Keep decrypted upstream errors and

.agents/skills/review-opensecret-security/SKILL.md

@@ -109,9 +109,10 @@ Apply these OpenSecret-specific invariants:
   rollback, and access to the owning key; ordinary startup lacks user keys.
 - Shared protocol changes require coordinated review of the monorepo-root
   `sdk/` source and the dependency actually resolved by each affected Maple
-  application path. Treat `apps/maple-research/frontend/package.json` as
-  authoritative for the TypeScript client; Research desktop, the proxy, and
-  the GPUI prototype consume `sdk/rust` through versioned path dependencies.
+  application path. Its manifest and lockfile select a published SDK or local
+  source; do not treat in-tree SDK validation as proof for a consumer pinned
+  to different source. Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy)
+  when reviewing the selected versions and compatibility boundaries.
 
 Use `$change-opensecret-api` or `$change-opensecret-provider` for the detailed
 contract procedure rather than duplicating it here.

.agents/skills/validate-maple/SKILL.md

@@ -42,12 +42,13 @@ Use for pure React, TypeScript, CSS, state, and browser behavior with no native
 SDK work under `sdk/` has its own component checks. Load
 `$develop-opensecret-sdk`, run the applicable TypeScript or Rust SDK checks,
 and add the in-tree OpenSecret integration when the public protocol or
-backend compatibility changes. Maple's frontend consumes `file:../../../sdk`;
-desktop Maple and `proxy/` consume `sdk/rust` through local path dependencies.
-Rust SDK runtime changes therefore require proxy checks and desktop Maple
-coverage, while SDK tests/docs/examples and standalone lockfile changes remain
-independent. Do not run unrelated mobile packaging for desktop-only Rust SDK
-or proxy inputs.
+backend compatibility changes. Follow the [SDK consumer version policy](../../../docs/sdk-publishing.md#consumer-version-policy)
+and inspect the consumer's manifest/lockfile: a published pin and a local link
+exercise different SDK source. CI conservatively selects proxy and desktop
+checks for Rust SDK runtime changes; add local-source consumer coverage when
+claiming an unpublished SDK edit works in that client. SDK tests/docs/examples
+and standalone lockfile changes remain independent. Do not run unrelated mobile
+packaging for desktop-only Rust SDK or proxy inputs.
 
 Proxy work under `proxy/` likewise has component and application boundaries.
 Load `$develop-maple-proxy`. Proxy or Rust SDK runtime inputs route to desktop
@@ -153,7 +154,7 @@ nix develop --no-update-lock-file .#ci -c ./scripts/ci/rust.sh
 
 The lint recipe runs `cargo fmt --check` and Clippy with warnings denied. The CI script provisions Linux ONNX Runtime when needed and runs `cargo test --all-targets --locked`. Neither command launches Maple.
 
-### Proxy checks and local dependency graph
+### Proxy checks and selected dependency graph
 
 Run the proxy's CI-equivalent component checks through its pinned shell:
 
@@ -168,8 +169,8 @@ nix develop --no-update-lock-file ./proxy -c bash -lc '
 '
 ```
 
-For proxy dependency-wiring or Rust SDK runtime changes, also prove the root
-application resolves the intended in-tree crates:
+For proxy dependency-wiring or Rust SDK runtime changes, also prove Research
+resolves one SDK from its selected source and the in-tree proxy:
 
 ```bash
 nix develop --no-update-lock-file .#ci -c \

.github/workflows/proxy-publish.yml

@@ -145,14 +145,8 @@ jobs:
 
           if [ -n "${previous_proxy_version}" ]; then
             set +e
-            git diff --quiet "${previous_sha}" "${release_sha}" -- \
-                proxy/Dockerfile \
-                proxy/Cargo.toml \
-                proxy/Cargo.lock \
-                proxy/src \
-                sdk/rust/Cargo.toml \
-                sdk/rust/src \
-                sdk/rust/assets
+            python3 -I scripts/ci/proxy_runtime_diff.py \
+              "${previous_sha}" "${release_sha}"
             runtime_diff_status=$?
             set -e
             case "${runtime_diff_status}" in
@@ -438,14 +432,8 @@ jobs:
             local from_sha="$1"
             local diff_status
             set +e
-            git diff --quiet "${from_sha}" "${RELEASE_SHA}" -- \
-              proxy/Dockerfile \
-              proxy/Cargo.toml \
-              proxy/Cargo.lock \
-              proxy/src \
-              sdk/rust/Cargo.toml \
-              sdk/rust/src \
-              sdk/rust/assets
+            python3 -I scripts/ci/proxy_runtime_diff.py \
+              "${from_sha}" "${RELEASE_SHA}"
             diff_status=$?
             set -e
             case "${diff_status}" in

.github/workflows/rust-tests.yml

@@ -17,6 +17,8 @@ on:
       - "scripts/ci/_common.sh"
       - "scripts/ci/rust.sh"
       - "scripts/ci/verify-local-rust-deps.sh"
+      - "scripts/ci/verify-agent-rust-deps.py"
+      - "scripts/ci/test_agent_rust_deps.py"
       - "flake.nix"
       - "flake.lock"
   pull_request:
@@ -32,6 +34,8 @@ on:
       - "scripts/ci/_common.sh"
       - "scripts/ci/rust.sh"
       - "scripts/ci/verify-local-rust-deps.sh"
+      - "scripts/ci/verify-agent-rust-deps.py"
+      - "scripts/ci/test_agent_rust_deps.py"
       - "flake.nix"
       - "flake.lock"
 

AGENTS.md

@@ -25,6 +25,11 @@ current source and tests take precedence over historical design documents.
   `justfile`, and `repo.meta.json`: shared documentation, tooling, CI, and
   repository identity. Keep active workflows and discoverable skills at root.
 
+For SDK consumption, follow the [consumer version policy](docs/sdk-publishing.md#consumer-version-policy):
+prefer independently pinned published versions, allow local links during active
+development, and review the actual SDK source before a client release. SDK
+publication and upgrading a consumer are separate decisions.
+
 The backend import does not change TEE deployment or introduce EIF publication
 through GitHub Actions. Preserve the manual signed-PCR compatibility procedure
 in [the backend guide](services/opensecret/docs/pcr-compatibility.md) and the
@@ -87,9 +92,10 @@ Run `nix flake check --no-update-lock-file` for flake, workflow, CI-script, or
 release-configuration changes, plus the affected component checks. The
 pre-commit hook is useful but does not establish full CI parity.
 
-`scripts/ci/change_detection.py` routes expensive app packaging. TypeScript SDK
-runtime inputs affect Research frontend builds; Rust SDK and proxy runtime
-inputs affect desktop builds. Tests, docs, container-only inputs, and standalone
+`scripts/ci/change_detection.py` routes expensive app packaging. It conservatively
+selects Research frontend builds for TypeScript SDK runtime inputs and desktop
+builds for Rust SDK and proxy runtime inputs, including when a consumer uses a
+published SDK pin. Tests, docs, container-only inputs, and standalone
 component lockfiles retain their independent lanes. Update the classifier and
 its table-driven tests when the dependency graph or component layout changes.
 The backend has its own root `opensecret-ci.yml` workflow and change selector;

apps/maple-agent/Cargo.toml

@@ -20,7 +20,7 @@ once_cell = "1.18.0"
 http = "1"
 reqwest = { version = "0.13", features = ["stream"] }
 # Shared monorepo crates retain their independent package names and versions.
-maple-sdk = { version = "3.6.2", path = "../../sdk/rust" }
+maple-sdk = "=3.6.2"
 maple-proxy = { version = "0.3.4", path = "../../proxy" }
 
 [profile.dev]