@deepmaid/maid-state-server 0.0.0-stage → 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenyonxu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/cli.d.ts

@@ -0,0 +1,14 @@
+//#region src/cli.d.ts
+/**
+ * maid-state CLI(maid-state 阶段规格 §12):serve/status/events/import/export/diff/compensate。
+ * 只读子命令以 readOnly 形态开库(不取排他锁,可与运行中 server 共存);
+ * import/export 建立在写库上(独占);compensate 走 client mTLS(缺 note / 非有限数 /
+ * maid 越权非零退出)。
+ */
+interface CliIo {
+  stdout(text: string): void;
+  stderr(text: string): void;
+}
+declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;
+//#endregion
+export { CliIo, runCli };

package/lib/cli.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { loadClientConfig, loadServerConfig } from "./config.js";
+import { startMaidStateServer } from "./server.js";
+import { diffEmotionJson, exportEmotionJson, importEmotionJson } from "./migrate.js";
+import { readFileSync, writeFileSync } from "node:fs";
+import { loadRegistry } from "@deepmaid/maid-identity/registry";
+import { PROTOCOL_VERSION, StateHttpClient, newEventId, openAuthorityStore } from "@deepmaid/maid-state";
+import { createEmotionConfigAuthority } from "@deepmaid/maid-emotion/config-authority";
+//#region src/cli.ts
+const HELP = `maid-state — DeepMaid 跨宿主状态服务 CLI
+
+用法:
+  maid-state serve     --config <server.yml>                    前台运行权威服务(mTLS)
+  maid-state status    --config <server.yml>                    各 maid revision/配置版本概览
+  maid-state events    --config <server.yml> [--maid <id>] [--after <revision>] [--limit <n>]
+                                                          事件回执清单(只读)
+  maid-state import    --config <server.yml> --from <state.json>  空库整份导入本机基线
+  maid-state export    --config <server.yml> --out <export.json>  导出当前权威状态
+  maid-state diff      --config <server.yml> --from <other.json> --out <diff.json>
+                                                          工作机旧状态 vs server 差异报告
+  maid-state compensate --config <client.yml> --maid <id> --delta <dim=value>... --note <text>
+                                                          人工补偿(显式 manual_compensation)
+`;
+function readJson(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		throw new Error(`cannot read JSON ${file} (${error.message})`, { cause: error });
+	}
+}
+async function runCli(argv, io) {
+	const [command, ...rest] = argv;
+	if (command === void 0 || command === "--help" || command === "help") {
+		io.stdout(HELP);
+		return command === void 0 ? 1 : 0;
+	}
+	const flag = (name) => {
+		const index = rest.indexOf(name);
+		return index >= 0 && index + 1 < rest.length ? rest[index + 1] : void 0;
+	};
+	try {
+		switch (command) {
+			case "serve": {
+				const configFile = flag("--config");
+				if (configFile === void 0) throw new Error("serve requires --config <server.yml>");
+				const config = loadServerConfig(configFile);
+				const server = await startMaidStateServer(config, { warn: (m) => io.stderr(m) });
+				io.stdout(`maid-state server listening at ${server.url} (authority ${server.authorityId})\n`);
+				const shutdown = async () => {
+					io.stderr("maid-state: shutting down\n");
+					await server.close();
+					process.exit(0);
+				};
+				process.once("SIGINT", () => {
+					shutdown();
+				});
+				process.once("SIGTERM", () => {
+					shutdown();
+				});
+				return new Promise(() => {});
+			}
+			case "status": {
+				const config = loadServerConfig(required(flag("--config"), "--config"));
+				const store = openAuthorityStore({
+					dataDir: config.dataDir,
+					readOnly: true
+				});
+				try {
+					const registry = loadRegistry(config.presetRoots, {
+						packRoots: config.packRoots,
+						warn: () => {}
+					});
+					const authority = createEmotionConfigAuthority({
+						presetRoots: config.presetRoots,
+						identity: registry,
+						globals: config.emotion,
+						warn: () => {}
+					});
+					io.stdout(JSON.stringify({
+						authorityId: store.authorityId,
+						protocolVersion: PROTOCOL_VERSION,
+						maids: Object.entries(store.exportStates()).map(([maidId, s]) => ({
+							maidId,
+							stateRevision: s.revision,
+							lastEffectiveAt: s.state.lastEffectiveAt,
+							configRevision: authority.get(maidId)?.configRevision ?? null
+						}))
+					}, null, 2) + "\n");
+					registry.dispose();
+				} finally {
+					store.close();
+				}
+				return 0;
+			}
+			case "events": {
+				const config = loadServerConfig(required(flag("--config"), "--config"));
+				const store = openAuthorityStore({
+					dataDir: config.dataDir,
+					readOnly: true
+				});
+				try {
+					const after = flag("--after");
+					const limit = flag("--limit");
+					const events = store.listEvents({
+						...flag("--maid") !== void 0 ? { maidId: flag("--maid") } : {},
+						...after !== void 0 ? { afterRevision: Number(after) } : {},
+						limit: limit !== void 0 ? Number(limit) : 100
+					});
+					io.stdout(JSON.stringify({ events }, null, 2) + "\n");
+				} finally {
+					store.close();
+				}
+				return 0;
+			}
+			case "import": {
+				const config = loadServerConfig(required(flag("--config"), "--config"));
+				const from = required(flag("--from"), "--from");
+				const registry = loadRegistry(config.presetRoots, {
+					packRoots: config.packRoots,
+					warn: () => {}
+				});
+				const authority = createEmotionConfigAuthority({
+					presetRoots: config.presetRoots,
+					identity: registry,
+					globals: config.emotion,
+					warn: () => {}
+				});
+				const store = openAuthorityStore({ dataDir: config.dataDir });
+				try {
+					const count = importEmotionJson(store, authority, readJson(from));
+					io.stdout(`imported ${count} maid(s) at revision 0\n`);
+				} finally {
+					store.close();
+					registry.dispose();
+				}
+				return 0;
+			}
+			case "export": {
+				const config = loadServerConfig(required(flag("--config"), "--config"));
+				const out = required(flag("--out"), "--out");
+				const store = openAuthorityStore({ dataDir: config.dataDir });
+				try {
+					writeFileSync(out, JSON.stringify(exportEmotionJson(store), null, 2) + "\n", "utf8");
+					io.stdout(`exported to ${out}\n`);
+				} finally {
+					store.close();
+				}
+				return 0;
+			}
+			case "diff": {
+				const config = loadServerConfig(required(flag("--config"), "--config"));
+				const from = required(flag("--from"), "--from");
+				const out = required(flag("--out"), "--out");
+				const store = openAuthorityStore({
+					dataDir: config.dataDir,
+					readOnly: true
+				});
+				try {
+					writeFileSync(out, JSON.stringify(diffEmotionJson(store, readJson(from)), null, 2) + "\n", "utf8");
+					io.stdout(`diff written to ${out}\n`);
+				} finally {
+					store.close();
+				}
+				return 0;
+			}
+			case "compensate": {
+				const config = loadClientConfig(required(flag("--config"), "--config"));
+				const maidId = required(flag("--maid"), "--maid");
+				const note = required(flag("--note"), "--note");
+				const deltas = {};
+				for (let i = 0; i < rest.length - 1; i++) if (rest[i] === "--delta") {
+					const token = rest[i + 1];
+					const eq = token.indexOf("=");
+					if (eq <= 0) throw new Error(`--delta expects <dim=value> (got '${token}')`);
+					const value = Number(token.slice(eq + 1));
+					if (!Number.isFinite(value)) throw new Error(`--delta value must be a finite number (got '${token.slice(eq + 1)}')`);
+					deltas[token.slice(0, eq)] = value;
+				}
+				if (Object.keys(deltas).length === 0) throw new Error("compensate requires at least one --delta <dim=value>");
+				const client = new StateHttpClient({
+					url: config.url,
+					hostId: config.hostId,
+					keyFile: config.keyFile,
+					certFile: config.certFile,
+					caFile: config.caFile,
+					serverFingerprint256: config.serverFingerprint256,
+					authorityId: config.authorityId
+				});
+				try {
+					const snapshot = await client.getSnapshot(maidId);
+					const receipt = await client.submit({
+						protocolVersion: PROTOCOL_VERSION,
+						eventId: newEventId(),
+						hostId: config.hostId,
+						maidId,
+						kind: "emotion.apply_deltas",
+						occurredAt: Date.now(),
+						sourceConfigRevision: snapshot.configRevision,
+						payload: {
+							deltas,
+							source: "manual_compensation",
+							note
+						}
+					});
+					if (receipt.status === "rejected") {
+						io.stderr(`compensate rejected: ${receipt.errorCode ?? "unknown"}\n`);
+						return 1;
+					}
+					io.stdout(`compensated ${maidId} (revision ${receipt.snapshot?.stateRevision ?? receipt.appliedRevision})\n`);
+					return 0;
+				} finally {
+					client.close();
+				}
+			}
+			default:
+				io.stderr(`unknown command '${command}'\n\n${HELP}`);
+				return 1;
+		}
+	} catch (error) {
+		io.stderr(`maid-state: ${error.message}\n`);
+		return 1;
+	}
+}
+function required(value, name) {
+	if (value === void 0) throw new Error(`${name} is required`);
+	return value;
+}
+if (process.argv[1] !== void 0 && process.argv[1].endsWith("cli.js")) runCli(process.argv.slice(2), {
+	stdout: (t) => process.stdout.write(t),
+	stderr: (t) => process.stderr.write(t)
+}).then((code) => process.exit(code)).catch(() => process.exit(1));
+//#endregion
+export { runCli };

