@lanes-sh/link 0.8.0 → 0.9.1

package/src/cli/config-repair.ts

@@ -1,7 +1,5 @@
-import { newConnectionsTemplate } from './config-templates.ts';
-import { CONNECTIONS_FILE, listProfiles, workspaceFiles, writeWorkspaceFile } from '#profile';
 import { ConfigDocument } from './config-edit.ts';
-import { ok, print, style, warn } from './output.ts';
+import { nextConnectionId } from './identity.ts';
 
 /**
  * Giving a profile a reserved provider it is missing, without undoing a choice.
@@ -19,16 +17,16 @@ import { ok, print, style, warn } from './output.ts';
  * than several that look alike.
  */
 
-/** The reserved provider ids that hold no account, and the label each row carries. */
+/** Lanes' own provider ids, and the label each row carries. */
 const RESERVED_SURFACES = {
-  memory: 'Memory',
-  tasks: 'Tasks',
-  assets: 'Assets',
-  skills: 'Skills',
-  vault: 'Vault',
-  setup: 'Setup',
-  identity: 'Identity',
-  entities: 'Entities',
+  lanes_memory: 'Memory',
+  lanes_tasks: 'Tasks',
+  lanes_assets: 'Assets',
+  lanes_skills: 'Skills',
+  lanes_vault: 'Vault',
+  lanes_setup: 'Setup',
+  lanes_identity: 'Identity',
+  lanes_entities: 'Entities',
 } as const;
 
 type ReservedSurface = keyof typeof RESERVED_SURFACES;
