@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/contract4-credentials.ts

@@ -0,0 +1,207 @@
+import { ConfigError } from '#profile';
+import type { SecretStore } from '#secrets';
+import { credentialRefFor } from '#registry';
+import type { ProviderRegistry } from '#registry';
+import type { ConnectionConfig } from '#profile';
+import { rotatableCredentialRefs } from '#connectivity';
+import type { Renames } from './contract4-data.ts';
+
+/**
+ * Move each stored credential to the ref its renamed connection now derives.
+ *
+ * **The step without which the rename loses every account.** A `credential_ref`
+ * is almost never written down: `credentialRefFor` derives it as
+ * `<provider>/<connection>`, so renaming `gmail.main_2` to `gmail.con17`
+ * silently repoints the lookup at a key nothing holds. Config, blobs and state
+ * all move; the secret stays where it was, and the endpoint reports "no stored
+ * credential" for an account that is still perfectly well authorised.
+ *
+ * Found by rehearsing the migration against a real workspace, where it turned
+ * six live credentials into six re-authorisations. ADR-051 records why that is
+ * not an acceptable release note.
+ *
+ * Refs come from the same authority the runtime resolves them with, rather than
+ * from a pattern over the store's keys. A ref is not always
+ * `<provider>/<id>` — an `oauth_apps` entry puts the app's name in front
+ * instead — and matching on the last segment cannot tell `google/main` for a
+ * renamed Gmail connection from `google/main` for a renamed Drive one.
+ */
+export interface CredentialMove {
+  readonly from: string;
+  readonly to: string;
+}
+
+export function planCredentialMoves(
+  connections: readonly ConnectionConfig[],
+  registry: ProviderRegistry,
+  renames: Renames,
+): CredentialMove[] {
+  const moves: CredentialMove[] = [];
+  const seen = new Set<string>();
+
+  for (const connection of connections) {
+    const to = renames.get(`${connection.provider}.${connection.id}`);
+    if (to === undefined) continue;
+
+    const id = to.slice(to.indexOf('.') + 1);
+    if (id === connection.id) continue;
+
+    const manifest = registry.manifest(connection.provider);
+    const after = { ...connection, id };
+
+    // A ref the row states outright does not move: it names a key the operator
+    // chose, and the id it happens to contain is not this migration's to read.
+    const refs: [string | undefined, string | undefined][] = [
+      [credentialRefFor(connection, manifest), credentialRefFor(after, manifest)],
+    ];
+
+    // An OAuth connection also holds the token blob `saveTokens` rewrites, and
+    // it is the one that matters — the hot path of an ordinary read.
+    if (manifest) {
+      const before = rotatableCredentialRefs(manifest, connection.id);
+      const now = rotatableCredentialRefs(manifest, id);
+      for (let index = 0; index < before.length; index += 1) {
+        refs.push([before[index], now[index]]);
+      }
+    }
+
+    for (const [from, into] of refs) {
+      if (from === undefined || into === undefined || from === into) continue;
+
+      // Keyed on the *pair*, not on the source. Several connections can derive
+      // one ref — three iCloud surfaces authorised as one account share
+      // `icloud/<id>` through `auth.app` — and giving distinct ids to each
+      // turns one credential into three. Deduping on the source sent it to
+      // whichever connection came first and orphaned the rest, which is what a
+      // real workspace showed on the first rehearsal.
+      const pair = `${from}\u0000${into}`;
+      if (seen.has(pair)) continue;
+      seen.add(pair);
+      moves.push({ from, to: into });
+    }
+  }
+
+  return moves;
+}
+
+/**
+ * Apply them, reading each value back before the old key is removed.
+ *
+ * The same rule the blob mover follows: a credential that half moved and a
+ * source already gone is the one state with nothing to retry from. A ref whose
+ * destination is already occupied is left alone rather than overwritten —
+ * that is a rerun finding its own work, and clobbering it would be the one
+ * irreversible thing here.
+ */
+export async function applyCredentialMoves(
+  store: SecretStore,
+  moves: readonly CredentialMove[],
+): Promise<string[]> {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  // Grouped by source, because one credential may feed several destinations
+  // and the source may only go once every one of them is written. Deleting
+  // after the first would take it away from the connections still to come.
+  const bySource = new Map<string, string[]>();
+  for (const move of moves) {
+    const into = bySource.get(move.from) ?? [];
+    into.push(move.to);
+    bySource.set(move.from, into);
+  }
+
+  for (const [from, destinations] of bySource) {
+    const value = await store.get(from);
+    if (value === null) continue;
+
+    // **The source goes only once every destination holds this value.** The
+    // delete used to sit outside this loop while the loop skipped an occupied
+    // destination — so a ref already holding something (a stale credential a
+    // `disconnect --keep-credential` left behind, or an unrelated account's)
+    // meant nothing was written and the source was destroyed anyway, reported
+    // as a successful move. `migrate-move.ts` guards the same hazard with
+    // `sameBytes`, and this is that guard.
+    let carried = true;
+
+    for (const to of destinations) {
+      const held = await store.get(to);
+
+      if (held !== null) {
+        // Our own earlier work, so this destination is done. Anything else is
+        // somebody's credential and is not ours to overwrite or to delete the
+        // source out from under.
+        if (held !== value) {
+          carried = false;
+          skipped.push(
+            `${from} → ${to}: ${to} already holds a different value, so nothing was moved or ` +
+              'deleted. Remove or rename it and run this again.',
+          );
+        }
+        continue;
+      }
+
+      await store.set(to, value);
+      if ((await store.get(to)) === null) {
+        throw new ConfigError(
+          `${to} did not read back after being written. Nothing has been deleted; ` +
+            'fix the credential store and run this again.',
+        );
+      }
+    }
+
+    if (!carried) continue;
+
+    await store.delete(from);
+    applied.push(`${from} → ${destinations.join(', ')}`);
+  }
+
+  return [...applied, ...skipped];
+}
+
+/**
+ * The sealed vault document, which `credentialRefFor` cannot see.
+ *
+ * A vault connection's `auth.kind` is `none`, so `credentialRefForConnection`
+ * returns `undefined` for it and the loop above skips it entirely — while
+ * `vaultRef` names the document `vault/<profile>/<connection>` and a deployed
+ * target seals it in Secret Manager. Contract 4 renames the connection and
+ * gives the ref a profile, so without this the revision opens a name nothing
+ * created: every vault item reads as absent, with no error, and the ciphertext
+ * sits orphaned under the old ref.
+ *
+ * Invisible in a local rehearsal, because the `file` and `blob` adapters take
+ * their path from `layout` and were already correct. `secret` is the adapter
+ * every deployment uses.
+ *
+ * A `ref` the target states outright is left alone: it names a document the
+ * operator chose, and a deployment already sealing under it has to keep
+ * opening it.
+ */
+export function planVaultMoves(
+  profiles: ReadonlyMap<string, { grants?: { connection?: unknown }[] }>,
+  renames: Renames,
+  declaredRef: string | undefined,
+): CredentialMove[] {
+  if (declaredRef !== undefined) return [];
+
+  const moves: CredentialMove[] = [];
+
+  for (const [profile, config] of profiles) {
+    const granted = (config.grants ?? [])
+      .map((grant) => grant.connection)
+      .find((ref): ref is string => typeof ref === 'string' && ref.startsWith('vault.'));
+
+    // `main` where the profile grants none, which is what `vaultRef` falls back
+    // to — so a profile that denied the vault still finds its own document
+    // rather than another profile's.
+    const was = granted === undefined ? 'main' : granted.slice('vault.'.length);
+    const to = granted === undefined ? undefined : renames.get(granted);
+    const now = to === undefined ? was : to.slice(to.indexOf('.') + 1);
+
+    const from = `vault/${was}`;
+    const into = `vault/${profile}/${now}`;
+    if (from !== into) moves.push({ from, to: into });
+  }
+
+  return moves;
+}

