@open-everywhere/core 0.1.0

package/agent/identity/link-flow.ts

@@ -0,0 +1,380 @@
+// The pure decision core of account linking: the initiator asks, the target consents in their own conversation, then the initiator finalizes. Whether a finalize needs a code-back is read off the challenge row, never off the setting at finalize time.
+// The two transports differ only in how act 2 identifies the target. The CODE transport forces a code-back because code-1 is a bearer token and the initiator's ratification arrives exactly when they expect one, so an intercepted code plus a reflexive yes would link an attacker's account; code-2 removes that reflex by making the initiator read the consent on the other account's own surface. The DIRECTORY transport addresses both ends itself, so its code-back is an off-by-default knob.
+
+import { hashLinkCode } from "./link-challenge.js";
+
+/** How act 2 identifies the target. See the module header. */
+export type LinkTransport = "directory" | "code";
+
+/** Every transport this deployment implements — the runtime guard for a value read back off a row
+ *  (a store is a string column; a row written by a later version must not silently read as
+ *  "directory" and skip the forced code-back). */
+export function asLinkTransport(raw: string | undefined): LinkTransport {
+  return raw === "directory" ? "directory" : "code";
+}
+
+/** Decided once, at consent time; the answer is materialised on the row and every later decision reads the row. A code-back that the transport requires but this surface cannot deliver degrades to the acknowledged ratification with an audit row, rather than refusing the claim. */
+export type CodeBackDecision = { readonly mint: true } | { readonly mint: false; readonly reason: "not-required" | "undeliverable" };
+
+export function codeBackDecision(input: { readonly transport: LinkTransport; readonly knobArmed: boolean; readonly deliverable: boolean }): CodeBackDecision {
+  const required = input.transport === "code" || input.knobArmed;
+  if (!required) return { mint: false, reason: "not-required" };
+  return input.deliverable ? { mint: true } : { mint: false, reason: "undeliverable" };
+}
+
+/**
+ * What a finalize call may do. `peek` writes NOTHING and names the consent; `commit` ratifies;
+ * `refuse` is a sentence the caller throws.
+ */
+export type FinalizeVerdict = { readonly kind: "peek" } | { readonly kind: "commit" } | { readonly kind: "refuse"; readonly reason: string };
+
+/**
+ * THE FINALIZE GATE — the one decision standing between a recorded consent and a written link.
+ *
+ * Three properties, and what each one is actually worth:
+ *
+ *  1. THE PEEK (OPE-618). A call that carries neither `acknowledge` nor `code` PEEKS: the caller gets
+ *     the consenting account named back and nothing is written. A call that DOES carry one must also
+ *     name the challenge it acts on (`challengeId`), and the refusal deliberately does not echo an id.
+ *     ⚠️ THIS IS NOT A BARRIER AGAINST A DISOBEDIENT MODEL, and must not be described as one:
+ *     `link_identity` returns the `challengeId` at act 1, so a model that kept it can pass
+ *     `acknowledge: true` on its first `confirm_link` call and commit an account it never showed
+ *     anybody — wherever no code-back digest is on the row. What the peek buys is stated once, in
+ *     tools/confirm_link.ts's own header: it repairs BLINDNESS, so the sentence the model puts in
+ *     front of the person names a real account off the row instead of a question. Property 2 is the
+ *     only one here that a model cannot answer out of its own context.
+ *  2. FORCED CODE-BACK. When the row carries a `backNonceHash`, `acknowledge: true` alone is REFUSED.
+ *     The only thing that commits is the code itself, compared by hash — a knowledge proof cannot be
+ *     answered by a reflex, and cannot be answered from context either.
+ *  3. NO CODE WHERE NONE WAS ISSUED. A `code` on a row with no `backNonceHash` is refused rather than
+ *     ignored. Ignoring it would let a person believe a second factor was checked when nothing was.
+ *
+ * PURE: the hash comparison is `hashLinkCode` over the supplied text, so the raw code-2 never has to
+ * be at rest for this to be decidable.
+ *
+ * 🔴 A BLANK `code` IS NO CODE, AND THAT IS A PEEK, NOT A REFUSAL. An empty or whitespace-only string
+ * normalises to absent, so a caller that fills every optional field with a placeholder lands on the
+ * peek rather than on a sentence telling it what went wrong. That is the RIGHT verdict — a peek
+ * writes nothing and is repeatable — but it means the PEEK'S OWN ANSWER is the only thing that can
+ * get such a caller moving again. On deploy #212 it could not: the answer said to go and ask the
+ * person for a code the person had already given, and the link was never written (OPE-1858). The
+ * answer now tells the caller to finish in the same turn; tools/confirm_link.ts owns that text.
+ */
+export function finalizeGate(input: {
+  /** The row's own code-back hash, or undefined when the consent step minted none. */
+  readonly backNonceHash: string | undefined;
+  readonly acknowledge?: boolean;
+  readonly code?: string;
+  readonly challengeId?: string;
+}): FinalizeVerdict {
+  const code = typeof input.code === "string" && input.code.trim().length > 0 ? input.code.trim() : undefined;
+  const acknowledged = input.acknowledge === true;
+  if (!acknowledged && code === undefined) return { kind: "peek" };
+  if (input.challengeId === undefined) {
+    return {
+      kind: "refuse",
+      reason:
+        "a finalizing confirm must pass back the challengeId of the consent it acts on — call confirm_link with neither `acknowledge` nor `code` first: it names the waiting account and returns the challengeId.",
+    };
+  }
+  if (input.backNonceHash !== undefined) {
+    if (code === undefined) {
+      // 🔴 THE SAME "FINISH IT NOW" SENTENCE THE PEEK CARRIES (OPE-1858), and this branch needs it
+      // MORE, not less: `confirm_link`'s own description prescribes `acknowledge: true` + challengeId
+      // as the second call, so a caller that follows the description on a code-back row lands exactly
+      // here. Telling it only to "ask the person for that code" sends a caller that is already
+      // holding the code away for a second copy — the deploy #212 outcome, one branch over.
+      return {
+        kind: "refuse",
+        reason:
+          "this link needs the code I posted back to the other account — `acknowledge` alone does not finalize it. " +
+          "If you ALREADY have that code, call again NOW with it and this challengeId: both calls belong in one turn, " +
+          "and the person often gives you the code in the very message you are answering. Ask them to read it off the " +
+          "other account only when you do not have it.",
+      };
+    }
+    if (hashLinkCode(code) !== input.backNonceHash) {
+      return { kind: "refuse", reason: "that code does not match the one I posted to the other account. Ask for it again — it is single-use and expires with the request." };
+    }
+    return { kind: "commit" };
+  }
+  if (code !== undefined) {
+    return { kind: "refuse", reason: "no second code was issued for this request — finalize it with `acknowledge: true` once the person has confirmed the account is theirs." };
+  }
+  return { kind: "commit" };
+}
+
+/**
+ * THE CONSENT GATE — act 2's twin of {@link finalizeGate}, for the account being ASKED.
+ *
+ * The same no-blind-answer property, aimed the other way: a consent call that carries no
+ * `acknowledge` PEEKS and is answered with the INITIATOR named, and a call that does acknowledge must
+ * name the request it answers. The person on this side is being asked about a STRANGER — that is the
+ * whole security value of the reverse flow (an unexpected DM naming someone you do not know is an
+ * easy human judgement), and it is worth nothing if the model can say yes before the name is in front
+ * of it.
+ *
+ * Separate from `finalizeGate` rather than a call into it with an absent hash, because the two steps
+ * refuse for different reasons and a person reads the sentence: this side has no code to be missing,
+ * and telling them one is would be wrong.
+ */
+export function consentGate(input: { readonly acknowledge?: boolean; readonly challengeId?: string; readonly code?: string }): FinalizeVerdict {
+  // A code on THIS side is refused rather than ignored, for the same reason `finalizeGate` refuses
+  // one where none was issued: the code-back travels initiator-ward, and silently dropping one here
+  // would let a person believe a factor was checked when nothing was.
+  if (typeof input.code === "string" && input.code.trim().length > 0) {
+    return { kind: "refuse", reason: "there is no code to give me here — a second code, if this link needs one, goes to the person who asked. Confirm with `acknowledge: true` and the challengeId." };
+  }
+  if (input.acknowledge !== true) return { kind: "peek" };
+  if (input.challengeId === undefined) {
+    return {
+      kind: "refuse",
+      reason:
+        "a consent must pass back the challengeId of the request it answers — call confirm_link without `acknowledge` first: it names the person who asked and returns the challengeId.",
+    };
+  }
+  return { kind: "commit" };
+}
+
+/**
+ * The claim VENUE rule (Tommy, 2026-08-16): on a platform this deployment can DM, a `link <code>`
+ * claim is DM-ONLY, and a claim addressed to the agent in a channel or a group DM is REFUSED with a
+ * pointer to the DM.
+ *
+ * WHY. Code-1 is a bearer token for the length of its TTL. Posting it in a room publishes it to
+ * everybody in that room, and the reverse-initiated design exists precisely to stop a bearer secret
+ * from ever being public. Where the agent can be DM'd, no code ever needs to leave a 1:1
+ * conversation — so it must not.
+ *
+ * SCOPED TO DM-CAPABLE PLATFORMS, and that scoping is the whole design. On every platform with NO DM
+ * arm (channels/post-arms.ts `deliverDirectMessage`) a room is the only place a claim can be made at
+ * all, so refusing there would delete the cross-platform claim the code transport exists for.
+ *
+ * 🔴 STATE THE PROPERTY, NEVER A PLATFORM LIST. `dmCapable` comes from the arm registry on every
+ * call, so a platform that gains an arm starts refusing room claims the same day, with no edit here,
+ * and a platform that has none keeps its room claim. A list written into this comment would be stale
+ * the moment a bundle ships an arm, and would teach the next reader the opposite of what the code
+ * does — it already did once, when it named Slack as the only DM-capable surface and OPE-623 added a
+ * second.
+ *
+ * A GROUP DM (`mpim`) is refused with the channel copy: it has an audience, which is the property
+ * that matters, and `link_identity` refuses to START there for the same reason.
+ *
+ * Returns the refusal a person reads, or `undefined` when the venue is fine.
+ */
+export function claimVenueRefusal(input: { readonly dmCapable: boolean; readonly mode: string | undefined }): string | undefined {
+  if (!input.dmCapable) return undefined;
+  if (input.mode === "dm") return undefined;
+  return (
+    "I can't take a link code here — a code is a secret for as long as it lasts, and this conversation has " +
+    "an audience. DM me and send it there instead. The code is still good; nothing was used up."
+  );
+}
+
+/**
+ * The claim ADDRESSING rule (Tommy, 2026-09-13): a `link <code>` line only claims when the person
+ * ADDRESSED the agent. An unaddressed line sitting in a room claims nothing, and the code is not
+ * spent.
+ *
+ * WHY. A link binds one human to a second account, so the claim is the evidence that a person MEANT
+ * to bind it. An ambient line in a busy room is not that: the agent is watching the room anyway, so
+ * anyone who can type there could land a claim on whichever wake happened to carry their line. The
+ * minted instruction (identity/link-challenge.ts `linkClaimInstructions`) has always promised this
+ * — "a bare, unaddressed line will not count" — and the code now keeps the promise.
+ *
+ * 🔴 ADDRESSING IS THE SURFACE'S OWN, AND THE SURFACE DECIDES IT, NOT THIS MODULE. The caller passes
+ * the AUTHORITATIVE host-set verdict (identity/binding.ts `currentTurnAddressed`). Which sites stamp
+ * it, exactly:
+ *   • every DM divert, UNCONDITIONALLY — Slack, Discord and Teams stamp `oe_addressing` on each 1:1
+ *     delivery, with no capability gate;
+ *   • each provider's NATIVE comment leg, on its own mention verdict — Notion's name-drop
+ *     (notion-webhook.ts), GitHub's `isMention` (github.ts) and Linear's agent session (linear.ts);
+ *   • the single-window mention policy, where `window.topology` is armed AND the surface is
+ *     operator-vouched (channels/unified-window.ts `singleWindowMentionPolicy`).
+ * 🔴 THE NATIVE LEG IS THE ONE THAT MATTERS FOR THE SHIPPED DEFAULT: `window.topology` is
+ * `shipped: false`, so a stock deployment never reaches the single-window stamp. A surface whose
+ * native leg does not stamp has NO claim path at all — which is why adding a surface means adding its
+ * stamp, not a special case here.
+ *
+ * Notion is the reason the rule reads "the surface's own form" rather than "an @mention": Notion lets
+ * no user @mention an integration at all, so its classifier promotes a NAME-DROP to `direct`. A
+ * surface with no mentions and no DMs therefore keeps its claim path, and every surface is held to the
+ * same rule. There is exactly ONE addressing notion in this tree, and this is a reader of it — never a
+ * second one.
+ *
+ * Returns the refusal a person reads, or `undefined` when the wake was addressed.
+ */
+export function claimAddressingRefusal(input: { readonly addressed: boolean }): string | undefined {
+  if (input.addressed) return undefined;
+  return (
+    "I can't take a link code from a line that isn't addressed to me — anybody can type in here, so a " +
+    "bare line is not evidence you meant it for me. Send the same line again, addressed to me: " +
+    "@mention me, or name-drop me where I have no @mention. The code is still good; nothing was used up."
+  );
+}
+
+/**
+ * ONE LIVE CODE PER PROOF-OF-CONTROL LOOP (Tommy, 2026-09-19): a turn that has just ANSWERED a link
+ * request refuses to start a fresh one.
+ *
+ * WHY. An answer is the middle of a loop, not the end of one. The account that answered still owes
+ * the initiator a step — the code-back, or a confirmation on the initiator's own side. A
+ * `link_identity` start in that same conversation mints a SECOND live code and tells the person to
+ * send it from their other account, so one DM then carries two codes and two contradictory
+ * instructions, and the person has no way to tell which one the agent is waiting on. Measured on the
+ * ship #223 board (2026-09-19, S-LINK-SLACK): the claimant's seat claimed at 15:52:02, started again
+ * at 15:52:04, and told the same account nine seconds later that "the link code hasn't been claimed
+ * yet".
+ *
+ * 🔴 TWO DOORS REACH THIS SENTENCE, AND THEY ARE DIFFERENT ACTS. The CODE transport's answer is a
+ * CLAIM (the person posted `link <code>`); the DIRECTORY transport's answer is a CONSENT (the person
+ * was asked and agreed). Both land in the same `claimed_*` triple — `consentLinkChallenge` writes it
+ * too, see the store contract — so `transport` is what keeps the copy honest. A consenter told "the
+ * one you just claimed" is being named for an act they never performed, and the whole product value
+ * of this line is that it names the person's real next step.
+ *
+ * NARROWING ONLY. It refuses a start; it grants nothing, widens no audience and changes no
+ * finalize rule. An expired answer is not an open one (identity/link-store.ts
+ * `openChallengeAnsweredBy` compares the TTL), so nobody is stranded: the loop the refusal points at
+ * is always one the person can still finish.
+ *
+ * `codeBack` is whether the answered row carries a code-back digest. When the code-back was
+ * undeliverable the finalize degrades to the acknowledged ratification ({@link codeBackDecision}),
+ * and the copy must not send the person looking for a code nobody posted.
+ *
+ * Returns the refusal a person reads, or `undefined` when no loop of theirs is open.
+ */
+export function linkStartOpenLoopRefusal(input: { readonly openLoop: boolean; readonly transport: LinkTransport; readonly codeBack: boolean }): string | undefined {
+  if (!input.openLoop) return undefined;
+  const subject = input.transport === "directory" ? "the link you just agreed to is still open" : "the link you just claimed is still open";
+  const finish = input.codeBack
+    ? "it finishes when you give whoever started it the code I posted you in this conversation."
+    : "it finishes when whoever started it confirms it on their own side.";
+  return `I can't start another link here: ${subject}, and ${finish}`;
+}
+
+/** What the initiator is told after a DIRECTORY-transport request goes out. Core-owned TRUSTED text;
+ *  `targetName` is the resolved, SANITIZED account label (identity/account-display-name.ts) and is
+ *  the only interpolation. PLAIN TEXT — this reaches whichever surface the person is on. */
+export function linkConsentPendingInstructions(targetName: string, ttlMinutes: number): string {
+  return (
+    `I have asked ${targetName} to confirm, in their own DM with me, that the account is theirs. ` +
+    `Nothing is linked yet, and nothing will be until you finalize it here.\n\n` +
+    `The request expires in ${ttlMinutes} minutes. When they answer I will come back to you in this ` +
+    `conversation. If you did not expect to be asked about that account, do nothing — a request that ` +
+    `is never finalized writes nothing at all.`
+  );
+}
+
+/**
+ * What the TARGET is asked, in their own DM, on the directory transport.
+ *
+ * 🔴 THIS IS AN UNSOLICITED MESSAGE TO A THIRD PARTY, AND ITS SHAPE IS A SECURITY DECISION. The
+ * recipient asked for nothing. Somebody else named their account, and the agent is about to put that
+ * stranger's chosen words in front of them. So the copy is built ANCHOR-FIRST:
+ *
+ *   • `initiatorAnchor` LEADS. It is composed from facts this deployment's own mapper captured — the
+ *     platform, the workspace and the account id — and is the one part of this message nobody can
+ *     choose. It is what the recipient should judge on.
+ *   • `initiatorName` is ATTRIBUTED, never asserted. It is the initiating account's own self-set
+ *     profile string, so the sentence says so in as many words: the agent reports what the account
+ *     CALLS ITSELF. Sanitizing (identity/account-display-name.ts) strips control characters and caps
+ *     the length, which stops a crafted name forging a second line — it does NOT remove a URL, a
+ *     brand name, or prose written to imitate the agent's own voice. Attribution is what makes those
+ *     harmless: a claim marked as a claim cannot borrow the agent's authority.
+ *   • The name is ABSENT entirely when none resolves. A placeholder would add nothing a reader can
+ *     check, and the anchor already names the account.
+ *
+ * The TARGET's own account is named by anchor too, never by profile name — the recipient knows who
+ * they are, and a second self-set string here would only be a second thing to spoof.
+ *
+ * PLAIN TEXT (no markdown — the direct-post path has no per-platform formatter).
+ */
+export function linkConsentAsk(input: {
+  readonly initiatorAnchor: string;
+  readonly initiatorName?: string;
+  readonly targetAnchor: string;
+  readonly ttlMinutes: number;
+}): string {
+  const attributed = input.initiatorName
+    ? `\n\nThat account calls itself "${input.initiatorName}". That is a name the account sets for ` +
+      `itself, so read it as a claim rather than as something I checked — the account id above is the ` +
+      `part nobody can change.`
+    : "";
+  return (
+    `Somebody asked me to link your account to theirs, and I need your say-so first.\n\n` +
+    `Who asked: ${input.initiatorAnchor}\n` +
+    `Your account: ${input.targetAnchor}${attributed}\n\n` +
+    `Linking means the two accounts count as ONE PERSON everywhere I can see, so their work and yours ` +
+    `are attributed together.\n\n` +
+    `If that account is yours, tell me here and I will record your consent. If you do not recognise it, ` +
+    `tell me to deny it. Nothing is written unless you agree, and the request expires on its own in ` +
+    `${input.ttlMinutes} minutes if you ignore it.`
+  );
+}
+
+/**
+ * The two BUTTON labels a consent ask carries on a surface that can render them (OPE-622).
+ *
+ * 🔴 NO INTERPOLATION, EVER. A label is the shortest thing on the screen and the least likely to be
+ * read carefully, so it must never be able to carry a self-set profile string. The ask's TEXT names
+ * the initiator and attributes their name as a claim; the buttons only name the two answers.
+ *
+ * They deliberately do not say "yes"/"no": the reader is being asked about a STRANGER's request, and
+ * a label that names the ACT ("this account is mine") is what makes an accidental tap unlikely.
+ */
+export function linkConsentButtonLabels(): { readonly confirm: string; readonly deny: string } {
+  return { confirm: "Yes — that account is mine", deny: "No — I don't recognise this" };
+}
+
+/**
+ * What the person who TAPPED sees, privately, on each outcome (OPE-622). Core-owned; the surface
+ * shows it to the clicker alone.
+ *
+ * 🔴 `notYours` ANSWERS TWO CASES WITH ONE SENTENCE — "this request is not yours" and "this request
+ * is gone" — and identity/link-consent.ts states why: a distinguishable answer would turn the button
+ * into an oracle that tells a stranger holding a challenge id whether it names somebody real.
+ */
+export function linkConsentClickAnswers(): {
+  readonly consented: string;
+  readonly consentedWithCode: (code: string) => string;
+  readonly denied: string;
+  readonly notYours: string;
+  readonly gone: string;
+} {
+  return {
+    consented:
+      "Recorded — thank you. NOTHING IS LINKED YET: the person who asked still has to finish it on " +
+      "their side, and I have told them you agreed. If you did not mean to do that, tell me here and " +
+      "I will take it back.",
+    consentedWithCode: (code: string) =>
+      `Recorded — thank you. Nothing is linked yet. To finish, the person who asked has to prove they ` +
+      `can read this conversation, so give them this code and let them enter it where they started the ` +
+      `link:\n\n    ${code}\n\nIt is single-use and expires with the request.`,
+    denied: "Declined. Nothing was written and nothing was linked, and that request is now closed for good.",
+    notYours:
+      "I have no open request for you to answer here. It was either already decided, or it has expired " +
+      "on its own. Nothing was written either way.",
+    gone: "That request is no longer open — it was already answered, or it expired. Nothing was written.",
+  };
+}
+
+/** What the TARGET is told once their consent is recorded and a code-back was minted. The code is
+ *  the one interpolation and this module never stores it. */
+export function codeBackInstructions(code: string): string {
+  return (
+    `Consent recorded. To finish, the person who asked has to prove they can read this conversation, ` +
+    `so give them this code and let them enter it where they started the link:\n\n    ${code}\n\n` +
+    `It is single-use and expires with the request. Nothing is linked until they enter it.`
+  );
+}
+
+/** What a CLAIMANT is told on the code transport once their `link <code>` lands and a code-back was
+ *  minted. Same act as {@link codeBackInstructions}, different door, so the copy names the door. */
+export function claimCodeBackReply(code: string): string {
+  return (
+    `That is a good code — I have recorded that this account is claiming the link. One step left: ` +
+    `whoever started the link has to prove they can read this, so enter this code where they started it:\n\n    ${code}\n\n` +
+    `It is single-use and expires with the request. Nothing is linked until it is entered.`
+  );
+}

