Family-tier `resolve`, then re-enable `drop-previous` for the family kinds

[sroussey]

Follow-up to #237, which registered coverage for sponsor-family / underwriter-family but deliberately left dropPrevious unregistered, so sec version drop-previous resolver sponsor-family still errors.

Why the purge was held back

On the person/company tier a version purge is safe because identity links are derived. The observation rows outlive the purge, so sec resolve --kind person --all rebuilds every link that was removed. Purge-then-rebuild is a closed loop.

The family tier has no such backstop:

• there is no observation → identity-link table — the per-filing link row is the attribution (spac_sponsor_link, underwriter_link), not a projection of something that survives it; and
• batch sec resolve refuses family kinds (person|company allow-list), so nothing can rebuild what a purge deletes.

Recovery from a family purge today means re-extracting every affected S-1/424 through the AI pipeline and re-paying that cost. And the trap is quiet: drop-previous is symmetric in shape across all four resolver kinds, so at the call site it reads like the same routine cleanup whichever kind it is handed.

What this issue asks for

1. Implement a family-tier resolve so family attribution is rebuildable from data that survives a purge, restoring the invariant person/company rely on.
2. Then register the dropPrevious closures for both family kinds, re-enabling the ceremony.

The hard part

A family is keyed off the sponsor/underwriter common name the AI extractor emitted. Only the legal name reaches the observation row, and the canonical family retains just one variant's display name — so a naive batch pass cannot faithfully re-partition families. A normalizer change that splits a family would reassign every member from that single stored name.

So this is not just wiring: it needs a decision about where the common name lives durably. Options worth weighing:

• persist the extractor's common name on the observation row (or a sibling table), so re-partitioning has the original input to work from;
• store the per-filing family assignment inputs alongside the link row, making the link reconstructable without re-extraction;
• accept re-extraction as the only rebuild path and keep drop-previous refusing family kinds permanently — in which case close this and document the asymmetry as deliberate rather than temporary.

Already in place

SpacSponsorLinkRepo.deleteForResolverVersion and UnderwriterLinkRepo.deleteForResolverVersion landed in #237 with tests, and are intentionally unreferenced by any command. They are the building block the purge needs — no command reaches them until the closures are registered.

registerResolvers.family.test.ts currently asserts the refusal and that every family row survives it on both tiers at both versions; those tests invert when the purge is re-enabled.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01KB8s4qR5goCoxjE94YDFUV

[sroussey]

The "hard part" here is addressed by #276, though the issue itself stays open — what lands is the foundation, not the ceremony.

What changed

This issue frames the blocker as:

A family is keyed off the sponsor/underwriter common name the AI extractor emitted. Only the legal name reaches the observation row … so a naive batch pass cannot faithfully re-partition families.

and lists three ways out, the first being "persist the extractor's common name on the observation row".

#276 takes a fourth: stop keying off the common name at all. normalizeFamilyName now derives the key from the legal name via a new companyFamilyName, and the legal name is a value every observation already carries. So re-partitioning becomes a re-computation — no new column, no sibling table, no re-extraction, and nothing to keep durable that isn't already.

companyFamilyName strips what separates one vehicle from the next — trailing legal form, series marker (roman numeral / year), parenthetical jurisdiction, Entities affiliated with bloc prefix, and a conjunction stranded by & Co. So Churchill Sponsor XIII LLC and Churchill Sponsor XIV LLC are one family off their legal names alone.

It deliberately does not fold business-line words. Acme Capital and Acme Ventures can be unrelated firms, and the asymmetry decides it: an over-merge silently attributes one house's deals to another and leaves no trace, while an under-merge is visible as two families and costs one alias. The rare genuine join stays an explicit, reviewable claim:

sec canonical underwriter-family alias "Chardan Capital Markets" "Chardan"

A nice side effect, and the clearest evidence the key improved: the existing UnderwriterFamilyResolver test that aliased Morgan Stanley & Co. → Morgan Stanley started failing with "self-alias is not permitted" — the normalizer now unifies that pair without an alias. Aliases are spent on judgment calls rather than on punctuation.

What this issue still wants

Both remaining items are unchanged in shape, just no longer blocked:

1. A family-tier resolve — batch sec resolve still refuses sponsor-family / underwriter-family via the person|company allow-list. The reason it had to is gone; the wiring is not written.
2. Register the dropPrevious closures for both kinds, inverting registerResolvers.family.test.ts, once (1) restores the rebuild invariant. SpacSponsorLinkRepo.deleteForResolverVersion / UnderwriterLinkRepo.deleteForResolverVersion from feat(resolver): family-tier coverage ceremony (drop-previous deliberately deferred) #237 are still the building block and still unreferenced.

So the third option this issue floats — "accept re-extraction as the only rebuild path and close this" — is no longer the pragmatic choice. Re-extraction is no longer the only path, so the deliberate-asymmetry framing can be dropped.

Two things to know before picking it up

• The key format changed (GOLDMAN SACHS → GOLDMAN-SACHS, and vehicle-level differences now collapse), so existing canonical_*_family.normalized_name rows and any operator-installed aliases keyed to those ids are orphaned. fix(eval): scope personNameFields to person-only extractors, and pass it everywhere #276 ships scripts/sql/truncate-identity-tier.sql (and a Postgres variant) which clears the derived identity tier and extractor_runs, so re-extraction happens at the same resolver version — no bump.
• family_description is keyed (family_kind, normalized_name), outside the canonical tier, so it survives the truncate but no longer matches. It is hand-curated and has no rebuild path other than re-import: sec editorial import data/editorial/family-descriptions.csv. Worth deciding whether the family-tier resolve should re-key it rather than leaving that to the operator.

---

Generated by Claude Code