@vorionsys/shared-constants

Single source of truth for the Vorion ecosystem -- canonical trust tiers, domain configuration, capability definitions, rate limits, error codes, API versions, product catalog, and UI themes.

Installation

npm install @vorionsys/shared-constants

What This Package Provides

| Module | Description | |--------|-------------| | Tiers | The BASIS 8-tier trust model (T0-T7) with score ranges, names, colors, and helper functions | | Domains | All Vorion, Agent Anchor, and Cognigate domains, API endpoints, emails, GitHub links, and npm package names | | Capabilities | Tier-gated capability definitions with categories and constraint metadata | | Products | Product catalog for both Vorion (open source) and Agent Anchor (commercial) with status and version info | | Rate Limits | Per-tier rate-limiting configurations and monthly quota definitions | | Error Codes | Standardized error codes (E1xxx-E7xxx) with HTTP status, categories, retry info, and message templates | | API Versions | Version management for Cognigate, Trust, Logic, BASIS, and CAR Spec APIs | | Themes | UI theme tokens (4 themes) with CSS custom-property generation |

Quick Start

import {
  TrustTier,
  TIER_THRESHOLDS,
  scoreToTier,
  API_ENDPOINTS,
  CAPABILITIES,
  getCapabilitiesForTier,
} from '@vorionsys/shared-constants';

// Convert a trust score to its tier
const tier = scoreToTier(750); // TrustTier.T4_STANDARD

// Look up tier metadata
const info = TIER_THRESHOLDS[TrustTier.T4_STANDARD];
console.log(info.name);         // "Standard"
console.log(info.min, info.max); // 650, 799
console.log(info.color);        // "#22c55e"

// List capabilities available at a tier
const caps = getCapabilitiesForTier(TrustTier.T4_STANDARD);
console.log(caps.map(c => c.code));
// ["CAP-READ-PUBLIC", "CAP-GENERATE-TEXT", ..., "CAP-ESCALATE-HUMAN"]

// Get an API endpoint
const apiUrl = API_ENDPOINTS.cognigate.production;
// "https://cognigate.dev/v1"

Trust Tiers

The BASIS 8-tier trust model (score range 0--1000):

| Tier | Score | Name | Description | |------|-------|------|-------------| | T0 | 0--199 | Sandbox | Isolated, no external access, observation only | | T1 | 200--349 | Observed | Read-only, sandboxed execution, monitored | | T2 | 350--499 | Provisional | Basic operations, heavy supervision | | T3 | 500--649 | Monitored | Standard operations with continuous monitoring | | T4 | 650--799 | Standard | External API access, policy-governed | | T5 | 800--875 | Trusted | Cross-agent communication, delegated tasks | | T6 | 876--950 | Certified | Admin tasks, agent spawning, minimal oversight | | T7 | 951--1000 | Autonomous | Full autonomy, self-governance, strategic only |

Subpath Imports

Import only the module you need to minimize bundle size:

import { TrustTier, scoreToTier } from '@vorionsys/shared-constants/tiers';
import { VORION_DOMAINS, API_ENDPOINTS } from '@vorionsys/shared-constants/domains';
import { CAPABILITIES, getCapabilitiesForTier } from '@vorionsys/shared-constants/capabilities';
import { VORION_PRODUCTS } from '@vorionsys/shared-constants/products';
import { RATE_LIMITS, getRateLimits } from '@vorionsys/shared-constants/rate-limits';
import { ERROR_CODES, getErrorByCode } from '@vorionsys/shared-constants/error-codes';
import { API_VERSIONS, getCurrentVersion } from '@vorionsys/shared-constants/api-versions';
import { THEMES, getActiveTheme, themeToCssVars } from '@vorionsys/shared-constants/themes';

Usage Examples

Trust Tier Helpers

import {
  TrustTier,
  scoreToTier,
  getTierName,
  getTierColor,
  getTierMinScore,
  getTierMaxScore,
  getTierCode,
  meetsTierRequirement,
  parseTier,
  ALL_TIERS,
} from '@vorionsys/shared-constants';

