Story 1528: DOCTYPES follow-ups — case-insensitive unique(firm_id, name) + seed defaults

Repo: pramaan-functions · Parent: EPIC-1489 · Follow-up to the Story-1497 DOCTYPES review.

🛰️ Satellite — WHY this exists (the catastrophe it prevents)

Story-1497 shipped the firm-wide business.document_types catalog, but left a door welded shut on day one. A brand-new firm logs in, opens the Documents Register, and the document-type dropdown is empty. Every firm's very first real action — "tag this file as a Contract" — fails, because nobody put a Contract in the catalog. A controlled vocabulary that starts empty is no vocabulary at all: the first lawyer is forced to free-type, and the moment two lawyers free-type the same idea with different casing (Contract vs contract), the register can never group or roll up consistently again.

This Story closes both halves of that gap, the two follow-ups the 1497 review flagged:

1. Uniqueness — two live types in one firm can never collide on name, compared case-insensitively.
2. A non-empty first run — every new firm is born with a canonical starter catalog, the same way it is already born with default matter types, participant labels, and firm roles.

✈️ Airplane — the analogy and the shape of the fix

Think of the catalog like the tabbed dividers in a physical case binder. Follow-up (1) is the rule "no two dividers may carry the same label" — and the librarian reads labels case-blind, so Contract and contract are the same divider. Follow-up (2) is the pre-printed starter set of dividers that ships inside every new binder so counsel never opens an empty one.

The whole catalog domain (entity, repository, CRUD API, RLS, audit) already exists from 1497. This Story adds nothing to the wire contract — it is a data-state fix, not a surface change. make openapi confirms zero drift.

Where the seed plugs in (firm provisioning)

FirmService.create_firm(...)        # one transaction, caller-owned
  ├─ insert firm + subscription
  ├─ seed_default_participant_labels   (existing)
  ├─ seed_default_matter_types         (existing)
  ├─ seed_default_document_types  ←──  NEW (this Story)
  └─ seed_default_firm_roles           (existing)

🔬 Microscopic — what shipped

Follow-up 1 — case-insensitive uniqueness (already in place; verified, no migration)

The required constraint already shipped inside Story-1497's migration 0109 (f3a1c7e90b24, PR #383) as the partial-unique index uq_document_types_firm_lower_name_live:

CREATE UNIQUE INDEX uq_document_types_firm_lower_name_live
    ON business.document_types (firm_id, lower(name))
    WHERE availability = 'live';

This is exactly the filing-types parity the AC asks for: per-firm, case-insensitive (lower(name)), and scoped to live rows so an archived contract never blocks creating a new one. Adding a second migration for the same index would fail (CREATE INDEX name collision) and break the single-head rule, so the correct action is to verify and rely on it, not duplicate it. Alembic head is unchanged at 0114 — single head preserved.

The application layer already enforced this case-insensitively too: repository.find_live_by_name matches on lower(name) == name.casefold() and raises 409 pramaan.document_type.name_conflict; the unique index is the last-line DB guarantee under a race.

Follow-up 2 — seed defaults on firm-create (NEW)

The starter set (a firm can rename/archive any of these afterward):

Contract · Affidavit · Pleading · Order · Judgment · Notice ·
Correspondence · Bank Statement · Invoice · Photograph ·
Identity Document · Other

The seed contract — titled by reason, not by mechanism

• Idempotent so re-provisioning is safe. It reads the firm's existing non-deleted names (case-folded) first and skips any default already present — running it twice yields exactly one of each.
• Archived rows count as "already there" so a firm's choices stick. If a firm archived Contract, re-seeding does not resurrect it — the match is availability != 'deleted', case-insensitive, mirroring the matter-type and participant-label seeds exactly.
• No display number, because a document type is a plain label. Unlike matter/participant/filing types, document types carry no *_number and call no business.allocate_reference — the seed just inserts rows (PRD O1, LOCKED).
• RLS-correct under the caller's transaction. The seed sets app.current_firm_id for the insert and restores the prior value in a finally, so the firm-write RLS policy passes and no firm context leaks to the next operation.
• No bespoke span (pramaan-docs ADR-124). The seed is covered by the create_firm boundary span; it adds no new external boundary, so it is instrumentation-exempt by the caller-covered rule.

Proof — real requests against a real (empty-first-run) DB

Run against the isolated Docker test DB at head (make test-db → 0114):

• test_seed_default_document_types_is_canonical_and_idempotent — seeds a fresh empty firm, runs the seed twice, asserts the live catalog equals the full canonical set with no duplicates and includes Other.
• test_seed_default_document_types_respects_archived_rows — pre-archives a lowercase contract, re-seeds, asserts exactly one contract row survives and it stays archived (the case-insensitive skip works).
• The existing 1497 CRUD / RLS / permission / 401 tests still pass, and the firm-provisioning suites (test_admin_firms, test_webhooks_clerk_route, services) stay green with the new seed in the create path.
• make openapi → no drift (no contract change).

One-sentence recall

1497 already gave the DB the case-insensitive unique(firm_id, lower(name)) WHERE live guard, so this follow-up's real work is the missing non-empty first run: every new firm is now born with a canonical, idempotent, archive-respecting starter set of document types — the same seed pattern as matter types and participant labels, just without a number.