@zhushanwen/pi-session-manager 0.4.0 → 0.6.0

package/src/__tests__/notify-ledger-discipline.test.ts

@@ -1,260 +0,0 @@
-// notify-ledger-discipline.test.ts — ledger 装配纪律（notify-once D3 ①-⑤ / U4）。
-// 包名 import @zhushanwen/subagent-core（D-10 领地补录后的 canonical 形态，相对路径 hack 已删）。
-// 覆盖：
-//   ① ensureLedgerBound 无条件重 bind（唯一装配方形态，与 subagent-workflow
-//      bindLedgerHostAndRecover 同款——槽上不残留捕获旧 ctx 的 host）；
-//   ② 槽空 → bind + recoverFromSession 成对（recover 吸收 session 文件既有条目——用未销账
-//      ledger entry 种子断言 pendingCount，证明 recover 真跑过）；
-//   ③ 双 bind 收敛——「先 bind 方在后 bind 之后 record 仍返回 true」（动态查槽恒取当前实例；
-//      缓存前实例引用则 record 恒 false 零日志——D3⑤ 事故形态反证）；
-//   ④ compactionCheck 直通当前实例、抛错不外抛（接入点降级，STANDARDS §11.1）；
-//   ⑤ 消费点 record 动态查槽 + deliveryCustomType = managed-session-notify；
-//      record 先 appendEntry 落盘后内存更新（时序钉：append 快照 = 该次 record 前计数）；
-//   sendDelivery stale ctx 守卫：stale 抛错静默降级 + warn 归因（条目标 sentAt 不挂回），
-//      非 stale 错误原样上抛走 settleRejected 留账重试；
-//   槽空降级（ensure 未跑/失败时 record → warn + false，用例登记）。
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-// logger mock helper 必须先于任何会加载 pi-extension-logger 的 import
-//（subagent-core barrel / ../notify-ledger.ts），见 logger-mock.ts 文件头
-import { createLoggerModuleMock, getLoggerMock } from "./helpers/logger-mock.ts";
-import {
-	bindNotifyLedgerHost,
-	getBoundNotifyLedger,
-	type NotifyLedgerHost,
-} from "@zhushanwen/subagent-core";
-import { STALE_CTX_MARKER } from "@zhushanwen/pi-ext-guards";
-
-vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
-
-const loggerMock = getLoggerMock();
-
-import {
-	ensureLedgerBound,
-	recordManagedNotify,
-	runLedgerCompactionCheck,
-} from "../notify-ledger.ts";
-import type { ManagedNotifyDetails } from "../notify-content.ts";
-
-/** recordManagedNotify 的最小合法 details（ManagedNotifyDetails 收紧后的测试桩形状） */
-function makeDetails(notifyId: string): ManagedNotifyDetails {
-	return { notifyId, sessionId: "s-test", reason: "completed", fulfills: 1, label: "test" };
-}
-
-interface HostProbe {
-	host: NotifyLedgerHost;
-	appendLedgerEntries: Array<{ customType: string; data: Record<string, unknown> }>;
-	/** 每次 append 发生时账本 pendingCount 快照——时序钉：恒等于该次 record 前的计数 */
-	pendingCountsAtAppend: number[];
-	attach(pendingCount: () => number): void;
-}
-
-function makeHost(): HostProbe {
-	const appendLedgerEntries: HostProbe["appendLedgerEntries"] = [];
-	const pendingCountsAtAppend: number[] = [];
-	let pendingCount: (() => number) | undefined;
-	const host: NotifyLedgerHost = {
-		appendLedgerEntry(customType, data) {
-			// 时序钉（D3 ③）：record 先 appendEntry 落盘、后内存更新——此刻本条尚未入账
-			if (pendingCount) pendingCountsAtAppend.push(pendingCount());
-			appendLedgerEntries.push({ customType, data: data as Record<string, unknown> });
-		},
-		readSessionEntries: () => [],
-		isIdle: () => false,
-		onAgentSettled: () => {},
-		sendDelivery: () => {},
-	};
-	return {
-		host,
-		appendLedgerEntries,
-		pendingCountsAtAppend,
-		attach: (fn) => {
-			pendingCount = fn;
-		},
-	};
-}
-
-/** ensureLedgerBound 的最小 pi/ctx 桩（appendEntry/on/sendMessage + getEntries/isIdle） */
-function makePiCtx(
-	entries: unknown[],
-	opts?: { isIdle?: boolean; sendMessage?: () => void },
-) {
-	const pi = {
-		appendEntry: vi.fn((customType: string, data: unknown) => {
-			entries.push({ type: "custom", customType, data });
-		}),
-		on: vi.fn(),
-		sendMessage: vi.fn(opts?.sendMessage ?? (() => {})),
-	};
-	const ctx = {
-		sessionManager: { getEntries: vi.fn(() => entries) },
-		isIdle: () => opts?.isIdle ?? false,
-	};
-	return { pi, ctx };
-}
-
-afterEach(() => {
-	// dispose 摘除模块级绑定（bind 路径实例 current===api → setBoundLedger(undefined)）
-	getBoundNotifyLedger()?.dispose();
-});
-
-describe("ledger 装配纪律（D3 ①-⑤，canonical import）", () => {
-	it("槽空 → recordManagedNotify 降级 false（ensure 未跑/失败时的登记降级，warn 留痕）", () => {
-		expect(getBoundNotifyLedger()).toBeUndefined();
-		expect(recordManagedNotify("sm-x", "content", makeDetails("sm-x"))).toBe(false);
-	});
-
-	it("⑤ bind 后 record 经动态查槽入账、deliveryCustomType = managed-session-notify；时序钉：append 先于内存更新", () => {
-		const probe = makeHost();
-		const ledger = bindNotifyLedgerHost(probe.host);
-		probe.attach(() => ledger.pendingCount());
-		expect(getBoundNotifyLedger()).toBe(ledger);
-		expect(recordManagedNotify("sm-a", "hello", makeDetails("sm-a"))).toBe(true);
-		expect(probe.appendLedgerEntries).toHaveLength(1);
-		expect(probe.appendLedgerEntries[0].customType).toBe("subagent-bg-notify-ledger");
-		expect(probe.appendLedgerEntries[0].data.deliveryCustomType).toBe("managed-session-notify");
-		expect(probe.appendLedgerEntries[0].data.content).toBe("hello");
-		expect(probe.pendingCountsAtAppend).toEqual([0]);
-		expect(ledger.pendingCount()).toBe(1);
-	});
-
-	it("③ 先 bind 方在后 bind 之后 record 仍返回 true（后 bind 者收敛单实例；缓存前实例引用则恒 false——D3⑤ 反证）", () => {
-		const probeA = makeHost();
-		const ledgerA = bindNotifyLedgerHost(probeA.host);
-		probeA.attach(() => ledgerA.pendingCount());
-		expect(recordManagedNotify("sm-1", "n1", makeDetails("sm-1"))).toBe(true);
-		expect(probeA.appendLedgerEntries).toHaveLength(1);
-
-		// 后 bind 方（模拟 subagent-workflow session_start 的 re-bind + recover 成对——
-		// bindNotifyLedgerHost 内部先 dispose 旧实例再 set，收敛为单实例全量态）
-		const probeB = makeHost();
-		const ledgerB = bindNotifyLedgerHost(probeB.host);
-		probeB.attach(() => ledgerB.pendingCount());
-
-		// 消费点动态查槽恒取当前实例：先 bind 方的后续 record 落后 bind 实例且返回 true
-		expect(getBoundNotifyLedger()).toBe(ledgerB);
-		expect(recordManagedNotify("sm-2", "n2", makeDetails("sm-2"))).toBe(true);
-		expect(probeB.appendLedgerEntries.map((e) => e.data.notifyId)).toEqual(["sm-2"]);
-		expect(probeA.appendLedgerEntries).toHaveLength(1); // 前实例不再收账
-		// 时序钉跨 bind 仍成立：sm-2 时 B 账面 0（append 快照 = 该次 record 前计数）
-		expect(probeB.pendingCountsAtAppend).toEqual([0]);
-
-		// 反证：若消费点缓存了前实例引用，record 恒 false 且零日志（对半概率丢全部通知的事故形态）
-		expect(ledgerA.record("sm-3", "n3", {})).toBe(false);
-		// 而动态查槽（本包消费面）依旧 true
-		expect(recordManagedNotify("sm-4", "n4", makeDetails("sm-4"))).toBe(true);
-		expect(probeB.appendLedgerEntries).toHaveLength(2);
-		expect(probeB.pendingCountsAtAppend).toEqual([0, 1]);
-	});
-
-	it("② 槽空 + ensureLedgerBound → bind + recoverFromSession 成对（既有未销账 ledger entry 被 recover 吸收）", () => {
-		const entries: unknown[] = [
-			{
-				type: "custom",
-				customType: "subagent-bg-notify-ledger",
-				data: {
-					v: 1,
-					notifyId: "sm-recovered",
-					content: "prior notification",
-					record: { notifyId: "sm-recovered" },
-				},
-			},
-		];
-		const { pi, ctx } = makePiCtx(entries);
-		expect(getBoundNotifyLedger()).toBeUndefined();
-
-		ensureLedgerBound(pi as never, ctx as never);
-		const ledger = getBoundNotifyLedger();
-		expect(ledger).toBeDefined();
-		// recover 真跑过：session 文件的未销账条目被吸收进内存态
-		expect(ctx.sessionManager.getEntries).toHaveBeenCalled();
-		expect(ledger!.pendingCount()).toBe(1);
-		// 装配后消费面就绪
-		expect(recordManagedNotify("sm-new", "n", makeDetails("sm-new"))).toBe(true);
-		expect(pi.appendEntry).toHaveBeenCalledWith(
-			"subagent-bg-notify-ledger",
-			expect.objectContaining({ notifyId: "sm-new", deliveryCustomType: "managed-session-notify" }),
-		);
-	});
-
-	it("① 槽已有实例 + ensureLedgerBound → 无条件重 bind（后 bind 收敛接管 + recover 重跑）", () => {
-		const probe = makeHost();
-		const ledger = bindNotifyLedgerHost(probe.host);
-		probe.attach(() => ledger.pendingCount());
-
-		const { pi, ctx } = makePiCtx([]);
-		ensureLedgerBound(pi as never, ctx as never);
-		// 后 bind 收敛：旧实例被 dispose，槽切到新实例（槽上不残留捕获旧 ctx 的 host）
-		const rebound = getBoundNotifyLedger();
-		expect(rebound).toBeDefined();
-		expect(rebound).not.toBe(ledger);
-		// recover 重跑：新 host 的 readSessionEntries 被消费
-		expect(ctx.sessionManager.getEntries).toHaveBeenCalled();
-		// 消费面动态查槽：record 落新实例（经新 host 的 appendLedgerEntry = pi.appendEntry）
-		expect(recordManagedNotify("sm-1", "n", makeDetails("sm-1"))).toBe(true);
-		expect(pi.appendEntry).toHaveBeenCalled();
-
-		// 重复调用同款：每次 session_start 都重装配（不查槽短路）
-		ensureLedgerBound(pi as never, ctx as never);
-		expect(getBoundNotifyLedger()).not.toBe(rebound);
-	});
-
-	it("sendDelivery stale ctx 守卫：stale 抛错静默降级 + warn 归因（条目标 sentAt，不外抛不挂回）", () => {
-		const { pi, ctx } = makePiCtx([], {
-			isIdle: true,
-			sendMessage: () => {
-				throw new Error(`ctx ${STALE_CTX_MARKER}`);
-			},
-		});
-		ensureLedgerBound(pi as never, ctx as never);
-		const ledger = getBoundNotifyLedger();
-		expect(ledger).toBeDefined();
-		expect(recordManagedNotify("sm-stale", "n", makeDetails("sm-stale"))).toBe(true);
-		expect(() => ledger!.attemptDeliver()).not.toThrow();
-		// stale 降级语义：本条不投递且按已受理标 sentAt（attemptDeliver 摘除，不挂回反复撞）
-		expect(ledger!.pendingCount()).toBe(0);
-		expect(loggerMock.warn).toHaveBeenCalledWith(
-			"[session-manager] notify delivery skipped (stale ctx)",
-			expect.objectContaining({ error: expect.stringContaining("stale") }),
-		);
-	});
-
-	it("sendDelivery 非 stale 错误原样上抛 → settleRejected 留账重试（pending 不摘、无 stale 归因）", () => {
-		// 清上一用例的 warn 记录——断言只认本用例内的调用
-		loggerMock.warn.mockClear();
-		const { pi, ctx } = makePiCtx([], {
-			isIdle: true,
-			sendMessage: () => {
-				throw new Error("boom");
-			},
-		});
-		ensureLedgerBound(pi as never, ctx as never);
-		const ledger = getBoundNotifyLedger();
-		expect(ledger).toBeDefined();
-		expect(recordManagedNotify("sm-err", "n", makeDetails("sm-err"))).toBe(true);
-		expect(() => ledger!.attemptDeliver()).not.toThrow();
-		// 非 stale 走 attemptDeliver 既有 catch：settleRejected 留账等下一边沿重试
-		expect(ledger!.pendingCount()).toBe(1);
-		expect(loggerMock.warn).not.toHaveBeenCalledWith(
-			"[session-manager] notify delivery skipped (stale ctx)",
-			expect.anything(),
-		);
-	});
-
-	it("④ compactionCheck 经动态查槽直通当前实例", () => {
-		const probe = makeHost();
-		const ledger = bindNotifyLedgerHost(probe.host);
-		probe.attach(() => ledger.pendingCount());
-		const spy = vi.spyOn(getBoundNotifyLedger()!, "compactionCheck").mockReturnValue(0);
-		runLedgerCompactionCheck();
-		expect(spy).toHaveBeenCalledTimes(1);
-	});
-
-	it("④ compactionCheck 抛错 → warn 吞掉不外抛（辅助面接入点降级，STANDARDS §11.1）", () => {
-		bindNotifyLedgerHost(makeHost().host);
-		vi.spyOn(getBoundNotifyLedger()!, "compactionCheck").mockImplementation(() => {
-			throw new Error("boom");
-		});
-		expect(() => runLedgerCompactionCheck()).not.toThrow();
-	});
-});

package/src/notify-ledger.ts

@@ -1,121 +0,0 @@
-// src/notify-ledger.ts — notify-ledger（B-ledger）装配与 record 消费（notify-once D3 装配纪律）。
-//
-// canonical 消费面（D-10 领地补录后落地）：@zhushanwen/subagent-core 的
-// getBoundNotifyLedger / bindNotifyLedgerHost——Symbol.for 进程级单例槽跨扩展 bundle
-// 共享同一 ledger 实体（C-ext-06），本包不再持有任何槽镜像。
-//
-// 装配纪律（D3）对照（session_start 无条件重装配方，与 subagent-workflow
-// bindLedgerHostAndRecover 同款；旧「查槽短路」形态已废）：
-//   ① session_start 无条件 bindNotifyLedgerHost(host).recoverFromSession() 成对——host
-//      捕获当次 session 的 pi/ctx，不查槽短路（与 subagent-core 每次 session_start 重
-//      bind 的设计假设对齐：槽上永不残留捕获旧 ctx 的 host）；
-//   ② recover 吸收 session 文件全部既有条目（G3 重启重放即 recoverFromSession 语义）；
-//   ③ 双 bind 收敛：后 bind 者 dispose 前实例 + recover → 单实例全量态，前者的已落盘
-//      条目无损（record 先 appendEntry 落盘后内存更新——notify-ledger-discipline 用例钉住）。
-//      收敛由 subagent-core bindNotifyLedgerHost 的 dispose 旧实例语义保证，装配方无需
-//      自查槽（subagent-core 侧 bind 用模块级单例 handler + boundLedger 引用切换，
-//      重 bind 不累积物理监听）；
-//   ④ compactionCheck 同批接线（session_compact handler，P-B4 降级——
-//      subagent-workflow 同款先例；两侧对同一槽实例重复调用为幂等 no-op）；
-//   ⑤ 消费点恒经 getBoundNotifyLedger() 动态查槽，禁缓存实例引用——后 bind 方 dispose
-//      旧实例后缓存引用的 record() 静默 return false 零日志，对半概率丢全部通知。
-//
-// 唯一装配方形态（拓扑假设）：taiji runtime 每 session 重 spawn pi 进程，进程内无
-// session 替换——session_start 触发时本包是该 session ledger 的唯一装配方（与
-// subagent-workflow 共存时按 ③ 收敛）。stale ctx 面因此收窄，sendDelivery 的
-// guardStaleCtx 为防御性兜底（异常形态留痕归因，非正常路径承重）。
-//
-// 槽空降级（record 时点仍无实例：session_start 未跑 / bind 失败）：warn 留痕 + false
-//（STANDARDS §11.1 通知类接入点降级，非静默吞）。
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindNotifyLedgerHost, getBoundNotifyLedger } from "@zhushanwen/subagent-core";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-import { createPiNotifyLedgerHost } from "@zhushanwen/pi-notify-ledger-host";
-import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
-
-import {
-	MANAGED_SESSION_NOTIFY_CUSTOM_TYPE,
-	type ManagedNotifyDetails,
-} from "./notify-content.ts";
-
-const logger = getLogger("session-manager");
-
-/**
- * 装配纪律 ①②（session_start 调用）：无条件 bind + recover 成对。
- * host 五端口的 pi 接线（appendEntry / getEntries / isIdle / agent_settled /
- * sendMessage + 送达 stale 防御）收敛在共享工厂 @zhushanwen/pi-notify-ledger-host
- * ——与 subagent-workflow 同一工厂（同一槽的两处装配方，host 接口一致才能互换
- * 消费），本包以 component/logger/warn 前缀参数化（label = session-manager:*、
- * stale warn 文案带 "[session-manager] " 前缀，归因不串包）。
- * 装配失败不阻断 session_start（record 侧走槽空降级）。
- */
-export function ensureLedgerBound(pi: ExtensionAPI, ctx: ExtensionContext): void {
-	try {
-		// ①② bind + recover 成对（G3 重启重放 = recoverFromSession 既有语义；
-		// 双 bind 收敛 = subagent-core dispose 旧实例语义，见文件头 ③）
-		bindNotifyLedgerHost(
-			createPiNotifyLedgerHost(pi, ctx, {
-				component: "session-manager",
-				logger,
-				staleWarnPrefix: "[session-manager] ",
-			}),
-		).recoverFromSession();
-	} catch (err) {
-		logger.warn("[session-manager] notify ledger bind failed (record degrades until next session_start)", {
-			error: toErrorMessage(err),
-		});
-	}
-}
-
-/**
- * 记账一条通知（B-ledger ① record，deliveryCustomType 走 managed-session-notify 外部通道，
- * 逐条投递不合批——合批已在 watch-coordinator 微窗内重建批身份，D3 裁决4）。
- * 装配纪律⑤：每次调用即到即读查槽，禁存实例引用；槽空 → warn 降级 + false。
- */
-export function recordManagedNotify(
-	notifyId: string,
-	content: string,
-	details: ManagedNotifyDetails,
-): boolean {
-	const ledger = getBoundNotifyLedger();
-	if (!ledger) {
-		logger.warn(
-			"[session-manager] notify ledger not bound — notification dropped (ensureLedgerBound 未跑或 bind 失败；下次 session_start 重试装配)",
-			{ notifyId },
-		);
-		return false;
-	}
-	try {
-		return ledger.record(notifyId, content, details, {
-			deliveryCustomType: MANAGED_SESSION_NOTIFY_CUSTOM_TYPE,
-		});
-	} catch (err) {
-		// 写入异常（stale ctx / appendEntry 失败）按接入点降级：不拖垮 watch 应答编排
-		//（unregister 照常），warn 留痕可归因
-		logger.warn("[session-manager] notify ledger record failed", {
-			notifyId,
-			error: toErrorMessage(err),
-		});
-		return false;
-	}
-}
-
-/**
- * compactionCheck 接线（装配纪律④，P-B4 降级——subagent-workflow session_compact 同款）：
- * 检测 ledger/ack entry 被 compaction 清除时按内存态补写（未清除即 0，幂等 no-op）。
- */
-export function runLedgerCompactionCheck(): void {
-	try {
-		const rewritten = getBoundNotifyLedger()?.compactionCheck() ?? 0;
-		if (rewritten > 0) {
-			logger.warn(
-				`[session-manager] notify ledger entries lost to compaction; rewrote ${rewritten} from memory`,
-			);
-		}
-	} catch (err) {
-		logger.warn("[session-manager] notify ledger compactionCheck failed", {
-			error: toErrorMessage(err),
-		});
-	}
-}