@haaaiawd/second-nature 0.1.50 → 0.2.0

package/{dist/src → runtime}/cli/ops/ops-router.js

@@ -26,6 +26,8 @@ import { queryNarrativeTimeline, queryNarrativeDiff, NarrativeVersionNotFoundErr
 import { viewSecretAnchor, } from "../../observability/services/runtime-secret-anchor-view.js";
 import { writeRestoreAudit, } from "../../observability/services/restore-audit-service.js";
 import { createHistoryDigestStore } from "../../storage/services/history-digest-store.js";
+// v8 T-ROS.C.1: loop_status read model
+import { readLoopStatus } from "../../observability/loop-status.js";
 // T-ROS.C.3: ManualRunDispatcher and its deps
 import { createManualRunDispatcher, } from "./manual-run-dispatcher.js";
 import { createExperienceWriter } from "../../core/second-nature/body/tool-experience/experience-writer.js";
@@ -850,6 +852,77 @@ export function createOpsRouter(deps) {
                 const data = await deps.readModels.loadCycleRecent(limit);
                 return { ok: true, data };
             }
+            // ─── v8 commands (T-ROS.C.1) ─────────────────────────────────────────
+            /**
+             * [G1] loop_status — v8 causal loop health read model.
+             * Returns machine-readable overallStatus, stalledAt, stageSummaries,
+             * and human-readable nextAction for operator diagnosis.
+             */
+            if (command === "loop_status") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.state) {
+                    const envelope = {
+                        ok: false,
+                        command: "loop_status",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "STATE_DB_UNAVAILABLE",
+                            message: "loop_status requires state database in OpsRouterDeps",
+                            nextStep: "wire_state_db_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                try {
+                    const result = await readLoopStatus(deps.state);
+                    if (!result.ok) {
+                        const envelope = {
+                            ok: false,
+                            command: "loop_status",
+                            runtimeMode: "workspace_full_runtime",
+                            surfaceMode: "cli",
+                            generatedAt,
+                            error: {
+                                code: "LOOP_STATUS_DEGRADED",
+                                message: result.degraded.operatorNextAction,
+                                nextStep: "check_state_db_and_retry",
+                            },
+                            warnings: [result.degraded.reason],
+                            sourceRefs: result.degraded.sourceRefs.map((r) => r.uri),
+                        };
+                        return envelope;
+                    }
+                    const envelope = {
+                        ok: true,
+                        command: "loop_status",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data: result.status,
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const envelope = {
+                        ok: false,
+                        command: "loop_status",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code: "LOOP_STATUS_EXCEPTION", message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
             // ─── v7 commands (T-ROS.C.1) ─────────────────────────────────────────
             /** [G2] self_health — transparent pass-through from SelfHealthSnapshot (DR-042). */
             if (command === "self_health") {

package/runtime/connectors/evidence-normalizer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * EvidenceNormalizer — Convert connector read results into v8 EvidenceItems.
+ *
+ * Core logic: Map successful read-type ConnectorResult payloads into
+ * deduplicated EvidenceItem rows with structured SourceRef, content hash,
+ * platform id, observedAt, and sensitivity hint.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/connector-system.md`
+ * - `.anws/v8/02_ARCHITECTURE_OVERVIEW.md §System 7`
+ *
+ * Dependencies:
+ * - `src/shared/types/v8-contracts.js` (SourceRef, V8ReasonCode)
+ * - `src/storage/v8-state-stores.js` (writeEvidenceItem)
+ *
+ * Boundary:
+ * - Does not judge evidence importance.
+ * - Does not fabricate evidence on empty or failed connector results.
+ * - Deduplicates by content hash within a single normalization run.
+ *
+ * Test coverage: tests/unit/connectors/evidence-normalizer.test.ts
+ */
+import type { StateDatabase } from "../storage/db/index.js";
+import type { DegradedOperationResult, V8ReasonCode, SensitivityClass } from "../shared/types/v8-contracts.js";
+export interface ConnectorReadResult {
+    status: "success" | "failed" | "unavailable" | "timeout";
+    platformId: string;
+    capabilityId: string;
+    items: ConnectorReadItem[];
+    observedAt?: string;
+    failureReason?: V8ReasonCode;
+}
+export interface ConnectorReadItem {
+    id?: string;
+    content: string;
+    platformRef?: string;
+    sensitivityHint?: SensitivityClass;
+    metadata?: Record<string, unknown>;
+}
+export interface EvidenceNormalizationResult {
+    evidenceIds: string[];
+    emptyReason?: V8ReasonCode;
+    degraded?: DegradedOperationResult;
+}
+export declare function normalizeConnectorEvidence(db: StateDatabase, result: ConnectorReadResult, now?: string): Promise<EvidenceNormalizationResult>;

package/runtime/connectors/evidence-normalizer.js

@@ -0,0 +1,115 @@
+/**
+ * EvidenceNormalizer — Convert connector read results into v8 EvidenceItems.
+ *
+ * Core logic: Map successful read-type ConnectorResult payloads into
+ * deduplicated EvidenceItem rows with structured SourceRef, content hash,
+ * platform id, observedAt, and sensitivity hint.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/connector-system.md`
+ * - `.anws/v8/02_ARCHITECTURE_OVERVIEW.md §System 7`
+ *
+ * Dependencies:
+ * - `src/shared/types/v8-contracts.js` (SourceRef, V8ReasonCode)
+ * - `src/storage/v8-state-stores.js` (writeEvidenceItem)
+ *
+ * Boundary:
+ * - Does not judge evidence importance.
+ * - Does not fabricate evidence on empty or failed connector results.
+ * - Deduplicates by content hash within a single normalization run.
+ *
+ * Test coverage: tests/unit/connectors/evidence-normalizer.test.ts
+ */
+import * as crypto from "node:crypto";
+import { writeEvidenceItem } from "../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function computeContentHash(content) {
+    return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+function buildSourceRef(platformId, capabilityId, itemId, observedAt) {
+    return {
+        uri: `sn://connector_result/${platformId}/${capabilityId}/${itemId}`,
+        family: "connector_result",
+        id: `${platformId}_${capabilityId}_${itemId}`,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
+}
+function inferSensitivityHint(item) {
+    if (item.sensitivityHint)
+        return item.sensitivityHint;
+    const content = item.content;
+    if (/token|secret|password|key|credential/i.test(content)) {
+        if (/\b[a-zA-Z0-9_]+\s*[:=]\s*['"][a-zA-Z0-9+/=]{20,}['"]/.test(content)) {
+            return "sensitive";
+        }
+        return "public_technical";
+    }
+    return "public_general";
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function normalizeConnectorEvidence(db, result, now = new Date().toISOString()) {
+    // Reject failed/unavailable/timeout results — no fabrication
+    if (result.status !== "success") {
+        return {
+            evidenceIds: [],
+            emptyReason: "ingestion_connector_failed",
+        };
+    }
+    // Empty result — no fabrication
+    if (!result.items || result.items.length === 0) {
+        return {
+            evidenceIds: [],
+            emptyReason: "evidence_batch_empty",
+        };
+    }
+    // Truncate if over 100 items
+    const items = result.items.slice(0, 100);
+    const truncated = result.items.length > 100;
+    const seenHashes = new Set();
+    const evidenceIds = [];
+    for (const item of items) {
+        if (typeof item.content !== "string") {
+            continue;
+        }
+        const contentHash = computeContentHash(item.content);
+        // Deduplicate by content hash
+        if (seenHashes.has(contentHash))
+            continue;
+        seenHashes.add(contentHash);
+        const itemId = item.id ?? `ev_${contentHash}`;
+        const observedAt = result.observedAt ?? now;
+        const sourceRef = buildSourceRef(result.platformId, result.capabilityId, itemId, observedAt);
+        const sensitivityHint = inferSensitivityHint(item);
+        const writeResult = await writeEvidenceItem(db, {
+            id: `ev_${result.platformId}_${itemId}_${observedAt.replace(/[:.]/g, "")}`,
+            createdAt: now,
+            platformId: result.platformId,
+            contentHash,
+            observedAt,
+            sensitivityHint,
+            sourceRefs: [sourceRef],
+            redactionClass: sensitivityHint === "sensitive" ? "blocked" : "none",
+            lifecycleStatus: "pending",
+            payloadJson: item.metadata ? JSON.stringify(item.metadata) : null,
+        });
+        if ("id" in writeResult) {
+            evidenceIds.push(writeResult.id);
+        }
+        else {
+            // Degraded write — continue with remaining items, report degraded
+            return {
+                evidenceIds,
+                degraded: writeResult,
+            };
+        }
+    }
+    return {
+        evidenceIds,
+        emptyReason: truncated ? "evidence_batch_truncated" : undefined,
+    };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * ActionClosureRecorder — Record heartbeat cycle closure outcomes.
+ *
+ * Core logic: Write ActionClosureRecord for no-action, completed, denied,
+ * deferred, downgraded, and failed outcomes. Handles idempotent retry
+ * and remember-for-review memory candidates.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeActionClosureRecord, readActionClosuresByCycle)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does not execute actions; only records outcomes.
+ * - Does not form long-term memory; only emits review intent.
+ * - Degrades gracefully on DB failure.
+ *
+ * Test coverage: tests/unit/action/action-closure-recorder.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, V8ReasonCode, MemoryReviewCandidateClosure } from "../../../shared/types/v8-contracts.js";
+export type ClosureStatus = "completed" | "no_action" | "denied" | "deferred" | "downgraded" | "failed";
+export interface ActionClosureRecord {
+    id: string;
+    cycleId: string;
+    proposalId?: string;
+    decisionId?: string;
+    idempotencyKey?: string;
+    retryOfClosureId?: string;
+    dispatchAttempt: number;
+    closureStatus: ClosureStatus;
+    inputSummary: string;
+    outputSummary?: string;
+    postProcessing: string[];
+    nextState: string;
+    reason: V8ReasonCode;
+    sourceRefs: SourceRef[];
+    memoryReviewCandidate?: MemoryReviewCandidateClosure;
+    closedAt: string;
+}
+export interface RecordClosureOptions {
+    now?: string;
+}
+export type RecordClosureResult = {
+    status: "recorded";
+    closureId: string;
+} | {
+    status: "idempotent";
+    closureId: string;
+} | DegradedOperationResult;
+export declare function recordNoActionClosure(db: StateDatabase, cycleId: string, noActionReason: V8ReasonCode, options?: RecordClosureOptions): Promise<RecordClosureResult>;
+export declare function recordRememberClosure(db: StateDatabase, cycleId: string, memoryReviewCandidate: MemoryReviewCandidateClosure, options?: RecordClosureOptions): Promise<RecordClosureResult>;
+export declare function recordPolicyOutcomeClosure(db: StateDatabase, cycleId: string, closureStatus: ClosureStatus, reason: V8ReasonCode, params: {
+    proposalId?: string;
+    decisionId?: string;
+    downgradedActionKind?: string;
+    postProcessing?: string[];
+    nextState?: string;
+}, options?: RecordClosureOptions): Promise<RecordClosureResult>;
+export declare function recordExecutionClosure(db: StateDatabase, cycleId: string, closureStatus: "completed" | "failed", reason: V8ReasonCode, params: {
+    proposalId: string;
+    decisionId: string;
+    executionResultRef?: string;
+    outputSummary?: string;
+    nextState?: string;
+    retryable?: boolean;
+}, options?: RecordClosureOptions): Promise<RecordClosureResult>;

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

@@ -0,0 +1,184 @@
+/**
+ * ActionClosureRecorder — Record heartbeat cycle closure outcomes.
+ *
+ * Core logic: Write ActionClosureRecord for no-action, completed, denied,
+ * deferred, downgraded, and failed outcomes. Handles idempotent retry
+ * and remember-for-review memory candidates.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.4`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (writeActionClosureRecord, readActionClosuresByCycle)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult, V8ReasonCode)
+ *
+ * Boundary:
+ * - Does not execute actions; only records outcomes.
+ * - Does not form long-term memory; only emits review intent.
+ * - Degrades gracefully on DB failure.
+ *
+ * Test coverage: tests/unit/action/action-closure-recorder.test.ts
+ */
+import { writeActionClosureRecord, readActionClosuresByCycle, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function buildInputSummary(proposalId, decisionId) {
+    const parts = [];
+    if (proposalId)
+        parts.push(`proposal=${proposalId}`);
+    if (decisionId)
+        parts.push(`decision=${decisionId}`);
+    return parts.join(" ") || "no-action";
+}
+// ───────────────────────────────────────────────────────────────
+// Public API — No action
+// ───────────────────────────────────────────────────────────────
+export async function recordNoActionClosure(db, cycleId, noActionReason, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const closureId = `cls_no_${cycleId}`;
+    const existing = await readActionClosuresByCycle(db, cycleId);
+    if (!existing.degraded && existing.rows.some((r) => r.status === "no_action")) {
+        return { status: "idempotent", closureId };
+    }
+    const result = await writeActionClosureRecord(db, {
+        id: closureId,
+        createdAt: now,
+        cycleId,
+        status: "no_action",
+        reason: noActionReason,
+        nextState: "await_next_cycle",
+        sourceRefs: [
+            {
+                uri: `sn://closure/no_action/${cycleId}`,
+                family: "action_closure",
+                id: cycleId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ],
+        redactionClass: "none",
+        lifecycleStatus: "closed",
+        payloadJson: JSON.stringify({ dispatchAttempt: 0, inputSummary: "no-action" }),
+    });
+    if ("reason" in result) {
+        return result;
+    }
+    return { status: "recorded", closureId };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API — Remember for review
+// ───────────────────────────────────────────────────────────────
+export async function recordRememberClosure(db, cycleId, memoryReviewCandidate, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const closureId = `cls_remember_${cycleId}_${now.replace(/[:.]/g, "")}`;
+    const result = await writeActionClosureRecord(db, {
+        id: closureId,
+        createdAt: now,
+        cycleId,
+        status: "completed",
+        reason: "remember_for_review",
+        nextState: "pending_daily_review",
+        sourceRefs: memoryReviewCandidate.sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "closed",
+        payloadJson: JSON.stringify({
+            memoryReviewCandidate,
+            dispatchAttempt: 1,
+            inputSummary: `remember_for_review topic=${memoryReviewCandidate.topicKey}`,
+        }),
+    });
+    if ("reason" in result) {
+        return result;
+    }
+    return { status: "recorded", closureId };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API — Policy decision outcome
+// ───────────────────────────────────────────────────────────────
+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",
+        },
+    ];
+    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,
+        cycleId,
+        proposalId: params.proposalId,
+        decisionId: params.decisionId,
+        status: closureStatus,
+        reason,
+        nextState: params.nextState ?? "await_next_cycle",
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "closed",
+        payloadJson: JSON.stringify({
+            dispatchAttempt: 1,
+            inputSummary: buildInputSummary(params.proposalId, params.decisionId),
+            postProcessing: params.postProcessing ?? [],
+            downgradedActionKind: params.downgradedActionKind,
+        }),
+    });
+    if ("reason" in result) {
+        return result;
+    }
+    return { status: "recorded", closureId };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API — Execution outcome
+// ───────────────────────────────────────────────────────────────
+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 result = await writeActionClosureRecord(db, {
+        id: closureId,
+        createdAt: now,
+        cycleId,
+        proposalId: params.proposalId,
+        decisionId: params.decisionId,
+        status: closureStatus,
+        reason,
+        nextState: params.nextState ?? (closureStatus === "completed" ? "await_next_cycle" : "retryable"),
+        sourceRefs,
+        redactionClass: "none",
+        lifecycleStatus: "closed",
+        payloadJson: JSON.stringify({
+            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;
+    }
+    return { status: "recorded", closureId };
+}

package/runtime/core/second-nature/action/action-proposal-builder.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ActionProposalBuilder — Convert JudgmentVerdict into ActionProposal.
+ *
+ * Core logic: Read a verdict, map action kind to side-effect class and
+ * expected output, and write an ActionProposal row. For `remember` verdicts,
+ * emit a MemoryReviewCandidateClosure instead of an executable proposal.
+ * For `ignore` / `watch`, return a no-action result.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readJudgmentVerdictById, writeActionClosureRecord)
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind, SourceRef,
+ *   DegradedOperationResult, V8ReasonCode, ACTION_KIND_REGISTRY)
+ *
+ * Boundary:
+ * - Does not evaluate policy; only builds proposal payload.
+ * - Does not write long-term memory on `remember`; emits review intent only.
+ * - Degrades gracefully on missing verdict or unreadable state.
+ *
+ * Test coverage: tests/unit/action/action-proposal-builder.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, PlatformNeutralActionKind, V8ReasonCode, MemoryReviewCandidateClosure } from "../../../shared/types/v8-contracts.js";
+export interface ActionProposal {
+    id: string;
+    cycleId: string;
+    judgmentVerdictId: string;
+    actionKind: PlatformNeutralActionKind;
+    targetPlatformId?: string;
+    targetCapabilityId?: string;
+    sourceRefs: SourceRef[];
+    reason: V8ReasonCode;
+    riskPosture: "low" | "medium" | "high" | "blocked";
+    expectedOutput: string;
+    sideEffectClass: string;
+    idempotencyKey: string;
+    createdAt: string;
+}
+export interface NoActionResult {
+    status: "no_action";
+    reason: V8ReasonCode;
+    cycleId: string;
+    judgmentVerdictId: string;
+}
+export interface RememberForReviewResult {
+    status: "remember_for_review";
+    memoryReviewCandidate: MemoryReviewCandidateClosure;
+    closureId: string;
+}
+export type BuildActionProposalResult = {
+    status: "proposal";
+    proposal: ActionProposal;
+} | NoActionResult | RememberForReviewResult;
+export interface BuildActionProposalOptions {
+    now?: string;
+}
+export declare function buildActionProposal(db: StateDatabase, judgmentVerdictId: string, options?: BuildActionProposalOptions): Promise<BuildActionProposalResult | DegradedOperationResult>;
+export interface BatchBuildProposalResult {
+    proposals: ActionProposal[];
+    noActions: NoActionResult[];
+    rememberForReviews: RememberForReviewResult[];
+    failed: {
+        judgmentVerdictId: string;
+        degraded: DegradedOperationResult;
+    }[];
+}
+export declare function buildActionProposals(db: StateDatabase, judgmentVerdictIds: string[], options?: BuildActionProposalOptions): Promise<BatchBuildProposalResult>;