Add repository layer strategy: JSON path queries, CRUD decisions, ecosystem integration
Add three open questions (OQ-17, OQ-18, OQ-19) covering attribute query strategy, CRUD generation approach, and storage-operations bridge placement. Create ADR-033 recording the v1 decision: JSON path queries for attributes with hand-written CRUD for static tables. Expand forward-look.md with Repository Layer Strategy section analyzing three approaches (JSON path, native columns via dbtype, hybrid) and their implications for the metagraph pattern. Add drizzle-graphql and dbtype from-dbtype comparison showing neither handles dynamic schema-as-data. Update overview.md with dbtype/ujsx in the dependency diagram, expanded ecosystem context in the bridging pattern section, and new open questions. Align open-questions.md: resolve OQ-17 and OQ-18 for v1 (ADR-033), add OQ-19 as open, update summary counts and ADR impact table.
This commit is contained in:
@@ -13,9 +13,9 @@ When a question is resolved, update its status to `resolved` and add a resolutio
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| Open | 7 |
|
||||
| Open | 8 |
|
||||
| Partially resolved | 1 |
|
||||
| Resolved | 8 |
|
||||
| Resolved | 10 |
|
||||
|
||||
**Open questions requiring decisions:**
|
||||
- **OQ-03** (actors table design) — deferred to ACL design
|
||||
@@ -25,10 +25,15 @@ When a question is resolved, update its status to `resolved` and add a resolutio
|
||||
- **OQ-11** (auto-migrate vs explicit consumer action) — conditional on OQ-10
|
||||
- **OQ-12** (schema evolution vs event-sourced replay) — post-v1 concern
|
||||
- **OQ-13** (schema evolution events in event stream) — post-v1
|
||||
- **OQ-19** (storage-operations bridge package location) — depends on long-term CRUD strategy
|
||||
|
||||
**Partially resolved:**
|
||||
- **OQ-01** (flowgraph Module export) — storage can start without it
|
||||
|
||||
**Resolved (v1 direction decided, long-term question remains open):**
|
||||
- **OQ-17** (attribute query strategy) — JSON path for v1 (ADR-033), hybrid viable with dbtype later
|
||||
- **OQ-18** (auto-generated vs hand-written CRUD) — hand-write for v1 (ADR-033), auto-gen remains an option
|
||||
|
||||
## How to Use This Document
|
||||
|
||||
- Each question has an **ID** (e.g., OQ-01), **status**, **origin** (which doc(s)), and **priority**
|
||||
@@ -41,7 +46,9 @@ When a question is resolved, update its status to `resolved` and add a resolutio
|
||||
|-----|----------|
|
||||
| ADR-003 | OQ-01 (partial — storage can start without flowgraph Module) |
|
||||
| ADR-015 | OQ-05 (constraint semantics) |
|
||||
| ADR-018 | OQ-17 (v1 decision: dbtype integration deferred, JSON path for v1) |
|
||||
| ADR-020 | OQ-02 (no nodeTypeId for now, can add later) |
|
||||
| ADR-033 | OQ-17 (JSON path queries for v1), OQ-18 (hand-written CRUD for v1) |
|
||||
|
||||
## Theme 1: Package Boundaries and Dependencies
|
||||
|
||||
@@ -171,4 +178,30 @@ When a question is resolved, update its status to `resolved` and add a resolutio
|
||||
- **Origin**: [overview.md](overview.md)
|
||||
- **Status**: resolved
|
||||
- **Priority**: high
|
||||
- **Resolution**: The repository CRUD layer (host-specific typed queries, schema validation before writes) belongs in `@alkdev/storage`. The operations bridging layer (generating `OperationSpec`s from metagraph schemas) belongs in a consumer or adapter package. These are separate concerns — CRUD is a storage concern; call protocol integration is an application concern.
|
||||
- **Resolution**: The repository CRUD layer (host-specific typed queries, schema validation before writes) belongs in `@alkdev/storage`. The operations bridging layer (generating `OperationSpec`s from metagraph schemas) belongs in a consumer or adapter package. These are separate concerns — CRUD is a storage concern; call protocol integration is an application concern.
|
||||
|
||||
## Theme 7: Repository Layer Strategy
|
||||
|
||||
### OQ-17: How should the repository layer handle attribute queries — JSON path, native columns, or dbtype-generated?
|
||||
|
||||
- **Origin**: [forward-look.md](forward-look.md)
|
||||
- **Status**: resolved (v1)
|
||||
- **Priority**: high
|
||||
- **Resolution**: For v1, attribute queries use JSON path extraction (`json_extract` on SQLite, `->>`/`#>>` on PG). Hand-written CRUD for static tables. dbtype integration and hybrid approach are post-v1. See ADR-033. The long-term question of whether to adopt the hybrid approach (static tables via dbtype, dynamic attributes remain JSON) remains open for future iterations.
|
||||
- **Cross-references**: ADR-033, ADR-018, [forward-look.md](forward-look.md)
|
||||
|
||||
### OQ-18: Should the repository layer's CRUD operations be auto-generated (drizzle-graphql pattern) or hand-written?
|
||||
|
||||
- **Origin**: [forward-look.md](forward-look.md)
|
||||
- **Status**: resolved (v1)
|
||||
- **Priority**: medium
|
||||
- **Resolution**: For v1, hand-write CRUD functions with explicit signatures. The three long-term options (hand-written, auto-generated from Drizzle, auto-generated from dbtype) remain open for future iterations. See ADR-033.
|
||||
- **Cross-references**: ADR-033, OQ-17
|
||||
|
||||
### OQ-19: Where does the storage-operations bridge package live in the @alkdev workspace?
|
||||
|
||||
- **Origin**: [forward-look.md](forward-look.md)
|
||||
- **Status**: open
|
||||
- **Priority**: medium
|
||||
- **Notes**: Four options: (1) hub-internal code, (2) dedicated `@alkdev/storage-operations` adapter, (3) `from-storage` adapter inside `@alkdev/operations`, (4) part of `@alkdev/dbtype`'s `from-dbtype` adapter. Option 1 is the most immediate (no new package). Option 2 is the cleanest separation. Option 3 creates an undesirable dependency direction (operations → storage). Option 4 is the long-term goal if dbtype is adopted. The choice depends on OQ-17/OQ-18 resolution: if hand-written CRUD, the bridge is trivial and can live in the hub; if auto-generated from dbtype, the bridge naturally lives with dbtype.
|
||||
- **Cross-references**: OQ-16, OQ-17, ADR-033
|
||||
Reference in New Issue
Block a user