@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/usage/assist-refusals.js

@@ -0,0 +1,79 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ // Straight from the SDK, not the admin barrel, for the reason `assist-usage.ts`
+// gives at its head: the statics need no app, and the barrel would drag the
+// default-app initialization into every unit test that touches a counter.
+import { FieldValue } from "firebase-admin/firestore";
+/**
+ * Every reason, in the order the card and the leaderboard list them: the
+ * workspace's own four first, then an allotment a manager set (AGL-2942),
+ * then the Free taste's (AGL-2925), which only a Free workspace can be
+ * refused by.
+ */ export const ASSIST_REFUSAL_REASONS = [
+    'band',
+    'cap',
+    'messages',
+    'budget',
+    'allotment',
+    'account',
+    'requests',
+    'refusals',
+    'platform'
+];
+export function recordAssistRefusal(firestore, orgId, month, reason) {
+    try {
+        const ref = firestore.collection('orgs').doc(orgId).collection('assistUsage').doc(month);
+        // `set(…, { merge: true })`, never `update()`: the month document does
+        // not exist before the org's first admitted message, and a refusal can
+        // come first — a Free workspace at its daily cap on a fresh month.
+        void Promise.resolve(ref.set({
+            month,
+            refusals: {
+                [reason]: FieldValue.increment(1)
+            }
+        }, {
+            merge: true
+        })).catch(()=>undefined);
+    } catch (unused) {
+    // A double without `set`, a ref that could not be built — the refusal
+    // has already been decided and this must not change that.
+    }
+}
+/**
+ * The `refusals` map off a month document as a complete, zero-filled record.
+ *
+ * Zero-filled rather than sparse because the readers render every reason:
+ * "band 0" beside "cap 12" is the finding, and a sparse map would make the
+ * reader guess whether an absent key meant none or not yet counted. A
+ * non-numeric or negative value reads as 0 — the counter is only ever
+ * incremented, so anything else is a hand edit.
+ */ export function assistRefusalCounts(raw) {
+    const map = raw != null ? raw : {};
+    const counts = Object.fromEntries(ASSIST_REFUSAL_REASONS.map((reason)=>{
+        var _map_reason;
+        const value = Number((_map_reason = map[reason]) != null ? _map_reason : 0);
+        return [
+            reason,
+            Number.isFinite(value) && value > 0 ? Math.floor(value) : 0
+        ];
+    }));
+    return _extends({}, counts, {
+        total: ASSIST_REFUSAL_REASONS.reduce((sum, reason)=>sum + counts[reason], 0)
+    });
+}
+
+//# sourceMappingURL=assist-refusals.js.map

