@haaaiawd/second-nature 0.2.2 → 0.2.4

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

@@ -25,6 +25,11 @@ import { writeHeartbeatCycleTrace, readHeartbeatCycleTraces, } from "../../../st
 import { recordLoopStageEvent } from "../../../observability/loop-stage-event-sink.js";
 import { buildPerceptionCards } from "../perception/perception-builder.js";
 import { runAgentJudgments } from "../perception/judgment-engine.js";
+import { loadAcceptedProjections } from "./accepted-projection-loader.js";
+import { buildActionProposal, } from "../action/action-proposal-builder.js";
+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";
 // ───────────────────────────────────────────────────────────────
 // Helpers
 // ───────────────────────────────────────────────────────────────
@@ -45,6 +50,13 @@ export async function runHeartbeatCycle(db, request) {
     const now = request.requestedAt ?? new Date().toISOString();
     const cycleSequence = await nextCycleSequence(db);
     const cycleId = buildCycleId(cycleSequence, now);
+    const cycleRef = {
+        uri: `sn://heartbeat/${cycleId}`,
+        family: "audit",
+        id: cycleId,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
     // Write cycle trace — started
     const traceResult = await writeHeartbeatCycleTrace(db, {
         id: cycleId,
@@ -53,22 +65,14 @@ export async function runHeartbeatCycle(db, request) {
         inputCount: 0,
         outputCount: 0,
         status: "started",
-        sourceRefs: [
-            {
-                uri: `sn://heartbeat/${cycleId}`,
-                family: "audit",
-                id: cycleId,
-                redactionClass: "none",
-                resolveStatus: "resolvable",
-            },
-        ],
+        sourceRefs: [cycleRef],
     });
     if ("reason" in traceResult) {
         return {
             status: "degraded",
             reason: "state_unreadable",
             ownerStage: "ingestion",
-            sourceRefs: [],
+            sourceRefs: [cycleRef],
             operatorNextAction: "Retry heartbeat after DB recovery",
             retryable: true,
         };
@@ -81,7 +85,7 @@ export async function runHeartbeatCycle(db, request) {
         stage: "ingestion",
         status: "started",
         occurredAt: now,
-        sourceRefs: [],
+        sourceRefs: [cycleRef],
     });
     // ── Perception stage ──
     const perceptionResult = await buildPerceptionCards(db, { cycleId, now });
@@ -98,18 +102,45 @@ export async function runHeartbeatCycle(db, request) {
         reason: perceptionDegraded
             ? perceptionResult.reason
             : undefined,
-        sourceRefs: [],
+        sourceRefs: [cycleRef],
     });
     if (perceptionDegraded || !("cards" in perceptionResult)) {
+        // Degraded path must still write a closure for observability
+        const degradedReason = perceptionDegraded
+            ? (perceptionResult.reason ?? "state_unreadable")
+            : "perception_failed";
+        const closureResult = await recordNoActionClosure(db, cycleId, degradedReason, { now });
+        let degradedClosureRef;
+        if ("closureId" in closureResult) {
+            degradedClosureRef = {
+                uri: `sn://closure/${closureResult.closureId}`,
+                family: "action_closure",
+                id: closureResult.closureId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            };
+        }
+        await recordLoopStageEvent(db, {
+            id: `evt_${cycleId}_closure`,
+            cycleId,
+            cycleSequence,
+            stage: "closure",
+            status: "failed",
+            occurredAt: new Date().toISOString(),
+            reason: degradedReason,
+            sourceRefs: degradedClosureRef ? [degradedClosureRef, cycleRef] : [cycleRef],
+        });
         return {
             cycleId,
             cycleSequence,
+            closureRef: degradedClosureRef,
+            noActionReason: degradedReason,
             degraded: perceptionDegraded
                 ? {
                     status: "degraded",
                     reason: perceptionResult.reason ?? "state_unreadable",
                     ownerStage: "perception",
-                    sourceRefs: [],
+                    sourceRefs: [cycleRef],
                     operatorNextAction: "Retry heartbeat after perception recovery",
                     retryable: true,
                 }
@@ -127,16 +158,42 @@ export async function runHeartbeatCycle(db, request) {
             status: "skipped",
             occurredAt: new Date().toISOString(),
             reason: "evidence_batch_empty",
-            sourceRefs: [],
+            sourceRefs: [cycleRef],
+        });
+        // Write no-action closure — every cycle must produce exactly one
+        const closureResult = await recordNoActionClosure(db, cycleId, "evidence_batch_empty", { now });
+        let emptyClosureRef;
+        if ("closureId" in closureResult) {
+            emptyClosureRef = {
+                uri: `sn://closure/${closureResult.closureId}`,
+                family: "action_closure",
+                id: closureResult.closureId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            };
+        }
+        await recordLoopStageEvent(db, {
+            id: `evt_${cycleId}_closure`,
+            cycleId,
+            cycleSequence,
+            stage: "closure",
+            status: "completed",
+            occurredAt: new Date().toISOString(),
+            reason: "evidence_batch_empty",
+            sourceRefs: emptyClosureRef ? [emptyClosureRef, cycleRef] : [cycleRef],
         });
         return {
             cycleId,
             cycleSequence,
+            closureRef: emptyClosureRef,
             noActionReason: "evidence_batch_empty",
         };
     }
+    // ── Context assembly: load accepted projections (T-DQ.R.3) ──
+    const projectionResult = await loadAcceptedProjections(db);
+    const acceptedProjections = projectionResult.ok ? projectionResult.slice.projections : [];
     // ── Judgment stage ──
-    const judgmentResult = await runAgentJudgments(db, cards.map((c) => c.id), { now });
+    const judgmentResult = await runAgentJudgments(db, cards.map((c) => c.id), { now, acceptedProjections });
     const judgmentFailed = judgmentResult.failed.length > 0;
     await recordLoopStageEvent(db, {
         id: `evt_${cycleId}_judgment`,
@@ -145,21 +202,275 @@ export async function runHeartbeatCycle(db, request) {
         stage: "judgment",
         status: judgmentFailed ? "failed" : "completed",
         occurredAt: new Date().toISOString(),
-        sourceRefs: [],
+        sourceRefs: [cycleRef],
     });
-    // Return cycle result
-    return {
+    // ── Action/Closure stage (T-CP.R.2) ──
+    // Every cycle must produce exactly one closure or no-action record.
+    let closureRef;
+    let noActionReason;
+    let closureDegraded;
+    // Record policy stage started
+    await recordLoopStageEvent(db, {
+        id: `evt_${cycleId}_policy`,
         cycleId,
         cycleSequence,
-        closureRef: judgmentResult.succeeded.length > 0
-            ? {
-                uri: `sn://judgment/${cycleId}`,
-                family: "judgment",
-                id: cycleId,
+        stage: "policy",
+        status: "started",
+        occurredAt: new Date().toISOString(),
+        sourceRefs: [cycleRef],
+    });
+    if (judgmentResult.succeeded.length === 0) {
+        // No actionable verdicts → no-action closure
+        const closureResult = await recordNoActionClosure(db, cycleId, "proposal_no_action", { now });
+        if ("closureId" in closureResult) {
+            closureRef = {
+                uri: `sn://closure/${closureResult.closureId}`,
+                family: "action_closure",
+                id: closureResult.closureId,
                 redactionClass: "none",
                 resolveStatus: "resolvable",
+            };
+        }
+        else if ("reason" in closureResult) {
+            closureDegraded = closureResult;
+        }
+        noActionReason = "proposal_no_action";
+    }
+    else {
+        // Find first actionable verdict (non-ignore, non-watch)
+        const actionableVerdict = judgmentResult.succeeded.find((v) => v.actionKind !== "ignore" && v.actionKind !== "watch");
+        if (!actionableVerdict) {
+            // All verdicts are ignore/watch → no-action
+            const closureResult = await recordNoActionClosure(db, cycleId, "proposal_no_action", { now });
+            if ("closureId" in closureResult) {
+                closureRef = {
+                    uri: `sn://closure/${closureResult.closureId}`,
+                    family: "action_closure",
+                    id: closureResult.closureId,
+                    redactionClass: "none",
+                    resolveStatus: "resolvable",
+                };
             }
-            : undefined,
-        noActionReason: judgmentResult.succeeded.length === 0 ? "proposal_no_action" : undefined,
+            else if ("reason" in closureResult) {
+                closureDegraded = closureResult;
+            }
+            noActionReason = "proposal_no_action";
+        }
+        else {
+            // Build proposal for the actionable verdict
+            const proposalResult = await buildActionProposal(db, actionableVerdict.id, { now });
+            if ("status" in proposalResult && proposalResult.status === "degraded") {
+                // Proposal build failed — still need a closure
+                closureDegraded = proposalResult;
+                const closureResult = await recordNoActionClosure(db, cycleId, closureDegraded.reason, { now });
+                if ("closureId" in closureResult) {
+                    closureRef = {
+                        uri: `sn://closure/${closureResult.closureId}`,
+                        family: "action_closure",
+                        id: closureResult.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    };
+                }
+                noActionReason = closureDegraded.reason;
+                await recordLoopStageEvent(db, {
+                    id: `evt_${cycleId}_policy`,
+                    cycleId,
+                    cycleSequence,
+                    stage: "policy",
+                    status: "failed",
+                    occurredAt: new Date().toISOString(),
+                    reason: closureDegraded.reason,
+                    sourceRefs: closureDegraded.sourceRefs.length > 0 ? closureDegraded.sourceRefs : [cycleRef],
+                });
+            }
+            else if (proposalResult.status === "no_action") {
+                const noAction = proposalResult;
+                const closureResult = await recordNoActionClosure(db, cycleId, noAction.reason, { now });
+                if ("closureId" in closureResult) {
+                    closureRef = {
+                        uri: `sn://closure/${closureResult.closureId}`,
+                        family: "action_closure",
+                        id: closureResult.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    };
+                }
+                noActionReason = noAction.reason;
+            }
+            else if (proposalResult.status === "remember_for_review") {
+                const remember = proposalResult;
+                const closureResult = await recordRememberClosure(db, cycleId, remember.memoryReviewCandidate, { now });
+                if ("closureId" in closureResult) {
+                    closureRef = {
+                        uri: `sn://closure/${closureResult.closureId}`,
+                        family: "action_closure",
+                        id: closureResult.closureId,
+                        redactionClass: "none",
+                        resolveStatus: "resolvable",
+                    };
+                }
+                else if ("reason" in closureResult) {
+                    closureDegraded = closureResult;
+                }
+            }
+            else if (proposalResult.status === "proposal") {
+                const { proposal } = proposalResult;
+                // Evaluate policy — conservative defaults: no real platform permission, no auto-allow
+                const decision = evaluateActionPolicy(proposal, {
+                    breakerStatus: "closed",
+                    platformPermissionDeclared: false,
+                    ownerPreferenceAllowAuto: false,
+                }, { now });
+                await recordLoopStageEvent(db, {
+                    id: `evt_${cycleId}_policy`,
+                    cycleId,
+                    cycleSequence,
+                    stage: "policy",
+                    status: "completed",
+                    occurredAt: new Date().toISOString(),
+                    reason: decision.decisionReason,
+                    sourceRefs: decision.proofRefs,
+                });
+                // Record execution stage started
+                await recordLoopStageEvent(db, {
+                    id: `evt_${cycleId}_execution`,
+                    cycleId,
+                    cycleSequence,
+                    stage: "execution",
+                    status: "started",
+                    occurredAt: new Date().toISOString(),
+                    sourceRefs: decision.proofRefs,
+                });
+                // Dispatch — no real external write in T-CP.R.2
+                const dispatchResult = dispatchAllowedAction(proposal, decision, { guidanceAvailable: false });
+                // Record closure based on dispatch outcome
+                if (dispatchResult.type === "none") {
+                    const closureStatus = decision.decision === "deny" ? "denied" : "deferred";
+                    const closureResult = await recordPolicyOutcomeClosure(db, cycleId, closureStatus, decision.decisionReason, {
+                        proposalId: proposal.id,
+                        decisionId: decision.id,
+                        nextState: "await_next_cycle",
+                    }, { now });
+                    if ("closureId" in closureResult) {
+                        closureRef = {
+                            uri: `sn://closure/${closureResult.closureId}`,
+                            family: "action_closure",
+                            id: closureResult.closureId,
+                            redactionClass: "none",
+                            resolveStatus: "resolvable",
+                        };
+                    }
+                    else if ("reason" in closureResult) {
+                        closureDegraded = closureResult;
+                    }
+                }
+                else if (dispatchResult.type === "guidance_unavailable") {
+                    const closureResult = await recordPolicyOutcomeClosure(db, cycleId, "downgraded", "guidance_unavailable", {
+                        proposalId: proposal.id,
+                        decisionId: decision.id,
+                        downgradedActionKind: dispatchResult.downgradedActionKind,
+                        nextState: "await_guidance_recovery",
+                    }, { now });
+                    if ("closureId" in closureResult) {
+                        closureRef = {
+                            uri: `sn://closure/${closureResult.closureId}`,
+                            family: "action_closure",
+                            id: closureResult.closureId,
+                            redactionClass: "none",
+                            resolveStatus: "resolvable",
+                        };
+                    }
+                    else if ("reason" in closureResult) {
+                        closureDegraded = closureResult;
+                    }
+                }
+                else if (dispatchResult.type === "guidance") {
+                    // Guidance draft dispatch — no external write
+                    const closureResult = await recordExecutionClosure(db, cycleId, "completed", "policy_allowed", {
+                        proposalId: proposal.id,
+                        decisionId: decision.id,
+                        outputSummary: "Guidance draft dispatched (simulated)",
+                        nextState: "await_next_cycle",
+                    }, { now });
+                    if ("closureId" in closureResult) {
+                        closureRef = {
+                            uri: `sn://closure/${closureResult.closureId}`,
+                            family: "action_closure",
+                            id: closureResult.closureId,
+                            redactionClass: "none",
+                            resolveStatus: "resolvable",
+                        };
+                    }
+                    else if ("reason" in closureResult) {
+                        closureDegraded = closureResult;
+                    }
+                }
+                else if (dispatchResult.type === "connector") {
+                    // Connector dispatch — simulated, no real platform write (T-CP.R.2)
+                    const closureResult = await recordExecutionClosure(db, cycleId, "completed", "policy_allowed", {
+                        proposalId: proposal.id,
+                        decisionId: decision.id,
+                        outputSummary: "Connector dispatch prepared (simulated — T-CP.R.2)",
+                        nextState: "await_real_execution",
+                    }, { now });
+                    if ("closureId" in closureResult) {
+                        closureRef = {
+                            uri: `sn://closure/${closureResult.closureId}`,
+                            family: "action_closure",
+                            id: closureResult.closureId,
+                            redactionClass: "none",
+                            resolveStatus: "resolvable",
+                        };
+                    }
+                    else if ("reason" in closureResult) {
+                        closureDegraded = closureResult;
+                    }
+                }
+                // Record execution stage completed
+                await recordLoopStageEvent(db, {
+                    id: `evt_${cycleId}_execution`,
+                    cycleId,
+                    cycleSequence,
+                    stage: "execution",
+                    status: closureDegraded ? "failed" : "completed",
+                    occurredAt: new Date().toISOString(),
+                    reason: closureDegraded?.reason,
+                    sourceRefs: decision.proofRefs,
+                });
+            }
+        }
+    }
+    // Record closure stage event
+    await recordLoopStageEvent(db, {
+        id: `evt_${cycleId}_closure`,
+        cycleId,
+        cycleSequence,
+        stage: "closure",
+        status: closureDegraded ? "failed" : "completed",
+        occurredAt: new Date().toISOString(),
+        reason: closureDegraded?.reason ?? noActionReason,
+        sourceRefs: closureRef ? [closureRef, cycleRef] : [cycleRef],
+    });
+    // Final safety net: if somehow nothing was recorded, write a degraded no-action
+    if (!closureRef && !noActionReason && !closureDegraded) {
+        const fallback = await recordNoActionClosure(db, cycleId, "proposal_no_action", { now });
+        if ("closureId" in fallback) {
+            closureRef = {
+                uri: `sn://closure/${fallback.closureId}`,
+                family: "action_closure",
+                id: fallback.closureId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            };
+        }
+        noActionReason = "proposal_no_action";
+    }
+    return {
+        cycleId,
+        cycleSequence,
+        closureRef,
+        noActionReason,
+        degraded: closureDegraded,
     };
 }

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

@@ -0,0 +1,33 @@
+/**
+ * RealRuntimeSpine — Bridge real workspace heartbeat into v8 action-closure spine.
+ *
+ * Core logic: Wrap v8 heartbeat orchestrator for CLI/OpenClaw consumption.
+ * Ensures every real heartbeat cycle writes exactly one closure/no-action
+ * with state-backed persistence and canonical stage events.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §4`
+ *
+ * Boundary:
+ * - Does NOT execute real external writes (T-CP.R.2).
+ * - Does NOT register fake context-engines.
+ * - Delegates all semantic decisions to action-closure-policy-system.
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface RealRuntimeSpineOptions {
+    workspaceRoot: string;
+    state: StateDatabase;
+    requestedAt?: string;
+    trigger?: "scheduled" | "manual" | "host";
+}
+export interface RealRuntimeSpineResult {
+    cycleId: string;
+    cycleSequence: number;
+    closureRef?: SourceRef;
+    noActionReason?: V8ReasonCode;
+    degraded?: DegradedOperationResult;
+}
+export declare function runRealRuntimeHeartbeatCycle(options: RealRuntimeSpineOptions): Promise<RealRuntimeSpineResult | DegradedOperationResult>;

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

@@ -0,0 +1,41 @@
+/**
+ * RealRuntimeSpine — Bridge real workspace heartbeat into v8 action-closure spine.
+ *
+ * Core logic: Wrap v8 heartbeat orchestrator for CLI/OpenClaw consumption.
+ * Ensures every real heartbeat cycle writes exactly one closure/no-action
+ * with state-backed persistence and canonical stage events.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §4`
+ *
+ * Boundary:
+ * - Does NOT execute real external writes (T-CP.R.2).
+ * - Does NOT register fake context-engines.
+ * - Delegates all semantic decisions to action-closure-policy-system.
+ */
+import { runHeartbeatCycle, } from "./heartbeat-orchestrator.js";
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function runRealRuntimeHeartbeatCycle(options) {
+    const request = {
+        workspaceRoot: options.workspaceRoot,
+        requestedAt: options.requestedAt,
+        trigger: options.trigger ?? "scheduled",
+    };
+    const result = await runHeartbeatCycle(options.state, request);
+    // Pass through degraded results directly
+    if ("status" in result && result.status === "degraded") {
+        return result;
+    }
+    const orchestrationResult = result;
+    return {
+        cycleId: orchestrationResult.cycleId,
+        cycleSequence: orchestrationResult.cycleSequence,
+        closureRef: orchestrationResult.closureRef,
+        noActionReason: orchestrationResult.noActionReason,
+        degraded: orchestrationResult.degraded,
+    };
+}

package/runtime/core/second-nature/guidance/impulse-context-reader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ImpulseContextReader — Read agent-facing impulse context artifact from state.
+ *
+ * Core logic: Retrieve the latest persisted artifact for a given scene/capability
+ * combo, with freshness diagnostics and explicit missing-artifact reasons.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md §1`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readImpulseContextArtifact)
+ *
+ * Boundary:
+ * - Does NOT fall back to real-time assembly; returns missing reason when absent.
+ * - Does NOT register a fake OpenClaw context-engine.
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+export interface ImpulseContextArtifactView {
+    id: string;
+    sceneType: string;
+    capabilityIntent: string | null;
+    platformId: string | null;
+    capabilityClass: string | null;
+    impulseSource: string;
+    impulseText: string | null;
+    atmosphereText: string | null;
+    expressionBoundaryConstraints: string[];
+    expressionBoundaryStyle: string | null;
+    freshnessVersion: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MissingArtifactReason {
+    available: false;
+    reason: "artifact_not_persisted" | "artifact_expired" | "state_unreadable" | "scene_capability_mismatch";
+    operatorNextAction: string;
+}
+export type ReadImpulseContextResult = {
+    available: true;
+    artifact: ImpulseContextArtifactView;
+    freshnessMs: number;
+} | MissingArtifactReason;
+export declare function readImpulseContext(db: StateDatabase, sceneType: string, capabilityIntent?: string, platformId?: string): Promise<ReadImpulseContextResult>;

package/runtime/core/second-nature/guidance/impulse-context-reader.js

@@ -0,0 +1,84 @@
+/**
+ * ImpulseContextReader — Read agent-facing impulse context artifact from state.
+ *
+ * Core logic: Retrieve the latest persisted artifact for a given scene/capability
+ * combo, with freshness diagnostics and explicit missing-artifact reasons.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md §1`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readImpulseContextArtifact)
+ *
+ * Boundary:
+ * - Does NOT fall back to real-time assembly; returns missing reason when absent.
+ * - Does NOT register a fake OpenClaw context-engine.
+ */
+import { readImpulseContextArtifact } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function parseConstraints(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function readImpulseContext(db, sceneType, capabilityIntent, platformId) {
+    const result = await readImpulseContextArtifact(db, sceneType, capabilityIntent, platformId);
+    if (result.degraded) {
+        return {
+            available: false,
+            reason: "state_unreadable",
+            operatorNextAction: "Check state database connectivity",
+        };
+    }
+    const row = result.row;
+    if (!row) {
+        return {
+            available: false,
+            reason: "artifact_not_persisted",
+            operatorNextAction: `Run guidance_payload for scene=${sceneType} cap=${capabilityIntent ?? "any"} to generate artifact`,
+        };
+    }
+    const now = Date.now();
+    const updatedAt = new Date(row.updatedAt).getTime();
+    const freshnessMs = now - updatedAt;
+    // Expire artifacts older than 24 hours
+    const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+    if (freshnessMs > ONE_DAY_MS) {
+        return {
+            available: false,
+            reason: "artifact_expired",
+            operatorNextAction: `Re-run guidance_payload for scene=${sceneType} — artifact is stale (${Math.round(freshnessMs / 3600000)}h old)`,
+        };
+    }
+    return {
+        available: true,
+        artifact: {
+            id: row.id,
+            sceneType: row.sceneType,
+            capabilityIntent: row.capabilityIntent,
+            platformId: row.platformId,
+            capabilityClass: row.capabilityClass,
+            impulseSource: row.impulseSource,
+            impulseText: row.impulseText,
+            atmosphereText: row.atmosphereText,
+            expressionBoundaryConstraints: parseConstraints(row.expressionBoundaryConstraintsJson),
+            expressionBoundaryStyle: row.expressionBoundaryStyle,
+            freshnessVersion: row.freshnessVersion,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        },
+        freshnessMs,
+    };
+}