@haaaiawd/second-nature 0.2.2 → 0.2.4

package/runtime/core/second-nature/guidance/impulse-context-writer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ImpulseContextWriter — Persist assembled impulse + atmosphere as agent-facing artifact.
+ *
+ * Core logic: Convert impulse assembly result into a durable artifact that can be
+ * read during setup, heartbeat, and platform-scene entry without re-assembly.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md §1`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeImpulseContextArtifact)
+ * - `src/guidance/impulse-assembler.js` (ImpulseAssemblerResult)
+ *
+ * Boundary:
+ * - Does NOT register a fake OpenClaw context-engine.
+ * - Does NOT claim delivery or decision capability.
+ * - Overwrites existing artifact for same scene/capability combo (upsert behavior).
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { ImpulseAssemblerResult } from "../../../guidance/impulse-assembler.js";
+import type { SourceRef, DegradedOperationResult } from "../../../shared/types/v8-contracts.js";
+export interface ImpulseContextArtifactInput {
+    sceneType: string;
+    capabilityIntent?: string;
+    platformId?: string;
+    impulseResult: ImpulseAssemblerResult;
+    atmosphereText?: string;
+    expressionBoundaryConstraints: string[];
+    expressionBoundaryStyle?: string;
+}
+export interface WriteArtifactResult {
+    id: string;
+    freshnessVersion: number;
+}
+export declare function writeImpulseContext(db: StateDatabase, input: ImpulseContextArtifactInput, options?: {
+    now?: string;
+    sourceRefs?: SourceRef[];
+}): Promise<WriteArtifactResult | DegradedOperationResult>;

package/runtime/core/second-nature/guidance/impulse-context-writer.js

@@ -0,0 +1,70 @@
+/**
+ * ImpulseContextWriter — Persist assembled impulse + atmosphere as agent-facing artifact.
+ *
+ * Core logic: Convert impulse assembly result into a durable artifact that can be
+ * read during setup, heartbeat, and platform-scene entry without re-assembly.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md §1`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeImpulseContextArtifact)
+ * - `src/guidance/impulse-assembler.js` (ImpulseAssemblerResult)
+ *
+ * Boundary:
+ * - Does NOT register a fake OpenClaw context-engine.
+ * - Does NOT claim delivery or decision capability.
+ * - Overwrites existing artifact for same scene/capability combo (upsert behavior).
+ */
+import { writeImpulseContextArtifact } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function buildArtifactId(sceneType, capabilityIntent, platformId) {
+    const cap = capabilityIntent ?? "none";
+    const plat = platformId ?? "generic";
+    return `ica_${sceneType}_${cap}_${plat}`;
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function writeImpulseContext(db, input, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const id = buildArtifactId(input.sceneType, input.capabilityIntent, input.platformId);
+    const sourceRefs = options?.sourceRefs ?? [
+        {
+            uri: `sn://impulse-context/${id}`,
+            family: "projection",
+            id,
+            redactionClass: "none",
+            resolveStatus: "resolvable",
+        },
+    ];
+    const result = await writeImpulseContextArtifact(db, {
+        id,
+        createdAt: now,
+        updatedAt: now,
+        sceneType: input.sceneType,
+        capabilityIntent: input.capabilityIntent ?? null,
+        platformId: input.platformId ?? null,
+        capabilityClass: input.impulseResult.capabilityClass ?? null,
+        impulseSource: input.impulseResult.source,
+        impulseText: input.impulseResult.impulse?.text ?? null,
+        atmosphereText: input.atmosphereText ?? null,
+        expressionBoundaryConstraintsJson: JSON.stringify(input.expressionBoundaryConstraints),
+        expressionBoundaryStyle: input.expressionBoundaryStyle ?? null,
+        freshnessVersion: 1,
+        sourceRefs,
+        redactionClass: "none",
+        payloadJson: JSON.stringify({
+            impulseKind: input.impulseResult.impulse?.kind ?? null,
+            impulseReviewStatus: input.impulseResult.impulse?.reviewStatus ?? null,
+        }),
+        lifecycleStatus: "active",
+    });
+    if ("reason" in result) {
+        return result;
+    }
+    return { id, freshnessVersion: 1 };
+}

package/runtime/core/second-nature/perception/judgment-engine.d.ts

@@ -23,6 +23,7 @@
  */
 import type { StateDatabase } from "../../../storage/db/index.js";
 import type { SourceRef, DegradedOperationResult, PlatformNeutralActionKind, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+import type { AcceptedProjection } from "../control-plane/accepted-projection-loader.js";
 export interface JudgmentVerdictResult {
     id: string;
     cycleId: string;
@@ -41,6 +42,7 @@ export interface RunAgentJudgmentResult {
 }
 export interface RunAgentJudgmentOptions {
     now?: string;
+    acceptedProjections?: AcceptedProjection[];
 }
 export declare function runAgentJudgment(db: StateDatabase, perceptionCardId: string, options?: RunAgentJudgmentOptions): Promise<RunAgentJudgmentResult | DegradedOperationResult>;
 export interface BatchJudgmentResult {

package/runtime/core/second-nature/perception/judgment-engine.js

@@ -153,7 +153,17 @@ export async function runAgentJudgment(db, perceptionCardId, options) {
             /* ignore */
         }
     }
-    const { actionKind, reason, finalConfidence } = selectVerdict(card.relevance ?? 0.3, card.confidence ?? 0.6, riskPosture, hasSourceRefs, possibleIntents);
+    let { actionKind, reason, finalConfidence } = selectVerdict(card.relevance ?? 0.3, card.confidence ?? 0.6, riskPosture, hasSourceRefs, possibleIntents);
+    // T-DQ.R.3: Boost verdict when accepted memory projection matches topic
+    const acceptedProjections = options?.acceptedProjections ?? [];
+    const matchingProjection = acceptedProjections.find((p) => p.topicKey.toLowerCase() === (card.topic ?? "").toLowerCase());
+    if (matchingProjection) {
+        finalConfidence = Math.min(0.95, finalConfidence + 0.1);
+        if (actionKind === "ignore") {
+            actionKind = "remember";
+            reason = "projection_topic_matched";
+        }
+    }
     const verdict = {
         id: `jud_${perceptionCardId}_${now.replace(/[:.]/g, "")}`,
         cycleId: card.cycleId,

package/runtime/core/second-nature/perception/perception-builder.d.ts

@@ -37,8 +37,12 @@ export interface PerceptionCardResult {
     cycleId: string;
     topic: string;
     entities: string[];
-    novelty: "new" | "recurring" | "update";
-    relevance: number;
+    /** Canonical novelty class: new | changed | duplicate | stale */
+    noveltyClass: "new" | "changed" | "duplicate" | "stale";
+    /** Numeric relevance score in [0, 1] */
+    relevanceScore: number;
+    /** Derived relevance class: low | medium | high */
+    relevanceClass: "low" | "medium" | "high";
     summary: string;
     possibleIntents: PlatformNeutralActionKind[];
     reviewPriority: "low" | "medium" | "high";

package/runtime/core/second-nature/perception/perception-builder.js

@@ -76,12 +76,13 @@ function extractEntities(evidence) {
     }
     return [...new Set(entities)];
 }
-function inferNovelty(evidence) {
+function inferNoveltyClass(evidence) {
+    // Canonical novelty classification
     if (evidence.sensitivityHint === "public_technical")
-        return "recurring";
+        return "changed";
     return "new";
 }
-function inferRelevance(evidence) {
+function inferRelevanceScore(evidence) {
     if (evidence.sensitivityHint === "sensitive")
         return 0.9;
     if (evidence.sensitivityHint === "public_technical")
@@ -90,6 +91,13 @@ function inferRelevance(evidence) {
         return 0.5;
     return 0.3;
 }
+function inferRelevanceClass(score) {
+    if (score >= 0.7)
+        return "high";
+    if (score >= 0.4)
+        return "medium";
+    return "low";
+}
 function inferSummary(evidence) {
     const platform = evidence.platformId;
     const topic = extractTopic(evidence);
@@ -124,13 +132,15 @@ function inferRiskFlags(evidence) {
 }
 function buildCardFromEvidence(evidence, cycleId, now) {
     const sourceRefs = parseSourceRefs(evidence.sourceRefsJson);
+    const relevanceScore = inferRelevanceScore(evidence);
     return {
         id: `per_${evidence.id}`,
         cycleId,
         topic: extractTopic(evidence),
         entities: extractEntities(evidence),
-        novelty: inferNovelty(evidence),
-        relevance: inferRelevance(evidence),
+        noveltyClass: inferNoveltyClass(evidence),
+        relevanceScore,
+        relevanceClass: inferRelevanceClass(relevanceScore),
         summary: inferSummary(evidence),
         possibleIntents: inferPossibleIntents(evidence),
         reviewPriority: inferReviewPriority(evidence),
@@ -177,8 +187,9 @@ export async function buildPerceptionCards(db, options) {
             cycleId: card.cycleId,
             topic: card.topic,
             entitiesJson: JSON.stringify(card.entities),
-            novelty: card.novelty,
-            relevance: card.relevance,
+            novelty: card.noveltyClass,
+            relevance: card.relevanceScore,
+            relevanceClass: card.relevanceClass,
             summary: card.summary,
             riskFlagsJson: JSON.stringify(card.riskFlags),
             confidence: card.confidence,

package/runtime/core/second-nature/quiet-dream/daily-rhythm-scheduler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DailyRhythmScheduler — Independent Quiet/Dream cadence with absence reasons.
+ *
+ * Core logic: Check if today's Quiet review is due (closures exist but no review
+ * yet), schedule/run it, then check Dream status. Records durable states so
+ * loop_status can report exact missing stages even when heartbeat does not
+ * select a quiet intent.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.1-§3.4`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (write/read DailyRhythmState)
+ * - `src/core/second-nature/quiet-dream/quiet-daily-review-builder.js`
+ * - `src/core/second-nature/quiet-dream/dream-scheduler.js`
+ *
+ * Boundary:
+ * - Does not run consolidation; only schedules and records lifecycle.
+ * - Does not bypass Dream runner; only records due/completed/blocked.
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export type RhythmStatus = "due" | "completed" | "skipped" | "blocked" | "not_due";
+export interface DailyRhythmState {
+    day: string;
+    quietStatus: RhythmStatus;
+    dreamStatus: RhythmStatus;
+    quietReason?: V8ReasonCode;
+    dreamReason?: V8ReasonCode;
+    quietCompletedAt?: string;
+    dreamCompletedAt?: string;
+}
+export interface CheckDailyRhythmOptions {
+    now?: string;
+    forceQuiet?: boolean;
+    schedulerAvailable?: boolean;
+}
+export type CheckDailyRhythmResult = {
+    status: "checked";
+    state: DailyRhythmState;
+} | DegradedOperationResult;
+export declare function checkDailyRhythm(db: StateDatabase, options?: CheckDailyRhythmOptions): Promise<CheckDailyRhythmResult>;

package/runtime/core/second-nature/quiet-dream/daily-rhythm-scheduler.js

@@ -0,0 +1,157 @@
+/**
+ * DailyRhythmScheduler — Independent Quiet/Dream cadence with absence reasons.
+ *
+ * Core logic: Check if today's Quiet review is due (closures exist but no review
+ * yet), schedule/run it, then check Dream status. Records durable states so
+ * loop_status can report exact missing stages even when heartbeat does not
+ * select a quiet intent.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.1-§3.4`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (write/read DailyRhythmState)
+ * - `src/core/second-nature/quiet-dream/quiet-daily-review-builder.js`
+ * - `src/core/second-nature/quiet-dream/dream-scheduler.js`
+ *
+ * Boundary:
+ * - Does not run consolidation; only schedules and records lifecycle.
+ * - Does not bypass Dream runner; only records due/completed/blocked.
+ */
+import { writeDailyRhythmState, readDailyRhythmStateByDay, readActionClosuresByDay, } from "../../../storage/v8-state-stores.js";
+import { buildQuietDailyReview } from "./quiet-daily-review-builder.js";
+import { scheduleDreamAfterQuiet } from "./dream-scheduler.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function todayString(now) {
+    return now.slice(0, 10);
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function checkDailyRhythm(db, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const day = todayString(now);
+    // Read existing rhythm state
+    const existing = await readDailyRhythmStateByDay(db, day);
+    if (existing.degraded) {
+        return existing.degraded;
+    }
+    const state = existing.row
+        ? {
+            day: existing.row.day,
+            quietStatus: existing.row.quietStatus,
+            dreamStatus: existing.row.dreamStatus,
+            quietReason: existing.row.quietReason,
+            dreamReason: existing.row.dreamReason,
+            quietCompletedAt: existing.row.quietCompletedAt ?? undefined,
+            dreamCompletedAt: existing.row.dreamCompletedAt ?? undefined,
+        }
+        : {
+            day,
+            quietStatus: "not_due",
+            dreamStatus: "not_due",
+        };
+    // Check if closures exist for today
+    const closuresRead = await readActionClosuresByDay(db, day);
+    if (closuresRead.degraded) {
+        return closuresRead.degraded;
+    }
+    const hasClosures = closuresRead.rows.length > 0;
+    // Determine Quiet status
+    if (state.quietStatus === "completed" || state.quietStatus === "blocked") {
+        // Already handled; don't re-run
+    }
+    else if (!hasClosures) {
+        state.quietStatus = "not_due";
+        state.quietReason = "quiet_empty_input";
+    }
+    else {
+        // Closures exist but Quiet not completed → due
+        state.quietStatus = "due";
+        state.quietReason = "quiet_empty_input";
+        // Auto-run Quiet if forced or if not yet attempted
+        if (options?.forceQuiet || state.quietStatus === "due") {
+            const quietResult = await buildQuietDailyReview(db, { day, now });
+            if (quietResult.status === "completed") {
+                state.quietStatus = "completed";
+                state.quietReason = "quiet_completed";
+                state.quietCompletedAt = now;
+            }
+            else if (quietResult.status === "empty") {
+                state.quietStatus = "skipped";
+                state.quietReason = quietResult.reason ?? "quiet_empty_input";
+            }
+            else {
+                // Degraded
+                state.quietStatus = "blocked";
+                state.quietReason = quietResult.reason ?? "state_unreadable";
+            }
+        }
+    }
+    // Determine Dream status based on Quiet outcome
+    if (state.quietStatus === "completed") {
+        if (state.dreamStatus === "completed" || state.dreamStatus === "blocked") {
+            // Already handled
+        }
+        else {
+            state.dreamStatus = "due";
+            state.dreamReason = "dream_scheduled";
+            // Schedule Dream
+            const quietId = `quiet_${day}`;
+            const dreamResult = await scheduleDreamAfterQuiet(db, quietId, {
+                now,
+                schedulerAvailable: options?.schedulerAvailable ?? true,
+            });
+            if ("reason" in dreamResult) {
+                state.dreamStatus = "blocked";
+                state.dreamReason = dreamResult.reason;
+            }
+            else if (dreamResult.status === "blocked") {
+                state.dreamStatus = "blocked";
+                state.dreamReason = dreamResult.reason ?? "dream_scheduler_unavailable";
+            }
+            else {
+                state.dreamStatus = "scheduled";
+                state.dreamReason = "dream_scheduled";
+            }
+        }
+    }
+    else if (state.quietStatus === "not_due") {
+        state.dreamStatus = "not_due";
+        state.dreamReason = "quiet_empty_input";
+    }
+    else {
+        // Quiet blocked/skipped → Dream cannot run
+        state.dreamStatus = "blocked";
+        state.dreamReason = "dream_blocked_redaction";
+    }
+    // Persist state
+    const writeResult = await writeDailyRhythmState(db, {
+        id: `rhythm_${day}`,
+        day,
+        quietStatus: state.quietStatus,
+        dreamStatus: state.dreamStatus,
+        quietReason: state.quietReason ?? null,
+        dreamReason: state.dreamReason ?? null,
+        quietCompletedAt: state.quietCompletedAt ?? null,
+        dreamCompletedAt: state.dreamCompletedAt ?? null,
+        sourceRefs: [
+            {
+                uri: `sn://rhythm/${day}`,
+                family: "dream_run",
+                id: `rhythm_${day}`,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ],
+        payloadJson: JSON.stringify({ checkedAt: now, hasClosures: closuresRead.rows.length }),
+        updatedAt: now,
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return { status: "checked", state };
+}

package/runtime/core/second-nature/quiet-dream/memory-projection-lifecycle.js

@@ -20,7 +20,7 @@
  *
  * Test coverage: tests/unit/dream/memory-projection-lifecycle.test.ts
  */
-import { readMemoryProjectionsByTopic, writeLongTermMemoryProjection, } from "../../../storage/v8-state-stores.js";
+import { readMemoryProjectionsByTopic, writeLongTermMemoryProjection, updateLongTermMemoryProjectionStatus, } from "../../../storage/v8-state-stores.js";
 // ───────────────────────────────────────────────────────────────
 // Public API
 // ───────────────────────────────────────────────────────────────
@@ -44,21 +44,12 @@ export async function acceptMemoryProjection(db, candidateId, topicKey, memoryTe
     const activeProjection = existing.rows.find((r) => r.status === "active" || r.status === "accepted");
     let supersedesId;
     if (activeProjection) {
-        // Supersede existing active projection
-        const supersedeResult = await writeLongTermMemoryProjection(db, {
-            id: activeProjection.id,
-            createdAt: activeProjection.createdAt,
-            candidateId: activeProjection.candidateId,
-            topicKey: activeProjection.topicKey,
-            status: "superseded",
-            sourceRefs: parseSourceRefs(activeProjection.sourceRefsJson),
-            redactionClass: activeProjection.redactionClass,
-            lifecycleStatus: "superseded",
-            payloadJson: JSON.stringify({
-                supersededAt: now,
-                supersededBy: candidateId,
-            }),
-        });
+        // Supersede existing active projection — UPDATE instead of INSERT
+        const supersedeResult = await updateLongTermMemoryProjectionStatus(db, activeProjection.id, "superseded", JSON.stringify({
+            ...parsePayloadJson(activeProjection.payloadJson),
+            supersededAt: now,
+            supersededBy: candidateId,
+        }));
         if ("reason" in supersedeResult) {
             return supersedeResult;
         }
@@ -149,3 +140,13 @@ function parseSourceRefs(json) {
         return [];
     }
 }
+function parsePayloadJson(json) {
+    if (!json)
+        return {};
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}

package/runtime/core/second-nature/quiet-dream/quiet-daily-review-builder.d.ts

@@ -27,7 +27,10 @@ export interface QuietDailyReviewResult {
     day: string;
     closureCount: number;
     memoryCandidateCount: number;
+    /** Generic source refs (closure + perception + other) */
     sourceRefs: SourceRef[];
+    /** Explicit closure refs — first-class provenance for reviewed ActionClosureRecords */
+    closureRefs: SourceRef[];
     reviewSummary: string;
     importanceSignals: string[];
     createdAt: string;

package/runtime/core/second-nature/quiet-dream/quiet-daily-review-builder.js

@@ -68,6 +68,8 @@ export async function buildQuietDailyReview(db, options) {
         };
     }
     const sourceRefs = closures.map(buildSourceRefFromClosure);
+    // T-DQ.R.4: first-class closure refs — identical to sourceRefs here, but explicitly typed
+    const closureRefs = closures.map(buildSourceRefFromClosure);
     // Collect memory-review candidates from closure payloads
     const memoryCandidates = [];
     for (const closure of closures) {
@@ -96,6 +98,7 @@ export async function buildQuietDailyReview(db, options) {
         closureCount: closures.length,
         memoryCandidateCount: memoryCandidates.length,
         sourceRefs,
+        closureRefs,
         redactionClass: "none",
         lifecycleStatus: "pending",
         payloadJson: JSON.stringify({
@@ -115,6 +118,7 @@ export async function buildQuietDailyReview(db, options) {
             closureCount: closures.length,
             memoryCandidateCount: memoryCandidates.length,
             sourceRefs,
+            closureRefs,
             reviewSummary,
             importanceSignals,
             createdAt: now,

package/runtime/observability/living-loop-health-gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LivingLoopHealthGate — Distinguish contract-smoke from real runtime activity.
+ *
+ * Core logic: Check for persisted ActionClosureRecord, QuietDailyReview,
+ * and DreamConsolidationRun to determine if the living loop has real
+ * evidence or is only passing contract smoke tests.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §4.2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §4`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readActionClosuresByDay, readDailyRhythmStateByDay)
+ *
+ * Boundary:
+ * - Read-only diagnostic; does not modify state.
+ * - Reports explicit absence reasons instead of silent zeros.
+ */
+import type { StateDatabase } from "../storage/db/index.js";
+import type { DegradedOperationResult } from "../shared/types/v8-contracts.js";
+export interface RealRunHealthGate {
+    /** Has at least one real ActionClosureRecord */
+    hasRealClosure: boolean;
+    /** Has a completed QuietDailyReview */
+    hasQuietArtifact: boolean;
+    /** Has a scheduled or completed DreamConsolidationRun */
+    hasDreamArtifact: boolean;
+    /** True if only contract smoke (cycle traces) but no real artifacts */
+    contractSmokeOnly: boolean;
+    /** True if closure exists but no runtime-produced cycle trace backs it */
+    seededStateDetected: boolean;
+    /** True only when real runtime activity is proven (not seeded, not smoke-only) */
+    gatePassed: boolean;
+    /** Explicit missing stage reason */
+    missingStage?: "closure" | "quiet" | "dream" | "none";
+    missingReason?: string;
+}
+export type RealRunHealthResult = {
+    ok: true;
+    gate: RealRunHealthGate;
+} | {
+    ok: false;
+    degraded: DegradedOperationResult;
+};
+export declare function checkRealRunHealth(db: StateDatabase, day?: string): Promise<RealRunHealthResult>;

package/runtime/observability/living-loop-health-gate.js

@@ -0,0 +1,94 @@
+/**
+ * LivingLoopHealthGate — Distinguish contract-smoke from real runtime activity.
+ *
+ * Core logic: Check for persisted ActionClosureRecord, QuietDailyReview,
+ * and DreamConsolidationRun to determine if the living loop has real
+ * evidence or is only passing contract smoke tests.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §4.2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §4`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readActionClosuresByDay, readDailyRhythmStateByDay)
+ *
+ * Boundary:
+ * - Read-only diagnostic; does not modify state.
+ * - Reports explicit absence reasons instead of silent zeros.
+ */
+import { readActionClosuresByDay, readDailyRhythmStateByDay, readHeartbeatCycleTraces, } from "../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function checkRealRunHealth(db, day) {
+    const targetDay = day ?? new Date().toISOString().slice(0, 10);
+    // Check closures
+    const closureResult = await readActionClosuresByDay(db, targetDay);
+    if (closureResult.degraded) {
+        return { ok: false, degraded: closureResult.degraded };
+    }
+    const hasRealClosure = closureResult.rows.length > 0;
+    // Check if closures are runtime-produced (backed by cycle trace + stage events)
+    let seededStateDetected = false;
+    if (hasRealClosure) {
+        const traces = await readHeartbeatCycleTraces(db, 1000);
+        if (traces.degraded) {
+            return { ok: false, degraded: traces.degraded };
+        }
+        for (const closure of closureResult.rows) {
+            const hasCycleTrace = traces.rows.some((t) => t.id === closure.cycleId);
+            if (!hasCycleTrace) {
+                seededStateDetected = true;
+                break;
+            }
+        }
+    }
+    // Check daily rhythm state for Quiet/Dream
+    const rhythmResult = await readDailyRhythmStateByDay(db, targetDay);
+    if (rhythmResult.degraded) {
+        return { ok: false, degraded: rhythmResult.degraded };
+    }
+    const rhythm = rhythmResult.row;
+    const hasQuietArtifact = rhythm?.quietStatus === "completed";
+    const hasDreamArtifact = rhythm?.dreamStatus === "scheduled" || rhythm?.dreamStatus === "completed";
+    // Determine if only contract smoke
+    const contractSmokeOnly = !hasRealClosure && !hasQuietArtifact && !hasDreamArtifact;
+    // Gate passes only when all real runtime stages have evidence
+    const gatePassed = !contractSmokeOnly && !seededStateDetected && hasRealClosure && hasQuietArtifact && hasDreamArtifact;
+    // Identify missing stage
+    let missingStage;
+    let missingReason;
+    if (!hasRealClosure) {
+        missingStage = "closure";
+        missingReason = "No ActionClosureRecord for today. Heartbeat may be running contract smoke without real action closure.";
+    }
+    else if (seededStateDetected) {
+        missingStage = "closure";
+        missingReason = "ActionClosureRecord exists but lacks runtime-produced cycle trace. Seeded state detected — not valid runtime proof.";
+    }
+    else if (!hasQuietArtifact) {
+        missingStage = "quiet";
+        missingReason = "ActionClosureRecord exists but no QuietDailyReview. Daily review may be due or skipped.";
+    }
+    else if (!hasDreamArtifact) {
+        missingStage = "dream";
+        missingReason = "QuietDailyReview completed but no DreamConsolidationRun. Dream scheduler may be unavailable.";
+    }
+    else {
+        missingStage = "none";
+        missingReason = "All living-loop stages have real artifacts.";
+    }
+    return {
+        ok: true,
+        gate: {
+            hasRealClosure,
+            hasQuietArtifact,
+            hasDreamArtifact,
+            contractSmokeOnly,
+            seededStateDetected,
+            gatePassed,
+            missingStage,
+            missingReason,
+        },
+    };
+}