@ectplsm/relic 0.3.2 → 0.4.0

package/dist/core/sync/persona-hash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Persona hash canonicalization — mikoshi-sync.md 準拠
+ *
+ * 正規化ルール:
+ *  - UTF-8 BOM 除去
+ *  - 改行を \n に統一
+ *  - 末尾 \n を strip
+ *
+ * Canonical payload:
+ *  header \n SOUL.md \n byteLen \n content \n IDENTITY.md \n byteLen \n content
+ *
+ * 出力: "sha256:<64 lowercase hex>"
+ * soul / identity どちらかが欠落なら null
+ */
+export declare function computePersonaHash(soul: string | undefined, identity: string | undefined): string | null;

package/dist/core/sync/persona-hash.js

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import { normalizeText } from "./normalize.js";
+const HEADER = "mikoshi.persona.v1";
+/**
+ * Persona hash canonicalization — mikoshi-sync.md 準拠
+ *
+ * 正規化ルール:
+ *  - UTF-8 BOM 除去
+ *  - 改行を \n に統一
+ *  - 末尾 \n を strip
+ *
+ * Canonical payload:
+ *  header \n SOUL.md \n byteLen \n content \n IDENTITY.md \n byteLen \n content
+ *
+ * 出力: "sha256:<64 lowercase hex>"
+ * soul / identity どちらかが欠落なら null
+ */
+export function computePersonaHash(soul, identity) {
+    if (!soul || !identity)
+        return null;
+    const normSoul = normalizeText(soul, { stripTrailingNewlines: true });
+    const normIdentity = normalizeText(identity, { stripTrailingNewlines: true });
+    const soulBytes = Buffer.byteLength(normSoul, "utf-8");
+    const identityBytes = Buffer.byteLength(normIdentity, "utf-8");
+    const payload = [
+        HEADER,
+        "SOUL.md",
+        String(soulBytes),
+        normSoul,
+        "IDENTITY.md",
+        String(identityBytes),
+        normIdentity,
+    ].join("\n");
+    const hex = createHash("sha256").update(payload, "utf-8").digest("hex");
+    return `sha256:${hex}`;
+}

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

@@ -0,0 +1,44 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+export type ClawPullPersonaFileDiff = "missing" | "same" | "different";
+export interface ClawPullDiff {
+    soulDiff: ClawPullPersonaFileDiff;
+    identityDiff: ClawPullPersonaFileDiff;
+    sourcePath: string;
+    remoteSoul?: string;
+    remoteIdentity?: string;
+}
+export type ClawPullOutcome = "pulled" | "already_synced";
+export interface ClawPullResult {
+    outcome: ClawPullOutcome;
+    engramId: string;
+    engramName: string;
+    sourcePath: string;
+    diff?: ClawPullDiff;
+}
+export declare class ClawPullEngramNotFoundError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class ClawPullWorkspaceNotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class ClawPullPersonaMissingError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class ClawPull {
+    private readonly localRepo;
+    constructor(localRepo: EngramRepository);
+    /**
+     * Phase 1: read workspace + diff. Does not write anything yet.
+     *
+     * Returns an `apply` closure when there are changes to write.
+     */
+    check(agentName: string, options?: {
+        openclawDir?: string;
+    }): Promise<{
+        result: ClawPullResult;
+        apply?: () => Promise<void>;
+    }>;
+}

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

