fix(background): avoid WorkOS org slug upserts

[tgmendes]

Why?

WorkOS organization sync was failing with duplicate key value violates unique constraint "organization_metadata_slug_key". The upsert had ON CONFLICT (id) DO UPDATE but no protection against the separate slug unique index — when an event updated an org's name, the resulting slug could collide with a sibling row's existing slug and the whole event would fail (and retry forever).

What?

Switched from blind upsert to fetch-then-write. Pure INSERT on the create path, pure UPDATE on the update path, slug never touched after initial creation.

Resolution flow for organization create/update events:

• Look up by workos_id. If found → update.
• Otherwise, if external_id is set → look up by it (Gram org ID = external_id). If found → update; if not → INSERT a new row using external_id as the Gram ID.
• Otherwise (no external_id), derive a deterministic Gram org ID via UUIDv5 from the WorkOS org ID, INSERT locally, then push that ID back to WorkOS as the external_id after the local transaction commits. Ordering ensures the remote external_id never points at a row that failed to persist. If the WorkOS write fails we log and rely on the next event to retry.

Also added a ShouldProcessEvent guard (event-ID lexicographic compare on ULIDs, falling back to workos_updated_at) so duplicate/out-of-order events from reconcile-overlap or backfill replay don't rewind state.

Concurrency considerations

• Per-WorkOS-org workflows are serialized via Temporal SignalWithStartWorkflow + USE_EXISTING, so same-org events never race.
• Cross-org create race (two events resolving to the same Gram org ID): the second INSERT fails with a PK conflict, the activity returns the error, Temporal retries, and the retry resolves to the update path.
• Cross-org slug race (two different orgs slugifying to the same base): protected by pg_advisory_xact_lock(hashtext(slug)) taken before FindUnique, so concurrent inserts on the same base slug serialize.
• Concurrency vs non-WorkOS writers (dashboard rename, signup flow, etc.) is
  NOT serialized by Temporal — only WorkOS sync vs WorkOS sync is. Known
  consequences:
  • Local UPDATE racing a WorkOS UPDATE: last writer wins. ShouldProcessEvent
    only de-dups WorkOS events against the cursor; it doesn't observe local writes.
  • Local INSERT racing a WorkOS INSERT on the same derived ID: second INSERT
    fails with PK conflict and Temporal retries into the update path.
  • Local INSERT racing a WorkOS INSERT on the same slug: advisory lock is
    WorkOS-side only; PG slug unique violation triggers retry + suffix.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5614dbb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
gram-docs-redirect	Ready	Preview, Comment	May 20, 2026 9:53am

[tgmendes]

@claude review once

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, comment @claude review on this pull request to trigger a review.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[speakeasybot]

🚀 Preview Environment (PR #2925)

Preview URL: https://pr-2925.dev.getgram.ai

Component	Status	Details	Updated (UTC)
✅ Database	Ready	Existing database reused	2026-05-20 10:56:40.
✅ Images	Available	Container images ready	2026-05-20 10:55:36.

_{Gram Preview Bot}