@lanes-sh/link 0.2.2 → 0.3.0

package/src/deployments/adapters/github.ts

@@ -0,0 +1,125 @@
+import { containedKey, type BlobKey, type BlobMetadata, type BlobStore } from '#stores/blobs';
+import { inferContentType } from './filesystem.ts';
+import type { GithubRepository } from './github-repo.ts';
+
+/**
+ * A GitHub repository as a `BlobStore`.
+ *
+ * The one thing a profile can put here is what the owner wrote — memory entries
+ * and skills. Not state, not the audit log, not the credential store, and never
+ * the vault; `src/profile/knowledge.ts` says why, and says it as a schema with
+ * no field to set rather than as a default.
+ *
+ * **The API, not a clone.** A clone would be faster and would work offline, and
+ * it fails on the property this interface exists to provide: a container
+ * filesystem is discarded on every revision, so a deployed endpoint's clone
+ * would be re-fetched at best and silently empty at worst. That is precisely
+ * the bug ADR-014 §2 fixed for the vault, and re-introducing it for memory is
+ * not worth the latency. It also needs a `git` binary, which the image does not
+ * carry. ADR-041.
+ *
+ * Vendor-named, like `gcs.ts` and `gcp-secret-manager.ts` beside it: ADR-013's
+ * rule is that an adapter for a *protocol* takes the protocol's name, and a
+ * client for one vendor's API cannot honestly claim one.
+ *
+ * **Several of these share one `GithubRepository`.** Memory and skills are two
+ * roots in one repository, and pointing both at one client means one head, one
+ * tree, and one blob cache between them.
+ */
+
+export interface GithubBlobStoreOptions {
+  readonly repository: GithubRepository;
+  /**
+   * A directory inside the repository that this store is rooted at — `memory`,
+   * `skills`, or those under a profile's own `path` prefix. Keys never see it.
+   */
+  readonly root?: string | undefined;
+  /** What a write commit says it did. `%s` is the key. */
+  readonly message?: ((operation: 'store' | 'remove', key: string) => string) | undefined;
+}
+
+const DEFAULT_MESSAGE = (operation: 'store' | 'remove', key: string): string =>
+  `${operation === 'store' ? 'Store' : 'Remove'} ${key}`;
+
+export function createGithubBlobStore(options: GithubBlobStoreOptions): BlobStore {
+  const repository = options.repository;
+  const message = options.message ?? DEFAULT_MESSAGE;
+  const root = (options.root ?? '').replace(/^\/+/, '').replace(/\/+$/, '');
+  const prefix = root === '' ? '' : `${root}/`;
+
+  /**
+   * A key becomes a path in the repository.
+   *
+   * `containedKey` is `#stores/blobs`', not a second rule written here.
+   * `conformance.ts` asserts that a key one target refuses is not one another
+   * accepts, and that can only hold while there is exactly one answer to what
+   * a key resolves to.
+   */
+  const pathFor = (key: BlobKey): string => `${prefix}${containedKey(key)}`;
+
+  /** The reverse, for a listing. Null when the path is outside this root. */
+  const keyFor = (path: string): BlobKey | null =>
+    path.startsWith(prefix) ? path.slice(prefix.length) : null;
+
+  return {
+    async put(key, data, putOptions) {
+      // `putOptions.contentType` is accepted and not stored, which is the one
+      // place this adapter cannot match the others. There is nowhere to put it:
+      // a sidecar would be a file in the owner's own repository, listed beside
+      // their entries and loaded as one. `list` infers from the extension
+      // instead, using the same map the filesystem adapter infers from — which
+      // covers every type anything here writes.
+      void putOptions;
+      await repository.writeFile(pathFor(key), data, message('store', key));
+    },
+
+    async get(key) {
+      const path = pathFor(key);
+      const { entries } = await repository.entries();
+      const entry = entries.get(path);
+      // Absence is a value, not an error — every caller is written against null.
+      if (!entry) return null;
+
+      // An empty file has a real blob and zero bytes; `blob` returns the empty
+      // array rather than null, which is the case `conformance.ts` pins.
+      return repository.blob(entry.sha);
+    },
+
+    async has(key) {
+      const path = pathFor(key);
+      return (await repository.entries()).entries.has(path);
+    },
+
+    async delete(key) {
+      // Deleting what is not there is not a failure: callers use this to make
+      // absence true, and a sweep racing another sweep must not throw.
+      await repository.deleteFile(pathFor(key), message('remove', key));
+    },
+
+    async list(innerPrefix) {
+      const { entries, committedAt } = await repository.entries();
+      const wanted = innerPrefix ?? '';
+      const found: BlobMetadata[] = [];
+
+      for (const entry of entries.values()) {
+        const key = keyFor(entry.path);
+        if (key === null || !key.startsWith(wanted)) continue;
+
+        const contentType = inferContentType(key);
+        found.push({
+          key,
+          size: entry.size,
+          ...(contentType ? { contentType } : {}),
+          // The branch tip's date, the same for every entry in one listing.
+          // Per-file timestamps would be one `GET /commits?path=…` each, and
+          // nothing needs them: `skillFingerprint` only needs this to change
+          // when the tree does, and memory uses it as a fallback for a
+          // hand-written file with no `updated_at` in its frontmatter.
+          modifiedAt: committedAt,
+        });
+      }
+
+      return found.sort((a, b) => a.key.localeCompare(b.key));
+    },
+  };
+}

