feat(sec): SPAC de-SPAC lifecycle — 8-K milestones, merger-proxy & redemption extraction

CLAUDE.md

@@ -175,9 +175,58 @@ and rolled-up key dates. It is **derived** from two append-only tables — `spac
 so replays are idempotent; an `as_of` guard protects filing-sourced scalar fields
 from out-of-order writes, and `spac_history` + `ChangeLog` version the row.
 
-Today only the IPO half is populated (S-1/DRS → `registration`, priced 424B1/424B4
-→ `ipo`); de-SPAC events (8-K items, S-4/proxy, redemptions, PIPE, de-registration)
-are defined-but-deferred slots.
+The IPO half is populated from S-1/DRS (`registration`) and priced 424B1/424B4
+(`ipo`). De-SPAC **milestone dates** are populated deterministically from 8-K
+item codes (known SPACs only — a `spac` row must already exist): item `1.01` →
+`definitive_agreement`, `1.02` → `terminated`, `2.01` → `completed`, `5.07` →
+`vote`. These group into `spac_deal` attempts via `deriveDeals`
+(recomputed from the event stream on every write, so `deal_index` is stable
+across replays) and roll up automatically. `target_name`, `pipe_amount`, and
+redemption amounts stay null until the narrative/AI extractors (S-4 / DEFM14A /
+425) land — 8-K item codes carry no names or amounts. Still deferred: name/SIC/
+ticker transitions and Form 25/15 de-registration.
+
+**Merger proxies** (`DEFM14A`/`PREM14A`, the `DEFM14C`/`PREM14C` consent statements,
+and the `DEFR14A`/`PRER14A` revised proxies; extractor id `merger-proxy`) run
+`processMergerProxy` (known SPACs only — a `spac` row must already exist): AI
+extraction over the merger / business-combination / PIPE sections records a
+per-accession `spac_merger_extraction` row (target name/CIK, PIPE amount, merger
+consideration) and observes the target company (`relation: "merger-proxy:target"`,
+`target_cik` resolved from the canonical company when it has one). `deriveDeals`
+correlates each extraction onto the matching `spac_deal` by filing-date window —
+*deriving* `target_name` / `target_cik` / `pipe_amount` (a later filing supersedes
+an earlier one — definitive over preliminary, revised over definitive), which
+retires the 8-K path's positional merge-preserve. Only the **definitive merger**
+statements `DEFM14A` and `DEFM14C` emit the `proxy` event (→ `proxy_date` /
+`status = proxy`): a consent deal (14C) has no `8-K 5.07` vote, so the definitive
+14C is its only approval-stage signal. Preliminary (`PREM14A`/`PREM14C`) and revised
+(`DEFR14A`/`PRER14A`) proxies are extraction-only. S-4 is deferred (newco-CIK linkage). Configure the
+model via `SEC_MERGER_PROXY_MODEL` (default `claude-sonnet-4-6`) and an optional
+confidence floor via `SEC_MERGER_PROXY_CONFIDENCE_FLOOR` (falls back to the shared
+`SEC_S1_CONFIDENCE_FLOOR` when unset).
+
+```bash
+sec fetch form <cik> DEFM14A             # fetch + extract a merger proxy
+sec extractor dead-letters merger-proxy  # version-fixable extraction failures
+sec extractor retry-dead-letters merger-proxy
+```
+
+**Redemption actuals** (extractor id `redemption`) are AI-extracted from a known
+SPAC's post-vote 8-K narrative. When an 8-K carries item `5.07`, `2.01`, or `8.01`
+for a known SPAC, ingestion escalates the fetch to the full submission `.txt` and
+reads the primary document + `EX-99.x` exhibits; `processRedemption8K` records a
+per-accession `spac_redemption_extraction` row, and `deriveDeals` correlates
+`redemption_amount` / `redemption_shares` onto the matching `spac_deal`. The deal
+column is the sole source `total_redemption_amount` sums, so redemptions are counted
+once. Configure the model via `SEC_REDEMPTION_MODEL` (default `claude-sonnet-4-6`)
+and an optional confidence floor via `SEC_REDEMPTION_CONFIDENCE_FLOOR` (falls back to
+`SEC_S1_CONFIDENCE_FLOOR`).
+
+```bash
+sec spac backfill-redemptions            # sweep historical known-SPAC trigger 8-Ks
+sec extractor dead-letters redemption    # version-fixable extraction failures
+sec extractor retry-dead-letters redemption
+```
 
 ```bash
 sec spac report <cik> [--format json]   # consolidated report

src/cli/groups/version.test.ts