@@ -56,13 +54,13 @@ type ReservedSurface = keyof typeof RESERVED_SURFACES;
  * template writes and a diff between the two reads as a diff.
  */
 export const DEFAULT_SURFACES: readonly ReservedSurface[] = [
-  'memory',
-  'tasks',
-  'assets',
-  'skills',
-  'vault',
-  'setup',
-  'entities',
+  'lanes_memory',
+  'lanes_tasks',
+  'lanes_assets',
+  'lanes_skills',
+  'lanes_vault',
+  'lanes_setup',
+  'lanes_entities',
 ];
 
 /**
@@ -121,18 +119,37 @@ export function ensureReservedConnection(
   const rows = Array.isArray(workspace?.connections) ? workspace.connections : [];
   const held_grants = Array.isArray(config?.grants) ? config.grants : [];
 
-  // The row this profile would use. Any instance of the provider will do, and
-  // the *first* one is taken rather than `main` specifically: an operator who
-  // renamed theirs should not get a second one bolted on beside it.
-  const existing = rows.find(
-    (row) => (row as { provider?: unknown } | null)?.provider === provider,
-  ) as { id?: unknown } | undefined;
-  const id = typeof existing?.id === 'string' ? existing.id : 'main';
-  const key = `${provider}.${id}`;
-
-  const held = held_grants.find(
-    (row) => (row as { connection?: unknown } | null)?.connection === key,
-  ) as { allow?: unknown; deny?: unknown } | undefined;
+  // **This profile's own grant comes first.** Any instance of the provider will
+  // do, and the *first* one is taken rather than `main` specifically: an
+  // operator who renamed theirs should not get a second one bolted on beside
+  // it. That reasoning was right and the lookup implementing it was not — it
+  // read the workspace's first row, which under contract 2 was this profile's
+  // because a profile carried its own connections, and under contract 3 is
+  // whichever profile sorts first.
+  //
+  // So the repair asked whether `personal` granted `memory.main` — demo's — saw
+  // that it did not, and set about adding it. For `vault` and `skills` the
+  // schema refuses a second grant and the save failed loudly, which is how this
+  // was found. For `memory`, `tasks`, `assets`, `setup` and `entities` nothing
+  // refuses it, and the profile would quietly have been granted another
+  // profile's notes and another profile's task list — the outcome ADR-059
+  // exists to prevent, arriving from the repair rather than the migration.
+  //
+  // **Every** instance, not the first one matched. A profile may grant two —
+  // `memory.team` and `memory.personal` — and reading only the first let a deny
+  // on the other be stepped around: the repair widened the undenied row and
+  // reported the surface granted, which is the one thing the paragraph below
+  // says it must never do.
+  //
+  // `startsWith` rather than slicing at the dot, because these rows are raw
+  // unvalidated YAML: `indexOf` answers -1 for a value with no dot at all, and
+  // `'vaults'.slice(0, -1)` is `'vault'` — so a typo'd `connection: vaults`
+  // matched the vault surface and was widened while the real one stayed
+  // unreachable.
+  const mine = held_grants.filter((row) => {
+    const connection = (row as { connection?: unknown } | null)?.connection;
+    return typeof connection === 'string' && connection.startsWith(`${provider}.`);
+  }) as { connection?: string; allow?: unknown; deny?: unknown }[];
 
   // Denied on purpose, and a deny beats an allow — so writing the rule would
   // widen nothing while announcing that an agent can now read the surface,
@@ -143,18 +160,53 @@ export function ensureReservedConnection(
   // Only a rule covering the whole surface counts. `deny: [setup.provider]` is
   // an operator narrowing it, not switching it off, and that narrowing survives
   // the repair untouched — which is the point of denying one capability.
-  if (patternsIn(held?.deny).some(covers)) return { changes: [], granted: [] };
+  if (mine.some((row) => patternsIn(row.deny).some(covers))) return { changes: [], granted: [] };
+
+  // The instance already carrying the rule, if any. Not an early return: the
+  // workspace row can be missing while the grant is present — a profile written
+  // before the surface existed, repaired once against a `connections.yaml` that
+  // has since been hand-edited — and repairing one half only is what this
+  // function exists to prevent.
+  const allowed = mine.find((row) => patternsIn(row.allow).some(covers));
+
+  // Otherwise the first row that exists and grants nothing is the one to widen.
+  const owned = allowed ?? mine[0];
+
+  // Only when this profile grants no instance of the provider at all is the
+  // workspace consulted, which is the case this was written for: a surface that
+  // did not exist when the profile was written.
+  const declared = rows.find(
+    (row) => (row as { provider?: unknown } | null)?.provider === provider,
+  ) as { id?: unknown } | undefined;
+
+  // The id an existing row already has, else the next free one. Opaque and
+  // allocated across the whole workspace, so `lan3` names exactly one row
+  // however many surfaces a repair adds in one pass.
+  const taken = rows.flatMap((row) => {
+    const id = (row as { id?: unknown } | null)?.id;
+    return typeof id === 'string' ? [id] : [];
+  });
+  const id = typeof declared?.id === 'string' ? declared.id : nextConnectionId(taken, true);
+
+  const key = owned?.connection ?? `${provider}.${id}`;
+
+  // Whether the *workspace* needs a row, which is a separate question from
+  // which one this profile grants: a profile cannot grant a connection that is
+  // not declared, so `owned` implies `declared`.
+  const existing = declared;
+  const held = owned;
 
   const changes: string[] = [];
   const granted: string[] = [];
 
   if (existing === undefined) {
-    // Inline, and `main` for the id, so a repaired workspace is spelled exactly
-    // like `newConnectionsTemplate` writes a fresh one. Two spellings of one row
-    // is how a template and its repair drift apart.
+    // Inline, and the allocated id, so a repaired workspace is spelled exactly
+    // like `newConnectionsTemplate` writes a fresh one — which is what
+    // `config-edit.test.ts` asserts by checking a fresh profile needs no repair.
+    // Two spellings of one row is how a template and its repair drift apart.
     connections.addTo(
       ['connections'],
-      { id: 'main', provider, account: RESERVED_SURFACES[provider] },
+      { id, provider, account: RESERVED_SURFACES[provider] },
       { inline: true },
     );
     changes.push(`connections.yaml += ${key}`);
@@ -166,7 +218,7 @@ export function ensureReservedConnection(
     profile.addTo(['grants'], { connection: key, allow: [rule], deny: [] }, { inline: true });
     changes.push(`grants += ${key}`);
     granted.push(rule);
-  } else if (!patternsIn(held.allow).some(covers)) {
+  } else if (allowed === undefined) {
     // A row that exists and grants nothing is a surface that is present and
     // silent. Widening it back is the repair; the deny check above is what stops
     // this undoing a deliberate narrowing.
@@ -178,28 +230,7 @@ export function ensureReservedConnection(
   return { changes, granted };
 }
 
-/** The workspace's connections document, written from the template if missing. */
-async function openOrCreateConnections(workspaceRoot: string): Promise<ConfigDocument> {
-  try {
-    return await ConfigDocument.openKey(workspaceRoot, CONNECTIONS_FILE);
-  } catch {
-    await writeWorkspaceFile(
-      workspaceFiles(workspaceRoot),
-      CONNECTIONS_FILE,
-      newConnectionsTemplate(),
-    );
-    return ConfigDocument.openKey(workspaceRoot, CONNECTIONS_FILE);
-  }
-}
-
 /** Whether a repair did anything, without a caller adding up two lists. */