package/src/cli/contract4-data.ts

@@ -0,0 +1,399 @@
+import { layout } from '#profile';
+import type { BlobStore } from '#stores/blobs';
+import {
+  decodeSegment,
+  DISCOVERY_NAMESPACE,
+  encodeSegment,
+  isWorkspaceNamespace,
+  OAUTH_NAMESPACE,
+} from '#stores/state';
+import { C3 } from './contract3-layout.ts';
+import { planRenames, renamedProvider } from './contract4-rename.ts';
+import { claim, type Move } from './migrate-move.ts';
+
+/**
+ * The half of the contract-4 migration that moves bytes rather than YAML.
+ *
+ * Contract 3 hoisted everything a profile owned up to the workspace; this
+ * carries it back down (ADR-066), and flattens what stays at the workspace out
+ * of `data/` while it is here (ADR-067). Same seam as `contract3-data.ts`, and
+ * the same ordering rule: everything that can refuse happens while this is
+ * still a plan.
+ *
+ * **The interesting decision is what to do with a store two profiles grant.**
+ * Contract 3's default gives every profile a grant on the same `.main`
+ * instances, so the common case in a freshly created workspace is that both
+ * profiles point at one memory. There is no answer that is right for everyone:
+ * moving it into one profile takes it away from the other, and merging is not a
+ * thing bytes can do. So it is **copied into each, and the original is left**.
+ * The operator is told, and deletes what they do not want — which is the only
+ * step in this migration that is theirs rather than ours.
+ */
+
+/** Which profiles grant a connection, by `<provider>.<id>`. */
+export type Granting = ReadonlyMap<string, readonly string[]>;
+
+/** Old `<provider>.<id>` to new, for every connection this workspace holds. */
+export type Renames = ReadonlyMap<string, string>;
+
+/**
+ * The new id for every connection, allocated in file order.
+ *
+ * File order rather than anything derived, so a rerun produces the same map and
+ * a preview matches the apply. A row that already carries an allocated id keeps
+ * it — this migration is not a renumbering, and running it twice must not walk
+ * `con1` to `con2`.
+ *
+ * The reserved ids are the owner layer's, and they are what the `lan` prefix is
+ * for: a reader can tell a surface built into Lanes from somebody's account
+ * without resolving anything.
+ */
+
+export interface DataPlan {
+  readonly moves: readonly Move[];
+  /**
+   * What was copied rather than moved, and into which profiles.
+   *
+   * Reported so the operator can delete the original. Never deleted here: a
+   * store two profiles were sharing is one whose owner has to decide, and this
+   * migration guessing would be the silent wrong answer ADR-059 warns about for
+   * the vault in particular.
+   */
+  readonly shared: readonly { readonly key: string; readonly profiles: readonly string[] }[];
+  /** Granted by nobody. Left exactly where it is, and named. */
+  readonly orphaned: readonly string[];
+  /**
+   * Per-profile credential stores contract 3 merged but did not delete.
+   *
+   * Named separately: they are a decryptable document and its key, and "no
+   * profile grants it" is the wrong sentence about one.
+   */
+  readonly leftover: readonly string[];
+}
+
+/**
+ * Where every object under `data/` is going.
+ *
+ * Anything matching no rule is left where it is — this moves what it
+ * understands and never deletes what it does not.
+ */
+export async function planMoves(
+  files: BlobStore,
+  granting: Granting,
+  profiles: readonly string[],
+  renames: Renames = new Map(),
+): Promise<DataPlan> {
+  /** The id a connection ends up with — itself, where nothing renamed it. */
+  const renamed = (provider: string, id: string): string => {
+    const to = renames.get(`${provider}.${id}`);
+    return to === undefined ? id : to.slice(to.indexOf('.') + 1);
+  };
+
+  const moves: Move[] = [];
+  const shared: { key: string; profiles: readonly string[] }[] = [];
+  const orphaned: string[] = [];
+  const leftover: string[] = [];
+  const claimed = new Set<string>();
+
+  for (const blob of await files.list('data/')) {
+    const parts = blob.key.split('/').slice(1);
+    const head = parts[0];
+    const tail = parts.slice(1);
+    if (head === undefined) continue;
+
+    // The four the workspace keeps, out of `data/` and up to the root.
+    if (head === 'credentials.enc' || head === 'credentials.enc.key') {
+      moves.push({ from: blob.key, to: head });
+      continue;
+    }
+    if (head === 'providers.d') {
+      moves.push({ from: blob.key, to: `${layout.providers()}/${tail.join('/')}` });
+      continue;
+    }
+    if (head === 'audit.log') {
+      moves.push({ from: blob.key, to: `${layout.audit()}/${tail.join('/')}` });
+      continue;
+    }
+    if (head === 'state.kv') {
+      for (const move of stateMoves(blob.key, tail, granting, claimed, renames, orphaned)) {
+        moves.push(move);
+      }
+      continue;
+    }
+
+    // `vault.d/<id>.enc` and `skills.d/<id>/...` — the two the profile takes
+    // back, keyed by the connection that already owns them.
+    if (head === 'vault.d' || head === 'skills.d') {
+      const connection = tail[0];
+      if (connection === undefined) continue;
+
+      const provider = head === 'vault.d' ? 'vault' : 'skills';
+      // A vault document is `<id>.enc`, so the id has the suffix stripped; a
+      // skills directory is the id itself.
+      const id = provider === 'vault' ? connection.replace(/\.enc(\.key)?$/, '') : connection;
+      const owners = granting.get(`${provider}.${id}`) ?? [];
+
+      const to = renamed(provider, id);
+      const into = (profile: string): string =>
+        provider === 'vault'
+          ? `${layout.vaultRoot(profile)}/${connection.replace(id, to)}`
+          : `${layout.skills(profile, to)}/${tail.slice(1).join('/')}`;
+
+      record(blob.key, owners, into, moves, shared, orphaned);
+      continue;
+    }
+
+    // **A contract-2 leftover is a credential, not an ungranted store.**
+    // Contract 3 merges `data/<profile>/credentials.enc` and never deletes it,
+    // so a workspace that came through it still holds one per profile — and
+    // "no profile grants it" is true and is the wrong sentence about a
+    // decryptable document: the operator reads it as tidy-up and leaves it.
+    if (tail[0] === 'credentials.enc' || tail[0] === 'credentials.enc.key') {
+      leftover.push(blob.key);
+      continue;
+    }
+
+    // Otherwise `<provider>/<connection>/…`, the namespace every provider's
+    // blobs are scoped into — memory, tasks, assets, entities and every vendor.
+    const connection = tail[0];
+    if (connection === undefined) continue;
+
+    const ref = `${head}.${connection}`;
+    const owners = granting.get(ref) ?? [];
+
+    // Both segments from the one rename: one without the other reads nothing.
+    const settled = renames.get(ref) ?? ref;
+    const dot = settled.indexOf('.');
+    const into = `${settled.slice(0, dot)}/${settled.slice(dot + 1)}`;
+
+    record(
+      blob.key,
+      owners,
+      (profile) => `${layout.blobs(profile)}/${into}/${tail.slice(1).join('/')}`,
+      moves,
+      shared,
+      orphaned,
+    );
+  }
+
+  // The declarations themselves, into the directory each now owns.
+  for (const profile of profiles) {
+    const from = C3.profile(profile);
+    if (await files.has(from)) moves.push({ from, to: layout.profileConfig(profile) });
+  }
+
+  return { moves, shared, orphaned, leftover };
+}
+
+/**
+ * One object, routed by how many profiles grant the connection it belongs to.
+ *
+ * Exactly one is a move. Several is a copy into each, with the original left
+ * behind — see the header. None is left alone and named: a store nothing grants
+ * is not this migration's to place, and deleting it would be the one
+ * irreversible thing in here.
+ */
+function record(
+  key: string,
+  owners: readonly string[],
+  into: (profile: string) => string,
+  moves: Move[],
+  shared: { key: string; profiles: readonly string[] }[],
+  orphaned: string[],
+): void {
+  if (owners.length === 0) {
+    orphaned.push(key);
+    return;
+  }
+
+  if (owners.length === 1) {
+    moves.push({ from: key, to: into(owners[0]!) });
+    return;
+  }
+
+  // `keep` rather than a move: `applyMoves` deletes the source once the copy
+  // reads back, and there is a second destination still to write.
+  for (const profile of owners) moves.push({ from: key, to: into(profile), keep: true });
+  shared.push({ key, profiles: owners });
+}
+
+/**
+ * Where one object under `data/state.kv` goes — and it may go to two places.
+ *
+ * The split is by namespace rather than by key: connection records, the
+ * discovery cache and the endpoint's own OAuth server are the workspace's, and
+ * everything else is one profile's use of an account. `isWorkspaceNamespace` in
+ * `#stores/state` is that rule and this reads it rather than restating it.
+ *
+ * A cursor belongs to whichever profiles grant its connection, so it takes the
+ * same fan-out as a blob does. The alternative — one cursor shared — is exactly
+ * the bug ADR-066 is fixing, two agents consuming each other's position.
+ */
+/**
+ * The namespaces contract 3 spelled without a dot, and contract 4 does.
+ *
+ * `discovery` and `oauth/…` were reachable by a provider — only `custom` is
+ * refused by grammar, so a manifest with id `oauth` landed inside them — and a
+ * dotted name is one no provider can reach. Renaming them is only half the job:
+ * the objects already written under the old spelling have to come across, or
+ * every client that had signed in is signed out and every discovered spec is
+ * fetched again. The rehearsal that found this left 75 OAuth records behind.
+ */
+const RENAMED_NAMESPACES: readonly [string, string][] = [
+  ['discovery', DISCOVERY_NAMESPACE],
+  ['oauth', OAUTH_NAMESPACE],
+];
+
+/** `<provider>/<connection>` as a state namespace is `<provider>.<connection>` as a ref. */
+function refOf(namespace: string): string {
+  const slash = namespace.indexOf('/');
+  return slash === -1 ? namespace : `${namespace.slice(0, slash)}.${namespace.slice(slash + 1)}`;
+}
+
+function stateMoves(
+  from: string,
+  tail: readonly string[],
+  granting: Granting,
+  claimed: Set<string>,
+  renames: Renames = new Map(),
+  orphaned: string[] = [],
+): Move[] {
+  const leaf = tail[tail.length - 1];
+
+  // **Guarded, the way `contract3-data.ts` guards it and for its reason.**
+  // `decodeSegment` throws `URIError` on a stray `%`, and contract 3's catch
+  // moves such a key *verbatim* — so the class of key that survives contract 3
+  // by design is exactly the class this read unguarded, and one of them threw
+  // `URI malformed` naming no file out of every command including the preview.
+  // A key this cannot parse is carried across unchanged rather than dropped.
+  if (leaf === undefined || tail.length < 2 || !leaf.endsWith('.json')) {
+    const move = claim(claimed, { from, to: `${layout.state()}/${tail.join('/')}` });
+    return move === null ? [] : [move];
+  }
+
+  let namespace: string;
+  let key: string;
+  try {
+    namespace = tail.slice(0, -1).map(decodeSegment).join('/');
+    key = decodeSegment(leaf.replace(/\.json$/, ''));
+  } catch {
+    const move = claim(claimed, { from, to: `${layout.state()}/${tail.join('/')}` });
+    return move === null ? [] : [move];
+  }
+
+  // The undotted spellings, carried across before anything else looks at them.
+  for (const [was, now] of RENAMED_NAMESPACES) {
+    if (namespace !== was && !namespace.startsWith(`${was}/`)) continue;
+
+    // Only the first segment. `oauth/tokens` is two segments and each is
+    // encoded on its own, so encoding `oauth.v1/tokens` whole would escape the
+    // separator too and write one segment named `oauth%2Ev1%2Ftokens`.
+    const move = claim(claimed, {
+      from,
+      to: `${layout.state()}/${[encodeSegment(now), ...tail.slice(1)].join('/')}`,
+    });
+    return move === null ? [] : [move];
+  }
+
+  if (isWorkspaceNamespace(namespace)) {
+    // A connection record is keyed on the ref *and* carries it in the body:
+    // `ConnectionRepository.list` reads `provider` and `id` out of the record,
+    // not out of the key. A renamed connection whose bytes moved verbatim would
+    // sit at `connections.v1/gmail.con1` still calling itself `gmail.main`, and
+    // the next reconcile would write a second record beside it.
+    const settled = namespace === 'connections.v1' ? renames.get(key) : undefined;
+    const to = `${layout.state()}/${
+      settled === undefined ? tail.join('/') : `${tail[0]!}/${encodeSegment(settled)}.json`
+    }`;
+
+    // Two profiles both hold a record for a connection they share, and the
+    // second differs only in when it was written.
+    const move = claim(claimed, {
+      from,
+      to,
+      ...(settled === undefined
+        ? {}
+        : { rewrite: (data: Uint8Array) => retarget(data, settled) }),
+    });
+    return move === null ? [] : [move];
+  }
+
+  // A cursor's namespace is `cursors.v1` and its *key* is the connection; a
+  // provider's own store is namespaced `<provider>/<connection>` instead — and
+  // that slash is not the dot a grant is keyed on. Looking the one up with the
+  // other matched nothing and dropped every provider's state in silence, which
+  // is the same shape of bug `contract3-data.ts` records having shipped once.
+  const cursor = namespace === 'cursors.v1';
+  const ref = cursor ? key : refOf(namespace);
+  const owners = granting.get(ref) ?? [];
+
+  if (owners.length === 0) {
+    orphaned.push(from);
+    return [];
+  }
+
+  const settled = renames.get(ref) ?? ref;
+  const dot = settled.indexOf('.');
+
+  // The rename reaches whichever half carries the ref, and only that half.
+  const moved = cursor
+    ? `${tail[0]!}/${encodeSegment(settled)}.json`
+    : [
+        encodeSegment(settled.slice(0, dot)),
+        encodeSegment(settled.slice(dot + 1)),
+        ...tail.slice(2),
+      ].join('/');
+
+  return owners.map((profile) => ({
+    from,
+    to: `${layout.profileState(profile)}/${moved}`,
+    keep: owners.length > 1,
+  }));
+}
+
+/**
+ * A connection record, told what it is now called.
+ *
+ * Spread rather than assigned field by field, so key order and anything a later
+ * version added survive. Bytes that are not a JSON object come back untouched:
+ * refusing to move what will not parse strands it where nothing reads it.
+ */
+function retarget(data: Uint8Array, ref: string): Uint8Array {
+  try {
+    const held = JSON.parse(new TextDecoder().decode(data)) as Record<string, unknown>;
+    if (held === null || typeof held !== 'object' || Array.isArray(held)) return data;
+
+    const dot = ref.indexOf('.');
+    return new TextEncoder().encode(
+      JSON.stringify({ ...held, provider: ref.slice(0, dot), id: ref.slice(dot + 1) }),
+    );
+  } catch {
+    return data;
+  }
+}
+
+/**
+ * Which profiles grant each connection, read off the profiles themselves.
+ *
+ * Derived rather than assumed, because the fan-out above is the whole decision:
+ * a connection nobody grants must not be placed anywhere, and one two profiles
+ * grant must not be placed in only the first. `connections.yaml` cannot answer
+ * this — it says what exists, not who selected it (ADR-057).
+ */
+export function grantingProfiles(
+  configs: ReadonlyMap<string, { grants?: { connection?: unknown }[] }>,
+): Granting {
+  const granting = new Map<string, string[]>();
+
+  for (const [profile, config] of configs) {
+    for (const grant of config.grants ?? []) {
+      const ref = grant.connection;
+      if (typeof ref !== 'string') continue;
+      const owners = granting.get(ref) ?? [];
+      if (!owners.includes(profile)) owners.push(profile);
+      granting.set(ref, owners);
+    }
+  }
+
+  return granting;
+}

