@agent-finops/core 0.9.1 → 0.9.3

package/README.md

@@ -42,10 +42,10 @@ official provider-reported financial evidence, keep modeled/local value
 `estimated` or `missing`, and leave unvalidated adapters `untested`.
 
 This is the open foundation for aibill's financial-accountability mission. The
-unreleased source preview includes contracts for locally confirmed ownership,
+published v0.9.1 package includes contracts for locally confirmed ownership,
 local self-attested approvals, and opt-in accepted GitHub outcomes. Those are
 not company-wide identity, RBAC, approval routing, invoice reconciliation, or
-verified business ROI; the public npm v0.8.1 package predates this preview.
+verified business ROI.
 
 Local API-equivalent estimates, subscription context, and official
 provider-reported cost are separate concepts and must not be added together.

package/dist/activitySnapshotCache.js

@@ -1,6 +1,6 @@
 import { constants } from "node:fs";
 import { execFile as execFileCallback } from "node:child_process";
-import { open, lstat, mkdir, chmod, realpath, rename, unlink } from "node:fs/promises";
+import { open, lstat, mkdir, chmod, readdir, realpath, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -343,12 +343,48 @@ async function ensureDefaultParent(homeDirectory, create) {
         throw new ActivitySnapshotCacheError("unsafe_directory", "The private aibill directory is not a real directory.");
     }
     if (!create && !hasPrivatePermissions(info.mode)) {
-        throw new ActivitySnapshotCacheError("unsafe_directory", "The private aibill directory is not private.");
+        // Self-heal (NEW-B1): 0.9.2's signup/telemetry state writers created
+        // ~/.aibill without a mode (755 under the default umask), which this
+        // guard then refused forever — bricking init on machines that ran
+        // 0.9.2 in that window. When the directory holds ONLY our own state
+        // files (no cache/ yet, nothing foreign), tighten it to 0700 and
+        // proceed instead of erroring. Anything unexpected still refuses.
+        if (!await selfHealStateOnlyAibillDirectory(parent)) {
+            throw new ActivitySnapshotCacheError("unsafe_directory", `The private aibill directory is not private. Fix: chmod 700 ${parent}`);
+        }
     }
     if (create)
         await chmod(parent, 0o700);
     await ensureDefaultCacheGitPrivacy(parent, create);
 }
+/**
+ * The complete set of files aibill's own home-scope state writers may have
+ * placed in ~/.aibill before any cache exists. A directory with exactly
+ * these contents (or fewer) is provably ours to repair.
+ */
+const selfHealableAibillEntries = new Set([
+    "signup.json",
+    "signup.json.tmp",
+    "telemetry.json",
+    "telemetry.json.tmp",
+    ".gitignore"
+]);
+async function selfHealStateOnlyAibillDirectory(parent) {
+    try {
+        const entries = await readdir(parent, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !selfHealableAibillEntries.has(entry.name))
+                return false;
+        }
+        await chmod(parent, 0o700);
+        const confirmed = await lstat(parent);
+        return !confirmed.isSymbolicLink() && confirmed.isDirectory() &&
+            hasPrivatePermissions(confirmed.mode);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * When a synthetic or real HOME is itself inside a Git worktree, protect the
  * complete top-level private state directory before any cache child is

package/dist/emailAddress.d.ts

@@ -0,0 +1,7 @@
+/**
+ * One intentionally pragmatic normalizer for waitlist and receipt-email
+ * boundaries. It prevents header/control injection without pretending to be
+ * a mailbox-verification system; ownership still requires an explicit flow.
+ */
+export declare function normalizeAibillEmailAddress(value: string): string | undefined;
+//# sourceMappingURL=emailAddress.d.ts.map

package/dist/emailAddress.js

@@ -0,0 +1,16 @@
+const controlCharacters = /[\u0000-\u001F\u007F]/u;
+const pragmaticEmailAddress = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
+/**
+ * One intentionally pragmatic normalizer for waitlist and receipt-email
+ * boundaries. It prevents header/control injection without pretending to be
+ * a mailbox-verification system; ownership still requires an explicit flow.
+ */
+export function normalizeAibillEmailAddress(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length < 3 || normalized.length > 254)
+        return undefined;
+    if (controlCharacters.test(normalized))
+        return undefined;
+    return pragmaticEmailAddress.test(normalized) ? normalized : undefined;
+}
+//# sourceMappingURL=emailAddress.js.map

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export * from "./planDetection.js";
 export * from "./planMath.js";
 export * from "./projectEconomics.js";
 export * from "./resultCard.js";
+export * from "./receiptShare.js";
 export * from "./projectEconomicsBuilder.js";
 export * from "./qualitativeIndexCache.js";
 export * from "./projectIndexStore.js";

package/dist/index.js

@@ -21,6 +21,7 @@ export * from "./planDetection.js";
 export * from "./planMath.js";
 export * from "./projectEconomics.js";
 export * from "./resultCard.js";
+export * from "./receiptShare.js";
 export * from "./projectEconomicsBuilder.js";
 export * from "./qualitativeIndexCache.js";
 export * from "./projectIndexStore.js";

package/dist/providerConnectors.d.ts

