@xerg/schemas 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @xerg/schemas
 
-Versioned TypeScript wire types for Xerg audit payloads, daily rollups, findings, comparisons, and recommendations.
+Versioned TypeScript wire types for Xerg audit payloads, daily rollups, findings, comparisons, and the hosted Action Center recommendation contract.
 
 ## What it is
 
@@ -11,6 +11,7 @@ It is intentionally small and stable:
 - TypeScript-first types for Xerg wire payloads
 - Daily spend and waste rollups for hosted dashboards and ingestion pipelines
 - A runtime `AUDIT_PUSH_PAYLOAD_VERSION` constant for compatibility checks
+- The ranked recommendation contract used by Xerg Cloud, Ask Xerg, and hosted MCP
 - A dependency-light package surface for backends, ingestion services, and internal tooling
 
 ## What it is not
@@ -53,10 +54,10 @@ Current version:
 ```ts
 import { AUDIT_PUSH_PAYLOAD_VERSION } from '@xerg/schemas';
 
-AUDIT_PUSH_PAYLOAD_VERSION; // 1
+AUDIT_PUSH_PAYLOAD_VERSION; // 2
 ```
 
-Daily series such as `spendByDay` and `wasteByDay` were added without bumping the payload version because they are additive fields that older consumers can ignore safely.
+Version `2` adds the richer `XergRecommendation` contract to the pushed payload. Recommendations are now first-class wire data rather than a local-only CLI add-on.
 
 ## Exports
 
@@ -68,6 +69,9 @@ Primary exports include:
 - `WireFinding`
 - `WireComparison`
 - `XergRecommendation`
+- `XergRecommendationPriorityBucket`
+- `XergRecommendationSurface`
+- `XergRecommendationCategory`
 - `AUDIT_PUSH_PAYLOAD_VERSION`
 
 ## Use cases
@@ -75,3 +79,4 @@ Primary exports include:
 - Share a single payload contract between the Xerg CLI and backend services
 - Type audit ingestion pipelines without copying interface definitions
 - Gate processing logic on an explicit payload version
+- Keep hosted action queues, MCP tools, and dashboard recommendation cards aligned with the CLI

package/dist/index.d.ts

@@ -24,7 +24,37 @@ interface WireFinding {
     costImpactUsd: number;
 }
 
-declare const AUDIT_PUSH_PAYLOAD_VERSION: 1;
+type XergRecommendationPriorityBucket = 'fix_now' | 'test_next' | 'watch';
+type XergRecommendationSurface = 'retry_policy' | 'loop_guard' | 'model_routing' | 'scheduler' | 'prompt_builder' | 'user_behavior' | 'other';
+type XergRecommendationCategory = 'structural_efficiency' | 'model_fit' | 'context_hygiene' | 'cadence_activity' | 'other';
+type XergRecommendationSeverity = 'high' | 'medium' | 'low';
+type XergRecommendationConfidence = 'high' | 'medium' | 'low';
+type XergRecommendationEffort = 'low' | 'medium' | 'high';
+type XergRecommendationScope = 'workspace' | 'source' | 'workflow';
+interface XergRecommendation {
+    id: string;
+    findingId: string;
+    kind: string;
+    title: string;
+    summary: string;
+    priorityBucket: XergRecommendationPriorityBucket;
+    recommendedOrder: number;
+    implementationSurface: XergRecommendationSurface;
+    category: XergRecommendationCategory;
+    severity: XergRecommendationSeverity;
+    estimatedSavingsUsd: number;
+    estimatedSavingsPct: number;
+    confidence: XergRecommendationConfidence;
+    effort: XergRecommendationEffort;
+    scope: XergRecommendationScope;
+    scopeId: string;
+    scopeLabel: string;
+    whereToChange: string;
+    validationPlan: string;
+    actions: string[];
+}
+
+declare const AUDIT_PUSH_PAYLOAD_VERSION: 2;
 type AuditPushPayloadVersion = typeof AUDIT_PUSH_PAYLOAD_VERSION;
 type PushEnvironment = 'local' | 'remote' | 'railway';
 interface FindingTaxonomyBucket {
@@ -72,6 +102,7 @@ interface AuditPushPayload {
         spendByDay: DailySpendBreakdown[];
         wasteByDay: DailyWasteBreakdown[];
         findings: WireFinding[];
+        recommendations: XergRecommendation[];
         notes: string[];
         comparison?: WireComparison | null;
     };
@@ -84,16 +115,4 @@ interface AuditPushPayload {
     };
 }
 
-interface XergRecommendation {
-    id: string;
-    findingId: string;
-    kind: string;
-    title: string;
-    description: string;
-    estimatedSavingsUsd: number;
-    confidence: 'high' | 'medium' | 'low';
-    actionType: 'model-switch' | 'cache-config' | 'prompt-trim' | 'dedup' | 'other';
-    suggestedChange?: Record<string, unknown>;
-}
-
-export { AUDIT_PUSH_PAYLOAD_VERSION, type AuditPushPayload, type AuditPushPayloadVersion, type DailySpendBreakdown, type DailyWasteBreakdown, type FindingTaxonomyBucket, type PushEnvironment, type SpendBreakdown, type WireComparison, type WireFinding, type WireFindingScope, type XergRecommendation };
+export { AUDIT_PUSH_PAYLOAD_VERSION, type AuditPushPayload, type AuditPushPayloadVersion, type DailySpendBreakdown, type DailyWasteBreakdown, type FindingTaxonomyBucket, type PushEnvironment, type SpendBreakdown, type WireComparison, type WireFinding, type WireFindingScope, type XergRecommendation, type XergRecommendationCategory, type XergRecommendationConfidence, type XergRecommendationEffort, type XergRecommendationPriorityBucket, type XergRecommendationScope, type XergRecommendationSeverity, type XergRecommendationSurface };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/audit-push-payload.ts
-var AUDIT_PUSH_PAYLOAD_VERSION = 1;
+var AUDIT_PUSH_PAYLOAD_VERSION = 2;
 export {
   AUDIT_PUSH_PAYLOAD_VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xerg/schemas",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Versioned TypeScript wire types for Xerg audit payloads, daily rollups, findings, comparisons, and recommendations.",
   "keywords": [
     "xerg",