@agoric/internal 0.4.0-u19.2 → 0.4.0-u21.0

package/src/metrics.js

@@ -0,0 +1,476 @@
+/**
+ * @file Metadata about exported metrics. Note that any embedded unit
+ *   information should be provided as case-sensitive UCUM (e.g., `s` for
+ *   seconds, `ms` for milliseconds, `KiBy` for binary kilobytes [each being
+ *   1024 bytes]).
+ *
+ *   - https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-units
+ *   - https://ucum.org/ucum
+ *   - https://ucum.nlm.nih.gov/ucum-lhc/demo.html
+ *   - https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure
+ */
+
+import { q } from '@endo/errors';
+import { isNat } from '@endo/nat';
+
+/**
+ * @import {Meter as OTelMeter, MetricAttributes} from '@opentelemetry/api';
+ * @import {TotalMap} from '@agoric/internal';
+ */
+
+const HISTOGRAM_MS_LATENCY_BOUNDARIES = [
+  5,
+  10,
+  25,
+  50,
+  100,
+  250,
+  500,
+  1000,
+  2500,
+  5000,
+  10000,
+  Infinity,
+];
+const HISTOGRAM_SECONDS_LATENCY_BOUNDARIES =
+  HISTOGRAM_MS_LATENCY_BOUNDARIES.map(ms => ms / 1000);
+
+// TODO: Validate these boundaries. We're not going to have 5ms blocks, but
+// we probably care about the difference between 10 vs. 30 seconds.
+export const HISTOGRAM_METRICS = /** @type {const} */ ({
+  swingset_crank_processing_time: {
+    description: 'Processing time per crank (ms)',
+    unit: 'ms',
+    boundaries: Array.of(1, 11, 21, 31, 41, 51, 61, 71, 81, 91, Infinity),
+  },
+  swingset_block_processing_seconds: {
+    description: 'Processing time per block',
+    unit: 's',
+    boundaries: HISTOGRAM_SECONDS_LATENCY_BOUNDARIES,
+  },
+  swingset_vat_startup: {
+    description: 'Vat startup time (ms)',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+  swingset_vat_delivery: {
+    description: 'Vat delivery time (ms)',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+  swingset_meter_usage: {
+    description: 'Vat meter usage',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+});
+
+const blockHistogramMetricDesc = {
+  // Disabled because importing from @opentelemetry/api breaks kernel bundling.
+  // Thankfully, it's the default anyway:
+  // https://github.com/open-telemetry/opentelemetry-js/blob/f4dd2a1062f980cd344cfb172a515d00115df570/api/src/metrics/Metric.ts#L53-L57
+  // valueType: ValueType.DOUBLE,
+  unit: 's',
+  advice: {
+    explicitBucketBoundaries: [
+      0.1, 0.2, 0.3, 0.4, 0.5, 1, 2, 3, 4, 5, 6, 7, 10, 15, 30,
+    ],
+  },
+};
+export const BLOCK_HISTOGRAM_METRICS = /** @type {const} */ ({
+  swingsetRunSeconds: {
+    description: 'Per-block time spent executing SwingSet',
+    ...blockHistogramMetricDesc,
+  },
+  swingsetChainSaveSeconds: {
+    description: 'Per-block time spent propagating SwingSet state into cosmos',
+    ...blockHistogramMetricDesc,
+  },
+  swingsetCommitSeconds: {
+    description:
+      'Per-block time spent committing SwingSet state to host storage',
+    ...blockHistogramMetricDesc,
+  },
+  cosmosCommitSeconds: {
+    description: 'Per-block time spent committing cosmos state',
+    ...blockHistogramMetricDesc,
+  },
+  fullCommitSeconds: {
+    description:
+      'Per-block time spent committing state, inclusive of COMMIT_BLOCK processing plus time spent [outside of cosmic-swingset] before and after it',
+    ...blockHistogramMetricDesc,
+  },
+  interBlockSeconds: {
+    description: 'Time spent idle between blocks',
+    ...blockHistogramMetricDesc,
+  },
+  afterCommitHangoverSeconds: {
+    description:
+      'Per-block time spent waiting for previous-block afterCommit work',
+    ...blockHistogramMetricDesc,
+  },
+  blockLagSeconds: {
+    description: 'The delay of each block from its expected begin time',
+    ...blockHistogramMetricDesc,
+    // Add buckets for excessively long delays.
+    advice: {
+      ...blockHistogramMetricDesc.advice,
+      explicitBucketBoundaries: /** @type {number[]} */ ([
+        ...blockHistogramMetricDesc.advice.explicitBucketBoundaries,
+        ...[60, 120, 180, 240, 300, 600, 3600],
+      ]),
+    },
+  },
+});
+
+/** @enum {(typeof QueueMetricAspect)[keyof typeof QueueMetricAspect]} */
+export const QueueMetricAspect = /** @type {const} */ ({
+  Length: 'length',
+  IncrementCount: 'increments',
+  DecrementCount: 'decrements',
+});
+
+/**
+ * Queue metrics come in {length,add,remove} triples sharing a common prefix.
+ *
+ * @param {string} namePrefix
+ * @param {string} descPrefix
+ * @returns {Record<
+ *   QueueMetricAspect,
+ *   { name: string; options: MetricAttributes }
+ * >}
+ */
+export const makeQueueMetricsMeta = (namePrefix, descPrefix) => {
+  /** @type {[QueueMetricAspect, string, string][]} */
+  const metricsMeta = [
+    [QueueMetricAspect.Length, 'length', 'length'],
+    [QueueMetricAspect.IncrementCount, 'add', 'increments'],
+    [QueueMetricAspect.DecrementCount, 'remove', 'decrements'],
+  ];
+  const entries = metricsMeta.map(([aspect, nameSuffix, descSuffix]) => {
+    const name = `${namePrefix}_${nameSuffix}`;
+    const description = `${descPrefix} ${descSuffix}`;
+    // Future OpenTelemetry SDKs should also support creating Instruments with
+    // attribute keys (such as the "queue" attribute for
+    // "cosmic_swingset_inbound_queue_{length,add,remove}" measurements):
+    // https://opentelemetry.io/docs/specs/otel/metrics/api/#instrument-advisory-parameter-attributes
+    // At that time, a new field will be added to this record.
+    return [aspect, { name, options: { description } }];
+  });
+  return Object.fromEntries(entries);
+};
+
+/**
+ * @template {string} QueueName
+ * @typedef QueueMetrics
+ * @property {(lengths: Record<QueueName, number>) => void} initLengths must be
+ *   called before any other function
+ * @property {(lengths: Record<QueueName, number>) => void} updateLengths
+ * @property {(queue: QueueName, delta?: number) => void} incLength for a
+ *   non-negative delta
+ * @property {(queue: QueueName, delta?: number) => void} decLength for a
+ *   non-negative delta
+ */
+
+/**
+ * Create {length,add,remove} Instruments for a queue and return functions for
+ * consistently initializing and updating them.
+ *
+ * @template {string} QueueName
+ * @param {object} config
+ * @param {OTelMeter} config.otelMeter
+ * @param {string} config.namePrefix
+ * @param {string} config.descPrefix
+ * @param {Pick<Console, 'warn'>} [config.console]
+ * @returns {QueueMetrics<QueueName>}
+ */
+export const makeQueueMetrics = ({
+  otelMeter,
+  namePrefix,
+  descPrefix,
+  console,
+}) => {
+  const {
+    [QueueMetricAspect.Length]: lengthMeta,
+    [QueueMetricAspect.IncrementCount]: upMeta,
+    [QueueMetricAspect.DecrementCount]: downMeta,
+  } = makeQueueMetricsMeta(namePrefix, descPrefix);
+  // TODO: When it's deemed safe to change reported metrics, make upCounter and
+  // downCounter synchronous (and drop `increments` and `decrements` maps).
+  // We can't do so until then because it will add a "_total" suffix to the
+  // Prometheus export metric name, diverging from `makeInboundQueueMetrics` in
+  // packages/cosmic-swingset/src/kernel-stats.js.
+  // https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/upgrade-to-2.x.md#-other-changes
+  const lengthCounter = otelMeter.createUpDownCounter(
+    lengthMeta.name,
+    lengthMeta.options,
+  );
+  // const upCounter = otelMeter.createCounter(upMeta.name, upMeta.options);
+  // const downCounter = otelMeter.createCounter(downMeta.name, downMeta.options);
+  const upCounter = otelMeter.createObservableCounter(
+    upMeta.name,
+    upMeta.options,
+  );
+  const downCounter = otelMeter.createObservableCounter(
+    downMeta.name,
+    downMeta.options,
+  );
+  const increments = /** @type {TotalMap<string, number>} */ (new Map());
+  const decrements = /** @type {TotalMap<string, number>} */ (new Map());
+  upCounter.addCallback(observer => {
+    for (const [queueName, value] of increments.entries()) {
+      observer.observe(value, { queue: queueName });
+    }
+  });
+  downCounter.addCallback(observer => {
+    for (const [queueName, value] of decrements.entries()) {
+      observer.observe(value, { queue: queueName });
+    }
+  });
+
+  let ready = false;
+  const lengths = /** @type {TotalMap<string, number>} */ (new Map());
+  const nudge = (queueName, delta, init = false) => {
+    if (!lengths.has(queueName)) {
+      if (!init) console?.warn('Unknown queue', queueName);
+      lengths.set(queueName, 0);
+      increments.set(queueName, 0);
+      decrements.set(queueName, 0);
+    }
+    const oldLength = lengths.get(queueName);
+    lengths.set(queueName, oldLength + delta);
+    const dimensions = { queue: queueName };
+    lengthCounter.add(delta, dimensions);
+    if (init) {
+      return;
+    } else if (delta > 0) {
+      // TODO per above: upCounter.add(delta, dimensions);
+      increments.set(queueName, (increments.get(queueName) || 0) + delta);
+    } else if (delta < 0) {
+      // TODO per above: downCounter.add(-delta, dimensions);
+      decrements.set(queueName, (decrements.get(queueName) || 0) - delta);
+    }
+    ready = true;
+  };
+
+  return harden({
+    initLengths: initialLengths => {
+      !ready ||
+        console?.warn(
+          `Unexpected repeat queue length initialization from ${q(lengths)} to ${q(initialLengths)}`,
+        );
+      for (const [queueName, newLength] of Object.entries(initialLengths)) {
+        if (!isNat(newLength)) {
+          console?.warn(`Invalid length for queue ${q(queueName)}:`, newLength);
+          continue;
+        }
+        nudge(queueName, newLength, true);
+      }
+    },
+    updateLengths: newLengths => {
+      ready || console?.warn('Missing initial queue lengths');
+      for (const [queueName, newLength] of Object.entries(newLengths)) {
+        if (!isNat(newLength)) {
+          console?.warn(`Invalid length for queue ${q(queueName)}:`, newLength);
+          continue;
+        }
+        nudge(queueName, newLength - (lengths.get(queueName) || 0));
+      }
+    },
+    incLength: (queueName, delta = 1) => {
+      if (!isNat(delta)) {
+        console?.warn(`Invalid increment for queue ${q(queueName)}:`, delta);
+        return;
+      }
+      nudge(queueName, delta);
+    },
+    decLength: (queueName, delta = 1) => {
+      if (!isNat(delta)) {
+        console?.warn(`Invalid decrement for queue ${q(queueName)}:`, delta);
+        return;
+      }
+      nudge(queueName, -delta);
+    },
+  });
+};
+
+// All the kernel metrics we are prepared for.
+/** @enum {(typeof MetricType)[keyof typeof MetricType]} MetricType */
+const MetricType = /** @type {const} */ ({
+  Counter: 'counter',
+  Gauge: 'gauge',
+});
+/**
+ * @typedef KernelMetricMeta
+ * @property {string} key
+ * @property {string} name
+ * @property {{ dimension: string; value: string }} [sub]
+ * @property {string} description
+ * @property {boolean} [consensus]
+ * @property {MetricType} metricType
+ */
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_SUM_METRICS = [
+  {
+    key: 'syscalls',
+    name: 'swingset_all_syscall_total',
+    description: 'Total number of SwingSet kernel calls',
+  },
+  {
+    key: 'syscallSend',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'send' },
+    description: 'Total number of SwingSet message send kernel calls',
+  },
+  {
+    key: 'syscallCallNow',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'callNow' },
+    description: 'Total number of SwingSet synchronous device kernel calls',
+  },
+  {
+    key: 'syscallSubscribe',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'subscribe' },
+    description: 'Total number of SwingSet promise subscription kernel calls',
+  },
+  {
+    key: 'syscallResolve',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'resolve' },
+    description: 'Total number of SwingSet promise resolution kernel calls',
+  },
+  {
+    key: 'syscallExit',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'exit' },
+    description: 'Total number of SwingSet vat exit kernel calls',
+  },
+  {
+    key: 'syscallVatstoreGet',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreGet' },
+    description: 'Total number of SwingSet vatstore get kernel calls',
+  },
+  {
+    key: 'syscallVatstoreSet',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreSet' },
+    description: 'Total number of SwingSet vatstore set kernel calls',
+  },
+  {
+    key: 'syscallVatstoreGetNextKey',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreGetNext' },
+    description: 'Total number of SwingSet vatstore getNextKey kernel calls',
+  },
+  {
+    key: 'syscallVatstoreDelete',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreDelete' },
+    description: 'Total number of SwingSet vatstore delete kernel calls',
+  },
+  {
+    key: 'syscallDropImports',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'dropImports' },
+    description: 'Total number of SwingSet drop imports kernel calls',
+  },
+  {
+    key: 'dispatches',
+    name: 'swingset_dispatch_total',
+    description: 'Total number of SwingSet vat calls',
+  },
+  {
+    key: 'dispatchDeliver',
+    name: 'swingset_dispatch_deliver_total',
+    description: 'Total number of SwingSet vat message deliveries',
+  },
+  {
+    key: 'dispatchNotify',
+    name: 'swingset_dispatch_notify_total',
+    description: 'Total number of SwingSet vat promise notifications',
+  },
+];
+
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_UPDOWN_METRICS = [
+  {
+    key: 'kernelObjects',
+    name: 'swingset_kernel_objects',
+    description: 'Active kernel objects',
+  },
+  {
+    key: 'kernelDevices',
+    name: 'swingset_kernel_devices',
+    description: 'Active kernel devices',
+  },
+  {
+    key: 'kernelPromises',
+    name: 'swingset_kernel_promises',
+    description: 'Active kernel promises',
+  },
+  {
+    key: 'kpUnresolved',
+    name: 'swingset_unresolved_kernel_promises',
+    description: 'Unresolved kernel promises',
+  },
+  {
+    key: 'kpFulfilled',
+    name: 'swingset_fulfilled_kernel_promises',
+    description: 'Fulfilled kernel promises',
+  },
+  {
+    key: 'kpRejected',
+    name: 'swingset_rejected_kernel_promises',
+    description: 'Rejected kernel promises',
+  },
+  {
+    key: 'runQueueLength',
+    name: 'swingset_run_queue_length',
+    consensus: true,
+    description: 'Length of the kernel run queue',
+  },
+  {
+    key: 'acceptanceQueueLength',
+    name: 'swingset_acceptance_queue_length',
+    consensus: true,
+    description: 'Length of the kernel acceptance queue',
+  },
+  {
+    key: 'promiseQueuesLength',
+    name: 'swingset_promise_queues_length',
+    consensus: true,
+    description: 'Combined length of all kernel promise queues',
+  },
+  {
+    key: 'clistEntries',
+    name: 'swingset_clist_entries',
+    description: 'Number of entries in the kernel c-list',
+  },
+  {
+    key: 'vats',
+    name: 'swingset_vats',
+    description: 'Number of active vats',
+  },
+];
+
+const { Counter, Gauge } = MetricType;
+/** @type {KernelMetricMeta[]} */
+export const KERNEL_STATS_METRICS = harden([
+  ...KERNEL_STATS_SUM_METRICS.map(m => ({ ...m, metricType: Counter })),
+  ...KERNEL_STATS_UPDOWN_METRICS.map(m => ({ ...m, metricType: Gauge })),
+]);
+
+// Ensure kernel stats key uniqueness.
+const kernelStatsKeys = new Map();
+for (const { key } of KERNEL_STATS_METRICS) {
+  kernelStatsKeys.set(key, (kernelStatsKeys.get(key) || 0) + 1);
+}
+const duplicateKernelStatsKeys = [...kernelStatsKeys.entries()].flatMap(
+  ([key, value]) => (value > 1 ? [key] : []),
+);
+if (duplicateKernelStatsKeys.length > 0) {
+  const msg = `Duplicate kernel stats keys ${JSON.stringify(duplicateKernelStatsKeys)}`;
+  throw Error(msg);
+}