package/lib/config.d.ts

@@ -0,0 +1,45 @@
+//#region src/config.d.ts
+/**
+ * 独立进程配置(maid-state 阶段规格 §10.3/§12):server.yml / client.yml(compensate 用)。
+ * fail-loud 纪律:缺 TLS、重复 hostId、空 allowMaids、相对 dataDir、未知顶层键全部拒绝;
+ * emotion 四数值是权威结算参数,**必填显式声明**(权威不携带隐式缺省)。
+ */
+interface EmotionGlobalsConfig {
+  vectorHalfLifeMs: number;
+  moodHalfLifeMs: number;
+  trendBand: number;
+  timezone: string;
+}
+interface MaidStateServerConfig {
+  dataDir: string;
+  presetRoots: string[];
+  packRoots: string[];
+  emotion: EmotionGlobalsConfig;
+  listen: {
+    host: string;
+    port: number;
+  };
+  tls: {
+    keyFile: string;
+    certFile: string;
+    caFile: string;
+  };
+  clients: Array<{
+    hostId: string;
+    fingerprint256: string;
+    allowMaids?: string[];
+  }>;
+}
+interface MaidStateClientConfig {
+  url: string;
+  hostId: string;
+  keyFile: string;
+  certFile: string;
+  caFile: string;
+  serverFingerprint256: string;
+  authorityId: string;
+}
+declare function loadServerConfig(file: string): MaidStateServerConfig;
+declare function loadClientConfig(file: string): MaidStateClientConfig;
+//#endregion
+export { EmotionGlobalsConfig, MaidStateClientConfig, MaidStateServerConfig, loadClientConfig, loadServerConfig };

package/lib/config.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { parse } from "yaml";
+//#region src/config.ts
+const SERVER_KEYS = /* @__PURE__ */ new Set([
+	"dataDir",
+	"presetRoots",
+	"packRoots",
+	"emotion",
+	"listen",
+	"tls",
+	"clients"
+]);
+const CLIENT_KEYS = /* @__PURE__ */ new Set([
+	"url",
+	"hostId",
+	"keyFile",
+	"certFile",
+	"caFile",
+	"serverFingerprint256",
+	"authorityId"
+]);
+function fail(where, message) {
+	throw new Error(`maid-state-server: ${where}: ${message}`);
+}
+function readYaml(file) {
+	let raw;
+	try {
+		raw = readFileSync(file, "utf8");
+	} catch (error) {
+		throw new Error(`maid-state-server: cannot read config ${file} (${error.message})`, { cause: error });
+	}
+	const parsed = parse(raw);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) fail(file, "config must be a mapping");
+	return parsed;
+}
+function requireStrings(where, node, keys) {
+	for (const key of keys) if (typeof node[key] !== "string" || node[key].length === 0) fail(where, `${key} must be a non-empty string`);
+}
+function loadServerConfig(file) {
+	const raw = readYaml(file);
+	for (const key of Object.keys(raw)) if (!SERVER_KEYS.has(key)) fail(file, `unknown top-level key '${key}'`);
+	if (typeof raw.dataDir !== "string" || raw.dataDir.length === 0 || !isAbsolute(raw.dataDir)) fail(file, "dataDir must be an absolute path");
+	const dataDir = raw.dataDir;
+	const presetRoots = Array.isArray(raw.presetRoots) && raw.presetRoots.every((p) => typeof p === "string") ? raw.presetRoots.map((p) => resolve(p)) : [];
+	if (presetRoots.length === 0) fail(file, "presetRoots must be a non-empty string array");
+	const packRoots = Array.isArray(raw.packRoots) && raw.packRoots.every((p) => typeof p === "string") ? raw.packRoots.map((p) => resolve(p)) : [];
+	const emotionNode = raw.emotion;
+	if (typeof emotionNode !== "object" || emotionNode === null) fail(file, "emotion globals required (vectorHalfLifeMs/moodHalfLifeMs/trendBand/timezone)");
+	const e = emotionNode;
+	const emotion = {
+		vectorHalfLifeMs: e.vectorHalfLifeMs,
+		moodHalfLifeMs: e.moodHalfLifeMs,
+		trendBand: e.trendBand,
+		timezone: e.timezone
+	};
+	for (const [key, value] of Object.entries(emotion)) if (key === "timezone") {
+		if (typeof value !== "string" || value.length === 0) fail(file, "emotion.timezone must be a non-empty string");
+	} else if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) fail(file, `emotion.${key} must be a positive finite number`);
+	const listenNode = raw.listen;
+	if (typeof listenNode !== "object" || listenNode === null) fail(file, "listen required ({host, port})");
+	const l = listenNode;
+	if (typeof l.host !== "string" || l.host.length === 0) fail(file, "listen.host must be a non-empty string");
+	if (typeof l.port !== "number" || !Number.isInteger(l.port) || l.port < 0 || l.port > 65535) fail(file, "listen.port must be 0-65535");
+	const tlsNode = raw.tls;
+	if (typeof tlsNode !== "object" || tlsNode === null) fail(file, "tls required (keyFile/certFile/caFile)");
+	const t = tlsNode;
+	requireStrings(`${file} [tls]`, t, [
+		"keyFile",
+		"certFile",
+		"caFile"
+	]);
+	const clientsNode = raw.clients;
+	if (!Array.isArray(clientsNode) || clientsNode.length === 0) fail(file, "clients must be a non-empty list");
+	const seen = /* @__PURE__ */ new Set();
+	const clients = clientsNode.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null) fail(`${file} [clients.${index}]`, "must be a mapping");
+		const c = entry;
+		requireStrings(`${file} [clients.${index}]`, c, ["hostId", "fingerprint256"]);
+		if (seen.has(c.hostId)) fail(file, `duplicate client hostId '${String(c.hostId)}'`);
+		seen.add(c.hostId);
+		if (c.allowMaids === void 0) return {
+			hostId: c.hostId,
+			fingerprint256: c.fingerprint256
+		};
+		if (!Array.isArray(c.allowMaids) || c.allowMaids.length === 0 || !c.allowMaids.every((m) => typeof m === "string")) fail(`${file} [clients.${index}]`, "allowMaids must be a non-empty string array (omit to allow all registered maids)");
+		return {
+			hostId: c.hostId,
+			fingerprint256: c.fingerprint256,
+			allowMaids: c.allowMaids
+		};
+	});
+	return {
+		dataDir,
+		presetRoots,
+		packRoots,
+		emotion,
+		listen: {
+			host: l.host,
+			port: l.port
+		},
+		tls: {
+			keyFile: t.keyFile,
+			certFile: t.certFile,
+			caFile: t.caFile
+		},
+		clients
+	};
+}
+function loadClientConfig(file) {
+	const raw = readYaml(file);
+	for (const key of Object.keys(raw)) if (!CLIENT_KEYS.has(key)) fail(file, `unknown top-level key '${key}'`);
+	requireStrings(file, raw, [...CLIENT_KEYS]);
+	return raw;
+}
+//#endregion
+export { loadClientConfig, loadServerConfig };

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import { CliIo, runCli } from "./cli.js";
+import { EmotionGlobalsConfig, MaidStateClientConfig, MaidStateServerConfig, loadClientConfig, loadServerConfig } from "./config.js";
+import { RunningMaidStateServer, startMaidStateServer } from "./server.js";
+import { EmotionDiffEntry, EmotionDiffReport, EmotionStateExport, LegacyEmotionStates, diffEmotionJson, exportEmotionJson, importEmotionJson } from "./migrate.js";
+export { type CliIo, type EmotionDiffEntry, type EmotionDiffReport, type EmotionGlobalsConfig, type EmotionStateExport, type LegacyEmotionStates, type MaidStateClientConfig, type MaidStateServerConfig, type RunningMaidStateServer, diffEmotionJson, exportEmotionJson, importEmotionJson, loadClientConfig, loadServerConfig, runCli, startMaidStateServer };

package/lib/index.js

@@ -0,0 +1,5 @@
+import { loadClientConfig, loadServerConfig } from "./config.js";
+import { startMaidStateServer } from "./server.js";
+import { diffEmotionJson, exportEmotionJson, importEmotionJson } from "./migrate.js";
+import { runCli } from "./cli.js";
+export { diffEmotionJson, exportEmotionJson, importEmotionJson, loadClientConfig, loadServerConfig, runCli, startMaidStateServer };

package/lib/migrate.d.ts

@@ -0,0 +1,51 @@
+import { AuthorityStore } from "@deepmaid/maid-state";
+import { EmotionAuthorityState, MaidEmotionState } from "@deepmaid/maid-emotion/domain";
+import { EmotionConfigAuthority } from "@deepmaid/maid-emotion/config-authority";
+//#region src/migrate.d.ts
+/**
+ * 迁移工具(maid-state 阶段规格 §13):空库整份导入本机基线、当前权威导出、
+ * 分叉差异报告。纪律:仅空库可导入(任一 maid 有状态或有事件回执即拒绝);一次导入
+ * 覆盖全部已配置 maid,任一缺失/未注册即整批回滚;**绝不自动合并**分叉(差异只报告)。
+ */
+interface EmotionStateExport {
+  formatVersion: 1;
+  authorityId: string;
+  exportedAt: number;
+  maids: Record<string, {
+    state: EmotionAuthorityState;
+    revision: number;
+  }>;
+}
+interface EmotionDiffEntry {
+  vectors?: {
+    server: Record<string, number>;
+    other: Record<string, number>;
+  };
+  emotion?: {
+    server: Record<string, number>;
+    other: Record<string, number>;
+  };
+  signals?: {
+    server: Record<string, unknown>;
+    other: Record<string, unknown>;
+  };
+  updatedAt?: {
+    server: number;
+    other: number;
+  };
+  historyLength?: {
+    server: number;
+    other: number;
+  };
+}
+interface EmotionDiffReport {
+  maids: Record<string, EmotionDiffEntry>;
+}
+/** 旧宿主状态文件形态:单文件多 maidId → Record<maidId, MaidEmotionState> */
+type LegacyEmotionStates = Record<string, MaidEmotionState>;
+declare function importEmotionJson(store: AuthorityStore<EmotionAuthorityState>, configAuthority: EmotionConfigAuthority, legacy: LegacyEmotionStates): number;
+declare function exportEmotionJson(store: AuthorityStore<EmotionAuthorityState>): EmotionStateExport;
+/** 差异报告:vectors/emotion 数值、signals、updatedAt、history 长度的双值对照;只读不写库 */
+declare function diffEmotionJson(store: AuthorityStore<EmotionAuthorityState>, other: LegacyEmotionStates): EmotionDiffReport;
+//#endregion
+export { EmotionDiffEntry, EmotionDiffReport, EmotionStateExport, LegacyEmotionStates, diffEmotionJson, exportEmotionJson, importEmotionJson };

