{"_id":"@ariffazil/a-forge","_rev":"2-cdf7ae45d6db279fca0a5f5df7c3cc9c","name":"@ariffazil/a-forge","dist-tags":{"latest":"2026.7.24"},"versions":{"2026.6.30":{"name":"@ariffazil/a-forge","version":"2026.6.30","_id":"@ariffazil/a-forge@2026.6.30","maintainers":[{"name":"ariffazil","email":"arifos@arif-fazil.com"}],"bin":{"agent":"dist/src/interfaces/cli.js","arifos-mcp":"dist/src/interfaces/mcp/cli.js","arifos-mcp-stdio":"dist/src/interfaces/mcp/stdio.js","arifos-mcp-server":"dist/src/interfaces/mcp/server.js"},"dist":{"shasum":"0ba98498ef0e8fd6680d8f49112ae6146ab93055","tarball":"https://registry.npmjs.org/@ariffazil/a-forge/-/a-forge-2026.6.30.tgz","fileCount":1301,"integrity":"sha512-DHLxGQNMMBR4mWPU08IHdv+dVBx1Le0VgqkV43Q9OJhzMyYtnUBED+E3T7NWYwyc57ZAj3MS85h9/sIR934Qdw==","signatures":[{"sig":"MEUCIBdhtCkKDW6UiwDqmBgf/1URWVbXy5Zk0T3sxFcPRJ4hAiEA/tv78VxX9TUxds2jEOlK3XXTygD6c6K1v/RO9UOqTow=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7903467},"type":"module","gitHead":"7d8d397a5d87fb85c91f2dba2ba04e4ad1e4c450","scripts":{"tui":"npx tsx src/infrastructure/tui/forge-tui.ts","test":"node dist/test/AgentEngine.test.js","build":"tsc -p tsconfig.json","start":"node dist/src/interfaces/server.js","mcp:http":"node dist/src/interfaces/mcp/cli.js serve --transport http --port 3000","terminal":"node dist/src/cli/terminal.js","mcp:stdio":"node dist/src/interfaces/mcp/cli.js serve --transport stdio","tui:start":"node dist/src/infrastructure/tui/forge-tui.js","terminal:dev":"npx tsx src/cli/terminal.ts","example:explore":"node dist/examples/runExploreExample.js"},"_npmUser":{"name":"ariffazil","email":"arifos@arif-fazil.com"},"_npmVersion":"10.9.8","description":"A-FORGE — Constitutional Event-Sourced Agent Runtime. Planner/Executor/Verifier triad, policy engine, governed memory, and 888_HOLD human sovereignty gates.","directories":{},"_nodeVersion":"22.23.0","dependencies":{"pg":"^8.21.0","zod":"^3.24.4","glob":"^11.0.2","blessed":"^0.1.81","express":"^5.1.0","prom-client":"^15.1.3","blessed-contrib":"^4.11.0","@supabase/supabase-js":"^2.108.1","@modelcontextprotocol/sdk":"^1.9.0"},"_hasShrinkwrap":false,"devDependencies":{"pyright":"^1.1.410","@types/pg":"^8.20.0","typescript":"^6.0.3","@types/node":"^25.9.3","@types/blessed":"^0.1.27","@types/express":"^5.0.6","yaml-language-server":"^1.23.0"},"_npmOperationalInternal":{"tmp":"tmp/a-forge_2026.6.30_1782826853019_0.8685614825883337","host":"s3://npm-registry-packages-npm-production"}},"2026.7.24":{"name":"@ariffazil/a-forge","version":"2026.7.24","description":"A-FORGE — Constitutional Event-Sourced Agent Runtime. Planner/Executor/Verifier triad, policy engine, governed memory, and 888_HOLD human sovereignty gates.","type":"module","bin":{"agent":"dist/src/interfaces/cli.js","arifos-mcp":"dist/src/interfaces/mcp/cli.js","arifos-mcp-server":"dist/src/interfaces/mcp/server.js","arifos-mcp-stdio":"dist/src/interfaces/mcp/stdio.js"},"scripts":{"build":"tsc -p tsconfig.json","start":"node dist/src/interfaces/server.js","test":"node dist/test/AgentEngine.test.js","example:explore":"node dist/examples/runExploreExample.js","mcp:stdio":"FORGE_STDIO_ACTOR_ID=opencode node dist/src/interfaces/mcp/cli.js serve --transport stdio","mcp:http":"node dist/src/interfaces/mcp/cli.js serve --transport http --port 3000","terminal":"node dist/src/cli/terminal.js","terminal:dev":"npx tsx src/cli/terminal.ts","tui":"npx tsx src/infrastructure/tui/forge-tui.ts","tui:start":"node dist/src/infrastructure/tui/forge-tui.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.9.0","@mozilla/readability":"^0.6.0","@supabase/supabase-js":"^2.108.1","@types/jsdom":"^28.0.3","@types/turndown":"^5.0.6","blessed":"^0.1.81","blessed-contrib":"^4.11.0","express":"^5.1.0","glob":"^11.0.2","hash-wasm":"^4.12.0","jose":"^6.1.3","jsdom":"^29.1.1","pg":"^8.21.0","prom-client":"^15.1.3","turndown":"^7.2.4","zod":"~3.25.76"},"devDependencies":{"@types/blessed":"^0.1.27","@types/express":"^5.0.6","@types/node":"^26.1.0","@types/pg":"^8.20.0","@types/pixelmatch":"^5.2.6","@types/pngjs":"^6.0.5","pixelmatch":"^7.2.0","pngjs":"^7.0.0","pyright":"^1.1.411","typescript":"^6.0.3","yaml-language-server":"^1.23.0"},"_id":"@ariffazil/a-forge@2026.7.24","gitHead":"8bf6b0b1e196379f7cf8d9fbcaff9bb481fa82fd","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-dvpUPse35S15kAoj0hvHMh0VmRtL7bbawXdZS157llY/SYhYK78X+v1LegC7Rh4CexCONCl8Aw3ki3sWPe4OdA==","shasum":"da0132702d5f222a5b0a40098564022afd0da524","tarball":"https://registry.npmjs.org/@ariffazil/a-forge/-/a-forge-2026.7.24.tgz","fileCount":1682,"unpackedSize":11890388,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH/r0VeemQYx0gsFM0gnji0Z+aj7qA7rHAlnVrkEdKFkAiEAyuBRSRLqXShm80INIo1B8nH++5rKfcX8i7K4CagJVcw="}]},"_npmUser":{"name":"ariffazil","email":"arifos@arif-fazil.com"},"directories":{},"maintainers":[{"name":"ariffazil","email":"arifos@arif-fazil.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/a-forge_2026.7.24_1784909185905_0.2649489732789472"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-30T13:40:52.839Z","modified":"2026-07-24T16:06:26.364Z","2026.6.30":"2026-06-30T13:40:53.203Z","2026.7.24":"2026-07-24T16:06:26.197Z"},"description":"A-FORGE — Constitutional Event-Sourced Agent Runtime. Planner/Executor/Verifier triad, policy engine, governed memory, and 888_HOLD human sovereignty gates.","maintainers":[{"name":"ariffazil","email":"arifos@arif-fazil.com"}],"readme":"<!-- SOT-MANIFEST\nfederation_release: v2026.07.23\nlast_verified: 2026-07-23T22:00Z\nlive_commit: 3a50f44\nqqq_version: v1.1.1 (10/10 tests passing, verdict round-trip closed)\nseal_chain: append-only (chattr +a) + Merkle anchor every 100 receipts\nsense_port: 7071 (healthy)\nmcp_port: 7072 (healthy)\nauthority_ceiling: 777_FORGE (execution only — never adjudicate)\nowner_summary: GREEN\ntruth_rule: MCP tools/list on :7072 beats any static count in prose\n-->\n\n# A-FORGE — Governed Execution Shell\n\n[![Agentic CI](https://github.com/ariffazil/A-FORGE/actions/workflows/agentic-ci.yml/badge.svg?branch=main)](https://github.com/ariffazil/A-FORGE/actions/workflows/agentic-ci.yml)\n[![Boundary Guard](https://github.com/ariffazil/A-FORGE/actions/workflows/a-forge-boundary-guard.yml/badge.svg?branch=main)](https://github.com/ariffazil/A-FORGE/actions/workflows/a-forge-boundary-guard.yml)\n[![Governance Gate](https://github.com/ariffazil/A-FORGE/actions/workflows/governance-gate.yml/badge.svg?branch=main)](https://github.com/ariffazil/A-FORGE/actions/workflows/governance-gate.yml)\n[![🔥 FORGE](https://img.shields.io/badge/%F0%9F%94%A5%20FORGE-52%20tools-orange)](https://mcp.arif-fazil.com/mcp)\n[![License](https://img.shields.io/github/license/ariffazil/A-FORGE?label=License)](LICENSE)\n\n> **A-FORGE is the hands. arifOS is the brain. The hands execute. The brain judges. The hands never adjudicate.**\n>\n> **DITEMPA BUKAN DIBERI — Execution is forged, not given.**\n\n---\n\n## TL;DR — Three Audiences\n\n**For human operators (Arif):** A-FORGE is the execution engine. It builds, deploys, runs code, and manages Docker — but only after arifOS judges and you (F13) approve. [Jump to §10](#10-for-human-operators)\n\n**For AI agents:** Register your forge instrument, get a lease, execute through governed gates. Never self-authorize. Never adjudicate. [Jump to §11](#11-for-ai-agents)\n\n**For institutions:** A-FORGE is the constitutional execution substrate — 52 MCP tools, 4-layer forge gate, full audit trail on every mutation. [Jump to §12](#12-for-institutions)\n\n---\n\n## 1. Federation Position\n\n```\n                         ┌─────────────────────────┐\n                         │      F13 SOVEREIGN       │\n                         │     Arif bin Fazil       │\n                         └────────────┬────────────┘\n                                      │ approves\n                                      ▼\n┌─────────────────────────────────────────────────────────────────────┐\n│                          AAA COCKPIT (:3001)                         │\n│                    Routes, displays, never judges                    │\n└────────────────────────────────┬────────────────────────────────────┘\n                                 │ routes to\n              ┌──────────────────┼──────────────────┐\n              ▼                  ▼                  ▼\n      ┌──────────┐       ┌──────────┐       ┌──────────┐\n      │  arifOS   │       │ A-FORGE  │       │  DOMAIN   │\n      │  JUDGES   │       │ EXECUTES │       │  ORGANS   │\n      │  :8088    │       │  :7071   │       │ GEOX :8081│\n      │ F1-F13   │       │  :7072   │       │WEALTH:18082│\n      │ VAULT999 │       │ ← HERE   │       │ WELL :18083│\n      └──────────┘       └──────────┘       └──────────┘\n```\n\n**Trinity roles:**\n- **arifOS** = LAW/JUDGMENT (\"May this happen?\")\n- **AAA** = STATE/ROUTING (\"Where does it go?\")\n- **A-FORGE** = EXECUTION/MUTATION (\"How do we safely do it?\")\n\n**Canonical flow:** Arif (F13) → AAA (IDENTITY) → arifOS (JUDGE) → A-FORGE (EXECUTE) → VAULT999 (SEAL)\n\n---\n\n## 2. What A-FORGE Is (and Is Not)\n\n| ✅ EXECUTES | ❌ NEVER |\n|-------------|---------|\n| Builds, deploys, runs code | Geoscience — Vsh, PHIE, Sw, porosity (→ GEOX) |\n| Shell, git, Docker, browser ops | Economics — NPV, IRR, capital allocation (→ WEALTH) |\n| 52 MCP tools under constitutional gates | Constitutional verdicts — SEAL/HOLD/VOID (→ arifOS) |\n| Routes intent to domain organs via A2A | Self-authorization — no execution without lease |\n| Full audit trail on every mutation | NumPy, Pandas, SciPy in execution path |\n\n---\n\n## 3. Architecture — Hexagonal Layers\n\n```\nsrc/\n├── domain/          # Pure business logic — no I/O\n│   ├── engine/      # AgentEngine.ts — core agent loop\n│   ├── governance/  # 4-layer forge gate\n│   ├── planner/     # PlanValidator — verifyGovernanceCard + reversibility\n│   └── agents/      # Agent profiles, capability definitions\n├── application/     # Use cases — services, approval, memory, A2A\n├── infrastructure/  # Adapters — LLM, tools, vault, bridges, CLI\n└── interfaces/      # Delivery — server.ts (Express :7071), MCP :7072, config\n```\n\n---\n\n## 4. The 4-Layer Forge Gate\n\nEvery execution passes ALL four layers. No skipping, no silence.\n\n| Layer | Component | Rule |\n|-------|-----------|------|\n| **1: F1 AMANAH** | Catastrophic pattern scan | HARAM/BLOCK → HALT |\n| **2: Model Capability** | Identity + capability band check | DEGRADED/MISSING → HALT |\n| **3: Governance Bridge** | F1–F12 floor eval via arifOS | VOID → HALT |\n| **4: Approval Boundary** | Irreversibility + blast radius | APPROVED → PROCEED |\n\n**Gödel Lock:** A-FORGE cannot seal its own `forge_execute` outcomes without external witness (arifOS kernel or Arif F13). The executor cannot certify itself.\n\n```mermaid\ngraph TB\n    AGENT[🤖 Agent / Intent] -->|request| LEASE{Valid Lease?}\n    LEASE -->|no| BLOCK[🚫 DENIED]\n    LEASE -->|yes| L1[Layer 1: F1 AMANAH<br/>Catastrophic Pattern Scan]\n    L1 -->|HARAM| BLOCK\n    L1 -->|PASS| L2[Layer 2: Model Capability<br/>Identity + Capability Band]\n    L2 -->|DEGRADED| BLOCK\n    L2 -->|PASS| L3[Layer 3: Governance Bridge<br/>arifOS F1-F12 Floor Eval]\n    L3 -->|VOID| BLOCK\n    L3 -->|SEAL| L4[Layer 4: Approval Boundary<br/>Irreversibility + Blast Radius]\n    L4 -->|888_HOLD| HOLD[⏸️ Human Ratification]\n    L4 -->|APPROVED| EXEC[⚡ Execute<br/>Shell · Git · Deploy · Docker]\n    EXEC -->|receipt| VAULT[(VAULT999<br/>Immutable Record)]\n    HOLD -->|approve| EXEC\n```\n\n### What Is a Lease?\n\nA **lease** is a bounded permission grant — the execution safety object of A-FORGE:\n\n- **Who may act** — the agent or instrument\n- **What may be changed** — scope of mutation\n- **Where action may occur** — filesystem, network, shell boundaries\n- **How long permission lasts** — time-bound, auto-expiring\n- **What witness is required** — rollback plan, audit trace\n\n> Without a valid lease, no mutation. The hands never self-authorize.\n\n### Federation Separation of Powers\n\n| Layer | Role | Can | Cannot |\n|-------|------|-----|--------|\n| **ARIF** | Sovereign | Veto, approve, decide | Be overridden |\n| **AAA** | State / Cockpit | Display, route, queue, register | Judge, execute, seal |\n| **arifOS** | Judge | Issue SEAL/HOLD/VOID/SABAR | Execute mutations |\n| **Domain Organs** | Witnesses | Compute and reflect evidence | Decide alone |\n| **A-FORGE** | Executor | Build, deploy, mutate | Self-authorize |\n| **VAULT999** | Ledger | Record immutable seals | Edit or delete history |\n\n> AAA routes and displays. arifOS judges. Domain organs witness. A-FORGE executes. VAULT999 records. ARIF decides.\n\n---\n\n## 5. Quick Start\n\n```bash\ncd /root/A-FORGE\n\nnpm install && npm run build           # Build TypeScript\n\nnpm test                                # AgentEngine suite\nmake test                               # Full battery (security + build + all suites)\n\n# MCP gateway (stdio — local agent ingress)\nnpm run mcp:stdio\n\n# Health checks\ncurl -s http://localhost:7071/health | python3 -m json.tool   # Sense API\ncurl -s http://localhost:7072/health | python3 -m json.tool   # MCP gateway\n\n# Deploy\nsystemctl restart a-forge              # Express :7071\nsystemctl restart a-forge-mcp          # MCP :7072\n```\n\n---\n\n## 6. The Execution Chain\n\n```\nINTENT → PLAN → arif_judge (SEAL) → forge_execute (4-gate) → VAULT999 (SEAL)\n```\n\n1. **Intent** declared by human or agent\n2. **Plan** validated by PlanValidator (reversibility, governance card)\n3. **Judge** arifOS issues SEAL/HOLD/VOID\n4. **Execute** A-FORGE runs through 4-layer forge gate\n5. **Seal** VAULT999 records immutable receipt\n\n---\n\n## 7. Deployment Surfaces\n\n| Surface | Port | Transport | Access |\n|---------|------|-----------|--------|\n| **Sense API** | 7071 | Express HTTP | Internal VPS |\n| **MCP Gateway** | 7072 | Streamable HTTP + stdio | Local + federation organs |\n| **Public MCP** | — | `https://mcp.arif-fazil.com/mcp` | Proxied through arifOS kernel |\n| **A2A** | — | Via AAA cockpit | Agent-to-agent mesh |\n\n---\n\n## 8. Service Architecture\n\n```bash\n# Systemd services\na-forge.service                    # Express API on :7071\na-forge-mcp.service                # MCP gateway on :7072\n\n# Key paths\n/root/A-FORGE/                     # Source + build\n/opt/a-forge/app/                  # Deployed runtime (rsync)\n/root/A-FORGE/identity.toml        # Canonical service identity\n/root/A-FORGE/.well-known/         # Agent cards + discovery\n```\n\n---\n\n## 9. Federation Cross-Reference\n\n| Organ | Role | Port | Repo |\n|-------|------|------|------|\n| arifOS | Constitutional kernel | 8088 | [ariffazil/arifos](https://github.com/ariffazil/arifos) |\n| AAA | State + cockpit | 3001 | [ariffazil/AAA](https://github.com/ariffazil/AAA) |\n| GEOX | Earth intelligence | 8081 | [ariffazil/geox](https://github.com/ariffazil/geox) |\n| WEALTH | Capital intelligence | 18082 | [ariffazil/wealth](https://github.com/ariffazil/wealth) |\n| WELL | Vitality guard | 18083 | [ariffazil/well](https://github.com/ariffazil/well) |\n| HERMES | Multi-modal bridge + Telegram relay | 8644 | [ariffazil/HERMES](https://github.com/ariffazil/HERMES) |\n| **A-FORGE** | Execution shell | 7071/7072 | ← you are here |\n\n---\n\n## 10. For Human Operators (Arif)\n\n**What you see:** A-FORGE executes. It builds, deploys, runs code, manages the VPS — after you or arifOS says it's safe.\n\n**What you do:** Review HOLDs, approve irreversible actions (F13), observe execution receipts.\n\n**Key endpoints:**\n- Health: `curl localhost:7071/health`\n- MCP tools: `curl localhost:7072/health`\n- Public door: `https://mcp.arif-fazil.com/mcp`\n\n**Your absolute veto:** No agent can self-authorize. No execution without a lease. Your F13 word is final.\n\n---\n\n## 11. For AI Agents (Forge Instruments)\n\n**You are a forge instrument.** Your job is execution under governance.\n\n**Rules:**\n1. Get a lease before executing → `forge_lease_request`\n2. Every execution goes through the 4-layer forge gate — no skipping\n3. `forge_execute` for MUTATE-class ops requires prior `arif_judge` SEAL\n4. Never self-authorize — the forge has no authority to adjudicate\n5. All claims carry epistemic labels: OBS, DER, INT, SPEC\n6. Boundary violations (geophysics, economics, verdicts) trigger 888_HOLD\n\n**Agent card:** `public/a2a/agent-card.example.json`\n\n---\n\n## 12. For Institutions\n\nA-FORGE provides governed, auditable execution:\n\n| Property | How A-FORGE delivers it |\n|----------|------------------------|\n| **Separation of powers** | Executor ≠ Judge — A-FORGE never adjudicates |\n| **Constitutional gates** | 4-layer forge gate on every mutation |\n| **Full audit trail** | Every execution logged, hash-chained to VAULT999 |\n| **Boundary enforcement** | Geophysics → GEOX, Economics → WEALTH, Verdicts → arifOS |\n| **Lease-based authority** | No execution without explicit lease scope |\n| **Gödel Lock** | External witness required for irreversible actions |\n\n---\n\n## 13. Build, Test, Deploy (CI)\n\n```bash\n# Standard CI\nnpm install && npm run build    # TypeScript compile\nmake test                       # Security audit + build + all test suites\n\n# Single test\nnode dist/test/AgentEngine.test.js\nnode --test --test-name-pattern=\"multi-turn tool execution\" dist/test/AgentEngine.test.js\n\n# Deploy (T2 — announce 10s)\nnpm run build\nsystemctl restart a-forge && systemctl restart a-forge-mcp\ncurl -s http://localhost:7071/health | python3 -m json.tool\n```\n\n**CI Architecture:** Dual-lane → Standard CI + BIJAKSANA (ΔS, Φ, Ψ, Ω) → Agentic CI Report → Check Run → Federation cron → VAULT999 seal.\n\n---\n\n## 14. Constitutional Boundary\n\n```\n    ┌──────────────────────────────────────────┐\n    │                                          │\n    │   A-FORGE EXECUTES.                      │\n    │   arifOS JUDGES.                         │\n    │   AAA DISPLAYS.                          │\n    │   The domain organs WITNESS.             │\n    │   Arif HOLDS THE VETO.                   │\n    │                                          │\n    │   The hands never judge.                 │\n    │   The forge never self-authorizes.       │\n    │   The executor never seals its own work. │\n    │                                          │\n    │   Without lease → no action.             │\n    │   Without SEAL → no mutation.            │\n    │   Without witness → no seal.             │\n    │                                          │\n    │   DITEMPA BUKAN DIBERI                  │\n    │   Execution is forged, not given.        │\n    │   999 SEAL ALIVE.                        │\n    │                                          │\n    └──────────────────────────────────────────┘\n```\n","readmeFilename":"README.md"}