@actiondock/core 2.20.0 → 2.21.0

package/dist/storage/config-value.js

@@ -0,0 +1,102 @@
+import { ActionDockError, CONFIG_DECRYPT_FAILED } from "../errors.js";
+import { decryptConfigValue, encryptConfigValue, } from "../security/config-cipher.js";
+import { isSecretConfigKey } from "./mask.js";
+/**
+ * 对保护声明递归剥离脱敏无关信息。
+ *
+ * 仅保留结构（properties/additionalProperties/items）、类型与 secret
+ * 标记；严禁把 default、enum、env、description 等可能携带值的内容
+ * 写入保护元数据，即使信封整体已加密也保持最小化。
+ */
+function sanitizeProtectionSchema(schema) {
+    const copy = {};
+    if (schema.type !== undefined)
+        copy.type = schema.type;
+    if (schema.secret !== undefined)
+        copy.secret = schema.secret;
+    if (schema.properties) {
+        copy.properties = Object.fromEntries(Object.entries(schema.properties).map(([name, child]) => [
+            name,
+            sanitizeProtectionSchema(child),
+        ]));
+    }
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties === "object") {
+        copy.additionalProperties = sanitizeProtectionSchema(schema.additionalProperties);
+    }
+    if (schema.items !== undefined && typeof schema.items === "object") {
+        copy.items = sanitizeProtectionSchema(schema.items);
+    }
+    return copy;
+}
+/** 对单条保护声明剥离脱敏无关字段（保留 secret/type/schema 结构信息）。 */
+function sanitizeProtectionDeclaration(item) {
+    const copy = {};
+    if (item.secret !== undefined)
+        copy.secret = item.secret;
+    if (item.type !== undefined)
+        copy.type = item.type;
+    if (item.schema)
+        copy.schema = sanitizeProtectionSchema(item.schema);
+    return copy;
+}
+/**
+ * 合并历史保护声明与当前敏感声明，绝不弱化保护强度。
+ *
+ * - 以规范化 JSON 作为去重标识，防止重复写入导致保护数组无界增长；
+ * - 当前声明中仅并入判定敏感的条目（非敏感声明不产生历史保护义务）；
+ * - 合并结果为空时保守回退为整项敏感，保证密文行始终有脱敏依据。
+ */
+export function mergeProtectionDeclarations(stored, current, key) {
+    const merged = [];
+    const seen = new Set();
+    const push = (item) => {
+        const sanitized = sanitizeProtectionDeclaration(item);
+        const identity = JSON.stringify(sanitized);
+        if (!seen.has(identity)) {
+            seen.add(identity);
+            merged.push(sanitized);
+        }
+    };
+    for (const item of stored ?? []) {
+        push(item);
+    }
+    for (const item of current) {
+        if (isSecretConfigKey(key, item)) {
+            push(item);
+        }
+    }
+    if (merged.length === 0) {
+        merged.push({ secret: true });
+    }
+    return merged;
+}
+/** 加密业务值与保护声明构成的完整信封，返回规范密文信封字符串。 */
+export function encryptConfigEnvelope(value, protection, scope, key, material) {
+    const envelope = { value, protection: [...protection] };
+    return encryptConfigValue(envelope, scope, key, material);
+}
+/**
+ * 严格解密密文信封并校验负载形态。
+ *
+ * 信封负载必须为含 value 属性的对象；protection 省略或为声明对象数组。
+ * 任何不合规输入抛 CONFIG_DECRYPT_FAILED，绝不把密文降级当作明文返回。
+ */
+export function decryptConfigEnvelope(ciphertext, scope, key, material) {
+    const payload = decryptConfigValue(ciphertext, scope, key, material);
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload) ||
+        !Object.prototype.hasOwnProperty.call(payload, "value")) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decrypted config payload for key '${key}' in scope '${scope}' is not a valid protection envelope`, { scope, key });
+    }
+    const envelope = payload;
+    if (envelope.protection !== undefined &&
+        (!Array.isArray(envelope.protection) ||
+            envelope.protection.some((item) => item === null || typeof item !== "object"))) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decrypted protection metadata for config key '${key}' in scope '${scope}' is malformed`, { scope, key });
+    }
+    return {
+        value: envelope.value,
+        protection: envelope.protection ?? [],
+    };
+}