package/src/module-utils.d.ts

@@ -0,0 +1,2 @@
+export function getSpecifier(fileUrl: string): Promise<string>;
+//# sourceMappingURL=module-utils.d.ts.map

package/src/module-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-utils.d.ts","sourceRoot":"","sources":["module-utils.js"],"names":[],"mappings":"AAaO,sCAHI,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAc3B"}

package/src/module-utils.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { search } from '@endo/compartment-mapper';
+import { Fail } from '@endo/errors';
+
+/**
+ * Given a file URL, return a deep import specifier that starts with the
+ * specifier for its containing module (e.g., the deep import specifier for this
+ * file is expected to be "@agoric/internal/src/module-utils.js").
+ *
+ * @param {string} fileUrl
+ * @returns {Promise<string>}
+ */
+export const getSpecifier = async fileUrl => {
+  // eslint-disable-next-line no-new
+  new URL(fileUrl); // validates fileUrl
+  const read = async location => {
+    const path = fileURLToPath(new URL(location, fileUrl));
+    return readFile(path);
+  };
+  const searchResult = await search(read, fileUrl);
+  const { packageDescriptorText, moduleSpecifier } = searchResult;
+  const { name } = JSON.parse(packageDescriptorText);
+  name || Fail`containing package must have a name`;
+  return `${name}/${moduleSpecifier.replace(/^\.\//, '')}`;
+};
+harden(getSpecifier);

