@ai-matrx/auth 0.2.0 → 0.2.2

package/dist/organizations.d.ts

@@ -1,227 +1,5 @@
-import { SupabaseClient } from '@supabase/supabase-js';
-import { A as AuthClient } from './session-DdQiStp6.js';
-
-/**
- * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
- * facts, for every Matrx client (the web, Matrx 2, the extension, Studio).
- *
- * 🚨 ONE ACTIVE ORGANIZATION, SET ONCE WHEN THE APP LOADS, NEVER NONE (Arman, 2026-10-07;
- * organizations STATE rules 10–15). The ladder picks what the UI OPENS to; from then on every
- * request carries the one active organization the person can see. Reads never filter by it.
- *
- * THE RUNGS, each kept only if it is a CURRENT membership:
- *   1. HELD     — what this tab (web) or this running app (desktop, in memory) already works in;
- *   2. LAST ACTIVE — `users.user_preferences.last_active_organization_id` (follows the person
- *                 across devices: STATE rule 12);
- *   3. START-UP — `users.user_preferences.startup_organization_id` (the "Start-up organization"
- *                 setting);
- *   4. FIRST    — the oldest active membership.
- * Zero memberships → null. A failed read THROWS (the host shows "could not check" and a retry,
- * never a guess). The ladder's own answer never writes anything (rule 14): only a person's click
- * writes last active.
- *
- * Hosts with extra rungs keep them (the web's `?org=` link rung) and call the pure core here.
- */
-
-/** One organization the person is an active member of, as every picker draws it. */
-interface OrganizationMembership {
-    readonly id: string;
-    readonly name: string;
-    readonly slug: string | null;
-    /** The database-validated 2–3 letters, when the organization has them. */
-    readonly abbreviation: string | null;
-    readonly logoUrl: string | null;
-    /** owner | admin | member (the membership's role). */
-    readonly role: string;
-    /** The person created it (drawn under the favourites, before the rest). */
-    readonly isOwn: boolean;
-    /** Classified in `iam.organizations.settings.test_fixture` — never guessed from a name. */
-    readonly isTestFixture: boolean;
-    /** When the membership began (ISO): the oldest is rung 4. */
-    readonly joinedAt: string;
-}
-interface AccountOrganizationChoices {
-    readonly lastActiveOrganizationId: string | null;
-    readonly startupOrganizationId: string | null;
-}
-type OrganizationRung = "held" | "last-active" | "startup" | "first";
-interface ResolvedOrganization<T extends {
-    id: string;
-}> {
-    readonly organization: T;
-    /** Which rung answered (for logs and tests; never shown as a choice). */
-    readonly rung: OrganizationRung;
-}
-interface LadderInput<T extends {
-    id: string;
-}> {
-    readonly memberships: readonly T[];
-    readonly held?: string | null;
-    readonly account?: AccountOrganizationChoices | null;
-    /** Rung 4: the oldest active membership. Omitted: the oldest by `joinedAt`, else the first given. */
-    readonly first?: T | null;
-}
-/**
- * THE LADDER. Pure: no read, no write. Null only when there are no memberships.
- */
-declare function resolveActiveOrganization<T extends {
-    id: string;
-    joinedAt?: string;
-}>(input: LadderInput<T>): ResolvedOrganization<T> | null;
-/**
- * The ladder with its reads deferred: the account's choices are read only when no held
- * organization answers, and the first membership only when nothing else does. A failed read
- * throws through.
- */
-declare function resolveActiveOrganizationLazily<T extends {
-    id: string;
-    joinedAt?: string;
-}>(input: {
-    readonly memberships: readonly T[];
-    readonly held?: string | null;
-    readonly readAccount: () => Promise<AccountOrganizationChoices>;
-    readonly first?: () => Promise<T | null>;
-}): Promise<ResolvedOrganization<T> | null>;
-/** The oldest membership by `joinedAt` (ties and missing dates keep the given order). */
-declare function oldestMembership<T extends {
-    joinedAt?: string;
-}>(memberships: readonly T[]): T | null;
-/**
- * THE ORDER every organization list uses (the shared OrganizationPicker's): favourites, then the
- * person's own organizations, then the rest; inside each band the given order is kept.
- */
-declare function orderOrganizations<T extends {
-    id: string;
-    isOwn?: boolean;
-}>(organizations: readonly T[], favouriteIds: readonly string[]): T[];
-/** Search over the two things a person types: the name and the abbreviation. */
-declare function organizationMatches(org: {
-    name: string;
-    abbreviation?: string | null;
-}, query: string): boolean;
-/** Any supabase-js client (typed or not). */
-type OrganizationsDb = SupabaseClient<any, any, any>;
-/**
- * Every organization the signed-in person is an ACTIVE member of (archived organizations left
- * out), through the canonical membership door (`mbr_for_user`, paged) and the organizations'
- * own rows. Throws when either read fails; [] when there are none. Ordered by name.
- */
-declare function readMemberships(db: OrganizationsDb, userId: string): Promise<OrganizationMembership[]>;
-interface ChoicesRow {
-    last_active_organization_id: string | null;
-    startup_organization_id: string | null;
-}
-/** The two columns as the ladder's input. A person with no preferences row has neither. */
-declare function toAccountOrganizationChoices(row: Partial<ChoicesRow> | null | undefined): AccountOrganizationChoices;
-/**
- * The account's last active and start-up organizations. 🚨 ONLY THE LADDER READS THESE: they
- * choose what the shell opens to and nothing else. Throws when the read fails.
- */
-declare function readAccountOrganizationChoices(db: OrganizationsDb, userId: string): Promise<AccountOrganizationChoices>;
-/** Save where the person now works, for their next load on any device. Only a click calls this. Throws on refusal. */
-declare function writeLastActiveOrganization(db: OrganizationsDb, organizationId: string): Promise<void>;
-/** Set (or clear, with null) the Start-up organization setting. Throws on refusal. */
-declare function writeStartupOrganization(db: OrganizationsDb, organizationId: string | null): Promise<void>;
-/** The favourites store's entity type (`platform.user_entity_state`). */
-declare const ORGANIZATION_ENTITY_TYPE = "organization";
-/**
- * The person's favourite organizations: the platform's per-person flag store
- * (`public.ues_list`, kind favorite), the same store agent and model favourites use. Throws on
- * failure.
- */
-declare function readOrganizationFavourites(db: OrganizationsDb): Promise<string[]>;
-/** Star (true) or unstar (false) one organization. `ues_set` refuses one the person cannot open. Throws on refusal. */
-declare function setOrganizationFavourite(db: OrganizationsDb, organizationId: string, favourite: boolean): Promise<void>;
-/**
- * What the AI Matrx server's refusal of a request's organization means for the ladder
- * (`matrx_connect` AuthMiddleware._organization_admission_words via `organization_free.py`):
- *   - 400 with `detail.organization_admission` "denied" (not a member), "unknown" (no such
- *     organization) or "archived" → the organization is gone for this person: re-run the ladder;
- *   - 503 with "unverifiable" (the lookup failed; Retry-After 5) → keep it and retry;
- *   - anything else → not an organization refusal.
- */
-type OrganizationRefusal = "lapsed" | "retry" | null;
-declare function classifyOrganizationRefusal(status: number, body: unknown): OrganizationRefusal;
-
-/**
- * THE ACTIVE ORGANIZATION — one per tab / running app, set once when the app loads, never none
- * while the person has a membership (Arman, 2026-10-07; organizations STATE rules 10–15).
- *
- *   const active = createActiveOrganization({ client: supabase });
- *   await active.load();                       // the ladder: held → last active → start-up → first
- *   const orgId = await active.ensureOrgId();  // HELD until the ladder answers; never a guess
- *   await active.switchTo(otherId);            // a person's click: saves last active for next load
- *
- * HELD-REQUEST SEMANTICS. A write or server call that needs the organization asks
- * `ensureOrgId()`: while the ladder is still resolving the call WAITS (it is held, never sent
- * without an organization and never sent with a guessed one); once resolved it gets the one
- * active organization; with zero memberships or a failed read it is REFUSED with a named error.
- * Acting on a record passes that record's own organization (`ensureOrgId(record.organization_id)`),
- * which wins and never switches the active one.
- *
- * 🚨 NEVER A LIST FILTER. Reads show everything the person can see across all their
- * organizations; nothing here narrows a read. The active organization is only where new things
- * are saved and which organization a server call runs in.
- *
- * The held id is identity-keyed: a different person signing in on the same device never inherits
- * the last person's organization, and a sign-out resets the store.
- */
-
-/** Where this tab / app remembers its organization between reloads (identity-keyed). */
-interface HeldOrganizationStore {
-    read(userId: string): string | null | Promise<string | null>;
-    write(userId: string, organizationId: string): void | Promise<void>;
-    clear(): void | Promise<void>;
-}
-type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
-interface ActiveOrganizationSnapshot {
-    readonly status: ActiveOrganizationStatus;
-    readonly userId: string | null;
-    readonly organizationId: string | null;
-    readonly organization: OrganizationMembership | null;
-    readonly memberships: readonly OrganizationMembership[];
-    /** Which ladder rung answered (or "switched" after a person's click). */
-    readonly rung: OrganizationRung | "switched" | null;
-    readonly error: string | null;
-}
-declare class NoActiveOrganizationError extends Error {
-    readonly reason: "signed-out" | "no-memberships" | "unreadable";
-    constructor(reason: "signed-out" | "no-memberships" | "unreadable", detail?: string);
-}
-declare class NotAMemberError extends Error {
-    readonly organizationId: string;
-    constructor(organizationId: string);
-}
-interface ActiveOrganization {
-    snapshot(): ActiveOrganizationSnapshot;
-    subscribe(listener: () => void): () => void;
-    /** Run the ladder (again). Resolves with the settled snapshot; never throws. */
-    load(): Promise<ActiveOrganizationSnapshot>;
-    /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
-    current(): string | null;
-    /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
-    ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
-    /** A person's click: switch, remember for this tab, save as last active for the next load. */
-    switchTo(organizationId: string): Promise<void>;
-    /** Feed a server refusal in: a lapsed organization re-runs the ladder. Returns the class. */
-    handleRefusal(status: number, body: unknown): Promise<"lapsed" | "retry" | null>;
-    dispose(): void;
-}
-interface CreateActiveOrganizationOptions {
-    /** The person's Supabase client (any supabase-js client). */
-    readonly client: OrganizationsDb & AuthClient;
-    /** Where this tab/app holds its choice. Default: browser `sessionStorage` (per tab), else memory. */
-    readonly held?: HeldOrganizationStore | undefined;
-    /** An extra first rung (the web's `?org=` link). Kept only if it is a current membership. */
-    readonly linked?: (() => string | null | undefined) | undefined;
-    /** Load as soon as it is created (default true). */
-    readonly autoLoad?: boolean | undefined;
-}
-/** A held store over a `Storage` (browser `sessionStorage` = per tab), identity-keyed. */
-declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore;
-/** Held in memory: the running app's own choice (desktop, scripts, tests). */
-declare function memoryHeldOrganization(): HeldOrganizationStore;
-declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
+export { h as AccountOrganizationChoices, j as ActiveOrganization, k as ActiveOrganizationSnapshot, l as ActiveOrganizationStatus, m as AdminSeat, n as AdminSeatInput, p as ArchiveFilter, C as CreateActiveOrganizationOptions, H as HeldOrganizationStore, L as LINK_ORGANIZATION_QUERY_KEY, q as LadderInput, t as LinkOrganizationDecision, v as LinkOrganizationDecisionInput, w as LinkOrganizationMembership, x as LinkOrganizationMessages, y as LinkOrganizationParam, N as NOT_A_MEMBER_RECHECK_GAP_MS, z as NoActiveOrganizationError, B as NotAMemberError, D as NotAMemberRefusalNotice, O as ORGANIZATION_ENTITY_TYPE, E as ORGANIZATION_RESOLUTION_TIMEOUT_MS, F as OrganizationBootstrapGate, G as OrganizationMembership, I as OrganizationRefusal, J as OrganizationRung, K as OrganizationsDb, P as ParentOrganization, R as ReadMembershipsOptions, M as ResolveWithLinkInput, Q as ResolvedOrganization, T as ResolvedWithLink, V as adminSeatReplacesUserContext, W as classifyLinkOrganizationValue, X as classifyOrganizationRefusal, Y as createActiveOrganization, Z as createNotAMemberRefusalNotice, _ as createOrganizationBootstrapGate, $ as decideLinkOrganization, a0 as isNotAMemberRefusal, a1 as linkOrganizationMalformedMessage, a2 as linkOrganizationNotAMemberMessage, a3 as linkOrganizationOfferMessage, a4 as linkOrganizationSwitchAnnouncement, a5 as memoryHeldOrganization, a6 as oldestMembership, a7 as orderOrganizations, a8 as organizationMatches, a9 as readAccountOrganizationChoices, aa as readLinkOrganizationParam, ab as readMemberships, ac as readOrganizationFavourites, ad as resolveActiveOrganization, ae as resolveActiveOrganizationLazily, af as resolveAdminSeat, ag as resolveChildOrganizationId, ah as resolveOrganizationWithLink, ai as setOrganizationFavourite, aj as storageHeldOrganization, ak as toAccountOrganizationChoices, al as writeLastActiveOrganization, am as writeStartupOrganization } from './active-organization-Dy4UtiyR.js';
+import '@supabase/supabase-js';
 
 /**
  * "This request needs an organization and names none" — the ONE recogniser, the server's throwable
@@ -329,4 +107,4 @@ declare function organizationRequiredEnvelope(error: OrganizationRequiredServerE
 /** The standard `Response` (status 400) a route answers the refusal with — no framework needed. */
 declare function organizationRequiredResponse(error: OrganizationRequiredServerError): Response;
 