package/agent/identity/link-initiator.ts

@@ -0,0 +1,27 @@
+// The gate on who may START or COMMIT an identity link, and it is deliberately SCOPED: it refuses only on a platform whose trust verdict was actually checked (BINDING_TRUSTED_PLATFORMS).
+// Elsewhere `trust !== "internal"` means nobody checked, so an unscoped refusal would not refuse guests — it would delete the feature for every caller on the platforms that cannot produce an internal verdict.
+
+import { BINDING_TRUSTED_PLATFORMS } from "../memory/domain.js";
+import type { Trust } from "./binding.js";
+
+/**
+ * The refusal a link-growing verb must throw, or `undefined` when the caller may proceed.
+ *
+ * A REFUSAL IS A VALUE here rather than a throw so the caller keeps its own error shape and the
+ * sentence is written once for both verbs. `act` completes "I can't ⟨act⟩ from here" — a short
+ * verb phrase ("start a link", "confirm a link"), never anything interpolated from content.
+ *
+ * The text is deliberately readable by the person who is refused: a guest DMing the agent should
+ * learn that membership is what is missing, not that something went wrong.
+ */
+export function linkInitiatorRefusal(binding: { readonly platform: string; readonly trust: Trust }, act: string): string | undefined {
+  if (binding.trust === "internal") return undefined;
+  // Absence of evidence is not refusal — see the header. Only a platform whose verdict was actually
+  // checked may refuse on it.
+  if (!BINDING_TRUSTED_PLATFORMS.has(binding.platform)) return undefined;
+  return (
+    `I can't ${act} from here — I can't confirm you're inside this organisation. ` +
+    `Linking accounts gives one person's identity reach across every surface I can see, so I only ` +
+    `do it for confirmed members. If you are one, ask an admin why this surface reads as external.`
+  );
+}