@@ -89,6 +89,13 @@ export type ProviderConnectorInput = {
      * shipped CLI can run a reconciliation without new flags.
      */
     reconciliation?: CursorReconciliationExpectation;
+    /**
+     * Operator-declared reconciliation anchor for a GitHub Copilot sync. When
+     * absent, the Copilot connector also accepts the
+     * AI_SPEND_COPILOT_RECONCILE_* environment variables so the shipped CLI can
+     * run a reconciliation without new flags.
+     */
+    copilotReconciliation?: GitHubCopilotReconciliationExpectation;
 };
 /**
  * A human-read billing anchor for one Cursor reconciliation run: the
@@ -141,6 +148,69 @@ export declare function parseCursorReconciliationEnv(env?: Record<string, string
     expectation?: CursorReconciliationExpectation;
     invalidReason?: string;
 };
+/**
+ * A human-read billing anchor for one GitHub Copilot reconciliation run: the
+ * AI-credit NET total the operator read off the organization's Billing &
+ * Licensing usage page for one calendar billing month (GitHub moved every
+ * Copilot Business/Enterprise account to usage-based AI-credit billing on
+ * 2026-06-01; 1 AI credit bills as $0.01). The connector compares its summed
+ * netAmount from the AI-credit usage report against this figure; only an
+ * in-run match within tolerance can produce verified financial evidence.
+ */
+export type GitHubCopilotReconciliationExpectation = {
+    /** Billing-page AI-credit net total for the declared month, in USD. */
+    expectedNetUsd: number;
+    /** The billing month shown next to that figure (YYYY-MM, UTC calendar month). */
+    expectedBillingMonth: string;
+    /**
+     * Optional absolute comparison tolerance in USD. Defaults to $0.01 (the
+     * billing page rounds to cents). Clamped to at most 1% of the expected total
+     * so a huge tolerance can never rubber-stamp a mismatch.
+     */
+    toleranceUsd?: number;
+    /**
+     * Optional account binding: a bare slug or `org:<slug>` / `enterprise:<slug>`.
+     * When present, the anchor applies ONLY to a sync of that account; a sync
+     * of any other org/enterprise fails the reconciliation closed (QA C3 —
+     * leftover shell env must never verify a different account by coincidence).
+     */
+    account?: string;
+};
+export type GitHubCopilotReconciliationOutcome = {
+    status: "verified" | "mismatch" | "not_provable";
+    /** Product-authored, terminal-safe explanation of the outcome. */
+    note: string;
+    connectorTotalUsd?: number;
+    expectedNetUsd?: number;
+    differenceUsd?: number;
+    toleranceUsd?: number;
+    /** The billing month the reconciliation was declared for (YYYY-MM). */
+    billingMonth?: string;
+};
+/** Environment variables the GitHub Copilot connector reads for a reconciliation run. */
+export declare const gitHubCopilotReconciliationEnvVars: {
+    readonly expectedUsd: "AI_SPEND_COPILOT_RECONCILE_EXPECTED_USD";
+    readonly billingMonth: "AI_SPEND_COPILOT_RECONCILE_MONTH";
+    readonly toleranceUsd: "AI_SPEND_COPILOT_RECONCILE_TOLERANCE_USD";
+    /**
+     * Optional binding of the anchor to ONE account (post-hoc QA C3): a bare
+     * slug or `org:<slug>` / `enterprise:<slug>`. When set, a sync of any
+     * other account fails the reconciliation closed instead of stamping a
+     * coincidence-equal total verified with leftover shell env.
+     */
+    readonly account: "AI_SPEND_COPILOT_RECONCILE_ACCOUNT";
+};
+/**
+ * Read an operator-declared GitHub Copilot reconciliation anchor from the
+ * local environment. Absent variables mean "no reconciliation requested";
+ * present but invalid variables fail closed with a reason (records stay
+ * estimated) instead of throwing, so a typo can never abort or silently
+ * verify a sync. Raw variable values are never echoed into the reason.
+ */
+export declare function parseGitHubCopilotReconciliationEnv(env?: Record<string, string | undefined>): {
+    expectation?: GitHubCopilotReconciliationExpectation;
+    invalidReason?: string;
+};
 export type ProviderConnectorResult = {
     provider: string;
     source: ApprovedSource;
@@ -179,6 +249,17 @@ export declare function normalizeAnthropicClaudeCodeUsageResponse(response: unkn
 export declare function normalizeGitHubCopilotSeatResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function normalizeAnthropicCostResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function normalizeGitHubCopilotMetricsResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+/**
+ * Normalize one GitHub AI-credit usage report (the 2026 usage-based billing
+ * model: GET /organizations/{org}/settings/billing/ai_credit/usage) into
+ * billed-dollar evidence records. Rows are NET provider-reported dollars, but
+ * this connector is fixture-verified, so — exactly like the Cursor connector —
+ * the records stay "estimated" until an in-run reconciliation proves the
+ * connector total against the operator-read billing page figure for the same
+ * billing month. Legacy premium-request units are deliberately not fetched or
+ * blended here (provider-contract exclusion).
+ */
+export declare function normalizeGitHubCopilotAiCreditUsageResponse(response: unknown, options: NormalizerOptions, reconciliation?: GitHubCopilotReconciliationOutcome): UsageRecord[];
 export declare function normalizeCursorSpendResponse(response: unknown, options: NormalizerOptions, reconciliation?: CursorReconciliationOutcome): UsageRecord[];
 export declare function fetchProviderUsageRecords(input: ProviderConnectorInput): Promise<ProviderConnectorResult>;
 export declare function summarizeProviderFinancials(records: UsageRecord[]): ProviderFinancialSummary;

package/dist/providerConnectors.js

@@ -69,6 +69,80 @@ function invalidCursorReconciliationExpectationReason(expectation) {
     }
     return undefined;
 }
+/** Environment variables the GitHub Copilot connector reads for a reconciliation run. */
+export const gitHubCopilotReconciliationEnvVars = {
+    expectedUsd: "AI_SPEND_COPILOT_RECONCILE_EXPECTED_USD",
+    billingMonth: "AI_SPEND_COPILOT_RECONCILE_MONTH",
+    toleranceUsd: "AI_SPEND_COPILOT_RECONCILE_TOLERANCE_USD",
+    /**
+     * Optional binding of the anchor to ONE account (post-hoc QA C3): a bare
+     * slug or `org:<slug>` / `enterprise:<slug>`. When set, a sync of any
+     * other account fails the reconciliation closed instead of stamping a
+     * coincidence-equal total verified with leftover shell env.
+     */
+    account: "AI_SPEND_COPILOT_RECONCILE_ACCOUNT"
+};
+/**
+ * Read an operator-declared GitHub Copilot reconciliation anchor from the
+ * local environment. Absent variables mean "no reconciliation requested";
+ * present but invalid variables fail closed with a reason (records stay
+ * estimated) instead of throwing, so a typo can never abort or silently
+ * verify a sync. Raw variable values are never echoed into the reason.
+ */
+export function parseGitHubCopilotReconciliationEnv(env = process.env) {
+    const rawExpected = env[gitHubCopilotReconciliationEnvVars.expectedUsd];
+    const rawMonth = env[gitHubCopilotReconciliationEnvVars.billingMonth];
+    const rawTolerance = env[gitHubCopilotReconciliationEnvVars.toleranceUsd];
+    const rawAccount = env[gitHubCopilotReconciliationEnvVars.account];
+    // A dangling ACCOUNT binding alone requests nothing — it only constrains a
+    // reconciliation that the expected/month pair actually requested.
+    if (rawExpected === undefined && rawMonth === undefined && rawTolerance === undefined) {
+        return {};
+    }
+    if (rawExpected === undefined || rawMonth === undefined) {
+        return {
+            invalidReason: `both ${gitHubCopilotReconciliationEnvVars.expectedUsd} and ${gitHubCopilotReconciliationEnvVars.billingMonth} are required to request a reconciliation`
+        };
+    }
+    const expectedNetUsd = Number(rawExpected.trim());
+    const toleranceUsd = rawTolerance === undefined ? undefined : Number(rawTolerance.trim());
+    const account = rawAccount?.trim();
+    const expectation = {
+        expectedNetUsd,
+        expectedBillingMonth: rawMonth.trim(),
+        ...(toleranceUsd === undefined ? {} : { toleranceUsd }),
+        ...(account ? { account } : {})
+    };
+    const invalidReason = invalidGitHubCopilotReconciliationExpectationReason(expectation);
+    return invalidReason ? { invalidReason } : { expectation };
+}
+function invalidGitHubCopilotReconciliationExpectationReason(expectation) {
+    if (!Number.isFinite(expectation.expectedNetUsd) || expectation.expectedNetUsd <= 0) {
+        return `${gitHubCopilotReconciliationEnvVars.expectedUsd} must be a positive USD amount read off the GitHub billing usage page`;
+    }
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(expectation.expectedBillingMonth)) {
+        return `${gitHubCopilotReconciliationEnvVars.billingMonth} must be the billing month shown on the usage page, formatted YYYY-MM`;
+    }
+    if (expectation.toleranceUsd !== undefined &&
+        (!Number.isFinite(expectation.toleranceUsd) || expectation.toleranceUsd < 0)) {
+        return `${gitHubCopilotReconciliationEnvVars.toleranceUsd} must be a non-negative USD amount when set`;
+    }
+    if (expectation.account !== undefined &&
+        !/^(?:(?:org|enterprise):)?[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(expectation.account)) {
+        // Never echo the raw value — env parse reasons are printed verbatim.
+        return `${gitHubCopilotReconciliationEnvVars.account} must be an org/enterprise slug, optionally prefixed org: or enterprise:`;
+    }
+    return undefined;
+}
+/**
+ * Shared reconciliation tolerance rule: default $0.01 (billing pages round to
+ * cents) and clamp to at most 1% of the expected figure so an oversized
+ * tolerance can never manufacture a match.
+ */
+function clampReconciliationToleranceUsd(expectedUsd, requestedToleranceUsd) {
+    const requested = Math.max(requestedToleranceUsd ?? 0.01, 0.01);
+    return Math.min(requested, Math.max(0.01, expectedUsd * 0.01));
+}
 export function normalizeOpenAiCostResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
@@ -449,6 +523,71 @@ export function normalizeGitHubCopilotMetricsResponse(response, options) {
     }
     return records;
 }
