@agent-finops/core 0.5.8 → 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: {
@@ -49,11 +50,38 @@ export function parseUsageCsv(contents) {
             userId: optionalValue(row.user_id),
             workspaceId: optionalValue(row.workspace_id),
             apiKeyId: optionalValue(row.api_key_id),
-            operation: optionalValue(row.operation)
+            providerCostType: optionalValue(row.provider_cost_type),
+            operation: optionalValue(row.operation),
+            usageGranularity: optionalValue(row.usage_granularity),
+            workloadSemantics: workloadSemantics(row)
         });
     });
 }
 function optionalValue(value) {
     return value === "" ? undefined : value;
 }
+function workloadSemantics(row) {
+    const stableInputFingerprint = optionalValue(row.stable_input_fingerprint);
+    const batchEligible = optionalBoolean(row.batch_eligible);
+    const downgradeSafe = optionalBoolean(row.downgrade_safe);
+    if (stableInputFingerprint === undefined &&
+        batchEligible === undefined &&
+        downgradeSafe === undefined) {
+        return undefined;
+    }
+    return {
+        ...(stableInputFingerprint ? { stableInputFingerprint } : {}),
+        ...(batchEligible !== undefined ? { batchEligible } : {}),
+        ...(downgradeSafe !== undefined ? { downgradeSafe } : {})
+    };
+}
+function optionalBoolean(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`Expected true/false CSV value, received ${JSON.stringify(value)}.`);
+}
 //# sourceMappingURL=sampleData.js.map

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,14 +12,45 @@ 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";
     }>;
     observedFrom: z.ZodString;
 }, z.core.$strip>;
 export type SpendSource = z.infer<typeof spendSourceSchema>;
+/**
+ * What one normalized usage record represents.
+ *
+ * Only `call` and `invocation` are precise enough to support per-workload
+ * counterfactuals such as model routing, result caching, Batch API moves, or
+ * prompt trimming. The remaining values are still useful financial evidence,
+ * but must never be silently treated as individual calls.
+ */
+export declare const usageGranularityValues: readonly ["call", "invocation", "session", "daily_aggregate", "usage_bucket", "billing_bucket", "seat", "user_aggregate"];
+export declare const usageGranularitySchema: z.ZodEnum<{
+    call: "call";
+    invocation: "invocation";
+    session: "session";
+    daily_aggregate: "daily_aggregate";
+    usage_bucket: "usage_bucket";
+    billing_bucket: "billing_bucket";
+    seat: "seat";
+    user_aggregate: "user_aggregate";
+}>;
+export type UsageGranularity = z.infer<typeof usageGranularitySchema>;
+/**
+ * Explicit adapter attestations for workload-specific optimization advice.
+ * These fields are intentionally absent by default: an operation label alone
+ * does not prove identical inputs, latency tolerance, or downgrade safety.
+ */
+export declare const workloadSemanticsSchema: z.ZodObject<{
+    stableInputFingerprint: z.ZodOptional<z.ZodString>;
+    batchEligible: z.ZodOptional<z.ZodBoolean>;
+    downgradeSafe: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type WorkloadSemantics = z.infer<typeof workloadSemanticsSchema>;
 export declare const usageRecordSchema: z.ZodObject<{
     id: z.ZodString;
     timestamp: z.ZodString;
@@ -28,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";
         }>;
@@ -40,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";
     }>;
