address second-round review feedback on #952

- service-discovery-types(design): drop the dangling reference to
  ~/DiscoveryNotes/ files that aren't in the repo
- service-matcher(matcher-vat): restore evicted entries on bridge
  ingest failure; the prior code rolled back the new entry but not
  the entries it had just superseded, so a transient bridge failure
  silently destroyed whatever previous registration shared the new
  one's providerTag
- service-matcher(matcher-vat): drop the dangling reference to
  discovery-plan.md (which was removed earlier); inline the relevant
  obligations directly in the file header
- sample-services(matcher-registration): change registerServicesWithMatcher
  to return a RegistrationSummary, throw on matcher-URL redeem failure,
  and throw when every entry fails — so bootstrap fails loudly instead
  of returning success with an empty matcher registry. Update call
  sites in echo-service and random-number-service to await the call
  instead of fire-and-forget, so the new throws actually surface

Author: FUDCo

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

@@ -60,13 +60,10 @@ export function buildRootObject(
       });
       contactUrl = await E(services.ocapURLIssuerService).issue(contact);
 
-      registerServicesWithMatcher({
+      await registerServicesWithMatcher({
         matcherUrl,
         ocapURLRedemptionService: services.ocapURLRedemptionService,
         entries: [{ name: SERVICE_NAME, contact, registrationToken }],
-      }).catch((error: unknown) => {
-        // eslint-disable-next-line no-console
-        console.error(`[${SERVICE_NAME}] Matcher registration failed:`, error);
       });
 
       return harden({ name: SERVICE_NAME, contactUrl });

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

@@ -63,13 +63,10 @@ export function buildRootObject(
       });
       contactUrl = await E(services.ocapURLIssuerService).issue(contact);
 
-      registerServicesWithMatcher({
+      await registerServicesWithMatcher({
         matcherUrl,
         ocapURLRedemptionService: services.ocapURLRedemptionService,
         entries: [{ name: SERVICE_NAME, contact, registrationToken }],
-      }).catch((error: unknown) => {
-        // eslint-disable-next-line no-console
-        console.error(`[${SERVICE_NAME}] Matcher registration failed:`, error);
       });
 
       return harden({ name: SERVICE_NAME, contactUrl });

packages/sample-services/src/vat-lib/matcher-registration.ts

@@ -14,36 +14,53 @@ export type RegistrationEntry = {
   registrationToken: string;
 };
 
+/**
+ * Summary of a `registerServicesWithMatcher` call: which entries
+ * landed in the matcher's registry, and which did not.
+ */
+export type RegistrationSummary = {
+  registered: { name: string }[];
+  failed: { name: string; cause: unknown }[];
+};
+
 /**
  * Register a service (or group of services) with a matcher.
  *
- * If `matcherUrl` is empty/undefined, logs and returns without contacting
- * any matcher — useful for development cycles where the matcher isn't
- * up yet. Otherwise redeems `matcherUrl` via the kernel's redemption
- * service and calls `registerServiceByRef(contact, token)` for each
- * entry sequentially. Registration failures are logged but do not abort
- * the remaining registrations.
+ * If `matcherUrl` is empty/undefined, logs and returns an empty summary
+ * without contacting any matcher — useful for development cycles where
+ * the matcher isn't up yet. Otherwise redeems `matcherUrl` via the
+ * kernel's redemption service and calls
+ * `registerServiceByRef(contact, token)` for each entry sequentially.
+ * Per-entry failures are logged but do not abort the remaining
+ * registrations.
+ *
+ * Throws when the matcher URL itself cannot be redeemed (there's no
+ * useful partial-success story past that point) and when every entry
+ * fails (so bootstrap returning success while the matcher's registry
+ * stays empty becomes a loud failure instead of a silent one).
  *
  * @param options - Registration options.
  * @param options.matcherUrl - Ocap URL of the matcher, or empty/undefined
  * to skip registration entirely.
  * @param options.ocapURLRedemptionService - Kernel service used to redeem
  * the matcher URL.
  * @param options.entries - Services to register.
+ * @returns Summary of which entries succeeded vs failed.
  */
 export async function registerServicesWithMatcher(options: {
   matcherUrl: string | undefined;
   ocapURLRedemptionService: OcapURLRedemptionService;
   entries: RegistrationEntry[];
-}): Promise<void> {
+}): Promise<RegistrationSummary> {
   const { matcherUrl, ocapURLRedemptionService, entries } = options;
+  const summary: RegistrationSummary = { registered: [], failed: [] };
 
   if (!matcherUrl) {
     // eslint-disable-next-line no-console
     console.log(
       '[vat] matcherUrl parameter not set; skipping matcher registration.',
     );
-    return;
+    return summary;
   }
 
   let matcher: ServiceMatcher;
@@ -52,9 +69,7 @@ export async function registerServicesWithMatcher(options: {
       matcherUrl,
     )) as ServiceMatcher;
   } catch (cause) {
-    // eslint-disable-next-line no-console
-    console.error(`[vat] Failed to redeem matcher URL ${matcherUrl}:`, cause);
-    return;
+    throw new Error(`Failed to redeem matcher URL ${matcherUrl}`, { cause });
   }
 
   for (const entry of entries) {
@@ -63,11 +78,21 @@ export async function registerServicesWithMatcher(options: {
         entry.contact,
         entry.registrationToken,
       );
+      summary.registered.push({ name: entry.name });
       // eslint-disable-next-line no-console
       console.log(`[vat] Registered service "${entry.name}" with matcher.`);
     } catch (cause) {
+      summary.failed.push({ name: entry.name, cause });
       // eslint-disable-next-line no-console
       console.error(`[vat] Failed to register "${entry.name}":`, cause);
     }
   }
+
+  if (entries.length > 0 && summary.registered.length === 0) {
+    throw new Error(
+      `All ${entries.length} registration(s) failed for matcher ${matcherUrl}`,
+    );
+  }
+
+  return summary;
 }

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

@@ -1,8 +1,6 @@
 # Service discovery — design notes
 
-Design notes for the types in this package, to be read alongside
-`~/DiscoveryNotes/discovery.md` (the background essay) and
-`~/DiscoveryNotes/discovery-analysis.md` (the analysis of the prior demo).
+Design notes for the types in this package.
 
 This package only holds wire-format types, runtime validators, and a small
 converter. The actual provider, matcher, and consumer live in their own

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

@@ -11,9 +11,10 @@
  *
  * The registry of registered services is **in-memory**. After a
  * matcher restart, providers must re-register. Making the registry
- * durable is a planned follow-up — see the "dedup / liveness" entry
- * in `discovery-plan.md` for the design obligations that come with
- * that path.
+ * durable is a planned follow-up; doing so brings its own obligations
+ * (eviction of stale registrations when providers disappear, liveness
+ * detection, and reconciling persisted entries with the bridge's LLM
+ * context) that need to be designed before that change lands.
  *
  * Ranking is delegated to an LLM-backed bridge process via an
  * `IOService` endowment named `llm`. On every successful registration
@@ -128,7 +129,8 @@ export function buildRootObject(
   }
 
   // Registry is in-memory. On matcher restart it starts empty;
-  // providers must re-register. (See plan follow-up "dedup / liveness".)
+  // providers must re-register. Making this durable is a planned
+  // follow-up; see the file header for the obligations it carries.
   const registry = new Map<string, RegisteredService>();
 
   const log = (...args: unknown[]): void => {
@@ -458,7 +460,17 @@ export function buildRootObject(
     description: ServiceDescription,
     contact: ContactPoint,
   ): Promise<void> {
+    // Stash superseded entries so we can restore them if the bridge
+    // ingest fails — otherwise a transient bridge failure would
+    // silently destroy whatever previous registration shared this
+    // providerTag, defeating the atomicity property the dedup commit
+    // was supposed to provide.
+    const evicted: [string, RegisteredService][] = [];
     for (const supersededId of findSamePeerSameTagEntries(description)) {
+      const prior = registry.get(supersededId);
+      if (prior) {
+        evicted.push([supersededId, prior]);
+      }
       registry.delete(supersededId);
       log(
         `evicted superseded registration ${supersededId} (providerTag=${description.providerTag})`,
@@ -469,7 +481,13 @@ export function buildRootObject(
       await ingestService(id, description);
     } catch (cause) {
       registry.delete(id);
-      log(`bridge ingest failed for ${id}; removed from registry:`, cause);
+      for (const [oldId, oldEntry] of evicted) {
+        registry.set(oldId, oldEntry);
+      }
+      log(
+        `bridge ingest failed for ${id}; rolled back new entry and restored ${evicted.length} evicted entries:`,
+        cause,
+      );
       throw cause;
     }
   }