@@ -64,6 +64,8 @@ describe("sec version CLI", () => {
         "CFPORTAL",
         "D",
         "S-1",
+        "merger-proxy",
+        "redemption",
       ]);
       const extractorRows = parsed.filter(
         (r: { component_kind: string }) => r.component_kind === "extractor"

src/commands/spac.ts

@@ -6,9 +6,11 @@
 
 import { Command } from "commander";
 import { globalServiceRegistry } from "workglow";
+import { withCli } from "@workglow/cli";
 import { SpacRepo } from "../storage/spac/SpacRepo";
 import { SPAC_SPONSOR_LINK_REPOSITORY_TOKEN } from "../storage/canonical/SpacSponsorLinkSchema";
 import { UNDERWRITER_LINK_REPOSITORY_TOKEN } from "../storage/canonical/UnderwriterLinkSchema";
+import { BackfillRedemptionsTask } from "../task/spac/BackfillRedemptionsTask";
 
 export interface SpacReport {
   readonly cik: number;
@@ -110,4 +112,15 @@ export function registerSpacCommands(program: Command): void {
         );
       }
     });
+
+  spacCmd
+    .command("backfill-redemptions")
+    .description("Re-process known-SPAC trigger-item 8-Ks to extract realized redemptions")
+    .action(async () => {
+      const out = (await withCli(new BackfillRedemptionsTask()).run({})) as {
+        selected: number;
+        processed: number;
+      };
+      console.log(`selected ${out.selected} filing(s); processed ${out.processed}`);
+    });
 }

src/config/DefaultDI.ts

@@ -344,6 +344,16 @@ import {
   SpacHistoryPrimaryKeyNames,
   SpacHistorySchema,
 } from "../storage/spac/SpacHistorySchema";