package/src/ses-utils.d.ts

@@ -34,6 +34,7 @@ export function PromiseAllOrErrors<T>(items: readonly (T | PromiseLike<T>)[]): P
 export function aggregateTryFinally<T>(trier: () => Promise<T>, finalizer: (error?: unknown) => Promise<unknown>): ReturnType<() => Promise<T>>;
 export function withDeferredCleanup<T>(fn: (addCleanup: (fn: (err?: unknown) => Promise<void>) => void) => Promise<T>): ReturnType<(addCleanup: (fn: (err?: unknown) => Promise<void>) => void) => Promise<T>>;
 export function assertAllDefined<T extends Record<string, unknown>>(obj: T): asserts obj is AllDefined<T>;
+export function attenuate<T, P extends Permit<T>>(specimen: T, permit: P, transform?: <U, SubP extends Permit<U>>(attenuation: U, permit: SubP) => U): Attenuated<T, P>;
 export const forever: AsyncIterable<undefined>;
 export function whileTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
 export function untilTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
@@ -56,6 +57,12 @@ export type Callable = (...args: any[]) => any;
 export type DeeplyAwaitedObject<T extends {}> = { [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]>; };
 export type DeeplyAwaited<T> = T extends PromiseLike<any> ? Awaited<T> : T extends {} ? Simplify<DeeplyAwaitedObject<T>> : Awaited<T>;
 export type AllDefined<T extends Record<string, unknown>> = { [P in keyof T]: Exclude<T[P], undefined>; };
