From 9521a03e9088ac6dedfddfd2ac6d649069ce2e7f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 03:11:43 +0000 Subject: [PATCH 1/3] feat(server): remove the release pin and formal resources arXMCP no longer pins a sibling repo's tagged formalization or re-serves it. Removed: - tools/formal_release_pin.py, the CLI that pinned a topic repo's release into notebooks.db; - the arxmcp://formal/{notebook} and /{key} resources, with the coverage census that only they used, and the retrieved_formal wrap tag; - the store's formal_releases methods. notebooks.db goes to v7, which drops the formal_releases table. The store's rule against dropping tables exists to protect user-authored notebook metadata; a pin was re-derived from a git tag, so the rule now names user-authored state explicitly. A new migration test seeds a v6 file holding a notebook and a pin, and checks that v7 drops only the pin table. Refs #546. --- server/mcp_resources.py | 410 +------------------ server/notebooks_store.py | 102 +---- server/tools.py | 12 +- tests/test_formal_release_pin.py | 554 -------------------------- tests/test_formal_resource.py | 521 ------------------------ tests/test_notebook_api.py | 73 +--- tools/formal_release_pin.py | 661 ------------------------------- tools/notebook_restore.py | 3 - 8 files changed, 37 insertions(+), 2299 deletions(-) delete mode 100644 tests/test_formal_release_pin.py delete mode 100644 tests/test_formal_resource.py delete mode 100644 tools/formal_release_pin.py diff --git a/server/mcp_resources.py b/server/mcp_resources.py index e72e7f5..79eb6fd 100644 --- a/server/mcp_resources.py +++ b/server/mcp_resources.py @@ -6,7 +6,7 @@ ``tools/list`` and never enter the frozen tool-schema / BP1 prompt-cache prefix (proven byte-identical by ``notebook-surface-expansion-spike-1``). -Five resources are registered (see :func:`register_resources`): +Three resources are registered (see :func:`register_resources`): - ``arxmcp://notebooks`` — a **concrete** index resource; ``resources/read`` returns ``{count, notebooks: [{slug, display_name, uri}, …]}`` (enumeration). @@ -14,8 +14,6 @@ notebook's METADATA (NO chunk content, NO LanceDB query). - ``arxmcp://corpus-manifest`` — a **concrete** resource, generated on-read (source-truth-m3); the content-addressed corpus provenance manifest. -- ``arxmcp://formal/{notebook}`` and ``arxmcp://formal/{notebook}/{key}`` — - **templates** over the pinned formalization a notebook serves (contract-v1). This surface is **read-only** — notebook mutation stays on the ``/ui/api`` REST surface (the MCP notebook-mutation-tools path is on the project's Won't list). @@ -43,17 +41,14 @@ import json import logging -from datetime import UTC, datetime from pathlib import Path from typing import TYPE_CHECKING, Any from server import corpus_manifest -from server.corpus import read_corpus_version from server.tools import ResourcesNotReadyError, get_resources, wrap_retrieved_text from tools._notebook_common import ( NotebookError, notebook_dir, - notebook_lancedb_path, validate_slug, ) @@ -71,19 +66,6 @@ #: source-truth-m3: a THIRD concrete resource (not a template) — the #: content-addressed corpus provenance manifest, generated on-read. CORPUS_MANIFEST_URI = "arxmcp://corpus-manifest" -#: contract-v1 (derived-alg-geo-lean #175): the pinned formalization a notebook -#: serves, and one record out of it. TEMPLATES on ``{notebook}``, which is what -#: makes a SECOND topic repo cost zero arXMCP code. -#: -#: RESOURCES, never tools. That is the whole reason this ships without a -#: schema-version bump or a prompt-cache invalidation: ``resources/read`` is a -#: different JSON-RPC method from ``tools/call``, so ``tools/list`` bytes -- -#: and therefore ``EXPECTED_TOOL_SCHEMA_SHA256`` and the BP1 prefix -- are -#: untouched. ``tests/test_formal_resource.py`` asserts that mechanically -#: rather than the PR description asserting it in prose. -FORMAL_INDEX_TEMPLATE_URI = "arxmcp://formal/{notebook}" -FORMAL_RECORD_TEMPLATE_URI = "arxmcp://formal/{notebook}/{key}" - #: Module-level live store (set by the lifespan via :func:`set_notebooks_store`, #: mirroring ``server.tools.set_resources``). ``None`` until startup wires it. _notebooks_store: NotebooksStore | None = None @@ -194,352 +176,6 @@ async def _notebook_metadata(slug: str) -> dict[str, Any]: } -def _utc_iso() -> str: - """The repo's timestamp convention, second-resolution, `Z`-suffixed. - - Local rather than imported from ``corpus_manifest``: that one is private - to its module and reaching through it would make an unrelated refactor - there break this census stamp. - """ - return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ") - - -#: Why a census has no denominator, and the two are NOT the same fact -#: (CLAUDE.md 4.9 rule 2 -- an epistemic absence never wears an operational -#: token). ``no-corpus-marker`` is an ANSWER: nothing has stamped a size for -#: this notebook, so there is no measured corpus for the registry to have -#: covered. ``unavailable`` is a FAULT: a size was stamped and this server -#: could not read it. -#: -#: The epistemic token names what was OBSERVED (no marker) rather than what it -#: usually implies (no ingest has run) -- 4.9 rule 1, no axis inferred from -#: another. It is deliberately NOT the word ``is_ingested`` uses on -#: ``arxmcp://notebooks/{slug}``, which answers a different question (does the -#: lancedb dir exist) and can legitimately disagree with this one: a crashed -#: ingest leaves the dir without the marker. -CENSUS_UNMEASURED_NO_CORPUS_MARKER = "no-corpus-marker" -CENSUS_UNMEASURED_UNAVAILABLE = "unavailable" - -#: Where the denominator was read from, as a token rather than only as prose in -#: ``corpus_chunks_note``: an agent branches on this, and a later surface that -#: counts live must ship a DIFFERENT token rather than quietly changing what -#: this one means. -CENSUS_SOURCE_CORPUS_VERSION_MARKER = "corpus-version-marker" - -#: The census is measured from the ingest-time ``corpus-version.json`` marker, -#: NOT from a live ``chunks_table.count_rows()``. Three reasons, in order: -#: -#: 1. ``resources/read`` is an unauthenticated JSON-RPC method. Putting a -#: LanceDB open + scan behind it hands an anonymous caller a dataset read -#: per request, which is the cost #175 declined to pay when it shipped this -#: field as ``None``. -#: 2. The marker is DATED. A live count answers "how many now" and can say -#: nothing about when; the issue asks for a *dated* census, and a number -#: whose measurement time is unknown is the thing being fixed here. -#: 3. It is the number the ops surface already calls the denominator -- -#: ``arxmcp_corpus_chunk_count_marker`` (``server/health.py``), against -#: which ``..._actual`` is compared under ``corpus_chunk_count_tolerance``. -#: A second, differently-sourced chunk count on a second surface would be a -#: new way for two arXMCP answers to disagree. -#: -#: What it costs is liveness: an ingest since the marker was stamped is not -#: reflected, which is exactly why ``corpus_measured_at`` ships beside it -#: rather than the reader assuming "now". -CENSUS_SOURCE_NOTE = ( - "corpus_chunks/corpus_papers are read from the notebook's ingest-time " - "corpus-version.json marker (stamped at corpus_measured_at, epoch " - "corpus_version), not counted live on this read -- a denominator with a " - "date, not a denominator as of an unknown moment. No coverage ratio is " - "computed for you: entries are statements and corpus_chunks are text " - "chunks, so entries/corpus_chunks mixes units, and papers_covered counts " - "papers the REGISTRY cites, which need not all be papers this notebook " - "holds." -) - - -def _corpus_denominator(notebook: str) -> dict[str, Any]: - """Measure the notebook a formal census is stated against. Never raises. - - derived-alg-geo-lean **#179**. #175 shipped ``corpus_chunks: None`` with a - note naming this issue as its owner; this is that owner. The numerator - (``entries``, ``papers_covered``) was always in the response -- what was - missing is the thing that makes it mean anything, because ten records - against a 15,280-chunk notebook and ten records against a ten-chunk - notebook are the same numerator and opposite facts. - - Degrades to a null denominator with a REASON rather than failing the read: - a census is a report about the corpus, and an unreadable corpus marker must - not take down the pin record beside it. The reason distinguishes "no corpus - to have covered" from "could not measure the corpus" per 4.9 rule 2. - """ - paths = _configured_application_paths() - base = paths.notebooks if paths is not None else None - unmeasured: dict[str, Any] = { - "corpus_chunks": None, - "corpus_papers": None, - "corpus_version": None, - "corpus_measured_at": None, - # Named even when it yielded nothing: "we looked HERE and found no - # answer" is a different report from "we did not look". - "corpus_source": CENSUS_SOURCE_CORPUS_VERSION_MARKER, - } - try: - info = read_corpus_version(notebook_lancedb_path(notebook, base=base)) - except NotebookError: - # Containment / symlink rejection at var/arxmcp/notebooks/ -- - # the same out-of-band tamper signal _notebook_metadata logs. Operator - # -visible server-side; the agent gets "unavailable", not the path. - logger.warning( - "formal census: notebook %r lancedb-path containment check " - "rejected (possible symlink tamper); denominator unmeasured", - notebook, - ) - return {**unmeasured, "corpus_unmeasured_reason": CENSUS_UNMEASURED_UNAVAILABLE} - except (ValueError, OSError) as exc: - # Present-but-corrupt marker, or an OS error reading it. A corpus - # exists; its size could not be established. That is a fault, and it - # must not read as "this notebook has nothing in it". - logger.warning( - "formal census: notebook %r corpus-version read failed (%s); " - "denominator unmeasured", - notebook, - type(exc).__name__, - ) - return {**unmeasured, "corpus_unmeasured_reason": CENSUS_UNMEASURED_UNAVAILABLE} - if info is None: - # No marker: no ingest has run. An answer, not a fault. - return {**unmeasured, "corpus_unmeasured_reason": CENSUS_UNMEASURED_NO_CORPUS_MARKER} - return { - "corpus_chunks": info.chunk_count, - "corpus_papers": info.paper_count, - "corpus_version": info.version, - "corpus_measured_at": info.created_at, - "corpus_source": CENSUS_SOURCE_CORPUS_VERSION_MARKER, - "corpus_unmeasured_reason": None, - } - - -#: Caveats are GENERATED, never authored: each is a mechanical consequence of a -#: field in the pin, so a record cannot be served with a caveat somebody forgot -#: to write. Ordered by severity, and ``withdrawn`` is always first when it -#: applies -- a reader who stops after one line must read that one. -def _caveats( - pin: dict[str, Any], - key: str, - withdrawn: dict[str, Any] | None, - *, - census: dict[str, Any] | None = None, -) -> list[str]: - caveats: list[str] = [] - if withdrawn is not None: - caveats.append( - f"WITHDRAWN. The producer retracted this record at " - f"{withdrawn.get('withdrawn_at', 'an unrecorded date')}" - + (f": {withdrawn['reason']}" if withdrawn.get("reason") else "") - + f". The withdrawal was read from tag " - f"{pin.get('withdrawals_tag') or 'unknown'}, which may be NEWER " - f"than the pinned {pin.get('tag')} -- withdrawals are the one " - f"channel allowed to travel forward in time, because they can " - f"only remove trust." - ) - if pin.get("digest_provenance") != "git_rooted": - caveats.append( - "digest_provenance is self_attested_only: the artifact set agrees " - "with itself and nothing outside it was consulted for the attest " - "digests. That is a state a file copy also reaches. It is neither " - "a pass nor a fail." - ) - if not pin.get("resolution_json"): - caveats.append( - "No corpus resolution accompanies this pin, so nothing here says " - "whether the quoted statements still appear in any corpus. Absent, " - "not passing." - ) - if not pin.get("review_json"): - caveats.append( - "No human faithfulness review accompanies this pin. Nobody has " - "read this mathematics against its source." - ) - if not key: - caveats.append(_coverage_caveat(census or {})) - return caveats - - -def _coverage_caveat(census: dict[str, Any]) -> str: - """The coverage line, stated from the census rather than in the abstract. - - #175 could only say "coverage is a fraction and `census` says which", - because `census` did not yet say. It does now, so this caveat quotes the - two numbers instead of pointing at them -- a reader who stops after the - caveats has still seen the denominator. - - The arithmetic is deliberately left undone (see :data:`CENSUS_SOURCE_NOTE`): - stating "N entries against M chunks" is a fact, and dividing them would - manufacture a percentage out of two different units. - """ - if "corpus_source" not in census: - # No census was handed in at all (not a state _formal_index can reach; - # a future caller could). Say the abstract thing rather than render a - # concrete-looking line out of missing values -- "measured at None - # chunks" would read as a measurement. - return ( - "Coverage is a dated census, not a property of this response, and " - "no census accompanied this one. Read the `census` block on " - "arxmcp://formal/ for the numbers." - ) - reason = census.get("corpus_unmeasured_reason") - if reason == CENSUS_UNMEASURED_NO_CORPUS_MARKER: - return ( - "Coverage is a dated census, and this one has no denominator: no " - "corpus-version marker stamps a size for this notebook, so the " - f"{_count(census.get('entries', 0), 'entry', 'entries')} here " - "are stated against " - "nothing measured. Not a fault -- usually it means no ingest has " - "run yet, and a notebook can be registered and pinned before it " - "is. Do NOT read it as an empty corpus." - ) - if reason == CENSUS_UNMEASURED_UNAVAILABLE: - return ( - "Coverage is a dated census, and this server could not measure the " - "denominator on this read (the corpus-version marker is present " - "but unreadable). `corpus_chunks` is null for an OPERATIONAL " - "reason, not because the corpus is empty -- do not read this as a " - "small notebook." - ) - return ( - f"Coverage is a dated census, not a property of this response: " - f"{_count(census.get('entries', 0), 'entry', 'entries')} covering " - f"{_count(census.get('papers_covered', 0), 'cited paper')}, against a " - f"notebook measured at {_count(census.get('corpus_chunks'), 'chunk')} " - f"across {_count(census.get('corpus_papers'), 'paper')} as of " - f"{census.get('corpus_measured_at')} (corpus epoch " - f"{census.get('corpus_version')}). The ratio is left to you on " - "purpose; see corpus_chunks_note." - ) - - -def _count(n: Any, singular: str, plural: str | None = None) -> str: - """``"1 entry"`` / ``"2 entries"``. Agent-facing prose, so it agrees. - - A caveat that reads "1 cited papers" invites the reader to skim it, and - these lines are the half of the response that a reader who skims the JSON - still sees. - """ - return f"{n} {singular if n == 1 else (plural or singular + 's')}" - - -def _withdrawn_keys(pin: dict[str, Any]) -> dict[str, dict[str, Any]]: - raw = pin.get("withdrawals_json") - if not raw: - return {} - try: - document = json.loads(raw) - except (TypeError, ValueError): - logger.warning("formal resource: withdrawals_json is not JSON; ignoring") - return {} - return { - item["key"]: item - for item in (document.get("withdrawals") or []) - if isinstance(item, dict) and item.get("key") - } - - -def _pin_header(pin: dict[str, Any]) -> dict[str, Any]: - """What was pinned. Never a verdict about it.""" - return { - "repo": pin.get("repo"), - "tag": pin.get("tag"), - "tag_object_sha": pin.get("tag_object_sha"), - "commit_sha": pin.get("commit_sha"), - "registry_id": pin.get("registry_id"), - "registry_sha256": pin.get("registry_sha256"), - "env_digest": pin.get("env_digest"), - "digest_provenance": pin.get("digest_provenance"), - "withdrawals_tag": pin.get("withdrawals_tag"), - "pinned_at": pin.get("pinned_at"), - } - - -async def _formal_index(notebook: str) -> dict[str, Any]: - """``arxmcp://formal/{notebook}`` — what this notebook pins, and how little. - - A notebook that pins nothing gets ``pinned: false`` rather than an error: - "this corpus has no formalization" is an answer, and the overwhelming - majority of notebooks are in that state. - """ - validate_slug(notebook) # FIRST, before any store or FS access - pin = await _require_store().get_formal_release(notebook) - if pin is None: - return { - "notebook": notebook, - "pinned": False, - "reason": ( - "no formal release is pinned for this notebook. arXMCP hosts " - "no formalization of its own; a record appears here only once " - "an operator pins a topic repo's release." - ), - } - registry = json.loads(pin["registry_json"]) - entries = registry.get("entries") or {} - withdrawn = _withdrawn_keys(pin) - papers = sorted({ - f"{(e.get('source') or {}).get('scheme')}:" - f"{(e.get('source') or {}).get('id')}" - f"{(e.get('source') or {}).get('version') or ''}" - for e in entries.values() - }) - # The denominator this census needs to MEAN anything (#179). Measured - # before the payload is built so the caveats can quote it rather than - # gesture at it -- and it is a null-with-a-reason, never an exception, so - # an unreadable corpus marker cannot take the pin record down with it. - census = { - "entries": len(entries), - "withdrawn": len(set(entries) & set(withdrawn)), - "papers_covered": len(papers), - "papers": papers, - **_corpus_denominator(notebook), - "corpus_chunks_note": CENSUS_SOURCE_NOTE, - "generated_at": _utc_iso(), - } - return { - "notebook": notebook, - "pinned": True, - "pin": _pin_header(pin), - "census": census, - "keys": sorted(entries), - "caveats": _caveats(pin, "", None, census=census), - } - - -async def _formal_record(notebook: str, key: str) -> dict[str, Any]: - """``arxmcp://formal/{notebook}/{key}`` — one record, re-served verbatim. - - ADR-0004's asymmetry is the whole permission model: arXMCP MAY downgrade an - axis from its own fresher resolution, and has NO code path that raises one. - So the entry is passed through exactly as the producer published it and - every judgement this server adds arrives as a generated ``caveats[]`` entry - beside it, never as an edit to the record. - """ - validate_slug(notebook) - pin = await _require_store().get_formal_release(notebook) - if pin is None: - raise ValueError(f"notebook {notebook!r} pins no formal release") - registry = json.loads(pin["registry_json"]) - entry = (registry.get("entries") or {}).get(key) - if entry is None: - raise ValueError(f"no entry {key!r} in the release pinned for {notebook!r}") - withdrawn = _withdrawn_keys(pin).get(key) - return { - "notebook": notebook, - "key": key, - "pin": _pin_header(pin), - # Verbatim. Not reshaped, not summarized, not annotated in place. - "entry": entry, - "withdrawn": withdrawn is not None, - "caveats": _caveats(pin, key, withdrawn), - } - - def register_resources(mcp_server: FastMCP) -> None: """Register the notebook MCP resources on ``mcp_server``. @@ -621,53 +257,9 @@ async def _corpus_manifest() -> str: ) return _wrap_json(payload, kind="manifest") - @mcp_server.resource( - FORMAL_INDEX_TEMPLATE_URI, - name="formal", - description=( - "The formalization release pinned for one notebook: the topic " - "repo, tag, tag-object and commit shas, registry digest, " - "digest_provenance, the citation keys it carries, and a DATED " - "COVERAGE CENSUS. resources/read returns {notebook, pinned, pin, " - "census, keys, caveats}; census carries the numerator (entries, " - "withdrawn, papers_covered) AND the denominator it is stated " - "against (corpus_chunks, corpus_papers, corpus_version, " - "corpus_measured_at, corpus_source), so N records never read as a covered " - "corpus. A null corpus_chunks names its reason in " - "corpus_unmeasured_reason: `no-corpus-marker` (nothing stamped a " - "size) is an answer, `unavailable` (a size was stamped and could " - "not be read) is a fault, and neither is 0. A notebook that pins " - "nothing returns " - "pinned:false, which is an answer and not an error. Read " - "arxmcp://formal// for one record." - ), - mime_type="text/plain", - ) - async def _formal_index_resource(notebook: str) -> str: - return _wrap_json(await _formal_index(notebook), kind="formal") - - @mcp_server.resource( - FORMAL_RECORD_TEMPLATE_URI, - name="formal-record", - description=( - "One statement record out of the release pinned for a notebook, " - "re-served VERBATIM as the producer published it. resources/read " - "returns {notebook, key, pin, entry, withdrawn, caveats}. Every " - "judgement this server adds is a generated caveat beside the " - "record, never an edit to it: arXMCP may DOWNGRADE a trust axis " - "from its own fresher information and has no path that raises one. " - "A withdrawn record is served with `withdrawn` first in caveats[]." - ), - mime_type="text/plain", - ) - async def _formal_record_resource(notebook: str, key: str) -> str: - return _wrap_json(await _formal_record(notebook, key), kind="formal") - __all__ = [ "CORPUS_MANIFEST_URI", - "FORMAL_INDEX_TEMPLATE_URI", - "FORMAL_RECORD_TEMPLATE_URI", "NOTEBOOKS_INDEX_URI", "NOTEBOOK_TEMPLATE_URI", "register_resources", diff --git a/server/notebooks_store.py b/server/notebooks_store.py index 367bedc..67b5663 100644 --- a/server/notebooks_store.py +++ b/server/notebooks_store.py @@ -64,7 +64,7 @@ #: data loss). When adding a new version: append a new #: ``if current_version < N:`` block in ``_open_sync`` using #: ``CREATE TABLE IF NOT EXISTS`` / ``ALTER TABLE`` and bump -#: SCHEMA_VERSION; do NOT drop existing tables. +#: SCHEMA_VERSION; do NOT drop a table that holds user-authored state. #: #: v3→v4 is the textbook-ingest-m6 ADDITIVE migration adding three #: parse-tracking columns to ``notebooks``: ``parse_status``, @@ -86,7 +86,11 @@ #: arXMCP holds no registry, only a pin to one, and re-serves its #: records verbatim). Written by ``tools/formal_release_pin.py``, read #: by the ``arxmcp://formal/*`` resources. derived-alg-geo-lean #174. -SCHEMA_VERSION: int = 6 +#: +#: v6→v7 drops ``formal_releases`` again: the release pin and the formal +#: resources were removed. Its rows were never user-authored state, since +#: each was re-derived from a sibling repo's git tag. +SCHEMA_VERSION: int = 7 def _migrate(conn: sqlite3.Connection, version: int, *statements: str) -> None: @@ -118,11 +122,10 @@ def _migrate(conn: sqlite3.Connection, version: int, *statements: str) -> None: #: Module-level so a SYNC CLI can reach the migration ladder. #: #: It used to be a closure inside ``NotebooksStore.open``, which meant the -#: only way to migrate this file was to construct an async store. Two CLIs -#: could not, and wrote the ``notebooks`` table by raw ``sqlite3`` instead: -#: ``tools/notebook_restore.py`` (:227, :302, :320) and, once contract-v1 -#: landed, the release pinner. Neither touched ``user_version``, so rows they -#: wrote sat in a file the v0->v1 block below would DROP on the next server +#: only way to migrate this file was to construct an async store. A sync CLI +#: could not, and wrote the ``notebooks`` table by raw ``sqlite3`` instead +#: (``tools/notebook_restore.py``). It never touched ``user_version``, so rows +#: it wrote sat in a file the v0->v1 block below would DROP on the next server #: start -- the migration is guarded by ``current_version < 1`` and a #: raw-sqlite writer leaves that at 0 forever. ``tools/notebook_list_offline.py`` #: already carries the read-side half of this lesson (its m2 critique F2). @@ -335,6 +338,9 @@ def open_sync(db_path: Path) -> sqlite3.Connection: " ON DELETE CASCADE" ")", ) + # v6 -> v7: the release pin was removed, and nothing reads this table. + if current_version < 7: + _migrate(conn, 7, "DROP TABLE IF EXISTS formal_releases") return conn @@ -903,88 +909,6 @@ def _update() -> int: return await asyncio.to_thread(_update) - # ------------------------------------------------------------------ - # Formal releases (contract-v1; derived-alg-geo-lean #174) - # ------------------------------------------------------------------ - - async def upsert_formal_release(self, row: dict[str, str | None]) -> None: - """Write (or replace) the pin for ``(slug, repo)``. - - ``INSERT OR REPLACE``: one pin per notebook per topic repo, and - re-pinning to a newer tag REPLACES rather than accumulates. Keeping - both would leave two answers to "what does this notebook serve", and - the resource would have to choose -- which is the operator's decision, - expressed by which tag they pinned. - - The caller (``tools/formal_release_pin.py``) owns every verification; - this method owns none. That split is deliberate: a store method that - re-checked digests would be a second, weaker gate that a future caller - might rely on instead of the real one. - """ - async with self._lock: - def _write() -> None: - self._conn.execute( - "INSERT OR REPLACE INTO formal_releases (" - " slug, repo, tag, tag_object_sha, commit_sha," - " registry_id, registry_sha256, env_digest," - " digest_provenance, asset_dir, bundle_json," - " registry_json, resolution_json, review_json," - " withdrawals_json, withdrawals_tag, pinned_at" - ") VALUES (" - " :slug, :repo, :tag, :tag_object_sha, :commit_sha," - " :registry_id, :registry_sha256, :env_digest," - " :digest_provenance, :asset_dir, :bundle_json," - " :registry_json, :resolution_json, :review_json," - " :withdrawals_json, :withdrawals_tag, :pinned_at" - ")", - row, - ) - await asyncio.to_thread(_write) - - async def get_formal_release(self, slug: str) -> dict[str, str | None] | None: - """The pin for ``slug``, or ``None`` when this notebook pins nothing. - - ``None`` is the ordinary case and not an error: most notebooks have no - formalization, and the ``arxmcp://formal/{notebook}`` resource says so - rather than 404-ing, because "this corpus has no formalization" is an - answer. - """ - async with self._lock: - def _query() -> dict[str, str | None] | None: - cur = self._conn.execute( - f"SELECT {_FORMAL_COLUMNS} FROM formal_releases " - "WHERE slug = ? ORDER BY repo LIMIT 1", - (slug,), - ) - row = cur.fetchone() - if row is None: - return None - return dict(zip(_FORMAL_COLUMNS.split(", "), row, strict=True)) - return await asyncio.to_thread(_query) - - async def list_formal_releases(self) -> list[dict[str, str | None]]: - """Every pin, ordered by ``(slug, repo)``.""" - async with self._lock: - def _query() -> list[dict[str, str | None]]: - cur = self._conn.execute( - f"SELECT {_FORMAL_COLUMNS} FROM formal_releases " - "ORDER BY slug, repo" - ) - names = _FORMAL_COLUMNS.split(", ") - return [dict(zip(names, row, strict=True)) for row in cur.fetchall()] - return await asyncio.to_thread(_query) - - -#: Selected explicitly rather than with ``*`` so a future ALTER cannot silently -#: change the shape every reader unpacks. -_FORMAL_COLUMNS = ( - "slug, repo, tag, tag_object_sha, commit_sha, registry_id, " - "registry_sha256, env_digest, digest_provenance, asset_dir, bundle_json, " - "registry_json, resolution_json, review_json, withdrawals_json, " - "withdrawals_tag, pinned_at" -) - - __all__ = [ "NotebooksStore", "SCHEMA_VERSION", diff --git a/server/tools.py b/server/tools.py index c76d0de..f267f6f 100644 --- a/server/tools.py +++ b/server/tools.py @@ -672,13 +672,6 @@ def envelope( #: manifest differently from paper-body content. Like the notebook tag it is #: NOT a tool / not in ALL_TOOLS, so the ``tools/list`` hash is untouched. _WRAP_TAG_MANIFEST = "retrieved_manifest" -#: contract-v1 (derived-alg-geo-lean #175): the two ``arxmcp://formal/*`` -#: resources. Its own tag rather than reusing ``retrieved_notebook`` because -#: the content has a different provenance and a different trust story: it is a -#: SIBLING REPO's published record, re-served verbatim, and the reader is meant -#: to treat "arXMCP said it" and "the topic repo published it" as different -#: claims. A shared delimiter would make them one. -_WRAP_TAG_FORMAL = "retrieved_formal" def wrap_retrieved_text( @@ -717,9 +710,7 @@ def wrap_retrieved_text( ``"equation"`` → ``...``; ``"notebook"`` → ``...`` (MCP resource metadata); ``"manifest"`` → ``...`` (the - ``arxmcp://corpus-manifest`` resource, source-truth-m3); - ``"formal"`` → ``...`` (the two - ``arxmcp://formal/*`` resources, contract-v1). An + ``arxmcp://corpus-manifest`` resource, source-truth-m3). An unknown ``kind`` falls back to ````. Equation wrapping is reserved for ``find_equation`` when E10_S03 wires equation atom body text into the response. @@ -737,7 +728,6 @@ def wrap_retrieved_text( "equation": _WRAP_TAG_EQUATION, "notebook": _WRAP_TAG_NOTEBOOK, "manifest": _WRAP_TAG_MANIFEST, - "formal": _WRAP_TAG_FORMAL, }.get(kind, _WRAP_TAG_CHUNK) open_tag = f"<{tag}>" close_tag = f"" diff --git a/tests/test_formal_release_pin.py b/tests/test_formal_release_pin.py deleted file mode 100644 index 84bac08..0000000 --- a/tests/test_formal_release_pin.py +++ /dev/null @@ -1,554 +0,0 @@ -"""The pinner, and the tamper it is supposed to catch. - -derived-alg-geo-lean **#174**. The design weakness this closes: a bundle that -crosses the seam validated only for self-consistency has no producer-side gate -that survives a file copy. Flip `contains_sorry_ax`, recompute that file's -sha256 into `bundle.json`, and the set agrees with itself while saying the -opposite of what CI measured. - -So the central test is the tamper test, and it is written twice on purpose: - -* with a digest block in the tag message, the pinner REFUSES — the tag object - is a root the tampering cannot reach; -* without one, it does NOT refuse, and reports `self_attested_only`. - -The second is not a weaker version of the first. It is the honest record of -where the topic repo stands today: `attest/*` is gitignored there, so nothing -git-rooted covers those files, and v0.1.0's tag message asserts the property in -prose while carrying no block. A test suite that only exercised the happy path -would let `self_attested_only` read as a pass, which is the failure §4.9 rule 1 -exists to prevent. - -Real `git`, synthetic repos, no network. -""" - -from __future__ import annotations - -import hashlib -import json -import os -import shutil -import subprocess -from pathlib import Path - -import pytest - -from tools.formal_release_pin import ( - GIT_ROOTED, - SELF_ATTESTED_ONLY, - PinError, - newest_tag, - parse_digest_block, - read_tag, - refuse_dirty_worktree, - to_row, - verify, - write_pin, -) - -pytestmark = pytest.mark.skipif( - shutil.which("git") is None, reason="git is not on PATH" -) - -REGISTRY_ID = "a520a8d4f877" -ENV_DIGEST = "45d9e8ca8c1b" + "c" * 52 # 64 hex; the schema checks the shape - - -def _sha(data: bytes) -> str: - return hashlib.sha256(data).hexdigest() - - -def _git(repo: Path, *args: str) -> str: - return subprocess.run( - ["git", "-C", str(repo), *args], - capture_output=True, text=True, check=True, - ).stdout - - -def _registry() -> dict: - return { - "schema_version": "registry/1.0", - "registry_id": REGISTRY_ID, - "notebook_hint": "bridgeland-stability", - "entries": { - f"stmt:{REGISTRY_ID}:bridgeland2007.lem-8.2": { - "kind": "lemma", "title": "A bound", "informal": "A bound.", - "source": {"scheme": "arxiv", "id": "math/0212237", - "version": "v3", "printed_number": "8.2", - "locator": None}, - "quote_mode": "verbatim", "quote": "Lemma 8.2. A bound.", - "quote_norm": "nfc-ws-collapse/1", - "quote_sha256": "e" * 64, - "mint_resolution": None, - "mint_unresolved_reason": "no resolver run", - "depends_on": [], "frontier": [], - "minted_at": "2026-08-05", "minted_by": "fixture", - "supersedes": None, "superseded_by": None, - } - }, - } - - -def _declarations(*, contains_sorry_ax: bool = False) -> dict: - return { - "schema_version": "declarations/1.0", - "contains_sorry_ax": contains_sorry_ax, - "constants": [{"name": "Topic.thm"}], - } - - -@pytest.fixture -def topic(tmp_path: Path) -> dict: - """A topic repo with a tag, plus its release assets in a sibling dir. - - Mirrors the real shape: the registry is TRACKED, `attest/*` is gitignored - and exists only as assets. - """ - repo = tmp_path / "topic" - (repo / "registry").mkdir(parents=True) - _git_init(repo) - - registry_bytes = (json.dumps(_registry(), indent=2) + "\n").encode() - (repo / "registry" / "bridgeland2007.json").write_bytes(registry_bytes) - (repo / ".gitignore").write_text("/attest/*\n", encoding="utf-8") - _git(repo, "add", "-A") - _git(repo, "commit", "-q", "-m", "the tree this tag names") - commit = _git(repo, "rev-parse", "HEAD").strip() - - assets = tmp_path / "assets" - assets.mkdir() - declarations = (json.dumps(_declarations(), indent=2) + "\n").encode() - (assets / "declarations.json").write_bytes(declarations) - bundle = { - "schema_version": "bundle/1.0", - "_type": "https://in-toto.io/Statement/v1", - "subject": [{"name": "Topic", - "uri": "https://example.invalid/topic", - "digest": {"gitCommit": commit, "gitTag": "v0.1.0"}}], - "contract_repo": {"url": "https://example.invalid/mfc", "rev": "a" * 40}, - "env_digest": ENV_DIGEST, - "registry_sha256": _sha(registry_bytes), - "predicates": [{ - "predicateType": "https://example.invalid/predicate/declarations/v1", - "file": "attest/declarations.json", - "sha256": _sha(declarations), - "produced_by": "fixture", - "env_digest": ENV_DIGEST, - "self_attested": True, - }], - "unrecognized_predicates": [], - } - _write_bundle(assets, bundle) - return {"repo": repo, "assets": assets, "commit": commit, - "registry_sha256": _sha(registry_bytes)} - - -def _git_init(repo: Path) -> None: - _git(repo, "init", "-q", "-b", "main") - _git(repo, "config", "user.email", "fixture@example.invalid") - _git(repo, "config", "user.name", "Fixture") - _git(repo, "config", "commit.gpgsign", "false") - _git(repo, "config", "tag.gpgsign", "false") - - -def _write_bundle(assets: Path, bundle: dict) -> bytes: - raw = (json.dumps(bundle, indent=2) + "\n").encode() - (assets / "bundle.json").write_bytes(raw) - return raw - - -def _tag(repo: Path, name: str, message: str) -> None: - _git(repo, "tag", "-a", name, "-m", message) - - -def _digest_block(assets: Path) -> str: - lines = [ - f"attest/bundle.json {_sha((assets / 'bundle.json').read_bytes())}", - f"attest/declarations.json " - f"{_sha((assets / 'declarations.json').read_bytes())}", - ] - return ("-----BEGIN MFC DIGESTS-----\n" + "\n".join(lines) - + "\n-----END MFC DIGESTS-----") - - -def _notebook_db(tmp_path: Path, slug: str = "bridgeland-stability") -> Path: - """A notebooks.db with the row `formal_releases.slug` references. - - The FK is the point: a pin for a notebook that does not exist would be a - record nothing can serve. - """ - from server.notebooks_store import open_sync - - db = tmp_path / "notebooks.db" - conn = open_sync(db) - try: - conn.execute( - "INSERT INTO notebooks (slug, display_name, lancedb_path, " - "created_at) VALUES (?, '', '', '2026-09-03T00:00:00Z')", - (slug,), - ) - finally: - conn.close() - return db - - -def _verify(topic, **kw): - defaults = dict( - tag_name="v0.1.0", slug="bridgeland-stability", - registry_path="registry/bridgeland2007.json", assets=topic["assets"], - ) - defaults.update(kw) - return verify(topic["repo"], **defaults) - - -# --- the tamper, both ways ----------------------------------------------------- - -def test_a_tamper_that_recomputes_the_bundle_is_refused_when_the_tag_names_digests( - topic, -) -> None: - """#174's test, and the whole reason this tool re-derives anything. - - `contains_sorry_ax` is flipped AND the file's sha256 is recomputed into - `bundle.json`, so the artifact set is internally consistent — every check - a self-validating bundle can perform passes. The tag object is the one - thing the tamperer cannot reach without pushing a new tag. - """ - assets = topic["assets"] - _tag(topic["repo"], "v0.1.0", "release\n\n" + _digest_block(assets)) - assert _verify(topic).digest_provenance == GIT_ROOTED - - tampered = (json.dumps(_declarations(contains_sorry_ax=True), indent=2) - + "\n").encode() - (assets / "declarations.json").write_bytes(tampered) - bundle = json.loads((assets / "bundle.json").read_text()) - bundle["predicates"][0]["sha256"] = _sha(tampered) # internally consistent - _write_bundle(assets, bundle) - - # Refused at the bundle, before its predicates are even read: the - # tamperer had to edit `bundle.json` to keep the set consistent, and the - # tag object names that file too. Either refusal is the tag object - # catching what the artifact set alone cannot. - with pytest.raises(PinError, match="(?i)tag object"): - _verify(topic) - - -def test_the_same_tamper_is_NOT_caught_without_a_digest_block(topic) -> None: - """And the pin says `self_attested_only` rather than pretending. - - This is where the topic repo stands today: `attest/*` is gitignored, so - the only digests covering those files are the ones inside the file set, - and a coordinated edit satisfies all of them. v0.1.0's tag message asserts - that "the tag object ... is the root of trust" in prose and carries no - block for anything to be rooted in. - - Asserted rather than left implicit because the alternative — a suite that - exercises only the block-present path — would let `self_attested_only` - read as a pass everywhere it appears. - """ - _tag(topic["repo"], "v0.1.0", "release, prose only, no digest block") - assert _verify(topic).digest_provenance == SELF_ATTESTED_ONLY - - assets = topic["assets"] - tampered = (json.dumps(_declarations(contains_sorry_ax=True), indent=2) - + "\n").encode() - (assets / "declarations.json").write_bytes(tampered) - bundle = json.loads((assets / "bundle.json").read_text()) - bundle["predicates"][0]["sha256"] = _sha(tampered) - _write_bundle(assets, bundle) - - pin = _verify(topic) - assert pin.digest_provenance == SELF_ATTESTED_ONLY - assert any("no git-rooted digest" in f for f in pin.findings) - - -def test_an_uncoordinated_tamper_is_caught_either_way(topic) -> None: - """Flipping the file WITHOUT recomputing the bundle is caught with no tag - block at all — internal consistency does that much. It is the coordinated - edit that needs an external root, which is why #174 specified one.""" - _tag(topic["repo"], "v0.1.0", "release, prose only") - (topic["assets"] / "declarations.json").write_bytes(b'{"tampered": true}\n') - with pytest.raises(PinError, match="the bundle claims"): - _verify(topic) - - -# --- what the git tag object actually pins -------------------------------------- - -def test_the_pin_names_the_tag_object_not_only_the_commit(topic) -> None: - """An annotated tag is its own object with its own sha, and that is what a - re-tag changes. Recording only the commit would make a silently re-cut tag - invisible.""" - _tag(topic["repo"], "v0.1.0", "release") - tag = read_tag(topic["repo"], "v0.1.0") - assert tag.is_annotated - assert tag.object_sha != tag.commit_sha == topic["commit"] - - -def test_a_bundle_describing_another_commit_is_refused(topic) -> None: - _tag(topic["repo"], "v0.1.0", "release") - bundle = json.loads((topic["assets"] / "bundle.json").read_text()) - bundle["subject"][0]["digest"]["gitCommit"] = "f" * 40 - _write_bundle(topic["assets"], bundle) - with pytest.raises(PinError, match="describe a different tree"): - _verify(topic) - - -def test_a_bundle_built_before_its_tag_is_refused(topic) -> None: - """`gitTag: null` is what an artifact set produced before the tag existed - says — a valid artifact and an invalid release.""" - _tag(topic["repo"], "v0.1.0", "release") - bundle = json.loads((topic["assets"] / "bundle.json").read_text()) - bundle["subject"][0]["digest"]["gitTag"] = None - _write_bundle(topic["assets"], bundle) - with pytest.raises(PinError, match="gitTag"): - _verify(topic) - - -def test_a_registry_that_moved_since_the_tag_is_refused(topic) -> None: - """The registry IS tracked, so this axis is git-rooted regardless of the - tag message — and it is the artifact arXMCP actually re-serves.""" - _tag(topic["repo"], "v0.1.0", "release") - bundle = json.loads((topic["assets"] / "bundle.json").read_text()) - bundle["registry_sha256"] = "d" * 64 - _write_bundle(topic["assets"], bundle) - with pytest.raises(PinError, match="registry_sha256 disagrees"): - _verify(topic) - - -def test_the_registry_is_read_from_git_not_from_the_worktree(topic) -> None: - """A pin describes a tag. Reading the file off disk would let an - uncommitted edit — or a later commit — into a record that claims to be - v0.1.0.""" - _tag(topic["repo"], "v0.1.0", "release") - moved = topic["repo"] / "registry" / "bridgeland2007.json" - moved.write_text('{"schema_version": "registry/1.0"}\n', encoding="utf-8") - _git(topic["repo"], "add", "-A") - _git(topic["repo"], "commit", "-q", "-m", "the registry moves on") - - pin = _verify(topic) - assert to_row(pin)["registry_sha256"] == topic["registry_sha256"] - assert pin.registry_doc["registry_id"] == REGISTRY_ID - - -# --- the dirty worktree --------------------------------------------------------- - -def test_a_dirty_worktree_is_refused(topic) -> None: - """The producer's own `mfc seal` refuses one, for the reason the topic - repo's .gitignore states: the subject attests a gitCommit, and uncommitted - changes make every digest a true statement about a tree nobody can fetch.""" - _tag(topic["repo"], "v0.1.0", "release") - (topic["repo"] / "stray.txt").write_text("uncommitted\n", encoding="utf-8") - with pytest.raises(PinError, match="uncommitted change"): - refuse_dirty_worktree(topic["repo"]) - with pytest.raises(PinError, match="uncommitted change"): - _verify(topic) - - -def test_an_untracked_file_counts_as_dirty(topic) -> None: - """`git status --porcelain` reports untracked files, and so must this: - an untracked artifact is exactly how a stray build output gets pinned.""" - _tag(topic["repo"], "v0.1.0", "release") - (topic["repo"] / "scratch.log").write_text("x\n", encoding="utf-8") - with pytest.raises(PinError): - refuse_dirty_worktree(topic["repo"]) - - -# --- the digest block ----------------------------------------------------------- - -def test_an_absent_digest_block_is_no_digests_not_an_error() -> None: - """Every tag in the world today is in this state.""" - assert parse_digest_block("just a release message") == {} - - -def test_a_malformed_digest_block_is_raised_not_degraded_to_absent() -> None: - """A block that cannot be read is not the same fact as no block, and - degrading one to the other would turn a typo into a silent downgrade from - `git_rooted` to `self_attested_only`.""" - with pytest.raises(PinError, match="unparseable"): - parse_digest_block( - "-----BEGIN MFC DIGESTS-----\nattest/bundle.json deadbeef\n" - "-----END MFC DIGESTS-----" - ) - - -def test_an_empty_digest_block_is_raised(topic) -> None: - with pytest.raises(PinError, match="empty MFC DIGESTS block"): - parse_digest_block( - "-----BEGIN MFC DIGESTS-----\n\n-----END MFC DIGESTS-----") - - -def test_a_block_that_omits_the_bundle_roots_nothing(topic) -> None: - """Every other digest in the set is READ OUT OF the bundle, so a block that - names the leaves and not the root is a root of trust in name only.""" - assets = topic["assets"] - block = ("-----BEGIN MFC DIGESTS-----\n" - f"attest/declarations.json " - f"{_sha((assets / 'declarations.json').read_bytes())}\n" - "-----END MFC DIGESTS-----") - _tag(topic["repo"], "v0.1.0", "release\n\n" + block) - with pytest.raises(PinError, match="does not name attest/bundle.json"): - _verify(topic) - - -def test_a_predicate_the_block_omits_downgrades_rather_than_passing(topic) -> None: - """Partial rooting is not rooting. The bundle's own digest agreeing with - the file proves only that both were written together.""" - assets = topic["assets"] - block = ("-----BEGIN MFC DIGESTS-----\n" - f"attest/bundle.json {_sha((assets / 'bundle.json').read_bytes())}\n" - "-----END MFC DIGESTS-----") - _tag(topic["repo"], "v0.1.0", "release\n\n" + block) - pin = _verify(topic) - assert pin.digest_provenance == SELF_ATTESTED_ONLY - assert any("does not name it" in f for f in pin.findings) - - -# --- withdrawals travel forward in time ------------------------------------------ - -def _add_withdrawals(repo: Path, tag: str, *, registry_id: str = REGISTRY_ID) -> None: - """Commit a withdrawals file and tag it LATER than everything present. - - `GIT_COMMITTER_DATE` moves the annotated tag's creatordate: git tags have - one-second resolution, and a test that cut two tags in the same second - would be asserting against whatever the tiebreak happened to do. - """ - (repo / "attest").mkdir(exist_ok=True) - (repo / "attest" / "withdrawals.yaml").write_text( - f"schema_version: withdrawals/1.0\nregistry_id: {registry_id}\n" - f"withdrawals:\n" - f" - key: stmt:{registry_id}:bridgeland2007.lem-8.2\n" - f" withdrawn_at: '2026-09-01'\n" - f" reason: the reviewer withdrew it\n", - encoding="utf-8", - ) - _git(repo, "add", "-f", "attest/withdrawals.yaml") - _git(repo, "commit", "-q", "-m", "withdraw one entry") - subprocess.run( - ["git", "-C", str(repo), "tag", "-a", tag, "-m", "later release"], - capture_output=True, text=True, check=True, - env={**os.environ, "GIT_COMMITTER_DATE": "2030-01-01T00:00:00+0000"}, - ) - - -def test_withdrawals_are_read_from_the_newest_tag_not_the_pinned_one(topic) -> None: - """The single channel permitted to travel forward in time, and safe for - exactly one reason: it can only REMOVE trust, never grant it. - - Without this, a v0.1.0 pin keeps serving a record that v0.2.0 marked - inadequate, and nothing tells anyone. - """ - pytest.importorskip("yaml") - _tag(topic["repo"], "v0.1.0", "release") - _add_withdrawals(topic["repo"], "v0.2.0") - - pin = _verify(topic) - assert pin.tag.name == "v0.1.0" - assert pin.withdrawals_tag == "v0.2.0" - assert pin.withdrawals_doc["withdrawals"][0]["key"].endswith("lem-8.2") - - -def test_withdrawals_for_another_registry_are_refused(topic) -> None: - """Applying them would remove trust from keys they were never about, and - a revocation channel that fires on the wrong keys is worse than none.""" - pytest.importorskip("yaml") - _tag(topic["repo"], "v0.1.0", "release") - _add_withdrawals(topic["repo"], "v0.2.0", registry_id="ffffffffffff") - with pytest.raises(PinError, match="were never about"): - _verify(topic) - - -def test_no_withdrawals_file_is_a_legitimate_state(topic) -> None: - """Most repositories have never withdrawn anything.""" - _tag(topic["repo"], "v0.1.0", "release") - pin = _verify(topic) - assert pin.withdrawals_doc is None - assert pin.withdrawals_tag == "v0.1.0" - - -def test_the_newest_tag_is_by_creation_date_not_by_name(topic) -> None: - """A version comparator would have to be taught this repo's tag grammar, - and getting it wrong points the revocation channel at the WRONG tag — the - one direction this channel must never fail in.""" - _tag(topic["repo"], "v0.1.0", "release") - _add_withdrawals(topic["repo"], "v0.10.0") - assert newest_tag(topic["repo"]) == "v0.10.0" - - -# --- the row, and the write ------------------------------------------------------ - -def test_the_stored_registry_is_the_bytes_from_git(topic) -> None: - """Not a re-serialization. `registry_sha256` is computed over these bytes - and the topic repo compares it against its own `shasum`, so a - canonicalizing round-trip would make the served record disagree with the - pin that vouches for it.""" - _tag(topic["repo"], "v0.1.0", "release") - row = to_row(_verify(topic)) - assert _sha(row["registry_json"].encode()) == row["registry_sha256"] - - -def test_the_row_records_which_root_of_trust_the_pin_rests_on(topic) -> None: - _tag(topic["repo"], "v0.1.0", "release") - row = to_row(_verify(topic)) - assert row["digest_provenance"] == SELF_ATTESTED_ONLY - assert row["tag_object_sha"] and row["commit_sha"] == topic["commit"] - assert row["registry_id"] == REGISTRY_ID - assert row["env_digest"] == ENV_DIGEST - - -def test_writing_a_pin_migrates_the_db_rather_than_arming_the_drop( - topic, tmp_path: Path, -) -> None: - """The hazard #174 names, asserted on the new writer as well as the old. - - A sync writer that opened a raw connection would leave `user_version` at 0 - with real rows in the file, and the server's v0->v1 block — guarded by - `current_version < 1` and opening with an unconditional - `DROP TABLE IF EXISTS notebooks` — would drop them at the next start. - """ - import sqlite3 - - from server.notebooks_store import SCHEMA_VERSION - - _tag(topic["repo"], "v0.1.0", "release") - db = _notebook_db(tmp_path) - write_pin(db, to_row(_verify(topic))) - - conn = sqlite3.connect(db) - try: - assert conn.execute("PRAGMA user_version").fetchone()[0] == SCHEMA_VERSION - rows = conn.execute( - "SELECT slug, tag, digest_provenance FROM formal_releases" - ).fetchall() - finally: - conn.close() - assert rows == [("bridgeland-stability", "v0.1.0", SELF_ATTESTED_ONLY)] - - -def test_re_pinning_replaces_rather_than_accumulates(topic, tmp_path: Path) -> None: - """Two pins for one (slug, repo) would be two answers to "what does this - notebook serve", and the resource would have to choose — which is the - operator's decision, expressed by which tag they pinned.""" - import sqlite3 - - _tag(topic["repo"], "v0.1.0", "release") - db = _notebook_db(tmp_path) - row = to_row(_verify(topic)) - write_pin(db, row) - write_pin(db, {**row, "tag": "v0.2.0"}) - - conn = sqlite3.connect(db) - try: - assert conn.execute( - "SELECT tag FROM formal_releases").fetchall() == [("v0.2.0",)] - finally: - conn.close() - - -def test_nothing_is_written_when_verification_refuses(topic, tmp_path: Path) -> None: - """A partial pin is worse than no pin: the resource would serve a record - whose verification never finished.""" - _tag(topic["repo"], "v0.1.0", "release") - (topic["repo"] / "stray.txt").write_text("dirty\n", encoding="utf-8") - db = tmp_path / "notebooks.db" - with pytest.raises(PinError): - _verify(topic) - assert not db.exists() diff --git a/tests/test_formal_resource.py b/tests/test_formal_resource.py deleted file mode 100644 index 30b3691..0000000 --- a/tests/test_formal_resource.py +++ /dev/null @@ -1,521 +0,0 @@ -"""The formal-release resources, and the zero-cost claim proved mechanically. - -derived-alg-geo-lean **#175**. Two resources — ``arxmcp://formal/{notebook}`` -and ``arxmcp://formal/{notebook}/{key}`` — and the reason they are RESOURCES -rather than tools is a claim, not a preference: ``resources/read`` is a -different JSON-RPC method from ``tools/call``, so ``tools/list`` bytes are -untouched and neither ``EXPECTED_TOOL_SCHEMA_SHA256`` nor the BP1 prompt-cache -prefix moves. The issue asks for that to be asserted here rather than in a PR -description, which is what :class:`TestByteStability` does. - -The other half is ADR-0004's asymmetry, which is the whole permission model -across the seam: arXMCP MAY downgrade a trust axis from its own fresher -information and has NO code path that raises one. So the record is re-served -verbatim and every judgement this server adds arrives as a generated caveat -BESIDE it. Those tests are the ones that fail if someone later "helpfully" -annotates a record in place. - -Private-loop store fixture, mirroring ``tests/test_mcp_resources.py``. No -model load, no LanceDB, no network. -""" - -from __future__ import annotations - -import asyncio -import json -from collections.abc import Iterator -from pathlib import Path - -import pytest -from mcp.server.fastmcp import FastMCP - -from server.corpus import CORPUS_VERSION_MARKER_NAME -from server.mcp_resources import ( - CENSUS_SOURCE_CORPUS_VERSION_MARKER, - CENSUS_UNMEASURED_NO_CORPUS_MARKER, - CENSUS_UNMEASURED_UNAVAILABLE, - FORMAL_INDEX_TEMPLATE_URI, - FORMAL_RECORD_TEMPLATE_URI, - register_resources, - reset_notebooks_store_for_tests, - set_notebooks_store, -) -from server.notebooks_store import NotebooksStore -from server.tools import register_all -from tests.test_server_tool_schema import ( - EXPECTED_TOOL_SCHEMA_SHA256, - compute_tool_schema_hash, -) -from tools import _notebook_common - -SLUG = "bridgeland-stability" -REGISTRY_ID = "a520a8d4f877" -KEY = f"stmt:{REGISTRY_ID}:bridgeland2007.lem-8.2" -OTHER_KEY = f"stmt:{REGISTRY_ID}:bridgeland2007.def-1.1" - - -def _registry() -> dict: - def entry(printed: str, version: str = "v3") -> dict: - return { - "kind": "lemma", "title": "A bound", "informal": "A bound.", - "source": {"scheme": "arxiv", "id": "math/0212237", - "version": version, "printed_number": printed, - "locator": None}, - "quote_mode": "verbatim", "quote": f"Lemma {printed}. A bound.", - "quote_norm": "nfc-ws-collapse/1", "quote_sha256": "e" * 64, - "mint_resolution": None, - "mint_unresolved_reason": "no resolver run", - "depends_on": [], "frontier": [], - "minted_at": "2026-08-05", "minted_by": "Chris Dare", - "supersedes": None, "superseded_by": None, - } - - return { - "schema_version": "registry/1.0", - "registry_id": REGISTRY_ID, - "notebook_hint": SLUG, - "entries": {KEY: entry("8.2"), OTHER_KEY: entry("1.1")}, - } - - -def _pin_row(**overrides) -> dict: - row = { - "slug": SLUG, - "repo": "https://github.com/chris-dare-dev/derived-alg-geo-lean", - "tag": "v0.1.0", - "tag_object_sha": "df9e6e6d46028000bfd2241d2061cadcbb21e79d", - "commit_sha": "7f649532ad83ac6a93b90918cba9fdbd779cec67", - "registry_id": REGISTRY_ID, - "registry_sha256": "f" * 64, - "env_digest": "45d9e8ca8c1b" + "c" * 52, - "digest_provenance": "self_attested_only", - "asset_dir": "/abs/host/path/assets", - "bundle_json": json.dumps({"schema_version": "bundle/1.0"}), - "registry_json": json.dumps(_registry()), - "resolution_json": None, - "review_json": None, - "withdrawals_json": None, - "withdrawals_tag": "v0.1.0", - "pinned_at": "2026-09-03T12:00:00Z", - } - row.update(overrides) - return row - - -@pytest.fixture -def env( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch -) -> Iterator[tuple[asyncio.AbstractEventLoop, NotebooksStore]]: - base = tmp_path / "notebooks" - base.mkdir() - monkeypatch.setattr(_notebook_common, "NOTEBOOKS_BASE", base) - loop = asyncio.new_event_loop() - store = loop.run_until_complete(NotebooksStore.open(tmp_path / "notebooks.db")) - loop.run_until_complete(store.create_notebook( - slug=SLUG, display_name="Bridgeland stability", - lancedb_path=str(base / SLUG / "lancedb"), - created_at="2026-05-21T00:00:00Z", - )) - set_notebooks_store(store) - try: - yield loop, store - finally: - loop.run_until_complete(store.close()) - loop.close() - reset_notebooks_store_for_tests() - - -def _mcp() -> FastMCP: - mcp = FastMCP("arxmcp", json_response=True) - register_all(mcp) - register_resources(mcp) - return mcp - - -def _read(loop, mcp: FastMCP, uri: str) -> dict: - contents = loop.run_until_complete(mcp.read_resource(uri)) - text = "".join(c.content for c in contents) - assert text.startswith("") - assert text.endswith("") - inner = text[len(""): -len("")] - return json.loads(inner) - - -def _pin(loop, store: NotebooksStore, **overrides) -> None: - loop.run_until_complete(store.upsert_formal_release(_pin_row(**overrides))) - - -def _ingest_marker(tmp_path: Path, text: str | None = None, **overrides) -> Path: - """Stamp a `corpus-version.json` under the notebook, as an ingest would. - - The census denominator is read from this file rather than counted live in - LanceDB (#179), so "ingested" in these tests means exactly "this marker - exists and parses" — no dataset, no embedder, no LanceDB. `text` writes - raw bytes instead, for the corrupt-marker path. - """ - lancedb = tmp_path / "notebooks" / SLUG / "lancedb" - lancedb.mkdir(parents=True, exist_ok=True) - marker = lancedb / CORPUS_VERSION_MARKER_NAME - if text is not None: - marker.write_text(text, encoding="utf-8") - return marker - payload = { - "version": 7, - "chunker_version": "chunker/2", - "embedder_version": "bge-m3/1", - "created_at": "2026-08-30T04:12:00Z", - "paper_count": 146, - "chunk_count": 15280, - } - payload.update(overrides) - marker.write_text(json.dumps(payload), encoding="utf-8") - return marker - - -# --- the zero-cost claim, asserted rather than described ------------------------ - -class TestByteStability: - """`EXPECTED_TOOL_SCHEMA_SHA256` and the BP1 prefix must not move. - - #175: "must assert EXPECTED_TOOL_SCHEMA_SHA256 is unchanged — proving the - zero-cost claim mechanically rather than asserting it in a PR - description." If one of these fails, a resource LEAKED into the tool - registry. Fix the leak; do not re-pin the constant. - """ - - def test_the_tool_schema_hash_is_unchanged(self) -> None: - tools = asyncio.run(_mcp().list_tools()) - assert compute_tool_schema_hash(tools) == EXPECTED_TOOL_SCHEMA_SHA256 - - def test_the_formal_resources_add_no_tools(self) -> None: - """Two servers, one with the resources: identical tool lists. - - Stronger than comparing against the pinned constant alone, which would - also pass if BOTH the constant and the surface had drifted together. - """ - base = FastMCP("arxmcp", json_response=True) - register_all(base) - base_tools = asyncio.run(base.list_tools()) - with_resources = asyncio.run(_mcp().list_tools()) - assert [t.name for t in base_tools] == [t.name for t in with_resources] - assert compute_tool_schema_hash(base_tools) == \ - compute_tool_schema_hash(with_resources) == EXPECTED_TOOL_SCHEMA_SHA256 - - def test_they_are_registered_as_templates_on_notebook(self) -> None: - """Templating on `{notebook}` is what makes a SECOND topic repo cost - zero arXMCP code — no new URI, no new registration, no schema bump.""" - templates = asyncio.run(_mcp().list_resource_templates()) - uris = {str(t.uriTemplate) for t in templates} - assert FORMAL_INDEX_TEMPLATE_URI in uris - assert FORMAL_RECORD_TEMPLATE_URI in uris - - -# --- a notebook that pins nothing ---------------------------------------------- - -def test_an_unpinned_notebook_answers_rather_than_erroring(env) -> None: - """"This corpus has no formalization" is an answer, and it is the state - almost every notebook is in. Raising here would make the ordinary case - look like a fault.""" - loop, _ = env - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}") - assert payload["pinned"] is False - assert "no formal release is pinned" in payload["reason"] - - -def test_a_record_read_on_an_unpinned_notebook_is_an_error(env) -> None: - """Different from the index: there is no record to describe, so there is - nothing to answer WITH.""" - loop, _ = env - with pytest.raises(Exception, match="pins no formal release"): - _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - - -# --- the index ----------------------------------------------------------------- - -def test_the_index_reports_what_was_pinned_and_how_it_was_verified(env) -> None: - loop, store = env - _pin(loop, store) - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}") - assert payload["pinned"] is True - assert payload["pin"]["tag"] == "v0.1.0" - assert payload["pin"]["tag_object_sha"].startswith("df9e6e6d") - assert payload["pin"]["digest_provenance"] == "self_attested_only" - assert sorted(payload["keys"]) == sorted([KEY, OTHER_KEY]) - - -class TestDatedCensus: - """#179. §4.9 rule 3: coverage is a dated, scoped census. - - #175 shipped the numerator and a null `corpus_chunks` naming this issue as - the denominator's owner. These tests are that owner: the denominator ships, - it is dated, and when it cannot be measured the null says WHICH KIND of - null it is — because "this notebook has no corpus" and "I could not read - how big the corpus is" are opposite facts that a bare `null` conflates - (§4.9 rule 2). - """ - - def test_the_denominator_ships_beside_the_numerator_and_is_dated( - self, env, tmp_path: Path - ) -> None: - """Two records against a 15,280-chunk notebook have covered a sliver of - it. Both numbers are in the same response, and the denominator carries - the moment it was true rather than implying "now".""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert census["entries"] == 2 - assert census["papers_covered"] == 1 - assert census["corpus_chunks"] == 15280 - assert census["corpus_papers"] == 146 - assert census["corpus_version"] == 7 - assert census["corpus_measured_at"] == "2026-08-30T04:12:00Z" - assert census["corpus_source"] == CENSUS_SOURCE_CORPUS_VERSION_MARKER - assert census["corpus_unmeasured_reason"] is None - assert census["generated_at"].endswith("Z") - - def test_the_denominator_is_dated_separately_from_the_response( - self, env, tmp_path: Path - ) -> None: - """`generated_at` stamps the READ; `corpus_measured_at` stamps the - MEASUREMENT. Collapsing them into one timestamp is the bug this field - exists to prevent — it would date a months-old count to this second.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert census["corpus_measured_at"] != census["generated_at"] - - def test_no_coverage_ratio_is_computed_for_the_reader( - self, env, tmp_path: Path - ) -> None: - """Entries are statements; chunks are text chunks. Dividing them would - manufacture a percentage out of two different units, so the census - states both numbers and says, in the note, why it stops there.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert not [k for k in census if "fraction" in k or "percent" in k] - assert "mixes units" in census["corpus_chunks_note"] - - def test_the_coverage_caveat_quotes_the_census_rather_than_pointing_at_it( - self, env, tmp_path: Path - ) -> None: - """A reader who stops after `caveats[]` has still seen the - denominator. #175's caveat could only say the fraction existed.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - caveats = " ".join(_read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["caveats"]) - assert "15280 chunks" in caveats - assert "146 papers" in caveats - assert "2026-08-30T04:12:00Z" in caveats - # Agent-facing prose agrees with its numbers: "1 cited paper", never - # "1 cited papers". These lines are what a reader who skims the JSON - # still reads. - assert "1 cited paper," in caveats - assert "2 entries covering" in caveats - - def test_an_unstamped_notebook_is_an_answer_not_a_zero(self, env) -> None: - """No marker means nothing stamped a size. The denominator is `null` - with reason `no-corpus-marker` — NEVER `0`, which would claim the - notebook is empty and make any registry read as total coverage of it. - - The token names the OBSERVATION, not its usual cause: `is_ingested` on - the notebook resource answers a different question (does the lancedb - dir exist) and a crashed ingest makes the two disagree honestly.""" - loop, store = env - _pin(loop, store) - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert census["corpus_chunks"] is None - assert census["corpus_papers"] is None - assert census["corpus_measured_at"] is None - assert census["corpus_unmeasured_reason"] == CENSUS_UNMEASURED_NO_CORPUS_MARKER - # "we looked here and found nothing" != "we did not look". - assert census["corpus_source"] == CENSUS_SOURCE_CORPUS_VERSION_MARKER - caveats = " ".join(_read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["caveats"]) - assert "no corpus-version marker stamps a size" in caveats - - def test_an_unreadable_marker_is_a_fault_not_a_small_notebook( - self, env, tmp_path: Path - ) -> None: - """§4.9 rule 2, applied to the census: an operational failure must not - wear an epistemic token. A corrupt marker says `unavailable`, which is - a different word from `no-corpus-marker` on purpose.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path, text="{not json at all") - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}") - census = payload["census"] - assert census["corpus_chunks"] is None - assert census["corpus_unmeasured_reason"] == CENSUS_UNMEASURED_UNAVAILABLE - assert "OPERATIONAL" in " ".join(payload["caveats"]) - - def test_a_bad_denominator_never_takes_down_the_pin_record( - self, env, tmp_path: Path - ) -> None: - """The census is a report ABOUT the corpus. An unreadable corpus marker - must not cost the reader the pin, the keys, or the other caveats.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path, text="{not json at all") - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}") - assert payload["pinned"] is True - assert payload["pin"]["tag"] == "v0.1.0" - assert sorted(payload["keys"]) == sorted([KEY, OTHER_KEY]) - assert "self_attested_only" in " ".join(payload["caveats"]) - - def test_the_census_costs_no_lancedb_read(self, env, tmp_path: Path) -> None: - """`resources/read` is unauthenticated. The denominator comes from the - ingest-time marker, so an anonymous caller cannot make this path open - and scan a dataset — asserted by there being no dataset at all.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - lancedb = tmp_path / "notebooks" / SLUG / "lancedb" - assert not (lancedb / "chunks.lance").exists() - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert census["corpus_chunks"] == 15280 - - def test_a_record_read_carries_no_census(self, env, tmp_path: Path) -> None: - """Coverage is a property of the index, not of one record. Attaching a - census to a single entry would invite reading it as that entry's.""" - loop, store = env - _pin(loop, store) - _ingest_marker(tmp_path) - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert "census" not in payload - assert not [c for c in payload["caveats"] if "dated census" in c] - - -def test_the_index_caveats_name_every_absent_axis(env) -> None: - """Absent is not passing. A pin with no resolution and no review says so - on every read, rather than leaving a reader to notice two missing keys.""" - loop, store = env - _pin(loop, store) - caveats = " ".join(_read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["caveats"]) - assert "self_attested_only" in caveats - assert "No corpus resolution" in caveats - assert "No human faithfulness review" in caveats - - -# --- one record, verbatim ------------------------------------------------------- - -def test_the_record_is_the_producers_entry_byte_for_byte(env) -> None: - """ADR-0004: arXMCP may DOWNGRADE an axis from its own fresher - information, and has no code path that raises one. Re-serving verbatim is - what makes that asymmetry checkable — an edited record cannot be compared - to what the producer published.""" - loop, store = env - _pin(loop, store) - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert payload["entry"] == _registry()["entries"][KEY] - - -def test_this_servers_judgements_arrive_beside_the_record_not_inside_it(env) -> None: - """The caveats are the only channel. If a future change annotates the - entry in place, this fails — which is the point.""" - loop, store = env - _pin(loop, store) - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert set(payload["entry"]) == set(_registry()["entries"][KEY]) - assert payload["caveats"] and isinstance(payload["caveats"], list) - - -def test_an_unknown_key_is_an_error_not_an_empty_record(env) -> None: - loop, store = env - _pin(loop, store) - with pytest.raises(Exception, match="no entry"): - _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/stmt:{REGISTRY_ID}:nope") - - -# --- withdrawals come first ----------------------------------------------------- - -def _withdrawals(key: str = KEY, registry_id: str = REGISTRY_ID) -> str: - return json.dumps({ - "schema_version": "withdrawals/1.0", - "registry_id": registry_id, - "withdrawals": [{ - "key": key, - "withdrawn_at": "2026-09-01", - "reason": "the reviewer found the statement diverges from the paper", - }], - }) - - -def test_a_withdrawn_record_says_so_first(env) -> None: - """The worst failure this contract can have is a record a human has - determined is NOT faithful still being served as evidence. A reader who - stops after one caveat must read that one.""" - loop, store = env - _pin(loop, store, withdrawals_json=_withdrawals(), withdrawals_tag="v0.2.0") - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert payload["withdrawn"] is True - assert payload["caveats"][0].startswith("WITHDRAWN") - assert "diverges from the paper" in payload["caveats"][0] - - -def test_a_withdrawal_names_the_tag_it_came_from(env) -> None: - """It is read from the NEWEST tag even when pinned to an older one — the - single channel allowed to travel forward in time. A reader comparing the - pinned tag to the withdrawal's tag must be able to see that happen.""" - loop, store = env - _pin(loop, store, withdrawals_json=_withdrawals(), withdrawals_tag="v0.2.0") - caveat = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}")["caveats"][0] - assert "v0.2.0" in caveat and "v0.1.0" in caveat - - -def test_a_withdrawal_of_another_key_does_not_touch_this_one(env) -> None: - """A revocation channel that fires on the wrong keys is worse than none.""" - loop, store = env - _pin(loop, store, withdrawals_json=_withdrawals(key=OTHER_KEY)) - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert payload["withdrawn"] is False - assert not any(c.startswith("WITHDRAWN") for c in payload["caveats"]) - - -def test_the_index_counts_withdrawn_entries(env) -> None: - loop, store = env - _pin(loop, store, withdrawals_json=_withdrawals()) - census = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}")["census"] - assert census["entries"] == 2 and census["withdrawn"] == 1 - - -def test_unparseable_withdrawals_do_not_take_the_resource_down(env) -> None: - """A record served WITHOUT its withdrawal is the failure this channel - exists to prevent, so the alternative would be to fail the read — but the - withdrawals blob is written by the pinner, which validated it, and a - corrupt one here means local damage rather than an untrustworthy producer. - Degrade to no-withdrawals and log; the caveats still say no review and no - resolution accompany the pin.""" - loop, store = env - _pin(loop, store, withdrawals_json="{not json") - payload = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert payload["withdrawn"] is False - - -# --- security ------------------------------------------------------------------- - -def test_an_invalid_slug_is_rejected_before_any_store_access(env) -> None: - """`validate_slug` FIRST — the same discipline the notebook resources - carry. A traversal in the notebook segment must never reach a path join.""" - loop, _ = env - # `NotebookError` is what `validate_slug` raises; FastMCP may wrap a - # resource-callback failure, so the assertion is on the MESSAGE reaching - # the caller rather than on the class. A bare `Exception` would also pass - # if the read failed for an unrelated reason. - with pytest.raises(Exception, match="(?i)slug"): - _read(loop, _mcp(), "arxmcp://formal/..%2F..%2Fetc") - - -def test_the_payload_never_exposes_the_asset_dir(env) -> None: - """`asset_dir` is a host path. It is in the pin so an OPERATOR can find - the 16 MB artifacts; it is not in the served record, because a filesystem - layout is not something an agent on the other side of the seam needs.""" - loop, store = env - _pin(loop, store) - index = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}") - record = _read(loop, _mcp(), f"arxmcp://formal/{SLUG}/{KEY}") - assert "/abs/host/path" not in json.dumps(index) - assert "/abs/host/path" not in json.dumps(record) diff --git a/tests/test_notebook_api.py b/tests/test_notebook_api.py index e2a7f52..4ff9dd9 100644 --- a/tests/test_notebook_api.py +++ b/tests/test_notebook_api.py @@ -1468,17 +1468,11 @@ async def _open_twice() -> tuple[int, list[str], int, list[str]]: assert "description" in c2 -class TestV5ToV6Migration: - """contract-v1 (derived-alg-geo-lean #174) — ``formal_releases``. - - ADDITIVE, like every block since v1->v2: a schema bump on notebook - METADATA must never lose a row. The v0->v1 block is the only destructive - one and it is guarded by ``current_version < 1``, which is precisely why a - writer that leaves ``user_version`` at 0 is a data-loss hazard rather than - an untidiness. - """ +class TestV6ToV7Migration: + """v7 drops ``formal_releases`` (the release pin was removed). That is the + one migration that drops a table; it must take only that table.""" - def test_v5_to_v6_adds_the_table_without_touching_existing_rows( + def test_v6_to_v7_drops_the_pin_table_and_keeps_notebooks( self, tmp_path: Path, ) -> None: import asyncio @@ -1486,22 +1480,27 @@ def test_v5_to_v6_adds_the_table_without_touching_existing_rows( db_path = tmp_path / "notebooks.db" - async def _seed_v5_then_open() -> tuple[int, list[str], list[str]]: - # A real v5 file, built by the store itself rather than by a - # hand-written CREATE that could drift from it. + async def _seed_v6_then_open() -> tuple[int, list[str], list[str]]: store = await NotebooksStore.open(db_path) try: await store.create_notebook( - slug="legacy-v5", display_name="Legacy v5", + slug="legacy-v6", display_name="Legacy v6", lancedb_path="/tmp/legacy/lancedb", created_at="2026-01-01T00:00:00+00:00", ) finally: await store.close() + # Rewind to v6 with a pinned row, as a file written before the + # pin was removed would be. conn = sqlite3.connect(str(db_path)) try: - conn.execute("PRAGMA user_version = 5") - conn.execute("DROP TABLE IF EXISTS formal_releases") + conn.execute( + "CREATE TABLE formal_releases (slug TEXT, repo TEXT, tag TEXT)" + ) + conn.execute( + "INSERT INTO formal_releases VALUES ('legacy-v6', 'r', 'v1')" + ) + conn.execute("PRAGMA user_version = 6") conn.commit() finally: conn.close() @@ -1515,44 +1514,16 @@ async def _seed_v5_then_open() -> tuple[int, list[str], list[str]]: conn = sqlite3.connect(str(db_path)) try: version = int(conn.execute("PRAGMA user_version").fetchone()[0]) - cols = [r[1] for r in conn.execute( - "PRAGMA table_info(formal_releases)").fetchall()] + tables = [r[0] for r in conn.execute( + "SELECT name FROM sqlite_master WHERE type = 'table'")] finally: conn.close() - return version, cols, slugs - - version, cols, slugs = asyncio.run(_seed_v5_then_open()) - assert version == SCHEMA_VERSION - assert slugs == ["legacy-v5"], "the v5 row must survive the bump" - assert "digest_provenance" in cols - assert "tag_object_sha" in cols - - def test_a_pin_requires_the_notebook_it_is_served_under( - self, tmp_path: Path, - ) -> None: - """The FK is load-bearing: a pin for a notebook that does not exist is - a record nothing can serve, and the resources reach it by slug.""" - import asyncio - import sqlite3 + return version, tables, slugs - async def _run() -> None: - store = await NotebooksStore.open(tmp_path / "notebooks.db") - try: - with pytest.raises(sqlite3.IntegrityError): - await store.upsert_formal_release({ - "slug": "no-such-notebook", "repo": "r", "tag": "v1", - "tag_object_sha": "a", "commit_sha": "b", - "registry_id": "c", "registry_sha256": "d", - "env_digest": "e", "digest_provenance": "git_rooted", - "asset_dir": "", "bundle_json": "{}", - "registry_json": "{}", "resolution_json": None, - "review_json": None, "withdrawals_json": None, - "withdrawals_tag": None, "pinned_at": "2026-09-03", - }) - finally: - await store.close() - - asyncio.run(_run()) + version, tables, slugs = asyncio.run(_seed_v6_then_open()) + assert version == SCHEMA_VERSION == 7 + assert "formal_releases" not in tables + assert slugs == ["legacy-v6"], "the notebook row must survive the bump" class TestNotebookTopicMetadata: diff --git a/tools/formal_release_pin.py b/tools/formal_release_pin.py deleted file mode 100644 index d89cecf..0000000 --- a/tools/formal_release_pin.py +++ /dev/null @@ -1,661 +0,0 @@ -"""Pin a topic repo's released formalization. Re-derives from git, not from the bundle. - -Lands derived-alg-geo-lean **#174** (epic #135). Offline, read-only over the -topic repo, and it writes exactly one row into ``notebooks.db``'s -``formal_releases`` table (v6). ADR-0004: arXMCP hosts no registry — it holds a -**pin** to a released one and re-serves its records verbatim. - -## The weakness this exists to fix - -A bundle that crosses the seam validated only for *self-consistency* has no -producer-side gate that survives a file copy. Every one of the design's -sorry-gates was on the producer's side; none of them travelled with the -artifact. Flip ``contains_sorry_ax`` in ``declarations.json``, recompute that -file's sha256 into ``bundle.json``, and the set is internally consistent and -says the opposite of what CI measured. - -So the root of trust is the **git tag object**, which the producer's own tag -message names as such: - - The tag object, not the bundle's self-reported hashes, is the root of - trust across the seam: arXMCP re-derives digests from it. - -## What is actually re-derivable, and what is not - -This is where the design and the repository disagree today, and the tool says -so rather than papering over it. - -**Re-derivable from git, and checked:** - -* ``subject[0].digest.gitCommit`` — against ``git rev-parse ^{commit}``. -* ``subject[0].digest.gitTag`` — against the tag name on the tag object. -* ``registry_sha256`` — against ``sha256(git show :registry/.json)``. - The registry IS tracked, and it is the artifact arXMCP re-serves. - -**Not re-derivable, because the files are not in git:** -``attest/*`` is gitignored in the topic repo (``/attest/*`` with a single -``!/attest/review.yaml`` re-include), deliberately — CI regenerates those on -every run and a committed copy would be a stale trust record. They exist only -as release assets. So ``predicates[].sha256`` can be checked for *internal* -consistency against the asset bytes and nothing more, and the tamper above is -NOT caught by any git-rooted check. - -That is a real gap and it is reported, never hidden: the pin records -``digest_provenance`` as ``git_rooted`` or ``self_attested_only``, and -``self_attested_only`` is never presented as a pass. §4.9 rule 1 — no axis is -inferred from another, and no bare "verified". - -**How to close it, at the next tag.** Put the digests in the tag message, -which is the one artifact the tag object actually carries and which no asset -replacement can reach. This tool parses that block already:: - - -----BEGIN MFC DIGESTS----- - attest/bundle.json - attest/declarations.json - attest/environment.json - attest/build.json - -----END MFC DIGESTS----- - -With the block present the tamper test refuses, because the recomputed -``bundle.json`` no longer matches the digest the tag object names. v0.1.0's -message carries prose asserting this property and no block, so pinning it -today reports ``self_attested_only``. - -## The withdrawals channel travels forward in time - -``withdrawals.yaml`` is fetched from the **newest** tag even when pinned to an -older one — the single channel permitted to do that, and safe for exactly one -reason: it can only REMOVE trust, never grant it. Without it, a v0.1.0 pin -keeps serving a record that v0.2.0 marked ``inadequate`` and nothing tells -anyone. - -Usage:: - - uv run python -m tools.formal_release_pin \\ - --repo-path ../derived-alg-geo-lean \\ - --tag v0.1.0 \\ - --notebook bridgeland-stability \\ - --assets ./release-assets \\ - --registry registry/bridgeland2007.json - -Exit codes: - 0 — pinned - 1 — refused: dirty worktree, unknown tag, digest mismatch, or an artifact - that does not validate. Nothing is written on any refusal. -""" - -from __future__ import annotations - -import argparse -import hashlib -import json -import re -import sqlite3 -import subprocess -import sys -from dataclasses import dataclass -from datetime import UTC, datetime -from pathlib import Path - -from tools._statement_common import StatementToolError, validate_against - -#: Digest provenance, and the two values are NOT a scale with a passing end. -#: `git_rooted` means the tag object names the digests and they match. -#: `self_attested_only` means the artifact set agrees with itself and nothing -#: outside it was consulted, which is the state a file copy survives. -GIT_ROOTED = "git_rooted" -SELF_ATTESTED_ONLY = "self_attested_only" - -#: The optional digest block in an annotated tag's message. Whitespace-tolerant -#: on the separator so a hand-written tag is not rejected for two spaces. -_DIGEST_BLOCK_RE = re.compile( - r"-----BEGIN MFC DIGESTS-----(?P.*?)-----END MFC DIGESTS-----", - re.DOTALL, -) -_DIGEST_LINE_RE = re.compile(r"^\s*(?P\S+)\s+(?P[0-9a-f]{64})\s*$") - - -class PinError(StatementToolError): - """A refusal. Printed, exit 1, nothing written.""" - - -@dataclass(frozen=True) -class TagObject: - """What the git tag object itself says.""" - - name: str - object_sha: str - commit_sha: str - message: str - digests: dict[str, str] - - @property - def is_annotated(self) -> bool: - """A lightweight tag is a ref, not an object, and carries no message. - - It can still name a commit, so the commit check holds; there is simply - nothing for a digest block to live in. - """ - return self.object_sha != self.commit_sha - - -def _git(repo: Path, *args: str) -> str: - proc = subprocess.run( - ["git", "-C", str(repo), *args], - capture_output=True, text=True, check=False, - ) - if proc.returncode != 0: - raise PinError( - f"git {' '.join(args)} failed in {repo}: " - f"{proc.stderr.strip() or proc.stdout.strip()}" - ) - return proc.stdout - - -def refuse_dirty_worktree(repo: Path) -> None: - """A dirty tree makes every digest a true statement about a tree nobody can fetch. - - The producer's own `mfc seal` refuses one for the same reason; a consumer - that did not would accept a pin nobody else can reproduce. - """ - porcelain = _git(repo, "status", "--porcelain").strip() - if porcelain: - lines = porcelain.split("\n") - shown = "\n".join(f" {ln}" for ln in lines[:10]) - more = f"\n … and {len(lines) - 10} more" if len(lines) > 10 else "" - raise PinError( - f"{repo} has {len(lines)} uncommitted change(s); refusing to pin.\n" - f"{shown}{more}\n" - f"The pin names a commit, and a dirty tree means the files here " - f"are not that commit. Stash or commit, then re-run." - ) - - -def read_tag(repo: Path, tag: str) -> TagObject: - """Resolve ``tag`` to its object, its commit, and any digest block.""" - object_sha = _git(repo, "rev-parse", "--verify", f"refs/tags/{tag}").strip() - commit_sha = _git(repo, "rev-parse", "--verify", f"{tag}^{{commit}}").strip() - kind = _git(repo, "cat-file", "-t", object_sha).strip() - message = _git(repo, "cat-file", "tag", object_sha) if kind == "tag" else "" - return TagObject( - name=tag, - object_sha=object_sha, - commit_sha=commit_sha, - message=message, - digests=parse_digest_block(message), - ) - - -def parse_digest_block(message: str) -> dict[str, str]: - """``{path: sha256}`` from a tag message's digest block; ``{}`` when absent. - - Absent is the ordinary case today and is NOT an error — it is the reason - the pin reads ``self_attested_only``. Silently returning ``{}`` for a - MALFORMED block would be, so a block containing no parseable line raises. - """ - match = _DIGEST_BLOCK_RE.search(message) - if match is None: - return {} - digests: dict[str, str] = {} - for line in match.group("body").split("\n"): - if not line.strip(): - continue - entry = _DIGEST_LINE_RE.match(line) - if entry is None: - raise PinError( - f"the tag's MFC DIGESTS block has an unparseable line: " - f"{line.strip()!r}. Expected ` <64-hex sha256>`. A block " - f"that cannot be read is not the same as no block, and it must " - f"not degrade quietly to one." - ) - digests[entry.group("path")] = entry.group("sha") - if not digests: - raise PinError( - "the tag carries an empty MFC DIGESTS block; that is not a " - "digest-free tag, it is a broken one" - ) - return digests - - -def blob_at(repo: Path, tag: str, path: str) -> bytes | None: - """The bytes of ``path`` in git at ``tag``, or ``None`` when untracked there.""" - proc = subprocess.run( - ["git", "-C", str(repo), "show", f"{tag}:{path}"], - capture_output=True, check=False, - ) - return proc.stdout if proc.returncode == 0 else None - - -def sha256_bytes(data: bytes) -> str: - return hashlib.sha256(data).hexdigest() - - -def newest_tag(repo: Path) -> str | None: - """The most recent tag — where withdrawals are read from. - - Creation date, not a version comparator: a comparator has to be taught - this repo's tag grammar, and getting it wrong would point the revocation - channel at the WRONG tag, which is the one direction this channel must - never fail in. - - Ties are broken by refname, descending. Git tag timestamps have - one-second resolution and two tags cut in the same second sort - arbitrarily otherwise -- which would make the channel non-deterministic - exactly when a release is being re-cut, and that is when it matters. - """ - out = _git( - repo, "for-each-ref", "--format=%(creatordate:unix) %(refname:short)", - "refs/tags", - ).strip() - rows = [] - for line in out.split("\n"): - if not line.strip(): - continue - stamp, _, name = line.partition(" ") - rows.append((int(stamp), name)) - if not rows: - return None - return max(rows)[1] - - -@dataclass -class Pin: - """Everything verified, ready to write. Assembled only on a clean run.""" - - slug: str - repo_url: str - tag: TagObject - registry_path: str - registry_bytes: bytes - registry_doc: dict - bundle_doc: dict - digest_provenance: str - findings: list[str] - withdrawals_doc: dict | None - withdrawals_tag: str | None - asset_dir: str - - -def verify( - repo: Path, - *, - tag_name: str, - slug: str, - registry_path: str, - assets: Path | None, - allow_dirty: bool = False, -) -> Pin: - """Every check, in order. Raises :class:`PinError` on the first refusal.""" - if not (repo / ".git").exists(): - raise PinError(f"{repo} is not a git repository") - if not allow_dirty: - refuse_dirty_worktree(repo) - - tag = read_tag(repo, tag_name) - - # --- the registry, which IS in git ------------------------------------ - registry_bytes = blob_at(repo, tag_name, registry_path) - if registry_bytes is None: - raise PinError( - f"{registry_path} is not tracked at {tag_name}. The registry is " - f"the one contract artifact this tool can root in git, so a pin " - f"without it has no git-rooted axis at all." - ) - registry_doc = json.loads(registry_bytes.decode("utf-8")) - registry_sha256 = sha256_bytes(registry_bytes) - - # --- the bundle, from the assets -------------------------------------- - bundle_doc, bundle_bytes = _load_bundle(repo, tag_name, assets) - validate_against(bundle_doc, "bundle-1.0") - - subject = (bundle_doc.get("subject") or [{}])[0] - digest = subject.get("digest") or {} - if digest.get("gitCommit") != tag.commit_sha: - raise PinError( - f"the bundle attests gitCommit {digest.get('gitCommit')!r} and " - f"{tag_name} points at {tag.commit_sha!r}. These artifacts " - f"describe a different tree than the one being pinned." - ) - if digest.get("gitTag") != tag_name: - raise PinError( - f"the bundle attests gitTag {digest.get('gitTag')!r}, not " - f"{tag_name!r}. An artifact set built before its tag existed says " - f"null here -- a valid artifact and an invalid release." - ) - if bundle_doc.get("registry_sha256") != registry_sha256: - raise PinError( - f"registry_sha256 disagrees. The bundle says " - f"{bundle_doc.get('registry_sha256')!r}; {registry_path} at " - f"{tag_name} hashes to {registry_sha256!r}. This is the check the " - f"whole seam rests on: the bundle describes a registry that is " - f"not the one in this tag." - ) - - # --- the predicates, rooted in the tag object when it says so --------- - provenance, findings = _check_predicates( - repo, tag, bundle_doc, bundle_bytes, assets - ) - - withdrawals_doc, withdrawals_tag = _load_withdrawals(repo, registry_doc) - - return Pin( - slug=slug, - repo_url=_remote_url(repo), - tag=tag, - registry_path=registry_path, - registry_bytes=registry_bytes, - registry_doc=registry_doc, - bundle_doc=bundle_doc, - digest_provenance=provenance, - findings=findings, - withdrawals_doc=withdrawals_doc, - withdrawals_tag=withdrawals_tag, - asset_dir=str(assets) if assets else "", - ) - - -def _load_bundle( - repo: Path, tag_name: str, assets: Path | None -) -> tuple[dict, bytes]: - """``attest/bundle.json`` from the assets, or from git if it is tracked.""" - if assets is not None: - path = assets / "bundle.json" - if not path.is_file(): - raise PinError(f"no bundle.json in {assets}") - raw = path.read_bytes() - else: - found = blob_at(repo, tag_name, "attest/bundle.json") - if found is None: - raise PinError( - "attest/bundle.json is neither in --assets nor tracked at " - f"{tag_name}. The topic repo gitignores attest/* and publishes " - "it as a release asset; download the assets and pass --assets." - ) - raw = found - return json.loads(raw.decode("utf-8")), raw - - -def _check_predicates( - repo: Path, - tag: TagObject, - bundle_doc: dict, - bundle_bytes: bytes, - assets: Path | None, -) -> tuple[str, list[str]]: - """Decide ``digest_provenance``, and say what could not be checked. - - Three rungs, and only the first is a claim about anything outside the - artifact set: - - 1. the tag object names the digests -> compare against it. ``git_rooted``. - 2. the file is tracked at the tag -> compare against the blob. Also - ``git_rooted`` for that file. - 3. neither -> compare the asset's bytes against what the bundle says about - them, which establishes the set is internally consistent and nothing - more. ``self_attested_only``. - """ - findings: list[str] = [] - rooted = bool(tag.digests) - - if rooted: - claimed = tag.digests.get("attest/bundle.json") - if claimed is None: - raise PinError( - "the tag's digest block does not name attest/bundle.json. A " - "block that omits the bundle roots nothing: every other digest " - "in the set is read out of the bundle." - ) - actual = sha256_bytes(bundle_bytes) - if claimed != actual: - raise PinError( - f"attest/bundle.json hashes to {actual} and the tag object " - f"names {claimed}. The tag object is the root of trust; these " - f"assets are not the ones this tag was cut over." - ) - - for predicate in bundle_doc.get("predicates") or []: - name = predicate.get("file", "") - claimed = predicate.get("sha256", "") - data = _predicate_bytes(repo, tag, name, assets) - if data is None: - findings.append(f"{name}: not present in --assets or in git; unchecked") - rooted = False - continue - actual = sha256_bytes(data) - if actual != claimed: - raise PinError( - f"{name} hashes to {actual}; the bundle claims {claimed}." - ) - if tag.digests: - tagged = tag.digests.get(name) - if tagged is None: - findings.append( - f"{name}: the bundle's digest matches the file, but the " - f"tag's digest block does not name it" - ) - rooted = False - elif tagged != actual: - raise PinError( - f"{name} hashes to {actual}; the TAG OBJECT names " - f"{tagged}. The bundle agreeing with the file means only " - f"that both were changed together." - ) - elif blob_at(repo, tag.name, name) is None: - rooted = False - - if not rooted: - findings.append( - "no git-rooted digest covers the attest artifacts: the topic repo " - "gitignores attest/* (deliberately -- CI regenerates them and a " - "committed copy would be a stale trust record) and this tag's " - "message carries no MFC DIGESTS block. The set is internally " - "consistent, which a file copy also is. Add the block at the next " - "tag; this tool reads it." - ) - return (GIT_ROOTED if rooted else SELF_ATTESTED_ONLY), findings - - -def _predicate_bytes( - repo: Path, tag: TagObject, name: str, assets: Path | None -) -> bytes | None: - if assets is not None: - candidate = assets / Path(name).name - if candidate.is_file(): - return candidate.read_bytes() - return blob_at(repo, tag.name, name) - - -def _load_withdrawals(repo: Path, registry_doc: dict) -> tuple[dict | None, str | None]: - """``withdrawals.yaml`` from the NEWEST tag, not the pinned one. - - The single channel permitted to travel forward in time, and safe for - exactly one reason: a withdrawal can only remove trust, never grant it. - Reading it from the pinned tag would mean a v0.1.0 pin keeps serving a - record v0.2.0 marked inadequate, with nothing to say so. - """ - latest = newest_tag(repo) - if latest is None: - return None, None - raw = blob_at(repo, latest, "attest/withdrawals.yaml") - if raw is None: - raw = blob_at(repo, latest, "withdrawals.yaml") - if raw is None: - return None, latest - try: - import yaml - except ImportError as exc: # pragma: no cover - PyYAML is a dep of [contract] - raise PinError( - "withdrawals.yaml exists at the newest tag but PyYAML is not " - "installed, so the revocation channel cannot be read. Refusing to " - "pin: a pin that silently skips withdrawals is exactly the failure " - "the channel was added to prevent." - ) from exc - document = yaml.safe_load(raw.decode("utf-8")) or {} - mine = registry_doc.get("registry_id") - theirs = document.get("registry_id") - if mine and theirs and mine != theirs: - raise PinError( - f"the withdrawals at {latest} are for registry {theirs!r} and this " - f"registry is {mine!r}. Applying them would remove trust from keys " - f"they were never about." - ) - return document, latest - - -def _remote_url(repo: Path) -> str: - try: - return _git(repo, "config", "--get", "remote.origin.url").strip() - except PinError: - return str(repo) - - -def to_row(pin: Pin, *, pinned_at: str | None = None) -> dict[str, str | None]: - """The ``formal_releases`` row. Small artifacts inline, big ones by path.""" - return { - "slug": pin.slug, - "repo": pin.repo_url, - "tag": pin.tag.name, - "tag_object_sha": pin.tag.object_sha, - "commit_sha": pin.tag.commit_sha, - "registry_id": pin.registry_doc.get("registry_id", ""), - "registry_sha256": sha256_bytes(pin.registry_bytes), - "env_digest": pin.bundle_doc.get("env_digest", ""), - "digest_provenance": pin.digest_provenance, - "asset_dir": pin.asset_dir, - "bundle_json": json.dumps(pin.bundle_doc, sort_keys=True), - # Stored as the BYTES from git, decoded -- not a re-serialization. - # `registry_sha256` is computed over these bytes and the topic repo - # compares it against its own `shasum`, so a canonicalizing round-trip - # here would make the served record disagree with the pin. - "registry_json": pin.registry_bytes.decode("utf-8"), - "resolution_json": None, - "review_json": None, - "withdrawals_json": ( - json.dumps(pin.withdrawals_doc, sort_keys=True) - if pin.withdrawals_doc is not None else None - ), - "withdrawals_tag": pin.withdrawals_tag, - "pinned_at": pinned_at or datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"), - } - - -def write_pin(db_path: Path, row: dict[str, str | None]) -> None: - """Write the row through the store's own migration ladder. - - :func:`server.notebooks_store.open_sync`, never a raw connection: a writer - that leaves ``user_version`` at 0 arms the v0->v1 block's unconditional - ``DROP TABLE``, which is the hazard #174 names in `notebook_restore.py` - and which a second sync writer would have doubled. - """ - from server.notebooks_store import open_sync - - conn = open_sync(db_path) - try: - columns = ", ".join(row) - placeholders = ", ".join(f":{k}" for k in row) - conn.execute("BEGIN IMMEDIATE") - try: - conn.execute( - f"INSERT OR REPLACE INTO formal_releases ({columns}) " - f"VALUES ({placeholders})", - row, - ) - conn.execute("COMMIT") - except sqlite3.IntegrityError as exc: - conn.execute("ROLLBACK") - # `formal_releases.slug` references `notebooks(slug)`, so a pin - # for a notebook that does not exist is refused by the FK. Said - # plainly here: the raw message is "FOREIGN KEY constraint - # failed", which names neither the notebook nor the fix. - raise PinError( - f"no notebook {row['slug']!r} on this server, so there is " - f"nothing for this release to be served under. Create it " - f"first (make init NOTEBOOK={row['slug']}), then re-pin. " - f"({exc})" - ) from exc - except Exception: - conn.execute("ROLLBACK") - raise - finally: - conn.close() - - -def run( - *, - repo_path: Path, - tag: str, - notebook: str, - registry: str, - assets: Path | None, - db_path: Path | None, - dry_run: bool, -) -> int: - from server.operator_settings import DEFAULT_DB_PATH - - pin = verify( - repo_path, tag_name=tag, slug=notebook, - registry_path=registry, assets=assets, - ) - row = to_row(pin) - - for finding in pin.findings: - print(f" note: {finding}", file=sys.stderr) - print( - f"{pin.tag.name} -> commit {pin.tag.commit_sha[:12]} " - f"(tag object {pin.tag.object_sha[:12]}), registry " - f"{row['registry_sha256'][:12]}, {len(pin.registry_doc.get('entries') or {})} " - f"entries, digest_provenance={pin.digest_provenance}" - ) - if pin.digest_provenance == SELF_ATTESTED_ONLY: - print( - " digest_provenance is self_attested_only. That is NOT a pass " - "with a caveat: it means nothing outside the artifact set was " - "consulted for the attest digests, which is a state a file copy " - "also reaches. The served record carries it.", - file=sys.stderr, - ) - if dry_run: - print("dry run; nothing written") - return 0 - write_pin(db_path or DEFAULT_DB_PATH, row) - print(f"pinned into {db_path or DEFAULT_DB_PATH}") - return 0 - - -def _build_arg_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description=(__doc__ or "").splitlines()[0], - formatter_class=argparse.RawDescriptionHelpFormatter, - ) - parser.add_argument("--repo-path", type=Path, required=True, - help="local clone of the topic repo") - parser.add_argument("--tag", required=True, help="the release tag to pin") - parser.add_argument("--notebook", required=True, - help="the notebook slug this release is served under") - parser.add_argument("--registry", required=True, - help="repo-relative path to registry/.json") - parser.add_argument("--assets", type=Path, default=None, - help="directory of downloaded release assets " - "(attest/* is gitignored in the topic repo)") - parser.add_argument("--db", type=Path, default=None, - help="notebooks.db (default: var/arxmcp/cache/notebooks.db)") - parser.add_argument("--dry-run", action="store_true", - help="verify and report; write nothing") - return parser - - -def main(argv: list[str] | None = None) -> int: - args = _build_arg_parser().parse_args(argv) - try: - return run( - repo_path=args.repo_path, tag=args.tag, notebook=args.notebook, - registry=args.registry, assets=args.assets, db_path=args.db, - dry_run=args.dry_run, - ) - except StatementToolError as exc: - print(f"error: {exc}", file=sys.stderr) - return 1 - - -if __name__ == "__main__": # pragma: no cover - raise SystemExit(main()) diff --git a/tools/notebook_restore.py b/tools/notebook_restore.py index ac6f068..2884392 100644 --- a/tools/notebook_restore.py +++ b/tools/notebook_restore.py @@ -247,9 +247,6 @@ def _open_db_with_retry(db_path: Path) -> sqlite3.Connection: read-side half of this at its m2 critique F2 (a `list` command that migrated the operator's only copy); this is the write-side half. - Contract-v1's ``formal_releases`` migration is what made it urgent: a - second sync writer would have doubled the exposure. - The retry loop stays here because it is this CLI's concern -- the server opens once at startup and has nothing to race. """ From 2843c9eabce10d7e2b81d2bb2ba36c0494e9775d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 03:12:39 +0000 Subject: [PATCH 2/3] feat(tools): remove the statement CLIs and mfc contract Removed the offline statement tooling that existed for the cross-repo formal contract: - tools/statement_resolve.py, the resolver that checked whether a registry quote still appeared in the corpus; - tools/statement_mint.py, which prefilled candidate registry entries; - tools/_statement_common.py, their shared plumbing; - their tests; - the `contract` extra (mfc from math-formal-contract-lean, pinned to a commit), and .github/workflows/contract.yml, which ran only these tests. uv.lock loses only the mfc package and the extra. Kept: documents.arxiv_version and its backfill. They were built for the resolver's version guard, but the column is half the documents key and is hashed into the corpus manifest. Their comments now give that reason instead of citing the resolver. Refs #546. --- .github/workflows/contract.yml | 134 ---- pyproject.toml | 23 - tests/test_notebook_arxiv_version_backfill.py | 5 +- tests/test_statement_mint.py | 323 --------- tests/test_statement_resolve.py | 615 ------------------ tools/_statement_common.py | 298 --------- tools/notebook_arxiv_version_backfill.py | 17 +- tools/notebook_documents_backfill.py | 11 +- tools/statement_mint.py | 461 ------------- tools/statement_resolve.py | 583 ----------------- uv.lock | 16 +- 11 files changed, 14 insertions(+), 2472 deletions(-) delete mode 100644 .github/workflows/contract.yml delete mode 100644 tests/test_statement_mint.py delete mode 100644 tests/test_statement_resolve.py delete mode 100644 tools/_statement_common.py delete mode 100644 tools/statement_mint.py delete mode 100644 tools/statement_resolve.py diff --git a/.github/workflows/contract.yml b/.github/workflows/contract.yml deleted file mode 100644 index 5d43a82..0000000 --- a/.github/workflows/contract.yml +++ /dev/null @@ -1,134 +0,0 @@ -name: contract - -# This repository's first CI, and it is deliberately narrow. -# -# `CLAUDE.md` §4.1 is unchanged by it: the local `make test` is still the -# authority, nothing here blocks a merge, and there are no feature branches for -# it to gate. What this job adds is the one thing a local suite cannot give the -# repo on the other side of the seam — evidence that the statement CLIs behave -# the same on a machine that is not this workstation, with nothing installed -# but the three packages they actually need. -# -# So it does NOT run `make test`. That would pull torch (~1.5 GB of wheels), -# LanceDB, transformers and a BGE-M3 download to exercise four dicts, and a job -# that expensive gets disabled the first week it is slow. The whole point of -# `tools/statement_resolve.py`'s pure core is that the ladder is testable with -# no LanceDB, no Lean, no models and no network, and this job is what collects -# on that. -# -# Path-filtered on purpose. This box lands many commits a day on desktop, -# server and ingest work that cannot affect the contract surface, and a job -# that runs on all of them teaches everyone to ignore the check. Nothing here -# is a required status check, so the usual "filtered job never reports, PR -# blocks forever" trap does not apply. - -on: - push: - branches: [main] - paths: &contract_paths - - "tools/statement_resolve.py" - - "tools/statement_mint.py" - - "tools/_statement_common.py" - - "tests/test_statement_resolve.py" - - "tests/test_statement_mint.py" - - "pyproject.toml" - - ".github/workflows/contract.yml" - pull_request: - paths: *contract_paths - workflow_dispatch: - -permissions: - contents: read - -jobs: - statement-cli: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - # Three packages, named individually rather than through - # `pip install '.[contract]'`. The extra is the right declaration for an - # operator — it pulls arXMCP and therefore torch — and the wrong one for - # a job whose entire claim is that this code needs none of that. If a - # future edit makes the resolver import `server.*` at module scope, this - # step fails, which is the correct outcome and would be invisible under - # the extra. - # - # The rev is read out of pyproject.toml rather than repeated here, so - # there is one pin and it cannot go stale in a second place. - - name: install the contract package at the pinned rev - run: | - set -euo pipefail - REV=$(python - <<'PY' - import re, pathlib - text = pathlib.Path("pyproject.toml").read_text(encoding="utf-8") - m = re.search( - r'"mfc @ git\+https://github\.com/chris-dare-dev/' - r'math-formal-contract-lean@([0-9a-f]{40})#subdirectory=contract"', - text, - ) - if not m: - raise SystemExit( - "pyproject.toml carries no 40-hex mfc pin in the `contract` " - "extra; a branch or tag there would make this job's result " - "depend on when it ran" - ) - print(m.group(1)) - PY - ) - echo "pinned mfc rev: $REV" - python -m pip install --quiet pytest jsonschema \ - "mfc @ git+https://github.com/chris-dare-dev/math-formal-contract-lean@${REV}#subdirectory=contract" - - # An `importorskip` that silently skips reads exactly like a pass in a - # green run, and `tests/test_statement_resolve.py` opens with one. Assert - # the import works before pytest gets the chance to be lenient about it. - - name: the contract package is importable, so nothing skips - run: | - python - <<'PY' - import pathlib - - import mfc.digest - - schema = pathlib.Path(mfc.__file__).parent / "schema" / "resolution-1.0.schema.json" - assert schema.is_file(), f"mfc shipped no {schema.name}" - # The version guard's verdict has to be representable, or every - # assertion about it passes vacuously against an older pin. - text = schema.read_text(encoding="utf-8") - assert '"not_applicable"' in text, ( - "the pinned mfc predates `not_applicable` in resolution/1.0; " - "the version-guard tests would validate nothing" - ) - print(f"ok: mfc.digest at {mfc.__file__}") - PY - - - name: pytest — the statement CLIs - run: python -m pytest tests/test_statement_resolve.py -q - - # Collect-only over the whole suite would need every runtime dep. This - # asserts the narrower thing the job actually cares about: the modules - # under test import with nothing but the three packages above, so the - # "no LanceDB, no models" claim is measured rather than asserted. - - name: the tools import without the corpus stack - run: | - python - <<'PY' - import sys - - import tools.statement_resolve # noqa: F401 - - heavy = sorted( - m for m in ("torch", "lancedb", "transformers", "faiss", "fastapi") - if m in sys.modules - ) - if heavy: - raise SystemExit( - f"importing tools.statement_resolve pulled in {heavy}; the " - f"corpus stack must stay behind a function-level import or " - f"this job stops being cheap and starts being a lie" - ) - print("ok: no corpus stack at import time") - PY diff --git a/pyproject.toml b/pyproject.toml index 351b0ea..7498fdb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -325,29 +325,6 @@ dev = [ # dependency is obliged to bring it. "httpx>=0.27", ] -# contract — the statement CLIs on the ingest plane -# (``tools/statement_resolve.py``, ``tools/statement_mint.py``; derived-alg-geo-lean -# #169/#170). NOT a runtime dependency and deliberately not one: nothing under -# ``server/`` imports it, so the served process, the wheel and the data-plane -# boundary are all untouched. -# -# It is an EXTRA rather than a vendored copy because the one thing these CLIs -# must not do is answer "is this the same statement" differently from the repo -# that minted the digest. ``mfc.digest.norm_text`` (NFC, then whitespace-run -# collapse, in that order) is that answer; a second implementation here would -# drift on the first Unicode subtlety anybody hits, and the symptom of the -# drift is a citation silently re-pointed at a different theorem. ADR-0009 -# makes ``mfc`` a shared tool for exactly this reason -- the consuming repo -# installs it rather than vendoring schema copies with a checksum-drift test. -# -# Pinned to a commit, never a branch, matching the rule the Lean pins follow. -# The same rev ``derived-alg-geo-lean/lakefile.toml`` pins, so the schemas this -# side validates against are the schemas that side emits. Bump both together -# or not at all. -contract = [ - "mfc @ git+https://github.com/chris-dare-dev/math-formal-contract-lean@b5a63cbab0cc2625cdfeacadfa9cb4b64a419598#subdirectory=contract", - "jsonschema>=4.18", -] # textbook-ingest e2 — PDF parsing via MinerU 3.x is INTENTIONALLY NOT # in a project extra. MinerU's dep tree caps transformers at v4, which # would silently downgrade the BGE-M3 / BGE-reranker stack the project diff --git a/tests/test_notebook_arxiv_version_backfill.py b/tests/test_notebook_arxiv_version_backfill.py index 14c005c..cefd09c 100644 --- a/tests/test_notebook_arxiv_version_backfill.py +++ b/tests/test_notebook_arxiv_version_backfill.py @@ -1,8 +1,7 @@ """The version backfill, and the one thing it must never do: guess. -derived-alg-geo-lean **#171**. The column it fills is load-bearing across a -repo boundary — `statement_resolve.py` reads it to decide whether a `current` -verdict is honest — so the interesting assertions here are the ABSTENTIONS. +The column it fills is half the documents key and is hashed into the corpus +manifest, so the interesting assertions here are the ABSTENTIONS. A backfill that filled every row would satisfy a naive "did it run" test and would be the exact failure #171 was filed about, one layer down: a version number that nothing establishes. diff --git a/tests/test_statement_mint.py b/tests/test_statement_mint.py deleted file mode 100644 index d6b7290..0000000 --- a/tests/test_statement_mint.py +++ /dev/null @@ -1,323 +0,0 @@ -"""The mint prefill, and the four things it is forbidden to do. - -derived-alg-geo-lean **#169**. Most of what matters about this tool is what it -REFUSES: it does not mint identity (ADR-0002), it does not write to the topic -repo (ADR-0001), it does not break a tie between candidate chunks, and it does -not fill in a field a human owes. A prefill that did any of those would be more -convenient and would defeat the point of a hand-minted registry. - -The `printed_number` lookup is also asserted here as a lookup in its own right. -It is the reason this file lives in arXMCP rather than in `mfc` — the audit -found no path anywhere that fetches "the chunk numbered 8.2". - -No LanceDB and no network: the chunk list is injected. -""" - -from __future__ import annotations - -import json -from pathlib import Path - -import pytest - -from tools._statement_common import Chunk -from tools.statement_mint import ( - HUMAN_OWNED, - build_entry, - find_by_printed_number, - find_by_text, -) - -mfc_digest = pytest.importorskip("mfc.digest") - -PAPER = "math/0212237" -BODY_82 = ( - "Lemma 8.2. Suppose $\\|\\sigma_1-\\sigma_2\\|<1/8$. Then the induced map " - "on slicings is well-defined." -) -BODY_APPENDIX_82 = ( - "Lemma A.8.2 restated. The appendix reprints the bound of Lemma 8.2 in the " - "numbering of this section." -) - - -def _chunk(suffix: str, body: str, printed: str | None) -> Chunk: - return Chunk( - chunk_id=f"arxiv:{PAPER}:{suffix}", - paper_id=PAPER, - body_text=body, - printed_number=printed, - chunker_version="v1.1", - ) - - -def _corpus() -> list[Chunk]: - return [ - _chunk("1111111111111111", BODY_82, "8.2"), - _chunk("2222222222222222", BODY_APPENDIX_82, "8.2"), - _chunk("3333333333333333", "Proposition 8.1. A local homeomorphism.", "8.1"), - _chunk("4444444444444444", "An unnumbered remark.", None), - Chunk(chunk_id="arxiv:2101.04404:5555555555555555", - paper_id="2101.04404", body_text=BODY_82, printed_number="8.2"), - ] - - -# --- the lookup that did not exist --------------------------------------------- - -def test_printed_number_fetches_the_chunk_numbered_that() -> None: - """*Fetch the chunk numbered 8.1.* No tool in this repo accepted a - printed_number as an input before this one.""" - hits = find_by_printed_number(_corpus(), PAPER, "8.1") - assert [c.chunk_id for c in hits] == [f"arxiv:{PAPER}:3333333333333333"] - - -def test_printed_number_is_scoped_to_the_paper() -> None: - """Numbers are per-paper. A lookup that ignored `paper_id` would return - another paper's Lemma 8.2, and it looks exactly as plausible.""" - hits = find_by_printed_number(_corpus(), PAPER, "8.2") - assert all(c.paper_id == PAPER for c in hits) - assert len(hits) == 2 - - -def test_printed_number_returns_every_match_rather_than_the_first() -> None: - """It is not unique by construction — a body and an appendix can both - print 8.2, and a re-chunk can leave two chunks carrying it. Returning one - would be a coin flip wearing a lookup's clothes; the caller refuses on - more than one.""" - assert len(find_by_printed_number(_corpus(), PAPER, "8.2")) == 2 - - -def test_printed_number_matching_ignores_surrounding_whitespace() -> None: - chunks = [_chunk("6666666666666666", "text", " 8.2 ")] - assert find_by_printed_number(chunks, PAPER, "8.2") - - -@pytest.mark.parametrize("locator", ["", " "]) -def test_an_empty_locator_matches_nothing_rather_than_everything( - locator: str, -) -> None: - """`(c.printed_number or "") == ""` matches every chunk the chunker could - not number — which on the textbook and MinerU paths is ALL of them. - - An empty locator selecting the whole notebook is the worst possible answer - to it, and it looks like a working lookup right up until someone mints - from the first result. - """ - assert find_by_printed_number(_corpus(), PAPER, locator) == [] - - -# --- the search, which lists ---------------------------------------------------- - -def test_search_is_whitespace_and_nfc_insensitive() -> None: - """Same normalization as the digest, so a line-wrap difference between - what an operator pastes and what the chunker stored is not a miss.""" - hits = find_by_text( - _corpus(), PAPER, "induced map\non slicings", mfc_digest.norm_text - ) - assert [c.chunk_id for c in hits] == [f"arxiv:{PAPER}:1111111111111111"] - - -def test_an_empty_search_matches_nothing_rather_than_everything() -> None: - """The empty string is contained in every body. Returning the whole paper - is the least useful possible answer to an empty query, and looks like a - working search.""" - assert find_by_text(_corpus(), PAPER, " ", mfc_digest.norm_text) == [] - - -def test_search_is_scoped_to_the_paper() -> None: - hits = find_by_text(_corpus(), PAPER, "well-defined", mfc_digest.norm_text) - assert all(c.paper_id == PAPER for c in hits) - - -# --- the fragment --------------------------------------------------------------- - -def _entry(**kw): - defaults = dict( - scheme="arxiv", work_id=PAPER, source_version="v3", - notebook="bridgeland-stability", corpus_version=5048, - corpus_manifest_content_hash="1" * 64, - quote_sha256=mfc_digest.quote_sha256, - minted_at="2026-09-03", observed_at="2026-09-03T12:00:00Z", - ) - defaults.update(kw) - return build_entry(_corpus()[0], **defaults) - - -def test_the_quote_is_the_chunk_body_byte_for_byte() -> None: - """Not normalized, not cleaned. `quote` is the MACHINE-owned field and - `mint_resolution.matched_by: quote_sha256` requires byte-equality with the - chunk; anything tidied here demotes the entry to printed_number forever. - A human's corrections belong in `quote_as_read`.""" - assert _entry()["quote"] == BODY_82 - - -def test_the_digest_is_the_function_the_resolver_will_compare_against() -> None: - """Two implementations of one comparison is the failure mode the whole - contract exists to prevent, so this asserts the identity rather than a - recomputed constant.""" - assert _entry()["quote_sha256"] == mfc_digest.quote_sha256(BODY_82) - assert _entry()["quote_norm"] == mfc_digest.TEXT_NORM_ID - - -@pytest.mark.parametrize("field", ["kind", "title", "informal", "minted_by"]) -def test_every_human_owned_field_is_null(field: str) -> None: - """`null`, never `"TODO: …"`. - - A placeholder STRING validates against `registry/1.0` — `title` asks only - for a non-empty string — so a fragment pasted and forgotten would pass - `mfc registry validate` and carry the word TODO into a published record. - `null` fails at the first gate the topic repo runs, which is the entire - reason this output is deliberately invalid. - """ - assert _entry()[field] is None - - -def test_the_checklist_names_every_field_left_null() -> None: - """A null with no explanation is a bug report from the tool to the user.""" - entry = _entry() - named = {item.split(" ")[0] for item in HUMAN_OWNED} - assert named == {k for k, v in entry.items() if v is None} - { - "supersedes", "superseded_by", "mint_unresolved_reason", - } - - -def test_mint_resolution_records_the_rung_it_actually_is() -> None: - """`quote` IS this chunk's body, so `quote_sha256` matches by - construction. Recorded rather than left null so the resolver's rung 1 has - a hint to try first — and the resolver still recomputes before accepting - it, which is what makes a stale hint harmless.""" - resolution = _entry()["mint_resolution"] - assert resolution["matched_by"] == "quote_sha256" - assert resolution["chunk_id"] == f"arxiv:{PAPER}:1111111111111111" - assert resolution["notebook"] == "bridgeland-stability" - assert resolution["corpus_version"] == 5048 - assert _entry()["mint_unresolved_reason"] is None - - -def test_no_manifest_hash_means_no_mint_resolution_and_a_stated_reason() -> None: - """An adopter with no arXMCP running still mints — the schema makes - `mint_resolution` nullable *with a reason* for exactly that case. - - What it must never do is stamp a resolution carrying a manifest hash - nobody computed: the topic repo's F-02 freshness rule compares that field - to decide whether the corpus has moved, and a fabricated value reads as - "it has not". - """ - entry = _entry(corpus_manifest_content_hash="") - assert entry["mint_resolution"] is None - assert "no mint-time resolution" in entry["mint_unresolved_reason"] - - -def test_the_printed_number_rides_as_a_typed_field_not_in_a_key() -> None: - """ADR-0002: the paper coordinate is typed fields, never key segments. - Three of the four candidate designs packed it into the key and survived - `math/0212237` only by luck.""" - source = _entry()["source"] - assert source == { - "scheme": "arxiv", "id": PAPER, "version": "v3", - "printed_number": "8.2", "locator": None, - } - - -def test_a_textbook_source_carries_no_version() -> None: - """The registry schema makes a version on a textbook source a category - error — there is no version axis to pin.""" - entry = build_entry( - Chunk(chunk_id="textbook:huybrechts-fm:0f0f0f0f0f0f0f0f", - paper_id="textbook:huybrechts-fm", body_text=BODY_82), - scheme="textbook", work_id="huybrechts-fm", source_version=None, - notebook="huybrechts", corpus_version=1, - corpus_manifest_content_hash="1" * 64, - quote_sha256=mfc_digest.quote_sha256, - ) - assert entry["source"]["version"] is None - assert entry["source"]["scheme"] == "textbook" - - -def test_an_unknown_arxiv_version_stays_null_rather_than_becoming_latest() -> None: - """`documents.arxiv_version` is `''` for every row today. Filling `v1`, or - today's latest, would be the fabrication #171 is about — and the schema - REQUIRES a version on an arXiv source, so a null here is a hard stop - rather than a soft omission.""" - assert _entry(source_version=None)["source"]["version"] is None - - -def _schema() -> dict: - import mfc - - return json.loads( - (Path(mfc.__file__).resolve().parent / "schema" - / "registry-1.0.schema.json").read_text(encoding="utf-8") - ) - - -def _document(entry: dict) -> dict: - """A whole `registry/1.0` file around one entry. - - The entry subschema is validated in context rather than on its own: its - `source` / `mintResolution` / `citationKey` members are `$ref`s into the - file's `$defs`, and pulling the subschema out leaves them pointing at - nothing. - """ - return { - "schema_version": "registry/1.0", - "registry_id": "a520a8d4f877", - "notebook_hint": "bridgeland-stability", - "entries": {"stmt:a520a8d4f877:bridgeland2007.lem-8.2": entry}, - } - - -def test_the_fragment_carries_exactly_the_registry_entry_keys() -> None: - """`additionalProperties: false`. A key this tool invents is rejected by - the topic repo, and the operator has no way to know which one.""" - schema = _schema() - allowed = set(schema["$defs"]["entry"]["properties"]) - required = set(schema["$defs"]["entry"]["required"]) - produced = set(_entry()) - assert produced <= allowed, f"invented key(s): {sorted(produced - allowed)}" - assert required <= produced, f"missing required: {sorted(required - produced)}" - - -def test_filling_the_human_fields_makes_the_fragment_valid() -> None: - """The deliberate invalidity must be EXACTLY the human's four fields. - - Without this, a structural mistake anywhere else in the fragment would - hide behind "it is supposed to fail validation" and only surface when - someone had already filled the prose in by hand. - """ - jsonschema = pytest.importorskip("jsonschema") - validator = jsonschema.Draft202012Validator(_schema()) - - entry = _entry() - errors = list(validator.iter_errors(_document(entry))) - assert errors, "the fragment must NOT validate before a human fills it in" - #: And it must fail for the RIGHT reason. Without this the test passes on - #: any malformed fragment, which is the failure it exists to catch. - assert {tuple(e.path)[-1] for e in errors} == { - "kind", "title", "informal", "minted_by"} - - entry.update(kind="lemma", title="A bound on the slicing map", - informal="Nearby stability conditions induce a well-defined " - "map on slicings.", minted_by="Chris Dare") - errors = sorted(validator.iter_errors(_document(entry)), - key=lambda e: list(e.path)) - assert not errors, f"{errors[0].json_path}: {errors[0].message}" - - -def test_a_filled_fragment_passes_the_registry_rules_end_to_end() -> None: - """Schema-valid is not rule-valid. `mfc registry validate` runs R-01..R-13 - over the whole file, and R-02 (`quote_sha256` recomputes from the inline - quote) is the one this tool could plausibly get wrong.""" - pytest.importorskip("jsonschema") - from mfc.rules_registry import check as registry_check - - entry = _entry() - entry.update(kind="lemma", title="A bound on the slicing map", - informal="Nearby stability conditions induce a map.", - minted_by="Chris Dare") - results = registry_check(_document(entry)) - failed = [r for r in results if r.status.name == "FAIL"] - assert not failed, [(r.rule, r.findings) for r in failed] - #: R-02 is the rule this tool could plausibly break, so assert it ran - #: rather than trusting an empty failure list over a vacuous sweep. - assert any(r.rule == "R-02" and r.status.name == "PASS" for r in results) diff --git a/tests/test_statement_resolve.py b/tests/test_statement_resolve.py deleted file mode 100644 index de0085b..0000000 --- a/tests/test_statement_resolve.py +++ /dev/null @@ -1,615 +0,0 @@ -"""The single test that proves the identifier scheme works. - -derived-alg-geo-lean **#170**. The claim under test is the one the whole -contract rests on: a citation key minted by hand in a topic repo keeps -addressing the same statement after the corpus is re-ingested and every -``chunk_id`` rotates. If that is false, ``registry/.json`` is a set of -dangling pointers with a schema. - -So this file does not check that the resolver runs. It rotates the corpus and -checks that identity survived the rotation — and, just as importantly, that a -statement genuinely REMOVED from the corpus comes back ``unresolvable`` rather -than pointed at the nearest surviving chunk. A resolver that reported -``current`` for everything would pass a "does it resolve" test and be worse -than useless. - -Per #151 the rotation is not a whitespace mutation. ``nfc-ws-collapse/1`` -absorbs whitespace by construction, so a test built on it proves the -normalization works and says nothing about the ladder. The rotation here -**merges** two chunks into one and **splits** a third, which is what a real -chunker bump does and what the ``quote_containment`` rung was added for. - -Deliberately cheap: no LanceDB, no Lean, no models, no network. The fixture is -four dicts. That is what lets it be this repo's first CI job. -""" - -from __future__ import annotations - -import copy -import json -from pathlib import Path - -import pytest - -from tools._statement_common import ( - Chunk, - corpus_paper_id, - read_document_versions, -) -from tools.statement_resolve import RESOLVER_VERSION, resolve - -mfc_digest = pytest.importorskip( - "mfc.digest", - reason=( - "the contract package is not installed; `pip install -e '.[contract]'`. " - "It is not vendored on purpose — see tools/_statement_common.py" - ), -) - -PAPER = "math/0212237" -REGISTRY_ID = "a520a8d4f877" - -#: The statement text of Definition 1.1, standing alone as one chunk. -DEF_11 = ( - "Definition 1.1. A stability condition $(Z,\\mathcal{P})$ on a " - "triangulated category $\\mathcal{D}$ consists of a group homomorphism " - "$Z\\colon K(\\mathcal{D})\\to\\mathbb{C}$ called the central charge, and " - "full additive subcategories $\\mathcal{P}(\\phi)$." -) - -#: Lemma 8.2, standing alone. Merged with the chunk after it in the rotation. -LEM_82 = ( - "Lemma 8.2. Let $\\sigma=(Z,\\mathcal{P})$ be a stability condition and " - "suppose $\\|\\sigma_1-\\sigma_2\\|<1/8$. Then the map on slicings is " - "well-defined." -) - -#: The chunk that FOLLOWS Lemma 8.2 and gets merged into it. -LEM_82_NEXT = ( - "The proof proceeds by induction on the length of the Harder-Narasimhan " - "filtration, using axiom (d) of Definition 1.1." -) - -#: Proposition 8.1's STATEMENT. The mint took the statement; the chunk it came -#: from carried statement + proof, so this entry resolves by containment even -#: before any rotation. The rotation then splits that chunk in two. -PROP_81_STMT = ( - "Proposition 8.1. The map $\\mathcal{Z}\\colon\\operatorname{Stab}" - "(\\mathcal{D})\\to\\operatorname{Hom}(K(\\mathcal{D}),\\mathbb{C})$ is a " - "local homeomorphism." -) -PROP_81_PROOF = ( - "Proof. Fix a stability condition and apply Lemma 8.2 to the pair of " - "slicings obtained from the deformation. $\\square$" -) - -#: An obligation whose text is in no chunk, before or after the rotation. The -#: control: whatever the ladder does to the other three, this one must come -#: back unresolvable. -REMOVED = ( - "Lemma 9.9. Every stability condition on a K3 surface is induced by a " - "Bridgeland pair, which no version of this paper ever claimed." -) - - -def _entry( - *, - quote: str, - kind: str = "lemma", - printed_number: str | None = None, - version: str | None = "v3", - scheme: str = "arxiv", - ident: str = PAPER, - mint_chunk_id: str | None = None, -) -> dict: - return { - "kind": kind, - "title": "fixture entry", - "informal": "fixture", - "source": { - "scheme": scheme, - "id": ident, - "version": version, - "printed_number": printed_number, - "locator": None, - }, - "quote_mode": "verbatim", - "quote": quote, - "quote_norm": "nfc-ws-collapse/1", - "quote_sha256": mfc_digest.quote_sha256(quote), - "mint_resolution": ( - None if mint_chunk_id is None else { - "notebook": "bridgeland-stability", - "chunk_id": mint_chunk_id, - "matched_by": "quote_sha256", - "corpus_manifest_content_hash": "1" * 64, - "observed_at": "2026-08-05T09:00:00Z", - } - ), - "depends_on": [], - "frontier": [], - "minted_at": "2026-08-05", - "minted_by": "fixture", - "supersedes": None, - "superseded_by": None, - "mint_unresolved_reason": None if mint_chunk_id else "no resolver yet", - } - - -def _key(label: str) -> str: - return f"stmt:{REGISTRY_ID}:bridgeland2007.{label}" - - -K_DEF = _key("def-1.1") -K_LEM = _key("lem-8.2") -K_PROP = _key("prop-8.1") -K_GONE = _key("obl-removed") - - -def _registry() -> dict: - return { - "schema_version": "registry/1.0", - "registry_id": REGISTRY_ID, - "notebook_hint": "bridgeland-stability", - "entries": { - K_DEF: _entry(quote=DEF_11, kind="definition", printed_number="1.1", - mint_chunk_id=f"arxiv:{PAPER}:aaaaaaaaaaaaaaaa"), - K_LEM: _entry(quote=LEM_82, printed_number="8.2", - mint_chunk_id=f"arxiv:{PAPER}:bbbbbbbbbbbbbbbb"), - K_PROP: _entry(quote=PROP_81_STMT, kind="proposition", - printed_number="8.1"), - K_GONE: _entry(quote=REMOVED, kind="obligation", printed_number=None), - }, - } - - -def _chunk(suffix: str, body: str, printed: str | None = None) -> Chunk: - return Chunk( - chunk_id=f"arxiv:{PAPER}:{suffix}", - paper_id=PAPER, - body_text=body, - printed_number=printed, - kind="theorem", - chunker_version="v1.1", - ) - - -def _corpus_as_minted() -> list[Chunk]: - """Four chunks, with the ids the registry's mint_resolutions name.""" - return [ - _chunk("aaaaaaaaaaaaaaaa", DEF_11, "1.1"), - _chunk("bbbbbbbbbbbbbbbb", LEM_82, "8.2"), - _chunk("cccccccccccccccc", LEM_82_NEXT, None), - _chunk("dddddddddddddddd", f"{PROP_81_STMT}\n\n{PROP_81_PROOF}", "8.1"), - ] - - -def _corpus_rotated() -> list[Chunk]: - """The same paper after a chunker bump. Every id is different. - - Three distinct mutations, none of them cosmetic: - - * ``A`` keeps its body and loses its id — the plain rotation. - * ``B`` and ``C`` are MERGED. Lemma 8.2's quote is no longer any chunk's - whole body, so byte-equality is gone and only containment can find it. - * ``D`` is SPLIT at the statement/proof boundary. Proposition 8.1's quote - resolved by containment before the rotation and by byte-equality after - it, which is the direction a split moves the evidence. - """ - return [ - _chunk("1111111111111111", DEF_11, "1.1"), - _chunk("2222222222222222", f"{LEM_82}\n\n{LEM_82_NEXT}", "8.2"), - _chunk("3333333333333333", PROP_81_STMT, "8.1"), - _chunk("4444444444444444", PROP_81_PROOF, None), - ] - - -def _resolve(chunks, *, versions=None, registry=None) -> dict: - return resolve( - registry or _registry(), - chunks, - notebook="bridgeland-stability", - registry_sha256="e" * 64, - corpus_version=5048, - corpus_manifest_content_hash="1" * 64, - chunker_version="v1.1", - document_versions={PAPER: "v3"} if versions is None else versions, - generated_at="2026-09-03T12:00:00Z", - norm_text=mfc_digest.norm_text, - ) - - -def _by_key(document: dict) -> dict[str, dict]: - return {r["key"]: r for r in document["results"]} - - -# --- the rotation, which is the whole point ---------------------------------- - -def test_every_entry_resolves_before_the_rotation() -> None: - """The baseline. Without it a green rotation test proves nothing. - - Note `prop-8.1` is already on the containment rung here: the mint took - Proposition 8.1's statement and the chunk it sat in carried the proof too. - That is the ordinary case, not a degraded one. - """ - rows = _by_key(_resolve(_corpus_as_minted())) - assert rows[K_DEF]["resolution"] == "current" - assert rows[K_DEF]["matched_by"] == "quote_sha256" - assert rows[K_LEM]["resolution"] == "current" - assert rows[K_LEM]["matched_by"] == "quote_sha256" - assert rows[K_PROP]["resolution"] == "current" - assert rows[K_PROP]["matched_by"] == "quote_containment" - assert rows[K_GONE]["resolution"] == "unresolvable" - - -def test_identity_survives_a_rotation_of_every_chunk_id() -> None: - """No chunk_id in the rotated corpus appears in the registry, and every - minted statement still resolves ``current``. - - This is the claim `stmt:<12hex>: