@lanes-sh/link 0.7.2 → 0.8.0

package/src/cli/workspace-migrate.ts

@@ -1,3 +1,5 @@
+import { migrateToContract3, needsContract3, type Contract3Migration } from './contract3.ts';
+import { readSession } from '#auth/lanes/session.ts';
 import { parseDocument } from 'yaml';
 import {
   ConfigError,
@@ -25,7 +27,7 @@ import { hoist, summarise } from './migrate-plan.ts';
  * of each profile — one in `~/.lanes-link`, one in the bucket the endpoint reads
  * — and gave them nothing to keep them honest. It failed the way it was always
  * going to: a local file was rewritten, lost its cloud target and eight
- * connections, and `status --target cloud` reported seven where the endpoint was
+ * connections, and `status --workspace cloud` reported seven where the endpoint was
  * serving fifteen. `sync targets` and ADR-044's deployment index were both
  * written in response to earlier rounds of the same thing.
  *
@@ -122,8 +124,8 @@ export async function migrateWorkspace(
   const changes: string[] = [];
   for (const [name, entry] of Object.entries(registry)) {
     changes.push(
-      entry.workspace !== undefined
-        ? `targets.${name}: pointer to ${entry.workspace}`
+      entry.at !== undefined
+        ? `workspaces.${name}: pointer to ${entry.at}`
         : `targets.${name}: declared in ${WORKSPACE_FILE}`,
     );
   }
@@ -147,17 +149,30 @@ export async function migrateWorkspace(
   // again.
   await writeRegistry(workspaceRoot, registry);
 
-  for (const { document } of legacy) {
+  for (const { document, profile } of legacy) {
     document.removeIn(['targets']);
-    document.setIn(['contract'], SUPPORTED_CONTRACT);
+    // Literally 2, not `SUPPORTED_CONTRACT`. This migration produces a
+    // contract-2 profile and nothing else; `migrateToContract3` takes it the
+    // rest of the way. Writing the current contract here would stamp a file
+    // that still has contract-2 shapes with the newest number, and the loader
+    // would then read it as a contract-3 document that is missing `grants:`.
+    document.setIn(['contract'], 2);
     // `instance.default_target` went with the block it selected from. It has
     // been inert since ADR-037 and there is now nothing for it to name.
     document.removeIn(['instance', 'default_target']);
-    // Shape-only: a profile may carry an unrelated problem the full loader
-    // refuses — a connection row still spelling a renamed provider is the one
-    // that happens — and blocking the structural fix on it would strand the file
-    // at a contract nothing reads. `doctor --fix` names and repairs that one.
-    await document.save({ shapeOnly: true });
+    // Written rather than saved, because `save` validates and what this
+    // produces is deliberately not valid *yet*: a contract-2 profile, which the
+    // runtime does not read. `migrateToContract3` is the step that makes it
+    // loadable, and it runs immediately after — so validating here would refuse
+    // the only shape this function is able to produce.
+    //
+    // Nothing is lost by not validating: the next step reads the file it just
+    // wrote, and `check` refuses anything either step leaves broken.
+    await writeWorkspaceFile(
+      workspaceFiles(workspaceRoot),
+      `profiles/${profile}.yaml`,
+      document.toString(),
+    );
   }
 
   return {
@@ -169,6 +184,82 @@ export async function migrateWorkspace(
   };
 }
 
+export interface ContractMigration {
+  readonly workspaceRoot: string;
+  /** The contract 1 → 2 half, when this workspace needed one. */
+  readonly legacy: WorkspaceMigration | null;
+  /** The contract 2 → 3 half, when this workspace needed one. */
+  readonly contract3: Contract3Migration | null;
+  /** Every profile either half rewrote, deduplicated. */
+  readonly profiles: readonly string[];
+  /** Targets written into the registry by the contract 1 → 2 half. */
+  readonly targets: readonly { name: string; kind: 'declared' | 'pointer'; where?: string }[];
+  /** Both halves' lines, in the order they happened. */
+  readonly changes: readonly string[];
+  /** Nothing to do: this workspace is already at `SUPPORTED_CONTRACT`. */
+  readonly alreadyCurrent: boolean;
+}
+
+/**
+ * Bring one workspace to `SUPPORTED_CONTRACT`, whatever it is on now.
+ *
+ * **This exists because "migrate a workspace" was spelled three times and only
+ * one of them arrived.** `update` ran the 1→2 step and then the 2→3 step;
+ * `deploy` and `doctor --fix` ran the first and stopped, which nothing said out
+ * loud — `migrateTargetWorkspace`'s own docstring claimed it brought a target
+ * "to the current contract" while calling only `migrateWorkspace`.
+ *
+ * What that cost is worth writing down, because it is not a refusal. A deploy
+ * uploaded contract-3 config over a contract-2 bucket and rolled a revision that
+ * read `data/state.kv` and `data/audit.log` — while the bytes sat where contract
+ * 2 put them, under `data/<profile>/`. The endpoint came up healthy and answered
+ * every call with an empty store: no memory, no tasks, no skills, and an audit
+ * log that verified as intact because an empty chain does. Nothing in the
+ * deploy, the health probe, or `doctor` had a way to notice.
+ *
+ * So there is one function now, and the contract number lives in one place. A
+ * fourth contract adds a step here and every caller gets it.
+ *
+ * **A dry run of a contract-1 workspace reports only the first half**, and that
+ * is honest rather than a gap: the 1→2 step wrote nothing, so the profiles are
+ * still contract 1 and the 2→3 step has nothing it recognises to describe. What
+ * it would do is knowable only after the step before it has run.
+ *
+ * **The signed-in subject is defaulted here rather than by each caller.** A
+ * migrated profile that lists nobody is an endpoint that advertises OAuth and
+ * then refuses its own owner, so it matters on every path — but `deployments`
+ * may not import `#auth` (see `MAY_IMPORT` in `src/architecture.test.ts`), and
+ * `deploy` is the caller that most needs it: once a target's profiles live in
+ * its bucket there is no upload behind it to put the members row back. A caller
+ * that knows better passes one; nobody signed in is a legitimate answer and
+ * stays default-deny on the identity axis.
+ */
+export async function migrateToCurrentContract(
+  workspaceRoot: string,
+  options: { apply: boolean; subject?: string } = { apply: true },
+): Promise<ContractMigration> {
+  const legacy = (await needsMigration(workspaceRoot))
+    ? await migrateWorkspace(workspaceRoot, { apply: options.apply })
+    : null;
+
+  const subject = options.subject ?? (await readSession().catch(() => null))?.subject;
+
+  const contract3 = await migrateToContract3(workspaceRoot, {
+    apply: options.apply,
+    ...(subject === undefined ? {} : { subject }),
+  });
+
+  return {
+    workspaceRoot,
+    legacy: legacy !== null && !legacy.alreadyCurrent ? legacy : null,
+    contract3: contract3.alreadyCurrent ? null : contract3,
+    profiles: [...new Set([...(legacy?.profiles ?? []), ...contract3.profiles])],
+    targets: legacy?.targets ?? [],
+    changes: [...(legacy?.changes ?? []), ...contract3.changes],
+    alreadyCurrent: (legacy === null || legacy.alreadyCurrent) && contract3.alreadyCurrent,
+  };
+}
+
 /**
  * Write the registry into the workspace file, creating it when absent.
  *
@@ -186,7 +277,7 @@ async function writeRegistry(
   const text = (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
   const document = parseDocument(text);
   const current = (document.toJSON() ?? {}) as {
-    targets?: Record<string, WorkspaceTarget>;
+    workspaces?: Record<string, WorkspaceTarget>;
     deployments?: {
       target?: string;
       workspace?: string;
@@ -198,7 +289,7 @@ async function writeRegistry(
   // Anything already in the file wins over what was hoisted: a workspace part
   // way through this has entries that are already right, and re-deriving them
   // from a profile that still carries a stale block would undo a correction.
-  const merged: Record<string, WorkspaceTarget> = { ...registry, ...(current.targets ?? {}) };
+  const merged: Record<string, WorkspaceTarget> = { ...registry, ...(current.workspaces ?? {}) };
 
   // ADR-044's index, folded into the entries it described. `primary` and
   // `last_deploy` were kept beside the declaration precisely because the
@@ -214,11 +305,16 @@ async function writeRegistry(
     };
   }
 
+  // `workspaces:`, not `targets:` — the registry is read back by the current
+  // schema even while the profiles beside it are still contract 2, because it
+  // is one document that both migrations share (ADR-061). The profiles are the
+  // half that stays at 2 until `migrateToContract3` runs.
   document.setIn(['contract'], SUPPORTED_CONTRACT);
   document.setIn(
-    ['targets'],
+    ['workspaces'],
     Object.fromEntries(Object.entries(merged).sort(([a], [b]) => a.localeCompare(b))),
   );
+  document.deleteIn(['targets']);
   document.deleteIn(['deployments']);
   document.deleteIn(['default_target']);
 
@@ -229,8 +325,8 @@ function describe(
   registry: Record<string, WorkspaceTarget>,
 ): { name: string; kind: 'declared' | 'pointer'; where?: string }[] {
   return Object.entries(registry).map(([name, entry]) =>
-    entry.workspace !== undefined
-      ? { name, kind: 'pointer' as const, where: entry.workspace }
+    entry.at !== undefined
+      ? { name, kind: 'pointer' as const, where: entry.at }
       : { name, kind: 'declared' as const },
   );
 }
@@ -249,6 +345,19 @@ function describe(
  * part of what it already means (ADR-052).
  */
 export async function refuseIfUnmigrated(root: string): Promise<void> {
+  if (await needsContract3(root)) {
+    throw new ConfigError(
+      `${root} is a contract 2 workspace, and this version does not read one.\n\n` +
+        '  Under contract 2 each profile carried its own connections and one flat\n' +
+        '  policy. Connections belong to the workspace now, and a profile selects\n' +
+        '  among them with per-connection scopes (ADR-057, ADR-058).\n\n' +
+        '  Migrate it:  lanes link update\n' +
+        '  Preview it:  lanes link update --check\n\n' +
+        '  Nothing is deleted by the migration: credentials are merged and read back\n' +
+        '  before the old stores are left in place.',
+    );
+  }
+
   if (!(await needsMigration(root))) return;
 
   throw new ConfigError(
@@ -258,6 +367,6 @@ export async function refuseIfUnmigrated(root: string): Promise<void> {
       '  copies of every profile that could drift apart (ADR-052).\n\n' +
       '  Migrate it:  lanes link update\n' +
       '  A deployed target is migrated by the deploy that ships the image reading it:\n' +
-      '               lanes link deploy --target <name>',
+      '               lanes link deploy --workspace <name>',
   );
 }

package/src/connectivity/manifest/provider.ts

@@ -18,7 +18,9 @@ import { connectionVariableSchema, placeholdersInConnector } from './variables.t
  *
  *   - built-ins, written as typed TS modules under `#providers/` and validated
  *     at import
- *   - the profile's own manifests in `data/<profile>/providers.d/*.yaml`, validated on load
+ *   - the workspace's own manifests in `data/providers.d/*.yaml`, validated on load
+ *     — the workspace's, not a profile's, because a manifest defines a
+ *     connection and connections stopped belonging to profiles (ADR-057)
  *
  * That second one is the scalability claim. A service nobody has integrated is
  * a YAML file the operator writes, not a pull request they wait on.

package/src/connectivity/manifest/requirements.ts

@@ -76,7 +76,7 @@ export interface SetupNeeds {
 function storeCommand(ref: string, placeholder: string, where: Selection): string {
   return (
     `printf %s "${placeholder}" | lanes link secrets set ${ref}` +
-    ` --profile ${where.profile} --target ${where.target}`
+    ` --profile ${where.profile} --workspace ${where.target}`
   );
 }
 

package/src/deployments/bind.ts

@@ -121,7 +121,7 @@ export async function bindConnectionCredentials(input: {
           `could not bind ${connection.provider}.${connection.id}'s credential to ` +
           `${serviceAccount}, so the deployed endpoint will be able to read it and not ` +
           'rotate it — which fails about an hour after the first use. ' +
-          `Run \`lanes link deploy --target ${input.target}\` to bind it. ` +
+          `Run \`lanes link deploy --workspace ${input.target}\` to bind it. ` +
           `(${driver.tool}: ${result.stderr.trim().split('\n').slice(-1)[0] ?? 'failed'})`,
       };
     }

package/src/deployments/deploy.ts

@@ -15,9 +15,9 @@ import { printSteps, runSteps } from './steps.ts';
 import { driverFor } from './drivers.ts';
 import { prepareSecrets, readableRefs, rotatableRefs } from './prepare.ts';
 import { repairOwnerLayer } from '#cli/config-repair.ts';
-import { migrateWorkspace } from '#cli/workspace-migrate.ts';
+import { migrateToCurrentContract } from '#cli/workspace-migrate.ts';
 import { deployedWorkspace, uploadWorkspace } from './upload.ts';
-import { collidingRefs, collisionRefusal, servingProfiles } from './serving.ts';
+import { servingProfiles } from './serving.ts';
 import { healthLine, reachability, registerLine, reportUnauthorised } from './report.ts';
 
 /**
@@ -75,9 +75,14 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // declare anything: it reads this machine's pointer and stops. So the bucket is
   // located, migrated, and only then opened.
   //
-  // Idempotent, and silent on a workspace already at contract 2 — a listing and
-  // no writes. `--dry-run` reports what it would do and writes nothing, like
-  // every other step of this command.
+  // Idempotent, and silent on a workspace already current — a listing and no
+  // writes. `--dry-run` reports what it would do and writes nothing, like every
+  // other step of this command.
+  //
+  // It goes all the way to `SUPPORTED_CONTRACT`, which it did not use to: this
+  // ran the contract 1→2 step alone, so a contract-2 bucket passed straight
+  // through and the revision came up reading an empty `data/` while the bytes
+  // stayed under `data/<profile>/`. See `migrateToCurrentContract`.
   if (!(await migrateTargetWorkspace(requireTargetFlag(flags), flags.dryRun !== true))) return;
 
   // The one command allowed to name a target that does not exist yet: creating
@@ -112,14 +117,13 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     print(style.dim(`         serving ${serving.join(', ')} — ${primary} owns the token`));
   }
 
-  // Before anything external, beside `check`, and for the same reason: two
-  // profiles writing one flat credential ref into one store is a failure with
-  // no later symptom worth having.
-  const colliding = await collidingRefs(resolution.workspaceRoot, serving);
-  if (colliding.length > 0) {
-    heading('Cannot share a credential store');
-    throw new ConfigError(collisionRefusal(colliding, target));
-  }
+  // The credential-collision preflight is gone. It existed because two profiles
+  // each held their own `gmail.main` and both derived the flat ref `gmail/main`
+  // into one store — the last deploy winning, with no later symptom worth
+  // having. A connection belongs to the workspace now and `<provider>.<id>` is
+  // unique by construction (ADR-057), so the state it guarded against cannot be
+  // written: `assertConnectionsUnique` refuses it at load, before a deploy runs
+  // at all.
 
   // `check` before anything external, per the gate order: a config that will be
   // rejected on boot should be rejected here, not after a five-minute build.
@@ -150,7 +154,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // below are, and read from config and manifests before anything opens a
   // store — `--dry-run` must reach the printed step list without touching a
   // credential.
-  const rotatable = await rotatableRefs(resolution.workspaceRoot, serving);
+  const rotatable = await rotatableRefs(resolution.workspaceRoot, serving, declared);
   const readable = await readableRefs(resolution.workspaceRoot, serving, declared);
   const provision = await driver.provision({
     deploy: deployConfig,
@@ -240,7 +244,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     for (const problem of prepared.blocking) print(fail(problem));
     throw new ConfigError(
       'The deployed instance cannot start without these. Store them with ' +
-        `lanes link secrets set <ref> --profile ${resolution.profile} --target ${target}, or ` +
+        `lanes link secrets set <ref> --profile ${resolution.profile} --workspace ${target}, or ` +
         `copy a local setup with lanes link secrets push --profile ${resolution.profile} ` +
         `--from local --to ${target}.`,
     );
@@ -275,6 +279,17 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     // workspace that this target cannot open, and nothing left to check.
     await repairOwnerLayer(resolution.workspaceRoot, serving);
 
+    // **The bucket's own contract, before anything is written over it.**
+    //
+    // The pass at the top of the command resolves the target through this
+    // machine's pointer, which a *first* deploy does not have: the entry is
+    // still a declaration, `resolveTargetWorkspace` answers with the local root,
+    // and it returns early. So this is the only pass that ever sees an existing
+    // bucket at contract 2 — and running it after the upload is the same as not
+    // running it, because the upload writes contract-3 profiles and
+    // `needsContract3` reads the profiles.
+    await migrateToCurrentContract(workspace, { apply: true });
+
     // Before the rollout, so the revision that comes up finds a config to read.
     // Uploading after would leave a window where the service is serving and the
     // workspace it was told to read is not there yet.
@@ -291,15 +306,9 @@ export async function deploy(flags: DeployFlags): Promise<void> {
       await uploadWorkspace(resolution.workspaceRoot, workspace, serving);
     }
 
-    // **The bucket's own migration, here and nowhere else.**
-    //
-    // A second pass, and it is not redundant. The one at the top of the command
-    // migrated whatever the bucket already held; this catches what the upload
-    // just put there — profiles from a workspace that is itself at contract 2
-    // arrive migrated, but a first deploy of a *newly created* bucket writes
-    // them here for the first time. Idempotent, so the ordinary case is one
-    // listing and no writes.
-    await migrateWorkspace(workspace, { apply: true });
+    // Again for what the upload put there: a newly created bucket gets its
+    // profiles written here for the first time. Idempotent — one listing.
+    await migrateToCurrentContract(workspace, { apply: true });
 
     // Where this deployment lives, in both registries — see `record.ts`. The
     // declaration has to land before the revision boots, so it goes here rather
@@ -325,7 +334,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   if (!url) {
     print(
       warn(
-        `deployed, but the platform reported no URL yet — run: lanes link outputs --profile ${resolution.profile} --target ${target}`,
+        `deployed, but the platform reported no URL yet — run: lanes link outputs --profile ${resolution.profile} --workspace ${target}`,
       ),
     );
     return;
@@ -365,7 +374,7 @@ async function migrateTargetWorkspace(target: string, apply: boolean): Promise<b
   const workspace = await resolveTargetWorkspace(root, target).catch(() => null);
   if (workspace === null || workspace === root) return true;
 
-  const migrated = await migrateWorkspace(workspace, { apply });
+  const migrated = await migrateToCurrentContract(workspace, { apply });
   if (migrated.alreadyCurrent) return true;
 
   heading(apply ? 'Migrated' : 'Would migrate');
@@ -383,6 +392,6 @@ async function migrateTargetWorkspace(target: string, apply: boolean): Promise<b
   print(style.dim('  Nothing was written, and nothing else was checked: the rest of this'));
   print(style.dim('  command opens the target, which is not readable until this has run.'));
   print('');
-  print(style.dim(`  Run it for real:  lanes link deploy --target ${target}`));
+  print(style.dim(`  Run it for real:  lanes link deploy --workspace ${target}`));
   return false;
 }

package/src/deployments/gcp/bucket.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { installRoot, layout } from '#profile';
+import { CONNECTIONS_FILE, WORKSPACE_FILE, installRoot, layout } from '#profile';
 import type { DeployStep } from '../driver.ts';
 import {
   removalStep,
@@ -77,9 +77,10 @@ export function bucketGrants(bucket: string, profiles: readonly string[]): Condi
    */
   const theBucket = `resource.name == "projects/_/buckets/${bucket}"`;
 
-  const manifestPrefixes = profiles.map((profile) =>
-    objectsUnder(`${layout.providers(profile)}/`),
-  );
+  // One prefix, not one per profile. Manifests are the workspace's since
+  // ADR-057 — a manifest defines a connection, and connections do not live in a
+  // profile — so the carve-out no longer varies with the profile set.
+  const manifestPrefixes = [objectsUnder(`${layout.providers()}/`)];
   // No profiles leaves the carve-out off rather than guessing at one: the
   // revision keeps write on its own data, as it did before this existed.
   const manifests = manifestPrefixes.length > 0 ? `(${manifestPrefixes.join(' || ')})` : null;
@@ -95,11 +96,21 @@ export function bucketGrants(bucket: string, profiles: readonly string[]): Condi
     {
       // `expression=true` was here, which is every object in the bucket — the
       // step title and ADR-023 both claim a narrowing this did not do. The
-      // config the revision reads is the workspace file, the profiles beside it,
-      // and each profile's own manifests, so name exactly those.
+      // config the revision reads is the workspace file, `connections.yaml`
+      // beside it, the profiles, and the manifests, so name exactly those.
+      //
+      // **Named by the constants, because the list went stale once already.**
+      // ADR-057 moved connections out of the profile into `connections.yaml` at
+      // the workspace root, and `upload.ts` puts it in the bucket because "the
+      // endpoint cannot resolve a single grant without it" — but this expression
+      // still enumerated the contract-2 set. Every fresh deploy built its image,
+      // rolled a revision, and died on `GCS refused to read "connections.yaml"
+      // (403)` before it could listen on its port. Nothing caught it: the
+      // condition is a string assembled here and asserted nowhere, so the suite
+      // saw a passing build and Cloud Run saw a container that never started.
       role: 'roles/storage.objectViewer',
       title: 'reads-its-config',
-      expression: `${theBucket} || ${objectsUnder('profiles/')} || ${objectIs('lanes-link.yaml')}${manifests ? ` || ${manifests}` : ''}`,
+      expression: `${theBucket} || ${objectsUnder('profiles/')} || ${objectIs(WORKSPACE_FILE)} || ${objectIs(CONNECTIONS_FILE)}${manifests ? ` || ${manifests}` : ''}`,
     },
   ];
 }

package/src/deployments/gcp/provision.ts

@@ -1,4 +1,4 @@
-import { VAULT_DOCUMENT_REF, type SecretRef } from '#secrets';
+import type { SecretRef } from '#secrets';
 import type { DeployStep, ProvisionInput } from '../driver.ts';
 import { encodeRef } from '../adapters/gcp-secret-manager.ts';
 import { bucketSteps } from './bucket.ts';
@@ -312,12 +312,12 @@ export async function provisionSteps(
     // mind: nothing here was wrong, it was incomplete, and being incomplete
     // looked exactly like being finished. Reading mail 403'd an hour after every
     // deploy.
-    const rotatable = [
-      ...(input.declared.vault?.adapter === 'secret'
-        ? [input.declared.vault.ref ?? VAULT_DOCUMENT_REF]
-        : []),
-      ...(input.rotatable ?? []),
-    ];
+    // Both kinds arrive already derived: the vault document is named per vault
+    // connection (ADR-059) and only `prepare.ts` has the profile configs to work
+    // it out. Naming `vault/document` here — the contract-2 constant — created
+    // and granted one secret while `openVault` asked for another, and the
+    // revision died on `PERMISSION_DENIED` before it could listen. See `vaultRef`.
+    const rotatable = [...(input.rotatable ?? [])];
 
     // Read, named one secret at a time, for the same reason the write side is:
     // a resource-level grant needs no condition to be scoped.

package/src/deployments/prepare.ts

@@ -1,5 +1,7 @@
 import { credentialRefFor, ownClientRefsFor, rotatableCredentialRefsFor } from '#registry';
-import { listProfiles, loadProfileConfig, type Config, type TargetConfig } from '#profile';
+import {
+  PAIR_TOKEN_REF,
+  readConnections, listProfiles, loadProfileConfig, vaultRef, type Config, type TargetConfig } from '#profile';
 import { VAULT_DOCUMENT_REF, VAULT_KEY_REF, generateVaultKey, type SecretStore } from '#secrets';
 import { ok, print, style, warn } from '#cli/output.ts';
 import { buildRegistryWithWorkspace, ensureProfileToken } from '#cli/runtime.ts';
@@ -66,6 +68,7 @@ export interface PrepareResult {
 export async function rotatableRefs(
   root: string,
   profiles: readonly string[] | undefined,
+  declared: TargetConfig | undefined,
 ): Promise<string[]> {
   const refs = new Set<string>();
   const wanted = profiles === undefined ? undefined : new Set(profiles);
@@ -80,16 +83,27 @@ export async function rotatableRefs(
       continue;
     }
 
-    // Inside the loop because manifests are the profile's own (ADR-030): a
-    // connection in `work` naming a provider only `work` declares resolves to
-    // nothing against `personal`'s registry, and a missed ref here is a 403 an
-    // hour after the revision reports healthy.
-    const registry = await buildRegistryWithWorkspace(root, name);
+    // `vault.put` is a capability an agent may hold under policy (ADR-022), so
+    // the revision rewrites this one — and it is per vault connection, which is
+    // what makes this a per-profile pass rather than a target-level constant.
+    // The loop had been reduced to `void config` when the derivation moved out;
+    // this is it moving back, next to the config it needs.
+    if (declared?.vault?.adapter === 'secret') refs.add(vaultRef(declared, config));
+  }
 
-    for (const connection of config.connections) {
-      const manifest = registry.manifest(connection.provider);
-      for (const ref of rotatableCredentialRefsFor(connection, manifest)) refs.add(ref);
-    }
+  // Once, outside the profile loop. Connections and the manifests that describe
+  // them belong to the workspace (ADR-057), so the per-profile registry ADR-030
+  // required is gone — and with it the failure it guarded against, where a
+  // connection in `work` resolved to nothing against `personal`'s registry and
+  // the missed ref became a 403 an hour after the revision reported healthy.
+  //
+  // Every connection, not just granted ones: a credential a revision cannot read
+  // is a broken account, and whether some profile currently grants it is a
+  // question that changes without redeploying.
+  const registry = await buildRegistryWithWorkspace(root);
+  for (const connection of (await readConnections(root)).connections) {
+    const manifest = registry.manifest(connection.provider);
+    for (const ref of rotatableCredentialRefsFor(connection, manifest)) refs.add(ref);
   }
 
   // Sorted, and a set: two Gmail connections share one dynamically registered
@@ -132,9 +146,41 @@ export async function readableRefs(
 ): Promise<string[]> {
   const refs = new Set<string>();
 
+  // Unconditionally, for every deploy, whether or not this workspace has ever
+  // been paired — and that is the point rather than a rounding up.
+  //
+  // Secret Manager answers a *missing binding* with 403, not 404, so that an
+  // identity cannot enumerate secrets by their error codes. The adapter returns
+  // null for the 404 and throws for the 403, so an unbound ref is a thrown
+  // error on the read path — and that is the failure `server/read/open.ts`
+  // records: a deployed revision asked for refs no binding covered and never
+  // went healthy.
+  //
+  // Bound, the deployed-but-never-paired case becomes the 404 instead — a
+  // secret that exists with no version — which reads back as null and renders
+  // as `401 {error:'unpaired'}`. The grant is what turns a crash into a
+  // refusal.
+  //
+  // Deciding it by asking *whether the workspace is paired* is the thing that
+  // cannot happen: that means opening a credential store inside `readableRefs`,
+  // which `--dry-run` reaches and must not do.
+  //
+  // Deliberately not in `rotatableRefs`. The revision never writes this one —
+  // minting is `lanes link pair`, from the operator's machine — and
+  // `secretVersionAdder` here would let a compromised revision issue itself a
+  // credential that reads the whole workspace.
+  //
+  // The cert and key refs are absent for a different reason: Cloud Run
+  // terminates TLS with a certificate a browser already trusts, so a deployed
+  // revision never calls `serveRead` and never reads either.
+  refs.add(PAIR_TOKEN_REF);
+
+  // Only the key is the target's. The *document* is named per vault connection
+  // (ADR-059), so it is added inside the profile loop below — naming it here
+  // meant `vault/document`, which is not what `openVault` opens, and the
+  // revision 403'd on a ref nothing had created. See `vaultRef`.
   if (declared?.vault?.adapter === 'secret') {
     refs.add(VAULT_KEY_REF);
-    refs.add(declared.vault.ref ?? VAULT_DOCUMENT_REF);
   } else if (declared?.vault?.adapter === 'blob') {
     // Ciphertext lives in the bucket, but the key that opens it is still here.
     refs.add(VAULT_KEY_REF);
@@ -153,22 +199,24 @@ export async function readableRefs(
     }
 
     refs.add(config.auth.token_ref);
+    if (declared?.vault?.adapter === 'secret') refs.add(vaultRef(declared, config));
     // The OIDC audience check reads this on every verify (`server/endpoint.ts`).
     if (config.auth.authorization?.mode === 'oidc') {
       refs.add(config.auth.authorization.client_id_ref);
     }
 
-    // Per profile, for the reason `rotatableRefs` gives: a manifest is this
-    // profile's, so the registry that resolves its connections must be too.
-    const registry = await buildRegistryWithWorkspace(root, name);
+  }
 
-    for (const connection of config.connections) {
-      const manifest = registry.manifest(connection.provider);
-      const ref = credentialRefFor(connection, manifest);
-      if (ref) refs.add(ref);
-      for (const rotatable of rotatableCredentialRefsFor(connection, manifest)) refs.add(rotatable);
-      for (const client of ownClientRefsFor(manifest, config.oauth_apps)) refs.add(client);
-    }
+  // Once, for the reason `rotatableRefs` gives.
+  const connectionsFile = await readConnections(root);
+  const registry = await buildRegistryWithWorkspace(root);
+
+  for (const connection of connectionsFile.connections) {
+    const manifest = registry.manifest(connection.provider);
+    const ref = credentialRefFor(connection, manifest);
+    if (ref) refs.add(ref);
+    for (const rotatable of rotatableCredentialRefsFor(connection, manifest)) refs.add(rotatable);
+    for (const client of ownClientRefsFor(manifest, connectionsFile.oauth_apps)) refs.add(client);
   }
 
   return [...refs].sort();
@@ -190,13 +238,13 @@ export async function prepareSecrets(input: PrepareInput): Promise<PrepareResult
   // The command is spelled out rather than described. This is the one manual
   // step a deploy genuinely cannot take for you, so it should cost a paste
   // rather than a trip to the docs to work out how the id is spelled.
-  const registry = await buildRegistryWithWorkspace(root, config.instance.profile);
-  for (const connection of config.connections) {
+  const registry = await buildRegistryWithWorkspace(root);
+  for (const connection of (await readConnections(root)).connections) {
     const ref = credentialRefFor(connection, registry.manifest(connection.provider));
     if (!ref || (await credentials.has(ref))) continue;
     warnings.push(
       `${connection.provider}.${connection.id} is not authorised yet — no credential at "${ref}"\n` +
-        `    lanes link connect ${connection.provider} --profile ${input.config.instance.profile} --target ${target} --id ${connection.id}`,
+        `    lanes link connect ${connection.provider} --profile ${input.config.instance.profile} --workspace ${target} --id ${connection.id}`,
     );
   }
 

package/src/deployments/record.ts

@@ -56,7 +56,7 @@ export async function recordDeployment(record: DeploymentRecord): Promise<void>
   // there pointed the bucket at itself, and the revision that came up refused to
   // open its own target.
   await recordTarget(resolveWorkspaceRoot(), record.target, {
-    workspace: record.workspace,
+    at: record.workspace,
     ...stamp,
   });
 }

package/src/deployments/report.ts

@@ -37,7 +37,7 @@ import { heading, ok, print, style, warn } from '#cli/output.ts';
 export function registerLine(profile: string, target: string): string {
   return style.dim(
     `  Connect your accounts first, then register with:\n` +
-      `    lanes link outputs --profile ${profile} --target ${target}\n` +
+      `    lanes link outputs --profile ${profile} --workspace ${target}\n` +
       '  A client keeps the tool list it fetched when it connected, so one registered\n' +
       '  before the accounts holds a surface without them until it is re-added.',
   );
@@ -66,7 +66,7 @@ export function reportUnauthorised(warnings: readonly string[], profile: string,
   print(
     style.dim(
       '  A browser consent per account is the one step this cannot take for you:\n' +
-        `    lanes link connect <provider> --profile ${profile} --target ${target}\n` +
+        `    lanes link connect <provider> --profile ${profile} --workspace ${target}\n` +
         '  Each is served as soon as it is authorised. There is no second deploy —\n' +
         '  deploying is how code gets here, and authorising an account changes none.',
     ),