@ectplsm/relic 0.5.0 → 0.5.2

package/README.md

@@ -21,6 +21,7 @@ Relic manages AI **Engrams** (memory + personality) and injects them across codi
 - [Engram Management](#engram-management)
 - [Cloud Storage and Sharing](#cloud-storage-and-sharing)
 - [Configuration](#configuration)
+- [Roadmap](#roadmap)
 
 ## Requirements
 
@@ -188,6 +189,8 @@ For LLM-assisted creation, persona authoring, template examples, and deletion ru
 
 Relic can push plaintext persona files and (end-to-end) encrypted memory files to [Mikoshi](https://mikoshi.ectplsm.com), so you can keep Engrams in the cloud and move them across machines without turning Mikoshi into your authoring source of truth.
 
+This includes avatar-aware persona push/pull: local image paths and external `https://` avatar URLs can be snapshotted into Mikoshi-managed storage during `relic mikoshi push`.
+
 For setup, API key configuration, persona push/pull, encrypted memory sync, and the recommended command flow, see [docs/mikoshi.md](docs/mikoshi.md).
 
 ## Configuration
@@ -197,6 +200,14 @@ Use `relic config` to manage the default Engram, Claw path, memory window, and d
 
 For command examples and precedence rules, see [docs/configuration.md](docs/configuration.md).
 
+## Roadmap
+
+Upcoming milestones that shape where Relic is heading:
+
+- **Tighter OpenClaw integration** — deeper interop with OpenClaw and other Claw-based frameworks, beyond the current push / pull / sync surface.
+- **Structured memory decomposition** — break `MEMORY.md` down into episodic, semantic, and procedural memory so the Construct can recall the right kind of knowledge at the right time.
+- **Memory Wiki on llm-wiki** — build a navigable memory wiki on top of [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), turning long-term memory into a browsable, linkable knowledge base instead of flat Markdown.
+
 ## License
 
 [MIT](./LICENCE.md)

package/dist/adapters/local/local-engram-repository.d.ts

@@ -1,4 +1,4 @@
-import type { Engram, EngramMeta } from "../../core/entities/engram.js";
+import type { Engram, EngramManifest, EngramMeta } from "../../core/entities/engram.js";
 import type { EngramRepository } from "../../core/ports/engram-repository.js";
 /**
  * LocalEngramRepository — ローカルファイルシステム上の
@@ -24,6 +24,8 @@ export declare class LocalEngramRepository implements EngramRepository {
     get(id: string): Promise<Engram | null>;
     save(engram: Engram): Promise<void>;
     delete(id: string): Promise<void>;
+    getEngramPath(id: string): string;
+    updateManifest(id: string, manifest: EngramManifest): Promise<void>;
     copyArchiveFiles(fromId: string, toId: string): Promise<boolean>;
     private readMeta;
     private toProfile;

package/dist/adapters/local/local-engram-repository.js

@@ -91,6 +91,27 @@ export class LocalEngramRepository {
             await rm(engramDir, { recursive: true });
         }
     }
+    getEngramPath(id) {
+        return join(this.basePath, id);
+    }
+    async updateManifest(id, manifest) {
+        const engramDir = join(this.basePath, id);
+        if (!existsSync(engramDir))
+            return;
+        const manifestPath = join(engramDir, MANIFEST_FILE);
+        const payload = {
+            id: manifest.id,
+            createdAt: manifest.createdAt,
+            updatedAt: manifest.updatedAt,
+            ...(manifest.avatarHash !== undefined
+                ? { avatarHash: manifest.avatarHash }
+                : {}),
+            ...(manifest.avatarSourceUrl !== undefined
+                ? { avatarSourceUrl: manifest.avatarSourceUrl }
+                : {}),
+        };
+        await writeFile(manifestPath, JSON.stringify(payload, null, 2), "utf-8");
+    }
     async copyArchiveFiles(fromId, toId) {
         const ARCHIVE_FILES = ["archive.md", "archive.cursor"];
         const fromDir = join(this.basePath, fromId);
@@ -148,6 +169,10 @@ export class LocalEngramRepository {
             id: meta.id,
             createdAt: meta.createdAt,
             updatedAt: meta.updatedAt,
+            ...(meta.avatarHash !== undefined ? { avatarHash: meta.avatarHash } : {}),
+            ...(meta.avatarSourceUrl !== undefined
+                ? { avatarSourceUrl: meta.avatarSourceUrl }
+                : {}),
         };
     }
     async writeMetaFiles(engramDir, meta) {

package/dist/adapters/mikoshi/client.d.ts

@@ -1,4 +1,4 @@
-import { type MikoshiClient, type MikoshiEngram, type MikoshiEngramDetail, type CreateEngramInput, type CreateEngramResponse, type SyncStatusResponse, type UpdatePersonaInput, type UpdatePersonaResponse, type UploadMemoryInput, type UploadMemoryResponse, type DownloadMemoryResponse } from "../../core/ports/mikoshi.js";
+import { type MikoshiClient, type MikoshiEngram, type MikoshiEngramDetail, type CreateEngramInput, type CreateEngramResponse, type SyncStatusResponse, type UpdatePersonaInput, type UpdatePersonaResponse, type UploadMemoryInput, type UploadMemoryResponse, type DownloadMemoryResponse, type UploadEngramAvatarResponse, type DeleteEngramAvatarResponse } from "../../core/ports/mikoshi.js";
 /**
  * MikoshiApiClient — Mikoshi REST API v1 の adapter 実装
  *
@@ -17,5 +17,7 @@ export declare class MikoshiApiClient implements MikoshiClient {
     updatePersona(engramId: string, input: UpdatePersonaInput): Promise<UpdatePersonaResponse>;
     uploadMemory(engramId: string, input: UploadMemoryInput): Promise<UploadMemoryResponse>;
     downloadMemory(engramId: string): Promise<DownloadMemoryResponse>;
+    uploadEngramAvatar(engramId: string, data: Buffer, mimeType: string): Promise<UploadEngramAvatarResponse>;
+    deleteEngramAvatar(engramId: string): Promise<DeleteEngramAvatarResponse>;
     private request;
 }

package/dist/adapters/mikoshi/client.js

@@ -1,4 +1,4 @@
-import { MikoshiApiError, MikoshiEngramSchema, MikoshiEngramDetailSchema, CreateEngramResponseSchema, SyncStatusResponseSchema, UpdatePersonaResponseSchema, UploadMemoryResponseSchema, DownloadMemoryResponseSchema, } from "../../core/ports/mikoshi.js";
+import { MikoshiApiError, MikoshiEngramSchema, MikoshiEngramDetailSchema, CreateEngramResponseSchema, SyncStatusResponseSchema, UpdatePersonaResponseSchema, UploadMemoryResponseSchema, DownloadMemoryResponseSchema, UploadEngramAvatarResponseSchema, DeleteEngramAvatarResponseSchema, } from "../../core/ports/mikoshi.js";
 import { z } from "zod";
 /**
  * MikoshiApiClient — Mikoshi REST API v1 の adapter 実装
@@ -49,6 +49,18 @@ export class MikoshiApiClient {
         const data = await this.request("GET", `/api/v1/engrams/${enc(engramId)}/memory`);
         return DownloadMemoryResponseSchema.parse(data);
     }
+    async uploadEngramAvatar(engramId, data, mimeType) {
+        const form = new FormData();
+        // Blob は Uint8Array を受け付ける (Node 18+ 標準)
+        const blob = new Blob([new Uint8Array(data)], { type: mimeType });
+        form.append("file", blob, filenameForMimeType(mimeType));
+        const raw = await this.request("PUT", `/api/v1/engrams/${enc(engramId)}/avatar`, form);
+        return UploadEngramAvatarResponseSchema.parse(raw);
+    }
+    async deleteEngramAvatar(engramId) {
+        const raw = await this.request("DELETE", `/api/v1/engrams/${enc(engramId)}/avatar`);
+        return DeleteEngramAvatarResponseSchema.parse(raw);
+    }
     // -----------------------------------------------------------------------
     // Internal
     // -----------------------------------------------------------------------
@@ -60,8 +72,14 @@ export class MikoshiApiClient {
         };
         const init = { method, headers };
         if (body !== undefined) {
-            headers["Content-Type"] = "application/json";
-            init.body = JSON.stringify(body);
+            if (body instanceof FormData) {
+                // multipart boundary は fetch に自動で決めさせる
+                init.body = body;
+            }
+            else {
+                headers["Content-Type"] = "application/json";
+                init.body = JSON.stringify(body);
+            }
         }
         const res = await fetch(url, init);
         if (!res.ok) {
@@ -82,3 +100,15 @@ export class MikoshiApiClient {
 function enc(segment) {
     return encodeURIComponent(segment);
 }
+/**
+ * multipart/form-data 送信時のダミーファイル名。
+ * Mikoshi 側は MIME と内容で判定するので拡張子さえ合っていればよい。
+ */
+function filenameForMimeType(mimeType) {
+    switch (mimeType) {
+        case "image/jpeg": return "avatar.jpg";
+        case "image/png": return "avatar.png";
+        case "image/webp": return "avatar.webp";
+        default: return "avatar";
+    }
+}

package/dist/adapters/shells/codex-shell.js

@@ -43,7 +43,7 @@ export class CodexShell {
         if (!options?.skipInjection) {
             args.push("-c", `developer_instructions=${JSON.stringify(wrapWithOverride(prompt))}`);
         }
-        args.push("-c", "features.codex_hooks=true", ...(options?.extraArgs ?? []));
+        args.push("-c", "features.hooks=true", ...(options?.extraArgs ?? []));
         const env = {};
         if (options?.engramId)
             env.RELIC_ENGRAM_ID = options.engramId;

package/dist/adapters/shells/gemini-shell.js

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { spawnShell, writeTempPrompt } from "./spawn-shell.js";
 import { setupGeminiHook, isGeminiHookSetup, writeGeminiHookScript } from "./gemini-hook.js";
 const execAsync = promisify(exec);
@@ -16,45 +16,45 @@ const RELIC_ENGRAM_END = "<!-- RELIC ENGRAM END -->";
  * 組み込みシステムプロンプトをキャプチャして返す。
  * キャプチャ結果は ~/.relic/gemini-system-default.md にキャッシュされる。
  */
-async function captureDefaultSystemPrompt(command) {
-    const tempDir = mkdtempSync(join(tmpdir(), "relic-gemini-capture-"));
-    const geminiDir = join(tempDir, ".gemini");
+async function captureDefaultSystemPrompt(command, cwd = process.cwd()) {
+    const geminiDir = join(cwd, ".gemini");
     mkdirSync(geminiDir, { recursive: true });
-    try {
-        await new Promise((resolve) => {
-            const child = spawn(command, [], {
-                cwd: tempDir,
-                env: { ...process.env, GEMINI_WRITE_SYSTEM_MD: "true" },
-                // stdin を /dev/null 相当にして TTY なしで起動
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            // ファイル書き出し猶予として5秒後に強制終了
-            const timeout = setTimeout(() => {
-                child.kill("SIGTERM");
-            }, 5000);
-            child.on("close", () => {
-                clearTimeout(timeout);
-                resolve();
-            });
-            child.on("error", () => {
-                clearTimeout(timeout);
-                resolve();
-            });
+    await new Promise((resolve) => {
+        const child = spawn(command, [], {
+            cwd,
+            env: { ...process.env, GEMINI_WRITE_SYSTEM_MD: "true" },
+            // stdin を /dev/null 相当にして TTY なしで起動
+            stdio: ["ignore", "pipe", "pipe"],
         });
-        const systemMdPath = join(geminiDir, "system.md");
-        if (!existsSync(systemMdPath)) {
-            throw new Error("Failed to capture Gemini default system prompt.\n" +
-                "Run manually: GEMINI_WRITE_SYSTEM_MD=true gemini\n" +
-                `Then copy .gemini/system.md to ${GEMINI_DEFAULT_CACHE}`);
-        }
-        const content = readFileSync(systemMdPath, "utf-8");
-        mkdirSync(RELIC_DIR, { recursive: true });
-        writeFileSync(GEMINI_DEFAULT_CACHE, content, "utf-8");
-        return content;
+        // ファイル書き出し猶予として5秒後に強制終了
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+        }, 5000);
+        child.on("close", () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+        child.on("error", () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+    const systemMdPath = join(geminiDir, "system.md");
+    if (!existsSync(systemMdPath)) {
+        throw new Error("Failed to capture Gemini default system prompt.\n" +
+            `Run manually from ${cwd}: GEMINI_WRITE_SYSTEM_MD=true gemini\n` +
+            `Then copy ${systemMdPath} to ${GEMINI_DEFAULT_CACHE}`);
+    }
+    const content = readFileSync(systemMdPath, "utf-8");
+    mkdirSync(RELIC_DIR, { recursive: true });
+    writeFileSync(GEMINI_DEFAULT_CACHE, content, "utf-8");
+    try {
+        unlinkSync(systemMdPath);
     }
-    finally {
-        rmSync(tempDir, { recursive: true, force: true });
+    catch {
+        // Cache creation succeeded; cleanup failure should not block launch.
     }
+    return content;
 }
 /**
  * デフォルトプロンプトにEngramセクションを追記 or 置換する（冪等）。
@@ -121,7 +121,7 @@ export class GeminiShell {
         }
         else {
             console.log("Capturing Gemini default system prompt (first run only)...");
-            defaultPrompt = await captureDefaultSystemPrompt(this.command);
+            defaultPrompt = await captureDefaultSystemPrompt(this.command, options?.cwd);
             console.log(`Cached to: ${GEMINI_DEFAULT_CACHE}`);
             console.log();
         }

package/dist/core/entities/engram.d.ts

@@ -66,14 +66,22 @@ export declare const EngramManifestSchema: z.ZodObject<{
     createdAt: z.ZodString;
     /** 最終更新日時 */
     updatedAt: z.ZodString;
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.ZodOptional<z.ZodString>;
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     createdAt: string;
     updatedAt: string;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }, {
     id: string;
     createdAt: string;
     updatedAt: string;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }>;
 export type EngramManifest = z.infer<typeof EngramManifestSchema>;
 /**
@@ -93,6 +101,10 @@ export declare const EngramMetaSchema: z.ZodObject<{
     createdAt: z.ZodString;
     /** 最終更新日時 */
     updatedAt: z.ZodString;
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.ZodOptional<z.ZodString>;
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     id: string;
@@ -100,6 +112,8 @@ export declare const EngramMetaSchema: z.ZodObject<{
     updatedAt: string;
     description?: string | undefined;
     tags?: string[] | undefined;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }, {
     name: string;
     id: string;
@@ -107,6 +121,8 @@ export declare const EngramMetaSchema: z.ZodObject<{
     updatedAt: string;
     description?: string | undefined;
     tags?: string[] | undefined;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }>;
 export type EngramMeta = z.infer<typeof EngramMetaSchema>;
 /**
@@ -128,6 +144,10 @@ export declare const EngramSchema: z.ZodObject<{
         createdAt: z.ZodString;
         /** 最終更新日時 */
         updatedAt: z.ZodString;
+        /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+        avatarHash: z.ZodOptional<z.ZodString>;
+        /** 前回 push 時に使った外部 avatar URL */
+        avatarSourceUrl: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         id: string;
@@ -135,6 +155,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     }, {
         name: string;
         id: string;
@@ -142,6 +164,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     }>;
     files: z.ZodObject<{
         /** 人格の核となる指示・行動原理 */
@@ -183,6 +207,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     };
     files: {
         soul: string;
@@ -201,6 +227,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     };
     files: {
         soul: string;

package/dist/core/entities/engram.js

@@ -43,6 +43,10 @@ export const EngramManifestSchema = z.object({
     createdAt: z.string().datetime(),
     /** 最終更新日時 */
     updatedAt: z.string().datetime(),
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.string().optional(),
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.string().url().optional(),
 });
 /**
  * Engramメタデータ — プロフィールとマニフェストを結合した利用時ビュー

package/dist/core/ports/engram-repository.d.ts

@@ -1,4 +1,4 @@
-import type { Engram, EngramMeta } from "../entities/engram.js";
+import type { Engram, EngramManifest, EngramMeta } from "../entities/engram.js";
 /**
  * EngramRepository — Engram永続化層の抽象ポート
  *
@@ -12,8 +12,24 @@ export interface EngramRepository {
     get(id: string): Promise<Engram | null>;
     /** Engramを保存（作成 or 更新） */
     save(engram: Engram): Promise<void>;
+    /**
+     * マニフェストだけを差分書き換えする軽量更新。
+     *
+     * `save()` は全ファイルを書き戻してしまうので、avatarHash のような
+     * マニフェスト内のフィールドだけを安全に更新したい時に使う。
+     * 対象 Engram が存在しない場合の挙動は実装に委ねる（例外または no-op）。
+     */
+    updateManifest(id: string, manifest: EngramManifest): Promise<void>;
     /** Engramを削除 */
     delete(id: string): Promise<void>;
     /** アーカイブファイル (archive.md, archive.cursor) を別Engramへコピー */
     copyArchiveFiles(fromId: string, toId: string): Promise<boolean>;
+    /**
+     * Engramのディレクトリ絶対パスを返す。
+     *
+     * 存在判定は行わず、リポジトリが想定するパスを返すだけ。
+     * avatar 画像の読み書きなどファイルシステム直接アクセスが必要な
+     * usecase から使う。リモート専用リポジトリでは null を返してよい。
+     */
+    getEngramPath(id: string): string | null;
 }

package/dist/core/ports/mikoshi.d.ts

@@ -906,6 +906,26 @@ export declare const DownloadMemoryResponseSchema: z.ZodDiscriminatedUnion<"hasM
     engramId: string;
 }>]>;
 export type DownloadMemoryResponse = z.infer<typeof DownloadMemoryResponseSchema>;
+/** クライアントが許可する avatar MIME タイプ */
+export declare const AVATAR_SUPPORTED_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/webp"];
+/** クライアント側事前バリデーションの最大バイト数 (Mikoshi 側と一致) */
+export declare const AVATAR_MAX_BYTES: number;
+export declare const UploadEngramAvatarResponseSchema: z.ZodObject<{
+    avatarUrl: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    avatarUrl: string;
+}, {
+    avatarUrl: string;
+}>;
+export type UploadEngramAvatarResponse = z.infer<typeof UploadEngramAvatarResponseSchema>;
+export declare const DeleteEngramAvatarResponseSchema: z.ZodObject<{
+    avatarUrl: z.ZodNull;
+}, "strip", z.ZodTypeAny, {
+    avatarUrl: null;
+}, {
+    avatarUrl: null;
+}>;
+export type DeleteEngramAvatarResponse = z.infer<typeof DeleteEngramAvatarResponseSchema>;
 export declare class MikoshiApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
@@ -934,4 +954,8 @@ export interface MikoshiClient {
     uploadMemory(engramId: string, input: UploadMemoryInput): Promise<UploadMemoryResponse>;
     /** 暗号化メモリバンドルをダウンロード */
     downloadMemory(engramId: string): Promise<DownloadMemoryResponse>;
+    /** Avatar 画像をアップロード (multipart/form-data) */
+    uploadEngramAvatar(engramId: string, data: Buffer, mimeType: string): Promise<UploadEngramAvatarResponse>;
+    /** Avatar 画像を削除 */
+    deleteEngramAvatar(engramId: string): Promise<DeleteEngramAvatarResponse>;
 }

package/dist/core/ports/mikoshi.js

@@ -188,6 +188,23 @@ export const DownloadMemoryResponseSchema = z.discriminatedUnion("hasMemory", [
     }),
 ]);
 // ---------------------------------------------------------------------------
+// Avatar upload / delete
+// ---------------------------------------------------------------------------
+/** クライアントが許可する avatar MIME タイプ */
+export const AVATAR_SUPPORTED_MIME_TYPES = [
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+];
+/** クライアント側事前バリデーションの最大バイト数 (Mikoshi 側と一致) */
+export const AVATAR_MAX_BYTES = 2 * 1024 * 1024;
+export const UploadEngramAvatarResponseSchema = z.object({
+    avatarUrl: z.string(),
+});
+export const DeleteEngramAvatarResponseSchema = z.object({
+    avatarUrl: z.null(),
+});
+// ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
 export class MikoshiApiError extends Error {

package/dist/core/sync/avatar.d.ts

@@ -0,0 +1,121 @@
+export type AvatarRef = {
+    kind: "path";
+    value: string;
+} | {
+    kind: "url";
+    value: string;
+};
+export interface FetchedAvatar {
+    bytes: Buffer;
+    mimeType: string;
+    finalUrl: string;
+}
+/**
+ * IDENTITY.md から Avatar フィールドの生の値を抽出する。
+ *
+ * - マッチしなければ null
+ * - 値が URL（http://, https://）の場合は Mikoshi 管理外として null
+ * - 空白のみの値も null として扱う
+ */
+export declare function parseAvatarPath(identity: string): string | null;
+/**
+ * IDENTITY.md から Avatar フィールドの参照先を抽出する。
+ *
+ * - マッチしなければ null
+ * - 空白のみの値も null
+ * - `http(s)://` は URL として返す
+ * - それ以外は path として返す
+ */
+export declare function parseAvatarRef(identity: string): AvatarRef | null;
+/**
+ * Avatar パスを絶対パスに解決する。
+ *
+ * - 絶対パス → そのまま
+ * - 相対パス → Engram ディレクトリ基準で resolve
+ */
+export declare function resolveAvatarPath(rawPath: string, engramDir: string): string;
+/**
+ * ファイル内容の SHA-256 ハッシュを計算する。
+ *
+ * 出力形式: "sha256:<64 lowercase hex>"
+ *
+ * ストリーム処理なので 2MB 制限を超える巨大ファイルでも OOM しない。
+ */
+export declare function computeAvatarHash(filePath: string): Promise<string>;
+export declare function computeAvatarHashFromBytes(bytes: Uint8Array): string;
+/**
+ * 拡張子から MIME タイプを判定する。
+ *
+ * 許可フォーマット: JPEG, PNG, WebP
+ * 対応外なら null（呼び出し側でエラーにする）
+ *
+ * バイナリ判定は Mikoshi 側の sharp に任せる方針。
+ * クライアントは軽量な事前バリデーションのみ。
+ */
+export declare function detectAvatarMimeType(filePath: string): string | null;
+/**
+ * レスポンス header / magic number の両方から MIME を判定する。
+ *
+ * 両方あって不一致なら null を返す。
+ */
+export declare function detectAvatarMimeTypeFromBytes(bytes: Uint8Array, headerMimeType?: string | null): string | null;
+export declare function isHttpsUrl(raw: string): boolean;
+/**
+ * ホストが private / loopback / link-local なら true。
+ *
+ * hostname の場合は DNS lookup して、返ってきた全アドレスを検査する。
+ * DNS rebinding の完全対策ではない。事故防止用。
+ */
+export declare function isPrivateHost(url: URL): Promise<boolean>;
+export declare function fetchAvatarFromUrl(url: string, maxBytes: number, timeoutMs: number): Promise<FetchedAvatar>;
+/**
+ * IDENTITY.md を Avatar 行の前後で分離した結果。
+ *
+ * Avatar 行が存在しない場合は `rawValue === null`、`before` に全内容、
+ * `after` に空文字が入る（呼び出し側が「Avatar 行無し」として判定できる）。
+ */
+export interface AvatarSplit {
+    /** Avatar 行の値の直前までの文字列（`- **Avatar:** ` prefix を含む） */
+    before: string;
+    /** Avatar 行の値（行末改行含まず）。Avatar 行が無ければ null */
+    rawValue: string | null;
+    /** Avatar 行の値の直後以降の文字列（行末改行とその後の内容） */
+    after: string;
+}
+/**
+ * IDENTITY.md を Avatar 行の値を境に前後分離する。
+ *
+ * 書き換えと drift 検出の両方で使う基本操作。
+ */
+export declare function splitAroundAvatar(identity: string): AvatarSplit;
+/**
+ * IDENTITY.md の Avatar 行の値だけを差し替えて新しい文字列を返す。
+ *
+ * Avatar 行が存在しない場合は元の identity をそのまま返す
+ * （新しい Avatar 行は挿入しない — 保守的な挙動）。
+ */
+export declare function rewriteAvatarValue(identity: string, newValue: string): string;
+/**
+ * avatar-only drift の検出結果。
+ *
+ * drift === true の場合のみ `localValue` / `remoteValue` が
+ * 非 null（両方に Avatar 行が存在し、値だけが違う）。
+ */
+export interface AvatarOnlyDrift {
+    drift: boolean;
+    localValue: string | null;
+    remoteValue: string | null;
+}
+/**
+ * 2つの IDENTITY.md の差分が Avatar 行の値だけかどうかを判定する。
+ *
+ * 判定条件:
+ * - 両方に Avatar 行が存在する
+ * - Avatar 行の前後 (`before` / `after`) が完全一致
+ * - Avatar 行の値だけ異なる
+ *
+ * PATH 前後の format 揺れ（改行数・空白数など）は
+ * `before` / `after` の文字列一致にそのまま反映されるため、
+ * 揺れがあれば avatar-only drift とは判定されない（false positive を避ける）。
+ */
+export declare function isAvatarOnlyDrift(local: string, remote: string): AvatarOnlyDrift;