@beingmartinbmc/ojas 0.2.0

package/dist/agni/response-distiller.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * `defaultResponseDistiller` — rule-based filler stripper for agent
+ * output.
+ *
+ * Pattern: LLM responses routinely contain ~30-40% filler — "Sure,
+ * I'd be happy to help!", "Hope this helps!", chain-of-thought
+ * meta-commentary, repeated preambles. None of it is load-bearing
+ * for the caller. Stripping it
+ * saves tokens on the output side without touching what actually
+ * matters.
+ *
+ * **Code blocks are sacrosanct.** Anything between fenced code fences
+ * (``` … ```) is preserved verbatim, byte-for-byte. We also preserve
+ * indented code blocks (4-space indent) and inline single-backtick
+ * spans.
+ *
+ * Three intensity levels:
+ *   - **`lite`**: strip only the lowest-risk preamble/closer phrases
+ *     (e.g. "Sure!", "Hope this helps!"). Won't touch substance.
+ *   - **`full`** (default): adds hedging (`I think`, `It seems`),
+ *     filler intros ("Let me take a look", "Here's what I found"), and
+ *     repeated "in summary" / "to conclude" closers.
+ *   - **`ultra`**: also collapses repeated empty lines, strips
+ *     standalone Markdown emphasis on filler phrases, and removes
+ *     "Note:" / "FYI:" prefixes from individual sentences.
+ *
+ * False-positive guard: every pattern is anchored to either start-of-
+ * string, start-of-line, end-of-string, or a sentence boundary. We
+ * never strip mid-sentence content unless it's a standalone hedge
+ * (`, I think,`) — and even then only at intensity `full`+.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultResponseDistiller = void 0;
+exports.createResponseDistiller = createResponseDistiller;
+// Conservative anchored patterns. Each is tested without --u flag to keep
+// behaviour stable across Node versions.
+//
+// IMPORTANT: every pattern uses `g` (global) so a single text with
+// multiple matches gets fully stripped, not just the first.
+const PATTERNS = [
+    // ── PREAMBLE ──
+    // "Sure!", "Sure, I'd be happy to help.", "Of course!"
+    {
+        pattern: /(^|[.!?]\s+)(Sure|Of course|Certainly|Absolutely|Definitely)(,?\s*(I'?d be happy to help[!.]?|here you go[!.]?|let me help[!.]?))?[.!]?\s*/gi,
+        category: 'preamble',
+        minIntensity: 'lite',
+    },
+    // "Let me take a look at..."  /  "Let me check..."  /  "Let's look at..."
+    {
+        pattern: /(^|[.!?]\s+)(Let me|Let's|I'll|I will)\s+(take a look at|check|examine|look at|review|look into)\s+[^.!?]*[.!]?\s*/gi,
+        category: 'preamble',
+        minIntensity: 'full',
+    },
+    // "Here's what I found:" / "Here is the answer:"
+    {
+        pattern: /(^|[.!?]\s+)(Here'?s|Here is) (what I found|the answer|my analysis|my response)[:.]?\s*/gi,
+        category: 'preamble',
+        minIntensity: 'full',
+    },
+    // "I'd be happy to help" / "I'd be glad to help"
+    {
+        pattern: /(^|[.!?]\s+)I'?d be (happy|glad|delighted) to (help|assist)[!.]?\s*/gi,
+        category: 'preamble',
+        minIntensity: 'lite',
+    },
+    // ── HEDGING ──
+    // Standalone hedging sentences: "I think this is right.", "It seems that..."
+    // We only strip the hedge, not the whole sentence.
+    {
+        pattern: /\b(?:I think|I believe|It seems(?: like)?|It appears(?: that)?|It looks like)\s+/gi,
+        category: 'hedging',
+        minIntensity: 'full',
+    },
+    // "as far as I can tell" / "to my knowledge"
+    {
+        pattern: /,?\s*(?:as far as I (?:can tell|know)|to (?:my|the best of my) knowledge)\s*,?\s*/gi,
+        category: 'hedging',
+        minIntensity: 'full',
+    },
+    // ── META ──
+    // "Note:" / "FYI:" at the start of a sentence (intensity ultra only).
+    {
+        pattern: /(^|[.!?]\s+)(Note|FYI|PSA|Heads up)[:!]\s*/gi,
+        category: 'meta',
+        minIntensity: 'ultra',
+    },
+    // Standalone markdown emphasis around filler ("**Important:**")
+    {
+        pattern: /(^|[.!?]\s+)\*+(?:Important|Note|Warning)\*+:\s*/gi,
+        category: 'meta',
+        minIntensity: 'ultra',
+    },
+    // ── CLOSER ──
+    // "Hope this helps!" / "Hope that helps!"
+    // NOTE: `(^|[.!?]\s+)` is *capturing* so the replacement function
+    // gets the leading punctuation as $1 and preserves the sentence boundary.
+    {
+        pattern: /(^|[.!?]\s+)(?:I )?[Hh]ope (?:this|that|it)\s+(?:helps|makes sense|clarifies|is clear)[!.]?\s*/g,
+        category: 'closer',
+        minIntensity: 'lite',
+    },
+    // "Let me know if you have any questions"
+    {
+        pattern: /(^|[.!?]\s+)Let me know (?:if you (?:have any questions|need anything else|want me to (?:elaborate|continue))|how (?:I can help|else I can assist))[.!?]?\s*/gi,
+        category: 'closer',
+        minIntensity: 'lite',
+    },
+    // "In summary, ..." / "To summarise, ..." — strip the intro only.
+    {
+        pattern: /(^|[.!?]\s+)(In summary|To summarise|To summarize|In conclusion|To conclude)\s*,\s*/gi,
+        category: 'closer',
+        minIntensity: 'full',
+    },
+];
+const INTENSITY_ORDER = {
+    lite: 1,
+    full: 2,
+    ultra: 3,
+};
+function shouldApply(pattern, level) {
+    return INTENSITY_ORDER[pattern.minIntensity] <= INTENSITY_ORDER[level];
+}
+function segment(text) {
+    const out = [];
+    // Match fenced blocks: ``` ... ``` or ~~~ ... ~~~ (with optional language tag).
+    const re = /(```[\s\S]*?```|~~~[\s\S]*?~~~)/g;
+    let last = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        if (m.index > last) {
+            out.push({ kind: 'prose', text: text.slice(last, m.index) });
+        }
+        out.push({ kind: 'code', text: m[0] });
+        last = m.index + m[0].length;
+    }
+    if (last < text.length) {
+        out.push({ kind: 'prose', text: text.slice(last) });
+    }
+    return out;
+}
+/** Char/4 token-count estimate so we can report `tokensRemoved`. */
+function estTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function createResponseDistiller(intensity = 'full') {
+    return {
+        name: `default-distiller/${intensity}`,
+        distill(text) {
+            if (typeof text !== 'string' || text.length === 0) {
+                return { text: text ?? '', tokensRemoved: 0, charsRemoved: 0, removed: [] };
+            }
+            const segments = segment(text);
+            const removed = new Set();
+            let removedChars = 0;
+            const outSegments = [];
+            for (const seg of segments) {
+                if (seg.kind === 'code') {
+                    outSegments.push(seg.text);
+                    continue;
+                }
+                let working = seg.text;
+                for (const p of PATTERNS) {
+                    if (!shouldApply(p, intensity))
+                        continue;
+                    const before = working.length;
+                    working = working.replace(p.pattern, (_match, lead = '') => lead);
+                    const delta = before - working.length;
+                    if (delta > 0) {
+                        removed.add(p.category);
+                        removedChars += delta;
+                    }
+                }
+                // At `ultra` intensity, collapse 3+ consecutive blank lines to 2.
+                if (intensity === 'ultra') {
+                    working = working.replace(/\n{3,}/g, '\n\n');
+                }
+                outSegments.push(working);
+            }
+            const distilled = outSegments.join('');
+            const tokensRemoved = Math.max(0, estTokens(text) - estTokens(distilled));
+            return {
+                text: distilled,
+                tokensRemoved,
+                charsRemoved: removedChars,
+                removed: Array.from(removed),
+            };
+        },
+    };
+}
+/** Default `ResponseDistiller` at `full` intensity. Re-export for convenience. */
+exports.defaultResponseDistiller = createResponseDistiller('full');
+//# sourceMappingURL=response-distiller.js.map

package/dist/agni/response-distiller.js.map

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

package/dist/agni/tiktoken-adapter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Optional tiktoken adapter for `TokenEstimator`.
+ *
+ * Why this is in its own file
+ * ---------------------------
+ * `tiktoken` is intentionally **not** a dependency of Ojas (the SDK runs
+ * fine without it on the default `charBasedTokenEstimator`). We expose
+ * this adapter as a *factory* that only loads `tiktoken` lazily — so:
+ *
+ *   - the Ojas SDK has zero runtime impact for users who don't need a
+ *     real tokenizer;
+ *   - users who *do* need one install `tiktoken` themselves and call
+ *     `createTiktokenEstimator(...)`;
+ *   - the factory throws a clear, actionable error if `tiktoken` isn't
+ *     installed, instead of failing somewhere deep in Agni at first
+ *     `assess()` call.
+ *
+ * Usage
+ * -----
+ * ```ts
+ * import { Agni, createTiktokenEstimator } from '@beingmartinbmc/ojas';
+ *
+ * const agni = new Agni({}, {
+ *   tokenEstimator: createTiktokenEstimator('cl100k_base'),
+ * });
+ * ```
+ *
+ * Encodings supported by `tiktoken` at time of writing:
+ *   - `cl100k_base`  (GPT-3.5, GPT-4 family)
+ *   - `o200k_base`   (GPT-4o family, o1 family)
+ *   - `r50k_base`    (legacy GPT-3)
+ *   - `p50k_base`    (Codex / older models)
+ *
+ * The factory passes the string through; if `tiktoken` doesn't recognise
+ * the encoding it will throw on first call and the adapter falls back to
+ * char/4 (with a single stderr warning) rather than crashing Agni.
+ */
+import type { TokenEstimator } from '../types';
+/** Encoding names accepted by current `tiktoken`. Pass-through; not validated. */
+export type TiktokenEncoding = 'cl100k_base' | 'o200k_base' | 'r50k_base' | 'p50k_base';
+/**
+ * Build a `TokenEstimator` backed by the optional `tiktoken` package.
+ *
+ * Throws synchronously when `tiktoken` is not installed (or fails to load),
+ * with a message that includes the install command. This is intentional —
+ * a confusingly-silent fallback would let users believe they were getting
+ * real-tokenizer numbers when they weren't.
+ *
+ * Once constructed, the estimator itself does **not** throw: if an
+ * individual `encode()` call fails on hostile input, the adapter
+ * gracefully returns the `charBasedTokenEstimator` result for that call
+ * so a single bad string can't break health assessment.
+ */
+export declare function createTiktokenEstimator(encoding?: TiktokenEncoding): TokenEstimator;
+//# sourceMappingURL=tiktoken-adapter.d.ts.map

package/dist/agni/tiktoken-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiktoken-adapter.d.ts","sourceRoot":"","sources":["../../src/agni/tiktoken-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAa/C,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,YAAY,GACZ,WAAW,GACX,WAAW,CAAC;AAEhB;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,GAAE,gBAAgC,GAAG,cAAc,CAmDlG"}

package/dist/agni/tiktoken-adapter.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Optional tiktoken adapter for `TokenEstimator`.
+ *
+ * Why this is in its own file
+ * ---------------------------
+ * `tiktoken` is intentionally **not** a dependency of Ojas (the SDK runs
+ * fine without it on the default `charBasedTokenEstimator`). We expose
+ * this adapter as a *factory* that only loads `tiktoken` lazily — so:
+ *
+ *   - the Ojas SDK has zero runtime impact for users who don't need a
+ *     real tokenizer;
+ *   - users who *do* need one install `tiktoken` themselves and call
+ *     `createTiktokenEstimator(...)`;
+ *   - the factory throws a clear, actionable error if `tiktoken` isn't
+ *     installed, instead of failing somewhere deep in Agni at first
+ *     `assess()` call.
+ *
+ * Usage
+ * -----
+ * ```ts
+ * import { Agni, createTiktokenEstimator } from '@beingmartinbmc/ojas';
+ *
+ * const agni = new Agni({}, {
+ *   tokenEstimator: createTiktokenEstimator('cl100k_base'),
+ * });
+ * ```
+ *
+ * Encodings supported by `tiktoken` at time of writing:
+ *   - `cl100k_base`  (GPT-3.5, GPT-4 family)
+ *   - `o200k_base`   (GPT-4o family, o1 family)
+ *   - `r50k_base`    (legacy GPT-3)
+ *   - `p50k_base`    (Codex / older models)
+ *
+ * The factory passes the string through; if `tiktoken` doesn't recognise
+ * the encoding it will throw on first call and the adapter falls back to
+ * char/4 (with a single stderr warning) rather than crashing Agni.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTiktokenEstimator = createTiktokenEstimator;
+const module_1 = require("module");
+const index_1 = require("./index");
+/**
+ * Node's `createRequire` lets us perform an opaque-to-bundlers
+ * resolution of an *optional* peer dependency without using `eval`.
+ * Static-analysis tools / CSP-restricted environments flag `eval`
+ * even when the input is a constant string, so this is the
+ * preferred form for "load this module only if the host installed
+ * it" patterns.
+ */
+const requireOptional = (0, module_1.createRequire)(__filename);
+/**
+ * Build a `TokenEstimator` backed by the optional `tiktoken` package.
+ *
+ * Throws synchronously when `tiktoken` is not installed (or fails to load),
+ * with a message that includes the install command. This is intentional —
+ * a confusingly-silent fallback would let users believe they were getting
+ * real-tokenizer numbers when they weren't.
+ *
+ * Once constructed, the estimator itself does **not** throw: if an
+ * individual `encode()` call fails on hostile input, the adapter
+ * gracefully returns the `charBasedTokenEstimator` result for that call
+ * so a single bad string can't break health assessment.
+ */
+function createTiktokenEstimator(encoding = 'cl100k_base') {
+    // We resolve `tiktoken` lazily via `createRequire` so users who do not
+    // need it pay zero install cost and never see a "Cannot find module"
+    // error in production. The require call is opaque to bundlers and
+    // does not use `eval`, which keeps the package clean for CSP-restricted
+    // hosts and static-analysis security scanners.
+    let tiktoken;
+    try {
+        tiktoken = requireOptional('tiktoken');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`createTiktokenEstimator: optional dependency 'tiktoken' is not installed. ` +
+            `Install it in your host project (\`npm install tiktoken\`), then call ` +
+            `createTiktokenEstimator(${JSON.stringify(encoding)}). ` +
+            `Underlying loader error: ${msg}`);
+    }
+    let enc;
+    try {
+        enc = tiktoken.get_encoding(encoding);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`createTiktokenEstimator: tiktoken does not recognise encoding ${JSON.stringify(encoding)}. ` +
+            `Loader error: ${msg}`);
+    }
+    let warned = false;
+    return {
+        name: `tiktoken/${encoding}`,
+        estimate(text) {
+            if (typeof text !== 'string' || text.length === 0)
+                return 0;
+            try {
+                return enc.encode(text).length;
+            }
+            catch (err) {
+                // Graceful degradation per the TokenEstimator contract: never throw.
+                // Surface the failure to stderr once, then mirror char/4 behaviour.
+                if (!warned) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`tiktoken/${encoding}.encode() failed once (${msg}); falling back to char/4 for affected calls.\n`);
+                    warned = true;
+                }
+                return index_1.charBasedTokenEstimator.estimate(text);
+            }
+        },
+    };
+}
+//# sourceMappingURL=tiktoken-adapter.js.map

package/dist/agni/tiktoken-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiktoken-adapter.js","sourceRoot":"","sources":["../../src/agni/tiktoken-adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;;AAoCH,0DAmDC;AArFD,mCAAuC;AAEvC,mCAAkD;AAElD;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,IAAA,sBAAa,EAAC,UAAU,CAAC,CAAC;AASlD;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAAC,WAA6B,aAAa;IAChF,uEAAuE;IACvE,qEAAqE;IACrE,kEAAkE;IAClE,wEAAwE;IACxE,+CAA+C;IAC/C,IAAI,QAAsF,CAAC;IAC3F,IAAI,CAAC;QACH,QAAQ,GAAG,eAAe,CAAC,UAAU,CAAoB,CAAC;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,wEAAwE;YACxE,2BAA2B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK;YACxD,4BAA4B,GAAG,EAAE,CACpC,CAAC;IACJ,CAAC;IAED,IAAI,GAAiD,CAAC;IACtD,IAAI,CAAC;QACH,GAAG,GAAG,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,iEAAiE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI;YAC3F,iBAAiB,GAAG,EAAE,CACzB,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,OAAO;QACL,IAAI,EAAE,YAAY,QAAQ,EAAE;QAC5B,QAAQ,CAAC,IAAY;YACnB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,CAAC,CAAC;YAC5D,IAAI,CAAC;gBACH,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YACjC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,qEAAqE;gBACrE,oEAAoE;gBACpE,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,QAAQ,0BAA0B,GAAG,iDAAiD,CACnG,CAAC;oBACF,MAAM,GAAG,IAAI,CAAC;gBAChB,CAAC;gBACD,OAAO,+BAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/chikitsa/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Ojas Chikitsa (ओजस चिकित्सा) — AI Repair & Rehabilitation System
+ *
+ * Diagnoses failures and creates structured repair protocols.
+ */
+import { HandoffSnapshot, HealthRecommendation, RehabilitationHealth, RehabilitationPolicy, RepairExecutionRecord, RepairExecutor, RepairProtocol, RepairVerifier, RuntimeFailure, TaskOutcomeRecord, VelocityStats } from '../types';
+import type { ChikitsaStateSnapshot } from '../persistence/types';
+export declare class Chikitsa {
+    private policy;
+    private protocols;
+    /**
+     * Rolling window of trailing task outcomes. Used by
+     * `getVelocityStats()` to compute success rate + duration percentiles
+     * + tasks/hour. Bounded by `policy.velocityWindowSize` so memory
+     * usage is stable across long-running agents.
+     */
+    private taskOutcomes;
+    /**
+     * Set of protocol ids that `executeProtocol()` has already applied
+     * via a `RepairExecutor`. A second call with the same protocol id
+     * short-circuits to `status: 'already-applied'` regardless of the
+     * executor's idempotency — Chikitsa is the source of truth for
+     * "this protocol has been run".
+     */
+    private appliedProtocolIds;
+    /** Audit log of every executeProtocol() invocation. Capped by `maxProtocols`. */
+    private executions;
+    constructor(policy?: Partial<RehabilitationPolicy>);
+    private validatePolicy;
+    /** Drop the oldest protocols when retention cap is exceeded. */
+    private enforceProtocolLimit;
+    /**
+     * Append a task outcome to the rolling velocity window. Rejects
+     * malformed entries (non-finite `durationMs`, unparseable
+     * `completedAt`) at the boundary so a buggy caller can't poison
+     * percentile math. Older entries past `velocityWindowSize` are
+     * evicted from the front.
+     */
+    recordTaskOutcome(record: TaskOutcomeRecord): void;
+    /**
+     * Windowed velocity summary over the trailing `velocityWindowSize`
+     * outcomes (default 50). Returns a zero-valued struct for an empty
+     * window so callers don't need to null-check before rendering.
+     */
+    getVelocityStats(): VelocityStats;
+    /** Read-only view of the current outcome window. Useful for tests + dashboards. */
+    getRecentOutcomes(): ReadonlyArray<TaskOutcomeRecord>;
+    /** Clear the velocity window. Useful for tests + cross-session boundaries. */
+    resetVelocityWindow(): void;
+    /**
+     * Serialise a structured `HandoffSnapshot` into a Markdown document
+     * the next agent (or the same agent in a fresh session) can read at
+     * boot. The file becomes the single source of truth for "what was
+     * I doing and where am I in it" across sessions.
+     *
+     * Markdown is intentionally human-first; structured callers should
+     * pass the snapshot object around directly and only call this when
+     * they want a persistable artefact.
+     */
+    generateHandoff(snapshot: HandoffSnapshot): string;
+    /**
+     * Run a `RepairProtocol` through a pluggable `RepairExecutor` and,
+     * optionally, a `RepairVerifier`. Closes the
+     * detect → diagnose → repair → **verify** loop so the agent has
+     * evidence the repair actually fixed the failure.
+     *
+     * Idempotency: Chikitsa is the source of truth for "has this
+     * protocol already run". A second call with the same `protocol.id`
+     * short-circuits to `status: 'already-applied'` without invoking
+     * the executor.
+     *
+     * Failure handling:
+     *  - Executor throws            → `status: 'failed'`, `error` set
+     *  - Executor returns `failed`  → `status: 'failed'`
+     *  - No verifier configured     → `status: 'applied'`
+     *  - Verifier returns `false`   → `status: 'unverified'`, then
+     *    if `executor.rollback` is defined the rollback runs and
+     *    status promotes to `'rolled-back'` (rollback errors are
+     *    swallowed; the status is still `'rolled-back'` so the
+     *    audit log captures the attempt).
+     *  - Verifier returns `true`    → `status: 'verified'`
+     *
+     * Pulse events emitted via the passed-in pulse, when provided, are
+     * the caller's job to wire — Chikitsa returns the record and lets
+     * Ojas's outer loop translate that to events.
+     */
+    executeProtocol(protocol: RepairProtocol, executor: RepairExecutor, verifier?: RepairVerifier): Promise<RepairExecutionRecord>;
+    /** Read-only audit log of every `executeProtocol()` call. */
+    executionHistory(): ReadonlyArray<RepairExecutionRecord>;
+    /** Whether a protocol id has been successfully applied (and not rolled back). */
+    hasProtocolBeenApplied(protocolId: string): boolean;
+    /** Clear all execution / applied state. Useful for tests + cross-session boundaries. */
+    resetExecutionHistory(): void;
+    private recordExecution;
+    /**
+     * Build a repair protocol for a single failure. Encapsulates ALL the
+     * policy logic (severity mapping, criticalRequiresHuman) so preview and
+     * commit produce identical results for the same input.
+     *
+     * `idMode` controls the protocol id: `'random'` produces a unique id
+     * suitable for committed protocols (each diagnose() call mints a new
+     * one); `'deterministic'` produces a stable hash of the failure so
+     * preview output can be diffed and deduped across calls.
+     */
+    private buildProtocol;
+    /**
+     * Pure: compute repair protocols for the given failures without appending
+     * them to internal state. Output is byte-identical to what `diagnose()`
+     * would produce *except* for the id, which is deterministic here so
+     * callers can diff or dedupe preview output across repeated calls.
+     */
+    previewDiagnose(failures: RuntimeFailure[]): RepairProtocol[];
+    /**
+     * Compute repair protocols and record them in internal state. Honors
+     * `policy.criticalRequiresHuman` via the same shared path as preview,
+     * but uses random ids so each diagnose() commit can be tracked
+     * independently in history.
+     */
+    diagnose(failures: RuntimeFailure[]): RepairProtocol[];
+    private diagnosisFor;
+    private actionsFor;
+    assess(): RehabilitationHealth;
+    recommend(): HealthRecommendation[];
+    getProtocols(): readonly Readonly<RepairProtocol>[];
+    exportState(): ChikitsaStateSnapshot;
+    importState(snapshot: Partial<ChikitsaStateSnapshot> | undefined): void;
+    getPolicy(): RehabilitationPolicy;
+    updatePolicy(updates: Partial<RehabilitationPolicy>): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/chikitsa/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chikitsa/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,eAAe,EACf,oBAAoB,EAEpB,oBAAoB,EACpB,oBAAoB,EAEpB,qBAAqB,EAErB,cAAc,EACd,cAAc,EAEd,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,aAAa,EACd,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AA6DlE,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAwB;IACzC;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAA2B;IAC/C;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,iFAAiF;IACjF,OAAO,CAAC,UAAU,CAA+B;gBAErC,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAItD,OAAO,CAAC,cAAc;IAmBtB,gEAAgE;IAChE,OAAO,CAAC,oBAAoB;IAS5B;;;;;;OAMG;IACH,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAoBlD;;;;OAIG;IACH,gBAAgB,IAAI,aAAa;IAoCjC,mFAAmF;IACnF,iBAAiB,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAIrD,8EAA8E;IAC9E,mBAAmB,IAAI,IAAI;IAM3B;;;;;;;;;OASG;IACH,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IA0DlD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,eAAe,CACnB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc,EACxB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,qBAAqB,CAAC;IA8HjC,6DAA6D;IAC7D,gBAAgB,IAAI,aAAa,CAAC,qBAAqB,CAAC;IAIxD,iFAAiF;IACjF,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInD,wFAAwF;IACxF,qBAAqB,IAAI,IAAI;IAK7B,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE;IAM7D;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE;IAStD,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,UAAU;IAqBlB,MAAM,IAAI,oBAAoB;IAY9B,SAAS,IAAI,oBAAoB,EAAE;IA8BnC,YAAY,IAAI,SAAS,QAAQ,CAAC,cAAc,CAAC,EAAE;IAInD,WAAW,IAAI,qBAAqB;IAQpC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,GAAG,IAAI;IAOvE,SAAS,IAAI,oBAAoB;IAIjC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;CAI3D"}