soulbridge 0.0.102 → 0.0.104

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

@@ -14,7 +14,7 @@
  *   soulbridge demo
  */
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 // node:sqlite prints an ExperimentalWarning the moment it loads. Replace the default
 // printer with a filter: the CLI's own output stays clean, other warnings still show.
 // Must run before the dynamic import below, which is why that import is dynamic.
@@ -221,9 +221,27 @@ async function main() {
             return;
         }
         case 'export': {
+            // Two shapes: a legacy JSONL of memories (--out), and the portable bundle (--dir)
+            // that carries the whole record, a readable summary and the current injection.
+            if (flags.dir) {
+                const { soul } = open(flags);
+                const dir = resolve(String(flags.dir));
+                mkdirSync(dir, { recursive: true });
+                const bundle = soul.portableBundle();
+                writeFileSync(join(dir, 'archive.jsonl'), `${bundle.archive.join('\n')}\n`, 'utf8');
+                writeFileSync(join(dir, 'summary.md'), bundle.summary, 'utf8');
+                writeFileSync(join(dir, 'injection.txt'), bundle.injection, 'utf8');
+                out({
+                    ok: true,
+                    dir,
+                    records: bundle.archive.length,
+                    files: ['archive.jsonl', 'summary.md', 'injection.txt'],
+                });
+                return;
+            }
             const file = flags.out;
             if (!file)
-                throw new Error('usage: soulbridge export --out soulbridge.jsonl');
+                throw new Error('usage: soulbridge export --out <file> | --dir <directory>');
             const { soul, deviceId } = open(flags);
             const body = exportJsonl(soul, deviceId);
             const target = resolve(file);
@@ -425,6 +443,7 @@ async function main() {
                 '  recall <q> [--limit N]          召回',
                 '  reflect --text|--file           会话反思',
                 '  export --out <file>             导出 JSONL',
+                '  export --dir <directory>        导出可携带档案（archive/summary/injection）',
                 '  import --in <file>              导入 JSONL',
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',

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

@@ -245,8 +245,10 @@ export function parseProfileMerge(raw, allowed, expected) {
         // model mixed two lenses back together, which is the welding the split prevents.
         if (expected && dimension !== expected)
             continue;
-        const sourceField = fields.find((field) => field.startsWith('来源'));
-        const sources = (sourceField?.replace(/^来源\s*[=＝]\s*/, '') ?? '')
+        // One name for the field now; 来源 is accepted only so an older prompt in flight
+        // still parses.
+        const sourceField = fields.find((field) => /^(证据|来源)\s*[=＝]/.test(field));
+        const sources = (sourceField?.replace(/^(证据|来源)\s*[=＝]\s*/, '') ?? '')
             .split(/[,，、;；\s]+/)
             .map((id) => id.trim())
             .filter((id) => allowed.has(id));
@@ -277,7 +279,9 @@ export function parseProfileMerge(raw, allowed, expected) {
  * so both are read — a line that names its sources can never be merge input.
  */
 export function isDerivedProfileLine(fact) {
-    return (fact.slots ?? []).some((slot) => slot.slot === '来源' || slot.slot === '合并');
+    // 证据 is the one name for "this line cites its sources"; 来源 was the old spelling and 合并
+    // marks a merged line that has no sources of its own.
+    return (fact.slots ?? []).some((slot) => slot.slot === '证据' || slot.slot === '合并');
 }
 /**
  * Cut the merge input along dimensions before any model sees it.

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

@@ -30,7 +30,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, 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 { 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, PortableBundle, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
 import type { Rule } from './rules.ts';
@@ -80,6 +80,11 @@ export declare class Soul {
     readonly dedupeWindowMs: number;
     readonly onLlmRaw?: (raw: string) => void;
     constructor(options: SoulOptions);
+    /**
+     * Everything a host needs to carry this soul to another machine or tool:
+     * the full archive, a readable summary, and the injection the model would see.
+     */
+    portableBundle(now?: number): PortableBundle;
     /** Verb 1: session start. */
     context(request?: Partial<ContextRequest>): ContextResult;
     /**

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

@@ -21,6 +21,7 @@ export * from './storage/config.js';
 export * from './storage/merge.js';
 export * from './storage/steering.js';
 export * from './storage/transcript.js';
+import { buildPortableBundle } from './portable.js';
 import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
 import { HOLDER_WORDS } from './config/domains.js';
 import { isActive, isRetracted, roleOf } from './roles.js';
@@ -100,6 +101,15 @@ export class Soul {
             });
         }
     }
+    /**
+     * Everything a host needs to carry this soul to another machine or tool:
+     * the full archive, a readable summary, and the injection the model would see.
+     */
+    portableBundle(now = Date.now()) {
+        const dump = this.store.dump(this.soulId, this.userId);
+        const injection = this.context({}).text;
+        return buildPortableBundle(dump, this.soulId, this.userId, injection, now);
+    }
     /** Verb 1: session start. */
     context(request = {}) {
         // Spread, not a field list: an explicit list silently dropped every option
@@ -181,7 +191,9 @@ export class Soul {
      * code would be the guess ADR 0027 forbids.
      */
     promotionCandidates(turnId) {
-        return this.store.factsByTurns([turnId]).filter((fact) => fact.slots.some((slot) => slot.slot === '原则候选' && slot.value.kind === 'text' && slot.value.value === '是'));
+        return this.store
+            .factsByTurns([turnId], { includeCandidates: true })
+            .filter((fact) => fact.role === 'lesson' && fact.status === 'candidate');
     }
     /**
      * Store one exchange (RFC 0007). Idempotent on `(sessionId, turn)`: a repeat is
@@ -494,11 +506,11 @@ export class Soul {
                 skipped.push({ what: statement, reason: 'duplicate' });
                 return null;
             }
-            // The promotion rules read this slot; they must not re-read the statement to
-            // guess whether it was a lesson, because that is the semantic call the model
-            // already made.
-            if (factDraft.principle)
-                slots.push({ slot: '原则候选', value: { kind: 'text', value: '是' } });
+            // An unclassified lesson is a candidate: a lesson the model flagged but did not
+            // place in a role. It is held and shown to the classifier, injected nowhere.
+            // This replaced the old `原则候选` slot, which was the same decision stored as text.
+            const role = factDraft.principle && !factDraft.role ? 'lesson' : factDraft.role;
+            const status = factDraft.principle && !factDraft.role ? 'candidate' : undefined;
             // ADR 0035: a fact from my side of the exchange is `inferred`, and inferred
             // claims must carry their evidence. The turn id is the evidence available here —
             // claims that need a tool or test result are kept out by the prompt instead.
@@ -510,7 +522,8 @@ export class Soul {
                 userId: this.userId,
                 statement,
                 holder,
-                role: factDraft.role,
+                role,
+                status,
                 typeName: factDraft.typeName,
                 at: factDraft.at,
                 atText: factDraft.atText,
@@ -747,7 +760,7 @@ export class Soul {
                 // More sources means more observations behind the line, so it ranks first.
                 confidence: Math.min(0.95, 0.6 + 0.05 * line.sources.length),
                 slots: [
-                    ...line.sources.map((id) => ({ slot: '来源', value: { kind: 'fact', factId: id } })),
+                    ...line.sources.map((id) => ({ slot: '证据', value: { kind: 'fact', factId: id } })),
                     // A merged line is not an original: re-merging merged lines loses detail.
                     { slot: '合并', value: { kind: 'text', value: '1' } },
                     { slot: '维度', value: { kind: 'text', value: line.dimension } },

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

@@ -0,0 +1,17 @@
+/**
+ * Portable bundle: the whole record, a human-readable summary, and the injection text.
+ *
+ * Three layers, because they answer different questions (spec/vocabulary.v1 §7):
+ *   archive   — everything, including raw exchanges; the recipient can rebuild the store.
+ *   summary   — what a person can read in a minute: rules, profile, conclusions, promises,
+ *               entities, open gaps. No ids unless they help.
+ *   injection — what the model would see right now; the smallest useful transfer.
+ *
+ * Nothing here filters by importance. An export that silently drops "unimportant" rows
+ * cannot be the source of truth, and importance is a semantic judgement we do not store.
+ */
+import type { PortableDump, PortableBundle } from './types.ts';
+export declare function buildPortableSummary(dump: PortableDump, soulId: string, userId: string, now: number): string;
+/** One JSON object per line, tagged so a reader can stream it without a schema. */
+export declare function buildArchiveLines(dump: PortableDump): string[];
+export declare function buildPortableBundle(dump: PortableDump, soulId: string, userId: string, injection: string, now: number): PortableBundle;

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

@@ -0,0 +1,93 @@
+export function buildPortableSummary(dump, soulId, userId, now) {
+    const lines = [];
+    lines.push(`# soulbridge 档案 · ${userId}`);
+    lines.push('');
+    lines.push(`- soul: ${soulId}`);
+    lines.push(`- 导出时间: ${new Date(now).toISOString()}`);
+    lines.push(`- 规模: 事实 ${dump.facts.length} · 实体 ${dump.entities.length} · 线索 ${dump.threads.length} · 轮次 ${dump.turns.length} · 缺口 ${dump.gaps.length}`);
+    lines.push('');
+    const byRole = (role) => dump.facts.filter((fact) => fact.role === role && fact.status === 'active');
+    const slotText = (fact, name) => {
+        const slot = fact.slots.find((item) => item.slot === name);
+        return slot?.value.kind === 'text' ? slot.value.value : undefined;
+    };
+    const rules = byRole('rule');
+    if (rules.length > 0) {
+        lines.push(`## 规则（${rules.length}）`);
+        for (const rule of rules) {
+            const trigger = slotText(rule, '触发');
+            const action = slotText(rule, '动作') ?? rule.statement;
+            lines.push(trigger ? `- 当 ${trigger}：${action}` : `- ${action}`);
+        }
+        lines.push('');
+    }
+    const profile = byRole('profile');
+    if (profile.length > 0) {
+        lines.push(`## 画像（${profile.length}）`);
+        for (const line of profile)
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    const judgments = byRole('judgment');
+    if (judgments.length > 0) {
+        lines.push(`## 结论（${judgments.length}）`);
+        for (const line of judgments.slice(0, 30))
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    const promises = byRole('promise');
+    if (promises.length > 0) {
+        lines.push(`## 承诺（${promises.length}）`);
+        for (const line of promises)
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    if (dump.entities.length > 0) {
+        lines.push(`## 实体（${dump.entities.length}）`);
+        for (const entity of dump.entities.slice(0, 50)) {
+            const aliases = entity.aliases.length > 0 ? `（别名：${entity.aliases.join('、')}）` : '';
+            lines.push(`- ${entity.name} · ${entity.type}${aliases}`);
+        }
+        lines.push('');
+    }
+    const openGaps = dump.gaps.filter((gap) => gap.status === 'open');
+    if (openGaps.length > 0) {
+        lines.push(`## 未闭合的缺口（${openGaps.length}）`);
+        for (const gap of openGaps.slice(0, 20))
+            lines.push(`- ${gap.topic}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** One JSON object per line, tagged so a reader can stream it without a schema. */
+export function buildArchiveLines(dump) {
+    const lines = [];
+    // `record` is the discriminator, not `type`: Entity has its own `type` field, and a
+    // spread after the tag would silently overwrite it.
+    for (const entity of dump.entities)
+        lines.push(JSON.stringify({ record: 'entity', ...entity }));
+    for (const fact of dump.facts)
+        lines.push(JSON.stringify({ record: 'fact', ...fact }));
+    for (const thread of dump.threads)
+        lines.push(JSON.stringify({ record: 'thread', ...thread }));
+    for (const gap of dump.gaps)
+        lines.push(JSON.stringify({ record: 'gap', ...gap }));
+    for (const turn of dump.turns)
+        lines.push(JSON.stringify({ record: 'turn', ...turn }));
+    for (const step of dump.steps)
+        lines.push(JSON.stringify({ record: 'step', ...step }));
+    for (const correction of dump.corrections)
+        lines.push(JSON.stringify({ record: 'correction', ...correction }));
+    return lines;
+}
+export function buildPortableBundle(dump, soulId, userId, injection, now) {
+    return {
+        schemaVersion: 1,
+        exportedAt: now,
+        soulId,
+        userId,
+        summary: buildPortableSummary(dump, soulId, userId, now),
+        injection,
+        archive: buildArchiveLines(dump),
+    };
+}

package/dist/packages/core/src/profile-prompt.js

@@ -41,7 +41,7 @@ const PROFILE_RULES = `<rules>
 - 不许出现"一切/所有/总是/从不"，除非来源原文里就有。
 - 每行给一个维度：${dimensionChoices()}
 - 一行只讲一个维度。不同维度必须分行——跨维度拼成一句就是没拆。
-- 每条必须给来源：来源=fc_xxx,fc_yyy，只能引用 <input> 里出现过的 id；没有来源的整行不要。
+- 每条必须给证据：证据=fc_xxx,fc_yyy，只能引用 <input> 里出现过的 id；没有证据的整行不要。
 - 合并后 5–8 条；宁少不凑。
 - 输入里没有的新判断，不许出现。
 </rules>`;
@@ -68,8 +68,8 @@ const PROFILE_EXAMPLE = `<example>
 - fc_c | 用户很讨厌一件事反复讲，换工具又要重新交代
 </input>
 <output>
-画像: 要机制，不要靠 prompt 的自觉 | 维度=${PROFILE_DIMENSIONS[1]} | 来源=fc_a,fc_b
-画像: 讨厌重复交代，工具换了也不该重讲 | 维度=${PROFILE_DIMENSIONS[2]} | 来源=fc_c
+画像: 要机制，不要靠 prompt 的自觉 | 维度=${PROFILE_DIMENSIONS[1]} | 证据=fc_a,fc_b
+画像: 讨厌重复交代，工具换了也不该重讲 | 维度=${PROFILE_DIMENSIONS[2]} | 证据=fc_c
 </output>
 </example>`;
 /**

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

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { SoulStore } from './store.ts';
-export declare const SCHEMA_VERSION = 10;
+export declare const SCHEMA_VERSION = 11;
 export declare const AFFECT_RETENTION_MS: number;
 export declare class DbNewerThanBinaryError extends Error {
     readonly code = "DB_NEWER_THAN_BINARY";
@@ -13,6 +13,7 @@ export declare class DbNewerThanBinaryError extends Error {
  * 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 upgradeToV11(db: DatabaseSync): void;
 export declare function upgradeToV10(db: DatabaseSync): void;
 export declare function upgradeToV9(db: DatabaseSync): void;
 export declare function upgradeToV8(db: DatabaseSync): void;

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

@@ -12,7 +12,7 @@ import { DEFAULT_EMOTION } from './types.js';
 import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
 import { FACT_ROLES } from './config/domains.js';
 import { bm25, buildCorpusStats, tokenize } from './scoring.js';
-export const SCHEMA_VERSION = 10;
+export const SCHEMA_VERSION = 11;
 /** How many recent pairs are considered before scoring. Bounded so recall stays O(candidates). */
 const RECALL_CANDIDATES = 500;
 export const AFFECT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -299,6 +299,21 @@ function upgradeToV3(db) {
  * 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 function upgradeToV11(db) {
+    // 原则候选 stored a decision as a slot; it is role+status now. The row becomes a lesson
+    // candidate — held and shown to the classifier, injected nowhere until it is placed.
+    db.exec(`UPDATE facts SET role = 'lesson', status = 'candidate'
+            WHERE id IN (SELECT fact_id FROM fact_slots WHERE slot = '原则候选' AND value_text = '是')`);
+    db.exec("DELETE FROM fact_slots WHERE slot = '原则候选'");
+    // One name for "this cites its sources": 来源 → 证据. Skip where the fact already cites
+    // the same row under the new name, then drop what is left of the old spelling.
+    db.exec(`UPDATE fact_slots SET slot = '证据'
+            WHERE slot = '来源'
+              AND NOT EXISTS (SELECT 1 FROM fact_slots x
+                               WHERE x.fact_id = fact_slots.fact_id AND x.slot = '证据'
+                                 AND x.ref_fact_id = fact_slots.ref_fact_id)`);
+    db.exec("DELETE FROM fact_slots WHERE slot = '来源'");
+}
 export function upgradeToV10(db) {
     // The four-state vocabulary (config/status.ts). Everything written under the old names
     // becomes one of the two states the code now reads; after this the fallbacks are gone.
@@ -448,8 +463,8 @@ export function openSqlite(file) {
                 upgradeToV7(db);
             if (version < 8)
                 upgradeToV8(db);
-            if (version < 10)
-                upgradeToV10(db);
+            if (version < 11)
+                upgradeToV11(db);
             // v6 adds tables only; SCHEMA creates them on every open, nothing to copy.
             setVersion(db, SCHEMA_VERSION);
             db.exec('COMMIT');
@@ -631,6 +646,45 @@ export function openSqlite(file) {
                 deviceId: row.device_id == null ? undefined : String(row.device_id),
             }));
         },
+        corrections(soulId, userId, limit = 100_000) {
+            return this.recentCorrections(soulId, userId, limit);
+        },
+        dump(soulId, userId) {
+            const facts = this.facts({ soulId, userId, limit: 100_000 });
+            const entities = this.findEntities({ soulId, userId, limit: 100_000 });
+            const threads = db
+                .prepare('SELECT * FROM threads WHERE soul_id = ? AND user_id = ? ORDER BY opened_at ASC')
+                .all(soulId, userId).map(rowToThread);
+            const gaps = db
+                .prepare('SELECT * FROM gaps WHERE soul_id = ? AND user_id = ? ORDER BY opened_at ASC')
+                .all(soulId, userId).map(rowToGap);
+            const turns = db
+                .prepare('SELECT * FROM turns WHERE soul_id = ? AND user_id = ? ORDER BY created_at ASC')
+                .all(soulId, userId).map(rowToTurnPair);
+            const steps = db
+                .prepare(`SELECT s.* FROM steps s JOIN turns t ON t.id = s.turn_id
+            WHERE t.soul_id = ? AND t.user_id = ? ORDER BY s.turn_id, s.idx`)
+                .all(soulId, userId);
+            return {
+                entities,
+                facts,
+                threads,
+                gaps,
+                turns,
+                steps: steps.map((row) => ({
+                    turnId: String(row.turn_id),
+                    idx: Number(row.idx),
+                    kind: row.kind,
+                    text: row.text == null ? undefined : String(row.text),
+                    toolName: row.tool_name == null ? undefined : String(row.tool_name),
+                    toolArgsChars: row.tool_args_chars == null ? undefined : Number(row.tool_args_chars),
+                    toolResultChars: row.tool_result_chars == null ? undefined : Number(row.tool_result_chars),
+                    ok: row.ok == null ? undefined : Boolean(row.ok),
+                    at: Number(row.at),
+                })),
+                corrections: this.recentCorrections(soulId, userId, 100_000),
+            };
+        },
         countCorrections(soulId, userId) {
             const row = db
                 .prepare('SELECT COUNT(*) AS n FROM corrections WHERE soul_id = ? AND user_id = ?')
@@ -1006,12 +1060,19 @@ export function openSqlite(file) {
             const text = row ? String(row.user_text ?? '').trim() : '';
             return text === '' ? null : text;
         },
-        factsByTurns(turnIds) {
+        factsByTurns(turnIds, options = {}) {
             if (turnIds.length === 0)
                 return [];
             const placeholders = turnIds.map(() => '?').join(',');
+            // Only live facts. A retracted statement must not become evidence for the next
+            // consolidation; a candidate is held but unconfirmed, so it is evidence for nothing
+            // except the promotion step that decides its role.
+            const live = options.includeCandidates
+                ? `f.status IN ('${FACT_STATUS.active}','${FACT_STATUS.candidate}')`
+                : `f.status = '${FACT_STATUS.active}'`;
             const rows = db
-                .prepare(`SELECT f.* FROM facts f WHERE f.source_turn_id IN (${placeholders}) ORDER BY f.created_at ASC`)
+                .prepare(`SELECT f.* FROM facts f WHERE f.source_turn_id IN (${placeholders})
+             AND ${live} ORDER BY f.created_at ASC`)
                 .all(...turnIds);
             const slots = slotsOfRows(db, rows.map((row) => String(row.id)));
             return rows.map((row) => rowToFact(row, slots));

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, Correction, Emotion, Entity, EntityQuery, EntitySpec, Fact, FactQuery, FactRole, FactSpec, FactStatus, Gap, GapSpec, Identity, Memory, QuerySpec, SessionSummary, SlotValue, TurnPair, TurnPairSpec, TurnFindResult, TurnFindSpec, TurnSpec, TurnStep, TurnThread, ThreadSpec } from './types.ts';
+import type { AffectSignal, Correction, Emotion, Entity, EntityQuery, EntitySpec, Fact, FactQuery, FactRole, FactSpec, FactStatus, Gap, GapSpec, Identity, Memory, PortableDump, QuerySpec, SessionSummary, SlotValue, TurnPair, TurnPairSpec, TurnFindResult, TurnFindSpec, TurnSpec, TurnStep, TurnThread, ThreadSpec } from './types.ts';
 export interface SoulStore {
     ensureSoul(identity: Identity): void;
     identity(soulId: string): Identity | null;
@@ -88,8 +88,13 @@ export interface SoulStore {
     lastClosedThread(soulId: string, userId: string): TurnThread | null;
     /** Every turn of a thread, in order — the chapter, not one page. */
     threadTurns(threadId: string): TurnPair[];
-    /** Facts whose source turn belongs to the given turns. */
-    factsByTurns(turnIds: string[]): Fact[];
+    /**
+     * Facts whose source turn belongs to the given turns. Live facts only; candidates are
+     * included when asked, because promotion needs to see lessons not yet classified.
+     */
+    factsByTurns(turnIds: string[], options?: {
+        includeCandidates?: boolean;
+    }): Fact[];
     /** One turn by id, for expanding a fact back into its conversation. */
     turn(id: string): TurnPair | null;
     /** Retire a fact: the new one replaces it, the old row stays for the record. */
@@ -98,6 +103,10 @@ export interface SoulStore {
     putGap(spec: GapSpec): Gap;
     openGaps(soulId: string, userId: string, limit?: number): Gap[];
     closeGap(id: string, closedByFactId?: string, at?: number): void;
+    /** Corrections the user made, newest first — the objective signal for behaviour changes. */
+    corrections(soulId: string, userId: string, limit?: number): Correction[];
+    /** Everything a portable bundle needs, scoped to one soul/user. */
+    dump(soulId: string, userId: string): PortableDump;
     /** Exchanges visible to `userId`; scored against `spec.query` when given. */
     recallTurnPairs(spec: TurnPairSpec): TurnPair[];
     countTurnPairs(soulId: string, userId: string, sessionId?: string): number;

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

@@ -61,6 +61,33 @@ export interface TurnPair {
     metadata: Record<string, unknown>;
     createdAt: number;
 }
+/** One step of a turn, flattened for the archive. */
+export interface PortableStep extends TurnStep {
+    turnId: string;
+}
+/** Everything the portable bundle needs, scoped to one soul/user. */
+export interface PortableDump {
+    entities: Entity[];
+    facts: Fact[];
+    threads: TurnThread[];
+    gaps: Gap[];
+    turns: TurnPair[];
+    steps: PortableStep[];
+    corrections: Correction[];
+}
+/** The three layers of the portability contract (spec/vocabulary.v1 §7). */
+export interface PortableBundle {
+    schemaVersion: number;
+    exportedAt: number;
+    soulId: string;
+    userId: string;
+    /** Human-readable: rules, profile, conclusions, promises, entities, open gaps. */
+    summary: string;
+    /** What the model would see right now. */
+    injection: string;
+    /** One JSON object per line, including raw turns — the source of truth. */
+    archive: string[];
+}
 /** What a recall call may narrow by. Everything is optional. */
 export interface TurnPairSpec {
     soulId: string;

package/package.json

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