@lanes-sh/link 0.7.2 → 0.9.0

package/src/profile/connections.ts

@@ -0,0 +1,195 @@
+import { ConfigError, describeRename } from './load.ts';
+import type { Config, ConnectionConfig, GrantConfig, TargetConfig } from './schema.ts';
+
+/**
+ * The join between a profile and the workspace it lives in.
+ *
+ * A connection is declared once, in `connections.yaml`, and a profile names the
+ * ones it selects in `grants:` (ADR-057). Nothing downstream should perform
+ * that join itself: `dispatch`, `visibility`, `status`, `setup` and the
+ * reconciler all want the same answer — *which accounts does this profile
+ * reach, and what may be done with each* — and three implementations of one
+ * join is three chances for discovery and enforcement to disagree, which is the
+ * failure `allowedConnections` exists to prevent on the capability axis.
+ *
+ * So this file answers it once and everything else asks.
+ */
+
+/** `<provider>.<id>` — the same string an agent passes as `connection`. */
+export function connectionRefOf(connection: ConnectionConfig): string {
+  return `${connection.provider}.${connection.id}`;
+}
+
+/**
+ * One account this profile reaches, with the rules that govern it.
+ *
+ * The grant travels with the connection deliberately. Every caller that has a
+ * connection in its hand is about to ask what may be done with it, and handing
+ * back a pair removes the second lookup — along with the possibility of pairing
+ * a connection with the wrong profile's grant, which is the one mistake this
+ * shape makes unrepresentable.
+ */
+export interface SelectedConnection {
+  readonly ref: string;
+  readonly connection: ConnectionConfig;
+  readonly grant: GrantConfig;
+}
+
+/**
+ * The connections a profile selects, in the order it declares them.
+ *
+ * Declaration order rather than the workspace's, because the profile is what
+ * this is a view of, and a listing that reordered the owner's own file would be
+ * answering a question nobody asked. A grant naming a connection that does not
+ * exist is skipped here and refused by `assertGrantsResolve` at load — this
+ * function is a view, not a gate, and a view that threw would make every
+ * listing depend on the config being valid.
+ */
+export function selectConnections(
+  config: Config,
+  available: readonly ConnectionConfig[],
+): SelectedConnection[] {
+  const byRef = new Map(available.map((connection) => [connectionRefOf(connection), connection]));
+
+  return config.grants.flatMap((grant) => {
+    const connection = byRef.get(grant.connection);
+    return connection === undefined ? [] : [{ ref: grant.connection, connection, grant }];
+  });
+}
+
+/**
+ * Every reference in a profile resolves, and nothing is granted twice.
+ *
+ * Two failures, and the second is the one worth having a check for. A grant
+ * naming a connection the workspace does not hold is visible the moment anyone
+ * looks — the surface is simply absent. Two grants naming the *same* connection
+ * is not: one of them silently wins, and which one depends on iteration order,
+ * so a profile could deny a capability in one row and allow it in another and
+ * behave differently between releases. Refusing at load is what keeps
+ * `grants:` a set rather than a sequence with precedence.
+ */
+export function assertGrantsResolve(
+  config: Config,
+  available: readonly ConnectionConfig[],
+): void {
+  const refs = new Set(available.map(connectionRefOf));
+
+  const missing = config.grants
+    .map((grant) => grant.connection)
+    .filter((ref) => !refs.has(ref));
+
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `Profile "${config.instance.profile}" grants a connection this workspace does not hold: ` +
+        `${[...new Set(missing)].join(', ')}.\n` +
+        `  Connections live in connections.yaml. Run "lanes link connection list" to see them.`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const duplicated = config.grants
+    .map((grant) => grant.connection)
+    .filter((ref) => (seen.has(ref) ? true : (seen.add(ref), false)));
+
+  if (duplicated.length > 0) {
+    throw new ConfigError(
+      `Profile "${config.instance.profile}" grants the same connection more than once: ` +
+        `${[...new Set(duplicated)].join(', ')}.\n` +
+        `  One row per connection — merge the allow and deny lists into it.`,
+    );
+  }
+}
+
+/**
+ * No two connections in a workspace share a reference.
+ *
+ * `<provider>.<id>` is what a credential ref is derived from and what an agent
+ * names, so a duplicate is two accounts answering to one address. It was
+ * impossible to express before contract 3 only because a profile held its own
+ * list; one workspace-wide list makes it expressible, so it has to be refused.
+ */
+export function assertConnectionsUnique(connections: readonly ConnectionConfig[]): void {
+  const seen = new Set<string>();
+  const duplicated = connections
+    .map(connectionRefOf)
+    .filter((ref) => (seen.has(ref) ? true : (seen.add(ref), false)));
+
+  if (duplicated.length > 0) {
+    throw new ConfigError(
+      `connections.yaml declares the same connection more than once: ` +
+        `${[...new Set(duplicated)].join(', ')}.\n` +
+        `  A connection is addressed as "<provider>.<id>", so two rows sharing one ` +
+        `are two accounts at one address.`,
+    );
+  }
+}
+
+/**
+ * The one connection this profile grants for a single-instance provider.
+ *
+ * `undefined` when it grants none, which is a legitimate state: a profile that
+ * denies `skills.*` reaches no skills, and the surface is absent rather than
+ * empty.
+ */
+export function soleGrantFor(config: Config, provider: string): string | undefined {
+  const prefix = `${provider}.`;
+  const granted = config.grants.find((grant) => grant.connection.startsWith(prefix));
+  return granted?.connection.slice(prefix.length);
+}
+
+/**
+ * Where this profile's vault document lives, in one spelling.
+ *
+ * **Two places derived this, and they disagreed.** `openVault` names it per
+ * connection (ADR-059) — `vault/main` for a profile granting `vault.main` — and
+ * the deploy's provisioning step named `vault/document`, the contract-2 constant.
+ * So every deployed workspace that did not hand-write `vault.ref` created and
+ * granted one secret and then asked Secret Manager for another: the revision got
+ * `PERMISSION_DENIED` on the ref nothing had made, exited 1, and never listened
+ * on its port. A deploy that hand-wrote a `ref` worked, which is what kept this
+ * out of sight — a rehearsal that sets one is testing the path nobody takes.
+ *
+ * `ref` still wins where it is written, because a deployment already sealing
+ * under one name has to keep opening it.
+ */
+export function vaultRef(declared: TargetConfig | undefined, config: Config): string {
+  // **The profile, then the connection.** This was `vault/<connection>`, which
+  // was distinct per profile only while each profile had its own vault
+  // instance. ADR-066 merges the owner layer to one row per surface, so every
+  // profile grants `lanes_vault.lan5` and every profile opened one sealed
+  // document — `vault_put` from `personal` overwriting `work`'s item of the
+  // same id, and `vault_get` reading the other profile's credential. The `file`
+  // and `blob` adapters take the profile from `layout`; this is the same fact
+  // for the adapter every deployment uses.
+  //
+  // A `ref` the target states outright still wins: a deployment already sealing
+  // under one name has to keep opening it.
+  const connection = soleGrantFor(config, 'lanes_vault') ?? 'main';
+  return declared?.vault?.ref ?? `vault/${config.instance.profile}/${connection}`;
+}
+
+/**
+ * A connection whose provider id moved out from under it.
+ *
+ * `tasks` is the built-in task list; Google's is `google_tasks` (ADR-051). A row
+ * that still says `tasks` and names an address rather than the built-in's own
+ * label is somebody's Google account resolving to the wrong provider — and the
+ * failure is silent in the worst way: the row loads, reconcile calls it active,
+ * and every call goes to an empty local store.
+ *
+ * Here rather than in the profile loader, because the evidence is the *account*
+ * and accounts live in this file.
+ */
+export function assertNoRenamedProviders(
+  connections: readonly ConnectionConfig[],
+  repair: string,
+): void {
+  const problems = connections.flatMap((connection, index) => {
+    const renamed = describeRename(connection, repair);
+    return renamed === null ? [] : [`connections[${index}]: ${renamed}`];
+  });
+
+  if (problems.length > 0) {
+    throw new ConfigError(`connections.yaml:\n${problems.map((p) => `  ${p}`).join('\n')}`, problems);
+  }
+}

