@haaaiawd/second-nature 0.1.43 → 0.1.50

package/dist/src/cli/ops/workspace-heartbeat-runner.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Wires CLI read models into control-plane `runHeartbeatCycle` for `heartbeat_check` (US-001 / CH-09-02 / T1.2.3).
+ *
+ * Snapshot inputs are derived from aggregated status; delivery defaults to none until host capability is modeled here.
+ *
+ * T1.2.3: when a `RuntimeDecisionRecorder` is provided, persist a `sn-runtime-*` ledger row +
+ * `second-nature-runtime` execution attempt after each cycle so `loadStatus` exits its `unknown`
+ * baseline once the runtime has actually executed at least one full-runtime turn.
+ *
+ * T2.2.2: when `state` + `workspaceRoot` are supplied, call `loadLifeEvidenceSnapshot` to fill
+ * `lifeEvidenceRefs`, `platformEventCount`, `workEventCount`, and `lifeEvidenceEmptyReason` on
+ * `SnapshotInputs` so planner/guard paths that require source refs see real DB truth.
+ * Falls back gracefully to `lifeEvidenceEmptyReason: "state_unavailable"` when state is absent.
+ */
+import type { HeartbeatSignal, HeartbeatCycleResult } from "../../core/second-nature/heartbeat/signal.js";
+import type { SnapshotInputs } from "../../core/second-nature/heartbeat/snapshot-builder.js";
+import type { CliReadModels } from "../read-models/index.js";
+import type { RuntimeDecisionRecorder } from "../../observability/services/runtime-decision-recorder.js";
+import type { StateDatabase } from "../../storage/db/index.js";
+import type { ConnectorExecutor } from "../../core/second-nature/orchestrator/effect-dispatcher.js";
+import type { CapabilityContractRegistry } from "../../connectors/base/manifest.js";
+import type { AffordanceMap } from "../../shared/types/v7-entities.js";
+import type { ExperienceWriter } from "../../core/second-nature/body/tool-experience/experience-writer.js";
+import type { QuietDreamSchedulePort } from "../../core/second-nature/quiet/run-source-backed-quiet.js";
+import { type HeartbeatDigestAssemblerDeps } from "../../observability/services/heartbeat-digest-assembler.js";
+import type { GoalLifecyclePolicy } from "../../core/second-nature/heartbeat/goal-lifecycle-policy.js";
+import type { IdleCuriosityPolicy } from "../../core/second-nature/heartbeat/idle-curiosity-policy.js";
+import type { CircuitBreakerManager } from "../../core/second-nature/body/circuit-breaker/circuit-breaker-manager.js";
+export interface WorkspaceHeartbeatRunnerOptions {
+    /** When supplied, the runner persists the cycle so `loadStatus` can read it (T1.2.3). */
+    runtimeRecorder?: RuntimeDecisionRecorder;
+    /**
+     * T2.2.2: when state + workspaceRoot are provided, life evidence is loaded from DB and merged
+     * into SnapshotInputs so planner/guard paths have real source-ref truth.
+     */
+    state?: StateDatabase;
+    workspaceRoot?: string;
+    /**
+     * T1.2.4: when true (and workspaceRoot is set), inject a `quietWorkflow` dep into the heartbeat
+     * cycle so quiet/reflection intents can call `runSourceBackedQuiet` and write artifacts to disk.
+     * Defaults to true when workspaceRoot is provided, since this is the host-safe workspace path.
+     */
+    enableQuietWorkflow?: boolean;
+    /**
+     * When present, guard-allowed connector_action intents are dispatched through the
+     * connector-system instead of returning connector_dispatch_unwired.
+     */
+    connectorExecutor?: ConnectorExecutor;
+    /**
+     * T2.4.1: when present, planner resolves platform-specific intents from accepted goals
+     * and connector evidence.
+     */
+    connectorRegistry?: CapabilityContractRegistry;
+    /** v7 T-V7C.C.2: affordance map for breaker-aware guard evaluation. */
+    affordanceMap?: AffordanceMap;
+    /** v7 T-V7C.C.2: experience writer for heartbeat connector attempts. */
+    experienceWriter?: ExperienceWriter;
+    /** v7 T-V7C.C.3: when present, a successful Quiet write auto-triggers Dream scheduling. */
+    dreamSchedulePort?: QuietDreamSchedulePort;
+    /** v7 T-CP.C.3: goal lifecycle policy for evaluating goal transitions before planning. */
+    goalLifecyclePolicy?: GoalLifecyclePolicy;
+    /** v7 T-CP.C.3: idle curiosity policy for read-only sensing when no active goals exist. */
+    idleCuriosityPolicy?: IdleCuriosityPolicy;
+    /** v7 T-BTS.C.5: circuit breaker manager for tracking connector execution health. */
+    circuitBreakerManager?: CircuitBreakerManager;
+    /**
+     * v7 T-V7C.C.3: when present, generates a HeartbeatDigest after each cycle
+     * (inside the digest window hour, if specified) and attempts delivery.
+     * Digest delivery failure is recorded as fallbackReason — never blocks the cycle.
+     */
+    digestOpts?: {
+        assemblerDeps: HeartbeatDigestAssemblerDeps;
+        /**
+         * UTC hour (0–23) at which to attempt digest generation.
+         * If unset, digest is generated on every cycle (for testing / always-on mode).
+         */
+        digestWindowHour?: number;
+    };
+}
+export declare function loadSnapshotInputsForWorkspaceHeartbeat(readModels: CliReadModels, options?: {
+    state?: StateDatabase;
+    workspaceRoot?: string;
+    affordanceMap?: AffordanceMap;
+}): Promise<SnapshotInputs>;
+export declare function createWorkspaceHeartbeatRunner(readModels: CliReadModels, options?: WorkspaceHeartbeatRunnerOptions): (signal: HeartbeatSignal) => Promise<HeartbeatCycleResult>;