@@ -54,14 +85,59 @@ export declare const usageRecordSchema: z.ZodObject<{
     quantity: z.ZodOptional<z.ZodNumber>;
     agentId: z.ZodOptional<z.ZodString>;
     operation: z.ZodOptional<z.ZodString>;
+    usageGranularity: z.ZodOptional<z.ZodEnum<{
+        call: "call";
+        invocation: "invocation";
+        session: "session";
+        daily_aggregate: "daily_aggregate";
+        usage_bucket: "usage_bucket";
+        billing_bucket: "billing_bucket";
+        seat: "seat";
+        user_aggregate: "user_aggregate";
+    }>>;
+    workloadSemantics: z.ZodOptional<z.ZodObject<{
+        stableInputFingerprint: z.ZodOptional<z.ZodString>;
+        batchEligible: z.ZodOptional<z.ZodBoolean>;
+        downgradeSafe: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type UsageRecord = z.infer<typeof usageRecordSchema>;
+/**
+ * True only when a record can honestly ground a modeled workload change.
+ *
+ * A provider billing row, usage bucket, seat, user total, or unlabelled legacy
+ * row may describe real spend, but it does not prove that one row was one
+ * optimizable call. Requiring both explicit call/invocation provenance and a
+ * named operation keeps aggregate connector data in accounting views without
+ * manufacturing per-call savings advice from it.
+ */
+export declare function hasModeledWorkloadEvidence(record: UsageRecord): boolean;
+/** Explicit one-call / one-model-invocation provenance, never inferred. */
+export declare function hasCallLevelProvenance(record: UsageRecord): boolean;
+/** A positive priced observation from which a dollar counterfactual can be modeled. */
+export declare function hasPricedEvidence(record: UsageRecord): boolean;
+/**
+ * Recognize the bundled demo records written by releases that predate the
+ * persisted `mode` field. The marker is deliberately narrow: every record
+ * must come from the shipped sample CSV and use a sample source identifier.
+ * This lets newer clients recover the demo boundary without guessing that an
+ * 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
+ * comparable series.
+ */
+export declare function spendComparisonKey(record: UsageRecord): string | undefined;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
         user: "user";
         project: "project";
-        client: "client";
         agent: "agent";
+        client: "client";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -76,8 +152,8 @@ export declare const attributionMappingSchema: z.ZodObject<{
         entityType: z.ZodEnum<{
             user: "user";
             project: "project";
-            client: "client";
             agent: "agent";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -89,8 +165,8 @@ export declare const attributionMappingSchema: z.ZodObject<{
         entityType: z.ZodEnum<{
             user: "user";
             project: "project";
-            client: "client";
             agent: "agent";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -99,10 +175,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
         evidence: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
     status: z.ZodEnum<{
-        unmapped: "unmapped";
         auto_mapped: "auto_mapped";
         needs_confirmation: "needs_confirmation";
         needs_question: "needs_question";
+        unmapped: "unmapped";
     }>;
     evidence: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -112,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";
     }>;
@@ -125,12 +201,13 @@ export declare const spendAnomalySchema: z.ZodObject<{
         week_over_week_spike: "week_over_week_spike";
     }>;
     key: z.ZodString;
+    comparisonKey: z.ZodOptional<z.ZodString>;
     previousAmountUsd: z.ZodNumber;
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -146,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";
     }>;
@@ -171,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";
     }>;
@@ -216,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";
     }>;
@@ -229,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>;
@@ -245,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";
         }>;
@@ -256,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";
         }>;
@@ -267,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";
         }>;
@@ -278,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";
         }>;
@@ -289,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";
         }>;
@@ -300,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";
         }>;
@@ -311,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";
         }>;
@@ -322,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";
         }>;
@@ -338,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";
         }>;
@@ -355,12 +432,13 @@ export declare const spendSummarySchema: z.ZodObject<{
             week_over_week_spike: "week_over_week_spike";
         }>;
         key: z.ZodString;
+        comparisonKey: z.ZodOptional<z.ZodString>;
         previousAmountUsd: z.ZodNumber;
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -378,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";
         }>;
@@ -416,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

@@ -13,6 +13,35 @@ export const spendSourceSchema = z.object({
     confidence: costConfidenceSchema,
     observedFrom: z.string().min(1)
 });
