Skip to content

Commit b561fcd

Browse files
Sam-BollingSam-Bolling
committed
docs(usgs-eq): add total bootstrap data model pack
1 parent c1c1c52 commit b561fcd

29 files changed

Lines changed: 1721 additions & 0 deletions

‎docs/research/USGS_EQ_Total_Bootstrap_Data_Model_Enrichment_Pack_2026-03-12.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# USGS Earthquake Total Bootstrap, Data Model, and Enrichment Pack
2+
3+
**Date:** 2026-03-12
4+
**Author:** Codex
5+
**Status:** Created, packaged, and intended for repository handoff
6+
**Scope:** `publishers/usgs_eq` total package including bootstrap guidance, data-model review, metadata enrichment, and zip artifact
7+
8+
---
9+
10+
## 1. Executive Summary
11+
12+
A new comprehensive USGS earthquake package was created under:
13+
14+
- `publishers/usgs_eq/total_bootstrap_data_model_enrichment_pack`
15+
16+
This package is broader than a metadata-only pack. It includes:
17+
18+
- a reviewed Pattern C resource-model description
19+
- live-source verification against current official USGS earthquake feeds and docs
20+
- metadata sidecars and worked examples
21+
- bootstrap patch candidates for richer procedure, system, datastream, and deployment metadata
22+
- a shareable zip artifact of the full package
23+
24+
The package is designed to keep the current feed-adapter architecture while
25+
materially improving provenance, semantic clarity, and future maintainability.
26+
27+
---
28+
29+
## 2. Why a Larger Package Was Justified
30+
31+
The USGS earthquake publisher is already stronger than a rough prototype. It already has:
32+
33+
- one normalization procedure
34+
- one global feed-adapter system
35+
- one earthquake-events datastream
36+
- a coherent deployment tree
37+
- a working runtime using the official USGS GeoJSON summary feed
38+
39+
So the right move was not to redesign it. The right move was to package the
40+
current implementation properly:
41+
42+
- make the Pattern C model explicit
43+
- anchor the bootstrap to current live USGS semantics
44+
- identify which metadata enrichments are safe now
45+
- record where richer detail-feed or FDSN enrichment belongs later
46+
47+
---
48+
49+
## 3. Live Research Findings That Matter
50+
51+
The package was informed by live verification on 2026-03-12 against the current
52+
USGS earthquake feed surface.
53+
54+
The most important findings were:
55+
56+
1. `all_day.geojson` is live and currently reports 287 events.
57+
2. `significant_month.geojson` is live and currently reports 11 events.
58+
3. Summary features already expose more fields than the current result contract uses.
59+
4. Per-event `detail` documents expose richer `products` trees and related resource URLs.
60+
5. The FDSN `query.geojson` endpoint aligns with the detail-feed surface for targeted retrieval.
61+
6. The official feed lifecycle policy offers stable production-feed guarantees and deprecation notice.
62+
63+
The most important modeling conclusion is this:
64+
65+
The current publisher should remain a summary-feed-driven Pattern C adapter. The
66+
detail feed and FDSN event service should be treated as documented enrichment
67+
companions, not as mandatory default polling surfaces.
68+
69+
---
70+
71+
## 4. Package Contents
72+
73+
### 4.1 Notes
74+
75+
The `notes/` section contains:
76+
77+
- live source verification
78+
- audit and recommendations
79+
- apply order
80+
- runtime and model follow-on guidance
81+
82+
### 4.2 Data model
83+
84+
The `data_model/` section contains:
85+
86+
- a resource-model walkthrough
87+
- machine-readable inventory
88+
- current observation-contract documentation
89+
- upstream-to-CSAPI field mapping
90+
91+
### 4.3 Metadata and examples
92+
93+
The `metadata/` section contains:
94+
95+
- official source URLs
96+
- live feed metadata snapshots
97+
- a summary-feature example
98+
- a detail-event example
99+
- a detail-versus-FDSN alignment snapshot
100+
- feed-variant and field-term semantics
101+
102+
### 4.4 Assets
103+
104+
The `assets/` section contains:
105+
106+
- a generic local earthquake icon SVG
107+
- a note explaining why no single official source image was bundled
108+
109+
### 4.5 Bootstrap patch candidates
110+
111+
The `patches/` section contains:
112+
113+
- constants and helper URLs
114+
- enriched procedure metadata candidates
115+
- enriched system metadata candidates
116+
- enriched datastream semantics
117+
- enriched deployment metadata
118+
- a config recommendation snapshot
119+
- a compact candidate snippet summary
120+
121+
---
122+
123+
## 5. Design Position
124+
125+
This package makes a deliberate distinction between:
126+
127+
- what should be changed now
128+
- what should be documented now but implemented later
129+
130+
### Recommended now
131+
132+
- richer official-source references
133+
- explicit summary/detail/FDSN source layering
134+
- richer datastream semantics and omitted-field documentation
135+
- lifecycle-policy documentation
136+
- explicit feed-variant guidance
137+
138+
### Recommended later
139+
140+
- optional result-body expansion for `sig`, `tsunami`, `alert`, `net`, and `url`
141+
- selective detail-feed enrichment for significant or revised events
142+
- stronger null-handling for missing magnitude
143+
- persistent dedupe state if restart replay becomes a concern
144+
145+
This keeps the package robust without forcing unnecessary runtime churn.
146+
147+
---
148+
149+
## 6. Bottom Line
150+
151+
The new USGS earthquake package is not just a metadata patch. It is a reviewed
152+
handoff bundle for the current publisher:
153+
154+
- architecture clarified
155+
- live upstream semantics verified
156+
- enrichment candidates prepared
157+
- zip artifact produced for transport and review
158+
159+
That is the right level of packaging for a publisher that is already functional
160+
and now needs to become more explicit, more authoritative, and easier to extend.

