@open-everywhere/core 0.1.0

package/agent/identity/link-tenant-backfill.ts

@@ -0,0 +1,79 @@
+// Stamps the deployment's sole admitted tenant onto identity-link rows written before the `tenant` column existed (the migration gives those rows ""). On a vendor-global platform that blank is correct and final.
+// A row whose tenant this deployment cannot name is LEFT ALONE with a loud operator line and never a thrown boot: an un-backfilled row matches nothing, which costs standing and never grants it, and the sweep runs on every boot, so declaring the workspace heals it.
+
+import { getOperationalStore } from "../operational/provider.js";
+import { isTenantScopedPlatform } from "./principal-key.js";
+import { tryLinkTenantOf } from "./link-tenant.js";
+import type { OperationalStore } from "../operational/store.js";
+
+/** What one sweep did, per platform — returned so a test can assert on it and the boot caller can
+ *  log it, rather than either having to re-read the table. */
+export interface LinkTenantBackfillOutcome {
+  /** Tenant-scoped platforms whose blank rows were stamped, with how many rows moved. */
+  readonly filled: readonly { readonly platform: string; readonly tenant: string; readonly rows: number }[];
+  /** Tenant-scoped platforms with blank rows whose tenant this deployment cannot name. These rows
+   *  are LEFT ALONE and their links stay dormant — see the header. */
+  readonly unresolved: readonly string[];
+}
+
+/**
+ * Stamp the deployment's sole admitted tenant onto every blank linked-id row of a tenant-scoped
+ * platform. Idempotent (a second run finds no blanks) and safe to run on every boot.
+ *
+ * Never throws for an unnameable tenant — that platform lands in `unresolved` and its rows are left
+ * exactly as they are. A STORE failure does propagate: that is an outage, not a decision, and the
+ * boot caller is the one that decides whether to swallow it.
+ */
+export async function backfillLinkTenants(opts?: { readonly store?: OperationalStore; readonly now?: Date }): Promise<LinkTenantBackfillOutcome> {
+  const store = opts?.store ?? getOperationalStore();
+  const at = (opts?.now ?? new Date()).toISOString();
+  const filled: { platform: string; tenant: string; rows: number }[] = [];
+  const unresolved: string[] = [];
+  for (const platform of await store.unbackfilledLinkedIdPlatforms()) {
+    // A blank on a vendor-global platform is the permanent, correct value — not a backlog item. The
+    // store deliberately has no opinion about which platforms those are, so the filter lives here.
+    if (!isTenantScopedPlatform(platform)) continue;
+    const tenant = tryLinkTenantOf(platform, undefined);
+    // `tryLinkTenantOf` returns "" only for a non-tenant-scoped platform, which the guard above
+    // already excluded — so a blank here would mean the two disagreed, and stamping "" would be a
+    // no-op that also reported success. Treated as unresolved, which is the honest reading.
+    if (tenant === undefined || tenant.length === 0) {
+      unresolved.push(platform);
+      continue;
+    }
+    filled.push({ platform, tenant, rows: await store.backfillLinkedIdTenant(platform, tenant, at) });
+  }
+  return { filled, unresolved };
+}
+
+/** The operator-facing line for a platform whose blank rows could not be named. One string so the
+ *  boot log and any later report say the same thing, with the self-healing fix first. */
+export function linkTenantBackfillWarning(platform: string): string {
+  return (
+    `[open-everywhere:identity] ⚠ identity links on "${platform}" carry no workspace and this deployment cannot name one. ` +
+    `On ${platform} a person id is issued PER WORKSPACE, so those rows cannot be matched safely and their links are ` +
+    "DORMANT — the people on them fall back to per-surface identity (nothing is mis-attributed; standing is lost, never " +
+    `gained). Fix: declare that workspace's ${platform} channel in agent/memory/config/domains.ts and reboot — this sweep runs ` +
+    "on every boot and stamps the rows as soon as the workspace is nameable. If more than one workspace is declared " +
+    "(OE_ALLOW_MULTI_TENANT_PRINCIPALS=1), only the original delivery knew which one these rows belong to; they have to " +
+    "be re-linked. (OPE-309 phase 2, identity/link-tenant-backfill.ts)"
+  );
+}
+
+/**
+ * The boot entry point: run the sweep and say what happened, exactly once per process start.
+ * TOTAL — every failure is logged and swallowed, because an identity backfill must never be the
+ * reason a deployment fails to come up (the rows it could not fix are already inert).
+ */
+export async function bootBackfillLinkTenants(opts?: { readonly store?: OperationalStore; readonly log?: (line: string) => void }): Promise<void> {
+  const log = opts?.log ?? ((line: string) => console.log(line));
+  try {
+    const outcome = await backfillLinkTenants(opts?.store ? { store: opts.store } : undefined);
+    for (const f of outcome.filled) {
+      if (f.rows > 0) log(`[open-everywhere:identity] backfilled ${f.rows} "${f.platform}" identity link row(s) with tenant "${f.tenant}" (OPE-309 phase 2).`);
+    }
+    for (const platform of outcome.unresolved) log(linkTenantBackfillWarning(platform));
+  } catch (err) {
+    log(`[open-everywhere:identity] identity link tenant backfill could not run: ${err instanceof Error ? err.message : String(err)} — links written before the tenant column stay dormant until it does.`);
+  }
+}

