feat(spac): enhance SPAC candidate classification logic

- Introduced a new function to determine the latest classification status of SPAC candidates based on their filings, allowing for more accurate filtering of candidates.
- Updated the `listSpacProcessCiks` function to exclude candidates classified as not SPAC based on their latest registration.
- Added comprehensive test cases to validate the new classification logic and ensure correct behavior when processing SPAC candidates.
- Refactored related code to improve clarity and maintainability, including updates to the database schema for classification storage.

Author: sroussey

src/cli/sync/spacSyncCiks.test.ts

@@ -8,6 +8,8 @@ import { beforeEach, describe, expect, it } from "vitest";
 import { globalServiceRegistry } from "workglow";
 import { resetDependencyInjectionsForTesting } from "../../config/TestingDI";
 import { setupAllDatabases } from "../../config/setupAllDatabases";
+import { S1_CLASSIFICATION_REPOSITORY_TOKEN } from "../../storage/classification/S1ClassificationSchema";
+import { FILING_REPOSITORY_TOKEN } from "../../storage/filing/FilingSchema";
 import {
   SPAC_CANDIDATE_REPOSITORY_TOKEN,
   type SpacCandidate,
@@ -72,6 +74,42 @@ function minimalSpac(cik: number): Spac {
   };
 }
 