-export { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type CreateActiveOrganizationOptions, type HeldOrganizationStore, type LadderInput, MEMBERSHIPS_URL, type MembershipReadClient, NoActiveOrganizationError, NotAMemberError, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_ENTITY_TYPE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembership, type OrganizationMembershipSummary, type OrganizationRefusal, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationRung, type OrganizationsDb, type ResolvedOrganization, classifyOrganizationRefusal, createActiveOrganization, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readAccountOrganizationChoices, readCallerMemberships, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };
+export { MEMBERSHIPS_URL, type MembershipReadClient, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readCallerMemberships };

package/dist/organizations.js

@@ -45,7 +45,8 @@ function organizationMatches(org, query) {
 }
 var MEMBERSHIP_PAGE = 500;
 var ID_CHUNK = 100;
-async function readMemberships(db, userId) {
+async function readMemberships(db, userId, options = {}) {
+  const filter = options.archived ?? "active";
   const memberships = [];
   for (let from = 0; ; from += MEMBERSHIP_PAGE) {
     const { data, error } = await db.rpc("mbr_for_user", { p_container_type: "organization" }).order("id", { ascending: true }).range(from, from + MEMBERSHIP_PAGE - 1);
@@ -68,7 +69,7 @@ async function readMemberships(db, userId) {
     if (error) throw new Error(`Your organizations could not be read: ${error.message}`);
     rows.push(...data ?? []);
   }
-  return rows.filter((r) => !r.archived_at).map((r) => {
+  return rows.filter((r) => filter === "all" ? true : filter === "archived" ? !!r.archived_at : !r.archived_at).map((r) => {
     const m = active.get(r.id);
     const settings = r.settings && typeof r.settings === "object" ? r.settings : {};
     return {
@@ -80,7 +81,8 @@ async function readMemberships(db, userId) {
       role: m?.role ?? "member",
       isOwn: !!r.created_by && r.created_by === userId,
       isTestFixture: settings["test_fixture"] === true,
-      joinedAt: m?.created_at ?? ""
+      joinedAt: m?.created_at ?? "",
+      archivedAt: r.archived_at ?? null
     };
   }).sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -181,6 +183,209 @@ function onSessionChange(client, cb) {
   return () => data.subscription.unsubscribe();
 }
 
+// src/organization-gate.ts
+var ORGANIZATION_RESOLUTION_TIMEOUT_MS = 1e4;
+function createOrganizationBootstrapGate(defaultTimeoutMs = ORGANIZATION_RESOLUTION_TIMEOUT_MS) {
+  let settled = false;
+  let announce = null;
+  let resolution = new Promise((resolve) => {
+    announce = resolve;
+  });
+  return {
+    isResolved: () => settled,
+    markResolved() {
+      if (settled) return;
+      settled = true;
+      announce?.();
+    },
+    async whenResolved(timeoutMs = defaultTimeoutMs) {
+      if (settled) return;
+      let timer;
+      await Promise.race([
+        resolution,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, timeoutMs);
+        })
+      ]);
+      if (timer !== void 0) clearTimeout(timer);
+    },
+    reset() {
+      announce?.();
+      settled = false;
+      resolution = new Promise((resolve) => {
+        announce = resolve;
+      });
+    }
+  };
+}
+var NOT_A_MEMBER_CODES = /* @__PURE__ */ new Set(["organization_forbidden", "organization_not_member"]);
+function isNotAMemberRefusal(body) {
+  if (!body || typeof body !== "object") return false;
+  const record = body;
+  if (typeof record.code === "string" && NOT_A_MEMBER_CODES.has(record.code)) return true;
+  const detail = record.detail;
+  return !!detail && typeof detail === "object" && typeof detail.code === "string" && NOT_A_MEMBER_CODES.has(detail.code);
+}
+var NOT_A_MEMBER_RECHECK_GAP_MS = 3e4;
+function createNotAMemberRefusalNotice(recheck, gapMs = NOT_A_MEMBER_RECHECK_GAP_MS) {
+  let last = Number.NEGATIVE_INFINITY;
+  return {
+    notice(body, now = Date.now()) {
+      if (!isNotAMemberRefusal(body)) return false;
+      if (now - last < gapMs) return false;
+      last = now;
+      recheck();
+      return true;
+    },
+    reset() {
+      last = Number.NEGATIVE_INFINITY;
+    }
+  };
+}
+function resolveChildOrganizationId(parent, explicit, label = "child record", onDisagree = (m) => console.warn(m)) {
+  const parentOrg = typeof parent === "string" ? parent : parent?.organization_id ?? null;
+  if (parentOrg) {
+    if (explicit && explicit !== parentOrg) {
+      onDisagree(`[child org] ${label} filed in its parent's organization ${parentOrg}, not ${explicit} \u2014 a child belongs with its parent.`);
+    }
+    return parentOrg;
+  }
+  return explicit ?? null;
+}
+function resolveAdminSeat(input) {
+  if (!input || input.laneOpen !== true || !input.organizationId) return null;
+  return { id: input.organizationId, name: input.organizationName ?? null };
+}
+function adminSeatReplacesUserContext(input, personOrganizationId) {
+  const seat = resolveAdminSeat(input);
+  return seat !== null && seat.id !== (personOrganizationId ?? null);
+}
+
+// src/organization-link.ts
+import { isRfc4122Uuid } from "@ai-matrx/kit/uuid";
+var LINK_ORGANIZATION_QUERY_KEY = "org";
+var SLUG = /^[a-z0-9][a-z0-9-]{0,99}$/i;
+function classifyLinkOrganizationValue(raw) {
+  const value = raw.trim();
+  if (isRfc4122Uuid(value)) return { kind: "named", organizationId: value };
+  if (SLUG.test(value)) return { kind: "addressed", slug: value.toLowerCase() };
+  return { kind: "malformed", raw: value };
+}
+function readLinkOrganizationParam(source) {
+  if (source == null) return { kind: "absent" };
+  let params;
+  if (source instanceof URLSearchParams) {
+    params = source;
+  } else {
+    try {
+      const q = source.includes("?") ? source.slice(source.indexOf("?")) : source;
+      params = new URLSearchParams(q);
+    } catch {
+      return { kind: "absent" };
+    }
+  }
+  if (!params.has(LINK_ORGANIZATION_QUERY_KEY)) return { kind: "absent" };
+  return classifyLinkOrganizationValue(params.get(LINK_ORGANIZATION_QUERY_KEY) ?? "");
+}
+function linkOrganizationNotAMemberMessage(signedInAs) {
+  const account = signedInAs ? `You are signed in as ${signedInAs}.` : "Check which account you are signed in as.";
+  return `The link you followed is for an organization this account is not a member of, so nothing was opened and you were not moved. ${account} Sign in with the account the link was meant for, or ask whoever sent it to give this account access.`;
+}
+function linkOrganizationMalformedMessage(raw) {
+  const quoted = raw.length > 0 ? ` ("${raw}")` : "";
+  return `The link you followed names an organization we cannot read${quoted}, so nothing was switched and you were left where you were. Ask whoever sent it for the link again, or pick the organization you are working in from the avatar menu.`;
+}
+function linkOrganizationSwitchAnnouncement(toName, fromName) {
+  const from = fromName ? ` You were working in ${fromName}.` : "";
+  return `You are now working in ${toName} because the link you followed is filed under it.${from} Switch back any time from the avatar menu.`;
+}
+function linkOrganizationOfferMessage(toName, fromName) {
+  const where = fromName ? `, and you are working in ${fromName}` : "";
+  return `The link you followed is for ${toName}${where}. "Switch organization when a link asks" is turned off in your settings, so nothing changed \u2014 switch to ${toName} to open it.`;
+}
+function decideLinkOrganization(input) {
+  const { param, memberships, currentOrganizationId } = input;
+  const switchWhenALinkAsks = input.switchWhenALinkAsks ?? true;
+  const say = {
+    notAMember: linkOrganizationNotAMemberMessage,
+    malformed: linkOrganizationMalformedMessage,
+    switched: linkOrganizationSwitchAnnouncement,
+    offer: linkOrganizationOfferMessage,
+    offerAction: (name) => `Switch to ${name}`,
+    ...input.messages
+  };
+  if (param.kind === "absent") return { kind: "no-link" };
+  if (param.kind === "malformed") {
+    return {
+      kind: "refused",
+      reason: "malformed",
+      message: say.malformed(param.raw)
+    };
+  }
+  const match = param.kind === "named" ? memberships.find((o) => o.id === param.organizationId) : memberships.find((o) => o.slug?.trim().toLowerCase() === param.slug);
+  if (!match && param.kind === "named" && input.admittedByAShare) {
+    return { kind: "admitted", organizationId: param.organizationId };
+  }
+  if (!match) {
+    return {
+      kind: "refused",
+      reason: "not-a-member",
+      message: say.notAMember(input.signedInAs)
+    };
+  }
+  if (currentOrganizationId === match.id) {
+    return { kind: "already-current", organizationId: match.id };
+  }
+  const fromName = currentOrganizationId ? input.currentOrganizationName ?? memberships.find((o) => o.id === currentOrganizationId)?.name ?? null : null;
+  if (currentOrganizationId && !switchWhenALinkAsks) {
+    return {
+      kind: "offered",
+      organizationId: match.id,
+      organizationName: match.name,
+      message: say.offer(match.name, fromName),
+      actionLabel: say.offerAction(match.name)
+    };
+  }
+  return {
+    kind: "honoured",
+    organizationId: match.id,
+    organizationName: match.name,
+    // Nothing to announce on a cold arrival: they were working nowhere, so
+    // they were not moved. A move, however, is always announced.
+    announcement: currentOrganizationId ? say.switched(match.name, fromName) : null
+  };
+}
+async function resolveOrganizationWithLink(input) {
+  const ladder = await resolveActiveOrganizationLazily({
+    memberships: input.memberships,
+    held: input.held ?? null,
+    readAccount: input.readAccount,
+    ...input.first ? { first: input.first } : {}
+  });
+  if (!ladder) return null;
+  const param = typeof input.link === "string" ? input.link.includes("=") ? readLinkOrganizationParam(input.link) : classifyLinkOrganizationValue(input.link) : readLinkOrganizationParam(input.link ?? null);
+  const decisionInput = {
+    param,
+    memberships: input.memberships.map((o) => ({ id: o.id, name: o.name, slug: o.slug ?? null })),
+    currentOrganizationId: ladder.organization.id,
+    currentOrganizationName: ladder.organization.name,
+    ...input.switchWhenALinkAsks === void 0 ? {} : { switchWhenALinkAsks: input.switchWhenALinkAsks },
+    ...input.signedInAs === void 0 ? {} : { signedInAs: input.signedInAs },
+    ...input.messages ? { messages: input.messages } : {}
+  };
+  let link = decideLinkOrganization(decisionInput);
+  if (link.kind === "refused" && link.reason === "not-a-member" && param.kind === "named" && input.admittedByAShare) {
+    if (await input.admittedByAShare(param.organizationId)) {
+      link = decideLinkOrganization({ ...decisionInput, admittedByAShare: true });
+    }
+  }
+  if (link.kind === "honoured") {
+    const organization = input.memberships.find((m) => m.id === link.organizationId);
+    if (organization) return { organization, rung: "link", link };
+  }
+  return { organization: ladder.organization, rung: ladder.rung, link };
+}
+
 // src/active-organization.ts
 var NoActiveOrganizationError = class extends Error {
   constructor(reason, detail) {
@@ -258,6 +463,7 @@ function createActiveOrganization(options) {
   const publish = (next) => {
     current = Object.freeze(next);
     if (current.status !== "resolving" && current.status !== "idle") {
+      options.bootstrapGate?.markResolved();
       const ready = waiters;
       waiters = [];
       for (const w of ready) w();
@@ -275,19 +481,38 @@ function createActiveOrganization(options) {
       }
       const memberships = await readMemberships(client, person.id);
       if (gen !== generation) return current;
-      const linked = options.linked?.() ?? null;
-      const heldId = (linked && memberships.some((m) => m.id === linked) ? linked : null) ?? await held.read(person.id);
-      const resolved = await resolveActiveOrganizationLazily({
-        memberships,
-        held: heldId,
-        readAccount: () => readAccountOrganizationChoices(client, person.id)
-      });
+      const linkOptions = options.link;
+      let resolved;
+      let linkDecision = null;
+      if (linkOptions) {
+        const r = await resolveOrganizationWithLink({
+          memberships,
+          held: await held.read(person.id),
+          readAccount: () => readAccountOrganizationChoices(client, person.id),
+          link: linkOptions.source() ?? null,
+          switchWhenALinkAsks: linkOptions.switchWhenALinkAsks?.(),
+          signedInAs: linkOptions.signedInAs?.(),
+          messages: linkOptions.messages,
+          admittedByAShare: linkOptions.admittedByAShare
+        });
+        resolved = r;
+        linkDecision = r?.link ?? null;
+      } else {
+        const linked = options.linked?.() ?? null;
+        const heldId = (linked && memberships.some((m) => m.id === linked) ? linked : null) ?? await held.read(person.id);
+        resolved = await resolveActiveOrganizationLazily({
+          memberships,
+          held: heldId,
+          readAccount: () => readAccountOrganizationChoices(client, person.id)
+        });
+      }
       if (gen !== generation) return current;
       if (!resolved) {
         publish({ ...IDLE, status: "none", userId: person.id, error: "no-memberships" });
         return current;
       }
       await held.write(person.id, resolved.organization.id);
+      if (linkDecision && linkDecision.kind !== "no-link") options.link?.onDecision?.(linkDecision);
       publish({
         status: "ready",
         userId: person.id,
@@ -323,6 +548,11 @@ function createActiveOrganization(options) {
     const userId = session.user?.id ?? null;
     if (event === "SIGNED_IN" && userId !== current.userId) void load();
   });
+  const seatFor = (snap) => {
+    const seat = resolveAdminSeat(options.adminSeat?.());
+    return seat && snap.memberships.some((m) => m.id === seat.id) ? seat.id : null;
+  };
+  let lastNotAMemberRecheck = Number.NEGATIVE_INFINITY;
   const settled = async () => {
     if (current.status === "idle") return load();
     if (current.status === "resolving") {
@@ -339,11 +569,11 @@ function createActiveOrganization(options) {
       };
     },
     load,
-    current: () => current.status === "ready" ? current.organizationId : null,
+    current: () => current.status === "ready" ? seatFor(current) ?? current.organizationId : null,
     async ensureOrgId(recordOrganizationId) {
       if (recordOrganizationId) return recordOrganizationId;
       const snap = await settled();
-      if (snap.status === "ready" && snap.organizationId) return snap.organizationId;
+      if (snap.status === "ready" && snap.organizationId) return seatFor(snap) ?? snap.organizationId;
       if (snap.status === "error") throw new NoActiveOrganizationError("unreadable", snap.error ?? void 0);
       throw new NoActiveOrganizationError(snap.error === "signed-out" ? "signed-out" : "no-memberships");
     },
@@ -358,7 +588,16 @@ function createActiveOrganization(options) {
       await writeLastActiveOrganization(client, organizationId);
     },
     async handleRefusal(status, body) {
-      const kind = classifyOrganizationRefusal(status, body);
+      let kind = classifyOrganizationRefusal(status, body);
+      if (kind === null && isNotAMemberRefusal(body)) {
+        const now = Date.now();
+        if (now - lastNotAMemberRecheck >= (options.refusalRecheckGapMs ?? NOT_A_MEMBER_RECHECK_GAP_MS)) {
+          lastNotAMemberRecheck = now;
+          kind = "lapsed";
+        } else {
+          return null;
+        }
+      }
       if (kind === "lapsed") {
         if (current.userId) await held.clear();
         await load();
@@ -460,20 +699,33 @@ function organizationRequiredResponse(error) {
   return Response.json(organizationRequiredEnvelope(error), { status: 400 });
 }
 export {
+  LINK_ORGANIZATION_QUERY_KEY,
   MEMBERSHIPS_URL,
+  NOT_A_MEMBER_RECHECK_GAP_MS,
   NoActiveOrganizationError,
   NotAMemberError,
   ORGANIZATION_CONTEXT_REQUIRED_CODE,
   ORGANIZATION_ENTITY_TYPE,
   ORGANIZATION_REQUIRED_CODE,
   ORGANIZATION_REQUIRED_WIRE_CODE,
+  ORGANIZATION_RESOLUTION_TIMEOUT_MS,
   OrganizationRequiredServerError,
+  adminSeatReplacesUserContext,
+  classifyLinkOrganizationValue,
   classifyOrganizationRefusal,
   createActiveOrganization,
+  createNotAMemberRefusalNotice,
+  createOrganizationBootstrapGate,
+  decideLinkOrganization,
   extractOrganizationHoldMemberships,
+  isNotAMemberRefusal,
   isOrganizationRequiredEnvelope,
   isOrganizationRequiredError,
   isOrganizationRequiredServerError,
+  linkOrganizationMalformedMessage,
+  linkOrganizationNotAMemberMessage,
+  linkOrganizationOfferMessage,
+  linkOrganizationSwitchAnnouncement,
   memoryHeldOrganization,
   oldestMembership,
   orderOrganizations,
@@ -483,10 +735,14 @@ export {
   organizationRequiredResponse,
   readAccountOrganizationChoices,
   readCallerMemberships,
+  readLinkOrganizationParam,
   readMemberships,
   readOrganizationFavourites,
   resolveActiveOrganization,
   resolveActiveOrganizationLazily,
+  resolveAdminSeat,
+  resolveChildOrganizationId,
+  resolveOrganizationWithLink,
   setOrganizationFavourite,
   storageHeldOrganization,
   toAccountOrganizationChoices,

package/dist/react.d.cts

@@ -61,6 +61,8 @@ interface OrganizationMembership {
     readonly isTestFixture: boolean;
     /** When the membership began (ISO): the oldest is rung 4. */
     readonly joinedAt: string;
+    /** When the organization was archived (ISO), or null. Present on every row `readMemberships` returns. */
+    readonly archivedAt?: string | null;
 }
 type OrganizationRung = "held" | "last-active" | "startup" | "first";
 
@@ -96,7 +98,7 @@ interface ActiveOrganizationSnapshot {
     readonly organization: OrganizationMembership | null;
     readonly memberships: readonly OrganizationMembership[];
     /** Which ladder rung answered (or "switched" after a person's click). */
-    readonly rung: OrganizationRung | "switched" | null;
+    readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
 }
 interface ActiveOrganization {

package/dist/react.d.ts

@@ -61,6 +61,8 @@ interface OrganizationMembership {
     readonly isTestFixture: boolean;
     /** When the membership began (ISO): the oldest is rung 4. */
     readonly joinedAt: string;
+    /** When the organization was archived (ISO), or null. Present on every row `readMemberships` returns. */
+    readonly archivedAt?: string | null;
 }
 type OrganizationRung = "held" | "last-active" | "startup" | "first";
 
@@ -96,7 +98,7 @@ interface ActiveOrganizationSnapshot {
     readonly organization: OrganizationMembership | null;
     readonly memberships: readonly OrganizationMembership[];
     /** Which ladder rung answered (or "switched" after a person's click). */
-    readonly rung: OrganizationRung | "switched" | null;
+    readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
 }
 interface ActiveOrganization {