‎publishers/usgs_eq/total_bootstrap_data_model_enrichment_pack/README.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# USGS Earthquake Total Bootstrap, Data Model, and Enrichment Pack
2+
3+
This package is a comprehensive handoff bundle for the current
4+
`publishers/usgs_eq` publisher in `OSHConnect-Python`.
5+
6+
It is broader than a metadata-only enrichment pack. It includes:
7+
8+
- a reviewed Pattern C feed-adapter data-model section
9+
- live-source verification notes against current official USGS earthquake feeds
10+
- metadata sidecars and worked examples
11+
- ready-to-apply bootstrap snippet candidates
12+
- a package manifest suitable for zipping and external sharing
13+
14+
The package was assembled after cross-referencing:
15+
16+
- the current local `bootstrap_usgs_eq.py`
17+
- the current local `usgs_eq_publisher.py`
18+
- the current local `config.json`
19+
- the current local USGS API reconnaissance notes
20+
- the current follow-on publishers plan
21+
- live USGS earthquake feed, detail, lifecycle, and FDSN resources verified on 2026-03-12
22+
23+
## Scope
24+
25+
This package is designed to improve and document the USGS earthquake publisher
26+
without forcing risky runtime or architecture changes into the current codepath.
27+
28+
It does three things:
29+
30+
1. documents the current Pattern C feed-adapter model
31+
2. provides a richer metadata-enrichment layer for earthquake procedure,
32+
system, datastream, and deployment resources
33+
3. captures the highest-value follow-on runtime and model recommendations
34+
35+
## Why this package exists
36+
37+
The current USGS earthquake publisher already has a coherent architecture:
38+
39+
- one shared earthquake normalization procedure
40+
- one global feed-adapter system
41+
- one earthquake-events datastream
42+
- one simple deployment tree
43+
- one working publisher that emits one observation per earthquake event
44+
45+
That baseline is sound. The main value of this package is to make the current
46+
design more explicit, more authoritative, and easier to extend safely.
47+
48+
The most important findings from live verification are:
49+
50+
- the `all_day` summary feed is live and currently reports 287 events
51+
- the `significant_month` summary feed is live and currently reports 11 events
52+
- each summary feature includes a per-event `detail` link
53+
- the detail feed adds a `products` structure with contributor-specific
54+
resources such as `origin`, `phase-data`, `nearby-cities`, and `scitech-link`
55+
- the FDSN `query.geojson` service exposes the same richer event surface and is
56+
best treated as a companion or future backfill source, not a required
57+
replacement for the summary feed
58+
- the feed lifecycle policy states production feeds are available for at least
59+
six months and receive at least 30 days notice before deprecation
60+
61+
## Package layout
62+
63+
- `bundle_manifest.json`
64+
- `notes/`
65+
- `data_model/`
66+
- `metadata/`
67+
- `assets/`
68+
- `patches/`
69+
70+
## Recommended reading order
71+
72+
1. `notes/LIVE_SOURCE_VERIFICATION_2026-03-12.md`
73+
2. `notes/AUDIT_AND_RECOMMENDATIONS.md`
74+
3. `data_model/RESOURCE_MODEL.md`
75+
4. `metadata/source_urls.json`
76+
5. `patches/bootstrap_usgs_eq_metadata_enriched_candidate_snippets.py`
77+
78+
## Implementation stance
79+
80+
This pack is conservative where the current runtime is already correct and
81+
explicit where the current metadata and data-model story are still thin.
82+
83+
It does not assume every possible enrichment should be applied immediately. In particular:
84+
85+
- metadata enrichment is recommended now
86+
- richer datastream semantics and official-source provenance are recommended now
87+
- detail-feed and FDSN-event-service alignment are documented now
88+
- summary-feed polling remains the recommended default runtime path
89+
- selective detail enrichment for significant or revised events is optional
90+
91+
## Important architecture notes
92+
93+
This pack keeps the current Pattern C model:
94+
95+
- no system-per-earthquake expansion
96+
- no per-event bootstrap resources
97+
- no requirement to poll the detail feed on every cycle
98+
99+
That means the richest enrichment targets are:
100+
101+
- the earthquake normalization procedure
102+
- the feed-adapter system metadata
103+
- the earthquake datastream schema and documentation
104+
- the deployment metadata and feed-variant documentation
105+
106+
It also means the package explicitly documents the current omission of several
107+
available upstream fields such as `sig`, `tsunami`, `alert`, `net`, `url`, and
108+
detail `products`, so future extensions can be made intentionally rather than
109+
accidentally.

