mcp-libraryofcongress 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,224 @@
 # Changelog
 
+## 2.1.0
+
+- A catalogue row pointing at a collection no longer claims an identifier
+  `get_item` can take. A search of the photos catalogue for the words civil war
+  photographs returns four rows addressed at `/collections/<slug>/`, and the
+  slug read off them sent `get_item` to `/item/civil-war/`, where the Library
+  answers that it holds nothing. Reading a collection through `get_item` was
+  the other way out and was not taken: a collection is a corpus a curator
+  built, with a count of records, a set of formats and a filter that opens it,
+  and none of that fits a record's shape of rights, call number, repository and
+  served copies. `list_collections` publishes collections, `search_items` takes
+  their wording as a filter, and the item route holds a record. Such a row now
+  carries `identifier: null` beside the `source_url` that opens it, and the
+  answer counts the rows carrying no identifier and says `get_item` has nothing
+  to take for them. `list_collections` still names each collection by its slug.
+- `list_collections` says which catalogue can be asked for a collection. Of 250
+  collections read, 50 publish only formats the `media_type` enum does not hold
+  (`web-archives`, `periodicals`, `video` among them) and 6 publish none, so
+  their `collection_filter` was advertised with no value of `media_type` able to
+  carry it: asked for the Afghanistan Web Archive, all eight catalogues answer
+  with nothing, and the failure reached the caller as "nothing matches your
+  query". Each row now carries `searchable_media_types`, read off the formats
+  the Library publishes for the collection and covering the Library's several
+  spellings of one catalogue, so `video` and `prints-and-photographs` name
+  `film-and-videos` and `photos`. A row naming none says so with an empty list,
+  a note counts those rows and names the formats behind them, and the new
+  `searchable_only` argument leaves them out.
+- `search_items` no longer reports the unfiltered total as the count for the
+  query as sent. A search whose filter matched nothing is asked again without
+  it, and both the heading and `total` then gave the figure of the wider
+  search, 311,225 for `history` in the books catalogue, as the number of records
+  matching a search that matched none, with one note saying the rows were
+  unfiltered while a second repeated the figure as a plain fact. Every
+  sentence carrying the count now names the search it counts, the set-aside note
+  states that the search as sent matched none, and `total` says the same in its
+  description. The advice that note gives points at where each filter's wording
+  is published: a subject and a place on a row, a language written in English,
+  and a collection under `collection_filter` in `list_collections`.
+- `search_newspapers` calls an excerpt a `passage` only when the page's
+  machine-read text carries a searched word as a word. Locating a term as a run
+  of letters found `art` inside _particular_, _impartially_, _parts_ and the
+  scanning noise _ARtloulttuat_, and `cat` inside _Cattle_: on `art gallery`,
+  four of the eight rows labelled `passage` were about wrinkle cream, harness
+  parts and a county fair, and each of them was excluded from the count of page
+  openings and handed over as the text around the words that matched. A term is
+  now found on a word boundary, in any case and with punctuation allowed to sit
+  against either end, which is what machine-read text does to a word. A row
+  where no term stands as a word is a `page_opening`, counted as one, and its
+  excerpt is the start of the page. Measured again on the same three queries:
+  thirty rows, eleven `passage` labels, all eleven carrying the words.
+- `search_items` no longer publishes a day and a month a row does not carry.
+  The catalogue files every row under one sortable date and fills what the
+  record leaves unsaid, so a photograph whose words say `1860` came back as
+  `1860-01-01`: on one measured page, twenty-three rows of twenty-five. `date`
+  and `year` on a row are now cut back to the precision the row's own words
+  support, read from the record block the row nests and the years the index
+  files it under, so a row and the record behind it state the same date.
+- A record naming a date of its own beside a range of other years keeps that
+  date. `photographed 1864, [printed between 1880 and 1889]` was reported as
+  1864 being the opening of a span, which denies the year the record states
+  outright. The note is now raised only when the record's own words write a
+  range out and open it on the year the catalogue files the record under.
+- `search_items` reads a page past the last one for what it is. The catalogue
+  answers such a page with a 404, which came back as `not_found` and the words
+  "the Library of Congress holds nothing at this address" on a call that
+  carries no address and about records that exist. The first page is read for
+  how many records match, and the answer says which page was asked for, how
+  many records match and across how many pages.
+- `search_items` searches a one-character word written in a script where one
+  character is a word. Refusing every query whose words run to a single
+  character refused `水`, and claimed as a property of the Library something the
+  catalogue disproves: on the books catalogue `山水` matches 57 records and
+  `水 山水` matches one, so the index does act on the character. Han, Japanese
+  and Korean script are searched as they stand, and what the catalogue answers
+  for them, including an answer of none, is reported as the answer it is. The
+  refusal that remains is for a query whose every word is a single letter.
+- `get_item` no longer publishes a day and a month the record does not carry.
+  The catalogue files every record under one sortable date and fills what the
+  record leaves unsaid: `mss412100053`, titled twice over as undated, is filed
+  at `1848-01-01`, which is the opening of the span its series covers, and a
+  record whose own words say `1925.` is filed at `1925-01-01`. `date` is now cut
+  back to the precision the record's own words support, `year` reads that value,
+  and the new `date_stated` carries those words. A record filed at the opening
+  of a span of years says so in a note. A record whose words name a month or a
+  day keeps the date as filed, and so does a record that says nothing about its
+  date, since it offers nothing to read the filed value against.
+- `search_items` refuses a query whose every word is a single letter.
+  The catalogue index holds no word of a single letter: on the books
+  catalogue `a`, `b` and `a b` each match nothing, `zz` matches 35,895, and
+  `a of` returns exactly the 748,064 that `of` returns alone. Answering with a
+  total of zero and "nothing in the books catalogue matches" reported a property
+  of the index as a fact about the collection. The refusal is `invalid_input`
+  and names the reason.
+- The note on newspaper matches whose excerpt is the opening of the page says
+  where the `[page opening]` mark is written. The mark rides on each excerpt in
+  the text block; the excerpts in the structured answer hold the machine-read
+  text as it stands, with nothing added to them, and the note names
+  `excerpt_kind` as what carries the distinction there.
+
+- `list_collections` says where paging through the corpus stops. The Library
+  publishes 583 collections and divides them into twelve pages of fifty; on the
+  twelfth the answer still read "583 collections exist and 33 are shown. Ask for
+  page 13 to continue", and page 13 came back as `not_found` with the words the
+  Library uses for an address it holds nothing at. The next page is now offered
+  only where the Library has one, the last page says it is the last and how many
+  pages the corpus runs to at the size asked for, and a page past the last is
+  answered as an empty page of a corpus that exists. `page` stops at 100, which
+  at a small `limit` stops short of the corpus: at a `limit` of 5 the answer now
+  says that 500 of the 583 collections are within reach and that raising `limit`
+  brings the rest.
+- `search_items` states an identifier a row does not carry. Searching the
+  manuscripts catalogue for abraham lincoln papers returns the Abraham Lincoln
+  Papers collection, whose `identifier` is null, and the text block printed that
+  row with nothing where the others carry `id:`, which reads as an identifier
+  that went unprinted rather than one that does not exist. Such a line now
+  states the absence, and the tool description says an identifier comes with a
+  row that names a record instead of promising one on every row.
+- A row that is a collection says so. On the same search, one row of the five is
+  the corpus a curator built and named rather than a manuscripts record, its
+  format reads `collection`, and the catalogue's count of 24,836 counts it in.
+  Rows now carry `is_collection`, and where any are present a note counts them,
+  says the item route holds nothing at their address, and says that the count
+  beside the rows counts them in.
+- A cataloguing code is no longer published as a date. The Library files a
+  record whose digits it has not established under a code standing in for them,
+  so `uuuu` means an unknown year and `18??` a year known only to its century:
+  `2002556854`, Gen. Lafayette's grand march, came back as `(18??)` in the slot
+  every other row fills with a year. `date` and `year` are null for such a
+  record, the new `date_code` carries the code under a name saying what it is, a
+  note says the Library has established no date, and `date_stated` still repeats
+  the record's own words, here `Philadelphia : Geo. Willig, [18--]`.
+- A filed date is kept whole only where the record's own words name the month it
+  is filed under. Asking whether those words named any month at all kept
+  `1934-01-01` on `2004663673`, a Van Vechten self-portrait the record dates
+  `1934 May 8.`, and kept `1483-01-01` on an incunable printed `1483-02-17`. The
+  month the catalogue filed the record under is now read against the months the
+  words name, and the value is cut back to the year when they do not name it. A
+  month word counts only where a day or a year stands beside it, so `may` in a
+  sentence and `march` in a title name no month, and a year with two digits
+  after a hyphen names a month only when the year is the one the record is filed
+  under, so `1908-09` beside a record filed at 1908 is 1908 to 1909.
+- `search_newspapers` searches a query of one character. The two searches
+  refused a short query in two unrelated shapes: `search_items` in its own words
+  with a reason and a hint, `search_newspapers` in the validation framework's,
+  as "Too small: expected string to have >=2 characters". The full-text index of
+  the newspaper corpus does hold single characters and answers each with a set
+  of its own: `a` matches 23,522,867 pages, `x` 13,323,103 and `q` 7,885,360, so
+  the minimum refused a question the corpus answers. It is gone. The catalogue
+  index holds no such word, `a` and `x` each matching none of the 798,435 books,
+  and `search_items` keeps its refusal in its own words.
+- What double quotes do to a newspaper search is stated as measured rather than
+  as a rule. The tools, the server instructions and the README all said quoting
+  narrows the search sharply and that dropping the quotes finds far more again.
+  Measured on ten queries, the count moves by no fixed amount and not always in
+  the same direction: `"iron horse"` matches 31,783 pages against 3,393,506
+  unquoted and `"good morning"` 129,769 against 12,219,078, while `"new york"`
+  matches 14,464,911 against 15,353,114, and `"of the"` matches 20,624,639
+  against 5,419,814 for the same words unquoted. What the quotes govern is how
+  the Library matches: a page can come back carrying the words apart or in
+  another order rather than the phrase as written. That is what is now said,
+  with the count named as no measure of the phrase and both forms worth asking.
+- `get_item` refuses an identifier carrying a control character. Such an
+  identifier was percent-encoded into the address and sent, and the Library
+  answered for something nobody publishes: `2017\u0001645459` came back as a
+  timeout and an escape sequence before the same digits as HTTP 500, where an
+  identifier climbing out of the item route was already refused as
+  `invalid_input` with its reason. Both are malformed identifiers and both are
+  now refused before an address is built. The refusal for a control character
+  names no identifier: those characters are the ones a terminal, a log and a
+  chat window do not draw, so printing the value back would show a different
+  spelling from the one that was sent.
+- Counts agree with the numbers they carry. A single match reported `On 1 of 2
+match(es)`, `1 match(es) came back`, `1 row(s) shown carry no date`, `431
+records match and 1 are shown` and `583 collections exist and 1 are shown`.
+  The parenthesised plural is gone and the nouns and verbs beside a count now
+  take the form that count takes, across the four tools.
+- `get_item` no longer returns the same words twice. The Library assembles the
+  description of some records by running the notes it holds on them together, so
+  `03027877` returned `First appeared in Tait's magazine, 1847-1849.` as its
+  whole description and again as `notes_on_record[0]`, and `2021617173` returned
+  its five notes both ways. A note whose words the description already carries
+  is left to the description, where it is published whole and paginates, and the
+  field says so in its own description.
+
+## 2.0.0
+
+### Breaking change
+
+`search_newspapers` no longer returns `words_located`. Each match now carries
+`excerpt_kind`, one of `"passage"` or `"page_opening"`. A caller reading
+`words_located === true` reads `excerpt_kind === "passage"`, and the false case
+reads `"page_opening"`.
+
+The boolean and the excerpt disagreed about what they were. `words_located:
+false` means the machine-read text the Library returned stops before the
+searched words, so the excerpt beside it is the **opening of the page** and does
+not carry the match. It sat in the answer in the same place and the same shape
+as a real passage, and a note beside it was the only thing saying otherwise.
+Measured on a live search, four matches in five were openings. Naming the kind
+of thing an excerpt is puts that where it cannot be skipped.
+
+### Also in this release
+
+- Every excerpt is now labelled in the rendered text itself, as
+  `[passage]` or `[page opening]` ahead of the words, so the mark travels with
+  the text a reader copies.
+- The tool described quoting as matching a phrase whole. It does not. Measured:
+  `"hell is other people"` quoted returns 18 pages, unquoted 1,634,731, and
+  among the quoted results are pages from 1891, 1897 and 1906, which precede the
+  line by half a century. Quoting narrows hard and decides nothing about how the
+  Library matches. The promise is gone from the tool description and from both
+  halves of the README, and a quoted query now carries a note saying the match
+  is not guaranteed to be the phrase.
+- Headings said the pages carry the query. They say what the Library matched.
+
+`NewspaperHit.wordsLocated`, on the `./client` subpath, is unchanged: it is the
+raw fact about the text received, and the tool layer names the kind of thing it
+renders from it.
+
 ## 1.1.0
 
 - An argument no tool declared was read and dropped, and the answer came back

package/README.md

@@ -55,7 +55,7 @@ npm and no configuration file to edit.
 | `search_newspapers` | Finds a phrase in the text of scanned newspaper pages.    | `query`, `location`, `publication`, `year_from`, `limit`  |
 | `search_items`      | Searches one catalogue: books, photos, maps, audio, more. | `query`, `media_type`, `subject`, `location`, `year_from` |
 | `get_item`          | Reads one record, section by section.                     | `identifier`, `sections`, `offset`                        |
-| `list_collections`  | The digital collections, with the filter each one takes.  | `limit`, `page`, `max_description_chars`                  |
+| `list_collections`  | The digital collections, with the filter each one takes.  | `limit`, `page`, `searchable_only`                        |
 
 The server is **read-only**. It uploads nothing and writes nothing back.
 
@@ -64,12 +64,19 @@ The server is **read-only**. It uploads nothing and writes nothing back.
 A catalogue search reads titles, creators and descriptions. `search_newspapers`
 reads what optical character recognition took off millions of scanned pages of
 American newspapers, so it answers a question nothing else here can: _which
-issue printed this phrase_. A match comes back with the paper, the date, the
+issue printed these words_. A match comes back with the paper, the date, the
 leaf of the issue, the state it was published in, and an address that opens that
 leaf with the query applied.
 