-/** `memory, tasks, assets, skills, vault, setup and entities`, in repair order. */
-function listSurfaces(): string {
-  const names = [...DEFAULT_SURFACES];
-  const last = names.pop();
-  return names.length === 0 ? String(last) : `${names.join(', ')} and ${last}`;
-}
-
 export function repaired(repair: SurfaceRepair): boolean {
   return repair.changes.length > 0 || repair.granted.length > 0;
 }
@@ -286,88 +317,6 @@ export function ensureIdentityConnection(
   connections: ConfigDocument,
   profile: ConfigDocument,
 ): SurfaceRepair {
-  return ensureReservedConnection(connections, profile, 'identity');
+  return ensureReservedConnection(connections, profile, 'lanes_identity');
 }
 
-/**
- * Apply that repair across a workspace, saving and reporting what changed.
- *
- * Here rather than in `#deployments`, where it was, because `start` needs it as
- * much as `deploy` does — more, in fact: `start` is the one command an existing
- * install runs without being asked to, so it is the path by which a profile
- * written before ADR-050 gets the layer at all. Two copies of a function that
- * widens a policy is not a thing to have.
- *
- * **The caller scopes it**, and for `deploy` that is exactly the set being
- * uploaded: a profile it sends is a profile the endpoint will serve, so
- * repairing a narrower set would leave a served profile without the surfaces.
- * Note what a `--profile` flag does not mean — it is the flag alone, so a
- * profile resolved from the environment leaves it undefined and that reads as
- * the whole workspace.
- *
- * *Which files are profiles* comes from `listProfiles`, never from an allowlist
- * of what is safe to copy: that would happily hand over a committed
- * `personal.example.yaml` or a nested `profiles/archive/old.yaml`, and this
- * opens and validates what it is given — which once turned a template into a
- * `ConfigError` aborting a deploy after provisioning had made cloud resources.
- *
- * A profile that cannot be read is warned about rather than fatal: the repair is
- * a courtesy on the way past, and the caller's real work should still happen.
- * Not silent, though — nothing else widens a policy without being asked.
- *
- * CLI-side by construction, like everything else in this file: a deployed
- * revision holds `objectViewer` on `profiles/` (ADR-023) and could not write
- * this even if the code let it.
- */
-export async function repairOwnerLayer(
-  workspaceRoot: string,
-  profiles: readonly string[] | undefined,
-  options: { report?: (line: string) => void } = {},
-): Promise<void> {
-  // stdout by default, because every caller but one is printing a report a
-  // person reads. `update --json` passes `progress` instead: what it produces is
-  // a document, and a line of prose in front of it corrupts whatever is parsing.
-  // Routed rather than silenced — nothing else here widens a policy without
-  // saying so, and this must not be the exception.
-  const say = options.report ?? print;
-  const wanted = profiles === undefined ? undefined : new Set(profiles);
-
-  // One connections document for the whole sweep. The owner layer is the
-  // workspace's now (ADR-059), so repairing three profiles must not add three
-  // `memory.main` rows — opening it once and saving it once is what makes the
-  // second profile see what the first one created.
-  // Created if absent rather than refused. A contract-3 workspace always has
-  // one, but a hand-made or half-migrated one may not — and this is the repair,
-  // so the file it needs is a thing to write rather than a reason to stop.
-  const connections = await openOrCreateConnections(workspaceRoot);
-  let connectionsChanged = false;
-
-  for (const name of await listProfiles(workspaceRoot)) {
-    if (wanted !== undefined && !wanted.has(name)) continue;
-
-    try {
-      const document = await ConfigDocument.open(workspaceRoot, name);
-      const repair = ensureOwnerLayer(connections, document);
-      if (!repaired(repair)) continue;
-
-      connectionsChanged = true;
-      await document.save();
-
-      say(ok(`gave ${style.bold(name)} its own owner layer`));
-      for (const change of repairLines(repair)) say(`      ${style.dim(change)}`);
-      // Built from `DEFAULT_SURFACES` rather than typed out. The typed-out
-      // version still named six after a seventh had been added, so a person
-      // watching a deploy was told entities had arrived on the line above and
-      // that the layer was six things on the line below.
-      say(`      ${style.dim(`${listSurfaces()} — your own material, no account behind any of them`)}`);
-    } catch (error) {
-      say(
-        warn(
-          `could not give ${name} its owner layer: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`,
-        ),
-      );
-    }
-  }
-
-  if (connectionsChanged) await connections.save();
-}

