@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/workspace-migrate.ts

@@ -1,3 +1,6 @@
+import { migrateToContract4, type Contract4Migration } from './contract4.ts';
+import { migrateToContract3, needsContract3, type Contract3Migration } from './contract3.ts';
+import { readSession } from '#auth/lanes/session.ts';
 import { parseDocument } from 'yaml';
 import {
   ConfigError,
@@ -16,6 +19,7 @@ import {
 } from '#profile';
 import { ConfigDocument } from './config-edit.ts';
 import { hoist, summarise } from './migrate-plan.ts';
+import { C3 } from './contract3-layout.ts';
 
 /**
  * Contract 1 → 2: the target moves out of the profile and into the workspace.
@@ -25,7 +29,7 @@ import { hoist, summarise } from './migrate-plan.ts';
  * of each profile — one in `~/.lanes-link`, one in the bucket the endpoint reads
  * — and gave them nothing to keep them honest. It failed the way it was always
  * going to: a local file was rewritten, lost its cloud target and eight
- * connections, and `status --target cloud` reported seven where the endpoint was
+ * connections, and `status --workspace cloud` reported seven where the endpoint was
  * serving fifteen. `sync targets` and ADR-044's deployment index were both
  * written in response to earlier rounds of the same thing.
  *
@@ -62,7 +66,7 @@ export interface WorkspaceMigration {
 /** Whether this workspace still holds anything at contract 1. */
 export async function needsMigration(workspaceRoot: string): Promise<boolean> {
   for (const profile of await listProfiles(workspaceRoot)) {
-    const text = await readWorkspaceFile(workspaceFiles(workspaceRoot), `profiles/${profile}.yaml`);
+    const text = await readWorkspaceFile(workspaceFiles(workspaceRoot), C3.profile(profile));
     if (text === null) continue;
     try {
       if (isLegacyProfile(parseDocument(text).toJSON())) return true;
@@ -91,7 +95,10 @@ export async function migrateWorkspace(
     [];
 
   for (const profile of names) {
-    const document = await ConfigDocument.open(workspaceRoot, profile);
+    // The contract-1 path, frozen. `open` resolves the live layout, which is
+    // contract 4's — so this read a profile that does not exist yet and the
+    // migration refused a workspace it was supposed to move.
+    const document = await ConfigDocument.openKey(workspaceRoot, C3.profile(profile));
     const raw = document.toJSON();
     if (!isLegacyProfile(raw)) continue;
 
@@ -122,12 +129,12 @@ export async function migrateWorkspace(
   const changes: string[] = [];
   for (const [name, entry] of Object.entries(registry)) {
     changes.push(
-      entry.workspace !== undefined
-        ? `targets.${name}: pointer to ${entry.workspace}`
-        : `targets.${name}: declared in ${WORKSPACE_FILE}`,
+      entry.at !== undefined
+        ? `workspaces.${name}: pointer to ${entry.at}`
+        : `targets.${name}: declared in ${C3.workspace}`,
     );
   }
-  for (const { profile } of legacy) changes.push(`profiles/${profile}.yaml: targets: removed, contract: 2`);
+  for (const { profile } of legacy) changes.push(`${C3.profile(profile)}: targets: removed, contract: 2`);
 
   if (!options.apply) {
     return {
@@ -147,17 +154,30 @@ export async function migrateWorkspace(
   // again.
   await writeRegistry(workspaceRoot, registry);
 
-  for (const { document } of legacy) {
+  for (const { document, profile } of legacy) {
     document.removeIn(['targets']);
-    document.setIn(['contract'], SUPPORTED_CONTRACT);
+    // Literally 2, not `SUPPORTED_CONTRACT`. This migration produces a
+    // contract-2 profile and nothing else; `migrateToContract3` takes it the
+    // rest of the way. Writing the current contract here would stamp a file
+    // that still has contract-2 shapes with the newest number, and the loader
+    // would then read it as a contract-3 document that is missing `grants:`.
+    document.setIn(['contract'], 2);
     // `instance.default_target` went with the block it selected from. It has
     // been inert since ADR-037 and there is now nothing for it to name.
     document.removeIn(['instance', 'default_target']);
-    // Shape-only: a profile may carry an unrelated problem the full loader
-    // refuses — a connection row still spelling a renamed provider is the one
-    // that happens — and blocking the structural fix on it would strand the file
-    // at a contract nothing reads. `doctor --fix` names and repairs that one.
-    await document.save({ shapeOnly: true });
+    // Written rather than saved, because `save` validates and what this
+    // produces is deliberately not valid *yet*: a contract-2 profile, which the
+    // runtime does not read. `migrateToContract3` is the step that makes it
+    // loadable, and it runs immediately after — so validating here would refuse
+    // the only shape this function is able to produce.
+    //
+    // Nothing is lost by not validating: the next step reads the file it just
+    // wrote, and `check` refuses anything either step leaves broken.
+    await writeWorkspaceFile(
+      workspaceFiles(workspaceRoot),
+      C3.profile(profile),
+      document.toString(),
+    );
   }
 
   return {
@@ -169,6 +189,98 @@ export async function migrateWorkspace(
   };
 }
 
+export interface ContractMigration {
+  readonly workspaceRoot: string;
+  /** The contract 1 → 2 half, when this workspace needed one. */
+  readonly legacy: WorkspaceMigration | null;
+  /** The contract 2 → 3 half, when this workspace needed one. */
+  readonly contract3: Contract3Migration | null;
+  readonly contract4: Contract4Migration | null;
+  /** Every profile either half rewrote, deduplicated. */
+  readonly profiles: readonly string[];
+  /** Targets written into the registry by the contract 1 → 2 half. */
+  readonly targets: readonly { name: string; kind: 'declared' | 'pointer'; where?: string }[];
+  /** Both halves' lines, in the order they happened. */
+  readonly changes: readonly string[];
+  /** Nothing to do: this workspace is already at `SUPPORTED_CONTRACT`. */
+  readonly alreadyCurrent: boolean;
+}
+
+/**
+ * Bring one workspace to `SUPPORTED_CONTRACT`, whatever it is on now.
+ *
+ * **This exists because "migrate a workspace" was spelled three times and only
+ * one of them arrived.** `update` ran the 1→2 step and then the 2→3 step;
+ * `deploy` and `doctor --fix` ran the first and stopped, which nothing said out
+ * loud — `migrateTargetWorkspace`'s own docstring claimed it brought a target
+ * "to the current contract" while calling only `migrateWorkspace`.
+ *
+ * What that cost is worth writing down, because it is not a refusal. A deploy
+ * uploaded contract-3 config over a contract-2 bucket and rolled a revision that
+ * read `data/state.kv` and `data/audit.log` — while the bytes sat where contract
+ * 2 put them, under `data/<profile>/`. The endpoint came up healthy and answered
+ * every call with an empty store: no memory, no tasks, no skills, and an audit
+ * log that verified as intact because an empty chain does. Nothing in the
+ * deploy, the health probe, or `doctor` had a way to notice.
+ *
+ * So there is one function now, and the contract number lives in one place. A
+ * fourth contract adds a step here and every caller gets it.
+ *
+ * **A dry run of a contract-1 workspace reports only the first half**, and that
+ * is honest rather than a gap: the 1→2 step wrote nothing, so the profiles are
+ * still contract 1 and the 2→3 step has nothing it recognises to describe. What
+ * it would do is knowable only after the step before it has run.
+ *
+ * **The signed-in subject is defaulted here rather than by each caller.** A
+ * migrated profile that lists nobody is an endpoint that advertises OAuth and
+ * then refuses its own owner, so it matters on every path — but `deployments`
+ * may not import `#auth` (see `MAY_IMPORT` in `src/architecture.test.ts`), and
+ * `deploy` is the caller that most needs it: once a target's profiles live in
+ * its bucket there is no upload behind it to put the members row back. A caller
+ * that knows better passes one; nobody signed in is a legitimate answer and
+ * stays default-deny on the identity axis.
+ */
+export async function migrateToCurrentContract(
+  workspaceRoot: string,
+  options: { apply: boolean; subject?: string; target?: string } = { apply: true },
+): Promise<ContractMigration> {
+  const legacy = (await needsMigration(workspaceRoot))
+    ? await migrateWorkspace(workspaceRoot, { apply: options.apply })
+    : null;
+
+  const subject = options.subject ?? (await readSession().catch(() => null))?.subject;
+
+  const contract3 = await migrateToContract3(workspaceRoot, {
+    apply: options.apply,
+    ...(subject === undefined ? {} : { subject }),
+  });
+
+  // In sequence, not in parallel: contract 4 moves what contract 3 produced, so
+  // it has to run against the tree the previous step left. With `apply: false`
+  // it sees the unmigrated shape and reports only what it can see from here —
+  // which is the honest preview, and why the count is not promised.
+  const contract4 = await migrateToContract4(workspaceRoot, {
+    apply: options.apply,
+    ...(options.target === undefined ? {} : { target: options.target }),
+  });
+
+  return {
+    workspaceRoot,
+    legacy: legacy !== null && !legacy.alreadyCurrent ? legacy : null,
+    contract3: contract3.alreadyCurrent ? null : contract3,
+    contract4: contract4.alreadyCurrent ? null : contract4,
+    profiles: [
+      ...new Set([...(legacy?.profiles ?? []), ...contract3.profiles, ...contract4.profiles]),
+    ],
+    targets: legacy?.targets ?? [],
+    changes: [...(legacy?.changes ?? []), ...contract3.changes, ...contract4.changes],
+    alreadyCurrent:
+      (legacy === null || legacy.alreadyCurrent) &&
+      contract3.alreadyCurrent &&
+      contract4.alreadyCurrent,
+  };
+}
+
 /**
  * Write the registry into the workspace file, creating it when absent.
  *
@@ -183,10 +295,10 @@ async function writeRegistry(
   registry: Record<string, WorkspaceTarget>,
 ): Promise<void> {
   const files = workspaceFiles(workspaceRoot);
-  const text = (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
+  const text = (await readWorkspaceFile(files, C3.workspace)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
   const document = parseDocument(text);
   const current = (document.toJSON() ?? {}) as {
-    targets?: Record<string, WorkspaceTarget>;
+    workspaces?: Record<string, WorkspaceTarget>;
     deployments?: {
       target?: string;
       workspace?: string;
@@ -198,7 +310,7 @@ async function writeRegistry(
   // Anything already in the file wins over what was hoisted: a workspace part
   // way through this has entries that are already right, and re-deriving them
   // from a profile that still carries a stale block would undo a correction.
-  const merged: Record<string, WorkspaceTarget> = { ...registry, ...(current.targets ?? {}) };
+  const merged: Record<string, WorkspaceTarget> = { ...registry, ...(current.workspaces ?? {}) };
 
   // ADR-044's index, folded into the entries it described. `primary` and
   // `last_deploy` were kept beside the declaration precisely because the
@@ -214,23 +326,28 @@ async function writeRegistry(
     };
   }
 
+  // `workspaces:`, not `targets:` — the registry is read back by the current
+  // schema even while the profiles beside it are still contract 2, because it
+  // is one document that both migrations share (ADR-061). The profiles are the
+  // half that stays at 2 until `migrateToContract3` runs.
   document.setIn(['contract'], SUPPORTED_CONTRACT);
   document.setIn(
-    ['targets'],
+    ['workspaces'],
     Object.fromEntries(Object.entries(merged).sort(([a], [b]) => a.localeCompare(b))),
   );
+  document.deleteIn(['targets']);
   document.deleteIn(['deployments']);
   document.deleteIn(['default_target']);
 
-  await writeWorkspaceFile(files, WORKSPACE_FILE, String(document));
+  await writeWorkspaceFile(files, C3.workspace, String(document));
 }
 
 function describe(
   registry: Record<string, WorkspaceTarget>,
 ): { name: string; kind: 'declared' | 'pointer'; where?: string }[] {
   return Object.entries(registry).map(([name, entry]) =>
-    entry.workspace !== undefined
-      ? { name, kind: 'pointer' as const, where: entry.workspace }
+    entry.at !== undefined
+      ? { name, kind: 'pointer' as const, where: entry.at }
       : { name, kind: 'declared' as const },
   );
 }
@@ -249,6 +366,19 @@ function describe(
  * part of what it already means (ADR-052).
  */
 export async function refuseIfUnmigrated(root: string): Promise<void> {
+  if (await needsContract3(root)) {
+    throw new ConfigError(
+      `${root} is a contract 2 workspace, and this version does not read one.\n\n` +
+        '  Under contract 2 each profile carried its own connections and one flat\n' +
+        '  policy. Connections belong to the workspace now, and a profile selects\n' +
+        '  among them with per-connection scopes (ADR-057, ADR-058).\n\n' +
+        '  Migrate it:  lanes link update\n' +
+        '  Preview it:  lanes link update --check\n\n' +
+        '  Nothing is deleted by the migration: credentials are merged and read back\n' +
+        '  before the old stores are left in place.',
+    );
+  }
+
   if (!(await needsMigration(root))) return;
 
   throw new ConfigError(
@@ -258,6 +388,6 @@ export async function refuseIfUnmigrated(root: string): Promise<void> {
       '  copies of every profile that could drift apart (ADR-052).\n\n' +
       '  Migrate it:  lanes link update\n' +
       '  A deployed target is migrated by the deploy that ships the image reading it:\n' +
-      '               lanes link deploy --target <name>',
+      '               lanes link deploy --workspace <name>',
   );
 }

package/src/connectivity/manifest/provider.ts

@@ -18,7 +18,9 @@ import { connectionVariableSchema, placeholdersInConnector } from './variables.t
  *
  *   - built-ins, written as typed TS modules under `#providers/` and validated
  *     at import
- *   - the profile's own manifests in `data/<profile>/providers.d/*.yaml`, validated on load
+ *   - the workspace's own manifests in `data/providers.d/*.yaml`, validated on load
+ *     — the workspace's, not a profile's, because a manifest defines a
+ *     connection and connections stopped belonging to profiles (ADR-057)
  *
  * That second one is the scalability claim. A service nobody has integrated is
  * a YAML file the operator writes, not a pull request they wait on.
@@ -74,25 +76,44 @@ export const providerManifestSchema = z.object({
 export type ProviderManifest = z.infer<typeof providerManifestSchema>;
 
 /**
- * Provider ids reserved for the owner layer.
+ * The owner layer's provider ids — Lanes' own surfaces.
+ *
+ * **`lanes_` on each, which is what stops them needing to be reserved.** They
+ * were `memory`, `tasks`, `assets`, `skills`, `vault`, `entities` — six of the
+ * most obvious words a vendor manifest might want, held back from every
+ * operator so the built-ins could have them. `buildRegistry` registers these
+ * before `PROVIDERS`, so a manifest claiming one threw at startup rather than
+ * being shadowed (ADR-051); the reservation is what made that a refusal instead
+ * of a collision. Prefixed, there is nothing to reserve: an operator's own
+ * `memory` connector is now a legal thing to declare.
+ *
+ * It is also the shape the vendor-qualified providers already use —
+ * `google_tasks`, `gmail_imap`, `icloud_mail` — and it reads the same way: the
+ * half before the underscore says whose surface this is.
  *
  * The order is read: `#server/mcp`'s instructions emit one paragraph per
  * reachable id in this sequence, so it is the order an agent meets them in.
- * `entities` is appended rather than inserted alphabetically so that it lands
- * beside `identity`: the two answer the same question about different people,
- * and the instructions collapse them into one paragraph when both are reachable.
+ * `lanes_entities` is appended rather than inserted alphabetically so that it
+ * lands beside `lanes_identity`: the two answer the same question about
+ * different people, and the instructions collapse them into one paragraph when
+ * both are reachable.
  */
 export const RESERVED_PROVIDER_IDS: readonly string[] = [
-  'memory',
-  'tasks',
-  'assets',
-  'skills',
-  'vault',
-  'setup',
-  'identity',
-  'entities',
+  'lanes_memory',
+  'lanes_tasks',
+  'lanes_assets',
+  'lanes_skills',
+  'lanes_vault',
+  'lanes_setup',
+  'lanes_identity',
+  'lanes_entities',
 ];
 
+/** Old id to new, for the contract-4 migration and for a refusal that names it. */
+export const RENAMED_OWNER_PROVIDERS: ReadonlyMap<string, string> = new Map(
+  RESERVED_PROVIDER_IDS.map((id) => [id.slice('lanes_'.length), id]),
+);
+
 /**
  * Validate a manifest, with the cross-field rules the schema alone cannot
  * express.

package/src/connectivity/manifest/requirements.ts

@@ -76,7 +76,7 @@ export interface SetupNeeds {
 function storeCommand(ref: string, placeholder: string, where: Selection): string {
   return (
     `printf %s "${placeholder}" | lanes link secrets set ${ref}` +
-    ` --profile ${where.profile} --target ${where.target}`
+    ` --profile ${where.profile} --workspace ${where.target}`
   );
 }
 

package/src/connectivity/transports/imap/parser.ts

@@ -16,6 +16,30 @@
 const CR = 0x0d;
 const LF = 0x0a;
 
+/**
+ * The most this will accumulate before refusing a response.
+ *
+ * A literal's length is a number the *server* writes — `{1234}` — and the
+ * reader's job is to wait until that many bytes have arrived. With no ceiling
+ * that is an allocation an upstream decides the size of, and the upstream is
+ * not always one this endpoint chose: a connector names its own host, so a
+ * connection pointed at a hostile or compromised server could announce a
+ * literal of any size and be believed.
+ *
+ * Sixty-four mebibytes because that is already the ceiling on the other side of
+ * the same journey — `MAX_UPLOAD_BYTES` in `server/attachments.ts` — and a
+ * message larger than the largest attachment this endpoint will accept is not
+ * one it can do anything useful with. Every mail host's own limit is well below
+ * it, so this is never what refuses a legitimate read.
+ *
+ * Applied twice, and both are needed. The announced length is refused up front,
+ * so an absurd number costs nothing rather than being discovered after the
+ * bytes arrive. The accumulated buffer is refused too, because one response may
+ * announce several literals and a server that never completes a response would
+ * otherwise grow this without ever announcing anything unreasonable.
+ */
+export const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+
 /** A parsed element of a response. */
 export type ImapToken =
   | { readonly kind: 'atom'; readonly value: string }
@@ -32,27 +56,56 @@ export type ImapToken =
  */
 export class ResponseAssembler {
   #buffer = new Uint8Array(0);
-
+  /** Bytes in use. The buffer is grown ahead of this and is not a length. */
+  #length = 0;
+
+  /**
+   * Take a chunk off the socket.
+   *
+   * Capacity doubles rather than growing to fit. It used to allocate exactly
+   * `held + chunk` and copy everything across on every chunk, which is
+   * quadratic in the size of a response — a thirty-megabyte message arriving in
+   * sixty-four-kilobyte pieces copied several gigabytes to assemble, and that
+   * was the *legitimate* case. Doubling makes each byte move a constant number
+   * of times.
+   */
   push(chunk: Uint8Array): void {
-    const merged = new Uint8Array(this.#buffer.length + chunk.length);
-    merged.set(this.#buffer);
-    merged.set(chunk, this.#buffer.length);
-    this.#buffer = merged;
+    const needed = this.#length + chunk.length;
+    if (needed > MAX_RESPONSE_BYTES) {
+      throw new Error(
+        `The server sent more than ${MAX_RESPONSE_BYTES} bytes without completing a response.`,
+      );
+    }
+
+    if (needed > this.#buffer.length) {
+      let capacity = Math.max(this.#buffer.length, 8192);
+      while (capacity < needed) capacity *= 2;
+
+      const grown = new Uint8Array(Math.min(capacity, MAX_RESPONSE_BYTES));
+      grown.set(this.#buffer.subarray(0, this.#length));
+      this.#buffer = grown;
+    }
+
+    this.#buffer.set(chunk, this.#length);
+    this.#length = needed;
   }
 
   /** The next complete response, or undefined while more bytes are needed. */
   next(): Uint8Array | undefined {
-    const end = completeResponseEnd(this.#buffer);
+    const end = completeResponseEnd(this.#buffer.subarray(0, this.#length));
     if (end === undefined) return undefined;
 
-    const response = this.#buffer.subarray(0, end);
-    this.#buffer = this.#buffer.slice(end);
+    // A copy, not a view: the remainder is shifted down in place below, which
+    // would otherwise rewrite the bytes underneath the response just returned.
+    const response = this.#buffer.slice(0, end);
+    this.#buffer.copyWithin(0, end, this.#length);
+    this.#length -= end;
     return response;
   }
 
   /** Whatever has arrived but does not yet form a response. For diagnostics. */
   get pending(): number {
-    return this.#buffer.length;
+    return this.#length;
   }
 }
 
@@ -67,6 +120,14 @@ function completeResponseEnd(buffer: Uint8Array): number | undefined {
     const announced = literalLength(buffer, cursor, crlf);
     if (announced === undefined) return crlf + 2;
 
+    // Refused on the announcement rather than after the bytes turn up: the
+    // number is the server's, and believing an absurd one means waiting for it.
+    if (announced > MAX_RESPONSE_BYTES) {
+      throw new Error(
+        `The server announced a ${announced}-byte literal, over the ${MAX_RESPONSE_BYTES}-byte limit.`,
+      );
+    }
+
     const afterLiteral = crlf + 2 + announced;
     if (buffer.length < afterLiteral) return undefined;
 

package/src/deployments/adapters/filesystem.ts

@@ -1,7 +1,7 @@
 import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import type { BlobKey, BlobMetadata, BlobStore } from '#stores/blobs';
+import { containedKey, type BlobKey, type BlobMetadata, type BlobStore } from '#stores/blobs';
 
 /**
  * Filesystem blob store — the `local` target's adapter.
@@ -54,12 +54,27 @@ export function createFilesystemBlobStore(options: FilesystemBlobStoreOptions):
    * this adapter is also usable directly, and a containment check belongs at
    * the point where a path actually becomes a filesystem operation. Defence in
    * depth is cheap; a provider escaping its directory is not.
+   *
+   * **The rule is `containedKey`'s, not this file's.** It used to be a copy,
+   * and the copy did not agree: it tested `rel.startsWith('..')` where it meant
+   * "the first segment is `..`", so a key beginning with two dots and
+   * continuing — an ordinary name — was refused here and accepted by every
+   * other adapter. That is the divergence `conformance.ts` exists to prevent,
+   * and it was reachable from an ordinary argument, because a provider passes
+   * a caller's name straight through as a key.
+   *
+   * Kept as a resolve-then-join rather than deferring the whole path: the
+   * shared rule answers "does this land inside", and this adapter still has to
+   * turn the answer into a filesystem path.
    */
   const pathFor = (key: BlobKey): string => {
-    const resolved = resolve(root, key);
+    const resolved = resolve(root, containedKey(key));
     const rel = relative(root, resolved);
 
-    if (rel === '' || rel.startsWith('..') || rel.startsWith(`..${sep}`)) {
+    // Unreachable once `containedKey` has answered, and kept because this is
+    // the line where a path becomes a filesystem operation: a future change to
+    // either side should fail here rather than escape.
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`)) {
       throw new Error(`Blob key resolves outside the store root: ${key}`);
     }
     return resolved;

package/src/deployments/bind.ts

@@ -121,7 +121,7 @@ export async function bindConnectionCredentials(input: {
           `could not bind ${connection.provider}.${connection.id}'s credential to ` +
           `${serviceAccount}, so the deployed endpoint will be able to read it and not ` +
           'rotate it — which fails about an hour after the first use. ' +
-          `Run \`lanes link deploy --target ${input.target}\` to bind it. ` +
+          `Run \`lanes link deploy --workspace ${input.target}\` to bind it. ` +
           `(${driver.tool}: ${result.stderr.trim().split('\n').slice(-1)[0] ?? 'failed'})`,
       };
     }