package/src/cli/contract4-rename.ts

@@ -0,0 +1,73 @@
+import { nextConnectionId } from './identity.ts';
+import { C3_OWNER_PROVIDERS } from './contract3-layout.ts';
+import type { Renames } from './contract4-data.ts';
+
+/**
+ * What every connection is called after contract 4.
+ *
+ * Its own module because it is one decision read by four rewrites — the rows,
+ * the grants, the blob paths and the state keys — and because a map keyed one
+ * way and queried another is the bug `contract3-data.ts` records shipping once.
+ * One place to build it, one place for everything else to read it from.
+ */
+
+/**
+ * The id and provider every connection ends up with.
+ *
+ * Two things happen here, and the merge is the interesting one.
+ *
+ * **The owner layer merges to one row per surface.** Contract 3 made the
+ * *connection* the isolation boundary, so three profiles each needed their own
+ * `memory` — a workspace with three profiles came out of that migration holding
+ * `memory.main`, `memory.work` and `memory.demo`, and the file read as
+ * duplicated because it was. ADR-066 makes the *profile* the boundary, so one
+ * row serves every profile and each still keeps its own bytes at
+ * `profiles/<name>/lanes_memory/lan1/`. Merging the rows merges no notes, which
+ * is exactly why contract 3 could not do it and this can.
+ *
+ * **Both sequences are numbered cleanly**, `con1..conN` over the accounts in
+ * file order and `lan1..lan8` over the merged owner rows. A rerun produces the
+ * same map because the order is the file's, and a row already carrying an
+ * allocated id keeps it — this is not a renumbering, and running it twice must
+ * not walk `con1` to `con2`.
+ */
+export function planRenames(
+  connections: readonly { id: string; provider: string }[],
+): Renames {
+  const renames = new Map<string, string>();
+  const taken = connections
+    .map((row) => row.id)
+    .filter((id) => /^(lan|con)[0-9]+$/.test(id));
+
+  // One destination per owner-layer *provider*, so every profile's instance of
+  // it lands on the same row.
+  const merged = new Map<string, string>();
+
+  for (const row of connections) {
+    const owner = C3_OWNER_PROVIDERS.includes(row.provider);
+    const provider = renamedProvider(row.provider);
+    const from = `${row.provider}.${row.id}`;
+
+    if (owner) {
+      const already = merged.get(provider);
+      if (already !== undefined) {
+        renames.set(from, already);
+        continue;
+      }
+    }
+
+    const id = /^(lan|con)[0-9]+$/.test(row.id) ? row.id : nextConnectionId(taken, owner);
+    if (!taken.includes(id)) taken.push(id);
+
+    const to = `${provider}.${id}`;
+    renames.set(from, to);
+    if (owner) merged.set(provider, to);
+  }
+
+  return renames;
+}
+
+/** `memory` becomes `lanes_memory`; everything else keeps its id. */
+export function renamedProvider(provider: string): string {
+  return C3_OWNER_PROVIDERS.includes(provider) ? `lanes_${provider}` : provider;
+}