Skip to content

ARVIS Intermediate Representation Specification v1

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here.

Status

  • Version: v1
  • Scope: Normative (Core)
  • Component: ARVIS Core / Interface Layer

1. Purpose

The ARVIS Intermediate Representation (IR) defines the canonical, deterministic, and versioned output of a cognitive execution.

The IR serves as:

  • the primary interface between ARVIS and external systems
  • the basis for audit, replay, and compliance
  • a machine-verifiable representation of a cognitive episode

Every ARVIS-compliant system MUST produce a valid IR.

IMPORTANT:

The IR is the single source of truth for all external representations of a cognitive execution.

The IR defines the canonical boundary between cognition and response construction. All downstream layers (conversation, linguistic, execution, interoperability) MUST derive strictly from the IR without modifying its semantics.

All interoperability layers (e.g. canonical signal systems) MUST derive exclusively from the IR.

2. Core Principles

2.1 Determinism

Given identical inputs, the IR MUST be identical:

  • same structure
  • same values
  • same ordering

2.2 Canonicalization

The IR MUST be normalized before exposure:

  • order-invariant
  • stable across executions
  • free of runtime artifacts

2.3 Replayability

The IR MUST allow:

  • deterministic replay
  • reconstruction of the decision path
  • verification of constraints

2.4 Separation of Layers

The IR system is composed of distinct layers:

  1. Constructed IR (from CognitiveIRBuilder)
  2. Normalized IR
  3. Validated IR
  4. Serialized IR
  5. Hashed IR
  6. Envelope (portable contract)

2.5 Separation from Interoperability Layers

The IR is independent from any external canonical signal system.

In particular:

  • the IR MUST NOT embed signal registry constraints
  • the IR MUST NOT be reduced to signal-based representations

Transformations such as:

IR → Canonical Signals

are handled by external projection layers (e.g. Kernel Adapter) and are:

  • deterministic
  • rule-based
  • lossy

The IR remains the authoritative representation.

External projections MAY introduce runtime metadata.

To ensure consistency, a projection MUST remain deterministically derivable from the source IR (the historical semantic-fingerprint mechanism left the tree with the kernel-adapter rule engine; the surviving consistency guarantees are the canonical serializer and the IR hash).

If origin is None, it MUST be normalized to a deterministic default value ("unknown").

Missing or undefined fields MUST be normalized to deterministic default values. These defaults MUST be explicitly defined and consistent across implementations.

2.6 Memory Influence Model

Memory is a kernel-managed subsystem.

During execution:

  • a deterministic memory snapshot is constructed
  • the snapshot is injected into the pipeline context (read-only)
  • cognition is influenced by this snapshot

However, the IR does not expose memory directly.

Instead, memory influences the IR through:

  • constraint shaping
  • preference shaping
  • context enrichment

The IR MUST only contain memory-derived projections, not memory itself.

This ensures:

  • Zero-Knowledge Cognitive System (ZKCS) compliance
  • deterministic replay
  • audit safety

Memory exposure is therefore:

Memory Repository
    ↓
Policy Filtering
    ↓
Memory Snapshot (internal)
    ↓
Cognitive Processing
    ↓
IR (filtered influence only)

---

## 3. Canonical IR Structure (v1)

The normative IR object is:

