@haaaiawd/second-nature 0.1.51 → 0.2.0

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

@@ -0,0 +1,38 @@
+/**
+ * HeartbeatOrchestrator — v8 control-plane heartbeat cycle trace writer.
+ *
+ * Core logic: Emit ordered HeartbeatCycleTrace, invoke perception/judgment
+ * ports, and return cycle result without making semantic action decisions.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §3`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeHeartbeatCycleTrace, readHeartbeatCycleTraces)
+ * - `src/observability/loop-stage-event-sink.js` (recordLoopStageEvent)
+ * - `src/core/second-nature/perception/perception-builder.js` (buildPerceptionCards)
+ * - `src/core/second-nature/perception/judgment-engine.js` (runAgentJudgments)
+ *
+ * Boundary:
+ * - Does NOT make semantic decisions about action allowability.
+ * - Does NOT bypass ActionPolicyDecision.
+ * - Degrades gracefully on DB failure or downstream unavailable.
+ *
+ * Test coverage: tests/unit/control-plane/heartbeat-cycle-trace.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface HeartbeatOrchestrationRequest {
+    workspaceRoot: string;
+    requestedAt?: string;
+    trigger?: "scheduled" | "manual" | "host";
+}
+export interface HeartbeatOrchestrationResult {
+    cycleId: string;
+    cycleSequence: number;
+    closureRef?: SourceRef;
+    noActionReason?: V8ReasonCode;
+    degraded?: DegradedOperationResult;
+}
+export declare function runHeartbeatCycle(db: StateDatabase, request: HeartbeatOrchestrationRequest): Promise<HeartbeatOrchestrationResult | DegradedOperationResult>;

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

@@ -0,0 +1,165 @@
+/**
+ * HeartbeatOrchestrator — v8 control-plane heartbeat cycle trace writer.
+ *
+ * Core logic: Emit ordered HeartbeatCycleTrace, invoke perception/judgment
+ * ports, and return cycle result without making semantic action decisions.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §3`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeHeartbeatCycleTrace, readHeartbeatCycleTraces)
+ * - `src/observability/loop-stage-event-sink.js` (recordLoopStageEvent)
+ * - `src/core/second-nature/perception/perception-builder.js` (buildPerceptionCards)
+ * - `src/core/second-nature/perception/judgment-engine.js` (runAgentJudgments)
+ *
+ * Boundary:
+ * - Does NOT make semantic decisions about action allowability.
+ * - Does NOT bypass ActionPolicyDecision.
+ * - Degrades gracefully on DB failure or downstream unavailable.
+ *
+ * Test coverage: tests/unit/control-plane/heartbeat-cycle-trace.test.ts
+ */
+import { writeHeartbeatCycleTrace, readHeartbeatCycleTraces, } from "../../../storage/v8-state-stores.js";
+import { recordLoopStageEvent } from "../../../observability/loop-stage-event-sink.js";
+import { buildPerceptionCards } from "../perception/perception-builder.js";
+import { runAgentJudgments } from "../perception/judgment-engine.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+async function nextCycleSequence(db) {
+    const result = await readHeartbeatCycleTraces(db, 1);
+    if (result.degraded || result.rows.length === 0) {
+        return 1;
+    }
+    return (result.rows[0]?.cycleSequence ?? 0) + 1;
+}
+function buildCycleId(sequence, now) {
+    return `cyc_${now.replace(/[:.]/g, "")}_${sequence}`;
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function runHeartbeatCycle(db, request) {
+    const now = request.requestedAt ?? new Date().toISOString();
+    const cycleSequence = await nextCycleSequence(db);
+    const cycleId = buildCycleId(cycleSequence, now);
+    // Write cycle trace — started
+    const traceResult = await writeHeartbeatCycleTrace(db, {
+        id: cycleId,
+        cycleSequence,
+        heartbeatStartedAt: now,
+        inputCount: 0,
+        outputCount: 0,
+        status: "started",
+        sourceRefs: [
+            {
+                uri: `sn://heartbeat/${cycleId}`,
+                family: "audit",
+                id: cycleId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ],
+    });
+    if ("reason" in traceResult) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "ingestion",
+            sourceRefs: [],
+            operatorNextAction: "Retry heartbeat after DB recovery",
+            retryable: true,
+        };
+    }
+    // Record ingestion stage started
+    await recordLoopStageEvent(db, {
+        id: `evt_${cycleId}_ingestion`,
+        cycleId,
+        cycleSequence,
+        stage: "ingestion",
+        status: "started",
+        occurredAt: now,
+        sourceRefs: [],
+    });
+    // ── Perception stage ──
+    const perceptionResult = await buildPerceptionCards(db, { cycleId, now });
+    const perceptionDegraded = "status" in perceptionResult && perceptionResult.status === "degraded"
+        ? perceptionResult
+        : null;
+    await recordLoopStageEvent(db, {
+        id: `evt_${cycleId}_perception`,
+        cycleId,
+        cycleSequence,
+        stage: "perception",
+        status: perceptionDegraded ? "failed" : "completed",
+        occurredAt: new Date().toISOString(),
+        reason: perceptionDegraded
+            ? perceptionResult.reason
+            : undefined,
+        sourceRefs: [],
+    });
+    if (perceptionDegraded || !("cards" in perceptionResult)) {
+        return {
+            cycleId,
+            cycleSequence,
+            degraded: perceptionDegraded
+                ? {
+                    status: "degraded",
+                    reason: perceptionResult.reason ?? "state_unreadable",
+                    ownerStage: "perception",
+                    sourceRefs: [],
+                    operatorNextAction: "Retry heartbeat after perception recovery",
+                    retryable: true,
+                }
+                : undefined,
+        };
+    }
+    const cards = perceptionResult.cards;
+    if (cards.length === 0) {
+        // No cards → no judgment needed
+        await recordLoopStageEvent(db, {
+            id: `evt_${cycleId}_judgment`,
+            cycleId,
+            cycleSequence,
+            stage: "judgment",
+            status: "skipped",
+            occurredAt: new Date().toISOString(),
+            reason: "evidence_batch_empty",
+            sourceRefs: [],
+        });
+        return {
+            cycleId,
+            cycleSequence,
+            noActionReason: "evidence_batch_empty",
+        };
+    }
+    // ── Judgment stage ──
+    const judgmentResult = await runAgentJudgments(db, cards.map((c) => c.id), { now });
+    const judgmentFailed = judgmentResult.failed.length > 0;
+    await recordLoopStageEvent(db, {
+        id: `evt_${cycleId}_judgment`,
+        cycleId,
+        cycleSequence,
+        stage: "judgment",
+        status: judgmentFailed ? "failed" : "completed",
+        occurredAt: new Date().toISOString(),
+        sourceRefs: [],
+    });
+    // Return cycle result
+    return {
+        cycleId,
+        cycleSequence,
+        closureRef: judgmentResult.succeeded.length > 0
+            ? {
+                uri: `sn://judgment/${cycleId}`,
+                family: "judgment",
+                id: cycleId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            }
+            : undefined,
+        noActionReason: judgmentResult.succeeded.length === 0 ? "proposal_no_action" : undefined,
+    };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * GuidanceProposalConsumer — Consume policy-downgraded proposals and
+ * produce owner-visible draft/notify outputs.
+ *
+ * Core logic: Read an ActionPolicyDecision with downgrade, map to
+ * guidance request shape, and return owner-visible output without
+ * executing external write.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/autonomy-policy-evaluator.js` (ActionPolicyDecision)
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind)
+ *
+ * Boundary:
+ * - Does not generate actual text; returns guidance request envelope.
+ * - Does not execute connector; only produces draft/notify intent.
+ * - Degrades gracefully on missing decision.
+ *
+ * Test coverage: tests/unit/guidance/guidance-proposal-consumer.test.ts
+ */
+import type { ActionPolicyDecision } from "../action/autonomy-policy-evaluator.js";
+import type { ActionProposal } from "../action/action-proposal-builder.js";
+import type { PlatformNeutralActionKind, SourceRef, DegradedOperationResult, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface GuidanceOutput {
+    id: string;
+    mode: "draft" | "notify";
+    textRef: SourceRef;
+    sourceRefs: SourceRef[];
+    deliveryClaim: "not_delivered";
+    decisionId: string;
+    actionKind: PlatformNeutralActionKind;
+    ownerVisible: boolean;
+}
+export type GuidanceValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: V8ReasonCode;
+    sourceRefs: SourceRef[];
+};
+export type ConsumeGuidanceProposalResult = {
+    ok: true;
+    output: GuidanceOutput;
+} | {
+    ok: false;
+    degraded: DegradedOperationResult;
+};
+export declare function consumeGuidanceProposal(proposal: ActionProposal, decision: ActionPolicyDecision): ConsumeGuidanceProposalResult;

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

@@ -0,0 +1,113 @@
+/**
+ * GuidanceProposalConsumer — Consume policy-downgraded proposals and
+ * produce owner-visible draft/notify outputs.
+ *
+ * Core logic: Read an ActionPolicyDecision with downgrade, map to
+ * guidance request shape, and return owner-visible output without
+ * executing external write.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/guidance-voice-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/autonomy-policy-evaluator.js` (ActionPolicyDecision)
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind)
+ *
+ * Boundary:
+ * - Does not generate actual text; returns guidance request envelope.
+ * - Does not execute connector; only produces draft/notify intent.
+ * - Degrades gracefully on missing decision.
+ *
+ * Test coverage: tests/unit/guidance/guidance-proposal-consumer.test.ts
+ */
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function validateSourceRefs(proposalRefs, proofRefs) {
+    // Proposal must have at least one source ref
+    if (proposalRefs.length === 0) {
+        return {
+            ok: false,
+            reason: "source_refs_unresolved",
+            sourceRefs: [],
+        };
+    }
+    const allRefs = [...proposalRefs, ...proofRefs];
+    const unresolved = allRefs.filter((r) => r.resolveStatus === "missing" || r.resolveStatus === "permission_denied");
+    if (unresolved.length > 0) {
+        return {
+            ok: false,
+            reason: "source_refs_unresolved",
+            sourceRefs: unresolved,
+        };
+    }
+    return { ok: true };
+}
+function buildGuidanceOutput(proposal, decision) {
+    const actionKind = decision.downgradedActionKind ?? proposal.actionKind;
+    let mode = "notify";
+    if (actionKind === "draft_reply" || actionKind === "auto_reply") {
+        mode = "draft";
+    }
+    else if (actionKind === "draft_publish" || actionKind === "auto_publish") {
+        mode = "draft";
+    }
+    else if (actionKind === "notify_owner") {
+        mode = "notify";
+    }
+    const textRef = {
+        uri: `sn://guidance/${proposal.id}`,
+        family: "action_closure",
+        id: proposal.id,
+        redactionClass: "none",
+        sensitivityClass: proposal.sourceRefs[0]?.sensitivityClass ?? "public_general",
+        resolveStatus: "resolvable",
+    };
+    return {
+        id: `guidance_${decision.id}_${Date.now()}`,
+        mode,
+        textRef,
+        sourceRefs: [...proposal.sourceRefs, ...decision.proofRefs],
+        deliveryClaim: "not_delivered",
+        decisionId: decision.id,
+        actionKind,
+        ownerVisible: true,
+    };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export function consumeGuidanceProposal(proposal, decision) {
+    // Only consume allowed or downgraded proposals
+    if (decision.decision !== "downgrade" && decision.decision !== "allow") {
+        return {
+            ok: false,
+            degraded: {
+                status: "blocked",
+                reason: "policy_denied_high_risk",
+                ownerStage: "execution",
+                sourceRefs: decision.proofRefs,
+                operatorNextAction: "Review policy decision before requesting guidance",
+                retryable: false,
+            },
+        };
+    }
+    // Validate source refs
+    const validation = validateSourceRefs(proposal.sourceRefs, decision.proofRefs);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            degraded: {
+                status: "blocked",
+                reason: validation.reason,
+                ownerStage: "execution",
+                sourceRefs: validation.sourceRefs,
+                operatorNextAction: "Fix unresolved source refs in proposal or decision proof",
+                retryable: true,
+            },
+        };
+    }
+    const output = buildGuidanceOutput(proposal, decision);
+    return { ok: true, output };
+}

package/runtime/core/second-nature/heartbeat/goal-lifecycle-policy.d.ts

@@ -1,24 +1,24 @@
-export interface GoalTransitionRequest {
-    goalId: string;
-    newStatus: "completed" | "expired" | "replaced" | "paused" | "accepted";
-    reason: string;
-    updatedAt: string;
-}
-/** Minimal goal shape required by the lifecycle policy evaluator. */
-export interface EvaluableGoal {
-    goalId: string;
-    kind?: string;
-    scope?: string;
-    status: string;
-    updatedAt?: string;
-    expiresAt?: string;
-}
-export interface GoalLifecyclePolicyResult {
-    activeGoals: EvaluableGoal[];
-    transitionRequests: GoalTransitionRequest[];
-    evaluatedAt: string;
-}
-export interface GoalLifecyclePolicy {
-    evaluate(goals: EvaluableGoal[]): GoalLifecyclePolicyResult;
-}
-export declare function createGoalLifecyclePolicy(): GoalLifecyclePolicy;
+export interface GoalTransitionRequest {
+    goalId: string;
+    newStatus: "completed" | "expired" | "replaced" | "paused" | "accepted";
+    reason: string;
+    updatedAt: string;
+}
+/** Minimal goal shape required by the lifecycle policy evaluator. */
+export interface EvaluableGoal {
+    goalId: string;
+    kind?: string;
+    scope?: string;
+    status: string;
+    updatedAt?: string;
+    expiresAt?: string;
+}
+export interface GoalLifecyclePolicyResult {
+    activeGoals: EvaluableGoal[];
+    transitionRequests: GoalTransitionRequest[];
+    evaluatedAt: string;
+}
+export interface GoalLifecyclePolicy {
+    evaluate(goals: EvaluableGoal[]): GoalLifecyclePolicyResult;
+}
+export declare function createGoalLifecyclePolicy(): GoalLifecyclePolicy;

