primarysource 0.1.0__py3-none-any.whl

primarysource/itu/cli.py

@@ -0,0 +1,445 @@
+"""`primarysource itu` (formerly `itulib`) - fetch, index, then ask.
+
+`fetch` and `sync` are the only commands that touch the network, and they write outside the checkout by
+default. Everything that reads refuses to answer when the corpus or index is absent, naming the command that
+fixes it; an empty result here is always a real empty, never a swallowed failure.
+
+References use one grammar everywhere: `X.690§11.6¶2` (`¶n` is the nth sentence of the extracted clause), or
+the looser `X.690 11.6` and `11.6` (which means X.690). `X.690§11.6¶5-` is the clause from its 5th sentence on,
+which is what a paged read says to continue with.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+
+from primarysource.errors import LibError
+
+from . import __version__, corpus, index, sources, text
+from .errata import errata_text
+
+DEFAULT = "X.690"
+
+
+def _resolve(ref: str) -> tuple[sources.Edition, str, int | None]:
+    rec, number, para = text.parse_ref(ref)
+    return sources.resolve(rec or DEFAULT), number, para
+
+
+def _join(parts: list[str]) -> str:
+    return " ".join(parts)
+
+
+def cmd_info(_args: argparse.Namespace) -> int:
+    for item in (*sources.IN_FORCE, *sources.SUPERSEDED):
+        state = "fetched" if corpus.has(item) else "-"
+        print(f"{item.key:18} {item.status:11} {item.octets:>10,} B  {state:8} {item.title}")
+    for amendment in sources.AMENDMENTS:
+        fetched = "fetched" if amendment.artifact and corpus.has(amendment) else "-"
+        print(f"{amendment.key:18} {amendment.status:11} {'':>12}  {fetched:8} {amendment.label}")
+    print(f"corpus home: {corpus.home()}")
+    return 0
+
+
+def cmd_fetch(args: argparse.Namespace) -> int:
+    document = sources.resolve_document(args.target)
+    path = corpus.fetch(document, refresh=args.refresh)
+    print(f"fetched {document.key} -> {path} ({path.stat().st_size:,} B)")
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    """Fetch and index each in-force edition. One failure is reported and does not stop the rest, and the exit
+    status is non-zero if any failed, because a sync that quietly skips reports the same green as one that ran."""
+    everything = (*sources.IN_FORCE, *sources.SUPERSEDED)
+    targets = (
+        [sources.resolve(name) for name in args.targets]
+        if args.targets
+        else list(everything if args.all else sources.IN_FORCE)
+    )
+    failed: list[str] = []
+    for edition in targets:
+        try:
+            corpus.fetch(edition)
+            count = index.build(edition)
+            print(f"{edition.key:16} ok  {count:>5} clauses")
+        except LibError as error:
+            failed.append(edition.key)
+            print(f"{edition.key:16} FAILED  {error.as_text()}", file=sys.stderr)
+        except (RuntimeError, OSError) as error:
+            failed.append(edition.key)
+            print(f"{edition.key:16} FAILED  {error}", file=sys.stderr)
+    return 3 if failed else 0
+
+
+def cmd_index(args: argparse.Namespace) -> int:
+    edition = sources.resolve(args.edition)
+    print(f"{edition.key}: {index.build(edition)} clauses indexed")
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    edition = sources.resolve(args.edition)
+    query = _join(args.query)
+    found = index.search(edition, query, args.limit, args.start)
+    if found.relaxed:
+        print("note: no clause contains every term; these contain some of them\n", file=sys.stderr)
+    if not found.hits:
+        print(f"{edition.key}: no clause matches {query!r} (this is a real empty: the index is loaded)")
+        return 1
+    for hit in found.hits:
+        print(f"{index.citation(edition, hit.number)}  {hit.title}\n    {hit.excerpt}\n")
+    if found.next_start is not None:
+        print(f"[more: continue with --start {found.next_start}]")
+    return 0
+
+
+def cmd_read(args: argparse.Namespace) -> int:
+    ref = _join(args.ref)
+    document = next((a for a in sources.AMENDMENTS if a.key == args.ref[0]), None)
+    if document is not None:
+        print(document.label, "", errata_text(document), sep="\n")
+        return 0
+    target = text.parse_target(ref)
+    edition, number, para = sources.resolve(target.rec or DEFAULT), target.number, target.para
+    start = para if target.onward and para is not None else args.start
+    if target.onward:
+        para = None
+    if args.view == "normative":
+        found = index.normative_statements(edition, number)
+        if found is None:
+            print(f"{edition.key}: no clause §{number}", file=sys.stderr)
+            return 1
+        for n, sentence in found:
+            print(f"{index.citation(edition, number, n)}\n    {sentence}")
+        return 0
+    if args.view == "refs":
+        return _print_links(edition, number)
+    if para is not None:
+        one = index.sentence(edition, number, para)
+        if one is None:
+            print(f"{edition.key}: §{number} has no ¶{para}", file=sys.stderr)
+            return 1
+        print(f"{index.citation(edition, number, para)}\n\n{one}")
+        return 0
+    page = index.page(edition, number, start=start, max_tokens=args.max_tokens)
+    if page is None or page.total == 0:
+        kids = index.children(edition, number)
+        if kids:
+            print(f"{index.citation(edition, number)}: heading only; subclauses:")
+            for child, title in kids:
+                print(f"  {child:10} {title}")
+            return 0
+        if page is None:
+            print(f"{edition.key}: no clause §{number}", file=sys.stderr)
+            return 1
+        print(f"{index.citation(edition, number)}  {page.title}: heading with no text and no indexed subclauses")
+        return 0
+    print(f"{index.citation(edition, page.number)}  {page.title}\n")
+    print(page.text)
+    if page.next is not None:
+        doc = edition.rec if sources.resolve(edition.rec) is edition else edition.key
+        print(
+            f"\n[¶{page.first}-{page.last} of {page.total}; continue with: read '{doc}§{page.number}¶{page.next}-']"
+        )
+    extra = index.fragments(edition, number) - 1
+    if extra:
+        print(
+            f"\nwarning: {extra} other extracted fragment(s) share the number {number}; this is the first. "
+            "Check the PDF before relying on it.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def cmd_cite(args: argparse.Namespace) -> int:
+    edition, number, para = _resolve(_join(args.ref))
+    if index.read(edition, number) is None:
+        print(f"{edition.key}: no clause §{number}; refusing to cite what is not there", file=sys.stderr)
+        return 1
+    print(index.citation(edition, number, para))
+    return 0
+
+
+def _print_links(edition: sources.Edition, number: str) -> int:
+    found = index.links(edition, number)
+    if found is None:
+        print(f"{edition.key}: no clause §{number}", file=sys.stderr)
+        return 1
+    print(index.citation(edition, number))
+    for label, values in (
+        ("points at", found.clauses),
+        ("unresolved", found.unresolved),
+        ("recommendations", found.recommendations),
+        ("standards", found.standards),
+        ("cited by", found.cited_by),
+    ):
+        print(f"  {label:16} {', '.join(values) if values else '-'}")
+    return 0
+
+
+def cmd_compare(args: argparse.Namespace) -> int:
+    first, second = sources.resolve(args.edition_a), sources.resolve(args.edition_b)
+    _rec, number, _para = text.parse_ref(args.number)
+    result = index.compare(first, second, number)
+    print(f"{index.citation(first, number)}  ->  {index.citation(second, number)}")
+    if not (result.in_a and result.in_b):
+        side = first.key if not result.in_a else second.key
+        print(f"§{number} does not exist in {side}; the rule may have moved rather than gone.")
+        return 1
+    if result.same:
+        print("identical (ignoring whitespace and case)")
+        return 0
+    for para, sentence in result.removed:
+        print(f"- [¶{para}] {sentence}")
+    for para, sentence in result.added:
+        print(f"+ [¶{para}] {sentence}")
+    return 0
+
+
+def cmd_catalog_sync(args: argparse.Namespace) -> int:
+    """Read series listings (about one request each), then, with --details, each recommendation's pages."""
+    from . import catalog
+
+    letters = list(sources.SERIES) if args.series == ["all"] else [s.upper() for s in args.series]
+    fetcher = catalog.Fetcher(catalog.catalog_dir() / "cache")
+    for letter in letters:
+        count = catalog.sync_listing(letter, fetcher, refresh=args.refresh)
+        print(f"series {letter}: {count} recommendations listed")
+        if args.details:
+            done, pages = catalog.sync_details(
+                letter,
+                fetcher,
+                limit=args.limit,
+                only=args.rec or None,
+                include_withdrawn=args.include_withdrawn,
+                refresh=args.refresh,
+                reparse=args.reparse,
+                progress=lambda message: print("  " + message, flush=True),
+            )
+            print(f"series {letter}: {done} recommendations detailed, {pages} component pages read")
+    print(f"{fetcher.requests} request(s) made to itu.int")
+    return 0
+
+
+def cmd_catalog_list(args: argparse.Namespace) -> int:
+    from . import catalog
+
+    recs = catalog.load(args.series.upper())
+    found = catalog.rows(recs, text=args.text, fmt=args.format, free_only=args.free)
+    for row in found[: args.limit]:
+        print(f"{row.rec:10} {row.kind:11} {row.label:42} {row.summary():34} {row.title}")
+    shown = min(len(found), args.limit)
+    detailed = sum(1 for entry in recs.values() if entry.get("components") is not None)
+    print(
+        f"\n{shown} of {len(found)} shown; {detailed} of {len(recs)} recommendations in series {args.series.upper()}"
+        f" have details (sync with --details for the rest). * = not freely available."
+    )
+    return 0 if found else 1
+
+
+def cmd_catalog_show(args: argparse.Namespace) -> int:
+    from . import catalog
+
+    rec = args.rec
+    entry = catalog.load(rec[0].upper()).get(rec)
+    if entry is None:
+        print(f"{rec}: not in the catalogue. Run: primarysource itu catalog sync {rec[0].upper()}", file=sys.stderr)
+        return 1
+    print(f"{rec}  [{entry.get('status')}]  {entry.get('title')}")
+    if entry.get("note"):
+        print(f"  note: {entry['note']}")
+    components = entry.get("components")
+    if components is None:
+        print(f"  no details yet. Run: primarysource itu catalog sync {rec[0].upper()} --details")
+        return 0
+    for component in components:  # type: ignore[attr-defined]
+        assets = component.get("assets") or []
+        formats = " ".join(f"{a['fmt']}{'' if a['access'] == 'free' else '*'}" for a in assets)
+        head = f"{component['section']:10} {component['kind']:11} {component['label']:42}"
+        print(f"  {head} {component['status']:24} {formats}")
+    return 0
+
+
+def cmd_links(args: argparse.Namespace) -> int:
+    edition, number, _para = _resolve(_join(args.ref))
+    return _print_links(edition, number)
+
+
+def cmd_grep(args: argparse.Namespace) -> int:
+    edition = sources.resolve(args.edition)
+    hits, more = index.grep(edition, args.pattern, start=args.start, max_tokens=args.max_tokens)
+    for hit in hits:
+        print(f"{index.citation(edition, hit.number)}\n    {hit.excerpt}\n")
+    if more is not None:
+        print(f"[cut by --max-tokens; continue with --start {more}, or narrow the pattern]", file=sys.stderr)
+    return 0 if hits else 1
+
+
+def cmd_browse(args: argparse.Namespace) -> int:
+    if not args.path:
+        registered = {item.rec.split(".")[0] for item in sources.IN_FORCE}
+        for letter, title in sources.SERIES.items():
+            print(f"{letter}  {'*' if letter in registered else ' '}  {title}")
+        print("\n* = has registered recommendations")
+        return 0
+    if len(args.path) == 1:
+        for item in sources.IN_FORCE:
+            if item.rec.startswith(args.path.upper() + "."):
+                print(f"{item.rec:8} {'fetched' if corpus.has(item) else '-':8} {item.title}")
+        return 0
+    for number, title in index.top_level(sources.resolve(args.path), args.depth):
+        print(f"{number:10} {title}")
+    return 0
+
+
+def cmd_errata(args: argparse.Namespace) -> int:
+    items = [a for a in sources.AMENDMENTS if a.rec == args.rec]
+    if not items:
+        print(f"{args.rec}: nothing registered", file=sys.stderr)
+        return 1
+    for item in items:
+        state = "fetched" if item.artifact and corpus.has(item) else ("not fetched" if item.artifact else "no id")
+        print(f"{item.key}  [{item.status}; {state}]\n    {item.label}")
+    return 0
+
+
+def cmd_mcp(_args: argparse.Namespace) -> int:
+    from . import mcp
+
+    try:
+        mcp.require_extra()
+    except ImportError as error:
+        print(error, file=sys.stderr)
+        return 2
+    mcp.main()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="primarysource itu", description=__doc__, formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("--version", action="version", version=f"primarysource itu {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add(name: str, handler: Callable[[argparse.Namespace], int], help_text: str) -> argparse.ArgumentParser:
+        command = sub.add_parser(name, help=help_text, description=help_text)
+        command.set_defaults(handler=handler)
+        return command
+
+    add("info", cmd_info, "registered editions, amendments and what is fetched")
+
+    fetch = add("fetch", cmd_fetch, "download one edition or erratum into ITULIB_HOME and verify its digest")
+    fetch.add_argument("target", nargs="?", default=DEFAULT, help="edition or erratum key (default X.690)")
+    fetch.add_argument("--refresh", action="store_true", help="download again even if present")
+
+    sync = add("sync", cmd_sync, "fetch and index every in-force edition (or those named)")
+    sync.add_argument("targets", nargs="*", help="editions to sync (default: every in-force edition)")
+    sync.add_argument("--all", action="store_true", help="include superseded editions that have a digest")
+
+    idx = add("index", cmd_index, "build the clause index for a fetched edition")
+    idx.add_argument("edition", nargs="?", default=DEFAULT)
+
+    search = add("search", cmd_search, "full-text clause search")
+    search.add_argument("edition")
+    search.add_argument("query", nargs="+")
+    search.add_argument("--limit", type=int, default=8)
+    search.add_argument("--start", type=int, default=0, help="0-based offset of the first hit (paging)")
+
+    read = add("read", cmd_read, "print a clause (or one sentence, or an erratum) with its citation")
+    read.add_argument("ref", nargs="+", help="X.690§11.6, X.690 11.6¶2, X.690§11.6¶5-, 11.6, or an erratum key")
+    read.add_argument("--start", type=int, default=1, help="first sentence to print (paging)")
+    read.add_argument("--max-tokens", type=int, default=2000)
+    read.add_argument("--view", choices=["text", "normative", "refs"], default="text")
+
+    cite = add("cite", cmd_cite, "the citation string for a clause or sentence")
+    cite.add_argument("ref", nargs="+")
+
+    compare = add("compare", cmd_compare, "what changed in a clause between two editions")
+    compare.add_argument("number")
+    compare.add_argument("edition_a", nargs="?", default="X.690#2008-11")
+    compare.add_argument("edition_b", nargs="?", default="X.690#2021-02")
+
+    links = add("links", cmd_links, "what a clause points at, and what points at it")
+    links.add_argument("ref", nargs="+")
+
+    grep = add("grep", cmd_grep, "regular expression over clause bodies")
+    grep.add_argument("edition")
+    grep.add_argument("pattern")
+    grep.add_argument("--max-tokens", type=int, default=1500)
+    grep.add_argument("--start", type=int, default=0, help="0-based offset of the first matching clause")
+
+    browse = add("browse", cmd_browse, "ITU-T series, a series' recommendations, or a recommendation's clauses")
+    browse.add_argument("path", nargs="?", default="")
+    browse.add_argument("--depth", type=int, default=2)
+
+    errata = add("errata", cmd_errata, "errata, corrigenda and amendments registered for a recommendation")
+    errata.add_argument("rec", nargs="?", default=DEFAULT)
+
+    catalog = add("catalog", lambda _args: 0, "the ITU-T catalogue: what exists and in which formats (metadata only)")
+    catalog_sub = catalog.add_subparsers(dest="catalog_command", required=True)
+
+    def add_catalog(
+        name: str, handler: Callable[[argparse.Namespace], int], help_text: str
+    ) -> argparse.ArgumentParser:
+        command = catalog_sub.add_parser(name, help=help_text, description=help_text)
+        command.set_defaults(handler=handler)
+        return command
+
+    csync = add_catalog(
+        "sync", cmd_catalog_sync, "read series listings from itu.int (1 request/second, cached under ITULIB_HOME)"
+    )
+    csync.add_argument("series", nargs="*", default=["X"], help="series letters, or 'all' (default: X)")
+    csync.add_argument("--details", action="store_true", help="also read each recommendation's pages (resumable)")
+    csync.add_argument("--limit", type=int, help="stop after this many recommendations (with --details)")
+    csync.add_argument(
+        "--rec", nargs="*", help="only these recommendations, for example X.509 X.690 (with --details)"
+    )
+    csync.add_argument("--include-withdrawn", action="store_true")
+    csync.add_argument("--refresh", action="store_true", help="ignore the page cache and fetch again")
+    csync.add_argument("--reparse", action="store_true", help="rebuild details from cached pages (no requests)")
+
+    clist = add_catalog("list", cmd_catalog_list, "in-force editions with their available formats")
+    clist.add_argument("--series", default="X")
+    clist.add_argument("--text", default="", help="substring of number or title")
+    clist.add_argument("--format", default="", help="only editions offering this format id (PDF, EPB, MSW, TOC-HTM)")
+    clist.add_argument("--free", action="store_true", help="count only freely available assets for --format")
+    clist.add_argument("--limit", type=int, default=50)
+
+    cshow = add_catalog("show", cmd_catalog_show, "every component of one recommendation, with formats")
+    cshow.add_argument("rec", help="for example X.509")
+
+    add("mcp", cmd_mcp, "serve the MCP tools over stdio (needs the mcp extra)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # The corpus is full of characters cp1252 has no room for: X.680 §47.3 contains U+2212 MINUS SIGN, and
+    # printing that clause killed the command with UnicodeEncodeError on a redirected Windows console. A tool
+    # whose whole job is to hand back clause text cannot be allowed to die on a minus sign, so stdout is
+    # UTF-8 with replacement rather than whatever the console's code page happens to be.
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    args = build_parser().parse_args(argv)
+    # A missing corpus is a known state with a known remedy, so it is reported as one rather than as a
+    # traceback: a stack ending in CorpusMissing reads like a crash, an `action:` line reads as instructions.
+    try:
+        return int(args.handler(args))
+    except LibError as error:
+        print(error.as_text(), file=sys.stderr)
+        return 3
+    except KeyError as error:
+        print(error.args[0], file=sys.stderr)
+        return 2
+    except ValueError as error:
+        print(error, file=sys.stderr)
+        return 2
+    except RuntimeError as error:
+        print(str(error), file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

primarysource/itu/collection.py

@@ -0,0 +1,20 @@
+"""ITU-T recommendations as a primarysource collection. Importing this needs nothing beyond the core."""
+
+from __future__ import annotations
+
+from primarysource.model import Unit
+from primarysource.refs import RefGrammar
+from primarysource.registry import Collection
+
+# itulib's refs: X.690§11.6¶2, with an edition key after the number (X.690#2008-11§8.1). ¶n counts sentences of
+# the extracted clause. The tools already carry the itu_ prefix.
+COLLECTION = Collection(
+    name="itu",
+    title="ITU-T recommendations (the ASN.1 family X.680-X.697), fetched by the user",
+    prefix="itu_",
+    unit=Unit.SENTENCE,
+    grammar=RefGrammar(r"[A-Z]\.\d+(?:\.\d+)?(?:#[\d-]+)?"),
+    server="primarysource.itu.mcp:build",
+    cli="primarysource.itu.cli:main",
+    identify="primarysource.itu.identify:identify",
+)

primarysource/itu/corpus.py

@@ -0,0 +1,118 @@
+"""The corpus lives on the user's machine, and this repository never carries it.
+
+What decides the design is the notice printed on page iii of the recommendation itself: ITU reserves all
+rights and permits no part of the publication to be reproduced by any means without its prior written
+permission. That is quoted here in paraphrase rather than verbatim for the same reason the text is not
+vendored, and `tests/test_license.py` fails if a clause sentence ever appears in this tree.
+
+So `fetch` is a command the user runs, the download lands outside the checkout by default, and a clone of this
+repository contains code, clause arithmetic and pinned digests - never spec text. The tripwire exists because
+the tempting way to make a search test pass is to commit the PDF, and that is the one move a git history
+cannot walk back.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import pathlib
+import time
+import urllib.request
+
+from primarysource.errors import LibError
+
+from .sources import Amendment, Edition
+
+Document = Edition | Amendment
+
+# itulib's own default, kept so an existing library is found after the move into primarysource.
+DEFAULT_HOME = pathlib.Path.home() / ".itulib"
+
+
+def home() -> pathlib.Path:
+    """`$ITULIB_HOME`, else an existing `~/.itulib`, else `primarysource.home.collection_home("itu")`
+    (`$PRIMARYSOURCE_HOME/itu` or the per-user `primarysource/itu`)."""
+    override = os.environ.get("ITULIB_HOME")
+    if override:
+        return pathlib.Path(override)
+    if DEFAULT_HOME.is_dir() and not os.environ.get("PRIMARYSOURCE_HOME"):
+        return DEFAULT_HOME
+    from primarysource.home import collection_home
+
+    return collection_home("itu")
+
+
+def pdf_path(edition: Document) -> pathlib.Path:
+    return home() / "corpus" / f"{edition.key.replace('#', '-').replace('!', '-')}.pdf"
+
+
+def manifest_path() -> pathlib.Path:
+    return home() / "manifest.json"
+
+
+def _record() -> dict[str, dict[str, object]]:
+    path = manifest_path()
+    if not path.is_file():
+        return {}
+    loaded = json.loads(path.read_text(encoding="utf-8"))
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def has(edition: Document) -> bool:
+    """Present and, if a digest is registered, byte-identical to it."""
+    path = pdf_path(edition)
+    if not path.is_file():
+        return False
+    if not edition.sha256:
+        return True
+    return hashlib.sha256(path.read_bytes()).hexdigest() == edition.sha256
+
+
+def require(edition: Document) -> pathlib.Path:
+    """The local PDF, or an error naming the command that produces it."""
+    path = pdf_path(edition)
+    if not has(edition):
+        raise CorpusMissing(
+            f"{edition.key} is not in {home()}. The file is copyright ITU and is fetched to your machine rather "
+            "than shipped with this package, so there is no way to obtain it from the repository.",
+            "itu_info shows which editions are fetched",
+            f"primarysource itu fetch {edition.key}",
+        )
+    return path
+
+
+class CorpusMissing(LibError, RuntimeError):
+    """The corpus has not been fetched. The remedy is a command (`action`), never a committed file."""
+
+
+def fetch(edition: Document, *, refresh: bool = False) -> pathlib.Path:
+    """Download one edition, verify it against the registered digest, and record what arrived."""
+    path = pdf_path(edition)
+    if has(edition) and not refresh:
+        return path
+    url = edition.pdf_url
+    if url is None:
+        raise RuntimeError(f"{edition.key}: no download id is registered, so there is nothing to fetch")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    request = urllib.request.Request(url, headers={"User-Agent": "itulib-fetch"})  # noqa: S310
+    with urllib.request.urlopen(request, timeout=300) as response:  # noqa: S310
+        body = response.read()
+    if not body.startswith(b"%PDF"):
+        raise RuntimeError(f"{edition.key}: server returned {len(body)} bytes that are not a PDF")
+    digest = hashlib.sha256(body).hexdigest()
+    if edition.sha256 and digest != edition.sha256:
+        raise RuntimeError(
+            f"{edition.key}: digest {digest} does not match the registered {edition.sha256}. "
+            f"ITU may have re-published the edition; re-verify before trusting any citation from it."
+        )
+    path.write_bytes(body)
+    records = _record()
+    records[edition.key] = {
+        "sha256": digest,
+        "octets": len(body),
+        "fetched_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "source": url,
+    }
+    manifest_path().write_text(json.dumps(records, indent=2), encoding="utf-8")
+    return path

primarysource/itu/errata.py

@@ -0,0 +1,16 @@
+"""The text of an erratum, from the fetched covering note. Not indexed: it has no clause structure."""
+
+from __future__ import annotations
+
+from . import corpus, text
+from .sources import Amendment
+
+
+def errata_text(amendment: Amendment) -> str:
+    """Extracted text of a fetched erratum, or CorpusMissing naming the fetch command.
+
+    The covering note is a figure replacement, so the extract carries the instruction and the figure caption
+    but not the figure itself; the PDF is the authority for what the corrected figure shows.
+    """
+    pdf = corpus.require(amendment)
+    return text.tidy(" ".join(text.pages(pdf)))