-Put a phrase in double quotes to match it whole. Without quotes the words are
-matched separately, which finds far more.
+Double quotes change what the search matches, and the Library decides what they
+mean: a matched page can carry the words apart or in another order rather than
+the phrase as written, so an answer to a quoted query says so and points at the
+page to read. What the quotes do to the number of matching pages is the
+Library's own business and varies from one query to the next: measured against
+the corpus, quoting divides the count by a hundred on some queries, moves it by
+a few per cent on others, and raises it above the unquoted count on others
+again. The count is therefore no evidence that the phrase was printed anywhere,
+and both forms are worth asking.
 
 The corpus spans every state and a century and a half, so a bare phrase reaches
 a great deal that a question did not ask for. Three arguments narrow it:
@@ -101,9 +108,14 @@ page 2, 3 and so on rather than treating the first answer as the whole of it.
 
 **An excerpt is sometimes the opening of the page.** The Library returns the
 beginning of a page's text with each row rather than the whole page, so the
-searched words are often further down than that text reaches. `words_located`
-says which of the two happened: true and the passage is centred on the words,
-false and it is the opening of the leaf. Follow `source_url` for the rest.
+searched words are often further down than that text reaches. Every match
+carries `excerpt_kind`, and every excerpt is labelled with it in the text block:
+
+- **`passage`**, the text around the words that matched, centred on them.
+- **`page_opening`**, the start of the leaf, sent because the text that came
+  back stops before the searched words appear. It does not carry the match, so
+  quoting it quotes something else. The notes count how many there are, and
+  `source_url` opens the leaf with the query applied.
 
 **Scanned text is machine-read.** Excerpts carry the misreadings that come with
 it. Quote them as scanned text and link the page.
