@vorionsys/runtime

Orchestration layer for AI agent governance, built on the Vorion trust framework and aligned with the BASIS (Baseline Authority for Safe & Interoperable Systems) specification.

Combines Gate Trust (one-time admission control) and Dynamic Trust (per-action real-time scoring) into a unified, fast decision system with cryptographic proof of every governance decision.

Installation

npm install @vorionsys/runtime

Peer dependencies (optional, enhance functionality):

npm install @vorionsys/atsf-core @vorionsys/contracts

Quick Start

import {
  createTrustFacade,
  createProofCommitter,
  createIntentPipeline,
} from '@vorionsys/runtime';

// 1. Create the trust facade (Gate Trust + Dynamic Trust)
const facade = createTrustFacade();

// 2. Create the proof committer (cryptographic audit trail)
const committer = createProofCommitter();

// 3. Wire them together with the intent pipeline
const pipeline = createIntentPipeline(facade, committer);

// 4. Admit an agent (Gate Trust - "the door")
const admission = await facade.admit({
  agentId: 'agent-123',
  name: 'DataProcessor',
  capabilities: ['read:data', 'write:reports'],
  observationTier: 'GRAY_BOX',
});

console.log(admission.admitted);          // true
console.log(admission.initialScore);      // 200 (GRAY_BOX initial)
console.log(admission.observationCeiling); // 800

// 5. Authorize an action (Dynamic Trust - "the handshake")
const auth = await facade.authorize('agent-123', {
  type: 'read',
  resource: 'data/users',
});

if (auth.allowed) {
  console.log('Decision tier:', auth.tier);         // 'GREEN'
  console.log('Constraints:', auth.constraints);    // { timeoutMs, maxOperations, ... }
}

What It Provides

| Component | Purpose | |---|---| | TrustFacade | Unified API combining gate trust (admission) and dynamic trust (per-action authorization) with an 8-tier trust model (T0-T7) | | ProofCommitter | Zero-latency synchronous hash commitment (<1ms) with async Merkle-tree batching and optional Ed25519 signing | | IntentPipeline | End-to-end orchestration: Intent -> Gate Check -> Authorization -> Execution -> Proof | | SQLiteProofStore | Persistent proof storage backed by better-sqlite3 with WAL mode | | SQLiteTrustStore | Persistent agent trust records and signal history backed by better-sqlite3 | | InMemoryProofStore | In-memory proof store for testing and development |

Core Concepts

Trust Tiers (T0-T7)

Agents are assigned a numeric trust score (0-1000) that maps to one of eight tiers:

| Tier | Name | Score Range | |------|------|-------------| | T0 | Untrusted | 0-99 | | T1 | Provisional | 100-199 | | T2 | Basic | 200-349 | | T3 | Monitored | 350-499 | | T4 | Standard | 500-649 | | T5 | Trusted | 650-799 | | T6 | Elevated | 800-899 | | T7 | Autonomous | 900-1000 |

Observation Tiers

Agent visibility determines the maximum trust score (ceiling) an agent can achieve:

• BLACK_BOX -- Opaque internals, ceiling at 500 (max T3)
• GRAY_BOX -- Partial visibility, ceiling at 800 (max T5)
• WHITE_BOX -- Full visibility, ceiling at 1000 (max T7)

Decision Tiers

Every authorization returns one of three decision tiers:

• GREEN -- Allowed with standard constraints
• YELLOW -- Allowed with additional constraints and refinement options
• RED -- Denied

Asymmetric Trust Dynamics

Trust is hard to earn and easy to lose. Decay and recovery dynamics are policy-configurable, preventing rapid trust escalation while enforcing accountability.

Subpath Imports

Each major component is available as a subpath import:

// Root -- all exports
import { createTrustFacade, createProofCommitter, createIntentPipeline } from '@vorionsys/runtime';

// Trust facade only
import { createTrustFacade, TrustFacade } from '@vorionsys/runtime/trust-facade';

// Proof committer only
import { createProofCommitter, ProofCommitter } from '@vorionsys/runtime/proof-committer';

// Intent pipeline only
import { createIntentPipeline, IntentPipeline } from '@vorionsys/runtime/intent-pipeline';

