---
id: document-jsonb-column-boundaries
name: Document JSONB Column Boundaries (metadata vs data)
status: completed
depends_on: []
scope: narrow
risk: medium
impact: component
level: implementation
---

## Description

W01: The `commonCols.metadata` and per-table `data` JSONB columns overlap with no documented boundary. `api_keys` stores `scopes`/`resources`/`tags` inside `metadata`; `accounts` has both `data` (preferences, avatar) and `metadata` (arbitrary) with overlapping purposes. An implementer cannot determine which column to use for what.

Define and document the boundary: `data` holds structured domain-specific data with known TypeScript types; `metadata` holds opaque key-value pairs for subsystem use with a namespacing convention (e.g., `_keypal.scopes`).

## Acceptance Criteria

- [ ] `README.md` documents the boundary between `commonCols.metadata` and per-table `data` columns
- [ ] Namespacing convention for `metadata` is specified (e.g., `_subsystem.key`)
- [ ] Each table that has both columns lists what belongs in each (`identity.md` for `accounts`, `api_keys`)
- [ ] Update `keypal` usage note: `api_keys.metadata._keypal.scopes` pattern documented

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#W01
- docs/architecture/storage/README.md:73
- docs/architecture/storage/identity.md:85-88, :23

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion