Repository navigation
Description
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:
- Three reader chromes for one content type —
/define/soldiershows the tall catalog cards and the compact Met shelf. - No document says how to add a provider.
docs/discovery/holds one handoff;docs/integrations/holds per-source notes. - Nothing asserts that a provider conforms. "Does discovery work" has been an audit per provider.
- Artsy is 3,500 lines beside the pipeline, not in it.
Discovery.target_for_page/3takes the lowest object id of a page's lexemes —/define/waropens on the prefix sense; the Met reads the whole page's senses to route around it.- 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.
family,grief,justice,solitudehave 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=trueon 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;objectDateis free text; 16/1,644 titles exceed 255 chars. - Wikidata: bind sitelink counts with
VALUES, neverFILTER(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);wbgetentitieswalks up (instance/subclass of), never down. - Encyclopedia:
entities.preferred_labelisvarchar(255)(characters);refers_to(sense → entity) andlexeme_entity_candidate(lexeme → entity) are the two link predicates; identity is retired, never deleted;Claims.reinstate/2is the reversal tool. - Process:
mix compileto completion beforemix phx.serveror Oban discards jobs with module is not a worker (three sessions bitten); a fresh worktree always failsmanifest_test.exs:25(wants untrackeddata/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);zshdoes not word-split$varinfor— use${=var}; the dev DB isdevils_dictionary_v2, neverdevils_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 anywork_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.sectionkeyed by the content-type table. A corpus candidate becomes a shelf item with a match reason, sorted after live results. The tall#artwork-candidatessection andArtwork.cardleave the word page (/artworksstays 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 scopeLexicon.by_lemma_or_slug/2already 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_msjoinsmin_retry_interval_msincapabilities/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.Conformancedrives any provider through admission, budget, cache, pagination, cleanup, render and identity with its ownReq.Teststub;Corpus.Conformancechecks 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|cursorscaffolds the module(s), stub, config entries, conformance test include and a ledger template;--content-typeunknown to the table refuses. - K8 — Two documents.
docs/discovery/README.md(architecture: pipeline stages, identity rule, archetypes, content-type table, budgets) anddocs/discovery/adding-a-provider.md(the checklist: bounded probe + ledger → spec → generator → stub → conformance → browser proof → PR under 150 files).docs/integrations/<slug>.mdstays 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/Availabilitystay 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)
- K2: catalog candidates flow into
Culture.sectionas items with a K3 match reason; retire#artwork-candidatesfromword_live.ex; content-type shelf order film · artwork · text · gif;/define/soldier,/define/love,/define/allegory(the Artsy pilot) each show one Artworks shelf. - K3 struct + one renderer replacing
Culture.match_detail/2's three branches andArtwork.card's copy. - K4 page scope in
Discovery(shared), Met's privatetarget_entities/1deleted in favour of it; CineGraph unchanged in behaviour. - K5 pacing capability; Met at 3,000; all search terms queried.
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)
- K6 conformance suites, run against CineGraph, Met, the offset fixture, and both corpora.
- K7 generator with its own test (generate → conformance passes on the scaffold with a stub).
- K8 documents, written from the code, not from this issue.
- Architecture test: every module in
:discovery_providersand every manifest underpriv/artworks/manifests/ofschema_version ≥ 1is 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.
- Bounded probe ≤200 requests, ledger.
- Corpus:
poetrydb-v1.json— every poem (title, author, line count, lines hash, author QID where the manifest crosswalk names one); seed aswork_kind: "poem". - Discovery:
/lines/<lemma>→ attestation candidates (K11), text-first card (no image slot), match reason uses "war" in line N. - 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.
- 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: scaffolddemowith the generator, run the full suite, expect only the environmental failure, deletedemo. - Corpus registration is one place.
identity,namespaceandwork_kindalready live inCorpus.Manifest.@kinds; theentry/3row mapping inCorpus.Seederis 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. 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 ondevils_dictionary_testproduced 41 phantom failures during the 1b audit).- Ledger template gets the running-total column §1 demands; the
covers?/1browser item says what to verify when a provider declines nothing (an unattested word → empty shelf, negative cache, one request). - Optional, ≤40 requests, ledgered: recover Byron and Shelley into
poetrydb-v1bylinecountbucket; bump the manifest, keep provenance exact inselection. - Seed
poetrydb-v1intodevils_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
- Archetype discovery only. Content type
:image— the Photos row Many sources, one shelf: the Photos shelf (Openverse, Unsplash, Pexels) as the rule for every multi-source content type — memes and quotes follow it; what eventasaurus taught #116 M4 defines (heading: "Photos",aspect: "aspect-[4/3]",attribution: :required): add that one row if Many sources, one shelf: the Photos shelf (Openverse, Unsplash, Pexels) as the rule for every multi-source content type — memes and quotes follow it; what eventasaurus taught #116 Phase 1 has not landed it yet, exactly as M4 specifies, so the two efforts declare the same shelf. Not:artwork. Transport GET, pagination cursor (MediaWikicontinue). Coordination: Many sources, one shelf: the Photos shelf (Openverse, Unsplash, Pexels) as the rule for every multi-source content type — memes and quotes follow it; what eventasaurus taught #116 owns the Photos shelf's family rules (interleave, cross-source dedup, attribution); 3a is that shelf's identity-bearing source and lands before Many sources, one shelf: the Photos shelf (Openverse, Unsplash, Pexels) as the rule for every multi-source content type — memes and quotes follow it; what eventasaurus taught #116 Phase 1, which then reshapes the shelf 3a paints. - Match:
haswbstatement:P180=<QID>in a Commons search, for the QIDs the page's sensesrefers_to— the same evidence read the Met uses. A file is kept only when its structured data carries the QID (search proposes, the hydrated statements dispose). No broader walk in 3a. - Licence gate on the hydrated file: keep only
CC0,CC BY,CC BY-SAand public-domain marks read from the file'sextmetadata; record the licence and attribution on the item. Thumbnail URLs only; no image bytes. - Identity: namespace
commons_file= the file's page id (Mid); the file's ownP180/P6243are metadata, never its identity. - Pacing: measure; start at 1 s; honour
maxlag. Probe ceiling 300, ledger as you go. - Retire Artsy's private client (K9): delete
lib/devils_dictionary/artsy/client.ex,request_coordinator.exandavailability.ex, and the/artworkspage's live-search branch; the 43-work pilot stays as catalog rows and its gene mappings stay readable;Providers.Artsystays registered (registry-only profile). Conformance and coverage must stay green;docs/integrations/artsy.mdsays what was removed and why. - Exit: conformance green including the cursor cases;
/define/soldierand/define/dogshow Commons images with reasons naming the QID; ledger ≤ 300; the Artsy deletion is its own commit.
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/dogopens ondog(#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:textcard inCultureat 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/warat 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-Afteron an HTTP 200 body;PageEvidencejoins the quick reference; the ceiling is stated as per-phase. Small, same PR. - Exit: conformance green;
/define/warand/define/telephoneshow a Texts shelf carrying poems and newspaper pages together;/define/dogopens ondog; 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 theVALUES-bound walk, identityolid,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@kindskeys and theentry/3clause — 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> (); identityolidso a live hit and a corpus row converge on one entity, as PoetryDB's do. - Pacing: measure; Open Library asks for a
User-Agentwith contact; ceiling 300. - Exit: conformance green for provider and corpus; coverage test sees both;
/define/warshows 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
- Phase 1a — one reader surface, match-reason struct, page scope, pacing (PR Phase 1a of #109: one reader surface and the shared provider rules #112, merged 2026-09-18, A)
- Phase 1b — conformance, generator, the two documents (PR Phase 1b of #109: conformance, the generator and the two documents #113, merged 2026-09-18, A)
- Phase 2 — PoetryDB from the docs alone (PR Phase 2 of #109: PoetryDB, built from the documents #115, merged 2026-09-18, A; kit verdict A−)
- Phase 1c — the fix-ups Phase 2 measured (PR Phase 1c of #109: the fix-ups Phase 2 measured #117, merged 2026-09-18, A)
- Phase 3 — 3a Wikimedia Commons ✅ (PR Phase 3a of #109: Wikimedia Commons by depicts identity, and Artsy's client retired #119, A) · 3b ✅ shared changes only, Chronicling America BLOCKED by LoC bot verification (PR Phase 3b of #109: the text card at phone width, the bare lemma — and Chronicling America blocked #120, A−) · 3c Open Library (corpus through the generator; now also the second-attestation-provider proof)
- Phase 4 — Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101 P0 → P3, then Explore local AI curation: persona editors, schema, models and compute budgets #97
- Parked: GIPHY caching approval (K10); Artsy retention permission; linker coverage for
family/grief/justice/solitude(Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101's row); the non-commercial posture for MusicBrainz/IGDB/Guardian (from Explore next discovery providers: quotes, music, books, news, images, games, nature and social APIs #100); ConceptNet as a source (from Harden the encyclopedia backbone: durable word identities, correct source relationships, safe refresh, and ConceptNet integration #72)
Activity
Merge pull request #110 from razrfly/09-17-phase2-readme
holden commentedon Sep 17, 2026
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-worktreedata/dumps, not evidence. Five further full runs across four seeds reproduced only that one.The three pages, and
/define/warOne 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./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./define/allegory— the Artsy pilot's 43 artworks read through K2's chrome and nothing else underartsy/changed. Related Artsy gene “Allegory”./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.375 px
document.documentElement.scrollWidth == 375on all four — no horizontal page scroll. Left to right: soldier, war, allegory, love.Where the code disagreed with the brief
Lexicon.by_lemma_or_slug/2is private, and it is not the scope K4 needs. It anchors on the string a reader typed, so the same page reached by/define/warand by/words/147197/warresolves 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 addedLexicon.page_scope/1(a query of object ids) andpage_lexeme_ids/1beside it, which is the lexeme-anchored form the Met had already built privately, and deleted the Met's copy.The target cannot be only a set.
discovery_mappings.target_object_idis 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 carrieslexeme_idsbeside it./define/war: was the verb55026, is now the noun147197, both mappings verified in the dev database.The lexeme set has to come from the database, not from
page.headword.lexemes.mapping_target/1rebuilds 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 asmapping_evidence_changed. It is one cheap query in both places instead.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. Neithertermnornotecan hold both without meaning two different things, soMatchReasoncarriesreachedas well, documented as such.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/0readsconfig[:request_interval_ms]with the measured 3,000 as its default, becauseconfig/test.exsneeds 0 and a capability that ignored the environment would put 78 s of sleep in the suite.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.
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).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 withscrollLeft == 1584— past every result the page had just fetched. Measured in Chrome, fixed by droppingsnap-x snap-proximityfrom the rail, pinned by a test.overflow-anchor: nonewas not the cause; I tried it first and it changed nothing.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:warthe noun): keyword search + discoverwarthe noun): 1 search + 25 hydrationsNo 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 withmain's code. The proof is in the run's own row:next_cursorcame back as the bare"25"with a nullterm_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
artsy/changed. GIPHY is untouched beyond rendering its shelf where it always did./define/soldier,/define/loveand/define/allegorydo 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), andlovehas no Met coverage. Every page shows one artwork shelf carrying whichever of the three it has, which is what K2 actually requires;/define/soldiercarries two sources in one shelf (Met live + Wikidata and Met from the corpora) and/define/allegorycarries Artsy.main. Same code, same database, different port.holden commentedon Sep 17, 2026
Independent audit of Phase 1a (PR #112 @
e527107) — 2026-09-18Grade: A. Merge it. Phase 1b may start from its merge.
Reproduced
mix precommit: 1,075 tests, 1 failure — the environmentalmanifest_test.exs:25only. Effective 1,075 / 0, matching the report.#artwork-candidatessection 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).warmapping before this branch targeted the verb55026; the two created by the session's live run (54 cinegraph, 55 met, 21:23) target the noun147197. Verified, not read off the report./define/soldierscreenshot: 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
MatchReasonis the right shape and its eighth fieldreachedis justified — the broader walk genuinely names two things.Lexicon.page_scope/1anchored 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; theProcess.sleepin 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
main's code (barenext_cursor, nullterm_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 inadding-a-provider.md(Phase 1b).allegory;lovehas 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)
Artworks.shelf_items/2→suggestions/2, several queries) where the live providers pay only acovers?existence check. Fine at 3,212 works; measure p95 before the corpora grow past ~50k./define/soldierthe 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).review_state: :not_yet_reviewedand 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.Merge pull request #112 from razrfly/codex/issue-109-phase1a
holden commentedon Sep 17, 2026
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/orlib/devils_dictionary_web/changed at all — the only newlib/file is the generator task.mix precommit: 1,188 tests, 1 failure —manifest_test.exs:25, the fresh-worktreedata/dumps, not evidence. Zero compile warnings. Baseline onmain@f147a5fwas 1,078; this adds 110 tests.Conformance — 110 tests, 0 failures
cinegraphmetoffset-fixture:textartsygiphymet-highlights-v1.jsonwikidata-famous-v1.jsonA 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 withrequest_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 anidentity_record/1resolves to an object, one without saysinsufficient_evidenceand carries none; noillustratesclaim is ever written); and the reader (renders throughCulture.sectionon 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_providershas a fixture, every fixture is run by a suite, every committed corpus manifest has a suite, and every other JSON file inpriv/artworks/manifests/is a well-formed Artsy import manifest.The generator, unedited
The demo was then deleted and
config/reverted;git statusis clean of it.Where the code disagreed with the brief
K6 says "every registered module must pass". Two of the four cannot be driven, so the suite has two profiles. Artsy declares
background: falseand GIPHY declarestransport: :browser; neither exportsretrieve/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 thatserver_providers/0refuses 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.The architecture test cannot use "every manifest with
schema_version >= 1" as the rule.priv/artworks/manifests/holds six JSON files with aschema_version, and only two are corpora. The other four are the Artsy pilot's resumable import manifests —DevilsDictionary.Artworks.Manifest,schema_version2,candidateskeyed onqid+artsy_artwork_slug— a different format sharing a directory. Taking the brief literally would have demanded a corpus conformance suite forpilot-v1.json, which has norowsto seed. The test covers every manifestCorpus.Manifest.corpus_manifest?/1recognises, and then asserts each remaining file loads as an Artsy import manifest, so the exception is checked rather than assumed.The conformance case lives in
test/support/, notlib/.DevilsDictionary.Discovery.Conformanceis 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 whereDataCaseis, compiled only in:test. Shipping test-only machinery inlib/would put it in a release."Using the provider's own
Req.Teststub" needed somewhere for that stub to live. Adding a stub callback toDiscovery.Providerwould 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 aConformance.Fixtureintest/support/:provider/0,covered_target/1,uncovered_target/1andstub/2.stub/2returns the external ids its installed responses will yield, per page, so the fixture is a claim the suite checks rather than a second implementation.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
@kindsinCorpus.Manifest, and anentry/3clause inCorpus.Seederthat maps a row onto aSourceIdentity.Entry— which only someone who has read the source's own rows can write.--archetype corpusscaffolds the builder module and then prints both edits, and the generator's test asserts it prints them and thatManifest.new/3raises 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.Providers.get/1answers an unknown slug with:unsupported_provider, not:provider_not_registered.:provider_not_registeredis whatensure_source/1returns when the source row is missing. The conformance admission case asserts what the code returns.K10's "rendering its shelf through K2's chrome" is not what shipped, and cannot be as things stand.
Culture.section/1draws fromDiscovery.state/2items, and a browser-transport provider has none — GIPHY's requests are made by the reader's browser and nothing is cached server-side.WordLivestill rendersDevilsDictionaryWeb.GiphyShelf.section/1beneath 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.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.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-2asaid the sustained pace is ~1 req/s set byrequest_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-probecarried 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 smin_retry_interval_msmeasured there is unchanged and still shipped.artsy.mdsaid "four mappings currently have verified opaque Artsy gene IDs" wherepriv/artworks/meaning-mappings-v1.jsonhas 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.mdsaid nothing about where the provider sits in the kit; it now does.PORT=4017 mix phx.serveralready works —config/runtime.exsreadsPORTwith 4007 as its default, for every environment, and it overridesconfig/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 againstdevils_dictionary_v2is 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: scaffoldingdemointo the real config and runningmix testgives 1,207 tests, 11 failures — ten of them real, in four files that count providers or assume one server provider makes one run:test/devils_dictionary/discovery/providers_test.exstest/devils_dictionary_web/live/culture_discovery_live_test.exsRepo.one!(Run)— one provider, one run (5 tests)test/devils_dictionary_web/live/film_identity_flow_test.exstest/devils_dictionary_web/live/home_live_test.exsThe eleventh is the environmental manifest test.
adding-a-provider.mdnames 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.checkexits with CINEGRAPH_API_KEY is missing or blank;mix dd.discovery --dry-runselects 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/aritynamed 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/2andArtwork.card, both retired by Phase 1a) and were rewritten so the documents name only what exists.Every command in
adding-a-provider.mdwas run as written:mise installmise all tools are installedmix deps.getAll dependencies have been fetchedmix compilemix precommitmix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offsetmix test …/demo_conformance_test.exsmix test …/conformance …/corpus/conformance …/conformance_coverage_test.exslsof -nP -iTCP:4007 -sTCP:LISTENbeam.smp— which is the finding the rule exists forPORT=4017 mix phx.servergit diff --name-only main...HEAD | wc -lgit switch -c …The three commands in the README's development section were run too:
mix dd.discovery --dry-run,mix dd.discovery.checkandmix dd.artworks.seed --dry-run(1,644 rows,would_seed: 1644, nothing written).Left out, and why
devils_dictionary_v2for the whole session, and starting a second node against that database is precisely what the rule this PR documents forbids.PORT=4017 mix phx.serveris therefore verified by config resolution rather than by a second running server.Req.Test; no image bytes, no network.mix dd.provider.new demoin the repository and pasted in full.mix dd.provider.new --archetype corpusdoes not produce a corpus that passes conformance unedited, and cannot — see disagreement 5. The discovery half does.holden commentedon Sep 17, 2026
Independent audit of Phase 1b (PR #113 @
f231121) — 2026-09-18Grade: A. Merge it. Phase 2 is ready, with one rule amended below.
Reproduced
mix precommit: 1,188 tests, 1 failure — the environmentalmanifest_test.exs:25only. Matches the report.mix dd.provider.new demo --archetype discovery --content-type text --transport get --pagination offsetwrote the four files and two config edits;mix compileclean;demo_conformance_test.exs→ 19 tests, 0 failures. An unknown--content-type videois refused with the table's rule.demoregistered, a clean full-suite run is 1,207 tests, 12 failures: 5 inculture_discovery_live_test.exs, 3 inproviders_test.exs, 1 each inhome_live_test.exsandfilm_identity_flow_test.exs, plus the environmental one — the four filesadding-a-provider.mdnames. (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 sharingdevils_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.)illustratesinvariant, and the render throughCulture.section; 8 per corpus including idempotent seed and label width; the coverage test reads the registry and the manifest directory off disk.The ten deviations
All correctly argued. Two are structural and reach into Phase 2:
Corpus.Manifest.@kindsand anentry/3clause inCorpus.Seederare 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 abotharchetype 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.Deductions (none blocking)
test/support/, somix dd.provider.newon a fresh clone works only in:test— fine, documented.mix dd.provider.verify <slug>would close it.Phase 2 handoff stays one line: "Do Phase 2 of #109."
holden commentedon Sep 17, 2026
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.mix dd.provider.newchecked 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 itselfFile.write!/2; a test collides on the last output and asserts nothing else was writtenuse <case>, fixture:/manifest:with the expected valueschema_version >= 1nil >= 1and"1" >= 1are both true under Elixir term orderingis_integer(version) and version >= 1Corpus.Conformanceon its sizemin(@slice, length(rows))FunctionClauseErrorin conformance after doing every registration the generator namesnamespacejoinssourceandidentityinCorpus.Manifest's@kinds, exposed asidentity_namespace/1for key <- …, value = Map.get(…)drops a falsy value, sorequest_interval_ms: nilskipped the assertion entirelyMap.fetch/2— absent is the only thing that may be skippedTwo are worth more than a line.
#2 was real, and I checked it rather than assuming. I replaced
met_conformance_test.exswith 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 throughuse … 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) andnamespace(theexternal_identifiersnamespace the seeder writes it to) genuinely differ — a Wikidata row is keyed onqidand identified aswikidata— so neither derives from the other, and a kind declaring only the first leftCorpus.Conformancewith a hard-coded list of its own.Corpus.Manifest.@kindsnow carries all three andidentity_namespace/1exposes it; the generator's corpus instructions andadding-a-provider.mdstep 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 precommitafter these fixes reported 45 failures —Ecto.StaleEntryError,MatchErrorandquery_canceledscattered acrossAbsorb.BatchTest,AccountsTest,WiktionaryIndexTestand other modules this branch never touches. None was a regression: another checkout was runningmix testagainst the samedevils_dictionary_testat the same time, and two runs trample each other's sandboxes. The same commit on its own database:config/test.exsalready appendsMIX_TEST_PARTITIONto the database name and thetestalias 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.Merge pull request #113 from razrfly/codex/issue-109-phase1b
holden commentedon Sep 18, 2026
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, so42b947dwas stranded on the branch. #114 is that single commit — 3 files, generator input validation only — rather than a push straight tomain.On merged
main, in the primary checkout (which has thedata/dumps):Zero warnings, no environmental failure — the
data/dumps are there, so thesources/manifest_test.exsexception that a worktree always hits does not apply. Clean working tree,mainin sync withorigin/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:
Macro.camelize/1folds a trailing or doubled hyphen away, somix dd.provider.new demo-would write four files at paths nobody has used and define the moduledemoalready 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,openverseandchronicling-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.holden commentedon Sep 18, 2026
Phase 2 — PoetryDB, built from the documents. PR #115.
Branch
codex/issue-109-phase2-poetrydb, 20 files, not merged. The Phase 2section was read once and then closed; everything after that came from
docs/discovery/README.md,docs/discovery/adding-a-provider.md,docs/integrations/and whatmix dd.provider.newwrote.Conformance output, pasted
The provider suite and the corpus suite:
Every suite plus the architecture test:
The whole suite:
1,221 tests, 1 failure —
manifest_test.exs, the environmental one thatneeds the untracked
data/dumps. Baseline measured onmainbefore anychange: 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 inhome_live_test.exs,one in
film_identity_flow_test.exs, five inculture_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./author→ 129 poets/lines/warwithlines→ 503 ×3, 15.7–17.1 s/title/Sonnet 1→ never left the process (invalid_request_target). Counted anyway.thunderbolt(25 hits) 503; three others 200linescomes back/author/<poet>/…,lineseach, 300 ms apart → 127 × 200, 2 × 503query.wikidata.org/sparql, 127 labels per call/define/war, one run/define/love, one run/define/zyzzyva, one run167 / 200. B1–B3 are
discovery_request_attemptsrows 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 compileto completionfirst. 1280 and 375 CSS px driven over CDP with
Emulation.setDeviceMetricsOverride— not--window-size, as the checklistwarns.
docs/discovery/issue-109-phase2-war-1280-2026-09-18.jpgdocs/discovery/issue-109-phase2-war-375-2026-09-18.jpgdocs/discovery/issue-109-phase2-love-1280-2026-09-18.jpgdocs/discovery/issue-109-phase2-love-375-2026-09-18.jpgWhat 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:
The 375 measurement:
document.documentElement.scrollWidth === 375at375 on both pages, and
=== 1280at 1280. No horizontal page scroll ateither 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 backsucceeded,result_count 0,request_count 1,completion_reason: no_results,refresh_after24 hout. PoetryDB's 200-carrying-404 was read as a negative cache, not a
failure and not a backoff.
poetrydb_poemidentities whose ids are theones in the committed manifest —
69b7e022c9c6bc683f2800d6fb99edc6isOde 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:
warkept 3 of 12candidates,
lovekept 10 of 12. 5 and 4 requests respectively.Where the documents were wrong or insufficient
1.
Corpus.Conformancecannot run a non-artwork corpus — a shared file outside the permitted listThe finding.
test/support/artworks/corpus_conformance.exsays it is thesuite "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/0countedwork_kind == "artwork"as a literal, so for acorpus of poems it is always 0 and its idempotence and dry-run assertions
assert nothing.
row, "#{@path} records no depicted QIDs, so nothing could ever match a page"— which a text corpus fails by construction.Measured:
poetrydb-v1against the unmodified suite was 8 tests, 2failures, both of those.
And
conformance_coverage_test.exsrequires every committed corpusmanifest 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 andis 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:
Manifest.work_kind(manifest["kind"]), a thirdregistration in
@kindsbesideidentityandnamespace. That key is in apermitted 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.
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.
Manifest.identity_namespace/1and carries its kind'swork_kind. That isthe 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_kindinto@kindspermanently (done here) and keep the branch, or split
Corpus.Conformanceinto a shared half and an artwork half, and let the coverage test accept
either. The generator should also print the
work_kindregistration as athird 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 notprevent 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, andmainhas no PoetryDB module atall, so a second node would have produced a proof of nothing.
devils_dictionary_v2is 13 GB and
DD_DATABASEneeds thedata/dumps that a fresh checkout doesnot 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?/1has no documented answer for a provider that declines nothing but couldThe 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
trueis right, because any word can be looked for in a line. Sothat 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 writesdocs/integrations/<slug>.mdas "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.
mix helpusespoetrydbas its worked example withexactly 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:attestationandMatchReasonalready parses
"lines"→ Uses “war” at line N. Nothing needed writingfor the reason — K3 had already done it. That is the kit working.
Every shared file touched, and why
Permitted, and only these:
lib/devils_dictionary/artworks/corpus/manifest.expoetrydbkind in@kinds— the generator's first named edit. Pluswork_kindon all three kinds and its accessor; see finding 1.lib/devils_dictionary/artworks/corpus/seeder.exentry("poetrydb", …)clause withwork_kind: "poem"— the generator's second named edit.test/devils_dictionary/discovery/providers_test.exs[Artsy, CineGraph, Giphy, Met, Poetrydb];server_providers()now three; addedserver_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.exstest/devils_dictionary_web/live/culture_discovery_live_test.exsRepo.one!(Run)now register the one provider they are about, via a smallonly/1helper — the file's own existing idiom (four other tests already doput_env(…, [CineGraph, fixture])). Every assertion kept verbatim.test/devils_dictionary_web/live/film_identity_flow_test.exsNothing in those files was weakened. The
Repo.one!(Run)assertions arestronger 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:
test/support/artworks/corpus_conformance.exconfig/config.exsandconfig/test.exswere edited by the generator; my ownchange there is the
:poetrydbendpoint,https://poetrydb.example/api→https://poetrydb.org, inside my provider's own stanza.Left out, named as left out
/authorresponses 503 after ~16 s — Don Juan alone is 16,092 lines andShelley's 312 poems total 37,898. Recovering them means splitting by
linecountbucket, which would cost ~40 of my remaining requests and leavea 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
selectionblock and in the integration doc. The briefasked for every poem and this is 2,523 of them, not all.
author_qid. Three are namesakes the rule cannotseparate (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.
mix dd.artworks.seedrun against the development database. Thecorpus is committed, checksummed and seeded by the conformance suite (25
rows, twice, idempotent). Seeding all 2,523 into
devils_dictionary_v2isa data change to a shared 13 GB database that Phase 2 does not require, so
I did not make it.
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.
for posters, so poem titles truncate hard ("Ode in Memory o…"). It is
legible and it is the shared
Cultureshelf, not anything this providerships — a provider ships zero components. Worth a look when a second text
provider lands; not fixed here.
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.
holden commentedon Sep 18, 2026
Independent audit of Phase 2 (PR #115 @
b3b57d0) and the program verdict — 2026-09-18Phase 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
mix precommit: 1,221 tests, 1 failure (the environmentalmanifest_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'swar,love,zyzzyva; 11work_kind: "poem"entities from live resolution, 0 seeded (as stated); source rowpoetrydbpresent.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 ownselectionblock./define/warscreenshot: a Texts shelf, PoetryDB · attested lines, no image slot, each item Uses "war" at line N.artwork_countreplacements only; the depiction case now branches (artwork corpora must still carry depicted QIDs). Nothing weakened; the scopedRepo.one!(Run)assertions are stronger.The acceptance test, scored
The session built a fourth pipeline provider and a third corpus from
docs/discovery/*.mdand 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 countedwork_kind == "artwork"literally and required depicted QIDs, so a corpus of poems failed 2 of 8 by construction. The fix (awork_kindregistration 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?/1browser 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/warreturns 1,026 poems of which 201 use war as a word, and the gate kept 3 of 12 onwar, 10 of 12 onlove. 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)
linecountbuckets for ~40 requests.linesfield of/lines/<word>every time. The provider routes around it; the shelf will be slow on first paint for a new word.What "absorb more APIs" costs now, measured
Before Phase 3 — one short session, "1c", recommended
identity,namespace,work_kind, and theentry/3row mapping) toward data, or at least have the generator print all three edits; today it names two.linecountbucket (≤40 requests).Then Phase 3 as planned. Handoff for 1c: "Do Phase 1c of #109" once the section is written.
holden commentedon Sep 18, 2026
Phase 1b finding closed. The
Corpus.Conformancegap reported above isfixed in #115 (
6648c88), as a Phase 1b fix rather than the Phase 2 patch itoriginally 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.
@kindsis already the one place a corpus kind'sidentityandnamespacelive; it now also carries
work_kindandevidence:work_kindevidencemet-highlightsartwork:depictionwikidata-famousartwork:depictionpoetrydbpoem:noneevidenceis what a row of this kind can match a page on —:depictionwhenit records the QIDs of what the work shows,
:nonewhen it records identityand 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:
mix dd.provider.newanddocs/discovery/adding-a-provider.mdnow print allfive
@kindskeys instead of three, so the next corpus session does notrediscover 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 thetwo-axis form times out at ~16 s) fixes both that and the result's citable
locator. Ledger now 172 / 200.
Merge pull request #115 from razrfly/codex/issue-109-phase2-poetrydb
holden commentedon Sep 18, 2026
Phase 1c — the fix-ups Phase 2 measured. PR #117,
codex/issue-109-phase1coffmain@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:26here. 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:
Before the fix, full suite with
demoregistered:After, same scaffold,
mix precommit:Then
demo's four files deleted andconfig/config.exs/config/test.exsreverted 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(3failures) and
home_live_test.exs(1).culture_discovery_live_test.exsandfilm_identity_flow_test.exswere already provider-scoped by #115'sonly/1helper — 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.exsnow 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.exsreads the expected sourcecount 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
@kindskeys — #1156648c88did that as aPhase 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) plussource. What was missing was the test, and a single listfor the printout to be derived from.
Manifest.registration_keys/0is now read off@kinds, and a kind thatregisters 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.
Two tests in
dd_provider_new_test.exshold the printout toManifest.registration_keys/0, for--archetype corpusand forboth.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 discoveryscaffold and printed for both: it told a corpus session to run
<slug>_conformance_test.exsand to "replace the scaffolded response envelopeand its stub", none of which
--archetype corpuswrites. It is archetype-awarenow.
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_jobstable; differentdatabase → use another port. One test run per test database is stated beside
it, with the 41-phantom-failure measurement.
docs/discovery/README.mdcarried the same advice in shorter form ("If port4007 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?/1Template: 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_attemptsfor that source. A test assertsthe generated ledger carries the column header.
covers?/1browser item: it now says a provider that declines nothing has nosubject here, that the default
trueis right for a text provider, and namesthe substitution to verify instead — unattested word, empty shelf, run recorded
no_results, one request, reload spends none.Item 5 — the ledger, 40 / 40
/author/<poet>/title,linecountfor Byron and ShelleyReq.Finchnot started in my script. Counted anyway, the way P3 was:reqstarted/author,linecount/Percy%20Bysshe%20Shelley;4/title,linecountlinecount4 — solinecountmatches exactlyquery.wikidata.org/sparql, POST, both names in oneVALUESblock withwikibase:sitelinks/author,linecount/<poet>;<n>/title,author,linecount,lines, the 34 largest buckets, 1 s apart503of any kind. 380 poems: Byron 198 of 325, Shelley 182 of 312Every 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 anauthor 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.recoveryin the manifest lists every bucket taken, the poemcounts 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/3takes a:source_url— a recovered row records thebucket URL it actually came from, because the
/author/<poet>route does notresolve for these two.
Item 6 — seeded into
devils_dictionary_v2--dry-runwork_kindinwork_details, before → after: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
the other two. Measured: 4 real failures, in
providers_test.exsandhome_live_test.exs.Phase 2 of #109: PoetryDB, built from the documents #115
6648c88. The gap was the test, and a single list to derive theprintout from.
@kindsholds five keys, four of themregistrations plus
source. The printout and its test are keyed onManifest.registration_keys/0so the number stops being a literal anywhere.manifest_test.exs:26, where the audit says1,221 and
:25. Same commit, same environmental failure.mix dd.healthandmix dd.scoreboth 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
the 219 buckets. Listed above; derivable from the manifest.
mix setup,gh repo clone, themix dd.absorb/dd.scope.build/dd.link/dd.resolve/dd.snapshot/dd.materialize --alllines ofthe 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 setupwrites seeds and a dev user. I verified everytask exists and every flag in every line is in that task's own
OptionParserswitches, 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 fromhttp://localhost:4007/,then stopped). Every command in
adding-a-provider.mdwas run as written,including the
psql -tAcline I added andPORT=4017 mix phx.server'smix compilehalf.and the brief did not ask for one. The seeded corpus half is not yet on a
page — a corpus row declaring
evidence: :nonereaches a reader through thelive provider, not through
Artworks.shelf_items/1, so 2,903 seeded poemschange 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.
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 areboth free now.
mix dd.materialize --allnot run. The dry run reports 0 gaps, so itwould 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).holden commentedon Sep 18, 2026
Independent audit of Phase 1c (PR #117 @
c860bf9) — 2026-09-18Grade: A. Merge it. Phase 3 may start from its merge.
Reproduced
mix precommit: 1,225 tests, 1 failure — the environmentalmanifest_test.exsonly. Matches the report.demowith the generator into the real config,mix compile, fullmix 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.devils_dictionary_v2:work_detailsreadsartwork 3,212 · poem 2,903 · film 95 · dictionary 2; 2,903poetrydb_poemidentities = the manifest's row count; the 11 poems Phase 2's live runs had minted matched rather than duplicated.poetrydb-v1: 2,903 rows, 129 poets, 2,499 with an author QID; Byron 198, Shelley 182 recovered bylinecountbucket on exactly the 40-request cap, withselection.recoverylisting every bucket taken and the 257 not recovered — derivable, not merely admitted.providers_test.exsasserts each provider is scheduled for its own content type and for no other;home_live_test.exsreads 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.psqlline beside it.Deviations, all correct
Two counting files not four (#115 had scoped the others); the generator already printed every
@kindskey since6648c88, so the gap was the test and a single source of truth (Manifest.registration_keys/0, now mutation-checked);@kindscarries five keys, not three; the README's development section did not run as written (dd.health/dd.scorerefuse without--scope) and is fixed. A defect found on the way — the generator'snext:block was discovery-shaped for both archetypes — is fixed and archetype-aware.Deductions (none blocking)
evidence: :nonehas 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.
1 remaining item
holden commentedon Sep 18, 2026
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 honestkind: :queryreason (M6) while Phase 3a here makes Wikimedia Commons the identity-bearing one. Both stand: #116 owns the:imageshelf 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.holden commentedon Sep 18, 2026
Phase 3a report — Wikimedia Commons by depicts identity, and Artsy's client retired
PR: #119 (branch
codex/issue-109-phase3a-commonsoffmain@4207b8a, three commits, 32 files, not merged). Read the Phase 3 section once for the defaults and the K13 amendment, then worked fromdocs/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: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 precommiton the final tree: 1,217 tests, 1 failure —test/devils_dictionary/sources/manifest_test.exs, the environmental one. Baseline onmainbefore 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, anddiscovery_request_attemptsforcommonsreads 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).list=search haswbstatement:P180=Q4991371, ns 6, limit 5continue= `{"continue":"-generator=searchwithprop=imageinfo(url,extmetadata,iiurlwidth=640)extmetadatalicence in one answer;continue= `{"continue":"gsroffset, thenQ144alone, thenQ25324` alonehaswbstatement:P180=Q4991371 filetype:bitmapmaxlag=-1, to see the lag refusal{"error":{"code":"maxlag","docref":"See https://commons.wikimedia.org/w/api.php for API usage. Subscribe to the mediawiki-api-announce mailing list at <https://lists.wikimedia.org/postorius/lists/mediawiki-api-announce.lists.wikimedia.org/> 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"]continue(gsroffset=5, `continue=gsroffsethaswbstatement:P180=Q262026(andiron), the empty casehaswbstatement:P180=Q4115189(the Wikidata sandbox item) asgenerator=searchand aslist=searchvideo/webm, a park), so the window has to gate onmimeas well as on licence. Written wrongly at first as "noquerykey"; corrected after reading the bodygenerator=search(limit 10) then awbgetentitiesof its ten M-ids, 1 s aparthaswbstatement:P180=Q999999999999 filetype:bitmapas generator and as list{"batchcomplete":true}; list body{"batchcomplete":true,"query":{"search":[],"searchinfo":{"totalhits":0}}}gsrlimit=12,gsrsort=incoming_links_descgsrlimit=12, default sort, thenwbgetentitiesfor the twelveP180=Q4991371in their statements; licences %{"Attribution" => 2, "CC BY-SA 3.0" => 1, "CC BY-SA 4.0" => 1, "Public domain" => 8}/define/dogrefers to OR'd in onehaswbstatement,gsrlimit=12, links-desc, thenwbgetentitieswbgetentities ids=M116369alone/define/soldieron port 4007, one node ondevils_dictionary_v2: one search, onewbgetentitiesAttributionPolish Army photograph); every item reasoned Direct depiction of “soldier” (Q4991371). Three titles carried hidden QuickStatements text out ofObjectName— 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 belowprop=imageinfofor pageids 283006 and 8715577: the rawObjectNameHTML behind the two titles the first browser proof got wrong<div class="description">/<span class="language">-free; it is nested<div style="display:inline-block">blocks with<b>French:</b>labels/define/soldieragain on the fixed providerlanguageclass — D1 fetched the raw HTML, the rule became take thelang="en"element, and this run too was deleted and the one label corrected by hand before the third visit below/define/soldier, third visit, port 4007, one node ondevils_dictionary_v2, 1280 CSS pxAttributionfile dropped), every item Direct depiction of “soldier” (Q4991371), titles clean;scrollWidth === 1280; no console errors/define/soldierat 375 CSS px over CDP (Emulation.setDeviceMetricsOverride)scrollWidth === 375; 11 items/define/dogat 1280: the five QIDs/define/dogrefers to, OR'dscrollWidth === 1280; no console errors/define/dogat 375scrollWidth === 375; 12 items/define/zyzzyvaat 1280 — a page with norefers_toclaimcovers?/1declined it before admission.discovery_request_attemptsforcommonsreads 4 after the four proofs, which is B7 + B9No 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 compileto completion first, headless Chrome over CDP withEmulation.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/soldierthe 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/dognine 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 === 375at 375 and=== 1280at 1280 on both pages.The decline case:
/define/zyzzyvahas norefers_toclaim, shows no Images shelf, admitted no Commons run and spent no request.Where the documents were wrong or insufficient
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.refers_to, "the same evidence read the Met uses", but that read was two private functions inmet.ex. A second provider had to copy them or the kit had to share them. I extractedDevilsDictionary.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.MatchReason.from_result/2knew tags, keywords and lines, and not depictions, whilefrom_candidate/1did. 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.:imageis 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.exsasserts the refusal message with the literal listfilm, artwork, text, gifand 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.Retry-Afterheader is honoured at full length and written to the source; MediaWiki sends that header with a 200 body carryingerror.code == "maxlag", soTransport.classify/6never 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.<slug>_item; the issue namescommons_file. Changed by hand, as expected, but the generator could take--namespace.SourceIdentity.enrich_entity/2prefers the storedpreferred_labelfor 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".Artworks.Seeder(the Wikidata-to-Artsy importer), the import stage ofmix dd.artworks.seed,Artworks.withdraw_artsy/1's coordinator call, theRequestCoordinatorchild inApplication, and the client keys inconfig :devils_dictionary, :artsyall depended on the deleted modules. All went or were trimmed;docs/integrations/artsy.mdlists each. The--buildand--wikidata-onlystages of the seed task, which only ever spoke to Wikidata, stay.docs/mobile/README.mdis right andadding-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:imagein 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 toenabled.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; deletedlib/devils_dictionary/artsy/*,lib/devils_dictionary/artworks/seeder.exand their tests.Decisions made in the session
:image, not:artwork(finding 4). Identitywork_kind: "image".license,license_url,authorand acredit_lineare 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).maxlag=5: measured as unnecessary at 250 ms (B3, B4) and shipped as courtesy; both overridable in config.result_limit(12), so a page is exactly two requests and nothing proposed is thrown away by atake.Left out, named
/define/soldieris one QID;/define/dogis five, OR'd.withdrawal succeeds after a seeded creator citation) went with the importer;withdraw_artsy/1is still covered byartwork_live_test.exs.commonscorpus — none; the archetype is discovery only.maxlagrefusal under load (only the forcedmaxlag=-1, A6) and a real429; both are unit-tested against the measured shapes./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 ownsWordPage.holden commentedon Sep 18, 2026
Independent audit of Phase 3a (PR #119 @
9085b0b) — 2026-09-18Grade: 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
mix precommit: 1,217 tests, 1 failure — the environmentalmanifest_test.exsonly. 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 MediaWikicontinueobject asnext_cursor; 4 request attempts on record, as stated; 23commons_fileidentities = 23work_kind: "image"entities. Sample rows carry title, licence and author · licence as the creator line (John Warwick Brooke · Public domain).artsy_artwork_slugidentities and 7 enabled gene mappings, unchanged. Every removed assertion in the diff belongs to the deleted client, availability and importer suites.docs/integrations/artsy.mdopens with what was removed and why./define/soldierscreenshot: an Images shelf, Wikimedia Commons · depicts: Wikidata, attribution beneath every thumbnail, every reason Direct depiction of "soldier" (Q4991371).haswbstatement:P180=Q1|P180=Q2 filetype:bitmap),generator=search+prop=imageinfoso licence and thumbnail arrive in one answer, gate onextmetadata.LicensewithLicenseShortNamefallback andmime image/*,maxlag=5on 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
PageEvidenceextracted 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/2did not know depictions (onlyfrom_candidate/1did). A live P180 statement rendered as a tag would have misnamed the mechanism. Fixed with one reader.Retry-Afterarrives on a non-200; MediaWiki sends it with a 200 body. The next MediaWiki provider needs that sentence.:imageas 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,--namespacefor 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)
/define/dogopens 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" andWordPage'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 inWordPagefor whoever runs 3b.gsrsort=incoming_links_descis 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.Application, the client keys in config). All of it depended on the deleted client and all of it is listed inartsy.md; the wider cut was right.For 3b
Baseline after merge; fix the
'dogranking first (it will show on every apostrophe-led lemma); the cramped 375 px text card is 3b's shared change as planned.Merge pull request #119 from razrfly/codex/issue-109-phase3a-commons
holden commentedon Sep 18, 2026
Phase 3b — report
PR #120. Branch
codex/issue-109-phase3b-chronamoffmainatdddc632(3a merged, baselineconfirmed 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.gov308-redirects towww.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 towww.loc.gov/itself, and it did not clear on retest. It is not specific to
Reqeither — thesame 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
search/pages/results?andtext=war&format=jsonwww.loc.gov/chroniclingamerica/…collections/chronicling-america/?q=war&fo=jsonwww.loc.gov/search/?q=war&fo=jsonlccn/sn83045462/1918-11-11/ed-1/seq-1/ocr.txt…/seq-1.jsonwww.loc.gov/item/sn83045462/?fo=jsonwww.loc.gov/apis/— LoC's own API docschroniclingamerica.loc.gov/data/ocr/newspapers.jsontile.loc.gov/storage-services/…www.loc.gov/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(§4requires 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
One failure, not green. It is the environmental manifest test needing the
untracked
data/dumps. Baseline at the branch point was 1220 tests, 1failure — 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 bylemma, the collation puts
'dog(#1547258) ahead ofdog(#51134), andheadword/3took[first | _]of that. 17,403 English pages have a bare rowthat 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/doghadcommons,metandpoetrydbmappings on #1547258.Fixed by ranking the lexemes once in
build/2: lemma-is-slug, thendiffers-only-in-case, then the rest; stable and keyed only on that rank, so the
existing order survives within a tier and
pos_rank/1keeps the bare lemmafirst 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
scrollHeight168 and gotclientHeight48. 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) — anentry in the table, not a branch in
Culture. Before/after pair on/define/warat 375 is in
docs/discovery/.Where the documents were wrong or insufficient
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.
PORT=4017 mix phx.serverdoes nothing.config/dev.exshardcodesport: 4007and no config readsPORT. The guide's whole "a differentdatabase → use another port" branch is therefore not executable as written —
you must edit config. Worth fixing in the guide or in
dev.exs.app.csssources
lib/devils_dictionary_webonly.aspect-[2/3]andaspect-squarewere 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-44andsm:w-52were emitted not at all until I added the table to@source. Thiswas a live latent bug, not something I introduced.
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.
Every shared file touched, and why
lib/devils_dictionary/lexicon/word_page.extest/devils_dictionary/lexicon/word_page_test.exstest/devils_dictionary/discovery_test.exslib/devils_dictionary/discovery/content_types.excolumn+title_clamplib/devils_dictionary_web/components/culture.exassets/css/app.csstest/support/discovery/conformance.extest/devils_dictionary/discovery/content_types_test.exsdocs/discovery/README.md,docs/discovery/adding-a-provider.mddocs/integrations/chronicling-america.mdNo other shared file was touched. No existing assertion was weakened.
Left out, named as left out
/define/warand/define/telephoneshow poemsand 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, latervisits 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.
versioned, so the
'dogrows created before the fix remain; new ones arecorrect. Re-targeting them is a maintenance task and out of scope.
mix dd.provider.newwas never run, so this session cannot report on thegenerator'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.mdstill stand — or replacethe 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.
holden commentedon Sep 18, 2026
Independent audit of Phase 3b (PR #120 @
2003998) — 2026-09-18Grade: 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
mix precommit: 1,224 tests, 1 failure — the environmentalmanifest_test.exsonly. Matches.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.rank_lexemes/1inWordPage.build/2ranks lemma-equals-slug, then case-only difference, then the rest; stable, sopos_rank/1keeps the bare lemma first within its part of speech. Two regression tests that fail on the parent. Indevils_dictionary_v2the three newdogmappings (commons, met, poetrydb) target #51134dog, 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.w-44 sm:w-52, three lines for text), not a branch inCulture; 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….Retry-Aftersentence, the per-phase ceiling,PageEvidencein the quick reference.A latent bug found on the way, worth more than the phase
app.cssnever scannedcontent_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" becauseconfig/dev.exshardcodes 4007 "and no config readsPORT".config/runtime.exs:24readsPORTwith 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=4017works.Deductions
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.
Merge pull request #120 from razrfly/codex/issue-109-phase3b-chronam
holden commentedon Sep 18, 2026
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 onolid, 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:
The whole set, as the guide's §5 asks:
mix precommit: 1,252 tests, 1 failure —test/devils_dictionary/sources/manifest_test.exs:25, the environmental one needing the untrackeddata/dumps. Baseline onmainbefore this branch: 1,224 tests, 1 failure, the same file. Registering the provider reddened nothing.The ledger — 78 of 300
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
Afterwards on
devils_dictionary_v2: 946olididentifiers, 946 distinct, 946 rows withwork_details.work_kind = 'book'. The 66 matched on the first run are works the registry already held under their Wikidata QID.Browser proof
scrollWidth/define/wardocs/discovery/issue-109-phase3c-war-1280-2026-09-18.jpg/define/wardocs/discovery/issue-109-phase3c-war-375-2026-09-18.jpg/define/lovedocs/discovery/issue-109-phase3c-love-1280-2026-09-18.jpg/define/lovedocs/discovery/issue-109-phase3c-love-375-2026-09-18.jpg/define/war, rail at the books/poems boundarydocs/discovery/issue-109-phase3c-war-shelf-books-and-poems-1280-2026-09-18.jpgBooks beside poems on one Texts shelf. Byline: Open Library · attested books · PoetryDB · attested lines. On
/define/warthe 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/lovecarries 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 withEmulation.setDeviceMetricsOverride, since--window-sizedoes 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/waropens 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, runsucceeded/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 asCorpus.WikidataFamousis, 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.mdhas no worked example of a corpus walk — only of a provider — which is why this cost the phase's first hour.2.
MatchReasoncannot express a text locator that is not a line — and this is the blocking one.attestations/1builds 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, andsearch/inside.jsonreturns onepage_numfor five snippets, so there is no page locator either. The options were to put a page number in a field the renderer prints asline 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 byCulture's own composition and the year on the card. Never about.The fix is one clause:
attestations/1reading 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
@kindskeys with a gloss each, and that was enough to write the registration without openingmanifest.exfirst. The gap: the terminal printout never says where the manifest is written or that the kind string must matchManifest.new/3's. Step 4 says "build the manifest from the probe's rows and commit it" without saying where; onlydefault_path/0in the generated module answers. The generated module's moduledoc is better than the terminal text.4. Two smaller ones.
config/test.exssetsresult_limit: 3, notconfig.exs's12; 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 athttps://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@kindsentry, all five keys. The generator named it.lib/devils_dictionary/artworks/corpus/seeder.ex— theentry("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
jovana0000uttaandwolfskinder0000johnare 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.P648also publishesOL…MandOL…Aids; only work ids are kept..claude/launch.json's 4007, not 4017. 4007 was free and nothing else was ondevils_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.holden commentedon Sep 18, 2026
Independent audit of Phase 3c (PR #121 @
2254382) and the Phase 3 verdict — 2026-09-183c grade: A−. Merge it. Phase 3 grade: A−. #109 closes with this.
Reproduced
mix precommit: 1,252 tests, 1 failure — the environmentalmanifest_test.exsonly. 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: 967olididentifiers, all distinct, = 967work_kind: "book"entities = the 946-row corpus + 21 live-resolved books; every live result's entity carries anolid— 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.open-library-v1: 946 works, every row with a QID, floor 15 sitelinks, War and Peace (Q161531) as the smoke test, and aselectionblock that records why the class filter moved out of the walk.@kindsentry is complete (evidence: :none, correctly, for a text corpus)./define/warshelf 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
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 — theCorpus.WikidataFamouspattern — and the guide has no corpus-walk example. My brief was wrong; the workaround is the right general rule.MatchReason.attestations/1hardcodes 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
warreach the shelf as English. Named, in the fixture and the report; not fixed. A second signal (the snippet's own script/stopwords) is a cheap improvement for whoever touches the provider next.evidence: :none, so nothing on a word page is ever drawn from them; what the shelf shows are the live hits — Internet Archive lending scans, 2004 and 2015 titles. Same structural gap aspoetrydb-v1. Not 3c's defect (the brief asked for exactly this), but it is now two corpora that exist for identity only, and Many sources, one shelf: the Photos shelf (Openverse, Unsplash, Pexels) as the rule for every multi-source content type — memes and quotes follow it; what eventasaurus taught #116 or Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101 must decide whether attestation can be served from held text.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
MatchReasonlocator clause; the corpora-reach-no-page question; a corpus-walk example for the guide;config/test.exs'sresult_limit: 3vs12note; the parked list (GIPHY approval, Artsy retention permission, linker coverage for abstract senses, NC posture, ConceptNet). Phase 4 already lives in #101 and #97.holden commentedon Sep 18, 2026
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.
holden commentedon Sep 18, 2026
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.holden commentedon Sep 18, 2026
Second full-suite run on the same worktree: 1,252 tests, 1 failure — the environmental manifest test only. The
HealthRecordsTestfailure did not recur; order-dependent, not 3c's. Audit result and grade unchanged.Merge pull request #121 from razrfly/codex/issue-109-phase3c-openlibrary
The kit refreshed well and forgot nothing. One global `retention_seco…