package/src/profile/deployments.ts

@@ -1,7 +1,13 @@
 import { parseDocument } from 'yaml';
 import { readWorkspaceFile, workspaceFiles, writeWorkspaceFile } from './files.ts';
-import { SUPPORTED_CONTRACT, workspaceSchema, type WorkspaceTarget } from './schema.ts';
+import {
+  SUPPORTED_CONTRACT,
+  workspaceSchema,
+  workspaceTargetSchema,
+  type WorkspaceTarget,
+} from './schema.ts';
 import { WORKSPACE_FILE } from './workspace.ts';
+import { LEGACY_WORKSPACE_FILE } from './layout.ts';
 
 /**
  * Writing the target registry.
@@ -74,24 +80,96 @@ async function editRegistry(
   edit: (targets: Record<string, WorkspaceTarget>) => void,
 ): Promise<void> {
   const files = workspaceFiles(workspaceRoot);
+
+  // **Either name, and the one it read is the one it writes.** Reading only the
+  // new name meant an unmigrated workspace fell through to a bare
+  // `contract: 4` document: `deploy` then wrote a registry holding one target
+  // beside the `lanes-link.yaml` that declared them all, and `readWorkspace`
+  // prefers the new name — so every other target vanished from a command whose
+  // job was to record one.
+  const held = await readWorkspaceFile(files, WORKSPACE_FILE);
+  const key = held === null ? LEGACY_WORKSPACE_FILE : WORKSPACE_FILE;
   const text =
-    (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
+    held ??
+    (await readWorkspaceFile(files, LEGACY_WORKSPACE_FILE)) ??
+    `contract: ${SUPPORTED_CONTRACT}\n`;
 
   const document = parseDocument(text);
-  const targets = (document.toJSON()?.targets ?? {}) as Record<string, WorkspaceTarget>;
+  const raw = (document.toJSON() ?? {}) as {
+    workspaces?: Record<string, WorkspaceTarget>;
+    targets?: Record<string, LegacyTargetEntry>;
+  };
+
+  // **Whichever block this file already keeps its registry in.**
+  //
+  // This read and wrote `workspaces:` unconditionally. A contract-2 file keeps
+  // it under `targets:`, so recording a deploy into one found no registry,
+  // added the entry to an empty object, and wrote a *second* block beside the
+  // first. `workspaceSchema` has no `targets` key and zod strips what it does
+  // not declare, so the hybrid validated and landed.
+  //
+  // That is reachable from an ordinary command: `deploy` migrates the target
+  // workspace, never the local one, so deploying to a bucket from a laptop that
+  // has not run `update` yet does exactly this. The result is a file whose two
+  // registries disagree — and `rewriteRegistry` then rebuilds `workspaces:`
+  // from the stale `targets:`, discarding the newer record without a word.
+  //
+  // Writing into the block the file already has keeps it coherent at whatever
+  // contract it is, and leaves converting the two to the migration that owns
+  // that job.
+  const legacy = raw.workspaces === undefined && raw.targets !== undefined;
+  const block = legacy ? 'targets' : 'workspaces';
+  const targets = legacy ? current(raw.targets ?? {}) : (raw.workspaces ?? {});
 
   edit(targets);
 
-  if (Object.keys(targets).length === 0) document.deleteIn(['targets']);
-  else document.setIn(['targets'], sorted(targets));
+  if (Object.keys(targets).length === 0) document.deleteIn([block]);
+  else document.setIn([block], sorted(legacy ? asLegacy(targets) : targets));
 
   // Validated before it lands, on the rendered tree rather than the input, so
   // what is checked is what would be read back.
-  workspaceSchema.parse(document.toJSON());
+  //
+  // `workspaceSchema` declares no `targets` key and zod strips what it does not
+  // declare, so on the legacy branch parsing the whole document checks nothing
+  // at all — an entry that is neither pointer nor declaration, or one trying to
+  // be both, landed silently and only surfaced weeks later when the migration
+  // converted it and refused. The entries are checked directly there, in the
+  // contract-3 shape `current` normalised them to.
+  if (legacy) for (const entry of Object.values(targets)) workspaceTargetSchema.parse(entry);
+  else workspaceSchema.parse(document.toJSON());
 
-  await writeWorkspaceFile(files, WORKSPACE_FILE, String(document));
+  await writeWorkspaceFile(files, key, String(document));
 }
 
-function sorted(targets: Record<string, WorkspaceTarget>): Record<string, WorkspaceTarget> {
+function sorted<T>(targets: Record<string, T>): Record<string, T> {
   return Object.fromEntries(Object.entries(targets).sort(([a], [b]) => a.localeCompare(b)));
 }
+
+/**
+ * A contract-2 entry spelled a pointer `workspace:`; contract 3 spells it `at:`.
+ *
+ * Normalised on the way in and back on the way out, so `edit` and `pick` see one
+ * shape and never have to ask which contract they are looking at — and so a
+ * legacy file keeps the spelling its own schema expects.
+ */
+interface LegacyTargetEntry extends Omit<WorkspaceTarget, 'at'> {
+  workspace?: string;
+}
+
+function current(targets: Record<string, LegacyTargetEntry>): Record<string, WorkspaceTarget> {
+  return Object.fromEntries(
+    Object.entries(targets).map(([name, entry]) => {
+      const { workspace, ...rest } = entry;
+      return [name, workspace === undefined ? rest : { at: workspace, ...rest }];
+    }),
+  );
+}
+
+function asLegacy(targets: Record<string, WorkspaceTarget>): Record<string, LegacyTargetEntry> {
+  return Object.fromEntries(
+    Object.entries(targets).map(([name, entry]) => {
+      const { at, ...rest } = entry;
+      return [name, at === undefined ? rest : { workspace: at, ...rest }];
+    }),
+  );
+}

