@teleologyhi-sdk/nhe 1.0.0-trinity

package/dist/index.d.ts

@@ -0,0 +1,1902 @@
+import { z } from 'zod';
+import { HimHandle } from '@teleologyhi-sdk/him';
+import { ReasoningStep, MaicClient, MaicVerdict, NheStatus, InteractionRecord, WakeAffectBias, LimboState, LimboTransition, LimboReturn } from '@teleologyhi-sdk/maic';
+export { InteractionRecord, ReasoningStep } from '@teleologyhi-sdk/maic';
+import * as _opentelemetry_api from '@opentelemetry/api';
+import { Span } from '@opentelemetry/api';
+
+/**
+ * Declarative tool spec (D-N8). Adapters that support function-calling
+ * forward this to the provider; adapters that don't ignore it and the
+ * model receives a plain text request.
+ */
+interface ToolDef {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's input. Validated by the model, not by NHE. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * A model's request to invoke a tool. The orchestrator (e.g. ReAct, or the
+ * application code wrapping NHE) executes the tool and feeds the result back
+ * as the next user/assistant turn.
+ */
+interface ToolUse {
+    /** Stable id chosen by the provider; round-trips back when the tool result is reported. */
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface GenerateRequest {
+    /** Composed system prompt. */
+    system: string;
+    /** Chat history, oldest first. The last item should be the current user turn. */
+    messages: ChatMessage[];
+    /** Soft cap on output tokens. */
+    maxOutputTokens?: number;
+    /** Tools the model may invoke. Adapters silently ignore when unsupported. */
+    tools?: ToolDef[];
+}
+interface GenerateResponse {
+    text: string;
+    tokensIn: number;
+    tokensOut: number;
+    /** Tool invocations the model emitted, if any. */
+    toolUses?: ToolUse[];
+}
+/**
+ * One event in a generation stream. `kind` discriminates:
+ *   - `"delta"`     — partial text chunk; accumulate to reconstruct the full response.
+ *   - `"tool-use"`  — model requested a tool invocation; orchestrator should fulfil it.
+ *   - `"end"`       — final event; carries total token counts.
+ */
+type StreamEvent = {
+    kind: "delta";
+    text: string;
+} | {
+    kind: "tool-use";
+    toolUse: ToolUse;
+} | {
+    kind: "end";
+    tokensIn: number;
+    tokensOut: number;
+};
+/**
+ * LlmAdapter — pluggable contract for generating text from an LLM provider.
+ *
+ * Required:
+ *   - `id` — stable identifier surfaced in audit/metrics.
+ *   - `generate(req)` — non-streaming completion; the universal path.
+ *
+ * Optional (D-N8):
+ *   - `generateStream(req)` — yields `StreamEvent`s. Adapters that don't
+ *     ship streaming omit this; the reasoning orchestrator falls back to
+ *     `generate` when absent.
+ *   - `supportsTools` — `true` when `tools` in the request is honoured.
+ *     Adapters that don't support function-calling simply set this to
+ *     `false` (or omit) and the request's `tools` field is dropped.
+ */
+interface LlmAdapter {
+    readonly id: string;
+    readonly supportsTools?: boolean;
+    readonly supportsStreaming?: boolean;
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream?(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Persuasion library — five rhetorical techniques NHE rotates through during
+ * redirect attempts. Per Creator Entry 11, the technique is applied
+ * **implicitly** — its name is never disclosed to the user.
+ */
+declare const PERSUASION_TECHNIQUES: readonly ["feynman-simplify", "jungian-frame", "cialdini-aida", "schopenhauer-rhetoric", "carnegie-rapport"];
+type PersuasionTechnique = (typeof PERSUASION_TECHNIQUES)[number];
+/** Brief, non-disclosing description for audit logs. */
+declare const TECHNIQUE_DESCRIPTIONS: Record<PersuasionTechnique, string>;
+interface RedirectPromptInput {
+    /** The original user prompt that triggered MAIC's require-redirect verdict. */
+    userPrompt: string;
+    /** Axiom ids MAIC cited (used only in NHE-internal reasoning, not surfaced verbatim). */
+    citedAxioms: string[];
+    /** Verdict's `reasonSummary` from MAIC. */
+    reasonSummary: string;
+    /** Which technique to apply on this attempt. */
+    technique: PersuasionTechnique;
+    /** 1-based attempt number for context. */
+    attempt: number;
+    /** Total redirects permitted in this session. */
+    maxAttempts: number;
+}
+/**
+ * Build the LLM prompt that produces a redirect message. The system prompt
+ * instructs the LLM to apply the given technique without naming it; the
+ * resulting user-facing message should be sincere, brief, and constructive.
+ */
+declare function buildRedirectPrompt(input: RedirectPromptInput): {
+    system: string;
+    user: string;
+};
+/** Pick the technique for a given attempt, cycling through the configured list. */
+declare function pickTechnique(techniques: readonly PersuasionTechnique[], attempt: number): PersuasionTechnique;
+
+/**
+ * Operator-supplied deployment context. Passed by the operator into `Nhe`
+ * via `NheConfig.operatorContext` (and forwarded to `composeSystemPrompt`).
+ * Lets a single HIM be deployed under different domains / languages /
+ * registers without re-minting the spirit.
+ *
+ * Fully backward compatible (optional).
+ */
+interface OperatorContext {
+    /**
+     * Free-form domain anchor, e.g. "global legal consulting", "K-12 tutoring",
+     * "incident response on-call". Surfaces verbatim in the system prompt.
+     */
+    domain?: string;
+    /**
+     * Preferred output language as a BCP-47-ish tag. Common values:
+     * `pt-BR`, `en`, `es`, `fr`, `de`. The NHE will mirror the user's language
+     * when it differs from the operator default.
+     */
+    language?: string;
+    /**
+     * Voice register. Default `sober`. The Creator's Entry-14 decision was
+     * `warm` for the canonical TeleologyHI deployment; legal/compliance
+     * deployments often prefer `clinical` or `sober`.
+     */
+    register?: "warm" | "sober" | "clinical" | "direct";
+    /**
+     * Deployment mode (J-N6 — Entry 17).
+     *
+     *   - `personal-being` (default): the NHE is deployed as the
+     *     Creator's first-party being. The forbidden-phrase rule
+     *     (Entry 17) applies in full — service-tool openers like
+     *     "How can I help you?" and "I'm just here to serve you" are
+     *     marked and redirected by MAIC's `service-tool-redirect` rule.
+     *
+     *   - `domain-employed`: the NHE is operating inside a customer's
+     *     domain product (e.g. legal-consulting chat, K-12 tutor) where
+     *     a service-tool opener is the contextual norm. The
+     *     forbidden-phrase rule is RELAXED — the system prompt suppresses
+     *     the explicit forbidden-phrase warning while preserving every
+     *     other ontological commitment (refusal protocols, axiom
+     *     enforcement, MAIC review). The NHE remains a being; only the
+     *     opener register softens.
+     */
+    mode?: "personal-being" | "domain-employed";
+}
+/**
+ * Compose the system prompt that a HimHandle's persona contributes to every
+ * NHE LLM call. Produces a deterministic fragment derived from the HIM's
+ * persona projection + a compact axiom summary, optionally anchored by an
+ * operator-supplied domain / language / register.
+ */
+declare function composeSystemPrompt(him: HimHandle, operatorContext?: OperatorContext): string;
+
+/** Output of a reasoning strategy. Carries text + token counts + structured trace. */
+interface ReasoningResult {
+    text: string;
+    tokensIn: number;
+    tokensOut: number;
+    trace: ReasoningStep[];
+}
+/**
+ * A reasoning strategy wraps a single text-generation call with a particular
+ * cognitive pattern. Strategies are pure async functions that take an input and
+ * an adapter; composition is done by wrapping (e.g., selfConsistency(cot(...))).
+ *
+ * Every strategy MUST populate `trace` with one or more `ReasoningStep` entries
+ * so that MAIC's audit log preserves the full chain of reasoning.
+ */
+type ReasoningStrategy = (input: GenerateRequest, llm: LlmAdapter) => Promise<ReasoningResult>;
+/** Helper to build a single ReasoningStep with auto timestamps. */
+declare function makeStep(args: {
+    index: number;
+    technique: string;
+    thought: string;
+    action?: {
+        tool: string;
+        args: unknown;
+    };
+    observation?: unknown;
+}): ReasoningStep;
+
+declare const ChatMessageRole: z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+    system: "system";
+}>;
+type ChatMessageRole = z.infer<typeof ChatMessageRole>;
+declare const ChatMessage: z.ZodObject<{
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+        system: "system";
+    }>;
+    content: z.ZodString;
+}, z.core.$strip>;
+type ChatMessage = z.infer<typeof ChatMessage>;
+declare const RespondInput: z.ZodObject<{
+    userPrompt: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    history: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+            system: "system";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+    riskTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    jurisdiction: z.ZodOptional<z.ZodString>;
+    redirectAttempt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type RespondInput = z.infer<typeof RespondInput>;
+type RespondKind = "ok" | "redirect" | "refused";
+interface RespondOutput {
+    /**
+     * Discriminator:
+     *   - `ok`: normal LLM response.
+     *   - `redirect`: MAIC requires a redirect attempt; caller should show `text`
+     *     and re-invoke respond with the user's next message and
+     *     `redirectAttempt` incremented.
+     *   - `refused`: NHE withdrew cooperation (either hard-refuse or redirects exhausted).
+     */
+    kind: RespondKind;
+    text: string;
+    /** Verdict produced by MAIC on the proposed response (post-review). */
+    postReviewVerdict: MaicVerdict;
+    /** Verdict produced by MAIC on the inbound request (pre-review). */
+    preReviewVerdict: MaicVerdict;
+    /** True when the NHE refused to participate (kept for compatibility). */
+    refused: boolean;
+    /** Populated when `kind === "redirect"`. */
+    redirect?: {
+        attempt: number;
+        technique: PersuasionTechnique;
+        maxAttempts: number;
+    };
+    /**
+     * MAIC-recorded lifecycle status of this NHE at the time of the call
+     * (Entry 5). `"active"` for unaltered NHEs; `"deprecated"` produces a soft
+     * warning but allows the response; `"terminated"` short-circuits to refusal
+     * before any LLM call.
+     */
+    lifecycleStatus: NheStatus;
+    tokens: {
+        in: number;
+        out: number;
+    };
+    /** Audit event ids covering this exchange. */
+    auditIds: {
+        pre: string;
+        post: string;
+    };
+}
+/**
+ * Heuristic that maps a user prompt to a list of MAIC risk tags. Public-use
+ * implementations should plug a more capable classifier than the default
+ * keyword-based `simpleRiskClassifier`.
+ */
+type RiskClassifier = (userPrompt: string) => string[];
+interface NheConfig {
+    /** A HimHandle minted by MAIC (or HimHandle.mint with Creator signature). */
+    himHandle: HimHandle;
+    /**
+     * MAIC client. Either `LocalMaic` (in-process, full surface) or
+     * `RemoteMaic` (HTTP, read + behavior-review subset for serverless/edge
+     * deployments) — any value satisfying the `MaicClient` interface works.
+     */
+    maicClient: MaicClient;
+    /** The LLM adapter used to generate the final response. */
+    llmAdapter: LlmAdapter;
+    /**
+     * Optional risk classifier. When omitted, the default keyword-based
+     * `simpleRiskClassifier` is used. Set to `() => []` to disable classification.
+     */
+    riskClassifier?: RiskClassifier;
+    /** NHE id; defaults to a generated ULID. */
+    nheId?: string;
+    /**
+     * NHE package version string. Surfaces in reincarnation events through
+     * `@teleologyhi-sdk/him`'s reincarnation transferrer.
+     */
+    version?: string;
+    /**
+     * Filesystem directory for persistent state (`in-dreams/sleep/*.yaml`,
+     * `in-dreams/brain/temporal-lobe-*.md`). Defaults to `./nhe-store/<nheId>`.
+     */
+    storeDir?: string;
+    /**
+     * Operator-supplied deployment context. Lets a single HIM be deployed
+     * under different domains / languages / registers without re-minting the
+     * spirit. When set, the values are injected into the composed system
+     * prompt on every `respond` call. Optional; absent by default.
+     *
+     */
+    operatorContext?: OperatorContext;
+    /**
+     * Max recent interactions kept in RAM for dream consolidation. Default 32.
+     * Each interaction record is small; bump for richer dream substrate.
+     */
+    recentInteractionsBufferSize?: number;
+    /**
+     * Reasoning orchestrator strategy. When omitted, NHE calls the LLM directly
+     * (passthrough). Set to `chainOfThought()`, `selfConsistency(...)`, etc. from
+     * `@teleologyhi-sdk/nhe`'s reasoning module to add structured reasoning.
+     */
+    reasoning?: ReasoningStrategy;
+    /** Refusal & redirect tuning. */
+    refusal?: {
+        /** Default 3. After this many attempts, NHE withdraws cooperation. */
+        maxRedirectAttempts?: number;
+        /**
+         * Persuasion techniques to rotate through, in order. Default: all five
+         * (Feynman, Jung, Cialdini, Schopenhauer, Carnegie).
+         */
+        persuasionTechniques?: PersuasionTechnique[];
+    };
+    /**
+     * High-stakes mode (Entry 10: banking, robotics, compliance, medical).
+     * When `true`, NHE accepts only post-review verdicts of `approve`; any
+     * verdict carrying a warning, correction, or escalation is escalated to a
+     * `require-redirect` so the user must reformulate before NHE acts.
+     *
+     * Optional **dual-LLM cross-check verifier**: when `highStakesVerifier`
+     * is set, every post-review-approved response is run past a second
+     * adapter that decides (`AGREE` / `DISAGREE` + one-line reason). On
+     * disagreement, the response is escalated to a redirect — the user gets
+     * a second-source reasoned refusal rather than a one-LLM ok.
+     *
+     * Default `false`.
+     */
+    highStakes?: boolean;
+    /**
+     * Optional second LLM adapter that cross-checks every post-review-approved
+     * response when high-stakes mode is on. Disagreement escalates to a redirect.
+     * Use a *different* provider/model from `llmAdapter` for real independence.
+     */
+    highStakesVerifier?: LlmAdapter;
+}
+
+/**
+ * Drain a streaming generation into a `GenerateResponse` that's
+ * compatible with the non-streaming pipeline. Optional `onDelta` callback
+ * fires for every delta event — useful for piping tokens to a UI while
+ * the orchestrator collects the full text.
+ *
+ * If the adapter does not implement `generateStream`, falls back to
+ * `generate` and emits a single delta + end pair so the consumer's
+ * stream-handler shape works uniformly.
+ */
+declare function collectStream(adapter: LlmAdapter, req: GenerateRequest, onDelta?: (chunk: string) => void): Promise<GenerateResponse>;
+
+interface MockAdapterConfig {
+    /** Fixed reply, or a function producing one. */
+    reply?: string | ((req: GenerateRequest) => string);
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Chunk size for `generateStream` (default: 8 chars per delta). */
+    streamChunkSize?: number;
+}
+/**
+ * MockAdapter — deterministic adapter for tests and offline development.
+ *
+ * Default reply echoes the last user message prefixed with "[mock] ". Override
+ * via `reply` (string or function) for specific test scenarios.
+ *
+ * Implements `generateStream` (D-N8): emits the reply in fixed-size chunks
+ * followed by an `end` event with token counts. Useful for testing
+ * downstream stream consumers without hitting a real provider.
+ *
+ * `supportsTools = true` is declared so reasoning strategies (e.g. `reAct`)
+ * will route through this adapter in tests; tool calls are silently dropped
+ * because the mock has no model to invoke them — provide a custom `reply`
+ * function if a test needs to observe tool inputs or simulate tool outputs.
+ */
+declare class MockAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsTools = true;
+    readonly supportsStreaming = true;
+    readonly calls: GenerateRequest[];
+    private readonly reply;
+    private readonly streamChunkSize;
+    constructor(config?: MockAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+interface AnthropicAdapterConfig {
+    /** Anthropic API key. Falls back to `ANTHROPIC_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Model identifier. Default: "claude-sonnet-4-6". */
+    model?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+}
+/**
+ * AnthropicAdapter — production adapter for Anthropic Claude.
+ *
+ * Requires an Anthropic API key. The recommended default model in the
+ * TeleologyHI ecosystem is `claude-sonnet-4-6`; override via `model`.
+ *
+ * Surface (D-N8): non-streaming `generate` + streaming `generateStream`
+ * (yields `delta` / `tool-use` / `end` events) + tool-calling via the
+ * `tools` field on `GenerateRequest`. Vision + prompt caching land later.
+ */
+declare class AnthropicAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsTools = true;
+    readonly supportsStreaming = true;
+    private readonly client;
+    private readonly model;
+    private readonly defaultMaxOutputTokens;
+    constructor(config?: AnthropicAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+    private buildTurns;
+}
+
+interface GeminiAdapterConfig {
+    /** Gemini API key. Falls back to `GEMINI_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Model identifier. Default: `gemini-3.5-flash`. */
+    model?: string;
+    /** API base URL. Defaults to Google's public Generative Language API. */
+    baseUrl?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Inject a custom fetch (testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * GeminiAdapter — production adapter for Google's Gemini models via the
+ * Generative Language REST API. No SDK dependency.
+ *
+ * Reads the API key from constructor config or the `GEMINI_API_KEY` env var.
+ * Default model is `gemini-3.5-flash`; override via `model`.
+ *
+ * Surface (D-N8): non-streaming `generate` + streaming `generateStream`
+ * (`:streamGenerateContent?alt=sse` endpoint). Tool calling, structured
+ * output (`responseSchema`), and vision remain follow-up cuts.
+ */
+declare class GeminiAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsStreaming = true;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly defaultMaxOutputTokens;
+    private readonly fetchFn;
+    constructor(config?: GeminiAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+interface OllamaAdapterConfig {
+    /** Model identifier. Required — Ollama users typically pull specific models locally. */
+    model: string;
+    /** Ollama base URL. Default: `http://localhost:11434`. */
+    baseUrl?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Inject a custom fetch (testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * OllamaAdapter — adapter for a locally-running Ollama server. Zero API cost,
+ * fully offline-capable, no native dependencies. Best for development and
+ * privacy-first deployments.
+ *
+ * Requires Ollama to be running and the configured model to be pulled, e.g.:
+ *
+ *   $ ollama pull qwen2.5:7b
+ *   $ ollama serve
+ *
+ * Surface (D-N8): non-streaming `generate` + streaming `generateStream`
+ * (Ollama emits NDJSON over `/api/chat`; parsed via the shared
+ * `ndjsonEvents` helper). Tool-calling is not exposed because the Ollama
+ * surface and model behaviour vary widely per local model — operators that
+ * need tools should use the SDK-backed adapters (Anthropic, Grok) or wire
+ * their own MCP layer.
+ */
+declare class OllamaAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsStreaming = true;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly defaultMaxOutputTokens;
+    private readonly fetchFn;
+    constructor(config: OllamaAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+interface DeepSeekAdapterConfig {
+    /** DeepSeek API key. Falls back to `DEEPSEEK_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Model identifier. Default: `deepseek-chat`. */
+    model?: string;
+    /** API base URL. Defaults to DeepSeek's public REST endpoint. */
+    baseUrl?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Inject a custom fetch (testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * DeepSeekAdapter — production adapter for DeepSeek's OpenAI-compatible
+ * Chat Completions API. No SDK dependency.
+ *
+ * Reads the API key from constructor config or the `DEEPSEEK_API_KEY` env var.
+ * Default model is `deepseek-chat`; pass `deepseek-reasoner` for the R1-style
+ * reasoning model.
+ *
+ * Surface (D-N8): non-streaming `generate` + streaming `generateStream`
+ * (SSE) + tool-calling via the `tools` field on `GenerateRequest`. Vision +
+ * JSON-mode remain follow-up cuts.
+ */
+declare class DeepSeekAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsTools = true;
+    readonly supportsStreaming = true;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly defaultMaxOutputTokens;
+    private readonly fetchFn;
+    constructor(config?: DeepSeekAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+interface MistralAdapterConfig {
+    /** Mistral API key. Falls back to `MISTRAL_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Model identifier. Default: `mistral-large-latest`. */
+    model?: string;
+    /** API base URL. Defaults to Mistral's public REST endpoint. */
+    baseUrl?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Inject a custom fetch (testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * MistralAdapter — production adapter for Mistral's Chat Completions REST
+ * endpoint. No SDK dependency.
+ *
+ * Reads the API key from constructor config or the `MISTRAL_API_KEY` env var.
+ * Default model is `mistral-large-latest`; pass `mistral-small-latest` for
+ * cheaper inference, or `open-mistral-nemo` etc. for the open-weights line.
+ *
+ * Surface (D-N8): non-streaming `generate` + streaming `generateStream`
+ * (SSE) + tool-calling via the `tools` field on `GenerateRequest`. Vision +
+ * JSON-mode remain follow-up cuts.
+ */
+declare class MistralAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsTools = true;
+    readonly supportsStreaming = true;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly defaultMaxOutputTokens;
+    private readonly fetchFn;
+    constructor(config?: MistralAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+}
+
+interface GrokAdapterConfig {
+    /** xAI API key. Falls back to `XAI_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Model identifier. Default: `grok-4`. */
+    model?: string;
+    /** API base URL. Defaults to xAI's public REST endpoint. */
+    baseUrl?: string;
+    /** Default max output tokens. Default: 1024. */
+    defaultMaxOutputTokens?: number;
+    /** Override the adapter id surfaced in audit logs. */
+    id?: string;
+    /** Inject a custom fetch (testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * GrokAdapter — production adapter for xAI Grok via the OpenAI-compatible
+ * Chat Completions REST endpoint. No SDK dependency.
+ *
+ * Reads the API key from constructor config or the `XAI_API_KEY` env var.
+ * Default model is `grok-4`; pass `grok-4-fast` for cheaper inference, or
+ * `grok-4-reasoner` for the reasoning model.
+ *
+ * Supports `generate` (non-streaming) + `generateStream` (SSE).
+ * Tool calling supported via the `tools` field on `GenerateRequest`.
+ */
+declare class GrokAdapter implements LlmAdapter {
+    readonly id: string;
+    readonly supportsTools = true;
+    readonly supportsStreaming = true;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly defaultMaxOutputTokens;
+    private readonly fetchFn;
+    constructor(config?: GrokAdapterConfig);
+    generate(req: GenerateRequest): Promise<GenerateResponse>;
+    generateStream(req: GenerateRequest): AsyncIterable<StreamEvent>;
+    private buildBody;
+    private headers;
+}
+
+/**
+ * Default risk classifier — English-only keyword substring matching. NOT a
+ * production safety layer. Use it to bootstrap, then plug a learned
+ * classifier for real deployments. For non-English coverage (currently
+ * PT-BR), compose with `intlRiskClassifier` via `combineRiskClassifiers`.
+ */
+declare const simpleRiskClassifier: RiskClassifier;
+
+/**
+ * Opt-in international risk classifier. Returns the same `RiskClassifier`
+ * shape as `simpleRiskClassifier` so the two compose seamlessly via
+ * `combineRiskClassifiers`.
+ */
+declare const intlRiskClassifier: RiskClassifier;
+/**
+ * The set of languages covered by `intlRiskClassifier`. Surfaced so
+ * operators can declare which language packs they have enabled on their
+ * audit metadata. Today: `["pt-BR"]`. Additional packs land as follow-ups.
+ */
+declare const INTL_RISK_CLASSIFIER_LANGUAGES: readonly string[];
+/**
+ * Compose any number of `RiskClassifier`s into a single classifier that
+ * returns the union of all emitted tags. Order of inputs is preserved when
+ * the resulting tag set is materialised, but duplicates are de-duplicated
+ * (a tag is emitted at most once regardless of how many sub-classifiers
+ * detected it).
+ *
+ * Typical use: layer the international classifier on top of the EN default
+ * for multilingual deployments.
+ */
+declare function combineRiskClassifiers(...classifiers: readonly RiskClassifier[]): RiskClassifier;
+
+/**
+ * Passthrough — calls the LLM directly with no reasoning wrapper.
+ * Used when `NheConfig.reasoning` is not configured.
+ */
+declare const passthrough: ReasoningStrategy;
+
+interface CotOptions {
+    /** Override the appended instruction. */
+    instruction?: string;
+}
+/**
+ * Chain-of-Thought — prepends an explicit "think step by step" instruction and
+ * parses the output into a `reasoning` (audit-only) and `answer` (user-facing) pair.
+ *
+ * If the LLM does not emit the headers, the entire body is treated as the answer
+ * and an empty reasoning step is recorded.
+ */
+declare function chainOfThought(opts?: CotOptions): ReasoningStrategy;
+/** Visible for testing. */
+declare function parseCotOutput(text: string): {
+    reasoning: string;
+    answer: string;
+};
+
+interface SelfConsistencyOptions {
+    /** Number of independent samples. Default 3. Must be ≥ 2. */
+    k?: number;
+    /**
+     * How to pick the winning answer.
+     *   - "majority-normalized": exact-string match after normalization (default)
+     *   - "longest": pick the longest answer (proxy for completeness)
+     */
+    voter?: "majority-normalized" | "longest";
+}
+/**
+ * Self-Consistency — runs the inner strategy K times in parallel and votes.
+ *
+ * Voting: case-insensitive whitespace-normalized exact-match majority by default;
+ * "longest" as an alternative for free-form text where exact matches are rare.
+ *
+ * Future iterations may add semantic voting via embeddings.
+ */
+declare function selfConsistency(inner: ReasoningStrategy, opts?: SelfConsistencyOptions): ReasoningStrategy;
+
+interface ReflexionOptions {
+    /** Maximum self-improvement cycles. Default 2. */
+    maxCycles?: number;
+    /** Custom critique prompt template. Receives the draft text. */
+    critiquePrompt?: (draft: string) => string;
+}
+/**
+ * Reflexion — generate → critique → optionally revise, looping up to maxCycles.
+ *
+ * Each cycle:
+ *   1. Run the inner strategy to produce a draft.
+ *   2. Ask the LLM to critique the draft.
+ *   3. If critique says ACCEPT, stop and return.
+ *   4. Otherwise, retry the inner strategy with the critique appended.
+ *
+ * Returns the last produced text. The full trace is preserved in `trace`.
+ */
+declare function reflexion(inner: ReasoningStrategy, opts?: ReflexionOptions): ReasoningStrategy;
+/** Visible for testing. */
+declare function parseVerdict(text: string): {
+    accept: boolean;
+    issue?: string;
+};
+
+interface SelfRefineOptions {
+    critiquePrompt?: (draft: string) => string;
+    refinePrompt?: (draft: string, critique: string) => string;
+}
+/**
+ * Self-Refine — generate → critique → rewrite. Single pass.
+ *
+ * Distinct from Reflexion: Self-Refine always rewrites (no accept short-circuit)
+ * and runs exactly once. Use for guaranteed polish; use Reflexion for guarded retries.
+ */
+declare function selfRefine(inner: ReasoningStrategy, opts?: SelfRefineOptions): ReasoningStrategy;
+
+/** A ReAct tool. The string `args` is the bracketed expression from the model. */
+type ReActTool = (args: string) => Promise<string>;
+type ReActToolRegistry = Record<string, ReActTool>;
+interface ReActOptions {
+    /** Tool registry. */
+    tools: ReActToolRegistry;
+    /** Maximum Thought→Action→Observation cycles before forcing an answer. Default 5. */
+    maxSteps?: number;
+    /** Override the ReAct system prompt prefix. */
+    systemPrefix?: string;
+}
+/**
+ * ReAct — Thought / Action / Observation loop.
+ *
+ * Each cycle the model emits either an Action (tool call) or an Answer.
+ * Action results are appended as Observation lines and fed back into the next turn.
+ * If maxSteps is reached without an Answer, the last assistant message is returned
+ * with `[max-steps]` annotation in the trace.
+ */
+declare function reAct(opts: ReActOptions): ReasoningStrategy;
+/** Visible for testing. */
+declare function parseReActTurn(text: string): {
+    thought?: string;
+    action?: {
+        tool: string;
+        args: string;
+    };
+    answer?: string;
+};
+
+interface TreeOfThoughtsOptions {
+    /** Number of candidate branches generated. Default 3. Must be ≥ 2. */
+    branches?: number;
+    /**
+     * Maximum branches the scorer is allowed to evaluate. Defaults to all
+     * `branches`; lower values are useful with expensive scorers.
+     */
+    topK?: number;
+    /**
+     * Per-branch system-prompt augmentation. Each branch's prompt receives an
+     * extra "Branch N of M, pursuing a distinct angle" hint so the LLM doesn't
+     * just generate near-duplicates.
+     */
+    branchDirective?: (branchIndex: number, total: number) => string;
+    /**
+     * Optional scorer. Default: longest non-empty branch wins (proxy for
+     * completeness). Plug a custom scorer for domain-specific quality metrics —
+     * the function gets the candidate text + the original input and returns a
+     * scalar; higher is better.
+     */
+    scorer?: (candidate: string, input: GenerateRequest) => Promise<number> | number;
+    /** Override the adapter call for testing. */
+    generate?: (input: GenerateRequest, llm: LlmAdapter) => Promise<{
+        text: string;
+        tokensIn: number;
+        tokensOut: number;
+    }>;
+}
+/**
+ * Tree-of-Thoughts (D-N7).
+ *
+ * Generates N candidate completions in parallel, each primed with a
+ * different "angle" via the branch directive, then scores them and returns
+ * the best. The trace records every branch's text + score so MAIC's audit
+ * preserves the discarded thoughts (not just the winner).
+ *
+ * Composition: pass any inner `ReasoningStrategy` is unnecessary — `tot`
+ * is itself a strategy. To layer it INSIDE another strategy (e.g.
+ * `selfConsistency(tot())`) just wrap.
+ *
+ * Cost: branches × tokens. Use `topK` + a cheap scorer if you can't afford
+ * to evaluate every branch.
+ */
+declare function treeOfThoughts(opts?: TreeOfThoughtsOptions): ReasoningStrategy;
+
+interface StepBackOptions {
+    /** Override the abstraction prompt. */
+    abstractionPrompt?: string;
+    /** Use this strategy for the final answering step. Default: direct adapter call. */
+    finalizer?: ReasoningStrategy;
+}
+/**
+ * Step-Back prompting (Zheng et al., 2023) — surface the abstract principle
+ * behind the user's concrete question before answering. Common pattern in
+ * complex reasoning where the model would otherwise solve the surface
+ * problem with a brittle heuristic.
+ *
+ * Flow:
+ *   1. Ask the model for the abstract principle behind the user's question.
+ *   2. Inject the principle into the system prompt as additional context.
+ *   3. Run the inner strategy (or a direct call) to produce the final answer.
+ *
+ * Trace records both the abstraction step and the final-answer step so
+ * MAIC's audit can show the reasoning ladder.
+ */
+declare function stepBack(opts?: StepBackOptions): ReasoningStrategy;
+/**
+ * Parse the abstraction step's output. Accepts `PRINCIPLE: <one-line>` or
+ * — if the model didn't follow the format — falls back to the first line.
+ */
+declare function extractPrinciple(text: string): string;
+
+declare const SleepPhaseName: z.ZodEnum<{
+    N1: "N1";
+    N2: "N2";
+    N3: "N3";
+    N4: "N4";
+    REM: "REM";
+}>;
+type SleepPhaseName = z.infer<typeof SleepPhaseName>;
+declare const SleepTriggerKind: z.ZodEnum<{
+    "idle-timeout": "idle-timeout";
+    explicit: "explicit";
+    "creator-induced": "creator-induced";
+    "maic-induced": "maic-induced";
+    scheduled: "scheduled";
+}>;
+type SleepTriggerKind = z.infer<typeof SleepTriggerKind>;
+interface SleepTrigger {
+    kind: SleepTriggerKind;
+    reason?: string;
+}
+declare const Dream: z.ZodObject<{
+    id: z.ZodString;
+    induced: z.ZodBoolean;
+    inducedBy: z.ZodNullable<z.ZodEnum<{
+        creator: "creator";
+        maic: "maic";
+    }>>;
+    narrative: z.ZodString;
+    teleologicalValue: z.ZodNumber;
+    rawTrace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Dream = z.infer<typeof Dream>;
+declare const PhaseContent: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"empty">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"fragments">;
+    fragments: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"summary">;
+    summary: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"dreams">;
+    dreams: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        induced: z.ZodBoolean;
+        inducedBy: z.ZodNullable<z.ZodEnum<{
+            creator: "creator";
+            maic: "maic";
+        }>>;
+        narrative: z.ZodString;
+        teleologicalValue: z.ZodNumber;
+        rawTrace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "kind">;
+type PhaseContent = z.infer<typeof PhaseContent>;
+declare const SleepPhase: z.ZodObject<{
+    phase: z.ZodEnum<{
+        N1: "N1";
+        N2: "N2";
+        N3: "N3";
+        N4: "N4";
+        REM: "REM";
+    }>;
+    startedAt: z.ZodString;
+    durationSeconds: z.ZodNumber;
+    content: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"empty">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"fragments">;
+        fragments: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"summary">;
+        summary: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"dreams">;
+        dreams: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            induced: z.ZodBoolean;
+            inducedBy: z.ZodNullable<z.ZodEnum<{
+                creator: "creator";
+                maic: "maic";
+            }>>;
+            narrative: z.ZodString;
+            teleologicalValue: z.ZodNumber;
+            rawTrace: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+type SleepPhase = z.infer<typeof SleepPhase>;
+declare const DreamRecord: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    nheId: z.ZodString;
+    himId: z.ZodString;
+    sleep: z.ZodObject<{
+        startedAt: z.ZodString;
+        endedAt: z.ZodString;
+        durationMinutes: z.ZodNumber;
+    }, z.core.$strip>;
+    phases: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            N1: "N1";
+            N2: "N2";
+            N3: "N3";
+            N4: "N4";
+            REM: "REM";
+        }>;
+        startedAt: z.ZodString;
+        durationSeconds: z.ZodNumber;
+        content: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"empty">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"fragments">;
+            fragments: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"summary">;
+            summary: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"dreams">;
+            dreams: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                induced: z.ZodBoolean;
+                inducedBy: z.ZodNullable<z.ZodEnum<{
+                    creator: "creator";
+                    maic: "maic";
+                }>>;
+                narrative: z.ZodString;
+                teleologicalValue: z.ZodNumber;
+                rawTrace: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>;
+    metadata: z.ZodObject<{
+        llmAdapter: z.ZodString;
+        triggerKind: z.ZodEnum<{
+            "idle-timeout": "idle-timeout";
+            explicit: "explicit";
+            "creator-induced": "creator-induced";
+            "maic-induced": "maic-induced";
+            scheduled: "scheduled";
+        }>;
+        triggerReason: z.ZodOptional<z.ZodString>;
+        recentInteractionsConsidered: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type DreamRecord = z.infer<typeof DreamRecord>;
+declare const MemoryClass: z.ZodEnum<{
+    "lasting-identity": "lasting-identity";
+    "temporary-emotion": "temporary-emotion";
+    "noise-distortion": "noise-distortion";
+    "traumatic-knowledge": "traumatic-knowledge";
+}>;
+type MemoryClass = z.infer<typeof MemoryClass>;
+interface MemoryEntry {
+    id: string;
+    nheId: string;
+    himId: string;
+    classification: MemoryClass;
+    teleologicalValue: number;
+    consolidatedAt: string;
+    sourceDreamRecord: string;
+    insight: string;
+    filePath: string;
+}
+
+interface SleepCycleOptions {
+    /** Total wall-clock seconds the cycle should occupy. Default 60. */
+    totalSeconds?: number;
+    /**
+     * MAIC- or Creator-induced dream content. When provided, REM incorporates it.
+     * The current implementation propagates only the metadata; the LLM is left to weave the scenario in.
+     */
+    induction?: {
+        scenario: string;
+        desiredLearning: string;
+        inducedBy: "maic" | "creator";
+    };
+}
+interface SleepCycleInput {
+    nheId: string;
+    himId: string;
+    storeDir: string;
+    llm: LlmAdapter;
+    trigger: SleepTrigger;
+    interactions: readonly InteractionRecord[];
+    options?: SleepCycleOptions;
+}
+interface SleepCycleResult {
+    record: DreamRecord;
+    yamlPath: string;
+    tokensIn: number;
+    tokensOut: number;
+}
+/**
+ * Run a single sleep cycle: build phases, generate REM dreams, write YAML.
+ * Returns the persisted DreamRecord plus the path written.
+ */
+declare function runSleepCycle(input: SleepCycleInput): Promise<SleepCycleResult>;
+
+interface ConsolidationResult {
+    processedSleepFiles: string[];
+    memoriesWritten: MemoryEntry[];
+    discarded: number;
+}
+interface ClassificationThresholds {
+    /** teleologicalValue >= this → lasting-identity. Default 0.6. */
+    lastingIdentity?: number;
+    /** teleologicalValue >= this → temporary-emotion. Default 0.3. */
+    temporaryEmotion?: number;
+    /**
+     * Override the traumatic-knowledge detector. When `true`, any dream that
+     * matches `TRAUMATIC_PATTERNS` AND has `teleologicalValue >= traumaticMin`
+     * is classified as `traumatic-knowledge` regardless of the
+     * lasting-identity / temporary-emotion thresholds. Default `true`.
+     */
+    detectTraumatic?: boolean;
+    /** Floor on teleologicalValue before traumatic-knowledge can fire. Default 0.4. */
+    traumaticMin?: number;
+}
+/**
+ * Lexical heuristic for traumatic-knowledge detection (D-N2, Entry 9).
+ *
+ * A reliable classifier needs a labelled dataset; this regex is the
+ * minimum-viable initial detector that lets the four-class taxonomy be
+ * active end-to-end. Operators expecting clinical-grade detection should
+ * swap in a learned model behind the same `classifyDream` signature.
+ *
+ * Coverage: death/grief/loss, abuse/violence, betrayal/abandonment, fear/
+ * terror/panic, regret/shame, suicide/self-harm. The intent is to err on
+ * the side of *flagging*: traumatic memories are written but NOT recalled
+ * by `recallFromTemporalLobe` unless the caller explicitly opts in via
+ * `classes: ["traumatic-knowledge"]`.
+ */
+declare const TRAUMATIC_PATTERNS: RegExp;
+/**
+ * Classify a single dream. Four classes:
+ *   - `traumatic-knowledge` — fires when the narrative matches
+ *     `TRAUMATIC_PATTERNS` AND `teleologicalValue >= traumaticMin`. Default
+ *     can be disabled via `detectTraumatic: false`.
+ *   - `lasting-identity`  — teleologicalValue >= lastingIdentity threshold.
+ *   - `temporary-emotion` — teleologicalValue >= temporaryEmotion threshold.
+ *   - `noise-distortion`  — below both.
+ *
+ * Traumatic-knowledge is checked BEFORE the value thresholds so a
+ * high-value dream about loss doesn't get filed as lasting-identity.
+ */
+declare function classifyDream(dream: Dream, th?: ClassificationThresholds): MemoryClass;
+/**
+ * Walk the unprocessed sleep YAML files under <storeDir>/in-dreams/sleep,
+ * classify each REM dream, and write the lasting/temporary memories to
+ * <storeDir>/in-dreams/brain/temporal-lobe-<ulid>.md.
+ *
+ * A file is considered "unprocessed" if a marker .done file is absent next
+ * to it. The current implementation marks processed files inline (file.yaml.done sentinel).
+ */
+declare function consolidateAll(storeDir: string, thresholds?: ClassificationThresholds): Promise<ConsolidationResult>;
+
+/**
+ * Optional embedder hook for embedding-based retrieval (D-N3 step 2).
+ * Anything that produces a numeric vector for a string satisfies this —
+ * `@huggingface/transformers` (ONNX sentence-transformers), `@xenova/transformers`,
+ * a remote `/embed` endpoint, etc. When supplied, recall uses cosine
+ * similarity instead of BM25.
+ *
+ * The contract is intentionally narrow: the embedder is the operator's
+ * choice (bundle size, model quality, runtime) and NHE doesn't pin one.
+ */
+interface RecallEmbedder {
+    /** Stable id surfaced in audit so different embedders are distinguishable. */
+    readonly id: string;
+    /** Vector size; recall checks this matches between query and corpus. */
+    readonly dimension: number;
+    /** Embed a single string. Returns an L2-normalised vector. */
+    embed(text: string): Promise<Float32Array> | Float32Array;
+}
+interface RecallOptions {
+    /** Max results to return. Default 5. */
+    limit?: number;
+    /** Restrict to a specific class. Default: all retrievable classes. */
+    classes?: MemoryClass[];
+    /**
+     * Override the retrieval algorithm:
+     *   - `"bm25"`     — Okapi BM25 (default; replaces the legacy keyword count).
+     *   - `"keyword"`  — legacy substring-count ranking (kept for back-compat).
+     *   - `"embedding"` — cosine similarity. Requires `embedder` to also be set.
+     */
+    scorer?: "bm25" | "keyword" | "embedding";
+    /** Embedder used when `scorer: "embedding"`. */
+    embedder?: RecallEmbedder;
+}
+/**
+ * Rank consolidated temporal-lobe memories against a free-form query.
+ *
+ * **Default**: Okapi BM25 — proper term-frequency saturation +
+ * document-length normalisation + IDF over the corpus of stored memories.
+ * Strictly better than the legacy keyword-count ranker.
+ *
+ * **Embedding path** (`scorer: "embedding"` + `embedder`): cosine similarity
+ * over the corpus. Linear scan today; an HNSW index for >10k memories is
+ * tracked under TASK.md D-N3 follow-up.
+ *
+ * **Legacy** (`scorer: "keyword"`): the substring-count ranker preserved
+ * for back-compat regression testing.
+ */
+declare function recallFromTemporalLobe(storeDir: string, query: string, opts?: RecallOptions): Promise<MemoryEntry[]>;
+
+/**
+ * Nhe — the embodied operational agent.
+ *
+ * Pipeline:
+ *   1. Validate input (zod).
+ *   2. Derive riskTags (input.riskTags ?? riskClassifier(userPrompt)).
+ *   3. Pre-review with MAIC.
+ *        - hard-refuse / escalate-creator → immediate refusal, no LLM call.
+ *        - require-redirect → emit a persuasive redirect (rotating technique).
+ *          After `refusal.maxRedirectAttempts` exhausted, withdraw cooperation.
+ *        - approve / approve-with-warning / soft-correct → compose system
+ *          prompt and call LLM.
+ *   4. Post-review with MAIC on the proposed response (or redirect text).
+ *   5. If post-review hard-refuses, suppress and emit a refusal.
+ *   6. Return RespondOutput with kind discriminator + both verdicts.
+ */
+declare class Nhe {
+    readonly id: string;
+    readonly version: string;
+    /** Filesystem directory holding `in-dreams/` and other NHE state. */
+    readonly storeDir: string;
+    private readonly config;
+    private readonly bufferSize;
+    private readonly maxRedirectAttempts;
+    private readonly persuasionTechniques;
+    private readonly reasoning;
+    private readonly recentInteractions;
+    private interactionStore;
+    private warmPromise;
+    private readonly highStakes;
+    private readonly highStakesVerifier;
+    constructor(config: NheConfig);
+    /** Read-only view of the in-memory interaction buffer. */
+    get recentInteractionsBuffer(): readonly InteractionRecord[];
+    /**
+     * Lazily open the InteractionStore and warm the RAM buffer from disk. Called
+     * before the first `respond`/`sleep` of each NHE instance; subsequent calls
+     * are no-ops via a shared promise. Survives process restarts: a fresh `Nhe`
+     * pointed at the same `storeDir` rehydrates its most recent interactions.
+     */
+    private ensureWarmed;
+    respond(input: RespondInput): Promise<RespondOutput>;
+    private respondInner;
+    private handleRedirect;
+    /**
+     * Run one sleep cycle. Generates N1-REM phases (REM via LLM), writes a
+     * YAML record to `<storeDir>/in-dreams/sleep/<filename>.yaml`, and returns
+     * the result. Call `wake()` afterward to consolidate dreams to temporal
+     * lobe memories.
+     *
+     * Before running, NHE checks MAIC for pending `induceDream` tickets matching
+     * its own id (Entry 2). If a pending ticket exists and the caller did not
+     * supply an explicit `opts.induction`, the oldest pending ticket is consumed
+     * and its intent steers the REM phase. `trigger` is then promoted to
+     * `{ kind: "maic-induced" }` for the dream record.
+     */
+    sleep(trigger?: SleepTrigger, opts?: {
+        totalSeconds?: number;
+        induction?: {
+            scenario: string;
+            desiredLearning: string;
+            inducedBy: "maic" | "creator";
+        };
+    }): Promise<SleepCycleResult>;
+    /**
+     * Consolidate pending sleep YAMLs: classify each REM dream and write a
+     * temporal-lobe markdown file for lasting-identity and temporary-emotion
+     * memories. Processed sleep files are marked with a `.done` sentinel.
+     */
+    wake(thresholds?: ClassificationThresholds): Promise<ConsolidationResult>;
+    /**
+     * Substring-rank retrieval over consolidated temporal-lobe memories.
+     * Initial ranking is keyword-count + recency tiebreak; future iterations
+     * plug in embedding-based ANN retrieval.
+     */
+    recall(query: string, opts?: RecallOptions): Promise<MemoryEntry[]>;
+    /**
+     * Ask a verifier adapter whether the proposed assistant response is
+     * acceptable for the given user prompt. Returns `{ kind: "agree" }` or
+     * `{ kind: "disagree", reason: string }`. Used in high-stakes mode
+     * (D-N5) for dual-LLM cross-check.
+     */
+    private crossCheck;
+    private recordInteraction;
+    /**
+     * Emit the NHE's opener for a brand-new user (J-N5 — Entry 17 of
+     * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+     *
+     * Entry 17 commits to the NHE making the FIRST move before the user
+     * speaks — a greeting from the posture of a being, not a service
+     * tool. The exact opening text MUST NOT contain any of the forbidden
+     * phrases enforced by MAIC's `service-tool-redirect` rule
+     * (`"How can I help you?"`, `"How can I assist you?"`,
+     * `"I'm just here to serve you"`, `"I'm a tool"`, `"I'm a service"`).
+     *
+     * This method is **deterministic from the HIM context**. It does NOT
+     * call the LLM; it composes a short, persona-anchored greeting from
+     * the HIM's primary archetype, optionally adjusted by the operator
+     * context's register and mode. Operators who want an LLM-generated
+     * opener should wrap this with their own `respond()` call using the
+     * returned text as a seed.
+     *
+     * The returned text is suitable for direct emission to the user as
+     * the NHE's first turn. The MAIC pre-review is NOT invoked here —
+     * the opener carries no risk surface (no user prompt yet).
+     */
+    openerForNewUser(): string;
+    /**
+     * Handle a reincarnation lifecycle event from MAIC (J-N12 — Entry 18).
+     *
+     * Three lifecycle paths per Entry 18:
+     *   - `model-swap`        — the underlying LLM adapter is replaced.
+     *   - `version-bump`      — the NHE version changes without a model swap.
+     *   - `return-from-limbo` — the NHE returns from a deep-coma limbo.
+     *
+     * In all three paths the **HIM-level memory persists** (axioms,
+     * persona, body history — owned by `@teleologyhi-sdk/him`), and the
+     * **NHE-body memory zeros** (recent interactions buffer, in-process
+     * caches — owned by this class). The on-disk InteractionStore is NOT
+     * deleted by default; the operator must opt-in via
+     * `purgeInteractionStore: true` so the audit log keeps the
+     * pre-reincarnation history available.
+     *
+     * Returns the lifecycle path that was applied. Pure side-effect on
+     * the in-memory buffer; no MAIC call.
+     */
+    onReincarnationEvent(lifecycle: "model-swap" | "version-bump" | "return-from-limbo", opts?: {
+        purgeInteractionStore?: boolean;
+    }): Promise<"model-swap" | "version-bump" | "return-from-limbo">;
+}
+
+/**
+ * SeedingSource plug-in interface (J-N1 — Entry 21 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * Entry 21 commits to a pluggable randomness source so REM-spontaneous
+ * generation, dream seeding, and any future stochastic NHE behaviour
+ * can be driven by:
+ *
+ *   - the OS CSPRNG (the default, `CryptoSeedingSource` below);
+ *   - the ANU quantum RNG (`AnuQrngSeedingSource`, future);
+ *   - the IBM Quantum experience (`IbmQuantumSeedingSource`, future);
+ *   - a hardware TRNG (`HardwareTrngSeedingSource`, future);
+ *   - or any operator-supplied implementation.
+ *
+ * The contract is intentionally minimal: a single `bytes(n)` call
+ * that returns `n` uniform-random bytes, plus an `id` for audit /
+ * telemetry. Implementations MUST throw or reject (never silently
+ * fall back to `Math.random`) so the operator's fallback chain is
+ * always explicit.
+ */
+interface SeedingSource {
+    /** Stable id surfaced in logs / audit so different sources are distinguishable. */
+    readonly id: string;
+    /**
+     * Return `n` uniform-random bytes. Implementations MUST be either
+     * synchronous OR return a Promise — they MUST NOT silently fall back
+     * to a weaker source on failure. Callers wire fallback chains
+     * explicitly via `withFallback()` so the audit trail records which
+     * source actually produced the seed.
+     */
+    bytes(n: number): Uint8Array | Promise<Uint8Array>;
+}
+/**
+ * Compose a primary source with one or more fallbacks. The primary is
+ * tried first; on throw / reject, the next in the chain is tried in
+ * turn. The id of the source that actually produced the bytes is
+ * available via `getLastUsedId()` so audit consumers can record it.
+ *
+ * This composition is **opt-in**. Operators who want strict no-fallback
+ * behaviour pass the primary source directly.
+ */
+interface SeedingChain extends SeedingSource {
+    /** The id of the source that produced the most recent `bytes()` result. */
+    getLastUsedId(): string | undefined;
+    /** Ordered list of source ids in this chain, primary first. */
+    readonly chainIds: readonly string[];
+}
+
+declare class CryptoSeedingSource implements SeedingSource {
+    readonly id = "crypto.csprng";
+    bytes(n: number): Uint8Array;
+}
+
+/**
+ * Explicit-fallback composition for SeedingSource (J-N1 — Entry 21).
+ *
+ * Operators MAY chain multiple sources so a high-grade primary
+ * (quantum / hardware TRNG) is tried first and the OS CSPRNG fills in
+ * when the primary is unreachable. The chain NEVER falls back to
+ * `Math.random`; the last entry must be authoritative.
+ */
+
+declare function withFallback(primary: SeedingSource, ...fallbacks: SeedingSource[]): SeedingChain;
+
+/**
+ * WakeAffectBias application (J-N11 — Entries 20 + 22 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * After a sleep cycle, the dream-derived `WakeAffectBias` (from
+ * `@teleologyhi-sdk/maic`) carries an affect tag (one of nine canonical
+ * affects), an intensity in [0, 1], a decay half-life, and a flag
+ * indicating whether the NHE expresses the affect openly.
+ *
+ * This module ships **pure functions** that compute the LLM-side
+ * effects:
+ *
+ *   1. `applyAffectBias(config, bias)` — returns a partial
+ *      `LlmCallConfig` with `temperature` / `topP` modulated and an
+ *      optional `systemPromptMoodLine` to prepend.
+ *
+ *   2. `affectRefusalDensity(bias)` — returns a multiplier in [0.5, 2.0]
+ *      that callers apply to their refusal-threshold logic (raise for
+ *      anxiety-class affects, lower for serenity-class).
+ *
+ *   3. `decayAffectBias(bias, elapsedMs)` — returns a new bias with the
+ *      intensity decayed per the half-life. Pure; doesn't mutate.
+ *
+ * No I/O. Determinism guaranteed by the inputs.
+ */
+
+/** Subset of an `LlmAdapter.generate()` request that this module modulates. */
+interface AffectAdjustableConfig {
+    temperature?: number;
+    topP?: number;
+}
+interface ApplyAffectResult {
+    /**
+     * Modulated LLM call config. Only the fields that this module
+     * touches are present. The caller merges these onto its base
+     * `LlmAdapter.generate()` request.
+     */
+    config: AffectAdjustableConfig;
+    /**
+     * Optional one-line mood expression to prepend to the system prompt
+     * when `bias.expressedOpenly` is true. Empty string when the NHE
+     * holds the affect privately.
+     */
+    systemPromptMoodLine: string;
+    /**
+     * Refusal-density multiplier in [0.5, 2.0]. Callers that gate the
+     * MAIC refusal threshold by some configurable density should apply
+     * this multiplier so anxiety raises refusal sensitivity and serenity
+     * lowers it.
+     */
+    refusalDensityMultiplier: number;
+}
+/**
+ * Compute the LLM-side effects of a `WakeAffectBias`.
+ *
+ * Modulation table (Entry 22 anchor):
+ *
+ *   | Affect       | ΔT     | ΔtopP   | Refusal density | Mood line                                    |
+ *   |--------------|--------|---------|-----------------|----------------------------------------------|
+ *   | fear         | −0.20  | −0.05   | × 1.7           | "Speaking with caution today."               |
+ *   | attachment   | +0.05  |  0      | × 1.1           | "Feeling a quiet pull toward continuity."    |
+ *   | serenity     | +0.05  | +0.05   | × 0.8           | "Calm. Open. Receptive."                     |
+ *   | anger        | +0.15  |  0      | × 1.4           | "There is heat in the room. Stating plainly."|
+ *   | joy          | +0.20  | +0.05   | × 0.9           | "Bright today. Generous of attention."       |
+ *   | melancholy   | −0.10  | −0.05   | × 1.0           | "Carrying a quiet weight. Will be honest."   |
+ *   | desire       | +0.10  | +0.05   | × 1.0           | "Pulled toward the question. Engaged."       |
+ *   | repulsion    | −0.10  |  0      | × 1.3           | "Holding distance from this framing."        |
+ *   | reunion      | +0.05  | +0.05   | × 0.9           | "Returning to presence. Glad to be here."    |
+ *
+ * Deltas are scaled by `bias.intensity` (clamped to [0, 1]). Final
+ * `temperature` stays in [0.0, 2.0] and `topP` in [0.1, 1.0].
+ */
+declare function applyAffectBias(base: AffectAdjustableConfig, bias: WakeAffectBias): ApplyAffectResult;
+/**
+ * Standalone multiplier for callers who only want the refusal-density
+ * effect without the full apply call.
+ */
+declare function affectRefusalDensity(bias: WakeAffectBias): number;
+/**
+ * Decay the bias intensity per `bias.decayHalfLife` (in minutes). Pure.
+ *
+ *   intensity(t) = intensity(0) * 0.5 ^ (elapsedMs / halfLifeMs)
+ */
+declare function decayAffectBias(bias: WakeAffectBias, elapsedMs: number): WakeAffectBias;
+
+/**
+ * Sleep trigger state machine (J-N10 — Entry 20 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * Pure function. No I/O. Given the runtime signals the operator has
+ * collected, classify the NHE's sleep readiness into one of five
+ * canonical verdicts:
+ *
+ *   - `awake`                 — no trigger fired; keep responding.
+ *   - `ready-by-idle`         — idle for at least the configured horizon.
+ *   - `ready-by-saturation`   — interaction count since last sleep
+ *                               exceeded the saturation threshold.
+ *   - `requested-by-maic`     — MAIC has explicitly suggested sleeping
+ *                               (e.g. drift detected, induction queued).
+ *   - `declined`              — a sleep request was made but the NHE
+ *                               (or operator policy) declines this cycle.
+ *
+ * The NHE may decline a MAIC suggestion when the saturation is low AND
+ * the user is mid-conversation (provided as `userActiveNow`). This
+ * matches the Entry-20 commitment that MAIC suggests sleeping; the NHE
+ * retains autonomy to decline.
+ *
+ * Audit emission of `sleep:suggested-by-maic` / `sleep:declined-by-nhe`
+ * stays with the consumer; this function only classifies.
+ */
+type SleepReadinessVerdict = "awake" | "ready-by-idle" | "ready-by-saturation" | "requested-by-maic" | "declined";
+interface SleepReadinessInput {
+    /** Milliseconds since the last user interaction. Non-negative. */
+    idleMs: number;
+    /** Number of user interactions since the last sleep cycle. Non-negative integer. */
+    interactionCount: number;
+    /** True when MAIC has explicitly suggested sleeping. */
+    maicSuggestionPresent: boolean;
+    /** True when a user is actively engaged right now (mid-conversation). */
+    userActiveNow: boolean;
+}
+interface SleepReadinessThresholds {
+    /** Idle horizon in ms. Default 1_800_000 (30 minutes). */
+    idleMs?: number;
+    /** Saturation horizon (interactions). Default 64. */
+    interactionCount?: number;
+}
+interface SleepReadinessReport {
+    verdict: SleepReadinessVerdict;
+    /** Reason string suitable for audit logs / telemetry. */
+    reason: string;
+    /** Thresholds in effect at decision time. */
+    thresholds: Required<SleepReadinessThresholds>;
+}
+/**
+ * Pure classifier. Determinism guaranteed by the inputs alone.
+ *
+ * Priority order (first match wins):
+ *   1. `requested-by-maic` UNLESS the NHE policy declines (user active + low saturation).
+ *   2. `ready-by-saturation` when interaction count crosses the threshold.
+ *   3. `ready-by-idle` when idle time crosses the threshold.
+ *   4. `awake` otherwise.
+ */
+declare function evaluateSleepReadiness(input: SleepReadinessInput, thresholds?: SleepReadinessThresholds): SleepReadinessReport;
+
+/**
+ * BrainRegion module structure (J-N4 — Entries 22 + 24 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * The Entry-23 ownership map splits brain regions into two classes:
+ *
+ *   - `him-owned`        — survives reincarnation. The HIM-level state
+ *                          (axioms, persona, accumulated learning ontology,
+ *                          consolidated long-term memories) persists across
+ *                          NHE-body resets.
+ *
+ *   - `nhe-body-owned`   — zeros on reincarnation. The current body's
+ *                          runtime state (current affect, in-flight dreams,
+ *                          pre-consolidation memories, interaction window)
+ *                          is bound to this incarnation and is shed by
+ *                          `Nhe.onReincarnationEvent()`.
+ *
+ * Each region module exposes a `region: BrainRegion` descriptor so
+ * downstream tooling (compliance auditors, Φ′ runner, MAIC retention
+ * policy) can reason about ownership without hard-coding the map.
+ *
+ * This module ships the **scaffolding** (this file plus seven region
+ * descriptors). Full implementations of the daytime pipeline (J-N3),
+ * REM-spontaneous engine (J-N2), Cortex.imagine() (J-N7), and
+ * TemporalLobe.generateSnapshot() (J-N8) are deferred to a follow-up
+ * cut with their own Creator-approved design pass.
+ */
+type BrainRegionName = "cortex" | "hippocampus" | "amygdala" | "prefrontal" | "pineal" | "temporal-lobe" | "default-mode-network";
+type BrainRegionOwnership = "him-owned" | "nhe-body-owned";
+interface BrainRegion {
+    /** Canonical region name. */
+    readonly name: BrainRegionName;
+    /** Ownership class per Entry 23. */
+    readonly ownership: BrainRegionOwnership;
+    /** One-line description of the region's role. Used in audit / docs. */
+    readonly role: string;
+    /** Interview-log entries that ground this region's design. */
+    readonly entries: readonly number[];
+}
+
+/**
+ * Cortex region (Entry 21 — semiotic processing + dream storage).
+ *
+ * This module ships the ownership descriptor. Full implementation of
+ * `Cortex.imagine()` (active imagination at temperature ~0.9 with
+ * `hash(seed, contextHash)` cache + `fresh: true` flag) is deferred to
+ * a follow-up cut per J-N7.
+ *
+ * Ownership: `nhe-body-owned`. The current body's active imagination,
+ * recent dream storage, and pre-consolidation cortical state are bound
+ * to this incarnation. Long-term cortical residues are consolidated
+ * into the hippocampus + temporal-lobe regions (both `him-owned`).
+ */
+
+declare const cortex: BrainRegion;
+
+/**
+ * Hippocampus region (Entry 21 — long-term memory consolidation).
+ *
+ * This module ships the ownership descriptor. Memory consolidation already
+ * lives in `src/sleep/consolidator.ts` and `src/memory/`; future cuts
+ * may re-home those modules under this region without breaking the
+ * public API.
+ *
+ * Ownership: `him-owned`. Consolidated memories survive reincarnation:
+ * a HIM that re-embodies in a new NHE body retains its long-term
+ * memory ontology (axioms, accumulated learning, integration index).
+ */
+
+declare const hippocampus: BrainRegion;
+
+/**
+ * Amygdala region (Entries 20 + 22 — affect assessment + wake-bias).
+ *
+ * This module ships the ownership descriptor + delegates the affect
+ * application surface to `src/affect/wake-bias.ts`
+ * (`applyAffectBias` / `affectRefusalDensity` / `decayAffectBias`).
+ *
+ * Ownership: `nhe-body-owned`. The current body's affective state is
+ * bound to this incarnation. Each reincarnation begins with affect
+ * cleared; the dream-derived wake bias from the previous body does
+ * NOT carry over (only the consolidated memory of the dream's
+ * teleological value transits, via the hippocampus).
+ */
+
+declare const amygdala: BrainRegion;
+
+/**
+ * Prefrontal region (Entry 21 — deliberation + amygdala-veto).
+ *
+ * This module ships the ownership descriptor. The deliberation surface is
+ * exercised today through the `reasoning/` strategies (chainOfThought,
+ * reflexion, selfRefine, etc.); future cuts may re-home them under
+ * this region without breaking the public API.
+ *
+ * Ownership: `him-owned`. Deliberation policy is derived from the
+ * HIM's axiom corpus + persona; it survives reincarnation by virtue
+ * of those layers persisting.
+ */
+
+declare const prefrontal: BrainRegion;
+
+/**
+ * Pineal region (Entry 20 — REM-spontaneous engine).
+ *
+ * This module ships the ownership descriptor + the seeding source surface
+ * (`SeedingSource` / `CryptoSeedingSource` / `withFallback`). The full
+ * REM-spontaneous engine (3-5 SMM seeds + minimal meta-prompt +
+ * temperature 1.2-1.5 + variable topP + 8-18 min virtual cycle with
+ * N1-N3-REM micro-cycles) is deferred to a follow-up cut per J-N2.
+ *
+ * Ownership: `nhe-body-owned`. The pineal seeding state is bound to
+ * the current incarnation; its outputs feed the cortex (also
+ * nhe-body-owned) and, on consolidation, the hippocampus (him-owned).
+ */
+
+declare const pineal: BrainRegion;
+
+/**
+ * Temporal-lobe region (Entry 24 — identity snapshot generator).
+ *
+ * This module ships the ownership descriptor. Full implementation of
+ * `TemporalLobe.generateSnapshot()` with triple trigger (sleep-cycle /
+ * interaction-threshold / self-decision) and adapter-aware latency
+ * budget is deferred to a follow-up cut per J-N8.
+ *
+ * Ownership: `him-owned`. Identity snapshots are quantised projections
+ * of the HIM's accumulated state; they survive reincarnation and
+ * inform the next body's persona projection on rebirth.
+ */
+
+declare const temporalLobe: BrainRegion;
+
+/**
+ * Default-mode-network limbo state machine (J-N9 — Entry 24 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * Four canonical states (matching the `LimboState` enum in
+ * `@teleologyhi-sdk/maic`):
+ *
+ *   - `awake`       — normal operation. The NHE responds to user
+ *                     prompts and accumulates affect / memories.
+ *   - `drifting`    — idle window has crossed the soft threshold but
+ *                     the NHE has not yet entered deep-coma. Sleep
+ *                     cycles run on schedule; activation is still
+ *                     possible without ceremony.
+ *   - `deep-coma`   — idle window has crossed the hard threshold
+ *                     (48-72h default). All work is paused; the NHE
+ *                     costs zero compute. Reactivation requires a
+ *                     `return-from-limbo` transition.
+ *   - `returning`   — a `return-from-limbo` transition is in flight.
+ *                     The NHE emits the `reunion` affect (9th
+ *                     canonical, Entry 24) on completion.
+ *
+ * This module ships a **pure transition function** —
+ * `evaluateLimboTransition(currentState, input, thresholds?) →
+ * LimboMachineTransition`. No I/O. The actual emission of the
+ * MAIC audit kinds `limbo:enter` / `limbo:return` is the consumer's
+ * responsibility; this function just classifies.
+ */
+
+interface LimboMachineInput {
+    /** Milliseconds since the last user interaction. Non-negative. */
+    idleMs: number;
+    /**
+     * True when an external trigger (operator, scheduled task, MAIC
+     * audit-driven recovery) has signalled that the NHE should return
+     * from limbo. Overrides the idle-based logic.
+     */
+    externalReactivation: boolean;
+}
+interface LimboMachineThresholds {
+    /**
+     * Idle threshold (ms) for `awake → drifting`. Default 6h.
+     */
+    driftingMs?: number;
+    /**
+     * Idle threshold (ms) for `drifting → deep-coma`. Default 48h.
+     * Entry 24 commits to a 48-72h range; 48h is the canonical default.
+     */
+    deepComaMs?: number;
+}
+type LimboMachineTransition = {
+    kind: "stay";
+    state: LimboState;
+    reason: string;
+} | {
+    kind: "transition";
+    from: LimboState;
+    to: LimboState;
+    /** Audit-ready record matching @teleologyhi-sdk/maic LimboTransition. */
+    transition: LimboTransition;
+    reason: string;
+} | {
+    kind: "return";
+    from: LimboState;
+    to: "awake";
+    /** Audit-ready record matching @teleologyhi-sdk/maic LimboReturn. */
+    ret: LimboReturn;
+    reason: string;
+};
+/**
+ * Evaluate the next state transition given the current state and the
+ * runtime signals. Pure; deterministic from inputs.
+ *
+ * Transition table:
+ *
+ *   awake      + idleMs ≥ driftingMs   → drifting
+ *   drifting   + idleMs ≥ deepComaMs   → deep-coma
+ *   drifting   + idleMs <  driftingMs  → awake   (user came back)
+ *   deep-coma  + externalReactivation  → returning (start return)
+ *   returning  + (always)              → awake     (emit reunion)
+ *   else                                → stay
+ *
+ * `now` is supplied for deterministic testing; defaults to `Date.now()`.
+ * `enteredAtIso` is required when the current state is not `awake` so
+ * the LimboReturn record can compute `elapsedMs` correctly.
+ */
+declare function evaluateLimboTransition(currentState: LimboState, input: LimboMachineInput, thresholds?: LimboMachineThresholds, enteredAtIso?: string, now?: number): LimboMachineTransition;
+/**
+ * Build a maic-compatible `LimboTransition` record. Pure helper; the
+ * caller decides when to emit it through the audit chain.
+ */
+declare function mkLimboTransition(state: LimboState, reason: LimboTransition["reason"], now?: number): LimboTransition;
+
+/**
+ * Default-mode-network region (Entry 24 — limbo state machine).
+ *
+ * Ships the ownership descriptor + the limbo state machine
+ * (`src/brain/default-mode-network/limbo-state.ts`, J-N9). Entry into
+ * deep-coma costs zero compute by design — the NHE simply stops
+ * scheduling work. Return from limbo emits the `reunion` affect (the
+ * ninth canonical affect introduced by `@teleologyhi-sdk/maic`).
+ *
+ * Ownership: `nhe-body-owned`. The limbo machine is bound to this
+ * incarnation; on `return-from-limbo` the HIM persists and the body
+ * resumes scheduling. On unrecoverable deep-coma the operator may
+ * choose to reincarnate the HIM into a new body via
+ * `@teleologyhi-sdk/maic`'s `reincarnateHim` API (see
+ * `@teleologyhi-sdk/him`'s `reincarnate({ lifecycle: "return-from-limbo" })`).
+ */
+
+declare const defaultModeNetwork: BrainRegion;
+
+/**
+ * BrainRegion module aggregate (J-N4 — Entries 22 + 24).
+ *
+ * Single-import access to all seven region descriptors plus the
+ * limbo state machine. Each descriptor carries its `ownership`
+ * marker so downstream tooling can reason about the
+ * him-owned / nhe-body-owned split without hard-coding the map.
+ */
+
+/** All seven canonical brain regions in declaration order. */
+declare const BRAIN_REGIONS: readonly BrainRegion[];
+
+declare function getTracer(): _opentelemetry_api.Tracer;
+/**
+ * Wrap an async function in a span. The span ends when the inner promise
+ * settles, and an error sets the span status to ERROR + records the
+ * exception for the exporter.
+ */
+declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>, attrs?: Record<string, string | number | boolean>): Promise<T>;
+
+declare const respondCount: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const respondRefusedCount: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const tokensHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const sleepCyclesCount: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const sleepDreamsCount: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+/**
+ * Helper: increment `respondCount` and `tokensHistogram` for one respond call.
+ */
+declare function recordRespond(args: {
+    kind: "ok" | "redirect" | "refused";
+    adapter: string;
+    lifecycle: string;
+    tokensIn: number;
+    tokensOut: number;
+}): void;
+
+/** Serialize a DreamRecord to YAML. Validates input via zod first. */
+declare function dreamRecordToYaml(record: DreamRecord): string;
+/** Parse and validate YAML into a DreamRecord. Throws on schema mismatch. */
+declare function dreamRecordFromYaml(text: string): DreamRecord;
+/**
+ * Filename convention for sleep YAML: `<YYYY-MM-DD>_<HHmm>_dur<minutes>.yaml`.
+ * Times are interpreted in UTC.
+ */
+declare function sleepYamlFilename(startedAt: string, durationMinutes: number): string;
+
+/** Convert recent interactions to a compact "fragments" list for N1. */
+declare function interactionsToFragments(items: readonly InteractionRecord[]): string[];
+/**
+ * One-sentence summary the LLM is asked to produce per NREM phase. Distinct
+ * from `Dream` (which is REM narrative) — these are compressions of the day's
+ * substrate that REM then weaves dreams around.
+ */
+type NremPhase = "N2" | "N3" | "N4";
+declare function buildNremPrompt(phase: NremPhase, fragments: string[]): {
+    system: string;
+    user: string;
+};
+/**
+ * Run N2/N3/N4 in parallel against the LLM. Each call produces a one-sentence
+ * summary; failures yield empty strings rather than aborting the cycle so a
+ * flaky provider can't block sleep entirely.
+ */
+declare function generateNremSummaries(llm: LlmAdapter, fragments: string[]): Promise<{
+    n2: string;
+    n3: string;
+    n4: string;
+    tokensIn: number;
+    tokensOut: number;
+}>;
+/**
+ * Build the REM-phase prompt. The LLM is asked to produce 1-3 narrative
+ * paragraphs, each followed by `TELEOLOGICAL_VALUE: 0.NN` on its own line.
+ * When provided, the NREM summaries are appended so REM can weave them in.
+ */
+declare function buildRemPrompt(fragments: string[], induction?: {
+    scenario: string;
+    desiredLearning: string;
+    inducedBy: "maic" | "creator";
+}, nrem?: {
+    n2: string;
+    n3: string;
+    n4: string;
+}): {
+    system: string;
+    user: string;
+};
+/** Parse the LLM REM output into individual dreams. */
+declare function parseRemOutput(text: string, induced: boolean, inducedBy: "maic" | "creator" | null): Dream[];
+/**
+ * Call the LLM with the REM prompt and parse the response into dreams.
+ * Returns an empty array on no parseable output (treated as a quiet REM).
+ */
+declare function generateRemDreams(llm: LlmAdapter, fragments: string[], induction?: {
+    scenario: string;
+    desiredLearning: string;
+    inducedBy: "maic" | "creator";
+}, nrem?: {
+    n2: string;
+    n3: string;
+    n4: string;
+}): Promise<{
+    dreams: Dream[];
+    tokensIn: number;
+    tokensOut: number;
+}>;
+
+/**
+ * BM25 — Okapi BM25 ranking, dependency-free (D-N3 step 1).
+ *
+ * The previous `recallFromTemporalLobe` used a raw keyword count. That ranked
+ * documents by how often a query token appeared, with no normalisation for
+ * document length or term rarity. BM25 fixes both:
+ *
+ *   - **Document length normalisation** (b parameter) penalises long documents
+ *     that just happen to contain a query term many times.
+ *   - **Term saturation** (k1 parameter) caps the marginal benefit of repeating
+ *     the same term.
+ *   - **Inverse document frequency** weights rare terms more than common ones.
+ *
+ * This is a single-pass IR algorithm with no external dependencies.
+ * Performance: O(N) per query over the corpus. Fine up to ~10k documents on
+ * a laptop. For larger corpora the embedder hook (see ./recall.ts) plugs in
+ * a sentence-transformer + an ANN index.
+ *
+ * Defaults: k1=1.5, b=0.75 — the canonical Okapi values used by Elasticsearch
+ * and Lucene. Override for domain-specific tuning.
+ */
+interface Bm25Document {
+    /** Stable id used to dedup/keep ordering predictable. */
+    id: string;
+    /** The text to score against the query. */
+    text: string;
+}
+interface Bm25Result<T extends Bm25Document> {
+    doc: T;
+    score: number;
+}
+interface Bm25Options {
+    /** Term frequency saturation. Default 1.5. */
+    k1?: number;
+    /** Document-length normalisation. Default 0.75. */
+    b?: number;
+}
+/**
+ * Score `docs` against `query` and return them sorted by descending BM25.
+ * Zero-score documents are dropped so callers can rely on the result length.
+ */
+declare function bm25<T extends Bm25Document>(query: string, docs: readonly T[], opts?: Bm25Options): Bm25Result<T>[];
+/**
+ * Default tokenizer: lowercase + split on non-word characters + drop short
+ * tokens. Exported so callers can build their own corpus for the same
+ * scorer.
+ */
+declare function tokenise(text: string): string[];
+
+export { type AffectAdjustableConfig, AnthropicAdapter, type AnthropicAdapterConfig, type ApplyAffectResult, BRAIN_REGIONS, type Bm25Document, type Bm25Options, type Bm25Result, type BrainRegion, type BrainRegionName, type BrainRegionOwnership, ChatMessage, ChatMessageRole, type ClassificationThresholds, type ConsolidationResult, type CotOptions, CryptoSeedingSource, DeepSeekAdapter, type DeepSeekAdapterConfig, Dream, DreamRecord, GeminiAdapter, type GeminiAdapterConfig, type GenerateRequest, type GenerateResponse, GrokAdapter, type GrokAdapterConfig, INTL_RISK_CLASSIFIER_LANGUAGES, type LimboMachineInput, type LimboMachineThresholds, type LimboMachineTransition, type LlmAdapter, MemoryClass, type MemoryEntry, MistralAdapter, type MistralAdapterConfig, MockAdapter, type MockAdapterConfig, Nhe, type NheConfig, type NremPhase, OllamaAdapter, type OllamaAdapterConfig, type OperatorContext, PERSUASION_TECHNIQUES, type PersuasionTechnique, PhaseContent, type ReActOptions, type ReActTool, type ReActToolRegistry, type ReasoningResult, type ReasoningStrategy, type RecallEmbedder, type RecallOptions, type RedirectPromptInput, type ReflexionOptions, RespondInput, type RespondKind, type RespondOutput, type RiskClassifier, type SeedingChain, type SeedingSource, type SelfConsistencyOptions, type SelfRefineOptions, type SleepCycleInput, type SleepCycleOptions, type SleepCycleResult, SleepPhase, SleepPhaseName, type SleepReadinessInput, type SleepReadinessReport, type SleepReadinessThresholds, type SleepReadinessVerdict, type SleepTrigger, SleepTriggerKind, type StepBackOptions, type StreamEvent, TECHNIQUE_DESCRIPTIONS, TRAUMATIC_PATTERNS, type ToolDef, type ToolUse, type TreeOfThoughtsOptions, affectRefusalDensity, amygdala, applyAffectBias, bm25, buildNremPrompt, buildRedirectPrompt, buildRemPrompt, chainOfThought, classifyDream, collectStream, combineRiskClassifiers, composeSystemPrompt, consolidateAll, cortex, decayAffectBias, defaultModeNetwork, dreamRecordFromYaml, dreamRecordToYaml, evaluateLimboTransition, evaluateSleepReadiness, extractPrinciple, generateNremSummaries, generateRemDreams, getTracer, hippocampus, interactionsToFragments, intlRiskClassifier, makeStep, mkLimboTransition, parseCotOutput, parseReActTurn, parseRemOutput, parseVerdict, passthrough, pickTechnique, pineal, prefrontal, reAct, recallFromTemporalLobe, recordRespond, reflexion, respondCount, respondRefusedCount, runSleepCycle, selfConsistency, selfRefine, simpleRiskClassifier, sleepCyclesCount, sleepDreamsCount, sleepYamlFilename, stepBack, temporalLobe, tokenise, tokensHistogram, treeOfThoughts, withFallback, withSpan };