glm-5.1
2b63cda1c7
Copy architecture docs, ADRs, storage domain specs, research, reviews, and 56 storage architecture tasks from the alkhub_ts monorepo. Adapt for standalone @alkdev/hub repo structure (src/ not packages/hub/). Sanitize all sensitive information: - Replace private IPs (10.0.0.1) with localhost defaults - Remove internal server hostnames (dev1, ns528096) - Replace /workspace/ private paths with npm package references - Remove hardcoded credentials from examples - Rewrite infrastructure.md without private network details Add Deno project scaffolding: deno.json (pinned deps), .gitignore, AGENTS.md, entry point. Migrate existing code stubs (crypto, config types, logger) with updated import paths.
80 lines
4.7 KiB
Markdown
80 lines
4.7 KiB
Markdown
---
|
|
id: review-operations-schema-stabilization
|
|
name: Review Operations Schema Split and Storage Spec Stabilization Gate
|
|
status: completed
|
|
depends_on: [split-operations-into-definitions-and-registrations, spec-adr-consistency, security-specs, cascade-decisions, data-integrity-specs]
|
|
scope: broad
|
|
risk: high
|
|
impact: project
|
|
level: review
|
|
---
|
|
|
|
## Description
|
|
|
|
Final review of the storage spec stabilization gate — verifying that the spec is truly implementable and that cross-references are consistent. This covers:
|
|
|
|
### 1. Operations Schema (Definitions + Registrations Split)
|
|
|
|
The D3 decision split `operation_specs` into two tables. This is the only broad-scope, high-risk task in the set. It changes the fundamental data model for how the hub routes calls. The review must verify consistency across ALL docs that reference operations:
|
|
|
|
- `spokes.md` — table schemas for `operations` and `operation_registrations`
|
|
- `call-graph.md` — references to operation routing
|
|
- `coordination.md` — references to spoke operations
|
|
- `table-reference.md` — FK entries, indexes, status enums
|
|
- ADR-006 — must reflect the definitions/registrations split
|
|
|
|
### 2. Storage Spec Stabilization Gate
|
|
|
|
The `storage-spec-stabilization` task is THE gate. Its acceptance criteria are:
|
|
1. All dependent tasks are completed ✓
|
|
2. Cross-references between completed tasks are consistent (needs verification)
|
|
3. No remaining contradictions in the covered domain (needs verification)
|
|
|
|
All 26 dependent tasks are marked completed but none have Summary sections filled. The review must verify that the spec docs are in a state where implementation can begin without ambiguity.
|
|
|
|
### 3. Doc Status
|
|
|
|
All architecture docs still have `status: draft`. If the spec is truly stabilized, these should be promoted. The review should confirm readiness for `status: stable`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `operations` table schema in `spokes.md` is complete and consistent with `table-reference.md`
|
|
- [ ] `operation_registrations` table schema is complete with polymorphic FK documented
|
|
- [ ] ADR-006 reflects the definitions/registrations split (or is superseded)
|
|
- [ ] All `operation_specs` references across docs are updated to `operations`/`operation_registrations`
|
|
- [ ] Call routing flow (definition lookup → active registrations → dispatch) is documented
|
|
- [ ] Spoke disconnect lifecycle is unambiguous in `spokes.md`: deactivate registrations, keep definitions
|
|
- [ ] Cross-references between all per-domain docs and `table-reference.md` are consistent
|
|
- [ ] No remaining contradictions in cascade behavior, status enums, or FK relationships
|
|
- [ ] `spokes.md`, `call-graph.md`, `coordination.md` consistently use the new naming
|
|
- [ ] A recommendation on doc status promotion (`draft` → `stable`) is provided
|
|
|
|
## References
|
|
|
|
- docs/architecture/storage/spokes.md
|
|
- docs/architecture/storage/call-graph.md
|
|
- docs/architecture/storage/coordination.md
|
|
- docs/architecture/storage/table-reference.md
|
|
- docs/decisions/ADR-006-operation-specs-as-capabilities.md
|
|
- docs/decisions/storage-spec-phase1-resolutions.md (D3)
|
|
- All per-domain architecture docs in docs/architecture/storage/
|
|
|
|
## Notes
|
|
|
|
This is the stabilization gate review. If this passes, storage implementation can begin. If it finds issues, they must be resolved before implementation starts — fixing spec contradictions during implementation is orders of magnitude more expensive than fixing them now.
|
|
|
|
## Summary
|
|
|
|
Review completed 2026-04-23. 10 acceptance criteria checked: 7 PASS, 3 FAIL (2 critical, 1 requiring judgment).
|
|
|
|
**Critical issues found and fixed:**
|
|
1. `operations.accessLevel` in D3 vs `operations.accessControl` in spokes.md — inconsistent naming with different semantics → **Fixed**: updated D3 to use `accessControl` (matching spokes.md and operations.md).
|
|
2. ADR-002 still referenced `operation_specs.inputSchema/outputSchema` → **Fixed**: updated to `operations.inputSchema/outputSchema`.
|
|
3. `call_graph_nodes.operationId` had no FK declaration and was ambiguous (FK vs free-text identifier) → **Fixed**: made it a nullable FK to `operations.id` with SET NULL cascade, added to cascade table, clarified in call-graph.md.
|
|
|
|
**Warnings noted (deferred to implementation phase):**
|
|
- `spoke-runner.md` uses `runnerId` instead of `spokeId` (acknowledged in README, terminology cleanup deferred)
|
|
- No end-to-end call routing flow documented (multi-provider dispatch unspecified — design gap for implementation)
|
|
- D3 column list doesn't fully match spokes.md (D3 is the decision, spokes.md is the spec — spokes.md is authoritative)
|
|
|
|
**Gate recommendation**: After fixes, storage spec stabilization should pass. 2 hours of additional doc work on call routing flow is recommended before hub.call implementation. |