pramana-protocol 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# pramana-protocol
+
+**PRAMANA/1.0** — A Self-Verifying Cognition Protocol for AI-Native Service Universes
+
+> Named after Dharmakīrti's epistemological framework (c. 600–660 CE, Nalanda). *Pramana* = valid cognition.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19273330.svg)](https://zenodo.org/records/19273330)
+[![npm](https://img.shields.io/npm/v/pramana-protocol)](https://www.npmjs.com/package/pramana-protocol)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+---
+
+## The Problem
+
+At 200+ AI services, capability registries decay into stale documentation. Services claim capabilities they no longer have. Knowledge bases contain rules that were never validated. Routing succeeds while cognition fails. **Declaration without proof is hallucination at scale.**
+
+## The Protocol
+
+Three intertwined strands. Four signals. Five authenticity levels. One return signal that closes the loop.
+
+```
+Strand 1 — CAPABILITY    What services exist and what they can do  (AnkrCodex-compatible)
+Strand 2 — KNOWLEDGE     Domain rules — SHASTRA / YUKTI / VIVEKA   (Knowledge Codex-compatible)
+Strand 3 — PROOF         Implementation matches declaration         (CCA-compatible)
+```
+
+```
+Signal 1 — STATE    What the service knows and can do
+Signal 2 — TRUST    What is authorised
+Signal 3 — SENSE    What is happening now
+Signal 4 — PHALA    Delivery outcome → returned to SOURCE RULE     ← the novel signal
+```
+
+**PHALA** closes the loop. Every delivery outcome returns to the *rule that generated the answer* — not the service log. Wrong outcomes trigger RCA. Correct outcomes reaffirm the rule. The system learns from every transaction.
+
+## Authenticity Markers
+
+Every output carries a marker. Never a percentage. A binary checklist per strand.
+
+| Level | Label | Action |
+|---|---|---|
+| PRAMANA-0 | UNVERIFIED | **Mandatory human check — do not act** |
+| PRAMANA-1 | SINGLE SOURCE | Verify independently. System explains which strand + why it answered. |
+| PRAMANA-2 | PARTIAL AUTHENTIC | Missing strand named explicitly. Proceed with caution. |
+| PRAMANA-3 | AUTHENTIC | All three strands confirmed. Reliable. |
+| PRAMANA-3+ | AUTHENTICATED + INFERRED | Full coverage + SLM inference. Highest confidence. |
+
+## Install
+
+```bash
+npm install pramana-protocol
+```
+
+## Usage
+
+```typescript
+import {
+  STRAND, SIGNAL, PRAMANA_LEVEL,
+  getPramanaLevel, buildMarker,
+  PhalaPayload
+} from 'pramana-protocol';
+
+// Determine authenticity level from available strands
+const level = getPramanaLevel(
+  [STRAND.CAPABILITY, STRAND.KNOWLEDGE],  // proof strand missing
+  false                                    // SLM not available
+);
+// → PRAMANA_LEVEL.PARTIAL_AUTHENTIC (2)
+
+// Build a display marker for the output
+const marker = buildMarker(
+  [STRAND.CAPABILITY, STRAND.KNOWLEDGE],
+  false,
+  'Proof strand unavailable — CCA not yet run for this service'
+);
+// → { level: 2, label: 'PRAMANA-2 — PARTIAL AUTHENTIC', strands_missing: ['proof'], ... }
+
+// PHALA payload — fire on every delivery outcome
+const phala: PhalaPayload = {
+  signal_type: 'phala',
+  rule_id: 'MAR-YK-007',
+  applied_by: 'mari8x-legal',
+  query_context: 'charter party clause, English law',
+  outcome: 'failure',
+  strands_available: [STRAND.CAPABILITY, STRAND.KNOWLEDGE],
+  strand_missing: [STRAND.PROOF],
+  authenticity_level: PRAMANA_LEVEL.PARTIAL_AUTHENTIC,
+  rca_triggered: true,
+  timestamp: new Date().toISOString()
+};
+```
+
+## Reference Implementation
+
+**ANKR** is Customer Zero — 200+ services running PRAMANA/1.0.
+
+- AnkrCodex (capability registry) — Strand 1
+- GRANTHX Knowledge Codex (5,336 rules, SHASTRA/YUKTI/VIVEKA) — Strand 2
+- CCA Capability Closure Audit (174 services audited) — Strand 3
+- PHALA signal wired across all services
+
+## Protocol Specification
+
+Full RFC-style spec: [PROTOCOL.md](PROTOCOL.md)
+
+Academic paper (Zenodo DOI: 10.5281/zenodo.19273330): [PAPER.md](PAPER.md)
+
+## Built on Forja
+
+PRAMANA is the cognition layer built on top of the Forja declaration protocol.
+
+```
+Forja     = declaration protocol (what a service IS and can do)
+PRAMANA   = cognition protocol   (whether that declaration holds under real usage)
+```
+
+- Forja: [rocketlang/forja-protocol](https://github.com/rocketlang/forja-protocol)
+- Trust constants: [ankr-trust-constants](https://www.npmjs.com/package/ankr-trust-constants)
+
+## Author
+
+**Capt. Anil Kumar Sharma**
+PowerPbox IT Solutions Pvt Ltd
+capt.anil.sharma@powerpbox.org
+
+DPIIT Registered Startup, Haryana, India
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * pramana-protocol — Core constants and types for the PRAMANA/1.0 cognition protocol
+ * https://zenodo.org/records/19273330
+ *
+ * Author: Capt. Anil Kumar Sharma, PowerPbox IT Solutions Pvt Ltd
+ * License: Apache-2.0
+ */
+export declare const PRAMANA_LEVEL: {
+    /** No strand available. Mandatory human check. Never act on this output. */
+    readonly UNVERIFIED: 0;
+    /** One strand only. System must explain which strand and why it answered. */
+    readonly SINGLE_SOURCE: 1;
+    /** Two strands confirmed. Missing strand must be named explicitly. */
+    readonly PARTIAL_AUTHENTIC: 2;
+    /** All three strands confirmed. Reliable. */
+    readonly AUTHENTIC: 3;
+    /** Full strand coverage + SLM Purva-paksha inference applied. */
+    readonly AUTHENTICATED_INFERRED: 4;
+};
+export type PramanaLevel = typeof PRAMANA_LEVEL[keyof typeof PRAMANA_LEVEL];
+export declare const PRAMANA_LABEL: Record<PramanaLevel, string>;
+export declare const PRAMANA_ACTION: Record<PramanaLevel, string>;
+export declare const STRAND: {
+    readonly CAPABILITY: "capability";
+    readonly KNOWLEDGE: "knowledge";
+    readonly PROOF: "proof";
+};
+export type StrandType = typeof STRAND[keyof typeof STRAND];
+export declare const SIGNAL: {
+    readonly STATE: "state";
+    readonly TRUST: "trust";
+    readonly SENSE: "sense";
+    readonly PHALA: "phala";
+};
+export type SignalType = typeof SIGNAL[keyof typeof SIGNAL];
+export interface PhalaPayload {
+    signal_type: 'phala';
+    rule_id: string;
+    applied_by: string;
+    query_context: string;
+    outcome: 'success' | 'failure' | 'partial';
+    strands_available: StrandType[];
+    strand_missing: StrandType[];
+    authenticity_level: PramanaLevel;
+    rca_triggered: boolean;
+    slm_available?: boolean;
+    timestamp: string;
+}
+export declare const RCA_FAILURE: {
+    readonly ROUTING: "routing";
+    readonly APPLICATION: "application";
+    readonly RULE: "rule";
+    readonly UNKNOWN: "unknown";
+};
+export type RcaFailureType = typeof RCA_FAILURE[keyof typeof RCA_FAILURE];
+export declare function getPramanaLevel(strandsAvailable: StrandType[], slmAvailable?: boolean): PramanaLevel;
+export interface AuthenticityMarker {
+    level: PramanaLevel;
+    label: string;
+    action: string;
+    strands_present: StrandType[];
+    strands_missing: StrandType[];
+    explanation?: string;
+}
+export declare function buildMarker(strandsAvailable: StrandType[], slmAvailable?: boolean, explanation?: string): AuthenticityMarker;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,eAAO,MAAM,aAAa;IACxB,4EAA4E;;IAE5E,6EAA6E;;IAE7E,sEAAsE;;IAEtE,6CAA6C;;IAE7C,iEAAiE;;CAEzD,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,aAAa,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE5E,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAMtD,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAMvD,CAAC;AAIF,eAAO,MAAM,MAAM;;;;CAIT,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,MAAM,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAI5D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,MAAM,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAI5D,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3C,iBAAiB,EAAE,UAAU,EAAE,CAAC;IAChC,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,kBAAkB,EAAE,YAAY,CAAC;IACjC,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,OAAO,WAAW,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAI1E,wBAAgB,eAAe,CAC7B,gBAAgB,EAAE,UAAU,EAAE,EAC9B,YAAY,UAAQ,GACnB,YAAY,CAOd;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,WAAW,CACzB,gBAAgB,EAAE,UAAU,EAAE,EAC9B,YAAY,UAAQ,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,kBAAkB,CAapB"}

package/dist/index.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * pramana-protocol — Core constants and types for the PRAMANA/1.0 cognition protocol
+ * https://zenodo.org/records/19273330
+ *
+ * Author: Capt. Anil Kumar Sharma, PowerPbox IT Solutions Pvt Ltd
+ * License: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RCA_FAILURE = exports.SIGNAL = exports.STRAND = exports.PRAMANA_ACTION = exports.PRAMANA_LABEL = exports.PRAMANA_LEVEL = void 0;
+exports.getPramanaLevel = getPramanaLevel;
+exports.buildMarker = buildMarker;
+// ── Authenticity Levels ────────────────────────────────────────────────────────
+exports.PRAMANA_LEVEL = {
+    /** No strand available. Mandatory human check. Never act on this output. */
+    UNVERIFIED: 0,
+    /** One strand only. System must explain which strand and why it answered. */
+    SINGLE_SOURCE: 1,
+    /** Two strands confirmed. Missing strand must be named explicitly. */
+    PARTIAL_AUTHENTIC: 2,
+    /** All three strands confirmed. Reliable. */
+    AUTHENTIC: 3,
+    /** Full strand coverage + SLM Purva-paksha inference applied. */
+    AUTHENTICATED_INFERRED: 4,
+};
+exports.PRAMANA_LABEL = {
+    0: 'PRAMANA-0 — UNVERIFIED',
+    1: 'PRAMANA-1 — SINGLE SOURCE',
+    2: 'PRAMANA-2 — PARTIAL AUTHENTIC',
+    3: 'PRAMANA-3 — AUTHENTIC',
+    4: 'PRAMANA-3+ — AUTHENTICATED + INFERRED',
+};
+exports.PRAMANA_ACTION = {
+    0: 'MANDATORY HUMAN CHECK — do not act on this output',
+    1: 'Verify independently before relying on this output',
+    2: 'Proceed with caution — check missing strand before acting',
+    3: 'Reliable — proceed',
+    4: 'Highest available confidence — proceed',
+};
+// ── Strand Types ───────────────────────────────────────────────────────────────
+exports.STRAND = {
+    CAPABILITY: 'capability', // AnkrCodex — what services exist and what they can do
+    KNOWLEDGE: 'knowledge', // Knowledge Codex — domain rules (SHASTRA/YUKTI/VIVEKA)
+    PROOF: 'proof', // CCA — implementation matches declaration
+};
+// ── Signal Types ───────────────────────────────────────────────────────────────
+exports.SIGNAL = {
+    STATE: 'state', // What the service knows and can do
+    TRUST: 'trust', // What is authorised
+    SENSE: 'sense', // What is happening now
+    PHALA: 'phala', // Delivery outcome — returned to source RULE (the novel signal)
+};
+// ── RCA Failure Types ──────────────────────────────────────────────────────────
+exports.RCA_FAILURE = {
+    ROUTING: 'routing', // Wrong service received the query
+    APPLICATION: 'application', // Right service, rule applied incorrectly
+    RULE: 'rule', // Rule itself is wrong or outdated
+    UNKNOWN: 'unknown', // Cannot classify — escalate to human
+};
+// ── Strand Availability → PRAMANA Level ───────────────────────────────────────
+function getPramanaLevel(strandsAvailable, slmAvailable = false) {
+    const count = strandsAvailable.length;
+    if (count === 0)
+        return exports.PRAMANA_LEVEL.UNVERIFIED;
+    if (count === 1)
+        return exports.PRAMANA_LEVEL.SINGLE_SOURCE;
+    if (count === 2)
+        return exports.PRAMANA_LEVEL.PARTIAL_AUTHENTIC;
+    if (count >= 3 && slmAvailable)
+        return exports.PRAMANA_LEVEL.AUTHENTICATED_INFERRED;
+    return exports.PRAMANA_LEVEL.AUTHENTIC;
+}
+function buildMarker(strandsAvailable, slmAvailable = false, explanation) {
+    const level = getPramanaLevel(strandsAvailable, slmAvailable);
+    const allStrands = Object.values(exports.STRAND);
+    const missing = allStrands.filter(s => !strandsAvailable.includes(s));
+    return {
+        level,
+        label: exports.PRAMANA_LABEL[level],
+        action: exports.PRAMANA_ACTION[level],
+        strands_present: strandsAvailable,
+        strands_missing: missing,
+        ...(level < exports.PRAMANA_LEVEL.AUTHENTIC && explanation ? { explanation } : {}),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAqFH,0CAUC;AAaD,kCAiBC;AA3HD,kFAAkF;AAErE,QAAA,aAAa,GAAG;IAC3B,4EAA4E;IAC5E,UAAU,EAAE,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,CAAC;IAChB,sEAAsE;IACtE,iBAAiB,EAAE,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,CAAC;IACZ,iEAAiE;IACjE,sBAAsB,EAAE,CAAC;CACjB,CAAC;AAIE,QAAA,aAAa,GAAiC;IACzD,CAAC,EAAE,wBAAwB;IAC3B,CAAC,EAAE,2BAA2B;IAC9B,CAAC,EAAE,+BAA+B;IAClC,CAAC,EAAE,uBAAuB;IAC1B,CAAC,EAAE,uCAAuC;CAC3C,CAAC;AAEW,QAAA,cAAc,GAAiC;IAC1D,CAAC,EAAE,mDAAmD;IACtD,CAAC,EAAE,oDAAoD;IACvD,CAAC,EAAE,2DAA2D;IAC9D,CAAC,EAAE,oBAAoB;IACvB,CAAC,EAAE,wCAAwC;CAC5C,CAAC;AAEF,kFAAkF;AAErE,QAAA,MAAM,GAAG;IACpB,UAAU,EAAE,YAAY,EAAI,uDAAuD;IACnF,SAAS,EAAG,WAAW,EAAK,wDAAwD;IACpF,KAAK,EAAO,OAAO,EAAS,2CAA2C;CAC/D,CAAC;AAIX,kFAAkF;AAErE,QAAA,MAAM,GAAG;IACpB,KAAK,EAAG,OAAO,EAAI,oCAAoC;IACvD,KAAK,EAAG,OAAO,EAAI,qBAAqB;IACxC,KAAK,EAAG,OAAO,EAAI,wBAAwB;IAC3C,KAAK,EAAG,OAAO,EAAI,gEAAgE;CAC3E,CAAC;AAoBX,kFAAkF;AAErE,QAAA,WAAW,GAAG;IACzB,OAAO,EAAM,SAAS,EAAO,mCAAmC;IAChE,WAAW,EAAE,aAAa,EAAG,0CAA0C;IACvE,IAAI,EAAS,MAAM,EAAU,mCAAmC;IAChE,OAAO,EAAM,SAAS,EAAO,sCAAsC;CAC3D,CAAC;AAIX,iFAAiF;AAEjF,SAAgB,eAAe,CAC7B,gBAA8B,EAC9B,YAAY,GAAG,KAAK;IAEpB,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC;IACtC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,qBAAa,CAAC,UAAU,CAAC;IACjD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,qBAAa,CAAC,aAAa,CAAC;IACpD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,qBAAa,CAAC,iBAAiB,CAAC;IACxD,IAAI,KAAK,IAAI,CAAC,IAAI,YAAY;QAAE,OAAO,qBAAa,CAAC,sBAAsB,CAAC;IAC5E,OAAO,qBAAa,CAAC,SAAS,CAAC;AACjC,CAAC;AAaD,SAAgB,WAAW,CACzB,gBAA8B,EAC9B,YAAY,GAAG,KAAK,EACpB,WAAoB;IAEpB,MAAM,KAAK,GAAG,eAAe,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,cAAM,CAAiB,CAAC;IACzD,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtE,OAAO;QACL,KAAK;QACL,KAAK,EAAE,qBAAa,CAAC,KAAK,CAAC;QAC3B,MAAM,EAAE,sBAAc,CAAC,KAAK,CAAC;QAC7B,eAAe,EAAE,gBAAgB;QACjC,eAAe,EAAE,OAAO;QACxB,GAAG,CAAC,KAAK,GAAG,qBAAa,CAAC,SAAS,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pramana-protocol",
+  "version": "1.0.0",
+  "description": "PRAMANA/1.0 — A Self-Verifying Cognition Protocol for AI-Native Service Universes. Three strands. Four signals. Five authenticity levels. The PHALA signal closes the loop.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "PROTOCOL.md",
+    "PAPER.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "pramana",
+    "ai-protocol",
+    "capability-registry",
+    "knowledge-codex",
+    "phala-signal",
+    "authenticity-marker",
+    "rca-loop",
+    "forja",
+    "ankr",
+    "dharmakirti"
+  ],
+  "author": "Capt. Anil Kumar Sharma <capt.anil.sharma@powerpbox.org> (PowerPbox IT Solutions Pvt Ltd)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rocketlang/pramana-protocol.git"
+  },
+  "homepage": "https://zenodo.org/records/19273330",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}