@open-everywhere/core 0.1.0

package/agent/identity/directory.ts

@@ -0,0 +1,89 @@
+// The vendor-neutral directory port an enterprise IdP adapter plugs into, so identity links can be pre-populated; unregistered means the feature is cleanly OFF rather than a crash.
+// The IdP is a SYNC SOURCE, never an authority and never on a request path: everything it returns lands as a `suggested` row that changes no attribution until a human confirms it, and only the `attested` grade may skip that human (OE_DIRECTORY_AUTOCONFIRM=attested, default off).
+
+/** How strongly the directory's (platform, nativeId) claim is evidenced. Ordered strongest-first;
+ *  see the module header. The auto-confirm policy may act on "attested" ALONE — "asserted" (the IdP
+ *  states the mapping, the downstream platform never confirmed it) and "email-match" both wait for
+ *  the person, and both are ratifiable only by the named account itself. */
+export type DirectoryGrade = "attested" | "asserted" | "email-match";
+
+/** One platform account the directory maps to a person. `platform` is our own platform token
+ *  ("slack", "github", "linear" — the same namespace `principalKey` qualifies with), NEVER the
+ *  vendor's own app label; `nativeId` is that platform's own opaque user id. */
+export interface DirectoryAccount {
+  readonly platform: string;
+  /**
+   * Which workspace issued `nativeId` on a tenant-scoped platform. Absent means the sync falls back to the deployment's sole admitted workspace, so an adapter that never sets it behaves exactly as it did before the field existed.
+   * It is the OPERATOR'S own mapping (for Okta, the `<platform>/<tenant>` half of an OE_DIRECTORY_OKTA_APPS entry), never the IdP answering "which workspace", and the sync still refuses a workspace this deployment has not admitted.
+   */
+  readonly tenant?: string;
+  readonly nativeId: string;
+  readonly grade: DirectoryGrade;
+}
+
+/**
+ * One person as the directory sees them.
+ *
+ * `externalId` is the IdP's own stable user id. It is an AUDIT and GROUPING key — it is stamped
+ * into the evidence of every row this person's sync writes so "why does the system believe these
+ * are the same human" answers with a directory record — but it is NEVER a join key into link-sets:
+ * the only join currency is (platform, nativeId), which is link-store.ts's invariant 4 ("nothing
+ * joins on a name") holding one level up. `displayName` and `email` are DISPLAY/enricher inputs on
+ * the same footing.
+ */
+export interface DirectoryPerson {
+  readonly externalId: string;
+  readonly displayName: string;
+  readonly email?: string;
+  readonly accounts: readonly DirectoryAccount[];
+  /** IdP group names, verbatim — the input identity/group-sync.ts diffs into the person-groups overlay. */
+  readonly groups: readonly string[];
+  /**
+   * The person is deactivated in the IdP (Okta DEPROVISIONED/SUSPENDED). NARROWING SIGNAL: the sync
+   * applies it EAGERLY (suspend the link-set) even in the most conservative policy mode, because
+   * narrowing is safe to automate and only widening needs a gate. It is never a revoke — terminal
+   * decisions stay human.
+   */
+  readonly deprovisioned: boolean;
+}
+
+/** The vendor-neutral directory port. One adapter satisfies it structurally and is the ONLY place
+ *  an IdP API is named. `id` is the provider token stamped into every row's evidence
+ *  (`directory-sync:<id>`), so it must be stable across deploys — it is what an audit row is read
+ *  back against, not a label. */
+export interface DirectoryProvider {
+  /** Stable provider token, e.g. "okta". Appears in evidence and audit rows. */
+  readonly id: string;
+  /** Human-readable name for logs and the control-plane status view. */
+  readonly name: string;
+  /**
+   * The whole directory, in one call. A FULL SNAPSHOT rather than a delta feed on purpose: the sync
+   * planner is a pure diff against materialised state, so it needs both sides in hand, and a
+   * partial page would read as "these people no longer exist" — which the planner is explicitly
+   * forbidden to act on, but which would still make its deprovision detection wrong.
+   *
+   * Throwing is the correct failure: a directory that half-answered must not be diffed. The sync
+   * catches it, logs loudly and leaves state untouched.
+   */
+  listPeople(): Promise<readonly DirectoryPerson[]>;
+}
+
+let registered: DirectoryProvider | undefined;
+
+/** Register the directory provider (the IdP adapter). Called once at boot by the adapter wiring;
+ *  idempotent overwrite (last wins), mirroring registerAwsIdentityProvider/registerUserAuthFlow. */
+export function registerDirectoryProvider(provider: DirectoryProvider): void {
+  registered = provider;
+}
+
+/** The registered provider, or undefined when no directory adapter is wired — the CLEANLY-OFF
+ *  answer. Deliberately NOT a `require*` throwing twin: unlike an AWS mint, there is no caller here
+ *  that must have a provider. The sync tick and both control verbs are meant to be callable on a
+ *  deployment with no IdP and say "nothing is wired", which is information, not an outage. */
+export function directoryProvider(): DirectoryProvider | undefined {
+  return registered;
+}
+
+export function resetDirectoryProvider(): void {
+  registered = undefined;
+}

