soulbridge 0.0.12 → 0.0.14

package/README.md

@@ -114,6 +114,7 @@ SQLite（默认） / Postgres（可选）
 | [适配器索引](adapters/README.md) | 各宿主适配器与接入契约 |
 | [quality](docs/quality.md) | 质量模型、九条门禁、五条评审清单 |
 | [references](docs/references.md) | 外部资料的去留与过期判断 |
+| [roadmap](docs/roadmap.md) | 下一步做什么、借鉴了什么、明确不做什么 |
 | [runbook](docs/runbook.md) | 发版流程、维护操作、已知待办 |
 
 **规则**：架构级改动必须先有 RFC 或 ADR；聊天里达成的不算决定。

package/dist/packages/cli/src/cli.js

@@ -324,6 +324,22 @@ async function main() {
             out({ ok: soul.forget(id), id });
             return;
         }
+        case 'corrections': {
+            const { soul } = open(flags);
+            const rows = soul.corrections(flags.limit ? Number(flags.limit) : 10);
+            if (rows.length === 0) {
+                process.stdout.write('no corrections recorded yet\n');
+                return;
+            }
+            for (const row of rows) {
+                const when = new Date(row.at).toISOString().slice(0, 19).replace('T', ' ');
+                process.stdout.write(`${when}  [${row.rule ?? '-'}]\n`);
+                process.stdout.write(`  用户: ${row.userText}\n`);
+                if (row.assistantText)
+                    process.stdout.write(`  当时: ${row.assistantText}\n`);
+            }
+            return;
+        }
         case 'status': {
             const config = ensureConfig();
             const dbPath = resolveDbPath(flags.db);
@@ -393,6 +409,7 @@ async function main() {
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',
                 '  list [--limit N]                看它记住了什么',
+                '  corrections [--limit N]         看被纠正过的证据',
                 '  forget <id>                     忘掉一条记忆（墓碑）',
                 '  status                          一眼看它是否在工作',
                 '  stats                           看原始状态（JSON）',

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

@@ -8,7 +8,7 @@ export * from './types.ts';
 export type { SoulStore } from './store.ts';
 export { openSqlite, SCHEMA_VERSION, AFFECT_RETENTION_MS, DbNewerThanBinaryError } from './sqlite.ts';
 export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT_WINDOW_MS, } from './context.ts';
-export { reflect, ruleExtract, nextEmotion } from './reflect.ts';
+export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule } from './reflect.ts';
 export { rank, scoreMemory, tokenize, relevance } from './scoring.ts';
 export * from './affect/index.ts';
 export { measureStyle } from './style/measure.ts';
@@ -17,7 +17,7 @@ export * from './storage/config.ts';
 export * from './storage/merge.ts';
 export * from './storage/steering.ts';
 export * from './storage/transcript.ts';
