generated from coulomb/repo-seed
111 lines
2.8 KiB
Markdown
111 lines
2.8 KiB
Markdown
---
|
|
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.
|