Proof-Physics

JSONFlow Physics Runtime — Deterministic Causal State Transformation System

Reality as Code, Code as Reality.

Quick Start

npm install proof-physics
npm start -- run examples/particle.js --ticks=50
npm start -- run examples/economy.js --ticks=10

What is Proof-Physics?

A Universe is a deterministic simulation engine with four parts:

| Component | Purpose | |-----------|---------| | initialState | S₀ — the starting state | | transitions | JSONFlow operations applied each tick | | constraints | Physical laws (invariants) | | observe(fn) | Non-mutating state projections |

Every universe is SOVEREIGN OMEGA VERIFIED — guaranteed deterministic, replayable, causal, and law-abiding.

Core Concepts

Deterministic State Machines

Every tick, transitions are applied to produce a new state. Same initial state → same final state, always.

import { Universe, op } from 'proof-physics';

const u = new Universe({
  initialState: { counter: 0 },
  transitions: [
    op.set('counter', op.binop('+', op.ref('counter'), 1)),
  ],
});

u.run(10);
console.log(u.state.counter); // 10 ✓ (deterministic)

Physical Laws via Constraints

Constraints are invariants—properties that must hold at every tick. Break a constraint → universe halts.

constraints: [
  constraint('never negative', state => state.balance >= 0),
  constraint('conservation', state =>
    state.agents.reduce((sum, a) => sum + a.wealth, 0) === 1000
  ),
]

Causal Ordering

Transitions automatically form a Directed Acyclic Graph (DAG) of causality. No cycles, no time-travel paradoxes.

  Tick 0 → Tick 1 → Tick 2 → ...
           /|\       /|\
          / | \     / | \
   Transition nodes form acyclic dependency graph

The 7 JSONFlow Operators

All transitions are built from these 7 primitives:

1. SET — Field Assignment

op.set('agent.health', 80)                    // literal
op.set('counter', op.ref('counter'))          // reference
op.set('x', op.binop('+', op.ref('x'), 5))   // expression

2. IF — Conditional Branch

op.if(
  op.binop('>', op.ref('health'), 0),
  [op.set('alive', true)],  // then
  [op.set('alive', false)]  // else
)

3. WHILE — Bounded Loop

op.while(
  op.binop('>', op.ref('remaining'), 0),
  [
    op.set('sum', op.binop('+', op.ref('sum'), op.ref('value'))),
    op.set('remaining', op.binop('-', op.ref('remaining'), 1)),
  ]
)

Max iterations: 100,000 (prevents infinite loops)

4. FOREACH — Array Iteration

op.foreach(
  op.ref('agents'),      // collection
  'agent',               // iterator variable
  [op.set('agent.tick', op.ref('agent.tick') + 1)]
)

5. PARALLEL — Independent Concurrent Operations

op.parallel(
  op.set('x', 10),
  op.set('y', 20),
  op.set('z', 30)
)
// ✓ No conflicts — all three write different fields
// ✗ Would fail if two ops wrote to same field

6. RETURN — Early Exit

op.return(value)  // return from current block

7. NO-OP — Identity

op.noop()  // does nothing (identity morphism)

Expression Language

All expressions evaluate against the current state:

op.ref('field.path')                    // field reference: "agent.health"
op.binop('+', left, right)              // operators: + - * / % ** == != < <= > >= && ||
op.ternary(cond, thenExpr, elseExpr)    // ternary: ? :
op.call('Math.floor', value)            // built-ins: Math, Number, String, Boolean, JSON
42 / "string" / true / null             // literals

Examples

Example 1: Particle Physics

Classical projectile motion with bounce:

pp run examples/particle.js --ticks=50

State: { particle: { x, y, vx, vy } }
Transitions: Euler integration + bounce collision
Constraints: y ≥ 0 (no phasing through ground)

Example 2: Multi-Agent Economy

Three traders with money conservation law:

pp run examples/economy.js --ticks=10

State: Array of agents with { id, balance, goods }
Transitions: Dynamic per-tick trades (if balance ≥ price)
Constraints: Total money must always be $300

Verification & Proof

Every universe can be verified:

const v = u.verify();
// {
//   sovereign_omega_verified: true,
//   deterministic: true,
//   replayable: true,
//   hashConsistent: true,
//   causalDAGValid: true,
//   genesisHash: "abc123...",
//   currentHash: "def456...",
//   merkleRoot: "ghi789...",
//   ticks: 50,
//   dag: { nodes: 243, edges: 187 }
// }

