@agent-finops/core 0.7.3 → 0.8.0

package/dist/sourceStatus.js

@@ -1,4 +1,5 @@
 import { localAgentFormatDescriptors } from "./localAgentFormats/registry.js";
+import { generatedProviderContractStates } from "./providerContractStates.generated.js";
 /**
  * How thoroughly an ingestion path itself has been exercised.
  *
@@ -12,6 +13,7 @@ export const sourceValidationCoverageValues = [
     "failed"
 ];
 export const sourceFreshnessStatusValues = ["fresh", "stale", "not_checked"];
+export const providerContractStateValues = ["current", "stale_contract"];
 /**
  * Shipped validation matrix. Keep these claims proof-conservative: a live
  * authentication check is not the same as a non-empty end-to-end billing
@@ -23,48 +25,67 @@ export const sourceStatusDefinitions = [
         label: `${descriptor.label} local logs`,
         validationCoverage: descriptor.confidenceDefaults.validationCoverage,
         validationNote: descriptor.validationNote,
-        staleAfterHours: 72
+        staleAfterHours: 72,
+        ...(descriptor.id === "gemini-cli"
+            ? { contractState: generatedProviderContractStates["gemini-cli"] }
+            : {})
     })),
     {
         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
+        staleAfterHours: 48,
+        contractState: generatedProviderContractStates.openai
     },
     {
         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
+        staleAfterHours: 48,
+        contractState: generatedProviderContractStates.anthropic
     },
     {
         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
+        staleAfterHours: 48,
+        contractState: generatedProviderContractStates.cursor
     },
     {
         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
+        staleAfterHours: 48,
+        contractState: generatedProviderContractStates["github-copilot"]
     }
 ];
-export function buildSourceStatuses(observations = [], now = new Date()) {
+export function buildSourceStatuses(observations = [], now = new Date(), definitions = sourceStatusDefinitions) {
     const byId = new Map(observations.map((observation) => [observation.id, observation]));
-    return sourceStatusDefinitions.map((definition) => {
+    return definitions.map((definition) => {
         const observation = byId.get(definition.id);
+        const observedContractState = observation?.contractState;
+        const contractState = definition.contractState === "stale_contract" || observedContractState === "stale_contract"
+            ? "stale_contract"
+            : definition.contractState;
+        const observedFinancialEvidence = observation?.financialEvidence ?? "missing";
+        const financialEvidence = contractState === "stale_contract" && observedFinancialEvidence === "verified"
+            ? "missing"
+            : observedFinancialEvidence;
+        const financialEvidenceNote = contractState === "stale_contract" && observedFinancialEvidence === "verified"
+            ? "Provider contract drift is unresolved; the verified financial headline is withheld pending human review."
+            : observation?.financialEvidenceNote ?? "No current financial evidence was observed on this machine.";
         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.",
+            financialEvidence,
+            financialEvidenceNote,
+            ...(contractState ? { contractState } : {}),
             freshness: sourceFreshness(definition, observation, now),
             ...(observation?.lastError ? { lastError: observation.lastError } : {})
         };
@@ -86,6 +107,79 @@ export function financialEvidenceForRecords(records) {
     }
     return "missing";
 }
+/**
+ * Apply the reviewed provider-contract gate before any connected financial
+ * calculation. Local transcript evidence is unchanged. When a provider's
+ * financial semantics are stale, its priced rows remain present for audit and
+ * attribution but cannot carry a dollar amount or proof-level confidence.
+ */
+export function applyProviderContractGate(records, definitions = sourceStatusDefinitions) {
+    const contractStates = new Map(definitions
+        .filter((definition) => definition.contractState !== undefined)
+        .map((definition) => [definition.id, definition.contractState]));
+    return records.map((record) => {
+        if (record.providerCostType === "local_agent_logs")
+            return record;
+        const sourceId = providerStatusIdForRecord(record);
+        if (!sourceId || contractStates.get(sourceId) !== "stale_contract")
+            return record;
+        return {
+            ...record,
+            source: { ...record.source, confidence: "missing" },
+            amountUsd: null,
+            costConfidence: "missing"
+        };
+    });
+}
+/**
+ * Project persisted source metadata through the same fail-closed contract
+ * gate as records. This is read-time only: the signed local receipt remains
+ * byte-exact, while an upgraded release cannot repeat an obsolete verified
+ * claim from an older sources.json.
+ */
+export function applyProviderContractGateToSourceRegistry(registry, definitions = sourceStatusDefinitions) {
+    const states = new Map(definitions
+        .filter((definition) => definition.contractState !== undefined)
+        .map((definition) => [definition.id, definition.contractState]));
+    return {
+        ...registry,
+        approvedSources: registry.approvedSources.map((source) => {
+            if (source.type !== "provider_api")
+                return source;
+            const statusId = providerStatusIdForProvider(source.provider);
+            if (!statusId || states.get(statusId) !== "stale_contract")
+                return source;
+            const baseScope = source.scope.split(" Last successful pull produced ")[0]?.trim() || source.scope;
+            return {
+                ...source,
+                financialEvidence: "missing",
+                fieldsMissing: Array.from(new Set([
+                    ...source.fieldsMissing,
+                    "provider financial headline (contract review required)"
+                ])),
+                scope: `${baseScope} Provider contract drift is unresolved; prior financial evidence and headline are withheld.`
+            };
+        })
+    };
+}
+function providerStatusIdForRecord(record) {
+    if (record.source.provider === "google" && record.agentId === "gemini-cli")
+        return "gemini-cli";
+    return providerStatusIdForProvider(record.source.provider);
+}
+function providerStatusIdForProvider(provider) {
+    if (provider === "openai")
+        return "openai";
+    if (provider === "anthropic")
+        return "anthropic";
+    if (provider === "cursor")
+        return "cursor";
+    if (provider === "github" || provider === "github-copilot" || provider === "copilot")
+        return "github-copilot";
+    if (provider === "google" || provider === "gemini")
+        return "gemini-cli";
+    return undefined;
+}
 /** Stable, plain-text formatter shared by terminal surfaces. */
 export function formatSourceStatuses(statuses) {
     return statuses.map((status) => {
@@ -93,6 +187,7 @@ export function formatSourceStatuses(statuses) {
         return [
             `${status.label} (${status.id})`,
             `  validation coverage: ${status.validationCoverage}`,
+            ...(status.contractState ? [`  provider contract: ${status.contractState}`] : []),
             `  financial evidence: ${status.financialEvidence}`,
             `  freshness: ${freshness}`,
             `  last error: ${status.lastError ? singleLineStatusText(status.lastError) : "none recorded"}`,

package/dist/stateTrust.js

@@ -39,7 +39,7 @@ export async function verifyConnectedSpendTrustReceipt(rootPath, exactSpendConte
         if (isNodeError(error, "ENOENT")) {
             return missingTrust();
         }
-        return invalidTrust(error instanceof Error ? error.message : String(error));
+        return invalidTrust("the external trust directory failed safety validation");
     }
     let rawReceipt;
     try {
@@ -48,7 +48,7 @@ export async function verifyConnectedSpendTrustReceipt(rootPath, exactSpendConte
     catch (error) {
         if (isNodeError(error, "ENOENT"))
             return missingTrust();
-        return invalidTrust(error instanceof Error ? error.message : String(error));
+        return invalidTrust("the external provider-sync receipt failed safety validation");
     }
     let receipt;
     try {

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc -b",
     "typecheck": "tsc -b --pretty false",