fix(llmo): make syncBrandSites non-destructive to the primary citation row (LLMO-4621)

[rainer-friederich]

Related Issues

• LLMO-4621 — Pattern A: 13 active root brands ended up with no brand_sites linkage despite brands.site_id being set
• Companion DB trigger PR (existence invariant): adobe/mysticat-data-service#496 — adds the brands_ensure_primary_brand_site trigger
• Companion backfill PR (24 historical brands): adobe-rnd/llmo-data-retrieval-service#1494

Problem

syncBrandSites (src/support/brands-storage.js) did an unconditional DELETE then early-returned on empty urls without re-INSERT. A second caller — most plausibly POST /v2/orgs/{orgId}/brands from Brandalf brand-sync — re-upserting an active root with urls=[] for an existing active brand silently wiped the primary citation row. The audit-time symptom: 13 active root brands with brands.site_id set, bs_count=0, and zero prompts. Bleed stopped at Satori 2026-04-28 20:58 UTC by coincidence.

The Pattern A investigation is on LLMO-4621 comment 54398141.

Fix split

The LLMO-4621 invariant — "every active brand with brands.site_id set has at least one brand_sites row mirroring brands.site_id" — has two halves. Each half is enforced where the codebase rules say it belongs.

invariant	enforced where	mechanism
Primary brand_sites row exists when brands.site_id is set	DB	brands_ensure_primary_brand_site trigger in adobe/mysticat-data-service#496, mirrors the existing set_brand_site_organization_id auto-fill pattern
syncBrandSites cannot wipe the primary brand_sites row	App (this PR)	non-destructive syncBrandSites rewrite
Onboarding upsertBrand failures are visible to operators	App (this PR)	log.warn → log.error + Slack say()

mysticat-data-service/CLAUDE.md explicitly disrecommends triggers that RAISE on writes ("If you're writing a BEFORE UPDATE trigger that raises an exception, you're probably granting UPDATE when you shouldn't be"), so the non-destruction half cannot live in a BEFORE DELETE … RETURN NULL trigger. It stays in app code.

What's in this PR

src/support/brands-storage.js

• syncBrandSites rewritten non-destructively. Replaces DELETE-then-INSERT with: load brands.site_id (the protected primary), upsert the desired URL-derived rows, then DELETE only pre-existing rows whose site_id is NOT in the desired set AND NOT the primary. The targeted DELETE uses PK ids to avoid PostgREST not.in quoting edge cases.

src/controllers/llmo/llmo-onboarding.js

• The swallowed Failed to create initial brand in normalized table is elevated from log.warn to log.error and now also emits a Slack-visible warning via say(). Onboarding still proceeds (the SpaceCat site row exists), but operators see the failure in Coralogix and the onboarding Slack thread immediately rather than weeks later via audit query — this was the silent-failure surface that hid the original bleed.

What's NOT in this PR (deliberately)

• ensurePrimaryBrandSite helper — superseded by the DB trigger in adobe/mysticat-data-service#496.
• BEFORE DELETE trigger on brand_sites — would be the BEFORE … RAISE anti-pattern explicitly disrecommended by mysticat-data-service/CLAUDE.md. The non-destruction half stays in syncBrandSites instead.
• Backfill of the 24 historical brands — covered by adobe-rnd/llmo-data-retrieval-service#1494.

Test plan

• npx mocha test/support/brands-storage.test.js — 81 passing (3 existing error-path tests revised to match the new flow, 1 new regression test added)
• npx mocha test/controllers/llmo/llmo-onboarding.test.js — 97 passing (the swallow assertion updated to match the new log.error + say shape)
• npx mocha test/controllers/brands.test.js — 231 passing
• npm run lint clean (exit 0; pre-existing deprecation warnings only, none from this change)

New / revised tests covering LLMO-4621

• throws when brand_sites upsert fails during syncBrandSites — first error path in the new flow (desired-set upsert failure)
• throws when brand_sites orphan-cleanup delete fails during syncBrandSites — third error path in the new flow (orphan DELETE failure)
• throws when SELECT existing brand_sites fails during syncBrandSites orphan-cleanup — second error path in the new flow (load existing failure)
• preserves primary brand_sites row in syncBrandSites when caller urls do not match the primary site — the actual non-destruction invariant (primary site_id is excluded from the orphan DELETE even when the caller's URLs target a different site entirely)

Deploy ordering

The two companion PRs (this one + adobe/mysticat-data-service#496) are independent and can deploy in either order or in parallel. Either one alone closes the api-service write path. Both together cover all writers (api-service + future scripts/services) AND make the invariant impossible to violate via the destructive DELETE pattern. The backfill (adobe-rnd/llmo-data-retrieval-service#1494) runs against prod after this PR merges to repair the 24 historical brands.

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a patch release when merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!