Skip to content

feat: export CitationCheck and check_citations from the package root - #437

Merged
imran-siddique merged 1 commit into
agentrust-io:mainfrom
opento-suggestions:feat/export-citation
Sep 30, 2026
Merged

imran-siddique merged 1 commit into
agentrust-io:mainfrom
opento-suggestions:feat/export-citation

Conversation

@opento-suggestions

@opento-suggestions opento-suggestions commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

verify_record() returns one VerificationResult carrying both a RevocationCheck and a mapping of CitationCheck, so to a caller reading a result the two are the same kind of thing. They were not reachable the same way: agentrust_trace.RevocationCheck resolves and agentrust_trace.CitationCheck raises AttributeError, leaving the citation half to be reached by module path.

CitationCheck and check_citations now join RevocationCheck and check_bundle in __all__. That list is grouped by the module each name is imported from, and the citation pair joins the group the revocation pair already forms. Nothing else moves. agentrust_trace.citation was already reachable as a module, because revocation.py imports CitationCheck at module level, so no import behaviour changes and no signature, outcome, default or error is touched; the same objects stay reachable by their old module paths.

check_citations is exported for the reason check_bundle is. Neither is called anywhere outside its own module, sign.verify_record and the tests, so neither earns its place at the root by call count; both are the documented entry point of the module whose result type sits beside it, and exporting one type without its entry point splits a surface a caller uses together. SURFACES is deliberately not exported: agentrust_trace.citation.SURFACES is the path the VerificationResult.citations docstring already names, and a bare SURFACES at the package root would say less than the qualified name does.

The test asserts the two revocation names beside the two citation ones rather than pinning the citation half alone, so it fails if either side moves. Run against the tree with the export removed it reports CitationCheck is not in __all__. Mutants over __all__ and the import block are each caught, including one that binds the exported name to RevocationCheck, so a name that resolves to the wrong object fails rather than passing.

Stated limitations. This adds two existing public names to a namespace; it changes no behaviour and adds no argument, so there is no type-confusion surface to test. It is not quite a no-op for every caller: from agentrust_trace import * now binds two more names and could shadow a caller's own CitationCheck. No documentation page states the import path this corrects, so none is updated; docs/verification.md explains the citations result and names no type, which this change does not alter.

On the two numbers in this description: #190 is the tracking issue for the citation work and is what the CHANGELOG.md entry for that change cites. #374 is the pull request that added citations, and its description is where the export was named as a small follow-up kept out of that diff. This is that follow-up.

One collision to flag: #438, which corrects the digest algorithms named on docs/schema.md, adds its own CHANGELOG.md bullet at the same anchor in ## [Unreleased]. A trial merge conflicts in CHANGELOG.md and in no other file, so whichever of the two lands second rebases one bullet. The branches are cut from the same commit and share no other path.

Verification was run on Windows 10 with Python 3.13.5 (CI's 3.11 and 3.12 were not run), against 63f4d15: 5 failed, 2390 passed, 6 skipped at the untouched commit, and 5 failed, 2391 passed, 6 skipped after, the same five red in both. They are the known Windows generator failures, which reproduce on the untouched tree and come from write_text giving CRLF where the fixture comparison is byte-for-byte:

tests/test_generators_reproduce_fixtures.py::test_generator_reproduces_its_committed_fixtures[conformance]
tests/test_generators_reproduce_fixtures.py::test_generator_reproduces_its_committed_fixtures[gap-disclosure]
tests/test_generators_reproduce_fixtures.py::test_generator_reproduces_its_committed_fixtures[canonicalization-boundary]
tests/test_generators_reproduce_fixtures.py::test_generator_reproduces_its_committed_fixtures[delegation-link]
tests/test_generators_reproduce_fixtures.py::test_generator_reproduces_its_committed_fixtures[verifier-compatibility]

ruff check src tests scripts passes at 0.16.9, which is the pin in requirements/dev.txt; mypy src/agentrust_trace is clean under strict; tools/check_dashes.py is clean. No Linux run is claimed.

Refs #190.

Type of change

  • Editorial (typo, link fix, clarification: no normative effect)
  • Non-breaking spec change (new optional field, new platform profile, informative addition)
  • Breaking spec change (requires 14-day comment period and Project Lead sign-off)
  • Schema change
  • Example addition

No box fits and I would rather say so than tick the nearest. This is a change to the reference implementation's export list: two names already public by module path are added to __all__. Nothing in the specification, the schema or the wire format is touched, so the three spec boxes would each overstate it, and it adds no example.

Spec section

None. The types themselves are unchanged. RevocationCheck carries the outcomes section 3.2.3 requires a verifier to be able to report; CitationCheck answers no reporting duty in the specification, since section 3.1.2's rules on cited objects are prohibitions on a verifier rather than requirements to report, and the citation outcome names are not accepted normative text. This PR changes where both are importable from and nothing about either.

Checklist

  • DCO sign-off on all commits (git commit -s)
  • CHANGELOG.md updated (for any normative change): updated, though there is no normative change
  • Breaking changes marked with <!-- CHANGED: #NNN: description --> in spec text: no spec text changes
  • Backward compatibility statement included (for breaking changes): not a breaking change; no existing import stops working, and the import * note above is the compatibility statement for the package

Tool-assisted: the build, the witness rounds and this description. I answer for all of it.

verify_record() returns one VerificationResult carrying both a
RevocationCheck and a mapping of CitationCheck, so the two are the same
kind of thing to a caller reading a result. They were not reachable the
same way: agentrust_trace.RevocationCheck resolved and
agentrust_trace.CitationCheck raised AttributeError, leaving the
citation half to be reached by module path. The description of the
change that added citations said the export was a follow-up kept out of
that diff; this is it.

The two names sit beside their revocation counterparts in __all__,
classes before functions, as the rest of the list is ordered. Nothing
else changes. agentrust_trace.citation was already reachable, because
revocation.py imports CitationCheck at module level, so no import
behaviour moves and no signature, outcome or default is touched.

The test asserts the revocation names beside the citation ones rather
than the citation half alone, so it fails if either side moves. Run
against the tree with the export removed it reports CitationCheck is
not in __all__, and five mutants over __all__ and the import block,
including one that binds the exported name to RevocationCheck, are each
caught.

Refs agentrust-io#190.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: opento-suggestions <opentosuggestionsofficial@gmail.com>
@imran-siddique
imran-siddique merged commit 6e398e7 into agentrust-io:main Sep 30, 2026
8 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants