@haaaiawd/second-nature 0.1.27 → 0.1.29

package/runtime/core/second-nature/heartbeat/embodied-context-assembler.js

@@ -0,0 +1,164 @@
+/**
+ * EmbodiedContextAssembler — T-CP.C.1
+ *
+ * Core logic: Assembles a complete EmbodiedContext from up to 7 read ports:
+ * - 5 state-memory slices via EmbodiedContextStatePort
+ * - affordanceMap via AffordanceAssembler
+ * - selfHealth via SelfHealthProvider (observability hook)
+ *
+ * Trim policies (DR-020):
+ * - recentInteractions: LIFO 10
+ * - toolExperience: LIFO 10
+ * - sourceRefs: deduplicated to 20 per slice
+ *
+ * Performance: P95 < 400ms for full assembly (DR-016).
+ *
+ * Dependencies:
+ * - `EmbodiedContextStatePort` from `../../../storage/services/embodied-context-state-port.js`
+ * - `AffordanceAssembler` from `../body/tool-affordance/affordance-assembler.js`
+ * - `EmbodiedContext` from `../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Candidate dream outputs are NOT included (DR-011).
+ * - Each slice gets its own loaded/degraded/blocked status.
+ * - Does NOT throw on partial failure; assembles best-effort context.
+ *
+ * Test coverage: tests/unit/control-plane/embodied-context-assembler.test.ts
+ */
+function trimLifo(arr, limit) {
+    if (arr.length <= limit)
+        return arr;
+    return arr.slice(-limit);
+}
+function dedupSourceRefs(items, limit) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        if (item.sourceRefs && item.sourceRefs.length > 0) {
+            const key = item.sourceRefs.join("|");
+            if (seen.has(key))
+                continue;
+            if (seen.size >= limit)
+                break;
+            seen.add(key);
+        }
+        result.push(item);
+    }
+    return result;
+}
+export function createEmbodiedContextAssembler(deps) {
+    const { statePort, affordanceAssembler, selfHealthProvider, options = {}, } = deps;
+    const interactionLimit = options.interactionLimit ?? 10;
+    const experienceLimit = options.experienceLimit ?? 10;
+    const profileId = options.profileId ?? "default";
+    return {
+        async assembleEmbodiedContext() {
+            const assembledAt = new Date().toISOString();
+            // ── 1. Identity ───────────────────────────────────────────
+            const identityResult = await statePort.loadIdentityProfile(profileId);
+            const identitySlice = identityResult.status === "loaded"
+                ? { status: "loaded", data: identityResult.data }
+                : identityResult.status === "degraded" && identityResult.data
+                    ? {
+                        status: "degraded",
+                        data: identityResult.data,
+                        reason: identityResult.reason,
+                    }
+                    : {
+                        status: "degraded",
+                        data: {},
+                        reason: identityResult.reason,
+                    };
+            // ── 2. Goals ──────────────────────────────────────────────
+            const goalsResult = await statePort.listActiveGoals(10);
+            const goalsSlice = goalsResult.status === "loaded"
+                ? { status: "loaded", data: goalsResult.data }
+                : { status: "degraded", data: [], reason: goalsResult.reason };
+            // ── 3. Recent Interactions (trim LIFO) ────────────────────
+            const interactionResult = await statePort.loadRecentInteractionSnapshot(interactionLimit);
+            const recentInteractionsSlice = interactionResult.status === "loaded"
+                ? {
+                    status: "loaded",
+                    data: trimLifo(interactionResult.data, interactionLimit),
+                }
+                : {
+                    status: "degraded",
+                    data: [],
+                    reason: interactionResult.reason,
+                };
+            // ── 4. Tool Experience (trim LIFO) ────────────────────────
+            const experienceResult = await statePort.loadToolExperienceSlice(experienceLimit);
+            const toolExperienceSlice = experienceResult.status === "loaded"
+                ? {
+                    status: "loaded",
+                    data: trimLifo(experienceResult.data, experienceLimit),
+                }
+                : {
+                    status: "degraded",
+                    data: [],
+                    reason: experienceResult.reason,
+                };
+            // ── 5. Accepted Dream ─────────────────────────────────────
+            const dreamResult = await statePort.loadAcceptedDreamProjection(3);
+            const acceptedDreamSlice = dreamResult.status === "loaded"
+                ? { status: "loaded", data: dreamResult.data }
+                : { status: "degraded", data: [], reason: dreamResult.reason };
+            // ── 6. Affordance Map ─────────────────────────────────────
+            let affordanceMapSlice;
+            try {
+                const affordanceMap = await affordanceAssembler.assembleAffordanceMap();
+                affordanceMapSlice = {
+                    status: "loaded",
+                    data: affordanceMap,
+                };
+            }
+            catch (err) {
+                affordanceMapSlice = {
+                    status: "degraded",
+                    data: {},
+                    reason: `affordance_assembly_failed:${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            // ── 7. Self Health (optional) ─────────────────────────────
+            let selfHealthSlice;
+            if (selfHealthProvider) {
+                try {
+                    const healthResult = await selfHealthProvider.loadSelfHealth();
+                    selfHealthSlice =
+                        healthResult.status === "loaded"
+                            ? { status: "loaded", data: healthResult.data }
+                            : {
+                                status: "degraded",
+                                data: {
+                                    snapshotId: "degraded",
+                                    dimensions: {},
+                                    checkedAt: assembledAt,
+                                },
+                                reason: healthResult.reason,
+                            };
+                }
+                catch (err) {
+                    selfHealthSlice = {
+                        status: "degraded",
+                        data: {
+                            snapshotId: "degraded",
+                            dimensions: {},
+                            checkedAt: assembledAt,
+                        },
+                        reason: `self_health_unavailable:${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }
+            return {
+                identity: identitySlice,
+                goals: goalsSlice,
+                recentInteractions: recentInteractionsSlice,
+                toolExperience: toolExperienceSlice,
+                acceptedDream: acceptedDreamSlice,
+                affordanceMap: affordanceMapSlice,
+                selfHealth: selfHealthSlice,
+                assembledAt,
+            };
+        },
+    };
+}

package/runtime/core/second-nature/heartbeat/goal-lifecycle-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GoalLifecyclePolicy — T-CP.C.3
+ *
+ * Core logic: Evaluates active goals, detects replace/expire
+ * conditions, and emits typed GoalTransitionRequest.
+ *
+ * Responsibility separation (DR-012):
+ * - control-plane evaluates and emits transition requests.
+ * - state-memory executes transitions via GoalLifecycleStore.
+ * - This module does NOT write goal state directly.
+ *
+ * Rules:
+ * - Same kind+scope: newest accepted goal stays active; older ones → replaced.
+ * - Expired goals (expiresAt < now) → expired transition request.
+ *
+ * Boundary:
+ * - Consumes AgentGoal[] from EmbodiedContext.goals slice.
+ * - Returns GoalTransitionRequest[] for state-memory to execute.
+ *
+ * Test coverage: tests/unit/control-plane/goal-lifecycle-policy.test.ts
+ */
+import type { AgentGoal } from "../../../shared/types/goal.js";
+export interface GoalTransitionRequest {
+    goalId: string;
+    newStatus: "completed" | "expired" | "replaced" | "paused" | "accepted";
+    reason: string;
+    updatedAt: string;
+}
+export interface GoalLifecyclePolicyResult {
+    activeGoals: AgentGoal[];
+    transitionRequests: GoalTransitionRequest[];
+    evaluatedAt: string;
+}
+export interface GoalLifecyclePolicy {
+    evaluate(goals: AgentGoal[]): GoalLifecyclePolicyResult;
+}
+export declare function createGoalLifecyclePolicy(): GoalLifecyclePolicy;

package/runtime/core/second-nature/heartbeat/goal-lifecycle-policy.js

@@ -0,0 +1,61 @@
+export function createGoalLifecyclePolicy() {
+    return {
+        evaluate(goals) {
+            const now = new Date().toISOString();
+            const activeGoals = [];
+            const transitionRequests = [];
+            // Group by kind+scope to detect duplicates among accepted goals
+            const groups = new Map();
+            for (const goal of goals) {
+                if (goal.status !== "accepted")
+                    continue;
+                const key = `${goal.kind}:${goal.scope ?? "global"}`;
+                const list = groups.get(key) ?? [];
+                list.push(goal);
+                groups.set(key, list);
+            }
+            for (const [key, list] of groups) {
+                // Sort by updatedAt desc, keep newest as active
+                const sorted = [...list].sort((a, b) => {
+                    const aTime = new Date(a.updatedAt).getTime();
+                    const bTime = new Date(b.updatedAt).getTime();
+                    if (isNaN(aTime) || isNaN(bTime))
+                        return 0;
+                    return bTime - aTime;
+                });
+                const [newest, ...older] = sorted;
+                if (newest) {
+                    activeGoals.push(newest);
+                    // Older same kind+scope goals → replace
+                    for (const old of older) {
+                        transitionRequests.push({
+                            goalId: old.goalId,
+                            newStatus: "replaced",
+                            reason: `same_kind_scope_replace:${key}`,
+                            updatedAt: now,
+                        });
+                    }
+                }
+            }
+            // Detect expired goals among active
+            for (const goal of activeGoals) {
+                if (goal.expiresAt) {
+                    const expiresTime = new Date(goal.expiresAt).getTime();
+                    if (!isNaN(expiresTime) && expiresTime < new Date(now).getTime()) {
+                        transitionRequests.push({
+                            goalId: goal.goalId,
+                            newStatus: "expired",
+                            reason: "expires_at_reached",
+                            updatedAt: now,
+                        });
+                    }
+                }
+            }
+            return {
+                activeGoals,
+                transitionRequests,
+                evaluatedAt: now,
+            };
+        },
+    };
+}

package/runtime/core/second-nature/heartbeat/idle-curiosity-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * IdleCuriosityPolicy — T-CP.C.3
+ *
+ * Core logic: When no active goal exists, selects at most one healthy,
+ * allowlisted, read-only sensing intent from the affordance map.
+ *
+ * Rules:
+ * - Only read-only capabilities (heuristic: intent ends with .read / .discover / .inspect / .search).
+ * - Only safe or exploratory affordance status.
+ * - Max one candidate per heartbeat.
+ * - 1-hour cooldown per platform.
+ * - No eligible connector → reason idle_policy_no_eligible_connector.
+ *
+ * Boundary:
+ * - Does NOT execute connector.
+ * - Returns a candidate descriptor, not an execution authorization.
+ *
+ * Test coverage: tests/unit/control-plane/idle-curiosity-policy.test.ts
+ */
+import type { AffordanceMap } from "../../../shared/types/v7-entities.js";
+export interface IdleCuriosityCandidate {
+    platformId: string;
+    capabilityId: string;
+    intent: string;
+    reason: string;
+}
+export interface IdleCuriosityPolicyResult {
+    candidate?: IdleCuriosityCandidate;
+    reason: string;
+}
+export interface IdleCuriosityPolicy {
+    select(affordanceMap: AffordanceMap, recentIdleHistory: {
+        platformId: string;
+        at: string;
+    }[]): IdleCuriosityPolicyResult;
+}
+export declare function createIdleCuriosityPolicy(): IdleCuriosityPolicy;

package/runtime/core/second-nature/heartbeat/idle-curiosity-policy.js

@@ -0,0 +1,60 @@
+const IDLE_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
+function isReadOnlyIntent(intent) {
+    return (intent.endsWith(".read") ||
+        intent.endsWith(".discover") ||
+        intent.endsWith(".inspect") ||
+        intent.endsWith(".search"));
+}
+export function createIdleCuriosityPolicy() {
+    return {
+        select(affordanceMap, recentIdleHistory) {
+            const now = Date.now();
+            // Build eligible list
+            const eligible = [];
+            for (const [platformId, items] of Object.entries(affordanceMap)) {
+                for (const item of items) {
+                    // Read-only only
+                    if (!isReadOnlyIntent(item.intent))
+                        continue;
+                    // Healthy status only
+                    if (item.status !== "safe" && item.status !== "exploratory")
+                        continue;
+                    // Check cooldown
+                    const lastIdle = recentIdleHistory
+                        .filter((h) => h.platformId === platformId)
+                        .sort((a, b) => {
+                        const aTime = new Date(a.at).getTime();
+                        const bTime = new Date(b.at).getTime();
+                        if (isNaN(aTime) || isNaN(bTime))
+                            return 0;
+                        return bTime - aTime;
+                    })[0];
+                    if (lastIdle) {
+                        const lastTime = new Date(lastIdle.at).getTime();
+                        if (!isNaN(lastTime)) {
+                            const elapsed = now - lastTime;
+                            if (elapsed < IDLE_COOLDOWN_MS)
+                                continue;
+                        }
+                    }
+                    eligible.push(item);
+                }
+            }
+            if (eligible.length === 0) {
+                return { reason: "idle_policy_no_eligible_connector" };
+            }
+            // Deterministic selection: first eligible by stable sort
+            const chosen = eligible.sort((a, b) => a.platformId.localeCompare(b.platformId) ||
+                a.capabilityId.localeCompare(b.capabilityId))[0];
+            return {
+                candidate: {
+                    platformId: chosen.platformId,
+                    capabilityId: chosen.capabilityId,
+                    intent: chosen.intent,
+                    reason: "idle_sensing_selected",
+                },
+                reason: "idle_sensing_selected",
+            };
+        },
+    };
+}

package/runtime/core/second-nature/heartbeat/index.d.ts

@@ -6,3 +6,7 @@ export { buildPlannerRhythmWindow, type PlannerRhythmWindowSlice } from "../rhyt
 export { runHeartbeatCycle, type RunHeartbeatCycleInput } from "./run-heartbeat-cycle.js";
 export { routeScopedInput, type ScopeRouterDeps, } from "./scope-router.js";
 export { requestGuidanceForIntent, dispatchAllowedEffect, executeHeartbeatCycle, type GuidanceBridgeDeps, type EffectDispatchDeps, type HeartbeatExecutorDeps, type GuidanceBridgeResult, type HeartbeatExecutionResult, } from "./heartbeat-executor.js";
+export { runHeartbeatV7, type HeartbeatDecision, type HeartbeatV7Deps, type RunHeartbeatV7Input, } from "./run-heartbeat-cycle-v7.js";
+export { createDecisionTraceEmitter, createNoOpTraceEmitter, type DecisionTracePayload, type DecisionTraceEmitter, } from "./decision-trace-emitter.js";
+export { createGoalLifecyclePolicy, type GoalLifecyclePolicy, type GoalTransitionRequest, type GoalLifecyclePolicyResult, } from "./goal-lifecycle-policy.js";
+export { createIdleCuriosityPolicy, type IdleCuriosityPolicy, type IdleCuriosityCandidate, type IdleCuriosityPolicyResult, } from "./idle-curiosity-policy.js";

package/runtime/core/second-nature/heartbeat/index.js

@@ -5,3 +5,8 @@ export { buildPlannerRhythmWindow } from "../rhythm/planner-rhythm-window.js";
 export { runHeartbeatCycle } from "./run-heartbeat-cycle.js";
 export { routeScopedInput, } from "./scope-router.js";
 export { requestGuidanceForIntent, dispatchAllowedEffect, executeHeartbeatCycle, } from "./heartbeat-executor.js";
+/* Wave 57 — v7 heartbeat main loop + goal/idle policy */
+export { runHeartbeatV7, } from "./run-heartbeat-cycle-v7.js";
+export { createDecisionTraceEmitter, createNoOpTraceEmitter, } from "./decision-trace-emitter.js";
+export { createGoalLifecyclePolicy, } from "./goal-lifecycle-policy.js";
+export { createIdleCuriosityPolicy, } from "./idle-curiosity-policy.js";

package/runtime/core/second-nature/heartbeat/run-heartbeat-cycle-v7.d.ts

@@ -0,0 +1,63 @@
+/**
+ * runHeartbeatV7 — T-CP.C.2
+ *
+ * Core logic: v7 heartbeat main loop entry.
+ * - Scope routing (rhythm / user_task / user_reply)
+ * - EmbodiedContext assembly via EmbodiedContextAssembler
+ * - Candidate planning via injected CandidateIntentPlanner
+ * - Hard guard evaluation with affordance + breaker awareness
+ * - Downstream request orchestration
+ * - Decision trace emission
+ *
+ * Performance: assembly + planning + guards P95 < 2s.
+ *   Exceeding samples are marked degraded but do not crash.
+ *
+ * Boundary:
+ * - Does NOT write state, execute connectors, or generate guidance copy.
+ * - Returns HeartbeatDecision; downstream execution is delegated.
+ *
+ * Dependencies:
+ * - EmbodiedContextAssembler from ./embodied-context-assembler.js
+ * - evaluateHardGuards from ../orchestrator/hard-guard-evaluator.js
+ * - createDownstreamIntentOrchestrator from ../orchestrator/downstream-intent-orchestrator.js
+ * - createDecisionTraceEmitter from ./decision-trace-emitter.js
+ * - routeScopedInput from ./scope-router.js
+ *
+ * Test coverage:
+ * - tests/unit/control-plane/run-heartbeat-cycle-v7.test.ts
+ * - tests/integration/control-plane/heartbeat-loop.test.ts
+ */
+import type { HeartbeatSignal, RuntimeScope } from "./signal.js";
+import type { EmbodiedContextAssembler } from "./embodied-context-assembler.js";
+import type { CandidateIntent, GuardEvaluation } from "../types.js";
+import type { HardGuardEvaluatorDeps } from "../orchestrator/hard-guard-evaluator.js";
+import type { DownstreamIntentOrchestrator } from "../orchestrator/downstream-intent-orchestrator.js";
+import type { DecisionTraceEmitter } from "./decision-trace-emitter.js";
+import type { EmbodiedContext } from "../../../shared/types/v7-entities.js";
+export type HeartbeatDecisionStatus = "heartbeat_ok" | "intent_selected" | "deferred" | "denied" | "delivery_unavailable" | "runtime_carrier_only";
+export interface HeartbeatDecision {
+    decisionId: string;
+    scope: RuntimeScope;
+    status: HeartbeatDecisionStatus;
+    selectedIntentId?: string;
+    downstreamRequestId?: string;
+    reasons: string[];
+    contextId?: string;
+}
+export interface CandidateIntentPlanner {
+    planCandidates(context: EmbodiedContext): CandidateIntent[];
+}
+export interface HeartbeatV7Deps {
+    assembler: EmbodiedContextAssembler;
+    planner: CandidateIntentPlanner;
+    evaluateHardGuards: (intent: CandidateIntent, deps: HardGuardEvaluatorDeps) => GuardEvaluation;
+    buildGuardDeps: (context: EmbodiedContext) => HardGuardEvaluatorDeps;
+    downstreamOrchestrator: DownstreamIntentOrchestrator;
+    traceEmitter: DecisionTraceEmitter;
+}
+export interface RunHeartbeatV7Input {
+    signal: HeartbeatSignal;
+    runtimeAvailable: boolean;
+    deps: HeartbeatV7Deps;
+}
+export declare function runHeartbeatV7(input: RunHeartbeatV7Input): Promise<HeartbeatDecision>;

package/runtime/core/second-nature/heartbeat/run-heartbeat-cycle-v7.js

@@ -0,0 +1,118 @@
+import { routeScopedInput } from "./scope-router.js";
+const P95_MS = 2000;
+export async function runHeartbeatV7(input) {
+    const { signal, runtimeAvailable, deps } = input;
+    // ── Scope routing ─────────────────────────────────────────────
+    const payload = typeof signal.payload === "object" &&
+        signal.payload !== null &&
+        !Array.isArray(signal.payload)
+        ? signal.payload
+        : {};
+    const scoped = {
+        trigger: signal.trigger,
+        scopeHint: signal.scopeHint,
+        payload,
+    };
+    const route = routeScopedInput(scoped);
+    // Runtime availability gate
+    if (!runtimeAvailable) {
+        return {
+            decisionId: `decision:carrier:${Date.now()}`,
+            scope: route.scope,
+            status: "runtime_carrier_only",
+            reasons: ["runtime_unavailable_no_lived_experience_loop"],
+        };
+    }
+    // User task bypass
+    if (route.scope === "user_task") {
+        return {
+            decisionId: `decision:user_task:${Date.now()}`,
+            scope: "user_task",
+            status: "heartbeat_ok",
+            reasons: ["rhythm_gate_bypass_user_task"],
+        };
+    }
+    // User reply light path
+    if (route.scope === "user_reply") {
+        return {
+            decisionId: `decision:user_reply:${Date.now()}`,
+            scope: "user_reply",
+            status: "heartbeat_ok",
+            reasons: ["user_reply_light_continuity_skeleton"],
+        };
+    }
+    // ── Rhythm path: assemble embodied context ──────────────────
+    const assemblyStart = Date.now();
+    const context = await deps.assembler.assembleEmbodiedContext();
+    const assemblyMs = Date.now() - assemblyStart;
+    const contextId = `ctx:${Date.now()}`;
+    // Build guard deps from assembled context
+    const guardDeps = deps.buildGuardDeps(context);
+    // Plan candidates
+    const candidates = deps.planner.planCandidates(context);
+    // Evaluate guards and select first allowed
+    for (const intent of candidates) {
+        const evaluation = deps.evaluateHardGuards(intent, guardDeps);
+        if (evaluation.verdict === "allow") {
+            const downstream = deps.downstreamOrchestrator.orchestrate(intent);
+            const decisionId = `decision:${intent.id}:${Date.now()}`;
+            const result = {
+                decisionId,
+                scope: "rhythm",
+                status: "intent_selected",
+                selectedIntentId: intent.id,
+                downstreamRequestId: downstream.kind === "none"
+                    ? undefined
+                    : `${downstream.kind}:${decisionId}`,
+                reasons: evaluation.reasons.length > 0
+                    ? evaluation.reasons
+                    : ["guard_allow"],
+                contextId,
+            };
+            // P95 degradation note (does not change status per T-CP.C.2 acceptance)
+            if (assemblyMs > P95_MS) {
+                result.reasons.push(`heartbeat_degraded:assembly_p95_exceeded:${assemblyMs}ms`);
+            }
+            await safeEmitTrace(deps.traceEmitter, result, contextId);
+            return result;
+        }
+        if (evaluation.verdict === "defer") {
+            continue;
+        }
+        // deny / escalate → continue to next candidate
+    }
+    // ── No allowed candidates ────────────────────────────────────
+    const decisionId = `decision:no_allow:${Date.now()}`;
+    const result = {
+        decisionId,
+        scope: "rhythm",
+        status: candidates.length === 0 ? "heartbeat_ok" : "deferred",
+        reasons: candidates.length === 0
+            ? ["silent_no_candidates"]
+            : ["no_allow_verdict"],
+        contextId,
+    };
+    if (assemblyMs > P95_MS) {
+        result.reasons.push(`heartbeat_degraded:assembly_p95_exceeded:${assemblyMs}ms`);
+    }
+    await safeEmitTrace(deps.traceEmitter, result, contextId);
+    return result;
+}
+async function safeEmitTrace(emitter, decision, contextId) {
+    const trace = {
+        traceId: `trace:${decision.decisionId}`,
+        decisionId: decision.decisionId,
+        contextId,
+        scope: decision.scope,
+        status: decision.status,
+        reasons: decision.reasons,
+        selectedIntentId: decision.selectedIntentId,
+        emittedAt: new Date().toISOString(),
+    };
+    try {
+        await emitter.emit(trace);
+    }
+    catch {
+        // Trace emission must not block the heartbeat cycle
+    }
+}

package/runtime/core/second-nature/orchestrator/downstream-intent-orchestrator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DownstreamIntentOrchestrator — T-CP.C.2
+ *
+ * Core logic: Maps an allowed CandidateIntent to a typed downstream request.
+ * Does NOT own downstream implementation — only constructs the request envelope.
+ *
+ * Boundary:
+ * - Returns typed request objects; caller delegates to connector-system,
+ *   dream-quiet-system, or guidance-voice-system.
+ * - maintenance/no_effect intents produce "none" requests (no downstream).
+ *
+ * Test coverage: tests/unit/control-plane/downstream-intent-orchestrator.test.ts
+ */
+import type { CandidateIntent } from "../types.js";
+export interface ConnectorIntentRequest {
+    kind: "connector_intent";
+    platformId: string;
+    capabilityId?: string;
+    payload: Record<string, unknown>;
+}
+export interface QuietRunRequest {
+    kind: "quiet_run";
+    reason: string;
+}
+export interface DreamScheduleRequest {
+    kind: "dream_schedule";
+    reason: string;
+}
+export interface GuidanceDraftRequest {
+    kind: "guidance_draft";
+    targetChannel?: string;
+    evidenceRefs: string[];
+}
+export type DownstreamRequest = ConnectorIntentRequest | QuietRunRequest | DreamScheduleRequest | GuidanceDraftRequest | {
+    kind: "none";
+    reason: string;
+};
+export interface DownstreamIntentOrchestrator {
+    orchestrate(intent: CandidateIntent): DownstreamRequest;
+}
+export declare function createDownstreamIntentOrchestrator(): DownstreamIntentOrchestrator;

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

@@ -0,0 +1,43 @@
+export function createDownstreamIntentOrchestrator() {
+    return {
+        orchestrate(intent) {
+            switch (intent.effectClass) {
+                case "connector_action":
+                case "external_platform_action":
+                    return {
+                        kind: "connector_intent",
+                        platformId: intent.platformId ?? "unknown",
+                        capabilityId: intent.capabilityIntent,
+                        payload: {
+                            sourceRefs: intent.sourceRefs.map((r) => r.id),
+                            summary: intent.summary,
+                        },
+                    };
+                case "user_outreach":
+                    return {
+                        kind: "guidance_draft",
+                        targetChannel: intent.platformId,
+                        evidenceRefs: intent.sourceRefs.map((r) => r.id),
+                    };
+                case "narrative_reflection":
+                    return { kind: "quiet_run", reason: "narrative_reflection" };
+                case "maintenance":
+                case "no_effect":
+                    return {
+                        kind: "none",
+                        reason: "no_downstream_for_maintenance",
+                    };
+                case "memory_curation":
+                    return {
+                        kind: "dream_schedule",
+                        reason: "memory_curation",
+                    };
+                default:
+                    return {
+                        kind: "none",
+                        reason: `unhandled_effect_class:${intent.effectClass}`,
+                    };
+            }
+        },
+    };
+}

package/runtime/core/second-nature/orchestrator/effect-dispatcher.d.ts

@@ -6,6 +6,7 @@ export interface AllowedIntent {
     kind: "work" | "exploration" | "social" | "quiet" | "reflection" | "outreach" | "maintenance";
     summary: string;
     effectClass: EffectClass;
+    capabilityIntent?: string;
     platformId?: string;
     payload?: Record<string, unknown>;
 }
@@ -74,7 +75,7 @@ export type DispatchResult = {
     status: "maintenance_done";
     commitId: string;
 };
-export declare function toCapabilityIntent(intent: Pick<AllowedIntent, "kind">): CapabilityIntent;
+export declare function toCapabilityIntent(intent: Pick<AllowedIntent, "kind" | "capabilityIntent">): CapabilityIntent;
 export declare class EffectDispatcher {
     private readonly leaseManager;
     private readonly commitPort;