@ectplsm/relic 0.3.2 → 0.4.0

package/dist/core/usecases/mikoshi-memory-pull.js

@@ -0,0 +1,142 @@
+import { decryptMemoryBundle } from "../sync/crypto.js";
+import { collectMemoryFiles, memoryFilesToRecord } from "../sync/memory-hash.js";
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class MikoshiMemoryPullEngramNotFoundError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" not found locally`);
+        this.engramId = engramId;
+        this.name = "MikoshiMemoryPullEngramNotFoundError";
+    }
+}
+export class MikoshiMemoryPullCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiMemoryPullCloudNotFoundError";
+    }
+}
+export class MikoshiMemoryPullDecryptError extends Error {
+    constructor(cause) {
+        super("Failed to decrypt memory bundle — wrong passphrase or corrupted data");
+        this.name = "MikoshiMemoryPullDecryptError";
+        this.cause = cause;
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class MikoshiMemoryPull {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    /**
+     * Phase 1: download + decrypt + diff。書き込みはまだしない。
+     */
+    async check(engramId, passphrase) {
+        // 1. ローカル Engram
+        const local = await this.localRepo.get(engramId);
+        if (!local)
+            throw new MikoshiMemoryPullEngramNotFoundError(engramId);
+        // 2. クラウド検索
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiMemoryPullCloudNotFoundError(engramId);
+        // 3. 暗号化バンドルをダウンロード
+        const memoryRes = await this.mikoshi.downloadMemory(cloudEngram.id);
+        if (!memoryRes.hasMemory) {
+            return {
+                result: {
+                    outcome: "no_remote_memory",
+                    engramId,
+                    engramName: local.meta.name,
+                    cloudEngramId: cloudEngram.id,
+                },
+            };
+        }
+        // 4. 復号
+        let remoteFiles;
+        try {
+            remoteFiles = decryptMemoryBundle(memoryRes, passphrase);
+        }
+        catch (err) {
+            throw new MikoshiMemoryPullDecryptError(err);
+        }
+        // 5. ローカルとの差分計算
+        const localEntries = collectMemoryFiles(local.files);
+        const localRecord = memoryFilesToRecord(localEntries);
+        const diff = computeDiff(localRecord, remoteFiles);
+        if (diff.added.length === 0 && diff.changed.length === 0 && diff.removed.length === 0) {
+            return {
+                result: {
+                    outcome: "already_synced",
+                    engramId,
+                    engramName: local.meta.name,
+                    cloudEngramId: cloudEngram.id,
+                },
+            };
+        }
+        // 6. apply クロージャ
+        const apply = async () => {
+            const fresh = await this.localRepo.get(engramId);
+            if (!fresh)
+                throw new MikoshiMemoryPullEngramNotFoundError(engramId);
+            const updatedFiles = { ...fresh.files };
+            // リモートバンドルからファイルを適用
+            updatedFiles.user = remoteFiles["USER.md"] ?? undefined;
+            updatedFiles.memory = remoteFiles["MEMORY.md"] ?? undefined;
+            // memory entries を再構築
+            const newEntries = {};
+            for (const [path, content] of Object.entries(remoteFiles)) {
+                if (path.startsWith("memory/") && path.endsWith(".md")) {
+                    const date = path.replace("memory/", "").replace(".md", "");
+                    newEntries[date] = content;
+                }
+            }
+            updatedFiles.memoryEntries = Object.keys(newEntries).length > 0 ? newEntries : undefined;
+            await this.localRepo.save({
+                meta: { ...fresh.meta, updatedAt: new Date().toISOString() },
+                files: updatedFiles,
+            });
+        };
+        return {
+            result: {
+                outcome: "pulled",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                diff,
+            },
+            apply,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function computeDiff(local, remote) {
+    const allPaths = new Set([...Object.keys(local), ...Object.keys(remote)]);
+    const added = [];
+    const changed = [];
+    const removed = [];
+    for (const path of [...allPaths].sort()) {
+        const inLocal = path in local;
+        const inRemote = path in remote;
+        if (inRemote && !inLocal) {
+            added.push(path);
+        }
+        else if (inLocal && !inRemote) {
+            removed.push(path);
+        }
+        else if (inLocal && inRemote && local[path] !== remote[path]) {
+            changed.push(path);
+        }
+    }
+    return { added, changed, removed };
+}

package/dist/core/usecases/mikoshi-memory-push.d.ts

@@ -0,0 +1,34 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+export type MikoshiMemoryPushOutcome = "uploaded" | "conflict";
+export interface MikoshiMemoryPushResult {
+    outcome: MikoshiMemoryPushOutcome;
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+    /** upload 成功時 */
+    version?: number;
+    memoryContentHash?: string;
+    bundleHash?: string;
+    /** conflict 時のリモート情報 */
+    conflictRemoteHash?: string;
+    conflictRemoteVersion?: number;
+}
+export declare class MikoshiMemoryPushEngramNotFoundError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiMemoryPushNoFilesError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiMemoryPushCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiMemoryPush {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    execute(engramId: string, passphrase: string): Promise<MikoshiMemoryPushResult>;
+}

package/dist/core/usecases/mikoshi-memory-push.js

@@ -0,0 +1,105 @@
+import { MikoshiApiError } from "../ports/mikoshi.js";
+import { collectMemoryFiles, memoryFilesToRecord, computeMemoryContentHash } from "../sync/memory-hash.js";
+import { encryptMemoryBundle } from "../sync/crypto.js";
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class MikoshiMemoryPushEngramNotFoundError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" not found locally`);
+        this.engramId = engramId;
+        this.name = "MikoshiMemoryPushEngramNotFoundError";
+    }
+}
+export class MikoshiMemoryPushNoFilesError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" has no memory files to upload`);
+        this.engramId = engramId;
+        this.name = "MikoshiMemoryPushNoFilesError";
+    }
+}
+export class MikoshiMemoryPushCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi. Push persona first with: relic mikoshi push`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiMemoryPushCloudNotFoundError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class MikoshiMemoryPush {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    async execute(engramId, passphrase) {
+        // 1. ローカル Engram 読み込み
+        const local = await this.localRepo.get(engramId);
+        if (!local)
+            throw new MikoshiMemoryPushEngramNotFoundError(engramId);
+        // 2. Memory ファイル収集
+        const memoryEntries = collectMemoryFiles(local.files);
+        if (memoryEntries.length === 0)
+            throw new MikoshiMemoryPushNoFilesError(engramId);
+        // 3. クラウド検索
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiMemoryPushCloudNotFoundError(engramId);
+        // 4. 暗号化
+        const filesRecord = memoryFilesToRecord(memoryEntries);
+        const bundle = encryptMemoryBundle(filesRecord, passphrase);
+        // 5. ローカル memory content hash
+        const memoryContentHash = computeMemoryContentHash(memoryEntries);
+        if (!memoryContentHash)
+            throw new MikoshiMemoryPushNoFilesError(engramId);
+        // 6. リモートの現在の memory hash を取得
+        const syncStatus = await this.mikoshi.getSyncStatus(cloudEngram.id);
+        const expectedRemoteHash = syncStatus.memory.token?.memoryContentHash ?? null;
+        // 7. アップロード
+        try {
+            const res = await this.mikoshi.uploadMemory(cloudEngram.id, {
+                ciphertext: bundle.ciphertext,
+                cipherAlgorithm: bundle.cipherAlgorithm,
+                cipherNonce: bundle.cipherNonce,
+                wrappedBundleKey: bundle.wrappedBundleKey,
+                wrapAlgorithm: bundle.wrapAlgorithm,
+                kdfAlgorithm: bundle.kdfAlgorithm,
+                kdfSalt: bundle.kdfSalt,
+                kdfParams: bundle.kdfParams,
+                manifest: bundle.manifest,
+                expectedRemoteMemoryContentHash: expectedRemoteHash,
+                memoryContentHash,
+                bundleHash: bundle.bundleHash,
+            });
+            return {
+                outcome: "uploaded",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                version: res.version,
+                memoryContentHash: res.memoryContentHash,
+                bundleHash: res.bundleHash,
+            };
+        }
+        catch (err) {
+            if (err instanceof MikoshiApiError && err.isConflict && err.code === "MEMORY_CONFLICT") {
+                const body = err.body;
+                return {
+                    outcome: "conflict",
+                    engramId,
+                    engramName: local.meta.name,
+                    cloudEngramId: cloudEngram.id,
+                    conflictRemoteHash: body?.currentMemory?.memoryContentHash,
+                    conflictRemoteVersion: body?.currentMemory?.version,
+                };
+            }
+            throw err;
+        }
+    }
+}

package/dist/core/usecases/mikoshi-memory-sync.d.ts

@@ -0,0 +1,36 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+import { type MemoryRecordDiff } from "../sync/memory-merge.js";
+export type MikoshiMemorySyncOutcome = "synced" | "already_synced" | "conflict";
+export interface MikoshiMemorySyncResult {
+    outcome: MikoshiMemorySyncOutcome;
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+    localUpdated?: boolean;
+    remoteUpdated?: boolean;
+    diff?: MemoryRecordDiff;
+    mergedPaths?: string[];
+    version?: number;
+    memoryContentHash?: string;
+    bundleHash?: string;
+    conflictRemoteHash?: string;
+    conflictRemoteVersion?: number;
+}
+export declare class MikoshiMemorySyncEngramNotFoundError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiMemorySyncCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiMemorySyncDecryptError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class MikoshiMemorySync {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    execute(engramId: string, passphrase: string): Promise<MikoshiMemorySyncResult>;
+}

package/dist/core/usecases/mikoshi-memory-sync.js

@@ -0,0 +1,175 @@
+import { MikoshiApiError } from "../ports/mikoshi.js";
+import { decryptMemoryBundle, encryptMemoryBundle } from "../sync/crypto.js";
+import { collectMemoryFiles, computeMemoryContentHash, memoryFilesToRecord } from "../sync/memory-hash.js";
+import { applyMemoryRecordToFiles, computeMemoryRecordDiff, mergeMemoryRecords, } from "../sync/memory-merge.js";
+export class MikoshiMemorySyncEngramNotFoundError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" not found locally`);
+        this.engramId = engramId;
+        this.name = "MikoshiMemorySyncEngramNotFoundError";
+    }
+}
+export class MikoshiMemorySyncCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi. Push persona first with: relic mikoshi push`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiMemorySyncCloudNotFoundError";
+    }
+}
+export class MikoshiMemorySyncDecryptError extends Error {
+    constructor(cause) {
+        super("Failed to decrypt memory bundle — wrong passphrase or corrupted data");
+        this.name = "MikoshiMemorySyncDecryptError";
+        this.cause = cause;
+    }
+}
+export class MikoshiMemorySync {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    async execute(engramId, passphrase) {
+        const local = await this.localRepo.get(engramId);
+        if (!local)
+            throw new MikoshiMemorySyncEngramNotFoundError(engramId);
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiMemorySyncCloudNotFoundError(engramId);
+        const localRecord = memoryFilesToRecord(collectMemoryFiles(local.files));
+        const memoryRes = await this.mikoshi.downloadMemory(cloudEngram.id);
+        let remoteRecord = {};
+        let expectedRemoteHash = null;
+        if (memoryRes.hasMemory) {
+            try {
+                remoteRecord = decryptMemoryBundle(memoryRes, passphrase);
+            }
+            catch (err) {
+                throw new MikoshiMemorySyncDecryptError(err);
+            }
+            expectedRemoteHash = memoryRes.memoryContentHash;
+        }
+        if (Object.keys(localRecord).length === 0 && Object.keys(remoteRecord).length === 0) {
+            return {
+                outcome: "already_synced",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                localUpdated: false,
+                remoteUpdated: false,
+            };
+        }
+        const diff = computeMemoryRecordDiff(localRecord, remoteRecord);
+        const { merged, changedPaths } = mergeMemoryRecords(localRecord, remoteRecord);
+        const localUpdated = !recordsEqual(localRecord, merged);
+        const remoteUpdated = !recordsEqual(remoteRecord, merged);
+        if (!localUpdated && !remoteUpdated) {
+            return {
+                outcome: "already_synced",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                localUpdated: false,
+                remoteUpdated: false,
+                diff,
+                mergedPaths: [],
+            };
+        }
+        if (localUpdated) {
+            await this.localRepo.save({
+                meta: { ...local.meta, updatedAt: new Date().toISOString() },
+                files: applyMemoryRecordToFiles(local.files, merged),
+            });
+        }
+        if (!remoteUpdated) {
+            return {
+                outcome: "synced",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                localUpdated,
+                remoteUpdated: false,
+                diff,
+                mergedPaths: changedPaths,
+            };
+        }
+        const mergedBundle = encryptMemoryBundle(merged, passphrase);
+        const mergedEntries = Object.entries(merged).map(([path, content]) => ({ path, content }));
+        const memoryContentHash = computeMemoryContentHash(mergedEntries);
+        if (!memoryContentHash) {
+            return {
+                outcome: "already_synced",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                localUpdated,
+                remoteUpdated: false,
+                diff,
+                mergedPaths: changedPaths,
+            };
+        }
+        try {
+            const uploaded = await this.mikoshi.uploadMemory(cloudEngram.id, {
+                ciphertext: mergedBundle.ciphertext,
+                cipherAlgorithm: mergedBundle.cipherAlgorithm,
+                cipherNonce: mergedBundle.cipherNonce,
+                wrappedBundleKey: mergedBundle.wrappedBundleKey,
+                wrapAlgorithm: mergedBundle.wrapAlgorithm,
+                kdfAlgorithm: mergedBundle.kdfAlgorithm,
+                kdfSalt: mergedBundle.kdfSalt,
+                kdfParams: mergedBundle.kdfParams,
+                manifest: mergedBundle.manifest,
+                expectedRemoteMemoryContentHash: expectedRemoteHash,
+                memoryContentHash,
+                bundleHash: mergedBundle.bundleHash,
+            });
+            return {
+                outcome: "synced",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                localUpdated,
+                remoteUpdated: true,
+                diff,
+                mergedPaths: changedPaths,
+                version: uploaded.version,
+                memoryContentHash: uploaded.memoryContentHash,
+                bundleHash: uploaded.bundleHash,
+            };
+        }
+        catch (err) {
+            if (err instanceof MikoshiApiError && err.isConflict && err.code === "MEMORY_CONFLICT") {
+                const body = err.body;
+                return {
+                    outcome: "conflict",
+                    engramId,
+                    engramName: local.meta.name,
+                    cloudEngramId: cloudEngram.id,
+                    localUpdated,
+                    remoteUpdated: true,
+                    diff,
+                    mergedPaths: changedPaths,
+                    conflictRemoteHash: body?.currentMemory?.memoryContentHash,
+                    conflictRemoteVersion: body?.currentMemory?.version,
+                };
+            }
+            throw err;
+        }
+    }
+}
+function recordsEqual(a, b) {
+    const aKeys = Object.keys(a).sort();
+    const bKeys = Object.keys(b).sort();
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (let i = 0; i < aKeys.length; i += 1) {
+        if (aKeys[i] !== bKeys[i])
+            return false;
+        if (a[aKeys[i]] !== b[bKeys[i]])
+            return false;
+    }
+    return true;
+}

package/dist/core/usecases/mikoshi-pull.d.ts

@@ -0,0 +1,44 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+export type MikoshiPullOutcome = "pulled" | "already_synced";
+export interface MikoshiPullDiff {
+    soulDiffers: boolean;
+    identityDiffers: boolean;
+    remoteSoul: string;
+    remoteIdentity: string;
+}
+export interface MikoshiPullResult {
+    outcome: MikoshiPullOutcome;
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+    diff?: MikoshiPullDiff;
+}
+export declare class MikoshiPullEngramNotFoundError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiPullCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiPullPersonaMissingError extends Error {
+    readonly cloudEngramId: string;
+    constructor(cloudEngramId: string);
+}
+export declare class MikoshiPull {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    /**
+     * Phase 1: fetch + diff。上書きはまだしない。
+     *
+     * - ローカル未作成 → EngramNotFoundError
+     * - ローカル既存 + 差分なし → already_synced
+     * - ローカル既存 + 差分あり → apply で上書き
+     */
+    check(engramId: string): Promise<{
+        result: MikoshiPullResult;
+        apply?: () => Promise<void>;
+    }>;
+}

package/dist/core/usecases/mikoshi-pull.js

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class MikoshiPullEngramNotFoundError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" not found locally. Use "relic mikoshi pull" to create or update it.`);
+        this.engramId = engramId;
+        this.name = "MikoshiPullEngramNotFoundError";
+    }
+}
+export class MikoshiPullCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiPullCloudNotFoundError";
+    }
+}
+export class MikoshiPullPersonaMissingError extends Error {
+    cloudEngramId;
+    constructor(cloudEngramId) {
+        super(`Remote Engram "${cloudEngramId}" is missing SOUL.md or IDENTITY.md`);
+        this.cloudEngramId = cloudEngramId;
+        this.name = "MikoshiPullPersonaMissingError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class MikoshiPull {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    /**
+     * Phase 1: fetch + diff。上書きはまだしない。
+     *
+     * - ローカル未作成 → EngramNotFoundError
+     * - ローカル既存 + 差分なし → already_synced
+     * - ローカル既存 + 差分あり → apply で上書き
+     */
+    async check(engramId) {
+        // 1. ローカル Engram 必須
+        const local = await this.localRepo.get(engramId);
+        if (!local) {
+            throw new MikoshiPullEngramNotFoundError(engramId);
+        }
+        // 2. クラウド検索
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiPullCloudNotFoundError(engramId);
+        // 3. Detail 取得 (persona content 込み)
+        const detail = await this.mikoshi.getEngram(cloudEngram.id);
+        const { soul: remoteSoul, identity: remoteIdentity } = extractPersona(detail);
+        if (!remoteSoul || !remoteIdentity) {
+            throw new MikoshiPullPersonaMissingError(cloudEngram.id);
+        }
+        // 4. 差分計算 (末尾空白の差異は無視)
+        const soulDiffers = normalizeContent(local.files.soul) !== normalizeContent(remoteSoul);
+        const identityDiffers = normalizeContent(local.files.identity) !== normalizeContent(remoteIdentity);
+        if (!soulDiffers && !identityDiffers) {
+            return {
+                result: {
+                    outcome: "already_synced",
+                    engramId,
+                    engramName: local.meta.name,
+                    cloudEngramId: cloudEngram.id,
+                },
+            };
+        }
+        const diff = {
+            soulDiffers,
+            identityDiffers,
+            remoteSoul,
+            remoteIdentity,
+        };
+        // 5. apply クロージャ
+        const apply = async () => {
+            const fresh = await this.localRepo.get(engramId);
+            if (!fresh)
+                throw new MikoshiPullEngramNotFoundError(engramId);
+            const updatedFiles = { ...fresh.files };
+            if (soulDiffers)
+                updatedFiles.soul = remoteSoul;
+            if (identityDiffers)
+                updatedFiles.identity = remoteIdentity;
+            await this.localRepo.save({
+                meta: { ...fresh.meta, updatedAt: new Date().toISOString() },
+                files: updatedFiles,
+            });
+        };
+        return {
+            result: {
+                outcome: "pulled",
+                engramId,
+                engramName: local.meta.name,
+                cloudEngramId: cloudEngram.id,
+                diff,
+            },
+            apply,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractPersona(detail) {
+    let soul;
+    let identity;
+    for (const f of detail.personaFiles) {
+        if (f.fileType === "SOUL")
+            soul = f.content;
+        if (f.fileType === "IDENTITY")
+            identity = f.content;
+    }
+    return { soul, identity };
+}
+/** Trim trailing whitespace so minor formatting differences don't cause false diffs. */
+function normalizeContent(content) {
+    return (content ?? "").trimEnd();
+}