soulbridge 0.0.26 → 0.0.98

package/dist/packages/core/src/index.d.ts

@@ -11,16 +11,31 @@ export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT
 export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule, detectCorrection, isQuestion, } from './reflect.ts';
 export type { CorrectionLayer, CorrectionSignal, CorrectionVerdict } from './reflect.ts';
 export { rank, scoreMemory, tokenize, relevance, bm25, buildCorpusStats } from './scoring.ts';
+export { parseThreadLine } from './extract.ts';
+export { renderConsolidationPrompt, renderVerificationPrompt, renderRelationPrompt, renderRuleClassifyPrompt, renderProfileMergePrompt, renderExtractionPrompt, } from './prompts.ts';
+export type { ConsolidationPromptInput, VerificationPromptInput, RelationPromptInput, RuleClassifyPromptInput, ProfileMergePromptInput, ExtractionPromptInput, } from './prompts.ts';
+export { gateConclusion, conclusionSlots, normalizeStatement, parseConclusionDraft, parseVerificationDraft, parseRelationDraft, readVerification, parseProfileMerge, groupProfileCandidates, isDerivedProfileLine, PROFILE_DIMENSIONS, } from './consolidate.ts';
+export type { VerificationDraft, ConclusionRelation } from './consolidate.ts';
+export type { ProfileLine, ProfileCandidate, ProfileGroup } from './consolidate.ts';
+import type { ProfileLine } from './consolidate.ts';
+export { fires, parseRuleClassifications, parseTrigger, selectRules } from './rules.ts';
+export type { Rule, RuleTrigger, RuleClassification } from './rules.ts';
+export { planRetrieval } from './retrieval.ts';
+export type { RetrievalPlan, RetrievalPrimitive } from './retrieval.ts';
 export * from './affect/index.ts';
+export { escapeBlockText, escapeAttr } from './inject-text.ts';
 export { measureStyle } from './style/measure.ts';
 export type { StyleMetrics } from './style/measure.ts';
 export * from './storage/config.ts';
 export * from './storage/merge.ts';
 export * from './storage/steering.ts';
 export * from './storage/transcript.ts';
-import type { AffectSignal, ContextRequest, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, TurnPair, Visibility } from './types.ts';
+import type { AffectSignal, ContextRequest, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, CommitResult, Entity, ExtractDraft, ConclusionDraft, Fact, ThreadAttribution, TurnThread, FactDetail, FactSpec, Gap, GapSpec, SessionHandoff, TurnFindResult, SessionSummary, TurnPair, TurnStep, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
+import type { Rule } from './rules.ts';
+import type { RetrievalPlan } from './retrieval.ts';
+import type { ExtractionContext } from './extract.ts';
 export { gateDrafts } from './reflect.ts';
 export interface SoulOptions {
     store: SoulStore;
@@ -71,6 +86,12 @@ export declare class Soul {
      * Audit view: every non-deleted row, including superseded and expired ones.
      * Prompt builders use `context`, which filters both out.
      */
+    /**
+     * The recent holdings, as the shape hosts already consume.
+     *
+     * Reads facts: the legacy table is inert after the migration, and a list that kept
+     * reading it would look empty while the system clearly remembers things.
+     */
     list(limit?: number): Memory[];
     /** Tombstone one memory so it never reaches a prompt again. */
     forget(id: string): boolean;
@@ -86,6 +107,23 @@ export declare class Soul {
         rule?: string;
     }): string;
     corrections(limit?: number): Correction[];
+    /**
+     * Was this turn one the user corrected?
+     *
+     * A correction is the highest-signal moment a lesson has: being told you were
+     * wrong is the consequence the experience comes with (brief 0023, T1). The link
+     * is the user's own words — corrections do not carry a turn id, and inventing a
+     * time window would misattribute a nearby turn.
+     */
+    wasCorrectedTurn(turnId: string): boolean;
+    /**
+     * The experiences of one turn that were flagged as lessons, and nothing else.
+     *
+     * Promotion reads the flag, never the statement: whether a sentence is "about how
+     * to work" is the semantic call the extractor already made, and re-deriving it in
+     * code would be the guess ADR 0027 forbids.
+     */
+    promotionCandidates(turnId: string): Fact[];
     /**
      * Store one exchange (RFC 0007). Idempotent on `(sessionId, turn)`: a repeat is
      * ignored by the store, so this returns nothing — there is no id worth handing
@@ -98,24 +136,322 @@ export declare class Soul {
         assistantText: string;
         at?: number;
         metadata?: Record<string, unknown>;
-    }): void;
+        /**
+         * The real shape of the reply: reasoning / text / tool steps in order.
+         *
+         * Stored, never injected. Reasoning is a draft, so recall and prompts read
+         * `kind === 'text'` only; it is kept because "why did you say that" and
+         * consolidation both need it.
+         */
+        steps?: TurnStep[];
+    }): string;
+    /**
+     * One turn by id, for adapters that only kept the id (extraction queue,
+     * handoff). Returns null when the row is gone, so callers can drop the item
+     * instead of retrying forever.
+     */
+    turn(id: string): TurnPair | null;
     /** Recall exchanges, scored against `query` when it is non-empty. */
     recallTurnPairs(query: string, limit?: number): TurnPair[];
     countTurnPairs(): number;
