@haaaiawd/second-nature 0.1.50 → 0.2.0

package/runtime/core/second-nature/quiet-dream/dream-consolidation-runner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DreamConsolidationRunner — Generate memory candidates from Quiet review.
+ *
+ * Core logic: Read DreamConsolidationRun and associated QuietDailyReview,
+ * apply rules-only candidate generation, redaction gate, validation,
+ * and update run status to completed/failed/blocked.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readDreamConsolidationRunById, readQuietDailyReviewById, writeLongTermMemoryProjection)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Rules-only candidate generation; no model assist in this version.
+ * - Does not accept/reject projections; only creates candidates.
+ * - Redaction gate blocks sensitive private content, preserves public technical.
+ *
+ * Test coverage: tests/unit/dream/dream-consolidation-runner.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface DreamMemoryCandidate {
+    id: string;
+    runId: string;
+    reviewId: string;
+    candidateText: string;
+    sourceRefs: SourceRef[];
+    confidence: number;
+    validationStatus: "valid" | "rejected" | "blocked";
+    validationReason?: string;
+}
+export interface RunDreamConsolidationResult {
+    runId: string;
+    status: "completed" | "failed" | "blocked";
+    candidates: DreamMemoryCandidate[];
+    reason?: V8ReasonCode;
+}
+export interface RunDreamConsolidationOptions {
+    now?: string;
+}
+export declare function runDreamConsolidation(db: StateDatabase, runId: string, options?: RunDreamConsolidationOptions): Promise<RunDreamConsolidationResult | DegradedOperationResult>;

package/runtime/core/second-nature/quiet-dream/dream-consolidation-runner.js

@@ -0,0 +1,180 @@
+/**
+ * DreamConsolidationRunner — Generate memory candidates from Quiet review.
+ *
+ * Core logic: Read DreamConsolidationRun and associated QuietDailyReview,
+ * apply rules-only candidate generation, redaction gate, validation,
+ * and update run status to completed/failed/blocked.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readDreamConsolidationRunById, readQuietDailyReviewById, writeLongTermMemoryProjection)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Rules-only candidate generation; no model assist in this version.
+ * - Does not accept/reject projections; only creates candidates.
+ * - Redaction gate blocks sensitive private content, preserves public technical.
+ *
+ * Test coverage: tests/unit/dream/dream-consolidation-runner.test.ts
+ */
+import { readDreamConsolidationRunById, readQuietDailyReviewById, writeLongTermMemoryProjection, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function parsePayloadJson(json) {
+    if (!json)
+        return {};
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+function buildSourceRefsFromReview(review) {
+    return [
+        {
+            uri: `sn://quiet/${review.id}`,
+            family: "quiet_review",
+            id: review.id,
+            redactionClass: "none",
+            resolveStatus: "resolvable",
+        },
+    ];
+}
+function redactSensitive(input) {
+    // Simple redaction: block credential-shaped patterns
+    if (/\b(?:Bearer|token|secret|password|key)\s*[:=]\s*[a-zA-Z0-9+/=]{8,}\b/i.test(input)) {
+        return { text: "[redacted: credential shape detected]", blocked: true };
+    }
+    return { text: input, blocked: false };
+}
+function generateCandidatesFromReview(runId, reviewId, reviewPayload) {
+    const candidates = [];
+    const summary = String(reviewPayload.reviewSummary ?? "");
+    if (summary.length > 0) {
+        const { text, blocked } = redactSensitive(summary);
+        if (blocked) {
+            candidates.push({
+                id: `cand_${runId}_summary`,
+                runId,
+                reviewId,
+                candidateText: text,
+                sourceRefs: buildSourceRefsFromReview({ id: reviewId, day: "" }),
+                confidence: 0.3,
+                validationStatus: "blocked",
+                validationReason: "redaction_blocked",
+            });
+        }
+        else {
+            candidates.push({
+                id: `cand_${runId}_summary`,
+                runId,
+                reviewId,
+                candidateText: `Daily review: ${text}`,
+                sourceRefs: buildSourceRefsFromReview({ id: reviewId, day: "" }),
+                confidence: 0.6,
+                validationStatus: "valid",
+            });
+        }
+    }
+    const importanceSignals = reviewPayload.importanceSignals;
+    if (importanceSignals && importanceSignals.length > 0) {
+        const { text, blocked } = redactSensitive(importanceSignals.join("; "));
+        if (!blocked) {
+            candidates.push({
+                id: `cand_${runId}_signals`,
+                runId,
+                reviewId,
+                candidateText: `Important signals: ${text}`,
+                sourceRefs: buildSourceRefsFromReview({ id: reviewId, day: "" }),
+                confidence: 0.5,
+                validationStatus: "valid",
+            });
+        }
+    }
+    return candidates;
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function runDreamConsolidation(db, runId, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const runRead = await readDreamConsolidationRunById(db, runId);
+    if (runRead.degraded) {
+        return runRead.degraded;
+    }
+    const run = runRead.row;
+    if (!run) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "dream",
+            sourceRefs: [],
+            operatorNextAction: `DreamConsolidationRun ${runId} not found`,
+            retryable: false,
+        };
+    }
+    const reviewRead = await readQuietDailyReviewById(db, run.quietReviewId);
+    if (reviewRead.degraded) {
+        return reviewRead.degraded;
+    }
+    const review = reviewRead.row;
+    if (!review) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "dream",
+            sourceRefs: [],
+            operatorNextAction: `QuietDailyReview ${run.quietReviewId} not found`,
+            retryable: false,
+        };
+    }
+    const reviewPayload = parsePayloadJson(review.payloadJson);
+    const candidates = generateCandidatesFromReview(runId, run.quietReviewId, reviewPayload);
+    // If all candidates blocked → run blocked
+    if (candidates.length > 0 && candidates.every((c) => c.validationStatus === "blocked")) {
+        return {
+            runId,
+            status: "blocked",
+            candidates,
+            reason: "dream_blocked_redaction",
+        };
+    }
+    // Write valid candidates as projections (candidate status)
+    const validCandidates = candidates.filter((c) => c.validationStatus === "valid");
+    for (const candidate of validCandidates) {
+        const projectionResult = await writeLongTermMemoryProjection(db, {
+            id: `proj_${candidate.id}`,
+            createdAt: now,
+            candidateId: candidate.id,
+            topicKey: `topic_${review.day}`,
+            status: "candidate",
+            sourceRefs: candidate.sourceRefs,
+            redactionClass: "none",
+            lifecycleStatus: "candidate",
+            payloadJson: JSON.stringify({
+                candidateText: candidate.candidateText,
+                confidence: candidate.confidence,
+                runId,
+            }),
+        });
+        if ("reason" in projectionResult) {
+            return {
+                runId,
+                status: "failed",
+                candidates,
+                reason: projectionResult.reason,
+            };
+        }
+    }
+    return {
+        runId,
+        status: "completed",
+        candidates,
+        reason: "dream_completed",
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * 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 type { StateDatabase } from "../../../storage/db/index.js";
+import type { DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface DreamScheduleResult {
+    id: string;
+    quietReviewId: string;
+    status: "scheduled" | "started" | "completed" | "failed" | "blocked";
+    reason?: V8ReasonCode;
+    createdAt: string;
+}
+export interface ScheduleDreamAfterQuietOptions {
+    now?: string;
+    schedulerAvailable?: boolean;
+}
+export declare function scheduleDreamAfterQuiet(db: StateDatabase, quietReviewId: string, options?: ScheduleDreamAfterQuietOptions): Promise<DreamScheduleResult | DegradedOperationResult>;

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>;