@aglyn/aglyn 1.0.0-beta.266 → 1.0.0-beta.268

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.266",
+  "version": "1.0.0-beta.268",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -37,16 +37,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.266",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.266",
-    "@aglyn/shared-data-types": "1.0.0-beta.266",
-    "@aglyn/shared-util-email": "1.0.0-beta.266",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.266",
-    "@aglyn/shared-util-http": "1.0.0-beta.266",
-    "@aglyn/shared-util-logger": "1.0.0-beta.266",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.266",
-    "@aglyn/shared-util-tools": "1.0.0-beta.266",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.266",
+    "@aglyn/shared-data-enums": "1.0.0-beta.268",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.268",
+    "@aglyn/shared-data-types": "1.0.0-beta.268",
+    "@aglyn/shared-util-email": "1.0.0-beta.268",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.268",
+    "@aglyn/shared-util-http": "1.0.0-beta.268",
+    "@aglyn/shared-util-logger": "1.0.0-beta.268",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.268",
+    "@aglyn/shared-util-tools": "1.0.0-beta.268",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.268",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",
@@ -61,7 +61,7 @@
   "peerDependencies": {
     "@mui/material": "^9.3.1",
     "@mui/system": "^9.2.0",
-    "firebase": "^12.18.0",
+    "firebase": "^13.0.0",
     "next": "^16.3.3",
     "react": "^19.2.8"
   },

package/src/lib/app-utils/health-report.d.ts

