@rocketlang/aegis-guard 0.1.0 → 0.2.0

package/README.md

@@ -127,3 +127,89 @@ const redisNonceStore: NonceStore = {
 ## License
 
 AGPL-3.0 — Capt. Anil Sharma, powerpbox.org
+
+---
+
+## v0.2.0 — Opt-in Agentic Control Center (ACC) event bus
+
+Added 2026-05-17. Each Five Locks primitive now emits an `AccReceipt` on
+success or failure, **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/aegis-guard';
+
+const myBus: EventBus = {
+  emit: (r: AccReceipt) => console.log(`[ACC] ${r.event_type} verdict=${r.verdict} ${r.summary}`),
+};
+setEventBus(myBus);
+```
+
+Now every primitive call emits a receipt. Pass `null` to `setEventBus` to detach.
+
+### Receipt events emitted
+
+| Primitive | event_type on success | event_type on failure |
+|---|---|---|
+| `verifyApprovalToken` | `lock.approval.verified` (PASS) | `lock.approval.rejected` (FAIL) |
+| `verifyAndConsumeNonce` | `lock.nonce.consumed` (PASS) | `lock.nonce.rejected` (FAIL) |
+| `checkIdempotency` | `lock.idempotency.duplicate` (PASS) OR `lock.idempotency.mismatch` (WARN) | (no event for non-duplicate path) |
+| `emitAegisSenseEvent` | `lock.sense.emitted` (PASS or WARN if irreversible) | — |
+
+### Receipt shape
+
+```typescript
+interface AccReceipt {
+  receipt_id: string;       // primitive-prefixed identifier
+  primitive: string;        // always 'aegis-guard' for this package
+  event_type: string;       // lock.*
+  emitted_at: string;       // ISO 8601
+  agent_id?: string;        // reserved — not yet populated by aegis-guard
+  verdict?: string;         // PASS | FAIL | WARN
+  rules_fired?: string[];   // e.g. ['AEG-E-016']
+  summary?: string;         // ≤200 chars
+  payload?: Record<string, unknown>;
+}
+```
+
+The shape is a strict subset of the EE PRAMANA receipt format. EE
+consumers ingest these events without translation.
+
+### Phase-1 limits (v0.2.0)
+
+- **agent_id is not yet populated** — primitives don't receive an agent
+  context as parameter. Future versions may add an optional `agent_id`
+  argument to each primitive; today you can post-process receipts in the
+  bus to add agent context from your own tracking.
+- **`buildIdempotencyFingerprint`, `digestApprovalToken`, `mintApprovalToken`
+  do NOT emit** — they're pure helpers called many times per operation.
+  Emitting from them would flood the bus.
+- **`buildQualityMaskAtPromotion`, `buildQualityDriftScore`,
+  `meetsHgQualityRequirement` do NOT emit** — quality computation is
+  scoring, not a governance decision. They're called during promotion
+  decisions; the calling code emits the governance event.
+- **Default bus is in-process only.** Multi-process buses (Redis-backed,
+  etc.) are a consumer choice — implement the `EventBus` interface and
+  call `setEventBus(yourBus)`.
+
+### Use with `@rocketlang/aegis-suite`
+
+If you installed the meta-package, you can wire all 6 primitives in one call:
+
+```typescript
+import { wireAllToBus } from '@rocketlang/aegis-suite';  // available in suite v0.2.0+
+wireAllToBus();  // default: in-memory bus + SQLite writer to ~/.aegis/acc-events.db
+```
+
+This sets up the bus on aegis-guard + chitta-detect + lakshmanrekha + hanumang-mandate
+all at once, and persists events for the Agentic Control Center page.
+
+### Discipline
+
+- **Stateless contract preserved.** Primitives hold no state beyond a
+  module-private bus reference. Pass `null` to `setEventBus` to detach.
+- **Emission must never throw.** If your bus implementation throws,
+  the primitive's caller is unaffected — the receipt is silently dropped.
+  This is intentional; observability must not break the governed path.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rocketlang/aegis-guard",
-  "version": "0.1.0",
-  "description": "AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services",
+  "version": "0.2.0",
+  "description": "AEGIS Guard SDK — Five Locks primitives (approval-token, nonce, idempotency, SENSE, quality-evidence) + opt-in Agentic Control Center event bus for AEGIS-governed services",
   "license": "AGPL-3.0-only",
   "type": "module",
   "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",

package/src/acc-bus.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+// See LICENSE for details.
+//
+// @rocketlang/aegis-guard — opt-in ACC event bus integration (v0.2.0)
+// @rule:ACC-003 — Opt-in event bus. 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. No bus = no emit.
+// @rule:INF-ACC-005 — emit() is a no-op when no bus has been set.
+
+/**
+ * Lightweight receipt shape — structurally compatible with the canonical
+ * AccReceipt in /root/aegis/src/acc/types.ts. Defined locally so
+ * this primitive can ship without depending on the ACC package.
+ */
+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;
+}
+
+// Module-private bus reference. null by default — emission is no-op.
+let _bus: EventBus | null = null;
+
+/**
+ * Opt-in: provide an event bus to receive lightweight ACC receipts
+ * for every Five Locks primitive call. Pass null to detach.
+ *
+ * Default behaviour (no bus set): primitives behave EXACTLY as v0.1.0 —
+ * no emission, no state, no side effect beyond their primary return value.
+ *
+ * @rule:ACC-003 @rule:ACC-YK-003
+ */
+export function setEventBus(bus: EventBus | null): void {
+  _bus = bus;
+}
+
+/**
+ * Internal helper — primitives call this to emit a receipt. No-op when
+ * no bus is set. MUST NOT throw — bus implementation handles delivery
+ * failures (ACC-YK-003 stateless contract).
+ *
+ * @rule:INF-ACC-005
+ */
+export function emitAccReceipt(receipt: Omit<AccReceipt, 'primitive' | 'emitted_at'>): void {
+  if (!_bus) return;
+  try {
+    _bus.emit({
+      ...receipt,
+      primitive: 'aegis-guard',
+      emitted_at: new Date().toISOString(),
+    });
+  } catch {
+    // bus implementation failure must never break the primitive's caller
+  }
+}
+
+/** Test/introspection helper — does the primitive have a bus set right now? */
+export function isBusWired(): boolean {
+  return _bus !== null;
+}

package/src/approval-token.ts

@@ -5,6 +5,7 @@
 import { createHash } from 'crypto';
 import { IrrNoApprovalError } from './errors.js';
 import { type NonceStore, defaultNonceStore } from './nonce.js';
+import { emitAccReceipt } from './acc-bus.js';
 
 // Token may arrive up to 60s before local clock (NTP tolerance).
 const CLOCK_SKEW_MS = 60_000;
@@ -41,48 +42,63 @@ export function verifyApprovalToken(
   expectedCapability: string,
   expectedOperation: string,
 ): ApprovalTokenPayload {
-  let payload: ApprovalTokenPayload;
-
+  // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt on success OR failure
+  const scope = `${expectedServiceId}/${expectedCapability}/${expectedOperation}`;
   try {
-    const decoded = Buffer.from(token, 'base64url').toString('utf8');
-    payload = JSON.parse(decoded) as ApprovalTokenPayload;
-  } catch {
-    throw new IrrNoApprovalError(expectedCapability, 'token could not be decoded');
-  }
-
-  if (payload.service_id !== expectedServiceId) {
-    throw new IrrNoApprovalError(
-      expectedCapability,
-      `AEG-E-016: token scoped to '${payload.service_id}', not '${expectedServiceId}'`,
-    );
-  }
-
-  if (payload.capability !== expectedCapability) {
-    throw new IrrNoApprovalError(
-      expectedCapability,
-      `AEG-E-016: token capability '${payload.capability}' does not match '${expectedCapability}'`,
-    );
-  }
-
-  if (payload.operation !== expectedOperation) {
-    throw new IrrNoApprovalError(
-      expectedCapability,
-      `AEG-E-016: token operation '${payload.operation}' does not match '${expectedOperation}'`,
-    );
-  }
+    let payload: ApprovalTokenPayload;
+    try {
+      const decoded = Buffer.from(token, 'base64url').toString('utf8');
+      payload = JSON.parse(decoded) as ApprovalTokenPayload;
+    } catch {
+      throw new IrrNoApprovalError(expectedCapability, 'token could not be decoded');
+    }
 
-  if (Date.now() > payload.expires_at) {
-    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token expired');
-  }
+    if (payload.service_id !== expectedServiceId) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        `AEG-E-016: token scoped to '${payload.service_id}', not '${expectedServiceId}'`,
+      );
+    }
+    if (payload.capability !== expectedCapability) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        `AEG-E-016: token capability '${payload.capability}' does not match '${expectedCapability}'`,
+      );
+    }
+    if (payload.operation !== expectedOperation) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        `AEG-E-016: token operation '${payload.operation}' does not match '${expectedOperation}'`,
+      );
+    }
+    if (Date.now() > payload.expires_at) {
+      throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token expired');
+    }
+    if (payload.issued_at !== undefined && payload.issued_at > Date.now() + CLOCK_SKEW_MS) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        'AEG-E-016: token issued_at is in the future (clock skew > 60s or forged timestamp)',
+      );
+    }
 
-  if (payload.issued_at !== undefined && payload.issued_at > Date.now() + CLOCK_SKEW_MS) {
-    throw new IrrNoApprovalError(
-      expectedCapability,
-      'AEG-E-016: token issued_at is in the future (clock skew > 60s or forged timestamp)',
-    );
+    emitAccReceipt({
+      receipt_id: `aegis-guard-verify-${digestApprovalToken(token)}`,
+      event_type: 'lock.approval.verified',
+      verdict: 'PASS',
+      rules_fired: ['AEG-E-016'],
+      summary: scope,
+    });
+    return payload;
+  } catch (err) {
+    emitAccReceipt({
+      receipt_id: `aegis-guard-verify-fail-${Date.now()}`,
+      event_type: 'lock.approval.rejected',
+      verdict: 'FAIL',
+      rules_fired: ['AEG-E-016'],
+      summary: `${scope} — ${(err as Error).message?.slice(0, 160) ?? 'verification failed'}`,
+    });
+    throw err;
   }
-
-  return payload;
 }
 
 // @rule:AEG-HG-2B-006 — consume nonce before any state mutation; missing nonce = hard reject.
@@ -91,19 +107,39 @@ export async function verifyAndConsumeNonce(
   payload: ApprovalTokenPayload,
   store: NonceStore = defaultNonceStore,
 ): Promise<void> {
-  if (!payload.nonce) {
-    throw new IrrNoApprovalError(
-      payload.capability,
-      'AEG-E-016: irreversible operation requires nonce for replay prevention',
-    );
-  }
-  const ttlMs = Math.max(0, payload.expires_at - Date.now());
-  const consumed = await store.consumeNonce(payload.nonce, ttlMs);
-  if (!consumed) {
-    throw new IrrNoApprovalError(
-      payload.capability,
-      `AEG-E-016: nonce '${payload.nonce}' already consumed — approval replay rejected`,
-    );
+  // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt on success OR failure
+  const scope = `${payload.service_id}/${payload.capability}/${payload.operation}`;
+  try {
+    if (!payload.nonce) {
+      throw new IrrNoApprovalError(
+        payload.capability,
+        'AEG-E-016: irreversible operation requires nonce for replay prevention',
+      );
+    }
+    const ttlMs = Math.max(0, payload.expires_at - Date.now());
+    const consumed = await store.consumeNonce(payload.nonce, ttlMs);
+    if (!consumed) {
+      throw new IrrNoApprovalError(
+        payload.capability,
+        `AEG-E-016: nonce '${payload.nonce}' already consumed — approval replay rejected`,
+      );
+    }
+    emitAccReceipt({
+      receipt_id: `aegis-guard-nonce-${payload.nonce}`,
+      event_type: 'lock.nonce.consumed',
+      verdict: 'PASS',
+      rules_fired: ['AEG-HG-2B-006'],
+      summary: scope,
+    });
+  } catch (err) {
+    emitAccReceipt({
+      receipt_id: `aegis-guard-nonce-fail-${Date.now()}`,
+      event_type: 'lock.nonce.rejected',
+      verdict: 'FAIL',
+      rules_fired: ['AEG-HG-2B-006'],
+      summary: `${scope} — ${(err as Error).message?.slice(0, 160) ?? 'nonce check failed'}`,
+    });
+    throw err;
   }
 }
 

package/src/idempotency.ts

@@ -1,6 +1,8 @@
 // @rule:AEG-HG-2B-006 — idempotency protects the operation; nonce protects the approval (separate locks)
 // Pattern: check DB for externalRef before mutating. Matching fingerprint = safe no-op. Mismatch = warn + reject.
 
+import { emitAccReceipt } from './acc-bus.js';
+
 export interface IdempotencyCheckResult {
   isDuplicate: boolean;
   payloadMismatch: boolean;
@@ -22,11 +24,21 @@ export function checkIdempotency(
   }
   const payloadMismatch =
     existingFingerprint !== undefined && existingFingerprint !== newFingerprint;
-  return {
+  const result: IdempotencyCheckResult = {
     isDuplicate: true,
     payloadMismatch,
     safeNoOp: !payloadMismatch,
   };
+  emitAccReceipt({
+    receipt_id: `aegis-guard-idem-${_externalRef}`,
+    event_type: payloadMismatch ? 'lock.idempotency.mismatch' : 'lock.idempotency.duplicate',
+    verdict: payloadMismatch ? 'WARN' : 'PASS',
+    rules_fired: ['AEG-HG-2B-006'],
+    summary: payloadMismatch
+      ? `duplicate externalRef ${_externalRef} with payload mismatch — caller must reject or escalate`
+      : `duplicate externalRef ${_externalRef} — safe no-op, return existing`,
+  });
+  return result;
 }
 
 // Build a stable base64 fingerprint from an arbitrary operation payload.

package/src/index.ts

@@ -1,8 +1,19 @@
 // @rocketlang/aegis-guard — AEGIS Guard SDK public API
 // Five Locks proved in carbonx-backend (batches 62-74). Batch 93 makes them reusable.
+// v0.2.0 adds opt-in Agentic Control Center (ACC) event bus integration.
 
 export { IrrNoApprovalError, AegisNonceError } from './errors.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';
+
 export { type NonceStore, defaultNonceStore } from './nonce.js';
 
 export {

package/src/sense.ts

@@ -33,6 +33,26 @@ export function configureSenseTransport(transport: SenseTransport): void {
 
 // @rule:CA-003 — all three snapshot fields are required by the type; callers must supply them.
 // approval_token_ref, if present, must already be the output of digestApprovalToken (AEG-HG-2B-005).
+// @rule:ACC-003 — also emit an ACC receipt for cockpit observability (no-op when bus unset).
 export function emitAegisSenseEvent(event: AegisSenseEvent): void {
   _transport(event);
+  emitAccReceiptFromSense(event);
+}
+
+import { emitAccReceipt } from './acc-bus.js';
+
+function emitAccReceiptFromSense(event: AegisSenseEvent): void {
+  emitAccReceipt({
+    receipt_id: `aegis-guard-sense-${event.correlation_id || Date.now()}`,
+    event_type: 'lock.sense.emitted',
+    verdict: event.irreversible ? 'WARN' : 'PASS',
+    rules_fired: ['CA-003', 'AEG-HG-2B-003', 'AEG-HG-2B-005'],
+    summary: `${event.service_id}/${event.capability}/${event.operation} ${event.irreversible ? '(irreversible)' : ''}`,
+    payload: {
+      event_type: event.event_type,
+      correlation_id: event.correlation_id,
+      approval_token_ref: event.approval_token_ref,
+      delta: event.delta,
+    },
+  });
 }