📖 Overview v1.0

The ICore API exposes constitutional interfaces for every layer of the ICore computing platform. Each API layer maps to a specification module and governs how components communicate under constitutional constraint.

Constitutional Architecture

/* ICore Layer Architecture */
┌─────────────────────────────────────────────┐
│  USDS  — Unforgeable Secure Distribution    │
├─────────────────────────────────────────────┤
│  UCA   — Unified Constraint Adapter        │
├─────────────────────────────────────────────┤
│  UCN   — Universal Constitutional Network   │
├─────────────────────────────────────────────┤
│  UWA   — Universal Workspace Adapter       │
├─────────────────────────────────────────────┤
│  USR   — Universal Sovereign Runtime       │
└─────────────────────────────────────────────┘

Core Principles

✅ Conformance Tests 50 Tests

All 50 conformance tests validate that an ICore implementation satisfies the constitutional requirements of each API layer.

⚙️ USR API 6 Engines

The Universal Sovereign Runtime provides the foundational execution layer. Every component runs within a sovereign USR context governed by constitutional constraint.

Identity Engine

Manages unforgeable identity declaration and verification for all entities.

// Declare a new constitutional identity
const identity = await usr.identity.declare({
  "entity": "com.example.service",
  "publicKey": "ed25519:...",
  "capabilities": ["execute", "attest"]
});

// Register the identity in the constitutional ledger
const registered = await usr.identity.register(identity);

// Verify an identity's authenticity
const valid = await usr.identity.verify(identity.id);

Execution Engine

Executes constitutional operations with full attestation and constraint enforcement.

// Execute a constitutional operation
const result = await usr.execution.execute({
  "operation": "process",
  "input": { "data": payload },
  "constraints": ["max-gas:1000"]
});

// Retrieve execution history
const history = await usr.execution.getHistory(result.contextId);

Constraints Engine

Enforces constitutional constraints on all operations within the runtime.

// Enforce a constraint on an operation
await usr.constraints.enforce({
  "target": operationId,
  "constraint": "no-network-access",
  "violation": "halt"
});

// Test if an operation would violate constraints
const safe = await usr.constraints.test(operationId);

Isolation Engine

Manages capability-based isolation between constitutional contexts.

// Request a capability from the constitutional authority
const cap = await usr.isolation.requestCapability({
  "entity": identity.id,
  "resource": "storage.write",
  "scope": "namespace:alpha",
  "ttl": 3600
});

// Revoke a previously granted capability
await usr.isolation.revokeCapability(cap.id);

// Check if a capability is currently active
const active = await usr.isolation.checkCapability(cap.id);

Attestation Engine

Creates and verifies cryptographic attestations for constitutional operations.

// Create an attestation for a completed operation
const att = await usr.attestation.attest({
  "operationId": result.contextId,
  "statement": "Operation completed within constitutional bounds",
  "signer": identity.id
});

// Verify a single attestation
const valid = await usr.attestation.verify(att.id);

// Verify an entire chain of attestations
const chainValid = await usr.attestation.verifyChain(att.chainId);

Orchestration Engine

Manages the lifecycle of constitutional processes and inter-process messaging.

// Start a new constitutional process
const proc = await usr.orchestration.start({
  "template": "data-pipeline",
  "identity": identity.id,
  "config": { "maxSteps": 100 }
});

// Suspend a running process
await usr.orchestration.suspend(proc.id);

// Resume a suspended process
await usr.orchestration.resume(proc.id);

// Terminate a process
await usr.orchestration.terminate(proc.id);

// Send an inter-process message
await usr.orchestration.sendMessage(proc.id, {
  "type": "data",
  "payload": result
});

🧩 UWA API 5 Engines

The Universal Workspace Adapter manages component lifecycle, event handling, and workspace composition under constitutional governance.

Component Engine

Full lifecycle management for workspace components — from declaration to termination.

// Create and declare a workspace component
const comp = await uwa.component.create({
  "type": "transformer",
  "config": { "input": "stream-a" }
});

await uwa.component.declare(comp.id, {
  "capabilities": ["read", "write"],
  "constraints": ["no-network"]
});

// Validate against constitutional rules
await uwa.component.validate(comp.id);

// Full lifecycle
await uwa.component.initialize(comp.id);
await uwa.component.start(comp.id);
await uwa.component.suspend(comp.id);
await uwa.component.resume(comp.id);
await uwa.component.terminate(comp.id);

Event Engine

Constitutional event emission and consumption within workspace boundaries.

// Emit a constitutional event
await uwa.event.emit({
  "type": "data.ready",
  "source": comp.id,
  "payload": { "count": 42 }
});

// Consume events matching a pattern
const events = await uwa.event.consume({
  "pattern": "data.*",
  "limit": 10
});

Execution Engine

Executes workspace operations with constraint awareness.

// Execute a workspace operation
const result = await uwa.execution.execute({
  "operation": "transform",
  "target": comp.id,
  "input": events
});

Composition Engine

Manages the DAG of workspace components and their constitutional relationships.

// Compose components via directed edges
await uwa.composition.addEdge({
  "from": compA.id,
  "to": compB.id,
  "constraint": "data-flow"
});

// Get downstream components
const children = await uwa.composition.getChildren(compA.id);

// Validate entire composition graph
await uwa.composition.validate();

Workspace Runtime

High-level interface for workspace operations combining all engines.

// High-level workspace runtime API
const component = await uwa.runtime.createComponent(config);
await uwa.runtime.executeEvent(component.id, event);
await uwa.runtime.compose(components);
const status = await uwa.runtime.getStatus();

🌐 UCN API 6 Engines

The Universal Constitutional Network governs node creation, discovery, communication, synchronization, and trust across distributed constitutional participants.

Node Engine

Creates and manages constitutional network nodes with lifecycle control.

// Create a new constitutional network node
const node = await ucn.node.createNode({
  "identity": identity.id,
  "capabilities": ["relay", "store"],
  "network": "primary"
});

// Extend the network with new nodes
await ucn.node.extendNetwork("primary", [node.id]);

// Activate the network
await ucn.node.activateNetwork("primary");

// Revoke a node
await ucn.node.revoke(node.id);

Discovery Engine

Constitutional service discovery and advertisement.

// Advertise a constitutional service
await ucn.discovery.advertise({
  "service": "data-transform",
  "node": node.id,
  "constraints": ["max-connections:10"]
});

// Query for available services
const services = await ucn.discovery.query({
  "type": "data-transform"
});

Communication Engine

Constitutional event creation and verification across nodes.

// Create a network event
const event = await ucn.communication.createEvent({
  "type": "data.sync",
  "from": nodeA.id,
  "to": nodeB.id,
  "payload": data
});

// Verify event authenticity
const verified = await ucn.communication.verifyEvent(event.id);

Sync Engine

Distributed state synchronization with constitutional integrity.

// Initialize shared state
await ucn.sync.initState("shared-doc", initialState);

// Create a state delta
const delta = await ucn.sync.createDelta("shared-doc", changes);

// Apply a delta to local state
await ucn.sync.applyDelta("shared-doc", delta);

// Merge conflicting deltas
const merged = await ucn.sync.mergeDelta("shared-doc", deltaA, deltaB);

Trust Engine

Constitutional trust anchors and transitive trust chain verification.

// Add a trust anchor (root of trust)
await ucn.trust.addAnchor({
  "identity": rootIdentity.id,
  "level": "constitutional"
});

// Assert trust in another entity
await ucn.trust.assertTrust({
  "from": nodeA.id,
  "to": nodeB.id,
  "scope": "communication"
});

// Revoke trust
await ucn.trust.revokeTrust(nodeA.id, nodeB.id);

// Verify trust chain between two entities
const trusted = await ucn.trust.verifyChain(nodeA.id, nodeB.id);

Network Runtime

High-level interface for network operations.

// Join a constitutional network
await ucn.runtime.joinNetwork({
  "network": "primary",
  "identity": identity.id,
  "bootstrap": ["node://seed-1"]
});

// Get network status
const status = await ucn.runtime.getStatus();

🔌 UCA API 7 Engines

The Unified Constraint Adapter manages adapter registration, naming, serialization, and boundary operations across constitutional domains.

Adapter Engine

Registration and lifecycle management for constraint adapters.

// Register a constraint adapter
await uca.adapter.register({
  "name": "json-v2",
  "type": "serialization",
  "handler": jsonHandler
});

// Replace an existing adapter
await uca.adapter.replace("json-v1", "json-v2");

// Unregister an adapter
await uca.adapter.unregister("json-v2");

Naming Engine

Constitutional name resolution and mapping verification.

// Register a name mapping
await uca.naming.registerMapping({
  "name": "storage.alpha",
  "target": storageEngine.id,
  "constraints": ["read-only"]
});

// Resolve a name to its target
const target = await uca.naming.resolve("storage.alpha");

// Verify a mapping is valid
const valid = await uca.naming.verify("storage.alpha");

Serialization Engine

Constitutional serialization with roundtrip integrity verification.

// Serialize with constitutional integrity
const bytes = await uca.serialization.serialize({
  "data": complexObject,
  "format": "cbor",
  "sign": true
});

// Deserialize with verification
const obj = await uca.serialization.deserialize(bytes);

// Verify roundtrip integrity
const intact = await uca.serialization.verifyRoundtrip(bytes);

Execution Adapter

Cross-domain execution with sandbox enforcement and resource tracking.

// Execute with adapter constraints
const result = await uca.execution.execute({
  "adapter": "sandbox-adapter",
  "operation": computeTask
});

// Check sandbox boundaries
const safe = await uca.execution.sandboxCheck(result.contextId);

// Get resource consumption report
const report = await uca.execution.resourceReport(result.contextId);

Storage Adapter

Constitutional storage with integrity verification.

// Store data with constitutional integrity
const ref = await uca.storage.store({
  "data": document,
  "namespace": "alpha",
  "encrypt": true
});

// Retrieve data
const data = await uca.storage.retrieve(ref.id);

// Verify storage integrity
const intact = await uca.storage.verifyIntegrity(ref.id);

Communication Adapter

Cross-boundary communication with source verification.

// Send a message across boundaries
await uca.communication.send({
  "to": "namespace:beta",
  "message": crossDomainData,
  "signed": true
});

// Verify message source authenticity
const authentic = await uca.communication.verifySource(messageId);

Boundary Runtime

High-level boundary management interface.

// Get boundary adapter status
const status = await uca.runtime.getStatus();
// → { adapters: 7, active: 5, violations: 0 }

📦 USDS API 4 Engines

The Unforgeable Secure Distribution System handles constitutional package creation, signing, distribution, and verification.

Package Engine

Creates and extracts unforgeable constitutional packages.

// Create a constitutional package
const pkg = await usds.package.create({
  "contents": componentBundle,
  "metadata": {
    "name": "transformer-v1",
    "version": "1.0.0"
  },
  "constraints": ["read-only"]
});

// Extract a package
const contents = await usds.package.extract(pkg.id);

Signing Engine

Constitutional cryptographic signing and verification.

// Sign a package
const sig = await usds.signing.sign({
  "packageId": pkg.id,
  "signer": identity.id,
  "algorithm": "ed25519"
});

// Verify a signature
const valid = await usds.signing.verify(sig.id);

Distribution Engine

Secure transfer and tracking of constitutional packages.

// Transfer a package to a recipient
const tx = await usds.distribution.transfer({
  "packageId": pkg.id,
  "recipient": recipientNode.id,
  "encrypted": true
});

// Track distribution status
const status = await usds.distribution.track(tx.id);

Verification Engine

Verifies package integrity and trust chains.

// Verify a single package
const valid = await usds.verification.verify(pkg.id);

// Verify the entire chain of custody
const chainValid = await usds.verification.verifyChain(pkg.id);
// → { valid: true, signatures: 3, attestations: 7 }

⚡ Quick Reference All Methods

Complete method signatures for every engine across all API layers.

USR — Universal Sovereign Runtime

UWA — Universal Workspace Adapter

UCN — Universal Constitutional Network

UCA — Unified Constraint Adapter

USDS — Unforgeable Secure Distribution System