package/dist/src/cli/ops/workspace-heartbeat-runner.js

@@ -0,0 +1,242 @@
+import { runHeartbeatCycle } from "../../core/second-nature/heartbeat/run-heartbeat-cycle.js";
+import { loadLifeEvidenceSnapshot } from "../../storage/snapshots/life-evidence-snapshot.js";
+import { createAgentGoalStore } from "../../storage/goal/agent-goal-store.js";
+import { createNarrativeStateStore } from "../../storage/narrative/narrative-state-store.js";
+import { createRelationshipMemoryStore } from "../../storage/relationship/relationship-memory-store.js";
+import { createIdentityProfileStore } from "../../storage/services/identity-profile-store.js";
+import { generateHeartbeatDigest, } from "../../observability/services/heartbeat-digest-assembler.js";
+import { createHistoryDigestStore } from "../../storage/services/history-digest-store.js";
+export async function loadSnapshotInputsForWorkspaceHeartbeat(readModels, options = {}) {
+    const status = await readModels.loadStatus();
+    const mode = status.rhythm.mode === "unknown" ? "active" : status.rhythm.mode;
+    // CH-15-03: quietEnabledBridge should reflect whether the quiet *execution path* is wired
+    // (workspaceRoot available), not whether the last observed rhythm decision was "quiet".
+    // status.quiet.mode is typically "unknown" until a Quiet artifact has been persisted, which
+    // means binding to it would permanently suppress the quiet window — the opposite of intent.
+    // We instead enable the bridge whenever workspaceRoot is provided (same condition as
+    // `createWorkspaceHeartbeatRunner` uses for injecting quietWorkflow).
+    const quietEnabledBridge = !!options.workspaceRoot;
+    // T2.2.2: Load life evidence from state DB when available so SnapshotInputs carries real refs.
+    let lifeEvidenceRefs;
+    let platformEventCount;
+    let workEventCount;
+    let lifeEvidenceEmptyReason;
+    if (options.state && options.workspaceRoot) {
+        try {
+            const snapshot = await loadLifeEvidenceSnapshot(options.state, options.workspaceRoot, { limit: 50 }, 
+            // Skip repair gate here — runner is called inside a live cycle; gate ran at startup.
+            { runRepairGate: false });
+            lifeEvidenceRefs = snapshot.evidenceRefs.map((ref) => ({
+                id: ref.id,
+                kind: ref.kind,
+                uri: ref.uri,
+            }));
+            platformEventCount = snapshot.platformEvents.length;
+            workEventCount = snapshot.workEvents.length;
+            if (snapshot.empty) {
+                // L-01: Currently snapshot only exposes `empty` boolean.
+                // Future: if snapshot adds `emptyReason` (e.g. "redacted_only"), map it here.
+                lifeEvidenceEmptyReason = "no_sources";
+            }
+        }
+        catch {
+            // If evidence load fails, signal state_unavailable rather than crashing the cycle.
+            lifeEvidenceRefs = [];
+            platformEventCount = 0;
+            workEventCount = 0;
+            lifeEvidenceEmptyReason = "state_unavailable";
+        }
+    }
+    else {
+        // No state wired — record that life evidence wasn't loaded so guards can reason honestly.
+        lifeEvidenceEmptyReason = "state_unavailable";
+    }
+    // T2.1.4: Load accepted goals from state DB when available.
+    // M-03: typed as GoalContext to avoid coupling to the full AgentGoal schema.
+    let acceptedGoals;
+    let acceptedGoalsLoadError;
+    if (options.state) {
+        try {
+            const goalStore = createAgentGoalStore(options.state);
+            acceptedGoals = await goalStore.listAgentGoals({
+                statuses: ["accepted"],
+                limit: 20,
+            });
+        }
+        catch (err) {
+            acceptedGoals = [];
+            acceptedGoalsLoadError = err instanceof Error ? err.message : String(err);
+            // H-05: Distinguish "load failed" from "no goals" for observability.
+        }
+    }
+    // CR-02: Load narrative state and relationship memory when state is available.
+    let narrativeState;
+    let relationshipMemory;
+    let identity;
+    if (options.state) {
+        try {
+            const narrativeStore = createNarrativeStateStore(options.state);
+            narrativeState = (await narrativeStore.loadNarrativeState()) ?? undefined;
+        }
+        catch {
+            // Narrative state is optional; failure should not block the cycle.
+        }
+        try {
+            const relationshipStore = createRelationshipMemoryStore(options.state);
+            relationshipMemory = (await relationshipStore.loadRelationshipMemory()) ?? undefined;
+        }
+        catch {
+            // Relationship memory is optional; failure should not block the cycle.
+        }
+        try {
+            const identityStore = createIdentityProfileStore(options.state);
+            const identityResult = await identityStore.loadIdentityProfile("default");
+            if (identityResult.status === "loaded" && identityResult.profile) {
+                identity = identityResult.profile;
+            }
+        }
+        catch {
+            // Identity is optional; failure should not block the cycle.
+        }
+    }
+    return {
+        mode,
+        currentWindowId: status.rhythm.windowId ?? "workspace-default",
+        pendingObligations: [],
+        recentOutreachHashes: [],
+        deniedIntents: [],
+        budgets: { socialUsed: 0, socialLimit: 5 },
+        awaitingUserInput: false,
+        quietEnabledBridge,
+        deliveryCapability: { target: "none" },
+        lifeEvidenceRefs,
+        platformEventCount,
+        workEventCount,
+        lifeEvidenceEmptyReason,
+        acceptedGoals,
+        acceptedGoalsLoadError,
+        narrativeState,
+        relationshipMemory,
+        affordanceMap: options.affordanceMap,
+        identity,
+    };
+}
+export function createWorkspaceHeartbeatRunner(readModels, options = {}) {
+    // T1.2.4: inject quietWorkflow dep when workspaceRoot is set so quiet/reflection intents
+    // can trigger runSourceBackedQuiet and persist artifacts to disk.
+    const quietEnabled = options.workspaceRoot && options.enableQuietWorkflow !== false;
+    // T2.1.5: when state DB is wired, create a NarrativeStateStore for heartbeat updates.
+    const narrativeStateStore = options.state
+        ? createNarrativeStateStore(options.state)
+        : undefined;
+    return async (signal) => {
+        const cycle = await runHeartbeatCycle({
+            signal,
+            runtimeAvailable: true,
+            deps: {
+                loadSnapshotInputs: () => loadSnapshotInputsForWorkspaceHeartbeat(readModels, {
+                    state: options.state,
+                    workspaceRoot: options.workspaceRoot,
+                    affordanceMap: options.affordanceMap,
+                }),
+                // T1.2.4: pass quietWorkflow dep so runSourceBackedQuiet can persist artifacts.
+                quietWorkflow: quietEnabled
+                    ? {
+                        workspaceRoot: options.workspaceRoot,
+                        // v7 T-V7C.C.3: pass Dream schedule port so Quiet completion triggers Dream.
+                        dreamSchedulePort: options.dreamSchedulePort,
+                    }
+                    : undefined,
+                connectorExecutor: options.connectorExecutor,
+                narrativeStateStore,
+                // T3.3.1: pass state + workspaceRoot so connector effects can write life evidence.
+                state: options.state,
+                workspaceRoot: options.workspaceRoot,
+                // T2.4.1: pass registry so planner resolves platform-specific intents.
+                connectorRegistry: options.connectorRegistry,
+                // v7 T-V7C.C.2: pass experience writer for heartbeat connector attempts.
+                experienceWriter: options.experienceWriter,
+                // v7 T-CP.C.3: pass goal lifecycle policy for pre-planning goal evaluation.
+                goalLifecyclePolicy: options.goalLifecyclePolicy,
+                // v7 T-CP.C.3: pass idle curiosity policy for goal-less exploration.
+                idleCuriosityPolicy: options.idleCuriosityPolicy,
+                // v7 T-BTS.C.5: pass circuit breaker manager for execution health tracking.
+                circuitBreakerManager: options.circuitBreakerManager,
+            },
+        });
+        if (options.runtimeRecorder) {
+            try {
+                await options.runtimeRecorder.recordHeartbeatCycle({ cycle, signal });
+            }
+            catch {
+                // T1.2.3: recorder must never break the heartbeat surface response.
+                // Failure here means status simply remains at its previous aggregate; the
+                // cycle outcome itself is still returned to the caller.
+            }
+        }
+        // v7 T-V7C.C.3 / T-V7C.C.6: After each cycle, attempt HeartbeatDigest generation
+        // and persist to heartbeat_digest table so the digest index actually grows.
+        // Only runs inside the designated UTC digest window hour, or on every cycle when
+        // digestWindowHour is unset (test / always-on mode).
+        if (options.digestOpts) {
+            const { assemblerDeps, digestWindowHour } = options.digestOpts;
+            const nowHour = new Date().getUTCHours();
+            const inDigestWindow = digestWindowHour === undefined || nowHour === digestWindowHour;
+            if (inDigestWindow) {
+                try {
+                    const date = new Date().toISOString().slice(0, 10);
+                    const assembledDigest = await generateHeartbeatDigest(date, assemblerDeps);
+                    // v7 T-V7C.C.6: Persist assembled digest to heartbeat_digest table when state DB is wired.
+                    if (options.state) {
+                        const digestStore = createHistoryDigestStore(options.state);
+                        await digestStore.writeHeartbeatDigest(toStoreDigest(assembledDigest));
+                    }
+                }
+                catch (err) {
+                    // Digest generation / persistence must not break the heartbeat cycle response.
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.warn(`[workspace-heartbeat-runner] Digest generation/persistence failed: ${msg}`);
+                }
+            }
+        }
+        return cycle;
+    };
+}
+/**
+ * Bridge: converts the assembler-facing HeartbeatDigest into the storage-facing
+ * HeartbeatDigest (shared/types/v7-entities.ts) so it can be written to heartbeat_digest.
+ *
+ * The two shapes diverge by design: assembler is an audit-aggregate rich view;
+ * store is a flattened day-keyed row. Mapping is lossy but sufficient for growth.
+ */
+function toStoreDigest(d) {
+    return {
+        digestId: `digest:${d.date}:${Date.now()}`,
+        day: d.date,
+        connectorSummary: d.connectorSummary.map((c) => ({
+            platformId: c.platformId,
+            status: c.blockedCount > 0
+                ? "blocked"
+                : c.circuitOpenCount > 0
+                    ? "blocked"
+                    : c.failureCount > 0
+                        ? "degraded"
+                        : "ok",
+            attemptCount: c.successCount + c.failureCount + c.blockedCount,
+        })),
+        goalSummary: [
+            { kind: "new", activeCount: d.goalSummary.newGoals },
+            { kind: "completed", activeCount: d.goalSummary.completedGoals },
+            { kind: "expired", activeCount: d.goalSummary.expiredGoals },
+            { kind: "replaced", activeCount: d.goalSummary.replacedGoals },
+            { kind: "active", activeCount: d.goalSummary.activeGoals },
+        ].filter((g) => g.activeCount > 0),
+        quietCount: d.quietDreamSummary.quietRuns,
+        dreamCount: d.quietDreamSummary.dreamRuns,
+        breakerSummary: d.healthSummary.circuitBreakerChanges > 0
+            ? [{ connectorId: "aggregate", state: "changed" }]
+            : [],
+        healthStatus: d.healthSummary.auditChainHealthy ? "ok" : "degraded",
+        createdAt: d.generatedAt,
+    };
+}

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

@@ -0,0 +1,24 @@
+export interface GoalTransitionRequest {
+    goalId: string;
+    newStatus: "completed" | "expired" | "replaced" | "paused" | "accepted";
+    reason: string;
+    updatedAt: string;
+}
+/** Minimal goal shape required by the lifecycle policy evaluator. */
+export interface EvaluableGoal {
+    goalId: string;
+    kind?: string;
+    scope?: string;
+    status: string;
+    updatedAt?: string;
+    expiresAt?: string;
+}
+export interface GoalLifecyclePolicyResult {
+    activeGoals: EvaluableGoal[];
+    transitionRequests: GoalTransitionRequest[];
+    evaluatedAt: string;
+}
+export interface GoalLifecyclePolicy {
+    evaluate(goals: EvaluableGoal[]): GoalLifecyclePolicyResult;
+}
+export declare function createGoalLifecyclePolicy(): GoalLifecyclePolicy;

package/dist/src/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 ?? 0).getTime();
+                    const bTime = new Date(b.updatedAt ?? 0).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/dist/src/core/second-nature/heartbeat/heartbeat-loop.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Heartbeat Decision Loop
+ *
+ * Main entry point for the heartbeat runtime. Accepts a HeartbeatSignal,
+ * builds runtime snapshot, plans candidate intents, evaluates hard guards,
+ * and returns a HeartbeatCycleResult.
+ *
+ * Per design doc §4.3: heartbeat round follows the sequence:
+ * signal → snapshot → plan → guard → result (HEARTBEAT_OK or intent_selected)
+ *
+ * Per ADR-005: heartbeat is the free-rhythm main entry; this loop
+ * implements the default conservative path where HEARTBEAT_OK is
+ * the first-class result when no action is warranted.
+ */
+import type { HeartbeatSignal, HeartbeatCycleResult, HeartbeatCycleStatus, RuntimeScope, RuntimeTrigger } from "./signal.js";
+import type { CandidateIntent, ContinuitySnapshot, IntentKind } from "../types.js";
+import { type SnapshotInputs } from "./snapshot-builder.js";
+import { type HeartbeatRuntimeSnapshot } from "./runtime-snapshot.js";
+import type { GuidanceDraftPort } from "../../../guidance/outreach-draft-schema.js";
+import type { StateDatabase } from "../../../storage/db/index.js";
+import { type OpenClawDeliveryPort } from "../outreach/dispatch-user-outreach.js";
+import type { ConnectorExecutor } from "../../../connectors/base/contract.js";
+import type { CapabilityContractRegistry } from "../../../connectors/base/manifest.js";
+import type { NarrativeStateStore } from "../../../storage/narrative/narrative-state-store.js";
+import type { NarrativeTracePayload } from "../../../observability/services/lived-experience-audit.js";
+import type { ExperienceWriter } from "../body/tool-experience/experience-writer.js";
+import type { QuietDreamSchedulePort } from "../quiet/run-source-backed-quiet.js";
+import type { GoalLifecyclePolicy } from "./goal-lifecycle-policy.js";
+import type { IdleCuriosityPolicy } from "./idle-curiosity-policy.js";
+import type { CircuitBreakerManager } from "../body/circuit-breaker/circuit-breaker-manager.js";
+export interface HeartbeatDecisionTracePayload {
+    scope: RuntimeScope;
+    status: HeartbeatCycleStatus;
+    reasons: string[];
+    selectedIntentId?: string;
+    rhythmWindowId: string;
+    allowedIntentKinds: IntentKind[];
+    candidateCount: number;
+    lifeEvidenceEmpty: boolean;
+    trigger: RuntimeTrigger;
+}
+/** Optional outreach delivery chain: when set, first allowed `user_outreach` runs dispatch (CR-M1). */
+export interface HeartbeatOutreachDispatchDeps {
+    state: StateDatabase;
+    guidance: GuidanceDraftPort;
+    delivery: OpenClawDeliveryPort;
+}
+/** Optional Quiet orchestration: when set, quiet/reflection allows run source-backed Quiet writer (T2.3.3). */
+export interface HeartbeatQuietWorkflowDeps {
+    workspaceRoot: string;
+    /** v7 T-V7C.C.3: when present, a successful Quiet write auto-triggers Dream scheduling. */
+    dreamSchedulePort?: QuietDreamSchedulePort;
+}
+/**
+ * Resolves the heartbeat outcome for a guard-allowed intent (outreach dispatch, quiet orchestration, or default).
+ * Exported for unit tests (CR-M1 wiring).
+ */
+export declare function resolveAllowedIntentResult(intent: CandidateIntent, runtime: HeartbeatRuntimeSnapshot, inputs: SnapshotInputs, signal: HeartbeatSignal, deps: Pick<HeartbeatDeps, "outreachDispatch" | "quietWorkflow" | "connectorExecutor" | "state" | "workspaceRoot" | "experienceWriter" | "circuitBreakerManager">): Promise<HeartbeatCycleResult>;
+export interface HeartbeatDeps {
+    /** Load snapshot inputs from state-system */
+    loadSnapshotInputs: () => Promise<SnapshotInputs>;
+    /** Optional observability hook (T2.2.1): one record per completed cycle. */
+    recordDecisionTrace?: (payload: HeartbeatDecisionTracePayload) => Promise<void>;
+    outreachDispatch?: HeartbeatOutreachDispatchDeps;
+    quietWorkflow?: HeartbeatQuietWorkflowDeps;
+    /**
+     * When present, guard-allowed connector_action intents are dispatched
+     * through the connector-system instead of returning connector_dispatch_unwired.
+     */
+    connectorExecutor?: ConnectorExecutor;
+    /** T2.1.5: when present, heartbeat writes a source-backed NarrativeState revision after each cycle. */
+    narrativeStateStore?: NarrativeStateStore;
+    /** T5.1.2: when present, heartbeat records a NarrativeTrace after successful narrative state update. */
+    recordNarrativeTrace?: (payload: NarrativeTracePayload) => Promise<void>;
+    /** T3.3.1: when present, successful connector effects write LifeEvidence artifacts. */
+    state?: StateDatabase;
+    /** T3.3.1: workspace root for evidence artifact paths. */
+    workspaceRoot?: string;
+    /** T2.4.1: when present, planner resolves platform-specific intents. */
+    connectorRegistry?: CapabilityContractRegistry;
+    /** v7 T-V7C.C.2: when present, connector attempts write ToolExperience with triggerSource="heartbeat". */
+    experienceWriter?: ExperienceWriter;
+    /** v7 T-CP.C.3: when present, evaluates goal lifecycle transitions before candidate planning. */
+    goalLifecyclePolicy?: GoalLifecyclePolicy;
+    /** v7 T-CP.C.3: when present, selects read-only sensing intent when no active goals exist. */
+    idleCuriosityPolicy?: IdleCuriosityPolicy;
+    /** v7 T-BTS.C.5: when present, updates breaker state after connector execution. */
+    circuitBreakerManager?: CircuitBreakerManager;
+}
+/**
+ * Ingest a heartbeat rhythm signal and drive one full decision round.
+ */
+export declare function ingestRhythmSignal(signal: HeartbeatSignal, deps: HeartbeatDeps): Promise<HeartbeatCycleResult>;
+/**
+ * Build a snapshot directly from inputs (for testing or when state-system is unavailable).
+ */
+export declare function buildSnapshotFromInputs(inputs: SnapshotInputs): ContinuitySnapshot;