From ac2cf78ffa828e1743333c897f3da9eda7f427c8 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 11 May 2026 13:47:26 +0800
Subject: [PATCH] Fix SpacetimeDB wasm dependency boundary

---
 .hermes/shared-memory/pitfalls.md                 |  8 ++++++++
 ...RKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md | 15 +++++++++++++++
 server-rs/crates/api-server/Cargo.toml            |  2 +-
 server-rs/crates/shared-contracts/Cargo.toml      |  7 ++++++-
 server-rs/crates/shared-contracts/README.md       |  1 +
 server-rs/crates/shared-contracts/src/lib.rs      |  3 ++-
 6 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md
index edb0fdf5..c2f55aeb 100644
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -107,6 +107,14 @@
 - 验证：发布前完成 schema 检查、bindings 生成、表目录更新和相关 smoke。
 - 关联：`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
 
+## SpacetimeDB publish 报 wasm-bindgen 时先查 shared-contracts feature
+
+- 现象：发布 `spacetime-module` 时报 `wasm-bindgen detected`，提示 `wasm-bindgen is only for webassembly modules that target the web platform`。
+- 原因：SpacetimeDB module 的 wasm32 构建树被间接带入原生/网页依赖；已验证链路是 `reqwest -> platform-oss -> shared-contracts -> module-runtime -> spacetime-module`，由共享契约默认启用资产 OSS 契约触发。
+- 处理：让 `shared-contracts` 的 OSS 资产契约走 `oss-contracts` feature，workspace 根依赖保持 `default-features = false`；`api-server` 这类原生后端需要资产 DTO 时在自身 `Cargo.toml` 显式启用 `features = ["oss-contracts"]`。
+- 验证：执行 `cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown` 应显示 nothing to print；再执行 `cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown`。
+- 关联：`server-rs/crates/shared-contracts/Cargo.toml`、`server-rs/crates/api-server/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。
+
 ## 本地 SpacetimeDB replica identity 不匹配
 
 - 现象：本地 standalone 启动时报 `mismatched database identity`。
diff --git a/docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md b/docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md
index 29fae1be..e3e7042b 100644
--- a/docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md
+++ b/docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md
@@ -16,6 +16,7 @@
 4. 成员 crate 只保留自身需要表达的差异，例如 `features`、`optional = true` 或 target-specific dependency。
 5. 需要关闭 default features 的依赖，应优先在 workspace 根依赖中声明；成员 crate 不再重复覆盖同一项。
 6. `module-assets` 这类有默认服务端 feature 的领域 crate，在 workspace 根内按 `default-features = false` 维护；需要服务端 OSS/HTTP 能力的 adapter crate 显式启用 `features = ["server-service"]`。
+7. 面向 SpacetimeDB WASM 的依赖链不得隐式启用原生 HTTP / OSS / Web 平台依赖；例如 `shared-contracts` 的 `assets` 模块通过 `oss-contracts` feature 暴露给 `api-server`，`spacetime-module` 路径只消费关闭默认 feature 后的纯 DTO 子集。
 
 ## 3. 本次收敛范围
 
@@ -53,3 +54,17 @@ npm.cmd run check:encoding -- docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDA
 ```
 
 若仅改 Cargo 依赖配置且未触碰 API smoke 相关代码，不强制启动 `npm run api-server`；若后续改动同时涉及 API 路由、SpacetimeDB facade 或运行时行为，仍按 `AGENTS.md` 和 DDD 文档执行后端 smoke。
+
+## 6. SpacetimeDB WASM 依赖边界
+
+`spacetime publish` 会构建 `spacetime-module` 的 `wasm32-unknown-unknown` 目标。这个目标不能包含 `wasm-bindgen`，也不应通过 DTO crate 间接拉入 `reqwest`、`web-sys` 或浏览器 WebAssembly 平台依赖。
+
+已验证的排查命令：
+
+```powershell
+cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown
+cargo tree --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown | Select-String -Pattern 'wasm-bindgen|platform-oss|reqwest'
+cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown
+```
+
+若反向树显示 `reqwest -> platform-oss -> shared-contracts -> module-* -> spacetime-module`，优先检查新增的 `shared-contracts` 或领域 crate 依赖是否忘记关闭默认 feature。原生 `api-server` 需要资产上传契约时，应在自身 `Cargo.toml` 显式启用 `shared-contracts` 的 `oss-contracts` feature，而不是让 workspace 根依赖默认启用。
diff --git a/server-rs/crates/api-server/Cargo.toml b/server-rs/crates/api-server/Cargo.toml
index acaf6c2b..9dec401d 100644
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -36,7 +36,7 @@ platform-oss = { workspace = true }
 platform-speech = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-shared-contracts = { workspace = true }
+shared-contracts = { workspace = true, features = ["oss-contracts"] }
 shared-kernel = { workspace = true }
 shared-logging = { workspace = true }
 spacetime-client = { workspace = true }
diff --git a/server-rs/crates/shared-contracts/Cargo.toml b/server-rs/crates/shared-contracts/Cargo.toml
index df973184..dabc1f73 100644
--- a/server-rs/crates/shared-contracts/Cargo.toml
+++ b/server-rs/crates/shared-contracts/Cargo.toml
@@ -4,7 +4,12 @@ edition.workspace = true
 version.workspace = true
 license.workspace = true
 
+[features]
+# 默认给 api-server 等原生后端保留资产上传契约；SpacetimeDB WASM 路径通过 workspace 依赖关闭默认 feature。
+default = ["oss-contracts"]
+oss-contracts = ["dep:platform-oss"]
+
 [dependencies]
-platform-oss = { workspace = true }
+platform-oss = { workspace = true, optional = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/server-rs/crates/shared-contracts/README.md b/server-rs/crates/shared-contracts/README.md
index e6c1937d..ce9bfcb0 100644
--- a/server-rs/crates/shared-contracts/README.md
+++ b/server-rs/crates/shared-contracts/README.md
@@ -94,3 +94,4 @@
 1. `shared-contracts` 只放协议类型与兼容结构，不承接业务规则、供应商适配或状态写入逻辑。
 2. 各模块 crate 对外暴露的协议优先复用这里的共享定义，避免重复散落。
 3. 前端兼容契约一旦进入本 crate，就必须与任务清单和基线文档同步维护。
+4. `assets` 模块依赖 `platform-oss` 的稳定返回类型，默认通过 `oss-contracts` feature 给 `api-server` 使用；SpacetimeDB WASM 构建链路必须通过 workspace 依赖关闭默认 feature，避免把 `platform-oss` / `reqwest` / `wasm-bindgen` 带进 `spacetime-module`。
diff --git a/server-rs/crates/shared-contracts/src/lib.rs b/server-rs/crates/shared-contracts/src/lib.rs
index 30613c10..5b99fe3c 100644
--- a/server-rs/crates/shared-contracts/src/lib.rs
+++ b/server-rs/crates/shared-contracts/src/lib.rs
@@ -1,13 +1,14 @@
 pub mod admin;
 pub mod ai;
 pub mod api;
+#[cfg(feature = "oss-contracts")]
 pub mod assets;
 pub mod auth;
 pub mod big_fish;
 pub mod big_fish_works;
 pub mod creation_agent_document_input;
-pub mod creative_agent;
 pub mod creation_entry_config;
+pub mod creative_agent;
 pub mod hyper3d;
 pub mod llm;
 pub mod match3d_agent;