Answers spec v1.2, example asks with an overlap gate, host and time checks

.github/workflows/ci.yml

@@ -18,9 +18,11 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - run: pip install "httpx==0.28.1" "duckdb==1.5.4"
-      - name: schema check (every record)
+      - run: pip install "httpx==0.28.1" "duckdb==1.5.4" "pytest==9.1.1"
+      - name: schema check (every record + every answers/ file; no live fetch)
         run: python -m sourcetool check
+      - name: answers rules (schema, the sample check, build merge; offline)
+        run: python -m pytest tests/test_answers.py -q
       - name: probe sources changed in this PR (fail on regressions only)
         if: github.event_name == 'pull_request'
         run: |

README.md

@@ -28,6 +28,7 @@ python3 -m venv .venv && .venv/bin/pip install httpx duckdb
 .venv/bin/python -m sourcetool build          # build/library.duckdb (+ search index)
 .venv/bin/python -m sourcetool lookup "tides for Charleston Harbor today"
 .venv/bin/python -m sourcetool coverage       # sources per subcategory, empty ones listed
+.venv/bin/python -m sourcetool answers-check  # fetch each answers/ sample and verify its paths (live)
 ```
 
 | Path | What |
@@ -37,6 +38,7 @@ python3 -m venv .venv && .venv/bin/pip install httpx duckdb
 | `sources/harvested/` | records harvested from open catalogs (labelled, ranked lower) |
 | `sources/suggested/` | users' suggestions, written by `sourcetool ingest` |
 | `providers/` | provider records |
+| `answers/` | which response paths answer which questions, per curated source (merged into records by `build`) |
 | `resolvers/` | lists that turn words into parameters (status pages, stations…) |
 | `sourcetool/` | the tool |
 | `service/` | the Library API the app submits votes and suggestions to ([README](service/README.md)) |

answers/_skipped.md

@@ -0,0 +1,16 @@
+# Sources without answers
+
+One line per source: id — why no answers file was written.
+
+- nyt-sports — the feed answers HTTP 200 with zero items (2026-09-28); nothing to verify a list answer against.
+- politifact — the feed starts with blank lines before `<?xml`; the app's feed parser refuses it ("XML or text declaration not at start of entity"), so no card can read it until the parser strips leading whitespace.
+- powerball-home — an html page (the jackpot, cash value and next draw are page text); the page door reads it, and its readings are in the record's examples.
+
+## Held back (records not published)
+
+One line per record the 2026-09-29 round wanted but did not publish: id — why.
+
+- subreddit-top-rss — reddit.com robots.txt disallows every path for every agent (`Disallow: /`); a hard refusal excludes the source.
+- aws-health-currentevents — the AWS site terms bar robots and data mining, and the Health Dashboard documents no public API; terms unclear, not published.
+- megamillions-home — the jackpot is filled by script from a POST service (no readable page text), and the site publishes no terms of use to check; Mega Millions numbers come from data.ny.gov (ny-lottery-megamillions) instead.
+- thesportsdb-league-round — a round's results for one team need an any-of row filter (home OR away team), which answers spec v1.2 does not have; waits on that schema.

answers/abc-top.json

@@ -0,0 +1,34 @@
+{
+ "source_id": "abc-top",
+ "answers": [
+  {
+   "name": "latest",
+   "label": "Headlines",
+   "kind": "list",
+   "primary": true,
+   "words": [
+    "headlines",
+    "news",
+    "breaking",
+    "top stories",
+    "latest"
+   ],
+   "path": "items",
+   "row": [
+    {
+     "path": "title",
+     "label": "Title",
+     "type": "text"
+    },
+    {
+     "path": "published",
+     "label": "Published",
+     "type": "time"
+    }
+   ],
+   "may_be_empty": false
+  }
+ ],
+ "sample_url": "https://abcnews.go.com/abcnews/topstories",
+ "checked": "2026-09-28"
+}

answers/adsblol-callsign.json

@@ -0,0 +1,66 @@
+{
+  "source_id": "adsblol-callsign",
+  "answers": [
+    {
+      "name": "aircraft",
+      "label": "Flight position",
+      "words": [
+        "where",
+        "position",
+        "track",
+        "flight",
+        "altitude",
+        "speed",
+        "location",
+        "map",
+        "latitude",
+        "longitude"
+      ],
+      "primary": true,
+      "kind": "list",
+      "path": "ac",
+      "row": [
+        {
+          "path": "alt_baro",
+          "label": "Altitude",
+          "type": "number",
+          "unit": "ft"
+        },
+        {
+          "path": "gs",
+          "label": "Ground speed",
+          "type": "number",
+          "unit": "kt"
+        },
+        {
+          "path": "lat",
+          "label": "Latitude",
+          "type": "number"
+        },
+        {
+          "path": "lon",
+          "label": "Longitude",
+          "type": "number"
+        }
+      ],
+      "may_be_empty": true
+    },
+    {
+      "name": "updated",
+      "label": "Last update",
+      "words": [
+        "updated",
+        "last seen",
+        "when",
+        "time"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "now",
+      "type": "time",
+      "window": "now"
+    }
+  ],
+  "sample_url": "https://api.adsb.lol/v2/callsign/DAL1234",
+  "checked": "2026-09-28"
+}

answers/amtraker-trains.json

@@ -0,0 +1,132 @@
+{
+  "source_id": "amtraker-trains",
+  "answers": [
+    {
+      "name": "stops",
+      "label": "Stops: scheduled vs actual",
+      "words": [
+        "late",
+        "on time",
+        "delayed",
+        "running late",
+        "arrival",
+        "eta",
+        "when",
+        "schedule",
+        "stops",
+        "stations"
+      ],
+      "primary": true,
+      "kind": "list",
+      "path": "{train}[0].stations",
+      "row": [
+        {
+          "path": "name",
+          "label": "Station",
+          "type": "text"
+        },
+        {
+          "path": "schArr",
+          "label": "Scheduled",
+          "type": "time"
+        },
+        {
+          "path": "arr",
+          "label": "Actual / expected",
+          "type": "time"
+        },
+        {
+          "path": "status",
+          "label": "Status",
+          "type": "text"
+        }
+      ],
+      "axis": {
+        "cell": "schArr",
+        "step": "hour"
+      }
+    },
+    {
+      "name": "route",
+      "label": "Route",
+      "words": [
+        "route",
+        "which train",
+        "name",
+        "line"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "{train}[0].routeName",
+      "type": "text",
+      "window": "now"
+    },
+    {
+      "name": "next_station",
+      "label": "Next / current station",
+      "words": [
+        "where",
+        "next stop",
+        "next station",
+        "location",
+        "now"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "{train}[0].eventName",
+      "type": "text",
+      "window": "latest"
+    },
+    {
+      "name": "state",
+      "label": "Train state",
+      "words": [
+        "status",
+        "running",
+        "active",
+        "departed",
+        "completed",
+        "state"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "{train}[0].trainState",
+      "type": "text",
+      "window": "now"
+    },
+    {
+      "name": "speed",
+      "label": "Speed",
+      "words": [
+        "speed",
+        "how fast",
+        "moving",
+        "velocity",
+        "mph"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "{train}[0].velocity",
+      "type": "number",
+      "unit": "mph",
+      "window": "now"
+    },
+    {
+      "name": "updated",
+      "label": "Last position update",
+      "words": [
+        "updated",
+        "last update",
+        "as of",
+        "last seen"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "{train}[0].lastValTS",
+      "type": "time",
+      "window": "now"
+    }
+  ],
+  "sample_url": "https://api-v3.amtraker.com/v3/trains/5",
+  "checked": "2026-09-28"
+}

answers/apple-top-albums.json

@@ -0,0 +1,73 @@
+{
+  "source_id": "apple-top-albums",
+  "answers": [
+    {
+      "name": "chart",
+      "label": "Top albums",
+      "words": [
+        "top albums",
+        "albums",
+        "music",
+        "top",
+        "chart",
+        "charts",
+        "most popular",
+        "top 25",
+        "best"
+      ],
+      "primary": true,
+      "kind": "list",
+      "path": "feed.results",
+      "row": [
+        {
+          "path": "name",
+          "label": "Album",
+          "type": "text"
+        },
+        {
+          "path": "artistName",
+          "label": "Artist",
+          "type": "text"
+        },
+        {
+          "path": "releaseDate",
+          "label": "Released",
+          "type": "date"
+        }
+      ]
+    },
+    {
+      "name": "number_one",
+      "label": "Number one",
+      "words": [
+        "number one",
+        "#1",
+        "top one",
+        "no. 1",
+        "at the top",
+        "first place"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "feed.results[0].name",
+      "type": "text",
+      "window": "latest"
+    },
+    {
+      "name": "number_one_by",
+      "label": "Number one artist",
+      "words": [
+        "who is number one",
+        "#1 by",
+        "top artist"
+      ],
+      "primary": false,
+      "kind": "value",
+      "path": "feed.results[0].artistName",
+      "type": "text",
+      "window": "latest"
+    }
+  ],
+  "sample_url": "https://rss.marketingtools.apple.com/api/v2/us/music/most-played/25/albums.json",
+  "checked": "2026-09-28"
+}