docs: correct ecosystem dependency direction and add integration context

Architecture docs previously referenced the hub as the authoritative source
for call/identity specs. In reality, call protocol, identity, and access control
come from @alkdev/operations; call graph schemas from @alkdev/flowgraph; task
graph schemas from @alkdev/taskgraph; event transport from @alkdev/pubsub. The
hub is a consumer of @alkdev/storage, not the other way around.

Key changes:
- overview.md: add Ecosystem Integration section with dependency direction
  diagram, What Comes From Where table, repo layer bridging pattern, and
  circular dependency avoidance guidance
- overview.md: promote repo-layer vs operations-bridging from open question
  to explicit decision (CRUD in storage, bridging in consumer)
- overview.md: add zero-ecosystem-dependency statement; fix taskgraph type
  names (TaskGraphNodeAttributes, DependencyEdge)
- overview.md: fix terminology (hub is consumer, not authority)
- metagraph.md: add Ecosystem Context section; replace hub references with
  correct ecosystem sources; fix GraphStatus/GraphBaseType enum
  mischaracterization (C1); unify empty-array semantics with sqlite-host (C2);
  clarify repo layer does NOT import operations (C3); add flowgraph canonical
  schema note; add versioning cross-reference to graph_types table
- encrypted-data.md: reframe hub as provenance not authority; update What
  Lives Where table; fix standalone table advice; update references
- sqlite-host.md: fix actors table description; unify empty-array semantics;
  contextualize hub as reference consumer; add operations identity reference
This commit is contained in:
2026-05-28 14:25:16 +00:00
parent bb544469fd
commit 33a5b0816d
4 changed files with 229 additions and 58 deletions

View File

@@ -62,9 +62,9 @@ All tables share these columns:
}
```
**Notable differences from hub's PostgreSQL common columns**:
**Notable differences from a typical PostgreSQL common columns pattern**:
| Column | SQLite | PostgreSQL (hub) |
| Column | SQLite | PostgreSQL (typical) |
| ----------- | ------------------------------------- | ------------------------------------------------------------- |
| `id` | text PK (consumer-generated) | text PK with `$defaultFn(() => crypto.randomUUID())` |
| `metadata` | `text` with JSON mode | `jsonb` with `$type<Record<string, unknown>>()` |
@@ -130,12 +130,13 @@ Stores edge type definitions within a graph type.
a graph type.
**Empty array semantics**: `allowedSourceTypes` and `allowedTargetTypes` default
to `[]` (empty JSON array) in the database. The repository layer must treat `[]`
(empty array) as "no restriction" — any node type is a valid endpoint — matching
the behavior of `undefined` in the `EdgeType` schema. A non-empty array
restricts endpoints to only the listed node types. There is no "no types
allowed" state; if edge types need to be disabled, use a status or soft-delete
pattern on the edge type definition.
to `[]` (empty JSON array) in the database. `[]` means "no restriction" — any
node type is a valid endpoint — matching the behavior of `undefined` in the
`EdgeType` schema layer. A non-empty array restricts endpoints to only the
listed node types. There is no "no types allowed" state; if edge types need to
be disabled, use a status or soft-delete pattern on the edge type definition.
The repository layer must enforce this convention consistently. See
[metagraph.md](./metagraph.md) for the schema-layer definition.
### `graphs`
@@ -209,9 +210,11 @@ its edges.
### `actors`
Standalone identity table. Currently not referenced by any relation. This is a
placeholder for the hub's account/identity model and may become a node type in
an ACL graph or remain a standalone table. See [overview.md](./overview.md) Open
Standalone identity table. Currently not referenced by any relation — the
`actors` table has no FK references to or from any metagraph table and is not
included in `relations.ts`. This is a placeholder for identity data and may
become a node type in an ACL graph (based on `@alkdev/operations`'s `Identity`
interface) or remain a standalone table. See [overview.md](./overview.md) Open
Question 1.
| Column | Type | Constraints | Notes |
@@ -355,14 +358,15 @@ changes:
| `integer` (boolean mode) | `boolean` |
| `text` (enum) | `pgEnum` or `text` with check constraint |
See hub's `commonCols` reference in
[../../hub/docs/architecture/storage/table-reference.md] for the PostgreSQL
patterns.
See a consumer's `commonCols` pattern (e.g., the hub's
`/workspace/@alkdev/hub/docs/architecture/storage/table-reference.md`) for
PostgreSQL reference patterns.
## References
- Drizzle ORM SQLite core: https://orm.drizzle.team/docs/sqlite-core
- libsql client: https://github.com/tursodatabase/libsql
- Hub common columns pattern:
- Hub common columns (reference consumer):
`/workspace/@alkdev/hub/docs/architecture/storage/table-reference.md`
- Operations AccessControl and Identity: `/workspace/@alkdev/operations/docs/architecture/api-surface.md`
- Source: `src/sqlite/`