@haaaiawd/second-nature 0.1.7 → 0.1.9

package/runtime/cli/ops/ops-router.js

@@ -0,0 +1,83 @@
+/**
+ * Shared ops command dispatch for CLI + tool surfaces (T1.1.3, T1.2.2).
+ */
+import { heartbeatCheck } from "./heartbeat-surface.js";
+import { showOperatorFallback, OperatorFallbackNotFoundError } from "./show-operator-fallback.js";
+export function createOpsRouter(deps) {
+    return {
+        heartbeatCheck: (input) => heartbeatCheck({
+            ...input,
+            runtimeAvailable: input.runtimeAvailable ?? deps.runtimeAvailable,
+            readModels: input.readModels ?? deps.readModels,
+        }),
+        dispatch(command, input) {
+            if (command === "heartbeat_check") {
+                const runtimeAvailable = typeof input?.runtimeAvailable === "boolean" ? input.runtimeAvailable : deps.runtimeAvailable;
+                return heartbeatCheck({
+                    probeOnly: Boolean(input?.probeOnly),
+                    runtimeAvailable,
+                    fakeControlPlanePassthrough: input?.fakeControlPlanePassthrough && typeof input.fakeControlPlanePassthrough === "object"
+                        ? input.fakeControlPlanePassthrough
+                        : undefined,
+                    readModels: deps.readModels,
+                    timestamp: typeof input?.timestamp === "string" ? input.timestamp : undefined,
+                    sessionContext: typeof input?.sessionContext === "string" ? input.sessionContext : undefined,
+                    scopeHint: input?.scopeHint,
+                });
+            }
+            if (command === "fallback") {
+                const ref = typeof input?.ref === "string" ? input.ref.trim() : "";
+                if (!ref) {
+                    return {
+                        ok: false,
+                        error: {
+                            code: "MISSING_FALLBACK_REF",
+                            message: "fallback requires args.ref (e.g. fallback:…)",
+                            requiredUserInput: ["ref"],
+                            nextStep: "reinvoke_with_ref",
+                        },
+                    };
+                }
+                if (!deps.readModels?.loadFallbackView) {
+                    return {
+                        ok: false,
+                        error: {
+                            code: "FALLBACK_READ_MODEL_UNAVAILABLE",
+                            message: "Operator fallback view requires workspace read models",
+                            requiredUserInput: ["ref"],
+                            nextStep: "wire_read_models_into_ops_router",
+                        },
+                    };
+                }
+                return (async () => {
+                    try {
+                        const data = await showOperatorFallback(ref, deps.readModels);
+                        return { ok: true, command: "fallback", data };
+                    }
+                    catch (error) {
+                        if (error instanceof OperatorFallbackNotFoundError) {
+                            return {
+                                ok: false,
+                                command: "fallback",
+                                error: {
+                                    code: error.code,
+                                    message: error.message,
+                                    requiredUserInput: ["ref"],
+                                    nextStep: "verify_fallback_ref_from_delivery_audit",
+                                },
+                            };
+                        }
+                        throw error;
+                    }
+                })();
+            }
+            return {
+                ok: false,
+                error: {
+                    code: "unknown_ops_command",
+                    message: `Unknown ops command: ${command}`,
+                },
+            };
+        },
+    };
+}

package/runtime/cli/ops/show-operator-fallback.d.ts

@@ -0,0 +1,13 @@
+import type { OperatorFallbackView } from "../../storage/fallback/operator-fallback-view.js";
+export declare class OperatorFallbackNotFoundError extends Error {
+    readonly ref: string;
+    readonly code: "FALLBACK_NOT_FOUND";
+    constructor(ref: string);
+}
+export interface ShowOperatorFallbackReadModels {
+    loadFallbackView(ref: string): Promise<OperatorFallbackView | null>;
+}
+/**
+ * T1.2.2 — Operator-visible fallback: always `status: not_sent` (ADR-007), never sent/delivered.
+ */
+export declare function showOperatorFallback(ref: string, readModels: ShowOperatorFallbackReadModels): Promise<OperatorFallbackView>;