package/dist/storage/file-lock.js

@@ -292,6 +292,10 @@ function* acquireLockMachine(lockPath, options, isAsync) {
                             isDir = s.isDirectory();
                         }
                         catch { }
+                        // 所有权仲裁：陈旧目录在守卫独占保护下不可能被他人新建，可直接接管；
+                        // 陈旧单文件被 unlink 后存在创建间隙，仅当本回收者亲自 mkdir 成功才可宣称所有权，
+                        // 否则主锁已被他人在守卫外真实创建，严禁覆盖现存元数据或删除赢家
+                        let mainLockClaimable = isDir;
                         if (!isDir) {
                             try {
                                 yield (d) => d.unlink(lockPath);
@@ -299,35 +303,45 @@ function* acquireLockMachine(lockPath, options, isAsync) {
                             catch { }
                             try {
                                 yield (d) => d.mkdir(lockPath, { mode: 0o700 });
+                                mainLockClaimable = true;
                             }
                             catch (err) {
                                 if (err.code !== "EEXIST")
                                     throw err;
                             }
+                            if (!mainLockClaimable && !isAsync) {
+                                // 同步语义：主锁已被他人真实创建，当轮快速失败，不得向调用方泄露原始 EEXIST
+                                if (options?.createLockError) {
+                                    throw options.createLockError(`Lock '${lockPath}' is currently held by another active process`);
+                                }
+                                throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently held by another active process`);
+                            }
                         }
-                        // 在接管守卫独占保护下写入并核验元数据，杜绝外部并发读取到残余陈旧元数据
-                        token = randomUUID();
-                        metadata = {
-                            pid: process.pid,
-                            createdAt: clock.now().toISOString(),
-                            ...options?.metadata,
-                            token,
-                        };
-                        const metaPath = join(lockPath, LOCK_METADATA_FILE);
-                        const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
-                        yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-                        yield (d) => d.rename(tmpPath, metaPath);
-                        const raw = yield (d) => d.readFile(metaPath, "utf-8");
-                        const verify = JSON.parse(raw);
-                        if (verify?.token !== token) {
-                            if (options?.createLockError) {
-                                throw options.createLockError(`Failed to verify acquired lock ownership in '${lockPath}'`);
+                        if (mainLockClaimable) {
+                            // 在接管守卫独占保护下写入并核验元数据，杜绝外部并发读取到残余陈旧元数据
+                            token = randomUUID();
+                            metadata = {
+                                pid: process.pid,
+                                createdAt: clock.now().toISOString(),
+                                ...options?.metadata,
+                                token,
+                            };
+                            const metaPath = join(lockPath, LOCK_METADATA_FILE);
+                            const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
+                            yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+                            yield (d) => d.rename(tmpPath, metaPath);
+                            const raw = yield (d) => d.readFile(metaPath, "utf-8");
+                            const verify = JSON.parse(raw);
+                            if (verify?.token !== token) {
+                                if (options?.createLockError) {
+                                    throw options.createLockError(`Failed to verify acquired lock ownership in '${lockPath}'`);
+                                }
+                                throw new ActionDockError(STORAGE_BUSY, `Failed to verify acquired lock ownership in '${lockPath}'`);
                             }
-                            throw new ActionDockError(STORAGE_BUSY, `Failed to verify acquired lock ownership in '${lockPath}'`);
+                            activeLockPaths.add(resolvedPath);
+                            acquired = true;
+                            reclaimMetadataWritten = true;
                         }
-                        activeLockPaths.add(resolvedPath);
-                        acquired = true;
-                        reclaimMetadataWritten = true;
                     }
                     finally {
                         try {

package/dist/storage/index.d.ts

@@ -1,4 +1,6 @@
-import type { RuntimeStorage } from "./types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
+import { type RedactResult } from "./mask.js";
+import type { ConfigSnapshot, RuntimeStorage } from "./types.js";
 export { DataDirLock, type DataDirLockInfo, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export { NodeSqliteDriver } from "./sqlite-driver.js";
@@ -34,7 +36,7 @@ export declare function resolveDatabasePath(packageId: string, options?: {
  * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
  *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans, configDeclarations）
  */
 export declare function createStorage(packageId: string, options?: {
     projectRoot?: string;
@@ -43,6 +45,7 @@ export declare function createStorage(packageId: string, options?: {
     customHome?: string;
     recoverOrphans?: boolean;
     retentionPolicy?: import("./types.js").RunsRetentionPolicy;
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }): RuntimeStorage;
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。
@@ -70,4 +73,23 @@ export declare function createGlobalStorage(customHomeOrOptions?: string | {
     customHome?: string;
     dataDir?: string;
     inMemory?: boolean;
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }, dataDirArg?: string): RuntimeStorage;
+/**
+ * 读取配置值与配套历史保护声明的原子快照。
+ *
+ * 优先使用存储的 getConfigSnapshot 单次 SELECT 配对读取值与保护规则，
+ * 消除先读值后读保护之间行被并发删除或改写造成的错配竞态；
+ * 存储未提供快照能力（如 MemoryStorage 或外部旧实现）时回退为
+ * 原值读取加可选保护读取的既有配对行为。
+ */
+export declare function readConfigWithProtection(storage: RuntimeStorage, key: string): ConfigSnapshot | undefined;
+/**
+ * 依据当前声明与历史保护声明合并脱敏管理视图配置值。
+ *
+ * 仅在存在历史保护声明（值曾按敏感声明加密写入）时使用：当前声明与历史
+ * 保护声明合并后取脱敏并集；合并后仍未产生任何脱敏结果时保守隐藏整项，
+ * 杜绝加密值因声明变更或跨宿主加载差异重新外泄明文。
+ * 无历史保护时由调用方沿用各自既有脱敏原语，保持行为不变。
+ */
+export declare function redactConfigValueWithProtection(value: unknown, items: readonly ConfigItemDefinition[], protection: readonly ConfigItemDefinition[] | undefined): RedactResult;

package/dist/storage/index.js

@@ -1,7 +1,9 @@
 import { join, relative, resolve } from "node:path";
 import { assertValidPackageId, getActionDockHome, isPathOutsideBoundary } from "../utils/index.js";
 import { ActionDockError, PATH_TRAVERSAL } from "../errors.js";
+import { createConfigKeyProvider } from "../security/config-key.js";
 import { SqliteRuntimeStorage } from "./sqlite.js";
+import { redactConfigValueForDeclarations } from "./mask.js";
 export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export { NodeSqliteDriver } from "./sqlite-driver.js";
@@ -56,7 +58,7 @@ export function resolveDatabasePath(packageId, options = {}) {
  * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
  *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans, configDeclarations）
  */
 export function createStorage(packageId, options = {}) {
     const dbPath = resolveDatabasePath(packageId, options);
@@ -65,6 +67,17 @@ export function createStorage(packageId, options = {}) {
         packageId,
         recoverOrphans: options.recoverOrphans,
         retentionPolicy: options.retentionPolicy,
+        ...(options.configDeclarations?.length ? { configDeclarations: options.configDeclarations } : {}),
+        // 持久化库统一注入懒加载密钥提供器：密钥与数据库共享同一有效 dataDir/customHome 域；
+        // 内存库不注入，由存储内部使用随机内存密钥，确保内存运行不触碰宿主密钥源
+        ...(dbPath !== ":memory:"
+            ? {
+                configKeyProvider: createConfigKeyProvider({
+                    customHome: options.customHome,
+                    dataDir: options.dataDir,
+                }),
+            }
+            : {}),
     });
 }
 /**
@@ -94,10 +107,12 @@ export function createGlobalStorage(customHomeOrOptions, dataDirArg) {
     let customHome;
     let dataDir;
     let inMemory = false;
+    let configDeclarations;
     if (typeof customHomeOrOptions === "object" && customHomeOrOptions !== null) {
         customHome = customHomeOrOptions.customHome;
         dataDir = customHomeOrOptions.dataDir;
         inMemory = Boolean(customHomeOrOptions.inMemory);
+        configDeclarations = customHomeOrOptions.configDeclarations;
     }
     else {
         customHome = customHomeOrOptions;
@@ -107,5 +122,53 @@ export function createGlobalStorage(customHomeOrOptions, dataDirArg) {
         return new SqliteRuntimeStorage({ dbPath: ":memory:", packageId: "__global__" });
     }
     const dbPath = resolveGlobalDatabasePath({ dataDir, customHome });
-    return new SqliteRuntimeStorage({ dbPath, packageId: "__global__" });
+    return new SqliteRuntimeStorage({
+        dbPath,
+        packageId: "__global__",
+        configKeyProvider: createConfigKeyProvider({ customHome, dataDir }),
+        ...(configDeclarations?.length ? { configDeclarations } : {}),
+    });
+}
+/**
+ * 读取配置值与配套历史保护声明的原子快照。
+ *
+ * 优先使用存储的 getConfigSnapshot 单次 SELECT 配对读取值与保护规则，
+ * 消除先读值后读保护之间行被并发删除或改写造成的错配竞态；
+ * 存储未提供快照能力（如 MemoryStorage 或外部旧实现）时回退为
+ * 原值读取加可选保护读取的既有配对行为。
+ */
+export function readConfigWithProtection(storage, key) {
+    if (typeof storage.getConfigSnapshot === "function") {
+        return storage.getConfigSnapshot(key);
+    }
+    const value = storage.getConfig(key);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof storage.getConfigProtection === "function") {
+        const protection = storage.getConfigProtection(key);
+        return protection !== undefined ? { value, protection } : { value };
+    }
+    return { value };
+}
+/**
+ * 依据当前声明与历史保护声明合并脱敏管理视图配置值。
+ *
+ * 仅在存在历史保护声明（值曾按敏感声明加密写入）时使用：当前声明与历史
+ * 保护声明合并后取脱敏并集；合并后仍未产生任何脱敏结果时保守隐藏整项，
+ * 杜绝加密值因声明变更或跨宿主加载差异重新外泄明文。
+ * 无历史保护时由调用方沿用各自既有脱敏原语，保持行为不变。
+ */
+export function redactConfigValueWithProtection(value, items, protection) {
+    if (protection === undefined) {
+        return redactConfigValueForDeclarations(value, [...items]);
+    }
+    const merged = [...items, ...protection];
+    const result = redactConfigValueForDeclarations(value, merged);
+    if (!result.secret) {
+        return value === undefined
+            ? { value: undefined, secret: true, redactedPaths: [] }
+            : { value: undefined, secret: true, redactedPaths: [""] };
+    }
+    return result;
 }

package/dist/storage/migrations/index.d.ts

@@ -0,0 +1,40 @@
+import type { ConfigItemDefinition } from "../../project/types.js";
+import type { ConfigKeyProvider } from "../../security/config-cipher.js";
+import type { Clock } from "../clock.js";
+import { type SqliteDriver } from "../types.js";
+/**
+ * 版本迁移执行上下文：迁移所需的最小依赖集合。
+ *
+ * 由存储装配入口（SqliteRuntimeStorage）提供底层驱动、目标命名空间、
+ * 配置声明集合与密钥提供器；主干层只装配数据，不做任何迁移判断。
+ */
+export interface SchemaMigrationContext {
+    driver: SqliteDriver;
+    dbPath: string;
+    packageId: string;
+    declarations: readonly Record<string, ConfigItemDefinition>[];
+    keyProvider: ConfigKeyProvider;
+    clock: Clock;
+}
+/** 单个版本迁移步骤：from → to 的原子转换。 */
+export interface StorageMigration {
+    from: number;
+    to: number;
+    run(context: SchemaMigrationContext): void;
+}
+/**
+ * 存储打开前的版本就绪入口：新库建库、旧库迁移、当前库校验。
+ *
+ * 调用时机：先于任何正常子存储构造（当前版本存储实现始终假定数据库
+ * 已经是当前版本），也先于运行记录恢复（恢复依赖子存储）。
+ *
+ * - 版本等于当前：锁外只读校验核心表齐备，缺失即拒绝（半升级或损坏
+ *   状态不得静默修补）；
+ * - 其余版本（含全新库）：统一进入 BEGIN IMMEDIATE 写事务，锁内重读
+ *   版本后决策——全新库执行当前版本 DDL，旧版本沿注册链迁移并逐步更新
+ *   版本号，无支持路径（如版本 1 或未来版本）明确拒绝；
+ * - 结构完整性校验在事务内、提交前执行：任何失败（含迁移步骤与最终
+ *   校验）都会把数据、结构与版本号整体回滚，数据库保持进入前状态可重试；
+ * - 并发连接已抢先完成同一升级时，锁内版本已是当前版本，校验后直接通过。
+ */
+export declare function ensureStorageSchema(context: SchemaMigrationContext): void;

package/dist/storage/migrations/index.js

@@ -0,0 +1,96 @@
+import { ActionDockError, UNSUPPORTED_STORAGE_SCHEMA } from "../../errors.js";
+import { createCurrentSchema, validateCurrentSchema } from "../sqlite-schema.js";
+import { STORAGE_SCHEMA_VERSION } from "../types.js";
+import { migrateV2ToV3 } from "./v2-to-v3.js";
+/**
+ * 已注册的版本迁移链。
+ *
+ * 每个历史版本的全部转换逻辑封装在各自迁移文件中；下线某旧版本支持时，
+ * 删除对应迁移文件与注册项即可，当前版本读写代码不感知历史版本。
+ */
+const MIGRATIONS = [
+    { from: 2, to: 3, run: migrateV2ToV3 },
+];
+/** 读取数据库当前 schema 版本号。 */
+function readUserVersion(driver) {
+    const row = driver.prepare("PRAGMA user_version;").get();
+    return Number(row?.user_version ?? 0);
+}
+/** 构造不支持版本的统一拒绝错误。 */
+function unsupportedVersionError(version, dbPath) {
+    return new ActionDockError(UNSUPPORTED_STORAGE_SCHEMA, `Database schema version ${version} of '${dbPath}' has no supported migration path to the current version ${STORAGE_SCHEMA_VERSION}; upgrade the database first with a build that still supports version ${version}.`, { dbPath, version, current: STORAGE_SCHEMA_VERSION });
+}
+/**
+ * 沿注册链推导从 from 到当前版本的迁移步骤序列。
+ *
+ * 返回 null 表示无支持路径：from 非法（<= 0）、不低于当前版本（未来版本
+ * 一律拒绝，结构完整也不得当作当前版本打开），或链上存在缺口、注册步骤
+ * 无法精确抵达当前版本。
+ */
+function buildMigrationChain(from) {
+    if (from <= 0 || from >= STORAGE_SCHEMA_VERSION) {
+        return null;
+    }
+    const chain = [];
+    let version = from;
+    while (version < STORAGE_SCHEMA_VERSION) {
+        const step = MIGRATIONS.find((migration) => migration.from === version);
+        if (!step) {
+            return null;
+        }
+        chain.push(step);
+        version = step.to;
+    }
+    if (version !== STORAGE_SCHEMA_VERSION) {
+        return null;
+    }
+    return chain;
+}
+/**
+ * 存储打开前的版本就绪入口：新库建库、旧库迁移、当前库校验。
+ *
+ * 调用时机：先于任何正常子存储构造（当前版本存储实现始终假定数据库
+ * 已经是当前版本），也先于运行记录恢复（恢复依赖子存储）。
+ *
+ * - 版本等于当前：锁外只读校验核心表齐备，缺失即拒绝（半升级或损坏
+ *   状态不得静默修补）；
+ * - 其余版本（含全新库）：统一进入 BEGIN IMMEDIATE 写事务，锁内重读
+ *   版本后决策——全新库执行当前版本 DDL，旧版本沿注册链迁移并逐步更新
+ *   版本号，无支持路径（如版本 1 或未来版本）明确拒绝；
+ * - 结构完整性校验在事务内、提交前执行：任何失败（含迁移步骤与最终
+ *   校验）都会把数据、结构与版本号整体回滚，数据库保持进入前状态可重试；
+ * - 并发连接已抢先完成同一升级时，锁内版本已是当前版本，校验后直接通过。
+ */
+export function ensureStorageSchema(context) {
+    const { driver, dbPath } = context;
+    // 跨进程写并发基线：优先设置 busy_timeout，确保后续 PRAGMA（如
+    // journal_mode = WAL）与迁移事务在锁争用时能够重试等待
+    driver.exec("PRAGMA busy_timeout = 5000;");
+    driver.exec("PRAGMA journal_mode = WAL;");
+    driver.exec("PRAGMA synchronous = NORMAL;");
+    if (readUserVersion(driver) === STORAGE_SCHEMA_VERSION) {
+        validateCurrentSchema(driver, dbPath);
+        return;
+    }
+    driver.transaction(() => {
+        const locked = readUserVersion(driver);
+        if (locked === STORAGE_SCHEMA_VERSION) {
+            validateCurrentSchema(driver, dbPath);
+            return;
+        }
+        if (locked === 0) {
+            createCurrentSchema(driver);
+        }
+        else {
+            const chain = buildMigrationChain(locked);
+            if (chain === null) {
+                throw unsupportedVersionError(locked, dbPath);
+            }
+            for (const step of chain) {
+                step.run(context);
+                driver.exec(`PRAGMA user_version = ${step.to};`);
+            }
+        }
+        validateCurrentSchema(driver, dbPath);
+    }, "immediate");
+}

package/dist/storage/migrations/v2-to-v3.d.ts

@@ -0,0 +1,16 @@
+import type { SchemaMigrationContext } from "./index.js";
+/**
+ * V2 → V3 专用迁移：V2 数据库全部历史知识的唯一归属地。
+ *
+ * 在调用方维护事务（BEGIN IMMEDIATE）内完成：
+ * - 结构补齐：runs 表新增列（origin_json / host_session_id / host_pid /
+ *   heartbeat_at）、events 审计事件表、config_encryption 密钥元数据表；
+ * - 敏感明文转密文：按声明集合（各字典内具体键优先于模板、跨字典取并集）
+ *   判定当前命名空间的配置键，整键加密并保留业务值与 updated_at；
+ * - 密钥管理：存在待加密行时才解析并持久化密钥（提供器在迁移事务内先落盘
+ *   密钥与身份标记，再由本事务提交密文），同一事务内钉住密钥指纹。
+ *
+ * 直接操作底层 SQL，不构造也不调用当前版本存储对象：将来修改正常写入
+ * 行为不会意外改变历史迁移语义。本文件与注册项在下线 V2 支持时整体删除。
+ */
+export declare function migrateV2ToV3(context: SchemaMigrationContext): void;

package/dist/storage/migrations/v2-to-v3.js

@@ -0,0 +1,116 @@
+import { ActionDockError, CONFIG_ENCRYPTION_ERROR } from "../../errors.js";
+import { resolveConfigDeclaration } from "../../project/config-declarations.js";
+import { isEncryptedConfigValue } from "../../security/config-cipher.js";
+import { isSecretConfigKey } from "../mask.js";
+import { CONFIG_ENCRYPTION_TABLE_DDL } from "../sqlite-schema.js";
+import { encryptConfigEnvelope, mergeProtectionDeclarations } from "../config-value.js";
+import { safeParseStoredJson } from "../utils.js";
+/**
+ * V2 → V3 专用迁移：V2 数据库全部历史知识的唯一归属地。
+ *
+ * 在调用方维护事务（BEGIN IMMEDIATE）内完成：
+ * - 结构补齐：runs 表新增列（origin_json / host_session_id / host_pid /
+ *   heartbeat_at）、events 审计事件表、config_encryption 密钥元数据表；
+ * - 敏感明文转密文：按声明集合（各字典内具体键优先于模板、跨字典取并集）
+ *   判定当前命名空间的配置键，整键加密并保留业务值与 updated_at；
+ * - 密钥管理：存在待加密行时才解析并持久化密钥（提供器在迁移事务内先落盘
+ *   密钥与身份标记，再由本事务提交密文），同一事务内钉住密钥指纹。
+ *
+ * 直接操作底层 SQL，不构造也不调用当前版本存储对象：将来修改正常写入
+ * 行为不会意外改变历史迁移语义。本文件与注册项在下线 V2 支持时整体删除。
+ */
+export function migrateV2ToV3(context) {
+    upgradeRunsColumns(context.driver);
+    ensureEventsTable(context.driver);
+    context.driver.exec(CONFIG_ENCRYPTION_TABLE_DDL);
+    encryptSensitivePlaintextConfigs(context);
+}
+/** 补齐 runs 表历史新增列（旧库形态可能全部缺失）。 */
+function upgradeRunsColumns(driver) {
+    const columns = driver.prepare("PRAGMA table_info(runs);").all();
+    const present = new Set(columns.map((column) => column.name));
+    const additions = [
+        ["origin_json", "TEXT"],
+        ["host_session_id", "TEXT"],
+        ["host_pid", "INTEGER"],
+        ["heartbeat_at", "TEXT"],
+    ];
+    for (const [column, type] of additions) {
+        if (!present.has(column)) {
+            driver.exec(`ALTER TABLE runs ADD COLUMN ${column} ${type};`);
+        }
+    }
+}
+/** 补齐 events 审计事件表（V3 必备结构）。 */
+function ensureEventsTable(driver) {
+    driver.exec(`
+    CREATE TABLE IF NOT EXISTS events (
+      id TEXT PRIMARY KEY,
+      package_id TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      payload_json TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events(package_id, event_type);
+  `);
+}
+/** 解析目标键在各声明字典下的有效声明并集（各字典内具体键优先于模板）。 */
+function resolveDeclarations(declarations, key) {
+    const items = [];
+    for (const dict of declarations) {
+        const resolved = resolveConfigDeclaration(dict, key)?.item;
+        if (resolved !== undefined) {
+            items.push(resolved);
+        }
+    }
+    return items;
+}
+/**
+ * 按声明集合加密当前命名空间的敏感明文配置行。
+ *
+ * - 只处理非空明文行：普通明文与非敏感键保持原状（普通明文与密文在
+ *   当前版本内合法共存）；空串与空值行留待正常写入路径处理；
+ * - 先对全部目标行完成严格 JSON 解析，再解析密钥并钉住指纹，避免为
+ *   注定失败的迁移提前创建密钥文件；任何一步失败由调用方事务整体回滚；
+ * - 迁移只替换 value_json，业务原值与 updated_at 完整保留。
+ */
+function encryptSensitivePlaintextConfigs(context) {
+    const { driver, packageId, declarations, keyProvider, clock, dbPath } = context;
+    const rows = driver
+        .prepare("SELECT key, value_json FROM config WHERE package_id = ?")
+        .all(packageId);
+    const targets = [];
+    for (const row of rows) {
+        const raw = row.value_json;
+        if (typeof raw !== "string" || raw === "" || isEncryptedConfigValue(raw)) {
+            continue;
+        }
+        const items = resolveDeclarations(declarations, row.key);
+        if (!items.some((item) => isSecretConfigKey(row.key, item))) {
+            continue;
+        }
+        const value = safeParseStoredJson(raw, `v2-migration config db=${dbPath} package=${packageId} key=${row.key}`, { strict: true });
+        targets.push({ key: row.key, value, items });
+    }
+    if (targets.length === 0) {
+        return;
+    }
+    const material = keyProvider(true);
+    const pinned = driver
+        .prepare("SELECT key_id FROM config_encryption WHERE id = 1")
+        .get();
+    if (pinned === undefined) {
+        driver
+            .prepare("INSERT INTO config_encryption (id, key_id, created_at) VALUES (1, ?, ?)")
+            .run(material.id, clock.now().toISOString());
+    }
+    else if (pinned.key_id !== material.id) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption metadata exists with a different key identity in database '${dbPath}'`, { dbPath, pinnedKeyId: pinned.key_id });
+    }
+    const update = driver.prepare("UPDATE config SET value_json = ? WHERE package_id = ? AND key = ?");
+    for (const target of targets) {
+        const protection = mergeProtectionDeclarations([], target.items, target.key);
+        const ciphertext = encryptConfigEnvelope(target.value, protection, packageId, target.key, material);
+        update.run(ciphertext, packageId, target.key);
+    }
+}