scoreToTier(750);                                 // TrustTier.T4_STANDARD
getTierName(TrustTier.T5_TRUSTED);                // "Trusted"
getTierColor(TrustTier.T3_MONITORED);             // "#eab308"
getTierMinScore(TrustTier.T4_STANDARD);           // 650
getTierMaxScore(TrustTier.T4_STANDARD);           // 799
getTierCode(TrustTier.T4_STANDARD);               // "T4"
meetsTierRequirement(750, TrustTier.T3_MONITORED); // true
parseTier('T3');                                   // TrustTier.T3_MONITORED
parseTier('TRUSTED');                              // TrustTier.T5_TRUSTED
ALL_TIERS;                                         // [T0, T1, T2, T3, T4, T5, T6, T7]

Domains and Endpoints

import {
  VORION_DOMAINS,
  AGENTANCHOR_DOMAINS,
  COGNIGATE_DOMAINS,
  API_ENDPOINTS,
  VORION_EMAILS,
  GITHUB,
  NPM_PACKAGES,
  ALL_DOMAINS,
  DOMAIN_ALIASES,
} from '@vorionsys/shared-constants';

VORION_DOMAINS.basis;                  // "https://basis.vorion.org"
AGENTANCHOR_DOMAINS.trust;             // "https://trust.agentanchorai.com"
COGNIGATE_DOMAINS.main;                // "https://cognigate.dev"
API_ENDPOINTS.cognigate.production;    // "https://cognigate.dev/v1"
API_ENDPOINTS.agentAnchor.sandbox;     // "https://sandbox.agentanchorai.com/v1"
VORION_EMAILS.security;               // "[email protected]"
GITHUB.vorion.mainRepo;               // "https://github.com/voriongit/vorion"
NPM_PACKAGES.vorion.sharedConstants;   // "@vorionsys/shared-constants"

Capabilities

import {
  CapabilityCategory,
  CAPABILITIES,
  getCapabilitiesForTier,
  getCapability,
  isCapabilityAvailable,
  getCapabilityMinTier,
  getCapabilitiesByCategory,
  getAllCapabilityCodes,
} from '@vorionsys/shared-constants';

// Get all capabilities unlocked at T4 or below
const caps = getCapabilitiesForTier(TrustTier.T4_STANDARD);

// Look up a single capability
const cap = getCapability('CAP-AGENT-DELEGATE');
// { code: "CAP-AGENT-DELEGATE", name: "Task Delegation", unlockTier: T5_TRUSTED, ... }

// Check if available
isCapabilityAvailable('CAP-FILE-WRITE', TrustTier.T3_MONITORED); // true (unlocks at T2)

// Get minimum tier needed
getCapabilityMinTier('CAP-AGENT-SPAWN'); // TrustTier.T6_CERTIFIED

// Filter by category
const apiCaps = getCapabilitiesByCategory(CapabilityCategory.API_ACCESS);

Products

import {
  ProductCategory,
  ProductStatus,
  VORION_PRODUCTS,
  AGENTANCHOR_PRODUCTS,
  ALL_PRODUCTS,
  getProduct,
  getProductsByCategory,
  getProductsByStatus,
  getProductsByOrganization,
} from '@vorionsys/shared-constants';

const basis = getProduct('basis');
// { id: "basis", name: "BASIS", status: "ga", url: "https://basis.vorion.org", ... }

const gaProducts = getProductsByStatus(ProductStatus.GA);
const openSource = getProductsByCategory(ProductCategory.OPEN_SOURCE);
const vorionProducts = getProductsByOrganization('vorion');

Rate Limits and Quotas

import {
  TrustTier,
  RATE_LIMITS,
  TIER_QUOTAS,
  getRateLimits,
  wouldExceedLimit,
  formatRateLimit,
  getQuota,
  isUnlimited,
} from '@vorionsys/shared-constants';

const limits = getRateLimits(TrustTier.T4_STANDARD);
// { requestsPerSecond: 20, requestsPerMinute: 600, burstLimit: 50, ... }

wouldExceedLimit(TrustTier.T4_STANDARD, 'minute', 599); // false
wouldExceedLimit(TrustTier.T4_STANDARD, 'minute', 600); // true

formatRateLimit(TrustTier.T4_STANDARD);
// "20/s, 600/min, 10000/hr"

