@harrylabsj/kiwi 0.6.0

package/dist/agent/buyer/scheduler.js

@@ -0,0 +1,317 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ConnectorError } from "../connector/types.js";
+import { observationHash, runSearchCycle } from "./search-loop.js";
+import { BuyerTaskError } from "./types.js";
+const DEFAULT_BUDGET = { max_requests: 20, max_rules: 50, max_tasks: 5 };
+export class TaskScheduler {
+    store;
+    connectors;
+    now;
+    constructor(options) {
+        this.store = options.store;
+        this.connectors = new Map(options.connectors.map((c) => [c.connector_id, c]));
+        const clock = options.now ?? (() => new Date().toISOString());
+        this.now = () => new Date(Date.parse(clock())).toISOString();
+    }
+    connectorFor(candidateConnectorId) {
+        return this.connectors.get(candidateConnectorId);
+    }
+    async tick(budget = {}) {
+        const b = { ...DEFAULT_BUDGET, ...budget };
+        const now = this.now();
+        const result = {
+            checked_rules: 0,
+            notifications: [],
+            tasks_searched: [],
+            tasks_expired: [],
+            errors: [],
+        };
+        let requests = 0;
+        // 1. Expire tracking tasks past their deadline (§11.3: tracking -> expired).
+        for (const task of this.store.expirableTasks(now)) {
+            try {
+                this.store.transitionTask({
+                    task_id: task.task_id,
+                    to: "expired",
+                    expected_version: task.version,
+                    event_type: "expired",
+                    origin: "scheduler",
+                    idempotency_key: `expire:${task.task_id}:${task.expires_at ?? now}`,
+                });
+                result.tasks_expired.push(task.task_id);
+            }
+            catch (err) {
+                result.errors.push(`expire ${task.task_id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // 2. Due tracking rules, grouped by candidate (merged observe+notify).
+        const due = this.store.dueRules(now, b.max_rules);
+        const byCandidate = new Map();
+        const taskLevel = [];
+        for (const rule of due) {
+            if (rule.candidate_id === undefined)
+                taskLevel.push(rule);
+            else {
+                const group = byCandidate.get(rule.candidate_id) ?? [];
+                group.push(rule);
+                byCandidate.set(rule.candidate_id, group);
+            }
+        }
+        for (const [candidateId, rules] of byCandidate) {
+            if (requests >= b.max_requests)
+                break;
+            const candidate = this.store.getCandidate(candidateId);
+            if (candidate === undefined || candidate.sku === undefined) {
+                for (const rule of rules)
+                    this.store.markRuleChecked(rule.rule_id, false, now);
+                continue;
+            }
+            const connector = this.connectorFor(candidate.connector_id);
+            if (connector === undefined) {
+                result.errors.push(`no connector ${candidate.connector_id} for candidate ${candidateId}`);
+                continue;
+            }
+            let observation;
+            requests += 1;
+            // §11.7: observation freshness TTL comes from the task's tracking
+            // policy, not a hardcoded 30 minutes.
+            const task = this.store.getTask(candidate.task_id);
+            const ttlSeconds = task?.tracking_policy.observation_ttl_seconds ?? 1800;
+            try {
+                const product = await connector.getProduct(candidate.sku);
+                const added = this.store.addObservation({
+                    candidate_id: candidateId,
+                    observed_at: now,
+                    source_url_or_ref: `shopping-cli:/products/${product.sku}`,
+                    title: product.title,
+                    price: {
+                        list: product.price,
+                        currency: product.currency,
+                        delivery_fee: product.delivery.fee,
+                    },
+                    promotion: {},
+                    stock: { quantity: product.stock, observed_at: now },
+                    delivery: { ...product.delivery },
+                    after_sales: {},
+                    merchant: {
+                        id: product.merchant.id,
+                        name: product.merchant.name,
+                        city: product.merchant.city,
+                        warnings: product.warnings,
+                    },
+                    content_hash: observationHash(product),
+                    fresh_until: new Date(Date.parse(now) + ttlSeconds * 1000).toISOString(),
+                });
+                if (added.added) {
+                    this.store.updateCandidate(candidateId, { latest_observation_id: added.observation_id });
+                }
+                observation = this.store.latestObservation(candidateId);
+            }
+            catch (err) {
+                // §18.2: a failed read never reuses stale facts; reschedule and report.
+                result.errors.push(`observe ${candidateId}: ${err instanceof Error ? err.message : String(err)}`);
+                for (const rule of rules)
+                    this.store.markRuleChecked(rule.rule_id, false, now);
+                continue;
+            }
+            if (observation === undefined)
+                continue;
+            const previous = this.store.observations(candidateId, 2)[1];
+            const triggered = [];
+            for (const rule of rules) {
+                result.checked_rules += 1;
+                const inCooldown = rule.cooldown_seconds > 0 &&
+                    rule.last_triggered_at !== undefined &&
+                    Date.parse(rule.last_triggered_at) + rule.cooldown_seconds * 1000 > Date.parse(now);
+                const reason = inCooldown ? undefined : evaluateRule(rule, observation, previous, now);
+                if (reason !== undefined) {
+                    triggered.push({ rule, reason });
+                    this.store.markRuleChecked(rule.rule_id, true, now);
+                }
+                else {
+                    this.store.markRuleChecked(rule.rule_id, false, now);
+                }
+            }
+            if (triggered.length > 0) {
+                // Merged: one notification per candidate per observation (§11.7). The
+                // event is keyed by observation_id, so an unchanged fact re-triggering
+                // after cooldown does NOT surface a duplicate notification.
+                const summary = triggered.map((t) => t.reason).join("；");
+                const inserted = this.store.appendEvent(rules[0]?.task_id ?? "", "notification", {
+                    candidate_id: candidateId,
+                    rule_ids: triggered.map((t) => t.rule.rule_id),
+                    summary,
+                }, "scheduler", `notify:${candidateId}:${observation.observation_id}`);
+                if (inserted) {
+                    result.notifications.push({
+                        task_id: rules[0]?.task_id ?? "",
+                        candidate_id: candidateId,
+                        summary,
+                        rule_ids: triggered.map((t) => t.rule.rule_id),
+                    });
+                }
+            }
+        }
+        // 3. Task-level rules (periodic_review / price_below / stock_available)
+        //    queue a re-search. 求值在重搜索之后（第 5 步）——任务级规则针对的是
+        //    "任务任一候选满足条件"（如默认 price_below 阈值），必须基于本 tick
+        //    重搜索产生的新鲜观察，否则条件形同虚设（评审项 H5：此前只
+        //    markRuleChecked，条件从未被求值，承诺的"降价/到货通知"静默失效）。
+        const searchQueue = new Map();
+        for (const rule of taskLevel) {
+            const task = this.store.getTask(rule.task_id);
+            if (task !== undefined && task.status === "tracking") {
+                searchQueue.set(task.task_id, task);
+            }
+            else {
+                // 不重搜的任务：仅推进检查时间，避免每 tick 重复入队。
+                result.checked_rules += 1;
+                this.store.markRuleChecked(rule.rule_id, true, now);
+            }
+        }
+        // 4. Due task wakeups (restart recovery: everything comes from the DB).
+        for (const task of this.store.dueTasks(now, b.max_tasks)) {
+            searchQueue.set(task.task_id, task);
+        }
+        let searched = 0;
+        for (const task of searchQueue.values()) {
+            if (searched >= b.max_tasks)
+                break;
+            const connector = this.connectorFor(task.connector_scope.connectors[0] ?? "shopping-cli");
+            if (connector === undefined) {
+                result.errors.push(`no connector for task ${task.task_id}`);
+                continue;
+            }
+            searched += 1;
+            try {
+                const before = new Set(this.store.listCandidates(task.task_id).map((c) => c.canonical_key));
+                const cycle = await runSearchCycle({ store: this.store, connector, now: this.now }, task.task_id, `tick:${task.task_id}:${now}`);
+                result.tasks_searched.push(task.task_id);
+                if (cycle.outcome === "retry" && cycle.error !== undefined) {
+                    // §18.1 transient failure: runSearchCycle parked the task with a
+                    // scheduled retry but did NOT throw. Surface it in tick errors so
+                    // the chat/model can see the task is retrying — otherwise a
+                    // persistently down gateway looks like a silently stalled task.
+                    result.errors.push(`search ${task.task_id}: ${cycle.error}（已安排自动重试）`);
+                }
+                const newOnes = this.store
+                    .listCandidates(task.task_id)
+                    .filter((c) => !before.has(c.canonical_key));
+                if (newOnes.length > 0) {
+                    const inserted = this.store.appendEvent(task.task_id, "notification", {
+                        summary: `发现 ${newOnes.length} 个新候选`,
+                        new_candidates: newOnes.map((c) => c.candidate_id),
+                    }, "scheduler", `notify:${task.task_id}:new:${now}`);
+                    if (inserted) {
+                        result.notifications.push({
+                            task_id: task.task_id,
+                            summary: `发现 ${newOnes.length} 个新候选`,
+                            rule_ids: [],
+                        });
+                    }
+                }
+                void cycle;
+            }
+            catch (err) {
+                if (err instanceof BuyerTaskError || err instanceof ConnectorError) {
+                    result.errors.push(`search ${task.task_id}: ${err.message}`);
+                }
+                else {
+                    result.errors.push(`search ${task.task_id}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        // 5. Task-level rules evaluated against this tick's fresh observations
+        //    （评审项 H5 修复）：只对本 tick 实际重搜过的任务求值——重搜写入了
+        //    新观察，规则看到的是当前事实。任一候选满足条件即触发（任务级
+        //    price_below 的阈值是全任务预算；stock_available 同理）。通知按
+        //    (task_id, rule_id, 触发观察) 去重——观察未变时不重复打扰用户。
+        const searchedTasks = new Set(result.tasks_searched);
+        for (const rule of taskLevel) {
+            if (!searchedTasks.has(rule.task_id))
+                continue;
+            const task = this.store.getTask(rule.task_id);
+            if (task === undefined)
+                continue;
+            result.checked_rules += 1;
+            let triggeredReason;
+            let triggerObservationId;
+            for (const candidate of this.store.listCandidates(rule.task_id)) {
+                if (candidate.sku === undefined)
+                    continue;
+                const observation = this.store.latestObservation(candidate.candidate_id);
+                if (observation === undefined)
+                    continue;
+                const previous = this.store.observations(candidate.candidate_id, 2)[1];
+                const inCooldown = rule.cooldown_seconds > 0 &&
+                    rule.last_triggered_at !== undefined &&
+                    Date.parse(rule.last_triggered_at) + rule.cooldown_seconds * 1000 > Date.parse(now);
+                const reason = inCooldown ? undefined : evaluateRule(rule, observation, previous, now);
+                if (reason !== undefined) {
+                    triggeredReason = reason;
+                    triggerObservationId = observation.observation_id;
+                    break;
+                }
+            }
+            if (triggeredReason === undefined || triggerObservationId === undefined) {
+                this.store.markRuleChecked(rule.rule_id, false, now);
+                continue;
+            }
+            this.store.markRuleChecked(rule.rule_id, true, now);
+            const inserted = this.store.appendEvent(rule.task_id, "notification", {
+                rule_ids: [rule.rule_id],
+                summary: triggeredReason,
+            }, "scheduler", `notify:${rule.task_id}:${rule.rule_id}:${triggerObservationId}`);
+            if (inserted) {
+                result.notifications.push({
+                    task_id: rule.task_id,
+                    summary: triggeredReason,
+                    rule_ids: [rule.rule_id],
+                });
+            }
+        }
+        return result;
+    }
+}
+/** Evaluate one rule against the latest facts. Returns a reason when triggered. */
+function evaluateRule(rule, latest, previous, now) {
+    switch (rule.rule_type) {
+        case "price_below": {
+            const threshold = Number(rule.condition.threshold);
+            if (!Number.isFinite(threshold))
+                return undefined;
+            const total = latest.price.list + latest.price.delivery_fee;
+            return total <= threshold
+                ? `到手价 ${total} ${latest.price.currency} 已低于 ${threshold}`
+                : undefined;
+        }
+        case "stock_available":
+            return latest.stock.quantity > 0 ? `已到货（库存 ${latest.stock.quantity}）` : undefined;
+        case "delivery_before": {
+            const before = typeof rule.condition.eta_before === "string" ? rule.condition.eta_before : "";
+            if (before === "")
+                return undefined;
+            const etaMinutes = Number(latest.delivery.eta_minutes ?? 0);
+            return Date.parse(now) + etaMinutes * 60_000 <= Date.parse(before)
+                ? `可在 ${before} 前送达`
+                : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/agent/buyer/scheduler.js.map

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

package/dist/agent/buyer/search-loop.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { CommerceConnector, ConnectorProduct } from "../connector/types.js";
+import type { BuyerTaskStore } from "./task-store.js";
+import type { BuyerTask, ProductCandidate, ProductObservation } from "./types.js";
+export interface SearchCycleDeps {
+    store: BuyerTaskStore;
+    connector: CommerceConnector;
+    now: () => string;
+}
+export interface ShortlistEntry {
+    candidate: ProductCandidate;
+    observation?: ProductObservation;
+}
+export interface SearchCycleResult {
+    task: BuyerTask;
+    /** `retry` = transient connector error, task parked for a scheduled retry. */
+    outcome: "shortlist_ready" | "tracking" | "failed" | "retry";
+    shortlist: ShortlistEntry[];
+    error?: string;
+}
+/**
+ * Content-hash over the assertion-relevant facts (§11.6 dedup). Includes
+ * delivery ETA so a changed delivery promise produces a NEW observation
+ * instead of being silently deduped away (which would keep `delivery_before`
+ * rules and the delivery dimension evaluating stale ETAs).
+ */
+export declare function observationHash(product: ConnectorProduct): string;
+export declare function runSearchCycle(deps: SearchCycleDeps, taskId: string, runId: string): Promise<SearchCycleResult>;

package/dist/agent/buyer/search-loop.js

@@ -0,0 +1,280 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Buyer search execution loop (design §13):
+ * ready -> searching -> (shortlist_ready -> awaiting_user | tracking).
+ *
+ * Every run has a run_id; every event carries an idempotency key derived
+ * from it, so a retried run never double-writes. Transitions are
+ * version-guarded. Connector failures classify: transient => the task
+ * moves to `failed` with a retriable note (never silently keeps stale
+ * facts, §18.2).
+ */
+import { createHash } from "node:crypto";
+import { ConnectorError } from "../connector/types.js";
+import { hardFilter, scoreCandidate } from "./ranker.js";
+import { BuyerTaskError } from "./types.js";
+/**
+ * Content-hash over the assertion-relevant facts (§11.6 dedup). Includes
+ * delivery ETA so a changed delivery promise produces a NEW observation
+ * instead of being silently deduped away (which would keep `delivery_before`
+ * rules and the delivery dimension evaluating stale ETAs).
+ */
+export function observationHash(product) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        title: product.title,
+        price: product.price,
+        fee: product.delivery.fee,
+        stock: product.stock,
+        eta_minutes: product.delivery.eta_minutes,
+        warnings: product.warnings,
+    }))
+        .digest("hex");
+}
+function toObservation(candidateId, product, now, ttlSeconds) {
+    return {
+        candidate_id: candidateId,
+        observed_at: now,
+        source_url_or_ref: `shopping-cli:/products/${product.sku}`,
+        title: product.title,
+        price: { list: product.price, currency: product.currency, delivery_fee: product.delivery.fee },
+        promotion: {},
+        stock: { quantity: product.stock, observed_at: now },
+        delivery: { ...product.delivery },
+        after_sales: {},
+        merchant: {
+            id: product.merchant.id,
+            name: product.merchant.name,
+            city: product.merchant.city,
+            warnings: product.warnings,
+        },
+        content_hash: observationHash(product),
+        fresh_until: new Date(Date.parse(now) + ttlSeconds * 1000).toISOString(),
+    };
+}
+/** Install default tracking rules from constraints when none are active (§13). */
+function installDefaultRules(deps, task) {
+    const { store } = deps;
+    const active = store.rulesForTask(task.task_id).filter((r) => r.status === "active");
+    if (active.length > 0)
+        return active;
+    const installed = [];
+    const interval = task.tracking_policy.default_interval_seconds;
+    const cooldown = task.tracking_policy.default_cooldown_seconds;
+    if (task.constraints.max_total_price !== undefined) {
+        installed.push(store.addTrackingRule({
+            task_id: task.task_id,
+            rule_type: "price_below",
+            condition: { threshold: task.constraints.max_total_price },
+            interval_seconds: interval,
+            cooldown_seconds: cooldown,
+            idempotency_key: `${task.task_id}:default:price_below`,
+        }));
+    }
+    installed.push(store.addTrackingRule({
+        task_id: task.task_id,
+        rule_type: "stock_available",
+        condition: {},
+        interval_seconds: interval,
+        cooldown_seconds: cooldown,
+        idempotency_key: `${task.task_id}:default:stock_available`,
+    }));
+    installed.push(store.addTrackingRule({
+        task_id: task.task_id,
+        rule_type: "periodic_review",
+        condition: {},
+        interval_seconds: interval,
+        cooldown_seconds: cooldown,
+        idempotency_key: `${task.task_id}:default:periodic_review`,
+    }));
+    return installed;
+}
+export async function runSearchCycle(deps, taskId, runId) {
+    const { store, connector } = deps;
+    // Normalize to UTC ISO (lexicographic timestamp comparisons downstream).
+    const now = () => new Date(Date.parse(deps.now())).toISOString();
+    let task = store.getTask(taskId);
+    if (task === undefined)
+        throw new BuyerTaskError("not_found", `no task ${taskId}`);
+    if (!["ready", "searching", "tracking"].includes(task.status)) {
+        throw new BuyerTaskError("illegal_transition", `task ${taskId} is ${task.status}; search requires ready/searching/tracking`);
+    }
+    // A private budget may be vaulted (max_total_price_vault_ref); resolve it
+    // here so filtering and default rules never see the plaintext value and
+    // never skip the constraint when it lives in the Vault (§11.2).
+    const budget = store.resolveBudget(task.constraints);
+    const effectiveConstraints = budget !== undefined ? { ...task.constraints, max_total_price: budget } : task.constraints;
+    const startedAt = now();
+    // ready/tracking -> searching (idempotent; already-searching = crash resume).
+    if (task.status !== "searching") {
+        task = store.transitionTask({
+            task_id: taskId,
+            to: "searching",
+            expected_version: task.version,
+            event_type: "search_started",
+            origin: "scheduler",
+            idempotency_key: `${runId}:search_started`,
+            // 崩溃恢复 + 防并发重复执行（评审项 H4）：新激活任务的 next_run_at 为
+            // NULL（createTask 时置空、激活 ready 不设置）——searching 转移若保留
+            // NULL，崩溃后 dueTasks（要求 NOT NULL）永不选中该任务，永久卡死且
+            // 无恢复路径（"already-searching = crash resume" 注释此前不成立）。
+            // 置为未来锁定期：正常完成由 tracking/shortlist 转移覆盖该值；崩溃
+            // 后到期即被 dueTasks 重新选中恢复；锁定期内下一 tick 不会重复选中
+            // 同一任务（防并发搜索）。
+            next_run_at: new Date(Date.parse(startedAt) +
+                Math.max(task.tracking_policy.default_interval_seconds, 60) * 1000).toISOString(),
+        });
+    }
+    let products;
+    try {
+        products = await connector.searchProducts({
+            ...(task.intent.query_text !== undefined ? { query: task.intent.query_text } : {}),
+            ...(task.intent.city !== undefined ? { city: task.intent.city } : {}),
+            ...(task.intent.area !== undefined ? { area: task.intent.area } : {}),
+            include_out_of_stock: task.constraints.exclude_out_of_stock === false,
+            limit: task.search_budget.max_candidates,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const retriable = err instanceof ConnectorError && err.kind === "transient";
+        if (retriable) {
+            // §18.1/§13: a transient connector error must not kill the task. Park it
+            // in `tracking` with a scheduled retry (exponential backoff, capped); the
+            // scheduler's dueTasks re-runs it when next_run_at is due.
+            const attempts = store.taskEvents(taskId).filter((e) => e.type === "connector_retry").length + 1;
+            const backoffMs = Math.min(task.tracking_policy.default_interval_seconds * 1000 * 2 ** Math.min(attempts - 1, 5), 6 * 3600 * 1000);
+            const nextRunAt = new Date(Date.parse(startedAt) + backoffMs).toISOString();
+            task = store.transitionTask({
+                task_id: taskId,
+                to: "tracking",
+                expected_version: task.version,
+                event_type: "connector_retry",
+                payload: { error: message, retriable: true, attempts, next_run_at: nextRunAt },
+                origin: "connector",
+                idempotency_key: `${runId}:retry`,
+                next_run_at: nextRunAt,
+            });
+            return { task, outcome: "retry", shortlist: [], error: message };
+        }
+        task = store.transitionTask({
+            task_id: taskId,
+            to: "failed",
+            expected_version: task.version,
+            event_type: "failed",
+            payload: { error: message, retriable: false },
+            origin: "connector",
+            idempotency_key: `${runId}:failed`,
+        });
+        return { task, outcome: "failed", shortlist: [], error: message };
+    }
+    const observations = new Map();
+    const eligible = [];
+    for (const product of products.slice(0, task.search_budget.max_candidates)) {
+        const candidate = store.upsertCandidate({
+            task_id: taskId,
+            connector_id: connector.connector_id,
+            platform: connector.platform,
+            external_product_id: product.sku,
+            sku: product.sku,
+            merchant_id: product.merchant_id,
+        });
+        const obs = store.addObservation(toObservation(candidate.candidate_id, product, startedAt, task.tracking_policy.observation_ttl_seconds));
+        const filter = hardFilter(product, effectiveConstraints, startedAt);
+        const observation = store.latestObservation(candidate.candidate_id);
+        observations.set(product.sku, observation);
+        if (filter.eligible === "ineligible") {
+            store.updateCandidate(candidate.candidate_id, {
+                eligibility: "ineligible",
+                candidate_status: "rejected",
+                rejection_reasons: filter.reasons,
+                ...(obs.added ? { latest_observation_id: obs.observation_id } : {}),
+            });
+            continue;
+        }
+        const { score, explanation } = scoreCandidate(product, {
+            intent: task.intent,
+            policy: task.ranking_policy,
+            now: startedAt,
+            observations,
+        });
+        if (filter.unknowns.length > 0)
+            explanation.stale_facts.push(...filter.unknowns);
+        const updated = store.updateCandidate(candidate.candidate_id, {
+            eligibility: filter.eligible,
+            candidate_status: "tracked",
+            score,
+            score_explanation: explanation,
+            ...(obs.added ? { latest_observation_id: obs.observation_id } : {}),
+        });
+        eligible.push({ candidate: updated, product });
+    }
+    store.appendEvent(taskId, "observation_added", { products: products.length, eligible: eligible.length }, "connector", `${runId}:observations`);
+    eligible.sort((a, b) => (b.candidate.score ?? 0) - (a.candidate.score ?? 0));
+    if (eligible.length > 0) {
+        const top = eligible.slice(0, 3);
+        for (const { candidate } of top) {
+            store.updateCandidate(candidate.candidate_id, { candidate_status: "shortlisted" });
+        }
+        task = store.transitionTask({
+            task_id: taskId,
+            to: "shortlist_ready",
+            expected_version: task.version,
+            event_type: "shortlisted",
+            payload: {
+                candidates: top.map(({ candidate }) => ({
+                    candidate_id: candidate.candidate_id,
+                    sku: candidate.sku,
+                    score: candidate.score,
+                })),
+            },
+            origin: "scheduler",
+            idempotency_key: `${runId}:shortlisted`,
+        });
+        task = store.transitionTask({
+            task_id: taskId,
+            to: "awaiting_user",
+            expected_version: task.version,
+            event_type: "status_changed",
+            origin: "scheduler",
+            idempotency_key: `${runId}:awaiting_user`,
+        });
+        return {
+            task,
+            outcome: "shortlist_ready",
+            shortlist: top.map(({ candidate }) => ({
+                candidate,
+                observation: observations.get(candidate.sku ?? ""),
+            })),
+        };
+    }
+    // Nothing eligible yet: install tracking rules and wait for wakeups.
+    const rules = installDefaultRules(deps, { ...task, constraints: effectiveConstraints });
+    const nextRun = new Date(Date.parse(startedAt) + task.tracking_policy.default_interval_seconds * 1000).toISOString();
+    task = store.transitionTask({
+        task_id: taskId,
+        to: "tracking",
+        expected_version: task.version,
+        event_type: "tracking_installed",
+        payload: { rule_ids: rules.map((r) => r.rule_id) },
+        origin: "scheduler",
+        idempotency_key: `${runId}:tracking`,
+        next_run_at: nextRun,
+    });
+    return { task, outcome: "tracking", shortlist: [] };
+}
+//# sourceMappingURL=search-loop.js.map