去除internel 访问级别

2026-08-07 17:15:02 +08:00
parent 1ddd2799f2
commit 0c7fac70b2
8 changed files with 270 additions and 159 deletions
@@ -261,7 +261,7 @@ struct Validation_Error {

 Validation is explicit and is not automatically executed by managed writes.

-## 10. Managed internal read/write
+## 10. Intrinsic managed read/write

 Typed member-pointer access:

@@ -277,7 +277,7 @@ auto temperature = device.read_key<"temperature">();
 device.write_key<"temperature">(30.0);
 ```

-These operations use `Managed_Access_Mode::internal`.
+These operations use the property's intrinsic capability directly. There is no separate `internal` capability mode; readability and writability come from the accessor itself.

 `read()` returns a value object, not a reference to storage. The read is performed while the configured shared lock is held when synchronization is enabled.

@@ -564,11 +564,21 @@ erased.runtime_object_type();
 erased.runtime_property_count();
 ```

-Runtime write:
+Intrinsic runtime write does not require a mode:

 ```cpp
 double value = 35.0;
 auto result = erased.runtime_write(
+    "temperature",
+    typeid(double),
+    &value
+);
+```
+
+A boundary projection is selected explicitly when an adapter must respect external or persistence capability metadata:
+
+```cpp
+auto external_result = erased.runtime_write(
    Managed_Access_Mode::external,
    "temperature",
    typeid(double),
@@ -576,7 +586,7 @@ auto result = erased.runtime_write(
 );
 ```

-Runtime read uses a callback:
+Runtime read uses the same overload model and returns the value through a callback:

 ```cpp
 static void read_double(void* context, std::size_t, std::string_view, const std::type_info& type, const void* value) {
@@ -586,6 +596,11 @@ static void read_double(void* context, std::size_t, std::string_view, const std:
 }
 double output = 0.0;
 auto result = erased.runtime_read(
+    "temperature",
+    &output,
+    &read_double
+);
+auto external_result = erased.runtime_read(
    Managed_Access_Mode::external,
    "temperature",
    &output,
@@ -603,7 +618,7 @@ Runtime_Access_Result::not_writable
 Runtime_Access_Result::type_mismatch
 ```

-The runtime path uses the same capability and synchronization rules as typed managed access.
+The intrinsic runtime overload uses the accessor's intrinsic capability and the same synchronization topology as typed `read()`/`write()`. The overload taking `Managed_Access_Mode` applies the selected external or persistence projection before using the same synchronization rules.

 ## 22. Lock policy

@@ -261,7 +261,7 @@ struct Validation_Error {

 Validation 是显式操作，不会在 managed write 中自动执行。

-## 10. Internal Managed Read/Write
+## 10. Intrinsic Managed Read/Write

 成员指针形式：

@@ -277,7 +277,7 @@ auto temperature = device.read_key<"temperature">();
 device.write_key<"temperature">(30.0);
 ```

-这些操作属于 `Managed_Access_Mode::internal`。
+这些操作直接使用 Property 的固有能力，不再存在单独的 `internal` capability mode；可读、可写能力由 accessor 本身决定。

 `read()` 返回值对象而不是底层存储引用。启用同步时，读取发生在配置的 shared lock 持有期间。

@@ -564,11 +564,21 @@ erased.runtime_object_type();
 erased.runtime_property_count();
 ```

-Runtime write：
+Intrinsic runtime write 不需要 mode：

 ```cpp
 double value = 35.0;
 auto result = erased.runtime_write(
+    "temperature",
+    typeid(double),
+    &value
+);
+```
+
+当 adapter 需要遵守 external 或 persistence capability metadata 时，再显式选择边界投影：
+
+```cpp
+auto external_result = erased.runtime_write(
    Managed_Access_Mode::external,
    "temperature",
    typeid(double),
@@ -576,7 +586,7 @@ auto result = erased.runtime_write(
 );
 ```

-Runtime read 通过 callback 返回值：
+Runtime read 使用同样的 overload 模型，并通过 callback 返回值：

 ```cpp
 static void read_double(void* context, std::size_t, std::string_view, const std::type_info& type, const void* value) {
@@ -586,6 +596,11 @@ static void read_double(void* context, std::size_t, std::string_view, const std:
 }
 double output = 0.0;
 auto result = erased.runtime_read(
+    "temperature",
+    &output,
+    &read_double
+);
+auto external_result = erased.runtime_read(
    Managed_Access_Mode::external,
    "temperature",
    &output,
@@ -603,7 +618,7 @@ Runtime_Access_Result::not_writable
 Runtime_Access_Result::type_mismatch
 ```

-Runtime path 与 typed managed access 使用同一套 capability 和 synchronization 规则。
+Intrinsic runtime overload 使用 accessor 的固有能力，并与 typed `read()`/`write()` 使用同一套 synchronization topology。带 `Managed_Access_Mode` 的 overload 会先应用 external 或 persistence 投影，再使用同样的同步规则。

 ## 22. Lock Policy

@@ -218,23 +218,34 @@ This duality is intentional rather than accidental.

 Do not pretend that inheriting `Property_Object<T>` turns public C++ members into encapsulated properties. If a subsystem requires managed synchronization, its coding rules must require the managed path.

-## 11. Capabilities are views, not copies of the object model
+## 11. Intrinsic capability comes before boundary projections

-The same property may have different visibility under different managed modes:
+Every property first has capabilities defined by its accessor itself:

 ```text
-internal
-external
-persistence
+intrinsic
+├── read
+└── write
 ```

-Core derives those capabilities from Attributes and the accessor’s actual read/write abilities.
+Normal managed application code uses those intrinsic capabilities directly through `read()`, `write()`, locks and traversal. `internal` is therefore not a separate capability mode.
+
+External and persistence behavior are boundary projections over that same property definition:
+
+```text
+Property
+├── intrinsic: read / write
+├── external: read / write projection
+└── persistence: load / store projection
+```
+
+Core combines projection Attributes with the accessor's actual abilities. A projection may narrow intrinsic capability, but it must never invent an ability the accessor does not provide.

 An external view should not become a second schema. A persistence view should not become a second schema. They are projections over one schema.

 ### Rule

-**One property definition, multiple capability projections.**
+**One property definition, intrinsic capabilities, explicit boundary projections.**

 ## 12. Validation is metadata plus an explicit operation

@@ -321,7 +332,8 @@ This makes consistency explicit rather than relying on a getter that casually re
 `Property_Object_Base` intentionally provides a type-erased runtime interface using:

 - string key;
- `Managed_Access_Mode`;
+- intrinsic access when no mode is supplied;
+- `Managed_Access_Mode` only when selecting the `external` or `persistence` projection;
 - `std::type_info`;
 - explicit result codes.

@@ -218,23 +218,34 @@ Managed path 会经过 descriptor 和该实例的同步拓扑。

 不要假装继承 `Property_Object<T>` 以后 public member 就自动变成强封装属性。如果某个子系统要求受管理同步，那么该子系统自己的编码约束必须要求使用 managed path。

-## 11. Capability 是 Schema 的投影视图，不是第二套 Schema
+## 11. 固有能力先于边界投影

-同一个属性在不同 managed mode 下可以拥有不同可见性：
+每个 Property 首先拥有 accessor 自身决定的能力：

 ```text
-internal
-external
-persistence
+intrinsic
+├── read
+└── write
 ```

-Core 根据 Attribute 和 accessor 实际读写能力计算这些 capability。
+应用内部的普通 managed code 通过 `read()`、`write()`、lock 和 traversal 直接使用这套固有能力，因此 `internal` 不再是单独的 capability mode。
+
+External 和 Persistence 是同一份 Property definition 之上的边界投影：
+
+```text
+Property
+├── intrinsic: read / write
+├── external: read / write projection
+└── persistence: load / store projection
+```
+
+Core 会把投影 Attribute 与 accessor 的实际能力结合起来。投影可以收窄固有能力，但绝不能凭空创造 accessor 本身不具备的能力。

 External view 不应该发展成第二份 Schema；Persistence view 也不应该成为第二份 Schema。它们都只是同一 Schema 的能力投影。

 ### 原则

-**一份 property definition，多种 capability projection。**
+**一份 property definition，固有能力明确，边界投影显式。**

 ## 12. Validation = 元数据 + 显式操作

@@ -321,7 +332,8 @@ synchronization(
 `Property_Object_Base` 提供 type-erased runtime interface，核心输入包括：

 - string key；
- `Managed_Access_Mode`；
+- 不传 mode 时使用 intrinsic access；
+- 只有选择 `external` 或 `persistence` 投影时才使用 `Managed_Access_Mode`；
 - `std::type_info`；
 - 显式 result code。