@lanes-sh/link 0.2.2 → 0.3.1

package/src/deployments/sync-apply.ts

@@ -0,0 +1,276 @@
+import { parseDocument } from 'yaml';
+import {
+  ConfigError,
+  parseConfig,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+  type Config,
+} from '#profile';
+import { ConfigDocument } from '#cli/config-edit.ts';
+import { diffConfigs, keyedArrayFor, type Change } from './sync.ts';
+import { isWorkspaceConfig } from './upload.ts';
+
+/**
+ * Deciding a difference and writing it down.
+ *
+ * The rule is union, and refusal where a union is not possible. Anything one
+ * side is missing is copied to it; anything both sides hold differently stops
+ * the sync and prints the diff. Last-writer-wins was the alternative and it is
+ * the failure this whole command exists because of — a copy of a profile
+ * quietly replaced another that held six connections it did not.
+ *
+ * `--prefer` is how a conflict is resolved, and it is deliberately one flag for
+ * the whole run rather than a prompt per key: a sync that asks twelve questions
+ * is one answered by pressing return, and the twelfth answer is the one that
+ * matters.
+ */
+
+export type Prefer = 'local' | 'remote';
+
+export interface ProfileSync {
+  readonly profile: string;
+  readonly changes: readonly Change[];
+  /** Only on the local side: the remote file does not exist at all. */
+  readonly onlyRemote: boolean;
+  readonly onlyLocal: boolean;
+}
+
+const profileKey = (profile: string): string => `profiles/${profile}.yaml`;
+
+/** Parse a profile out of a workspace, or `undefined` when it is not there. */
+async function readProfile(root: string, profile: string): Promise<Config | undefined> {
+  const text = await readWorkspaceFile(workspaceFiles(root), profileKey(profile));
+  if (text === null) return undefined;
+
+  // A remote copy that will not parse is a conflict the operator has to look
+  // at, not something to overwrite with the local one — it may be the only copy
+  // of something.
+  try {
+    return parseConfig(text, `${root}/${profileKey(profile)}`).config;
+  } catch (error) {
+    throw new ConfigError(
+      `${root}/${profileKey(profile)} could not be read, so it cannot be merged:\n` +
+        `  ${error instanceof Error ? (error.message.split('\n')[0] ?? '') : String(error)}\n` +
+        '  Fix it there, or pass --prefer local to overwrite it.',
+    );
+  }
+}
+
+/**
+ * The same file, unvalidated, as the source of what actually gets written.
+ *
+ * The diff compares *validated* configs, because that is the only comparison
+ * that gets equality right: `policy.allow: [gmail.*]` and
+ * `[{capability: gmail.*}]` are the same grant written two ways, and a raw
+ * comparison would call that a conflict.
+ *
+ * What is written has to come from here all the same. Writing the validated
+ * value back means writing every default zod filled in on the way through —
+ * `min_instances: 0`, an OAuth token lifetime nobody set — into a file the
+ * operator reads. Recovering six connections should not also silently expand
+ * three policy rules into a shape they were not written in.
+ *
+ * The two cannot disagree about whether something is missing: a default is
+ * filled in identically on both sides, so it is equal, so it is never a change.
+ */
+async function readRawProfile(root: string, profile: string): Promise<unknown> {
+  const text = await readWorkspaceFile(workspaceFiles(root), profileKey(profile));
+  return text === null ? undefined : parseDocument(text).toJSON();
+}
+
+/** Every profile either side has, so one that exists only remotely is still seen. */
+export async function profilesInEither(local: string, remote: string): Promise<string[]> {
+  const names = async (root: string): Promise<string[]> =>
+    (await workspaceFiles(root).list('profiles/'))
+      .map((entry) => entry.key.slice('profiles/'.length))
+      .filter((name) => name.endsWith('.yaml') && !name.endsWith('.example.yaml'))
+      .filter((name) => !name.includes('/'))
+      .map((name) => name.slice(0, -'.yaml'.length));
+
+  return [...new Set([...(await names(local)), ...(await names(remote))])].sort();
+}
+
+/** What differs, for one profile, between the workspace and a target's copy. */
+export async function planProfile(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  prefer: Prefer | undefined,
+): Promise<ProfileSync> {
+  const local = await readProfile(localRoot, profile);
+  const remote = prefer === 'local' && local !== undefined
+    ? // Told local wins outright: there is nothing to ask the remote copy, and
+      // reading it could only produce conflicts already decided.
+      undefined
+    : await readProfile(remoteRoot, profile);
+
+  return {
+    profile,
+    changes: diffConfigs(local, remote),
+    onlyRemote: local === undefined && remote !== undefined,
+    onlyLocal: remote === undefined && local !== undefined,
+  };
+}
+
+/** The changes that will be written, once `--prefer` has decided the rest. */
+export function resolved(changes: readonly Change[], prefer: Prefer | undefined): Change[] {
+  return changes.map((change) => {
+    if (change.direction !== 'conflict') return change;
+    if (prefer === undefined) return change;
+    return { ...change, direction: prefer === 'remote' ? 'pull' : 'push' } as Change;
+  });
+}
+
+/**
+ * Write everything the local copy is missing into the local profile.
+ *
+ * Through `ConfigDocument`, so the comments an operator wrote survive a
+ * recovery, and so the result is validated before it lands — a merged config
+ * that would not load is a worse outcome than the one being fixed.
+ *
+ * A keyed-array element is written by rewriting its array. A YAML sequence has
+ * no addressable slot for "the entry whose provider is gmail", and merging by
+ * index is exactly the comparison this avoided making in the first place.
+ */
+export async function applyPulls(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  changes: readonly Change[],
+): Promise<number> {
+  const pulls = changes.filter((change) => change.direction === 'pull');
+  if (pulls.length === 0) return 0;
+
+  // A profile local does not have at all is a file copy: there is no document
+  // to edit, and every key in it is a pull.
+  if (pulls.some((change) => change.path.length === 0)) {
+    const text = await readWorkspaceFile(workspaceFiles(remoteRoot), profileKey(profile));
+    if (text === null) return 0;
+    await writeWorkspaceFile(workspaceFiles(localRoot), profileKey(profile), text);
+    return 1;
+  }
+
+  const document = await ConfigDocument.open(localRoot, profile);
+  const remote = await readRawProfile(remoteRoot, profile);
+  if (remote === undefined) return 0;
+
+  const written = new Set<string>();
+  for (const change of pulls) {
+    const array = keyedArrayFor(change.path);
+    const path = array ?? change.path;
+
+    // One write per array, however many of its elements were missing.
+    const key = path.join('.');
+    if (written.has(key)) continue;
+    written.add(key);
+
+    const value = valueAt(remote, path);
+    // Absent from the raw document means the remote side only has it as a
+    // default, which the local side fills in identically. Nothing to write.
+    if (value === undefined) continue;
+
+    document.setIn([...path], value);
+  }
+
+  await document.save();
+  return written.size;
+}
+
+/** Read a path out of the raw document, for handing to `setIn`. */
+function valueAt(config: unknown, path: readonly string[]): unknown {
+  let value: unknown = config;
+  for (const step of path) {
+    if (!(typeof value === 'object' && value !== null)) return undefined;
+    value = (value as Record<string, unknown>)[step];
+  }
+  return value;
+}
+
+/**
+ * Send the local profile up, once it holds everything both sides had.
+ *
+ * Wholesale rather than key by key, and only *after* the pulls have been
+ * applied: at that point the local file is the union, so copying it up makes
+ * the remote one the union too. The remote copy has no comments of its own to
+ * lose — `uploadWorkspace` wrote it — so there is nothing finer-grained to
+ * preserve, and one PUT cannot half-apply a merge.
+ */
+export async function applyPushes(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  changes: readonly Change[],
+): Promise<boolean> {
+  if (!changes.some((change) => change.direction === 'push')) return false;
+
+  const text = await readWorkspaceFile(workspaceFiles(localRoot), profileKey(profile));
+  if (text === null) return false;
+
+  await writeWorkspaceFile(workspaceFiles(remoteRoot), profileKey(profile), text);
+  return true;
+}
+
+/**
+ * The authored areas inside `data/` — skills and provider manifests.
+ *
+ * They ride the same allowlist a deploy uploads by, and for the reason that
+ * comment gives at length: the list is what keeps a credential store out of a
+ * bucket, and a second answer to "which files" is how the two drift. Compared
+ * by content, since they are documents rather than config, and differing
+ * content is a conflict like any other.
+ */
+export interface BlobSync {
+  readonly key: string;
+  readonly direction: 'pull' | 'push' | 'conflict';
+}
+
+export async function planBlobs(localRoot: string, remoteRoot: string): Promise<BlobSync[]> {
+  const read = async (root: string): Promise<Map<string, Uint8Array>> => {
+    const files = workspaceFiles(root);
+    const found = new Map<string, Uint8Array>();
+
+    for (const entry of await files.list('')) {
+      // `undefined` profile: every profile's authored areas, since sync is
+      // scoped to the target and not to one of them.
+      if (!isWorkspaceConfig(entry.key) || entry.key.endsWith('.yaml')) continue;
+      const bytes = await files.get(entry.key);
+      if (bytes !== null) found.set(entry.key, bytes);
+    }
+    return found;
+  };
+
+  const here = await read(localRoot);
+  const there = await read(remoteRoot);
+  const equal = (a: Uint8Array, b: Uint8Array): boolean =>
+    a.length === b.length && a.every((byte, index) => byte === b[index]);
+
+  return [...new Set([...here.keys(), ...there.keys()])].sort().flatMap((key): BlobSync[] => {
+    const local = here.get(key);
+    const remote = there.get(key);
+    if (local === undefined) return [{ key, direction: 'pull' }];
+    if (remote === undefined) return [{ key, direction: 'push' }];
+    return equal(local, remote) ? [] : [{ key, direction: 'conflict' }];
+  });
+}
+
+export async function applyBlobs(
+  localRoot: string,
+  remoteRoot: string,
+  blobs: readonly BlobSync[],
+): Promise<number> {
+  let copied = 0;
+
+  for (const blob of blobs) {
+    const from = blob.direction === 'pull' ? remoteRoot : localRoot;
+    const to = blob.direction === 'pull' ? localRoot : remoteRoot;
+
+    const bytes = await workspaceFiles(from).get(blob.key);
+    if (bytes === null) continue;
+
+    await workspaceFiles(to).put(blob.key, bytes, { contentType: 'application/octet-stream' });
+    copied += 1;
+  }
+
+  return copied;
+}

package/src/deployments/sync.ts

@@ -0,0 +1,136 @@
+import type { Config } from '#profile';
+
+/**
+ * What differs between a workspace and a target's copy of it.
+ *
+ * A deployed endpoint reads its config out of a bucket, and `deploy` puts it
+ * there — so from the moment of the first deploy there are two copies of every
+ * profile. They are supposed to agree. When they do not, one of them holds
+ * something the other has lost, and until now nothing could say which or bring
+ * it back.
+ *
+ * This file only *finds* the difference. Deciding it and writing it are
+ * `sync-apply.ts`, and choosing which bucket to compare against is the command.
+ * Split that way because the diff is the part worth testing exhaustively and
+ * the only part with no I/O in it.
+ */
+
+/** Which side is missing what, or that both have it and disagree. */
+export type Direction = 'pull' | 'push' | 'conflict';
+
+export interface Change {
+  /** Where in the config, e.g. `['targets', 'cloud']` or `['connections']`. */
+  readonly path: readonly string[];
+  readonly direction: Direction;
+  /** What remote holds. Absent when remote is the side that is missing it. */
+  readonly remote?: unknown;
+  /** What local holds. Absent when local is the side that is missing it. */
+  readonly local?: unknown;
+}
+
+/**
+ * Arrays whose elements are records rather than an ordered list.
+ *
+ * `connections` is a set of accounts keyed by `provider.id`; comparing it
+ * positionally would call a reordered file a conflict and, worse, would call an
+ * *added* connection a change to whichever one now sits at that index. The key
+ * function is what makes "personal gained a mailbox" a different fact from
+ * "personal's third connection changed".
+ *
+ * `identity` is deliberately absent. Its declaration order is meaningful — the
+ * first entry of a kind is the one to reach for — so it is an ordered list and
+ * compares as one.
+ */
+const KEYED: Record<string, (item: Record<string, unknown>) => string> = {
+  connections: (item) => `${String(item['provider'])}.${String(item['id'])}`,
+  'policy.allow': (item) => String(item['capability']),
+  'policy.deny': (item) => String(item['capability']),
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Every difference between one profile's two copies.
+ *
+ * Recursive over objects so a change reports at the narrowest path that
+ * describes it: two profiles differing only in `auth.authorization` produce
+ * that path, not `auth`, and applying it cannot take `token_ref` with it.
+ */
+export function diffConfigs(local: Config | undefined, remote: Config | undefined): Change[] {
+  if (local === undefined && remote === undefined) return [];
+
+  // A whole profile that only one side has. Reported at the root, because the
+  // unit that has to be copied is the file.
+  if (local === undefined) return [{ path: [], direction: 'pull', remote }];
+  if (remote === undefined) return [{ path: [], direction: 'push', local }];
+
+  return walk([], local as unknown, remote as unknown);
+}
+
+function walk(path: readonly string[], local: unknown, remote: unknown): Change[] {
+  if (same(local, remote)) return [];
+
+  if (local === undefined) return [{ path, direction: 'pull', remote }];
+  if (remote === undefined) return [{ path, direction: 'push', local }];
+
+  const key = path.join('.');
+  const keyOf = KEYED[key];
+  if (keyOf && Array.isArray(local) && Array.isArray(remote)) {
+    return walkKeyed(path, keyOf, local, remote);
+  }
+
+  if (isRecord(local) && isRecord(remote)) {
+    const keys = [...new Set([...Object.keys(local), ...Object.keys(remote)])].sort();
+    return keys.flatMap((name) => walk([...path, name], local[name], remote[name]));
+  }
+
+  // Two scalars, or two ordered arrays, that are not equal. There is no
+  // narrower path to report and no way to have both.
+  return [{ path, direction: 'conflict', local, remote }];
+}
+
+/**
+ * A keyed array, compared as the set of records it is.
+ *
+ * Each element reports under `path.key` — `connections.gmail.work` — so a
+ * missing account names itself in the output instead of appearing as an index.
+ * Applying still rewrites the whole array, because a YAML sequence has no
+ * addressable slot for "the element whose provider is gmail".
+ */
+function walkKeyed(
+  path: readonly string[],
+  keyOf: (item: Record<string, unknown>) => string,
+  local: readonly unknown[],
+  remote: readonly unknown[],
+): Change[] {
+  const index = (items: readonly unknown[]): Map<string, unknown> =>
+    new Map(items.filter(isRecord).map((item) => [keyOf(item), item]));
+
+  const here = index(local);
+  const there = index(remote);
+  const names = [...new Set([...here.keys(), ...there.keys()])].sort();
+
+  return names.flatMap((name) => walk([...path, name], here.get(name), there.get(name)));
+}
+
+/**
+ * The array a change belongs to, when it belongs to one.
+ *
+ * `['connections', 'gmail.work']` is applied by rewriting `connections`, so
+ * both the writer and the renderer need to know where the element stops and the
+ * key begins. Longest prefix first, so `policy.allow` wins over `policy`.
+ */
+export function keyedArrayFor(path: readonly string[]): readonly string[] | undefined {
+  for (let depth = path.length - 1; depth > 0; depth--) {
+    if (path.slice(0, depth).join('.') in KEYED) return path.slice(0, depth);
+  }
+  return undefined;
+}
+
+/** Whether a set of changes can be applied without being told which side wins. */
+export function conflictsIn(changes: readonly Change[]): Change[] {
+  return changes.filter((change) => change.direction === 'conflict');
+}

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';
 
 /**
@@ -63,17 +64,21 @@ export function deployedWorkspace(declared: TargetConfig): string | undefined {
  * prefix: `data/personal/skills.detour/` is not `skills.d`, and the difference
  * between matching it and not is a credential in a bucket.
  */
-export function isWorkspaceConfig(key: string, profile?: string | undefined): boolean {
+export function isWorkspaceConfig(key: string, profiles?: readonly string[]): boolean {
   if (key === WORKSPACE_FILE) return true;
 
-  // One profile when the deploy names one, so a workspace holding personal and
-  // work does not push both into a bucket only one of them is for. The same
-  // question for both shapes, asked once.
+  // A set rather than one name, because a deploy now sends every profile that
+  // declares the target rather than the single one it was told. `undefined`
+  // still means the whole workspace, and an *empty* set means nothing — which
+  // is a distinction a bare string could not make.
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
+
   const owner = authoredAreaOwner(key);
-  if (owner !== null) return profile === undefined || owner === profile;
+  if (owner !== null) return wanted === undefined || wanted.has(owner);
 
   if (!key.startsWith('profiles/') || !key.endsWith('.yaml')) return false;
-  return profile === undefined || key === `profiles/${profile}.yaml`;
+  const name = key.slice('profiles/'.length, -'.yaml'.length);
+  return wanted === undefined || wanted.has(name);
 }
 
 /**
@@ -119,10 +124,12 @@ function authoredAreaOwner(key: string): string | null {
  */
 export async function repairSetupSurface(
   workspaceRoot: string,
-  profile: string | undefined,
+  profiles: readonly string[] | undefined,
 ): Promise<void> {
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
+
   for (const name of await listProfiles(workspaceRoot)) {
-    if (profile !== undefined && name !== profile) continue;
+    if (wanted !== undefined && !wanted.has(name)) continue;
 
     try {
       const document = await ConfigDocument.open(workspaceRoot, name);
@@ -150,14 +157,14 @@ export async function repairSetupSurface(
 export async function uploadWorkspace(
   root: string,
   destination: string,
-  profile: string | undefined,
+  profiles: readonly string[] | undefined,
 ): Promise<void> {
   const local = workspaceFiles(root);
   const remote = workspaceFiles(destination);
 
   let copied = 0;
   for (const entry of await local.list('')) {
-    if (!isWorkspaceConfig(entry.key, profile)) continue;
+    if (!isWorkspaceConfig(entry.key, profiles)) continue;
 
     const bytes = await local.get(entry.key);
     if (bytes === null) continue;
@@ -202,6 +209,6 @@ export async function publishWorkspace(input: {
   const destination = deployedWorkspace(declared);
   if (!destination) return null;
 
-  await uploadWorkspace(input.workspaceRoot, destination, input.profile);
+  await uploadWorkspace(input.workspaceRoot, destination, [input.profile]);
   return destination;
 }

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/deployments.ts

@@ -0,0 +1,80 @@
+import { parseDocument } from 'yaml';
+import { readWorkspaceFile, workspaceFiles, writeWorkspaceFile } from './files.ts';
+import { workspaceSchema, type DeploymentRecord } from './schema.ts';
+import { WORKSPACE_FILE, readWorkspace } from './workspace.ts';
+
+/**
+ * The workspace's record of where its deployments live.
+ *
+ * A target is declared by a profile, and that declaration is what every command
+ * resolves from. This is the index beside it, and the distinction is the whole
+ * design: a profile file rewritten by hand or by a tool took a live Cloud Run
+ * service, its bucket, and its credential store out of reach in one edit,
+ * because the four lines naming them were the only copy. The service was still
+ * running. Nothing could find it.
+ *
+ * So the record is kept where the thing it describes is not: one level up, in
+ * `lanes-link.yaml`. `sync targets` reads it to know which bucket to open, and
+ * nothing else reads it at all — an index that starts being resolved from is a
+ * second source of truth, which is the failure ADR-037 spent a release
+ * removing (ADR-044).
+ */
+
+/** Every deployment the workspace has recorded. Empty for a workspace with none. */
+export async function readDeployments(workspaceRoot: string): Promise<DeploymentRecord[]> {
+  // A workspace file that will not parse is not a reason to fail a recovery:
+  // the caller has other ways to find a target, and this is the cheapest.
+  try {
+    return (await readWorkspace(workspaceRoot))?.deployments ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** What the workspace knows about one target, if anything. */
+export async function findDeployment(
+  workspaceRoot: string,
+  target: string,
+): Promise<DeploymentRecord | undefined> {
+  return (await readDeployments(workspaceRoot)).find((entry) => entry.target === target);
+}
+
+/**
+ * Record a deployment, replacing any earlier entry for the same target.
+ *
+ * Keyed by target rather than appended, because a target has one deployment by
+ * definition — a second entry would be a history, and a history is a thing to
+ * read wrong. Redeploying the same target to a new bucket should leave one
+ * record naming the new one.
+ *
+ * Merged into the existing entry so a field this caller does not know about —
+ * `primary`, on a redeploy that did not ask — is carried forward rather than
+ * dropped.
+ *
+ * Written through the YAML document API, so the comments in a workspace file an
+ * operator has annotated survive being indexed.
+ */
+export async function recordDeployment(
+  workspaceRoot: string,
+  entry: DeploymentRecord,
+): Promise<void> {
+  const files = workspaceFiles(workspaceRoot);
+  const text = (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? 'contract: 1\n';
+
+  const document = parseDocument(text);
+  const existing = await readDeployments(workspaceRoot);
+  const previous = existing.find((record) => record.target === entry.target);
+
+  const merged = [
+    ...existing.filter((record) => record.target !== entry.target),
+    { ...previous, ...entry },
+  ].sort((a, b) => a.target.localeCompare(b.target));
+
+  document.setIn(['deployments'], merged);
+
+  // 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());
+
+  await writeWorkspaceFile(files, WORKSPACE_FILE, String(document));
+}

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>;