openfeel 1.1.7 → 1.2.0

package/dist/core/flow-archive/archive-health.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 归档一致性健康检查项构造 — 纯函数
+ * 职责：构造 `flow health` 的「归档一致性」检查项——
+ *       a. 归档索引（`meta.archived_versions`）↔ 归档目录清单**双向对账**（恒产生 1 条 pass/warn）；
+ *       b. 活跃集残留（flow.json `stages` 仍含已归档版本阶段；仅非空时产生一条 warn）。
+ * 边界：**只读**——读取轻量索引（`getArchivedVersions`）+ 归档目录清单级（`listArchiveVersions`，目录级）；
+ *       **b 项候选分支**（活跃键版本前缀 ∈ 索引）按版本**惰性读一次**匹配快照（`readArchiveFile`，
+ *       仅取 `stages` 键集，不读 reviews/log）；常规（无候选）零读归档文件；不写盘、不加锁。
+ * 契约修订（REV-80-019；落点更正 REV-80-024）：原「不读归档文件内容」契约实际落点 =
+ *       `stage-80/plan.md §二 不变量 4`（:61）+ 大计划 `v1.2.0/plan.md §八 item 4`（:266）/ 裁定 Q（:118），
+ *       **不在 `§四.4`**（plan.md 措辞按 REV-80-020 移交 planner 修订）。
+ * 依赖方向（REV-80-005）：对 flow-manager 仅 `import type`（编译期擦除，零运行时依赖边）；
+ *       本文件仅被 `src/commands/flow.ts` 消费，禁 `flow-manager → flow-archive` 运行时依赖。
+ */
+import type { FlowData, HealthCheckItem } from '../flow-manager.js';
+/**
+ * 构造归档一致性检查项（a 双向对账 + b 活跃集残留）。
+ *
+ * - a 项（恒产生 1 条 pass/warn）：`archived_versions` ↔ `.openfeel/flow-archive/*.json` 目录清单双向对账；
+ *   两侧差集均空 → pass；否则 warn（索引有文件缺 / 文件有索引缺）。
+ * - b 项（仅非空时产生 warn，**两段式判据**——REV-80-019）：候选 = ① 版本前缀 ∈ `archived_versions`
+ *   （索引级廉价预筛）**∧** ② 键 ∈ 对应归档快照 `stages` 键集（`readArchiveFile`，键级精确证据）——
+ *   「默认版本新建阶段」（键 ∉ 快照）不误报；快照不可读（缺失/损坏 → 读侧宽容 null）→ 不可证实 → 不报
+ *   （索引/文件不一致由 a 项承担）。
+ *
+ * @param input.projectPath 项目根路径（扫描目录清单；b 项候选分支读匹配版本快照以取 `stages` 键集）
+ * @param input.data 当前 flow.json 数据（只读）
+ * @returns HealthCheckItem[]；全部项 `status ∈ {'pass','warn'}`（**恒无 fail**）
+ */
+export declare function archiveHealthItems(input: {
+    projectPath: string;
+    data: FlowData;
+}): HealthCheckItem[];
+//# sourceMappingURL=archive-health.d.ts.map

package/dist/core/flow-archive/archive-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-health.d.ts","sourceRoot":"","sources":["../../../src/core/flow-archive/archive-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AASpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,eAAe,EAAE,CAwDpG"}

package/dist/core/flow-archive/archive-health.js