package/agent/identity/link-tenant.ts

@@ -0,0 +1,54 @@
+// The `tenant` column's vocabulary for the identity link tables: a non-tenant-scoped platform always stores "" (the argument is IGNORED, not defaulted, because a Discord DM has no guild), a tenant-scoped platform stores the real `binding.workspace`, so "" on a tenant-scoped row means only "nobody has named this yet".
+// When a caller holds no binding the tenant comes from the deployment's sole admitted tenant (access/tenant-admission.ts); when config names none or names two, this fails closed rather than inventing an identity segment.
+
+import { isTenantScopedPlatform } from "./principal-key.js";
+import { MULTI_TENANT_ENV, soleAdmittedTenantFromConfig } from "../access/tenant-admission.js";
+
+/**
+ * The tenant value for an account whose platform is NOT tenant-scoped — and, on a tenant-scoped
+ * platform, the marker of a row written before the column existed. See the module header for why
+ * one sentinel serves both and why it is "" rather than NULL.
+ */
+export const LINK_TENANT_NONE = "";
+
+/**
+ * The tenant column value for one account on `platform`.
+ *
+ * `tenant` is the caller's own surface fact (`binding.workspace`, a challenge row's recorded
+ * tenant) — pass it whenever you have it, and `undefined` when you genuinely do not. It is IGNORED
+ * for a non-tenant-scoped platform, on purpose: see the header's Discord-DM case.
+ *
+ * THROWS when the platform is tenant-scoped, the caller supplied nothing, and the deployment's
+ * config names no single tenant. That is the one case where any answer would be invented, and an
+ * invented tenant segment is an identity claim — so the caller gets an exception with the two real
+ * fixes in it rather than a row nobody can account for.
+ */
+export function linkTenantOf(platform: string, tenant?: string | null): string {
+  const resolved = tryLinkTenantOf(platform, tenant);
+  if (resolved === undefined) throw new Error(linkTenantUnresolvableMessage(platform));
+  return resolved;
+}
+
+/** {@link linkTenantOf} as a VALUE — `undefined` where that one throws. For the callers that must
+ *  turn "cannot name the tenant" into a refusal sentence or a skipped step rather than an
+ *  exception (the sync planner, the boot backfill), which is most of them. */
+export function tryLinkTenantOf(platform: string, tenant?: string | null): string | undefined {
+  if (!isTenantScopedPlatform(platform)) return LINK_TENANT_NONE;
+  const given = typeof tenant === "string" ? tenant.trim() : "";
+  if (given.length > 0) return given;
+  return soleAdmittedTenantFromConfig(platform);
+}
+
+/** The operator-actionable message for an unresolvable tenant. One string, shared by the throw and
+ *  by every caller that reports the same condition as a refusal, so an operator meets the same
+ *  sentence wherever it surfaces. */
+export function linkTenantUnresolvableMessage(platform: string): string {
+  return (
+    `cannot name the ${platform} tenant for this account: on ${platform} a person id is issued PER TENANT, so an ` +
+    `identity link has to record which workspace it came from, and this call supplied none. This deployment's config ` +
+    `names no single ${platform} tenant either — either it declares no ${platform} channels at all, or it declares more ` +
+    `than one (which is only possible with ${MULTI_TENANT_ENV}=1). Fail closed. Fix: add the ${platform} channel for that ` +
+    `workspace to agent/memory/config/domains.ts, or make the call from a surface that names its workspace ` +
+    "(identity/link-tenant.ts, OPE-309)."
+  );
+}

