mindspace: version runtime contracts and audit packages

docs/103-runtime-topology.md

@@ -68,6 +68,11 @@ not be reused.
 
 `/Users/john/MindSpace` is the production MindSpace service root. Do not treat `/Users/john/Project/Memind/MindSpace` as the canonical MindSpace service root after the split.
 
+`/health` and `/mindspace/v1/contract` expose the MindSpace service contract
+version and build metadata. Production release scripts must reject a service
+whose contract version is stale, whose required authority bindings are missing,
+or whose `gitSha` does not match the runtime artifact manifest.
+
 ## goosed
 
 103 goosed runs in Colima/Docker, not as native launchd processes.

docs/local-dev.md

@@ -133,6 +133,18 @@ runtime artifact。它会读取本机配置的开发数据库并创建唯一的
 `split-service-smoke-*` session/package 记录，退出时会清理对应
 package/artifact，并把临时文件根删除。
 
+remote adapter 会在 Portal 启动时校验 `/mindspace/v1/contract` 的
+`contractVersion`、required capabilities 与关键 binding。如果本机
+`8082` 仍是旧 MindSpace runtime，Portal 会 fail-fast，而不是等到
+页面交付时才出现 `Unknown binding`。
+
+排查 package / artifact / public URL 链路：
+
+```bash
+npm run audit:conversation-packages -- --limit 100
+npm run trace:mindspace-artifact -- --public-url http://127.0.0.1:5173/MindSpace/<owner>/public/page.html
+```
+
 启动后 Portal 日志应出现：`[Portal] Runtime profile: MEMIND_RUNTIME_PROFILE=local, MINDSPACE_SERVER_ADAPTER=local, ...`
 
 **禁止：** 把 103 生产 `.env`、RDS 连接串、`MINDSPACE_REMOTE_AUTH_TOKEN` 生产值复制进本机 Git 仓库。

docs/mindspace-seamless-migration-runbook.md

@@ -47,6 +47,9 @@ Phase A is complete when:
 - Shared adapter contract
 - Local and remote adapter selection
 - Remote transport with auth token, timeout, and configurable operation path
+- Remote contract fail-fast: Portal rejects a standalone MindSpace service
+  whose `/mindspace/v1/contract` is below the required contract version or
+  missing required authority bindings
 - Remote mode skips Memind-side generated-page workspace sync; background jobs stay on the standalone MindSpace runtime
 
 ### Standalone MindSpace service
@@ -57,7 +60,9 @@ Path:
 Responsibilities:
 - bootstrap DB-backed local MindSpace services
 - expose `POST /mindspace/v1/adapter/:binding/:method`
-- expose `/health` and `/mindspace/v1/contract`
+- expose `/health` and `/mindspace/v1/contract`; both include the service
+  contract version, and `/contract` also includes required capabilities,
+  bindings, `buildId`, `gitSha`, and `builtAt`
 - manage publication cleanup
 - manage optional workspace maintenance
 - manage optional agent worker
@@ -147,6 +152,19 @@ The smoke uses the configured local development database to create a unique
 `split-service-smoke-*` session/package and removes those package/artifact
 rows plus its temporary filesystem root before exit.
 
+Contract and artifact diagnostics:
+
+```bash
+npm run audit:conversation-packages -- --limit 100
+npm run trace:mindspace-artifact -- --package-id cp_20260727_16
+npm run trace:mindspace-artifact -- --public-url http://127.0.0.1:5173/MindSpace/<owner>/public/page.html
+```
+
+`audit:conversation-packages -- --repair` is intentionally narrow: it only
+inserts missing `public_html` artifact records when a `generated_file`
+artifact already points to a `public/*.html` `h5_assets` row. It does not
+rewrite physical files or change publication status.
+
 Current verified local user:
 - `1c99b83b-0454-474f-a5d2-129d34506a32`