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

package/lib/index.js

@@ -0,0 +1,1113 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { createServer, request } from "node:https";
+import { checkServerIdentity } from "node:tls";
+//#region src/protocol.ts
+/**
+* maid-state 协议信封(阶段规格 §6,2026-11-06):传输无关的命令/快照/回执三件套。
+* 稳定性纪律:
+* - turn eventId 派生命名空间 'emotion.turn.v1' 与 commandHash 的语义字段集都**不随
+*   线 protocolVersion 变化**(升级后重放旧命令不得被当成新事件/新冲突);
+* - canonicalJson 键排序用代码点比较,不用 localeCompare(ICU 随构建漂移会破哈希稳定性)。
+*/
+const PROTOCOL_VERSION = 1;
+/** 稳定机器码错误(规格 §11:永久协议错误与临时网络错误必须分开) */
+var StateCommandError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "StateCommandError";
+	}
+};
+/** 确定性 JSON 序列化:键代码点排序、剔除 undefined;数字/字符串走 JSON 标准形态 */
+function canonicalJson(value) {
+	if (value === void 0) return "null";
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+function revisionOf(value) {
+	return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+/** UUIDv7(时间有序,重试语义友好);eventId 手势/重逢/补偿通道使用 */
+function newEventId(now = Date.now()) {
+	const bytes = randomBytes(16);
+	const timestamp = BigInt(now);
+	for (let i = 0; i < 6; i++) bytes[i] = Number(timestamp >> BigInt((5 - i) * 8) & 255n);
+	bytes[6] = bytes[6] & 15 | 112;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = bytes.toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** turn 命令稳定身份:turnKey 派生(规格 §6.1),宿主会话/轮次重放复用同一 eventId */
+function turnEventId(input) {
+	return `turn_${revisionOf([
+		"emotion.turn.v1",
+		input.hostId,
+		input.sessionId,
+		input.turn
+	])}`;
+}
+/** 语义命令哈希:只覆盖领域语义字段,不含 protocolVersion/传输元数据(规格 §6.1) */
+function commandHash(command) {
+	return revisionOf({
+		eventId: command.eventId,
+		hostId: command.hostId,
+		maidId: command.maidId,
+		kind: command.kind,
+		occurredAt: command.occurredAt,
+		sourceConfigRevision: command.sourceConfigRevision,
+		payload: command.payload
+	});
+}
+/** 入站命令形状守卫(规格 §6.1):协议版本/必填串/有限时间/payload 对象 */
+function assertStateCommand(value) {
+	const c = value;
+	if (c?.protocolVersion !== 1) throw new StateCommandError("PROTOCOL_VERSION", `protocolVersion unsupported (expected 1, got ${String(c?.protocolVersion)})`);
+	for (const key of [
+		"eventId",
+		"hostId",
+		"maidId",
+		"kind",
+		"sourceConfigRevision"
+	]) {
+		const v = c[key];
+		if (typeof v !== "string" || v.length === 0) throw new StateCommandError("COMMAND_SHAPE", `${key} required (non-empty string)`);
+	}
+	if (!Number.isFinite(c.occurredAt)) throw new StateCommandError("COMMAND_SHAPE", "occurredAt must be a finite number");
+	if (c.payload === void 0 || c.payload === null || typeof c.payload !== "object") throw new StateCommandError("COMMAND_SHAPE", "payload object required");
+}
+//#endregion
+//#region src/lock.ts
+const HEARTBEAT_INTERVAL_MS = 5e3;
+function pidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+function acquireDataDirLock(dataDir) {
+	mkdirSync(dataDir, { recursive: true });
+	try {
+		chmodSync(dataDir, 448);
+	} catch {}
+	const file = join(dataDir, "server.lock");
+	const info = {
+		pid: process.pid,
+		startedAt: Date.now(),
+		heartbeatAt: Date.now()
+	};
+	const writeBody = (flag) => {
+		const fd = openSync(file, flag, 384);
+		try {
+			writeFileSync(fd, JSON.stringify(info));
+		} finally {
+			closeSync(fd);
+		}
+	};
+	info.heartbeatAt = info.startedAt;
+	try {
+		writeBody("wx");
+	} catch (error) {
+		if (error.code !== "EEXIST") throw new Error(`maid-state: cannot create data dir lock at ${file} (${error.message})`, { cause: error });
+		let holder = {};
+		try {
+			holder = JSON.parse(readFileSync(file, "utf8"));
+		} catch {}
+		if (typeof holder.pid === "number" && pidAlive(holder.pid)) throw new Error(`maid-state: data directory locked by active server (pid ${holder.pid}): ${dataDir}`, { cause: error });
+		try {
+			unlinkSync(file);
+		} catch {}
+		writeBody("wx");
+	}
+	const timer = setInterval(() => {
+		info.heartbeatAt = Date.now();
+		try {
+			writeBody("w");
+		} catch {}
+	}, HEARTBEAT_INTERVAL_MS);
+	timer.unref();
+	let released = false;
+	return {
+		pid: info.pid,
+		release() {
+			if (released) return;
+			released = true;
+			clearInterval(timer);
+			try {
+				unlinkSync(file);
+			} catch {}
+		}
+	};
+}
+//#endregion
+//#region src/authority-store.ts
+const SCHEMA$1 = `
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS maid_state (
+  maid_id TEXT PRIMARY KEY,
+  revision INTEGER NOT NULL,
+  state_json TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS event_receipt (
+  maid_id TEXT NOT NULL,
+  event_id TEXT NOT NULL,
+  command_hash TEXT NOT NULL,
+  host_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  occurred_at INTEGER NOT NULL,
+  received_at INTEGER NOT NULL,
+  effective_at INTEGER,
+  source_config_revision TEXT NOT NULL,
+  applied_config_revision TEXT NOT NULL,
+  status TEXT NOT NULL,
+  applied_revision INTEGER,
+  error_code TEXT,
+  audit_json TEXT NOT NULL,
+  PRIMARY KEY (maid_id, event_id)
+);
+`;
+function rowToReceipt(row) {
+	return {
+		maidId: row.maid_id,
+		eventId: row.event_id,
+		commandHash: row.command_hash,
+		hostId: row.host_id,
+		kind: row.kind,
+		occurredAt: row.occurred_at,
+		receivedAt: row.received_at,
+		effectiveAt: row.effective_at,
+		sourceConfigRevision: row.source_config_revision,
+		appliedConfigRevision: row.applied_config_revision,
+		status: row.status,
+		appliedRevision: row.applied_revision,
+		errorCode: row.error_code,
+		audit: JSON.parse(row.audit_json)
+	};
+}
+function openAuthorityStore(options) {
+	const readOnly = options.readOnly === true;
+	const dbFile = join(options.dataDir, "authority.db");
+	let lock;
+	if (!readOnly) lock = acquireDataDirLock(options.dataDir);
+	const db = new DatabaseSync(dbFile, readOnly ? { readOnly: true } : { readOnly: false });
+	if (!readOnly) {
+		try {
+			chmodSync(dbFile, 384);
+		} catch {}
+		db.exec("PRAGMA journal_mode=WAL");
+		db.exec("PRAGMA busy_timeout=5000");
+		db.exec("PRAGMA foreign_keys=ON");
+		db.exec(SCHEMA$1);
+	}
+	const metaGet = (key) => {
+		return db.prepare("SELECT value FROM meta WHERE key = ?").get(key)?.value;
+	};
+	let authorityId = metaGet("authorityId");
+	if (readOnly) {
+		if (authorityId === void 0) throw new Error(`maid-state: not a maid-state database (missing authorityId): ${dbFile}`);
+	} else if (authorityId === void 0) {
+		authorityId = randomUUID();
+		db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("authorityId", authorityId);
+	}
+	let txDepth = 0;
+	const requireTx = (op) => {
+		if (txDepth === 0) throw new Error(`maid-state: ${op} requires an active transaction (call store.transaction(...))`);
+	};
+	const readState = (maidId) => {
+		const row = db.prepare("SELECT revision, state_json FROM maid_state WHERE maid_id = ?").get(maidId);
+		return row === void 0 ? void 0 : {
+			state: JSON.parse(row.state_json),
+			revision: row.revision
+		};
+	};
+	const writeState = (maidId, value) => {
+		requireTx("writeState");
+		db.prepare("INSERT OR REPLACE INTO maid_state (maid_id, revision, state_json) VALUES (?, ?, ?)").run(maidId, value.revision, JSON.stringify(value.state));
+	};
+	const readReceipt = (maidId, eventId) => {
+		const row = db.prepare("SELECT * FROM event_receipt WHERE maid_id = ? AND event_id = ?").get(maidId, eventId);
+		return row === void 0 ? void 0 : rowToReceipt(row);
+	};
+	const writeReceipt = (receipt) => {
+		requireTx("writeReceipt");
+		db.prepare(`INSERT OR REPLACE INTO event_receipt (
+      maid_id, event_id, command_hash, host_id, kind, occurred_at, received_at, effective_at,
+      source_config_revision, applied_config_revision, status, applied_revision, error_code, audit_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(receipt.maidId, receipt.eventId, receipt.commandHash, receipt.hostId, receipt.kind, receipt.occurredAt, receipt.receivedAt, receipt.effectiveAt, receipt.sourceConfigRevision, receipt.appliedConfigRevision, receipt.status, receipt.appliedRevision, receipt.errorCode, JSON.stringify(receipt.audit));
+	};
+	return {
+		get authorityId() {
+			return authorityId;
+		},
+		readState,
+		writeState,
+		readReceipt,
+		writeReceipt,
+		transaction(fn) {
+			if (readOnly) throw new Error("maid-state: readOnly store cannot open transactions");
+			if (txDepth > 0) throw new Error("maid-state: nested transactions are not allowed");
+			db.exec("BEGIN IMMEDIATE");
+			txDepth = 1;
+			try {
+				const out = fn({
+					readState,
+					writeState,
+					readReceipt,
+					writeReceipt
+				});
+				db.exec("COMMIT");
+				return out;
+			} catch (error) {
+				txDepth = 0;
+				try {
+					db.exec("ROLLBACK");
+				} catch {}
+				throw error;
+			} finally {
+				txDepth = 0;
+			}
+		},
+		listEvents(filter) {
+			const clauses = [];
+			const params = [];
+			if (filter.maidId !== void 0) {
+				clauses.push("maid_id = ?");
+				params.push(filter.maidId);
+			}
+			if (filter.afterRevision !== void 0) {
+				clauses.push("(applied_revision IS NULL OR applied_revision > ?)");
+				params.push(filter.afterRevision);
+			}
+			const limit = Math.max(1, Math.min(500, Math.floor(filter.limit)));
+			const where = clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+			return db.prepare(`SELECT * FROM event_receipt${where} ORDER BY rowid LIMIT ?`).all(...params, limit).map(rowToReceipt);
+		},
+		exportStates() {
+			const rows = db.prepare("SELECT maid_id, revision, state_json FROM maid_state").all();
+			const out = {};
+			for (const row of rows) out[row.maid_id] = {
+				state: JSON.parse(row.state_json),
+				revision: row.revision
+			};
+			return out;
+		},
+		close() {
+			db.close();
+			lock?.release();
+		}
+	};
+}
+//#endregion
+//#region src/authority.ts
+var StateAuthority = class {
+	store;
+	domain;
+	now;
+	authorityId;
+	#chains = /* @__PURE__ */ new Map();
+	constructor(store, domain, now) {
+		this.store = store;
+		this.domain = domain;
+		this.now = now;
+		this.authorityId = store.authorityId;
+	}
+	/** 当前权威快照;fresh 状态不落库、不推进 revision */
+	snapshot(maidId) {
+		const entry = this.domain.config(maidId);
+		if (entry === void 0) throw new StateCommandError("UNKNOWN_MAID", `maid '${maidId}' has no config`);
+		const stored = this.store.readState(maidId);
+		return {
+			maidId,
+			stateRevision: stored?.revision ?? 0,
+			configRevision: entry.configRevision,
+			serverTime: this.now(),
+			state: stored?.state ?? this.domain.fresh(maidId, entry.config),
+			config: entry.config
+		};
+	}
+	submit(command) {
+		const next = (this.#chains.get(command.maidId) ?? Promise.resolve()).then(() => this.submitNow(command), () => this.submitNow(command));
+		this.#chains.set(command.maidId, next.catch(() => {}));
+		return next;
+	}
+	submitNow(command) {
+		try {
+			assertStateCommand(command);
+		} catch (error) {
+			return this.reject(command, error, "shape 校验失败(无法持久化回执时仅返回)");
+		}
+		const hash = commandHash(command);
+		const receivedAt = this.now();
+		return this.store.transaction((tx) => {
+			const prior = tx.readReceipt(command.maidId, command.eventId);
+			if (prior !== void 0) {
+				if (prior.commandHash === hash) return {
+					eventId: command.eventId,
+					status: prior.status === "applied" ? "duplicate" : "rejected",
+					appliedRevision: prior.appliedRevision,
+					snapshot: this.snapshotInTx(tx, command.maidId),
+					errorCode: prior.errorCode
+				};
+				return this.reject(command, new StateCommandError("EVENT_ID_CONFLICT", `eventId '${command.eventId}' reused with different content`), "conflict", tx);
+			}
+			const entry = this.domain.config(command.maidId);
+			if (entry === void 0) return this.reject(command, new StateCommandError("UNKNOWN_MAID", `maid '${command.maidId}' has no config`), "unknown maid", tx);
+			let applied;
+			try {
+				const stored = tx.readState(command.maidId);
+				applied = this.domain.apply({
+					state: stored?.state ?? this.domain.fresh(command.maidId, entry.config),
+					command,
+					config: entry.config,
+					receivedAt
+				});
+			} catch (error) {
+				if (error instanceof StateCommandError) return this.reject(command, error, "domain reject", tx);
+				throw error;
+			}
+			const revision = (tx.readState(command.maidId)?.revision ?? 0) + 1;
+			tx.writeState(command.maidId, {
+				state: applied.state,
+				revision
+			});
+			tx.writeReceipt({
+				maidId: command.maidId,
+				eventId: command.eventId,
+				commandHash: hash,
+				hostId: command.hostId,
+				kind: command.kind,
+				occurredAt: command.occurredAt,
+				receivedAt,
+				effectiveAt: applied.effectiveAt,
+				sourceConfigRevision: command.sourceConfigRevision,
+				appliedConfigRevision: entry.configRevision,
+				status: "applied",
+				appliedRevision: revision,
+				errorCode: null,
+				audit: applied.audit
+			});
+			return {
+				eventId: command.eventId,
+				status: "applied",
+				appliedRevision: revision,
+				snapshot: this.snapshotInTx(tx, command.maidId),
+				errorCode: null
+			};
+		});
+	}
+	/** 拒绝回执:maidId 可用时持久化(幂等复述),不可用时(坏形状)仅返回 */
+	reject(command, error, reason, tx) {
+		const code = error instanceof StateCommandError ? error.code : "INTERNAL";
+		const message = error instanceof Error ? error.message : String(error);
+		const receipt = {
+			maidId: command.maidId,
+			eventId: command.eventId,
+			commandHash: safeHash(command),
+			hostId: command.hostId,
+			kind: command.kind,
+			occurredAt: command.occurredAt,
+			receivedAt: this.now(),
+			effectiveAt: null,
+			sourceConfigRevision: command.sourceConfigRevision,
+			appliedConfigRevision: "",
+			status: "rejected",
+			appliedRevision: null,
+			errorCode: code,
+			audit: {
+				reason,
+				message
+			}
+		};
+		const persist = (writer) => {
+			if (typeof command.maidId === "string" && command.maidId.length > 0 && typeof command.eventId === "string" && command.eventId.length > 0) writer.writeReceipt(receipt);
+		};
+		if (tx !== void 0) {
+			persist(tx);
+			let snapshot = null;
+			try {
+				snapshot = this.snapshotInTx(tx, command.maidId);
+			} catch {}
+			return {
+				eventId: command.eventId,
+				status: "rejected",
+				appliedRevision: null,
+				snapshot,
+				errorCode: code
+			};
+		}
+		if (typeof command.maidId === "string" && command.maidId.length > 0) try {
+			this.store.transaction((writer) => persist(writer));
+			let snapshot = null;
+			try {
+				snapshot = this.snapshot(command.maidId);
+			} catch {}
+			return {
+				eventId: command.eventId,
+				status: "rejected",
+				appliedRevision: null,
+				snapshot,
+				errorCode: code
+			};
+		} catch {}
+		return {
+			eventId: command.eventId,
+			status: "rejected",
+			appliedRevision: null,
+			snapshot: null,
+			errorCode: code
+		};
+	}
+	/** 事务内快照(与公开 snapshot 同语义,读未提交的本事务写入) */
+	snapshotInTx(tx, maidId) {
+		const entry = this.domain.config(maidId);
+		if (entry === void 0) throw new StateCommandError("UNKNOWN_MAID", `maid '${maidId}' has no config`);
+		const stored = tx.readState(maidId);
+		return {
+			maidId,
+			stateRevision: stored?.revision ?? 0,
+			configRevision: entry.configRevision,
+			serverTime: this.now(),
+			state: stored?.state ?? this.domain.fresh(maidId, entry.config),
+			config: entry.config
+		};
+	}
+};
+function safeHash(command) {
+	try {
+		return commandHash(command);
+	} catch {
+		return "unhashable";
+	}
+}
+//#endregion
+//#region src/tls.ts
+function normalizeFingerprint(fp) {
+	return fp.replaceAll(":", "").trim().toUpperCase();
+}
+function loadKeyCertCa(input) {
+	return {
+		key: readFileSync(input.keyFile, "utf8"),
+		cert: readFileSync(input.certFile, "utf8"),
+		ca: readFileSync(input.caFile, "utf8")
+	};
+}
+/** 证书指纹 → host 身份映射(未登记指纹返回 undefined) */
+function identityOfPeer(clients, peerFingerprint256) {
+	if (peerFingerprint256 === void 0) return void 0;
+	const normalized = normalizeFingerprint(peerFingerprint256);
+	return clients.find((c) => normalizeFingerprint(c.fingerprint256) === normalized);
+}
+function maidAllowed(identity, maidId) {
+	return identity.allowMaids === void 0 || identity.allowMaids.includes(maidId);
+}
+//#endregion
+//#region src/http-server.ts
+/**
+* mTLS HTTP 传输·server 面(maid-state 阶段规格 §6.4 信封/§10.3 授权):
+* - 成功响应 { authorityId, payload },错误响应 { authorityId, error: { code, message } };
+* - hostId 只信证书指纹映射,body 自报 hostId 与证书不一致 → 403;
+* - body 上限 2 MiB(413);坏 JSON 400;domain 拒绝 = 200+rejected 回执(稳定码);
+*   未知内部异常 = 500 TEMPORARY(client 可重试);
+* - 不回显请求 payload;本层不 console,日志由调用方注入。
+*/
+const MAX_BODY_BYTES = 2097152;
+function startStateHttpServer(input) {
+	const { authority, store } = input;
+	const material = loadKeyCertCa(input.tls);
+	const server = createServer({
+		key: material.key,
+		cert: material.cert,
+		ca: material.ca,
+		requestCert: true,
+		rejectUnauthorized: true,
+		minVersion: "TLSv1.2"
+	});
+	const send = (res, status, body) => {
+		const payload = JSON.stringify(body);
+		res.writeHead(status, {
+			"content-type": "application/json",
+			"content-length": Buffer.byteLength(payload)
+		});
+		res.end(payload);
+	};
+	const sendError = (res, status, code, message) => {
+		send(res, status, {
+			authorityId: authority.authorityId,
+			error: {
+				code,
+				message
+			}
+		});
+	};
+	server.on("request", (req, res) => {
+		const peer = req.socket;
+		const identity = identityOfPeer(input.tls.clients, peer.getPeerCertificate?.()?.fingerprint256);
+		if (req.url === "/v1/health") {
+			send(res, 200, {
+				authorityId: authority.authorityId,
+				payload: {
+					authorityId: authority.authorityId,
+					protocolVersion: 1
+				}
+			});
+			return;
+		}
+		if (identity === void 0) {
+			sendError(res, 403, "IDENTITY_UNKNOWN", "client certificate is not registered");
+			return;
+		}
+		if (req.url === "/v1/status" && req.method === "GET") {
+			const states = store.exportStates();
+			send(res, 200, {
+				authorityId: authority.authorityId,
+				payload: {
+					authorityId: authority.authorityId,
+					protocolVersion: 1,
+					maids: Object.entries(states).map(([maidId, s]) => ({
+						maidId,
+						stateRevision: s.revision
+					}))
+				}
+			});
+			return;
+		}
+		if ((req.url ?? "").startsWith("/v1/events") && req.method === "GET") {
+			const query = new URL(req.url ?? "/v1/events", "https://localhost").searchParams;
+			const limitRaw = query.get("limit");
+			const afterRaw = query.get("afterRevision");
+			const limit = limitRaw === null ? 100 : Number(limitRaw);
+			const afterRevision = afterRaw === null ? void 0 : Number(afterRaw);
+			if (!Number.isFinite(limit) || afterRevision !== void 0 && !Number.isFinite(afterRevision)) {
+				sendError(res, 400, "BAD_QUERY", "afterRevision/limit query invalid");
+				return;
+			}
+			const filter = {
+				...query.get("maidId") !== null ? { maidId: query.get("maidId") } : {},
+				...afterRevision !== void 0 ? { afterRevision } : {},
+				limit
+			};
+			const events = store.listEvents(filter);
+			send(res, 200, {
+				authorityId: authority.authorityId,
+				payload: { events }
+			});
+			return;
+		}
+		const snapshotMatch = /^\/v1\/maids\/([^/]+)\/snapshot$/.exec(req.url ?? "");
+		if (snapshotMatch !== null && req.method === "GET") {
+			const maidId = decodeURIComponent(snapshotMatch[1]);
+			if (!maidAllowed(identity, maidId)) {
+				sendError(res, 403, "FORBIDDEN", `maid '${maidId}' not allowed for host '${identity.hostId}'`);
+				return;
+			}
+			let snapshot;
+			try {
+				snapshot = authority.snapshot(maidId);
+			} catch (error) {
+				sendError(res, 404, "UNKNOWN_MAID", error.message);
+				return;
+			}
+			send(res, 200, {
+				authorityId: authority.authorityId,
+				payload: { snapshot }
+			});
+			return;
+		}
+		const commandsMatch = /^\/v1\/maids\/([^/]+)\/commands$/.exec(req.url ?? "");
+		if (commandsMatch !== null && req.method === "POST") {
+			const maidId = decodeURIComponent(commandsMatch[1]);
+			if (!maidAllowed(identity, maidId)) {
+				sendError(res, 403, "FORBIDDEN", `maid '${maidId}' not allowed for host '${identity.hostId}'`);
+				return;
+			}
+			const chunks = [];
+			let size = 0;
+			let aborted = false;
+			req.on("data", (chunk) => {
+				if (aborted) return;
+				size += chunk.length;
+				if (size > MAX_BODY_BYTES) {
+					aborted = true;
+					sendError(res, 413, "BODY_TOO_LARGE", `body exceeds ${MAX_BODY_BYTES} bytes`);
+					req.resume();
+					return;
+				}
+				chunks.push(chunk);
+			});
+			req.on("end", () => {
+				if (aborted) return;
+				let command;
+				try {
+					command = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+				} catch {
+					sendError(res, 400, "BAD_JSON", "request body is not valid JSON");
+					return;
+				}
+				const claimed = command?.hostId;
+				if (claimed !== identity.hostId) {
+					sendError(res, 403, "FORBIDDEN", `body hostId '${String(claimed)}' does not match certificate identity '${identity.hostId}'`);
+					return;
+				}
+				if (command?.maidId !== maidId) {
+					sendError(res, 400, "MAID_MISMATCH", "path maidId does not match command maidId");
+					return;
+				}
+				authority.submit(command).then((receipt) => send(res, 200, {
+					authorityId: authority.authorityId,
+					payload: { receipt }
+				}), () => sendError(res, 500, "TEMPORARY", "command application failed; safe to retry"));
+			});
+			return;
+		}
+		sendError(res, 404, "NOT_FOUND", `no route for ${req.method} ${req.url}`);
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(input.listen.port, input.listen.host, () => {
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : input.listen.port;
+			resolve({
+				url: `https://${input.listen.host}:${port}`,
+				authorityId: authority.authorityId,
+				close: () => new Promise((done) => server.close(() => done()))
+			});
+		});
+	});
+}
+//#endregion
+//#region src/http-client.ts
+var StateHttpClient = class {
+	#config;
+	#material;
+	#closed = false;
+	constructor(config) {
+		this.#config = {
+			requestTimeoutMs: 5e3,
+			...config
+		};
+		this.#material = loadKeyCertCa(config);
+	}
+	async getSnapshot(maidId) {
+		return (await this.#call("GET", `/v1/maids/${encodeURIComponent(maidId)}/snapshot`)).snapshot;
+	}
+	async submit(command) {
+		return (await this.#call("POST", `/v1/maids/${encodeURIComponent(command.maidId)}/commands`, command)).receipt;
+	}
+	async health() {
+		return await this.#call("GET", "/v1/health");
+	}
+	async status() {
+		return await this.#call("GET", "/v1/status");
+	}
+	async listEvents(filter) {
+		const params = new URLSearchParams({ limit: String(filter.limit) });
+		if (filter.maidId !== void 0) params.set("maidId", filter.maidId);
+		if (filter.afterRevision !== void 0) params.set("afterRevision", String(filter.afterRevision));
+		return (await this.#call("GET", `/v1/events?${params.toString()}`)).events;
+	}
+	close() {
+		this.#closed = true;
+	}
+	#call(method, path, body) {
+		if (this.#closed) return Promise.reject(/* @__PURE__ */ new Error("maid-state client closed"));
+		const payload = body === void 0 ? void 0 : JSON.stringify(body);
+		const url = new URL(path, this.#config.url);
+		return new Promise((resolve, reject) => {
+			const options = {
+				method,
+				hostname: url.hostname,
+				port: url.port,
+				path: `${url.pathname}${url.search}`,
+				key: this.#material.key,
+				cert: this.#material.cert,
+				ca: this.#material.ca,
+				timeout: this.#config.requestTimeoutMs,
+				headers: { ...payload !== void 0 ? {
+					"content-type": "application/json",
+					"content-length": Buffer.byteLength(payload)
+				} : {} },
+				checkServerIdentity: (host, cert) => {
+					const hostnameError = checkServerIdentity(host, cert);
+					if (hostnameError !== void 0) return hostnameError;
+					if (cert.fingerprint256 === void 0 || normalizeFingerprint(cert.fingerprint256) !== normalizeFingerprint(this.#config.serverFingerprint256)) return /* @__PURE__ */ new Error(`server fingerprint mismatch (expected ${this.#config.serverFingerprint256})`);
+				}
+			};
+			const req = request(options, (res) => {
+				const chunks = [];
+				res.on("data", (chunk) => chunks.push(chunk));
+				res.on("end", () => {
+					const status = res.statusCode ?? 0;
+					let envelope;
+					try {
+						envelope = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+					} catch {
+						reject(/* @__PURE__ */ new Error(`maid-state: non-JSON response (status ${status})`));
+						return;
+					}
+					if (envelope?.authorityId !== void 0 && envelope.authorityId !== this.#config.authorityId) {
+						reject(new StateCommandError("AUTHORITY_MISMATCH", `expected authority ${this.#config.authorityId}, got ${envelope.authorityId}`));
+						return;
+					}
+					if (envelope?.error !== void 0) {
+						reject(new StateCommandError(envelope.error.code, envelope.error.message));
+						return;
+					}
+					if (status < 200 || status >= 300 || envelope?.payload === void 0) {
+						reject(/* @__PURE__ */ new Error(`maid-state: unexpected response (status ${status})`));
+						return;
+					}
+					resolve(envelope.payload);
+				});
+				res.on("error", (err) => reject(err));
+			});
+			req.on("error", (err) => reject(err));
+			req.on("timeout", () => {
+				req.destroy();
+				reject(/* @__PURE__ */ new Error(`maid-state: request timeout after ${this.#config.requestTimeoutMs}ms`));
+			});
+			if (payload !== void 0) req.write(payload);
+			req.end();
+		});
+	}
+};
+//#endregion
+//#region src/client-journal.ts
+const DEFAULT_MAX_PENDING = 1e3;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS commands (
+  maid_id TEXT NOT NULL,
+  event_id TEXT NOT NULL,
+  turn_key TEXT,
+  kind TEXT NOT NULL,
+  status TEXT NOT NULL,
+  occurred_at INTEGER NOT NULL,
+  command_hash TEXT,
+  payload_json TEXT,
+  source_config_revision TEXT,
+  applied_revision INTEGER,
+  error_code TEXT,
+  PRIMARY KEY (maid_id, event_id)
+);
+CREATE TABLE IF NOT EXISTS snapshots (
+  maid_id TEXT PRIMARY KEY,
+  state_revision INTEGER NOT NULL,
+  config_revision TEXT NOT NULL,
+  server_time INTEGER NOT NULL,
+  snapshot_json TEXT NOT NULL
+);
+`;
+function rowToCommand(row) {
+	if (row.payload_json === null) return void 0;
+	return JSON.parse(row.payload_json);
+}
+var ClientJournal = class {
+	#db;
+	#hostId;
+	#maxPending;
+	constructor(options) {
+		mkdirSync(dirname(options.file), { recursive: true });
+		this.#db = new DatabaseSync(options.file, { readOnly: false });
+		try {
+			chmodSync(options.file, 384);
+		} catch {}
+		this.#db.exec("PRAGMA journal_mode=WAL");
+		this.#db.exec(SCHEMA);
+		this.#hostId = options.hostId;
+		this.#maxPending = options.maxPendingEvents ?? DEFAULT_MAX_PENDING;
+	}
+	#rowOf(maidId, eventId) {
+		return this.#db.prepare("SELECT * FROM commands WHERE maid_id = ? AND event_id = ?").get(maidId, eventId);
+	}
+	#pendingCount(maidId) {
+		return this.#db.prepare("SELECT COUNT(*) AS n FROM commands WHERE maid_id = ? AND status IN ('reserved','awaiting_config','pending')").get(maidId).n;
+	}
+	/** turn 预留(判分前):turnKey 查重(hostId 用本 journal 构造身份,调用方无须知晓),新轮插入 reserved */
+	reserveTurn(input) {
+		const eventId = turnEventId({
+			hostId: this.#hostId,
+			sessionId: input.sessionId,
+			turn: input.turn
+		});
+		return this.#reserveInTx(eventId, input);
+	}
+	#reserveInTx(eventId, input) {
+		const existing = this.#rowOf(input.maidId, eventId);
+		if (existing !== void 0) {
+			if (existing.status === "reserved" || existing.status === "awaiting_config") return {
+				kind: "resume",
+				eventId,
+				draft: existing.payload_json === null ? input.draft : JSON.parse(existing.payload_json)
+			};
+			return {
+				kind: "duplicate",
+				eventId
+			};
+		}
+		if (this.#pendingCount(input.maidId) >= this.#maxPending) return {
+			kind: "full",
+			eventId: null
+		};
+		this.#db.prepare("INSERT INTO commands (maid_id, event_id, turn_key, kind, status, occurred_at, payload_json) VALUES (?, ?, ?, 'emotion.settle_turn', 'reserved', ?, ?)").run(input.maidId, eventId, `${this.#hostId}\n${input.sessionId}\n${input.turn}`, input.occurredAt, JSON.stringify(input.draft));
+		return {
+			kind: "new",
+			eventId,
+			draft: input.draft
+		};
+	}
+	/** 预留记录查询(reserved/awaiting/pending/acked/failed 任意状态;draft 仅预留态有语义) */
+	reservationOf(eventId) {
+		const row = this.#findByEventId(eventId);
+		return row === void 0 ? void 0 : {
+			maidId: row.maid_id,
+			status: row.status
+		};
+	}
+	/** reserved/awaiting_config → pending(定稿):draft 从预留行内部取(builder 组装完整 payload) */
+	finalizeTurn(input) {
+		const found = this.#findByEventId(input.eventId);
+		if (found === void 0 || found.status !== "reserved" && found.status !== "awaiting_config") return null;
+		const draft = found.payload_json === null ? {} : JSON.parse(found.payload_json);
+		const command = {
+			protocolVersion: 1,
+			eventId: found.event_id,
+			hostId: this.#hostId,
+			maidId: found.maid_id,
+			kind: "emotion.settle_turn",
+			occurredAt: found.occurred_at,
+			sourceConfigRevision: input.sourceConfigRevision,
+			payload: input.build(draft)
+		};
+		this.#db.prepare("UPDATE commands SET status = 'pending', payload_json = ?, command_hash = ?, source_config_revision = ? WHERE maid_id = ? AND event_id = ?").run(JSON.stringify(command), commandHash(command), input.sourceConfigRevision, found.maid_id, found.event_id);
+		return command;
+	}
+	#findByEventId(eventId) {
+		return this.#db.prepare("SELECT * FROM commands WHERE event_id = ?").get(eventId);
+	}
+	/** gesture/reunion/manual:一次性持久化完整命令(幂等:重复 eventId 直接接受) */
+	enqueueCommand(command) {
+		if (this.#rowOf(command.maidId, command.eventId) !== void 0) return true;
+		if (this.#pendingCount(command.maidId) >= this.#maxPending) return false;
+		this.#db.prepare("INSERT INTO commands (maid_id, event_id, turn_key, kind, status, occurred_at, command_hash, payload_json, source_config_revision) VALUES (?, ?, NULL, ?, 'pending', ?, ?, ?, ?)").run(command.maidId, command.eventId, command.kind, command.occurredAt, commandHash(command), JSON.stringify(command), command.sourceConfigRevision);
+		return true;
+	}
+	/** reserved → awaiting_config(无配置快照的本地保留);仅 reserved 可转 */
+	markAwaitingConfig(eventId) {
+		const row = this.#findByEventId(eventId);
+		if (row === void 0 || row.status !== "reserved") return false;
+		this.#db.prepare("UPDATE commands SET status = 'awaiting_config' WHERE maid_id = ? AND event_id = ?").run(row.maid_id, eventId);
+		return true;
+	}
+	listAwaitingConfig(maidId) {
+		return this.#db.prepare("SELECT * FROM commands WHERE maid_id = ? AND status = 'awaiting_config' ORDER BY rowid").all(maidId).map((r) => ({
+			eventId: r.event_id,
+			kind: r.kind,
+			occurredAt: r.occurred_at,
+			draft: r.payload_json === null ? void 0 : JSON.parse(r.payload_json)
+		}));
+	}
+	listPending(maidId) {
+		return this.#db.prepare("SELECT * FROM commands WHERE maid_id = ? AND status = 'pending' ORDER BY rowid").all(maidId).map(rowToCommand).filter((c) => c !== void 0);
+	}
+	/** 确认:pending → acked,清 payload(原文清理),可选保存权威快照(revision 守卫) */
+	markAcked(eventId, ack) {
+		const row = this.#findByEventId(eventId);
+		if (row === void 0) return;
+		this.#db.prepare("UPDATE commands SET status = 'acked', applied_revision = ?, payload_json = NULL WHERE maid_id = ? AND event_id = ?").run(ack.appliedRevision, row.maid_id, eventId);
+		if (ack.snapshot !== void 0) this.saveSnapshot(ack.snapshot);
+	}
+	/** 永久失败:pending → failed,payload 保留供显式导出(不自动删除) */
+	markFailed(eventId, errorCode) {
+		const row = this.#findByEventId(eventId);
+		if (row === void 0) return;
+		this.#db.prepare("UPDATE commands SET status = 'failed', error_code = ? WHERE maid_id = ? AND event_id = ?").run(errorCode, row.maid_id, eventId);
+	}
+	exportFailed() {
+		return this.#db.prepare("SELECT * FROM commands WHERE status = 'failed' ORDER BY rowid").all().map((r) => ({
+			maidId: r.maid_id,
+			eventId: r.event_id,
+			command: rowToCommand(r),
+			errorCode: r.error_code
+		}));
+	}
+	/** 快照缓存:旧 revision 不回退;同 revision 允许新 serverTime(不回退)/config 更新 */
+	saveSnapshot(snapshot) {
+		const existing = this.#db.prepare("SELECT * FROM snapshots WHERE maid_id = ?").get(snapshot.maidId);
+		if (existing !== void 0) {
+			if (snapshot.stateRevision < existing.state_revision) return;
+			if (snapshot.stateRevision === existing.state_revision && snapshot.serverTime <= existing.server_time) {
+				if (snapshot.configRevision === existing.config_revision) return;
+			}
+		}
+		this.#db.prepare("INSERT OR REPLACE INTO snapshots (maid_id, state_revision, config_revision, server_time, snapshot_json) VALUES (?, ?, ?, ?, ?)").run(snapshot.maidId, snapshot.stateRevision, snapshot.configRevision, snapshot.serverTime, JSON.stringify(snapshot));
+	}
+	/** 已知 maid 全集(快照 ∪ 命令表;M3h 预备状态面用)。 */
+	listMaids() {
+		const rows = this.#db.prepare("SELECT maid_id AS maid FROM snapshots UNION SELECT maid_id AS maid FROM commands").all();
+		return [...new Set(rows.map((row) => row.maid))];
+	}
+	readSnapshot(maidId) {
+		const row = this.#db.prepare("SELECT snapshot_json FROM snapshots WHERE maid_id = ?").get(maidId);
+		return row === void 0 ? void 0 : JSON.parse(row.snapshot_json);
+	}
+	close() {
+		this.#db.close();
+	}
+};
+//#endregion
+//#region src/remote-client.ts
+const DEFAULT_RETRY_INITIAL_MS = 1e3;
+const DEFAULT_RETRY_MAX_MS = 12e4;
+var RemoteStateClient = class {
+	journal;
+	#options;
+	#transport;
+	#project;
+	#chains = /* @__PURE__ */ new Map();
+	#timers = /* @__PURE__ */ new Map();
+	#closed = false;
+	constructor(options) {
+		this.journal = options.journal;
+		this.#transport = options.transport;
+		this.#project = options.project;
+		this.#options = {
+			now: options.now ?? (() => Date.now()),
+			random: options.random ?? Math.random,
+			retryInitialMs: options.retryInitialMs ?? DEFAULT_RETRY_INITIAL_MS,
+			retryMaxMs: options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS
+		};
+	}
+	/** 同步读:base 快照 + pending 重算;无快照 → undefined(不注情绪、不发网络) */
+	read(maidId) {
+		const base = this.journal.readSnapshot(maidId);
+		if (base === void 0) return void 0;
+		const pending = this.journal.listPending(maidId);
+		const now = this.#options.now();
+		return {
+			state: this.#project(base, pending, now),
+			config: base.config,
+			stateRevision: base.stateRevision,
+			configRevision: base.configRevision,
+			staleSince: Math.max(0, now - base.serverTime),
+			outboxDepth: pending.length
+		};
+	}
+	/** 权威快照刷新:成功后 read() 以新 base 重算;失败沿用缓存(向调用方上抛由其决定) */
+	async refresh(maidId) {
+		return await this.#enqueue(maidId, async () => {
+			const snapshot = await this.#transport.getSnapshot(maidId);
+			this.journal.saveSnapshot(snapshot);
+			this.#lastOkAt = this.#options.now();
+		});
+	}
+	/** FIFO flush(显式调用):成功重置退避;网络/临时错误中断并上抛(已 ack 的不回退) */
+	async flush(maidId) {
+		return await this.#enqueue(maidId, async () => this.#runFlush(maidId, true));
+	}
+	async #runFlush(maidId, manual) {
+		this.#timers.delete(maidId);
+		if (manual) this.#retryAttempts.set(maidId, 0);
+		for (;;) {
+			const [command] = this.journal.listPending(maidId);
+			if (command === void 0) return;
+			try {
+				const receipt = await this.#transport.submit(command);
+				if (receipt.status === "applied" || receipt.status === "duplicate") {
+					this.journal.markAcked(command.eventId, {
+						appliedRevision: receipt.appliedRevision,
+						...receipt.snapshot !== null ? { snapshot: receipt.snapshot } : {}
+					});
+					this.#lastOkAt = this.#options.now();
+					continue;
+				}
+				this.journal.markFailed(command.eventId, receipt.errorCode);
+				if (receipt.snapshot !== null) this.journal.saveSnapshot(receipt.snapshot);
+			} catch (error) {
+				if (error instanceof StateCommandError) throw error;
+				this.#scheduleRetry(maidId);
+				throw error;
+			}
+		}
+	}
+	close() {
+		this.#closed = true;
+		for (const timer of this.#timers.values()) clearTimeout(timer);
+		this.#timers.clear();
+	}
+	/** 指数退避 + 抖动:min(max, initial×2^n);timer unref */
+	#scheduleRetry(maidId) {
+		if (this.#closed) return;
+		if (this.#timers.get(maidId) !== void 0) return;
+		const attempt = this.#retryAttempts.get(maidId) ?? 0;
+		this.#retryAttempts.set(maidId, attempt + 1);
+		const delay = Math.min(this.#options.retryMaxMs, this.#options.retryInitialMs * 2 ** attempt);
+		const jitter = Math.floor(delay * .2 * this.#options.random());
+		const timer = setTimeout(() => {
+			this.#timers.delete(maidId);
+			this.#enqueue(maidId, async () => this.#runFlush(maidId, false)).catch(() => {});
+		}, delay + jitter);
+		timer.unref();
+		this.#timers.set(maidId, timer);
+	}
+	#retryAttempts = /* @__PURE__ */ new Map();
+	#lastOkAt = null;
+	/** 可观测快照(M3h 预备):lastOkAt + 逐 maid 缓存陈旧度/outbox 深度;同步读不发网络。 */
+	status() {
+		return {
+			lastOkAt: this.#lastOkAt,
+			closed: this.#closed,
+			maids: this.journal.listMaids().map((maidId) => {
+				const base = this.journal.readSnapshot(maidId);
+				const pending = this.journal.listPending(maidId).length;
+				if (base === void 0) return {
+					maidId,
+					hasSnapshot: false,
+					stateRevision: 0,
+					staleSince: null,
+					outboxDepth: pending
+				};
+				const now = this.#options.now();
+				return {
+					maidId,
+					hasSnapshot: true,
+					stateRevision: base.stateRevision,
+					staleSince: Math.max(0, now - base.serverTime),
+					outboxDepth: pending
+				};
+			})
+		};
+	}
+	/** per-maid 串行链:前序失败不阻断本命令;closed 后拒绝 */
+	async #enqueue(maidId, run) {
+		if (this.#closed) throw new Error("maid-state remote client closed");
+		const next = (this.#chains.get(maidId) ?? Promise.resolve()).then(run, run);
+		this.#chains.set(maidId, next.catch(() => {}));
+		return await next;
+	}
+};
+//#endregion
+//#region src/embedded-transport.ts
+/**
+* M3j 内嵌传输(规格 §9.2):直接调用同进程 StateAuthority——无网络监听、无 TLS、
+* 无序列化边界。embedded 后端与 HTTP client 共用同一权威/命令/回执/revision 语义,
+* 由结构保证「同一输入同一结果」;唯一权威仍是 authority.db,本 transport 不持状态。
+*/
+var EmbeddedStateTransport = class {
+	authority;
+	constructor(authority) {
+		this.authority = authority;
+	}
+	async getSnapshot(maidId) {
+		return this.authority.snapshot(maidId);
+	}
+	async submit(command) {
+		return await this.authority.submit(command);
+	}
+};
+//#endregion
+export { ClientJournal, EmbeddedStateTransport, PROTOCOL_VERSION, RemoteStateClient, StateAuthority, StateCommandError, StateHttpClient, acquireDataDirLock, assertStateCommand, canonicalJson, commandHash, identityOfPeer, loadKeyCertCa, maidAllowed, newEventId, normalizeFingerprint, openAuthorityStore, revisionOf, startStateHttpServer, turnEventId };