@zhushanwen/pi-session-path 0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zhushanwen/pi-session-path",
+  "version": "0.1.0",
+  "description": "Active-path clipping for pi session entries — single shared implementation for state-rebuilding extensions (todo/plan/goal/scheduler), so revoked subtrees stay out of rebuild inputs (shared library, not a Pi extension, zero dependencies).",
+  "type": "module",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "session",
+    "active-path",
+    "shared"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/active-path.test.ts

@@ -0,0 +1,100 @@
+/**
+ * filterActivePath 单测——四包（todo/plan/goal/scheduler）收编后的单一实现。
+ * 覆盖：分支裁剪 / 无分支回归 / leafId 防御回退 / 统一后的回退取值口径（无 id
+ * 尾条目）/ legacy 线性 fixture / 环状 parentId 防挂死。
+ */
+import { describe, expect, it } from "vitest";
+
+import { filterActivePath, type ActivePathSessionView } from "../index";
+
+interface BranchEntry { // oe-exempt:20261001:test:测试 fixture 形状契约（分支树 entry 最小形状，断言面消费）
+	type: string;
+	id: string;
+	parentId: string | null;
+	customType?: string;
+	data?: unknown;
+}
+
+function entry(id: string, parentId: string | null, customType = "x"): BranchEntry {
+	return { type: "custom", id, parentId, customType, data: {} };
+}
+
+/** 撤回后真实形态：label entry 落文件尾（parentId = 回退后叶子） */
+function labelEntry(id: string, parentId: string | null): BranchEntry {
+	return { type: "label", id, parentId, targetId: "u-x", label: "taiji:revoked" };
+}
+
+function makeView(
+	entries: Array<Record<string, unknown>>,
+	leafId?: string | null,
+): ActivePathSessionView<Record<string, unknown>> {
+	return {
+		getEntries: () => entries.slice(),
+		getLeafId: leafId === undefined ? undefined : () => leafId,
+	};
+}
+
+const idsOf = (entries: Array<Record<string, unknown>>): unknown[] =>
+	entries.map((e) => e["id"]);
+
+describe("filterActivePath（活跃路径裁剪单一实现）", () => {
+	it("有分支 fixture：被撤子树不进输出——活跃路径 = leafId 沿 parentId 回溯", () => {
+		// 树：e1 → e2(active)；e1 → e3(revoked，物理后写)；撤回落 label 锚 L（parentId=e2）
+		const view = makeView([
+			entry("e1", null),
+			entry("e2", "e1", "active"),
+			entry("e3", "e1", "revoked"),
+			labelEntry("L", "e2"),
+		], "L");
+
+		expect(idsOf(filterActivePath(view))).toEqual(["e1", "e2", "L"]);
+	});
+
+	it("无分支回归：leafId = 文件尾 → 全量保留（现行为不变）", () => {
+		const view = makeView([entry("e1", null), entry("e2", "e1")], "e2");
+
+		expect(idsOf(filterActivePath(view))).toEqual(["e1", "e2"]);
+	});
+
+	it("leafId 防御：null / 指向不存在 entry / 视图不携带 getLeafId → 回退文件尾", () => {
+		const entries = [entry("e1", null), entry("e2", "e1")];
+		for (const leafId of [null, "missing-id", undefined]) {
+			const clipped = filterActivePath(makeView(entries, leafId));
+			expect(idsOf(clipped)).toEqual(["e1", "e2"]);
+		}
+	});
+
+	it("统一回退取值口径：尾条目无 string id → 回退叶子 = 最后一条带 id 的条目，无 id 尾条目保留在输出", () => {
+		// 收编前分叉点：plan/todo 取数组尾（无 id 条目）、goal/scheduler 取最后一条
+		// 带 id 条目。统一为后者——回溯需要 id 锚点；无 id 条目按线性文件语义保留。
+		const view = makeView([
+			entry("e1", null, "id-having"),
+			{ type: "custom", customType: "id-less-tail", data: {} },
+		], null);
+
+		const clipped = filterActivePath(view);
+		expect(clipped).toHaveLength(2);
+		expect(clipped[1]).toMatchObject({ customType: "id-less-tail" });
+	});
+
+	it("legacy fixture：全文件无 string id（线性最小形状）→ 不过滤，保持裁剪前行为", () => {
+		const view: ActivePathSessionView<Record<string, unknown>> = {
+			getEntries: () => [
+				{ type: "custom", customType: "a", data: {} },
+				{ type: "custom", customType: "b", data: {} },
+			],
+		};
+
+		expect(filterActivePath(view)).toHaveLength(2);
+	});
+
+	it("环状 parentId（a↔b，leafId 指向环内）→ 回溯终止不挂死", () => {
+		const view = makeView([entry("a", "b"), entry("b", "a")], "a");
+
+		expect(new Set(idsOf(filterActivePath(view))).size).toBeGreaterThan(0);
+	});
+
+	it("空 entries → 原样返回空数组", () => {
+		expect(filterActivePath(makeView([], "x"))).toEqual([]);
+	});
+});

package/src/index.ts

@@ -0,0 +1,91 @@
+// src/index.ts
+//
+// @zhushanwen/pi-session-path —— pi session 活跃路径裁剪共享库（不是 Pi extension，
+// 零依赖纯函数，无 pi SDK peerDep——供任意 @zhushanwen/pi-* 包消费）。
+//
+// 收敛背景：todo/plan/goal/scheduler 四包曾各持一份同构 filterActivePath（extension
+// 不能 import runtime 包，四包间却可互享），靠注释纪律保持同步——回退取值口径已实际
+// 分叉（plan/todo 取数组尾条目 vs goal/scheduler 取最后一条带 string id 的条目，无
+// id 尾条目上行为可分叉）。语义同构 = 假差异，收敛为单一实现；读者普查登记见
+// docs/architecture/session-readers-census.md（§3 各包行 + §4.1 防御语义异源登记）。
+// runtime 侧（entry-tree-builder 重建链 / readEntries 投影的 filterEntriesToActivePath）
+// 与 plugin 侧不经本包、保持独立——跨面异源是有意设计，非漏接。
+
+/**
+ * entry 的树结构字段视图（duck-typed 收窄，无断言）。含 type?: unknown 只为通过
+ * weak-type 检查（全 optional 目标须与源共享属性名——各消费包的最小 entry 形状
+ * SessionEntryLike/SchedulerEntryLike 只声明 type）；真实 pi SessionEntry 恒有
+ * id/parentId（SessionEntryBase），缺失时按线性文件语义处理（见 filterActivePath）。
+ */
+interface TreeEntryFields { // oe-exempt:20261001:framework:duck-typed 树字段收窄视图（weak-type 检查要求的独立 interface 形态）——共享实现内部结构，非待变体抽象
+	type?: unknown;
+	id?: unknown;
+	parentId?: unknown;
+}
+
+/**
+ * 活跃路径回溯所需的最小 session 视图。getLeafId 可选：消费包的最小视图（单测
+ * fixture / SessionPort 委托）不携带时按文件尾回退；pi ReadonlySessionManager 恒
+ * 携带（结构兼容，多余成员不受限）。
+ */
+export interface ActivePathSessionView<TEntry extends TreeEntryFields> { // oe-exempt:20261001:framework:消费包 session 视图的 ports 契约——goal ActivePathSessionView / pi ReadonlySessionManager / SchedulerBackendCtx.sessionManager 以结构兼容形状传入，类型契约先行、单实现常态
+	getEntries(): TEntry[];
+	getLeafId?(): string | null;
+}
+
+/**
+ * 活跃路径裁剪：从 leafId 沿 parentId 回溯得活跃路径 id 集合，按文件序过滤 entries。
+ * 撤回（navigateTree 树回退）后被撤子树的 entry 不再进入状态重建输入——被撤内容
+ * 不得经压缩摘要 / 面板 / 逐轮注入回到模型上下文。
+ *
+ * 防御语义（pi buildSessionPath 同构）：leafId 缺失/失效时回退文件尾——取**最后一条
+ * 带 string id 的 entry**（正常文件尾即它；回溯需要 id 锚点，无 id 的尾条目当不了
+ * 叶子，按线性文件语义保留在输出中）。此为四包收编时统一的回退取值口径：真实 pi
+ * SessionEntry 恒有 id，两口径仅在无 id 的 duck-typed fixture 上可分叉，生产行为
+ * 逐字节不变。
+ *
+ * 边界形态：
+ * - 无任何树信息（legacy 线性 fixture，全文件无 string id）→ 不过滤，保持裁剪前行为；
+ * - 无 id 的 entry → 保留（线性文件语义，不因缺字段丢行）；
+ * - 环状 parentId → activeIds 已含即终止，不挂死。
+ */
+export function filterActivePath<TEntry extends TreeEntryFields>(
+	view: ActivePathSessionView<TEntry>,
+): TEntry[] {
+	const entries = view.getEntries();
+	if (entries.length === 0) return entries;
+
+	const byId = new Map<string, { id: string; parentId: string | null }>();
+	for (const entry of entries) {
+		const tree: TreeEntryFields = entry;
+		if (typeof tree.id === "string") {
+			byId.set(tree.id, {
+				id: tree.id,
+				parentId: typeof tree.parentId === "string" ? tree.parentId : null,
+			});
+		}
+	}
+	// 无任何树信息（legacy 线性 fixture）→ 不过滤，保持裁剪前行为
+	if (byId.size === 0) return entries;
+
+	const leafId = view.getLeafId?.();
+	let current =
+		(leafId ? byId.get(leafId) : undefined) ?? lastOfMapValues(byId);
+	const activeIds = new Set<string>();
+	while (current && !activeIds.has(current.id)) {
+		activeIds.add(current.id);
+		current = current.parentId ? byId.get(current.parentId) : undefined;
+	}
+	return entries.filter((entry) => {
+		const tree: TreeEntryFields = entry;
+		return typeof tree.id !== "string" || activeIds.has(tree.id);
+	});
+}
+
+function lastOfMapValues(
+	map: Map<string, { id: string; parentId: string | null }>,
+): { id: string; parentId: string | null } | undefined {
+	let last: { id: string; parentId: string | null } | undefined;
+	for (const value of map.values()) last = value;
+	return last;
+}