+import { objectMap } from '@endo/common/object-map.js';
+import { objectMetaMap } from '@endo/common/object-meta-map.js';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
 import type { LimitedConsole } from './js-utils.js';
+import type { Permit } from './types.js';
+import type { Attenuated } from './types.js';
 import type { ERef } from '@endo/far';
+export { objectMap, objectMetaMap, fromUniqueEntries };
 //# sourceMappingURL=ses-utils.d.ts.map

package/src/ses-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ses-utils.d.ts","sourceRoot":"","sources":["ses-utils.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ses-utils.d.ts","sourceRoot":"","sources":["ses-utils.js"],"names":[],"mappings":"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"}

package/src/ses-utils.js

@@ -5,18 +5,27 @@
  *   either directly or indirectly (e.g. by @endo imports).
  */
 
+import { objectMap } from '@endo/common/object-map.js';
+import { objectMetaMap } from '@endo/common/object-meta-map.js';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
 import { q, Fail, makeError, annotateError, X } from '@endo/errors';
 import { deeplyFulfilled, isObject } from '@endo/marshal';
 import { makePromiseKit } from '@endo/promise-kit';
 import { makeQueue } from '@endo/stream';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore TS7016 The 'jessie.js' library may need to update its package.json or typings
 import { asyncGenerate } from 'jessie.js';
 import { logLevels } from './js-utils.js';
 
 /** @import {LimitedConsole} from './js-utils.js'; */
 
