@lanes-sh/link 0.3.1 → 0.4.0

package/src/connectivity/auth/strategy/index.ts

@@ -1,10 +1,134 @@
+import type { AuthStrategy, AuthStrategyContext } from '../../connector.ts';
+import type { ProviderContext } from '../../context.ts';
+import type { ProviderDefinition } from '../../provider.ts';
+import type { ProviderManifest } from '../../manifest/index.ts';
+
 /**
  * The escape hatch: auth no declarative form should try to express.
  *
- * bunq generates an RSA keypair, runs a three-step handshake, signs every
- * request, and verifies the response signature. That earns code. Nothing is
- * registered yet, so this fails loudly rather than sending an unauthenticated
- * request that would fail confusingly upstream.
+ * A strategy is the one place per-vendor code is permitted outside `local`
+ * providers, and it stays *auth* — a request in, an authorised request out.
+ * The moment one starts translating endpoints, the problem ADR-008 removed has
+ * come back.
+ *
+ * There is no global registry here, and that is deliberate. A strategy is not a
+ * plugin the runtime discovers; it is a property of the provider that needs it,
+ * so it travels on that provider's `ProviderDefinition` the same way an authored
+ * capability does. Two things follow, both of them the point:
+ *
+ *   - this component stays free of vendor names, which is the rule
+ *     `architecture.test.ts` holds over everything a request passes through
+ *   - adding one is still a folder under `providers/` and a line in its index,
+ *     rather than a folder here plus a registration somewhere else
+ */
+
+/**
+ * What `strategyFor` needs from the registry, and no more.
+ *
+ * Structural rather than the real `ProviderRegistry`, so this file states its
+ * dependency as two methods instead of importing a component to name a type.
+ */
+export interface StrategySource {
+  get(id: string): { readonly definition?: ProviderDefinition | undefined } | undefined;
+  list(): readonly { readonly definition?: ProviderDefinition | undefined }[];
+}
+
+/**
+ * The strategy a manifest declares.
+ *
+ * Its own definition first, which is the built-in case: `providers/bunq`
+ * carries the code for the manifest beside it, and the two must agree about
+ * which strategy that is. A manifest naming `strategy: acme` while its
+ * definition carries something else is a wiring mistake that would otherwise
+ * surface as a signature the vendor rejects — a long way from its cause.
+ *
+ * Then any other registered provider that supplies one by that name, which is
+ * the case a declaration-only manifest needs. A workspace YAML in
+ * `providers.d/` is parsed into a `ProviderManifest` and has no definition at
+ * all, so without this it could name a strategy and never reach it — and naming
+ * one is exactly what a manifest is for. It is also the only way to point a
+ * connection at a vendor's sandbox, since a built-in manifest's `options` are
+ * not the operator's to edit.
+ *
+ * Borrowing the *code* is not borrowing the *credential*: the ref still derives
+ * from the manifest's own id, so `bunq_sandbox` reads `bunq_sandbox/<id>` and
+ * cannot reach what `bunq` holds.
+ */
+export function strategyFor(
+  manifest: ProviderManifest,
+  source: StrategySource,
+): AuthStrategy {
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(`Provider "${manifest.id}" does not declare a strategy.`);
+  }
+
+  const named = manifest.auth.strategy;
+  const own = source.get(manifest.id)?.definition?.authStrategy;
+
+  if (own) {
+    if (own.id !== named) {
+      throw new Error(
+        `Provider "${manifest.id}" declares auth strategy "${named}" but carries "${own.id}".`,
+      );
+    }
+    return own;
+  }
+
+  const borrowed = source
+    .list()
+    .map((entry) => entry.definition?.authStrategy)
+    .find((strategy) => strategy?.id === named);
+
+  if (!borrowed) refuseStrategy(named);
+  return borrowed;
+}
+
+/**
+ * What a strategy is given, derived from what the provider is given.
+ *
+ * Narrower than a `ProviderContext` on purpose: the connection's own
+ * credentials read-only, its own scoped state, and its logger. Nothing else,
+ * and in particular no storage, no audit logger, and no signal — a strategy
+ * authenticates a request and has no business doing anything a provider does.
+ *
+ * `write` is the one part that varies, and the variation *is* the rule.
+ * Persisting a credential is a setup-time act, so `connect` passes a writer and
+ * the dispatch path does not. Per-request code then cannot store a credential
+ * because there is nothing on the object to store one with, rather than because
+ * somebody remembered not to.
+ *
+ * Takes the three fields it reads rather than a whole `ProviderContext`, so the
+ * two callers can be what they are: dispatch hands over the context it already
+ * built, and `connect` — which has no provider context, because the connection
+ * does not exist yet — assembles the same three from the runtime.
+ */
+export function strategyContextFrom(input: {
+  /** Dispatch hands over the `ProviderContext` it built; `connect` assembles the three itself. */
+  readonly source: Pick<ProviderContext, 'credentials' | 'state' | 'log'>;
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly profile: string;
+  readonly write?: ((ref: string, value: string) => Promise<void>) | undefined;
+}): AuthStrategyContext {
+  const { source, manifest, connectionId, profile, write } = input;
+
+  return {
+    manifest,
+    connectionId,
+    profile,
+    credentials: source.credentials,
+    state: source.state,
+    log: source.log,
+    options: manifest.auth.kind === 'strategy' ? (manifest.auth.options ?? {}) : {},
+    ...(write ? { write } : {}),
+  };
+}
+
+/**
+ * A manifest asked for a strategy nothing supplies.
+ *
+ * Fails loudly rather than sending an unauthenticated request, which would fail
+ * upstream with an error about the vendor rather than about the wiring.
  */
 export function refuseStrategy(strategy: string): never {
   throw new Error(

package/src/connectivity/connector.ts

@@ -159,6 +159,17 @@ export interface AuthStrategy {
 export interface AuthStrategyContext {
   readonly manifest: ProviderManifest;
   readonly connectionId: string;
+  /**
+   * Which profile this is acting for.
+   *
+   * Nothing about authenticating one request needs it. What needs it is any
+   * strategy that keeps something in process memory: one endpoint serves every
+   * profile in the workspace from one process, so `<provider>.<connection>` is
+   * not a unique key — two profiles each holding a bunq connection called
+   * `main` would share whatever it named. `state` and `credentials` are already
+   * scoped per profile and a cache in front of them must be too.
+   */
+  readonly profile: string;
   /** Read-only, scoped to this connection — the same boundary providers get. */
   readonly credentials: ProviderContext['credentials'];
   /**

package/src/connectivity/index.ts

@@ -48,7 +48,17 @@ export {
  * Everything else is a manifest.
  */
 export type { AuthRequirement, ProviderDefinition } from './provider.ts';
-export { defineLocalProvider, defineProviderWithCapabilities } from './provider.ts';
+export {
+  defineLocalProvider,
+  defineProviderWithCapabilities,
+  defineProviderWithStrategy,
+} from './provider.ts';
+
+/**
+ * The strategy seam. Vendor-free by construction: these three know that a
+ * strategy exists and never which one.
+ */
+export { refuseStrategy, strategyContextFrom, strategyFor } from './auth/strategy/index.ts';
 
 export type {
   ProviderManifest,

package/src/connectivity/manifest/auth.ts

@@ -164,6 +164,25 @@ export const authOAuthSchema = z.object({
    */
   authorize_url: z.url().optional(),
   token_url: z.url().optional(),
+  /**
+   * A loopback redirect to name to the vendor verbatim, for one that matches it
+   * exactly rather than by prefix.
+   *
+   * `connect` normally listens on a port the kernel picks, which works because
+   * most authorization servers accept any loopback port. One that pins the
+   * whole URL cannot: the port it was told in a console months ago is not the
+   * port this run happens to get, and the grant is refused with
+   * `redirect_uri_mismatch`.
+   *
+   * The full URL rather than a port, because the vendor's console decides the
+   * spelling — `localhost` and `127.0.0.1` are different strings to a matcher
+   * even when they are the same host — and the two must be identical.
+   *
+   * Mutually exclusive with `broker`, which answers the same question the other
+   * way: there the redirect is the broker's HTTPS origin and the loopback port
+   * travels in `state`.
+   */
+  redirect_uri: z.url().optional(),
   /**
    * Extra parameters on the authorization request.
    *

package/src/connectivity/manifest/connector.ts

@@ -56,6 +56,27 @@ export const httpConnectorSchema = z.object({
       exclude: z.array(z.string()).default([]),
     })
     .optional(),
+  /**
+   * Sent on every request this connector makes.
+   *
+   * The same field as `mcp`'s above and refused the same way for
+   * `Authorization` — but for the opposite reason. An mcp server chooses its
+   * own tool list and a header is the only way to ask it for less; a REST API
+   * asks for nothing, and this is for what the *vendor* requires of a client
+   * rather than what a caller wants from it.
+   *
+   * The case in hand is a `User-Agent`. Nothing else here sets one, so every
+   * install of this program looks identical to a host that rate-limits by
+   * client — and a service that asks callers to identify themselves throttles
+   * the default agent hardest, which reads as an outage rather than a refusal.
+   *
+   * Precedence is narrowest-wins: `accept` is a default this may override, a
+   * header parameter the operation itself declares overrides this, and
+   * `content-type` is derived from the document and overrides everything —
+   * a blanket header cannot silently change how one operation's body is
+   * encoded.
+   */
+  headers: z.record(z.string(), z.string()).optional(),
 });
 
 /**

package/src/connectivity/manifest/primitives.ts

@@ -16,5 +16,9 @@ export const credentialRef = z
   .string()
   .regex(
     /^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)+$/,
-    'must be a credential reference like "bunq/api_key", not a literal value',
+    // A placeholder rather than a real provider id. The example teaches the
+    // shape either way, and this file is inside the scope
+    // `architecture.test.ts` keeps free of vendor names — an error message that
+    // names one is exactly the "message that assumes a vendor" the rule is for.
+    'must be a credential reference like "acme/api_key", not a literal value',
   );

package/src/connectivity/manifest/provider.ts

@@ -225,6 +225,36 @@ export function defineProvider(input: unknown): ProviderManifest {
     );
   }
 
+  // Two answers to "where does the browser come back to", and a manifest
+  // naming both leaves it to whichever the flow reads first. A broker's
+  // redirect is its own HTTPS origin, with the loopback port carried in
+  // `state`; a fixed redirect is this machine, named exactly. Neither is wrong,
+  // but they cannot both be in force.
+  if (manifest.auth.kind === 'oauth' && manifest.auth.broker && manifest.auth.redirect_uri) {
+    throw new Error(
+      `Provider "${manifest.id}": auth may declare "broker" or "redirect_uri", not both — a brokered flow redirects to the broker and carries the loopback port in state, so a fixed redirect would never be used.`,
+    );
+  }
+
+  // Connector headers are for what the *server* offers as configuration; the
+  // credential is the auth block's, and a manifest setting both would have one
+  // quietly overwrite the other depending on which the transport merged last.
+  //
+  // Checked for every connector that has the field rather than for `mcp` alone.
+  // It was written when `mcp` was the only one, and the reasoning never had
+  // anything to do with which transport carried the header — an `http`
+  // connector naming `Authorization` collides with `auth` in exactly the same
+  // way, and would have validated cleanly.
+  const connectorHeaders =
+    'headers' in manifest.connector ? (manifest.connector.headers ?? {}) : {};
+  for (const name of Object.keys(connectorHeaders)) {
+    if (name.toLowerCase() === 'authorization') {
+      throw new Error(
+        `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
+      );
+    }
+  }
+
   if (manifest.connector.kind === 'mcp') {
     const auth = manifest.auth;
 
@@ -250,18 +280,6 @@ export function defineProvider(input: unknown): ProviderManifest {
         `Provider "${manifest.id}": an mcp connector always sends its token as "Authorization: Bearer", so auth.header ("${auth.header}") cannot be honoured. Remove it, or reach this service with an http connector.`,
       );
     }
-
-    // The third spelling of the same collision. Connector headers are for what
-    // the *server* offers as configuration; the credential is the auth block's,
-    // and a manifest setting both would have one quietly overwrite the other
-    // depending on which the transport merged last.
-    for (const name of Object.keys(manifest.connector.headers ?? {})) {
-      if (name.toLowerCase() === 'authorization') {
-        throw new Error(
-          `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
-        );
-      }
-    }
   }
 
   const names = new Set<string>();

package/src/connectivity/provider.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { SecretRef } from '#secrets';
 import type { Capability } from './capability.ts';
+import type { AuthStrategy } from './connector.ts';
 import type { ProviderContext } from './context.ts';
 import { bundleSchema, defineProvider, type ProviderManifest } from './manifest/index.ts';
 
@@ -32,6 +33,16 @@ export interface ProviderDefinition<
 
   readonly capabilities: readonly Capability[];
 
+  /**
+   * Pluggable auth, for a vendor whose handshake no manifest field can describe.
+   *
+   * Carried here rather than in a registry the runtime searches, because a
+   * strategy belongs to exactly one provider and nothing else may use it. The
+   * manifest declares *that* there is one and names it; this is the code, and
+   * `strategyFor` checks the two agree.
+   */
+  readonly authStrategy?: AuthStrategy;
+
   /**
    * Which credential refs a connection may read. Core turns this into the
    * allowlist behind `ProviderContext.credentials`, so a provider cannot reach
@@ -161,3 +172,47 @@ export function defineProviderWithCapabilities(input: {
     capabilities: input.capabilities,
   };
 }
+
+/**
+ * A manifest-based provider whose authentication is code rather than a field.
+ *
+ * The sibling of `defineProviderWithCapabilities`, and rarer. That one exists
+ * where a vendor's API can do something its *document* cannot express; this one
+ * where a vendor's **handshake** can. Everything else about the provider stays
+ * declared — the connector kind, the operations, the redaction — and the
+ * strategy only ever sees a request on its way out and a response on its way
+ * back.
+ *
+ * ADR-008 puts a number on how much this is allowed to be: roughly 150 lines,
+ * for auth, once. A strategy that grows a second job is the 612-line problem
+ * returning by a different door.
+ */
+export function defineProviderWithStrategy(input: {
+  readonly manifest: ProviderManifest;
+  readonly strategy: AuthStrategy;
+  readonly capabilities?: readonly Capability[];
+}): ProviderDefinition {
+  const { manifest, strategy } = input;
+
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(
+      `Provider "${manifest.id}" carries an auth strategy but declares auth.kind "${manifest.auth.kind}". Declare { kind: 'strategy', strategy: '${strategy.id}' }.`,
+    );
+  }
+
+  if (manifest.auth.strategy !== strategy.id) {
+    throw new Error(
+      `Provider "${manifest.id}" declares auth strategy "${manifest.auth.strategy}" but carries "${strategy.id}".`,
+    );
+  }
+
+  return {
+    manifest,
+    // Permissive for the same reason `defineProviderWithCapabilities` is: a
+    // manifest provider's connection is already described by its manifest.
+    configSchema: z.unknown(),
+    connectionSchema: z.unknown(),
+    capabilities: input.capabilities ?? [],
+    authStrategy: strategy,
+  };
+}

package/src/connectivity/transports/factory.ts

@@ -180,6 +180,7 @@ function build(
         ...(manifest.connector.operations?.exclude?.length
           ? { exclude: manifest.connector.operations.exclude }
           : {}),
+        ...(manifest.connector.headers ? { headers: manifest.connector.headers } : {}),
       });
   }
 }

package/src/connectivity/transports/http/index.ts

@@ -26,9 +26,70 @@ export interface HttpConnectorOptions {
   readonly openapi: string;
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
+  /** Sent on every request. Never `Authorization` — the manifest refuses it. */
+  readonly headers?: Readonly<Record<string, string>>;
   readonly fetch?: typeof globalThis.fetch;
 }
 
+/**
+ * The one body encoding that is not JSON often enough to be worth knowing about.
+ *
+ * A form-encoded write is not a legacy curiosity: it is what a large share of
+ * APIs that predate JSON request bodies still require, and one of them refusing
+ * `application/json` is not a negotiation — the request fails outright, with an
+ * error about the parameters rather than about the encoding.
+ */
+const FORM_ENCODED = 'application/x-www-form-urlencoded';
+
+/**
+ * What the *document* says the body is, rather than what we would prefer.
+ *
+ * `mcp-from-openapi` records the declared media type on each body entry of the
+ * mapper, so this needs nothing threaded through `target` — the mapper is
+ * already cached there, which is what lets a cold instance encode correctly
+ * without re-reading the spec.
+ *
+ * JSON is the default because an operation with no declared request body has no
+ * media type to read, and because it is what this connector always sent.
+ */
+function bodyContentType(mapper: readonly ParameterMapper[]): string {
+  for (const entry of mapper) {
+    if (entry.type !== 'body') continue;
+    const declared = entry.serialization?.contentType;
+    if (declared) return declared;
+  }
+
+  return 'application/json';
+}
+
+/**
+ * Arrays repeat rather than join, for the reason the query string does above.
+ *
+ * A nested object is JSON inside the field, which is the only thing a
+ * form-encoded body can do with one — there is no standard spelling of nesting
+ * here, and every API that accepts one accepts it as a string.
+ */
+function encodeBody(body: Readonly<Record<string, unknown>>, contentType: string): string {
+  if (!contentType.startsWith(FORM_ENCODED)) return JSON.stringify(body);
+
+  const form = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      for (const element of value) {
+        if (element !== undefined && element !== null) form.append(key, String(element));
+      }
+      continue;
+    }
+
+    form.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+
+  return form.toString();
+}
+
 /**
  * `*` matches any run of characters; anything else is literal.
  *
@@ -148,6 +209,12 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
 
       const url = new URL(options.baseUrl.replace(/\/$/, '') + buildPath(template, args, mapper));
       const headers = new Headers({ accept: 'application/json' });
+
+      // After `accept`, which is a default worth overriding, and before the
+      // operation's own header parameters, which are narrower than a header
+      // declared once for the whole connector.
+      for (const [key, value] of Object.entries(options.headers ?? {})) headers.set(key, value);
+
       const body = collect(args, mapper, 'body');
 
       for (const [key, value] of Object.entries(collect(args, mapper, 'query'))) {
@@ -174,7 +241,11 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
       }
 
       const hasBody = Object.keys(body).length > 0;
-      if (hasBody) headers.set('content-type', 'application/json');
+      const contentType = bodyContentType(mapper);
+      // Last, so it beats a connector-wide header. Which encoding an operation
+      // uses is the document's to state, and a blanket `content-type` that
+      // silently changed it would be a bug nobody could see from the manifest.
+      if (hasBody) headers.set('content-type', contentType);
 
       // Auth is attached by core, from the manifest's auth kind or its strategy.
       // A connector never sees a raw credential.
@@ -182,7 +253,7 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
         new Request(url.href, {
           method,
           headers,
-          ...(hasBody ? { body: JSON.stringify(body) } : {}),
+          ...(hasBody ? { body: encodeBody(body, contentType) } : {}),
           signal: context.provider.signal,
         }),
       );

package/src/deployments/sync-apply.ts

@@ -8,7 +8,7 @@ import {
   type Config,
 } from '#profile';
 import { ConfigDocument } from '#cli/config-edit.ts';
-import { diffConfigs, keyedArrayFor, type Change } from './sync.ts';
+import { diffConfigs, keyOfElement, keyedArrayFor, type Change } from './sync.ts';
 import { isWorkspaceConfig } from './upload.ts';
 
 /**
@@ -155,28 +155,82 @@ export async function applyPulls(
   const remote = await readRawProfile(remoteRoot, profile);
   if (remote === undefined) return 0;
 
+  const local = document.toJSON();
   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);
+    if (array) {
+      // One write per array, however many of its elements were missing — and
+      // the value written is the *merge*, never the remote array.
+      //
+      // It used to be `setIn(array, remoteArray)`, which reads as "pull the
+      // connections" and means "replace the connections". A profile that had
+      // gained six accounts locally since the last deploy lost all six to a
+      // command whose entire purpose is not losing things. The tests missed it
+      // because every one of them had a local array that was a subset of the
+      // remote — the case where replacing and merging agree.
+      const key = array.join('.');
+      if (written.has(key)) continue;
+      written.add(key);
+
+      const merged = mergeKeyed(
+        array,
+        valueAt(local, array),
+        valueAt(remote, array),
+        pulls
+          .filter((one) => keyedArrayFor(one.path)?.join('.') === key)
+          .map((one) => one.path[array.length])
+          .filter((name): name is string => name !== undefined),
+      );
+      if (merged !== undefined) document.setIn([...array], merged);
+      continue;
+    }
 
-    const value = valueAt(remote, path);
+    const value = valueAt(remote, change.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);
+    document.setIn([...change.path], value);
   }
 
   await document.save();
   return written.size;
 }
 
+/**
+ * The local array, with the named elements taken from the remote one.
+ *
+ * Element order is local's, with anything new appended, so a pull reads as a
+ * diff in the file rather than as a reshuffle. An element named in `wanted` and
+ * absent from the remote array is skipped rather than removed: the diff said it
+ * was missing locally, so it cannot also be missing remotely.
+ */
+function mergeKeyed(
+  arrayPath: readonly string[],
+  local: unknown,
+  remote: unknown,
+  wanted: readonly string[],
+): unknown[] | undefined {
+  if (!Array.isArray(remote)) return undefined;
+
+  const merged = Array.isArray(local) ? [...(local as unknown[])] : [];
+  const keyOf = (item: unknown): string | undefined => keyOfElement(arrayPath, item);
+
+  for (const name of new Set(wanted)) {
+    const incoming = remote.find((item) => keyOf(item) === name);
+    if (incoming === undefined) continue;
+
+    const at = merged.findIndex((item) => keyOf(item) === name);
+    if (at >= 0) merged[at] = incoming;
+    else merged.push(incoming);
+  }
+
+  return merged;
+}
+
 /** Read a path out of the raw document, for handing to `setIn`. */
 function valueAt(config: unknown, path: readonly string[]): unknown {
   let value: unknown = config;

package/src/deployments/sync.ts

@@ -41,12 +41,23 @@ export interface Change {
  * 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 KEYED: Record<string, (item: unknown) => string | undefined> = {
+  connections: (item) =>
+    isRecord(item) ? `${String(item['provider'])}.${String(item['id'])}` : undefined,
+  // Two shapes, and both are reached. The diff runs over validated configs,
+  // where `allow: [gmail.*]` has become `[{capability: gmail.*}]`; the writer
+  // runs over the raw document, where it is still a string. A key function that
+  // knew only the validated shape found nothing to merge and silently wrote the
+  // array without it.
+  'policy.allow': capabilityOf,
+  'policy.deny': capabilityOf,
 };
 
+function capabilityOf(item: unknown): string | undefined {
+  if (typeof item === 'string') return item;
+  return isRecord(item) ? String(item['capability']) : undefined;
+}
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
@@ -102,12 +113,16 @@ function walk(path: readonly string[], local: unknown, remote: unknown): Change[
  */
 function walkKeyed(
   path: readonly string[],
-  keyOf: (item: Record<string, unknown>) => string,
+  keyOf: (item: unknown) => string | undefined,
   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]));
+    new Map(
+      items
+        .map((item) => [keyOf(item), item] as const)
+        .filter((pair): pair is readonly [string, unknown] => pair[0] !== undefined),
+    );
 
   const here = index(local);
   const there = index(remote);
@@ -130,6 +145,19 @@ export function keyedArrayFor(path: readonly string[]): readonly string[] | unde
   return undefined;
 }
 
+/**
+ * How an element of a keyed array identifies itself, for the writer.
+ *
+ * The diff indexes these to compare them; applying one has to find the same
+ * element again in *both* raw documents, and it cannot re-derive the key from
+ * the path — `connections.gmail.work` is one key containing a dot, not two
+ * steps. Exported so the two halves cannot disagree about what identifies a
+ * connection.
+ */
+export function keyOfElement(arrayPath: readonly string[], item: unknown): string | undefined {
+  return KEYED[arrayPath.join('.')]?.(item);
+}
+
 /** 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');