@lanes-sh/link 0.5.3 → 0.6.0

package/src/profile/schema.ts

@@ -27,8 +27,19 @@ import { knowledgeTargetSchema } from './knowledge.ts';
  * outright — never a best-effort load. Guessing at an unknown schema on a file
  * that governs authorization is how you end up granting something the operator
  * did not write.
+ *
+ * **2 moved `targets:` out of the profile and into the workspace** (ADR-052). A
+ * profile used to declare the adapter sets it could be opened against, which
+ * meant a deploy left two copies of every profile — one in the workspace and one
+ * in the bucket the endpoint reads — with nothing keeping them honest. Now a
+ * 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.
  */
-export const SUPPORTED_CONTRACT = 1;
+export const SUPPORTED_CONTRACT = 2;
 
 /**
  * There is no `database:` block any more.
@@ -149,8 +160,13 @@ export const vaultTargetSchema = z.object({
  */
 export const deployTargetSchema = z.object({
   platform: z.enum(['cloudrun']),
-  region: z.string(),
-  service: z.string(),
+  // Non-empty here rather than in a referential check further down. Under
+  // contract 1 `assertReferentialIntegrity` walked the profile's `targets:`
+  // block for these; the block is the workspace's now (ADR-052), and a
+  // constraint the schema can express belongs in the schema — an empty service
+  // name should fail at load, not minutes into a build.
+  region: z.string().min(1),
+  service: z.string().min(1),
   /**
    * `iam` puts the platform's own identity check in front of the service;
    * `public` leaves the door open and relies on this application's gate.
@@ -197,69 +213,21 @@ export const deployTargetSchema = z.object({
 });
 
 /**
- * The pre-`deploy` spelling, still accepted.
+ * One adapter set — where credentials are kept, where bytes go, where it rolls.
  *
- * Normalised into `deploy` below rather than read anywhere, so exactly one shape
- * reaches the rest of the codebase. It gains `access: iam` in the process, which
- * is a deliberate change of default for a config that predates the field — a
- * deploy that was open stays open only by saying so.
+ * Declared by the **workspace** that is this target, not by a profile in it
+ * (ADR-052). The `cloudrun:` spelling `deploy:` replaced is gone with contract
+ * 1; `./legacy.ts` still normalises it, on the one path that reads a contract-1
+ * file at all.
  */
-const legacyCloudRunSchema = z.object({
-  project: z.string(),
-  region: z.string(),
-  service: z.string(),
+export const targetSchema = z.object({
+  credentials: credentialsTargetSchema,
+  audit: auditTargetSchema.optional(),
+  storage: storageTargetSchema,
+  vault: vaultTargetSchema.optional(),
+  deploy: deployTargetSchema.optional(),
 });
 
-export const targetSchema = z
-  .object({
-    credentials: credentialsTargetSchema,
-    audit: auditTargetSchema.optional(),
-    storage: storageTargetSchema,
-    vault: vaultTargetSchema.optional(),
-    /**
-     * Memory and skills, somewhere other than `storage` above.
-     *
-     * Optional and absent by default, so every profile written before it keeps
-     * storing both exactly where it did. See `knowledge.ts` for why these two
-     * are separable from the rest and why the credential store and the vault
-     * are not.
-     */
-    knowledge: knowledgeTargetSchema.optional(),
-    deploy: deployTargetSchema.optional(),
-    /** @deprecated Write `deploy` with `platform: cloudrun`. */
-    cloudrun: legacyCloudRunSchema.optional(),
-  })
-  .superRefine((target, ctx) => {
-    // Both present is refused rather than resolved by precedence: a second place
-    // to say where this deploys could only ever disagree with the first, and
-    // silently preferring one would roll a revision to the project the operator
-    // was not reading.
-    if (target.deploy && target.cloudrun) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['cloudrun'],
-        message:
-          'both "deploy" and "cloudrun" are declared — remove "cloudrun", which "deploy" replaces',
-      });
-    }
-  })
-  .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 rule is a pattern, and usually just a string.
  *
@@ -303,11 +271,20 @@ export const policySchema = z.object({
  * is *whose mailbox is this*. `id` is the stable key that `credential_ref` and
  * the agent's `connection` argument point at, and it is derived from `account`
  * so it means something too.
+ *
+ * `label` is the operator's own word for the same row, and it exists because
+ * `account` cannot be. Three things read `account` as an identity — the
+ * reconnect match in `settleIdentity`, the id derived from it, and the `From`
+ * header `gmail.send_message` writes — so a `relabel` that wrote "Work mail"
+ * there stopped the next `connect` recognising the account it had renamed.
+ * Nothing addresses a connection by its label; it is only ever displayed.
  */
 export const connectionSchema = z.object({
   id: z.string().regex(/^[a-z0-9][a-z0-9_]*$/, 'must be lowercase alphanumeric with underscores'),
   provider: identifier,
   account: z.string().min(1),
+  /** Absent means the row is shown as its account, which is the usual case. */
+  label: z.string().min(1).optional(),
   credential_ref: credentialRef.optional(),
   /** Provider-specific, validated later against that provider's own schema. */
   config: z.record(z.string(), z.unknown()).optional(),
@@ -319,27 +296,20 @@ export const oauthAppSchema = z.object({
 });
 
 
+/**
+ * One profile: who it is, what it reaches, and what it may do.
+ *
+ * **It does not say where it runs.** A profile lives in exactly one workspace
+ * and that workspace is a target (ADR-052), so the adapter set is a property of
+ * where the file is, not of what is in it. `instance.default_target` went with
+ * `targets:` — it was already inert under ADR-037, and contract 2 is the release
+ * that stops carrying it.
+ */
 export const configSchema = z.object({
   contract: z.number().int().positive(),
 
   instance: z.object({
     profile: identifier,
-    /**
-     * @deprecated Parsed, never read. See ADR-037.
-     *
-     * Every command names its target on the command line now, so nothing
-     * consults this. It stays *declared* rather than being dropped, and that is
-     * the whole point: an undeclared key is stripped silently by the schema,
-     * which would leave `check` and `doctor` with nothing to report and an
-     * operator staring at a line they reasonably believe still selects
-     * something. Declaring it is what lets them be told it is inert.
-     *
-     * Optional, so a profile written today needs no such line, and unvalidated,
-     * so a stale value naming a target that no longer exists is harmless rather
-     * than a failure on a key nothing reads. The `database:` note above records
-     * the same decision for the same reason.
-     */
-    default_target: z.string().min(1).optional(),
     port: z.number().int().min(1).max(65535).default(7337),
     /**
      * Loopback by default. Binding elsewhere is possible but the server
@@ -348,8 +318,6 @@ export const configSchema = z.object({
     host: z.string().default('127.0.0.1'),
   }),
 
-  targets: z.record(z.string(), targetSchema),
-
   auth: z
     .object({
       mode: z.literal('bearer').default('bearer'),
@@ -389,6 +357,22 @@ export const configSchema = z.object({
   connections: z.array(connectionSchema).default([]),
   policy: policySchema.default({ allow: [], deny: [] }),
 
+  /**
+   * Memory and skills, somewhere other than the target's own storage (ADR-041).
+   *
+   * On the profile rather than the target, which is where contract 1 kept it.
+   * That was never really a property of the adapter set — it says where *this
+   * profile's* notes live — and it had to be per-target only because a profile
+   * could be declared against several. It lives in exactly one now (ADR-052), so
+   * per-profile and per-profile-per-target are the same thing, and this is the
+   * one of the two that matches what ADR-030 says a profile owns.
+   *
+   * Optional and absent by default, so a profile that says nothing keeps both
+   * where it keeps everything else. See `knowledge.ts` for why these two are
+   * separable from the rest and why the credential store and the vault are not.
+   */
+  knowledge: knowledgeTargetSchema.optional(),
+
   /**
    * Who the owner is, for anything written as them. Optional and additive, so
    * every profile written before it keeps loading unchanged — the same reasoning
@@ -407,44 +391,121 @@ export { authorizationSchema, identitySchema };
 export type { IdentityEntry } from './identity.ts';
 
 /**
- * Where a deployment lives — an index, not configuration.
+ * One entry in the workspace's target registry.
  *
- * **Nothing resolves from this.** A target is still declared by the profile,
- * and a command still acts on what the profile says. This exists because the
- * profile file was the *only* record that a deployment existed, so rewriting
- * one erased the sole pointer to a live service, a bucket holding every byte
- * the endpoint remembered, and a credential store — none of which had gone
- * anywhere. There was no command that could find them again.
+ * Two shapes, and which one a workspace writes says who owns the target:
  *
- * It lives in `lanes-link.yaml`, outside any profile, for exactly that reason:
- * a record kept inside the thing it describes cannot survive the thing being
- * lost. `lanes link sync targets` reads it, and reads it *only* to know where
- * to look (ADR-044).
+ * - **A declaration** — `credentials` and `storage`, and whatever else the
+ *   adapter set needs. This workspace *is* that target. `~/.lanes-link` writes
+ *   one of these for `local`.
+ * - **A pointer** — `workspace: gs://bucket[/prefix]`, and nothing else. The
+ *   target lives elsewhere and the workspace at that URI declares it. This is
+ *   what a machine holds for `cloud`.
  *
- * Written by `deploy`, after an upload has succeeded — so it never names a
- * workspace nothing was ever put in.
+ * The pointer is why there is nothing to sync. ADR-044 added an index beside the
+ * profile's own `targets:` block and had to insist it was "an index, not
+ * configuration", because resolving from it would have made it a second source
+ * of truth. Here it is the *only* source: the profile declares no target at all,
+ * so a pointer and a declaration cannot disagree — there is one of them per
+ * target, in one file (ADR-052).
+ *
+ * A declaration for a target that is not deployed yet is the bootstrap case and
+ * is allowed: `deploy` reads it, creates the remote workspace, writes the
+ * declaration *there*, and replaces this one with a pointer. That is the only
+ * moment a target is described in two places, and it does not outlive the
+ * command.
  */
-export const deploymentRecordSchema = z.object({
-  target: identifier,
-  /** Where the deployed endpoint reads its config: `gs://bucket[/prefix]`. */
-  workspace: z.string().min(1),
-  /**
-   * Whose bearer token opens this endpoint (ADR-009).
-   *
-   * Recorded rather than inferred. One endpoint serves every profile in the
-   * bucket under one token, and which profile's token that is decides who gets
-   * in — the one question about a deployment that must not be guessed at.
-   */
-  primary: identifier.optional(),
-  last_deploy: z.string().optional(),
-});
+export const workspaceTargetSchema = z
+  .object({
+    /** A pointer: where the workspace declaring this target lives. */
+    workspace: z.string().min(1).optional(),
+    credentials: credentialsTargetSchema.optional(),
+    audit: auditTargetSchema.optional(),
+    storage: storageTargetSchema.optional(),
+    vault: vaultTargetSchema.optional(),
+    deploy: deployTargetSchema.optional(),
+    /**
+     * Whose bearer token opens this endpoint (ADR-009).
+     *
+     * Recorded rather than inferred. One endpoint serves every profile in the
+     * workspace under one token, and which profile's token that is decides who
+     * gets in — the one question about a deployment that must not be guessed at.
+     */
+    primary: identifier.optional(),
+    last_deploy: z.string().optional(),
+  })
+  .superRefine((entry, ctx) => {
+    const declares = entry.credentials !== undefined || entry.storage !== undefined;
+
+    // Both is the state ADR-052 exists to prevent, and it is worth refusing
+    // 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) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'names a "workspace" and also declares adapters — a target is declared by exactly ' +
+          'one workspace. Keep the adapters here, or keep the pointer and declare them there.',
+      });
+      return;
+    }
+
+    if (!declares && entry.workspace === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'declares neither "workspace" nor "credentials" and "storage" — a target either ' +
+          'lives here or points at where it does.',
+      });
+      return;
+    }
+
+    if (declares && (entry.credentials === undefined || entry.storage === undefined)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: [entry.credentials === undefined ? 'credentials' : 'storage'],
+        message: 'a target declared here needs both "credentials" and "storage"',
+      });
+    }
+  });
 
-/** The workspace file: `lanes-link.yaml`, alongside a `profiles/` directory. */
+/**
+ * The workspace file: `lanes-link.yaml`, alongside a `profiles/` directory.
+ *
+ * `default_profile` is parsed and ignored, as it has been since ADR-037 — it
+ * survives so `check` can say it is inert rather than the schema stripping it
+ * silently. `deployments:` is gone; `targets` above is what it became.
+ */
 export const workspaceSchema = z.object({
   contract: z.number().int().positive(),
   default_profile: identifier.optional(),
-  deployments: z.array(deploymentRecordSchema).default([]),
+  targets: z.record(z.string(), workspaceTargetSchema).default({}),
 });
 
 export type WorkspaceConfig = z.infer<typeof workspaceSchema>;
-export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;
+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;
+}
+
+/**
+ * The adapter set a registry entry declares, or undefined for a pointer.
+ *
+ * A pointer has to be followed before there is anything to open, which is
+ * `resolveTargetWorkspace`'s job — this only narrows the shape once it has been.
+ */
+export function declaredTarget(entry: WorkspaceTarget): TargetConfig | undefined {
+  if (entry.credentials === undefined || entry.storage === undefined) return undefined;
+  return {
+    credentials: entry.credentials,
+    storage: entry.storage,
+    ...(entry.audit ? { audit: entry.audit } : {}),
+    ...(entry.vault ? { vault: entry.vault } : {}),
+    ...(entry.deploy ? { deploy: entry.deploy } : {}),
+  };
+}

package/src/profile/targets.ts

@@ -1,5 +1,5 @@
 import { ConfigError } from './load.ts';
-import type { Config } from './schema.ts';
+import { isPointer, type WorkspaceTarget } from './schema.ts';
 
 /**
  * Which target a command acts on.
@@ -9,8 +9,9 @@ import type { Config } from './schema.ts';
  * the profile, which is why it is a different file.
  *
  * **`--target`, or the command does not run** (ADR-037). There is no fallback:
- * not `LANES_LINK_TARGET`, not `instance.default_target`. Both are still
- * parsed, so no existing config file has to change, and neither is read.
+ * not `LANES_LINK_TARGET`, not `instance.default_target`. The variable is still
+ * named in a refusal so a shell configured for the old world can be told it is
+ * ignored; the key went with contract 1.
  *
  * 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
@@ -19,10 +20,18 @@ import type { Config } from './schema.ts';
  * 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.
+ *
+ * **What changed under ADR-052** is where the list of targets comes from. It was
+ * one profile's `targets:` block, which meant "is this target declared" had a
+ * different answer per profile and a deployment could look vanished from inside
+ * one of them. It is now the workspace registry — one list, before any profile
+ * is read, which is what lets `--target` be chosen first.
  */
 
+export type Registry = Record<string, WorkspaceTarget>;
+
 /**
- * The target this command named, checked against what the profile declares.
+ * The target this command named, checked against the workspace registry.
  *
  * `allowUndeclared` is for the one command whose job is to create the target it
  * was given — `deploy`, on a first run. Every other command naming a target that
@@ -30,14 +39,14 @@ import type { Config } from './schema.ts';
  * answer.
  */
 export function requireTarget(
-  config: Config,
+  registry: Registry,
   targetFlag: string | undefined,
-  options: { allowUndeclared?: boolean; profile?: string } = {},
+  options: { allowUndeclared?: boolean; root?: string } = {},
 ): string {
-  if (!targetFlag) throw noTargetNamed(config, options.profile);
+  if (!targetFlag) throw noTargetNamed(registry, options.root);
 
-  if (options.allowUndeclared !== true && !(targetFlag in config.targets)) {
-    throw undeclaredTarget(targetFlag, config, options.profile);
+  if (options.allowUndeclared !== true && !(targetFlag in registry)) {
+    throw notInRegistry(targetFlag, registry, options.root);
   }
 
   return targetFlag;
@@ -46,43 +55,41 @@ export function requireTarget(
 /**
  * The refusal for a command that named no target.
  *
- * It lists the targets with their adapters, because "which one" is the question
- * being asked and the adapter set is what distinguishes them. It also reports
- * the two things that used to answer this and no longer do — an exported
- * variable and the key still sitting in the file — since an operator looking at
- * either has every reason to believe it is still working.
+ * It lists the targets and where each lives, because "which one" is the question
+ * being asked and here-versus-elsewhere is what distinguishes them. It also
+ * reports the variable that used to answer this and no longer does, since an
+ * operator with it exported has every reason to believe it still works.
+ *
+ * One refusal rather than the two this replaced. `noTargetNamed` used to list
+ * one profile's adapters and `noTargetInWorkspace` listed which profiles
+ * declared each name — a distinction that existed only because a target was
+ * declared per profile. There is one list now, so there is one sentence.
  */
 export function noTargetNamed(
-  config: Config,
-  profile?: string,
+  registry: Registry,
+  root?: string,
   env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
 ): ConfigError {
-  const names = Object.keys(config.targets);
-  const whose = profile ? ` by profile "${profile}"` : '';
+  const names = Object.keys(registry).sort();
+  const where = root ?? 'this workspace';
 
-  const rows = names
-    .map((name) => {
-      const declared = config.targets[name]!;
-      const deployed = declared.deploy ? '  deployed' : '';
-      return `    ${name}    ${declared.credentials.adapter}  ${declared.storage.adapter}${deployed}`;
-    })
-    .join('\n');
+  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',
+    );
+  }
 
   const stale = env[LEGACY_TARGET_ENV];
-  const inert = config.instance.default_target;
 
   return new ConfigError(
     '--target is required. This command opens a target\'s stores, and nothing\n' +
       'else selects one.\n\n' +
-      `  Targets declared${whose}\n${rows}\n` +
-      `\n  e.g. lanes link status --profile ${profile ?? '<name>'} --target ${names[0] ?? '<target>'}` +
+      `  Targets in ${where}\n${rows(registry, names)}\n` +
+      `\n  e.g. lanes link status --target ${names[0]}` +
       (stale
         ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
           '  Unset it, or pass --target.'
-        : '') +
-      (inert
-        ? `\n\n  instance.default_target: ${inert} is still in this profile. It is no longer\n` +
-          '  read either, and is safe to delete.'
         : ''),
   );
 }
@@ -94,72 +101,36 @@ export function noTargetNamed(
  * an operator is looking at and reasonably believes is still working — which is
  * the whole difference between "this stopped working" and "this stopped working
  * and here is why".
+ *
+ * The deployed image still *sets* it, and that is not a contradiction: a
+ * revision serves exactly one target and passes it to `serve` on the command
+ * line. Nothing resolves from the variable on either side.
  */
 export const LEGACY_TARGET_ENV = 'LANES_LINK_TARGET';
 
-/**
- * The refusal for a target that is not in the file, in one spelling.
- *
- * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
- * than a sentence naming the available targets survives: the copies drift the
- * moment either learns something the other does not.
- */
-export function undeclaredTarget(target: string, config: Config, profile?: string): ConfigError {
-  const have = Object.keys(config.targets).join(', ') || 'none';
-  const whose = profile ? `profile "${profile}"` : 'this profile';
+/** The refusal for a target that is not in the registry, in one spelling. */
+export function notInRegistry(target: string, registry: Registry, root?: string): ConfigError {
+  const names = Object.keys(registry).sort();
+  const where = root ?? 'this workspace';
 
-  return new ConfigError(`Target "${target}" is not declared by ${whose} (have: ${have})`);
-}
-
-/**
- * The refusal for a target-scoped command that named no target.
- *
- * The twin of `noTargetNamed`, for the commands whose subject is the target
- * rather than one profile's view of it (ADR-043). It lists the target names the
- * *workspace* declares and who declares each, because the question those
- * commands are asking is "which endpoint", and a target only one profile knows
- * about is the answer to a different question than one they all share.
- *
- * Naming the profiles is not decoration. A target declared by one profile and
- * not its sibling is precisely the state that reads as a deployment having
- * disappeared, and it is invisible from inside either profile alone.
- */
-export function noTargetInWorkspace(
-  declared: ReadonlyMap<string, readonly string[]>,
-  workspaceRoot: string,
-  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
-): ConfigError {
-  if (declared.size === 0) {
-    return new ConfigError(
-      `--target is required, and no profile in ${workspaceRoot} declares one.\n` +
-        '  Create a profile with: lanes link profile add <name> --target local',
-    );
+  if (names.length === 0) {
+    return new ConfigError(`Target "${target}" is not declared, and ${where} declares none.`);
   }
 
-  const total = new Set(
-    [...declared.values()].flatMap((profiles) => profiles as readonly string[]),
-  ).size;
+  return new ConfigError(
+    `Target "${target}" is not declared in ${where}.\n\n  Targets\n${rows(registry, names)}`,
+  );
+}
 
-  const rows = [...declared.entries()]
-    .map(([name, profiles]) => {
-      // "every profile" rather than the list once it is all of them: the list is
-      // there to show a gap, and a complete one shows none.
-      const whose = profiles.length === total ? 'every profile' : profiles.join(', ');
-      return `    ${name}    ${whose}`;
+function rows(registry: Registry, names: readonly string[]): string {
+  return names
+    .map((name) => {
+      const entry = registry[name]!;
+      if (isPointer(entry)) return `    ${name}    ${entry.workspace}`;
+      const adapters = [entry.credentials?.adapter, entry.storage?.adapter]
+        .filter(Boolean)
+        .join('  ');
+      return `    ${name}    here  ${adapters}${entry.deploy ? '  deployable' : ''}`;
     })
     .join('\n');
-
-  const first = [...declared.keys()][0]!;
-  const stale = env[LEGACY_TARGET_ENV];
-
-  return new ConfigError(
-    '--target is required. This command acts on a target, and every profile\n' +
-      'that declares it.\n\n' +
-      `  Targets in ${workspaceRoot}\n${rows}\n` +
-      `\n  e.g. lanes link status --target ${first}` +
-      (stale
-        ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
-          '  Unset it, or pass --target.'
-        : ''),
-  );
 }

package/src/profile/testing.ts

@@ -0,0 +1,78 @@
+import { SUPPORTED_CONTRACT } from './schema.ts';
+
+/**
+ * Workspace files for tests, so a fixture says what it is testing.
+ *
+ * Under contract 1 a test workspace needed only `contract` and a profile, because
+ * the profile carried its own `targets:` block. The target is declared by the
+ * workspace now (ADR-052), so every fixture that opens a store needs one here —
+ * and thirty of them writing the same eight lines by hand is how a fixture ends
+ * up subtly different from the thing it is standing in for.
+ *
+ * Kept beside the schema rather than under a test directory, following
+ * `stores/blobs/testing.ts` and `stores/state/testing.ts`.
+ */
+
+/** The adapters each well-known test target gets. */
+const ADAPTERS: Record<string, string> = {
+  local: `    credentials: { adapter: file }
+    storage: { adapter: filesystem }`,
+  // Deployable, because that is what `cloud` means everywhere it is used as a
+  // fixture: the tests that name it are about a target with a service in front
+  // of it, and one without a `deploy:` block reads as an ordinary bucket.
+  cloud: `    credentials: { adapter: gcp-secret-manager, project: my-project }
+    storage: { adapter: gcs, bucket: your-bucket }
+    vault: { adapter: secret }
+    deploy:
+      platform: cloudrun
+      project: my-project
+      region: europe-west1
+      service: my-service`,
+  staging: `    credentials: { adapter: gcp-secret-manager, project: staging-project }
+    storage: { adapter: gcs, bucket: staging-bucket }`,
+  s3: `    credentials: { adapter: file }
+    storage:
+      adapter: s3
+      bucket: your-bucket
+      endpoint: https://example.storage.example.com/storage/v1/s3
+      region: eu-central-1
+      access_key_id_ref: s3/access_key_id
+      secret_access_key_ref: s3/secret_access_key`,
+};
+
+/**
+ * A `lanes-link.yaml` declaring the named targets.
+ *
+ * Anything not in the table above is given the local adapters, which is what a
+ * test naming an arbitrary target is nearly always after — it wants the name to
+ * resolve, not the bytes to go anywhere in particular.
+ */
+export function workspaceYaml(
+  targets: readonly string[] = ['local'],
+  options: { defaultProfile?: string } = {},
+): string {
+  const blocks = targets
+    .map((name) => `  ${name}:\n${ADAPTERS[name] ?? ADAPTERS['local']}`)
+    .join('\n');
+
+  return (
+    `contract: ${SUPPORTED_CONTRACT}\n` +
+    (options.defaultProfile ? `default_profile: ${options.defaultProfile}\n` : '') +
+    `targets:\n${blocks}\n`
+  );
+}
+
+/** A registry entry pointing at another workspace, for the pointer paths. */
+export function pointerYaml(
+  target: string,
+  workspace: string,
+  options: { defaultProfile?: string; alsoLocal?: boolean } = {},
+): string {
+  const local = options.alsoLocal === false ? '' : `  local:\n${ADAPTERS['local']}\n`;
+
+  return (
+    `contract: ${SUPPORTED_CONTRACT}\n` +
+    (options.defaultProfile ? `default_profile: ${options.defaultProfile}\n` : '') +
+    `targets:\n${local}  ${target}:\n    workspace: ${workspace}\n`
+  );
+}