@lanes-sh/link 0.5.4 → 0.6.0

package/src/deployments/serving.ts

@@ -1,7 +1,8 @@
 import {
   ConfigError,
-  findDeployment,
+  listProfiles,
   loadWorkspaceProfiles,
+  readRegistry,
   type WorkspaceProfiles,
 } from '#profile';
 import { rotatableCredentialRefsFor } from '#registry';
@@ -17,10 +18,16 @@ import { buildRegistryWithWorkspace } from '#cli/runtime.ts';
  * profile did not declare yet — which the survey then offered to create
  * somewhere new. The way to deploy both was to know that already.
  *
- * The set is derived rather than guessed: it is every profile declaring the
- * target, which is exactly the set the endpoint will try to open. `--profile`
- * narrows it, and naming one is still how a first deploy works, because a
- * target nothing declares has no set to derive (ADR-043).
+ * The set is derived rather than guessed: it is every profile *in* the target's
+ * workspace, which is exactly the set the endpoint will try to open. `--profile`
+ * narrows it, and naming one is still how a first deploy works, because a target
+ * that does not exist yet has no workspace to derive from (ADR-043, ADR-052).
+ *
+ * It used to be "every profile declaring the target", read out of each profile's
+ * own file. That is the shape ADR-052 removed: the same question had a different
+ * answer per profile, so a rewritten file could drop a profile out of the set
+ * silently and the deploy would quietly send fewer profiles than the endpoint
+ * was serving.
  */
 
 export interface Serving {
@@ -42,23 +49,20 @@ export async function servingProfiles(input: {
     return { profiles: [...named], primary: named[0]! };
   }
 
-  const workspace = await loadWorkspaceProfiles(workspaceRoot);
-  const declaring = workspace.loaded
-    .filter((entry) => target in entry.config.targets)
-    .map((entry) => entry.profile);
+  const living = await listProfiles(workspaceRoot);
 
-  if (declaring.length === 0) {
+  if (living.length === 0) {
     throw new ConfigError(
-      `No profile declares "${target}", so there is no set to deploy.\n` +
+      `No profile lives in "${target}", so there is no set to deploy.\n` +
         '  A first deploy creates the target, and has to be told which profile\n' +
         '  it belongs to:\n' +
         `    lanes link deploy --target ${target} --profile <name>\n\n` +
-        `  If "${target}" was deployed before and the declaration was lost:\n` +
+        `  If "${target}" was deployed before and the pointer to it was lost:\n` +
         `    lanes link sync targets --target ${target} --discover`,
     );
   }
 
-  return { profiles: declaring, primary: await choosePrimary(workspaceRoot, target, declaring) };
+  return { profiles: living, primary: await choosePrimary(workspaceRoot, target, living) };
 }
 
 /**
@@ -75,13 +79,13 @@ async function choosePrimary(
   target: string,
   declaring: readonly string[],
 ): Promise<string> {
-  const recorded = (await findDeployment(workspaceRoot, target))?.primary;
+  const recorded = (await readRegistry(workspaceRoot))[target]?.primary;
   if (recorded !== undefined && declaring.includes(recorded)) return recorded;
 
   if (declaring.length === 1) return declaring[0]!;
 
   throw new ConfigError(
-    `${declaring.length} profiles declare "${target}", and nothing records which\n` +
+    `${declaring.length} profiles live in "${target}", and nothing records which\n` +
       "of them owns the endpoint's token. One token opens the endpoint and\n" +
       'reaches every profile behind it, so this cannot be picked for you.\n\n' +
       `  Name it once and it is remembered:\n` +

package/src/deployments/upload.ts

@@ -1,4 +1,5 @@
 import {
+  openTarget,
   DATA_DIR,
   WORKSPACE_FILE,
   layout,
@@ -150,7 +151,15 @@ export async function publishWorkspace(input: {
   readonly target: string;
   readonly profile: string;
 }): Promise<string | null> {
-  const declared = input.config.targets[input.target];
+  // Resolution failures are swallowed rather than thrown. The config edit that
+  // called this has already succeeded and is on disk; a target that cannot be
+  // resolved — undeclared, or a pointer to a bucket that is not answering — is
+  // something for `check` and `status` to report, not a reason to fail an edit
+  // that is done. Returning null is "published nowhere", which is exactly what
+  // happened.
+  const declared = await openTarget(input.workspaceRoot, input.target)
+    .then((resolved) => resolved.declared)
+    .catch(() => undefined);
   if (!declared) return null;
 
   const destination = deployedWorkspace(declared);

package/src/profile/deployments.ts

@@ -1,76 +1,83 @@
 import { parseDocument } from 'yaml';
 import { readWorkspaceFile, workspaceFiles, writeWorkspaceFile } from './files.ts';
-import { workspaceSchema, type DeploymentRecord } from './schema.ts';
-import { WORKSPACE_FILE, readWorkspace } from './workspace.ts';
+import { SUPPORTED_CONTRACT, workspaceSchema, type WorkspaceTarget } from './schema.ts';
+import { WORKSPACE_FILE } from './workspace.ts';
 
 /**
- * The workspace's record of where its deployments live.
+ * Writing the target registry.
  *
- * A target is declared by a profile, and that declaration is what every command
- * resolves from. This is the index beside it, and the distinction is the whole
- * design: a profile file rewritten by hand or by a tool took a live Cloud Run
- * service, its bucket, and its credential store out of reach in one edit,
- * because the four lines naming them were the only copy. The service was still
- * running. Nothing could find it.
+ * ADR-044 kept a deployment *index* here and had to insist it was "an index, not
+ * configuration", because a target was declared by the profile and resolving
+ * from anything else would have been a second source of truth. ADR-052 removed
+ * the thing it was second to: the profile declares no target now, so this file
+ * writes the only declaration there is.
  *
- * So the record is kept where the thing it describes is not: one level up, in
- * `lanes-link.yaml`. `sync targets` reads it to know which bucket to open, and
- * nothing else reads it at all — an index that starts being resolved from is a
- * second source of truth, which is the failure ADR-037 spent a release
- * removing (ADR-044).
+ * Which is why the entry shape matters. A workspace that *is* the target writes
+ * its adapters; a machine reaching it writes a pointer. `registry.ts` follows
+ * one to the other, and the schema refuses an entry trying to be both.
+ *
+ * Everything goes through the YAML document API, so the comments in a workspace
+ * file an operator has annotated survive being written to.
  */
 
-/** Every deployment the workspace has recorded. Empty for a workspace with none. */
-export async function readDeployments(workspaceRoot: string): Promise<DeploymentRecord[]> {
-  // A workspace file that will not parse is not a reason to fail a recovery:
-  // the caller has other ways to find a target, and this is the cheapest.
-  try {
-    return (await readWorkspace(workspaceRoot))?.deployments ?? [];
-  } catch {
-    return [];
-  }
-}
-
-/** What the workspace knows about one target, if anything. */
-export async function findDeployment(
-  workspaceRoot: string,
-  target: string,
-): Promise<DeploymentRecord | undefined> {
-  return (await readDeployments(workspaceRoot)).find((entry) => entry.target === target);
-}
-
 /**
- * Record a deployment, replacing any earlier entry for the same target.
+ * Record a target, replacing any earlier entry of the same name.
  *
- * Keyed by target rather than appended, because a target has one deployment by
- * definition — a second entry would be a history, and a history is a thing to
- * read wrong. Redeploying the same target to a new bucket should leave one
- * record naming the new one.
+ * Keyed by name rather than appended, because a workspace has one answer per
+ * target by definition — a second entry would be a history, and a history is a
+ * thing to read wrong.
  *
- * Merged into the existing entry so a field this caller does not know about —
+ * Merged over the existing entry so a field this caller does not know about —
  * `primary`, on a redeploy that did not ask — is carried forward rather than
- * dropped.
- *
- * Written through the YAML document API, so the comments in a workspace file an
- * operator has annotated survive being indexed.
+ * dropped. That merge is why `deploy` can record a new `last_deploy` without
+ * having to re-answer whose token opens the endpoint.
  */
-export async function recordDeployment(
+export async function recordTarget(
   workspaceRoot: string,
-  entry: DeploymentRecord,
+  target: string,
+  entry: WorkspaceTarget,
+): Promise<void> {
+  await editRegistry(workspaceRoot, (targets) => {
+    const previous = targets[target];
+    // A pointer replacing a declaration is `deploy` handing the target over to
+    // the workspace it just wrote, so the adapter keys have to go rather than
+    // merge — an entry carrying both is what the schema refuses.
+    targets[target] =
+      entry.workspace !== undefined ? { ...pick(previous), ...entry } : { ...previous, ...entry };
+  });
+}
+
+/** Forget a target. Used by `profile remove --target` once nothing is left in it. */
+export async function removeTarget(workspaceRoot: string, target: string): Promise<void> {
+  await editRegistry(workspaceRoot, (targets) => {
+    delete targets[target];
+  });
+}
+
+/** The fields that survive a declaration becoming a pointer: the deploy record. */
+function pick(previous: WorkspaceTarget | undefined): Partial<WorkspaceTarget> {
+  if (!previous) return {};
+  return {
+    ...(previous.primary ? { primary: previous.primary } : {}),
+    ...(previous.last_deploy ? { last_deploy: previous.last_deploy } : {}),
+  };
+}
+
+async function editRegistry(
+  workspaceRoot: string,
+  edit: (targets: Record<string, WorkspaceTarget>) => void,
 ): Promise<void> {
   const files = workspaceFiles(workspaceRoot);
-  const text = (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? 'contract: 1\n';
+  const text =
+    (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
 
   const document = parseDocument(text);
-  const existing = await readDeployments(workspaceRoot);
-  const previous = existing.find((record) => record.target === entry.target);
+  const targets = (document.toJSON()?.targets ?? {}) as Record<string, WorkspaceTarget>;
 
-  const merged = [
-    ...existing.filter((record) => record.target !== entry.target),
-    { ...previous, ...entry },
-  ].sort((a, b) => a.target.localeCompare(b.target));
+  edit(targets);
 
-  document.setIn(['deployments'], merged);
+  if (Object.keys(targets).length === 0) document.deleteIn(['targets']);
+  else document.setIn(['targets'], sorted(targets));
 
   // Validated before it lands, on the rendered tree rather than the input, so
   // what is checked is what would be read back.
@@ -78,3 +85,7 @@ export async function recordDeployment(
 
   await writeWorkspaceFile(files, WORKSPACE_FILE, String(document));
 }
+
+function sorted(targets: Record<string, WorkspaceTarget>): Record<string, WorkspaceTarget> {
+  return Object.fromEntries(Object.entries(targets).sort(([a], [b]) => a.localeCompare(b)));
+}

package/src/profile/index.ts

@@ -14,17 +14,19 @@
 export {
   SUPPORTED_CONTRACT,
   configSchema,
-  deploymentRecordSchema,
+  declaredTarget,
+  isPointer,
   workspaceSchema,
+  workspaceTargetSchema,
   type AuthorizationConfig,
   type Config,
   type ConnectionConfig,
   type DeployConfig,
-  type DeploymentRecord,
   type IdentityEntry,
   type PolicyRuleConfig,
   type TargetConfig,
   type WorkspaceConfig,
+  type WorkspaceTarget,
 } from './schema.ts';
 
 export {
@@ -66,19 +68,33 @@ export {
   readWorkspace,
   resolveSelection,
   resolveWorkspaceRoot,
-  targetsByName,
   workspacePath,
   type LoadedProfile,
   type WorkspaceProfiles,
 } from './workspace.ts';
 export {
   LEGACY_TARGET_ENV,
-  noTargetInWorkspace,
   noTargetNamed,
+  notInRegistry,
   requireTarget,
-  undeclaredTarget,
+  type Registry,
 } from './targets.ts';
-export { findDeployment, readDeployments, recordDeployment } from './deployments.ts';
+export {
+  isLegacyProfile,
+  isLegacyWorkspace,
+  legacyConfigSchema,
+  legacyTargetSchema,
+  type LegacyConfig,
+  type LegacyTarget,
+} from './legacy.ts';
+export {
+  declaredHere,
+  openTarget,
+  readRegistry,
+  resolveTargetWorkspace,
+  type ResolvedTarget,
+} from './registry.ts';
+export { recordTarget, removeTarget } from './deployments.ts';
 export {
   isRemoteWorkspace,
   readWorkspaceFile,

package/src/profile/legacy.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import {
+  auditTargetSchema,
+  credentialsTargetSchema,
+  deployTargetSchema,
+  storageTargetSchema,
+  vaultTargetSchema,
+} from './schema.ts';
+import { knowledgeTargetSchema } from './knowledge.ts';
+
+/**
+ * Contract 1, understood well enough to migrate away from.
+ *
+ * The runtime does not read this and must not start. A binary that loaded either
+ * shape would be the two-sources-of-truth problem ADR-052 removed, one level up:
+ * two spellings of "where does this target live", both valid, disagreeing
+ * silently. `SUPPORTED_CONTRACT` is 2 and a contract-1 file is refused
+ * everywhere except here.
+ *
+ * Deliberately loose. It parses only what the migration has to *move* — the
+ * `targets:` block and its adapters — and passes everything else through
+ * untouched, because the migration edits the YAML document rather than
+ * re-rendering it from a parsed shape. A file with a problem this schema cannot
+ * see is a file the contract-2 loader will report properly once the structure is
+ * right, and that order is on purpose: a stale connection row must not block the
+ * structural fix.
+ */
+
+/**
+ * The `cloudrun:` block `deploy:` replaced.
+ *
+ * Normalised here rather than in `schema.ts`, which is where it used to live.
+ * Contract 2 has no reason to carry a spelling nothing has written for two
+ * releases, and the migration is the last thing that will ever read one.
+ */
+const legacyCloudRunSchema = z.object({
+  project: z.string(),
+  region: z.string(),
+  service: z.string(),
+});
+
+export const legacyTargetSchema = z
+  .object({
+    credentials: credentialsTargetSchema,
+    audit: auditTargetSchema.optional(),
+    storage: storageTargetSchema,
+    vault: vaultTargetSchema.optional(),
+    knowledge: knowledgeTargetSchema.optional(),
+    deploy: deployTargetSchema.optional(),
+    cloudrun: legacyCloudRunSchema.optional(),
+  })
+  .transform(({ cloudrun, ...target }) =>
+    target.deploy || !cloudrun
+      ? target
+      : {
+          ...target,
+          // The pre-`deploy` spelling predates both of these, so it gets the
+          // same defaults the current one would: the closed door, and no
+          // instance kept warm.
+          deploy: {
+            ...cloudrun,
+            platform: 'cloudrun' as const,
+            access: 'iam' as const,
+            min_instances: 0,
+          },
+        },
+  );
+
+/** A contract-1 profile, as far as the migration needs to understand one. */
+export const legacyConfigSchema = z.object({
+  contract: z.literal(1),
+  instance: z.object({ profile: z.string() }).passthrough(),
+  targets: z.record(z.string(), legacyTargetSchema).default({}),
+});
+
+export type LegacyTarget = z.infer<typeof legacyTargetSchema>;
+export type LegacyConfig = z.infer<typeof legacyConfigSchema>;
+
+/** Whether a parsed document is a contract-1 profile, without throwing on one. */
+export function isLegacyProfile(raw: unknown): boolean {
+  return (
+    raw !== null &&
+    typeof raw === 'object' &&
+    !Array.isArray(raw) &&
+    (raw as { contract?: unknown }).contract === 1
+  );
+}
+
+/** Whether a parsed workspace file is contract 1. Same test, different file. */
+export function isLegacyWorkspace(raw: unknown): boolean {
+  return isLegacyProfile(raw);
+}

package/src/profile/load.ts

@@ -129,7 +129,7 @@ function formatZodIssues(error: z.ZodError): string {
  * A connection naming a provider whose id has moved out from under it.
  *
  * There is exactly one, and it is the reason this function exists: `tasks` was
- * Google Tasks until the built-in task list took the plain noun (ADR-051). A row
+ * Google Tasks until the built-in task list took the plain noun (ADR-052). A row
  * left saying `provider: tasks` does not fail — it resolves to the *built-in*,
  * `reconcile` marks it active because a provider needing no credential is
  * authorized by construction, and the operator is left with their Google Tasks
@@ -200,15 +200,15 @@ export const RENAMED_PROVIDERS: Readonly<Record<string, ProviderRename>> = {
 /**
  * The repair, spelled with the selection it will refuse without.
  *
- * Both flags come off the document being validated rather than off the command
- * that is running: nothing has resolved anything yet, and the profile is written
- * in the file. A profile declaring one target names it; one declaring several
- * cannot be guessed at, and a placeholder is more honest than picking.
+ * The profile comes off the document being validated rather than off the command
+ * that is running, because nothing has resolved anything yet and the name is
+ * written in the file. The target cannot come from there any more — a profile
+ * declares none (ADR-052) — so it stays a placeholder. That is honest rather
+ * than lossy: the file being repaired lives in exactly one target's workspace,
+ * and whoever is reading this refusal just typed which one.
  */
 function repairCommand(config: Config): string {
-  const targets = Object.keys(config.targets);
-  const target = targets.length === 1 ? targets[0] : `<${targets.join('|') || 'target'}>`;
-  return `lanes link doctor --fix --profile ${config.instance.profile} --target ${target}`;
+  return `lanes link doctor --fix --profile ${config.instance.profile} --target <target>`;
 }
 
 /** The rename a row is owed, or `null` when it is owed none. */
@@ -241,26 +241,10 @@ function renamedProvider(
 function assertReferentialIntegrity(config: Config, source: string): void {
   const problems: string[] = [];
 
-  const targetNames = new Set(Object.keys(config.targets));
-  if (targetNames.size === 0) {
-    problems.push('targets: at least one target must be declared');
-  }
-  // `instance.default_target` is deliberately not checked. Nothing reads it
-  // (ADR-037), so validating it would be validating a comment — and failing
-  // `check` on a stale value would teach that the key still matters.
-
-  // Only what holds for every platform. What one platform needs and the next
-  // has no concept of — a GCP project, an AWS role ARN — is refused by the
-  // driver that needs it, the way an adapter-specific field is refused by the
-  // code that opens the adapter rather than by this file.
-  for (const [name, target] of Object.entries(config.targets)) {
-    if (!target.deploy) continue;
-    for (const field of ['region', 'service'] as const) {
-      if (!target.deploy[field]) {
-        problems.push(`targets.${name}.deploy.${field}: required for a deployable target`);
-      }
-    }
-  }
+  // 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.

package/src/profile/registry.ts

@@ -0,0 +1,182 @@
+import { ConfigError } from './load.ts';
+import { notInRegistry } from './targets.ts';
+import { readWorkspace } from './workspace.ts';
+import {
+  SUPPORTED_CONTRACT,
+  declaredTarget,
+  isPointer,
+  type TargetConfig,
+  type WorkspaceTarget,
+} from './schema.ts';
+
+/**
+ * The target registry: which targets exist, and which workspace declares each.
+ *
+ * A target names an adapter set. Under contract 1 a *profile* declared one per
+ * target it could be opened against, which is what made a deploy leave two
+ * copies of every profile — one in `~/.lanes-link`, one in the bucket the
+ * endpoint reads — with nothing keeping them honest. The reported failure is in
+ * `sync-apply.ts`'s header and it happened again while this was being written:
+ * a rewritten local file reported seven connections for a target whose bucket
+ * held fifteen, and the endpoint went on serving all fifteen throughout.
+ *
+ * Now a workspace **is** a target (ADR-052). It declares its adapters once, in
+ * its own `lanes-link.yaml`, and holds the profiles that live in it. A profile
+ * is one copy in one place, so there is no reconciliation left to get wrong.
+ *
+ * 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
+ * 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.
+ */
+
+/** Everything a command needs once it knows which target it is acting on. */
+export interface ResolvedTarget {
+  readonly target: string;
+  /**
+   * Where this target's profiles and workspace file live — a directory, or a
+   * bucket URL. Not necessarily the root the command was invoked from.
+   */
+  readonly workspaceRoot: string;
+  /** The adapter set, from whichever workspace declares it. */
+  readonly declared: TargetConfig;
+  /** The declaring entry, for `primary` and `last_deploy`. */
+  readonly entry: WorkspaceTarget;
+  /** Whether the local workspace reached this through a pointer. */
+  readonly remote: boolean;
+}
+
+/** 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 ?? {};
+}
+
+/**
+ * Follow a target to the workspace that declares it.
+ *
+ * Returns `root` itself for a target this workspace declares, and the pointer's
+ * URI for one it does not. One hop only: a pointer whose destination is itself a
+ * pointer is a loop, and a registry that can chain is one where "where does this
+ * live" stops having a short answer.
+ */
+export async function resolveTargetWorkspace(root: string, target: string): Promise<string> {
+  const registry = await readRegistry(root);
+  const entry = registry[target];
+  if (!entry) throw notInRegistry(target, registry, root);
+  return isPointer(entry) ? entry.workspace.replace(/\/$/, '') : root;
+}
+
+/**
+ * A target, resolved to the adapter set a command can open.
+ *
+ * The pointer hop is the only thing here that touches the network, and it
+ * happens once per command rather than per store — `openSecretStoreFor` and
+ * `openBlobStoreFor` take what this returns rather than resolving again.
+ */
+export async function openTarget(root: string, target: string): Promise<ResolvedTarget> {
+  const registry = await readRegistry(root);
+  const entry = registry[target];
+  if (!entry) throw notInRegistry(target, registry, root);
+
+  if (!isPointer(entry)) {
+    const declared = declaredTarget(entry);
+    // Unreachable through the schema, which refuses an entry that is neither a
+    // pointer nor a complete declaration. Kept because the alternative to a
+    // sentence here is a `TypeError` inside an adapter three frames down.
+    if (!declared) throw incompleteTarget(target, root);
+    return { target, workspaceRoot: root, declared, entry, remote: false };
+  }
+
+  const workspaceRoot = entry.workspace.replace(/\/$/, '');
+  const remoteRegistry = await readRegistry(workspaceRoot);
+  const remoteEntry = remoteRegistry[target];
+
+  if (!remoteEntry) {
+    // A contract-1 workspace has no `targets:` block at all, so it looks exactly
+    // like one that declares the wrong things. Told apart here because the two
+    // have completely different fixes, and "does not declare it" would send
+    // someone editing a bucket that is merely out of date.
+    if (await isUnmigrated(workspaceRoot)) throw remoteAtContractOne(target, workspaceRoot);
+    throw pointerMissesTarget(target, workspaceRoot, remoteRegistry, root);
+  }
+  if (isPointer(remoteEntry)) throw pointerChain(target, workspaceRoot, root);
+
+  const declared = declaredTarget(remoteEntry);
+  if (!declared) throw incompleteTarget(target, workspaceRoot);
+
+  // The local entry's `primary` and `last_deploy` are what `deploy` wrote on the
+  // machine that ran it; the declaring workspace is authoritative for everything
+  // else. Merged this way round so a redeploy from a second machine does not
+  // silently lose the first one's record of who opens the endpoint.
+  return {
+    target,
+    workspaceRoot,
+    declared,
+    entry: { ...entry, ...remoteEntry },
+    remote: true,
+  };
+}
+
+/** The targets a workspace declares itself, rather than pointing at. */
+export function declaredHere(registry: Record<string, WorkspaceTarget>): string[] {
+  return Object.entries(registry)
+    .filter(([, entry]) => !isPointer(entry))
+    .map(([name]) => name)
+    .sort();
+}
+
+function incompleteTarget(target: string, root: string): ConfigError {
+  return new ConfigError(
+    `Target "${target}" in ${root} declares neither "credentials" nor "storage", ` +
+      'so there is nothing to open.',
+  );
+}
+
+function pointerMissesTarget(
+  target: string,
+  workspaceRoot: string,
+  remote: Record<string, WorkspaceTarget>,
+  root: string,
+): ConfigError {
+  const there = Object.keys(remote).sort().join(', ') || 'none';
+  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}`,
+  );
+}
+
+function pointerChain(target: string, workspaceRoot: string, root: string): ConfigError {
+  return new ConfigError(
+    `${root} points target "${target}" at ${workspaceRoot}, which points somewhere else again.\n` +
+      '  A target is declared by exactly one workspace. Follow it and declare it there.',
+  );
+}
+
+
+/**
+ * Whether a workspace still holds contract-1 profiles.
+ *
+ * Duplicated in spirit with `workspace-migrate.ts`'s `needsMigration`, and not
+ * imported from it: `#profile` is below `#cli` in the layering, and a refusal
+ * reaching upwards for a sentence is how a cycle gets introduced. This looks at
+ * one file rather than every profile, which is all a refusal needs.
+ */
+async function isUnmigrated(root: string): Promise<boolean> {
+  const workspace = await readWorkspace(root).catch(() => null);
+  if (workspace === null) return false;
+  return workspace.contract < SUPPORTED_CONTRACT;
+}
+
+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` +
+      '  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).',
+  );
+}