@haaaiawd/second-nature 0.1.50 → 0.2.0

package/runtime/observability/loop-status.js

@@ -0,0 +1,85 @@
+/**
+ * LoopStatus — Expose loop health and stalled stage diagnostics.
+ *
+ * Core logic: Call assembleLoopStatus, format into v8 loop_status shape,
+ * and include policy-denied closure counts.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md`
+ *
+ * Dependencies:
+ * - `src/observability/causal-loop-health.js` (assembleLoopStatus)
+ * - `src/storage/v8-state-stores.js` (readLoopStageEventsByStage)
+ *
+ * Boundary:
+ * - Read-only diagnostic query; does not modify state.
+ * - Returns degraded envelope when state unreadable.
+ *
+ * Test coverage: tests/unit/observability/loop-status.test.ts
+ */
+import { assembleLoopStatus } from "./causal-loop-health.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function computeNextAction(overallStatus, stalledAt) {
+    if (overallStatus === "healthy") {
+        return "No operator action required. Loop is progressing normally.";
+    }
+    if (overallStatus === "no_data") {
+        return "Run a heartbeat cycle or check connector configuration to generate initial evidence.";
+    }
+    if (overallStatus === "degraded") {
+        return "Check state database connectivity and retry. If persistent, review logs for state_unreadable errors.";
+    }
+    if (overallStatus === "stalled" && stalledAt) {
+        const actions = {
+            ingestion: "Verify connector credentials and platform availability. Check ingestion_connector_failed events.",
+            perception: "Check perception model availability or rules-only fallback. Review evidence_batch_empty vs perception_blocked_redaction.",
+            judgment: "Review judgment_low_confidence or judgment_missing_source_refs. Ensure perception cards have valid source refs.",
+            policy: "Review policy_denied_high_risk or policy_denied_missing_permission. Check affordance map and breaker status.",
+            execution: "Verify connector executor and guidance port availability. Check execution_unavailable or execution_timeout events.",
+            closure: "Check closure_missing or closure_failed. Verify state write validation and idempotency key uniqueness.",
+            quiet: "Quiet review may be empty or failed. Check quiet_empty_input or quiet_failed events. Daily review triggers after 36h window.",
+            dream: "Dream scheduler may be unavailable or redaction blocked. Check dream_scheduler_unavailable or dream_blocked_redaction events.",
+            projection: "Projection may be rejected or missing source refs. Check projection_rejected events and candidate validation.",
+        };
+        return actions[stalledAt] ?? `Review ${stalledAt} stage events for blocked or failed status.`;
+    }
+    return "Review loop stage events and state database health.";
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function readLoopStatus(db) {
+    const health = await assembleLoopStatus(db, { limit: 50 });
+    if ("status" in health && health.status === "degraded") {
+        return {
+            ok: false,
+            degraded: health,
+        };
+    }
+    const snapshot = health;
+    const stageSummaries = snapshot.stages.map((s) => ({
+        stage: s.stage,
+        eventCount: s.eventCount,
+        stalled: s.stalled,
+        lastEventAt: s.lastEventAt,
+    }));
+    // Policy denied count is a placeholder; real implementation would query action closures
+    const policyDeniedCount = 0;
+    const nextAction = computeNextAction(snapshot.overallStatus, snapshot.stalledAt);
+    return {
+        ok: true,
+        status: {
+            ok: true,
+            overallStatus: snapshot.overallStatus,
+            stalledAt: snapshot.stalledAt,
+            lastCycleSequence: snapshot.lastCycleSequence,
+            lastHeartbeatAt: snapshot.lastHeartbeatAt,
+            stageSummaries,
+            policyDeniedCount,
+            nextAction,
+        },
+    };
+}

package/{dist/src → runtime}/shared/types/index.js

@@ -4,3 +4,6 @@ export * from "./outreach.js";
 export * from "./source-ref.js";
 export * from "./goal.js";
 export * from "./v7-entities.js";
+// v8-contracts intentionally NOT re-exported from index to avoid SourceRef
+// name collision with v7 tuple type. v8 consumers import directly from
+// `./v8-contracts.js`.

package/runtime/shared/types/v8-contracts.d.ts

@@ -0,0 +1,86 @@
+/**
+ * v8 Shared Contracts — Cross-system value contracts for Living Perception Loop.
+ *
+ * Core logic: Single source of truth for types that would otherwise be
+ * duplicated across perception-judgment, action-closure-policy,
+ * dream-quiet-memory, observability-health, and control-plane systems.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §2`
+ *
+ * Dependencies: none (primitive shared types).
+ * Boundary: Type definitions only; no runtime logic.
+ * Test coverage: tests/unit/contracts/v8-shared-contracts.test.ts
+ */
+export type PlatformNeutralActionKind = "ignore" | "watch" | "remember" | "notify_owner" | "draft_reply" | "auto_reply" | "draft_publish" | "auto_publish" | "run_connector";
+export type ActionSideEffectClass = "none" | "local_state" | "owner_attention" | "external_write" | "external_read" | "capability_declared";
+export type ActionAttentionClass = "none" | "owner_visible" | "external_visible" | "depends_on_capability";
+export interface ActionKindMetadata {
+    kind: PlatformNeutralActionKind;
+    sideEffectClass: ActionSideEffectClass;
+    attentionClass: ActionAttentionClass;
+    requiresPolicyDecision: boolean;
+    allowedDowngrades: PlatformNeutralActionKind[];
+}
+export type ConnectorCapabilitySideEffect = "external_read" | "external_write" | "local_state" | "unknown";
+export type SourceRefFamily = "evidence" | "perception" | "judgment" | "action_closure" | "quiet_review" | "dream_run" | "memory_projection" | "tool_experience" | "connector_result" | "audit";
+export type RedactionClass = "none" | "redacted" | "blocked";
+export type SensitivityClass = "public_technical" | "public_general" | "private_context" | "sensitive";
+export type SourceResolveStatus = "resolvable" | "missing" | "redacted" | "permission_denied";
+export interface SourceRef {
+    uri: string;
+    family: SourceRefFamily;
+    id: string;
+    redactionClass: RedactionClass;
+    sensitivityClass?: SensitivityClass;
+    resolveStatus?: SourceResolveStatus;
+    resolveFailureReason?: string;
+}
+export type HeartbeatCycleStatus = "started" | "completed" | "failed" | "degraded";
+export interface HeartbeatCycleTrace {
+    cycleId: string;
+    cycleSequence: number;
+    heartbeatStartedAt: string;
+    heartbeatCompletedAt?: string;
+    inputCount: number;
+    outputCount: number;
+    expectedDownstreamByCycle?: number;
+    status: HeartbeatCycleStatus;
+}
+export type LoopStage = "ingestion" | "perception" | "judgment" | "policy" | "execution" | "closure" | "quiet" | "dream" | "projection";
+export type LoopStageEventStatus = "started" | "completed" | "skipped" | "blocked" | "failed";
+export interface LoopStageEvent {
+    id: string;
+    cycleId: string;
+    cycleSequence: number;
+    stage: LoopStage;
+    status: LoopStageEventStatus;
+    reason?: V8ReasonCode;
+    sourceRefs: SourceRef[];
+    redactionClass: RedactionClass;
+    occurredAt: string;
+    expectedDownstreamByCycle?: number;
+    payloadJson?: string;
+}
+export type MemoryReviewClosureSubtype = "remember_for_review";
+export interface MemoryReviewCandidateClosure {
+    closureSubtype: MemoryReviewClosureSubtype;
+    perceptionRef: SourceRef;
+    judgmentVerdictRef: SourceRef;
+    topicKey: string;
+    memoryIntentReason: string;
+    reviewPriority: "low" | "medium" | "high";
+    sourceRefs: [SourceRef, ...SourceRef[]];
+}
+export interface DegradedOperationResult {
+    status: "degraded" | "blocked";
+    reason: V8ReasonCode;
+    ownerStage: LoopStage;
+    sourceRefs: SourceRef[];
+    operatorNextAction: string;
+    retryable: boolean;
+}
+export type V8ReasonCode = "quiet_completed" | "quiet_empty_input" | "quiet_state_unreadable" | "quiet_validation_failed" | "dream_scheduled" | "dream_scheduler_unavailable" | "dream_started" | "dream_completed" | "dream_failed" | "dream_blocked_redaction" | "projection_candidate_created" | "projection_accepted" | "projection_rejected" | "projection_superseded" | "proposal_created" | "proposal_no_action" | "proposal_missing_source_refs" | "proposal_risk_blocked" | "policy_allowed" | "policy_deferred_owner_confirmation" | "policy_downgraded_to_draft" | "policy_denied_missing_permission" | "policy_denied_high_risk" | "policy_denied_breaker_open" | "guidance_unavailable" | "closure_completed" | "closure_no_action" | "closure_denied" | "closure_deferred" | "closure_downgraded" | "closure_downgraded_without_draft" | "closure_failed" | "perception_rules_only" | "evidence_batch_empty" | "evidence_batch_truncated" | "judgment_low_confidence" | "judgment_missing_source_refs" | "source_refs_unresolved" | "state_unreadable" | "stage_event_missing" | "ingestion_no_data" | "ingestion_empty" | "ingestion_state_unreadable" | "ingestion_connector_failed" | "execution_completed" | "execution_failed" | "execution_timeout" | "execution_unavailable";
+export declare const ACTION_KIND_REGISTRY: Readonly<Record<PlatformNeutralActionKind, ActionKindMetadata>>;

