test(ocap-kernel): pin each refcount audit credit source to a literal

The clean-audit cases prove each rule agrees with whatever the store did,
which stays true if a rule and the code it mirrors are wrong by the same
constant. Six of eight rules could have drifted and the suite would have
stayed green.

Each of the ten credit sources now pins its count and holder labels to
literals and asserts drift in both directions: too low collects a live
capability, too high leaks it. That closes the two coverage gaps as a side
effect — a run-queue send's result promise, and a message parked on an
unresolved promise, neither of which any test reached.

Also states what the audit can and cannot find, which matters because its
ground truth *is* the holder set: a count that disagrees with its holders
is caught either way, but a holder that should have been torn down and
wasn't justifies its own count at any value, so a leaked reference is
invisible to it by construction. That is exactly the case the retained
settled-promise c-list entry leaves behind, so the CHANGELOG no longer
claims the audit would catch it.

The `auditRefCounts` JSDoc no longer scopes the option as "intended for
tests and debugging": it stands in for the invariant `collectGarbage`
cannot assert, and is off by default only because it walks the whole store.

`kernel-test`'s audit test asserts both hops of the failure now. #1005
changed the shape: callers are told the run loop died and the audit error
rides along as the `cause`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/kernel-test/src/refcount-audit.test.ts

@@ -48,8 +48,16 @@ describe('reference count audit', () => {
       .queueMessage(exporterKRef, 'createObject', ['x'])
       .catch(() => undefined);
 
-    await expect(
-      kernel.queueMessage(exporterKRef, 'createObject', ['y']),
-    ).rejects.toThrow(/reference count invariant violated/u);
+    // What a caller is told directly is that the run loop is gone; the audit
+    // failure that killed it rides along as the `cause`. That chain is the part
+    // that has to survive, since "run loop died" on its own names nothing.
+    const failure = (await kernel
+      .queueMessage(exporterKRef, 'createObject', ['y'])
+      .catch((error) => error)) as Error;
+
+    expect(failure.message).toMatch(/Kernel run loop died/u);
+    expect(String(failure.cause)).toMatch(
+      /reference count invariant violated/u,
+    );
   }, 30000);
 });

packages/ocap-kernel/CHANGELOG.md

@@ -34,7 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Caveat: a legitimate string argument that begins with `@@` followed by alphanumerics will be misinterpreted as a marker; wrap such literals inside an object
 
 - Reference-count auditing: `auditRefCounts`, `recomputeRefCounts`, `formatRefCountViolations`, `assertRefCountsIfAuditing`, and `setRefCountAuditing` on the kernel store, plus a `Kernel.make` option `auditRefCounts` that verifies every kref's counts against the references the kernel actually holds at the end of each crank ([#1010](https://github.com/MetaMask/ocap-kernel/pull/1010))
