# Structive Extension 架构指南

[English](EXTENSIONS.md)

## 1. Extension 的职责

Extension 给 Structive 增加领域 metadata 与领域解释，但不能让 Property Core 反向依赖具体领域。

依赖方向：

```text
Extension → Property Core
Property Core -X→ Extension
```

Core 提供：

- Schema 与 Property Descriptor；
- intrinsic readable/writable；
- Attribute 协议；
- Constraint；
- Synchronization metadata 与 managed access；
- Runtime structural access。

Extension 定义自己的 category 与解释逻辑。

## 2. Extension 基本原则

Extension 只拥有自己的领域语义。

例如 Presentation 拥有：

```text
label
description
group
order
```

Property Core 不需要理解 presentation。

未来 Persistence Extension 可以拥有自己的持久化 metadata，RPC Extension 可以拥有协议 metadata。

## 3. 外部 Policy 永远属于外部

Property Core 完全没有内建访问控制模式。

Extension 或应用层自己负责：

```text
这个属性要不要显示？
这个 endpoint 要不要允许写？
这个 Property 要不要持久化？
当前用户是否有权限？
```

Extension 可以读取结构事实：

```text
Property::readable
Property::writable
sensitive metadata
Extension 自己的 metadata
```

但最终 policy 属于 Consumer。

`read_only` 只表示 Structive managed object 自身没有这个 Property 的写操作，不代表任何外部系统必须暴露它。

## 4. 当前 Presentation Extension

Include：

```cpp
#include <structive/property/extensions/presentation.hpp>
```

Link：

```cmake
target_link_libraries(my_target PRIVATE structive::property_extensions)
```

当前 Attribute：

```cpp
presentation::label<"Temperature">
presentation::description<"Current device temperature">
presentation::group<"Environment">
presentation::order<2>
```

示例：

```cpp
field<&Device::temperature>(
    key<"temperature">,
    unit<"C">,
    presentation::label<"Temperature">,
    presentation::description<"Current device temperature">,
    presentation::group<"Environment">,
    presentation::order<2>
)
```

## 5. Presentation 解释

```cpp
auto info = presentation::describe<&Device::temperature>(device.schema());
```

`Presentation_Info`：

```text
key
label
description
group
order
has_order
```

没有 label 时，Presentation Extension fallback 到 Property key。这个 fallback 属于 Presentation，不属于 Core。

## 6. 可继承 Extension Attribute

Extension category 可以选择 inheritable：

```cpp
defaults(
    presentation::group<"Environment">
)
```

Property-level metadata 覆盖同 category 的 inheritable single-valued default。

只有真正适合继承的 metadata 才应该这样设计。

## 7. 设计新的 Extension Attribute

```cpp
namespace my_extension {
struct Format_Category {};
template <Fixed_String Value>
struct Format_Attribute {
    using attribute_category = Format_Category;
    static constexpr bool single_valued = true;
    static constexpr bool inheritable = false;
    static constexpr auto value = Value;
};
template <Fixed_String Value>
inline constexpr Format_Attribute<Value> format{};
}
```

直接挂在 Property：

```cpp
field<&Device::temperature>(
    key<"temperature">,
    my_extension::format<"0.0 C">
)
```

不需要修改 Core。

## 8. 读取 Extension Attribute

Descriptor-local metadata：

```cpp
using Property = std::remove_cvref_t<decltype(schema.property<&Device::temperature>())>;
static_assert(Property::template has_attribute<my_extension::Format_Category>);
```

可继承 metadata 可以使用 Core 的通用 effective-Attribute 工具。

Fallback 和解释规则由 Extension 自己拥有。

## 9. Multi-Valued Metadata

如果 category 不是 single-valued，Extension 可以允许同 category 多个 Attribute。

只有重复声明本身结构非法时才应该设置 `single_valued = true`。

## 10. 推荐 Extension 边界

适合的领域包括：

- Presentation / Editor Hint；
- Serialization Name / Format Hint；
- Persistence Mapping Metadata；
- RPC / Protocol Naming Metadata；
- Diagnostics / Telemetry Metadata；
- Documentation Metadata。

领域实现继续放在 Property Core 外部。

## 11. 使用 Intrinsic Capability

Consumer 可以把 intrinsic capability 当作结构事实。

例如 Editor 可以先用：

```cpp
Property::writable
```

判断一个 Property 是否具备“可编辑的结构资格”，但 Editor 仍然可以叠加自己的应用 policy。

Persistence Adapter 即使看到 `Property::readable == true`，也完全可以决定不保存它。

RPC Endpoint 即使看到一个 Property writable，也可以完全不暴露它。

这种分离是刻意设计。

## 12. Read-Only 优化属于 Core 保证

Extension 不需要为 stored `read_only` Property 自己实现特殊锁逻辑。

Core 保证这类 Property 不贡献 lock slot 和 mutex，managed read 走 no-lock path。

如果 Extension 故意通过 raw C++ 写它，就已经绕过该保证，同步责任由 Extension 自己承担。

## 13. Fallback 属于 Consumer

Core 不应该决定：

```text
没有 label -> key
没有 database column -> key
没有 RPC name -> key
```

这些 fallback 属于对应 Extension 或 Adapter。

## 14. 防止 Extension 语义泄漏进 Core

不要因为一个 Extension 需要某个概念，就给 Core 增加特殊 enum 或分支。

优先：

```text
Extension-owned Attribute category
+ Extension-owned interpretation
```

而不是：

```text
Core 学会 Extension 领域语义
```

## 15. Header-Only Metadata 与 Linked Code

Metadata 类型通常可以保持 header-only。领域确实需要非模板 runtime behavior 时，再放 linked implementation。

当前 Presentation Extension 把 metadata 放头文件，把 `make_presentation_info` 放 linked target。

## 16. Extension 审核清单

新增 Extension feature 前检查：

1. Core 是否已经提供所需的通用结构机制？
2. 能否表达成 Extension-owned Attribute？
3. Fallback 是否由 Extension 自己拥有？
4. Access / Exposure Policy 是否仍在 Core 外？
5. 是否把 intrinsic `readable/writable` 当结构事实，而不是 authorization？
6. 是否避免无意 raw write 绕过 managed synchronization？
7. Core 是否仍完全独立于 Extension？