@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/contract3-shape.ts

@@ -0,0 +1,212 @@
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import type { ContractRename, LegacyConnection, LegacyProfile } from './contract3.ts';
+import { keyOf } from './contract3.ts';
+import { C3_OWNER_PROVIDERS } from './contract3-layout.ts';
+
+/**
+ * Turning contract 2's shape into contract 3's, without touching a file.
+ *
+ * Split from the flow because these are the decisions and that is the ordering:
+ * which connections exist after hoisting, what each profile's grants become, and
+ * what a rule with an expiry means. Every defect review found in this migration
+ * was in one of those three, and none of them needed a filesystem to reproduce.
+ */
+
+/**
+ * Hoist every profile's connections into one list.
+ *
+ * **Keyed on provider and account, not on the id.** The common case is two
+ * profiles that both connected the same mailbox: same provider, same account,
+ * usually the same id, and they merge into one row because they *are* one
+ * account. The interesting case is two profiles each holding a row spelled
+ * `gmail.main` naming different mailboxes, which is legal under contract 2
+ * because a connection lived inside one profile and nothing ever compared them.
+ *
+ * That collision is resolved by renaming, never by picking. Both accounts are
+ * real, both have a credential, and choosing either would take somebody's
+ * mailbox away silently. The second becomes `gmail.main_2`, and the rename is
+ * reported so the operator sees it before anything else reads the file.
+ */
+export function hoistConnections(profiles: ReadonlyMap<string, LegacyProfile>): {
+  rows: LegacyConnection[];
+  renames: ContractRename[];
+  perProfile: Map<string, Map<string, string>>;
+} {
+  const rows: LegacyConnection[] = [];
+  const renames: ContractRename[] = [];
+  const byAccount = new Map<string, LegacyConnection>();
+  const taken = new Set<string>();
+  const perProfile = new Map<string, Map<string, string>>();
+
+  for (const [profile, config] of profiles) {
+    const mapping = new Map<string, string>();
+    perProfile.set(profile, mapping);
+
+    for (const connection of config.connections ?? []) {
+      // Two profiles' owner layers are never the same thing, whatever their
+      // rows say. Every contract-2 profile carried an identical owner layer
+      // written from a fixed table — `{memory: 'Memory', vault: 'Vault', ...}`
+      // — so an identity of provider-plus-account made all of them collide and
+      // merge. That is the one outcome ADR-059 forbids: interleaving two sets of
+      // notes is not reversible and not reviewable, and for the vault the wrong
+      // answer is a credential. Keying on the profile forces a rename instead.
+      const owner = C3_OWNER_PROVIDERS.includes(connection.provider);
+      const identity = owner
+        ? `${connection.provider} @${profile}`
+        : `${connection.provider} ${connection.account}`;
+      const existing = byAccount.get(identity);
+
+      if (existing) {
+        // The same account, already hoisted. This profile's old key maps to
+        // whatever the first one settled on, which may itself be a rename.
+        mapping.set(keyOf(connection), keyOf(existing));
+        continue;
+      }
+
+      let id = connection.id;
+      if (taken.has(`${connection.provider}.${id}`)) {
+        // The profile's own name for an owner-layer surface, which is what
+        // ADR-059 specifies and reads far better than `memory.main_2` when the
+        // thing being separated is "work's notes". A numeric suffix is the
+        // fallback for a real account, and for the case where the profile name
+        // is itself taken.
+        const preferred = owner ? sanitise(profile) : `${id}_2`;
+        let candidate = preferred;
+        let suffix = 2;
+        while (taken.has(`${connection.provider}.${candidate}`)) {
+          suffix += 1;
+          candidate = `${preferred}_${suffix}`;
+        }
+        renames.push({
+          from: `${connection.provider}.${id}`,
+          to: `${connection.provider}.${candidate}`,
+          reason: owner
+            ? `"${profile}" has its own ${connection.provider}, which is not "${id}"'s`
+            : `"${profile}" named a different account (${connection.account}) with that id`,
+        });
+        id = candidate;
+      }
+
+      const row: LegacyConnection = { ...connection, id };
+      rows.push(row);
+      byAccount.set(identity, row);
+      taken.add(keyOf(row));
+      mapping.set(keyOf(connection), keyOf(row));
+    }
+  }
+
+  return { rows, renames, perProfile };
+}
+
+/** A profile name as a connection id: the same alphabet `connectionRef` allows. */
+function sanitise(profile: string): string {
+  const cleaned = profile.toLowerCase().replace(/[^a-z0-9_]/g, '_').replace(/^_+/, '');
+  return cleaned.length > 0 ? cleaned : 'two';
+}
+
+/**
+ * A rule, in whichever of the two shapes contract 2 accepted, with its expiry.
+ *
+ * Reading the capability alone got both directions wrong, and it is the same
+ * mistake `config-repair.ts` documents. `isRuleActive` is what made a lapsed
+ * rule inert, so dropping `expires_at` turned an allow that died months ago into
+ * a live permanent grant — and an expired *deny* into a permanent one, which is
+ * not the safe direction either, because a deny outranks every allow.
+ *
+ * A rule that has already lapsed is dropped rather than carried: it granted and
+ * denied nothing on the day of the migration, and writing it forward would give
+ * it a meaning it did not have.
+ */
+type Rule = string | { capability: string; expires_at: string };
+
+function patternsOf(rules: unknown, now = Date.now()): Rule[] {
+  if (!Array.isArray(rules)) return [];
+
+  return rules.flatMap((rule): Rule[] => {
+    if (typeof rule === 'string') return [rule];
+
+    const object = rule as { capability?: unknown; expires_at?: unknown } | null;
+    const capability = object?.capability;
+    if (typeof capability !== 'string') return [];
+
+    const expiry = object?.expires_at;
+    if (typeof expiry !== 'string') return [capability];
+
+    const at = Date.parse(expiry);
+    if (Number.isNaN(at)) return [capability];
+    return at > now ? [{ capability, expires_at: expiry }] : [];
+  });
+}
+
+/** The capability a rule names, whichever shape it is in. */
+function capabilityOf(rule: Rule): string {
+  return typeof rule === 'string' ? rule : rule.capability;
+}
+
+/**
+ * The grant rows one contract-2 profile becomes.
+ *
+ * Every connection gets the rules that named its provider, which is precisely
+ * what the flat block meant: rules covered every account of a provider in the
+ * profile. So this loses nothing, and gains the ability to diverge afterwards.
+ *
+ * A rule naming a provider the profile has no connection for is dropped rather
+ * than carried. Under contract 2 an `allow` like that was refused at load, and a
+ * `deny` was permitted as a note to self; there is nowhere to put either now,
+ * because a row without a connection is not expressible.
+ */
+export function grantsFor(
+  config: LegacyProfile,
+  mapping: ReadonlyMap<string, string>,
+): { connection: string; allow: Rule[]; deny: Rule[] }[] {
+  const allow = patternsOf(config.policy?.allow);
+  const deny = patternsOf(config.policy?.deny);
+
+  const covers = (rule: Rule, provider: string): boolean => {
+    const pattern = capabilityOf(rule);
+    return pattern === '*' || pattern.startsWith(`${provider}.`);
+  };
+
+  // Keyed on the *settled* connection, because two rows can become one. A
+  // profile could hold `gmail.main` and `gmail.archive` for the same mailbox at
+  // different scopes — which is legal under contract 2, and the reason tokens
+  // are per connection at all — and the hoist keys on provider-plus-account, so
+  // both settle on one row. Emitting a grant per original row then wrote the
+  // same `connection:` twice and `assertGrantsUnique` refused the profile,
+  // failing the migration on a merge it had just performed itself.
+  //
+  // The rules are unioned rather than picked between. Both rows were in force
+  // before, the connection they describe is now one connection, and dropping
+  // either would narrow a policy the operator never narrowed.
+  const rows = new Map<string, { connection: string; allow: Rule[]; deny: Rule[] }>();
+
+  for (const connection of config.connections ?? []) {
+    const provider = connection.provider;
+    // A bare `*` becomes the provider wildcard rather than being copied
+    // through. It would still mean the same thing inside a row, which is
+    // already scoped to one connection, but writing it out is what makes the
+    // file say so. An expiry rides along untouched.
+    const widen = (rule: Rule): Rule => {
+      if (typeof rule === 'string') return rule === '*' ? `${provider}.*` : rule;
+      return rule.capability === '*' ? { ...rule, capability: `${provider}.*` } : rule;
+    };
+
+    const key = mapping.get(keyOf(connection)) ?? keyOf(connection);
+    const row = rows.get(key) ?? { connection: key, allow: [], deny: [] };
+
+    row.allow = union(row.allow, allow.filter((rule) => covers(rule, provider)).map(widen));
+    row.deny = union(row.deny, deny.filter((rule) => covers(rule, provider)).map(widen));
+    rows.set(key, row);
+  }
+
+  return [...rows.values()];
+}
+
+/** Rules from two merged rows, keeping the first spelling of each capability. */
+function union(held: readonly Rule[], adding: readonly Rule[]): Rule[] {
+  const merged = [...held];
+  for (const rule of adding) {
+    if (!merged.some((one) => capabilityOf(one) === capabilityOf(rule))) merged.push(rule);
+  }
+  return merged;
+}

