@adhdev/daemon-core 0.9.82-rc.34 → 0.9.82-rc.341

package/dist/mesh/mesh-runtime-store.d.ts

@@ -0,0 +1,418 @@
+import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
+export declare class MeshRuntimeStore {
+    private static instance;
+    private readonly db;
+    private readonly dbPath;
+    private readonly migratedMeshIds;
+    private fingerprintSweepCounter;
+    private walWriteCounter;
+    private static readonly WAL_CHECK_INTERVAL;
+    private static readonly WAL_MAX_BYTES;
+    private constructor();
+    static getInstance(): MeshRuntimeStore;
+    static resetForTests(): void;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    private migrate;
+    hasCompletionFingerprint(fingerprint: string): boolean;
+    recordCompletionFingerprint(fingerprint: string, ttlMs: number): void;
+    sweepExpiredFingerprints(): void;
+    recordDirectDelivered(coordinatorDaemonId: string, fingerprint: string, ttlMs: number): void;
+    wasDirectDelivered(coordinatorDaemonId: string, fingerprint: string): boolean;
+    sweepExpiredDirectDelivered(): void;
+    private maybeCheckpointWal;
+    private ensureLegacyQueueMigrated;
+    getQueueEntries(meshId: string, statuses?: MeshTaskStatus[]): MeshWorkQueueEntry[];
+    getQueueRevision(meshId: string): string;
+    replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void;
+    deleteQueue(meshId: string): void;
+    insertQueueEntry(entry: MeshWorkQueueEntry): void;
+    updateQueueEntry(entry: MeshWorkQueueEntry): void;
+    findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null;
+    hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean;
+    /** A session may only execute one task at a time, regardless of task mode. */
+    private hasActiveSessionAssignment;
+    /** A node may only execute one write task at a time (worktree isolation). */
+    private hasActiveNodeAssignment;
+    /**
+     * Count active (status='assigned') tasks on a node, regardless of provider or
+     * task mode. This is the load metric for least-loaded / round-robin ranking:
+     * the scheduler prefers the node with the fewest active assignments so
+     * untargeted work spreads instead of piling onto whichever node asks first.
+     */
+    nodeActiveAssignmentCount(meshId: string, nodeId: string): number;
+    /**
+     * O(1) count of queue tasks in 'pending' status for a mesh. A COUNT(*) over the
+     * indexed status column, so it avoids JSON.parse-ing every queue row — used as a
+     * cheap guard before the reconcile loop runs a full triggerMeshQueue scan.
+     */
+    pendingQueueTaskCount(meshId: string): number;
+    /**
+     * Read the current per-mesh round-robin cursor (0 when unset). Used to rotate
+     * the tie-break winner among nodes tied at the least load.
+     */
+    getSchedulerCursor(meshId: string): number;
+    /**
+     * Atomically advance the per-mesh round-robin cursor by one and return the
+     * value that was current BEFORE the bump (the value the caller should rotate
+     * by for this pass). UPSERT keeps it lock-free across concurrent passes.
+     */
+    bumpSchedulerCursor(meshId: string): number;
+    /**
+     * Count active (status='assigned') tasks on a (node, provider) combination,
+     * matched by the assignedProviderType stamped on the payload at claim time.
+     * Drives the per-(node, provider) maxParallel cap (RepoMeshNodePolicy
+     * providerRoles). The active-assignment set for a single node is tiny, so
+     * parsing payloads here is cheap and avoids a schema migration. Pre-cap legacy
+     * rows (no provider stamp) and other providers on the same node do not consume
+     * this provider's budget, so the cap is fully backward compatible.
+     */
+    private activeProviderAssignmentCount;
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[], opts?: {
+        providerType?: string;
+        providerMaxParallel?: number;
+    }): MeshWorkQueueEntry | null;
+    getQueueStatsByStatus(meshId: string): {
+        status: string;
+        count: number;
+    }[];
+    getActiveAssignmentDetails(meshId: string): Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+        message: string;
+    }>;
+    /**
+     * Resolve the `assigned` queue row a completion event belongs to.
+     *
+     * Clock-skew safety (C2): a completion event's `occurredAtIso` carries the
+     * REMOTE WORKER's clock, while `updated_at` carries the COORDINATOR's clock
+     * (set at assignment and re-bumped on every mutation). For a remote node,
+     * coordinator-clock > worker-clock skew used to make an `updated_at <= occurredAt`
+     * filter return nothing, stranding the finished task as `assigned` forever.
+     *
+     * We therefore NEVER filter completion-matching on the mutable `updated_at`:
+     *  1. If `taskId` is given, match the exact `assigned` row by id (no time filter).
+     *  2. Otherwise a session holds at most one `assigned` task — match it without a
+     *     time filter. If several exist (shouldn't normally), disambiguate by the
+     *     IMMUTABLE `dispatchTimestamp`: latest `dispatchTimestamp <= occurredAt`,
+     *     and if skew makes ALL of them later than `occurredAt`, fall back to the
+     *     most-recent `dispatchTimestamp` rather than returning null.
+     */
+    findAssignedBySession(meshId: string, sessionId: string, occurredAtIso?: string, taskId?: string): MeshWorkQueueEntry | null;
+    private toRow;
+    insertDirectDispatch(entry: {
+        taskId: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    }): void;
+    getActiveDirectDispatches(meshId: string): Array<{
+        taskId: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        message: string;
+        taskMode: string | null;
+        via: string;
+        status: string;
+        dispatchedToIdleSession: boolean;
+        dispatchedAt: string;
+        updatedAt: string;
+    }>;
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+    cleanupTerminalDirectDispatches(olderThanMs: number): void;
+    deleteDirectDispatches(meshId: string): void;
+    /**
+     * Delete specific direct dispatch rows by taskId for a mesh. Used by the staleDirect prune
+     * path to remove orphaned/terminal dispatch records whose node/session is no longer in the
+     * live mesh. Returns the number of rows actually deleted. No-op for an empty taskId list.
+     */
+    deleteDirectDispatchesByTaskId(meshId: string, taskIds: string[]): number;
+    markStaleDirectDispatches(meshId: string, olderThanMs: number): void;
+    setRemoteIdleSession(nodeId: string, sessionId: string, providerType: string, expiresAt: number, metadata?: any): void;
+    getRemoteIdleSessions(): Array<{
+        nodeId: string;
+        sessionId: string;
+        providerType: string;
+        expiresAt: number;
+        metadata?: any;
+    }>;
+    deleteRemoteIdleSession(nodeId: string, sessionId: string): void;
+    pruneExpiredRemoteIdleSessions(): void;
+    insertSessionDelivery(entry: {
+        id: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        taskId?: string;
+        kind: string;
+        priority?: number;
+        message: string;
+        status: string;
+        deliverAfter?: string;
+        expiresAt?: string;
+        sourceCoordinatorSessionId?: string;
+        sourceCoordinatorDaemonId?: string;
+        createdAt: string;
+        updatedAt: string;
+    }): void;
+    updateSessionDeliveryStatus(id: string, status: string, opts?: {
+        lastError?: string;
+        incrementAttempt?: boolean;
+    }): void;
+    getActiveSessionDeliveries(meshId: string, sessionId?: string): Array<{
+        id: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        taskId: string | null;
+        kind: string;
+        priority: number;
+        message: string;
+        status: string;
+        deliverAfter: string | null;
+        expiresAt: string | null;
+        attemptCount: number;
+        sourceCoordinatorSessionId: string | null;
+        sourceCoordinatorDaemonId: string | null;
+        lastError: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    expireStaleSessionDeliveries(meshId: string): void;
+    deleteSessionDeliveries(meshId: string): void;
+    recordCompletionConflict(entry: {
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId?: string;
+        conflictingSessionId?: string;
+        originalTaskId?: string;
+        originalSessionId?: string;
+        event: string;
+        createdAt: string;
+    }): void;
+    getRecentCompletionConflicts(meshId: string, limitMs?: number): Array<{
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId: string | null;
+        conflictingSessionId: string | null;
+        originalTaskId: string | null;
+        originalSessionId: string | null;
+        event: string;
+        createdAt: string;
+    }>;
+    /**
+     * Record a mesh tool call and check whether this mesh+tool combination is
+     * being called too rapidly (sliding window rate guard).
+     *
+     * Returns a rate-limit advisory string when the call rate is too high, null otherwise.
+     * windowMs: sliding window size in ms (default 10s)
+     * maxCalls: max allowed calls within the window (default 5)
+     */
+    recordMeshToolCall(opts: {
+        meshId: string;
+        tool: string;
+        sessionId?: string | null;
+        windowMs?: number;
+        maxCalls?: number;
+    }): {
+        rateLimitExceeded: boolean;
+        callsInWindow: number;
+        advisory: string | null;
+    };
+    /**
+     * Prune tool call log entries older than the given age in ms.
+     * Exposed for testing.
+     */
+    pruneToolCallLog(olderThanMs: number): void;
+    appendLedgerEntry(entry: {
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }): void;
+    readLedgerEntries(meshId: string, opts?: {
+        tail?: number;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /**
+     * G2 read cutover: read ledger entries in append order (oldest first),
+     * matching legacy JSONL file-order semantics. Ties on the same timestamp
+     * are broken by rowid (insertion order), preserving the positional
+     * guarantee that mesh-events relies on for same-millisecond entries.
+     */
+    readLedgerEntriesOrdered(meshId: string, opts?: {
+        since?: string;
+        kinds?: string[];
+        tail?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /** Remove all ledger entries for a mesh (mesh deletion / test cleanup). */
+    clearLedgerForMesh(meshId: string): number;
+    /** G2: remove entries moved to the JSONL archive so the SQLite runtime set mirrors the active ledger. */
+    deleteLedgerEntries(meshId: string, ids: string[]): number;
+    hasLedgerEntry(meshId: string, id: string): boolean;
+    ledgerEntryCount(meshId: string): number;
+    importLedgerEntries(entries: Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }>): number;
+    /**
+     * G4: Read a bounded, cursor-addressable ledger slice directly from the SQLite
+     * mesh_event_ledger table. This is the P2P reconcile read path; JSONL files are
+     * retained as export/import/debug/legacy artifacts only.
+     *
+     * The return shape is structurally compatible with MeshLedgerSlice so callers
+     * in mesh-tools.ts can pass it directly to buildMeshLedgerReplicaEvidence.
+     */
+    readLedgerSlice(meshId: string, opts?: {
+        afterId?: string;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): {
+        protocol: 'adhdev.mesh.ledger.slice.v1';
+        meshId: string;
+        entries: Array<{
+            id: string;
+            meshId: string;
+            timestamp: string;
+            kind: string;
+            nodeId: string | null;
+            sessionId: string | null;
+            providerType: string | null;
+            payload: unknown;
+        }>;
+        cursor: {
+            afterId: string | null;
+            nextAfterId: string | null;
+            limit: number;
+            hasMore: boolean;
+        };
+        sourceOfTruth: {
+            kind: 'local_sqlite';
+            table: 'mesh_event_ledger';
+            bounded: true;
+            maxLimit: number;
+        };
+    };
+    insertPendingEvent(event: {
+        id: string;
+        meshId: string;
+        coordinatorDaemonId?: string | null;
+        event: string;
+        payload?: unknown;
+        fingerprint?: string | null;
+        queuedAt: number;
+    }): boolean;
+    /**
+     * Drain undrained pending events for a mesh, atomically marking them drained.
+     * When `opts.onlyEvents` is supplied, ONLY rows whose `event` is in that set are
+     * drained — the rest stay queued (drained=0) for a later drain. This is how the
+     * reconcile loop force-drains terminal/force-inject events into a *generating*
+     * coordinator while leaving non-force progress events for the coordinator's next
+     * idle transition. Filtering happens inside the same transaction as the
+     * drained=1 marking, so force-drain + a concurrent full drain can never both
+     * consume the same row.
+     */
+    drainPendingEvents(meshId: string, coordinatorDaemonId?: string | null | ReadonlyArray<string>, opts?: {
+        onlyEvents?: ReadonlySet<string>;
+    }): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    /** Non-destructive peek — returns undrained events without marking them drained. */
+    peekPendingEvents(meshId: string, coordinatorDaemonId?: string | null | ReadonlyArray<string>): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    hasPendingEventFingerprint(meshId: string, fingerprint: string): boolean;
+    upsertMission(mission: {
+        id: string;
+        meshId: string;
+        title: string;
+        goal?: string;
+        status?: string;
+    }): void;
+    getMission(meshId: string, missionId: string): {
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    getMissions(meshId: string, statuses?: string[]): Array<{
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Remove all missions for a mesh — mesh deletion / test cleanup. */
+    clearMissionsForMesh(meshId: string): number;
+    /** Remove all pending-event rows (drained included) for a mesh — mesh deletion / test cleanup. */
+    clearPendingEventsForMesh(meshId: string): number;
+    pendingEventCount(meshId: string): number;
+    /**
+     * Mark specific pending-event rows drained by id (ack). Used by the
+     * unresolved-delegate durable-forward outbox: an event is peeked (not drained)
+     * while its push to the coordinator is unconfirmed, then marked drained ONLY
+     * after the push is acked. A failed push leaves the row undrained so the next
+     * reconcile tick retries it. Returns the number of rows newly marked drained.
+     */
+    markPendingEventsDrainedById(ids: ReadonlyArray<string>): number;
+    /**
+     * Hard-delete pending-event rows by id (including the dedup fingerprint history).
+     * Used to expire an unresolved-delegate outbox entry that has exhausted its retry
+     * budget — fully removing it frees the fingerprint so a genuinely new completion
+     * for the same task could be re-queued later. Returns the number of rows deleted.
+     */
+    deletePendingEventsById(ids: ReadonlyArray<string>): number;
+}

package/dist/mesh/mesh-task-stats.d.ts

@@ -0,0 +1,49 @@
+/**
+ * M7: Operational stats (time/attempts) derived from existing truth.
+ *
+ * No cost/token accounting — ADHDev observes PTY/CDP and cannot see API
+ * tokens (explicit non-goal). Everything here is derived at query time from
+ * the SQLite ledger and queue rows; there is no separate aggregate table.
+ * Tasks with missing ledger evidence report incompleteEvidence instead of
+ * estimated numbers.
+ */
+export interface MeshTaskStats {
+    taskId: string;
+    status: string;
+    dispatchedAt: string | null;
+    terminalAt: string | null;
+    terminalKind: 'task_completed' | 'task_failed' | null;
+    /** dispatched → terminal wall clock; null when evidence is incomplete. */
+    durationMs: number | null;
+    /** Number of task_dispatched ledger entries observed for this task. */
+    dispatchCount: number;
+    /** Queue requeueCount (0 when the row is gone or never requeued). */
+    requeueCount: number;
+    /** True when dispatch or terminal ledger evidence is missing — numbers are withheld, never estimated. */
+    incompleteEvidence?: true;
+}
+export interface MeshMissionStats {
+    missionId: string;
+    taskCount: number;
+    completed: number;
+    failed: number;
+    /** Sum of per-task durations with complete evidence. */
+    totalDurationMs: number;
+    /** First dispatch → last terminal across the mission's tasks; null without complete endpoints. */
+    wallClockMs: number | null;
+    /** Total requeue attempts across the mission's tasks. */
+    retries: number;
+    /** Task ids whose ledger evidence was incomplete (excluded from sums). */
+    incompleteTaskIds: string[];
+}
+/**
+ * Compute per-task stats from ledger entries. Scans a bounded tail window —
+ * stats are an operational view of recent work, not a full historical report.
+ */
+export declare function computeMeshTaskStats(meshId: string, opts?: {
+    taskIds?: string[];
+    missionId?: string;
+    tail?: number;
+}): MeshTaskStats[];
+/** Mission rollup — derived from per-task stats, no stored aggregates. */
+export declare function computeMeshMissionStats(meshId: string, missionId: string): MeshMissionStats;

package/dist/mesh/mesh-unresolved-forward-outbox.d.ts

@@ -0,0 +1,30 @@
+export declare const UNRESOLVED_FORWARD_OUTBOX_MESH_ID = "__unresolved_forward_outbox__";
+export interface UnresolvedForwardEntry {
+    /** Row id in mesh_pending_events; pass back to ack/expire after a push attempt. */
+    id: string;
+    /** The coordinator daemon to push this event to (mesh_forward_event target). */
+    coordinatorDaemonId: string;
+    /** The flat payload to forward (already shaped for handleMeshForwardEvent). */
+    payload: Record<string, unknown>;
+    /** When the entry was first enqueued (epoch ms) — used for age-based expiry. */
+    queuedAt: number;
+}
+/**
+ * Durably enqueue an unresolved-delegate forward for a coordinator daemon. The
+ * `forwardPayload` is the flat shape handleMeshForwardEvent reads on the coordinator.
+ * Idempotent on the event fingerprint. Returns true when a new row was written (or a
+ * duplicate was harmlessly ignored), false on a hard persistence failure.
+ */
+export declare function enqueueUnresolvedDelegateForward(coordinatorDaemonId: string, eventName: string, forwardPayload: Record<string, unknown>): boolean;
+/** Peek (non-destructive) every undrained outbox entry across all coordinators. */
+export declare function peekUnresolvedDelegateForwards(): UnresolvedForwardEntry[];
+/** Mark an outbox entry delivered (acked) after a successful push. */
+export declare function ackUnresolvedDelegateForward(id: string): void;
+/**
+ * Drop outbox entries that have exceeded the max retry age. Returns the count
+ * expired so the caller can log a fail-loud trace (a dropped completion is a real
+ * loss; it must be visible, not silent).
+ */
+export declare function expireStaleUnresolvedDelegateForwards(nowMs?: number): number;
+/** Test helper: purge the entire outbox. */
+export declare function __clearUnresolvedDelegateForwardOutboxForTests(): void;