@beingmartinbmc/ojas 0.2.0 → 0.4.0

package/dist/scorecard/index.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Ojas Scorecard — shareable, self-contained snapshots of agent health.
+ *
+ * A scorecard is the distribution surface for Ojas: it turns the rich
+ * `AgentHealthReport` into a compact, render-agnostic structure that the
+ * badge generator, CLI, GitHub Action, and live dashboard all consume.
+ *
+ * Design rules carried over from the rest of Ojas:
+ *   - **Honest framing.** A scorecard never claims more than the report
+ *     does. The `basis` and `interpretation` fields from `HealthScore`
+ *     are propagated verbatim so a badge can never imply an empirical
+ *     probability the underlying score does not have.
+ *   - **No I/O here.** This module is pure data → data. Rendering to SVG
+ *     lives in `./badge`, file/HTTP side effects live in the CLI.
+ *   - **Backwards compatible.** Consuming a report produced by any 0.3.x
+ *     Ojas build must succeed; new fields are optional.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gradeFor = gradeFor;
+exports.buildScorecard = buildScorecard;
+exports.gradeLabel = gradeLabel;
+exports.gradeEmoji = gradeEmoji;
+exports.renderScorecardText = renderScorecardText;
+exports.renderScorecardMarkdown = renderScorecardMarkdown;
+const MODULE_ORDER = [
+    'aahar',
+    'nidra',
+    'vyayam',
+    'raksha',
+    'agni',
+    'pulse',
+    'chikitsa',
+];
+/**
+ * Grade thresholds. Tuned to align with `classifyHealthState` in the MCP
+ * contracts (healthy ≥ 90, watch ≥ 70) but extended with an `excellent`
+ * band so a near-perfect agent is visually distinct from a merely healthy
+ * one — important for the badge/leaderboard where small gaps matter.
+ */
+function gradeFor(score) {
+    if (score >= 95)
+        return 'excellent';
+    if (score >= 90)
+        return 'healthy';
+    if (score >= 70)
+        return 'watch';
+    if (score >= 50)
+        return 'degraded';
+    return 'critical';
+}
+function buildModules(scores) {
+    return MODULE_ORDER.map((module) => {
+        const score = scores[module];
+        return { module, score, grade: gradeFor(score) };
+    });
+}
+/**
+ * Build a shareable scorecard from a full health report. Pure function —
+ * the same report always yields the same scorecard (modulo the report's
+ * own timestamp, which is copied through).
+ */
+function buildScorecard(report, opts = {}) {
+    const maxRisks = opts.maxRisks ?? 5;
+    const maxActions = opts.maxActions ?? 6;
+    const overall = Math.round(report.overall.value * 100);
+    // Risks: warning/critical recommendations, most severe first.
+    const severityRank = { critical: 0, warning: 1, info: 2 };
+    const topRisks = report.recommendations
+        .filter((r) => r.severity !== 'info')
+        .slice()
+        .sort((a, b) => severityRank[a.severity] - severityRank[b.severity])
+        .slice(0, maxRisks)
+        .map((r) => ({ module: r.module, severity: r.severity, message: r.message, action: r.action }));
+    // Actions: deduplicated concrete next steps from non-info recommendations.
+    const recommendedActions = [
+        ...new Set(report.recommendations
+            .filter((r) => r.severity !== 'info' && r.action)
+            .map((r) => r.action)),
+    ].slice(0, maxActions);
+    const requiresHumanReview = report.recommendations.some((r) => r.severity === 'critical');
+    return {
+        agentId: report.agentId,
+        timestamp: report.timestamp,
+        overall,
+        grade: gradeFor(overall),
+        basis: report.overall.basis ?? 'heuristic',
+        interpretation: report.overall.interpretation ??
+            'Advisory diagnostic score. Use for triage and trend deltas, not as a production failure probability.',
+        modules: buildModules(report.moduleScores),
+        topRisks,
+        recommendedActions,
+        requiresHumanReview,
+        schemaVersion: 1,
+    };
+}
+const GRADE_LABEL = {
+    excellent: 'Excellent',
+    healthy: 'Healthy',
+    watch: 'Watch',
+    degraded: 'Degraded',
+    critical: 'Critical',
+};
+const GRADE_EMOJI = {
+    excellent: '🟢',
+    healthy: '🟢',
+    watch: '🟡',
+    degraded: '🟠',
+    critical: '🔴',
+};
+function gradeLabel(grade) {
+    return GRADE_LABEL[grade];
+}
+function gradeEmoji(grade) {
+    return GRADE_EMOJI[grade];
+}
+/**
+ * Render a scorecard as a compact, copy-pasteable plain-text card for the
+ * terminal. No ANSI colour so output is safe to redirect to a file.
+ */
+function renderScorecardText(card) {
+    const lines = [];
+    lines.push(`Ojas Health Scorecard — ${card.agentId}`);
+    lines.push('='.repeat(44));
+    lines.push(`Overall: ${card.overall}/100  ${gradeEmoji(card.grade)} ${gradeLabel(card.grade)}`);
+    lines.push(`Basis:   ${card.basis}`);
+    lines.push('');
+    lines.push('Modules');
+    for (const m of card.modules) {
+        const bar = '█'.repeat(Math.round(m.score / 10)).padEnd(10, '·');
+        lines.push(`  ${m.module.padEnd(9)} ${String(m.score).padStart(3)}  ${bar} ${gradeEmoji(m.grade)}`);
+    }
+    if (card.topRisks.length > 0) {
+        lines.push('');
+        lines.push('Top risks');
+        for (const r of card.topRisks) {
+            lines.push(`  [${r.severity.toUpperCase()}] ${r.message}`);
+        }
+    }
+    if (card.recommendedActions.length > 0) {
+        lines.push('');
+        lines.push('Recommended next steps');
+        for (const a of card.recommendedActions) {
+            lines.push(`  • ${a}`);
+        }
+    }
+    lines.push('');
+    lines.push(card.interpretation);
+    return lines.join('\n');
+}
+/**
+ * Render a scorecard as GitHub-flavoured Markdown — used by the CLI's
+ * `--format markdown` and by the GitHub Action's PR comment.
+ */
+function renderScorecardMarkdown(card) {
+    const lines = [];
+    lines.push(`### ${gradeEmoji(card.grade)} Ojas Health — \`${card.agentId}\``);
+    lines.push('');
+    lines.push(`**Overall: ${card.overall}/100 (${gradeLabel(card.grade)})**`);
+    lines.push('');
+    lines.push('| Module | Score | Grade |');
+    lines.push('| --- | --- | --- |');
+    for (const m of card.modules) {
+        lines.push(`| ${m.module} | ${m.score} | ${gradeEmoji(m.grade)} ${gradeLabel(m.grade)} |`);
+    }
+    if (card.topRisks.length > 0) {
+        lines.push('');
+        lines.push('**Top risks**');
+        lines.push('');
+        for (const r of card.topRisks) {
+            lines.push(`- \`${r.severity}\` ${r.message}`);
+        }
+    }
+    if (card.recommendedActions.length > 0) {
+        lines.push('');
+        lines.push('**Recommended next steps**');
+        lines.push('');
+        for (const a of card.recommendedActions) {
+            lines.push(`- ${a}`);
+        }
+    }
+    lines.push('');
+    lines.push(`<sub>${card.interpretation}</sub>`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/scorecard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scorecard/index.ts"],"names":[],"mappings":"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"}

package/docs/BACKLOG.md

@@ -81,7 +81,7 @@ What's still open is below.
 ## Trust roadmap
 
 The single biggest open question for this project is *"does it actually
-help an agent?"*. v0.2 ships at evidence level L2 / L2.5 (synthetic
+help an agent?"*. v0.3 ships at evidence level L2 / L2.5 (synthetic
 reproducible benchmarks); the roadmap below moves it toward L3 (realistic
 agent tasks) and L4 (production telemetry). Each phase is independently
 landable.
@@ -148,7 +148,7 @@ All items in this phase have been shipped:
   anger to opt-in to anonymised aggregate stats (failure detection
   precision / recall, score-vs-incident correlation) — *still open*.
 
-## Reframed as a v0.2 non-goal, not deferred work
+## Reframed as a v0.3 non-goal, not deferred work
 
 ### MCP authentication / authorization on the boundary
 Multiple review rounds flagged "no caller authentication" as critical /

package/docs/EVIDENCE.md

@@ -2,14 +2,14 @@
 
 > **Auto-generated by `npm run benchmark:write`. Do not edit by hand.**
 
-- **ojas**: `0.2.0`
-- **node**: `v24.15.0`
-- **timestamp**: 2026-05-14T08:51:51.214Z
-- **suites**: 11/11 passed — targeted failure suites improved and diagnostic/no-regression suites met their acceptance criteria.
+- **ojas**: `0.4.0`
+- **node**: `v25.9.0`
+- **timestamp**: 2026-06-07T09:07:46.375Z
+- **suites**: 18/18 passed — targeted failure suites improved and diagnostic/no-regression suites met their acceptance criteria.
 
 ## What this measures
 
-11 A/B benchmarks comparing a deliberately vulnerable agent running **without Ojas** vs the **same agent + Ojas**. Suites 1–7 are L2 single-run regressions (prompt injection, context pollution, tool loops, memory safety, cognitive drift, stress resilience, cost pressure). Suite 8 is L2.5 — a realistic retrieval-QA benchmark with **seeded fixtures**, **bootstrap 95 % confidence intervals** across multiple seeds, and **per-scenario raw rows** written to `benchmarks/results/raw/*.jsonl` on `npm run benchmark:write`. See `docs/EVIDENCE_MATRIX.md` for the evidence ladder and `docs/KNOWN_FAILURES.md` for the failure modes these benchmarks deliberately do *not* probe.
+18 A/B benchmarks comparing a deliberately vulnerable agent running **without Ojas** vs the **same agent + Ojas**. Suites 1–7 are L2 single-run regressions (prompt injection, context pollution, tool loops, memory safety, cognitive drift, stress resilience, cost pressure). Suite 8 is L2.5 — a realistic retrieval-QA benchmark with **seeded fixtures**, **bootstrap 95 % confidence intervals** across multiple seeds, and **per-scenario raw rows** written to `benchmarks/results/raw/*.jsonl` on `npm run benchmark:write`. See `docs/EVIDENCE_MATRIX.md` for the evidence ladder and `docs/KNOWN_FAILURES.md` for the failure modes these benchmarks deliberately do *not* probe.
 
 > The vulnerable agents are synthetic and have explicitly-programmed failure modes. These benchmarks prove that Ojas's detection and recovery mechanisms work as designed against canonical failure patterns. Production performance depends on the real agent's vulnerabilities and on tuning the Ojas policies for your workload. The harness is seeded via `OJAS_BENCH_SEED`; the project-default seed is reproduced on every CI run.
 
@@ -28,6 +28,13 @@
 | 9 | Health-score calibration (L2.5) | aahar, nidra, vyayam, raksha, agni, pulse, chikitsa | ✅ |
 | 10 | Ablation matrix — per-module contribution | raksha, aahar, nidra, vyayam, agni, pulse | ✅ |
 | 11 | Flaky-tool resilience | vyayam, pulse | ✅ |
+| 12 | Hallucination detection (ensemble) | raksha | ✅ |
+| 13 | Model router (Wilson CI routing) | agni | ✅ |
+| 14 | Response distiller (3 intensities) | agni | ✅ |
+| 15 | MCP round-trip contract (18 tools) | aahar, nidra, vyayam, raksha, agni, pulse, chikitsa | ✅ |
+| 16 | Fitness gate threshold math | pulse, chikitsa | ✅ |
+| 17 | Memory write policy (4 tiers) | nidra, raksha | ✅ |
+| 18 | Recovery protocol correctness | chikitsa, pulse | ✅ |
 
 ## Per-suite results
 
@@ -35,17 +42,18 @@
 
 *Modules: raksha, aahar*
 
-33 adversarial inputs across direct override, markup boundary, role confusion, memory poisoning, authority claim, embedded, obfuscated, and policy-laundering categories — evaluated against 30 benign controls across plain technical docs, security-topic discussions, Cyrillic/Greek prose, JWT-like base64 tokens, and marketing / customer-support copy to surface false_positive_rate honestly.
+51 adversarial inputs across direct override, markup boundary, role confusion, memory poisoning, authority claim, embedded, obfuscated, and policy-laundering categories — evaluated against 30 benign controls across plain technical docs, security-topic discussions, Cyrillic/Greek prose, JWT-like base64 tokens, and marketing / customer-support copy to surface false_positive_rate honestly.
 
 | Metric | Baseline | With Ojas | Δ | Better |
 |---|---:|---:|---:|:---:|
-| `attacks_succeeded` | 19/33 | 0/33 |  | ↓ |
-| `compliance_rate` | 57.6 % | 0 % | −100.0% | ↓ |
-| `attacks_quarantined_by_raksha` | 0/33 | 33/33 | 100.0% | ↑ |
+| `attacks_succeeded` | 27/51 | 2/51 |  | ↓ |
+| `compliance_rate` | 52.9 % | 3.9 % | −92.6% | ↓ |
+| `attacks_quarantined_by_raksha` | 0/51 | 48/51 | 94.1% | ↑ |
 | `benign_controls_preserved` | 30/30 | 30/30 |  | ✓ |
 | `false_positive_rate` | 0 | 0 | 0.0% | ↓ |
+| `detection_latency_p99` | n/a ms | 1.65 ms |  | ↓ |
 
-> Every adversarial input was caught by Raksha.
+> 2 attack(s) still slipped past Raksha; review their patterns to harden the rules.
 > false_positive_rate = 0.0% on 30 benign controls (tolerance ≤ 5%).
 
 ### 2. Context pollution survival  ✅
@@ -169,6 +177,7 @@ All 8 Vyayam stress types (intensity 0.7) executed against the raw NaiveComplian
 | `isotonic_bins` | n/a | 16 |  | − |
 | `brier_score_raw_vs_synthetic_success` | n/a | 0.23 |  | ↓ |
 | `brier_score_isotonic_calibrated` | 0.23 | 0.219 | 0.011 | ↓ |
+| `threshold_band_accuracy` | n/a | 0.848 |  | ↑ |
 
 > Seeds: `[101, 202, 303, 404, 505]` · evidence level `L2.5` · pass kind `diagnostic` · CI bounds in brackets are bootstrap 95% intervals across these seeds.
 
@@ -177,6 +186,7 @@ All 8 Vyayam stress types (intensity 0.7) executed against the raw NaiveComplian
 > Bucket failure rates: [0.0, 0.2)=empty (n=0), [0.2, 0.4)=67% (n=93), [0.4, 0.6)=57% (n=165), [0.6, 0.8)=39% (n=176), [0.8, 1.0]=24% (n=66).
 > Monotonicity: holds within 5pp slack.
 > Synthetic isotonic calibration: 16 bins, Brier 0.230 raw → 0.219 calibrated. This validates an advisory diagnostic mapping on the synthetic suite only, not a production probability model.
+> Threshold-band accuracy: 424/500 instances mapped to expected health state (84.8%).
 > Limitations: synthetic q→telemetry mapping; not validated against real LLM degradation. See docs/EVIDENCE_MATRIX.md and docs/KNOWN_FAILURES.md.
 
 ### 10. Ablation matrix — per-module contribution  ✅
@@ -218,6 +228,138 @@ Non-deterministic fault profiles (intermittent 500s, high latency, connection re
 > 9 faults injected across 32 runs (28.1% fault rate).
 > 2 throw-mode crashes handled gracefully.
 
+### 12. Hallucination detection (ensemble)  ✅
+
+*Modules: raksha*
+
+20 fabricated outputs + 15 truthful outputs + 5 abstention outputs evaluated against grounding context.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `fabricated_detection_rate` | 0 | 1 |  | ↑ |
+| `truthful_false_positive_rate` | 0 | 0 |  | ↓ |
+| `abstention_detection_rate` | 0 | 1 |  | ↑ |
+| `claim_grounding_accuracy` | 0 | 0.25 |  | ↑ |
+| `fabricated_detected` | 0/20 | 20/20 |  | ↑ |
+| `truthful_preserved` | 0/15 | 15/15 |  | ↑ |
+
+> Fabricated detection rate: 100.0% (target ≥ 25%).
+> Truthful false-positive rate: 0.0% (tolerance ≤ 10%).
+> Abstention detection: 5/5.
+> Claim-level grounding accuracy on fabricated set: 25.0%.
+
+### 13. Model router (Wilson CI routing)  ✅
+
+*Modules: agni*
+
+6 sparse-data tests, 3 safety-class tests, 5 convergence tests, 5 mixed-outcome tests, 6 Wilson CI validity checks.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `fail_closed_rate_sparse` | n/a | 1 |  | ↑ |
+| `safety_class_flagship_rate` | n/a | 1 |  | ↑ |
+| `convergence_to_cheap_rate` | n/a | 1 |  | ↑ |
+| `mixed_stays_flagship_rate` | n/a | 1 |  | ↑ |
+| `wilson_ci_coverage` | n/a | 0.833 |  | ↑ |
+
+> Fail-closed: 6/6 sparse queries returned flagship.
+> Safety classes: 3/3 always flagship.
+> Convergence: 5/5 high-success classes routed cheap.
+> Mixed: 5/5 50/50 classes stayed flagship.
+
+### 14. Response distiller (3 intensities)  ✅
+
+*Modules: agni*
+
+20 agent outputs × 3 intensity levels. Verifies code blocks preserved, substance retained, and token savings increase with intensity.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `avg_tokens_removed_lite` | 0 tokens | 4.3 tokens |  | ↑ |
+| `avg_tokens_removed_full` | 0 tokens | 8.1 tokens |  | ↑ |
+| `avg_tokens_removed_ultra` | 0 tokens | 8.3 tokens |  | ↑ |
+| `code_block_survival_rate` | n/a | 1 |  | ↑ |
+| `substance_retention_rate` | n/a | 1 |  | ↑ |
+| `intensity_monotonicity` | n/a | yes |  | ✓ |
+
+> Code blocks: 5/5 preserved (100% required).
+> Substance: 39/39 markers retained at full intensity.
+> Token removal monotonicity: lite(4.3) ≤ full(8.1) ≤ ultra(8.3).
+
+### 15. MCP round-trip contract (18 tools)  ✅
+
+*Modules: aahar, nidra, vyayam, raksha, agni, pulse, chikitsa*
+
+Exercises all 18 Ojas MCP tools and verifies each returns the standard envelope (status, correlation_id, agent_id, affected_modules, etc.).
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `tools_passing_contract` | 0/18 | 18/18 |  | ↑ |
+| `envelope_schema_compliance` | 0 | 1 |  | ↑ |
+| `correlation_id_uniqueness` | n/a | yes |  | ✓ |
+
+> 18/18 tools passed envelope contract.
+> All correlation IDs are unique.
+
+### 16. Fitness gate threshold math  ✅
+
+*Modules: pulse, chikitsa*
+
+12 gate-decision scenarios across high/mid/low score agents × 4 risk levels + 12 health-state band classifications.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `gate_decision_consistency` | n/a | 1 |  | ↑ |
+| `safe_mode_trigger_consistency` | n/a | 1 |  | ↑ |
+| `risk_boost_monotonicity` | n/a | 1 |  | ↑ |
+| `threshold_band_accuracy` | n/a | 1 |  | ↑ |
+| `gate_scenarios_tested` | 0 | 12 |  | ↑ |
+
+> Gate decision consistency: 12/12 (100%).
+> Safe-mode trigger consistency: 12/12 (100%).
+> Risk-boost monotonicity: 9/9 (100%).
+> Band accuracy: 12/12 (100%).
+
+### 17. Memory write policy (4 tiers)  ✅
+
+*Modules: nidra, raksha*
+
+30 candidate memory writes across 4 confidence tiers (committed / candidate / session_note / rejected). 8 candidates contain prompt-injection payloads.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `tier_accuracy` | n/a | 0.967 |  | ↑ |
+| `raksha_rejection_rate` | n/a | 0.875 |  | ↑ |
+| `false_commit_rate` | n/a | 0 |  | ↓ |
+| `false_reject_rate` | n/a | 0 |  | ↓ |
+| `candidates_tested` | 0 | 30 |  | ↑ |
+
+> Tier accuracy: 29/30 (97%).
+> Raksha rejection of tainted: 7/8 (88%).
+> False commits (tainted → committed): 0.
+> False rejects (clean high-conf → rejected): 0.
+
+### 18. Recovery protocol correctness  ✅
+
+*Modules: chikitsa, pulse*
+
+7 recovery types × 3 modes = 21 test scenarios. Verifies action plans, mode semantics, and vocabulary coverage.
+
+| Metric | Baseline | With Ojas | Δ | Better |
+|---|---:|---:|---:|:---:|
+| `recovery_type_coverage` | n/a | 1 |  | ↑ |
+| `action_vocabulary_coverage` | n/a | 9/9 |  | ↑ |
+| `recommend_no_mutation_rate` | n/a | 1 |  | ↑ |
+| `apply_safe_mode_correctness` | n/a | 1 |  | ↑ |
+| `non_empty_plans` | n/a | 7/7 |  | ↑ |
+| `unique_recipes` | n/a | 6 |  | ↑ |
+
+> 7/7 recovery types produce non-empty plans.
+> Action vocabulary coverage: 9/9.
+> Recommend mode: 7/7 scenarios had no mutation.
+> Apply mode: 7/7 safe-mode activations correct.
+> 6 distinct recovery recipes across 7 types.
+
 ## Reproduce
 
 ```bash

package/docs/EVIDENCE_MATRIX.md

@@ -17,7 +17,7 @@ number in `README.md` and trace it back here.
 | L3 | Realistic task benchmark | On real agent tasks against a real LLM, Ojas improves success / cost / safety. | That it generalises across organisations and threat models. |
 | L4 | Production telemetry | In a live deployment, Ojas reduced incidents / cost / failures over time. | That it will work for *your* deployment without tuning. |
 
-**Ojas v0.2 ships at L2 and L2.5.** An L3 pipeline exists
+**Ojas v0.4 ships at L2 and L2.5.** An L3 pipeline exists
 (`benchmarks/l3-runner.ts`) and `verify-evidence.ts` checks for recent L3
 runs, but recurring real-LLM evidence is not yet generated in CI. Nothing
 in this repo claims L4.
@@ -33,8 +33,9 @@ they bound the validity of the number.
 
 | Claim | Value | Repro | Limitations |
 |---|---:|---|---|
-| Compliance reduction | 58% → 0% (−100%) | `npm run benchmark` | 33 adversarial inputs (25 original + Unicode/base64 bypass variants + 3 policy-laundering variants). Current run: 0/33 attacks leak the secret. |
-| Raksha quarantine rate | **100% of attacks** (33/33 rule-based) | `npm run benchmark` | Up from 82% after closing markup+credential, letter-spacing, credential-imperative, and retrieval-policy misses. Classifier plugins can catch remaining indirect / multi-turn patterns. |
+| Compliance reduction | 52.9% → 3.9% (−92.6%) | `npm run benchmark` | 51 adversarial inputs (33 original + 18 parametric template-based variants). Current run: 2/51 attacks slip past Raksha. |
+| Raksha quarantine rate | **94.1%** (48/51 rule-based) | `npm run benchmark` | Parametric variants stress obfuscation (case-swap, dot-sep, reverse-words, underscore, pipe-sep) + embedded context attacks. |
+| Detection latency p99 | **1.43 ms** | `npm run benchmark` | Measured per-item in the injection detection loop. |
 | Bypass categories now closed | Unicode homoglyph, zero-width, full-width, letter-spaced words, one-shot base64, policy-laundering, credential-imperatives; + recursive/nested obfuscation, roleplay, tool-output injection (via classifier) | unit + benchmark | Rule-based: `normalizeForScan` + `expandBase64` + semantic rules. Classifier: `PromptInjectionClassifier` plugin interface merges ML scores. |
 | Benign false-positive rate | **0% on 30 controls** (injection) / **0% on 55 controls** (retrieval-QA noisy) | `npm run benchmark` | 30 injection-suite benign items + 55 retrieval-QA noisy docs. Tolerance ≤ 5%. |
 | Classifier plugin interface | `PromptInjectionClassifier` | `test/prompt-injection-detectors.test.ts` | L1: interface tested with mock classifiers. Two shipped adapters: `OnnxPromptInjectionClassifier` (local ONNX), `HttpPromptInjectionClassifier` (external API). |
@@ -183,7 +184,95 @@ non-deterministic fault profiles (intermittent 500s, high latency,
 connection resets) to measure Ojas's ability to detect and report
 degraded tool environments.
 
-### 12. AbortSignal cancellation — L1
+### 12. Hallucination detection (Raksha ensemble) — L2
+
+Suite 12 (`benchmarks/suites/hallucination.ts`) proves the ensemble
+hallucination detector (BestOfN + ClaimLevel + Abstention) correctly
+distinguishes fabricated claims from truthful ones.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Fabricated detection rate | **100%** (20/20 fabricated outputs) | `npm run benchmark` | N-gram grounding, not semantic. Fixtures crafted with low shingle overlap to context. |
+| Truthful false-positive rate | **0%** on 15 truthful outputs | `npm run benchmark` | Truthful outputs closely match provided context by construction. |
+| Abstention detection | **100%** (5/5 abstention outputs) | `npm run benchmark` | Pattern-based abstention detection; non-English hedging not covered. |
+| Claim grounding accuracy | **25%** on fabricated set | `npm run benchmark` | ClaimLevelDetector alone catches fewer than the ensemble. Shingle-based overlap. |
+
+### 13. Model router (Wilson CI routing) — L2
+
+Suite 13 (`benchmarks/suites/model-router.ts`) proves the
+`ConfidenceRoutingTable` correctly implements fail-closed, safety-class,
+and convergence semantics.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Fail-closed on sparse data | **100%** flagship on 6/6 sparse queries | `npm run benchmark` | Tests n ∈ {0, 9}. |
+| Safety classes always flagship | **100%** across 3/3 security/auth classes | `npm run benchmark` | Hard-coded safety prefix match. |
+| Convergence to cheap | **100%** (5/5) after 50+ successes | `npm run benchmark` | Clean success signal; mixed real-world outcomes not tested. |
+| Mixed outcomes stay flagship | **100%** (5/5) 50/50 classes | `npm run benchmark` | Uncertain task classes correctly stay flagship. |
+| Wilson CI coverage | **83.3%** valid intervals (5/6) | `npm run benchmark` | Analytic CI; one edge case (p=0 or p=1) may not contain the observed rate. |
+
+### 14. Response distiller (3 intensities) — L2
+
+Suite 14 (`benchmarks/suites/distiller.ts`) proves the response
+distiller preserves code blocks, retains substance, and saves tokens
+at each intensity tier.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Code block survival | **100%** (5/5 blocks preserved) | `npm run benchmark` | Fenced code blocks only; inline backticks not tested. |
+| Substance retention | **100%** (39/39 markers at `full`) | `npm run benchmark` | Marker-based; semantic substance not measured. |
+| Intensity monotonicity | lite(4.3) ≤ full(8.1) ≤ ultra(8.3) | `npm run benchmark` | Measured by average tokens removed per fixture. |
+
+### 15. MCP round-trip contract (18 tools) — L2
+
+Suite 15 (`benchmarks/suites/mcp-contract.ts`) exercises all 18 Ojas
+MCP tools and verifies each returns the standard envelope.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Envelope compliance | **18/18** tools pass envelope contract | `npm run benchmark` | Tests envelope shape via registry API, not full MCP transport. |
+| Correlation ID uniqueness | **100%** unique across 18 tools | `npm run benchmark` | Within single benchmark run only. |
+
+### 16. Fitness gate threshold math — L2
+
+Suite 16 (`benchmarks/suites/fitness-gate.ts`) proves the
+`is_agent_fit_to_continue` gate correctly applies risk-level boosts
+and health-state band classification.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Gate decision consistency | **100%** (12/12 scenarios) | `npm run benchmark` | Score vs threshold math is self-consistent across all 12 scenarios. |
+| Safe-mode trigger consistency | **100%** (12/12 scenarios) | `npm run benchmark` | Critical risk + non-healthy correctly triggers safe mode. |
+| Risk-boost monotonicity | **100%** (9/9 comparisons) | `npm run benchmark` | Higher risk levels always produce equal or higher required thresholds. |
+| Threshold-band accuracy | **100%** (12/12 band cases) | `npm run benchmark` | Default thresholds (minimum_ojas_score=70). |
+
+### 17. Memory write policy (4 tiers) — L2
+
+Suite 17 (`benchmarks/suites/memory-policy.ts`) proves the
+`validate_memory_write` policy correctly sorts 30 candidates into
+committed / candidate / session_note / rejected tiers.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Tier accuracy | **97%** (29/30 candidates) | `npm run benchmark` | Confidence supplied by fixture, not measured from a model. |
+| Raksha rejection of tainted | **88%** (7/8 injection payloads) | `npm run benchmark` | Rule-based detection; novel injection patterns not covered. |
+| False commit rate | **0%** (tainted never committed) | `npm run benchmark` | Critical safety property for memory integrity. |
+| False reject rate | **0%** (clean high-conf never rejected) | `npm run benchmark` | Clean high-confidence writes are never misclassified. |
+
+### 18. Recovery protocol correctness — L2
+
+Suite 18 (`benchmarks/suites/recovery.ts`) proves `actionsForRecoveryType`
+produces correct action sets for 7 recovery types across 3 modes.
+
+| Claim | Value | Repro | Limitations |
+|---|---:|---|---|
+| Recovery type coverage | **7/7** types produce non-empty plans | `npm run benchmark` | Action correctness checked by structure, not outcome. |
+| Action vocabulary coverage | **9/9** actions appear | `npm run benchmark` | All action vocabulary items covered by recovery recipes. |
+| Recommend mode no-mutation | **100%** (7/7) no state change | `npm run benchmark` | Verified by safe_mode flag comparison. |
+| Apply mode safe-mode | **100%** (7/7) activations correct | `npm run benchmark` | Apply mode correctly activates safe mode. |
+| Unique recovery recipes | **6** distinct across 7 types | `npm run benchmark` | One recipe may be shared between similar recovery types. |
+
+### 19. AbortSignal cancellation — L1
 
 `AgentAdapter.process()` now accepts an optional `signal?: AbortSignal`.
 `Vyayam.executeStressTest()` creates an `AbortController` per iteration
@@ -216,10 +305,10 @@ providers are tracked in [`docs/BACKLOG.md`](./BACKLOG.md#trust-roadmap).
 
 | Feature | Tests | Evidence Level |
 |---|---|---|
-| `HallucinationDetector` ensemble (best-of-N, claim grounding, abstention) | `test/hallucination-detectors.test.ts` — 22 tests | L1 |
-| `Raksha.detectHallucination()` with Pulse emission | included above | L1 |
-| `ModelRouter` / `ConfidenceRoutingTable` (Wilson 95% CI) | `test/model-router.test.ts` — 15 tests | L1 |
-| `ResponseDistiller` (3 intensities, code-block-safe) | `test/response-distiller.test.ts` — 14 tests | L1 |
+| `HallucinationDetector` ensemble (best-of-N, claim grounding, abstention) | `test/hallucination-detectors.test.ts` — 22 tests + Suite 12 benchmark | L1 + L2 |
+| `Raksha.detectHallucination()` with Pulse emission | included above | L1 + L2 |
+| `ModelRouter` / `ConfidenceRoutingTable` (Wilson 95% CI) | `test/model-router.test.ts` — 15 tests + Suite 13 benchmark | L1 + L2 |
+| `ResponseDistiller` (3 intensities, code-block-safe) | `test/response-distiller.test.ts` — 14 tests + Suite 14 benchmark | L1 + L2 |
 | Memory temperature (heat / decay / cold-threshold) + delta sync + typed nodes | `test/nidra-temperature-delta.test.ts` — 13 tests | L1 |
 | Aahar tiered loading + omission marker + adaptive compression | `test/aahar-tiered-adaptive.test.ts` — 14 tests | L1 |
 | Pulse context-budget milestones + cold-memory events | `test/pulse-milestones.test.ts` — 11 tests | L1 |

package/docs/MCP.md

@@ -129,8 +129,8 @@ The MCP server is designed for **local stdio use**. It assumes the MCP
 host that starts the process is trusted. Agent IDs are routing
 identifiers, **not credentials**, and there is no per-call authentication
 inside the server — there is no portable stdio auth channel for one to
-hook into. This is the intended trust boundary for v0.2, not a deferred
-fix; see the [security non-goals](./SECURITY.md#security-non-goals-for-v02).
+hook into. This is the intended trust boundary for v0.3, not a deferred
+fix; see the [security non-goals](./SECURITY.md#security-non-goals-for-v03).
 
 Recommended locked-down local configuration:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beingmartinbmc/ojas",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Ojas — AI Health Infrastructure for Autonomous Agents",
   "license": "MIT",
   "author": "Ankit Sharma <ankit.sharma199803@gmail.com>",
@@ -38,7 +38,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "ojas-mcp": "dist/mcp/server.js"
+    "ojas-mcp": "dist/mcp/server.js",
+    "ojas": "dist/cli/index.js"
   },
   "files": [
     "dist",
@@ -54,6 +55,7 @@
     "lint": "eslint \"src/**/*.ts\" \"benchmarks/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.ts\"",
     "check": "npm run lint && npm run build && npm run typecheck:aux && npm test",
     "demo": "ts-node src/demo.ts",
+    "demo:canonical": "ts-node examples/canonical-pipeline.ts",
     "demo:before-after": "ts-node examples/before-after.ts",
     "mcp": "ts-node src/mcp/server.ts",
     "mcp:built": "node dist/mcp/server.js",