+/**
+ * Normalize one GitHub AI-credit usage report (the 2026 usage-based billing
+ * model: GET /organizations/{org}/settings/billing/ai_credit/usage) into
+ * billed-dollar evidence records. Rows are NET provider-reported dollars, but
+ * this connector is fixture-verified, so — exactly like the Cursor connector —
+ * the records stay "estimated" until an in-run reconciliation proves the
+ * connector total against the operator-read billing page figure for the same
+ * billing month. Legacy premium-request units are deliberately not fetched or
+ * blended here (provider-contract exclusion).
+ */
+export function normalizeGitHubCopilotAiCreditUsageResponse(response, options, reconciliation) {
+    const items = extractArray(response, "usageItems");
+    const timePeriod = isRecord(response) && isRecord(response.timePeriod) ? response.timePeriod : undefined;
+    const year = nonNegativeIntegerValue(timePeriod?.year);
+    const month = nonNegativeIntegerValue(timePeriod?.month);
+    const day = nonNegativeIntegerValue(timePeriod?.day);
+    const monthKey = typeof year === "number" && typeof month === "number" && month >= 1 && month <= 12
+        ? `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}`
+        : undefined;
+    const timestampDate = monthKey && typeof day === "number" && day >= 1 && day <= 31
+        ? `${monthKey}-${String(day).padStart(2, "0")}`
+        : monthKey
+            ? `${monthKey}-01`
+            : undefined;
+    const timestamp = timestampDate && Number.isFinite(Date.parse(`${timestampDate}T00:00:00Z`))
+        ? new Date(`${timestampDate}T00:00:00Z`).toISOString()
+        : new Date().toISOString();
+    // Fail-closed stamping mirror of the Cursor connector: only an in-run
+    // reconciliation match may flip these records to "verified"; a mismatched or
+    // unprovable reconciliation keeps them estimated.
+    const reconciled = reconciliation?.status === "verified";
+    const confidence = reconciled ? "verified" : "estimated";
+    return items.flatMap((item, index) => {
+        if (!isRecord(item))
+            return [];
+        const product = stringValue(item.product);
+        const sku = stringValue(item.sku);
+        const netAmountUsd = parseDollarUsd(item.netAmount);
+        if (!product || !sku || typeof netAmountUsd !== "number")
+            return [];
+        const model = stringValue(item.model);
+        const grossAmountUsd = parseDollarUsd(item.grossAmount);
+        const discountAmountUsd = parseDollarUsd(item.discountAmount);
+        const netQuantity = nonNegativeNumberValue(item.netQuantity);
+        const amounts = typeof grossAmountUsd === "number" && typeof discountAmountUsd === "number"
+            ? `gross $${grossAmountUsd.toFixed(2)} - discounts $${discountAmountUsd.toFixed(2)} = net $${netAmountUsd.toFixed(2)}`
+            : `net $${netAmountUsd.toFixed(2)}`;
+        const baseOperation = `GitHub AI-credit billed usage${monthKey ? ` for ${monthKey}` : ""} (${sku}; ${amounts}; metered spend, excludes seat license fees)`;
+        return [{
+                id: slugifySourceId(["github-copilot-ai-credit", monthKey ?? "unknown-month", options.accountId, product, sku, model, String(index)].filter(Boolean).join("-")),
+                timestamp,
+                source: { id: options.sourceId, name: "GitHub AI-credit usage report", provider: "github-copilot", confidence, observedFrom: options.observedFrom },
+                model: model ?? sku,
+                inputTokens: 0,
+                outputTokens: 0,
+                amountUsd: netAmountUsd,
+                costConfidence: confidence,
+                projectId: options.accountId,
+                providerCostType: "copilot_ai_credit_billing",
+                usageGranularity: "billing_bucket",
+                ...(netQuantity === undefined ? {} : { quantity: netQuantity }),
+                operation: reconciled ? `${baseOperation}; ${reconciliation.note}` : baseOperation
+            }];
+    });
+}
 export function normalizeCursorSpendResponse(response, options, reconciliation) {
     const users = extractArray(response, "teamMemberSpend");
     const cycleStart = isRecord(response) ? numberValue(response.subscriptionCycleStart) : undefined;
@@ -622,9 +761,247 @@ async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
     const seatFetch = input.org ? await fetchPaginatedJson(fetcher, buildGitHubCopilotSeatsUrl(input.org), request, "github-copilot", "GitHub Copilot seats") : undefined;
     if (seatFetch)
         assessGitHubCopilotSeatCompleteness(seatFetch);
-    const metricsRecords = metricsFetch.pages.flatMap((page) => normalizeGitHubCopilotMetricsResponse(page, { sourceId, observedFrom: "GitHub Copilot metrics API", accountId }));
-    const seatRecords = seatFetch ? seatFetch.pages.flatMap((page) => normalizeGitHubCopilotSeatResponse(page, { sourceId, observedFrom: "GitHub Copilot billing seats API", accountId })) : [];
-    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords], qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : [])]));
+    const requested = input.copilotReconciliation
+        ? { expectation: input.copilotReconciliation, invalidReason: invalidGitHubCopilotReconciliationExpectationReason(input.copilotReconciliation) }
+        : parseGitHubCopilotReconciliationEnv();
+    const aiCredit = await fetchGitHubCopilotAiCreditUsage(fetcher, input, request, requested.expectation);
+    const syncedAccount = input.org
+        ? { scope: "org", slug: input.org }
+        : { scope: "enterprise", slug: input.enterprise };
+    const reconciliation = assessGitHubCopilotReconciliation(aiCredit, requested.expectation, requested.invalidReason, syncedAccount);
+    // Dedupe every record family by stable id BEFORE the QA summary so a
+    // GitHub page-shift during churn (the same seat or day row returned on
+    // two pages) can never double-count estimated dollars or usage (QA M2).
+    const metricsRecords = dedupeGitHubCopilotRecordsById(metricsFetch.pages.flatMap((page) => normalizeGitHubCopilotMetricsResponse(page, { sourceId, observedFrom: "GitHub Copilot metrics API", accountId })), metricsFetch);
+    const seatRecords = seatFetch
+        ? dedupeGitHubCopilotRecordsById(seatFetch.pages.flatMap((page) => normalizeGitHubCopilotSeatResponse(page, { sourceId, observedFrom: "GitHub Copilot billing seats API", accountId })), seatFetch)
+        : [];
+    const aiCreditRecords = aiCredit.fetch
+        ? dedupeGitHubCopilotRecordsById(aiCredit.fetch.pages.flatMap((page) => normalizeGitHubCopilotAiCreditUsageResponse(page, { sourceId, observedFrom: "GitHub AI-credit usage report", accountId }, reconciliation)), aiCredit.fetch)
+        : [];
+    const qa = qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : []), ...(aiCredit.fetch ? [aiCredit.fetch] : [])]);
+    if (aiCredit.unavailableReason) {
+        // A token scoped to Copilot metrics/seats alone still yields honest usage
+        // evidence, so a missing billing permission degrades to estimated records
+        // with an explicit diagnostic instead of failing the whole sync.
+        qa.instructions = [...qa.instructions, aiCredit.unavailableReason];
+        qa.responseDrift.push({
+            label: "GitHub Copilot AI-credit usage report",
+            field: "usageItems",
+            issue: aiCredit.unavailableReason
+        });
+    }
+    if (reconciliation) {
+        // The outcome must survive the persisted-QA round trip, so it rides in
+        // instructions (kept verbatim) and, on failure, in responseDrift.
+        qa.instructions = [...qa.instructions, `Reconciliation ${reconciliation.status}: ${reconciliation.note}`];
+        if (reconciliation.status !== "verified") {
+            qa.responseDrift.push({
+                label: "GitHub Copilot AI-credit usage report",
+                field: "usageItems[].netAmount (billing month total)",
+                issue: reconciliation.note
+            });
+        }
+    }
+    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords, ...aiCreditRecords], qa);
+}
+function resolveGitHubCopilotBillingMonth(expectation) {
+    if (expectation && /^\d{4}-(0[1-9]|1[0-2])$/.test(expectation.expectedBillingMonth)) {
+        const [year, month] = expectation.expectedBillingMonth.split("-").map(Number);
+        return { year: year, month: month };
+    }
+    const now = new Date();
+    return { year: now.getUTCFullYear(), month: now.getUTCMonth() + 1 };
+}
+/**
+ * Read the org/enterprise AI-credit usage report for one billing month (the
+ * declared reconciliation month, else the current UTC month). The endpoint
+ * needs the fine-grained "Administration: read" organization permission
+ * (enterprise reads: billing read); a 401/403/404 therefore degrades with an
+ * honest note instead of failing metrics/seat evidence, while transport and
+ * schema failures still fail closed.
+ */
+async function fetchGitHubCopilotAiCreditUsage(fetcher, input, request, expectation) {
+    const label = "GitHub Copilot AI-credit usage report";
+    const billingMonth = resolveGitHubCopilotBillingMonth(expectation);
+    try {
+        const response = await fetchJsonOrThrow(fetcher, buildGitHubCopilotAiCreditUsageUrl(input, billingMonth), request, "github-copilot", label);
+        const fetchResult = {
+            pages: [response.payload],
+            pagination: { label, pagesFetched: 1, stoppedBecause: "complete", maxPages: 1 },
+            rateLimits: response.rateLimit ? [response.rateLimit] : [],
+            responseDrift: detectResponseDrift(response.payload, "github-copilot", label)
+        };
+        markMalformedGitHubCopilotAiCreditRows(fetchResult, label);
+        return { fetch: fetchResult, billingMonth };
+    }
+    catch (error) {
+        const status = error instanceof ProviderConnectorError ? error.status : undefined;
+        if (error instanceof ProviderConnectorError && (error.code === "authentication_error" || status === 404)) {
+            return {
+                billingMonth,
+                unavailableReason: `GitHub AI-credit usage report was unavailable (HTTP ${status ?? "error"}); billed dollars were skipped. Grant the fine-grained "Administration: read" organization permission (enterprise: billing read) to include them.`
+            };
+        }
+        throw error;
+    }
+}
+function buildGitHubCopilotAiCreditUsageUrl(input, billingMonth) {
+    const base = input.enterprise
+        ? `https://api.github.com/enterprises/${encodeURIComponent(input.enterprise)}/settings/billing/ai_credit/usage`
+        : input.org
+            ? `https://api.github.com/organizations/${encodeURIComponent(input.org)}/settings/billing/ai_credit/usage`
+            : undefined;
+    if (!base)
+        throw new Error("GitHub Copilot connector requires --org or --enterprise.");
+    const url = new URL(base);
+    url.searchParams.set("year", String(billingMonth.year));
+    url.searchParams.set("month", String(billingMonth.month));
+    return url.toString();
+}
+function markMalformedGitHubCopilotAiCreditRows(fetchResult, label) {
+    const issues = [];
+    const report = (field, issue) => issues.push({ label, field, issue });
+    for (const page of fetchResult.pages) {
+        if (!isRecord(page) || !Array.isArray(page.usageItems)) {
+            report("usageItems", "AI-credit usage response omitted the canonical usageItems array; completeness cannot be proven");
+            continue;
+        }
+        if (!isRecord(page.timePeriod) || typeof nonNegativeIntegerValue(page.timePeriod.year) !== "number") {
+            report("timePeriod", "AI-credit usage response omitted the documented timePeriod object; the billing month cannot be proven");
+        }
+        for (const [index, item] of page.usageItems.entries()) {
+            const itemPath = `usageItems[${index}]`;
+            if (!isRecord(item)) {
+                report(itemPath, "AI-credit usage response contained a non-object usage row; the row was excluded");
+                continue;
+            }
+            if (!stringValue(item.product) || !stringValue(item.sku)) {
+                report(`${itemPath}.product/sku`, "AI-credit usage row is missing its product or sku label; the row was excluded");
+            }
+            if (typeof parseDollarUsd(item.netAmount) !== "number") {
+                report(`${itemPath}.netAmount`, "AI-credit usage row requires a non-negative USD netAmount; the row was excluded");
+            }
+            for (const field of ["grossAmount", "discountAmount", "pricePerUnit", "grossQuantity", "discountQuantity", "netQuantity"]) {
+                if (item[field] !== undefined && typeof nonNegativeNumberValue(item[field]) !== "number") {
+                    report(`${itemPath}.${field}`, "AI-credit usage amounts and quantities must be non-negative numbers; the invalid value was excluded");
+                }
+            }
+        }
+    }
+    if (issues.length === 0)
+        return;
+    fetchResult.coverageIncomplete = true;
+    fetchResult.responseDrift.push(...issues);
+}
+/** Case-insensitive account-binding match; a bare slug matches either scope. */
+function gitHubCopilotAccountBindingMatches(declared, synced) {
+    if (!synced)
+        return false;
+    const normalized = declared.trim().toLowerCase();
+    const scoped = normalized.match(/^(org|enterprise):(.+)$/);
+    if (scoped) {
+        return scoped[1] === synced.scope && scoped[2] === synced.slug.toLowerCase();
+    }
+    return normalized === synced.slug.toLowerCase();
+}
+/**
+ * Compare the connector's summed AI-credit net total for one billing month
+ * against the operator-read billing page figure. Every exit that is not a
+ * window-proven match inside the clamped tolerance fails closed: the records
+ * stay estimated and the note says exactly why. Returns undefined when no
+ * reconciliation was requested.
+ */
+function assessGitHubCopilotReconciliation(aiCredit, expectation, invalidReason, syncedAccount) {
+    if (!expectation && !invalidReason)
+        return undefined;
+    if (invalidReason || !expectation) {
+        return {
+            status: "not_provable",
+            note: `GitHub Copilot reconciliation input was rejected (${invalidReason ?? "missing expectation"}); records remain estimated.`
+        };
+    }
+    const billingMonth = expectation.expectedBillingMonth;
+    if (expectation.account !== undefined &&
+        !gitHubCopilotAccountBindingMatches(expectation.account, syncedAccount)) {
+        // QA C3: leftover shell env from one account's runbook pass must never
+        // stamp a different account verified on a coincidence-equal total.
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: `${gitHubCopilotReconciliationEnvVars.account} is bound to a different org/enterprise than this sync; the billing figure was not applied. Reconcile one account per shell, or update the binding. Records remain estimated.`
+        };
+    }
+    if (!aiCredit.fetch) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: `GitHub Copilot reconciliation requires the AI-credit usage report; ${aiCredit.unavailableReason ?? "the report could not be read."} Records remain estimated.`
+        };
+    }
+    if (aiCredit.fetch.pagination.stoppedBecause !== "complete" || aiCredit.fetch.coverageIncomplete === true) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: "GitHub Copilot reconciliation requires a complete AI-credit report; the response was incomplete or partially malformed, so billed dollars cannot be verified. Records remain estimated."
+        };
+    }
+    for (const page of aiCredit.fetch.pages) {
+        const timePeriod = isRecord(page) && isRecord(page.timePeriod) ? page.timePeriod : undefined;
+        const year = nonNegativeIntegerValue(timePeriod?.year);
+        const month = nonNegativeIntegerValue(timePeriod?.month);
+        const monthKey = typeof year === "number" && typeof month === "number"
+            ? `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}`
+            : undefined;
+        if (monthKey !== billingMonth) {
+            return {
+                status: "not_provable",
+                billingMonth,
+                note: `The declared billing month ${billingMonth} does not match the provider-reported time period${monthKey ? ` ${monthKey}` : ""}; the billing page figure and the connector read different windows. Records remain estimated.`
+            };
+        }
+        if (timePeriod?.day !== undefined) {
+            // Fail closed on any day field (null included), and say WHY without
+            // the self-contradictory month-vs-same-month wording (QA A4): a
+            // day-scoped report cannot anchor a whole-month billing figure.
+            return {
+                status: "not_provable",
+                billingMonth,
+                note: `GitHub Copilot reconciliation requires a whole-month AI-credit report; the provider-reported time period carries a day field, so the monthly billing page figure cannot be compared against it. Records remain estimated.`
+            };
+        }
+    }
+    const connectorTotalUsd = aiCredit.fetch.pages.reduce((sum, page) => sum + extractArray(page, "usageItems").reduce((pageSum, item) => pageSum + (isRecord(item) ? parseDollarUsd(item.netAmount) ?? 0 : 0), 0), 0);
+    if (!(connectorTotalUsd > 0)) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            connectorTotalUsd,
+            expectedNetUsd: expectation.expectedNetUsd,
+            note: "GitHub Copilot reconciliation needs a non-zero connector total; matching $0.00 against a billing page figure proves nothing (a fully promo-discounted month cannot verify). Records remain estimated."
+        };
+    }
+    const toleranceUsd = clampReconciliationToleranceUsd(expectation.expectedNetUsd, expectation.toleranceUsd);
+    const differenceUsd = Math.abs(connectorTotalUsd - expectation.expectedNetUsd);
+    const shared = {
+        connectorTotalUsd,
+        expectedNetUsd: expectation.expectedNetUsd,
+        differenceUsd,
+        toleranceUsd,
+        billingMonth
+    };
+    if (differenceUsd <= toleranceUsd + 1e-9) {
+        return {
+            status: "verified",
+            ...shared,
+            note: `reconciled to the operator-read GitHub billing usage AI-credit net total $${expectation.expectedNetUsd.toFixed(2)} for the billing month ${billingMonth}: connector total $${connectorTotalUsd.toFixed(2)}, difference $${differenceUsd.toFixed(2)} within tolerance $${toleranceUsd.toFixed(2)}`
+        };
+    }
+    return {
+        status: "mismatch",
+        ...shared,
+        note: `GitHub Copilot reconciliation mismatch: connector AI-credit net total $${connectorTotalUsd.toFixed(2)} vs operator-read $${expectation.expectedNetUsd.toFixed(2)} for the billing month ${billingMonth}; difference $${differenceUsd.toFixed(2)} exceeds tolerance $${toleranceUsd.toFixed(2)}. Records remain estimated until the totals agree.`
+    };
 }
 async function fetchCursor(input, token, fetcher, sourceId) {
     const accountId = input.accountId ?? input.org ?? "cursor-team";
@@ -701,10 +1078,7 @@ function assessCursorReconciliation(spendFetch, expectation, invalidReason) {
             note: "Cursor reconciliation needs a non-zero connector total; matching $0.00 against a dashboard figure proves nothing. Records remain estimated."
         };
     }
