feat(service-matcher): dedup re-registrations by (peerId, providerTag)

Author: FUDCo

packages/sample-services/src/echo-service/index.ts

@@ -56,6 +56,7 @@ export function buildRootObject(
         remotableSpec,
         getContactUrl: () => contactUrl,
         expectedToken: registrationToken,
+        providerTag: 'echo',
       });
       contactUrl = await E(services.ocapURLIssuerService).issue(contact);
 

packages/sample-services/src/random-number-service/index.ts

@@ -59,6 +59,7 @@ export function buildRootObject(
         remotableSpec,
         getContactUrl: () => contactUrl,
         expectedToken: registrationToken,
+        providerTag: 'random-number',
       });
       contactUrl = await E(services.ocapURLIssuerService).issue(contact);
 

packages/sample-services/src/vat-lib/contact-endpoint.ts

@@ -33,6 +33,11 @@ import type {
  * `ocapURLIssuerService.issue(...)` resolves.
  * @param options.expectedToken - The registration token the matcher must
  * present to validate registration.
+ * @param options.providerTag - The provider-local identifier for the
+ * service. Must be unique among services hosted by this provider and
+ * must persist across restarts of the same logical service; the matcher
+ * uses (peerId, providerTag) as the dedup key when re-registrations
+ * arrive.
  * @returns A ContactPoint exo.
  */
 export function makeContactEndpoint(options: {
@@ -42,6 +47,7 @@ export function makeContactEndpoint(options: {
   remotableSpec: RemotableSpec;
   getContactUrl: () => string;
   expectedToken: string;
+  providerTag: string;
 }): ContactPoint {
   const {
     name,
@@ -50,6 +56,7 @@ export function makeContactEndpoint(options: {
     remotableSpec,
     getContactUrl,
     expectedToken,
+    providerTag,
   } = options;
   let consumed = false;
 
@@ -72,6 +79,7 @@ export function makeContactEndpoint(options: {
         }),
         description,
         contact: harden(contact),
+        providerTag,
       });
     },
 

packages/service-discovery-types/docs/design.md

@@ -113,6 +113,7 @@ const description: ServiceDescription = {
   description:
     'A capability that lists wallet accounts and signs personal messages.',
   contact: [{ contactType: 'public', contactUrl }],
+  providerTag: 'personal-message-signer',
 };
 ```
 

packages/service-discovery-types/src/index.test.ts

@@ -67,6 +67,7 @@ describe('ServiceDescriptionStruct', () => {
       apiSpec: { properties: {} },
       description: 'a service',
       contact: [{ contactType: 'public', contactUrl: 'ocap:abc@peer' }],
+      providerTag: 'svc',
     };
     expect(is(desc, ServiceDescriptionStruct)).toBe(true);
   });
@@ -80,6 +81,7 @@ describe('ServiceDescriptionStruct', () => {
         { contactType: 'permissioned', contactUrl: 'ocap:b@peer' },
         { contactType: 'validatedClient', contactUrl: 'ocap:c@peer' },
       ],
+      providerTag: 'svc',
     };
     expect(is(desc, ServiceDescriptionStruct)).toBe(true);
   });
@@ -89,6 +91,7 @@ describe('ServiceDescriptionStruct', () => {
       apiSpec: { properties: {} },
       description: 'a service',
       contact: [{ contactType: 'guest', contactUrl: 'ocap:a@peer' }],
+      providerTag: 'svc',
     };
     expect(is(bad, ServiceDescriptionStruct)).toBe(false);
   });
@@ -97,6 +100,16 @@ describe('ServiceDescriptionStruct', () => {
     const bad = {
       apiSpec: { properties: {} },
       contact: [{ contactType: 'public', contactUrl: 'ocap:a@peer' }],
+      providerTag: 'svc',
+    };
+    expect(is(bad, ServiceDescriptionStruct)).toBe(false);
+  });
+
+  it('rejects a missing providerTag', () => {
+    const bad = {
+      apiSpec: { properties: {} },
+      description: 'a service',
+      contact: [{ contactType: 'public', contactUrl: 'ocap:a@peer' }],
     };
     expect(is(bad, ServiceDescriptionStruct)).toBe(false);
   });
@@ -125,6 +138,7 @@ describe('ServiceMatchListStruct', () => {
         apiSpec: { properties: {} },
         description: 'svc',
         contact: [{ contactType: 'public' as const, contactUrl: 'ocap:a@p' }],
+        providerTag: 'svc',
       },
       rationale: 'matches "sign" semantics',
     };

packages/service-discovery-types/src/service-description.ts

@@ -120,11 +120,23 @@ export type ServiceContactInfo = {
 
 /**
  * The full JSON-serializable description of a service.
+ *
+ * `providerTag` is a stable identifier that the provider assigns to each
+ * service it hosts. It must be unique among services hosted by the same
+ * provider (same kernel, same libp2p peer ID) and must persist across
+ * restarts of that service — when a provider re-registers after a kernel
+ * restart, the matcher uses the (peerId, providerTag) pair to recognize
+ * the new registration as a replacement for the previous one and evict
+ * the now-stale entry. Tags don't need to be globally unique: two
+ * unrelated providers can both use `providerTag: 'main'` without
+ * collision because their peer IDs differ. Conventional shape is a short
+ * lowercase kebab-case slug naming the service.
  */
 export type ServiceDescription = {
   apiSpec: ObjectSpec;
   description: string;
   contact: ServiceContactInfo[];
+  providerTag: string;
 };
 
 // ---------------------------------------------------------------------------
@@ -207,6 +219,7 @@ export const ServiceDescriptionStruct: Struct<ServiceDescription> = object({
   apiSpec: ObjectSpecStruct,
   description: string(),
   contact: array(ServiceContactInfoStruct),
+  providerTag: string(),
 });
 
 // Compile-time assertions that the hand-written types line up with the

packages/service-matcher/src/matcher-vat/index.test.ts

@@ -27,10 +27,12 @@ type Services = {
 const sampleDescription = (
   name = 'Signer',
   contactUrl = 'ocap:abc@peer',
+  providerTag = name.toLowerCase(),
 ): ServiceDescription => ({
   apiSpec: { properties: {} },
   description: `A service called ${name}`,
   contact: [{ contactType: 'public', contactUrl }],
+  providerTag,
 });
 
 /**
@@ -420,6 +422,7 @@ describe('matcher vat', () => {
         apiSpec: { properties: {} },
         description: 'no contact',
         contact: [],
+        providerTag: 'lonely',
       };
 
       await expect(
@@ -428,6 +431,95 @@ describe('matcher vat', () => {
     });
   });
 
+  describe('same-peer same-tag dedup', () => {
+    it('evicts the previous registration when (peer, tag) matches', async () => {
+      await root.bootstrap({}, mocks.services);
+      const publicFacet = root.getPublicFacet();
+
+      // First registration: peerA + tag=signer
+      const description1 = sampleDescription(
+        'Signer',
+        'ocap:key1@peerA',
+        'signer',
+      );
+      const contactA = makeMockContact({
+        description: description1,
+        expectedToken: 'tok-A',
+      });
+      mocks.redeem.mockResolvedValueOnce(contactA.contact);
+      await publicFacet.registerService(description1, 'tok-A');
+      expect(root.listAll()).toHaveLength(1);
+
+      // Second registration: same peerA + same tag=signer (simulates the
+      // same logical provider re-registering after a kernel restart with a
+      // fresh contact endpoint).
+      const description2 = sampleDescription(
+        'Signer',
+        'ocap:key2@peerA',
+        'signer',
+      );
+      const contactB = makeMockContact({
+        description: description2,
+        expectedToken: 'tok-B',
+      });
+      mocks.redeem.mockResolvedValueOnce(contactB.contact);
+      await publicFacet.registerService(description2, 'tok-B');
+
+      // Only the most recent (peerA, signer) registration survives.
+      const all = root.listAll();
+      expect(all).toHaveLength(1);
+      expect(all[0]?.description.contact[0]?.contactUrl).toBe(
+        'ocap:key2@peerA',
+      );
+    });
+
+    it('keeps both when same peer registers different tags', async () => {
+      await root.bootstrap({}, mocks.services);
+      const publicFacet = root.getPublicFacet();
+
+      const echo = sampleDescription('Echo', 'ocap:k1@peerA', 'echo');
+      const echoContact = makeMockContact({
+        description: echo,
+        expectedToken: 'tok-A',
+      });
+      mocks.redeem.mockResolvedValueOnce(echoContact.contact);
+      await publicFacet.registerService(echo, 'tok-A');
+
+      const random = sampleDescription('Random', 'ocap:k2@peerA', 'random');
+      const randomContact = makeMockContact({
+        description: random,
+        expectedToken: 'tok-B',
+      });
+      mocks.redeem.mockResolvedValueOnce(randomContact.contact);
+      await publicFacet.registerService(random, 'tok-B');
+
+      expect(root.listAll()).toHaveLength(2);
+    });
+
+    it('keeps both when different peers share a tag', async () => {
+      await root.bootstrap({}, mocks.services);
+      const publicFacet = root.getPublicFacet();
+
+      const fromA = sampleDescription('Signer', 'ocap:k1@peerA', 'signer');
+      const contactA = makeMockContact({
+        description: fromA,
+        expectedToken: 'tok-A',
+      });
+      mocks.redeem.mockResolvedValueOnce(contactA.contact);
+      await publicFacet.registerService(fromA, 'tok-A');
+
+      const fromB = sampleDescription('Signer', 'ocap:k2@peerB', 'signer');
+      const contactB = makeMockContact({
+        description: fromB,
+        expectedToken: 'tok-B',
+      });
+      mocks.redeem.mockResolvedValueOnce(contactB.contact);
+      await publicFacet.registerService(fromB, 'tok-B');
+
+      expect(root.listAll()).toHaveLength(2);
+    });
+  });
+
   describe('findServices', () => {
     it('asks the bridge and returns whatever services it cites', async () => {
       const llm = makeMockLlm({

packages/service-matcher/src/matcher-vat/index.ts

@@ -369,6 +369,59 @@ export function buildRootObject(
     return reply.matches;
   }
 
+  /**
+   * Extract the peer ID portion of an OCAP URL.
+   *
+   * The URL grammar is `ocap:<oid>@<peerId>[,<relayHint>]*`. Returns
+   * the empty string if the URL doesn't match — callers treat that as
+   * "no peer info, can't dedup".
+   *
+   * @param contactUrl - The OCAP URL to parse.
+   * @returns The peer ID, or '' if it can't be extracted.
+   */
+  function peerIdFromContactUrl(contactUrl: string): string {
+    const at = contactUrl.indexOf('@');
+    if (at < 0) {
+      return '';
+    }
+    const rest = contactUrl.slice(at + 1);
+    const comma = rest.indexOf(',');
+    return comma < 0 ? rest : rest.slice(0, comma);
+  }
+
+  /**
+   * Find every existing registry entry that shares (peerId, providerTag)
+   * with the given description. Used to evict superseded entries when a
+   * provider re-registers after a restart.
+   *
+   * @param description - The incoming registration's description.
+   * @returns Array of registry ids of matching entries.
+   */
+  function findSamePeerSameTagEntries(
+    description: ServiceDescription,
+  ): string[] {
+    const newPeerId = peerIdFromContactUrl(
+      description.contact[0]?.contactUrl ?? '',
+    );
+    if (newPeerId === '') {
+      return [];
+    }
+    const newTag = description.providerTag;
+    const matches: string[] = [];
+    for (const entry of registry.values()) {
+      if (entry.description.providerTag !== newTag) {
+        continue;
+      }
+      const existingPeerId = peerIdFromContactUrl(
+        entry.description.contact[0]?.contactUrl ?? '',
+      );
+      if (existingPeerId === newPeerId) {
+        matches.push(entry.id);
+      }
+    }
+    return matches;
+  }
+
   /**
    * Store a service in the (in-memory) registry.
    *
@@ -387,9 +440,16 @@ export function buildRootObject(
   }
 
   /**
-   * Final step shared by all `register*` paths: store locally and tell
-   * the bridge. If the bridge call fails, undo the local store so the
-   * registry never contains entries the LLM doesn't know about.
+   * Final step shared by all `register*` paths: evict any superseded
+   * registrations, store the new entry locally, and tell the bridge. If
+   * the bridge call fails, undo the local store so the registry never
+   * contains entries the LLM doesn't know about.
+   *
+   * Eviction key is (peerId, providerTag) — see ServiceDescription's
+   * `providerTag` for the contract. The dead `svc:N` entries that get
+   * evicted here may still be cited by the LLM bridge's stale
+   * conversation context; `findServices` filters those out via the
+   * existing "bridge cited unknown id" guard.
    *
    * @param description - The validated service description.
    * @param contact - The validated contact endpoint.
@@ -398,6 +458,12 @@ export function buildRootObject(
     description: ServiceDescription,
     contact: ContactPoint,
   ): Promise<void> {
+    for (const supersededId of findSamePeerSameTagEntries(description)) {
+      registry.delete(supersededId);
+      log(
+        `evicted superseded registration ${supersededId} (providerTag=${description.providerTag})`,
+      );
+    }
     const id = store(description, contact);
     try {
       await ingestService(id, description);