[Spike] Assess verification against real wallet versions #118

[EmmanuelAdah]

Add protocol-drift detection infrastructure for real Freighter/Albedo wallet testing

Summary

Adds a spike report and initial infrastructure for detecting when real Freighter/Albedo
extension releases drift from what Gryd Lock's synthetic e2e fixtures assume. Splits
CI into fast/blocking checks vs. slower/non-blocking real-wallet canary checks, and adds
a first real-wallet interception test against a live Freighter build.

What's included

Docs

• protocol-drift-spike.md — synthetic coverage analysis, wallet compatibility matrix
  template, protocol-fixture proposal, CI/scheduled recommendation, follow-up plan.

External protocol contracts

• src/intercept/externalWalletProtocol.ts — zod schemas + type guards for Freighter's
  SUBMIT_TRANSACTION request/response and Albedo's intent request/response, built from
  the real fixtures already used in src/tests/walletContracts.test.ts. Distinct from
  the existing src/intercept/protocol.ts, which governs Gryd Lock's own internal
  message bus and can't drift the way an upstream wallet can.
• Only the decline/reject path is confirmed against real fixtures for both wallets.
  Success-response shapes for both are explicitly marked unconfirmed in comments.

Real-wallet e2e (new, isolated from the synthetic suite)

• e2e/real/real-freighter-version.spec.ts — loads a real, version-pinned Freighter
  build alongside dist/, captures whatever messages the real extension actually sends,
  and validates them against the schemas above. Skips gracefully if no vendored build
  is present.
• playwright.canary.config.ts — new, scoped to e2e/real, longer timeout than the
  synthetic config.
• playwright.e2e.config.ts — added testIgnore: '**/real/**' so the default
  npm run test:e2e never picks up real-wallet tests.
• scripts/download-wallet-release.sh — fetches a pinned Freighter/Albedo tag.
  Clones source only — does not build it yet (see Known gaps).
• tests/wallet-versions.json — single source of truth for pinned wallet versions.

CI

• .github/workflows/ci.yml — added npm audit --omit=dev (blocking, production deps
  only) and full npm audit (informational, continue-on-error); removed a redundant
  duplicate Playwright browser install; added npm run check:versions to the PR-blocking
  path.
• .github/workflows/wallet-canary.yml — new, non-blocking, scheduled nightly (pinned
  versions) + weekly (latest versions), files/updates a GitHub issue on failure.

Misc

• .gitignore — fixed a real bug in the fixtures/wallets/**/ pattern (git won't
  descend into an already-ignored directory to apply the .pinned-version negation);
  added coverage/, playwright-report/, .env*.

Known gaps — do not merge assuming these are solved

• scripts/download-wallet-release.sh doesn't build anything. Needs the real
  Freighter/Albedo build commands wired in once confirmed.
• The real Freighter test currently fails on a fresh profile, because Freighter
  has no onboarded account and lands on #/welcome. e2e/real/helpers/onboardFreighter.ts
  is a scaffold with placeholder selectors (marked TODO-SELECTOR), not working
  code — it needs real selectors from a recorded onboarding session
  (scripts/record-freighter-onboarding.mjs) before this test can pass end-to-end.
• No golden-capture fixtures or docs/wallet-compatibility.md yet — the matrix in
  the spike doc has unverified cells pending a real run.
• No packaging/zip step implementing releaseArchiveName() from scripts/versioning.mjs.
• PyCharm's Playwright plugin isn't correctly picking up e2e/real/*.spec.ts — runs
  fine from terminal (npx playwright test --config=playwright.canary.config.ts), IDE
  integration untested/unresolved.

Testing

• npx playwright test --config=playwright.canary.config.ts -g "Real-wallet protocol drift: Freighter" — currently fails at the onboarding gap described above (expected,
  not a regression).
• Synthetic suite (npm run test:e2e) and unit/contract tests (npm run test:all)
  unaffected by this PR — no changes to existing passing tests.

Follow-ups (not in this PR)

• Complete onboardFreighter() with real recorded selectors.
• Wire real build commands into download-wallet-release.sh.
• Repeat the same pattern for Albedo (structurally different — popup-first, no ambient
  interception point).
• Populate docs/wallet-compatibility.md from actual PoC runs.