@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/render-cache.js

@@ -0,0 +1,198 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { unstable_cache } from "next/cache";
+/**
+ * Cross-request caching for the tenant render path's Firestore reads
+ * (AGL-1302, the caching half of AGL-1151).
+ *
+ * Every tenant SSR render fanned out to ~15–40 uncached Admin-SDK reads —
+ * host resolution, org billing, screen + version, the layout chain, and the
+ * whole compose bundle (components, variables, functions, datasets,
+ * workflows, plugin installs). None of that data is per-visitor, and almost
+ * all of it is identical across every path on a site, so a 50-route sweep
+ * paid the same host-scoped reads 50 times over. Routine verification
+ * traffic alone burned ~44K reads/day (87% of the free tier).
+ *
+ * This module is deliberately a THIN wrapper around `unstable_cache` rather
+ * than a cache of its own, so invalidation stays Next's: entries are tagged
+ * and the existing publish/revalidate path (`/api/revalidate`, AGL-1150)
+ * busts them with `revalidateTag` the same moment it drops the page HTML.
+ *
+ * Ground rules encoded here, because `unstable_cache` enforces none of them:
+ *
+ * - VALUES ARE JSON. `unstable_cache` stores `JSON.stringify(result)`, so a
+ *   cache HIT returns plain data while a MISS would return live objects —
+ *   Firestore `Timestamp`s, most importantly, whose `.seconds` getter decays
+ *   to `_seconds` across the round trip. Serving two shapes for the same
+ *   read is how a schedule check works in testing and misfires in
+ *   production, so `withRenderCache` normalizes the MISS through the same
+ *   JSON round trip. Callers whose logic needs live `Timestamp` semantics
+ *   must not cache that read (see the pending-`publishSchedule` guards at
+ *   the call sites).
+ *
+ * - NEGATIVES ARE NOT CACHED unless a caller opts in via `store`. A
+ *   transient miss (host not found, doc missing) cached for the TTL is a
+ *   self-inflicted outage; the Firestore negative-cache class of bug is
+ *   exactly this shape.
+ *
+ * - OUTSIDE NEXT (jest, scripts) there is no incremental cache and
+ *   `unstable_cache` throws its `incrementalCache missing` invariant before
+ *   running the callback. The wrapper catches precisely that and falls back
+ *   to the uncached read, so shared-lib specs exercise the same code path
+ *   they always did.
+ *
+ * - NEVER cache per-user reads through this. Everything cached here must be
+ *   a pure function of published site data.
+ */ /**
+ * One tag per host covers every host-scoped cached doc — the host doc, the
+ * compose bundle, plugin installs, the sitemap payload. The tenant
+ * `/api/revalidate` route busts it on publish (alongside its existing
+ * `revalidatePath` calls), so a publish is exactly as instant as AGL-1150
+ * made it; the TTL is only the backstop for writes that never announce
+ * themselves.
+ */ export const tenantDataTag = (hostId)=>`tenant-data:${hostId}`;
+/**
+ * The backstop TTL for published site data — every read that
+ * `revalidateTag(tenantDataTag(hostId))` busts on publish.
+ *
+ * WHY AN HOUR AND NOT A MINUTE (2026-08-26, from the Vercel cost review).
+ *
+ * Every cache in this layer shipped at 60s, and the page above them was
+ * `revalidate = 60` too. Setting the backstop to the same order as the
+ * request rate makes it the PRIMARY propagation mechanism rather than a
+ * backstop: the whole chain expired together, so a render a minute paid the
+ * full sequential Firestore walk — host, org billing, redirect rules, page
+ * resolution, screen, compose bundle, enrichers — and none of it was ever
+ * stale in a way anyone could observe, because the publish path had already
+ * busted the tag the moment the content changed.
+ *
+ * Measured on `/[host]/[scheme]/[[...slug]]`: 0.78 GB-hr across 635 invocations, a P75
+ * of 3.65s, and ~4.4 GB-s per render — the most expensive route per hit in
+ * the account, on a site with no real traffic yet.
+ *
+ * So the TTL goes back to being what `withRenderCache`'s own docstring says
+ * it is: "the backstop for writes that never announce themselves." An hour
+ * bounds an unannounced direct-to-Firestore edit. Everything that goes
+ * through the product announces itself and is busted in the same instant it
+ * always was, so publish latency is unchanged.
+ *
+ * ⛔ NOT for reads that change OUTSIDE a publish. Two deliberately keep their
+ * own short TTLs and must not be moved onto this one:
+ *
+ *   - `ORG_BILLING_TTL_SECONDS` — a plan change happens in the console and
+ *     nothing busts the tenant tag for it, so this TTL is the ONLY thing
+ *     propagating an upgrade or a downgrade to the live site.
+ *   - `HOST_ALIAS_TTL_SECONDS` / `HOST_DOC_TTL_SECONDS` — a custom domain
+ *     attaching is the customer sitting there waiting for their site
+ *     (AGL-2010), and the `cname--` alias entry expires only by TTL.
+ *
+ * Takedowns are unaffected either way: the middleware runs ahead of every
+ * cache here and carries its own memo, which is what
+ * `lockdown-middleware-propagation.spec.ts` measures.
+ */ export const PUBLISHED_SITE_DATA_TTL_SECONDS = 3600;
+/**
+ * The backstop for the one read a screen publish changes under an UNCHANGED
+ * cache key — the version pointer (AGL-2573).
+ *
+ * The hour above is argued on the premise that "everything that goes through
+ * the product announces itself". That premise held for eleven days in August
+ * and then did not: the tenant refused the announce and every publish on the
+ * platform fell back to this TTL. The announce is still the mechanism — no TTL
+ * can make a publish instant, because the page above these caches is ISR-held
+ * and does not re-run a loader to notice a fresher document — but a backstop
+ * only bounds a failure, and an hour is not a bound anyone would choose for
+ * "your published page is not the page you published".
+ *
+ * Applied to the POINTER alone, deliberately, because the pointer alone is
+ * what makes the hour expensive. `get-screen-version` is keyed by `versionId`,
+ * so the body of a newly published version misses on its own; the only thing
+ * standing between a visitor and it is the screen document that names which
+ * version is live. That document is one small read, and shortening it leaves
+ * the expensive reads — the compose bundle, the node trees — at the hour the
+ * cost review set.
+ *
+ * The principle rather than a tuned figure: **the pointer must never be staler
+ * than the HTML that reads it** — `<=` the tenant catch-all's ISR window
+ * (`apps/tenant/app/[host]/[scheme]/[[...slug]]/page.tsx`), which
+ * `publish-pointer-tracks-page-window.spec.ts` enforces. Above the window, the
+ * page regenerates and faithfully rebuilds itself from a stale pointer, which
+ * is the failure being closed.
+ *
+ * It matched that window exactly while the window was also 600s. It no longer
+ * does, and staying at 600 under an hour-long window is the deliberate choice
+ * (AGL-2690): the loader runs only when the page regenerates, so a shorter TTL
+ * here costs the same single read per regeneration — a miss instead of a hit —
+ * and buys a rebuild from data at most ten minutes old rather than up to an
+ * hour old. That difference only shows when the publish announce is down, and
+ * the announce has been down for eleven days once already.
+ *
+ * The read cost this adds is one document per page REGENERATION rather than
+ * one per hour — regenerations are already bounded by the ISR window, so the
+ * ceiling is the render rate and not the request rate. That is the price of
+ * the bound, and it is the cheapest read on the path.
+ */ export const PUBLISH_POINTER_TTL_SECONDS = 600;
+/**
+ * The alias→hostId resolution is tagged separately because it is the one
+ * cache keyed BEFORE the hostId is known. It only changes on subdomain
+ * rename or custom-domain (dis)connect, never on publish.
+ */ export const tenantHostAliasTag = (alias)=>`tenant-host:${alias}`;
+/**
+ * A value that must be RETURNED but not STORED (a negative result, or a doc
+ * carrying a pending publish schedule). Thrown out of the cached callback so
+ * `unstable_cache` never writes it, caught by the wrapper and unwrapped.
+ */ let BypassStore = class BypassStore extends Error {
+    constructor(value){
+        super('render-cache bypass'), this.value = value;
+        this.name = 'RenderCacheBypass';
+    }
+};
+const isMissingIncrementalCache = (error)=>error instanceof Error && error.message.includes('incrementalCache missing');
+/**
+ * The same normalization the page props already go through (`JSON.parse(
+ * JSON.stringify(...))` at every loader exit), applied at the cache boundary
+ * so hits and misses hand back byte-identical shapes.
+ */ export function toPlainJson(value) {
+    if (value === undefined || value === null) return value;
+    return JSON.parse(JSON.stringify(value));
+}
+export async function withRenderCache(options) {
+    const { key, revalidate, tags, read, store } = options;
+    const cached = unstable_cache(async ()=>{
+        const value = toPlainJson(await read());
+        if (value === undefined || store && !store(value)) {
+            throw new BypassStore(value);
+        }
+        return value;
+    }, [
+        ...key
+    ], {
+        revalidate,
+        tags: [
+            ...tags
+        ]
+    });
+    try {
+        return await cached();
+    } catch (error) {
+        if (error instanceof BypassStore) return error.value;
+        // No Next server context (jest, one-off scripts): the invariant throws
+        // before the callback runs, so reading directly is not a double read.
+        if (isMissingIncrementalCache(error)) return toPlainJson(await read());
+        throw error;
+    }
+}
+
+//# sourceMappingURL=render-cache.js.map

package/src/lib/render-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/tenant/data/admin/src/lib/render-cache.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { unstable_cache } from 'next/cache'\n\n/**\n * Cross-request caching for the tenant render path's Firestore reads\n * (AGL-1302, the caching half of AGL-1151).\n *\n * Every tenant SSR render fanned out to ~15–40 uncached Admin-SDK reads —\n * host resolution, org billing, screen + version, the layout chain, and the\n * whole compose bundle (components, variables, functions, datasets,\n * workflows, plugin installs). None of that data is per-visitor, and almost\n * all of it is identical across every path on a site, so a 50-route sweep\n * paid the same host-scoped reads 50 times over. Routine verification\n * traffic alone burned ~44K reads/day (87% of the free tier).\n *\n * This module is deliberately a THIN wrapper around `unstable_cache` rather\n * than a cache of its own, so invalidation stays Next's: entries are tagged\n * and the existing publish/revalidate path (`/api/revalidate`, AGL-1150)\n * busts them with `revalidateTag` the same moment it drops the page HTML.\n *\n * Ground rules encoded here, because `unstable_cache` enforces none of them:\n *\n * - VALUES ARE JSON. `unstable_cache` stores `JSON.stringify(result)`, so a\n *   cache HIT returns plain data while a MISS would return live objects —\n *   Firestore `Timestamp`s, most importantly, whose `.seconds` getter decays\n *   to `_seconds` across the round trip. Serving two shapes for the same\n *   read is how a schedule check works in testing and misfires in\n *   production, so `withRenderCache` normalizes the MISS through the same\n *   JSON round trip. Callers whose logic needs live `Timestamp` semantics\n *   must not cache that read (see the pending-`publishSchedule` guards at\n *   the call sites).\n *\n * - NEGATIVES ARE NOT CACHED unless a caller opts in via `store`. A\n *   transient miss (host not found, doc missing) cached for the TTL is a\n *   self-inflicted outage; the Firestore negative-cache class of bug is\n *   exactly this shape.\n *\n * - OUTSIDE NEXT (jest, scripts) there is no incremental cache and\n *   `unstable_cache` throws its `incrementalCache missing` invariant before\n *   running the callback. The wrapper catches precisely that and falls back\n *   to the uncached read, so shared-lib specs exercise the same code path\n *   they always did.\n *\n * - NEVER cache per-user reads through this. Everything cached here must be\n *   a pure function of published site data.\n */\n\n/**\n * One tag per host covers every host-scoped cached doc — the host doc, the\n * compose bundle, plugin installs, the sitemap payload. The tenant\n * `/api/revalidate` route busts it on publish (alongside its existing\n * `revalidatePath` calls), so a publish is exactly as instant as AGL-1150\n * made it; the TTL is only the backstop for writes that never announce\n * themselves.\n */\nexport const tenantDataTag = (hostId: string): string => `tenant-data:${hostId}`\n\n/**\n * The backstop TTL for published site data — every read that\n * `revalidateTag(tenantDataTag(hostId))` busts on publish.\n *\n * WHY AN HOUR AND NOT A MINUTE (2026-08-26, from the Vercel cost review).\n *\n * Every cache in this layer shipped at 60s, and the page above them was\n * `revalidate = 60` too. Setting the backstop to the same order as the\n * request rate makes it the PRIMARY propagation mechanism rather than a\n * backstop: the whole chain expired together, so a render a minute paid the\n * full sequential Firestore walk — host, org billing, redirect rules, page\n * resolution, screen, compose bundle, enrichers — and none of it was ever\n * stale in a way anyone could observe, because the publish path had already\n * busted the tag the moment the content changed.\n *\n * Measured on `/[host]/[scheme]/[[...slug]]`: 0.78 GB-hr across 635 invocations, a P75\n * of 3.65s, and ~4.4 GB-s per render — the most expensive route per hit in\n * the account, on a site with no real traffic yet.\n *\n * So the TTL goes back to being what `withRenderCache`'s own docstring says\n * it is: \"the backstop for writes that never announce themselves.\" An hour\n * bounds an unannounced direct-to-Firestore edit. Everything that goes\n * through the product announces itself and is busted in the same instant it\n * always was, so publish latency is unchanged.\n *\n * ⛔ NOT for reads that change OUTSIDE a publish. Two deliberately keep their\n * own short TTLs and must not be moved onto this one:\n *\n *   - `ORG_BILLING_TTL_SECONDS` — a plan change happens in the console and\n *     nothing busts the tenant tag for it, so this TTL is the ONLY thing\n *     propagating an upgrade or a downgrade to the live site.\n *   - `HOST_ALIAS_TTL_SECONDS` / `HOST_DOC_TTL_SECONDS` — a custom domain\n *     attaching is the customer sitting there waiting for their site\n *     (AGL-2010), and the `cname--` alias entry expires only by TTL.\n *\n * Takedowns are unaffected either way: the middleware runs ahead of every\n * cache here and carries its own memo, which is what\n * `lockdown-middleware-propagation.spec.ts` measures.\n */\nexport const PUBLISHED_SITE_DATA_TTL_SECONDS = 3600\n\n/**\n * The backstop for the one read a screen publish changes under an UNCHANGED\n * cache key — the version pointer (AGL-2573).\n *\n * The hour above is argued on the premise that \"everything that goes through\n * the product announces itself\". That premise held for eleven days in August\n * and then did not: the tenant refused the announce and every publish on the\n * platform fell back to this TTL. The announce is still the mechanism — no TTL\n * can make a publish instant, because the page above these caches is ISR-held\n * and does not re-run a loader to notice a fresher document — but a backstop\n * only bounds a failure, and an hour is not a bound anyone would choose for\n * \"your published page is not the page you published\".\n *\n * Applied to the POINTER alone, deliberately, because the pointer alone is\n * what makes the hour expensive. `get-screen-version` is keyed by `versionId`,\n * so the body of a newly published version misses on its own; the only thing\n * standing between a visitor and it is the screen document that names which\n * version is live. That document is one small read, and shortening it leaves\n * the expensive reads — the compose bundle, the node trees — at the hour the\n * cost review set.\n *\n * The principle rather than a tuned figure: **the pointer must never be staler\n * than the HTML that reads it** — `<=` the tenant catch-all's ISR window\n * (`apps/tenant/app/[host]/[scheme]/[[...slug]]/page.tsx`), which\n * `publish-pointer-tracks-page-window.spec.ts` enforces. Above the window, the\n * page regenerates and faithfully rebuilds itself from a stale pointer, which\n * is the failure being closed.\n *\n * It matched that window exactly while the window was also 600s. It no longer\n * does, and staying at 600 under an hour-long window is the deliberate choice\n * (AGL-2690): the loader runs only when the page regenerates, so a shorter TTL\n * here costs the same single read per regeneration — a miss instead of a hit —\n * and buys a rebuild from data at most ten minutes old rather than up to an\n * hour old. That difference only shows when the publish announce is down, and\n * the announce has been down for eleven days once already.\n *\n * The read cost this adds is one document per page REGENERATION rather than\n * one per hour — regenerations are already bounded by the ISR window, so the\n * ceiling is the render rate and not the request rate. That is the price of\n * the bound, and it is the cheapest read on the path.\n */\nexport const PUBLISH_POINTER_TTL_SECONDS = 600\n\n/**\n * The alias→hostId resolution is tagged separately because it is the one\n * cache keyed BEFORE the hostId is known. It only changes on subdomain\n * rename or custom-domain (dis)connect, never on publish.\n */\nexport const tenantHostAliasTag = (alias: string): string =>\n  `tenant-host:${alias}`\n\n/**\n * A value that must be RETURNED but not STORED (a negative result, or a doc\n * carrying a pending publish schedule). Thrown out of the cached callback so\n * `unstable_cache` never writes it, caught by the wrapper and unwrapped.\n */\nclass BypassStore extends Error {\n  constructor(readonly value: unknown) {\n    super('render-cache bypass')\n    this.name = 'RenderCacheBypass'\n  }\n}\n\nconst isMissingIncrementalCache = (error: unknown): boolean =>\n  error instanceof Error && error.message.includes('incrementalCache missing')\n\n/**\n * The same normalization the page props already go through (`JSON.parse(\n * JSON.stringify(...))` at every loader exit), applied at the cache boundary\n * so hits and misses hand back byte-identical shapes.\n */\nexport function toPlainJson<T>(value: T): T {\n  if (value === undefined || value === null) return value\n  return JSON.parse(JSON.stringify(value)) as T\n}\n\nexport interface RenderCacheOptions<T> {\n  /**\n   * Cache key parts. The FIRST part must be unique per read helper — every\n   * call funnels through the same callback source, and `unstable_cache` keys\n   * on callback text + key parts, so the name prefix is what keeps\n   * `getScreen` and `getComponents` from colliding.\n   */\n  key: readonly string[]\n  /** TTL in seconds — the staleness backstop when no tag bust arrives. */\n  revalidate: number\n  /** Tags `revalidateTag` can bust — see `tenantDataTag`. */\n  tags: readonly string[]\n  /** The uncached read. Must resolve to JSON-serializable data. */\n  read: () => Promise<T>\n  /**\n   * Return `false` to serve the value WITHOUT storing it. Negative results\n   * and docs whose live `Timestamp` semantics matter (pending publish\n   * schedules) belong here. `undefined` is never stored regardless.\n   */\n  store?: (value: T) => boolean\n}\n\nexport async function withRenderCache<T>(\n  options: RenderCacheOptions<T>,\n): Promise<T> {\n  const { key, revalidate, tags, read, store } = options\n  const cached = unstable_cache(\n    async () => {\n      const value = toPlainJson(await read())\n      if (value === undefined || (store && !store(value))) {\n        throw new BypassStore(value)\n      }\n      return value\n    },\n    [...key],\n    { revalidate, tags: [...tags] },\n  )\n  try {\n    return await cached()\n  } catch (error) {\n    if (error instanceof BypassStore) return error.value as T\n    // No Next server context (jest, one-off scripts): the invariant throws\n    // before the callback runs, so reading directly is not a double read.\n    if (isMissingIncrementalCache(error)) return toPlainJson(await read())\n    throw error\n  }\n}\n"],"names":["unstable_cache","tenantDataTag","hostId","PUBLISHED_SITE_DATA_TTL_SECONDS","PUBLISH_POINTER_TTL_SECONDS","tenantHostAliasTag","alias","BypassStore","Error","value","name","isMissingIncrementalCache","error","message","includes","toPlainJson","undefined","JSON","parse","stringify","withRenderCache","options","key","revalidate","tags","read","store","cached"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,aAAY;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CC,GAED;;;;;;;CAOC,GACD,OAAO,MAAMC,gBAAgB,CAACC,SAA2B,CAAC,YAAY,EAAEA,QAAQ,CAAA;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCC,GACD,OAAO,MAAMC,kCAAkC,KAAI;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCC,GACD,OAAO,MAAMC,8BAA8B,IAAG;AAE9C;;;;CAIC,GACD,OAAO,MAAMC,qBAAqB,CAACC,QACjC,CAAC,YAAY,EAAEA,OAAO,CAAA;AAExB;;;;CAIC,GACD,IAAA,AAAMC,cAAN,MAAMA,oBAAoBC;IACxB,YAAY,AAASC,KAAc,CAAE;QACnC,KAAK,CAAC,6BADaA,QAAAA;QAEnB,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAEA,MAAMC,4BAA4B,CAACC,QACjCA,iBAAiBJ,SAASI,MAAMC,OAAO,CAACC,QAAQ,CAAC;AAEnD;;;;CAIC,GACD,OAAO,SAASC,YAAeN,KAAQ;IACrC,IAAIA,UAAUO,aAAaP,UAAU,MAAM,OAAOA;IAClD,OAAOQ,KAAKC,KAAK,CAACD,KAAKE,SAAS,CAACV;AACnC;AAwBA,OAAO,eAAeW,gBACpBC,OAA8B;IAE9B,MAAM,EAAEC,GAAG,EAAEC,UAAU,EAAEC,IAAI,EAAEC,IAAI,EAAEC,KAAK,EAAE,GAAGL;IAC/C,MAAMM,SAAS3B,eACb;QACE,MAAMS,QAAQM,YAAY,MAAMU;QAChC,IAAIhB,UAAUO,aAAcU,SAAS,CAACA,MAAMjB,QAAS;YACnD,MAAM,IAAIF,YAAYE;QACxB;QACA,OAAOA;IACT,GACA;WAAIa;KAAI,EACR;QAAEC;QAAYC,MAAM;eAAIA;SAAK;IAAC;IAEhC,IAAI;QACF,OAAO,MAAMG;IACf,EAAE,OAAOf,OAAO;QACd,IAAIA,iBAAiBL,aAAa,OAAOK,MAAMH,KAAK;QACpD,uEAAuE;QACvE,sEAAsE;QACtE,IAAIE,0BAA0BC,QAAQ,OAAOG,YAAY,MAAMU;QAC/D,MAAMb;IACR;AACF"}

package/src/lib/server/account-addresses.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Where an address came from. An address can have more than one. */
+export type AccountAddressSource = 
+/** The Firebase Auth record's `email` — what a token carries today. */
+'primary'
+/** A federated provider's own address, from `providerData[].email`. */
+ | 'provider'
+/** A row in `users/{uid}/emails` — a confirmed alias, or a former primary. */
+ | 'stored';
+/** One address, with everything a consumer needs to decide what to do. */
+export interface AccountAddress {
+    /** Lowercased and trimmed. The form both hashed stores key on. */
+    address: string;
+    /** Every source that named it, so a card can say WHY it is listed. */
+    sources: AccountAddressSource[];
+    /**
+     * `sha256(address)` — the SAME derivation `emailSuppressionKey` uses, so a
+     * consumer never has to re-derive it and the two can never disagree about
+     * which document describes which person.
+     */
+    key: string;
+    /**
+     * Another account holds this address too.
+     *
+     * ⚠️ `false` means "nothing found", NOT "nobody else holds it" — see the
+     * reverse-direction note in this module's header.
+     */
+    shared: boolean;
+    /**
+     * A provider asserted this address for this account and the uniqueness
+     * claim was REFUSED, because another account already held it.
+     *
+     * Carried onto the staff surface rather than left in a log line. The
+     * refusal is the whole mechanism: silently skipping the claim is what let
+     * the live collision exist unrecorded, so an account carrying a provider
+     * address it does not own has to be visible on its own page.
+     */
+    indexConflict: boolean;
+}
+/**
+ * ## How big this can get, and why nothing here slices
+ *
+ * `MAX_ACCOUNT_EMAILS` is 5 and caps the SUBCOLLECTION only; the primary and
+ * the provider addresses are additional, so the set can exceed 5. It stays
+ * far under Firestore's 30-element `in` limit in every realistic shape, but
+ * "far under" is not a guarantee and a truncated erasure is the worst outcome
+ * available in this whole area — it reports success over addresses it never
+ * swept.
+ *
+ * So the rule is: consumers ITERATE this list, they do not slice it, and any
+ * consumer feeding it to an `in` query CHUNKS. No function in this module
+ * truncates its result.
+ */
+export interface AccountAddressSet {
+    uid: string;
+    /** The Auth record's current address, or null for an addressless account. */
+    primary: string | null;
+    /** Primary first, then the rest in a stable order. */
+    addresses: AccountAddress[];
+    /**
+     * A source threw and the set may be SHORT.
+     *
+     * Load-bearing for erasure: erasing "every address" from an incomplete set
+     * is not erasing every address, and the caller has to be able to say so
+     * rather than report a complete erasure it did not perform.
+     */
+    incomplete: boolean;
+}
+/** `sha256` of the normalized address. */
+export declare function accountAddressKey(address: string): string;
+/**
+ * Every address `uid` holds, from all three sources.
+ *
+ * `record` is passed in rather than fetched: every caller already has the
+ * Auth record in hand, and re-fetching it would add a pooled lookup to a page
+ * that has already paid for one.
+ *
+ * Best-effort per source. A Firestore outage must not make the delivery card
+ * fall back to the single-address behaviour SILENTLY — it reports
+ * `incomplete` instead, and the callers that destroy data refuse on it.
+ *
+ * @param detectShared consult the reverse direction for each non-primary
+ *        address. One extra lookup per address; skip it where the answer is
+ *        not used.
+ */
+export declare function resolveAccountAddresses(options: {
+    uid: string;
+    /** The Auth record — `email` and `providerData` are read from it. */
+    record?: {
+        email?: string | null;
+        providerData?: readonly {
+            email?: string | null;
+        }[];
+    } | null;
+    detectShared?: boolean;
+    firestore?: any;
+}): Promise<AccountAddressSet>;
+/** Just the addresses, for a caller that needs nothing else. */
+export declare function addressList(set: AccountAddressSet): string[];
+/** Just the hashed keys, for a query against a store keyed by them. */
+export declare function addressKeys(set: AccountAddressSet): string[];
+export interface AddressHolders {
+    address: string;
+    /** Every uid found to hold it. May be SHORT — see below. */
+    uids: string[];
+    /** More than one distinct account was found. */
+    ambiguous: boolean;
+}
+/**
+ * Which accounts hold `address`, as far as can be determined.
+ *
+ * ## What it can and cannot see
+ *
+ * It consults the two sources an address can be looked up IN:
+ *
+ *  - Firebase Auth, across pools — the account holding it as its PRIMARY.
+ *  - `emailIdentityIndex/{address}` — the account holding it as a CONFIRMED
+ *    alias.
+ *
+ * It cannot see a `providerData` holder, because Firebase Auth offers no
+ * lookup by provider address; that field is readable only from a record you
+ * already have. This is not a gap that can be closed by trying harder, and
+ * the live shape of it is ordinary: an account whose Google provider address
+ * is another account's primary.
+ *
+ * So the result is sound in ONE direction only. `ambiguous: true` is proof
+ * that more than one account holds the address. `ambiguous: false` is the
+ * absence of evidence, never evidence of absence — a caller must not treat a
+ * single uid as "this address belongs to this person".
+ */
+export declare function findAccountsHoldingAddress(input: unknown, options?: {
+    firestore?: any;
+}): Promise<AddressHolders>;
+/**
+ * The single account an address can be attributed to, or null.
+ *
+ * Null for BOTH "nobody" and "more than one", deliberately. The caller writes
+ * an audit subject with it, and a row naming the wrong customer is worse than
+ * a row naming none: the collection exists to answer "who at Aglyn read my
+ * data", and an answer that points at an innocent account is not a weaker
+ * answer, it is a false one.
+ */
+export declare function attributableAccountForAddress(input: unknown, options?: {
+    firestore?: any;
+}): Promise<string | null>;