@ai-matrx/auth 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog — @ai-matrx/auth
 
+## 0.2.1
+### website organization pieces (round 2)
+
+**The website's organization logic moves in (`/organizations`); the app keeps only store bindings.**
+- `createActiveOrganization` — new options: `link` (the `?org=` link as a first-class rung, honoured only for a
+  current membership, `onDecision` receives refused/offered/announced/admitted for the host to say), `adminSeat`
+  (admin lane replaces `current()`/`ensureOrgId()` while open, only for a membership), `bootstrapGate`,
+  `refusalRecheckGapMs`; `handleRefusal` now also re-runs the ladder for the not-a-member codes
+  (`organization_forbidden` / `organization_not_member`), once per gap. `storageHeldOrganization(...).read` is sync.
+- `organization-link` — `classifyLinkOrganizationValue`, `readLinkOrganizationParam`, `decideLinkOrganization`
+  (injectable `messages`), `resolveOrganizationWithLink` (the one ladder + the link, share admission injected).
+- `organization-gate` — `createOrganizationBootstrapGate`, `isNotAMemberRefusal`, `createNotAMemberRefusalNotice`,
+  `resolveChildOrganizationId`, `resolveAdminSeat`, `adminSeatReplacesUserContext`.
+Tests: active-organization (+5), organization-gate (9).
+
 ## 0.2.0
 
 **The apps' own identity, server-door and sign-in copies move in (consolidation U1).**

package/dist/organizations.cjs