package/agent/identity/display-title.ts

@@ -0,0 +1,19 @@
+// `name` is the IMMUTABLE identifier: it is persisted verbatim into operational rows, routine rows frozen at arm time, audit detail and the synthetic session-registry key, and nothing migrates on a rename — so the optional `title` is the only field a human-facing rename touches.
+// This module is the one place that resolves the pair, and its output is DISPLAY-ONLY: nothing resolves, matches, partitions, authorizes or persists on it.
+
+/** Anything carrying the immutable-name / optional-display-title pair. */
+export interface Titled {
+  readonly name: string;
+  readonly title?: string;
+}
+
+/**
+ * The label to show a human for a named config object: its `title` when set to something
+ * non-blank, otherwise its `name`. Never throws; a whitespace-only title is treated as
+ * absent (a half-filled config field must not render as an empty label).
+ */
+export function displayTitle(x: Titled | undefined): string | undefined {
+  if (!x) return undefined;
+  const t = x.title?.trim();
+  return t && t.length > 0 ? t : x.name;
+}

package/agent/identity/frozen-surface-binding.internal.ts

@@ -0,0 +1,83 @@
+// A host-frozen SurfaceBinding carried across an internal unified delivery. The codec lives in its
+// own leaf so identity/binding.ts and channels/unified-window.ts can share one strict grammar without
+// importing each other's runtime graphs.
+
+import type { BindableContext, SurfaceBinding } from "./binding.js";
+
+/** Host-only auth stamp for an internal delivery whose authority was frozen on an earlier wake. */
+export const OE_FROZEN_SURFACE_BINDING_ATTR = "oe_frozen_surface_binding";
+
+/** Strictly admit the sanitized binding shape that may cross a durable/store or self-dispatch seam. */
+export function isFrozenSurfaceBinding(value: unknown): value is SurfaceBinding {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const b = value as Record<string, unknown>;
+  const allowed = new Set([
+    "org",
+    "platform",
+    "workspace",
+    "surface",
+    "domainSurface",
+    "mode",
+    "modeResolved",
+    "visibility",
+    "trust",
+    "declaredTrust",
+    "principalId",
+    "principalAttested",
+    "target",
+    "threadTs",
+    "engagementKey",
+    "roomEngagementKey",
+    "anchorMessageId",
+    "anchorChannelId",
+  ]);
+  if (Object.keys(b).some((key) => !allowed.has(key))) return false;
+  for (const key of ["org", "platform", "workspace", "surface"] as const) {
+    if (typeof b[key] !== "string" || b[key].length === 0) return false;
+  }
+  if (b.mode !== "channel" && b.mode !== "dm" && b.mode !== "mpim") return false;
+  if (b.visibility !== "public" && b.visibility !== "private") return false;
+  if (b.trust !== "internal" && b.trust !== "external") return false;
+  if (b.declaredTrust !== undefined && b.declaredTrust !== "internal" && b.declaredTrust !== "public") return false;
+  if (b.principalAttested !== undefined && b.principalAttested !== true) return false;
+  // OPE-1867: the mode's provenance rides the freeze, or a frozen turn would report every
+  // conversation as gap-filled and mask surfaces the mapper did classify. `true`-or-absent, like
+  // principalAttested above — a `false` is not a spelling this grammar admits.
+  if (b.modeResolved !== undefined && b.modeResolved !== true) return false;
+  for (const key of ["domainSurface", "principalId", "threadTs", "engagementKey", "roomEngagementKey", "anchorMessageId", "anchorChannelId"] as const) {
+    if (b[key] !== undefined && (typeof b[key] !== "string" || b[key].length === 0)) return false;
+  }
+  if (b.target !== undefined) {
+    if (b.target === null || typeof b.target !== "object" || Array.isArray(b.target)) return false;
+    const target = b.target as Record<string, unknown>;
+    const allowedTargetKeys: Readonly<Record<string, ReadonlySet<string>>> = {
+      slack: new Set(["channelId"]),
+      discord: new Set(["channelId", "guildId", "channelType"]),
+      notion: new Set(["discussionId", "pageId", "credentialId"]),
+      linear: new Set(["agentSessionId", "issueId", "parentId", "organizationId"]),
+      teams: new Set(["serviceUrl", "conversationId", "tenantId", "channelId", "teamId", "conversationType", "aadObjectId"]),
+      github: new Set(["owner", "repo", "issueNumber", "pullRequestNumber", "installationId"]),
+    };
+    const keys = allowedTargetKeys[String(b.platform)];
+    if (
+      keys === undefined ||
+      Object.keys(target).some((key) => !keys.has(key)) ||
+      Object.values(target).some((v) => v !== undefined && typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+    )
+      return false;
+  }
+  return true;
+}
+
+/** Parse the frozen binding carried by one host-built internal delivery. */
+export function frozenSurfaceBindingFrom(ctx: BindableContext): SurfaceBinding | undefined {
+  try {
+    const raw = ctx.session?.auth?.current?.attributes?.[OE_FROZEN_SURFACE_BINDING_ATTR];
+    const text = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof text !== "string" || text.length === 0 || text.length > 16_384) return undefined;
+    const parsed: unknown = JSON.parse(text);
+    return isFrozenSurfaceBinding(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/agent/identity/group-sync.ts

@@ -0,0 +1,169 @@
+// The pure planner that diffs IdP group membership against the machine-owned person-group overlay and emits the next overlay file.
+// Groups are access-bearing, so nothing here writes: every change, an addition or a removal, lands only through a diff a human merged.
+
+import { directoryGroupName, type Group } from "./groups.js";
+import { directoryLinkSetId } from "./directory-sync.js";
+import { emitGroupsModule, type GroupsFile } from "./groups-codemod.js";
+import type { DirectoryPerson } from "./directory.js";
+
+/** One thing merging this plan's overlay would change. There is deliberately no "apply" verb — the
+ *  steps describe a DIFF a human reads, not operations something performs. */
+export type GroupSyncStep =
+  | { readonly kind: "add-group"; readonly group: string; readonly title: string; readonly members: number }
+  | { readonly kind: "drop-group"; readonly group: string; readonly members: number }
+  | { readonly kind: "add-member"; readonly group: string; readonly linkSet: string }
+  | { readonly kind: "remove-member"; readonly group: string; readonly linkSet: string };
+
+export interface GroupSyncPlan {
+  readonly provider: string;
+  readonly people: number;
+  /** The overlay this plan would produce — canonical, deterministic, ready to emit. */
+  readonly next: GroupsFile;
+  readonly steps: readonly GroupSyncStep[];
+  /** LOUD, operator-facing: everything the planner refused to act on. */
+  readonly warnings: readonly string[];
+  readonly counts: {
+    readonly addGroup: number;
+    readonly dropGroup: number;
+    readonly addMember: number;
+    readonly removeMember: number;
+  };
+}
+
+/** True when merging this plan would change nothing — the idempotency property, named so a caller
+ *  (and a test) can assert it without re-deriving what "no change" means. */
+export function groupPlanIsNoop(plan: GroupSyncPlan): boolean {
+  return plan.steps.length === 0;
+}
+
+/**
+ * THE PURE DIFF: directory group membership vs the current overlay.
+ *
+ * `current` is the overlay's OWN groups (identity/groups-codemod.ts `directoryGroupsOf` recovers
+ * them from a merged registry on a deployed instance). Hand-written groups are never in it and are
+ * never touched — the namespace partition is what guarantees that.
+ */
+export function planDirectoryGroups(input: {
+  readonly provider: string;
+  readonly people: readonly DirectoryPerson[];
+  readonly current: GroupsFile;
+  /**
+   * Rule 5 — the operator's optional allowlist of VERBATIM IdP group names. Present ⇒ only these
+   * groups sync; a person's membership in any group not on the list is ignored (it never enters
+   * `desired`, so it neither adds nor holds an overlay group). Absent/undefined ⇒ every group syncs,
+   * the original behaviour. Resolved at the edge (`directoryGroupAllowlist`) so this planner stays
+   * pure.
+   */
+  readonly allowGroups?: readonly string[];
+}): GroupSyncPlan {
+  const warnings: string[] = [];
+  const allow = input.allowGroups ? new Set(input.allowGroups) : undefined;
+
+  const desired = new Map<string, { title: string; members: Set<string> }>();
+  for (const person of input.people) {
+    // Rule 3 — a deprovisioned person is not a member of anything, whatever their IdP groups say.
+    if (person.deprovisioned) continue;
+    const linkSet = directoryLinkSetId(input.provider, person.externalId);
+    for (const raw of person.groups) {
+      if (typeof raw !== "string" || raw.trim().length === 0) {
+        warnings.push(`directory person "${person.externalId}" carries an empty group name — skipped (fix the duplicate/blank group in the IdP).`);
+        continue;
+      }
+      // Rule 5 — outside the operator allowlist ⇒ this group does not sync. Matched on the verbatim
+      // IdP name (what the operator listed), before the `directory:` namespace is applied.
+      if (allow && !allow.has(raw)) continue;
+      const name = directoryGroupName(raw);
+      const entry = desired.get(name) ?? { title: raw, members: new Set<string>() };
+      entry.members.add(linkSet);
+      desired.set(name, entry);
+    }
+  }
+
+  const currentByName = new Map(input.current.groups.map((g) => [g.name, g]));
+  const steps: GroupSyncStep[] = [];
+
+  for (const name of [...desired.keys()].sort()) {
+    const want = desired.get(name)!;
+    const have = currentByName.get(name);
+    if (!have) {
+      steps.push({ kind: "add-group", group: name, title: want.title, members: want.members.size });
+      continue;
+    }
+    const haveSets = new Set(have.members.map((m) => (typeof m === "string" ? m : m.linkSet)));
+    for (const linkSet of [...want.members].sort()) if (!haveSets.has(linkSet)) steps.push({ kind: "add-member", group: name, linkSet });
+    for (const linkSet of [...haveSets].sort()) if (!want.members.has(linkSet)) steps.push({ kind: "remove-member", group: name, linkSet });
+  }
+
+  // DROPPED groups: in the overlay, gone from the directory. Rule 2 — planned, not applied.
+  for (const g of [...input.current.groups].sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!desired.has(g.name)) steps.push({ kind: "drop-group", group: g.name, members: g.members.length });
+  }
+
+  // A group whose every member left is DROPPED rather than emitted empty: an empty group grants
+  // nothing and `assertGroupsValid` refuses one, so emitting it would produce an overlay that cannot
+  // load.
+  const next: GroupsFile = {
+    groups: [...desired.entries()]
+      .filter(([, v]) => v.members.size > 0)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([name, v]): Group => ({ name, title: v.title, members: [...v.members].sort().map((linkSet) => ({ linkSet })) })),
+  };
+
+  return {
+    provider: input.provider,
+    people: input.people.length,
+    next,
+    steps,
+    warnings,
+    counts: {
+      addGroup: steps.filter((s) => s.kind === "add-group").length,
+      dropGroup: steps.filter((s) => s.kind === "drop-group").length,
+      addMember: steps.filter((s) => s.kind === "add-member").length,
+      removeMember: steps.filter((s) => s.kind === "remove-member").length,
+    },
+  };
+}
+
+/** The overlay file text this plan would have a human commit — the deliverable of `review` mode. */
+export function planOverlayContent(plan: GroupSyncPlan): string {
+  return emitGroupsModule(plan.next);
+}
+
+/** The env var that carries the operator's IdP-group allowlist (rule 5) — a comma-separated list of
+ *  VERBATIM IdP group names. Config-as-code by env, the OE_* idiom of OE_DIRECTORY_AUTOCONFIRM. */
+export const OE_DIRECTORY_GROUP_ALLOWLIST_ENV = "OE_DIRECTORY_GROUP_ALLOWLIST";
+
+/**
+ * Resolve the operator's IdP-group allowlist from the environment, at the caller's edge (never in
+ * the pure planner). Returns the parsed list, or `undefined` when unset/blank — which the planner
+ * reads as "sync every group" (the default, no behaviour change). Comma-separated, whitespace
+ * trimmed per entry, empty entries dropped; an all-blank value is undefined (an operator who sets it
+ * to "" or "," did not mean "sync nothing", which would be a silent, total narrowing — the safe read
+ * of a non-value is the default, and a real empty allowlist is expressed by not setting the var).
+ */
+export function directoryGroupAllowlist(env: NodeJS.ProcessEnv = process.env): readonly string[] | undefined {
+  const raw = env[OE_DIRECTORY_GROUP_ALLOWLIST_ENV]?.trim();
+  if (!raw) return undefined;
+  const names = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  return names.length > 0 ? names : undefined;
+}
+
+/** One human-readable line per step, for the control-plane response and the audit detail. */
+export function renderGroupPlan(plan: GroupSyncPlan): string[] {
+  return plan.steps.map((s) => {
+    switch (s.kind) {
+      case "add-group":
+        return `+ group "${s.group}" (${s.title}) with ${s.members} member(s)`;
+      case "drop-group":
+        return `- group "${s.group}" (had ${s.members} member(s)) — no longer in the directory`;
+      case "add-member":
+        // An admin reads this line before merging the overlay, so it states the live consequence: a linkSet membership is effective once merged, because the DM connector gate resolves through the awaitable expander (access/group-request.ts).
+        return `+ ${s.linkSet} → "${s.group}" (LIVE once merged — every CONFIRMED account of this link-set gets the group's bundle in its own DM)`;
+      case "remove-member":
+        return `- ${s.linkSet} from "${s.group}"`;
+    }
+  });
+}

package/agent/identity/groups-codemod.ts

@@ -0,0 +1,142 @@
+// The only writer of the IdP-group overlay (`agent/identity/groups.generated.ts`): a structural transformation of a plan from the pure diff in identity/group-sync.ts, byte-deterministic and idempotent, so the diff a human reviews was never model-authored.
+// Every overlay group carries the `directory:` prefix and every member is a `{ linkSet }` reference, never a principal key — that keeps the machine-owned and hand-written namespaces disjoint and defers every widening decision to resolve time, where only confirmed accounts count.
+
+import { overlayModuleHeader, unwrapOverlayModule, wrapOverlayModule, type OverlayModuleGrammar } from "../access/overlay-module.js";
+import { DIRECTORY_GROUP_PREFIX, isDirectoryGroupName, type Group } from "./groups.js";
+
+/** The IdP-group overlay file shape — data-only person-groups, nothing else. */
+export interface GroupsFile {
+  readonly groups: readonly Group[];
+}
+
+/** A codemod refusal — invalid file or an invariant breach. Distinct type so callers can tell
+ *  "refused by design" from an unexpected failure. */
+export class GroupsCodemodError extends Error {}
+
+export function emptyGroupsFile(): GroupsFile {
+  return { groups: [] };
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse + shape-check a groups overlay from unknown JSON. STRICT and fail-loud: unknown top-level
+ * keys, un-namespaced group names, unknown Group fields, and any member that is not a
+ * `{ linkSet: string }` all throw — the overlay is machine-written, so any deviation means a
+ * hand-edit went wrong, and a silently mis-parsed access-bearing overlay IS the security bug.
+ *
+ * Deep semantic validation (uniqueness, empty members, duplicate members) stays with
+ * `assertGroupsValid` on the MERGED result; this only pins the overlay-specific rules: shape, the
+ * `directory:` namespace, and the link-set-only member vocabulary.
+ */
+export function parseGroupsFile(value: unknown): GroupsFile {
+  if (!isRecord(value)) throw new GroupsCodemodError("groups overlay must be a JSON object with a `groups` array");
+  const keys = Object.keys(value).filter((k) => k !== "$comment");
+  const unknown = keys.filter((k) => k !== "groups");
+  if (unknown.length > 0) throw new GroupsCodemodError(`groups overlay has unknown top-level key(s): ${unknown.join(", ")}`);
+  if (!Array.isArray(value.groups)) throw new GroupsCodemodError("groups overlay needs a `groups` array (use [] when empty)");
+
+  const groups: Group[] = [];
+  for (const g of value.groups) {
+    if (!isRecord(g) || typeof g.name !== "string" || !isDirectoryGroupName(g.name)) {
+      throw new GroupsCodemodError(
+        `every overlay group needs a "${DIRECTORY_GROUP_PREFIX}"-prefixed name (got: ${JSON.stringify(isRecord(g) ? g.name : g)}) — that namespace is what keeps synced groups from colliding with hand-written ones`,
+      );
+    }
+    for (const k of Object.keys(g)) {
+      if (!["name", "title", "members"].includes(k)) {
+        throw new GroupsCodemodError(`overlay group "${g.name}" has field "${k}" — the overlay carries only name/title/members; put anything else in a hand-written group`);
+      }
+    }
+    if (g.title !== undefined && typeof g.title !== "string") throw new GroupsCodemodError(`overlay group "${g.name}" title must be a string`);
+    if (!Array.isArray(g.members)) throw new GroupsCodemodError(`overlay group "${g.name}" members must be an array`);
+    for (const m of g.members) {
+      // LINK-SET REFS ONLY. A principal key here would be a widening decision written into a file
+      // whose reviewer cannot verify it, and would bypass the confirmed-only rule — see the header.
+      if (!isRecord(m) || typeof m.linkSet !== "string" || m.linkSet.length === 0 || Object.keys(m).length !== 1) {
+        throw new GroupsCodemodError(`overlay group "${g.name}" has a member that is not a { linkSet: "<id>" } reference — the overlay never writes bare principal keys`);
+      }
+    }
+    groups.push(g as unknown as Group);
+  }
+  return { groups };
+}
+
+const GROUP_KEYS = ["name", "title", "members"];
+
+function orderKeys(obj: Record<string, unknown>, order: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of order) if (k in obj) out[k] = obj[k];
+  for (const k of Object.keys(obj).sort()) if (!(k in out)) out[k] = obj[k];
+  return out;
+}
+
+function canonicalGroup(g: Group): Record<string, unknown> {
+  const members = [...g.members]
+    .map((m) => (typeof m === "string" ? m : m.linkSet))
+    .sort()
+    .map((linkSet) => ({ linkSet }));
+  return orderKeys({ ...g, members }, GROUP_KEYS);
+}
+
+/**
+ * Canonical, byte-deterministic serialisation of the overlay's DATA: groups sorted by name, members
+ * sorted by link-set id, fixed key order, 2-space indent, trailing newline. This is the body
+ * {@link emitGroupsModule} wraps the module grammar around, and
+ * `emitGroupsModule(parseGroupsModule(emitGroupsModule(f))) === emitGroupsModule(f)`.
+ */
+export function stringifyGroups(file: GroupsFile): string {
+  const groups = [...file.groups].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalGroup);
+  return JSON.stringify({ groups }, null, 2) + "\n";
+}
+
+/** This overlay's fixed module grammar. Constants only: the emitted bytes depend on the data alone. */
+const GROUPS_MODULE: OverlayModuleGrammar = {
+  what: "person-groups overlay",
+  header: overlayModuleHeader("person-groups overlay", "packages/core/agent/identity/groups-codemod.ts"),
+  typeImport: 'import type { GroupsFile } from "@open-everywhere/core/agent/identity/groups-codemod.js";',
+  typeName: "GroupsFile",
+};
+
+export function emitGroupsModule(file: GroupsFile): string {
+  return wrapOverlayModule(GROUPS_MODULE, stringifyGroups(file));
+}
+
+/**
+ * Parse an overlay module's text, VERIFYING THE ROUND TRIP. Strip the grammar (refusing if it was
+ * touched at all), parse the data, then re-emit and demand the bytes come back identical — so a
+ * hand-edit that reorders keys, re-indents or leaves a stray field REFUSES here rather than being
+ * silently rewritten by the next plan, which would put a diff in front of a reviewer that they never
+ * authored.
+ */
+export function parseGroupsModule(text: string): GroupsFile {
+  const file = parseGroupsFile(unwrapOverlayModule(GROUPS_MODULE, text, (m) => new GroupsCodemodError(m)));
+  if (emitGroupsModule(file) !== text) {
+    throw new GroupsCodemodError(
+      "person-groups overlay is not in canonical form — re-emitting its own data does not reproduce the file, so it has been hand-edited. Run `npm run overlays:normalize` and commit the result (the codemod refuses to rewrite a file it did not write).",
+    );
+  }
+  return file;
+}
+
+/** LENIENT re-emit for `npm run overlays:normalize`: take whatever well-shaped data the module
+ *  carries and return the canonical module text. The only path allowed to accept a non-canonical
+ *  file — its whole job is to produce the canonical one. */
+export function renormalizeGroupsModule(text: string): string {
+  return emitGroupsModule(parseGroupsFile(unwrapOverlayModule(GROUPS_MODULE, text, (m) => new GroupsCodemodError(m))));
+}
+
+/**
+ * The overlay's own groups, recovered from a MERGED registry by filtering on the reserved namespace.
+ *
+ * 🔴 THIS IS ONLY CORRECT BECAUSE THE NAMESPACE IS ENFORCED AT BOTH ENDS: hand-written groups are
+ * refused the `directory:` prefix (`assertReservedGroupNamespace`) and overlay groups are required to
+ * carry it ({@link parseGroupsFile}), so "prefixed" and "from the overlay" are the same set. It
+ * exists so a DEPLOYED instance — which cannot read its own repo — can still diff the live overlay
+ * against a fresh directory snapshot without a second config seam carrying the same data twice.
+ */
+export function directoryGroupsOf(groups: readonly Group[]): GroupsFile {
+  return { groups: groups.filter((g) => isDirectoryGroupName(g.name)) };
+}

