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

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/index.d.ts

@@ -0,0 +1,411 @@
+//#region src/protocol.d.ts
+/**
+ * maid-state 协议信封(阶段规格 §6,2026-11-06):传输无关的命令/快照/回执三件套。
+ * 稳定性纪律:
+ * - turn eventId 派生命名空间 'emotion.turn.v1' 与 commandHash 的语义字段集都**不随
+ *   线 protocolVersion 变化**(升级后重放旧命令不得被当成新事件/新冲突);
+ * - canonicalJson 键排序用代码点比较,不用 localeCompare(ICU 随构建漂移会破哈希稳定性)。
+ */
+declare const PROTOCOL_VERSION = 1;
+type EventKind = 'emotion.settle_turn' | 'emotion.apply_deltas';
+interface StateCommand<P = unknown> {
+  protocolVersion: number;
+  eventId: string;
+  hostId: string;
+  maidId: string;
+  kind: EventKind;
+  occurredAt: number;
+  sourceConfigRevision: string;
+  payload: P;
+}
+interface StateSnapshot<S, C> {
+  maidId: string;
+  stateRevision: number;
+  configRevision: string;
+  serverTime: number;
+  state: S;
+  config: C;
+}
+interface CommandReceipt<S, C> {
+  eventId: string;
+  status: 'applied' | 'duplicate' | 'rejected';
+  appliedRevision: number | null;
+  snapshot: StateSnapshot<S, C> | null;
+  errorCode: string | null;
+}
+/** 传输接缝(in-memory 假件与 HTTPS+mTLS 实现同面;maid-state 不认识具体 domain) */
+interface StateTransport<S, C> {
+  getSnapshot(maidId: string): Promise<StateSnapshot<S, C>>;
+  submit(command: StateCommand): Promise<CommandReceipt<S, C>>;
+}
+/** 稳定机器码错误(规格 §11:永久协议错误与临时网络错误必须分开) */
+declare class StateCommandError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/** 确定性 JSON 序列化:键代码点排序、剔除 undefined;数字/字符串走 JSON 标准形态 */
+declare function canonicalJson(value: unknown): string;
+declare function revisionOf(value: unknown): string;
+/** UUIDv7(时间有序,重试语义友好);eventId 手势/重逢/补偿通道使用 */
+declare function newEventId(now?: number): string;
+/** turn 命令稳定身份:turnKey 派生(规格 §6.1),宿主会话/轮次重放复用同一 eventId */
+declare function turnEventId(input: {
+  hostId: string;
+  sessionId: string;
+  turn: number;
+}): string;
+/** 语义命令哈希:只覆盖领域语义字段,不含 protocolVersion/传输元数据(规格 §6.1) */
+declare function commandHash(command: StateCommand): string;
+/** 入站命令形状守卫(规格 §6.1):协议版本/必填串/有限时间/payload 对象 */
+declare function assertStateCommand(value: unknown): asserts value is StateCommand;
+//#endregion
+//#region src/lock.d.ts
+/**
+ * server 数据目录排他锁(maid-state 阶段规格 §10.1):防第二活跃实例双写同库。
+ * - 锁体 {pid, startedAt, heartbeatAt},heartbeat 5s 刷新(unref,不阻进程退出);
+ * - 回收判定按持锁进程存活性:PID 已死(ESRCH)→ 回收;活进程(含 EPERM)→ 一律拒绝,
+ *   即便 heartbeat 过期也不抢(挂死服务器留给人工处置,不引入双开风险);
+ * - Windows 不改 ACL,目录边界由宿主用户目录承担(部署文档声明)。
+ */
+interface DataDirLock {
+  readonly pid: number;
+  /** 停止 heartbeat 并删除自持锁文件(幂等) */
+  release(): void;
+}
+declare function acquireDataDirLock(dataDir: string): DataDirLock;
+//#endregion
+//#region src/authority-store.d.ts
+/**
+ * 权威事务存储(maid-state 阶段规格 §6.3/§10.1):SQLite 单库承载 maid 状态、revision、
+ * 事件回执与 meta(authorityId/协议版本)。纪律:
+ * - 状态更新、revision、事件去重记录**同事务**(write 方法仅可在 transaction() 内调用);
+ * - 第二活跃实例经数据目录排他锁拒绝;死 PID 残留锁回收;
+ * - readOnly 形态供运行中 server 的只读 CLI(status/events/export):不开写锁、禁止事务;
+ * - S 为不透明状态(domain 负责形状);存储层只做 JSON 序列化。
+ */
+interface StoredAuthorityState<S> {
+  state: S;
+  revision: number;
+}
+interface StoredReceipt {
+  maidId: string;
+  eventId: string;
+  commandHash: string;
+  hostId: string;
+  kind: string;
+  occurredAt: number;
+  receivedAt: number;
+  effectiveAt: number | null;
+  sourceConfigRevision: string;
+  appliedConfigRevision: string;
+  status: string;
+  appliedRevision: number | null;
+  errorCode: string | null;
+  audit: Record<string, unknown>;
+}
+interface AuthorityTransaction<S> {
+  readState(maidId: string): StoredAuthorityState<S> | undefined;
+  writeState(maidId: string, value: StoredAuthorityState<S>): void;
+  readReceipt(maidId: string, eventId: string): StoredReceipt | undefined;
+  writeReceipt(receipt: StoredReceipt): void;
+}
+interface ListEventsFilter {
+  maidId?: string;
+  afterRevision?: number;
+  limit: number;
+}
+interface AuthorityStore<S> extends AuthorityTransaction<S> {
+  readonly authorityId: string;
+  transaction<T>(fn: (tx: AuthorityTransaction<S>) => T): T;
+  listEvents(filter: ListEventsFilter): StoredReceipt[];
+  exportStates(): Record<string, StoredAuthorityState<S>>;
+  close(): void;
+}
+interface OpenAuthorityStoreOptions {
+  dataDir: string;
+  /** 只读形态(CLI status/events/export):不取排他锁、禁止事务/写方法 */
+  readOnly?: boolean;
+}
+declare function openAuthorityStore<S>(options: OpenAuthorityStoreOptions): AuthorityStore<S>;
+//#endregion
+//#region src/authority.d.ts
+/**
+ * per-maid 权威服务(maid-state 阶段规格 §4.2/§8.2):领域无关的串行结算与幂等层。
+ * - StateDomain 是 domain 接缝(emotion/未来 world 各自实现 apply/config/fresh);
+ * - 同 maid 全部写命令经 Promise 链串行,不同 maid 并行;
+ * - 幂等键 (maidId,eventId):applied+同 hash → duplicate(返回当前快照,不用陈旧历史快照
+ *   覆盖);rejected+同 hash → 原样复述;任意 status+异 hash → EVENT_ID_CONFLICT;
+ * - StateCommandError = 永久拒绝(落 rejected 回执、不动状态、不推进 revision);
+ *   未知异常向上抛(传输层转临时 500),链尾兜底 catch 防一次失败毒死后续。
+ */
+interface StateDomain<S, C> {
+  /** maid 配置(权威配置源);undefined = 未注册 maid(UNKNOWN_MAID) */
+  config(maidId: string): {
+    config: C;
+    configRevision: string;
+  } | undefined;
+  fresh(maidId: string, config: C): S;
+  apply(input: {
+    state: S;
+    command: StateCommand;
+    config: C;
+    receivedAt: number;
+  }): {
+    state: S;
+    effectiveAt: number;
+    audit: Record<string, unknown>;
+  };
+}
+declare class StateAuthority<S, C> {
+  #private;
+  private readonly store;
+  private readonly domain;
+  private readonly now;
+  readonly authorityId: string;
+  constructor(store: AuthorityStore<S>, domain: StateDomain<S, C>, now: () => number);
+  /** 当前权威快照;fresh 状态不落库、不推进 revision */
+  snapshot(maidId: string): StateSnapshot<S, C>;
+  submit(command: StateCommand): Promise<CommandReceipt<S, C>>;
+  private submitNow;
+  /** 拒绝回执:maidId 可用时持久化(幂等复述),不可用时(坏形状)仅返回 */
+  private reject;
+  /** 事务内快照(与公开 snapshot 同语义,读未提交的本事务写入) */
+  private snapshotInTx;
+}
+//#endregion
+//#region src/tls.d.ts
+/**
+ * TLS 材料装载与身份映射(maid-state 阶段规格 §10.3):
+ * - 证书/私钥/CA 从文件读入(server 与 client 各自持有);
+ * - fingerprint 归一化(去冒号、大写)后比对,client 身份只信证书,不信 body 自报;
+ * - allowMaids 是 host→maid 授权面(缺省 = 全部已注册 maid)。
+ */
+interface ClientIdentity {
+  hostId: string;
+  fingerprint256: string;
+  allowMaids?: readonly string[];
+}
+interface TlsServerConfig {
+  keyFile: string;
+  certFile: string;
+  caFile: string;
+  clients: readonly ClientIdentity[];
+}
+interface TlsClientConfig {
+  url: string;
+  hostId: string;
+  keyFile: string;
+  certFile: string;
+  caFile: string;
+  serverFingerprint256: string;
+  authorityId: string;
+  requestTimeoutMs?: number;
+}
+declare function normalizeFingerprint(fp: string): string;
+declare function loadKeyCertCa(input: {
+  keyFile: string;
+  certFile: string;
+  caFile: string;
+}): {
+  key: string;
+  cert: string;
+  ca: string;
+};
+/** 证书指纹 → host 身份映射(未登记指纹返回 undefined) */
+declare function identityOfPeer(clients: readonly ClientIdentity[], peerFingerprint256: string | undefined): ClientIdentity | undefined;
+declare function maidAllowed(identity: ClientIdentity, maidId: string): boolean;
+//#endregion
+//#region src/http-server.d.ts
+interface StateHttpServer {
+  url: string;
+  authorityId: string;
+  close(): Promise<void>;
+}
+declare function startStateHttpServer<S, C>(input: {
+  authority: StateAuthority<S, C>;
+  store: AuthorityStore<S>;
+  listen: {
+    host: string;
+    port: number;
+  };
+  tls: TlsServerConfig;
+}): Promise<StateHttpServer>;
+//#endregion
+//#region src/http-client.d.ts
+interface ServerStatusView {
+  authorityId: string;
+  protocolVersion: number;
+  maids: Array<{
+    maidId: string;
+    stateRevision: number;
+  }>;
+}
+declare class StateHttpClient<S, C> implements StateTransport<S, C> {
+  #private;
+  constructor(config: TlsClientConfig);
+  getSnapshot(maidId: string): Promise<StateSnapshot<S, C>>;
+  submit(command: StateCommand): Promise<CommandReceipt<S, C>>;
+  health(): Promise<{
+    authorityId: string;
+    protocolVersion: number;
+  }>;
+  status(): Promise<ServerStatusView>;
+  listEvents(filter: {
+    maidId?: string;
+    afterRevision?: number;
+    limit: number;
+  }): Promise<StoredReceipt[]>;
+  close(): void;
+}
+//#endregion
+//#region src/client-journal.d.ts
+/**
+ * client durable journal(maid-state 阶段规格 §6.5/§8.1/§10.4):
+ * - turn 在 LLM judge 前以 turnKey 预留(reserved),判分后 finalize 成 pending——崩溃重启
+ *   复用原 eventId/occurredAt,draft 原文仅保留到确认,acked 后清除 payload 只留去重元数据;
+ * - awaiting_config = 无配置快照时的本地保留,取得配置后 finalize(不得空判分冒充);
+ * - pending 上限只数 reserved/awaiting/pending,满员拒绝新写入,绝不静默丢最旧;
+ * - 快照缓存带 revision 守卫:旧 revision 不回退,同 revision 允许新 serverTime/config 更新。
+ */
+type JournalStatus = 'reserved' | 'awaiting_config' | 'pending' | 'acked' | 'failed';
+interface ReserveTurnInput<D> {
+  maidId: string;
+  sessionId: string;
+  turn: number;
+  occurredAt: number;
+  draft: D;
+}
+type ReserveTurnResult<D> = {
+  kind: 'new' | 'resume';
+  eventId: string;
+  draft: D;
+} | {
+  kind: 'duplicate';
+  eventId: string;
+} | {
+  kind: 'full';
+  eventId: null;
+};
+interface FailedJournalEntry {
+  maidId: string;
+  eventId: string;
+  command: StateCommand | undefined;
+  errorCode: string | null;
+}
+interface ClientJournalOptions {
+  file: string;
+  hostId: string;
+  maxPendingEvents?: number;
+}
+declare class ClientJournal<S = unknown, C = unknown> {
+  #private;
+  constructor(options: ClientJournalOptions);
+  /** turn 预留(判分前):turnKey 查重(hostId 用本 journal 构造身份,调用方无须知晓),新轮插入 reserved */
+  reserveTurn<D>(input: ReserveTurnInput<D>): ReserveTurnResult<D>;
+  /** 预留记录查询(reserved/awaiting/pending/acked/failed 任意状态;draft 仅预留态有语义) */
+  reservationOf(eventId: string): {
+    maidId: string;
+    status: JournalStatus;
+  } | undefined;
+  /** reserved/awaiting_config → pending(定稿):draft 从预留行内部取(builder 组装完整 payload) */
+  finalizeTurn(input: {
+    eventId: string;
+    sourceConfigRevision: string;
+    build(draft: unknown): unknown;
+  }): StateCommand | null;
+  /** gesture/reunion/manual:一次性持久化完整命令(幂等:重复 eventId 直接接受) */
+  enqueueCommand(command: StateCommand): boolean;
+  /** reserved → awaiting_config(无配置快照的本地保留);仅 reserved 可转 */
+  markAwaitingConfig(eventId: string): boolean;
+  listAwaitingConfig(maidId: string): Array<{
+    eventId: string;
+    kind: string;
+    occurredAt: number;
+    draft: unknown;
+  }>;
+  listPending(maidId: string): StateCommand[];
+  /** 确认:pending → acked,清 payload(原文清理),可选保存权威快照(revision 守卫) */
+  markAcked(eventId: string, ack: {
+    appliedRevision: number | null;
+    snapshot?: StateSnapshot<S, C>;
+  }): void;
+  /** 永久失败:pending → failed,payload 保留供显式导出(不自动删除) */
+  markFailed(eventId: string, errorCode: string | null): void;
+  exportFailed(): FailedJournalEntry[];
+  /** 快照缓存:旧 revision 不回退;同 revision 允许新 serverTime(不回退)/config 更新 */
+  saveSnapshot(snapshot: StateSnapshot<S, C>): void;
+  /** 已知 maid 全集(快照 ∪ 命令表;M3h 预备状态面用)。 */
+  listMaids(): string[];
+  readSnapshot(maidId: string): StateSnapshot<S, C> | undefined;
+  close(): void;
+}
+//#endregion
+//#region src/remote-client.d.ts
+/**
+ * remote client(maid-state 阶段规格 §7/§8):读 = 快照缓存 + pending 乐观投影(逐次重算,
+ * 绝不写回 base);写 = journal FIFO flush,applied/duplicate → acked(清原文),
+ * rejected → failed(保留原文供导出),网络/临时错误 → 保留 pending 指数退避重试。
+ * - per-maid Promise 链串行(refresh/flush 共用),同 maid 至多一个在途请求,不同 maid 并行;
+ * - 乐观投影永远可丢弃:refresh 拿到新 base 后由 read() 重算;
+ * - 自动重试 timer unref,不阻进程退出;close 停 timer 拒后续。
+ */
+interface ClientRead<S, C> {
+  state: S;
+  config: C;
+  stateRevision: number;
+  configRevision: string;
+  /** 缓存陈旧度代理:now - base snapshot.serverTime;无快照不可读 */
+  staleSince: number | null;
+  outboxDepth: number;
+}
+/** 运行时可观测状态(M3h 预备:设置页「状态服务」行数据源;§12.2 client 侧可查项)。 */
+interface ClientRuntimeStatus {
+  /** 最近一次与权威的成功往返(refresh/ack);null=从未成功 */
+  lastOkAt: number | null;
+  closed: boolean;
+  maids: Array<{
+    maidId: string;
+    hasSnapshot: boolean;
+    stateRevision: number;
+    staleSince: number | null;
+    outboxDepth: number;
+  }>;
+}
+interface RemoteStateClientOptions<S, C> {
+  journal: ClientJournal<S, C>;
+  transport: StateTransport<S, C>;
+  project(base: StateSnapshot<S, C>, pending: readonly StateCommand[], now: number): S;
+  now?: () => number;
+  random?: () => number;
+  retryInitialMs?: number;
+  retryMaxMs?: number;
+}
+declare class RemoteStateClient<S, C> {
+  #private;
+  readonly journal: ClientJournal<S, C>;
+  constructor(options: RemoteStateClientOptions<S, C>);
+  /** 同步读:base 快照 + pending 重算;无快照 → undefined(不注情绪、不发网络) */
+  read(maidId: string): ClientRead<S, C> | undefined;
+  /** 权威快照刷新:成功后 read() 以新 base 重算;失败沿用缓存(向调用方上抛由其决定) */
+  refresh(maidId: string): Promise<void>;
+  /** FIFO flush(显式调用):成功重置退避;网络/临时错误中断并上抛(已 ack 的不回退) */
+  flush(maidId: string): Promise<void>;
+  close(): void;
+  /** 可观测快照(M3h 预备):lastOkAt + 逐 maid 缓存陈旧度/outbox 深度;同步读不发网络。 */
+  status(): ClientRuntimeStatus;
+}
+//#endregion
+//#region src/embedded-transport.d.ts
+/**
+ * M3j 内嵌传输(规格 §9.2):直接调用同进程 StateAuthority——无网络监听、无 TLS、
+ * 无序列化边界。embedded 后端与 HTTP client 共用同一权威/命令/回执/revision 语义,
+ * 由结构保证「同一输入同一结果」;唯一权威仍是 authority.db,本 transport 不持状态。
+ */
+declare class EmbeddedStateTransport<S, C> implements StateTransport<S, C> {
+  private readonly authority;
+  constructor(authority: StateAuthority<S, C>);
+  getSnapshot(maidId: string): Promise<StateSnapshot<S, C>>;
+  submit(command: StateCommand): Promise<CommandReceipt<S, C>>;
+}
+//#endregion
+export { type AuthorityStore, type AuthorityTransaction, type ClientIdentity, ClientJournal, type ClientJournalOptions, type ClientRead, type ClientRuntimeStatus, type CommandReceipt, type DataDirLock, EmbeddedStateTransport, type EventKind, type FailedJournalEntry, type JournalStatus, type ListEventsFilter, type OpenAuthorityStoreOptions, PROTOCOL_VERSION, RemoteStateClient, type RemoteStateClientOptions, type ReserveTurnInput, type ReserveTurnResult, type ServerStatusView, StateAuthority, type StateCommand, StateCommandError, type StateDomain, StateHttpClient, type StateHttpServer, type StateSnapshot, type StateTransport, type StoredAuthorityState, type StoredReceipt, type TlsClientConfig, type TlsServerConfig, acquireDataDirLock, assertStateCommand, canonicalJson, commandHash, identityOfPeer, loadKeyCertCa, maidAllowed, newEventId, normalizeFingerprint, openAuthorityStore, revisionOf, startStateHttpServer, turnEventId };