@vorion/car-client

TypeScript client SDK for the Categorical Agentic Registry (CAR) -- the unique agent identity, registration, and provenance system within the Vorion platform.

What is CAR?

The Categorical Agentic Registry (CAR) is Vorion's identity layer for AI agents. Every agent in the Vorion ecosystem receives a CAR ID -- a unique, cryptographically-anchored identity that tracks the agent's identity, provenance, capability declarations, and role permissions across its entire lifecycle. Trust scores are not part of the CAR identity; they are dynamic behavioral metrics computed at runtime by a separate trust engine (ATSF/Cognigate) that references agents by their CAR ID.

CAR is the identity registry that the Phase 6 Trust Engine (ATSF/Cognigate) relies on. The trust engine implements five architectural decisions (Q1-Q5) governing how agents earn trust, assume roles, inherit presets, and maintain auditable provenance -- all keyed to CAR IDs. The trust model is governed by BASIS (Baseline Authority for Safe & Interoperable Systems), an independent standards body that defines the canonical trust tiers, role matrices, and compliance ceilings. In short: CAR answers "WHO is this agent?" while ATSF/Cognigate answers "HOW MUCH do we trust this agent?"

This SDK (@vorion/car-client) provides a type-safe TypeScript client for programmatic access to the CAR identity APIs -- registering agents, tracking provenance, managing the full agent identity lifecycle, and evaluating role permissions. It also re-exports convenience wrappers for trust engine operations (ceiling checks, gaming alerts) that reference CAR-registered agents.

Installation

npm install @vorion/car-client

Quick Start

import { createCARClient } from '@vorion/car-client'

// Create a client connected to the CAR API
const client = createCARClient({
  baseUrl: 'https://api.agentanchorai.com',
  apiKey: process.env.CAR_API_KEY,
})

// Get dashboard statistics
const { stats } = await client.getStats()
console.log(`${stats.contextStats.agents} agents registered`)

// Evaluate whether an agent can assume a role
const result = await client.evaluateRoleGate({
  agentId: 'agent-123',
  requestedRole: 'R_L3',
  currentTier: 'T3',
})

if (result.evaluation.finalDecision === 'ALLOW') {
  // Agent is authorized -- proceed with operation
}

Features

CAR Identity Features

| Feature | Description | |---------|-------------| | Hierarchical Context (Q2) | 4-tier immutable context (Deployment > Organization > Agent > Operation) | | Role Gates (Q3) | 3-layer evaluation (Kernel matrix > Policy rules > BASIS override) | | Federated Presets (Q4) | CAR > Vorion > Axiom derivation chains with lineage verification | | Provenance (Q5) | Immutable origin tracking with creation type classification |

Trust Engine Features (via ATSF/Cognigate, accessible through this SDK)

| Feature | Description | |---------|-------------| | Ceiling Enforcement (Q1) | Dual-layer trust ceilings with regulatory compliance (EU AI Act, NIST, ISO 42001) | | Gaming Detection | Trust score manipulation detection and alerting |

Note: The trust engine features above are provided by ATSF/Cognigate, not by CAR itself. This SDK exposes them as convenience wrappers since they operate on CAR-registered agents.

Usage Examples

Registering Agent Provenance (CAR ID)

Every agent in CAR has immutable provenance. Register a new agent identity or track derivation from existing agents:

import { createCARClient } from '@vorion/car-client'

const client = createCARClient({
  baseUrl: 'https://api.agentanchorai.com',
  apiKey: process.env.CAR_API_KEY,
})

// Register a fresh agent -- no trust modifier applied
const fresh = await client.createProvenance({
  agentId: 'agent-alpha-001',
  creationType: 'FRESH',
  createdBy: 'system',
})

// Clone from an existing agent -- applies -50 trust modifier
const clone = await client.createProvenance({
  agentId: 'agent-alpha-002',
  creationType: 'CLONED',
  parentAgentId: 'agent-alpha-001',
  createdBy: '[email protected]',
})

// Evolve an agent -- applies +100 trust modifier
const evolved = await client.createProvenance({
  agentId: 'agent-beta-001',
  creationType: 'EVOLVED',
  parentAgentId: 'agent-alpha-001',
  createdBy: 'training-pipeline',
})

Looking Up CAR IDs and Agent Identity

Query provenance records to look up any agent's identity, lineage, and creation history:

