refactor(bridgeAccess): use accesses.update for in-place updates (Plan 58 Phase 4b)

Plan 66's accesses.update lets us preserve the access id (token, apiEndpoint)
across permission changes. The old delete+create pattern is replaced with a
single in-place update call.

Changes:
- `ensureBridgeAccess` updateIfDifferent branch: `connection.updateAccess(id, {permissions, clientData})`
  instead of delete+create. apiEndpoint preserved; id becomes composite `<base>:<serial>`.
- `BridgeAccessResult.recreated` (boolean) dropped — no recreate happens.
  Replaced with `updated: boolean` (true when accesses.update was called).
- 1-retry `StaleAccessIdError` budget: if another writer updates the access
  between our `accesses.get` and our `accesses.update`, we refetch and retry once.
- `recreateBridgeAccess` (public) + `_recreateFromExisting` (private) dropped
  entirely — no workspace callers, dead code from the Plan 27 era.

clientData merge: empirically verified on demo (Plan 66 deploy) that
`accesses.update` MERGES clientData (existing keys preserved when not in
payload), so previousAccessIds chains on legacy bridge accesses survive
automatically without explicit read-merge-write.

Author: perki

tests/bridgeAccess.test.js

@@ -5,19 +5,19 @@ import { assert } from './test-utils/deps-node.js';
 // The main integration test is in the bridge-mira tests.
 
 // Import to verify the module loads correctly