package/agent/identity/link-resolve.ts

@@ -0,0 +1,227 @@
+// The pure union read path: the config principals map plus confirmed DB link-sets, composed for attribution consumers. When both sides give one account to different people the account is dropped from both and a warning is emitted — never merged, and never matched on a display name.
+
+import { surfaceAccounts, surfaceIdsFromAccounts, type Principal, type PrincipalAccountRef, type PrincipalSurfaceIds } from "./principals.js";
+import { isTenantScopedPlatform, tryPrincipalKey } from "./principal-key.js";
+
+/** One confirmed link-set, flattened for the union. `handle` is DISPLAY ONLY (it becomes the
+ *  entry's `name` when there is no config entry to take a real name from); `ids` are the CONFIRMED
+ *  accounts only — the caller filters, because `expandLinkSet` already does. */
+export interface LinkSetPrincipal {
+  readonly linkSetId: string;
+  readonly handle: string;
+  readonly ids: PrincipalSurfaceIds;
+}
+
+export interface UnionWarning {
+  /** The account the two sides disagree about — its PRINCIPAL KEY when the grammar can compose one,
+   *  and an explicitly un-key-shaped sentence when it cannot. See {@link conflictWarning}. */
+  readonly key: string;
+  readonly message: string;
+}
+
+export interface PrincipalUnion {
+  /** The merged roster, in CONFIG ORDER first then DB-only entries — so a consumer that renders
+   *  this list sees the reviewed entries where it always saw them. */
+  readonly principals: readonly Principal[];
+  /** Every account dropped for conflicting ownership, with the reason. Non-empty means an operator
+   *  has an identity disagreement to resolve; consumers surface it rather than swallow it. */
+  readonly warnings: readonly UnionWarning[];
+}
+
+/** The exact account key: the (platform, tenant, id) triple as a JSON tuple, which is injective by construction, so no separator character can collide. */
+function strictKey(a: PrincipalAccountRef): string {
+  return JSON.stringify([a.platform, a.tenant ?? "", a.id]);
+}
+
+/** The account key with the workspace rung REMOVED — what an UNQUALIFIED entry can be matched on.
+ *  Never used as an identity, only as a lookup into {@link byLoose}; see {@link sameAccount}. */
+function looseKey(a: PrincipalAccountRef): string {
+  return JSON.stringify([a.platform, a.id]);
+}
+
+/**
+ * Are these two written accounts THE SAME ACCOUNT?
+ *
+ * 🔴 THE ASYMMETRIC ARM IS THE COMPATIBILITY GUARANTEE (OPE-350). Equal platform and equal id is
+ * necessary always. On a tenant-scoped platform, two QUALIFIED accounts must additionally agree on
+ * the workspace — that is the aliasing OPE-309 deleted, and it is not being re-opened here. But a
+ * QUALIFIED account and an UNQUALIFIED one with the same id ARE the same account, because "bare"
+ * means "this id, in whichever workspace this deployment serves" (principals.ts's header) and the
+ * qualified side simply says which one that is. Without this arm every existing single-workspace
+ * deployment would stop joining its config map to its own link-sets the moment the link tables
+ * started reporting a real tenant — the config entry says `slack: "U1"`, the confirmed row says
+ * `slack/T1/U1`, and a strict comparison calls them two people.
+ *
+ * The ambiguity that arm could create — one bare entry matching TWO qualified accounts in different
+ * workspaces — is not resolved by picking one. It is detected in {@link unionPrincipals} and treated
+ * as a conflict, which costs the account its cross-surface treatment and grants nothing.
+ */
+function sameAccount(a: PrincipalAccountRef, b: PrincipalAccountRef): boolean {
+  if (a.platform !== b.platform || a.id !== b.id) return false;
+  if (!isTenantScopedPlatform(a.platform)) return true;
+  if (a.tenant === undefined || b.tenant === undefined) return true;
+  return a.tenant === b.tenant;
+}
+
+/** An index over one side's accounts, supporting both the strict and the unqualified lookup. */
+interface AccountIndex {
+  /** strictKey → the owning entry's index. */
+  readonly byStrict: Map<string, number>;
+  /** looseKey → every (account, owner index) sharing that (platform, id). */
+  readonly byLoose: Map<string, { readonly account: PrincipalAccountRef; readonly owner: number }[]>;
+}
+
+function indexAccounts(sides: readonly { readonly ids: PrincipalSurfaceIds }[]): AccountIndex {
+  const byStrict = new Map<string, number>();
+  const byLoose = new Map<string, { account: PrincipalAccountRef; owner: number }[]>();
+  for (const [i, s] of sides.entries()) {
+    for (const a of surfaceAccounts(s.ids)) {
+      if (!byStrict.has(strictKey(a))) byStrict.set(strictKey(a), i);
+      const list = byLoose.get(looseKey(a)) ?? [];
+      list.push({ account: a, owner: i });
+      byLoose.set(looseKey(a), list);
+    }
+  }
+  return { byStrict, byLoose };
+}
+
+/**
+ * Union the config map with confirmed link-sets.
+ *
+ * Three cases, and the third is the one that matters:
+ *  • an account only config knows → the config entry, unchanged;
+ *  • an account only the DB knows → a new entry named by the link-set's handle;
+ *  • an account BOTH know:
+ *      – if the two entries share it and their other accounts are compatible (neither claims an
+ *        account the other assigns to somebody else), they are the SAME person and merge — the
+ *        config entry keeps its reviewed `name`/`handle`/`email` and gains the DB's extra accounts;
+ *      – otherwise the account is CONFLICTED: removed from both entries, warning emitted.
+ *
+ * Deterministic and total: no I/O, no clock, no config lookup, and the output order is config order
+ * then link-set order.
+ */
+export function unionPrincipals(config: readonly Principal[], linkSets: readonly LinkSetPrincipal[]): PrincipalUnion {
+  const warnings: UnionWarning[] = [];
+  const conflicted = new Map<string, PrincipalAccountRef>(); // strictKey → the account, for the warning
+
+  const flag = (a: PrincipalAccountRef): void => {
+    if (!conflicted.has(strictKey(a))) conflicted.set(strictKey(a), a);
+  };
+
+  // Which link-set (if any) each config entry corresponds to, and vice versa. A correspondence is
+  // established by a SHARED ACCOUNT — the only join key either side is allowed to be matched on.
+  const setIndex = indexAccounts(linkSets);
+  for (const [k, holders] of setIndex.byLoose) {
+    void k;
+    // Two link-sets claiming one account cannot happen through link-store.ts (the PK forbids it),
+    // but this function is total over whatever it is handed — so it is treated as a conflict rather
+    // than resolved by list order. Compared with `sameAccount` so two link-sets holding the SAME id
+    // in DIFFERENT workspaces (the whole point of OPE-350) are two accounts, not a collision.
+    for (const x of holders) {
+      for (const y of holders) {
+        if (x.owner === y.owner || !sameAccount(x.account, y.account)) continue;
+        flag(x.account);
+        flag(y.account);
+      }
+    }
+  }
+
+  const setsMatching = (a: PrincipalAccountRef): { readonly account: PrincipalAccountRef; readonly owner: number }[] =>
+    (setIndex.byLoose.get(looseKey(a)) ?? []).filter((h) => sameAccount(a, h.account));
+
+  const configForSet = new Map<number, number>(); // link-set index → config index
+  for (const [ci, p] of config.entries()) {
+    const hits = new Set<number>();
+    for (const a of surfaceAccounts(p.ids)) {
+      const matches = setsMatching(a);
+      // 🔴 ONE BARE ENTRY MATCHING TWO WORKSPACES' ACCOUNTS IS A CONFLICT, NOT A CHOICE. This is the
+      // only ambiguity the unqualified arm of `sameAccount` can introduce, and it is answered the
+      // same way every other identity disagreement here is: drop the account, say so, and let the
+      // operator qualify the entry. Picking a workspace would be inventing a tenant rung, which the
+      // grammar refuses to do everywhere else in the tree.
+      if (matches.length > 1 && new Set(matches.map((m) => m.account.tenant ?? "")).size > 1) {
+        flag(a);
+        for (const m of matches) flag(m.account);
+        continue;
+      }
+      for (const m of matches) hits.add(m.owner);
+    }
+    if (hits.size === 0) continue;
+    if (hits.size > 1) {
+      // This config entry's accounts are spread across several link-sets: config says one person,
+      // the DB says several. No merge — every shared account is conflicted.
+      for (const a of surfaceAccounts(p.ids)) {
+        const matches = setsMatching(a);
+        if (matches.length === 0) continue;
+        flag(a);
+        for (const m of matches) flag(m.account);
+      }
+      continue;
+    }
+    const si = [...hits][0]!;
+    const already = configForSet.get(si);
+    if (already !== undefined && already !== ci) {
+      // Two config entries share accounts with ONE link-set: the DB says one person, config says
+      // two. Same refusal, from the other direction.
+      for (const entry of [config[already]!, p]) {
+        for (const a of surfaceAccounts(entry.ids)) {
+          const matches = setsMatching(a).filter((m) => m.owner === si);
+          if (matches.length === 0) continue;
+          flag(a);
+          for (const m of matches) flag(m.account);
+        }
+      }
+      continue;
+    }
+    configForSet.set(si, ci);
+  }
+
+  for (const a of conflicted.values()) warnings.push(conflictWarning(a));
+
+  const dropped = (a: PrincipalAccountRef): boolean => conflicted.has(strictKey(a));
+  const mergedSets = new Set<number>();
+  const principals: Principal[] = [];
+
+  for (const [ci, p] of config.entries()) {
+    const si = [...configForSet.entries()].find(([, c]) => c === ci)?.[0];
+    const accounts: PrincipalAccountRef[] = surfaceAccounts(p.ids).filter((a) => !dropped(a));
+    if (si !== undefined) {
+      mergedSets.add(si);
+      for (const b of surfaceAccounts(linkSets[si]!.ids)) {
+        if (dropped(b)) continue;
+        // A confirmed DB account is added even when config already names accounts on that platform — it is a challenge-proven row, not a rival spelling of the same account. Only a genuine dispute between two owners refuses to merge, and that drops the account from both sides.
+        const same = accounts.find((a) => sameAccount(a, b));
+        if (same === undefined) {
+          accounts.push(b);
+          continue;
+        }
+        // The unqualified/qualified heal: config said `slack: "U1"`, the confirmed row says which
+        // workspace that was. Keep the QUALIFIED spelling — it is strictly more addressable, and it
+        // is the one that composes a principal key.
+        if (same.tenant === undefined && b.tenant !== undefined) accounts[accounts.indexOf(same)] = b;
+      }
+    }
+    principals.push({ ...p, ids: surfaceIdsFromAccounts(accounts) });
+  }
+
+  for (const [si, s] of linkSets.entries()) {
+    if (mergedSets.has(si)) continue;
+    const accounts = surfaceAccounts(s.ids).filter((a) => !dropped(a));
+    if (accounts.length === 0) continue;
+    principals.push({ name: s.handle, handle: s.handle, ids: surfaceIdsFromAccounts(accounts) });
+  }
+
+  return { principals, warnings };
+}
+
+/** The warning names the account's principal key when the grammar can compose one. An unqualified account on a tenant-scoped platform composes none, so the fallback stays prose rather than a key-shaped string that addresses nobody. */
+function conflictWarning(a: PrincipalAccountRef): UnionWarning {
+  const key = tryPrincipalKey(a.platform, a.tenant, a.id) ?? `the ${a.platform} account "${a.id}" (workspace unnamed)`;
+  return {
+    key,
+    message:
+      `identity conflict: ${key} is claimed by two different people across the config principals map and the DB link-sets. ` +
+      `NO merge was applied for that account (fail-closed on merge) — it stays a distinct per-surface identity until the ` +
+      `disagreement is resolved (edit agent/identity/principals.ts, or revoke the link-set).`,
+  };
+}