@xerg/schemas

Versioned TypeScript wire types for Xerg audit payloads, daily rollups, findings, comparisons, and the hosted Action Center recommendation contract.

What it is

@xerg/schemas defines the public JSON contract shared between the Xerg CLI, the local audit engine, and any service that consumes pushed audit summaries.

It is intentionally small and stable:

• TypeScript-first types for Xerg wire payloads
• Daily spend and waste rollups for hosted dashboards and ingestion pipelines
• Content-free detector coverage and source-stability accounting for honest waste claims
• A runtime AUDIT_PUSH_PAYLOAD_VERSION constant for compatibility checks
• A versioned generic XergEventPayload ingest contract with request, cost-component, state, tool, and cache fingerprints
• The ranked recommendation contract used by Xerg Cloud, Ask Xerg, and hosted MCP
• Additive browser-pairing and authenticated workspace-entitlement contracts, including optional exact-organization approval binding
• The versioned, content-free hosted client-context header contract and bounded host/invocation enums
• A dependency-free runtime validator and published JSON Schema for untrusted generic-ingest payloads
• A stable MIT-licensed contract package even though the main Xerg source repository is private

What it is not

Use validateXergEventPayload(value) for dependency-free runtime validation, or import @xerg/schemas/xerg-event-payload-v4.schema.json with a JSON Schema validator. The same schema is published at https://xerg.ai/schemas/xerg-event-payload-v4.schema.json.

Install

npm install @xerg/schemas

Example

import {
  AUDIT_PUSH_PAYLOAD_VERSION,
  type AuditPushPayload,
} from '@xerg/schemas';

export function acceptAuditPayload(payload: AuditPushPayload) {
  if (payload.version !== AUDIT_PUSH_PAYLOAD_VERSION) {
    throw new Error(`Unsupported payload version: ${payload.version}`);
  }

  return payload.summary.spendByDay;
}

Compatibility contract

AuditPushPayload.version is the top-level wire version.

• Additive fields that older consumers can safely ignore should usually keep the same version.
• Breaking changes to existing field names, meanings, or required structure should ship behind a new payload version.
• Producers and consumers should reject payloads with a newer unsupported version instead of guessing.

Current version:

import { AUDIT_PUSH_PAYLOAD_VERSION } from '@xerg/schemas';

AUDIT_PUSH_PAYLOAD_VERSION; // 7

Version 2 added the richer XergRecommendation contract. Version 3 added optional token-economics and outcomes rollups, provenance, pricing coverage, and meta.dedupKey. Version 4 added the runtime summary.auditKind discriminant. Version 5 added shared economic/analysis identity, content-free detector eligibility, and source stability. Version 6 separates three evidence-strict monetary findings from seven neutral signals, replaces current costImpactUsd with affected/avoidable amounts plus evidence and impact bases, and reports coverage for each current detector. Version 7 adds daily priced and unpriced call counts for coverage transparency without changing spend or metering semantics. Xerg 0.27.0 additively emits optional WireSignal.scopeLabel within Push v7; older v7/v6 payloads remain valid without it. Runtime wire versions 6 and 7 are accepted.

V5 history is stored unchanged and displayed as a legacy detection method. V6 recurrence includes detectorVersion; separately stored analyses can share an economicAuditId without being discarded. V6 and v7 meter identically from daily known spend.

XergEventPayload is a separate generic-ingest contract. Its current emitted version is 4, while the validator accepts versions 1, 2, 3, and 4. Version 3 added stable request and cost-component IDs plus content-free input, result, state, and cache-entry fingerprints. Version 4 coordinates with Push v7, whose daily priced and unpriced call counts provide coverage transparency without changing metered amounts. Older payloads remain readable but do not gain evidence-strict coverage they did not originally contain. Raw prompts, tool arguments, results, and cache content are forbidden from these fields.

Exports

Primary exports include:

• AuditPushPayload
• RuntimeWireSummaryV5, RuntimeWireSummaryV6, and RuntimeWireSummaryV7
• RuntimeDetectionCoverage, DetectorCoverage, and SourceStability
• DailySpendBreakdown
• DailyWasteBreakdown
• WireFinding, LegacyWireFinding, and WireSignal
• WireComparison
• XergRecommendation
• XergRecommendationPriorityBucket
• XergRecommendationSurface
• XergRecommendationCategory
• AUDIT_PUSH_PAYLOAD_VERSION
• XergEventPayload, XergEvent, XERG_EVENT_PAYLOAD_VERSION, and ACCEPTED_XERG_EVENT_PAYLOAD_VERSIONS
• ACTIVE_FINDING_KINDS, SIGNAL_KINDS, and LEGACY_FINDING_KINDS with their corresponding types
• SIGNAL_KIND_META and getSignalMetricRows for ordered, bounded signal evidence presentation
• CreateCliPairingRequest, CliPairingPollResponse, and CliPairingWorkspaceBinding
• CLIENT_CONTEXT_VERSION, the XERG_*_HEADER constants, ExecutionContext, AgentHostHint, InvocationPath, and their type guards
• WorkspaceEntitlements, including the authenticated Clerk organizationId
• FINDING_KIND_META (and FindingKindMeta) — per-kind display label, recommendation category, and implementation surface
• isFindingKind, getFindingKindLabel, getFindingKindCategory, getFindingKindSurface — runtime helpers with safe fallbacks for unknown wire kinds (raw kind / 'other')
• COVERAGE_REASON_LABELS — shared plain-language explanations for bounded detector-coverage reason codes

Use cases

• 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