@@ -0,0 +1,117 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { RELIC_FILE_MAP, resolveWorkspacePath } from "../../shared/openclaw.js";
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class ClawPullEngramNotFoundError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" not found locally. Use "relic claw pull" to create or update it.`);
+        this.engramId = engramId;
+        this.name = "ClawPullEngramNotFoundError";
+    }
+}
+export class ClawPullWorkspaceNotFoundError extends Error {
+    path;
+    constructor(path) {
+        super(`Claw workspace not found at ${path}`);
+        this.path = path;
+        this.name = "ClawPullWorkspaceNotFoundError";
+    }
+}
+export class ClawPullPersonaMissingError extends Error {
+    path;
+    constructor(path) {
+        super(`No persona files (SOUL.md, IDENTITY.md) found in ${path}`);
+        this.path = path;
+        this.name = "ClawPullPersonaMissingError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class ClawPull {
+    localRepo;
+    constructor(localRepo) {
+        this.localRepo = localRepo;
+    }
+    /**
+     * Phase 1: read workspace + diff. Does not write anything yet.
+     *
+     * Returns an `apply` closure when there are changes to write.
+     */
+    async check(agentName, options) {
+        const sourcePath = resolveWorkspacePath(agentName, options?.openclawDir);
+        if (!existsSync(sourcePath)) {
+            throw new ClawPullWorkspaceNotFoundError(sourcePath);
+        }
+        // 1. Local Engram must exist
+        const local = await this.localRepo.get(agentName);
+        if (!local) {
+            throw new ClawPullEngramNotFoundError(agentName);
+        }
+        // 2. Read persona files from workspace
+        const remoteSoul = await readOptionalFile(join(sourcePath, RELIC_FILE_MAP.soul));
+        const remoteIdentity = await readOptionalFile(join(sourcePath, RELIC_FILE_MAP.identity));
+        if (!remoteSoul && !remoteIdentity) {
+            throw new ClawPullPersonaMissingError(sourcePath);
+        }
+        // 3. Diff
+        const soulDiff = diffFile(local.files.soul, remoteSoul);
+        const identityDiff = diffFile(local.files.identity, remoteIdentity);
+        if (soulDiff !== "different" && identityDiff !== "different") {
+            return {
+                result: {
+                    outcome: "already_synced",
+                    engramId: agentName,
+                    engramName: local.meta.name,
+                    sourcePath,
+                },
+            };
+        }
+        const diff = {
+            soulDiff,
+            identityDiff,
+            sourcePath,
+            remoteSoul,
+            remoteIdentity,
+        };
+        // 4. Apply closure
+        const apply = async () => {
+            const fresh = await this.localRepo.get(agentName);
+            if (!fresh)
+                throw new ClawPullEngramNotFoundError(agentName);
+            const updatedFiles = { ...fresh.files };
+            if (soulDiff === "different" && remoteSoul)
+                updatedFiles.soul = remoteSoul;
+            if (identityDiff === "different" && remoteIdentity)
+                updatedFiles.identity = remoteIdentity;
+            await this.localRepo.save({
+                meta: { ...fresh.meta, updatedAt: new Date().toISOString() },
+                files: updatedFiles,
+            });
+        };
+        return { result: { outcome: "pulled", engramId: agentName, engramName: local.meta.name, sourcePath, diff }, apply };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readOptionalFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    return readFile(filePath, "utf-8");
+}
+function diffFile(localContent, remoteContent) {
+    if (!remoteContent)
+        return "missing";
+    if (!localContent)
+        return "different";
+    return normalizeContent(localContent) === normalizeContent(remoteContent) ? "same" : "different";
+}
+/** Trim trailing whitespace so minor formatting differences don't cause false diffs. */
+function normalizeContent(content) {
+    return content.trimEnd();
+}

package/dist/core/usecases/extract.d.ts

@@ -32,7 +32,6 @@ export declare class Extract {
     execute(agentName: string, options?: {
         name?: string;
         openclawDir?: string;
-        force?: boolean;
     }): Promise<ExtractResult>;
     private comparePersonaFile;
     private readFiles;

package/dist/core/usecases/extract.js

@@ -55,7 +55,7 @@ export class Extract {
             throw new WorkspaceNotFoundError(sourcePath);
         }
         const existing = await this.repository.get(agentName);
-        if (existing && !options?.force) {
+        if (existing) {
             throw new AlreadyExtractedError(agentName);
         }
         const { files, filesRead } = await this.readFiles(sourcePath);
@@ -63,31 +63,17 @@ export class Extract {
             throw new WorkspaceEmptyError(sourcePath);
         }
         const now = new Date().toISOString();
-        const engram = existing && options?.force
-            ? {
-                meta: {
-                    ...existing.meta,
-                    name: options?.name ?? existing.meta.name,
-                    updatedAt: now,
-                },
-                // Force extract only replaces persona files from Claw.
-                files: {
-                    ...existing.files,
-                    soul: files.soul ?? existing.files.soul,
-                    identity: files.identity ?? existing.files.identity,
-                },
-            }
-            : {
-                meta: {
-                    id: agentName,
-                    name: options?.name ?? agentName,
-                    description: `Extracted from OpenClaw workspace (${agentName})`,
-                    createdAt: now,
-                    updatedAt: now,
-                    tags: ["extracted", "openclaw"],
-                },
-                files,
-            };
+        const engram = {
+            meta: {
+                id: agentName,
+                name: options?.name ?? agentName,
+                description: `Extracted from OpenClaw workspace (${agentName})`,
+                createdAt: now,
+                updatedAt: now,
+                tags: ["extracted", "openclaw"],
+            },
+            files,
+        };
         await this.repository.save(engram);
         return {
             engramId: agentName,
@@ -142,7 +128,7 @@ export class WorkspaceEmptyError extends Error {
 }
 export class AlreadyExtractedError extends Error {
     constructor(id) {
-        super(`Engram "${id}" already exists. Re-run with "--force" option to overwrite local persona files from the Claw workspace.`);
+        super(`Engram "${id}" already exists. Use "relic claw pull" to update it.`);
         this.name = "AlreadyExtractedError";
     }
 }

package/dist/core/usecases/index.d.ts

@@ -6,6 +6,14 @@ export { RefreshSamples, type RefreshSamplesResult, } from "./refresh-samples.js
 export { Inject, InjectEngramNotFoundError, InjectClawDirNotFoundError, InjectWorkspaceNotFoundError, type InjectPersonaFileDiff, type InjectPersonaDiffResult, type InjectResult, } from "./inject.js";
 export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedError, type ExtractPersonaFileDiff, type ExtractPersonaDiffResult, type ExtractResult, } from "./extract.js";
 export { MemoryWrite, MemoryWriteEngramNotFoundError, type MemoryWriteResult, } from "./memory-write.js";
+export { ClawPull, ClawPullEngramNotFoundError, ClawPullWorkspaceNotFoundError, ClawPullPersonaMissingError, type ClawPullResult, type ClawPullDiff, } from "./claw-pull.js";
 export { Sync, SyncOpenclawDirNotFoundError, type SyncTarget, type SyncResult, type SyncInitialResult, } from "./sync.js";
 export { ArchivePending, ArchivePendingEngramNotFoundError, type ArchivePendingResult, } from "./archive-pending.js";
 export { ArchiveCursorUpdate, ArchiveCursorUpdateEngramNotFoundError, type ArchiveCursorUpdateResult, } from "./archive-cursor-update.js";
+export { MikoshiStatus, MikoshiStatusEngramNotFoundError, MikoshiStatusCloudNotFoundError, type MikoshiStatusResult, } from "./mikoshi-status.js";
+export { MikoshiPush, MikoshiPushEngramNotFoundError, MikoshiPushPersonaHashError, MikoshiPushPersonaConflictError, type MikoshiPushResult, type MikoshiPushApplyResult, } from "./mikoshi-push.js";
+export { MikoshiDownload, MikoshiDownloadAlreadyExistsError, MikoshiDownloadCloudNotFoundError, MikoshiDownloadPersonaMissingError, type MikoshiDownloadResult, } from "./mikoshi-download.js";
+export { MikoshiPull, MikoshiPullEngramNotFoundError, MikoshiPullCloudNotFoundError, MikoshiPullPersonaMissingError, type MikoshiPullResult, type MikoshiPullDiff, } from "./mikoshi-pull.js";
+export { MikoshiMemoryPush, MikoshiMemoryPushEngramNotFoundError, MikoshiMemoryPushNoFilesError, MikoshiMemoryPushCloudNotFoundError, type MikoshiMemoryPushResult, } from "./mikoshi-memory-push.js";
+export { MikoshiMemoryPull, MikoshiMemoryPullEngramNotFoundError, MikoshiMemoryPullCloudNotFoundError, MikoshiMemoryPullDecryptError, type MikoshiMemoryPullResult, type MikoshiMemoryPullDiff, } from "./mikoshi-memory-pull.js";
+export { MikoshiMemorySync, MikoshiMemorySyncEngramNotFoundError, MikoshiMemorySyncCloudNotFoundError, MikoshiMemorySyncDecryptError, type MikoshiMemorySyncResult, } from "./mikoshi-memory-sync.js";

package/dist/core/usecases/index.js

@@ -6,6 +6,14 @@ export { RefreshSamples, } from "./refresh-samples.js";
 export { Inject, InjectEngramNotFoundError, InjectClawDirNotFoundError, InjectWorkspaceNotFoundError, } from "./inject.js";
 export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedError, } from "./extract.js";
 export { MemoryWrite, MemoryWriteEngramNotFoundError, } from "./memory-write.js";
+export { ClawPull, ClawPullEngramNotFoundError, ClawPullWorkspaceNotFoundError, ClawPullPersonaMissingError, } from "./claw-pull.js";
 export { Sync, SyncOpenclawDirNotFoundError, } from "./sync.js";
 export { ArchivePending, ArchivePendingEngramNotFoundError, } from "./archive-pending.js";
 export { ArchiveCursorUpdate, ArchiveCursorUpdateEngramNotFoundError, } from "./archive-cursor-update.js";
+export { MikoshiStatus, MikoshiStatusEngramNotFoundError, MikoshiStatusCloudNotFoundError, } from "./mikoshi-status.js";
+export { MikoshiPush, MikoshiPushEngramNotFoundError, MikoshiPushPersonaHashError, MikoshiPushPersonaConflictError, } from "./mikoshi-push.js";
+export { MikoshiDownload, MikoshiDownloadAlreadyExistsError, MikoshiDownloadCloudNotFoundError, MikoshiDownloadPersonaMissingError, } from "./mikoshi-download.js";
+export { MikoshiPull, MikoshiPullEngramNotFoundError, MikoshiPullCloudNotFoundError, MikoshiPullPersonaMissingError, } from "./mikoshi-pull.js";
+export { MikoshiMemoryPush, MikoshiMemoryPushEngramNotFoundError, MikoshiMemoryPushNoFilesError, MikoshiMemoryPushCloudNotFoundError, } from "./mikoshi-memory-push.js";
+export { MikoshiMemoryPull, MikoshiMemoryPullEngramNotFoundError, MikoshiMemoryPullCloudNotFoundError, MikoshiMemoryPullDecryptError, } from "./mikoshi-memory-pull.js";
+export { MikoshiMemorySync, MikoshiMemorySyncEngramNotFoundError, MikoshiMemorySyncCloudNotFoundError, MikoshiMemorySyncDecryptError, } from "./mikoshi-memory-sync.js";

package/dist/core/usecases/inject.d.ts

@@ -4,6 +4,7 @@ export interface InjectPersonaDiffResult {
     engramId: string;
     engramName: string;
     targetPath: string;
+    targetExists: boolean;
     soul: InjectPersonaFileDiff;
     identity: InjectPersonaFileDiff;
     overwriteRequired: boolean;

package/dist/core/usecases/inject.js

@@ -17,6 +17,7 @@ export class Inject {
     async inspectPersona(engramId, options) {
         const { engram, targetPath } = await this.loadInjectTarget(engramId, options);
         const mergeIdentity = options?.mergeIdentity ?? false;
+        const targetExists = existsSync(targetPath);
         const soul = await this.compareTargetFile(join(targetPath, INJECT_FILE_MAP.soul), this.resolveInjectedContent("soul", engram.files, mergeIdentity));
         const identity = mergeIdentity
             ? "skipped"
@@ -25,6 +26,7 @@ export class Inject {
             engramId: engram.meta.id,
             engramName: engram.meta.name,
             targetPath,
+            targetExists,
             soul,
             identity,
             overwriteRequired: soul === "different" || identity === "different",

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

@@ -0,0 +1,29 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+export interface MikoshiCloneResult {
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+}
+export declare class MikoshiCloneAlreadyExistsError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiCloneCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiClonePersonaMissingError extends Error {
+    readonly cloudEngramId: string;
+    constructor(cloudEngramId: string);
+}
+export declare class MikoshiClone {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    /**
+     * Clone a remote Engram from Mikoshi to local.
+     * Fails if the local Engram already exists.
+     */
+    execute(engramId: string): Promise<MikoshiCloneResult>;
+}

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

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class MikoshiCloneAlreadyExistsError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" already exists locally. Use "relic mikoshi pull" to update it.`);
+        this.engramId = engramId;
+        this.name = "MikoshiCloneAlreadyExistsError";
+    }
+}
+export class MikoshiCloneCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiCloneCloudNotFoundError";
+    }
+}
+export class MikoshiClonePersonaMissingError extends Error {
+    cloudEngramId;
+    constructor(cloudEngramId) {
+        super(`Remote Engram "${cloudEngramId}" is missing SOUL.md or IDENTITY.md`);
+        this.cloudEngramId = cloudEngramId;
+        this.name = "MikoshiClonePersonaMissingError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class MikoshiClone {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    /**
+     * Clone a remote Engram from Mikoshi to local.
+     * Fails if the local Engram already exists.
+     */
+    async execute(engramId) {
+        // 1. ローカルに既に存在 → エラー
+        const existing = await this.localRepo.get(engramId);
+        if (existing) {
+            throw new MikoshiCloneAlreadyExistsError(engramId);
+        }
+        // 2. クラウド検索
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiCloneCloudNotFoundError(engramId);
+        // 3. Detail 取得 (persona content 込み)
+        const detail = await this.mikoshi.getEngram(cloudEngram.id);
+        const { soul, identity } = extractPersona(detail);
+        if (!soul || !identity) {
+            throw new MikoshiClonePersonaMissingError(cloudEngram.id);
+        }
+        // 4. ローカルに新規作成
+        const now = new Date().toISOString();
+        await this.localRepo.save({
+            meta: {
+                id: engramId,
+                name: detail.name,
+                description: detail.description ?? undefined,
+                tags: detail.tags,
+                createdAt: now,
+                updatedAt: now,
+            },
+            files: {
+                soul,
+                identity,
+            },
+        });
+        return {
+            engramId,
+            engramName: detail.name,
+            cloudEngramId: cloudEngram.id,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// 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 };
+}

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

@@ -0,0 +1,29 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+export interface MikoshiDownloadResult {
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+}
+export declare class MikoshiDownloadAlreadyExistsError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiDownloadCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiDownloadPersonaMissingError extends Error {
+    readonly cloudEngramId: string;
+    constructor(cloudEngramId: string);
+}
+export declare class MikoshiDownload {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    /**
+     * Download a remote Engram from Mikoshi to local.
+     * Fails if the local Engram already exists.
+     */
+    execute(engramId: string): Promise<MikoshiDownloadResult>;
+}

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

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class MikoshiDownloadAlreadyExistsError extends Error {
+    engramId;
+    constructor(engramId) {
+        super(`Engram "${engramId}" already exists locally. Use "relic mikoshi pull" to update it.`);
+        this.engramId = engramId;
+        this.name = "MikoshiDownloadAlreadyExistsError";
+    }
+}
+export class MikoshiDownloadCloudNotFoundError extends Error {
+    sourceEngramId;
+    constructor(sourceEngramId) {
+        super(`Engram "${sourceEngramId}" not found on Mikoshi`);
+        this.sourceEngramId = sourceEngramId;
+        this.name = "MikoshiDownloadCloudNotFoundError";
+    }
+}
+export class MikoshiDownloadPersonaMissingError extends Error {
+    cloudEngramId;
+    constructor(cloudEngramId) {
+        super(`Remote Engram "${cloudEngramId}" is missing SOUL.md or IDENTITY.md`);
+        this.cloudEngramId = cloudEngramId;
+        this.name = "MikoshiDownloadPersonaMissingError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Usecase
+// ---------------------------------------------------------------------------
+export class MikoshiDownload {
+    localRepo;
+    mikoshi;
+    constructor(localRepo, mikoshi) {
+        this.localRepo = localRepo;
+        this.mikoshi = mikoshi;
+    }
+    /**
+     * Download a remote Engram from Mikoshi to local.
+     * Fails if the local Engram already exists.
+     */
+    async execute(engramId) {
+        // 1. ローカルに既に存在 → エラー
+        const existing = await this.localRepo.get(engramId);
+        if (existing) {
+            throw new MikoshiDownloadAlreadyExistsError(engramId);
+        }
+        // 2. クラウド検索
+        const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        if (!cloudEngram)
+            throw new MikoshiDownloadCloudNotFoundError(engramId);
+        // 3. Detail 取得 (persona content 込み)
+        const detail = await this.mikoshi.getEngram(cloudEngram.id);
+        const { soul, identity } = extractPersona(detail);
+        if (!soul || !identity) {
+            throw new MikoshiDownloadPersonaMissingError(cloudEngram.id);
+        }
+        // 4. ローカルに新規作成
+        const now = new Date().toISOString();
+        await this.localRepo.save({
+            meta: {
+                id: engramId,
+                name: detail.name,
+                description: detail.description ?? undefined,
+                tags: detail.tags,
+                createdAt: now,
+                updatedAt: now,
+            },
+            files: {
+                soul,
+                identity,
+            },
+        });
+        return {
+            engramId,
+            engramName: detail.name,
+            cloudEngramId: cloudEngram.id,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// 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 };
+}

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

@@ -0,0 +1,38 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+import type { MikoshiClient } from "../ports/mikoshi.js";
+export type MikoshiMemoryPullOutcome = "pulled" | "already_synced" | "no_remote_memory";
+export interface MikoshiMemoryPullDiff {
+    added: string[];
+    changed: string[];
+    removed: string[];
+}
+export interface MikoshiMemoryPullResult {
+    outcome: MikoshiMemoryPullOutcome;
+    engramId: string;
+    engramName: string;
+    cloudEngramId: string;
+    diff?: MikoshiMemoryPullDiff;
+}
+export declare class MikoshiMemoryPullEngramNotFoundError extends Error {
+    readonly engramId: string;
+    constructor(engramId: string);
+}
+export declare class MikoshiMemoryPullCloudNotFoundError extends Error {
+    readonly sourceEngramId: string;
+    constructor(sourceEngramId: string);
+}
+export declare class MikoshiMemoryPullDecryptError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class MikoshiMemoryPull {
+    private readonly localRepo;
+    private readonly mikoshi;
+    constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
+    /**
+     * Phase 1: download + decrypt + diff。書き込みはまだしない。
+     */
+    check(engramId: string, passphrase: string): Promise<{
+        result: MikoshiMemoryPullResult;
+        apply?: () => Promise<void>;
+    }>;
+}