docs(agents): design doc for agent-store ↔ entity bridge [#2847]

[viniciusdacal]

Summary

Design doc for bridging AgentStore with Vertz entities so agent sessions and messages become queryable from app code with rules.* RLS applied — without changing the agent loop's atomic write path. Resolves Gap #4 of plans/open-agents-clone.md.

This PR is design-only. No implementation. Awaits human sign-off on the settled design at plans/agent-store-entity-bridge.md (Rev 6) before Task A/B/C implementation begins in a follow-up PR.

The design, in three sentences

1. Developers spread agentSessionColumns / agentMessageColumns into their own d.table() calls, register via createDb({ models }), then call defineAgentEntities(db) to get { session, message } entities wired into createServer({ entities }). Tenant scoping auto-detected; access defaults are rules.where({ userId: rules.user.id }) + a before.create hook that injects userId/tenantId from the request context (ctx wins over input).
2. Writes stay on the existing memoryStore / sqliteStore / d1Store implementations — atomic transaction() / batch() semantics preserved, D1 semantics unchanged, durable resume unaffected. AgentStore.appendMessages gains a session parameter (matches the existing appendMessagesAtomic shape) so stores can denormalize userId/tenantId onto agent_messages rows — enabling flat rules.where({ userId }) on Message without framework changes.
3. Reads through the entity API (/api/agent-session auto-routes, ctx.entities.agentSession.list()) get full RLS. Reads inside the agent loop (store.loadSession) stay on the existing run.ts:222-252 ownership check. Honest scoping.

Public API changes

Additions (@vertz/agents/entities subpath):

• agentSessionColumns, agentMessageColumns — plain ColumnRecord constants
• agentSessionIndexes, agentMessageIndexes — index arrays
• defineAgentEntities(db, opts?) — factory returning { session, message }

Breaking change (pre-v1, .claude/rules/policies.md permits):

• AgentStore.appendMessages(sessionId, messages) → appendMessages(sessionId, messages, session). All three in-repo store impls update. One call site in run.ts (~1 line). No known external consumers.
• agent_messages table gains user_id / tenant_id columns. Every @vertz/agents user runs an additive ALTER TABLE agent_messages ADD COLUMN … migration on upgrade. Migration SQL provided.

Review process

Three full rounds of adversarial review (DX, Product, Technical) per .claude/rules/design-and-planning.md:

Rev	DX	Product	Technical
1	Changes (6 blockers)	Changes (5 blockers)	Changes (4 blockers)
2	Changes (4 blockers)	Changes (2 blockers)	Changes (6 hallucinations + 3 design)
3	Approved (E2E fixes needed)	Approved (polish only)	Approved (E2E fixes needed)
5	Approved	Approved	Changes (3 E2E issues)
6	—	—	Clean (final targeted verify)

Architecture settled at Rev 3; Rev 4–6 were editorial passes fixing API-shape drift in the E2E acceptance test (verified against real file:line evidence).

Follow-up issues filed

• chore(agents): reject entity hook registration on factory-produced Session/Message entities #2957 — Reject entity hook registration on factory-produced Session/Message entities (enforces the hook-bypass contract at boot)
• chore(agents): migrate agent_sessions.state and agent_messages.toolCalls to d.jsonb<T>() #2958 — Migrate state / toolCalls columns to d.jsonb<T>() with opt-in flag

Decision requested

One scope call flagged for explicit sign-off:

• Non-adopter breaking change. Every @vertz/agents user must run a two-statement ALTER TABLE migration on upgrade, even if they never adopt entities. Rationale + alternative rejected in the design. If this scope is unacceptable, say so and I'll re-work the denormalization into an opt-in flag.

Test plan

• Human reads plans/agent-store-entity-bridge.md end-to-end
• Human signs off on the single scope decision (non-adopter breaking change)
• Follow-up implementation PR tracks E2E test in apps/demo/e2e/agent-store-entity-bridge.test.ts passing against real createDb + sqliteStore + createCrudHandlers (not the stubbed snippet in the doc)

🤖 Generated with Claude Code