# Schema: `chains_chip_v0.3.parquet`

**Version:** v0.3.0
**Companion builder:** `event-chain-builder/scripts/build_chains.py`
**Machine-readable schema:** `schemas/chains_v0.3.schema.json` (authoritative machine contract loaded directly by the builder)
**Inputs:** `companies_chip_subset_entity_v0.3.parquet`,
`funding_events_chip_v0.3_clean_human_v0.2.parquet`,
`exposure_events_chip_v0.3_clean_human_v0.2.parquet`, and
`interface_events_chip_v0.4_clean_human_v0.2_identity_patch_v1.parquet`

## Purpose

Materialize one temporal chain per unique funding-level company outcome. Funding parquet rows are participant rows, so the builder first groups them by `(company_id, event_type, round_name, announce_date)` and creates one chain end for each group. Company labels come directly from `companies_chip_subset_entity_v0.3.parquet`.

## Temporal semantics

- Known-date outcomes are ordered chronologically; ties are deterministically ordered by outcome type and round.
- The first known outcome uses `chain_start_date=founding`. Because founding date is not present in company entity v0.3, this means all dated middle events before the outcome.
- Later known outcomes use the half-open interval `[previous_outcome_date, current_outcome_date)`.
- Undated exposure/interface events cannot be placed temporally and are excluded from every chain. They remain in the source event parquets and are reported as build diagnostics.
- An outcome without `announce_date` has `chain_end_date=unknown`, `chain_window_status=unknown_end_date`, and no middle events. This avoids fabricating a time window or assigning the same remaining middle events to multiple unknown-end outcomes.

## Arrow schema

| # | Column | Arrow type | Nullable | Contract |
|---:|---|---|:---:|---|
| 1 | `chain_id` | `large_string` | No | PK; `chain:<sha1-prefix>` over company/outcome/round/end date |
| 2 | `company_id` | `large_string` | No | FK to chip company entity v0.3 |
| 3 | `company_canonical_name` | `large_string` | No | Display name from entity |
| 4 | `company_label_v4` | `large_string` | No | `SUCCESS`, `FAILURE`, or `AMBIGUOUS` from entity |
| 5 | `company_outcome_label_v4` | `large_string` | No | Detailed outcome label from entity |
| 6 | `chain_sequence` | `int64` | No | 1-based deterministic order within company |
| 7 | `chain_start_date` | `large_string` | No | `YYYY-MM-DD` or `founding` |
| 8 | `chain_start_reason` | `large_string` | No | `founding_or_prehistory` or `previous_outcome` |
| 9 | `chain_end_date` | `large_string` | No | `YYYY-MM-DD` or `unknown` |
| 10 | `chain_window_status` | `large_string` | No | `dated` or `unknown_end_date` |
| 11 | `outcome_type` | `large_string` | No | Funding-level outcome enum |
| 12 | `outcome_round` | `large_string` | Yes | Round designation for funding attempts |
| 13 | `outcome_event_ids` | `list<element: large_string>` | No | Participant-row IDs grouped into this outcome |
| 14 | `n_participant_rows` | `int64` | No | Number of funding participant rows at chain end |
| 15 | `investor_ids` | `list<element: large_string>` | No | Unique matched investor IDs, nulls removed |
| 16 | `investor_raw_names` | `list<element: large_string>` | No | Unique raw participant/acquirer names |
| 17 | `n_exposure` | `int64` | No | Dated exposure events in the chain window |
| 18 | `exposure_event_ids` | `list<element: large_string>` | No | Ordered exposure event IDs |
| 19 | `exposure_types` | `list<element: large_string>` | No | Event types aligned with `exposure_event_ids` |
| 20 | `n_interface` | `int64` | No | Dated interface event-participant rows in the window |
| 21 | `interface_event_ids` | `list<element: large_string>` | No | Ordered interface event IDs |
| 22 | `interface_types` | `list<element: large_string>` | No | Event types aligned with `interface_event_ids` |
| 23 | `schema_version` | `large_string` | No | Constant `v0.3.0` |

Schema metadata records the exact released entity and event input filenames.

## Outcome enum

`funding_round`, `funding_failed`, `funding_withdrawn`, `ipo_filed`, `ipo_completed`, `ipo_withdrawn`, `acquired`, `company_closed`.

## Snapshot limitation

The released snapshot contains 1,342 chains across 663 companies. Of these,
1,071 chains have dated outcome windows. SUCCESS/FAILURE comparisons in the
paper use the fixed 501-company subset with at least one dated, evaluable chain;
they do not represent all 2,547 companies in the chip universe.

The builder refuses to overwrite an existing output unless `--force-output` is supplied.