@haaaiawd/second-nature 0.1.51 → 0.2.0

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

@@ -0,0 +1,105 @@
+/**
+ * DreamScheduler — Schedule Dream consolidation after Quiet completion.
+ *
+ * Core logic: Read a QuietDailyReview, create a DreamConsolidationRun
+ * with lifecycle trace, and write it to state. Handles unavailable
+ * scheduler by recording degraded state.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readQuietDailyReviewById, writeDreamConsolidationRun)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does not run consolidation; only schedules and records lifecycle.
+ * - Does not form long-term memory; Dream runner does that.
+ * - Degrades gracefully on missing review or unreadable state.
+ *
+ * Test coverage: tests/unit/dream/dream-scheduler-lifecycle.test.ts
+ */
+import { readQuietDailyReviewById, writeDreamConsolidationRun, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function scheduleDreamAfterQuiet(db, quietReviewId, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const readResult = await readQuietDailyReviewById(db, quietReviewId);
+    if (readResult.degraded) {
+        return readResult.degraded;
+    }
+    const review = readResult.row;
+    if (!review) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "dream",
+            sourceRefs: [],
+            operatorNextAction: `QuietDailyReview ${quietReviewId} not found`,
+            retryable: false,
+        };
+    }
+    const runId = `dream_${quietReviewId}_${now.replace(/[:.]/g, "")}`;
+    // Scheduler unavailable → record blocked state
+    if (options?.schedulerAvailable === false) {
+        const writeResult = await writeDreamConsolidationRun(db, {
+            id: runId,
+            createdAt: now,
+            quietReviewId,
+            status: "blocked",
+            reason: "dream_scheduler_unavailable",
+            sourceRefs: [
+                {
+                    uri: `sn://dream/scheduler_unavailable/${quietReviewId}`,
+                    family: "dream_run",
+                    id: quietReviewId,
+                    redactionClass: "none",
+                    resolveStatus: "resolvable",
+                },
+            ],
+            redactionClass: "none",
+            lifecycleStatus: "pending",
+            payloadJson: JSON.stringify({ scheduledAt: now, blocked: true }),
+        });
+        if ("reason" in writeResult) {
+            return writeResult;
+        }
+        return {
+            id: runId,
+            quietReviewId,
+            status: "blocked",
+            reason: "dream_scheduler_unavailable",
+            createdAt: now,
+        };
+    }
+    // Normal schedule
+    const writeResult = await writeDreamConsolidationRun(db, {
+        id: runId,
+        createdAt: now,
+        quietReviewId,
+        status: "scheduled",
+        sourceRefs: [
+            {
+                uri: `sn://dream/scheduled/${quietReviewId}`,
+                family: "dream_run",
+                id: quietReviewId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ],
+        redactionClass: "none",
+        lifecycleStatus: "pending",
+        payloadJson: JSON.stringify({ scheduledAt: now }),
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return {
+        id: runId,
+        quietReviewId,
+        status: "scheduled",
+        createdAt: now,
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * MemoryProjectionLifecycle — Manage accepted long-term memory projections.
+ *
+ * Core logic: Accept, activate, supersede, and reject projections.
+ * When accepting a projection on a topic with existing active projection,
+ * supersede the old one.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readMemoryProjectionsByTopic, writeLongTermMemoryProjection)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Only accepts projections with source refs.
+ * - Supersedes old active projections on same topic automatically.
+ * - Does not delete projections; only transitions status.
+ *
+ * Test coverage: tests/unit/dream/memory-projection-lifecycle.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface ProjectionLifecycleResult {
+    projectionId: string;
+    status: "accepted" | "rejected" | "superseded" | "retired";
+    reason: V8ReasonCode;
+    supersedesProjectionId?: string;
+}
+export interface AcceptMemoryProjectionOptions {
+    now?: string;
+}
+export declare function acceptMemoryProjection(db: StateDatabase, candidateId: string, topicKey: string, memoryText: string, sourceRefs: SourceRef[], options?: AcceptMemoryProjectionOptions): Promise<ProjectionLifecycleResult | DegradedOperationResult>;
+export declare function rejectMemoryProjection(db: StateDatabase, projectionId: string, candidateId: string, topicKey: string, sourceRefs: SourceRef[], reason?: V8ReasonCode, options?: AcceptMemoryProjectionOptions): Promise<ProjectionLifecycleResult | DegradedOperationResult>;
+export declare function retireMemoryProjection(db: StateDatabase, projectionId: string, candidateId: string, topicKey: string, sourceRefs: SourceRef[], options?: AcceptMemoryProjectionOptions): Promise<ProjectionLifecycleResult | DegradedOperationResult>;

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

@@ -0,0 +1,151 @@
+/**
+ * MemoryProjectionLifecycle — Manage accepted long-term memory projections.
+ *
+ * Core logic: Accept, activate, supersede, and reject projections.
+ * When accepting a projection on a topic with existing active projection,
+ * supersede the old one.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readMemoryProjectionsByTopic, writeLongTermMemoryProjection)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Only accepts projections with source refs.
+ * - Supersedes old active projections on same topic automatically.
+ * - Does not delete projections; only transitions status.
+ *
+ * Test coverage: tests/unit/dream/memory-projection-lifecycle.test.ts
+ */
+import { readMemoryProjectionsByTopic, writeLongTermMemoryProjection, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function acceptMemoryProjection(db, candidateId, topicKey, memoryText, sourceRefs, options) {
+    const now = options?.now ?? new Date().toISOString();
+    if (sourceRefs.length === 0) {
+        return {
+            status: "degraded",
+            reason: "source_refs_unresolved",
+            ownerStage: "projection",
+            sourceRefs: [],
+            operatorNextAction: "Acceptance requires source refs",
+            retryable: false,
+        };
+    }
+    const existing = await readMemoryProjectionsByTopic(db, topicKey);
+    if (existing.degraded) {
+        return existing.degraded;
+    }
+    // Find active projection to supersede
+    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,
+            }),
+        });
+        if ("reason" in supersedeResult) {
+            return supersedeResult;
+        }
+        supersedesId = activeProjection.id;
+    }
+    // Create new accepted/active projection
+    const projectionId = `proj_${candidateId}_${now.replace(/[:.]/g, "")}`;
+    const writeResult = await writeLongTermMemoryProjection(db, {
+        id: projectionId,
+        createdAt: now,
+        candidateId,
+        topicKey,
+        status: "active",
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "active",
+        payloadJson: JSON.stringify({
+            memoryText,
+            acceptedAt: now,
+            supersedesProjectionId: supersedesId,
+        }),
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return {
+        projectionId,
+        status: "accepted",
+        reason: "projection_accepted",
+        supersedesProjectionId: supersedesId,
+    };
+}
+export async function rejectMemoryProjection(db, projectionId, candidateId, topicKey, sourceRefs, reason = "projection_rejected", options) {
+    const now = options?.now ?? new Date().toISOString();
+    const writeResult = await writeLongTermMemoryProjection(db, {
+        id: projectionId,
+        createdAt: now,
+        candidateId,
+        topicKey,
+        status: "rejected",
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "rejected",
+        payloadJson: JSON.stringify({ rejectedAt: now, reason }),
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return {
+        projectionId,
+        status: "rejected",
+        reason,
+    };
+}
+export async function retireMemoryProjection(db, projectionId, candidateId, topicKey, sourceRefs, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const writeResult = await writeLongTermMemoryProjection(db, {
+        id: projectionId,
+        createdAt: now,
+        candidateId,
+        topicKey,
+        status: "retired",
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "retired",
+        payloadJson: JSON.stringify({ retiredAt: now }),
+    });
+    if ("reason" in writeResult) {
+        return writeResult;
+    }
+    return {
+        projectionId,
+        status: "retired",
+        reason: "projection_rejected",
+    };
+}
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function parseSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * 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 type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface QuietDailyReviewResult {
+    id: string;
+    day: string;
+    closureCount: number;
+    memoryCandidateCount: number;
+    sourceRefs: SourceRef[];
+    reviewSummary: string;
+    importanceSignals: string[];
+    createdAt: string;
+}
+export interface BuildQuietDailyReviewOptions {
+    day?: string;
+    now?: string;
+}
+export type BuildQuietDailyReviewOutput = {
+    status: "completed";
+    review: QuietDailyReviewResult;
+} | {
+    status: "empty";
+    reason: V8ReasonCode;
+} | DegradedOperationResult;
+export declare function buildQuietDailyReview(db: StateDatabase, options?: BuildQuietDailyReviewOptions): Promise<BuildQuietDailyReviewOutput>;

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;