@lsctech/polaris 0.1.0

package/dist/tracker/schema.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executionGraphV1Schema = exports.executionGraphV2Schema = void 0;
+const zod_1 = require("zod");
+/**
+ * The full v2 execution graph schema.
+ * Use this for validation when loading a graph from disk.
+ */
+exports.executionGraphV2Schema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal("v2"),
+    /** Source of truth metadata for the execution cluster. */
+    source: zod_1.z.object({
+        id: zod_1.z.string(),
+        type: zod_1.z.string(),
+        analysis: zod_1.z
+            .object({
+            id: zod_1.z.string(),
+            doc: zod_1.z.string().nullable().optional(),
+        })
+            .optional(),
+    }),
+    /** Normalized map of all nodes (issues) in the graph. */
+    nodes: zod_1.z.record(zod_1.z.object({
+        id: zod_1.z.string(),
+        title: zod_1.z.string(),
+        status: zod_1.z.string(),
+        sessionType: zod_1.z.string().optional(),
+        /** Markdown body / description of the issue. */
+        body: zod_1.z.string().optional(),
+    })),
+    /** Dependency map. Key is the node ID, value is an array of node IDs it is blocked by. */
+    dependencies: zod_1.z.record(zod_1.z.array(zod_1.z.string())),
+    /**
+     * Clusters are ordered groups of nodes.
+     * This is the primary execution structure.
+     */
+    clusters: zod_1.z.record(zod_1.z.object({
+        id: zod_1.z.string(),
+        title: zod_1.z.string(),
+        /**
+         * Runnable children only — issue IDs to be dispatched to workers.
+         * Does not include the cluster root or context/reference nodes.
+         * When the cluster root itself is the only work item (leaf cluster),
+         * it appears here and also as cluster_root.
+         */
+        children: zod_1.z.array(zod_1.z.string()),
+        /**
+         * The issue that was passed as the target to `polaris run`.
+         * This is a context/coordination node. It must not be dispatched
+         * as a worker child unless it is also the only entry in children
+         * (leaf cluster with no implementation sub-issues).
+         */
+        cluster_root: zod_1.z.string().optional(),
+    })),
+    /** The active cluster ID to be used for execution. */
+    activeCluster: zod_1.z.string(),
+}).superRefine((data, ctx) => {
+    if (data.activeCluster && !data.clusters[data.activeCluster]) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ["activeCluster"],
+            message: `activeCluster '${data.activeCluster}' does not exist in the clusters map`,
+        });
+    }
+});
+/**
+ * The v1 `clusters.json` schema.
+ * This is used for migration purposes.
+ */
+exports.executionGraphV1Schema = zod_1.z.object({
+    source_id: zod_1.z.string(),
+    analyze_source_id: zod_1.z.string().optional(),
+    source_type: zod_1.z.string(),
+    created_at: zod_1.z.string(),
+    analysis_doc: zod_1.z.string().nullable().optional(),
+    clusters: zod_1.z.array(zod_1.z.object({
+        cluster_id: zod_1.z.string(),
+        description: zod_1.z.string(),
+        children: zod_1.z.array(zod_1.z.object({
+            id: zod_1.z.string(),
+            title: zod_1.z.string(),
+            session_type: zod_1.z.string(),
+            blockedBy: zod_1.z.array(zod_1.z.string()),
+        })),
+    })),
+});

package/dist/tracker/sync/index.js

@@ -0,0 +1,404 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrackerSyncService = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const store_js_1 = require("../../cluster-state/store.js");
+const queue_store_js_1 = require("./queue-store.js");
+const lifecycle_policy_js_1 = require("../lifecycle-policy.js");
+class TrackerSyncService {
+    adapter;
+    mutationQueue = [];
+    localGraphRef;
+    repoRoot;
+    clusterId;
+    queueFilePath;
+    lifecyclePolicy;
+    ready;
+    constructor(adapter, localGraph, options = {}) {
+        this.adapter = adapter;
+        this.localGraphRef = localGraph;
+        this.repoRoot = options.repoRoot ?? process.cwd();
+        this.clusterId = options.clusterId;
+        this.queueFilePath = options.queueFilePath ?? node_path_1.default.join(this.repoRoot, ".taskchain_artifacts", "polaris-run", "mutation-queue.json");
+        this.lifecyclePolicy = options.lifecyclePolicy;
+        this.ready = this.loadQueue();
+    }
+    async loadQueue() {
+        this.mutationQueue = await (0, queue_store_js_1.loadMutationQueue)(this.queueFilePath);
+        console.log(`Loaded ${this.mutationQueue.length} mutations from queue store.`);
+    }
+    async saveQueue() {
+        await (0, queue_store_js_1.saveMutationQueue)(this.mutationQueue, this.queueFilePath);
+        console.log(`Saved ${this.mutationQueue.length} mutations to queue store.`);
+    }
+    async syncIn(input) {
+        console.log(`Starting sync-in for tracker: ${input.trackerId}`);
+        const fetchedData = await this.adapter.fetchData(input);
+        let syncedInCount = 0;
+        if (Array.isArray(fetchedData) && fetchedData.length > 0) {
+            syncedInCount = fetchedData.length;
+            console.log(`Synced in ${syncedInCount} items.`);
+        }
+        return {
+            syncedInCount,
+            mutationsQueuedCount: this.mutationQueue.length,
+            mutationsAppliedCount: 0,
+            conflictsDetectedCount: 0,
+            failedMutationsCount: 0,
+            details: [`Sync-in completed. ${syncedInCount} items processed.`],
+        };
+    }
+    async addMutation(mutation) {
+        await this.ready;
+        const newMutation = {
+            ...mutation,
+            id: (0, node_crypto_1.randomUUID)(),
+            status: 'pending',
+            timestamp: new Date().toISOString(),
+            retries: 0,
+        };
+        this.mutationQueue.push(newMutation);
+        await this.saveQueue();
+        console.log(`Mutation added to queue: ${newMutation.id}`);
+    }
+    async reconcile(dryRun = false) {
+        await this.ready;
+        console.log(`Starting reconciliation (dryRun: ${dryRun})`);
+        const prepared = await this.prepareValidatedQueue(dryRun);
+        let mutationsAppliedCount = 0;
+        let conflictsDetectedCount = 0;
+        let failedMutationsCount = prepared.failureCount;
+        const details = [...prepared.details];
+        const mutationsToProcess = this.mutationQueue.filter((mutation) => mutation.status === 'pending' || mutation.status === 'failed');
+        for (const mutation of mutationsToProcess) {
+            if (dryRun) {
+                details.push(`Dry run: Would apply mutation ${mutation.id} (${mutation.type} ${mutation.entityType}:${mutation.entityId})`);
+                continue;
+            }
+            try {
+                const localEntity = this.localGraphRef.getNode(mutation.entityId);
+                if (localEntity) {
+                    const remoteEntity = await this.adapter.fetchData({ trackerId: mutation.entityId });
+                    if (remoteEntity && this.adapter.detectConflict(localEntity, remoteEntity)) {
+                        mutation.status = 'conflicted';
+                        conflictsDetectedCount++;
+                        mutation.error = 'Remote tracker entity changed since local validation.';
+                        await this.syncClusterMutationStatus(mutation, 'conflicted', mutation.error);
+                        details.push(`Conflict detected for mutation ${mutation.id}. Remote entity changed.`);
+                        continue;
+                    }
+                }
+                mutation.status = 'sent';
+                await this.syncClusterMutationStatus(mutation, 'sent');
+                const updatedMutation = await this.adapter.applyMutation(mutation);
+                Object.assign(mutation, updatedMutation);
+                if (updatedMutation.status === 'succeeded') {
+                    mutationsAppliedCount++;
+                    await this.syncClusterMutationStatus(mutation, 'succeeded');
+                    details.push(`Successfully applied mutation ${mutation.id}`);
+                }
+                else {
+                    mutation.status = updatedMutation.status === 'conflicted' ? 'conflicted' : 'failed';
+                    mutation.error = updatedMutation.error;
+                    failedMutationsCount++;
+                    await this.syncClusterMutationStatus(mutation, mutation.status, mutation.error);
+                    details.push(`Failed to apply mutation ${mutation.id}: ${mutation.error ?? 'Unknown error'}`);
+                }
+            }
+            catch (error) {
+                mutation.retries += 1;
+                mutation.error = error instanceof Error ? error.message : String(error);
+                mutation.status = 'failed';
+                failedMutationsCount++;
+                await this.syncClusterMutationStatus(mutation, 'failed', mutation.error);
+                details.push(`Error applying mutation ${mutation.id} (retry ${mutation.retries}): ${mutation.error}`);
+            }
+        }
+        await this.saveQueue();
+        const report = {
+            syncedInCount: 0,
+            mutationsQueuedCount: this.mutationQueue.filter((mutation) => mutation.status === 'pending' || mutation.status === 'failed').length,
+            mutationsAppliedCount,
+            conflictsDetectedCount,
+            failedMutationsCount,
+            details,
+        };
+        console.log(`Reconciliation completed. Applied: ${mutationsAppliedCount}, Conflicts: ${conflictsDetectedCount}, Failed: ${failedMutationsCount}`);
+        return report;
+    }
+    getMutationQueue() {
+        return this.mutationQueue;
+    }
+    async prepareValidatedQueue(dryRun) {
+        if (!this.clusterId) {
+            return { preparedCount: 0, failureCount: 0, details: [] };
+        }
+        const clusterState = await (0, store_js_1.readClusterState)(this.clusterId, this.repoRoot);
+        if (!clusterState) {
+            return {
+                preparedCount: 0,
+                failureCount: 1,
+                details: [`Cluster state for ${this.clusterId} is missing; cannot prepare tracker reconciliation.`],
+            };
+        }
+        const nextQueue = [...this.mutationQueue];
+        const trackerMutations = { ...(clusterState.tracker_mutations ?? {}) };
+        const preparedDetails = [];
+        let preparedCount = 0;
+        let failureCount = 0;
+        let changed = false;
+        const sourceGeneration = clusterState.state_generation;
+        for (const childState of clusterState.child_states) {
+            if (childState.status !== 'done') {
+                continue;
+            }
+            const existingRef = trackerMutations[childState.id];
+            if (existingRef?.status === 'succeeded') {
+                continue;
+            }
+            const evidence = await this.validateCompletionEvidence(clusterState, childState.id);
+            if (!evidence.valid) {
+                failureCount += 1;
+                preparedDetails.push(`Skipped ${childState.id}: ${evidence.reason}`);
+                const blockedRef = this.buildTrackerReference({
+                    existing: existingRef,
+                    childId: childState.id,
+                    idempotencyKey: existingRef?.idempotency_key ?? `blocked:${childState.id}`,
+                    mutationIds: existingRef?.mutation_ids ?? [],
+                    status: 'blocked',
+                    resultFile: clusterState.result_pointers[childState.id] ?? '',
+                    packetFile: clusterState.packet_pointers[childState.id],
+                    commit: clusterState.commits[childState.id],
+                    sourceStateGeneration: sourceGeneration,
+                    error: evidence.reason,
+                });
+                if (!this.sameTrackerReference(existingRef, blockedRef)) {
+                    trackerMutations[childState.id] = blockedRef;
+                    changed = true;
+                }
+                continue;
+            }
+            const idempotencyKey = this.buildIdempotencyKey(evidence.value);
+            const existingQueueMutation = nextQueue.find((mutation) => mutation.operationId === idempotencyKey);
+            if (existingRef?.idempotency_key === idempotencyKey && existingQueueMutation) {
+                trackerMutations[childState.id] = this.buildTrackerReference({
+                    existing: existingRef,
+                    childId: childState.id,
+                    idempotencyKey,
+                    mutationIds: [existingQueueMutation.id],
+                    status: this.normalizeMutationStatus(existingQueueMutation.status),
+                    resultFile: evidence.value.resultFile,
+                    packetFile: evidence.value.packetFile,
+                    commit: evidence.value.commit,
+                    sourceStateGeneration: evidence.value.sourceStateGeneration,
+                    error: existingQueueMutation.error,
+                });
+                continue;
+            }
+            let queuedMutation = existingQueueMutation;
+            if (!queuedMutation) {
+                // Resolve the lifecycle state from policy for validation-passed children
+                const lifecycleTransition = (0, lifecycle_policy_js_1.resolveLifecycleTransition)("child-validation-passed", this.lifecyclePolicy);
+                // Skip creating a mutation if the policy says to skip or target is no_status_change
+                if (lifecycleTransition.skip || lifecycleTransition.targetState === "no_status_change") {
+                    continue;
+                }
+                const targetState = lifecycleTransition.targetState;
+                const newMutation = {
+                    id: (0, node_crypto_1.randomUUID)(),
+                    operationId: idempotencyKey,
+                    type: "update",
+                    entityType: "issue",
+                    entityId: childState.id,
+                    payload: {
+                        state: targetState,
+                    },
+                    status: "pending",
+                    timestamp: new Date().toISOString(),
+                    retries: 0,
+                    evidence: {
+                        ...evidence.value,
+                        clusterId: this.clusterId,
+                        childId: childState.id,
+                    },
+                };
+                nextQueue.push(newMutation);
+                queuedMutation = newMutation;
+                preparedCount += 1;
+                changed = true;
+                preparedDetails.push(`Queued validated tracker mutation for ${childState.id} (target state: ${targetState}).`);
+            }
+            if (!queuedMutation) {
+                continue;
+            }
+            const pendingRef = this.buildTrackerReference({
+                existing: existingRef,
+                childId: childState.id,
+                idempotencyKey,
+                mutationIds: [queuedMutation.id],
+                status: this.normalizeMutationStatus(queuedMutation.status),
+                resultFile: evidence.value.resultFile,
+                packetFile: evidence.value.packetFile,
+                commit: evidence.value.commit,
+                sourceStateGeneration: evidence.value.sourceStateGeneration,
+                error: queuedMutation.error,
+            });
+            if (!this.sameTrackerReference(existingRef, pendingRef)) {
+                trackerMutations[childState.id] = pendingRef;
+                changed = true;
+            }
+        }
+        if (!dryRun && changed) {
+            this.mutationQueue = nextQueue;
+            await this.saveQueue();
+            await (0, store_js_1.writeClusterState)(this.clusterId, {
+                ...clusterState,
+                state_generation: clusterState.state_generation + 1,
+                tracker_mutations: trackerMutations,
+            }, this.repoRoot);
+        }
+        return { preparedCount, failureCount, details: preparedDetails };
+    }
+    async validateCompletionEvidence(clusterState, childId) {
+        const packetFile = clusterState.packet_pointers[childId];
+        if (!packetFile) {
+            return { valid: false, reason: 'missing packet pointer' };
+        }
+        const resultFile = clusterState.result_pointers[childId];
+        if (!resultFile) {
+            return { valid: false, reason: 'missing sealed result pointer' };
+        }
+        const validation = clusterState.validation_results[childId];
+        if (!validation?.passed) {
+            return { valid: false, reason: 'validation result is missing or failed' };
+        }
+        const commit = clusterState.commits[childId];
+        if (!commit) {
+            return { valid: false, reason: 'missing commit evidence' };
+        }
+        let packet;
+        let result;
+        try {
+            packet = JSON.parse(await (0, promises_1.readFile)(packetFile, 'utf-8'));
+        }
+        catch (error) {
+            return {
+                valid: false,
+                reason: `unable to read packet file (${error instanceof Error ? error.message : String(error)})`,
+            };
+        }
+        try {
+            result = JSON.parse(await (0, promises_1.readFile)(resultFile, 'utf-8'));
+        }
+        catch (error) {
+            return {
+                valid: false,
+                reason: `unable to read result file (${error instanceof Error ? error.message : String(error)})`,
+            };
+        }
+        if (packet.cluster_id !== this.clusterId || packet.active_child !== childId || !packet.run_id) {
+            return { valid: false, reason: 'packet metadata does not match the active cluster child' };
+        }
+        if (result.run_id !== packet.run_id || result.child_id !== childId) {
+            return { valid: false, reason: 'sealed result does not match packet run/child identifiers' };
+        }
+        if (result.status !== 'success') {
+            return { valid: false, reason: `sealed result status is ${result.status ?? 'missing'}` };
+        }
+        if (!result.commit || result.commit !== commit) {
+            return { valid: false, reason: 'sealed result commit does not match cluster-state commit evidence' };
+        }
+        return {
+            valid: true,
+            value: {
+                runId: packet.run_id,
+                packetFile,
+                resultFile,
+                commit,
+                sourceStateGeneration: clusterState.state_generation,
+                validatedAt: new Date().toISOString(),
+            },
+        };
+    }
+    buildIdempotencyKey(evidence) {
+        return (0, node_crypto_1.createHash)('sha256')
+            .update([
+            this.clusterId ?? '',
+            evidence.runId,
+            evidence.resultFile,
+            evidence.commit,
+        ].join(':'))
+            .digest('hex');
+    }
+    async syncClusterMutationStatus(mutation, status, error) {
+        if (!this.clusterId || !mutation.evidence) {
+            return;
+        }
+        const clusterState = await (0, store_js_1.readClusterState)(this.clusterId, this.repoRoot);
+        if (!clusterState) {
+            return;
+        }
+        const existing = clusterState.tracker_mutations[mutation.entityId];
+        const next = this.buildTrackerReference({
+            existing,
+            childId: mutation.entityId,
+            idempotencyKey: mutation.operationId,
+            mutationIds: [mutation.id],
+            status,
+            resultFile: mutation.evidence.resultFile,
+            packetFile: mutation.evidence.packetFile,
+            commit: mutation.evidence.commit,
+            sourceStateGeneration: mutation.evidence.sourceStateGeneration,
+            error,
+            attemptedAt: new Date().toISOString(),
+        });
+        if (this.sameTrackerReference(existing, next)) {
+            return;
+        }
+        await (0, store_js_1.writeClusterState)(this.clusterId, {
+            ...clusterState,
+            state_generation: clusterState.state_generation + 1,
+            tracker_mutations: {
+                ...clusterState.tracker_mutations,
+                [mutation.entityId]: next,
+            },
+        }, this.repoRoot);
+    }
+    buildTrackerReference(input) {
+        const updatedAt = new Date().toISOString();
+        return {
+            mutation_ids: input.mutationIds,
+            idempotency_key: input.idempotencyKey,
+            source_state_generation: input.sourceStateGeneration,
+            result_file: input.resultFile,
+            packet_file: input.packetFile,
+            commit: input.commit,
+            status: input.status,
+            updated_at: updatedAt,
+            last_attempted_at: input.attemptedAt ?? input.existing?.last_attempted_at,
+            last_error: input.error,
+        };
+    }
+    normalizeMutationStatus(status) {
+        if (status === 'sent') {
+            return 'sent';
+        }
+        return status;
+    }
+    sameTrackerReference(left, right) {
+        if (!left) {
+            return false;
+        }
+        const normalize = (value) => ({
+            ...value,
+            updated_at: undefined,
+        });
+        return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+    }
+}
+exports.TrackerSyncService = TrackerSyncService;

package/dist/tracker/sync/queue-store.js

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadMutationQueue = loadMutationQueue;
+exports.saveMutationQueue = saveMutationQueue;
+const promises_1 = require("node:fs/promises");
+const path = __importStar(require("node:path"));
+/**
+ * Loads the mutation queue from a JSON file.
+ * If the file does not exist, an empty array is returned.
+ * @param filePath The path to the mutation queue JSON file. Defaults to .taskchain_artifacts/polaris-run/mutation-queue.json.
+ * @returns A promise that resolves to an array of MutationRecord.
+ */
+async function loadMutationQueue(filePath = path.join(process.cwd(), '.taskchain_artifacts', 'polaris-run', 'mutation-queue.json')) {
+    try {
+        await (0, promises_1.mkdir)(path.dirname(filePath), { recursive: true });
+        const fileContent = await (0, promises_1.readFile)(filePath, 'utf-8');
+        const parsed = JSON.parse(fileContent);
+        // Validate that the parsed result is the expected queue shape
+        if (!Array.isArray(parsed)) {
+            throw new Error('Mutation queue file must contain an array');
+        }
+        for (const item of parsed) {
+            if (typeof item !== 'object' ||
+                item === null ||
+                typeof item.id !== 'string' ||
+                typeof item.operationId !== 'string' ||
+                typeof item.type !== 'string' ||
+                typeof item.entityType !== 'string' ||
+                typeof item.entityId !== 'string' ||
+                typeof item.payload !== 'object' ||
+                typeof item.status !== 'string' ||
+                typeof item.timestamp !== 'string' ||
+                typeof item.retries !== 'number') {
+                throw new Error('Invalid mutation record format in queue file');
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        console.error('Error loading mutation queue:', error);
+        throw error;
+    }
+}
+/**
+ * Saves the mutation queue to a JSON file.
+ * @param queue The array of MutationRecord to save.
+ * @param filePath The path to the mutation queue JSON file. Defaults to .taskchain_artifacts/polaris-run/mutation-queue.json.
+ * @returns A promise that resolves when the queue has been saved.
+ */
+async function saveMutationQueue(queue, filePath = path.join(process.cwd(), '.taskchain_artifacts', 'polaris-run', 'mutation-queue.json')) {
+    try {
+        await (0, promises_1.mkdir)(path.dirname(filePath), { recursive: true });
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(queue, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.error('Error saving mutation queue:', error);
+        throw error;
+    }
+}

package/dist/tracker/sync/queue-store.test.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const promises_2 = require("node:fs/promises");
+const queue_store_1 = require("./queue-store");
+(0, vitest_1.describe)('queue-store', () => {
+    let testDir;
+    let testFilePath;
+    (0, vitest_1.beforeEach)(async () => {
+        testDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'queue-store-test-'));
+        testFilePath = (0, node_path_1.join)(testDir, '.polaris', 'runs', 'mutation-queue.json');
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await (0, promises_1.rm)(testDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)('should load an empty array if the queue file does not exist', async () => {
+        const queue = await (0, queue_store_1.loadMutationQueue)(testFilePath);
+        (0, vitest_1.expect)(queue).toEqual([]);
+    });
+    (0, vitest_1.it)('should save and load a queue with multiple records', async () => {
+        const mockQueue = [
+            {
+                id: 'mut-1',
+                operationId: 'op-1',
+                type: 'create',
+                entityType: 'issue',
+                entityId: 'local-1',
+                payload: { title: 'Test Issue 1' },
+                status: 'pending',
+                timestamp: new Date().toISOString(),
+                retries: 0,
+            },
+            {
+                id: 'mut-2',
+                operationId: 'op-2',
+                type: 'update',
+                entityType: 'issue',
+                entityId: 'local-2',
+                payload: { description: 'Updated description' },
+                status: 'failed',
+                timestamp: new Date().toISOString(),
+                retries: 1,
+                error: 'Network error',
+            },
+        ];
+        await (0, queue_store_1.saveMutationQueue)(mockQueue, testFilePath);
+        const loadedQueue = await (0, queue_store_1.loadMutationQueue)(testFilePath);
+        (0, vitest_1.expect)(loadedQueue).toEqual(mockQueue);
+        // Verify file content directly
+        const fileContent = await (0, promises_2.readFile)(testFilePath, 'utf-8');
+        (0, vitest_1.expect)(JSON.parse(fileContent)).toEqual(mockQueue);
+    });
+    (0, vitest_1.it)('should handle saving an empty queue', async () => {
+        await (0, queue_store_1.saveMutationQueue)([], testFilePath);
+        const loadedQueue = await (0, queue_store_1.loadMutationQueue)(testFilePath);
+        (0, vitest_1.expect)(loadedQueue).toEqual([]);
+    });
+    (0, vitest_1.it)('should overwrite existing queue data', async () => {
+        const initialQueue = [
+            {
+                id: 'mut-initial',
+                operationId: 'op-initial',
+                type: 'create',
+                entityType: 'project',
+                entityId: 'proj-1',
+                payload: { name: 'Initial Project' },
+                status: 'succeeded',
+                timestamp: new Date().toISOString(),
+                retries: 0,
+            },
+        ];
+        await (0, queue_store_1.saveMutationQueue)(initialQueue, testFilePath);
+        const newQueue = [
+            {
+                id: 'mut-new',
+                operationId: 'op-new',
+                type: 'update',
+                entityType: 'project',
+                entityId: 'proj-1',
+                payload: { name: 'Updated Project' },
+                status: 'pending',
+                timestamp: new Date().toISOString(),
+                retries: 0,
+            },
+        ];
+        await (0, queue_store_1.saveMutationQueue)(newQueue, testFilePath);
+        const loadedQueue = await (0, queue_store_1.loadMutationQueue)(testFilePath);
+        (0, vitest_1.expect)(loadedQueue).toEqual(newQueue);
+    });
+    (0, vitest_1.it)('should return an empty array if the file exists but is empty', async () => {
+        await (0, queue_store_1.saveMutationQueue)([], testFilePath); // create an empty file
+        const queue = await (0, queue_store_1.loadMutationQueue)(testFilePath);
+        (0, vitest_1.expect)(queue).toEqual([]);
+    });
+    (0, vitest_1.it)('should throw an error for malformed JSON content', async () => {
+        // Manually create a malformed JSON file
+        await (0, promises_1.mkdir)((0, node_path_1.join)(testDir, '.polaris', 'runs'), { recursive: true });
+        await (0, promises_1.writeFile)(testFilePath, '{"id": "malformed",', 'utf-8');
+        await (0, vitest_1.expect)((0, queue_store_1.loadMutationQueue)(testFilePath)).rejects.toThrow(SyntaxError);
+    });
+});