@agent-finops/core 0.5.9 → 0.6.0

package/dist/sampleData.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { usageRecordSchema } from "./schema.js";
+import { downgradeSampleUsageEvidence, parseUsageRecord } from "./schema.js";
 // One level up from dist/ = the package root, where samples/ ships (see
 // "files" in package.json). Must survive npm installation — never resolve
 // relative to the repo.
@@ -12,7 +12,8 @@ export const sampleFiles = [
 ];
 export async function loadSampleUsageData(rootDir = packageRoot) {
     const records = await Promise.all(sampleFiles.map((file) => loadUsageCsv(resolve(rootDir, file))));
-    return records.flat().sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+    return downgradeSampleUsageEvidence(records.flat())
+        .sort((left, right) => left.timestamp.localeCompare(right.timestamp));
 }
 async function loadUsageCsv(path) {
     const contents = await readFile(path, "utf8");
@@ -28,7 +29,7 @@ export function parseUsageCsv(contents) {
     return recordLines.map((line) => {
         const values = line.split(",");
         const row = Object.fromEntries(headers.map((header, index) => [header, values[index]?.trim() ?? ""]));
-        return usageRecordSchema.parse({
+        return parseUsageRecord({
             id: row.id,
             timestamp: row.timestamp,
             source: {

package/dist/schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const costConfidenceValues: readonly ["verified", "estimated", "detected_unverified", "missing"];
 export declare const costConfidenceSchema: z.ZodEnum<{
-    verified: "verified";
     estimated: "estimated";
+    verified: "verified";
     detected_unverified: "detected_unverified";
     missing: "missing";
 }>;
@@ -12,8 +12,8 @@ export declare const spendSourceSchema: z.ZodObject<{
     name: z.ZodString;
     provider: z.ZodString;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -59,8 +59,8 @@ export declare const usageRecordSchema: z.ZodObject<{
         name: z.ZodString;
         provider: z.ZodString;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -71,8 +71,8 @@ export declare const usageRecordSchema: z.ZodObject<{
     outputTokens: z.ZodNumber;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -124,6 +124,8 @@ export declare function hasPricedEvidence(record: UsageRecord): boolean;
  * arbitrary unlabeled state is real local or connected evidence.
  */
 export declare function isBundledSampleUsage(records: UsageRecord[]): boolean;
+/** A declared demo/sample mode can never carry proof-level financial labels. */
+export declare function downgradeSampleUsageEvidence(records: UsageRecord[]): UsageRecord[];
 /**
  * Stable financial cohort for period-over-period comparisons. Missing shape
  * provenance returns `undefined`; unknown rows must not be pooled into a fake
@@ -132,10 +134,10 @@ export declare function isBundledSampleUsage(records: UsageRecord[]): boolean;
 export declare function spendComparisonKey(record: UsageRecord): string | undefined;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
-        client: "client";
+        user: "user";
         project: "project";
         agent: "agent";
-        user: "user";
+        client: "client";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -148,10 +150,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     usageRecordId: z.ZodString;
     candidates: z.ZodArray<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
             agent: "agent";
-            user: "user";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -161,10 +163,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     }, z.core.$strip>>;
     selected: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
             agent: "agent";
-            user: "user";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -186,8 +188,8 @@ export declare const spendBreakdownEntrySchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -204,8 +206,8 @@ export declare const spendAnomalySchema: z.ZodObject<{
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -221,8 +223,8 @@ export declare const workflowWatchEntrySchema: z.ZodObject<{
     shareOfSpend: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -246,8 +248,8 @@ export declare const recommendationSchema: z.ZodObject<{
     }>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -291,8 +293,8 @@ export declare const spendInsightSchema: z.ZodObject<{
     affectedModels: z.ZodArray<z.ZodString>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -304,14 +306,14 @@ export declare const spendSummarySchema: z.ZodObject<{
     totalUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     confidenceBreakdown: z.ZodRecord<z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>, z.ZodNumber>;
@@ -320,8 +322,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -331,8 +333,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -342,8 +344,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -353,8 +355,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -364,8 +366,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -375,8 +377,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -386,8 +388,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -397,8 +399,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -413,8 +415,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         shareOfSpend: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -435,8 +437,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -454,8 +456,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         }>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -492,8 +494,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         affectedModels: z.ZodArray<z.ZodString>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;

package/dist/schema.js

@@ -111,8 +111,29 @@ export function hasPricedEvidence(record) {
  * arbitrary unlabeled state is real local or connected evidence.
  */
 export function isBundledSampleUsage(records) {
-    return records.length > 0 && records.every((record) => record.source.observedFrom === "sample_csv" &&
-        /(?:^|-)sample$/i.test(record.source.id));
+    return records.length > 0 && records.every(isBundledSampleRecord);
+}
+function isBundledSampleRecord(record) {
+    return record.source.observedFrom === "sample_csv" &&
+        /(?:^|-)sample$/i.test(record.source.id);
+}
+/** A declared demo/sample mode can never carry proof-level financial labels. */
+export function downgradeSampleUsageEvidence(records) {
+    return records.map(downgradeSampleRecordEvidence);
+}
+function downgradeSampleRecordEvidence(record) {
+    return {
+        ...record,
+        source: {
+            ...record.source,
+            confidence: record.source.confidence === "verified"
+                ? "estimated"
+                : record.source.confidence
+        },
+        costConfidence: record.costConfidence === "verified"
+            ? "estimated"
+            : record.costConfidence
+    };
 }
 /**
  * Stable financial cohort for period-over-period comparisons. Missing shape
@@ -234,7 +255,10 @@ export const spendSummarySchema = z.object({
     insights: z.array(spendInsightSchema).default([])
 });
 export function parseUsageRecord(value) {
-    return usageRecordSchema.parse(value);
+    const record = usageRecordSchema.parse(value);
+    if (!isBundledSampleRecord(record))
+        return record;
+    return downgradeSampleRecordEvidence(record);
 }
 export function parseSpendSummary(value) {
     return spendSummarySchema.parse(value);

package/dist/sourceRegistry.d.ts

@@ -1,15 +1,18 @@
 import type { UsageSignal } from "./discovery.js";
+import type { FinancialEvidenceStatus, SourceValidationCoverage } from "./sourceStatus.js";
 export type SourceType = "local_folder" | "provider_export" | "provider_api" | "browser_account" | "local_tool_detection" | "mcp_tool" | "internal_system";
 export type SourceAccessMethod = "file" | "api" | "browser" | "cli_detection" | "mcp" | "internal" | "manual";
 export type ConnectorAuthMode = "oauth" | "api_token_ref" | "browser_session" | "mcp_auth" | "manual_export" | "none";
 export type ConnectorTokenStorage = "local_reference_only" | "keychain_reference" | "none";
-export type SourceVerificationStatus = "verified" | "estimated" | "detected_unverified" | "missing";
+/** @deprecated Use FinancialEvidenceStatus. Kept only for persisted v1 migration. */
+export type SourceVerificationStatus = FinancialEvidenceStatus;
+export type SourceBoundaryApproval = "approved";
 export type IngestionLaneId = "local_files_exports" | "provider_apis" | "browser_account_ui" | "local_cli_tool_detection" | "mcp_internal_systems";
 export type IngestionLane = {
     id: IngestionLaneId;
     label: string;
     sourceTypes: SourceType[];
-    defaultVerification: SourceVerificationStatus;
+    defaultFinancialEvidence: FinancialEvidenceStatus;
 };
 export type ApprovedSource = {
     id: string;
@@ -22,7 +25,12 @@ export type ApprovedSource = {
     scope: string;
     lane: IngestionLaneId;
     accessMethod: SourceAccessMethod;
-    verification: SourceVerificationStatus;
+    /** Permission to read this exact boundary. This is never financial proof. */
+    boundaryApproval: SourceBoundaryApproval;
+    /** How thoroughly the connector/parser itself has been exercised. */
+    validationCoverage: SourceValidationCoverage;
+    /** Quality of the financial numbers currently emitted by this source. */
+    financialEvidence: FinancialEvidenceStatus;
     fieldsVerified: string[];
     fieldsEstimated: string[];
     fieldsMissing: string[];
@@ -73,7 +81,7 @@ export type ProviderConnectorCatalogEntry = {
 };
 export type MissingSourcePrompt = {
     provider: string;
-    status: Extract<SourceVerificationStatus, "detected_unverified" | "missing">;
+    status: Extract<FinancialEvidenceStatus, "detected_unverified" | "missing">;
     reason: string;
     detectedEvidence: string[];
     suggestedConnector: string;
@@ -100,8 +108,25 @@ export declare const providerCatalog: ProviderCatalogEntry[];
 export declare const providerConnectorCatalog: ProviderConnectorCatalogEntry[];
 export declare const defaultDeniedGlobs: string[];
 export declare function createLocalFolderSourceRegistry(rootPath: string, now?: Date): SourceRegistry;
-export declare function addApprovedSource(registry: SourceRegistry, source: Omit<ApprovedSource, "approvedAt" | "readOnly" | "scope" | "lane" | "accessMethod" | "verification" | "fieldsVerified" | "fieldsEstimated" | "fieldsMissing"> & Partial<Pick<ApprovedSource, "readOnly" | "scope" | "lane" | "accessMethod" | "verification" | "fieldsVerified" | "fieldsEstimated" | "fieldsMissing" | "authMode" | "authScopes" | "tokenStorage" | "authReference">>, now?: Date): SourceRegistry;
+export declare function addApprovedSource(registry: SourceRegistry, source: Omit<ApprovedSource, "approvedAt" | "readOnly" | "scope" | "lane" | "accessMethod" | "boundaryApproval" | "validationCoverage" | "financialEvidence" | "fieldsVerified" | "fieldsEstimated" | "fieldsMissing"> & Partial<Pick<ApprovedSource, "readOnly" | "scope" | "lane" | "accessMethod" | "boundaryApproval" | "validationCoverage" | "financialEvidence" | "fieldsVerified" | "fieldsEstimated" | "fieldsMissing" | "authMode" | "authScopes" | "tokenStorage" | "authReference">>, now?: Date): SourceRegistry;
 export declare function createProviderConnectorStub(provider: string, type?: SourceType, now?: Date): ApprovedSource;
+/**
+ * Read a persisted source registry into the canonical three-axis contract.
+ *
+ * Version 1 registries used `verification` for several unrelated meanings.
+ * It is accepted here only as a migration input for financial evidence and is
+ * deliberately omitted from the returned object. A local-folder approval is
+ * permission metadata, so even a legacy `verification: "verified"` migrates
+ * to `financialEvidence: "missing"`.
+ */
+export declare function normalizeSourceRegistry(value: unknown): SourceRegistry;
+/**
+ * Persisted source registries are repository-controlled configuration. Until
+ * an external provider-sync receipt binds their exact bytes, keep only the
+ * approved read-only boundary and remove any self-asserted validation or
+ * financial-evidence claims.
+ */
+export declare function downgradeUntrustedSourceRegistryClaims(registry: SourceRegistry): SourceRegistry;
 export declare function buildMissingSourcePrompts(signals: UsageSignal[], registry: SourceRegistry): MissingSourcePrompt[];
 export declare function confirmMapping(input: Omit<ConfirmedMapping, "id" | "status" | "confirmedAt">, now?: Date): ConfirmedMapping;
 export declare function createScanAuditLog(events?: ScanAuditEvent[]): ScanAuditLog;