@@ -0,0 +1,76 @@
+import { getArchivedVersions, listArchiveVersions, readArchiveFile } from './archive-ops.js';
+import { versionOfStageId } from './grouping.js';
+/** a 项 section 常量（双向对账；与测试断言一致，REV-80-012） */
+const SECTION_INDEX = '归档一致性';
+/** b 项 section 常量（活跃集残留；与测试断言一致，REV-80-012） */
+const SECTION_RESIDUAL = '归档残留';
+/**
+ * 构造归档一致性检查项（a 双向对账 + b 活跃集残留）。
+ *
+ * - a 项（恒产生 1 条 pass/warn）：`archived_versions` ↔ `.openfeel/flow-archive/*.json` 目录清单双向对账；
+ *   两侧差集均空 → pass；否则 warn（索引有文件缺 / 文件有索引缺）。
+ * - b 项（仅非空时产生 warn，**两段式判据**——REV-80-019）：候选 = ① 版本前缀 ∈ `archived_versions`
+ *   （索引级廉价预筛）**∧** ② 键 ∈ 对应归档快照 `stages` 键集（`readArchiveFile`，键级精确证据）——
+ *   「默认版本新建阶段」（键 ∉ 快照）不误报；快照不可读（缺失/损坏 → 读侧宽容 null）→ 不可证实 → 不报
+ *   （索引/文件不一致由 a 项承担）。
+ *
+ * @param input.projectPath 项目根路径（扫描目录清单；b 项候选分支读匹配版本快照以取 `stages` 键集）
+ * @param input.data 当前 flow.json 数据（只读）
+ * @returns HealthCheckItem[]；全部项 `status ∈ {'pass','warn'}`（**恒无 fail**）
+ */
+export function archiveHealthItems(input) {
+    const items = [];
+    const { projectPath, data } = input;
+    // a. 双向对账（索引 ↔ 文件目录清单）
+    const indexed = getArchivedVersions(data); // 快照副本
+    const files = listArchiveVersions(projectPath); // 目录清单级、字典序
+    const indexedSet = new Set(indexed);
+    const filesSet = new Set(files);
+    const missingFiles = indexed.filter((v) => !filesSet.has(v)); // 索引有、文件缺
+    const missingIndex = files.filter((v) => !indexedSet.has(v)); // 文件有、索引缺
+    if (missingFiles.length === 0 && missingIndex.length === 0) {
+        items.push({
+            section: SECTION_INDEX,
+            status: 'pass',
+            message: `归档索引与归档文件一致（${indexed.length} 个版本）`,
+        });
+    }
+    else {
+        // 两侧差集任一非空 → warn（展示各≤5 条）
+        items.push({
+            section: SECTION_INDEX,
+            status: 'warn',
+            message: `归档索引与文件不一致：索引有文件缺 [${missingFiles.slice(0, 5).join(', ')}]；文件有索引缺 [${missingIndex.slice(0, 5).join(', ')}]（可经 flow archive list / flow archive show 复核）`,
+        });
+    }
+    // b. 活跃集残留（仅非空时产生 warn；判据两段式——REV-80-019）：
+    //    ① 版本前缀 ∈ archived_versions（索引级廉价预筛；归一化派生不单独构成判据——REV-80-001）；
+    //    ② 键 ∈ 对应归档快照的 stages 键集（键级精确证据——「默认版本新建阶段」不误报）。
+    //    快照不可读（缺失/损坏，readArchiveFile 读侧宽容 → null）→ 不可证实 → 不报（索引/文件不一致由 a 项承担）。
+    const residual = [];
+    const snapshotStageKeys = new Map(); // version → 快照 stages 键集（每版本至多读一次）
+    for (const stageId of Object.keys(data.stages)) {
+        const version = versionOfStageId(stageId);
+        if (!version || !indexedSet.has(version)) {
+            continue; // 不可解析 或 版本未归档 → 非候选（不读归档文件）
+        }
+        let keys = snapshotStageKeys.get(version);
+        if (keys === undefined) {
+            const snapshot = readArchiveFile(projectPath, version);
+            keys = new Set(Object.keys(snapshot?.stages ?? {}));
+            snapshotStageKeys.set(version, keys);
+        }
+        if (keys.has(stageId)) {
+            residual.push(stageId);
+        }
+    }
+    if (residual.length > 0) {
+        items.push({
+            section: SECTION_RESIDUAL,
+            status: 'warn',
+            message: `flow.json 仍含已归档版本阶段：${residual.slice(0, 5).join(', ')}（可能由 checkpoint restore 带回或重复归档残留；须重新执行 flow archive <version> 收敛）`,
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=archive-health.js.map

package/dist/core/flow-archive/archive-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-health.js","sourceRoot":"","sources":["../../../src/core/flow-archive/archive-health.ts"],"names":[],"mappings":"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"}

package/dist/core/flow-archive/archive-ops.d.ts

@@ -0,0 +1,68 @@
+import type { FlowData, MetaPhase } from '../flow-manager.js';
+import type { ArchiveFile } from './archive-file.js';
+/** 归档目录：{projectPath}/.openfeel/flow-archive（Q2 定稿：不纳入 WORKSPACE_DIRS，按需 mkdir 幂等创建） */
+export declare function getArchiveDir(projectPath: string): string;
+/**
+ * 归档文件路径：{archiveDir}/{version}.json（路径单点）。
+ *
+ * ⚠️ 仅接受**已校验**的版本字符串（经 `isValidArchiveVersion`，REV-78-011）：
+ * 本函数只做拼接、不做合法性/路径穿越校验；调用方须先走 `isValidArchiveVersion`
+ * 或使用上游已校验入口（`writeArchiveFile` / `readArchiveFile` / `listArchiveVersions`）。
+ */
+export declare function getArchiveFilePath(projectPath: string, version: string): string;
+/**
+ * 版本字符串合法性（探针法复用 parseStageId，禁自写正则）：
+ * `${s}-stage-00` 可被 parseStageId 解析且版本段恒等 → 合法；空串/含路径分隔符/非版本形态 → 非法。
+ *
+ * 导出版（原私有版本校验函数重命名并导出），供命令层复用——REV-79-004。
+ */
+export declare function isValidArchiveVersion(s: string): boolean;
+/**
+ * 版本号归一（输入前缀兼容）：trim → 去单个前导 `v`（如有）→ 补 `v` → 经 `isValidArchiveVersion` 校验。
+ * 归一方向恒为「去 v 再加 v」：引擎键恒带 `v`（与 `versionOfStageId` 输出同形态；REV-79-004）。
+ * **禁**复用 `normalizeVersion`（`src/core/plan/roadmap.ts:17`，方向相反：去 `v`）。
+ *
+ * 错误路径返回 null 的触发条件：空串 / 探针校验失败（非 vX.Y[.Z] 形态、含路径分隔符等）。
+ */
+export declare function normalizeArchiveVersion(input: string): string | null;
+/**
+ * 写归档文件（覆盖写 = 同版本幂等；backup:false，D8 定稿）。
+ * 独立锁 `flow-archive` 内原子写（同目录 temp + fsync + rename）；目录按需 mkdir（幂等）。
+ * @throws 版本字符串非法（路径穿越防御，D9）或写盘失败
+ */
+export declare function writeArchiveFile(projectPath: string, file: ArchiveFile): void;
+/**
+ * 列举已归档版本（目录扫描 + 文件名合法校验）。
+ * 目录不存在 → []；仅收 `{version}.json` 且 version 通过 isValidArchiveVersion 者；返回字典序排序（非语义版本序）。
+ */
+export declare function listArchiveVersions(projectPath: string): string[];
+/**
+ * 读取归档文件。
+ * 缺失 / 损坏（JSON 解析失败）/ 非法版本（路径穿越防御）/ 内容非对象 → null（不抛）；
+ * 未知键保留（不重建对象）；缺 counts → 按实际长度回填（读时计算，不写盘）。
+ */
+export declare function readArchiveFile(projectPath: string, version: string): ArchiveFile | null;
+/**
+ * 读取已归档版本索引（快照副本，防外部改内存；缺失/非数组 → []）。
+ */
+export declare function getArchivedVersions(data: FlowData): string[];
+/**
+ * 追加已归档版本（幂等去重；**纯内存**，不写盘——持久化由命令层 save() 承担）。
+ * @returns 是否新增（false = 已存在，no-op 不追加）
+ */
+export declare function addArchivedVersion(data: FlowData, version: string): boolean;
+/**
+ * 归档后 pipeline 处置（**纯内存**，不 IO；save 由调用方统一（裁定 P））。
+ *
+ * 前置条件：须在 stages 移除**之后**调用（phase 按归档后活跃集重算）。
+ * - `pipeline.current.stage` 属被归档版本 → 置空 `{ stage: '', op: '' }`（currentCleared = true）。
+ * - `pipeline.phase` 按活跃集重算：非空且全部 done → `'done'`，否则 `'active'`
+ *   （**空集 → active**，与 `flow-manager.ts:1495-1496` 空集守卫同效；REV-79-005）。
+ *
+ * @returns currentCleared = current 是否命中被归档版本；phase = 处置后的 pipeline.phase
+ */
+export declare function applyArchivePipelineDisposition(data: FlowData, version: string): {
+    currentCleared: boolean;
+    phase: MetaPhase;
+};
+//# sourceMappingURL=archive-ops.d.ts.map

package/dist/core/flow-archive/archive-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-ops.d.ts","sourceRoot":"","sources":["../../../src/core/flow-archive/archive-ops.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKxD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAW7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAUjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAoBxF;AA6BD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAG5D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAW3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,GACd;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAY/C"}

package/dist/core/flow-archive/archive-ops.js

@@ -0,0 +1,184 @@
+/**
+ * 归档读写原语与索引管理 — 归档引擎的 IO 层
+ * 职责：归档文件路径单点 / 写盘（独立锁 flow-archive + 原子写）/ 读取（宽容） / 列举 / meta.archived_versions 管理（纯内存）
+ *       + pipeline 处置（纯内存）。
+ * 写盘与锁复用 src/core/fs/ 工具层（原子写模式 + 建议性文件锁模式）；
+ * 归档锁名 `flow-archive` 与 flow 锁**不嵌套**（裁定 P；核验 A19）。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteFileSync } from '../fs/atomic-write.js';
+import { withFileLock, projectLockPath } from '../fs/file-lock.js';
+import { versionOfStageId } from './grouping.js';
+/** 归档写盘锁名（独立于 flow 锁；锁文件落 .openfeel/tmp/locks/flow-archive.lock） */
+const ARCHIVE_LOCK_NAME = 'flow-archive';
+/** 归档目录：{projectPath}/.openfeel/flow-archive（Q2 定稿：不纳入 WORKSPACE_DIRS，按需 mkdir 幂等创建） */
+export function getArchiveDir(projectPath) {
+    return join(projectPath, '.openfeel', 'flow-archive');
+}
+/**
+ * 归档文件路径：{archiveDir}/{version}.json（路径单点）。
+ *
+ * ⚠️ 仅接受**已校验**的版本字符串（经 `isValidArchiveVersion`，REV-78-011）：
+ * 本函数只做拼接、不做合法性/路径穿越校验；调用方须先走 `isValidArchiveVersion`
+ * 或使用上游已校验入口（`writeArchiveFile` / `readArchiveFile` / `listArchiveVersions`）。
+ */
+export function getArchiveFilePath(projectPath, version) {
+    return join(getArchiveDir(projectPath), `${version}.json`);
+}
+/**
+ * 版本字符串合法性（探针法复用 parseStageId，禁自写正则）：
+ * `${s}-stage-00` 可被 parseStageId 解析且版本段恒等 → 合法；空串/含路径分隔符/非版本形态 → 非法。
+ *
+ * 导出版（原私有版本校验函数重命名并导出），供命令层复用——REV-79-004。
+ */
+export function isValidArchiveVersion(s) {
+    if (s.length === 0) {
+        return false;
+    }
+    return versionOfStageId(`${s}-stage-00`) === s;
+}
+/**
+ * 版本号归一（输入前缀兼容）：trim → 去单个前导 `v`（如有）→ 补 `v` → 经 `isValidArchiveVersion` 校验。
+ * 归一方向恒为「去 v 再加 v」：引擎键恒带 `v`（与 `versionOfStageId` 输出同形态；REV-79-004）。
+ * **禁**复用 `normalizeVersion`（`src/core/plan/roadmap.ts:17`，方向相反：去 `v`）。
+ *
+ * 错误路径返回 null 的触发条件：空串 / 探针校验失败（非 vX.Y[.Z] 形态、含路径分隔符等）。
+ */
+export function normalizeArchiveVersion(input) {
+    const trimmed = input.trim();
+    // 去单个前导 v（如 `vv1.1.7` 去后剩 `v1.1.7`，仍带 v → 校验失败 → null，防双前缀）
+    const body = trimmed.startsWith('v') ? trimmed.slice(1) : trimmed;
+    const candidate = `v${body}`;
+    return isValidArchiveVersion(candidate) ? candidate : null;
+}
+/**
+ * 写归档文件（覆盖写 = 同版本幂等；backup:false，D8 定稿）。
+ * 独立锁 `flow-archive` 内原子写（同目录 temp + fsync + rename）；目录按需 mkdir（幂等）。
+ * @throws 版本字符串非法（路径穿越防御，D9）或写盘失败
+ */
+export function writeArchiveFile(projectPath, file) {
+    if (!isValidArchiveVersion(file.version)) {
+        // 破坏性写路径默认拒绝：非法版本（含路径分隔符/非版本形态）零写盘
+        throw new Error(`归档版本非法：${file.version}`);
+    }
+    const filePath = getArchiveFilePath(projectPath, file.version);
+    mkdirSync(getArchiveDir(projectPath), { recursive: true });
+    const lockPath = projectLockPath(projectPath, ARCHIVE_LOCK_NAME);
+    withFileLock(lockPath, () => {
+        atomicWriteFileSync(filePath, JSON.stringify(file, null, 2) + '\n', { backup: false });
+    });
+}
+/**
+ * 列举已归档版本（目录扫描 + 文件名合法校验）。
+ * 目录不存在 → []；仅收 `{version}.json` 且 version 通过 isValidArchiveVersion 者；返回字典序排序（非语义版本序）。
+ */
+export function listArchiveVersions(projectPath) {
+    const dir = getArchiveDir(projectPath);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => name.slice(0, -'.json'.length))
+        .filter((stem) => isValidArchiveVersion(stem))
+        .sort();
+}
+/**
+ * 读取归档文件。
+ * 缺失 / 损坏（JSON 解析失败）/ 非法版本（路径穿越防御）/ 内容非对象 → null（不抛）；
+ * 未知键保留（不重建对象）；缺 counts → 按实际长度回填（读时计算，不写盘）。
+ */
+export function readArchiveFile(projectPath, version) {
+    if (!isValidArchiveVersion(version)) {
+        return null; // 读侧宽容：非法版本不抛，视同不可读
+    }
+    const filePath = getArchiveFilePath(projectPath, version);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // 合法 JSON 但非对象（null / 数组 / 数字 / 字符串）→ 视同损坏（契约：缺失/损坏/非法 → null，REV-78-012）
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return withCountsFallback(parsed);
+    }
+    catch {
+        // 损坏（解析失败）：返回 null 不崩溃（读侧宽容；kb 读侧分类范式）
+        return null;
+    }
+}
+/** 读侧宽容：counts 三段齐全则原样返回；否则按实际长度回填（读时计算，不写盘） */
+function withCountsFallback(file) {
+    const counts = file.counts;
+    if (counts &&
+        typeof counts.stages === 'number' &&
+        typeof counts.reviews === 'number' &&
+        typeof counts.log === 'number') {
+        return file;
+    }
+    const stages = file.stages ?? {};
+    const reviews = file.reviews ?? [];
+    const log = file.log ?? [];
+    return {
+        ...file,
+        stages,
+        reviews,
+        log,
+        counts: {
+            stages: Object.keys(stages).length,
+            reviews: reviews.length,
+            log: log.length,
+        },
+    };
+}
+/**
+ * 读取已归档版本索引（快照副本，防外部改内存；缺失/非数组 → []）。
+ */
+export function getArchivedVersions(data) {
+    const list = data.meta?.archived_versions;
+    return Array.isArray(list) ? [...list] : [];
+}
+/**
+ * 追加已归档版本（幂等去重；**纯内存**，不写盘——持久化由命令层 save() 承担）。
+ * @returns 是否新增（false = 已存在，no-op 不追加）
+ */
+export function addArchivedVersion(data, version) {
+    if (!data.meta) {
+        // 防御：缺 meta 的存量/损坏数据（与 save() 的 ??= 兜底同字面量）
+        data.meta = { version: '1.0', project: '', updated: '', revision: 0 };
+    }
+    const existing = getArchivedVersions(data);
+    if (existing.includes(version)) {
+        return false; // 幂等：重复登记不追加
+    }
+    data.meta.archived_versions = [...existing, version];
+    return true;
+}
+/**
+ * 归档后 pipeline 处置（**纯内存**，不 IO；save 由调用方统一（裁定 P））。
+ *
+ * 前置条件：须在 stages 移除**之后**调用（phase 按归档后活跃集重算）。
+ * - `pipeline.current.stage` 属被归档版本 → 置空 `{ stage: '', op: '' }`（currentCleared = true）。
+ * - `pipeline.phase` 按活跃集重算：非空且全部 done → `'done'`，否则 `'active'`
+ *   （**空集 → active**，与 `flow-manager.ts:1495-1496` 空集守卫同效；REV-79-005）。
+ *
+ * @returns currentCleared = current 是否命中被归档版本；phase = 处置后的 pipeline.phase
+ */
+export function applyArchivePipelineDisposition(data, version) {
+    const current = data.pipeline?.current;
+    // 命中被归档版本 → 置空 current（stage 与 op 同清；versionOfStageId('') === null 故空串永不命中）
+    const currentCleared = !!current && versionOfStageId(current.stage) === version;
+    if (currentCleared && data.pipeline) {
+        data.pipeline.current = { stage: '', op: '' };
+    }
+    // 宏观 done 判定（空集守卫：无阶段视为非全 done → active）
+    const allDone = Object.keys(data.stages).length > 0
+        && Object.values(data.stages).every((s) => s.phase === 'done');
+    data.pipeline.phase = allDone ? 'done' : 'active';
+    return { currentCleared, phase: data.pipeline.phase };
+}
+//# sourceMappingURL=archive-ops.js.map

package/dist/core/flow-archive/archive-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-ops.js","sourceRoot":"","sources":["../../../src/core/flow-archive/archive-ops.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIjD,oEAAoE;AACpE,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEzC,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,OAAe;IACrE,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS;IAC7C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAClE,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC7B,OAAO,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,IAAiB;IACrE,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,mCAAmC;QACnC,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/D,SAAS,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;IACjE,YAAY,CAAC,QAAQ,EAAE,GAAG,EAAE;QAC1B,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,GAAG,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,CAAC;SACpB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;SAC7C,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,OAAe;IAClE,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,CAAC,oBAAoB;IACnC,CAAC;IACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,0EAA0E;QAC1E,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAqB,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAS,kBAAkB,CAAC,IAAiB;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,IACE,MAAM;QACN,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAClC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAC9B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;IAC3B,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,OAAO;QACP,GAAG;QACH,MAAM,EAAE;YACN,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM;YAClC,OAAO,EAAE,OAAO,CAAC,MAAM;YACvB,GAAG,EAAE,GAAG,CAAC,MAAM;SAChB;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAc,EAAE,OAAe;IAChE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,4CAA4C;QAC5C,IAAI,CAAC,IAAI,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACxE,CAAC;IACD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,CAAC,aAAa;IAC7B,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,iBAAiB,GAAG,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B,CAC7C,IAAc,EACd,OAAe;IAEf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC;IACvC,4EAA4E;IAC5E,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC;IAChF,IAAI,cAAc,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;IAChD,CAAC;IACD,yCAAyC;IACzC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;WAC9C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC;IACjE,IAAI,CAAC,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC"}

package/dist/core/flow-archive/grouping.d.ts

@@ -0,0 +1,58 @@
+import type { FlowData, StageData, ReviewItem, LogEntry } from '../flow-manager.js';
+import type { ArchiveFile } from './archive-file.js';
+/** splitForArchive 返回：归档段（缺 schemaVersion/archived_at，由命令层装配） + 保留段 */
+export interface SplitResult {
+    /** 归档段：不含 schemaVersion / archived_at（由 stage-79 命令层装配后交 writeArchiveFile） */
+    archive: Omit<ArchiveFile, 'schemaVersion' | 'archived_at'>;
+    /** 保留段：留在 flow.json 的条目（不可归档归属者一律落此） */
+    remainder: {
+        stages: Record<string, StageData>;
+        reviews: ReviewItem[];
+        log: LogEntry[];
+    };
+}
+/** 可归档候选（供命令面判据门消费；blocking REV 判定归命令层，本函数只读纯判定） */
+export interface ArchivableCandidate {
+    /** 版本前缀（如 `v1.1.7`） */
+    version: string;
+    /** 该版本全部 stageId（保持 stages 键遍历顺序） */
+    stages: string[];
+    /** 该版本是否全部阶段 phase=done（空集守卫：length>0 && every(done)） */
+    allDone: boolean;
+}
+/**
+ * stageId → 版本前缀（如 `v1.1.7`）。
+ * 复用 parseStageId（唯一权威，禁自写正则）：fullStageId = `${version}-${stageDir}`，剥离 `-${stageDir}` 后缀即版本段。
+ * 短名 stageId 经 parseStageId 归一化为 `v1.0.0-*`（DEFAULT_STAGE_VERSION，既定语义）。
+ * 无法解析返回 null。
+ */
+export declare function versionOfStageId(stageId: string): string | null;
+/**
+ * stages 按版本前缀分组（版本 → stageId 列表）。
+ * 保持稳定顺序（按 stages 键遍历顺序）；无法解析的 stageId 跳过（不产生分组 → 永不归档）。
+ */
+export declare function groupStagesByVersion(stages: Record<string, StageData>): Map<string, string[]>;
+/**
+ * 可归档候选列表（只读纯函数）：版本 + 该版本 stageId 列表 + 是否全部 phase=done。
+ * allDone 采用空集守卫（length > 0 && every(done)，对齐 flow-manager.ts:1484-1486 范式——空集不判 done）。
+ * 不判 REV（blocking open REV 判定归命令层，裁定 O2）。
+ */
+export declare function listArchivableCandidates(data: FlowData): ArchivableCandidate[];
+/**
+ * 版本作用域内的「阻塞 open」审查条目（只读纯函数；返回新数组副本，push 不影响 data.reviews）。
+ *
+ * 谓词为**全仓唯一**口径（对齐 `flow-manager.ts:1456`/`:1570`；REV-79-002）：
+ * `r.blocking !== false && r.status === 'open'` —— blocking 缺省（undefined）= 阻塞。
+ * 版本作用域解析与 splitForArchive **同源**（复用本文件私有 versionOfReviewOp）。
+ */
+export declare function listBlockingOpenRevsForVersion(data: FlowData, version: string): ReviewItem[];
+/**
+ * 按版本切分 flow 数据（纯函数，不写盘）。
+ * - stages：该版本全部 stageId 条目整体搬入 archive；其余（含不可解析 stageId）保留 remainder。
+ * - reviews：`versionOfReviewOp(r.op) === version` 者搬入；其余保留（保序）。
+ * - log：`versionOfLogEntry(e) === version` 者搬入；其余保留（保序；无 stageName / 不可解析一律保留）。
+ * - 版本不存在 → archive 为空集（counts 全 0），不抛错。
+ * 返回集合中的对象为原数据浅引用（调用方不得修改）。
+ */
+export declare function splitForArchive(data: FlowData, version: string): SplitResult;
+//# sourceMappingURL=grouping.d.ts.map

package/dist/core/flow-archive/grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.d.ts","sourceRoot":"","sources":["../../../src/core/flow-archive/grouping.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC;IAC5D,wCAAwC;IACxC,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAClC,OAAO,EAAE,UAAU,EAAE,CAAC;QACtB,GAAG,EAAE,QAAQ,EAAE,CAAC;KACjB,CAAC;CACH;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAe7F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,EAAE,CAO9E;AAiBD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAI5F;AAeD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAiD5E"}

package/dist/core/flow-archive/grouping.js

@@ -0,0 +1,153 @@
+/**
+ * 版本分组与切分纯函数 — 归档引擎的解析核心
+ * 职责：stageId → 版本前缀（复用 parseStageId，禁自写正则）；
+ *      按版本分组；按版本切分 flow 数据（stages 全搬 / reviews 按 op 前缀 / log 按 detail.stageName）。
+ * 本文件全部为纯函数（只读输入，不写盘、不加锁、不读环境）。
+ */
+import { parseStageId } from '../plan/path.js';
+/**
+ * stageId → 版本前缀（如 `v1.1.7`）。
+ * 复用 parseStageId（唯一权威，禁自写正则）：fullStageId = `${version}-${stageDir}`，剥离 `-${stageDir}` 后缀即版本段。
+ * 短名 stageId 经 parseStageId 归一化为 `v1.0.0-*`（DEFAULT_STAGE_VERSION，既定语义）。
+ * 无法解析返回 null。
+ */
+export function versionOfStageId(stageId) {
+    const parsed = parseStageId(stageId);
+    if (!parsed) {
+        return null;
+    }
+    const suffix = `-${parsed.stageDir}`;
+    if (!parsed.fullStageId.endsWith(suffix)) {
+        return null;
+    }
+    return parsed.fullStageId.slice(0, -suffix.length);
+}
+/**
+ * stages 按版本前缀分组（版本 → stageId 列表）。
+ * 保持稳定顺序（按 stages 键遍历顺序）；无法解析的 stageId 跳过（不产生分组 → 永不归档）。
+ */
+export function groupStagesByVersion(stages) {
+    const groups = new Map();
+    for (const stageId of Object.keys(stages)) {
+        const version = versionOfStageId(stageId);
+        if (!version) {
+            continue; // 无法解析 → 不分组（保留在 flow.json）
+        }
+        const list = groups.get(version);
+        if (list) {
+            list.push(stageId);
+        }
+        else {
+            groups.set(version, [stageId]);
+        }
+    }
+    return groups;
+}
+/**
+ * 可归档候选列表（只读纯函数）：版本 + 该版本 stageId 列表 + 是否全部 phase=done。
+ * allDone 采用空集守卫（length > 0 && every(done)，对齐 flow-manager.ts:1484-1486 范式——空集不判 done）。
+ * 不判 REV（blocking open REV 判定归命令层，裁定 O2）。
+ */
+export function listArchivableCandidates(data) {
+    const result = [];
+    for (const [version, stageIds] of groupStagesByVersion(data.stages)) {
+        const allDone = stageIds.length > 0 && stageIds.every((id) => data.stages[id]?.phase === 'done');
+        result.push({ version, stages: stageIds, allDone });
+    }
+    return result;
+}
+/**
+ * reviews 条目 → 版本前缀。
+ * `op` 形如 `<stageId>.op-NNN` 或 `<stageId>`：点号锚定正则 `/^(.+)\.(op-\d+)$/` 剥离 opId 段
+ * （stageId 自身可含点号，禁 split('.')；见 archive/merge.ts:57-67 既有范式）；stageId 段经 versionOfStageId。
+ * 无法归属返回 null（→ 保留在 flow.json）。
+ */
+function versionOfReviewOp(op) {
+    if (typeof op !== 'string' || op.length === 0) {
+        return null;
+    }
+    const anchor = op.match(/^(.+)\.(op-\d+)$/);
+    const stageId = anchor ? anchor[1] : op;
+    return versionOfStageId(stageId);
+}
+/**
+ * 版本作用域内的「阻塞 open」审查条目（只读纯函数；返回新数组副本，push 不影响 data.reviews）。
+ *
+ * 谓词为**全仓唯一**口径（对齐 `flow-manager.ts:1456`/`:1570`；REV-79-002）：
+ * `r.blocking !== false && r.status === 'open'` —— blocking 缺省（undefined）= 阻塞。
+ * 版本作用域解析与 splitForArchive **同源**（复用本文件私有 versionOfReviewOp）。
+ */
+export function listBlockingOpenRevsForVersion(data, version) {
+    return (data.reviews ?? []).filter((r) => versionOfReviewOp(r.op) === version && r.blocking !== false && r.status === 'open');
+}
+/**
+ * log 条目 → 版本前缀。
+ * 唯一读 `detail.stageName`（裁定 T）；缺失 / 非字符串 / 不可解析 → null（保留在 flow.json）。
+ * 注意：`detail.stageId` / `detail.stage` 等其它键一律不看（保守裁定，见 D3）。
+ */
+function versionOfLogEntry(entry) {
+    const stageName = entry?.detail?.['stageName'];
+    if (typeof stageName !== 'string') {
+        return null;
+    }
+    return versionOfStageId(stageName);
+}
+/**
+ * 按版本切分 flow 数据（纯函数，不写盘）。
+ * - stages：该版本全部 stageId 条目整体搬入 archive；其余（含不可解析 stageId）保留 remainder。
+ * - reviews：`versionOfReviewOp(r.op) === version` 者搬入；其余保留（保序）。
+ * - log：`versionOfLogEntry(e) === version` 者搬入；其余保留（保序；无 stageName / 不可解析一律保留）。
+ * - 版本不存在 → archive 为空集（counts 全 0），不抛错。
+ * 返回集合中的对象为原数据浅引用（调用方不得修改）。
+ */
+export function splitForArchive(data, version) {
+    const archiveStages = {};
+    const remainderStages = {};
+    for (const [stageId, stage] of Object.entries(data.stages)) {
+        if (versionOfStageId(stageId) === version) {
+            archiveStages[stageId] = stage;
+        }
+        else {
+            remainderStages[stageId] = stage;
+        }
+    }
+    const archiveReviews = [];
+    const remainderReviews = [];
+    for (const review of data.reviews ?? []) {
+        if (versionOfReviewOp(review.op) === version) {
+            archiveReviews.push(review);
+        }
+        else {
+            remainderReviews.push(review);
+        }
+    }
+    const archiveLog = [];
+    const remainderLog = [];
+    for (const entry of data.log ?? []) {
+        if (versionOfLogEntry(entry) === version) {
+            archiveLog.push(entry);
+        }
+        else {
+            remainderLog.push(entry);
+        }
+    }
+    return {
+        archive: {
+            version,
+            stages: archiveStages,
+            reviews: archiveReviews,
+            log: archiveLog,
+            counts: {
+                stages: Object.keys(archiveStages).length,
+                reviews: archiveReviews.length,
+                log: archiveLog.length,
+            },
+        },
+        remainder: {
+            stages: remainderStages,
+            reviews: remainderReviews,
+            log: remainderLog,
+        },
+    };
+}
+//# sourceMappingURL=grouping.js.map

package/dist/core/flow-archive/grouping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.js","sourceRoot":"","sources":["../../../src/core/flow-archive/grouping.ts"],"names":[],"mappings":"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"}