@haaaiawd/second-nature 0.2.12 → 0.2.13

package/runtime/connectors/base/normalized-evidence-content.d.ts

@@ -23,6 +23,8 @@
 export declare const NORMALIZED_EVIDENCE_SCHEMA_VERSION = 1;
 export type EvidenceSourceKind = "post" | "comment" | "profile" | "task" | "event" | "game_state" | "notification" | "document" | "unknown";
 export type SummaryProducer = "connector_rules" | "model_assist" | "operator_supplied";
+export type EvidenceContentStatus = "content_present" | "content_missing" | "content_redacted";
+export type EvidenceContentMissingReason = "id_only" | "empty_payload" | "unsupported_shape" | "redacted_private";
 export interface EvidenceActor {
     id?: string;
     displayName?: string;
@@ -36,6 +38,8 @@ export interface NormalizedEvidenceContent {
     externalId?: string;
     title?: string;
     summary: string;
+    contentStatus: EvidenceContentStatus;
+    contentMissingReason?: EvidenceContentMissingReason;
     excerpt?: string;
     canonicalText?: string;
     actor?: EvidenceActor;

package/runtime/connectors/base/normalized-evidence-content.js

@@ -226,8 +226,25 @@ function normalizeSingleItem(item, options) {
     const tags = extractTags(item);
     const entities = extractEntities(item);
     const metrics = extractMetrics(item);
-    const rawText = bodyText ?? title ?? "[no readable content]";
-    const summary = truncate(rawText, 160);
+    const hasReadableContent = isNonEmptyString(bodyText) || isNonEmptyString(title);
+    const hasContentMarkers = isNonEmptyString(url) ||
+        (actor?.displayName && actor.displayName.length > 0) ||
+        tags.length > 0 ||
+        entities.length > 0 ||
+        (metrics && Object.keys(metrics).length > 0);
+    let contentStatus = "content_present";
+    let contentMissingReason;
+    let summary;
+    if (!hasReadableContent && !hasContentMarkers) {
+        contentStatus = "content_missing";
+        contentMissingReason = externalId ? "id_only" : "empty_payload";
+        summary = `Content missing: ${contentMissingReason === "id_only" ? "id-only evidence" : "empty payload"}`;
+    }
+    else {
+        const rawText = bodyText ?? title ?? "[no readable content]";
+        summary = truncate(rawText, 160);
+    }
+    const rawText = bodyText ?? title ?? "";
     const excerpt = rawText.length > summary.length ? truncate(rawText, options.excerptMaxChars ?? 240) : undefined;
     const canonicalText = truncate(rawText, options.canonicalTextMaxChars ?? 2000);
     return {
@@ -238,6 +255,8 @@ function normalizeSingleItem(item, options) {
         externalId,
         title,
         summary,
+        contentStatus,
+        contentMissingReason,
         excerpt,
         canonicalText,
         actor,

package/runtime/connectors/evidence-normalizer.js

@@ -31,6 +31,11 @@ import { extractNormalizedEvidenceItems, computeEvidenceContentHashSync, } from
 function computeLegacyContentHash(content) {
     return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
 }
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars)}…`;
+}
 function buildSourceRef(platformId, capabilityId, itemId, observedAt) {
     return {
         uri: `sn://connector_result/${platformId}/${capabilityId}/${itemId}`,
@@ -191,6 +196,32 @@ async function normalizeLegacyConnectorEvidence(db, result, now) {
         const observedAt = result.observedAt ?? now;
         const sourceRef = buildSourceRef(result.platformId, result.capabilityId, itemId, observedAt);
         const sensitivityHint = mergeSensitivityHint(inferSensitivityHint(item.content), item.sensitivityHint);
+        const trimmedContent = item.content.trim();
+        const looksLikeIdOnly = /^[a-z0-9_-]+$/i.test(trimmedContent) && trimmedContent.length < 64;
+        const contentStatus = looksLikeIdOnly || trimmedContent.length === 0
+            ? "content_missing"
+            : "content_present";
+        const contentMissingReason = contentStatus === "content_missing"
+            ? trimmedContent.length === 0
+                ? "empty_payload"
+                : "id_only"
+            : undefined;
+        const normalized = {
+            schemaVersion: 1,
+            sourceKind: "unknown",
+            platformId: result.platformId,
+            capabilityId: result.capabilityId,
+            externalId: item.id,
+            summary: contentStatus === "content_missing"
+                ? `Content missing: ${contentMissingReason === "id_only" ? "id-only evidence" : "empty payload"}`
+                : truncate(trimmedContent, 160),
+            contentStatus,
+            contentMissingReason,
+            excerpt: contentStatus === "content_present" ? truncate(trimmedContent, 240) : undefined,
+            canonicalText: contentStatus === "content_present" ? truncate(trimmedContent, 2000) : undefined,
+            observedAt,
+            summaryProducer: "connector_rules",
+        };
         const writeResult = await writeEvidenceItem(db, {
             id: `ev_${result.platformId}_${itemId}_${observedAt.replace(/[:.]/g, "")}`,
             createdAt: now,
@@ -201,7 +232,7 @@ async function normalizeLegacyConnectorEvidence(db, result, now) {
             sourceRefs: [sourceRef],
             redactionClass: sensitivityHint === "sensitive" ? "blocked" : "none",
             lifecycleStatus: "pending",
-            payloadJson: item.metadata ? JSON.stringify(item.metadata) : null,
+            payloadJson: JSON.stringify(normalized),
         });
         if ("id" in writeResult) {
             evidenceIds.push(writeResult.id);

package/runtime/core/second-nature/action/action-closure-recorder.d.ts

@@ -38,6 +38,8 @@ export interface ActionClosureRecord {
     nextState: string;
     reason: V8ReasonCode;
     sourceRefs: SourceRef[];
+    proofRefs?: SourceRef[];
+    traceRefs?: SourceRef[];
     memoryReviewCandidate?: MemoryReviewCandidateClosure;
     closedAt: string;
 }

package/runtime/core/second-nature/action/action-closure-recorder.js

@@ -21,6 +21,7 @@
  * Test coverage: tests/unit/action/action-closure-recorder.test.ts
  */
 import { writeActionClosureRecord, readActionClosuresByCycle, } from "../../../storage/v8-state-stores.js";
+import { buildClosureProvenance, cycleTraceRef, closureTraceRef, decisionProofRef, } from "../../../shared/provenance-tier.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -50,7 +51,8 @@ export async function recordNoActionClosure(db, cycleId, noActionReason, options
         status: "no_action",
         reason: noActionReason,
         nextState: "await_next_cycle",
-        sourceRefs: [
+        sourceRefs: [cycleTraceRef(cycleId)],
+        proofRefs: [
             {
                 uri: `sn://closure/no_action/${cycleId}`,
                 family: "action_closure",
@@ -59,8 +61,9 @@ export async function recordNoActionClosure(db, cycleId, noActionReason, options
                 resolveStatus: "resolvable",
             },
         ],
+        traceRefs: [cycleTraceRef(cycleId)],
         redactionClass: "none",
-        payloadJson: JSON.stringify({ dispatchAttempt: 0, inputSummary: "no-action" }),
+        payload: { dispatchAttempt: 0, inputSummary: "no-action" },
     });
     if ("reason" in result) {
         return result;
@@ -73,6 +76,10 @@ export async function recordNoActionClosure(db, cycleId, noActionReason, options
 export async function recordRememberClosure(db, cycleId, memoryReviewCandidate, options) {
     const now = options?.now ?? new Date().toISOString();
     const closureId = `cls_remember_${cycleId}_${now.replace(/[:.]/g, "")}`;
+    const provenance = buildClosureProvenance({
+        sourceRefs: memoryReviewCandidate.sourceRefs,
+        traceRefs: [cycleTraceRef(cycleId)],
+    });
     const result = await writeActionClosureRecord(db, {
         id: closureId,
         createdAt: now,
@@ -82,13 +89,15 @@ export async function recordRememberClosure(db, cycleId, memoryReviewCandidate,
         status: "completed",
         reason: "remember_for_review",
         nextState: "pending_daily_review",
-        sourceRefs: memoryReviewCandidate.sourceRefs,
+        sourceRefs: provenance.sourceRefs,
+        proofRefs: provenance.proofRefs,
+        traceRefs: provenance.traceRefs,
         redactionClass: "none",
-        payloadJson: JSON.stringify({
+        payload: {
             memoryReviewCandidate,
             dispatchAttempt: 1,
             inputSummary: `remember_for_review topic=${memoryReviewCandidate.topicKey}`,
-        }),
+        },
     });
     if ("reason" in result) {
         return result;
@@ -101,24 +110,21 @@ export async function recordRememberClosure(db, cycleId, memoryReviewCandidate,
 export async function recordPolicyOutcomeClosure(db, cycleId, closureStatus, reason, params, options) {
     const now = options?.now ?? new Date().toISOString();
     const closureId = `cls_${closureStatus}_${cycleId}_${now.replace(/[:.]/g, "")}`;
-    const sourceRefs = [
-        {
-            uri: `sn://closure/${closureStatus}/${cycleId}`,
-            family: "action_closure",
-            id: cycleId,
-            redactionClass: "none",
-            resolveStatus: "resolvable",
-        },
+    const sourceRefs = params.proposalId
+        ? [
+            {
+                uri: `sn://proposal/${params.proposalId}`,
+                family: "action_closure",
+                id: params.proposalId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ]
+        : [];
+    const proofRefs = [
+        closureTraceRef(closureId),
+        ...(params.decisionId ? [decisionProofRef(params.decisionId)] : []),
     ];
-    if (params.decisionId) {
-        sourceRefs.push({
-            uri: `sn://decision/${params.decisionId}`,
-            family: "action_closure",
-            id: params.decisionId,
-            redactionClass: "none",
-            resolveStatus: "resolvable",
-        });
-    }
     const result = await writeActionClosureRecord(db, {
         id: closureId,
         createdAt: now,
@@ -131,13 +137,15 @@ export async function recordPolicyOutcomeClosure(db, cycleId, closureStatus, rea
         reason,
         nextState: params.nextState ?? "await_next_cycle",
         sourceRefs,
+        proofRefs,
+        traceRefs: [cycleTraceRef(cycleId)],
         redactionClass: "none",
-        payloadJson: JSON.stringify({
+        payload: {
             dispatchAttempt: 1,
             inputSummary: buildInputSummary(params.proposalId, params.decisionId),
             postProcessing: params.postProcessing ?? [],
             downgradedActionKind: params.downgradedActionKind,
-        }),
+        },
     });
     if ("reason" in result) {
         return result;
@@ -150,14 +158,19 @@ export async function recordPolicyOutcomeClosure(db, cycleId, closureStatus, rea
 export async function recordExecutionClosure(db, cycleId, closureStatus, reason, params, options) {
     const now = options?.now ?? new Date().toISOString();
     const closureId = `cls_exec_${closureStatus}_${cycleId}_${now.replace(/[:.]/g, "")}`;
-    const sourceRefs = [
-        {
-            uri: `sn://closure/${closureStatus}/${cycleId}`,
-            family: "action_closure",
-            id: cycleId,
-            redactionClass: "none",
-            resolveStatus: "resolvable",
-        },
+    const sourceRefs = params.executionResultRef
+        ? [
+            {
+                uri: params.executionResultRef,
+                family: "connector_result",
+                id: params.executionResultRef,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ]
+        : [];
+    const proofRefs = [
+        closureTraceRef(closureId),
     ];
     const result = await writeActionClosureRecord(db, {
         id: closureId,
@@ -171,14 +184,16 @@ export async function recordExecutionClosure(db, cycleId, closureStatus, reason,
         reason,
         nextState: params.nextState ?? (closureStatus === "completed" ? "await_next_cycle" : "retryable"),
         sourceRefs,
+        proofRefs,
+        traceRefs: [cycleTraceRef(cycleId)],
         redactionClass: "none",
-        payloadJson: JSON.stringify({
+        payload: {
             dispatchAttempt: 1,
             executionResultRef: params.executionResultRef,
             outputSummary: params.outputSummary,
             inputSummary: buildInputSummary(params.proposalId, params.decisionId),
             retryable: params.retryable ?? closureStatus === "failed",
-        }),
+        },
     });
     if ("reason" in result) {
         return result;

package/runtime/core/second-nature/action/action-proposal-builder.js

@@ -25,6 +25,7 @@
 import { readJudgmentVerdictById, } from "../../../storage/v8-state-stores.js";
 import { parseSourceRefs } from "../../../shared/serialization.js";
 import { ACTION_KIND_REGISTRY } from "../../../shared/types/v8-contracts.js";
+import { classifyDegradedStatus } from "../../../shared/degraded-status-classifier.js";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -70,7 +71,7 @@ export async function buildActionProposal(db, judgmentVerdictId, options) {
     const verdict = readResult.row;
     if (!verdict) {
         return {
-            status: "degraded",
+            status: classifyDegradedStatus("state_unreadable"),
             reason: "state_unreadable",
             ownerStage: "policy",
             sourceRefs: [],
@@ -174,7 +175,7 @@ export async function buildActionProposals(db, judgmentVerdictIds, options) {
         else if ("status" in result && result.status === "remember_for_review") {
             rememberForReviews.push(result);
         }
-        else if ("status" in result && result.status === "degraded") {
+        else if ("operatorNextAction" in result) {
             failed.push({
                 judgmentVerdictId,
                 degraded: result,

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

@@ -33,6 +33,7 @@ export interface ConnectorDispatchRequest {
         decision: string;
     };
     sourceRefs: string;
+    proofRefs: string;
 }
 export interface GuidanceDispatchRequest {
     type: "guidance";
@@ -43,6 +44,7 @@ export interface GuidanceDispatchRequest {
         decision: string;
     };
     sourceRefs: string;
+    proofRefs: string;
 }
 export interface NoDispatchResult {
     type: "none";

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

@@ -21,6 +21,7 @@
  * 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
 // ───────────────────────────────────────────────────────────────
@@ -61,7 +62,8 @@ export function dispatchAllowedAction(proposal, decision, options) {
                 actionKind: target,
                 draftType,
                 policyProof: { decisionId: decision.id, decision: decision.decision },
-                sourceRefs: serializeSourceRefs(decision.proofRefs),
+                sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                proofRefs: serializeSourceRefs(decision.proofRefs),
             },
         };
     }
@@ -77,6 +79,7 @@ export function dispatchAllowedAction(proposal, decision, options) {
                     idempotencyKey: proposal.idempotencyKey,
                     policyProof: { decisionId: decision.id, decision: decision.decision },
                     sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                    proofRefs: serializeSourceRefs(decision.proofRefs),
                 },
             };
         }
@@ -93,6 +96,7 @@ export function dispatchAllowedAction(proposal, decision, options) {
                     draftType,
                     policyProof: { decisionId: decision.id, decision: decision.decision },
                     sourceRefs: serializeSourceRefs(proposal.sourceRefs),
+                    proofRefs: serializeSourceRefs(decision.proofRefs),
                 },
             };
         }
@@ -102,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/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 };
+}