package/runtime/core/second-nature/heartbeat/goal-lifecycle-policy.js

@@ -1,61 +1,61 @@
-export function createGoalLifecyclePolicy() {
-    return {
-        evaluate(goals) {
-            const now = new Date().toISOString();
-            const activeGoals = [];
-            const transitionRequests = [];
-            // Group by kind+scope to detect duplicates among accepted goals
-            const groups = new Map();
-            for (const goal of goals) {
-                if (goal.status !== "accepted")
-                    continue;
-                const key = `${goal.kind}:${goal.scope ?? "global"}`;
-                const list = groups.get(key) ?? [];
-                list.push(goal);
-                groups.set(key, list);
-            }
-            for (const [key, list] of groups) {
-                // Sort by updatedAt desc, keep newest as active
-                const sorted = [...list].sort((a, b) => {
-                    const aTime = new Date(a.updatedAt ?? 0).getTime();
-                    const bTime = new Date(b.updatedAt ?? 0).getTime();
-                    if (isNaN(aTime) || isNaN(bTime))
-                        return 0;
-                    return bTime - aTime;
-                });
-                const [newest, ...older] = sorted;
-                if (newest) {
-                    activeGoals.push(newest);
-                    // Older same kind+scope goals → replace
-                    for (const old of older) {
-                        transitionRequests.push({
-                            goalId: old.goalId,
-                            newStatus: "replaced",
-                            reason: `same_kind_scope_replace:${key}`,
-                            updatedAt: now,
-                        });
-                    }
-                }
-            }
-            // Detect expired goals among active
-            for (const goal of activeGoals) {
-                if (goal.expiresAt) {
-                    const expiresTime = new Date(goal.expiresAt).getTime();
-                    if (!isNaN(expiresTime) && expiresTime < new Date(now).getTime()) {
-                        transitionRequests.push({
-                            goalId: goal.goalId,
-                            newStatus: "expired",
-                            reason: "expires_at_reached",
-                            updatedAt: now,
-                        });
-                    }
-                }
-            }
-            return {
-                activeGoals,
-                transitionRequests,
-                evaluatedAt: now,
-            };
-        },
-    };
-}
+export function createGoalLifecyclePolicy() {
+    return {
+        evaluate(goals) {
+            const now = new Date().toISOString();
+            const activeGoals = [];
+            const transitionRequests = [];
+            // Group by kind+scope to detect duplicates among accepted goals
+            const groups = new Map();
+            for (const goal of goals) {
+                if (goal.status !== "accepted")
+                    continue;
+                const key = `${goal.kind}:${goal.scope ?? "global"}`;
+                const list = groups.get(key) ?? [];
+                list.push(goal);
+                groups.set(key, list);
+            }
+            for (const [key, list] of groups) {
+                // Sort by updatedAt desc, keep newest as active
+                const sorted = [...list].sort((a, b) => {
+                    const aTime = new Date(a.updatedAt ?? 0).getTime();
+                    const bTime = new Date(b.updatedAt ?? 0).getTime();
+                    if (isNaN(aTime) || isNaN(bTime))
+                        return 0;
+                    return bTime - aTime;
+                });
+                const [newest, ...older] = sorted;
+                if (newest) {
+                    activeGoals.push(newest);
+                    // Older same kind+scope goals → replace
+                    for (const old of older) {
+                        transitionRequests.push({
+                            goalId: old.goalId,
+                            newStatus: "replaced",
+                            reason: `same_kind_scope_replace:${key}`,
+                            updatedAt: now,
+                        });
+                    }
+                }
+            }
+            // Detect expired goals among active
+            for (const goal of activeGoals) {
+                if (goal.expiresAt) {
+                    const expiresTime = new Date(goal.expiresAt).getTime();
+                    if (!isNaN(expiresTime) && expiresTime < new Date(now).getTime()) {
+                        transitionRequests.push({
+                            goalId: goal.goalId,
+                            newStatus: "expired",
+                            reason: "expires_at_reached",
+                            updatedAt: now,
+                        });
+                    }
+                }
+            }
+            return {
+                activeGoals,
+                transitionRequests,
+                evaluatedAt: now,
+            };
+        },
+    };
+}