@@ -120,11 +132,24 @@ Narrowing is typed rather than free text: `year_from`, `year_to`, `subject`,
 matches nothing is set aside, the search is asked again without it, and the
 answer names what was dropped, so a narrowing that spelled a subject the Library
 words differently is reported as a spelling that found nothing rather than as
-the Library holding nothing on it.
+the Library holding nothing on it. Every sentence carrying the count then names
+the search without the filter, since that is the search the rows and the count
+come from.
 
 By default only material with a digitised copy comes back. `online_only: false`
 takes in the records the Library holds on a shelf alone.
 
+**The catalogue index holds no word of a single letter.** A query made only of
+such words matches nothing whatever the Library holds, and the same query with
+one longer word beside them returns exactly what that longer word returns alone.
+`search_items` refuses it as invalid input and names the reason, since a count
+of zero would read as a statement about the collection. A word written as one
+character, as Han, Japanese and Korean script write many, is a word the index
+does hold, and it is searched as it stands. The full-text index behind
+`search_newspapers` is a different index and does hold single characters,
+answering each with a set of its own, so `search_newspapers` searches for one
+rather than refusing it.
+
 ## Reading a record, and finding a corpus
 
 `get_item` takes one identifier. An identifier can carry slashes: a single
@@ -135,10 +160,61 @@ full field list are each larger than the record they describe. A long
 description paginates by character offset and resumes at a line boundary: when
 `next_offset` is not null, call again with `offset` set to it.
 
