@harrylabsj/kiwi 0.8.0 → 0.9.0

package/dist/merchant-runtime/backup.js

@@ -0,0 +1,226 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 持续备份（V2 阶段四 + BUG-06 修复：src/merchant-runtime/backup.ts）。
+ *
+ * 事务一致性：
+ *   - SQLite 文件用 `VACUUM INTO`（读事务一致性快照；源库 WAL 模式下并发写
+ *     安全；busy 时短暂重试，仍失败则本轮备份 fail-closed 记错误）；
+ *   - 快照完成后实际打开备份库跑 `PRAGMA integrity_check`，不通过即删除该轮
+ *     快照并抛错（绝不留下不可恢复的快照）；
+ *   - Ledger 等文件类数据在 SQLite 快照之后复制——最终一致性边界：append
+ *     中的最后一行可能是部分写入，恢复端按 Ledger 链校验容错（文档化，
+ *     见 deploy/merchant-bundle/README.md）。
+ *
+ * RPO 口径（工程诚实）：周期快照的 RPO ≤ 备份周期（缺省 5 分钟），
+ * 不宣称 RPO=0；RPO=0 需同步持久化/持续复制（留主备阶段）。
+ * 快照写 manifest（文件清单 + 大小 + sha256）供恢复校验；轮换保留最近 N 份。
+ */
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { writeFileAtomic } from "../fs/atomic-write.js";
+function walk(dir, base, out, skipped) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(full, base, out, skipped);
+        else if (entry.isFile())
+            out.push(path.relative(base, full));
+        else if (entry.isSymbolicLink()) {
+            // 审查 P2：symlink 数据静默丢弃会让恢复后出现「校验全绿」的数据缺口
+            // ——至少记入 manifest 跳过清单，让缺口可见。
+            skipped.push(path.relative(base, full));
+        }
+    }
+}
+function sha256File(file) {
+    return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+/**
+ * SQLite 事务一致性快照（BUG-06）：VACUUM INTO（读事务一致；源库 WAL 下并发
+ * 写安全）。busy/失败短暂重试，仍失败抛错（本轮备份 fail-closed）。
+ * 快照后打开备份库跑 integrity_check——不通过即抛错（调用方删除该轮快照）。
+ */
+function snapshotSqlite(src, dst) {
+    mkdirSync(path.dirname(dst), { recursive: true, mode: 0o700 });
+    rmSync(dst, { force: true });
+    if (!existsSync(src)) {
+        // 审查 P2：DatabaseSync 缺省会静默建空库——源在 walk 与快照之间消失时
+        // 会产出「校验全绿」的空库快照（静默数据丢失）。fail-closed。
+        throw new Error(`SQLite 源库不存在，拒绝快照（fail-closed）：${src}`);
+    }
+    let lastErr;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        let db;
+        try {
+            db = new DatabaseSync(src, { readOnly: true });
+            db.exec("PRAGMA busy_timeout = 2000");
+            // VACUUM INTO 目标路径防注入：单引号转义
+            db.exec(`VACUUM INTO '${dst.replaceAll("'", "''")}'`);
+            db.close();
+            db = undefined;
+            const check = new DatabaseSync(dst);
+            try {
+                const rows = check.prepare("PRAGMA integrity_check").all();
+                if (rows.length !== 1 || rows[0]?.integrity_check !== "ok") {
+                    throw new Error(`备份库 integrity_check 未通过：${dst}（${JSON.stringify(rows)}）`);
+                }
+            }
+            finally {
+                check.close();
+            }
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            if (db !== undefined) {
+                try {
+                    db.close();
+                }
+                catch {
+                    // 忽略
+                }
+            }
+            rmSync(dst, { force: true });
+        }
+    }
+    throw new Error(`SQLite 快照失败（${src}）：${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+}
+/** 快照备份 + 轮换（keepLatest 份）。幂等：同时间戳目录复用覆盖。
+ *  启动时清理孤儿快照目录（审查 P2：优雅关闭/崩溃打断备份留下的无 manifest
+ *  目录既不参与轮换也永不清理，反复在备份窗口重启可累积占满磁盘）。 */
+export function runBackup(options) {
+    const now = (options.now ?? (() => new Date().toISOString()))();
+    const keep = options.keepLatest ?? 10;
+    // 孤儿快照清理：无 manifest.json 且修改时间超过 1 小时的目录（1 小时缓冲
+    // 避免误删并发进行中的快照——jobs 已串行，此处是双保险）。
+    try {
+        for (const entry of readdirSync(options.backupsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = path.join(options.backupsDir, entry.name);
+            if (existsSync(path.join(dir, "manifest.json")))
+                continue;
+            try {
+                if (Date.now() - statSync(dir).mtimeMs > 60 * 60 * 1000) {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // 单个目录清理失败不影响本轮备份
+            }
+        }
+    }
+    catch {
+        // backups 目录不存在等：交给下方 mkdirSync
+    }
+    const stamp = now.replace(/[:.]/g, "-");
+    const snapshotDir = path.join(options.backupsDir, stamp);
+    mkdirSync(snapshotDir, { recursive: true, mode: 0o700 });
+    const files = [];
+    const skipped = [];
+    walk(options.dataDir, options.dataDir, files, skipped);
+    // 不备份 backups 自身（若 backups 在 dataDir 内）、锁文件与 SQLite WAL/SHM 临时文件
+    const included = files.filter((f) => !f.startsWith("backups") &&
+        !f.endsWith(".lock") &&
+        !f.endsWith(".tmp") &&
+        !f.endsWith(".sqlite-wal") &&
+        !f.endsWith(".sqlite-shm"));
+    try {
+        // SQLite 先行（VACUUM INTO 一致性快照），文件类随后（最终一致性边界见文件头）
+        const sorted = included.sort((a, b) => {
+            const aSql = a.endsWith(".sqlite") ? 0 : 1;
+            const bSql = b.endsWith(".sqlite") ? 0 : 1;
+            return aSql - bSql || (a < b ? -1 : 1);
+        });
+        const manifest = {
+            created_at: now,
+            source_dir: options.dataDir,
+            files: [],
+            ...(skipped.length > 0 ? { skipped } : {}),
+        };
+        for (const rel of sorted) {
+            const src = path.join(options.dataDir, rel);
+            const dst = path.join(snapshotDir, rel);
+            if (rel.endsWith(".sqlite")) {
+                snapshotSqlite(src, dst);
+            }
+            else {
+                mkdirSync(path.dirname(dst), { recursive: true, mode: 0o700 });
+                cpSync(src, dst);
+            }
+            // manifest 记录的是**快照内容**的摘要（dst），恢复校验的是快照自身完整性
+            manifest.files.push({ path: rel, bytes: statSync(dst).size, sha256: sha256File(dst) });
+        }
+        writeFileSync(path.join(snapshotDir, "manifest.json"), JSON.stringify(manifest, null, 2), {
+            mode: 0o600,
+        });
+        // 审查 P2：成功备份的最新时间戳（health 的 backup_stale 告警读取）。
+        writeFileAtomic(path.join(options.backupsDir, "latest-backup.json"), `${JSON.stringify({ created_at: now, snapshot_dir: snapshotDir }, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (err) {
+        // 失败轮次不留半成品快照
+        rmSync(snapshotDir, { recursive: true, force: true });
+        throw err;
+    }
+    // 轮换：保留最近 keep 份
+    const snapshots = readdirSync(options.backupsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(path.join(options.backupsDir, e.name, "manifest.json")))
+        .map((e) => e.name)
+        .sort()
+        .reverse();
+    const rotatedOut = [];
+    for (const old of snapshots.slice(keep)) {
+        rmSync(path.join(options.backupsDir, old), { recursive: true, force: true });
+        rotatedOut.push(old);
+    }
+    const manifest = JSON.parse(readFileSync(path.join(snapshotDir, "manifest.json"), "utf8"));
+    return { snapshot_dir: snapshotDir, manifest, rotated_out: rotatedOut };
+}
+/** 恢复（恢复演练同路径）：按 manifest 校验快照完整性后回写目标目录。 */
+export function restoreBackup(options) {
+    const manifest = JSON.parse(readFileSync(path.join(options.snapshotDir, "manifest.json"), "utf8"));
+    // 路径越界守卫（审查 P2）：manifest 可能来自异地/他人，files[].path 含
+    // `..` 段或绝对路径即是任意文件写入原语——逐条校验后再落盘。
+    const targetRoot = path.resolve(options.targetDir);
+    const safeRel = (rel) => {
+        const normalized = path.normalize(rel);
+        if (path.isAbsolute(normalized) || normalized.split(path.sep).includes("..")) {
+            throw new Error(`备份清单路径越界（拒绝恢复）：${rel}`);
+        }
+        return normalized;
+    };
+    // 先校验完整性（manifest 内每个文件存在且 sha256 一致）——不完整拒绝恢复。
+    for (const f of manifest.files) {
+        const rel = safeRel(f.path);
+        const src = path.join(options.snapshotDir, rel);
+        if (!existsSync(src))
+            throw new Error(`备份快照缺文件 ${f.path}（不完整，拒绝恢复）`);
+        if (sha256File(src) !== f.sha256) {
+            throw new Error(`备份快照文件 ${f.path} 摘要不一致（损坏，拒绝恢复）`);
+        }
+    }
+    mkdirSync(options.targetDir, { recursive: true, mode: 0o700 });
+    for (const f of manifest.files) {
+        const dst = path.join(targetRoot, safeRel(f.path));
+        mkdirSync(path.dirname(dst), { recursive: true, mode: 0o700 });
+        cpSync(path.join(options.snapshotDir, safeRel(f.path)), dst);
+    }
+    return { restored: manifest.files.length, verified: true };
+}
+//# sourceMappingURL=backup.js.map

package/dist/merchant-runtime/backup.js.map

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

package/dist/merchant-runtime/health.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ManagedServiceState } from "./manager.js";
+export interface MerchantAlert {
+    code: "process_down" | "product_source_unavailable" | "registration_invalid" | "backlog" | "disk_low" | "cert_expiring" | "backup_stale";
+    severity: "critical" | "warning";
+    message: string;
+}
+export interface MerchantHealthReport {
+    ok: boolean;
+    checked_at: string;
+    checks: {
+        processes: {
+            ok: boolean;
+            services: ManagedServiceState[];
+        };
+        product_source: {
+            ok: boolean;
+            version?: string;
+            error?: string;
+        };
+        data_dir: {
+            ok: boolean;
+            path: string;
+            writable: boolean;
+        };
+        disk: {
+            ok: boolean;
+            free_bytes?: number;
+        };
+        registration: {
+            ok: boolean;
+            error?: string;
+            evaluated: boolean;
+        };
+        backlog: {
+            ok: true;
+            pending: number;
+            threshold: number;
+        };
+        certificate: {
+            ok: boolean;
+            days_left?: number;
+            evaluated: boolean;
+        };
+        backup: {
+            ok: true;
+            evaluated: boolean;
+            last_success_at?: string;
+            error?: string;
+        };
+    };
+    /** 结构化告警事件（V2 阶段四 7×24；超阈值/失效即产生，可供通知通道消费）。 */
+    alerts: MerchantAlert[];
+}
+/** 磁盘余量下限（字节；缺省 100MB）。 */
+export declare const MIN_FREE_BYTES: number;
+/** 待处理命令积压告警阈值（缺省 50）。 */
+export declare const BACKLOG_ALERT_THRESHOLD = 50;
+/** 证书临期告警阈值（天；缺省 14）。 */
+export declare const CERT_EXPIRING_DAYS = 14;
+/** 能力探测记录最大有效期（BUG-05；缺省 3 分钟 = 3 个健康轮询周期）。 */
+export declare const PROBE_MAX_AGE_MS = 180000;
+export interface MerchantHealthDeps {
+    /** merchantDataDir（V2 §5.1）。 */
+    dataDir: string;
+    /** 受管服务状态（来自 MerchantRuntimeManager.status()）。 */
+    services: ManagedServiceState[];
+    now?: () => string;
+    minFreeBytes?: number;
+    /** 待处理命令数（积压告警；缺省 0）。 */
+    pendingCommands?: number;
+    /** 注册检查报告（F25；缺省不评）。 */
+    registration?: {
+        ok: boolean;
+        error?: string;
+    };
+    /** TLS 证书剩余天数（可选；配置了才评）。 */
+    certDaysLeft?: number;
+    /** 能力探测记录最大有效期（BUG-05；过期记录判 unhealthy）。 */
+    probeMaxAgeMs?: number;
+    /** 备份新鲜度（审查 P2：备份停摆进告警通道，不再只活在内存 jobs 里）。
+     *  读 <backupsDir>/latest-backup.json（runBackup 成功后原子落盘）。 */
+    backupMaxAgeMs?: number;
+}
+export declare function collectMerchantHealth(deps: MerchantHealthDeps): MerchantHealthReport;

package/dist/merchant-runtime/health.js

@@ -0,0 +1,206 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Merchant 实例分项健康检查（V2 阶段一：src/merchant-runtime/health.ts）。
+ *
+ * 分项：受管进程存活、商品源（shopping-cli 能力探测结果，读
+ * capability-probe.json 落盘记录——探测本身在 merchant-client.ts）、状态
+ * 目录可写、磁盘余量。输出结构化健康报告；任一分项失败 → ok:false，
+ * 不吞错不编造（fail-closed 口径与能力探测一致）。
+ */
+import { existsSync, readFileSync, statfsSync, writeFileSync, rmSync } from "node:fs";
+import path from "node:path";
+/** 磁盘余量下限（字节；缺省 100MB）。 */
+export const MIN_FREE_BYTES = 100 * 1024 * 1024;
+/** 待处理命令积压告警阈值（缺省 50）。 */
+export const BACKLOG_ALERT_THRESHOLD = 50;
+/** 证书临期告警阈值（天；缺省 14）。 */
+export const CERT_EXPIRING_DAYS = 14;
+/** 能力探测记录最大有效期（BUG-05；缺省 3 分钟 = 3 个健康轮询周期）。 */
+export const PROBE_MAX_AGE_MS = 180_000;
+export function collectMerchantHealth(deps) {
+    const checkedAt = (deps.now ?? (() => new Date().toISOString()))();
+    const minFree = deps.minFreeBytes ?? MIN_FREE_BYTES;
+    const processes = {
+        ok: deps.services.every((s) => s.running),
+        services: deps.services,
+    };
+    // 商品源：读能力探测落盘记录（探测动作在 mcp serve 启动/健康轮询时执行）。
+    // 商品源：读能力探测落盘记录（BUG-05：加新鲜度判定——超时/连接失败/HTTP
+    // 异常/记录过期均判 unhealthy；实时探测由周期任务执行，见 cli runtime start）。
+    const probePath = path.join(deps.dataDir, "capability-probe.json");
+    const probeMaxAgeMs = deps.probeMaxAgeMs ?? PROBE_MAX_AGE_MS;
+    let productSource;
+    if (!existsSync(probePath)) {
+        productSource = { ok: false, error: "无能力探测记录（capability-probe.json 不存在）" };
+    }
+    else {
+        try {
+            const probe = JSON.parse(readFileSync(probePath, "utf8"));
+            const probedAt = Date.parse(probe.probed_at);
+            const stale = !Number.isFinite(probedAt) || Date.parse(checkedAt) - probedAt > probeMaxAgeMs;
+            productSource = {
+                ok: probe.ok === true && !stale,
+                ...(probe.version !== undefined ? { version: probe.version } : {}),
+                ...(probe.error !== undefined ? { error: probe.error } : {}),
+                ...(stale ? { error: `能力探测记录过期（probed_at ${probe.probed_at}，超过 ${probeMaxAgeMs}ms 未刷新）` } : {}),
+            };
+        }
+        catch (err) {
+            productSource = {
+                ok: false,
+                error: `能力探测记录损坏：${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // 状态目录可写（写探针文件即删）
+    let writable = false;
+    const probe = path.join(deps.dataDir, "runtime", ".health-probe");
+    try {
+        writeFileSync(probe, checkedAt, { mode: 0o600 });
+        rmSync(probe, { force: true });
+        writable = true;
+    }
+    catch {
+        writable = false;
+    }
+    let freeBytes;
+    try {
+        const fs = statfsSync(deps.dataDir);
+        freeBytes = fs.bavail * fs.bsize;
+    }
+    catch {
+        freeBytes = undefined;
+    }
+    const pending = deps.pendingCommands ?? 0;
+    // 备份新鲜度（审查 P2）：runBackup 每次成功后落 latest-backup.json；
+    // 超过 maxAge（缺省 3×5min 备份周期）或从未成功 → 告警（warning，不翻转
+    // 整体 ok——进程/数据面健康不受备份停摆影响，但必须可见）。
+    const backupMaxAgeMs = deps.backupMaxAgeMs ?? 15 * 60_000;
+    const latestBackupPath = path.join(deps.dataDir, "backups", "latest-backup.json");
+    // backup 与 backlog 同为 warning 面：不翻转整体 ok（进程/数据面健康不受
+    // 备份停摆影响），停摆经 backup_stale 告警进入通知通道。
+    let backupStale;
+    let backupLastSuccessAt;
+    if (!existsSync(latestBackupPath)) {
+        backupStale = "尚无成功备份记录（latest-backup.json 不存在）";
+    }
+    else {
+        try {
+            const record = JSON.parse(readFileSync(latestBackupPath, "utf8"));
+            const at = typeof record.created_at === "string" ? record.created_at : undefined;
+            const age = at !== undefined ? Date.parse(checkedAt) - Date.parse(at) : Number.NaN;
+            if (!Number.isFinite(age)) {
+                backupStale = "latest-backup.json 缺少有效 created_at";
+            }
+            else if (age > backupMaxAgeMs) {
+                backupStale = `最近成功备份距今 ${Math.round(age / 60000)} 分钟（阈值 ${Math.round(backupMaxAgeMs / 60000)}）`;
+            }
+            else if (at !== undefined) {
+                backupLastSuccessAt = at;
+            }
+        }
+        catch (err) {
+            backupStale = `latest-backup.json 损坏：${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    const checks = {
+        processes,
+        product_source: productSource,
+        data_dir: { ok: writable, path: deps.dataDir, writable },
+        disk: {
+            ok: freeBytes !== undefined && freeBytes >= minFree,
+            ...(freeBytes !== undefined ? { free_bytes: freeBytes } : {}),
+        },
+        // registration/certificate are optional inputs, but when supplied their
+        // critical failures must affect health.ok rather than only producing an
+        // alert that callers might ignore.
+        registration: {
+            ok: deps.registration?.ok ?? true,
+            evaluated: deps.registration !== undefined,
+            ...(deps.registration?.error !== undefined ? { error: deps.registration.error } : {}),
+        },
+        // Backlog is a warning condition and should not trigger process restart.
+        backlog: { ok: true, pending, threshold: BACKLOG_ALERT_THRESHOLD },
+        backup: {
+            ok: true,
+            evaluated: true,
+            ...(backupLastSuccessAt !== undefined ? { last_success_at: backupLastSuccessAt } : {}),
+            ...(backupStale !== undefined ? { error: backupStale } : {}),
+        },
+        certificate: {
+            ok: deps.certDaysLeft === undefined || deps.certDaysLeft > 0,
+            evaluated: deps.certDaysLeft !== undefined,
+            ...(deps.certDaysLeft !== undefined ? { days_left: deps.certDaysLeft } : {}),
+        },
+    };
+    // 结构化告警（7×24；每个告警有明确 code/severity，供通知通道消费）。
+    const alerts = [];
+    for (const s of deps.services) {
+        if (!s.running) {
+            alerts.push({
+                code: "process_down",
+                severity: "critical",
+                message: `受管进程 ${s.name} 未运行`,
+            });
+        }
+    }
+    if (!productSource.ok) {
+        alerts.push({
+            code: "product_source_unavailable",
+            severity: "critical",
+            message: `商品源不可用：${productSource.error ?? "未知"}`,
+        });
+    }
+    if (deps.registration !== undefined && !deps.registration.ok) {
+        alerts.push({
+            code: "registration_invalid",
+            severity: "critical",
+            message: `catalog 注册失效：${deps.registration.error ?? "未知"}`,
+        });
+    }
+    if (pending > BACKLOG_ALERT_THRESHOLD) {
+        alerts.push({
+            code: "backlog",
+            severity: "warning",
+            message: `待处理命令积压 ${pending}（阈值 ${BACKLOG_ALERT_THRESHOLD}）`,
+        });
+    }
+    if (!checks.disk.ok) {
+        alerts.push({ code: "disk_low", severity: "warning", message: "磁盘余量低于下限" });
+    }
+    if (!checks.backup.ok) {
+        alerts.push({
+            code: "backup_stale",
+            severity: "warning",
+            message: `备份停摆：${checks.backup.error ?? "未知"}`,
+        });
+    }
+    if (deps.certDaysLeft !== undefined && deps.certDaysLeft <= CERT_EXPIRING_DAYS) {
+        alerts.push({
+            code: "cert_expiring",
+            severity: deps.certDaysLeft <= 3 ? "critical" : "warning",
+            message: `TLS 证书 ${deps.certDaysLeft} 天后到期`,
+        });
+    }
+    return {
+        ok: Object.values(checks).every((c) => c.ok),
+        checked_at: checkedAt,
+        checks,
+        alerts,
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/merchant-runtime/health.js.map

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

package/dist/merchant-runtime/jobs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Merchant 实例周期任务骨架（V2 阶段一：src/merchant-runtime/jobs.ts）。
+ *
+ * 本轮落地：健康轮询（health-poll，刷新 capability-probe 与健康报告）+
+ * 持续备份接缝（backup hook——备份实现放阶段四，本轮注册即明确报「未实现」，
+ * 不静默假装已备份）。任务串行执行、异常隔离（单个任务失败不影响其他任务
+ * 与宿主进程），错误进最近运行记录。
+ */
+export interface MerchantJob {
+    name: string;
+    intervalMs: number;
+    run: () => Promise<void>;
+}
+export interface MerchantJobRunRecord {
+    name: string;
+    last_run_at?: string;
+    last_error?: string;
+    runs: number;
+}
+export declare class MerchantJobs {
+    private readonly jobs;
+    private readonly timers;
+    private readonly records;
+    /** 在途任务（审查 P2：重入保护，防长备份与健康轮询自我重叠）。 */
+    private readonly inFlight;
+    private readonly now;
+    private running;
+    constructor(options?: {
+        now?: () => string;
+    });
+    register(job: MerchantJob): void;
+    /** 立即执行一次（异常隔离：记录 last_error，不抛出）。同任务在途时跳过
+     *  （审查 P2：与「串行执行」文档口径一致——长任务不与下一轮并发重叠）。 */
+    runOnce(name: string): Promise<MerchantJobRunRecord>;
+    /** 启动全部周期任务。 */
+    start(): void;
+    stop(): void;
+    list(): MerchantJobRunRecord[];
+}
+/**
+ * 标准任务集：健康轮询 + 持续备份接缝。
+ * backupHook 缺省 = 阶段四未实现的明确接缝（记录错误，绝不静默成功）。
+ */
+export declare function standardMerchantJobs(deps: {
+    healthPoll: () => Promise<void>;
+    backupHook?: () => Promise<void>;
+    healthIntervalMs?: number;
+    backupIntervalMs?: number;
+}): MerchantJob[];