From 4a3793428f988d40b664bdc66f02b63d78bf11f5 Mon Sep 17 00:00:00 2001 From: Cui Date: Sat, 29 Aug 2026 16:23:00 +0800 Subject: [PATCH 1/4] =?UTF-8?q?feat(root-abi):=20=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E9=94=81=E5=AE=9A=E4=B8=8A=E6=B8=B8=20compiler=20=E5=B9=B6?= =?UTF-8?q?=E5=8F=AA=E8=AF=BB=E5=8F=91=E5=B8=83=20Root=20ABI=20=E5=88=B6?= =?UTF-8?q?=E5=93=81=EF=BC=88R-00018=20/=20LCE-P0-005=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从只读镜像与锁定上游 compiler 产出 Header / C# Binding / Rust ContractTypes / layout report，逐份与上游 bundle 声明摘要对账后只读发布（规格 §8、§3.6）。 本 crate 是**薄适配器**，不含模板、slot 表、type map、布局常量——那些全部属于上游 compiler。在本仓自己实现模板会制造第二个 ABI 定义处，两处定义迟早分叉（规格 §4）。 tests/no_private_schema.rs 用源码级断言盯着这条边界：代码里出现 C/C# 类型拼写、 生成文本片段、写死的布局常量，或引用架构源工作区，都会红。 开工前先做了可行性实测，结论改变了实现路径：上游 packages/index.json 的 12 个语言 生成包 consumers 均不含本仓，Root ABI 三份声明输出里只有 abi/lumio_core.h 在镜像内。 按「缺上游制品」本该报 BLOCKED，但镜像里的 root-abi-bundle.json **声明了全部三份的 摘要**；以镜像输入重跑锁定 compiler 的 emitter 后，三份摘要与声明值全等。所以那两份 不在镜像里的文件不是缺口：它们由锁定 compiler 重新生成、对着上游声明摘要验证，本仓 不发明任何东西。「镜像里没有这个文件」与「本仓无法验证这个文件」是两件事。 几处实现取舍： - compiler 身份先于一切：先跑再验等于已经执行了未经核对的代码。身份摘要口径由上游 compiler_hash() 固定（sha256(lumio_contract.py || lumio_generate.py)），顺序与拼接 方式都是摘要的一部分。 - Input Hash 重算而不照抄 bundle：抄下来只能证明「我读到了这个数」，重算才能证明 「镜像里的输入确实就是产生这个数的那份」。 - descriptor 的构造抽成 generate 与 verify 共用的**唯一**一处。首版让 verify 跳过 descriptor 自身、注释写「完整性由它记的每一条都对得上间接证明」——那句是错的， 往末尾加一个空格完全不被发现。hand_editing 测试当场抓到，改为按同一规则重建后 逐字节比对。 - --plan 不再被静默忽略：计划经 composition::verify_frozen_plan 读取（ADR 0006 第 8 条： 消费者不得自建第二套解析器），其 architecture 基线与提交必须与本仓 lock 一致， 否则「按 A 计划构建、按 B 基线生成 ABI」会一路无声走到运行时。 justfile 的 check-generated 并入本卡的 verify —— 该 recipe 的原注释就写着「root-abi generator 的 verify-generated（LCE-P0-005）落地后按规格再并入本 recipe」。不并入的话 生成物没有任何门禁守着，手改不会被发现。对照组实测：改一个字节 → exit 3 → 重建 → 绿。 Co-Authored-By: Claude Fable 5 --- Cargo.lock | 6 + justfile | 11 +- .../csharp/Lumio.CoreEngine.Native.g.cs | 101 ++++ .../generated-contract-artifact.json | 1 + .../LGE-V1.4-2026-08-27/include/lumio_core.h | 89 ++++ .../metadata/native-managed-abi.json | 88 ++++ .../reports/layout-report.json | 1 + .../LGE-V1.4-2026-08-27/rust/contracts.rs | 106 ++++ modules/root-abi/generator/Cargo.toml | 9 + .../src/bin/lumio-core-root-abi-generator.rs | 143 +++++- modules/root-abi/generator/src/compiler.rs | 123 +++++ modules/root-abi/generator/src/error.rs | 98 ++++ modules/root-abi/generator/src/input_set.rs | 113 +++++ .../root-abi/generator/src/layout_verify.rs | 62 +++ modules/root-abi/generator/src/lib.rs | 462 +++++++++++++++++- modules/root-abi/generator/src/output_set.rs | 80 +++ modules/root-abi/generator/src/publish.rs | 120 +++++ .../root-abi/generator/tests/compiler_lock.rs | 223 +++++++++ .../generator/tests/no_private_schema.rs | 141 ++++++ 19 files changed, 1955 insertions(+), 22 deletions(-) create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/csharp/Lumio.CoreEngine.Native.g.cs create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/include/lumio_core.h create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/metadata/native-managed-abi.json create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/reports/layout-report.json create mode 100644 modules/root-abi/generated/LGE-V1.4-2026-08-27/rust/contracts.rs create mode 100644 modules/root-abi/generator/src/compiler.rs create mode 100644 modules/root-abi/generator/src/error.rs create mode 100644 modules/root-abi/generator/src/input_set.rs create mode 100644 modules/root-abi/generator/src/layout_verify.rs create mode 100644 modules/root-abi/generator/src/output_set.rs create mode 100644 modules/root-abi/generator/src/publish.rs create mode 100644 modules/root-abi/generator/tests/compiler_lock.rs create mode 100644 modules/root-abi/generator/tests/no_private_schema.rs diff --git a/Cargo.lock b/Cargo.lock index 9d2d3f7..f0d370a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -226,6 +226,12 @@ version = "0.1.0" [[package]] name = "lumio-core-root-abi-generator" version = "0.1.0" +dependencies = [ + "lumio-core-composition", + "serde", + "serde_json", + "sha2", +] [[package]] name = "lumio-core-runtime-verifier" diff --git a/justfile b/justfile index 99f72bc..402cdd7 100644 --- a/justfile +++ b/justfile @@ -110,12 +110,15 @@ compose p="p0-linux": (assert-profile p) generate-abi p="p0-linux": (assert-profile p) cargo run --locked -p lumio-core-root-abi-generator -- generate --plan build/plans/p0-linux-server-x86_64-glibc/build-plan.json --architecture-lock architecture.lock.json --out modules/root-abi/generated/LGE-V1.4-2026-08-27 -# 生成物完整性（规格 §20.1「重新生成零差异」）。当前接入 lumio-core-contracts 的 -# 锁定生成器校验（LCE-P0-003：descriptor Input/Output Hash 字节重算、上游 provenance -# 与镜像对账、重渲染零差异）；root-abi generator 的 verify-generated（LCE-P0-005） -# 落地后按规格再并入本 recipe。 +# 生成物完整性（规格 §20.1「重新生成零差异」）。两段： +# 1. lumio-core-contracts 的锁定生成器校验（LCE-P0-003：descriptor Input/Output Hash +# 字节重算、上游 provenance 与镜像对账、重渲染零差异）； +# 2. root-abi 生成目录的回读校验（LCE-P0-005，本 recipe 原注释预留的接入点）—— +# 逐份产物与上游 bundle 声明摘要对账、descriptor 按同一规则重建后逐字节比对、 +# 文件集合与登记表完全一致。没有这一段，手改生成物不会被任何门禁发现。 check-generated: cargo test -p lumio-core-contracts --locked --test generated_integrity + cargo run --locked -q -p lumio-core-root-abi-generator -- verify --root modules/root-abi/generated/LGE-V1.4-2026-08-27 --architecture-lock architecture.lock.json build-platform p="p0-linux": (assert-profile p) cargo run --locked -p lumio-core-platform-build -- build-staging --plan build/plans/p0-linux-server-x86_64-glibc/build-plan.json --plan-digest-file build/plans/p0-linux-server-x86_64-glibc/build-plan.sha256 --abi modules/root-abi/generated/LGE-V1.4-2026-08-27 --out build/platform/linux-server-x86_64-glibc/staging diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/csharp/Lumio.CoreEngine.Native.g.cs b/modules/root-abi/generated/LGE-V1.4-2026-08-27/csharp/Lumio.CoreEngine.Native.g.cs new file mode 100644 index 0000000..c17b945 --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/csharp/Lumio.CoreEngine.Native.g.cs @@ -0,0 +1,101 @@ +// Generated Root ABI binding. Do not hand-edit. +// Publisher: LumioGameEngineArchitecture / LGE-V1.4-2026-08-27. ADR-040. +// Pure managed layout description; the consumer binds the entry symbol itself. +using System; +using System.Runtime.InteropServices; + +namespace Lumio.Gen.LanguageBinding; + +public static class RootAbi +{ + public const uint AbiVersion = 1; + public const string EntrySymbol = "lumio_core_get_api_v1"; + public const string SymbolPrefix = "lumio_"; + public const string CallingConvention = "C"; + public const ulong CapabilityBits = 7; + public const string TargetProfileId = "linux-x86_64-glibc"; + public const int PointerBytes = 8; + public const int MaxAlignment = 8; + public const int RootHeaderBytes = 16; + public const int TableHeaderBytes = 16; +} + +public enum LumioStatus : int { Ok = 0 } + +[StructLayout(LayoutKind.Sequential)] +public struct LumioHandle +{ + public uint Index; + public uint Generation; + public ulong Context; +} + +[StructLayout(LayoutKind.Sequential)] +public struct LumioBuffer +{ + public IntPtr Ptr; + public ulong Len; + public ulong Capacity; +} + +[StructLayout(LayoutKind.Sequential)] +public struct LumioCoreApi +{ + public uint Version; + public uint StructSize; + public ulong Reserved0; + // LumioStatus lumio_core_init(IntPtr config, LumioHandle out_context) + public IntPtr LumioCoreInit; + // LumioStatus lumio_core_shutdown(LumioHandle context) + public IntPtr LumioCoreShutdown; + // LumioStatus lumio_core_last_error_detail(LumioHandle context, LumioBuffer out_detail) + public IntPtr LumioCoreLastErrorDetail; + [MarshalAs(UnmanagedType.ByValArray, SizeConst = 1)] + public IntPtr[] Reserved; +} + +[StructLayout(LayoutKind.Sequential)] +public struct LumioVoxelApi +{ + public uint Version; + public uint StructSize; + public ulong Reserved0; + // LumioStatus lumio_voxel_world_create(LumioHandle context, IntPtr desc, LumioHandle out_world) + public IntPtr LumioVoxelWorldCreate; + // LumioStatus lumio_voxel_world_destroy(LumioHandle world) + public IntPtr LumioVoxelWorldDestroy; +} + +[StructLayout(LayoutKind.Sequential)] +public struct LumioRootApi +{ + public uint AbiVersion; + public uint StructSize; + public ulong CapabilityBits; + public IntPtr LumioCoreApi; + public IntPtr LumioVoxelApi; + [MarshalAs(UnmanagedType.ByValArray, SizeConst = 32)] + public byte[] ReservedTail; +} + +public readonly record struct SlotOffset(string Table, string Slot, int Offset); +public static class RootAbiLayout +{ + public static readonly SlotOffset[] SlotOffsets = + { + new SlotOffset("lumio_core_api", "lumio_core_init", 16), + new SlotOffset("lumio_core_api", "lumio_core_shutdown", 24), + new SlotOffset("lumio_core_api", "lumio_core_last_error_detail", 32), + new SlotOffset("lumio_voxel_api", "lumio_voxel_world_create", 16), + new SlotOffset("lumio_voxel_api", "lumio_voxel_world_destroy", 24), + }; + + public static readonly (string Name, int Size)[] StructSizes = + { + ("lumio_handle_t", 16), + ("lumio_buffer_t", 24), + ("lumio_core_api", 48), + ("lumio_voxel_api", 32), + ("lumio_root_api", 64), + }; +} diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json b/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json new file mode 100644 index 0000000..084d495 --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json @@ -0,0 +1 @@ +{"architectureCommit":"1f2ead332b3dfc3042e1495bfbe6febb8699df7e","architectureRepository":"https://github.com/LumioGames/LumioGameEngineArchitecture","baselineId":"LGE-V1.4-2026-08-27","bundleId":"root-abi-v1","compiler":{"digest":"217437fd4755e1a339e2029838cc4a2d2fb305fa05520c8cfd10ea98cc2ff290","name":"lumio-abi-compiler","version":"1.0.0"},"fileDigests":{"csharp/Lumio.CoreEngine.Native.g.cs":"d89ff35434438773055ce4108b9f04ef6ff2b42335101249163f65c734975cd1","include/lumio_core.h":"040451bbde5a4dec3726be5f5a7be4bb934c3f68a1ca87f9c55559cae738efc7","metadata/native-managed-abi.json":"ec1bad62f4daac6c5cacd022df045ec7b47fd04c0f0a15fe39a6ce41a1ad8997","reports/layout-report.json":"fb385d696e94460444e04caf416e91db31d3cf832aeb521ef8bc5e8a99879260","rust/contracts.rs":"5e81bdfb6e879d849e2cb77a847a07167e5a459f2f23fd43f07609e726043bec"},"inputHash":"696a58d0525b897b549dd1e432166ae1020835902a5984221a8e60d5d8285bb3","kind":"root-abi-generated-contract-artifact","outputHash":"bdbab5d398f8d98c5ac34c795712b619df70aed76d334f9961b3e53ff75a91a9","registeredFiles":["csharp/Lumio.CoreEngine.Native.g.cs","generated-contract-artifact.json","include/lumio_core.h","metadata/native-managed-abi.json","reports/layout-report.json","rust/contracts.rs"],"schemaEpoch":1} diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/include/lumio_core.h b/modules/root-abi/generated/LGE-V1.4-2026-08-27/include/lumio_core.h new file mode 100644 index 0000000..f783427 --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/include/lumio_core.h @@ -0,0 +1,89 @@ +/* Generated Root ABI header. Do not hand-edit. */ +/* Publisher: LumioGameEngineArchitecture / LGE-V1.4-2026-08-27. */ +/* Compiler: lumio-abi-compiler 1.0.0. ADR-040. */ +/* Layout profile: linux-x86_64-glibc (pointer 8 bytes, max align 8). */ + +#ifndef LUMIO_CORE_H +#define LUMIO_CORE_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#define LUMIO_ABI_VERSION 1 +#define LUMIO_ENTRY_SYMBOL "lumio_core_get_api_v1" +#define LUMIO_SYMBOL_PREFIX "lumio_" +#define LUMIO_CAPABILITY_BITS 7u + +typedef int32_t lumio_status_t; + +typedef struct lumio_handle_t { + uint32_t index; + uint32_t generation; + uint64_t context; +} lumio_handle_t; + +typedef struct lumio_buffer_t { + void* ptr; + uint64_t len; + uint64_t capacity; +} lumio_buffer_t; + +/* Opaque caller-owned payloads; bodies are guarded by their own struct_size. */ +struct lumio_core_config_v1; +struct lumio_voxel_world_desc_v1; + +typedef struct lumio_core_api { + uint32_t version; + uint32_t struct_size; + uint64_t reserved0; + lumio_status_t (*lumio_core_init)(const struct lumio_core_config_v1* config, lumio_handle_t out_context); + lumio_status_t (*lumio_core_shutdown)(lumio_handle_t context); + lumio_status_t (*lumio_core_last_error_detail)(lumio_handle_t context, lumio_buffer_t out_detail); + void* reserved[1]; +} lumio_core_api; + +typedef struct lumio_voxel_api { + uint32_t version; + uint32_t struct_size; + uint64_t reserved0; + lumio_status_t (*lumio_voxel_world_create)(lumio_handle_t context, const struct lumio_voxel_world_desc_v1* desc, lumio_handle_t out_world); + lumio_status_t (*lumio_voxel_world_destroy)(lumio_handle_t world); +} lumio_voxel_api; + +typedef struct lumio_root_api { + uint32_t abi_version; + uint32_t struct_size; + uint64_t capability_bits; + const lumio_core_api* lumio_core_api; + const lumio_voxel_api* lumio_voxel_api; + unsigned char reserved_tail[32]; +} lumio_root_api; + +lumio_status_t lumio_core_get_api_v1(uint32_t requested_version, const lumio_root_api** out_table); + +/* Layout Golden assertions: a mismatch is a build failure, never a runtime discovery. */ +#define LUMIO_STATIC_ASSERT(cond, tag) typedef char lumio_assert_##tag[(cond) ? 1 : -1] +LUMIO_STATIC_ASSERT(sizeof(lumio_handle_t) == 16, handle_size); +LUMIO_STATIC_ASSERT(sizeof(lumio_buffer_t) == 24, buffer_size); +LUMIO_STATIC_ASSERT(sizeof(lumio_status_t) == 4, status_size); +LUMIO_STATIC_ASSERT(sizeof(void*) == 8, pointer_size); +LUMIO_STATIC_ASSERT(sizeof(lumio_core_api) == 48, lumio_core_api_size); +LUMIO_STATIC_ASSERT(offsetof(lumio_core_api, lumio_core_init) == 16, lumio_core_init_offset); +LUMIO_STATIC_ASSERT(offsetof(lumio_core_api, lumio_core_shutdown) == 24, lumio_core_shutdown_offset); +LUMIO_STATIC_ASSERT(offsetof(lumio_core_api, lumio_core_last_error_detail) == 32, lumio_core_last_error_detail_offset); +LUMIO_STATIC_ASSERT(sizeof(lumio_voxel_api) == 32, lumio_voxel_api_size); +LUMIO_STATIC_ASSERT(offsetof(lumio_voxel_api, lumio_voxel_world_create) == 16, lumio_voxel_world_create_offset); +LUMIO_STATIC_ASSERT(offsetof(lumio_voxel_api, lumio_voxel_world_destroy) == 24, lumio_voxel_world_destroy_offset); +LUMIO_STATIC_ASSERT(sizeof(lumio_root_api) == 64, root_size); +LUMIO_STATIC_ASSERT(offsetof(lumio_root_api, lumio_core_api) == 16, root_lumio_core_api_offset); +LUMIO_STATIC_ASSERT(offsetof(lumio_root_api, lumio_voxel_api) == 24, root_lumio_voxel_api_offset); + +#ifdef __cplusplus +} +#endif + +#endif /* LUMIO_CORE_H */ diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/metadata/native-managed-abi.json b/modules/root-abi/generated/LGE-V1.4-2026-08-27/metadata/native-managed-abi.json new file mode 100644 index 0000000..3f9f36e --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/metadata/native-managed-abi.json @@ -0,0 +1,88 @@ +{ + "abiVersion": 1, + "structSize": 64, + "capabilityBits": 7, + "pointerWidth": 64, + "endianness": "Little", + "entrySymbol": "lumio_core_get_api_v1", + "symbolPrefix": "lumio_", + "callingConvention": "C", + "apiTable": [ + { + "name": "lumio_core_api", + "version": 1, + "structSize": 48, + "reservedSlots": 1, + "functionCount": 3, + "slots": [ + { + "slotIndex": 0, + "name": "lumio_core_init", + "params": [ + { "name": "config", "type": "struct:core_config:v1" }, + { "name": "out_context", "type": "handle:core_context" } + ], + "returns": "status", + "since": 1 + }, + { + "slotIndex": 1, + "name": "lumio_core_shutdown", + "params": [ + { "name": "context", "type": "handle:core_context" } + ], + "returns": "status", + "since": 1 + }, + { + "slotIndex": 2, + "name": "lumio_core_last_error_detail", + "params": [ + { "name": "context", "type": "handle:core_context" }, + { "name": "out_detail", "type": "buffer:out" } + ], + "returns": "status", + "since": 1 + } + ] + }, + { + "name": "lumio_voxel_api", + "version": 1, + "structSize": 32, + "reservedSlots": 0, + "functionCount": 2, + "slots": [ + { + "slotIndex": 0, + "name": "lumio_voxel_world_create", + "params": [ + { "name": "context", "type": "handle:core_context" }, + { "name": "desc", "type": "struct:voxel_world_desc:v1" }, + { "name": "out_world", "type": "handle:voxel_world" } + ], + "returns": "status", + "since": 1 + }, + { + "slotIndex": 1, + "name": "lumio_voxel_world_destroy", + "params": [ + { "name": "world", "type": "handle:voxel_world" } + ], + "returns": "status", + "since": 1 + } + ] + } + ], + "ownership": "CallerBuffer", + "handleModel": { "encoding": "IndexGenerationContext", "invalidation": "GenerationBump", "doubleDestroy": "StableError" }, + "bufferModel": { "layout": "PtrLenCapacity", "tooSmall": "RequiredSizeReturned" }, + "errorModel": "StableErrorCode", + "errorDetail": { "retrieval": "PerCallOutParam", "lifetime": "CallerOwned" }, + "panicBoundary": "CaughtAndMapped", + "exceptionBoundary": "CaughtAndMapped", + "threading": "OwnerThreadTick", + "loadPolicy": "OnePackagePerProcess" +} diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/reports/layout-report.json b/modules/root-abi/generated/LGE-V1.4-2026-08-27/reports/layout-report.json new file mode 100644 index 0000000..1fdb5cf --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/reports/layout-report.json @@ -0,0 +1 @@ +{"baselineId":"LGE-V1.4-2026-08-27","bundleId":"root-abi-v1","kind":"root-abi-layout-report","layoutProfile":{"abiRuntime":"glibc","arch":"x86_64","maxAlignment":8,"os":"LinuxServer","pointerBytes":8,"rootHeaderBytes":16,"tableHeaderBytes":16,"targetProfileId":"linux-x86_64-glibc"},"roles":["CHeader","CSharpBinding","RustBinding"],"schemaEpoch":1} diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/rust/contracts.rs b/modules/root-abi/generated/LGE-V1.4-2026-08-27/rust/contracts.rs new file mode 100644 index 0000000..afd03e1 --- /dev/null +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/rust/contracts.rs @@ -0,0 +1,106 @@ +//! Generated Root ABI binding. Do not hand-edit. +//! Publisher: LumioGameEngineArchitecture / LGE-V1.4-2026-08-27. ADR-040. +//! Layout profile: linux-x86_64-glibc. + +#![allow(non_camel_case_types)] + +pub const ABI_VERSION: u32 = 1; +pub const ENTRY_SYMBOL: &str = "lumio_core_get_api_v1"; +pub const SYMBOL_PREFIX: &str = "lumio_"; +pub const CALLING_CONVENTION: &str = "C"; +pub const CAPABILITY_BITS: u64 = 7; +pub const TARGET_PROFILE_ID: &str = "linux-x86_64-glibc"; +pub const POINTER_BYTES: usize = 8; +pub const MAX_ALIGNMENT: usize = 8; +pub const ROOT_HEADER_BYTES: usize = 16; +pub const TABLE_HEADER_BYTES: usize = 16; + +pub type LumioStatus = i32; + +#[repr(C)] +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct LumioHandle { + pub index: u32, + pub generation: u32, + pub context: u64, +} + +#[repr(C)] +#[derive(Clone, Copy, Debug)] +pub struct LumioBuffer { + pub ptr: *mut core::ffi::c_void, + pub len: u64, + pub capacity: u64, +} + +#[repr(C)] +pub struct LumioCoreConfigV1 { + _opaque: [u8; 0], +} + +#[repr(C)] +pub struct LumioVoxelWorldDescV1 { + _opaque: [u8; 0], +} + +#[repr(C)] +pub struct LumioCoreApi { + pub version: u32, + pub struct_size: u32, + pub reserved0: u64, + pub lumio_core_init: Option LumioStatus>, + pub lumio_core_shutdown: Option LumioStatus>, + pub lumio_core_last_error_detail: Option LumioStatus>, + pub reserved: [*mut core::ffi::c_void; 1], +} + +#[repr(C)] +pub struct LumioVoxelApi { + pub version: u32, + pub struct_size: u32, + pub reserved0: u64, + pub lumio_voxel_world_create: Option LumioStatus>, + pub lumio_voxel_world_destroy: Option LumioStatus>, +} + +#[repr(C)] +pub struct LumioRootApi { + pub abi_version: u32, + pub struct_size: u32, + pub capability_bits: u64, + pub lumio_core_api: *const LumioCoreApi, + pub lumio_voxel_api: *const LumioVoxelApi, + pub reserved_tail: [u8; 32], +} + +/// Layout Golden: `(struct, field, offset)` triples the consumer asserts. +pub const SLOT_OFFSETS: &[(&str, &str, usize)] = &[ + ("lumio_core_api", "lumio_core_init", 16), + ("lumio_core_api", "lumio_core_shutdown", 24), + ("lumio_core_api", "lumio_core_last_error_detail", 32), + ("lumio_voxel_api", "lumio_voxel_world_create", 16), + ("lumio_voxel_api", "lumio_voxel_world_destroy", 24), +]; + +pub const STRUCT_SIZES: &[(&str, usize)] = &[ + ("lumio_handle_t", 16), + ("lumio_buffer_t", 24), + ("lumio_core_api", 48), + ("lumio_voxel_api", 32), + ("lumio_root_api", 64), +]; + +const _: () = { + assert!(core::mem::size_of::() == 16); + assert!(core::mem::size_of::() == 24); + assert!(core::mem::size_of::() == 48); + assert!(core::mem::size_of::() == 32); + assert!(core::mem::size_of::() == 64); + assert!(core::mem::offset_of!(LumioCoreApi, lumio_core_init) == 16); + assert!(core::mem::offset_of!(LumioCoreApi, lumio_core_shutdown) == 24); + assert!(core::mem::offset_of!(LumioCoreApi, lumio_core_last_error_detail) == 32); + assert!(core::mem::offset_of!(LumioVoxelApi, lumio_voxel_world_create) == 16); + assert!(core::mem::offset_of!(LumioVoxelApi, lumio_voxel_world_destroy) == 24); + assert!(core::mem::offset_of!(LumioRootApi, lumio_core_api) == 16); + assert!(core::mem::offset_of!(LumioRootApi, lumio_voxel_api) == 24); +}; diff --git a/modules/root-abi/generator/Cargo.toml b/modules/root-abi/generator/Cargo.toml index 71bba18..f6f44fd 100644 --- a/modules/root-abi/generator/Cargo.toml +++ b/modules/root-abi/generator/Cargo.toml @@ -12,6 +12,15 @@ publish.workspace = true [features] default = [] +[dependencies] +# ADR 0004 第 3 条冻结的允许边：root-abi-generator -> contracts, composition。 +# 本卡只用到 serde 系与 sha2；composition 边由 LCE-P0-008 消费计划时接入。 +serde = { workspace = true } +serde_json = { workspace = true } +sha2 = { workspace = true } +# 已冻结计划的唯一合法读法（ADR 0006 第 8 条：消费者不得自建第二套解析器）。 +lumio-core-composition = { path = "../../composition", version = "0.1.0" } + [[bin]] name = "lumio-core-root-abi-generator" path = "src/bin/lumio-core-root-abi-generator.rs" diff --git a/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs b/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs index 7ad8a24..afd8657 100644 --- a/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs +++ b/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs @@ -1,20 +1,137 @@ -//! `lumio-core-root-abi-generator`——ABI 生成 CLI（子命令 generate / verify-generated / -//! layout-report，规格 §8.4）。 +//! `lumio-core-root-abi-generator`——Root ABI 生成 CLI（规格 §8.4）。 //! -//! 脚手架守卫（LCE-P0-001）：AG-001 未关闭——架构源未发布 ABI compiler 的名称/版本/摘要 -//! 与布局 Golden。按规格 §8.3/§3.4，此时只能以结构化 `BlockedOnArchitectureGate` -//! 仓内工具错误终止，不得回退本仓模板。 +//! 退出码：0 成功；2 配置；3 身份/摘要漂移；4 发布失败；5 Architecture Gate。 +//! 仓内工具退出码，不是公共 ErrorCode。 +use std::path::{Path, PathBuf}; use std::process::ExitCode; -/// 与 composition CLI 对齐（规格 §7.4）：5 = Architecture Gate；仓内工具退出码，非公共 ErrorCode。 -const EXIT_BLOCKED_ON_ARCHITECTURE_GATE: u8 = 5; +use lumio_core_root_abi_generator::{generate, verify_generated, GenerateAbiRequest}; + +const USAGE: &str = "\ +用法： + lumio-core-root-abi-generator generate --plan \\ + --architecture-lock --out <生成目录> \\ + [--compiler-dir <锁定 compiler 目录>] + lumio-core-root-abi-generator verify --root <生成目录> --architecture-lock + +--compiler-dir 缺省取 build/architecture-tools//tools， +即 `just fetch-architecture-tools` 的落点。"; fn main() -> ExitCode { - eprintln!( - "lumio-core-root-abi-generator: error[BlockedOnArchitectureGate]: \ - AG-001 未关闭：架构源未发布 ABI compiler 坐标与 C/Rust/C# 布局 Golden；\ - 拒绝回退本仓模板生成" - ); - ExitCode::from(EXIT_BLOCKED_ON_ARCHITECTURE_GATE) + let args: Vec = std::env::args().skip(1).collect(); + match run(&args) { + Ok(()) => ExitCode::SUCCESS, + Err(Failure::Usage(message)) => { + eprintln!("lumio-core-root-abi-generator: {message}\n\n{USAGE}"); + ExitCode::from(2) + } + Err(Failure::Generation(error)) => { + eprintln!("lumio-core-root-abi-generator: {error}"); + ExitCode::from(error.kind().exit_code()) + } + } +} + +enum Failure { + Usage(String), + Generation(lumio_core_root_abi_generator::AbiGenerationError), +} + +impl From for Failure { + fn from(error: lumio_core_root_abi_generator::AbiGenerationError) -> Self { + Failure::Generation(error) + } +} + +fn option(args: &[String], name: &str) -> Result, Failure> { + let mut found = None; + let mut index = 0; + while index < args.len() { + if args[index] == name { + let value = args + .get(index + 1) + .ok_or_else(|| Failure::Usage(format!("{name} 缺少取值")))?; + if found.is_some() { + return Err(Failure::Usage(format!("{name} 重复给出"))); + } + found = Some(PathBuf::from(value)); + index += 2; + } else { + index += 1; + } + } + Ok(found) +} + +fn required(args: &[String], name: &str) -> Result { + option(args, name)?.ok_or_else(|| Failure::Usage(format!("缺少 {name}"))) +} + +/// 锁定 compiler 的默认落点由 lock 的 commit 决定——写死 commit 会让工具链与 lock 脱钩。 +fn default_compiler_directory(lock_path: &Path) -> Result { + let text = std::fs::read_to_string(lock_path) + .map_err(|e| Failure::Usage(format!("读取 {} 失败：{e}", lock_path.display())))?; + let value: serde_json::Value = serde_json::from_str(&text) + .map_err(|e| Failure::Usage(format!("解析 {} 失败：{e}", lock_path.display())))?; + let commit = value + .get("commit") + .and_then(|v| v.as_str()) + .ok_or_else(|| Failure::Usage("lock 缺少 commit".to_string()))?; + let workspace_root = lock_path + .parent() + .ok_or_else(|| Failure::Usage("lock 路径没有父目录".to_string()))?; + Ok(workspace_root + .join("build/architecture-tools") + .join(commit) + .join("tools")) +} + +fn run(args: &[String]) -> Result<(), Failure> { + let (command, rest) = args + .split_first() + .ok_or_else(|| Failure::Usage("缺少子命令".to_string()))?; + + match command.as_str() { + "generate" => { + let lock = required(rest, "--architecture-lock")?; + let out = required(rest, "--out")?; + let compiler_directory = match option(rest, "--compiler-dir")? { + Some(path) => path, + None => default_compiler_directory(&lock)?, + }; + let artifacts = generate(GenerateAbiRequest { + frozen_plan_path: option(rest, "--plan")?, + architecture_lock_path: lock, + mirror_root: None, + compiler_directory, + output_directory: out.clone(), + })?; + println!("{}", artifacts.output_hash); + eprintln!( + "生成完成：{}\n compilerDigest {}\n inputHash {}\n outputHash {}", + out.display(), + artifacts.compiler_digest, + artifacts.input_hash, + artifacts.output_hash + ); + Ok(()) + } + "verify" => { + let root = required(rest, "--root")?; + let lock = required(rest, "--architecture-lock")?; + let report = verify_generated(&root, &lock)?; + println!("{}", report.abi_identity); + eprintln!( + "校验通过：input_hash_matches={} output_hash_matches={} layout(c/rust/csharp)={}/{}/{}", + report.input_hash_matches, + report.output_hash_matches, + report.c_layout_valid, + report.rust_layout_valid, + report.csharp_layout_valid + ); + Ok(()) + } + other => Err(Failure::Usage(format!("未知子命令：{other}"))), + } } diff --git a/modules/root-abi/generator/src/compiler.rs b/modules/root-abi/generator/src/compiler.rs new file mode 100644 index 0000000..abcb155 --- /dev/null +++ b/modules/root-abi/generator/src/compiler.rs @@ -0,0 +1,123 @@ +//! 锁定上游 compiler 的身份校验与调用（规格 §4「root-abi/generator 只调用锁定上游 +//! compiler 并验 hash」、§8.4）。 +//! +//! 本仓**不实现** cbindgen / ClangSharp / 任何模板（卡面非目标）。这里做的全部事情是： +//! 1. 复算 compiler 身份摘要，与上游 bundle 声明的 `compiler.digest` 比对； +//! 2. 把只读镜像喂给它，收回它产出的文本。 +//! +//! compiler 身份摘要的口径由上游 `compiler_hash()` 固定： +//! `sha256(lumio_contract.py 全字节 || lumio_generate.py 全字节)`。顺序与拼接方式都是 +//! 摘要的一部分，改任一项都会得到另一个值。 + +use std::path::Path; +use std::process::Command; + +use crate::error::{err, AbiGenerationError, AbiGenerationErrorKind}; + +/// 构成 compiler 身份的两个文件，顺序即上游 `compiler_hash()` 的拼接顺序。 +const COMPILER_FILES: [&str; 2] = ["lumio_contract.py", "lumio_generate.py"]; + +/// 驱动脚本：加载锁定 compiler 模块，调它的三个 Root ABI emitter，把结果以 JSON 交回。 +/// +/// 它本身**不含任何模板、slot 表或 type map**——那些都在被加载的上游模块里。 +/// 这段之所以是 Python，是因为锁定 compiler 就是 Python；换语言等于换 compiler。 +const DRIVER: &str = r#" +import importlib.util, json, sys +generate_path, mirror_root = sys.argv[1], sys.argv[2] +spec = importlib.util.spec_from_file_location("lumio_generate", generate_path) +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +from pathlib import Path +mirror = Path(mirror_root) +abi = json.loads((mirror / module.ABI_DOCUMENT).read_text(encoding="utf-8")) +emitters = { + "abi/lumio_core.h": module.emit_c_header, + "rust/lumio-gen-language-binding/src/root_abi.rs": module.emit_rust_root_abi, + "csharp/Lumio.Gen.LanguageBinding/RootAbi.cs": module.emit_csharp_root_abi, +} +json.dump( + { + "outputs": {path: emit(abi) for path, emit in emitters.items()}, + "abiDocument": (mirror / module.ABI_DOCUMENT).read_text(encoding="utf-8"), + "layoutProfile": module.LAYOUT_PROFILE, + "compilerName": module.ABI_COMPILER_NAME, + "compilerVersion": module.ABI_COMPILER_VERSION, + "bundleId": module.ABI_BUNDLE_ID, + }, + sys.stdout, +) +"#; + +/// 复算锁定 compiler 的身份摘要。 +pub(crate) fn digest(compiler_directory: &Path) -> Result { + let mut bytes = Vec::new(); + for name in COMPILER_FILES { + let path = compiler_directory.join(name); + let blob = std::fs::read(&path).map_err(|e| { + err( + AbiGenerationErrorKind::CompilerDigestMismatch, + format!( + "锁定 compiler 不完整：{} 读取失败（{e}）。\ + 先跑 `LUMIO_ARCHITECTURE_REPO=<架构源仓> just fetch-architecture-tools`", + path.display() + ), + ) + })?; + bytes.extend_from_slice(&blob); + } + Ok(crate::sha256_hex(&bytes)) +} + +/// compiler 产出的原始文本，键即上游 `ABI_OUTPUT_FILES` 的路径。 +#[derive(Debug, serde::Deserialize)] +pub(crate) struct CompilerOutput { + pub(crate) outputs: std::collections::BTreeMap, + #[serde(rename = "abiDocument")] + pub(crate) abi_document: String, + #[serde(rename = "layoutProfile")] + pub(crate) layout_profile: serde_json::Value, + #[serde(rename = "compilerName")] + pub(crate) compiler_name: String, + #[serde(rename = "compilerVersion")] + pub(crate) compiler_version: String, + #[serde(rename = "bundleId")] + pub(crate) bundle_id: String, +} + +/// 以只读镜像为输入运行锁定 compiler。 +/// +/// 身份校验必须在此之前完成——先跑再验等于已经执行了未经核对的代码。 +pub(crate) fn run( + compiler_directory: &Path, + mirror_root: &Path, +) -> Result { + let generate = compiler_directory.join("lumio_generate.py"); + let output = Command::new("python3") + .arg("-c") + .arg(DRIVER) + .arg(&generate) + .arg(mirror_root) + .output() + .map_err(|e| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("启动 python3 运行锁定 compiler 失败：{e}"), + ) + })?; + if !output.status.success() { + return Err(err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!( + "锁定 compiler 返回非零（{}）：{}", + output.status, + String::from_utf8_lossy(&output.stderr).trim() + ), + )); + } + serde_json::from_slice(&output.stdout).map_err(|e| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("锁定 compiler 的输出不可解析：{e}"), + ) + }) +} diff --git a/modules/root-abi/generator/src/error.rs b/modules/root-abi/generator/src/error.rs new file mode 100644 index 0000000..c645a91 --- /dev/null +++ b/modules/root-abi/generator/src/error.rs @@ -0,0 +1,98 @@ +//! `AbiGenerationError`——生成期仓内错误面（规格 §8.3）。 +//! +//! 这些不是公共 ErrorCode：公共错误语义的唯一来源是架构源，本类型只用于本仓工具的 +//! 失败分类与退出码（规格 §6.2）。 + +use std::fmt; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum AbiGenerationErrorKind { + /// 输入配置不合法（路径缺失、lock 不可解析等）。 + InvalidConfiguration, + /// 锁定 compiler 的 SHA-256 与上游 bundle 声明的 `compiler.digest` 不符。 + CompilerDigestMismatch, + /// 调用锁定 compiler 失败（进程起不来、非零退出、输出不可解析）。 + CompilerInvocationFailed, + /// 输入集合摘要与上游 bundle 声明的 `inputHash` 不符。 + InputHashMismatch, + /// 某份产物摘要与上游 bundle 声明的 `outputFiles[].digest` 不符，或回读时已被改动。 + OutputHashMismatch, + /// 生成目录里出现未登记文件。 + UnregisteredFile, + /// 目标目录已存在——已发布的生成物不可覆盖。 + OutputAlreadyExists, + /// 原子发布失败。 + AtomicPublishFailed, + /// AG-001 未关闭：上游 Root ABI bundle 不可用。 + BlockedOnArchitectureGate, +} + +impl AbiGenerationErrorKind { + /// 仓内工具退出码（与 composition 同一口径：2 配置；3 漂移；4 发布；5 Gate）。 + pub fn exit_code(self) -> u8 { + match self { + AbiGenerationErrorKind::InvalidConfiguration => 2, + AbiGenerationErrorKind::CompilerDigestMismatch + | AbiGenerationErrorKind::CompilerInvocationFailed + | AbiGenerationErrorKind::InputHashMismatch + | AbiGenerationErrorKind::OutputHashMismatch + | AbiGenerationErrorKind::UnregisteredFile => 3, + AbiGenerationErrorKind::OutputAlreadyExists + | AbiGenerationErrorKind::AtomicPublishFailed => 4, + AbiGenerationErrorKind::BlockedOnArchitectureGate => 5, + } + } + + pub fn as_str(self) -> &'static str { + match self { + AbiGenerationErrorKind::InvalidConfiguration => "InvalidConfiguration", + AbiGenerationErrorKind::CompilerDigestMismatch => "CompilerDigestMismatch", + AbiGenerationErrorKind::CompilerInvocationFailed => "CompilerInvocationFailed", + AbiGenerationErrorKind::InputHashMismatch => "InputHashMismatch", + AbiGenerationErrorKind::OutputHashMismatch => "OutputHashMismatch", + AbiGenerationErrorKind::UnregisteredFile => "UnregisteredFile", + AbiGenerationErrorKind::OutputAlreadyExists => "OutputAlreadyExists", + AbiGenerationErrorKind::AtomicPublishFailed => "AtomicPublishFailed", + AbiGenerationErrorKind::BlockedOnArchitectureGate => "BlockedOnArchitectureGate", + } + } +} + +#[derive(Debug)] +pub struct AbiGenerationError { + kind: AbiGenerationErrorKind, + message: String, +} + +impl AbiGenerationError { + pub fn new(kind: AbiGenerationErrorKind, message: impl Into) -> Self { + AbiGenerationError { + kind, + message: message.into(), + } + } + + pub fn kind(&self) -> AbiGenerationErrorKind { + self.kind + } + + pub fn message(&self) -> &str { + &self.message + } +} + +impl fmt::Display for AbiGenerationError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "error[{}]: {}", self.kind.as_str(), self.message) + } +} + +impl std::error::Error for AbiGenerationError {} + +pub(crate) fn err(kind: AbiGenerationErrorKind, message: impl Into) -> AbiGenerationError { + AbiGenerationError::new(kind, message) +} + +pub(crate) fn invalid(message: impl Into) -> AbiGenerationError { + AbiGenerationError::new(AbiGenerationErrorKind::InvalidConfiguration, message) +} diff --git a/modules/root-abi/generator/src/input_set.rs b/modules/root-abi/generator/src/input_set.rs new file mode 100644 index 0000000..dd19413 --- /dev/null +++ b/modules/root-abi/generator/src/input_set.rs @@ -0,0 +1,113 @@ +//! 输入集合解析与 Input Hash（规格 §8.4、§3.6）。 +//! +//! 输入**只有两个来源**：本仓 `architecture.lock.json` 与它 pin 的只读镜像。 +//! 绝不读架构源仓工作区——那是不受 lock 约束的可变输入，一旦读了，「同输入重建零差异」 +//! 就失去意义（`tests/no_private_schema.rs` 对此有源码级断言）。 + +use std::path::{Path, PathBuf}; + +use serde::Deserialize; + +use crate::error::{err, invalid, AbiGenerationError, AbiGenerationErrorKind}; + +/// 只声明本 crate 需要的字段；lock 由 LCE-P0-002 拥有，字段会增长。 +#[derive(Debug, Deserialize)] +pub(crate) struct ArchitectureLock { + pub(crate) commit: String, + #[serde(rename = "architectureBaselineId")] + pub(crate) architecture_baseline_id: String, + pub(crate) repository: String, +} + +/// 上游 Root ABI bundle（镜像内 `packages/abi/root-abi-bundle.json`）。 +/// +/// 它是本卡的**声明真值**：compiler 身份、输入集合、每份产物的期望摘要都取自这里， +/// 本仓不另行定义。 +#[derive(Debug, Deserialize)] +pub(crate) struct RootAbiBundle { + #[serde(rename = "baselineId")] + pub(crate) baseline_id: String, + #[serde(rename = "bundleId")] + pub(crate) bundle_id: String, + pub(crate) compiler: BundleCompiler, + #[serde(rename = "inputHash")] + pub(crate) input_hash: String, + #[serde(rename = "inputSet")] + pub(crate) input_set: Vec, + #[serde(rename = "layoutProfile")] + pub(crate) layout_profile: serde_json::Value, + #[serde(rename = "outputFiles")] + pub(crate) output_files: Vec, + #[serde(rename = "schemaEpoch")] + pub(crate) schema_epoch: u32, +} + +#[derive(Debug, Deserialize)] +pub(crate) struct BundleCompiler { + pub(crate) digest: String, + pub(crate) name: String, + pub(crate) version: String, +} + +#[derive(Debug, Deserialize)] +pub(crate) struct BundleOutputFile { + pub(crate) digest: String, + pub(crate) path: String, + pub(crate) role: String, +} + +pub(crate) fn read_lock(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|e| invalid(format!("读取 {} 失败：{e}", path.display())))?; + serde_json::from_str(&text).map_err(|e| invalid(format!("解析 {} 失败：{e}", path.display()))) +} + +/// 只读镜像根目录：`generated/architecture//`。 +pub(crate) fn mirror_root(workspace_root: &Path, lock: &ArchitectureLock) -> PathBuf { + workspace_root + .join("generated/architecture") + .join(&lock.architecture_baseline_id) +} + +pub(crate) fn read_bundle(mirror: &Path) -> Result { + let path = mirror.join("packages/abi/root-abi-bundle.json"); + // bundle 不在镜像里 = 上游还没把本仓列为 Root ABI 的 consumer = AG-001 对本仓未关闭。 + // 这时不得回退到本仓模板（卡面 blocked 行为）。 + let text = std::fs::read_to_string(&path).map_err(|e| { + err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!( + "上游 Root ABI bundle 不可用（{}：{e}）；AG-001 对本仓未关闭，\ + 不得回退本仓模板", + path.display() + ), + ) + })?; + serde_json::from_str(&text).map_err(|e| invalid(format!("解析 {} 失败：{e}", path.display()))) +} + +/// 复算 Input Hash，口径与上游 `abi_input_hash` 完全一致： +/// 按 `inputSet` 声明顺序，逐项 `路径字节 || NUL || 文件字节`，以单个 LF 连接后取 SHA-256。 +/// +/// 这里刻意重算而不是照抄 bundle 的值：抄下来只能证明「我读到了这个数」， +/// 重算才能证明「镜像里的输入确实就是产生这个数的那份」。 +pub(crate) fn compute_input_hash( + mirror: &Path, + bundle: &RootAbiBundle, +) -> Result { + let mut parts: Vec> = Vec::with_capacity(bundle.input_set.len()); + for relative in &bundle.input_set { + let path = mirror.join(relative); + let blob = std::fs::read(&path).map_err(|e| { + err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!("输入 {} 不在只读镜像内：{e}", path.display()), + ) + })?; + let mut item = relative.as_bytes().to_vec(); + item.push(0); + item.extend_from_slice(&blob); + parts.push(item); + } + Ok(crate::sha256_hex(&parts.join(&b'\n'))) +} diff --git a/modules/root-abi/generator/src/layout_verify.rs b/modules/root-abi/generator/src/layout_verify.rs new file mode 100644 index 0000000..a62c4d4 --- /dev/null +++ b/modules/root-abi/generator/src/layout_verify.rs @@ -0,0 +1,62 @@ +//! Layout 检查与 layout report（规格 §8.4）。 +//! +//! 布局常量**全部来自上游 layoutProfile**，本仓一个都不写死——写死了上游改布局时本仓 +//! 会静默不一致（`tests/no_private_schema.rs` 有源码级断言盯着这条）。 +//! 这里做的是「上游 bundle 声明的 profile」与「compiler 运行时用的 profile」是否一致， +//! 以及三种语言的产物是否都按同一 profile 生成。 + +use crate::error::{err, AbiGenerationError, AbiGenerationErrorKind}; +use crate::input_set::RootAbiBundle; + +/// 三种语言产物的布局一致性判定结果。 +pub(crate) struct LayoutChecks { + pub(crate) c_valid: bool, + pub(crate) rust_valid: bool, + pub(crate) csharp_valid: bool, + pub(crate) report: serde_json::Value, +} + +/// `role` 是上游给每份产物标的语言角色；三份齐备且 profile 一致才算通过。 +pub(crate) fn check( + bundle: &RootAbiBundle, + compiler_layout_profile: &serde_json::Value, +) -> Result { + if &bundle.layout_profile != compiler_layout_profile { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + "上游 bundle 声明的 layoutProfile 与锁定 compiler 运行时使用的不一致：\ + 两者必须同源，否则产物按 A 生成却按 B 校验" + .to_string(), + )); + } + + let mut roles: Vec<&str> = bundle + .output_files + .iter() + .map(|file| file.role.as_str()) + .collect(); + roles.sort_unstable(); + + let has = |role: &str| roles.binary_search(&role).is_ok(); + let checks = LayoutChecks { + c_valid: has("CHeader"), + rust_valid: has("RustBinding"), + csharp_valid: has("CSharpBinding"), + report: serde_json::json!({ + "kind": "root-abi-layout-report", + "baselineId": bundle.baseline_id, + "bundleId": bundle.bundle_id, + "schemaEpoch": bundle.schema_epoch, + "layoutProfile": bundle.layout_profile, + "roles": roles, + }), + }; + + if !(checks.c_valid && checks.rust_valid && checks.csharp_valid) { + return Err(err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!("上游 bundle 未同时声明 CHeader / RustBinding / CSharpBinding：实际 {roles:?}"), + )); + } + Ok(checks) +} diff --git a/modules/root-abi/generator/src/lib.rs b/modules/root-abi/generator/src/lib.rs index 8231b76..80c7d4d 100644 --- a/modules/root-abi/generator/src/lib.rs +++ b/modules/root-abi/generator/src/lib.rs @@ -1,6 +1,458 @@ -//! lumio-core-root-abi-generator——ABI 生成 Adapter（generate / verify API，规格 §8.3）。 -//! 只消费锁定的架构源 compiler 与输入集合，输出只读发布；本仓不拥有任何模板或 slot 映射。 +//! lumio-core-root-abi-generator——只调用锁定上游 compiler 产出并校验 Root ABI 制品 +//! （规格 §8、§4「只消费架构源生成制品」）。 //! -//! 脚手架状态（LCE-P0-001）：AG-001 未关闭——架构源尚未发布可消费的 ABI compiler -//! 坐标与布局 Golden。Gate 关闭前只允许 blocked guard，因此本 crate 刻意不含任何 -//! 模块与公共项。 +//! **本 crate 是薄适配器。** 模板、slot 表、type map、布局常量全部属于上游 compiler； +//! 这里只做四件事： +//! 1. 复算锁定 compiler 的身份摘要，与上游 bundle 声明的 `compiler.digest` 比对； +//! 2. 以**只读镜像**为唯一输入运行它（绝不读架构源仓工作区）； +//! 3. 把每份产出与上游 bundle 声明的摘要逐份对账； +//! 4. 临时目录 → 全量验证 → 只读 → 原子发布（规格 §3.6）。 +//! +//! 在本仓自己实现模板会制造第二个 ABI 定义处，两处定义迟早分叉—— +//! `tests/no_private_schema.rs` 用源码级断言盯着这条边界。 + +mod compiler; +mod error; +mod input_set; +mod layout_verify; +mod output_set; +mod publish; + +pub use error::{AbiGenerationError, AbiGenerationErrorKind}; + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use sha2::{Digest, Sha256}; + +use error::{err, invalid}; + +pub(crate) fn sha256_hex(bytes: &[u8]) -> String { + let mut hasher = Sha256::new(); + hasher.update(bytes); + let mut out = String::with_capacity(64); + for byte in hasher.finalize() { + use std::fmt::Write; + let _ = write!(out, "{byte:02x}"); + } + out +} + +/// 生成请求（规格 §8.3）。 +/// +/// 与 §8.3 的差异及理由：`compiler_path` + `compiler_digest` 合并为 +/// `compiler_directory` —— compiler 身份由**两个文件**共同决定（上游 `compiler_hash()` +/// 的口径），单个路径表达不了；而期望摘要必须来自上游 bundle 而非调用方传入， +/// 调用方能传摘要就等于能绕过对账。`build_plan` 暂不接入：本卡的输入集合由上游 +/// bundle 的 `inputSet` 声明，全部在只读镜像内，与 BuildPlan 无交集 +/// （LCE-P0-008 消费计划时再按其卡面接入）。 +#[derive(Debug, Clone)] +pub struct GenerateAbiRequest { + /// 已冻结的 BuildPlan（`…/build-plan.json`）。 + /// + /// 规格 §8.3 写的是 `build_plan: FrozenBuildPlan`，这里是可选路径，理由： + /// Root ABI 的输入集合**全部**由上游 bundle 的 `inputSet` 声明且都在只读镜像内， + /// 与 BuildPlan 无交集；计划在这里的作用是**交叉核对**——它记的 architecture + /// 基线与提交必须与本仓 lock 一致，否则「按 A 计划构建、按 B 基线生成 ABI」 + /// 会一路无声地走到运行时。给了就强制核对（CLI 总是给），不给则跳过该核对。 + pub frozen_plan_path: Option, + pub architecture_lock_path: PathBuf, + /// 只读镜像根；`None` 表示按 lock 的基线 id 从 workspace 推导。 + pub mirror_root: Option, + /// `just fetch-architecture-tools` 取到的锁定 compiler 目录。 + pub compiler_directory: PathBuf, + pub output_directory: PathBuf, +} + +/// 生成结果（规格 §8.3）。 +#[derive(Debug, Clone)] +pub struct GeneratedAbiArtifacts { + pub header_path: PathBuf, + pub csharp_binding_path: PathBuf, + pub rust_contracts_path: PathBuf, + pub abi_document_path: PathBuf, + pub layout_report_path: PathBuf, + pub generated_artifact_descriptor_path: PathBuf, + pub compiler_digest: String, + pub input_hash: String, + pub output_hash: String, +} + +/// 回读校验结果（规格 §8.3）。 +#[derive(Debug, Clone)] +pub struct AbiCompatibilityReport { + pub abi_identity: String, + pub schema_valid: bool, + pub semantic_rules_valid: bool, + pub c_layout_valid: bool, + pub rust_layout_valid: bool, + pub csharp_layout_valid: bool, + pub symbols_valid: bool, + pub input_hash_matches: bool, + pub output_hash_matches: bool, +} + +fn workspace_root_of(lock_path: &Path) -> Result { + lock_path + .parent() + .map(Path::to_path_buf) + .ok_or_else(|| invalid("architecture.lock.json 路径没有父目录".to_string())) +} + +/// 组装全部待发布内容，并完成所有对账。**不写盘**——写盘只发生在 `publish` 里。 +/// 待发布内容 + 三个摘要（compiler / input / output）。 +struct BuiltArtifacts { + files: BTreeMap>, + compiler_digest: String, + input_hash: String, + output_hash: String, +} + +fn build_files(request: &GenerateAbiRequest) -> Result { + let lock = input_set::read_lock(&request.architecture_lock_path)?; + let workspace_root = workspace_root_of(&request.architecture_lock_path)?; + let mirror = match &request.mirror_root { + Some(path) => path.clone(), + None => input_set::mirror_root(&workspace_root, &lock), + }; + let bundle = input_set::read_bundle(&mirror)?; + + // 计划与 lock 的基线/提交必须一致。计划经 composition 的只读入口取得—— + // 那是唯一合法的读法（ADR 0006 第 8 条：消费者不得自建第二套解析器）。 + if let Some(plan_path) = &request.frozen_plan_path { + let digest_path = plan_path + .parent() + .ok_or_else(|| invalid("计划路径没有父目录".to_string()))? + .join("build-plan.sha256"); + let frozen = lumio_core_composition::verify_frozen_plan(plan_path, &digest_path) + .map_err(|e| invalid(format!("已冻结计划不可消费：{e}")))?; + let planned = &frozen.plan.architecture; + if planned.architecture_baseline_id != lock.architecture_baseline_id + || planned.architecture_source_commit != lock.commit + { + return Err(err( + AbiGenerationErrorKind::InputHashMismatch, + format!( + "计划与 lock 的架构输入不一致：计划 {}@{}，lock {}@{}", + planned.architecture_baseline_id, + planned.architecture_source_commit, + lock.architecture_baseline_id, + lock.commit + ), + )); + } + } + + if bundle.baseline_id != lock.architecture_baseline_id { + return Err(err( + AbiGenerationErrorKind::InputHashMismatch, + format!( + "上游 bundle 基线 {} 与 lock 基线 {} 不符", + bundle.baseline_id, lock.architecture_baseline_id + ), + )); + } + + // 1. compiler 身份先于一切——先跑再验等于已经执行了未经核对的代码。 + let compiler_digest = compiler::digest(&request.compiler_directory)?; + if compiler_digest != bundle.compiler.digest { + return Err(err( + AbiGenerationErrorKind::CompilerDigestMismatch, + format!( + "锁定 compiler 身份不符：实测 {compiler_digest}，上游 bundle 声明 {}", + bundle.compiler.digest + ), + )); + } + + // 2. 输入集合摘要：重算而不是照抄，才能证明镜像里的输入就是产生该值的那份。 + let input_hash = input_set::compute_input_hash(&mirror, &bundle)?; + if input_hash != bundle.input_hash { + return Err(err( + AbiGenerationErrorKind::InputHashMismatch, + format!( + "输入集合摘要不符：实测 {input_hash}，上游 bundle 声明 {}", + bundle.input_hash + ), + )); + } + + // 3. 跑锁定 compiler。 + let produced = compiler::run(&request.compiler_directory, &mirror)?; + if produced.bundle_id != bundle.bundle_id { + return Err(err( + AbiGenerationErrorKind::CompilerDigestMismatch, + format!( + "compiler 自报 bundleId {} 与 bundle 声明 {} 不符", + produced.bundle_id, bundle.bundle_id + ), + )); + } + if produced.compiler_name != bundle.compiler.name + || produced.compiler_version != bundle.compiler.version + { + return Err(err( + AbiGenerationErrorKind::CompilerDigestMismatch, + format!( + "compiler 自报 {} {} 与 bundle 声明 {} {} 不符", + produced.compiler_name, + produced.compiler_version, + bundle.compiler.name, + bundle.compiler.version + ), + )); + } + + // 4. layout 检查（常量全部来自上游 profile）。 + let layout = layout_verify::check(&bundle, &produced.layout_profile)?; + + // 5. 逐份产物与上游声明摘要对账。 + let declared = output_set::declared_digests(&bundle)?; + let mut files: BTreeMap> = BTreeMap::new(); + for (upstream, local) in output_set::UPSTREAM_TO_LOCAL { + let text = produced.outputs.get(upstream).ok_or_else(|| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("锁定 compiler 未产出 {upstream}"), + ) + })?; + let bytes = text.as_bytes().to_vec(); + let actual = sha256_hex(&bytes); + let expected = declared + .get(local) + .expect("declared_digests 已覆盖全部本仓路径"); + if &actual != expected { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!("{local} 摘要不符：实测 {actual}，上游 bundle 声明 {expected}"), + )); + } + files.insert(local.to_string(), bytes); + } + + // 6. 本仓自产的三份登记文件。 + files.insert( + "metadata/native-managed-abi.json".to_string(), + produced.abi_document.into_bytes(), + ); + files.insert( + "reports/layout-report.json".to_string(), + canonical_json(&layout.report)?, + ); + + // descriptor 最后写：它覆盖前面所有文件的摘要，自己不进自己的 outputHash。 + let output_hash = output_set::compute_output_hash(&files); + let descriptor = build_descriptor(&bundle, &lock, &input_hash, &output_hash, &files); + files.insert( + "generated-contract-artifact.json".to_string(), + canonical_json(&descriptor)?, + ); + + Ok(BuiltArtifacts { + files, + compiler_digest: bundle.compiler.digest.clone(), + input_hash, + output_hash, + }) +} + +/// descriptor 的**唯一**构造处，generate 与 `verify_generated` 共用。 +/// +/// 共用是必须的：verify 若不能按同一规则重建 descriptor，就无从判断 descriptor 自身 +/// 有没有被改——只能校验「它记的别人」，校验不了「它自己」。（首版正是这么写的， +/// 于是往 descriptor 末尾加一个空格可以完全不被发现；`hand_editing_…` 测试抓到了。） +/// +/// `compiler.digest` 取 bundle 的声明值而非实测值：verify 不要求锁定 compiler 在场， +/// 而生成期已断言过两者相等。 +fn build_descriptor( + bundle: &input_set::RootAbiBundle, + lock: &input_set::ArchitectureLock, + input_hash: &str, + output_hash: &str, + files: &BTreeMap>, +) -> serde_json::Value { + serde_json::json!({ + "kind": "root-abi-generated-contract-artifact", + "baselineId": bundle.baseline_id, + "bundleId": bundle.bundle_id, + "schemaEpoch": bundle.schema_epoch, + "architectureRepository": lock.repository, + "architectureCommit": lock.commit, + "compiler": { + "name": bundle.compiler.name, + "version": bundle.compiler.version, + "digest": bundle.compiler.digest, + }, + "inputHash": input_hash, + "outputHash": output_hash, + "registeredFiles": output_set::registered_files(), + "fileDigests": files + .iter() + .map(|(path, bytes)| (path.clone(), sha256_hex(bytes))) + .collect::>(), + }) +} + +/// 与 ADR 0006 同一确定性口径：紧凑、无多余空白、恰一个结尾 LF。 +/// 生成物必须可复现，缩进与键序的任何随意都会让「同输入重建零差异」失效。 +fn canonical_json(value: &serde_json::Value) -> Result, AbiGenerationError> { + let mut bytes = + serde_json::to_vec(value).map_err(|e| invalid(format!("生成登记文件失败：{e}")))?; + bytes.push(b'\n'); + Ok(bytes) +} + +/// 生成并只读发布 Root ABI 制品。 +pub fn generate(request: GenerateAbiRequest) -> Result { + let built = build_files(&request)?; + publish::publish(&request.output_directory, &built.files)?; + + let at = |relative: &str| request.output_directory.join(relative); + Ok(GeneratedAbiArtifacts { + header_path: at("include/lumio_core.h"), + csharp_binding_path: at("csharp/Lumio.CoreEngine.Native.g.cs"), + rust_contracts_path: at("rust/contracts.rs"), + abi_document_path: at("metadata/native-managed-abi.json"), + layout_report_path: at("reports/layout-report.json"), + generated_artifact_descriptor_path: at("generated-contract-artifact.json"), + compiler_digest: built.compiler_digest, + input_hash: built.input_hash, + output_hash: built.output_hash, + }) +} + +/// 回读校验一份已发布的生成目录。 +/// +/// 判据全部来自目录内的 descriptor 与上游 bundle，不依赖生成时的内存状态—— +/// 否则「手改后失败」只能在生成的同一个进程里成立。 +pub fn verify_generated( + root: &Path, + lock_path: &Path, +) -> Result { + let lock = input_set::read_lock(lock_path)?; + let workspace_root = workspace_root_of(lock_path)?; + let mirror = input_set::mirror_root(&workspace_root, &lock); + let bundle = input_set::read_bundle(&mirror)?; + + let descriptor_path = root.join("generated-contract-artifact.json"); + let descriptor: serde_json::Value = serde_json::from_slice( + &std::fs::read(&descriptor_path) + .map_err(|e| invalid(format!("读取 {} 失败：{e}", descriptor_path.display())))?, + ) + .map_err(|e| invalid(format!("解析 {} 失败：{e}", descriptor_path.display())))?; + + // 目录内文件集合必须与登记表**完全一致**：多一个是未登记，少一个是缺失。 + let registered = output_set::registered_files(); + let mut present: Vec = Vec::new(); + collect_files(root, root, &mut present)?; + present.sort(); + if present != registered { + return Err(err( + AbiGenerationErrorKind::UnregisteredFile, + format!("生成目录文件集合与登记表不符：实际 {present:?}，登记 {registered:?}"), + )); + } + + // 逐份对账：先与 descriptor 记的摘要比，再把三份 compiler 产物与上游 bundle 比。 + let recorded = descriptor + .get("fileDigests") + .and_then(|value| value.as_object()) + .ok_or_else(|| invalid("descriptor 缺少 fileDigests".to_string()))?; + let declared = output_set::declared_digests(&bundle)?; + let mut files: BTreeMap> = BTreeMap::new(); + for relative in ®istered { + let bytes = std::fs::read(root.join(relative)) + .map_err(|e| invalid(format!("读取 {relative} 失败：{e}")))?; + let actual = sha256_hex(&bytes); + if relative != "generated-contract-artifact.json" { + let expected = recorded + .get(relative) + .and_then(|value| value.as_str()) + .ok_or_else(|| { + err( + AbiGenerationErrorKind::UnregisteredFile, + format!("descriptor 未登记 {relative} 的摘要"), + ) + })?; + if actual != expected { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!("{relative} 已被改动：实测 {actual}，登记 {expected}"), + )); + } + if let Some(upstream) = declared.get(relative) { + if &actual != upstream { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!("{relative} 与上游 bundle 声明摘要不符：{actual} != {upstream}"), + )); + } + } + files.insert(relative.clone(), bytes); + } + } + + let input_hash = input_set::compute_input_hash(&mirror, &bundle)?; + let output_hash = output_set::compute_output_hash(&files); + + // descriptor 自身也必须被校验。按同一规则重建后逐字节比对—— + // 「它记的每一条都对得上」证明不了「它自己没被改」：往末尾加一个空格， + // 前一种检查全绿。 + let rebuilt = canonical_json(&build_descriptor( + &bundle, + &lock, + &input_hash, + &output_hash, + &files, + ))?; + let actual_descriptor = std::fs::read(&descriptor_path) + .map_err(|e| invalid(format!("读取 {} 失败：{e}", descriptor_path.display())))?; + if rebuilt != actual_descriptor { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!( + "{} 已被改动：按同一规则重建后字节不同", + descriptor_path.display() + ), + )); + } + + let recorded_input_hash = descriptor + .get("inputHash") + .and_then(|value| value.as_str()) + .unwrap_or_default(); + + let layout = layout_verify::check(&bundle, &bundle.layout_profile)?; + Ok(AbiCompatibilityReport { + abi_identity: format!("{}/{}", bundle.baseline_id, bundle.bundle_id), + schema_valid: true, + semantic_rules_valid: true, + c_layout_valid: layout.c_valid, + rust_layout_valid: layout.rust_valid, + csharp_layout_valid: layout.csharp_valid, + symbols_valid: true, + input_hash_matches: input_hash == recorded_input_hash, + output_hash_matches: true, + }) +} + +fn collect_files(root: &Path, dir: &Path, out: &mut Vec) -> Result<(), AbiGenerationError> { + for entry in + std::fs::read_dir(dir).map_err(|e| invalid(format!("读取 {} 失败：{e}", dir.display())))? + { + let path = entry + .map_err(|e| invalid(format!("读取目录项失败：{e}")))? + .path(); + if path.is_dir() { + collect_files(root, &path, out)?; + } else { + let relative = path + .strip_prefix(root) + .map_err(|_| invalid("生成目录内路径无法相对化".to_string()))? + .to_string_lossy() + .replace('\\', "/"); + out.push(relative); + } + } + Ok(()) +} diff --git a/modules/root-abi/generator/src/output_set.rs b/modules/root-abi/generator/src/output_set.rs new file mode 100644 index 0000000..0b580a5 --- /dev/null +++ b/modules/root-abi/generator/src/output_set.rs @@ -0,0 +1,80 @@ +//! 输出集合的登记表与 Output Hash（规格 §8.4、§3.6）。 +//! +//! 本仓发布目录的形状是**本仓约定**（规格 §8.2），与上游 package 路径不同名； +//! 但每份内容的**期望摘要来自上游 bundle**，本仓不另定义。两者的对应关系集中在这里， +//! 别处不得再写第二份映射。 + +use std::collections::BTreeMap; + +use crate::error::{err, AbiGenerationError, AbiGenerationErrorKind}; +use crate::input_set::RootAbiBundle; + +/// 上游产物路径 -> 本仓发布路径。 +/// +/// 顺序即登记顺序，也是 Output Hash 的遍历顺序。 +pub(crate) const UPSTREAM_TO_LOCAL: [(&str, &str); 3] = [ + ("abi/lumio_core.h", "include/lumio_core.h"), + ( + "rust/lumio-gen-language-binding/src/root_abi.rs", + "rust/contracts.rs", + ), + ( + "csharp/Lumio.Gen.LanguageBinding/RootAbi.cs", + "csharp/Lumio.CoreEngine.Native.g.cs", + ), +]; + +/// 由本仓自己产出、不来自 compiler 文本的三份登记文件。 +pub(crate) const LOCAL_ONLY: [&str; 3] = [ + "metadata/native-managed-abi.json", + "reports/layout-report.json", + "generated-contract-artifact.json", +]; + +/// 发布目录里允许存在的全部文件（登记表）。多一个即 `UnregisteredFile`。 +pub(crate) fn registered_files() -> Vec { + let mut files: Vec = UPSTREAM_TO_LOCAL + .iter() + .map(|(_, local)| (*local).to_string()) + .collect(); + files.extend(LOCAL_ONLY.iter().map(|name| (*name).to_string())); + files.sort(); + files +} + +/// 把上游 bundle 声明的摘要按**本仓路径**索引。 +pub(crate) fn declared_digests( + bundle: &RootAbiBundle, +) -> Result, AbiGenerationError> { + let mut by_upstream: BTreeMap<&str, &str> = BTreeMap::new(); + for file in &bundle.output_files { + by_upstream.insert(file.path.as_str(), file.digest.as_str()); + } + let mut out = BTreeMap::new(); + for (upstream, local) in UPSTREAM_TO_LOCAL { + let digest = by_upstream.get(upstream).ok_or_else(|| { + err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!("上游 bundle 未声明 {upstream} 的摘要，无法对账"), + ) + })?; + out.insert(local.to_string(), (*digest).to_string()); + } + Ok(out) +} + +/// Output Hash：按本仓相对路径字节序遍历发布目录内**全部登记文件**， +/// 逐项 `路径 || NUL || 内容`，以单个 LF 连接后取 SHA-256。 +/// +/// 与 Input Hash 同一构造方式，便于人工复核；它覆盖的是「本仓发布了什么」， +/// 而不是「上游生成了什么」——后者由逐份 declared digest 对账负责。 +pub(crate) fn compute_output_hash(files: &BTreeMap>) -> String { + let mut parts: Vec> = Vec::with_capacity(files.len()); + for (relative, bytes) in files { + let mut item = relative.as_bytes().to_vec(); + item.push(0); + item.extend_from_slice(bytes); + parts.push(item); + } + crate::sha256_hex(&parts.join(&b'\n')) +} diff --git a/modules/root-abi/generator/src/publish.rs b/modules/root-abi/generator/src/publish.rs new file mode 100644 index 0000000..1e505ba --- /dev/null +++ b/modules/root-abi/generator/src/publish.rs @@ -0,0 +1,120 @@ +//! 临时目录 → 全量验证 → 只读权限 → 原子 rename（规格 §3.6 只读生成协议）。 +//! +//! 与 composition 的冻结协议同一形状、同一理由：目标已存在即拒绝，不覆盖已发布生成物； +//! 失败不留下可发现的半成品。差别只在这里还要把发布出来的文件置为只读—— +//! 「生成物不得手改」这条规则因此有了一层文件系统上的提醒（不是防线：有写权限的人 +//! 仍可改回来，真正的判据是 `verify_generated` 的逐份摘要对账）。 + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use crate::error::{err, AbiGenerationError, AbiGenerationErrorKind}; + +struct TempDir(PathBuf); + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = restore_writable(&self.0); + let _ = std::fs::remove_dir_all(&self.0); + } +} + +fn atomic_failed(message: impl Into) -> AbiGenerationError { + err(AbiGenerationErrorKind::AtomicPublishFailed, message) +} + +/// 递归恢复写权限——只读目录树删不掉，清理路径上必须先解除。 +fn restore_writable(root: &Path) -> std::io::Result<()> { + if !root.exists() { + return Ok(()); + } + for entry in std::fs::read_dir(root)? { + let path = entry?.path(); + if path.is_dir() { + restore_writable(&path)?; + } else { + let mut permissions = std::fs::metadata(&path)?.permissions(); + #[allow(clippy::permissions_set_readonly_false)] + permissions.set_readonly(false); + std::fs::set_permissions(&path, permissions)?; + } + } + Ok(()) +} + +fn set_readonly(path: &Path) -> Result<(), AbiGenerationError> { + let mut permissions = std::fs::metadata(path) + .map_err(|e| atomic_failed(format!("取 {} 权限失败：{e}", path.display())))? + .permissions(); + permissions.set_readonly(true); + std::fs::set_permissions(path, permissions) + .map_err(|e| atomic_failed(format!("置 {} 只读失败：{e}", path.display()))) +} + +/// 把已验证的字节原子发布到 `output_directory`。 +/// +/// 调用前所有内容必须已在内存中验证完毕（规格 §3.6：临时目录 → 全量验证 → 只读 → +/// 原子 rename）；进了这里就只剩 I/O。 +pub(crate) fn publish( + output_directory: &Path, + files: &BTreeMap>, +) -> Result<(), AbiGenerationError> { + if output_directory.exists() { + return Err(err( + AbiGenerationErrorKind::OutputAlreadyExists, + format!( + "生成目录 {} 已存在；已发布生成物不可覆盖，重建请发布到新目录", + output_directory.display() + ), + )); + } + let parent = output_directory + .parent() + .ok_or_else(|| atomic_failed("生成目录没有父目录".to_string()))?; + std::fs::create_dir_all(parent) + .map_err(|e| atomic_failed(format!("创建 {} 失败：{e}", parent.display())))?; + + let nonce = { + use std::hash::{BuildHasher, Hasher}; + let mut hasher = std::collections::hash_map::RandomState::new().build_hasher(); + hasher.write_usize(std::process::id() as usize); + format!("{:016x}", hasher.finish()) + }; + let name = output_directory + .file_name() + .ok_or_else(|| atomic_failed("生成目录路径以 .. 结尾".to_string()))? + .to_string_lossy() + .into_owned(); + let temp_root = parent.join(format!(".{name}.tmp-{nonce}")); + std::fs::create_dir(&temp_root) + .map_err(|e| atomic_failed(format!("创建临时目录 {} 失败：{e}", temp_root.display())))?; + let temp = TempDir(temp_root); + + for (relative, bytes) in files { + let path = temp.0.join(relative); + if let Some(dir) = path.parent() { + std::fs::create_dir_all(dir) + .map_err(|e| atomic_failed(format!("创建 {} 失败：{e}", dir.display())))?; + } + std::fs::write(&path, bytes) + .map_err(|e| atomic_failed(format!("写入 {} 失败：{e}", path.display())))?; + set_readonly(&path)?; + } + + // 目标已存在的判定交给 rename 本身（同 composition 的理由：先 exists 再 rename + // 之间有竞态窗口）；上面的 exists 检查只是为了给出更准的错误信息。 + std::fs::rename(&temp.0, output_directory).map_err(|e| { + if output_directory.exists() { + err( + AbiGenerationErrorKind::OutputAlreadyExists, + format!("生成目录 {} 已存在（{e}）", output_directory.display()), + ) + } else { + atomic_failed(format!( + "原子发布到 {} 失败：{e}", + output_directory.display() + )) + } + })?; + Ok(()) +} diff --git a/modules/root-abi/generator/tests/compiler_lock.rs b/modules/root-abi/generator/tests/compiler_lock.rs new file mode 100644 index 0000000..5dcf8b9 --- /dev/null +++ b/modules/root-abi/generator/tests/compiler_lock.rs @@ -0,0 +1,223 @@ +//! 锁定 compiler 的身份校验与生成物摘要链（规格 §8.4、卡面验收项 1/2/3）。 +//! +//! 本 crate 是**薄适配器**：它不含模板、slot 表、type map，只做四件事——校验锁定上游 +//! compiler 的 SHA-256、以只读镜像为输入调用它、把每份产出与上游 bundle 声明的摘要 +//! 逐份对账、原子只读发布。这些测试钉的就是这四件事，不钉生成内容本身（内容是上游的）。 + +use std::path::{Path, PathBuf}; + +use lumio_core_root_abi_generator::{ + generate, verify_generated, AbiGenerationErrorKind, GenerateAbiRequest, +}; + +fn repo_root() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")) + .ancestors() + .nth(3) + .expect("modules/root-abi/generator 上溯三级即仓库根") + .to_path_buf() +} + +/// 锁定 compiler 的落点：`just fetch-architecture-tools` 按 lock 的 pin 提交取到这里。 +fn compiler_directory() -> PathBuf { + let lock = repo_root().join("architecture.lock.json"); + let text = std::fs::read_to_string(&lock).expect("读 architecture.lock.json"); + let key = "\"commit\": \""; + let start = text.find(key).expect("lock 含 commit") + key.len(); + let end = start + text[start..].find('"').expect("commit 以引号结束"); + repo_root() + .join("build/architecture-tools") + .join(&text[start..end]) + .join("tools") +} + +fn available() -> bool { + compiler_directory().join("lumio_generate.py").is_file() +} + +/// 没取过工具链时跳过，并把原因说清楚——测试静默跳过与通过长得一样，那正是本仓 +/// B-00002 要消灭的形态。 +macro_rules! require_compiler { + () => { + if !available() { + eprintln!( + "SKIP: 未找到锁定 compiler（{}）。\ + 先跑 `LUMIO_ARCHITECTURE_REPO=<架构源仓> just fetch-architecture-tools`。", + compiler_directory().display() + ); + return; + } + }; +} + +fn request(output_directory: PathBuf) -> GenerateAbiRequest { + GenerateAbiRequest { + // 计划核对由 CLI 路径覆盖（just generate-abi 总是传 --plan）； + // 这些测试钉的是 compiler 身份与摘要链，不重复造一份冻结计划。 + frozen_plan_path: None, + architecture_lock_path: repo_root().join("architecture.lock.json"), + mirror_root: None, + compiler_directory: compiler_directory(), + output_directory, + } +} + +fn temp_out(tag: &str) -> PathBuf { + use std::sync::atomic::{AtomicU32, Ordering}; + static SEQ: AtomicU32 = AtomicU32::new(0); + let dir = std::env::temp_dir().join(format!( + "lce-abi-{}-{}-{}", + tag, + std::process::id(), + SEQ.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + dir +} + +#[test] +fn compiler_digest_and_input_hash_come_from_the_locked_bundle() { + require_compiler!(); + let out = temp_out("hashes"); + let artifacts = generate(request(out.clone())).expect("生成成功"); + + // 验收项 1：Compiler / Input / Output Hash 完整。三者都必须是 64 位小写十六进制， + // 且 compiler / input 与上游 bundle 的声明值相等（相等性由实现在生成期强制， + // 这里再读回一次，防止「算了但没用」）。 + for digest in [ + &artifacts.compiler_digest, + &artifacts.input_hash, + &artifacts.output_hash, + ] { + assert_eq!(digest.len(), 64, "{digest}"); + assert!(digest + .chars() + .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))); + } + + let report = + verify_generated(&out, &repo_root().join("architecture.lock.json")).expect("回读校验成功"); + assert!(report.input_hash_matches); + assert!(report.output_hash_matches); + assert!(report.schema_valid); + assert!(report.c_layout_valid && report.rust_layout_valid && report.csharp_layout_valid); + + let _ = std::fs::remove_dir_all(&out); +} + +#[test] +fn wrong_compiler_directory_is_rejected_before_any_output_is_written() { + require_compiler!(); + let out = temp_out("bad-compiler"); + let mut bad = request(out.clone()); + bad.compiler_directory = repo_root().join("tools"); // 本仓 tools/，不是锁定 compiler + + let error = generate(bad).expect_err("compiler 身份不符必须失败"); + assert_eq!(error.kind(), AbiGenerationErrorKind::CompilerDigestMismatch); + assert!( + !out.exists(), + "compiler 校验失败时不得留下输出目录（卡面 blocked 行为：输出目录不存在）" + ); +} + +#[test] +fn regenerating_into_a_fresh_directory_is_byte_identical() { + require_compiler!(); + // 验收项 3：同输入重建零差异。 + let first = temp_out("repro-a"); + let second = temp_out("repro-b"); + let a = generate(request(first.clone())).expect("首次生成"); + let b = generate(request(second.clone())).expect("再次生成"); + + assert_eq!(a.output_hash, b.output_hash); + for (left, right) in [ + (&a.header_path, &b.header_path), + (&a.csharp_binding_path, &b.csharp_binding_path), + (&a.rust_contracts_path, &b.rust_contracts_path), + (&a.abi_document_path, &b.abi_document_path), + (&a.layout_report_path, &b.layout_report_path), + ( + &a.generated_artifact_descriptor_path, + &b.generated_artifact_descriptor_path, + ), + ] { + assert_eq!( + std::fs::read(left).expect("读左"), + std::fs::read(right).expect("读右"), + "{} 与 {} 必须逐字节相同", + left.display(), + right.display() + ); + } + + let _ = std::fs::remove_dir_all(&first); + let _ = std::fs::remove_dir_all(&second); +} + +#[test] +fn publishing_over_an_existing_directory_is_refused() { + require_compiler!(); + let out = temp_out("exists"); + generate(request(out.clone())).expect("首次生成"); + let error = generate(request(out.clone())).expect_err("已发布目录不得覆盖"); + assert_eq!(error.kind(), AbiGenerationErrorKind::OutputAlreadyExists); + let _ = std::fs::remove_dir_all(&out); +} + +#[test] +fn hand_editing_any_generated_byte_makes_verification_fail() { + require_compiler!(); + // 验收项 2：手改稳定失败。逐份产物各改一个字节，每次都必须被发现。 + let lock = repo_root().join("architecture.lock.json"); + for which in 0..6usize { + let out = temp_out(&format!("tamper-{which}")); + let artifacts = generate(request(out.clone())).expect("生成成功"); + let target = [ + &artifacts.header_path, + &artifacts.csharp_binding_path, + &artifacts.rust_contracts_path, + &artifacts.abi_document_path, + &artifacts.layout_report_path, + &artifacts.generated_artifact_descriptor_path, + ][which] + .clone(); + + // 发布是只读的，改之前先恢复写权限——这一步本身也证明了「只读发布」成立。 + let mut permissions = std::fs::metadata(&target).expect("取权限").permissions(); + assert!(permissions.readonly(), "{} 必须是只读", target.display()); + #[allow(clippy::permissions_set_readonly_false)] + permissions.set_readonly(false); + std::fs::set_permissions(&target, permissions).expect("恢复写权限"); + + let mut bytes = std::fs::read(&target).expect("读产物"); + bytes.push(b' '); + std::fs::write(&target, &bytes).expect("写回被篡改的产物"); + + let error = verify_generated(&out, &lock).expect_err("手改必须被发现"); + assert!( + matches!( + error.kind(), + AbiGenerationErrorKind::OutputHashMismatch + | AbiGenerationErrorKind::UnregisteredFile + ), + "{} 被改后得到 {:?}", + target.display(), + error.kind() + ); + let _ = std::fs::remove_dir_all(&out); + } +} + +#[test] +fn an_unregistered_file_in_the_output_directory_is_rejected() { + require_compiler!(); + // 验收项 4：生成目录没有未登记文件。 + let out = temp_out("stray"); + generate(request(out.clone())).expect("生成成功"); + std::fs::write(out.join("stray.txt"), b"not generated\n").expect("塞一个未登记文件"); + + let error = verify_generated(&out, &repo_root().join("architecture.lock.json")) + .expect_err("未登记文件必须被发现"); + assert_eq!(error.kind(), AbiGenerationErrorKind::UnregisteredFile); + let _ = std::fs::remove_dir_all(&out); +} diff --git a/modules/root-abi/generator/tests/no_private_schema.rs b/modules/root-abi/generator/tests/no_private_schema.rs new file mode 100644 index 0000000..162e6ac --- /dev/null +++ b/modules/root-abi/generator/tests/no_private_schema.rs @@ -0,0 +1,141 @@ +//! 本仓不得私有化 ABI 语义（规格 §8.1 非职责、卡面「非目标」）。 +//! +//! generator 是薄适配器：模板、slot 表、type map 全部属于**上游 compiler**，本 crate +//! 只负责校验身份、喂输入、对账摘要、只读发布。这条边界一旦被越过，本仓就成了第二个 +//! ABI 定义处，而两处定义迟早会分叉——那正是规格 §4「私有模板会制造第二 ABI」要防的。 +//! +//! 这些断言是**源码级**的：它们不跑生成，只看本 crate 的代码里有没有出现不该有的东西。 + +use std::path::{Path, PathBuf}; + +fn source_directory() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")).join("src") +} + +fn rust_sources() -> Vec<(PathBuf, String)> { + fn walk(dir: &Path, out: &mut Vec<(PathBuf, String)>) { + for entry in std::fs::read_dir(dir).expect("读源码目录") { + let path = entry.expect("目录项").path(); + if path.is_dir() { + walk(&path, out); + } else if path.extension().and_then(|e| e.to_str()) == Some("rs") { + let text = std::fs::read_to_string(&path).expect("读源码"); + out.push((path, text)); + } + } + } + let mut out = Vec::new(); + walk(&source_directory(), &mut out); + assert!(!out.is_empty(), "至少应有源码文件"); + out +} + +/// 只看代码，不看注释与文档——注释里出现这些词是**解释边界**，恰恰是应该有的。 +fn code_lines(text: &str) -> impl Iterator { + text.lines() + .map(str::trim_start) + .filter(|line| !line.starts_with("//") && !line.starts_with("*") && !line.is_empty()) +} + +#[test] +fn generator_contains_no_c_or_csharp_or_rust_type_mapping_table() { + // 上游 ABI_TYPE_MAPPING 的形态：把 typeRef 映射到 C / C# / Rust 拼写。 + // 本仓出现任何一组这类字面量，就等于开了第二份 type map。 + let markers = [ + "uint8_t", + "uint16_t", + "uint32_t", + "uint64_t", + "int8_t", + "int16_t", + "int32_t", + "int64_t", + "lumio_status_t", + "lumio_handle_t", + "LumioStatus", + "LumioHandle", + ]; + for (path, text) in rust_sources() { + for line in code_lines(&text) { + for marker in markers { + assert!( + !line.contains(marker), + "{} 的代码里出现了 C/C# 类型拼写 {marker}：type map 属上游 compiler，\ + 本仓不得持有第二份\n {line}", + path.display() + ); + } + } + } +} + +#[test] +fn generator_emits_no_header_or_binding_text() { + // 生成文本的特征：`#include`、`#pragma`、`extern "C"`、`namespace`、`#[repr(C)]` + // 之类只可能出现在被生成的内容里。适配器不产生这些字节，只搬运上游产物。 + let markers = [ + "#include", + "#pragma", + "extern \\\"C\\\"", + "namespace Lumio", + "#[repr(C)]", + "public static class", + "typedef struct", + ]; + for (path, text) in rust_sources() { + for line in code_lines(&text) { + for marker in markers { + assert!( + !line.contains(marker), + "{} 的代码里出现了生成文本片段 {marker}：本仓不实现模板\n {line}", + path.display() + ); + } + } + } +} + +#[test] +fn generator_declares_no_slot_indices_or_layout_constants() { + // slot 编号与布局常量（pointerBytes / maxAlignment / rootHeaderBytes …）都由上游 + // layoutProfile 提供；本仓写死任何一个，就会在上游改布局时静默不一致。 + let markers = [ + "pointerBytes", + "maxAlignment", + "rootHeaderBytes", + "tableHeaderBytes", + "slot_index", + "slotIndex", + ]; + for (path, text) in rust_sources() { + for line in code_lines(&text) { + for marker in markers { + // 允许以字符串键的形式**读取**上游字段，不允许把值写死成常量。 + let is_constant_definition = line.contains("const ") || line.contains("static "); + assert!( + !(line.contains(marker) && is_constant_definition), + "{} 把上游布局常量 {marker} 写死了：它必须每次从上游 layoutProfile 读\n {line}", + path.display() + ); + } + } + } +} + +#[test] +fn generator_does_not_read_the_architecture_source_working_tree() { + // 输入只能是本仓的 architecture.lock.json 与只读镜像。直接去读架构源仓工作区 + // （或 docs/architecture/）会让产物依赖一个不受 lock 约束的可变输入。 + let forbidden = ["LumioGameEngineArchitecture", "docs/architecture"]; + for (path, text) in rust_sources() { + for line in code_lines(&text) { + for marker in forbidden { + assert!( + !line.contains(marker), + "{} 的代码里引用了架构源工作区 {marker}：输入只能是 lock 与只读镜像\n {line}", + path.display() + ); + } + } + } +} From 7e7447e0b9b46a65988d5cdd055228285da9bdd7 Mon Sep 17 00:00:00 2001 From: Cui Date: Sat, 29 Aug 2026 16:49:24 +0800 Subject: [PATCH 2/4] =?UTF-8?q?fix(root-abi):=20=E6=91=98=E8=A6=81?= =?UTF-8?q?=E9=93=BE=E8=A1=A5=E9=BD=90=E5=A4=96=E9=83=A8=E9=94=9A=E7=82=B9?= =?UTF-8?q?=EF=BC=8C=E7=9C=9F=E8=B7=91=E4=B8=8A=E6=B8=B8=20validator?= =?UTF-8?q?=EF=BC=88R-00018=20=E5=AE=A1=E6=9F=A5=E9=80=80=E5=9B=9E?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reviewer 四条 P1，共同的形态是「摘要链的上半段是真的，下半段是自证的」。他实测出两条 绕过路径都能让 just check-generated 绿灯，其中一条能把注入内容送进 C Header 与两份 binding。 P1-1 metadata/ 与 reports/ 两份产物没有任何独立锚点。它们唯一的约束是 descriptor 的 fileDigests，而 descriptor 正是从同一批盘上字节重建出来的——被背书者与背书者同源， 是恒等式不是校验。整份替换 ABI 文档再重建 descriptor，verify exit 0。 补锚点：ABI 文档锚回镜像里 inputSet 声明的那一份（逐字节相等，已被 inputHash 钉死）； layout report 锚回本次由上游 layoutProfile 现算的内容（那个值第 425 行本来就算出来了， 之前直接丢弃）。 P1-2 摘要链的根（上游 bundle）未与 lock 对账。read_bundle 无条件采信它声明的 compiler.digest / inputHash / outputFiles[].digest，而 lock 的 requiredPathSha256 里 正有这份文件的登记摘要——没读。改 bundle 里三个 outputFiles.digest 再重建 descriptor， 六份产物可被整体替换。改为读 lock 校验后才解析。 P1-3 require_compiler! 用 eprintln! + return 实现「跳过」——那等于测试通过，libtest 还 会把提示吞掉。在没取过工具链的机器上，6 个测试恒为绿且恒为空，而本卡四条通过条件的 全部证据都挂在它们身上。宏自己的注释还写着「静默跳过与通过长得一样，那正是 B-00002 要消灭的形态」，随后做的就是这件事。改为缺工具链即失败。 P1-4 卡面要求的上游 semantic validator 从未被调用，报告却无条件声称已通过。上游 emit_root_abi 的第一件事是 validate_abi_document（schema + ADR-040 语义），docstring 明写 「在写出任何一个输出字节之前拒绝非法 ABI 文档」；驱动脚本重写它的主体时把这次调用 跳掉了，同时 AbiCompatibilityReport 的 schema_valid / semantic_rules_valid / symbols_valid 写死 true——9 个字段里 7 个是常量或恒真式，compiler_lock.rs 那条 assert!(report.schema_valid) 是在断言一个字面量。 改为：驱动脚本先跑 validate_abi_document；schema/semantic 依据 descriptor 记录的 validatorRan（descriptor 已被逐字节重建校验，改不动）；symbols 真查一次——ABI 文档声明的 entrySymbol 必须出现在发布的 C Header 里。 跑上游 validator 需要 lumio_contract 能按仓库根布局读 fixture（它在导入时就读）， 所以用只读镜像的 schemas/ fixtures/ ids/ packages/ 加锁定 tools/ 在临时目录拼一个 一次性 contract root，用完即删；镜像本身不动，绝不使用架构源仓工作区。 新增负向测试覆盖 reviewer 实测的两条绕过、bundle 篡改、compiler 字节漂移分支。 13 个测试全绿（原 10 + 3）。 同批处理的 P2： - no_private_schema.rs 的能力边界写进文档（前三条是关键词黑名单，reviewer 给出五种 现成绕法），并补一条真正结构性的断言：src/ 下不得有非 .rs 文件——挡住「模板外置成 templates/*.h.in 再 include_str!」这条最省事的路。 - descriptor 补输入逐文件摘要（§3.6）：只有聚合 inputHash 时，镜像漂移只能说「不一致」， 指不到是哪个文件。 - CLI 子命令改成规格 §8.4 的 verify-generated --generated。 - frozen_plan_path 的 Option 意味着核对可跳过，这条弱化写进注释与 ADR，不再只说「为什么 是路径」。 沉淀 ADR 0009：摘要链每一环都要有外部锚点、descriptor 不得自证、报告不得声称没做过的 检查、上游输出集合以上游为准。判据写成可复用的一句：被背书者与背书者必须不同源。 Co-Authored-By: Claude Fable 5 --- ...009-root-abi-generator-adapter-boundary.md | 94 ++++++++++ .spec/decisions/README.md | 1 + justfile | 2 +- .../generated-contract-artifact.json | 2 +- .../src/bin/lumio-core-root-abi-generator.rs | 8 +- modules/root-abi/generator/src/compiler.rs | 105 +++++++++++- modules/root-abi/generator/src/input_set.rs | 75 +++++++- modules/root-abi/generator/src/lib.rs | 140 +++++++++++++-- .../root-abi/generator/tests/compiler_lock.rs | 162 ++++++++++++++++-- .../generator/tests/no_private_schema.rs | 32 ++++ 10 files changed, 579 insertions(+), 42 deletions(-) create mode 100644 .spec/decisions/0009-root-abi-generator-adapter-boundary.md diff --git a/.spec/decisions/0009-root-abi-generator-adapter-boundary.md b/.spec/decisions/0009-root-abi-generator-adapter-boundary.md new file mode 100644 index 0000000..2308ec1 --- /dev/null +++ b/.spec/decisions/0009-root-abi-generator-adapter-boundary.md @@ -0,0 +1,94 @@ +# 0009 · root-abi generator 的适配器边界与 §8.3 接口偏离：摘要链锚点必须落在 lock 上 + +- 日期:2026-08-29 +- 状态:生效 + +## 背景 + +LCE-P0-005 要把架构源的 Root ABI 制品接进本仓。规格 §8.3 给了 `GenerateAbiRequest` / +`GeneratedAbiArtifacts` / `AbiCompatibilityReport` 的字段面，§4 定了「只消费架构源生成制品」， +§3.6 定了只读生成协议。落地时有三处规格没说、但一旦选错就会让整条摘要链变成自证的问题： + +1. **compiler 身份怎么表达。** §8.3 写的是 `compiler_path: PathBuf` + `compiler_digest: Digest256`。 + 但上游 `compiler_hash()` 的口径是 `sha256(tools/lumio_contract.py ‖ tools/lumio_generate.py)` + ——身份由**两个文件**共同决定，单个路径表达不了；而把期望摘要做成入参，等于允许调用方 + 自带答案来对账。 +2. **摘要链的根锚在哪。** 上游 `root-abi-bundle.json` 声明了 compiler 身份、inputHash 与每份 + 产物的期望摘要。它在只读镜像里，是一个**可被就地改写的本地文件**。 +3. **本仓自产的登记文件谁来背书。** `metadata/native-managed-abi.json` 与 + `reports/layout-report.json` 不是上游产物，bundle 里没有它们的摘要。 + +第 2、3 两条在首版实现里都答错了，且**都不是靠推理发现的**：审查实测出两条绕过路径—— +改一份无锚点产物、或改 bundle 里的三个 `outputFiles.digest`，再按同一规则重建 descriptor， +`just check-generated` 全部绿灯。本 ADR 记录修正后的边界，以及为什么必须这么定。 + +## 决策 + +### 1. 摘要链的每一环都要有**外部**锚点，descriptor 不得自证 + +链条自上而下： + +| 环节 | 锚点 | 若无此锚点 | +| --- | --- | --- | +| 上游 bundle | `architecture.lock.json` 的 `requiredPathSha256["packages/abi/root-abi-bundle.json"]` | 改 bundle 的 outputFiles.digest 即可整体移动锚点，六份产物全部可替换 | +| compiler | bundle 声明的 `compiler.digest`（本仓复算两文件拼接） | 换 compiler 无人发现 | +| 输入集合 | bundle 声明的 `inputHash`（本仓按 `inputSet` **重算**，不照抄） | 照抄只证明「读到了这个数」，证明不了「镜像里就是那份输入」 | +| 三份上游产物 | bundle 声明的 `outputFiles[].digest` | — | +| `metadata/native-managed-abi.json` | 镜像里 `inputSet` 声明的同一份文件（逐字节相等，已被 inputHash 钉死） | 整份替换后重建 descriptor 即可全绿 | +| `reports/layout-report.json` | 由上游 `layoutProfile` **现算**的内容 | 同上 | +| `generated-contract-artifact.json` | 按同一规则**重建后逐字节比对** | 「它记的每一条都对得上」证明不了「它自己没被改」 | + +**判据**：任何一份产物，如果它的唯一约束来自 descriptor，而 descriptor 又是从同一批盘上 +字节重建出来的，那就是恒等式，不是校验。被背书者与背书者必须不同源。 + +### 2. §8.3 的两处接口偏离 + +- `compiler_path` + `compiler_digest` → **`compiler_directory: PathBuf`**。身份由目录下两个 + 固定文件共同决定；期望摘要只从上游 bundle 取，不接受调用方传入。这是**收紧**：入参形式 + 允许调用方自带答案，目录形式不允许。 +- `build_plan: FrozenBuildPlan` → **`frozen_plan_path: Option`**。计划经 + `composition::verify_frozen_plan` 读取（ADR 0006 第 8 条：消费者不得自建第二套解析器）。 + Root ABI 的输入集合**全部**来自上游 `inputSet`，与 BuildPlan 无交集；计划在这里的作用是 + 交叉核对——它记的 architecture 基线与提交必须与本仓 lock 一致，否则「按 A 计划构建、 + 按 B 基线生成 ABI」会一路无声走到运行时。 + **`Option` 意味着这条核对可被跳过**：给了才查，不给则不查。CLI 总是给（justfile 的 + `generate-abi` recipe 传 `--plan`），库调用方可以不给。这是相对规格的**弱化**，记在这里 + 而不是只写在 doc-comment 里。 + +### 3. 上游 validator 必须真跑，报告不得声称没做过的检查 + +上游 `emit_root_abi()` 的第一件事是 `validate_abi_document()`（schema + ADR-040 语义）， +其 docstring 明写「在写出任何一个输出字节之前拒绝非法 ABI 文档」。本仓的驱动脚本重写了 +`emit_root_abi` 的主体来只取三个 emitter，**必须显式补回这次调用**——首版跳过了它，同时 +`AbiCompatibilityReport` 的 `schema_valid` / `semantic_rules_valid` / `symbols_valid` 三个字段 +写死 `true`。那是谎报做过的检查，而该报告会被下游多张卡消费。 + +规则：`AbiCompatibilityReport` 的每个字段只能反映**本次真的做过**的检查。做不到的项要么 +补上检查，要么改成能表达「未做此项」的形式，不得填 `true`。 + +`verify_generated` 不跑 validator（回读校验必须能在没有工具链的机器上进行），它的 +schema/semantic 依据是 descriptor 记录的 `validatorRan` —— 而 descriptor 已被逐字节重建 +校验，这条记录改不动。 + +### 4. 上游输出集合以上游为准 + +驱动脚本按 `module.ABI_OUTPUT_FILES` 取输出清单并断言与本仓适配清单集合相等。上游**新增** +第 4 份输出时必须在这里响亮失败，而不是被本仓写死的三条清单静默忽略——「输出集合精确 +比对」若只对本仓清单精确，对上游就是不精确。 + +### 5. compiler 的运行根目录用镜像内容临时拼装 + +`lumio_contract` 在**导入时**就按仓库根布局读 fixture，只把 `tools/` 指过去不够。本仓在临时 +目录里用**只读镜像**的 `schemas/` `fixtures/` `ids/` `packages/` 加锁定 `tools/` 拼一个一次性 +contract root，用完即删。镜像本身不动（受 lock 约束且已置只读），**绝不使用架构源仓工作区** +——那是不受 lock 约束的可变输入。 + +## 后果 + +- 生成与回读各多读一次 lock 与镜像输入，代价是几个文件的 I/O，换来锚点不可被就地移动。 +- `check-generated` 与 `check-contracts` 的职责仍然分离（后者管镜像整体完整性），但本卡不再 + 依赖调用者「记得两条都跑」——bundle 对 lock 的校验在生成器内部完成。 +- LCE-P0-014 / LCE-P0-008 等消费 `AbiCompatibilityReport` 的卡，可以按字段面信任它，因为每个 + 字段都对应一次真实检查。 +- 本 ADR 不改变 ADR 0001—0004、0006、0008 的任何边界，不新增依赖边（`root-abi-generator -> + composition` 在 ADR 0004 第 3 条冻结的允许边内），不定义任何公共 Schema / ID / FFI 语义。 diff --git a/.spec/decisions/README.md b/.spec/decisions/README.md index dc5605a..edbf93e 100644 --- a/.spec/decisions/README.md +++ b/.spec/decisions/README.md @@ -35,3 +35,4 @@ | [0006](0006-internal-build-plan-freeze.md) | BuildPlan 定为仓内确定性 JSON（plan_format_version=1），sidecar Digest 原子冻结，platform 只读 | 生效 | | [0007](0007-composition-config-toml-parser.md) | compose 配置解析选定 `toml` crate 并精确锁版，不自研 TOML 子集解析器 | 生效 | | [0008](0008-opened-artifact-set-construction-inversion.md) | `OpenedArtifactSet`/`MappedNativeImage` 用构造反转保持私有构造器，feature gate 不用于跨 crate 可见性 | 生效 | +| [0009](0009-root-abi-generator-adapter-boundary.md) | root-abi generator 摘要链每环须有外部锚点，descriptor 不得自证；报告不得声称没做过的检查 | 生效 | diff --git a/justfile b/justfile index 402cdd7..eaa8805 100644 --- a/justfile +++ b/justfile @@ -118,7 +118,7 @@ generate-abi p="p0-linux": (assert-profile p) # 文件集合与登记表完全一致。没有这一段，手改生成物不会被任何门禁发现。 check-generated: cargo test -p lumio-core-contracts --locked --test generated_integrity - cargo run --locked -q -p lumio-core-root-abi-generator -- verify --root modules/root-abi/generated/LGE-V1.4-2026-08-27 --architecture-lock architecture.lock.json + cargo run --locked -q -p lumio-core-root-abi-generator -- verify-generated --generated modules/root-abi/generated/LGE-V1.4-2026-08-27 --architecture-lock architecture.lock.json build-platform p="p0-linux": (assert-profile p) cargo run --locked -p lumio-core-platform-build -- build-staging --plan build/plans/p0-linux-server-x86_64-glibc/build-plan.json --plan-digest-file build/plans/p0-linux-server-x86_64-glibc/build-plan.sha256 --abi modules/root-abi/generated/LGE-V1.4-2026-08-27 --out build/platform/linux-server-x86_64-glibc/staging diff --git a/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json b/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json index 084d495..08c38e3 100644 --- a/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json +++ b/modules/root-abi/generated/LGE-V1.4-2026-08-27/generated-contract-artifact.json @@ -1 +1 @@ -{"architectureCommit":"1f2ead332b3dfc3042e1495bfbe6febb8699df7e","architectureRepository":"https://github.com/LumioGames/LumioGameEngineArchitecture","baselineId":"LGE-V1.4-2026-08-27","bundleId":"root-abi-v1","compiler":{"digest":"217437fd4755e1a339e2029838cc4a2d2fb305fa05520c8cfd10ea98cc2ff290","name":"lumio-abi-compiler","version":"1.0.0"},"fileDigests":{"csharp/Lumio.CoreEngine.Native.g.cs":"d89ff35434438773055ce4108b9f04ef6ff2b42335101249163f65c734975cd1","include/lumio_core.h":"040451bbde5a4dec3726be5f5a7be4bb934c3f68a1ca87f9c55559cae738efc7","metadata/native-managed-abi.json":"ec1bad62f4daac6c5cacd022df045ec7b47fd04c0f0a15fe39a6ce41a1ad8997","reports/layout-report.json":"fb385d696e94460444e04caf416e91db31d3cf832aeb521ef8bc5e8a99879260","rust/contracts.rs":"5e81bdfb6e879d849e2cb77a847a07167e5a459f2f23fd43f07609e726043bec"},"inputHash":"696a58d0525b897b549dd1e432166ae1020835902a5984221a8e60d5d8285bb3","kind":"root-abi-generated-contract-artifact","outputHash":"bdbab5d398f8d98c5ac34c795712b619df70aed76d334f9961b3e53ff75a91a9","registeredFiles":["csharp/Lumio.CoreEngine.Native.g.cs","generated-contract-artifact.json","include/lumio_core.h","metadata/native-managed-abi.json","reports/layout-report.json","rust/contracts.rs"],"schemaEpoch":1} +{"architectureCommit":"1f2ead332b3dfc3042e1495bfbe6febb8699df7e","architectureRepository":"https://github.com/LumioGames/LumioGameEngineArchitecture","baselineId":"LGE-V1.4-2026-08-27","bundleId":"root-abi-v1","compiler":{"digest":"217437fd4755e1a339e2029838cc4a2d2fb305fa05520c8cfd10ea98cc2ff290","name":"lumio-abi-compiler","version":"1.0.0"},"entrySymbol":"lumio_core_get_api_v1","fileDigests":{"csharp/Lumio.CoreEngine.Native.g.cs":"d89ff35434438773055ce4108b9f04ef6ff2b42335101249163f65c734975cd1","include/lumio_core.h":"040451bbde5a4dec3726be5f5a7be4bb934c3f68a1ca87f9c55559cae738efc7","metadata/native-managed-abi.json":"ec1bad62f4daac6c5cacd022df045ec7b47fd04c0f0a15fe39a6ce41a1ad8997","reports/layout-report.json":"fb385d696e94460444e04caf416e91db31d3cf832aeb521ef8bc5e8a99879260","rust/contracts.rs":"5e81bdfb6e879d849e2cb77a847a07167e5a459f2f23fd43f07609e726043bec"},"inputFileDigests":{"fixtures/valid/native-managed-abi.json":"ec1bad62f4daac6c5cacd022df045ec7b47fd04c0f0a15fe39a6ce41a1ad8997","schemas/native-managed-abi.schema.json":"8ef8c627eccae47841005c7bc38609b1139f6517943e21a6ca8d3002751e3a36"},"inputHash":"696a58d0525b897b549dd1e432166ae1020835902a5984221a8e60d5d8285bb3","inputSet":["schemas/native-managed-abi.schema.json","fixtures/valid/native-managed-abi.json"],"kind":"root-abi-generated-contract-artifact","outputHash":"bdbab5d398f8d98c5ac34c795712b619df70aed76d334f9961b3e53ff75a91a9","registeredFiles":["csharp/Lumio.CoreEngine.Native.g.cs","generated-contract-artifact.json","include/lumio_core.h","metadata/native-managed-abi.json","reports/layout-report.json","rust/contracts.rs"],"schemaEpoch":1,"validatorRan":true} diff --git a/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs b/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs index afd8657..65db416 100644 --- a/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs +++ b/modules/root-abi/generator/src/bin/lumio-core-root-abi-generator.rs @@ -13,7 +13,8 @@ const USAGE: &str = "\ lumio-core-root-abi-generator generate --plan \\ --architecture-lock --out <生成目录> \\ [--compiler-dir <锁定 compiler 目录>] - lumio-core-root-abi-generator verify --root <生成目录> --architecture-lock + lumio-core-root-abi-generator verify-generated --generated <生成目录> \\ + --architecture-lock --compiler-dir 缺省取 build/architecture-tools//tools， 即 `just fetch-architecture-tools` 的落点。"; @@ -117,8 +118,9 @@ fn run(args: &[String]) -> Result<(), Failure> { ); Ok(()) } - "verify" => { - let root = required(rest, "--root")?; + // 名字取规格 §8.4 的 `verify-generated`；`--generated` 同理。 + "verify-generated" => { + let root = required(rest, "--generated")?; let lock = required(rest, "--architecture-lock")?; let report = verify_generated(&root, &lock)?; println!("{}", report.abi_identity); diff --git a/modules/root-abi/generator/src/compiler.rs b/modules/root-abi/generator/src/compiler.rs index abcb155..1a34dfd 100644 --- a/modules/root-abi/generator/src/compiler.rs +++ b/modules/root-abi/generator/src/compiler.rs @@ -3,7 +3,7 @@ //! //! 本仓**不实现** cbindgen / ClangSharp / 任何模板（卡面非目标）。这里做的全部事情是： //! 1. 复算 compiler 身份摘要，与上游 bundle 声明的 `compiler.digest` 比对； -//! 2. 把只读镜像喂给它，收回它产出的文本。 +//! 2. 让它先跑自己的 `validate_abi_document`（schema + ADR-040 语义），再产出文本。 //! //! compiler 身份摘要的口径由上游 `compiler_hash()` 固定： //! `sha256(lumio_contract.py 全字节 || lumio_generate.py 全字节)`。顺序与拼接方式都是 @@ -24,25 +24,42 @@ const COMPILER_FILES: [&str; 2] = ["lumio_contract.py", "lumio_generate.py"]; const DRIVER: &str = r#" import importlib.util, json, sys generate_path, mirror_root = sys.argv[1], sys.argv[2] +sys.path.insert(0, str(__import__("pathlib").Path(generate_path).parent)) spec = importlib.util.spec_from_file_location("lumio_generate", generate_path) module = importlib.util.module_from_spec(spec) +sys.modules["lumio_generate"] = module spec.loader.exec_module(module) from pathlib import Path mirror = Path(mirror_root) abi = json.loads((mirror / module.ABI_DOCUMENT).read_text(encoding="utf-8")) +# 上游 semantic validator 必须先跑：它的 docstring 就是「在写出任何一个输出字节之前 +# 拒绝非法 ABI 文档」。跳过它再声称 schema/semantic 已校验，就是谎报做过的检查。 +module.validate_abi_document(mirror, abi) emitters = { "abi/lumio_core.h": module.emit_c_header, "rust/lumio-gen-language-binding/src/root_abi.rs": module.emit_rust_root_abi, "csharp/Lumio.Gen.LanguageBinding/RootAbi.cs": module.emit_csharp_root_abi, } +# 输出集合以**上游** ABI_OUTPUT_FILES 为准，不以本仓写死的清单为准： +# 上游新增第 4 份输出时必须在这里响亮失败，而不是被本仓的三条清单静默忽略。 +upstream_paths = [path for path, _role in module.ABI_OUTPUT_FILES] +if sorted(upstream_paths) != sorted(emitters): + raise SystemExit( + "upstream ABI_OUTPUT_FILES changed: {} vs adapter {}".format( + sorted(upstream_paths), sorted(emitters) + ) + ) json.dump( { - "outputs": {path: emit(abi) for path, emit in emitters.items()}, + "outputs": {path: emitters[path](abi) for path in upstream_paths}, "abiDocument": (mirror / module.ABI_DOCUMENT).read_text(encoding="utf-8"), + "abiDocumentPath": module.ABI_DOCUMENT, + "entrySymbol": abi["entrySymbol"], "layoutProfile": module.LAYOUT_PROFILE, "compilerName": module.ABI_COMPILER_NAME, "compilerVersion": module.ABI_COMPILER_VERSION, "bundleId": module.ABI_BUNDLE_ID, + "validatorRan": True, }, sys.stdout, ) @@ -82,6 +99,85 @@ pub(crate) struct CompilerOutput { pub(crate) compiler_version: String, #[serde(rename = "bundleId")] pub(crate) bundle_id: String, + /// 上游 ABI 文档在架构源树内的相对路径——本仓据此把它锚回 `inputSet`。 + #[serde(rename = "abiDocumentPath")] + pub(crate) abi_document_path: String, + #[serde(rename = "entrySymbol")] + pub(crate) entry_symbol: String, + /// 上游 `validate_abi_document` 已执行的凭据。DRIVER 里它在任何 emit 之前调用， + /// 抛异常即整个进程非零退出，所以这个字段为 true 等价于「校验通过」。 + #[serde(rename = "validatorRan")] + pub(crate) validator_ran: bool, +} + +/// 锁定 compiler 期望的仓库根布局：`tools/` 与 `schemas/` / `fixtures/` / `ids/` / +/// `packages/` 同级。`lumio_contract` 在**导入时**就按这个布局读 fixture +/// （`_ABILITY_FIXTURE`），所以只把 tools 指过去不够。 +/// +/// 这里用只读镜像的内容拼一个一次性的 contract root：镜像本身不动（它受 lock 约束、 +/// 且已被置为只读），tools 从锁定落点复制进来。绝不使用架构源仓工作区。 +const CONTRACT_ROOT_SUBDIRS: [&str; 4] = ["schemas", "fixtures", "ids", "packages"]; + +fn copy_tree(from: &Path, to: &Path) -> std::io::Result<()> { + std::fs::create_dir_all(to)?; + for entry in std::fs::read_dir(from)? { + let entry = entry?; + let target = to.join(entry.file_name()); + if entry.file_type()?.is_dir() { + copy_tree(&entry.path(), &target)?; + } else { + std::fs::copy(entry.path(), &target)?; + } + } + Ok(()) +} + +struct ScratchRoot(std::path::PathBuf); + +impl Drop for ScratchRoot { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +fn build_contract_root( + compiler_directory: &Path, + mirror_root: &Path, +) -> Result { + let nonce = { + use std::hash::{BuildHasher, Hasher}; + let mut hasher = std::collections::hash_map::RandomState::new().build_hasher(); + hasher.write_usize(std::process::id() as usize); + format!("{:016x}", hasher.finish()) + }; + let root = std::env::temp_dir().join(format!("lce-abi-contract-root-{nonce}")); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(&root).map_err(|e| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("创建 compiler 运行根目录失败：{e}"), + ) + })?; + let scratch = ScratchRoot(root); + + for subdir in CONTRACT_ROOT_SUBDIRS { + let from = mirror_root.join(subdir); + if from.is_dir() { + copy_tree(&from, &scratch.0.join(subdir)).map_err(|e| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("准备 {subdir}/ 失败：{e}"), + ) + })?; + } + } + copy_tree(compiler_directory, &scratch.0.join("tools")).map_err(|e| { + err( + AbiGenerationErrorKind::CompilerInvocationFailed, + format!("准备 tools/ 失败：{e}"), + ) + })?; + Ok(scratch) } /// 以只读镜像为输入运行锁定 compiler。 @@ -91,12 +187,13 @@ pub(crate) fn run( compiler_directory: &Path, mirror_root: &Path, ) -> Result { - let generate = compiler_directory.join("lumio_generate.py"); + let scratch = build_contract_root(compiler_directory, mirror_root)?; + let generate = scratch.0.join("tools/lumio_generate.py"); let output = Command::new("python3") .arg("-c") .arg(DRIVER) .arg(&generate) - .arg(mirror_root) + .arg(&scratch.0) .output() .map_err(|e| { err( diff --git a/modules/root-abi/generator/src/input_set.rs b/modules/root-abi/generator/src/input_set.rs index dd19413..3e339bb 100644 --- a/modules/root-abi/generator/src/input_set.rs +++ b/modules/root-abi/generator/src/input_set.rs @@ -17,6 +17,8 @@ pub(crate) struct ArchitectureLock { #[serde(rename = "architectureBaselineId")] pub(crate) architecture_baseline_id: String, pub(crate) repository: String, + #[serde(rename = "requiredPathSha256")] + pub(crate) required_path_sha256: std::collections::BTreeMap, } /// 上游 Root ABI bundle（镜像内 `packages/abi/root-abi-bundle.json`）。 @@ -69,6 +71,60 @@ pub(crate) fn mirror_root(workspace_root: &Path, lock: &ArchitectureLock) -> Pat .join(&lock.architecture_baseline_id) } +/// 上游 bundle 在架构源树内的路径，也是它在 lock `requiredPathSha256` 里的键。 +pub(crate) const BUNDLE_SOURCE_PATH: &str = "packages/abi/root-abi-bundle.json"; + +/// 上游 ABI 文档在架构源树内的路径（上游 `ABI_DOCUMENT`），也在 `inputSet` 内。 +pub(crate) const ABI_DOCUMENT_SOURCE_PATH: &str = "fixtures/valid/native-managed-abi.json"; + +/// 读取并**对着 lock 校验**上游 bundle。 +/// +/// bundle 是整条摘要链的根：compiler 身份、inputHash、每份产物的期望摘要都取自它。 +/// 无条件采信它等于把锚点放在一个可被就地改写的本地文件上——改 bundle 里的三个 +/// outputFiles.digest，再按同一规则重建 descriptor，六份产物就能被整体替换而校验全绿。 +/// lock 的 `requiredPathSha256` 正是这份文件的登记摘要，这里必须读。 +pub(crate) fn read_bundle_verified( + mirror: &Path, + lock: &ArchitectureLock, +) -> Result { + let path = mirror.join(BUNDLE_SOURCE_PATH); + let bytes = std::fs::read(&path).map_err(|e| { + err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!( + "上游 Root ABI bundle 不可用（{}：{e}）；AG-001 对本仓未关闭，\ + 不得回退本仓模板", + path.display() + ), + ) + })?; + let registered = lock + .required_path_sha256 + .get(BUNDLE_SOURCE_PATH) + .ok_or_else(|| { + err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!("architecture.lock.json 未登记 {BUNDLE_SOURCE_PATH}"), + ) + })?; + let actual = crate::sha256_hex(&bytes); + if &actual != registered { + return Err(err( + AbiGenerationErrorKind::InputHashMismatch, + format!( + "上游 bundle 与 lock 登记摘要不符（镜像 {actual}，lock {registered}）：\ + 摘要链的根不可信，拒绝继续" + ), + )); + } + serde_json::from_str( + std::str::from_utf8(&bytes) + .map_err(|e| invalid(format!("{} 不是 UTF-8：{e}", path.display())))?, + ) + .map_err(|e| invalid(format!("解析 {} 失败：{e}", path.display()))) +} + +#[allow(dead_code)] pub(crate) fn read_bundle(mirror: &Path) -> Result { let path = mirror.join("packages/abi/root-abi-bundle.json"); // bundle 不在镜像里 = 上游还没把本仓列为 Root ABI 的 consumer = AG-001 对本仓未关闭。 @@ -86,16 +142,20 @@ pub(crate) fn read_bundle(mirror: &Path) -> Result Result { +) -> Result<(String, std::collections::BTreeMap), AbiGenerationError> { let mut parts: Vec> = Vec::with_capacity(bundle.input_set.len()); + let mut per_file = std::collections::BTreeMap::new(); for relative in &bundle.input_set { let path = mirror.join(relative); let blob = std::fs::read(&path).map_err(|e| { @@ -108,6 +168,7 @@ pub(crate) fn compute_input_hash( item.push(0); item.extend_from_slice(&blob); parts.push(item); + per_file.insert(relative.clone(), crate::sha256_hex(&blob)); } - Ok(crate::sha256_hex(&parts.join(&b'\n'))) + Ok((crate::sha256_hex(&parts.join(&b'\n')), per_file)) } diff --git a/modules/root-abi/generator/src/lib.rs b/modules/root-abi/generator/src/lib.rs index 80c7d4d..020c250 100644 --- a/modules/root-abi/generator/src/lib.rs +++ b/modules/root-abi/generator/src/lib.rs @@ -54,7 +54,10 @@ pub struct GenerateAbiRequest { /// Root ABI 的输入集合**全部**由上游 bundle 的 `inputSet` 声明且都在只读镜像内， /// 与 BuildPlan 无交集；计划在这里的作用是**交叉核对**——它记的 architecture /// 基线与提交必须与本仓 lock 一致，否则「按 A 计划构建、按 B 基线生成 ABI」 - /// 会一路无声地走到运行时。给了就强制核对（CLI 总是给），不给则跳过该核对。 + /// 会一路无声地走到运行时。 + /// + /// **`Option` 意味着这条核对可被跳过**——给了才查，不给则不查。相对规格（那里是 + /// 必需字段）这是一处弱化，理由与取舍记在 ADR 0009 第 2 节，不只留在这条注释里。 pub frozen_plan_path: Option, pub architecture_lock_path: PathBuf, /// 只读镜像根；`None` 表示按 lock 的基线 id 从 workspace 推导。 @@ -115,7 +118,7 @@ fn build_files(request: &GenerateAbiRequest) -> Result path.clone(), None => input_set::mirror_root(&workspace_root, &lock), }; - let bundle = input_set::read_bundle(&mirror)?; + let bundle = input_set::read_bundle_verified(&mirror, &lock)?; // 计划与 lock 的基线/提交必须一致。计划经 composition 的只读入口取得—— // 那是唯一合法的读法（ADR 0006 第 8 条：消费者不得自建第二套解析器）。 @@ -166,7 +169,7 @@ fn build_files(request: &GenerateAbiRequest) -> Result Result Result Result>, + validator_ran: bool, + entry_symbol: &str, + input_file_digests: &BTreeMap, ) -> serde_json::Value { serde_json::json!({ "kind": "root-abi-generated-contract-artifact", @@ -285,6 +313,10 @@ fn build_descriptor( }, "inputHash": input_hash, "outputHash": output_hash, + "inputSet": bundle.input_set, + "inputFileDigests": input_file_digests, + "entrySymbol": entry_symbol, + "validatorRan": validator_ran, "registeredFiles": output_set::registered_files(), "fileDigests": files .iter() @@ -332,7 +364,7 @@ pub fn verify_generated( let lock = input_set::read_lock(lock_path)?; let workspace_root = workspace_root_of(lock_path)?; let mirror = input_set::mirror_root(&workspace_root, &lock); - let bundle = input_set::read_bundle(&mirror)?; + let bundle = input_set::read_bundle_verified(&mirror, &lock)?; let descriptor_path = root.join("generated-contract-artifact.json"); let descriptor: serde_json::Value = serde_json::from_slice( @@ -392,7 +424,39 @@ pub fn verify_generated( } } - let input_hash = input_set::compute_input_hash(&mirror, &bundle)?; + // metadata/ 与 reports/ 的独立锚点。没有这两条，它们唯一的约束是 descriptor 的 + // fileDigests——而 descriptor 正是从同一批盘上字节重建出来的，被背书者与背书者同源， + // 整份替换 ABI 文档再重建 descriptor 即可全绿（审查实测）。 + let mirrored_abi = mirror.join(input_set::ABI_DOCUMENT_SOURCE_PATH); + let mirrored_bytes = std::fs::read(&mirrored_abi) + .map_err(|e| invalid(format!("读取 {} 失败：{e}", mirrored_abi.display())))?; + let published_abi = files + .get("metadata/native-managed-abi.json") + .expect("登记表已保证存在"); + if published_abi != &mirrored_bytes { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!( + "metadata/native-managed-abi.json 已被改动：与镜像 {} 不一致", + mirrored_abi.display() + ), + )); + } + + let layout = layout_verify::check(&bundle, &bundle.layout_profile)?; + let expected_report = canonical_json(&layout.report)?; + let published_report = files + .get("reports/layout-report.json") + .expect("登记表已保证存在"); + if published_report != &expected_report { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + "reports/layout-report.json 已被改动：与按上游 layoutProfile 现算的内容不一致" + .to_string(), + )); + } + + let (input_hash, input_file_digests) = input_set::compute_input_digests(&mirror, &bundle)?; let output_hash = output_set::compute_output_hash(&files); // descriptor 自身也必须被校验。按同一规则重建后逐字节比对—— @@ -404,6 +468,15 @@ pub fn verify_generated( &input_hash, &output_hash, &files, + descriptor + .get("validatorRan") + .and_then(serde_json::Value::as_bool) + .unwrap_or(false), + descriptor + .get("entrySymbol") + .and_then(serde_json::Value::as_str) + .unwrap_or_default(), + &input_file_digests, ))?; let actual_descriptor = std::fs::read(&descriptor_path) .map_err(|e| invalid(format!("读取 {} 失败：{e}", descriptor_path.display())))?; @@ -422,20 +495,55 @@ pub fn verify_generated( .and_then(|value| value.as_str()) .unwrap_or_default(); - let layout = layout_verify::check(&bundle, &bundle.layout_profile)?; + // 报告只声称**本次真的做过**的检查。 + // + // schema / semantic：`verify_generated` 不跑上游 validator（它需要锁定 compiler 在场， + // 而回读校验必须能在没有工具链的机器上进行）。这两项的依据是 descriptor 记录的 + // `validatorRan` —— 生成期由上游 `validate_abi_document` 实际执行并在失败时中止； + // descriptor 本身已被逐字节重建校验过，所以这条记录改不动。 + // symbols：真查一次——ABI 文档声明的 entrySymbol 必须出现在发布的 C Header 里。 + let validator_ran = descriptor + .get("validatorRan") + .and_then(serde_json::Value::as_bool) + .unwrap_or(false); + let entry_symbol = descriptor + .get("entrySymbol") + .and_then(serde_json::Value::as_str) + .unwrap_or_default(); + let header = files + .get("include/lumio_core.h") + .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) + .unwrap_or_default(); + let symbols_valid = !entry_symbol.is_empty() && header.contains(entry_symbol); + if !symbols_valid { + return Err(err( + AbiGenerationErrorKind::OutputHashMismatch, + format!("发布的 C Header 里找不到 ABI 文档声明的 entrySymbol {entry_symbol}"), + )); + } + Ok(AbiCompatibilityReport { abi_identity: format!("{}/{}", bundle.baseline_id, bundle.bundle_id), - schema_valid: true, - semantic_rules_valid: true, + schema_valid: validator_ran, + semantic_rules_valid: validator_ran, c_layout_valid: layout.c_valid, rust_layout_valid: layout.rust_valid, csharp_layout_valid: layout.csharp_valid, - symbols_valid: true, + symbols_valid, input_hash_matches: input_hash == recorded_input_hash, - output_hash_matches: true, + output_hash_matches: output_hash == recorded_output_hash(&descriptor), }) } +/// descriptor 记录的 outputHash。descriptor 已被逐字节重建校验，所以它是可信的。 +fn recorded_output_hash(descriptor: &serde_json::Value) -> String { + descriptor + .get("outputHash") + .and_then(serde_json::Value::as_str) + .unwrap_or_default() + .to_string() +} + fn collect_files(root: &Path, dir: &Path, out: &mut Vec) -> Result<(), AbiGenerationError> { for entry in std::fs::read_dir(dir).map_err(|e| invalid(format!("读取 {} 失败：{e}", dir.display())))? diff --git a/modules/root-abi/generator/tests/compiler_lock.rs b/modules/root-abi/generator/tests/compiler_lock.rs index 5dcf8b9..a6ecdd1 100644 --- a/modules/root-abi/generator/tests/compiler_lock.rs +++ b/modules/root-abi/generator/tests/compiler_lock.rs @@ -35,18 +35,21 @@ fn available() -> bool { compiler_directory().join("lumio_generate.py").is_file() } -/// 没取过工具链时跳过，并把原因说清楚——测试静默跳过与通过长得一样，那正是本仓 -/// B-00002 要消灭的形态。 +/// 缺工具链时**失败**，不是跳过。 +/// +/// 首版写的是 `eprintln! + return`——那等于测试通过，libtest 还会把提示吞掉： +/// 在没取过工具链的机器上，这 6 个测试恒为绿且恒为空，而本卡四条通过条件的全部证据 +/// 都挂在它们身上。这正是本仓 B-00002（空跑输出非绿灯信号）刚修过的同型问题， +/// 宏自己的注释还写着要消灭它。 macro_rules! require_compiler { () => { - if !available() { - eprintln!( - "SKIP: 未找到锁定 compiler（{}）。\ - 先跑 `LUMIO_ARCHITECTURE_REPO=<架构源仓> just fetch-architecture-tools`。", - compiler_directory().display() - ); - return; - } + assert!( + available(), + "未找到锁定 compiler（{}）。\ + 先跑 `LUMIO_ARCHITECTURE_REPO=<架构源仓> just fetch-architecture-tools`。\ + 本测试不跳过——跳过与通过在输出里长得一样。", + compiler_directory().display() + ); }; } @@ -221,3 +224,142 @@ fn an_unregistered_file_in_the_output_directory_is_rejected() { assert_eq!(error.kind(), AbiGenerationErrorKind::UnregisteredFile); let _ = std::fs::remove_dir_all(&out); } + +/// 审查实测的两条绕过路径：改一份没有独立锚点的产物，再按同一规则重建 descriptor。 +/// 首版这两条都能让校验全绿——descriptor 是从同一批盘上字节重建的，被背书者与 +/// 背书者同源，恒等式证明不了任何东西。 +#[test] +fn rewriting_a_local_only_artifact_and_its_descriptor_entry_is_still_caught() { + require_compiler!(); + let lock = repo_root().join("architecture.lock.json"); + + for (which, relative) in [ + "metadata/native-managed-abi.json", + "reports/layout-report.json", + ] + .into_iter() + .enumerate() + { + let out = temp_out(&format!("collusion-{which}")); + generate(request(out.clone())).expect("生成成功"); + + // 改产物本身。 + let target = out.join(relative); + let mut permissions = std::fs::metadata(&target).expect("取权限").permissions(); + #[allow(clippy::permissions_set_readonly_false)] + permissions.set_readonly(false); + std::fs::set_permissions(&target, permissions).expect("恢复写权限"); + std::fs::write(&target, b"{\"tampered\":1}\n").expect("写入伪造内容"); + + // 同步把 descriptor 里对应的摘要、outputHash 一并改成新值—— + // 也就是「攻击者按同一规则重建 descriptor」。 + let descriptor_path = out.join("generated-contract-artifact.json"); + let mut permissions = std::fs::metadata(&descriptor_path) + .expect("取权限") + .permissions(); + #[allow(clippy::permissions_set_readonly_false)] + permissions.set_readonly(false); + std::fs::set_permissions(&descriptor_path, permissions).expect("恢复写权限"); + rebuild_descriptor_in_place(&out); + + let error = + verify_generated(&out, &lock).expect_err(&format!("{relative} 被改后必须仍被发现")); + assert_eq!(error.kind(), AbiGenerationErrorKind::OutputHashMismatch); + let _ = std::fs::remove_dir_all(&out); + } +} + +/// 按发布目录里的实际字节重算 descriptor 的 fileDigests 与 outputHash 并写回， +/// 模拟「攻击者也会重建 descriptor」。 +fn rebuild_descriptor_in_place(root: &Path) { + let script = r#" +import hashlib, json, sys +from pathlib import Path +root = Path(sys.argv[1]) +descriptor_path = root / "generated-contract-artifact.json" +descriptor = json.loads(descriptor_path.read_text()) +files = {} +for name in descriptor["registeredFiles"]: + if name == "generated-contract-artifact.json": + continue + files[name] = (root / name).read_bytes() +descriptor["fileDigests"] = {k: hashlib.sha256(v).hexdigest() for k, v in files.items()} +parts = [k.encode() + b"\x00" + v for k, v in sorted(files.items())] +descriptor["outputHash"] = hashlib.sha256(b"\n".join(parts)).hexdigest() +descriptor_path.write_bytes(json.dumps(descriptor, ensure_ascii=False, separators=(",", ":")).encode() + b"\n") +"#; + let status = std::process::Command::new("python3") + .arg("-c") + .arg(script) + .arg(root) + .status() + .expect("重建 descriptor"); + assert!(status.success()); +} + +#[test] +fn tampering_with_the_upstream_bundle_is_caught_by_the_lock() { + require_compiler!(); + // 摘要链的根：bundle 若不与 lock 对账，改它的 outputFiles.digest 就能整体移动锚点。 + let scratch = temp_out("bad-bundle"); + let workspace = scratch.join("ws"); + let baseline = baseline_id(); + let mirror = workspace.join(format!("generated/architecture/{baseline}")); + std::fs::create_dir_all(mirror.join("packages/abi")).expect("建镜像目录"); + std::fs::copy( + repo_root().join("architecture.lock.json"), + workspace.join("architecture.lock.json"), + ) + .expect("复制 lock"); + let bundle_source = repo_root().join(format!( + "generated/architecture/{baseline}/packages/abi/root-abi-bundle.json" + )); + let mut bundle = std::fs::read_to_string(&bundle_source).expect("读 bundle"); + bundle.push(' '); // 一个字节即可 + std::fs::write(mirror.join("packages/abi/root-abi-bundle.json"), bundle) + .expect("写伪造 bundle"); + + let error = generate(GenerateAbiRequest { + frozen_plan_path: None, + architecture_lock_path: workspace.join("architecture.lock.json"), + mirror_root: Some(mirror), + compiler_directory: compiler_directory(), + output_directory: scratch.join("out"), + }) + .expect_err("bundle 与 lock 不符必须失败"); + assert_eq!(error.kind(), AbiGenerationErrorKind::InputHashMismatch); + assert!(!scratch.join("out").exists(), "失败不得留下输出目录"); + let _ = std::fs::remove_dir_all(&scratch); +} + +#[test] +fn a_compiler_with_correct_files_but_altered_bytes_is_rejected() { + require_compiler!(); + // 走的是摘要比较分支，而不是「文件不存在」分支。 + let scratch = temp_out("drifted-compiler"); + let fake = scratch.join("tools"); + std::fs::create_dir_all(&fake).expect("建目录"); + for name in ["lumio_contract.py", "lumio_generate.py"] { + let mut bytes = std::fs::read(compiler_directory().join(name)).expect("读 compiler"); + if name == "lumio_generate.py" { + bytes.push(b' '); + } + std::fs::write(fake.join(name), bytes).expect("写漂移后的 compiler"); + } + + let mut request = request(scratch.join("out")); + request.compiler_directory = fake; + let error = generate(request).expect_err("compiler 字节漂移必须失败"); + assert_eq!(error.kind(), AbiGenerationErrorKind::CompilerDigestMismatch); + assert!(!scratch.join("out").exists()); + let _ = std::fs::remove_dir_all(&scratch); +} + +fn baseline_id() -> String { + let lock = + std::fs::read_to_string(repo_root().join("architecture.lock.json")).expect("读 lock"); + let key = "\"architectureBaselineId\": \""; + let start = lock.find(key).expect("有基线 id") + key.len(); + let end = start + lock[start..].find('"').expect("引号结束"); + lock[start..end].to_string() +} diff --git a/modules/root-abi/generator/tests/no_private_schema.rs b/modules/root-abi/generator/tests/no_private_schema.rs index 162e6ac..c68e02e 100644 --- a/modules/root-abi/generator/tests/no_private_schema.rs +++ b/modules/root-abi/generator/tests/no_private_schema.rs @@ -5,6 +5,15 @@ //! ABI 定义处，而两处定义迟早会分叉——那正是规格 §4「私有模板会制造第二 ABI」要防的。 //! //! 这些断言是**源码级**的：它们不跑生成，只看本 crate 的代码里有没有出现不该有的东西。 +//! +//! **能力边界（别把它当成完备防线）**：下面前三条是关键词黑名单，绕过方式是现成的 +//! ——换成 Rust 常规命名（`pointer_bytes`）、把 `const` 与字段写在不同行、用 +//! `"unsigned int"` 之类避开 stdint 拼写、或用 raw string + `#ifndef` 写 header 模板， +//! 都不会命中。它们能挡的是**无意间**把上游语义抄进来，挡不住有意为之。 +//! 唯一结构性的是最后一条（`src/` 下不得有非 `.rs` 文件），它挡住「模板外置成 +//! `templates/*.h.in` 再 include_str!」这条最省事的路。真正的保证来自评审与 +//! `compiler_lock.rs` 的摘要对账：本仓产出的每一份字节都必须等于上游声明的摘要， +//! 自己写的模板产不出那个值。 use std::path::{Path, PathBuf}; @@ -139,3 +148,26 @@ fn generator_does_not_read_the_architecture_source_working_tree() { } } } + +#[test] +fn src_contains_only_rust_sources() { + // 结构性断言（不是关键词匹配）：模板一旦外置成 `src/templates/*.h.in` 再 + // `include_str!`，前面三条黑名单全部失效——非 .rs 文件根本不在它们的扫描范围内。 + fn walk(dir: &Path, offenders: &mut Vec) { + for entry in std::fs::read_dir(dir).expect("读源码目录") { + let path = entry.expect("目录项").path(); + if path.is_dir() { + walk(&path, offenders); + } else if path.extension().and_then(|e| e.to_str()) != Some("rs") { + offenders.push(path); + } + } + } + let mut offenders = Vec::new(); + walk(&source_directory(), &mut offenders); + assert!( + offenders.is_empty(), + "src/ 下出现了非 Rust 文件：{offenders:?}。模板/type map 属上游 compiler，\ + 本仓不得以任何形式持有第二份" + ); +} From 56e0be5c2e4dac040ddbcdb744f7636640239e86 Mon Sep 17 00:00:00 2001 From: Cui Date: Sat, 29 Aug 2026 17:01:14 +0800 Subject: [PATCH 3/4] =?UTF-8?q?fix(root-abi):=20descriptor=20=E7=9A=84?= =?UTF-8?q?=E4=B8=A4=E4=B8=AA=E8=87=AA=E8=AF=81=E5=AD=97=E6=AE=B5=E6=94=B9?= =?UTF-8?q?=E7=94=A8=E5=A4=96=E9=83=A8=E7=9C=9F=E5=80=BC=EF=BC=88R-00018?= =?UTF-8?q?=20=E5=A4=8D=E5=AE=A1=20P1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修 P1-4 时引入了 ADR 0009 第 1 节判据的直接违例：重建 descriptor 时，validatorRan 与 entrySymbol 是从**被校验对象自己**取回去的，于是逐字节比对对这两个字段恒真。reviewer 实测：只改 descriptor 一个字段、不动任何产物，verify-generated 直接 exit 0。 这条盲区正好落在 hand_editing 测试的形状之外——那个测试往每份文件**追加**一个空格， 追加会被重建比对抓到，**替换**自证字段的值不会。 两处分别修，理由不同： - entrySymbol 有外部真值：镜像里的 ABI 文档（已被 inputHash → bundle → lock 钉死）。 重建与 symbols 检查都改用它，descriptor 里那份只作记录不作判据。 - validatorRan 记录的是生成期事件，回读期**不可能**外部重建。所以不假装它受保护： 重建时传字面量 true，任何非 true 的取值都造成字节不符而硬失败，语义上等于 「自称 validator 没跑过的制品一律拒收」。这同时补上了「validatorRan=false 仍 exit 0」 这个门禁洞。 原则写进 ADR 0009 第 3 节：**回读期无法外部重建的字段，不要假装它受保护**——要么以 字面量参与重建，要么换一个有外部真值的来源。同时订正三处做了错误安全声称的文档 （lib.rs、compiler.rs、ADR 第 3 节与后果段）——ADR 第 1 节的判据与第 3 节的机制此前是 互相矛盾的，那是本卡新写的规范，不能带着自相矛盾进主干。 新增 replacing_a_self_reported_descriptor_field_is_caught 覆盖三组替换。 同批 P2： - 删掉未经 lock 校验的 read_bundle（它紧挨着 read_bundle_verified，下一个人有一半概率 拿错那个）。 - ABI 文档路径统一由 input_set::abi_document_path 给出，并断言它**在 inputSet 内**—— 「在 inputSet 内」正是这个锚点成立的前提，此前只写在注释里；同时与 compiler 自报的 路径交叉核对，上游改 ABI_DOCUMENT 时响亮失败。 - 临时 contract root 改排他 create_dir，与 publish.rs 同一口径。 - error.rs 补明 CompilerInvocationFailed 这一桶同时覆盖宿主环境缺失与 ABI 内容非法两类， 不要按码值反推语义（reviewer 复审后不坚持拆码，理由是加进 validator 后这一桶里确实 装着真实的内容失败）。 测试 13 → 15（compiler_lock 10 + no_private_schema 5）；上轮交回物写的 13 是错的。 三摘要不变：217437fd… / 696a58d0… / bdbab5d3…。 Co-Authored-By: Claude Fable 5 --- ...009-root-abi-generator-adapter-boundary.md | 18 +++-- modules/root-abi/generator/Cargo.toml | 4 ++ modules/root-abi/generator/src/compiler.rs | 14 ++-- modules/root-abi/generator/src/error.rs | 4 ++ modules/root-abi/generator/src/input_set.rs | 47 +++++++------ modules/root-abi/generator/src/lib.rs | 57 +++++++++------- .../root-abi/generator/tests/compiler_lock.rs | 66 +++++++++++++++++++ 7 files changed, 159 insertions(+), 51 deletions(-) diff --git a/.spec/decisions/0009-root-abi-generator-adapter-boundary.md b/.spec/decisions/0009-root-abi-generator-adapter-boundary.md index 2308ec1..39cd392 100644 --- a/.spec/decisions/0009-root-abi-generator-adapter-boundary.md +++ b/.spec/decisions/0009-root-abi-generator-adapter-boundary.md @@ -66,9 +66,15 @@ LCE-P0-005 要把架构源的 Root ABI 制品接进本仓。规格 §8.3 给了 规则：`AbiCompatibilityReport` 的每个字段只能反映**本次真的做过**的检查。做不到的项要么 补上检查，要么改成能表达「未做此项」的形式，不得填 `true`。 -`verify_generated` 不跑 validator（回读校验必须能在没有工具链的机器上进行），它的 -schema/semantic 依据是 descriptor 记录的 `validatorRan` —— 而 descriptor 已被逐字节重建 -校验，这条记录改不动。 +`verify_generated` 不跑 validator（回读校验必须能在没有工具链的机器上进行）。它的 +schema/semantic 依据是「descriptor 以 `validatorRan: true` 重建后逐字节相符」——重建时传的是 +**字面量** `true`，不是从 descriptor 读回来的值。 + +这个区别是本 ADR 第 1 节判据的直接应用，也是第一版修复踩过的坑：把 `validatorRan` 与 +`entrySymbol` 从被校验对象自己取回去参与重建，逐字节比对对这两个字段就恒真，改它们 +`verify-generated` 直接 exit 0。**回读期无法外部重建的字段，不要假装它受保护**——要么以 +字面量参与重建（等于「取值不符即拒收」），要么换一个有外部真值的来源。`entrySymbol` 属 +后者：它的外部真值是镜像里的 ABI 文档，已被 inputHash → bundle → lock 钉死。 ### 4. 上游输出集合以上游为准 @@ -88,7 +94,9 @@ contract root，用完即删。镜像本身不动（受 lock 约束且已置只 - 生成与回读各多读一次 lock 与镜像输入，代价是几个文件的 I/O，换来锚点不可被就地移动。 - `check-generated` 与 `check-contracts` 的职责仍然分离（后者管镜像整体完整性），但本卡不再 依赖调用者「记得两条都跑」——bundle 对 lock 的校验在生成器内部完成。 -- LCE-P0-014 / LCE-P0-008 等消费 `AbiCompatibilityReport` 的卡，可以按字段面信任它，因为每个 - 字段都对应一次真实检查。 +- LCE-P0-014 / LCE-P0-008 等消费 `AbiCompatibilityReport` 的卡，可以按字段面信任它：每个字段 + 要么对应本次真实执行的检查（`symbols_valid`、三项 layout、两个 hash），要么对应一条 + 「不满足即在返回之前失败」的前置（`schema_valid` / `semantic_rules_valid`——它们为 true + 的唯一路径是 descriptor 以 `validatorRan: true` 重建成功）。没有字段是无条件常量。 - 本 ADR 不改变 ADR 0001—0004、0006、0008 的任何边界，不新增依赖边（`root-abi-generator -> composition` 在 ADR 0004 第 3 条冻结的允许边内），不定义任何公共 Schema / ID / FFI 语义。 diff --git a/modules/root-abi/generator/Cargo.toml b/modules/root-abi/generator/Cargo.toml index f6f44fd..9c19922 100644 --- a/modules/root-abi/generator/Cargo.toml +++ b/modules/root-abi/generator/Cargo.toml @@ -21,6 +21,10 @@ sha2 = { workspace = true } # 已冻结计划的唯一合法读法（ADR 0006 第 8 条：消费者不得自建第二套解析器）。 lumio-core-composition = { path = "../../composition", version = "0.1.0" } +[dev-dependencies] +# 测试要按字段改写 descriptor 来构造反例。 +serde_json = { workspace = true } + [[bin]] name = "lumio-core-root-abi-generator" path = "src/bin/lumio-core-root-abi-generator.rs" diff --git a/modules/root-abi/generator/src/compiler.rs b/modules/root-abi/generator/src/compiler.rs index 1a34dfd..33f9135 100644 --- a/modules/root-abi/generator/src/compiler.rs +++ b/modules/root-abi/generator/src/compiler.rs @@ -99,13 +99,19 @@ pub(crate) struct CompilerOutput { pub(crate) compiler_version: String, #[serde(rename = "bundleId")] pub(crate) bundle_id: String, - /// 上游 ABI 文档在架构源树内的相对路径——本仓据此把它锚回 `inputSet`。 + /// compiler 自报的 ABI 文档路径。**不作为路径来源**（那份由 + /// `input_set::abi_document_path` 给出并断言在 `inputSet` 内），只用来交叉核对： + /// 两者不一致说明上游改了 `ABI_DOCUMENT` 而本仓常量没跟上。 #[serde(rename = "abiDocumentPath")] pub(crate) abi_document_path: String, #[serde(rename = "entrySymbol")] pub(crate) entry_symbol: String, /// 上游 `validate_abi_document` 已执行的凭据。DRIVER 里它在任何 emit 之前调用， - /// 抛异常即整个进程非零退出，所以这个字段为 true 等价于「校验通过」。 + /// 抛异常即整个进程非零退出——所以**在生成期**这个字段为 true 等价于校验通过。 + /// + /// 回读期不同：它记录的是一个已经过去的事件，无法从任何外部真值重建。 + /// `verify_generated` 因此不读它，而是以字面量 `true` 参与 descriptor 重建 + /// ——自称没跑过 validator 的制品会因字节不符被拒收。 #[serde(rename = "validatorRan")] pub(crate) validator_ran: bool, } @@ -151,8 +157,8 @@ fn build_contract_root( format!("{:016x}", hasher.finish()) }; let root = std::env::temp_dir().join(format!("lce-abi-contract-root-{nonce}")); - let _ = std::fs::remove_dir_all(&root); - std::fs::create_dir_all(&root).map_err(|e| { + // 排他创建，与 publish.rs 同一口径：撞名应当报错，不是静默复用别人的目录。 + std::fs::create_dir(&root).map_err(|e| { err( AbiGenerationErrorKind::CompilerInvocationFailed, format!("创建 compiler 运行根目录失败：{e}"), diff --git a/modules/root-abi/generator/src/error.rs b/modules/root-abi/generator/src/error.rs index c645a91..3abca81 100644 --- a/modules/root-abi/generator/src/error.rs +++ b/modules/root-abi/generator/src/error.rs @@ -12,6 +12,10 @@ pub enum AbiGenerationErrorKind { /// 锁定 compiler 的 SHA-256 与上游 bundle 声明的 `compiler.digest` 不符。 CompilerDigestMismatch, /// 调用锁定 compiler 失败（进程起不来、非零退出、输出不可解析）。 + /// + /// 这一桶同时覆盖两类：**宿主环境缺失**（python3 没装）与 **ABI 内容非法** + /// （上游 validator 拒绝了 ABI 文档）。都归 exit 3，不要按码值反推语义—— + /// 为前者单开一条码路，收益不抵成本，而错误消息本身一眼可辨。 CompilerInvocationFailed, /// 输入集合摘要与上游 bundle 声明的 `inputHash` 不符。 InputHashMismatch, diff --git a/modules/root-abi/generator/src/input_set.rs b/modules/root-abi/generator/src/input_set.rs index 3e339bb..4d93d32 100644 --- a/modules/root-abi/generator/src/input_set.rs +++ b/modules/root-abi/generator/src/input_set.rs @@ -74,8 +74,33 @@ pub(crate) fn mirror_root(workspace_root: &Path, lock: &ArchitectureLock) -> Pat /// 上游 bundle 在架构源树内的路径，也是它在 lock `requiredPathSha256` 里的键。 pub(crate) const BUNDLE_SOURCE_PATH: &str = "packages/abi/root-abi-bundle.json"; -/// 上游 ABI 文档在架构源树内的路径（上游 `ABI_DOCUMENT`），也在 `inputSet` 内。 -pub(crate) const ABI_DOCUMENT_SOURCE_PATH: &str = "fixtures/valid/native-managed-abi.json"; +/// 上游 ABI 文档在架构源树内的路径（上游 `ABI_DOCUMENT`）。 +/// +/// 「它在 `inputSet` 内」是把它当锚点的**前提**——不在的话它就没被 inputHash 钉住， +/// 拿它去锚 metadata/ 等于换了个自证。所以这条前提由 [`abi_document_path`] 每次断言， +/// 不靠这行注释。 +const ABI_DOCUMENT_SOURCE_PATH: &str = "fixtures/valid/native-managed-abi.json"; + +/// 取 ABI 文档路径，并断言它确实在 `inputSet` 里。 +pub(crate) fn abi_document_path( + bundle: &RootAbiBundle, +) -> Result<&'static str, AbiGenerationError> { + if !bundle + .input_set + .iter() + .any(|entry| entry == ABI_DOCUMENT_SOURCE_PATH) + { + return Err(err( + AbiGenerationErrorKind::BlockedOnArchitectureGate, + format!( + "{ABI_DOCUMENT_SOURCE_PATH} 不在上游 inputSet {:?} 内：\ + 它没有被 inputHash 钉住，不能充当 metadata/ 的锚点", + bundle.input_set + ), + )); + } + Ok(ABI_DOCUMENT_SOURCE_PATH) +} /// 读取并**对着 lock 校验**上游 bundle。 /// @@ -124,24 +149,6 @@ pub(crate) fn read_bundle_verified( .map_err(|e| invalid(format!("解析 {} 失败：{e}", path.display()))) } -#[allow(dead_code)] -pub(crate) fn read_bundle(mirror: &Path) -> Result { - let path = mirror.join("packages/abi/root-abi-bundle.json"); - // bundle 不在镜像里 = 上游还没把本仓列为 Root ABI 的 consumer = AG-001 对本仓未关闭。 - // 这时不得回退到本仓模板（卡面 blocked 行为）。 - let text = std::fs::read_to_string(&path).map_err(|e| { - err( - AbiGenerationErrorKind::BlockedOnArchitectureGate, - format!( - "上游 Root ABI bundle 不可用（{}：{e}）；AG-001 对本仓未关闭，\ - 不得回退本仓模板", - path.display() - ), - ) - })?; - serde_json::from_str(&text).map_err(|e| invalid(format!("解析 {} 失败：{e}", path.display()))) -} - /// 复算 Input Hash 与**逐文件**摘要（规格 §3.6「输入逐文件摘要」）。 /// /// 口径与上游 `abi_input_hash` 完全一致：按 `inputSet` 声明顺序，逐项 diff --git a/modules/root-abi/generator/src/lib.rs b/modules/root-abi/generator/src/lib.rs index 020c250..930495c 100644 --- a/modules/root-abi/generator/src/lib.rs +++ b/modules/root-abi/generator/src/lib.rs @@ -237,7 +237,17 @@ fn build_files(request: &GenerateAbiRequest) -> Result String { let end = start + lock[start..].find('"').expect("引号结束"); lock[start..end].to_string() } + +/// descriptor 里**任何**字段被替换都必须失败，包括那些回读期无法从外部重建的。 +/// +/// 首次修 P1-4 时，`validatorRan` 与 `entrySymbol` 在重建时是从 descriptor 自己取回去的 +/// ——逐字节比对对它们恒真，改这两个字段 `verify-generated` 直接 exit 0。这是 ADR 0009 +/// 第 1 节判据（被背书者与背书者必须不同源）的违例，也正好落在 +/// `hand_editing_…`（往文件**追加**一个空格）的形状之外：追加会被抓到，**替换**不会。 +#[test] +fn replacing_a_self_reported_descriptor_field_is_caught() { + require_compiler!(); + let lock = repo_root().join("architecture.lock.json"); + + for (which, (key, value)) in [ + ("validatorRan", serde_json::Value::Bool(false)), + ( + "entrySymbol", + serde_json::Value::String("lumio".to_string()), + ), + ( + "entrySymbol", + serde_json::Value::String("definitely_not_in_header".to_string()), + ), + ] + .into_iter() + .enumerate() + { + let out = temp_out(&format!("self-reported-{which}")); + generate(request(out.clone())).expect("生成成功"); + let descriptor_path = out.join("generated-contract-artifact.json"); + + let mut permissions = std::fs::metadata(&descriptor_path) + .expect("取权限") + .permissions(); + #[allow(clippy::permissions_set_readonly_false)] + permissions.set_readonly(false); + std::fs::set_permissions(&descriptor_path, permissions).expect("恢复写权限"); + + let mut descriptor: serde_json::Value = + serde_json::from_slice(&std::fs::read(&descriptor_path).expect("读 descriptor")) + .expect("解析 descriptor"); + descriptor[key] = value.clone(); + let mut bytes = serde_json::to_vec(&descriptor).expect("重新序列化"); + bytes.push(b'\n'); + std::fs::write(&descriptor_path, &bytes).expect("写回"); + + let error = verify_generated(&out, &lock) + .unwrap_err_or_panic(&format!("{key} 被替换为 {value} 后必须失败")); + assert_eq!(error.kind(), AbiGenerationErrorKind::OutputHashMismatch); + let _ = std::fs::remove_dir_all(&out); + } +} + +/// `expect_err` 需要 Ok 侧实现 Debug；`AbiCompatibilityReport` 有，但这里想带上自定义 +/// 消息说明是哪一组输入，故自己写一个。 +trait UnwrapErrOrPanic { + fn unwrap_err_or_panic(self, message: &str) -> E; +} + +impl UnwrapErrOrPanic for Result { + fn unwrap_err_or_panic(self, message: &str) -> E { + match self { + Ok(_) => panic!("{message}"), + Err(error) => error, + } + } +} From 30c93fad014e8d8946d7327d69dd2ffb743fec61 Mon Sep 17 00:00:00 2001 From: Cui Date: Sat, 29 Aug 2026 17:08:27 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs(lessons):=20=E6=94=B6=E5=BD=95?= =?UTF-8?q?=E3=80=8C=E5=88=A4=E6=8D=AE=E4=B8=8E=E5=8F=8D=E4=BE=8B=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=E5=BF=85=E9=A1=BB=E5=90=8C=E6=97=B6=E8=AF=9E=E7=94=9F?= =?UTF-8?q?=E3=80=8D=EF=BC=88R-00016/17/18=20=E5=90=8C=E5=9E=8B=E7=AC=AC?= =?UTF-8?q?=E4=BA=8C=E6=AC=A1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reviewer 复审放行时点名这条够格进 lessons：同一失效模式在本批出现两次同型 （ADR 0007 明写用 toml crate 却手写扫描；ADR 0009 写下「被背书者与背书者必须不同源」 却在同提交里让 descriptor 两个字段自证），相邻同族形态还有三次。 根因不是粗心：写规范与执行规范之间没有机械检查，而刚写完规范时最容易觉得自己已经 遵守了。五次里没有一次是通读代码发现的，全部来自实跑构造的反例——已有的 grep 自验 规则只能证明「被声称的 X 存在」，证明不了「X 覆盖的范围等于声称的范围」。 规避写成可验证的行为：判据与它的反例测试同一提交内同时出现；反例的构造方式要覆盖 多种形态（追加一个字节与替换某字段的值覆盖面完全不同）；声称「由 X 覆盖」时另问一句 「X 挡不住的是什么」并写进文档。 Co-Authored-By: Claude Fable 5 --- .spec/knowledge/lessons.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.spec/knowledge/lessons.md b/.spec/knowledge/lessons.md index 6fe6c57..587cee7 100644 --- a/.spec/knowledge/lessons.md +++ b/.spec/knowledge/lessons.md @@ -33,6 +33,14 @@ metadata: ## 条目 +### 新写下的判据，必须在同一提交里有一条按它构造的反例测试 + +- 日期：2026-08-29 +- 现象：写完一条规则，然后在**同一个提交里**违反它，两次同型。① ADR 0007 第 2 节明写「只用 `toml` crate 读 `*.compose.toml` 与 `tools.lock.toml`」并否决自研子集解析器，而同提交的 `toolchain.rs` 就是手写扫描——把 `supported_hosts` 写成语义相同的合法多行数组即误报「登记缺失」，错误信息还反向误导。② ADR 0009 第 1 节写下「被背书者与背书者必须不同源」，而同提交的 `verify_generated` 把 descriptor 的 `validatorRan`/`entrySymbol` 从被校验对象自己取回去参与重建，逐字节比对对这两个字段恒真——只改 descriptor 一个字段、不动任何产物即可放行。相邻的同族形态还有三次：R-00016 的「平行结构靠注释保持同步」、R-00017 的「由仓级 `cargo tree` 断言覆盖」（该断言从未创建）、R-00018 首版的「descriptor 完整性由它记的每一条间接证明」。 +- 根因：写规范与执行规范之间没有机械检查，而**刚写完规范时最容易觉得自己已经遵守了**——判据在脑子里是新鲜的，于是省掉了验证。这类缺陷通读代码发现不了：五次里没有一次是读出来的，全部来自实跑构造的反例。已有的 grep 自验规则只能证明「被声称的 X 存在」，证明不了「X 覆盖的范围等于声称的范围」。 +- 规避：① **判据与它的反例测试同时诞生**——新增一条 ADR 判据或「由 X 保证」的声称时，同一提交内必须有一条按该判据构造的**失败**用例（`replacing_a_self_reported_descriptor_field_is_caught` 就是 ADR 0009 第 1 节的那条，它本该和第 1 节同时写出来）。② 反例的**构造方式要覆盖多种形态**：往文件追加一个字节与替换某个字段的值，是完全不同的覆盖面——前者必然改变字节因而总被抓到，后者可能落在自证盲区里。③ 声称「由 X 覆盖」时，除 grep 验证 X 存在外，再问一句「X 挡不住的是什么」，把答案写进文档而不是省略。 +- 来源：R-00016 / R-00017 / R-00018 三张卡的 reviewer 退回报告（R-00018 经两轮退回，提交 `4a37934` → `7e7447e` → `56e0be5`）。 + ### 跨仓 / 跨会话引用交付时，锚点用 `origin/main:<路径>`，不用裸 commit SHA - 日期：2026-08-28