// Persistent stores
import { createSQLiteProofStore, createSQLiteTrustStore } from '@vorionsys/runtime/stores';

API Reference

TrustFacade

The primary API for agent governance. Implements the TrustGate interface.

import { createTrustFacade, type TrustFacadeConfig } from '@vorionsys/runtime';

const facade = createTrustFacade({
  // All fields are optional with sensible defaults
  gateTrustCacheTtlMs: 3600000,       // Cache gate trust results for 1 hour
  maxAuthorizationLatencyMs: 50,       // Target latency for authorize()
  useAtsfForPersistence: true,         // Use ATSF-core for persistence
  useA3iForDynamics: true,             // Use A3I for trust dynamics
  primaryScoreSource: 'atsf',          // Primary source for trust scores
});

facade.admit(agent: AgentCredentials): Promise<AdmissionResult>

Gate trust check -- called once at agent registration. Result is cached.

const result = await facade.admit({
  agentId: 'agent-123',
  name: 'My Agent',
  capabilities: ['read:data', 'write:reports'],
  observationTier: 'WHITE_BOX',       // 'BLACK_BOX' | 'GRAY_BOX' | 'WHITE_BOX'
  metadata: { version: '1.0' },       // optional
});

// AdmissionResult:
// {
//   admitted: boolean,
//   initialTier: TrustTier,         // 0-7
//   initialScore: number,           // e.g. 300 for WHITE_BOX
//   observationCeiling: number,     // e.g. 1000 for WHITE_BOX
//   capabilities: string[],
//   expiresAt: Date,
//   reason?: string,                // set when admitted === false
// }

facade.authorize(agentId: string, action: Action): Promise<AuthorizationResult>

Dynamic trust check -- called on every action. Must be fast (<50ms target).

const auth = await facade.authorize('agent-123', {
  type: 'read',              // 'read' | 'write' | 'delete' | 'execute' | ...
  resource: 'data/users',
  context: { limit: 100 },   // optional
});

// AuthorizationResult:
// {
//   allowed: boolean,
//   tier: DecisionTier,            // 'GREEN' | 'YELLOW' | 'RED'
//   currentScore: number,
//   currentTier: TrustTier,
//   constraints?: Constraints,     // timeoutMs, maxOperations, resourceLimits
//   refinements?: Refinement[],    // YELLOW decisions include refinement options
//   reason: string,
//   latencyMs: number,
// }

facade.fullCheck(agent: AgentCredentials, action: Action): Promise<FullCheckResult>

Combined admission + authorization in a single call. Useful for first-time agent interactions.

const result = await facade.fullCheck(agentCredentials, action);

// FullCheckResult:
// {
//   admission: AdmissionResult,
//   authorization?: AuthorizationResult,  // only present if admission.admitted === true
// }

facade.recordSignal(signal: TrustSignal): Promise<void>

Record a trust signal that updates the agent's dynamic trust score.

await facade.recordSignal({
  agentId: 'agent-123',
  type: 'success',            // 'success' | 'failure' | 'violation' | 'neutral'
  weight: 0.5,                // 0-1
  source: 'execution-engine',
  context: { intentId: '...' },  // optional
});

facade.getScore(agentId: string): Promise<number | null>

Returns the current trust score, or null if the agent is unknown.

facade.getTier(agentId: string): Promise<TrustTier | null>

Returns the current trust tier (0-7), or null if the agent is unknown.

facade.revoke(agentId: string, reason: string): Promise<void>

Revoke an agent's admission. Clears cached trust data and prevents future authorizations until re-admitted.

ProofCommitter

Zero-latency cryptographic proof system. Synchronous hash commitment on the hot path (<1ms), with asynchronous Merkle-tree batching on the cold path.

import { createProofCommitter, type ProofCommitterConfig } from '@vorionsys/runtime';

const committer = createProofCommitter({
  maxBufferSize: 100,        // Auto-flush when buffer reaches this size
  flushIntervalMs: 100,      // Periodic flush interval
  enableSigning: false,      // Enable Ed25519 signing
  privateKey: undefined,     // Base64-encoded Ed25519 private key (required if signing enabled)
});

committer.commit(event: ProofEvent): string

Synchronous hot-path commitment. Returns a commitment ID. Target: <1ms.

const commitmentId = committer.commit({
  type: 'intent_submitted',   // ProofEventType
  entityId: 'agent-123',
  payload: { action: 'read', resource: 'data/users' },
  timestamp: Date.now(),
  correlationId: 'corr-456',  // optional, for linking related events
});

ProofEventType values: 'intent_submitted' | 'decision_made' | 'execution_started' | 'execution_completed' | 'trust_signal' | 'agent_admitted' | 'agent_revoked' | 'parity_violation'

committer.flush(): Promise<void>

Force-flush the buffer. Builds a Merkle tree, optionally signs, and persists to the proof store.

committer.stop(): Promise<void>

Flush remaining events and stop the periodic flush timer. Call this on shutdown.

committer.getCommitment(commitmentId: string): Promise<ProofCommitment | null>

Retrieve a commitment from the store by ID.

committer.getCommitmentsForEntity(entityId: string): Promise<ProofCommitment[]>

Retrieve all commitments for a given entity (agent, intent, etc.).

committer.verifyCommitment(commitment: ProofCommitment): boolean

Verify a commitment's SHA-256 hash matches the original event.

committer.getMetrics()

Returns { totalCommitments, totalBatches, avgFlushTimeMs, bufferSize }.

committer.getBufferSize(): number

Returns the number of uncommitted events in the buffer.

IntentPipeline

Orchestrates the full agent intent lifecycle: Intent -> Gate Check -> Authorization -> Execution -> Proof.

import { createIntentPipeline, type IntentPipelineConfig } from '@vorionsys/runtime';

const pipeline = createIntentPipeline(trustFacade, proofCommitter, {
  verboseLogging: false,       // Enable detailed logging
  timeoutMs: 5000,             // Maximum processing time
  autoRecordSignals: true,     // Auto-record trust signals on execution
});

pipeline.registerHandler(actionType: string, handler: ExecutionHandler): void

Register an execution handler for an action type.

pipeline.registerHandler('read', async (intent, context) => {
  // Execute the intent
  const data = await myDatabase.query(intent.action.resource);
  return { success: true, result: data };
});

pipeline.registerHandler('write', async (intent, context) => {
  try {
    await myDatabase.write(intent.action.resource, intent.metadata);
    return { success: true };
  } catch (err) {
    return { success: false, error: err.message };
  }
});

pipeline.submit(credentials: AgentCredentials, action: Action, metadata?: Record<string, unknown>): Promise<IntentResult>

Submit an intent for full processing (gate check, authorization, execution, proof).

const result = await pipeline.submit(
  {
    agentId: 'agent-123',
    name: 'DataProcessor',
    capabilities: ['read:data'],
    observationTier: 'GRAY_BOX',
  },
  { type: 'read', resource: 'data/users' },
  { limit: 50 },  // optional metadata
);

// IntentResult:
// {
//   intentId: string,
//   allowed: boolean,
//   tier: DecisionTier,          // 'GREEN' | 'YELLOW' | 'RED'
//   reason: string,
//   commitmentId: string,        // proof commitment ID
//   constraints?: string[],
//   processingTimeMs: number,
// }

pipeline.check(credentials: AgentCredentials, action: Action): Promise<{ allowed, tier, reason }>

Quick authorization check without execution.

pipeline.getMetrics()

Returns { totalIntents, allowedIntents, deniedIntents, avgProcessingTimeMs, allowRate }.

pipeline.flushProofs(): Promise<void>

Flush all pending proof commitments.

pipeline.stop(): Promise<void>

Stop the pipeline and flush remaining proofs.

Persistent Stores

SQLite-backed stores for production use. Both use WAL mode by default for better write concurrency.

SQLiteProofStore

import { createSQLiteProofStore } from '@vorionsys/runtime/stores';

const proofStore = createSQLiteProofStore({
  dbPath: './data/proofs.db',   // Use ':memory:' for in-memory
  walMode: true,                // default: true
});

// Pass to ProofCommitter
const committer = createProofCommitter({ maxBufferSize: 100 }, proofStore);