+async function putClassification(args: {
+  readonly cik: number;
+  readonly accession_number: string;
+  readonly filing_date: string;
+  readonly is_spac: boolean;
+  readonly created_at?: string;
+}): Promise<void> {
+  await globalServiceRegistry.get(FILING_REPOSITORY_TOKEN).put({
+    cik: args.cik,
+    accession_number: args.accession_number,
+    filing_date: args.filing_date,
+    report_date: null,
+    acceptance_date: `${args.filing_date}T12:00:00.000Z`,
+    form: "S-1",
+    file_number: null,
+    film_number: null,
+    primary_doc: "doc.htm",
+    primary_doc_description: null,
+    size: null,
+    is_xbrl: null,
+    is_inline_xbrl: null,
+    items: null,
+    act: null,
+  });
+  await globalServiceRegistry.get(S1_CLASSIFICATION_REPOSITORY_TOKEN).put({
+    extractor_id: "S-1",
+    accession_number: args.accession_number,
+    cik: args.cik,
+    sic: args.is_spac ? 6770 : 6141,
+    sic_description: null,
+    is_spac: args.is_spac,
+    classifier_source: "sgml-header",
+    created_at: args.created_at ?? "2026-08-17T00:00:00.000Z",
+  });
+}
+
 function candidateRow(cik: number, confidence: SpacCandidate["confidence"]): SpacCandidate {
   return {
     cik,
@@ -132,6 +170,74 @@ describe("listSpacProcessCiks", () => {
     await expect(listKnownSpacCiks()).resolves.toEqual([1]);
     await expect(listSpacProcessCiks()).resolves.toEqual([1, 2]);
   });
+
+  it("drops a medium candidate whose latest registration classified is_spac=false", async () => {
+    const candidateRepo = globalServiceRegistry.get(SPAC_CANDIDATE_REPOSITORY_TOKEN);
+    await candidateRepo.put(candidateRow(7974, "medium"));
+    await putClassification({
+      cik: 7974,
+      accession_number: "0000950134-96-000313",
+      filing_date: "1996-02-09",
+      is_spac: false,
+    });
+
+    await expect(listSpacProcessCiks()).resolves.toEqual([]);
+  });
+
+  it("keeps a known SPAC whose later operating registration classified is_spac=false", async () => {
+    const spacRepo = globalServiceRegistry.get(SPAC_REPOSITORY_TOKEN);
+    const candidateRepo = globalServiceRegistry.get(SPAC_CANDIDATE_REPOSITORY_TOKEN);
+    await spacRepo.put(minimalSpac(1848507));
+    await candidateRepo.put(candidateRow(1848507, "medium"));
+    await putClassification({
+      cik: 1848507,
+      accession_number: "0001848507-26-000001",
+      filing_date: "2026-01-15",
+      is_spac: false,
+    });
+
+    await expect(listSpacProcessCiks()).resolves.toEqual([1848507]);
+  });
+
+  it("keeps a candidate when a later registration classified is_spac=true", async () => {
+    const candidateRepo = globalServiceRegistry.get(SPAC_CANDIDATE_REPOSITORY_TOKEN);
+    await candidateRepo.put(candidateRow(9001, "medium"));
+    await putClassification({
+      cik: 9001,
+      accession_number: "0000000000-21-000001",
+      filing_date: "2021-01-01",
+      is_spac: false,
+    });
+    await putClassification({
+      cik: 9001,
+      accession_number: "0000000000-21-000002",
+      filing_date: "2021-06-01",
+      is_spac: true,
+    });
+
+    await expect(listSpacProcessCiks()).resolves.toEqual([9001]);
+  });
+
+  it("uses the later filing date, not process order, as latest", async () => {
+    const candidateRepo = globalServiceRegistry.get(SPAC_CANDIDATE_REPOSITORY_TOKEN);
+    await candidateRepo.put(candidateRow(9002, "high"));
+    await putClassification({
+      cik: 9002,
+      accession_number: "0000000000-21-000010",
+      filing_date: "2021-01-01",
+      is_spac: true,
+      created_at: "2026-08-20T00:00:00.000Z",
+    });
+    await putClassification({
+      cik: 9002,
+      accession_number: "0000000000-21-000011",
+      filing_date: "2021-06-01",
+      is_spac: false,
+      created_at: "2026-08-01T00:00:00.000Z",
+    });
+
+    await expect(listSpacProcessCiks()).resolves.toEqual([]);
+  });
 });
 
 async function recordRun(args: {

src/cli/sync/spacSyncCiks.ts

@@ -5,11 +5,17 @@
  */
 
 import { globalServiceRegistry } from "workglow";
+import { S1_CLASSIFICATION_REPOSITORY_TOKEN } from "../../storage/classification/S1ClassificationSchema";
+import { FILING_REPOSITORY_TOKEN } from "../../storage/filing/FilingSchema";
 import {
   SPAC_CANDIDATE_REPOSITORY_TOKEN,
   type SpacCandidateConfidence,
 } from "../../storage/spac/SpacCandidateSchema";
 import { SPAC_REPOSITORY_TOKEN } from "../../storage/spac/SpacSchema";
+import {
+  latestClassifiedAsSpac,
+  type ClassificationVerdict,
+} from "../../task/spac/classifySpacCandidate";
 import { EXTRACTOR_RUN_REPOSITORY_TOKEN } from "../../storage/versioning/ExtractorRunSchema";
 import { SYNC_FORM_DOMAINS } from "./syncFormDomains";
 
@@ -124,9 +130,10 @@ export async function filterSpacCiksByHistory(
   return ciks.filter((cik) => touched.has(cik));
 }
 
-/** Known spac rows ∪ spac_candidate rows with confidence high|medium. */
+/** Known spac rows ∪ high|medium candidates, minus classified-not-SPAC CIKs. */
 export async function listSpacProcessCiks(): Promise<number[]> {
   const known = await listKnownSpacCiks();
+  const knownSet = new Set(known);
   const ciks = new Set<number>(known);
   const candidateRepo = globalServiceRegistry.get(SPAC_CANDIDATE_REPOSITORY_TOKEN);
 
@@ -139,13 +146,66 @@ export async function listSpacProcessCiks(): Promise<number[]> {
       [];
   }
 
+  const unknown = candidates.filter((row) => !knownSet.has(row.cik)).map((row) => row.cik);
+  const rejected = await listCiksLatestClassificationNotSpac(unknown);
+
   for (const row of candidates) {
+    if (rejected.has(row.cik)) continue;
     ciks.add(row.cik);
   }
 
   return [...ciks].sort((a, b) => a - b);
 }
 
+/**
+ * CIKs among `ciks` whose latest parsed registration classified `is_spac=false`.
+ * A CIK with no classification is not rejected — the forms pipeline has not
+ * answered yet.
+ */
+async function listCiksLatestClassificationNotSpac(ciks: readonly number[]): Promise<Set<number>> {
+  const rejected = new Set<number>();
+  if (ciks.length === 0) return rejected;
+
+  const classRepo = globalServiceRegistry.get(S1_CLASSIFICATION_REPOSITORY_TOKEN);
+  const filingRepo = globalServiceRegistry.get(FILING_REPOSITORY_TOKEN);
+  const byCik = new Map<number, ClassificationVerdict[]>();
+  const accessions = new Set<string>();
+  const sorted = [...new Set(ciks)].sort((a, b) => a - b);
+  for (let i = 0; i < sorted.length; i += TOUCHED_CIK_CHUNK) {
+    const chunk = sorted.slice(i, i + TOUCHED_CIK_CHUNK);
+    const rows = (await classRepo.query({ cik: { value: chunk, operator: "in" } })) ?? [];
+    for (const row of rows) {
+      if (row.cik == null) continue;
+      accessions.add(row.accession_number);
+      const list = byCik.get(row.cik) ?? [];
+      list.push({
+        accession_number: row.accession_number,
+        is_spac: row.is_spac,
+        created_at: row.created_at,
+      });
+      byCik.set(row.cik, list);
+    }
+  }
+
+  const filingDateByAccession = new Map<string, string>();
+  const accessionList = [...accessions];
+  for (let i = 0; i < accessionList.length; i += TOUCHED_CIK_CHUNK) {
+    const chunk = accessionList.slice(i, i + TOUCHED_CIK_CHUNK);
+    const filings =
+      (await filingRepo.query({ accession_number: { value: chunk, operator: "in" } })) ?? [];
+    for (const filing of filings) {
+      filingDateByAccession.set(filing.accession_number, filing.filing_date);
+    }
+  }
+
+  for (const [cik, rows] of byCik) {
+    if (latestClassifiedAsSpac(rows, filingDateByAccession) === false) {
+      rejected.add(cik);
+    }
+  }
+  return rejected;
+}
+
 /** CIKs that already have a `spac` row — the 8-K / proxy / 25-15 handlers' gate. */
 export async function listKnownSpacCiks(): Promise<number[]> {
   const spacRepo = globalServiceRegistry.get(SPAC_REPOSITORY_TOKEN);

src/config/storageRegistry.ts

@@ -934,11 +934,14 @@ export const SEC_STORAGE_REGISTRY: readonly StorageDefinition[] = [
     table: "s1_classification",
     schema: S1ClassificationSchema,
     primaryKeyNames: S1ClassificationPrimaryKeyNames,
-    // The SPAC candidate scan groups this table by `cik` and reads only `sic`.
-    // The PK is `(extractor_id, accession_number)`, so nothing else covers it —
+    // The SPAC candidate scan groups this table by `cik` and reads `sic`,
+    // `is_spac`, `created_at` and `accession_number`. The PK is
+    // `(extractor_id, accession_number)`, so nothing else covers that set —
     // and `setupDatabase()` re-emits `CREATE INDEX IF NOT EXISTS` on every run,
-    // so an existing database picks this up without a migration.
-    indexes: [["cik", "sic"]],
+    // so an existing database picks this up without a migration. The previous
+    // `(cik, sic)` index is left standing on databases that already have it;
+    // it is a prefix of this one and is unused by the scan once this exists.
+    indexes: [["cik", "sic", "is_spac", "created_at", "accession_number"]],
   }),
   defineStorage({
     token: CANONICAL_PERSON_REPOSITORY_TOKEN,

src/task/spac/classifySpacCandidate.test.ts

@@ -18,6 +18,7 @@ const facts = (over: Partial<SpacCandidateFacts>): SpacCandidateFacts => ({
   name: null,
   current_sic: null,
   filed_sic_6770: null,
+  classified_as_spac: null,
   first_reg_form: null,
   first_reg_date: null,
   renamed_from: null,
@@ -417,3 +418,69 @@ describe("the as-filed header SIC signal", () => {
     expect(row?.signal_filed_sic_6770).toBeNull();
   });
 });
+
+describe("a parsed registration that is not a SPAC", () => {
+  it("demotes a weak-named lender to low once its S-1 classified is_spac=false", () => {
+    // ASSOCIATES FIRST CAPITAL CORP (CIK 7974): "%capital corp%" plus an S-1
+    // grades medium, but every registration the forms pipeline has read is an
+    // operating company. Process ignores `low`, so this is how it drops off
+    // the worklist without a new confidence enum.
+    const row = classifySpacCandidate(
+      facts({
+        cik: 7974,
+        name: "ASSOCIATES FIRST CAPITAL CORP",
+        current_sic: 6141,
+        first_reg_form: "S-1",
+        first_reg_date: "1996-02-09",
+        classified_as_spac: false,
+      }),
+      AT
+    );
+    expect(row).toMatchObject({ confidence: "low", signal_name_match: false });
+  });
+
+  it("does not demote when the classification has not been asked yet", () => {
+    const row = classifySpacCandidate(
+      facts({
+        cik: 7974,
+        name: "ASSOCIATES FIRST CAPITAL CORP",
+        current_sic: 6141,
+        first_reg_form: "S-1",
+        first_reg_date: "1996-02-09",
+        classified_as_spac: null,
+      }),
+      AT
+    );
+    expect(row?.confidence).toBe("medium");
+  });
+
+  it("does not demote a high SPAC whose latest registration classified is_spac=true", () => {
+    const row = classifySpacCandidate(
+      facts({
+        cik: 2082251,
+        name: "Yuanxiang Acquisition Corp.",
+        current_sic: 6770,
+        first_reg_form: "F-1",
+        first_reg_date: "2025-09-17",
+        classified_as_spac: true,
+      }),
+      AT
+    );
+    expect(row?.confidence).toBe("high");
+  });
+
+  it("caps even a 6770-coded name at low when the latest registration said it is not a SPAC", () => {
+    const row = classifySpacCandidate(
+      facts({
+        cik: 42,
+        name: "Someone Acquisition Corp",
+        current_sic: 6770,
+        first_reg_form: "S-1",
+        first_reg_date: "2021-01-01",
+        classified_as_spac: false,
+      }),
+      AT
+    );
+    expect(row?.confidence).toBe("low");
+  });
+});