@ectplsm/relic 0.4.0 → 0.5.1

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

@@ -5,7 +5,21 @@ export interface MikoshiPullDiff {
     soulDiffers: boolean;
     identityDiffers: boolean;
     remoteSoul: string;
+    /**
+     * 書き込み対象の IDENTITY.md。
+     *
+     * リモート IDENTITY.md の Avatar 行を
+     * `avatarUrl` に書き換えた後の最終形で保持する。
+     * 書き換えが発生しなかった場合は remote 原文と同一。
+     */
     remoteIdentity: string;
+    /**
+     * Avatar 行を Mikoshi 上の URL に書き換えたかどうか。
+     *
+     * 書き換えが発生したときのみ URL 文字列がセットされ、
+     * CLI が書き換え結果をユーザーへ通知するのに使う。
+     */
+    rewrittenAvatarUrl?: string;
 }
 export interface MikoshiPullResult {
     outcome: MikoshiPullOutcome;
@@ -41,4 +55,16 @@ export declare class MikoshiPull {
         result: MikoshiPullResult;
         apply?: () => Promise<void>;
     }>;
+    /**
+     * apply 対象となる IDENTITY.md を決定する。
+     *
+     * - リモートに `avatarUrl` が無い → remote をそのまま
+     * - ローカルに Avatar 行の path があり、そのファイルが存在する
+     *   → ローカル画像が source of truth なので remote (path) を採用
+     * - それ以外（ローカル画像なし / ローカル値が URL / path だけあるがファイル欠如）
+     *   → remote IDENTITY の Avatar 行を R2 URL に書き換え
+     *
+     * Avatar 行自体が無ければ rewrite は no-op で remote と等価になる。
+     */
+    private resolveAppliedIdentity;
 }

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

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { parseAvatarRef, resolveAvatarPath, rewriteAvatarValue, } from "../sync/avatar.js";
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -58,9 +60,24 @@ export class MikoshiPull {
         if (!remoteSoul || !remoteIdentity) {
             throw new MikoshiPullPersonaMissingError(cloudEngram.id);
         }
+        // Avatar URL fallback (Phase 3):
+        // ローカルに有効な avatar 画像があれば remote IDENTITY をそのまま採用。
+        // ローカル画像が無い / ローカル値が URL の場合で remote.avatarUrl があれば
+        // apply 対象の IDENTITY を URL 版に差し替える。Avatar 行自体が無ければ
+        // rewriteAvatarValue は no-op なので何も追加しない。
+        const engramDir = this.localRepo.getEngramPath(engramId);
+        const appliedIdentity = this.resolveAppliedIdentity({
+            remoteIdentity,
+            remoteAvatarUrl: detail.avatarUrl,
+            localIdentity: local.files.identity,
+            engramDir,
+        });
+        const rewrittenAvatarUrl = detail.avatarUrl && appliedIdentity !== remoteIdentity
+            ? detail.avatarUrl
+            : undefined;
         // 4. 差分計算 (末尾空白の差異は無視)
         const soulDiffers = normalizeContent(local.files.soul) !== normalizeContent(remoteSoul);
-        const identityDiffers = normalizeContent(local.files.identity) !== normalizeContent(remoteIdentity);
+        const identityDiffers = normalizeContent(local.files.identity) !== normalizeContent(appliedIdentity);
         if (!soulDiffers && !identityDiffers) {
             return {
                 result: {
@@ -75,7 +92,8 @@ export class MikoshiPull {
             soulDiffers,
             identityDiffers,
             remoteSoul,
-            remoteIdentity,
+            remoteIdentity: appliedIdentity,
+            rewrittenAvatarUrl,
         };
         // 5. apply クロージャ
         const apply = async () => {
@@ -86,7 +104,7 @@ export class MikoshiPull {
             if (soulDiffers)
                 updatedFiles.soul = remoteSoul;
             if (identityDiffers)
-                updatedFiles.identity = remoteIdentity;
+                updatedFiles.identity = appliedIdentity;
             await this.localRepo.save({
                 meta: { ...fresh.meta, updatedAt: new Date().toISOString() },
                 files: updatedFiles,
@@ -103,6 +121,32 @@ export class MikoshiPull {
             apply,
         };
     }
+    /**
+     * apply 対象となる IDENTITY.md を決定する。
+     *
+     * - リモートに `avatarUrl` が無い → remote をそのまま
+     * - ローカルに Avatar 行の path があり、そのファイルが存在する
+     *   → ローカル画像が source of truth なので remote (path) を採用
+     * - それ以外（ローカル画像なし / ローカル値が URL / path だけあるがファイル欠如）
+     *   → remote IDENTITY の Avatar 行を R2 URL に書き換え
+     *
+     * Avatar 行自体が無ければ rewrite は no-op で remote と等価になる。
+     */
+    resolveAppliedIdentity(args) {
+        const { remoteIdentity, remoteAvatarUrl, localIdentity, engramDir } = args;
+        if (!remoteAvatarUrl)
+            return remoteIdentity;
+        if (localIdentity && engramDir) {
+            const localRef = parseAvatarRef(localIdentity);
+            if (localRef?.kind === "path") {
+                const resolved = resolveAvatarPath(localRef.value, engramDir);
+                if (existsSync(resolved)) {
+                    return remoteIdentity;
+                }
+            }
+        }
+        return rewriteAvatarValue(remoteIdentity, remoteAvatarUrl);
+    }
 }
 // ---------------------------------------------------------------------------
 // Helpers

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

@@ -1,6 +1,46 @@
 import type { EngramRepository } from "../ports/engram-repository.js";
 import type { MikoshiClient } from "../ports/mikoshi.js";
 export type MikoshiPushOutcome = "create_required" | "push_required" | "already_synced";
+/**
+ * Avatar 差分判定の結果。
+ *
+ * - `no_avatar_field`     : IDENTITY.md に Avatar フィールドが無い
+ * - `no_local_file`       : Avatar フィールドはあるがローカルにファイルが無い（削除は自動化しない）
+ * - `skip`                : ローカルハッシュがリモート (manifest) と一致
+ * - `upload_required`     : 初回 or ハッシュ不一致。アップロード候補
+ */
+export type MikoshiPushAvatarOutcome = "no_avatar_field" | "no_local_file" | "skip" | "upload_required";
+export type MikoshiPushAvatarSkipReason = "remote_avatar_url_matches_identity" | "source_url_unchanged" | "local_file_hash_unchanged";
+export interface MikoshiPushAvatarInfo {
+    outcome: MikoshiPushAvatarOutcome;
+    source?: "file" | "url";
+    /** 解決済みの絶対パス (outcome が no_avatar_field 以外で設定) */
+    localPath?: string;
+    /** IDENTITY.md に書かれていた生のパス値 */
+    rawPath?: string;
+    /** IDENTITY.md に書かれていた外部 URL */
+    sourceUrl?: string;
+    /** `sha256:<hex>` 形式。outcome が "skip" / "upload_required" のときのみ設定 */
+    localHash?: string;
+    /** `skip` のときの理由 */
+    skipReason?: MikoshiPushAvatarSkipReason;
+    /** バリデーション済み MIME。upload_required のときのみ設定 */
+    localMimeType?: string;
+    /** ファイルサイズ (bytes)。upload_required のときのみ設定 */
+    localSize?: number;
+}
+/**
+ * persona hash が不一致で、かつ local と remote の IDENTITY.md の差分が
+ * Avatar 行の値だけだった場合にセットされる。
+ *
+ * pull 側で R2 URL にローカルを書き換えたときに自然に発生するケース。
+ * CLI はこの値を使って「これは Avatar URL の drift ですよ」という
+ * 専用メッセージを出してから push 承認を取り直す。
+ */
+export interface MikoshiPushAvatarDrift {
+    localValue: string;
+    remoteValue: string;
+}
 export interface MikoshiPushResult {
     outcome: MikoshiPushOutcome;
     engramId: string;
@@ -8,11 +48,37 @@ export interface MikoshiPushResult {
     /** クラウド側の canonical ID (existing remote only) */
     cloudEngramId?: string;
     remotePersonaHash?: string | null;
+    /** Avatar 差分情報 (check 時点のスナップショット) */
+    avatar?: MikoshiPushAvatarInfo;
+    /** push_required のとき、IDENTITY.md の diff が Avatar 行だけなら設定 */
+    avatarDrift?: MikoshiPushAvatarDrift;
 }
+export type MikoshiPushAvatarAction = "uploaded" | "skipped" | "failed";
+export type MikoshiPushAvatarFailureStage = "fetch" | "upload";
+export type MikoshiPushAvatarProgressStage = "fetching" | "uploading";
 export interface MikoshiPushApplyResult {
-    action: "created" | "updated";
+    /**
+     * - `created`     : 新規 Engram を作成した（avatar は同じ apply 内で追随）
+     * - `updated`     : persona を上書きした
+     * - `avatar_only` : persona は同期済みだが avatar だけ更新した
+     */
+    action: "created" | "updated" | "avatar_only";
     cloudEngramId: string;
+    /** persona を更新したケースのみ設定 */
     newPersonaHash?: string;
+    /** Avatar アップロードの結果 */
+    avatarAction?: MikoshiPushAvatarAction;
+    /** アップロード成功時のみ設定される R2 上の URL */
+    newAvatarUrl?: string;
+    /** `avatarAction === "failed"` の場合に設定される失敗原因 */
+    avatarError?: Error;
+    /** `avatarAction === "failed"` の場合に設定される失敗段階 */
+    avatarFailureStage?: MikoshiPushAvatarFailureStage;
+    /** `avatarAction === "skipped"` の場合に設定される理由 */
+    avatarSkipReason?: MikoshiPushAvatarSkipReason;
+}
+export interface MikoshiPushApplyOptions {
+    onAvatarProgress?: (stage: MikoshiPushAvatarProgressStage) => void;
 }
 export declare class MikoshiPushEngramNotFoundError extends Error {
     readonly engramId: string;
@@ -27,13 +93,74 @@ export declare class MikoshiPushPersonaConflictError extends Error {
     readonly conflictRemoteHash?: string | undefined;
     constructor(engramId: string, conflictRemoteHash?: string | undefined);
 }
+export declare class MikoshiPushAvatarReadError extends Error {
+    readonly engramId: string;
+    readonly avatarPath: string;
+    readonly cause?: unknown | undefined;
+    constructor(engramId: string, avatarPath: string, cause?: unknown | undefined);
+}
+export declare class MikoshiPushAvatarTooLargeError extends Error {
+    readonly engramId: string;
+    readonly avatarPath: string;
+    readonly actualBytes: number;
+    readonly maxBytes: number;
+    constructor(engramId: string, avatarPath: string, actualBytes: number, maxBytes: number);
+}
+export declare class MikoshiPushAvatarInvalidMimeError extends Error {
+    readonly engramId: string;
+    readonly avatarPath: string;
+    constructor(engramId: string, avatarPath: string);
+}
+export declare class MikoshiPushAvatarHttpError extends Error {
+    readonly engramId: string;
+    readonly avatarUrl: string;
+    constructor(engramId: string, avatarUrl: string);
+}
+export declare class MikoshiPushAvatarPrivateHostError extends Error {
+    readonly engramId: string;
+    readonly avatarUrl: string;
+    constructor(engramId: string, avatarUrl: string);
+}
+export declare class MikoshiPushAvatarFetchError extends Error {
+    readonly engramId: string;
+    readonly avatarUrl: string;
+    readonly cause?: unknown | undefined;
+    constructor(engramId: string, avatarUrl: string, cause?: unknown | undefined);
+}
 export declare class MikoshiPush {
     private readonly localRepo;
     private readonly mikoshi;
     constructor(localRepo: EngramRepository, mikoshi: MikoshiClient);
     check(engramId: string): Promise<{
         result: MikoshiPushResult;
-        apply?: () => Promise<MikoshiPushApplyResult>;
+        apply?: (options?: MikoshiPushApplyOptions) => Promise<MikoshiPushApplyResult>;
     }>;
     execute(engramId: string): Promise<MikoshiPushApplyResult | undefined>;
+    /**
+     * IDENTITY.md の Avatar フィールドを解析し、ローカルファイルを検査して
+     * 差分情報を返す。
+     *
+     * 判定順:
+     * - Avatar フィールドなし → `no_avatar_field`
+     * - URL 値で、remote.avatarUrl と一致 or manifest の source URL と一致 → `skip`
+     * - URL 値で、それ以外 → `upload_required`
+     * - フィールドありだがファイル不在 → `no_local_file`（削除は自動化しない）
+     * - リモートに avatarUrl が **あり** かつ manifest ハッシュと一致 → `skip`
+     * - リモートに avatarUrl が **無い**、または ハッシュ不一致 → `upload_required`
+     *
+     * リモート側の avatarUrl が無ければ manifest ハッシュの一致は意味を持たない。
+     * これは Mikoshi エンドポイント切り替えや、リモート側で手動削除された
+     * ケースで skip で詰まるのを防ぐため。
+     *
+     * MIME 非対応 / サイズ超過 / 読み取り失敗はエラーとして throw する。
+     */
+    private inspectAvatar;
+    /**
+     * 必要なら avatar をアップロードし、成功時に manifest を更新する。
+     *
+     * - `upload_required` 以外 → `avatarAction: "skipped"` で即返す
+     * - upload に失敗しても persona の成功は巻き戻さず、
+     *   `avatarAction: "failed"` と `avatarError` で呼び出し側に知らせる
+     */
+    private applyAvatarUpload;
 }

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

@@ -1,5 +1,8 @@
-import { MikoshiApiError } from "../ports/mikoshi.js";
+import { readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { MikoshiApiError, AVATAR_MAX_BYTES } from "../ports/mikoshi.js";
 import { computePersonaHash } from "../sync/persona-hash.js";
+import { computeAvatarHash, computeAvatarHashFromBytes, detectAvatarMimeType, isAvatarOnlyDrift, fetchAvatarFromUrl, parseAvatarRef, resolveAvatarPath, } from "../sync/avatar.js";
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -29,6 +32,74 @@ export class MikoshiPushPersonaConflictError extends Error {
         this.name = "MikoshiPushPersonaConflictError";
     }
 }
+export class MikoshiPushAvatarReadError extends Error {
+    engramId;
+    avatarPath;
+    cause;
+    constructor(engramId, avatarPath, cause) {
+        super(`Failed to read avatar file for "${engramId}": ${avatarPath}`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.cause = cause;
+        this.name = "MikoshiPushAvatarReadError";
+    }
+}
+export class MikoshiPushAvatarTooLargeError extends Error {
+    engramId;
+    avatarPath;
+    actualBytes;
+    maxBytes;
+    constructor(engramId, avatarPath, actualBytes, maxBytes) {
+        super(`Avatar for "${engramId}" is ${actualBytes} bytes, exceeds limit of ${maxBytes} bytes`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.actualBytes = actualBytes;
+        this.maxBytes = maxBytes;
+        this.name = "MikoshiPushAvatarTooLargeError";
+    }
+}
+export class MikoshiPushAvatarInvalidMimeError extends Error {
+    engramId;
+    avatarPath;
+    constructor(engramId, avatarPath) {
+        super(`Avatar for "${engramId}" has unsupported format: ${avatarPath} (only JPEG, PNG, and WebP are allowed)`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.name = "MikoshiPushAvatarInvalidMimeError";
+    }
+}
+export class MikoshiPushAvatarHttpError extends Error {
+    engramId;
+    avatarUrl;
+    constructor(engramId, avatarUrl) {
+        super(`Avatar URL for "${engramId}" must use HTTPS: ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.name = "MikoshiPushAvatarHttpError";
+    }
+}
+export class MikoshiPushAvatarPrivateHostError extends Error {
+    engramId;
+    avatarUrl;
+    constructor(engramId, avatarUrl) {
+        super(`Avatar URL for "${engramId}" points to a private host: ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.name = "MikoshiPushAvatarPrivateHostError";
+    }
+}
+export class MikoshiPushAvatarFetchError extends Error {
+    engramId;
+    avatarUrl;
+    cause;
+    constructor(engramId, avatarUrl, cause) {
+        super(`Failed to fetch avatar URL for "${engramId}": ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.cause = cause;
+        this.name = "MikoshiPushAvatarFetchError";
+    }
+}
 // ---------------------------------------------------------------------------
 // Usecase
 // ---------------------------------------------------------------------------
@@ -47,7 +118,16 @@ export class MikoshiPush {
         const localHash = computePersonaHash(soul, identity);
         if (!localHash)
             throw new MikoshiPushPersonaHashError(engramId);
+        const engramDir = this.localRepo.getEngramPath(engramId);
         const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        const remoteAvatarUrl = cloudEngram?.avatarUrl ?? null;
+        // 差分検出は localHash だけでなくリモートの avatarUrl 有無も見る。
+        // - リモートに avatar がある → manifest ハッシュと比較 (従来挙動)
+        // - リモートに avatar が無い / リモート Engram 自体無し → manifest に関係なく upload_required
+        //   (Mikoshi エンドポイントを切り替えた場合に skip で詰まるのを防ぐ)
+        const avatarInfo = engramDir
+            ? await this.inspectAvatar(identity, engramDir, local.meta.avatarHash, local.meta.avatarSourceUrl, remoteAvatarUrl, engramId)
+            : { outcome: "no_avatar_field" };
         if (!cloudEngram) {
             return {
                 result: {
@@ -55,8 +135,9 @@ export class MikoshiPush {
                     engramId,
                     engramName: local.meta.name,
                     remotePersonaHash: null,
+                    avatar: avatarInfo,
                 },
-                apply: async () => {
+                apply: async (options) => {
                     const created = await this.mikoshi.createEngram({
                         name: local.meta.name,
                         sourceEngramId: engramId,
@@ -65,9 +146,11 @@ export class MikoshiPush {
                         soul,
                         identity,
                     });
+                    const avatarOutcome = await this.applyAvatarUpload(created.id, engramId, avatarInfo, local.meta, options);
                     return {
                         action: "created",
                         cloudEngramId: created.id,
+                        ...avatarOutcome,
                     };
                 },
             };
@@ -75,6 +158,16 @@ export class MikoshiPush {
         const syncStatus = await this.mikoshi.getSyncStatus(cloudEngram.id);
         const remoteHash = syncStatus.persona.token?.hash ?? null;
         if (remoteHash && localHash === remoteHash) {
+            const apply = avatarInfo.outcome === "upload_required"
+                ? async (options) => {
+                    const avatarOutcome = await this.applyAvatarUpload(cloudEngram.id, engramId, avatarInfo, local.meta, options);
+                    return {
+                        action: "avatar_only",
+                        cloudEngramId: cloudEngram.id,
+                        ...avatarOutcome,
+                    };
+                }
+                : undefined;
             return {
                 result: {
                     outcome: "already_synced",
@@ -82,9 +175,32 @@ export class MikoshiPush {
                     engramName: local.meta.name,
                     cloudEngramId: cloudEngram.id,
                     remotePersonaHash: remoteHash,
+                    avatar: avatarInfo,
                 },
+                apply,
             };
         }
+        // push_required の場合、local と remote の IDENTITY.md の差分が
+        // Avatar 行だけかどうかをベストエフォートで調べる。
+        // pull 側の URL 書き換えで自然に発生する drift を CLI が説明できるようにする。
+        // detail 取得に失敗した場合は黙って諦めて通常の push フローに戻る。
+        let avatarDrift;
+        try {
+            const detail = await this.mikoshi.getEngram(cloudEngram.id);
+            const remoteIdentity = extractRemoteIdentity(detail);
+            if (remoteIdentity) {
+                const drift = isAvatarOnlyDrift(identity, remoteIdentity);
+                if (drift.drift && drift.localValue && drift.remoteValue) {
+                    avatarDrift = {
+                        localValue: drift.localValue,
+                        remoteValue: drift.remoteValue,
+                    };
+                }
+            }
+        }
+        catch {
+            // best effort — detail fetch error は drift 警告を諦めるだけに留める
+        }
         return {
             result: {
                 outcome: "push_required",
@@ -92,20 +208,19 @@ export class MikoshiPush {
                 engramName: local.meta.name,
                 cloudEngramId: cloudEngram.id,
                 remotePersonaHash: remoteHash,
+                avatar: avatarInfo,
+                avatarDrift,
             },
-            apply: async () => {
+            apply: async (options) => {
                 const expectedHash = remoteHash ?? "";
+                let newPersonaHash;
                 try {
                     const updated = await this.mikoshi.updatePersona(cloudEngram.id, {
                         soul,
                         identity,
                         expectedRemotePersonaHash: expectedHash,
                     });
-                    return {
-                        action: "updated",
-                        cloudEngramId: cloudEngram.id,
-                        newPersonaHash: updated.persona.hash,
-                    };
+                    newPersonaHash = updated.persona.hash;
                 }
                 catch (err) {
                     if (err instanceof MikoshiApiError && err.isConflict && err.code === "PERSONA_CONFLICT") {
@@ -114,14 +229,204 @@ export class MikoshiPush {
                     }
                     throw err;
                 }
+                const avatarOutcome = await this.applyAvatarUpload(cloudEngram.id, engramId, avatarInfo, local.meta, options);
+                return {
+                    action: "updated",
+                    cloudEngramId: cloudEngram.id,
+                    newPersonaHash,
+                    ...avatarOutcome,
+                };
             },
         };
     }
     async execute(engramId) {
-        const { result, apply } = await this.check(engramId);
-        if (result.outcome === "already_synced" || !apply) {
+        const { apply } = await this.check(engramId);
+        if (!apply)
             return undefined;
-        }
         return apply();
     }
+    /**
+     * IDENTITY.md の Avatar フィールドを解析し、ローカルファイルを検査して
+     * 差分情報を返す。
+     *
+     * 判定順:
+     * - Avatar フィールドなし → `no_avatar_field`
+     * - URL 値で、remote.avatarUrl と一致 or manifest の source URL と一致 → `skip`
+     * - URL 値で、それ以外 → `upload_required`
+     * - フィールドありだがファイル不在 → `no_local_file`（削除は自動化しない）
+     * - リモートに avatarUrl が **あり** かつ manifest ハッシュと一致 → `skip`
+     * - リモートに avatarUrl が **無い**、または ハッシュ不一致 → `upload_required`
+     *
+     * リモート側の avatarUrl が無ければ manifest ハッシュの一致は意味を持たない。
+     * これは Mikoshi エンドポイント切り替えや、リモート側で手動削除された
+     * ケースで skip で詰まるのを防ぐため。
+     *
+     * MIME 非対応 / サイズ超過 / 読み取り失敗はエラーとして throw する。
+     */
+    async inspectAvatar(identity, engramDir, existingHash, existingSourceUrl, remoteAvatarUrl, engramId) {
+        if (!identity)
+            return { outcome: "no_avatar_field" };
+        const avatarRef = parseAvatarRef(identity);
+        if (!avatarRef)
+            return { outcome: "no_avatar_field" };
+        if (avatarRef.kind === "url") {
+            if (remoteAvatarUrl && avatarRef.value === remoteAvatarUrl) {
+                return {
+                    outcome: "skip",
+                    source: "url",
+                    sourceUrl: avatarRef.value,
+                    skipReason: "remote_avatar_url_matches_identity",
+                };
+            }
+            if (existingSourceUrl && avatarRef.value === existingSourceUrl) {
+                return {
+                    outcome: "skip",
+                    source: "url",
+                    sourceUrl: avatarRef.value,
+                    localHash: existingHash,
+                    skipReason: "source_url_unchanged",
+                };
+            }
+            return {
+                outcome: "upload_required",
+                source: "url",
+                sourceUrl: avatarRef.value,
+            };
+        }
+        const rawPath = avatarRef.value;
+        const localPath = resolveAvatarPath(rawPath, engramDir);
+        if (!existsSync(localPath)) {
+            return { outcome: "no_local_file", source: "file", rawPath, localPath };
+        }
+        const mimeType = detectAvatarMimeType(localPath);
+        if (!mimeType) {
+            throw new MikoshiPushAvatarInvalidMimeError(engramId, localPath);
+        }
+        let size;
+        try {
+            const stats = await stat(localPath);
+            size = stats.size;
+        }
+        catch (err) {
+            throw new MikoshiPushAvatarReadError(engramId, localPath, err);
+        }
+        if (size > AVATAR_MAX_BYTES) {
+            throw new MikoshiPushAvatarTooLargeError(engramId, localPath, size, AVATAR_MAX_BYTES);
+        }
+        let localHash;
+        try {
+            localHash = await computeAvatarHash(localPath);
+        }
+        catch (err) {
+            throw new MikoshiPushAvatarReadError(engramId, localPath, err);
+        }
+        const remoteHasAvatar = remoteAvatarUrl !== null && remoteAvatarUrl !== "";
+        if (remoteHasAvatar && existingHash && localHash === existingHash) {
+            return {
+                outcome: "skip",
+                source: "file",
+                rawPath,
+                localPath,
+                localHash,
+                skipReason: "local_file_hash_unchanged",
+            };
+        }
+        return {
+            outcome: "upload_required",
+            source: "file",
+            rawPath,
+            localPath,
+            localHash,
+            localMimeType: mimeType,
+            localSize: size,
+        };
+    }
+    /**
+     * 必要なら avatar をアップロードし、成功時に manifest を更新する。
+     *
+     * - `upload_required` 以外 → `avatarAction: "skipped"` で即返す
+     * - upload に失敗しても persona の成功は巻き戻さず、
+     *   `avatarAction: "failed"` と `avatarError` で呼び出し側に知らせる
+     */
+    async applyAvatarUpload(cloudEngramId, engramId, info, meta, options) {
+        if (info.outcome !== "upload_required") {
+            return { avatarAction: "skipped", avatarSkipReason: info.skipReason };
+        }
+        try {
+            let bytes;
+            let mimeType;
+            let avatarHash;
+            let avatarSourceUrl;
+            if (info.source === "url") {
+                if (!info.sourceUrl) {
+                    return { avatarAction: "skipped" };
+                }
+                try {
+                    options?.onAvatarProgress?.("fetching");
+                    const fetched = await fetchAvatarFromUrl(info.sourceUrl, AVATAR_MAX_BYTES, 10_000);
+                    bytes = fetched.bytes;
+                    mimeType = fetched.mimeType;
+                    avatarHash = computeAvatarHashFromBytes(bytes);
+                    avatarSourceUrl = info.sourceUrl;
+                }
+                catch (err) {
+                    if (err instanceof Error) {
+                        const message = err.message.toLowerCase();
+                        if (message.includes("must use https")) {
+                            throw new MikoshiPushAvatarHttpError(engramId, info.sourceUrl);
+                        }
+                        if (message.includes("private host")) {
+                            throw new MikoshiPushAvatarPrivateHostError(engramId, info.sourceUrl);
+                        }
+                    }
+                    throw new MikoshiPushAvatarFetchError(engramId, info.sourceUrl, err);
+                }
+            }
+            else {
+                if (!info.localPath || !info.localMimeType || !info.localHash) {
+                    // 型上はありうるが、check() 側の upload_required は常にこれらを満たす
+                    return { avatarAction: "skipped" };
+                }
+                bytes = await readFile(info.localPath);
+                mimeType = info.localMimeType;
+                avatarHash = info.localHash;
+            }
+            options?.onAvatarProgress?.("uploading");
+            const response = await this.mikoshi.uploadEngramAvatar(cloudEngramId, bytes, mimeType);
+            // manifest の avatarHash を更新。updatedAt も合わせて進める。
+            await this.localRepo.updateManifest(engramId, {
+                id: meta.id,
+                createdAt: meta.createdAt,
+                updatedAt: new Date().toISOString(),
+                avatarHash,
+                avatarSourceUrl,
+            });
+            return {
+                avatarAction: "uploaded",
+                newAvatarUrl: response.avatarUrl,
+            };
+        }
+        catch (err) {
+            const failureStage = err instanceof MikoshiPushAvatarFetchError ||
+                err instanceof MikoshiPushAvatarHttpError ||
+                err instanceof MikoshiPushAvatarPrivateHostError
+                ? "fetch"
+                : "upload";
+            return {
+                avatarAction: "failed",
+                avatarError: err instanceof Error ? err : new Error(String(err)),
+                avatarFailureStage: failureStage,
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractRemoteIdentity(detail) {
+    for (const file of detail.personaFiles) {
+        if (file.fileType === "IDENTITY")
+            return file.content;
+    }
+    return undefined;
 }