@@ -531,20 +531,51 @@ export declare function signupDroughtHealth(markers: SignupServedMarker[] | null
  * 10/17's). The streak of two was red only on 10/11, AGL-3724, and nowhere
  * else. A streak of three missed AGL-3724 entirely.
  *
+ * ## A site is not the question; reaching the console is (2026-10-18)
+ *
+ * The streak rule went red on 2026-10-18 at 15:37Z for the same reason the
+ * count did: the two newest people had no site, and both had LEFT. One left
+ * nine seconds after the workspace appeared. The other reached the site list,
+ * walked four steps of the guided start, and stopped. Sign-ups on either side
+ * of them made sites on the same build. "No site" is an outcome that leaving
+ * produces as surely as a broken landing does, so no rule over sites alone
+ * can tell the two apart.
+ *
+ * What AGL-3724 broke was the landing itself: the person never REACHED the
+ * console after the workspace was made. That is recorded now. Every org is
+ * born with `landedAtMs: null` ({@link ORG_LANDED_AT_PATH}), and the org
+ * shell's activity beat, which fires the moment the workspace opens, sets it
+ * the first time (`stampOrgLastActivity`). So an org counts as stranded only
+ * when it has no site AND its owner never reached the console. A person who
+ * arrived and then left is a drop-off, which is not this check's business.
+ *
+ * An org without the field predates the marker, and the check has no
+ * evidence about it either way, so it ABSTAINS on it (`unmarkedOrgs`). It is
+ * never counted as stranded, the way a check that cannot see its subject
+ * says so instead of guessing.
+ *
  * Pure, like its siblings: the route reads, this decides. The body carries
  * counts only, never an org id, slug or visitor key, because the endpoint is
  * public.
  */
 export interface SignupLandingCheck extends HealthCheck {
-    /** Orgs in the window that have no site. Null when the read failed. */
+    /**
+     * Orgs in the window with no site whose owner never reached the console.
+     * Null when the read failed.
+     */
     strandedOrgs: number | null;
-    /** People in the window with no site in any of their orgs. */
+    /** People in the window none of whose orgs has a site or a landing. */
     strandedPeople: number | null;
     /**
-     * How many of the newest people in the window, in a row, have no site:
+     * How many of the newest people in the window, in a row, are stranded:
      * what the verdict reads. Null when the read failed.
      */
     strandedStreak: number | null;
+    /**
+     * Orgs with no site that predate the landing marker, which the check
+     * abstains on. Null when the read failed.
+     */
+    unmarkedOrgs: number | null;
     /** Every org in the window, the context for the counts above. */
     orgsInWindow: number | null;
     /** How far back the window reaches. */
@@ -569,12 +600,21 @@ export declare const SIGNUP_LANDING_GRACE_MINUTES = 30;
  */
 export declare const MAX_STRANDED_SIGNUPS = 2;
 /**
- * One org as the landing check reads it: whether it has any site, when it
- * was made, and who made it. `visitor` is an opaque key that never leaves
- * the check; an org without one is its own person.
+ * Where an org records that its owner reached the console (see
+ * {@link SignupLandingCheck}). `null` from birth, epoch millis once the
+ * workspace has been opened, absent on an org made before it existed.
+ */
+export declare const ORG_LANDED_AT_PATH = "landedAtMs";
+/**
+ * One org as the landing check reads it: whether it has any site, whether
+ * its owner reached the console, when it was made, and who made it.
+ * `landed` is `undefined` for an org that predates the marker. `visitor` is
+ * an opaque key that never leaves the check; an org without one is its own
+ * person.
  */
 export interface SignupLandingOrg {
     hostCount: number;
+    landed?: boolean;
     createdAtMs?: number | null;
     visitor?: string | null;
 }
@@ -1497,6 +1537,10 @@ export interface CronBeatStore {
     collection(name: string): {
         doc(id: string): {
             set(data: Record<string, unknown>, options?: unknown): Promise<unknown>;
+            /** Present on a real Firestore handle; {@link writeCronBeats} reads the summary through it. */
+            get?(): Promise<{
+                get(field: string): unknown;
+            }>;
         };
     };
 }
@@ -1514,6 +1558,34 @@ export declare const CRON_BEAT_EVERY_MINUTE_MIN_INTERVAL_MS: number;
 /** Test seam. */
 export declare function resetCronBeatThrottleForTests(): void;
 export declare function writeCronBeat(store: CronBeatStore, jobId: string, now?: number): Promise<boolean>;
+/**
+ * How long a job's own document may lag its summary entry when the jobs are
+ * marked together (AGL-3932).
+ *
+ * The reader judges from the summary and opens a job's own document only to
+ * confirm an entry the summary calls late, so a job marked every fifteen
+ * minutes does not need its own document rewritten every fifteen minutes:
+ * half an hour, under every plugin job's forty-five-minute grace, keeps the
+ * confirming mark fresh enough to agree with a summary that has stopped.
+ */
+export declare const CRON_BEAT_OWN_MARK_REFRESH_MS: number;
+/**
+ * The marks one run leaves for several jobs at once — the plugin-crons route
+ * stamps twenty jobs a run, and {@link writeCronBeat} per job was forty
+ * writes every fifteen minutes, half of everything the platform wrote
+ * (AGL-3932).
+ *
+ * One summary write carries every job's entry (merged, like the single mark's).
+ * A job's own document is rewritten only when the summary's current entry
+ * for it is missing or older than {@link CRON_BEAT_OWN_MARK_REFRESH_MS},
+ * which one read of the summary tells; a store without `get`, or a summary
+ * that cannot be read or written, falls back to the single-mark shape for
+ * every job, so no run can leave fewer marks than before.
+ *
+ * NEVER THROWS, as {@link writeCronBeat} never throws, and for the same
+ * reason. Returns false only when nothing landed for some job.
+ */
+export declare function writeCronBeats(store: CronBeatStore, jobIds: readonly string[], now?: number): Promise<boolean>;
 /**
  * The beats a summary document holds, ignoring anything malformed.
  *

package/src/lib/app-utils/health-report.js

@@ -548,6 +548,11 @@ export function signupDroughtHealth(markers, attemptMarkers, orgCreations, ms, m
  * Red when the two newest people in the window are both stranded. See
  * {@link SignupLandingCheck}.
  */ export const MAX_STRANDED_SIGNUPS = 2;
+/**
+ * Where an org records that its owner reached the console (see
+ * {@link SignupLandingCheck}). `null` from birth, epoch millis once the
+ * workspace has been opened, absent on an org made before it existed.
+ */ export const ORG_LANDED_AT_PATH = 'landedAtMs';
 export function signupLandingHealth(orgs, ms, maxStranded = MAX_STRANDED_SIGNUPS, windowHours = SIGNUP_LANDING_WINDOW_HOURS, graceMinutes = SIGNUP_LANDING_GRACE_MINUTES) {
     const shape = {
         windowHours,
@@ -564,31 +569,41 @@ export function signupLandingHealth(orgs, ms, maxStranded = MAX_STRANDED_SIGNUPS
             strandedOrgs: null,
             strandedPeople: null,
             strandedStreak: null,
+            unmarkedOrgs: null,
             orgsInWindow: null
         }, shape);
     }
     // `!(n > 0)` rather than `n === 0`, so a corrupt count (NaN, a string)
     // reads as "no site" and cannot hide a stranded org.
     const hasSite = (landing)=>Number(landing.hostCount) > 0;
-    const strandedOrgs = orgs.filter((landing)=>!hasSite(landing)).length;
+    // Each org is one of: arrived (a site, or its owner reached the console),
+    // stranded (neither, and the marker says so), or unknown (neither, and it
+    // predates the marker).
+    const arrived = (landing)=>hasSite(landing) || landing.landed === true;
+    const isStranded = (landing)=>!arrived(landing) && landing.landed === false;
+    const strandedOrgs = orgs.filter(isStranded).length;
+    const unmarkedOrgs = orgs.filter((landing)=>!arrived(landing) && landing.landed === undefined).length;
     const people = new Map();
     orgs.forEach((landing, index)=>{
-        var _ref, _ref1;
+        var _ref, _ref1, _ref2;
         const key = landing.visitor ? `visitor:${landing.visitor}` : `org:${index}`;
         const createdAtMs = Number(landing.createdAtMs);
         const latestMs = Number.isFinite(createdAtMs) ? createdAtMs : 0;
         const person = people.get(key);
         people.set(key, {
             latestMs: Math.max((_ref = person == null ? void 0 : person.latestMs) != null ? _ref : 0, latestMs),
-            landed: ((_ref1 = person == null ? void 0 : person.landed) != null ? _ref1 : false) || hasSite(landing)
+            arrived: ((_ref1 = person == null ? void 0 : person.arrived) != null ? _ref1 : false) || arrived(landing),
+            stranded: ((_ref2 = person == null ? void 0 : person.stranded) != null ? _ref2 : false) || isStranded(landing)
         });
     });
+    // A person with nothing but unmarked orgs is not graded at all: neither
+    // arrived nor stranded, so they neither start nor break a streak.
     const newestFirst = [
         ...people.values()
-    ].sort((a, b)=>b.latestMs - a.latestMs);
-    const strandedPeople = newestFirst.filter((person)=>!person.landed).length;
+    ].filter((person)=>person.arrived || person.stranded).sort((a, b)=>b.latestMs - a.latestMs);
+    const strandedPeople = newestFirst.filter((person)=>!person.arrived).length;
     let strandedStreak = 0;
-    while(strandedStreak < newestFirst.length && !newestFirst[strandedStreak].landed){
+    while(strandedStreak < newestFirst.length && !newestFirst[strandedStreak].arrived){
         strandedStreak += 1;
     }
     const stranded = strandedStreak >= maxStranded;
@@ -601,6 +616,7 @@ export function signupLandingHealth(orgs, ms, maxStranded = MAX_STRANDED_SIGNUPS
         strandedOrgs,
         strandedPeople,
         strandedStreak,
+        unmarkedOrgs,
         orgsInWindow: orgs.length
     }, shape);
 }