package/agent/identity/groups-delivery.ts

@@ -0,0 +1,156 @@
+// Bot-PR courier for the person-group overlay: it commits the planner's overlay to the config repo and opens or updates a PR whose merge IS the human approval.
+// Nothing takes effect on a running instance until that PR merges and the merged config redeploys; the path refuses loudly when no config repo is set, and a no-op plan opens no PR.
+
+import { getConfig, type AccessRequestsConfig } from "../access/config.js";
+import { GitHubContents, type CommitId } from "../scm/contents.js";
+import { createBranch, getBranchSha } from "../scm/refs.js";
+import { createOrUpdatePullRequest } from "../scm/pr.js";
+import { getGitHubApp } from "../scm/provider.js";
+import { resolveConfigRepoWriteToken } from "../scm/config-repo-token.js";
+import { isSafeBranchName } from "../scm/git.js";
+import { emitGroupsModule } from "./groups-codemod.js";
+import { groupPlanIsNoop, renderGroupPlan, type GroupSyncPlan } from "./group-sync.js";
+
+/** The default repo-relative path of the person-group overlay — the file the codemod owns. */
+const DEFAULT_GROUPS_OVERLAY_PATH = "agent/identity/groups.generated.ts";
+
+/** AccessRequestsConfig with the ONE field the group delivery needs PROVEN present. Unlike the
+ *  grants flow it does not require an admin channel — the group PR has no notification. */
+export type GroupsDeliveryConfig = AccessRequestsConfig & { readonly configRepo: string };
+
+/**
+ * The group-overlay delivery config, fail-closed: an absent loader or a missing config repo throws.
+ * Mirrors `requireAccessRequestsConfig` but demands only `configRepo` (no `adminChannel`) — a
+ * half-configured courier must refuse loudly, not silently do nothing on a control verb an admin
+ * expected to open a PR.
+ */
+export function requireGroupsDeliveryConfig(override?: AccessRequestsConfig): GroupsDeliveryConfig {
+  const cfg = override ?? getConfig().loadAccessRequests?.() ?? undefined;
+  if (!cfg?.configRepo) {
+    throw new Error(
+      "IdP group-overlay bot-PR delivery isn't configured on this deployment — an operator must set the config repo " +
+        "(AppConfig.loadAccessRequests; env OE_ACCESS_CONFIG_REPO). Until then, directory_groups_plan still returns the " +
+        "overlay content for an admin to commit by hand.",
+    );
+  }
+  return cfg as GroupsDeliveryConfig;
+}
+
+/** Injectable seams for {@link deliverGroupsOverlay} — every network edge and the config lookup, so
+ *  the whole path is offline-testable (scripts/groups-test.ts) with the live defaults used
+ *  byte-for-byte in production. Mirrors AccessRequestExecuteDeps, minus the Slack `post`. */
+export interface GroupsDeliveryDeps {
+  readonly config?: AccessRequestsConfig;
+  readonly contents?: Pick<GitHubContents, "getFile" | "putFile">;
+  readonly getBranchSha?: typeof getBranchSha;
+  readonly createBranch?: typeof createBranch;
+  readonly createPr?: typeof createOrUpdatePullRequest;
+  readonly resolveToken?: (repo: string) => Promise<string>;
+  readonly committer?: CommitId;
+}
+
+/** What the delivery did. `outcome:"no-op"` means the overlay already matched the directory and no
+ *  PR was opened; `committed` is whether a fresh overlay commit landed (false on a re-run whose
+ *  branch already carries the identical bytes). */
+export interface GroupsDeliveryOutcome {
+  readonly outcome: "no-op" | "opened" | "updated";
+  readonly repo: string;
+  readonly branch: string;
+  readonly committed: boolean;
+  readonly pr?: { readonly number: number; readonly url: string };
+  readonly note: string;
+}
+
+/**
+ * The PR body — code-rendered from the machine-computed plan, NO model text at any point. Unlike the
+ * grants flow's body there is no `reason`/`universe` to sanitise: a group-sync plan is a pure diff
+ * of the directory against the overlay (`renderGroupPlan`), so every line here is either that diff or
+ * a host-authored constant. The doctrine footer states why merging is safe to reason about.
+ */
+export function groupsPrBody(plan: GroupSyncPlan): string {
+  const diff = renderGroupPlan(plan);
+  return [
+    `Sync the person-group overlay against the \`${plan.provider}\` directory.`,
+    "",
+    `${plan.people} directory person(s) diffed — ${plan.counts.addGroup} group(s) added, ${plan.counts.dropGroup} dropped, ` +
+      `${plan.counts.addMember} member(s) added, ${plan.counts.removeMember} removed.`,
+    "",
+    ...(diff.length ? diff : ["(no changes)"]),
+    ...(plan.warnings.length ? ["", "Warnings (the planner refused to act on these):", ...plan.warnings.map((w) => `- ${w}`)] : []),
+    "",
+    "---",
+    "This diff was produced by the deterministic person-group codemod from a directory snapshot — no model authored any",
+    "part of it. The groups are `directory:`-namespaced (they cannot collide with hand-written ones) and every member is a",
+    "link-set reference, so a person contributes only the accounts they have CONFIRMED. Merging this PR IS the approval:",
+    "the memberships take effect on the next deploy of the merged config. Closing it unmerged declines the sync.",
+    "See docs/how-it-works/access-and-scoping.md.",
+  ].join("\n");
+}
+
+/**
+ * Delivers the plan's overlay as a bot-PR, and touches the SCM plane not at all when the plan changes nothing.
+ * The branch is directory-groups/<provider> and is STABLE, not per-run, so a re-run updates the same PR, and the overlay commit lands only when the bytes differ.
+ */
+export async function deliverGroupsOverlay(plan: GroupSyncPlan, deps: GroupsDeliveryDeps = {}): Promise<GroupsDeliveryOutcome> {
+  const cfg = requireGroupsDeliveryConfig(deps.config);
+  const repo = cfg.configRepo;
+  const base = cfg.configBase ?? "main";
+  const groupsPath = cfg.groupsPath ?? DEFAULT_GROUPS_OVERLAY_PATH;
+  const branch = `directory-groups/${plan.provider}`;
+  if (!isSafeBranchName(branch)) {
+    // provider.id is a stable, operator-controlled token ("okta"); this only fires on a garbage one.
+    throw new Error(`unsafe directory-groups branch name "${branch}" (from provider id "${plan.provider}")`);
+  }
+
+  if (groupPlanIsNoop(plan)) {
+    return {
+      outcome: "no-op",
+      repo,
+      branch,
+      committed: false,
+      note: "the overlay already matches the directory — no PR opened.",
+    };
+  }
+
+  const overlayContent = emitGroupsModule(plan.next);
+  const token = await (deps.resolveToken ?? resolveConfigRepoWriteToken)(repo);
+  const contents = deps.contents ?? new GitHubContents();
+  const refSha = deps.getBranchSha ?? getBranchSha;
+  const mkBranch = deps.createBranch ?? createBranch;
+  const openPr = deps.createPr ?? createOrUpdatePullRequest;
+
+  let branchSha = await refSha({ repo, branch, token });
+  if (branchSha === null) {
+    const baseSha = await refSha({ repo, branch: base, token });
+    if (baseSha === null) throw new Error(`config repo ${repo} has no base branch "${base}" — check accessRequests.configBase.`);
+    await mkBranch({ repo, branch, sha: baseSha, token });
+    branchSha = baseSha;
+  }
+
+  // The codemod emits byte-stable output, so comparing the committed bytes is an honest test for a real change rather than a formatting artefact.
+  const existing = await contents.getFile(repo, groupsPath, branch, token);
+  let committed = false;
+  if (!existing || existing.content !== overlayContent) {
+    const committer = deps.committer ?? getGitHubApp()?.committer() ?? { name: "open-everywhere[bot]", email: "open-everywhere@users.noreply.github.com" };
+    await contents.putFile(repo, groupsPath, overlayContent, `directory group sync: ${plan.provider}`, branch, token, committer, existing?.sha);
+    committed = true;
+  }
+
+  const pr = await openPr({
+    repo,
+    head: branch,
+    base,
+    title: `Directory group sync: ${plan.provider}`,
+    body: groupsPrBody(plan),
+    token,
+  });
+
+  return {
+    outcome: pr.updated ? "updated" : "opened",
+    repo,
+    branch,
+    committed,
+    pr: { number: pr.number, url: pr.url },
+    note: `${pr.updated ? "updated" : "opened"} PR #${pr.number} — ${pr.url}; an admin merges it in GitHub to apply the group overlay (nothing takes effect until they do).`,
+  };
+}