@agent-finops/core 0.5.8 → 0.6.0

package/dist/sourceRegistry.js

@@ -3,31 +3,31 @@ export const ingestionLanes = [
         id: "local_files_exports",
         label: "Local files and provider exports",
         sourceTypes: ["local_folder", "provider_export"],
-        defaultVerification: "estimated"
+        defaultFinancialEvidence: "estimated"
     },
     {
         id: "provider_apis",
         label: "Official provider APIs",
         sourceTypes: ["provider_api"],
-        defaultVerification: "verified"
+        defaultFinancialEvidence: "verified"
     },
     {
         id: "browser_account_ui",
         label: "Browser Account UI",
         sourceTypes: ["browser_account"],
-        defaultVerification: "verified"
+        defaultFinancialEvidence: "verified"
     },
     {
         id: "local_cli_tool_detection",
         label: "Local CLI/tool detection path",
         sourceTypes: ["local_tool_detection"],
-        defaultVerification: "detected_unverified"
+        defaultFinancialEvidence: "detected_unverified"
     },
     {
         id: "mcp_internal_systems",
         label: "MCP and internal systems",
         sourceTypes: ["mcp_tool", "internal_system"],
-        defaultVerification: "verified"
+        defaultFinancialEvidence: "verified"
     }
 ];
 export const supportedSourceTypes = ingestionLanes.flatMap((lane) => lane.sourceTypes);
@@ -195,7 +195,9 @@ export function createLocalFolderSourceRegistry(rootPath, now = new Date()) {
                 scope: "Read-only scan of the explicit --path root. No writes outside .ai-spend-agent. No cloud upload.",
                 lane: "local_files_exports",
                 accessMethod: "file",
-                verification: "verified",
+                boundaryApproval: "approved",
+                validationCoverage: "untested",
+                financialEvidence: "missing",
                 fieldsVerified: ["approved local folder boundary"],
                 fieldsEstimated: [],
                 fieldsMissing: ["provider account billing data"]
@@ -209,14 +211,24 @@ export function createLocalFolderSourceRegistry(rootPath, now = new Date()) {
 }
 export function addApprovedSource(registry, source, now = new Date()) {
     const timestamp = now.toISOString();
+    const canonicalRegistry = normalizeSourceRegistry(registry);
+    if (source.readOnly === false) {
+        throw new Error("Approved source boundaries must remain read-only.");
+    }
     const nextSource = {
-        ...source,
-        readOnly: source.readOnly ?? true,
+        id: source.id,
+        type: source.type,
+        label: source.label,
+        ...(source.path ? { path: source.path } : {}),
+        ...(source.provider ? { provider: source.provider } : {}),
+        readOnly: true,
         approvedAt: timestamp,
         scope: source.scope ?? defaultScopeForSource(source.type),
         lane: source.lane ?? laneForSourceType(source.type),
         accessMethod: source.accessMethod ?? accessMethodForSourceType(source.type),
-        verification: source.verification ?? ingestionLanes.find((lane) => lane.sourceTypes.includes(source.type))?.defaultVerification ?? "estimated",
+        boundaryApproval: source.boundaryApproval ?? "approved",
+        validationCoverage: source.validationCoverage ?? "untested",
+        financialEvidence: source.type === "local_folder" ? "missing" : (source.financialEvidence ?? "missing"),
         fieldsVerified: source.fieldsVerified ?? [],
         fieldsEstimated: source.fieldsEstimated ?? [],
         fieldsMissing: source.fieldsMissing ?? [],
@@ -225,11 +237,11 @@ export function addApprovedSource(registry, source, now = new Date()) {
         tokenStorage: source.tokenStorage,
         authReference: source.authReference
     };
-    const withoutExisting = registry.approvedSources.filter((candidate) => candidate.id !== nextSource.id);
+    const withoutExisting = canonicalRegistry.approvedSources.filter((candidate) => candidate.id !== nextSource.id);
     return {
-        ...registry,
-        ingestionLanes: registry.ingestionLanes ?? ingestionLanes,
-        supportedSourceTypes: registry.supportedSourceTypes ?? supportedSourceTypes,
+        ...canonicalRegistry,
+        ingestionLanes: canonicalRegistry.ingestionLanes ?? ingestionLanes,
+        supportedSourceTypes: canonicalRegistry.supportedSourceTypes ?? supportedSourceTypes,
         approvedSources: [...withoutExisting, nextSource],
         updatedAt: timestamp
     };
@@ -248,7 +260,11 @@ export function createProviderConnectorStub(provider, type = providerCatalog.fin
         scope: defaultScopeForSource(type),
         lane: laneForSourceType(type),
         accessMethod: accessMethodForSourceType(type, catalogEntry),
-        verification: "missing",
+        boundaryApproval: "approved",
+        // Registering a read-only boundary is not evidence that a connector ran.
+        // A successful provider result promotes this axis explicitly.
+        validationCoverage: "untested",
+        financialEvidence: "missing",
         fieldsVerified: catalogEntry?.verifiedFields ?? [],
         fieldsEstimated: [],
         fieldsMissing: catalogEntry?.missingFields ?? ["approved account/API/export source"],
@@ -257,6 +273,157 @@ export function createProviderConnectorStub(provider, type = providerCatalog.fin
         tokenStorage: tokenStorageForConnectorType(type, connectorEntry)
     };
 }
+/**
+ * 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 function normalizeSourceRegistry(value) {
+    if (!isObject(value) || value.version !== 1 || value.localOnly !== true || value.cloudUpload !== false) {
+        throw new Error("Invalid local source registry: expected the canonical local-only registry shape.");
+    }
+    if (!Array.isArray(value.approvedSources) ||
+        !Array.isArray(value.deniedGlobs) ||
+        !Array.isArray(value.ingestionLanes) ||
+        !Array.isArray(value.supportedSourceTypes) ||
+        !isValidIso(value.updatedAt) ||
+        !isStringList(value.deniedGlobs) ||
+        !value.supportedSourceTypes.every(isSourceTypeValue)) {
+        throw new Error("Invalid local source registry: expected valid source, lane, and deny lists.");
+    }
+    const normalizedLanes = value.ingestionLanes.map(normalizeIngestionLane);
+    const normalizedSources = value.approvedSources.map(normalizeApprovedSource);
+    return {
+        version: 1,
+        localOnly: true,
+        cloudUpload: false,
+        approvedSources: normalizedSources,
+        deniedGlobs: [...value.deniedGlobs],
+        ingestionLanes: normalizedLanes,
+        supportedSourceTypes: [...value.supportedSourceTypes],
+        updatedAt: value.updatedAt
+    };
+}
+function normalizeIngestionLane(value) {
+    if (!isObject(value) ||
+        !isIngestionLaneId(value.id) ||
+        !isNonEmptyString(value.label) ||
+        !Array.isArray(value.sourceTypes) ||
+        !value.sourceTypes.every(isSourceTypeValue)) {
+        throw new Error("Invalid local source registry: an ingestion lane has a malformed shape.");
+    }
+    if (value.defaultFinancialEvidence !== undefined && !isFinancialEvidence(value.defaultFinancialEvidence)) {
+        throw new Error("Invalid local source registry: an ingestion lane has invalid financial evidence.");
+    }
+    if (value.defaultVerification !== undefined && !isFinancialEvidence(value.defaultVerification)) {
+        throw new Error("Invalid local source registry: an ingestion lane has an invalid legacy verification value.");
+    }
+    const financialEvidence = isFinancialEvidence(value.defaultFinancialEvidence)
+        ? value.defaultFinancialEvidence
+        : isFinancialEvidence(value.defaultVerification)
+            ? value.defaultVerification
+            : undefined;
+    if (!financialEvidence) {
+        throw new Error("Invalid local source registry: an ingestion lane is missing its financial-evidence default.");
+    }
+    return {
+        id: value.id,
+        label: value.label,
+        sourceTypes: [...value.sourceTypes],
+        defaultFinancialEvidence: financialEvidence
+    };
+}
+function normalizeApprovedSource(value) {
+    if (!isObject(value) ||
+        !isNonEmptyString(value.id) ||
+        !isSourceTypeValue(value.type) ||
+        !isNonEmptyString(value.label) ||
+        value.readOnly !== true ||
+        !isValidIso(value.approvedAt) ||
+        !isNonEmptyString(value.scope) ||
+        !isIngestionLaneId(value.lane) ||
+        !isAccessMethod(value.accessMethod) ||
+        !isStringList(value.fieldsVerified) ||
+        !isStringList(value.fieldsEstimated) ||
+        !isStringList(value.fieldsMissing)) {
+        throw new Error("Invalid local source registry: an approved source has a malformed shape.");
+    }
+    if (value.boundaryApproval !== undefined && value.boundaryApproval !== "approved") {
+        throw new Error("Invalid local source registry: an approved source has an invalid boundary approval.");
+    }
+    if (value.validationCoverage !== undefined && !isValidationCoverage(value.validationCoverage)) {
+        throw new Error("Invalid local source registry: an approved source has an invalid validation coverage.");
+    }
+    if (value.financialEvidence !== undefined && !isFinancialEvidence(value.financialEvidence)) {
+        throw new Error("Invalid local source registry: an approved source has invalid financial evidence.");
+    }
+    if (value.verification !== undefined && !isFinancialEvidence(value.verification)) {
+        throw new Error("Invalid local source registry: an approved source has an invalid legacy verification value.");
+    }
+    const provider = optionalNonEmptyString(value.provider, "provider");
+    const path = optionalNonEmptyString(value.path, "path");
+    const authReference = optionalNonEmptyString(value.authReference, "auth reference");
+    const authMode = optionalEnum(value.authMode, isAuthMode, "auth mode");
+    const tokenStorage = optionalEnum(value.tokenStorage, isTokenStorage, "token storage");
+    if (value.authScopes !== undefined && !isStringList(value.authScopes)) {
+        throw new Error("Invalid local source registry: an approved source has invalid auth scopes.");
+    }
+    const migratedEvidence = isFinancialEvidence(value.financialEvidence)
+        ? value.financialEvidence
+        : isFinancialEvidence(value.verification)
+            ? value.verification
+            : "missing";
+    return {
+        id: value.id,
+        type: value.type,
+        label: value.label,
+        ...(path ? { path } : {}),
+        ...(provider ? { provider } : {}),
+        readOnly: true,
+        approvedAt: value.approvedAt,
+        scope: value.scope,
+        lane: value.lane,
+        accessMethod: value.accessMethod,
+        boundaryApproval: "approved",
+        validationCoverage: isValidationCoverage(value.validationCoverage)
+            ? value.validationCoverage
+            : "untested",
+        financialEvidence: value.type === "local_folder" ? "missing" : migratedEvidence,
+        fieldsVerified: [...value.fieldsVerified],
+        fieldsEstimated: [...value.fieldsEstimated],
+        fieldsMissing: [...value.fieldsMissing],
+        ...(authMode ? { authMode } : {}),
+        ...(value.authScopes ? { authScopes: [...value.authScopes] } : {}),
+        ...(tokenStorage ? { tokenStorage } : {}),
+        ...(authReference ? { authReference } : {})
+    };
+}
+/**
+ * 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 function downgradeUntrustedSourceRegistryClaims(registry) {
+    const canonical = normalizeSourceRegistry(registry);
+    return {
+        ...canonical,
+        approvedSources: canonical.approvedSources.map((source) => ({
+            ...source,
+            validationCoverage: "untested",
+            financialEvidence: "missing",
+            fieldsVerified: source.fieldsVerified.filter((field) => /approved|boundary|read-only|folder/i.test(field)),
+            fieldsMissing: Array.from(new Set([
+                ...source.fieldsMissing,
+                "machine-bound provider validation and financial evidence"
+            ]))
+        }))
+    };
+}
 export function buildMissingSourcePrompts(signals, registry) {
     const providerSignals = new Map();
     for (const signal of signals) {
@@ -267,7 +434,7 @@ export function buildMissingSourcePrompts(signals, registry) {
     }
     const prompts = [];
     for (const [provider, detectedSignals] of Array.from(providerSignals.entries())) {
-        if (hasVerifiedProviderSource(registry, provider)) {
+        if (hasCurrentProviderFinancialEvidence(registry, provider)) {
             continue;
         }
         const catalogEntry = providerCatalog.find((entry) => entry.id === provider);
@@ -276,7 +443,7 @@ export function buildMissingSourcePrompts(signals, registry) {
         prompts.push({
             provider,
             status: "detected_unverified",
-            reason: `${provider} was detected locally, but no verified provider/API/browser/export source is connected.`,
+            reason: `${provider} was detected locally, but no approved provider/API/browser/export boundary has current financial evidence. Connector validation is reported separately.`,
             detectedEvidence: detectedSignals.map((signal) => signal.evidence),
             suggestedConnector: `connect ${provider} --type ${preferredType}`,
             suggestedSourceTypes
@@ -315,17 +482,26 @@ export function slugifySourceId(label) {
         .replace(/^-+|-+$/g, "");
     return slug || "approved-source";
 }
-function hasVerifiedProviderSource(registry, provider) {
+function hasCurrentProviderFinancialEvidence(registry, provider) {
     return registry.approvedSources.some((source) => {
         if (source.provider !== provider) {
             return false;
         }
-        if (source.verification === "verified" && source.type !== "local_tool_detection") {
-            return true;
-        }
-        return source.type === "provider_export" || source.type === "provider_api" || source.type === "browser_account" || source.type === "internal_system";
+        return source.boundaryApproval === "approved" &&
+            source.validationCoverage !== "failed" &&
+            source.financialEvidence !== "missing" &&
+            source.type !== "local_tool_detection";
     });
 }
+function validationCoverageForSource(provider, type) {
+    if (type === "provider_api" && (provider === "openai" || provider === "anthropic"))
+        return "live_verified";
+    if (type === "provider_api" && (provider === "cursor" || provider === "github-copilot" || provider === "copilot"))
+        return "fixture_verified";
+    if (provider === "local-agent-logs" && type === "local_tool_detection")
+        return "live_verified";
+    return "untested";
+}
 function authModeForConnectorType(type, connectorEntry) {
     if (type === "browser_account")
         return "browser_session";
@@ -377,4 +553,57 @@ function accessMethodForSourceType(type, catalogEntry) {
         return "internal";
     return "file";
 }
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isValidIso(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function isSourceTypeValue(value) {
+    return supportedSourceTypes.includes(value);
+}
+function isIngestionLaneId(value) {
+    return value === "local_files_exports" ||
+        value === "provider_apis" ||
+        value === "browser_account_ui" ||
+        value === "local_cli_tool_detection" ||
+        value === "mcp_internal_systems";
+}
+function isAccessMethod(value) {
+    return value === "file" || value === "api" || value === "browser" || value === "cli_detection" || value === "mcp" || value === "internal" || value === "manual";
+}
+function isFinancialEvidence(value) {
+    return value === "verified" || value === "estimated" || value === "detected_unverified" || value === "missing";
+}
+function isValidationCoverage(value) {
+    return value === "live_verified" || value === "fixture_verified" || value === "untested" || value === "failed";
+}
+function isAuthMode(value) {
+    return value === "oauth" || value === "api_token_ref" || value === "browser_session" || value === "mcp_auth" || value === "manual_export" || value === "none";
+}
+function isTokenStorage(value) {
+    return value === "local_reference_only" || value === "keychain_reference" || value === "none";
+}
+function optionalNonEmptyString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!isNonEmptyString(value)) {
+        throw new Error(`Invalid local source registry: an approved source has an invalid ${label}.`);
+    }
+    return value;
+}
+function optionalEnum(value, predicate, label) {
+    if (value === undefined)
+        return undefined;
+    if (!predicate(value)) {
+        throw new Error(`Invalid local source registry: an approved source has an invalid ${label}.`);
+    }
+    return value;
+}
 //# sourceMappingURL=sourceRegistry.js.map

package/dist/sourceStatus.d.ts

@@ -0,0 +1,65 @@
+import type { CostConfidence, UsageRecord } from "./schema.js";
+/**
+ * How thoroughly an ingestion path itself has been exercised.
+ *
+ * This is deliberately separate from financial evidence quality. A connector
+ * can be live-verified while a particular record is still only an estimate.
+ */
+export declare const sourceValidationCoverageValues: readonly ["live_verified", "fixture_verified", "untested", "failed"];
+export type SourceValidationCoverage = typeof sourceValidationCoverageValues[number];
+/** The existing aibill financial-evidence vocabulary, named for this contract. */
+export type FinancialEvidenceStatus = CostConfidence;
+export declare const sourceFreshnessStatusValues: readonly ["fresh", "stale", "not_checked"];
+export type SourceFreshnessStatus = typeof sourceFreshnessStatusValues[number];
+export type SourceStatusId = "claude-code" | "codex" | "openai" | "anthropic" | "cursor" | "github-copilot";
+export type SourceStatusDefinition = {
+    id: SourceStatusId;
+    label: string;
+    validationCoverage: SourceValidationCoverage;
+    validationNote: string;
+    staleAfterHours: number;
+};
+export type SourceStatusObservation = {
+    id: SourceStatusId;
+    financialEvidence: FinancialEvidenceStatus;
+    financialEvidenceNote: string;
+    /** When this source was last read or synced, even if it returned no records. */
+    checkedAt?: string;
+    /** Timestamp of the newest evidence row, which may precede the sync time. */
+    latestEvidenceAt?: string;
+    /** A sanitized error from the latest recorded attempt, if one exists. */
+    lastError?: string;
+    /** Runtime failures may override the shipped validation baseline. */
+    validationCoverage?: SourceValidationCoverage;
+};
+export type SourceStatusFreshness = {
+    status: SourceFreshnessStatus;
+    checkedAt?: string;
+    latestEvidenceAt?: string;
+    staleAfterHours: number;
+};
+export type SourceStatus = {
+    id: SourceStatusId;
+    label: string;
+    validationCoverage: SourceValidationCoverage;
+    validationNote: string;
+    financialEvidence: FinancialEvidenceStatus;
+    financialEvidenceNote: string;
+    freshness: SourceStatusFreshness;
+    lastError?: string;
+};
+/**
+ * Shipped validation matrix. Keep these claims proof-conservative: a live
+ * authentication check is not the same as a non-empty end-to-end billing
+ * reconciliation.
+ */
+export declare const sourceStatusDefinitions: readonly SourceStatusDefinition[];
+export declare function buildSourceStatuses(observations?: readonly SourceStatusObservation[], now?: Date): SourceStatus[];
+/**
+ * Reduce one source's current rows to the evidence label used for its headline.
+ * Verified billed cost wins; otherwise estimates win over an unpriced signal.
+ */
+export declare function financialEvidenceForRecords(records: readonly UsageRecord[]): FinancialEvidenceStatus;
+/** Stable, plain-text formatter shared by terminal surfaces. */
+export declare function formatSourceStatuses(statuses: readonly SourceStatus[]): string;
+//# sourceMappingURL=sourceStatus.d.ts.map

package/dist/sourceStatus.js

@@ -0,0 +1,147 @@
+/**
+ * How thoroughly an ingestion path itself has been exercised.
+ *
+ * This is deliberately separate from financial evidence quality. A connector
+ * can be live-verified while a particular record is still only an estimate.
+ */
+export const sourceValidationCoverageValues = [
+    "live_verified",
+    "fixture_verified",
+    "untested",
+    "failed"
+];
+export const sourceFreshnessStatusValues = ["fresh", "stale", "not_checked"];
+/**
+ * Shipped validation matrix. Keep these claims proof-conservative: a live
+ * authentication check is not the same as a non-empty end-to-end billing
+ * reconciliation.
+ */
+export const sourceStatusDefinitions = [
+    {
+        id: "claude-code",
+        label: "Claude Code local logs",
+        validationCoverage: "live_verified",
+        validationNote: "Local transcript parsing is exercised against live logs; dollar values remain API-rate estimates.",
+        staleAfterHours: 72
+    },
+    {
+        id: "codex",
+        label: "Codex local logs",
+        validationCoverage: "live_verified",
+        validationNote: "Local parsing was replayed against live logs; total-only token shapes and unknown aliases remain missing rather than becoming estimated $0.",
+        staleAfterHours: 72
+    },
+    {
+        id: "openai",
+        label: "OpenAI Costs and Usage API",
+        validationCoverage: "live_verified",
+        validationNote: "Product connector QA exercised non-empty Admin cost and usage API paths; the tested Costs total reconciled to invoiced API credits less the provider-UI balance with $0.00 variance. This does not reconcile the current user's account; final invoices, tax, discounts, and later adjustments remain separate.",
+        staleAfterHours: 48
+    },
+    {
+        id: "anthropic",
+        label: "Anthropic Cost Report and Claude Code Analytics",
+        validationCoverage: "live_verified",
+        validationNote: "Admin cost and Claude Code usage paths are exercised with non-empty live records.",
+        staleAfterHours: 48
+    },
+    {
+        id: "cursor",
+        label: "Cursor Admin API",
+        validationCoverage: "fixture_verified",
+        validationNote: "Canonical teamMemberSpend envelopes, totalPages pagination, completeness failures, and malformed responses pass recorded fixtures; live account QA is pending.",
+        staleAfterHours: 48
+    },
+    {
+        id: "github-copilot",
+        label: "GitHub Copilot organization APIs",
+        validationCoverage: "fixture_verified",
+        validationNote: "The 2026-03-10 signed-NDJSON metrics workflow, seat pagination, per-seat plan types, and failure paths pass recorded fixtures; live account QA is pending.",
+        staleAfterHours: 48
+    }
+];
+export function buildSourceStatuses(observations = [], now = new Date()) {
+    const byId = new Map(observations.map((observation) => [observation.id, observation]));
+    return sourceStatusDefinitions.map((definition) => {
+        const observation = byId.get(definition.id);
+        return {
+            id: definition.id,
+            label: definition.label,
+            validationCoverage: observation?.validationCoverage ?? definition.validationCoverage,
+            validationNote: definition.validationNote,
+            financialEvidence: observation?.financialEvidence ?? "missing",
+            financialEvidenceNote: observation?.financialEvidenceNote ?? "No current financial evidence was observed on this machine.",
+            freshness: sourceFreshness(definition, observation, now),
+            ...(observation?.lastError ? { lastError: observation.lastError } : {})
+        };
+    });
+}
+/**
+ * Reduce one source's current rows to the evidence label used for its headline.
+ * Verified billed cost wins; otherwise estimates win over an unpriced signal.
+ */
+export function financialEvidenceForRecords(records) {
+    if (records.some((record) => record.costConfidence === "verified" && typeof record.amountUsd === "number")) {
+        return "verified";
+    }
+    if (records.some((record) => record.costConfidence === "estimated" && typeof record.amountUsd === "number")) {
+        return "estimated";
+    }
+    if (records.some((record) => record.costConfidence === "detected_unverified")) {
+        return "detected_unverified";
+    }
+    return "missing";
+}
+/** Stable, plain-text formatter shared by terminal surfaces. */
+export function formatSourceStatuses(statuses) {
+    return statuses.map((status) => {
+        const freshness = formatFreshness(status.freshness);
+        return [
+            `${status.label} (${status.id})`,
+            `  validation coverage: ${status.validationCoverage}`,
+            `  financial evidence: ${status.financialEvidence}`,
+            `  freshness: ${freshness}`,
+            `  last error: ${status.lastError ? singleLineStatusText(status.lastError) : "none recorded"}`,
+            `  validation proof: ${status.validationNote}`,
+            `  evidence note: ${status.financialEvidenceNote}`
+        ].join("\n");
+    }).join("\n\n");
+}
+function sourceFreshness(definition, observation, now) {
+    const checkedAt = validIso(observation?.checkedAt);
+    const latestEvidenceAt = validIso(observation?.latestEvidenceAt);
+    if (!checkedAt) {
+        return {
+            status: "not_checked",
+            staleAfterHours: definition.staleAfterHours,
+            ...(latestEvidenceAt ? { latestEvidenceAt } : {})
+        };
+    }
+    const ageHours = (now.getTime() - Date.parse(checkedAt)) / 3_600_000;
+    return {
+        status: ageHours > definition.staleAfterHours ? "stale" : "fresh",
+        checkedAt,
+        ...(latestEvidenceAt ? { latestEvidenceAt } : {}),
+        staleAfterHours: definition.staleAfterHours
+    };
+}
+function validIso(value) {
+    return value && Number.isFinite(Date.parse(value)) ? value : undefined;
+}
+function formatFreshness(freshness) {
+    if (freshness.status === "not_checked")
+        return "not_checked (no local check recorded)";
+    const latest = freshness.latestEvidenceAt
+        ? `; latest evidence ${freshness.latestEvidenceAt}`
+        : "; no evidence rows observed";
+    return `${freshness.status} (checked ${freshness.checkedAt}${latest}; stale after ${freshness.staleAfterHours}h)`;
+}
+function singleLineStatusText(value) {
+    return value
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 500) || "invalid empty error";
+}
+//# sourceMappingURL=sourceStatus.js.map

package/dist/stateTrust.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A connected-provider spend file lives inside a repository and is therefore
+ * untrusted by default. A successful provider sync writes this small receipt
+ * outside the repository, binding the exact spend.json bytes to this machine
+ * and canonical project root. Successful syncs also bind sources.json so a
+ * clone cannot forge validation or financial-evidence axes. Merely cloning
+ * committed state cannot create the external receipt.
+ */
+export type ConnectedSpendTrustResult = {
+    trusted: true;
+    trustedAt: string;
+    spendSha256: string;
+    sourceRegistrySha256?: string;
+} | {
+    trusted: false;
+    reason: "missing" | "mismatch" | "invalid";
+    message: string;
+};
+export type ConnectedSpendTrustOptions = {
+    /** Test/embedding override. Production callers normally use user state. */
+    trustDirectory?: string;
+    /** Exact sources.json bytes written by the same successful provider sync. */
+    sourceRegistryContents?: string;
+};
+export declare function writeConnectedSpendTrustReceipt(rootPath: string, exactSpendContents: string, options?: ConnectedSpendTrustOptions): Promise<void>;
+export declare function verifyConnectedSpendTrustReceipt(rootPath: string, exactSpendContents: string, options?: ConnectedSpendTrustOptions): Promise<ConnectedSpendTrustResult>;
+/**
+ * Provider/source truth axes are trusted only when the same external receipt
+ * binds both the connected spend state and the exact persisted sources.json.
+ * A repository clone or edit can therefore register a boundary, but cannot
+ * self-assert live validation or verified financial evidence.
+ */
+export declare function verifyConnectedSourceRegistryTrustReceipt(rootPath: string, exactSpendContents: string, exactSourceRegistryContents: string, options?: ConnectedSpendTrustOptions): Promise<ConnectedSpendTrustResult>;
+/** Remove stale trust whenever connected state is reset or replaced locally. */
+export declare function invalidateConnectedSpendTrustReceipt(rootPath: string, options?: ConnectedSpendTrustOptions): Promise<void>;
+export declare function connectedTrustFailureMessage(reason: string): string;
+//# sourceMappingURL=stateTrust.d.ts.map