```yaml
CognitiveIR:
  input: CognitiveInputIR
  context: CognitiveContextIR
  decision: CognitiveDecisionIR
  state: CognitiveStateIR | null
  gate: CognitiveGateIR
  projection: object | null   (ProjectionIRAdapter payload)
  validity: object | null     (ValidityIRAdapter payload)
  stability: object | null    (StabilityIRAdapter payload)
  adaptive: object | null     (AdaptiveIRAdapter payload)
  tools: list[dict] | null    (ToolResult-shaped entries, see below)

4. IR Construction Pipeline

The IR MUST be built through the canonical pipeline:

CognitiveIRBuilder
→ CognitiveIRNormalizer
→ CognitiveIRValidator
→ CognitiveIRSerializer
→ CognitiveIRHasher
→ CognitiveIREnvelope

Each step is mandatory for full compliance.

5. Component Definitions

5.1 Input

Represents the originating interaction.

MUST include:

  • input_id
  • actor_id
  • surface_kind
  • metadata

5.2 Context

Represents execution context.

MUST include:

  • user_id
  • session_id (if available)
  • conversation_mode (if applicable)
  • memory-derived constraints and preferences (normalized, projection-safe)
  • execution context hints
  • additional deterministic context fields (normalized)

IMPORTANT:

The IR context MUST NOT contain raw memory entries.

Memory is a kernel-managed subsystem and is accessed during execution through a memory snapshot.

Only the following may appear in IR context:

  • normalized constraints derived from memory
  • preference signals derived from memory
  • policy-approved memory influence

The IR MUST NOT expose:

  • raw memory entries
  • memory values or content
  • repository-level data structures

5.3 Decision

Represents structured decision semantics.

MUST include:

  • decision_id
  • decision_kind
  • memory_intent
  • reason_codes
  • structured decision components (actions, gaps, conflicts)

5.4 State

Represents canonical cognitive state.

Derived from:

  • CognitiveStateBuilder
  • CognitiveStateContract

MAY be null if unavailable.

5.5 Gate

Represents final decision validation.

MUST include:

  • verdict ∈ {ALLOW, REQUIRE_CONFIRMATION, ABSTAIN}
  • bundle_id
  • reason_codes

5.6 Stability (Optional)

Represents projected stability state.

5.7 Adaptive (Optional)

Represents adaptive control snapshot.

5.8 Tools ( Runtime Execution Layer)

Represents tool execution results associated with the cognitive episode.

Properties: - MUST be deterministic - MUST reflect actual runtime execution - MUST NOT influence decision semantics

IMPORTANT:

Tool results are attached to the IR, but are not part of the decision computation.

They are:

  • post-decision
  • non-causal
  • replay-observable only

Structure:

Each tools entry (a plain dict in CognitiveIR.tools, built from the ToolResult fields): tool_name: str success: bool output: Any | null error: str | null latency_ms: float | null

6. Normalization

The IR MUST be normalized before validation.

Normalization MUST ensure:

  • sorted reason_codes
  • deterministic ordering of collections
  • stable mapping ordering
  • semantic equivalence → structural equivalence

7. Validation

The IR MUST pass validation before serialization.

Validation enforces:

  • schema integrity
  • type correctness
  • cross-field consistency

8. Serialization

The IR MUST be serialized deterministically.

Example:

serialized = CognitiveIRSerializer.serialize(ir)

9. Hashing

The IR MUST support deterministic hashing:

hash = CognitiveIRHasher.hash(ir)

Rules:

  • identical IR → identical hash
  • normalization required before hashing

10. Envelope

The IR MUST be embeddable in an envelope:

CognitiveIREnvelope:
  ir: CognitiveIR
  serialized: string
  hash: string

The envelope is the portable IR contract.

11. Invariants

The IR MUST satisfy:

  • no hidden state
  • full determinism
  • consistency between gate and decision
  • MUST be fully derived from validated Gate output
  • MUST NOT be modified by downstream layers
  • reason_codes reflect triggered conditions
  • normalized IR is idempotent
  • the IR MUST preserve all semantically relevant information produced by the pipeline
  • memory influence MUST be projection-safe and ZKCS-compliant
  • IR MUST NOT leak raw memory content

12. Replay Requirements

The IR MUST support replay:

pipeline.run_from_ir(ir)

Replay MUST produce:

  • identical verdict
  • identical reason_codes
  • identical IR after normalization
  • independence from runtime execution order
  • independence from scheduler behavior

Memory Replay Semantics

Memory is time-dependent and must not be recomputed during replay.

Therefore:

  • the memory snapshot used during execution MUST be considered part of the execution context
  • replay MUST rely on journaled memory exposure
  • replay MUST NOT recompute memory state dynamically

This ensures:

  • strict determinism
  • audit reproducibility
  • temporal consistency of memory influence

13. Compatibility Rules

Minor updates

  • new optional fields allowed
  • no semantic change

Major updates

  • version bump required
  • breaking changes documented

14. Compliance Requirements

An implementation is IR-compliant if:

  • IR is normalized
  • IR is validated
  • serialization is deterministic
  • hashing is stable
  • replay is consistent

If external projection layers are implemented:

  • they MUST use the IR as input
  • they MUST NOT alter IR semantics
  • they MUST remain deterministic and side-effect free

Conversation and linguistic layers MUST: - derive strictly from IR - NOT alter IR semantics

15. Forbidden Practices

The system MUST NOT:

  • produce non-normalized IR
  • skip validation
  • generate non-deterministic ordering
  • include hidden runtime state
  • mutate IR after hashing
  • expose raw memory entries in IR
  • recompute memory during replay

16. Future Extensions (Non-Normative)

  • timeline integration
  • multi-agent IR
  • probabilistic annotations
  • extended audit metadata