---
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
state_hub_workstream_id: "bc35882d-5caa-4c2a-9b63-31b0b1c81486"
---

# 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
state_hub_task_id: "198b3e06-7093-410a-8538-54628e70dfa5"
```

Add a store-record envelope matching the generic Postgres bootstrap table
columns.

```task
id: USER-WP-0017-T2
status: done
priority: high
state_hub_task_id: "d18b5db1-b4c5-4e23-aa12-335cacfa5eb2"
```

Add deterministic record-key and metadata extraction rules for all manifest
record types.

```task
id: USER-WP-0017-T3
status: done
priority: high
state_hub_task_id: "ca1757e6-52c3-44e4-9523-d01c8f1dcc6b"
```

Add JSON-safe payload encoding for dataclasses, enums, datetimes, tuples, and
mapping fields.

```task
id: USER-WP-0017-T4
status: done
priority: high
state_hub_task_id: "33f555f0-2ab3-4f93-ae5a-28b70814bb57"
```

Add payload decoding back into the original domain dataclasses.

```task
id: USER-WP-0017-T5
status: done
priority: medium
state_hub_task_id: "93c5bd34-f935-4cc9-ab6c-a0a37865592f"
```

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.