@holoscript/uaal

uAAL — Universal Autonomous Agent Language Virtual Machine.
Stack-based bytecode execution engine for the uAA2++ 7-Phase Protocol.

Quick Start

import { UAALVirtualMachine, UAALCompiler, UAALOpCode } from '@holoscript/uaal';

const vm = new UAALVirtualMachine();
const compiler = new UAALCompiler();

// Build a full 7-phase cognitive cycle
const bytecode = compiler.buildFullCycle('Analyze the market data');
const result = await vm.execute(bytecode);
// result.taskStatus === 'HALTED'

Custom Handlers

The registerHandler() API is the extension point. Your private services inject logic without modifying the VM core:

vm.registerHandler(UAALOpCode.OP_INVOKE_LLM, async (proxy, operands) => {
  const result = await myLLMService.call(operands[0] as string);
  proxy.push(result);
});

Semantic Harness

@holoscript/uaal/semantic exposes the pure structural gates used by the uAAL v2 corpus work. Agents can consume these functions without the private corpus generator or receipt CLI:

import {
  benchmarkAffordance,
  benchmarkAnalogy,
  benchmarkComposition,
  benchmarkCounterfactual,
  benchmarkMereology,
  benchmarkMotif,
  benchmarkPresupposition,
  benchmarkTension,
  benchmarkTheoryOfMind,
  recoverFalseBelief,
} from '@holoscript/uaal/semantic';

const recovery = recoverFalseBelief(ir);
const gate = benchmarkTheoryOfMind([{ completion: JSON.stringify(ir), metadata }]);
// gate.pass === true when belief, perspective, causal, and falsification checks hold

The harness covers theory-of-mind false belief, beneficiary reachability/telos, agent-relative containment/occlusion, body-relative affordance, temporal stale-vs-error separation, deontic force, commitment discharge, counterfactual necessity, per-modality sensory access, world composition, mereological persistence, narrative tension, cross-graph analogy, presupposition projection, and thematic motif recurrence. Private corpus generation, held-out generalization, and producibility receipts stay outside the npm package; the public subpath exports the pure recognizers and benchmark gates.

Semantic Gate

@holoscript/uaal/gate is the public falsifiable spec for uAAL v2 semantic IR well-formedness. It checks referential integrity, perception-grounding, multi-perspective interiority, and causal acyclicity while reporting theory-of-mind richness metrics. It does not expose private corpus generator templates:

import { semanticGate } from '@holoscript/uaal/gate';

const result = semanticGate(ir);
// result.pass === true when the IR is structurally grounded

The split is intentional: publish the gate/spec so outside agents can verify IR, keep the generator/data recipe private so held-out generalization cannot be overfit from public templates.

7-Phase Protocol

| Phase | OpCode | Purpose | | ----------- | ------ | ----------------------------------------------------------------- | | 0. INTAKE | 0x10 | Gather data and context | | 1. REFLECT | 0x11 | Analyze and understand | | 2. EXECUTE | 0x14 | Take action | | 3. COMPRESS | 0x12 | Store knowledge efficiently | | 4. DREAMING | 0x15 | Validate and re-evaluate compressed knowledge (REINTAKE opcode) | | 5. GROW | 0x16 | Learn patterns, wisdom, gotchas | | 6. EVOLVE | 0x17 | Adapt and optimize |

Scripts

npm run test    # Run tests
npm run build   # Build to dist/
npm run dev     # Watch mode

Package boundary & release posture

npm install @holoscript/uaal

This package targets external agent frameworks and operator/founder teams embedding the uAA2++ 7-Phase Protocol VM in their own runtime — not just the core team. registerHandler() is caller-owned: point it at your own model calls, retrieval service, or storage backend; the VM core ships no default provider and reads no environment variables on your behalf.

This package does not ship the private corpus generator, held-out generalization harness, or producibility-receipt CLI — those stay in the founder-local research workspace outside this package boundary. Only the pure UAALVirtualMachine/UAALCompiler core, the /semantic benchmark recognizers, and the /gate structural validator are published.

Release posture: v0-preview. The bytecode opcode set and semantic-gate scoring are still evolving; known limitations include no persisted VM state across process restarts and no built-in rollback for registerHandler side effects — callers are responsible for their own handler idempotency.