package/src/cli/config-templates.ts

@@ -27,7 +27,7 @@ export function newProfileTemplate(profile: string, port: number, subject?: stri
 #
 # Edit it by hand or through the CLI; both are supported, and CLI edits preserve
 # your comments and ordering.
-contract: 3
+contract: 4
 
 instance:
   profile: ${profile}
@@ -90,17 +90,17 @@ limits:
 # works, because the next connect or deploy puts it back. The three narrowings
 # worth knowing:
 #
-#   deny: [memory.write]        remember nothing new
-#   deny: [skills.manage.*]     invoke procedures, do not write them
-#   deny: [vault.put, vault.remove]
+#   deny: [lanes_memory.write]     remember nothing new
+#   deny: [lanes_skills.manage.*]  invoke procedures, do not write them
+#   deny: [lanes_vault.put, lanes_vault.remove]
 grants:
-  - { connection: memory.main, allow: [memory.*], deny: [] }
-  - { connection: tasks.main, allow: [tasks.*], deny: [] }
-  - { connection: assets.main, allow: [assets.*], deny: [] }
-  - { connection: skills.main, allow: [skills.*], deny: [] }
-  - { connection: vault.main, allow: [vault.*], deny: [] }
-  - { connection: setup.main, allow: [setup.*], deny: [] }
-  - { connection: entities.main, allow: [entities.*], deny: [] }
+  - { connection: lanes_memory.lan1, allow: [lanes_memory.*], deny: [] }
+  - { connection: lanes_tasks.lan2, allow: [lanes_tasks.*], deny: [] }
+  - { connection: lanes_assets.lan3, allow: [lanes_assets.*], deny: [] }
+  - { connection: lanes_skills.lan4, allow: [lanes_skills.*], deny: [] }
+  - { connection: lanes_vault.lan5, allow: [lanes_vault.*], deny: [] }
+  - { connection: lanes_setup.lan6, allow: [lanes_setup.*], deny: [] }
+  - { connection: lanes_entities.lan7, allow: [lanes_entities.*], deny: [] }
 
 # Who may consume this profile (ADR-060).
 #
@@ -146,7 +146,7 @@ export function newWorkspaceTemplate(): string {
 # uses it prints which one it got. Commands that publish or destroy — deploy,
 # sync, secrets push, profile remove, disconnect, token rotate — refuse it and
 # make you type the name (ADR-061).
-contract: 3
+contract: 4
 default_workspace: local
 workspaces:
   local:
@@ -176,20 +176,22 @@ export function newConnectionsTemplate(): string {
 # this list says whose data is reachable without having to look anything up.
 # "label" is your own word for the same row, and only ever displayed.
 #
-# The seven below hold no account: they reach your own material rather than
-# anybody's API, so there was never anything for a connect step to authorise
-# (ADR-050). Make a second one — "lanes link connect memory --id work" — when you
-# want two profiles to share nothing.
-contract: 3
+# The "lanes_" rows are Lanes' own surfaces and hold no account: they reach your
+# own material rather than anybody's API, so there was never anything for a
+# connect step to authorise (ADR-050). Every profile grants the same ones and
+# still keeps its own bytes — what you write through one profile is absent in
+# another (ADR-066). A second instance is for holding two of something in one
+# profile: "lanes link connect lanes_memory --id lan9".
+contract: 4
 
 connections:
-  - { id: main, provider: memory, account: Memory }
-  - { id: main, provider: tasks, account: Tasks }
-  - { id: main, provider: assets, account: Assets }
-  - { id: main, provider: skills, account: Skills }
-  - { id: main, provider: vault, account: Vault }
-  - { id: main, provider: setup, account: Setup }
-  - { id: main, provider: entities, account: Entities }
+  - { id: lan1, provider: lanes_memory, account: Memory }
+  - { id: lan2, provider: lanes_tasks, account: Tasks }
+  - { id: lan3, provider: lanes_assets, account: Assets }
+  - { id: lan4, provider: lanes_skills, account: Skills }
+  - { id: lan5, provider: lanes_vault, account: Vault }
+  - { id: lan6, provider: lanes_setup, account: Setup }
+  - { id: lan7, provider: lanes_entities, account: Entities }
 
 # App registrations, shared by every connection of that vendor.
 oauth_apps: {}

package/src/cli/contract3-credentials.ts

@@ -0,0 +1,294 @@
+import { ConfigError, LEGACY_DATA_DIR, isRemoteWorkspace } from '#profile';
+import { C3 } from './contract3-layout.ts';
+import { createFileSecretStore } from '#secrets';
+
+/**
+ * The credential half of the contract-3 migration.
+ *
+ * Split from `contract3-data.ts` when that file outgrew the budget, on the seam
+ * the migration already had: objects move, credentials merge, and the two obey
+ * different rules. A moved object has one home and the move is reversible by
+ * moving it back. A merged credential has to survive two profiles claiming one
+ * ref, and the wrong resolution points a live connection at somebody else's
+ * account — so nothing here picks between two values, ever.
+ *
+ * The whole file is ordered around one promise: every refusal happens before
+ * the first write.
+ */
+
+/**
+ * What this migration needs to know about one profile's credentials.
+ *
+ * Assembled by `contract3.ts` from the hoist, because the two facts below are
+ * decisions that file already made and this one must not make differently.
+ */
+export interface CredentialPlan {
+  readonly profile: string;
+  /** Every connection-derived credential ref, and where it is going. */
+  readonly renames: ReadonlyMap<string, RefTarget>;
+  /** This profile's endpoint token ref, which is deliberately not migrated. */
+  readonly tokenRef: string;
+}
+
+/** What the merged credential store will hold, and what was left out of it. */
+export interface CredentialMerge {
+  /** Refs the merged store will hold, sorted. */
+  readonly refs: readonly string[];
+  /** Endpoint token refs left behind rather than merged, sorted. */
+  readonly tokens: readonly string[];
+}
+
+/** Where a credential ref is going, and which connection it belongs to after. */
+export interface RefTarget {
+  readonly to: string;
+  /** The settled `provider.id` this ref's connection became. */
+  readonly connection: string;
+}
+
+/**
+ * The credential ref of every connection the hoist touched, renamed or not.
+ *
+ * `credentialRefForConnection` derives `${app ?? provider}/${connectionId}` for
+ * every auth kind that has a per-connection credential, and `hoistConnections`
+ * renames the connection with `{ ...connection, id }` — which leaves the derived
+ * ref pointing at the old id. So a profile whose `github.main` became
+ * `github.main_2` still claimed `github/main`, and two profiles claiming one ref
+ * with two different tokens is what aborted the migration.
+ *
+ * **Unrenamed connections are in here too**, which is not redundancy: the
+ * `connection` half is what tells `readMerged` that two refs landing on one
+ * target belong to the same connection and are therefore a merge rather than a
+ * clash. Without it a single profile declaring `gmail.main` and `gmail.archive`
+ * for one mailbox — legal under contract 2, and the reason tokens are
+ * per-connection at all, since the scopes differ — was hoisted into one row and
+ * then refused with "Two profiles hold different values", naming one profile
+ * twice and prescribing a rename that cannot help.
+ *
+ * Only the `<provider>/<id>` spelling is derived here. A provider declaring
+ * `auth.app` stores under `<app>/<id>` and a row carrying an explicit
+ * `credential_ref` stores wherever it says — neither is reconstructable without
+ * the manifest, which this migration does not load. Those refs are carried
+ * across untouched, and a genuine clash between two of them is refused by name.
+ */
+export function connectionRefs(mapping: ReadonlyMap<string, string>): Map<string, RefTarget> {
+  const refs = new Map<string, RefTarget>();
+
+  for (const [from, to] of mapping) {
+    const before = from.indexOf('.');
+    const after = to.indexOf('.');
+    if (before < 0 || after < 0) continue;
+    refs.set(`${from.slice(0, before)}/${from.slice(before + 1)}`, {
+      to: `${to.slice(0, after)}/${to.slice(after + 1)}`,
+      connection: to,
+    });
+  }
+
+  return refs;
+}
+
+/**
+ * Every credential the merged store will hold, addressed as contract 3 will
+ * address it.
+ *
+ * One walk, shared by the preview and the apply, because the two disagreeing is
+ * the defect this replaces: `planCredentials` collected the union of ref *names*
+ * and never compared values, so a clash it could not see aborted
+ * `mergeCredentials` — at which point `rewriteRegistry` and `writeConnections`
+ * had already run, and the workspace was half-migrated behind a message saying
+ * nothing had been written.
+ *
+ * Read-only. Everything that can refuse, refuses here.
+ *
+ * **A workspace in a bucket has nothing to merge, and this says so rather than
+ * finding out.** `workspacePath` refuses a filesystem adapter against a remote
+ * root, so the only credential store such a workspace can declare is
+ * `gcp-secret-manager` — whose refs were never scoped by profile, and are
+ * therefore already what contract 3 wants. Without the guard the path below is
+ * built by string interpolation into `gs://bucket/data/<profile>/credentials.enc`
+ * and handed to `Bun.file`, where the failure is swallowed by the `catch` and
+ * reads exactly like a workspace with no credentials in it.
+ */
+async function readMerged(
+  root: string,
+  plans: readonly CredentialPlan[],
+): Promise<{ merged: Map<string, string>; tokens: Set<string> }> {
+  const merged = new Map<string, string>();
+  const held = new Map<string, { profile: string; connection?: string }>();
+  // One entry per endpoint-token ref, holding what each profile had under it.
+  // Decided after the walk, because whether it can be carried across depends on
+  // whether the profiles agree — which is not known until they have all been read.
+  const endpoint = new Map<string, Map<string, string>>();
+  const tokens = new Set<string>();
+
+  if (isRemoteWorkspace(root)) return { merged, tokens };
+
+  for (const plan of plans) {
+    const store = createFileSecretStore({
+      path: `${root}/${LEGACY_DATA_DIR}/${plan.profile}/credentials.enc`,
+    });
+
+    let refs: string[];
+    try {
+      refs = await store.list();
+    } catch {
+      // A store that will not open is reported by `doctor`, not here. This runs
+      // as a preview too, and must not fail on a workspace that is already
+      // broken.
+      continue;
+    }
+
+    for (const ref of refs) {
+      // The endpoint's own bearer token, which every profile keeps under the
+      // same ref because `authSchema` defaults `token_ref` to `profile/token`.
+      // Under contract 2 that was unambiguous — one store per profile. Under
+      // contract 3 there is one store, so three profiles' tokens are three
+      // values for one key, and there is no merge that means anything.
+      //
+      // Left behind rather than picked between. It is minted locally rather
+      // than granted by anybody, `ensureProfileToken` writes a fresh one the
+      // first time a command asks, and the old stores are not deleted — so the
+      // cost is re-registering a client, and no account has to be authorised
+      // again.
+      let value: string | null;
+      try {
+        value = await store.get(ref);
+      } catch {
+        continue;
+      }
+      if (value === null) continue;
+
+      // The endpoint's own bearer token, held under one ref by every profile
+      // because `authSchema` defaults `token_ref` to `profile/token`. Set aside
+      // rather than merged here; see below.
+      if (ref === plan.tokenRef) {
+        const seen = endpoint.get(ref) ?? new Map<string, string>();
+        seen.set(plan.profile, value);
+        endpoint.set(ref, seen);
+        continue;
+      }
+
+      const mapped = plan.renames.get(ref);
+      const target = mapped?.to ?? ref;
+      const first = merged.get(target);
+
+      if (first !== undefined) {
+        if (first === value) continue;
+
+        // Two refs on one target whose connections are the same connection.
+        // That is the hoist merging two rows for one account — legal under
+        // contract 2, where `gmail.main` and `gmail.archive` could hold the
+        // same mailbox at different scopes — and there is one connection now,
+        // so one token. The first row is the one that survived the hoist, so
+        // its credential is the one that belongs to it.
+        const owner = held.get(target);
+        if (mapped !== undefined && owner?.connection === mapped.connection) continue;
+
+        throw new ConfigError(
+          `Two credentials want to be at "${target}", and this migration cannot choose ` +
+            `between them.\n` +
+            `  ${owner?.profile ?? 'another profile'} and ${plan.profile} both hold one. Both ` +
+            `are real credentials, and picking either would point a connection at the wrong ` +
+            `account.\n` +
+            `  Nothing has been written. Give one of them its own credential_ref before ` +
+            `migrating.`,
+        );
+      }
+
+      merged.set(target, value);
+      held.set(target, {
+        profile: plan.profile,
+        ...(mapped === undefined ? {} : { connection: mapped.connection }),
+      });
+    }
+  }
+
+  // **A token is only left behind when the profiles disagree about it.**
+  //
+  // Under contract 2 each profile had its own store, so one ref meant one value
+  // per profile and contract 3's single store cannot hold three of them. But a
+  // workspace with one profile — or three that were registered from the same
+  // token — has nothing to choose between, and dropping it there was gratuitous:
+  // every client registered against that endpoint started getting 401s after a
+  // routine `update`, for a conflict that did not exist.
+  //
+  // Where they do disagree it is still left behind rather than picked between.
+  // It is minted locally rather than granted by anybody, `ensureProfileToken`
+  // writes a fresh one the first time a command asks, and the old stores are not
+  // deleted — so the cost is re-registering a client, and no account has to be
+  // authorised again.
+  for (const [ref, byProfile] of endpoint) {
+    const values = new Set(byProfile.values());
+    const agreed = values.size === 1 ? [...values][0] : undefined;
+
+    if (agreed === undefined || merged.has(ref)) {
+      tokens.add(ref);
+      continue;
+    }
+
+    merged.set(ref, agreed);
+    held.set(ref, { profile: [...byProfile.keys()].join(', ') });
+  }
+
+  return { merged, tokens };
+}
+
+/**
+ * What the merge will do, computed before anything is written.
+ *
+ * The report an operator confirms is therefore the real one, and a refusal
+ * leaves the workspace exactly as it was.
+ */
+export async function planCredentials(
+  root: string,
+  plans: readonly CredentialPlan[],
+): Promise<CredentialMerge> {
+  const { merged, tokens } = await readMerged(root, plans);
+  return { refs: [...merged.keys()].sort(), tokens: [...tokens].sort() };
+}
+
+/**
+ * Copy every profile's credentials into the workspace store.
+ *
+ * Written and read back before the old stores are touched, which is the whole
+ * of the safety argument: a half-finished merge that has not deleted anything is
+ * recoverable by running it again, and one that deleted first is not.
+ *
+ * The old stores are left in place regardless. They are a few kilobytes, they
+ * are the only copy of anything if this went wrong, and `doctor` names them so
+ * an operator can remove them once the endpoint has served a request.
+ *
+ * Skipped entirely for a workspace in a bucket, for the reason `readMerged`
+ * gives: its credentials are in Secret Manager under refs that were never
+ * per-profile, so there is no second store to fold in.
+ */
+export async function mergeCredentials(
+  root: string,
+  plans: readonly CredentialPlan[],
+): Promise<void> {
+  if (isRemoteWorkspace(root)) return;
+
+  const { merged } = await readMerged(root, plans);
+  const destination = createFileSecretStore({ path: `${root}/${C3.credentials()}` });
+
+  for (const [ref, value] of merged) {
+    const already = await destination.get(ref);
+    if (already !== null) {
+      // Already copied, by a run that did not get to the end. Anything else is
+      // a store that disagrees with the profiles it was built from, which is
+      // not something to overwrite silently.
+      if (already === value) continue;
+      throw new ConfigError(
+        `${C3.credentials()} already holds a different value for "${ref}" than the profile ` +
+          `stores do. Nothing has been deleted; resolve it and run this again.`,
+      );
+    }
+
+    await destination.set(ref, value);
+    if ((await destination.get(ref)) !== value) {
+      throw new ConfigError(
+        `The credential "${ref}" did not read back after being written to ` +
+          `${C3.credentials()}. Nothing has been deleted; fix the store and run this again.`,
+      );
+    }
+  }
+}