spec(numbers): decide integer-valued members by value, with Python and JavaScript tests (#247)

[chernistry]

What this changes

JSON has one number type. 1785000000, 1785000000.0 and 1.785e9 are three
spellings of one value, and RFC 8785 writes all three as 1785000000, so a Trust
Record carrying any of them has one pre-image and one signature. Section 3.2.2 does
not say whether a member typed integer holds an integer when it is written the
second or the third way. This proposal adds a paragraph that says it does: whether a
number is an integer, and whether it is inside the safe-integer range, is decided by
its value and not by its spelling.

This is a proposal, not a merge request for accepted text. Opened per the ruling on
#247 that a whole number within the existing limits counts as an integer, including
decimal and exponent spellings, brought as its own proposal with Python and
JavaScript tests and boundary cases.

What's open today

• The schemas already decide by value. jsonschema follows JSON Schema 2020-12,
  whose integer matches any number with a zero fractional part (Validation §6.1.1),
  so a record with "iat": 1785000000.0 passes schema/trace-claim.json as it stands.
  No schema file changes in this PR.
• The reference's verify_record does not. Its freshness check tested
  isinstance(iat, int), and json.loads returns a float for the fraction and
  exponent spellings, so a correctly signed record that had just passed the schema was
  rejected with record has no valid integer 'iat' for freshness check. The bridge's
  authorized_at, expires_at and transcript.after.observed_at checks carried the
  same type test.
• A JavaScript verifier cannot tell the spellings apart at all. JSON.parse
  returns one number for all three.

So two implementations reading the same signed bytes can reach different verdicts
today, and the difference has nothing to do with the signature.

The rule

Added to section 3.2.2 after "What the rule covers", marked
<!-- CHANGED: #247 - integer-valued members are decided by value, not by spelling -->:

What counts as an integer. JSON has one kind of number. RFC 8259 §6 gives it a
single grammar in which a fraction and an exponent are optional parts, so
1785000000, 1785000000.0 and 1.785e9 are three ways of writing one value.
Whether a number is an integer, for a member typed integer and for the range above,
is decided by that value and not by how it is written: 1785000000.0 and 1.785e9
are the integer 1785000000, 1785000000.5 is not an integer, and 1e21 is an integer
outside the range. The value is the IEEE 754 double the number parses to, which is
what RFC 8785 serializes and so what a signature covers; a spelling with more digits
than a double carries, such as 1785000000.0000000001, is the integer 1785000000. A
verifier MUST make both decisions on that value. JSON Schema 2020-12, in which the
schemas of this specification are written, defines integer the same way
(Validation §6.1.1: any number with a zero fractional part). RFC 8785 writes the value
and not the text it was read from, so the three spellings above have one pre-image
and one signature, and the spelling is not something a signature can vouch for. A
verifier whose parser returns only the value, as JSON.parse does, has no spelling to
decide by; a verifier that decided by spelling would reject records that such a
verifier accepts, over the same signed bytes.

One MUST. The sentence pinning the value to the double is there for one edge: a
spelling with more precision than a double holds. An implementation that parsed to
arbitrary precision would call 1785000000.0000000001 a fraction, while every
implementation that parses to a double, which includes every JavaScript verifier,
calls it the integer 1785000000, and the signature covers that integer. The double is
the one reading every implementation can follow.

What this change does

• Spec (spec/trace-v0.2.md, section 3.2.2): the paragraph above.
• Reference (src/agentrust_trace/sign.py): _integer_value decides a member by
  value, refuses bool explicitly, and says which rule failed: ... is not an integer value: ... or ... outside the safe-integer range .... The iat freshness check
  uses it. _canonical_bytes now refuses a whole number past the safe-integer range
  written as a float (1e21, 9.007199254740993e15), with the IntegerDomainError
  that rfc8785 already raised for the same value written as an integer. The section
  3.2.2 range rule is on every canonicalized object, including the ones no schema
  constrains (bridge declarations, tool-call digests, transcript hashes), and read by
  value 1e21 is an integer outside the range; the rfc8785 package refuses an
  out-of-range int and writes the float as 1e+21 without complaint.
• Bridge (src/agentrust_trace/intent_bridge.py): authorized_at, expires_at and
  transcript.after.observed_at are decided by value, with the reason in the error.
• Adapters (src/agentrust_trace/adapters/agt.py, sandbox.py): the two transcript
  hashes go through _canonical_bytes instead of calling rfc8785.dumps directly, so
  every digest in the package draws the range in the same place.
• Model (src/agentrust_trace/models.py): JsonInt reads a whole float as the
  integer it is and dumps the plain integer; it refuses a float that is not whole, and
  a numeric string, which pydantic's lax mode used to read as a number and the schema
  never accepted.
• Docs (docs/schema.md): one sentence in the introduction.
• Vectors (examples/number-spelling/): seven signed Trust Records, their
  generator, a README, a JavaScript test and a scan script; see below.
• Tests (tests/test_integer_by_value.py, tests/test_adequacy_all_sets.py): the
  boundary table at every layer, the vectors recomputed from committed bytes, plausible
  shortcut implementations graded against the set, and the set registered with the
  adequacy checks.

schema/, the packaged schema copy and the v0.3 draft are unchanged, byte for byte.

Change classification

This PR does not set MAJOR/MINOR/PATCH for itself; that is your call. What it does to
verdicts:

• Accepted now, rejected before: a record whose integer member is a whole number
  written with a fraction or an exponent (Python reference; the TypeScript verifier in
  feat(trust-record-verify): a TypeScript verifier for TRACE v0.2, scored against the Python one #376 already accepted it), and the same for the bridge's three time fields.
• Rejected now, accepted before, in the Python library only: a numeric string for
  an integer member of the model, which the schema already refused; and a whole float
  past the safe-integer range in any object the library signs or digests, such as a
  nanosecond timestamp that went through a double, which the TypeScript canonicalizer
  in feat(trust-record-verify): a TypeScript verifier for TRACE v0.2, scored against the Python one #376 already refused. No record that passes the schema is affected by either:
  every object in the record schema is closed or held to canonicalizableValue, and
  every integer member is bounded.
• No published verdict changes. See the scan below.

Reproduce

Python, against main and against this branch, using a record already on main:

import json

from agentrust_trace.sign import verify_record

path = "examples/verifier-compatibility/01-known-version-verified.json"
text = open(path, encoding="utf-8").read()
assert text.count('"iat": 1785000000,') == 1
for spelling in ("1785000000", "1785000000.0", "1.785e9"):
    doc = json.loads(text.replace('"iat": 1785000000,', f'"iat": {spelling},'))
    try:
        verify_record(doc["record"], doc["trusted_key"], now=1785000100)
        print(f"{spelling:>14}  verified")
    except ValueError as exc:
        print(f"{spelling:>14}  rejected: {exc}")

main (1adbe20)
    1785000000  verified
  1785000000.0  rejected: record has no valid integer 'iat' for freshness check
       1.785e9  rejected: record has no valid integer 'iat' for freshness check
this branch
    1785000000  verified
  1785000000.0  verified
       1.785e9  verified

JavaScript, Node.js 20 or later, nothing to install:

node -e 'for (const t of ["1785000000", "1785000000.0", "1.785e9"]) console.log(t, JSON.parse(t), Number.isSafeInteger(JSON.parse(t)))'
node --test examples/number-spelling/spelling.test.mjs

The first line prints the same number three times. The test file (9 tests) checks that
the spelling does not survive String(Number(x)), the serialization RFC 8785 adopts,
walks the safe-integer boundary as the double sees it, and verifies every signature in
the set with node:crypto over a minimal RFC 8785 form of each record.
tests/test_integer_by_value.py runs it when Node.js 20 or later is on the path.

Vectors

examples/number-spelling/:

Fixture	Member	Written as	Expected
01-integer-spelling-verified.json	iat	1785000000	verified
02-fraction-spelling-verified.json	iat	1785000000.0	verified, 01's signature
03-exponent-spelling-verified.json	iat	1.785e9	verified, 01's signature
04-fractional-value-rejected.json	iat	1785000000.5	rejected, not an integer value
05-fractional-value-exponent-spelling-rejected.json	iat	17850000005e-1	rejected, not an integer value, 04's signature
06-above-range-integer-spelling-rejected.json	appraisal.timestamp	9007199254740992	rejected, outside the range
07-above-range-exponent-spelling-rejected.json	appraisal.timestamp	1.0e+21	rejected, outside the range

01 reuses the record, key and signature published in
examples/verifier-compatibility/01-known-version-verified.json, so the set
introduces no new signing key. Every signature in the set is valid, so a rejecting
vector is rejected for the rule it names and nothing else. The range vectors use
appraisal.timestamp, which no freshness rule reads.

Two vectors per rule, each pair chosen so that a plausible shortcut passes one and
fails the other: refusing an exponent, or accepting .0 by stripping it from the text,
fails 03 and not 02; finding a fraction by looking for a decimal point accepts 05; and
leaving the range to the rfc8785 package rejects 06 and verifies 07.
tests/test_integer_by_value.py runs those shortcuts over the set and checks each is
caught where the README says it is.

Scan: which published records change verdict

examples/number-spelling/scan_published_numbers.py reads every number's spelling
through json's parse_int and parse_float hooks, in *.json files and in fenced
json blocks in Markdown, and reports every integer-typed member written with a
fraction or an exponent. Integer-typed members are read from schema/*.json, plus
cnf.jwk members and the two members typed in prose (observed_at in the bridge
profile, tool_catalog.tool_count in server provenance).

python examples/number-spelling/scan_published_numbers.py \
  examples spec docs schema \
  /path/to/trace-tests-checkout-at-3af2b53 \
  /path/to/trace-registry-checkout

Root	Documents	Numbers	Integer-typed	Written with a fraction or an exponent
examples/ (this repo)	202	1064	453	0
spec/, docs/, schema/ (this repo)	19	86	11	0
trace-tests @ 3af2b53	16	47	32	0
trace-registry @ d8fa885	26	64	9	0
Total	263	1261	505	0

No number anywhere in those roots is written with a fraction or an exponent, integer
member or not. The scan skips examples/number-spelling/, whose vectors are
re-spelled on purpose; pointed at that directory it finds exactly the five re-spelled
members, which is the check that it finds what it looks for. Five Markdown blocks in
spec/ and docs/ are fragments that do not parse; none contains a number written
with a fraction or an exponent.

Current behavior of both implementations

Checked against main at 1adbe20, the base of this branch:

• This repository's reference library verifies 01, rejects 02 and 03 at the
  freshness check (record has no valid integer 'iat' for freshness check), and
  rejects 04 to 07 at the schema. With this change, 01 to 03 verify and 04 to 07 are
  rejected at the schema with the same messages as before.
• The TypeScript verifier under review in feat(trust-record-verify): a TypeScript verifier for TRACE v0.2, scored against the Python one #376 (at 01ca3a5) already decides by
  value, by construction: trust-record-verify/src/verify.ts lines 324 to 327 test
  iat with Number.isSafeInteger; trust-record-verify/src/jcs.ts lines 64 to 76
  refuse any integer-valued number past the range with canonicalization_failed,
  whatever it parsed from; and the schema validators compiled by
  trust-record-verify/scripts/generate-validators.mjs (line 27) test integer as
  !(data % 1), a test on the value. Run over the seven vectors, its verifyRecord
  verifies 01 to 03, and rejects 04 and 05 with schema_invalid ("at iat: must be
  integer") and 06 and 07 with schema_invalid ("at appraisal.timestamp: must be <=
  9007199254740991").

So the two implementations already disagreed on 02 and 03 before this proposal, and
this change brings the reference to what the TypeScript verifier does.

Out of scope (follow-ups, not folded into this proposal)

• Server provenance (src/agentrust_trace/provenance.py): issued_at and
  tool_catalog.tool_count keep their type tests, and
  tests/test_provenance_tool_count.py pins 2.0 as a malformed count. That profile
  signs under section 3.2, so the rule arguably reaches it, but reversing a pinned
  behaviour belongs with that profile.
• Registry anchor format (anchor_bytes, spec/registry-anchor-v1.md §1): the
  anchor leaf is sorted-key JSON, not RFC 8785, and excludes every non-integer number by
  type, 1.0 included, with a test pinning it. Whether that profile should read 1.0
  as 1 is its own question.
• Producer guidance. JSON Schema 2020-12 Core §6.3 says integer JSON numbers SHOULD
  NOT be encoded with a fractional part. Whether TRACE should say the same to producers
  is left open; nothing here requires it.
• Verifier options such as now and max_age_seconds are caller configuration,
  not record data, and keep their integer type checks.

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

This changes normative text in section 3.2.2; breaking or non-breaking is left to you,
see "Change classification" above. No schema file changes: the schemas already read
integers this way.

Spec section

§3.2.2 (Mandatory signature and freshness binding), a new paragraph after "What the
rule covers".

Checklist

• DCO sign-off on all commits (git commit -s)
• CHANGELOG.md updated
• Change marked with <!-- CHANGED: #247 - integer-valued members are decided by value, not by spelling --> in spec text
• Backward compatibility statement included (for breaking changes): the scan above is the evidence; classification is yours

Context

Requested by @imran-siddique on #247, who asked for this as a separate proposal with
Python and JavaScript tests, including boundary cases. Proposed by @chernistry.

[imran-siddique]

Alex, the by-value direction matches my ruling on #247. Please resolve the scope mismatch before implementation approval: the new paragraph reads broadly, but server provenance retains type-based checks for issued_at and tool_count. Either align that profile with tests or explicitly bound the new rule and track the remaining alignment separately. Keep registry-anchor encoding separate. Also document the Python API compatibility changes, including newly rejected numeric strings and out-of-range whole floats; unchanged schemas alone do not make those changes non-breaking.

[lywinged]

Checked at 2778d94, against its base 1adbe20 and main at 5222ed4.

The reproducer in the description gives the output shown there on the base and on this head; current main still rejects 1785000000.0 and 1.785e9. The seven vectors verify and reject as the table says; 02 and 03 carry 01's signature and 05 carries 04's. The scan reproduces here, for trace-tests at 3af2b53 and for trace-registry at d8fa885. Full suite 2340 passed and 6 skipped; the JavaScript test passes 9 of 9.

I also ran the suite against twelve plausible edits: accepting a boolean, dropping or narrowing either range check, truncating a fraction, walking dicts but not lists, reading numeric strings again, keeping a whole float as a float, and putting either adapter back on rfc8785.dumps. Eleven fail a test. Three things before approval:

1. The scope sentence and the code disagree about the provenance record. The description says the whole-float refusal applies "in any object the library signs or digests", and that the provenance profile "signs under section 3.2, so the rule arguably reaches it"; spec/server-provenance-v1.md line 109 agrees that its signing "follows TRACE v0.2 §3.2 exactly, including the canonicalization". The scope sentence added in 2778d94 says the provenance record "is not changed by this paragraph", but provenance.sign_record and provenance.verify_record canonicalize through _canonical_bytes (lines 342 and 483), so a record carrying 1e21, 9007199254740992.0 or -1e21 in an extension member, signed and verified on the base, is refused by verify_record here. The sentence also does not name spec/server-provenance-v2.md, on main since #409. Either settles it: drop the list after the colon, so the paragraph governs everything the rule above covers, provenance included for the range, which also takes in section 3.1.4's transcript_digest; or keep provenance outside and give it a canonicalization path without the new refusal. Whether provenance's issued_at and tool_catalog.tool_count are decided by value is the question the comment above asked to be tracked separately, and there is no issue for it yet.

2. The CHANGELOG's Python API list needs three corrections. Item (2) names sign_claim, which does not exist; the signing functions are sign.sign_record, provenance.sign_record and intent_bridge.sign_bridge. It says the callers raise rfc8785.IntegerDomainError, but digest_jcs and sign_bridge raise IntentBridgeError and the provenance functions raise ProvenanceError. It also omits point 1's provenance change.

3. Rebasing onto main has one catch. #418 wrapped rfc8785.dumps in _canonical_bytes so that nesting past the stack is reported as a CanonicalizationError. With _refuse_whole_floats_out_of_range(d) ahead of that try, the walker's own RecursionError comes out first, and two of #418's tests fail: test_verify_bridge_refuses_a_deeply_nested_tool_call_with_intent_bridge_error and test_provenance_verify_record_refuses_a_deeply_nested_member_with_provenance_error. With the call inside the try, the merged tree passes, 2526 passed and 6 skipped.

Tests to add, not blocking: below the range, _canonical_bytes's own check is tested only with -9007199254740992, which rfc8785 already refuses. Four edits to that check pass the suite: checking only the upper bound, the one of the twelve above that passed; moving either bound in by one; and moving the lower bound out by one. Running -9007199254740992.0, -1e21, 9007199254740991.0 and -9007199254740991.0 through _canonical_bytes pins all four.

[imran-siddique]

@chernistry the three asks from 23 September are met at 08b1d76: the rule reaches provenance.py, registry-anchor encoding is untouched, and the CHANGELOG names both newly refused inputs as a Python API break. #432 and #401 merged today and this now conflicts on CHANGELOG.md, intent_bridge.py and tests/test_adequacy_all_sets.py. Rebase onto main and I will carry the paragraph and merge once it is green.