package/src/lib/usage/assist-refusals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/assist-refusals.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// Straight from the SDK, not the admin barrel, for the reason `assist-usage.ts`\n// gives at its head: the statics need no app, and the barrel would drag the\n// default-app initialization into every unit test that touches a counter.\nimport { FieldValue } from 'firebase-admin/firestore'\nimport type { AiRefusedBy } from '../model/ai-allotments'\n\n/**\n * THE PER-ORG REFUSAL COUNTER (AGL-2930).\n *\n * `reserveAssistMessage` refuses for four reasons and, until now, recorded\n * none of them: a refusal moved no counter by design, so the month document\n * could say how much an org spent and nothing about how often it was turned\n * away. Staff monitoring needs the second figure — a workspace refused at its\n * band forty times this month is a sales conversation, and one refused at the\n * operator's backstop is an incident — and neither is derivable from spend.\n *\n * The count lives on the SAME document the spend does, as a map:\n *\n *   orgs/{orgId}/assistUsage/{YYYY-MM}.refusals.{reason}\n *\n * with `reason` one of the four `AssistRefusedBy` values. A map rather than\n * four top-level fields so a reader can take the whole thing in one `get`,\n * and so a fifth reason lands without a schema change.\n *\n * ## Fire-and-forget, and never throws\n *\n * The write is deliberately OUTSIDE the reservation transaction and off its\n * await path. A refusal is the cheap, no-token exit of the gate, and a\n * counter that could fail the refusal — or slow it, or retry the transaction\n * it was called from — would make the observation more expensive than the\n * thing observed. So this returns synchronously, swallows every error\n * including a double that has no `set`, and the only cost of a lost increment\n * is an undercount on a staff card.\n */\n\n/** A reason that actually refused — the `null` (admitted) case has no count. */\nexport type AssistRefusalReason = NonNullable<AiRefusedBy>\n\n/**\n * Every reason, in the order the card and the leaderboard list them: the\n * workspace's own four first, then an allotment a manager set (AGL-2942),\n * then the Free taste's (AGL-2925), which only a Free workspace can be\n * refused by.\n */\nexport const ASSIST_REFUSAL_REASONS: readonly AssistRefusalReason[] = [\n  'band',\n  'cap',\n  'messages',\n  'budget',\n  'allotment',\n  'account',\n  'requests',\n  'refusals',\n  'platform',\n]\n\nexport function recordAssistRefusal(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  month: string,\n  reason: AssistRefusalReason,\n): void {\n  try {\n    const ref = firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('assistUsage')\n      .doc(month)\n    // `set(…, { merge: true })`, never `update()`: the month document does\n    // not exist before the org's first admitted message, and a refusal can\n    // come first — a Free workspace at its daily cap on a fresh month.\n    void Promise.resolve(\n      ref.set(\n        { month, refusals: { [reason]: FieldValue.increment(1) } },\n        { merge: true },\n      ),\n    ).catch(() => undefined)\n  } catch {\n    // A double without `set`, a ref that could not be built — the refusal\n    // has already been decided and this must not change that.\n  }\n}\n\n/** Every reason's count, zero-filled, as the card and the leaderboard read them. */\nexport type AssistRefusalCounts = Record<AssistRefusalReason, number> & {\n  total: number\n}\n\n/**\n * The `refusals` map off a month document as a complete, zero-filled record.\n *\n * Zero-filled rather than sparse because the readers render every reason:\n * \"band 0\" beside \"cap 12\" is the finding, and a sparse map would make the\n * reader guess whether an absent key meant none or not yet counted. A\n * non-numeric or negative value reads as 0 — the counter is only ever\n * incremented, so anything else is a hand edit.\n */\nexport function assistRefusalCounts(raw: unknown): AssistRefusalCounts {\n  const map = (raw ?? {}) as Record<string, unknown>\n  const counts = Object.fromEntries(\n    ASSIST_REFUSAL_REASONS.map((reason) => {\n      const value = Number(map[reason] ?? 0)\n      return [reason, Number.isFinite(value) && value > 0 ? Math.floor(value) : 0]\n    }),\n  ) as Record<AssistRefusalReason, number>\n  return {\n    ...counts,\n    total: ASSIST_REFUSAL_REASONS.reduce((sum, reason) => sum + counts[reason], 0),\n  }\n}\n"],"names":["FieldValue","ASSIST_REFUSAL_REASONS","recordAssistRefusal","firestore","orgId","month","reason","ref","collection","doc","Promise","resolve","set","refusals","increment","merge","catch","undefined","assistRefusalCounts","raw","map","counts","Object","fromEntries","value","Number","isFinite","Math","floor","total","reduce","sum"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,gFAAgF;AAChF,4EAA4E;AAC5E,0EAA0E;AAC1E,SAASA,UAAU,QAAQ,2BAA0B;AAmCrD;;;;;CAKC,GACD,OAAO,MAAMC,yBAAyD;IACpE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,OAAO,SAASC,oBACdC,SAAsC,EACtCC,KAAa,EACbC,KAAa,EACbC,MAA2B;IAE3B,IAAI;QACF,MAAMC,MAAMJ,UACTK,UAAU,CAAC,QACXC,GAAG,CAACL,OACJI,UAAU,CAAC,eACXC,GAAG,CAACJ;QACP,uEAAuE;QACvE,uEAAuE;QACvE,mEAAmE;QACnE,KAAKK,QAAQC,OAAO,CAClBJ,IAAIK,GAAG,CACL;YAAEP;YAAOQ,UAAU;gBAAE,CAACP,OAAO,EAAEN,WAAWc,SAAS,CAAC;YAAG;QAAE,GACzD;YAAEC,OAAO;QAAK,IAEhBC,KAAK,CAAC,IAAMC;IAChB,EAAE,eAAM;IACN,sEAAsE;IACtE,0DAA0D;IAC5D;AACF;AAOA;;;;;;;;CAQC,GACD,OAAO,SAASC,oBAAoBC,GAAY;IAC9C,MAAMC,MAAOD,cAAAA,MAAO,CAAC;IACrB,MAAME,SAASC,OAAOC,WAAW,CAC/BtB,uBAAuBmB,GAAG,CAAC,CAACd;YACLc;QAArB,MAAMI,QAAQC,QAAOL,cAAAA,GAAG,CAACd,OAAO,YAAXc,cAAe;QACpC,OAAO;YAACd;YAAQmB,OAAOC,QAAQ,CAACF,UAAUA,QAAQ,IAAIG,KAAKC,KAAK,CAACJ,SAAS;SAAE;IAC9E;IAEF,OAAO,aACFH;QACHQ,OAAO5B,uBAAuB6B,MAAM,CAAC,CAACC,KAAKzB,SAAWyB,MAAMV,MAAM,CAACf,OAAO,EAAE;;AAEhF"}

