@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/webhook-delivery.js

@@ -0,0 +1,413 @@
+/**
+ * @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.
+ */ /**
+ * DID THE WEBHOOK ACTUALLY DO ANYTHING? (AGL-1954)
+ *
+ * Every signal we have about the billing webhook is a signal about the
+ * REQUEST. Stripe records `delivery_success` off the status code. The
+ * idempotency claim in `stripeEvents` records that the signature verified and
+ * the handler was entered. `/api/health/billing` (AGL-1924) counts what
+ * Stripe attempted and failed to deliver. All three read green for the one
+ * failure this module exists to catch: **a handler that answers 200 and moves
+ * nothing.**
+ *
+ * That is not hypothetical here. AGL-1798 is exactly it — `charge.refunded`
+ * was never subscribed on the live destination, so AGL-1546's entitlement
+ * revocation had no trigger, and every other indicator looked fine for as
+ * long as it lasted. AGL-1551 is the same class from the other side: a week
+ * of 100% rejected deliveries behind a green "Active" badge.
+ *
+ * ## The honest signal is an EFFECT, not a return code
+ *
+ * A check that asserts "the handler ran" is nearly as blind as the 200 —
+ * the handler DID run in the AGL-1798 shape, it just had no work registered
+ * for the event. So the route reports what it COMMITTED: an org's plan
+ * mirrored, a `platformRevenue` row written, a refund stamped, an orphan
+ * recorded, an audit row appended, a plugin claiming the event. Those are the
+ * things whose absence is the bug.
+ *
+ * ## Three outcomes, and conflating the middle two is its own failure
+ *
+ * A binary "did it write something" would fire on every legitimately
+ * irrelevant delivery — a tenant shopper's subscription carries no
+ * `metadata.orgId` and correctly moves nothing on OUR side; a marketplace
+ * refund resolves to no workspace customer and is correctly left to the
+ * plugins; a `won` dispute nobody claimed reversed no money and correctly
+ * wakes nobody. Alerting on those is alert fatigue, which ends with the alarm
+ * muted and the real one lost inside it.
+ *
+ * So a branch that decides an event is not its business must SAY SO, by
+ * name, through {@link WebhookEffectLedger.skip}. That is what separates:
+ *
+ * | outcome   | meaning                                            | alarm |
+ * |-----------|----------------------------------------------------|-------|
+ * | `acted`   | something durable committed, or a plugin claimed it | no    |
+ * | `ignored` | a branch named a reason, or we never asked for this event type | no |
+ * | `inert`   | an event we deliberately subscribe to produced NEITHER | YES  |
+ *
+ * `inert` is the whole point. Falling off the end of the dispatch with no
+ * effect and no stated reason is precisely what a deleted write, an
+ * unregistered plugin handler, or a renamed event type looks like from
+ * inside the process — and it is the only one of the three that nothing else
+ * in this system can see.
+ *
+ * ## Why the "did we ask for it" test is the required-events list
+ *
+ * Stripe delivers what the destination is subscribed to, and the destination
+ * is created by `tools/scripts/setup-stripe.mjs` from `WEBHOOK_EVENTS`. An
+ * event type outside that list reaching us is either a hand-added
+ * subscription or a Connect delivery arriving at the platform destination —
+ * unremarkable, and never our silent-drop bug, because we never claimed to
+ * handle it. An event type INSIDE it is one we went out of our way to ask
+ * Stripe for, so producing nothing from it is a contradiction by
+ * construction.
+ *
+ * `REQUIRED_WEBHOOK_EVENTS` below is a copy of that list, and a copy is a
+ * drift hazard — so `webhook-delivery.spec.ts` reads the `.mjs` and fails on
+ * any divergence, in either direction. The alternative (moving the list
+ * across the nx boundary out of `tools/`) is a wider change than this
+ * warrants and is tracked on AGL-1948.
+ *
+ * Pure: no clock, no I/O, no Firestore. The route records, this decides, the
+ * spec exercises every branch without a network.
+ */ /** What a single delivery turned out to be. */ /**
+ * The event types the platform destination is subscribed to, mirroring
+ * `WEBHOOK_EVENTS` in `tools/scripts/lib/stripe-webhook-health.mjs`.
+ *
+ * The list is the definition of "we asked for this", which is what makes a
+ * no-op delivery of one of them a defect rather than a non-event. Kept in
+ * the same order as the source so a diff between the two reads cleanly.
+ */ export const REQUIRED_WEBHOOK_EVENTS = [
+    'customer.subscription.created',
+    'customer.subscription.updated',
+    'customer.subscription.deleted',
+    'checkout.session.completed',
+    'invoice.finalized',
+    'invoice.paid',
+    'invoice.payment_failed',
+    'charge.refunded',
+    'charge.dispute.created',
+    'charge.dispute.closed',
+    // AI overage charged as it accrues (AGL-3011), in the source list's order.
+    'invoice.voided',
+    'invoice.marked_uncollectible',
+    'customer.updated',
+    'payment_method.attached',
+    'payment_method.detached'
+];
+/**
+ * How the CONNECT destination identifies itself (AGL-1948), mirroring
+ * `CONNECT_SCOPE_METADATA_KEY` / `CONNECT_SCOPE_METADATA_VALUE` in
+ * `tools/scripts/lib/stripe-webhook-health.mjs`.
+ *
+ * Connected-account events are delivered only to a destination created with
+ * `connect: true`, and Stripe's API does not report that flag back on the
+ * endpoint object — so the destination is identified by metadata we set at
+ * creation instead. Same copy-and-guard arrangement as the list above.
+ */ export const CONNECT_SCOPE_METADATA_KEY = 'aglyn_scope';
+export const CONNECT_SCOPE_METADATA_VALUE = 'connect';
+/**
+ * What the Connect destination must carry, mirroring
+ * `CONNECT_WEBHOOK_EVENTS` in the same script lib.
+ *
+ * `account.updated` is the whole point of it: AGL-1997's `syncConnectAccountStatus`
+ * is what stops a merchant whose Stripe account was later restricted from
+ * going on selling against a stale `stripeChargesEnabled`, with the SHOPPER
+ * meeting the failure at payment time. Without this event the handler cannot
+ * run — which is exactly the state AGL-2122 found and fixed.
+ */ export const REQUIRED_CONNECT_WEBHOOK_EVENTS = [
+    'account.updated'
+];
+/**
+ * Does this Stripe endpoint object carry our Connect scope marker?
+ *
+ * Coverage for it reuses `unsubscribedRequiredEvents` with
+ * `REQUIRED_CONNECT_WEBHOOK_EVENTS` as the `required` argument — the wildcard
+ * and null handling are identical questions, and a second copy of that logic
+ * is a second place for it to drift.
+ */ export function isConnectWebhookEndpoint(endpoint) {
+    const metadata = endpoint == null ? void 0 : endpoint.metadata;
+    return (metadata == null ? void 0 : metadata[CONNECT_SCOPE_METADATA_KEY]) === CONNECT_SCOPE_METADATA_VALUE;
+}
+export function createWebhookEffectLedger() {
+    const effects = [];
+    const skips = [];
+    return {
+        effects,
+        skips,
+        effect (name) {
+            effects.push(name);
+        },
+        skip (reason) {
+            skips.push(reason);
+        }
+    };
+}
+/** Firestore methods that MUTATE. Everything else is a read or a builder. */ const WRITE_METHODS = new Set([
+    'set',
+    'update',
+    'create',
+    'delete',
+    'add'
+]);
+/**
+ * Wrap a Firestore handle so every write it commits lands in the ledger.
+ *
+ * ## Why this exists rather than a `ledger.effect()` beside each write
+ *
+ * A hand-placed note next to a write is a check that CANNOT FAIL in the one
+ * way that matters. Delete the write and leave the note, and the ledger
+ * cheerfully reports an effect that never happened — which is the same
+ * "asserts its own literals" defect the health probes are written to avoid.
+ * The note has to be caused by the write, not merely adjacent to it.
+ *
+ * So the effect is recorded from INSIDE the call, after it resolves. A write
+ * that throws records nothing (it did not commit); a write that is deleted
+ * from the source records nothing (it is not called). There is no edit to
+ * the handler that removes the work and keeps the signal.
+ *
+ * ## What it deliberately does not see
+ *
+ * Writes issued through a DIFFERENT Firestore handle — the shared
+ * `tenant-data-admin` writers (`writeOrgBilling`, `notifyOrgAdmins`,
+ * `notifyStaff`), which each open their own — and anything a plugin does
+ * inside its own handler. Those are noted explicitly by the caller where
+ * they are the only consequence of a branch, and the comments at those call
+ * sites say so. The boundary is stated rather than hidden: this covers the
+ * route's own writes, which is where the route's own bugs live.
+ *
+ * A Proxy rather than a hand-written facade because the wrapped object is
+ * passed on to `updateExisting` and friends, which call methods this module
+ * has never heard of. A facade would have to enumerate them and would
+ * silently drop the ones it forgot.
+ */ export function observeWrites(handle, ledger, label = 'firestore') {
+    return new Proxy(handle, {
+        get (target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== 'function' || typeof property !== 'string') {
+                return value;
+            }
+            const method = property;
+            return (...args)=>{
+                const result = value.apply(target, args);
+                // `collection('orgs')` names the thing being written, so the ledger
+                // reads `orgs.update` rather than `firestore.update`. Everything
+                // else inherits the label it was reached through.
+                const nextLabel = method === 'collection' && typeof args[0] === 'string' ? args[0] : label;
+                if (WRITE_METHODS.has(method)) {
+                    // Recorded on RESOLUTION. A rejected write committed nothing and
+                    // must not read as an effect.
+                    return Promise.resolve(result).then((settled)=>{
+                        ledger.effect(`${nextLabel}.${method}`);
+                        return settled;
+                    });
+                }
+                // Builders (`collection`, `doc`, `where`, `limit`) return objects
+                // that can themselves be written through, so the wrapper follows
+                // them. Thenables are returned bare: wrapping a promise would make
+                // `then` look like a builder and recurse forever.
+                if (result && typeof result === 'object' && typeof result.then !== 'function') {
+                    return observeWrites(result, ledger, nextLabel);
+                }
+                return result;
+            };
+        }
+    });
+}
+/**
+ * Classify one delivery.
+ *
+ * Order is the argument:
+ *
+ * 1. **Any effect, or any plugin claim, wins.** A delivery that both wrote
+ *    something and skipped something else did work; a partially-skipped
+ *    handler is not an idle one.
+ * 2. **A named skip is an answer.** Reaching a branch that consciously
+ *    decided "not ours" is a handled event, not a dropped one.
+ * 3. **An event type we never subscribed to is not our problem.** Nothing
+ *    promised to handle it.
+ * 4. **Everything else is inert** — and by elimination that means: we asked
+ *    Stripe for this event, we received it, no handler claimed it, no branch
+ *    wrote anything, and no branch could say why.
+ */ export function classifyWebhookDelivery(input) {
+    var _input_required;
+    const { type, effects, skips, claimed } = input;
+    const required = (_input_required = input.required) != null ? _input_required : REQUIRED_WEBHOOK_EVENTS;
+    if (effects.length > 0) return {
+        outcome: 'acted',
+        reason: effects[0]
+    };
+    if (claimed) return {
+        outcome: 'acted',
+        reason: 'plugin-claimed'
+    };
+    if (skips.length > 0) return {
+        outcome: 'ignored',
+        reason: skips[0]
+    };
+    if (!required.includes(type)) {
+        return {
+            outcome: 'ignored',
+            reason: 'not-subscribed'
+        };
+    }
+    return {
+        outcome: 'inert',
+        reason: 'no-effect'
+    };
+}
+/**
+ * How long after Stripe CREATES an event its first delivery attempt may
+ * plausibly take to reach us, in seconds. Mirrors `RETRY_LAG_SECONDS` in
+ * `tools/scripts/lib/stripe-webhook-health.mjs`, under the same
+ * read-the-`.mjs`-as-text drift guard as the lists above.
+ *
+ * Calibrated against the live account on 2026-08-18: the five deliveries that
+ * succeeded first time landed in 1.0–3.7s; the one that did not —
+ * `evt_1U49XtDYHP4psn7hA9VHPnZz`, whose three 400s ARE the three failures the
+ * Stripe Dashboard was showing — landed 16,665s (4h 37m) late. Two minutes
+ * sits three orders of magnitude clear of the healthy band and still inside
+ * Stripe's first automatic retry interval, so it separates the two without
+ * straddling either.
+ */ export const RETRY_LAG_SECONDS = 120;
+/**
+ * DID THIS DELIVERY ONLY LAND ON A RETRY? (AGL-2039, the last arm of AGL-1948)
+ *
+ * ## The reconciliation this exists to close
+ *
+ * `/api/health/billing` scores EVENTS and `GET /v1/events?delivery_success=false`
+ * is a TERMINAL-state filter: it selects events that are still pending or
+ * failed EVERY attempt. An event that 400s three times and then succeeds on
+ * the fourth reads back `delivery_success: true` and is, to that filter,
+ * indistinguishable from one that succeeded immediately. The Stripe Dashboard
+ * scores delivery ATTEMPTS, so the same hour reads 0% here and 30% there —
+ * and both numbers are right. The three real failures were visible only in
+ * the second reading, and each was a mirror that did not run when it should
+ * have.
+ *
+ * The recoverable half of the attempt history is in our own data. The route
+ * claims `stripeEvents/{id}` AFTER signature verification and DELETES the
+ * claim when a handler throws, so the stamp always records the attempt that
+ * actually got through. The distance from `event.created` to that stamp is
+ * the delivery lag, and a lag of minutes means an earlier attempt failed.
+ *
+ * ## Why this is decided at WRITE time, not at read time
+ *
+ * The obvious implementation reads `receivedAt` off every claim document in
+ * the window and subtracts. That turns a `.count()` aggregation — one
+ * integer, zero documents read — into a document scan on a PUBLIC,
+ * unauthenticated health endpoint polled every five minutes. Deciding here,
+ * once, at the moment of the claim, lets the probe stay an aggregation over a
+ * marker field, exactly like AGL-1954's `inertAtMs`.
+ *
+ * ## Absent, zero and unknown are THREE different things
+ *
+ * `strictNullChecks` is off repo-wide, so an absent `created` folds to falsy
+ * and a naive `Number(event?.created ?? 0)` yields 0 — which subtracts to a
+ * lag of ~1.7 BILLION seconds and reports every such delivery as a retry,
+ * forever, on a perfectly healthy webhook. A monitoring signal that reds on
+ * its own missing input is worse than no signal, because it is the thing that
+ * gets muted. So each of those inputs is rejected by name:
+ *
+ * | input                       | attempt    | reason                  |
+ * |-----------------------------|------------|-------------------------|
+ * | field absent / null         | `unknown`  | `created-absent`        |
+ * | a string, NaN, Infinity     | `unknown`  | `created-not-a-number`  |
+ * | `0` or negative             | `unknown`  | `created-non-positive`  |
+ * | our own stamp unusable      | `unknown`  | `received-unusable`     |
+ * | created in the FUTURE by more than the bar | `unknown` | `clock-skew` |
+ *
+ * A lag between `-threshold` and `+threshold` is `first-attempt`: sub-second
+ * clock skew between Stripe's clock and ours is ordinary and is not evidence
+ * of anything.
+ *
+ * Pure: no clock, no I/O. The caller supplies both timestamps.
+ */ export function classifyDeliveryLag(input) {
+    var _input_thresholdSeconds;
+    const threshold = (_input_thresholdSeconds = input.thresholdSeconds) != null ? _input_thresholdSeconds : RETRY_LAG_SECONDS;
+    const created = input.eventCreatedSeconds;
+    if (created === undefined || created === null) {
+        return {
+            attempt: 'unknown',
+            lagSeconds: null,
+            reason: 'created-absent'
+        };
+    }
+    if (typeof created !== 'number' || !Number.isFinite(created)) {
+        return {
+            attempt: 'unknown',
+            lagSeconds: null,
+            reason: 'created-not-a-number'
+        };
+    }
+    // Zero is the value an absent field folds to under the repo's null rules,
+    // and no Stripe event was created at the epoch. Rejected by name so it can
+    // never be mistaken for a measurement.
+    if (created <= 0) {
+        return {
+            attempt: 'unknown',
+            lagSeconds: null,
+            reason: 'created-non-positive'
+        };
+    }
+    const received = input.receivedAtMs;
+    if (typeof received !== 'number' || !Number.isFinite(received) || received <= 0) {
+        return {
+            attempt: 'unknown',
+            lagSeconds: null,
+            reason: 'received-unusable'
+        };
+    }
+    const lagSeconds = received / 1000 - created;
+    // An event stamped in OUR future by more than the threshold is a clock
+    // disagreement, not a fast delivery, and reporting it as a healthy first
+    // attempt would be an answer we cannot support.
+    if (lagSeconds < -threshold) {
+        return {
+            attempt: 'unknown',
+            lagSeconds: null,
+            reason: 'clock-skew'
+        };
+    }
+    return {
+        attempt: lagSeconds > threshold ? 'retried' : 'first-attempt',
+        lagSeconds,
+        reason: 'measured'
+    };
+}
+/**
+ * Which required events is a destination NOT subscribed to? (AGL-1948)
+ *
+ * The same blind spot from the configuration side, and the cheaper half of
+ * it: a subscription removed by hand in the Stripe dashboard produces no
+ * failed delivery, no rejected request and no inert one either — Stripe
+ * simply stops sending, and every count on the health probe reads a
+ * perfectly healthy zero. `charge.refunded` was missing from the live
+ * endpoint for exactly this reason (AGL-1798) and the only thing that ever
+ * noticed was a script nobody ran.
+ *
+ * `['*']` is Stripe's wildcard subscription and covers everything.
+ *
+ * Returns the names, sorted, so the probe body is stable and a diff between
+ * two readings is meaningful.
+ */ export function unsubscribedRequiredEvents(enabledEvents, required = REQUIRED_WEBHOOK_EVENTS) {
+    if (!enabledEvents) return [];
+    if (enabledEvents.includes('*')) return [];
+    const enabled = new Set(enabledEvents);
+    return required.filter((event)=>!enabled.has(event)).sort();
+}
+
+//# sourceMappingURL=webhook-delivery.js.map

