"baggage": prepare for vat upgrade, deliver durable objects to successor

[warner]

What is the Problem Being Solved?

As part of #1848 and #2004, we need a way for version-1 of a vat to prepare for upgrade to version-2. The earlier version should store critical data (anything necessary for version-2 to fulfill the obligations impliedexpressed by version-1's durable exports) in durable storage, where it can be accessed by version-2. But then version-2 needs a way to reach it.

Our plan is to define a special durable BigMapStore, colloquially named "the baggage", with at least one string key. As a durable collection, it can only hold durable things (pass-by-copy data, imported Presences, exported Remotables that can be reattached at upgrade, exported virtual objects whose Kinds can be reattached at upgrade, and other durable collections). The handle to the baggage is provided to each version at startup, through some special TBD argument (maybe vatPowers.baggage).

In addition to durable data, the baggage should be able to hold whatever sort of "reattachment handle" / "identity resumption/reclamation facet" / (I haven't found a good word yet) that #3062 exposes, through which version-2 can provide new behavior records for the virtual-object Kinds that the earlier version created. This provides a user-code -legible way to connect the original Kind definition in version-1, through a named path in the baggage, to the code in version-2 that attaches a new Kind definition to that named path.

The metaphor is that version-1 of the vat is a business owner preparing for retirement, and their shop is going to be moved to a new building. Version-1 puts important documents and inventory in durable collections, and puts references to those collections in the "baggage". Upon retirement (upgrade), everything that's durable is moved to the new building, and anything that isn't durable is left behind. But these are ocaps, so merely being present in the new building is not sufficient: you need an access path. Version-2 is the new owner in the new location, who is handed the "baggage" by the estate/transfer agent. Anything not transitively reachable from the baggage is unreachable, even it if was durable. Both the old and new owners can use Store access to store/retrieve their data, e.g. version-1 does baggage.set('pending orders', pendingOrdersCollection), and version-2 does pendingOrdersCollection = baggage.get('pending orders').

The baggage Store can use non-string keys too, later, but the starting point must be a string (or Number, or other flat data), because version-2 starts with nothing but the baggage and the source code they rode in on. That source code can contain data but not objects. The baggage is the only real "object" they get from version-1.

Description of the Design

TBD

Obviously we should find a better name than "baggage". "upgrade data"?

Maybe deliver as vatPowers.baggage, which limits access to just buildRootObject and whatever function version-2++ uses at startup (maybe also buildRootObject, maybe something like upgrade or start). Another option is an additional argument to buildRootObject.

Security Considerations

All sorts of critical (mutable!) state is reachable from the baggage, so it must be closely held and thoughtfully guarded. It's easy to store a hierarchy of data in there, so POLA should be exercised (give pendingOrders to the order-handling code, rather than all baggage). Clearly the baggage must not be exposed as a global.

Test Plan

Unit tests to show baggage being present on vatPowers and usability as a normal collection.

Unit/integration tests to populate baggage with some plausible use-case data (order book, some Kind handles) and then demonstrate a version-2 upgrade path which then reads from baggage and restores functionality using the data therein.

Documentation Plan

docs/vat-upgrade.md should have a section on the baggage, what it offers, how to use it, when to not use it (intentionally abandoned non-durable data), and some examples.