package/src/cli/contract3.ts

@@ -0,0 +1,399 @@
+import { newConnectionsTemplate } from './config-templates.ts';
+import { planMoves } from './contract3-data.ts';
+import { applyMoves } from './migrate-move.ts';
+import {
+  mergeCredentials,
+  planCredentials,
+  connectionRefs,
+  type CredentialPlan,
+} from './contract3-credentials.ts';
+import { parseDocument } from 'yaml';
+import {
+  CONNECTIONS_FILE,
+  ConfigError,
+  isRemoteWorkspace,
+  layout,
+  listProfiles,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+} from '#profile';
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import { ConfigDocument } from './config-edit.ts';
+import { grantsFor, hoistConnections } from './contract3-shape.ts';
+import { C3 } from './contract3-layout.ts';
+/**
+ * Contract 2 to contract 3: connections move out of the profile.
+ *
+ * The hardest migration this project has done, and the one it could least
+ * afford to skip. `layout.ts` and ADR-030 both set the precedent that there is
+ * no migration, because machinery to move an old layout is more code than the
+ * thing it moves and has to keep working forever. That precedent was set for
+ * *empty directories*. Here the thing being moved is every credential the
+ * operator holds, and "re-authorise fifteen accounts in a browser" is not a
+ * release note anyone should write.
+ *
+ * Four moves, in an order chosen so a crash between any two leaves a workspace
+ * that still opens:
+ *
+ *   1. Connections are hoisted into `connections.yaml`.
+ *   2. Credentials are merged into one store, and read back before the old ones
+ *      are touched.
+ *   3. Profiles are rewritten, `grants:` being the old connections crossed with
+ *      the old flat policy, which is exactly what contract 2 meant.
+ *   4. Bytes move to their connection-keyed homes.
+ *
+ * The registry rename rides along at the end: it is one document and cannot
+ * half-apply.
+ */
+
+/** What a divergent id was renamed to, and why. */
+export interface ContractRename {
+  readonly from: string;
+  readonly to: string;
+  readonly reason: string;
+}
+
+export interface Contract3Migration {
+  readonly workspaceRoot: string;
+  readonly profiles: readonly string[];
+  readonly connections: readonly string[];
+  readonly renames: readonly ContractRename[];
+  readonly credentials: readonly string[];
+  readonly moved: readonly string[];
+  readonly changes: readonly string[];
+  readonly alreadyCurrent: boolean;
+}
+
+export interface LegacyConnection {
+  readonly id: string;
+  readonly provider: string;
+  readonly account: string;
+  readonly label?: string;
+  readonly credential_ref?: string;
+  readonly config?: Record<string, unknown>;
+}
+
+export interface LegacyProfile {
+  readonly contract?: number;
+  readonly connections?: LegacyConnection[];
+  readonly policy?: { allow?: unknown[]; deny?: unknown[] };
+  readonly oauth_apps?: Record<string, unknown>;
+  /**
+   * Read for `token_ref` alone, and read raw rather than through `authSchema`:
+   * this walks profiles that have not been validated, and a profile that fails
+   * validation for an unrelated reason still has an endpoint token to leave
+   * behind.
+   */
+  readonly auth?: { token_ref?: string };
+}
+
+/** The schema default, and what every profile written by the CLI carries. */
+const DEFAULT_TOKEN_REF = 'profile/token';
+
+/** Whether this workspace still holds anything at contract 2. */
+export async function needsContract3(workspaceRoot: string): Promise<boolean> {
+  for (const profile of await listProfiles(workspaceRoot)) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 2) return true;
+  }
+  return false;
+}
+
+async function readProfile(root: string, profile: string): Promise<LegacyProfile | null> {
+  const text = await readWorkspaceFile(workspaceFiles(root), C3.profile(profile));
+  if (text === null) return null;
+  try {
+    return parseDocument(text).toJSON() as LegacyProfile;
+  } catch {
+    // A file that will not parse is not this function's problem to report;
+    // `check` gives it a better sentence than "needs migrating" would.
+    return null;
+  }
+}
+
+/** `gmail.main` — how a connection is addressed in every file after this. */
+export function keyOf(connection: { provider: string; id: string }): string {
+  return `${connection.provider}.${connection.id}`;
+}
+
+export async function migrateToContract3(
+  workspaceRoot: string,
+  options: { apply: boolean; subject?: string } = { apply: true },
+): Promise<Contract3Migration> {
+  const legacy = new Map<string, LegacyProfile>();
+
+  for (const profile of await listProfiles(workspaceRoot)) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 2) legacy.set(profile, raw);
+  }
+
+  const nothing: Contract3Migration = {
+    workspaceRoot,
+    profiles: [],
+    connections: [],
+    renames: [],
+    credentials: [],
+    moved: [],
+    changes: [],
+    alreadyCurrent: true,
+  };
+  if (legacy.size === 0) return nothing;
+
+  const { rows, renames, perProfile } = hoistConnections(legacy);
+  const files = workspaceFiles(workspaceRoot);
+
+  // Everything that can be computed is computed before the first write, so a
+  // refusal leaves the workspace exactly as it was.
+  const plans: CredentialPlan[] = [...legacy].map(([profile, config]) => ({
+    profile,
+    renames: connectionRefs(perProfile.get(profile) ?? new Map()),
+    tokenRef:
+      typeof config.auth?.token_ref === 'string' ? config.auth.token_ref : DEFAULT_TOKEN_REF,
+  }));
+
+  const credentials = await planCredentials(workspaceRoot, plans);
+  const moves = await planMoves(files, [...legacy.keys()], perProfile);
+
+  const changes: string[] = [
+    `${CONNECTIONS_FILE}: ${rows.length} connection(s) hoisted`,
+    ...renames.map((rename) => `renamed ${rename.from} to ${rename.to} (${rename.reason})`),
+    ...[...legacy.keys()].map((profile) => `profiles/${profile}.yaml: contract 3, grants`),
+  ];
+  if (credentials.refs.length > 0) {
+    changes.push(`${C3.credentials()}: ${credentials.refs.length} credential(s) merged`);
+  }
+  if (credentials.tokens.length > 0) {
+    changes.push(
+      `${credentials.tokens.join(', ')}: left behind — one endpoint token per workspace now, ` +
+        'and a fresh one is minted on the next command',
+    );
+  }
+  if (moves.length > 0) changes.push(`${moves.length} object(s) moved to their connection`);
+
+  const result: Contract3Migration = {
+    workspaceRoot,
+    profiles: [...legacy.keys()],
+    connections: rows.map(keyOf),
+    renames,
+    credentials: credentials.refs,
+    moved: moves.map((move) => move.to),
+    changes,
+    alreadyCurrent: false,
+  };
+
+  if (!options.apply) return result;
+
+  // The registry first, and this ordering is the whole of the re-entrancy.
+  //
+  // Every later step is idempotent — writing `connections.yaml` again produces
+  // the same file, merging a credential that is already there is a no-op,
+  // rewriting a contract-3 profile is skipped, and a move whose source is gone
+  // is skipped. `rewriteRegistry` is the one step that is not, because it reads
+  // `targets:` and would find none the second time.
+  //
+  // Running it last meant an interruption anywhere before it left profiles at
+  // contract 3 and `lanes-link.yaml` still at contract 2 — a state where
+  // re-entry found nothing to migrate, and `workspaceSchema` parsed a file whose
+  // `workspaces:` defaulted to empty, so every command refused with "declares no
+  // workspace" and there was no way back.
+  await rewriteRegistry(workspaceRoot);
+  await writeConnections(workspaceRoot, rows, legacy);
+  await mergeCredentials(workspaceRoot, plans);
+
+  // **The bytes move before the profile says they have.**
+  //
+  // `rewriteProfiles` is what stamps `contract: 3`, and that stamp is the only
+  // thing `needsContract3` reads — so it is not a step among steps, it is the
+  // record that the migration finished. Running it before `applyMoves` meant an
+  // interruption between the two left profiles claiming contract 3 with every
+  // byte still under `data/<profile>/`, and a re-run that looked at the stamp
+  // and found nothing to do. The workspace opened, which is what this file
+  // ordered its steps to guarantee, and the owner's memory, tasks, skills and
+  // audit log were not in it.
+  //
+  // A network round trip per object made that window real rather than
+  // theoretical: this migrates buckets now, and the first one it was pointed at
+  // held 1,906 objects.
+  await applyMoves(files, moves);
+  await rewriteProfiles(workspaceRoot, legacy, perProfile, options.subject);
+
+  return result;
+}
+
+/**
+ * The hoisted rows, plus every profile's `oauth_apps` merged into one block.
+ *
+ * **Anything already in the file survives**, which is the rule `writeRegistry`
+ * states for the same reason: a workspace part way through this has entries that
+ * are already right, and re-deriving them from what is left would undo a
+ * correction.
+ *
+ * Not a tidiness argument here. `rewriteProfiles` stamps profiles one at a time
+ * and `legacy` holds only those still at contract 2, so an interruption part way
+ * through it left a rerun hoisting a *subset* — and this overwrote the file with
+ * it, deleting the already-migrated profiles' rows. Their grants named those
+ * connections still. In the shape that actually bites, two profiles held
+ * `gmail.main` for different mailboxes and were hoisted to `gmail.main` and
+ * `gmail.main_2`; the rerun rebuilt the file from the second profile alone, so
+ * `gmail.main` came back naming the *other* person's mailbox and the first
+ * profile's surviving grant pointed at it. Nothing errored, and
+ * `loadProfileConfig` returned ok.
+ */
+async function writeConnections(
+  root: string,
+  rows: readonly LegacyConnection[],
+  legacy: ReadonlyMap<string, LegacyProfile>,
+): Promise<void> {
+  const apps: Record<string, unknown> = {};
+  for (const config of legacy.values()) Object.assign(apps, config.oauth_apps ?? {});
+
+  const held = await readWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE);
+  const current = held === null ? null : ConfigDocument.fromText(held, CONNECTIONS_FILE);
+  const previous = ((current?.toJSON() as { connections?: unknown } | null)?.connections ??
+    []) as LegacyConnection[];
+
+  const merged = new Map<string, LegacyConnection>();
+  for (const row of rows) merged.set(keyOf(row), row);
+  // Second, so a row this run re-derived does not displace the one already
+  // written for it.
+  for (const row of previous) {
+    if (typeof row?.provider === 'string' && typeof row?.id === 'string') merged.set(keyOf(row), row);
+  }
+
+  const document = ConfigDocument.fromText(newConnectionsTemplate(), CONNECTIONS_FILE);
+  document.setIn(['connections'], [...merged.values()]);
+  document.setIn(['oauth_apps'], {
+    ...((current?.toJSON() as { oauth_apps?: Record<string, unknown> } | null)?.oauth_apps ?? {}),
+    ...apps,
+  });
+
+  await writeWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE, document.toString());
+}
+
+/** Contract 3, `grants:` and `members:`, with everything else left as written. */
+async function rewriteProfiles(
+  root: string,
+  legacy: ReadonlyMap<string, LegacyProfile>,
+  perProfile: ReadonlyMap<string, Map<string, string>>,
+  subject: string | undefined,
+): Promise<void> {
+  for (const [profile, config] of legacy) {
+    // `openKey` at the contract-3 path, not `open`, which resolves the live
+    // layout: this produces contract 3, and contract 4 moves what it produced.
+    const document = await ConfigDocument.openKey(root, C3.profile(profile));
+
+    document.setIn(['contract'], 3);
+    document.setIn(['grants'], grantsFor(config, perProfile.get(profile) ?? new Map()));
+    // Empty unless the migration was run by somebody signed in. Nobody is a
+    // legitimate state and it is default deny on the identity axis, but a
+    // workspace whose profiles nobody can consume is a poor thing to hand back,
+    // so `update` passes the signed-in subject through.
+    document.setIn(['members'], subject ? [{ subject, role: 'owner' }] : []);
+
+    // The authorization block arrives here rather than in the template, because
+    // an existing profile has one only if it was deployed. Every endpoint runs
+    // the flow now, loopback included (ADR-062).
+    if (document.getIn(['auth', 'authorization']) === undefined) {
+      document.setIn(['auth', 'authorization'], { mode: 'self' });
+    }
+
+    document.removeIn(['connections']);
+    document.removeIn(['policy']);
+    document.removeIn(['oauth_apps']);
+
+    await document.save({ contract: 3 });
+  }
+}
+
+/** `targets:` becomes `workspaces:`, and a pointer's `workspace:` becomes `at:`. */
+async function rewriteRegistry(root: string): Promise<void> {
+  const document = await ConfigDocument.openKey(root, C3.workspace);
+  const registry = document.toJSON() as {
+    contract?: number;
+    targets?: Record<string, { workspace?: string }>;
+    workspaces?: Record<string, unknown>;
+  } | null;
+
+  const targets = registry?.targets;
+
+  // Already renamed, which is what a contract-1 workspace looks like here: the
+  // 1-to-2 migration wrote `workspaces:` on its way through. Returning early
+  // skipped the contract stamp and the default below, so that path finished a
+  // migration and left neither.
+  if (targets !== undefined) {
+    const workspaces: Record<string, unknown> = {};
+    for (const [name, entry] of Object.entries(targets)) {
+      const { workspace, ...rest } = entry;
+      workspaces[name] = workspace === undefined ? rest : { at: workspace, ...rest };
+    }
+
+    // **Anything already under `workspaces:` wins over what `targets:` says**,
+    // which is the same rule the 1-to-2 migration states for the same reason: a
+    // workspace part way through this has entries that are already right, and
+    // re-deriving them from a stale block would undo a correction.
+    //
+    // It is not hypothetical here. `editRegistry` used to write `workspaces:`
+    // into a contract-2 file without touching its `targets:`, so a deploy from
+    // an unmigrated laptop left two registries disagreeing — and this
+    // overwrote the newer one with the older, silently reverting a recorded
+    // deployment to whatever the last contract-2 command had written. That
+    // write is fixed at source, and this is what repairs a file already
+    // carrying both.
+    const merged: Record<string, unknown> = { ...workspaces };
+    for (const [name, entry] of Object.entries(registry?.workspaces ?? {})) {
+      const derived = merged[name];
+      // Per field, not per entry. The newer block is what `editRegistry` wrote
+      // when it could not see `targets:`, and `sync` writes only `{ at }` — so
+      // replacing the entry wholesale discarded `primary` (which schema.ts calls
+      // the one question about a deployment that must not be guessed at),
+      // `last_deploy`, and the whole `deploy:` block carrying project and
+      // region. Preserving the record was the entire point of the merge.
+      merged[name] =
+        derived !== null && typeof derived === 'object' && entry !== null && typeof entry === 'object'
+          ? { ...(derived as Record<string, unknown>), ...(entry as Record<string, unknown>) }
+          : entry;
+    }
+    document.setIn(['workspaces'], merged);
+    document.removeIn(['targets']);
+  }
+
+  document.setIn(['contract'], 3);
+  const workspaces = (document.toJSON() as { workspaces?: Record<string, unknown> } | null)
+    ?.workspaces ?? {};
+
+  // The workspace on this machine, and only the *first* one when there is no
+  // such thing. Written rather than left absent so the sticky default is on
+  // from the first command after upgrading (ADR-061).
+  //
+  // This used to take the first key outright, on the stated grounds that "for
+  // every workspace this migration will ever see" that is `local`. It is not:
+  // the registry is written sorted, so a workspace that had ever deployed came
+  // out of the 1-to-2 migration with `cloud` ahead of `local`. Upgrading then
+  // pointed every subsequent command at a bucket — which is the one kind of
+  // workspace that can be unreachable, and was: the next `status` answered with
+  // a 403 from GCS rather than with the profiles sitting on the disk.
+  //
+  // A pointer carries `at:`; a workspace declaring its own adapters does not.
+  if (document.getIn(['default_workspace']) === undefined) {
+    const names = Object.keys(workspaces);
+    const here = names.find((name) => {
+      const entry = workspaces[name] as
+        | { at?: unknown; storage?: { adapter?: unknown } }
+        | undefined;
+      // A pointer is here when it points at a path rather than a bucket:
+      // `resolveTargetWorkspace` follows a local one just as happily.
+      if (typeof entry?.at === 'string') return !isRemoteWorkspace(entry.at);
+      // Otherwise it declares its own adapters, and only a filesystem one is on
+      // this machine. Reading "no `at:`" as "local" missed that a cloud target
+      // surveyed by `bootstrap` but never rolled out is a *declaration* — so a
+      // deploy that failed at build or IAM left the same 403 default this was
+      // written to prevent.
+      return entry?.storage?.adapter === 'filesystem';
+    });
+    const chosen = here ?? names[0];
+    if (chosen !== undefined) document.setIn(['default_workspace'], chosen);
+  }
+
+  await document.save();
+}