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-23T06:52:29+00:00
`archive_version.version`	v0.24.456-review
`archive_version.display_version`	v0.24.456
`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 public comparison.csv/json only as a public-safe compatibility worklist; generate the private full-inventory package before reporting complete partner gaps.
Share a full-inventory package intentionally and validate any returned acknowledgement against its package and stable gap IDs.
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.

Full review versus public compatibility

A complete bidirectional gap report uses the intentionally generated private review package. The public comparison endpoints contain a public-safe subset and must not be quoted as the complete gap between LUX and CHT.

Population	Delivery	Full gap claims
`partner_review_full_inventory`	intentionally generated private review package	Yes, review evidence only
`public_safe_compatibility_subset`	/chance-brothers/comparison.json and .csv	No

Private package command: run scripts/chance_partner_reconciliation.py with generate. The complete reproducible command is in the agent JSON and Markdown contracts.

Optional improvements Chance may adopt

Entirely voluntary. The current map export remains usable and none of these capabilities is required for the present exchange. They would only make later identity and change comparisons easier and more precise.

Capability	Suggestion	Why it helps
`stable_record_id`	Persistent record ID	Keeps identity stable when a title or URL slug changes.
`modified_at`	Record modified timestamp	Makes incremental comparison and changed-row review more precise.
`revision_or_content_hash`	Revision or content hash	Lets both sides prove which record version was compared.
`structured_full_record_export`	Structured full-record export	Reduces page-by-page fetching when comparing claims and evidence.
`record_lifecycle_state`	Redirected, superseded, or removed state	Distinguishes a deliberate lifecycle change from a temporary absence.

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	Public-safe compatibility comparison; review-only, not an import source or full-inventory gap report.
`/chance-brothers/sync/extractions/`	html+json	Selectable historical map extractions, snapshot deltas, and curated notes/gap packages.

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`