@xopcai/xopc 0.0.323 → 0.0.325

package/dist/src/home-intelligence/repository.js

@@ -0,0 +1,495 @@
+import { init_transaction, runSqliteSavepoint } from "../storage/sqlite/transaction.js";
+import { HomeAdvisorSchema, HomeOpportunitySchema } from "../../packages/gateway-contract/src/home.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { HOME_ADVICE_STRATEGY_VERSION, HOME_FEEDBACK_WINDOW_MS, homePatternKey } from "./strategy.js";
+import { randomUUID } from "node:crypto";
+//#region src/home-intelligence/repository.ts
+init_src();
+init_transaction();
+function parseJson(value, fallback) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return fallback;
+	}
+}
+function uniqueReasons(reasons) {
+	return [...new Set(reasons)];
+}
+function ratio(numerator, denominator) {
+	return denominator > 0 ? numerator / denominator : 0;
+}
+function parseOpportunity(row) {
+	return HomeOpportunitySchema.parse({
+		...parseJson(row.content_json, {}),
+		id: row.opportunity_id,
+		revision: row.revision
+	});
+}
+var HomeIntelligenceRepository = class {
+	constructor(db) {
+		this.db = db;
+	}
+	enqueue(principal, input) {
+		return runSqliteSavepoint(this.db, () => {
+			const duplicate = this.db.prepare(`SELECT generation_id FROM home_advice_generations
+        WHERE owner_id = ? AND workspace_id = ? AND idempotency_key = ?`).get(principal.ownerId, principal.workspaceId, input.idempotencyKey);
+			if (duplicate) return {
+				generationId: duplicate.generation_id,
+				created: false
+			};
+			const active = this.db.prepare(`SELECT * FROM home_advice_generations
+        WHERE owner_id = ? AND workspace_id = ?
+          AND status IN ('queued', 'running', 'retry_wait')
+        LIMIT 1`).get(principal.ownerId, principal.workspaceId);
+			if (active) {
+				const reasons = uniqueReasons([...parseJson(active.reasons_json, []), ...input.reasons]);
+				this.db.prepare(`UPDATE home_advice_generations SET
+          reasons_json = ?, requested_at = MAX(requested_at, ?),
+          dirty_after_start = CASE WHEN status = 'running' THEN 1 ELSE dirty_after_start END
+          WHERE generation_id = ?`).run(JSON.stringify(reasons), input.requestedAt, active.generation_id);
+				return {
+					generationId: active.generation_id,
+					created: false
+				};
+			}
+			const generationId = randomUUID();
+			this.db.prepare(`INSERT INTO home_advice_generations (
+        generation_id, owner_id, workspace_id, idempotency_key, status, reasons_json, requested_at, strategy_version
+      ) VALUES (?, ?, ?, ?, 'queued', ?, ?, ?)`).run(generationId, principal.ownerId, principal.workspaceId, input.idempotencyKey, JSON.stringify(uniqueReasons(input.reasons)), input.requestedAt, HOME_ADVICE_STRATEGY_VERSION);
+			return {
+				generationId,
+				created: true
+			};
+		});
+	}
+	claimNext(principal, workerId, now, leaseMs = 6e4) {
+		return runSqliteSavepoint(this.db, () => {
+			const row = this.db.prepare(`SELECT * FROM home_advice_generations
+        WHERE owner_id = ? AND workspace_id = ?
+          AND (status = 'queued' OR (status = 'retry_wait' AND retry_at <= ?)
+          OR (status = 'running' AND lease_until < ?))
+        ORDER BY requested_at ASC LIMIT 1`).get(principal.ownerId, principal.workspaceId, now, now);
+			if (!row) return void 0;
+			const nextEpoch = row.lease_epoch + 1;
+			const changed = this.db.prepare(`UPDATE home_advice_generations SET
+        status = 'running', started_at = ?, lease_owner = ?, lease_until = ?,
+        lease_epoch = ?, attempt = attempt + 1, dirty_after_start = 0, retry_at = NULL
+        WHERE generation_id = ? AND owner_id = ? AND workspace_id = ? AND lease_epoch = ?
+          AND (status = 'queued' OR (status = 'retry_wait' AND retry_at <= ?)
+            OR (status = 'running' AND lease_until < ?))`).run(now, workerId, now + leaseMs, nextEpoch, row.generation_id, principal.ownerId, principal.workspaceId, row.lease_epoch, now, now);
+			if (Number(changed.changes) !== 1) return void 0;
+			return {
+				generationId: row.generation_id,
+				ownerId: row.owner_id,
+				workspaceId: row.workspace_id,
+				leaseOwner: workerId,
+				leaseEpoch: nextEpoch,
+				attempt: row.attempt + 1,
+				reasons: parseJson(row.reasons_json, [])
+			};
+		});
+	}
+	complete(claim, completion) {
+		return runSqliteSavepoint(this.db, () => {
+			const current = this.requireClaim(claim);
+			const opportunities = [];
+			if (completion.result.state === "ready") {
+				const seen = /* @__PURE__ */ new Set();
+				for (const candidate of completion.result.opportunities) {
+					const opportunity = HomeOpportunitySchema.parse(candidate);
+					const key = this.opportunityDedupeKey(opportunity);
+					if (seen.has(key)) continue;
+					seen.add(key);
+					opportunities.push(opportunity);
+					if (opportunities.length === 3) break;
+				}
+				if (opportunities.length === 0) throw new Error("A ready home generation requires an opportunity");
+			}
+			if (completion.result.state !== "quiet" || completion.result.reason === "insufficient_value") this.db.prepare(`UPDATE home_opportunity_projections SET state = 'superseded', updated_at = ?
+          WHERE owner_id = ? AND workspace_id = ? AND state IN ('active', 'snoozed')`).run(completion.completedAt, claim.ownerId, claim.workspaceId);
+			const parsedResult = completion.result.state === "ready" ? {
+				state: "ready",
+				placement: completion.result.placement ?? "primary",
+				opportunityIds: opportunities.map((item) => item.id)
+			} : HomeAdvisorSchema.parse(completion.result);
+			if (completion.result.state === "ready") opportunities.forEach((opportunity, rank) => {
+				this.db.prepare(`INSERT INTO home_opportunity_projections (
+            opportunity_id, generation_id, owner_id, workspace_id, rank, kind, project_id,
+            dedupe_key, content_json, evidence_refs_json, snapshot_hash, state, revision,
+            created_at, updated_at, expires_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`).run(opportunity.id, claim.generationId, claim.ownerId, claim.workspaceId, rank, opportunity.kind, opportunity.projectId ?? null, this.opportunityDedupeKey(opportunity), JSON.stringify(opportunity), JSON.stringify(opportunity.evidence.map(({ id, revision, sourceRef, freshUntil }) => ({
+					id,
+					revision,
+					sourceRef,
+					freshUntil
+				}))), completion.snapshotHash, opportunity.revision, completion.completedAt, completion.completedAt, opportunity.expiresAt);
+			});
+			const status = completion.result.state === "quiet" ? "skipped" : "succeeded";
+			const changed = this.db.prepare(`UPDATE home_advice_generations SET
+        status = ?, completed_at = ?, lease_owner = NULL, lease_until = NULL,
+        snapshot_hash = ?, evidence_ids_json = ?, result_json = ?, model_ref = ?,
+        input_tokens = ?, output_tokens = ?, estimated_cost_usd = ?, outcome_reason = ?,
+        strategy_version = ?, error_code = NULL
+        WHERE generation_id = ? AND status = 'running' AND lease_owner = ? AND lease_epoch = ?`).run(status, completion.completedAt, completion.snapshotHash, JSON.stringify([...new Set(completion.evidenceIds)]), JSON.stringify(parsedResult), completion.modelRef ?? null, completion.inputTokens ?? null, completion.outputTokens ?? null, completion.estimatedCostUsd ?? null, completion.outcomeReason ?? null, HOME_ADVICE_STRATEGY_VERSION, claim.generationId, claim.leaseOwner, claim.leaseEpoch);
+			if (Number(changed.changes) !== 1) throw new Error("Home generation lease was lost");
+			return { dirty: current.dirty_after_start === 1 };
+		});
+	}
+	fail(claim, now, errorCode, retryAt) {
+		const status = claim.attempt < 3 && retryAt !== void 0 ? "retry_wait" : "failed";
+		const changed = this.db.prepare(`UPDATE home_advice_generations SET
+      status = ?, retry_at = ?, completed_at = CASE WHEN ? = 'failed' THEN ? ELSE NULL END,
+      lease_owner = NULL, lease_until = NULL, error_code = ?
+      WHERE generation_id = ? AND status = 'running' AND lease_owner = ? AND lease_epoch = ?`).run(status, status === "retry_wait" ? retryAt : null, status, now, errorCode, claim.generationId, claim.leaseOwner, claim.leaseEpoch);
+		if (Number(changed.changes) !== 1) throw new Error("Home generation lease was lost");
+	}
+	getLatestSnapshotHash(principal) {
+		return this.db.prepare(`SELECT snapshot_hash FROM home_advice_generations
+      WHERE owner_id = ? AND workspace_id = ? AND status IN ('succeeded', 'skipped')
+        AND (model_ref IS NOT NULL OR outcome_reason IS NULL
+          OR outcome_reason NOT IN ('no_change', 'budget_exhausted'))
+      ORDER BY completed_at DESC, rowid DESC LIMIT 1`).get(principal.ownerId, principal.workspaceId)?.snapshot_hash ?? void 0;
+	}
+	countModelGenerationAttemptsSince(principal, since, currentGenerationId) {
+		const row = this.db.prepare(`SELECT COALESCE(SUM(CASE
+        WHEN generation_id = ? THEN MAX(attempt - 1, 0)
+        WHEN model_ref IS NOT NULL THEN 1
+        WHEN status IN ('failed', 'retry_wait') THEN attempt
+        ELSE 0
+      END), 0) AS count
+      FROM home_advice_generations
+      WHERE owner_id = ? AND workspace_id = ? AND COALESCE(started_at, requested_at) >= ?`).get(currentGenerationId, principal.ownerId, principal.workspaceId, since);
+		return Number(row.count);
+	}
+	listSuppressionKeys(principal) {
+		const rows = this.db.prepare(`SELECT f.scope_json, p.kind, p.project_id
+      FROM home_opportunity_feedback f
+      JOIN home_opportunity_projections p ON p.opportunity_id = f.opportunity_id
+      WHERE p.owner_id = ? AND p.workspace_id = ? AND f.kind = 'less_like_this'
+      ORDER BY f.created_at DESC LIMIT 100`).all(principal.ownerId, principal.workspaceId);
+		return new Set(rows.map((row) => {
+			const scope = parseJson(row.scope_json, {});
+			return `${typeof scope.kind === "string" ? scope.kind : row.kind}:${(typeof scope.projectId === "string" ? scope.projectId : row.project_id) ?? "global"}`;
+		}));
+	}
+	getSuccessfulPatterns(principal) {
+		const rows = this.db.prepare(`SELECT p.content_json
+      FROM home_opportunity_projections p
+      JOIN tasks t ON p.resolution_kind = 'task' AND p.resolution_ref = t.task_id
+      WHERE p.owner_id = ? AND p.workspace_id = ?
+        AND p.state = 'accepted' AND t.phase = 'closed' AND t.resolution = 'done'`).all(principal.ownerId, principal.workspaceId);
+		const patterns = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const opportunity = HomeOpportunitySchema.parse(parseJson(row.content_json, null));
+			const key = homePatternKey(opportunity.projectId, opportunity.outcome);
+			const current = patterns.get(key);
+			patterns.set(key, {
+				projectId: opportunity.projectId,
+				title: opportunity.title,
+				outcome: opportunity.outcome,
+				successCount: (current?.successCount ?? 0) + 1
+			});
+		}
+		return [...patterns.values()].sort((left, right) => right.successCount - left.successCount || left.outcome.localeCompare(right.outcome));
+	}
+	getPersonalization(principal, now) {
+		const rows = this.db.prepare(`SELECT p.kind,
+        SUM(CASE WHEN f.kind IN ('irrelevant', 'source_incorrect') THEN 1 ELSE 0 END) AS negative_count,
+        SUM(CASE WHEN f.kind = 'started' THEN 1 ELSE 0 END) AS positive_count
+      FROM home_opportunity_feedback f
+      JOIN home_opportunity_projections p ON p.opportunity_id = f.opportunity_id
+      WHERE p.owner_id = ? AND p.workspace_id = ? AND f.created_at >= ?
+      GROUP BY p.kind`).all(principal.ownerId, principal.workspaceId, now - HOME_FEEDBACK_WINDOW_MS);
+		return { highConfidenceKinds: new Set(rows.filter((row) => Number(row.negative_count) >= 3 && Number(row.negative_count) - Number(row.positive_count) >= 2).map((row) => row.kind)) };
+	}
+	getMetrics(principal, since, until) {
+		const generation = this.db.prepare(`SELECT
+        COUNT(*) AS total,
+        SUM(CASE WHEN status = 'succeeded' THEN 1 ELSE 0 END) AS succeeded,
+        SUM(CASE WHEN status = 'skipped' THEN 1 ELSE 0 END) AS quiet,
+        SUM(CASE WHEN status IN ('failed', 'cancelled') THEN 1 ELSE 0 END) AS failed,
+        COALESCE(SUM(estimated_cost_usd), 0) AS estimated_cost_usd
+      FROM home_advice_generations
+      WHERE owner_id = ? AND workspace_id = ? AND requested_at BETWEEN ? AND ?`).get(principal.ownerId, principal.workspaceId, since, until);
+		const outcome = this.db.prepare(`SELECT
+        COUNT(*) AS opportunities,
+        SUM(CASE WHEN state = 'accepted' THEN 1 ELSE 0 END) AS started,
+        SUM(CASE WHEN state = 'discussing' THEN 1 ELSE 0 END) AS discussed,
+        SUM(CASE WHEN state = 'expired' THEN 1 ELSE 0 END) AS expired
+      FROM home_opportunity_projections
+      WHERE owner_id = ? AND workspace_id = ? AND created_at BETWEEN ? AND ?`).get(principal.ownerId, principal.workspaceId, since, until);
+		const completed = this.db.prepare(`SELECT COUNT(*) AS count
+      FROM home_opportunity_projections p
+      JOIN tasks t ON p.resolution_kind = 'task' AND p.resolution_ref = t.task_id
+      WHERE p.owner_id = ? AND p.workspace_id = ? AND p.created_at BETWEEN ? AND ?
+        AND t.phase = 'closed' AND t.resolution = 'done'`).get(principal.ownerId, principal.workspaceId, since, until);
+		const feedbackRows = this.db.prepare(`SELECT f.kind, COUNT(*) AS count
+      FROM home_opportunity_feedback f
+      JOIN home_opportunity_projections p ON p.opportunity_id = f.opportunity_id
+      WHERE p.owner_id = ? AND p.workspace_id = ? AND f.created_at BETWEEN ? AND ?
+      GROUP BY f.kind`).all(principal.ownerId, principal.workspaceId, since, until);
+		const feedback = new Map(feedbackRows.map((row) => [row.kind, Number(row.count)]));
+		const corrected = [
+			"already_done",
+			"irrelevant",
+			"too_early",
+			"source_incorrect",
+			"less_like_this"
+		].reduce((count, kind) => count + (feedback.get(kind) ?? 0), 0);
+		const strategyRows = this.db.prepare(`SELECT
+        g.strategy_version AS version,
+        COUNT(DISTINCT g.generation_id) AS generations,
+        COUNT(DISTINCT p.opportunity_id) AS opportunities,
+        COUNT(DISTINCT CASE WHEN f.kind = 'started' THEN p.opportunity_id END) AS started,
+        COUNT(DISTINCT CASE WHEN t.phase = 'closed' AND t.resolution = 'done' THEN p.opportunity_id END) AS completed
+      FROM home_advice_generations g
+      LEFT JOIN home_opportunity_projections p ON p.generation_id = g.generation_id
+      LEFT JOIN home_opportunity_feedback f ON f.opportunity_id = p.opportunity_id
+      LEFT JOIN tasks t ON p.resolution_kind = 'task' AND p.resolution_ref = t.task_id
+      WHERE g.owner_id = ? AND g.workspace_id = ? AND g.requested_at BETWEEN ? AND ?
+      GROUP BY g.strategy_version
+      ORDER BY g.strategy_version`).all(principal.ownerId, principal.workspaceId, since, until);
+		const opportunities = Number(outcome.opportunities);
+		const started = Number(outcome.started);
+		return {
+			window: {
+				since,
+				until
+			},
+			currentStrategyVersion: HOME_ADVICE_STRATEGY_VERSION,
+			generations: {
+				total: Number(generation.total),
+				succeeded: Number(generation.succeeded),
+				quiet: Number(generation.quiet),
+				failed: Number(generation.failed),
+				estimatedCostUsd: Number(generation.estimated_cost_usd)
+			},
+			outcomes: {
+				opportunities,
+				started,
+				discussed: Number(outcome.discussed),
+				completed: Number(completed.count),
+				corrected,
+				expired: Number(outcome.expired)
+			},
+			rates: {
+				start: ratio(started, opportunities),
+				completionFromStarted: ratio(Number(completed.count), started),
+				correction: ratio(corrected, opportunities)
+			},
+			feedback: {
+				alreadyDone: feedback.get("already_done") ?? 0,
+				irrelevant: feedback.get("irrelevant") ?? 0,
+				tooEarly: feedback.get("too_early") ?? 0,
+				sourceIncorrect: feedback.get("source_incorrect") ?? 0,
+				lessLikeThis: feedback.get("less_like_this") ?? 0
+			},
+			strategies: strategyRows.map((row) => ({
+				version: row.version,
+				generations: Number(row.generations),
+				opportunities: Number(row.opportunities),
+				started: Number(row.started),
+				completed: Number(row.completed)
+			}))
+		};
+	}
+	invalidateOpportunitiesByEvidenceSources(principal, sourceTypes, now) {
+		if (!sourceTypes.size) return 0;
+		return runSqliteSavepoint(this.db, () => {
+			const ids = this.db.prepare(`SELECT opportunity_id, generation_id, content_json, revision, state, expires_at, snoozed_until
+        FROM home_opportunity_projections
+        WHERE owner_id = ? AND workspace_id = ? AND state IN ('active', 'snoozed')`).all(principal.ownerId, principal.workspaceId).filter((row) => parseOpportunity(row).evidence.some((item) => sourceTypes.has(item.sourceType))).map((row) => row.opportunity_id);
+			const invalidate = this.db.prepare(`UPDATE home_opportunity_projections
+        SET state = 'superseded', revision = revision + 1, updated_at = ?
+        WHERE opportunity_id = ? AND owner_id = ? AND workspace_id = ? AND state IN ('active', 'snoozed')`);
+			return ids.reduce((count, id) => count + Number(invalidate.run(now, id, principal.ownerId, principal.workspaceId).changes), 0);
+		});
+	}
+	getAdvisor(principal, now) {
+		const active = this.db.prepare(`SELECT requested_at FROM home_advice_generations
+      WHERE owner_id = ? AND workspace_id = ? AND status IN ('queued', 'running', 'retry_wait')
+      ORDER BY requested_at DESC LIMIT 1`).get(principal.ownerId, principal.workspaceId);
+		const rows = this.db.prepare(`SELECT opportunity_id, generation_id, content_json, revision, state, expires_at, snoozed_until
+      FROM home_opportunity_projections
+      WHERE owner_id = ? AND workspace_id = ? AND state IN ('active', 'snoozed')
+        AND expires_at > ? AND (state = 'active' OR snoozed_until <= ?)
+      ORDER BY rank ASC LIMIT 3`).all(principal.ownerId, principal.workspaceId, now, now);
+		const opportunities = rows.map(parseOpportunity);
+		if (opportunities.length > 0) {
+			const generatedAt = Math.min(...opportunities.map((item) => item.generatedAt));
+			const expiresAt = Math.min(...opportunities.map((item) => item.expiresAt));
+			const generation = this.db.prepare(`SELECT result_json FROM home_advice_generations
+        WHERE generation_id = ?`).get(rows[0].generation_id);
+			const placement = (generation?.result_json ? parseJson(generation.result_json, {}) : {}).placement === "compact" ? "compact" : "primary";
+			return HomeAdvisorSchema.parse({
+				state: "ready",
+				primary: opportunities[0],
+				alternatives: opportunities.slice(1),
+				placement,
+				generatedAt,
+				expiresAt,
+				stale: Boolean(active)
+			});
+		}
+		if (active) return {
+			state: "refreshing",
+			requestedAt: active.requested_at
+		};
+		const latest = this.db.prepare(`SELECT status, result_json, error_code FROM home_advice_generations
+      WHERE owner_id = ? AND workspace_id = ? AND status IN ('succeeded', 'skipped', 'failed')
+      ORDER BY COALESCE(completed_at, requested_at) DESC, rowid DESC LIMIT 1`).get(principal.ownerId, principal.workspaceId);
+		if (latest?.status === "failed") return {
+			state: "quiet",
+			reason: "generation_failed"
+		};
+		const result = latest?.result_json ? parseJson(latest.result_json, null) : null;
+		if (result && typeof result === "object" && "state" in result && (result.state === "quiet" || result.state === "clarification")) {
+			const advisor = HomeAdvisorSchema.parse(result);
+			return advisor.state === "clarification" && advisor.expiresAt <= now ? {
+				state: "quiet",
+				reason: "no_change"
+			} : advisor;
+		}
+		return {
+			state: "quiet",
+			reason: "no_change"
+		};
+	}
+	getOpportunity(principal, opportunityId, now) {
+		const row = this.db.prepare(`SELECT opportunity_id, generation_id, content_json, revision, state, expires_at, snoozed_until
+      FROM home_opportunity_projections WHERE opportunity_id = ? AND owner_id = ? AND workspace_id = ?
+        AND state IN ('active', 'snoozed') AND expires_at > ?`).get(opportunityId, principal.ownerId, principal.workspaceId, now);
+		return row ? parseOpportunity(row) : void 0;
+	}
+	getOpportunitySnapshot(principal, opportunityId) {
+		const row = this.db.prepare(`SELECT opportunity_id, generation_id, content_json, revision, state, expires_at, snoozed_until
+      FROM home_opportunity_projections WHERE opportunity_id = ? AND owner_id = ? AND workspace_id = ?`).get(opportunityId, principal.ownerId, principal.workspaceId);
+		return row ? parseOpportunity(row) : void 0;
+	}
+	listHistory(principal) {
+		return this.db.prepare(`SELECT
+        p.opportunity_id, p.generation_id, p.content_json, p.revision, p.state,
+        p.expires_at, p.snoozed_until, p.updated_at, p.resolution_kind, p.resolution_ref,
+        f.kind AS feedback_kind, t.phase AS task_phase, t.resolution AS task_resolution
+      FROM home_opportunity_projections p
+      LEFT JOIN home_opportunity_feedback f ON f.feedback_id = (
+        SELECT latest.feedback_id FROM home_opportunity_feedback latest
+        WHERE latest.opportunity_id = p.opportunity_id
+        ORDER BY latest.created_at DESC, latest.rowid DESC LIMIT 1
+      )
+      LEFT JOIN tasks t ON p.resolution_kind = 'task' AND p.resolution_ref = t.task_id
+      WHERE p.owner_id = ? AND p.workspace_id = ?
+      ORDER BY p.updated_at DESC, p.opportunity_id ASC LIMIT 100`).all(principal.ownerId, principal.workspaceId).map((row) => {
+			const opportunity = parseOpportunity(row);
+			const status = row.feedback_kind === "already_done" || row.task_phase === "closed" && row.task_resolution === "done" ? "completed" : row.state === "accepted" ? "started" : row.state === "discussing" ? "discussing" : row.state === "active" ? "available" : row.state;
+			const href = row.resolution_kind === "task" && row.resolution_ref ? `/tasks/${encodeURIComponent(row.resolution_ref)}` : row.resolution_kind === "session" && row.resolution_ref && row.resolution_ref !== "draft" ? `/chat/${encodeURIComponent(row.resolution_ref)}` : void 0;
+			return {
+				opportunity,
+				status,
+				...row.feedback_kind ? { feedbackKind: row.feedback_kind } : {},
+				updatedAt: row.updated_at,
+				...row.snoozed_until === null ? {} : { snoozedUntil: row.snoozed_until },
+				...href ? { href } : {}
+			};
+		});
+	}
+	isFeedbackRecorded(opportunityId, idempotencyKey) {
+		const row = this.db.prepare(`SELECT opportunity_id FROM home_opportunity_feedback
+      WHERE idempotency_key = ?`).get(idempotencyKey);
+		if (!row) return false;
+		if (row.opportunity_id !== opportunityId) throw new Error("Feedback idempotency key belongs to another opportunity");
+		return true;
+	}
+	recordFeedback(principal, opportunityId, input) {
+		return runSqliteSavepoint(this.db, () => {
+			const duplicate = this.db.prepare(`SELECT opportunity_id FROM home_opportunity_feedback
+        WHERE idempotency_key = ?`).get(input.idempotencyKey);
+			if (duplicate) {
+				if (duplicate.opportunity_id !== opportunityId) throw new Error("Feedback idempotency key belongs to another opportunity");
+				return this.getOpportunity(principal, opportunityId, input.createdAt);
+			}
+			const next = this.feedbackTransition(input);
+			const changed = this.db.prepare(`UPDATE home_opportunity_projections SET
+        state = ?, revision = revision + 1, updated_at = ?, snoozed_until = ?,
+        resolution_kind = ?, resolution_ref = ?
+        WHERE opportunity_id = ? AND owner_id = ? AND workspace_id = ?
+          AND revision = ? AND state IN ('active', 'snoozed')`).run(next.state, input.createdAt, next.snoozedUntil, input.resolution?.kind ?? null, input.resolution?.ref ?? null, opportunityId, principal.ownerId, principal.workspaceId, input.expectedRevision);
+			if (Number(changed.changes) !== 1) throw new Error("Home opportunity is stale or unavailable");
+			this.db.prepare(`INSERT INTO home_opportunity_feedback (
+        feedback_id, opportunity_id, idempotency_key, kind, reason_code, note, scope_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(input.feedbackId ?? randomUUID(), opportunityId, input.idempotencyKey, input.kind, input.reasonCode ?? null, input.note ?? null, JSON.stringify(input.scope ?? {}), input.createdAt);
+			return this.getOpportunity(principal, opportunityId, input.createdAt);
+		});
+	}
+	undoFeedback(principal, opportunityId, idempotencyKey, now) {
+		return runSqliteSavepoint(this.db, () => {
+			const feedback = this.db.prepare(`SELECT f.feedback_id, f.idempotency_key, f.kind,
+          p.state, p.expires_at
+        FROM home_opportunity_feedback f
+        JOIN home_opportunity_projections p ON p.opportunity_id = f.opportunity_id
+        WHERE f.opportunity_id = ? AND p.owner_id = ? AND p.workspace_id = ?
+        ORDER BY f.created_at DESC, f.rowid DESC LIMIT 1`).get(opportunityId, principal.ownerId, principal.workspaceId);
+			if (!feedback || feedback.idempotency_key !== idempotencyKey) throw new Error("Only the latest home opportunity feedback can be undone");
+			if (feedback.kind === "started" || feedback.kind === "discussed") throw new Error("Started or discussed opportunities cannot be undone here");
+			if (!["dismissed", "snoozed"].includes(feedback.state) || feedback.expires_at <= now) throw new Error("Home opportunity feedback can no longer be undone");
+			this.db.prepare(`DELETE FROM home_opportunity_feedback WHERE feedback_id = ?`).run(feedback.feedback_id);
+			const changed = this.db.prepare(`UPDATE home_opportunity_projections SET
+        state = 'active', revision = revision + 1, updated_at = ?, snoozed_until = NULL,
+        resolution_kind = NULL, resolution_ref = NULL
+        WHERE opportunity_id = ? AND owner_id = ? AND workspace_id = ?
+          AND state IN ('dismissed', 'snoozed') AND expires_at > ?`).run(now, opportunityId, principal.ownerId, principal.workspaceId, now);
+			if (Number(changed.changes) !== 1) throw new Error("Home opportunity feedback can no longer be undone");
+			const opportunity = this.getOpportunity(principal, opportunityId, now);
+			if (!opportunity) throw new Error("Home opportunity feedback can no longer be undone");
+			return opportunity;
+		});
+	}
+	maintain(now) {
+		return runSqliteSavepoint(this.db, () => {
+			const expired = this.db.prepare(`UPDATE home_opportunity_projections
+        SET state = 'expired', revision = revision + 1, updated_at = ?
+        WHERE state IN ('active', 'snoozed') AND expires_at <= ?`).run(now, now);
+			const awakened = this.db.prepare(`UPDATE home_opportunity_projections
+        SET state = 'active', revision = revision + 1, updated_at = ?, snoozed_until = NULL
+        WHERE state = 'snoozed' AND snoozed_until <= ? AND expires_at > ?`).run(now, now, now);
+			return {
+				expired: Number(expired.changes),
+				awakened: Number(awakened.changes)
+			};
+		});
+	}
+	requireClaim(claim) {
+		const row = this.db.prepare(`SELECT * FROM home_advice_generations
+      WHERE generation_id = ? AND status = 'running' AND lease_owner = ? AND lease_epoch = ?`).get(claim.generationId, claim.leaseOwner, claim.leaseEpoch);
+		if (!row) throw new Error("Home generation lease was lost");
+		return row;
+	}
+	feedbackTransition(input) {
+		if (input.kind === "started") return {
+			state: "accepted",
+			snoozedUntil: null
+		};
+		if (input.kind === "discussed") return {
+			state: "discussing",
+			snoozedUntil: null
+		};
+		if (input.kind === "snoozed" || input.kind === "too_early") {
+			if (!input.snoozedUntil || input.snoozedUntil <= input.createdAt) throw new Error("A future snoozedUntil is required");
+			return {
+				state: "snoozed",
+				snoozedUntil: input.snoozedUntil
+			};
+		}
+		return {
+			state: "dismissed",
+			snoozedUntil: null
+		};
+	}
+	opportunityDedupeKey(opportunity) {
+		const outcome = opportunity.outcome.toLocaleLowerCase().replace(/[\p{P}\p{S}\s]+/gu, "");
+		return `${opportunity.kind}:${opportunity.projectId ?? "global"}:${outcome}`;
+	}
+};
+//#endregion
+export { HomeIntelligenceRepository };

package/dist/src/home-intelligence/snapshot.d.ts

@@ -0,0 +1,43 @@
+import type { HomeEvidence } from '@xopcai/gateway-contract';
+import type { Task } from '@xopcai/gateway-contract';
+import type { KnowledgeItem, KnowledgeReadPolicy } from '../knowledge-memory/domain.js';
+import type { Project } from '../projects/types.js';
+import type { SessionMetadata } from '../session/types.js';
+import type { HomeSuccessfulPattern } from './strategy.js';
+export interface HomeContextSnapshot {
+    generatedAt: number;
+    locale: 'en' | 'zh';
+    projects: Array<Pick<Project, 'id' | 'name' | 'status' | 'health' | 'brief' | 'outcome' | 'successCriteria' | 'targetAt' | 'updatedAt'>>;
+    tasks: Array<Pick<Task, 'id' | 'projectId' | 'title' | 'phase' | 'priority' | 'dueAt' | 'updatedAt'> & {
+        objective?: string;
+    }>;
+    knowledge: Array<Pick<KnowledgeItem, 'id' | 'kind' | 'content' | 'scope' | 'updatedAt' | 'expiresAt' | 'validTo'> & {
+        sourceType: Extract<HomeEvidence['sourceType'], 'calendar' | 'mail' | 'communication' | 'user_model'>;
+        provider?: string;
+    }>;
+    recentSessions: Array<{
+        id: string;
+        title: string;
+        projectId?: string;
+        updatedAt: number;
+    }>;
+    successfulPatterns: HomeSuccessfulPattern[];
+    evidence: HomeEvidence[];
+    hash: string;
+}
+export interface HomeSnapshotSources {
+    projects(): Project[];
+    tasks(): Task[];
+    knowledge(): KnowledgeItem[];
+    knowledgePolicy?(): KnowledgeReadPolicy;
+    sessions?(): SessionMetadata[];
+}
+export declare class HomeSnapshotBuilder {
+    private readonly sources;
+    constructor(sources: HomeSnapshotSources);
+    build(input: {
+        now: number;
+        locale: 'en' | 'zh';
+        successfulPatterns?: HomeSuccessfulPattern[];
+    }): HomeContextSnapshot;
+}

package/dist/src/home-intelligence/snapshot.js

@@ -0,0 +1,133 @@
+import { knowledgeItemAllowed } from "../knowledge-memory/repository.js";
+import { createHash } from "node:crypto";
+//#region src/home-intelligence/snapshot.ts
+function contentHash(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function knowledgeSourceType(item) {
+	if (item.recordClass !== "source_index") return "user_model";
+	const identity = [
+		item.source.provider,
+		item.source.kind,
+		item.source.sourceInstanceId
+	].filter((value) => typeof value === "string").join(":").toLocaleLowerCase();
+	if (identity.includes("calendar")) return "calendar";
+	if (/gmail|outlook|\bmail\b/.test(identity)) return "mail";
+	if (/slack|teams|dingtalk|wecom|feishu|lark/.test(identity)) return "communication";
+	return "user_model";
+}
+function knowledgeFreshUntil(item, now) {
+	const ttl = item.sourceType === "calendar" ? 360 * 6e4 : item.sourceType === "mail" || item.sourceType === "communication" ? 720 * 6e4 : 1440 * 6e4;
+	return Math.min(item.expiresAt ?? Number.MAX_SAFE_INTEGER, item.validTo ?? Number.MAX_SAFE_INTEGER, now + ttl);
+}
+var HomeSnapshotBuilder = class {
+	constructor(sources) {
+		this.sources = sources;
+	}
+	build(input) {
+		const projects = this.sources.projects().filter((project) => project.status === "active" || project.status === "planned" || project.status === "paused").sort((left, right) => (right.lastActiveAt ?? right.updatedAt) - (left.lastActiveAt ?? left.updatedAt)).slice(0, 8).map(({ id, name, status, health, brief, outcome, successCriteria, targetAt, updatedAt }) => ({
+			id,
+			name,
+			status,
+			health,
+			brief,
+			outcome,
+			successCriteria,
+			targetAt,
+			updatedAt
+		}));
+		const projectIds = new Set(projects.map((project) => project.id));
+		const tasks = this.sources.tasks().filter((task) => task.phase !== "closed" && (!task.projectId || projectIds.has(task.projectId))).sort((left, right) => (left.dueAt ?? Number.MAX_SAFE_INTEGER) - (right.dueAt ?? Number.MAX_SAFE_INTEGER) || right.updatedAt - left.updatedAt).slice(0, 30).map(({ id, projectId, title, phase, priority, dueAt, updatedAt, contract }) => ({
+			id,
+			projectId,
+			title,
+			phase,
+			priority,
+			dueAt,
+			updatedAt,
+			objective: contract?.objective
+		}));
+		const knowledgePolicy = this.sources.knowledgePolicy?.();
+		const knowledge = this.sources.knowledge().filter((item) => item.status === "active" && (!item.expiresAt || item.expiresAt > input.now) && (!item.validTo || item.validTo > input.now) && (!knowledgePolicy || knowledgeItemAllowed(item, knowledgePolicy)) && (item.scope.type !== "project" || item.scope.id && projectIds.has(item.scope.id))).sort((left, right) => right.importance - left.importance || right.updatedAt - left.updatedAt).slice(0, 30).map((item) => ({
+			id: item.id,
+			kind: item.kind,
+			content: item.content,
+			scope: item.scope,
+			updatedAt: item.updatedAt,
+			expiresAt: item.expiresAt,
+			validTo: item.validTo,
+			sourceType: knowledgeSourceType(item),
+			...typeof item.source.provider === "string" ? { provider: item.source.provider } : {}
+		}));
+		const recentSessions = (this.sources.sessions?.() ?? []).filter((session) => session.messageCount > 0).map((session) => ({
+			id: session.key,
+			title: session.name?.trim() || (input.locale === "zh" ? "未命名会话" : "Untitled conversation"),
+			projectId: session.projectId,
+			updatedAt: Date.parse(session.lastInteractionAt ?? session.updatedAt)
+		})).filter((session) => Number.isFinite(session.updatedAt)).sort((left, right) => right.updatedAt - left.updatedAt).slice(0, 12);
+		const evidence = [
+			...projects.map((project) => ({
+				id: `project:${project.id}:v${project.updatedAt}`,
+				sourceType: "project",
+				sourceRef: project.id,
+				revision: String(project.updatedAt),
+				observation: [project.name, project.outcome || project.brief].filter(Boolean).join("：").slice(0, 1e3),
+				observedAt: project.updatedAt,
+				freshUntil: input.now + 1440 * 6e4,
+				href: `/projects/${encodeURIComponent(project.id)}`
+			})),
+			...tasks.map((task) => ({
+				id: `task:${task.id}:v${task.updatedAt}`,
+				sourceType: "task",
+				sourceRef: task.id,
+				revision: String(task.updatedAt),
+				observation: [task.title, task.objective].filter(Boolean).join("：").slice(0, 1e3),
+				observedAt: task.updatedAt,
+				freshUntil: input.now + 720 * 6e4,
+				href: `/tasks?task=${encodeURIComponent(task.id)}`
+			})),
+			...knowledge.map((item) => ({
+				id: `knowledge:${item.id}:v${item.updatedAt}`,
+				sourceType: item.sourceType,
+				sourceRef: item.id,
+				revision: String(item.updatedAt),
+				observation: item.content.slice(0, 1e3),
+				observedAt: item.updatedAt,
+				freshUntil: knowledgeFreshUntil(item, input.now),
+				...item.provider ? { href: `/connectors?connector=${encodeURIComponent(item.provider)}` } : item.scope.type === "project" && item.scope.id ? { href: `/projects/${encodeURIComponent(item.scope.id)}` } : {}
+			})),
+			...recentSessions.map((session) => ({
+				id: `conversation:${session.id}:v${session.updatedAt}`,
+				sourceType: "conversation",
+				sourceRef: session.id,
+				revision: String(session.updatedAt),
+				observation: session.title.slice(0, 1e3),
+				observedAt: session.updatedAt,
+				freshUntil: input.now + 720 * 6e4,
+				href: `/chat/${encodeURIComponent(session.id)}`
+			}))
+		];
+		const successfulPatterns = [...input.successfulPatterns ?? []].filter((item) => item.successCount > 0).sort((left, right) => right.successCount - left.successCount || left.outcome.localeCompare(right.outcome)).slice(0, 20);
+		const stableContent = {
+			locale: input.locale,
+			projects,
+			tasks,
+			knowledge,
+			recentSessions,
+			successfulPatterns
+		};
+		return {
+			generatedAt: input.now,
+			locale: input.locale,
+			projects,
+			tasks,
+			knowledge,
+			recentSessions,
+			successfulPatterns,
+			evidence,
+			hash: contentHash(stableContent)
+		};
+	}
+};
+//#endregion
+export { HomeSnapshotBuilder };