postcrime-heuristics — application documentation

Audience: architect (project owner). This is a product/architecture tour, not API docs.

What this is

postcrime-heuristics is a generalized, post-hoc fingerprinting framework for automated detection of anomalous corporate activity in the SEC EDGAR database — a precrime-oriented scoring methodology applied retrospectively. It crawls DOJ + SEC enforcement output and EDGAR filings, normalises them into a corpus, and runs a fleet of regex- and LLM-backed enrichment workflows to surface independent signals (structural EDGAR metadata, individual legal histories, market dynamics) associated with shell-company / boiler-room / pump-and-dump activity. Effectiveness is measured by the interval between when signals emerge and the eventual enforcement action (SEC/DOJ press release, complaint, indictment), accounting for the typical 6–12 month investigation lag.

Two things to keep separate:

1. The crawler corpus (crawler/ + processor/ + corpus.db) — DOJ-SDNY press, SEC press releases, SEC litigation releases. This is "what cops + regulators already prosecuted." Driven by fraud-publisher → fraud.rows → fraud-enricher-v2.
2. The EDGAR fingerprint corpus (edgar-fraud-scan on node-eighteen, output at /mnt/oink/docker/edgar-fraud-scan/data/flagged/*.ndjson) — every issuer that has ever filed with the SEC, scored against a library of rule-based fingerprints (filing-agent template, Reg S, promissory notes, opinion letters).

Specific networks (e.g. the Cane Clark LLP ecosystem) are illustrative validation examples, not the system's scope. The corpus store is corpus.db (SQLite, proxied through fraud-db-broker); the forward-canonical store is ParadeDB at 192.168.1.181:5432/postcrimedb, postcrime schema — migration in progress.

Where things live

How postcrime-heuristics fits into the rest of tankbottoms.eth's stack

edgar-cik-cli ──┐
                ├──▶ edgar-fraud-scan (node-eighteen)
EDGAR full-text ┘        │
                         ▼
                   flagged/*.ndjson  ──┐
                                       │
       DOJ + SEC crawler ──▶ corpus.db ┼──▶ postcrime-heuristics
                                       │     (this repo)
                                       │       │
                                       │       ├── search-ui  (postcrime.atsignhandle.xyz)
                                       │       ├── stats-miner (D3 panels)
                                       │       └── fraud-enricher-v2 → gpumon-ingress LLMs
                                       │
                                       └──▶ ciks-banana
                                              (curated 672-entity Cane viewer)

• Inputs: EDGAR via edgar-cik-cli, DOJ/SEC press via this repo's crawler/.
• LLM calls: all routed through gpumon-ingress at http://gpumon-ingress:4001 (swarm overlay) or http://192.168.1.211:4010 (LAN). No direct Ollama / vLLM calls.
• Downstream consumer: ciks-banana joins curated entity rosters against corpus.db + the EDGAR fingerprint NDJSONs to render the Cane network site.

Read this in order

1. architecture.md — services + the new queue-driven data flow.
2. data-shape.md — corpus.db schema, the workflow_runs state machine, queue envelopes.
3. heuristics.md — what each fingerprint signal actually detects.
4. enrichment.md — LLM passes (fraud-enricher-v2 workflows).
5. frontend.md — what the search-ui currently shows, plus a goals scaffold for tankbottoms.eth to fill in.
6. investigation-workflow.md — example investigation workflow (Cane Clark network as validation case) — concrete commands.
7. roadmap.md — done / in-flight / open.

TL;DR status (2026-05-19)

• Waves 5 + 6 of the federation-queue migration landed: fraud-publisher and fraud-enricher-v2 are deployed on node-eighteen, dual-tailing the legacy stack-enrich-* services.
• workflow_runs gating table added today (broker/src/migrations/2026-05-19-workflow-runs.sql).
• The case-facts workflow is the cutover-validation pilot; format-title + title-llm + link-references + refetch-pdf + scheme-classify followed once schema gates cleared.
• _overnight-questions.md has 13 open questions, several of which are docs / decision-pending, not engineering work — surface those before starting new code.
• The flagged NDJSONs on node-eighteen were last refreshed 2026-05-12 (1 week stale). The next refresh is gated on the EDGAR pull schedule, not this repo.

GAP: no application-layer doc previously existed. This folder is the first pass.