// Get provenance for a specific agent
const { records, lineage } = await client.getProvenance('agent-alpha-001')
console.log(`Agent created via: ${records[0].creationType}`)
console.log(`Trust modifier: ${records[0].trustModifier}`)

// Lineage shows the full derivation chain
if (lineage) {
  lineage.forEach((ancestor) => {
    console.log(`${ancestor.agentId} (${ancestor.creationType})`)
  })
}

Evaluating Role Gates (Q3)

The role gate system uses a 3-layer evaluation to decide whether an agent can assume a given role:

const result = await client.evaluateRoleGate({
  agentId: 'agent-123',
  requestedRole: 'R_L3',      // Orchestrator
  currentTier: 'T3',          // Monitored
  currentScore: 550,
  attestations: ['security-audit'],
})

// Inspect each layer
console.log(result.layers.kernel.allowed)      // Kernel matrix lookup
console.log(result.layers.policy.result)       // Policy rule evaluation
console.log(result.layers.basis.overrideUsed)  // BASIS override applied?

if (result.evaluation.finalDecision === 'ALLOW') {
  console.log('Agent authorized for Orchestrator role')
} else if (result.evaluation.finalDecision === 'ESCALATE') {
  console.log('Requires manual approval')
} else {
  console.log('Denied:', result.evaluation.decisionReason)
}

Checking Trust Ceilings (Q1) -- Trust Engine Feature

Trust ceilings are enforced by the trust engine (ATSF/Cognigate), not by CAR itself. This SDK provides convenience access to ceiling checks for CAR-registered agents. Trust scores are capped by regulatory and organizational ceilings:

const ceiling = await client.checkCeiling({
  agentId: 'agent-123',
  proposedScore: 750,
  complianceFramework: 'EU_AI_ACT',  // Ceiling: 699
})

if (ceiling.result.ceilingApplied) {
  console.log(`Score capped from ${ceiling.result.proposedScore} to ${ceiling.result.finalScore}`)
  console.log(`Ceiling source: ${ceiling.result.ceilingSource}`)
  console.log(`Compliance: ${ceiling.result.complianceStatus}`)
}

Managing the Context Hierarchy (Q2)

The 4-tier context hierarchy is immutable and tracks every deployment, organization, agent, and operation:

// Get the full hierarchy
const hierarchy = await client.getContextHierarchy()
console.log(`${hierarchy.summary.agentCount} agents across ${hierarchy.summary.deploymentCount} deployments`)

// Navigate individual tiers
const deployments = await client.getDeployments()
const orgs = await client.getOrganizations(deployments[0].deploymentId)
const agents = await client.getAgents(deployments[0].deploymentId, orgs[0].orgId)
const operations = await client.getOperations(agents[0].agentId)

// Create a new deployment context
const deployment = await client.createDeployment({
  deploymentId: 'prod-us-east-1',
  name: 'Production US East',
  version: '2.1.0',
  environment: 'production',
  maxTrustCeiling: 900,
  contextHash: '...',
})

Federated Presets (Q4)

Presets follow a derivation chain: CAR (canonical) > Vorion (reference) > Axiom (deployment):

// Get the full preset hierarchy
const presets = await client.getPresetHierarchy()
console.log(`${presets.summary.aciCount} CAR canonical presets`)
console.log(`${presets.summary.verifiedLineages} verified lineages`)

// Access each tier of presets
const carPresets = await client.getCARPresets()
const vorionPresets = await client.getVorionPresets()
const axiomPresets = await client.getAxiomPresets('deployment-123')

// Verify that an Axiom preset traces back to a valid CAR canonical
const verification = await client.verifyPresetLineage('axiom-preset-123')
if (verification.verified) {
  console.log('Lineage verified: CAR > Vorion > Axiom')
}

Gaming Detection Alerts -- Trust Engine Feature

Gaming detection is a trust engine (ATSF/Cognigate) feature that monitors trust score manipulation attempts for CAR-registered agents. This SDK provides convenience access:

// Get active gaming alerts
const { alerts, summary } = await client.getGamingAlerts('ACTIVE')

alerts.forEach((alert) => {
  console.log(`[${alert.severity}] ${alert.alertType}: ${alert.details}`)
})

// Resolve a false positive
await client.updateGamingAlertStatus(
  alerts[0].id,
  'RESOLVED',
  '[email protected]',
  'False positive -- batch processing caused rapid score changes'
)

Local Development

import { createLocalCARClient } from '@vorion/car-client'

// Connect to a local CAR API with debug logging enabled
const client = createLocalCARClient(3000)
const health = await client.healthCheck()
console.log(`CAR API v${health.version} -- ${health.status}`)

