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

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
USER-WP-0017	workplan	Durable Store Record Serialization	netkingdom	user-engine	finished	codex	netkingdom	medium	17	2026-06-16	2026-06-16	USER-WP-0016	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

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.

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.

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.

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.

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.