-const { fromEntries, keys, values } = Object;
+/** @import {ERef} from '@endo/far'; */
+/** @import {Primitive} from '@endo/pass-style'; */
+/** @import {Permit, Attenuated} from './types.js'; */
+
+export { objectMap, objectMetaMap, fromUniqueEntries };
 
-/** @import {ERef} from '@endo/far' */
+const { fromEntries, keys, values } = Object;
 
 /** @param {(level: string) => (...args: unknown[]) => void} makeLogger */
 export const makeLimitedConsole = makeLogger => {
@@ -175,6 +184,61 @@ export const assertAllDefined = obj => {
   }
 };
 
+/**
+ * Attenuate `specimen` to only properties allowed by `permit`.
+ *
+ * @template T
+ * @template {Permit<T>} P
+ * @param {T} specimen
+ * @param {P} permit
+ * @param {<U, SubP extends Permit<U>>(attenuation: U, permit: SubP) => U} [transform]
+ *   used to replace the results of recursive picks (but not blanket permits)
+ * @returns {Attenuated<T, P>}
+ */
+export const attenuate = (specimen, permit, transform = x => x) => {
+  // Fast-path for no attenuation.
+  if (permit === true || typeof permit === 'string') {
+    return /** @type {Attenuated<T, P>} */ (specimen);
+  }
+
+  /** @type {string[]} */
+  const path = [];
+  /**
+   * @template SubT
+   * @template {Exclude<Permit<SubT>, Primitive>} SubP
+   * @type {(specimen: SubT, permit: SubP) => Attenuated<SubT, SubP>}
+   */
+  const extract = (subSpecimen, subPermit) => {
+    if (subPermit === null || typeof subPermit !== 'object') {
+      throw path.length === 0
+        ? Fail`invalid permit: ${q(permit)}`
+        : Fail`invalid permit at path ${q(path)}: ${q(subPermit)}`;
+    } else if (subSpecimen === null || typeof subSpecimen !== 'object') {
+      throw path.length === 0
+        ? Fail`specimen must be an object for permit ${q(permit)}`
+        : Fail`specimen at path ${q(path)} must be an object for permit ${q(subPermit)}`;
+    }
+    const picks = Object.entries(subPermit).map(([subKey, deepPermit]) => {
+      if (!Object.hasOwn(subSpecimen, subKey)) {
+        throw Fail`specimen is missing path ${q(path.concat(subKey))}`;
+      }
+      const deepSpecimen = Reflect.get(subSpecimen, subKey);
+      if (deepPermit === true || typeof deepPermit === 'string') {
+        return [subKey, deepSpecimen];
+      }
+      path.push(subKey);
+      const extracted = extract(/** @type {any} */ (deepSpecimen), deepPermit);
+      const entry = [subKey, extracted];
+      path.pop();
+      return entry;
+    });
+    return transform(Object.fromEntries(picks), subPermit);
+  };
+
+  // @ts-expect-error cast
+  return extract(specimen, permit);
+};
+
 /** @type {IteratorResult<undefined, never>} */
 const notDone = harden({ done: false, value: undefined });
 

