feat(ocapn): add baggage seams and op:resume-session handshake

[kumavis]

Refs: N/A

Description

This PR now includes the durable-client scaffolding plus follow-on implementation to tighten resume semantics and persist additional session/table state through baggage.

Core @endo/ocapn updates

• Resume handshake format split
  • op:start-session remains full introduction handshake (captpVersion, key, location, location signature).
  • op:resume-session is now resume-specific and minimal:
    • sessionId
    • sessionIdSignature
• Resume validation flow
  • incoming op:resume-session is validated against baggage-backed session records
  • signature is checked against the stored peer public key for that prior session
  • session-id mismatch and unknown sessions fail closed with abort
• Resume requires baggage-backed history
  • makeClient({ tryResumeSession: true }) now requires an explicitly supplied baggage instance.
• Baggage-backed resume lookup state
  • persisted maps added in client baggage:
    • ocapn:resumeSessionsByLocationId
    • ocapn:resumeSessionsById
• Baggage helper behavior improvement
  • provideFromBaggage() now returns the value read back from baggage after initialization, allowing baggage implementations to provide wrapped/persistent map-like stores.
• Export-position persistence integration
  • referenceKit now reads/writes optional table methods:
    • getNextExportPosition()
    • setNextExportPosition()
  • used to keep slot allocation monotonic across restart.

Durable package @endo/ocapn-durable-client

• Added durable package scaffold and helpers.
• Added filesystem-backed baggage (makeFsDurableBaggage) with recursive encoding/decoding support for baggage entries and map-like values.
• Durable table factory now persists per-peer table state including:
  • localSlots
  • nextExportPosition
• Added schema doc:
  • packages/ocapn-durable-client/docs/baggage-schema.md
• README updated to clarify durable boundary expectations:
  • user-provided boundary references are expected to be durable objects (e.g. makeExo style), not ephemeral Far refs.

Restart coverage

• Durable restart tests in packages/ocapn-durable-client/test/restart.test.js now verify:
  • import/export slot continuity across client restart with persisted baggage
  • monotonic slot progression for new exports after restart
  • explicit baggage requirement when tryResumeSession is enabled.

Security Considerations

• Resume handshake is now clearly separated from start-session handshake and scoped to existing-session proof material.
• Resume acceptance is tied to persisted session records and signature verification.

Scaling Considerations

• Additional baggage entries introduce modest map lookups/writes on session resolution/resume and slot allocation updates.

Documentation Considerations

• Added durable baggage hierarchy/schema document with key layout and invariants.
• Updated durable README assumptions around durable references.

Testing Considerations

Executed:

In packages/ocapn:

• corepack yarn lint
• corepack yarn test
• corepack yarn test:update-snapshots test/codecs/operations.test.js

In packages/ocapn-durable-client:

• corepack yarn lint
• corepack yarn test

Compatibility Considerations

• op:start-session remains default for fresh sessions.
• op:resume-session wire format changed to resume-specific fields.
• resume mode now explicitly depends on provided baggage.

Upgrade Considerations

• Existing ephemeral users remain on start-session default behavior.
• Durable/resume adopters should provide explicit baggage and rely on persisted resume/session records.

  

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5cb24a2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR