@haaaiawd/second-nature 0.1.50 → 0.2.0

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;

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

@@ -0,0 +1,213 @@
+/**
+ * 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 { ACTION_KIND_REGISTRY } from "../../../shared/types/v8-contracts.js";
+// ───────────────────────────────────────────────────────────────
+// Config
+// ───────────────────────────────────────────────────────────────
+const AUTO_WRITE_MIN_RISK = "low";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function isWriteSideEffect(sideEffectClass) {
+    return sideEffectClass === "external_write" || sideEffectClass === "capability_declared";
+}
+function isOwnerAttentionAction(actionKind) {
+    return ["notify_owner", "draft_reply", "draft_publish"].includes(actionKind);
+}
+function canAutoRun(actionKind, riskPosture) {
+    const meta = ACTION_KIND_REGISTRY[actionKind];
+    if (!meta)
+        return false;
+    if (meta.sideEffectClass === "external_write" && riskPosture !== "low")
+        return false;
+    if (meta.sideEffectClass === "external_write" && riskPosture === "low")
+        return true;
+    if (meta.sideEffectClass === "capability_declared")
+        return riskPosture === "low";
+    if (meta.sideEffectClass === "owner_attention")
+        return riskPosture === "low" || riskPosture === "medium";
+    return meta.requiresPolicyDecision === false || meta.sideEffectClass === "none" || meta.sideEffectClass === "local_state";
+}
+function downgradeTarget(actionKind) {
+    const meta = ACTION_KIND_REGISTRY[actionKind];
+    if (!meta || meta.allowedDowngrades.length === 0)
+        return undefined;
+    return meta.allowedDowngrades[0];
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export function evaluateActionPolicy(proposal, context, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const proposalId = proposal.id;
+    const decisionId = `dec_${proposalId}_${now.replace(/[:.]/g, "")}`;
+    const proofRefs = proposal.sourceRefs.length > 0
+        ? proposal.sourceRefs
+        : [
+            {
+                uri: `sn://policy/${proposalId}`,
+                family: "action_closure",
+                id: proposalId,
+                redactionClass: "none",
+                resolveStatus: "resolvable",
+            },
+        ];
+    // 1. Missing source refs for owner/write actions → deny
+    if (proposal.sourceRefs.length === 0 &&
+        (isWriteSideEffect(proposal.sideEffectClass) || isOwnerAttentionAction(proposal.actionKind))) {
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "deny",
+            decisionReason: "policy_denied_missing_permission",
+            autonomyLevel: "none",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    // 2. Risk blocked or high → deny or defer
+    if (proposal.riskPosture === "blocked") {
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "deny",
+            decisionReason: "policy_denied_high_risk",
+            autonomyLevel: "none",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    if (proposal.riskPosture === "high") {
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "defer",
+            decisionReason: "policy_deferred_owner_confirmation",
+            autonomyLevel: "owner_confirm",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    // 3. Circuit breaker open → deny
+    if (context.breakerStatus === "open") {
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "deny",
+            decisionReason: "policy_denied_breaker_open",
+            autonomyLevel: "none",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    // 4. Write-side action + no platform permission → downgrade or deny
+    if (isWriteSideEffect(proposal.sideEffectClass) &&
+        context.platformPermissionDeclared === false) {
+        const target = downgradeTarget(proposal.actionKind);
+        if (target) {
+            return {
+                id: decisionId,
+                proposalId,
+                decision: "downgrade",
+                decisionReason: "policy_downgraded_to_draft",
+                autonomyLevel: "draft_only",
+                downgradedActionKind: target,
+                proofRefs,
+                decidedAt: now,
+            };
+        }
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "deny",
+            decisionReason: "policy_denied_missing_permission",
+            autonomyLevel: "none",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    // 5. Owner preference blocks auto → downgrade
+    if (context.ownerPreferenceAllowAuto === false &&
+        isWriteSideEffect(proposal.sideEffectClass)) {
+        const target = downgradeTarget(proposal.actionKind);
+        if (target) {
+            return {
+                id: decisionId,
+                proposalId,
+                decision: "downgrade",
+                decisionReason: "policy_downgraded_to_draft",
+                autonomyLevel: "draft_only",
+                downgradedActionKind: target,
+                proofRefs,
+                decidedAt: now,
+            };
+        }
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "deny",
+            decisionReason: "policy_denied_missing_permission",
+            autonomyLevel: "none",
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    // 6. Low risk + permission + healthy affordance → allow
+    if (proposal.riskPosture === AUTO_WRITE_MIN_RISK ||
+        proposal.riskPosture === "medium") {
+        if (canAutoRun(proposal.actionKind, proposal.riskPosture)) {
+            return {
+                id: decisionId,
+                proposalId,
+                decision: "allow",
+                decisionReason: "policy_allowed",
+                autonomyLevel: "auto_allowed",
+                proofRefs,
+                decidedAt: now,
+            };
+        }
+    }
+    // Default: downgrade to draft or deny
+    const target = downgradeTarget(proposal.actionKind);
+    if (target) {
+        return {
+            id: decisionId,
+            proposalId,
+            decision: "downgrade",
+            decisionReason: "policy_downgraded_to_draft",
+            autonomyLevel: "draft_only",
+            downgradedActionKind: target,
+            proofRefs,
+            decidedAt: now,
+        };
+    }
+    return {
+        id: decisionId,
+        proposalId,
+        decision: "deny",
+        decisionReason: "policy_denied_missing_permission",
+        autonomyLevel: "none",
+        proofRefs,
+        decidedAt: now,
+    };
+}

package/runtime/core/second-nature/action/policy-bound-dispatch.d.ts

@@ -0,0 +1,69 @@
+/**
+ * PolicyBoundDispatch — Dispatch allowed actions and record closure-safe
+ * downgraded results.
+ *
+ * Core logic: Read ActionPolicyDecision, route to connector or guidance
+ * based on decision, and return dispatch result for closure recording.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/autonomy-policy-evaluator.js` (ActionPolicyDecision)
+ * - `src/core/second-nature/action/action-proposal-builder.js` (ActionProposal)
+ *
+ * Boundary:
+ * - Does not execute connector directly; returns dispatch envelope.
+ * - Does not generate guidance text; returns guidance request envelope.
+ * - Degrades gracefully on unavailable guidance.
+ *
+ * Test coverage: tests/unit/action/policy-bound-dispatch.test.ts
+ */
+import type { DegradedOperationResult, PlatformNeutralActionKind, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+import type { ActionProposal } from "./action-proposal-builder.js";
+import type { ActionPolicyDecision } from "./autonomy-policy-evaluator.js";
+export interface ConnectorDispatchRequest {
+    type: "connector";
+    platformId: string;
+    capabilityId: string;
+    idempotencyKey: string;
+    policyProof: {
+        decisionId: string;
+        decision: string;
+    };
+    sourceRefs: string;
+}
+export interface GuidanceDispatchRequest {
+    type: "guidance";
+    actionKind: PlatformNeutralActionKind;
+    draftType: "reply" | "publish" | "notify";
+    policyProof: {
+        decisionId: string;
+        decision: string;
+    };
+    sourceRefs: string;
+}
+export interface NoDispatchResult {
+    type: "none";
+    reason: V8ReasonCode;
+}
+export interface GuidanceUnavailableResult {
+    type: "guidance_unavailable";
+    downgradedActionKind: PlatformNeutralActionKind;
+    reason: "guidance_unavailable";
+}
+export type DispatchResult = {
+    type: "connector";
+    request: ConnectorDispatchRequest;
+} | {
+    type: "guidance";
+    request: GuidanceDispatchRequest;
+} | NoDispatchResult | GuidanceUnavailableResult | {
+    type: "degraded";
+    degraded: DegradedOperationResult;
+};
+export interface DispatchAllowedActionOptions {
+    guidanceAvailable?: boolean;
+}
+export declare function dispatchAllowedAction(proposal: ActionProposal, decision: ActionPolicyDecision, options?: DispatchAllowedActionOptions): DispatchResult;

package/runtime/core/second-nature/action/policy-bound-dispatch.js

@@ -0,0 +1,112 @@
+/**
+ * PolicyBoundDispatch — Dispatch allowed actions and record closure-safe
+ * downgraded results.
+ *
+ * Core logic: Read ActionPolicyDecision, route to connector or guidance
+ * based on decision, and return dispatch result for closure recording.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/core/second-nature/action/autonomy-policy-evaluator.js` (ActionPolicyDecision)
+ * - `src/core/second-nature/action/action-proposal-builder.js` (ActionProposal)
+ *
+ * Boundary:
+ * - Does not execute connector directly; returns dispatch envelope.
+ * - Does not generate guidance text; returns guidance request envelope.
+ * - Degrades gracefully on unavailable guidance.
+ *
+ * Test coverage: tests/unit/action/policy-bound-dispatch.test.ts
+ */
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function inferGuidanceDraftType(actionKind) {
+    if (actionKind === "draft_reply" || actionKind === "auto_reply")
+        return "reply";
+    if (actionKind === "draft_publish" || actionKind === "auto_publish")
+        return "publish";
+    return "notify";
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export function dispatchAllowedAction(proposal, decision, options) {
+    // deny / defer → no dispatch
+    if (decision.decision === "deny") {
+        return { type: "none", reason: decision.decisionReason };
+    }
+    if (decision.decision === "defer") {
+        return { type: "none", reason: decision.decisionReason };
+    }
+    // downgrade → guidance only (no external write)
+    if (decision.decision === "downgrade") {
+        const target = decision.downgradedActionKind ?? proposal.actionKind;
+        const draftType = inferGuidanceDraftType(target);
+        // If guidance is unavailable, return closure-safe downgrade result
+        if (options?.guidanceAvailable === false) {
+            return {
+                type: "guidance_unavailable",
+                downgradedActionKind: target,
+                reason: "guidance_unavailable",
+            };
+        }
+        return {
+            type: "guidance",
+            request: {
+                type: "guidance",
+                actionKind: target,
+                draftType,
+                policyProof: { decisionId: decision.id, decision: decision.decision },
+                sourceRefs: JSON.stringify(decision.proofRefs),
+            },
+        };
+    }
+    // allow → route by action kind
+    if (decision.decision === "allow") {
+        if (proposal.actionKind === "run_connector") {
+            return {
+                type: "connector",
+                request: {
+                    type: "connector",
+                    platformId: proposal.targetPlatformId ?? "connector",
+                    capabilityId: proposal.targetCapabilityId ?? "run_connector",
+                    idempotencyKey: proposal.idempotencyKey,
+                    policyProof: { decisionId: decision.id, decision: decision.decision },
+                    sourceRefs: JSON.stringify(proposal.sourceRefs),
+                },
+            };
+        }
+        if (proposal.actionKind === "auto_reply" ||
+            proposal.actionKind === "auto_publish" ||
+            proposal.actionKind === "draft_reply" ||
+            proposal.actionKind === "draft_publish") {
+            const draftType = inferGuidanceDraftType(proposal.actionKind);
+            return {
+                type: "guidance",
+                request: {
+                    type: "guidance",
+                    actionKind: proposal.actionKind,
+                    draftType,
+                    policyProof: { decisionId: decision.id, decision: decision.decision },
+                    sourceRefs: JSON.stringify(proposal.sourceRefs),
+                },
+            };
+        }
+        // notify_owner / remember / watch / ignore — no external dispatch needed
+        return { type: "none", reason: decision.decisionReason };
+    }
+    return {
+        type: "degraded",
+        degraded: {
+            status: "degraded",
+            reason: "closure_failed",
+            ownerStage: "execution",
+            sourceRefs: decision.proofRefs,
+            operatorNextAction: "Unexpected policy decision shape",
+            retryable: false,
+        },
+    };
+}