@mnemom/mnemom 0.17.34-next.2 → 0.17.34-next.4

package/dist/lib/scan/record.d.ts

@@ -4,10 +4,19 @@
  * Read-only and local: the answer is held in memory to build the report and is never uploaded or
  * stored (mnemom-api#4211: Mnemom stores no scan result).
  *
- * The window is always the last 30 days ending now (the contract's maximum). It is its own
+ * The window is the last 30 days ending now, less a one-minute margin at the start so it stays
+ * inside the API's retention floor (the contract's maximum is 30 days). It is its own
  * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
  * number is ever produced here.
  *
+ * An org with more requests in the window than the API will total in one read (it answers 400
+ * "window holds more than N requests: narrow it") is read in pieces: the failing window is halved
+ * at its midpoint, recursively, and the pieces are summed. The API's window is half-open
+ * [from, to), so pieces [from, mid) and [mid, to) neither overlap nor leave a gap. Fan-out is
+ * bounded (RECORD_MAX_REQUESTS reads, no piece split below RECORD_MIN_SPLIT_MS per half), and a
+ * total is all or nothing: any piece that fails for any other reason makes the whole read
+ * "unavailable", never a partial sum.
+ *
  * Outcomes are a closed set, and every one has fixed text. The thrown value, the response body
  * and the credential never reach the terminal:
  *   ok            totals read and shape-checked
@@ -19,6 +28,21 @@ import { type RecordWindowTotals } from "../api.js";
 export declare const RECORD_WINDOW_DAYS = 30;
 export declare const RECORD_WINDOW_LABEL = "last 30 days";
 export declare const RECORD_TIMEOUT_MS = 10000;
+/**
+ * The API 400s a `from` earlier than its own now minus 30 days (retention floor, strict on purpose:
+ * mnemom-api#4310). Its clock runs later than ours by latency, so a window opening exactly 30 days
+ * before our now is always past that floor. Open it this much after instead; `to` stays our now
+ * (the API accepts a `to` up to 60s ahead of its clock: WINDOW_SKEW_MS in mnemom-api
+ * src/record/totals.ts). Ending at now centres the budget: the window is accepted while our clock is
+ * within 60s of the API's in either direction; ending earlier would trade away the floor side.
+ */
+export declare const RECORD_FLOOR_MARGIN_MS = 60000;
+/** Most reads one scan may make (the first full-window read included). */
+export declare const RECORD_MAX_REQUESTS = 64;
+/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+export declare const RECORD_TOTAL_TIMEOUT_MS = 60000;
+/** A window is split only if both halves stay at least this long. */
+export declare const RECORD_MIN_SPLIT_MS: number;
 export declare const isOrgId: (v: unknown) => v is string;
 export declare const RECORD_AUTH_MSG = "Record totals were refused for this org. Run `mnemom login` (or set MNEMOM_API_KEY) with an owner, admin or auditor of the org passed to --org, then retry.";
 export declare class RecordAuthError extends Error {
@@ -41,6 +65,8 @@ export interface RecordDeps {
     fetchTotals?: (orgId: string, from: string, to: string, signal: AbortSignal) => Promise<unknown>;
     now?: () => number;
     timeoutMs?: number;
+    /** Budget for every read of one total together (default RECORD_TOTAL_TIMEOUT_MS). */
+    totalTimeoutMs?: number;
 }
 export declare function recordWindow(nowMs: number): RecordWindow;
 /** Shape-check the body: a malformed answer is "unavailable", never rendered. */

package/dist/lib/scan/record.js

@@ -4,10 +4,19 @@
  * Read-only and local: the answer is held in memory to build the report and is never uploaded or
  * stored (mnemom-api#4211: Mnemom stores no scan result).
  *
- * The window is always the last 30 days ending now (the contract's maximum). It is its own
+ * The window is the last 30 days ending now, less a one-minute margin at the start so it stays
+ * inside the API's retention floor (the contract's maximum is 30 days). It is its own
  * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
  * number is ever produced here.
  *
+ * An org with more requests in the window than the API will total in one read (it answers 400
+ * "window holds more than N requests: narrow it") is read in pieces: the failing window is halved
+ * at its midpoint, recursively, and the pieces are summed. The API's window is half-open
+ * [from, to), so pieces [from, mid) and [mid, to) neither overlap nor leave a gap. Fan-out is
+ * bounded (RECORD_MAX_REQUESTS reads, no piece split below RECORD_MIN_SPLIT_MS per half), and a
+ * total is all or nothing: any piece that fails for any other reason makes the whole read
+ * "unavailable", never a partial sum.
+ *
  * Outcomes are a closed set, and every one has fixed text. The thrown value, the response body
  * and the credential never reach the terminal:
  *   ok            totals read and shape-checked
@@ -19,8 +28,23 @@ import { getRecordWindowTotals, MnemomApiError } from "../api.js";
 export const RECORD_WINDOW_DAYS = 30;
 export const RECORD_WINDOW_LABEL = "last 30 days";
 export const RECORD_TIMEOUT_MS = 10_000;
-/** `to` may not be in the future; stay a minute behind so a fast local clock cannot trip it. */
-const CLOCK_SKEW_MS = 60_000;
+/**
+ * The API 400s a `from` earlier than its own now minus 30 days (retention floor, strict on purpose:
+ * mnemom-api#4310). Its clock runs later than ours by latency, so a window opening exactly 30 days
+ * before our now is always past that floor. Open it this much after instead; `to` stays our now
+ * (the API accepts a `to` up to 60s ahead of its clock: WINDOW_SKEW_MS in mnemom-api
+ * src/record/totals.ts). Ending at now centres the budget: the window is accepted while our clock is
+ * within 60s of the API's in either direction; ending earlier would trade away the floor side.
+ */
+export const RECORD_FLOOR_MARGIN_MS = 60_000;
+/** Most reads one scan may make (the first full-window read included). */
+export const RECORD_MAX_REQUESTS = 64;
+/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+export const RECORD_TOTAL_TIMEOUT_MS = 60_000;
+/** A window is split only if both halves stay at least this long. */
+export const RECORD_MIN_SPLIT_MS = 60 * 60 * 1000;
+/** The API's bigint ceiling: a larger sum cannot be a real total. */
+const MAX_MMU = 9223372036854775807n;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const ORG_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
@@ -33,9 +57,9 @@ export class RecordAuthError extends Error {
     }
 }
 export function recordWindow(nowMs) {
-    const to = nowMs - CLOCK_SKEW_MS;
+    const to = nowMs;
     return {
-        from: new Date(to - RECORD_WINDOW_DAYS * DAY_MS).toISOString(),
+        from: new Date(to - RECORD_WINDOW_DAYS * DAY_MS + RECORD_FLOOR_MARGIN_MS).toISOString(),
         to: new Date(to).toISOString(),
     };
 }
@@ -60,26 +84,100 @@ export function parseWindowTotals(v) {
         as_of: o.as_of,
     };
 }
+/** The API's too-many-requests answer: a 400 saying the window holds more than N requests. */
+const isWindowTooBig = (e) => e instanceof MnemomApiError &&
+    e.effectiveStatus === 400 &&
+    /holds more than \d+ requests/.test(e.message);
+/** Latest of two as_of timestamps (a "latest row" field is combined by max, never added). */
+function laterAsOf(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (Number.isNaN(ta) || Number.isNaN(tb))
+        throw new Error("unparsable as_of");
+    return tb > ta ? b : a;
+}
+/**
+ * Add two windows' totals. Costs, charges and row counts are additive over disjoint windows (a
+ * request sits in the window of its gateway row, and its billing row follows it). `mu_charged_mmu`
+ * is null for a window with no billing row, so it is null only when every piece is null, as the
+ * API's own multi-lineage sum does. `as_of` is the latest row's time, so it is the max.
+ */
+function addTotals(a, b) {
+    const model = BigInt(a.model_cost_mmu) + BigInt(b.model_cost_mmu);
+    const mu = a.mu_charged_mmu === null && b.mu_charged_mmu === null
+        ? null
+        : BigInt(a.mu_charged_mmu ?? "0") + BigInt(b.mu_charged_mmu ?? "0");
+    const rows = a.row_count + b.row_count;
+    if (model > MAX_MMU || (mu !== null && mu > MAX_MMU) || !Number.isSafeInteger(rows)) {
+        throw new Error("summed total out of range");
+    }
+    return {
+        model_cost_mmu: model.toString(),
+        mu_charged_mmu: mu === null ? null : mu.toString(),
+        row_count: rows,
+        as_of: laterAsOf(a.as_of, b.as_of),
+    };
+}
+/** Any failure other than auth / not-in-cohort makes the whole total unavailable. */
+class SplitFailed extends Error {
+}
+class NotInCohort extends Error {
+}
 /** Never throws except RecordAuthError (401/403, fail closed). */
 export async function fetchRecordTotals(orgId, deps = {}) {
     if (!isOrgId(orgId))
         return { status: "unavailable" };
     const window = recordWindow((deps.now ?? Date.now)());
     const fetchTotals = deps.fetchTotals ?? getRecordWindowTotals;
-    const signal = AbortSignal.timeout(deps.timeoutMs ?? RECORD_TIMEOUT_MS);
+    const timeoutMs = deps.timeoutMs ?? RECORD_TIMEOUT_MS;
+    const deadline = Date.now() + (deps.totalTimeoutMs ?? RECORD_TOTAL_TIMEOUT_MS);
+    let requests = 0;
+    /** Total of [fromMs, toMs). Throws RecordAuthError, NotInCohort (root 404 only) or SplitFailed. */
+    const read = async (fromMs, toMs, root) => {
+        const left = deadline - Date.now();
+        if (requests >= RECORD_MAX_REQUESTS || left <= 0)
+            throw new SplitFailed();
+        requests += 1;
+        try {
+            const body = await fetchTotals(orgId, new Date(fromMs).toISOString(), new Date(toMs).toISOString(), AbortSignal.timeout(Math.min(timeoutMs, left)));
+            const totals = parseWindowTotals(body);
+            if (!totals)
+                throw new SplitFailed();
+            return totals;
+        }
+        catch (e) {
+            if (e instanceof MnemomApiError) {
+                const s = e.effectiveStatus;
+                if (s === 401 || s === 403)
+                    throw new RecordAuthError();
+                if (s === 404 && root)
+                    throw new NotInCohort();
+                if (isWindowTooBig(e)) {
+                    const mid = fromMs + Math.floor((toMs - fromMs) / 2);
+                    if (mid - fromMs < RECORD_MIN_SPLIT_MS || toMs - mid < RECORD_MIN_SPLIT_MS) {
+                        throw new SplitFailed();
+                    }
+                    const first = await read(fromMs, mid, false);
+                    return addTotals(first, await read(mid, toMs, false));
+                }
+            }
+            // RecordAuthError / NotInCohort / nested failures above are thrown from this handler and never land here.
+            throw new SplitFailed();
+        }
+    };
     try {
-        const body = await fetchTotals(orgId, window.from, window.to, signal);
-        const totals = parseWindowTotals(body);
-        return totals ? { status: "ok", totals, window } : { status: "unavailable" };
+        const totals = await read(Date.parse(window.from), Date.parse(window.to), true);
+        return { status: "ok", totals, window };
     }
     catch (e) {
-        if (e instanceof MnemomApiError) {
-            const s = e.effectiveStatus;
-            if (s === 401 || s === 403)
-                throw new RecordAuthError();
-            if (s === 404)
-                return { status: "not_in_cohort" };
-        }
+        if (e instanceof RecordAuthError)
+            throw e;
+        if (e instanceof NotInCohort)
+            return { status: "not_in_cohort" };
         return { status: "unavailable" };
     }
 }

package/dist/lib/scan/report-email.d.ts

@@ -1,8 +1,9 @@
+import { type CostPerPr, type CostSpend } from "./cost-per-pr.js";
 import type { ScanResult } from "./scan.js";
 import type { ShareLevel } from "./share.js";
 export declare const REPORT_SCHEMA_VERSION = "org-scan-report/1";
 export declare const ESTIMATE_NAME = "automatable_work_share";
-export declare const METHOD_URL = "https://www.mnemom.ai/method";
+export declare const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
 export interface EmailReport {
     schema_version: typeof REPORT_SCHEMA_VERSION;
     org_id: string;
@@ -39,6 +40,22 @@ export interface EmailReport {
         unit: string;
         method_url: string;
     };
+    /**
+     * Optional, added after org-scan-report/1 shipped; absent whenever it cannot be computed (no spend,
+     * no merged PR in the period, an incomplete scan, an empty bucket). See cost-per-pr.ts.
+     *   cost_per_merged_pr  average cost of one merged PR in the period
+     *   cost_by_pr_size     { small | medium | large }: average cost of ONE PR of that size, per-bucket
+     *                       keys absent when the bucket is empty. small < 50 lines changed, medium 50..500, large > 500.
+     * A figure is { label: "estimate", spend_source, pr_scope, pr_count } (+ spend_scope: "whole_org" on
+     * anthropic_usage) plus { value_cents } (anthropic_usage) or { low_cents, high_cents } (modelled_range). Integer cents.
+     * pr_scope is "ai_assisted" for modelled_range (spend and size buckets split across AI-assisted PRs only;
+     * absent if none) and "all_merged" otherwise; pr_count counts PRs in that scope.
+     * Always attached when present. The API's report validator (mnemom-api src/org-scan/report-schema.ts) is
+     * closed, so an API that does not yet list these keys answers 400 invalid_report; sendReportEmail then
+     * retries once without them so the report email still goes out.
+     */
+    cost_per_merged_pr?: CostPerPr["cost_per_merged_pr"];
+    cost_by_pr_size?: CostPerPr["cost_by_pr_size"];
 }
 export interface ReportEmailBody {
     report: EmailReport;
@@ -56,13 +73,16 @@ export interface ReportEmailBody {
  */
 export declare function buildEmailReport(result: ScanResult, o: {
     orgId: string;
-    period: {
-        start: string;
-        end: string;
-    };
     now: () => number;
     sendSpendRange: boolean;
     scanId?: string;
+    /** The requested scan period (the one the spend covers), not the examined window. */
+    period?: {
+        start: string;
+        end: string;
+    };
+    /** The one spend source the cost figures are split from; null/absent leaves them out. */
+    costSpend?: CostSpend | null;
 }): EmailReport;
 export declare function buildEmailBody(report: EmailReport, level: ShareLevel, complete: boolean, ctoEmail?: string): ReportEmailBody;
 /** Closed set of failure names; each has fixed text. */

package/dist/lib/scan/report-email.js

@@ -13,9 +13,10 @@
  */
 import { randomUUID } from "node:crypto";
 import { MnemomApiError, postApi } from "../api.js";
+import { buildCostPerPr } from "./cost-per-pr.js";
 export const REPORT_SCHEMA_VERSION = "org-scan-report/1";
 export const ESTIMATE_NAME = "automatable_work_share";
-export const METHOD_URL = "https://www.mnemom.ai/method";
+export const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
 const cents = (usd) => Math.max(0, Math.round(usd * 100));
 /**
  * Maps the local scan onto the route's closed report shape. Team totals stay empty (they come only from
@@ -36,11 +37,16 @@ export function buildEmailReport(result, o) {
             .filter(([, n]) => typeof n === "number" && n > 0)
             .map(([tool, count]) => ({ tool, count: count }))
         : [];
+    // Only a scan that read every merged PR in the period gives an average that means anything.
+    const exhaustive = coverage.complete && coverage.prsSkippedLarge === 0 && coverage.prsUnreadable === 0;
+    const cost = buildCostPerPr(result.prSizes, o.period ?? { start: coverage.windowStart, end: coverage.windowEnd }, o.costSpend ?? null, exhaustive);
     return {
         schema_version: REPORT_SCHEMA_VERSION,
         org_id: o.orgId,
         scan_id: o.scanId ?? randomUUID(),
-        period: o.period,
+        // The span the scan actually examined (coverage), never the requested period: with no --period
+        // that defaults to today..today, which is not what was read.
+        period: { start: coverage.windowStart, end: coverage.windowEnd },
         generated_at: new Date(o.now()).toISOString(),
         measured: {
             teams: [],
@@ -65,6 +71,7 @@ export function buildEmailReport(result, o) {
             },
         },
         estimate: { name: ESTIMATE_NAME, value, unit, method_url: METHOD_URL },
+        ...cost,
     };
 }
 export function buildEmailBody(report, level, complete, ctoEmail) {
@@ -111,6 +118,13 @@ function classifyStatus(status) {
         return "report_rejected";
     return "unexpected_response";
 }
+/** The body without the optional cost figures; the same object when it carries none. */
+function withoutCostFigures(body) {
+    const { cost_per_merged_pr: _a, cost_by_pr_size: _b, ...rest } = body.report;
+    return "cost_per_merged_pr" in body.report || "cost_by_pr_size" in body.report
+        ? { ...body, report: rest }
+        : body;
+}
 /** Never throws. The thrown value, the response body and the credential are never surfaced. */
 export async function sendReportEmail(orgId, body, deps = {}) {
     const post = deps.post ?? defaultPost;
@@ -121,6 +135,13 @@ export async function sendReportEmail(orgId, body, deps = {}) {
     catch (e) {
         if (e instanceof MnemomApiError && e.effectiveStatus === 404)
             return { status: "unavailable" };
+        // An API that predates the cost figures rejects the unknown keys with a 400. The email must still
+        // go out, so retry once with the figures left off; any other failure is classified as below.
+        if (e instanceof MnemomApiError && e.effectiveStatus === 400) {
+            const bare = withoutCostFigures(body);
+            if (bare !== body)
+                return sendReportEmail(orgId, bare, deps);
+        }
         if (e instanceof MnemomApiError) {
             // A 4xx that names the runner (the API refuses a send that would skip the runner) gets its own text.
             if (e.effectiveStatus >= 400 && e.effectiveStatus < 500 && /runner/i.test(e.code ?? ""))

package/dist/lib/scan/scan.d.ts

@@ -7,6 +7,7 @@ import { type GitHubCredential } from "./credential.js";
 import { type ScanCaps, type StopReason } from "./caps.js";
 import { type FailureReason } from "./failure.js";
 import { type PrSource } from "./pr-source.js";
+import type { PrSize } from "./cost-per-pr.js";
 import { type SpendEstimate } from "./spend/spend-estimate.js";
 export interface ScanInput {
     repos: string[];
@@ -53,6 +54,8 @@ export interface ScanResult {
     };
     byRepo: RepoTotals[];
     spend: SpendEstimate;
+    /** Every merged PR read in full (reverts and unreadable/oversize PRs excluded): merge day and size. In memory only. */
+    prSizes: PrSize[];
 }
 export type ScanOutcome = {
     status: "done";

package/dist/lib/scan/scan.js

@@ -109,6 +109,7 @@ export async function runLocalScan(deps, input) {
         };
         const totals = { prs: 0, reverts: 0, ciGreen: 0, examined: 0 };
         const spendInputs = [];
+        const prSizes = [];
         let skippedLarge = 0;
         let unreadable = 0;
         for (const { repo, item } of chosen) {
@@ -146,6 +147,11 @@ export async function runLocalScan(deps, input) {
                 totals.ciGreen += 1;
                 bucket(repo).ciGreen += 1;
             }
+            prSizes.push({
+                mergedDay: item.mergedDay,
+                lines: rec.additions + rec.deletions,
+                aiAssisted: (rec.tools?.length ?? 0) > 0,
+            });
             spendInputs.push({
                 additions: rec.additions,
                 deletions: rec.deletions,
@@ -172,7 +178,13 @@ export async function runLocalScan(deps, input) {
         };
         return {
             status: "done",
-            result: { coverage, totals, byRepo: [...byRepo.values()], spend: estimateSpend(spendInputs) },
+            result: {
+                coverage,
+                totals,
+                byRepo: [...byRepo.values()],
+                spend: estimateSpend(spendInputs),
+                prSizes,
+            },
         };
     }
     catch (e) {

package/dist/lib/session-key.d.ts

@@ -24,9 +24,10 @@ export interface SessionKeyDeps {
     revoke: (keyId: string) => Promise<void>;
     say: (line: string) => void;
     /**
-     * Override the mint/revoke timeout, tests only — real callers never set these, so the real
-     * 10s/3s bounds below always apply in production. Exists so a test can exercise "never
-     * settles" against a short, fast timeout rather than waiting out the real one.
+     * Override the mint/revoke timeout. Tests use it; the one real caller is the exit path of a
+     * launch that prints a conduct receipt, which bounds the revoke by the receipt's deadline
+     * (agent.ts, Doors W1.3). Otherwise the 10s/3s bounds below apply. Tests use it to exercise
+     * "never settles" against a short, fast timeout rather than waiting out the real one.
      */
     mintTimeoutMs?: number;
     revokeTimeoutMs?: number;