+import {
+  SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN,
+  SpacMergerExtractionPrimaryKeyNames,
+  SpacMergerExtractionSchema,
+} from "../storage/spac/SpacMergerExtractionSchema";
+import {
+  SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN,
+  SpacRedemptionExtractionPrimaryKeyNames,
+  SpacRedemptionExtractionSchema,
+} from "../storage/spac/SpacRedemptionExtractionSchema";
 import { createStorage } from "./createStorage";
 
 export const DefaultDI = () => {
@@ -665,6 +675,24 @@ export const DefaultDI = () => {
     SPAC_HISTORY_REPOSITORY_TOKEN,
     createStorage("spac_history", SpacHistorySchema, SpacHistoryPrimaryKeyNames, [["cik"]])
   );
+  globalServiceRegistry.registerInstance(
+    SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN,
+    createStorage(
+      "spac_merger_extraction",
+      SpacMergerExtractionSchema,
+      SpacMergerExtractionPrimaryKeyNames,
+      [["cik"]]
+    )
+  );
+  globalServiceRegistry.registerInstance(
+    SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN,
+    createStorage(
+      "spac_redemption_extraction",
+      SpacRedemptionExtractionSchema,
+      SpacRedemptionExtractionPrimaryKeyNames,
+      [["cik"]]
+    )
+  );
 
   // ----- Observation / Canonical / Resolver -----
   globalServiceRegistry.registerInstance(

src/config/TestingDI.ts

@@ -258,6 +258,16 @@ import {
   SpacHistoryPrimaryKeyNames,
   SpacHistorySchema,
 } from "../storage/spac/SpacHistorySchema";
+import {
+  SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN,
+  SpacMergerExtractionPrimaryKeyNames,
+  SpacMergerExtractionSchema,
+} from "../storage/spac/SpacMergerExtractionSchema";
+import {
+  SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN,
+  SpacRedemptionExtractionPrimaryKeyNames,
+  SpacRedemptionExtractionSchema,
+} from "../storage/spac/SpacRedemptionExtractionSchema";
 import {
   CANONICAL_COMPANY_REPOSITORY_TOKEN,
   CanonicalCompanyPrimaryKeyNames,
@@ -493,6 +503,22 @@ export function resetDependencyInjectionsForTesting() {
     SPAC_HISTORY_REPOSITORY_TOKEN,
     new InMemoryTabularStorage(SpacHistorySchema, SpacHistoryPrimaryKeyNames, [["cik"]])
   );
+  globalServiceRegistry.registerInstance(
+    SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN,
+    new InMemoryTabularStorage(
+      SpacMergerExtractionSchema,
+      SpacMergerExtractionPrimaryKeyNames,
+      [["cik"]]
+    )
+  );
+  globalServiceRegistry.registerInstance(
+    SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN,
+    new InMemoryTabularStorage(
+      SpacRedemptionExtractionSchema,
+      SpacRedemptionExtractionPrimaryKeyNames,
+      [["cik"]]
+    )
+  );
 
   // Initialize Crowdfunding repositories
   globalServiceRegistry.registerInstance(

src/config/setupAllDatabases.ts

@@ -54,6 +54,8 @@ import { SPAC_REPOSITORY_TOKEN } from "../storage/spac/SpacSchema";
 import { SPAC_DEAL_REPOSITORY_TOKEN } from "../storage/spac/SpacDealSchema";
 import { SPAC_EVENT_REPOSITORY_TOKEN } from "../storage/spac/SpacEventSchema";
 import { SPAC_HISTORY_REPOSITORY_TOKEN } from "../storage/spac/SpacHistorySchema";
+import { SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN } from "../storage/spac/SpacMergerExtractionSchema";
+import { SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN } from "../storage/spac/SpacRedemptionExtractionSchema";
 import {
   CANONICAL_COMPANY_ALIAS_REPOSITORY_TOKEN,
   CANONICAL_PERSON_ALIAS_REPOSITORY_TOKEN,
@@ -145,6 +147,8 @@ export async function setupAllDatabases(): Promise<void> {
   await globalServiceRegistry.get(SPAC_DEAL_REPOSITORY_TOKEN).setupDatabase();
   await globalServiceRegistry.get(SPAC_EVENT_REPOSITORY_TOKEN).setupDatabase();
   await globalServiceRegistry.get(SPAC_HISTORY_REPOSITORY_TOKEN).setupDatabase();
+  await globalServiceRegistry.get(SPAC_MERGER_EXTRACTION_REPOSITORY_TOKEN).setupDatabase();
+  await globalServiceRegistry.get(SPAC_REDEMPTION_EXTRACTION_REPOSITORY_TOKEN).setupDatabase();
   await globalServiceRegistry.get(CIK_LAST_UPDATE_REPOSITORY_TOKEN).setupDatabase();
   await globalServiceRegistry.get(PROCESSED_FACTS_REPOSITORY_TOKEN).setupDatabase();
   await globalServiceRegistry.get(PROCESSED_SUBMISSIONS_REPOSITORY_TOKEN).setupDatabase();

src/sec/forms/miscellaneous-filings/Form_8_K.storage.ts

@@ -4,10 +4,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { ModelConfig } from "workglow";
 import { Form8KEventRepo } from "../../../storage/form-8k-event/Form8KEventRepo";
 import type { Form8KEvent } from "../../../storage/form-8k-event/Form8KEventSchema";
 import type { Form8K } from "./Form_8_K.schema";
 import { Form_8_K_ITEMS } from "./Form_8_K";
+import { SpacRepo } from "../../../storage/spac/SpacRepo";
+import { SpacReportWriter } from "../../../storage/spac/SpacReportWriter";
+import { mapItemCodesToSpacEvents } from "./spac8kMilestones";
+import { processRedemption8K } from "./redemption8k";
 
 /**
  * Extracts item codes from the filing metadata `items` field.
@@ -48,6 +53,8 @@ export async function processForm8K({
   items,
   report_date,
   form8K,
+  fullSubmissionText,
+  model,
 }: {
   readonly cik: number;
   readonly accession_number: string;
@@ -56,6 +63,8 @@ export async function processForm8K({
   readonly items: string | undefined | null;
   readonly report_date: string | undefined | null;
   readonly form8K: Form8K;
+  readonly fullSubmissionText?: string;
+  readonly model?: ModelConfig;
 }): Promise<void> {
   const eventRepo = new Form8KEventRepo();
   const isAmendment = form === "8-K/A";
@@ -76,4 +85,37 @@ export async function processForm8K({
     };
     await eventRepo.saveEvent(event);
   }
+
+  // --- Consolidated SPAC report: map de-SPAC milestone items (known SPACs only) ---
+  const spacRow = await new SpacRepo().getSpac(cik);
+  if (spacRow) {
+    // Skip when no usable date is available: an undated milestone (empty
+    // event_date) would write junk announced_date/definitive_agreement_date
+    // onto the deal/row. Reachable only on the best-effort path where the
+    // filing-metadata row is absent (report_date null, filing_date "").
+    const eventDate = effectiveReportDate || filing_date;
+    const spacEvents = eventDate ? mapItemCodesToSpacEvents(itemCodes, eventDate) : [];
+    if (spacEvents.length > 0) {
+      await new SpacReportWriter().recordDealMilestones({
+        cik,
+        accession_number,
+        filing_date,
+        form,
+        primary_document: null,
+        events: spacEvents,
+      });
+    }
+  }
+
+  if (spacRow && fullSubmissionText) {
+    await processRedemption8K({
+      cik,
+      accession_number,
+      filing_date,
+      form,
+      itemCodes,
+      fullSubmissionText,
+      model,
+    });
+  }
 }