const quota = getQuota(TrustTier.T7_AUTONOMOUS);
isUnlimited(quota.monthlyApiCalls); // true (-1 means unlimited)

Error Codes

import {
  ErrorCategory,
  ERROR_CODES,
  getErrorByCode,
  getErrorsByCategory,
  getRetryableErrors,
  formatErrorMessage,
  createErrorResponse,
} from '@vorionsys/shared-constants';

// Look up error by its code string
const err = getErrorByCode('E1001');
// { code: "E1001", httpStatus: 401, category: "auth", message: "API key is missing...", retryable: false }

// Use a named error constant
const response = createErrorResponse(
  ERROR_CODES.TRUST_TIER_INSUFFICIENT,
  { currentTier: 'T2', requiredTier: 'T4' },
  'req_abc123',
);
// { error: { code: "E5001", message: "Trust tier T2 insufficient. Required: T4.", ... }, status: 403 }

// Get all retryable errors (useful for retry logic)
const retryable = getRetryableErrors();

// Get errors by category
const authErrors = getErrorsByCategory(ErrorCategory.AUTH);

API Versions

import {
  VersionStatus,
  API_VERSIONS,
  getCurrentVersion,
  getVersionDefinition,
  isVersionSupported,
  isVersionDeprecated,
  getStableVersions,
  buildApiUrl,
  VERSION_HEADERS,
  COGNIGATE_CURRENT_VERSION,
  BASIS_SPEC_VERSION,
} from '@vorionsys/shared-constants';

getCurrentVersion('cognigate');   // "v1"
getCurrentVersion('basis');       // "v1"
BASIS_SPEC_VERSION;               // "1.0.0"

isVersionSupported('cognigate', 'v1');  // true
isVersionDeprecated('cognigate', 'v1'); // false

buildApiUrl('https://cognigate.dev', 'v1', 'agents/lookup');
// "https://cognigate.dev/v1/agents/lookup"

const stableVersions = getStableVersions('trust');

VERSION_HEADERS.REQUEST_VERSION;  // "X-API-Version"

Themes

import {
  ACTIVE_THEME,
  THEMES,
  getActiveTheme,
  getAllThemeIds,
  themeToCssVars,
} from '@vorionsys/shared-constants';

ACTIVE_THEME;              // "midnight_cyan"
getAllThemeIds();           // ["midnight_cyan", "indigo_authority", "obsidian_amber", "arctic_glass"]

const theme = getActiveTheme();
console.log(theme.accent);      // "#06b6d4"
console.log(theme.bgPrimary);   // "#0a0a0f"
console.log(theme.fontFamily);  // "'Inter', -apple-system, ..."

// Generate CSS custom properties for injection
const cssVars = themeToCssVars('midnight_cyan');
// "--bg-primary: #0a0a0f; --accent: #06b6d4; ..."

API Reference

Tiers (@vorionsys/shared-constants/tiers)

| Export | Kind | Description | |--------|------|-------------| | TrustTier | enum | Trust tier enum (T0_SANDBOX through T7_AUTONOMOUS) | | TIER_THRESHOLDS | const | Score ranges, names, descriptions, and colors for each tier | | scoreToTier(score) | function | Convert a 0-1000 score to its TrustTier | | getTierThreshold(tier) | function | Get the full TierThreshold object for a tier | | getTierName(tier) | function | Get human-readable tier name | | getTierColor(tier) | function | Get hex color for a tier | | getTierMinScore(tier) | function | Get minimum score required for a tier | | getTierMaxScore(tier) | function | Get maximum score for a tier | | getTierCode(tier) | function | Get short code string (e.g. "T4") | | meetsTierRequirement(score, minTier) | function | Check if a score meets a minimum tier | | parseTier(input) | function | Parse tier from string ("T3", "3", "MONITORED") | | ALL_TIERS | const | Ordered array of all 8 tiers | | TierThreshold | type | Interface for tier threshold configuration | | TrustTierName | type | Union of tier display names | | TrustTierCode | type | Union of tier short codes ("T0" through "T7") |

Domains (@vorionsys/shared-constants/domains)