-    // Default $0.01 (dashboards round to cents); clamp to at most 1% of the
-    // expected figure so an oversized tolerance cannot manufacture a match.
-    const requestedTolerance = Math.max(expectation.toleranceUsd ?? 0.01, 0.01);
-    const toleranceUsd = Math.min(requestedTolerance, Math.max(0.01, expectation.expectedOnDemandUsd * 0.01));
+    const toleranceUsd = clampReconciliationToleranceUsd(expectation.expectedOnDemandUsd, expectation.toleranceUsd);
     const differenceUsd = Math.abs(connectorTotalUsd - expectation.expectedOnDemandUsd);
     const shared = {
         connectorTotalUsd,
@@ -918,7 +1292,27 @@ function assessGitHubCopilotSeatCompleteness(fetchResult) {
     const expected = fetchResult.pages
         .map((page) => isRecord(page) ? numberValue(page.total_seats) : undefined)
         .find((value) => typeof value === "number");
-    const actual = fetchResult.pages.reduce((sum, page) => sum + extractArray(page, "seats").length, 0);
+    // Count UNIQUE seat identities (same derivation as the normalizer), not raw
+    // rows: a GitHub page-shift during churn can return the same assignee on
+    // two pages, which would otherwise satisfy total_seats while a real seat
+    // went unfetched (QA M2). Rows without any identity still count singly.
+    const identities = new Set();
+    let unidentifiedRows = 0;
+    for (const page of fetchResult.pages) {
+        for (const seat of extractArray(page, "seats")) {
+            if (!isRecord(seat)) {
+                unidentifiedRows += 1;
+                continue;
+            }
+            const assignee = isRecord(seat.assignee) ? seat.assignee : {};
+            const identity = stringValue(assignee.login) ?? stringValue(assignee.email) ?? stringValue(seat.login) ?? stringValue(seat.id);
+            if (identity)
+                identities.add(identity);
+            else
+                unidentifiedRows += 1;
+        }
+    }
+    const actual = identities.size + unidentifiedRows;
     if (typeof expected !== "number") {
         if (fetchResult.pagination.stoppedBecause === "complete")
             fetchResult.pagination.stoppedBecause = "missing_cursor";
@@ -927,10 +1321,42 @@ function assessGitHubCopilotSeatCompleteness(fetchResult) {
     }
     else if (fetchResult.pagination.stoppedBecause === "complete" && actual !== expected) {
         fetchResult.pagination.stoppedBecause = "missing_cursor";
-        fetchResult.pagination.note = `GitHub reported ${expected} seats but returned ${actual}; completeness cannot be proven.`;
+        fetchResult.pagination.note = `GitHub reported ${expected} seats but returned ${actual} unique seat identit${actual === 1 ? "y" : "ies"}; completeness cannot be proven.`;
         fetchResult.responseDrift.push({ label: "GitHub Copilot seats", field: "total_seats", issue: fetchResult.pagination.note });
     }
 }
+/**
+ * Dedupe one normalized GitHub Copilot record family by stable id, mirroring
+ * the OpenAI dedupe semantics: an identical duplicate is excluded with a
+ * drift note; conflicting rows sharing one id are ALL excluded (evidence
+ * that cannot be told apart must not be counted). Any duplicate marks the
+ * fetch's coverage incomplete so the sync reports partial instead of
+ * silently inflating estimated dollars (QA M2).
+ */
+function dedupeGitHubCopilotRecordsById(records, fetchResult) {
+    const byId = new Map();
+    const conflicted = new Set();
+    for (const record of records) {
+        const existing = byId.get(record.id);
+        if (!existing && !conflicted.has(record.id)) {
+            byId.set(record.id, record);
+            continue;
+        }
+        fetchResult.coverageIncomplete = true;
+        fetchResult.responseDrift.push({
+            label: fetchResult.pagination.label,
+            field: "normalized records[].id",
+            issue: existing && JSON.stringify(existing) === JSON.stringify(record)
+                ? "duplicate provider record was excluded"
+                : "conflicting provider records shared one stable identity; all conflicting rows were excluded"
+        });
+        if (existing && JSON.stringify(existing) !== JSON.stringify(record)) {
+            byId.delete(record.id);
+            conflicted.add(record.id);
+        }
+    }
+    return Array.from(byId.values());
+}
 async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label) {
     const pages = [];
     const rateLimits = [];
@@ -1540,6 +1966,11 @@ function knownProviderFields(provider, label) {
     if (provider === "github-copilot" && label.toLowerCase().includes("metrics")) {
         return new Set([...common, "download_links", "download_links[]", "day_totals", "day_totals[]", "day_totals[].day", "day_totals[].daily_active_users", "day_totals[].totals_by_model_feature", "day_totals[].totals_by_model_feature[]", "day_totals[].totals_by_model_feature[].model", "day_totals[].totals_by_model_feature[].feature", "day_totals[].totals_by_model_feature[].engaged_users", "day_totals[].totals_by_model_feature[].total_requests", "day_totals[].totals_by_model_feature[].user_initiated_interaction_count", "day_totals[].totals_by_cli", "day_totals[].totals_by_cli.request_count", "day_totals[].totals_by_cli.prompt_count", "day_totals[].totals_by_cli.session_count", "day_totals[].totals_by_cli.token_usage", "day_totals[].totals_by_cli.token_usage.prompt_tokens_sum", "day_totals[].totals_by_cli.token_usage.output_tokens_sum", "day_totals[].totals_by_cli.token_usage.avg_tokens_per_request", "day_totals[].totals_by_cli.engaged_users", "day_totals[].totals_by_cli.total_requests", "report_start_day", "report_end_day", "created_at", "generated_at", "etl_id", "day_partition", "entity_id_partition", "enterprise_id", "organization_id"]);
     }
+    if (provider === "github-copilot" && label.toLowerCase().includes("ai-credit")) {
+        // Documented 2026 enhanced-billing usage report shape: a timePeriod echo
+        // plus usageItems rows (product/sku/model with gross/discount/net money).
+        return new Set([...common, "timePeriod", "timePeriod.year", "timePeriod.month", "timePeriod.day", "usageItems", "usageItems[]", "usageItems[].date", "usageItems[].product", "usageItems[].sku", "usageItems[].model", "usageItems[].unitType", "usageItems[].pricePerUnit", "usageItems[].grossQuantity", "usageItems[].grossAmount", "usageItems[].discountQuantity", "usageItems[].discountAmount", "usageItems[].netQuantity", "usageItems[].netAmount", "usageItems[].organizationName", "usageItems[].repositoryName"]);
+    }
     if (provider === "github-copilot" && label.toLowerCase().includes("seats")) {
         return new Set([...common, "total_seats", "seats", "seats[]", "seats[].created_at", "seats[].updated_at", "seats[].pending_cancellation_date", "seats[].last_activity_at", "seats[].last_activity_editor", "seats[].last_authenticated_at", "seats[].plan_type", "seats[].login", "seats[].id", "seats[].assignee", "seats[].assignee.login", "seats[].assignee.email", "seats[].assignee.id", "seats[].assignee.node_id", "seats[].assignee.avatar_url", "seats[].assignee.html_url", "seats[].assignee.type", "seats[].assignee.site_admin", "seats[].assigning_team", "seats[].organization"]);
     }
@@ -1585,8 +2016,11 @@ function providerInstructions(provider) {
     }
     if (provider === "github-copilot") {
         return [
-            "Use a GitHub token reference with org or enterprise Copilot metrics and billing seats read access.",
-            "Seat records estimate monthly commitment; metrics records are usage evidence without direct spend allocation."
+            "Use a GitHub token reference with org or enterprise Copilot metrics, billing seats, and billing usage read access.",
+            "Fine-grained token permissions (2026): 'Organization Copilot metrics: read' for usage metrics, 'GitHub Copilot Business: read' for seats, and 'Administration: read' for the AI-credit usage report (classic PATs: read:org and/or manage_billing:copilot; enterprise reads accept read:enterprise). The org's Copilot 'usage metrics' policy must be enabled.",
+            "Seat records estimate monthly plan commitment at list price ($19 Business / $39 Enterprise); metrics records are usage evidence without direct spend allocation.",
+            "AI-credit records carry GitHub-billed net dollars (usage-based billing for every Copilot Business/Enterprise account since 2026-06-01; 1 AI credit bills as $0.01) and stay estimated until an in-sync reconciliation matches the billing page figure; set AI_SPEND_COPILOT_RECONCILE_EXPECTED_USD and AI_SPEND_COPILOT_RECONCILE_MONTH to run one, and optionally AI_SPEND_COPILOT_RECONCILE_ACCOUNT (org:<slug> or enterprise:<slug>) to bind the anchor to one account when several are synced from one shell. Legacy premium-request billing is not fetched or blended.",
+            "Individual Copilot (Free/Pro/Pro+) exposes no org billing or metrics API; the personal-plan endpoints under /users/{username}/settings/billing need that user's own token with 'Plan: read' and are not implemented."
         ];
     }
     if (provider === "cursor") {
@@ -1610,7 +2044,7 @@ function providerPermissionPrompt(provider, label, response, payload) {
             return `Missing Anthropic Admin read scopes for ${label} (${status}). Reconnect with organization cost report and Claude Code usage report read access. ${rawMessage}`;
         }
         if (provider === "github-copilot") {
-            return `Missing GitHub Copilot org or enterprise read scopes for ${label} (${status}). Reconnect with Copilot metrics and billing seats read access. ${rawMessage}`;
+            return `Missing GitHub Copilot org or enterprise read scopes for ${label} (${status}). Reconnect with Copilot metrics, billing seats, and billing usage (Administration: read) access. ${rawMessage}`;
         }
         if (provider === "cursor") {
             return `Missing Cursor team admin read scopes for ${label} (${status}). Use Cursor Admin API access or fall back to Browser Account UI/manual export. ${rawMessage}`;

package/dist/receiptShare.d.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { type ResultCard } from "./resultCard.js";
+/**
+ * Post-launch transport groundwork only.
+ *
+ * This module does not upload, send, persist, authenticate, render markup, or
+ * expose a CLI command. It defines the bounded aggregate payload that a future
+ * opt-in receipt route may accept after its own waitlist, durable-rate-limit,
+ * retention, and mail-provider controls exist.
+ */
+export declare const RECEIPT_SHARE_V0_VERSION: "0.1.0";
+export declare const RECEIPT_SHARE_CARD_V0_KIND: "aibill.receipt_share_card";
+export declare const RECEIPT_EMAIL_REQUEST_V0_KIND: "aibill.receipt_email_request";
+export declare const receiptShareCutV0Schema: z.ZodObject<{
+    template: z.ZodEnum<{
+        route_lower_cost_model: "route_lower_cost_model";
+        narrow_context: "narrow_context";
+        cache_repeated_work: "cache_repeated_work";
+        use_batch_api: "use_batch_api";
+    }>;
+    modeledOpportunityUsd: z.ZodNumber;
+    evidence: z.ZodLiteral<"modeled_not_verified">;
+}, z.core.$strict>;
+export declare const receiptShareCardV0Schema: z.ZodObject<{
+    kind: z.ZodLiteral<"aibill.receipt_share_card">;
+    schemaVersion: z.ZodLiteral<"0.1.0">;
+    currency: z.ZodLiteral<"USD">;
+    windowDays: z.ZodNumber;
+    mode: z.ZodEnum<{
+        mixed: "mixed";
+        connected: "connected";
+        "local-logs": "local-logs";
+    }>;
+    financials: z.ZodObject<{
+        subscriptionCommitted: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            pricedSubs: z.ZodNumber;
+            totalSubs: z.ZodNumber;
+        }, z.core.$strict>;
+        apiEquivalent: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                estimated: "estimated";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        providerBilled: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                verified: "verified";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        blended: z.ZodNull;
+        blendPolicy: z.ZodLiteral<"never_blended">;
+    }, z.core.$strict>;
+    providerCount: z.ZodNumber;
+    recordCount: z.ZodNumber;
+    confidence: z.ZodEnum<{
+        estimated: "estimated";
+        verified: "verified";
+        detected_unverified: "detected_unverified";
+        missing: "missing";
+    }>;
+    cuts: z.ZodArray<z.ZodObject<{
+        template: z.ZodEnum<{
+            route_lower_cost_model: "route_lower_cost_model";
+            narrow_context: "narrow_context";
+            cache_repeated_work: "cache_repeated_work";
+            use_batch_api: "use_batch_api";
+        }>;
+        modeledOpportunityUsd: z.ZodNumber;
+        evidence: z.ZodLiteral<"modeled_not_verified">;
+    }, z.core.$strict>>;
+    contentBoundary: z.ZodObject<{
+        rawHistoryIncluded: z.ZodLiteral<false>;
+        localIdentifiersIncluded: z.ZodLiteral<false>;
+        clientMarkupIncluded: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const receiptEmailRequestV0Schema: z.ZodObject<{
+    kind: z.ZodLiteral<"aibill.receipt_email_request">;
+    schemaVersion: z.ZodLiteral<"0.1.0">;
+    recipientEmail: z.ZodString;
+    consent: z.ZodLiteral<"email_and_aggregate_card_via_mail_provider">;
+    card: z.ZodObject<{
+        kind: z.ZodLiteral<"aibill.receipt_share_card">;
+        schemaVersion: z.ZodLiteral<"0.1.0">;
+        currency: z.ZodLiteral<"USD">;
+        windowDays: z.ZodNumber;
+        mode: z.ZodEnum<{
+            mixed: "mixed";
+            connected: "connected";
+            "local-logs": "local-logs";
+        }>;
+        financials: z.ZodObject<{
+            subscriptionCommitted: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                pricedSubs: z.ZodNumber;
+                totalSubs: z.ZodNumber;
+            }, z.core.$strict>;
+            apiEquivalent: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                financialEvidence: z.ZodEnum<{
+                    estimated: "estimated";
+                    missing: "missing";
+                }>;
+            }, z.core.$strict>;
+            providerBilled: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                financialEvidence: z.ZodEnum<{
+                    verified: "verified";
+                    missing: "missing";
+                }>;
+            }, z.core.$strict>;
+            blended: z.ZodNull;
+            blendPolicy: z.ZodLiteral<"never_blended">;
+        }, z.core.$strict>;
+        providerCount: z.ZodNumber;
+        recordCount: z.ZodNumber;
+        confidence: z.ZodEnum<{
+            estimated: "estimated";
+            verified: "verified";
+            detected_unverified: "detected_unverified";
+            missing: "missing";
+        }>;
+        cuts: z.ZodArray<z.ZodObject<{
+            template: z.ZodEnum<{
+                route_lower_cost_model: "route_lower_cost_model";
+                narrow_context: "narrow_context";
+                cache_repeated_work: "cache_repeated_work";
+                use_batch_api: "use_batch_api";
+            }>;
+            modeledOpportunityUsd: z.ZodNumber;
+            evidence: z.ZodLiteral<"modeled_not_verified">;
+        }, z.core.$strict>>;
+        contentBoundary: z.ZodObject<{
+            rawHistoryIncluded: z.ZodLiteral<false>;
+            localIdentifiersIncluded: z.ZodLiteral<false>;
+            clientMarkupIncluded: z.ZodLiteral<false>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ReceiptShareCutV0 = z.infer<typeof receiptShareCutV0Schema>;
+export type ReceiptShareCardV0 = z.infer<typeof receiptShareCardV0Schema>;
+export type ReceiptEmailRequestV0 = z.infer<typeof receiptEmailRequestV0Schema>;
+export type BuildReceiptShareCardV0Input = {
+    resultCard: ResultCard;
+    providerCount: number;
+    recordCount: number;
+    confidence: ReceiptShareCardV0["confidence"];
+    cuts: ReceiptShareCutV0[];
+};
+/**
+ * Projects the canonical local result card into a smaller aggregate-only
+ * transport card. Subscription labels, project rows, runways, record IDs,
+ * source metadata, prompts, paths, and raw history are intentionally omitted.
+ */
+export declare function buildReceiptShareCardV0(input: BuildReceiptShareCardV0Input): ReceiptShareCardV0;
+export declare const RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H: 1;
+export declare const RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H: 10;
+declare const receiptEmailDeliveryStateV0Schema: z.ZodObject<{
+    waitlistMember: z.ZodBoolean;
+    emailSendsLast24Hours: z.ZodNumber;
+    ipSendsLast24Hours: z.ZodNumber;
+}, z.core.$strict>;
+export type ReceiptEmailDeliveryDecisionV0 = {
+    status: "join_first";
+    httpStatus: 403;
+} | {
+    status: "rate_limited";
+    httpStatus: 429;
+    scope: "email" | "ip";
+} | {
+    status: "accepted";
+    httpStatus: 202;
+};
+/**
+ * Pure authorization policy for a future route. Counters must come from a
+ * durable shared store; this function creates no in-memory limiter and has no
+ * persistence or network side effects.
+ */
+export declare function decideReceiptEmailDeliveryV0(state: z.input<typeof receiptEmailDeliveryStateV0Schema>): ReceiptEmailDeliveryDecisionV0;
+export {};
+//# sourceMappingURL=receiptShare.d.ts.map

package/dist/receiptShare.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { resultCardSchema, resultCardTotalsSchema } from "./resultCard.js";
+/**
+ * Post-launch transport groundwork only.
+ *
+ * This module does not upload, send, persist, authenticate, render markup, or
+ * expose a CLI command. It defines the bounded aggregate payload that a future
+ * opt-in receipt route may accept after its own waitlist, durable-rate-limit,
+ * retention, and mail-provider controls exist.
+ */
+export const RECEIPT_SHARE_V0_VERSION = "0.1.0";
+export const RECEIPT_SHARE_CARD_V0_KIND = "aibill.receipt_share_card";
+export const RECEIPT_EMAIL_REQUEST_V0_KIND = "aibill.receipt_email_request";
+const boundedUsdSchema = z.number().finite().nonnegative().max(1_000_000_000);
+export const receiptShareCutV0Schema = z.object({
+    template: z.enum([
+        "route_lower_cost_model",
+        "narrow_context",
+        "cache_repeated_work",
+        "use_batch_api"
+    ]),
+    modeledOpportunityUsd: boundedUsdSchema.positive(),
+    evidence: z.literal("modeled_not_verified")
+}).strict();
+export const receiptShareCardV0Schema = z.object({
+    kind: z.literal(RECEIPT_SHARE_CARD_V0_KIND),
+    schemaVersion: z.literal(RECEIPT_SHARE_V0_VERSION),
+    currency: z.literal("USD"),
+    windowDays: z.number().int().min(1).max(365),
+    // Demo/sample payloads are intentionally ineligible for real delivery.
+    mode: z.enum(["local-logs", "connected", "mixed"]),
+    /** Canonical three-basis stack, including blended:null/never_blended. */
+    financials: resultCardTotalsSchema,
+    providerCount: z.number().int().positive().max(64),
+    recordCount: z.number().int().positive().max(1_000_000),
+    confidence: z.enum(["verified", "estimated", "detected_unverified", "missing"]),
+    /** Fixed templates only: no client-provided title, model, operation, or markup. */
+    cuts: z.array(receiptShareCutV0Schema).max(3),
+    contentBoundary: z.object({
+        rawHistoryIncluded: z.literal(false),
+        localIdentifiersIncluded: z.literal(false),
+        clientMarkupIncluded: z.literal(false)
+    }).strict()
+}).strict().superRefine((card, context) => {
+    if (card.providerCount > card.recordCount) {
+        context.addIssue({
+            code: "custom",
+            path: ["providerCount"],
+            message: "Provider count cannot exceed aggregate record count."
+        });
+    }
+});
+// Deliberately ASCII and single-line. The future route must additionally use
+// the already-waitlisted normalized address as its authorization identity.
+const receiptRecipientEmailV0Schema = z.string()
+    .trim()
+    .toLowerCase()
+    .min(3)
+    .max(254)
+    .regex(/^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/u);
+export const receiptEmailRequestV0Schema = z.object({
+    kind: z.literal(RECEIPT_EMAIL_REQUEST_V0_KIND),
+    schemaVersion: z.literal(RECEIPT_SHARE_V0_VERSION),
+    recipientEmail: receiptRecipientEmailV0Schema,
+    /** Names both pieces of data and the third-party transit boundary. */
+    consent: z.literal("email_and_aggregate_card_via_mail_provider"),
+    card: receiptShareCardV0Schema
+}).strict();
+/**
+ * Projects the canonical local result card into a smaller aggregate-only
+ * transport card. Subscription labels, project rows, runways, record IDs,
+ * source metadata, prompts, paths, and raw history are intentionally omitted.
+ */
+export function buildReceiptShareCardV0(input) {
+    const resultCard = resultCardSchema.parse(input.resultCard);
+    return receiptShareCardV0Schema.parse({
+        kind: RECEIPT_SHARE_CARD_V0_KIND,
+        schemaVersion: RECEIPT_SHARE_V0_VERSION,
+        currency: "USD",
+        windowDays: resultCard.windowDays,
+        mode: resultCard.mode,
+        financials: resultCard.totals,
+        providerCount: input.providerCount,
+        recordCount: input.recordCount,
+        confidence: input.confidence,
+        cuts: input.cuts,
+        contentBoundary: {
+            rawHistoryIncluded: false,
+            localIdentifiersIncluded: false,
+            clientMarkupIncluded: false
+        }
+    });
+}
+export const RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H = 1;
+export const RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H = 10;
+const receiptEmailDeliveryStateV0Schema = z.object({
+    waitlistMember: z.boolean(),
+    emailSendsLast24Hours: z.number().int().nonnegative().max(1_000_000),
+    ipSendsLast24Hours: z.number().int().nonnegative().max(1_000_000)
+}).strict();
+/**
+ * Pure authorization policy for a future route. Counters must come from a
+ * durable shared store; this function creates no in-memory limiter and has no
+ * persistence or network side effects.
+ */
+export function decideReceiptEmailDeliveryV0(state) {
+    const parsed = receiptEmailDeliveryStateV0Schema.parse(state);
+    if (!parsed.waitlistMember)
+        return { status: "join_first", httpStatus: 403 };
+    if (parsed.emailSendsLast24Hours >= RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H) {
+        return { status: "rate_limited", httpStatus: 429, scope: "email" };
+    }
+    if (parsed.ipSendsLast24Hours >= RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H) {
+        return { status: "rate_limited", httpStatus: 429, scope: "ip" };
+    }
+    return { status: "accepted", httpStatus: 202 };
+}
+//# sourceMappingURL=receiptShare.js.map

package/dist/sourceRegistry.js

@@ -62,10 +62,17 @@ export const providerCatalog = [
         label: "GitHub Copilot",
         preferredSourceType: "provider_api",
         preferredAccessMethod: "api",
-        verifiedFields: ["Copilot usage metrics", "seat assignments and reported plan types"],
+        // AI-credit billing (gross/discount/net) is implemented and shipped;
+        // billed dollars stay estimated until an AI_SPEND_COPILOT_RECONCILE_*
+        // reconciliation matches the billing page figure. Legacy premium-request
+        // billing is deliberately never fetched.
+        verifiedFields: [
+            "Copilot usage metrics",
+            "seat assignments and reported plan types",
+            "AI-credit gross, discount, and net billing usage report"
+        ],
         missingFields: [
             "GitHub admin token reference and organization or enterprise slug",
-            "AI-credit gross, discount, and net billing",
             "license invoice settlement"
         ]
     },
@@ -177,7 +184,7 @@ export const providerConnectorCatalog = [
         fallbackAuthModes: [],
         scopes: ["fine-grained Administration: read", "organization or enterprise billing access"],
         tokenStorage: "local_reference_only",
-        setupHint: "Use a local env reference to a GitHub token with read-only organization or enterprise Copilot metrics and seat access; AI-credit billing is not implemented."
+        setupHint: "Use a local env reference to a GitHub token with read-only organization or enterprise Copilot metrics, seat, and AI-credit billing usage access; billed AI-credit dollars stay estimated until an AI_SPEND_COPILOT_RECONCILE_* reconciliation matches the billing page figure."
     },
     {
         provider: "cursor",

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.9.1",
+  "version": "0.9.3",
+  "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",