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:
2026-05-30 11:02:49 +00:00
parent ed8710a7f5
commit a2ee452a63
5 changed files with 258 additions and 6 deletions

View File

@@ -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