@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/contract4-yaml.ts

@@ -0,0 +1,223 @@
+import {
+  CONNECTIONS_FILE,
+  connectionsFileSchema,
+  ConfigError,
+  layout,
+  readWorkspaceFile,
+  workspaceFiles,
+} from '#profile';
+import { parseDocument } from 'yaml';
+import { ConfigDocument } from './config-edit.ts';
+import type { Renames } from './contract4-data.ts';
+
+/**
+ * The two YAML rewrites contract 4 makes, and the order between them.
+ *
+ * The grants go first and the rows second, with the stamp after both — every
+ * window that leaves is one a rerun closes, because both rewrites are
+ * idempotent: a grant or a row already naming the new ref is not in the map and
+ * is left alone. Renaming the rows first destroyed the only source the map is
+ * derived from, and the rerun then stamped a profile whose grants named a
+ * connection nothing declared.
+ */
+
+/**
+ * `memory.*` becomes `lanes_memory.*`, in either spelling a rule may take.
+ *
+ * A rule is a bare pattern string or `{ capability, expires_at }`, and an
+ * expiry has to survive: dropping it would turn a lapsing grant into a
+ * permanent one, which is the direction that fails unsafely.
+ */
+function retitle(rules: unknown, was: string, now: string): unknown {
+  if (!Array.isArray(rules)) return rules;
+
+  const moved = (pattern: string): string =>
+    pattern === was || pattern.startsWith(`${was}.`) ? `${now}${pattern.slice(was.length)}` : pattern;
+
+  return rules.map((rule) => {
+    if (typeof rule === 'string') return moved(rule);
+    const held = rule as { capability?: unknown };
+    return typeof held.capability === 'string'
+      ? { ...held, capability: moved(held.capability) }
+      : rule;
+  });
+}
+
+/**
+ * Every profile's grants, onto the ids and providers the rename settled.
+ *
+ * Its own pass rather than a step inside the stamping loop, because the two
+ * have to happen either side of `renameConnections` — the grants while the rows
+ * still carry the old ids, the stamp once everything else is done.
+ *
+ * A rule may only name the provider its row grants (ADR-058), so the
+ * `allow`/`deny` patterns move with the `connection` or the profile is one the
+ * loader refuses.
+ */
+export async function rewriteGrants(
+  root: string,
+  profiles: readonly string[],
+  renames: Renames,
+): Promise<void> {
+  for (const profile of profiles) {
+    const document = await ConfigDocument.openKey(root, layout.profileConfig(profile));
+
+    const held = document.toJSON() as { grants?: unknown };
+    const grants = held.grants;
+    if (!Array.isArray(grants)) continue;
+
+    // **Deduplicated, because the owner layer merges.** Every profile's own
+    // `memory` grant renames to `lanes_memory.lan1` (ADR-066), and a profile
+    // that granted two instances of one surface would emit two rows at one
+    // address — which `validateConfig` refuses, on the save below, after the
+    // registry and every byte have already moved.
+    const seen = new Set<string>();
+
+    document.setIn(
+      ['grants'],
+      grants.flatMap((grant) => {
+        const one = grant as { connection?: unknown; allow?: unknown; deny?: unknown };
+        const ref = typeof one.connection === 'string' ? one.connection : undefined;
+        if (ref === undefined) return [grant];
+
+        const to = renames.get(ref) ?? ref;
+        if (seen.has(to)) return [];
+        seen.add(to);
+
+        const was = ref.slice(0, ref.indexOf('.'));
+        const now = to.slice(0, to.indexOf('.'));
+
+        return [
+          {
+            ...one,
+            connection: to,
+            ...(was === now
+              ? {}
+              : { allow: retitle(one.allow, was, now), deny: retitle(one.deny, was, now) }),
+          },
+        ];
+      }),
+    );
+
+    // `shapeOnly`, because the rows still name the old ids at this point and
+    // `assertGrantsResolve` would refuse a grant it cannot yet resolve. The
+    // secret-shaped-value check and the schema both still run.
+    await document.save({ shapeOnly: true, contract: 3 });
+  }
+}
+
+/** Every connection row, however far through the migration this workspace is. */
+/**
+ * Refuse a `connections.yaml` the rewrite at the end could not have saved.
+ *
+ * `readConnectionRows` reads raw and drops a row it cannot understand, which is
+ * what lets it run before the guard that would block its own fix — but it means
+ * a malformed file yields *fewer* rows rather than an error, and a rehearsal
+ * found what that costs: the rename map came out empty, every byte moved
+ * verbatim into the profiles, and the validating save at the very end refused.
+ * `data/` was then empty, so a rerun had nothing to move and left the bytes at
+ * their old ids while the rows moved on without them.
+ *
+ * So it is checked here, before the first byte moves, which is where this
+ * migration says everything that can fail belongs. Deliberately *not*
+ * `readConnections`: that one also runs `assertNoRenamedProviders`, and a
+ * workspace holding `tasks` is the workspace this migration exists to repair.
+ */
+export async function assertConnectionsSavable(root: string): Promise<void> {
+  const text = await readWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE);
+  if (text === null) return;
+
+  const parsed = connectionsFileSchema.safeParse(parseDocument(text).toJSON());
+  if (parsed.success) return;
+
+  throw new ConfigError(
+    `${CONNECTIONS_FILE} is not valid, and this migration rewrites it — so it stops here,\n` +
+      '  with the workspace exactly as it was. Fix these, then run it again:\n' +
+      parsed.error.issues.map((issue) => `  ${issue.path.join('.')}: ${issue.message}`).join('\n'),
+  );
+}
+
+export async function readConnectionRows(
+  root: string,
+  full = false,
+): Promise<{ id: string; provider: string; account: string; credential_ref?: string }[]> {
+  const text = await readWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE);
+  if (text === null) return [];
+
+  const held = parseDocument(text).toJSON() as { connections?: unknown };
+  if (!Array.isArray(held.connections)) return [];
+
+  return held.connections.flatMap((row) => {
+    const one = row as { id?: unknown; provider?: unknown; account?: unknown };
+    if (typeof one.id !== 'string' || typeof one.provider !== 'string') return [];
+
+    // `account` matters only to `credentialRefFor`, which reads a row's own
+    // `credential_ref` off it; the id and provider are all the rest wants.
+    return [
+      {
+        ...(full ? (row as object) : {}),
+        id: one.id,
+        provider: one.provider,
+        account: typeof one.account === 'string' ? one.account : '',
+      },
+    ];
+  });
+}
+
+/**
+ * The ids, in `connections.yaml` and in the credential store's refs.
+ *
+ * A `credential_ref` defaults to `<provider>/<connection>` and is derived
+ * rather than written, so the rows carry no ref to update — but a connection
+ * that *declares* one, and every `oauth_apps` entry, is a string naming an id
+ * and has to move with it.
+ */
+export async function renameConnections(root: string, renames: Renames): Promise<void> {
+  const document = await ConfigDocument.openKey(root, CONNECTIONS_FILE);
+
+  // `toJSON()`, not `getIn`: `getIn` hands back YAML nodes rather than plain
+  // JS, so an `Array.isArray` on the result is false and the rewrite silently
+  // does nothing — which is exactly what it did, and the migration reported
+  // success with every id unchanged.
+  const held = document.toJSON() as { connections?: unknown };
+  if (!Array.isArray(held.connections)) return;
+
+  // **Deduplicated, because the owner layer merges.** Three profiles' own
+  // `memory` rows all rename to `lanes_memory.lan1` (ADR-066), and keeping
+  // three of them would be three rows at one address — which
+  // `assertConnectionsUnique` refuses, on the save at the end of this. The
+  // first row wins and the rest are dropped; the *bytes* are not merged, they
+  // land under each profile's own directory.
+  const seen = new Set<string>();
+  const rows = held.connections.flatMap((row) => {
+    const one = row as { id?: unknown; provider?: unknown };
+    if (typeof one.id !== 'string' || typeof one.provider !== 'string') return [row];
+
+    const to = renames.get(`${one.provider}.${one.id}`);
+    if (to === undefined) return [row];
+    if (seen.has(to)) return [];
+    seen.add(to);
+
+    // Both halves. The provider moved for the owner layer (`memory` became
+    // `lanes_memory`) and the id moved for everything unallocated, and a row
+    // that took one without the other names a connection nothing resolves.
+    const dot = to.indexOf('.');
+    return [{ ...one, provider: to.slice(0, dot), id: to.slice(dot + 1) }];
+  });
+
+  // **Lanes' own rows last, and the accounts in file order.** Nothing reads the
+  // order, but somebody does: interleaved, `con17` landed between `lan14` and
+  // `lan15` and the file read as though the numbering had gone wrong.
+  const owned = (row: unknown): boolean =>
+    typeof (row as { provider?: unknown }).provider === 'string' &&
+    (row as { provider: string }).provider.startsWith('lanes_');
+
+  document.setIn(['connections'], [...rows.filter((r) => !owned(r)), ...rows.filter(owned)]);
+
+  // The stamp this file was missing. Nothing reads it — every contract check is
+  // on a profile — which is exactly why it went stale, and a marker that lies
+  // is worse than no marker for whoever writes the next migration.
+  document.setIn(['contract'], 4);
+
+  await document.save();
+}

package/src/cli/contract4.ts

@@ -0,0 +1,342 @@
+import {
+  ConfigError,
+  layout,
+  listProfiles,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+  WORKSPACE_FILE,
+  CONNECTIONS_FILE,
+  openTarget,
+} from '#profile';
+import { parseDocument } from 'yaml';
+import { ConfigDocument } from './config-edit.ts';
+import { C3 } from './contract3-layout.ts';
+import { grantingProfiles, planMoves, type DataPlan, type Renames } from './contract4-data.ts';
+import { planRenames } from './contract4-rename.ts';
+import {
+  assertConnectionsSavable,
+  readConnectionRows,
+  renameConnections,
+  rewriteGrants,
+} from './contract4-yaml.ts';
+import { applyMoves, assertOneObjectPerDestination } from './migrate-move.ts';
+import {
+  applyCredentialMoves,
+  planCredentialMoves,
+  planVaultMoves,
+} from './contract4-credentials.ts';
+import { openSecretStoreFor } from './runtime/select.ts';
+import { buildRegistryWithWorkspace } from './runtime/registry.ts';
+
+/**
+ * Contract 3 to contract 4: a profile owns its data again.
+ *
+ * Contract 3 moved every account up to the workspace and, in the same sweep,
+ * moved the owner layer's bytes beside the *connection* — so a profile owned
+ * nothing and the shipped default had every profile granting one memory.
+ * ADR-066 reverses that half; ADR-067 collapses a profile into one directory
+ * and retires `data/`, which had stopped meaning anything once the declaration
+ * moved in beside the bytes.
+ *
+ * Four steps, ordered so a crash between any two leaves a workspace that still
+ * opens:
+ *
+ *   1. The registry is renamed. One document, cannot half-apply.
+ *   2. Bytes move — the workspace's up out of `data/`, a profile's into its
+ *      directory.
+ *   3. Declarations move into the directories they now name.
+ *   4. Each profile is stamped `contract: 4`.
+ *
+ * **The stamp is last, and it is the record that this finished** rather than a
+ * step among steps. Contract 3 shipped with it written first, which left
+ * profiles claiming the new contract with every byte still at the old path and
+ * a rerun that read the stamp and found nothing to do.
+ *
+ * Every read here goes through `C3`, and every write through `layout`. A
+ * migration that asks the live layout for its *source* paths finds nothing to
+ * move the moment the next contract lands.
+ */
+
+export interface Contract4Migration {
+  readonly workspaceRoot: string;
+  readonly profiles: readonly string[];
+  readonly changes: readonly string[];
+  /** Copied into more than one profile, original left. The operator decides. */
+  readonly shared: DataPlan['shared'];
+  /** Granted by no profile. Left where it is. */
+  readonly orphaned: readonly string[];
+  readonly alreadyCurrent: boolean;
+}
+
+/** Whether this workspace still holds anything at contract 3. */
+export async function needsContract4(workspaceRoot: string): Promise<boolean> {
+  for (const profile of await listProfiles(workspaceRoot)) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 3) return true;
+  }
+  return false;
+}
+
+async function readProfile(
+  root: string,
+  profile: string,
+): Promise<{ contract?: number; grants?: { connection?: unknown }[] } | null> {
+  const files = workspaceFiles(root);
+  // The contract-3 path first: a profile still to be migrated is there, and one
+  // already migrated is at the new path. Reading only one shape makes a rerun
+  // after an interruption see half a workspace.
+  const text =
+    (await readWorkspaceFile(files, C3.profile(profile))) ??
+    (await readWorkspaceFile(files, layout.profileConfig(profile)));
+  if (text === null) return null;
+  try {
+    return parseDocument(text).toJSON() as { contract?: number };
+  } catch {
+    return null;
+  }
+}
+
+export async function migrateToContract4(
+  workspaceRoot: string,
+  options: { apply: boolean; target?: string } = { apply: true },
+): Promise<Contract4Migration> {
+  const target = options.target ?? 'local';
+  const names = await listProfiles(workspaceRoot);
+  const configs = new Map<string, { grants?: { connection?: unknown }[] }>();
+
+  for (const profile of names) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 3) configs.set(profile, raw);
+  }
+
+  if (configs.size === 0) {
+    return {
+      workspaceRoot,
+      profiles: [],
+      changes: [],
+      shared: [],
+      orphaned: [],
+      alreadyCurrent: true,
+    };
+  }
+
+  const profiles = [...configs.keys()];
+  const files = workspaceFiles(workspaceRoot);
+
+  // Every connection the workspace holds, and the id each ends up with. Built
+  // once and read by every rewrite below — the contract-3 mover's own bug was a
+  // map keyed one way and queried the other, which made the resolution a silent
+  // no-op and sent two profiles' blobs into one namespace.
+  await assertConnectionsSavable(workspaceRoot);
+
+  const rows = await readConnectionRows(workspaceRoot);
+  const renames = planRenames(rows);
+
+  const plan = await planMoves(files, grantingProfiles(configs), profiles, renames);
+
+  // Everything that can refuse, before the first byte moves. A `keep` move is
+  // exempt: two profiles granting one store are *meant* to write one source to
+  // two destinations, which is the shape this check exists to catch elsewhere.
+  assertOneObjectPerDestination(plan.moves.filter((move) => move.keep !== true));
+
+  const changes = [...describe(plan, profiles), ...repositoryNotes(configs, renames)];
+  if (!options.apply) {
+    return {
+      workspaceRoot,
+      profiles,
+      changes,
+      shared: plan.shared,
+      orphaned: plan.orphaned,
+      alreadyCurrent: false,
+    };
+  }
+
+  await renameRegistry(workspaceRoot);
+  await applyMoves(files, plan.moves);
+
+  // Credentials before the rows: a ref is derived from the id, so the rows must
+  // still name the old one for `planCredentialMoves` to compute the same pair
+  // on a rerun.
+  const credentials = await moveCredentials(workspaceRoot, target, rows, renames, configs);
+
+  // **The rows are renamed after the grants and before the stamp**, and every
+  // window that leaves is one a rerun closes. `connections.yaml` is the only
+  // source `planRenames` has, so renaming it before the grants destroyed the
+  // map mid-flight: the rerun read the new rows, computed `lan1 → lan1`, found
+  // no mapping for `memory.main`, and stamped a profile whose grants named a
+  // connection nothing declared — refused at load, and `needsContract4` false,
+  // so no migration would ever run again.
+  //
+  // Both rewrites are idempotent, which is what makes the order safe rather
+  // than merely better: a grant already naming the new ref is not in the map
+  // and is left alone, and so is a row.
+  await rewriteGrants(workspaceRoot, profiles, renames);
+  await renameConnections(workspaceRoot, renames);
+
+  // Last. The stamp is the record that the migration finished.
+  for (const profile of profiles) {
+    const document = await ConfigDocument.openKey(workspaceRoot, layout.profileConfig(profile));
+    document.setIn(['contract'], 4);
+    await document.save();
+  }
+
+  return {
+    workspaceRoot,
+    profiles,
+    changes: [...changes, ...credentials],
+    shared: plan.shared,
+    orphaned: plan.orphaned,
+    alreadyCurrent: false,
+  };
+}
+
+/**
+ * Move each stored credential to the ref its renamed connection now derives.
+ *
+ * **Throws rather than warns**, and that is the whole of its error handling. It
+ * warned once, and the rehearsal that found it showed why it must not: the
+ * warning was printed, `renameConnections` ran anyway, and the workspace came
+ * out with rows naming `gmail.con1` while the secret sat at
+ * `gmail/wjj_andrews`. A rerun cannot repair that — the rows are renamed, so
+ * the second run computes no rename for them and the old ref is orphaned with
+ * nothing left that knows what it belonged to.
+ *
+ * Failing here leaves the rows untouched, which is the state a rerun *can*
+ * finish from. Bytes that already moved are found in place and skipped.
+ */
+async function moveCredentials(
+  root: string,
+  target: string,
+  rows: readonly { id: string; provider: string }[],
+  renames: Renames,
+  profiles: ReadonlyMap<string, { grants?: { connection?: unknown }[] }>,
+): Promise<string[]> {
+  if (rows.length === 0) return [];
+
+  const [store, registry] = await Promise.all([
+    openSecretStoreFor(root, target),
+    buildRegistryWithWorkspace(root),
+  ]);
+
+  // `readConnectionRows`, not `readConnections`. The latter runs
+  // `assertNoRenamedProviders`, which refuses a `tasks` row — and a workspace
+  // holding one is exactly the workspace being migrated, so reading through the
+  // guard makes the refusal block its own fix. ADR-051's rule, met twice now: a
+  // refusal has to name a command, and the command has to be able to run.
+  // The vault's document is planned separately because `credentialRefFor`
+  // cannot name it — see `planVaultMoves`. One apply for both, so a source
+  // feeding several destinations is deleted once rather than per plan.
+  const declared = (await openTarget(root, target)).declared;
+
+  return await applyCredentialMoves(store, [
+    ...planCredentialMoves(await readConnectionRows(root, true), registry, renames),
+    ...(declared.vault?.adapter === 'secret'
+      ? planVaultMoves(profiles, renames, declared.vault.ref)
+      : []),
+  ]);
+}
+
+/**
+ * `lanes-link.yaml` becomes `workspaces.yaml`.
+ *
+ * Written then deleted rather than moved, so an interruption leaves both and
+ * `readWorkspace` — which prefers the new name — still opens the workspace.
+ * Losing this file is losing the address of every target.
+ */
+async function renameRegistry(root: string): Promise<void> {
+  const files = workspaceFiles(root);
+  if (await files.has(WORKSPACE_FILE)) return;
+
+  const text = await readWorkspaceFile(files, C3.workspace);
+  if (text === null) return;
+
+  await writeWorkspaceFile(files, WORKSPACE_FILE, text);
+  if ((await readWorkspaceFile(files, WORKSPACE_FILE)) === null) {
+    throw new ConfigError(
+      `${WORKSPACE_FILE} did not read back after being written. Nothing has been deleted; ` +
+        'fix the store and run this again.',
+    );
+  }
+  await files.delete(C3.workspace);
+}
+
+/**
+ * What a `knowledge:` repository needs done by hand, named rather than left.
+ *
+ * A profile keeping its memory and entities in GitHub addresses them by the
+ * connection id — an entry reaches the repository as `memory/<id>/<entry>.md`.
+ * Contract 4 renames the id, so the provider starts reading `memory/lan1/`
+ * while the repository still holds `memory/main/`: `memory_search` returns
+ * nothing and `entities_find` finds nobody, with the data sitting intact under
+ * the old name and nothing having failed.
+ *
+ * Not repaired here on purpose. Renaming directories in somebody's repository
+ * is a network write to a thing this migration does not own, and `applyMoves`
+ * cannot reach a GitHub store at all — so the honest move is to say exactly
+ * what to rename, which is one `git mv` per area. `removalPlan` warns about the
+ * same class for the same reason.
+ */
+function repositoryNotes(
+  configs: ReadonlyMap<string, { knowledge?: unknown; grants?: { connection?: unknown }[] }>,
+  renames: Renames,
+): string[] {
+  const notes: string[] = [];
+
+  for (const [profile, config] of configs) {
+    const repo = (config.knowledge as { repo?: unknown } | undefined)?.repo;
+    if (typeof repo !== 'string') continue;
+
+    for (const surface of ['memory', 'entities'] as const) {
+      const granted = (config.grants ?? [])
+        .map((grant) => grant.connection)
+        .find((ref): ref is string => typeof ref === 'string' && ref.startsWith(`${surface}.`));
+      if (granted === undefined) continue;
+
+      const to = renames.get(granted);
+      if (to === undefined) continue;
+
+      const was = granted.slice(granted.indexOf('.') + 1);
+      const now = to.slice(to.indexOf('.') + 1);
+      if (was === now) continue;
+
+      notes.push(
+        `${repo}: rename ${surface}/${was}/ to ${surface}/${now}/ — "${profile}" reads it by the ` +
+          'connection id, and nothing here can write to your repository',
+      );
+    }
+  }
+
+  return notes;
+}
+
+function describe(plan: DataPlan, profiles: readonly string[]): string[] {
+  const changes = [`${C3.workspace} → ${WORKSPACE_FILE}`];
+
+  for (const profile of profiles) {
+    changes.push(`${C3.profile(profile)} → ${layout.profileConfig(profile)}: contract 4`);
+  }
+
+  const moved = plan.moves.filter((move) => move.keep !== true).length;
+  if (moved > 0) changes.push(`${moved} object(s) moved out of data/`);
+
+  for (const { key, profiles: owners } of plan.shared) {
+    changes.push(`${key}: copied into ${owners.join(' and ')} — the original is left for you`);
+  }
+  for (const key of plan.orphaned) {
+    changes.push(`${key}: no profile grants it, so it stays where it is`);
+  }
+
+  // Said as what it is. Contract 3 merged these and deliberately did not delete
+  // them, so a workspace that came through it still holds a decryptable
+  // credential document per profile — and reporting that as an ungranted store
+  // reads as tidy-up rather than as a credential left on disk.
+  for (const key of plan.leftover) {
+    changes.push(
+      `${key}: a credential store contract 3 merged and left behind — its contents are in ` +
+        `${layout.credentials()} now, so delete it`,
+    );
+  }
+
+  return changes;
+}

package/src/cli/endpoint-url.ts

@@ -9,7 +9,7 @@ import type { Config, DeployConfig, TargetConfig } from '#profile';
  *
  * Shared because getting it wrong is silent in the worst way. `outputs` asked
  * the driver; `mcp add` built the local URL unconditionally, so
- * `lanes link mcp add --target cloud` registered `http://127.0.0.1:7337/mcp`
+ * `lanes link mcp add --workspace cloud` registered `http://127.0.0.1:7337/mcp`
  * with the agent — a registration that looks successful, names the right
  * server, and points at a port with nothing behind it. One of the two had the
  * answer and the other could not see it, which is what a copied line does

package/src/cli/identity.ts

@@ -88,10 +88,10 @@ export async function resolveAccount(
       if (!primary || !identity.qualifier) return primary;
 
       // `alice (Acme)` rather than `alice`. The bracketed half is what makes
-      // two workspaces two accounts instead of one overwritten twice, and it
-      // survives into the connection id because `idFromAccount` slugifies the
-      // whole string when there is no `@` in it — `alice_acme`, which is a row
-      // somebody can read in `status`.
+      // two workspaces two accounts instead of one overwritten twice: the
+      // reconnect match below is on the account, so without it the second
+      // connect repairs the first row rather than adding one. It used to reach
+      // the id as well, back when the id was slugified from this.
       const qualifier = pluck(body, identity.qualifier);
       return qualifier ? `${primary} (${qualifier})` : primary;
     }
@@ -116,29 +116,47 @@ export async function resolveAccount(
 }
 
 /**
- * Turn an account into a connection id.
+ * `lan` for a surface built into Lanes, `con` for somebody's account.
  *
- * `ada.lovelace@example.com` becomes `ada_lovelace`, which is what appears in
- * `credential_ref` and in the agent's `connection` argument. The local part is
- * enough to tell accounts apart in practice, and the full address is still
- * right there in `account` when it is not.
+ * The prefix is the only thing an id says, and it says the one thing that is
+ * true forever: whether there is a vendor behind this row. Everything else a
+ * reader wants — whose mailbox, what the operator calls it — is `account` and
+ * `label`, one field each, both changeable without moving a reference.
  */
-export function idFromAccount(account: string, taken: readonly string[] = []): string {
-  const local = account.includes('@') ? (account.split('@')[0] ?? account) : account;
-
-  const base =
-    local
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '_')
-      .replace(/^_+|_+$/g, '')
-      .slice(0, 40) || 'main';
-
-  if (!taken.includes(base)) return base;
-
-  // A genuine collision — two accounts sharing a local part, e.g. the same
-  // name at two domains. Suffixing beats overwriting someone else's credential.
-  for (let n = 2; ; n++) {
-    const candidate = `${base}${n}`;
-    if (!taken.includes(candidate)) return candidate;
+export const OWNER_ID_PREFIX = 'lan';
+export const ACCOUNT_ID_PREFIX = 'con';
+
+/**
+ * The next free connection id.
+ *
+ * **Opaque, where this used to derive the id from the account.**
+ * `ada.lovelace@example.com` became `ada_lovelace`, on the reasoning that the
+ * local part tells accounts apart in practice. It does not: the same name at
+ * two domains produced `ada_lovelace` and `ada_lovelace2`, and an id that half
+ * describes its account is worse than one that does not, because it invites
+ * being trusted. What made that concrete is that the id is the whole of the
+ * `connection` enum a model chooses from.
+ *
+ * So the id is a key and nothing else. `account` carries the identity the
+ * provider reports and `label` the operator's own word, which means a `relabel`
+ * never moves a `credential_ref`, a blob path, or a grant.
+ *
+ * **A leading letter, not a bare number.** `id: 001` parses as the integer `1`
+ * in YAML, so `gmail.001` in a grant would match nothing and every id would need
+ * quoting forever. `con1` is a string unconditionally.
+ *
+ * Numbers are never reused: the highest taken plus one, so an id that appears
+ * in an audit log years later still means the row it meant then.
+ */
+export function nextConnectionId(taken: readonly string[], owner: boolean): string {
+  const prefix = owner ? OWNER_ID_PREFIX : ACCOUNT_ID_PREFIX;
+  const pattern = new RegExp(`^${prefix}([0-9]+)$`);
+
+  let highest = 0;
+  for (const id of taken) {
+    const match = pattern.exec(id);
+    if (match) highest = Math.max(highest, Number(match[1]));
   }
+
+  return `${prefix}${highest + 1}`;
 }