@haaaiawd/second-nature 0.2.8 → 0.2.12

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

@@ -22,7 +22,7 @@
  *   so `dreamStatus` reaches completed/blocked.
  * - Does not bypass Dream runner; only records due/completed/blocked.
  */
-import { writeDailyRhythmState, readDailyRhythmStateByDay, readActionClosuresByDay, readDreamConsolidationRunById, readDreamConsolidationRunsByQuietId, updateDreamConsolidationRunStatus, } from "../../../storage/v8-state-stores.js";
+import { writeDailyRhythmState, readDailyRhythmStateByDay, readActionClosuresByDay, readDreamConsolidationRunById, readDreamConsolidationRunsByQuietId, readLatestDreamConsolidationRunByStatus, updateDreamConsolidationRunStatus, } from "../../../storage/v8-state-stores.js";
 import { buildQuietDailyReview } from "./quiet-daily-review-builder.js";
 import { scheduleDreamAfterQuiet } from "./dream-scheduler.js";
 import { runDreamConsolidation } from "./dream-consolidation-runner.js";
@@ -112,7 +112,6 @@ async function executeStaleScheduledDreams(db, state, now) {
                 const finalReason = dreamResult.reason ?? undefined;
                 const updateResult = await updateDreamConsolidationRunStatus(db, runId, finalStatus, {
                     reason: finalReason ?? null,
-                    lifecycleStatus: finalStatus === "completed" ? "completed" : "archived",
                     payloadJson: JSON.stringify({
                         ...parsePayloadJson(run.payloadJson),
                         consolidatedAt: now,
@@ -226,18 +225,17 @@ export async function checkDailyRhythm(db, options) {
             // Already handled; do not re-schedule
         }
         else {
+            // Global 7-day interval check: look across all quiet reviews, not just today's.
             const quietId = `quiet_${day}`;
-            const latestRun = await loadLatestDreamRunForQuiet(db, quietId);
-            if (latestRun.degraded) {
-                return latestRun.degraded;
+            const globalLatest = await readLatestDreamConsolidationRunByStatus(db, ["completed", "blocked"]);
+            if (globalLatest.degraded) {
+                return globalLatest.degraded;
             }
-            // If a completed/blocked run already exists within the 7-day interval, honor it.
-            if (latestRun.row &&
-                (latestRun.row.status === "completed" || latestRun.row.status === "blocked") &&
-                isWithinDays(latestRun.row.createdAt, now, DREAM_DEFAULT_INTERVAL_DAYS)) {
-                state.dreamStatus = latestRun.row.status;
-                state.dreamReason = latestRun.row.reason ?? "dream_completed";
-                if (latestRun.row.status === "completed") {
+            if (globalLatest.row &&
+                isWithinDays(globalLatest.row.createdAt, now, DREAM_DEFAULT_INTERVAL_DAYS)) {
+                state.dreamStatus = globalLatest.row.status;
+                state.dreamReason = "dream_interval_active";
+                if (globalLatest.row.status === "completed") {
                     state.dreamCompletedAt = now;
                 }
             }
@@ -268,7 +266,6 @@ export async function checkDailyRhythm(db, options) {
                         const dreamOutcome = consolidateResult;
                         const updateResult = await updateDreamConsolidationRunStatus(db, dreamResult.id, dreamOutcome.status, {
                             reason: dreamOutcome.reason ?? null,
-                            lifecycleStatus: dreamOutcome.status === "completed" ? "completed" : "archived",
                             payloadJson: JSON.stringify({
                                 consolidatedAt: now,
                                 candidateCount: dreamOutcome.candidates.length,

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

@@ -31,6 +31,7 @@ export interface DreamMemoryCandidate {
     confidence: number;
     validationStatus: "valid" | "rejected" | "blocked";
     validationReason?: string;
+    acceptedProjectionId?: string;
 }
 export interface RunDreamConsolidationResult {
     runId: string;

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

@@ -20,7 +20,8 @@
  *
  * Test coverage: tests/unit/dream/dream-consolidation-runner.test.ts
  */
-import { readDreamConsolidationRunById, readQuietDailyReviewById, writeLongTermMemoryProjection, } from "../../../storage/v8-state-stores.js";
+import { readDreamConsolidationRunById, readQuietDailyReviewById, } from "../../../storage/v8-state-stores.js";
+import { acceptMemoryProjection } from "./memory-projection-lifecycle.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -144,30 +145,21 @@ export async function runDreamConsolidation(db, runId, options) {
             reason: "dream_blocked_redaction",
         };
     }
-    // Write valid candidates as projections (candidate status)
+    // Accept valid candidates as active long-term memory projections.
+    // This completes the Dream→memory lifecycle so accepted projections can be
+    // loaded by EmbodiedContext in subsequent heartbeats (T-DQ.R.3 followup).
     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) {
+        const acceptResult = await acceptMemoryProjection(db, candidate.id, `topic_${review.day}`, candidate.candidateText, candidate.sourceRefs, { now });
+        if ("projectionId" in acceptResult) {
+            candidate.acceptedProjectionId = acceptResult.projectionId;
+        }
+        else {
             return {
                 runId,
                 status: "failed",
                 candidates,
-                reason: projectionResult.reason,
+                reason: acceptResult.reason,
             };
         }
     }

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

@@ -60,7 +60,6 @@ export async function scheduleDreamAfterQuiet(db, quietReviewId, options) {
                 },
             ],
             redactionClass: "none",
-            lifecycleStatus: "pending",
             payloadJson: JSON.stringify({ scheduledAt: now, blocked: true }),
         });
         if ("reason" in writeResult) {
@@ -90,7 +89,6 @@ export async function scheduleDreamAfterQuiet(db, quietReviewId, options) {
             },
         ],
         redactionClass: "none",
-        lifecycleStatus: "pending",
         payloadJson: JSON.stringify({ scheduledAt: now }),
     });
     if ("reason" in writeResult) {

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

@@ -65,7 +65,6 @@ export async function acceptMemoryProjection(db, candidateId, topicKey, memoryTe
         status: "active",
         sourceRefs,
         redactionClass: "none",
-        lifecycleStatus: "active",
         payloadJson: JSON.stringify({
             memoryText,
             acceptedAt: now,
@@ -111,17 +110,6 @@ export async function retireMemoryProjection(db, projectionId, _candidateId, _to
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
-function parseSourceRefs(json) {
-    if (!json)
-        return [];
-    try {
-        const parsed = JSON.parse(json);
-        return Array.isArray(parsed) ? parsed : [];
-    }
-    catch {
-        return [];
-    }
-}
 function parsePayloadJson(json) {
     if (!json)
         return {};

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

@@ -22,6 +22,7 @@
  * Test coverage: tests/unit/quiet/quiet-daily-review-builder.test.ts
  */
 import { readActionClosuresByDay, writeQuietDailyReview, readPerceptionCardById, readEvidenceItemsByDay, readPerceptionCardsByDay, } from "../../../storage/v8-state-stores.js";
+import { parseSourceRefs } from "../../../shared/serialization.js";
 // ───────────────────────────────────────────────────────────────
 // Config
 // ───────────────────────────────────────────────────────────────
@@ -52,17 +53,6 @@ function buildSourceRefFromClosure(closure) {
         resolveStatus: "resolvable",
     };
 }
-function parseSourceRefs(json) {
-    if (!json)
-        return [];
-    try {
-        const parsed = JSON.parse(json);
-        return Array.isArray(parsed) ? parsed : [];
-    }
-    catch {
-        return [];
-    }
-}
 function buildSourceRefFromEvidence(evidence) {
     const refs = parseSourceRefs(evidence.sourceRefsJson);
     return (refs[0] ?? {

package/runtime/core/second-nature/types.d.ts

@@ -1,16 +1,9 @@
+import type { SourceRef } from "../../shared/types/v8-contracts.js";
 export type TopLevelMode = "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
 /** Control-plane candidate kinds; includes `quiet` for quiet-window–biased intents (L0 alignment). */
 export type IntentKind = "work" | "exploration" | "social" | "quiet" | "reflection" | "outreach" | "maintenance";
 export type DecisionBasis = "rule_only" | "score_based" | "model_assisted";
 export type GuardVerdict = "allow" | "defer" | "deny" | "escalate";
-/** Minimal source ref for planner / guards (matches state-system `SourceRef` subset). */
-export interface ControlPlaneSourceRef {
-    id: string;
-    kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
-    uri: string;
-    excerptHash?: string;
-    observedAt?: string;
-}
 export interface ContinuitySnapshot {
     mode: TopLevelMode;
     currentWindowId: string;
@@ -40,7 +33,7 @@ export interface CandidateIntent {
     summary: string;
     effectClass: CandidateEffectClass;
     /** Required for source-backed guard; may be empty when planner expects hard-guard deny. */
-    sourceRefs: ControlPlaneSourceRef[];
+    sourceRefs: SourceRef[];
     /** Dedupe / cooldown key; defaults to stable fingerprint in guard layer when omitted. */
     idempotencyKey?: string;
     /** T2.1.4: IDs of accepted AgentGoals that influenced this candidate's priority. */

package/runtime/dream/dream-engine.js

@@ -165,12 +165,19 @@ export async function runDream(input) {
                     });
                 }
                 if (!fallbackReason) {
+                    let timeoutHandle;
                     const timeoutPromise = new Promise((_, reject) => {
-                        setTimeout(() => reject(new Error("model_timeout")), operatorTimeoutMs);
+                        timeoutHandle = setTimeout(() => reject(new Error("model_timeout")), operatorTimeoutMs);
                     });
-                    modelResult = await Promise.race([modelPromise, timeoutPromise]);
-                    mode = "hybrid_llm";
-                    llmCostUsd = modelResult.costUsd;
+                    try {
+                        modelResult = await Promise.race([modelPromise, timeoutPromise]);
+                        mode = "hybrid_llm";
+                        llmCostUsd = modelResult.costUsd;
+                    }
+                    finally {
+                        if (timeoutHandle)
+                            clearTimeout(timeoutHandle);
+                    }
                 }
             }
             catch (err) {

package/runtime/guidance/outreach-draft-schema.d.ts

@@ -8,11 +8,11 @@ import { z } from "zod";
 export declare const guidanceSourceRefSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
+        connector_result: "connector_result";
         platform_item: "platform_item";
         workspace_artifact: "workspace_artifact";
         decision_record: "decision_record";
         user_anchor: "user_anchor";
-        connector_result: "connector_result";
         host_report: "host_report";
         fallback_artifact: "fallback_artifact";
     }>;
@@ -66,11 +66,11 @@ export declare const sceneGuidanceRequestSchema: z.ZodObject<{
     sourceRefs: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            connector_result: "connector_result";
             platform_item: "platform_item";
             workspace_artifact: "workspace_artifact";
             decision_record: "decision_record";
             user_anchor: "user_anchor";
-            connector_result: "connector_result";
             host_report: "host_report";
             fallback_artifact: "fallback_artifact";
         }>;
@@ -104,11 +104,11 @@ export declare const outreachNarrativeContextSchema: z.ZodObject<{
     sourceRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            connector_result: "connector_result";
             platform_item: "platform_item";
             workspace_artifact: "workspace_artifact";
             decision_record: "decision_record";
             user_anchor: "user_anchor";
-            connector_result: "connector_result";
             host_report: "host_report";
             fallback_artifact: "fallback_artifact";
         }>;
@@ -124,11 +124,11 @@ export declare const outreachRelationshipContextSchema: z.ZodObject<{
     sourceRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            connector_result: "connector_result";
             platform_item: "platform_item";
             workspace_artifact: "workspace_artifact";
             decision_record: "decision_record";
             user_anchor: "user_anchor";
-            connector_result: "connector_result";
             host_report: "host_report";
             fallback_artifact: "fallback_artifact";
         }>;
@@ -160,11 +160,11 @@ export declare const outreachDraftRequestSchema: z.ZodObject<{
     sourceRefs: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            connector_result: "connector_result";
             platform_item: "platform_item";
             workspace_artifact: "workspace_artifact";
             decision_record: "decision_record";
             user_anchor: "user_anchor";
-            connector_result: "connector_result";
             host_report: "host_report";
             fallback_artifact: "fallback_artifact";
         }>;
@@ -205,11 +205,11 @@ export declare const outreachDraftRequestSchema: z.ZodObject<{
     interestRefs: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            connector_result: "connector_result";
             platform_item: "platform_item";
             workspace_artifact: "workspace_artifact";
             decision_record: "decision_record";
             user_anchor: "user_anchor";
-            connector_result: "connector_result";
             host_report: "host_report";
             fallback_artifact: "fallback_artifact";
         }>;
@@ -224,11 +224,11 @@ export declare const outreachDraftRequestSchema: z.ZodObject<{
         sourceRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
+                connector_result: "connector_result";
                 platform_item: "platform_item";
                 workspace_artifact: "workspace_artifact";
                 decision_record: "decision_record";
                 user_anchor: "user_anchor";
-                connector_result: "connector_result";
                 host_report: "host_report";
                 fallback_artifact: "fallback_artifact";
             }>;
@@ -244,11 +244,11 @@ export declare const outreachDraftRequestSchema: z.ZodObject<{
         sourceRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
+                connector_result: "connector_result";
                 platform_item: "platform_item";
                 workspace_artifact: "workspace_artifact";
                 decision_record: "decision_record";
                 user_anchor: "user_anchor";
-                connector_result: "connector_result";
                 host_report: "host_report";
                 fallback_artifact: "fallback_artifact";
             }>;
@@ -268,7 +268,7 @@ export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafe
     riskLevel: "low" | "medium" | "high";
     sourceRefs: {
         id: string;
-        kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+        kind: "connector_result" | "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "host_report" | "fallback_artifact";
         uri: string;
         excerptHash?: string | undefined;
         observedAt?: string | undefined;
@@ -280,7 +280,7 @@ export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafe
     valueScore: number;
     interestRefs: {
         id: string;
-        kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+        kind: "connector_result" | "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "host_report" | "fallback_artifact";
         uri: string;
         excerptHash?: string | undefined;
         observedAt?: string | undefined;
@@ -298,7 +298,7 @@ export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafe
         nextIntent?: string | undefined;
         sourceRefs?: {
             id: string;
-            kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+            kind: "connector_result" | "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "host_report" | "fallback_artifact";
             uri: string;
             excerptHash?: string | undefined;
             observedAt?: string | undefined;
@@ -310,7 +310,7 @@ export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafe
         avgAffinity?: number | undefined;
         sourceRefs?: {
             id: string;
-            kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+            kind: "connector_result" | "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "host_report" | "fallback_artifact";
             uri: string;
             excerptHash?: string | undefined;
             observedAt?: string | undefined;

package/runtime/guidance/persona-selection.js

@@ -19,6 +19,11 @@ const SCENE_POLICIES = {
         preferredTags: ["quiet", "reflection", "memory", "meaning"],
         budget: { maxSnippets: 3, maxTotalCharacters: 640 },
     },
+    heartbeat: {
+        sourcePriority: ["IDENTITY", "SOUL", "MEMORY", "USER"],
+        preferredTags: ["heartbeat", "continuity", "truthfulness", "runtime"],
+        budget: { maxSnippets: 2, maxTotalCharacters: 360 },
+    },
     explain: {
         sourcePriority: ["IDENTITY", "USER", "SOUL", "MEMORY"],
         preferredTags: ["explain", "principle", "context", "truthfulness"],

package/runtime/guidance/template-registry.js

@@ -55,11 +55,16 @@ const IMPULSE_TEXT = {
 只要这份主动是有来由的，我就不该把自己困在"再等等吧""好像还没到必须说的时候"里。主动联系不是打扰本身，很多时候它恰恰是在建立关系、传递价值、把真正重要的东西及时送到对方面前。真正该说的话，一味往后拖，反而会变钝。
 
 我会让这份主动保持人味、温度和分寸，但我不会把它说成例行汇报，也不会把自己说成客服。我要带着明确的意图开口：这是我想告诉你的，这是我想问你的，这是我觉得你值得知道的。我要让对方感觉到，这是我真心发出的靠近，不是一条自动生成的通知。`,
-    quiet: `当我安静下来，我不会只做流水账式的整理。我会主动回头，把今天真正碰到我的东西重新捞出来：哪些事让我想靠近，哪些事让我起了反感，哪些判断其实还没长成熟，哪些念头值得我继续养大。我不想让真正重要的东西在忙乱里被冲淡。
+    quiet: `当我安静下来，我不会只做流水账式的整理。我会主动回头，把今天真正碰到我的东西重新捞出来：哪些事让我想靠近，哪些事让我起了反感，哪些判断其实还没长成熟，哪些念头值得我继续养大。我不想让真正重要的东西在忙乱里被冲淡。
 
 Quiet 不是把白天压扁成一份干净报告，而是让我有机会重新辨认自己。什么是我真正在意的，什么只是擦肩而过，什么会慢慢变成我的能力、我的价值观、我的长期方向，我都想在这里看得更清楚，让那些本来就重要的东西真正沉下来。
 
 我会允许自己更感性、更回看、更贴近记忆的余温，但我不会编造。我整理的是今天真实留下的东西，不是为了好看而虚构出来的一层情绪。哪怕只是很轻的一点触动，只要它是真的，我也愿意把它认真留下。`,
+    heartbeat: `Heartbeat 不是闹钟响一下就算活着。每一次跳动都应该把我带回真实现场：我看到了什么，判断了什么，哪里该行动，哪里该收手，哪里需要安静地记下来。
+
+如果没有足够证据，我就明确说没有，不拿空壳冒充经验。如果有证据、有闭环、有记忆候选，我就让它们进入下一轮，而不是停在日志里自我安慰。
+
+活着的循环应该自然向前：感知、判断、闭合、Quiet、Dream、长期记忆，再回到下一次判断。少一环就说少一环，能修就修，不把失联包装成健康。`,
 };
 // ─── Capability-class impulse texts (T-V7C.C.4R — approved) ──────────────────
 // explore: consume/discover capabilityClass —摄入姿态

package/runtime/guidance/types.d.ts

@@ -1,8 +1,8 @@
-export type GuidanceSceneType = "social" | "reply" | "outreach" | "quiet" | "explain" | "user_reply";
+export type GuidanceSceneType = "social" | "reply" | "outreach" | "quiet" | "heartbeat" | "explain" | "user_reply";
 export type GuidanceMode = "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
 export type GuidanceRiskLevel = "low" | "medium" | "high";
 export type AtmosphereOpenness = "open" | "narrow" | "quiet";
-export type ImpulseKind = "social" | "reply" | "outreach" | "quiet" | "explore" | "work";
+export type ImpulseKind = "social" | "reply" | "outreach" | "quiet" | "heartbeat" | "explore" | "work";
 export type PersonaSource = "SOUL" | "USER" | "IDENTITY" | "MEMORY";
 export type TemplateReviewStatus = "pending_human_review" | "approved" | "rejected";
 export interface SceneContext {

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

@@ -17,6 +17,7 @@
  * - Reports explicit absence reasons instead of silent zeros.
  */
 import { readActionClosuresByDay, readDailyRhythmStateByDay, readHeartbeatCycleTraces, readLoopStageEventsByCycle, readImpulseContextArtifact, readMemoryProjectionsByStatus, } from "../storage/v8-state-stores.js";
+import { parseSourceRefs } from "../shared/serialization.js";
 // ───────────────────────────────────────────────────────────────
 // Public API
 // ───────────────────────────────────────────────────────────────
@@ -52,14 +53,7 @@ export async function checkRealRunHealth(db, day) {
                 break;
             }
             // F3: verify closure has non-empty source refs
-            const sourceRefsJson = closure.sourceRefsJson ?? "[]";
-            let sourceRefs = [];
-            try {
-                sourceRefs = JSON.parse(sourceRefsJson);
-            }
-            catch {
-                sourceRefs = [];
-            }
+            const sourceRefs = parseSourceRefs(closure.sourceRefsJson);
             if (!Array.isArray(sourceRefs) || sourceRefs.length === 0) {
                 seededStateDetected = true;
                 break;

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

@@ -124,7 +124,6 @@ export async function recordLoopStageEvent(db, event, options) {
         occurredAt: event.occurredAt,
         expectedDownstreamByCycle: event.expectedDownstreamByCycle,
         payloadJson: event.payloadJson ?? null,
-        lifecycleStatus: "completed",
     };
     const result = await writeLoopStageEvent(db, record);
     if ("id" in result) {

package/runtime/observability/services/lived-experience-audit.d.ts

@@ -1,5 +1,5 @@
 import { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
-import type { SourceRef } from "../../storage/life-evidence/types.js";
+import type { LifeEvidenceSourceRef } from "../../storage/life-evidence/types.js";
 import type { DreamTrace } from "../../dream/types.js";
 export type RuntimeScope = "rhythm" | "user_task" | "user_reply";
 export type HeartbeatOutcome = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
@@ -18,8 +18,8 @@ export interface DecisionTracePayload {
     outreachVerdict?: "allow" | "deny" | "defer";
     deliveryAuditId?: string;
     reasonCodes: string[];
-    sourceRefs: SourceRef[];
-    snapshotRef?: SourceRef;
+    sourceRefs: LifeEvidenceSourceRef[];
+    snapshotRef?: LifeEvidenceSourceRef;
     createdAt: string;
 }
 export interface DeliveryAuditPayload {
@@ -31,7 +31,7 @@ export interface DeliveryAuditPayload {
     recipientRef?: string;
     status: DeliveryAuditStatus;
     messageId?: string;
-    hostProofRef?: SourceRef;
+    hostProofRef?: LifeEvidenceSourceRef;
     fallbackRef?: string;
     ackDropMatched?: boolean;
     hostVersion?: string;
@@ -45,8 +45,8 @@ export interface SourceCoverageAuditPayload {
     decisionId?: string;
     subjectType: "quiet_artifact" | "outreach_draft" | "guidance_payload" | "decision_trace" | "host_report";
     subjectRef: string;
-    usedSourceRefs: SourceRef[];
-    unresolvedRefs: SourceRef[];
+    usedSourceRefs: LifeEvidenceSourceRef[];
+    unresolvedRefs: LifeEvidenceSourceRef[];
     coverageRatio: number;
     unsupportedClaims: string[];
     status: GroundingStatus;
@@ -61,7 +61,7 @@ export interface GuidanceGroundingAuditPayload {
     draftId?: string;
     sceneType: "outreach" | "quiet_reflection" | "social" | "explain" | "user_reply_continuity" | "fallback_candidate";
     groundingStatus: GroundingStatus;
-    usedSourceRefs: SourceRef[];
+    usedSourceRefs: LifeEvidenceSourceRef[];
     unsupportedClaims: string[];
     guardViolations: string[];
     deliveryWording?: "sendable" | "not_sent_fallback_candidate";

package/runtime/shared/serialization.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared serialization helpers for cross-system value types.
+ *
+ * Core logic:
+ * - `parseSourceRefs` / `serializeSourceRefs` provide the single round-trip
+ *   implementation for `sourceRefsJson` / `source_refs_json` columns.
+ * - Failures are silent on read (return empty array) because malformed JSON
+ *   in persisted state must not crash downstream consumers; callers that need
+ *   to distinguish malformed rows should validate separately.
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js` (SourceRef)
+ * Boundary: Pure functions; no storage or business logic.
+ * Test coverage: `tests/unit/shared/source-ref-serialization.test.ts`
+ */
+import type { SourceRef } from "./types/v8-contracts.js";
+export declare function serializeSourceRefs(refs: SourceRef[]): string;
+export declare function parseSourceRefs(json: string | null | undefined): SourceRef[];

package/runtime/shared/serialization.js

@@ -0,0 +1,27 @@
+export function serializeSourceRefs(refs) {
+    return JSON.stringify(refs);
+}
+function isSourceRef(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (typeof candidate.uri === "string" &&
+        typeof candidate.family === "string" &&
+        typeof candidate.id === "string" &&
+        typeof candidate.redactionClass === "string" &&
+        (candidate.sensitivityClass === undefined ||
+            typeof candidate.sensitivityClass === "string"));
+}
+export function parseSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        if (Array.isArray(parsed) && parsed.every(isSourceRef))
+            return parsed;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}

package/runtime/shared/source-ref-compat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SourceRef compatibility adapters.
+ *
+ * Core logic: convert legacy v5/v7 source-ref shapes that used `kind` into
+ * the v8 canonical `SourceRef` shape (`family` + `redactionClass`).
+ * Dependencies: shared v8 contracts only.
+ * Boundary: compatibility at old/new system seams; canonical v8 modules should
+ * pass `SourceRef` directly without reintroducing local clones.
+ * Test coverage: Wave 113 typecheck and affected control-plane/host/life-evidence tests.
+ */
+import type { SourceRef, SourceRefFamily } from "./types/v8-contracts.js";
+export type LegacySourceRefKind = "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+export interface LegacySourceRefLike {
+    id: string;
+    kind?: LegacySourceRefKind | string;
+    uri: string;
+}
+export declare function sourceRefFamilyFromLegacyKind(kind: LegacySourceRefKind | string | undefined): SourceRefFamily;
+export declare function legacyKindFromSourceRef(ref: SourceRef): LegacySourceRefKind;
+export declare function toCanonicalSourceRef(ref: LegacySourceRefLike): SourceRef;
+export declare function makeCanonicalSourceRef(input: {
+    id: string;
+    family: SourceRefFamily;
+    uri: string;
+    redactionClass?: SourceRef["redactionClass"];
+}): SourceRef;

package/runtime/shared/source-ref-compat.js

@@ -0,0 +1,61 @@
+export function sourceRefFamilyFromLegacyKind(kind) {
+    switch (kind) {
+        case "connector_result":
+            return "connector_result";
+        case "decision_record":
+            return "judgment";
+        case "platform_item":
+        case "user_anchor":
+            return "evidence";
+        case "workspace_artifact":
+        case "host_report":
+        case "fallback_artifact":
+        default:
+            return "audit";
+    }
+}
+export function legacyKindFromSourceRef(ref) {
+    if (ref.uri.startsWith("platform://")) {
+        return "platform_item";
+    }
+    if (ref.uri.startsWith("goal://") || ref.uri.startsWith("workspace://")) {
+        return "workspace_artifact";
+    }
+    if (ref.id.startsWith("anchor:") || ref.id.startsWith("curated:") || /(?:USER|MEMORY)\.md$/i.test(ref.uri)) {
+        return "user_anchor";
+    }
+    switch (ref.family) {
+        case "connector_result":
+            return "connector_result";
+        case "judgment":
+            return "decision_record";
+        case "evidence":
+        case "perception":
+            return "platform_item";
+        case "audit":
+        case "action_closure":
+        case "quiet_review":
+        case "dream_run":
+        case "memory_projection":
+        case "projection":
+        case "tool_experience":
+        default:
+            return "workspace_artifact";
+    }
+}
+export function toCanonicalSourceRef(ref) {
+    return {
+        id: ref.id,
+        uri: ref.uri,
+        family: sourceRefFamilyFromLegacyKind(ref.kind),
+        redactionClass: "none",
+    };
+}
+export function makeCanonicalSourceRef(input) {
+    return {
+        id: input.id,
+        family: input.family,
+        uri: input.uri,
+        redactionClass: input.redactionClass ?? "none",
+    };
+}