Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/nostr/doctor-contract-api.ts

@@ -0,0 +1,263 @@
+// Nostr API module exposes the plugin public contract.
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  archiveLegacyStateSource,
+  type PluginDoctorStateMigration,
+} from "openclaw/plugin-sdk/runtime-doctor";
+import { normalizeNostrStateAccountId } from "./src/state-account-id.js";
+
+type NostrBusState = {
+  version: 2;
+  lastProcessedAt: number | null;
+  gatewayStartedAt: number | null;
+  recentEventIds: string[];
+};
+
+type NostrProfileState = {
+  version: 1;
+  lastPublishedAt: number | null;
+  lastPublishedEventId: string | null;
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+};
+
+const BUS_STATE_NAMESPACE = "bus-state";
+const PROFILE_STATE_NAMESPACE = "profile-state";
+const MAX_NOSTR_STATE_ENTRIES = 256;
+
+function finiteNumberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseBusState(value: unknown): NostrBusState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const parsed = value as Record<string, unknown>;
+  if (parsed.version !== 1 && parsed.version !== 2) {
+    return null;
+  }
+  return {
+    version: 2,
+    lastProcessedAt: finiteNumberOrNull(parsed.lastProcessedAt),
+    gatewayStartedAt: finiteNumberOrNull(parsed.gatewayStartedAt),
+    recentEventIds:
+      parsed.version === 2 && Array.isArray(parsed.recentEventIds)
+        ? parsed.recentEventIds.filter((entry): entry is string => typeof entry === "string")
+        : [],
+  };
+}
+
+function parseProfileState(value: unknown): NostrProfileState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const parsed = value as Record<string, unknown>;
+  if (parsed.version !== 1) {
+    return null;
+  }
+  const rawResults = parsed.lastPublishResults;
+  const lastPublishResults: Record<string, "ok" | "failed" | "timeout"> = {};
+  if (rawResults && typeof rawResults === "object" && !Array.isArray(rawResults)) {
+    for (const [relay, result] of Object.entries(rawResults)) {
+      if (result === "ok" || result === "failed" || result === "timeout") {
+        lastPublishResults[relay] = result;
+      }
+    }
+  }
+  return {
+    version: 1,
+    lastPublishedAt: finiteNumberOrNull(parsed.lastPublishedAt),
+    lastPublishedEventId:
+      typeof parsed.lastPublishedEventId === "string" ? parsed.lastPublishedEventId : null,
+    lastPublishResults:
+      rawResults === null || Object.keys(lastPublishResults).length === 0
+        ? null
+        : lastPublishResults,
+  };
+}
+
+async function readJsonFile(filePath: string): Promise<unknown> {
+  return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+}
+
+async function listLegacyFiles(params: {
+  stateDir: string;
+  prefix: string;
+  parse: (value: unknown) => unknown;
+}): Promise<Array<{ accountId: string; filePath: string; value: unknown }>> {
+  const dir = path.join(params.stateDir, "nostr");
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const suffix = ".json";
+  const files: Array<{ accountId: string; filePath: string; value: unknown }> = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith(params.prefix) || !entry.name.endsWith(suffix)) {
+      continue;
+    }
+    const rawAccountId = entry.name.slice(params.prefix.length, -suffix.length);
+    const accountId = normalizeNostrStateAccountId(rawAccountId);
+    const filePath = path.join(dir, entry.name);
+    try {
+      const value = params.parse(await readJsonFile(filePath));
+      if (value) {
+        files.push({ accountId, filePath, value });
+      }
+    } catch {
+      // Malformed legacy cache/cursor files are ignored by migration.
+    }
+  }
+  return files;
+}
+
+async function ensureStoreCapacity(params: {
+  files: Array<{ accountId: string }>;
+  store: { entries: () => Promise<Array<{ key: string; value: unknown }>> };
+  maxEntries: number;
+  label: string;
+  warnings: string[];
+}): Promise<Set<string> | null> {
+  const existingKeys = new Set((await params.store.entries()).map((entry) => entry.key));
+  const missingKeys = new Set(
+    params.files.map((file) => file.accountId).filter((key) => !existingKeys.has(key)),
+  );
+  if (missingKeys.size > params.maxEntries - existingKeys.size) {
+    params.warnings.push(
+      `Skipped migrating ${params.label} because plugin state has room for ${params.maxEntries - existingKeys.size} of ${missingKeys.size} missing entries; left legacy sources in place`,
+    );
+    return null;
+  }
+  return existingKeys;
+}
+
+export const stateMigrations: PluginDoctorStateMigration[] = [
+  {
+    id: "nostr-bus-state-json-to-plugin-state",
+    label: "Nostr bus state",
+    async detectLegacyState(params) {
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "bus-state-",
+        parse: parseBusState,
+      });
+      if (files.length === 0) {
+        return null;
+      }
+      return {
+        preview: [
+          `- Nostr bus state: ${files.length} ${files.length === 1 ? "account" : "accounts"} -> plugin state (${BUS_STATE_NAMESPACE})`,
+        ],
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "bus-state-",
+        parse: parseBusState,
+      });
+      const store = params.context.openPluginStateKeyedStore<NostrBusState>({
+        namespace: BUS_STATE_NAMESPACE,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+      });
+      const existingKeys = await ensureStoreCapacity({
+        files,
+        store,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+        label: "Nostr bus state",
+        warnings,
+      });
+      if (!existingKeys) {
+        return { changes, warnings };
+      }
+      let imported = 0;
+      for (const file of files) {
+        if (!existingKeys.has(file.accountId)) {
+          await store.register(file.accountId, file.value as NostrBusState);
+          existingKeys.add(file.accountId);
+          imported++;
+        }
+        await archiveLegacyStateSource({
+          filePath: file.filePath,
+          label: "Nostr bus state",
+          changes,
+          warnings,
+        });
+      }
+      if (imported > 0) {
+        changes.unshift(
+          `Migrated ${imported} Nostr bus-state ${imported === 1 ? "entry" : "entries"} -> plugin state`,
+        );
+      }
+      return { changes, warnings };
+    },
+  },
+  {
+    id: "nostr-profile-state-json-to-plugin-state",
+    label: "Nostr profile state",
+    async detectLegacyState(params) {
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "profile-state-",
+        parse: parseProfileState,
+      });
+      if (files.length === 0) {
+        return null;
+      }
+      return {
+        preview: [
+          `- Nostr profile state: ${files.length} ${files.length === 1 ? "account" : "accounts"} -> plugin state (${PROFILE_STATE_NAMESPACE})`,
+        ],
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "profile-state-",
+        parse: parseProfileState,
+      });
+      const store = params.context.openPluginStateKeyedStore<NostrProfileState>({
+        namespace: PROFILE_STATE_NAMESPACE,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+      });
+      const existingKeys = await ensureStoreCapacity({
+        files,
+        store,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+        label: "Nostr profile state",
+        warnings,
+      });
+      if (!existingKeys) {
+        return { changes, warnings };
+      }
+      let imported = 0;
+      for (const file of files) {
+        if (!existingKeys.has(file.accountId)) {
+          await store.register(file.accountId, file.value as NostrProfileState);
+          existingKeys.add(file.accountId);
+          imported++;
+        }
+        await archiveLegacyStateSource({
+          filePath: file.filePath,
+          label: "Nostr profile state",
+          changes,
+          warnings,
+        });
+      }
+      if (imported > 0) {
+        changes.unshift(
+          `Migrated ${imported} Nostr profile-state ${imported === 1 ? "entry" : "entries"} -> plugin state`,
+        );
+      }
+      return { changes, warnings };
+    },
+  },
+];