Skip to content

The operator's view: one preflight for every provider, the ledger in a table, and the freshness a browser shelf can claim (#144 Phase 4) - #153

Merged
holden merged 2 commits into
mainfrom
claude/phase-4-operators-view-823045
Sep 22, 2026
Merged

holden merged 2 commits into
mainfrom
claude/phase-4-operators-view-823045

Conversation

@holden

@holden holden commented Sep 22, 2026

Copy link
Copy Markdown
Member

Closes #144.

Phase 4, the last one: the operator's view. mix dd.discovery.check walks the
registry instead of naming CineGraph, mix dd.discovery.status is new, /ops/discovery
renders both, and the discovery README gains the section that says what this issue made
true. With it, the six acceptance boxes are all true or accounted for, so the issue closes.

What changed

File What
lib/devils_dictionary/discovery/status.ex new. preflight/0 (registry, enabled?/0, stanza, endpoints, policy, credential presence) and rows/0 (runs, failures, last success, results held, display roots and stale roots, retention due, budget used in this source's window, provider-wide backoff). The one implementation the two tasks and the page render
lib/mix/tasks/dd.discovery.check.ex rewritten: every registered provider, none named. Providers.validate!/0 is called rather than re-implemented, and first — a module that does not export enabled?/0 used to raise UndefinedFunctionError from inside the preflight
lib/mix/tasks/dd.discovery.status.ex new
lib/devils_dictionary_web/live/discovery_live.ex new /ops/discovery: the ledger table, the preflight table, four stats and the two commands. A sibling of /ops/imports, not a section of it — that page is the corpus, this one the culture shelves, and they share an eyebrow and nothing else
config/runtime.exs the credential list is named provider_credential_env, and :provider_credentials publishes one boolean per admitted name. That scope is the only one holding both the exported environment and the development .env, so it is the only one that can answer present honestly — and the only thing that leaves it is the boolean
router.ex, layouts.ex, ops.ex the route, the footer link in dev and test, and one moduledoc that said "the two consoles"
culture.ex one line: a browser shelf now says Fetched by your browser on this visit; nothing is stored here. (acceptance 4, below)
docs/discovery/README.md, adding-a-provider.md, README.md the operator's view section, promise row 6, the "useful tasks" block that documented the old CineGraph exit, the two conventions a new provider needs, the quick reference and the task list

Provider-agnostic, and asserted: three tests register a fake provider and find its row —
in Status, in each task, and on the page. Two conventions the twelve already follow do the
work: a stanza is the slug with hyphens as underscores, and a credential is an
allowed_provider_env name starting with the slug's shell-safe prefix — the same env_prefix
runtime.exs already derives policy variables with. Names no provider claims are printed as
unclaimed rather than dropped, which is what ARTSY_CLIENT_ID and ARTSY_CLIENT_SECRET are.

Never a key: dd_discovery_check_test.exs configures a distinctive value for every keyed
provider and greps the task's whole output for each one; the status task's suite and the page's
do the same. Endpoints are printed — they are in config.exs in the open — after the check
that they carry no userinfo, query or fragment.

The six acceptance boxes

# Box True? Evidence
1 A twelfth provider touches its own files and allowed_provider_env, nothing else ✅ The Guardian (#142) and Spotify (#143), and the followup in a04530a that brought both onto Provider.Helpers
2 grep -c 'defp word_pattern' …providers/*.ex returns 0 ✅ 0 across all twelve, run below
3 A source with retention_seconds: 86_400 holds nothing older than a day, including source_records ✅ retention_test.exs (25 h under a short policy takes the result and its source record; the same age under the default keeps both), plus the Guardian's 23 h hold. 65 tests, 0 failures
4 Every shelf on /define/war says when it was fetched or since when it is held ✅ after one line in this PR Six shelves said it since Phase 2; the GIFs shelf said nothing, because a browser shelf has no display root to read. It now says Fetched by your browser on this visit; nothing is stored here. Measured on /define/war: culture-freshness-{film,artwork,image,text,news,music} and culture-freshness-gif-giphy
5 mix dd.discovery.status runs on a keyless checkout and prints a row per provider ✅ Below: 12 rows with the .env moved aside, exit 0
6 Artsy is a corpus, GIPHY is a browser provider through the row, and nothing registered can neither run nor render ✅ conformance_coverage_test.exs, every registered provider can either run or render — there is no third state

mix dd.discovery.check

Keyed:

PROVIDERS (12 registered)
  provider      kind     ready   switch  policy  endpoints
  bing-news     server   yes     on      ok      https://www.bing.com/news/search
  cinegraph     server   yes     on      ok      https://cinegraph.org/api/graphql
  commons       server   yes     on      ok      https://commons.wikimedia.org/w/api.php
  giphy         browser  yes     on      ok      https://api.giphy.com/v1/gifs/search
  guardian      server   yes     on      ok      https://content.guardianapis.com/search
  met           server   yes     on      ok      —
  open-library  server   yes     on      ok      https://openlibrary.org
  openverse     server   yes     on      ok      https://api.openverse.org/v1/images/
  pexels        server   yes     on      ok      https://api.pexels.com/v1/search
  poetrydb      server   yes     on      ok      https://poetrydb.org
  spotify       server   yes     on      ok      https://api.spotify.com/v1/search  https://accounts.spotify.com/api/token
  unsplash      server   yes     on      ok      https://api.unsplash.com/search/photos

CREDENTIALS (names only — no value is read to print this)
  missing is a name this environment does not set. Whether that matters is the provider's answer above, not this line's: a switch left unset is its default.
  bing-news     BING_NEWS_ENABLED missing
  cinegraph     CINEGRAPH_API_KEY present · CINEGRAPH_GRAPHQL_URL present
  giphy         GIPHY_API_KEY present
  guardian      GUARDIAN_API_KEY present
  pexels        PEXELS_API_KEY present
  spotify       SPOTIFY_CLIENT_ID present · SPOTIFY_CLIENT_SECRET present · SPOTIFY_ENABLED missing
  unsplash      UNSPLASH_ACCESS_KEY present
  (unclaimed)   ARTSY_CLIENT_ID present · ARTSY_CLIENT_SECRET present
  Admitted by allowed_provider_env and read by no registered provider — Artsy's are
  kept deliberately (#144 §4). Not a fault; a credential nothing asks for.

  12/12 ready · 0 switched off · 0 waiting for a credential

  Configuration only. A present credential has not been used against the provider yet.

Keyless — the same twelve rows, the .env symlink moved aside, exit 0:

PROVIDERS (12 registered)
  provider      kind     ready   switch  policy  endpoints
  bing-news     server   yes     on      ok      https://www.bing.com/news/search
  cinegraph     server   no      on      ok      https://cinegraph.org/api/graphql
  commons       server   yes     on      ok      https://commons.wikimedia.org/w/api.php
  giphy         browser  no      on      ok      https://api.giphy.com/v1/gifs/search
  guardian      server   no      on      ok      https://content.guardianapis.com/search
  met           server   yes     on      ok      —
  open-library  server   yes     on      ok      https://openlibrary.org
  openverse     server   yes     on      ok      https://api.openverse.org/v1/images/
  pexels        server   no      on      ok      https://api.pexels.com/v1/search
  poetrydb      server   yes     on      ok      https://poetrydb.org
  spotify       server   no      on      ok      https://api.spotify.com/v1/search  https://accounts.spotify.com/api/token
  unsplash      server   no      on      ok      https://api.unsplash.com/search/photos

CREDENTIALS (names only — no value is read to print this)
  missing is a name this environment does not set. Whether that matters is the provider's answer above, not this line's: a switch left unset is its default.
  bing-news     BING_NEWS_ENABLED missing
  cinegraph     CINEGRAPH_API_KEY missing · CINEGRAPH_GRAPHQL_URL missing
  giphy         GIPHY_API_KEY missing
  guardian      GUARDIAN_API_KEY missing
  pexels        PEXELS_API_KEY missing
  spotify       SPOTIFY_CLIENT_ID missing · SPOTIFY_CLIENT_SECRET missing · SPOTIFY_ENABLED missing
  unsplash      UNSPLASH_ACCESS_KEY missing
  (unclaimed)   ARTSY_CLIENT_ID missing · ARTSY_CLIENT_SECRET missing
  Admitted by allowed_provider_env and read by no registered provider — Artsy's are
  kept deliberately (#144 §4). Not a fault; a credential nothing asks for.

  6/12 ready · 0 switched off · 6 waiting for a credential

  Configuration only. A present credential has not been used against the provider yet.

mix dd.discovery.status

Keyed, against the development database:

DISCOVERY (12 registered providers, read at 2026-09-22 16:31:47 UTC)
  provider      state       runs  failed  last success         held  roots  stale   due   budget  backoff
  bing-news     ready         10       0  Sep 22 16:09 (21m)     40     10      6     0     0/30  —
  cinegraph     ready         20       0  Sep 21 17:24 (23h)     99     20      7     0     0/30  —
  commons       ready          7       0  Sep 20 13:37 (2d)      74      6      0     0     0/30  —
  giphy         browser        0       0  never                   0      0      0     0    0/100  —
  guardian      ready          4       0  Sep 22 15:46 (45m)     41      4      0     0    4/400  —
  met           ready         10       0  Sep 21 13:43 (26h)     60      8      5     0   0/1000  —
  open-library  ready         22       3  Sep 21 15:47 (24h)    184     19      1     0     0/30  —
  openverse     ready         23       0  Sep 21 17:24 (23h)    201     22      3     0     0/30  —
  pexels        ready         17       0  Sep 21 17:24 (23h)    202     15      0     0     0/30  —
  poetrydb      ready         28       0  Sep 22 15:38 (53m)     77     28     14     0     0/30  —
  spotify       ready          5       0  Sep 22 15:38 (53m)     48      5      0     0    3/500  —
  unsplash      ready         18       0  Sep 21 17:24 (23h)    176     17      3     0     0/30  —

  39 of 154 display roots are past their refresh clock; each is re-queued by the next visit to its page.
  0 run(s) are past retention and go on the next cleanup tick (counted over the next 500 due, oldest first).
  1 provider(s) are driven by the reader's browser and store nothing here, by design.

Keyless — twelve rows, not one:

DISCOVERY (12 registered providers, read at 2026-09-22 16:31:38 UTC)
  provider      state       runs  failed  last success         held  roots  stale   due   budget  backoff
  bing-news     ready         10       0  Sep 22 16:09 (21m)     40     10      6     0     0/30  —
  cinegraph     no key        20       0  Sep 21 17:24 (23h)     99     20      7     0     0/30  —
  commons       ready          7       0  Sep 20 13:37 (2d)      74      6      0     0     0/30  —
  giphy         browser        0       0  never                   0      0      0     0    0/100  —
  guardian      no key         4       0  Sep 22 15:46 (45m)     41      4      0     0    4/400  —
  met           ready         10       0  Sep 21 13:43 (26h)     60      8      5     0   0/1000  —
  open-library  ready         22       3  Sep 21 15:47 (24h)    184     19      1     0     0/30  —
  openverse     ready         23       0  Sep 21 17:24 (23h)    201     22      3     0     0/30  —
  pexels        no key        17       0  Sep 21 17:24 (23h)    202     15      0     0     0/30  —
  poetrydb      ready         28       0  Sep 22 15:38 (52m)     77     28     14     0     0/30  —
  spotify       no key         5       0  Sep 22 15:38 (53m)     48      5      0     0    3/500  —
  unsplash      no key        18       0  Sep 21 17:24 (23h)    176     17      3     0     0/30  —

  39 of 154 display roots are past their refresh clock; each is re-queued by the next visit to its page.
  0 run(s) are past retention and go on the next cleanup tick (counted over the next 500 due, oldest first).
  1 provider(s) are driven by the reader's browser and store nothing here, by design.

/ops/discovery

1280 px, light and dark:

1280 light
1280 dark

375 px, light and dark. Measured rather than eyeballed: document.documentElement.scrollWidth
is 375 and window.innerWidth is 375 — the two tables scroll inside their own boxes and the
page does not scroll sideways.

375 light
375 dark

Gate

MIX_TEST_PARTITION=p4ops mix precommit — 1,722 tests, 0 failures (1,692 on main).

Shared files touched: config/runtime.exs, router.ex, layouts.ex, components/ops.ex,
components/culture.ex (one line), and the two discovery documents. No provider module changed.

🤖 Generated with Claude Code

@gitguardian

gitguardian Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.


🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.

@coderabbitai

coderabbitai Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

  • Run on-demand review

This review includes 17 billable files and costs up to $4.25.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 15 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 72 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Essentials

Run ID: fbb70c0b-e9f3-4b3b-a095-6a541e0559b1

📥 Commits

Reviewing files that changed from the base of the PR and between 223db29 and ad3e826.

⛔ Files ignored due to path filters (4)
  • docs/discovery/issue-144-phase4-ops-discovery-1280-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase4-ops-discovery-1280-dark-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase4-ops-discovery-375-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase4-ops-discovery-375-dark-2026-09-22.jpg is excluded by !**/*.jpg
📒 Files selected for processing (17)
  • README.md
  • config/runtime.exs
  • docs/discovery/README.md
  • docs/discovery/adding-a-provider.md
  • lib/devils_dictionary/discovery/status.ex
  • lib/devils_dictionary_web/components/culture.ex
  • lib/devils_dictionary_web/components/layouts.ex
  • lib/devils_dictionary_web/components/ops.ex
  • lib/devils_dictionary_web/live/discovery_live.ex
  • lib/devils_dictionary_web/router.ex
  • lib/mix/tasks/dd.discovery.check.ex
  • lib/mix/tasks/dd.discovery.status.ex
  • test/devils_dictionary/discovery/status_test.exs
  • test/devils_dictionary/tasks/dd_discovery_check_test.exs
  • test/devils_dictionary/tasks/dd_discovery_status_test.exs
  • test/devils_dictionary_web/components/culture_chrome_test.exs
  • test/devils_dictionary_web/live/ops_discovery_live_test.exs

Comment @coderabbitai help to get the list of available commands.

holden and others added 2 commits September 22, 2026 18:37
…eader

`mix dd.discovery.check` had checked CineGraph, by name, since the second
provider was registered. Eleven providers could have had a missing credential,
an endpoint pasted whole out of a dashboard with its userinfo still in it, or a
`source_policies` override `Policy` cannot read, and the preflight would still
have printed *CineGraph configuration ready*. And the other half of the
operator's question — what has each provider spent, what is it holding, what is
stale, what does retention take next — had no reader at all: it was four tables
and a `SELECT`.

One module answers both. `Discovery.Status.preflight/0` reads the registry,
each provider's own `enabled?/0`, its stanza and its policy;
`Discovery.Status.rows/0` reads `discovery_runs`, `discovery_results`,
`discovery_request_attempts` and the source row's provider-wide backoff.
`mix dd.discovery.check`, `mix dd.discovery.status` and a new `/ops/discovery`
render what those two return and hold no numbers of their own — the arrangement
`Health.records/1` has had with `mix dd.health` and `/ops/imports` since #69 §6,
for the reason that page states: two implementations of one number are two
numbers.

**Nothing names a provider.** Both functions map `Providers.all()`, so the
thirteenth gets a row in both tasks and both tables the day it is registered,
and three tests prove it by registering a fake and finding its row. Two
conventions the twelve already follow carry the rest: a provider's stanza is
its slug with hyphens as underscores, and its credentials are the
`allowed_provider_env` names starting with its shell-safe prefix — the same
`env_prefix` `runtime.exs` already derives the per-provider policy variables
with. A name no registered provider claims is printed as *unclaimed* rather
than dropped, which is what Artsy's two have been since it left the registry.

**No credential value is read to report one.** `runtime.exs` is the only scope
holding both the exported environment and the development `.env`, so that is
where presence is decided; what leaves it is one boolean per admitted name, and
`:provider_credentials` is a map of them. A task asking `System.get_env/1`
would have called every `.env` key missing in dev. The check task's suite
configures a distinctive value for every keyed provider and greps the task's
whole output for each one; the status task's and the page's do the same.

A misconfiguration fails the preflight. **A missing credential does not**: a
keyless checkout is a deployment this system is designed to have, and a gate
against it would be a gate against the Met. A registry `validate!/0` refuses is
checked first and on its own — asking a module that does not export
`enabled?/0` whether it is enabled raised `UndefinedFunctionError` out of the
preflight, which is a worse report of the same fault than the sentence the boot
check already writes.

Measured, on this machine, 2026-09-22:

  * keyed: `mix dd.discovery.check` prints 12 rows, `12/12 ready`; keyless
    (the `.env` symlink moved aside), the same 12 rows, `6/12 ready · 0
    switched off · 6 waiting for a credential`, exit 0.
  * `mix dd.discovery.status` prints 12 rows on both, and on the development
    database reads 164 runs, 1,202 results held, 39 of 154 display roots stale
    and 0 past retention — the acceptance line's *nine rows, not one*, at the
    count the registry has now.
  * `/ops/discovery` at 1280 and 375 px, light and dark, in
    `docs/discovery/issue-144-phase4-*`. At 375 the page's `scrollWidth` is
    375: the two tables scroll inside their own boxes and the page does not.
  * `mix precommit` — 1,722 tests, 0 failures, from 1,692 on `main`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…aid nothing

Checking the issue's fourth acceptance line rather than assuming it: *every
shelf on `/define/war` says when it was fetched or since when it is held*. Six
do, since Phase 2 — film, artworks, images, text, news and music read *Fetched
4 days ago · refreshes on your next visit after…*, and the artwork shelf's
corpus half adds *catalog held since 17 Sep 2026*. The GIFs shelf said nothing
at all.

It said nothing because `freshness/1` reads a display root and a browser shelf
has none: the request is the reader's browser's and nothing it returns is
stored, which is K10 and is the point of that transport. But *now, and not
kept* is an answer to when this was fetched, and a shelf that stays silent
reads as one whose age nobody knows rather than one that has no age to have.

One line, in the shared browser shelf, where it names no provider: *Fetched by
your browser on this visit; nothing is stored here.* — the same sentence the
on-demand definition card already uses for the same reason, in the same place
the server shelves put theirs. Its id follows the browser shelf's own rule and
carries the provider as well as the type, because two browser providers on one
content type are two shelves.

Measured: `/define/war` on the development database now answers the acceptance
line for all seven shelves; `culture_chrome_test.exs` asserts the line and its
id, beside the Phase 2 cases for a fetched shelf, a corpus shelf and a shelf
that has fetched nothing and rightly says nothing. 27 tests in that file, 0
failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@holden
holden force-pushed the claude/phase-4-operators-view-823045 branch from 55137b1 to ad3e826 Compare September 22, 2026 16:37
@holden

holden commented Sep 22, 2026

Copy link
Copy Markdown
Member Author

Re-pushed after GitGuardian flagged two findings on the first push. Both were the test fixtures' own sentinel values — spotify-id-…/spotify-secret-… read as an OAuth2 client-credentials pair, which is exactly the shape the "never prints a key" tests need to plant and then grep for. The values are now sentences (spotify-id-a-preflight-must-never-print) rather than random-looking tokens, the two commits were rebuilt so the old strings are not in the branch's history, and GitGuardian passes. No production code changed with them.

Gate re-run after the rename: MIX_TEST_PARTITION=p4ops mix precommit — 1,722 tests, 0 failures. (One intervening run had a single health_records_test.exs setup failure under load; that file passes alone and the next two full runs were clean — the shared-test-database flake this repo's docs describe.)

@holden
holden merged commit 8acfafe into main Sep 22, 2026
2 checks passed
holden added a commit that referenced this pull request Sep 22, 2026
The suite's only warning after #153 and #154 merge, and a warning is a
line the next reader has to read past.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@holden
holden deleted the claude/phase-4-operators-view-823045 branch November 7, 2026 12:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant