---
id: document-mappings-valid-shapes
name: Document Valid Column Combinations for Mappings Table
status: completed
depends_on: []
scope: narrow
risk: medium
impact: component
level: implementation
---

## Description

W20: The `mappings` table stores three conceptually different relationships in one table: session→spoke, session→parent session, session→task. All nullable FKs allow any combination, including invalid ones. The table name `mappings` doesn't convey what's mapped.

Document the valid column combinations (polymorphic association shapes): `sessionId` always NOT NULL; `taskId` only for task-scoped mappings; `parentSessionId` only for coordinator children. This makes it a polymorphic association table with documented shapes.

## Acceptance Criteria

- [ ] `coordination.md` documents valid column combinations (mapping shapes)
- [ ] Shape 1: Session→Spoke (`sessionId` + `spokeId`, no `taskId`/`parentSessionId`)
- [ ] Shape 2: Session→Parent (`sessionId` + `parentSessionId`, no `taskId`)
- [ ] Shape 3: Session→Task (`sessionId` + `taskId`, no `parentSessionId`)
- [ ] Invalid combinations documented (e.g., `taskId` + `parentSessionId` on same row)
- [ ] `sessionId` noted as always NOT NULL for any mapping

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#W20
- docs/architecture/storage/coordination.md:10-27

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion