Diff two session recordings
Answer the question a card lab asks constantly: the same script ran against two cards, or against one card before and after a change, so where did they stop agreeing?
On this page
yggdrasim-session-diff compares the APDU traces of two shell session
recordings and reports only what differs: status words, response bodies,
and exchanges present on one side only.
Record both sessions
The session recorder lives in the SCP11 Local Access and SCP11 eIM Local shells. Run the same command sequence against each card:
RECORD START Workspace/card-a.yaml
... run the sequence ...
RECORD STOP
Then repeat against the second card into Workspace/card-b.yaml.
RECORD [STATUS|START|STOP|CANCEL] is the session recorder in those
shells. Do not confuse it with the SCP03 shell's RECORD <n|ALL|start-end>,
which is READ RECORD against a card file and writes no recording.
The recorder writes .yaml, .yml, or .json; the diff reads all three.
Compare them
yggdrasim-session-diff Workspace/card-a.yaml Workspace/card-b.yaml
left : Workspace/card-a.yaml (146 exchanges)
right: Workspace/card-b.yaml (147 exchanges)
3 difference(s): 1 status, 1 response, 0 only-left, 1 only-right
L41/R41 status differs 00A4000402FFFF
left : 9000
right: 6A82
L58/R58 response differs 00B0000010
left : 98620000000000000001
right: 98620000000000000002
L-/R92 only in right 00C0000010
Exit status is 0 when the traces match, 1 when they diverge, and 2
when a file could not be read, so a shell loop can branch on it:
if ! yggdrasim-session-diff baseline.yaml candidate.yaml > /dev/null; then
echo "card behaviour changed"
fi
--json emits the same result as a machine-readable object.
How exchanges are aligned
Alignment is on the command APDU, not on position. A single extra exchange
on one side (a retry, an added GET RESPONSE) would otherwise shift every
following index and make the rest of the run look different when only one
thing changed. With APDU-keyed alignment that insertion shows up as one
only in right entry and the rest still lines up.
The consequence worth knowing: if the two runs issue genuinely different
command sequences, you get paired only in left / only in right entries
rather than a "changed" entry, because there is no matching command to
compare a response against.
Response payloads are truncated
APDU responses can carry PINs, keys, and operator secrets. Text output clips payloads to 32 hex characters and tells you the true length:
left : AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA... (128 hex chars)
Pass --full to print them untruncated. Do that only when you know what
is in the trace and where the output is going.
From an AI assistant
The same comparison is available as the session_diff MCP tool; see
Run the MCP Server.
From Python
from yggdrasim_common.session_diff import diff_recordings
result = diff_recordings("card-a.yaml", "card-b.yaml")
if not result.identical:
first = result.first_divergence
print(first.kind, first.left_index, first.apdu_hex)
Validation
Diff a recording against itself. It must report APDU traces are identical
and exit 0:
yggdrasim-session-diff Workspace/card-a.yaml Workspace/card-a.yaml
If that reports differences, the recordings carry per-run state (timestamps inside a response, a counter) rather than the tool being wrong.