‎publishers/usgs_eq/total_bootstrap_data_model_enrichment_pack/assets/official_image_reference.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
No official static representative earthquake image is bundled in this package.
2+
3+
Reason:
4+
5+
- the publisher models a global real-time event feed rather than one durable physical asset
6+
- event-specific maps and pages are generated per earthquake
7+
- a generic local icon is more appropriate for this package than a single official source image

‎publishers/usgs_eq/total_bootstrap_data_model_enrichment_pack/assets/usgs_eq_generic.svg‎

Lines changed: 8 additions & 0 deletions
Loading

‎publishers/usgs_eq/total_bootstrap_data_model_enrichment_pack/bundle_manifest.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "USGS Earthquake Total Bootstrap, Data Model, and Enrichment Pack",
3+
"packageVersion": "2026-03-12",
4+
"publisherPath": "publishers/usgs_eq",
5+
"generatedDate": "2026-03-12",
6+
"purpose": [
7+
"Document the current USGS earthquake publisher architecture",
8+
"Provide live-verified source references and worked examples",
9+
"Deliver a metadata enrichment pack for earthquake bootstrap resources",
10+
"Package the result as a shareable zip artifact"
11+
],
12+
"artifactGroups": [
13+
"notes",
14+
"data_model",
15+
"metadata",
16+
"assets",
17+
"patches"
18+
],
19+
"upstreamVerifiedOn": "2026-03-12",
20+
"currentLocalInputs": [
21+
"publishers/usgs_eq/bootstrap_usgs_eq.py",
22+
"publishers/usgs_eq/usgs_eq_publisher.py",
23+
"publishers/usgs_eq/config.json",
24+
"docs/research/USGS_API_Reconnaissance_Notes.md",
25+
"docs/research/USGS_NIMS_Follow_On_Publishers_Plan.md"
26+
],
27+
"notes": [
28+
"This package is Pattern C specific and assumes one global feed-adapter system with one earthquake-events datastream.",
29+
"Live verification confirms the summary feed, detail feed, lifecycle policy, and FDSN event service remain aligned with the current publisher model.",
30+
"The zip archive for this package is created as a sibling artifact under publishers/usgs_eq."
31+
]
32+
}

0 commit comments

Comments
 (0)