feat: add durable store record serialization

workplans/USER-WP-0017-durable-store-record-serialization.md

@@ -0,0 +1,110 @@
+---
+id: USER-WP-0017
+type: workplan
+title: "Durable Store Record Serialization"
+domain: netkingdom
+repo: user-engine
+status: finished
+owner: codex
+topic_slug: netkingdom
+planning_priority: medium
+planning_order: 17
+created: "2026-06-16"
+updated: "2026-06-16"
+depends_on:
+  - USER-WP-0016
+---
+
+# USER-WP-0017 - Durable Store Record Serialization
+
+## Goal
+
+Define a dependency-free serialization contract for the generic durable store
+record shape introduced by USER-WP-0016 so a future Postgres adapter can persist
+and restore domain dataclasses through JSONB without embedding ad hoc codecs.
+
+## Scope Direction
+
+This workplan should cover deterministic record keys, adapter metadata columns,
+JSON-safe payload encoding, and round-trip decoding for every logical record
+type in the migration manifest.
+
+## Non-Goals
+
+- Do not add a production Postgres driver.
+- Do not implement connection pooling, migrations, locks, or outbox claiming.
+- Do not redact durable payloads; adapters must avoid logging raw payloads.
+
+## Tasks
+
+```task
+id: USER-WP-0017-T1
+status: done
+priority: high
+```
+
+Add a store-record envelope matching the generic Postgres bootstrap table
+columns.
+
+```task
+id: USER-WP-0017-T2
+status: done
+priority: high
+```
+
+Add deterministic record-key and metadata extraction rules for all manifest
+record types.
+
+```task
+id: USER-WP-0017-T3
+status: done
+priority: high
+```
+
+Add JSON-safe payload encoding for dataclasses, enums, datetimes, tuples, and
+mapping fields.
+
+```task
+id: USER-WP-0017-T4
+status: done
+priority: high
+```
+
+Add payload decoding back into the original domain dataclasses.
+
+```task
+id: USER-WP-0017-T5
+status: done
+priority: medium
+```
+
+Document how future Postgres adapters should use the serialization contract.
+
+## Acceptance Criteria
+
+- Every logical record type in the migration manifest has a codec.
+- Encoded payloads can be passed through `json.dumps`.
+- Domain records round-trip through `StoreRecord` without losing enum,
+  datetime, tuple, or nested dataclass structure.
+- Composite keys are deterministic and collision-resistant for scoped records.
+- Documentation warns that durable payloads may contain sensitive values and
+  must not be used as diagnostics output.
+
+## Expected Outputs
+
+- `user_engine.store_records` module.
+- Store-record serialization tests.
+- Durable-store documentation updates.
+
+## Implementation Notes
+
+Implemented on 2026-06-16:
+
+- Added `StoreRecord`, `store_record_for`, `domain_record_from_store_record`,
+  and manifest validation helpers.
+- Added JSON-safe recursive encode/decode support for all current domain
+  dataclasses used by `UserEngineStore`.
+- Added round-trip tests using the same reference records as the conformance
+  harness.
+- Documented the serialization layer as the provider-neutral prerequisite to a
+  live Postgres adapter.