@haaaiawd/second-nature 0.1.7 → 0.1.9

package/runtime/core/second-nature/orchestrator/intent-planner.js

@@ -1,16 +1,45 @@
-const MAX_CANDIDATES = 6;
-function planObligationIntents(snapshot) {
-    return snapshot.pendingObligations.map((obligation, index) => ({
+import { isLifeEvidenceSliceEmpty } from "../heartbeat/runtime-snapshot.js";
+import { buildHeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
+const MAX_CANDIDATE_INTENTS = 6;
+const OBLIGATION_SOURCE = [
+    { id: "obligation-anchor", kind: "workspace_artifact", uri: "workspace://obligations/pending" },
+];
+function evidenceRefsForConnector(runtime) {
+    if (!isLifeEvidenceSliceEmpty(runtime.lifeEvidence) && runtime.lifeEvidence.evidenceRefs.length > 0) {
+        return runtime.lifeEvidence.evidenceRefs.slice(0, 8);
+    }
+    if (!isLifeEvidenceSliceEmpty(runtime.lifeEvidence)) {
+        return [
+            {
+                id: "life-evidence-summary",
+                kind: "connector_result",
+                uri: `workspace://life-evidence/counts/${runtime.lifeEvidence.platformEventCount}/${runtime.lifeEvidence.workEventCount}`,
+            },
+        ];
+    }
+    return [];
+}
+function isAllowedKind(kind, runtime) {
+    return runtime.rhythmWindow.allowedIntentKinds.includes(kind);
+}
+function planWorkIntents(runtime) {
+    if (!isAllowedKind("work", runtime))
+        return [];
+    return runtime.continuity.pendingObligations.map((obligation, index) => ({
         id: `intent-obligation-${index}`,
         kind: "work",
         priority: 100 - index,
         source: "obligation",
         summary: `fulfill obligation: ${obligation}`,
-        effectClass: "external_platform_action",
+        effectClass: "connector_action",
+        sourceRefs: [...OBLIGATION_SOURCE],
+        idempotencyKey: `obligation:${obligation}:${index}`,
     }));
 }
-function planPlatformIntents(snapshot) {
-    const socialPriorityBase = snapshot.budgets && snapshot.budgets.socialUsed >= snapshot.budgets.socialLimit ? 10 : 60;
+function planExplorationIntents(runtime) {
+    if (!isAllowedKind("exploration", runtime))
+        return [];
+    const refs = evidenceRefsForConnector(runtime);
     return [
         {
             id: "intent-exploration",
@@ -18,45 +47,80 @@ function planPlatformIntents(snapshot) {
             priority: 70,
             source: "tick",
             summary: "scan platform opportunities",
-            effectClass: "external_platform_action",
+            effectClass: "connector_action",
+            sourceRefs: refs,
+            idempotencyKey: "exploration:scan platform opportunities",
         },
+    ];
+}
+function planSocialIntents(runtime) {
+    if (!isAllowedKind("social", runtime))
+        return [];
+    const refs = evidenceRefsForConnector(runtime);
+    return [
         {
             id: "intent-social",
             kind: "social",
-            priority: socialPriorityBase,
+            priority: runtime.continuity.budgets && runtime.continuity.budgets.socialUsed >= runtime.continuity.budgets.socialLimit ? 10 : 60,
             source: "tick",
             summary: "engage social platforms",
-            effectClass: "external_platform_action",
+            effectClass: "connector_action",
+            sourceRefs: refs,
+            idempotencyKey: "social:engage social platforms",
         },
     ];
 }
-function planQuietIntents(snapshot) {
-    if (snapshot.mode !== "quiet") {
+function planQuietReflectionIntents(runtime) {
+    if (!runtime.rhythmWindow.quietBias && runtime.continuity.mode !== "quiet") {
         return [];
     }
-    return [
-        {
+    const out = [];
+    if (isAllowedKind("quiet", runtime)) {
+        out.push({
+            id: "intent-quiet",
+            kind: "quiet",
+            priority: 55,
+            source: "quiet_plan",
+            summary: "quiet window bookkeeping",
+            effectClass: "no_effect",
+            sourceRefs: [],
+            idempotencyKey: "quiet:bookkeeping",
+        });
+    }
+    if (isAllowedKind("maintenance", runtime)) {
+        out.push({
             id: "intent-maintenance",
             kind: "maintenance",
-            priority: 90,
+            priority: 50,
             source: "quiet_plan",
             summary: "run maintenance checks",
             effectClass: "maintenance",
-        },
-        {
+            sourceRefs: [],
+            idempotencyKey: "maintenance:checks",
+        });
+    }
+    if (isAllowedKind("reflection", runtime)) {
+        const refs = evidenceRefsForConnector(runtime);
+        out.push({
             id: "intent-reflection",
             kind: "reflection",
-            priority: 80,
+            priority: 45,
             source: "quiet_plan",
             summary: "run narrative reflection",
             effectClass: "narrative_reflection",
-        },
-    ];
+            sourceRefs: refs,
+            idempotencyKey: "reflection:narrative",
+        });
+    }
+    return out;
 }
-function planOutreachIntents(snapshot) {
-    if (snapshot.recentOutreachHashes.length > 3) {
+function planOutreachIntents(runtime) {
+    if (!isAllowedKind("outreach", runtime))
+        return [];
+    if (runtime.continuity.recentOutreachHashes.length > 3) {
         return [];
     }
+    const refs = evidenceRefsForConnector(runtime);
     return [
         {
             id: "intent-outreach",
@@ -65,24 +129,67 @@ function planOutreachIntents(snapshot) {
             source: "tick",
             summary: "consider proactive user outreach",
             effectClass: "user_outreach",
+            sourceRefs: refs,
+            idempotencyKey: "outreach:consider proactive user outreach",
         },
     ];
 }
-export function planIntent(snapshot) {
+/**
+ * Plan ordered candidates for one heartbeat turn using rhythm window + life evidence slice.
+ */
+export function planCandidateIntents(runtime) {
+    if (runtime.continuity.mode === "paused_for_interrupt") {
+        const pausedMaintenance = [
+            {
+                id: "intent-maintenance",
+                kind: "maintenance",
+                priority: 40,
+                source: "tick",
+                summary: "run maintenance checks",
+                effectClass: "maintenance",
+                sourceRefs: [],
+                idempotencyKey: "maintenance:checks",
+            },
+        ];
+        return pausedMaintenance
+            .filter((intent) => runtime.rhythmWindow.allowedIntentKinds.includes(intent.kind))
+            .slice(0, MAX_CANDIDATE_INTENTS);
+    }
+    if (runtime.continuity.mode === "maintenance_only") {
+        return planWorkIntents(runtime).sort((a, b) => b.priority - a.priority).slice(0, MAX_CANDIDATE_INTENTS);
+    }
     const intents = [
-        ...planObligationIntents(snapshot),
-        ...planPlatformIntents(snapshot),
-        ...planQuietIntents(snapshot),
-        ...planOutreachIntents(snapshot),
+        ...planWorkIntents(runtime),
+        ...planExplorationIntents(runtime),
+        ...planSocialIntents(runtime),
+        ...planQuietReflectionIntents(runtime),
+        ...planOutreachIntents(runtime),
     ];
     return intents
+        .filter((intent) => runtime.rhythmWindow.allowedIntentKinds.includes(intent.kind))
         .sort((a, b) => b.priority - a.priority)
-        .slice(0, MAX_CANDIDATES);
+        .slice(0, MAX_CANDIDATE_INTENTS);
+}
+/** @deprecated Continuity-only helper for tests; prefer `planCandidateIntents` + `buildHeartbeatRuntimeSnapshot`. */
+export function planIntent(snapshot) {
+    const inputs = {
+        mode: snapshot.mode,
+        currentWindowId: snapshot.currentWindowId,
+        pendingObligations: snapshot.pendingObligations,
+        recentOutreachHashes: snapshot.recentOutreachHashes,
+        deniedIntents: snapshot.deniedIntents,
+        budgets: snapshot.budgets,
+        awaitingUserInput: snapshot.awaitingUserInput,
+        riskSuppressed: snapshot.riskSuppressed,
+        quietEnabledBridge: snapshot.mode === "quiet",
+    };
+    const runtime = buildHeartbeatRuntimeSnapshot("2026-03-25T12:00:00.000Z", inputs, snapshot);
+    return planCandidateIntents(runtime);
 }
 export function decideDecisionBasis(intent) {
     if (intent.source === "obligation")
         return "rule_only";
-    if (intent.kind === "maintenance")
+    if (intent.effectClass === "maintenance" || intent.effectClass === "no_effect")
         return "rule_only";
     if (intent.kind === "outreach" || intent.kind === "reflection")
         return "model_assisted";

package/runtime/core/second-nature/orchestrator/lease-manager.d.ts

@@ -1,4 +1,4 @@
-export type EffectClass = "external_platform_action" | "memory_curation" | "narrative_reflection" | "user_outreach" | "maintenance";
+export type EffectClass = "external_platform_action" | "connector_action" | "memory_curation" | "narrative_reflection" | "user_outreach" | "maintenance" | "no_effect";
 export interface LeaseHandle {
     id: string;
     granted: boolean;

package/runtime/core/second-nature/orchestrator/lease-manager.js

@@ -50,7 +50,7 @@ export class LeaseManager {
         };
     }
     resolveScope(effectClass, scopeHint) {
-        if (effectClass === "external_platform_action" || effectClass === "user_outreach") {
+        if (effectClass === "external_platform_action" || effectClass === "connector_action" || effectClass === "user_outreach") {
             return scopeHint && scopeHint.length > 0 ? `${GLOBAL_SCOPE}:${scopeHint}` : GLOBAL_SCOPE;
         }
         return null;

package/runtime/core/second-nature/outreach/build-outreach-draft-request.d.ts

@@ -0,0 +1,6 @@
+import type { OutreachDraftRequest } from "../../../guidance/outreach-draft-schema.js";
+import type { CandidateIntent } from "../types.js";
+import type { HeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
+import type { OutreachJudgment } from "./judge-outreach.js";
+import type { DeliveryTargetResolution } from "./delivery-target.js";
+export declare function buildOutreachDraftRequest(candidate: CandidateIntent, judgment: OutreachJudgment, snapshot: HeartbeatRuntimeSnapshot, delivery: DeliveryTargetResolution): OutreachDraftRequest;

package/runtime/core/second-nature/outreach/build-outreach-draft-request.js

@@ -0,0 +1,63 @@
+/**
+ * Maps control-plane judgment + delivery resolution into guidance OutreachDraftRequest (T6.2.1).
+ * Aligns with control-plane-system.detail §3.9 buildOutreachDraftRequest.
+ */
+import * as crypto from "node:crypto";
+function inferRhythmWindowKind(windowId) {
+    const id = windowId.toLowerCase();
+    if (id.includes("work"))
+        return "work";
+    if (id.includes("social"))
+        return "social";
+    if (id.includes("quiet"))
+        return "quiet";
+    if (id.includes("reflect"))
+        return "reflection";
+    if (id.includes("explore"))
+        return "exploration";
+    return undefined;
+}
+function toGuidanceRefs(refs) {
+    return refs.map((r) => ({
+        id: r.id,
+        kind: r.kind,
+        uri: r.uri,
+        excerptHash: r.excerptHash,
+        observedAt: r.observedAt,
+    }));
+}
+function mapDeliveryVerdict(verdict) {
+    switch (verdict) {
+        case "target_available":
+            return "target_available";
+        case "target_none":
+            return "target_none";
+        case "channel_missing":
+            return "channel_missing";
+        case "host_unsupported":
+            return "host_unsupported";
+        default:
+            return "host_unsupported";
+    }
+}
+export function buildOutreachDraftRequest(candidate, judgment, snapshot, delivery) {
+    const sceneType = delivery.verdict === "target_available" ? "outreach" : "fallback_candidate";
+    const riskLevel = delivery.verdict === "target_available" ? "medium" : "low";
+    return {
+        requestId: `outreach_draft_request:${crypto.randomUUID()}`,
+        sceneType,
+        runtimeScope: "rhythm",
+        rhythmWindowKind: inferRhythmWindowKind(snapshot.rhythmWindow.windowId),
+        riskLevel,
+        sourceRefs: toGuidanceRefs(judgment.sourceRefs),
+        decisionId: judgment.decisionId,
+        candidateId: candidate.id,
+        judgmentVerdict: judgment.verdict,
+        valueScore: judgment.valueScore,
+        interestRefs: toGuidanceRefs(judgment.interestRefs),
+        deliveryContext: {
+            deliveryVerdict: mapDeliveryVerdict(delivery.verdict),
+            wordingMode: delivery.verdict === "target_available" ? "sendable" : "not_sent_fallback_candidate",
+        },
+    };
+}

package/runtime/core/second-nature/outreach/delivery-target.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolves OpenClaw-visible delivery target from host capability snapshot (T2.3.1 / ADR-007).
+ *
+ * Core logic: explicit/last targets require channel materialization; `none` is a first-class verdict.
+ * Test coverage: tests/unit/core/outreach-judgment.test.ts
+ */
+export type DeliveryHostTarget = "none" | "last" | "explicit";
+export interface DeliveryCapabilitySnapshot {
+    /** Raw host value; may be empty string before normalization. */
+    target?: DeliveryHostTarget | string | null;
+    channel?: string | null;
+    recipient?: string | null;
+    lastKnownVisibleChannel?: string | null;
+    /** When true, host reports unsupported delivery surface (maps to host_unsupported verdict). */
+    hostUnsupported?: boolean;
+}
+export type DeliveryTargetVerdict = "target_none" | "channel_missing" | "target_available" | "host_unsupported";
+export interface DeliveryTargetResolution {
+    verdict: DeliveryTargetVerdict;
+    target?: DeliveryHostTarget;
+    channel?: string;
+    recipient?: string;
+    reason: string;
+}
+export declare function resolveDeliveryTarget(snapshot: DeliveryCapabilitySnapshot): DeliveryTargetResolution;
+export declare function isDeliveryUnavailableReason(reason: string): boolean;

package/runtime/core/second-nature/outreach/delivery-target.js

@@ -0,0 +1,70 @@
+/**
+ * Resolves OpenClaw-visible delivery target from host capability snapshot (T2.3.1 / ADR-007).
+ *
+ * Core logic: explicit/last targets require channel materialization; `none` is a first-class verdict.
+ * Test coverage: tests/unit/core/outreach-judgment.test.ts
+ */
+export function resolveDeliveryTarget(snapshot) {
+    if (snapshot.hostUnsupported) {
+        return {
+            verdict: "host_unsupported",
+            target: snapshot.target && String(snapshot.target).trim() !== "" && snapshot.target !== "none"
+                ? snapshot.target
+                : "none",
+            reason: "host_delivery_surface_unsupported",
+        };
+    }
+    const raw = snapshot.target;
+    if (raw === undefined || raw === null || String(raw).trim() === "" || raw === "none") {
+        return {
+            verdict: "target_none",
+            target: "none",
+            reason: "heartbeat_run_without_user_visible_delivery",
+        };
+    }
+    if (raw === "explicit") {
+        const ch = (snapshot.channel ?? "").trim();
+        const rec = (snapshot.recipient ?? "").trim();
+        if (!ch || !rec) {
+            return {
+                verdict: "channel_missing",
+                target: "explicit",
+                reason: "explicit_delivery_requires_channel_and_recipient",
+            };
+        }
+        return {
+            verdict: "target_available",
+            target: "explicit",
+            channel: ch,
+            recipient: rec,
+            reason: "delivery_target_available",
+        };
+    }
+    if (raw === "last") {
+        const lastCh = (snapshot.lastKnownVisibleChannel ?? "").trim();
+        if (!lastCh) {
+            return {
+                verdict: "channel_missing",
+                target: "last",
+                reason: "last_target_has_no_known_visible_channel",
+            };
+        }
+        return {
+            verdict: "target_available",
+            target: "last",
+            channel: lastCh,
+            recipient: snapshot.recipient?.trim() || undefined,
+            reason: "delivery_target_available",
+        };
+    }
+    return {
+        verdict: "target_available",
+        target: raw,
+        channel: snapshot.channel?.trim() || snapshot.lastKnownVisibleChannel?.trim() || undefined,
+        recipient: snapshot.recipient?.trim() || undefined,
+        reason: "delivery_target_available",
+    };
+}
+export function isDeliveryUnavailableReason(reason) {
+    return reason === "target_none" || reason === "channel_missing" || reason === "host_unsupported";
+}

package/runtime/core/second-nature/outreach/dispatch-user-outreach.d.ts

@@ -0,0 +1,38 @@
+/**
+ * User outreach dispatch path: judgment → draft → host delivery → attempt + operator fallback (T2.3.2).
+ * Mirrors control-plane-system.detail §3.9 dispatchAllowedIntent user_outreach branch.
+ */
+import type { GuidanceDraftPort } from "../../../guidance/outreach-draft-schema.js";
+import type { CandidateIntent } from "../types.js";
+import type { HeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
+import type { HeartbeatCycleResult } from "../heartbeat/signal.js";
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef } from "../../../storage/life-evidence/types.js";
+import { type JudgeOutreachInput } from "./judge-outreach.js";
+import { type DeliveryTargetResolution } from "./delivery-target.js";
+export interface OpenClawDeliverySendResult {
+    id: string;
+    status: "sent" | "failed" | "dropped_by_host_policy";
+    errorClass?: string;
+    messageId?: string;
+    /** Host-reported delivery proof when messageId is absent (T4.3.1). */
+    hostProofRef?: SourceRef;
+}
+export interface OpenClawDeliveryPort {
+    sendDeliveryRequest(input: {
+        decisionId: string;
+        target: NonNullable<DeliveryTargetResolution["target"]>;
+        channel: string;
+        recipient?: string;
+        message: string;
+        sourceRefs: CandidateIntent["sourceRefs"];
+    }): Promise<OpenClawDeliverySendResult>;
+}
+export declare function dispatchUserOutreachIntent(input: {
+    candidate: CandidateIntent;
+    snapshot: HeartbeatRuntimeSnapshot;
+    judgeInput: Omit<JudgeOutreachInput, "candidate">;
+    guidance: GuidanceDraftPort;
+    delivery: OpenClawDeliveryPort;
+    state: StateDatabase;
+}): Promise<HeartbeatCycleResult>;

package/runtime/core/second-nature/outreach/dispatch-user-outreach.js

@@ -0,0 +1,119 @@
+import { writeDeliveryAttempt } from "../../../storage/delivery/write-delivery-attempt.js";
+import { writeOperatorFallback } from "../../../storage/fallback/write-operator-fallback.js";
+import { judgeOutreach } from "./judge-outreach.js";
+import { resolveDeliveryTarget } from "./delivery-target.js";
+import { buildOutreachDraftRequest } from "./build-outreach-draft-request.js";
+function toSourceRefs(refs) {
+    return refs.map((r) => ({ ...r }));
+}
+function hasDeliveryProof(attempt) {
+    return Boolean(attempt.messageId?.trim()) || Boolean(attempt.hostProofRef);
+}
+function operatorReasonForUnavailable(verdict) {
+    if (verdict === "target_none")
+        return "target_none";
+    if (verdict === "channel_missing")
+        return "channel_missing";
+    return "host_unsupported";
+}
+export async function dispatchUserOutreachIntent(input) {
+    const { candidate, snapshot, judgeInput, guidance, delivery, state } = input;
+    const judgment = judgeOutreach({ ...judgeInput, candidate });
+    if (judgment.verdict !== "allow") {
+        return {
+            scope: "rhythm",
+            status: judgment.verdict === "defer" ? "deferred" : "denied",
+            selectedIntentId: candidate.id,
+            reasons: judgment.reasons,
+            decisionId: judgment.decisionId,
+        };
+    }
+    const deliveryResolution = resolveDeliveryTarget(judgeInput.delivery);
+    if (deliveryResolution.verdict !== "target_available") {
+        const req = buildOutreachDraftRequest(candidate, judgment, snapshot, deliveryResolution);
+        const draft = await guidance.draftOutreachMessage(req);
+        const fb = await writeOperatorFallback(state, {
+            reason: operatorReasonForUnavailable(deliveryResolution.verdict),
+            decisionId: judgment.decisionId,
+            sourceRefs: toSourceRefs(judgment.sourceRefs),
+            candidateMessage: draft.status === "ready" ? draft.draft.text : undefined,
+            nextStep: "resolve_delivery_target_or_retry_after_host_update",
+        });
+        return {
+            scope: "rhythm",
+            status: "delivery_unavailable",
+            selectedIntentId: candidate.id,
+            reasons: [deliveryResolution.reason],
+            decisionId: judgment.decisionId,
+            fallbackRef: fb.fallbackRef,
+        };
+    }
+    const req = buildOutreachDraftRequest(candidate, judgment, snapshot, deliveryResolution);
+    const draft = await guidance.draftOutreachMessage(req);
+    if (draft.status !== "ready") {
+        return {
+            scope: "rhythm",
+            status: "denied",
+            selectedIntentId: candidate.id,
+            reasons: draft.reasons,
+            decisionId: judgment.decisionId,
+        };
+    }
+    const attempt = await delivery.sendDeliveryRequest({
+        decisionId: judgment.decisionId,
+        target: deliveryResolution.target,
+        channel: deliveryResolution.channel,
+        recipient: deliveryResolution.recipient,
+        message: draft.draft.text,
+        sourceRefs: judgment.sourceRefs,
+    });
+    if (attempt.status !== "sent" || !hasDeliveryProof(attempt)) {
+        const fb = await writeOperatorFallback(state, {
+            reason: "delivery_failed",
+            decisionId: judgment.decisionId,
+            sourceRefs: toSourceRefs(judgment.sourceRefs),
+            candidateMessage: draft.draft.text,
+            nextStep: "review_delivery_audit_and_host_capability",
+        });
+        const hostReportedSentWithoutProof = attempt.status === "sent" && !hasDeliveryProof(attempt);
+        await writeDeliveryAttempt(state, {
+            attemptId: attempt.id,
+            decisionId: judgment.decisionId,
+            target: deliveryResolution.target,
+            channel: deliveryResolution.channel,
+            status: attempt.status === "dropped_by_host_policy" ? "dropped_by_host_policy" : "failed",
+            errorClass: hostReportedSentWithoutProof
+                ? "delivery_proof_missing"
+                : attempt.errorClass ?? attempt.status,
+            fallbackRef: fb.fallbackRef,
+        });
+        return {
+            scope: "rhythm",
+            status: "delivery_unavailable",
+            selectedIntentId: candidate.id,
+            reasons: hostReportedSentWithoutProof
+                ? ["delivery_failed", "delivery_proof_missing"]
+                : ["delivery_failed", attempt.status],
+            decisionId: judgment.decisionId,
+            deliveryAttemptId: attempt.id,
+            fallbackRef: fb.fallbackRef,
+        };
+    }
+    await writeDeliveryAttempt(state, {
+        attemptId: attempt.id,
+        decisionId: judgment.decisionId,
+        target: deliveryResolution.target,
+        channel: deliveryResolution.channel,
+        status: "sent",
+        messageId: attempt.messageId?.trim(),
+        hostProofRef: attempt.hostProofRef,
+    });
+    return {
+        scope: "rhythm",
+        status: "intent_selected",
+        selectedIntentId: candidate.id,
+        reasons: ["outreach_sent"],
+        decisionId: judgment.decisionId,
+        deliveryAttemptId: attempt.id,
+    };
+}

package/runtime/core/second-nature/outreach/judge-input-from-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { SnapshotInputs } from "../heartbeat/snapshot-builder.js";
+import type { HeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
+import type { CandidateIntent } from "../types.js";
+import type { JudgeOutreachInput, JudgeOutreachUserInterest } from "./judge-outreach.js";
+import type { UserInterestSnapshot } from "../../../storage/user-interest/types.js";
+export declare function userInterestSnapshotToJudge(snapshot?: UserInterestSnapshot): JudgeOutreachUserInterest;
+export declare function buildJudgeOutreachInputFromSnapshot(intent: CandidateIntent, runtime: HeartbeatRuntimeSnapshot, inputs: SnapshotInputs): Omit<JudgeOutreachInput, "candidate">;

package/runtime/core/second-nature/outreach/judge-input-from-snapshot.js

@@ -0,0 +1,45 @@
+import { isLifeEvidenceSliceEmpty } from "../heartbeat/runtime-snapshot.js";
+function toControlPlaneRefs(refs) {
+    return refs.map((r) => ({
+        id: r.id,
+        kind: r.kind,
+        uri: r.uri,
+        excerptHash: r.excerptHash,
+        observedAt: r.observedAt,
+    }));
+}
+export function userInterestSnapshotToJudge(snapshot) {
+    if (!snapshot) {
+        return { staleness: "insufficient", confidence: 0, signals: [], sourceRefs: [] };
+    }
+    return {
+        staleness: snapshot.staleness,
+        confidence: snapshot.confidence,
+        signals: snapshot.signals.map((s) => ({
+            topic: s.topic,
+            confidence: s.confidence,
+            sourceRefs: s.sourceRefs.map((r) => ({
+                id: r.id,
+                kind: r.kind,
+                uri: r.uri,
+                excerptHash: r.excerptHash,
+                observedAt: r.observedAt,
+            })),
+        })),
+        sourceRefs: toControlPlaneRefs(snapshot.sourceRefs),
+    };
+}
+export function buildJudgeOutreachInputFromSnapshot(intent, runtime, inputs) {
+    const delivery = inputs.deliveryCapability ?? { target: "none" };
+    const key = intent.idempotencyKey ?? intent.id;
+    return {
+        userInterest: userInterestSnapshotToJudge(inputs.userInterestSnapshot),
+        lifeEvidence: {
+            empty: isLifeEvidenceSliceEmpty(runtime.lifeEvidence),
+            evidenceRefCount: runtime.lifeEvidence.evidenceRefs.length,
+        },
+        delivery,
+        duplicateBlocked: runtime.hardGuards.hasDuplicateIntent(key),
+        cooldownBlocked: !runtime.hardGuards.isOutreachCooldownClear(key),
+    };
+}

package/runtime/core/second-nature/outreach/judge-outreach.d.ts

@@ -0,0 +1,40 @@
+import type { CandidateIntent, ControlPlaneSourceRef } from "../types.js";
+import { type DeliveryCapabilitySnapshot, type DeliveryTargetResolution } from "./delivery-target.js";
+export type OutreachJudgmentVerdict = "allow" | "deny" | "defer";
+export type CooldownState = "clear" | "cooling_down" | "duplicate";
+export interface JudgeOutreachUserInterest {
+    staleness: "fresh" | "stale" | "insufficient";
+    confidence: number;
+    signals: Array<{
+        topic: string;
+        confidence: number;
+        sourceRefs: ControlPlaneSourceRef[];
+    }>;
+    sourceRefs: ControlPlaneSourceRef[];
+}
+export interface JudgeOutreachLifeEvidence {
+    empty: boolean;
+    evidenceRefCount: number;
+}
+export interface JudgeOutreachInput {
+    candidate: CandidateIntent;
+    userInterest: JudgeOutreachUserInterest;
+    lifeEvidence: JudgeOutreachLifeEvidence;
+    delivery: DeliveryCapabilitySnapshot;
+    duplicateBlocked?: boolean;
+    cooldownBlocked?: boolean;
+}
+export interface OutreachJudgment {
+    decisionId: string;
+    candidateId: string;
+    verdict: OutreachJudgmentVerdict;
+    valueScore: number;
+    userRelevance: number;
+    actionability: number;
+    interestRefs: ControlPlaneSourceRef[];
+    sourceRefs: ControlPlaneSourceRef[];
+    cooldownState: CooldownState;
+    deliveryVerdict: DeliveryTargetResolution["verdict"];
+    reasons: string[];
+}
+export declare function judgeOutreach(input: JudgeOutreachInput): OutreachJudgment;