fixup! feat(marshal,pass-style): admit immutable ArrayBuffer through codecs

Apply the relevant feedback from #2871 to subsume that PR:

- @gibson042 #2871:byteArray.js:127 — `uint8ArrayToByteArray` now
  honors the source `Uint8Array`'s `byteOffset` and `length`, so a
  view over a slice of a larger buffer round-trips correctly:
  `uint8ArrayToByteArray(new Uint8Array(buf, byteOffset, length))`
  represents exactly the bytes in `[byteOffset, byteOffset + length)`.
  Documented the zero-copy / copy tradeoff with `sliceToImmutable`.
- @gibson042 #2871:byteArray.js:130 — comment on `byteArrayToHex` /
  `hexToByteArray` is now phrased as "Like `encodeHex` but…" /
  "Like `decodeHex` but…", matching gibson's suggested wording for
  the byteArray-flavored wrappers.
- @erights #2871:encodeToCapData.js:453 / encodeToSmallcaps.js — the
  factory functions `makeDecodeFromCapData` and
  `makeDecodeFromSmallcaps` are now `harden`-ed at module scope,
  matching the existing harden of their encoder counterparts
  (`makeEncodeToCapData`, `makeEncodeToSmallcaps`).
- @erights #2871:marshal-test-data.js — propagate Mark's full
  byteArray fixture set: `roundTripPairs`, `jsonJustinPairs`,
  `unsortedSample`, and `sortedSample`.  The Justin test compartment
  exposes `hexToByteArray` so the rendered Justin expression
  evaluates.

Not propagated, deliberately:

- `packages/marshal/src/rankOrder.js` — Mark's
  `compareRankRemotablesTied` refactor is orthogonal to codec
  admission and lands as its own PR (bots #73 today, awaiting an
  upstream PR).
- `packages/pass-style/src/hex.js` — Mark vendored a private hex
  implementation in pass-style; we route through the merged
  `@endo/hex` package (#3208) instead.  As a result,
  `packages/pass-style/index.js` exports `byteArrayToHex` /
  `hexToByteArray` but not `uint8ArrayToHex` / `hexToUint8Array`;
  consumers needing raw hex helpers should
  `import { encodeHex, decodeHex } from '@endo/hex'`.

Tests: `@endo/marshal` 79 + 1 skip, `@endo/pass-style` 29.  Lint clean.

Author: kriskowal

packages/marshal/src/encodeToCapData.js

@@ -451,3 +451,4 @@ export const makeDecodeFromCapData = (decodeOptions = {}) => {
   };
   return harden(decodeFromCapData);
 };
+harden(makeDecodeFromCapData);

packages/marshal/src/encodeToSmallcaps.js

@@ -477,3 +477,4 @@ export const makeDecodeFromSmallcaps = (decodeOptions = {}) => {
   };
   return harden(decodeFromSmallcaps);
 };
+harden(makeDecodeFromSmallcaps);

packages/marshal/test/marshal-justin.test.js

@@ -5,6 +5,7 @@ import { makeError, X } from '@endo/errors';
 import {
   Far,
   Remotable,
+  hexToByteArray,
   makeTagged,
   passableSymbolForName,
 } from '@endo/pass-style';
