Settle v3 vocabulary on `database`/`collection` (`table` reserved for HBase)

[em3s]

Context

Container terms piled up across generations: v2 service/label, v3 database/table, queue namespace/queue, datastore datastore/namespace.

table is the pain: the logical table and the physical HBase table both appear in the API (/databases/{db}/tables/{t} vs /datastore/hbase/tables/{name}), with no way to tell them apart.

Decision

v3 logical hierarchy is database > collection > edge/vertex/multi-edge. Physical stays datastore > namespace > table (HBase). So table means physical only, collection means logical only.

• collection: what modern DBs converge on (MongoDB, Firestore, vector DBs; ArangoDB uses vertex/edge collections).
• Keep database: Mongo is exactly database > collection, and only table changes so churn stays small. (domain etc. considered, dropped — taste, not correctness.)

Fold queue into /graph/v3:

• /queue/v1/namespaces/{ns}/queues/{q} → /graph/v3/databases/{db}/collections/{c}
• A queue is already an ImmutableEdge table (QueueMetadataService builds it via the v3 table API; QueueService runs enqueue/poll as edge mutate/scan) — a surface move, not a storage migration.
• partitions nests under messages (/messages/partitions/{p}/poll), matching /edges/scan/{index}.
• namespace/queue container words disappear; namespace stays physical-only.

Consequences

• Add /collections/{collection}; keep /tables/{table} as a maintained compat alias (same handler, internal code untouched). v3→v2 mapping unchanged (database→service, collection→label).
• Keep /queue/v1 as a compat alias.
• Docs/CLI/responses lead with collection; table stays supported. Ambiguity closes when tables is retired.
• Follow-ups: body field naming (table/collection), CLI alias, Queue as a first-class model (Promote Queue to a first-class model (backed by ImmutableEdge) #471).