package/src/lib/app-utils/webhook-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/webhook-delivery.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\n/**\n * DID THE WEBHOOK ACTUALLY DO ANYTHING? (AGL-1954)\n *\n * Every signal we have about the billing webhook is a signal about the\n * REQUEST. Stripe records `delivery_success` off the status code. The\n * idempotency claim in `stripeEvents` records that the signature verified and\n * the handler was entered. `/api/health/billing` (AGL-1924) counts what\n * Stripe attempted and failed to deliver. All three read green for the one\n * failure this module exists to catch: **a handler that answers 200 and moves\n * nothing.**\n *\n * That is not hypothetical here. AGL-1798 is exactly it — `charge.refunded`\n * was never subscribed on the live destination, so AGL-1546's entitlement\n * revocation had no trigger, and every other indicator looked fine for as\n * long as it lasted. AGL-1551 is the same class from the other side: a week\n * of 100% rejected deliveries behind a green \"Active\" badge.\n *\n * ## The honest signal is an EFFECT, not a return code\n *\n * A check that asserts \"the handler ran\" is nearly as blind as the 200 —\n * the handler DID run in the AGL-1798 shape, it just had no work registered\n * for the event. So the route reports what it COMMITTED: an org's plan\n * mirrored, a `platformRevenue` row written, a refund stamped, an orphan\n * recorded, an audit row appended, a plugin claiming the event. Those are the\n * things whose absence is the bug.\n *\n * ## Three outcomes, and conflating the middle two is its own failure\n *\n * A binary \"did it write something\" would fire on every legitimately\n * irrelevant delivery — a tenant shopper's subscription carries no\n * `metadata.orgId` and correctly moves nothing on OUR side; a marketplace\n * refund resolves to no workspace customer and is correctly left to the\n * plugins; a `won` dispute nobody claimed reversed no money and correctly\n * wakes nobody. Alerting on those is alert fatigue, which ends with the alarm\n * muted and the real one lost inside it.\n *\n * So a branch that decides an event is not its business must SAY SO, by\n * name, through {@link WebhookEffectLedger.skip}. That is what separates:\n *\n * | outcome   | meaning                                            | alarm |\n * |-----------|----------------------------------------------------|-------|\n * | `acted`   | something durable committed, or a plugin claimed it | no    |\n * | `ignored` | a branch named a reason, or we never asked for this event type | no |\n * | `inert`   | an event we deliberately subscribe to produced NEITHER | YES  |\n *\n * `inert` is the whole point. Falling off the end of the dispatch with no\n * effect and no stated reason is precisely what a deleted write, an\n * unregistered plugin handler, or a renamed event type looks like from\n * inside the process — and it is the only one of the three that nothing else\n * in this system can see.\n *\n * ## Why the \"did we ask for it\" test is the required-events list\n *\n * Stripe delivers what the destination is subscribed to, and the destination\n * is created by `tools/scripts/setup-stripe.mjs` from `WEBHOOK_EVENTS`. An\n * event type outside that list reaching us is either a hand-added\n * subscription or a Connect delivery arriving at the platform destination —\n * unremarkable, and never our silent-drop bug, because we never claimed to\n * handle it. An event type INSIDE it is one we went out of our way to ask\n * Stripe for, so producing nothing from it is a contradiction by\n * construction.\n *\n * `REQUIRED_WEBHOOK_EVENTS` below is a copy of that list, and a copy is a\n * drift hazard — so `webhook-delivery.spec.ts` reads the `.mjs` and fails on\n * any divergence, in either direction. The alternative (moving the list\n * across the nx boundary out of `tools/`) is a wider change than this\n * warrants and is tracked on AGL-1948.\n *\n * Pure: no clock, no I/O, no Firestore. The route records, this decides, the\n * spec exercises every branch without a network.\n */\n\n/** What a single delivery turned out to be. */\nexport type WebhookDeliveryOutcome = 'acted' | 'ignored' | 'inert'\n\n/**\n * The event types the platform destination is subscribed to, mirroring\n * `WEBHOOK_EVENTS` in `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * The list is the definition of \"we asked for this\", which is what makes a\n * no-op delivery of one of them a defect rather than a non-event. Kept in\n * the same order as the source so a diff between the two reads cleanly.\n */\nexport const REQUIRED_WEBHOOK_EVENTS: readonly string[] = [\n  'customer.subscription.created',\n  'customer.subscription.updated',\n  'customer.subscription.deleted',\n  'checkout.session.completed',\n  'invoice.finalized',\n  'invoice.paid',\n  'invoice.payment_failed',\n  'charge.refunded',\n  'charge.dispute.created',\n  'charge.dispute.closed',\n  // AI overage charged as it accrues (AGL-3011), in the source list's order.\n  'invoice.voided',\n  'invoice.marked_uncollectible',\n  'customer.updated',\n  'payment_method.attached',\n  'payment_method.detached',\n]\n\n/**\n * How the CONNECT destination identifies itself (AGL-1948), mirroring\n * `CONNECT_SCOPE_METADATA_KEY` / `CONNECT_SCOPE_METADATA_VALUE` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * Connected-account events are delivered only to a destination created with\n * `connect: true`, and Stripe's API does not report that flag back on the\n * endpoint object — so the destination is identified by metadata we set at\n * creation instead. Same copy-and-guard arrangement as the list above.\n */\nexport const CONNECT_SCOPE_METADATA_KEY = 'aglyn_scope'\nexport const CONNECT_SCOPE_METADATA_VALUE = 'connect'\n\n/**\n * What the Connect destination must carry, mirroring\n * `CONNECT_WEBHOOK_EVENTS` in the same script lib.\n *\n * `account.updated` is the whole point of it: AGL-1997's `syncConnectAccountStatus`\n * is what stops a merchant whose Stripe account was later restricted from\n * going on selling against a stale `stripeChargesEnabled`, with the SHOPPER\n * meeting the failure at payment time. Without this event the handler cannot\n * run — which is exactly the state AGL-2122 found and fixed.\n */\nexport const REQUIRED_CONNECT_WEBHOOK_EVENTS: readonly string[] = ['account.updated']\n\n/**\n * Does this Stripe endpoint object carry our Connect scope marker?\n *\n * Coverage for it reuses `unsubscribedRequiredEvents` with\n * `REQUIRED_CONNECT_WEBHOOK_EVENTS` as the `required` argument — the wildcard\n * and null handling are identical questions, and a second copy of that logic\n * is a second place for it to drift.\n */\nexport function isConnectWebhookEndpoint(endpoint: unknown): boolean {\n  const metadata = (endpoint as { metadata?: Record<string, unknown> })?.metadata\n  return metadata?.[CONNECT_SCOPE_METADATA_KEY] === CONNECT_SCOPE_METADATA_VALUE\n}\n\n/**\n * A per-delivery record of what actually committed.\n *\n * Deliberately append-only and stringly-typed: the reasons are read by a\n * human in a log line and by a spec, never switched on. Keeping it dumb is\n * what stops it growing into a second dispatch table that can disagree with\n * the real one.\n */\nexport interface WebhookEffectLedger {\n  /** Durable things this delivery committed, in the order they landed. */\n  readonly effects: readonly string[]\n  /** Reasons a branch decided the event was none of its business. */\n  readonly skips: readonly string[]\n  /**\n   * Record a committed effect. Call this AFTER the write it names, so a\n   * throw between the two cannot claim an effect that never landed.\n   */\n  effect(name: string): void\n  /**\n   * Record a deliberate no-op and why. This is the difference between \"not\n   * ours\" and \"broken\", and it is the half that prevents alert fatigue.\n   */\n  skip(reason: string): void\n}\n\nexport function createWebhookEffectLedger(): WebhookEffectLedger {\n  const effects: string[] = []\n  const skips: string[] = []\n  return {\n    effects,\n    skips,\n    effect(name: string) {\n      effects.push(name)\n    },\n    skip(reason: string) {\n      skips.push(reason)\n    },\n  }\n}\n\n/** Firestore methods that MUTATE. Everything else is a read or a builder. */\nconst WRITE_METHODS = new Set(['set', 'update', 'create', 'delete', 'add'])\n\n/**\n * Wrap a Firestore handle so every write it commits lands in the ledger.\n *\n * ## Why this exists rather than a `ledger.effect()` beside each write\n *\n * A hand-placed note next to a write is a check that CANNOT FAIL in the one\n * way that matters. Delete the write and leave the note, and the ledger\n * cheerfully reports an effect that never happened — which is the same\n * \"asserts its own literals\" defect the health probes are written to avoid.\n * The note has to be caused by the write, not merely adjacent to it.\n *\n * So the effect is recorded from INSIDE the call, after it resolves. A write\n * that throws records nothing (it did not commit); a write that is deleted\n * from the source records nothing (it is not called). There is no edit to\n * the handler that removes the work and keeps the signal.\n *\n * ## What it deliberately does not see\n *\n * Writes issued through a DIFFERENT Firestore handle — the shared\n * `tenant-data-admin` writers (`writeOrgBilling`, `notifyOrgAdmins`,\n * `notifyStaff`), which each open their own — and anything a plugin does\n * inside its own handler. Those are noted explicitly by the caller where\n * they are the only consequence of a branch, and the comments at those call\n * sites say so. The boundary is stated rather than hidden: this covers the\n * route's own writes, which is where the route's own bugs live.\n *\n * A Proxy rather than a hand-written facade because the wrapped object is\n * passed on to `updateExisting` and friends, which call methods this module\n * has never heard of. A facade would have to enumerate them and would\n * silently drop the ones it forgot.\n */\nexport function observeWrites<T extends object>(\n  handle: T,\n  ledger: WebhookEffectLedger,\n  label = 'firestore',\n): T {\n  return new Proxy(handle, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver)\n      if (typeof value !== 'function' || typeof property !== 'string') {\n        return value\n      }\n      const method = property\n      return (...args: unknown[]) => {\n        const result = (value as (...a: unknown[]) => unknown).apply(\n          target,\n          args,\n        )\n        // `collection('orgs')` names the thing being written, so the ledger\n        // reads `orgs.update` rather than `firestore.update`. Everything\n        // else inherits the label it was reached through.\n        const nextLabel =\n          method === 'collection' && typeof args[0] === 'string'\n            ? (args[0] as string)\n            : label\n        if (WRITE_METHODS.has(method)) {\n          // Recorded on RESOLUTION. A rejected write committed nothing and\n          // must not read as an effect.\n          return Promise.resolve(result).then((settled) => {\n            ledger.effect(`${nextLabel}.${method}`)\n            return settled\n          })\n        }\n        // Builders (`collection`, `doc`, `where`, `limit`) return objects\n        // that can themselves be written through, so the wrapper follows\n        // them. Thenables are returned bare: wrapping a promise would make\n        // `then` look like a builder and recurse forever.\n        if (\n          result &&\n          typeof result === 'object' &&\n          typeof (result as { then?: unknown }).then !== 'function'\n        ) {\n          return observeWrites(result as object, ledger, nextLabel)\n        }\n        return result\n      }\n    },\n  })\n}\n\nexport interface WebhookDeliveryVerdict {\n  outcome: WebhookDeliveryOutcome\n  /** One short phrase naming WHY, for the log line and the spec. */\n  reason: string\n}\n\n/**\n * Classify one delivery.\n *\n * Order is the argument:\n *\n * 1. **Any effect, or any plugin claim, wins.** A delivery that both wrote\n *    something and skipped something else did work; a partially-skipped\n *    handler is not an idle one.\n * 2. **A named skip is an answer.** Reaching a branch that consciously\n *    decided \"not ours\" is a handled event, not a dropped one.\n * 3. **An event type we never subscribed to is not our problem.** Nothing\n *    promised to handle it.\n * 4. **Everything else is inert** — and by elimination that means: we asked\n *    Stripe for this event, we received it, no handler claimed it, no branch\n *    wrote anything, and no branch could say why.\n */\nexport function classifyWebhookDelivery(input: {\n  type: string\n  effects: readonly string[]\n  skips: readonly string[]\n  claimed: boolean\n  /** Overridable so the spec can prove the rule rather than the list. */\n  required?: readonly string[]\n}): WebhookDeliveryVerdict {\n  const { type, effects, skips, claimed } = input\n  const required = input.required ?? REQUIRED_WEBHOOK_EVENTS\n  if (effects.length > 0) return { outcome: 'acted', reason: effects[0] }\n  if (claimed) return { outcome: 'acted', reason: 'plugin-claimed' }\n  if (skips.length > 0) return { outcome: 'ignored', reason: skips[0] }\n  if (!required.includes(type)) {\n    return { outcome: 'ignored', reason: 'not-subscribed' }\n  }\n  return { outcome: 'inert', reason: 'no-effect' }\n}\n\n/**\n * How long after Stripe CREATES an event its first delivery attempt may\n * plausibly take to reach us, in seconds. Mirrors `RETRY_LAG_SECONDS` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`, under the same\n * read-the-`.mjs`-as-text drift guard as the lists above.\n *\n * Calibrated against the live account on 2026-08-18: the five deliveries that\n * succeeded first time landed in 1.0–3.7s; the one that did not —\n * `evt_1U49XtDYHP4psn7hA9VHPnZz`, whose three 400s ARE the three failures the\n * Stripe Dashboard was showing — landed 16,665s (4h 37m) late. Two minutes\n * sits three orders of magnitude clear of the healthy band and still inside\n * Stripe's first automatic retry interval, so it separates the two without\n * straddling either.\n */\nexport const RETRY_LAG_SECONDS = 120\n\n/**\n * What a delivery's lag says about the attempts BEFORE it.\n *\n * `unknown` is a first-class outcome, not a synonym for either answer. See\n * {@link classifyDeliveryLag} for why that matters more here than usual.\n */\nexport type WebhookDeliveryAttempt = 'first-attempt' | 'retried' | 'unknown'\n\n/** Why {@link classifyDeliveryLag} answered as it did. */\nexport type WebhookDeliveryLagReason =\n  | 'measured'\n  | 'created-absent'\n  | 'created-not-a-number'\n  | 'created-non-positive'\n  | 'received-unusable'\n  | 'clock-skew'\n\nexport interface WebhookDeliveryLagVerdict {\n  attempt: WebhookDeliveryAttempt\n  /** Seconds between `event.created` and our claim. Null unless `measured`. */\n  lagSeconds: number | null\n  reason: WebhookDeliveryLagReason\n}\n\n/**\n * DID THIS DELIVERY ONLY LAND ON A RETRY? (AGL-2039, the last arm of AGL-1948)\n *\n * ## The reconciliation this exists to close\n *\n * `/api/health/billing` scores EVENTS and `GET /v1/events?delivery_success=false`\n * is a TERMINAL-state filter: it selects events that are still pending or\n * failed EVERY attempt. An event that 400s three times and then succeeds on\n * the fourth reads back `delivery_success: true` and is, to that filter,\n * indistinguishable from one that succeeded immediately. The Stripe Dashboard\n * scores delivery ATTEMPTS, so the same hour reads 0% here and 30% there —\n * and both numbers are right. The three real failures were visible only in\n * the second reading, and each was a mirror that did not run when it should\n * have.\n *\n * The recoverable half of the attempt history is in our own data. The route\n * claims `stripeEvents/{id}` AFTER signature verification and DELETES the\n * claim when a handler throws, so the stamp always records the attempt that\n * actually got through. The distance from `event.created` to that stamp is\n * the delivery lag, and a lag of minutes means an earlier attempt failed.\n *\n * ## Why this is decided at WRITE time, not at read time\n *\n * The obvious implementation reads `receivedAt` off every claim document in\n * the window and subtracts. That turns a `.count()` aggregation — one\n * integer, zero documents read — into a document scan on a PUBLIC,\n * unauthenticated health endpoint polled every five minutes. Deciding here,\n * once, at the moment of the claim, lets the probe stay an aggregation over a\n * marker field, exactly like AGL-1954's `inertAtMs`.\n *\n * ## Absent, zero and unknown are THREE different things\n *\n * `strictNullChecks` is off repo-wide, so an absent `created` folds to falsy\n * and a naive `Number(event?.created ?? 0)` yields 0 — which subtracts to a\n * lag of ~1.7 BILLION seconds and reports every such delivery as a retry,\n * forever, on a perfectly healthy webhook. A monitoring signal that reds on\n * its own missing input is worse than no signal, because it is the thing that\n * gets muted. So each of those inputs is rejected by name:\n *\n * | input                       | attempt    | reason                  |\n * |-----------------------------|------------|-------------------------|\n * | field absent / null         | `unknown`  | `created-absent`        |\n * | a string, NaN, Infinity     | `unknown`  | `created-not-a-number`  |\n * | `0` or negative             | `unknown`  | `created-non-positive`  |\n * | our own stamp unusable      | `unknown`  | `received-unusable`     |\n * | created in the FUTURE by more than the bar | `unknown` | `clock-skew` |\n *\n * A lag between `-threshold` and `+threshold` is `first-attempt`: sub-second\n * clock skew between Stripe's clock and ours is ordinary and is not evidence\n * of anything.\n *\n * Pure: no clock, no I/O. The caller supplies both timestamps.\n */\nexport function classifyDeliveryLag(input: {\n  /** `event.created`, in unix SECONDS, exactly as Stripe sent it. */\n  eventCreatedSeconds: unknown\n  /** When we claimed the event, in unix MILLISECONDS. */\n  receivedAtMs: unknown\n  /** Overridable so the spec can prove the rule rather than the constant. */\n  thresholdSeconds?: number\n}): WebhookDeliveryLagVerdict {\n  const threshold = input.thresholdSeconds ?? RETRY_LAG_SECONDS\n  const created = input.eventCreatedSeconds\n  if (created === undefined || created === null) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'created-absent' }\n  }\n  if (typeof created !== 'number' || !Number.isFinite(created)) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-not-a-number',\n    }\n  }\n  // Zero is the value an absent field folds to under the repo's null rules,\n  // and no Stripe event was created at the epoch. Rejected by name so it can\n  // never be mistaken for a measurement.\n  if (created <= 0) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-non-positive',\n    }\n  }\n  const received = input.receivedAtMs\n  if (typeof received !== 'number' || !Number.isFinite(received) || received <= 0) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'received-unusable' }\n  }\n  const lagSeconds = received / 1000 - created\n  // An event stamped in OUR future by more than the threshold is a clock\n  // disagreement, not a fast delivery, and reporting it as a healthy first\n  // attempt would be an answer we cannot support.\n  if (lagSeconds < -threshold) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'clock-skew' }\n  }\n  return {\n    attempt: lagSeconds > threshold ? 'retried' : 'first-attempt',\n    lagSeconds,\n    reason: 'measured',\n  }\n}\n\n/**\n * Which required events is a destination NOT subscribed to? (AGL-1948)\n *\n * The same blind spot from the configuration side, and the cheaper half of\n * it: a subscription removed by hand in the Stripe dashboard produces no\n * failed delivery, no rejected request and no inert one either — Stripe\n * simply stops sending, and every count on the health probe reads a\n * perfectly healthy zero. `charge.refunded` was missing from the live\n * endpoint for exactly this reason (AGL-1798) and the only thing that ever\n * noticed was a script nobody ran.\n *\n * `['*']` is Stripe's wildcard subscription and covers everything.\n *\n * Returns the names, sorted, so the probe body is stable and a diff between\n * two readings is meaningful.\n */\nexport function unsubscribedRequiredEvents(\n  enabledEvents: readonly string[] | null | undefined,\n  required: readonly string[] = REQUIRED_WEBHOOK_EVENTS,\n): string[] {\n  if (!enabledEvents) return []\n  if (enabledEvents.includes('*')) return []\n  const enabled = new Set(enabledEvents)\n  return required.filter((event) => !enabled.has(event)).sort()\n}\n"],"names":["REQUIRED_WEBHOOK_EVENTS","CONNECT_SCOPE_METADATA_KEY","CONNECT_SCOPE_METADATA_VALUE","REQUIRED_CONNECT_WEBHOOK_EVENTS","isConnectWebhookEndpoint","endpoint","metadata","createWebhookEffectLedger","effects","skips","effect","name","push","skip","reason","WRITE_METHODS","Set","observeWrites","handle","ledger","label","Proxy","get","target","property","receiver","value","Reflect","method","args","result","apply","nextLabel","has","Promise","resolve","then","settled","classifyWebhookDelivery","input","type","claimed","required","length","outcome","includes","RETRY_LAG_SECONDS","classifyDeliveryLag","threshold","thresholdSeconds","created","eventCreatedSeconds","undefined","attempt","lagSeconds","Number","isFinite","received","receivedAtMs","unsubscribedRequiredEvents","enabledEvents","enabled","filter","event","sort"],"mappings":"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"}

package/src/lib/app-utils/where-used.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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.
+ */
+/**
+ * The client of the console's where-used scan (`/api/hosts/where-used`).
+ *
+ * The scan is the platform's: one route answers what references a variable, a
+ * function or a workflow across a site's published screens, layouts, workflows
+ * and variables. Its client sat in the logic plugin, so the workflows plugin
+ * imported logic to ask about a workflow. It is here beside the route it
+ * calls, and both ask the platform.
+ *
+ * Imported by its own subpath; it is not in the barrel, so a page that never
+ * asks does not carry it.
+ */
+export interface WhereUsedDependent {
+    type: 'screen' | 'layout' | 'workflow' | 'variable';
+    id: string;
+    name: string;
+    via: Array<'id' | 'name'>;
+    /** Published version scanned (screens/layouts) — deep-link target. */
+    versionId?: string;
+}
+export interface WhereUsedResult {
+    dependents: WhereUsedDependent[];
+    total: number;
+    /** Dependents holding legacy name tokens — a rename breaks these. */
+    legacyCount: number;
+}
+/** One-line summary for confirm dialogs: `2 screens, 1 workflow`. */
+export declare function summarizeDependents(result: WhereUsedResult): string;
+/**
+ * Calls the AGL-187 where-used scan for a variable/function/workflow.
+ * Fail-open: scan errors return an empty result so delete/rename flows
+ * degrade to their old (unwarned) behavior instead of blocking.
+ */
+export declare function fetchWhereUsed(user: {
+    getIdToken?: () => Promise<string>;
+} | null | undefined, body: {
+    hostId: string;
+    kind: 'variable' | 'function' | 'workflow';
+    id: string;
+    name?: string;
+}): Promise<WhereUsedResult>;

package/src/lib/app-utils/where-used.js

@@ -0,0 +1,59 @@
+/**
+ * @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 { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+const DEPENDENT_TYPE_LABELS = {
+    screen: 'screen',
+    layout: 'layout',
+    workflow: 'workflow',
+    variable: 'variable'
+};
+/** One-line summary for confirm dialogs: `2 screens, 1 workflow`. */ export function summarizeDependents(result) {
+    const counts = new Map();
+    for (const dependent of result.dependents){
+        var _counts_get;
+        const label = DEPENDENT_TYPE_LABELS[dependent.type];
+        counts.set(label, ((_counts_get = counts.get(label)) != null ? _counts_get : 0) + 1);
+    }
+    return [
+        ...counts.entries()
+    ].map(([label, count])=>`${count} ${label}${count === 1 ? '' : 's'}`).join(', ');
+}
+/**
+ * Calls the AGL-187 where-used scan for a variable/function/workflow.
+ * Fail-open: scan errors return an empty result so delete/rename flows
+ * degrade to their old (unwarned) behavior instead of blocking.
+ */ export async function fetchWhereUsed(user, body) {
+    try {
+        const response = await authorizedFetch(user, '/api/hosts/where-used', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body)
+        });
+        if (!response.ok) throw new Error(`Scan failed (${response.status})`);
+        return await response.json();
+    } catch (error) {
+        console.error(error);
+        return {
+            dependents: [],
+            total: 0,
+            legacyCount: 0
+        };
+    }
+}
+
+//# sourceMappingURL=where-used.js.map

