soulbridge 0.0.13 → 0.0.15

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

@@ -312,7 +312,9 @@ async function main() {
             }
             for (const memory of memories) {
                 const preview = memory.content.replace(/\s+/g, ' ').slice(0, 72);
-                process.stdout.write(`${memory.id}  ${memory.type.padEnd(9)} imp=${String(memory.importance).padEnd(2)} ${preview}\n`);
+                const status = memory.status === 'active' ? '' : ` [${memory.status}]`;
+                const superseded = memory.supersededBy ? ` -> ${memory.supersededBy}` : '';
+                process.stdout.write(`${memory.id}  ${memory.type.padEnd(9)} imp=${String(memory.importance).padEnd(2)}${status}${superseded} ${preview}\n`);
             }
             return;
         }
@@ -324,6 +326,14 @@ async function main() {
             out({ ok: soul.forget(id), id });
             return;
         }
+        case 'supersede': {
+            const [oldId, newId] = positional;
+            if (!oldId || !newId)
+                throw new Error('usage: soulbridge supersede <old-id> <new-id>');
+            const { soul } = open(flags);
+            out({ ok: soul.supersede(oldId, newId), oldId, newId });
+            return;
+        }
         case 'corrections': {
             const { soul } = open(flags);
             const rows = soul.corrections(flags.limit ? Number(flags.limit) : 10);
@@ -344,9 +354,19 @@ async function main() {
             const config = ensureConfig();
             const dbPath = resolveDbPath(flags.db);
             const store = openSqlite(dbPath);
-            const memories = store.query({ soulId: config.soulId, userId: config.userId, limit: 100_000 });
+            const memories = store.query({
+                soulId: config.soulId,
+                userId: config.userId,
+                status: ['active', 'superseded'],
+                includeExpired: true,
+                limit: 100_000,
+            });
             const samples = store.recentAffect(config.soulId, config.userId, 0);
             store.close();
+            const now = Date.now();
+            const activeCount = memories.filter((m) => m.status === 'active' && (m.validUntil === undefined || m.validUntil > now)).length;
+            const supersededCount = memories.filter((m) => m.status === 'superseded').length;
+            const expiredCount = memories.filter((m) => m.status === 'active' && m.validUntil !== undefined && m.validUntil <= now).length;
             const byType = new Map();
             for (const memory of memories)
                 byType.set(memory.type, (byType.get(memory.type) ?? 0) + 1);
@@ -373,7 +393,7 @@ async function main() {
             const lines = [
                 `soul       ${config.soulId} / ${config.userId}`,
                 `db         ${dbPath}`,
-                `memories   ${memories.length}  (${typeText})`,
+                `memories   ${memories.length}  (有效 ${activeCount} · 被取代 ${supersededCount} · 已过期 ${expiredCount})  (${typeText})`,
                 `affect     ${samples.length} samples${samples.length > 0 ? ` · last ${ago(samples[0].at)}` : ''}`,
                 plugin
                     ? `plugin     v${plugin.version ?? '?'} · applied ${ago(plugin.appliedAt)} · inject ${plugin.injects ?? 0} · observe ${plugin.observes ?? 0} · fail ${plugin.observeFails ?? 0}`
@@ -411,6 +431,7 @@ async function main() {
                 '  list [--limit N]                看它记住了什么',
                 '  corrections [--limit N]         看被纠正过的证据',
                 '  forget <id>                     忘掉一条记忆（墓碑）',
+                '  supersede <old> <new>           用新记忆取代旧记忆（保留历史）',
                 '  status                          一眼看它是否在工作',
                 '  stats                           看原始状态（JSON）',
                 '  demo                            端到端演示（无需模型）',

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

@@ -52,10 +52,15 @@ export declare class Soul {
     constructor(options: SoulOptions);
     /** Verb 1: session start. */
     context(request?: Partial<ContextRequest>): ContextResult;
-    /** Every active memory, newest first. For `list` and for auditing injection. */
+    /**
+     * Audit view: every non-deleted row, including superseded and expired ones.
+     * Prompt builders use `context`, which filters both out.
+     */
     list(limit?: number): Memory[];
     /** Tombstone one memory so it never reaches a prompt again. */
     forget(id: string): boolean;
+    /** Mark `oldId` replaced by `newId`; neither row is deleted (RFC 0004). */
+    supersede(oldId: string, newId: 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.

package/dist/packages/core/src/index.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;
@@ -59,14 +59,27 @@ export class Soul {
             maxItems: request.maxItems,
         });
     }
-    /** Every active memory, newest first. For `list` and for auditing injection. */
+    /**
+     * Audit view: every non-deleted row, including superseded and expired ones.
+     * Prompt builders use `context`, which filters both out.
+     */
     list(limit = 50) {
-        return this.store.query({ soulId: this.soulId, userId: this.userId, limit });
+        return this.store.query({
+            soulId: this.soulId,
+            userId: this.userId,
+            status: ['active', 'superseded'],
+            includeExpired: true,
+            limit,
+        });
     }
     /** Tombstone one memory so it never reaches a prompt again. */
     forget(id) {
         return this.store.forget(id);
     }
+    /** Mark `oldId` replaced by `newId`; neither row is deleted (RFC 0004). */
+    supersede(oldId, newId) {
+        return this.store.supersede(oldId, newId);
+    }
     /**
      * Record a user correction as evidence (RFC 0003 phase A). Nothing here
      * reaches a prompt; distillation to a strategy is a later phase.
@@ -129,10 +142,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());
@@ -164,7 +180,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;
@@ -30,6 +30,20 @@ export declare const RULES: Rule[];
 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

@@ -86,6 +86,41 @@ export function correctionRule(text) {
 }
 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) {
@@ -149,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);
@@ -177,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

@@ -236,12 +236,15 @@ export function openSqlite(file) {
         query(spec) {
             const statuses = spec.status ?? ['active'];
             const placeholders = statuses.map(() => '?').join(', ');
+            const now = spec.now ?? Date.now();
+            // Expiry is a filter, not a deletion: audit views can still see the row.
+            const expiry = spec.includeExpired ? '' : 'AND (valid_until IS NULL OR valid_until > ?)';
             const rows = db
                 .prepare(`SELECT * FROM memories
            WHERE soul_id = ? AND (user_id = ? OR visibility = 'shared')
-             AND status IN (${placeholders}) AND deleted_at IS NULL
+             AND status IN (${placeholders}) AND deleted_at IS NULL ${expiry}
            ORDER BY created_at DESC LIMIT ?`)
-                .all(spec.soulId, spec.userId, ...statuses, spec.limit ?? 500);
+                .all(spec.soulId, spec.userId, ...statuses, ...(spec.includeExpired ? [] : [now]), spec.limit ?? 500);
             const memories = rows.map(rowToMemory);
             return spec.types ? memories.filter((m) => spec.types.includes(m.type)) : memories;
         },
@@ -258,6 +261,19 @@ export function openSqlite(file) {
                 .run(now, now, id));
             return Number(result.changes ?? 0) > 0;
         },
+        /** Mark `oldId` as replaced by `newId`. Neither row is deleted. */
+        supersede(oldId, newId, now = Date.now()) {
+            const replacement = db
+                .prepare('SELECT id FROM memories WHERE id = ? AND deleted_at IS NULL')
+                .get(newId);
+            if (!replacement)
+                return false;
+            const result = withRetry(() => db
+                .prepare(`UPDATE memories SET status = 'superseded', superseded_by = ?, updated_at = ?
+             WHERE id = ? AND status = 'active' AND deleted_at IS NULL`)
+                .run(newId, now, oldId));
+            return Number(result.changes ?? 0) > 0;
+        },
         saveAffect(soulId, userId, signal, at, deviceId) {
             withRetry(() => {
                 db.prepare(`INSERT OR IGNORE INTO affect_samples

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

@@ -18,6 +18,12 @@ export interface SoulStore {
      * merge, the deletion wins by updatedAt). Returns false when no such active row.
      */
     forget(id: string, now?: number): boolean;
+    /**
+     * Mark `oldId` as replaced by `newId` (status superseded, supersededBy set).
+     * Both rows stay; returns false when the replacement is missing or the old row
+     * is not active.
+     */
+    supersede(oldId: string, newId: string, now?: number): boolean;
     /** Persist one affect sample (payload only; no raw text). */
     saveAffect(soulId: string, userId: string, signal: AffectSignal, at: number, deviceId?: string): void;
     /** Samples newer than `sinceMs`, newest first. */

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

@@ -23,8 +23,11 @@ export interface Memory {
     keywords: string[];
     createdAt: number;
     lastRecalledAt?: number;
+    /** Written on create; no code filters by it yet (roadmap N3). */
     validFrom?: number;
+    /** Reserved for expiry filtering; not enforced yet (roadmap N3). */
     validUntil?: number;
+    /** Reserved for conflict replacement; not written yet (roadmap N3). */
     supersededBy?: string;
     /** Last-writer-wins clock for cross-device merge (ADR 0021). */
     updatedAt?: number;
@@ -81,12 +84,6 @@ export interface ContextResult {
         directives: string[];
     };
 }
-export interface RecallRequest {
-    soulId: string;
-    userId: string;
-    q: string;
-    limit?: number;
-}
 export interface ScoredMemory {
     memory: Memory;
     score: number;
@@ -97,14 +94,41 @@ export interface QuerySpec {
     status?: MemoryStatus[];
     types?: MemoryType[];
     limit?: number;
+    /** Clock for expiry checks; defaults to now. */
+    now?: number;
+    /**
+     * Audit views (`list`) need to see expired rows; prompt builders must not.
+     * Defaults to false, so expiry applies unless a caller asks otherwise.
+     */
+    includeExpired?: boolean;
 }
 export interface ReflectResult {
     memories: number;
-    superseded: number;
+    /**
+     * How many older memories were replaced by a newer conflicting one.
+     *
+  ull` 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;
@@ -166,12 +190,3 @@ export interface Correction {
     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.13",
+  "version": "0.0.15",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",