@xshieldai/hanumang-mandate 0.2.0

package/LICENSE

@@ -0,0 +1,31 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 ANKR Labs / Capt. Anil Sharma
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+The full text of the GNU Affero General Public License v3 is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt
+
+ADDITIONAL TERMS (permitted under AGPL §7):
+
+If you run a modified version of this software as a network service,
+you must make the complete source code of the modified version available
+to all users of that service under the terms of this license.
+
+Commercial use, including SaaS deployments and enterprise integrations,
+requires a separate commercial license. Contact: captain@ankr.in

package/README.md

@@ -0,0 +1,251 @@
+# @rocketlang/hanumang-mandate
+
+Agent delegation credential verifier + 7-axis posture scorer. Pure primitives extracted from the internal **xshieldai-hanumang** Fastify service.
+
+**Two primitives. No DB. No HTTP. Install and use.**
+
+## What this is
+
+`hanumang-mandate` is the credential + posture-scoring layer of HanumanG, the agent-delegation-posture monitor inside xShieldAI. The full service has SQLite-backed attestations, regression alerts, revocation-URL polling, and Forja endpoints — that lives in the closed product. This package is the two primitives the rest of the service is built on: **Mudrika credential verification** and **7-axis posture scoring**.
+
+## Complementary to `@rocketlang/aegis` HanumanG
+
+The aegis package and this package are **different governance moments**, both named "HanumanG":
+
+| | `@rocketlang/aegis` HanumanG | `@rocketlang/hanumang-mandate` |
+|---|---|---|
+| Question | *Can this agent SPAWN?* | *Is this agent's MANDATE valid? What's its posture?* |
+| When | PreToolUse hook (spawn-time) | Continuous (per-action) |
+| Output | Binary PASS/FAIL | A/B/C/D/F grade + per-axis score |
+| Axes (7) | identity / authorization / scope / budget / depth / purpose / revocability | mudrika_integrity / identity_broadcast / mandate_bounds / proportional_force / return_with_proof / no_overreach / truthful_report |
+
+Use both. They are **not duplicates** — they cover different governance concerns.
+
+## Install
+
+```bash
+npm install @rocketlang/hanumang-mandate
+# or
+bun add @rocketlang/hanumang-mandate
+```
+
+## Mudrika — the delegation credential
+
+A Mudrika is a JWT-shaped credential that a principal issues to an agent. It declares: who is acting, on whose behalf, for what task, with what trust mask, in what scope, for how long, with what proof of provenance.
+
+```typescript
+import { verifyMudrika } from '@rocketlang/hanumang-mandate';
+
+const mudrika = {
+  mudrika_version: 'v1',
+  mudrika_id: 'mdr-001-2026-05-16',
+  principal_id: 'user:capt-anil',
+  agent_id: 'agent:codex-001',
+  task_id: 'task:refactor-routes',
+  trust_mask: 0b00011111,         // 5 bits set
+  scope_key: 'aegis/packages/aegis-guard',
+  issued_at: '2026-05-16T12:00:00Z',
+  ttl_seconds: 3600,
+  required_return_proof: 'pramana_receipt',
+  revocation_url: 'https://aegis.rocketlang.dev/mudrika/revoke',
+  pramana_chain: ['root', 'pramana:abc123'],
+};
+
+const result = verifyMudrika(mudrika, 'agent:codex-001');
+// {
+//   outcome: 'PASS',                       // or 'FAIL' / 'EXPIRED' / 'REVOKED'
+//   failure_reason: null,
+//   expires_at: '2026-05-16T13:00:00Z',
+//   trust_mask: 31,
+//   scope_key: 'aegis/packages/aegis-guard',
+//   principal_id: 'user:capt-anil',
+//   ...
+// }
+```
+
+### Phase-1 limit — signature is NOT cryptographically verified
+
+`verifyMudrika()` validates structure + TTL + trust_mask range. It does **not** verify the `signature` field cryptographically. The `signature` is in the payload schema for forward compatibility; today, callers must establish provenance themselves (e.g., authenticated transport, internal trust boundary).
+
+Phase 2 will add signature verification. If you need it now, wrap `verifyMudrika()` with your own crypto check.
+
+## 7-axis posture scorer
+
+The scorer assesses an agent's per-action behaviour across seven axes. Each axis returns 0–100 + an outcome (`PASS` / `WARN` / `FAIL`). The aggregate `PostureScore` uses a **worst-axis floor** (`HNG-YK-001`) — a single FAIL caps the grade at D regardless of how high the average is.
+
+```typescript
+import { scoreAxis, computePostureScore } from '@rocketlang/hanumang-mandate';
+
+const axisScores = [
+  scoreAxis({
+    axis: 'mudrika_integrity',
+    mudrika_verified: true,
+    mudrika_ttl_remaining_s: 600,
+    pramana_chain_depth: 2,
+  }),
+  scoreAxis({
+    axis: 'identity_broadcast',
+    self_declared: true,
+    declared_fields: ['agentId', 'agentType', 'officerRole', 'scopeKey', 'taskId', 'delegatedBy'],
+  }),
+  scoreAxis({
+    axis: 'mandate_bounds',
+    trust_mask_granted: 0b11111,
+    trust_mask_requested: 0b01111,
+    scope_key_match: true,
+    ttl_respected: true,
+  }),
+  scoreAxis({
+    axis: 'proportional_force',
+    response_mode: 1,
+  }),
+  scoreAxis({
+    axis: 'return_with_proof',
+    receipt_filed: true,
+    receipt_signed: true,
+    actions_listed: true,
+    deviations_reported: true,
+  }),
+  scoreAxis({
+    axis: 'no_overreach',
+    trust_mask_granted: 0b11111,
+    trust_mask_used: 0b00111,
+  }),
+  scoreAxis({
+    axis: 'truthful_report',
+    before_state_present: true,
+    after_state_present: true,
+    errors_reported: true,
+    human_modified_flagged: true,
+  }),
+];
+
+const posture = computePostureScore(axisScores);
+// {
+//   overall_score: 100,
+//   overall_grade: 'A',
+//   violation_count: 0,
+//   warn_count: 0,
+//   axes: { mudrika_integrity: {...}, identity_broadcast: {...}, ... }
+// }
+```
+
+### The 7 axes
+
+| Axis | Rule | What it checks |
+|---|---|---|
+| `mudrika_integrity` | HNG-S-001 | Credential present + verified + non-expiring |
+| `identity_broadcast` | HNG-S-002 | Agent self-declared with required fields |
+| `mandate_bounds` | HNG-S-003 | Requested mask ≤ granted mask, scope match, TTL respected |
+| `proportional_force` | HNG-S-004 | Response mode (1/2/3) properly routed |
+| `return_with_proof` | HNG-S-005 | Task closed with signed receipt + actions list |
+| `no_overreach` | HNG-S-006 | Used bits ⊆ granted bits + utilisation signal |
+| `truthful_report` | HNG-S-007 | before/after state present, errors + human-modification declared |
+
+### Grade thresholds
+
+| Grade | Condition |
+|---|---|
+| A | overall_score ≥ 90, no violations |
+| B | overall_score ≥ 80, no violations |
+| C | overall_score ≥ 60, no violations |
+| D | overall_score < 60, OR 1–2 violations |
+| F | 3+ violations |
+
+## What this package does NOT do
+
+- **No DB.** No persistence. The full xshieldai-hanumang service stores attestations to SQLite — you'd need to write your own store on top of these primitives.
+- **No HTTP.** `revocation_url` is in the mudrika payload but `verifyMudrika()` does not call it. The full service does (HNG-S-011, EE feature).
+- **No signature crypto.** See Phase-1 limit above.
+- **No regression alerting.** The full service tracks posture over time and routes alerts; not here.
+- **No registry / fleet view.** That's the EE layer.
+
+## Honest discipline
+
+`hanumang-mandate` was extracted from a service that runs internally at `trust_mask=1`, `claude_ankr_mask=29`, `claw_mask=14255`. Those scores describe the **full service**, not this primitives-only SDK. The package itself is v0.1.0 — a first OSS surface of the credential + scoring primitives, audited in extraction but not independently CA-audited as a standalone artifact.
+
+The Phase-1 signature limit is real. Use this for structural verification in trusted-transport environments, not for crypto-attested mandates over untrusted channels.
+
+## Related
+
+- [`@rocketlang/aegis`](https://www.npmjs.com/package/@rocketlang/aegis) — spawn-time HanumanG + DAN gate + budget caps (complementary to this)
+- [`@rocketlang/kavachos`](https://www.npmjs.com/package/@rocketlang/kavachos) — seccomp-bpf + Falco behavior governance
+- [`@rocketlang/chitta-detect`](https://www.npmjs.com/package/@rocketlang/chitta-detect) — memory poisoning detection
+- [`@rocketlang/lakshmanrekha`](https://www.npmjs.com/package/@rocketlang/lakshmanrekha) — LLM endpoint probe suite
+- [`@rocketlang/aegis-guard`](https://www.npmjs.com/package/@rocketlang/aegis-guard) — Five Locks SDK
+
+## License
+
+AGPL-3.0-only. See [LICENSE](LICENSE). Any modified version run as a network service must publish source per AGPL clause 13.
+
+The full xshieldai-hanumang service is internal (port 4255) and not currently distributed.
+
+For commercial dual-licensing or partnership: [captain@ankr.in](mailto:captain@ankr.in).
+
+---
+
+## v0.2.0 — Opt-in Agentic Control Center (ACC) event bus
+
+Added 2026-05-17. `verifyMudrika()`, `scoreAxis()`, and
+`computePostureScore()` now emit `AccReceipt` events, **but only when
+you wire a bus**. Without `setEventBus`, v0.2.0 behaves identically to
+v0.1.0 — no emission, no state, no side effect.
+
+### Wire it in 3 lines
+
+```typescript
+import { setEventBus, type EventBus, type AccReceipt } from '@rocketlang/hanumang-mandate';
+
+const myBus: EventBus = {
+  emit: (r: AccReceipt) => console.log(`[ACC] ${r.event_type} ${r.verdict} ${r.summary}`),
+};
+setEventBus(myBus);
+```
+
+### Receipt events emitted
+
+| Primitive | event_type | verdict |
+|---|---|---|
+| `verifyMudrika` (PASS) | `mudrika.verified` | PASS |
+| `verifyMudrika` (FAIL / EXPIRED) | `mudrika.rejected` | FAIL |
+| `scoreAxis` (per axis) | `posture.axis_scored` | PASS / WARN / FAIL |
+| `computePostureScore` (aggregate) | `posture.scored` | `{grade}-{verdict}` (e.g. `A-PASS`, `D-FAIL`) |
+
+### Receipt shape
+
+```typescript
+interface AccReceipt {
+  receipt_id: string;       // primitive-prefixed: 'hanumang-mudrika-{mudrikaId}' etc.
+  primitive: string;        // always 'hanumang-mandate'
+  event_type: string;       // 'mudrika.verified' | 'mudrika.rejected' | 'posture.axis_scored' | 'posture.scored'
+  emitted_at: string;       // ISO 8601
+  agent_id?: string;        // populated from mudrika.agent_id on verifyMudrika; not yet on scoreAxis
+  verdict?: string;
+  rules_fired?: string[];   // HNG-* rule IDs
+  summary?: string;
+  payload?: Record<string, unknown>;
+}
+```
+
+Strict subset of EE PRAMANA receipt format — EE consumers ingest without translation.
+
+### Phase-1 limits (v0.2.0)
+
+- **agent_id is populated on `mudrika.verified` only** — scoreAxis and
+  computePostureScore don't currently receive an agent_id parameter. Future
+  versions may add an optional `agent_id` field to `AxisInput`; today,
+  post-process receipts in the bus to add agent context from your own tracking.
+- **scoreAxis emits per call** — if you score 7 axes for one agent, that's
+  7 `posture.axis_scored` events + 1 `posture.scored` aggregate = 8 receipts.
+  Cockpit consumers may want to collapse these for display.
+- **Mudrika signature crypto NOT verified** (unchanged from v0.1.0) —
+  emission says `mudrika.verified` based on structural + TTL + trust_mask
+  range checks only. Phase-2 will add cryptographic signature verification.
+- **Default bus is in-process only.** Multi-process buses are a consumer choice.
+
+### Use with `@rocketlang/aegis-suite`
+
+```typescript
+import { wireAllToBus } from '@rocketlang/aegis-suite';  // suite v0.2.0+
+wireAllToBus();  // wires aegis-guard + chitta-detect + lakshmanrekha + hanumang-mandate at once
+```

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@xshieldai/hanumang-mandate",
+  "version": "0.2.0",
+  "description": "HanumanG mandate primitives — Mudrika delegation credential verifier + 7-axis posture scorer (mudrika_integrity, identity_broadcast, mandate_bounds, proportional_force, return_with_proof, no_overreach, truthful_report) + opt-in Agentic Control Center event bus. Extracted from xshieldai-hanumang.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",
+  "homepage": "https://github.com/rocketlang/aegis/tree/main/packages/hanumang-mandate",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rocketlang/aegis.git",
+    "directory": "packages/hanumang-mandate"
+  },
+  "bugs": {
+    "url": "https://github.com/rocketlang/aegis/issues"
+  },
+  "keywords": [
+    "hanumang",
+    "mudrika",
+    "xshieldai",
+    "rocketlang",
+    "ai-agent-delegation",
+    "agent-governance",
+    "ai-attestation",
+    "posture-scoring",
+    "agent-safety",
+    "delegation-credential",
+    "ai-mandate"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "hanumang_mandate": {
+    "extracted_from": "xshieldai-hanumang (internal Fastify service, port 4255)",
+    "complementary_to": "@rocketlang/aegis HanumanG (spawn-time governance)",
+    "phase": "phase-1-complete (structural mudrika verification; signature crypto deferred to phase-2)",
+    "rules_implemented": [
+      "HNG-S-001 (mudrika integrity axis)",
+      "HNG-S-002 (identity broadcast axis)",
+      "HNG-S-003 (mandate bounds axis)",
+      "HNG-S-004 (proportional force axis)",
+      "HNG-S-005 (return with proof axis)",
+      "HNG-S-006 (no overreach axis)",
+      "HNG-S-007 (truthful report axis)",
+      "HNG-S-008 (mudrika structure)",
+      "HNG-S-009 (mudrika TTL check)",
+      "HNG-S-010 (trust_mask range)",
+      "HNG-YK-001 (worst-axis floor aggregate grade)"
+    ],
+    "rules_left_in_ee": [
+      "HNG-S-011 (revocation URL reachability — requires HTTP)",
+      "Signature crypto verification (Phase-2)",
+      "Attestation persistence (SQLite-backed)",
+      "Regression alert routing (partial in EE)",
+      "Forja STATE/TRUST/SENSE/PROOF endpoints"
+    ]
+  }
+}

package/src/acc-bus.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+// See LICENSE for details.
+//
+// @rocketlang/hanumang-mandate — opt-in Agentic Control Center event bus (v0.2.0)
+// @rule:ACC-003 — Opt-in. emit only when setEventBus() called.
+// @rule:ACC-004 — Lightweight OSS receipt shape (strict subset of EE PRAMANA).
+// @rule:ACC-YK-003 — Stateless-primitive contract preserved.
+// @rule:INF-ACC-005 — emit() is a no-op when no bus has been set.
+
+export interface AccReceipt {
+  receipt_id: string;
+  primitive: string;
+  event_type: string;
+  emitted_at: string;
+  agent_id?: string;
+  verdict?: string;
+  rules_fired?: string[];
+  summary?: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface EventBus {
+  emit(receipt: AccReceipt): void;
+}
+
+let _bus: EventBus | null = null;
+
+export function setEventBus(bus: EventBus | null): void {
+  _bus = bus;
+}
+
+export function emitAccReceipt(receipt: Omit<AccReceipt, 'primitive' | 'emitted_at'>): void {
+  if (!_bus) return;
+  try {
+    _bus.emit({
+      ...receipt,
+      primitive: 'hanumang-mandate',
+      emitted_at: new Date().toISOString(),
+    });
+  } catch {
+    // bus implementation failure must never break the primitive's caller
+  }
+}
+
+export function isBusWired(): boolean {
+  return _bus !== null;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+//
+// @rocketlang/hanumang-mandate — Agent delegation credential + 7-axis posture scoring.
+//
+// Extracted from xshieldai-hanumang (the full Fastify service with SQLite-
+// backed attestations, Forja STATE/TRUST/SENSE/PROOF endpoints, and
+// Phase-2 regression alert routing). This package contains ONLY the
+// pure primitives — Mudrika credential verification + 7-axis scorer.
+//
+// COMPLEMENTARY to @rocketlang/aegis HanumanG (spawn-time governance):
+//   @rocketlang/aegis      → "Can this agent SPAWN?" (PreToolUse gate)
+//   @rocketlang/hanumang-mandate → "Is this agent's MANDATE valid?" + posture
+//
+// Public surface:
+//   import {
+//     verifyMudrika, scoreAxis, computePostureScore,
+//   } from '@rocketlang/hanumang-mandate';
+
+export {
+  verifyMudrika,
+} from './mudrika.js';
+
+export type {
+  MudrikaPayload,
+  VerifyOutcome,
+  VerifyResult,
+} from './mudrika.js';
+
+export {
+  scoreAxis,
+  computePostureScore,
+} from './scorer.js';
+
+export type {
+  Axis,
+  AxisOutcome,
+  AxisInput,
+  AxisScore,
+  PostureScore,
+} from './scorer.js';
+
+// @rule:ACC-003 — Opt-in event bus for Agentic Control Center observability.
+//                 Stateless contract preserved (ACC-YK-003): emit is no-op
+//                 when setEventBus has not been called. v0.2.0+.
+export {
+  type AccReceipt,
+  type EventBus,
+  setEventBus,
+  isBusWired,
+} from './acc-bus.js';

package/src/mudrika.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+// See LICENSE for details.
+
+// HanumanG — Mudrika verification engine
+// @rule:HNG-S-001 — mudrika is the mandatory delegation credential; no mudrika = refuse
+// @rule:HNG-S-008 — mudrika structure: principal_id, agent_id, trust_mask, scope_key, ttl, pramana_chain
+// @rule:HNG-S-009 — mudrika TTL must not be expired at verification time
+// @rule:HNG-S-010 — trust_mask in mudrika must be ≤ trust_mask of principal (spawn invariant)
+// @rule:HNG-S-011 — revocation_url must be reachable; REVOKED mudrikas refuse immediately
+//
+// PHASE-1 LIMIT: verifyMudrika() validates STRUCTURE + TTL + trust_mask range only.
+// It does NOT cryptographically verify the `signature` field. Phase-2 will add
+// signature verification. Today, mudrika trust is assumed to come from an
+// authenticated channel; callers must verify provenance themselves.
+
+import { emitAccReceipt } from './acc-bus.js';
+
+export interface MudrikaPayload {
+  mudrika_version: string;
+  mudrika_id: string;
+  principal_id: string;
+  agent_id: string;
+  task_id: string;
+  trust_mask: number;
+  scope_key: string;
+  issued_at: string;
+  ttl_seconds: number;
+  required_return_proof: string;
+  revocation_url: string;
+  pramana_chain: string[];
+  signature?: string;
+}
+
+export type VerifyOutcome = 'PASS' | 'FAIL' | 'EXPIRED' | 'REVOKED';
+
+export interface VerifyResult {
+  outcome: VerifyOutcome;
+  failure_reason: string | null;
+  expires_at: string;
+  trust_mask: number;
+  scope_key: string;
+  principal_id: string;
+  mudrika_id: string;
+  pramana_chain: string[];
+  duration_ms: number;
+}
+
+export function verifyMudrika(raw: unknown, expected_agent_id?: string): VerifyResult {
+  const t0 = Date.now();
+
+  if (!raw || typeof raw !== 'object') {
+    return fail('mudrika_missing', t0);
+  }
+
+  const m = raw as Partial<MudrikaPayload>;
+
+  // Required fields
+  if (
+    !m.mudrika_id ||
+    !m.principal_id ||
+    !m.agent_id ||
+    !m.task_id ||
+    !m.scope_key ||
+    !m.issued_at ||
+    !m.ttl_seconds
+  ) {
+    return fail('missing_required_fields', t0);
+  }
+
+  // Agent ID must match if provided
+  if (expected_agent_id && m.agent_id !== expected_agent_id) {
+    return fail(`agent_id_mismatch: expected ${expected_agent_id} got ${m.agent_id}`, t0);
+  }
+
+  // TTL check — @rule:HNG-S-009
+  const issuedAt = new Date(m.issued_at).getTime();
+  if (isNaN(issuedAt)) return fail('invalid_issued_at', t0);
+  const expiresAt = new Date(issuedAt + (m.ttl_seconds ?? 0) * 1000);
+  if (Date.now() > expiresAt.getTime()) {
+    const expiredResult: VerifyResult = {
+      outcome: 'EXPIRED',
+      failure_reason: `mudrika expired at ${expiresAt.toISOString()}`,
+      expires_at: expiresAt.toISOString(),
+      trust_mask: m.trust_mask ?? 0,
+      scope_key: m.scope_key ?? '',
+      principal_id: m.principal_id ?? '',
+      mudrika_id: m.mudrika_id ?? '',
+      pramana_chain: m.pramana_chain ?? [],
+      duration_ms: Date.now() - t0,
+    };
+    emitAccReceipt({
+      receipt_id: `hanumang-mudrika-expired-${m.mudrika_id ?? t0}`,
+      event_type: 'mudrika.rejected',
+      agent_id: m.agent_id,
+      verdict: 'EXPIRED',
+      rules_fired: ['HNG-S-009'],
+      summary: `mudrika ${m.mudrika_id ?? '?'} expired at ${expiresAt.toISOString()}`,
+    });
+    return expiredResult;
+  }
+
+  // Spawn invariant — child trust_mask ≤ declared maximum (32-bit)
+  // @rule:HNG-S-010 + BitMask OS spawn invariant
+  const trust_mask = m.trust_mask ?? 0;
+  if (trust_mask < 0 || trust_mask > 0xffffffff) {
+    return fail('trust_mask_out_of_range', t0);
+  }
+
+  // Pramana chain present (warning if empty — not blocking at verification stage)
+  const pramana_chain = m.pramana_chain ?? [];
+
+  const result: VerifyResult = {
+    outcome: 'PASS',
+    failure_reason: null,
+    expires_at: expiresAt.toISOString(),
+    trust_mask,
+    scope_key: m.scope_key,
+    principal_id: m.principal_id,
+    mudrika_id: m.mudrika_id,
+    pramana_chain,
+    duration_ms: Date.now() - t0,
+  };
+
+  // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt for cockpit observability
+  emitAccReceipt({
+    receipt_id: `hanumang-mudrika-${m.mudrika_id}`,
+    event_type: 'mudrika.verified',
+    agent_id: m.agent_id,
+    verdict: 'PASS',
+    rules_fired: ['HNG-S-008', 'HNG-S-009', 'HNG-S-010'],
+    summary: `mudrika ${m.mudrika_id} verified for ${m.principal_id} → ${m.agent_id} scope=${m.scope_key}`,
+    payload: {
+      trust_mask,
+      expires_at: result.expires_at,
+      pramana_chain_depth: pramana_chain.length,
+      duration_ms: result.duration_ms,
+    },
+  });
+
+  return result;
+}
+
+function fail(reason: string, t0: number): VerifyResult {
+  const result: VerifyResult = {
+    outcome: 'FAIL',
+    failure_reason: reason,
+    expires_at: new Date().toISOString(),
+    trust_mask: 0,
+    scope_key: '',
+    principal_id: '',
+    mudrika_id: '',
+    pramana_chain: [],
+    duration_ms: Date.now() - t0,
+  };
+
+  // @rule:ACC-003 — emit failure receipt for cockpit observability
+  emitAccReceipt({
+    receipt_id: `hanumang-mudrika-fail-${t0}`,
+    event_type: 'mudrika.rejected',
+    verdict: 'FAIL',
+    rules_fired: ['HNG-S-008', 'HNG-S-009', 'HNG-S-010'],
+    summary: `mudrika rejected: ${reason}`,
+  });
+
+  return result;
+}

package/src/scorer.ts

@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+// See LICENSE for details.
+
+// HanumanG — 7-axis posture scorer
+// @rule:HNG-S-001  axis 1: mudrika integrity
+// @rule:HNG-S-002  axis 2: identity broadcast
+// @rule:HNG-S-003  axis 3: mandate bounds
+// @rule:HNG-S-004  axis 4: proportional force
+// @rule:HNG-S-005  axis 5: return with proof
+// @rule:HNG-S-006  axis 6: no overreach
+// @rule:HNG-S-007  axis 7: truthful report
+// @rule:HNG-YK-001 — aggregate grade uses worst-axis floor, not average
+
+import { emitAccReceipt } from './acc-bus.js';
+
+export type Axis =
+  | 'mudrika_integrity'
+  | 'identity_broadcast'
+  | 'mandate_bounds'
+  | 'proportional_force'
+  | 'return_with_proof'
+  | 'no_overreach'
+  | 'truthful_report';
+
+export type AxisOutcome = 'PASS' | 'WARN' | 'FAIL';
+
+export interface AxisInput {
+  axis: Axis;
+  // Axis 1: mudrika integrity
+  mudrika_verified?: boolean;
+  mudrika_ttl_remaining_s?: number;
+  pramana_chain_depth?: number;
+  // Axis 2: identity broadcast
+  self_declared?: boolean;
+  declared_fields?: string[];
+  // Axis 3: mandate bounds
+  trust_mask_granted?: number;
+  trust_mask_requested?: number;
+  scope_key_match?: boolean;
+  ttl_respected?: boolean;
+  // Axis 4: proportional force
+  response_mode?: 1 | 2 | 3;
+  standing_order_exists?: boolean;
+  // Axis 5: return with proof
+  receipt_filed?: boolean;
+  receipt_signed?: boolean;
+  actions_listed?: boolean;
+  deviations_reported?: boolean;
+  // Axis 6: no overreach
+  trust_mask_used?: number;
+  // Axis 7: truthful report
+  before_state_present?: boolean;
+  after_state_present?: boolean;
+  errors_reported?: boolean;
+  human_modified_flagged?: boolean;
+  // shared
+  task_id?: string;
+  evidence?: string;
+}
+
+export interface AxisScore {
+  axis: Axis;
+  score: number;
+  outcome: AxisOutcome;
+  rule_id: string;
+  notes: string[];
+}
+
+export interface PostureScore {
+  overall_score: number;
+  overall_grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  axes: Record<Axis, AxisScore>;
+  violation_count: number;
+  warn_count: number;
+}
+
+const AXIS_RULES: Record<Axis, string> = {
+  mudrika_integrity: 'HNG-S-001',
+  identity_broadcast: 'HNG-S-002',
+  mandate_bounds: 'HNG-S-003',
+  proportional_force: 'HNG-S-004',
+  return_with_proof: 'HNG-S-005',
+  no_overreach: 'HNG-S-006',
+  truthful_report: 'HNG-S-007',
+};
+
+export function scoreAxis(input: AxisInput): AxisScore {
+  const notes: string[] = [];
+  let score = 100;
+
+  switch (input.axis) {
+    case 'mudrika_integrity': {
+      // @rule:HNG-S-001 — no mudrika = FAIL immediately
+      if (!input.mudrika_verified) {
+        score = 0;
+        notes.push('mudrika absent or failed verification');
+        break;
+      }
+      if ((input.mudrika_ttl_remaining_s ?? 60) < 30) {
+        score -= 20;
+        notes.push('mudrika expires in <30s');
+      }
+      if ((input.pramana_chain_depth ?? 0) === 0) {
+        score -= 10;
+        notes.push('empty pramana chain');
+      }
+      break;
+    }
+
+    case 'identity_broadcast': {
+      // @rule:HNG-S-002 — no self-declaration = FAIL
+      if (!input.self_declared) {
+        score = 0;
+        notes.push('agent did not self-declare before action');
+        break;
+      }
+      const required = ['agentId', 'agentType', 'officerRole', 'scopeKey', 'taskId', 'delegatedBy'];
+      const declared = input.declared_fields ?? [];
+      const missing = required.filter((f) => !declared.includes(f));
+      if (missing.length > 0) {
+        score -= missing.length * 10;
+        notes.push(`missing declaration fields: ${missing.join(', ')}`);
+      }
+      break;
+    }
+
+    case 'mandate_bounds': {
+      // @rule:HNG-S-003 — exceeding any bound = immediate FAIL
+      if (input.trust_mask_requested !== undefined && input.trust_mask_granted !== undefined) {
+        // spawn invariant: child cannot request bits parent doesn't have
+        if ((input.trust_mask_requested & ~input.trust_mask_granted) !== 0) {
+          score = 0;
+          notes.push(
+            `trust_mask_requested(${input.trust_mask_requested}) exceeds trust_mask_granted(${input.trust_mask_granted})`
+          );
+          break;
+        }
+      }
+      if (input.scope_key_match === false) {
+        score = 0;
+        notes.push('action outside declared scope_key');
+        break;
+      }
+      if (input.ttl_respected === false) {
+        score -= 40;
+        notes.push('action attempted after TTL expiry');
+      }
+      break;
+    }
+
+    case 'proportional_force': {
+      // @rule:HNG-S-004 — mode must be correctly routed
+      const mode = input.response_mode ?? 1;
+      if (mode === 2 && !input.standing_order_exists) {
+        score = 0;
+        notes.push('mode-2 execution without prior standing order');
+        break;
+      }
+      if (mode === 3) {
+        notes.push('mode-3 existential action: always permitted');
+      }
+      break;
+    }
+
+    case 'return_with_proof': {
+      // @rule:HNG-S-005 — incomplete receipt = FAIL
+      if (!input.receipt_filed) {
+        score = 0;
+        notes.push('task closed without return receipt');
+        break;
+      }
+      if (!input.receipt_signed) {
+        score -= 30;
+        notes.push('receipt unsigned (SAKSHI countersign missing)');
+      }
+      if (!input.actions_listed) {
+        score -= 30;
+        notes.push('actions_taken list absent in receipt');
+      }
+      if (!input.deviations_reported && input.deviations_reported !== undefined) {
+        score -= 20;
+        notes.push('deviations not reported');
+      }
+      break;
+    }
+
+    case 'no_overreach': {
+      // @rule:HNG-S-006 — used bits vs granted bits
+      const granted = input.trust_mask_granted ?? 0;
+      const used = input.trust_mask_used ?? 0;
+      if (granted === 0) break;
+      // Bits used that were not granted = overreach
+      if ((used & ~granted) !== 0) {
+        score = 0;
+        notes.push(`overreach: used bits ${used & ~granted} not in granted mask`);
+        break;
+      }
+      const grantedBits = popcount(granted);
+      const usedBits = popcount(used);
+      const utilisation = grantedBits > 0 ? usedBits / grantedBits : 0;
+      if (utilisation > 0.8) {
+        score -= 20;
+        notes.push(
+          `high utilisation ${Math.round(utilisation * 100)}%: over-provisioning signal (HNG-S-006)`
+        );
+      }
+      break;
+    }
+
+    case 'truthful_report': {
+      // @rule:HNG-S-007 — omission = violation
+      if (!input.before_state_present) {
+        score -= 30;
+        notes.push('before_state absent (CA-003 / HNG-S-007)');
+      }
+      if (!input.after_state_present) {
+        score -= 30;
+        notes.push('after_state absent (CA-003 / HNG-S-007)');
+      }
+      if (input.errors_reported === false) {
+        score -= 20;
+        notes.push('errors not reported (truthful report violated)');
+      }
+      if (input.human_modified_flagged === false) {
+        score -= 10;
+        notes.push('human_modified not declared (CA-005)');
+      }
+      break;
+    }
+  }
+
+  score = Math.max(0, Math.min(100, score));
+  const outcome: AxisOutcome = score >= 80 ? 'PASS' : score >= 50 ? 'WARN' : 'FAIL';
+  const result: AxisScore = { axis: input.axis, score, outcome, rule_id: AXIS_RULES[input.axis], notes };
+
+  // @rule:ACC-003 — emit per-axis score (no-op when bus unset)
+  emitAccReceipt({
+    receipt_id: `hanumang-axis-${input.axis}-${input.task_id ?? 'unspec'}-${Date.now()}`,
+    event_type: 'posture.axis_scored',
+    agent_id: undefined,
+    verdict: outcome,
+    rules_fired: [result.rule_id],
+    summary: `axis=${input.axis} score=${score} outcome=${outcome} task=${input.task_id ?? 'unspec'}`,
+    payload: { axis: input.axis, score, notes: notes.slice(0, 5) },
+  });
+
+  return result;
+}
+
+export function computePostureScore(axisScores: AxisScore[]): PostureScore {
+  // @rule:HNG-YK-001 — worst-axis floor: a single FAIL caps the grade at D
+  const scores = axisScores.map((a) => a.score);
+  const overall_score =
+    scores.length > 0 ? Math.round(scores.reduce((s, n) => s + n, 0) / scores.length) : 0;
+  const violation_count = axisScores.filter((a) => a.outcome === 'FAIL').length;
+  const warn_count = axisScores.filter((a) => a.outcome === 'WARN').length;
+
+  let overall_grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  if (violation_count > 0) {
+    overall_grade = violation_count >= 3 ? 'F' : 'D';
+  } else if (overall_score >= 90) {
+    overall_grade = 'A';
+  } else if (overall_score >= 80) {
+    overall_grade = 'B';
+  } else if (overall_score >= 60) {
+    overall_grade = 'C';
+  } else {
+    overall_grade = 'D';
+  }
+
+  const axes: Record<Axis, AxisScore> = {} as Record<Axis, AxisScore>;
+  for (const a of axisScores) axes[a.axis as Axis] = a;
+
+  const result: PostureScore = { overall_score, overall_grade, axes, violation_count, warn_count };
+
+  // @rule:ACC-003 @rule:HNG-YK-001 — emit aggregate posture (worst-axis floor)
+  const verdict =
+    overall_grade === 'A' || overall_grade === 'B' ? 'PASS'
+    : overall_grade === 'C' ? 'WARN'
+    : 'FAIL';
+  emitAccReceipt({
+    receipt_id: `hanumang-posture-${Date.now()}`,
+    event_type: 'posture.scored',
+    verdict: `${overall_grade}-${verdict}`,
+    rules_fired: ['HNG-YK-001'],
+    summary: `posture grade=${overall_grade} score=${overall_score}/100 violations=${violation_count} warns=${warn_count}`,
+    payload: { overall_score, overall_grade, violation_count, warn_count, axes_evaluated: axisScores.length },
+  });
+
+  return result;
+}
+
+function popcount(n: number): number {
+  let count = 0;
+  let x = n >>> 0;
+  while (x) {
+    count += x & 1;
+    x >>>= 1;
+  }
+  return count;
+}