package/agent/identity/oauth-vault-share.ts

@@ -0,0 +1,40 @@
+// The pure, org-scoped subject shape a confirmed link-set member keys the OAuth vault by, so one person's own token is reachable from every one of their own confirmed DMs.
+// MEMBERSHIP IS CONSENT: a suspended, revoked or unlinked set makes `callerLinkSets` return [] and the account resolves its raw subject on the next connector resolve, while a revoke additionally PURGES the credentials keyed by that subject.
+
+import { principalKey } from "./principal-key.js";
+
+/** The prefix that namespaces a SHARED (link-set) vault subject. The ONLY producer of an `ls:`-prefixed
+ *  subject is {@link sharedVaultSubject} for a caller who resolves to a confirmed/active link-set.
+ *
+ *  Disjointness from the raw path is STRUCTURAL, not a claim about vendor id shapes (threat (e)): the
+ *  only other producer of a vault subject is {@link rawVaultSubject}, which prefixes
+ *  {@link RAW_VAULT_SUBJECT_PREFIX} — a different literal — so no input to either function can make one
+ *  shape read as the other. Anchored on the two prefixes rather than on "no native id looks like this",
+ *  because the latter is a promise about six vendors' id namespaces that nobody here can keep. */
+export const SHARED_VAULT_SUBJECT_PREFIX = "ls:";
+
+/** The prefix that namespaces a RAW (single-account) vault subject — the counterpart to
+ *  {@link SHARED_VAULT_SUBJECT_PREFIX}, and the reason the two shapes cannot collide in either
+ *  direction. Distinct literals, both applied unconditionally by their one producer. */
+export const RAW_VAULT_SUBJECT_PREFIX = "p:";
+
+/**
+ * The ORG-SCOPED shared vault subject for a link-set — the value that replaces a caller's raw
+ * principal id as the OAuth vault key when they resolve to a confirmed/active link-set.
+ *
+ * 🔴 ORG-QUALIFIED ON PURPOSE (threat (d)). The OAuth vault key (`oe-oauth:tok:<ref>:user:<subject>`)
+ * does not itself carry org, so the org rides INSIDE the subject here — defence in depth on top of the
+ * already-globally-unique link-set UUID, so two orgs can never address one shared row even at the
+ * vault-key layer. Pure: a function of (org, linkSetId), no I/O.
+ */
+export function sharedVaultSubject(org: string, linkSetId: string): string {
+  return `${SHARED_VAULT_SUBJECT_PREFIX}${org}/${linkSetId}`;
+}
+
+/**
+ * The qualified vault subject for ONE account — the single composer every per-person credential key routes through (the connector user-OAuth vault, the AWS Identity Center token vault, the per-user warm cache), qualified by org, platform and, on a tenant-scoped platform, tenant, so no two people's rows can alias.
+ * It THROWS when the platform is tenant-scoped and the caller can name no tenant, because a wrong credential key hands somebody a stranger's live token; its output changed for Slack when the tenant rung landed, so pre-phase-1 rows are unreachable and each person re-authorises once.
+ */
+export function rawVaultSubject(org: string, platform: string, tenant: string | undefined | null, nativeId: string): string {
+  return `${RAW_VAULT_SUBJECT_PREFIX}${org}/${principalKey(platform, tenant, nativeId)}`;
+}

package/agent/identity/platform.ts

@@ -0,0 +1,48 @@
+// Platform normalization — a dependency-free LEAF so both binding.ts and
+// binding-bridge.ts can share the ONE implementation without importing each other.
+// (v1 had binding-bridge import channelPlatform back out of binding.ts — a
+// runtime-only ESM cycle that Node/tsx handled fine but is exactly the construct a
+// bundler can compile into a workflow-side runtime failure. A leaf module makes the
+// cycle impossible instead of arguing it's benign.)
+
+/**
+ * Channel-NAME → platform aliases. Eve derives a session's kind from the channel's FILE
+ * SLUG (agent/channels/<name>.ts), not its kindHint — so a platform served by a channel
+ * file that isn't named exactly after the platform binds as the file slug and silently
+ * misses the MAPPERS registry (live bug 2026-07-06: gateway sessions bound as platform
+ * "discord-gateway" in tool/hook contexts — the Discord mapper never ran and the approval
+ * tools refused the surface — while the route-side dispatch, which builds its own ctx with
+ * kind "discord", partitioned correctly). Alias every such channel file here.
+ */
+const PLATFORM_ALIASES: Readonly<Record<string, string>> = {
+  "discord-gateway": "discord", // channels/discord-gateway.ts — the relay-fed ambient-message surface
+};
+
+// Platforms a PREFIXED channel slug collapses to (`slack-qabot.ts` → "slack"). The
+// multi-bot direction (item 27) mounts one channel FILE per bot identity — per-identity
+// session namespacing comes free from eve's channel-name prefix — so every new identity
+// file would otherwise reproduce the "discord-gateway" live bug above (slug misses the
+// MAPPERS registry → binds fail-closed external) until someone remembers the alias table.
+// A prefix RULE kills the whole class; the explicit map above stays for exceptions.
+const PLATFORM_PREFIXES: readonly string[] = ["slack", "discord", "teams", "linear"];
+
+/** Collapse a bare kind/platform string through the alias table, then the prefix rule
+ *  (`<platform>-<anything>` → platform). Used by every seam that carries a platform
+ *  string — channelPlatform (live contexts) AND the binding-BRIDGE read (a durable
+ *  session stamped before an alias landed carries the raw slug; normalizing at read-time
+ *  heals those sessions instead of waiting for them to age out). */
+export function normalizePlatform(bare: string | undefined): string | undefined {
+  if (!bare) return bare;
+  const aliased = PLATFORM_ALIASES[bare];
+  if (aliased) return aliased;
+  for (const p of PLATFORM_PREFIXES) {
+    if (bare.startsWith(`${p}-`)) return p;
+  }
+  return bare;
+}
+
+/** Strip an eve namespaced kind ("channel:slack" → "slack") and normalize aliases. */
+export function platformFromKind(rawKind: string | undefined): string | undefined {
+  const bare = rawKind && rawKind.includes(":") ? rawKind.slice(rawKind.lastIndexOf(":") + 1) : rawKind;
+  return normalizePlatform(bare);
+}

package/agent/identity/principal-key-rules.ts

