Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

docs/spec: close Go verifier findings on Anchor Format §1 escaping rules, verifier-compatibility README, and Acta crosswalk (#448 items 3, 16, 19)

Open
  • Is something wrong?
#536 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@drk-ram is already working on this.

Since Oct 15, 2026.

  • #537 by @drk-ram — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
20/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start with the three named documents: spec/registry-anchor-v1.md §1 (lines 54-65), examples/verifier-compatibility/README.md, and the two 3.3.2 references in docs/crosswalks/acta-decision-receipts.md, checked against spec/trace-v0.2.md §3.3. Any code changes touch src/agentrust_trace/sign.py:anchor_bytes and conformance/src/trace_tests/inclusion.py:canonical_claim_bytes, which need unit tests. Linked PR #537 is already open, so coordinate with it before starting. Done means the five escaping rules are stated and the stale text is corrected.

Written by the indexing model from the issue text.

Description

What is wrong

Checked on main at commit 6fb2570254023ee78d9bdc9f6c2c696ad7a9862c:

Three verified findings from the independent Go verifier report (#448 items 3, 16, and 19) remain open across spec/registry-anchor-v1.md, examples/verifier-compatibility/README.md, and docs/crosswalks/acta-decision-receipts.md:

  1. #448 Item 19 — spec/registry-anchor-v1.md §1 defines canonical_claim_bytes via a Python json.dumps call rather than stating the five language-independent serialization rules.
    In spec/registry-anchor-v1.md:54-65:

    • The four prose bullets state: sorted object keys by Unicode code point, "," and ":" separators, non-ASCII characters escaped (ensure_ascii) as ASCII bytes, and no trailing newline, followed by json.dumps(claim, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("ascii").
    • Five byte-affecting rules that Python's json.dumps(..., ensure_ascii=True) performs are left unstated in the prose rules:
      1. Mandatory two-character short escapes (\", \\, \b, \f, \n, \r, \t) for U+0022, U+005C, U+0008, U+000C, U+000A, U+000D, U+0009, with / (U+002F) unescaped.
      2. Lowercase four-hex-digit \uXXXX escapes for all other control characters (U+0000 to U+001F) and all BMP characters above U+007F (noting that U+007F DELETE is emitted literally as byte 0x7F by ensure_ascii=True while U+0080 and above are escaped).
      3. Characters above the Basic Multilingual Plane (U+10000 to U+10FFFF) encoded as lowercase UTF-16 surrogate pairs \ud8xx\udcxx.
      4. Lone UTF-16 surrogates (U+D800 to U+DFFF) rejected as outside the profile.
      5. Negative zero (-0) serialized as 0.
        Without these rules stated in §1, a non-Python implementation (Go, Rust, TypeScript) following the four prose bullets can emit \u000a instead of \n, uppercase \u00E9 instead of \u00e9, or escape / as \/, producing a different leaf hash for the same claim.

  2. #448 Item 3 — examples/verifier-compatibility/README.md still states that no normative text has been accepted and that docs/verification.md says nothing about version skew.
    examples/verifier-compatibility/README.md:3-11 says:

    **No normative text for them has been accepted.** Do not read a passing vector here as a conformance requirement.
    Nothing in docs/verification.md currently says what a verifier must do about version skew
    However, spec/trace-v0.2.md §3.3 and docs/verification.md ("Step 4: Check the EAT profile", lines 26-34) now normatively require a nonempty accepted_profiles set and require the verification result to record both profile and accepted_profiles (Obligations 2 and 3 of #116), while only Obligations 1 (emitter version declarations) and 4 (downgrade disclosure) remain deferred.

  3. #448 Item 16 — docs/crosswalks/acta-decision-receipts.md cites section 3.3.2 (the v0.1 section number) in two places where v0.2 section 3.3.3 is meant.
    In docs/crosswalks/acta-decision-receipts.md:

    • Line 25: The verification pattern in 3.3.2 is deliberately domain-agnostic
    • Line 61: Serves exactly the external-evidence-by-digest role 3.3.2 describes.
      In spec/trace-v0.2.md, action receipts is section 3.3.3 (3.3.2 was the section number in spec/trace-v0.1.md, and the rest of acta-decision-receipts.md already cites 3.3.3).

Spec section or file

  • spec/registry-anchor-v1.md §1
  • examples/verifier-compatibility/README.md
  • docs/crosswalks/acta-decision-receipts.md
  • Related: #448 (items 3, 16, 19)

Expected behavior

  • State the exact string-escaping, surrogate-pair, lone-surrogate exclusion, and -0 rules in spec/registry-anchor-v1.md §1 (and enforce lone-surrogate rejection in src/agentrust_trace/sign.py:anchor_bytes and conformance/src/trace_tests/inclusion.py:canonical_claim_bytes if needed, with unit tests pinning all five rules).
  • Update examples/verifier-compatibility/README.md to reflect that Obligations 2 and 3 of #116 are now in spec/trace-v0.2.md §3.3 and docs/verification.md, while Obligations 1 and 4 remain deferred.
  • Update the two stale 3.3.2 references in docs/crosswalks/acta-decision-receipts.md to 3.3.3.

Impact

Non-Python implementations of registry-anchor-v1 §1 can compute different anchor leaf digests on control characters, non-ASCII strings, or non-BMP characters, and readers of examples/verifier-compatibility/README.md and docs/crosswalks/acta-decision-receipts.md meet outdated normative status and section numbers.

Contributor: Raghuvar Durga (@drk-ram)

Dominant language
Python
Stars
37
Forks
33
Avg merge
1d 4h
Merged PRs (30d)
120

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from agentrust-io/trace-spec

All issues in agentrust-io/trace-spec

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.