Skip to content

AlanGrid/Profit.OS

BranchesTags

Repository files navigation

Profit.OS

Profit.OS is a liquidity-aware portfolio operating system designed to coordinate capital allocation, risk, and execution.

Profit.OS is an operating system for investing rather than another trading bot. Its purpose is to assemble independent AI components into a deterministic execution pipeline where each layer has a single responsibility. Intelligence comes from structured evaluation, memory, governance, and execution — not from any individual model.

Architecture

Profit.OS
│
├── RC-1 Execution Kernel (Frozen)
│   ├── State Machine (PLAN → EXECUTE → ACTIVE → EXIT → DONE)
│   ├── Journal (append-only, durable)
│   ├── Recovery (deterministic, from journal)
│   ├── Risk Engine (position sizing, exposure limits)
│   ├── Execution Firewall (blocks execute on WATCH/REJECT)
│   └── Read Model (state projection from journal)
│
├── Journal
│   └── journal.jsonl (append-only event log)
│
├── Read Models
│   ├── read-model.ts (state projection)
│   ├── analytics.ts (performance metrics)
│   ├── equity-curve-reducer.ts (P&L progression)
│   └── trade-aggregate.ts (trade lifecycle)
│
├── RC-2 AI Integration Layer
│   ├── REST (9 endpoints: state, journal, positions, analytics, equity, mcp/tools, mcp/resources, mcp/call, scanner/watchlist)
│   ├── WebSocket (/ws/ai for real-time state subscriptions)
│   ├── MCP (6 tools: read_positions, read_journal, read_analytics, read_equity_curve, read_trade, read_state; 3 resources: state, journal, analytics)
│   └── Assistant Adapters (ChatGPT, Claude, Sider)
│
├── Terminal UI
│   ├── rsky_trade.html (single-page trading terminal)
│   ├── DOM semantic attributes (data-* on all interactive elements)
│   └── Localhost serving (http://localhost:8787)
│
└── Documentation
    ├── RC1_GATE1_ACCEPTANCE.md
    ├── 2026-07-19_RC1_COMPLETION_SUMMARY.md
    ├── 2026-07-20_RC2_ALPHA_ACCEPTANCE.md
    ├── RC2_IMPLEMENTATION_INDEX.md
    ├── RC2_ROADMAP.md
    ├── BUILD_TAGS.md
    ├── ARCHITECTURAL_DECISION_REMOVABILITY.md
    ├── CONSTRAINT_AI_INTEGRATION_ISOLATION.md
    └── RC2_REMOVABILITY_RULE.md

Core Invariant

The execution engine is deterministic and independently testable. All AI capabilities are removable observer layers. Removing the AI Layer must not change execution behavior.

RC-1 Execution Kernel (Frozen)

The RC-1 execution kernel is locked and frozen. No modifications are permitted.

Validated:

  • 200/200 automated tests passing
  • 30 consecutive outcome-blind dust trades with zero execution defects
  • Post-restart verification (clean state, correct recovery)
  • Journal durability verified via mid-process kill testing

Build Tag: v0.2.0-rc1-passed (immutable)

Components:

  • kernel.ts — State machine (PLANNING → PLANNED → ACTIVE → REVIEWING → CLOSED/CANCELLED)
  • write-event.ts — Journal append (append-only, durable)
  • read-model.ts — State projection from journal events
  • execution-policy.ts — Classification rules (EXECUTE/WATCH/REJECT)
  • execution-firewall.test.ts — Blocks execute on WATCH/REJECT
  • position-sizing.ts — Risk-based position calculation
  • risk-engine.ts — Exposure limits and portfolio constraints
  • analytics.ts — Performance metrics (win rate, expectancy, R-multiples)
  • equity-curve-reducer.ts — Realized P&L progression
  • trade-aggregate.ts — Trade lifecycle aggregation

RC-2 AI Integration Layer

The AI Integration Layer provides read-only access to trade data for external AI assistants. All components are observers only — they cannot write to the journal, modify execution state, or influence trade decisions.

Build Tag: v0.2.0-rc1-passed-ai-alpha

Components:

  • ai-layer/types.ts — Read-only view types for AI consumption
  • ai-layer/adapter.ts — AssistantAdapter interface + BaseAssistantAdapter
  • ai-layer/websocket.ts — Real-time state broadcast via WebSocket
  • ai-layer/mcp-server.ts — MCP protocol tools + resources
  • ai-layer/dom-semantics.ts — DOM scanning utilities
  • ai-layer/index.ts — Barrel re-exports

Adapters:

  • ChatGPTAdapter — ChatGPT Browser Agent
  • ClaudeAdapter — Claude Browser Integration
  • SiderAdapter — Sider / Claw

REST Endpoints:

  • GET /api/state — Full application state snapshot
  • GET /api/journal — Trade journal (filterable)
  • GET /api/positions — Open positions
  • GET /api/analytics — Performance analytics
  • GET /api/equity — Equity curve data
  • GET /api/scanner — Scanner output
  • GET /api/watchlist — Watchlist
  • GET /api/mcp/tools — MCP tool definitions
  • GET /api/mcp/resources — MCP resource definitions
  • POST /api/mcp/call — Execute MCP tool call

WebSocket:

  • /ws/ai — Real-time state subscriptions (polling interval: 2s)

MCP Tools:

  • read_positions — Read open positions
  • read_journal — Read trade journal
  • read_analytics — Read performance analytics
  • read_equity_curve — Read equity curve
  • read_trade — Read specific trade by ID
  • read_state — Read full state snapshot

Execution Isolation

The execution firewall is a hard architectural boundary:

Layer 3: External Observer (AI, dashboards, advisory)
Layer 2: Deterministic Classifier (rule-based, config-driven)
Layer 1: Execution Firewall (stateless, journal-reading)
Layer 0: RC-1 Kernel (locked, stress-tested, AI-free)

Rules:

  1. AI systems are never called from Layer 0 (RC-1 kernel)
  2. AI systems are never called from Layer 1 (firewall)
  3. AI systems are never called from Layer 2 (deterministic classifier)
  4. If AI systems fail, execution continues normally
  5. No AI decisions stored in journal (only deterministic classifier output)

Build Lineage

Build Tag Status Date Description
v0.2.0-rc1-passed LOCKED 2026-07-19 RC-1 Gate 1 Acceptance (30/30 trades, 200/200 tests)
v0.2.0-rc1-passed-ai-alpha ACTIVE 2026-07-20 AI Integration Layer Alpha (read-only)

Directory Structure

profit.os/
├── README.md                          # This file
├── LICENSE                            # License
├── .gitignore                         # Git ignore rules
├── profit.os.code-workspace           # VS Code workspace
├── rsky_trade_operators_manual.docx   # Operator manual
│
├── claude/                            # Claude memory system
│   ├── input/                         # Input data
│   │   ├── tools/                     # Code and tools
│   │   │   ├── rsky.terminal/         # Execution kernel + AI layer
│   │   │   ├── rsky.pattern.lib/      # Pattern library
│   │   │   └── cc.prompt.lib/         # Prompt library
│   │   └── img/                       # Images
│   ├── output/                        # Documentation output
│   │   ├── mrb/                       # MRB reports
│   │   └── *.md                       # Acceptance reports, roadmaps, etc.
│   ├── skills/                        # Claude skills
│   ├── mem0/                          # Mem0 memory system
│   └── temp/                          # Temporary files
│
├── docs/                              # Architecture documentation
│   ├── enforcement-kernel.md
│   ├── insight-compiler.md
│   ├── memory-policy.md
│   ├── pipeline.md
│   └── verifier.md
│
└── diagrams/                          # Architecture diagrams
    ├── profit-os-architecture.png
    ├── equity.curve.png
    └── active.trading.position.board.png

Documentation Index

Acceptance & Sign-Off

  • claude/output/RC1_GATE1_ACCEPTANCE.md — RC-1 Gate 1 acceptance report
  • claude/output/2026-07-19_RC1_COMPLETION_SUMMARY.md — RC-1 completion session summary
  • claude/output/2026-07-20_RC2_ALPHA_ACCEPTANCE.md — AI Integration Layer Alpha acceptance

Build Management

  • claude/output/BUILD_TAGS.md — Version registry (immutable build references)

RC-2 Planning

  • claude/output/RC2_ROADMAP.md — 9-component roadmap for RC-2
  • claude/output/RC2_IMPLEMENTATION_INDEX.md — Complete documentation index

Architectural Principles (Locked)

  • claude/output/RC2_REMOVABILITY_RULE.md — Removability engineering rule
  • claude/output/ARCHITECTURAL_DECISION_REMOVABILITY.md — ADR for removability
  • claude/output/CONSTRAINT_AI_INTEGRATION_ISOLATION.md — AI integration isolation constraint
  • claude/output/RC2_ARCHITECTURAL_MANIFESTO.md — All principles + implementation guidance

Architecture Documentation

  • docs/enforcement-kernel.md — Enforcement kernel design
  • docs/insight-compiler.md — Insight compiler design
  • docs/memory-policy.md — Memory policy design
  • docs/pipeline.md — Pipeline architecture
  • docs/verifier.md — Verifier design

Getting Started

Prerequisites

  • Node.js (v18+)
  • npm

Installation

cd claude/input/tools/rsky.terminal
npm install

Running the Terminal

# Start the server
node server.js

# Or use the launcher
.\rsky-trade-launcher.ps1

The terminal will be available at http://localhost:8787.

Testing

cd claude/input/tools/rsky.terminal

# Run all tests
npx ts-node --esm kernel.test.ts
npx ts-node --esm execution-firewall.test.ts
npx ts-node --esm recovery-invariant.test.ts
npx ts-node --esm recovery-selection.test.ts
npx ts-node --esm classifier.test.ts
npx ts-node --esm analytics.test.ts
npx ts-node --esm position-sizing.test.ts
npx ts-node --esm equity-curve-reducer.test.ts
npx ts-node --esm trade-aggregate.test.ts
npx ts-node --esm acceptance-journal-replay.test.ts

License

TBD

About

Profit.OS is a liquidity-aware portfolio operating system designed to coordinate capital allocation, risk, and execution.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages