feat(cli): emit self-contained before/after sequence comparison bundles

[tryingET]

Purpose

Introduce the first data-plane primitive for an interactive AppMap PR comparison workspace: one portable file containing the before diagram, after diagram, merged semantic diff, and event alignment for synchronized change navigation.

This is the Sequence Diagram vertical slice toward synchronized before/after/overlay views for Dependency Map, Sequence Diagram, Trace View, and Flame Graph.

Changes

• Add appmap sequence-diagram-compare <base-appmap> <head-appmap>.
• Emit *.compare.diff.sequence.json containing:
  • serialized base and head sequence diagrams;
  • the existing merged semantic diff;
  • aligned actor ordering;
  • stable change IDs;
  • base/head/diff event IDs for added, removed, and changed actions;
  • optional scenario and revision metadata.
• Register the command in the CLI.
• Add a focused unit test using existing AppMap fixtures.

Example

appmap sequence-diagram-compare \
  base.appmap.json \
  head.appmap.json \
  --scenario login-success \
  --base-revision "$BASE_SHA" \
  --head-revision "$HEAD_SHA" \
  --output-file login-success.compare.diff.sequence.json

Companion work

• Viewer: tryingET/vscode-appland#1
• End-to-end producer/dogfood: tryingET/appmap-node#1
• Artifact publisher: tryingET/review-action#1
• Deterministic comparison skill: tryingET/skills#1

Validation

Cross-repository dogfood is green in tryingET/appmap-node run 32134789649:

• CLI branch builds and runs the new command.
• Exact base/head appmap-node revisions build.
• Recordings are sanitized.
• Control comparison contains 0 changes.
• Visual comparison contains exactly 1 added authorize call.
• Portable comparison artifact uploads.
• The real generated bundle opens in the companion VS Code Electron test.
• Dogfood VSIX packages and uploads.
• Review-action publisher/skill harness passes.

Artifacts:

• appmap-pr-comparison — artifact 9323691826, SHA-256 0cd6a4fc0a11f38713e6739fbab585e2f553dd6cece002d33c4d53a66651e0e9
• appmap-comparison-vsix — artifact 9323896071, SHA-256 7855a61259d588b0ee12807143f6dd63c15a33708f67722a474db07207b531f0

The upstream CI and native-build runs currently show action_required, awaiting first-time-contributor workflow approval rather than reporting a code failure. The PR remains draft while the dependency chain is reviewed.

[tryingET]

Final schema-v1 freeze and cross-repository dogfood

This supersedes the earlier prototype validation. The comparison artifact is now a frozen, view-neutral contract, not a Sequence-Diagram-only envelope.

Frozen contract

• kind: "appmap.comparison"
• top-level schemaVersion: 1
• independently versioned dependency, sequence, trace, and flame view slots
• one canonical BehavioralChange[] shared by every view
• deterministic, opaque chg_<20-hex> IDs; repeated identical changes use _2, _3, …
• event references where available and elementIds for structural actions without events
• explicit recording, revision, producer, capability, and navigation metadata
• published JSON Schema, TypeScript declarations, compatibility rules, changelog, and five conformance fixtures: clean, added, removed, changed, reordered
• runtime validation before the CLI writes a bundle

Final reproducible dogfood

tryingET/appmap-node run 32226024667 is green across all three pinned jobs:

• Record and compare base/head behavior — passed
• Build and exercise comparison viewer — passed
• Verify review artifact publisher — passed

The run pinned and verified these exact revisions:

• appmap-js: aab690a5c4c01802551993718b508718c1139c11
• vscode-appland: cfd3a0fef35b016cb0af20ee02ae46fd35414069
• review-action: 67060904f03c0c8a1492e610f845eefd29e53a78
• skills: 167db8d4b7eb56086c74a9ef9ffe7b2d3c8ab627

It verified:

• model contract tests: 12 passed
• CLI producer tests: 2 passed
• clean control: 0 behavioral changes
• visual scenario: exactly 1 call-added authorize change
• deterministic, non-positional change IDs
• structural actions without AppMap event IDs remain represented through elementIds
• all source AppMaps were sanitized
• the generated schema-v1 artifact opened in the pinned VS Code Electron extension host
• the comparison viewer VSIX packaged successfully
• the pinned skill and review-action publisher harness passed

Final artifacts

• appmap-pr-comparison-schema-v1 — artifact 9355642181, SHA-256 9e7e2d34d75dcae27a6a60f7b9d22d90daa04233af4a2358ddda2ae38b6ffac0
• appmap-comparison-schema-v1-vsix — artifact 9355691022, SHA-256 c845728666068d97d58864bb091e14bf0cc33ed314097a2d776cc00745429379

The data artifact includes the generated bundles, four sanitized AppMaps, JSON Schema, compatibility documentation, schema changelog, all five fixtures, and a lock file containing every exact tested revision.

The upstream CI and Build Native checks remain action_required, awaiting first-time-contributor workflow approval; the pinned fork dogfood reports no code or integration failure.