7.0.1

.github/workflows/swift.yml

@@ -1,22 +1,45 @@
 # This workflow will build a Swift project
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-swift
+# For more information: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-swift
 
 name: Swift
 
 on:
   push:
-    branches: [ "main" ]
+    branches:
+      - "main"
+      - "fix/smartflat-snapshot-pollution"
+      - "refactor/decoder-context"
   pull_request:
     branches: [ "main" ]
+  workflow_dispatch:
 
 jobs:
   build:
 
     runs-on: macos-latest
+    timeout-minutes: 30
 
     steps:
     - uses: actions/checkout@v4
     - name: Build
       run: swift build -v
     - name: Run tests
       run: swift test -v
+    - name: Build Release
+      run: swift build -c release
+    - name: Test Release
+      run: swift test -c release
+
+  thread-sanitizer:
+
+    runs-on: macos-latest
+    timeout-minutes: 15
+
+    steps:
+    - uses: actions/checkout@v4
+    # 保留全局选项与日志哨兵共享状态的并发回归覆盖。
+    - name: Run Thread Sanitizer concurrency tests
+      run: swift test --sanitize=thread --filter GlobalOptionsConcurrencyTests
+    # 覆盖独立 decoder 并发回退默认值的路径；使用精确过滤器，确保日志能证明目标用例实际执行。
+    - name: Run Thread Sanitizer decoding context concurrency test
+      run: swift test --sanitize=thread --filter DecodingContextTests.testConcurrentIndependentDecodersFallbackDefaultsStayIsolated

CONTRIBUTING.md

@@ -35,8 +35,8 @@ cd SmartCodable
 swift build
 ```
 
-- 最低要求：Swift 5.0、Xcode 14
-- 宏相关功能需要：Swift 5.9、Xcode 15
+- 最低要求：Swift 5.9、Xcode 15（与 `Package.swift` 的 `swift-tools-version: 5.9` 一致）
+- 宏相关功能在配套库 SmartCodableMacro 中，同样要求 Swift 5.9、Xcode 15
 
 ### 开发流程
 
@@ -48,9 +48,9 @@ swift build
 ### 代码规范
 
 - **不破坏公共 API**：`SmartDecodable`、`SmartEncodable`、属性包装器的公开接口不能改签名
-- **向后兼容**：保持 Swift 5.0+ / iOS 13+ 的最低版本要求
+- **向后兼容**：保持 Swift 5.9+ / iOS 13+ 的最低版本要求（以 `Package.swift` 的 `swift-tools-version` 为准）
 - **不新增 SwiftSyntax 依赖**：核心模块（`SmartCodable` target）不能依赖 SwiftSyntax
-- **DecodingCache 快照必须成对调用**：`cacheSnapshot()` 和 `removeSnapshot()` 必须配对，注意异常路径
+- **解码上下文通过类型入口统一建立**：`unwrap(as:)` / `decodeInPlace(_:)` 内部经 `decoderForEntry` 为每次可观察的模型初始化准备局部 `DecodingSnapshot`；容器在创建时固定绑定所属模型，不要在调用方手工构造、缓存或跨调用复用上下文
 - 修改核心解码逻辑后，至少手动验证：简单模型、嵌套模型、数组模型、类型不匹配、缺失字段
 
 ### Commit 规范

Document/QA/QA3.md

@@ -118,30 +118,36 @@ struct NameModel: SmartCodable {
 }
 
 let dict: [String: String] = [ : ]
-if let model = NameModel.deserialize(dict: dict) {
+if let model = NameModel.deserialize(from: dict) {
     print(model.name)
     // 我是初始值
 }
 ```
 
 为了实现该功能，SmartCodable 重新实现了完整的 JSON 解码器（`SmartJSONDecoder`），而非仅重写 `JSONKeyedDecodingContainer` 的协议方法。
 
-核心实现在 `DecodingCache` 中，通过快照机制记录当前正在解析的 Model 的初始值：
+核心实现在 `DecodingSnapshot`（解码上下文显式绑定）中，为每一次模型解码记录初始值与映射元数据：
 
 ```swift
-// DecodingCache.swift 简化示意
-func cacheSnapshot<T>(for type: T.Type, codingPath: [CodingKey]) {
-    guard let smartType = type as? SmartDecodable.Type else { return }
-    let snapshot = DecodingSnapshot(objectType: smartType, codingPath: codingPath)
-    snapshots.append(snapshot)
+// DecodingSnapshot.swift 简化示意
+final class DecodingSnapshot {
+    let objectType: any SmartDecodable.Type   // 构造后不可变
+
+    private var cachedInitialValues: [String: Any]?  // nil=未反射；[:]=已反射无字段
+    private lazy var cachedTransformers: [SmartValueTransformer]? = {
+        objectType.mappingForValue()
+    }()
+
+    private func initialValues() -> [String: Any] {
+        // 懒加载：首次需要默认值时才通过 Mirror 反射获取（含父类递归）
+        // 提取所有属性的初始值后缓存，同一上下文内复用同一份引用
+    }
 }
 
-// 懒加载：首次需要默认值时才通过 Mirror 反射获取
-private func populateInitialValues(snapshot: DecodingSnapshot) {
-    guard let type = snapshot.objectType else { return }
-    let mirror = Mirror(reflecting: type.init())
-    // 提取所有属性的初始值存入 snapshot.initialValues
+// 每个新的、可观察的模型初始化入口都创建自己的上下文（JSONDecoderImpl+Unwrap.swift）
+func decoderForEntry<T>(_ type: T.Type) -> JSONDecoderImpl {
+    replacingContexts(model: makeSnapshotForEntry(type), property: propertyContext)
 }
 ```
 
