@n-dx/core 0.1.0

package/packages/rex/dist/core/scope-creep.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Scope creep detection for container items (epics, features).
+ *
+ * Detects when a container's child count has grown significantly beyond
+ * its initial count (stored as item metadata `initialChildCount`).
+ *
+ * @module rex/core/scope-creep
+ */
+import type { PRDItem } from "../schema/index.js";
+/** Result of scope creep detection for a single container. */
+export interface ScopeCreepResult {
+    id: string;
+    title: string;
+    level: string;
+    initialChildCount: number;
+    currentChildCount: number;
+    growthPercent: number;
+}
+/**
+ * Detect containers whose child count has grown beyond the initial count.
+ *
+ * @param items - PRD item tree
+ * @param threshold - growth ratio threshold (default 0.5 = 50% increase)
+ * @returns containers that have grown beyond the threshold
+ */
+export declare function detectScopeCreep(items: PRDItem[], threshold?: number): ScopeCreepResult[];
+/**
+ * Set the initial child count on a container item.
+ * Call this when a container is first created or when resetting the baseline.
+ */
+export declare function setInitialChildCount(item: PRDItem): void;

package/packages/rex/dist/core/scope-creep.js

@@ -0,0 +1,53 @@
+/**
+ * Scope creep detection for container items (epics, features).
+ *
+ * Detects when a container's child count has grown significantly beyond
+ * its initial count (stored as item metadata `initialChildCount`).
+ *
+ * @module rex/core/scope-creep
+ */
+import { isContainerLevel } from "../schema/index.js";
+import { walkTree } from "./tree.js";
+/** Default growth threshold: 50% increase triggers a warning. */
+const DEFAULT_THRESHOLD = 0.5;
+/**
+ * Detect containers whose child count has grown beyond the initial count.
+ *
+ * @param items - PRD item tree
+ * @param threshold - growth ratio threshold (default 0.5 = 50% increase)
+ * @returns containers that have grown beyond the threshold
+ */
+export function detectScopeCreep(items, threshold = DEFAULT_THRESHOLD) {
+    const results = [];
+    for (const { item } of walkTree(items)) {
+        if (!isContainerLevel(item.level))
+            continue;
+        if (!item.children || item.children.length === 0)
+            continue;
+        const initial = item.initialChildCount;
+        if (typeof initial !== "number" || initial <= 0)
+            continue;
+        const current = item.children.filter((c) => c.status !== "deleted").length;
+        const growth = (current - initial) / initial;
+        if (growth > threshold) {
+            results.push({
+                id: item.id,
+                title: item.title,
+                level: item.level,
+                initialChildCount: initial,
+                currentChildCount: current,
+                growthPercent: Math.round(growth * 100),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Set the initial child count on a container item.
+ * Call this when a container is first created or when resetting the baseline.
+ */
+export function setInitialChildCount(item) {
+    const count = item.children?.filter((c) => c.status !== "deleted").length ?? 0;
+    item.initialChildCount = count;
+}
+//# sourceMappingURL=scope-creep.js.map

package/packages/rex/dist/core/scope-creep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-creep.js","sourceRoot":"","sources":["../../src/core/scope-creep.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAYrC,iEAAiE;AACjE,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAgB,EAChB,YAAoB,iBAAiB;IAErC,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QAC5C,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAE3D,MAAM,OAAO,GAAI,IAAgC,CAAC,iBAAiB,CAAC;QACpE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC;YAAE,SAAS;QAE1D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;QACpF,MAAM,MAAM,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC;QAE7C,IAAI,MAAM,GAAG,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,iBAAiB,EAAE,OAAO;gBAC1B,iBAAiB,EAAE,OAAO;gBAC1B,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC;aACxC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9E,IAAgC,CAAC,iBAAiB,GAAG,KAAK,CAAC;AAC9D,CAAC"}

package/packages/rex/dist/core/stats.d.ts

@@ -0,0 +1,12 @@
+import type { PRDItem } from "../schema/index.js";
+export interface TreeStats {
+    total: number;
+    completed: number;
+    inProgress: number;
+    pending: number;
+    failing: number;
+    deferred: number;
+    blocked: number;
+    deleted: number;
+}
+export declare function computeStats(items: PRDItem[]): TreeStats;

package/packages/rex/dist/core/stats.js

@@ -0,0 +1,47 @@
+import { isWorkItem } from "../schema/index.js";
+import { walkTree } from "./tree.js";
+export function computeStats(items) {
+    const stats = {
+        total: 0,
+        completed: 0,
+        inProgress: 0,
+        pending: 0,
+        failing: 0,
+        deferred: 0,
+        blocked: 0,
+        deleted: 0,
+    };
+    for (const { item } of walkTree(items)) {
+        // Only count work items (not containers) for accurate work metrics
+        if (!isWorkItem(item.level))
+            continue;
+        // Deleted items are tracked separately and excluded from total
+        if (item.status === "deleted") {
+            stats.deleted++;
+            continue;
+        }
+        stats.total++;
+        switch (item.status) {
+            case "completed":
+                stats.completed++;
+                break;
+            case "in_progress":
+                stats.inProgress++;
+                break;
+            case "pending":
+                stats.pending++;
+                break;
+            case "failing":
+                stats.failing++;
+                break;
+            case "deferred":
+                stats.deferred++;
+                break;
+            case "blocked":
+                stats.blocked++;
+                break;
+        }
+    }
+    return stats;
+}
+//# sourceMappingURL=stats.js.map

package/packages/rex/dist/core/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/core/stats.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAarC,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,MAAM,KAAK,GAAc;QACvB,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;KACX,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,mEAAmE;QACnE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QAEtC,+DAA+D;QAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QAED,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,WAAW;gBACd,KAAK,CAAC,SAAS,EAAE,CAAC;gBAClB,MAAM;YACR,KAAK,aAAa;gBAChB,KAAK,CAAC,UAAU,EAAE,CAAC;gBACnB,MAAM;YACR,KAAK,SAAS;gBACZ,KAAK,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM;YACR,KAAK,SAAS;gBACZ,KAAK,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM;YACR,KAAK,UAAU;gBACb,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACjB,MAAM;YACR,KAAK,SAAS;gBACZ,KAAK,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/rex/dist/core/structural.d.ts

@@ -0,0 +1,63 @@
+import type { PRDItem, ItemLevel } from "../schema/index.js";
+export interface EpiclessFeature {
+    itemId: string;
+    title: string;
+    status: string;
+    childCount: number;
+}
+export interface OrphanedItem {
+    itemId: string;
+    title: string;
+    level: ItemLevel;
+    reason: string;
+}
+export interface StuckItem {
+    itemId: string;
+    title: string;
+    stuckSinceMs: number;
+    reason: string;
+}
+export interface EmptyContainerItem {
+    itemId: string;
+    title: string;
+    level: ItemLevel;
+    reason: string;
+}
+export interface StructuralResult {
+    valid: boolean;
+    errors: string[];
+    /** Non-fatal issues (e.g. blocked items without blockedBy). */
+    warnings: string[];
+    orphanedItems: OrphanedItem[];
+    cycles: string[][];
+    stuckItems: StuckItem[];
+    /** Epics/features with no (non-deleted) children — indicates incomplete work. */
+    emptyContainers: EmptyContainerItem[];
+}
+export interface StructuralOptions {
+    /** Threshold in milliseconds before an in_progress task is considered stuck. Default: 48 hours. */
+    stuckThresholdMs?: number;
+    /** Override "now" for testing. Default: Date.now(). */
+    now?: number;
+}
+/**
+ * Validate structural integrity of a PRD tree beyond schema and DAG checks.
+ *
+ * Detects:
+ * 1. Orphaned items — placed at a level that violates the hierarchy rules
+ * 2. Circular blockedBy references — cycles in the dependency graph
+ * 3. Stuck tasks — in_progress for too long or missing startedAt
+ *
+ * Warns:
+ * - Items with status "blocked" but no blockedBy dependencies
+ * - Empty containers — epics/features with no (non-deleted) children
+ */
+export declare function validateStructure(items: PRDItem[], options?: StructuralOptions): StructuralResult;
+/**
+ * Find features positioned at root level without a parent epic.
+ *
+ * These violate the hierarchy rule that features must be under an epic.
+ * Returns structured data for each epicless feature, including status
+ * and non-deleted child count, suitable for interactive resolution prompts.
+ */
+export declare function findEpiclessFeatures(items: PRDItem[]): EpiclessFeature[];

package/packages/rex/dist/core/structural.js

@@ -0,0 +1,267 @@
+import { LEVEL_HIERARCHY, getContainerLevels } from "../schema/index.js";
+import { walkTree, collectAllIds } from "./tree.js";
+const DEFAULT_STUCK_THRESHOLD_MS = 48 * 60 * 60 * 1000; // 48 hours
+/**
+ * Validate structural integrity of a PRD tree beyond schema and DAG checks.
+ *
+ * Detects:
+ * 1. Orphaned items — placed at a level that violates the hierarchy rules
+ * 2. Circular blockedBy references — cycles in the dependency graph
+ * 3. Stuck tasks — in_progress for too long or missing startedAt
+ *
+ * Warns:
+ * - Items with status "blocked" but no blockedBy dependencies
+ * - Empty containers — epics/features with no (non-deleted) children
+ */
+export function validateStructure(items, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const orphanedItems = findOrphanedItems(items);
+    const cycles = findCycles(items);
+    const stuckItems = findStuckItems(items, options);
+    const emptyContainers = findEmptyContainers(items);
+    for (const orphan of orphanedItems) {
+        errors.push(`Orphaned: "${orphan.itemId}" (${orphan.level}) — ${orphan.reason}`);
+    }
+    for (const cycle of cycles) {
+        errors.push(`Cycle: ${cycle.join(" → ")}`);
+    }
+    for (const stuck of stuckItems) {
+        errors.push(`Stuck: "${stuck.itemId}" — ${stuck.reason}`);
+    }
+    for (const ec of emptyContainers) {
+        warnings.push(`Empty container: "${ec.itemId}" (${ec.title}) — ${ec.reason}`);
+    }
+    // Warn about blocked items with no recorded dependencies
+    for (const { item } of walkTree(items)) {
+        if (item.status === "blocked" &&
+            (!item.blockedBy || item.blockedBy.length === 0)) {
+            warnings.push(`Blocked without dependencies: "${item.id}" (${item.title}) — ` +
+                `status is "blocked" but blockedBy is empty. Consider adding dependency IDs ` +
+                `or recording the blocker reason in the description.`);
+        }
+    }
+    // Timestamp and status-field consistency
+    const timestampWarnings = findTimestampInconsistencies(items);
+    warnings.push(...timestampWarnings);
+    // Parent-child status consistency
+    const parentChildWarnings = findParentChildInconsistencies(items);
+    warnings.push(...parentChildWarnings);
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        orphanedItems,
+        cycles,
+        stuckItems,
+        emptyContainers,
+    };
+}
+/**
+ * Find items whose placement violates the LEVEL_HIERARCHY rules.
+ */
+function findOrphanedItems(items) {
+    const orphans = [];
+    for (const { item, parents } of walkTree(items)) {
+        const parentLevel = parents.length > 0 ? parents[parents.length - 1].level : null;
+        const allowedParents = LEVEL_HIERARCHY[item.level];
+        if (!allowedParents.includes(parentLevel)) {
+            const placement = parentLevel === null ? "root" : `under ${parentLevel}`;
+            const expected = allowedParents
+                .map((l) => (l === null ? "root" : l))
+                .join(" or ");
+            orphans.push({
+                itemId: item.id,
+                title: item.title,
+                level: item.level,
+                reason: `${item.level} at ${placement}, expected under ${expected}`,
+            });
+        }
+    }
+    return orphans;
+}
+/**
+ * Container levels that should have children to be meaningful.
+ * Work items (tasks/subtasks) are leaf-level and don't require children.
+ */
+const CONTAINER_LEVELS = new Set(getContainerLevels());
+/**
+ * Terminal statuses where an empty container is expected or acceptable.
+ * Completed, deferred, and deleted items don't need children.
+ */
+const TERMINAL_CONTAINER_STATUSES = new Set(["completed", "deferred", "deleted"]);
+/**
+ * Find epics and features with no (non-deleted) children.
+ * These indicate incomplete work — a container was created but never populated.
+ */
+function findEmptyContainers(items) {
+    const empty = [];
+    for (const { item } of walkTree(items)) {
+        if (!CONTAINER_LEVELS.has(item.level))
+            continue;
+        if (TERMINAL_CONTAINER_STATUSES.has(item.status))
+            continue;
+        const liveChildren = (item.children ?? []).filter((c) => c.status !== "deleted");
+        if (liveChildren.length === 0) {
+            empty.push({
+                itemId: item.id,
+                title: item.title,
+                level: item.level,
+                reason: `${item.level} has no child items`,
+            });
+        }
+    }
+    return empty;
+}
+/**
+ * Find cycles in the blockedBy dependency graph.
+ *
+ * Returns each cycle as an array of IDs forming the loop (last element
+ * repeats the first to show the cycle closing).
+ */
+function findCycles(items) {
+    const allIds = collectAllIds(items);
+    const cycles = [];
+    // Build adjacency: item → items it depends on (via blockedBy)
+    const adjacency = new Map();
+    for (const { item } of walkTree(items)) {
+        if (item.blockedBy && item.blockedBy.length > 0) {
+            adjacency.set(item.id, item.blockedBy.filter((dep) => allIds.has(dep)));
+        }
+    }
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(node, path) {
+        if (inStack.has(node)) {
+            const cycleStart = path.indexOf(node);
+            cycles.push(path.slice(cycleStart).concat(node));
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        inStack.add(node);
+        for (const dep of adjacency.get(node) ?? []) {
+            dfs(dep, [...path, node]);
+        }
+        inStack.delete(node);
+    }
+    for (const id of allIds) {
+        if (!visited.has(id)) {
+            dfs(id, []);
+        }
+    }
+    return cycles;
+}
+/**
+ * Find timestamp and status-field inconsistencies.
+ *
+ * Detects:
+ * - Completed items without completedAt
+ * - Non-completed items with stale completedAt
+ * - completedAt before startedAt
+ */
+function findTimestampInconsistencies(items) {
+    const warnings = [];
+    for (const { item } of walkTree(items)) {
+        // Completed items should have completedAt
+        if (item.status === "completed" && !item.completedAt) {
+            warnings.push(`Timestamp inconsistency: "${item.id}" (${item.title}) — ` +
+                `status is "completed" but completedAt is missing.`);
+        }
+        // Non-completed items should not have completedAt
+        if (item.status !== "completed" && item.completedAt) {
+            warnings.push(`Timestamp inconsistency: "${item.id}" (${item.title}) — ` +
+                `status is "${item.status}" but completedAt is set. ` +
+                `Consider clearing completedAt or updating the status.`);
+        }
+        // completedAt must be after startedAt
+        if (item.startedAt && item.completedAt) {
+            const started = new Date(item.startedAt).getTime();
+            const completed = new Date(item.completedAt).getTime();
+            if (completed < started) {
+                warnings.push(`Timestamp inconsistency: "${item.id}" (${item.title}) — ` +
+                    `completedAt is before startedAt.`);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Find parent-child status inconsistencies.
+ *
+ * Detects:
+ * - Completed parent with non-terminal children (pending, in_progress, blocked)
+ */
+function findParentChildInconsistencies(items) {
+    const warnings = [];
+    const terminalStatuses = new Set(["completed", "deferred"]);
+    for (const { item } of walkTree(items)) {
+        if (item.status !== "completed")
+            continue;
+        if (!item.children || item.children.length === 0)
+            continue;
+        const nonTerminal = item.children.filter((c) => !terminalStatuses.has(c.status));
+        if (nonTerminal.length > 0) {
+            const childSummary = nonTerminal
+                .slice(0, 3)
+                .map((c) => `"${c.title}" (${c.status})`)
+                .join(", ");
+            const more = nonTerminal.length > 3 ? ` +${nonTerminal.length - 3} more` : "";
+            warnings.push(`Parent-child inconsistency: "${item.id}" (${item.title}) — ` +
+                `status is "completed" but has non-terminal children: ${childSummary}${more}.`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Find features positioned at root level without a parent epic.
+ *
+ * These violate the hierarchy rule that features must be under an epic.
+ * Returns structured data for each epicless feature, including status
+ * and non-deleted child count, suitable for interactive resolution prompts.
+ */
+export function findEpiclessFeatures(items) {
+    return items
+        .filter((item) => item.level === "feature" && item.status !== "deleted")
+        .map((item) => ({
+        itemId: item.id,
+        title: item.title,
+        status: item.status,
+        childCount: (item.children ?? []).filter((c) => c.status !== "deleted").length,
+    }));
+}
+/**
+ * Find tasks that are in_progress for too long or are missing startedAt.
+ */
+function findStuckItems(items, options) {
+    const threshold = options.stuckThresholdMs ?? DEFAULT_STUCK_THRESHOLD_MS;
+    const now = options.now ?? Date.now();
+    const stuck = [];
+    for (const { item } of walkTree(items)) {
+        if (item.status !== "in_progress")
+            continue;
+        if (!item.startedAt) {
+            stuck.push({
+                itemId: item.id,
+                title: item.title,
+                stuckSinceMs: 0,
+                reason: "in_progress with no startedAt timestamp",
+            });
+            continue;
+        }
+        const started = new Date(item.startedAt).getTime();
+        const elapsed = now - started;
+        if (elapsed > threshold) {
+            const hours = Math.floor(elapsed / (60 * 60 * 1000));
+            stuck.push({
+                itemId: item.id,
+                title: item.title,
+                stuckSinceMs: elapsed,
+                reason: `in_progress for ${hours}h (threshold: ${Math.floor(threshold / (60 * 60 * 1000))}h)`,
+            });
+        }
+    }
+    return stuck;
+}
+//# sourceMappingURL=structural.js.map

package/packages/rex/dist/core/structural.js.map

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

package/packages/rex/dist/core/sync-engine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bidirectional sync engine for PRDStore instances.
+ *
+ * Coordinates between a local store and a remote store using the primitives
+ * from `sync.ts` (conflict detection, resolution, timestamping). Supports
+ * three sync modes:
+ *
+ * - **push**: local → remote (send local changes out)
+ * - **pull**: remote → local (fetch remote changes in)
+ * - **sync**: bidirectional (push + pull with unified conflict resolution)
+ *
+ * The engine operates on flat item maps built from each store's document tree,
+ * then writes the merged result back to both stores.
+ */
+import type { PRDStore } from "../store/contracts.js";
+import { type ConflictRecord } from "./sync.js";
+export type SyncDirection = "push" | "pull" | "sync";
+export interface SyncReport {
+    direction: SyncDirection;
+    /** Items pushed from local to remote */
+    pushed: string[];
+    /** Items pulled from remote to local */
+    pulled: string[];
+    /** Items unchanged and skipped */
+    skipped: string[];
+    /** Conflicts detected and resolved */
+    conflicts: ConflictRecord[];
+    /** Items deleted from remote during sync */
+    deleted: string[];
+    /** Errors encountered during sync */
+    errors: Array<{
+        itemId: string;
+        error: string;
+    }>;
+    /** ISO 8601 timestamp of the sync operation */
+    timestamp: string;
+}
+export interface SyncOptions {
+    /** Set of item IDs that were locally deleted since last sync. */
+    deletions?: Set<string>;
+}
+export declare class SyncEngine {
+    private local;
+    private remote;
+    constructor(local: PRDStore, remote: PRDStore);
+    /**
+     * Push local changes to the remote store.
+     * Items modified locally since last sync are written to remote.
+     * If the remote also changed the same item, conflict resolution applies.
+     */
+    push(): Promise<SyncReport>;
+    /**
+     * Pull remote changes to the local store.
+     * Items modified remotely since last sync are written to local.
+     * If the local also changed the same item, conflict resolution applies.
+     */
+    pull(): Promise<SyncReport>;
+    /**
+     * Full bidirectional sync: push local changes, pull remote changes,
+     * resolve any conflicts with last-write-wins.
+     */
+    sync(options?: SyncOptions): Promise<SyncReport>;
+}