-import { getOrCreateBridgeAccess, recreateBridgeAccess, ensureBridgeAccess } from '../ts/appTemplates/bridgeAccess.ts';
+import { getOrCreateBridgeAccess, ensureBridgeAccess } from '../ts/appTemplates/bridgeAccess.ts';
 
 describe('[BACC] Bridge Access helpers', function () {
-  it('[BA01] should export all three helper functions', () => {
+  it('[BA01] should export both helper functions', () => {
     assert.equal(typeof getOrCreateBridgeAccess, 'function');
-    assert.equal(typeof recreateBridgeAccess, 'function');
     assert.equal(typeof ensureBridgeAccess, 'function');
   });
 
   it('[BA02] should be importable from appTemplates', async () => {
     const appTemplates = await import('../ts/appTemplates/appTemplates.ts');
     assert.equal(typeof appTemplates.getOrCreateBridgeAccess, 'function');
-    assert.equal(typeof appTemplates.recreateBridgeAccess, 'function');
     assert.equal(typeof appTemplates.ensureBridgeAccess, 'function');
+    // recreateBridgeAccess was dropped in Plan 58 Phase 4b — accesses.update replaces delete+create.
+    assert.equal(typeof appTemplates.recreateBridgeAccess, 'undefined');
   });
 });

ts/appTemplates/appTemplates.ts

@@ -8,7 +8,7 @@ import { CollectorRequest } from './CollectorRequest.ts';
 import { Contact } from './Contact.ts';
 export type { ContactInvite } from './Contact.ts';
 export type { AccessUpdateRequest, AccessUpdateRequestContent, AccessUpdateAction } from './interfaces.ts';
-export { getOrCreateBridgeAccess, recreateBridgeAccess, ensureBridgeAccess } from './bridgeAccess.ts';
+export { getOrCreateBridgeAccess, ensureBridgeAccess } from './bridgeAccess.ts';
 export type { BridgeAccessOptions, BridgeAccessResult } from './bridgeAccess.ts';
 export {
   getSectionItemLabels,

ts/appTemplates/bridgeAccess.ts

@@ -14,10 +14,10 @@ export interface BridgeAccessOptions {
 export interface BridgeAccessResult {
   apiEndpoint: string;
   accessId: string;
-  /** Whether the access was newly created (vs. reused) */
+  /** Whether the access was newly created (vs. reused/updated) */
   created: boolean;
-  /** Whether the access was recreated (old deleted, new created) */
-  recreated: boolean;
+  /** Whether an existing access was updated in place via accesses.update */
+  updated: boolean;
 }
 
 /**
@@ -39,7 +39,7 @@ export async function getOrCreateBridgeAccess (
       apiEndpoint: existing.apiEndpoint,
       accessId: existing.id,
       created: false,
-      recreated: false
+      updated: false
     };
   }
 
@@ -53,146 +53,90 @@ export async function getOrCreateBridgeAccess (
     apiEndpoint: access.apiEndpoint,
     accessId: access.id,
     created: true,
-    recreated: false
-  };
-}
-
-/**
- * Recreate a bridge access with updated permissions/clientData.
- * Deletes the old access and creates a new one, carrying forward previousAccessIds
- * so that events created under old accesses are still attributable.
- *
- * @param connection - Pryv connection to the user's account (personal token)
- * @param options - new access configuration
- */
-export async function recreateBridgeAccess (
-  connection: pryv.Connection,
-  options: BridgeAccessOptions
-): Promise<BridgeAccessResult> {
-  const accesses = await (connection as any).apiOne('accesses.get', {}, 'accesses');
-  const existing = accesses.find((a: any) => a.name === options.name);
-
-  // Build previousAccessIds chain
-  const previousAccessIds: string[] = [];
-  if (existing) {
-    if (existing.id) previousAccessIds.push(existing.id);
-    const oldPrevIds = existing.clientData?.previousAccessIds;
-    if (Array.isArray(oldPrevIds)) {
-      for (const id of oldPrevIds) {
-        if (!previousAccessIds.includes(id)) previousAccessIds.push(id);
-      }
-    }
-    // Delete old access
-    await (connection as any).apiOne('accesses.delete', { id: existing.id }, 'accessDeletion');
-    logger.info('Deleted old bridge access for recreation', { name: options.name, oldId: existing.id });
-  }
-
-  // Merge previousAccessIds into clientData
-  const clientData = {
-    ...options.clientData,
-    previousAccessIds: previousAccessIds.length > 0 ? previousAccessIds : undefined
-  };
-
-  const access = await (connection as any).apiOne('accesses.create', {
-    name: options.name,
-    permissions: options.permissions,
-    clientData
-  }, 'access');
-
-  return {
-    apiEndpoint: access.apiEndpoint,
-    accessId: access.id,
-    created: true,
-    recreated: existing != null
+    updated: false
   };
 }
 
 /**
  * Get or create a bridge access, with optional permission update detection.
- * If the access exists but permissions differ, recreates it with the new permissions
- * while preserving previousAccessIds for event attribution.
+ *
+ * If the access exists and `updateIfDifferent` is set and permissions differ,
+ * updates it in place via `accesses.update` (Plan 66). The access id becomes
+ * composite (`<base>:<serial>`) but the token and apiEndpoint are preserved.
+ *
+ * Server-side `clientData` merge means any pre-existing keys on the access
+ * (notably `previousAccessIds` from the legacy delete+create era) are
+ * preserved automatically — we only send the keys we want to set.
+ *
+ * `StaleAccessIdError` handling: if another writer updates the access between
+ * our `accesses.get` and our `accesses.update`, we refetch + retry once.
+ * Two consecutive stale errors propagate.
  *
  * @param connection - Pryv connection to the user's account (personal token)
  * @param options - access configuration
- * @param options.updateIfDifferent - if true, recreate when permissions differ (default: false)
+ * @param options.updateIfDifferent - if true, update permissions in place when they differ (default: false)
  */
 export async function ensureBridgeAccess (
   connection: pryv.Connection,
   options: BridgeAccessOptions & { updateIfDifferent?: boolean }
 ): Promise<BridgeAccessResult> {
-  const accesses = await (connection as any).apiOne('accesses.get', {}, 'accesses');
-  const existing = accesses.find((a: any) => a.name === options.name);
-
-  if (existing) {
-    // Check if permissions match
-    if (options.updateIfDifferent && !permissionsMatch(existing.permissions, options.permissions)) {
-      logger.info('Bridge access permissions differ, recreating', { name: options.name });
-      // Can't re-fetch — pass existing directly to avoid double API call
-      return await _recreateFromExisting(connection, existing, options);
+  let attempt = 0;
+  while (true) {
+    const accesses = await (connection as any).apiOne('accesses.get', {}, 'accesses');
+    const existing = accesses.find((a: any) => a.name === options.name);
+
+    if (!existing) {
+      const access = await (connection as any).apiOne('accesses.create', {
+        name: options.name,
+        permissions: options.permissions,
+        clientData: options.clientData || {}
+      }, 'access');
+      return {
+        apiEndpoint: access.apiEndpoint,
+        accessId: access.id,
+        created: true,
+        updated: false
+      };
     }
-    return {
-      apiEndpoint: existing.apiEndpoint,
-      accessId: existing.id,
-      created: false,
-      recreated: false
-    };
-  }
-
-  const access = await (connection as any).apiOne('accesses.create', {
-    name: options.name,
-    permissions: options.permissions,
-    clientData: options.clientData || {}
-  }, 'access');
 
-  return {
-    apiEndpoint: access.apiEndpoint,
-    accessId: access.id,
-    created: true,
-    recreated: false
-  };
-}
+    if (!options.updateIfDifferent || permissionsMatch(existing.permissions, options.permissions)) {
+      return {
+        apiEndpoint: existing.apiEndpoint,
+        accessId: existing.id,
+        created: false,
+        updated: false
+      };
+    }
 
-/** @private recreate from an already-fetched existing access */
-async function _recreateFromExisting (
-  connection: pryv.Connection,
-  existing: any,
-  options: BridgeAccessOptions
-): Promise<BridgeAccessResult> {
-  const previousAccessIds: string[] = [];
-  if (existing.id) previousAccessIds.push(existing.id);
-  const oldPrevIds = existing.clientData?.previousAccessIds;
-  if (Array.isArray(oldPrevIds)) {
-    for (const id of oldPrevIds) {
-      if (!previousAccessIds.includes(id)) previousAccessIds.push(id);
+    // Update in place. Server merges clientData; we only send our new keys.
+    const updatePayload: Record<string, any> = { permissions: options.permissions };
+    if (options.clientData != null) updatePayload.clientData = options.clientData;
+
+    try {
+      logger.info('Bridge access permissions differ, updating', { name: options.name, id: existing.id });
+      const updated = await (connection as any).updateAccess(existing.id, updatePayload);
+      return {
+        apiEndpoint: updated.apiEndpoint,
+        accessId: updated.id,
+        created: false,
+        updated: true
+      };
+    } catch (e: any) {
+      if (e instanceof (pryv as any).StaleAccessIdError && attempt === 0) {
+        attempt++;
+        logger.info('Bridge access stale on update, refetching and retrying once', { name: options.name });
+        continue;
+      }
+      throw e;
     }
   }
-
-  await (connection as any).apiOne('accesses.delete', { id: existing.id }, 'accessDeletion');
-
-  const clientData = {
-    ...options.clientData,
-    previousAccessIds: previousAccessIds.length > 0 ? previousAccessIds : undefined
-  };
-
-  const access = await (connection as any).apiOne('accesses.create', {
-    name: options.name,
-    permissions: options.permissions,
-    clientData
-  }, 'access');
-
-  return {
-    apiEndpoint: access.apiEndpoint,
-    accessId: access.id,
-    created: true,
-    recreated: true
-  };
 }
 
 /** Compare two permission arrays (order-independent) */
 function permissionsMatch (a: any[], b: Permission[]): boolean {
   if (!a || !b) return false;
   if (a.length !== b.length) return false;
-  const normalize = (p: any) => `${p.streamId || ''}:${p.level || ''}:${p.feature || ''}:${p.setting || ''}`;
+  const normalize = (p: any): string => `${p.streamId || ''}:${p.level || ''}:${p.feature || ''}:${p.setting || ''}`;
   const setA = new Set(a.map(normalize));
   const setB = new Set(b.map(normalize));
   if (setA.size !== setB.size) return false;