-    /** Verb 3: on demand. */
+    /**
+     * Every turn that matches, not the best few: for "how many times" and "what
+     * did we decide overall" the count matters more than the ranking, and the
+     * model does the counting (ADR 0027). `truncated` tells the caller the answer
+     * would be incomplete.
+     */
+    /**
+     * Turn text → drafts.
+     *
+     * Extraction is the model's job (ADR 0029: Generative Agents, Mem0 and
+     * Graphiti all extract with an LLM and keep code for validation and storage).
+     * The rules are a floor, not a ceiling: they matter when no model is
+     * configured and they cross-check the answer when one is. A model answer with
+     * no usable draft falls back to the rules instead of losing the turn.
+     */
+    extract(text: string, options?: {
+        at?: number;
+        llm?: (prompt: string) => Promise<string> | string;
+        /** 'auto' (default) uses the model then falls back; 'rules' forces rules. */
+        mode?: 'auto' | 'rules';
+        /** What the model may see; defaults to the recent store state. */
+        context?: ExtractionContext;
+        /**
+         * My reply in the same turn. The unit of memory is the exchange (ADR 0035):
+         * without this half, "my promises" is a rule the model can never use.
+         */
+        assistantText?: string;
+    }): Promise<ExtractDraft>;
+    /** The slice of the store the extractor is allowed to know about. */
+    extractionContext(limit?: number, options?: {
+        turnNo?: number;
+        sessionId?: string;
+    }): ExtractionContext;
+    /**
+     * Put a turn into a thread.
+     *
+     * Default is continuity (ADR 0034): a named thread joins when it exists and is open;
+     * an unreadable answer, a hallucinated id, or no answer at all joins the previous
+     * turn's thread instead of opening a new one — fragmentation is what starves
+     * consolidation, and threads can be split later while a lost topic cannot.
+     */
+    applyThread(attribution: ThreadAttribution | undefined, spec: {
+        sessionId: string;
+        turnNo: number;
+        turnId: string;
+        at: number;
+        fallbackTopic?: string;
+        /** The thread the previous turn belonged to; the default when unsure. */
+        previousThreadId?: string;
+    }): {
+        threadId: string;
+        created: boolean;
+        topic: string;
+        joinReason: string;
+        topicUpdated: boolean;
+    };
+    private openThreadFor;
+    /**
+     * Drafts → database.
+     *
+     * The gate is a labeller, not a filter. A sentence that parses is kept: an
+     * undeclared entity in a slot is kept as text (no entity is created), an unknown
+     * holder falls back to the world layer, and only an unreadable statement or an
+     * exact duplicate is refused. Everything degraded or refused is reported, so the
+     * loss is visible instead of silent.
+     */
+    commitDrafts(draft: ExtractDraft, options?: {
+        turnId?: string;
+        at?: number;
+    }): CommitResult;
+    /** Remember a person/thing/place; calling again just refreshes "last mentioned". */
+    rememberEntity(name: string, type: Entity['type'], options?: {
+        aliases?: string[];
+        attrs?: Record<string, unknown>;
+        seenAt?: number;
+    }): Entity;
+    findEntities(name: string, limit?: number): Entity[];
+    /** Write one connection between things. */
+    recordFact(spec: Omit<FactSpec, 'soulId' | 'userId'>): Fact;
+    /**
+     * Store one conclusion if the deterministic gate accepts it.
+     *
+     * A conclusion is not a new kind of record: it is a fact whose type is 结论,
+     * held by the soul itself, with one `fact` slot per citation. That way recall,
+     * export and supersede keep working, and the evidence can be followed back to
+     * the observation that produced it.
+     */
+    recordConclusion(draft: ConclusionDraft, options: {
+        allowed: string[];
+        mergeInto?: string;
+    }): {
+        ok: boolean;
+        reason?: string;
+        fact?: Fact;
+        superseded?: string;
+        merged?: string;
+    };
+    /**
+     * The rules we hold (ADR 0033): facts whose type is 规则 and whose 触发 slot parses.
+     *
+     * A rule without a usable trigger is skipped, not injected — an always-on rule is
+     * wallpaper, and wallpaper is how a lesson gets ignored.
+     */
+    rules(): Rule[];
+    /**
+     * Apply a rule classification (ADR 0033): retag as 规则 and store its trigger.
+     *
+     * The trigger is what makes the rule injectable later; a rule without one would
+     * have to be always-on, which is exactly what this split exists to avoid.
+     */
+    markRule(factId: string, classification: {
+        trigger: string;
+        action?: string;
+    }): void;
+    /** Apply a profile classification: it is about the person, not a triggered rule. */
+    markProfile(factId: string, options?: {
+        dimension?: string;
+    }): void;
+    /**
+     * Park a lesson that could not be classified.
+     *
+     * Neither bucket is safe for it: as a rule it would fire every turn, and as a
+     * profile line it would put an imperative into the description of a person. It
+     * goes to 待修, which nothing injects, and shows up in a review count.
+     */
+    markUnclassified(factId: string): void;
+    /** The judgments about the person that are waiting to be merged. */
+    profileItems(limit?: number): Fact[];
+    /**
+     * Replace a pile of judgments with the merged ones.
+     *
+     * Each merged line becomes a 画像 fact citing its sources, and every source it
+     * covers is superseded — not deleted, so the audit trail survives the compression.
+     */
+    applyProfileMerge(lines: ProfileLine[]): Fact[];
+    /** The merged profile, strongest first — what is injected every turn. */
+    profile(limit?: number): Fact[];
+    /** Which primitive this question needs (0020).
+     *
+     * The subject is resolved against the entities we hold, so "上次和 a 吃饭" can
+     * never be answered with the last closed topic.
+     */
+    planRetrieval(text: string): RetrievalPlan;
+    /** The entity timeline: what is known about one person/thing, newest first. */
+    latestAbout(entityName: string, options?: {
+        predicate?: string;
+        query?: string;
+        limit?: number;
+    }): Fact[];
+    /** Mark facts as surfaced; retrieval practice slows their decay (0019). */
+    recordRecalls(factIds: string[], at?: number): void;
+    /**
+     * Close topics the conversation has moved past.
+     *
+     * Three signals, in order of strength: the host's archive list (the user said
+     * this session is done), turns elapsed inside the running session, and — only
+     * as a fallback — silence in another session.
+     */
+    closeIdleThreads(sessionId: string, options?: {
+        idleTurns?: number;
+        idleMs?: number;
+        archivedSessionIds?: string[];
+        at?: number;
+    }): Array<{
+        id: string;
+        reason: 'archived' | 'quiet-turns' | 'quiet-time';
+    }>;
+    /** The thread the previous turn belonged to, for the attribution candidate list. */
+    threadBefore(sessionId: string, turnNo: number): string | null;
+    /**
+     * Everything a closed thread needs for consolidation: the topic, the turns in
+     * order (as text), and the facts extracted from those turns.
+     *
+     * The turns are what makes this a chapter rather than a batch: A B A means the
+     * facts alone have lost the resume.
+     */
+    threadContext(threadId: string): {
+        thread: TurnThread;
+        turns: Array<{
+            turnNo: number;
+            userText: string;
+            assistantText: string;
+        }>;
+        facts: Fact[];
+    } | null;
+    /**
+     * What "where were we" means: the last topic that actually finished, its
+     * conclusion, and the last couple of turns.
+     *
+     * A session boundary is not a topic boundary, so this is keyed on the closed
+     * thread, not on the previous session.
+     */
+    lastClosedThread(): {
+        thread: TurnThread;
+        conclusion: Fact | null;
+        /** Both sides of the last turns (ADR 0035): "where were we" includes what I said. */
+        turns: Array<{
+            turnNo: number;
+            userText: string;
+            assistantText: string;
+        }>;
+    } | null;
+    /** The entities a set of facts mentions — the key a conclusion is recalled by. */
+    entitiesOfFacts(factIds: string[]): string[];
+    /**
+     * Conclusions worth comparing a new one against.
+     *
+     * Ordered by shared evidence first, then recency: two conclusions drawn from
+     * the same facts are the likeliest restatements, and the recency tail catches
+     * the ones whose evidence was reworded.
+     */
+    conclusionCandidates(evidence: string[], limit?: number): Array<{
+        id: string;
+        statement: string;
+        evidence: number;
+    }>;
+    /**
+     * Fold new evidence into a held conclusion.
+     *
+     * The statement is not rewritten: keeping it makes the merge auditable, and a
+     * richer statement is the model's job at the next natural revision, not this
+     * function's.
+     */
+    mergeEvidence(into: string, evidence: string[]): {
+        ok: boolean;
+        reason?: string;
+        added?: number;
+    };
+    /** Current conclusions, newest first. Superseded ones are history, not state. */
+    conclusions(limit?: number): Fact[];
+    /**
+     * The newest facts, newest first — the input batch for consolidation.
+     *
+     * Observations only: conclusions share the same table, and feeding a conclusion
+     * back as evidence would let the model cite its own guess.
+     */
+    recentFacts(limit?: number): Fact[];
+    /** How many observations exist; consolidation triggers on growth, not time. */
+    factTotal(): number;
+    /**
+     * Everything that happened to or around one entity — the "about her" path.
+     *
+     * `order: 'asc'` gives the earliest fact, which is how "when we first met"
+     * is answered without storing a special label: the model reads the timeline.
+     */
+    factsAbout(entityId: string, options?: {
+        since?: number;
+        until?: number;
+        limit?: number;
+        order?: 'asc' | 'desc';
+    }): Fact[];
+    /** A fact plus the conversation behind it: hook first, detail on demand. */
+    factDetail(factId: string): FactDetail | null;
+    /** Open questions, highest tension first. */
+    openGaps(limit?: number): Gap[];
+    recordGap(spec: Omit<GapSpec, 'soulId' | 'userId'>): Gap;
+    closeGap(id: string, closedByFactId?: string): void;
+    findTurns(text: string, options?: {
+        sessionId?: string;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): TurnFindResult;
+    /** Conversations, most recent first, derived from the recorded exchanges. */
+    sessions(limit?: number): SessionSummary[];
+    /**
+     * What a new session inherits from the previous conversation.
+     *
+     * Measured: naive first/last picked "ok" and "停" — boundaries are not the
+     * same as signals. So the topic is the longest user message of that session
+     * (shortest messages carry no topic), and the tail is the last few exchanges
+     * whose user message has substance.
+     */
+    handoff(currentSessionId: string, tail?: number): SessionHandoff | null;
+    /**
+     * Verb 3: on demand.
+     *
+     * Reads facts, not the legacy `memories` table: after the migration that table is
+     * inert, and a recall that still read it would stay empty forever.
+     */
     recall(query: string, limit?: number): ScoredMemory[];
     /** Pure analysis, no storage. Async because the analyzer may call a model. */
     analyze(text: string): Promise<AffectSignal>;
     /**
-     * Verb 2: after each turn.
+     * Verb 2: after each turn. Affect and emotion only.
      *
-     * The analyzer may be async (a model); any failure degrades to the lexicon
-     * analyzer. Emotion is computed from the turn only — never from affect.
+     * Memory writing moved to `extract()` + `commitDrafts()` (facts), which is the one
+     * representation the rest of the system reads. This method used to run a second
+     * model pass (`llmExtractTurn`) behind a second gate (`gateDrafts`) into the legacy
+     * `memories` table — two prompts, two gates, two model calls for the same message.
      */
     observe(turn: Turn): Promise<ObserveResult>;
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.
-     * Same write path, no extraction heuristics.
+     *
+     * Writes a fact, like every other write path. This used to be a row in the legacy
+     * `memories` table, which meant "remember this" produced something the rest of the
+     * system (anchors, recall, conclusions) had to be told about separately.
      */
     remember(content: string, options?: {
         type?: MemoryType;
@@ -123,9 +459,12 @@ export declare class Soul {
         visibility?: Visibility;
     }): string;
     /**
-     * Explicit write requested by a host or its model (RFC 0005). Unlike
-     * `remember`, it passes the same gates as `observe` and dedupes by content,
-     * so a tool cannot bypass shape/semantics or flood duplicates.
+     * Explicit write requested by a host or its model (RFC 0005).
+     *
+     * Writes a fact and keeps the old dedupe contract: exact duplicate returns the
+     * existing id, and a paraphrase inside the dedupe window is treated as the same
+     * statement. Shape checks are the statement checks (non-empty, short enough);
+     * the old `gateDrafts` layer existed only to protect the retired table.
      */
     rememberExplicit(input: {
         content: string;
@@ -137,6 +476,19 @@ export declare class Soul {
         duplicate?: boolean;
         reason?: string;
     };
+    /**
+     * One-off: move the legacy `memories` rows into facts (ADR 0032), then retire them.
+     *
+     * The old rows are the only description of the soul's own lessons that exists, so
+     * they are copied — never rewritten — and marked superseded pointing at the new
+     * fact. Re-running is safe: a statement that already has a fact is linked, not
+     * copied again.
+     */
+    migrateLegacyMemories(): {
+        migrated: number;
+        linked: number;
+        skipped: number;
+    };
     /** Verb 4: session end. */
     reflect(turns: Turn[], options?: {
         updateEmotion?: boolean;