package/src/profile/index.ts

@@ -1,10 +1,14 @@
 /**
  * A profile: its file, its schema, and where it lives on disk.
  *
- * **One profile = one config = one database = one credential store.** Profiles
- * share an endpoint and its token (ADR-009); they never share state. This
- * component owns everything about what a profile *is* — the YAML contract, the
- * loader that validates it, and the workspace resolution that finds it.
+ * **A profile is a selection, not an inventory.** Since contract 3 the accounts
+ * live in the workspace's `connections.yaml` and a profile names the ones it
+ * grants (ADR-057), so profiles share an endpoint, its token, the credential
+ * store, and any connection they both select. What they do not share is the
+ * grant: two profiles on one mailbox can permit entirely different things
+ * (ADR-058). This component owns everything about what a profile *is* — the
+ * YAML contract, the loader that validates it, the join onto the workspace's
+ * connections, and the resolution that finds them.
  *
  * What it deliberately does not own: which providers exist (`#registry`) and
  * how a call runs (`#dispatch`). Those were all one package called `core`,
@@ -15,23 +19,44 @@ export {
   DEPLOY_DEFAULTS,
   SUPPORTED_CONTRACT,
   configSchema,
+  SINGLE_INSTANCE_PROVIDERS,
+  connectionsFileSchema,
   declaredTarget,
+  grantSchema,
   isPointer,
+  memberSchema,
   workspaceSchema,
   workspaceTargetSchema,
   type AuthorizationConfig,
   type Config,
   type ConnectionConfig,
+  type ConnectionsFile,
   type DeployConfig,
+  type GrantConfig,
   type IdentityEntry,
+  type MemberConfig,
   type PolicyRuleConfig,
   type TargetConfig,
   type WorkspaceConfig,
   type WorkspaceTarget,
 } from './schema.ts';
 
+export {
+  assertConnectionsUnique,
+  assertGrantsResolve,
+  assertNoRenamedProviders,
+  connectionRefOf,
+  selectConnections,
+  soleGrantFor,
+  vaultRef,
+  type SelectedConnection,
+} from './connections.ts';
+
+export { PAIR_CERT_REF, PAIR_KEY_REF, PAIR_TOKEN_REF } from './pairing.ts';
+
 export {
   KNOWLEDGE_LAYOUT,
+  KNOWLEDGE_PREFIX,
   knowledgeRoot,
   knowledgeTargetSchema,
   parseRepository,
@@ -103,13 +128,17 @@ export {
   writeWorkspaceFile,
 } from './files.ts';
 export {
+  CONNECTIONS_FILE,
+  readConnections,
   type ProfileSelection,
   type Resolution,
   type ResolveOptions,
 } from './workspace.ts';
 
 export {
-  DATA_DIR,
+  PROFILE_FILE,
+  LEGACY_DATA_DIR,
+  LEGACY_WORKSPACE_FILE,
+  legacyProfileConfig,
   layout,
-  profileDir,
 } from './layout.ts';

package/src/profile/knowledge.ts

@@ -96,11 +96,17 @@ export type KnowledgeConfig = z.infer<typeof knowledgeTargetSchema>;
 /**
  * Where each area sits inside the repository.
  *
- * Three directories, named after the three things that move. `memory` is also
- * the memory provider's own blob namespace — the prefix core scopes it into under
- * the profile's blob root — which is why the same word does both jobs: the
- * route that redirects it and the directory it lands in are the same fact, and
- * spelling them separately is how they would come to disagree.
+ * Three directories, named after the three things that move — and named for a
+ * *reader*, because a knowledge repository is somebody's own and they browse it
+ * on GitHub. `memory/` is what belongs at the top of that tree, not
+ * `lanes_memory/`.
+ *
+ * **This used to be the provider's blob prefix as well**, on the reasoning that
+ * one word doing both jobs could not come to disagree with itself. Contract 4
+ * prefixed the owner layer (`lanes_memory`), so the two are no longer the same
+ * string and the choice has to be made rather than avoided: the route below
+ * reads `PROVIDER_PREFIX`, and this stays the readable name. `KNOWLEDGE_ROUTES`
+ * pairs them in one place so a rename still cannot move one without the other.
  *
  * Declared here, beside the schema, so the runtime that opens these stores and
  * the command that migrates into them read one definition.
@@ -113,6 +119,13 @@ export const KNOWLEDGE_LAYOUT = {
 
 export type KnowledgeArea = keyof typeof KNOWLEDGE_LAYOUT;
 
+/** The blob prefix each area is scoped into locally — the provider's own id. */
+export const KNOWLEDGE_PREFIX = {
+  memory: 'lanes_memory',
+  skills: 'lanes_skills',
+  entities: 'lanes_entities',
+} as const;
+
 /** The directory one area occupies, under the profile's optional path prefix. */
 export function knowledgeRoot(knowledge: KnowledgeConfig, area: KnowledgeArea): string {
   const directory = KNOWLEDGE_LAYOUT[area];