| Export | Kind | Description | |--------|------|-------------| | VORION_DOMAINS | const | Vorion organization URLs (main, basis, carId, atsf, learn, kaizen) | | AGENTANCHOR_DOMAINS | const | Agent Anchor AI URLs (main, trust, logic, status, verify) | | COGNIGATE_DOMAINS | const | Cognigate URLs (main, docs) | | API_ENDPOINTS | const | Production/staging/sandbox API base URLs | | VORION_EMAILS | const | Vorion contact email addresses | | AGENTANCHOR_EMAILS | const | Agent Anchor contact email addresses | | GITHUB | const | GitHub organization and repo URLs | | NPM_PACKAGES | const | npm package names for all published packages | | ALL_DOMAINS | const | Combined object containing all domain groups | | DOMAIN_ALIASES | const | Map of alternate domains to their primary | | VorionDomain | type | Key union for VORION_DOMAINS | | AgentAnchorDomain | type | Key union for AGENTANCHOR_DOMAINS | | CognigateDomain | type | Key union for COGNIGATE_DOMAINS |

Capabilities (@vorionsys/shared-constants/capabilities)

| Export | Kind | Description | |--------|------|-------------| | CapabilityCategory | enum | Capability categories (DATA_ACCESS, API_ACCESS, CODE_EXECUTION, etc.) | | CAPABILITIES | const | Array of all capability definitions with tier gates | | getCapabilitiesForTier(tier) | function | Get all capabilities available at or below a tier | | getCapability(code) | function | Look up a capability by its code string | | isCapabilityAvailable(code, tier) | function | Check if a capability is unlocked at a tier | | getCapabilityMinTier(code) | function | Get the minimum tier required for a capability | | getCapabilitiesByCategory(category) | function | Filter capabilities by category | | getAllCapabilityCodes() | function | Get array of all capability code strings | | CapabilityDefinition | type | Interface for a capability definition |

Products (@vorionsys/shared-constants/products)

| Export | Kind | Description | |--------|------|-------------| | ProductCategory | enum | Product categories (OPEN_SOURCE, COMMERCIAL, DEVELOPER_TOOLS, EDUCATION) | | ProductStatus | enum | Product lifecycle status (DEVELOPMENT through EOL) | | VORION_PRODUCTS | const | Vorion open-source product definitions | | AGENTANCHOR_PRODUCTS | const | Agent Anchor commercial product definitions | | ALL_PRODUCTS | const | Combined product catalog | | getProduct(id) | function | Look up a product by ID | | getProductsByCategory(category) | function | Filter products by category | | getProductsByStatus(status) | function | Filter products by lifecycle status | | getProductsByOrganization(org) | function | Get products for "vorion" or "agentanchor" | | ProductDefinition | type | Interface for a product definition |

Rate Limits (@vorionsys/shared-constants/rate-limits)

| Export | Kind | Description | |--------|------|-------------| | RATE_LIMITS | const | Rate-limit configurations keyed by tier | | TIER_QUOTAS | const | Monthly quota configurations keyed by tier | | getRateLimits(tier) | function | Get RateLimitConfig for a tier | | getMinTierForLimits(config) | function | Find the lowest tier that satisfies given limits | | wouldExceedLimit(tier, window, count) | function | Check if a count exceeds a tier's limit for a time window | | formatRateLimit(tier) | function | Human-readable rate-limit string | | getQuota(tier) | function | Get QuotaConfig for a tier | | isUnlimited(value) | function | Check if a quota value represents unlimited (-1) | | RateLimitConfig | type | Interface for rate-limit settings | | QuotaConfig | type | Interface for monthly quota settings |

Error Codes (@vorionsys/shared-constants/error-codes)