-当某个属性解码失败时，从快照中找到该属性的初始值进行填充。这种懒加载设计避免了每次解码都进行反射，只有在真正需要回退默认值时才会触发。
+当某个属性解码失败时，从当前容器固定绑定的模型上下文中取回该属性的初始值进行填充。容器在创建时绑定所属模型，子模型解码期间父容器的归属不变；这种懒加载设计也避免了每次解码都进行反射，只有在真正需要回退默认值时才会触发。

Document/TechnicalGuide.md

@@ -19,10 +19,10 @@ SmartCodable (主模块)
 ├── Core/
 │   ├── SmartCodable/           # 核心协议：SmartDecodable, SmartEncodable
 │   ├── JSONDecoder/            # 自定义解码器（完整实现，非包装系统 JSONDecoder）
-│   │   ├── Decoder/            # SmartJSONDecoder 入口 + JSONDecoderImpl 核心
+│   │   ├── Decoder/            # SmartJSONDecoder 入口 + JSONDecoderImpl 核心 + DecodingSnapshot（模型上下文）
 │   │   ├── Impl/               # KeyedContainer / UnkeyedContainer / SingleValueContainer
 │   │   ├── Patcher/            # 类型转换 + 默认值提供
-│   │   └── Cache/              # 解码缓存（快照机制）
+│   │   └── Cache/              # 编码缓存（编码侧快照机制）
 │   ├── JSONEncoder/            # 自定义编码器
 │   ├── PropertyWrapper/        # 属性包装器（SmartAny, SmartIgnored, SmartFlat 等）
 │   ├── Transformer/            # 值转换器（日期、颜色、URL 等）
@@ -51,19 +51,20 @@ SmartJSONDecoder.smartDecode(type, from: data)    // SmartJSONDecoder.swift
 JSONDecoderImpl.unwrap(as: type)                  // JSONDecoderImpl+Unwrap.swift
   ├── 特殊类型直接处理：Date, Data, URL, Decimal, CGFloat, Dictionary
   └── 普通类型：
-      ├── cache.cacheSnapshot()                   // 创建快照，记录类型信息
-      ├── type.init(from: self)                   // 触发 Codable 标准流程
-      │   ↓
-      │   KeyedContainer 初始化                    // JSONDecoderImpl+KeyedContainer.swift
-      │     ├── _convertDictionary()              // 应用 Key Mapping
-      │     │   ├── SmartKeyDecodingStrategy      // snake_case → camelCase 等
-      │     │   └── KeysMapper.convertFrom()      // 自定义 mappingForKey()
-      │     └── 逐属性解码：
-      │         ├── 1. 检查 ValueTransformer      // mappingForValue() 自定义转换
-      │         ├── 2. 尝试标准解码
-      │         ├── 3. 类型转换 Patcher            // Int↔String, Bool↔Int 等
-      │         └── 4. 默认值回退 Cache             // Mirror 反射获取的初始值
-      └── cache.removeSnapshot()                  // 清理快照
+      └── decoderForEntry(type)                   // 为本次类型入口准备局部上下文
+          ├── modelSnapshot = DecodingSnapshot(objectType:)  // Smart 模型每次入口新建
+          └── type.init(from: entry)              // 触发 Codable 标准流程
+              ↓
+              KeyedContainer 初始化               // JSONDecoderImpl+KeyedContainer.swift
+                ├── snapshot = impl.modelSnapshot // 容器创建时固定绑定所属模型
+                ├── _convertDictionary()          // 应用 Key Mapping（owner 来自固定 snapshot）
+                │   ├── SmartKeyDecodingStrategy  // snake_case → camelCase 等
+                │   └── KeysMapper.convertFrom()  // 自定义 mappingForKey()
+                └── 逐属性解码：
+                    ├── 1. 检查 ValueTransformer // mappingForValue() 自定义转换（读自身 snapshot）
+                    ├── 2. 尝试标准解码
+                    ├── 3. 类型转换 Patcher       // Int↔String, Bool↔Int 等
+                    └── 4. 默认值回退 snapshot    // Mirror 反射获取的初始值
   ↓
 didFinishMapping()                                // 用户回调，可做后处理
 ```
@@ -73,53 +74,95 @@ didFinishMapping()                                // 用户回调，可做后处
 与原生 Codable 最大的区别在于错误处理策略。当某个属性解码失败时：
 
 1. **先尝试类型转换**（Patcher）：比如 JSON 传了 `"123"` 但属性类型是 `Int`，自动转换
-2. **再回退到默认值**（DecodingCache）：使用属性声明时的初始值
+2. **再回退到默认值**（DecodingSnapshot）：使用属性声明时的初始值
 3. **最后记录日志**（SmartSentinel）：不抛异常，不中断解析，但记录问题
 
 这个策略是整个项目的核心设计意图。
 
 ---
 
-## 四、默认值机制（DecodingCache）
+## 四、默认值机制（解码上下文显式绑定）
 
 这是 SmartCodable 最核心的机制，也是最需要理解的部分。
 
 ### 工作原理
 
+默认值与映射元数据由 `DecodingSnapshot` 承载：**某一次模型解码的上下文**。
+每个新的、框架可观察的 Smart 模型初始化入口都会创建自己的实例，不按类型、
+路径或作用域去重；`objectType` 构造后不可变。
+
 ```