package/lib/migrate.js

@@ -0,0 +1,85 @@
+import { alignStateToConfig, emotionTiersOf } from "@deepmaid/maid-emotion/domain";
+//#region src/migrate.ts
+function importEmotionJson(store, configAuthority, legacy) {
+	const existing = store.exportStates();
+	const hasEvents = store.listEvents({ limit: 1 }).length > 0;
+	if (Object.keys(existing).length > 0 || hasEvents) throw new Error(`maid-state-server: import requires an empty authority store (data dir not empty): refusing to overwrite history`);
+	const configured = /* @__PURE__ */ new Set();
+	for (const maidId of configAuthority.list()) if (configAuthority.get(maidId) !== void 0) configured.add(maidId);
+	for (const maidId of Object.keys(legacy)) if (!configured.has(maidId)) throw new Error(`maid-state-server: legacy state carries unregistered/unconfigured maid '${maidId}'`);
+	for (const maidId of configured) if (legacy[maidId] === void 0) throw new Error(`maid-state-server: configured maid '${maidId}' missing from legacy state (refusing partial import)`);
+	let count = 0;
+	store.transaction((tx) => {
+		for (const maidId of configured) {
+			const entry = configAuthority.get(maidId);
+			const legacyState = legacy[maidId];
+			const current = alignStateToConfig(legacyState, Object.keys(entry.config.emotion.dimensions), emotionTiersOf(entry.config.emotion));
+			const lastEffectiveAt = Math.max(legacyState.updatedAt, legacyState.emotion?.updatedAt ?? 0, legacyState.signals.lastMessageAt);
+			tx.writeState(maidId, {
+				state: {
+					current,
+					lastEffectiveAt
+				},
+				revision: 0
+			});
+			count++;
+		}
+	});
+	return count;
+}
+function exportEmotionJson(store) {
+	return {
+		formatVersion: 1,
+		authorityId: store.authorityId,
+		exportedAt: Date.now(),
+		maids: store.exportStates()
+	};
+}
+/** 差异报告:vectors/emotion 数值、signals、updatedAt、history 长度的双值对照;只读不写库 */
+function diffEmotionJson(store, other) {
+	const serverStates = store.exportStates();
+	const maids = {};
+	const emotionValues = (state) => {
+		const dims = state.emotion?.dimensions;
+		return dims === void 0 ? {} : Object.fromEntries(Object.entries(dims).map(([id, d]) => [id, d.value]));
+	};
+	const asMaid = (s) => s;
+	for (const maidId of /* @__PURE__ */ new Set([...Object.keys(serverStates), ...Object.keys(other)])) {
+		const server = serverStates[maidId]?.state.current;
+		const otherState = other[maidId];
+		if (server === void 0 || otherState === void 0) {
+			maids[maidId] = { historyLength: {
+				server: server !== void 0 ? asMaid(server).history.length : -1,
+				other: otherState !== void 0 ? otherState.history.length : -1
+			} };
+			continue;
+		}
+		const entry = {};
+		if (JSON.stringify(server.vectors) !== JSON.stringify(otherState.vectors)) entry.vectors = {
+			server: { ...server.vectors },
+			other: { ...otherState.vectors }
+		};
+		const serverEmotion = emotionValues(asMaid(server));
+		const otherEmotion = emotionValues(otherState);
+		if (JSON.stringify(serverEmotion) !== JSON.stringify(otherEmotion)) entry.emotion = {
+			server: serverEmotion,
+			other: otherEmotion
+		};
+		if (JSON.stringify(server.signals) !== JSON.stringify(otherState.signals)) entry.signals = {
+			server: { ...server.signals },
+			other: { ...otherState.signals }
+		};
+		if (server.updatedAt !== otherState.updatedAt) entry.updatedAt = {
+			server: server.updatedAt,
+			other: otherState.updatedAt
+		};
+		if (asMaid(server).history.length !== otherState.history.length) entry.historyLength = {
+			server: asMaid(server).history.length,
+			other: otherState.history.length
+		};
+		if (Object.keys(entry).length > 0) maids[maidId] = entry;
+	}
+	return { maids };
+}
+//#endregion
+export { diffEmotionJson, exportEmotionJson, importEmotionJson };