package/src/storage-test-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAyBO,yCAHI,MAAM,UACN,MAAM,6GAGC;AAElB;;;GAGG;AACH;;;;;EAEG;;eAMU,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO;mBAEzB,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM;;AA8CjC,8CAtBuB,GAAG,KAAK,GAAG,CAsB+B;AAU1D,6CAHI,MAAM,gBACN,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC;;;;;oBA+Fb,CAAC;;;;UAgDpB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;;sBAd3B,MAAM,KACJ,MAAM,EAAE;;0BA9FP,cAAc;;;8IAAd,cAAc;;;;EAiH7B;AAoBM,4CADO,oBAAoB,CA6BjC;AAUM,yCAPI,OAAO,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,WACvC,oBAAoB,GAAG,cAAc,QACrC,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,CAAK;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,EAAE,CAAC,GAAG;IAChD,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC,iBAkDL;6BAxGa,UAAU,CAAC,OAAO,kBAAkB,CAAC;;;;;;;;aAIrC,CACT,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,UAAU,EACvB,KAAK,CAAC,EAAE,MAAM,KACX,OAAO;UAKD,MAAM,MAAM,EAAE;;mCAEd,WAAW,GAAG,2BAA2B;qCAhQJ,uBAAuB;iCAOU,uBAAuB;oCAAvB,uBAAuB;gCAAvB,uBAAuB"}
+{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAyBO,yCAHI,MAAM,UACN,MAAM,6GAGC;AAElB;;;GAGG;AACH;;;;;EAEG;;eAMU,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO;mBAEzB,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM;;AA8CjC,8CAtBuB,GAAG,KAAK,GAAG,CAsB+B;AAU1D,6CAHI,MAAM,gBACN,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC;;;;;oBAuFhB,CAAC;;;;UAwDjB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;;sBAd3B,MAAM,KACJ,MAAM,EAAE;;0BA9FP,cAAc;;;8IAAd,cAAc;;;;EAiH7B;AAoBM,4CADO,oBAAoB,CA6BjC;AAUM,yCAPI,OAAO,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,WACvC,oBAAoB,GAAG,cAAc,QACrC,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,CAAK;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,EAAE,CAAC,GAAG;IAChD,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC,iBAkDL;6BAxGa,UAAU,CAAC,OAAO,kBAAkB,CAAC;;;;;;;;aAIrC,CACT,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,UAAU,EACvB,KAAK,CAAC,EAAE,MAAM,KACX,OAAO;UAKD,MAAM,MAAM,EAAE;;mCAEd,WAAW,GAAG,2BAA2B;qCAhQJ,uBAAuB;iCAOU,uBAAuB;oCAAvB,uBAAuB;gCAAvB,uBAAuB"}

package/src/tmpDir.d.ts

@@ -0,0 +1,2 @@
+export function makeTempDirFactory(tmp: Pick<typeof import("tmp"), "dirSync">): (prefix?: string) => [dirName: string, cleanup: () => void];
+//# sourceMappingURL=tmpDir.d.ts.map

package/src/tmpDir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmpDir.d.ts","sourceRoot":"","sources":["tmpDir.js"],"names":[],"mappings":"AAMO,wCAFI,IAAI,CAAC,oBAAa,EAAE,SAAS,CAAC,aAGlB,MAAM,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,CASvE"}

package/src/tmpDir.js

@@ -0,0 +1,17 @@
+/**
+ * Create a `tmpDir` function that synchronously creates a temporary directory
+ * and a function for deleting it along with any added contents.
+ *
+ * @param {Pick<import('tmp'), 'dirSync'>} tmp
+ */
+export const makeTempDirFactory = tmp => {
+  /** @type {(prefix?: string) => [dirName: string, cleanup: () => void]} */
+  const tmpDir = prefix => {
+    const { name, removeCallback } = tmp.dirSync({
+      prefix,
+      unsafeCleanup: true,
+    });
+    return [name, removeCallback];
+  };
+  return tmpDir;
+};