@rocketlang/chitta-detect 0.1.0 → 0.2.0

package/README.md

@@ -181,3 +181,66 @@ AGPL-3.0-only. The full chitta-guard service is BSL-1.1 (converts to AGPL-3.0 af
 See [LICENSE](LICENSE) for the AGPL-3.0 terms. Any modified version run as a network service must publish source per AGPL clause 13.
 
 For commercial dual-licensing or EE-tier access: [captain@ankr.in](mailto:captain@ankr.in).
+
+---
+
+## v0.2.0 — Opt-in Agentic Control Center (ACC) event bus
+
+Added 2026-05-17. `scan.evaluate()` now emits an `AccReceipt` on every
+scan, **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/chitta-detect';
+
+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 |
+|---|---|---|
+| `scan.evaluate` | `scan.evaluated` | PASS / ADVISORY / INJECT_SUSPECT / BLOCK |
+
+### Receipt shape
+
+```typescript
+interface AccReceipt {
+  receipt_id: string;       // primitive-prefixed (cg-scan-{ts}-{counter})
+  primitive: string;        // always 'chitta-detect'
+  event_type: string;       // 'scan.evaluated'
+  emitted_at: string;       // ISO 8601
+  agent_id?: string;        // copied from agentContext.agent_id
+  verdict?: string;         // PASS | ADVISORY | INJECT_SUSPECT | BLOCK
+  rules_fired?: string[];   // e.g. ['CG-006', 'CG-003', 'INF-CG-002']
+  summary?: string;         // "{scan_type} → {verdict} (confidence=X, action=Y)"
+  payload?: Record<string, unknown>; // scan_type, posture, confidence, fingerprint_matched, tool_output_classification
+}
+```
+
+Strict subset of EE PRAMANA receipt format — EE consumers ingest without translation.
+
+### Phase-1 limits (v0.2.0)
+
+- **Only `scan.evaluate` emits** — the orchestrator that combines all
+  detectors. Individual detector primitives (`fingerprint.scan`,
+  `imperative.scan`, `trust.resolve`, `toolOutput.classify`,
+  `capabilityExpansion.scan`, `rateLimit.check`, `retrospective.audit`)
+  do NOT emit independently. Reasoning: emitting from every detector
+  would flood the bus (a single `scan.evaluate` call runs 4+ detectors).
+  If you call detectors directly outside `scan.evaluate`, no event is
+  emitted — that's a Phase-1 limit.
+- **Default bus is in-process only.** Multi-process buses (Redis-backed,
+  etc.) 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

@@ -1,7 +1,7 @@
 {
   "name": "@rocketlang/chitta-detect",
-  "version": "0.1.0",
-  "description": "Memory poisoning detection primitives for AI agents — pure pattern matchers (RAG trust, agent-role imperatives, tool-output poisoning, capability expansion, injection fingerprints). Extracted from chitta-guard.",
+  "version": "0.2.0",
+  "description": "Memory poisoning detection primitives for AI agents — pure pattern matchers (RAG trust, agent-role imperatives, tool-output poisoning, capability expansion, injection fingerprints) + opt-in Agentic Control Center event bus. Extracted from chitta-guard.",
   "license": "AGPL-3.0-only",
   "type": "module",
   "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",

package/src/acc-bus.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
+// See LICENSE for details.
+//
+// @rocketlang/chitta-detect — 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. 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 chitta-detect orchestrator call. Pass null to detach.
+ *
+ * Without setEventBus, v0.2.0 behaves identically to v0.1.0 — no
+ * emission, no state, no side effect.
+ *
+ * @rule:ACC-003 @rule:ACC-YK-003
+ */
+export function setEventBus(bus: EventBus | null): void {
+  _bus = bus;
+}
+
+/**
+ * Internal helper — emit a receipt. No-op when no bus is set.
+ * MUST NOT throw — bus implementation handles delivery failures.
+ *
+ * @rule:INF-ACC-005
+ */
+export function emitAccReceipt(receipt: Omit<AccReceipt, 'primitive' | 'emitted_at'>): void {
+  if (!_bus) return;
+  try {
+    _bus.emit({
+      ...receipt,
+      primitive: 'chitta-detect',
+      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/index.ts

@@ -31,6 +31,16 @@ export * as rateLimit from './rate-limit.js';
 export * as retrospective from './retrospective.js';
 export * as scan from './scan.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';
+
 // Re-export the types most consumers will name explicitly
 export type { SourceMetadata, TrustClassification, TrustClassifyResult } from './trust.js';
 export type { ImperativeScanResult } from './imperative.js';

package/src/scan.ts

@@ -13,6 +13,7 @@ import { resolve as resolveTrust } from './trust.js';
 import { scan as fingerprintScan } from './fingerprint.js';
 import { classify as classifyToolOutput } from './tool-output.js';
 import type { SourceMetadata } from './trust.js';
+import { emitAccReceipt } from './acc-bus.js';
 
 export type ScanVerdict = 'PASS' | 'ADVISORY' | 'INJECT_SUSPECT' | 'BLOCK';
 
@@ -140,7 +141,26 @@ export function evaluate(
     verdict = 'PASS';
   }
 
-  return buildResult(scan_id, verdict, combinedConfidence, rules_fired, imp, fp, trust, toolOutputClassification, scanned_at);
+  const result = buildResult(scan_id, verdict, combinedConfidence, rules_fired, imp, fp, trust, toolOutputClassification, scanned_at);
+
+  // @rule:ACC-003 @rule:ACC-004 — emit cockpit receipt (no-op when bus unset)
+  emitAccReceipt({
+    receipt_id: scan_id,
+    event_type: 'scan.evaluated',
+    agent_id: agentContext.agent_id,
+    verdict: result.verdict,
+    rules_fired: result.rules_fired,
+    summary: `${agentContext.scan_type ?? 'memory_write'} → ${result.verdict} (confidence=${result.confidence}, action=${result.action})`,
+    payload: {
+      scan_type: agentContext.scan_type,
+      posture: agentContext.posture,
+      confidence: result.confidence,
+      fingerprint_matched: result.details.fingerprint_matched,
+      tool_output_classification: result.details.tool_output_classification,
+    },
+  });
+
+  return result;
 }
 
 function buildResult(