@lanes-sh/link 0.7.1 → 0.8.0

package/src/profile/load.ts

@@ -1,10 +1,10 @@
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
 import {
+  SINGLE_INSTANCE_PROVIDERS,
   SUPPORTED_CONTRACT,
   configSchema,
   type Config,
-  type PolicyRuleConfig,
 } from './schema.ts';
 import { findSecrets, formatSecretFindings } from './secret-detection.ts';
 
@@ -21,7 +21,7 @@ export class ConfigError extends Error {
 export interface LoadedConfig {
   readonly config: Config;
   readonly source: string;
-  /** `provider.id` for every declared connection, in declaration order. */
+  /** `provider.id` for every connection this profile grants, in declaration order. */
   readonly connectionKeys: readonly string[];
 }
 
@@ -208,7 +208,7 @@ export const RENAMED_PROVIDERS: Readonly<Record<string, ProviderRename>> = {
  * and whoever is reading this refusal just typed which one.
  */
 function repairCommand(config: Config): string {
-  return `lanes link doctor --fix --profile ${config.instance.profile} --target <target>`;
+  return `lanes link doctor --fix --profile ${config.instance.profile} --workspace <name>`;
 }
 
 /** The rename a row is owed, or `null` when it is owed none. */
@@ -221,7 +221,7 @@ export function renamedProviderFor(connection: {
   return moved;
 }
 
-function renamedProvider(
+export function describeRename(
   connection: { provider: string; account: string },
   repair: string,
 ): string | null {
@@ -241,30 +241,74 @@ function renamedProvider(
 function assertReferentialIntegrity(config: Config, source: string): void {
   const problems: string[] = [];
 
-  // There is nothing to check about targets here any more. A profile declares
-  // none (ADR-052): the workspace holding this file declares the one target it
-  // lives in, and `workspaceSchema` is what validates that. A profile is now
-  // portable between targets precisely because it says nothing about them.
-
-  // Connection ids are unique per provider, so `gmail.main` and
-  // `icloud_mail.main` can coexist.
-  const connectionKeys = new Set<string>();
-  const providerNames = new Set(config.connections.map((connection) => connection.provider));
-
-  config.connections.forEach((connection, index) => {
-    const key = `${connection.provider}.${connection.id}`;
-    if (connectionKeys.has(key)) {
-      problems.push(`connections[${index}]: duplicate connection "${key}"`);
+  // Nothing about targets is checked here any more. A profile declares none
+  // (ADR-052): the workspace holding this file declares the one it lives in.
+  //
+  // Nothing about *connections* is either, and that is newer. A connection
+  // belongs to the workspace (ADR-057), so whether a grant names a real one is
+  // a question this file cannot answer on its own — `assertGrantsResolve` in
+  // `./connections.ts` answers it once `connections.yaml` has been read. What
+  // is checkable from one profile alone is checked here, and only that.
+
+  // A grant names one connection, so every capability in it belongs to that
+  // connection's provider. Worth refusing rather than warning: `allowedConnections`
+  // filters candidates to the capability's own provider before policy is
+  // consulted, so `allow: [calendar.*]` on a row granting `gmail.personal`
+  // matches nothing, ever, while reading exactly like a grant that works.
+  const grantKeys = new Set<string>();
+  config.grants.forEach((grant, index) => {
+    if (grantKeys.has(grant.connection)) {
+      problems.push(`grants[${index}]: duplicate grant for "${grant.connection}"`);
     }
-    connectionKeys.add(key);
+    grantKeys.add(grant.connection);
+
+    const provider = grant.connection.split('.')[0] ?? '';
+
+    // The renamed-provider check is not here any more. It compares a row's
+    // *account* against the label the built-in keeps — "is this really Google
+    // Tasks?" — and an account lives in `connections.yaml` now (ADR-057). A
+    // profile grant carries only the key, so asking here would either need the
+    // other file or answer from nothing; `assertNoRenamedProviders` asks where
+    // the answer is.
+
+    for (const [field, rules] of [
+      ['allow', grant.allow],
+      ['deny', grant.deny],
+    ] as const) {
+      rules.forEach((rule, ruleIndex) => {
+        if (rule.capability === '*') return;
+        const named = rule.capability.split('.')[0] ?? '';
+        if (named === provider) return;
 
-    const renamed = renamedProvider(connection, repairCommand(config));
-    if (renamed) problems.push(`connections[${index}]: ${renamed}`);
+        problems.push(
+          `grants[${index}].${field}[${ruleIndex}]: "${rule.capability}" names provider ` +
+            `"${named}", but this row grants "${grant.connection}". A rule here governs ` +
+            `that connection and nothing else, so it can only name "${provider}.*".`,
+        );
+      });
+    }
   });
 
-  // Same reason as a duplicate connection: two entries with the same kind and
-  // value cannot both be meant, and the one that loses is invisible. It matters
-  // more here than it looks, because the two would usually differ only in their
+  // At most one skills grant and one vault grant, for the reason
+  // `SINGLE_INSTANCE_PROVIDERS` gives: both surface as flat names with no
+  // argument to route on, so a second instance is a collision rather than a
+  // choice.
+  for (const provider of SINGLE_INSTANCE_PROVIDERS) {
+    const granted = config.grants
+      .map((grant) => grant.connection)
+      .filter((ref) => ref.startsWith(`${provider}.`));
+
+    if (granted.length > 1) {
+      problems.push(
+        `grants: ${granted.join(' and ')} — a profile may grant one "${provider}" connection. ` +
+          `It is surfaced by name with nothing to route on, so two would be one name for two things.`,
+      );
+    }
+  }
+
+  // Same reason as a duplicate grant: two entries with the same kind and value
+  // cannot both be meant, and the one that loses is invisible. It matters more
+  // here than it looks, because the two would usually differ only in their
   // `note` — so the discarded one is precisely the guidance someone wrote down
   // to stop an agent picking wrong.
   const identityKeys = new Set<string>();
@@ -276,28 +320,17 @@ function assertReferentialIntegrity(config: Config, source: string): void {
     identityKeys.add(key);
   });
 
-  const checkRules = (rules: readonly PolicyRuleConfig[], field: 'allow' | 'deny'): void => {
-    rules.forEach((rule, index) => {
-      const where = `policy.${field}[${index}]`;
-      if (rule.capability === '*') return;
-
-      // A rule naming a provider with no connection is almost always a typo,
-      // and one that fails open-looking: it reads as a grant while matching
-      // nothing. Worth saying, but not fatal for a `deny` — denying something
-      // you have not connected yet is a perfectly reasonable thing to write
-      // ahead of time.
-      const providerOfCapability = rule.capability.split('.')[0] ?? '';
-      if (field === 'allow' && !providerNames.has(providerOfCapability)) {
-        problems.push(
-          `${where}: "${rule.capability}" names provider "${providerOfCapability}", which has no connection` +
-            (providerNames.size > 0 ? ` (have: ${[...providerNames].join(', ')})` : ''),
-        );
-      }
-    });
-  };
-
-  checkRules(config.policy.allow, 'allow');
-  checkRules(config.policy.deny, 'deny');
+  // A subject listed twice is one row deciding the role and the other doing
+  // nothing, and which one wins is iteration order. Since the two would differ
+  // only in `role`, the silent loser is exactly the line someone added to
+  // promote or demote somebody (ADR-060).
+  const subjects = new Set<string>();
+  config.members.forEach((member, index) => {
+    if (subjects.has(member.subject)) {
+      problems.push(`members[${index}]: duplicate subject "${member.subject}"`);
+    }
+    subjects.add(member.subject);
+  });
 
   if (problems.length > 0) {
     throw new ConfigError(`${source}:\n${problems.map((p) => `  ${p}`).join('\n')}`, problems);
@@ -316,7 +349,7 @@ export function parseConfig(text: string, source = '<config>'): LoadedConfig {
   return {
     config,
     source,
-    connectionKeys: config.connections.map((c) => `${c.provider}.${c.id}`),
+    connectionKeys: config.grants.map((grant) => grant.connection),
   };
 }
 

package/src/profile/pairing.ts

@@ -0,0 +1,32 @@
+/**
+ * Where the dashboard's pairing credentials live in a workspace's store.
+ *
+ * Here rather than beside the command that writes them, because three
+ * components now read these names and only one of them is the CLI: the server
+ * opens the read surface with them (`#server/read`), and a deploy binds the
+ * token so the revision may read it (`#deployments/prepare.ts`). Importing a
+ * *command* module for a string constant dragged `cli/output.ts`,
+ * `cli/prompt.ts` and the terminal handling behind them into the container's
+ * runtime graph, which is a large amount of the CLI to load in order to learn
+ * three names.
+ *
+ * Underscores, not dots. A secret reference is `[a-z0-9_-]` separated by `/`
+ * (see `isValidSecretRef`), and that is not arbitrary: these names become
+ * Secret Manager entries on a deployed workspace, and Google allows no dots
+ * there either. `workspace/pair.cert` was refused at the moment somebody first
+ * ran the command.
+ */
+
+/** The credential the dashboard presents. Reads everything; can change nothing. */
+export const PAIR_TOKEN_REF = 'workspace/pair_token';
+
+/**
+ * The certificate the loopback read listener terminates TLS with, and its key.
+ *
+ * Loopback only, and deliberately not bound on a deployed workspace: Cloud Run
+ * terminates TLS with a certificate a browser already trusts, so a deployed
+ * revision never calls `serveRead` and never reads either of these. Binding two
+ * secrets nothing reads would say the boundary is wider than it is.
+ */
+export const PAIR_CERT_REF = 'workspace/pair_cert';
+export const PAIR_KEY_REF = 'workspace/pair_key';

package/src/profile/primitives.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * The four string shapes the config contract is built out of.
+ * The string shapes the config contract is built out of.
  *
  * Their own file because more than one schema module needs them, and the
  * alternative was either a circular import or a second copy of a regex that
@@ -66,3 +66,37 @@ export const browserOrigin = z.string().refine(
   },
   'must be "*" or an origin with no trailing slash or path, e.g. "https://chat.example"',
 );
+
+/**
+ * `<provider>.<connection>` — how a grant names what it governs.
+ *
+ * One string rather than two fields, because it is one string everywhere else
+ * it appears: the `connection` argument an agent passes, the audit event, the
+ * `setup_overview` listing, and the refusal a mismatched pairing produces.
+ * Splitting it in the config alone would mean every reader joins it back
+ * together.
+ */
+export const connectionRef = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9_]*\.[a-z0-9][a-z0-9_]*$/,
+    'must be "<provider>.<connection>", e.g. "gmail.personal"',
+  );
+
+/**
+ * Who a profile is delegated to: `lanes:<subject>` (ADR-060).
+ *
+ * The prefix is load-bearing twice over, and the second reason is the one that
+ * would otherwise be found the hard way. A Lanes subject is a 28-character
+ * mixed-case alphanumeric string — which is exactly what `secret-detection.ts`
+ * refuses as a high-entropy blob, so a bare one could not be written into a
+ * profile at all. The colon takes the value out of `OPAQUE_TOKEN`'s character
+ * class, so saying which identity provider vouched for the subject and being
+ * storable are the same decision rather than an exemption list.
+ *
+ * A pasted credential still cannot be smuggled in here: it does not match this
+ * pattern either, which is what makes the fix a narrowing rather than a hole.
+ */
+export const subjectRef = z
+  .string()
+  .regex(/^lanes:[A-Za-z0-9]{6,64}$/, 'must be "lanes:<subject>", as written by lanes auth login');

package/src/profile/registry.ts

@@ -27,7 +27,7 @@ import {
  * A machine reaches a target it does not hold through a **pointer** — a registry
  * entry carrying `workspace:` and nothing else. Following one is a read of that
  * workspace's own file, which is why every function here is async and why
- * `--target cloud` needs the bucket reachable. That is the trade ADR-052 takes
+ * `--workspace cloud` needs the bucket reachable. That is the trade ADR-052 takes
  * deliberately: a cloud target that cannot be read says so, where the shape it
  * replaces answered instantly from a copy that had been wrong for eight hours.
  */
@@ -51,7 +51,7 @@ export interface ResolvedTarget {
 /** Every target the workspace at `root` knows about. Empty when it has no file. */
 export async function readRegistry(root: string): Promise<Record<string, WorkspaceTarget>> {
   const workspace = await readWorkspace(root);
-  return workspace?.targets ?? {};
+  return workspace?.workspaces ?? {};
 }
 
 /**
@@ -66,7 +66,7 @@ export async function resolveTargetWorkspace(root: string, target: string): Prom
   const registry = await readRegistry(root);
   const entry = registry[target];
   if (!entry) throw notInRegistry(target, registry, root);
-  return isPointer(entry) ? entry.workspace.replace(/\/$/, '') : root;
+  return isPointer(entry) ? entry.at.replace(/\/$/, '') : root;
 }
 
 /**
@@ -90,7 +90,7 @@ export async function openTarget(root: string, target: string): Promise<Resolved
     return { target, workspaceRoot: root, declared, entry, remote: false };
   }
 
-  const workspaceRoot = entry.workspace.replace(/\/$/, '');
+  const workspaceRoot = entry.at.replace(/\/$/, '');
   const remoteRegistry = await readRegistry(workspaceRoot);
   const remoteEntry = remoteRegistry[target];
 
@@ -146,7 +146,7 @@ function pointerMissesTarget(
   return new ConfigError(
     `${root} says target "${target}" lives at ${workspaceRoot}, but that workspace does not ` +
       `declare it (it declares: ${there}).\n` +
-      `  Adopt what is really there:  lanes link sync targets --target ${target} --from ${workspaceRoot}`,
+      `  Adopt what is really there:  lanes link sync targets --workspace ${target} --from ${workspaceRoot}`,
   );
 }
 
@@ -176,7 +176,7 @@ function remoteAtContractOne(target: string, workspaceRoot: string): ConfigError
   return new ConfigError(
     `${workspaceRoot} is a contract 1 workspace, so it does not declare "${target}" yet.\n` +
       '  Its profiles still carry their own targets: block, which this version does not read.\n\n' +
-      `  lanes link deploy --target ${target}\n` +
+      `  lanes link deploy --workspace ${target}\n` +
       '  migrates it and rolls the image that can read it, in that order — which is what\n' +
       '  keeps the endpoint in front of it serving throughout (ADR-052).',
   );

package/src/profile/schema.ts

@@ -1,5 +1,12 @@
 import { z } from 'zod';
-import { browserOrigin, capabilityPattern, credentialRef, identifier } from './primitives.ts';
+import {
+  browserOrigin,
+  capabilityPattern,
+  connectionRef,
+  credentialRef,
+  identifier,
+  subjectRef,
+} from './primitives.ts';
 import { authorizationSchema } from './authorization.ts';
 import { identitySchema } from './identity.ts';
 import { knowledgeTargetSchema } from './knowledge.ts';
@@ -35,11 +42,19 @@ import { knowledgeTargetSchema } from './knowledge.ts';
  * workspace *is* a target: it declares its own adapters once, holds the profiles
  * that live in it, and a profile is one copy in one place.
  *
- * A hard cut, and contract 1 is not read here. `./legacy.ts` understands it, and
- * only the migration uses that — a runtime that loaded either shape would be the
- * two-sources-of-truth problem again, one level up.
+ * **3 moved `connections:` out of the profile and into the workspace**
+ * (ADR-057), and replaced the profile's flat `policy:` with `grants:`, one row
+ * per connection (ADR-058). A profile stopped being an inventory of accounts
+ * and became a selection over them, which is what makes "read this mailbox,
+ * write that calendar" a thing that can be written down. It also gained
+ * `members:`, because a profile worth sharing needs to say who may consume it
+ * (ADR-060).
+ *
+ * A hard cut each time, and only the newest is read here. `./legacy.ts`
+ * understands the older shapes and only the migration uses it — a runtime that
+ * loaded either would be the two-sources-of-truth problem again, one level up.
  */
-export const SUPPORTED_CONTRACT = 2;
+export const SUPPORTED_CONTRACT = 3;
 
 /**
  * There is no `database:` block any more.
@@ -136,7 +151,7 @@ export const auditTargetSchema = z.object({
  */
 export const vaultTargetSchema = z.object({
   adapter: z.enum(['file', 'blob', 'secret']),
-  /** File path, or blob key. Defaults to `./data/<profile>.vault.enc` / `vault.enc`. */
+  /** File path, or blob key. Defaults to `data/vault.d/<connection>.enc`. */
   path: z.string().optional(),
   /** `secret` only: where the sealed document lives. Defaults to `vault/document`. */
   ref: credentialRef.optional(),
@@ -327,6 +342,69 @@ export const policySchema = z.object({
   deny: z.array(policyRuleSchema).default([]),
 });
 
+/**
+ * Providers a profile may grant at most one instance of.
+ *
+ * Not a limitation of the store — `data/skills.d/<id>/` and
+ * `data/vault.d/<id>.enc` hold as many as anyone makes (ADR-059). It is a
+ * limitation of the surface, and it comes from the protocol rather than from
+ * here.
+ *
+ * Every other owner-layer tool takes a `connection` argument, so two memory
+ * instances are two routes through one tool and the caller says which. These
+ * two have nowhere to put that. A skill is surfaced as an MCP **prompt**, and a
+ * prompt is selected by name with no arguments to route on (ADR-012) — two
+ * `triage` skills in one profile would be one name for two procedures. A vault
+ * item becomes its own `vault.get.<id>` capability, and capability ids are flat
+ * for the same reason: two instances holding `stripe_key` would be one
+ * capability naming two secrets, which is the worst of the three collisions
+ * because the wrong answer is a credential.
+ *
+ * So the refusal is at load, where it names both rows, rather than at call time
+ * where one would silently win.
+ */
+export const SINGLE_INSTANCE_PROVIDERS: readonly string[] = ['skills', 'vault'];
+
+/**
+ * One connection, and what may be done with it (ADR-058).
+ *
+ * The rules are the same `allow`/`deny` pair `policySchema` has always carried;
+ * what is new is that a row names the account they govern. ADR-003 kept rules
+ * connection-blind on the reasoning that "a narrower grant is a narrower
+ * profile" — sound while a connection lived in exactly one profile, because the
+ * second profile *was* the granularity. ADR-057 removed that mechanism, so the
+ * granularity moves into the rule.
+ *
+ * **There is no profile-wide `allow` beside these rows, deliberately.** A
+ * second place a connection could be granted is a second answer to "may this
+ * call proceed", and two answers to one question is the failure ADR-052 exists
+ * to prevent. A profile that wants the same rules on eight connections writes
+ * eight rows; the repetition is the cost of there being one place to look.
+ *
+ * Default deny is unchanged and now bites one step earlier: a connection with
+ * no row is not reachable, and is never advertised.
+ */
+export const grantSchema = z.object({
+  connection: connectionRef,
+  allow: z.array(policyRuleSchema).default([]),
+  deny: z.array(policyRuleSchema).default([]),
+});
+
+/**
+ * Who may consume this profile (ADR-060).
+ *
+ * `role` decides who may edit this list and nothing else. Both roles reach
+ * exactly what the grants above allow, because a role that changed what an
+ * agent could call would be a second policy system beside `grants:`, with
+ * precedence rules between them, answering a question the first one already
+ * answers. Two people needing different scopes is two profiles, which is cheap
+ * now that neither of them re-authorises an account.
+ */
+export const memberSchema = z.object({
+  subject: subjectRef,
+  role: z.enum(['owner', 'member']).default('member'),
+});
+
 /**
  * One authorised account.
  *
@@ -412,15 +490,36 @@ export const configSchema = z.object({
     })
     .default({ requests_per_minute: 120, upstream_calls_per_minute: 60 }),
 
-  oauth_apps: z.record(identifier, oauthAppSchema).default({}),
+  /**
+   * What this profile is for, in the owner's own words.
+   *
+   * New in contract 3, and it earns its place because a profile is now a thing
+   * you hand to somebody (ADR-060). "personal-assistant" is a name; "reads my
+   * mail, keeps the calendar, never sends" is what a member needs to know
+   * before accepting it. The dashboard and `setup_overview` show it.
+   */
+  description: z.string().min(1).optional(),
 
   /**
-   * There is no `providers` block. A provider is enabled by having a connection
-   * to it — a second place to say so could only ever disagree with the first,
-   * and everything else a provider needs is in its manifest.
+   * The connections this profile selects, and what may be done with each.
+   *
+   * There is no `connections:` block here any more — a connection belongs to
+   * the workspace (ADR-057), and `connections.yaml` beside this file is where
+   * it lives. A grant naming a connection the workspace does not hold is
+   * refused by `assertReferentialIntegrity` rather than loading and reaching
+   * nothing.
    */
-  connections: z.array(connectionSchema).default([]),
-  policy: policySchema.default({ allow: [], deny: [] }),
+  grants: z.array(grantSchema).default([]),
+
+  /**
+   * Who may consume this profile (ADR-060).
+   *
+   * Empty is not "everyone" — it is nobody, which is default deny applied to
+   * the identity axis. `profile add` writes the signed-in subject as `owner`,
+   * so the empty state is one a hand-edit produces rather than one anybody is
+   * handed.
+   */
+  members: z.array(memberSchema).default([]),
 
   /**
    * Memory and skills, somewhere other than the target's own storage (ADR-041).
@@ -446,8 +545,35 @@ export const configSchema = z.object({
   identity: identitySchema.default([]),
 });
 
+/**
+ * `connections.yaml` — every account authorised in this workspace (ADR-057).
+ *
+ * Its own file rather than a block in `lanes-link.yaml`, because that file is
+ * the registry and is read before anything else can be: resolving which
+ * workspace a command means must not require parsing every connection in it.
+ * And its own file rather than staying in the profile, because authorising an
+ * account and deciding what may be done with it are two acts, and only the
+ * second is a property of a profile.
+ *
+ * `oauth_apps` comes with them. A registered client belongs to the account it
+ * authenticates, not to whichever selection happens to name that account.
+ *
+ * There is still no `providers` block. A provider is enabled by having a
+ * connection to it — a second place to say so could only ever disagree with the
+ * first, and everything else a provider needs is in its manifest.
+ */
+export const connectionsFileSchema = z.object({
+  contract: z.number().int().positive(),
+  connections: z.array(connectionSchema).default([]),
+  oauth_apps: z.record(identifier, oauthAppSchema).default({}),
+});
+
+export type ConnectionsFile = z.infer<typeof connectionsFileSchema>;
+
 export type Config = z.infer<typeof configSchema>;
 export type ConnectionConfig = z.infer<typeof connectionSchema>;
+export type GrantConfig = z.infer<typeof grantSchema>;
+export type MemberConfig = z.infer<typeof memberSchema>;
 export type PolicyRuleConfig = z.infer<typeof policyRuleSchema>;
 export type TargetConfig = z.infer<typeof targetSchema>;
 export type DeployConfig = z.infer<typeof deployTargetSchema>;
@@ -482,8 +608,14 @@ export type { IdentityEntry } from './identity.ts';
  */
 export const workspaceTargetSchema = z
   .object({
-    /** A pointer: where the workspace declaring this target lives. */
-    workspace: z.string().min(1).optional(),
+    /**
+     * A pointer: where the workspace declaring this one lives.
+     *
+     * Spelled `at:` rather than `workspace:` since contract 3. The block is
+     * `workspaces:` now (ADR-061), and `workspaces.cloud.workspace` names the
+     * concept twice and reads as a typo.
+     */
+    at: z.string().min(1).optional(),
     credentials: credentialsTargetSchema.optional(),
     audit: auditTargetSchema.optional(),
     storage: storageTargetSchema.optional(),
@@ -497,6 +629,15 @@ export const workspaceTargetSchema = z
      * gets in — the one question about a deployment that must not be guessed at.
      */
     primary: identifier.optional(),
+    /**
+     * The Lanes workspace this one serves, when it serves one (ADR-060).
+     *
+     * A binding, not an identity: it says whose membership list
+     * `profile members add` validates a subject against. Absent means the
+     * workspace delegates only to the signed-in owner, which is what `local`
+     * does.
+     */
+    lanes_workspace: z.string().min(1).optional(),
     last_deploy: z.string().optional(),
     /**
      * The CLI release that rolled the revision serving this target.
@@ -520,21 +661,21 @@ export const workspaceTargetSchema = z
     // rather than preferring one: a pointer beside a declaration is two answers
     // to "where are this target's bytes", and picking either silently is how the
     // fifteen-connection bucket got reported as seven.
-    if (declares && entry.workspace !== undefined) {
+    if (declares && entry.at !== undefined) {
       ctx.addIssue({
         code: 'custom',
         message:
-          'names a "workspace" and also declares adapters — a target is declared by exactly ' +
+          'names an "at" and also declares adapters — a workspace is declared in exactly ' +
           'one workspace. Keep the adapters here, or keep the pointer and declare them there.',
       });
       return;
     }
 
-    if (!declares && entry.workspace === undefined) {
+    if (!declares && entry.at === undefined) {
       ctx.addIssue({
         code: 'custom',
         message:
-          'declares neither "workspace" nor "credentials" and "storage" — a target either ' +
+          'declares neither "at" nor "credentials" and "storage" — a workspace either ' +
           'lives here or points at where it does.',
       });
       return;
@@ -559,7 +700,17 @@ export const workspaceTargetSchema = z
 export const workspaceSchema = z.object({
   contract: z.number().int().positive(),
   default_profile: identifier.optional(),
-  targets: z.record(z.string(), workspaceTargetSchema).default({}),
+  /**
+   * The workspace a command acts in when `--workspace` is absent (ADR-061).
+   *
+   * The first key in this file that is read rather than parsed and ignored
+   * since ADR-037. What makes it not the resolution chain that decision removed
+   * is that there is one source, it is printed on every command that uses it,
+   * and every command that publishes or destroys refuses it outright. If the
+   * echo is ever dropped for tidiness, ADR-061 has been reversed.
+   */
+  default_workspace: z.string().optional(),
+  workspaces: z.record(z.string(), workspaceTargetSchema).default({}),
 });
 
 export type WorkspaceConfig = z.infer<typeof workspaceSchema>;
@@ -568,8 +719,8 @@ export type WorkspaceTarget = z.infer<typeof workspaceTargetSchema>;
 /** Whether a registry entry points elsewhere rather than declaring the target. */
 export function isPointer(
   entry: WorkspaceTarget,
-): entry is WorkspaceTarget & { workspace: string } {
-  return entry.workspace !== undefined;
+): entry is WorkspaceTarget & { at: string } {
+  return entry.at !== undefined;
 }
 
 /**

package/src/profile/targets.ts

@@ -16,7 +16,7 @@ import { isPointer, type WorkspaceTarget } from './schema.ts';
  * The chain this replaces resolved `--target`, then the variable, then the key,
  * and printed which of the three it landed on. What that bought was one flag
  * saved per command. What it cost was that an *ignored* flag still produced a
- * working command — `profile add --target cloud` dropped the flag on the floor
+ * working command — `profile add --workspace cloud` dropped the flag on the floor
  * and the next command carried on from a different source, so the mistake
  * surfaced one command later with nothing connecting it to its cause. A
  * resolver with nowhere to fall back to cannot fail that way.
@@ -69,27 +69,39 @@ export function noTargetNamed(
   registry: Registry,
   root?: string,
   env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+  options: { refusedDefault?: boolean } = {},
 ): ConfigError {
   const names = Object.keys(registry).sort();
   const where = root ?? 'this workspace';
 
   if (names.length === 0) {
     return new ConfigError(
-      `--target is required, and ${where} declares none.\n` +
-        '  Create one with: lanes link profile add <name> --target local',
+      `--workspace is required, and ${where} declares none.\n` +
+        '  Create one with: lanes link profile add <name> --workspace local',
     );
   }
 
   const stale = env[LEGACY_TARGET_ENV];
 
+  // The refusal a *destructive* command gives is a different sentence, because
+  // the operator has a default set and is entitled to know why it was not used
+  // (ADR-061). Saying only "--workspace is required" to somebody who configured
+  // one reads as a bug in the tool.
+  const because =
+    options.refusedDefault === true
+      ? "--workspace is required. This command publishes or destroys, so the\ndefault is not used for it.\n\n"
+      : "--workspace is required. This command opens a workspace's stores, and\nnothing else selects one.\n\n";
+
   return new ConfigError(
-    '--target is required. This command opens a target\'s stores, and nothing\n' +
-      'else selects one.\n\n' +
-      `  Targets in ${where}\n${rows(registry, names)}\n` +
-      `\n  e.g. lanes link status --target ${names[0]}` +
+    because +
+      `  Workspaces in ${where}\n${rows(registry, names)}\n` +
+      `\n  e.g. lanes link status --workspace ${names[0]}` +
+      (options.refusedDefault === true
+        ? '\n\n  A default is set and is used by every command that only reads.'
+        : '') +
       (stale
         ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
-          '  Unset it, or pass --target.'
+          '  Unset it, or pass --workspace.'
         : ''),
   );
 }
@@ -126,7 +138,7 @@ function rows(registry: Registry, names: readonly string[]): string {
   return names
     .map((name) => {
       const entry = registry[name]!;
-      if (isPointer(entry)) return `    ${name}    ${entry.workspace}`;
+      if (isPointer(entry)) return `    ${name}    ${entry.at}`;
       const adapters = [entry.credentials?.adapter, entry.storage?.adapter]
         .filter(Boolean)
         .join('  ');