soulbridge 0.0.26 → 0.0.98

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

@@ -1,3 +1,10 @@
+/**
+ * Reflection: turn a finished session into durable memory + an emotion update.
+ *
+ * `core` never calls a model itself. If the caller passes an `LlmFn`, richer
+ * extraction is possible later; today the rule path is the default, which keeps
+ * the whole loop runnable offline.
+ */
 import type { DraftRejection, Emotion, LlmFn, MemoryType, ReflectResult, Turn } from './types.ts';
 import type { SoulStore } from './store.ts';
 interface Draft {

package/dist/packages/core/src/reflect.js

@@ -1,12 +1,13 @@
-/**
- * Reflection: turn a finished session into durable memory + an emotion update.
- *
- * `core` never calls a model itself. If the caller passes an `LlmFn`, richer
- * extraction is possible later; today the rule path is the default, which keeps
- * the whole loop runnable offline.
- */
-import { randomUUID } from 'node:crypto';
-import { tokenize } from './scoring.js';
+/** The fact type a legacy MemoryType maps to; one vocabulary at rest (type_name). */
+const MEMORY_TYPE_TO_FACT = {
+    semantic: '事实',
+    episodic: '事件',
+    strategy: '教训',
+    cognition: '原则',
+    relationship: '关系',
+    trait: '性格',
+    fact: '事实',
+};
 /**
  * A standing instruction needs both halves: when it applies, and what it asks
  * for. A bare "每次" is usually a complaint ("每次都不能用"), so the trigger
@@ -258,30 +259,27 @@ export async function reflect(store, options) {
     else {
         drafts.push(...ruleExtract(options.turns));
     }
-    const existing = store.query({ soulId: options.soulId, userId: options.userId });
-    const seen = new Set(existing.map((m) => m.content));
+    // One representation: a reflected draft becomes a fact, not a row in the retired
+    // `memories` table. Dedupe is by statement against the facts already held, because
+    // the same sentence can arrive through extraction, a tool, or this verb.
+    const existing = store.facts({ soulId: options.soulId, userId: options.userId, limit: 1000 });
+    const seen = new Set(existing.map((fact) => fact.statement.trim()));
     const { accepted, rejected } = gateDrafts(drafts);
     let written = 0;
     for (const draft of accepted) {
-        if (seen.has(draft.content))
+        const statement = draft.content.trim();
+        if (seen.has(statement))
             continue;
-        seen.add(draft.content);
-        const memory = {
-            id: `mem_${randomUUID().slice(0, 8)}`,
+        seen.add(statement);
+        store.putFact({
             soulId: options.soulId,
             userId: options.userId,
-            type: draft.type,
-            content: draft.content,
-            importance: draft.importance,
-            vividness: 0.8,
-            recallCount: 0,
-            status: 'active',
-            visibility: draft.type === 'relationship' ? 'private' : 'private',
-            keywords: tokenize(draft.content),
-            createdAt: now,
-            validFrom: now,
-        };
-        store.put(memory);
+            statement,
+            typeName: MEMORY_TYPE_TO_FACT[draft.type] ?? '事实',
+            holder: 'self',
+            source: 'told',
+            confidence: Math.min(1, Math.max(0, draft.importance / 10)),
+        });
         written += 1;
     }
     let emotion = store.emotion(options.soulId, options.userId);

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

@@ -0,0 +1,39 @@
+/**
+ * Which retrieval primitive a question needs (0020).
+ *
+ * The mistake this file exists to prevent: treating "上次" as a retrieval method.
+ * "上次和 a 吃饭" and "上次和 c 吃饭" are different questions with the same words
+ * around them — the subject decides what is fetched, and "上次" only says to order
+ * it newest-first. So the router looks for a subject first, and falls back to
+ * conversation continuity, then to a time window, then to plain relevance.
+ *
+ * Rules, not a model: a wrong guess here degrades to relevance search, and never
+ * to "answer about somebody else", which is the one failure worse than silence.
+ */
+export type RetrievalPrimitive = 'entity' | 'continuity' | 'time' | 'related';
+export interface RetrievalPlan {
+    primitive: RetrievalPrimitive;
+    /** The entity the question is about, when one is named. */
+    subject?: string;
+    reason: string;
+}
+/**
+ * A named subject the store may not know yet.
+ *
+ * An unknown name is still a subject: "上次和 c 吃饭" must come back empty, not be
+ * treated as "where were we last time" and answered with somebody else's topic.
+ * The name stops at the first predicate character, so 小林吃饭 yields 小林.
+ *
+ * Rejected on purpose: a fragment with no predicate after it ("和数据保持一致" →
+ * 数据保持), and any fragment containing a function word ("上次一样", "他一起").
+ * Guessing a subject is worse than falling through to relevance search.
+ */
+export declare function subjectCandidate(text: string): string | undefined;
+/**
+ * Pick a primitive from the question and the entities we know.
+ *
+ * Longest name first: 小林 must win over 小, and 核桃暗号 over 核桃. A name that is
+ * merely a substring of another word is a false positive the caller cannot
+ * recover from, so this stays deliberately literal.
+ */
+export declare function planRetrieval(text: string, entityNames: string[]): RetrievalPlan;

package/dist/packages/core/src/retrieval.js

@@ -0,0 +1,105 @@
+/**
+ * Which retrieval primitive a question needs (0020).
+ *
+ * The mistake this file exists to prevent: treating "上次" as a retrieval method.
+ * "上次和 a 吃饭" and "上次和 c 吃饭" are different questions with the same words
+ * around them — the subject decides what is fetched, and "上次" only says to order
+ * it newest-first. So the router looks for a subject first, and falls back to
+ * conversation continuity, then to a time window, then to plain relevance.
+ *
+ * Rules, not a model: a wrong guess here degrades to relevance search, and never
+ * to "answer about somebody else", which is the one failure worse than silence.
+ */
+const CONTINUITY = /上次|刚才|上回|接着|继续|说到哪|聊到哪/;
+const TIME_CUE = /上周|上星期|昨天|前天|今天|那天|当时|上个月|月初|去年|\d{1,2}月\d{1,2}[日号]/;
+/**
+ * Pick a primitive from the question and the entities we know.
+ *
+ * Longest name first: 小林 must win over 小, and 核桃暗号 over 核桃. A name that is
+ * merely a substring of another word is a false positive the caller cannot
+ * recover from, so this stays deliberately literal.
+ */
+/** "和/跟/与/同 X" — how a companion question names the other person. */
+const WITH_SUBJECT = /(?:和|跟|与|同)\s*([A-Za-z0-9][A-Za-z0-9_]*|[\u4e00-\u9fa5]{1,4})/;
+/** The name ends where the predicate begins. */
+const PREDICATE_START = /[说聊吃见去在是了的吧呢啊吗过还就都也等到]/;
+/** Pronouns are not lookup keys: 我 is the user, 你 is the assistant. */
+const NOT_A_NAME = new Set(['我', '你', '您', '他', '她', '它', '我们', '你们', '他们', '她们']);
+/** Function words inside a candidate: "上次一样" and "他一起" are phrases, not names. */
+const FUNCTION_WORD = /[这那次样起一我你他她它们的]/;
+/** Escape a name before it goes into a RegExp. */
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Does the message actually mention this known entity?
+ *
+ * A Latin name must stand on its own: the entity "a" is a substring of "package",
+ * so `includes` routed ordinary technical messages to `<about name="a">` and
+ * suppressed the related-conversation block on most turns. A one-character CJK name
+ * is noise (小 is in 小林), but a one-character Latin name is fine when it is a
+ * whitespace-delimited token — "上次和 a 吃饭" is a real subject.
+ */
+function mentions(question, name) {
+    if (/^[A-Za-z0-9_]+$/.test(name)) {
+        return new RegExp(`(^|[^A-Za-z0-9_])${escapeRegex(name)}([^A-Za-z0-9_]|$)`, 'i').test(question);
+    }
+    return [...name].length >= 2 && question.includes(name);
+}
+/**
+ * A named subject the store may not know yet.
+ *
+ * An unknown name is still a subject: "上次和 c 吃饭" must come back empty, not be
+ * treated as "where were we last time" and answered with somebody else's topic.
+ * The name stops at the first predicate character, so 小林吃饭 yields 小林.
+ *
+ * Rejected on purpose: a fragment with no predicate after it ("和数据保持一致" →
+ * 数据保持), and any fragment containing a function word ("上次一样", "他一起").
+ * Guessing a subject is worse than falling through to relevance search.
+ */
+export function subjectCandidate(text) {
+    const match = WITH_SUBJECT.exec(String(text ?? ''));
+    const raw = match?.[1]?.trim();
+    if (!raw)
+        return undefined;
+    // A Latin name is delimited by whitespace ("上次和 c 吃饭"), so it needs no
+    // predicate boundary; a CJK run does ("小林吃饭" must stop at 吃).
+    let name;
+    if (/^[A-Za-z0-9_]+$/.test(raw)) {
+        name = raw;
+    }
+    else {
+        const cut = raw.search(PREDICATE_START);
+        // No predicate boundary means the conjunction was not naming a person.
+        if (cut <= 0)
+            return undefined;
+        name = raw.slice(0, cut).trim();
+    }
+    if (!name || NOT_A_NAME.has(name) || FUNCTION_WORD.test(name))
+        return undefined;
+    return name;
+}
+/**
+ * Pick a primitive from the question and the entities we know.
+ *
+ * Longest name first: 小林 must win over 小, and 核桃暗号 over 核桃. A name that is
+ * merely a substring of another word is a false positive the caller cannot
+ * recover from, so this stays deliberately literal.
+ */
+export function planRetrieval(text, entityNames) {
+    const question = String(text ?? '');
+    const names = [...new Set(entityNames.filter(Boolean))].sort((a, b) => [...b].length - [...a].length);
+    const subject = names.find((name) => mentions(question, name));
+    if (subject)
+        return { primitive: 'entity', subject, reason: `mentions "${subject}"` };
+    // An unknown name is an unknown subject, not an absent one. Looking it up
+    // returns nothing, which is the honest answer.
+    const unnamed = subjectCandidate(question);
+    if (unnamed)
+        return { primitive: 'entity', subject: unnamed, reason: `unknown subject "${unnamed}"` };
+    if (CONTINUITY.test(question))
+        return { primitive: 'continuity', reason: 'continuity cue, no subject' };
+    if (TIME_CUE.test(question))
+        return { primitive: 'time', reason: 'time cue, no subject' };
+    return { primitive: 'related', reason: 'no subject, no cue' };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * The two decisions every reader used to make for itself, in one place.
+ *
+ * During the rebuild the `facts` table changes shape in a way that cannot be flipped at once:
+ *   - `role` is a new closed field; old rows have none, and their role lives in the Chinese
+ *     `type_name` label;
+ *   - `status` moves from none/superseded to raw/candidate/active/retracted, but old rows keep
+ *     their old values until the migration runs.
+ *
+ * If each call site guessed, they would guess differently — the exact failure mode that made
+ * "规则/画像/待修" both a type and a state. So: one decoder, used everywhere, written to accept
+ * both vocabularies until the fallback is deleted in the contract step.
+ */
+import type { Fact } from './types.ts';
+import type { FactRole } from './types.ts';
+export declare function roleOf(fact: Pick<Fact, 'role' | 'typeName'>): FactRole;
+export declare function isActive(fact: Pick<Fact, 'status'>): boolean;
+export declare function isRetracted(fact: Pick<Fact, 'status'>): boolean;

package/dist/packages/core/src/roles.js

@@ -0,0 +1,17 @@
+import { FACT_STATE_MIGRATION, LEGACY_ROLE_BY_TYPE } from './config/domains.js';
+import { FACT_STATUS } from './config/status.js';
+const LEGACY_ROLES = LEGACY_ROLE_BY_TYPE;
+/** Old and new status values that mean "this is in use". */
+const ACTIVE_STATES = new Set(['active', 'none', 'kept', 'open']);
+export function roleOf(fact) {
+    if (fact.role)
+        return fact.role;
+    return LEGACY_ROLES[fact.typeName ?? ''] ?? 'observation';
+}
+export function isActive(fact) {
+    return ACTIVE_STATES.has(String(fact.status));
+}
+export function isRetracted(fact) {
+    const mapped = FACT_STATE_MIGRATION[String(fact.status)] ?? String(fact.status);
+    return mapped === 'retracted' || String(fact.status) === FACT_STATUS.superseded;
+}

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

@@ -0,0 +1,69 @@
+export interface RuleTrigger {
+    /** Substring keywords; any one is enough. */
+    any?: string[];
+    /** Case-insensitive regex source; any match is enough. */
+    regex?: string;
+    /** A counter flag maintained by the adapter, e.g. `long-session`. */
+    state?: string;
+}
+export interface Rule {
+    id: string;
+    statement: string;
+    trigger: RuleTrigger;
+    scope?: string;
+    confidence?: number;
+}
+/**
+ * Parse the stored trigger. Malformed JSON means "no trigger", not "always":
+ * a rule that fires on everything is worse than a rule that never fires.
+ */
+export declare function parseTrigger(raw: string): RuleTrigger | null;
+/**
+ * Does this rule apply to the current message?
+ *
+ * With both content and state conditions, both must hold: a rule that mentions
+ * both is meant for a narrower situation, and over-firing is the failure that
+ * pushes a rule into the wallpaper class.
+ */
+export declare function fires(rule: Rule, text: string, state?: Record<string, boolean>): boolean;
+/** The rules to inject: only the ones that fire, strongest first, capped. */
+export declare function selectRules(rules: Rule[], text: string, state?: Record<string, boolean>, limit?: number): Rule[];
+export interface RuleClassification {
+    id: string;
+    /**
+     * `pending` is a third bucket on purpose: a lesson that is neither clearly a
+     * triggered rule nor clearly a statement about the person must not be forced into
+     * either. As a rule it would become wallpaper; as a profile line it would put an
+     * imperative into the description of a person.
+     */
+    kind: 'rule' | 'profile' | 'pending';
+    /** Trigger JSON built by this parser, never authored by the model. */
+    trigger?: string;
+    /** One sentence of what to do, when this is a rule. */
+    action?: string;
+    /**
+     * Which lens the person statement belongs to, when this is a profile item.
+     *
+     * Absent when the model did not say or named something that is not a dimension:
+     * the merge step refuses to merge unlabelled items rather than guess, so a wrong
+     * dimension here would silently file the judgment under the wrong lens.
+     */
+    dimension?: string;
+    /** Why it could not be classified, when pending. */
+    reason?: string;
+}
+/**
+ * Parse the classifier's answer. Line-table, not JSON — the model fills fields and
+ * the code assembles the trigger, because we already know model-authored JSON is a
+ * hope (the extractor was moved off it for the same reason).
+ *
+ *   规则: fc_x | 关键词=json,package.json | 动作=用 edit 工具改 JSON
+ *   规则: fc_y | 正则=\.json\b
+ *   规则: fc_z | 状态=long-session
+ *   画像: fc_p
+ *   待修: fc_q | 原因=不知道什么时候该用
+ *
+ * A 规则 with no usable condition becomes 待修, not 画像: the two failures have
+ * different consequences and only one of them pollutes the profile.
+ */
+export declare function parseRuleClassifications(raw: string): RuleClassification[];

package/dist/packages/core/src/rules.js

@@ -0,0 +1,152 @@
+/**
+ * Rule matching (ADR 0033).
+ *
+ * A rule is not a memory: it constrains behaviour, so it should appear when its
+ * situation applies and stay out of the way otherwise. Always-on rules become
+ * wallpaper, which is how a lesson turns into a paragraph the model skips.
+ *
+ * The whole thing is a pure function over (rule, user message, session state) so
+ * it can be tested without a database or a model call.
+ */
+import { PROFILE_DIMENSIONS } from './consolidate.js';
+/**
+ * Parse the stored trigger. Malformed JSON means "no trigger", not "always":
+ * a rule that fires on everything is worse than a rule that never fires.
+ */
+export function parseTrigger(raw) {
+    try {
+        const parsed = JSON.parse(String(raw ?? ''));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const out = {};
+        if (Array.isArray(parsed.any)) {
+            const any = parsed.any.map((item) => String(item ?? '').trim()).filter(Boolean);
+            if (any.length > 0)
+                out.any = any;
+        }
+        if (typeof parsed.regex === 'string' && parsed.regex.trim())
+            out.regex = parsed.regex.trim();
+        if (typeof parsed.state === 'string' && parsed.state.trim())
+            out.state = parsed.state.trim();
+        return out.any || out.regex || out.state ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Content conditions are OR-ed; a state condition must also hold when present. */
+function contentMatches(trigger, text) {
+    if (!trigger.any && !trigger.regex)
+        return false;
+    const haystack = text.toLowerCase();
+    if (trigger.any?.some((keyword) => haystack.includes(keyword.toLowerCase())))
+        return true;
+    if (trigger.regex) {
+        try {
+            if (new RegExp(trigger.regex, 'i').test(text))
+                return true;
+        }
+        catch {
+            // A broken regex must not throw on every turn; it simply never matches.
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Does this rule apply to the current message?
+ *
+ * With both content and state conditions, both must hold: a rule that mentions
+ * both is meant for a narrower situation, and over-firing is the failure that
+ * pushes a rule into the wallpaper class.
+ */
+export function fires(rule, text, state = {}) {
+    const trigger = rule.trigger ?? {};
+    const hasContent = Boolean(trigger.any || trigger.regex);
+    const hasState = Boolean(trigger.state);
+    if (!hasContent && !hasState)
+        return false; // no trigger = never fires
+    if (hasContent && !contentMatches(trigger, String(text ?? '')))
+        return false;
+    if (hasState && !state[trigger.state])
+        return false;
+    return true;
+}
+/** The rules to inject: only the ones that fire, strongest first, capped. */
+export function selectRules(rules, text, state = {}, limit = 5) {
+    return rules
+        .filter((rule) => fires(rule, text, state))
+        .sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))
+        .slice(0, Math.max(0, limit));
+}
+const CLASSIFIED = /^(规则|画像|待修)\s*[:：]\s*(.+)$/;
+const KEY_FIELD = /^(关键词|正则|状态|动作|原因|维度)\s*[=＝]\s*(.*)$/;
+/**
+ * Parse the classifier's answer. Line-table, not JSON — the model fills fields and
+ * the code assembles the trigger, because we already know model-authored JSON is a
+ * hope (the extractor was moved off it for the same reason).
+ *
+ *   规则: fc_x | 关键词=json,package.json | 动作=用 edit 工具改 JSON
+ *   规则: fc_y | 正则=\.json\b
+ *   规则: fc_z | 状态=long-session
+ *   画像: fc_p
+ *   待修: fc_q | 原因=不知道什么时候该用
+ *
+ * A 规则 with no usable condition becomes 待修, not 画像: the two failures have
+ * different consequences and only one of them pollutes the profile.
+ */
+export function parseRuleClassifications(raw) {
+    const out = [];
+    for (const line of String(raw ?? '').split(/\r?\n/)) {
+        const match = CLASSIFIED.exec(line.trim());
+        if (!match)
+            continue;
+        const parts = match[2].split('|').map((part) => part.trim());
+        const id = parts[0];
+        if (!id || !/^fc_/.test(id))
+            continue;
+        const kindLabel = match[1];
+        const fields = new Map();
+        for (const part of parts.slice(1)) {
+            const field = KEY_FIELD.exec(part);
+            if (field)
+                fields.set(field[1], field[2].trim());
+        }
+        if (kindLabel === '画像') {
+            const dimension = fields.get('维度');
+            // A dimension the merge step does not know is not a dimension; keeping it out
+            // leaves the item unlabelled, which is visible, instead of mislabelled.
+            const known = dimension && PROFILE_DIMENSIONS.includes(dimension);
+            out.push({ id, kind: 'profile', ...(known ? { dimension } : {}) });
+            continue;
+        }
+        if (kindLabel === '待修') {
+            out.push({ id, kind: 'pending', reason: fields.get('原因') });
+            continue;
+        }
+        const keywords = (fields.get('关键词') ?? '')
+            .split(/[,，、;；\s]+/)
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const regex = fields.get('正则');
+        const state = fields.get('状态');
+        const trigger = {};
+        if (keywords.length > 0)
+            trigger.any = keywords;
+        if (regex)
+            trigger.regex = regex;
+        if (state)
+            trigger.state = state;
+        if (!trigger.any && !trigger.regex && !trigger.state) {
+            out.push({ id, kind: 'pending', reason: '规则缺少触发条件' });
+            continue;
+        }
+        out.push({
+            id,
+            kind: 'rule',
+            trigger: JSON.stringify(trigger),
+            action: fields.get('动作') || undefined,
+        });
+    }
+    return out;
+}

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

@@ -1,19 +1,40 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { SoulStore } from './store.ts';
-export declare const SCHEMA_VERSION = 4;
+export declare const SCHEMA_VERSION = 9;
 export declare const AFFECT_RETENTION_MS: number;
 export declare class DbNewerThanBinaryError extends Error {
     readonly code = "DB_NEWER_THAN_BINARY";
     readonly dbVersion: number;
     constructor(dbVersion: number);
 }
+/**
+ * v3/v4 → v5: turns become the unit of memory (briefs/0014). Existing exchanges
+ * are copied across as turns with a single text step, so nothing is lost; the
+ * old table stays as a read-only legacy copy.
+ */
+/** v6 → v7: turn threads (a topic's turns need not be adjacent) plus turns.thread_id. */
+export declare function upgradeToV9(db: DatabaseSync): void;
+export declare function upgradeToV8(db: DatabaseSync): void;
+export declare function upgradeToV7(db: DatabaseSync): void;
+export declare function upgradeToV5(db: DatabaseSync): void;
 /**
  * Copy the database aside before a schema upgrade.
  *
- * In WAL mode the most recent commits can live in the `-wal` sidecar, so a copy
- * of the main file alone can be missing data exactly when it matters. Checkpoint
- * first (TRUNCATE moves the WAL back into the main file and empties it), then
- * copy. Exported for the upgrade test.
+ * The backup is the only way back from a bad migration, so it has to be *valid*,
+ * not merely present. Two failures were possible before: a plain file copy after
+ * `wal_checkpoint(TRUNCATE)` dropped the newest commits when another connection
+ * pinned an old snapshot (the checkpoint returns busy and only partially flushes,
+ * and that return value was ignored), and an existing backup file was trusted
+ * forever even if it was the broken one from an earlier attempt.
+ *
+ * `VACUUM INTO` reads through the WAL and writes a consistent snapshot regardless
+ * of other readers, so it is the primary path; a checkpoint+copy remains as the
+ * fallback, and whatever it produces is opened and integrity-checked. A copy that
+ * fails its own check is moved aside (kept for forensics) and the upgrade refuses
+ * to run — a corrupt backup is worse than none, because it is the one thing we
+ * would trust when everything else failed.
+ *
+ * Exported for the upgrade test.
  */
 export declare function backupBeforeUpgrade(db: DatabaseSync, file: string, from: number): void;
 export declare function openSqlite(file: string): SoulStore;