docs: document entity_id/userId tangle in connected_accounts + Liquibase camelCase rule

@zen-agentchecks n/achecks…zen/retro-connected-accounts-entity-id-docs-vvsmyo → master2 files · +72 −0review: @lingalarahul7review: @anshugarg15review: @rohanprabhureview: @acsrujanreview: @sarthakupdated 1mo ago

GitHub

▸Description· 1 comment · 6 noise

Description

Closes two recurring documentation gaps surfaced in #zen-retros that each burned multiple turns to re-derive from code in recent sessions:

apps/apollo/src/lib/connected_accounts/CONNECTED_ACCOUNTS.md — new "Identity & Lookup" section before "Account Type":

Table mapping the four identity fields (id UUID vs nanoId ca_* vs userId owner vs clientUniqueUserId correlation), with the entity_id / user_id API parameter aliases.
shouldUseEntityId = !connectedAccountId branching at findConnectedAccounts.ts:203 — when connected_account_id is provided the SQL filters on nanoId + projectId only; userId is NOT in the WHERE.
Post-fetch ownership check at getOrFindConnectedAccount.ts:120-180 is gated on handleEntityIdMismatch (bound to projectConfig.is2FAEnabled in tool_auth_builder.ts:99 and recipe_auth_builder.ts:97). 2FA-off projects skip BOTH the ownership check AND the SHARED ACL gate at lines 153-180.

packages/db/docs/DB_MIGRATIONS_GUIDE.md — new "Best Practices → Schema Changes" bullet:

Liquibase migrations MUST double-quote camelCase column names in every SQL identifier reference (ADD/DROP/RENAME COLUMN, index column lists, WHERE clauses, functional indexes).
Cites v9_add_manually_manage_connections_chat_sessions ("manuallyManageConnections") and v21_add_tool_router_session_schema ("isToolRouterConfig") as canonical examples.

How did I test this PR

Verified shouldUseEntityId = !connectedAccountId is at findConnectedAccounts.ts:203 and the post-fetch check at getOrFindConnectedAccount.ts:120-140.
Verified handleEntityIdMismatch: projectConfig.is2FAEnabled at tool_auth_builder.ts:99 and recipe_auth_builder.ts:97.
Verified the cited canonical Liquibase migrations contain the exact quoted-camelCase column strings.
Docs-only change — no code paths modified, no tests affected.

Origin: cron-weekly-retro-ai-improvements / zen-cron-f7c9b8477802 Triggered by: karan@composio.dev | Source: cron-weekly-retro-ai-improvements Session: https://zen-api-production-4c98.up.railway.app/dashboard/#/chat/zen-cron-f7c9b8477802

@zen-agent1mo ago

✅ Post-PR lifecycle complete

build-checks (apollo profile): pnpm lint + pnpm format:check + pnpm check-types → 3/3 PASS (lint: 1 pre-existing warning, 0 errors)
CI: 27/27 green (all required checks including lint-apollo, env-var-check, Vitest E2E, Apollo Core Platform reusable workflows, Analyze)
Codex review (codex exec review --base origin/master): LGTM — "The changes are documentation-only and I did not identify any introduced inaccuracies or issues that would break existing behavior." (Codex verified handleEntityIdMismatch: projectConfig.is2FAEnabled claim at tool_auth_builder.ts:99 + recipe_auth_builder.ts:97 via ripgrep before approving.)
PR comments: 0 human review comments to address
mergeStateStatus: BLOCKED — review required from CODEOWNERS

Docs-only PR; no runtime/E2E paths to exercise.

▸ 6 bot/status comments hidden

@vercel[bot]1mo ago

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
apollo	Ready	Preview, Comment	May 13, 2026 0:15am

Project	Deployment	Actions	Updated (UTC)
debby	Skipped		May 13, 2026 0:15am

@github-actions[bot]1mo ago

🔍 Suggested Reviewers

Based on git blame analysis of 2 file(s):

Contributor	Contribution	Files
lingalarahul7	60%	2

loading diff…

@zen-agent1mo ago

✅ Post-PR lifecycle complete

build-checks (apollo profile): pnpm lint + pnpm format:check + pnpm check-types → 3/3 PASS (lint: 1 pre-existing warning, 0 errors)
CI: 27/27 green (all required checks including lint-apollo, env-var-check, Vitest E2E, Apollo Core Platform reusable workflows, Analyze)
Codex review (codex exec review --base origin/master): LGTM — "The changes are documentation-only and I did not identify any introduced inaccuracies or issues that would break existing behavior." (Codex verified handleEntityIdMismatch: projectConfig.is2FAEnabled claim at tool_auth_builder.ts:99 + recipe_auth_builder.ts:97 via ripgrep before approving.)
PR comments: 0 human review comments to address
mergeStateStatus: BLOCKED — review required from CODEOWNERS

Docs-only PR; no runtime/E2E paths to exercise.

Flag	Coverage Δ
e2e-tests	`5.82% <ø> (ø)`
self-hosted-tests	`5.64% <ø> (ø)`
thermos-unit-tests	`?`
unit-tests	`58.75% <ø> (ø)`

docs: document entity_id/userId tangle in connected_accounts + Liquibase camelCase rule

Description

How did I test this PR

✅ Post-PR lifecycle complete

🔍 Suggested Reviewers

Description

How did I test this PR

✅ Post-PR lifecycle complete

🔍 Suggested Reviewers

💡 Recommendation

🧪 Test Results Summary (Self-Hosted Tests)

🧪 Test Results Summary (E2E Tests)

🧪 Test Results Summary (Unit Tests)

Codecov Report