@@ -42,6 +43,7 @@ const fakeJustinCompartment = () => {
   return new Compartment({
     slot,
     slotToVal,
+    hexToByteArray,
     makeTagged,
     passableSymbolForName,
   });

packages/marshal/tools/marshal-test-data.js

@@ -1,5 +1,9 @@
 import harden from '@endo/harden';
-import { makeTagged, passableSymbolForName } from '@endo/pass-style';
+import {
+  hexToByteArray,
+  makeTagged,
+  passableSymbolForName,
+} from '@endo/pass-style';
 import {
   exampleAlice,
   exampleBob,
@@ -129,6 +133,15 @@ export const roundTripPairs = harden([
   [[undefined], [{ '@qclass': 'undefined' }]],
   [{ foo: undefined }, { foo: { '@qclass': 'undefined' } }],
 
+  // byteArray
+  [
+    hexToByteArray('0f'),
+    {
+      '@qclass': 'byteArray',
+      data: '0f',
+    },
+  ],
+
   // tagged
   [
     makeTagged('x', 8),
@@ -258,6 +271,9 @@ export const jsonJustinPairs = harden([
   ['{"@qclass":"symbol","name":"foo"}', 'passableSymbolForName("foo")'],
   ['{"@qclass":"symbol","name":"@@@@foo"}', 'passableSymbolForName("@@@@foo")'],
 
+  // byteArray
+  ['{"@qclass":"byteArray","data":"0aff"}', 'hexToByteArray("0aff")'],
+
   // Arrays and objects
   ['[{"@qclass":"undefined"}]', '[undefined]'],
   ['{"foo":{"@qclass":"undefined"}}', '{foo:undefined}'],
@@ -334,6 +350,7 @@ export const unsortedSample = harden([
   undefined,
   -Infinity,
   [5],
+  hexToByteArray('0f'),
   exampleAlice,
   [],
   passableSymbolForName('foo'),
@@ -347,6 +364,7 @@ export const unsortedSample = harden([
   [exampleAlice, 'a'],
   [exampleBob, 'z'],
   -0,
+  hexToByteArray('aa'),
   {},
   [5, undefined],
   -3,
@@ -356,6 +374,7 @@ export const unsortedSample = harden([
   ]),
   true,
   'bar',
+  hexToByteArray('0a'),
   [5, null],
   new Promise(() => {}), // forever unresolved
   makeTagged('nonsense', [
@@ -429,6 +448,10 @@ export const sortedSample = harden([
   [exampleCarol, 'm'],
   [exampleBob, 'z'],
 
+  hexToByteArray('0a'),
+  hexToByteArray('0f'),
+  hexToByteArray('aa'),
+
   false,
   true,
   true,

packages/pass-style/src/byteArray.js

@@ -97,16 +97,34 @@ harden(byteArrayToUint8Array);
  * Converts a `Uint8Array` to a `ByteArray`, i.e., a hardened Immutable
  * ArrayBuffer whose `passStyleOf` is `'byteArray'`.
  *
+ * Honors the `Uint8Array`'s `byteOffset` and `length` so that a view
+ * over a slice of a larger buffer round-trips correctly:
+ * `uint8ArrayToByteArray(new Uint8Array(buf, byteOffset, length))`
+ * always represents exactly the bytes in `[byteOffset, byteOffset +
+ * length)`.
+ *
+ * If the underlying platform implements `sliceToImmutable` natively
+ * with the obvious zero-copy optimization on an already-immutable
+ * source buffer, this conversion is zero-copy.  Otherwise, it pays
+ * the copy cost implicit in `sliceToImmutable`.
+ *
  * @param {Uint8Array} uint8Array
  * @returns {ArrayBuffer}
  */
-export const uint8ArrayToByteArray = uint8Array =>
+export const uint8ArrayToByteArray = uint8Array => {
+  const { byteOffset, length } = uint8Array;
   // @ts-expect-error shim-augmented ArrayBuffer type
-  harden(uint8Array.buffer.sliceToImmutable(0, uint8Array.length));
+  const byteArray = uint8Array.buffer.sliceToImmutable(
+    byteOffset,
+    byteOffset + length,
+  );
+  return harden(byteArray);
+};
 harden(uint8ArrayToByteArray);
 
 /**
- * Hex-encodes the contents of a ByteArray.
+ * Like `encodeHex` but starting from a presumably frozen (immutable)
+ * ByteArray.
  *
  * @param {ByteArray} byteArray
  * @returns {string}
@@ -116,7 +134,9 @@ export const byteArrayToHex = byteArray =>
 harden(byteArrayToHex);
 
 /**
- * Decodes a hex string into a ByteArray (hardened Immutable ArrayBuffer).
+ * Like `decodeHex` but producing a hardened Immutable ArrayBuffer
+ * (`passStyleOf === 'byteArray'`) instead of a fresh mutable
+ * `Uint8Array`.
  *
  * @param {string} hex
  * @param {string} [name]