-  - Reports drift in both directions: counts too low (a live capability can be collected) and counts too high with no holder (a leak)
+  - Reports drift in both directions: counts too low (a live capability can be collected) and counts too high with no holder (an orphaned count). It compares counts against the holders it finds, so a holder that should have been torn down but wasn't justifies its own count and is not detectable this way
   - Exports the `RefCountViolation` type, a union over `kind: 'mismatch' | 'dangling'`
 - Add `setReachableFlag` to the kernel store, the counterpart to `clearReachableFlag` ([#1010](https://github.com/MetaMask/ocap-kernel/pull/1010))
 - Add `orphanKernelObject` to the kernel store, which drops an object's owner mapping and hands it to the collector ([#1010](https://github.com/MetaMask/ocap-kernel/pull/1010))

packages/ocap-kernel/src/Kernel.ts

@@ -110,8 +110,12 @@ export class Kernel {
    * @param options.allowedGlobalNames - Optional list of allowed global names for vat endowments.
    * @param options.auditRefCounts - If true, verify every kref's reference
    * counts against the references the kernel actually holds at the end of each
-   * crank, and throw on any mismatch. Intended for tests and debugging; the
-   * audit walks the whole store.
+   * crank, and throw on any mismatch. This is the check standing in for the
+   * accounting invariant `collectGarbage` still cannot assert (see the comment
+   * on its `retireExport` branch), so it is not optional
+   * instrumentation: it is off by default only because it walks the whole store
+   * every crank. Any kernel whose accounting is under test wants it on, and
+   * every kernel `kernel-test` builds enables it.
    * @param options.onRunLoopFailure - Optional handler called if the run loop dies.
    */
   // eslint-disable-next-line no-restricted-syntax

packages/ocap-kernel/src/store/methods/refcount-audit.test.ts

@@ -1,3 +1,4 @@
+import type { KernelDatabase } from '@metamask/kernel-store';
 import { describe, it, expect, beforeEach } from 'vitest';
 
 import { makeMapKernelDatabase } from '../../../test/storage.ts';
@@ -6,6 +7,7 @@ import { makeKernelStore } from '../index.ts';
 
 describe('reference count audit', () => {
   let kernelStore: ReturnType<typeof makeKernelStore>;
+  let kdb: KernelDatabase;
 
   /**
    * Register and initialize an endpoint so it can hold c-list entries.
@@ -19,8 +21,35 @@ describe('reference count audit', () => {
     }
   }
 
+  /**
+   * Overwrite a kref's stored count, going around the store's own arithmetic so
+   * that drift can be introduced in either direction regardless of what the
+   * current count happens to be.
+   *
+   * @param kref - The kref whose count to overwrite.
+   * @param counts - The count text, in the store's encoding.
+   */
+  function setStoredCount(kref: KRef, counts: string): void {
+    kdb.kernelKVStore.set(`${kref}.refCount`, counts);
+  }
+
+  /**
+   * Shift every component of a count by the same amount.
+   *
+   * @param counts - The count text, in the store's encoding.
+   * @param delta - How far to shift each component.
+   * @returns The shifted count text.
+   */
+  function shift(counts: string, delta: number): string {
+    return counts
+      .split(',')
+      .map((part) => `${Number(part) + delta}`)
+      .join(',');
+  }
+
   beforeEach(() => {
-    kernelStore = makeKernelStore(makeMapKernelDatabase());
+    kdb = makeMapKernelDatabase();
+    kernelStore = makeKernelStore(kdb);
     kernelStore.markInitialized();
     givenVats('v1', 'v2', 'v3');
   });
@@ -172,6 +201,166 @@ describe('reference count audit', () => {
     });
   });
 
+  // The clean-audit cases above prove each rule agrees with whatever the store
+  // did, which stays true if a rule and the code it mirrors are wrong by the
+  // same constant. These pin each credit source to a literal count and holder
+  // label, and check drift in both directions: too low collects a live
+  // capability, too high leaks it.
+  describe('each credit source, on its own', () => {
+    const sources: {
+      what: string;
+      hold: () => KRef;
+      expected: string;
+      holders: string[];
+    }[] = [
+      {
+        what: 'an object import a vat still reaches',
+        hold: () => {
+          const kref = kernelStore.exportFromEndpoint('v1', 'o+1');
+          kernelStore.translateRefKtoE('v2', kref, true);
+          return kref;
+        },
+        expected: '1,1',
+        holders: ['v2 c-list import o-1'],
+      },
+      {
+        what: 'an object import a vat has dropped but not retired',
+        hold: () => {
+          const kref = kernelStore.exportFromEndpoint('v1', 'o+1');
+          kernelStore.translateRefKtoE('v2', kref, true);
+          kernelStore.clearReachableFlag('v2', kref);
+          return kref;
+        },
+        expected: '0,1',
+        holders: ['v2 c-list import o-1'],
+      },
+      {
+        what: 'a pinned object',
+        hold: () => {
+          const kref = kernelStore.exportFromEndpoint('v1', 'o+1');
+          kernelStore.pinObject(kref);
+          return kref;
+        },
+        expected: '1,1',
+        holders: ['pin'],
+      },
+      {
+        what: "a run-queue send's target and slot",
+        hold: () => {
+          const kref = kernelStore.exportFromEndpoint('v1', 'o+1');
+          kernelStore.enqueueRun({
+            type: 'send',
+            target: kref,
+            message: { methargs: { body: '#[]', slots: [kref] }, result: null },
+          });
+          kernelStore.incrementRefCount(kref, 'queue|target');
+          kernelStore.incrementRefCount(kref, 'queue|slot');
+          return kref;
+        },
+        expected: '2,2',
+        holders: ['run queue #1 send target', 'run queue #1 send slot'],
+      },
+      {
+        what: "a run-queue send's result promise",
+        hold: () => {
+          const target = kernelStore.exportFromEndpoint('v1', 'o+1');
+          const kpid = kernelStore.initKernelPromise()[0];
+          kernelStore.enqueueRun({
+            type: 'send',
+            target,
+            message: { methargs: { body: '#[]', slots: [] }, result: kpid },
+          });
+          kernelStore.incrementRefCount(target, 'queue|target');
+          kernelStore.incrementRefCount(kpid, 'queue|result');
+          return kpid;
+        },
+        expected: '2',
+        holders: ['unsettled promise', 'run queue #1 send result'],
+      },
+      {
+        what: 'a queued notification',
+        hold: () => {
+          const kpid = kernelStore.exportFromEndpoint('v1', 'p+1');
+          kernelStore.enqueueRun({ type: 'notify', endpointId: 'v2', kpid });
+          kernelStore.incrementRefCount(kpid, 'notify');
+          return kpid;
+        },
+        expected: '3',
+        holders: [
+          'unsettled promise',
+          'run queue #1 notify',
+          'v1 c-list export p+1',
+        ],
+      },
+      {
+        // `enqueuePromiseMessage` takes the references itself, which is the
+        // point of the transfer-don't-duplicate fix; incrementing here too
+        // would be the double-count it exists to prevent.
+        what: 'a message parked on an unresolved promise',
+        hold: () => {
+          const target = kernelStore.exportFromEndpoint('v1', 'o+1');
+          const kpid = kernelStore.initKernelPromise()[0];
+          kernelStore.enqueuePromiseMessage(kpid, {
+            methargs: { body: '#[]', slots: [target] },
+            result: null,
+          });
+          return kpid;
+        },
+        expected: '2',
+        holders: ['unsettled promise', 'kp1 queue #1 target'],
+      },
+      {
+        what: 'a promise nobody has settled yet',
+        hold: () => kernelStore.initKernelPromise()[0],
+        expected: '1',
+        holders: ['unsettled promise'],
+      },
+      {
+        what: "a settled promise's resolution slot",
+        hold: () => {
+          const koid = kernelStore.exportFromEndpoint('v1', 'o+1');
+          const kpid = kernelStore.exportFromEndpoint('v1', 'p+1');
+          kernelStore.incrementRefCount(koid, 'resolve|slot');
+          kernelStore.resolveKernelPromise(kpid, false, {
+            body: '#"$0"',
+            slots: [koid],
+          });
+          return koid;
+        },
+        expected: '1,1',
+        holders: ['kp1 resolution slot'],
+      },
+      {
+        what: "a promise's own c-list entries",
+        hold: () => {
+          const kpid = kernelStore.exportFromEndpoint('v1', 'p+1');
+          kernelStore.translateRefKtoE('v2', kpid, true);
+          return kpid;
+        },
+        expected: '3',
+        holders: [
+          'unsettled promise',
+          'v1 c-list export p+1',
+          'v2 c-list import p-1',
+        ],
+      },
+    ];
+
+    it.each(sources)('credits $what exactly', ({ hold, expected, holders }) => {
+      const kref = hold();
+
+      expect(kernelStore.auditRefCounts()).toStrictEqual([]);
+
+      for (const delta of [1, -1]) {
+        const stored = shift(expected, delta);
+        setStoredCount(kref, stored);
+        expect(kernelStore.auditRefCounts()).toStrictEqual([
+          { kind: 'mismatch', kref, stored, expected, holders },
+        ]);
+      }
+    });
+  });
+
   describe('assertRefCountsIfAuditing', () => {
     it('does nothing while auditing is off', () => {
       const kref = kernelStore.exportFromEndpoint('v1', 'o+1');

packages/ocap-kernel/src/store/methods/refcount-audit.ts

@@ -256,6 +256,15 @@ export function getRefCountAuditMethods(ctx: StoreContext) {
    * Compare every kref's stored reference counts against the references the
    * kernel can be seen to hold.
    *
+   * What this can and cannot find is worth being precise about, because the
+   * ground truth here *is* the holder set. A count that disagrees with its
+   * holders is caught in either direction: too low, and a live capability can be
+   * collected; too high with no holder left, and the count itself is orphaned.
+   * But a holder that should have been torn down and wasn't justifies its own
+   * count — at any value — so a leaked *reference* is invisible to this by
+   * construction. A c-list entry that outlives what it names is the case that
+   * matters: see the settled-promise TODO in `KernelRouter`.
+   *
    * @returns The krefs whose counts disagree with ground truth, in kref order.
    */
   function auditRefCounts(): RefCountViolation[] {