@ectplsm/relic 0.4.0 → 0.5.1

package/dist/core/sync/avatar.js

@@ -0,0 +1,352 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { isAbsolute, resolve, extname } from "node:path";
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+/**
+ * Avatar path / hash utilities — engram-avatar-upload プラン準拠
+ *
+ * IDENTITY.md 内の `- **Avatar:** <path>` を検出し、
+ * 絶対パス / Engram 相対パスの両方を解決する。
+ * Phase 4 以降は URL 値も parse するが、既存 pull 互換のため
+ * `parseAvatarPath()` は従来どおり path のみ返す。
+ */
+/** Avatar 行を検出する正規表現 */
+const AVATAR_LINE_PATTERN = /^-\s+\*\*Avatar:\*\*\s*(.+)$/m;
+/**
+ * 分割用の正規表現。
+ *
+ * group 1: `- **Avatar:** ` までの prefix（末尾の空白含む）
+ * group 2: Avatar の値部分（行末まで）
+ */
+const AVATAR_LINE_PATTERN_SPLIT = /^(-\s+\*\*Avatar:\*\*\s*)(.+)$/m;
+/** クライアントが許可する MIME タイプ */
+const SUPPORTED_MIME = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+const SUPPORTED_MIME_SET = new Set(Object.values(SUPPORTED_MIME));
+const MAX_REDIRECTS = 3;
+/**
+ * IDENTITY.md から Avatar フィールドの生の値を抽出する。
+ *
+ * - マッチしなければ null
+ * - 値が URL（http://, https://）の場合は Mikoshi 管理外として null
+ * - 空白のみの値も null として扱う
+ */
+export function parseAvatarPath(identity) {
+    const ref = parseAvatarRef(identity);
+    return ref?.kind === "path" ? ref.value : null;
+}
+/**
+ * IDENTITY.md から Avatar フィールドの参照先を抽出する。
+ *
+ * - マッチしなければ null
+ * - 空白のみの値も null
+ * - `http(s)://` は URL として返す
+ * - それ以外は path として返す
+ */
+export function parseAvatarRef(identity) {
+    const match = identity.match(AVATAR_LINE_PATTERN);
+    if (!match)
+        return null;
+    const raw = match[1].trim();
+    if (raw.length === 0)
+        return null;
+    if (/^https?:\/\//i.test(raw)) {
+        return { kind: "url", value: raw };
+    }
+    return { kind: "path", value: raw };
+}
+/**
+ * Avatar パスを絶対パスに解決する。
+ *
+ * - 絶対パス → そのまま
+ * - 相対パス → Engram ディレクトリ基準で resolve
+ */
+export function resolveAvatarPath(rawPath, engramDir) {
+    return isAbsolute(rawPath) ? rawPath : resolve(engramDir, rawPath);
+}
+/**
+ * ファイル内容の SHA-256 ハッシュを計算する。
+ *
+ * 出力形式: "sha256:<64 lowercase hex>"
+ *
+ * ストリーム処理なので 2MB 制限を超える巨大ファイルでも OOM しない。
+ */
+export function computeAvatarHash(filePath) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(filePath);
+        stream.on("error", rejectPromise);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolvePromise(`sha256:${hash.digest("hex")}`));
+    });
+}
+export function computeAvatarHashFromBytes(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * 拡張子から MIME タイプを判定する。
+ *
+ * 許可フォーマット: JPEG, PNG, WebP
+ * 対応外なら null（呼び出し側でエラーにする）
+ *
+ * バイナリ判定は Mikoshi 側の sharp に任せる方針。
+ * クライアントは軽量な事前バリデーションのみ。
+ */
+export function detectAvatarMimeType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return SUPPORTED_MIME[ext] ?? null;
+}
+/**
+ * レスポンス header / magic number の両方から MIME を判定する。
+ *
+ * 両方あって不一致なら null を返す。
+ */
+export function detectAvatarMimeTypeFromBytes(bytes, headerMimeType) {
+    const normalizedHeader = normalizeHeaderMimeType(headerMimeType);
+    const magicMime = detectAvatarMimeTypeByMagic(bytes);
+    if (normalizedHeader && magicMime && normalizedHeader !== magicMime) {
+        return null;
+    }
+    return magicMime ?? normalizedHeader ?? null;
+}
+export function isHttpsUrl(raw) {
+    try {
+        return new URL(raw).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * ホストが private / loopback / link-local なら true。
+ *
+ * hostname の場合は DNS lookup して、返ってきた全アドレスを検査する。
+ * DNS rebinding の完全対策ではない。事故防止用。
+ */
+export async function isPrivateHost(url) {
+    const hostname = url.hostname;
+    if (!hostname)
+        return true;
+    if (isIpAddressPrivate(hostname)) {
+        return true;
+    }
+    if (isIP(hostname) !== 0) {
+        return false;
+    }
+    try {
+        const addresses = await lookup(hostname, { all: true });
+        if (addresses.length === 0)
+            return true;
+        return addresses.some((entry) => isIpAddressPrivate(entry.address));
+    }
+    catch {
+        return true;
+    }
+}
+export async function fetchAvatarFromUrl(url, maxBytes, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let currentUrl = url;
+        for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+            if (!isHttpsUrl(currentUrl)) {
+                throw new Error(`Avatar URL must use HTTPS: ${currentUrl}`);
+            }
+            const parsed = new URL(currentUrl);
+            if (await isPrivateHost(parsed)) {
+                throw new Error(`Avatar URL points to a private host: ${currentUrl}`);
+            }
+            const response = await fetch(parsed, {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    Accept: "image/jpeg, image/png, image/webp",
+                },
+            });
+            if (isRedirectResponse(response.status)) {
+                const location = response.headers.get("location");
+                if (!location) {
+                    throw new Error(`Avatar URL redirected without Location header: ${currentUrl}`);
+                }
+                if (redirectCount === MAX_REDIRECTS) {
+                    throw new Error(`Avatar URL exceeded redirect limit (${MAX_REDIRECTS})`);
+                }
+                currentUrl = new URL(location, parsed).toString();
+                continue;
+            }
+            if (!response.ok) {
+                throw new Error(`Avatar URL fetch failed with HTTP ${response.status}`);
+            }
+            const contentLength = response.headers.get("content-length");
+            if (contentLength) {
+                const parsedLength = Number.parseInt(contentLength, 10);
+                if (Number.isFinite(parsedLength) && parsedLength > maxBytes) {
+                    throw new Error(`Avatar URL content-length exceeds ${maxBytes} bytes (actual: ${parsedLength})`);
+                }
+            }
+            const bytes = await readResponseBody(response, maxBytes);
+            const mimeType = detectAvatarMimeTypeFromBytes(bytes, response.headers.get("content-type"));
+            if (!mimeType) {
+                throw new Error("Avatar URL returned an unsupported image format");
+            }
+            return { bytes, mimeType, finalUrl: currentUrl };
+        }
+        throw new Error(`Avatar URL exceeded redirect limit (${MAX_REDIRECTS})`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * IDENTITY.md を Avatar 行の値を境に前後分離する。
+ *
+ * 書き換えと drift 検出の両方で使う基本操作。
+ */
+export function splitAroundAvatar(identity) {
+    const match = AVATAR_LINE_PATTERN_SPLIT.exec(identity);
+    if (!match) {
+        return { before: identity, rawValue: null, after: "" };
+    }
+    const prefix = match[1];
+    const value = match[2];
+    const valueStart = match.index + prefix.length;
+    const valueEnd = valueStart + value.length;
+    return {
+        before: identity.slice(0, valueStart),
+        rawValue: value,
+        after: identity.slice(valueEnd),
+    };
+}
+/**
+ * IDENTITY.md の Avatar 行の値だけを差し替えて新しい文字列を返す。
+ *
+ * Avatar 行が存在しない場合は元の identity をそのまま返す
+ * （新しい Avatar 行は挿入しない — 保守的な挙動）。
+ */
+export function rewriteAvatarValue(identity, newValue) {
+    const split = splitAroundAvatar(identity);
+    if (split.rawValue === null)
+        return identity;
+    return split.before + newValue + split.after;
+}
+/**
+ * 2つの IDENTITY.md の差分が Avatar 行の値だけかどうかを判定する。
+ *
+ * 判定条件:
+ * - 両方に Avatar 行が存在する
+ * - Avatar 行の前後 (`before` / `after`) が完全一致
+ * - Avatar 行の値だけ異なる
+ *
+ * PATH 前後の format 揺れ（改行数・空白数など）は
+ * `before` / `after` の文字列一致にそのまま反映されるため、
+ * 揺れがあれば avatar-only drift とは判定されない（false positive を避ける）。
+ */
+export function isAvatarOnlyDrift(local, remote) {
+    const a = splitAroundAvatar(local);
+    const b = splitAroundAvatar(remote);
+    if (a.rawValue === null || b.rawValue === null) {
+        return { drift: false, localValue: null, remoteValue: null };
+    }
+    if (a.before === b.before && a.after === b.after && a.rawValue !== b.rawValue) {
+        return { drift: true, localValue: a.rawValue, remoteValue: b.rawValue };
+    }
+    return { drift: false, localValue: null, remoteValue: null };
+}
+function normalizeHeaderMimeType(headerMimeType) {
+    if (!headerMimeType)
+        return null;
+    const mimeType = headerMimeType.split(";")[0]?.trim().toLowerCase();
+    return mimeType && SUPPORTED_MIME_SET.has(mimeType) ? mimeType : null;
+}
+function detectAvatarMimeTypeByMagic(bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (bytes.length >= 8 &&
+        bytes[0] === 0x89 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x4e &&
+        bytes[3] === 0x47 &&
+        bytes[4] === 0x0d &&
+        bytes[5] === 0x0a &&
+        bytes[6] === 0x1a &&
+        bytes[7] === 0x0a) {
+        return "image/png";
+    }
+    if (bytes.length >= 12 &&
+        bytes[0] === 0x52 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x46 &&
+        bytes[8] === 0x57 &&
+        bytes[9] === 0x45 &&
+        bytes[10] === 0x42 &&
+        bytes[11] === 0x50) {
+        return "image/webp";
+    }
+    return null;
+}
+async function readResponseBody(response, maxBytes) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error("Avatar URL response body is empty");
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        totalBytes += value.byteLength;
+        if (totalBytes > maxBytes) {
+            throw new Error(`Avatar URL body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}
+function isRedirectResponse(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function isIpAddressPrivate(value) {
+    const family = isIP(value);
+    if (family === 4)
+        return isPrivateIpv4(value);
+    if (family === 6)
+        return isPrivateIpv6(value);
+    return false;
+}
+function isPrivateIpv4(value) {
+    const parts = value.split(".").map((part) => Number.parseInt(part, 10));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === 10)
+        return true;
+    if (a === 127)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+}
+function isPrivateIpv6(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === "::1")
+        return true;
+    if (normalized.startsWith("fc") || normalized.startsWith("fd"))
+        return true;
+    return false;
+}

package/dist/core/usecases/archive-cursor-update.d.ts

@@ -16,6 +16,12 @@ export declare class ArchiveCursorUpdate {
     execute(engramId: string, count: number): Promise<ArchiveCursorUpdateResult>;
     private readCursor;
 }
+export declare class ArchiveCursorAdvanceOverflowError extends Error {
+    readonly id: string;
+    readonly requestedCount: number;
+    readonly availablePending: number;
+    constructor(id: string, requestedCount: number, availablePending: number);
+}
 export declare class ArchiveCursorUpdateEngramNotFoundError extends Error {
     constructor(id: string);
 }

package/dist/core/usecases/archive-cursor-update.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
+import { ArchivePending } from "./archive-pending.js";
 /**
  * ArchiveCursorUpdate — archive.cursor を指定件数分だけ進める
  *
@@ -19,6 +20,11 @@ export class ArchiveCursorUpdate {
         }
         const cursorPath = join(engramDir, "archive.cursor");
         const previousCursor = await this.readCursor(cursorPath);
+        const archivePending = new ArchivePending(this.engramsPath);
+        const pending = await archivePending.execute(engramId, Number.MAX_SAFE_INTEGER);
+        if (count > pending.entries.length) {
+            throw new ArchiveCursorAdvanceOverflowError(engramId, count, pending.entries.length);
+        }
         const newCursor = previousCursor + count;
         await writeFile(cursorPath, String(newCursor), "utf-8");
         return { previousCursor, newCursor };
@@ -36,6 +42,18 @@ export class ArchiveCursorUpdate {
         }
     }
 }
+export class ArchiveCursorAdvanceOverflowError extends Error {
+    id;
+    requestedCount;
+    availablePending;
+    constructor(id, requestedCount, availablePending) {
+        super(`Engram "${id}" cursor advance overflow (${requestedCount} > ${availablePending}). Refusing to move archive.cursor.`);
+        this.id = id;
+        this.requestedCount = requestedCount;
+        this.availablePending = availablePending;
+        this.name = "ArchiveCursorAdvanceOverflowError";
+    }
+}
 export class ArchiveCursorUpdateEngramNotFoundError extends Error {
     constructor(id) {
         super(`Engram "${id}" archive not found`);

package/dist/core/usecases/archive-pending.d.ts

@@ -1,6 +1,16 @@
+export interface ArchivePendingEntry {
+    /** archive.md 先頭行から抽出した日付 */
+    date: string | null;
+    /** archive.md 先頭行の summary 部分 */
+    summary: string | null;
+    /** エントリ全文 */
+    raw: string;
+    /** 先頭行を除いた本文 */
+    body: string;
+}
 export interface ArchivePendingResult {
     /** 未蒸留エントリ（cursor以降） */
-    entries: string[];
+    entries: ArchivePendingEntry[];
     /** 現在のcursor位置 */
     cursor: number;
     /** archive内の総エントリ数 */
@@ -8,6 +18,12 @@ export interface ArchivePendingResult {
     /** 今回返さなかった残りの未蒸留エントリ数 */
     remaining: number;
 }
+export declare class ArchiveCursorCorruptedError extends Error {
+    readonly id: string;
+    readonly cursor: number;
+    readonly total: number;
+    constructor(id: string, cursor: number, total: number);
+}
 /**
  * ArchivePending — archive.md の未蒸留エントリを取得する
  *
@@ -20,6 +36,7 @@ export declare class ArchivePending {
     execute(engramId: string, limit?: number): Promise<ArchivePendingResult>;
     private readCursor;
 }
+export declare function parseArchiveEntry(raw: string): ArchivePendingEntry;
 export declare class ArchivePendingEngramNotFoundError extends Error {
     constructor(id: string);
 }

package/dist/core/usecases/archive-pending.js

@@ -2,7 +2,20 @@ import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 const ENTRY_SEPARATOR = /\n---\n/;
-const DEFAULT_LIMIT = 30;
+const DEFAULT_LIMIT = 100;
+const ENTRY_HEADER_PATTERN = /^(\d{4}-\d{2}-\d{2}) \| ?(.*)$/;
+export class ArchiveCursorCorruptedError extends Error {
+    id;
+    cursor;
+    total;
+    constructor(id, cursor, total) {
+        super(`Engram "${id}" archive cursor is invalid (${cursor} > ${total}). Repair archive.cursor before distilling.`);
+        this.id = id;
+        this.cursor = cursor;
+        this.total = total;
+        this.name = "ArchiveCursorCorruptedError";
+    }
+}
 /**
  * ArchivePending — archive.md の未蒸留エントリを取得する
  *
@@ -29,11 +42,14 @@ export class ArchivePending {
             .map((e) => e.trim())
             .filter((e) => e.length > 0);
         const cursor = await this.readCursor(engramDir);
+        if (cursor > allEntries.length) {
+            throw new ArchiveCursorCorruptedError(engramId, cursor, allEntries.length);
+        }
         const pendingEntries = allEntries.slice(cursor);
         const effectiveLimit = limit ?? DEFAULT_LIMIT;
         const returned = pendingEntries.slice(0, effectiveLimit);
         return {
-            entries: returned,
+            entries: returned.map(parseArchiveEntry),
             cursor,
             total: allEntries.length,
             remaining: pendingEntries.length - returned.length,
@@ -53,6 +69,25 @@ export class ArchivePending {
         }
     }
 }
+export function parseArchiveEntry(raw) {
+    const trimmed = raw.trim();
+    const [header = "", ...rest] = trimmed.split("\n");
+    const match = header.match(ENTRY_HEADER_PATTERN);
+    if (!match) {
+        return {
+            date: null,
+            summary: null,
+            raw: trimmed,
+            body: trimmed,
+        };
+    }
+    return {
+        date: match[1],
+        summary: match[2] || null,
+        raw: trimmed,
+        body: rest.join("\n").trim(),
+    };
+}
 export class ArchivePendingEngramNotFoundError extends Error {
     constructor(id) {
         super(`Engram "${id}" archive not found`);

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

@@ -5,11 +5,11 @@ export { MigrateEngrams, type MigrateEngramsResult, } from "./migrate-engrams.js
 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 { MemoryWrite, MemoryWriteEngramNotFoundError, type MemoryWriteBatchItem, 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 { ArchivePending, ArchiveCursorCorruptedError, ArchivePendingEngramNotFoundError, type ArchivePendingEntry, type ArchivePendingResult, } from "./archive-pending.js";
+export { ArchiveCursorUpdate, ArchiveCursorAdvanceOverflowError, 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";

package/dist/core/usecases/index.js

@@ -8,8 +8,8 @@ export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedE
 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 { ArchivePending, ArchiveCursorCorruptedError, ArchivePendingEngramNotFoundError, } from "./archive-pending.js";
+export { ArchiveCursorUpdate, ArchiveCursorAdvanceOverflowError, 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";

package/dist/core/usecases/memory-write.d.ts

@@ -4,6 +4,10 @@ export interface MemoryWriteResult {
     appended: boolean;
     path: string;
 }
+export interface MemoryWriteBatchItem {
+    date: string;
+    content: string;
+}
 /**
  * MemoryWrite — Engramのメモリエントリに追記する
  *
@@ -14,6 +18,7 @@ export declare class MemoryWrite {
     private readonly engramsPath;
     constructor(engramsPath: string);
     execute(engramId: string, content: string, date?: string): Promise<MemoryWriteResult>;
+    executeBatch(engramId: string, writes: MemoryWriteBatchItem[]): Promise<MemoryWriteResult[]>;
 }
 export declare class MemoryWriteEngramNotFoundError extends Error {
     constructor(id: string);

package/dist/core/usecases/memory-write.js

@@ -14,29 +14,39 @@ export class MemoryWrite {
     }
     async execute(engramId, content, date) {
         const resolvedDate = date ?? new Date().toISOString().split("T")[0];
+        const [result] = await this.executeBatch(engramId, [
+            { date: resolvedDate, content },
+        ]);
+        return result;
+    }
+    async executeBatch(engramId, writes) {
         const engramDir = join(this.engramsPath, engramId);
         if (!existsSync(engramDir)) {
             throw new MemoryWriteEngramNotFoundError(engramId);
         }
         const memoryDir = join(engramDir, "memory");
         await mkdir(memoryDir, { recursive: true });
-        const filePath = join(memoryDir, `${resolvedDate}.md`);
-        let appended = false;
-        if (existsSync(filePath)) {
-            const existing = await readFile(filePath, "utf-8");
-            const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-            await writeFile(filePath, existing + separator + content + "\n", "utf-8");
-            appended = true;
-        }
-        else {
-            await writeFile(filePath, content + "\n", "utf-8");
+        const results = [];
+        for (const write of writes) {
+            const filePath = join(memoryDir, `${write.date}.md`);
+            let appended = false;
+            if (existsSync(filePath)) {
+                const existing = await readFile(filePath, "utf-8");
+                const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+                await writeFile(filePath, existing + separator + write.content + "\n", "utf-8");
+                appended = true;
+            }
+            else {
+                await writeFile(filePath, write.content + "\n", "utf-8");
+            }
+            results.push({
+                engramId,
+                date: write.date,
+                appended,
+                path: filePath,
+            });
         }
-        return {
-            engramId,
-            date: resolvedDate,
-            appended,
-            path: filePath,
-        };
+        return results;
     }
 }
 export class MemoryWriteEngramNotFoundError extends Error {

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

@@ -4,6 +4,11 @@ export interface MikoshiDownloadResult {
     engramId: string;
     engramName: string;
     cloudEngramId: string;
+    /**
+     * リモートに `avatarUrl` があり、ローカルに書き込んだ IDENTITY.md の
+     * Avatar 行をその URL で書き換えた場合にセットされる。
+     */
+    rewrittenAvatarUrl?: string;
 }
 export declare class MikoshiDownloadAlreadyExistsError extends Error {
     readonly engramId: string;

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

@@ -1,3 +1,4 @@
+import { rewriteAvatarValue } from "../sync/avatar.js";
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -55,6 +56,20 @@ export class MikoshiDownload {
         if (!soul || !identity) {
             throw new MikoshiDownloadPersonaMissingError(cloudEngram.id);
         }
+        // Avatar URL fallback (Phase 3):
+        // リモートに avatarUrl があれば、IDENTITY.md の Avatar 行をその URL に
+        // 書き換えてから保存する。新規ダウンロード時はローカルに画像が無いので
+        // URL 版のほうが Construct / Shell で表示できて実用的。
+        // Avatar 行が無ければ rewriteAvatarValue は no-op なので何も起こらない。
+        let identityToWrite = identity;
+        let rewrittenAvatarUrl;
+        if (detail.avatarUrl) {
+            const next = rewriteAvatarValue(identity, detail.avatarUrl);
+            if (next !== identity) {
+                identityToWrite = next;
+                rewrittenAvatarUrl = detail.avatarUrl;
+            }
+        }
         // 4. ローカルに新規作成
         const now = new Date().toISOString();
         await this.localRepo.save({
@@ -68,13 +83,14 @@ export class MikoshiDownload {
             },
             files: {
                 soul,
-                identity,
+                identity: identityToWrite,
             },
         });
         return {
             engramId,
             engramName: detail.name,
             cloudEngramId: cloudEngram.id,
+            rewrittenAvatarUrl,
         };
     }
 }