@@ -1947,6 +1963,97 @@ export async function writeCronBeat(store, jobId, now = Date.now()) {
         return false;
     }
 }
+/**
+ * How long a job's own document may lag its summary entry when the jobs are
+ * marked together (AGL-3932).
+ *
+ * The reader judges from the summary and opens a job's own document only to
+ * confirm an entry the summary calls late, so a job marked every fifteen
+ * minutes does not need its own document rewritten every fifteen minutes:
+ * half an hour, under every plugin job's forty-five-minute grace, keeps the
+ * confirming mark fresh enough to agree with a summary that has stopped.
+ */ export const CRON_BEAT_OWN_MARK_REFRESH_MS = 30 * 60000;
+/**
+ * The marks one run leaves for several jobs at once — the plugin-crons route
+ * stamps twenty jobs a run, and {@link writeCronBeat} per job was forty
+ * writes every fifteen minutes, half of everything the platform wrote
+ * (AGL-3932).
+ *
+ * One summary write carries every job's entry (merged, like the single mark's).
+ * A job's own document is rewritten only when the summary's current entry
+ * for it is missing or older than {@link CRON_BEAT_OWN_MARK_REFRESH_MS},
+ * which one read of the summary tells; a store without `get`, or a summary
+ * that cannot be read or written, falls back to the single-mark shape for
+ * every job, so no run can leave fewer marks than before.
+ *
+ * NEVER THROWS, as {@link writeCronBeat} never throws, and for the same
+ * reason. Returns false only when nothing landed for some job.
+ */ export async function writeCronBeats(store, jobIds, now = Date.now()) {
+    const ids = [
+        ...new Set(jobIds)
+    ].filter((id)=>!CRON_BEAT_RESERVED_DOCS.has(id));
+    if (!ids.length) return true;
+    const beats = store.collection(CRON_BEAT_COLLECTION);
+    const summary = beats.doc(CRON_BEAT_SUMMARY_DOC);
+    let current = null;
+    try {
+        if (summary.get) {
+            const snapshot = await summary.get();
+            current = new Map(cronBeatsFromSummary(snapshot.get('beats')).map((beat)=>[
+                    beat.jobId,
+                    beat.atMs
+                ]));
+        }
+    } catch (unused) {
+    // Unreadable: every job gets its own mark below, as before.
+    }
+    const refresh = current === null ? ids : ids.filter((id)=>{
+        const last = current.get(id);
+        return last === undefined || now - last >= CRON_BEAT_OWN_MARK_REFRESH_MS || now < last;
+    });
+    let landed = true;
+    for (const id of refresh){
+        try {
+            await beats.doc(id).set({
+                jobId: id,
+                atMs: now,
+                at: new Date(now).toISOString()
+            }, {
+                merge: true
+            });
+        } catch (unused) {
+            landed = false;
+        }
+    }
+    try {
+        await summary.set({
+            beats: Object.fromEntries(ids.map((id)=>[
+                    id,
+                    now
+                ]))
+        }, {
+            merge: true
+        });
+    } catch (unused) {
+        // The summary is what the reader reads first; without it, give every job
+        // the mark the reader confirms against, as the single mark would have.
+        for (const id of ids){
+            if (refresh.includes(id)) continue;
+            try {
+                await beats.doc(id).set({
+                    jobId: id,
+                    atMs: now,
+                    at: new Date(now).toISOString()
+                }, {
+                    merge: true
+                });
+            } catch (unused) {
+                landed = false;
+            }
+        }
+    }
+    return landed;
+}
 /**
  * The beats a summary document holds, ignoring anything malformed.
  *