@haaaiawd/second-nature 0.2.9 → 0.2.13

package/runtime/core/second-nature/action/policy-bound-dispatch.js

@@ -20,6 +20,8 @@
  *
  * Test coverage: tests/unit/action/policy-bound-dispatch.test.ts
  */
+import { serializeSourceRefs } from "../../../shared/serialization.js";
+import { classifyDegradedStatus } from "../../../shared/degraded-status-classifier.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -60,7 +62,8 @@ export function dispatchAllowedAction(proposal, decision, options) {
                 actionKind: target,
                 draftType,
                 policyProof: { decisionId: decision.id, decision: decision.decision },
-                sourceRefs: JSON.stringify(decision.proofRefs),
+                sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                proofRefs: serializeSourceRefs(decision.proofRefs),
             },
         };
     }
@@ -75,7 +78,8 @@ export function dispatchAllowedAction(proposal, decision, options) {
                     capabilityId: proposal.targetCapabilityId ?? "run_connector",
                     idempotencyKey: proposal.idempotencyKey,
                     policyProof: { decisionId: decision.id, decision: decision.decision },
-                    sourceRefs: JSON.stringify(proposal.sourceRefs),
+                    sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                    proofRefs: serializeSourceRefs(decision.proofRefs),
                 },
             };
         }
@@ -91,7 +95,8 @@ export function dispatchAllowedAction(proposal, decision, options) {
                     actionKind: proposal.actionKind,
                     draftType,
                     policyProof: { decisionId: decision.id, decision: decision.decision },
-                    sourceRefs: JSON.stringify(proposal.sourceRefs),
+                    sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                    proofRefs: serializeSourceRefs(decision.proofRefs),
                 },
             };
         }
@@ -101,10 +106,10 @@ export function dispatchAllowedAction(proposal, decision, options) {
     return {
         type: "degraded",
         degraded: {
-            status: "degraded",
+            status: classifyDegradedStatus("closure_failed"),
             reason: "closure_failed",
             ownerStage: "execution",
-            sourceRefs: decision.proofRefs,
+            sourceRefs: proposal.sourceRefs,
             operatorNextAction: "Unexpected policy decision shape",
             retryable: false,
         },

package/runtime/core/second-nature/control-plane/accepted-projection-loader.js

@@ -20,6 +20,7 @@
  * Test coverage: tests/unit/control-plane/accepted-projection-loader.test.ts
  */
 import { readMemoryProjectionsByStatus, } from "../../../storage/v8-state-stores.js";
+import { parseSourceRefs } from "../../../shared/serialization.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -33,17 +34,6 @@ function parsePayloadJson(json) {
         return {};
     }
 }
-function parseSourceRefs(json) {
-    if (!json)
-        return [];
-    try {
-        const parsed = JSON.parse(json);
-        return Array.isArray(parsed) ? parsed : [];
-    }
-    catch {
-        return [];
-    }
-}
 // ───────────────────────────────────────────────────────────────
 // Public API
 // ───────────────────────────────────────────────────────────────

package/runtime/core/second-nature/control-plane/cycle-finalizer.d.ts

@@ -0,0 +1,82 @@
+/**
+ * CycleFinalizer — v8 exactly-one closure invariant (T-AC.R.2, T-AC.R.3)
+ *
+ * Core logic: provide a single boundary that records exactly one
+ * ActionClosureRecord or no-action closure per heartbeat cycle.
+ * Enforces idempotency key = cycleId, write order (closure row first),
+ * and restart reconcile for orphaned closure/event rows.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §6.1a`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §3.4`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/action-closure-recorder.js`
+ * - `src/storage/v8-state-stores.js`
+ *
+ * Boundary:
+ * - One cycle → one closure row.
+ * - Duplicate terminal closure for same cycleId → `unsafe` idempotency conflict.
+ * - On partial failure, returns degraded diagnostic; caller records stage event.
+ * - Reconcile detects orphaned closure (event missing) or orphaned event (closure missing).
+ *
+ * Test coverage: tests/unit/control-plane/cycle-finalizer.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { DegradedOperationResult, V8ReasonCode, SourceRef } from "../../../shared/types/v8-contracts.js";
+export interface CycleFinalizerResult {
+    closureRef?: SourceRef;
+    noActionReason?: V8ReasonCode;
+    degraded?: DegradedOperationResult;
+}
+export type ClosureKind = {
+    kind: "no_action";
+    reason: V8ReasonCode;
+} | {
+    kind: "policy";
+    closureStatus: "completed" | "denied" | "deferred" | "downgraded";
+    reason: V8ReasonCode;
+    proposalId: string;
+    decisionId: string;
+    platformId?: string;
+    capabilityId?: string;
+    downgradedActionKind?: string;
+} | {
+    kind: "execution";
+    closureStatus: "completed" | "failed";
+    reason: V8ReasonCode;
+    proposalId: string;
+    decisionId: string;
+    platformId?: string;
+    capabilityId?: string;
+    executionResultRef?: string;
+    outputSummary?: string;
+};
+export declare function finalizeCycle(db: StateDatabase, cycleId: string, closure: ClosureKind, options?: {
+    now?: string;
+}): Promise<CycleFinalizerResult>;
+export interface ReconcileResult {
+    /** Closure row exists but no closure stage event — event should be replayed. */
+    orphanedClosure?: {
+        closureId: string;
+        cycleId: string;
+    };
+    /** Stage event exists but no closure row — closure is missing, do not fabricate. */
+    orphanedEvent?: {
+        cycleId: string;
+        stage: string;
+    };
+    /** No orphan detected — cycle is consistent. */
+    consistent: boolean;
+    degraded?: DegradedOperationResult;
+}
+/**
+ * Reconcile a cycle's closure and stage event rows.
+ * Called at cycle start or by `loop_status` to detect partial-failure leftovers.
+ *
+ * Per design §6.1a:
+ * - closure row written, event missing → replay event with traceRefs
+ * - event written, closure row missing → report closure_unavailable / unsafe
+ */
+export declare function reconcileCycleClosure(db: StateDatabase, cycleId: string): Promise<ReconcileResult>;

package/runtime/core/second-nature/control-plane/cycle-finalizer.js

@@ -0,0 +1,187 @@
+/**
+ * CycleFinalizer — v8 exactly-one closure invariant (T-AC.R.2, T-AC.R.3)
+ *
+ * Core logic: provide a single boundary that records exactly one
+ * ActionClosureRecord or no-action closure per heartbeat cycle.
+ * Enforces idempotency key = cycleId, write order (closure row first),
+ * and restart reconcile for orphaned closure/event rows.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §6.1a`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §3.4`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/action-closure-recorder.js`
+ * - `src/storage/v8-state-stores.js`
+ *
+ * Boundary:
+ * - One cycle → one closure row.
+ * - Duplicate terminal closure for same cycleId → `unsafe` idempotency conflict.
+ * - On partial failure, returns degraded diagnostic; caller records stage event.
+ * - Reconcile detects orphaned closure (event missing) or orphaned event (closure missing).
+ *
+ * Test coverage: tests/unit/control-plane/cycle-finalizer.test.ts
+ */
+import { recordNoActionClosure, recordPolicyOutcomeClosure, recordExecutionClosure, } from "../action/action-closure-recorder.js";
+import { readActionClosuresByCycle, readLoopStageEventsByCycle, } from "../../../storage/v8-state-stores.js";
+import { classifyDegradedStatus } from "../../../shared/degraded-status-classifier.js";
+// Terminal closure statuses — a cycle with any of these is considered finalized.
+const TERMINAL_CLOSURE_STATUSES = new Set([
+    "completed",
+    "no_action",
+    "denied",
+    "deferred",
+    "downgraded",
+    "failed",
+]);
+/**
+ * Check whether a cycle already has a terminal closure row.
+ * This is the idempotency gate for `finalizeCycle`.
+ */
+async function checkExistingTerminalClosure(db, cycleId) {
+    const existing = await readActionClosuresByCycle(db, cycleId);
+    if (existing.degraded)
+        return { hasTerminal: false };
+    const terminal = existing.rows.find((r) => TERMINAL_CLOSURE_STATUSES.has(r.status));
+    if (terminal)
+        return { hasTerminal: true, existingClosureId: terminal.id };
+    return { hasTerminal: false };
+}
+export async function finalizeCycle(db, cycleId, closure, options) {
+    const now = options?.now ?? new Date().toISOString();
+    // Idempotency gate: check if this cycle already has a terminal closure.
+    // recordNoActionClosure has its own idempotency check, but policy/execution do not.
+    // We check uniformly here to enforce the exactly-one invariant.
+    if (closure.kind !== "no_action") {
+        const existing = await checkExistingTerminalClosure(db, cycleId);
+        if (existing.hasTerminal) {
+            return {
+                degraded: {
+                    status: "unsafe",
+                    reason: "closure_idempotency_conflict",
+                    ownerStage: "closure",
+                    sourceRefs: [],
+                    operatorNextAction: `Cycle ${cycleId} already has terminal closure ${existing.existingClosureId}; duplicate finalize blocked`,
+                    retryable: false,
+                },
+            };
+        }
+    }
+    switch (closure.kind) {
+        case "no_action": {
+            const result = await recordNoActionClosure(db, cycleId, closure.reason, { now });
+            if ("closureId" in result) {
+                return {
+                    closureRef: {
+                        uri: `sn://closure/${result.closureId}`,
+                        family: "action_closure",
+                        id: result.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    },
+                    noActionReason: closure.reason,
+                };
+            }
+            return {
+                noActionReason: closure.reason,
+                degraded: result,
+            };
+        }
+        case "policy": {
+            const result = await recordPolicyOutcomeClosure(db, cycleId, closure.closureStatus, closure.reason, {
+                proposalId: closure.proposalId,
+                decisionId: closure.decisionId,
+                platformId: closure.platformId,
+                capabilityId: closure.capabilityId,
+                downgradedActionKind: closure.downgradedActionKind,
+            }, { now });
+            if ("closureId" in result) {
+                return {
+                    closureRef: {
+                        uri: `sn://closure/${result.closureId}`,
+                        family: "action_closure",
+                        id: result.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    },
+                };
+            }
+            return { degraded: result };
+        }
+        case "execution": {
+            const result = await recordExecutionClosure(db, cycleId, closure.closureStatus, closure.reason, {
+                proposalId: closure.proposalId,
+                decisionId: closure.decisionId,
+                platformId: closure.platformId,
+                capabilityId: closure.capabilityId,
+                executionResultRef: closure.executionResultRef,
+                outputSummary: closure.outputSummary,
+            }, { now });
+            if ("closureId" in result) {
+                return {
+                    closureRef: {
+                        uri: `sn://closure/${result.closureId}`,
+                        family: "action_closure",
+                        id: result.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    },
+                };
+            }
+            return { degraded: result };
+        }
+        default: {
+            const exhaustive = closure;
+            return {
+                degraded: {
+                    status: classifyDegradedStatus("closure_failed"),
+                    reason: "closure_failed",
+                    ownerStage: "closure",
+                    sourceRefs: [],
+                    operatorNextAction: `Unknown closure kind: ${JSON.stringify(exhaustive)}`,
+                    retryable: false,
+                },
+            };
+        }
+    }
+}
+/**
+ * Reconcile a cycle's closure and stage event rows.
+ * Called at cycle start or by `loop_status` to detect partial-failure leftovers.
+ *
+ * Per design §6.1a:
+ * - closure row written, event missing → replay event with traceRefs
+ * - event written, closure row missing → report closure_unavailable / unsafe
+ */
+export async function reconcileCycleClosure(db, cycleId) {
+    const closures = await readActionClosuresByCycle(db, cycleId);
+    if (closures.degraded) {
+        return {
+            consistent: false,
+            degraded: closures.degraded,
+        };
+    }
+    const events = await readLoopStageEventsByCycle(db, cycleId);
+    if (events.degraded) {
+        return {
+            consistent: false,
+            degraded: events.degraded,
+        };
+    }
+    const terminalClosure = closures.rows.find((r) => TERMINAL_CLOSURE_STATUSES.has(r.status));
+    const closureEvent = events.rows.find((r) => r.stage === "closure" || r.stage === "action_closure");
+    if (terminalClosure && !closureEvent) {
+        return {
+            orphanedClosure: { closureId: terminalClosure.id, cycleId },
+            consistent: false,
+        };
+    }
+    if (!terminalClosure && closureEvent) {
+        return {
+            orphanedEvent: { cycleId, stage: closureEvent.stage },
+            consistent: false,
+        };
+    }
+    return { consistent: true };
+}

package/runtime/core/second-nature/control-plane/heartbeat-orchestrator.d.ts

@@ -35,6 +35,7 @@ export interface HeartbeatOrchestrationResult {
     closureRef?: SourceRef;
     noActionReason?: V8ReasonCode;
     degraded?: DegradedOperationResult;
+    rhythmDegraded?: DegradedOperationResult;
     rhythmState?: DailyRhythmState;
 }
 export declare function runHeartbeatCycle(db: StateDatabase, request: HeartbeatOrchestrationRequest): Promise<HeartbeatOrchestrationResult | DegradedOperationResult>;

package/runtime/core/second-nature/control-plane/heartbeat-orchestrator.js

@@ -31,6 +31,7 @@ import { evaluateActionPolicy } from "../action/autonomy-policy-evaluator.js";
 import { dispatchAllowedAction } from "../action/policy-bound-dispatch.js";
 import { recordNoActionClosure, recordRememberClosure, recordPolicyOutcomeClosure, recordExecutionClosure, } from "../action/action-closure-recorder.js";
 import { checkDailyRhythm } from "../quiet-dream/daily-rhythm-scheduler.js";
+import { classifyDegradedStatus } from "../../../shared/degraded-status-classifier.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -84,7 +85,7 @@ async function advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef,
     catch (rhythmErr) {
         const errMsg = rhythmErr instanceof Error ? rhythmErr.message : String(rhythmErr);
         const degraded = {
-            status: "degraded",
+            status: classifyDegradedStatus("state_unreadable"),
             reason: "state_unreadable",
             ownerStage: "quiet",
             sourceRefs: [cycleRef],
@@ -130,7 +131,7 @@ export async function runHeartbeatCycle(db, request) {
     });
     if ("reason" in traceResult) {
         return {
-            status: "degraded",
+            status: classifyDegradedStatus("state_unreadable"),
             reason: "state_unreadable",
             ownerStage: "ingestion",
             sourceRefs: [cycleRef],
@@ -150,7 +151,7 @@ export async function runHeartbeatCycle(db, request) {
     });
     // ── Perception stage ──
     const perceptionResult = await buildPerceptionCards(db, { cycleId, now });
-    const perceptionDegraded = "status" in perceptionResult && perceptionResult.status === "degraded"
+    const perceptionDegraded = "ownerStage" in perceptionResult
         ? perceptionResult
         : null;
     await recordLoopStageEvent(db, {
@@ -191,7 +192,7 @@ export async function runHeartbeatCycle(db, request) {
             reason: degradedReason,
             sourceRefs: degradedClosureRef ? [degradedClosureRef, cycleRef] : [cycleRef],
         });
-        const { rhythmState } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
+        const { rhythmState, rhythmDegraded } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
         return {
             cycleId,
             cycleSequence,
@@ -199,14 +200,15 @@ export async function runHeartbeatCycle(db, request) {
             noActionReason: degradedReason,
             degraded: perceptionDegraded
                 ? {
-                    status: "degraded",
-                    reason: perceptionResult.reason ?? "state_unreadable",
+                    status: classifyDegradedStatus(degradedReason),
+                    reason: degradedReason,
                     ownerStage: "perception",
                     sourceRefs: [cycleRef],
                     operatorNextAction: "Retry heartbeat after perception recovery",
                     retryable: true,
                 }
-                : undefined,
+                : rhythmDegraded,
+            rhythmDegraded,
             rhythmState,
         };
     }
@@ -245,12 +247,14 @@ export async function runHeartbeatCycle(db, request) {
             reason: "evidence_batch_empty",
             sourceRefs: emptyClosureRef ? [emptyClosureRef, cycleRef] : [cycleRef],
         });
-        const { rhythmState } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
+        const { rhythmState, rhythmDegraded } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
         return {
             cycleId,
             cycleSequence,
             closureRef: emptyClosureRef,
             noActionReason: "evidence_batch_empty",
+            degraded: rhythmDegraded,
+            rhythmDegraded,
             rhythmState,
         };
     }
@@ -324,7 +328,7 @@ export async function runHeartbeatCycle(db, request) {
         else {
             // Build proposal for the actionable verdict
             const proposalResult = await buildActionProposal(db, actionableVerdict.id, { now });
-            if ("status" in proposalResult && proposalResult.status === "degraded") {
+            if ("operatorNextAction" in proposalResult) {
                 // Proposal build failed — still need a closure
                 closureDegraded = proposalResult;
                 const closureResult = await recordNoActionClosure(db, cycleId, closureDegraded.reason, { now });
@@ -365,7 +369,7 @@ export async function runHeartbeatCycle(db, request) {
             }
             else if (proposalResult.status === "remember_for_review") {
                 const remember = proposalResult;
-                const closureResult = await recordRememberClosure(db, cycleId, remember.memoryReviewCandidate, { now });
+                const closureResult = await recordRememberClosure(db, cycleId, remember.memoryReviewCandidate, { now, platformId: "heartbeat" });
                 if ("closureId" in closureResult) {
                     closureRef = {
                         uri: `sn://closure/${closureResult.closureId}`,
@@ -395,7 +399,8 @@ export async function runHeartbeatCycle(db, request) {
                     status: "completed",
                     occurredAt: new Date().toISOString(),
                     reason: decision.decisionReason,
-                    sourceRefs: decision.proofRefs,
+                    sourceRefs: proposal.sourceRefs,
+                    proofRefs: decision.proofRefs,
                 });
                 // Record execution stage started
                 await recordLoopStageEvent(db, {
@@ -405,7 +410,8 @@ export async function runHeartbeatCycle(db, request) {
                     stage: "execution",
                     status: "started",
                     occurredAt: new Date().toISOString(),
-                    sourceRefs: decision.proofRefs,
+                    sourceRefs: proposal.sourceRefs,
+                    proofRefs: decision.proofRefs,
                 });
                 // Dispatch — no real external write in T-CP.R.2
                 const dispatchResult = dispatchAllowedAction(proposal, decision, { guidanceAvailable: false });
@@ -509,7 +515,8 @@ export async function runHeartbeatCycle(db, request) {
                     status: closureDegraded ? "failed" : "completed",
                     occurredAt: new Date().toISOString(),
                     reason: closureDegraded?.reason,
-                    sourceRefs: decision.proofRefs,
+                    sourceRefs: proposal.sourceRefs,
+                    proofRefs: decision.proofRefs,
                 });
             }
         }
@@ -540,13 +547,14 @@ export async function runHeartbeatCycle(db, request) {
         noActionReason = "proposal_no_action";
     }
     // T-CP.R.3: Advance daily rhythm after closure/no-action
-    const { rhythmState } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
+    const { rhythmState, rhythmDegraded } = await advanceAndRecordDailyRhythm(db, cycleId, cycleSequence, cycleRef, now);
     return {
         cycleId,
         cycleSequence,
         closureRef,
         noActionReason,
-        degraded: closureDegraded,
+        degraded: closureDegraded ?? rhythmDegraded,
+        rhythmDegraded,
         rhythmState,
     };
 }

package/runtime/core/second-nature/control-plane/real-runtime-spine.d.ts

@@ -31,5 +31,7 @@ export interface RealRuntimeSpineResult {
     noActionReason?: V8ReasonCode;
     degraded?: DegradedOperationResult;
     rhythmState?: DailyRhythmState;
+    rhythmDegraded?: DegradedOperationResult;
+    impulseContextArtifactId?: string;
 }
 export declare function runRealRuntimeHeartbeatCycle(options: RealRuntimeSpineOptions): Promise<RealRuntimeSpineResult | DegradedOperationResult>;

package/runtime/core/second-nature/control-plane/real-runtime-spine.js

@@ -27,7 +27,7 @@ export async function runRealRuntimeHeartbeatCycle(options) {
     };
     const result = await runHeartbeatCycle(options.state, request);
     // Pass through degraded results directly
-    if ("status" in result && result.status === "degraded") {
+    if ("status" in result) {
         return result;
     }
     const orchestrationResult = result;
@@ -38,5 +38,6 @@ export async function runRealRuntimeHeartbeatCycle(options) {
         noActionReason: orchestrationResult.noActionReason,
         degraded: orchestrationResult.degraded,
         rhythmState: orchestrationResult.rhythmState,
+        rhythmDegraded: orchestrationResult.rhythmDegraded,
     };
 }

package/runtime/core/second-nature/guidance/guidance-proposal-consumer.d.ts

@@ -29,10 +29,11 @@ export interface GuidanceOutput {
     mode: "draft" | "notify";
     textRef: SourceRef;
     sourceRefs: SourceRef[];
+    proofRefs: SourceRef[];
     deliveryClaim: "not_delivered";
     decisionId: string;
     actionKind: PlatformNeutralActionKind;
-    ownerVisible: boolean;
+    ownerVisible: true;
 }
 export type GuidanceValidationResult = {
     ok: true;

package/runtime/core/second-nature/guidance/guidance-proposal-consumer.js

@@ -68,7 +68,8 @@ function buildGuidanceOutput(proposal, decision) {
         id: `guidance_${decision.id}_${Date.now()}`,
         mode,
         textRef,
-        sourceRefs: [...proposal.sourceRefs, ...decision.proofRefs],
+        sourceRefs: proposal.sourceRefs,
+        proofRefs: decision.proofRefs,
         deliveryClaim: "not_delivered",
         decisionId: decision.id,
         actionKind,
@@ -87,7 +88,8 @@ export function consumeGuidanceProposal(proposal, decision) {
                 status: "blocked",
                 reason: "policy_denied_high_risk",
                 ownerStage: "execution",
-                sourceRefs: decision.proofRefs,
+                sourceRefs: proposal.sourceRefs,
+                proofRefs: decision.proofRefs,
                 operatorNextAction: "Review policy decision before requesting guidance",
                 retryable: false,
             },

package/runtime/core/second-nature/heartbeat/heartbeat-loop.js

@@ -12,6 +12,7 @@ import { mapLifeEvidence } from "../../../connectors/base/map-life-evidence.js";
 import { appendLifeEvidence } from "../../../storage/life-evidence/append-life-evidence.js";
 import { normalizeConnectorEvidence } from "../../../connectors/evidence-normalizer.js";
 import { recordConnectorAttemptAudit } from "../../../observability/services/audit-closure-recorders.js";
+import { makeCanonicalSourceRef } from "../../../shared/source-ref-compat.js";
 /**
  * Resolves the heartbeat outcome for a guard-allowed intent (outreach dispatch, quiet orchestration, or default).
  * Exported for unit tests (CR-M1 wiring).
@@ -302,11 +303,11 @@ export async function ingestRhythmSignal(signal, deps) {
                         effectClass: "connector_action",
                         capabilityIntent: idleResult.candidate.capabilityId,
                         sourceRefs: [
-                            {
+                            makeCanonicalSourceRef({
                                 id: "idle_curiosity",
-                                kind: "workspace_artifact",
+                                family: "audit",
                                 uri: `idle://${idleResult.candidate.platformId}`,
-                            },
+                            }),
                         ],
                         idempotencyKey: `idle:${idleResult.candidate.platformId}:${idleResult.candidate.capabilityId}`,
                         goalInfluenceRefs: [],

package/runtime/core/second-nature/heartbeat/runtime-snapshot.d.ts

@@ -1,13 +1,14 @@
 /**
  * HeartbeatRuntimeSnapshot assembly for candidate planner + hard guards (T2.1.3, T2.2.1).
  */
-import type { ContinuitySnapshot, ControlPlaneSourceRef } from "../types.js";
+import type { ContinuitySnapshot } from "../types.js";
+import type { SourceRef } from "../../../shared/types/v8-contracts.js";
 import type { RhythmPolicy } from "../rhythm/rhythm-policy.js";
 import { type PlannerRhythmWindowSlice } from "../rhythm/planner-rhythm-window.js";
 import type { SnapshotInputs } from "./snapshot-builder.js";
 import type { AffordanceMap } from "../../../shared/types/v7-entities.js";
 export interface PlannerLifeEvidenceSlice {
-    evidenceRefs: ControlPlaneSourceRef[];
+    evidenceRefs: SourceRef[];
     platformEventCount: number;
     workEventCount: number;
     emptyReason?: "no_sources" | "state_unavailable" | "redacted_only";

package/runtime/core/second-nature/heartbeat/snapshot-builder.d.ts

@@ -6,7 +6,8 @@
  *
  * Per design doc §4.2: SnapshotBuilder prepares inputs for the Rhythm Engine.
  */
-import type { ContinuitySnapshot, ControlPlaneSourceRef, TopLevelMode } from "../types.js";
+import type { ContinuitySnapshot, TopLevelMode } from "../types.js";
+import type { SourceRef } from "../../../shared/types/v8-contracts.js";
 import type { RhythmPolicy } from "../rhythm/rhythm-policy.js";
 import type { DeliveryCapabilitySnapshot } from "../outreach/delivery-target.js";
 import type { UserInterestSnapshot } from "../../../storage/user-interest/types.js";
@@ -30,7 +31,7 @@ export interface SnapshotInputs {
     awaitingUserInput?: boolean;
     riskSuppressed?: boolean;
     /** Evidence refs for source-backed planner/guards (T2.1.3 / T2.2.1). */
-    lifeEvidenceRefs?: ControlPlaneSourceRef[];
+    lifeEvidenceRefs?: SourceRef[];
     platformEventCount?: number;
     workEventCount?: number;
     lifeEvidenceEmptyReason?: "no_sources" | "state_unavailable" | "redacted_only";

package/runtime/core/second-nature/orchestrator/intent-planner.js

@@ -1,10 +1,11 @@
+import { makeCanonicalSourceRef } from "../../../shared/source-ref-compat.js";
 import { isLifeEvidenceSliceEmpty } from "../heartbeat/runtime-snapshot.js";
 import { buildHeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
 import { resolvePlatformForIntent, } from "./platform-capability-router.js";
 import { isGoalRelatedToCandidate } from "./goal-priority.js";
 const MAX_CANDIDATE_INTENTS = 6;
 const OBLIGATION_SOURCE = [
-    { id: "obligation-anchor", kind: "workspace_artifact", uri: "workspace://obligations/pending" },
+    makeCanonicalSourceRef({ id: "obligation-anchor", family: "audit", uri: "workspace://obligations/pending" }),
 ];
 function evidenceRefsForConnector(runtime) {
     if (!isLifeEvidenceSliceEmpty(runtime.lifeEvidence) && runtime.lifeEvidence.evidenceRefs.length > 0) {
@@ -253,8 +254,9 @@ export function planCandidateIntents(runtime, options) {
         if (intent.sourceRefs.length === 0 && related.length > 0) {
             intent.sourceRefs = related.slice(0, 4).map((g) => ({
                 id: g.goalId,
-                kind: "workspace_artifact",
+                family: "audit",
                 uri: `goal://${g.goalId}`,
+                redactionClass: "none",
             }));
         }
     }

package/runtime/core/second-nature/orchestrator/narrative-update.js

@@ -3,9 +3,8 @@ const DEFAULT_NARRATIVE_ID = "default";
 function mapControlPlaneRefToSourceRef(ref) {
     return {
         sourceId: ref.id,
-        kind: ref.kind,
+        kind: ref.family,
         url: ref.uri,
-        snippet: ref.excerptHash,
     };
 }
 /**