API Reference

Factory Functions

| Function | Description | |----------|-------------| | createCARClient(config) | Create a CAR client with full configuration | | createLocalCARClient(port?) | Create a client for local development (debug mode enabled) |

CARClientConfig

interface CARClientConfig {
  baseUrl: string                      // CAR API base URL
  apiKey?: string                      // Bearer token for authentication
  timeout?: number                     // Request timeout in ms (default: 30000)
  headers?: Record<string, string>     // Custom HTTP headers
  debug?: boolean                      // Enable request/response logging
}

Client Methods

Stats and Dashboard

| Method | Return Type | Description | |--------|-------------|-------------| | getStats() | DashboardData | Get Phase 6 dashboard statistics | | healthCheck() | { status, version } | API health check |

Context Hierarchy (Q2)

| Method | Return Type | Description | |--------|-------------|-------------| | getContextHierarchy() | ContextHierarchy | Get full 4-tier hierarchy | | getDeployments() | DeploymentContext[] | List deployment contexts | | getOrganizations(deploymentId?) | OrgContext[] | List organization contexts | | getAgents(deploymentId?, orgId?) | AgentContext[] | List agent contexts | | getOperations(agentId?) | OperationContext[] | List operation contexts | | createDeployment(data) | DeploymentContext | Create a deployment context |

Role Gates (Q3)

| Method | Return Type | Description | |--------|-------------|-------------| | evaluateRoleGate(request) | RoleGateResponse | Evaluate 3-layer role gate | | getRoleGateEvaluations(agentId?, options?) | { evaluations, summary } | Get evaluation history |

Ceiling Enforcement (Q1) -- Trust Engine

| Method | Return Type | Description | |--------|-------------|-------------| | checkCeiling(request) | CeilingCheckResponse | Check score against trust engine ceilings | | getCeilingEvents(agentId?, options?) | { events, summary } | Get ceiling event history |

Gaming Alerts -- Trust Engine

| Method | Return Type | Description | |--------|-------------|-------------| | getGamingAlerts(status?, limit?) | { alerts, summary } | Get trust engine gaming alerts | | createGamingAlert(request) | { alert } | Create a gaming alert | | updateGamingAlertStatus(alertId, status, resolvedBy?, notes?) | { alert } | Update alert status |

Federated Presets (Q4)

| Method | Return Type | Description | |--------|-------------|-------------| | getPresetHierarchy() | PresetHierarchy | Get full preset hierarchy | | getCARPresets() | CARPreset[] | Get CAR canonical presets | | getVorionPresets() | VorionPreset[] | Get Vorion reference presets | | getAxiomPresets(deploymentId?) | AxiomPreset[] | Get Axiom deployment presets | | verifyPresetLineage(axiomPresetId) | { verified, lineage?, reason? } | Verify preset derivation chain |

Provenance (Q5)

| Method | Return Type | Description | |--------|-------------|-------------| | getProvenance(agentId?) | { records, summary, lineage? } | Get provenance records | | createProvenance(request) | { record } | Register agent provenance |

Utility Functions

Note: These utilities are convenience re-exports. Trust tier computation is a trust engine (ATSF/Cognigate) concept; these helpers are included so consumers do not need a separate dependency for common lookups.

| Function | Description | |----------|-------------| | getTierFromScore(score) | Compute trust tier (T0-T7) from a numeric score (trust engine logic, re-exported for convenience) | | isRoleAllowedForTier(role, tier) | Check if a role is permitted for a given tier (kernel layer) |

Exported Constants

Note: Trust-related constants (TRUST_TIER_RANGES, TRUST_TIER_LABELS, DEFAULT_PROVENANCE_MODIFIERS, REGULATORY_CEILINGS) are trust engine concepts re-exported by this SDK for developer convenience. They are defined by ATSF/Cognigate and BASIS, not by the CAR identity system.

| Constant | Description | |----------|-------------| | TRUST_TIER_RANGES | Score ranges for each trust tier (T0-T7) -- trust engine re-export | | TRUST_TIER_LABELS | Human-readable labels for each tier -- trust engine re-export | | AGENT_ROLE_LABELS | Human-readable labels for each role (R-L0 to R-L8) | | DEFAULT_PROVENANCE_MODIFIERS | Default trust score modifiers by creation type -- trust engine re-export | | REGULATORY_CEILINGS | Maximum trust score by compliance framework -- trust engine re-export |

Zod Schemas (Runtime Validation)

All request types have companion Zod schemas for runtime validation:

| Schema | Validates | |--------|-----------| | TrustTierSchema | Trust tier codes (T0-T7) | | AgentRoleSchema | Agent role codes (R_L0-R_L8) | | CreationTypeSchema | Creation types (FRESH, CLONED, EVOLVED, PROMOTED, IMPORTED) | | RoleGateDecisionSchema | Role gate decisions (ALLOW, DENY, ESCALATE) | | ComplianceStatusSchema | Compliance statuses (COMPLIANT, WARNING, VIOLATION) | | GamingAlertTypeSchema | Gaming alert types | | AlertSeveritySchema | Alert severity levels | | AlertStatusSchema | Alert status values | | RoleGateRequestSchema | Full role gate request validation | | CeilingCheckRequestSchema | Full ceiling check request validation | | ProvenanceCreateRequestSchema | Full provenance creation request validation |

Error Handling

import { CARError } from '@vorion/car-client'

try {
  await client.evaluateRoleGate(request)
} catch (error) {
  if (error instanceof CARError) {
    console.log(error.statusCode)  // HTTP status code
    console.log(error.details)     // API error details

    error.isClientError()  // true for 4xx
    error.isServerError()  // true for 5xx
    error.isTimeout()      // true for 408
    error.isStatus(404)    // check specific status
  }
}

Trust Tiers

Architectural note: Trust tiers are computed by the trust engine (ATSF/Cognigate) at runtime, not stored in the CAR identity. CAR does not assign or track trust scores. This table is included as a developer reference because the @vorion/car-client SDK re-exports trust tier constants and utility functions (e.g., getTierFromScore) as a convenience for consumers who need both identity and trust data.

| Tier | Label | Score Range | Description | |------|-------|-------------|-------------| | T0 | Sandbox | 0-199 | Isolated testing, no external access | | T1 | Observed | 200-349 | Read-only, fully monitored | | T2 | Provisional | 350-499 | Basic operations with supervision | | T3 | Monitored | 500-649 | Standard operations, anomaly detection | | T4 | Standard | 650-799 | Extended operations, policy-governed | | T5 | Trusted | 800-875 | Privileged operations, minimal oversight | | T6 | Certified | 876-950 | High autonomy, council review for critical | | T7 | Autonomous | 951-1000 | Full autonomy, self-governance |

Agent Roles

| Role | Level | Min Tier | Description | |------|-------|----------|-------------| | R-L0 | Listener | T0 | Passive observation | | R-L1 | Executor | T0 | Single task execution | | R-L2 | Planner | T1 | Multi-step planning | | R-L3 | Orchestrator | T2 | Multi-agent coordination | | R-L4 | Architect | T3 | System design | | R-L5 | Governor | T4 | Policy control | | R-L6 | Sovereign | T5 | Full autonomy | | R-L7 | Meta-Agent | T5 | Agent creation | | R-L8 | Ecosystem | T5 | Ecosystem control |

Compliance Frameworks

Architectural note: Compliance ceiling enforcement is a trust engine concept. The trust engine (ATSF/Cognigate) caps trust scores based on regulatory frameworks for CAR-registered agents. These constants are re-exported by the @vorion/car-client SDK for developer convenience.

| Framework | Max Trust Score | Description | |-----------|----------------|-------------| | EU_AI_ACT | 699 | EU Artificial Intelligence Act | | NIST_AI_RMF | 899 | NIST AI Risk Management Framework | | ISO_42001 | 799 | ISO/IEC 42001 AI Management System | | DEFAULT | 1000 | No regulatory ceiling applied |

Provenance Modifiers

Architectural note: Provenance modifiers are trust engine inputs, not CAR identity fields. When CAR records an agent's creation type (FRESH, CLONED, etc.), the trust engine (ATSF/Cognigate) applies these modifiers to compute the agent's initial trust score. The modifiers are re-exported by the @vorion/car-client SDK for developer convenience.

| Creation Type | Trust Modifier | Description | |---------------|---------------|-------------| | FRESH | 0 | New agent, no modifier | | CLONED | -50 | Copy of existing agent, penalty applied | | EVOLVED | +100 | Agent upgraded through training | | PROMOTED | +150 | Agent promoted through review | | IMPORTED | -100 | External agent, significant penalty |

License

Apache-2.0. See LICENSE for details.

Links

• Repository
• Package directory
• Issue tracker