Chance Brothers sync interface

Interface Guide

Experimental technical partner preview. This is not a stable production API, is not safe for automatic import, and is not access-controlled. It documents manual comparison and review of LUX Light Archive Chance Brothers data. LUX stores lighthouses and sites, but also lenses, optics, lanterns, towers, museum objects, and other heritage assets that may move or survive separately.

Snapshot protocol

The exchange files describe a dated generated snapshot. Use this section when comparing imports across time or reporting a parser/import bug.

Metadata	Value
`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

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.

Model

Mermaid source for agents

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

Endpoints

Path	Format	Use
`/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.

Core concepts

Concept	Meaning
`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.

Fields

Use the JSON and Markdown contracts for machine import. These field lists are collapsed here so the human guide stays readable.

CSV / JSON export 35 fields

CSV / JSON export
`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 10 fields

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

GeoJSON properties 15 fields

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 7 fields

Partner overlay
`lux_asset_id`
`cht_source_id`
`cht_url`
`match_status`
`adoption_status`
`reviewed_at`
`reviewer_note`