@lanes-sh/link 0.7.2 → 0.9.0

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,28 @@ 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).
+ *
+ * **4 gave a profile its bytes back, and retired `data/`** (ADR-066, ADR-067).
+ * Contract 3 moved the owner layer's stores beside the *connection*, so a
+ * profile owned nothing and two profiles granting one memory read one note. The
+ * profile is the container again — `profiles/<name>/` holds its declaration and
+ * everything it owns — and `data/`, which had been the line between what a
+ * revision reads and what it writes, stopped drawing that line the moment the
+ * declaration moved inside it. No file's *shape* changed: `grants:`,
+ * `members:` and `connections.yaml` are untouched, and only the paths moved.
+ *
+ * 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 = 4;
 
 /**
  * There is no `database:` block any more.
@@ -136,7 +160,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 +351,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[] = ['lanes_skills', 'lanes_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 +499,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 +554,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 +617,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 +638,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 +670,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 +709,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 +728,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('  ');

package/src/profile/testing.ts

@@ -58,7 +58,7 @@ export function workspaceYaml(
   return (
     `contract: ${SUPPORTED_CONTRACT}\n` +
     (options.defaultProfile ? `default_profile: ${options.defaultProfile}\n` : '') +
-    `targets:\n${blocks}\n`
+    `workspaces:\n${blocks}\n`
   );
 }
 
@@ -73,6 +73,108 @@ export function pointerYaml(
   return (
     `contract: ${SUPPORTED_CONTRACT}\n` +
     (options.defaultProfile ? `default_profile: ${options.defaultProfile}\n` : '') +
-    `targets:\n${local}  ${target}:\n    workspace: ${workspace}\n`
+    `workspaces:\n${local}  ${target}:\n    at: ${workspace}\n`
   );
 }
+
+/**
+ * A `connections.yaml` holding the owner layer plus whatever a test names.
+ *
+ * Every fixture that opens a runtime needs one now: a profile's grants name rows
+ * in this file, and `assertGrantsResolve` refuses a grant with nothing behind it
+ * (ADR-057). Thirty tests writing the seven owner-layer rows by hand is how a
+ * fixture ends up subtly different from what `newConnectionsTemplate` writes.
+ */
+export function connectionsYaml(
+  extra: readonly { id: string; provider: string; account: string }[] = [],
+): string {
+  const owner = [
+    { id: 'lan1', provider: 'lanes_memory', account: 'Memory' },
+    { id: 'lan2', provider: 'lanes_tasks', account: 'Tasks' },
+    { id: 'lan3', provider: 'lanes_assets', account: 'Assets' },
+    { id: 'lan4', provider: 'lanes_skills', account: 'Skills' },
+    { id: 'lan5', provider: 'lanes_vault', account: 'Vault' },
+    { id: 'lan6', provider: 'lanes_setup', account: 'Setup' },
+    { id: 'lan7', provider: 'lanes_entities', account: 'Entities' },
+  ];
+
+  const rows = [...owner, ...extra]
+    .map((row) => `  - { id: ${row.id}, provider: ${row.provider}, account: ${row.account} }`)
+    .join('\n');
+
+  return `contract: ${SUPPORTED_CONTRACT}\nconnections:\n${rows}\noauth_apps: {}\n`;
+}
+
+/** The owner-layer grant rows a fresh profile carries, plus whatever a test names. */
+export function grantsYaml(
+  extra: readonly { connection: string; allow?: readonly string[]; deny?: readonly string[] }[] = [],
+): string {
+  const owner = [
+    'lanes_memory',
+    'lanes_tasks',
+    'lanes_assets',
+    'lanes_skills',
+    'lanes_vault',
+    'lanes_setup',
+    'lanes_entities',
+  ].map((provider, index) => ({
+    connection: `${provider}.lan${index + 1}`,
+    allow: [`${provider}.*`],
+    deny: [],
+  }));
+
+  return [...owner, ...extra]
+    .map(
+      (grant) =>
+        `  - { connection: ${grant.connection}, allow: [${(grant.allow ?? []).join(', ')}], ` +
+        `deny: [${(grant.deny ?? []).join(', ')}] }`,
+    )
+    .join('\n');
+}
+
+/** A whole profile document at the current contract, for a test that needs one. */
+export function profileYaml(
+  profile: string,
+  options: {
+    port?: number;
+    grants?: readonly { connection: string; allow?: readonly string[]; deny?: readonly string[] }[];
+    members?: readonly string[];
+  } = {},
+): string {
+  const members = (options.members ?? [])
+    .map((subject) => `  - { subject: ${subject}, role: owner }`)
+    .join('\n');
+
+  return (
+    `contract: ${SUPPORTED_CONTRACT}\n` +
+    `instance:\n  profile: ${profile}\n  port: ${options.port ?? 7337}\n  host: 127.0.0.1\n` +
+    `auth:\n  mode: bearer\n  token_ref: profile/token\n` +
+    `grants:\n${grantsYaml(options.grants ?? [])}\n` +
+    `members:${members ? `\n${members}` : ' []'}\n`
+  );
+}
+
+/**
+ * Write a profile's declaration into a fixture workspace.
+ *
+ * A profile is a directory now (ADR-067), so writing one means creating that
+ * directory — which every fixture that used to write `profiles/<name>.yaml`
+ * beside its siblings got for free. Centralised here rather than repeated in
+ * twenty test files, for the reason `layout.ts` exists at all: the last time a
+ * path was spelled in two places one of them went stale, and the failure was a
+ * listing that disagreed with a loader about what existed.
+ */
+export async function writeProfileFixture(
+  root: string,
+  profile: string,
+  body: string,
+): Promise<string> {
+  const { mkdir, writeFile } = await import('node:fs/promises');
+  const { dirname, join } = await import('node:path');
+  const { layout } = await import('./layout.ts');
+
+  const path = join(root, layout.profileConfig(profile));
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body);
+  return path;
+}