ankr-forja

AnkrForja v0.2 — The knowledge exchange protocol for AI-native services.

STATE + TRUST + SENSE + ANNOUNCE. One codexAgent() call wires all four layers from your codex.json.

Install

npm install ankr-forja

What It Is

AnkrForja is an open protocol (Apache 2.0) that lets AI-native services declare exactly what they know, what they can do, and who is authorised to do it — without documentation, without interpretation, without hallucination.

GET  /api/v2/forja/state         — what this service knows and can do
GET  /api/v2/forja/trust/:userId — what this user/role is authorised to do
POST /api/v2/forja/sense/emit    — fire a real-time event to subscribers
GET  /api/v2/forja/proof         — what % of rules are annotated and verified

Quick Start

import Fastify from 'fastify'
import { codexAgent } from 'ankr-forja'

const app = Fastify()
await app.register(codexAgent())   // reads codex.json, wires all four endpoints
await app.listen({ port: 4000 })

Your service is now discoverable by any AnkrCodex crawler — no docs needed.

The Four Layers

| Endpoint | Purpose | |---|---| | STATE | Capability manifest — can_answer, can_do, emits. Machine-readable. | | TRUST | Role-based permission matrix. Returns what this user/agent tier can do. | | SENSE | Real-time event emission. Push events to subscribers on state changes. | | PROOF | Rule annotation coverage. coverage_pct = % of code decisions traced to domain rules. |

Why Not MCP?

MCP tool schemas consume ~55,000 tokens to load. A Forja STATE response is ~800 bytes. A trust bitmask check is one bitwise AND: (mask & BOOK) !== 0. Binary truth — no interpretation, no parsing, no hallucination possible.

At 200+ services, interpretation equals hallucination. The only solution is binary truth.

Trust Bitmask

Pair with ankr-trust-constants for zero-interpretation capability checks:

import { BOOK, MANIFEST, hasPerm } from 'ankr-trust-constants'

const trust = await fetch('/api/v2/forja/trust/user123').then(r => r.json())
if (hasPerm(trust.trust_mask, BOOK)) {
  // this user can create bookings — binary truth, no string matching
}

The 32-bit Allocation

Bits 0-7   — Universal Forja       (READ, QUERY, WRITE, EXECUTE, APPROVE, AUDIT, ADMIN, SUPER)
Bits 8-15  — Maritime block        (BOOK, MANIFEST, BL_ISSUE, RATE_DESK, FEEDER_OPS, ...)
Bits 16-23 — Logistics block       (GATE_IN, TRACK, FTA_CHECK, ALERT_ACK, PORT_OPS, ...)
Bits 24-31 — AGI autonomy tier     (AI_READ, AI_QUERY, AI_SUGGEST, AI_EXECUTE, AI_APPROVE, ...)

One integer encodes the full permission surface of any service. No string arrays. No parsing.

codex.json

Forja reads your service's codex.json at startup:

{
  "service": "portwatch-backend",
  "port": 4080,
  "domain": "maritime-port",
  "can_answer": ["vessel.ukc-status", "vessel.cpa-alert"],
  "can_do": ["MOVEMENT_AUTHORITY", "ALERT_ACK"],
  "emits": ["ukc-breach", "cpa-alert"],
  "forja_state": "/api/v2/forja/state",
  "forja_trust": "/api/v2/forja/trust",
  "forja_sense": "/api/v2/forja/sense/emit",
  "forja_proof": "/api/v2/forja/proof",
  "forja_version": "2.0"
}

can_answer in codex.json = can_answer in Forja STATE. They must stay in sync.

Used In Production

205+ services across the ANKR maritime platform run on this protocol — VTS systems, electronic Bill of Lading, charter party management, voyage intelligence, port congestion analytics.

Protocol Spec

Full specification: FORJA-SPEC-v0.1

Related

• ankr-trust-constants — 32-bit bitmask constants

License

Apache 2.0 — open protocol, anyone implements it.

Built by ANKR Labs | PowerPbox IT Solutions Pvt Ltd