package/src/deployments/deploy.ts

@@ -1,4 +1,4 @@
-import { ConfigError, resolveDeployTarget, type DeployConfig } from '#profile';
+import { ConfigError, type DeployConfig } from '#profile';
 import { announce, fail, heading, ok, print, style, warn } from '#cli/output.ts';
 import { staleNudge } from '#cli/release.ts';
 import { confirm, isInteractive } from '#cli/prompt.ts';
@@ -8,6 +8,7 @@ import { printSteps, runSteps } from './steps.ts';
 import { driverFor } from './drivers.ts';
 import { prepareSecrets, readableRefs, rotatableRefs } from './prepare.ts';
 import { deployedWorkspace, repairSetupSurface, uploadWorkspace } from './upload.ts';
+import { unservableProfiles, unservableRefusal } from './servable.ts';
 
 /**
  * `lanes link deploy` — set up what is missing, build the image, roll a revision,
@@ -46,13 +47,20 @@ export interface DeployFlags extends GlobalFlags {
 export async function deploy(flags: DeployFlags): Promise<void> {
   // The one command allowed to name a target that does not exist yet: creating
   // it is what a first deploy is for.
-  const { resolution, config } = await resolveProfile(flags, { allowUndeclaredTarget: true });
-
-  // And the one command that can work out which target it meant. `resolveProfile`
-  // falls back to `instance.default_target`, which is the target commands *run*
-  // against — `local`, and never the answer to "deploy what".
-  const { target, source } = resolveDeployTarget(config, flags.target);
-  announce({ ...resolution, target, targetSource: source });
+  //
+  // It used to work out its own target too — the one declaring a `deploy` block,
+  // guessing when there was one, refusing when there were two, and inventing
+  // `cloud` when there were none. That inference was a defence against
+  // `instance.default_target`, which is `local` on a scaffolded profile and
+  // never the answer to "deploy what". With the fallback gone (ADR-037) the
+  // defence has nothing to defend against, and what is left is three behaviours
+  // from one command line on the command that creates cloud resources and rolls
+  // a public URL — where `allowUndeclaredTarget` means a mistake is not refused
+  // but surveyed, written into the profile, and deployed as a new service.
+  const { resolution, config, target } = await resolveProfile(flags, {
+    allowUndeclaredTarget: true,
+  });
+  announce(resolution);
 
   // `check` before anything external, per the gate order: a config that will be
   // rejected on boot should be rejected here, not after a five-minute build.
@@ -103,7 +111,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     deploy: deployConfig,
     tag,
     target,
-    ...(flags.profile !== undefined ? { profile: flags.profile } : {}),
+    profile: resolution.profile,
     ...(workspace !== undefined ? { workspace } : {}),
     ...(secretEnv ? { secretEnv } : {}),
   });
@@ -168,8 +176,9 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     for (const problem of prepared.blocking) print(fail(problem));
     throw new ConfigError(
       'The deployed instance cannot start without these. Store them with ' +
-        `lanes link secrets set <ref> --target ${target}, or copy a local setup with ` +
-        `lanes link secrets push --from local --to ${target}.`,
+        `lanes link secrets set <ref> --profile ${resolution.profile} --target ${target}, or ` +
+        `copy a local setup with lanes link secrets push --profile ${resolution.profile} ` +
+        `--from local --to ${target}.`,
     );
   }
 
@@ -193,6 +202,25 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // the upload sends would leave a served profile without the surface — this
   // bug again, one profile over.
   if (workspace) {
+    // Before anything is copied, and before the rollout: the endpoint opens
+    // every profile in the bucket against this one target, so a profile that
+    // does not declare it is not a profile that gets skipped — it is a revision
+    // that never goes healthy. `servable.ts` has the whole failure.
+    //
+    // Here rather than at the top of the command because it reads the same
+    // scope the upload does, and that scope is not settled until `workspace`
+    // says there is a bucket to send to at all.
+    const unservable = await unservableProfiles({
+      workspaceRoot: resolution.workspaceRoot,
+      profile: flags.profile,
+      target,
+    });
+
+    if (unservable.length > 0) {
+      heading('Cannot be served');
+      throw new ConfigError(unservableRefusal(unservable, target));
+    }
+
     await repairSetupSurface(resolution.workspaceRoot, flags.profile);
 
     // Before the rollout, so the revision that comes up finds a config to read.
@@ -208,7 +236,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   if (!url) {
     print(
       warn(
-        `deployed, but the platform reported no URL yet — run: lanes link outputs --target ${target}`,
+        `deployed, but the platform reported no URL yet — run: lanes link outputs --profile ${resolution.profile} --target ${target}`,
       ),
     );
     return;
@@ -218,9 +246,9 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   print(`  ${url}/mcp`);
   print(await healthLine(url));
   print('');
-  print(registerLine(target));
+  print(registerLine(resolution.profile, target));
 
-  reportUnauthorised(prepared.warnings, target);
+  reportUnauthorised(prepared.warnings, resolution.profile, target);
 }
 
 /**
@@ -242,9 +270,10 @@ export async function deploy(flags: DeployFlags): Promise<void> {
  * appeared only on a later re-deploy, by which point the connector is usually
  * registered and the ordering is no longer available to get right.
  */
-function registerLine(target: string): string {
+function registerLine(profile: string, target: string): string {
   return style.dim(
-    `  Connect your accounts first, then register with: lanes link outputs --target ${target}\n` +
+    `  Connect your accounts first, then register with:\n` +
+      `    lanes link outputs --profile ${profile} --target ${target}\n` +
       '  A client keeps the tool list it fetched when it connected, so one registered\n' +
       '  before the accounts holds a surface without them until it is re-added.',
   );
@@ -264,7 +293,7 @@ function registerLine(target: string): string {
  * refusing it, naming the connection rather than the staleness. Reconcile now
  * runs again on every reload, and `connect` asks for one (ADR-029).
  */
-function reportUnauthorised(warnings: readonly string[], target: string): void {
+function reportUnauthorised(warnings: readonly string[], profile: string, target: string): void {
   if (warnings.length === 0) return;
 
   heading('Not authorised yet');
@@ -273,7 +302,7 @@ function reportUnauthorised(warnings: readonly string[], target: string): void {
   print(
     style.dim(
       '  A browser consent per account is the one step this cannot take for you:\n' +
-        `    lanes link connect <provider> --target ${target}\n` +
+        `    lanes link connect <provider> --profile ${profile} --target ${target}\n` +
         '  Each is served as soon as it is authorised. There is no second deploy —\n' +
         '  deploying is how code gets here, and authorising an account changes none.',
     ),
@@ -313,7 +342,7 @@ async function healthLine(url: string): Promise<string> {
     return ok(
       body.profiles
         ? `healthy — serving ${body.profiles.join(', ')}`
-        : 'healthy — run `lanes link outputs` for what it serves',
+        : 'healthy — run `lanes link outputs` with this profile and target for what it serves',
     );
   } catch {
     // A cold start plus a database connect can outrun a short probe, and

package/src/deployments/driver.ts

@@ -39,7 +39,14 @@ export interface PlanInput {
   readonly deploy: DeployConfig;
   readonly tag: string;
   readonly target: string;
-  readonly profile?: string | undefined;
+  /**
+   * The primary profile this revision serves.
+   *
+   * Required rather than optional: `deploy` names it (ADR-037), and a revision
+   * that boots without `LANES_LINK_PROFILE` refuses. Leaving it optional here is
+   * what let deployments ship without the variable at all.
+   */
+  readonly profile: string;
   /**
    * Where the running instance reads its config, as a store URL.
    *

package/src/deployments/gcp/driver.ts

@@ -103,7 +103,9 @@ export function deployPlan(input: PlanInput): DeployStep[] {
         '--set-env-vars',
         [
           `LANES_LINK_TARGET=${input.target}`,
-          ...(input.profile ? [`LANES_LINK_PROFILE=${input.profile}`] : []),
+          // Unconditional: `deploy` requires --profile (ADR-037), so this is
+          // always known, and a revision without it refuses at boot.
+          `LANES_LINK_PROFILE=${input.profile}`,
           ...(input.workspace ? [`LANES_LINK_HOME=${input.workspace}`] : []),
         ].join(','),
         ...secretMounts(input.secretEnv),

package/src/deployments/knowledge.ts

@@ -0,0 +1,119 @@
+import type { SecretStore } from '#secrets';
+import type { BlobStore } from '#stores/blobs';
+import { knowledgeRoot, type KnowledgeConfig } from '#profile';
+import { requireSecret, type TargetInput } from './target.ts';
+import type { FetchLike } from './adapters/github-api.ts';
+// Type-only, so a target with no `knowledge` block never loads the adapter.
+// The same rule `target.ts` follows for the cloud adapters, kept here by the
+// fact that a type import is erased entirely.
+import type { GithubRepository } from './adapters/github-repo.ts';
+// Re-exported so a caller that wants to replace the transport does not have to
+// reach past this module into an adapter. It is narrower than
+// `typeof globalThis.fetch`, which under Bun's types carries a `preconnect` a
+// test double would otherwise have to stub.
+export type { FetchLike } from './adapters/github-api.ts';
+
+/**
+ * Opening the place a profile keeps its memory and its skills, when that is not
+ * the place it keeps everything else.
+ *
+ * Its own file rather than a fifth case in `target.ts`, because it is not the
+ * same kind of decision. `target.ts` answers "where does this target run" —
+ * credentials here, bytes there — and every consumer of a `BlobStore` rides
+ * that one answer. This answers a narrower one: two directories of documents
+ * the owner wrote have somewhere else to be, and nothing else moves with them.
+ *
+ * ADR-041 has the argument. `src/profile/knowledge.ts` has the contract, and
+ * the reason there is no field here that could name the credential store or the
+ * vault.
+ */
+
+/**
+ * One repository client, two stores.
+ *
+ * Memory and skills are two directories in one repository, and pointing both at
+ * one client means one branch head, one tree, and one blob cache between them —
+ * so the endpoint's two-second skill poll keeps memory's view current for free.
+ * Two clients would each poll, each cache, and could disagree about which
+ * commit is current.
+ */
+export interface KnowledgeStores {
+  readonly repository: GithubRepository;
+  readonly skills: BlobStore;
+  /** Rooted at the repository's memory directory; keys are `<connection>/<id>.md`. */
+  readonly memory: BlobStore;
+  /** One line for `target show` and `doctor`, so the config file is not the only witness. */
+  readonly describe: string;
+}
+
+/**
+ * `undefined` when the target declares no `knowledge` block — which is every
+ * profile written before it existed, so the caller's fallback is the path that
+ * has always run rather than a special case.
+ */
+export async function openKnowledge(
+  input: TargetInput,
+  secrets: SecretStore,
+  /** Injected for tests. The repository is the only thing these stores reach. */
+  call?: FetchLike,
+): Promise<KnowledgeStores | undefined> {
+  const { declared, target } = input;
+  const knowledge = declared.knowledge;
+  if (!knowledge) return undefined;
+
+  const token = await requireSecret(
+    secrets,
+    knowledge.token_ref,
+    `targets.${target}.knowledge.token_ref`,
+    target,
+    'the github adapter',
+  );
+
+  const { GithubRepository } = await import('./adapters/github-repo.ts');
+  const repository = new GithubRepository({
+    repo: knowledge.repo,
+    token,
+    ...(knowledge.branch !== undefined ? { branch: knowledge.branch } : {}),
+    ...(call ? { fetch: call } : {}),
+  });
+
+  return {
+    repository,
+    ...(await knowledgeStores(repository, knowledge)),
+    describe: describeKnowledge(knowledge),
+  };
+}
+
+/**
+ * The two stores a knowledge repository holds.
+ *
+ * Separate from `openKnowledge` because `lanes link knowledge use` builds these
+ * against a repository it is still probing — before any of it has been written
+ * into the config `openKnowledge` reads. Two spellings of one layout is how a
+ * migration comes to write where nothing later looks.
+ */
+export async function knowledgeStores(
+  repository: GithubRepository,
+  knowledge: KnowledgeConfig,
+): Promise<{ skills: BlobStore; memory: BlobStore }> {
+  const { createGithubBlobStore } = await import('./adapters/github.ts');
+
+  const build = (area: 'memory' | 'skills'): BlobStore =>
+    createGithubBlobStore({
+      repository,
+      root: knowledgeRoot(knowledge, area),
+      // What the commit says it did. Named per area rather than left to the
+      // adapter's default, because "Store main/note.md" in a repository holding
+      // both is a line that does not say which of them changed.
+      message: (operation, key) =>
+        `${operation === 'store' ? 'Store' : 'Remove'} ${area === 'skills' ? 'skill' : 'memory'} ${key}`,
+    });
+
+  return { skills: build('skills'), memory: build('memory') };
+}
+
+/** `github:owner/name#branch/path`, in one place so every reader agrees. */
+export function describeKnowledge(knowledge: KnowledgeConfig): string {
+  const branch = knowledge.branch ? `#${knowledge.branch}` : '';
+  return `github:${knowledge.repo}${branch}${knowledge.path ? `/${knowledge.path}` : ''}`;
+}

package/src/deployments/prepare.ts

@@ -188,7 +188,7 @@ export async function prepareSecrets(input: PrepareInput): Promise<PrepareResult
     if (!ref || (await credentials.has(ref))) continue;
     warnings.push(
       `${connection.provider}.${connection.id} is not authorised yet — no credential at "${ref}"\n` +
-        `    lanes link connect ${connection.provider} --target ${target} --id ${connection.id}`,
+        `    lanes link connect ${connection.provider} --profile ${input.config.instance.profile} --target ${target} --id ${connection.id}`,
     );
   }
 
@@ -252,6 +252,6 @@ async function seedProfileToken(input: {
   }
 
   const { created } = await ensureProfileToken(input.credentials, ref);
-  if (created) print(ok(`minted an endpoint token at "${ref}" — read it with: lanes link token show`));
+  if (created) print(ok(`minted an endpoint token at "${ref}" — read it with lanes link token show`));
 }
 

package/src/deployments/servable.ts

@@ -0,0 +1,81 @@
+import { listProfiles, loadProfileConfig } from '#profile';
+
+/**
+ * Whether every profile a deploy sends can actually run on the target it sends them to.
+ *
+ * A deploy uploads config for a set of profiles and rolls a revision baked with
+ * one `LANES_LINK_TARGET`. The endpoint then opens *every* profile it finds in
+ * the bucket against that one target — see `openReconciled` — and a profile that
+ * does not declare it throws on the way up. The catch there closes the runtimes
+ * and rethrows, so the container exits and the revision never goes healthy.
+ *
+ * That is the whole failure, and its shape is what makes it worth a pre-flight:
+ * the profile at fault is usually the one just scaffolded, the operator was not
+ * thinking about the deployment when they made it, and the symptom is a revision
+ * that will not start — which reads as a problem with the deploy, the image, or
+ * the platform. Nothing points at the new profile. Refusing here costs one file
+ * read per profile and names it.
+ *
+ * Its own file, not a private function in `deploy.ts`, for the reason
+ * `handoff.ts` gives: `deploy.test.ts` does not import `deploy.ts`, and making
+ * it do so would pull the whole CLI runtime into a unit test.
+ */
+
+export interface Unservable {
+  readonly profile: string;
+  /** What it does declare, so the refusal says how far off it is. */
+  readonly declares: readonly string[];
+}
+
+/**
+ * The profiles this deploy would send that the revision could not open.
+ *
+ * Scoped exactly as `uploadWorkspace` and `repairSetupSurface` are — by the
+ * `--profile` flag, absent meaning the whole workspace — because the set that
+ * gets uploaded is the set that gets served, and checking a different one would
+ * be checking the wrong question.
+ *
+ * A profile that cannot be parsed is not reported here. It is already fatal
+ * further along, with a better message than this could give, and a YAML error
+ * dressed up as "cannot run on cloud" would send someone looking at their
+ * targets instead of their syntax.
+ */
+export async function unservableProfiles(input: {
+  readonly workspaceRoot: string;
+  readonly profile: string | undefined;
+  readonly target: string;
+}): Promise<Unservable[]> {
+  const found: Unservable[] = [];
+
+  for (const name of await listProfiles(input.workspaceRoot)) {
+    if (input.profile !== undefined && name !== input.profile) continue;
+
+    let declared: string[];
+    try {
+      const { config } = await loadProfileConfig(input.workspaceRoot, name);
+      declared = Object.keys(config.targets);
+    } catch {
+      continue;
+    }
+
+    if (!declared.includes(input.target)) found.push({ profile: name, declares: declared });
+  }
+
+  return found;
+}
+
+/** The refusal, as a block, so the wording is testable without a deploy. */
+export function unservableRefusal(found: readonly Unservable[], target: string): string {
+  const rows = found
+    .map((one) => `        ${one.profile}   declares: ${one.declares.join(', ') || 'nothing'}`)
+    .join('\n');
+
+  return (
+    `${found.length} profile${found.length === 1 ? '' : 's'} would be uploaded that cannot run on "${target}":\n` +
+    `${rows}\n\n` +
+    '      The endpoint opens every profile in the bucket with this target, so the\n' +
+    '      revision would come up and refuse to start.\n' +
+    `        lanes link profile add <name> --target ${target}   declares it on a new one\n` +
+    '        --profile <name>                          deploys just the one'
+  );
+}

package/src/deployments/target.ts

@@ -271,15 +271,16 @@ export async function openStorage(
  * Two refs make the same two mistakes available twice over, and "undefined is
  * not a string" from inside an S3 client is not a diagnosis.
  */
-async function requireSecret(
+export async function requireSecret(
   secrets: SecretStore,
   ref: string | undefined,
   field: string,
   target: string,
+  requiredBy = 'the s3 adapter',
 ): Promise<string> {
   if (!ref) {
     throw new ConfigError(
-      `${field} is required for the s3 adapter — the key is a credential, so config names it ` +
+      `${field} is required for ${requiredBy} — the value is a credential, so config names it ` +
         'rather than carrying it.',
     );
   }

package/src/deployments/upload.ts

@@ -7,7 +7,8 @@ import {
   type Config,
   type TargetConfig,
 } from '#profile';
-import { ConfigDocument, ensureSetupConnection, repairLines, repaired } from '#cli/config-edit.ts';
+import { ConfigDocument } from '#cli/config-edit.ts';
+import { ensureSetupConnection, repairLines, repaired } from '#cli/config-repair.ts';
 import { ok, print, style, warn } from '#cli/output.ts';
 
 /**

package/src/dispatch/dispatch.ts

@@ -241,7 +241,7 @@ export class Dispatcher {
         return (outcome = deny(
           'denied_connection_unauthorized',
           record.status === 'unauthorized'
-            ? `Connection ${request.connectionKey} has no valid credential. Run: lanes link connect ${request.connectionKey}`
+            ? `Connection ${request.connectionKey} has no valid credential. Connecting it again for this profile and target would store one.`
             : `Connection ${request.connectionKey} is disabled.`,
         ));
       }

package/src/profile/identity.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { identifier } from './primitives.ts';
+
+/**
+ * Who the owner is, in this profile — the names, addresses, and handles they
+ * want used when something is written as them.
+ *
+ * A profile already says what is *reachable*: connections, credentials, what
+ * policy permits. It said nothing about *whose* they are. So an agent composing
+ * a message, opening a pull request, or signing off had to infer a name from
+ * whatever happened to be in the conversation, and it mixed them across
+ * profiles — the work signature on a personal mailbox, the wrong handle in a
+ * commit trailer. The information was knowable and simply not written down.
+ *
+ * Three shapes were possible and only this one is right:
+ *
+ * - **A list, not a map.** `names: [John, Semin]` cannot say *when* to use
+ *   which, and the note is the whole point — an owner with two names has them
+ *   for a reason. A flat list of `{kind, value, note}` mirrors `connections`,
+ *   which is the other list in this file whose order a reader relies on.
+ * - **`kind` is free-form**, any `identifier`. Shipping an enum would mean a
+ *   release every time someone wants `linkedin`, `pronouns`, or `signature`,
+ *   and there is nothing this file could do with the knowledge that a value is
+ *   an email that would be worth that. Rendering is generic and stays generic.
+ * - **`note` is prose, not a reference.** Binding an entry to a connection was
+ *   the obvious alternative and is a trap: it puts a cross-reference into
+ *   `assertReferentialIntegrity`, and then renaming a connection breaks config
+ *   *load* — the profile stops opening because a name in a signature moved.
+ *   The agent reading "use with the personal mailbox" gets it right without
+ *   costing anything the day that mailbox is renamed.
+ *
+ * Declaration order is meaningful and preserved: the first entry of a kind is
+ * the one to reach for absent a reason, and the reader of the YAML sees the same
+ * order the agent is told.
+ *
+ * Not a secret, and worth being explicit about why, because this is the first
+ * block in a profile that holds the owner's own data rather than a pointer to
+ * it. A name and an address are disclosed by the first message of any mailbox
+ * this endpoint serves; withholding them here while serving the mailbox would
+ * be theatre. What is refused is a *credential* pasted into a value — a token
+ * beginning `ghp_` in a `github` entry trips `secret-detection.ts` like anything
+ * else in this file, which is that check working rather than getting in the way.
+ */
+export const identityEntrySchema = z.object({
+  /** `name`, `email`, `github` — or anything else the owner finds useful. */
+  kind: identifier,
+  value: z.string().min(1),
+  /**
+   * When this one applies, in the owner's words.
+   *
+   * Optional, and usually absent on the only entry of its kind: a profile with
+   * one address needs no note explaining which address to use. It earns its
+   * place the moment there are two.
+   */
+  note: z.string().min(1).optional(),
+});
+
+export const identitySchema = z.array(identityEntrySchema);
+
+export type IdentityEntry = z.infer<typeof identityEntrySchema>;