Skip to content

docs(contract-types,ffi): converge Gate comments with the published Root ABI - #2

Merged
Go1c merged 1 commit into
mainfrom
docs/converge-abi-gate-facts
Aug 28, 2026
Merged

docs(contract-types,ffi): converge Gate comments with the published Root ABI#2
Go1c merged 1 commit into
mainfrom
docs/converge-abi-gate-facts

Conversation

@Go1c

@Go1c Go1c commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

背景

架构源已发布 ADR-040 Root ABI bundle(origin/main:packages/abi/),且 packages/index.jsonrootAbi.consumers 现已登记本仓(与 LumioCoreEngine 并列)。

本仓有 6 处陈述仍写着「未发布 C Header」——现在是事实错误,会误导下一个读这些 seam 的人。本轮 RM-00002 对账里已经发生过一次同类事故:一份跨仓消息因为编号没加仓限定,让对方去找了一个不存在的 ADR。

改了什么(只改陈述,不绑定、不誊抄任何已发布数值)

  • contract-types/generated.rslib.rs:bundle 已发布,本仓是其登记消费方、直接绑定 C Header;有意不消费 Rust/C# 生成包。绑定本身仍未落地。
  • contract-types/layout.rs:写出表为空的真实原因。bundle 只认证了一个 layoutProfileIdlinux-x86_64-glibc),无条件誊抄其尺寸等于在 darwin / windows 上断言架构源未认证的布局——与手写公共数值是同一条红线。等其余 target profile 发布,或等这个 gate 做成按 target 门控。
  • native-ffi/exports.rs:Header 存在,但其入口符号归 CoreEngine root-abi,不归本仓(ADR 0001)。provider 符号表仍未发布。
  • generated_layout_matches_manifest:断言消息改为陈述真实约束(只有一个已认证 layout profile),不再说「Header 未发布」。

仍然成立的陈述一律未动:ErrorCode 数值、Operation ids、diagnostics RecordPort 对本仓需求仍未发布。

一处值得记的过程事实

写这份注释的第一稿里,我把 Root API 符号名直接拼进了 exports.rs 的文档注释,被本仓自己的源码文本守卫当场拒绝

thread 'exports::tests::c_smoke_invalid_handle_returns_stable_code' panicked at
crates/lumio-native-ffi/src/exports.rs:71:9:
exports.rs must not mention the Root API symbol

守卫是对的,也设计得干净(它自己用 concat! 拆开字符串避免自触发)。现改为间接指代,守卫未做任何改动

验证证据

命令 退出码
cargo fmt --all -- --check 0
cargo clippy --workspace --all-targets -- -D warnings 0
cargo clippy --workspace --all-targets --all-features -- -D warnings 0
cargo build --workspace --benches 0
cargo test --workspace 0(90 passed / 0 failed
cargo test --workspace --all-features 0
cargo test --workspace --no-default-features 0
cargo xtask check-dep-dag / dump-symbols / check-baseline 0
node .spec/tools/spec-lint.mjs + node --test .spec/tools/spec-lint.test.mjs 0

两条相关守卫实测通过:exports::tests::c_smoke_invalid_handle_returns_stable_code ... oksymbol_guard::tests::root_symbol_is_absent ... ok

边界

  • 纯注释 + 1 条断言消息;无逻辑、无 API、无行为变更。
  • 未绑定任何 ABI 值,未新增依赖,Cargo.lock 未动。
  • 不夹带:仍然成立的「未发布」陈述一处未改。

🤖 Generated with Claude Code

…oot ABI

The architecture source published the ADR-040 Root ABI bundle
(`origin/main:packages/abi/`), and `packages/index.json` now registers this
repository in `rootAbi.consumers` alongside LumioCoreEngine. Six statements in
this workspace still claimed no C Header exists, which is now false and would
mislead the next agent reading these seams.

Corrected, without binding anything and without transcribing any published
value:

- contract-types `generated.rs` / `lib.rs`: the bundle is published and this
  repo is a registered consumer of it, binding its C Header directly; it is
  deliberately NOT a consumer of the Rust/C# generated packages. Binding itself
  is still pending.
- contract-types `layout.rs`: state the real reason the table stays empty. The
  bundle certifies exactly one `layoutProfileId` (`linux-x86_64-glibc`), so
  transcribing its sizes unconditionally would assert layouts on darwin and
  windows that the architecture source has not certified — the same red line as
  inventing them. Binding waits for the remaining target profiles or for a
  target-gated table.
- native-ffi `exports.rs`: the Header exists, but its entry symbol belongs to
  CoreEngine root-abi, not here (ADR 0001). The provider symbol list is still
  unpublished.
- `generated_layout_matches_manifest`: assertion message now names the real
  constraint (one certified layout profile) instead of "Header unpublished".

Statements that are still true are left alone: ErrorCode values, Operation ids
and the diagnostics RecordPort remain unpublished for this repository's needs.

Comment-only plus one assertion message; no logic, no API and no behaviour
change. While writing this, the source-text guard in `exports.rs` correctly
rejected a first draft that spelled the Root API symbol — the comment now
refers to it indirectly and the guard is untouched.

Verified at this commit:
  cargo fmt --all -- --check                                            exit 0
  cargo clippy --workspace --all-targets -- -D warnings                 exit 0
  cargo clippy --workspace --all-targets --all-features -- -D warnings  exit 0
  cargo build --workspace --benches                                     exit 0
  cargo test --workspace                                exit 0  90 passed/0 failed
  cargo test --workspace --all-features                                 exit 0
  cargo test --workspace --no-default-features                          exit 0
  cargo xtask check-dep-dag / dump-symbols / check-baseline             exit 0
  node .spec/tools/spec-lint.mjs && node --test spec-lint.test.mjs      exit 0
  exports::tests::c_smoke_invalid_handle_returns_stable_code ... ok
  symbol_guard::tests::root_symbol_is_absent ... ok

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Go1c
Go1c merged commit c180bdd into main Aug 28, 2026
2 checks passed
@Go1c
Go1c deleted the docs/converge-abi-gate-facts branch August 28, 2026 12:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant