@workflow-cannon/workspace-kit 0.15.0 → 0.16.1

package/dist/modules/task-engine/index.js

@@ -1,11 +1,11 @@
 import crypto from "node:crypto";
 import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
-import { TaskStore } from "./store.js";
 import { TransitionService } from "./service.js";
 import { TaskEngineError, getAllowedTransitionsFrom } from "./transitions.js";
 import { getNextActions } from "./suggestions.js";
 import { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
-import { WishlistStore } from "./wishlist-store.js";
+import { openPlanningStores } from "./planning-open.js";
+import { runMigrateTaskPersistence } from "./migrate-task-persistence-runtime.js";
 import { buildWishlistItemFromIntake, validateWishlistIntakePayload, validateWishlistUpdatePayload, WISHLIST_ID_RE } from "./wishlist-validation.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
@@ -14,22 +14,8 @@ export { getNextActions } from "./suggestions.js";
 export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 export { WishlistStore } from "./wishlist-store.js";
 export { validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./wishlist-validation.js";
-function taskStorePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.storeRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
-function wishlistStorePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.wishlistStoreRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
+export { openPlanningStores } from "./planning-open.js";
+export { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
 const TASK_ID_RE = /^T\d+$/;
 const MUTABLE_TASK_FIELDS = new Set([
     "title",
@@ -126,7 +112,7 @@ function mutationEvidence(mutationType, taskId, actor, details) {
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.5.0",
+        version: "0.6.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],
@@ -249,6 +235,11 @@ export const taskEngineModule = {
                     file: "get-next-actions.md",
                     description: "Get prioritized next-action suggestions with blocking analysis."
                 },
+                {
+                    name: "migrate-task-persistence",
+                    file: "migrate-task-persistence.md",
+                    description: "Copy task + wishlist state between JSON files and a single SQLite database (offline migration)."
+                },
                 {
                     name: "dashboard-summary",
                     file: "dashboard-summary.md",
@@ -259,9 +250,12 @@ export const taskEngineModule = {
     },
     async onCommand(command, ctx) {
         const args = command.args ?? {};
-        const store = new TaskStore(ctx.workspacePath, taskStorePath(ctx));
+        if (command.name === "migrate-task-persistence") {
+            return runMigrateTaskPersistence(ctx, args);
+        }
+        let planning;
         try {
-            await store.load();
+            planning = await openPlanningStores(ctx);
         }
         catch (err) {
             if (err instanceof TaskEngineError) {
@@ -270,9 +264,10 @@ export const taskEngineModule = {
             return {
                 ok: false,
                 code: "storage-read-error",
-                message: `Failed to load task store: ${err.message}`
+                message: `Failed to open task planning stores: ${err.message}`
             };
         }
+        const store = planning.taskStore;
         if (command.name === "run-transition") {
             const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
             const action = typeof args.action === "string" ? args.action : undefined;
@@ -566,14 +561,14 @@ export const taskEngineModule = {
                 phase: t.phase ?? null
             }));
             const blockedTop = suggestion.blockingAnalysis.slice(0, 15);
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
+            let wishlistItems = [];
             try {
-                await wishlistStore.load();
+                const wishlistStore = await planning.openWishlist();
+                wishlistItems = wishlistStore.getAllItems();
             }
             catch {
                 /* wishlist store optional */
             }
-            const wishlistItems = wishlistStore.getAllItems();
             const wishlistOpenCount = wishlistItems.filter((i) => i.status === "open").length;
             const data = {
                 schemaVersion: 1,
@@ -690,8 +685,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "create-wishlist") {
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const raw = args;
             const v = validateWishlistIntakePayload(raw);
             if (!v.ok) {
@@ -717,8 +711,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "list-wishlist") {
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const statusFilter = typeof args.status === "string" ? args.status : undefined;
             let items = wishlistStore.getAllItems();
             if (statusFilter && ["open", "converted", "cancelled"].includes(statusFilter)) {
@@ -740,8 +733,7 @@ export const taskEngineModule = {
             if (!wishlistId) {
                 return { ok: false, code: "invalid-task-schema", message: "get-wishlist requires 'wishlistId' or 'id'" };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const item = wishlistStore.getItem(wishlistId);
             if (!item) {
                 return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
@@ -758,8 +750,7 @@ export const taskEngineModule = {
             if (!wishlistId || !updates) {
                 return { ok: false, code: "invalid-task-schema", message: "update-wishlist requires wishlistId and updates" };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const existing = wishlistStore.getItem(wishlistId);
             if (!existing) {
                 return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
@@ -817,8 +808,7 @@ export const taskEngineModule = {
                     message: "convert-wishlist requires non-empty tasks array"
                 };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const wlItem = wishlistStore.getItem(wishlistId);
             if (!wlItem) {
                 return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
@@ -854,14 +844,6 @@ export const taskEngineModule = {
                 }
                 built.push(bt.task);
             }
-            for (const t of built) {
-                store.addTask(t);
-                store.addMutationEvidence(mutationEvidence("create-task", t.id, actor, {
-                    initialStatus: t.status,
-                    source: "convert-wishlist",
-                    wishlistId
-                }));
-            }
             const convertedIds = built.map((t) => t.id);
             const updatedWishlist = {
                 ...wlItem,
@@ -871,9 +853,25 @@ export const taskEngineModule = {
                 convertedToTaskIds: convertedIds,
                 conversionDecomposition: dec.value
             };
-            wishlistStore.updateItem(updatedWishlist);
-            await store.save();
-            await wishlistStore.save();
+            const applyConvertMutations = () => {
+                for (const t of built) {
+                    store.addTask(t);
+                    store.addMutationEvidence(mutationEvidence("create-task", t.id, actor, {
+                        initialStatus: t.status,
+                        source: "convert-wishlist",
+                        wishlistId
+                    }));
+                }
+                wishlistStore.updateItem(updatedWishlist);
+            };
+            if (planning.kind === "sqlite") {
+                planning.sqliteDual.withTransaction(applyConvertMutations);
+            }
+            else {
+                applyConvertMutations();
+                await store.save();
+                await wishlistStore.save();
+            }
             return {
                 ok: true,
                 code: "wishlist-converted",

package/dist/modules/task-engine/migrate-task-persistence-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleCommandResult, ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export declare function runMigrateTaskPersistence(ctx: ModuleLifecycleContext, args: Record<string, unknown>): Promise<ModuleCommandResult>;

package/dist/modules/task-engine/migrate-task-persistence-runtime.js

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { TaskEngineError } from "./transitions.js";
+import { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+import { planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
+import { DEFAULT_TASK_STORE_PATH } from "./store.js";
+import { DEFAULT_WISHLIST_PATH } from "./wishlist-store.js";
+function emptyTaskDoc() {
+    return {
+        schemaVersion: 1,
+        tasks: [],
+        transitionLog: [],
+        mutationLog: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+function emptyWishDoc() {
+    return {
+        schemaVersion: 1,
+        items: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+async function atomicWriteJson(targetPath, body) {
+    const dir = path.dirname(targetPath);
+    const tmpPath = `${targetPath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmpPath, body, "utf8");
+    await fs.rename(tmpPath, targetPath);
+}
+export async function runMigrateTaskPersistence(ctx, args) {
+    const direction = typeof args.direction === "string" ? args.direction.trim() : "";
+    if (direction !== "json-to-sqlite" && direction !== "sqlite-to-json") {
+        return {
+            ok: false,
+            code: "invalid-task-schema",
+            message: "migrate-task-persistence requires direction: 'json-to-sqlite' | 'sqlite-to-json'"
+        };
+    }
+    const dryRun = args.dryRun === true;
+    const force = args.force === true;
+    const taskRel = planningTaskStoreRelativePath(ctx) ?? DEFAULT_TASK_STORE_PATH;
+    const wishRel = planningWishlistStoreRelativePath(ctx) ?? DEFAULT_WISHLIST_PATH;
+    const taskPath = path.resolve(ctx.workspacePath, taskRel);
+    const wishPath = path.resolve(ctx.workspacePath, wishRel);
+    const dbRel = planningSqliteDatabaseRelativePath(ctx);
+    const dual = new SqliteDualPlanningStore(ctx.workspacePath, dbRel);
+    if (direction === "json-to-sqlite") {
+        if (fsSync.existsSync(dual.dbPath) && !force) {
+            return {
+                ok: false,
+                code: "storage-write-error",
+                message: `SQLite database already exists at ${dual.dbPath} (pass force:true to overwrite)`
+            };
+        }
+        let taskDoc = emptyTaskDoc();
+        try {
+            const raw = await fs.readFile(taskPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.schemaVersion !== 1) {
+                throw new TaskEngineError("import-parse-error", `Unsupported task schema ${parsed.schemaVersion}`);
+            }
+            if (!Array.isArray(parsed.mutationLog)) {
+                parsed.mutationLog = [];
+            }
+            taskDoc = parsed;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                taskDoc = emptyTaskDoc();
+            }
+            else if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: `Failed to read task JSON: ${err.message}`
+                };
+            }
+        }
+        let wishDoc = emptyWishDoc();
+        try {
+            const raw = await fs.readFile(wishPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.schemaVersion !== 1) {
+                throw new TaskEngineError("import-parse-error", `Unsupported wishlist schema ${parsed.schemaVersion}`);
+            }
+            if (!Array.isArray(parsed.items)) {
+                throw new TaskEngineError("import-parse-error", "Wishlist items must be an array");
+            }
+            wishDoc = parsed;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                wishDoc = emptyWishDoc();
+            }
+            else if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: `Failed to read wishlist JSON: ${err.message}`
+                };
+            }
+        }
+        if (dryRun) {
+            return {
+                ok: true,
+                code: "migrate-dry-run",
+                message: "Dry run: would import JSON task/wishlist documents into SQLite",
+                data: {
+                    dbPath: dual.dbPath,
+                    taskPath,
+                    wishPath,
+                    taskCount: taskDoc.tasks.length,
+                    wishlistCount: wishDoc.items.length
+                }
+            };
+        }
+        dual.seedFromDocuments(taskDoc, wishDoc);
+        try {
+            dual.persistSync();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: "storage-write-error",
+                message: `Failed to write SQLite database: ${err.message}`
+            };
+        }
+        return {
+            ok: true,
+            code: "migrated-json-to-sqlite",
+            message: `Imported task and wishlist JSON into ${dual.dbPath}`,
+            data: { dbPath: dual.dbPath, taskPath, wishPath }
+        };
+    }
+    // sqlite-to-json
+    if (!fsSync.existsSync(dual.dbPath)) {
+        return {
+            ok: false,
+            code: "storage-read-error",
+            message: `SQLite database not found at ${dual.dbPath}`
+        };
+    }
+    dual.loadFromDisk();
+    if (!force && (fsSync.existsSync(taskPath) || fsSync.existsSync(wishPath))) {
+        return {
+            ok: false,
+            code: "storage-write-error",
+            message: `Target JSON path already exists (task or wishlist); pass force:true to overwrite`,
+            data: { taskPath, wishPath }
+        };
+    }
+    if (dryRun) {
+        return {
+            ok: true,
+            code: "migrate-dry-run",
+            message: "Dry run: would export SQLite documents to JSON files",
+            data: {
+                dbPath: dual.dbPath,
+                taskPath,
+                wishPath,
+                taskCount: dual.taskDocument.tasks.length,
+                wishlistCount: dual.wishlistDocument.items.length
+            }
+        };
+    }
+    try {
+        await atomicWriteJson(taskPath, JSON.stringify(dual.taskDocument, null, 2) + "\n");
+        await atomicWriteJson(wishPath, JSON.stringify(dual.wishlistDocument, null, 2) + "\n");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: "storage-write-error",
+            message: `Failed to write JSON export: ${err.message}`
+        };
+    }
+    return {
+        ok: true,
+        code: "migrated-sqlite-to-json",
+        message: `Exported SQLite planning state to ${taskPath} and ${wishPath}`,
+        data: { dbPath: dual.dbPath, taskPath, wishPath }
+    };
+}

package/dist/modules/task-engine/planning-config.d.ts

@@ -0,0 +1,10 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export type TaskPersistenceBackend = "json" | "sqlite";
+export declare function getTaskPersistenceBackend(config: Record<string, unknown> | undefined): TaskPersistenceBackend;
+export declare function planningTaskStoreRelativePath(ctx: {
+    effectiveConfig?: Record<string, unknown>;
+}): string | undefined;
+export declare function planningWishlistStoreRelativePath(ctx: {
+    effectiveConfig?: Record<string, unknown>;
+}): string | undefined;
+export declare function planningSqliteDatabaseRelativePath(ctx: ModuleLifecycleContext): string;

package/dist/modules/task-engine/planning-config.js

@@ -0,0 +1,37 @@
+export function getTaskPersistenceBackend(config) {
+    const tasks = config?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return "json";
+    }
+    const b = tasks.persistenceBackend;
+    if (b === "sqlite") {
+        return "sqlite";
+    }
+    return "json";
+}
+export function planningTaskStoreRelativePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.storeRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
+export function planningWishlistStoreRelativePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.wishlistStoreRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
+export function planningSqliteDatabaseRelativePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return ".workspace-kit/tasks/workspace-kit.db";
+    }
+    const p = tasks.sqliteDatabaseRelativePath;
+    return typeof p === "string" && p.trim().length > 0
+        ? p.trim()
+        : ".workspace-kit/tasks/workspace-kit.db";
+}

package/dist/modules/task-engine/planning-open.d.ts

@@ -0,0 +1,16 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+import { TaskStore } from "./store.js";
+import { WishlistStore } from "./wishlist-store.js";
+import { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+export type OpenedPlanningStores = {
+    kind: "json";
+    taskStore: TaskStore;
+    sqliteDual: null;
+    openWishlist: () => Promise<WishlistStore>;
+} | {
+    kind: "sqlite";
+    taskStore: TaskStore;
+    sqliteDual: SqliteDualPlanningStore;
+    openWishlist: () => Promise<WishlistStore>;
+};
+export declare function openPlanningStores(ctx: ModuleLifecycleContext): Promise<OpenedPlanningStores>;

package/dist/modules/task-engine/planning-open.js

@@ -0,0 +1,34 @@
+import { TaskStore } from "./store.js";
+import { WishlistStore } from "./wishlist-store.js";
+import { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+import { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
+export async function openPlanningStores(ctx) {
+    if (getTaskPersistenceBackend(ctx.effectiveConfig) === "sqlite") {
+        const dual = new SqliteDualPlanningStore(ctx.workspacePath, planningSqliteDatabaseRelativePath(ctx));
+        dual.loadFromDisk();
+        const taskStore = TaskStore.forSqliteDual(dual);
+        await taskStore.load(); // binds task document reference from dual
+        return {
+            kind: "sqlite",
+            sqliteDual: dual,
+            taskStore,
+            openWishlist: async () => {
+                const w = WishlistStore.forSqliteDual(dual);
+                await w.load();
+                return w;
+            }
+        };
+    }
+    const taskStore = TaskStore.forJsonFile(ctx.workspacePath, planningTaskStoreRelativePath(ctx));
+    await taskStore.load();
+    return {
+        kind: "json",
+        sqliteDual: null,
+        taskStore,
+        openWishlist: async () => {
+            const w = WishlistStore.forJsonFile(ctx.workspacePath, planningWishlistStoreRelativePath(ctx));
+            await w.load();
+            return w;
+        }
+    };
+}

package/dist/modules/task-engine/sqlite-dual-planning.d.ts

@@ -0,0 +1,21 @@
+import type { TaskStoreDocument } from "./types.js";
+import type { WishlistStoreDocument } from "./wishlist-types.js";
+/** Single-file SQLite backing for task + wishlist JSON documents (atomic convert-wishlist). */
+export declare class SqliteDualPlanningStore {
+    private db;
+    readonly dbPath: string;
+    private _taskDoc;
+    private _wishlistDoc;
+    constructor(workspacePath: string, databaseRelativePath: string);
+    get taskDocument(): TaskStoreDocument;
+    get wishlistDocument(): WishlistStoreDocument;
+    getDisplayPath(): string;
+    private ensureDb;
+    /** Load documents from an existing database file; otherwise start empty (no file created). */
+    loadFromDisk(): void;
+    /** Replace in-memory documents (used by migrate). */
+    seedFromDocuments(taskDoc: TaskStoreDocument, wishlistDoc: WishlistStoreDocument): void;
+    persistSync(): void;
+    /** Run synchronous work inside one SQLite transaction and flush both blobs at the end. */
+    withTransaction(work: () => void): void;
+}

package/dist/modules/task-engine/sqlite-dual-planning.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { TaskEngineError } from "./transitions.js";
+const DDL = `
+CREATE TABLE IF NOT EXISTS workspace_planning_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  task_store_json TEXT NOT NULL,
+  wishlist_store_json TEXT NOT NULL
+);
+`;
+function emptyTaskStoreDocument() {
+    return {
+        schemaVersion: 1,
+        tasks: [],
+        transitionLog: [],
+        mutationLog: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+function emptyWishlistDocument() {
+    return {
+        schemaVersion: 1,
+        items: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+/** Single-file SQLite backing for task + wishlist JSON documents (atomic convert-wishlist). */
+export class SqliteDualPlanningStore {
+    db = null;
+    dbPath;
+    _taskDoc;
+    _wishlistDoc;
+    constructor(workspacePath, databaseRelativePath) {
+        this.dbPath = path.resolve(workspacePath, databaseRelativePath);
+        this._taskDoc = emptyTaskStoreDocument();
+        this._wishlistDoc = emptyWishlistDocument();
+    }
+    get taskDocument() {
+        return this._taskDoc;
+    }
+    get wishlistDocument() {
+        return this._wishlistDoc;
+    }
+    getDisplayPath() {
+        return this.dbPath;
+    }
+    ensureDb() {
+        if (!this.db) {
+            const dir = path.dirname(this.dbPath);
+            fs.mkdirSync(dir, { recursive: true });
+            this.db = new Database(this.dbPath);
+            this.db.pragma("journal_mode = WAL");
+            this.db.exec(DDL);
+        }
+        return this.db;
+    }
+    /** Load documents from an existing database file; otherwise start empty (no file created). */
+    loadFromDisk() {
+        if (!fs.existsSync(this.dbPath)) {
+            this._taskDoc = emptyTaskStoreDocument();
+            this._wishlistDoc = emptyWishlistDocument();
+            return;
+        }
+        const db = this.ensureDb();
+        const row = db
+            .prepare("SELECT task_store_json, wishlist_store_json FROM workspace_planning_state WHERE id = 1")
+            .get();
+        if (!row) {
+            this._taskDoc = emptyTaskStoreDocument();
+            this._wishlistDoc = emptyWishlistDocument();
+            return;
+        }
+        try {
+            const taskParsed = JSON.parse(row.task_store_json);
+            const wishParsed = JSON.parse(row.wishlist_store_json);
+            if (taskParsed.schemaVersion !== 1) {
+                throw new TaskEngineError("storage-read-error", `Unsupported task store schema in SQLite: ${taskParsed.schemaVersion}`);
+            }
+            if (wishParsed.schemaVersion !== 1) {
+                throw new TaskEngineError("storage-read-error", `Unsupported wishlist schema in SQLite: ${wishParsed.schemaVersion}`);
+            }
+            if (!Array.isArray(taskParsed.mutationLog)) {
+                taskParsed.mutationLog = [];
+            }
+            if (!Array.isArray(wishParsed.items)) {
+                throw new TaskEngineError("storage-read-error", "Wishlist items missing in SQLite row");
+            }
+            this._taskDoc = taskParsed;
+            this._wishlistDoc = wishParsed;
+        }
+        catch (err) {
+            if (err instanceof TaskEngineError) {
+                throw err;
+            }
+            throw new TaskEngineError("storage-read-error", `Failed to parse SQLite planning row: ${err.message}`);
+        }
+    }
+    /** Replace in-memory documents (used by migrate). */
+    seedFromDocuments(taskDoc, wishlistDoc) {
+        this._taskDoc = taskDoc;
+        this._wishlistDoc = wishlistDoc;
+    }
+    persistSync() {
+        this._taskDoc.lastUpdated = new Date().toISOString();
+        this._wishlistDoc.lastUpdated = new Date().toISOString();
+        const db = this.ensureDb();
+        const t = JSON.stringify(this._taskDoc);
+        const w = JSON.stringify(this._wishlistDoc);
+        const exists = db.prepare("SELECT 1 AS ok FROM workspace_planning_state WHERE id = 1").get();
+        if (exists) {
+            db.prepare("UPDATE workspace_planning_state SET task_store_json = ?, wishlist_store_json = ? WHERE id = 1").run(t, w);
+        }
+        else {
+            db.prepare("INSERT INTO workspace_planning_state (id, task_store_json, wishlist_store_json) VALUES (1, ?, ?)").run(t, w);
+        }
+    }
+    /** Run synchronous work inside one SQLite transaction and flush both blobs at the end. */
+    withTransaction(work) {
+        const db = this.ensureDb();
+        const txn = db.transaction(() => {
+            work();
+            this._taskDoc.lastUpdated = new Date().toISOString();
+            this._wishlistDoc.lastUpdated = new Date().toISOString();
+            const t = JSON.stringify(this._taskDoc);
+            const w = JSON.stringify(this._wishlistDoc);
+            const exists = db.prepare("SELECT 1 AS ok FROM workspace_planning_state WHERE id = 1").get();
+            if (exists) {
+                db.prepare("UPDATE workspace_planning_state SET task_store_json = ?, wishlist_store_json = ? WHERE id = 1").run(t, w);
+            }
+            else {
+                db.prepare("INSERT INTO workspace_planning_state (id, task_store_json, wishlist_store_json) VALUES (1, ?, ?)").run(t, w);
+            }
+        });
+        txn();
+    }
+}

package/dist/modules/task-engine/store.d.ts

@@ -1,8 +1,17 @@
-import type { TaskEntity, TaskMutationEvidence, TransitionEvidence } from "./types.js";
+import type { TaskEntity, TaskMutationEvidence, TaskStoreDocument, TransitionEvidence } from "./types.js";
+import type { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+export declare const DEFAULT_TASK_STORE_PATH = ".workspace-kit/tasks/state.json";
+export type TaskStorePersistence = {
+    loadDocument: () => Promise<TaskStoreDocument>;
+    saveDocument: (doc: TaskStoreDocument) => Promise<void>;
+    pathLabel: string;
+};
 export declare class TaskStore {
     private document;
-    private readonly filePath;
-    constructor(workspacePath: string, storePath?: string);
+    private readonly persistence;
+    constructor(persistence: TaskStorePersistence);
+    static forJsonFile(workspacePath: string, storeRelativePath?: string): TaskStore;
+    static forSqliteDual(dual: SqliteDualPlanningStore): TaskStore;
     load(): Promise<void>;
     save(): Promise<void>;
     getAllTasks(): TaskEntity[];