Five Verification Properties

1. Deterministic — Same inputs → same outputs
2. Replayable — Can reconstruct from snapshot
3. Hash-Consistent — Every state has stable hash
4. Causally Valid — No cycles in transition DAG
5. Law-Abiding — All constraints satisfied at every step

CLI Usage

# Run evolution
pp run <universe.js> [--ticks=N]

# Check integrity
pp verify <universe.js>

# Prove determinism by replaying
pp replay <universe.js> [--ticks=N]

# Show performance metrics
pp metrics <universe.js> [--ticks=N]

# Inspect state and history
pp examine <universe.js>

# Show examples
pp library

# License info
pp license

# Help
pp help

Project Structure

src/
  index.js         Public API + fluent DSL (op, constraint helpers)
  universe.js      Universe class (tick engine, verification)
  transitions.js   JSONFlow primitive executor (all 7 ops)
  expr.js          Expression evaluator ($ref, $op, $if, $call)
  dag.js           CausalDAG builder + cycle verifier
  hash.js          FNV-1a hashing + Merkle root
  cli.js           Command-line interface

examples/
  particle.js      Classical mechanics
  economy.js       Agent-based economy

Architecture: The Tick Engine

Each tick:

1. Fetch transitions for this tick (static or dynamic)
2. Pre-check constraints — abort if violated
3. Execute all transitions against current state (cloned)
4. Post-check constraints — enforce physical laws
5. Record state hash and history
6. Advance tick counter

State (S_n) ──→ [Clone] ──→ [Execute Transitions] ──→ [Check Constraints] ──→ Hash ──→ S_(n+1)

Determinism Guarantee

Proof-Physics is deterministic because:

• ✓ All floating-point operations are reproducible
• ✓ State is cloned before mutation (no hidden state)
• ✓ Transitions have no side effects (pure functions)
• ✓ No randomness (unless explicitly seeded)
• ✓ No timing dependencies
• ✓ No external I/O during ticks

Result: Replay any universe from genesis and get identical hash.

License

Dual-Licensed:

• Open Source: GNU GPL v3.0 (free, community-friendly)
• Commercial: Proprietary license available (no GPL restrictions)

See LICENSE.md for details and commercial licensing.

Copyright © 2026 James Chapman
Contact: [email protected]

Performance

On modern hardware (single-threaded Node.js):

| Scenario | Ticks | Time | Rate | |----------|-------|------|------| | Particle (simple state) | 1000 | ~50ms | 20k ticks/sec | | Economy (multi-agent) | 100 | ~5ms | 20k ticks/sec | | Complex (many transitions) | 10 | ~1ms | 10k ticks/sec |

Throughput is mainly limited by JSON serialization (for hashing).

Limitations & Future

Current:

• Single-threaded (no parallel tick execution)
• JSON-only state (no custom objects or functions)
• Max WHILE iterations: 100,000 (prevents hangs)

Future ideas:

• Worker thread parallelization for independent transitions
• Time-travel snapshots (rewind to any tick)
• Distributed consensus (multi-node replay verification)
• Web UI for state visualization

Contributing

Contributions welcome! Before submitting PRs:

1. Test with npm test
2. Ensure pp verify passes your examples
3. Add tests for new operators
4. Document your changes

By contributing, you agree to license your work under both GPL v3.0 and the Commercial License.

FAQ

Q: Can I use this in a closed-source product?
A: Yes, with a Commercial License. Email [email protected]

Q: How is this different from Redux/Vuex?
A: Proof-Physics guarantees determinism and replayability by design. Constraints are first-class. Causal DAGs are tracked. No side effects possible.

Q: Can I add randomness?
A: Yes, if seeded deterministically. Pass a PRNG to the Universe and use it in transitions.

Q: What's the maximum tick count?
A: Theoretically unlimited. History grows O(n) in ticks. For 1M ticks, expect ~100MB memory.

References

• Deterministic simulation: https://en.wikipedia.org/wiki/Deterministic_simulation
• DAG causality: https://en.wikipedia.org/wiki/Directed_acyclic_graph
• Merkle trees: https://en.wikipedia.org/wiki/Merkle_tree
• Constraint programming: https://en.wikipedia.org/wiki/Constraint_programming

Last Updated: January 2026
Version: 1.0.2
Status: Production-Ready