package/lib/server.d.ts

@@ -0,0 +1,19 @@
+import { MaidStateServerConfig } from "./config.js";
+//#region src/server.d.ts
+/**
+ * 权威服务组合入口(maid-state 阶段规格 §4.2;M3j 起委托 maid-emotion 的共享
+ * createEmotionAuthority 组合面):纯 registry + 共享 authority(config 权威 +
+ * domain reducer + 事务存储)+ mTLS 面。embedded 后端与 server 消费同一组合,
+ * 「同一输入同一结果」由结构保证。
+ */
+interface RunningMaidStateServer {
+  authorityId: string;
+  url: string;
+  close(): Promise<void>;
+}
+declare function startMaidStateServer(config: MaidStateServerConfig, deps?: {
+  warn?: (m: string) => void;
+  now?: () => number;
+}): Promise<RunningMaidStateServer>;
+//#endregion
+export { RunningMaidStateServer, startMaidStateServer };

package/lib/server.js

@@ -0,0 +1,39 @@
+import { loadRegistry } from "@deepmaid/maid-identity/registry";
+import { createEmotionAuthority } from "@deepmaid/maid-emotion/authority";
+import { startStateHttpServer } from "@deepmaid/maid-state";
+//#region src/server.ts
+async function startMaidStateServer(config, deps = {}) {
+	const warn = deps.warn ?? (() => {});
+	const registry = loadRegistry(config.presetRoots, {
+		packRoots: config.packRoots,
+		warn
+	});
+	const runtime = createEmotionAuthority({
+		dataDir: config.dataDir,
+		presetRoots: config.presetRoots,
+		identity: registry,
+		globals: config.emotion,
+		warn,
+		...deps.now !== void 0 ? { now: deps.now } : {}
+	});
+	const http = await startStateHttpServer({
+		authority: runtime.authority,
+		store: runtime.store,
+		listen: config.listen,
+		tls: {
+			...config.tls,
+			clients: config.clients
+		}
+	});
+	return {
+		authorityId: runtime.authority.authorityId,
+		url: http.url,
+		close: async () => {
+			await http.close();
+			registry.dispose();
+			runtime.close();
+		}
+	};
+}
+//#endregion
+export { startMaidStateServer };

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@deepmaid/maid-state-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.3",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "maid-state": "./lib/cli.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "default": "./lib/server.js"
+    },
+    "./config": {
+      "types": "./lib/config.d.ts",
+      "default": "./lib/config.js"
+    },
+    "./migrate": {
+      "types": "./lib/migrate.d.ts",
+      "default": "./lib/migrate.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "yaml": "2.9.0",
+    "@deepmaid/maid-emotion": "0.1.0-alpha.3",
+    "@deepmaid/maid-identity": "0.1.0-alpha.3",
+    "@deepmaid/maid-state": "0.1.0-alpha.3"
+  },
+  "devDependencies": {
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.