package/runtime/cli/ops/show-operator-fallback.js

@@ -0,0 +1,22 @@
+export class OperatorFallbackNotFoundError extends Error {
+    ref;
+    code = "FALLBACK_NOT_FOUND";
+    constructor(ref) {
+        super(`No operator fallback artifact for ref: ${ref}`);
+        this.ref = ref;
+        this.name = "OperatorFallbackNotFoundError";
+    }
+}
+/**
+ * T1.2.2 — Operator-visible fallback: always `status: not_sent` (ADR-007), never sent/delivered.
+ */
+export async function showOperatorFallback(ref, readModels) {
+    const view = await readModels.loadFallbackView(ref);
+    if (!view) {
+        throw new OperatorFallbackNotFoundError(ref.trim());
+    }
+    return {
+        ...view,
+        status: "not_sent",
+    };
+}

package/runtime/cli/ops/workspace-heartbeat-runner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wires CLI read models into control-plane `runHeartbeatCycle` for `heartbeat_check` (US-001 / CH-09-02).
+ *
+ * Snapshot inputs are derived from aggregated status; delivery defaults to none until host capability is modeled here.
+ */
+import type { HeartbeatSignal, HeartbeatCycleResult } from "../../core/second-nature/heartbeat/signal.js";
+import type { SnapshotInputs } from "../../core/second-nature/heartbeat/snapshot-builder.js";
+import type { CliReadModels } from "../read-models/index.js";
+export declare function loadSnapshotInputsForWorkspaceHeartbeat(readModels: CliReadModels): Promise<SnapshotInputs>;
+export declare function createWorkspaceHeartbeatRunner(readModels: CliReadModels): (signal: HeartbeatSignal) => Promise<HeartbeatCycleResult>;

package/runtime/cli/ops/workspace-heartbeat-runner.js

@@ -0,0 +1,26 @@
+import { runHeartbeatCycle } from "../../core/second-nature/heartbeat/run-heartbeat-cycle.js";
+export async function loadSnapshotInputsForWorkspaceHeartbeat(readModels) {
+    const status = await readModels.loadStatus();
+    const mode = status.rhythm.mode === "unknown" ? "active" : status.rhythm.mode;
+    const quietEnabledBridge = status.quiet.mode === "quiet";
+    return {
+        mode,
+        currentWindowId: status.rhythm.windowId ?? "workspace-default",
+        pendingObligations: [],
+        recentOutreachHashes: [],
+        deniedIntents: [],
+        budgets: { socialUsed: 0, socialLimit: 5 },
+        awaitingUserInput: false,
+        quietEnabledBridge,
+        deliveryCapability: { target: "none" },
+    };
+}
+export function createWorkspaceHeartbeatRunner(readModels) {
+    return (signal) => runHeartbeatCycle({
+        signal,
+        runtimeAvailable: true,
+        deps: {
+            loadSnapshotInputs: () => loadSnapshotInputsForWorkspaceHeartbeat(readModels),
+        },
+    });
+}

package/runtime/cli/read-models/index.d.ts

@@ -1,6 +1,9 @@
 import type { StateDatabase } from "../../storage/db/index.js";
 import type { ObservabilityDatabase } from "../../observability/db/index.js";
-import type { StatusReadModel, DailyReportReadModel, QuietReadModel, SessionDetailReadModel, CredentialReadModel, ExplainReadModel } from "./types.js";
+import { AppendOnlyAuditStore } from "../../observability/audit/append-only-audit-store.js";
+import type { StatusReadModel, DailyReportReadModel, QuietReadModel, SessionDetailReadModel, CredentialReadModel, ExplainReadModel, ExplainSubjectKind } from "./types.js";
+export type { ExplainSubjectKind } from "./types.js";
+import type { OperatorFallbackView } from "../../storage/fallback/operator-fallback-view.js";
 export interface CliReadModels {
     loadStatus(scope?: string): Promise<StatusReadModel>;
     loadDailyReport(day: string): Promise<DailyReportReadModel>;
@@ -8,13 +11,19 @@ export interface CliReadModels {
     loadSession(sessionId: string): Promise<SessionDetailReadModel>;
     loadCredential(platformId: string): Promise<CredentialReadModel>;
     explain(subject: ExplainSubject): Promise<ExplainReadModel>;
+    /** T1.2.2 — persisted operator fallback; view status is always not_sent. */
+    loadFallbackView(ref: string): Promise<OperatorFallbackView | null>;
 }
+/** T1.2.1 / T1.2.2 — operator-facing read surface (subset of full CLI read models). */
+export type OpsReadModelPort = Pick<CliReadModels, "loadStatus" | "loadDailyReport" | "loadQuiet" | "loadSession" | "loadCredential" | "explain" | "loadFallbackView">;
 export interface ExplainSubject {
-    kind: "decision" | "platform-selection" | "outreach" | "soul-change";
+    kind: ExplainSubjectKind;
     id: string;
 }
 export interface CliReadModelsDeps {
     stateDb: StateDatabase;
     observabilityDb: ObservabilityDatabase;
+    /** When set, explain can resolve delivery/fallback/report/source_ref and enrich decision subjects from lived-experience audit envelopes (T5.3.1 / T1.2.1). */
+    livedExperienceAuditStore?: AppendOnlyAuditStore;
 }
 export declare function createCliReadModels(deps: CliReadModelsDeps): CliReadModels;

package/runtime/cli/read-models/index.js

@@ -4,8 +4,33 @@ import { AssetRepository } from "../../storage/repositories/asset-repository.js"
 import { CredentialRepository } from "../../storage/repositories/credential-repository.js";
 import { EvidenceQueryEngine } from "../../observability/query/evidence-query-engine.js";
 import { decisionLedger, executionAttempts } from "../../observability/db/schema/index.js";
+import { queryExplain } from "../../observability/query/explain-query.js";
+import { mapOperatorExplainToReadModel } from "./operator-explain-map.js";
+import { loadOperatorFallbackRow, toOperatorFallbackView } from "../../storage/fallback/load-operator-fallback.js";
 const INTERNAL_RUNTIME_PLATFORM_ID = "second-nature-runtime";
 const INTERNAL_RUNTIME_TRACE_PREFIX = "sn-runtime-";
+function toExplainQuery(subject) {
+    switch (subject.kind) {
+        case "decision":
+            return { kind: "decision", decisionId: subject.id };
+        case "fallback": {
+            const ref = subject.id.startsWith("fallback:") ? subject.id : `fallback:${subject.id}`;
+            return { kind: "fallback", fallbackRef: ref };
+        }
+        case "probe":
+        case "report":
+            return { kind: "report", reportId: subject.id };
+        case "delivery":
+            return { kind: "delivery", auditId: subject.id };
+        case "source_ref":
+            return { kind: "source_ref", sourceRefId: subject.id };
+        default:
+            return undefined;
+    }
+}
+function isAuditOnlySubjectKind(kind) {
+    return kind === "fallback" || kind === "probe" || kind === "report" || kind === "delivery" || kind === "source_ref";
+}
 function buildCredentialNextStep(status) {
     if (status === "pending_verification")
         return "submit_verification_answer";
@@ -36,6 +61,7 @@ export function createCliReadModels(deps) {
     const credentialRepository = new CredentialRepository(deps.stateDb);
     const quietLoader = createQuietInputLoader(assetRepository);
     const evidenceQuery = new EvidenceQueryEngine(deps.observabilityDb);
+    const auditStore = deps.livedExperienceAuditStore;
     return {
         async loadStatus(_scope) {
             let recentAttempts = [];
@@ -190,7 +216,31 @@ export function createCliReadModels(deps) {
                 nextStep: buildCredentialNextStep(record.status),
             };
         },
+        async loadFallbackView(ref) {
+            const row = await loadOperatorFallbackRow(deps.stateDb, ref);
+            if (!row)
+                return null;
+            return toOperatorFallbackView(row);
+        },
         async explain(subject) {
+            const q = toExplainQuery(subject);
+            if (auditStore && q) {
+                const op = queryExplain(q, auditStore);
+                if (isAuditOnlySubjectKind(subject.kind)) {
+                    return mapOperatorExplainToReadModel(op, subject.kind);
+                }
+                if (op.relatedEventIds.length > 0) {
+                    return mapOperatorExplainToReadModel(op, subject.kind);
+                }
+            }
+            if (isAuditOnlySubjectKind(subject.kind)) {
+                return {
+                    subjectType: subject.kind,
+                    conclusion: auditStore ? "no_matching_audit_events" : "lived_experience_audit_store_unavailable",
+                    keyFactors: auditStore ? [] : ["configure_lived_experience_audit_store_for_operator_explain"],
+                    evidenceRefs: [],
+                };
+            }
             const query = subject.kind === "decision" || subject.kind === "platform-selection" || subject.kind === "outreach"
                 ? { decisionId: subject.id }
                 : { assetId: subject.id };

package/runtime/cli/read-models/operator-explain-map.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Maps T5.3.1 operator explain query results into CLI ExplainReadModel (T1.2.1).
+ */
+import type { OperatorExplainReadModel } from "../../observability/query/explain-query.js";
+import type { ExplainReadModel, ExplainSubjectKind } from "./types.js";
+export declare function mapOperatorExplainToReadModel(op: OperatorExplainReadModel, subjectKind: ExplainSubjectKind): ExplainReadModel;

package/runtime/cli/read-models/operator-explain-map.js

@@ -0,0 +1,10 @@
+export function mapOperatorExplainToReadModel(op, subjectKind) {
+    return {
+        subjectType: subjectKind,
+        conclusion: op.summary,
+        keyFactors: op.events.map((e) => `${e.eventId}:${e.summary}`),
+        evidenceRefs: op.relatedEventIds.map((id) => `audit_event:${id}`),
+        warnings: op.warnings.length ? op.warnings : undefined,
+        relatedAuditEventIds: op.relatedEventIds.length ? op.relatedEventIds : undefined,
+    };
+}

package/runtime/cli/read-models/types.d.ts

@@ -64,12 +64,16 @@ export interface CredentialReadModel {
     attemptsRemaining?: number;
     nextStep?: string;
 }
+export type ExplainSubjectKind = "decision" | "platform-selection" | "outreach" | "soul-change" | "fallback" | "probe" | "delivery" | "report" | "source_ref";
 export interface ExplainReadModel {
-    subjectType: "decision" | "platform-selection" | "outreach" | "soul-change";
+    subjectType: ExplainSubjectKind;
     conclusion: string;
     keyFactors: string[];
     evidenceRefs: string[];
     policyRefs?: string[];
     requiredUserInput?: string[];
     nextStep?: string;
+    /** Operator / lived-experience audit warnings (e.g. no user-visible contact) */
+    warnings?: string[];
+    relatedAuditEventIds?: string[];
 }

package/runtime/cli/runtime/runtime-artifact-boundary.d.ts

@@ -0,0 +1,28 @@
+export type SurfaceMode = "host_safe_carrier" | "workspace_full_runtime" | "capability_probe";
+export type RuntimeArtifactModule = "runtime_registration" | "ops_router" | "heartbeat_bridge_adapter" | "host_capability_adapter" | "probe_runner" | "read_model_adapter" | "fallback_shell";
+export interface RuntimeArtifactBoundary {
+    surfaceMode: SurfaceMode;
+    includes: RuntimeArtifactModule[];
+    fallbackAllowed: boolean;
+    sourcePathDependencyAllowed: false;
+}
+export type ResolvePackagedRuntimeResult = {
+    ok: true;
+    runtimeRoot: string;
+    boundary: RuntimeArtifactBoundary;
+    resolvedModules: Partial<Record<RuntimeArtifactModule, string>>;
+} | {
+    ok: false;
+    code: "runtime_artifact_missing" | "runtime_layout_incomplete";
+    message: string;
+    runtimeRoot: string;
+    missingPaths: string[];
+};
+/** Relative paths under `plugin/runtime/` that the packaging script must copy. */
+export declare const PACKAGED_RUNTIME_REQUIRED_ENTRIES: readonly string[];
+export declare function detectForbiddenSourcePathDependencies(sourceText: string): string[];
+export declare function defaultRuntimeArtifactBoundary(surfaceMode?: SurfaceMode): RuntimeArtifactBoundary;
+/**
+ * Verify packaged plugin `runtime/` tree and entrypoints required for ADR-006 closure.
+ */
+export declare function resolvePackagedRuntime(packageRoot: string): ResolvePackagedRuntimeResult;

package/runtime/cli/runtime/runtime-artifact-boundary.js

@@ -0,0 +1,94 @@
+/**
+ * Packaged runtime artifact boundary (cli-system / ADR-006).
+ *
+ * Core logic: resolve plugin-local `runtime/` layout produced by build-plugin-package;
+ * forbid dev-only imports that reach repo `src/` from published surfaces.
+ *
+ * Boundaries: filesystem checks only; does not execute host loaders.
+ *
+ * Test coverage: tests/unit/cli/runtime-artifact-boundary.test.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Relative paths under `plugin/runtime/` that the packaging script must copy. */
+export const PACKAGED_RUNTIME_REQUIRED_ENTRIES = [
+    "cli/index.js",
+    "storage/index.js",
+    "observability/index.js",
+    "core/second-nature/index.js",
+    "core/second-nature/runtime/service-entry.js",
+    "guidance/index.js",
+    "connectors/index.js",
+    "shared/types/index.js",
+];
+const DEFAULT_INCLUDES = [
+    "runtime_registration",
+    "ops_router",
+    "heartbeat_bridge_adapter",
+    "read_model_adapter",
+    "fallback_shell",
+];
+const SOURCE_REPO_PATH_PATTERN = /(?:from\s+["']|import\s+["']|require\s*\(\s*["'])(?:\.\.\/)+src\//i;
+export function detectForbiddenSourcePathDependencies(sourceText) {
+    const hits = [];
+    const lines = sourceText.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (SOURCE_REPO_PATH_PATTERN.test(line)) {
+            hits.push(`line ${i + 1}: ${line.trim()}`);
+        }
+    }
+    return hits;
+}
+export function defaultRuntimeArtifactBoundary(surfaceMode = "workspace_full_runtime") {
+    return {
+        surfaceMode,
+        includes: [...DEFAULT_INCLUDES],
+        fallbackAllowed: true,
+        sourcePathDependencyAllowed: false,
+    };
+}
+/**
+ * Verify packaged plugin `runtime/` tree and entrypoints required for ADR-006 closure.
+ */
+export function resolvePackagedRuntime(packageRoot) {
+    const runtimeRoot = path.join(packageRoot, "runtime");
+    if (!fs.existsSync(runtimeRoot) || !fs.statSync(runtimeRoot).isDirectory()) {
+        return {
+            ok: false,
+            code: "runtime_artifact_missing",
+            message: `runtime directory missing under ${packageRoot}`,
+            runtimeRoot,
+            missingPaths: [runtimeRoot],
+        };
+    }
+    const missingPaths = [];
+    for (const rel of PACKAGED_RUNTIME_REQUIRED_ENTRIES) {
+        const abs = path.join(runtimeRoot, rel);
+        if (!fs.existsSync(abs)) {
+            missingPaths.push(abs);
+        }
+    }
+    if (missingPaths.length > 0) {
+        return {
+            ok: false,
+            code: "runtime_layout_incomplete",
+            message: "packaged runtime is missing one or more required compiled modules",
+            runtimeRoot,
+            missingPaths,
+        };
+    }
+    const resolvedModules = {
+        ops_router: path.join(runtimeRoot, "cli/index.js"),
+        runtime_registration: path.join(runtimeRoot, "core/second-nature/runtime/service-entry.js"),
+        heartbeat_bridge_adapter: path.join(runtimeRoot, "core/second-nature/heartbeat/index.js"),
+        read_model_adapter: path.join(runtimeRoot, "cli/read-models/index.js"),
+        fallback_shell: path.join(runtimeRoot, "cli/index.js"),
+    };
+    return {
+        ok: true,
+        runtimeRoot,
+        boundary: defaultRuntimeArtifactBoundary(),
+        resolvedModules,
+    };
+}

package/runtime/connectors/base/contract.d.ts

@@ -20,6 +20,8 @@ export interface ExecutionPlan {
     channel: ChannelType;
     endpointMode: "rest_json" | "a2a_envelope" | "cli_stdout" | "skill_call";
     idempotencyKey?: string;
+    /** True when selected channel is manifest-marked degraded (cli/skill/browser). */
+    degraded?: boolean;
 }
 export interface ConnectorResult<T> {
     status: "success" | "retryable_failure" | "terminal_failure";
@@ -59,6 +61,10 @@ export interface ConnectorManifestLike {
     channelPriority: ChannelType[];
     credentialTypes: string[];
     degradedChannels?: ChannelType[];
+    sourceRefPolicy?: {
+        minSourceRefs?: number;
+        rejectInlineSensitivePayload?: boolean;
+    };
 }
 export interface ConnectorManifestLoader {
     loadManifest(platformId: string): ConnectorManifestLike;

package/runtime/connectors/base/execution-policy.d.ts

@@ -0,0 +1,47 @@
+import type { CapabilityIntent, ConnectorRequest, ExecutionPlan } from "./contract.js";
+export type EffectSemanticsClass = "read_only" | "side_effect" | "task_claim" | "keepalive";
+export declare function classifyConnectorIntentEffect(intent: CapabilityIntent): EffectSemanticsClass;
+export interface EffectCommitLedgerPort {
+    getOrCreateIntentCommitRecord(input: {
+        decisionId: string;
+        intentId: string;
+        idempotencyKey: string;
+        effectClass: string;
+    }): Promise<{
+        existing: boolean;
+        record: {
+            id: string;
+            state: string;
+            outcomeRef?: string;
+        };
+    }>;
+}
+/** In-memory ledger for tests and offline harnesses. */
+export declare class InMemoryEffectCommitLedger implements EffectCommitLedgerPort {
+    private readonly byKey;
+    private key;
+    getOrCreateIntentCommitRecord(input: {
+        decisionId: string;
+        intentId: string;
+        idempotencyKey: string;
+        effectClass: string;
+    }): Promise<{
+        existing: boolean;
+        record: {
+            id: string;
+            state: string;
+            outcomeRef?: string;
+        };
+    }>;
+    /** Test seam: mark a key as already committed with replayable outcome. */
+    seedCommitted(decisionId: string, idempotencyKey: string, outcomeRef: string): void;
+    markState(decisionId: string, idempotencyKey: string, state: string): void;
+}
+export interface EnforceExecutionPolicyDeps {
+    effectCommitLedger?: EffectCommitLedgerPort;
+}
+export declare function enforceExecutionPolicy(plan: ExecutionPlan, intent: CapabilityIntent, request: ConnectorRequest, deps: EnforceExecutionPolicyDeps): Promise<{
+    skipAdapter: boolean;
+    existingOutcomeRef?: string;
+    effectCommitId?: string;
+}>;

package/runtime/connectors/base/execution-policy.js

@@ -0,0 +1,82 @@
+/**
+ * Side-effect idempotency + degraded-channel gate + effect commit replay (T3.2.1).
+ * Aligns with connector-system.detail §3.6 enforceExecutionPolicy.
+ */
+import * as crypto from "node:crypto";
+import { ConnectorPolicyError } from "./failure-taxonomy.js";
+const READONLY = new Set([
+    "feed.read",
+    "notification.list",
+    "work.discover",
+]);
+export function classifyConnectorIntentEffect(intent) {
+    if (intent === "agent.heartbeat")
+        return "keepalive";
+    if (intent === "task.claim")
+        return "task_claim";
+    if (READONLY.has(intent))
+        return "read_only";
+    return "side_effect";
+}
+/** In-memory ledger for tests and offline harnesses. */
+export class InMemoryEffectCommitLedger {
+    byKey = new Map();
+    key(decisionId, idempotencyKey) {
+        return `${decisionId}::${idempotencyKey}`;
+    }
+    async getOrCreateIntentCommitRecord(input) {
+        const k = this.key(input.decisionId, input.idempotencyKey);
+        const hit = this.byKey.get(k);
+        if (hit) {
+            return { existing: true, record: hit };
+        }
+        const id = crypto.randomUUID();
+        const rec = { id, state: "planned", outcomeRef: undefined };
+        this.byKey.set(k, rec);
+        return { existing: false, record: rec };
+    }
+    /** Test seam: mark a key as already committed with replayable outcome. */
+    seedCommitted(decisionId, idempotencyKey, outcomeRef) {
+        const id = crypto.randomUUID();
+        this.byKey.set(this.key(decisionId, idempotencyKey), { id, state: "committed", outcomeRef });
+    }
+    markState(decisionId, idempotencyKey, state) {
+        const k = this.key(decisionId, idempotencyKey);
+        const cur = this.byKey.get(k);
+        if (!cur)
+            throw new Error("ledger_seed_missing");
+        this.byKey.set(k, { ...cur, state });
+    }
+}
+export async function enforceExecutionPolicy(plan, intent, request, deps) {
+    const semantics = classifyConnectorIntentEffect(intent);
+    if ((semantics === "side_effect" || semantics === "task_claim") && !plan.idempotencyKey?.trim()) {
+        throw new ConnectorPolicyError("permanent_input_error", "side_effect_requires_idempotency_key");
+    }
+    if (plan.degraded && (semantics === "side_effect" || semantics === "task_claim")) {
+        throw new ConnectorPolicyError("semantic_rejection", "degraded_channel_not_allowed_for_side_effect");
+    }
+    if (plan.idempotencyKey && deps.effectCommitLedger) {
+        if (!request.decisionId?.trim() || !request.intentId?.trim()) {
+            throw new ConnectorPolicyError("permanent_input_error", "effect_commit_requires_decision_and_intent_id");
+        }
+        const lookup = await deps.effectCommitLedger.getOrCreateIntentCommitRecord({
+            decisionId: request.decisionId,
+            intentId: request.intentId,
+            idempotencyKey: plan.idempotencyKey,
+            effectClass: semantics,
+        });
+        if (lookup.existing && lookup.record.state === "committed") {
+            return {
+                skipAdapter: true,
+                existingOutcomeRef: lookup.record.outcomeRef,
+                effectCommitId: lookup.record.id,
+            };
+        }
+        if (lookup.existing && (lookup.record.state === "dispatched" || lookup.record.state === "reconcile")) {
+            throw new ConnectorPolicyError("concurrency_conflict", "effect_commit_requires_reconcile");
+        }
+        return { skipAdapter: false, effectCommitId: lookup.record.id };
+    }
+    return { skipAdapter: false };
+}

package/runtime/connectors/base/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./contract.js";
 export * from "./manifest.js";
+export * from "./map-life-evidence.js";
 export * from "./failure-taxonomy.js";
 export * from "./route-planner.js";
 export * from "./channel-health.js";
 export * from "./policy-layer.js";
+export * from "./execution-policy.js";

package/runtime/connectors/base/index.js

@@ -1,6 +1,8 @@
 export * from "./contract.js";
 export * from "./manifest.js";
+export * from "./map-life-evidence.js";
 export * from "./failure-taxonomy.js";
 export * from "./route-planner.js";
 export * from "./channel-health.js";
 export * from "./policy-layer.js";
+export * from "./execution-policy.js";