# Chance Brothers Sync Interface

Experimental partner-preview contract. Not a stable production API, not access-controlled, and not safe for automatic import.

## Endpoints
- `/chance-brothers/export.csv` (csv): Flat manual-review projection of public-safe Chance Brothers payloads; not automatic-import authoritative.
- `/chance-brothers/export.json` (json): Authoritative preview serialization with snapshot, hash, state, and provenance metadata.
- `/chance-brothers/lighthouses.geojson` (geojson): Mapped point overlay for records with coordinates.
- `/chance-brothers/comparison.csv` (csv): Reconciliation report between LUX rows and the latest prepared CHT snapshot.
- `/chance-brothers/comparison.json` (json): Structured reconciliation report; review-only, not an import source.

## Snapshot Metadata
- `generated_at`: `2026-08-09T22:21:23+00:00`
- `archive_version.version`: `v0.24.362-review`
- `archive_version.display_version`: `v0.24.362`
- `extractor.script`: `scripts/build_static_site.py`

## Sync Protocol
- Before manual evaluation, verify source_snapshot_id and source_snapshot_checksum; generated_at and archive_version are build metadata, not snapshot identity.
- If reporting an import issue, include generated_at, archive_version.version, extractor.script, the endpoint path, and the affected lux_asset_id or cht_source_id.
- Use comparison.csv/json to review gaps and possible adoptions after a Chance Heritage Trust import, then record confirmed decisions in the partner overlay.
- When a CHT page appears to have reused LUX data, store the CHT URL as a partner link only; do not promote it to independent source evidence.
- Never infer deletion from absence; record missing_from_latest_snapshot and require a separate reviewed decision.

## Core Concepts
- `heritage_asset`: A first-class LUX object such as a lens, optic, lantern, apparatus, tower, museum object, or related component. It is not always a lighthouse page.
- `lighthouse_or_site`: A host place or navigation site that may contain, display, replace, or historically relate to a Chance Brothers asset.
- `current_host_id`: Reviewed LUX lighthouse/lightship host when known. It may be blank when an asset is known but not yet matched to a host record.
- `current_location`: Source-import or reviewed location used for matching and mapping. Coordinates are not automatically accepted canonical lighthouse coordinates.
- `source_evidence`: The source rows supporting or discovering the asset. Object-level links are useful provenance but not automatically field-level evidence.
- `partner_link`: Manual counterpart/adoption review row for Chance Heritage Trust exchange. It is separate from independent source evidence.

## Export Fields
`exchange_record_id`, `schema_version`, `record_hash`, `lux_id`, `lux_asset_id`, `subject_family`, `subject_subtype`, `partner_id`, `external_record_id`, `external_url`, `partner_record_state`, `preferred_name`, `aliases`, `latitude`, `longitude`, `object_distinction`, `manufacturer`, `review_status`, `publication_state`, `exchange_assertion_state`, `counterpart_state`, `public_lux_url`, `generated_at`, `source_snapshot_id`, `source_snapshot_checksum`, `raw_record_hash`, `collision_cohort_id`, `visibility_mode`, `media_state`, `spatial_eligibility`, `spatial_omission_reason`, `field_provenance_hash`, `field_provenance_json`, `media_json`, `downstream_impact_json`

## Comparison Fields
`comparison_status`, `lux_asset_id`, `lux_title`, `lux_url`, `cht_source_id`, `cht_title`, `cht_url`, `match_method`, `review_action`, `review_note`

## GeoJSON Properties
`exchange_record_id`, `schema_version`, `record_hash`, `lux_id`, `external_record_id`, `partner_record_state`, `preferred_name`, `subject_subtype`, `manufacturer`, `review_status`, `publication_state`, `exchange_assertion_state`, `counterpart_state`, `public_lux_url`, `source_snapshot_id`

## Partner Overlay Fields
`lux_asset_id`, `cht_source_id`, `cht_url`, `match_status`, `adoption_status`, `reviewed_at`, `reviewer_note`

## Agent Rules
- Do not automatically import any partner-preview endpoint into a CMS.
- Use JSON as the reference representation; CSV and GeoJSON are projections of the same rows.
- Use lighthouses.geojson only for mapped points; unmapped assets can still be valid records.
- Do not import comparison.csv/json as facts; it is a reconciliation worklist.
- Blank image fields mean no public-safe image is currently exported.
- Do not treat matched_cht_url as independent evidence when the CHT page may have reused LUX data.
- Keep heritage assets distinct from lighthouse/site pages: a lens or optic may move, survive separately, or lack a confirmed host.

## Model Diagram
```mermaid
flowchart LR
  LUX[LUX heritage_asset\nlens / optic / lantern / tower] --> Export[CSV / JSON export]
  LUX --> GeoJSON[GeoJSON mapped points]
  LUX --> Comparison[Comparison report]
  CHT[CHT snapshot] --> Comparison
  Overlay[partner link overlay\nmanual review] --> Export
  Overlay --> Comparison
  Comparison --> Review[Curator review\nconfirm / reject / adoption signal]
  Review --> Overlay
```