-import type { AffectSignal, ContextRequest, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, Visibility } from './types.ts';
+import type { AffectSignal, ContextRequest, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
 export interface SoulOptions {
@@ -56,6 +56,16 @@ export declare class Soul {
     list(limit?: number): Memory[];
     /** Tombstone one memory so it never reaches a prompt again. */
     forget(id: string): boolean;
+    /**
+     * Record a user correction as evidence (RFC 0003 phase A). Nothing here
+     * reaches a prompt; distillation to a strategy is a later phase.
+     */
+    recordCorrection(input: {
+        userText: string;
+        assistantText?: string;
+        rule?: string;
+    }): string;
+    corrections(limit?: number): Correction[];
     /** Verb 3: on demand. */
     recall(query: string, limit?: number): ScoredMemory[];
     /** Pure analysis, no storage. Async because the analyzer may call a model. */

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

@@ -7,7 +7,7 @@
 export * from './types.js';
 export { openSqlite, SCHEMA_VERSION, AFFECT_RETENTION_MS, DbNewerThanBinaryError } from './sqlite.js';
 export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT_WINDOW_MS, } from './context.js';
-export { reflect, ruleExtract, nextEmotion } from './reflect.js';
+export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule } from './reflect.js';
 export { rank, scoreMemory, tokenize, relevance } from './scoring.js';
 export * from './affect/index.js';
 export { measureStyle } from './style/measure.js';
@@ -19,7 +19,7 @@ import { buildContext } from './context.js';
 import { reflect, ruleExtract, nextEmotion } from './reflect.js';
 import { rank, tokenize } from './scoring.js';
 import { analyzeAffect, emptyAffect, lexiconAnalyzer } from './affect/analyze.js';
-import { llmExtractTurn } from './reflect.js';
+import { gateDrafts, llmExtractTurn } from './reflect.js';
 export class Soul {
     store;
     soulId;
@@ -67,6 +67,28 @@ export class Soul {
     forget(id) {
         return this.store.forget(id);
     }
+    /**
+     * Record a user correction as evidence (RFC 0003 phase A). Nothing here
+     * reaches a prompt; distillation to a strategy is a later phase.
+     */
+    recordCorrection(input) {
+        const now = Date.now();
+        const id = `cor_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+        this.store.saveCorrection({
+            id,
+            soulId: this.soulId,
+            userId: this.userId,
+            at: now,
+            userText: input.userText,
+            assistantText: input.assistantText,
+            rule: input.rule,
+            deviceId: this.deviceId,
+        });
+        return id;
+    }
+    corrections(limit = 20) {
+        return this.store.recentCorrections(this.soulId, this.userId, limit);
+    }
     /** Verb 3: on demand. */
     recall(query, limit = 5) {
         const memories = this.store.query({ soulId: this.soulId, userId: this.userId });
@@ -107,10 +129,13 @@ export class Soul {
                 }
             }
         }
+        // Deterministic write gates: shape -> semantics -> per-turn budget. Whatever
+        // they refuse is reported, so written: 0 always has a reason.
+        const gated = gateDrafts(drafts);
         // observe runs every turn; repeating a sentence must not create a second row.
         const seen = new Set(this.store.query({ soulId: this.soulId, userId: this.userId, limit: 10_000 }).map((m) => m.content.trim()));
         let written = 0;
-        for (const draft of drafts) {
+        for (const draft of gated.accepted) {
             if (seen.has(draft.content.trim()))
                 continue;
             seen.add(draft.content.trim());
@@ -142,7 +167,14 @@ export class Soul {
         }
         const emotion = nextEmotion(this.store.emotion(this.soulId, this.userId), [turn]);
         this.store.saveEmotion(this.soulId, this.userId, emotion, now);
-        return { written, emotion, affect, extractedBy: written > 0 ? extractedBy : 'none' };
+        return {
+            written,
+            committed: written > 0,
+            rejections: gated.rejected,
+            emotion,
+            affect,
+            extractedBy: written > 0 ? extractedBy : 'none',
+        };
     }
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.

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

@@ -1,4 +1,4 @@
-import type { Emotion, LlmFn, MemoryType, ReflectResult, Turn } from './types.ts';
+import type { DraftRejection, Emotion, LlmFn, MemoryType, ReflectResult, Turn } from './types.ts';
 import type { SoulStore } from './store.ts';
 interface Draft {
     type: MemoryType;
@@ -26,6 +26,24 @@ export declare const MAX_STRATEGY_CHARS = 80;
 export declare function distillStrategy(text: string): string | null;
 /** Cheap, synchronous, no model. Deliberately conservative: false positives cost trust. */
 export declare const RULES: Rule[];
+/** Is this user turn a correction? Evidence for RFC 0003, not a memory by itself. */
+export declare function isCorrection(text: string): boolean;
+/** Which marker matched, for statistics; null when the turn is not a correction. */
+export declare function correctionRule(text: string): string | null;
+/** Types an extractor may produce; episodic/relationship are host-local. */
+export declare const EXTRACTABLE_TYPES: MemoryType[];
+export declare const MAX_CONTENT_CHARS = 500;
+/** A single turn should not flood the store. */
+export declare const MAX_DRAFTS_PER_TURN = 3;
+/**
+ * Deterministic write gates. A draft must pass shape, then semantics, then the
+ * per-turn budget; anything refused is reported with the gate that refused it,
+ * so a "written: 0" is explainable rather than mysterious.
+ */
+export declare function gateDrafts(drafts: Draft[]): {
+    accepted: Draft[];
+    rejected: DraftRejection[];
+};
 export declare function ruleExtract(turns: Turn[]): Draft[];
 /** Corrections raise tension and lower passion; an ordinary session lets tension decay. */
 export declare function nextEmotion(current: Emotion, turns: Turn[]): Emotion;

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

@@ -75,8 +75,52 @@ export const RULES = [
     },
 ];
 const CORRECTION = /(不对|不是这样|错了|你搞错|wrong|that'?s not right|incorrect)/i;
+/** Is this user turn a correction? Evidence for RFC 0003, not a memory by itself. */
+export function isCorrection(text) {
+    return CORRECTION.test(text);
+}
+/** Which marker matched, for statistics; null when the turn is not a correction. */
+export function correctionRule(text) {
+    const match = CORRECTION.exec(text);
+    return match ? match[0] : null;
+}
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
 const round2 = (n) => Math.round(n * 100) / 100;
+/** Types an extractor may produce; episodic/relationship are host-local. */
+export const EXTRACTABLE_TYPES = ['strategy', 'trait', 'fact', 'cognition'];
+export const MAX_CONTENT_CHARS = 500;
+/** A single turn should not flood the store. */
+export const MAX_DRAFTS_PER_TURN = 3;
+/**
+ * Deterministic write gates. A draft must pass shape, then semantics, then the
+ * per-turn budget; anything refused is reported with the gate that refused it,
+ * so a "written: 0" is explainable rather than mysterious.
+ */
+export function gateDrafts(drafts) {
+    const accepted = [];
+    const rejected = [];
+    for (const draft of drafts) {
+        const content = draft.content.trim();
+        if (!EXTRACTABLE_TYPES.includes(draft.type)) {
+            rejected.push({ gate: 'shape', reason: `type ${draft.type} is not extractable`, content });
+            continue;
+        }
+        if (content.length < 2 || content.length > MAX_CONTENT_CHARS) {
+            rejected.push({ gate: 'shape', reason: `length ${content.length} (2..${MAX_CONTENT_CHARS})`, content });
+            continue;
+        }
+        if (content.replace(/[\s\p{P}\p{S}]/gu, '').length < 2) {
+            rejected.push({ gate: 'semantic', reason: 'no word characters', content });
+            continue;
+        }
+        if (accepted.length >= MAX_DRAFTS_PER_TURN) {
+            rejected.push({ gate: 'budget', reason: `more than ${MAX_DRAFTS_PER_TURN} drafts in one turn`, content });
+            continue;
+        }
+        accepted.push({ ...draft, content });
+    }
+    return { accepted, rejected };
+}
 export function ruleExtract(turns) {
     const drafts = [];
     for (const turn of turns) {
@@ -140,8 +184,9 @@ export async function reflect(store, options) {
     }
     const existing = store.query({ soulId: options.soulId, userId: options.userId });
     const seen = new Set(existing.map((m) => m.content));
+    const { accepted, rejected } = gateDrafts(drafts);
     let written = 0;
-    for (const draft of drafts) {
+    for (const draft of accepted) {
         if (seen.has(draft.content))
             continue;
         seen.add(draft.content);
@@ -168,7 +213,7 @@ export async function reflect(store, options) {
         emotion = nextEmotion(emotion, options.turns);
         store.saveEmotion(options.soulId, options.userId, emotion);
     }
-    return { memories: written, superseded: 0, emotion };
+    return { memories: written, superseded: null, emotion, committed: written > 0, rejections: rejected };
 }
 /* ------------------------------------------------------------------ *
  * LLM distillation port (optional)

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

@@ -76,6 +76,17 @@ CREATE TABLE IF NOT EXISTS affect_samples (
 );
 CREATE INDEX IF NOT EXISTS idx_affect ON affect_samples(soul_id, user_id, at DESC);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_affect_unique ON affect_samples(soul_id, user_id, at, analyzer);
+CREATE TABLE IF NOT EXISTS corrections (
+  id             TEXT PRIMARY KEY,
+  soul_id        TEXT NOT NULL,
+  user_id        TEXT NOT NULL,
+  at             INTEGER NOT NULL,
+  user_text      TEXT NOT NULL,
+  assistant_text TEXT,
+  rule           TEXT,
+  device_id      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_corrections ON corrections(soul_id, user_id, at DESC);
 `;
 const sleepSync = (ms) => {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -123,6 +134,20 @@ function upgradeToV2(db) {
     db.exec('UPDATE memories SET updated_at = created_at WHERE updated_at IS NULL');
     db.exec('UPDATE emotions SET updated_at = 0 WHERE updated_at IS NULL');
 }
+/** v2 → v3: corrections evidence table (RFC 0003 phase A). */
+function upgradeToV3(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS corrections (
+    id             TEXT PRIMARY KEY,
+    soul_id        TEXT NOT NULL,
+    user_id        TEXT NOT NULL,
+    at             INTEGER NOT NULL,
+    user_text      TEXT NOT NULL,
+    assistant_text TEXT,
+    rule           TEXT,
+    device_id      TEXT
+  )`);
+    db.exec('CREATE INDEX IF NOT EXISTS idx_corrections ON corrections(soul_id, user_id, at DESC)');
+}
 function backupBeforeUpgrade(file, from) {
     if (file === ':memory:' || !existsSync(file))
         return;
@@ -144,6 +169,8 @@ export function openSqlite(file) {
         backupBeforeUpgrade(file, version);
         if (version < 2)
             upgradeToV2(db);
+        if (version < 3)
+            upgradeToV3(db);
         setVersion(db, SCHEMA_VERSION);
     }
     const stmtPut = db.prepare(`
@@ -260,6 +287,34 @@ export function openSqlite(file) {
             const result = withRetry(() => db.prepare('DELETE FROM affect_samples WHERE at < ?').run(beforeMs));
             return Number(result.changes ?? 0);
         },
+        saveCorrection(correction) {
+            withRetry(() => db
+                .prepare(`INSERT INTO corrections (id, soul_id, user_id, at, user_text, assistant_text, rule, device_id)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(correction.id, correction.soulId, correction.userId, correction.at, correction.userText, correction.assistantText ?? null, correction.rule ?? null, correction.deviceId ?? null));
+        },
+        recentCorrections(soulId, userId, limit) {
+            const rows = db
+                .prepare(`SELECT * FROM corrections WHERE soul_id = ? AND user_id = ?
+           ORDER BY at DESC LIMIT ?`)
+                .all(soulId, userId, limit);
+            return rows.map((row) => ({
+                id: String(row.id),
+                soulId: String(row.soul_id),
+                userId: String(row.user_id),
+                at: Number(row.at),
+                userText: String(row.user_text),
+                assistantText: row.assistant_text == null ? undefined : String(row.assistant_text),
+                rule: row.rule == null ? undefined : String(row.rule),
+                deviceId: row.device_id == null ? undefined : String(row.device_id),
+            }));
+        },
+        countCorrections(soulId, userId) {
+            const row = db
+                .prepare('SELECT COUNT(*) AS n FROM corrections WHERE soul_id = ? AND user_id = ?')
+                .get(soulId, userId);
+            return Number(row.n);
+        },
         count(soulId, userId) {
             const row = db
                 .prepare(`SELECT COUNT(*) AS n FROM memories

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

@@ -2,7 +2,7 @@
  * The only port. Every added method is a storage engine's opinion leaking into
  * the domain, so the surface stays deliberately small.
  */
-import type { AffectSignal, Emotion, Identity, Memory, QuerySpec } from './types.ts';
+import type { AffectSignal, Correction, Emotion, Identity, Memory, QuerySpec } from './types.ts';
 export interface SoulStore {
     ensureSoul(identity: Identity): void;
     identity(soulId: string): Identity | null;
@@ -24,6 +24,10 @@ export interface SoulStore {
     recentAffect(soulId: string, userId: string, sinceMs: number): AffectSignal[];
     /** Drop samples older than `beforeMs`; returns rows removed. */
     purgeAffect(beforeMs: number): number;
+    /** Evidence, not memory: a user correction plus the reply it targeted. */
+    saveCorrection(correction: Correction): void;
+    recentCorrections(soulId: string, userId: string, limit: number): Correction[];
+    countCorrections(soulId: string, userId: string): number;
     count(soulId: string, userId: string): number;
     close(): void;
 }

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

@@ -100,11 +100,30 @@ export interface QuerySpec {
 }
 export interface ReflectResult {
     memories: number;
-    superseded: number;
+    /**
+     * How many older memories were replaced by a newer conflicting one.
+     * `null` means this build does not track supersession yet — it used to report
+     * a hardcoded 0, which claimed a capability that did not exist.
+     */
+    superseded: number | null;
     emotion: Emotion;
+    /** True when at least one memory was durably written by this call. */
+    committed: boolean;
+    /** Drafts refused before writing, with the gate that refused them. */
+    rejections: DraftRejection[];
+}
+export type GateName = 'shape' | 'semantic' | 'budget';
+export interface DraftRejection {
+    gate: GateName;
+    reason: string;
+    content: string;
 }
 export interface ObserveResult {
     written: number;
+    /** True when at least one memory was durably written by this call. */
+    committed: boolean;
+    /** Drafts refused before writing, with the gate that refused them. */
+    rejections: DraftRejection[];
     emotion: Emotion;
     /** Analysis of the user turn. Empty signal for assistant turns or on failure. */
     affect: AffectSignal;
@@ -148,3 +167,30 @@ export interface AffectSignal {
 export declare const EMPTY_AFFECT: AffectSignal;
 /** Wire version of the four verbs. Additive changes bump MINOR (ADR 0005). */
 export declare const PROTOCOL_VERSION = "0.2";
+/**
+ * Evidence, not memory: a user correction captured with the reply it targeted.
+ * Stored separately so it never reaches a prompt; distillation (RFC 0003 phase B)
+ * is what turns evidence into a strategy.
+ */
+export interface Correction {
+    id: string;
+    soulId: string;
+    userId: string;
+    at: number;
+    /** The user's own words, complete. */
+    userText: string;
+    /** The reply the correction targeted, complete; undefined when unknown. */
+    assistantText?: string;
+    /** Which marker matched (for statistics). */
+    rule?: string;
+    deviceId?: string;
+}
+export interface CorrectionInput {
+    soulId: string;
+    userId: string;
+    userText: string;
+    assistantText?: string;
+    rule?: string;
+    deviceId?: string;
+    at?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soulbridge",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",