| Export | Kind | Description | |--------|------|-------------| | ErrorCategory | enum | Error categories (AUTH, VALIDATION, RATE_LIMIT, NOT_FOUND, TRUST, SERVER, EXTERNAL, CONFIG) | | AUTH_ERRORS | const | Authentication error definitions (E1001-E1007) | | VALIDATION_ERRORS | const | Validation error definitions (E2001-E2008) | | RATE_LIMIT_ERRORS | const | Rate-limit error definitions (E3001-E3004) | | NOT_FOUND_ERRORS | const | Not-found error definitions (E4001-E4005) | | TRUST_ERRORS | const | Trust/governance error definitions (E5001-E5007) | | SERVER_ERRORS | const | Server error definitions (E6001-E6004) | | EXTERNAL_ERRORS | const | External service error definitions (E7001-E7003) | | ERROR_CODES | const | All error definitions merged into one object | | getErrorByCode(code) | function | Look up error by code string (e.g. "E1001") | | getErrorsByCategory(category) | function | Get all errors in a category | | getRetryableErrors() | function | Get all errors marked as retryable | | formatErrorMessage(error, params) | function | Interpolate parameters into a message template | | createErrorResponse(error, params?, requestId?) | function | Build a structured error response object | | ErrorDefinition | type | Interface for an error definition | | ErrorCode | type | Union of all error constant keys |

API Versions (@vorionsys/shared-constants/api-versions)

| Export | Kind | Description | |--------|------|-------------| | VersionStatus | enum | Version lifecycle status (DEVELOPMENT, PREVIEW, STABLE, DEPRECATED, RETIRED) | | COGNIGATE_VERSIONS | const | Cognigate API version definitions | | COGNIGATE_CURRENT_VERSION | const | Current Cognigate API version string | | COGNIGATE_DEFAULT_VERSION | const | Default Cognigate API version string | | TRUST_API_VERSIONS | const | Trust API version definitions | | TRUST_CURRENT_VERSION | const | Current Trust API version string | | LOGIC_API_VERSIONS | const | Logic API version definitions | | LOGIC_CURRENT_VERSION | const | Current Logic API version string | | BASIS_VERSIONS | const | BASIS spec version definitions | | BASIS_CURRENT_VERSION | const | Current BASIS spec version string | | BASIS_SPEC_VERSION | const | Full semver of BASIS spec ("1.0.0") | | CAR_SPEC_VERSIONS | const | CAR Spec version definitions | | CAR_SPEC_CURRENT_VERSION | const | Current CAR Spec version string | | API_VERSIONS | const | All API version definitions grouped by service | | getCurrentVersion(service) | function | Get current version for a service | | getVersionDefinition(service, version) | function | Get full version definition | | isVersionSupported(service, version) | function | Check if a version is still supported | | isVersionDeprecated(service, version) | function | Check if a version is deprecated | | getStableVersions(service) | function | Get all stable versions for a service | | buildApiUrl(baseUrl, version, path) | function | Build a versioned API URL | | VERSION_HEADERS | const | Standard HTTP header names for version negotiation | | ApiVersionDefinition | type | Interface for an API version definition |

Themes (@vorionsys/shared-constants/themes)

| Export | Kind | Description | |--------|------|-------------| | ACTIVE_THEME | const | Currently active theme ID | | THEMES | const | All theme token definitions keyed by ThemeId | | getActiveTheme() | function | Get token object for the active theme | | getAllThemeIds() | function | Get array of all available theme IDs | | themeToCssVars(themeId?) | function | Generate CSS custom-property string for a theme | | ThemeId | type | Union of theme identifiers | | ThemeTokens | type | Interface for a complete set of theme tokens |

Root Exports

| Export | Kind | Description | |--------|------|-------------| | VERSION | const | Package version string | | LAST_UPDATED | const | Last updated date string |

TypeScript

All types are fully exported and can be imported as type-only:

import type {
  TrustTier,
  TierThreshold,
  TrustTierName,
  TrustTierCode,
  CapabilityDefinition,
  CapabilityCategory,
  ProductDefinition,
  ProductCategory,
  ProductStatus,
  RateLimitConfig,
  QuotaConfig,
  ErrorDefinition,
  ErrorCode,
  ErrorCategory,
  ApiVersionDefinition,
  VersionStatus,
  ThemeId,
  ThemeTokens,
  VorionDomain,
  AgentAnchorDomain,
  CognigateDomain,
} from '@vorionsys/shared-constants';

Requirements

• Node.js >= 18
• TypeScript >= 5.7 (for type-only imports)

Repository

This package lives in the Vorion monorepo:

https://github.com/voriongit/vorion/tree/master/packages/shared-constants

License

Apache-2.0