+/**
+ * What one normalized usage record represents.
+ *
+ * Only `call` and `invocation` are precise enough to support per-workload
+ * counterfactuals such as model routing, result caching, Batch API moves, or
+ * prompt trimming. The remaining values are still useful financial evidence,
+ * but must never be silently treated as individual calls.
+ */
+export const usageGranularityValues = [
+    "call",
+    "invocation",
+    "session",
+    "daily_aggregate",
+    "usage_bucket",
+    "billing_bucket",
+    "seat",
+    "user_aggregate"
+];
+export const usageGranularitySchema = z.enum(usageGranularityValues);
+/**
+ * Explicit adapter attestations for workload-specific optimization advice.
+ * These fields are intentionally absent by default: an operation label alone
+ * does not prove identical inputs, latency tolerance, or downgrade safety.
+ */
+export const workloadSemanticsSchema = z.object({
+    stableInputFingerprint: z.string().min(8).max(128).regex(/^[a-zA-Z0-9:_-]+$/).optional(),
+    batchEligible: z.boolean().optional(),
+    downgradeSafe: z.boolean().optional()
+}).strict();
 export const usageRecordSchema = z.object({
     id: z.string().min(1),
     timestamp: z.string().datetime({ offset: true }),
@@ -30,7 +59,9 @@ export const usageRecordSchema = z.object({
     providerCostType: z.string().min(1).optional(),
     quantity: z.number().nonnegative().optional(),
     agentId: z.string().min(1).optional(),
-    operation: z.string().min(1).optional()
+    operation: z.string().min(1).optional(),
+    usageGranularity: usageGranularitySchema.optional(),
+    workloadSemantics: workloadSemanticsSchema.optional()
 }).superRefine((record, context) => {
     if (record.costConfidence === "missing" && record.amountUsd !== null) {
         context.addIssue({
@@ -47,6 +78,79 @@ export const usageRecordSchema = z.object({
         });
     }
 });
+/**
+ * True only when a record can honestly ground a modeled workload change.
+ *
+ * A provider billing row, usage bucket, seat, user total, or unlabelled legacy
+ * row may describe real spend, but it does not prove that one row was one
+ * optimizable call. Requiring both explicit call/invocation provenance and a
+ * named operation keeps aggregate connector data in accounting views without
+ * manufacturing per-call savings advice from it.
+ */
+export function hasModeledWorkloadEvidence(record) {
+    return (hasCallLevelProvenance(record) &&
+        typeof record.operation === "string" &&
+        record.operation.trim().length > 0 &&
+        hasPricedEvidence(record));
+}
+/** Explicit one-call / one-model-invocation provenance, never inferred. */
+export function hasCallLevelProvenance(record) {
+    return record.usageGranularity === "call" || record.usageGranularity === "invocation";
+}
+/** A positive priced observation from which a dollar counterfactual can be modeled. */
+export function hasPricedEvidence(record) {
+    return (typeof record.amountUsd === "number" &&
+        record.amountUsd > 0 &&
+        record.costConfidence !== "missing");
+}
+/**
+ * Recognize the bundled demo records written by releases that predate the
+ * persisted `mode` field. The marker is deliberately narrow: every record
+ * must come from the shipped sample CSV and use a sample source identifier.
+ * This lets newer clients recover the demo boundary without guessing that an
+ * arbitrary unlabeled state is real local or connected evidence.
+ */
+export function isBundledSampleUsage(records) {
+    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
+ * provenance returns `undefined`; unknown rows must not be pooled into a fake
+ * comparable series.
+ */
+export function spendComparisonKey(record) {
+    if (!record.providerCostType || !record.usageGranularity) {
+        return undefined;
+    }
+    return [
+        record.source.id,
+        record.source.provider,
+        record.providerCostType,
+        record.usageGranularity
+    ].map((part) => encodeURIComponent(part)).join("|");
+}
 export const attributionCandidateSchema = z.object({
     entityType: z.enum(["client", "project", "agent", "user", "workspace", "api_key"]),
     entityId: z.string().min(1),
@@ -69,6 +173,7 @@ export const spendBreakdownEntrySchema = z.object({
 export const spendAnomalySchema = z.object({
     kind: z.enum(["day_over_day_spike", "week_over_week_spike"]),
     key: z.string().min(1),
+    comparisonKey: z.string().min(1).optional(),
     previousAmountUsd: z.number().nonnegative(),
     currentAmountUsd: z.number().nonnegative(),
     multiplier: z.number().nonnegative(),
@@ -150,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;