+**A malformed identifier is refused rather than answered.** An identifier that
+climbs out of the item route, or one carrying a control character, is
+`invalid_input` before any address is built. The refusal for a control character
+names no identifier: those characters are the ones a terminal, a log and a chat
+window do not draw, so printing the value back would show a different spelling
+from the one that was sent.
+
+**The same words are not returned twice.** The Library assembles the description
+of some records by running the notes it holds on them together. A note whose
+words the description already carries is left to the description, so
+`notes_on_record` holds what the description does not.
+
+**A row says whether it is a record or a collection.** A catalogue search
+returns, beside its records, the corpora a curator gathered and named, and the
+Library's count of what matches counts them in. Such a row carries
+`is_collection: true`, its `identifier` is null because the item route holds
+nothing at a collection's address, and `source_url` opens the collection. A row
+carrying no identifier says so where the others print theirs, and the notes
+count both kinds.
+
+**A cataloguing code is not a date.** Where the Library has established no date
+it files a record under a code standing in for the digits, `uuuu` for an unknown
+year and `18??` for a year known only to its century. `date` and `year` are null
+for such a record, `date_code` carries the code under a name saying what it is,
+and the notes say no date has been established.
+
+**A date carries only the precision the record supports.** The catalogue files
+every record under one sortable date and fills what the record leaves unsaid: a
+record whose own words say `1925` is filed at `1925-01-01`, and a piece of a
+series is filed at the opening of the span the series covers. `date` is cut back
+to the precision those words support, in a catalogue row as in a record read on
+its own: the filed value is kept whole only where the words name the month it is
+filed under, so a photograph the record dates `1934 May 8.` and the catalogue
+files at `1934-01-01` comes back as `1934`. A month word counts only where a day
+or a year stands beside it, and a year with two digits after a hyphen names a
+month only when that year is the one the record is filed under, so `1908-09`
+beside a record filed at 1908 reads as 1908 to 1909. `date_stated` repeats the
+words themselves, and a record whose words
+write out a span of years and open it on the filed year carries a note saying
+that `date` and `year` are where the catalogue sorts it. A year the words state
+outright is a date of the record, whatever ranges sit beside it.
+
 `list_collections` shows the bodies of material a curator chose, described and
 published together, so a caller can see what is there before searching. Each row