package/src/lib/app-utils/where-used.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/where-used.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 { authorizedFetch } from '@aglyn/shared-util-http/authorized-token'\n\n/**\n * The client of the console's where-used scan (`/api/hosts/where-used`).\n *\n * The scan is the platform's: one route answers what references a variable, a\n * function or a workflow across a site's published screens, layouts, workflows\n * and variables. Its client sat in the logic plugin, so the workflows plugin\n * imported logic to ask about a workflow. It is here beside the route it\n * calls, and both ask the platform.\n *\n * Imported by its own subpath; it is not in the barrel, so a page that never\n * asks does not carry it.\n */\n\nexport interface WhereUsedDependent {\n  type: 'screen' | 'layout' | 'workflow' | 'variable'\n  id: string\n  name: string\n  via: Array<'id' | 'name'>\n  /** Published version scanned (screens/layouts) — deep-link target. */\n  versionId?: string\n}\n\nexport interface WhereUsedResult {\n  dependents: WhereUsedDependent[]\n  total: number\n  /** Dependents holding legacy name tokens — a rename breaks these. */\n  legacyCount: number\n}\n\nconst DEPENDENT_TYPE_LABELS: Record<WhereUsedDependent['type'], string> = {\n  screen: 'screen',\n  layout: 'layout',\n  workflow: 'workflow',\n  variable: 'variable',\n}\n\n/** One-line summary for confirm dialogs: `2 screens, 1 workflow`. */\nexport function summarizeDependents(result: WhereUsedResult): string {\n  const counts = new Map<string, number>()\n  for (const dependent of result.dependents) {\n    const label = DEPENDENT_TYPE_LABELS[dependent.type]\n    counts.set(label, (counts.get(label) ?? 0) + 1)\n  }\n  return [...counts.entries()]\n    .map(([label, count]) => `${count} ${label}${count === 1 ? '' : 's'}`)\n    .join(', ')\n}\n\n/**\n * Calls the AGL-187 where-used scan for a variable/function/workflow.\n * Fail-open: scan errors return an empty result so delete/rename flows\n * degrade to their old (unwarned) behavior instead of blocking.\n */\nexport async function fetchWhereUsed(\n  user: { getIdToken?: () => Promise<string> } | null | undefined,\n  body: {\n    hostId: string\n    kind: 'variable' | 'function' | 'workflow'\n    id: string\n    name?: string\n  },\n): Promise<WhereUsedResult> {\n  try {\n    const response = await authorizedFetch(user, '/api/hosts/where-used', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n    })\n    if (!response.ok) throw new Error(`Scan failed (${response.status})`)\n    return (await response.json()) as WhereUsedResult\n  } catch (error) {\n    console.error(error)\n    return { dependents: [], total: 0, legacyCount: 0 }\n  }\n}\n"],"names":["authorizedFetch","DEPENDENT_TYPE_LABELS","screen","layout","workflow","variable","summarizeDependents","result","counts","Map","dependent","dependents","label","type","set","get","entries","map","count","join","fetchWhereUsed","user","body","response","method","headers","JSON","stringify","ok","Error","status","json","error","console","total","legacyCount"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,eAAe,QAAQ,2CAA0C;AA+B1E,MAAMC,wBAAoE;IACxEC,QAAQ;IACRC,QAAQ;IACRC,UAAU;IACVC,UAAU;AACZ;AAEA,mEAAmE,GACnE,OAAO,SAASC,oBAAoBC,MAAuB;IACzD,MAAMC,SAAS,IAAIC;IACnB,KAAK,MAAMC,aAAaH,OAAOI,UAAU,CAAE;YAEtBH;QADnB,MAAMI,QAAQX,qBAAqB,CAACS,UAAUG,IAAI,CAAC;QACnDL,OAAOM,GAAG,CAACF,OAAO,EAACJ,cAAAA,OAAOO,GAAG,CAACH,kBAAXJ,cAAqB,KAAK;IAC/C;IACA,OAAO;WAAIA,OAAOQ,OAAO;KAAG,CACzBC,GAAG,CAAC,CAAC,CAACL,OAAOM,MAAM,GAAK,GAAGA,MAAM,CAAC,EAAEN,QAAQM,UAAU,IAAI,KAAK,KAAK,EACpEC,IAAI,CAAC;AACV;AAEA;;;;CAIC,GACD,OAAO,eAAeC,eACpBC,IAA+D,EAC/DC,IAKC;IAED,IAAI;QACF,MAAMC,WAAW,MAAMvB,gBAAgBqB,MAAM,yBAAyB;YACpEG,QAAQ;YACRC,SAAS;gBAAE,gBAAgB;YAAmB;YAC9CH,MAAMI,KAAKC,SAAS,CAACL;QACvB;QACA,IAAI,CAACC,SAASK,EAAE,EAAE,MAAM,IAAIC,MAAM,CAAC,aAAa,EAAEN,SAASO,MAAM,CAAC,CAAC,CAAC;QACpE,OAAQ,MAAMP,SAASQ,IAAI;IAC7B,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAACA;QACd,OAAO;YAAErB,YAAY,EAAE;YAAEuB,OAAO;YAAGC,aAAa;QAAE;IACpD;AACF"}