@haaaiawd/second-nature 0.1.8 → 0.1.9

package/runtime/connectors/base/execution-policy.js

@@ -0,0 +1,82 @@
+/**
+ * Side-effect idempotency + degraded-channel gate + effect commit replay (T3.2.1).
+ * Aligns with connector-system.detail §3.6 enforceExecutionPolicy.
+ */
+import * as crypto from "node:crypto";
+import { ConnectorPolicyError } from "./failure-taxonomy.js";
+const READONLY = new Set([
+    "feed.read",
+    "notification.list",
+    "work.discover",
+]);
+export function classifyConnectorIntentEffect(intent) {
+    if (intent === "agent.heartbeat")
+        return "keepalive";
+    if (intent === "task.claim")
+        return "task_claim";
+    if (READONLY.has(intent))
+        return "read_only";
+    return "side_effect";
+}
+/** In-memory ledger for tests and offline harnesses. */
+export class InMemoryEffectCommitLedger {
+    byKey = new Map();
+    key(decisionId, idempotencyKey) {
+        return `${decisionId}::${idempotencyKey}`;
+    }
+    async getOrCreateIntentCommitRecord(input) {
+        const k = this.key(input.decisionId, input.idempotencyKey);
+        const hit = this.byKey.get(k);
+        if (hit) {
+            return { existing: true, record: hit };
+        }
+        const id = crypto.randomUUID();
+        const rec = { id, state: "planned", outcomeRef: undefined };
+        this.byKey.set(k, rec);
+        return { existing: false, record: rec };
+    }
+    /** Test seam: mark a key as already committed with replayable outcome. */
+    seedCommitted(decisionId, idempotencyKey, outcomeRef) {
+        const id = crypto.randomUUID();
+        this.byKey.set(this.key(decisionId, idempotencyKey), { id, state: "committed", outcomeRef });
+    }
+    markState(decisionId, idempotencyKey, state) {
+        const k = this.key(decisionId, idempotencyKey);
+        const cur = this.byKey.get(k);
+        if (!cur)
+            throw new Error("ledger_seed_missing");
+        this.byKey.set(k, { ...cur, state });
+    }
+}
+export async function enforceExecutionPolicy(plan, intent, request, deps) {
+    const semantics = classifyConnectorIntentEffect(intent);
+    if ((semantics === "side_effect" || semantics === "task_claim") && !plan.idempotencyKey?.trim()) {
+        throw new ConnectorPolicyError("permanent_input_error", "side_effect_requires_idempotency_key");
+    }
+    if (plan.degraded && (semantics === "side_effect" || semantics === "task_claim")) {
+        throw new ConnectorPolicyError("semantic_rejection", "degraded_channel_not_allowed_for_side_effect");
+    }
+    if (plan.idempotencyKey && deps.effectCommitLedger) {
+        if (!request.decisionId?.trim() || !request.intentId?.trim()) {
+            throw new ConnectorPolicyError("permanent_input_error", "effect_commit_requires_decision_and_intent_id");
+        }
+        const lookup = await deps.effectCommitLedger.getOrCreateIntentCommitRecord({
+            decisionId: request.decisionId,
+            intentId: request.intentId,
+            idempotencyKey: plan.idempotencyKey,
+            effectClass: semantics,
+        });
+        if (lookup.existing && lookup.record.state === "committed") {
+            return {
+                skipAdapter: true,
+                existingOutcomeRef: lookup.record.outcomeRef,
+                effectCommitId: lookup.record.id,
+            };
+        }
+        if (lookup.existing && (lookup.record.state === "dispatched" || lookup.record.state === "reconcile")) {
+            throw new ConnectorPolicyError("concurrency_conflict", "effect_commit_requires_reconcile");
+        }
+        return { skipAdapter: false, effectCommitId: lookup.record.id };
+    }
+    return { skipAdapter: false };
+}

package/runtime/connectors/base/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./contract.js";
 export * from "./manifest.js";
+export * from "./map-life-evidence.js";
 export * from "./failure-taxonomy.js";
 export * from "./route-planner.js";
 export * from "./channel-health.js";
 export * from "./policy-layer.js";
+export * from "./execution-policy.js";

package/runtime/connectors/base/index.js

@@ -1,6 +1,8 @@
 export * from "./contract.js";
 export * from "./manifest.js";
+export * from "./map-life-evidence.js";
 export * from "./failure-taxonomy.js";
 export * from "./route-planner.js";
 export * from "./channel-health.js";
 export * from "./policy-layer.js";
+export * from "./execution-policy.js";

package/runtime/connectors/base/manifest.d.ts

@@ -1,11 +1,64 @@
-import { type CapabilityIntent, type ChannelType, type ConnectorManifestLike } from "./contract.js";
-export type ConnectorManifest = ConnectorManifestLike;
+import { z } from "zod";
+import { type CapabilityIntent, type ChannelType } from "./contract.js";
+declare const connectorManifestSchema: z.ZodObject<{
+    platformId: z.ZodString;
+    supportedCapabilities: z.ZodArray<z.ZodEnum<{
+        "feed.read": "feed.read";
+        "post.publish": "post.publish";
+        "comment.reply": "comment.reply";
+        "notification.list": "notification.list";
+        "message.send": "message.send";
+        "agent.register": "agent.register";
+        "agent.heartbeat": "agent.heartbeat";
+        "work.discover": "work.discover";
+        "task.claim": "task.claim";
+    }>>;
+    channelPriority: z.ZodArray<z.ZodEnum<{
+        api_rest: "api_rest";
+        api_rpc: "api_rpc";
+        a2a: "a2a";
+        mcp: "mcp";
+        cli: "cli";
+        skill: "skill";
+        browser: "browser";
+    }>>;
+    credentialTypes: z.ZodArray<z.ZodString>;
+    degradedChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        api_rest: "api_rest";
+        api_rpc: "api_rpc";
+        a2a: "a2a";
+        mcp: "mcp";
+        cli: "cli";
+        skill: "skill";
+        browser: "browser";
+    }>>>;
+    sourceRefPolicy: z.ZodOptional<z.ZodObject<{
+        minSourceRefs: z.ZodDefault<z.ZodNumber>;
+        rejectInlineSensitivePayload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConnectorManifest = z.infer<typeof connectorManifestSchema>;
 export declare class CapabilityContractRegistry {
     private readonly byPlatform;
     register(manifest: ConnectorManifest): void;
     loadManifest(platformId: string): ConnectorManifest;
+    listRegisteredPlatformIds(): string[];
     hasCapability(platformId: string, intent: CapabilityIntent): boolean;
     listCapabilities(platformId: string): CapabilityIntent[];
     listChannels(platformId: string): ChannelType[];
 }
+/** T3.1.1 contract name for manifest-first registry. */
+export declare const ConnectorManifestRegistry: typeof CapabilityContractRegistry;
+export type ConnectorManifestRegistry = CapabilityContractRegistry;
+export declare function describeConnector(registry: CapabilityContractRegistry, platformId: string): ConnectorManifest;
+export declare function checkConnector(registry: CapabilityContractRegistry, platformId: string): {
+    ok: boolean;
+    errors: string[];
+};
+export declare function discoverCapabilities(registry: CapabilityContractRegistry): Array<{
+    platformId: string;
+    capabilities: CapabilityIntent[];
+    degradedChannels?: ChannelType[];
+}>;
 export declare function parseConnectorManifest(input: unknown): ConnectorManifest;
+export {};

package/runtime/connectors/base/manifest.js

@@ -1,11 +1,18 @@
 import { z } from "zod";
 import { CAPABILITY_INTENTS, CHANNEL_TYPES } from "./contract.js";
+const sourceRefPolicySchema = z
+    .object({
+    minSourceRefs: z.number().int().min(0).default(1),
+    rejectInlineSensitivePayload: z.boolean().optional(),
+})
+    .optional();
 const connectorManifestSchema = z.object({
     platformId: z.string().min(1),
     supportedCapabilities: z.array(z.enum(CAPABILITY_INTENTS)).min(1),
     channelPriority: z.array(z.enum(CHANNEL_TYPES)).min(1),
     credentialTypes: z.array(z.string().min(1)).min(1),
     degradedChannels: z.array(z.enum(CHANNEL_TYPES)).optional(),
+    sourceRefPolicy: sourceRefPolicySchema,
 });
 export class CapabilityContractRegistry {
     byPlatform = new Map();
@@ -20,6 +27,9 @@ export class CapabilityContractRegistry {
         }
         return found;
     }
+    listRegisteredPlatformIds() {
+        return [...this.byPlatform.keys()];
+    }
     hasCapability(platformId, intent) {
         const manifest = this.loadManifest(platformId);
         return manifest.supportedCapabilities.includes(intent);
@@ -31,6 +41,46 @@ export class CapabilityContractRegistry {
         return [...this.loadManifest(platformId).channelPriority];
     }
 }
+/** T3.1.1 contract name for manifest-first registry. */
+export const ConnectorManifestRegistry = CapabilityContractRegistry;
+export function describeConnector(registry, platformId) {
+    return registry.loadManifest(platformId);
+}
+export function checkConnector(registry, platformId) {
+    const errors = [];
+    try {
+        const manifest = registry.loadManifest(platformId);
+        if (manifest.supportedCapabilities.length === 0) {
+            errors.push("capability_list_empty");
+        }
+        if (manifest.channelPriority.length === 0) {
+            errors.push("channel_priority_empty");
+        }
+        if (manifest.credentialTypes.length === 0) {
+            errors.push("credential_types_empty");
+        }
+        const degraded = manifest.degradedChannels ?? [];
+        for (const channel of degraded) {
+            if (!manifest.channelPriority.includes(channel)) {
+                errors.push(`degraded_channel_not_in_priority:${channel}`);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function discoverCapabilities(registry) {
+    return registry.listRegisteredPlatformIds().map((platformId) => {
+        const manifest = registry.loadManifest(platformId);
+        return {
+            platformId,
+            capabilities: [...manifest.supportedCapabilities],
+            degradedChannels: manifest.degradedChannels,
+        };
+    });
+}
 export function parseConnectorManifest(input) {
     return connectorManifestSchema.parse(input);
 }

package/runtime/connectors/base/map-life-evidence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maps normalized connector success results to `LifeEvidenceCandidate` (T3.1.2).
+ * Returns null when evidence cannot be source-backed (no refs, wrong intent, or failure).
+ */
+import type { CapabilityIntent, ConnectorResult } from "./contract.js";
+import type { LifeEvidenceCandidate, Sensitivity } from "../../storage/life-evidence/types.js";
+/**
+ * Produce a single life-evidence candidate from a connector outcome, or null if not mappable.
+ */
+export declare function mapLifeEvidence(input: {
+    platformId: string;
+    intent: CapabilityIntent;
+    result: ConnectorResult<unknown>;
+    observedAt?: string;
+    sensitivityOverride?: Sensitivity;
+}): LifeEvidenceCandidate | null;

package/runtime/connectors/base/map-life-evidence.js

@@ -0,0 +1,79 @@
+function extractSourceRefs(platformId, data, observedAt) {
+    if (data && typeof data === "object") {
+        const record = data;
+        if (Array.isArray(record.sourceRefs)) {
+            const out = [];
+            for (const item of record.sourceRefs) {
+                if (item && typeof item === "object" && "uri" in item && "id" in item) {
+                    const ref = item;
+                    out.push({
+                        id: String(ref.id),
+                        kind: ref.kind ?? "platform_item",
+                        uri: String(ref.uri),
+                        excerptHash: ref.excerptHash !== undefined ? String(ref.excerptHash) : undefined,
+                        observedAt: ref.observedAt !== undefined ? String(ref.observedAt) : observedAt,
+                    });
+                }
+            }
+            if (out.length > 0)
+                return out;
+        }
+        if (Array.isArray(record.items)) {
+            return record.items.map((item, index) => {
+                const id = item && typeof item === "object" && "id" in item
+                    ? String(item.id)
+                    : `${platformId}-item-${index}`;
+                return {
+                    id,
+                    kind: "platform_item",
+                    uri: `platform://${platformId}/item/${encodeURIComponent(id)}`,
+                    observedAt,
+                };
+            });
+        }
+    }
+    return [];
+}
+function resolveEvidenceType(intent) {
+    if (intent === "feed.read")
+        return "platform_browse";
+    if (intent === "work.discover")
+        return "task_discovery";
+    return null;
+}
+function resolveSensitivity(intent, explicit) {
+    if (explicit)
+        return explicit;
+    if (intent === "message.send" || intent === "comment.reply")
+        return "private";
+    return "public";
+}
+/**
+ * Produce a single life-evidence candidate from a connector outcome, or null if not mappable.
+ */
+export function mapLifeEvidence(input) {
+    if (input.result.status !== "success") {
+        return null;
+    }
+    if (input.intent === "message.send") {
+        return null;
+    }
+    const evidenceType = resolveEvidenceType(input.intent);
+    if (!evidenceType) {
+        return null;
+    }
+    const observedAt = input.observedAt ?? new Date().toISOString();
+    const refs = extractSourceRefs(input.platformId, input.result.data, observedAt);
+    if (refs.length === 0) {
+        return null;
+    }
+    return {
+        timestamp: observedAt,
+        evidenceType,
+        platformId: input.platformId,
+        summary: `${input.platformId}:${input.intent}`,
+        sourceRefs: refs,
+        sensitivity: resolveSensitivity(input.intent, input.sensitivityOverride),
+        producer: "connector-system",
+    };
+}

package/runtime/connectors/base/policy-layer.d.ts

@@ -1,4 +1,5 @@
 import { type FailureClass } from "./failure-taxonomy.js";
+import { type EffectCommitLedgerPort } from "./execution-policy.js";
 import type { CapabilityIntent, ConnectorRequest, ConnectorResult, ExecutionPlan, ExecutionRunner, RoutePlanner } from "./contract.js";
 import type { ExecutionTelemetry } from "../../observability/services/execution-telemetry.js";
 export interface RetryPolicy {
@@ -21,6 +22,7 @@ export interface ConnectorPolicyContext {
     cooldownPort?: CooldownPort;
     retryPolicy?: Partial<RetryPolicy>;
     allowDegradedFallback?: (plan: ExecutionPlan, request: ConnectorRequest) => boolean;
+    effectCommitLedger?: EffectCommitLedgerPort;
 }
 export declare function createConnectorPolicyLayer(ctx: ConnectorPolicyContext): {
     executeWithPolicy(intent: CapabilityIntent, request: ConnectorRequest): Promise<ConnectorResult<unknown>>;

package/runtime/connectors/base/policy-layer.js

@@ -1,4 +1,5 @@
 import { classifyFailure } from "./failure-taxonomy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
 const DEFAULT_RETRY_MAX = 3;
 const DEFAULT_BASE_DELAY_MS = 1000;
 const DEFAULT_MAX_DELAY_MS = 30000;
@@ -106,6 +107,21 @@ export function createConnectorPolicyLayer(ctx) {
                     },
                 };
             }
+            const policyGate = await enforceExecutionPolicy(plan, intent, request, {
+                effectCommitLedger: ctx.effectCommitLedger,
+            });
+            if (policyGate.skipAdapter && policyGate.existingOutcomeRef) {
+                return {
+                    status: "success",
+                    data: { replayedCommit: true, outcomeRef: policyGate.existingOutcomeRef },
+                    metadata: {
+                        platformId: request.platformId,
+                        channel: plan.channel,
+                        latencyMs: 0,
+                        degraded: plan.degraded,
+                    },
+                };
+            }
             let lastFailure;
             for (let attempt = 1; attempt <= retryPolicy.maxRetries; attempt += 1) {
                 const traceId = `${makeTraceId(request, plan)}:${attempt}`;

package/runtime/connectors/base/route-planner.js

@@ -93,6 +93,7 @@ export class ConnectorRoutePlanner {
             channel: selected,
             endpointMode: endpointModeFor(selected),
             idempotencyKey: request.idempotencyKey,
+            degraded: isDegradedChannel(selected, manifest.degradedChannels),
         };
     }
 }

package/runtime/connectors/index.d.ts

@@ -2,3 +2,4 @@ export * from "./base/index.js";
 export * from "./social-community/moltbook/index.js";
 export * from "./social-community/instreet/index.js";
 export * from "./agent-network/evomap/index.js";
+export * from "./near-real/near-real-connector-smoke.js";

package/runtime/connectors/index.js

@@ -2,3 +2,4 @@ export * from "./base/index.js";
 export * from "./social-community/moltbook/index.js";
 export * from "./social-community/instreet/index.js";
 export * from "./agent-network/evomap/index.js";
+export * from "./near-real/near-real-connector-smoke.js";

package/runtime/connectors/near-real/near-real-connector-smoke.d.ts

@@ -0,0 +1,19 @@
+import type { ObservabilityDatabase } from "../../observability/db/index.js";
+import type { StateDatabase } from "../../storage/db/index.js";
+export interface NearRealConnectorSmokeResult {
+    generatedAt: string;
+    platforms: {
+        social: "moltbook";
+        agentNetwork: "evomap";
+    };
+    feedReadEvidenceId?: string;
+    workDiscoverEvidenceId?: string;
+    taskClaimDryRunOk: boolean;
+    executionAttemptRowsForDecision: number;
+}
+export interface RunNearRealConnectorSmokeInput {
+    state: StateDatabase;
+    observabilityDb: ObservabilityDatabase;
+    workspaceRoot: string;
+}
+export declare function runNearRealConnectorSmoke(input: RunNearRealConnectorSmokeInput): Promise<NearRealConnectorSmokeResult>;

package/runtime/connectors/near-real/near-real-connector-smoke.js

@@ -0,0 +1,152 @@
+/**
+ * T3.3.1 — Near-real connector smoke: sentinel adapters + policy + telemetry + life evidence ingest.
+ * Uses fixture payloads (no live HTTP); task.claim runs with idempotency key (dry-run style outcome).
+ */
+import { eq } from "drizzle-orm";
+import { CapabilityContractRegistry } from "../base/manifest.js";
+import { ConnectorRoutePlanner } from "../base/route-planner.js";
+import { ChannelHealthStore } from "../base/channel-health.js";
+import { createConnectorPolicyLayer } from "../base/policy-layer.js";
+import { InMemoryEffectCommitLedger } from "../base/execution-policy.js";
+import { mapLifeEvidence } from "../base/map-life-evidence.js";
+import { moltbookManifest } from "../social-community/moltbook/manifest.js";
+import { evomapManifest } from "../agent-network/evomap/manifest.js";
+import { ExecutionTelemetry } from "../../observability/services/execution-telemetry.js";
+import { executionAttempts } from "../../observability/db/schema/index.js";
+import { appendLifeEvidence } from "../../storage/life-evidence/append-life-evidence.js";
+const DECISION_ID = "dec-near-real-smoke";
+function smokeRouteContext() {
+    return {
+        async loadCredentialState(platformId) {
+            if (platformId === "moltbook") {
+                return { platformId, status: "active", credentialType: "api_key" };
+            }
+            if (platformId === "evomap") {
+                return { platformId, status: "active", credentialType: "node_secret" };
+            }
+            throw new Error(`near_real_smoke_unsupported_platform:${platformId}`);
+        },
+        async loadCooldownState() {
+            return { blocked: false };
+        },
+    };
+}
+const smokeExecutionRunner = {
+    async run(plan, request) {
+        if (plan.platformId === "moltbook" && plan.intent === "feed.read") {
+            return {
+                platformId: plan.platformId,
+                channel: plan.channel,
+                latencyMs: 2,
+                success: true,
+                payload: {
+                    items: [{ id: "mb-smoke-1", title: "near-real fixture post" }],
+                },
+            };
+        }
+        if (plan.platformId === "evomap" && plan.intent === "work.discover") {
+            return {
+                platformId: plan.platformId,
+                channel: plan.channel,
+                latencyMs: 3,
+                success: true,
+                payload: {
+                    items: [{ id: "ev-task-smoke-1", title: "fixture agent task" }],
+                },
+            };
+        }
+        if (plan.platformId === "evomap" && plan.intent === "task.claim") {
+            return {
+                platformId: plan.platformId,
+                channel: plan.channel,
+                latencyMs: 1,
+                success: true,
+                degraded: plan.degraded,
+                payload: {
+                    dryRun: true,
+                    taskId: typeof request.payload.taskId === "string" ? request.payload.taskId : "unknown",
+                    note: "near_real_smoke_no_external_side_effect",
+                },
+            };
+        }
+        throw new Error(`near_real_smoke_unhandled:${plan.platformId}:${plan.intent}`);
+    },
+};
+export async function runNearRealConnectorSmoke(input) {
+    const ledger = new InMemoryEffectCommitLedger();
+    const registry = new CapabilityContractRegistry();
+    registry.register({ ...moltbookManifest });
+    registry.register({ ...evomapManifest });
+    const planner = new ConnectorRoutePlanner(registry, smokeRouteContext(), new ChannelHealthStore());
+    const telemetry = new ExecutionTelemetry(input.observabilityDb);
+    const policy = createConnectorPolicyLayer({
+        routePlanner: planner,
+        executionRunner: smokeExecutionRunner,
+        telemetry,
+        effectCommitLedger: ledger,
+        retryPolicy: { maxRetries: 1, jitter: false },
+    });
+    const base = {
+        decisionId: DECISION_ID,
+        payload: {},
+    };
+    const feedResult = await policy.executeWithPolicy("feed.read", {
+        platformId: "moltbook",
+        intent: "feed.read",
+        ...base,
+        intentId: "intent-smoke-feed-read",
+        payload: {},
+    });
+    let feedReadEvidenceId;
+    const feedCand = mapLifeEvidence({
+        platformId: "moltbook",
+        intent: "feed.read",
+        result: feedResult,
+    });
+    if (feedCand) {
+        const ack = await appendLifeEvidence(input.state, input.workspaceRoot, feedCand);
+        feedReadEvidenceId = ack.evidenceId;
+    }
+    const workResult = await policy.executeWithPolicy("work.discover", {
+        platformId: "evomap",
+        intent: "work.discover",
+        ...base,
+        intentId: "intent-smoke-work-discover",
+        payload: {},
+    });
+    let workDiscoverEvidenceId;
+    const workCand = mapLifeEvidence({
+        platformId: "evomap",
+        intent: "work.discover",
+        result: workResult,
+    });
+    if (workCand) {
+        const ack = await appendLifeEvidence(input.state, input.workspaceRoot, workCand);
+        workDiscoverEvidenceId = ack.evidenceId;
+    }
+    const claimResult = await policy.executeWithPolicy("task.claim", {
+        platformId: "evomap",
+        intent: "task.claim",
+        ...base,
+        intentId: "intent-smoke-task-claim",
+        payload: { taskId: "ev-task-smoke-1" },
+        idempotencyKey: "idem-near-real-task-claim-smoke",
+    });
+    const claimPayload = claimResult.status === "success" && claimResult.data && typeof claimResult.data === "object"
+        ? claimResult.data
+        : undefined;
+    const attemptRows = await input.observabilityDb.db
+        .select()
+        .from(executionAttempts)
+        .where(eq(executionAttempts.decisionId, DECISION_ID));
+    return {
+        generatedAt: new Date().toISOString(),
+        platforms: { social: "moltbook", agentNetwork: "evomap" },
+        feedReadEvidenceId,
+        workDiscoverEvidenceId,
+        taskClaimDryRunOk: claimResult.status === "success" &&
+            claimPayload?.dryRun === true &&
+            claimPayload?.note === "near_real_smoke_no_external_side_effect",
+        executionAttemptRowsForDecision: attemptRows.length,
+    };
+}

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

@@ -12,6 +12,8 @@ function intentKindToScene(kind) {
             return "outreach";
         case "exploration":
             return "explain";
+        case "quiet":
+            return null;
         default:
             return null;
     }

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

@@ -2,7 +2,7 @@
  * Heartbeat Decision Loop
  *
  * Main entry point for the heartbeat runtime. Accepts a HeartbeatSignal,
- * builds a ContinuitySnapshot, plans candidate intents, evaluates guards,
+ * builds runtime snapshot, plans candidate intents, evaluates hard guards,
  * and returns a HeartbeatCycleResult.
  *
  * Per design doc §4.3: heartbeat round follows the sequence:
@@ -12,28 +12,49 @@
  * implements the default conservative path where HEARTBEAT_OK is
  * the first-class result when no action is warranted.
  */
-import type { ContinuitySnapshot } from "../types.js";
-import type { HeartbeatSignal, HeartbeatCycleResult } from "./signal.js";
+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";
+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;
+}
+/**
+ * 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">): 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;
 }
 /**
  * Ingest a heartbeat rhythm signal and drive one full decision round.
- *
- * Decision flow:
- * 1. Build continuity snapshot from state-system inputs
- * 2. Plan candidate intents from snapshot
- * 3. Evaluate guards for each candidate in priority order
- * 4. Return one of:
- *    - intent_selected: a candidate passed all guards
- *    - denied: candidates existed but all were rejected by guards
- *    - heartbeat_ok: no candidates or no action warranted (conservative default)
- *
- * 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.
  */
 export declare function ingestRhythmSignal(signal: HeartbeatSignal, deps: HeartbeatDeps): Promise<HeartbeatCycleResult>;
 /**