@ectplsm/relic 0.5.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/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,
         };
     }
 }

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;
 }