@@ -20,20 +20,33 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/organizations.ts
 var organizations_exports = {};
 __export(organizations_exports, {
+  LINK_ORGANIZATION_QUERY_KEY: () => LINK_ORGANIZATION_QUERY_KEY,
   MEMBERSHIPS_URL: () => MEMBERSHIPS_URL,
+  NOT_A_MEMBER_RECHECK_GAP_MS: () => NOT_A_MEMBER_RECHECK_GAP_MS,
   NoActiveOrganizationError: () => NoActiveOrganizationError,
   NotAMemberError: () => NotAMemberError,
   ORGANIZATION_CONTEXT_REQUIRED_CODE: () => ORGANIZATION_CONTEXT_REQUIRED_CODE,
   ORGANIZATION_ENTITY_TYPE: () => ORGANIZATION_ENTITY_TYPE,
   ORGANIZATION_REQUIRED_CODE: () => ORGANIZATION_REQUIRED_CODE,
   ORGANIZATION_REQUIRED_WIRE_CODE: () => ORGANIZATION_REQUIRED_WIRE_CODE,
+  ORGANIZATION_RESOLUTION_TIMEOUT_MS: () => ORGANIZATION_RESOLUTION_TIMEOUT_MS,
   OrganizationRequiredServerError: () => OrganizationRequiredServerError,
+  adminSeatReplacesUserContext: () => adminSeatReplacesUserContext,
+  classifyLinkOrganizationValue: () => classifyLinkOrganizationValue,
   classifyOrganizationRefusal: () => classifyOrganizationRefusal,
   createActiveOrganization: () => createActiveOrganization,
+  createNotAMemberRefusalNotice: () => createNotAMemberRefusalNotice,
+  createOrganizationBootstrapGate: () => createOrganizationBootstrapGate,
+  decideLinkOrganization: () => decideLinkOrganization,
   extractOrganizationHoldMemberships: () => extractOrganizationHoldMemberships,
+  isNotAMemberRefusal: () => isNotAMemberRefusal,
   isOrganizationRequiredEnvelope: () => isOrganizationRequiredEnvelope,
   isOrganizationRequiredError: () => isOrganizationRequiredError,
   isOrganizationRequiredServerError: () => isOrganizationRequiredServerError,
+  linkOrganizationMalformedMessage: () => linkOrganizationMalformedMessage,
+  linkOrganizationNotAMemberMessage: () => linkOrganizationNotAMemberMessage,
+  linkOrganizationOfferMessage: () => linkOrganizationOfferMessage,
+  linkOrganizationSwitchAnnouncement: () => linkOrganizationSwitchAnnouncement,
   memoryHeldOrganization: () => memoryHeldOrganization,
   oldestMembership: () => oldestMembership,
   orderOrganizations: () => orderOrganizations,
@@ -43,10 +56,14 @@ __export(organizations_exports, {
   organizationRequiredResponse: () => organizationRequiredResponse,
   readAccountOrganizationChoices: () => readAccountOrganizationChoices,
   readCallerMemberships: () => readCallerMemberships,
+  readLinkOrganizationParam: () => readLinkOrganizationParam,
   readMemberships: () => readMemberships,
   readOrganizationFavourites: () => readOrganizationFavourites,
   resolveActiveOrganization: () => resolveActiveOrganization,
   resolveActiveOrganizationLazily: () => resolveActiveOrganizationLazily,
+  resolveAdminSeat: () => resolveAdminSeat,
+  resolveChildOrganizationId: () => resolveChildOrganizationId,
+  resolveOrganizationWithLink: () => resolveOrganizationWithLink,
   setOrganizationFavourite: () => setOrganizationFavourite,
   storageHeldOrganization: () => storageHeldOrganization,
   toAccountOrganizationChoices: () => toAccountOrganizationChoices,
@@ -238,6 +255,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
+var import_uuid = require("@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 ((0, import_uuid.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) {
@@ -315,6 +535,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();
@@ -332,19 +553,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,
@@ -380,6 +620,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") {
@@ -396,11 +641,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");
     },
@@ -415,7 +660,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();

package/dist/organizations.d.cts

@@ -143,6 +143,230 @@ declare function setOrganizationFavourite(db: OrganizationsDb, organizationId: s
 type OrganizationRefusal = "lapsed" | "retry" | null;
 declare function classifyOrganizationRefusal(status: number, body: unknown): OrganizationRefusal;
 
+/**
+ * Organization-question plumbing that is LOGIC, not store binding (moved from the website's
+ * `orgBootstrapGate`, `organizationRefusal`, `childOrganization`, `adminOrganization`).
+ * Pure: every host input is injected; no Redux, no Next, no window.
+ */
+/** How long a write may wait for the first answer before it is refused anyway. */
+declare const ORGANIZATION_RESOLUTION_TIMEOUT_MS = 10000;
+interface OrganizationBootstrapGate {
+    isResolved(): boolean;
+    /** The organization question has been answered (with an organization or without). Idempotent. */
+    markResolved(): void;
+    /** Wait for the answer or the timeout, whichever first. Always resolves; never rejects. */
+    whenResolved(timeoutMs?: number): Promise<void>;
+    /** Tests and in-place identity swaps only. */
+    reset(): void;
+}
+/** "Nobody has looked yet" is a race, not a fact: a held write waits on this, bounded. */
+declare function createOrganizationBootstrapGate(defaultTimeoutMs?: number): OrganizationBootstrapGate;
+/** True when an error body is the server's "you are not a member of the organization you carried". */
+declare function isNotAMemberRefusal(body: unknown): boolean;
+declare const NOT_A_MEMBER_RECHECK_GAP_MS = 30000;
+interface NotAMemberRefusalNotice {
+    /** True when a recheck was started (at most one per gap, so a burst reads memberships once). */
+    notice(body: unknown, now?: number): boolean;
+    reset(): void;
+}
+declare function createNotAMemberRefusalNotice(recheck: () => void, gapMs?: number): NotAMemberRefusalNotice;
+type ParentOrganization = string | {
+    organization_id?: string | null;
+} | null | undefined;
+/**
+ * A record created as part of an existing parent lives in the PARENT's organization; the explicit
+ * one applies only when the parent names none. A disagreement is announced (`onDisagree`,
+ * default console.warn), never obeyed.
+ */
+declare function resolveChildOrganizationId(parent: ParentOrganization, explicit?: string | null, label?: string, onDisagree?: (message: string) => void): string | null;
+/** What the host knows about the admin lane. */
+interface AdminSeatInput {
+    readonly laneOpen: boolean;
+    readonly organizationId?: string | null;
+    readonly organizationName?: string | null;
+}
+interface AdminSeat {
+    readonly id: string;
+    readonly name: string | null;
+}
+/** The admin organization in force right now, or null (off the lane, or none set). */
+declare function resolveAdminSeat(input: AdminSeatInput | null | undefined): AdminSeat | null;
+/** True when the admin seat differs from the person's own active organization (scope/project/task never ride across). */
+declare function adminSeatReplacesUserContext(input: AdminSeatInput | null | undefined, personOrganizationId: string | null | undefined): boolean;
+
+/**
+ * The query key, platform-wide. The server stamps this on every deep link it
+ * emits; `features/admin/users/components/OrganizationsAdminClient.tsx` has
+ * read it since before this module existed. One spelling, in one place.
+ */
+declare const LINK_ORGANIZATION_QUERY_KEY = "org";
+type LinkOrganizationParam = 
+/** No link said anything about an organization. The ladder is untouched. */
+{
+    kind: "absent";
+}
+/** Something was said and it is neither a uuid nor an address. Refused in words, never used. */
+ | {
+    kind: "malformed";
+    raw: string;
+}
+/** A well-formed organization id. Still has to survive the membership check. */
+ | {
+    kind: "named";
+    organizationId: string;
+}
+/** An organization's address (slug). Survives only by matching a membership's slug. */
+ | {
+    kind: "addressed";
+    slug: string;
+};
+/**
+ * Classify one bare `org=` value. The ONE rule for what a value may be, shared
+ * by the URL reader below and the boot resolver's bare-value path.
+ */
+declare function classifyLinkOrganizationValue(raw: string): LinkOrganizationParam;
+/**
+ * Read the key out of a query string, a `URLSearchParams`, or a full URL.
+ * Never throws: a URL this cannot parse is `absent`, because a crash on
+ * arrival is a worse answer than the ladder's own.
+ */
+declare function readLinkOrganizationParam(source: string | URLSearchParams | null | undefined): LinkOrganizationParam;
+interface LinkOrganizationMembership {
+    id: string;
+    name: string;
+    /** The organization's address, so an `addressed` link can be matched. */
+    slug?: string | null;
+}
+interface LinkOrganizationDecisionInput {
+    param: LinkOrganizationParam;
+    /** The person's LIVE memberships. The only authority on what they may open. */
+    memberships: ReadonlyArray<LinkOrganizationMembership>;
+    /** The organization they are working in right now, or null. */
+    currentOrganizationId: string | null;
+    currentOrganizationName?: string | null;
+    /**
+     * The knob `userPreferences.organization.switchOnLinkPrompt` — "switch
+     * organization when a link asks". DEFAULT ON, so an omitted value is `true`.
+     */
+    switchWhenALinkAsks?: boolean;
+    /** The account they are signed in as, for the refusal sentence. */
+    signedInAs?: string | null;
+    /**
+     * The link's organization is one this person is not a member of but IS let into
+     * by a share they accepted (`lib/organizations/linkOrganizationAdmission.ts`).
+     * A share admits and never makes a member, so the answer is `admitted`: nobody
+     * is moved, nothing is refused, and the page opens it as that organization's
+     * guest. Omitted, the answer is exactly what it was before (VERIFIER-15 H4).
+     */
+    admittedByAShare?: boolean;
+    /** Replace any of the default English sentences (a localising host). */
+    messages?: Partial<LinkOrganizationMessages>;
+}
+interface LinkOrganizationMessages {
+    notAMember(signedInAs?: string | null): string;
+    malformed(raw: string): string;
+    switched(toName: string, fromName: string | null): string;
+    offer(toName: string, fromName: string | null): string;
+    offerAction(toName: string): string;
+}
+type LinkOrganizationDecision = 
+/** Nothing to do. No toast, no change. */
+{
+    kind: "no-link";
+}
+/** The link names the organization they are already in. Silent no-op. */
+ | {
+    kind: "already-current";
+    organizationId: string;
+}
+/** Use this organization for this session. `announcement` non-null = they moved. */
+ | {
+    kind: "honoured";
+    organizationId: string;
+    organizationName: string;
+    announcement: string | null;
+}
+/** The knob is off and this would be a real switch. Offer it as a click. */
+ | {
+    kind: "offered";
+    organizationId: string;
+    organizationName: string;
+    message: string;
+    actionLabel: string;
+}
+/**
+ * Not a member, but let in by a share they accepted. Silent: nobody is moved
+ * (a share never makes a member) and nothing was refused (the page opens it).
+ */
+ | {
+    kind: "admitted";
+    organizationId: string;
+}
+/** Malformed, or not theirs. Changes nothing; says so. */
+ | {
+    kind: "refused";
+    reason: "malformed" | "not-a-member";
+    message: string;
+};
+/** What a person reads when the link's organization is not theirs to open. */
+declare function linkOrganizationNotAMemberMessage(signedInAs?: string | null): string;
+/** What a person reads when `org=` is not an organization id at all. */
+declare function linkOrganizationMalformedMessage(raw: string): string;
+/** What a person reads when a link actually moved them. Law 4: never silent. */
+declare function linkOrganizationSwitchAnnouncement(toName: string, fromName: string | null): string;
+/** What a person reads with the knob turned off and a link asking to move them. */
+declare function linkOrganizationOfferMessage(toName: string, fromName: string | null): string;
+/**
+ * The decision. One function, every branch, no side effects.
+ *
+ * 🚨 WHY THE KNOB GOVERNS ONLY A REAL SWITCH. The knob protects the
+ * organization a person is WORKING IN from being yanked out from under them by
+ * a link someone else composed. With `currentOrganizationId === null` there is
+ * nothing to protect and nothing to switch away from: the alternative to
+ * honouring the link is the picker, which is the very dead end this module was
+ * built to end. So the knob turns a SWITCH into an offer; it never turns an
+ * arrival into a refusal. This is deliberate and it is not a hidden default —
+ * with no link present, a null selection stays null exactly as before.
+ */
+declare function decideLinkOrganization(input: LinkOrganizationDecisionInput): LinkOrganizationDecision;
+interface ResolveWithLinkInput<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}> {
+    readonly memberships: readonly T[];
+    /** This tab's held organization (rung 1; a refresh keeps it). */
+    readonly held?: string | null;
+    readonly readAccount: () => Promise<AccountOrganizationChoices>;
+    readonly first?: () => Promise<T | null>;
+    /** The raw `?org=` value, a query string, a URL or URLSearchParams. Omitted = no link. */
+    readonly link?: string | URLSearchParams | null;
+    readonly switchWhenALinkAsks?: boolean | undefined;
+    readonly signedInAs?: string | null | undefined;
+    readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+    /** Asked only when the link already failed the membership check (a share admits, never joins). */
+    readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+}
+interface ResolvedWithLink<T> {
+    readonly organization: T;
+    readonly rung: OrganizationRung | "link";
+    /** What the link meant, when it said anything — the host SAYS it (refused / announced / offered). */
+    readonly link: LinkOrganizationDecision;
+}
+/**
+ * The ONE load ladder with the link folded in: held → last active → start-up → first, then the
+ * link's own organization wins ONLY when it is a current membership. Every other link outcome
+ * (refused, offered, already-current, admitted) leaves the ladder's answer standing. Null when
+ * the person has no memberships. A failed read throws through.
+ */
+declare function resolveOrganizationWithLink<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}>(input: ResolveWithLinkInput<T>): Promise<ResolvedWithLink<T> | null>;
+
 /**
  * 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).
@@ -181,7 +405,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;
 }
 declare class NoActiveOrganizationError extends Error {
@@ -214,11 +438,37 @@ interface CreateActiveOrganizationOptions {
     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;
+    /**
+     * The link's own organization (`?org=` uuid or address) as a first-class rung: honoured only when
+     * it is a current membership, otherwise the ladder stands and `onDecision` receives the refusal /
+     * offer / announcement for the host to SAY. Supersedes `linked` when both are given.
+     */
+    readonly link?: {
+        readonly source: () => string | URLSearchParams | null | undefined;
+        readonly switchWhenALinkAsks?: (() => boolean | undefined) | undefined;
+        readonly signedInAs?: (() => string | null | undefined) | undefined;
+        readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+        /** A share admits without making a member (asked only after a not-a-member verdict). */
+        readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+        readonly onDecision?: ((decision: LinkOrganizationDecision) => void) | undefined;
+    } | undefined;
+    /**
+     * THE ADMIN SEAT: while the host's admin lane is open, the admin's own organization IS the active
+     * one for every reader (`current()`, `ensureOrgId()`); off the lane the person's own is untouched.
+     * Ignored unless the seat is a current membership. The snapshot always keeps the person's own.
+     */
+    readonly adminSeat?: (() => AdminSeatInput | null | undefined) | undefined;
+    /** Marked resolved whenever the ladder settles (organization or none). */
+    readonly bootstrapGate?: OrganizationBootstrapGate | undefined;
+    /** Minimum gap between ladder re-runs caused by a not-a-member refusal. Default 30 s. */
+    readonly refusalRecheckGapMs?: number | 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;
+declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore & {
+    read(userId: string): string | null;
+};
 /** Held in memory: the running app's own choice (desktop, scripts, tests). */
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
@@ -329,4 +579,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 { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type AdminSeat, type AdminSeatInput, type CreateActiveOrganizationOptions, type HeldOrganizationStore, LINK_ORGANIZATION_QUERY_KEY, type LadderInput, type LinkOrganizationDecision, type LinkOrganizationDecisionInput, type LinkOrganizationMembership, type LinkOrganizationMessages, type LinkOrganizationParam, MEMBERSHIPS_URL, type MembershipReadClient, NOT_A_MEMBER_RECHECK_GAP_MS, NoActiveOrganizationError, NotAMemberError, type NotAMemberRefusalNotice, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_ENTITY_TYPE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, ORGANIZATION_RESOLUTION_TIMEOUT_MS, type OrganizationBootstrapGate, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembership, type OrganizationMembershipSummary, type OrganizationRefusal, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationRung, type OrganizationsDb, type ParentOrganization, type ResolveWithLinkInput, type ResolvedOrganization, type ResolvedWithLink, adminSeatReplacesUserContext, classifyLinkOrganizationValue, classifyOrganizationRefusal, createActiveOrganization, createNotAMemberRefusalNotice, createOrganizationBootstrapGate, decideLinkOrganization, extractOrganizationHoldMemberships, isNotAMemberRefusal, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, linkOrganizationMalformedMessage, linkOrganizationNotAMemberMessage, linkOrganizationOfferMessage, linkOrganizationSwitchAnnouncement, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readAccountOrganizationChoices, readCallerMemberships, readLinkOrganizationParam, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, resolveAdminSeat, resolveChildOrganizationId, resolveOrganizationWithLink, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };