@oxdeai/core

Deterministic Economic Containment Engine for Autonomous Systems

Deterministic · Canonical Snapshots · Property-Tested

@oxdeai/core is a TypeScript policy engine that enforces hard economic invariants before an agent executes an action.

It answers a narrow question:

Given an intent and a policy state, is this action economically allowed - deterministically?

If allowed, it emits a signed, expiring authorization bound to the intent and state snapshot. If denied, it fails closed.

No dashboards. No LLM classifiers. No heuristics. No post-fact monitoring.

Just deterministic pre-execution containment.

The Problem

Autonomous systems fail economically before they fail semantically.

Common failure modes:

• runaway tool-call loops
• recursive planning explosions
• uncontrolled concurrency
• replayed actions
• silent budget drain
• consumption-based billing surprises

Most “guardrails” operate after execution or rely on probabilistic models.

Economic invariants should not be probabilistic.

What This Library Is

A deterministic policy substrate that:

• evaluates (intent, state) → stable decision

• enforces:

  • per-period budgets
  • per-action caps
  • velocity windows
  • recursion depth limits
  • concurrency slots
  • replay protection

• emits signed authorizations (HMAC)

• produces hash-chained audit logs

• supports pure evaluation (evaluatePure)

• produces content-addressed policyId

• produces canonical stateHash

• produces tamper-evident auditHeadHash

Same inputs ⇒ same outputs.

What This Library Is Not

• Not a billing tool
• Not a cloud budget monitor
• Not a prompt filter
• Not a dashboard
• Not distributed coordination

It is the deterministic outer boundary.

Deterministic Guarantees

v0.6.0 formalizes deterministic snapshot and identity guarantees:

• policyId - content-addressed engine configuration
• stateHash - canonical snapshot hash
• auditHeadHash - tamper-evident execution trace hash
• formatVersion: 1 for canonical snapshots
• canonical JSON snapshot payloads (modules: Record<string, unknown>)
• portability across runtimes (no v8 blobs in snapshots)
• decode validation rejects malformed snapshots

If the engine version, module set, state, and event sequence are the same, these hashes are identical across runs.

Intent identity is canonical and signature-stripped.

Strict mode removes implicit entropy sources.

Show me the invariant

const out = engine.evaluatePure(intent, state);
const policyId = engine.computePolicyId();
const stateHash = engine.computeStateHash(out.nextState);
const auditHead = engine.audit.headHash();
console.log(policyId, stateHash, auditHead);

Invariant:

Same (engine version + modules + options + state + intent sequence) ⇒ identical policyId, stateHash, and auditHead.

No randomness. No hidden clocks (in strict mode). No non-deterministic ordering.

Design Philosophy

• Fail closed.
• Make invariants explicit.
• Make state portable.
• Make execution replayable.
• Separate identity from proof.
• Prefer deterministic containment over probabilistic detection.

Installation

npm install @oxdeai/core

Core Model

Agent / Runtime
↓
Structured Intent
↓
PolicyEngine (@oxdeai/core)
    → ALLOW + Authorization
    → DENY + Reasons
↓
Execution Layer (APIs / payments / infra provisioning)

Concepts

Intent

A structured economic action.

Examples:

• EXECUTE a paid tool call
• RELEASE an authorization-bound concurrency slot

State

Deterministic policy state containing:

• per-agent budgets
• per-action caps
• velocity windows
• replay nonce windows
• recursion depth caps
• concurrency caps + active authorizations
• tool amplification limits
• kill switches and allowlists

Authorization

If an intent is allowed, the engine emits a signed authorization:

• bound to intent_hash
• bound to policy_version
• bound to state_snapshot_hash
• includes expires_at
• verifiable via verifyAuthorization()

Example: Pure Evaluation

import { PolicyEngine } from "@oxdeai/core";
import type { State, Intent } from "@oxdeai/core";

const engine = new PolicyEngine({
  policy_version: "v0.6",
  engine_secret: process.env.OXDEAI_ENGINE_SECRET!,
  authorization_ttl_seconds: 60,
  strictDeterminism: false
});

const now = 1730000000; // injected timestamp (seconds)

const state: State = {
  policy_version: "v0.6",
  period_id: "2026-02",
  kill_switch: { global: false, agents: {} },
  allowlists: {},
  budget: { budget_limit: { "agent-1": 10_000n }, spent_in_period: { "agent-1": 0n } },
  max_amount_per_action: { "agent-1": 5_000n },
  velocity: { config: { window_seconds: 60, max_actions: 100 }, counters: {} },
  replay: { window_seconds: 3600, max_nonces_per_agent: 256, nonces: {} },
  recursion: { max_depth: { "agent-1": 2 } },
  concurrency: { max_concurrent: { "agent-1": 2 }, active: {}, active_auths: {} }
};

const intent: Intent = {
  agent_id: "agent-1",
  type: "EXECUTE",
  tool_call: true,
  tool: "openai.responses",
  nonce: 42n,
  amount: 100n,
  timestamp: now,
  depth: 0
};

const out = engine.evaluatePure(intent, state, { mode: "fail-fast" });

if (out.decision === "DENY") {
  console.error(out.reasons);
} else {
  // persist out.nextState
  // execute using out.authorization
}

Concurrency Lifecycle: RELEASE

RELEASE must reference a valid active authorization_id.

const releaseIntent: Intent = {
  agent_id: "agent-1",
  type: "RELEASE",
  authorization_id: out.authorization.authorization_id,
  nonce: 43n,
  amount: 0n,
  timestamp: now
};

const rel = engine.evaluatePure(releaseIntent, out.nextState);

Built-In Modules

• KillSwitchModule
• AllowlistModule
• ReplayModule
• RecursionDepthModule
• ConcurrencyModule
• ToolAmplificationModule
• BudgetModule
• VelocityModule

Determinism and Auditability

• Pure evaluation mode available
• Stable canonical JSON encoding
• BigInt normalization
• Sorted key hashing
• Hash-chained audit log
• Strict-mode clock injection
• Property-based determinism tests (seeded, no deps)

Snapshot API (v0.6)

import {
  PolicyEngine,
  encodeCanonicalState,
  decodeCanonicalState
} from "@oxdeai/core";

// 1. Export canonical snapshot
const snapshot = engine.exportState(state);
// 2. Encode to portable bytes (canonical JSON)
const bytes = encodeCanonicalState(snapshot);
// 3. Decode in another process/runtime
const decoded = decodeCanonicalState(bytes);
// 4. Import into fresh state container
const freshState = structuredClone(state);
engine.importState(freshState, decoded);
engine.computeStateHash(freshState); // identical to original

importState enforces formatVersion: 1 and rejects policy mismatches (policyId must match engine.computePolicyId()).

Snapshots are:

• Canonical JSON (no v8 serialization)
• Versioned (formatVersion: 1)
• Policy-bound (policyId must match)
• Deterministically hashed

Adapters (v0.8)

import { PolicyEngine, FileStateStore, FileAuditSink } from "@oxdeai/core";

const stateStore = new FileStateStore("./policy-state.bin");
const auditSink = new FileAuditSink("./audit.ndjson");

const engine = new PolicyEngine({
  policy_version: "v0.6",
  engine_secret: "secret",
  authorization_ttl_seconds: 60,
  stateStore,
  auditSink
});

const out = engine.evaluate(intent, state);
engine.commitState(state);
await engine.flushAudit();
await engine.flushState();

Core ships only minimal in-memory and file adapters; no redis/postgres adapters in core. Build those in separate packages.

Replay Verification (v0.7)

ReplayEngine.verify recomputes auditHeadHash offline from the provided events, and validates policy binding (policyId) plus non-decreasing timestamps.

Strict mode returns inconclusive unless the trace contains at least one STATE_CHECKPOINT (stateHash anchor).

import { PolicyEngine, ReplayEngine } from "@oxdeai/core";
const engine = new PolicyEngine({ policy_version: "v0.6", engine_secret: "secret", authorization_ttl_seconds: 60, checkpoint_every_n_events: 2 });
engine.evaluatePure(intent1, state);
const out = engine.evaluatePure(intent2, state);
const events = engine.audit.snapshot();
const verified = ReplayEngine.verify(events, { policyId: engine.computePolicyId() }); // strict by default
console.log(verified.ok, verified.status); // true, "ok" when checkpoints exist

Roadmap

v0.6 - Stateful Canonical Snapshots (shipped)

• State-bound module codecs (canonical JSON)
• Snapshot round-trip invariants (smoke + property tests)
• Versioned canonical snapshot format (formatVersion=1)
• Strict determinism completeness (no implicit entropy)

v0.7 - Replay as Verification (shipped)

• Replay verification API
• Optional deterministic state checkpoints (STATE_CHECKPOINT)
• Misuse hardening (strict => inconclusive without state anchors)

v0.8 - Host Integration Adapters (shipped)

• StateStore interface
• AuditSink interface
• Minimal in-memory + file adapters

License

Apache-2.0