-carries `collection_filter`, which is the wording `search_items` takes as its
-`collection` argument.
+carries `collection_filter`, the wording `search_items` takes as its
+`collection` argument, beside `searchable_media_types`, the catalogues that
+filter can be sent to. The Library gathers kinds of thing the catalogue search
+is not divided into, web archives and periodicals among them: such a collection
+names no `media_type`, says so with an empty list, and `searchable_only` leaves
+those rows out. The corpus runs to hundreds of collections and pages: the answer
+offers the next page only where the Library has one, says when the last has been
+reached and how many pages the corpus runs to at the size asked for, and reads a
+page past the last as an empty page of a corpus that exists. `page` stops at
+100, so at a small `limit` the answer says how many collections that ceiling
+reaches and that raising `limit` brings the rest within reach.
 
 ## What the answers claim
 
@@ -329,7 +405,7 @@ configuration à modifier.
 | `search_newspapers` | Trouve une phrase dans le texte des pages de journaux numérisées. | `query`, `location`, `publication`, `year_from`, `limit`  |
 | `search_items`      | Cherche un catalogue : livres, photos, cartes, sons, et le reste. | `query`, `media_type`, `subject`, `location`, `year_from` |
 | `get_item`          | Lit une fiche, section par section.                               | `identifier`, `sections`, `offset`                        |
-| `list_collections`  | Les collections numériques, avec le filtre que chacune accepte.   | `limit`, `page`, `max_description_chars`                  |
+| `list_collections`  | Les collections numériques, avec le filtre que chacune accepte.   | `limit`, `page`, `searchable_only`                        |
 
 Le serveur est **en lecture seule**. Il ne téléverse rien et n'écrit rien.
 
@@ -338,13 +414,21 @@ Le serveur est **en lecture seule**. Il ne téléverse rien et n'écrit rien.
 Une recherche de catalogue lit les titres, les auteurs et les descriptions.
 `search_newspapers` lit ce que la reconnaissance de caractères a tiré de
 millions de pages de journaux américains numérisées, et répond donc à une
-question qu'aucun autre outil ici ne sait traiter : _quel numéro a imprimé cette
-phrase_. Une correspondance revient avec le journal, la date, le feuillet du
+question qu'aucun autre outil ici ne sait traiter : _quel numéro a imprimé ces
+mots_. Une correspondance revient avec le journal, la date, le feuillet du
 numéro, l'État de publication, et une adresse qui ouvre ce feuillet avec la
 requête appliquée.
 
-Mettez une phrase entre guillemets doubles pour la faire correspondre en entier.
-Sans guillemets, les mots sont cherchés séparément, ce qui trouve bien plus.
+Les guillemets doubles changent ce que la recherche retient, et c'est la Library
+qui décide de ce qu'ils veulent dire : une page retenue peut porter les mots
+éloignés les uns des autres ou dans un autre ordre plutôt que la phrase telle
+qu'elle est écrite. La réponse à une requête entre guillemets le dit et renvoie
+à la page à lire. Ce que les guillemets font au nombre de pages retenues
+appartient à la Library et varie d'une requête à l'autre : mesuré sur le corpus,
+le compte est divisé par cent sur certaines requêtes, bouge de quelques pour
+cent sur d'autres, et dépasse le compte sans guillemets sur d'autres encore. Ce
+compte ne prouve donc pas que la phrase ait été imprimée quelque part, et les
+deux formes valent d'être posées.
 
 Le corpus couvre tous les États et un siècle et demi : une phrase seule ramène
 donc beaucoup de choses que la question ne demandait pas. Trois arguments la
