@haaaiawd/second-nature 0.1.8 → 0.1.9

package/runtime/cli/ops/heartbeat-surface.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stable HeartbeatSurfaceResult for second_nature_ops / CLI (T1.1.3, cli-system / ADR-005).
+ *
+ * S1 scope: carrier / probe / runtime-unavailable / fake control-plane passthrough only.
+ * Workspace full runtime: delegates to `runHeartbeatCycle` when read models are wired (US-001 / CH-09-02).
+ */
+import type { SurfaceMode } from "../runtime/runtime-artifact-boundary.js";
+import type { HeartbeatSignal } from "../../core/second-nature/heartbeat/signal.js";
+import type { CliReadModels } from "../read-models/index.js";
+export type HeartbeatSurfaceStatus = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
+export interface HeartbeatSurfaceResult {
+    ok: boolean;
+    status: HeartbeatSurfaceStatus;
+    surfaceMode: SurfaceMode;
+    decisionId?: string;
+    deliveryAttemptId?: string;
+    capabilityReportRef?: string;
+    fallbackRef?: string;
+    reasons: string[];
+    /** When false, callers must not treat the round as lived-experience loop completion */
+    livedExperienceLoopClaimed: boolean;
+    /** True when structured fields mirror a fake adapter for schema parity only */
+    schemaParityOnly?: boolean;
+}
+export interface HeartbeatCheckInput {
+    probeOnly?: boolean;
+    runtimeAvailable: boolean;
+    fakeControlPlanePassthrough?: Record<string, unknown>;
+    /** When set, full-runtime heartbeat_check runs the control-plane decision loop (US-001). */
+    readModels?: CliReadModels;
+    timestamp?: string;
+    sessionContext?: string;
+    scopeHint?: HeartbeatSignal["scopeHint"];
+}
+export declare function heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;

package/runtime/cli/ops/heartbeat-surface.js

@@ -0,0 +1,71 @@
+import { createWorkspaceHeartbeatRunner } from "./workspace-heartbeat-runner.js";
+function mapCycleToSurface(cycle, surfaceMode) {
+    const status = cycle.status === "runtime_carrier_only" ? "runtime_carrier_only" : cycle.status;
+    return {
+        ok: true,
+        status,
+        surfaceMode,
+        decisionId: cycle.decisionId,
+        deliveryAttemptId: cycle.deliveryAttemptId,
+        fallbackRef: cycle.fallbackRef,
+        reasons: cycle.reasons,
+        livedExperienceLoopClaimed: false,
+    };
+}
+export async function heartbeatCheck(input) {
+    if (!input.runtimeAvailable) {
+        return {
+            ok: true,
+            status: "runtime_carrier_only",
+            surfaceMode: "host_safe_carrier",
+            reasons: ["runtime_unavailable_packaged_carrier"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    if (input.probeOnly) {
+        return {
+            ok: true,
+            status: "heartbeat_ok",
+            surfaceMode: "capability_probe",
+            reasons: ["probe_only"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    if (input.fakeControlPlanePassthrough) {
+        const decisionId = typeof input.fakeControlPlanePassthrough.decisionId === "string"
+            ? input.fakeControlPlanePassthrough.decisionId
+            : undefined;
+        return {
+            ok: true,
+            status: "intent_selected",
+            surfaceMode: "host_safe_carrier",
+            reasons: ["fake_control_plane_passthrough"],
+            decisionId,
+            livedExperienceLoopClaimed: false,
+            schemaParityOnly: true,
+        };
+    }
+    if (!input.readModels) {
+        return {
+            ok: true,
+            status: "heartbeat_ok",
+            surfaceMode: "workspace_full_runtime",
+            reasons: ["heartbeat_read_models_unavailable"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    const timestamp = typeof input.timestamp === "string" && input.timestamp.trim().length > 0
+        ? input.timestamp.trim()
+        : new Date().toISOString();
+    const signal = {
+        trigger: "heartbeat_bridge",
+        scopeHint: input.scopeHint,
+        payload: {
+            timestamp,
+            sessionContext: typeof input.sessionContext === "string" ? input.sessionContext : undefined,
+        },
+    };
+    const run = createWorkspaceHeartbeatRunner(input.readModels);
+    const cycle = await run(signal);
+    return mapCycleToSurface(cycle, "workspace_full_runtime");
+}

package/runtime/cli/ops/ops-router.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared ops command dispatch for CLI + tool surfaces (T1.1.3, T1.2.2).
+ */
+import { type HeartbeatCheckInput, type HeartbeatSurfaceResult } from "./heartbeat-surface.js";
+import type { CliReadModels } from "../read-models/index.js";
+export interface OpsRouterDeps {
+    /** When true, packaged runtime artifacts resolved and full graph is loadable */
+    runtimeAvailable: boolean;
+    /** Workspace read models: fallback view + heartbeat decision loop inputs (T1.2.2 / US-001). */
+    readModels?: CliReadModels;
+}
+export interface OpsRouter {
+    heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;
+    dispatch(command: string, input?: Record<string, unknown>): HeartbeatSurfaceResult | Record<string, unknown> | Promise<HeartbeatSurfaceResult> | Promise<Record<string, unknown>>;
+}
+export declare function createOpsRouter(deps: OpsRouterDeps): OpsRouter;

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