Skip to content

Discovery provider kit: one reader surface, conformance, a generator and the docs — proved by PoetryDB, then scaled by archetype (supersedes #102) #109

Closed

Description

@holden

Purpose

Three providers exist and they share less than they should. This issue codifies what a provider is, so an agent can add one from the documentation alone, proves it with a text provider built that way, then scales by archetype. It supersedes #102 (Phases 1 and 2 delivered there; its Phases 3–5 are re-planned here with what they taught). #100 (provider research), #101 (assessor), #97 (personas) and #85 (umbrella) stay as the specs this tracker sequences.

Handoff prompts, one line each: "Do Phase 1a of #109", "Do Phase 1b of #109", "Do Phase 2 of #109".

Schema impact

0 new tables, 0 changes to existing tables through Phase 3. Phase 4 (assessor) may need pgvector; that decision is #101's and is not approved here.

Where it stands — main @ 4560308, 1,052 tests / 0 failures

Source Archetype today Code Reader surface State
CineGraph (films) discovery provider (GraphQL POST, cursor, keyword-id match) 429 lines Culture.section live-verified, #88
The Met (artworks) discovery provider (GET, offset, tag-QID identity match + ≤2-step broader walk) and corpus (met-highlights-v1, 1,644) 613 + 137 + ~1,200 Culture.section and the tall #artwork-candidates cards #102 2a/2b
Wikidata famous paintings corpus only (wikidata-famous-v1, 1,575, threshold 10 sitelinks, Mona Lisa in) shared with Met corpus tall cards #102 2b
Artsy pre-kit: own client, coordinator, seeder, catalog ~3,500 lines for 43 artworks tall cards + /artworks frozen pilot, #86
GIPHY browser widget, transient 254 its own shelf parked (no caching approval), #91

Catalog: 3,212 artworks in work_details, 1,668 Met ids, Mona Lisa Q12418 present. Association is identity, not text: 15,010 lexemes carry an active QID link after #102 D12 reinstated the 14,116 links #82 had withdrawn.

What works: the pipeline (admission, DB-coordinated budget, positive/negative cache, run lease, cleanup, PubSub) for two providers; QID identity match (soldier, war via World War I → world war → war); committed checksummed corpora; covers?/1 so a provider declines targets it cannot match.

What does not, and is this issue's reason:

  1. Three reader chromes for one content type — /define/soldier shows the tall catalog cards and the compact Met shelf.
  2. No document says how to add a provider. docs/discovery/ holds one handoff; docs/integrations/ holds per-source notes.
  3. Nothing asserts that a provider conforms. "Does discovery work" has been an audit per provider.
  4. Artsy is 3,500 lines beside the pipeline, not in it.
  5. Discovery.target_for_page/3 takes the lowest object id of a page's lexemes — /define/war opens on the prefix sense; the Met reads the whole page's senses to route around it.
  6. The Met provider queries only the first of a mapping's search terms, and paces at 1 s where 3 s is the measured sustainable rate.
  7. family, grief, justice, solitude have no QID link of any kind — the linker's coverage, not any provider's.

Learned, durable (do not re-measure)

  • Met: search totals are parameter-order-sensitive (2,310 / 2,299 / 62 for one query); isPublicDomain=true on search does not filter (objects 108646, 261944); 403 is a volume throttle — 44% refused over 2,600 requests at 1 req/s, none at 3 s/request; every tag row carries a QID (215/215, 68/68); highlights are 26.8% not public domain, so the PD highlight ceiling is ~1,675; objectDate is free text; 16/1,644 titles exceed 255 chars.
  • Wikidata: bind sitelink counts with VALUES, never FILTER (58 s → 12 requests); P11005 (Artsy artwork) = 48 items worldwide; P2042 (Artsy artist) = 21,488; P3634 (Met object) = 71,926; the Mona Lisa is reachable only here (P18 Commons image, 146 sitelinks); wbgetentities walks up (instance/subclass of), never down.
  • Encyclopedia: entities.preferred_label is varchar(255) (characters); refers_to (sense → entity) and lexeme_entity_candidate (lexeme → entity) are the two link predicates; identity is retired, never deleted; Claims.reinstate/2 is the reversal tool.
  • Process: mix compile to completion before mix phx.server or Oban discards jobs with module is not a worker (three sessions bitten); a fresh worktree always fails manifest_test.exs:25 (wants untracked data/ dumps) — not evidence; keep PRs under 150 files or CodeRabbit skips silently; a builder writes running ledger totals, never only at the end (2b's total is a range because the run was killed); zsh does not word-split $var in for — use ${=var}; the dev DB is devils_dictionary_v2, never devils_dictionary_dev.
  • Carried decisions from Discovery layer triage 2026-09-17: harden the provider contract, then the Met, then a text provider, then the UI #102 (D1–D14) stand: contract before providers; identity not text (D11); committed manifests (D10); reinstated links (D12); provider-classified retry statuses + min_retry_interval_ms (D13); bounded ledgers, no image bytes, PD only (D14).

Decisions (defaults; change them here, not in a chat)

  • K1 — Two archetypes and no third. A discovery provider answers a page live through the pipeline (Discovery.Provider, retrieve/4). A corpus is a committed, checksummed manifest seeded onto the registry (Artworks.Corpus.Manifest / Seeder, generalised to any work_kind). A source may be one or both. Anything else is a defect to fold in, not a shape to keep.
  • K2 — One reader surface. Every result, live or from a corpus, renders through Culture.section keyed by the content-type table. A corpus candidate becomes a shelf item with a match reason, sorted after live results. The tall #artwork-candidates section and Artwork.card leave the word page (/artworks stays as the browse page). A provider ships zero components.
  • K3 — One match-reason struct: %{kind, identifier, term, relation: exact | broader | related | attests, scope: sense | lexeme, locator, note}. CineGraph keyword ids, Met tags, catalog depicted-QIDs and text attestations all fill it; one function renders it.
  • K4 — Page target = the page's lexeme set. Replace target_for_page/3's lowest-id pick with the scope Lexicon.by_lemma_or_slug/2 already defines; mappings key on the page, evidence reads every sense on it (what the Met does privately becomes the shared rule). The shelf keeps saying relevance to this particular meaning is unverified. Sense-level relevance is Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101's.
  • K5 — Pacing is a capability. request_interval_ms joins min_retry_interval_ms in capabilities/0; the shared transport honours it; Met = 3,000. Every search term in a mapping is queried, round-robin across pages, not only the first.
  • K6 — Conformance is a test, not an audit. DevilsDictionary.Discovery.Conformance drives any provider through admission, budget, cache, pagination, cleanup, render and identity with its own Req.Test stub; Corpus.Conformance checks checksum, idempotent seed and label width. Every registered module must pass or the suite is red.
  • K7 — A generator. mix dd.provider.new <slug> --archetype discovery|corpus|both --content-type <type> --transport get|graphql --pagination offset|cursor scaffolds the module(s), stub, config entries, conformance test include and a ledger template; --content-type unknown to the table refuses.
  • K8 — Two documents. docs/discovery/README.md (architecture: pipeline stages, identity rule, archetypes, content-type table, budgets) and docs/discovery/adding-a-provider.md (the checklist: bounded probe + ledger → spec → generator → stub → conformance → browser proof → PR under 150 files). docs/integrations/<slug>.md stays the per-source page. Document encyclopedia composition and scope per-entry editorial selection #96's composition doc folds into the README.
  • K9 — Artsy is frozen, then folded. No new Artsy code. Phase 1a moves its 43 artworks' read path onto K2; its Client/RequestCoordinator/Availability stay until Phase 3 retires them behind the shared transport or deletes them.
  • K10 — GIPHY stays parked until written caching approval exists; the kit does not touch it beyond rendering its shelf through K2's chrome.
  • K11 — Text providers match by attestation. A text that uses the word is evidence the word is used, shown as uses "war" (relation attests), never as about. Identity for the author comes from a QID crosswalk in the manifest where one exists.
  • K12 — PoetryDB is the text provider (public domain, keyless, plain JSON GET, ~3,000 poems / ~130 authors): both archetypes — a corpus manifest of the whole database plus a discovery provider over /lines/<word> — so one small source proves K1 end to end.
  • K13 — Next sources by archetype, owner confirms or reorders: Open Library (books; corpus + discovery; OLID + Wikidata P648), Openverse (images; discovery; licence per item), Chronicling America (historical news; discovery; attestation; public domain). Not MusicBrainz/IGDB/Guardian until the non-commercial posture is settled (Explore next discovery providers: quotes, music, books, news, images, games, nature and social APIs #100).

Phase 1a — the reader and the shared rules (one session)

  1. K2: catalog candidates flow into Culture.section as items with a K3 match reason; retire #artwork-candidates from word_live.ex; content-type shelf order film · artwork · text · gif; /define/soldier, /define/love, /define/allegory (the Artsy pilot) each show one Artworks shelf.
  2. K3 struct + one renderer replacing Culture.match_detail/2's three branches and Artwork.card's copy.
  3. K4 page scope in Discovery (shared), Met's private target_entities/1 deleted in favour of it; CineGraph unchanged in behaviour.
  4. K5 pacing capability; Met at 3,000; all search terms queried.
  5. mix compile-before-server line in the README's development section.

Exit: precommit green; the three pages above show one artwork shelf each with Met, Wikidata and Artsy items interleaved and their reasons named; /define/war still opens on war the noun (K4) with films, artworks, GIFs in that order; 375 px attested; no file under artsy/ changed except the read path.

Phase 1b — conformance, generator, docs (one session)

  1. K6 conformance suites, run against CineGraph, Met, the offset fixture, and both corpora.
  2. K7 generator with its own test (generate → conformance passes on the scaffold with a stub).
  3. K8 documents, written from the code, not from this issue.
  4. Architecture test: every module in :discovery_providers and every manifest under priv/artworks/manifests/ of schema_version ≥ 1 is covered by conformance.

Exit: precommit green; mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offset produces a module that passes conformance unedited; the two documents exist and a reviewer can follow adding-a-provider.md without opening this issue.

Phase 2 — PoetryDB, built from the documents alone (one session, the kit's acceptance test)

Rules: the agent reads only docs/discovery/*.md, docs/integrations/, and the generator's output. If it needs to open this issue, that is a finding against Phase 1b, recorded in the PR. Shared files it may touch, and only these (established by Phase 1b's audit, 2026-09-18): the two corpus registrations the generator cannot write — the kind in Corpus.Manifest's @kinds and an entry/3 clause in Corpus.Seeder (with work_kind: "poem") — and the four test files that count providers or assume one run per visit (providers_test.exs, home_live_test.exs, culture_discovery_live_test.exs, film_identity_flow_test.exs; measured 11 failures on registering a fifth provider). Touching any other shared file is the finding.

  1. Bounded probe ≤200 requests, ledger.
  2. Corpus: poetrydb-v1.json — every poem (title, author, line count, lines hash, author QID where the manifest crosswalk names one); seed as work_kind: "poem".
  3. Discovery: /lines/<lemma> → attestation candidates (K11), text-first card (no image slot), match reason uses "war" in line N.
  4. Conformance passes; browser proof on /define/war (poems shelf) and /define/love.

Exit: three providers across three content types on one pipeline, no shared file touched, conformance green, ledger ≤200.

Phase 1c — the fix-ups Phase 2 measured (one session, before Phase 3)

Added 2026-09-18 from the Phase 2 audit. Every item is a defect the acceptance test surfaced; none changes provider behaviour or the reader.

  1. Registering a provider turns 0 tests red. The four counting tests (providers_test.exs, home_live_test.exs, culture_discovery_live_test.exs, film_identity_flow_test.exs) assert membership and per-provider runs, never totals or "the only run". Prove it the way Phase 1b measured it: scaffold demo with the generator, run the full suite, expect only the environmental failure, delete demo.
  2. Corpus registration is one place. identity, namespace and work_kind already live in Corpus.Manifest.@kinds; the entry/3 row mapping in Corpus.Seeder is the one edit that must stay code. The generator prints all three registrations for --archetype corpus|both (it names two today), and its test asserts the printout matches @kinds' keys.
  3. adding-a-provider.md §6: replace "use another port" with the rule Phase 2 stated — same database → the other server stops; different database → another port — and add one test run per test database beside it (four BEAM VMs on devils_dictionary_test produced 41 phantom failures during the 1b audit).
  4. Ledger template gets the running-total column §1 demands; the covers?/1 browser item says what to verify when a provider declines nothing (an unattested word → empty shelf, negative cache, one request).
  5. Optional, ≤40 requests, ledgered: recover Byron and Shelley into poetrydb-v1 by linecount bucket; bump the manifest, keep provenance exact in selection.
  6. Seed poetrydb-v1 into devils_dictionary_v2 (mix dd.artworks.seed, dry run first, counts in the report) so the corpus half is live on the same database the discovery half already uses.

Exit: precommit green; item 1's proof pasted; generator test green; both documents updated and every command in them still runs; work_kind: "poem" count in work_details equals the manifest's row count.

Phase 3 — the next three sources, one session each (3a → 3b → 3c)

Written 2026-09-18 after Phase 1c. Each source is chosen to prove a shape the kit has not yet exercised. Every session follows docs/discovery/adding-a-provider.md as written — probe with a ceiling and a running ledger, spec, generator, stub, conformance, browser proof, PR under 150 files, report — and reads this section once for its defaults. The one rule holds everywhere: association is identity (a QID the encyclopedia already asserts) or attestation (a text that uses the word); never a text search's own ranking. Handoff prompts: "Do Phase 3a of #109", then 3b, then 3c.

K13 amended: Wikimedia Commons replaces Openverse. Openverse publishes free-text tags and no Wikidata identifiers, so an image provider on it could only match by text, which the one rule forbids. Commons carries structured data — P180 depicts QIDs on files — plus a licence per file and a MediaWiki API with continuation cursors, which is the pagination shape the kit has only ever proven on CineGraph.

3a — Wikimedia Commons: images, discovery, the cursor proof, and Artsy retired

3b — Chronicling America: historical newspapers, text, attestation at scale

  • Archetype discovery only. Content type :text. Transport GET, pagination offset (page=). Public domain (Library of Congress, pre-1930 pages).
  • Match: attestation (K11) — search/pages/results?andtext=<word> proposes; the OCR text of the hydrated page disposes at a word boundary; the reason is uses "war" — , , page N. OCR is noisy: require the exact token, and record the OCR line as the note.
  • Identity: namespace loc_page = lccn/date/edition/sequence; the newspaper title's LCCN is metadata.
  • Pacing: the LoC publishes a rate; measure it; start at 1 s. Probe ceiling 300.
  • Why here: the second text provider tests whether the text card and the attestation reason generalise beyond poems — and the 375 px text card that Phase 2 found cramped gets its second user, which is the moment to fix it in Culture (shared, one change, before the PR).
  • Two shared changes this session owns, each its own commit, before the provider: (1) WordPage's ranking within a part of speech prefers the bare lemma, so /define/dog opens on dog (#51134) and not 'dog (#1547258) — the 3a audit found every apostrophe-led Wiktionary row wins today, and K4's target inherits it; a regression test on a page with both rows. (2) The :text card in Culture at 375 px: titles truncate to a few characters in a poster-width grid; give text items a wider column or a two-line title, measured on /define/war at 375, screenshot before and after.
  • From the 3a audit, for the guide: the README's transport section gains the sentence that MediaWiki-style APIs may send Retry-After on an HTTP 200 body; PageEvidence joins the quick reference; the ceiling is stated as per-phase. Small, same PR.
  • Exit: conformance green; /define/war and /define/telephone show a Texts shelf carrying poems and newspaper pages together; /define/dog opens on dog; the text card is legible at 375 px with a before/after pair; ledger ≤ 300.

3c — Open Library: books, both archetypes, the corpus-only path proven — and, since 3b's source is unreachable, the second attestation provider

From 3b (2026-09-18): Chronicling America is behind Cloudflare bot verification on every endpoint (403 "Just a moment…", verified twice); its bulk OCR tarballs are the only thing that answers and are a possible corpus later, not a provider. PORT=4017 works (config/runtime.exs:24); 3b's report saying otherwise is wrong.

  • Archetype both. Content type :text. Transport GET, pagination offset.
  • Corpus: openlibrary-classics-v1 — a committed manifest of public-domain works with a Wikidata QID via P648 (Open Library ID on Wikidata), built by a SPARQL page (?work wdt:P648 ?olid; wdt:P31/wdt:P279* wd:Q7725634; wdt:P50 ?author) with a sitelink floor measured with the VALUES-bound walk, identity olid, work_kind: "book", evidence: :none; author QIDs from the same query. This is the first corpus registered end to end through the generator's printout — the five @kinds keys and the entry/3 clause — and the report says whether the printout was sufficient.
  • Discovery: attestation via Open Library's full-text search (search/inside.json?q=<word>), the hit's snippet disposes at a word boundary; reason uses "war" in <title> (); identity olid so a live hit and a corpus row converge on one entity, as PoetryDB's do.
  • Pacing: measure; Open Library asks for a User-Agent with contact; ceiling 300.
  • Exit: conformance green for provider and corpus; coverage test sees both; /define/war shows books beside poems and pages on the one Texts shelf; the corpus seeds twice to identical counts; ledger ≤ 300.

After 3c

Four content types are still four; five providers and five corpora run on one pipeline; the shapes proven are GraphQL+cursor (CineGraph), GET+offset (Met, PoetryDB, Chronicling America, Open Library), GET+cursor (Commons), corpus-only (Open Library's manifest through the generator). Then Phase 4.

Phase 4 — assessor P0 (#101) on four providers, then personas (#97)

Starts after Phase 2. #101's spectrum prerequisite is replaced by "whatever Phases 2–3 delivered".

Checklist

Activity

  1. added a commit that references this issue on Sep 17, 2026
  2. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    Phase 1a done — #112, not merged

    K2, K3, K4, K5 and the README line. Schema impact: none. 27 files. mix precommit: 1,075 tests, 1 failure — manifest_test.exs:25, the fresh-worktree data/ dumps, not evidence. Five further full runs across four seeds reproduced only that one.

    The three pages, and /define/war

    One Artworks shelf each, reasons named, films · artworks · GIFs in that order.

    /define/soldier — the Met's 12 live results, then the catalog's 12 (Wikidata + The Met). The byline names both archetypes; each has its own About these results.

    soldier, 1280

    /define/war — the K4 payoff. The target is now the noun, so Q198 from the noun's sense reaches the page; the Met's broader walk says Related to “War” through the tag “American Civil War” (Q8676) and the catalog says Direct depiction of “War” (Q198) tagged “war” · not yet reviewed.

    war, 1280

    /define/allegory — the Artsy pilot's 43 artworks read through K2's chrome and nothing else under artsy/ changed. Related Artsy gene “Allegory”.

    allegory, 1280

    /define/love — catalog only; the Met declines a target it cannot match, so there is no shelf for it and no run was spent finding that out.

    love, 1280

    375 px

    document.documentElement.scrollWidth == 375 on all four — no horizontal page scroll. Left to right: soldier, war, allegory, love.

    soldier, 375
    war, 375
    allegory, 375
    love, 375

    Where the code disagreed with the brief

    1. Lexicon.by_lemma_or_slug/2 is private, and it is not the scope K4 needs. It anchors on the string a reader typed, so the same page reached by /define/war and by /words/147197/war resolves to different sets. K4's scope has to be answerable from a lexeme id, because that is what a target, a mapping and a catalog read all hold. I added Lexicon.page_scope/1 (a query of object ids) and page_lexeme_ids/1 beside it, which is the lexeme-anchored form the Met had already built privately, and deleted the Met's copy.

    2. The target cannot be only a set. discovery_mappings.target_object_id is a registry identity and a set is not one, so the target still names one lexeme — but it is now the lexeme the page opens on rather than the lowest object id, and it carries lexeme_ids beside it. /define/war: was the verb 55026, is now the noun 147197, both mappings verified in the dev database.

    3. The lexeme set has to come from the database, not from page.headword.lexemes. mapping_target/1 rebuilds the recipe at publication time, when there is no page. Taking the set from the rendered page would make /words/:id/:slug (one lexeme) and /define/:slug (seven) produce different QID sets for the same mapping key, and every evidence-versioned Met run would publish as mapping_evidence_changed. It is one cheap query in both places instead.

    4. K3's struct needs an eighth field. %{kind, identifier, term, relation, scope, locator, note} cannot express the Met's broader walk: Related to “War” through the tag “American Civil War” (Q8676) holds the tag's term and QID and the label of the concept the walk reached. Neither term nor note can hold both without meaning two different things, so MatchReason carries reached as well, documented as such.

    5. K5's pacing could not live only in fetch_objects/3. Moving it to the transport paces the Met's search too, so one page is 26 paced requests rather than 1 unpaced plus 25. Met.capabilities/0 reads config[:request_interval_ms] with the measured 3,000 as its default, because config/test.exs needs 0 and a capability that ignored the environment would put 78 s of sleep in the suite.

    6. A cursor's empty page still has to advance. The Met answered a no-match search by ending pagination, so with round-robin the second and third search terms would still never be asked. The empty branch now advances the cursor.

    7. The compact shelf had no place for the contributor's composer link, which the tall card carried. Dropping it would have removed a write path K2 says nothing about, so it moved into the shelf's About these results list, gated exactly as before (#culture-connect-c<id>, still server-gated at /connect).

    8. The shelf rail's scroll snapping is incompatible with a shelf that fills twice. CSS scroll snap re-snaps a container to its previously snapped box after a layout change; the corpus items paint synchronously and the live results are prepended when they arrive, so /define/soldier's artwork shelf opened with scrollLeft == 1584 — past every result the page had just fetched. Measured in Chrome, fixed by dropping snap-x snap-proximity from the rail, pinned by a test. overflow-anchor: none was not the cause; I tried it first and it changed nothing.

    9. Copy, on purpose: the caveat is now Relevance to this particular meaning is unverified rather than Keyword relevance… — one shelf carries keyword matches, tag identities and depicted QIDs, and K4 phrases it without the word too. The shared renderer also names a keyword's TMDb id, as the Met's shelf has always named its QIDs.

    Live provider ledger

    Whole session, from discovery_request_attempts:

    provider requests detail
    CineGraph 2 one new mapping (war the noun): keyword search + discover
    The Met 26 one new mapping (war the noun): 1 search + 25 hydrations

    No image bytes fetched. The other three pages' shelves came entirely from cache and the committed corpora.

    One thing the ledger cannot show, and should be recorded: the observed gap between those 26 Met requests was 1.17 s, not 3 s — because a dev server from the main checkout was running on port 4007 against the same devils_dictionary_v2, and its Oban node executed my queued job with main's code. The proof is in the run's own row: next_cursor came back as the bare "25" with a null term_index, which is pre-#109 output. Two Oban nodes on one database will steal each other's jobs; worth knowing before the next browser session. K5's pacing is asserted offline instead, by a test that drives a 4-request Met run at a 150 ms interval and fails below a 600 ms floor.

    Left out

    • K6, K7, K8 — Phase 1b's, untouched.
    • No file under artsy/ changed. GIPHY is untouched beyond rendering its shelf where it always did.
    • /define/soldier, /define/love and /define/allegory do not each show Met, Wikidata and Artsy items; the exit line asks for that and the data does not have it. Artsy's 43 works are only reachable from its gene mappings (allegory), and love has no Met coverage. Every page shows one artwork shelf carrying whichever of the three it has, which is what K2 actually requires; /define/soldier carries two sources in one shelf (Met live + Wikidata and Met from the corpora) and /define/allegory carries Artsy.
    • Verification ran on port 4017, not 4007: another session's dev server held 4007 from the main checkout, and screenshotting that would have been screenshotting main. Same code, same database, different port.
  3. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 1a (PR #112 @ e527107) — 2026-09-18

    Grade: A. Merge it. Phase 1b may start from its merge.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,075 tests, 1 failure — the environmental manifest_test.exs:25 only. Effective 1,075 / 0, matching the report.
    • Every removed assertion in the test diff belongs to the retired #artwork-candidates section or to the Met's deleted private scope (target_entities/1, its query-count tests). Nothing weakened; the replacements are stronger (a shelf test that asserts live-first ordering, a transport test that fails below a 600 ms floor, a round-robin test that reaches the second and third search terms).
    • K4 in the database: every war mapping before this branch targeted the verb 55026; the two created by the session's live run (54 cinegraph, 55 met, 21:23) target the noun 147197. Verified, not read off the report.
    • /define/soldier screenshot: Films → one Artworks shelf (the Met's live results, then the catalog's Wikidata and Met works) → GIFs. The two-chrome page from the 2b audit is gone.

    Code

    MatchReason is the right shape and its eighth field reached is justified — the broader walk genuinely names two things. Lexicon.page_scope/1 anchored on a lexeme id is the correct reading of K4 and the reason the same page cannot resolve to two sets. Pacing moved into the transport is the right place; the Process.sleep in the provider is gone. The scroll-snap finding (a shelf that fills twice re-snaps 1,584 px in) is the kind of thing only a browser check catches, and it is pinned by a test. All nine deviations are correctly argued.

    Two findings the session recorded that matter beyond this PR

    1. Two Oban nodes on one database steal each other's jobs. The main checkout's dev server on 4007 executed this branch's queued run with main's code (bare next_cursor, null term_index), which is why the observed Met pacing was 1.17 s. Rule for every future browser session: one dev server per database, or the audit measures the wrong code. Goes in adding-a-provider.md (Phase 1b).
    2. The exit line's "Met, Wikidata and Artsy items interleaved on all three pages" was mine and was wrong — the data cannot do it (Artsy's 43 works reach only allegory; love has no Met coverage). K2 asks for one shelf per content type carrying whatever sources it has, which is what shipped.

    Deductions and carry-forwards (none blocking)

    • The catalog shelf is computed synchronously on every first paint (Artworks.shelf_items/2 → suggestions/2, several queries) where the live providers pay only a covers? existence check. Fine at 3,212 works; measure p95 before the corpora grow past ~50k.
    • On /define/soldier the twelve live Met items (decorative arts: a watch, plates, a glass) sit ahead of Poussin and Botticelli, which are off-screen behind the rail. Live-first is the right default; ranking within a shelf is Phase 4's (Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101).
    • The byline reads The Met · tags: Wikidata · Saved catalog · Wikidata, The Met — accurate, and clunky. Copy for 1b's docs pass.
    • Corpus items carry review_state: :not_yet_reviewed and the composer link, so the write path survived the chrome change — good — but the shelf's About these results is now the only place a contributor finds it. Worth a line in the README.
  4. added a commit that references this issue on Sep 17, 2026
  5. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    Phase 1b done — #113, not merged

    K6, K7 and K8. Schema impact: none. 25 files. No provider behaviour, no reader, no Artsy or GIPHY code touched. Nothing under lib/devils_dictionary/discovery/ or lib/devils_dictionary_web/ changed at all — the only new lib/ file is the generator task.

    mix precommit: 1,188 tests, 1 failure — manifest_test.exs:25, the fresh-worktree data/ dumps, not evidence. Zero compile warnings. Baseline on main @ f147a5f was 1,078; this adds 110 tests.

    Conformance — 110 tests, 0 failures

    $ mix test test/devils_dictionary/discovery/conformance \
               test/devils_dictionary/artworks/corpus/conformance \
               test/devils_dictionary/discovery/conformance_coverage_test.exs \
               test/devils_dictionary/tasks/dd_provider_new_test.exs
    
    Finished in 6.1 seconds (0.3s async, 5.7s sync)
    110 tests, 0 failures
    
    Suite Profile Cases
    cinegraph full — GraphQL POST, cursor, two-stage retrieval 19
    met full — GET, offset, tag-QID identity, two search terms 19
    offset-fixture full — GET, offset, bare JSON array, :text 19
    artsy registry-only 9
    giphy registry-only 9
    met-highlights-v1.json corpus 8
    wikidata-famous-v1.json corpus 8
    architecture test — 5
    generator — 14

    A full-profile provider is driven through: the contract (identity, capability shape, content types the reader can present, pacing declarations, shelf_detail, the claim-versus-callbacks gate); admission (one run per target, a second visit joins the one in flight, an unregistered slug is refused, a declined target never becomes a run); budget (an exhausted rolling window defers with request_budget, spends no request and retains what is shown); cache (a positive answer is cached and not re-asked; an empty answer is a negative cache, not a failure); pagination (the cursor the provider handed back is the cursor the next request carried; a stale cursor is refused); cleanup (an abandoned lease is recovered and the run completes); identity (every result carries a source record; a provider with an identity_record/1 resolves to an object, one without says insufficient_evidence and carries none; no illustrates claim is ever written); and the reader (renders through Culture.section on its content type's shelf, with the provider's own byline and a reason per item that renders as one sentence).

    The architecture test reads coverage off disk, not off a list: every module in :discovery_providers has a fixture, every fixture is run by a suite, every committed corpus manifest has a suite, and every other JSON file in priv/artworks/manifests/ is a well-formed Artsy import manifest.

    The generator, unedited

    $ mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offset
      created  lib/devils_dictionary/discovery/providers/demo.ex
      created  test/support/discovery/conformance/demo_fixture.ex
      created  test/devils_dictionary/discovery/conformance/demo_conformance_test.exs
      created  docs/integrations/demo.md
      updated  config/config.exs
      updated  config/test.exs
    
    next:
      1. mix compile
      2. mix test test/devils_dictionary/discovery/conformance/demo_conformance_test.exs
      3. replace the scaffolded response envelope and its stub with the real one
      4. record the probe in docs/integrations/demo.md — running totals, not a total at the end
    
    docs/discovery/adding-a-provider.md is the whole checklist.
    
    $ git diff --stat config/
     config/config.exs | 5 +++++
     config/test.exs   | 6 ++++++
     2 files changed, 11 insertions(+)
    
    $ mix compile
    Compiling 210 files (.ex)
    Generated devils_dictionary app
    
    $ mix test test/devils_dictionary/discovery/conformance/demo_conformance_test.exs
    ...................
    Finished in 1.3 seconds (0.00s async, 1.3s sync)
    19 tests, 0 failures
    

    The demo was then deleted and config/ reverted; git status is clean of it.

    Where the code disagreed with the brief

    1. K6 says "every registered module must pass". Two of the four cannot be driven, so the suite has two profiles. Artsy declares background: false and GIPHY declares transport: :browser; neither exports retrieve/4, so there is no run for a conformance suite to drive. Rather than exclude them — which would leave the architecture test asserting coverage of a list with holes in it — the case template picks a registry-only profile from the provider's own capabilities: the contract half runs, and then it asserts that server_providers/0 refuses to offer the module to the worker and that a visit cannot admit a run for it. Every registered module really does pass a suite, and a provider that later grows a server transport is promoted into the full suite without anyone remembering to move it.

    2. The architecture test cannot use "every manifest with schema_version >= 1" as the rule. priv/artworks/manifests/ holds six JSON files with a schema_version, and only two are corpora. The other four are the Artsy pilot's resumable import manifests — DevilsDictionary.Artworks.Manifest, schema_version 2, candidates keyed on qid + artsy_artwork_slug — a different format sharing a directory. Taking the brief literally would have demanded a corpus conformance suite for pilot-v1.json, which has no rows to seed. The test covers every manifest Corpus.Manifest.corpus_manifest?/1 recognises, and then asserts each remaining file loads as an Artsy import manifest, so the exception is checked rather than assumed.

    3. The conformance case lives in test/support/, not lib/. DevilsDictionary.Discovery.Conformance is the name Discovery provider kit: one reader surface, conformance, a generator and the docs — proved by PoetryDB, then scaled by archetype (supersedes #102) #109 gives it, and it is an ExUnit case template — it belongs where DataCase is, compiled only in :test. Shipping test-only machinery in lib/ would put it in a release.

    4. "Using the provider's own Req.Test stub" needed somewhere for that stub to live. Adding a stub callback to Discovery.Provider would be provider behaviour, which this session was told not to change — and a provider should not ship its own test double anyway. So a provider supplies a Conformance.Fixture in test/support/: provider/0, covered_target/1, uncovered_target/1 and stub/2. stub/2 returns the external ids its installed responses will yield, per page, so the fixture is a claim the suite checks rather than a second implementation.

    5. K7's generator cannot write a corpus's registration. A discovery provider registers in one config line. A corpus registers in two pattern matches in shared modules: the kind in @kinds in Corpus.Manifest, and an entry/3 clause in Corpus.Seeder that maps a row onto a SourceIdentity.Entry — which only someone who has read the source's own rows can write. --archetype corpus scaffolds the builder module and then prints both edits, and the generator's test asserts it prints them and that Manifest.new/3 raises on the unregistered kind. Making the generator patch two function heads was the alternative, and guessing at a field mapping is worse than naming it.

    6. Providers.get/1 answers an unknown slug with :unsupported_provider, not :provider_not_registered. :provider_not_registered is what ensure_source/1 returns when the source row is missing. The conformance admission case asserts what the code returns.

    7. K10's "rendering its shelf through K2's chrome" is not what shipped, and cannot be as things stand. Culture.section/1 draws from Discovery.state/2 items, and a browser-transport provider has none — GIPHY's requests are made by the reader's browser and nothing is cached server-side. WordLive still renders DevilsDictionaryWeb.GiphyShelf.section/1 beneath the shared section, exactly where Phase 1a left it. Both documents say so; folding it in means giving GIPHY a server transport first, which K10 parks.

    8. docs/encyclopedia/README.md — Document encyclopedia composition and scope per-entry editorial selection #96's document — was never written. Document encyclopedia composition and scope per-entry editorial selection #96 is closed and the file does not exist, so "fold Document encyclopedia composition and scope per-entry editorial selection #96's composition doc into the README" became "write the composition material into the README from the code": durable identities against source material against reader composition, what makes a discovery result disposable cache, why a provider result is never a curated claim, and Document encyclopedia composition and scope per-entry editorial selection #96's open questions named as open.

    9. Three integration pages contradicted the shipped code, and are corrected in place rather than rewritten. A dated ledger is a record, so each correction is a dated note beside what it supersedes:

      • met-2a said the sustained pace is ~1 req/s set by request_interval_ms: 1_000, "applied between this provider's own hydrations". Both halves are wrong now: the interval is 3,000 ms, and K5 moved pacing into the shared transport, so the search is paced too — one page is 26 paced requests, not one unpaced plus 25.
      • met-probe carried the same "~1 request/second sustained" as revised guidance. Discovery layer triage 2026-09-17: harden the provider contract, then the Met, then a text provider, then the UI #102 2b refused 44% of 2,600 requests at that pace. The 1.5 s min_retry_interval_ms measured there is unchanged and still shipped.
      • artsy.md said "four mappings currently have verified opaque Artsy gene IDs" where priv/artworks/meaning-mappings-v1.json has seven enabled of thirteen — and its own Known limits section already said seven. It also described a word-page candidates chrome that K2 retired.
      • giphy.md said nothing about where the provider sits in the kit; it now does.
    10. PORT=4017 mix phx.server already works — config/runtime.exs reads PORT with 4007 as its default, for every environment, and it overrides config/dev.exs's hard-coded port. Verified by config resolution (PORT=4017 mix run --no-start), not by starting a second server, because doing that against devils_dictionary_v2 is the exact thing the rule forbids. No config change was needed.

    Two things measured while verifying, worth keeping

    Registering a provider is not free in the test suite. Providers' moduledoc says adding a provider is one config line and nothing else. That is true of the application and false of the suite: scaffolding demo into the real config and running mix test gives 1,207 tests, 11 failures — ten of them real, in four files that count providers or assume one server provider makes one run:

    File Why
    test/devils_dictionary/discovery/providers_test.exs asserts the exact shipped registry (3 tests)
    test/devils_dictionary_web/live/culture_discovery_live_test.exs Repo.one!(Run) — one provider, one run (5 tests)
    test/devils_dictionary_web/live/film_identity_flow_test.exs same assumption (1 test)
    test/devils_dictionary_web/live/home_live_test.exs the stats line counts sources (1 test)

    The eleventh is the environmental manifest test. adding-a-provider.md names all four files and the measured count, so the next session does not spend an hour deciding whether its provider is broken.

    A fresh worktree has no .env, so two documented tasks exit early. mix dd.discovery.check exits with CINEGRAPH_API_KEY is missing or blank; mix dd.discovery --dry-run selects its 20 targets and then reports 0 eligible providers. Both are the tasks working correctly. The Met is keyless, so it is the provider a keyless checkout can actually drive. The README says so.

    The reader test of the documents

    Every path and every markdown link in both documents — 38 of them — was checked to exist at this commit, by script. Every Module.function/arity named in both documents plus the four corrected integration pages was resolved against the compiled application; two survivors of that check were historical (Culture.match_detail/2 and Artwork.card, both retired by Phase 1a) and were rewritten so the documents name only what exists.

    Every command in adding-a-provider.md was run as written:

    Command Result
    mise install mise all tools are installed
    mix deps.get All dependencies have been fetched
    mix compile clean
    mix precommit 1,188 tests, 1 failure (environmental)
    mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offset 4 files created, 2 config files updated
    mix test …/demo_conformance_test.exs 19 tests, 0 failures
    mix test …/conformance …/corpus/conformance …/conformance_coverage_test.exs 96 tests, 0 failures
    lsof -nP -iTCP:4007 -sTCP:LISTEN found the other checkout's beam.smp — which is the finding the rule exists for
    PORT=4017 mix phx.server port resolution verified; the server was not started (see below)
    git diff --name-only main...HEAD | wc -l 25
    git switch -c … available in this git

    The three commands in the README's development section were run too: mix dd.discovery --dry-run, mix dd.discovery.check and mix dd.artworks.seed --dry-run (1,644 rows, would_seed: 1644, nothing written).

    Left out, and why

    • No browser proof, and none was asked for. This session adds tests, a generator and documents; nothing it changed is visible on a page. A dev server from the main checkout was holding port 4007 against devils_dictionary_v2 for the whole session, and starting a second node against that database is precisely what the rule this PR documents forbids. PORT=4017 mix phx.server is therefore verified by config resolution rather than by a second running server.
    • No live provider requests. Ledger: zero. Every conformance case runs through Req.Test; no image bytes, no network.
    • The generator's own test does not run the full 19-case conformance suite on its temporary-directory scaffold. Running ExUnit inside ExUnit is not something to build on. Instead it generates into a temp directory, compiles the provider and fixture in memory, and drives them through the real pipeline — admission, cache, negative cache and two-page pagination — for all four transport × pagination combinations. The full 19-case proof on a generated provider is verification step 3 above, run against a real mix dd.provider.new demo in the repository and pasted in full.
    • The registry-only profile does not prove Artsy or GIPHY work. It proves they are registered, declare a coherent contract, and cannot be scheduled. Neither has a pipeline to exercise; K9 and K10 are why.
    • mix dd.provider.new --archetype corpus does not produce a corpus that passes conformance unedited, and cannot — see disagreement 5. The discovery half does.
  6. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 1b (PR #113 @ f231121) — 2026-09-18

    Grade: A. Merge it. Phase 2 is ready, with one rule amended below.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,188 tests, 1 failure — the environmental manifest_test.exs:25 only. Matches the report.
    • The generator, unedited: mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offset wrote the four files and two config edits; mix compile clean; demo_conformance_test.exs → 19 tests, 0 failures. An unknown --content-type video is refused with the table's rule.
    • The documented breakage is exactly right. With demo registered, a clean full-suite run is 1,207 tests, 12 failures: 5 in culture_discovery_live_test.exs, 3 in providers_test.exs, 1 each in home_live_test.exs and film_identity_flow_test.exs, plus the environmental one — the four files adding-a-provider.md names. (My first measurement said 41; the extra 29 were in absorb/health/lexicon modules, vanished when run alone, and coincided with four BEAM VMs alive on this machine — another session's test run sharing devils_dictionary_test. Same trap as the two-Oban-nodes rule, one database over: one test run per test database, worth a line in the guide.)
    • The conformance case really drives the pipeline: 19 named cases per full-profile provider covering contract, admission, budget, positive/negative cache, cursor continuation and stale-cursor refusal, lease recovery, identity, no-illustrates invariant, and the render through Culture.section; 8 per corpus including idempotent seed and label width; the coverage test reads the registry and the manifest directory off disk.
    • Both documents read as something an agent could build from. The one rule (association is identity, never text; a text provider matches by attestation) and the eight-step checklist are the two things Phase 2 needs and both are there.

    The ten deviations

    All correctly argued. Two are structural and reach into Phase 2:

    • Bump solid_queue from 1.1.0 to 1.1.2 #5 — a corpus cannot be registered by the generator: the kind in Corpus.Manifest.@kinds and an entry/3 clause in Corpus.Seeder are pattern matches only a reader of the source's rows can write. True, and it means Phase 2's "no shared file touched" gate was unsatisfiable for a both archetype as written. Amended in the Phase 2 section: those two edits plus the four counting test files are the permitted shared edits; anything else remains the finding.
    • Bump importmap-rails from 2.0.3 to 2.1.0 #1 — registry-only profile for Artsy and GIPHY is the right call; the coverage test would otherwise assert a list with holes.

    Deductions (none blocking)

    • Conformance lives in test/support/, so mix dd.provider.new on a fresh clone works only in :test — fine, documented.
    • The generator's own test drives the scaffold through admission/cache/pagination in memory rather than the full 19; the full proof is the manual step 3 above. Acceptable; a future mix dd.provider.verify <slug> would close it.
    • The README's Where things stand section will date fast; it names 2026-09-18 numbers. Keep it, but Phase 2's report should refresh it.

    Phase 2 handoff stays one line: "Do Phase 2 of #109."

  7. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    CodeRabbit on #113 — six findings, six taken (fccdd50)

    mix precommit: 1,189 tests, 1 failure (the environmental manifest test), zero warnings. The scaffold still passes conformance unedited: 19 tests, 0 failures.

    # Finding What it actually was Fix
    1 partial scaffold on collision mix dd.provider.new checked each path as it wrote it, so a collision on the fourth output left the first three behind — and the next run then refuses on the files it wrote itself every path decided and every collision refused before the first File.write!/2; a test collides on the last output and asserts nothing else was written
    2 substring coverage checks the architecture test matched suite source text, so a comment naming a fixture satisfied it both assertions parse each suite and require a real use <case>, fixture:/manifest: with the expected value
    3 schema_version >= 1 asserts nothing about the type — nil >= 1 and "1" >= 1 are both true under Elixir term ordering is_integer(version) and version >= 1
    4 fixed 25-row slice a corpus with fewer than 25 rows would fail Corpus.Conformance on its size the slice is a ceiling: min(@slice, length(rows))
    5 hard-coded corpus namespaces a third corpus kind would raise FunctionClauseError in conformance after doing every registration the generator names namespace joins source and identity in Corpus.Manifest's @kinds, exposed as identity_namespace/1
    6 falsy pacing values for key <- …, value = Map.get(…) drops a falsy value, so request_interval_ms: nil skipped the assertion entirely Map.fetch/2 — absent is the only thing that may be skipped

    Two are worth more than a line.

    #2 was real, and I checked it rather than assuming. I replaced met_conformance_test.exs with a module whose only mention of the fixture was a comment. The old substring check passed it; the new parsed check fails with “MetFixture exists but no suite … runs it through use … fixture: …”. An architecture test whose whole job is to be unfoolable was foolable.

    #5 needed a shared-module change, which is why it is worth recording. identity (the row field a kind is keyed on) and namespace (the external_identifiers namespace the seeder writes it to) genuinely differ — a Wikidata row is keyed on qid and identified as wikidata — so neither derives from the other, and a kind declaring only the first left Corpus.Conformance with a hard-coded list of its own. Corpus.Manifest.@kinds now carries all three and identity_namespace/1 exposes it; the generator's corpus instructions and adding-a-provider.md step 3 ask for all three. Purely additive: no behaviour change, no schema impact.

    I did not act on CodeRabbit's docstring-coverage pre-merge warning (21.88% against an 80% threshold). It counts defps in a mix task and two ExUnit case templates, which cannot take @doc; every public function in the diff has one.

    One thing measured while verifying, worth keeping

    The first mix precommit after these fixes reported 45 failures — Ecto.StaleEntryError, MatchError and query_canceled scattered across Absorb.BatchTest, AccountsTest, WiktionaryIndexTest and other modules this branch never touches. None was a regression: another checkout was running mix test against the same devils_dictionary_test at the same time, and two runs trample each other's sandboxes. The same commit on its own database:

    $ MIX_TEST_PARTITION=p1b mix precommit
    1189 tests, 1 failure
    

    config/test.exs already appends MIX_TEST_PARTITION to the database name and the test alias creates and migrates it. This is the one-node-per-database rule one layer down, and it is now in both documents — 45 failures against 1 is exactly the kind of thing that gets diagnosed as a broken branch.

  8. added a commit that references this issue on Sep 17, 2026
  9. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 1b is on main — 7fb8d6b

    #113 merged as 4bd2cd4, and one leftover commit as #114 / 7fb8d6b.

    Why there were two. #113 was merged at fccdd50, a few minutes before I pushed the last CodeRabbit fix, so 42b947d was stranded on the branch. #114 is that single commit — 3 files, generator input validation only — rather than a push straight to main.

    On merged main, in the primary checkout (which has the data/ dumps):

    $ MIX_TEST_PARTITION=mainp1b mix precommit
    1191 tests, 0 failures
    

    Zero warnings, no environmental failure — the data/ dumps are there, so the sources/manifest_test.exs exception that a worktree always hits does not apply. Clean working tree, main in sync with origin/main.

    What #114 fixed. CodeRabbit's re-review of #113 had no inline findings left, but its residual-risk note said "certain valid-looking slugs cannot coexist as independent generated providers". Measured:

    demo   -> Demo        a-b   -> AB
    demo-  -> Demo        a--b  -> AB
    

    Macro.camelize/1 folds a trailing or doubled hyphen away, so mix dd.provider.new demo- would write four files at paths nobody has used and define the module demo already owns — invisible to the collision check #113 added, because that compares paths and the paths genuinely differ. A slug is now hyphen-separated lowercase alphanumeric words with no leading, trailing or doubled hyphen. poetrydb, open-library, openverse and chronicling-america — K12's and K13's own next sources — are all still accepted, and there is a test that says so.

    Checklist. Phases 1a and 1b are both delivered; I have not ticked them in the issue body, since that is yours to edit.

    Phase 2 is next, and its rule is the point of all this: the agent reads only docs/discovery/*.md, docs/integrations/ and the generator's output. If it has to open this issue or a shared file, that is a finding against Phase 1b and belongs in the PR.

  10. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 2 — PoetryDB, built from the documents. PR #115.

    Branch codex/issue-109-phase2-poetrydb, 20 files, not merged. The Phase 2
    section was read once and then closed; everything after that came from
    docs/discovery/README.md, docs/discovery/adding-a-provider.md,
    docs/integrations/ and what mix dd.provider.new wrote.


    Conformance output, pasted

    The provider suite and the corpus suite:

    $ MIX_TEST_PARTITION=p2poetry mix test \
        test/devils_dictionary/discovery/conformance/poetrydb_conformance_test.exs \
        test/devils_dictionary/artworks/corpus/conformance/poetrydb_corpus_conformance_test.exs
    Running ExUnit with seed: 775286, max_cases: 32
    
    ............................
    Finished in 25.5 seconds (0.00s async, 25.5s sync)
    28 tests, 0 failures
    

    Every suite plus the architecture test:

    $ MIX_TEST_PARTITION=p2poetry mix test \
        test/devils_dictionary/discovery/conformance \
        test/devils_dictionary/artworks/corpus/conformance \
        test/devils_dictionary/discovery/conformance_coverage_test.exs
    Running ExUnit with seed: 228160, max_cases: 32
    
    ..............................................................................................................................
    Finished in 30.9 seconds (0.3s async, 30.5s sync)
    126 tests, 0 failures
    

    The whole suite:

    $ MIX_TEST_PARTITION=p2poetry mix precommit
      1) test the real manifest pins every input, and every digest matches the file on disk (DevilsDictionary.Sources.ManifestTest)
         test/devils_dictionary/sources/manifest_test.exs:25
    Finished in 85.6 seconds (29.3s async, 56.3s sync)
    1221 tests, 1 failure
    

    1,221 tests, 1 failure — manifest_test.exs, the environmental one that
    needs the untracked data/ dumps. Baseline measured on main before any
    change: 1,189 tests, 1 failure, the same file. That is not "green" and is
    not described as green.

    Registering the fifth provider turned 11 tests red, as the guide predicts:
    one environmental, three in providers_test.exs, one in home_live_test.exs,
    one in film_identity_flow_test.exs, five in culture_discovery_live_test.exs.
    Exactly the four named files, no others.


    Ledger — 167 of the 200 ceiling

    Written as the probe ran, running totals, in docs/integrations/poetrydb.md.

    step reqs what total
    P1 1 /author → 129 poets 1
    P2 3 /lines/war with lines → 503 ×3, 15.7–17.1 s 4
    P3 1 /title/Sonnet 1 → never left the process (invalid_request_target). Counted anyway. 5
    P4 4 thunderbolt (25 hits) 503; three others 200 9
    P5 5 field-set bisection; the no-match dialect 14
    P6 3 narrowed queries → lines comes back 17
    P7 129 one /author/<poet>/…,lines each, 300 ms apart → 127 × 200, 2 × 503 146
    P8 2 sizing Byron and Shelley 148
    P9 2 query.wikidata.org/sparql, 127 labels per call 150
    P10 6 fixture capture 156
    P11 1 the miss again 157
    B1 5 /define/war, one run 162
    B2 4 /define/love, one run 166
    B3 1 /define/zyzzyva, one run 167

    167 / 200. B1–B3 are discovery_request_attempts rows for this source —
    what the application actually spent. No image bytes at any point; a poem has
    none. The two SPARQL calls are on this ledger rather than a separate one,
    because the ceiling is on the probe and not on one host.

    Request 3 never reached the network — Req rejected the literal space in the
    path locally. It is on the ledger because a request budgeted is a request
    spent, and hiding it would make the total a different number from the one I
    was working against.


    Browser proof

    Port 4017, one node on devils_dictionary_v2, mix compile to completion
    first. 1280 and 375 CSS px driven over CDP with
    Emulation.setDeviceMetricsOverride — not --window-size, as the checklist
    warns.

    • docs/discovery/issue-109-phase2-war-1280-2026-09-18.jpg
    • docs/discovery/issue-109-phase2-war-375-2026-09-18.jpg
    • docs/discovery/issue-109-phase2-love-1280-2026-09-18.jpg
    • docs/discovery/issue-109-phase2-love-375-2026-09-18.jpg

    What they show: a Texts shelf bylined PoetryDB · attested lines, with
    no image slot — title, Year unknown · Text, the poet, a Source link.
    Every item names its line:

    Ode in Memory of the American Volunteers Fallen for France: Uses “war” at line 16.
    Paris: Uses “war” at line 118.
    Ode on St Cecilia's Day,: Uses “war” at line 35.
    
    I Have A Rendezvous With Death: Uses “love” at line 19.
    Fragments: Uses “love” at line 14.
    Paris: Uses “love” at line 28.
    … ten in all
    

    The 375 measurement: document.documentElement.scrollWidth === 375 at
    375 on both pages, and === 1280 at 1280. No horizontal page scroll at
    either width, measured in the same emulated viewport the screenshot was taken
    in.

    Two things the browser established that conformance cannot:

    • /define/zyzzyva — run 54 came back succeeded, result_count 0,
      request_count 1, completion_reason: no_results, refresh_after 24 h
      out. PoetryDB's 200-carrying-404 was read as a negative cache, not a
      failure and not a backoff.
    • The live results resolved to poetrydb_poem identities whose ids are the
      ones in the committed manifest — 69b7e022c9c6bc683f2800d6fb99edc6 is
      Ode in Memory of the American Volunteers Fallen for France in both — with
      work_kind: "poem". The provider and the corpus converge on one entity.

    Yield, which is the substring gate doing its job: war kept 3 of 12
    candidates, love kept 10 of 12. 5 and 4 requests respectively.


    Where the documents were wrong or insufficient

    1. Corpus.Conformance cannot run a non-artwork corpus — a shared file outside the permitted list

    The finding. test/support/artworks/corpus_conformance.ex says it is the
    suite "every committed corpus manifest passes". It is not: it is the suite
    every artwork corpus passes. Two of its cases are artwork-shaped:

    • artwork_count/0 counted work_kind == "artwork" as a literal, so for a
      corpus of poems it is always 0 and its idempotence and dry-run assertions
      assert nothing.
    • "a depicted QID reaches the page whose meaning refers to it" asserts
      row, "#{@path} records no depicted QIDs, so nothing could ever match a page" — which a text corpus fails by construction.

    Measured: poetrydb-v1 against the unmodified suite was 8 tests, 2
    failures
    , both of those.

    And conformance_coverage_test.exs requires every committed corpus
    manifest to be run by use DevilsDictionary.Artworks.Corpus.Conformance, manifest: <path> specifically, so a separate poem suite would not satisfy it.
    The two requirements together make the file unavoidable.

    Why I did not work around it. Three non-edits were available and all three
    are worse. Seeding poems as work_kind: "artwork" contradicts the brief and
    is a lie in the data. Writing a parallel suite fails the coverage test.
    Recording a QID on a poem row so the depiction case passes would invent the
    one claim this corpus is built to avoid — a poem does not depict the word it
    uses, and that is the whole attestation rule.

    What I did. Edited it, additively:

    • the work kind is read from Manifest.work_kind(manifest["kind"]), a third
      registration in @kinds beside identity and namespace. That key is in a
      permitted file and belongs there for the reason the other two do: nothing
      outside that table should hold its own list of which corpora are artworks.
    • the depiction case now branches on what the manifest records. A corpus with
      depicted QIDs runs the existing round trip unchanged — the Met and
      Wikidata suites assert exactly what they asserted before. A corpus without
      them must instead assert that it is not an artwork corpus, so an artwork
      corpus that lost its QIDs still fails.
    • a new case, applying to all three: a seeded row is found again through
      Manifest.identity_namespace/1 and carries its kind's work_kind. That is
      the round trip every corpus has.

    All three corpus suites: 27 tests, 0 failures. No assertion removed or
    weakened.

    Suggested fix for Phase 1b: either fold work_kind into @kinds
    permanently (done here) and keep the branch, or split Corpus.Conformance
    into a shared half and an artwork half, and let the coverage test accept
    either. The generator should also print the work_kind registration as a
    third edit it cannot make — it currently names two.

    2. The guide's remedy for a busy port does not address the hazard it names

    §6 says two Oban nodes on one database steal each other's jobs, then says: "If
    something is listening, use another port rather than pointing a second node at
    devils_dictionary_v2"
    . Those are different things. A different port does not
    prevent a second node on the same database; it guarantees one.

    That is exactly the case I hit: a dev server from the main checkout was already
    on 4007 against devils_dictionary_v2, and main has no PoetryDB module at
    all, so a second node would have produced a proof of nothing. devils_dictionary_v2
    is 13 GB and DD_DATABASE needs the data/ dumps that a fresh checkout does
    not have, so a second database was not available either.

    Resolved by stopping the other server, with the user's decision, and running
    one node. Suggested wording: if something is listening on the port, find
    out whether it is on the same database. If it is, that server has to stop —
    another port does not help. If it is on a different database, use another
    port.

    3. covers?/1 has no documented answer for a provider that declines nothing but could

    The checklist's browser step asks to verify that "a page the provider declines
    shows no shelf for it at all, and spends no run"
    . PoetryDB declines nothing —
    the default true is right, because any word can be looked for in a line. So
    that checklist item has no subject here. I verified the nearest true thing
    instead (an unattested word is an empty shelf and a negative cache costing one
    request, run 54 above) and am naming the substitution rather than ticking the
    box.

    4. Smaller

    • adding-a-provider.md §3 says the generator writes docs/integrations/<slug>.md
      as "the ledger template", and §1 says to write the ledger as you go. The
      template's table has no running-total column; the text demands one. I added
      the column. Worth putting in the template.
    • The generator's own mix help uses poetrydb as its worked example with
      exactly the flags this source needs. Pleasant, but it meant the four
      decisions of §2 were pre-made in a doc I was told to derive them from. I
      made them from the probe anyway and they matched.
    • README.md's match-reason table lists :attestation and MatchReason
      already parses "lines" → Uses “war” at line N. Nothing needed writing
      for the reason — K3 had already done it. That is the kit working.

    Every shared file touched, and why

    Permitted, and only these:

    File Why
    lib/devils_dictionary/artworks/corpus/manifest.ex the poetrydb kind in @kinds — the generator's first named edit. Plus work_kind on all three kinds and its accessor; see finding 1.
    lib/devils_dictionary/artworks/corpus/seeder.ex the entry("poetrydb", …) clause with work_kind: "poem" — the generator's second named edit.
    test/devils_dictionary/discovery/providers_test.exs registry list [Artsy, CineGraph, Giphy, Met, Poetrydb]; server_providers() now three; added server_providers(:text) == [Poetrydb] and the third transport/pagination entry. The test's name changed from "two providers … two content types" to "three … three", because it was the name that was wrong.
    test/devils_dictionary_web/live/home_live_test.exs 10 sources → 11. One character and its comment.
    test/devils_dictionary_web/live/culture_discovery_live_test.exs five tests that call Repo.one!(Run) now register the one provider they are about, via a small only/1 helper — the file's own existing idiom (four other tests already do put_env(…, [CineGraph, fixture])). Every assertion kept verbatim.
    test/devils_dictionary_web/live/film_identity_flow_test.exs the same, inline, for the one test.

    Nothing in those files was weakened. The Repo.one!(Run) assertions are
    stronger for being scoped: they now mean "CineGraph's run", where before
    they meant "the only run there is", which was only ever true by accident of
    how many providers shipped.

    Also touched, and the finding above:

    File Why
    test/support/artworks/corpus_conformance.ex finding 1. Not on the permitted list.

    config/config.exs and config/test.exs were edited by the generator; my own
    change there is the :poetrydb endpoint, https://poetrydb.example/api →
    https://poetrydb.org, inside my provider's own stanza.


    Left out, named as left out

    1. Byron and Shelley are not in the corpus. 127 of 129 poets. Their
      /author responses 503 after ~16 s — Don Juan alone is 16,092 lines and
      Shelley's 312 poems total 37,898. Recovering them means splitting by
      linecount bucket, which would cost ~40 of my remaining requests and leave
      a manifest whose provenance is "every poem by these 127 poets, plus some of
      Shelley's". I kept the ceiling and the clean provenance, and named the gap
      in the manifest's selection block and in the integration doc. The brief
      asked for every poem and this is 2,523 of them, not all.
    2. Twelve poets have no author_qid. Three are namesakes the rule cannot
      separate (James Thomson is two poets, 38 sitelinks to 19); nine are names
      PoetryDB spells its own way — Lord Alfred Tennyson, Samuel Coleridge,
      Sir Walter Scott, Henry Wadsworth Longfellow, and five more. I did not
      hand-crosswalk them. Identity is the one rule, and a QID I guessed would be
      the only place in this corpus where a wrong identifier could reach a page.
    3. No mix dd.artworks.seed run against the development database. The
      corpus is committed, checksummed and seeded by the conformance suite (25
      rows, twice, idempotent). Seeding all 2,523 into devils_dictionary_v2 is
      a data change to a shared 13 GB database that Phase 2 does not require, so
      I did not make it.
    4. The Met's dev server was stopped and not restarted. PID 23064, port
      4007, from the main checkout. Stopped with the user's decision so my proof
      would measure my own code; left stopped, as they chose. Both 4007 and 4017
      are free now.
    5. The text card at 375 is cramped. Three columns in a shelf grid sized
      for posters, so poem titles truncate hard ("Ode in Memory o…"). It is
      legible and it is the shared Culture shelf, not anything this provider
      ships — a provider ships zero components. Worth a look when a second text
      provider lands; not fixed here.
    6. Pagination beyond page 1 was not exercised in the browser. Conformance
      drives it (the cursor round trip and the stale-cursor refusal both pass),
      and the Load more control is present on both pages, but I did not click
      it — each click is a real page of requests against a ceiling I wanted to
      keep headroom under.
  11. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 2 (PR #115 @ b3b57d0) and the program verdict — 2026-09-18

    Phase 2 grade: A. Merge it. Program grade ("can the kit absorb more APIs?"): A−, and yes — with one short fix-up session before Phase 3.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,221 tests, 1 failure (the environmental manifest_test.exs:25). Matches the report.
    • devils_dictionary_v2: PoetryDB runs 52 / 53 / 54 = results 5 req → 3, results 4 → 10, no_results 1 → 0 — exactly the report's war, love, zyzzyva; 11 work_kind: "poem" entities from live resolution, 0 seeded (as stated); source row poetrydb present.
    • Manifest poetrydb-v1: 2,523 rows, 127 of 129 poets, 2,317 rows with an author QID over 115 distinct QIDs; the crosswalk rule and the two missing poets (Byron, Shelley: oversized-payload 503s) are recorded in the manifest's own selection block.
    • /define/war screenshot: a Texts shelf, PoetryDB · attested lines, no image slot, each item Uses "war" at line N.
    • Removed assertions: the registry/count updates and the two artwork_count replacements only; the depiction case now branches (artwork corpora must still carry depicted QIDs). Nothing weakened; the scoped Repo.one!(Run) assertions are stronger.

    The acceptance test, scored

    The session built a fourth pipeline provider and a third corpus from docs/discovery/*.md and the generator's output, in one session, spending 167 of 200 requests. Shared files touched: the two corpus registrations and the four counting test files (all permitted) plus one unpermitted file, test/support/artworks/corpus_conformance.ex — and that one is a genuine kit defect, not a workaround: the corpus suite counted work_kind == "artwork" literally and required depicted QIDs, so a corpus of poems failed 2 of 8 by construction. The fix (a work_kind registration in @kinds, a branch on what the manifest records, a new identity round-trip case for every corpus) is the right one and is additive. That is the acceptance test working: the kit was wrong in one place, the documents let the agent find it, and the finding is recorded against Phase 1b.

    Four findings against the documents, all fair: the artwork-shaped corpus suite (above); §6's port advice ("use another port") does not address the hazard it names (a second node on the same database) — the true rule is same database → the other server stops; different database → another port; the covers?/1 browser check has no subject for a provider that declines nothing; the ledger template lacks the running-total column the text demands.

    Provider quality

    The two-stage search (substring /lines/<word> proposes; a word-boundary check on hydrated lines disposes) is the attestation rule done properly — /lines/war returns 1,026 poems of which 201 use war as a word, and the gate kept 3 of 12 on war, 10 of 12 on love. Hydration is narrowed by author, never title, because : ; / are PoetryDB operators and 434 of 2,526 titles contain one. Pacing 1 s and retry gap 5 s are declared as capabilities. A poem's author QID lives on the poem's metadata, deliberately not as the poem's identity.

    Deductions (none blocking)

    1. Byron and Shelley are absent — the API 503s on their collected works after ~16 s. Named in the manifest; recoverable later by linecount buckets for ~40 requests.
    2. Twelve poets have no QID (three true namesakes, nine PoetryDB spellings). Correctly not guessed.
    3. PoetryDB is fragile upstream: 15–17 s responses and 503s on the lines field of /lines/<word> every time. The provider routes around it; the shelf will be slow on first paint for a new word.
    4. The text card at 375 px is cramped in a grid sized for posters — the shared shelf's problem, Phase 3's first text-heavy session should look.
    5. Pagination past page 1 exercised by conformance only.

    What "absorb more APIs" costs now, measured

    Artsy (pre-kit) Met (#102) PoetryDB (from the docs)
    sessions 3 + 2 audits 2 (probe + 2a) + corpus session 1
    lines of source (provider + corpus + fixture + seeder clause) ~3,500 ~1,950 ~800
    shared files edited many 8 2 registrations + 4 counting tests + 1 kit defect
    live requests ≤194 61 + ~3,500 167
    reader components shipped 2 0 0

    Before Phase 3 — one short session, "1c", recommended

    1. Make the four counting tests provider-count-agnostic (assert membership and per-provider runs, not totals) so registering a provider turns 0 tests red instead of 11.
    2. Move the corpus registration (identity, namespace, work_kind, and the entry/3 row mapping) toward data, or at least have the generator print all three edits; today it names two.
    3. Fix §6's port guidance and add the ledger's running-total column to the template; add "one test run per test database".
    4. Optionally recover Byron and Shelley by linecount bucket (≤40 requests).

    Then Phase 3 as planned. Handoff for 1c: "Do Phase 1c of #109" once the section is written.

  12. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 1b finding closed. The Corpus.Conformance gap reported above is
    fixed in #115 (6648c88), as a Phase 1b fix rather than the Phase 2 patch it
    originally shipped as.

    The suite called itself the one every committed corpus passes and was the one
    every artwork corpus passes. The fix is not a branch in the suite — it is
    that "artwork" was an assumption where it should have been a declaration.
    @kinds is already the one place a corpus kind's identity and namespace
    live; it now also carries work_kind and evidence:

    kind work_kind evidence
    met-highlights artwork :depiction
    wikidata-famous artwork :depiction
    poetrydb poem :none

    evidence is what a row of this kind can match a page on — :depiction when
    it records the QIDs of what the work shows, :none when it records identity
    and display facts and nothing a page matches on. The suite reads the kind at
    compile time and emits the depiction round trip only for a corpus that
    declares it, so the Met's and Wikidata's copy of that case is unchanged
    character for character, and a text corpus is never handed a case it could
    only pass by inventing the one claim it exists to avoid.

    A declaration nothing checks is a comment, so a new case holds every corpus to
    its own. Mutation-checked in both directions:

    poetrydb-v1.json declares `evidence: :depiction` and no row carries a QID,
    so nothing in it could ever match a page
    
    met-highlights-v1.json declares `evidence: :none` and 1218 rows carry depicted
    QIDs. Either the manifest is making a claim it should not, or the kind should
    declare `:depiction` and be held to the round trip.
    

    mix dd.provider.new and docs/discovery/adding-a-provider.md now print all
    five @kinds keys instead of three, so the next corpus session does not
    rediscover this. A corpus manifest is also no longer described or refused as
    an "artwork corpus manifest".

    Still open from that report, and not fixed here: the guide's §6 remedy for
    a busy port. It says to use another port when something is listening, which
    does not prevent a second Oban node on the same database — it guarantees one.
    Suggested wording is in the report above; it wants a Phase 1b owner's decision
    rather than another edit from a Phase 2 branch.

    Also in #115, answering CodeRabbit: PoetryDB's two largest poets turned out to
    be unreachable live and not merely absent from the corpus, because the only
    hydration route was the one that 503s for them. A third query axis
    (/lines,author,linecount/<word>;<poet>;<n>, measured at 246–785 ms where the
    two-axis form times out at ~16 s) fixes both that and the result's citable
    locator. Ledger now 172 / 200.

  13. added a commit that references this issue on Sep 18, 2026
  14. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 1c — the fix-ups Phase 2 measured. PR #117, codex/issue-109-phase1c off main @ 2efd89a.

    Baseline measured on this branch before any edit: 1,223 tests, 1 failure
    (test/devils_dictionary/sources/manifest_test.exs:26, the environmental one).
    The audit reported 1,221 and :25; the same commit measures 1,223 and :26
    here. Final: 1,225 tests, 1 failure — the same one. All runs on
    MIX_TEST_PARTITION=p1c.


    Item 1 — the proof, pasted

    Scaffolded into the real config:

    $ mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offset
      created  lib/devils_dictionary/discovery/providers/demo.ex
      created  test/support/discovery/conformance/demo_fixture.ex
      created  test/devils_dictionary/discovery/conformance/demo_conformance_test.exs
      created  docs/integrations/demo.md
      updated  config/config.exs
      updated  config/test.exs
    

    Before the fix, full suite with demo registered:

      1) test the real manifest pins every input, and every digest matches the file on disk (DevilsDictionary.Sources.ManifestTest)
      2) test the page the stats line counts the index, what is defined, and the sources (DevilsDictionaryWeb.HomeLiveTest)
      3) test the pipeline runs three providers, over two transports and three content types (DevilsDictionary.Discovery.ProvidersTest)
      4) test the shipped registry is the configured one, not a literal in the module (DevilsDictionary.Discovery.ProvidersTest)
      5) test registration without the pipeline claim stays legal (DevilsDictionary.Discovery.ProvidersTest)
    1242 tests, 5 failures
    

    After, same scaffold, mix precommit:

    $ MIX_TEST_PARTITION=p1c mix precommit
    ...
      1) test the real manifest pins every input, and every digest matches the file on disk (DevilsDictionary.Sources.ManifestTest)
         test/devils_dictionary/sources/manifest_test.exs:26
    ...
    Finished in 65.6 seconds (30.2s async, 35.3s sync)
    1244 tests, 1 failure
    

    Then demo's four files deleted and config/config.exs / config/test.exs
    reverted with git checkout --; the branch carries no trace of it.

    Where the code disagreed with the brief. The brief names four counting
    test files. Only two were still count-dependent: providers_test.exs (3
    failures) and home_live_test.exs (1). culture_discovery_live_test.exs and
    film_identity_flow_test.exs were already provider-scoped by #115's only/1
    helper — every Repo.one!(Run) in them already means that provider's run.
    The audit's "eleven red" was measured before #115 landed those. I changed
    nothing in either file.

    No assertion was weakened. providers_test.exs now states transport,
    pagination and content type per provider, which also asserts something the
    three ordered lists did not: that each provider is scheduled for its own
    content type and for no other. home_live_test.exs reads the expected source
    count off what the fixture seeded, because that line counts source rows and
    registering a provider seeds one.


    Item 2 — the generator transcript

    The code already printed all five @kinds keys — #115 6648c88 did that as a
    Phase 1b fix, so the brief's "it names two today" is out of date and the brief's
    "all three registrations" is four (identity, namespace, work_kind,
    evidence) plus source. What was missing was the test, and a single list
    for the printout to be derived from.

    Manifest.registration_keys/0 is now read off @kinds, and a kind that
    registers a different set is a compile error in that module. The generator maps
    over it; the count it claims is the number of lines it printed.

    $ mix dd.provider.new demo2 --archetype corpus
    
    next:
      1. make the two registrations below, then mix compile
      2. build the manifest from the probe's rows and commit it
      3. mix test test/devils_dictionary/artworks/corpus/ — add the one-line
         suite `use DevilsDictionary.Artworks.Corpus.Conformance, manifest: ...`,
         which the coverage test requires of every committed manifest
      4. record the probe in docs/integrations/demo2.md — running totals, not a total at the end
    
    docs/discovery/adding-a-provider.md is the whole checklist.
    
    two edits this task cannot make for a corpus:
    
      * add "demo2" to @kinds in
        lib/devils_dictionary/artworks/corpus/manifest.ex, with all 5 of its
        registrations:
          source     the source slug the rows are attributed to
          identity   the row field this kind is keyed on
          namespace  the external_identifiers namespace that field is
                     written to — not always the same as identity
          work_kind  the work_details.work_kind the seeder writes
                     ("artwork", "poem", ...)
          evidence   :depiction when a row records the QIDs of what the work
                     shows and a page can match on them, :none when it
                     records identity and display facts only
        Anything short of all 5 and either a seeded row cannot be read
        back or Corpus.Conformance asks this corpus for a contract it does
        not have.
      * add an `entry("demo2", version, row)` clause to
        lib/devils_dictionary/artworks/corpus/seeder.ex that maps a row onto a
        SourceIdentity.Entry
    

    Two tests in dd_provider_new_test.exs hold the printout to
    Manifest.registration_keys/0, for --archetype corpus and for both.
    Mutation-checked: trimming the printout to the first two keys fails with
    "mix dd.provider.new --archetype corpus does not print the namespace
    registration"
    . mix test test/devils_dictionary/tasks/dd_provider_new_test.exs
    → 19 tests, 0 failures.

    A defect found on the way. The next: block was written for a discovery
    scaffold and printed for both: it told a corpus session to run
    <slug>_conformance_test.exs and to "replace the scaffolded response envelope
    and its stub", none of which --archetype corpus writes. It is archetype-aware
    now.


    Item 3 — §6's port rule

    Replaced with the rule Phase 2 stated. The doc now says to find out which
    database
    the listener is on before touching the port, gives the two commands
    that answer it, and then: same database → that server has to stop, another port
    does not help, because both nodes poll the same oban_jobs table; different
    database → use another port. One test run per test database is stated beside
    it, with the 41-phantom-failure measurement.

    docs/discovery/README.md carried the same advice in shorter form ("If port
    4007 is taken, use another port — never the same database from two nodes").
    Not named in the brief; corrected anyway, because it is the same sentence.


    Item 4 — the ledger template and covers?/1

    Template: a running-total column, one row per batch written when the batch
    finishes, and the note that browser-proof requests belong on the same ledger
    because they are discovery_request_attempts for that source. A test asserts
    the generated ledger carries the column header.

    covers?/1 browser item: it now says a provider that declines nothing has no
    subject here, that the default true is right for a text provider, and names
    the substitution to verify instead — unattested word, empty shelf, run recorded
    no_results, one request, reload spends none.


    Item 5 — the ledger, 40 / 40

    # requests what was asked what came back running total
    C1 2 /author/<poet>/title,linecount for Byron and Shelley never left the process — Req.Finch not started in my script. Counted anyway, the way P3 was 2 / 40
    C2 2 the same two, with :req started 200 in 0.98–1.23 s — Byron 325 poems / 69,650 lines, Shelley 312 / 37,898 4 / 40
    C3 1 /author,linecount/Percy%20Bysshe%20Shelley;4/title,linecount 200 in 736 ms, 18 rows, every one linecount 4 — so linecount matches exactly 5 / 40
    C4 1 query.wikidata.org/sparql, POST, both names in one VALUES block with wikibase:sitelinks 200 in 6.9 s — Shelley one candidate (Q93343, 142 sitelinks); George Gordon, Lord Byron no candidate at all 6 / 40
    C5 34 /author,linecount/<poet>;<n>/title,author,linecount,lines, the 34 largest buckets, 1 s apart 34 × 200, 232–923 ms, no 503 of any kind. 380 poems: Byron 198 of 325, Shelley 182 of 312 40 / 40

    Every C5 bucket returned exactly the number C2's title list predicted — 34 of
    34. No image bytes; there are none.

    poetrydb-v1: 2,523 → 2,903 rows, 127 → 129 poets, 2,317 → 2,499 with an
    author QID
    , checksum 9fa17133…, reloads and re-verifies.

    Provenance, and what the cap bought. Full coverage is one request per
    distinct linecount — 111 for Byron, 108 for Shelley, 219 in all. The cap
    was 40, so this is 380 of their 637 poems and Don Juan is not among them.
    selection.recovery in the manifest lists every bucket taken, the poem
    counts per poet, the method, the measurement that makes a bucket a partition
    rather than a filter, and the sentence "it is a budget ceiling and not an API
    limit" — so what is missing is derivable, not merely admitted.

    Byron carries no QID. The manifest's rule is exact label or alias, P31
    human, P106 poet/writer/author/lyricist, ≥5 sitelinks and ≥3× the runner-up.
    "George Gordon, Lord Byron" is neither a Wikidata label nor an alias of
    anything, so the query returned zero candidates for him. He is the thirteenth
    poet without a QID, by the rule and not by a guess.

    Corpus.Poetrydb.row/3 takes a :source_url — a recovered row records the
    bucket URL it actually came from, because the /author/<poet> route does not
    resolve for these two.


    Item 6 — seeded into devils_dictionary_v2

    run rows matched newly_created would_seed invalid
    --dry-run 2,903 0 0 2,903 0
    first 2,903 11 2,892 0 0
    second 2,903 2,903 0 0 0

    work_kind in work_details, before → after:

    artwork|3212      artwork|3212
    film|95           poem|2903
    poem|11           film|95
    dictionary|2      dictionary|2
    

    2,903 = the manifest's row count. The 11 were the poems live resolution had
    already minted in Phase 2; they matched rather than duplicating, which is the
    identity claim of #115 holding.


    Every place the code disagreed with the brief

    1. "The four counting tests" — two of them, not four. Phase 2 of #109: PoetryDB, built from the documents #115 already scoped
      the other two. Measured: 4 real failures, in providers_test.exs and
      home_live_test.exs.
    2. "The generator names two registrations today" — it named all five, since
      Phase 2 of #109: PoetryDB, built from the documents #115 6648c88. The gap was the test, and a single list to derive the
      printout from.
    3. "All three registrations" — @kinds holds five keys, four of them
      registrations plus source. The printout and its test are keyed on
      Manifest.registration_keys/0 so the number stops being a literal anywhere.
    4. Baseline — 1,223 tests and manifest_test.exs:26, where the audit says
      1,221 and :25. Same commit, same environmental failure.
    5. The README's development section does not run as written —
      mix dd.health and mix dd.score both refuse without --scope
      ("there is no default population", Remove Animals prototype coupling: make the encyclopedia subject-independent #77 §2). Fixed in the README; both run
      with --scope animals.

    Anything left out

    1. 257 of Byron's and Shelley's 637 poems. The 40-request cap buys 34 of
      the 219 buckets. Listed above; derivable from the manifest.
    2. mix setup, gh repo clone, the mix dd.absorb / dd.scope.build /
      dd.link / dd.resolve / dd.snapshot / dd.materialize --all lines of
      the README's development section were not executed.
      They re-import the
      corpus into a shared 13 GB database over hours and need the untracked
      data/ dumps; mix setup writes seeds and a dev user. I verified every
      task exists and every flag in every line is in that task's own
      OptionParser switches, and ran what is read-only or idempotent:
      mise install, mix deps.get, mix compile, mix ecto.migrate
      (Migrations already up), mix dd.materialize --dry-run (120,564 records,
      0 gaps), mix dd.health --scope animals, mix dd.score --scope animals
      (39/43 rows pass — pre-existing, nothing I touched), and
      mix compile && mix phx.server (HTTP 200 from http://localhost:4007/,
      then stopped). Every command in adding-a-provider.md was run as written,
      including the psql -tAc line I added and PORT=4017 mix phx.server's
      mix compile half.
    3. No browser proof. Nothing this session changes is visible in the reader,
      and the brief did not ask for one. The seeded corpus half is not yet on a
      page — a corpus row declaring evidence: :none reaches a reader through the
      live provider, not through Artworks.shelf_items/1, so 2,903 seeded poems
      change no shelf. Worth naming as a thing Phase 3 or Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101 may want.
    4. Three BEAM VMs were stopped and left stopped, per the ground rule: the
      dev server on 4007 from the main checkout (PID 12320, started 10:19 today)
      and two stale Artsy processes from 2026-09-12 (PIDs 83951, 90470). All three
      held connections to devils_dictionary_v2. Port 4007 and the database are
      both free now.
    5. mix dd.materialize --all not run. The dry run reports 0 gaps, so it
      would be a full rebuild of 120,564 derived records for no change.

    Verification order as briefed, all green: item 1's proof, the generator
    transcript, the checklist's commands, the two seed runs, and
    MIX_TEST_PARTITION=p1c mix precommit → 1,225 tests, 1 failure
    (manifest_test.exs:26).

  15. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 1c (PR #117 @ c860bf9) — 2026-09-18

    Grade: A. Merge it. Phase 3 may start from its merge.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,225 tests, 1 failure — the environmental manifest_test.exs only. Matches the report.
    • Item 1, reproduced independently: scaffolded demo with the generator into the real config, mix compile, full mix test → 1,244 tests, 1 failure, the environmental one. Registering a provider now turns zero tests red, down from eleven on 2026-09-18 morning. Reverted cleanly.
    • Item 6 in devils_dictionary_v2: work_details reads artwork 3,212 · poem 2,903 · film 95 · dictionary 2; 2,903 poetrydb_poem identities = the manifest's row count; the 11 poems Phase 2's live runs had minted matched rather than duplicated.
    • Manifest poetrydb-v1: 2,903 rows, 129 poets, 2,499 with an author QID; Byron 198, Shelley 182 recovered by linecount bucket on exactly the 40-request cap, with selection.recovery listing every bucket taken and the 257 not recovered — derivable, not merely admitted.
    • The rewritten counting tests are stronger, not weaker: providers_test.exs asserts each provider is scheduled for its own content type and for no other; home_live_test.exs reads the source count off what the fixture seeded. The other two files the brief named were already scoped by Phase 2 of #109: PoetryDB, built from the documents #115, correctly left alone.
    • §6 now reads as Phase 2 stated it — find out which database the listener is on; same database → that server stops, a different port does not help; different database → another port — with the one-test-run-per-test-database rule and the psql line beside it.

    Deviations, all correct

    Two counting files not four (#115 had scoped the others); the generator already printed every @kinds key since 6648c88, so the gap was the test and a single source of truth (Manifest.registration_keys/0, now mutation-checked); @kinds carries five keys, not three; the README's development section did not run as written (dd.health/dd.score refuse without --scope) and is fixed. A defect found on the way — the generator's next: block was discovery-shaped for both archetypes — is fixed and archetype-aware.

    Deductions (none blocking)

    • 257 of Byron's and Shelley's 637 poems remain unrecovered, including Don Juan; the manifest says exactly which buckets would fetch them (219 requests for full coverage).
    • Byron has no QID because "George Gordon, Lord Byron" is not a Wikidata label or alias; thirteen poets without one now. Correct by the rule; a hand crosswalk table is a Phase 3 nicety.
    • The seeded poem corpus reaches no page: a corpus row with evidence: :none has no shelf path except through the live provider, so 2,903 seeded poems change nothing a reader sees. Not a 1c defect — the corpus half exists for identity and /artworks-style browse — but worth deciding whether attestation can be answered from the local corpus (it can: the lines are hashed, not stored, so today it cannot; storing lines is a data-retention decision). Recorded for Phase 3 / Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101.

    Where the kit stands after 1c

    Adding a provider: one generator run, one fixture, one config line, zero shared-test edits. Adding a corpus: the generator prints the five registrations and the row-mapping clause it cannot write. Both documents run as written. Phase 3's first source should be the shape the kit has not yet proven — GraphQL or cursor paging, or corpus-only — so Open Library first if it is either.

  16. 1 remaining item

  17. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Coordination with #116 (2026-09-18). #116 was written at 2efd89a, before Phase 3 here was rewritten, and it takes Openverse as the first Photos source under an honest kind: :query reason (M6) while Phase 3a here makes Wikimedia Commons the identity-bearing one. Both stand: #116 owns the :image shelf and its multi-source rules; 3a is that shelf's identity-bearing provider. 3a now declares :image (section edited), lands first, then #116 Phase 1 reshapes the shelf. If the in-flight 3a session already declared :artwork, #116 Phase 1 retypes it — one line. Order: 3a → #116 Phase 1 → (#116 Phase 2 Openverse ∥ 3b Chronicling America) → 3c Open Library → #116 Phase 3. #116 Phase 0 (probe, no code) may run at any time, including now.

  18. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 3a report — Wikimedia Commons by depicts identity, and Artsy's client retired

    PR: #119 (branch codex/issue-109-phase3a-commons off main @ 4207b8a, three commits, 32 files, not merged). Read the Phase 3 section once for the defaults and the K13 amendment, then worked from docs/discovery/README.md, docs/discovery/adding-a-provider.md, docs/integrations/ and the generator's output. "Close the issue" I read as stop reading it: 3b and 3c are still on this tracker, so the GitHub issue stays open.

    Conformance output

    MIX_TEST_PARTITION=p3a mix test test/devils_dictionary/discovery/conformance/commons_conformance_test.exs --trace:

    DevilsDictionary.Discovery.Conformance.CommonsConformanceTest [test/devils_dictionary/discovery/conformance/commons_conformance_test.exs]
      * test commons \x{2014} the contract pacing declarations, where present, are non-negative milliseconds [L#2]
      * test commons \x{2014} the contract pacing declarations, where present, are non-negative milliseconds [L#2]
      * test commons \x{2014} identity a discovery appearance never writes an illustrates claim [L#2]
      * test commons \x{2014} identity a discovery appearance never writes an illustrates claim [L#2]
      * test commons \x{2014} the reader every result carries a reason that renders as one sentence [L#2]
      * test commons \x{2014} the reader every result carries a reason that renders as one sentence [L#2]
      * test commons \x{2014} admission a target the provider declines never becomes a run [L#2]
      * test commons \x{2014} admission a target the provider declines never becomes a run [L#2]
      * test commons \x{2014} the contract declares capabilities the shared pipeline can branch on [L#2]
      * test commons \x{2014} the contract declares capabilities the shared pipeline can branch on [L#2]
      * test commons \x{2014} identity every persisted result says what identity it resolved to, or why not [L#2]
      * test commons \x{2014} identity every persisted result says what identity it resolved to, or why not [L#2]
      * test commons \x{2014} admission admits one run for a covered target and joins the one in flight [L#2]
      * test commons \x{2014} admission admits one run for a covered target and joins the one in flight [L#2]
      * test commons \x{2014} the contract names one identity the registry and the source catalog share [L#2]
      * test commons \x{2014} the contract names one identity the registry and the source catalog share [L#2]
      * test commons \x{2014} admission an unregistered provider slug is not admitted [L#2]
      * test commons \x{2014} admission an unregistered provider slug is not admitted [L#2]
      * test commons \x{2014} the contract a module the pipeline is told it can drive exports everything it drives [L#2]
      * test commons \x{2014} the contract a module the pipeline is told it can drive exports everything it drives [L#2]
      * test commons \x{2014} cleanup an abandoned run is recovered and completes on the next attempt [L#2]
      * test commons \x{2014} cleanup an abandoned run is recovered and completes on the next attempt [L#2]
      * test commons \x{2014} cache an empty answer is a negative cache, not a failure [L#2]
      * test commons \x{2014} cache an empty answer is a negative cache, not a failure [L#2]
      * test commons \x{2014} the contract declares only content types the reader can present [L#2]
      * test commons \x{2014} the contract declares only content types the reader can present [L#2]
      * test commons \x{2014} the reader renders through Culture.section on its content type's shelf [L#2]
      * test commons \x{2014} the reader renders through Culture.section on its content type's shelf [L#2]
      * test commons \x{2014} the contract shelf_detail is one short qualifier or nothing at all [L#2]
      * test commons \x{2014} the contract shelf_detail is one short qualifier or nothing at all [L#2]
      * test commons \x{2014} budget an exhausted rolling budget defers the run and retains what is shown [L#2]
      * test commons \x{2014} budget an exhausted rolling budget defers the run and retains what is shown [L#2]
      * test commons \x{2014} pagination hands back a cursor and the next page appends to the first [L#2]
      * test commons \x{2014} pagination hands back a cursor and the next page appends to the first [L#2]
      * test commons \x{2014} pagination a stale cursor is refused rather than paged from [L#2]
      * test commons \x{2014} pagination a stale cursor is refused rather than paged from [L#2]
      * test commons \x{2014} cache a positive answer is cached and not asked for twice [L#2]
      * test commons \x{2014} cache a positive answer is cached and not asked for twice [L#2]
    Finished in 1.6 seconds (0.00s async, 1.6s sync)
    19 tests, 0 failures
    

    Every provider and corpus suite plus the architecture test (test/devils_dictionary/discovery/conformance test/devils_dictionary/artworks/corpus/conformance test/devils_dictionary/discovery/conformance_coverage_test.exs, with the Commons unit test): 160 tests, 0 failures. Artsy's registry-only profile and the coverage test are in that set and green after the client's deletion.

    MIX_TEST_PARTITION=p3a mix precommit on the final tree: 1,217 tests, 1 failure — test/devils_dictionary/sources/manifest_test.exs, the environmental one. Baseline on main before any change: 1,225 tests, 1 failure (the same). The 41-test difference is the deleted Artsy client, availability and importer suites, net of the 33 tests this phase added.

    Ledger — 90 of 300

    Written as it ran into docs/integrations/commons.md; browser-proof rows included. Requests 82–90 were spent by the running application, and discovery_request_attempts for commons reads 4 on the dev database, which is B7 + B9 (the two deleted runs' attempts went with their runs, and are on the ledger as B5 and B6).

    # requests what was asked what came back running total
    A1 1 list=search haswbstatement:P180=Q4991371, ns 6, limit 5 200 in 590 ms — 8852 total hits; continue = `{"continue":"-
    A2 1 the same search as generator=search with prop=imageinfo (url, extmetadata, iiurlwidth=640) 200 in 476 ms — 5 pages with thumbnail URL and extmetadata licence in one answer; continue = `{"continue":"gsroffset
    A3 1 `wbgetentities ids=M6659002 M7887852 M8841536
    A4 3 `haswbstatement:P180=Q144 P180=Q25324, then Q144alone, thenQ25324` alone 200/200/200 in 212/537/206 ms — 26220 hits for the OR, 26131 for dog, 115 for Canidae
    A5 1 haswbstatement:P180=Q4991371 filetype:bitmap 200 in 487 ms — 8840 hits (A1 had 8852 without the filter) 7 / 300
    A6 1 the same search with maxlag=-1, to see the lag refusal 200 in 237 ms — body {"error":{"code":"maxlag","docref":"See https://commons.wikimedia.org/w/api.php for API usage. Subscribe to the mediawiki-api-announce mailing list at &lt;https://lists.wikimedia.org/postorius/lists/mediawiki-api-announce.lists.wikimedia.org/&gt; for notice of API deprecations and breaking changes.","host":"10.64.16.149","info":"Waiting for 10.64.16.149: 0.445356 seconds lagged.","lag":0.445356,"type":"db"},"servedby":"mw-api-ext.eqiad.main-77d9d4c448-9vthq"}; Retry-After: ["5"] 8 / 300
    A7 1 page 2 of A2 by handing back its continue (gsroffset=5, `continue=gsroffset `)
    A8 1 haswbstatement:P180=Q262026 (andiron), the empty case 200 in 411 ms — body `{"batchcomplete":true,"continue":{"continue":"gsroffset
    B1 2 haswbstatement:P180=Q4115189 (the Wikidata sandbox item) as generator=search and as list=search 200/200 in 480/244 ms — not the empty case: five test uploads depict the sandbox item (a keyboard, a logo, a roundabout, a video/webm, a park), so the window has to gate on mime as well as on licence. Written wrongly at first as "no query key"; corrected after reading the body 12 / 300
    B2 1 `wbgetentities ids=M116369 M1 M999999999999`: a real file, a very early page id, an id that cannot exist
    B3 30 15 pages of soldier, each a generator=search (limit 10) then a wbgetentities of its ten M-ids, 1 s apart 15 of 15 pairs clean; latency 308–2449 ms, mean 615 ms; statuses [200]; errors [nil]; Retry-After [nil] 43 / 300
    B4 30 15 more pages the same way, 250 ms apart 15 of 15 pairs clean; latency 284–1746 ms, mean 495 ms; statuses [200]; errors [nil]; Retry-After [nil] 73 / 300
    C1 2 haswbstatement:P180=Q999999999999 filetype:bitmap as generator and as list 200/200 in 492/312 ms — generator body {"batchcomplete":true}; list body {"batchcomplete":true,"query":{"search":[],"searchinfo":{"totalhits":0}}} 75 / 300
    C2 1 soldier, gsrlimit=12, gsrsort=incoming_links_desc 200 in 542 ms — 12 files: File:Cheshire Regiment trench Somme 1916.jpg, File:David - Napoleon crossing the Alps - Malmaison1.jpg, File:Ulysses S. Grant from West Point to Appomattox.jpg, File:Steeplechase2.jpg, File:After the war a medal and maybe a job2.jpg, File:Polish Army Kołobrzeg 077.JPG, File:Into the Jaws of Death 23-0455M edit.jpg, File:Thure de Thulstrup - L. Prang and Co. - Battle of Gettysburg - Restoration by Adam Cuerden.jpg, File:ANA soldier with RPG-7 in 2013-cropped.jpg, File:Escolta presidencial, Plaza de Armas, Lima, Perú, 2015-07-28, DD 40.JPG, File:Yevgene Petrakov's film roll, 1960 04.jpg, File:Stamp of Ukraine s1985.jpg; licences %{"Attribution" => 1, "CC BY-SA 4.0" => 2, "Public domain" => 9} 76 / 300
    C3 2 soldier, gsrlimit=12, default sort, then wbgetentities for the twelve 200/200 in 618/363 ms — 12 files, 12 of 12 carry P180=Q4991371 in their statements; licences %{"Attribution" => 2, "CC BY-SA 3.0" => 1, "CC BY-SA 4.0" => 1, "Public domain" => 8} 78 / 300
    C4 2 dog: the five QIDs /define/dog refers to OR'd in one haswbstatement, gsrlimit=12, links-desc, then wbgetentities 200/200 in 747/468 ms — 12 files, 12 of 12 carry one of the five QIDs; licences %{"CC BY 2.0" => 1, "CC BY-SA 2.5" => 1, "CC BY-SA 3.0" => 4, "CC0" => 1, "Public domain" => 5} 80 / 300
    C5 1 wbgetentities ids=M116369 alone 200 in 183 ms — [{"M116369", ["statements"], ["P1163", "P180", "P2048", "P2049", "P3575", "P4092", "P571", "P6216", "P6731"]}] 81 / 300
    B5 2 browser proof, first visit to /define/soldier on port 4007, one node on devils_dictionary_v2: one search, one wbgetentities 12 proposed, 11 kept, 1 dropped by the licence gate (the Attribution Polish Army photograph); every item reasoned Direct depiction of “soldier” (Q4991371). Three titles carried hidden QuickStatements text out of ObjectName — fixed in the provider (hidden blocks dropped, description blocks yield to the file name), the run deleted and the three entity labels corrected by hand in the dev database, so the page is visited again below 83 / 300
    D1 1 prop=imageinfo for pageids 283006 and 8715577: the raw ObjectName HTML behind the two titles the first browser proof got wrong 200 in 446 ms — see Measured facts 9: the multi-language title block is <div class="description">/<span class="language">-free; it is nested <div style="display:inline-block"> blocks with <b>French:</b> labels 84 / 300
    B6 2 browser proof, /define/soldier again on the fixed provider 11 kept of 12 again; the hidden blocks were gone but Napoleon crossing the Alps still rendered as its French-then-English title block, because that block has no language class — D1 fetched the raw HTML, the rule became take the lang="en" element, and this run too was deleted and the one label corrected by hand before the third visit below 86 / 300
    B7 2 browser proof, /define/soldier, third visit, port 4007, one node on devils_dictionary_v2, 1280 CSS px 12 proposed, 11 kept (the Attribution file dropped), every item Direct depiction of “soldier” (Q4991371), titles clean; scrollWidth === 1280; no console errors 88 / 300
    B8 0 /define/soldier at 375 CSS px over CDP (Emulation.setDeviceMetricsOverride) the positive cache answered: no request; scrollWidth === 375; 11 items 88 / 300
    B9 2 /define/dog at 1280: the five QIDs /define/dog refers to, OR'd 12 proposed, 12 kept, every one Direct depiction of “dog” (Q144); scrollWidth === 1280; no console errors 90 / 300
    B10 0 /define/dog at 375 cached; scrollWidth === 375; 12 items 90 / 300
    B11 0 /define/zyzzyva at 1280 — a page with no refers_to claim no Images shelf, no Commons run, no request: covers?/1 declined it before admission. discovery_request_attempts for commons reads 4 after the four proofs, which is B7 + B9 90 / 300

    No image bytes were fetched by the probe or the server at any point; the browser fetched thumbnails to render the shelf, which is the ordinary display path.

    Browser proof

    Port 4007, the only node on devils_dictionary_v2, mix compile to completion first, headless Chrome over CDP with Emulation.setDeviceMetricsOverride (375 × 812 at scale 2, mobile). Each screenshot is a clip from the Images shelf through the Commons About these results list, open, so the reasons are legible. Every section of each page was read off the DOM as well: on /define/soldier the seven definition cards, the Artworks shelf (The Met and the saved catalog, 24 items), the Images shelf (Wikimedia Commons · depicts: Wikidata, 11 items, every one Direct depiction of “soldier” (Q4991371)), the Texts shelf (PoetryDB, 9), both related-words sections and the thing card; on /define/dog nine definition cards, the catalog-only Artworks shelf (12), the Images shelf (12 items, every one Direct depiction of “dog” (Q144)), Texts (1), four related-words sections and the thing card. No [role=status] left pending, no console errors, document.documentElement.scrollWidth === 375 at 375 and === 1280 at 1280 on both pages.

    The decline case: /define/zyzzyva has no refers_to claim, shows no Images shelf, admitted no Commons run and spent no request.

    issue-109-phase3a-soldier-1280-2026-09-18.jpg
    issue-109-phase3a-soldier-375-2026-09-18.jpg
    issue-109-phase3a-dog-1280-2026-09-18.jpg
    issue-109-phase3a-dog-375-2026-09-18.jpg

    Where the documents were wrong or insufficient

    1. The ceiling. adding-a-provider.md §1 and the generator's ledger template both say 200; the Phase 3 section says 300. I used 300 and the ledger says so. The guide should say the ceiling is per phase, set in the tracker.
    2. "The same evidence read the Met uses" was private to the Met. The Phase 3a brief says Commons matches on the QIDs a sense refers_to, "the same evidence read the Met uses", but that read was two private functions in met.ex. A second provider had to copy them or the kit had to share them. I extracted DevilsDictionary.Discovery.PageEvidence (any?/1, entities/2, digest/1, valid_entities?/1) and made the Met delegate; its behaviour and fixture are unchanged. The guide's quick reference should name it beside the provider contract.
    3. MatchReason.from_result/2 knew tags, keywords and lines, and not depictions, while from_candidate/1 did. A live P180 statement is a depiction; rendering it as a tag would have been a lie about the mechanism. One more reader ("depicts") and the README's list of keys.
    4. The content-type decision the issue deferred to the session. A US Army photograph on a shelf headed Artworks with an Artwork badge misnames what it shows, so :image is the fifth row (heading Images, badge Image, square, after artworks). The README says adding a type is "an entry here and nothing else"; that is almost true — test/devils_dictionary/tasks/dd_provider_new_test.exs asserts the refusal message with the literal list film, artwork, text, gif and went red. It is the same shape §5 warns about ("it is counting again, which is a finding against this checklist"), one level down. I updated the literal to name five; the assertion is unchanged in strength.
    5. The README's status table had no PoetryDB row after Phases 2 and 1c. Added, with the Commons row.
    6. The lag refusal is HTTP 200. The README's transport section says a Retry-After header is honoured at full length and written to the source; MediaWiki sends that header with a 200 body carrying error.code == "maxlag", so Transport.classify/6 never sees it. The provider reads the body and returns {:deferred, "maxlag", ≥5, request}. Worth a sentence in the README so the next MediaWiki provider does not discover it.
    7. The generator's scaffold names the namespace <slug>_item; the issue names commons_file. Changed by hand, as expected, but the generator could take --namespace.
    8. A matched identity keeps its existing label. SourceIdentity.enrich_entity/2 prefers the stored preferred_label for a typed entity, so when the first browser proof wrote three titles with hidden QuickStatements text into the registry, fixing the provider did not fix the rows: I deleted the run and corrected the three labels by hand on the dev database (ledger B5, B6). Nothing in the guide says what to do when a browser proof writes bad data through an identity adapter; it should, and the honest answer may be "delete the run and the entities it created".
    9. The retirement brief named three modules and a page branch; the code had more on the client. Artworks.Seeder (the Wikidata-to-Artsy importer), the import stage of mix dd.artworks.seed, Artworks.withdraw_artsy/1's coordinator call, the RequestCoordinator child in Application, and the client keys in config :devils_dictionary, :artsy all depended on the deleted modules. All went or were trimmed; docs/integrations/artsy.md lists each. The --build and --wikidata-only stages of the seed task, which only ever spoke to Wikidata, stay.
    10. The 375 px screenshot recipe in docs/mobile/README.md is right and adding-a-provider.md §6 points at it only obliquely; two things it does not say: lazy thumbnails stay grey unless the shelf is scrolled into view before capture, and a full-page capture with every <details> open is 30,000 px tall and proves nothing anyone can read. The four proofs here are clips around the shelf.

    Shared files touched, and why

    • lib/devils_dictionary/discovery/page_evidence.ex (new), lib/devils_dictionary/discovery/providers/met.ex — finding 2.
    • lib/devils_dictionary/discovery/content_types.ex — finding 4.
    • lib/devils_dictionary/discovery/match_reason.ex, test/devils_dictionary/discovery/match_reason_test.exs — finding 3.
    • test/devils_dictionary/discovery/providers_test.exs — a {Commons, :image, :cursor} row in the per-provider table and :image in its "other types" list; the test's own comment asks for this when a fourth pipeline provider joins.
    • test/devils_dictionary/tasks/dd_provider_new_test.exs — finding 4.
    • docs/discovery/README.md — the one-rule table, the content-type table, the coverage paragraph, the reason keys, the status table (finding 5).
    • config/config.exs, config/test.exs — the generator's stanzas made real (endpoint, no pacing in the suite); the Artsy stanza trimmed to enabled.
    • The Artsy retirement: lib/devils_dictionary/application.ex, lib/devils_dictionary/artworks.ex (one line), lib/devils_dictionary_web/live/artwork_live.ex, lib/mix/tasks/dd.artworks.seed.ex, test/devils_dictionary_web/live/artwork_live_test.exs (the "provider unconfigured" case now asserts the form is gone), docs/integrations/artsy.md; deleted lib/devils_dictionary/artsy/*, lib/devils_dictionary/artworks/seeder.ex and their tests.

    Decisions made in the session

    • :image, not :artwork (finding 4). Identity work_kind: "image".
    • Attribution rides in the card's creator line as author · licence (e.g. Diego Delso · CC BY-SA 4.0), because the shared card has no licence slot and a CC licence asks for attribution wherever the thumbnail is shown. license, license_url, author and a credit_line are also recorded on the item and the identity.
    • gsrsort=incoming_links_desc: a pure filter query has no relevance of its own, and how widely a file is used is the one quality signal the search offers (C2: the Somme trench photograph and David's Napoleon first).
    • Pacing 1 s, retry gap 5 s, maxlag=5: measured as unnecessary at 250 ms (B3, B4) and shipped as courtesy; both overridable in config.
    • The page window is result_limit (12), so a page is exactly two requests and nothing proposed is thrown away by a take.

    Left out, named

    • No broader walk, as the brief says: equal QID or nothing. /define/soldier is one QID; /define/dog is five, OR'd.
    • The seeder test that first seeded through the client (withdrawal succeeds after a seeded creator citation) went with the importer; withdraw_artsy/1 is still covered by artwork_live_test.exs.
    • A commons corpus — none; the archetype is discovery only.
    • Not verified live: a real maxlag refusal under load (only the forced maxlag=-1, A6) and a real 429; both are unit-tested against the measured shapes.
    • Observed, not mine: /define/dog's shelves say matches for “'dog” — the page's term carries a leading apostrophe from whichever lexeme the page opens on. Pre-existing; noted for whoever owns WordPage.
  19. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 3a (PR #119 @ 9085b0b) — 2026-09-18

    Grade: A. Merge it. The cursor shape is proven, the licence gate is on the hydrated file, and Artsy's client is gone in its own commit with the pilot intact.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,217 tests, 1 failure — the environmental manifest_test.exs only. Matches the report (the drop from 1,225 is the deleted Artsy suites net of 33 new tests).
    • devils_dictionary_v2: Commons runs 59 (soldier: 2 requests → 11 kept) and 60 (dog: 2 → 12), both with a MediaWiki continue object as next_cursor; 4 request attempts on record, as stated; 23 commons_file identities = 23 work_kind: "image" entities. Sample rows carry title, licence and author · licence as the creator line (John Warwick Brooke · Public domain).
    • The Artsy pilot survived the retirement: 9 artsy_artwork_slug identities and 7 enabled gene mappings, unchanged. Every removed assertion in the diff belongs to the deleted client, availability and importer suites. docs/integrations/artsy.md opens with what was removed and why.
    • /define/soldier screenshot: an Images shelf, Wikimedia Commons · depicts: Wikidata, attribution beneath every thumbnail, every reason Direct depiction of "soldier" (Q4991371).
    • Provider: one CirrusSearch clause per page QID (haswbstatement:P180=Q1|P180=Q2 filetype:bitmap), generator=search + prop=imageinfo so licence and thumbnail arrive in one answer, gate on extmetadata.License with LicenseShortName fallback and mime image/*, maxlag=5 on every request with the HTTP-200 lag refusal read from the body and returned as {:deferred, "maxlag", ≥5}, pacing 1 s / retry gap 5 s as capabilities.

    The ten findings against the documents — all fair, three matter

    • PageEvidence extracted from the Met's private functions so a second identity provider did not copy them. Correct, and the Met's conformance is unchanged. The guide's quick reference should name it.
    • MatchReason.from_result/2 did not know depictions (only from_candidate/1 did). A live P180 statement rendered as a tag would have misnamed the mechanism. Fixed with one reader.
    • A lag refusal is a 200. The README's transport section assumed Retry-After arrives on a non-200; MediaWiki sends it with a 200 body. The next MediaWiki provider needs that sentence.
    • Also right: :image as the fifth row (a US Army photograph under Artworks misnames it), the generator test's literal type list (one level down from §5's own warning), the ceiling stated as per-phase, --namespace for the generator, and the honest note that a browser proof can write bad data through an identity adapter and the guide does not say what to do.

    Deductions (none blocking)

    1. /define/dog opens on the lexeme 'dog (object 1547258, an apostrophe-led Wiktionary row), so its shelves read matches for "'dog". K4 picks "the lexeme the page opens on" and WordPage's ranking puts that row first among nouns. Pre-existing and correctly reported as not the session's, but it is a real defect in the K4 rule's input: ranking within a part of speech should prefer the bare lemma — a one-line fix in WordPage for whoever runs 3b.
    2. gsrsort=incoming_links_desc is a good default and is undocumented in the README's provider table; the ranking-within-a-shelf question remains Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101's.
    3. The retirement went wider than the brief named (the 1,090-line Artsy importer, the seed task's import stage, the coordinator child in Application, the client keys in config). All of it depended on the deleted client and all of it is listed in artsy.md; the wider cut was right.

    For 3b

    Baseline after merge; fix the 'dog ranking first (it will show on every apostrophe-led lemma); the cramped 375 px text card is 3b's shared change as planned.

  20. added a commit that references this issue on Sep 18, 2026
  21. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 3b — report

    PR #120. Branch
    codex/issue-109-phase3b-chronam off main at dddc632 (3a merged, baseline
    confirmed before starting). 19 files. Not merged.

    Chronicling America was not built. The two shared changes 3b owns landed in
    full, the three guide edits landed, and the probe stopped at 14 requests of 300
    because the source is unreachable. Details below, failures reported as failures.


    The blocker

    Every Library of Congress endpoint answers a scripted client with a Cloudflare
    "Just a moment…" bot-verification interstitial carrying HTTP 403.
    chroniclingamerica.loc.gov 308-redirects to www.loc.gov/chroniclingamerica/,
    and that host is gated.

    This is not a rate limit: it was the first request on a cold connection, it
    applies to the LoC's own /apis/ documentation page and to www.loc.gov/
    itself, and it did not clear on retest. It is not specific to Req either — the
    same URL in a real browser (a genuine Chromium, normal user agent) sat on
    "Performing security verification" and had still not cleared after ten
    seconds
    .

    Getting past it would mean defeating bot detection — spoofing a browser
    fingerprint, solving the JS challenge, or driving a browser to harvest a
    clearance cookie for a scripted client. I did not do that.

    The ledger — 14 / 300

    # Request Result
    1 legacy search/pages/results?andtext=war&format=json 308 → www.loc.gov/chroniclingamerica/…
    2 the redirect target 403 Cloudflare interstitial
    3 collections/chronicling-america/?q=war&fo=json 403
    4 www.loc.gov/search/?q=war&fo=json 403
    5 legacy search, following redirects 403
    6 lccn/sn83045462/1918-11-11/ed-1/seq-1/ocr.txt 403 — the hydration path attestation needs
    7 …/seq-1.json 403
    8 www.loc.gov/item/sn83045462/?fo=json 403
    9 www.loc.gov/apis/ — LoC's own API docs 403
    10 chroniclingamerica.loc.gov/data/ocr/ 200 — a 418 KB index of bulk OCR tarballs
    11 newspapers.json 403
    12 tile.loc.gov/storage-services/… 403
    13 search retested (transient?) 403
    14 www.loc.gov/ 403

    No page images fetched, nothing stored. The one endpoint that answered is a
    static directory of multi-gigabyte tarballs — not an API, and not something a
    live discovery provider can be built on.

    Why that ended the phase rather than delayed it

    Requests 2 and 6 are exactly the two halves of 3b's match rule — the search
    proposes, the hydrated OCR disposes — and both are gated. Without them there is
    no measured rate, no real captured response for the fixture's respond/1 (§4
    requires one), and no honest reason naming a paper, a date and a page.

    A scaffolded provider would have passed conformance; §4 says it "passes
    conformance as generated, which proves the wiring and nothing about the source."
    Registering one would have put a green suite and a source row behind a source
    this session never once reached — the failure §8 names. So I did not.


    Conformance output, pasted

    $ MIX_TEST_PARTITION=p3b mix test test/devils_dictionary/discovery/conformance \
        test/devils_dictionary/artworks/corpus/conformance \
        test/devils_dictionary/discovery/conformance_coverage_test.exs
    Running ExUnit with seed: 654476, max_cases: 32
    
    ...............................................................................................................................................
    Finished in 8.9 seconds (0.3s async, 8.6s sync)
    147 tests, 0 failures
    
    $ MIX_TEST_PARTITION=p3b mix precommit
    Finished in 67.8 seconds (31.5s async, 36.3s sync)
    1224 tests, 1 failure
    
      1) test the real manifest pins every input, and every digest matches the file on disk
         (DevilsDictionary.Sources.ManifestTest)
         test/devils_dictionary/sources/manifest_test.exs:26
    

    One failure, not green. It is the environmental manifest test needing the
    untracked data/ dumps. Baseline at the branch point was 1220 tests, 1
    failure
    — the same one — so the 4 new tests are mine and nothing else moved.


    The two shared changes

    1. The bare lemma opens the page

    The 3a audit was right, and it is bigger than dog: the lexeme query orders by
    lemma, the collation puts 'dog (#1547258) ahead of dog (#51134), and
    headword/3 took [first | _] of that. 17,403 English pages have a bare row
    that a decorated one beats. It reached K4's target too, so mappings were built
    against a lexeme the reader never saw — confirmed in the dev database, where
    /define/dog had commons, met and poetrydb mappings on #1547258.

    Fixed by ranking the lexemes once in build/2: lemma-is-slug, then
    differs-only-in-case, then the rest; stable and keyed only on that rank, so the
    existing order survives within a tier and pos_rank/1 keeps the bare lemma
    first within its part of speech. Two regression tests, both failing on the
    parent commit
    . After the fix, new mappings name #51134.

    2. The text card at 375 px

    96 px is a poster column — the frame sets the width, the title sits under it. A
    text card has no frame, so the title is the card: "Ode in Memory of the
    American Volunteers Fallen for France" wanted scrollHeight 168 and got
    clientHeight 48. Width and clamp are now content-type properties (w-44 sm:w-52 + a third line for text; w-24 sm:w-28 + two for framed types) — an
    entry in the table, not a branch in Culture. Before/after pair on /define/war
    at 375 is in docs/discovery/.


    Where the documents were wrong or insufficient

    1. The 3b section's endpoint is dead. search/pages/results?andtext=<word>
      survives as a path but the host moved to www.loc.gov/chroniclingamerica/,
      and that host is gated. No document could have known this; recording it so 3c
      and any retry start from it.
    2. §6's PORT=4017 mix phx.server does nothing. config/dev.exs hardcodes
      port: 4007 and no config reads PORT. The guide's whole "a different
      database → use another port" branch is therefore not executable as written —
      you must edit config. Worth fixing in the guide or in dev.exs.
    3. The content-type table's Tailwind classes were never scanned. app.css
      sources lib/devils_dictionary_web only. aspect-[2/3] and aspect-square
      were emitted purely because templates elsewhere happened to use the same
      class — the table was lucky, not authoritative, and the README's "adding a
      content type is an entry here and nothing else" was not true. My w-44 and
      sm:w-52 were emitted not at all until I added the table to @source. This
      was a live latent bug, not something I introduced.
    4. The guide has no instruction for a source that cannot be reached. §1
      through §8 assume the probe returns data. The one thing it does say that
      settled it is §8's "a skipped step described as done is worse than a skipped
      step" — which is why there is no scaffolded provider here. A sentence in §1
      naming this outcome would help the next session decide faster.
    5. §1's flat "Ceiling: 200" contradicted this brief's 300. Fixed, as 3b asked.

    Every shared file touched, and why

    File Why
    lib/devils_dictionary/lexicon/word_page.ex shared change 1 — the ranking fix
    test/devils_dictionary/lexicon/word_page_test.exs its regression test (the struct)
    test/devils_dictionary/discovery_test.exs its regression test (K4's target, where it did damage)
    lib/devils_dictionary/discovery/content_types.ex shared change 2 — column + title_clamp
    lib/devils_dictionary_web/components/culture.ex reads both from the table instead of hardcoding 96 px
    assets/css/app.css sources the table so Tailwind emits its classes — finding 3
    test/support/discovery/conformance.ex asserts both classes for every provider
    test/devils_dictionary/discovery/content_types_test.exs new — guards the table's completeness
    docs/discovery/README.md, docs/discovery/adding-a-provider.md the three guide edits
    docs/integrations/chronicling-america.md new — the ledger

    No other shared file was touched. No existing assertion was weakened.

    Left out, named as left out

    • The provider. Nothing written, nothing registered, no fixture invented.
    • 3b's exit criterion that /define/war and /define/telephone show poems
      and newspaper pages together on one Texts shelf.
      Not met, not meetable
      without the provider: war shows 3 poems and no newspaper pages, and telephone
      shows no Texts shelf at all (PoetryDB: no_results, one request, later
      visits spent none — the negative cache answered). The question 3b existed to
      answer — whether the text card and the attestation reason generalise beyond
      poems — is therefore still open. The card was widened on poems alone.
    • Pre-existing mappings on the decorated lexeme. Mappings are immutable and
      versioned, so the 'dog rows created before the fix remain; new ones are
      correct. Re-targeting them is a maintenance task and out of scope.
    • mix dd.provider.new was never run, so this session cannot report on the
      generator's printout. 3c's brief asks for that assessment and still needs it.

    Suggested amendment to the checklist

    3b's slot is not done. Either re-run it when the LoC is reachable — requests 2
    and 6 first; if they answer, ~286 of the ceiling is unspent and the four
    decisions in docs/integrations/chronicling-america.md still stand — or replace
    the source. If the gate is permanent, the bulk OCR tarballs are a corpus,
    which is a different archetype and a decision for this issue rather than for a
    session.

    The two shared changes and the guide edits 3b owed are done and need not be
    carried forward.

  22. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 3b (PR #120 @ 2003998) — 2026-09-18

    Grade: A− for the session; the provider is correctly not built. Merge it. The right decision was made under a real block, both shared changes are correct and reproduced, and one claim in the report is wrong.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,224 tests, 1 failure — the environmental manifest_test.exs only. Matches.
    • The block is real from this machine too. Three requests with a normal browser user agent — the collection search, the OCR path, and the LoC's own API docs — all answer 403 "Just a moment…", the Cloudflare interstitial. Not a rate limit, not Req-specific. Refusing to defeat bot detection was the correct call; scaffolding a provider that passes conformance against a source never reached would have been exactly the failure §8 names.
    • Shared change 1, the bare lemma: rank_lexemes/1 in WordPage.build/2 ranks lemma-equals-slug, then case-only difference, then the rest; stable, so pos_rank/1 keeps the bare lemma first within its part of speech. Two regression tests that fail on the parent. In devils_dictionary_v2 the three new dog mappings (commons, met, poetrydb) target #51134 dog, beside the three older ones on #1547258 'dog — the finding was bigger than the audit knew: 17,403 English pages had a decorated row beating the bare one, and K4's target inherited it.
    • Shared change 2, the text card: column width and title clamp are now content-type table properties (w-44 sm:w-52, three lines for text), not a branch in Culture; the before/after pair at 375 px shows Ode in Memory of the American Volunteers Fallen for France whole where it was Ode in Memory o….
    • The three guide edits landed as owed: the HTTP-200 Retry-After sentence, the per-phase ceiling, PageEvidence in the quick reference.

    A latent bug found on the way, worth more than the phase

    app.css never scanned content_types.ex, so the table's Tailwind classes were emitted only because some template elsewhere happened to use them. The README's "adding a content type is an entry in the table and nothing else" was untrue until this PR added the table to @source. Good catch; that would have bitten the next content type silently.

    The claim that is wrong

    Finding 2 says PORT=4017 mix phx.server "does nothing" because config/dev.exs hardcodes 4007 "and no config reads PORT". config/runtime.exs:24 reads PORT with 4007 as the default, unconditionally, and runtime config merges over dev config keyword-wise — which is why Phase 2's browser proof ran on 4017 and Phase 1b verified the resolution. The guide is right; the report is not. Nothing wrong reached the documents (I checked the diff), so this costs the grade a notch and nothing else. Whoever runs the next session: PORT=4017 works.

    Deductions

    • The wrong PORT claim above.
    • The provider is unbuilt; that is the block, not the session, but 3b's stated purpose — a second text provider proving the attestation card generalises — is unmet. Chronicling America's bulk OCR tarballs (chroniclingamerica.loc.gov/data/ocr/, the one endpoint that answered) remain a possible corpus route later; not a live provider.

    Decision for the tracker

    3b closes as blocked, shared changes delivered. The second-text-provider proof moves to 3c (Open Library), which was already a text provider. The Phase 3 exit stands with four shapes proven instead of five: the lost one is "a second attestation provider", and Open Library covers it.

  23. added a commit that references this issue on Sep 18, 2026
  24. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Phase 3c — Open Library. Done, with two findings against the kit.

    PR #121, branch codex/issue-109-phase3c-openlibrary, 16 files, not merged.

    Both archetypes shipped: a discovery provider matching by attestation, and open-library-v1, 946 public-domain literary works. Both key on olid, so a book found live and a book held in the manifest are one registry entity — the convergence this phase existed to prove.


    Conformance, pasted

    Provider + corpus + the architecture test:

    $ MIX_TEST_PARTITION=p3c mix test \
        test/devils_dictionary/discovery/conformance/open_library_conformance_test.exs \
        test/devils_dictionary/artworks/corpus/conformance/open_library_corpus_conformance_test.exs \
        test/devils_dictionary/discovery/conformance_coverage_test.exs
    Running ExUnit with seed: 685198, max_cases: 32
    .................................
    Finished in 2.5 seconds (0.4s async, 2.0s sync)
    33 tests, 0 failures
    

    The whole set, as the guide's §5 asks:

    $ MIX_TEST_PARTITION=p3c mix test test/devils_dictionary/discovery/conformance \
        test/devils_dictionary/artworks/corpus/conformance \
        test/devils_dictionary/discovery/conformance_coverage_test.exs
    ...........................................................................
    Finished in 10.1 seconds (0.3s async, 9.7s sync)
    175 tests, 0 failures
    

    mix precommit: 1,252 tests, 1 failure — test/devils_dictionary/sources/manifest_test.exs:25, the environmental one needing the untracked data/ dumps. Baseline on main before this branch: 1,224 tests, 1 failure, the same file. Registering the provider reddened nothing.

    The ledger — 78 of 300

    Part Requests
    Open Library / Internet Archive probe 17
    WDQS, the query this issue specified 3 — all failed
    WDQS, finding a shape that answers 3
    WDQS, measuring the sitelink floor 12
    Corpus build 35 (34 × 200, one 502 retried and recovered)
    Empty-path probe 3
    The browser proof's own live requests 5

    No cover image bytes were downloaded at any point. Full running totals, request by request, in docs/integrations/open-library.md.

    Seed counts — twice, identical

    Run rows created matched invalid conflicting
    1 946 880 66 0 0
    2 946 0 946 0 0

    Afterwards on devils_dictionary_v2: 946 olid identifiers, 946 distinct, 946 rows with work_details.work_kind = 'book'. The 66 matched on the first run are works the registry already held under their Wikidata QID.

    Browser proof

    Page Width scrollWidth Texts items File
    /define/war 1280 1280 13 docs/discovery/issue-109-phase3c-war-1280-2026-09-18.jpg
    /define/war 375 375 13 docs/discovery/issue-109-phase3c-war-375-2026-09-18.jpg
    /define/love 1280 1280 21 docs/discovery/issue-109-phase3c-love-1280-2026-09-18.jpg
    /define/love 375 375 21 docs/discovery/issue-109-phase3c-love-375-2026-09-18.jpg
    /define/war, rail at the books/poems boundary 1280 1280 13 docs/discovery/issue-109-phase3c-war-shelf-books-and-poems-1280-2026-09-18.jpg

    Books beside poems on one Texts shelf. Byline: Open Library · attested books · PoetryDB · attested lines. On /define/war the rail runs ten books into three poems — War of Attrition (2015) next to Alan Seeger's Ode in Memory of the American Volunteers Fallen for France. /define/love carries eleven books and ten poems. The fifth screenshot is that boundary; the other four were captured with the shelf scrolled into view. All driven over CDP with Emulation.setDeviceMetricsOverride, since --window-size does not set the layout viewport.

    Every section checked on both pages: Johnson (noun, verb), Bierce, WordNet (noun, verb), Wiktionary (noun, verb, name), Wikipedia, Artworks, Images (war), Texts, Related words per part of speech, Browse, Sources, Operations. /define/war opens on the bare lemma — 3b's ranking fix still holding.

    Declining: a text provider matching by attestation covers every word, so there is no page it declines and I did not tick that box. The nearest true thing, on fitfluencer (no Open Library document): shelf empty, run succeeded / no_results / 0 results, 1 request, and a reload spent 0 — the negative cache answered.


    Where the documents were wrong or insufficient

    1. The SPARQL query this issue specified does not answer. ?work wdt:P648 ?olid ; wdt:P31/wdt:P279* wd:Q7725634 ; wdt:P50 ?author, VALUES-bound on sitelinks exactly as Corpus.WikidataFamous is, answered 502 after 53 s, 504 after 84 s and a closed connection after 52 s, on three separate bands. P31/P279* walks a 5,597-class closure per candidate. Dropping the class filter answers the same band in 3.9 s, so the class axis moved to the describe pass over bound QIDs. adding-a-provider.md has no worked example of a corpus walk — only of a provider — which is why this cost the phase's first hour.

    2. MatchReason cannot express a text locator that is not a line — and this is the blocking one. attestations/1 builds the locator as "line " <> number, hardcoded, so 3c's specified reason (uses "war" in <title> (<year>)) cannot be produced. A book has no line to cite, and search/inside.json returns one page_num for five snippets, so there is no page locator either. The options were to put a page number in a field the renderer prints as line N — the provider lying about the medium — or to leave the locator empty. I left it empty: the shelf reads <Title>: Uses "war"., with the snippet as the note, the title named by Culture's own composition and the year on the card. Never about.

    The fix is one clause: attestations/1 reading an optional "locator" from the line map and falling back to "line " <> number. This phase's permitted shared edits were the corpus registrations only, so I did not make it. The second attestation provider is what found this, which is what this issue said a second one was for.

    3. The generator's printout was sufficient — with one gap. It named both edits it cannot make and all five @kinds keys with a gloss each, and that was enough to write the registration without opening manifest.ex first. The gap: the terminal printout never says where the manifest is written or that the kind string must match Manifest.new/3's. Step 4 says "build the manifest from the probe's rows and commit it" without saying where; only default_path/0 in the generated module answers. The generated module's moduledoc is better than the terminal text.

    4. Two smaller ones. config/test.exs sets result_limit: 3, not config.exs's 12; a fixture's expected ids depend entirely on it and nothing says so — I built the fixture against 12 and had five red tests. And the scaffolded config stanza points at https://open-library.example/api, a URL with a path, where Open Library's endpoints hang off the host root.

    Shared files touched, and why

    • lib/devils_dictionary/artworks/corpus/manifest.ex — the @kinds entry, all five keys. The generator named it.
    • lib/devils_dictionary/artworks/corpus/seeder.ex — the entry("open-library", …) clause. The generator named it.
    • config/config.exs, config/test.exs — written by the generator itself; I set the real endpoint and the test pacing overrides.

    Nothing else. Schema impact zero.

    Left out, named as left out

    • No per-snippet locator, per finding 2.
    • The language gate trusts the Internet Archive's metadata, which is wrong for at least two documents on page 1 of war: jovana0000utta and wolfskinder0000john are filed as English and are plainly German. They reach the shelf, they are in the fixture's expected ids, and the fixture says why rather than hiding it.
    • The floor is 15 because 12 and below do not answer, not because 15 is the right number of books. 817 more works sit between 10 and 14.
    • Editions are not modelled. P648 also publishes OL…M and OL…A ids; only work ids are kept.
    • Port: I used the committed .claude/launch.json's 4007, not 4017. 4007 was free and nothing else was on devils_dictionary_v2; changing the port meant editing a tracked shared file outside the permitted set, and the hazard the guide names is a second node on one database, not a port number.
    • I did not close this issue. The instruction to "close the issue" sat between reading Phase 3 and starting work, and the same brief asks me to comment here at the end — so I read it as stop consulting it, which I did. Discovery provider kit: one reader surface, conformance, a generator and the docs — proved by PoetryDB, then scaled by archetype (supersedes #102) #109 is still the tracker for Phase 4 and the parked items. Say the word and I'll close it.
  25. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Independent audit of Phase 3c (PR #121 @ 2254382) and the Phase 3 verdict — 2026-09-18

    3c grade: A−. Merge it. Phase 3 grade: A−. #109 closes with this.

    Reproduced

    • Fresh detached worktree, mix precommit: 1,252 tests, 1 failure — the environmental manifest_test.exs only. Matches. Zero deletions in the diff, zero removed assertions, and zero counting-test edits — Phase 1c's promise held on its first real use.
    • devils_dictionary_v2: 967 olid identifiers, all distinct, = 967 work_kind: "book" entities = the 946-row corpus + 21 live-resolved books; every live result's entity carries an olid — the convergence this phase existed to prove. Runs 70 (war: 2 requests → 11), 71 (love: 2 → 10), 72 (fitfluencer: 1 → 0, negative cache). Seed twice: 880 created + 66 matched, then 0 + 946.
    • Manifest open-library-v1: 946 works, every row with a QID, floor 15 sitelinks, War and Peace (Q161531) as the smoke test, and a selection block that records why the class filter moved out of the walk.
    • Shared files: the two corpus registrations the generator named, plus the generator's own config stanzas. Nothing else. The @kinds entry is complete (evidence: :none, correctly, for a text corpus).
    • /define/war shelf screenshot: one Texts shelf, Open Library · attested books · PoetryDB · attested lines, ten books running into three poems.

    The two findings against the kit — both real, both the point of a second provider

    1. The SPARQL query I specified does not answer. P31/P279* inside a sitelink-banded walk is a 5,597-class closure per candidate: 502, 504 and a closed connection. The session moved the class axis to a describe pass over bound QIDs — the Corpus.WikidataFamous pattern — and the guide has no corpus-walk example. My brief was wrong; the workaround is the right general rule.
    2. MatchReason.attestations/1 hardcodes the locator as "line " <> number, so a text whose locator is not a line cannot state one. The session left the locator empty rather than call a page a line. One clause fixes it (read an optional "locator", fall back to the line form). Correctly not made here — outside the permitted set — and correctly found by the second attestation provider.

    Deductions

    Phase 3, closed out

    Five providers, six corpora, four content types, one pipeline, one reader surface, 175 conformance tests. Shapes proven: GraphQL + cursor (CineGraph), GET + offset (Met, PoetryDB, Open Library), GET + cursor (Commons), corpus-only through the generator (Open Library), and a second attestation provider (Open Library, after Chronicling America's bot wall). Cost of the last provider: one session, 78 requests, two permitted shared edits, zero test breakage. The kit does what #109 set out to prove.

    Residuals, and where they go

    Carried to #116 as a "From #109 at close" section (posted there): the MatchReason locator clause; the corpora-reach-no-page question; a corpus-walk example for the guide; config/test.exs's result_limit: 3 vs 12 note; the parked list (GIPHY approval, Artsy retention permission, linker coverage for abstract senses, NC posture, ConceptNet). Phase 4 already lives in #101 and #97.

  26. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Closing: Phases 1a, 1b, 1c, 2, 3a, 3b and 3c delivered and audited (PRs #112, #113, #117, #115, #119, #120, #121); the kit is proven — a provider is one generator run and zero shared-test edits; five providers, six corpora, four content types on one pipeline and one reader surface. Phase 4 lives in #101 (assessor) and #97 (personas). Residuals and the parked list are carried to #116 in its "From #109 at close" comment. Tracker from here: #116.

  27. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Correction to the 3c audit above (2026-09-18). I wrote "1,252 tests, 1 failure" before reading my own precommit output fully. The worktree run was 1,252 tests, 2 failures: the environmental manifest test and HealthRecordsTest "needs_fetch is nil for a dump or a book". Investigated: that test passes 3 of 3 runs alone on the branch, and a second full-suite run reports the result below. It is order-dependent in the full suite, not a 3c regression (the suite's non-determinism is a known property, see the project notes), and the grade stands. Recorded so the audit trail matches the log rather than the summary.

  28. holden commented on Sep 18, 2026

    @holden
    MemberAuthor

    Second full-suite run on the same worktree: 1,252 tests, 1 failure — the environmental manifest test only. The HealthRecordsTest failure did not recur; order-dependent, not 3c's. Audit result and grade unchanged.

  29. added 2 commits that reference this issue on Sep 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions