@haaaiawd/second-nature 0.1.50 → 0.2.0

package/runtime/core/second-nature/body/tool-affordance/affordance-side-effect.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AffordanceSideEffect — v8 capability side-effect classifier.
+ *
+ * Core logic: Derive effective side-effect class for `run_connector` actions
+ * from connector capability metadata. Action policy uses this to decide
+ * allow/defer/downgrade/deny without knowing platform internals.
+ *
+ * Classification rules:
+ * - `feed.read`, `work.discover`, `notification.list` → external_read
+ * - `post.publish`, `comment.reply`, `message.send`, `task.claim` → external_write
+ * - `agent.register`, `agent.heartbeat` → local_state
+ * - Unknown / unlisted capability → unknown (policy must deny or downgrade)
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/body-tool-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §1.2`
+ *
+ * Dependencies:
+ * - `ConnectorCapabilitySideEffect` from `../../../../shared/types/v8-contracts.js`
+ *
+ * Boundary:
+ * - Pure classification function; no side effects, no DB access.
+ * - Does NOT perform capability probe — reads manifest metadata only.
+ * - Unknown capabilities return `unknown`; caller (policy) decides posture.
+ *
+ * Test coverage: tests/unit/body/affordance-side-effect.test.ts
+ */
+import type { ConnectorCapabilitySideEffect } from "../../../../shared/types/v8-contracts.js";
+export declare function deriveConnectorSideEffect(capabilityId: string): ConnectorCapabilitySideEffect;
+export interface CapabilityAffordancePosture {
+    connectorId: string;
+    capabilityId: string;
+    sideEffectClass: ConnectorCapabilitySideEffect;
+    authStatus: "ready" | "needs_auth" | "revoked" | "unknown";
+    breakerStatus: "closed" | "open" | "half_open";
+}
+export declare function assembleCapabilityAffordancePosture(connectorId: string, capabilityId: string, authStatus: CapabilityAffordancePosture["authStatus"], breakerStatus: CapabilityAffordancePosture["breakerStatus"]): CapabilityAffordancePosture;
+export interface SideEffectAwareAffordanceMap {
+    [connectorId: string]: {
+        [capabilityId: string]: CapabilityAffordancePosture;
+    };
+}
+export declare function buildSideEffectAwareAffordanceMap(postures: CapabilityAffordancePosture[]): SideEffectAwareAffordanceMap;
+export declare function lookupSideEffectPosture(map: SideEffectAwareAffordanceMap, connectorId: string, capabilityId: string): CapabilityAffordancePosture | undefined;
+export declare function isWriteSideEffect(sideEffect: ConnectorCapabilitySideEffect): boolean;
+export declare function isReadSideEffect(sideEffect: ConnectorCapabilitySideEffect): boolean;
+export declare function isLocalStateSideEffect(sideEffect: ConnectorCapabilitySideEffect): boolean;
+export declare function isUnknownSideEffect(sideEffect: ConnectorCapabilitySideEffect): boolean;
+export declare function effectiveActionSideEffectClass(sideEffect: ConnectorCapabilitySideEffect): "external_write" | "external_read" | "local_state" | "unknown";

package/runtime/core/second-nature/body/tool-affordance/affordance-side-effect.js

@@ -0,0 +1,100 @@
+/**
+ * AffordanceSideEffect — v8 capability side-effect classifier.
+ *
+ * Core logic: Derive effective side-effect class for `run_connector` actions
+ * from connector capability metadata. Action policy uses this to decide
+ * allow/defer/downgrade/deny without knowing platform internals.
+ *
+ * Classification rules:
+ * - `feed.read`, `work.discover`, `notification.list` → external_read
+ * - `post.publish`, `comment.reply`, `message.send`, `task.claim` → external_write
+ * - `agent.register`, `agent.heartbeat` → local_state
+ * - Unknown / unlisted capability → unknown (policy must deny or downgrade)
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/body-tool-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §1.2`
+ *
+ * Dependencies:
+ * - `ConnectorCapabilitySideEffect` from `../../../../shared/types/v8-contracts.js`
+ *
+ * Boundary:
+ * - Pure classification function; no side effects, no DB access.
+ * - Does NOT perform capability probe — reads manifest metadata only.
+ * - Unknown capabilities return `unknown`; caller (policy) decides posture.
+ *
+ * Test coverage: tests/unit/body/affordance-side-effect.test.ts
+ */
+// ───────────────────────────────────────────────────────────────
+// Capability → side-effect mapping
+// ───────────────────────────────────────────────────────────────
+const READ_CAPABILITIES = new Set([
+    "feed.read",
+    "work.discover",
+    "notification.list",
+    "profile.inspect",
+    "github:issue.search",
+]);
+const WRITE_CAPABILITIES = new Set([
+    "post.publish",
+    "comment.reply",
+    "message.send",
+    "task.claim",
+]);
+const LOCAL_STATE_CAPABILITIES = new Set([
+    "agent.register",
+    "agent.heartbeat",
+    "status.update",
+]);
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export function deriveConnectorSideEffect(capabilityId) {
+    if (READ_CAPABILITIES.has(capabilityId))
+        return "external_read";
+    if (WRITE_CAPABILITIES.has(capabilityId))
+        return "external_write";
+    if (LOCAL_STATE_CAPABILITIES.has(capabilityId))
+        return "local_state";
+    return "unknown";
+}
+export function assembleCapabilityAffordancePosture(connectorId, capabilityId, authStatus, breakerStatus) {
+    return {
+        connectorId,
+        capabilityId,
+        sideEffectClass: deriveConnectorSideEffect(capabilityId),
+        authStatus,
+        breakerStatus,
+    };
+}
+export function buildSideEffectAwareAffordanceMap(postures) {
+    const map = {};
+    for (const posture of postures) {
+        if (!map[posture.connectorId]) {
+            map[posture.connectorId] = {};
+        }
+        map[posture.connectorId][posture.capabilityId] = posture;
+    }
+    return map;
+}
+export function lookupSideEffectPosture(map, connectorId, capabilityId) {
+    return map[connectorId]?.[capabilityId];
+}
+// ───────────────────────────────────────────────────────────────
+// Policy-facing helpers
+// ───────────────────────────────────────────────────────────────
+export function isWriteSideEffect(sideEffect) {
+    return sideEffect === "external_write";
+}
+export function isReadSideEffect(sideEffect) {
+    return sideEffect === "external_read";
+}
+export function isLocalStateSideEffect(sideEffect) {
+    return sideEffect === "local_state";
+}
+export function isUnknownSideEffect(sideEffect) {
+    return sideEffect === "unknown";
+}
+export function effectiveActionSideEffectClass(sideEffect) {
+    return sideEffect;
+}

package/runtime/core/second-nature/control-plane/accepted-projection-loader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AcceptedProjectionLoader — Load accepted long-term memory into EmbodiedContext.
+ *
+ * Core logic: Read active/accepted projections from state, exclude candidates,
+ * and return bounded memory slice for heartbeat context assembly.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readMemoryProjectionsByStatus)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult)
+ *
+ * Boundary:
+ * - Only loads accepted/active projections; candidates are excluded.
+ * - Does not judge projection importance; loads all active.
+ * - Degrades gracefully on unreadable state.
+ *
+ * Test coverage: tests/unit/control-plane/accepted-projection-loader.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult } from "../../../shared/types/v8-contracts.js";
+export interface MemoryProjectionSlice {
+    projections: AcceptedProjection[];
+    topicKeys: string[];
+    totalProjections: number;
+}
+export interface AcceptedProjection {
+    id: string;
+    topicKey: string;
+    memoryText: string;
+    sourceRefs: SourceRef[];
+    acceptedAt?: string;
+}
+export type LoadAcceptedProjectionsResult = {
+    ok: true;
+    slice: MemoryProjectionSlice;
+} | {
+    ok: false;
+    degraded: DegradedOperationResult;
+};
+export declare function loadAcceptedProjections(db: StateDatabase, _options?: {
+    limit?: number;
+}): Promise<LoadAcceptedProjectionsResult>;

package/runtime/core/second-nature/control-plane/accepted-projection-loader.js

@@ -0,0 +1,85 @@
+/**
+ * AcceptedProjectionLoader — Load accepted long-term memory into EmbodiedContext.
+ *
+ * Core logic: Read active/accepted projections from state, exclude candidates,
+ * and return bounded memory slice for heartbeat context assembly.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/control-plane-system.md §5`
+ * - `.anws/v8/04_SYSTEM_DESIGN/dream-quiet-memory-system.md §4.2`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readMemoryProjectionsByStatus)
+ * - `src/shared/types/v8-contracts.js` (SourceRef, DegradedOperationResult)
+ *
+ * Boundary:
+ * - Only loads accepted/active projections; candidates are excluded.
+ * - Does not judge projection importance; loads all active.
+ * - Degrades gracefully on unreadable state.
+ *
+ * Test coverage: tests/unit/control-plane/accepted-projection-loader.test.ts
+ */
+import { readMemoryProjectionsByStatus, } from "../../../storage/v8-state-stores.js";
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function parsePayloadJson(json) {
+    if (!json)
+        return {};
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+function parseSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function loadAcceptedProjections(db, _options) {
+    const activeResult = await readMemoryProjectionsByStatus(db, "active");
+    if (activeResult.degraded) {
+        return {
+            ok: false,
+            degraded: activeResult.degraded,
+        };
+    }
+    const acceptedResult = await readMemoryProjectionsByStatus(db, "accepted");
+    if (acceptedResult.degraded) {
+        return {
+            ok: false,
+            degraded: acceptedResult.degraded,
+        };
+    }
+    const allProjections = [...activeResult.rows, ...acceptedResult.rows];
+    const projections = allProjections.map((row) => {
+        const payload = parsePayloadJson(row.payloadJson);
+        return {
+            id: row.id,
+            topicKey: row.topicKey,
+            memoryText: String(payload.memoryText ?? ""),
+            sourceRefs: parseSourceRefs(row.sourceRefsJson),
+            acceptedAt: payload.acceptedAt ? String(payload.acceptedAt) : undefined,
+        };
+    });
+    const topicKeys = [...new Set(projections.map((p) => p.topicKey))];
+    return {
+        ok: true,
+        slice: {
+            projections,
+            topicKeys,
+            totalProjections: projections.length,
+        },
+    };
+}

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