instar 0.28.83 → 0.28.85

package/dist/tasks/DivergenceChecker.d.ts

@@ -0,0 +1,89 @@
+/**
+ * DivergenceChecker — TaskFlow Phase 3a state-coherence monitor.
+ *
+ * Runs every 15 minutes during the Phase 3a dual-write window. Compares
+ * EvolutionManager's authoritative JSON state (proposals) against the
+ * TaskFlow registry's flow records on the (ownerKey, status, currentStep,
+ * waitJson.kind) tuple. Emits a `taskflow_divergence_count` metric on every
+ * run and a SharedStateLedger note kind `taskflow-divergence` per mismatch.
+ *
+ * Signal-vs-authority compliance: this is a SIGNAL emitter, never a gate.
+ *   - It does not block any user-facing action.
+ *   - It does not block any agent-internal action.
+ *   - On divergence > 0, it asks EvolutionManager to halt shadow-writes via
+ *     `setShadowWritesHalted(true)`. EvolutionManager continues JSON writes
+ *     uninterrupted; only the secondary TaskFlow shadow-write is paused
+ *     until divergence clears. This is a self-applied brake, not an
+ *     authority decision over user-facing flow.
+ *
+ * Phase 3b cutover requires `divergenceCount == 0` for ≥7 consecutive days
+ * AND ledger contains zero `taskflow-divergence` notes in that window. The
+ * cutover gate is enforced in the Phase 3b PR, not here.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Phase 3a.
+ */
+import type { TaskFlowRegistry } from './TaskFlowRegistry.js';
+import type { EvolutionManager } from '../core/EvolutionManager.js';
+import type { SharedStateLedger } from '../core/SharedStateLedger.js';
+import type { TaskFlowStatus } from './task-flow-types.js';
+import type { EvolutionStatus } from '../core/types.js';
+/** Default cron interval — 15 minutes per spec § Phase 3a. */
+export declare const DIVERGENCE_CHECK_INTERVAL_MS: number;
+export interface DivergenceMismatch {
+    kind: 'json-only' | 'taskflow-only' | 'status-mismatch' | 'step-mismatch' | 'wait-kind-mismatch';
+    ownerKey: string;
+    proposalId?: string;
+    flowId?: string;
+    proposalStatus?: EvolutionStatus;
+    flowStatus?: TaskFlowStatus;
+    expectedStep?: string;
+    actualStep?: string;
+    expectedWaitKind?: string | null;
+    actualWaitKind?: string | null;
+}
+export interface DivergenceReport {
+    scannedJsonProposals: number;
+    scannedTaskFlowRecords: number;
+    divergenceCount: number;
+    mismatches: DivergenceMismatch[];
+    checkedAt: string;
+}
+export interface DivergenceCheckerOptions {
+    registry: TaskFlowRegistry;
+    evolutionManager: EvolutionManager;
+    ledger?: SharedStateLedger;
+    intervalMs?: number;
+    now?: () => number;
+}
+export declare class DivergenceChecker {
+    private timer;
+    private readonly registry;
+    private readonly evolutionManager;
+    private readonly ledger?;
+    private readonly intervalMs;
+    private readonly now;
+    /** Most recent divergence count; readable by /health probes. */
+    divergenceCount: number;
+    /** Wall-clock of the most recent runOnce(). null until first run. */
+    lastCheckAt: string | null;
+    /** The most recent report, kept for /health and test assertions. */
+    lastReport: DivergenceReport | null;
+    constructor(opts: DivergenceCheckerOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * Single-pass divergence scan. Idempotent; safe to call as often as desired.
+     *
+     * Returns the report. Side effects:
+     *   1. Updates `divergenceCount` / `lastCheckAt` / `lastReport`.
+     *   2. Emits a SharedStateLedger note per mismatch (kind: 'note',
+     *      subject: 'taskflow-divergence').
+     *   3. Calls `evolutionManager.setShadowWritesHalted(...)`:
+     *        divergenceCount > 0 → halted=true
+     *        divergenceCount == 0 → halted=false (resume shadow-writes)
+     */
+    runOnce(): Promise<DivergenceReport>;
+    private emitMetric;
+    private emitLedgerNote;
+}
+//# sourceMappingURL=DivergenceChecker.d.ts.map

package/dist/tasks/DivergenceChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DivergenceChecker.d.ts","sourceRoot":"","sources":["../../src/tasks/DivergenceChecker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAAqB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE3E,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAI3D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EACA,WAAW,GACX,eAAe,GACf,iBAAiB,GACjB,eAAe,GACf,oBAAoB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAsCD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,gEAAgE;IAChE,eAAe,SAAK;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAClC,oEAAoE;IACpE,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAQ;gBAE/B,IAAI,EAAE,wBAAwB;IAQ1C,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IAOZ;;;;;;;;;;OAUG;IACG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA0H1C,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,cAAc;CA4BvB"}

package/dist/tasks/DivergenceChecker.js

@@ -0,0 +1,255 @@
+/**
+ * DivergenceChecker — TaskFlow Phase 3a state-coherence monitor.
+ *
+ * Runs every 15 minutes during the Phase 3a dual-write window. Compares
+ * EvolutionManager's authoritative JSON state (proposals) against the
+ * TaskFlow registry's flow records on the (ownerKey, status, currentStep,
+ * waitJson.kind) tuple. Emits a `taskflow_divergence_count` metric on every
+ * run and a SharedStateLedger note kind `taskflow-divergence` per mismatch.
+ *
+ * Signal-vs-authority compliance: this is a SIGNAL emitter, never a gate.
+ *   - It does not block any user-facing action.
+ *   - It does not block any agent-internal action.
+ *   - On divergence > 0, it asks EvolutionManager to halt shadow-writes via
+ *     `setShadowWritesHalted(true)`. EvolutionManager continues JSON writes
+ *     uninterrupted; only the secondary TaskFlow shadow-write is paused
+ *     until divergence clears. This is a self-applied brake, not an
+ *     authority decision over user-facing flow.
+ *
+ * Phase 3b cutover requires `divergenceCount == 0` for ≥7 consecutive days
+ * AND ledger contains zero `taskflow-divergence` notes in that window. The
+ * cutover gate is enforced in the Phase 3b PR, not here.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Phase 3a.
+ */
+/** Default cron interval — 15 minutes per spec § Phase 3a. */
+export const DIVERGENCE_CHECK_INTERVAL_MS = 15 * 60 * 1000;
+const CONTROLLER_ID = 'EvolutionManager';
+/**
+ * Status mapping — what TaskFlow status corresponds to a given proposal status?
+ * Single source of truth shared with EvolutionManager's dual-write logic.
+ *
+ * `null` means "ignore this proposal during divergence checks" — used for
+ * pre-Phase-3a JSON-only records that have not yet been backfilled.
+ */
+function expectedFlowStatusFor(p) {
+    switch (p) {
+        case 'proposed':
+            return 'queued';
+        case 'approved':
+        case 'in_progress':
+            return 'running';
+        case 'implemented':
+            return 'succeeded';
+        case 'rejected':
+            return 'failed';
+        case 'deferred':
+            return 'cancelled';
+        default:
+            return null;
+    }
+}
+function expectedStepFor(p) {
+    switch (p) {
+        case 'approved':
+            return 'approved';
+        case 'in_progress':
+            return 'in_progress';
+        default:
+            return null;
+    }
+}
+export class DivergenceChecker {
+    timer = null;
+    registry;
+    evolutionManager;
+    ledger;
+    intervalMs;
+    now;
+    /** Most recent divergence count; readable by /health probes. */
+    divergenceCount = 0;
+    /** Wall-clock of the most recent runOnce(). null until first run. */
+    lastCheckAt = null;
+    /** The most recent report, kept for /health and test assertions. */
+    lastReport = null;
+    constructor(opts) {
+        this.registry = opts.registry;
+        this.evolutionManager = opts.evolutionManager;
+        this.ledger = opts.ledger;
+        this.intervalMs = opts.intervalMs ?? DIVERGENCE_CHECK_INTERVAL_MS;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.runOnce().catch(() => {
+                /* swallow — divergence checking is best-effort */
+            });
+        }, this.intervalMs);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Single-pass divergence scan. Idempotent; safe to call as often as desired.
+     *
+     * Returns the report. Side effects:
+     *   1. Updates `divergenceCount` / `lastCheckAt` / `lastReport`.
+     *   2. Emits a SharedStateLedger note per mismatch (kind: 'note',
+     *      subject: 'taskflow-divergence').
+     *   3. Calls `evolutionManager.setShadowWritesHalted(...)`:
+     *        divergenceCount > 0 → halted=true
+     *        divergenceCount == 0 → halted=false (resume shadow-writes)
+     */
+    async runOnce() {
+        const checkedAt = new Date(this.now()).toISOString();
+        // Read JSON-side proposals via the public API.
+        const proposals = this.evolutionManager.listProposals();
+        const flowRecs = this.registry.findByControllerId(CONTROLLER_ID);
+        const mismatches = [];
+        const flowByOwnerKey = new Map();
+        for (const f of flowRecs)
+            flowByOwnerKey.set(f.ownerKey, f);
+        const jsonByOwnerKey = new Map();
+        for (const p of proposals) {
+            jsonByOwnerKey.set(`evolution:cluster:${p.id}`, p);
+        }
+        // Forward scan: JSON → TaskFlow.
+        for (const p of proposals) {
+            const ownerKey = `evolution:cluster:${p.id}`;
+            const flow = flowByOwnerKey.get(ownerKey);
+            if (!flow) {
+                mismatches.push({
+                    kind: 'json-only',
+                    ownerKey,
+                    proposalId: p.id,
+                    proposalStatus: p.status,
+                });
+                continue;
+            }
+            const expectedStatus = expectedFlowStatusFor(p.status);
+            if (expectedStatus !== null && flow.status !== expectedStatus) {
+                mismatches.push({
+                    kind: 'status-mismatch',
+                    ownerKey,
+                    proposalId: p.id,
+                    flowId: flow.flowId,
+                    proposalStatus: p.status,
+                    flowStatus: flow.status,
+                });
+            }
+            const expectedStep = expectedStepFor(p.status);
+            if (expectedStep !== null && flow.currentStep !== expectedStep) {
+                mismatches.push({
+                    kind: 'step-mismatch',
+                    ownerKey,
+                    proposalId: p.id,
+                    flowId: flow.flowId,
+                    expectedStep,
+                    actualStep: flow.currentStep,
+                });
+            }
+            // Wait-kind: Phase 3a does not yet use TaskFlow waits for proposals,
+            // so any waitJson on the flow is itself a divergence signal.
+            if (flow.waitJson) {
+                mismatches.push({
+                    kind: 'wait-kind-mismatch',
+                    ownerKey,
+                    proposalId: p.id,
+                    flowId: flow.flowId,
+                    expectedWaitKind: null,
+                    actualWaitKind: flow.waitJson.kind,
+                });
+            }
+        }
+        // Reverse scan: TaskFlow → JSON.
+        for (const f of flowRecs) {
+            if (!jsonByOwnerKey.has(f.ownerKey)) {
+                mismatches.push({
+                    kind: 'taskflow-only',
+                    ownerKey: f.ownerKey,
+                    flowId: f.flowId,
+                    flowStatus: f.status,
+                });
+            }
+        }
+        const report = {
+            scannedJsonProposals: proposals.length,
+            scannedTaskFlowRecords: flowRecs.length,
+            divergenceCount: mismatches.length,
+            mismatches,
+            checkedAt,
+        };
+        this.divergenceCount = report.divergenceCount;
+        this.lastCheckAt = checkedAt;
+        this.lastReport = report;
+        // Emit metric counter — surfaced via /health and ledger-stats.
+        this.emitMetric('taskflow_divergence_count', report.divergenceCount, {
+            controllerId: CONTROLLER_ID,
+            checkedAt,
+        });
+        // Emit one ledger note per mismatch (capped at 50 per pass to bound spam).
+        const noteLimit = 50;
+        for (const m of report.mismatches.slice(0, noteLimit)) {
+            this.emitLedgerNote(m, checkedAt);
+        }
+        // Signal-consumed brake — flip EvolutionManager's shadow-write switch.
+        // Tag the halt with our identity so a manual halt by an operator survives
+        // until that operator clears it. Auto-resume only clears halts we set.
+        if (report.divergenceCount > 0) {
+            this.evolutionManager.setShadowWritesHalted(true, `taskflow-divergence: ${report.divergenceCount} mismatch(es) at ${checkedAt}`, 'divergence-checker');
+        }
+        else {
+            const cur = this.evolutionManager.isShadowWritesHalted();
+            if (cur.halted && cur.source === 'divergence-checker') {
+                this.evolutionManager.setShadowWritesHalted(false);
+            }
+        }
+        return report;
+    }
+    // ── private helpers ──────────────────────────────────────────────
+    emitMetric(name, value, labels) {
+        // Lightweight surface — instar's metrics are emitted via console.log
+        // tagged lines that the dashboard scrapes; structured JSON keeps the
+        // line greppable. If a metric backend is wired later, this is the seam.
+        try {
+            console.log(`[metric] ${name}=${value} ${JSON.stringify(labels)}`);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    emitLedgerNote(m, checkedAt) {
+        if (!this.ledger)
+            return;
+        void Promise.resolve()
+            .then(() => this.ledger.append({
+            kind: 'note',
+            provenance: 'subsystem-asserted',
+            emittedBy: {
+                subsystem: 'taskflow-divergence',
+                instance: 'DivergenceChecker',
+            },
+            counterparty: { type: 'self', name: 'EvolutionManager', trustTier: 'trusted' },
+            subject: 'taskflow-divergence',
+            summary: `${m.kind}: ownerKey=${m.ownerKey} ` +
+                (m.proposalId ? `proposalId=${m.proposalId} ` : '') +
+                (m.flowId ? `flowId=${m.flowId} ` : '') +
+                (m.proposalStatus ? `proposalStatus=${m.proposalStatus} ` : '') +
+                (m.flowStatus ? `flowStatus=${m.flowStatus} ` : '') +
+                (m.expectedStep !== undefined ? `expectedStep=${m.expectedStep ?? 'none'} actualStep=${m.actualStep ?? 'none'} ` : '') +
+                (m.expectedWaitKind !== undefined ? `expectedWaitKind=${m.expectedWaitKind ?? 'none'} actualWaitKind=${m.actualWaitKind ?? 'none'}` : ''),
+            dedupKey: `taskflow-divergence:${m.kind}:${m.ownerKey}:${checkedAt}`,
+        }))
+            .catch(() => {
+            /* swallow — best-effort */
+        });
+    }
+}
+//# sourceMappingURL=DivergenceChecker.js.map

package/dist/tasks/DivergenceChecker.js.map

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

package/dist/tasks/LruCache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LruCache — bounded LRU for TaskFlowRegistry.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Phase 5 line 652
+ * ("LRU cache eviction tuning").
+ *
+ * Implementation: leans on JavaScript Map's insertion-order iteration. On `get`
+ * we delete-then-set to refresh recency. On `set` overflow we evict the oldest
+ * key (Map iterator first). Eviction count is exposed for metric emission.
+ */
+export interface LruCacheOptions<V> {
+    maxEntries: number;
+    /** Optional eviction observer for metric emission. */
+    onEvict?: (key: string, value: V) => void;
+}
+export declare class LruCache<V> {
+    private maxEntries;
+    private readonly map;
+    private readonly onEvict?;
+    private evictions;
+    constructor(opts: LruCacheOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    get size(): number;
+    get evictionCount(): number;
+    /** Test-only: iterate keys in LRU order (oldest first). */
+    keysInOrder(): string[];
+    /** Resize cap; immediately evict overflow if shrinking. */
+    setMaxEntries(n: number): void;
+}
+//# sourceMappingURL=LruCache.d.ts.map

package/dist/tasks/LruCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LruCache.d.ts","sourceRoot":"","sources":["../../src/tasks/LruCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC3C;AAED,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkC;IAC3D,OAAO,CAAC,SAAS,CAAK;gBAEV,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC;IAKpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAS/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAqBhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,2DAA2D;IAC3D,WAAW,IAAI,MAAM,EAAE;IAIvB,2DAA2D;IAC3D,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;CAa/B"}

package/dist/tasks/LruCache.js

@@ -0,0 +1,88 @@
+/**
+ * LruCache — bounded LRU for TaskFlowRegistry.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Phase 5 line 652
+ * ("LRU cache eviction tuning").
+ *
+ * Implementation: leans on JavaScript Map's insertion-order iteration. On `get`
+ * we delete-then-set to refresh recency. On `set` overflow we evict the oldest
+ * key (Map iterator first). Eviction count is exposed for metric emission.
+ */
+export class LruCache {
+    maxEntries;
+    map = new Map();
+    onEvict;
+    evictions = 0;
+    constructor(opts) {
+        this.maxEntries = Math.max(0, opts.maxEntries | 0);
+        this.onEvict = opts.onEvict;
+    }
+    get(key) {
+        const v = this.map.get(key);
+        if (v === undefined)
+            return undefined;
+        // refresh recency: re-insert at tail.
+        this.map.delete(key);
+        this.map.set(key, v);
+        return v;
+    }
+    set(key, value) {
+        if (this.maxEntries <= 0) {
+            // disabled — no caching.
+            return;
+        }
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        this.map.set(key, value);
+        while (this.map.size > this.maxEntries) {
+            const firstKey = this.map.keys().next().value;
+            if (!firstKey)
+                break;
+            const v = this.map.get(firstKey);
+            this.map.delete(firstKey);
+            this.evictions++;
+            if (this.onEvict) {
+                try {
+                    this.onEvict(firstKey, v);
+                }
+                catch { /* swallow */ }
+            }
+        }
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    get size() {
+        return this.map.size;
+    }
+    get evictionCount() {
+        return this.evictions;
+    }
+    /** Test-only: iterate keys in LRU order (oldest first). */
+    keysInOrder() {
+        return Array.from(this.map.keys());
+    }
+    /** Resize cap; immediately evict overflow if shrinking. */
+    setMaxEntries(n) {
+        this.maxEntries = Math.max(0, n | 0);
+        while (this.map.size > this.maxEntries) {
+            const firstKey = this.map.keys().next().value;
+            if (!firstKey)
+                break;
+            const v = this.map.get(firstKey);
+            this.map.delete(firstKey);
+            this.evictions++;
+            if (this.onEvict) {
+                try {
+                    this.onEvict(firstKey, v);
+                }
+                catch { /* swallow */ }
+            }
+        }
+    }
+}
+//# sourceMappingURL=LruCache.js.map

package/dist/tasks/LruCache.js.map

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

package/dist/tasks/RateLimiter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RateLimiter — sliding-window rate limiter for TaskFlow Phase 5.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Threat Model lines 679, 685.
+ *
+ * Design notes:
+ * - Per-key sliding window with monotonic clock injection (defaults to Date.now).
+ * - Buckets are pruned lazily on each `tryAcquire` to avoid an unref'd timer
+ *   purely for cleanup. A bucket whose window is fully in the past is dropped
+ *   on its next visit, and an O(N) sweep prunes stale entries every
+ *   PRUNE_EVERY_N acquisitions to bound memory under fan-out scenarios.
+ * - `Infinity` limit means "disabled" (always allow, no bookkeeping).
+ * - Returns retryAfterMs as the time until the oldest in-window timestamp ages
+ *   out. This is the spec-required retry hint surfaced to HTTP 429.
+ *
+ * Threat-model coverage:
+ * - Sliding window (not fixed window) — bursts at second boundaries cannot
+ *   double the effective rate. Clock skew on a single-writer server is bounded
+ *   by `now()` monotonicity; the limiter does not rely on wall-clock.
+ * - Per-key isolation prevents one noisy controller from starving others.
+ */
+export interface RateLimiterOptions {
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Max events permitted within a single window. Use Infinity to disable. */
+    limit: number;
+    /** Injected clock for tests; defaults to Date.now. */
+    now?: () => number;
+}
+export interface AcquireResult {
+    ok: boolean;
+    /** ms until the oldest in-window timestamp ages out (only set when !ok). */
+    retryAfterMs?: number;
+    /** current count in window after this call (for tests/metrics). */
+    currentCount?: number;
+}
+export declare class RateLimiter {
+    private readonly windowMs;
+    private readonly limit;
+    private readonly now;
+    private readonly buckets;
+    private acquireCount;
+    constructor(opts: RateLimiterOptions);
+    /**
+     * Attempt to acquire one slot for `key`. Returns ok=false with retryAfterMs
+     * when the per-key limit is exceeded.
+     *
+     * Note: this method is reentrancy-safe within a single-threaded event loop
+     * (Node.js) but is NOT designed for shared-memory concurrent callers. The
+     * TaskFlow server is a single-writer process by design.
+     */
+    tryAcquire(key: string): AcquireResult;
+    /** Forget a key entirely. Used when an entity is deleted (e.g. flow goes terminal). */
+    forget(key: string): void;
+    /** Test/debug — current bucket size for key. */
+    countFor(key: string): number;
+    /** Total number of keys currently tracked. */
+    size(): number;
+    private maybePrune;
+}
+//# sourceMappingURL=RateLimiter.d.ts.map

package/dist/tasks/RateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../src/tasks/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,YAAY,CAAK;gBAEb,IAAI,EAAE,kBAAkB;IAMpC;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IA+BtC,uFAAuF;IACvF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAU7B,8CAA8C;IAC9C,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,UAAU;CAUnB"}

package/dist/tasks/RateLimiter.js

@@ -0,0 +1,108 @@
+/**
+ * RateLimiter — sliding-window rate limiter for TaskFlow Phase 5.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md § Threat Model lines 679, 685.
+ *
+ * Design notes:
+ * - Per-key sliding window with monotonic clock injection (defaults to Date.now).
+ * - Buckets are pruned lazily on each `tryAcquire` to avoid an unref'd timer
+ *   purely for cleanup. A bucket whose window is fully in the past is dropped
+ *   on its next visit, and an O(N) sweep prunes stale entries every
+ *   PRUNE_EVERY_N acquisitions to bound memory under fan-out scenarios.
+ * - `Infinity` limit means "disabled" (always allow, no bookkeeping).
+ * - Returns retryAfterMs as the time until the oldest in-window timestamp ages
+ *   out. This is the spec-required retry hint surfaced to HTTP 429.
+ *
+ * Threat-model coverage:
+ * - Sliding window (not fixed window) — bursts at second boundaries cannot
+ *   double the effective rate. Clock skew on a single-writer server is bounded
+ *   by `now()` monotonicity; the limiter does not rely on wall-clock.
+ * - Per-key isolation prevents one noisy controller from starving others.
+ */
+const PRUNE_EVERY_N = 256;
+const MAX_BUCKETS = 50_000;
+export class RateLimiter {
+    windowMs;
+    limit;
+    now;
+    buckets = new Map();
+    acquireCount = 0;
+    constructor(opts) {
+        this.windowMs = opts.windowMs;
+        this.limit = opts.limit;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Attempt to acquire one slot for `key`. Returns ok=false with retryAfterMs
+     * when the per-key limit is exceeded.
+     *
+     * Note: this method is reentrancy-safe within a single-threaded event loop
+     * (Node.js) but is NOT designed for shared-memory concurrent callers. The
+     * TaskFlow server is a single-writer process by design.
+     */
+    tryAcquire(key) {
+        if (!isFinite(this.limit) || this.limit <= 0) {
+            // limit=0 also degenerate; treat as disabled for safety. The route layer
+            // is the place to reject if a sane minimum is required.
+            if (this.limit === 0) {
+                return { ok: false, retryAfterMs: this.windowMs, currentCount: 0 };
+            }
+            return { ok: true, currentCount: 0 };
+        }
+        const ts = this.now();
+        const windowStart = ts - this.windowMs;
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = [];
+            this.buckets.set(key, bucket);
+        }
+        // Drop in-place from the head while expired. Sliding window.
+        while (bucket.length > 0 && bucket[0] <= windowStart) {
+            bucket.shift();
+        }
+        if (bucket.length >= this.limit) {
+            const oldest = bucket[0];
+            const retryAfterMs = Math.max(0, oldest + this.windowMs - ts);
+            this.maybePrune(ts);
+            return { ok: false, retryAfterMs, currentCount: bucket.length };
+        }
+        bucket.push(ts);
+        this.maybePrune(ts);
+        return { ok: true, currentCount: bucket.length };
+    }
+    /** Forget a key entirely. Used when an entity is deleted (e.g. flow goes terminal). */
+    forget(key) {
+        this.buckets.delete(key);
+    }
+    /** Test/debug — current bucket size for key. */
+    countFor(key) {
+        const b = this.buckets.get(key);
+        if (!b)
+            return 0;
+        const ts = this.now();
+        const windowStart = ts - this.windowMs;
+        let n = 0;
+        for (const x of b)
+            if (x > windowStart)
+                n++;
+        return n;
+    }
+    /** Total number of keys currently tracked. */
+    size() {
+        return this.buckets.size;
+    }
+    maybePrune(ts) {
+        this.acquireCount++;
+        if (this.acquireCount < PRUNE_EVERY_N && this.buckets.size < MAX_BUCKETS)
+            return;
+        this.acquireCount = 0;
+        const windowStart = ts - this.windowMs;
+        for (const [k, b] of this.buckets) {
+            while (b.length > 0 && b[0] <= windowStart)
+                b.shift();
+            if (b.length === 0)
+                this.buckets.delete(k);
+        }
+    }
+}
+//# sourceMappingURL=RateLimiter.js.map