@haaaiawd/second-nature 0.1.51 → 0.2.0

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>;

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

@@ -0,0 +1,217 @@
+/**
+ * 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 { readJudgmentVerdictById, writeActionClosureRecord, } from "../../../storage/v8-state-stores.js";
+import { ACTION_KIND_REGISTRY } from "../../../shared/types/v8-contracts.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function parseVerdictSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function buildExpectedOutput(actionKind) {
+    switch (actionKind) {
+        case "ignore":
+            return "No action required";
+        case "watch":
+            return "Monitor for changes";
+        case "remember":
+            return "Queue for daily review";
+        case "notify_owner":
+            return "Send owner notification";
+        case "draft_reply":
+            return "Generate reply draft";
+        case "auto_reply":
+            return "Send automated reply";
+        case "draft_publish":
+            return "Generate publish draft";
+        case "auto_publish":
+            return "Publish to platform";
+        case "run_connector":
+            return "Execute connector capability";
+        default:
+            return "Unknown action";
+    }
+}
+function inferTargetPlatform(actionKind) {
+    if (actionKind === "run_connector") {
+        return { platformId: "connector", capabilityId: "run_connector" };
+    }
+    return {};
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function buildActionProposal(db, judgmentVerdictId, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const readResult = await readJudgmentVerdictById(db, judgmentVerdictId);
+    if (readResult.degraded) {
+        return readResult.degraded;
+    }
+    const verdict = readResult.row;
+    if (!verdict) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "policy",
+            sourceRefs: [],
+            operatorNextAction: `JudgmentVerdict ${judgmentVerdictId} not found`,
+            retryable: false,
+        };
+    }
+    const actionKind = verdict.actionKind;
+    const cycleId = verdict.cycleId;
+    // ignore / watch → no-action
+    if (actionKind === "ignore" || actionKind === "watch") {
+        return {
+            status: "no_action",
+            reason: "proposal_no_action",
+            cycleId,
+            judgmentVerdictId,
+        };
+    }
+    const sourceRefs = parseVerdictSourceRefs(verdict.sourceRefsJson);
+    // remember → memory review candidate closure (no direct projection)
+    if (actionKind === "remember") {
+        const candidate = {
+            closureSubtype: "remember_for_review",
+            perceptionRef: {
+                uri: `sn://perception/${verdict.perceptionCardId}`,
+                family: "perception",
+                id: verdict.perceptionCardId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+            judgmentVerdictRef: {
+                uri: `sn://judgment/${judgmentVerdictId}`,
+                family: "judgment",
+                id: judgmentVerdictId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+            topicKey: verdict.perceptionCardId,
+            memoryIntentReason: verdict.reason ?? "remember",
+            reviewPriority: "medium",
+            sourceRefs: (sourceRefs.length > 0 ? sourceRefs : [
+                {
+                    uri: `sn://proposal/remember/${judgmentVerdictId}`,
+                    family: "action_closure",
+                    id: judgmentVerdictId,
+                    redactionClass: "none",
+                    resolveStatus: "resolvable",
+                },
+            ]),
+        };
+        const closureId = `cls_remember_${judgmentVerdictId}_${now.replace(/[:.]/g, "")}`;
+        const writeResult = await writeActionClosureRecord(db, {
+            id: closureId,
+            createdAt: now,
+            cycleId,
+            status: "completed",
+            reason: "remember_for_review",
+            nextState: "pending_daily_review",
+            sourceRefs: candidate.sourceRefs,
+            redactionClass: "none",
+            lifecycleStatus: "closed",
+            payloadJson: JSON.stringify({ memoryReviewCandidate: candidate }),
+        });
+        if ("reason" in writeResult) {
+            return writeResult;
+        }
+        return {
+            status: "remember_for_review",
+            memoryReviewCandidate: candidate,
+            closureId,
+        };
+    }
+    // Actionable verdict → build proposal
+    const meta = ACTION_KIND_REGISTRY[actionKind];
+    const { platformId, capabilityId } = inferTargetPlatform(actionKind);
+    const proposal = {
+        id: `prop_${judgmentVerdictId}_${now.replace(/[:.]/g, "")}`,
+        cycleId,
+        judgmentVerdictId,
+        actionKind,
+        targetPlatformId: platformId,
+        targetCapabilityId: capabilityId,
+        sourceRefs: sourceRefs.length > 0 ? sourceRefs : [
+            {
+                uri: `sn://proposal/${judgmentVerdictId}`,
+                family: "action_closure",
+                id: judgmentVerdictId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ],
+        reason: verdict.reason ?? "proposal_created",
+        riskPosture: verdict.riskPosture ?? "low",
+        expectedOutput: buildExpectedOutput(actionKind),
+        sideEffectClass: meta?.sideEffectClass ?? "none",
+        idempotencyKey: `idem_${cycleId}_${judgmentVerdictId}`,
+        createdAt: now,
+    };
+    return {
+        status: "proposal",
+        proposal,
+    };
+}
+export async function buildActionProposals(db, judgmentVerdictIds, options) {
+    const proposals = [];
+    const noActions = [];
+    const rememberForReviews = [];
+    const failed = [];
+    for (const judgmentVerdictId of judgmentVerdictIds) {
+        const result = await buildActionProposal(db, judgmentVerdictId, options);
+        if ("status" in result && result.status === "proposal") {
+            proposals.push(result.proposal);
+        }
+        else if ("status" in result && result.status === "no_action") {
+            noActions.push(result);
+        }
+        else if ("status" in result && result.status === "remember_for_review") {
+            rememberForReviews.push(result);
+        }
+        else if ("status" in result && result.status === "degraded") {
+            failed.push({
+                judgmentVerdictId,
+                degraded: result,
+            });
+        }
+        else {
+            failed.push({
+                judgmentVerdictId,
+                degraded: result,
+            });
+        }
+    }
+    return { proposals, noActions, rememberForReviews, failed };
+}

package/runtime/core/second-nature/action/autonomy-policy-evaluator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AutonomyPolicyEvaluator — Evaluate ActionProposal against platform policy,
+ * affordance posture, and risk flags.
+ *
+ * Core logic: Table-driven allow/defer/downgrade/deny decisions based on
+ * side-effect class, source refs, risk posture, and breaker status.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.2, §4.1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind,
+ *   SourceRef, DegradedOperationResult, V8ReasonCode, ACTION_KIND_REGISTRY)
+ *
+ * Boundary:
+ * - Does not execute actions; only evaluates policy.
+ * - Does not read external platform state; relies on affordance input.
+ * - Pure function for testability; DB write is caller responsibility.
+ *
+ * Test coverage: tests/unit/action/autonomy-policy-evaluator.test.ts
+ */
+import type { SourceRef, PlatformNeutralActionKind, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+import type { ActionProposal } from "./action-proposal-builder.js";
+export interface ActionPolicyDecision {
+    id: string;
+    proposalId: string;
+    decision: "allow" | "defer" | "downgrade" | "deny";
+    decisionReason: V8ReasonCode;
+    autonomyLevel: "none" | "draft_only" | "owner_confirm" | "auto_allowed";
+    downgradedActionKind?: PlatformNeutralActionKind;
+    proofRefs: SourceRef[];
+    decidedAt: string;
+}
+export interface PolicyEvaluationContext {
+    breakerStatus?: "closed" | "open" | "half_open";
+    platformPermissionDeclared?: boolean;
+    ownerPreferenceAllowAuto?: boolean;
+}
+export interface EvaluateActionPolicyOptions {
+    now?: string;
+}
+export declare function evaluateActionPolicy(proposal: ActionProposal, context: PolicyEvaluationContext, options?: EvaluateActionPolicyOptions): ActionPolicyDecision;