implement clist reachability flag

[warner]

What is the Problem Being Solved?

As the "implement kernel-side syscall.dropImport handler, add clist reachability flag" part of #3106 , we need to keep track of when an import-side c-list entry represents the vat's ability to "reach" the swingset object designated by the kref (i.e. it might emit a message that references the kref at some point in the future), or if it can merely "recognize" that object (i.e. if the kref is sent into the vat in the future, the vat can recognize this kref as equal to one it saw before). The "reach" mode is a superset of the "merely recognizable" mode:

• reachable + recognizable
• not reachable, yes recognizable
• neither reachable nor recognizable

The kernel will use this information to figure out whether a vat export is still reachable by the kernel, and drop the export if not. The clist exports will be similarly marked to keep track of whether the kernel has told the vat to drop the export, and subsequently updated if the vat re-exports the same kref.

Description of the Design

I plan to change the kref -> vref clist entry format to include the reachability flag as a prefix on the vref. To make things easy to visually parse (for debugging), I'll use "R " as the "yes reachable" prefix, and "_ " as the "not reachable" prefix. The vref->kref direction will not be annotated. Some examples:

• reachable + recognizable: DB.set('v1.c.ko23', 'R o-45')
• not reachable, yes recognizable: DB.set('v1.c.ko23', '_ o-45')
• neither reachable nor recognizable: DB.delete('v1.c.ko23')

All code that looks up the kref->vref direction will be changed to handle this two-character prefix, using slice() to extract the parts.

Code that adds a new entry will set the reachability flag. Code that translates from vat space to kernel space will also set the reachability flag, to handle re-importing/re-exporting the vref. A separate task will be to handle syscall.dropImport and deliver dispatch.dropExport, both of which will clear the flag.

Security Considerations

Test Plan

Unit tests will be updated. New unit tests will be written for the translation code (to exercise the initial setting of the flag, and re-setting it upon re-import/re-export).

[warner]

The set/assert rules for the reachability flag (when translating in either direction) are:

• if you would be allowed to allocate a new entry, you must ensure the flag is set
• if you would not be allowed to allocate a new entry, you must assert that the flag was already set
• but GC syscalls should not set the flag

This means:

• vat -> kernel (syscalls):
  • non-GC syscalls use convertVatSlotToKernelSlot on targets and arguments
    • targets must already exist, and really ought to be an import (vats shouldn't involve the kernel when talking to themselves)
    • arguments which are exports:
      • if they already exist, set the reachability flag, because it might be a re-export
      • if they don't already exist, allocate a new kref, and set the reachability flag
    • arguments that are imports:
      • these must already exist, else it's a vat-fatal error
      • the existing entry must have the reachability flag set, else it's a vat-fatal error
        • existing but non-reachable would mean the vat previously imported this, but then gave it up by calling syscall.dropImport, so they no longer have the right to reference it with outbound messages
• kernel -> vat (deliveries, return value of syscall.vatstoreGet and syscall.invoke)
  • non-GC deliveries should not modify the reachable flag
  • arguments which are imports:
    • if they already exist, set the reachability flag (the vat can now reach the kref), because it might be a re-import
    • if they don't already exist, allocate a new vref, and set the reachability flag
  • arguments that were exports:
    • these must already exist
    • they existing entry must have the reachability flag set
      • if not, it's probably a kernel error, rather than a vat error: the kernel shouldn't clear that flag until the kref is no longer reachable by anyone else, so there should be no reason for the kernel to mention it in the delivery
      • if a vat could unilaterally revoke an object, without telling the kernel, that might look like this situation