@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/commands/auth.ts

@@ -0,0 +1,229 @@
+import { clearSession, isFresh, readSession } from '#auth/lanes/session.ts';
+import { DEFAULT_API_URL, currentIdToken, login } from '#auth/lanes/login.ts';
+import { completionPage } from '../callback-page.ts';
+import { print, ok, style, warn } from '../output.ts';
+
+/**
+ * `lanes auth` — who this machine is signed in as.
+ *
+ * A separate area from `lanes link auth`, which is a per-connection credential
+ * diagnostic and answers a different question entirely. Neither is renamed and
+ * neither gains an alias: one spelling per command, and the help text on each
+ * says which is which.
+ *
+ * Sign-in is required to consume a profile, local endpoints included (ADR-060).
+ * That is a real dependency on lanes.sh for a self-hostable tool, and the shape
+ * of it is worth stating plainly: **the network is needed to sign in and to
+ * refresh, not per request.** A machine offline for a day keeps serving, and
+ * `status` below is the command that says how long that has left to run — a
+ * session that lapses silently would present as an endpoint that worked
+ * yesterday and does not today, which is the worst failure to debug from the
+ * outside.
+ */
+
+export interface AuthFlags {
+  readonly json?: boolean | undefined;
+  readonly apiUrl?: string | undefined;
+}
+
+export async function authLogin(flags: AuthFlags = {}): Promise<void> {
+  const opened: string[] = [];
+
+  const session = await login({
+    apiUrl: flags.apiUrl,
+    // The same card a provider connect flow ends on. For a few seconds this
+    // page is the whole product, and it used to be an unstyled sentence on a
+    // white rectangle — in a browser set to dark, on a sign-in that had just
+    // worked. `brand.ts` carries the palette for both modes.
+    page: (outcome) =>
+      completionPage(
+        outcome.ok
+          ? { label: 'Lanes', heading: 'Signed in', detail: outcome.detail, ok: true }
+          : { label: 'Lanes', heading: 'That did not work', detail: outcome.detail, ok: false },
+      ),
+    onUrl: (url) => opened.push(url),
+    open: async (url) => {
+      // Printed as well as opened. A machine with no browser — a container, an
+      // SSH session — gets a URL it can paste somewhere that has one, which is
+      // the whole difference between "this does not work here" and "this takes
+      // one more step here".
+      print(style.dim('  Opening your browser to sign in. If nothing opens, use this:'));
+      print(`  ${url}`);
+      print('');
+      await openInBrowser(url);
+    },
+  });
+
+  if (flags.json === true) {
+    print(JSON.stringify({ subject: session.subject, email: session.email }, null, 2));
+    return;
+  }
+
+  print(ok(`signed in as ${style.bold(session.email ?? session.subject)}`));
+  print(style.dim(`      subject  ${session.subject}`));
+  print('');
+  print(
+    style.dim(
+      '      A profile reaches you only where its members list that subject:\n' +
+        '        lanes link profile members add <subject> --profile <name>',
+    ),
+  );
+  void opened;
+}
+
+export async function authLogout(flags: AuthFlags = {}): Promise<void> {
+  const session = await readSession();
+  await clearSession();
+
+  if (flags.json === true) {
+    print(JSON.stringify({ signedOut: session !== null }, null, 2));
+    return;
+  }
+
+  print(
+    session === null
+      ? style.dim('Not signed in; nothing to do.')
+      : ok(`signed out ${style.bold(session.email ?? session.subject)}`),
+  );
+
+  // Said out loud, because it is the surprising half. Signing out removes the
+  // identity this machine presents; it does not touch a profile's members list,
+  // and it does not revoke a token an agent already holds.
+  print(
+    style.dim(
+      '      Profiles still list you, and a client holding a token still holds it.\n' +
+        '      To take a token back: lanes link token rotate --workspace <name>',
+    ),
+  );
+}
+
+export async function authStatus(flags: AuthFlags = {}): Promise<void> {
+  const session = await readSession();
+
+  if (session === null) {
+    if (flags.json === true) {
+      print(JSON.stringify({ signedIn: false }, null, 2));
+      return;
+    }
+    print(warn('not signed in'));
+    print(style.dim('      Run: lanes auth login'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const fresh = isFresh(session);
+
+  if (flags.json === true) {
+    print(
+      JSON.stringify(
+        {
+          signedIn: true,
+          subject: session.subject,
+          email: session.email,
+          expiresAt: session.expiresAt,
+          fresh,
+          apiUrl: session.apiUrl,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  print(ok(`signed in as ${style.bold(session.email ?? session.subject)}`));
+  print(`      subject  ${style.dim(session.subject)}`);
+  print(`      api      ${style.dim(session.apiUrl)}`);
+  print(
+    `      token    ${
+      fresh
+        ? style.dim(`valid until ${session.expiresAt}`)
+        : style.dim('expired — the next command refreshes it')
+    }`,
+  );
+
+  if (session.apiUrl !== DEFAULT_API_URL) {
+    print(style.dim(`      This session was issued by ${session.apiUrl}, not the default.`));
+  }
+}
+
+/**
+ * Every workspace this identity can reach, and what it may do there.
+ *
+ * `GET /v1/me` is the source, and it is the server that decides — the client
+ * sends no uid, and the answer is derived from the token. That is what makes
+ * this listing something an operator can trust rather than a local guess.
+ */
+export async function authWorkspaces(flags: AuthFlags = {}): Promise<void> {
+  const session = await readSession();
+  if (session === null) {
+    print(warn('not signed in'));
+    print(style.dim('      Run: lanes auth login'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const token = await currentIdToken();
+  if (token === null) {
+    print(warn('the session could not be refreshed'));
+    print(style.dim('      Run: lanes auth login'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const response = await fetch(`${session.apiUrl}/v1/me`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+
+  if (!response.ok) {
+    print(warn(`${session.apiUrl} answered ${response.status}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const body = (await response.json()) as {
+    memberships?: { workspace_id: string; workspace_name: string; role: string }[];
+  };
+  const memberships = body.memberships ?? [];
+
+  if (flags.json === true) {
+    print(JSON.stringify({ memberships }, null, 2));
+    return;
+  }
+
+  print(style.dim(`signed in as ${session.email ?? session.subject}`));
+  print('');
+
+  if (memberships.length === 0) {
+    print(style.dim('You are a member of no Lanes workspace yet.'));
+  } else {
+    for (const one of memberships) {
+      print(`  ${style.bold(one.workspace_name)}  ${style.dim(one.role)}`);
+      print(`  ${style.dim(one.workspace_id)}`);
+    }
+  }
+
+  print('');
+  print(
+    style.dim(
+      'A remote lanes link workspace binds to one of these with `lanes_workspace:`\n' +
+        'in lanes-link.yaml, which is whose members a profile may delegate to.',
+    ),
+  );
+}
+
+/** Opens a URL, and says nothing if it cannot. The URL is printed either way. */
+async function openInBrowser(url: string): Promise<void> {
+  const command =
+    process.platform === 'darwin'
+      ? ['open', url]
+      : process.platform === 'win32'
+        ? ['cmd', '/c', 'start', '', url]
+        : ['xdg-open', url];
+
+  try {
+    await Bun.spawn(command, { stdout: 'ignore', stderr: 'ignore' }).exited;
+  } catch {
+    // Nothing to report: the URL is on screen above, which is the fallback.
+  }
+}

package/src/cli/commands/connect/accounts.ts

@@ -32,12 +32,12 @@ export function credentialApp(manifest: ProviderManifest): string | undefined {
  */
 export function accountSiblings(
   manifest: ProviderManifest,
-  config: Config,
+  connections: readonly ConnectionConfig[],
   registry: { manifest(id: string): ProviderManifest | undefined },
 ): ConnectionConfig[] {
   const app = credentialApp(manifest);
 
-  return config.connections.filter((connection) => {
+  return connections.filter((connection) => {
     if (connection.provider === manifest.id) return true;
     if (!app) return false;
     const sibling = registry.manifest(connection.provider);
@@ -55,7 +55,7 @@ export function accountSiblings(
  */
 export function siblingAccountId(
   manifest: ProviderManifest,
-  config: Config,
+  connections: readonly ConnectionConfig[],
   registry: { manifest(id: string): ProviderManifest | undefined },
 ): string | undefined {
   if (!credentialApp(manifest)) return undefined;
@@ -63,7 +63,7 @@ export function siblingAccountId(
   // Asked of the registry, not inferred from the id: `app` is a manifest field,
   // and a provider is free to declare `app: icloud` under any name it likes.
   const ids = new Set(
-    accountSiblings(manifest, config, registry)
+    accountSiblings(manifest, connections, registry)
       .filter((connection) => connection.provider !== manifest.id)
       .map((connection) => connection.id),
   );

package/src/cli/commands/connect/authorise.ts

@@ -1,3 +1,4 @@
+import { registering } from './registration.ts';
 import { auth, discoverOAuthProtectedResourceMetadata } from '@modelcontextprotocol/client';
 import { CredentialOAuthProvider } from '#connectivity/auth/index.ts';
 import type { SecretStore } from '#secrets';
@@ -146,10 +147,9 @@ export async function authorise(input: {
 
     const scope = manifest.auth.scopes.length > 0 ? manifest.auth.scopes.join(' ') : undefined;
 
-    const first = await auth(provider as never, {
-      serverUrl,
-      ...(scope ? { scope } : {}),
-    });
+    const first = await registering(manifest, serverUrl, () =>
+      auth(provider as never, { serverUrl, ...(scope ? { scope } : {}) }),
+    );
 
     if (first === 'AUTHORIZED') {
       progress(ok('already authorised'));

package/src/cli/commands/connect/bind-credential.ts

@@ -1,3 +1,4 @@
+import { grantedConnections } from '../../runtime.ts';
 import { bindConnectionCredentials, type BindOutcome } from '#deployments/bind.ts';
 import type { Runtime } from '../../runtime.ts';
 
@@ -35,7 +36,7 @@ export function bindNewCredential(
   connectionId: string,
   account: string,
 ): Promise<BindOutcome> {
-  const declared = runtime.config.connections.find(
+  const declared = grantedConnections(runtime).find(
     (candidate) => candidate.provider === providerId && candidate.id === connectionId,
   );
 

package/src/cli/commands/connect/custom/index.ts

@@ -92,7 +92,7 @@ export async function connectCustom(
   if (options.json !== true) announce(resolution);
 
   const path = manifestPath(workspaceRoot, profile, providerId);
-  const rerun = `${PROGRAM} connect custom ${providerId} --profile ${profile} --target ${target}`;
+  const rerun = `${PROGRAM} connect custom ${providerId} --profile ${profile} --workspace ${target}`;
 
   const prompter =
     options.prompter ??

package/src/cli/commands/connect/custom/write.ts

@@ -17,7 +17,7 @@ import { parseManifest } from '#providers/custom/index.ts';
 
 /** Where this profile keeps its own declarations. */
 export function manifestPath(workspaceRoot: string, profile: string, id: string): string {
-  return join(workspaceRoot, layout.providers(profile), `${id}.yaml`);
+  return join(workspaceRoot, layout.providers(), `${id}.yaml`);
 }
 
 /**
@@ -142,7 +142,7 @@ export async function checkOpenapiReachable(
 
   const beside = isAbsolute(value)
     ? value
-    : resolve(join(workspaceRoot, layout.providers(profile)), value);
+    : resolve(join(workspaceRoot, layout.providers()), value);
 
   if (await exists(beside)) return;
 

package/src/cli/commands/connect/grant.ts

@@ -1,27 +1,42 @@
+import type { Config } from '#profile';
 import type { ConfigDocument } from '../../config-edit.ts';
 import { matchesRule } from './accounts.ts';
 
 /**
  * What connecting grants.
  *
- * One rule per provider, not one per capability. The pinned-per-tool form this
- * replaced was 85 lines for four providers and unreadable, and what it bought —
- * a vendor cannot widen your policy by shipping a new tool — is preserved
- * instead by `doctor`, which reports capabilities that appeared after you
- * connected.
+ * One row naming the connection, carrying the wildcard for its provider — not
+ * one rule per capability. The pinned-per-tool form this replaced was 85 lines
+ * for four providers and unreadable, and what it bought — a vendor cannot widen
+ * your policy by shipping a new tool — is preserved instead by `doctor`, which
+ * reports capabilities that appeared after you connected.
  *
- * Idempotent, and by matching rather than by equality: a profile already holding
- * a broader rule that covers this one is not widened, and a second connect to
- * the same provider adds nothing.
+ * A row rather than a rule, since contract 3. The connection and the permission
+ * used to be two writes into two blocks, which is what made "a row with no rule"
+ * and "a rule with no row" both expressible and both silent: the first served
+ * nothing, the second was refused at load. A grant is one thing now (ADR-058),
+ * so neither state exists to be repaired.
+ *
+ * Idempotent, and by matching rather than by equality: a profile whose row for
+ * this connection already holds a broader rule is not widened, and a second
+ * connect to the same account adds nothing.
  */
-export function grantProvider(
+export function grantConnection(
   document: ConfigDocument,
-  allow: readonly { readonly capability: string }[],
-  providerId: string,
+  config: Config,
+  connection: string,
 ): string[] {
-  const rule = `${providerId}.*`;
-  if (allow.some((existing) => matchesRule(existing.capability, rule))) return [];
+  const rule = `${connection.split('.')[0] ?? ''}.*`;
+  const index = config.grants.findIndex((grant) => grant.connection === connection);
+
+  if (index === -1) {
+    document.addTo(['grants'], { connection, allow: [rule], deny: [] });
+    return [rule];
+  }
+
+  const existing = config.grants[index]!;
+  if (existing.allow.some((held) => matchesRule(held.capability, rule))) return [];
 
-  document.addTo(['policy', 'allow'], rule, { inline: true });
+  document.addTo(['grants', index, 'allow'], rule, { inline: true });
   return [rule];
 }

package/src/cli/commands/connect/index.ts

@@ -1,11 +1,21 @@
+import { CONNECTIONS_FILE } from '#profile';
 import { credentialRefForConnection, WRITE_BUNDLE } from '#connectivity';
+import { recordConfigChange } from '../../audit-change.ts';
 import { ConfigDocument } from '../../config-edit.ts';
 import { ensureOwnerLayer, repaired } from '../../config-repair.ts';
 import { emit, print } from '../../output.ts';
 import { nonInteractivePrompter, terminalPrompter, type Prompter } from '../../prompt.ts';
-import { openRuntime, type GlobalFlags } from '../../runtime.ts';
+import type { ConnectOptions } from './options.ts';
+
+export type { ConnectOptions } from './options.ts';
+import {
+  grantedConnections,
+  openRuntime,
+  primaryProfile,
+  type GlobalFlags,
+} from '../../runtime.ts';
 import { moveCredential, siblingAccountId } from './accounts.ts';
-import { grantProvider } from './grant.ts';
+import { grantConnection } from './grant.ts';
 import { acquireCredential } from './acquire.ts';
 import { declareConnection } from './declare.ts';
 import { resolveConnectionAddress, type ResolvedAddress } from './variables.ts';
@@ -25,80 +35,8 @@ import { settleIdentity } from './settle.ts';
 import { runStrategySetup } from './strategy.ts';
 import { announceConnectTarget } from './target-note.ts';
 import { unknownProvider } from './unknown.ts';
+import { DISCOVERY_NAMESPACE } from '#stores/state';
 
-/**
- * `lanes link connect <provider>` — the one command that adds an account.
- *
- * The same command regardless of connectivity. A local provider declares a
- * connection and stops; an MCP provider authorises, asks the upstream server
- * what it exposes, and grants it. Core learns nothing about any vendor: the
- * manifest says how to reach them and what to ask the operator for.
- *
- * The five numbered steps below are the whole command, and each one that grew
- * past a paragraph moved out: `authorise.ts` gets the token, `setup.ts` asks the
- * operator for what the vendor's console produced, `settle.ts` works out whose
- * account it was, and `accounts.ts` knows which connections are siblings.
- */
-
-export interface ConnectOptions extends GlobalFlags {
-  readonly id?: string | undefined;
-  readonly displayName?: string | undefined;
-  /** `--set key=value`, repeatable: where this connection's service is. */
-  readonly set?: readonly string[] | string | undefined;
-  /**
-   * `--label`: what to call this connection, instead of being asked.
-   *
-   * Distinct from `--display-name`, which answers *whose account this is* for a
-   * provider that cannot report it. This one never touches the identity, so it
-   * is safe to pass anything a person would say out loud.
-   */
-  readonly label?: string | undefined;
-  /** Ask for the stored credential again — a key rotated, or a password revoked. */
-  readonly replace?: boolean | undefined;
-  /**
-   * Answer nothing from a terminal: resolve every declared value from the
-   * credential store, and refuse with instructions where one is missing.
-   */
-  readonly nonInteractive?: boolean | undefined;
-  /** The operator has already agreed to scopes broader than the provider needs. */
-  readonly acceptBroadScopes?: boolean | undefined;
-  /**
-   * Register an OAuth client of your own rather than using a hosted one.
-   *
-   * Sticky by consequence rather than by flag: it writes the `oauth_apps` entry,
-   * and a profile that declares one is never moved off it. So this is typed once
-   * and then forgotten, which is the right shape for a decision about a client
-   * that is shared by every connection of that vendor.
-   */
-  /**
-   * `--own-client`, the older spelling of one of the routes `--auth` now names.
-   *
-   * Kept because it is in scripts and in a year of documentation, and because
-   * it still says something true. It resolves to `--auth own_client`.
-   */
-  readonly ownClient?: boolean | undefined;
-  /**
-   * `--auth <method>`: which way in, for a provider that offers more than one.
-   *
-   * Unset means ask, where there is somebody to ask and something to ask
-   * about. It is not sticky the way `--own-client` is: `--own-client` writes an
-   * `oauth_apps` entry that every connection of the vendor then reads, whereas
-   * this decides one connection's credential and is recorded by that credential
-   * existing. Two accounts on the same profile may honestly differ.
-   */
-  readonly auth?: string | undefined;
-  /** Injected for tests. The broker is the only thing `connect` fetches. */
-  readonly fetch?: typeof globalThis.fetch | undefined;
-  readonly json?: boolean | undefined;
-}
-
-
-/**
- * The connection id used before the provider has said whose account this is.
- *
- * It is a placeholder rather than a name, and `setup.ts` reads it as one: a
- * credential filed under it belongs to a `connect` that did not finish.
- */
 const PROVISIONAL_ID = 'pending';
 
 export async function connect(target: string, options: ConnectOptions): Promise<void> {
@@ -128,7 +66,13 @@ export async function runConnect(
 
   // The runtime is opened first because its registry includes workspace
   // manifests — a custom provider must be as connectable as a built-in.
-  const runtime = await openRuntime(options);
+  // A connection belongs to the workspace, so connecting does not need a
+  // profile (ADR-057). One is still resolved, because the registry that reads
+  // `providers.d/` is opened through a runtime and a runtime carries one — but
+  // it is not the subject, and nothing is written to it unless `--profile` was
+  // actually given.
+  const granting = options.profile !== undefined;
+  const runtime = await openRuntime({ ...options, profile: await primaryProfile(options) });
 
   // Declared out here so the `finally` can close whatever it built.
   let address: ResolvedAddress | undefined;
@@ -139,7 +83,7 @@ export async function runConnect(
     // `gs://` workspace is a second network read of the same YAML. Still long
     // before the browser opens, which is the part that matters. Inside the
     // `try` so the `finally` closes the runtime if the rendering throws.
-    if (!announced) announceConnectTarget(runtime, options.json);
+    if (!announced) announceConnectTarget(runtime, options.json, granting);
 
     const registry = runtime.registry;
     const entry = registry.get(providerId);
@@ -171,7 +115,17 @@ export async function runConnect(
     }
 
     const manifest = entry.manifest;
-    const document = await ConfigDocument.open(runtime.resolution.workspaceRoot, runtime.resolution.profile);
+    // Two documents, because a connection and a grant live in two files
+    // (ADR-057). Both opened here, so a failure to open either happens before
+    // anything is written to the other.
+    const document = await ConfigDocument.open(
+      runtime.resolution.workspaceRoot,
+      runtime.resolution.profile,
+    );
+    const connectionsDocument = await ConfigDocument.openKey(
+      runtime.resolution.workspaceRoot,
+      CONNECTIONS_FILE,
+    );
     const changes: string[] = [];
 
     // 1. Authorise, if this provider needs it.
@@ -183,7 +137,7 @@ export async function runConnect(
     //    Unless a sibling already knows: when several providers of one vendor
     //    share a per-account credential, the second one should adopt the first's
     //    id rather than invent `pending` and ask for a password already held.
-    const adopted = siblingAccountId(manifest, runtime.config, registry);
+    const adopted = siblingAccountId(manifest, runtime.workspaceConnections, registry);
     const named = options.id ?? namedId;
     const provisionalId = named ?? adopted ?? PROVISIONAL_ID;
 
@@ -252,10 +206,17 @@ export async function runConnect(
       manifest,
       provisionalId,
       credentials: runtime.credentials,
-      document,
+      // The connections file, not the profile. `oauth_apps` moved there in
+      // contract 3 — `configSchema` does not declare it any more and only
+      // `connectionsFileSchema` does — so `--own-client` was writing the switch
+      // into a key nothing reads. With no `--profile` the profile document is
+      // not even saved, so it was reported and discarded; with one, it landed in
+      // a block the schema drops, and dispatch fell back to the broker client
+      // while `deploy` bound none of the operator's own refs.
+      document: connectionsDocument,
       changes,
       providerId,
-      connections: runtime.config.connections,
+      connections: grantedConnections(runtime),
       target,
       profile,
       prompter,
@@ -305,7 +266,7 @@ export async function runConnect(
       credentials: runtime.credentials,
       connectorFor: address.connectorFor,
       remember: async (found) => {
-        await runtime.state.kv.set('discovery', providerId, JSON.stringify(found));
+        await runtime.state.kv.set(DISCOVERY_NAMESPACE, providerId, JSON.stringify(found));
         registry.setDiscovered(providerId, found);
       },
     });
@@ -313,8 +274,8 @@ export async function runConnect(
     // 4. Declare the connection, or update the one this account already has.
     changes.push(
       ...declareConnection({
-        document,
-        connections: runtime.config.connections,
+        document: connectionsDocument,
+        connections: runtime.workspaceConnections,
         providerId,
         connectionId,
         account,
@@ -324,8 +285,17 @@ export async function runConnect(
       }),
     );
 
-    // 5. Grant it — one rule per provider; `grant.ts` says why not per capability.
-    const granted = grantProvider(document, runtime.config.policy.allow, providerId);
+    // 5. Grant it — one row naming the connection, carrying its provider's
+    //    wildcard (ADR-058). The row *is* the grant, so neither half can be
+    //    written without the other.
+    //    Only when a profile was named. Connecting authorises an account into
+    //    the workspace; deciding what may be done with it belongs to a profile,
+    //    and those are two acts — so `connect` without `--profile` leaves the
+    //    account granted to nobody and says how to grant it. Writing a grant
+    //    into a profile the operator did not name would be choosing for them.
+    const granted = granting
+      ? grantConnection(document, runtime.config, `${providerId}.${connectionId}`)
+      : [];
 
     // 6. Repair the owner layer if this profile predates it.
     //
@@ -342,7 +312,7 @@ export async function runConnect(
     //    sentence in it is something a caller counting edits has to recognise
     //    and skip, and `granted` is the field that answers "what did this widen"
     //    — an audit reading it would have missed `setup.*` entirely.
-    const repair = ensureOwnerLayer(document);
+    const repair = ensureOwnerLayer(connectionsDocument, document, { grants: granting });
     changes.push(...repair.changes);
     granted.push(...repair.granted);
 
@@ -369,7 +339,39 @@ export async function runConnect(
       };
     }
 
-    await document.save();
+    // The connections file first, always, and the profile second.
+    //
+    // First because a grant naming a connection the workspace does not hold is
+    // refused at load by `assertGrantsResolve` — so if only one of these two
+    // writes lands, it has to be this one. The other order leaves a workspace
+    // that will not open.
+    //
+    // Always because this is where the connection is *declared*, and until this
+    // release it was never written at all: `declareConnection` edited a document
+    // in memory and nothing saved it, so a connect stored the credential, wrote
+    // the grant, and left no row. The account was authorised, invisible, and
+    // unusable.
+    await connectionsDocument.save();
+
+    // Untouched when no profile was named, and `save()` on an unchanged document
+    // still rewrites the file — which would restamp a profile nobody asked to
+    // edit.
+    if (granting) await document.save();
+
+    // A connection belongs to the workspace, so the row is scoped to the
+    // workspace even when a profile was granted it in the same breath — the
+    // grant is its own event, written by `grant`.
+    await recordConfigChange(
+      runtime.config,
+      runtime.resolution.workspaceRoot,
+      runtime.target,
+      {
+        capability: 'config.connection.create',
+        scope: runtime.target,
+        connection: connectionKey,
+        arguments: { account, ...(label ? { label } : {}) },
+      },
+    );
 
     // Where the endpoint that has to serve this reads its config, and then a
     // nudge to re-read it. Neither is a deploy (ADR-029).