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:
@@ -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/`
|
||||
|
||||
Reference in New Issue
Block a user