更完

docs/CORE_GUIDE.md

@@ -56,6 +56,32 @@ struct structive::Type_Descriptor<Device> {
 
 The descriptor is the structural definition of `Device`.
 
+### 3.1 Type-level metadata
+
+Extensions can attach compile-time attributes to the described type itself, independently
+from property metadata and inheritable property defaults:
+
+```cpp
+struct Action_Category {};
+struct Action {
+    using attribute_category = Action_Category;
+    static constexpr bool single_valued = false;
+    static constexpr bool inheritable = false;
+    std::string_view name;
+};
+
+return object<Device>(
+    type_metadata(Action{"reset"}, Action{"calibrate"}),
+    field<&Device::temperature>(key<"temperature">)
+);
+```
+
+Use `Schema::type_attribute_count<Category>`, `Schema::has_type_attribute<Category>`,
+`schema.type_attribute<Category>()` for a single-valued category, and
+`schema.for_each_type_attribute<Category>(callback)` for traversal. Core stores and
+validates the generic Attribute protocol but does not interpret extension-owned categories.
+Type metadata is not a property default and is never copied into individual properties.
+
 ## 4. Schema guarantees
 
 A valid schema guarantees:

docs/CORE_GUIDE.zh-CN.md

@@ -56,6 +56,32 @@ struct structive::Type_Descriptor<Device> {
 
 Descriptor 就是 `Device` 的结构定义。
 
+### 3.1 类型级 Metadata
+
+扩展可以直接给被描述类型附加编译期 Attribute；它与 Property metadata、可继承的
+Property defaults 相互独立：
+
+```cpp
+struct Action_Category {};
+struct Action {
+    using attribute_category = Action_Category;
+    static constexpr bool single_valued = false;
+    static constexpr bool inheritable = false;
+    std::string_view name;
+};
+
+return object<Device>(
+    type_metadata(Action{"reset"}, Action{"calibrate"}),
+    field<&Device::temperature>(key<"temperature">)
+);
+```
+
+通过 `Schema::type_attribute_count<Category>`、`Schema::has_type_attribute<Category>`、
+单值 category 的 `schema.type_attribute<Category>()`，以及
+`schema.for_each_type_attribute<Category>(callback)` 查询。Core 只存储并校验通用
+Attribute 协议，不解释扩展拥有的 category。类型 metadata 不是 Property default，
+不会复制到各个 Property。
+
 ## 4. Schema 静态保证
 
 合法 Schema 保证：

docs/DESIGN.md

@@ -226,6 +226,12 @@ Do not give a read-only stored field a mutex. A computed read uses synchronizati
 
 A Property Descriptor has one metadata store. Its entries are either Attributes or Constraints.
 
+An `Object_Schema` may additionally contain type-level Attributes supplied through
+`type_metadata(...)`. This is the single metadata store for facts about the described type;
+it is deliberately separate from property metadata and from inheritable property defaults.
+Core applies the same Attribute protocol and category uniqueness rules without interpreting
+extension-owned type semantics.
+
 Core and extensions share one Attribute mechanism for descriptive metadata. An Attribute owns a category and declares whether it is single-valued and inheritable. Constraints use the validation protocol but live in the same descriptor metadata store.
 
 Core must not create parallel metadata storage systems for UI, serialization, diagnostics or domain-specific features.

docs/DESIGN.zh-CN.md

@@ -224,6 +224,11 @@ Dependency 必须显式进入 Schema。每个 Property Accessor 都必须声明
 
 Property Descriptor 只有一份 metadata storage，其中的条目只能是 Attribute 或 Constraint。
 
+`Object_Schema` 还可以通过 `type_metadata(...)` 保存类型级 Attribute。这是被描述类型
+自身事实的唯一 metadata storage，明确区别于 Property metadata 和可继承的 Property
+defaults。Core 复用同一个 Attribute 协议与 category 唯一性规则，但不解释 Extension
+拥有的类型语义。
+
 Core 与 Extension 的描述性 metadata 共用 Attribute mechanism。Attribute 拥有 category，并声明 single-valued 与 inheritable 语义；Constraint 使用 validation protocol，但与 Attribute 保存在同一份 descriptor metadata storage 中。
 
 UI、serialization、诊断等新领域不应该另起第二套 metadata storage。