fix(uxf,payments): bundleCid determinism — lock envelope timestamp across attempts

[vrogojin]

Blocks PR #358 (V6-RECOVER test gap). The Node 20 CI failure on #358 traced to a pre-existing bundleCid non-determinism bug in main, not to V6's content. This PR fixes the root cause; #358 will be rebased onto the updated main and re-run CI.

Summary

The CAR root CID of a UXF bundle is the dag-cbor SHA-256 of the envelope block. The envelope embeds createdAt and updatedAt — both sourced from Math.floor(Date.now() / 1000) at create/ingest/merge time. This makes the bundleCid non-deterministic across attempts: two UxfPackage.create({...}).ingestAll(...) sequences straddling a wall-clock second boundary (a few ms apart) produce different envelope bytes → different bundleCids.

How the bug surfaces

tests/integration/transfer/crash-recovery.test.ts:726 asserts:

expect(finalEntry!.bundleCid).toBe(persisted!.bundleCid)

On slow Node 20 CI runs the resume call lands in a different wall-clock second than the first attempt → assertion flakes. Today's PR #358 CI fail (Node 20) → re-run pass demonstrates the flake exactly.

What's broken (besides this one test)

bundleCid stability is a core invariant, not a test convenience. The bug silently degrades:

• replay-LRU at the recipient (T.3.A's dedup key — different CID = treated as a new bundle, replay protection bypassed)
• IPFS pin reuse (re-publishing should hit the existing pin, not create a duplicate)
• sender-side outbox dedup (worker can't recognize "this is the same retry, not a new send")
• audit-Audit: integration/all-fixes — money-path subsystems (UXF / Profile / transfer pipeline) #333 H3 mergePkg targetExisting === sourceIncoming fast-path (already in main as of fix(uxf): surface mergePkg skipped tokens + add strict mode (Audit #333 H3) #352 — relies on consistent CIDs)

Fix

Public API (additive, fully back-compat)

UxfPackage.create({ description?, creator?, createdAt?, updatedAt? })
pkg.ingest(token, { updatedAt? })
pkg.ingestAll(tokens, { updatedAt? })

When the new fields are omitted, behaviour is identical to before. When provided, they lock the envelope timestamps.

Sender wiring

interface InstantSenderDeps {
  // ...existing fields
  readonly bundleCreatedAt?: number;  // unix ms
}
interface ConservativeSenderDeps {
  // ...existing fields
  readonly bundleCreatedAt?: number;  // unix ms
}

Inside both senders:

const now = deps.bundleCreatedAt ?? Date.now();         // lock once at top
const envelopeStamp = Math.floor(now / 1000);
const pkg = UxfPackage.create({ ..., createdAt: envelopeStamp });
pkg.ingestAll(tokens, { updatedAt: envelopeStamp });    // lock updatedAt too

Test update

tests/integration/transfer/crash-recovery.test.ts now passes bundleCreatedAt: persisted!.createdAt on each resume deps — what the test had always intended to verify. The 3 idempotency assertions there finally guarantee what they read.

New test file — forward regression guard

tests/unit/uxf/bundle-cid-determinism.test.ts (6 tests):

• ✅ Two calls with the SAME createdAt produce identical CIDs
• ✅ Two calls with DIFFERENT createdAt produce different CIDs (sanity: fix didn't strip the timestamp)
• ✅ Explicit updatedAt independently controls envelope
• ✅ Omitted updatedAt defaults to createdAt
• ✅ Production scenario — clock advances across a second boundary, locked timestamps produce identical CIDs
• ✅ Contrast — clock advances across the same boundary WITHOUT locks → different CIDs (proves the bug exists if locks are removed)

The contrast test is the regression guard: a future refactor that re-introduces unlocked Date.now() somewhere on the envelope path will fail this specific test, not just flake.

Production wiring (deferred)

PaymentsModule.dispatchUxfInstantSend / dispatchUxfConservativeSend should pass bundleCreatedAt from the resumed outbox entry's createdAt. First-attempt sends (no prior outbox entry) omit it and the sender computes a single locked timestamp internally. That's a follow-up — the infrastructure here is sufficient.

Test plan

• 6 new determinism tests pass
• All 4 tests/integration/transfer/crash-recovery.test.ts tests pass
• All 463 tests/unit/uxf/ + 1491 tests/unit/payments/transfer/ tests pass
• All 514 unit test files (8651 tests + 11 skipped) pass
• tsc --noEmit clean

Related

• Triggered by Node 20 CI flake on PR test(payments/transfer): close V6-RECOVER test-coverage gap + nightly soak CI (Audit #333 follow-up) #358 (audit-Audit: integration/all-fixes — money-path subsystems (UXF / Profile / transfer pipeline) #333 V6-RECOVER test gap)
• Audit-Audit: integration/all-fixes — money-path subsystems (UXF / Profile / transfer pipeline) #333 stack: fix(profile/storage): plug plaintext-seed window in encrypt() (Audit #333 C1) #346, fix(profile/migration): force durable flush before cleanup (Audit #333 C2) #347, fix(profile/flush-scheduler): probe before destructive oplog reset (Audit #333 C3) #361, fix(payments/transfer): same-process source lock for conservative-sender (Audit #333 H1) #349, fix(uxf): bind manifest tokenId to root content (Audit #333 H2) #351, fix(uxf): surface mergePkg skipped tokens + add strict mode (Audit #333 H3) #352, fix(payments/transfer): re-derive requestId binding gate (Audit #333 H4) #353, fix(payments/transfer): unlock source tokens on failed-permanent (Audit #333 H5) #354, fix(profile): add recompute-content verifier to ManifestCas (Audit #333 H7) #355 all already merged