package/runtime/shared/types/v8-contracts.js

@@ -0,0 +1,84 @@
+/**
+ * v8 Shared Contracts — Cross-system value contracts for Living Perception Loop.
+ *
+ * Core logic: Single source of truth for types that would otherwise be
+ * duplicated across perception-judgment, action-closure-policy,
+ * dream-quiet-memory, observability-health, and control-plane systems.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.detail.md §2`
+ *
+ * Dependencies: none (primitive shared types).
+ * Boundary: Type definitions only; no runtime logic.
+ * Test coverage: tests/unit/contracts/v8-shared-contracts.test.ts
+ */
+// ───────────────────────────────────────────────────────────────
+// 7. Action Kind Registry Metadata Table
+// ───────────────────────────────────────────────────────────────
+export const ACTION_KIND_REGISTRY = {
+    ignore: {
+        kind: "ignore",
+        sideEffectClass: "none",
+        attentionClass: "none",
+        requiresPolicyDecision: false,
+        allowedDowngrades: [],
+    },
+    watch: {
+        kind: "watch",
+        sideEffectClass: "local_state",
+        attentionClass: "none",
+        requiresPolicyDecision: false,
+        allowedDowngrades: [],
+    },
+    remember: {
+        kind: "remember",
+        sideEffectClass: "local_state",
+        attentionClass: "none",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["watch"],
+    },
+    notify_owner: {
+        kind: "notify_owner",
+        sideEffectClass: "owner_attention",
+        attentionClass: "owner_visible",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["watch"],
+    },
+    draft_reply: {
+        kind: "draft_reply",
+        sideEffectClass: "local_state",
+        attentionClass: "owner_visible",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["notify_owner", "watch"],
+    },
+    auto_reply: {
+        kind: "auto_reply",
+        sideEffectClass: "external_write",
+        attentionClass: "external_visible",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["draft_reply", "notify_owner", "watch"],
+    },
+    draft_publish: {
+        kind: "draft_publish",
+        sideEffectClass: "local_state",
+        attentionClass: "owner_visible",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["notify_owner", "watch"],
+    },
+    auto_publish: {
+        kind: "auto_publish",
+        sideEffectClass: "external_write",
+        attentionClass: "external_visible",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["draft_publish", "notify_owner", "watch"],
+    },
+    run_connector: {
+        kind: "run_connector",
+        sideEffectClass: "capability_declared",
+        attentionClass: "depends_on_capability",
+        requiresPolicyDecision: true,
+        allowedDowngrades: ["notify_owner", "watch"],
+    },
+};

package/{dist/src → runtime}/storage/db/schema/index.d.ts

@@ -12,3 +12,4 @@ export * from "./narrative-state.js";
 export * from "./relationship-memory.js";
 export * from "./agent-goal.js";
 export * from "./memory-store.js";
+export * from "./v8-entities.js";

package/{dist/src → runtime}/storage/db/schema/index.js

@@ -12,3 +12,4 @@ export * from "./narrative-state.js";
 export * from "./relationship-memory.js";
 export * from "./agent-goal.js";
 export * from "./memory-store.js";
+export * from "./v8-entities.js";