Phase 3: First-Class Twin API

[nilsonfh]

Phase 3: First-Class Twin API

Milestone 3 — Ditto-Style Twin Layer. Roadmap phase 3 of 6.

Goal

Twins become first-class resources: search, write, and graph navigation with embedded state.

Requirement

• R3 — Twin API primera clase: GET /api/twins paginated search, attributes/features writes, graph expand with embedded state (tenant-scoped recursive CTEs), relationsQuery in REST, OpenAPI-first.

Plans (3)

• 03-01 (Wave 1) — Topology tenant-scoped traversal foundation + CTE benchmark (NeighborsTenant, dedup UNION, ExpandWithCTE, synthetic depth 5-10 benchmark fixing limits)
• 03-02 (Wave 2) — Twin listing + graph expansion (read plane): GET /api/twins cursor pagination + filters; ?expand=relations(depth) with embedded state
• 03-03 (Wave 3) — Model-validated state writes + REST relationsQuery: PUT/PATCH .../attributes|features reusing the Phase 2 enforcer; relationsQuery in /api/entitiesQuery

Success Criteria

• GET /api/twins: search by tenant/kind/definition/text/relation filters, cursor pagination, OpenAPI-first
• PUT/PATCH /api/twins/{thingId}/attributes|features validated against model + safe TB mirror
• Graph expand ?expand=relations(depth) via tenant-scoped recursive CTEs (add the tenant predicate topology.Neighbors lacks)
• relationsQuery supported in REST /api/entitiesQuery (reuse proven WS BFS)
• Synthetic CTE benchmark (depth 5-10, tens of thousands of edges) fixes API limits

Next Action

Run /legion:build to execute Phase 3.