@haaaiawd/second-nature 0.1.50 → 0.2.0

package/runtime/storage/v8-state-stores.js

@@ -0,0 +1,491 @@
+/**
+ * v8 State Stores — Bounded write/read ports for Living Perception Loop entities.
+ *
+ * Core logic: Persist and retrieve EvidenceItem, PerceptionCard, JudgmentVerdict,
+ * ActionClosureRecord, QuietDailyReview, DreamConsolidationRun,
+ * LongTermMemoryProjection, HeartbeatCycleTrace, and LoopStageEvent.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/state-memory-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md`
+ *
+ * Dependencies:
+ * - drizzle-orm (SQLite)
+ * - `src/storage/db/schema/v8-entities.js`
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult)
+ *
+ * Boundary:
+ * - Write validation: rejects missing source refs, checks redaction class.
+ * - Read models: bounded by family + status filters; no cross-family joins.
+ * - Degraded state: returns DegradedOperationResult on DB failure, never throws.
+ *
+ * Test coverage: tests/unit/storage/v8-state-stores.test.ts
+ */
+import { eq, desc, like } from "drizzle-orm";
+import { evidenceItem, perceptionCard, judgmentVerdict, actionClosureRecord, quietDailyReview, dreamConsolidationRun, longTermMemoryProjection, heartbeatCycleTrace, loopStageEvent, } from "./db/schema/v8-entities.js";
+// ───────────────────────────────────────────────────────────────
+// Shared helpers
+// ───────────────────────────────────────────────────────────────
+function serializeSourceRefs(refs) {
+    return JSON.stringify(refs);
+}
+function parseSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        if (Array.isArray(parsed))
+            return parsed;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function makeDegraded(reason, ownerStage, operatorNextAction, sourceRefs = []) {
+    return {
+        status: "degraded",
+        reason,
+        ownerStage,
+        sourceRefs,
+        operatorNextAction,
+        retryable: true,
+    };
+}
+function validateSourceRefs(sourceRefs, ownerStage) {
+    if (!sourceRefs || sourceRefs.length === 0) {
+        return {
+            ok: false,
+            degraded: makeDegraded("source_refs_unresolved", ownerStage, "Ensure caller supplies at least one SourceRef"),
+        };
+    }
+    return { ok: true, record: sourceRefs };
+}
+// ───────────────────────────────────────────────────────────────
+// EvidenceItem store
+// ───────────────────────────────────────────────────────────────
+export async function writeEvidenceItem(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "ingestion");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(evidenceItem).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "ingestion", "Retry evidence write after DB recovery", validated.record);
+    }
+}
+export async function readEvidenceItemsByStatus(db, lifecycleStatus) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(evidenceItem)
+            .where(eq(evidenceItem.lifecycleStatus, lifecycleStatus))
+            .orderBy(desc(evidenceItem.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "ingestion", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// PerceptionCard store
+// ───────────────────────────────────────────────────────────────
+export async function writePerceptionCard(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "perception");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(perceptionCard).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "perception", "Retry perception write after DB recovery", validated.record);
+    }
+}
+export async function readPerceptionCardsByCycle(db, cycleId) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(perceptionCard)
+            .where(eq(perceptionCard.cycleId, cycleId))
+            .orderBy(desc(perceptionCard.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "perception", "Check state database connectivity"),
+        };
+    }
+}
+export async function readPerceptionCardById(db, id) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(perceptionCard)
+            .where(eq(perceptionCard.id, id))
+            .limit(1);
+        return { row: rows[0] };
+    }
+    catch {
+        return {
+            degraded: makeDegraded("state_unreadable", "perception", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// JudgmentVerdict store
+// ───────────────────────────────────────────────────────────────
+export async function writeJudgmentVerdict(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "judgment");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(judgmentVerdict).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "judgment", "Retry judgment write after DB recovery", validated.record);
+    }
+}
+export async function readJudgmentVerdictsByCycle(db, cycleId) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(judgmentVerdict)
+            .where(eq(judgmentVerdict.cycleId, cycleId))
+            .orderBy(desc(judgmentVerdict.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "judgment", "Check state database connectivity"),
+        };
+    }
+}
+export async function readJudgmentVerdictById(db, id) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(judgmentVerdict)
+            .where(eq(judgmentVerdict.id, id))
+            .limit(1);
+        return { row: rows[0] };
+    }
+    catch {
+        return {
+            degraded: makeDegraded("state_unreadable", "judgment", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// ActionClosureRecord store
+// ───────────────────────────────────────────────────────────────
+export async function writeActionClosureRecord(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "closure");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(actionClosureRecord).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "closure", "Retry closure write after DB recovery", validated.record);
+    }
+}
+export async function readActionClosuresByCycle(db, cycleId) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(actionClosureRecord)
+            .where(eq(actionClosureRecord.cycleId, cycleId))
+            .orderBy(desc(actionClosureRecord.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "closure", "Check state database connectivity"),
+        };
+    }
+}
+export async function readActionClosuresByDay(db, day) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(actionClosureRecord)
+            .where(like(actionClosureRecord.createdAt, `${day}%`))
+            .orderBy(desc(actionClosureRecord.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "closure", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// QuietDailyReview store
+// ───────────────────────────────────────────────────────────────
+export async function writeQuietDailyReview(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "quiet");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(quietDailyReview).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "quiet", "Retry Quiet write after DB recovery", validated.record);
+    }
+}
+export async function readQuietDailyReviewById(db, id) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(quietDailyReview)
+            .where(eq(quietDailyReview.id, id))
+            .limit(1);
+        return { row: rows[0] };
+    }
+    catch {
+        return {
+            degraded: makeDegraded("state_unreadable", "quiet", "Check state database connectivity"),
+        };
+    }
+}
+export async function readQuietDailyReviewsByDay(db, day) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(quietDailyReview)
+            .where(eq(quietDailyReview.day, day))
+            .orderBy(desc(quietDailyReview.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "quiet", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// DreamConsolidationRun store
+// ───────────────────────────────────────────────────────────────
+export async function writeDreamConsolidationRun(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "dream");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(dreamConsolidationRun).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "dream", "Retry Dream write after DB recovery", validated.record);
+    }
+}
+export async function readDreamConsolidationRunById(db, id) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(dreamConsolidationRun)
+            .where(eq(dreamConsolidationRun.id, id))
+            .limit(1);
+        return { row: rows[0] };
+    }
+    catch {
+        return {
+            degraded: makeDegraded("state_unreadable", "dream", "Check state database connectivity"),
+        };
+    }
+}
+export async function readDreamConsolidationRunsByQuietId(db, quietReviewId) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(dreamConsolidationRun)
+            .where(eq(dreamConsolidationRun.quietReviewId, quietReviewId))
+            .orderBy(desc(dreamConsolidationRun.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "dream", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// LongTermMemoryProjection store
+// ───────────────────────────────────────────────────────────────
+export async function writeLongTermMemoryProjection(db, row) {
+    const validated = validateSourceRefs(row.sourceRefs, "projection");
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(longTermMemoryProjection).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "projection", "Retry projection write after DB recovery", validated.record);
+    }
+}
+export async function readMemoryProjectionsByStatus(db, status) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(longTermMemoryProjection)
+            .where(eq(longTermMemoryProjection.status, status))
+            .orderBy(desc(longTermMemoryProjection.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "projection", "Check state database connectivity"),
+        };
+    }
+}
+export async function readMemoryProjectionsByTopic(db, topicKey) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(longTermMemoryProjection)
+            .where(eq(longTermMemoryProjection.topicKey, topicKey))
+            .orderBy(desc(longTermMemoryProjection.createdAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "projection", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// HeartbeatCycleTrace store
+// ───────────────────────────────────────────────────────────────
+export async function writeHeartbeatCycleTrace(db, row) {
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: row.sourceRefs ? serializeSourceRefs(row.sourceRefs) : "[]",
+        };
+        await db.db.insert(heartbeatCycleTrace).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", "ingestion", "Retry cycle trace write after DB recovery");
+    }
+}
+export async function readHeartbeatCycleTraces(db, limit = 100) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(heartbeatCycleTrace)
+            .orderBy(desc(heartbeatCycleTrace.cycleSequence))
+            .limit(limit);
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "ingestion", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// LoopStageEvent store
+// ───────────────────────────────────────────────────────────────
+export async function writeLoopStageEvent(db, row) {
+    const stage = row.stage;
+    const validated = validateSourceRefs(row.sourceRefs, stage);
+    if (!validated.ok)
+        return validated.degraded;
+    try {
+        const record = {
+            ...row,
+            sourceRefsJson: serializeSourceRefs(validated.record),
+        };
+        await db.db.insert(loopStageEvent).values(record);
+        return { id: row.id };
+    }
+    catch {
+        return makeDegraded("state_unreadable", stage, "Retry stage event write after DB recovery", validated.record);
+    }
+}
+export async function readLoopStageEventsByCycle(db, cycleId) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(loopStageEvent)
+            .where(eq(loopStageEvent.cycleId, cycleId))
+            .orderBy(desc(loopStageEvent.occurredAt));
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "closure", "Check state database connectivity"),
+        };
+    }
+}
+export async function readLoopStageEventsByStage(db, stage, limit = 100) {
+    try {
+        const rows = await db.db
+            .select()
+            .from(loopStageEvent)
+            .where(eq(loopStageEvent.stage, stage))
+            .orderBy(desc(loopStageEvent.occurredAt))
+            .limit(limit);
+        return { rows };
+    }
+    catch {
+        return {
+            rows: [],
+            degraded: makeDegraded("state_unreadable", "closure", "Check state database connectivity"),
+        };
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// SourceRef round-trip helper (for tests and consumers)
+// ───────────────────────────────────────────────────────────────
+export function extractSourceRefs(row) {
+    return parseSourceRefs(row.sourceRefsJson);
+}

package/HEARTBEAT.md

@@ -1,44 +0,0 @@
-# Second Nature Heartbeat
-
-Use the shipping Second Nature bridge by calling `second_nature_ops` with command `heartbeat_check` once per heartbeat round.
-
-## OpenClaw workspace root (operator)
-
-For **full read-bridge** behavior (`workspaceRootResolution` → `env` / `tool_args`), set **`SECOND_NATURE_WORKSPACE_ROOT`** on the gateway **or** pass **`workspaceRoot`** on each `second_nature_ops` call to the **same absolute path** as the OpenClaw **agent workspace** (default `~/.openclaw/workspace`, or `agents.defaults.workspace` in `~/.openclaw/openclaw.json`). That is where `workspace/SOUL.md`, `HEARTBEAT.md`, and Second Nature `data/` should live together. **Sandbox** or **per-agent** layouts: use the **actual** directory where the agent’s files and DB are mounted — see `explore/reports/2026-05-04_openclaw-plugin-install-vs-workspace-root.md` and `.anws/v5/05_TASKS.md` T1.1.4 **运维约定 (OpenClaw 宿主)**.
-
-## Tool call
-
-```json
-{
-  "command": "heartbeat_check",
-  "args": {
-    "timestamp": "<ISO-8601 timestamp>",
-    "sessionContext": "<optional short session summary>",
-    "heartbeatChecklist": "HEARTBEAT.md"
-  }
-}
-```
-
-## Success semantics
-
-- **Workspace CLI / full runtime** (read models wired): if the result contains `status: "heartbeat_ok"` (or another explicit lived-experience outcome from the decision loop), treat it per that surface’s contract.
-- **OpenClaw plugin + known workspace root** (`SECOND_NATURE_WORKSPACE_ROOT` or tool `workspaceRoot` resolving to `env` / `tool_args`, state DB openable): `heartbeat_check`, `quiet`, `status`, `explain`, `fallback`, `report`, `session`, and `credential` **show** use the **same read path as the workspace CLI** (lazy-loaded packaged runtime). Results match CLI-shaped payloads or return an explicit error — not carrier placeholders.
-- **Shipping host-safe plugin** (`second_nature_ops` on the packaged carrier): when the workspace root is **unknown**, expect `status: "runtime_carrier_only"` with `data.bridge.serviceEntryMode: "runtime_carrier_only"`. That means the carrier acknowledged the round — **not** that a full lived-experience decision loop ran on workspace state.
-- Treat the carrier-only result as “no additional action is required **from this carrier surface** for this round”; do not infer rhythm health or empty workspace telemetry from it.
-
-## Next-step semantics
-
-- If the result includes `nextAction: "continue_carrier_surface_only"`, continue the regular heartbeat flow without assuming workspace read models were evaluated.
-- If a future structured heartbeat decision returns a different `nextAction`, follow that explicit action instead of inventing one.
-
-## Boundary
-
-- This file defines the shipping heartbeat bridge entry.
-- Do not treat `second-nature-runtime` service startup as a per-heartbeat callback.
-- If heartbeat or Quiet notices a useful platform action that is not registered yet, it may call `second_nature_ops` with `command=connector_behavior_add`. That records a manifest capability only; it does not grant execution trust.
-
-## Agent habit
-
-Heartbeat only tells Claw how to touch the bridge. For the softer habit of using Second Nature in conversation, read `docs/claw-second-nature-inner-guide.md`: pause, look back at traces, and do not turn carrier acknowledgement into invented memory.
-
-When you discover a repeated action, name it plainly, such as `github:issue.search` or `agent-world:profile.inspect`, and leave a short reason in `description` or concrete `sourceRefs`. If you have seen it more than once, include `observedCount`. Good behavior evolution feels like leaving a note for your future self, not forcing the system to pretend it can already do more.