@haaaiawd/second-nature 0.1.50 → 0.2.0

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

@@ -0,0 +1,123 @@
+/**
+ * QuietDailyReviewBuilder — Aggregate daily closures, perceptions, and
+ * memory-review candidates into a source-backed QuietDailyReview.
+ *
+ * Core logic: Read ActionClosureRecords by day, collect memory-review
+ * candidates, build summary, and write QuietDailyReview row.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readActionClosuresByDay, writeQuietDailyReview)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does not form long-term memory; only emits review input for Dream.
+ * - Does not judge importance; reads closure status and risk flags.
+ * - Degrades gracefully on unreadable state.
+ *
+ * Test coverage: tests/unit/quiet/quiet-daily-review-builder.test.ts
+ */
+import { readActionClosuresByDay, writeQuietDailyReview, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Config
+// ───────────────────────────────────────────────────────────────
+const QUIET_MAX_CLOSURES_PER_DAY = 200;
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function todayString(now) {
+    return now.slice(0, 10);
+}
+function parsePayloadJson(json) {
+    if (!json)
+        return {};
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+function buildSourceRefFromClosure(closure) {
+    return {
+        uri: `sn://closure/${closure.id}`,
+        family: "action_closure",
+        id: closure.id,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function buildQuietDailyReview(db, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const day = options?.day ?? todayString(now);
+    const readResult = await readActionClosuresByDay(db, day);
+    if (readResult.degraded) {
+        return readResult.degraded;
+    }
+    const closures = readResult.rows.slice(0, QUIET_MAX_CLOSURES_PER_DAY);
+    if (closures.length === 0) {
+        return {
+            status: "empty",
+            reason: "quiet_empty_input",
+        };
+    }
+    const sourceRefs = closures.map(buildSourceRefFromClosure);
+    // Collect memory-review candidates from closure payloads
+    const memoryCandidates = [];
+    for (const closure of closures) {
+        const payload = parsePayloadJson(closure.payloadJson);
+        if (payload.memoryReviewCandidate) {
+            memoryCandidates.push(payload.memoryReviewCandidate);
+        }
+    }
+    // Build summary
+    const completedCount = closures.filter((c) => c.status === "completed").length;
+    const deniedCount = closures.filter((c) => c.status === "denied").length;
+    const failedCount = closures.filter((c) => c.status === "failed").length;
+    const reviewSummary = `Day ${day}: ${closures.length} closures (${completedCount} completed, ${deniedCount} denied, ${failedCount} failed)`;
+    const importanceSignals = [];
+    if (memoryCandidates.length > 0) {
+        importanceSignals.push(`${memoryCandidates.length} memory-review candidates`);
+    }
+    if (failedCount > 0) {
+        importanceSignals.push(`${failedCount} failed actions`);
+    }
+    const reviewId = `quiet_${day}`;
+    const writeResult = await writeQuietDailyReview(db, {
+        id: reviewId,
+        createdAt: now,
+        day,
+        closureCount: closures.length,
+        memoryCandidateCount: memoryCandidates.length,
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "pending",
+        payloadJson: JSON.stringify({
+            reviewSummary,
+            importanceSignals,
+            memoryCandidates,
+        }),
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return {
+        status: "completed",
+        review: {
+            id: reviewId,
+            day,
+            closureCount: closures.length,
+            memoryCandidateCount: memoryCandidates.length,
+            sourceRefs,
+            reviewSummary,
+            importanceSignals,
+            createdAt: now,
+        },
+    };
+}

package/runtime/observability/causal-loop-health.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CausalLoopHealth — Assemble loop health snapshot from cycle traces and stage events.
+ *
+ * Core logic: Read recent HeartbeatCycleTrace and LoopStageEvent rows,
+ * compute stage freshness, identify stalled stages, and return
+ * CausalLoopHealthSnapshot.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readHeartbeatCycleTraces, readLoopStageEventsByStage)
+ * - `src/shared/types/v8-contracts.js` (LoopStage, DegradedOperationResult)
+ *
+ * Boundary:
+ * - Does not judge action correctness; only measures loop progression.
+ * - Does not block heartbeat; returns degraded diagnostics.
+ * - Stall detection uses cycle-sequence gaps, not wall-clock only.
+ *
+ * Test coverage: tests/unit/observability/causal-loop-health.test.ts
+ */
+import type { StateDatabase } from "../storage/db/index.js";
+import type { LoopStage, DegradedOperationResult } from "../shared/types/v8-contracts.js";
+export interface StageHealth {
+    stage: LoopStage;
+    lastEventAt?: string;
+    lastCycleSequence?: number;
+    eventCount: number;
+    stalled: boolean;
+}
+export interface CausalLoopHealthSnapshot {
+    overallStatus: "healthy" | "degraded" | "stalled" | "no_data";
+    stalledAt?: LoopStage;
+    lastCycleSequence: number;
+    lastHeartbeatAt?: string;
+    stages: StageHealth[];
+    reason?: string;
+}
+export interface AssembleLoopStatusOptions {
+    stallThresholdCycles?: number;
+    limit?: number;
+}
+export declare function assembleLoopStatus(db: StateDatabase, options?: AssembleLoopStatusOptions): Promise<CausalLoopHealthSnapshot | DegradedOperationResult>;

package/runtime/observability/causal-loop-health.js

@@ -0,0 +1,118 @@
+/**
+ * CausalLoopHealth — Assemble loop health snapshot from cycle traces and stage events.
+ *
+ * Core logic: Read recent HeartbeatCycleTrace and LoopStageEvent rows,
+ * compute stage freshness, identify stalled stages, and return
+ * CausalLoopHealthSnapshot.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readHeartbeatCycleTraces, readLoopStageEventsByStage)
+ * - `src/shared/types/v8-contracts.js` (LoopStage, DegradedOperationResult)
+ *
+ * Boundary:
+ * - Does not judge action correctness; only measures loop progression.
+ * - Does not block heartbeat; returns degraded diagnostics.
+ * - Stall detection uses cycle-sequence gaps, not wall-clock only.
+ *
+ * Test coverage: tests/unit/observability/causal-loop-health.test.ts
+ */
+import { readHeartbeatCycleTraces, readLoopStageEventsByStage, } from "../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Config
+// ───────────────────────────────────────────────────────────────
+const DEFAULT_STALL_THRESHOLD_CYCLES = 2;
+const LOOP_STAGES = [
+    "ingestion",
+    "perception",
+    "judgment",
+    "policy",
+    "execution",
+    "closure",
+    "quiet",
+    "dream",
+    "projection",
+];
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function maxCycleSequence(stages) {
+    return Math.max(0, ...stages.map((s) => s.lastCycleSequence ?? 0));
+}
+function findStalledStage(stages, threshold) {
+    const maxSeq = maxCycleSequence(stages);
+    if (maxSeq === 0)
+        return undefined;
+    for (const stage of stages) {
+        if (stage.lastCycleSequence === undefined) {
+            // No events for this stage → stalled if other stages have progressed
+            if (maxSeq > 0)
+                return stage.stage;
+            continue;
+        }
+        const gap = maxSeq - stage.lastCycleSequence;
+        if (gap >= threshold) {
+            return stage.stage;
+        }
+    }
+    return undefined;
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function assembleLoopStatus(db, options) {
+    const threshold = options?.stallThresholdCycles ?? DEFAULT_STALL_THRESHOLD_CYCLES;
+    const limit = options?.limit ?? 100;
+    const cycleResult = await readHeartbeatCycleTraces(db, limit);
+    if (cycleResult.degraded) {
+        return cycleResult.degraded;
+    }
+    const cycles = cycleResult.rows;
+    if (cycles.length === 0) {
+        return {
+            overallStatus: "no_data",
+            lastCycleSequence: 0,
+            stages: [],
+            reason: "no heartbeat cycles recorded",
+        };
+    }
+    const lastCycle = cycles[0];
+    // Gather stage health
+    const stages = [];
+    for (const stage of LOOP_STAGES) {
+        const eventResult = await readLoopStageEventsByStage(db, stage, limit);
+        if (eventResult.degraded) {
+            return eventResult.degraded;
+        }
+        const events = eventResult.rows;
+        const lastEvent = events[0];
+        stages.push({
+            stage,
+            lastEventAt: lastEvent?.occurredAt ?? undefined,
+            lastCycleSequence: lastEvent?.cycleSequence ?? undefined,
+            eventCount: events.length,
+            stalled: false, // computed below
+        });
+    }
+    const stalledAt = findStalledStage(stages, threshold);
+    // Mark stalled stages
+    for (const stage of stages) {
+        if (stalledAt === stage.stage) {
+            stage.stalled = true;
+        }
+    }
+    const overallStatus = stalledAt
+        ? "stalled"
+        : "healthy";
+    return {
+        overallStatus,
+        stalledAt,
+        lastCycleSequence: lastCycle.cycleSequence,
+        lastHeartbeatAt: lastCycle.heartbeatStartedAt,
+        stages,
+        reason: stalledAt ? `stage ${stalledAt} stalled for >=${threshold} cycles` : undefined,
+    };
+}

package/runtime/observability/diagnostic-redaction.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DiagnosticRedaction — Attribute sensitivity blocks and redact diagnostics.
+ *
+ * Core logic: Given a diagnostic payload, classify its sensitivity,
+ * redact credential-shaped values, preserve public technical summaries,
+ * and attribute the block to the responsible system.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ *
+ * Dependencies:
+ * - `src/shared/types/v8-contracts.js` (SourceRef, RedactionClass, SensitivityClass)
+ *
+ * Boundary:
+ * - Pure function; no DB access.
+ * - Does not modify source data; returns redacted copy.
+ * - Public technical vocabulary is preserved.
+ *
+ * Test coverage: tests/unit/observability/diagnostic-redaction.test.ts
+ */
+import type { RedactionClass, SensitivityClass, V8ReasonCode } from "../shared/types/v8-contracts.js";
+export interface DiagnosticPayload {
+    summary: string;
+    detail?: string;
+    sourceSystem: "perception" | "judgment" | "dream" | "policy" | "storage" | "unknown";
+    sensitivityHint?: SensitivityClass;
+    reasonCode?: V8ReasonCode;
+}
+export interface RedactedDiagnostic {
+    summary: string;
+    detail?: string;
+    redactionClass: RedactionClass;
+    attribution: string;
+}
+export type DiagnosticAttribution = "storage_validation_block" | "dream_redaction_block" | "perception_risk_block" | "policy_denial" | "credential_shape_detected" | "private_context" | "public_technical_preserved" | "no_redaction_needed";
+/**
+ * Classify sensitivity-related diagnostic attribution based on source system
+ * and reason code. Maps to deterministic attribution categories per
+ * observability-health-system.detail.md §4.2.
+ */
+export declare function classifyDiagnosticAttribution(sourceSystem: DiagnosticPayload["sourceSystem"], reasonCode?: V8ReasonCode): DiagnosticAttribution;
+export declare function projectDiagnosticRedaction(payload: DiagnosticPayload): RedactedDiagnostic;

package/runtime/observability/diagnostic-redaction.js

@@ -0,0 +1,114 @@
+/**
+ * DiagnosticRedaction — Attribute sensitivity blocks and redact diagnostics.
+ *
+ * Core logic: Given a diagnostic payload, classify its sensitivity,
+ * redact credential-shaped values, preserve public technical summaries,
+ * and attribute the block to the responsible system.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ *
+ * Dependencies:
+ * - `src/shared/types/v8-contracts.js` (SourceRef, RedactionClass, SensitivityClass)
+ *
+ * Boundary:
+ * - Pure function; no DB access.
+ * - Does not modify source data; returns redacted copy.
+ * - Public technical vocabulary is preserved.
+ *
+ * Test coverage: tests/unit/observability/diagnostic-redaction.test.ts
+ */
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function containsCredentialValue(text) {
+    // Match both key=value and Bearer token formats
+    return /\b(?:Bearer|token|secret|password|key|credential)\s*[:=\s]\s*[a-zA-Z0-9+/=_-]{8,}\b/i.test(text);
+}
+function containsPrivateMarker(text) {
+    return /\b(?:DM|private message|confidential|internal only)\b/i.test(text);
+}
+function redactCredentialValues(text) {
+    // Redact both key=value and Bearer token formats
+    return text.replace(/\b((?:Bearer|token|secret|password|key|credential)\s*[:=\s]\s*)[a-zA-Z0-9+/=_-]{8,}\b/gi, "$1[REDACTED]");
+}
+/**
+ * Classify sensitivity-related diagnostic attribution based on source system
+ * and reason code. Maps to deterministic attribution categories per
+ * observability-health-system.detail.md §4.2.
+ */
+export function classifyDiagnosticAttribution(sourceSystem, reasonCode) {
+    // Storage validation blocks
+    if (reasonCode === "state_unreadable" || reasonCode === "quiet_validation_failed") {
+        return "storage_validation_block";
+    }
+    // Dream redaction blocks
+    if (reasonCode === "dream_blocked_redaction") {
+        return "dream_redaction_block";
+    }
+    // Perception risk blocks
+    if (reasonCode === "perception_rules_only" || reasonCode === "evidence_batch_truncated") {
+        return "perception_risk_block";
+    }
+    // Policy denial
+    if (reasonCode?.startsWith("policy_denied") || reasonCode === "policy_downgraded_to_draft") {
+        return "policy_denial";
+    }
+    return "no_redaction_needed";
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export function projectDiagnosticRedaction(payload) {
+    const summary = payload.summary;
+    const detail = payload.detail;
+    // Credential value shape → blocked
+    if (containsCredentialValue(summary) || (detail && containsCredentialValue(detail))) {
+        return {
+            summary: redactCredentialValues(summary),
+            detail: detail ? redactCredentialValues(detail) : undefined,
+            redactionClass: "blocked",
+            attribution: `${payload.sourceSystem}:credential_shape_detected`,
+        };
+    }
+    // Classify attribution from source system + reason code
+    const attribution = classifyDiagnosticAttribution(payload.sourceSystem, payload.reasonCode);
+    // Private context → redacted
+    if (payload.sensitivityHint === "private_context" ||
+        containsPrivateMarker(summary) ||
+        (detail && containsPrivateMarker(detail))) {
+        return {
+            summary: "[redacted: private context]",
+            detail: undefined,
+            redactionClass: "redacted",
+            attribution: `${payload.sourceSystem}:${attribution}`,
+        };
+    }
+    // Public technical → preserve with light redaction
+    if (payload.sensitivityHint === "public_technical") {
+        return {
+            summary,
+            detail,
+            redactionClass: "none",
+            attribution: `${payload.sourceSystem}:public_technical_preserved`,
+        };
+    }
+    // Source-system-specific attribution for blocked/redacted cases
+    if (attribution !== "no_redaction_needed") {
+        const isBlocked = attribution === "policy_denial" || attribution === "dream_redaction_block";
+        return {
+            summary: isBlocked ? `[blocked: ${attribution.replace(/_/g, " ")}]` : summary,
+            detail: isBlocked ? undefined : detail,
+            redactionClass: isBlocked ? "blocked" : "redacted",
+            attribution: `${payload.sourceSystem}:${attribution}`,
+        };
+    }
+    // Default: preserve
+    return {
+        summary,
+        detail,
+        redactionClass: "none",
+        attribution: `${payload.sourceSystem}:no_redaction_needed`,
+    };
+}

package/runtime/observability/loop-stage-event-sink.d.ts

@@ -0,0 +1,43 @@
+/**
+ * LoopStageEventSink — v8 observability stage event recorder.
+ *
+ * Core logic: Validate, redact, and append LoopStageEvent rows.
+ * Malformed events produce degraded diagnostics without blocking the
+ * heartbeat main loop.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.1`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeLoopStageEvent)
+ * - `src/shared/types/v8-contracts.js` (LoopStageEvent, SourceRef, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does NOT make semantic decisions about stage health.
+ * - Does NOT block callers on DB failure; returns degraded result.
+ * - Redacts credential-shaped values before persistence.
+ *
+ * Test coverage: tests/unit/observability/loop-stage-event-sink.test.ts
+ */
+import type { StateDatabase } from "../storage/db/index.js";
+import type { LoopStageEvent, DegradedOperationResult } from "../shared/types/v8-contracts.js";
+export interface RecordLoopStageEventOptions {
+    now?: string;
+}
+export type RecordLoopStageEventResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    degraded: DegradedOperationResult;
+};
+export declare function recordLoopStageEvent(db: StateDatabase, event: Partial<LoopStageEvent>, options?: RecordLoopStageEventOptions): Promise<RecordLoopStageEventResult>;
+export interface BatchRecordResult {
+    succeeded: string[];
+    failed: {
+        id?: string;
+        degraded: DegradedOperationResult;
+    }[];
+}
+export declare function recordLoopStageEvents(db: StateDatabase, events: Partial<LoopStageEvent>[], options?: RecordLoopStageEventOptions): Promise<BatchRecordResult>;

package/runtime/observability/loop-stage-event-sink.js

@@ -0,0 +1,148 @@
+/**
+ * LoopStageEventSink — v8 observability stage event recorder.
+ *
+ * Core logic: Validate, redact, and append LoopStageEvent rows.
+ * Malformed events produce degraded diagnostics without blocking the
+ * heartbeat main loop.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §3.1`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeLoopStageEvent)
+ * - `src/shared/types/v8-contracts.js` (LoopStageEvent, SourceRef, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does NOT make semantic decisions about stage health.
+ * - Does NOT block callers on DB failure; returns degraded result.
+ * - Redacts credential-shaped values before persistence.
+ *
+ * Test coverage: tests/unit/observability/loop-stage-event-sink.test.ts
+ */
+import { writeLoopStageEvent } from "../storage/v8-state-stores.js";
+function validateEvent(event) {
+    if (!event.cycleId || event.cycleId.trim().length === 0) {
+        return { ok: false, reason: "cycle_id_required", field: "cycleId" };
+    }
+    if (!event.stage || event.stage.trim().length === 0) {
+        return { ok: false, reason: "stage_required", field: "stage" };
+    }
+    if (!event.status || event.status.trim().length === 0) {
+        return { ok: false, reason: "status_required", field: "status" };
+    }
+    if (!event.occurredAt || event.occurredAt.trim().length === 0) {
+        return { ok: false, reason: "occurred_at_required", field: "occurredAt" };
+    }
+    const validStages = [
+        "ingestion",
+        "perception",
+        "judgment",
+        "policy",
+        "execution",
+        "closure",
+        "quiet",
+        "dream",
+        "projection",
+    ];
+    if (!validStages.includes(event.stage)) {
+        return { ok: false, reason: "stage_invalid", field: "stage" };
+    }
+    const validStatuses = [
+        "started",
+        "completed",
+        "skipped",
+        "blocked",
+        "failed",
+    ];
+    if (!validStatuses.includes(event.status)) {
+        return { ok: false, reason: "status_invalid", field: "status" };
+    }
+    return { ok: true };
+}
+// ───────────────────────────────────────────────────────────────
+// Redaction
+// ───────────────────────────────────────────────────────────────
+function redactSourceRefs(refs) {
+    let hasRedacted = false;
+    let hasBlocked = false;
+    const redacted = refs.map((ref) => {
+        if (ref.sensitivityClass === "sensitive") {
+            hasBlocked = true;
+            return {
+                ...ref,
+                redactionClass: "blocked",
+                resolveStatus: "redacted",
+                resolveFailureReason: "sensitivity_class_blocked",
+            };
+        }
+        if (ref.sensitivityClass === "private_context") {
+            hasRedacted = true;
+            return {
+                ...ref,
+                redactionClass: "redacted",
+                resolveStatus: "redacted",
+            };
+        }
+        return ref;
+    });
+    const redactionClass = hasBlocked
+        ? "blocked"
+        : hasRedacted
+            ? "redacted"
+            : "none";
+    return { redacted, redactionClass };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function recordLoopStageEvent(db, event, options) {
+    const validation = validateEvent(event);
+    if (!validation.ok) {
+        const degraded = {
+            status: "degraded",
+            reason: "stage_event_missing",
+            ownerStage: event.stage || "ingestion",
+            sourceRefs: event.sourceRefs || [],
+            operatorNextAction: `Fix missing ${validation.field} in stage event`,
+            retryable: false,
+        };
+        return { ok: false, degraded };
+    }
+    const now = options?.now ?? new Date().toISOString();
+    const sourceRefs = event.sourceRefs ?? [];
+    const { redacted: redactedRefs, redactionClass } = redactSourceRefs(sourceRefs);
+    const record = {
+        id: event.id ?? `evt_${now.replace(/[:.]/g, "")}_${event.cycleId}_${event.stage}`,
+        cycleId: event.cycleId,
+        cycleSequence: event.cycleSequence ?? 0,
+        stage: event.stage,
+        status: event.status,
+        reason: event.reason,
+        sourceRefs: redactedRefs,
+        redactionClass,
+        occurredAt: event.occurredAt,
+        expectedDownstreamByCycle: event.expectedDownstreamByCycle,
+        payloadJson: event.payloadJson ?? null,
+        lifecycleStatus: "completed",
+    };
+    const result = await writeLoopStageEvent(db, record);
+    if ("id" in result) {
+        return { ok: true, id: result.id };
+    }
+    return { ok: false, degraded: result };
+}
+export async function recordLoopStageEvents(db, events, options) {
+    const succeeded = [];
+    const failed = [];
+    for (const event of events) {
+        const result = await recordLoopStageEvent(db, event, options);
+        if (result.ok) {
+            succeeded.push(result.id);
+        }
+        else {
+            failed.push({ id: event.id ?? "unknown", degraded: result.degraded });
+        }
+    }
+    return { succeeded, failed };
+}

package/runtime/observability/loop-status.d.ts

@@ -0,0 +1,46 @@
+/**
+ * LoopStatus — Expose loop health and stalled stage diagnostics.
+ *
+ * Core logic: Call assembleLoopStatus, format into v8 loop_status shape,
+ * and include policy-denied closure counts.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md`
+ *
+ * Dependencies:
+ * - `src/observability/causal-loop-health.js` (assembleLoopStatus)
+ * - `src/storage/v8-state-stores.js` (readLoopStageEventsByStage)
+ *
+ * Boundary:
+ * - Read-only diagnostic query; does not modify state.
+ * - Returns degraded envelope when state unreadable.
+ *
+ * Test coverage: tests/unit/observability/loop-status.test.ts
+ */
+import type { StateDatabase } from "../storage/db/index.js";
+import type { DegradedOperationResult } from "../shared/types/v8-contracts.js";
+export interface LoopStatusReadModel {
+    ok: true;
+    overallStatus: string;
+    stalledAt?: string;
+    lastCycleSequence: number;
+    lastHeartbeatAt?: string;
+    stageSummaries: StageSummary[];
+    policyDeniedCount: number;
+    nextAction: string;
+}
+export interface StageSummary {
+    stage: string;
+    eventCount: number;
+    stalled: boolean;
+    lastEventAt?: string;
+}
+export type LoopStatusResult = {
+    ok: true;
+    status: LoopStatusReadModel;
+} | {
+    ok: false;
+    degraded: DegradedOperationResult;
+};
+export declare function readLoopStatus(db: StateDatabase): Promise<LoopStatusResult>;