Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
chore(prompts): file order 433, account_link_codes table-name collision breaking every device-link call
nirholas1ecbd3550c91
diff --git a/prompts/finish/433-auto-fix-account-link-codes-schema-collision.md b/prompts/finish/433-auto-fix-account-link-codes-schema-collision.mdnew file mode 100644index 000000000..8a02ed873--- /dev/null+++ b/prompts/finish/433-auto-fix-account-link-codes-schema-collision.md@@ -0,0 +1,188 @@+# 433. Fix the account_link_codes table-name collision breaking every phone/desktop/CLI/Telegram account-link call in production++How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.++## Operating clause (binding)++- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.+- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write, git push or a production deploy, posting to an external channel, committing content that references a crypto project other than $THREE, and destroying unrecoverable data. This order writes a new forward migration and a test; it applies the migration to whatever `DATABASE_URL` resolves to locally/in CI the same way every other migration in this repo is applied (`npm run db:migrate`), which is the existing convention, not a new gate. It does not push or deploy.+- Bug fixes are test-first (owner directive 2026-10-10): write the failing test first, confirm it fails for the reason given below (not a typo or setup error), then fix, then confirm it passes, then commit test and fix together.+- No mocks, no fake data, no unfinished-work markers, no commented-out code.+- The em-dash and en-dash characters are banned in everything you write.+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.+- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.+- Do not touch `prompts/finish/417-auto-thumbnail-error-fallback.md`, `420-auto-hover-state-regression.md`, or any other open order's files. This order's surface is exactly: one new migration file, `api/_lib/schema.sql` (comment only, see Task 4), `tests/account-link.test.js` (or a new `tests/account-link-codes-schema.test.js` if you decide the live-DB check doesn't belong in the mocked-DB suite, see Task 2), and `data/changelog.json`.++## Why this matters (measured 2026-10-24)++Every call into the phone/desktop/CLI/Telegram account-linking feature+(`/dashboard/account`, and the mobile-app pairing flow it backs) is broken in+production right now, and has been since the feature's migration merged on+2026-10-11. This is not a flaky edge case: it is a 100% failure rate on every+action (`mint`, `claim`, `poll`, `pending`, `decide`, `devices`, `revoke`)+dispatched by `api/auth/link-codes/[action].js`, because every one of them+reads or writes a column that does not exist on the live table.++Root cause, confirmed by direct reproduction against the real database+(`node --env-file=.env.local <script>`, using the repo's own `sql` tag from+`api/_lib/db.js`, 2026-10-24):++ test user id fc893ecf-8313-4be1-9fca-e868a4f73cb5+ THREW: NeonDbError: column "status" does not exist+ at ... listPendingLinkCodes (api/_lib/account-link/link-codes.js:155:15)+ code: '42703',+ routine: 'errorMissingColumn',++and confirmed by reading the live table's actual columns directly:++ select column_name from information_schema.columns where table_name = 'account_link_codes';+ -> id, code_hash, user_id, agent_id, label, scopes, created_at, expires_at, redeemed_at, link_id++Two unrelated features share the table name `account_link_codes`:++1. `api/_lib/migrations/20260922130000_agents_v1_api.sql` (merged 2026-09-22)+ created `account_link_codes` for an agent-identity pairing feature:+ columns `agent_id`, `scopes`, `redeemed_at`, `link_id`. This is the schema+ that is actually live in production today.+2. `api/_lib/migrations/20261011003000_account_linking.sql` (merged+ 2026-10-11) created a *different* table, also named `account_link_codes`,+ for the phone/desktop/CLI/Telegram device-linking feature that+ `api/_lib/account-link/link-codes.js` and `api/auth/link-codes/[action].js`+ actually implement: columns `device_kind`, `status`, `claim`,+ `claim_secret_hash`, `result_kind`, `result_id`, `result_secret`,+ `device_id`, `claimed_at`, `decided_at`, `consumed_at`.++Migration 2 used `CREATE TABLE IF NOT EXISTS account_link_codes (...)`. Since+a table of that name already existed from migration 1, this silently no-op'd:+no error, no warning, `npm run db:status` reports "all migrations applied"+(confirmed 2026-10-24: production is current through+`20261024020000_prediction_shadow_ledger.sql` with no drift), and the feature+shipped looking complete while being 100% broken against the real database.++This explains why the bug was never caught by `npm test`:+`tests/account-link.test.js` mocks `api/_lib/db.js` entirely with a scripted+fake (`vi.mock('../api/_lib/db.js', ...)`, see its header comment), so the+unit suite exercises the application logic correctly but never touches the+real schema. `npm run audit:web`'s page audit also cannot see this: the+link-codes dispatcher sits behind session auth+(`getSessionUser`/`sessionOrFail` in every handler) and the unauthenticated+audit never signs in, so it never dispatches a request that would surface the+500.++The old (migration-1) schema is dead code: grepping every `.js`/`.mjs` file+under `api/`, `src/`, `workers/`, `scripts/` for `account_link_codes` finds+exactly one consumer, `api/_lib/account-link/link-codes.js`, and every column+name it references (`status`, `device_kind`, `claim`, `claim_secret_hash`,+`result_kind`, `result_id`, `result_secret`, `device_id`, `claimed_at`,+`decided_at`, `consumed_at`) belongs to the migration-2 (new) schema, never to+migration-1's `agent_id`/`scopes`/`redeemed_at`/`link_id`. Nothing live reads+or writes the old schema's distinguishing columns. The fix is to rename the+old table out of the way (preserving its rows, in case the owner wants to+inspect or port old agent-identity-link data later, satisfying the+"destroying data that cannot be regenerated" gate by not destroying anything)+and let the already-written, already-shipped application code create and use+the correctly-shaped table.++## Step 0: re-derive the current state++ git log --oneline -1+ npm run db:status # confirm "all migrations applied", no drift+ grep -n "account_link_codes" api/_lib/migrations/20260922130000_agents_v1_api.sql+ grep -n "account_link_codes" api/_lib/migrations/20261011003000_account_linking.sql+ grep -rln "account_link_codes" api/ src/ workers/ scripts/ | grep -v node_modules # confirm the only live consumer is api/_lib/account-link/link-codes.js+ node --env-file=.env.local -e "+ import('./api/_lib/db.js').then(async ({ sql }) => {+ const rows = await sql\`select column_name from information_schema.columns where table_name = 'account_link_codes' order by ordinal_position\`;+ console.log(rows.map(r => r.column_name));+ process.exit(0);+ });+ "+ # expect: [ 'id','code_hash','user_id','agent_id','label','scopes','created_at','expires_at','redeemed_at','link_id' ]+ # (the OLD schema; if this instead already shows 'status'/'device_kind', someone has already+ # fixed this live and you should stop and verify whether this order is already resolved before continuing)++## Tasks++1. Create `api/_lib/migrations/20261024120000_fix_account_link_codes_collision.sql` (pick the current UTC+ timestamp per the repo's migration-naming convention, 14 digits `YYYYMMDDHHMMSS`, if 20261024120000+ is already taken by a concurrent agent's migration). Contents:+ - `ALTER TABLE IF EXISTS account_link_codes RENAME TO account_link_codes_agents_v1_legacy;` plus the+ matching index rename (`account_link_codes_user_idx` -> `account_link_codes_agents_v1_legacy_user_idx`),+ each guarded so the migration is safe if ever re-examined (use `IF EXISTS` on the table rename; Postgres+ has no `ALTER INDEX IF EXISTS ... RENAME` guard issue, `ALTER INDEX IF EXISTS` is valid syntax, use it).+ - Followed by the exact `CREATE TABLE IF NOT EXISTS account_link_codes (...)` and+ `CREATE INDEX IF NOT EXISTS account_link_codes_user_idx ...` statements copied verbatim from+ `api/_lib/migrations/20261011003000_account_linking.sql`, so the table that gets created this time is+ the correctly-shaped one (the rename in the prior statement clears the name collision first).+ - A short comment at the top of the file stating the root cause in one or two lines (not a changelog of+ this work order, just the technical fact for the next person reading migration history): the table name+ collided with the 2026-09-22 agents-v1 link-codes feature, which is preserved under the renamed table.+2. Apply it locally against the real database the repo already points at: `npm run db:migrate`. Confirm+ with `npm run db:status` that it is now applied and there is no drift.+3. Add a regression test. The existing `tests/account-link.test.js` mocks the DB entirely (see "Why this+ matters" above), so it cannot catch a real schema mismatch; adding the assertion there would not have+ caught this bug and will not catch its return. Instead add a new, small test file+ `tests/account-link-codes-schema.test.js` that opens a real connection via `node --env-file=.env.local`+ semantics (read `DATABASE_URL` the same way `scripts/apply-migrations.mjs` does: `.env.local` then `.env`+ then `process.env`; skip the test with a clear console message if no `DATABASE_URL` is resolvable, same+ pattern other DB-touching scripts in this repo use) and:+ - First, reproduce the exact failure this order fixes: write the test so that, run against a database+ that still has the pre-fix table shape, `listPendingLinkCodes` (or a direct+ `select status from account_link_codes limit 0`) throws a Postgres error with `code === '42703'`. Run+ it now (before Task 1/2's migration is applied, or against a scratch check) and confirm it fails for+ that reason, per the test-first rule.+ - Then, after the migration is applied, assert the live table has the new-schema columns+ (`status`, `device_kind`, `claim_secret_hash`, `claimed_at`, `decided_at`, `consumed_at`) and that+ `listPendingLinkCodes(userId)` resolves (empty array for a fresh user) rather than throwing.+ - Also assert `account_link_codes_agents_v1_legacy` exists (`select to_regclass('account_link_codes_agents_v1_legacy')`+ is not null) so a future cleanup pass can find the preserved old data.+4. Update the comment immediately above the `account_link_codes` block in `api/_lib/schema.sql` (around+ line 2695) to match the new (migration-2) column list, since `scripts/db-bootstrap.mjs` applies+ `schema.sql` before migrations and a fresh database should get a schema.sql comment that isn't+ misleading about which feature owns this table name today; do not change the actual `CREATE TABLE`+ statement in `schema.sql` itself (it must keep creating the legacy shape so the migration chain's rename+ step has something to rename on a from-scratch bootstrap, exactly mirroring what happened in production).+5. Run `npx vitest run tests/account-link.test.js tests/account-link-codes-schema.test.js` and confirm both+ files pass.+6. Run `npm run check:rules -- --paths api/_lib/migrations/20261024120000_fix_account_link_codes_collision.sql tests/account-link-codes-schema.test.js api/_lib/schema.sql` (substitute the real migration filename chosen in Task 1).+7. Delete any scratch/diagnostic scripts you create while working this order before committing (repo+ hygiene: no throwaway scripts in the root or in `scripts/` once the order is done).++## Definition of done++- [ ] New migration file exists under `api/_lib/migrations/`, renames the legacy table and index, then+ creates the correctly-shaped `account_link_codes` table and index (verified by re-reading the file).+- [ ] `npm run db:migrate` applied it against the real database and `npm run db:status` reports no pending+ migrations and no drift.+- [ ] `select column_name from information_schema.columns where table_name = 'account_link_codes'` now+ returns the new-schema columns (`status`, `device_kind`, `claim`, `claim_secret_hash`, `result_kind`,+ `result_id`, `result_secret`, `device_id`, `claimed_at`, `decided_at`, `consumed_at`), not the old ones.+- [ ] `select to_regclass('account_link_codes_agents_v1_legacy')` is not null (old data preserved, nothing destroyed).+- [ ] `tests/account-link-codes-schema.test.js` exists, reproduces the original 42703 failure mode in its+ first assertion, and passes end to end after the fix.+- [ ] `npx vitest run tests/account-link.test.js tests/account-link-codes-schema.test.js` exits 0.+- [ ] `npm run check:rules -- --paths <files touched>` exits 0.+- [ ] `api/_lib/schema.sql`'s comment above the `account_link_codes` block is corrected; its `CREATE TABLE`+ statement is unchanged.+- [ ] No scratch files left in the repo root or `scripts/`.+- [ ] One `data/changelog.json` entry (tag `fix`) describing the account-linking fix in terms a user would+ recognize ("fixed phone/desktop/CLI/Telegram account linking, which was failing on every attempt").+- [ ] Commit with explicit paths; subject names the actual fix (e.g.+ `fix(account-link): rename the colliding account_link_codes table so device linking stops throwing 42703`).++## Never blocked++| Looks like a blocker | It is not | Do this |+|---|---|---|+| `npm run db:migrate` applies immediately with no dry run, against what might be the shared production database | This is the documented, existing convention for every migration in this repo (`npm run db:status` confirms current state first); the rename preserves all old rows and the create is `IF NOT EXISTS`, so the operation is safe and reversible by renaming back | Run `npm run db:status` before and after, exactly as every other migration-writing order in this repo does |+| You can't tell whether `account_link_codes_agents_v1_legacy`'s old rows are "important" | They are 10-minute-TTL link codes from a feature that, per the grep in Step 0, no live code path reads; renaming (not dropping) satisfies the no-data-destruction rule regardless | Rename, never drop; note the row count you preserved in the report |+| `tests/account-link.test.js`'s mocked-DB pattern makes it awkward to add a real-DB assertion in the same file | That is exactly why Task 3 creates a separate file instead of extending the mocked suite | Keep the new real-DB test in its own file; do not weaken or remove the existing mock-based tests |+| No `DATABASE_URL` is resolvable in this environment | Every other migration/db script in this repo reads `.env.local` first; if that file is genuinely absent here, that is itself new information worth one line in the report, but check `.env.local` exists (per Step 0, it is present as of 2026-10-24) before concluding that | Read `.env.local`'s presence the same way `scripts/apply-migrations.mjs` does before assuming it's missing |++## Close out (required)++1. Verify every Definition of done line with the command output in front of you. Never claim a line you did not verify.+2. Commit with explicit paths.+3. Delete this file in the final commit (`git rm prompts/finish/433-auto-fix-account-link-codes-schema-collision.md`) once every Definition of done line is verified green, and append a dated entry to `prompts/finish/_context/production-100-PROGRESS.md` with the commit SHA. If a line cannot pass, leave the file and say which line remains and why.+4. Final report, in this order: the Step 0 measurements, the migration filename chosen, the before/after column lists, the test output, the commit SHA. No trailing questions.