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

package/src/lib/server/dynamic-list-materialize.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @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 type { DocumentReference } from 'firebase-admin/firestore';
+import { type DynamicListCandidate, type DynamicListSource } from '@aglyn/aglyn/server';
+/**
+ * Documents one sweep run may READ across all sources.
+ *
+ * A bound on work, not on membership. When a run exhausts it the sweep stops
+ * where it is, returns `complete: false` with the cursor it reached, and the
+ * next run continues — the shape the import-history sweep already uses. The
+ * alternative, an unbounded scan of every silo per list per run, is the
+ * expensive-read pattern this codebase refuses.
+ *
+ * ⚠️ Membership reconciliation is SKIPPED on an incomplete run. A partial
+ * scan has only seen part of the population, so anybody it did not reach
+ * would look like a non-match — and acting on that would delete real members
+ * because a budget ran out.
+ */
+export declare const DYNAMIC_LIST_SCAN_BUDGET = 5000;
+/**
+ * ⚠️ THE DATE FIELDS THIS FILE READS, AND WHO WRITES THEM.
+ *
+ * `createdAfterMs`/`createdBeforeMs` are applied IN MEMORY against
+ * `createdAt`, never as a Firestore `orderBy` or `where`. That distinction is
+ * the whole safety property: an `orderBy` on a data field drops every document
+ * missing it from the QUERY, invisibly, where an in-memory filter still reads
+ * the document and merely decides it does not match. The paging order is
+ * `__name__`, the one key every document has.
+ *
+ * The rule's decision for an undated record is to EXCLUDE it, so the writers
+ * were checked rather than assumed — a silo with an unstamped writer would
+ * quietly shrink every dated rule:
+ *
+ * - `leads` — `addHostLead` is the single writer and always stamps it.
+ * - `siteMembers` — `membership-register.ts` is the only creator; the other
+ *   member routes read or update an existing document.
+ * - `contacts` — `upsertHostContact`'s create path and the v1 API both stamp.
+ * - `formSubmissions` — the submit route is the only creator; the v1 API and
+ *   the inbox reply route read.
+ *
+ * A new writer of any of those four must stamp `createdAt` or be added here.
+ *
+ * ## Campaign membership is read the same way — off the paged document
+ *
+ * `campaignIds` is applied in memory too, and for a second reason beyond the
+ * one above: it is an ARRAY, so a Firestore `array-contains-any` could express
+ * only the single-campaign case and would need a composite index the moment it
+ * met any other filter in the rule. The membership is already on the document
+ * this scan has read, on a submission at the top and on a contact inside the
+ * reading holder's facet, so matching it costs nothing the page did not
+ * already pay.
+ */
+/** Where a partial sweep stopped, so the next run resumes rather than restarts. */
+export interface DynamicListCursor {
+    /** The source being scanned when the budget ran out. */
+    source: DynamicListSource;
+    /** The last document id read from it. */
+    afterId: string;
+}
+export interface MaterializeDynamicListResult {
+    /** People the rule matched and that are now enrolled. */
+    matched: number;
+    /** Rows created by this run. */
+    enrolled: number;
+    /** Rule-owned rows removed because the person no longer matches. */
+    removed: number;
+    /** False when the scan budget ran out — `cursor` says where to resume. */
+    complete: boolean;
+    cursor: DynamicListCursor | null;
+    /**
+     * True when the rule selects nobody by construction (no sources). Reported
+     * rather than silently materializing an empty list, because an empty list
+     * reads in the composer exactly like a rule that has not run yet.
+     */
+    empty: boolean;
+}
+/** What a read-only pass over the silos found. */
+export interface DynamicListScanResult {
+    /** Matched people, de-duplicated across silos by their person key. */
+    candidates: DynamicListCandidate[];
+    /** False when the scan budget ran out — `cursor` says where to resume. */
+    complete: boolean;
+    cursor: DynamicListCursor | null;
+    /**
+     * True when the rule selects nobody by construction — no sources, or a
+     * `segmentId` naming a segment that no longer exists.
+     */
+    empty: boolean;
+    /** Documents read, against the budget. */
+    read: number;
+}
+/**
+ * WHO A RULE SELECTS, without writing anything.
+ *
+ * The scan and the enrollment used to be one function, so "who would this
+ * match" could only be answered by materializing it. That is the wrong shape
+ * for two callers that now exist: a merchant asking to see an audience before
+ * committing to it, and a fixed list using the filters to FIND people to add.
+ * Neither may write memberships as a side effect of a question.
+ *
+ * One scanner rather than two. Every subtlety here is a place a second
+ * implementation would drift — the in-memory date filter (an `orderBy` on a
+ * data field would DROP undated documents rather than merely not matching
+ * them), the `__name__` paging order, `scopedToHost` on `contacts` and on
+ * nothing else, and a deleted `segmentId` narrowing to nobody rather than
+ * widening to everybody. `materializeDynamicList` reads this and then enrolls.
+ *
+ * NOTHING here writes, and nothing here compares a count against a limit.
+ */
+export declare function collectDynamicListCandidates(options: {
+    hostId: string;
+    rule: unknown;
+    resume?: DynamicListCursor | null;
+    nowMs?: number;
+    scanBudget?: number;
+}): Promise<DynamicListScanResult>;
+/**
+ * Re-evaluates one dynamic list and writes the result into its members.
+ *
+ * @param listRef `orgs/{orgId}/lists/{listId}` — the caller has proved it
+ *                exists and that it is `kind: 'dynamic'`.
+ * @param hostId  the site whose silos the rule draws from, and the scope the
+ *                org-owned contacts read is narrowed to.
+ * @param resume  a cursor from a previous incomplete run.
+ */
+export declare function materializeDynamicList(options: {
+    listRef: DocumentReference;
+    hostId: string;
+    rule: unknown;
+    resume?: DynamicListCursor | null;
+    nowMs?: number;
+    /**
+     * The scan budget. Passed by NOTHING in production — it exists so the suite
+     * can drive a sweep into an exhausted budget and require that it still
+     * removes nobody. A guarantee that only holds at the production budget was
+     * never that guarantee.
+     */
+    scanBudget?: number;
+}): Promise<MaterializeDynamicListResult>;