-解码开始
-  ↓
-cacheSnapshot(for: Model.self)          // 记录类型，但不立即反射
+unwrap(as: Model.self) / decodeInPlace / singleValue decode
   ↓
-某属性解码失败
+decoderForEntry(type)                    // 为本次入口准备局部 decoder 视图
   ↓
-initialValueIfPresent(forKey: "name")   // 首次访问时触发 Mirror 反射
+modelSnapshot = DecodingSnapshot(objectType: Model.self)   // 记录类型，但不立即反射
   ↓
-populateInitialValues()                  // 创建 Model.init()，用 Mirror 提取所有属性初始值
+执行 Model.init(from: entry)
   ↓
-返回 snapshot.initialValues["name"]     // 即用户声明的 var name: String = "默认值" 中的 "默认值"
+某属性解码失败
   ↓
-解码结束
+snapshot.initialValueIfPresent(forKey:)  // 首次访问时触发 Mirror 反射（含父类递归）
   ↓
-removeSnapshot(for: Model.self)          // 清理
+返回声明初始值                           // 即 var name: String = "默认值" 中的值
 ```
 
-### 快照栈机制
+解码完成后该上下文随 decoder 视图一起释放，框架不持有全局注册表。
+
+### 容器固定绑定
+
+KeyedContainer 在创建时绑定 `impl.modelSnapshot`，此后不再变化：子模型正在
+解码、抛错、或宿主在回调中同步回读已持有的容器，父容器的归属都不变。
+因此异常路径无需任何“恢复 owner”的动作，也不会出现 SmartFlat 平铺期间
+子模型默认值污染父容器的问题。
+
+`codingPath` 仍只表示 JSON 解码位置（用于错误路径与既有结构分支），不参与
+模型归属判断。
+
+### 属性边（PropertyDecodingContext）
 
-嵌套模型解码时，快照按栈（数组）管理。查找时通过 `codingPath` 匹配：
+模型容器的每个属性值视图携带一条明确的属性边：`(宿主模型上下文, 规范属性 key)`。
+它只服务“当前整属性”的合法消费者（恢复完整包装器声明、当前属性的整体
+Value Transformer），不提供向父级链式搜索的能力，也不能当作子对象的字段表：
+
+- 数组元素、字典数据键、手写 `nestedContainer` / `superDecoder` 进入的原始
+  子结构，属性边被清空，不得借用宿主字段表。
+- 未知的普通 `Codable` 子对象不继承上层模型上下文（否则同名字段会串值）；
+  其缺失字段按 Patcher 类型兜值处理。
+
+### 属性包装器的特殊处理
+
+属性包装器在 Swift 中存储为 `_propertyName`（下划线前缀）。snapshot 会同时
+检查 `key` 和 `_key`，并通过 `extractWrappedValue()` 提取包装器内的实际值；
+`declaredWrapper(forKey:as:)` 则返回完整的包装器声明，保留 `SmartIgnored.isEncodable`
+等自身配置。
+
+双协议包装器（同时遵循 `PropertyWrapperable` 与 `SmartDecodable`）经
+`unwrap` 入口先绑定包装器自身的上下文；内层模型必须通过协作接口获得自己的
+新上下文：
 
 ```swift
-struct A: SmartCodable {       // snapshot[0]: codingPath = []
-    var b: B = B()             // snapshot[1]: codingPath = ["b"]
-}
-struct B: SmartCodable {
-    var name: String = "hello" // 查找 snapshot where codingPath == ["b"]
+init(from decoder: Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    marker = try container.decode(Int.self, forKey: .marker)
+    wrappedValue = try Self.decodeWrappedValue(from: decoder)
 }
 ```
 
-### 属性包装器的特殊处理
+该接口对普通 Decoder 仍等价于 `Value(from: decoder)`；对 SmartCodable 则派生
+一个绑定到内层模型的新解码视图。旧包装器继续兼容；但若仍直接调用
+`Value(from:)`，wrapper 与 inner 共享同一个解码视图，框架没有可观察信息区分
+这次调用，表现为确定性的 wrapper-first 语义。需要严格内外隔离的自定义包装器
+必须使用 `decodeWrappedValue(from:)` 或容器 decode 入口。
+
+普通第三方包装器（仅 `PropertyWrapperable`）直接执行 `Value(from: decoder)`
+时，入口会为内层模型建立局部兼容上下文，保证内层声明默认值可用；该绑定只
+服务这一次直接初始化，下一次显式 `decode(Value.self)` 仍会新建上下文，
+两次独立初始化不会共享可变默认对象。
 
-属性包装器在 Swift 中存储为 `_propertyName`（下划线前缀）。DecodingCache 会同时检查 `key` 和 `_key`，并通过 `extractWrappedValue()` 提取包装器内的实际值。
+需要恢复包装器自身配置（例如 `SmartIgnored.isEncodable`）时，必须从属性边
+指向的宿主声明恢复完整包装器，不能只提取 `wrappedValue`，也不能从其他
+嵌套模型的同名属性推断状态。
 
 ---
 
@@ -177,7 +220,7 @@ struct Model: SmartCodable {
 1. ValueTransformer（mappingForValue）    ← 最高优先级
 2. 标准 Codable 解码
 3. Patcher 类型转换（Int↔String 等）
-4. DecodingCache 默认值回退              ← 最低优先级
+4. DecodingSnapshot 默认值回退            ← 最低优先级
 ```
 
 ### 内置 Transformer
@@ -284,14 +327,14 @@ SmartCodableOptions.ignoreNull = false          // 将 null 作为值传递给 A
 ### 必须遵守
 
 1. **不破坏公共 API**：`SmartDecodable`、`SmartEncodable`、所有属性包装器的公开接口不能改签名
-2. **向后兼容**：最低支持 Swift 5.0 / iOS 13+，不能使用高版本独占的 API
+2. **向后兼容**：包声明为 Swift tools 5.9，最低部署目标 iOS 13+ / macOS 10.15+，不能使用更高版本独占的 API
 3. **不新增 SwiftSyntax 依赖**：宏功能已隔离到独立 target，核心模块不能依赖 SwiftSyntax
 
 ### 代码约定
 
-4. **DecodingCache 的快照必须成对调用**：`cacheSnapshot()` 和 `removeSnapshot()` 必须配对，否则快照栈会泄漏。当前在 `unwrap()` 方法中管理，修改时注意异常路径
+4. **解码上下文通过类型入口统一建立**：`unwrap(as:)` / `decodeInPlace(_:)` 内部经 `decoderForEntry` 为每次可观察初始化准备局部上下文；不要在调用方手工构造或复用 `DecodingSnapshot`，也不要按 `(类型, codingPath)` 缓存上下文
 5. **Patcher 中的类型转换要双向安全**：比如 String → Int，必须验证字符串确实是合法数字，不能静默返回 0
-6. **属性包装器的存储名有下划线前缀**：Swift 编译器将 `@SmartAny var name` 存储为 `_name`，DecodingCache 中需要处理这个映射
+6. **属性包装器的存储名有下划线前缀**：Swift 编译器将 `@SmartAny var name` 存储为 `_name`，DecodingSnapshot 中需要处理这个映射
 7. **KeyedContainer 中的 `_convertDictionary()` 只执行一次**：在容器初始化时调用，之后的属性解码都基于转换后的字典
 
 ### 测试相关
@@ -301,6 +344,6 @@ SmartCodableOptions.ignoreNull = false          // 将 null 作为值传递给 A
 
 ### 性能相关
 
-10. **Mirror 反射是懒加载的**：`DecodingCache` 只在首次需要默认值时才反射，不是每次解码都反射
+10. **Mirror 反射是懒加载的**：`DecodingSnapshot` 只在首次需要默认值时才反射，不是每次解码都反射；同一上下文内重复查询复用同一份引用，跨上下文互不共享
 11. **SafeDictionary 使用 NSLock**：Sentinel 的日志字典有锁保护，在 `debugMode == .none` 时不会触碰
 12. **SmartSentinel 的日志守卫**：所有日志方法入口都有 `guard debugMode != .none else { return }`，Release 环境零开销（前提是 debugMode 保持默认的 `.none`）