# 02_event_alignment — WTF dump (children docs aligned by event)

This pack aligns **children docs** by a cross-cluster **event matching key** and produces:
- **Per-event stats** ranked by **how many clusters share the event** (computed; not using any stored cluster_count).
- A **full occurrences table** (one row per doc) with “visual matching” columns (metadata + signature ranges/times).
- Summary exports that compare **MCRO vs non‑MCRO** participation.

## What is the “event matching key”?

Children docs include `cluster_event_key`, usually shaped like:

`cluster:1570|2024-12-27|notice-of-motion-and-motion`

To match events **across clusters**, we strip off the `cluster:<id>|` prefix and use:

`event_match_key = 2024-12-27|notice-of-motion-and-motion`

This gives a stable grouping key: **event date + event kind**.

> If `cluster_event_key` is missing, the pack falls back to:
> `cluster:<cluster_id>|<case_event.date>|<doc_type>`
> then applies the same stripping logic.

## MCRO flag

`is_mcro_case_flag` is derived from `children.case_set` containing `'MCRO'`.  
This is used as a “frozen set” membership indicator.

## Outputs (CSV)

### 1) MCRO vs non‑MCRO overview
`02_event_alignment__mcro_vs_non_overview.csv`  
High-level counts of docs/cases/clusters with event dates, split by MCRO membership.

### 2) Cluster-count distribution
`02_event_alignment__cluster_count_distribution.csv`  
How many event keys are shared by N clusters.

### 3) Event stats (ranked by clusters found)
`02_event_alignment__stats.csv`  
Key columns:
- `n_clusters`, `n_docs`, `n_cases`
- MCRO vs non split columns (`n_docs_mcro`, etc.)
- `first_filing_date`, `last_filing_date`, `filing_span_days`
- size/page ranges

### 4) Full occurrences dump
`02_event_alignment__occurrences.csv`  
One row per doc, with:
- case + cluster identifiers
- event date/name/index
- filenames + doc_sha256
- XMP fields (`document_id`, `instance_id`, create/metadata dates, author/creator/title)
- PDF signature columns (sig1..sig6 names, times, signed_ranges)
- **Watermark columns** (`watermark_sig_index`, `watermark_sign_time`, `watermark_signed_ranges`) as validation signals.

## How to run (DuckDB CLI)

```sql
.read duckdb/sql/core/bootstrap.sql
.read duckdb/sql/core/starter_views__v3_provenance.sql

.read duckdb/sql/topics/02_cluster_alignment/02_event_alignment__views.sql
.read duckdb/sql/topics/02_cluster_alignment/02_event_alignment__exports.sql
```

Ensure this directory exists before export:
`./reports/02_cluster_alignment/`