Skip to content

Add pdr diff - #64

Merged
ILIASTEKEOGLOU merged 1 commit into
mainfrom
pdr/diff
Oct 10, 2026
Merged

ILIASTEKEOGLOU merged 1 commit into
mainfrom
pdr/diff

Conversation

@ILIASTEKEOGLOU

Copy link
Copy Markdown
Owner

Summary

qstriage pdr diff BEFORE AFTER [--format markdown|json] [--output FILE] [--overwrite]

  • Both documents are verified first (0.2 and 0.3 rules). If either fails,
    the command prints which one and exits 1 without a comparison.
  • Records are matched by record_id; decision and observed_state fields
    are compared.
  • Provenance items compared: input file (source_hash), policy pack
    (policy_pack_hash), algorithm registry (registry_hash), QSTriage
    version (engine.version), PDR format (pdr_version). When more than one
    differs, the report states that a decision change cannot be attributed to
    one of them. No cause is inferred.
  • Between different pdr_version values, fields present in only one
    document are listed as format differences, not as changes.

Report layout (Markdown, default)

  1. Result: decisions changed, records added and removed, verification of
    both files.
  2. What changed between the two runs, in plain words.
  3. Decisions that changed: action, algorithm status, human review, reason
    codes, per asset.
  4. Records whose observed state changed without a decision change, listed
    separately.
  5. Format differences (not decision changes).
  6. Field details table.

The report shows what the records contain and does not recommend actions.
Text taken from the documents is escaped with the same helpers as the
Markdown report. --format json carries the same content with document,
policy-pack and registry hashes.

Exit codes

0: comparison produced (the JSON field changed states whether anything
changed). 1: read, verification or write failure. 2: invalid option.

Verification

  • 13 tests: identical documents, single-cause and multiple-cause
    attribution, 0.2 to 0.3 and 0.3 to 0.2 format differences, added and
    removed records, tampered document refused, duplicate record_id
    refused, Markdown escaping of untrusted names, JSON content, CLI exit
    codes, no-clobber output, inputs unchanged.
  • Local runs: Linux Python 3.11 and 3.13, 1454 passed, 3 skipped; Windows
    Python 3.11, 1453 passed, 4 skipped. Comparing the stored PDR 0.2 fixture
    with a PDR 0.3 in which one algorithm became X25519MLKEM768 reports 2 of
    5 decisions changed and exits 0.

Documentation

docs/usage.md, docs/pdr-contract.md (Comparison), input limits in
docs/input-contracts.md and the README, CHANGELOG (Unreleased, Added).

qstriage pdr diff BEFORE AFTER verifies both PDR documents and
compares them record by record. A document that fails verification
stops the command with exit code 1 and no comparison.

Records are matched by record_id. The fields of decision and
observed_state are compared. Provenance is compared item by item:
input file, policy pack, algorithm registry, QSTriage version and
PDR format. When more than one item differs, the report states that
a decision change cannot be attributed to one of them. When the two
documents have different pdr_version values, fields present in only
one of them are listed as format differences, not as changes.

The Markdown report, the default, gives the result in plain
sentences first: how many decisions changed, what differs between
the two runs, and for each changed record the action, algorithm
status, human-review requirement and reason codes, followed by a
table of every changed field. Text taken from the documents is
escaped. --format json gives the same content with hashes.

Exit code 0 means a comparison was produced, 1 a read, verification
or write failure, 2 an invalid option. --output never replaces an
existing file without --overwrite and never writes over an input.
@ILIASTEKEOGLOU
ILIASTEKEOGLOU merged commit fdb35ad into main Oct 10, 2026
19 checks passed
@ILIASTEKEOGLOU
ILIASTEKEOGLOU deleted the pdr/diff branch October 10, 2026 17:09
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.

1 participant