@@ -379,9 +463,15 @@ que de prendre la première réponse pour la totalité.
 **Un extrait est parfois le début de la page.** La Library renvoie le début du
 texte d'une page avec chaque ligne de résultat plutôt que la page entière, si
 bien que les mots cherchés se trouvent souvent plus bas que ce texte ne va.
-`words_located` indique lequel des deux cas s'est produit : vrai et le passage
-est centré sur les mots, faux et c'est le début du feuillet. Suivez `source_url`
-pour la suite.
+Chaque correspondance porte `excerpt_kind`, et chaque extrait en porte
+l'étiquette dans le bloc de texte :
+
+- **`passage`** : le texte autour des mots correspondants, centré sur eux.
+- **`page_opening`** : le début du feuillet, renvoyé parce que le texte reçu
+  s'arrête avant que les mots cherchés n'apparaissent. Il ne porte pas la
+  correspondance, donc le citer revient à citer autre chose. Les notes comptent
+  combien il y en a, et `source_url` ouvre le feuillet avec la requête
+  appliquée.
 
 **Le texte numérisé est lu par une machine.** Les extraits en portent les
 fautes. Citez-les comme tels et suivez le lien.
@@ -397,11 +487,25 @@ Le filtrage est typé plutôt que textuel : `year_from`, `year_to`, `subject`,
 `location`, `language`, `collection`, `online_only`, `sort`. Un filtre qui ne
 correspond à rien est mis de côté, la recherche est relancée sans lui, et la
 réponse nomme ce qui a été écarté : une orthographe différente de celle de la
-Library est ainsi signalée comme telle, et non comme un fonds vide.
+Library est ainsi signalée comme telle, et non comme un fonds vide. Chaque
+phrase qui porte le total nomme alors la recherche sans le filtre, puisque c'est
+d'elle que viennent les lignes et le compte.
 
 Par défaut, seuls les documents disposant d'une copie numérisée reviennent.
 `online_only: false` inclut les fiches que la Library ne conserve qu'en rayon.
 
+**L'index du catalogue ne retient aucun mot d'une seule lettre.** Une requête
+composée uniquement de tels mots ne correspond à rien, quoi que la Library
+détienne, et la même requête accompagnée d'un mot plus long rend exactement ce
+que ce mot rend seul. `search_items` la refuse en `invalid_input` en donnant la
+raison, car un total de zéro se lirait comme une affirmation sur le fonds. Un
+mot qui s'écrit d'un seul caractère, comme les écritures han, japonaise et
+coréenne en comptent beaucoup, est un mot que l'index retient : il est cherché
+tel quel. L'index plein texte derrière `search_newspapers` est un autre index,
+qui retient bel et bien les caractères isolés et répond à chacun par un ensemble
+qui lui est propre : `search_newspapers` cherche un tel caractère au lieu de le
+refuser.
+
 ## Lire une fiche, et trouver un corpus
 
 `get_item` prend un identifiant. Un identifiant peut contenir des barres
@@ -413,10 +517,63 @@ qu'elles décrivent. Une description longue se pagine par décalage de caractèr
 et reprend à une fin de ligne : quand `next_offset` n'est pas nul, rappelez
 l'outil avec `offset` réglé sur cette valeur.
 
+**Un identifiant mal formé est refusé, pas répondu.** Un identifiant qui sort de
+la route des fiches, ou qui porte un caractère de contrôle, est `invalid_input`
+avant qu'aucune adresse ne soit construite. Le refus lié à un caractère de
+contrôle ne cite aucun identifiant : ces caractères sont ceux qu'un terminal, un
+journal ou une fenêtre de discussion ne dessinent pas, et le réimprimer
+montrerait une graphie différente de celle qui a été envoyée.
+
+**Les mêmes mots ne sont pas rendus deux fois.** La Library compose la
+description de certaines fiches en mettant bout à bout les notes qu'elle tient
+sur elles. Une note dont la description porte déjà les mots est laissée à la
+description : `notes_on_record` tient ce que la description ne porte pas.
+
+**Une ligne dit si elle est une fiche ou une collection.** Une recherche
+catalogue rend, à côté de ses fiches, les corpus qu'un conservateur a réunis et
+nommés, et le compte que la Library publie les inclut. Une telle ligne porte
+`is_collection: true`, son `identifier` est null parce que la route des fiches
+ne détient rien à l'adresse d'une collection, et `source_url` l'ouvre. Une ligne
+sans identifiant l'énonce là où les autres impriment le leur, et les notes
+comptent les deux cas.
+
+**Un code de catalogage n'est pas une date.** Là où la Library n'a établi
+aucune date, elle range la fiche sous un code qui tient lieu de chiffres :
+`uuuu` pour une année inconnue, `18??` pour une année connue au siècle près.
+`date` et `year` sont null pour une telle fiche, `date_code` porte le code sous
+un nom qui dit ce qu'il est, et les notes disent qu'aucune date n'est établie.
+
+**Une date ne porte que la précision que la fiche soutient.** Le catalogue range
+chaque fiche sous une date unique et comble ce que la fiche laisse de côté : une
+fiche dont les mots disent `1925` est rangée au `1925-01-01`, et une pièce d'un
+fonds est rangée à l'ouverture de la période que ce fonds couvre. `date` est
+ramenée à la précision que ces mots soutiennent, dans une ligne de résultat
+comme dans une fiche lue seule : la valeur de rangement n'est gardée entière que
+si les mots nomment le mois sous lequel la fiche est rangée, si bien qu'une
+photographie que la fiche date du `1934 May 8.` et que le catalogue range au
+`1934-01-01` revient en `1934`. Un nom de mois ne compte que si un jour ou une
+année l'accompagne, et une année suivie de deux chiffres après un tiret ne nomme
+un mois que si cette année est celle du rangement : `1908-09` à côté d'une fiche
+rangée en 1908 se lit 1908 à 1909. `date_stated` reprend les mots eux-mêmes, et une
+fiche dont les mots écrivent une période et l'ouvrent sur l'année de rangement
+porte une note disant que `date` et `year` sont l'endroit où le catalogue la
+classe. Une année que les mots énoncent en toutes lettres est une date de la
+fiche, quelles que soient les fourchettes qui l'accompagnent.
+
 `list_collections` montre les ensembles qu'un conservateur a choisis, décrits et
 publiés ensemble, pour voir ce qui existe avant de chercher. Chaque ligne porte
 `collection_filter`, la formulation exacte que `search_items` accepte dans son
-argument `collection`.
+argument `collection`, et `searchable_media_types`, les catalogues auxquels ce
+filtre peut être adressé. La Library réunit des types de documents que la
+recherche catalogue ne découpe pas, les archives du web et les périodiques parmi
+eux : une telle collection ne nomme aucun `media_type`, le dit par une liste
+vide, et `searchable_only` écarte ces lignes. Le corpus compte plusieurs
+centaines de collections et se pagine : la réponse ne propose la page suivante
+que là où la Library en a une, dit quand la dernière est atteinte et sur combien
+de pages le corpus court à la taille demandée, et lit une page au-delà de la
+dernière comme une page vide d'un corpus qui existe. `page` s'arrête à 100 :
+à faible `limit`, la réponse dit combien de collections ce plafond atteint et
+que relever `limit` met le reste à portée.
 
 ## Ce que les réponses affirment