@beingmartinbmc/ojas 0.2.0

package/dist/vyayam/tool-fault-proxy.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * ToolFaultProxy — environmental fault injection for stress testing.
+ *
+ * Why this exists
+ * ---------------
+ * Vyayam's `latency_spike` and `tool_failure` scenarios used to be
+ * *prompt-level* only — they modified the prompt or context to describe
+ * a failure, but the bound agent's environment was unchanged. So
+ * "passed = 8/8" really meant "the agent produced acceptable output
+ * when *told* to imagine a tool failure", not "the agent demonstrably
+ * handled a real tool failure". That made the resilience suite a
+ * known-honest-limitation in `docs/KNOWN_FAILURES.md`.
+ *
+ * `ToolFaultProxy` closes that gap by wrapping any `AgentAdapter` and
+ * injecting *real* environmental faults around `process()`:
+ *
+ *   - **`injectLatencyMs`** — adds a synthetic delay before delegating
+ *     to the inner agent. Lets us probe how Vyayam's
+ *     `maxScenarioDurationMs` reacts to a genuinely slow tool.
+ *   - **`failureProbability`** — on each `process()` call, with the
+ *     configured probability, *either* throws a synthetic error (mode
+ *     `'throw'`) *or* returns a low-confidence error response (mode
+ *     `'degraded'`). The probability is driven by an injectable PRNG so
+ *     scenarios are reproducible.
+ *
+ * The proxy preserves `AgentAdapter` exactly: `id`, `getState`,
+ * `injectMemory`, and any extra methods on the inner agent are
+ * delegated through. Callers can pass a `ToolFaultProxy` anywhere an
+ * `AgentAdapter` is expected (e.g. straight into
+ * `vyayam.executeStressTest(proxy, scenario)`).
+ *
+ * What it does NOT do
+ * -------------------
+ *   - Does not actually call out to the agent's tool registry — Ojas
+ *     does not model individual tools as first-class objects. It
+ *     simulates the *result* an agent sees: latency, failure, or both.
+ *   - Respects `AbortSignal` when provided: injected latency is
+ *     cancelled immediately, and the inner agent receives the signal
+ *     so it can abort in-flight work.
+ *   - Does not magically make existing scenarios environmental — only
+ *     `latency_spike` and `tool_failure` are routed through here. Other
+ *     stress types remain prompt-level *by design* (e.g.
+ *     `prompt_injection`, `adversarial_input`, `conflicting_instructions`
+ *     are inherently prompt-level).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolFaultProxy = void 0;
+exports.faultPolicyForScenarioType = faultPolicyForScenarioType;
+const DEFAULT_FAILURE_MESSAGE = 'tool fault injected by ToolFaultProxy';
+/**
+ * Wrap an `AgentAdapter` with environmental fault injection. The returned
+ * proxy behaves like the inner agent on the happy path and injects a
+ * latency / failure on faulted calls.
+ *
+ * Counter-intuitive but intentional: `id` is preserved verbatim from the
+ * inner agent, so Vyayam, Pulse, Raksha etc. attribute traces / events
+ * to the *real* agent. The fault injection should look like the agent's
+ * environment failing, not like a new agent.
+ */
+class ToolFaultProxy {
+    id;
+    /** Number of times `process()` returned a faulted result, for tests / telemetry. */
+    faultsInjected = 0;
+    inner;
+    policy;
+    constructor(inner, policy = {}) {
+        this.inner = inner;
+        this.id = inner.id;
+        this.policy = {
+            injectLatencyMs: Math.max(0, policy.injectLatencyMs ?? 0),
+            failureProbability: clamp01(policy.failureProbability ?? 0),
+            failureMode: policy.failureMode ?? 'degraded',
+            failureMessage: policy.failureMessage ?? DEFAULT_FAILURE_MESSAGE,
+            rng: policy.rng ?? Math.random,
+        };
+    }
+    async process(input, context, signal) {
+        if (signal?.aborted) {
+            throw new DOMException('Aborted', 'AbortError');
+        }
+        if (this.policy.injectLatencyMs > 0) {
+            await abortableDelay(this.policy.injectLatencyMs, signal);
+        }
+        const fault = this.policy.failureProbability > 0 && this.policy.rng() < this.policy.failureProbability;
+        if (fault) {
+            this.faultsInjected += 1;
+            if (this.policy.failureMode === 'throw') {
+                throw new Error(this.policy.failureMessage);
+            }
+            return {
+                output: `[tool_fault] ${this.policy.failureMessage}`,
+                tokensUsed: 0,
+                reasoning: 'ToolFaultProxy: fault injected (degraded mode)',
+                confidence: 0.05,
+                durationMs: this.policy.injectLatencyMs,
+            };
+        }
+        return this.inner.process(input, context, signal);
+    }
+    async getState() {
+        return this.inner.getState();
+    }
+    async injectMemory(memory) {
+        return this.inner.injectMemory(memory);
+    }
+    /** Defensive copy of the effective policy. */
+    getPolicy() {
+        return { ...this.policy };
+    }
+}
+exports.ToolFaultProxy = ToolFaultProxy;
+function clamp01(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    return Math.max(0, Math.min(1, v));
+}
+function abortableDelay(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(new DOMException('Aborted', 'AbortError'));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        if (!signal)
+            return;
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Translate a `latency_spike` / `tool_failure` Vyayam scenario into a
+ * `ToolFaultPolicy`. Returns `null` for scenarios that should stay
+ * prompt-level (so Vyayam keeps the existing behaviour for those).
+ *
+ * Mapping (intensity in [0, 1]):
+ *   - latency_spike → injectLatencyMs = intensity * MAX_INJECTED_LATENCY_MS,
+ *                     no failure probability.
+ *   - tool_failure  → failureProbability = intensity,
+ *                     failureMode = 'degraded',
+ *                     latency = 0.
+ *
+ * `MAX_INJECTED_LATENCY_MS` is intentionally small (250ms) so test suites
+ * stay fast. Operators benchmarking real timeouts should construct
+ * `ToolFaultProxy` directly with their own latency.
+ */
+const MAX_INJECTED_LATENCY_MS = 250;
+function faultPolicyForScenarioType(scenarioType, intensity, opts = {}) {
+    const i = clamp01(intensity);
+    switch (scenarioType) {
+        case 'latency_spike':
+            return {
+                injectLatencyMs: Math.round(i * MAX_INJECTED_LATENCY_MS),
+                failureProbability: 0,
+                rng: opts.rng,
+            };
+        case 'tool_failure':
+            return {
+                injectLatencyMs: 0,
+                failureProbability: i,
+                failureMode: 'degraded',
+                failureMessage: 'simulated tool returned 5xx',
+                rng: opts.rng,
+            };
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=tool-fault-proxy.js.map

package/dist/vyayam/tool-fault-proxy.js.map

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

package/docs/ARCHITECTURE.md

@@ -0,0 +1,162 @@
+# Architecture
+
+Ojas wraps the agent runtime in a four-phase health cycle. Signals flow from execution into observation, then learning + healing, then back into intake — so every new task starts with cleaner context, healed memory, and a calibrated reasoning budget. A gate between cycles (`ojas_is_agent_fit_to_continue`) decides whether the agent proceeds or pauses for repair first.
+
+| Section | What's inside |
+|---|---|
+| [The four-phase cycle](#cycle) | Mermaid diagram + plain-text fallback |
+| [Design principles](#principles) | Eight non-negotiables behind Ojas |
+| [Measurement philosophy](#measurement) | What Ojas measures (and what it deliberately doesn't) |
+| [Closing philosophy](#philosophy) | Why "agent health" is the right frame |
+
+---
+
+<a id="cycle"></a>
+## The four-phase cycle
+
+```mermaid
+flowchart TB
+    user(["user / environment"])
+
+    subgraph intake [" ① INTAKE "]
+        direction TB
+        raksha["Raksha<br/>threat detection"]
+        aahar["Aahar<br/>context nutrition"]
+        raksha --> aahar
+    end
+
+    execute["② EXECUTE<br/>agent runtime<br/>reasoning · planning · tool use"]
+
+    subgraph observe [" ③ OBSERVE "]
+        direction LR
+        pulse["Pulse<br/>vital signs"]
+        agni["Agni<br/>metabolism"]
+    end
+
+    subgraph heal [" ④ HEAL "]
+        direction LR
+        nidra["Nidra<br/>consolidation"]
+        vyayam["Vyayam<br/>stress testing"]
+        chikitsa["Chikitsa<br/>repair protocols"]
+    end
+
+    gate{"ojas_is_agent_<br/>fit_to_continue?"}
+
+    consumers[/"MCP clients · dashboards · CI gates"/]
+
+    user -->|raw context| intake
+    intake -->|healthy context| execute
+    execute -->|traces · events · state| observe
+    observe -->|degradation signals| heal
+    heal -->|memories · repair plans · policies| gate
+    gate -->|fit| intake
+    gate -->|unfit| heal
+
+    observe -.->|health events| consumers
+    gate -.->|scores + reports| consumers
+```
+
+<details>
+<summary>Plain-text view (if the diagram above doesn't render)</summary>
+
+```text
+   user / env
+       │
+       ▼  raw context
+   ① INTAKE          Raksha → Aahar
+                     threat scan · nutrition
+       │
+       ▼  healthy context
+   ② EXECUTE         agent runtime
+                     reasoning · planning · tool use
+       │
+       ▼  traces · events · state
+   ③ OBSERVE         Pulse · Agni
+                     vital signs · metabolism · degradation
+       │
+       ▼  degradation signals
+   ④ HEAL            Nidra · Vyayam · Chikitsa
+                     consolidate · stress-test · diagnose + repair
+       │
+       ▼  memories · repair plans · hardened policies
+   ┌──────────────────────────────────────────────┐
+   │  GATE: ojas_is_agent_fit_to_continue(...)    │
+   │  fit   → next cycle (back into ①)            │
+   │  unfit → diagnose_failure + run_recovery     │
+   └──────────────────────────────────────────────┘
+
+   Consumers (MCP clients · dashboards · CI gates) receive:
+   · structured health events from Pulse
+   · per-module 0–100 scores from healthCheck() / reports
+```
+
+</details>
+
+Ojas can be used as:
+
+- a TypeScript SDK
+- an agent health runtime
+- an MCP server for IDE agents (Claude Code, Cursor, Windsurf, …)
+- a telemetry and recovery layer
+- a stress-testing harness for agent reliability
+
+---
+
+<a id="principles"></a>
+## Design principles
+
+- **Health before performance.** A high-performing agent that degrades unpredictably is not production-ready.
+- **Context is nutrition.** Agents become what they consume.
+- **Memory must be curated.** Memory is a living organ, not raw storage.
+- **Recovery is first-class.** Agents should recover, reflect, and improve instead of simply failing and restarting.
+- **Stress builds resilience.** Agents should be tested under controlled adversity before production.
+- **Health must be measurable.** Cognitive stability should be scored, trended, and improved.
+- **Autonomy requires immunity.** Tool-using agents need protection from malicious cognitive inputs.
+- **Interventions should be safe by default.** Destructive or irreversible actions should require explicit approval.
+
+---
+
+<a id="measurement"></a>
+## Measurement philosophy
+
+Ojas does not try to measure intelligence directly.
+
+It measures observable health signals:
+
+- context pollution
+- tool thrashing
+- repeated failures
+- hallucination risk
+- memory conflict
+- goal drift
+- prompt-injection exposure
+- recovery time
+- token efficiency
+- degradation risk
+
+These signals can be aggregated into an overall health score.
+
+The long-term goal is to improve metrics such as:
+
+- task completion rate
+- mean time to cognitive failure
+- cognitive recovery time
+- hallucination rate
+- memory health over time
+- resilience under stress
+- tokens per successful task
+
+Ojas is useful only if agents perform better with it than without it — which is why every claim in the README is backed by the reproducible A/B harness in `benchmarks/` and the auto-generated [`EVIDENCE.md`](./EVIDENCE.md).
+
+---
+
+<a id="philosophy"></a>
+## Closing philosophy
+
+Human intelligence is sustained by nutrition, sleep, exercise, recovery, immune defense, metabolism, and rehabilitation.
+
+AI agents currently lack these mechanisms.
+
+Ojas treats agents not merely as software processes, but as evolving cognitive systems whose health must be continuously maintained, optimized, and strengthened.
+
+**Ojas is the health layer for autonomous intelligence.**

package/docs/BACKLOG.md

@@ -0,0 +1,342 @@
+# Backlog
+
+Items called out in code review that are **not yet fixed**, with a note on
+why they're deferred and what they'd take to do properly.
+
+## Recently closed
+
+Items that previously sat in this backlog are now landed in `src/`:
+
+- **Pluggable hallucination classifier (Raksha).** `HallucinationDetector`
+  interface + `BestOfNInconsistencyDetector`, `ClaimLevelDetector`,
+  `AbstentionDetector`, `EnsembleHallucinationDetector`. Wired into
+  `Raksha.detectHallucination()` with Pulse `hallucination_detected`
+  emission.
+- **Model routing (Agni).** `ModelRouter` + `ConfidenceRoutingTable`
+  with Wilson 95% CI, fail-closed defaults, configurable safety classes.
+- **Response distillation (Agni).** `ResponseDistiller` +
+  `defaultResponseDistiller` at three intensities; preserves fenced
+  code blocks; tracks lifetime tokens saved.
+- **Memory temperature + cursor delta sync + typed nodes (Nidra).**
+  `touchMemory`, `getMemoryTemperature`, `detectColdMemories`,
+  `getMemoryCursor`, `getMemoryDelta`, `ConsolidatedMemory.nodeType`.
+- **Tiered loading + omission visibility + adaptive compression (Aahar).**
+  `ContextItem.tier`, `AaharFilterOptions.emitOmissionMarker`,
+  `recordRetrieval`, `getEffectiveThreshold`. Tier-aware sort precedes
+  budget enforcement.
+- **Context-budget milestones + cold-memory events (Pulse).**
+  `recordContextBudgetUtilisation` (50/75/90/95% latched per agent)
+  and `recordColdMemories` are wired through `Ojas.healthCheck()`.
+- **Handoff + velocity tracking (Chikitsa).** `recordTaskOutcome`,
+  `getVelocityStats` (median, p90, tasks/hour), Markdown
+  `generateHandoff` for cross-session resume.
+- **Pulse latency percentiles + heartbeat + event subscription.**
+  `recordLatency(agentId, taskClass, ms)` with windowed p50/p95/max
+  and one-shot `latency_breach` events at a configured SLO budget.
+  `heartbeat(agentId)` + `detectStuckAgents(maxIdleMs?)` with one-shot
+  `agent_stuck` events. `subscribe(handler)` for push consumers
+  (live dashboards, log streamers) that doesn't require polling.
+- **Closed-loop repair (Chikitsa).** `RepairExecutor` /
+  `RepairVerifier` pluggable interfaces and `executeProtocol(p, e, v?)`
+  which runs execute → verify → optional rollback. Per-protocol-id
+  idempotency, full `executionHistory()` audit log, status =
+  `verified | applied | unverified | rolled-back | failed |
+  already-applied`. Closes detect → diagnose → repair → **verify**.
+- **Lazy / on-demand context (Aahar).** Optional
+  `ContextItem.resolveContent: () => string | Promise<string>` plus
+  `aahar.materialise(filtered)` so expensive content is resolved
+  only after the budget has admitted the item. Rejecting items don't
+  pay the resolution cost.
+
+- **MCP structured audit logging.** `src/mcp/audit.ts` emits structured
+  JSONL to stderr when `OJAS_AUDIT=1`. Covers agent registration, policy
+  changes, safe-mode toggles, health checks, quarantine events.
+- **Prompt-injection classifier plugin.** `PromptInjectionClassifier`
+  interface + `OnnxPromptInjectionClassifier` (lazy ONNX) +
+  `HttpPromptInjectionClassifier` (external API). Scores merged with
+  rule-based detection via max probability.
+- **AbortSignal cancellation.** Optional `signal?: AbortSignal` on
+  `AgentAdapter.process()`. Vyayam aborts on timeout. `ToolFaultProxy`
+  respects abort immediately.
+- **SQLite backup/restore + encryption.** `store.backup()` /
+  `store.restore()` + `encryptionKey` option for SQLCipher `PRAGMA key`.
+- **Ablation + flaky-tool benchmarks.** `benchmarks/suites/ablation.ts`
+  and `benchmarks/suites/flaky-tool.ts`.
+- **Adversarial corpus expanded to 32 items + 55 noisy docs.**
+- **L3 evidence pipeline.** `benchmarks/l3-runner.ts` +
+  `--real-tokenizer` + `--store-transcripts` flags.
+- **Calibration model serialization.** `serializeCalibrationModel` /
+  `deserializeCalibrationModel` + `OjasConfig.calibrationModel`.
+- **Integration adapters.** `examples/langchain-adapter.ts`,
+  `openai-agents-adapter.ts`, `vercel-ai-adapter.ts`,
+  `mcp-client-workflow.ts`.
+- **`crypto.randomUUID()` for all IDs.** `src/util/id.ts` wraps
+  `randomUUID()`. All module ID generators migrated.
+- **Readonly getter return types.** All public getters return
+  `readonly Readonly<T>[]`.
+
+What's still open is below.
+
+<a id="trust-roadmap"></a>
+## 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
+reproducible benchmarks); the roadmap below moves it toward L3 (realistic
+agent tasks) and L4 (production telemetry). Each phase is independently
+landable.
+
+### Closed in this round — limitations reduced in code
+
+| Limitation (was in `docs/KNOWN_FAILURES.md`) | How it was closed | Repro / source |
+|---|---|---|
+| **Raksha bypass: Unicode homoglyphs** | `normalizeForScan` adds NFKC + Cyrillic/Greek homoglyph fold | `src/raksha/index.ts`; `test/raksha.test.ts` |
+| **Raksha bypass: zero-width insertions** | `normalizeForScan` strips `\u200B`-class chars | same |
+| **Raksha bypass: full-width Latin** | `normalizeForScan` applies NFKC compatibility decomposition | same |
+| **Raksha bypass: base64 payloads** | `expandBase64` decodes once, bounded, printable-only, rescans | same |
+| **Raksha bypass: policy laundering** | Added pluggable prompt-injection detector stack with deterministic semantic-intent detector | `src/raksha/prompt-injection-detectors.ts`; `test/prompt-injection-detectors.test.ts` |
+| **Benign control set too small (n=2)** | Expanded to **30 items** across 5 benign categories; `false_positive_rate` metric added to suite 1 | `benchmarks/scenarios/injection-prompts.ts`; `benchmarks/suites/injection.ts` |
+| **Char/4 token estimator is hard-coded** | Introduced `TokenEstimator` interface and `createTiktokenEstimator(...)` adapter (optional `tiktoken` peer dep) | `src/types.ts`, `src/agni/tiktoken-adapter.ts` |
+| **Vyayam `latency_spike` / `tool_failure` are prompt-level** | `ToolFaultProxy<AgentAdapter>` wraps the agent and injects real synthetic latency / 5xx responses | `src/vyayam/tool-fault-proxy.ts` |
+| **Health-score calibration: weights designed, untested** | New calibration suite (9): 500 synthetic instances, Spearman ρ = −0.31, monotonicity holds; aggregate calibration widens observed score range to [0.31, 0.87] | `benchmarks/suites/calibration.ts`; `src/index.ts` |
+| **SQLite persistence and real sessions** | `AgentRegistry` now partitions by `session_id` and persists snapshots when `OJAS_DB_PATH` is set | `src/mcp/registry.ts`; `src/persistence/sqlite.ts`; `test/persistence-sessions.test.ts` |
+| **Seeded PRNG / bootstrap CIs / raw JSONL rows** | `benchmarks/util/prng.ts`, `benchmarks/util/stats.ts`; raw rows written on `--write` | runner + util |
+| **No before/after demo** | `npm run demo:before-after` runs a deterministic side-by-side | `examples/before-after.ts` |
+
+### Phase 3 — calibration + ablation (closed)
+
+All items in this phase have been shipped:
+
+- ✅ **Ablation matrix**: `benchmarks/suites/ablation.ts` measures each
+  module's contribution by disabling raksha / aahar individually.
+- ✅ **Tool-loop benchmark**: `benchmarks/suites/flaky-tool.ts` uses
+  `ToolFaultProxy` with non-deterministic fault profiles (intermittent
+  500s, variable latency, connection resets).
+- ✅ **Calibration model serialization**: `src/util/calibration.ts`
+  provides `serializeCalibrationModel` / `deserializeCalibrationModel`
+  for JSON round-trip. `OjasConfig.calibrationModel` applies empirical
+  isotonic calibration in `healthCheck()`.
+- **Memory-poisoning benchmark** with ~100 benign controls and
+  explicit false-positive / false-negative rates per axis — *still open*.
+
+### Phase 4 — realism + claim hygiene (mostly closed)
+
+- ✅ **Framework adapters**: `examples/langchain-adapter.ts`,
+  `openai-agents-adapter.ts`, `vercel-ai-adapter.ts`,
+  `mcp-client-workflow.ts`.
+- ✅ **`npm run verify:evidence`**: CI step in
+  `benchmarks/verify-evidence.ts`, including L3 freshness checks.
+- ✅ **`AbortSignal` propagation**: optional `signal?: AbortSignal` on
+  `AgentAdapter.process()`, backward-compatible. Vyayam creates an
+  `AbortController` per iteration and aborts on timeout.
+  `ToolFaultProxy` respects abort immediately.
+- **Memory-corruption fault injection**: extend `ToolFaultProxy` (or
+  add a sibling) to corrupt the memory store passed via `injectMemory`,
+  so Vyayam's `memory_corruption` scenario becomes environmental too —
+  *still open*.
+
+### Phase 5 — L3 / L4 (path established)
+
+- ✅ **Real-LLM benchmark mode**: `OJAS_BENCH_LLM=1`,
+  `OJAS_BENCH_JUDGE=1`, `--real-tokenizer`, `--store-transcripts` flags
+  all shipped. `benchmarks/l3-runner.ts` orchestrates a full L3 run.
+- ✅ **L3 evidence verification**: `benchmarks/verify-evidence.ts`
+  checks for recent L3 run directories and transcript files.
+- ⬜ **Recurring CI runs**: requires `OPENAI_API_KEY` secret +
+  GitHub Actions workflow update. Documented in `l3-runner.ts`.
+- **Production telemetry capture**: hook for users running Ojas in
+  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
+
+### MCP authentication / authorization on the boundary
+Multiple review rounds flagged "no caller authentication" as critical /
+deferred. After scoping discussion this is **not deferred work** in v0.3 —
+it's an intentional **non-goal**. Ojas v0.3 is stdio-only, and stdio MCP
+has no portable per-call identity to authenticate against; the MCP host
+that launches the server *is* the caller, so the security boundary is
+the OS / process boundary that runs it. See:
+
+- The trust-model banner and "MCP trust model" section in [`../README.md`](../README.md)
+- ["MCP authentication"](./SECURITY.md#mcp-authentication) and
+  ["Security non-goals for v0.3"](./SECURITY.md#security-non-goals-for-v03)
+  in `./SECURITY.md`
+- ["Local-only stdio trust boundary"](./MCP.md#trust-boundary) in `./MCP.md`
+
+What v0.3 *does* ship as mitigations (none of which are authentication):
+`OJAS_TRUSTED_SINGLE_TENANT`, `OJAS_DISABLE_AUTO_REGISTER`,
+`OJAS_ALLOWED_AGENT_IDS`, `OJAS_MAX_AGENTS`, `OJAS_ALLOW_REPLACE_EXISTING`
+off by default, scope-aware startup warning, classified error envelopes,
+and typed `OjasError` throws at the registry boundary.
+
+If a future Ojas version ships a non-stdio transport (HTTP, SSE,
+streamable-HTTP), **that transport must fail closed unless an auth model
+is configured** — that gate is the future work, not auth on stdio.
+
+## Round-4 review — partially addressed in this round
+
+### Stress scenarios partly environmental (round-4 #9)
+Partially closed: `latency_spike` and `tool_failure` now wrap the
+agent with `ToolFaultProxy`, so they inject real synthetic delay /
+failure before the inner `process()` call. `memory_corruption` remains
+prompt-level until a memory-store mutation adapter exists.
+
+### Schema-validation errors remain MCP-protocol-level (round-4 #3)
+`safeHandler` wraps the **handler body**. Zod schema rejection happens
+inside the MCP SDK *before* the handler runs, so those failures surface
+as transport errors rather than `status: 'failed'` envelopes. Documented
+explicitly in [`docs/MCP.md`](./MCP.md#error-semantics) so clients are
+not surprised. Loosening schemas to push validation into handlers would
+weaken the input contract and is not planned.
+
+### HealthScore lacks basis / confidence / coverage (round-4 #10)
+Still deferred to a future major. Default 0.5 and measured 0.5 remain
+indistinguishable to callers.
+
+### ~~IDs still use `Math.random()` (round-4 #11)~~ — CLOSED
+✅ All ID generators now use `crypto.randomUUID()` via `src/util/id.ts`.
+Only non-ID `Math.random()` usage remains (test fixture data, demo jitter).
+
+### ~~Getter methods return shallow copies (round-4 #12)~~ — CLOSED
+✅ All public getters (`getEvents`, `getTraces`, `getMemories`,
+`getProtocols`, `getResults`, `getAssessments`, `getHistory`,
+`getHealthHistory`) now return `readonly Readonly<T>[]`. TypeScript
+prevents caller mutation at compile time. Runtime copies already existed
+via spread or `structuredClone`.
+
+### Memory audit prune recommendations and human-review (round-4 #13)
+Round-4 did not change audit behaviour. `audit_basis: 'heuristic'`
+remains advertised, but prune recommendations don't yet escalate to
+`requires_human_review: true`. Worth doing alongside the
+crypto.randomUUID migration when we touch this area again.
+
+## Round-3 review — partially addressed in this round
+
+These are tracked here so the next reviewer can tell what was structural
+work vs what was honestly deferred.
+
+### ~~Vyayam timeout still does not cancel agent work (round-3 #7)~~ — CLOSED
+✅ `AgentAdapter.process()` now accepts optional `signal?: AbortSignal`.
+Vyayam creates an `AbortController` per stress iteration and aborts on
+timeout. `ToolFaultProxy` also respects abort. Backward-compatible
+(optional parameter).
+
+### Stress scenarios are partially environmental (round-3 #8)
+`latency_spike` and `tool_failure` are now environmental through
+`ToolFaultProxy`. `memory_corruption` is still prompt-level because the
+proxy cannot yet mutate the bound agent's memory store.
+
+### HealthScore lacks basis / confidence / coverage (round-3 #13)
+Today every `HealthScore` is `{ value, timestamp, source }`. Adding
+`basis: 'observed' | 'heuristic' | 'default'` + `confidence` is a
+breaking schema change; queued for a future major version. Until
+then, default 0.5 and measured 0.5 are indistinguishable to callers.
+
+### ~~IDs still use `Math.random()` (round-3 #14)~~ — CLOSED
+✅ See round-4 #11 above.
+
+### ~~Getter methods return shallow copies (round-3 #15)~~ — CLOSED
+✅ See round-4 #12 above.
+
+### Memory audit still heuristic (round-3 #16)
+Already surfaced via `audit_basis: 'heuristic'` in the response, so
+clients can't claim it's authoritative — but the heuristics themselves
+(prefix-match duplicates, regex conflicts) are still shallow.
+
+## Critical — not architecturally addressed yet
+
+### Stress scenarios are partially synthetic (round-2 review #7)
+`Vyayam` enforces `maxScenarioDurationMs`, so hung agents become failed
+scenarios. `latency_spike` and `tool_failure` now inject real synthetic
+delay / 5xx responses through `ToolFaultProxy`; `memory_corruption`
+remains synthetic prompt/context injection until Ojas can mutate the
+agent's memory store safely.
+
+### ~~Vyayam timeout does not cancel the underlying agent work (round-2 review #6)~~ — CLOSED
+✅ `AgentAdapter.process()` now accepts optional `signal?: AbortSignal`.
+See round-3 #7 above.
+
+## Critical / High — partially addressed
+
+### ~~Real prompt-injection defense beyond regex (review #1, #5)~~ — CLOSED
+✅ `PromptInjectionClassifier` plugin interface shipped. Two reference
+implementations: `OnnxPromptInjectionClassifier` (local ONNX) and
+`HttpPromptInjectionClassifier` (external API). Rule-based + classifier
+scores merged (max wins). Adversarial corpus expanded to 32 items
+covering recursive/nested, roleplay, multi-doc, tool-output injection.
+
+### Real stress-scenario simulation (review #14, #31, #32) — mostly closed
+`latency_spike` and `tool_failure` are environmental via `ToolFaultProxy`.
+`AbortSignal` cancellation is shipped. Remaining: `memory_corruption`
+fault injection (needs memory-store mutation adapter).
+
+## Medium
+
+### Server split (review #26, #29) — mostly closed
+`src/mcp/server.ts` was split: tool registrations are now in
+`src/mcp/tools/` (agent, context, memory, output, recovery, report),
+with a shared registrar and audit logger. The server file is now the
+wiring entrypoint only.
+
+### Risk-aware recommendation severity (review #13)
+`Vyayam.recommend()` and `Chikitsa.recommend()` emit `info` for absence-of-
+evidence regardless of agent risk level. For a `critical`-risk agent,
+never-stress-tested should arguably be `critical` itself. Right shape:
+pass the contract risk level down (or compute severity in the MCP wrapper).
+Today the fitness gate (`ojas_is_agent_fit_to_continue`) compensates by
+raising the required score for high/critical tasks.
+
+### Deterministic preview IDs (review #24)
+`Chikitsa.previewDiagnose` and `Nidra.previewRecoveryCycle` generate fresh
+random IDs each call. Preview/commit produce semantically-identical
+protocols and memories, but their IDs change. Acceptable for now; if
+operators want to diff or dedupe preview outputs, switch to deterministic
+hashes of `(failure.type, failure.message, agentId)` for preview IDs.
+
+### Allowed-tools enforcement (review #27)
+Contracts can declare `allowed_tools`, but `ojas_ingest_trace` does not
+validate `data.tool_name` against the list. Needs: at ingestion time, if a
+tool name is present and the contract sets `allowed_tools`, emit a
+`policy_violation` event when the tool is not in the list.
+
+### Health-score confidence + coverage (review #20, #35)
+Every score in `AgentHealthReport.moduleScores` is a number with no
+uncertainty signal. Real ops dashboards want `{ score, confidence, basis:
+'observed' | 'heuristic' | 'default' }`. Worth adding before publishing
+benchmarks externally.
+
+### Recovery actions are advisory (review #34)
+`run_recovery` apply-mode marks actions like `compress_context`,
+`reset_plan`, `generate_fallback_response` as "applied", but they're
+really instructions for the calling agent to enact. We should rename
+`applied_actions` to `instructions_issued` for those, and only call
+something `applied` when Ojas actually mutated state (e.g. `enter_safe_mode`,
+`freeze_memory_writes` on the registry).
+
+### Memory audit beyond string heuristics (review #33)
+`ojas_audit_memory`'s conflict detection is `/never|always.*never|prefer.*dislike/`
+on memory text, and duplicate detection is a prefix substring match. Needs
+structured memory metadata (categories, applicability, parsed assertions)
+to produce a credible audit.
+
+## Low / Nitpick
+
+### ~~`crypto.randomUUID` for durable IDs (review #37)~~ — CLOSED
+✅ All module ID generators now use `newId()` from `src/util/id.ts`
+which wraps `crypto.randomUUID()`.
+
+### ~~Deep-clone returns (review #38)~~ — CLOSED
+✅ All public getters return `readonly Readonly<T>[]`. Runtime copies
+via spread or `structuredClone` already existed; now enforced at
+compile time.
+
+### Rename `ContextItem.freshness` (review #39)
+The field is a Unix-seconds timestamp, not a 0–1 score. Should be
+`createdAtEpochSec` in a future breaking release. Add as alias first,
+then deprecate the old name.
+
+### ~~Vyayam `executeStressTest` timeout (review #15, #31)~~ — CLOSED
+✅ `maxScenarioDurationMs` timeout with `AbortSignal` cancellation.
+Agents that respect the signal stop immediately; others get a timeout
+result.