@@ -0,0 +1,113 @@
+// The pure checker behind `npm run lint:principal-key`: RULE 1 finds a hand-rolled principal key (a template literal joining a platform to a person id), RULE 2 finds any function named as a normaliser that strips the namespace back off.
+// Rule 2 is the one FAIL-OPEN shape here — every matcher over these keys fails closed on a mismatch, but an unqualifier makes two different people's keys compare equal — so it is banned by name; comment lines are skipped, because a comment spelling the grammar is documentation, not a second implementation.
+
+/** One defect, positioned so the driver can print `file:line`. */
+export interface PrincipalKeyDefect {
+  readonly file: string;
+  readonly line: number;
+  readonly rule: "composition" | "unqualifier";
+  readonly excerpt: string;
+  readonly message: string;
+}
+
+/** A `principalKey` FUNCTION declaration — collected across the tree so the driver can assert there
+ *  is exactly one, in the module that owns the grammar. */
+export interface ComposerDeclaration {
+  readonly file: string;
+  readonly line: number;
+}
+
+/** The module that owns the grammar, and the only file exempt from RULE 1. */
+export const PRINCIPAL_KEY_MODULE = "packages/core/agent/identity/principal-key.ts";
+
+/**
+ * Identifier fragments that name a PERSON. A key whose last segment interpolates one of these is a
+ * principal key; a key ending in `workspace`/`surface`/`channel` is a place and is out of scope.
+ *
+ * Evidence-gated (no-extrapolation): every fragment here is taken from an identifier that actually
+ * appears on a principal-composing call site in this tree — `principalId`, `nativeId`, `authorId`,
+ * `userId`, `clickerId`, `actor`, `memberId` — rather than from a general vocabulary of things that
+ * sound person-ish.
+ */
+const PERSON_ID_NOUNS = /(principal|native[_]?id|author[_]?id|user[_]?id|clicker[_]?id|member[_]?id|actor|sender[_]?id)/i;
+
+/**
+ * …plus a BARE `id` as the whole final expression (`id`, `parsed.id`, `p?.id`). Included because
+ * three of the real finds spelled it exactly that way, and excluded from the fragment list above
+ * because it must anchor: `channelId` and `workspaceId` end in "Id" and name places, so a
+ * substring test would flag every surface key in the tree.
+ */
+const BARE_ID = /(^|[.?\s])id$/i;
+
+/** A platform interpolation, then one or more `/`-joined interpolations. The LAST one decides
+ *  whether this is a person or a place, which is why it is captured separately. */
+const COMPOSITION = /\$\{([^}]*platform[^}]*)\}((?:\/\$\{[^}]*\})*)\/\$\{([^}]*)\}/gi;
+
+/** A name that pairs a stripping verb with principal vocabulary — RULE 2's target. `bareKey` is
+ *  listed by name because it is the one spelling that carries no principal token at all and would
+ *  otherwise slip through. */
+const UNQUALIFIER_NAME = /^(?:bareKey|(?=.*(?:strip|unqualif|bare|legacy))(?=.*principal).*)$/i;
+const DECLARATION = /\b(?:function|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g;
+
+/** Is this source line a comment? A comment that spells the grammar is documentation — including
+ *  this module's own header, which necessarily writes out the shapes it is talking about. */
+function isCommentLine(line: string): boolean {
+  const t = line.trim();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+
+/** Every defect in one source file. Pure; `file` is used only for reporting + the one exemption. */
+export function findPrincipalKeyDefects(file: string, source: string): PrincipalKeyDefect[] {
+  const defects: PrincipalKeyDefect[] = [];
+  const exempt = file.replace(/\\/g, "/").endsWith(PRINCIPAL_KEY_MODULE.slice(PRINCIPAL_KEY_MODULE.lastIndexOf("agent/")));
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (isCommentLine(line)) continue;
+
+    if (!exempt) {
+      for (const m of line.matchAll(COMPOSITION)) {
+        const last = m[3]!.trim();
+        if (!PERSON_ID_NOUNS.test(last) && !BARE_ID.test(last)) continue; // a place key — tenant/surface, not ours
+        defects.push({
+          file,
+          line: i + 1,
+          rule: "composition",
+          excerpt: m[0]!,
+          message:
+            `hand-rolled principal key \`${m[0]}\` — compose it with principalKey() from identity/principal-key.ts. ` +
+            "It is byte-identical today and that is the problem: when the grammar gains its tenant rung (OPE-309 phase 1) this copy keeps emitting the old shape, and a qualified-vs-unqualified mismatch is a plain string mismatch that silently matches nobody.",
+        });
+      }
+    }
+
+    for (const m of line.matchAll(DECLARATION)) {
+      const name = m[1]!;
+      if (!UNQUALIFIER_NAME.test(name)) continue;
+      defects.push({
+        file,
+        line: i + 1,
+        rule: "unqualifier",
+        excerpt: name,
+        message:
+          `\`${name}\` reads as a normaliser that strips a principal key's namespace back off. ` +
+          "🔴 That is the one FAIL-OPEN shape in this whole design: every matcher fails closed on a mismatch, so a missed one costs lost standing — but a normaliser that unqualifies makes two different people's keys compare EQUAL again. If this name means something else, rename it; there is no compatibility case that wants this function.",
+      });
+    }
+  }
+  return defects;
+}
+
+/** Every `principalKey` function declaration in one file — the driver asserts the tree has exactly
+ *  one, and that it lives in {@link PRINCIPAL_KEY_MODULE}. A second composer is the defect this
+ *  whole module exists to prevent, stated as a whole-tree property rather than a per-line one. */
+export function findComposerDeclarations(file: string, source: string): ComposerDeclaration[] {
+  const out: ComposerDeclaration[] = [];
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (isCommentLine(line)) continue;
+    if (/\b(?:export\s+)?function\s+principalKey\s*\(/.test(line)) out.push({ file, line: i + 1 });
+  }
+  return out;
+}

package/agent/identity/principal-key.ts

@@ -0,0 +1,210 @@
+// The one spelling of which person, on which platform, in which tenant: platform/native-id, or platform/tenant/native-id on a tenant-scoped platform, where a person id is issued per workspace and would otherwise alias two humans onto one key.
+// The platform is always a surface fact. It comes from the binding, the wake's channel key or the click's own room, never from inspecting the id's shape.
+
+/**
+ * A well-formed principal key: a lowercase, slash-free platform token, then "/", then a
+ * non-empty id carrying neither a slash nor whitespace.
+ *
+ * The id is deliberately slash-free. Every platform in the tree addresses a person with one
+ * opaque token (Slack member id, Discord snowflake, GitHub login, Linear/Notion/AAD
+ * uuid), so admitting a "/" would only make the parse ambiguous with no platform asking for it.
+ * A future platform that genuinely needs a path-shaped id changes THIS regex and
+ * {@link parsePrincipalKey} together — not one call site.
+ */
+export const PRINCIPAL_KEY = /^[a-z0-9][a-z0-9-]*\/[^/\s]+$/u;
+
+/**
+ * The TENANT-SCOPED principal key: the same platform token, then the tenant that ISSUED the id,
+ * then the id. Both tail segments carry neither a slash nor whitespace for the same reason the
+ * two-segment shape's id does — the parse has to be unambiguous, and no vendor in the tree
+ * addresses a workspace or a person with a path.
+ */
+const TENANT_PRINCIPAL_KEY = /^[a-z0-9][a-z0-9-]*\/[^/\s]+\/[^/\s]+$/u;
+
+/**
+ * The literal `binding.workspace` falls back to when a delivery names no workspace at all
+ * (identity/binding.ts's `seg(raw.workspace ?? local.workspace, UNNAMED_TENANT)`).
+ *
+ * 🔴 IT IS REFUSED AS A TENANT RUNG, and that refusal is the point (OPE-309 §2). It is not a
+ * workspace id — it is the string that means "nobody said". Letting it into a key would make one
+ * aliasing bucket that every unnamed delivery lands in, which is the exact defect the rung exists
+ * to delete, wearing a different spelling. Exported so binding.ts and this module cannot drift
+ * to two different literals.
+ */
+export const UNNAMED_TENANT = "dev";
+
+/**
+ * THROWS when the platform is tenant-scoped and no tenant can be named, the UNNAMED_TENANT fallback included: a guessed tenant segment grants standing to whoever collides, so there is no answer to invent. Callers that need a refusal instead of an exception use tryPrincipalKey.
+ * It deliberately does not normalize the platform string; a caller holding one that needs repair has an upstream bug (identity/platform.ts normalizes already).
+ */
+export function principalKey(platform: string, tenant: string | undefined | null, id: string): string {
+  const key = tryPrincipalKey(platform, tenant, id);
+  if (key === undefined) throw new Error(principalTenantUnresolvableMessage(platform, id));
+  return key;
+}
+
+/** {@link principalKey} as a VALUE — `undefined` where that one throws. For the callers that must
+ *  turn "cannot name the tenant" into a skipped step, a refusal sentence or a fail-closed `false`
+ *  rather than an exception (the resolver's DM branch, every roster matcher, an audit label).
+ *  Same split as identity/link-tenant.ts's `linkTenantOf`/`tryLinkTenantOf`. */
+export function tryPrincipalKey(platform: string, tenant: string | undefined | null, id: string): string | undefined {
+  if (!isTenantScopedPlatform(platform)) return `${platform}/${id}`;
+  const named = typeof tenant === "string" ? tenant.trim() : "";
+  if (named.length === 0 || named === UNNAMED_TENANT || named.includes("/")) return undefined;
+  return `${platform}/${named}/${id}`;
+}
+
+/** The operator-actionable message for a principal key that cannot be composed. One string, shared
+ *  by the throw and by every caller that reports the same condition as a refusal, so an operator
+ *  meets the same sentence wherever it surfaces (identity/link-tenant.ts's convention). */
+function principalTenantUnresolvableMessage(platform: string, id?: string): string {
+  return (
+    `cannot name the ${platform} tenant for ${id ? `"${id}"` : "this person"}: on ${platform} a person id is issued PER ` +
+    `WORKSPACE, so a principal key has to carry which workspace it came from ("${platform}/<tenant-id>/<native-id>"), and this ` +
+    `call named none — the delivery carried no workspace, or it fell back to "${UNNAMED_TENANT}", which is the string for ` +
+    "\"nobody said\" and not a workspace id. Fail closed: no standing is granted rather than guessing a tenant. " +
+    "(identity/principal-key.ts, OPE-309)"
+  );
+}
+
+/**
+ * Is this string a well-formed principal key? PLATFORM-AWARE by construction: the leading segment
+ * decides which shape is required, so a `slack/U1` entry written before the tenant rung fails here
+ * — which is exactly right, because the composer can no longer mint that string and the entry can
+ * therefore never match anybody. The config-load test; a `false` here means the entry is inert,
+ * which is why every caller of it throws rather than warns.
+ */
+export function isQualifiedPrincipalKey(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  const slash = value.indexOf("/");
+  if (slash <= 0) return false;
+  const platform = value.slice(0, slash);
+  if (!isTenantScopedPlatform(platform)) return PRINCIPAL_KEY.test(value);
+  // The {@link UNNAMED_TENANT} rung is refused for the same reason the composer refuses to mint
+  // it: the string is well-SHAPED and matches nobody, so it belongs on the loud side of the line.
+  return TENANT_PRINCIPAL_KEY.test(value) && value.split("/")[1] !== UNNAMED_TENANT;
+}
+
+/**
+ * Split a principal key back into its parts, or `undefined` when it isn't one. `tenant` is present
+ * exactly when the platform is tenant-scoped. A VALUE, not a throw: the readers are display/filter
+ * paths (a governance roster projection, an audit label) where a malformed entry must be skipped,
+ * not turned into an outage. Load-time validation is {@link isQualifiedPrincipalKey}'s job and runs
+ * first.
+ */
+export function parsePrincipalKey(
+  value: string | undefined,
+): { readonly platform: string; readonly tenant?: string; readonly id: string } | undefined {
+  if (!isQualifiedPrincipalKey(value)) return undefined;
+  const parts = value!.split("/");
+  return parts.length === 3
+    ? { platform: parts[0]!, tenant: parts[1]!, id: parts[2]! }
+    : { platform: parts[0]!, id: parts[1]! };
+}
+
+/**
+ * Is (platform, tenant, id) named on this roster of principal keys? The ONE matcher every roster
+ * check runs through (`Domain.admins` in access/roles.ts, identity/wake-trust.ts, approvals/flow.ts).
+ *
+ * FAIL-CLOSED on every missing part: no roster, no platform (the caller couldn't resolve which
+ * namespace the id lives in), no id, and — on a tenant-scoped platform — no nameable tenant all
+ * read as "not on the roster", never as a match. It is a BOOLEAN gate, so an unnameable tenant is
+ * reported as `false` rather than thrown: "not an admin" is the answer, and turning it into an
+ * outage would be a strictly worse way to say the same thing.
+ */
+export function rosterHasPrincipal(
+  roster: readonly string[] | undefined,
+  platform: string | undefined,
+  tenant: string | undefined | null,
+  id: string | undefined,
+): boolean {
+  if (!roster || roster.length === 0 || !platform || !id) return false;
+  const key = tryPrincipalKey(platform, tenant, id);
+  return key !== undefined && roster.includes(key);
+}
+
+/**
+ * The config-load remedy sentence for an entry that is not a well-formed key on a TENANT-SCOPED
+ * platform — the exact replacement when the deployment names exactly one tenant of that platform
+ * (access/tenant-admission.ts's `soleAdmittedTenant`, a FACT while the phase-0c fence is armed),
+ * and the shape plus where to find the missing segment when it does not.
+ *
+ * Pure: the caller resolves the tenant and passes it, so this module stays a zero-import leaf.
+ */
+export function principalKeyReplacementHint(entry: string, tenant: string | undefined): string {
+  const slash = entry.indexOf("/");
+  const platform = slash > 0 ? entry.slice(0, slash) : entry;
+  const id = slash > 0 ? entry.slice(slash + 1) : entry;
+  return tenant
+    ? `On ${platform} a person id is issued PER WORKSPACE, so the key needs the workspace rung. This deployment declares exactly one ${platform} workspace, so the replacement is "${platform}/${tenant}/${id}".`
+    : `On ${platform} a person id is issued PER WORKSPACE, so the key needs the workspace rung: "${platform}/<tenant-id>/${id}". The tenant id is the SECOND segment of this deployment's ${platform} channel keys in agent/memory/config/domains.ts (a channel "${platform}/T0AB1CD2E/C123" makes the key "${platform}/T0AB1CD2E/${id}").`;
+}
+
+/**
+ * The platforms whose PERSON ids are scoped to a tenant rather than to the vendor globally — the
+ * platforms where "two workspaces on one deployment" would make two different humans share one
+ * principal key (OPE-309).
+ *
+ * 🔴 MEMBERSHIP IS A CLAIM ABOUT OUR OWN MAPPERS, NOT ABOUT A VENDOR'S NAMESPACE. The question is
+ * NOT "does this vendor promise globally-unique ids" — that is a promise about somebody else's
+ * system that this repo explicitly refuses to rely on. It is "does OUR mapper name the tenant on
+ * EVERY delivery, DM included, so a tenant-qualified key could actually be composed there". That
+ * is testable per provider, which is the only reason a platform may be added.
+ *
+ * Only `slack` is in the set, because Slack is the only platform with in-repo evidence of a
+ * tenant-scoped id space AND a tenant named on every delivery (`team_id` rides channel and DM
+ * events alike; channels/slack.ts additionally heals it from the domain config). Per the
+ * no-extrapolation rule the other slots stay EMPTY rather than being filled from plausible priors.
+ *
+ * ADD-CRITERIA — a platform joins this set when all three hold, each demonstrated by a test:
+ *   1. the platform's person ids are namespaced per tenant (two tenants can issue the same id);
+ *   2. our mapper resolves the tenant on EVERY delivery mode, DM included — Discord is the
+ *      counter-example: a DM has no guild, so `workspace` falls back to the userId and the same
+ *      human would key differently in a channel than in a DM;
+ *   3. the credentials keyed by that principal (vault subjects, SSO token cache) are re-consented,
+ *      because adding a platform RE-KEYS them.
+ *
+ * FAILS OPEN for a platform not listed, deliberately: the alternative — assuming every platform is
+ * tenant-scoped — re-keys five platforms that have no defect and breaks Discord DMs outright.
+ */
+const TENANT_SCOPED_PLATFORMS: ReadonlySet<string> = new Set(["slack"]);
+
+/** Is this platform's person-id space scoped to a tenant? See {@link TENANT_SCOPED_PLATFORMS} for
+ *  what membership asserts and what it takes to add one. Fail-open on an unknown/absent platform,
+ *  matching the set's own documented posture. */
+export function isTenantScopedPlatform(platform: string | undefined): boolean {
+  return platform !== undefined && TENANT_SCOPED_PLATFORMS.has(platform);
+}
+
+/**
+ * The BARE ids on this roster that belong to `platform` IN `tenant`. For the one consumer that must
+ * compare a roster against ids a platform API hands back in its own namespace
+ * (access/audience-floor.ts's live room membership): the roster is projected DOWN into that
+ * namespace once, rather than every member id being lifted up into keys. Entries for other
+ * platforms — and malformed ones — drop out, which is the correct answer for a per-platform roster
+ * question.
+ *
+ * 🔴 THE TENANT FILTER IS NOT COSMETIC. Projecting down DISCARDS the namespace, so on a
+ * tenant-scoped platform a roster entry from another workspace would come back as a bare `U…` that
+ * the consumer then compares against THIS room's member list — re-creating, inside the one function
+ * that legitimately unqualifies, exactly the aliasing the rung deletes. Hence: entries whose tenant
+ * is not this one drop out, and an unnameable tenant yields nothing at all (fail closed).
+ */
+export function principalIdsOnPlatform(
+  roster: Iterable<string>,
+  platform: string | undefined,
+  tenant: string | undefined | null,
+): string[] {
+  if (!platform) return [];
+  const scoped = isTenantScopedPlatform(platform);
+  const named = typeof tenant === "string" ? tenant.trim() : "";
+  if (scoped && (named.length === 0 || named === UNNAMED_TENANT)) return [];
+  const ids: string[] = [];
+  for (const entry of roster) {
+    const parsed = parsePrincipalKey(entry);
+    if (parsed?.platform !== platform) continue;
+    if (scoped && parsed.tenant !== named) continue;
+    ids.push(parsed.id);
+  }
+  return ids;
+}