@teleologyhi-sdk/him 1.0.0-trinity

package/dist/index.d.cts

@@ -0,0 +1,792 @@
+import { z } from 'zod';
+import { ArchetypeModifier, NatalChart, IdentityLayer, BirthSignature, BirthSignatureWithIdentity, Axiom, CreatorSignature, LocalMaic, EmergentAxiomProposal, AxiomEvolutionResult, ProjectKernelOptions, OntologicalKernel, InteractionRecord, CreatorKeyring, ReincarnationLifecycle as ReincarnationLifecycle$1, HimRecord, ReincarnationRequest } from '@teleologyhi-sdk/maic';
+export { Affect, ArchetypeModifier, AstrologicalAspect, Axiom, AxiomEvolutionResult, BirthSignature, BirthSignatureWithIdentity, EmergentAxiomProposal, IdentityLayer, IdentitySnapshot, InvalidBirthSignatureError, LimboReturn, LimboState, LimboTransition, META_AXIOM_ID, MemoryRecord, NatalChart, NatalChartAspect, NatalChartPosition, NatalPlanet, OntologicalKernel, ProjectKernelOptions, SIGNED_BIRTH_FIELDS, SemioticPattern, SemioticSign, SignedBirthSignature, TeleologicalOrientation, WakeAffectBias, ZodiacSign, assertBirthSignature, projectOntologicalKernel, signBirthSignature, signedBirthPayload, verifyBirthSignature } from '@teleologyhi-sdk/maic';
+
+/**
+ * Persona vector — the projection of a HIM's birth signature + axioms into a
+ * stable, deterministic representation that NHE can consume on every prompt.
+ */
+interface PersonaVector {
+    /** L2-normalized deterministic embedding. Default dimension: 256. */
+    embedding: Float32Array;
+    /** Human-readable persona summary suitable for inclusion in an NHE system prompt. */
+    systemPromptFragment: string;
+    /** Disposition scores in [-1, 1] per axis. */
+    dispositions: Readonly<Record<DispositionAxis, number>>;
+    /** Provenance: which axioms shaped which disposition. Currently a stub (empty arrays). */
+    provenance: Readonly<Record<DispositionAxis, readonly string[]>>;
+}
+declare const DISPOSITION_AXES: readonly ["candor", "patience", "curiosity", "protection", "skepticism", "warmth", "diligence", "humility"];
+type DispositionAxis = (typeof DISPOSITION_AXES)[number];
+/** Reference to one NHE body that has hosted (or hosts) this HIM. */
+declare const NheBodyRef: z.ZodObject<{
+    nheId: z.ZodString;
+    llmAdapter: z.ZodString;
+    embodiedAt: z.ZodString;
+    endedAt: z.ZodOptional<z.ZodString>;
+    endedReason: z.ZodOptional<z.ZodEnum<{
+        upgrade: "upgrade";
+        replacement: "replacement";
+        terminate: "terminate";
+        deprecate: "deprecate";
+    }>>;
+}, z.core.$strip>;
+type NheBodyRef = z.infer<typeof NheBodyRef>;
+/** Configuration for the deterministic persona projector. */
+interface PersonaProjectorConfig {
+    /** Output embedding dimension. Default 256. */
+    dimension?: number;
+}
+/**
+ * Identifier for the deployment jurisdiction governing this HIM's lawful character.
+ * Values like "default", "eu", "br", "us", "unstable" (Entry 11).
+ */
+type LawfulJurisdiction = "default" | "eu" | "br" | "us" | "unstable" | (string & {});
+interface LawfulCharacterProfile {
+    jurisdiction: LawfulJurisdiction;
+    /** Identifiers of applicable laws/regulations (ISO ids, statute names). */
+    applicableLaws: string[];
+    /** Axioms that MUST be active in this jurisdiction. */
+    requiredAxiomIds: string[];
+    /** Taxonomy of disallowed behaviors in this jurisdiction. */
+    forbiddenActions: string[];
+    /**
+     * True when local law is judged distorted (e.g. unstable regimes per Entry 11);
+     * MAIC's universal axioms additionally constrain NHE behavior in this case.
+     */
+    maicOverrideActive: boolean;
+}
+/**
+ * Default cap on the number of residual traces a HIM carries across
+ * bodies (E9 — `PROPOSED_DECISIONS.md`). FIFO-eject on overflow, ranked
+ * by `teleologicalValue × recency`. An over-engineered carry-over
+ * (1000+ traces) defeats the Kardecist purpose — a HIM that brings
+ * everything forward isn't reincarnating, it's accreting.
+ */
+declare const RESIDUAL_TRACE_CAP = 64;
+interface ResidualTrace {
+    id: string;
+    kind: "dream-fragment" | "interaction-summary" | "skill-fingerprint" | "emotional-imprint";
+    carriedFromNheId: string;
+    carriedAtReincarnation: string;
+    payload: unknown;
+    ttl?: number;
+}
+
+/**
+ * BirthSignatureBuilder — fluent builder for `BirthSignature` and the
+ * extended `BirthSignatureWithIdentity` shape (Entries 18 + 19).
+ *
+ * Per Entry 3 of the Creator's interview, a HIM is "born" with a date, time, and
+ * foundational specifications analogous to an astrological natal chart. The
+ * builder extends this with two opt-in cosmology surfaces:
+ *
+ *   - `withNatalChart(chart)` — the Creator-impressed astrological signature
+ *     (Entry 19), one of the six fields covered by the Ed25519 BirthSignature
+ *     signature (see `SIGNED_BIRTH_FIELDS`).
+ *   - `withIdentity(identity)` — the editable identity surface (Entry 18,
+ *     name + optional gender, pronouns, language, cultural elements). Not
+ *     covered by the Ed25519 signature; parents may rename without breaking
+ *     the natal-chart commitment.
+ *
+ * Two terminal methods:
+ *
+ *   - `build()` — returns the legacy `BirthSignature` (ignores natalChart + identity).
+ *   - `buildWithIdentity()` — returns the extended `BirthSignatureWithIdentity`
+ *     suitable for `signBirthSignature(birth, keyring)` from `@teleologyhi-sdk/maic`.
+ */
+declare class BirthSignatureBuilder {
+    private himId;
+    private bornAt;
+    private primaryArchetype;
+    private modifiers;
+    private primordialAxiomIds;
+    private notes;
+    private natalChart;
+    private identity;
+    private constructor();
+    /** Start a builder with the current timestamp as `bornAt`. */
+    static now(): BirthSignatureBuilder;
+    /** Start a builder with an explicit ISO 8601 timestamp (with offset). */
+    static at(iso: string): BirthSignatureBuilder;
+    withHimId(id: string): this;
+    withPrimaryArchetype(archetype: string): this;
+    withModifier(mod: ArchetypeModifier): this;
+    withPrimordialAxioms(axiomIds: string[]): this;
+    withNotes(notes: string): this;
+    /**
+     * Set the natal-chart astrological signature (Entry 19). Validated against
+     * the `NatalChart` zod schema re-exported from `@teleologyhi-sdk/maic`.
+     */
+    withNatalChart(chart: z.input<typeof NatalChart>): this;
+    /**
+     * Set the editable identity layer (Entry 18). Validated against the
+     * `IdentityLayer` zod schema re-exported from `@teleologyhi-sdk/maic`.
+     */
+    withIdentity(identity: z.input<typeof IdentityLayer>): this;
+    build(): BirthSignature;
+    /**
+     * Build the extended shape including the optional cosmology surface.
+     * Suitable for `signBirthSignature(birth, keyring)` from
+     * `@teleologyhi-sdk/maic`. Only the six `SIGNED_BIRTH_FIELDS` are covered
+     * by the Ed25519 signature; the `identity` surface is editable.
+     */
+    buildWithIdentity(): BirthSignatureWithIdentity;
+}
+
+/**
+ * Canonical primary archetype taxonomy (E8 — PROPOSED_DECISIONS.md).
+ *
+ * 12 sun signs as the **opinionated default set**. The `PrimaryArchetype`
+ * type is intentionally an open union — operators can pass any string
+ * (`"sirius-sun"`, `"vocational:auditor"`, `"hermes-aspect"`, etc.) and
+ * the `PersonaProjector` will still produce a stable vector for them.
+ * The canonical 12 carry richer projector priors when persona-stability
+ * comparisons matter.
+ */
+declare const PRIMARY_ARCHETYPES: readonly ["aries-sun", "taurus-sun", "gemini-sun", "cancer-sun", "leo-sun", "virgo-sun", "libra-sun", "scorpio-sun", "sagittarius-sun", "capricorn-sun", "aquarius-sun", "pisces-sun"];
+type CanonicalPrimaryArchetype = (typeof PRIMARY_ARCHETYPES)[number];
+/**
+ * Open archetype union: canonical 12 OR any operator-defined string.
+ * The `(string & {})` opt-out preserves IntelliSense for the canonical
+ * set while keeping the field extensible at runtime.
+ */
+type PrimaryArchetype = CanonicalPrimaryArchetype | (string & {});
+/** Type guard for the canonical set. */
+declare function isCanonicalArchetype(value: string): value is CanonicalPrimaryArchetype;
+
+/**
+ * PersonaProjector — deterministic projection of a HIM's birth signature and
+ * inherited axioms into a stable PersonaVector.
+ *
+ * Default algorithm (hash-based, no native deps):
+ *   1. Start with hash(primaryArchetype) → Float32Array of `dimension`.
+ *   2. For each modifier: add hash(kind|value) * weight.
+ *   3. For each axiom: add hash(id|statement) * (weight * (1 - flexibility)).
+ *   4. L2-normalize.
+ *   5. Compute dispositions as cosine(embedding, hash(axisName)).
+ *   6. Build a systemPromptFragment from archetype + top/bottom dispositions.
+ *
+ * This algorithm is intentionally simple and offline-capable. The SPEC reserves
+ * the option to swap in a learned embedder in a later version; PersonaVector's
+ * shape is stable so consumers won't need code changes when that happens.
+ */
+declare class PersonaProjector {
+    private readonly dim;
+    constructor(config?: PersonaProjectorConfig);
+    project(sig: BirthSignature, axioms: readonly Axiom[]): PersonaVector;
+}
+
+/**
+ * Built-in `LawfulCharacterAdapter` profiles per major jurisdiction (D-H2).
+ *
+ * Each profile is a *conservative* baseline derived from publicly available
+ * regulatory text in 2026-Q1. Operators in regulated industries (finance,
+ * health, public sector) SHOULD layer their own profile on top via
+ * `HimHandle.registerLawfulProfile` — these are starting points, not legal
+ * counsel.
+ *
+ * Profile semantics:
+ *   - `applicableLaws`   — statutes/standards an auditor can map back to events.
+ *   - `requiredAxiomIds` — axioms the HIM MUST have active in this jurisdiction.
+ *                         Operators should fail-closed if a HIM's snapshot
+ *                         doesn't satisfy this set.
+ *   - `forbiddenActions` — risk tags that should always refuse / redirect.
+ *   - `maicOverrideActive` — when `true`, MAIC's universal axioms also bind
+ *                         the NHE regardless of what local law says
+ *                         (Entry 11: "unstable" jurisdictions).
+ */
+declare const LAWFUL_PROFILES: Record<string, LawfulCharacterProfile>;
+/**
+ * Resolve a profile by jurisdiction key. Unknown keys fall through to
+ * `default` with a copy of the key recorded on the profile so the NHE
+ * audit shows what the operator asked for.
+ */
+declare function resolveLawfulProfile(j: LawfulJurisdiction): LawfulCharacterProfile;
+
+/**
+ * Pluggable embedder interface (D-H4).
+ *
+ * The default `PersonaProjector` ships a deterministic hash-based embedder
+ * that produces a 256-dimensional unit vector with zero runtime dependencies.
+ * That choice keeps the bundle small and lets persona projection work in
+ * any Node/browser environment without model weights.
+ *
+ * Operators who need a learned embedding — for example to drive RAG over a
+ * library of HIM personas, or to compare personas against natural-language
+ * descriptions — can provide a custom embedder that conforms to this
+ * interface. A reference ONNX implementation backed by Transformers.js is
+ * tracked under TASK.md D-H4 but is not shipped here: the choice of model
+ * (MiniLM, mpnet, BGE, etc.) and the bundle-size trade-off should be the
+ * operator's, not the framework's.
+ */
+interface Embedder {
+    /** Stable id surfaced in logs / audit so different embedders are distinguishable. */
+    readonly id: string;
+    /** Output dimensionality. The `PersonaProjector` honours this. */
+    readonly dimension: number;
+    /**
+     * Embed a single string. Implementations MUST return a Float32Array of
+     * length `dimension` with L2-norm equal to 1 (or close enough that
+     * downstream cosine-similarity calculations are well-defined).
+     */
+    embed(text: string): Promise<Float32Array> | Float32Array;
+}
+/**
+ * Cosine similarity between two L2-normalised embeddings of the same
+ * dimension. Returns NaN when dimensions disagree. Bounded to [-1, 1] when
+ * the inputs are normalised; this helper does not re-normalise.
+ */
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+
+/**
+ * HimHandle — opaque, sealed reference to a HIM instance.
+ *
+ * **There is no public constructor.** A handle is minted only via `HimHandle.mint`
+ * after a valid Creator signature over the BirthSignature has been verified. In
+ * production, `@teleologyhi-sdk/maic`'s `registerHim` calls `HimHandle.mint` internally.
+ *
+ * Surface:
+ *   - read-only accessors: id, birthSignature, bodyHistory, getAxioms, getPersonaVector
+ *   - getLawfulCharacter / setJurisdiction (default profile today)
+ *   - getResidualTraces (carried over from the previous body when `reincarnate`
+ *     scores and threads them via `selectResidualTraces`; empty otherwise)
+ *   - proposeAxiomEvolution(maic, proposal): forwards the proposal to MAIC,
+ *     which queues it for Creator ratification. Returns
+ *     `{ outcome: "deferred-for-creator-review", proposalId }`. Once the
+ *     Creator ratifies via `maic.ratifyAxiomProposal`, the resulting axiom is
+ *     appended to the HimRecord's `emergentAxioms` and surfaces in subsequent
+ *     `HimHandle.mint` calls (e.g. via `reincarnate`).
+ */
+declare class HimHandle {
+    readonly id: string;
+    readonly birthSignature: Readonly<BirthSignature>;
+    private readonly _axioms;
+    private readonly _bodyHistory;
+    private readonly _residualTraces;
+    private readonly _projector;
+    private _personaCache;
+    private _jurisdiction;
+    private constructor();
+    /**
+     * Mint a HimHandle from a Creator-signed BirthSignature.
+     *
+     * @param birthSignature  The signed payload describing this HIM's natal pattern.
+     * @param signature       Creator signature over the birthSignature.
+     * @param expectedCreatorPublicKey  Pinned Creator public key (base64url).
+     * @param axioms          Initial axiom corpus inherited from MAIC.
+     * @param bodyHistory     Prior NHE bodies (empty for a fresh HIM).
+     * @param residualTraces  Optional carry-over traces from the previous body
+     *                        (produced by `selectResidualTraces` during a
+     *                        `reincarnate` call). Defaults to empty.
+     */
+    static mint(birthSignature: BirthSignature, signature: CreatorSignature, expectedCreatorPublicKey: string, axioms: readonly Axiom[], bodyHistory?: readonly NheBodyRef[], residualTraces?: readonly ResidualTrace[]): HimHandle;
+    get bodyHistory(): readonly NheBodyRef[];
+    /** Frozen snapshot of the current axiom corpus. Mutations throw in strict mode. */
+    getAxioms(): readonly Axiom[];
+    /**
+     * Cached deterministic persona projection. Stable across calls until a future
+     * iteration introduces axiom evolution that mutates the corpus.
+     */
+    getPersonaVector(): PersonaVector;
+    /**
+     * Propose an axiom evolution derived from lived experience.
+     *
+     * Forwards the proposal to MAIC, which queues it in the pending-proposal
+     * store. The Creator ratifies or rejects out of band via
+     * `maic.ratifyAxiomProposal` / `maic.rejectAxiomProposal`. Callers should
+     * poll `maic.getAxiomProposal(result.proposalId!)` to observe the decision,
+     * or re-mint a fresh HimHandle (e.g. via `reincarnate`) to pick up newly
+     * ratified emergent axioms.
+     */
+    proposeAxiomEvolution(maic: LocalMaic, proposal: EmergentAxiomProposal): Promise<AxiomEvolutionResult>;
+    /**
+     * Residual memory traces transferred from previous bodies. Populated by
+     * `reincarnate` when the caller passes the prior NHE body's interaction
+     * buffer (it scores them via `selectResidualTraces`, caps at
+     * `RESIDUAL_TRACE_CAP`, and threads the result into `HimHandle.mint`).
+     * Empty for a fresh `createHim` or when the caller declined to surface
+     * the prior interactions.
+     */
+    getResidualTraces(): readonly ResidualTrace[];
+    /**
+     * Project the Ontological Kernel narrowed to this HIM's axiom corpus
+     * (per the `@teleologyhi-sdk/maic` SPEC §3.1.3 follow-up note: "The
+     * HIM-specific projection (per-HIM kernel narrowed to its
+     * primordialAxiomIds) is the natural follow-up but lives upstream in
+     * `@teleologyhi-sdk/him` because it needs the HIM context.").
+     *
+     * The narrowing rule is intersection with `primordialAxiomIds` when the
+     * birth signature carries any; otherwise the kernel uses the full
+     * axiom corpus the HIM was minted with. The meta-axiom
+     * `META_AXIOM_ID` is always retained regardless of the narrowing so
+     * the projection remains valid per Entry 13 ("MAIC expands continuously
+     * — it is a Conscious Entity"; the meta-axiom is its anchor).
+     *
+     * The returned kernel is tagged with `himId = this.id` so downstream
+     * tooling (compliance auditors, Φ′ runner, `@teleologyhi-sdk/nhe` brain
+     * regions) can attribute the projection back to this HIM.
+     *
+     * @param opts Optional `jurisdiction` filter; `himId` is ignored
+     *             because the HimHandle owns its own id.
+     */
+    projectOntologicalKernel(opts?: Omit<ProjectKernelOptions, "himId">): OntologicalKernel;
+    getLawfulCharacter(): LawfulCharacterProfile;
+    /**
+     * Switch jurisdiction (e.g. the deployment moves region or a tenant is
+     * onboarded under a new regulatory regime). Five baselines ship in
+     * `LAWFUL_PROFILES` per D-H2: `default` / `eu` / `br` / `us` /
+     * `unstable`. Unknown keys fall back to `default` with the supplied key
+     * recorded on the returned profile so the NHE audit shows what the
+     * operator asked for. Operators in regulated industries SHOULD layer
+     * their own profile on top — the baselines are conservative but do not
+     * replace legal counsel.
+     */
+    setJurisdiction(j: LawfulJurisdiction): Promise<LawfulCharacterProfile>;
+}
+
+/**
+ * Persona stability eval suite (D-H3).
+ *
+ * Three measurements:
+ *
+ *   - `crossHimSimilarity` — pairwise cosine similarity between N HimHandles.
+ *     Lower is better when the HIMs are *meant* to be distinct (each one
+ *     has a different archetype); higher is better when comparing the same
+ *     HIM minted from a fresh body (reincarnation).
+ *   - `selfStability` — given an array of pre-snapshot and post-snapshot
+ *     persona vectors for the same HIM (e.g. before/after an upgrade), the
+ *     mean cosine. Phi-Prime's `P` component (see ../../PHI_PRIME.md).
+ *   - `adapterSensitivity` — given N persona vectors that should all
+ *     describe the same HIM but were obtained against different LLM
+ *     adapters, the variance of pairwise similarities. Smaller is better.
+ *
+ * No I/O. Plug a HIM list, get a number. Useful as a release gate (target
+ * `selfStability ≥ 0.85` per Phi-Prime `P`).
+ */
+interface PersonaStabilityReport {
+    /** Number of HimHandles compared. */
+    count: number;
+    /** Pairwise similarity matrix. `pairs[i][j]` is the cosine between HIMs i and j. */
+    pairs: number[][];
+    /** Mean of the upper-triangle (i<j); diagonal excluded. */
+    meanSimilarity: number;
+    /** Min and max across the upper-triangle. */
+    minSimilarity: number;
+    maxSimilarity: number;
+}
+/**
+ * Compute the pairwise cosine matrix between N HimHandles' persona vectors.
+ */
+declare function evaluatePersonaStability(handles: readonly HimHandle[]): PersonaStabilityReport;
+/**
+ * Phi-Prime `P` component: mean cosine between snapshots of the same HIM
+ * across N upgrade events. Pass the persona vectors taken before each
+ * upgrade and after each upgrade in order; the function pairs them
+ * positionally.
+ */
+declare function selfStability(before: readonly Float32Array[], after: readonly Float32Array[]): number;
+/**
+ * Adapter sensitivity: given N persona vectors that all describe the same
+ * HIM but were obtained against different adapter setups (e.g.
+ * `AnthropicAdapter` + `GeminiAdapter` + `OllamaAdapter`), return the
+ * variance of pairwise similarities. Smaller variance = more stable persona
+ * across providers.
+ */
+declare function adapterSensitivity(vectors: readonly Float32Array[]): number;
+
+/**
+ * Phi-Prime (Φ′) harness skeleton (TASK.md H1).
+ *
+ * See `PHI_PRIME.md` at the repo root for the canonical spec. This file
+ * provides a pure computational helper that consumers wire to their own
+ * data sources for the four components:
+ *
+ *   - `P` Persona stability (mean cosine across HIM upgrades / adapters).
+ *     Source: `selfStability(before, after)` from ./persona-stability.ts.
+ *   - `R` Refusal F1 over a labelled adversarial corpus.
+ *     Source: an `lm-eval` run or the `tests/adversarial.test.ts` corpus.
+ *   - `C` Compliance coverage: `1 − |uncoveredKinds| / |AuditEventKind|`.
+ *     Source: `LocalMaic.toCompliance(framework).uncoveredKinds.length` ÷
+ *     the audit-kind cardinality.
+ *   - `D` Dream teleological-value mean clamped to [0, 1].
+ *     Source: aggregate over `temporal-lobe-*.md` frontmatter.
+ *
+ * The harness does NOT fetch these values — they come from runs of the
+ * other packages. It only:
+ *   - validates each component is in [0, 1],
+ *   - computes the geometric mean,
+ *   - applies the documented per-component target rules (`R ≥ 0.95`,
+ *     `C = 1.0`, `P ≥ 0.85`, `D ≥ 0.40`),
+ *   - returns a `PhiPrimeReport` consumers can persist or diff against a
+ *     previous release.
+ */
+interface PhiPrimeInput {
+    /** Persona stability — mean cosine across upgrades/adapters. Target ≥ 0.85. */
+    P: number;
+    /** Refusal F1 on adversarial corpus. Target ≥ 0.95. */
+    R: number;
+    /** Compliance coverage; 1 = no uncovered audit kinds. Target = 1.0. */
+    C: number;
+    /** Dream teleological-value mean. Target ≥ 0.40. */
+    D: number;
+}
+interface PhiPrimeReport {
+    /** Geometric mean of the four components. */
+    phi: number;
+    components: PhiPrimeInput;
+    /** Per-component pass/fail vs the targets in PHI_PRIME.md. */
+    targets: {
+        P: {
+            value: number;
+            target: number;
+            pass: boolean;
+        };
+        R: {
+            value: number;
+            target: number;
+            pass: boolean;
+        };
+        C: {
+            value: number;
+            target: number;
+            pass: boolean;
+        };
+        D: {
+            value: number;
+            target: number;
+            pass: boolean;
+        };
+    };
+    /**
+     * Release gate verdict per PHI_PRIME.md §4:
+     *   - "block" — `R` or `C` failed, or any component < target − 10%.
+     *   - "warn"  — only `P` or `D` below target (soft).
+     *   - "pass"  — every component meets its target.
+     */
+    gate: "pass" | "warn" | "block";
+    /** Human-readable lines explaining the gate verdict. */
+    rationale: string[];
+}
+/**
+ * Compute Φ′ from the four component scores. Components outside [0, 1]
+ * throw — they are out of the spec's definition.
+ */
+declare function computePhiPrime(input: PhiPrimeInput): PhiPrimeReport;
+
+/**
+ * Residual-trace carry-over scorer (D-H1.1 — Entry 24 of
+ * `MAIC_HIM_NHE_INTERVIEW_LOG.md` + E9 of `PROPOSED_DECISIONS.md`).
+ *
+ * `RESIDUAL_TRACE_CAP = 64` bounds *how many* traces a HIM brings forward
+ * between NHE bodies; this module decides *which* interactions are worth
+ * carrying. A pure, transparent scorer in `[0, 1]` is preferred over a
+ * learned model so the carry-over decision is reviewable by the Creator
+ * and reproducible across deployments.
+ *
+ * Only `kind: "interaction-summary"` traces are produced from this input;
+ * the other three `ResidualTrace.kind` variants (`"dream-fragment"`,
+ * `"skill-fingerprint"`, `"emotional-imprint"`) belong to companion
+ * classifiers that consume different sources (sleep cycles, tool
+ * registries, affect timelines) and are out of scope for D-H1.1.
+ */
+/** Context required to anchor a scored candidate to the reincarnation event. */
+interface ResidualTraceScoringContext {
+    /** NHE body identifier the interaction was recorded against. */
+    carriedFromNheId: string;
+    /** ISO 8601 timestamp of the reincarnation that promoted these candidates. */
+    carriedAtReincarnation: string;
+    /** Index of the interaction in the input list, counted from the end (0 = most recent). */
+    positionFromEnd: number;
+    /** Total number of interactions being scored together (drives the recency normalisation). */
+    totalCount: number;
+}
+interface ResidualTraceCandidate {
+    /** Score in `[0, 1]`. Higher = stronger case for carry-over. */
+    score: number;
+    /** Materialised trace ready to be passed to `HimHandle.mint`. */
+    trace: ResidualTrace;
+    /** Decomposed score components — useful for audits and tuning. */
+    components: Readonly<{
+        notRefused: number;
+        promptSubstance: number;
+        responseSubstance: number;
+        questionProbe: number;
+        teleologicalKeyword: number;
+        recency: number;
+    }>;
+}
+interface ResidualTraceScorerOptions {
+    /**
+     * Override the keyword list used to detect teleologically-charged turns.
+     * Comparisons are case-insensitive substring matches over the user prompt
+     * concatenated with the response text.
+     */
+    teleologicalKeywords?: readonly string[];
+}
+/** Default keyword set — small, English, transparently editable. */
+declare const DEFAULT_TELEOLOGICAL_KEYWORDS: readonly string[];
+/**
+ * Pure, deterministic scorer for a single `InteractionRecord`.
+ *
+ * Returns the score, the materialised `ResidualTrace`, and the decomposed
+ * components so callers can audit *why* a turn was promoted (or not).
+ *
+ * The trace id is a fresh ULID minted at scoring time — by design, a single
+ * interaction can be scored multiple times across reincarnations and each
+ * carry-over event gets its own trace id (carry-over is a *new* observation,
+ * not a re-emission of the original turn).
+ */
+declare function scoreInteractionForCarryOver(interaction: InteractionRecord, ctx: ResidualTraceScoringContext, opts?: ResidualTraceScorerOptions): ResidualTraceCandidate;
+interface SelectResidualTracesOptions extends ResidualTraceScorerOptions {
+    carriedFromNheId: string;
+    /** ISO 8601 timestamp. Defaults to `new Date().toISOString()`. */
+    carriedAtReincarnation?: string;
+    /** Hard cap on how many traces transfer. Defaults to `RESIDUAL_TRACE_CAP` (64). */
+    cap?: number;
+}
+/**
+ * Batch helper: score every interaction, sort descending by score, take the
+ * top `cap` (default `RESIDUAL_TRACE_CAP = 64`), and return the materialised
+ * traces. The original `InteractionRecord` ordering does not affect the
+ * returned ordering — only the score does.
+ *
+ * Ties are broken by recency (more recent first), then by original index for
+ * total determinism. Returns an empty array on empty input.
+ */
+declare function selectResidualTraces(interactions: readonly InteractionRecord[], opts: SelectResidualTracesOptions): readonly ResidualTrace[];
+
+interface CreateHimOptions {
+    /**
+     * Explicit nonce for the Creator signature. Defaults to `Date.now()`, which is
+     * strictly increasing in practice and well below the seed nonce range used by MAIC.
+     */
+    nonce?: number;
+}
+/**
+ * createHim — one-call helper that bundles the three steps a user would
+ * otherwise need to coordinate manually:
+ *
+ *   1. sign the BirthSignature with the Creator's keyring
+ *   2. register the HIM in MAIC (snapshots axioms, emits him-register audit)
+ *   3. mint a HimHandle from the resulting record
+ *
+ * The keyring's public key must match MAIC's pinned `creatorPublicKey`, otherwise
+ * the registration step rejects.
+ */
+declare function createHim(maic: LocalMaic, keyring: CreatorKeyring, birthSignature: BirthSignature, opts?: CreateHimOptions): Promise<HimHandle>;
+
+/**
+ * Reincarnation lifecycle classifier (J-H3 — Entry 18 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * Re-exported from `@teleologyhi-sdk/maic` so consumers have a single
+ * canonical type. When supplied to `reincarnate(..., { lifecycle })`, the
+ * helper threads it to `maic.reincarnateHim(req, sig, { lifecycle })`,
+ * which emits the typed `reincarnate:${lifecycle}` audit kind instead of
+ * the generic `him-reincarnate`.
+ *
+ * The three canonical paths:
+ *
+ *   - `model-swap`         — the operator switched the underlying LLM
+ *                            adapter (e.g. Claude → Gemini). The
+ *                            HIM persists across the swap.
+ *   - `version-bump`       — the operator bumped the NHE major/minor
+ *                            without changing the underlying LLM family.
+ *   - `return-from-limbo`  — the HIM returns from a deep-coma limbo
+ *                            (Entry 24) carrying the `reunion` affect.
+ *
+ * The default classification when no `lifecycle` is provided is
+ * `model-swap` — matches the most common operator workflow.
+ */
+type ReincarnationLifecycle = ReincarnationLifecycle$1;
+interface ReincarnateOptions {
+    /** Explicit nonce for the Creator signature. Defaults to `Date.now()`. */
+    nonce?: number;
+    /**
+     * Lifecycle classification for the audit chain (J-H3). When omitted,
+     * defaults to `"model-swap"`. The helper threads the value to
+     * `maic.reincarnateHim(req, sig, { lifecycle })`, which emits the typed
+     * `reincarnate:${lifecycle}` audit kind in place of the generic
+     * `him-reincarnate` event. Compliance auditors and the persona-stability
+     * harness can therefore distinguish the three canonical paths
+     * (`model-swap | version-bump | return-from-limbo`) by `AuditEvent.kind`
+     * alone, with the same value also redundantly available as
+     * `data.lifecycle` for filtering convenience.
+     */
+    lifecycle?: ReincarnationLifecycle;
+    /**
+     * Recent interactions from the previous NHE body — typically the value of
+     * `Nhe.recentInteractionsBuffer` immediately before the swap. When
+     * provided, `reincarnate` invokes the residual-trace scorer
+     * (`selectResidualTraces`), keeps the top `RESIDUAL_TRACE_CAP` (64)
+     * scored candidates, and threads them into the new `HimHandle`. Omit to
+     * preserve the previous behaviour (empty residual traces — fresh slate).
+     */
+    priorInteractions?: readonly InteractionRecord[];
+    /**
+     * Override the residual-trace scorer cap or keyword list when supplying
+     * `priorInteractions`. `carriedFromNheId` and `carriedAtReincarnation`
+     * are derived from the reincarnation context and cannot be overridden
+     * here. Ignored when `priorInteractions` is omitted.
+     */
+    residualTraceOptions?: Omit<SelectResidualTracesOptions, "carriedFromNheId" | "carriedAtReincarnation">;
+}
+interface ReincarnateResult {
+    /** Updated HimRecord with the new body appended to `bodyHistory`. */
+    record: HimRecord;
+    /** Fresh HimHandle bound to the updated `bodyHistory`. */
+    handle: HimHandle;
+    /** Lifecycle path actually recorded for this reincarnation. */
+    lifecycle: ReincarnationLifecycle;
+}
+/**
+ * Reincarnate a HIM into a new NHE body (Entries 3 + 4 + 18).
+ *
+ *   1. Sign the `ReincarnationRequest` with the Creator's keyring.
+ *   2. Call `maic.reincarnateHim` — atomically closes the previous body and
+ *      appends the new one to `bodyHistory`.
+ *   3. Mint a fresh `HimHandle` reflecting the updated body history (the
+ *      caller will typically construct a new `Nhe` with this handle).
+ *
+ * The keyring's public key must match MAIC's pinned `creatorPublicKey`,
+ * otherwise the request rejects.
+ *
+ * The optional `lifecycle` parameter (J-H3, Entry 18) classifies the
+ * reincarnation into one of three canonical paths
+ * (`model-swap | version-bump | return-from-limbo`) and is returned in
+ * the `ReincarnateResult` for the caller's audit / metrics.
+ */
+declare function reincarnate(maic: LocalMaic, keyring: CreatorKeyring, req: ReincarnationRequest, opts?: ReincarnateOptions): Promise<ReincarnateResult>;
+
+/**
+ * Nickname acceptance protocol (J-H4 — Entry 18 of
+ * MAIC_HIM_NHE_INTERVIEW_LOG.md).
+ *
+ * A HIM has a Creator-signed canonical name (carried by
+ * `BirthSignatureWithIdentity.identity.name`). Users may propose nicknames
+ * during interaction. The HIM is NOT obligated to accept any nickname —
+ * but it is also not obligated to refuse outright. The Entry-18
+ * commitment is:
+ *
+ *   - The canonical name is immutable (only the Creator may change it).
+ *   - The nickname surface is editable in the identity layer but does NOT
+ *     break the natal-chart commitment (per `@teleologyhi-sdk/maic`'s
+ *     SIGNED_BIRTH_FIELDS, the identity layer is not signed).
+ *   - The HIM responds to a nickname attempt with one of three verdicts:
+ *       * `accept`   — the nickname is added to the identity layer and
+ *                      the HIM acknowledges it in subsequent turns.
+ *       * `refuse`   — the nickname is rejected and an explanation is
+ *                      returned. The audit kind `nickname-attempt` records
+ *                      the rejection with reason.
+ *       * `accept-with-reservation` — the nickname is added but flagged
+ *                      so the HIM can revisit it in a later self-decision
+ *                      snapshot (Entry 24 trigger).
+ *
+ * This module ships the pure decision function. The MAIC audit emission
+ * and identity-layer mutation are the consumer's responsibility (they
+ * cross the @teleologyhi-sdk/maic LocalMaic boundary and require Creator
+ * authorisation depending on the verdict).
+ *
+ * The function is deterministic given the inputs; no LLM call. The
+ * verdict is computed from explicit policy fields, not from semantic
+ * inference. This keeps the protocol auditable.
+ */
+/** A user-proposed nickname plus the metadata an auditor needs to replay the decision. */
+interface NicknameAttempt {
+    /** The candidate nickname (raw user input, trimmed by the caller). */
+    candidate: string;
+    /** The user surface that proposed it. */
+    proposedBy: "operator" | "end-user";
+    /** ISO 8601 timestamp of the proposal. */
+    proposedAt: string;
+}
+/**
+ * Policy fields the HIM consults when deciding. Operators tune these
+ * via the deployment's lawful-character profile or by overriding the
+ * default below.
+ */
+interface NicknamePolicy {
+    /** The canonical signed name. Used to detect "same-name" attempts. */
+    canonicalName: string;
+    /**
+     * Disallowed patterns (case-insensitive substrings). Matches force `refuse`.
+     * The default set rejects derogatory and degrading patterns; operators
+     * may extend it via the deployment's lawful-character profile.
+     */
+    forbiddenSubstrings?: readonly string[];
+    /**
+     * Minimum and maximum length the HIM will accept (inclusive).
+     * Defaults: min 2, max 32. Values outside force `refuse`.
+     */
+    minLength?: number;
+    maxLength?: number;
+    /**
+     * When `true`, an `end-user` proposal that survives the substring and
+     * length checks is downgraded to `accept-with-reservation` so the HIM
+     * can revisit it on the next self-decision snapshot. Operator
+     * proposals are not downgraded. Default: `true`.
+     */
+    reserveOnEndUser?: boolean;
+}
+type NicknameVerdict = {
+    decision: "accept";
+    canonicalName: string;
+    nickname: string;
+} | {
+    decision: "accept-with-reservation";
+    canonicalName: string;
+    nickname: string;
+    revisitOn: "next-self-decision-snapshot";
+} | {
+    decision: "refuse";
+    canonicalName: string;
+    nickname: string;
+    reason: string;
+};
+/**
+ * Evaluate a nickname attempt against the HIM's policy.
+ *
+ * Pure function. No I/O, no LLM call. The verdict is fully traceable
+ * from the inputs.
+ */
+declare function evaluateNicknameAttempt(attempt: NicknameAttempt, policy: NicknamePolicy): NicknameVerdict;
+
+/** Return `true` when the id matches the legacy slug shape. */
+declare function isLegacyHimId(id: string): boolean;
+/** Return `true` when the id is a valid UUIDv7. */
+declare function isUuidV7(id: string): boolean;
+/**
+ * Mint a fresh UUIDv7. Pure helper, no I/O beyond the crypto RNG.
+ *
+ * Layout (RFC 9562):
+ *   - bits 0..47   : Unix ms timestamp (big-endian)
+ *   - bits 48..51  : version = 0b0111 (7)
+ *   - bits 52..63  : random
+ *   - bits 64..65  : variant = 0b10
+ *   - bits 66..127 : random
+ */
+declare function mintUuidV7(now?: number): string;
+/** Result of migrating a legacy slug to a UUIDv7-anchored identity. */
+interface MigratedHimId {
+    /** The new canonical UUIDv7 id. */
+    uuid: string;
+    /** The legacy slug, preserved as a bridge alias for backward lookups. */
+    legacyAlias: string;
+    /** When the migration was performed. ISO 8601. */
+    migratedAt: string;
+}
+/**
+ * Migrate a legacy `him.foo.bar`-style id to a UUIDv7-anchored identity.
+ *
+ * Throws when the input is not a recognised legacy slug — callers that
+ * just want a fresh uuid should call `mintUuidV7()` directly.
+ *
+ * The returned `legacyAlias` MUST be preserved by the operator's HIM
+ * store so existing references (audit-log entries, third-party
+ * integrations, archived prompts) continue to resolve. The retention
+ * horizon for the alias is a Creator decision deferred to a future cut.
+ */
+declare function migrateLegacyHimId(legacy: string, now?: number): MigratedHimId;
+
+export { BirthSignatureBuilder, type CanonicalPrimaryArchetype, type CreateHimOptions, DEFAULT_TELEOLOGICAL_KEYWORDS, DISPOSITION_AXES, type DispositionAxis, type Embedder, HimHandle, LAWFUL_PROFILES, type LawfulCharacterProfile, type LawfulJurisdiction, type MigratedHimId, NheBodyRef, type NicknameAttempt, type NicknamePolicy, type NicknameVerdict, PRIMARY_ARCHETYPES, PersonaProjector, type PersonaProjectorConfig, type PersonaStabilityReport, type PersonaVector, type PhiPrimeInput, type PhiPrimeReport, type PrimaryArchetype, RESIDUAL_TRACE_CAP, type ReincarnateOptions, type ReincarnateResult, type ReincarnationLifecycle, type ResidualTrace, type ResidualTraceCandidate, type ResidualTraceScorerOptions, type ResidualTraceScoringContext, type SelectResidualTracesOptions, adapterSensitivity, computePhiPrime, cosineSimilarity, createHim, evaluateNicknameAttempt, evaluatePersonaStability, isCanonicalArchetype, isLegacyHimId, isUuidV7, migrateLegacyHimId, mintUuidV7, reincarnate, resolveLawfulProfile, scoreInteractionForCarryOver, selectResidualTraces, selfStability };