package/src/lib/usage/assist-signal-mining.d.ts

@@ -0,0 +1,375 @@
+/**
+ * @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 read side of the Aglyn Assist data loop (AGL-1860, AGL-2252).
+ *
+ * `orgs/{id}/assistSignals/{id}` is written on every assist turn and, until
+ * this module, was read by nothing. That is a specific kind of failure: the
+ * signal document exists BECAUSE AGL-1972 split the prose from the analytics
+ * so the corpus could outlive the 180-day expiry on what people typed. A
+ * corpus preserved for a reader that does not exist is just retention.
+ *
+ * Three questions, answered from one pass:
+ *
+ *  1. **Where are the docs thin?** Rank the cited docs paths by how often a
+ *     question landed on them and how often the answer was rated down. A
+ *     page cited constantly and rated down is a page that is being FOUND and
+ *     is not answering — the single most actionable row in the set, and the
+ *     one AGL-1860 wants turned into a docs issue.
+ *  2. **What did retrieval miss entirely?** A turn with no `docsPaths` is a
+ *     question the corpus could not match at all, so the model answered
+ *     ungrounded. That is a sharper gap signal than a low rating, and it is
+ *     invisible in any ranking keyed on paths — a missing page cites nothing,
+ *     so it appears nowhere. It is counted separately, by ROUTE, so the gap
+ *     comes with the screen the person was looking at when they hit it.
+ *  3. **What is this costing, and to whom?** Per-org and fleet-wide token and
+ *     dollar rollups, plus the cache-read rate. That last one settles a
+ *     question the chat route could only pose: the cached system prefix
+ *     measures 1,030–1,190 tokens against Sonnet 5's 1,024-token minimum, so
+ *     whether it caches at all is an empirical question and `cacheReadTokens`
+ *     is the only evidence. A prefix under the minimum caches silently not at
+ *     all, and the bill is the only place it shows.
+ *
+ * Pure and free of Firestore, so it can be tested on fixtures rather than on
+ * a mocked SDK — the route does the reading, this does the arithmetic.
+ */
+/** One `assistSignals` document, as the route projects it. */
+export interface AssistSignalRow {
+    orgId: string;
+    /**
+     * The signal's document id, which IS the exchange's id (AGL-2314).
+     *
+     * `recordAssistExchange` mints one id and writes both halves under it —
+     * `assistExchanges/{id}` for the prose that expires and `assistSignals/{id}`
+     * for the analytics that do not — deliberately, "so an exchange and its
+     * signal are joinable for as long as both exist, without storing a second
+     * pointer that could rot". Nothing ever made the join. This is the field
+     * that lets the corpus be read.
+     */
+    exchangeId: string;
+    route: string;
+    /**
+     * What the turn was for, as the rollups name it (AGL-2937): `assist`, a
+     * besigner mode, or a job kind. A signal written before the field is read
+     * by its route, where a generation job's step reads as `job`.
+     */
+    kind?: string;
+    model: string;
+    tier: 'free' | 'entitled' | string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /**
+     * What this turn cost us, at the serving model's provider rates. Every
+     * dollar mined out of this module is that figure: the signals page asks
+     * one money question and it is "what are we spending" (AGL-3015).
+     */
+    providerCostUsd: number;
+    docsPaths: string[];
+    stopReason: string | null;
+    feedback: 'up' | 'down' | null;
+    /** Served with no model call — docs retrieval or a cache hit (AGL-2486). */
+    deflected: boolean;
+}
+export interface DocsGapRow {
+    path: string;
+    /** Turns that cited this path. */
+    questions: number;
+    up: number;
+    down: number;
+    /** Distinct orgs that landed here — a gap one org has is not a gap. */
+    orgs: number;
+    providerCostUsd: number;
+    /** `down / (up + down)`, or null when nobody rated. */
+    downRate: number | null;
+}
+export interface UngroundedRoute {
+    route: string;
+    questions: number;
+    down: number;
+}
+/**
+ * A turn whose PROSE is worth reading (AGL-2314).
+ *
+ * `assistExchanges` holds the verbatim half — the question a customer typed
+ * and the answer we gave — for 180 days, and the module header calls it "the
+ * data loop's corpus". No corpus consumer existed: nothing in the repo read
+ * the collection, so we were retaining customers' words, and publicly
+ * promising to, for zero product value.
+ *
+ * The shortlist is deliberately NOT every turn. Prose is fetched only for
+ * turns that FAILED — rated thumbs-down, or grounded in no documentation at
+ * all — because those are the ones where the counts cannot say what went
+ * wrong and the words can. Reading the successful ones would be surveillance
+ * with a dashboard on it.
+ */
+export interface ProseCandidate {
+    orgId: string;
+    /**
+     * That workspace by name, filled in by the route.
+     *
+     * Optional because this module is pure and Firestore-free: it can count a
+     * workspace's turns and it cannot know what the workspace is called. The
+     * route resolves the labels and the reader falls back to the id, so a
+     * workspace outside the lookup is still a lead somebody can search for.
+     */
+    orgLabel?: string | null;
+    exchangeId: string;
+    /** The console screen the question was asked from. */
+    route: string;
+    feedback: 'up' | 'down' | null;
+    /** False when retrieval cited no documentation at all. */
+    grounded: boolean;
+}
+export interface OrgCostRow {
+    orgId: string;
+    /** That workspace by name — see {@link ProseCandidate.orgLabel}. */
+    orgLabel?: string | null;
+    messages: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    providerCostUsd: number;
+    down: number;
+}
+/** One row of a cost breakdown — see `totals.byTier` / `totals.byModel`. */
+export interface CostSplit {
+    messages: number;
+    providerCostUsd: number;
+}
+/** One kind of model turn, summed (AGL-2937) — see `totals.byKind`. */
+export interface KindTokenSplit {
+    messages: number;
+    providerCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /**
+     * The output 95 of every 100 turns of this kind stayed within, by nearest
+     * rank — the figure a kind's `max_tokens` is sized against.
+     */
+    outputP95: number;
+    /** The share of this kind's prompt tokens the cache served — `aiCacheHitRate`. */
+    cacheHitRate: number | null;
+}
+/** The kinds as the board lists them, dearest first. */
+export declare function kindTokenRows(split: Record<string, KindTokenSplit>): Array<KindTokenSplit & {
+    kind: string;
+}>;
+/** A sample's value at a percentile by nearest rank — always one that was seen; 0 for none. */
+export declare function nearestRankPercentile(values: readonly number[], percentile: number): number;
+/**
+ * A cost breakdown as a sorted, labelled list — dearest first (AGL-2340).
+ *
+ * Exported because the ordering is the readable half. A breakdown in
+ * whatever order the keys happened to be inserted is a table you have to
+ * scan; the point of the panel is that the expensive line is the top line.
+ */
+export declare function costSplitRows(split: Record<string, CostSplit>): {
+    key: string;
+    messages: number;
+    providerCostUsd: number;
+}[];
+/**
+ * One workspace on the month's spend leaderboard (AGL-2930).
+ *
+ * Read off `assistUsage/{month}` rather than off the signals: the signals
+ * carry every turn ever recorded and no month, so ranking them answers
+ * "who has spent the most since the beginning", and the board's question is
+ * "who is spending the most NOW". The month document is also where the
+ * refusal counter lives, so the row can say how often the org was refused
+ * beside how much it spent — the two numbers a staff reader compares.
+ */
+export interface AssistSpendRow {
+    orgId: string;
+    orgLabel?: string | null;
+    plan: string;
+    aiAddon: boolean;
+    /** Credits drawn this month, from the measured spend. */
+    credits: number;
+    providerCostUsd: number;
+    refusals: {
+        band: number;
+        cap: number;
+        messages: number;
+        budget: number;
+        /** A hard AI allotment a manager set (AGL-2942). */
+        allotment: number;
+        /** The Free taste's rungs (AGL-2925); zero on every paid workspace. */
+        account: number;
+        requests: number;
+        refusals: number;
+        platform: number;
+        total: number;
+    };
+}
+/** The Free taste's refusals as one figure: the board names the wall, not each rung. */
+export declare function freeTasteRefusals(refusals: AssistSpendRow['refusals']): number;
+/**
+ * The leaderboard's ordering: dearest first, then most credits, then by id
+ * so two equal rows render in one stable order rather than the order the
+ * scan happened to return them in. Returns the top `limit` and how many
+ * were ranked, so the page can say "top 25 of 140" rather than imply the
+ * cut is the whole fleet.
+ */
+export declare function rankAssistSpend(rows: readonly AssistSpendRow[], limit: number): {
+    rows: AssistSpendRow[];
+    ranked: number;
+};
+/**
+ * Today's platform-wide free-tier AI spend against its daily ceiling
+ * (AGL-2925), as the route reads it beside the mined signals. Declared here,
+ * where the page's report type lives, so the client page needs no import
+ * from the admin library to name it.
+ */
+export interface AssistFreeSpendReadout {
+    /** The UTC day the figures describe. */
+    day: string;
+    /**
+     * The day's free spend as the CEILING measures it — the billed figure,
+     * because the ceiling this is compared against was sized against it and
+     * the reservation refuses on the same reading (AGL-3015). The one dollar
+     * on this page that is not our provider bill, and it is a wall rather than
+     * a cost.
+     */
+    estCostUsd: number;
+    requests: number;
+    refusals: number;
+    ceilingUsd: number;
+    /** True once staff were mailed at 80% today. */
+    alerted: boolean;
+    /** True while every Free workspace is refused generation for the day. */
+    paused: boolean;
+}
+export interface AssistMiningReport {
+    scanned: number;
+    /** True when the read hit its ceiling — see `mineAssistSignals`. */
+    truncated: boolean;
+    totals: {
+        messages: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        providerCostUsd: number;
+        /**
+         * Turns answered with NO model call — docs retrieval or an answer-cache
+         * hit (AGL-2486). Counted separately from `messages`, which is every
+         * turn, so `deflected / messages` is the deflection rate.
+         */
+        deflected: number;
+        /**
+         * That rate, or `null` when nothing was scanned.
+         *
+         * Nullable rather than 0 for the reason `costUsd` on a reservation is:
+         * "no turns were scanned" and "every turn cost a model call" are opposite
+         * findings, and 0 says the second one when the truth is the first. This
+         * is the headline number for whether Assist is affordable to leave on,
+         * and it must not be able to report a false alarm on an idle month.
+         */
+        deflectionRate: number | null;
+        /**
+         * Share of prompt tokens served from cache — reads over everything the
+         * prompts were billed as, cache writes included (`aiCacheHitRate`) — or
+         * null at zero.
+         */
+        cacheReadRate: number | null;
+        /**
+         * Cost split by entitlement tier, then by model (AGL-2340).
+         *
+         * Both carried as `{ messages, providerCostUsd }` rather than a bare turn
+         * count, because the questions these answer are money questions and a
+         * count cannot answer either of them. `byTier` settles "is the free tier
+         * eating the margin, or are paying orgs?" — the free tier can be a
+         * minority of turns and a majority of spend, and a count says the
+         * opposite of the truth in exactly that case. `byModel` settles "would a
+         * cheaper model on the common path fix this?", where the whole point is
+         * that turns and dollars do not move together.
+         */
+        byTier: Record<string, CostSplit>;
+        byModel: Record<string, CostSplit>;
+        /**
+         * Model turns split by what they were for (AGL-2937): cost, the four
+         * token counts, the p95 output and the cache hit rate of each kind. A
+         * turn answered with no model call has no tokens to split and is left
+         * out.
+         */
+        byKind: Record<string, KindTokenSplit>;
+        stopReasons: Record<string, number>;
+        feedback: {
+            up: number;
+            down: number;
+            none: number;
+        };
+    };
+    docsGaps: DocsGapRow[];
+    /**
+     * How tall each ranking was BEFORE it was cut to `limit`.
+     *
+     * `truncated` reports only that the SCAN hit its ceiling. It says nothing
+     * about the rankings built from what was scanned, and those are cut too —
+     * every list below is sliced to `limit`. A table showing twenty-five of a
+     * hundred and thirty-seven cited pages looks exactly like one showing all
+     * twenty-five there are, which is the AGL-2220 shape the scan ceiling was
+     * given a banner to avoid, reproduced one layer down.
+     *
+     * Counted rather than inferred from `length === limit`: a ranking that is
+     * exactly `limit` rows tall is the case where the guess is wrong in both
+     * directions.
+     */
+    ranked: {
+        docsGaps: number;
+        ungroundedRoutes: number;
+        orgs: number;
+    };
+    /**
+     * Today's free-tier spend against the platform ceiling (AGL-2925).
+     * Optional because the miner is pure and does not produce it — the route
+     * reads it from Firestore and attaches it beside the mined report.
+     */
+    freeSpend?: AssistFreeSpendReadout;
+    /** Turns whose words are worth reading — see {@link ProseCandidate}. */
+    proseCandidates: ProseCandidate[];
+    ungrounded: {
+        questions: number;
+        down: number;
+        routes: UngroundedRoute[];
+    };
+    orgs: OrgCostRow[];
+}
+/**
+ * Normalize one raw signal document. Every field is defaulted, because a
+ * signal written by an older build is still evidence and dropping it would
+ * bias the ranking toward whatever shipped most recently.
+ */
+export declare function assistSignalRow(orgId: string, exchangeId: string, data: Record<string, unknown>): AssistSignalRow;
+/**
+ * Rank the docs gaps and roll the money up.
+ *
+ * `truncated` is carried through rather than hidden. A sweep that quietly
+ * stops at a ceiling and presents the remainder as the whole is the AGL-2220
+ * defect, and it is worse here than there: a partial sample of a RANKING
+ * looks exactly like a complete one, and the thing being ranked is where to
+ * spend documentation effort.
+ */
+export declare function mineAssistSignals(rows: AssistSignalRow[], options?: {
+    truncated?: boolean;
+    limit?: number;
+}): AssistMiningReport;