// Query proofs
const commitment = await proofStore.getCommitment('commitment-id');
const batch = await proofStore.getBatch('batch-id');
const entityProofs = await proofStore.getCommitmentsForEntity('agent-123');

// Housekeeping
proofStore.getStats();  // { batches: number, commitments: number }
proofStore.close();     // Close DB connection on shutdown

SQLiteTrustStore

import { createSQLiteTrustStore } from '@vorionsys/runtime/stores';

const trustStore = createSQLiteTrustStore({
  dbPath: './data/trust.db',    // Use ':memory:' for in-memory
  walMode: true,                // default: true
});

// Save/retrieve agent trust records
await trustStore.saveAgent(agentRecord);
const agent = await trustStore.getAgent('agent-123');

// Update scores
await trustStore.updateScore('agent-123', 450, 3);

// Revoke
await trustStore.revokeAgent('agent-123', 'Policy violation');

// Record and query trust signals
await trustStore.recordSignal(signalRecord);
const signals = await trustStore.getSignals('agent-123', 50);

// List active agents
const agents = await trustStore.listActiveAgents();

// Housekeeping
trustStore.getStats();  // { agents, activeAgents, signals }
trustStore.close();

InMemoryProofStore

import { InMemoryProofStore } from '@vorionsys/runtime';

const store = new InMemoryProofStore();
// Same ProofStore interface, useful for testing
store.getStats();  // { batches: number, commitments: number }
store.clear();     // Reset all data

Logger

import { createLogger } from '@vorionsys/runtime';

const logger = createLogger({
  component: 'my-component',
  level: 'debug',  // optional, defaults to LOG_LEVEL env var or 'info'
});

Uses pino with pretty-printing in non-production environments.

Full Example: Intent Pipeline

import {
  createTrustFacade,
  createProofCommitter,
  createIntentPipeline,
  createSQLiteProofStore,
} from '@vorionsys/runtime';

// Set up persistent proof storage
const proofStore = createSQLiteProofStore({ dbPath: './data/proofs.db' });

// Create the governance stack
const facade = createTrustFacade();
const committer = createProofCommitter({ maxBufferSize: 50 }, proofStore);
const pipeline = createIntentPipeline(facade, committer, {
  autoRecordSignals: true,
});

// Register execution handlers
pipeline.registerHandler('read', async (intent) => {
  const data = await fetchData(intent.action.resource);
  return { success: true, result: data };
});

// Submit an intent
const result = await pipeline.submit(
  {
    agentId: 'data-agent',
    name: 'Data Agent',
    capabilities: ['read:data'],
    observationTier: 'GRAY_BOX',
  },
  { type: 'read', resource: 'data/reports' },
);

if (result.allowed) {
  console.log(`Intent ${result.intentId} processed in ${result.processingTimeMs}ms`);
  console.log(`Decision: ${result.tier}, Proof: ${result.commitmentId}`);
} else {
  console.log(`Denied: ${result.reason}`);
}

// Graceful shutdown
await pipeline.stop();
proofStore.close();

TypeScript

All types are exported from the root entry point:

import type {
  // Trust Facade
  TrustGate,
  TrustFacadeConfig,
  AgentCredentials,
  AdmissionResult,
  Action,
  AuthorizationResult,
  FullCheckResult,
  TrustSignal,
  TrustTier,
  DecisionTier,
  ObservationTier,
  Constraints,
  Refinement,

  // Proof Committer
  ProofEvent,
  ProofEventType,
  ProofCommitment,
  ProofBatch,
  ProofCommitterConfig,
  ProofStore,

  // Intent Pipeline
  Intent,
  IntentResult,
  PipelineContext,
  IntentPipelineConfig,
  ExecutionHandler,

  // Stores
  SQLiteProofStoreConfig,
  SQLiteTrustStoreConfig,
  TrustStore,
  AgentTrustRecord,
  TrustSignalRecord,

  // Logger
  LoggerOptions,
} from '@vorionsys/runtime';

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (peer dependency)

License

Apache-2.0

Links

• Vorion Monorepo
• BASIS Specification -- Baseline Authority for Safe & Interoperable Systems