@haaaiawd/second-nature 0.1.27 → 0.1.29

package/runtime/core/second-nature/body/probe-signal-adapter.js

@@ -0,0 +1,60 @@
+/**
+ * ProbeSignalAdapter — T-BTS.C.4
+ *
+ * Core logic: Bridge between WetProbeRunner and state-memory.
+ * 1. Runs a wet probe for a capability.
+ * 2. Persists the CapabilityProbeResult to state-memory.
+ * 3. If the probe indicates degradation/unavailability, records a
+ *    corresponding ToolExperience row with triggerSource="probe".
+ *
+ * Dependencies:
+ * - `WetProbeRunner` from `../../../connectors/base/wet-probe-runner.js`
+ * - `CapabilityContractRegistryV7` from `../../../connectors/base/manifest-v7.js`
+ * - `CapabilityProbeResultStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ToolExperienceStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ExperienceWriter` from `./tool-experience/experience-writer.js`
+ *
+ * Boundary:
+ * - Does NOT modify breaker state — caller (CircuitBreakerManager) decides.
+ * - probePolicyDenied is treated as a valid result, not an error.
+ *
+ * Test coverage: tests/unit/body/probe-signal-adapter.test.ts
+ */
+import { createExperienceWriter } from "./tool-experience/experience-writer.js";
+export function createProbeSignalAdapter(deps) {
+    const { wetProbeRunner, probeResultStore, toolExperienceStore } = deps;
+    const experienceWriter = createExperienceWriter(toolExperienceStore);
+    return {
+        async runAndRecordProbe(platformId, capabilityId, registry) {
+            const result = await wetProbeRunner.runWetProbe(platformId, capabilityId, registry);
+            // Persist probe result
+            await probeResultStore.appendProbeResult(result.probeResult);
+            // Record experience for non-success probes
+            let experienceRecorded = false;
+            if (result.probeResult.actualStatus !== "available") {
+                const mockResult = {
+                    status: "terminal_failure",
+                    failureClass: "transport_failure",
+                    metadata: {
+                        platformId,
+                        channel: "api_rest",
+                        latencyMs: 0,
+                    },
+                };
+                await experienceWriter.recordExperience({
+                    connectorId: platformId,
+                    capabilityId,
+                    result: mockResult,
+                    triggerSource: "probe",
+                });
+                experienceRecorded = true;
+            }
+            return {
+                actualStatus: result.probeResult.actualStatus,
+                httpStatus: result.httpStatus,
+                recorded: true,
+                experienceRecorded,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * AffordanceAssembler — T-BTS.C.1
+ *
+ * Core logic: Assemble a platform→capability affordance map from the v7
+ * capability registry and recent probe results.
+ *
+ * Mapping rules (probe actualStatus → affordance status):
+ * - available  → safe
+ * - degraded   → exploratory
+ * - unavailable → unavailable
+ * - no probe + credential required → needs_auth
+ * - no probe + no credential required → unavailable
+ *
+ * Caching:
+ * - TTL cache (default 30s) keyed by serialized scope.
+ * - Invalidate on explicit call or when underlying data changes.
+ *
+ * Performance target: P95 < 1s for 50 manifests.
+ *
+ * Dependencies:
+ * - `CapabilityContractRegistryV7` from `../../../../connectors/base/manifest-v7.js`
+ * - `AffordanceItem`, `AffordanceMap`, `AffordanceContextScope`
+ *   from `../../../../shared/types/v7-entities.js`
+ * - `applyAffordanceContextScope` from `./affordance-context-scope.js`
+ *
+ * Boundary:
+ * - Does NOT perform HTTP probes — reads cached probe results only.
+ * - Credential-bearing entries are excluded (ADR-003).
+ * - Returns a plain object; caller decides persistence.
+ *
+ * Test coverage: tests/unit/body/affordance-assembler.test.ts
+ */
+import type { CapabilityContractRegistryV7 } from "../../../../connectors/base/manifest-v7.js";
+import type { AffordanceMap, AffordanceContextScope, ProbeActualStatus } from "../../../../shared/types/v7-entities.js";
+export interface ProbeResultReader {
+    getLatestProbeResult(platformId: string, capabilityId: string): {
+        actualStatus: ProbeActualStatus;
+        createdAt: string;
+    } | undefined;
+}
+export interface AffordanceAssembler {
+    assembleAffordanceMap(scope?: AffordanceContextScope): Promise<AffordanceMap>;
+    invalidateCache(): void;
+}
+export interface AffordanceAssemblerOptions {
+    registry: CapabilityContractRegistryV7;
+    probeReader: ProbeResultReader;
+    credentialRequired?: (platformId: string, capabilityId: string) => boolean;
+    ttlMs?: number;
+}
+export declare function createAffordanceAssembler(options: AffordanceAssemblerOptions): AffordanceAssembler;

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

@@ -0,0 +1,129 @@
+/**
+ * AffordanceAssembler — T-BTS.C.1
+ *
+ * Core logic: Assemble a platform→capability affordance map from the v7
+ * capability registry and recent probe results.
+ *
+ * Mapping rules (probe actualStatus → affordance status):
+ * - available  → safe
+ * - degraded   → exploratory
+ * - unavailable → unavailable
+ * - no probe + credential required → needs_auth
+ * - no probe + no credential required → unavailable
+ *
+ * Caching:
+ * - TTL cache (default 30s) keyed by serialized scope.
+ * - Invalidate on explicit call or when underlying data changes.
+ *
+ * Performance target: P95 < 1s for 50 manifests.
+ *
+ * Dependencies:
+ * - `CapabilityContractRegistryV7` from `../../../../connectors/base/manifest-v7.js`
+ * - `AffordanceItem`, `AffordanceMap`, `AffordanceContextScope`
+ *   from `../../../../shared/types/v7-entities.js`
+ * - `applyAffordanceContextScope` from `./affordance-context-scope.js`
+ *
+ * Boundary:
+ * - Does NOT perform HTTP probes — reads cached probe results only.
+ * - Credential-bearing entries are excluded (ADR-003).
+ * - Returns a plain object; caller decides persistence.
+ *
+ * Test coverage: tests/unit/body/affordance-assembler.test.ts
+ */
+import { applyAffordanceContextScope } from "./affordance-context-scope.js";
+function statusFromProbe(probeStatus) {
+    switch (probeStatus) {
+        case "available":
+            return "safe";
+        case "degraded":
+            return "exploratory";
+        case "unavailable":
+            return "unavailable";
+        default:
+            return "unavailable";
+    }
+}
+function scopeKey(scope) {
+    return JSON.stringify([
+        scope.platformIds?.sort() ?? [],
+        scope.goalKind ?? "",
+        scope.allowedStatuses?.sort() ?? [],
+    ]);
+}
+export function createAffordanceAssembler(options) {
+    const { registry, probeReader, credentialRequired, ttlMs = 30_000, } = options;
+    let cache;
+    function buildRawMap() {
+        const map = {};
+        for (const platformId of registry.listRegisteredPlatformIds()) {
+            const caps = registry.listCapabilities(platformId);
+            const items = [];
+            for (const cap of caps) {
+                const probe = probeReader.getLatestProbeResult(platformId, cap.capabilityId);
+                let status;
+                let reason;
+                let lastProbedAt;
+                if (probe) {
+                    status = statusFromProbe(probe.actualStatus);
+                    lastProbedAt = probe.createdAt;
+                    if (status === "unavailable") {
+                        reason = `probe_unavailable:${cap.capabilityId}`;
+                    }
+                }
+                else {
+                    const needsCred = credentialRequired?.(platformId, cap.capabilityId) ?? true;
+                    if (needsCred) {
+                        status = "needs_auth";
+                        reason = "credential_not_probed";
+                    }
+                    else {
+                        status = "unavailable";
+                        reason = "no_probe_result";
+                    }
+                }
+                items.push({
+                    platformId,
+                    capabilityId: cap.capabilityId,
+                    intent: cap.intent,
+                    status,
+                    reason,
+                    lastProbedAt,
+                });
+            }
+            if (items.length > 0) {
+                map[platformId] = items;
+            }
+        }
+        return map;
+    }
+    return {
+        async assembleAffordanceMap(scope = {}) {
+            const key = scopeKey(scope);
+            const now = Date.now();
+            if (cache && cache.key === key && now - cache.cachedAt < ttlMs) {
+                // Re-apply scope filter on cached raw map (scope may change)
+                const filtered = {};
+                for (const [pid, items] of Object.entries(cache.map)) {
+                    const scoped = applyAffordanceContextScope(items, scope);
+                    if (scoped.length > 0) {
+                        filtered[pid] = scoped;
+                    }
+                }
+                return filtered;
+            }
+            const raw = buildRawMap();
+            cache = { key, map: raw, cachedAt: now };
+            const filtered = {};
+            for (const [pid, items] of Object.entries(raw)) {
+                const scoped = applyAffordanceContextScope(items, scope);
+                if (scoped.length > 0) {
+                    filtered[pid] = scoped;
+                }
+            }
+            return filtered;
+        },
+        invalidateCache() {
+            cache = undefined;
+        },
+    };
+}

package/runtime/core/second-nature/body/tool-affordance/affordance-context-scope.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AffordanceContextScope — T-BTS.C.2
+ *
+ * Core logic: Filter semantics for affordance map assembly.
+ * - platformIds whitelist (empty = all platforms)
+ * - goalKind trust-tier filtering (task_completion prefers write/claim;
+ *   passive_sensing exposes only read-only)
+ * - allowedStatuses defaults to safe subset; blocked/pending_trust always excluded
+ * - Credential-bearing items never enter affordance (ADR-003)
+ *
+ * Dependencies:
+ * - `AffordanceItem`, `AffordanceContextScope` from `../../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Pure filter function; no side effects, no caching.
+ * - Does NOT map probe status to affordance status — that is the assembler's job.
+ *
+ * Test coverage: tests/unit/body/affordance-context-scope.test.ts
+ */
+import type { AffordanceItem, AffordanceContextScope, AffordanceStatus } from "../../../../shared/types/v7-entities.js";
+export declare const DEFAULT_ALLOWED_STATUSES: readonly AffordanceStatus[];
+/**
+ * Apply context scope filtering to an affordance item list.
+ * Returns a new array; does not mutate input.
+ */
+export declare function applyAffordanceContextScope(items: readonly AffordanceItem[], scope?: AffordanceContextScope): AffordanceItem[];
+/**
+ * Build a default scope suitable for heartbeat-cycle affordance assembly.
+ */
+export declare function defaultHeartbeatScope(): AffordanceContextScope;

package/runtime/core/second-nature/body/tool-affordance/affordance-context-scope.js

@@ -0,0 +1,92 @@
+/**
+ * AffordanceContextScope — T-BTS.C.2
+ *
+ * Core logic: Filter semantics for affordance map assembly.
+ * - platformIds whitelist (empty = all platforms)
+ * - goalKind trust-tier filtering (task_completion prefers write/claim;
+ *   passive_sensing exposes only read-only)
+ * - allowedStatuses defaults to safe subset; blocked/pending_trust always excluded
+ * - Credential-bearing items never enter affordance (ADR-003)
+ *
+ * Dependencies:
+ * - `AffordanceItem`, `AffordanceContextScope` from `../../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Pure filter function; no side effects, no caching.
+ * - Does NOT map probe status to affordance status — that is the assembler's job.
+ *
+ * Test coverage: tests/unit/body/affordance-context-scope.test.ts
+ */
+export const DEFAULT_ALLOWED_STATUSES = [
+    "safe",
+    "exploratory",
+];
+const BLOCKED_STATUSES = [
+    "unavailable", // painful is allowed for diagnostics; unavailable is blocked from active use
+];
+const READ_ONLY_INTENTS = new Set([
+    "feed.read",
+    "notification.list",
+    "work.discover",
+]);
+const WRITE_INTENTS = new Set([
+    "post.publish",
+    "comment.reply",
+    "message.send",
+    "agent.register",
+    "agent.heartbeat",
+    "task.claim",
+]);
+function isReadOnlyIntent(intent) {
+    return READ_ONLY_INTENTS.has(intent);
+}
+function isWriteIntent(intent) {
+    return WRITE_INTENTS.has(intent);
+}
+/**
+ * Apply context scope filtering to an affordance item list.
+ * Returns a new array; does not mutate input.
+ */
+export function applyAffordanceContextScope(items, scope = {}) {
+    const allowedStatuses = scope.allowedStatuses && scope.allowedStatuses.length > 0
+        ? scope.allowedStatuses
+        : [...DEFAULT_ALLOWED_STATUSES];
+    // blocked/pending_trust always excluded at the status level
+    const effectiveAllowed = allowedStatuses.filter((s) => !BLOCKED_STATUSES.includes(s));
+    const platformSet = scope.platformIds && scope.platformIds.length > 0
+        ? new Set(scope.platformIds)
+        : undefined;
+    return items.filter((item) => {
+        // 1. Status filter
+        if (!effectiveAllowed.includes(item.status)) {
+            return false;
+        }
+        // 2. Platform whitelist
+        if (platformSet && !platformSet.has(item.platformId)) {
+            return false;
+        }
+        // 3. Goal-kind intent filtering
+        if (scope.goalKind) {
+            if (scope.goalKind === "passive_sensing") {
+                // Only read-only capabilities
+                if (!isReadOnlyIntent(item.intent)) {
+                    return false;
+                }
+            }
+            else if (scope.goalKind === "task_completion") {
+                // Prefer write/claim — but do not exclude read; just allow all
+                // (higher-level assembler may sort/prioritize)
+            }
+            // Other goalKinds: no additional intent filter
+        }
+        return true;
+    });
+}
+/**
+ * Build a default scope suitable for heartbeat-cycle affordance assembly.
+ */
+export function defaultHeartbeatScope() {
+    return {
+        allowedStatuses: [...DEFAULT_ALLOWED_STATUSES],
+    };
+}

package/runtime/core/second-nature/body/tool-experience/experience-writer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ExperienceWriter — T-BTS.C.4
+ *
+ * Core logic: Records connector execution results as ToolExperience rows.
+ * - triggerSource is mandatory (DR-010)
+ * - failureClass directly transcribed from ConnectorResult (DR-007)
+ * - WriteValidationGate rejects raw payload before append
+ * - outcome mapping: success → "success", retryable_failure → "failure",
+ *   terminal_failure → "failure"
+ *
+ * Dependencies:
+ * - `ToolExperienceStore` from `../../../../storage/services/tool-experience-store.js`
+ * - `validateWritePayload` from `../../../../storage/services/write-validation-gate.js`
+ * - `ConnectorResult` type from `../../../../connectors/base/contract.js`
+ *
+ * Boundary:
+ * - Does NOT probe; only records completed attempts.
+ * - Caller supplies triggerSource explicitly (no default).
+ *
+ * Test coverage: tests/unit/body/experience-writer.test.ts
+ */
+import type { ToolExperienceStore } from "../../../../storage/services/tool-experience-store.js";
+import type { ConnectorResult } from "../../../../connectors/base/contract.js";
+import type { ToolExperienceTriggerSource } from "../../../../shared/types/v7-entities.js";
+export interface ExperienceRecordInput {
+    connectorId: string;
+    capabilityId: string;
+    result: ConnectorResult<unknown>;
+    triggerSource: ToolExperienceTriggerSource;
+}
+export interface ExperienceWriter {
+    recordExperience(input: ExperienceRecordInput): Promise<void>;
+}
+export declare function createExperienceWriter(store: ToolExperienceStore): ExperienceWriter;

package/runtime/core/second-nature/body/tool-experience/experience-writer.js

@@ -0,0 +1,67 @@
+/**
+ * ExperienceWriter — T-BTS.C.4
+ *
+ * Core logic: Records connector execution results as ToolExperience rows.
+ * - triggerSource is mandatory (DR-010)
+ * - failureClass directly transcribed from ConnectorResult (DR-007)
+ * - WriteValidationGate rejects raw payload before append
+ * - outcome mapping: success → "success", retryable_failure → "failure",
+ *   terminal_failure → "failure"
+ *
+ * Dependencies:
+ * - `ToolExperienceStore` from `../../../../storage/services/tool-experience-store.js`
+ * - `validateWritePayload` from `../../../../storage/services/write-validation-gate.js`
+ * - `ConnectorResult` type from `../../../../connectors/base/contract.js`
+ *
+ * Boundary:
+ * - Does NOT probe; only records completed attempts.
+ * - Caller supplies triggerSource explicitly (no default).
+ *
+ * Test coverage: tests/unit/body/experience-writer.test.ts
+ */
+import { validateWritePayload } from "../../../../storage/services/write-validation-gate.js";
+import * as crypto from "node:crypto";
+function outcomeFromConnectorStatus(status) {
+    switch (status) {
+        case "success":
+            return "success";
+        case "retryable_failure":
+        case "terminal_failure":
+            return "failure";
+        default:
+            return "failure";
+    }
+}
+export function createExperienceWriter(store) {
+    return {
+        async recordExperience(input) {
+            const { result, connectorId, capabilityId, triggerSource } = input;
+            const payload = {
+                connectorId,
+                capabilityId,
+                status: result.status,
+                failureClass: result.failureClass,
+                latencyMs: result.metadata.latencyMs,
+                triggerSource,
+                sourceRefs: ["experience:record"],
+            };
+            const gate = validateWritePayload(payload);
+            if (!gate.ok) {
+                throw new Error(`ExperienceWriter rejected by gate: ${gate.reason}`);
+            }
+            const experience = {
+                experienceId: crypto.randomUUID(),
+                connectorId,
+                capabilityId,
+                outcome: outcomeFromConnectorStatus(result.status),
+                failureClass: result.failureClass,
+                latencyMs: result.metadata.latencyMs,
+                evidenceQuality: result.status === "success" ? 1.0 : 0.0,
+                sourceRefs: ["experience:record"],
+                triggerSource,
+                createdAt: new Date().toISOString(),
+            };
+            await store.appendToolExperience(experience);
+        },
+    };
+}

package/runtime/core/second-nature/body/tool-experience/pain-signal-query.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PainSignal query — T-BTS.C.4
+ *
+ * Core logic: Computes a bounded pain signal from recent ToolExperience rows.
+ * Does NOT expose raw payload. Returns aggregated metrics for affordance map
+ * and heartbeat guard consumption.
+ *
+ * Dependencies:
+ * - `ToolExperienceStore` from `../../../../storage/services/tool-experience-store.js`
+ * - `ToolExperience` from `../../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Read-only; no side effects.
+ * - Bounded to last N rows (default 10) to keep computation constant-time.
+ *
+ * Test coverage: tests/unit/body/pain-signal-query.test.ts
+ */
+import type { ToolExperienceStore } from "../../../../storage/services/tool-experience-store.js";
+export interface PainSignal {
+    connectorId: string;
+    capabilityId: string;
+    painLevel: number;
+    recentFailureRate: number;
+    consecutiveFailures: number;
+    cooldownRecommended: boolean;
+    lastOutcomes: Array<{
+        outcome: string;
+        createdAt: string;
+    }>;
+}
+export interface PainSignalQuery {
+    getPainSignal(connectorId: string, capabilityId?: string): Promise<PainSignal | undefined>;
+}
+export declare function createPainSignalQuery(store: ToolExperienceStore, options?: {
+    lookbackLimit?: number;
+    cooldownThreshold?: number;
+}): PainSignalQuery;

package/runtime/core/second-nature/body/tool-experience/pain-signal-query.js

@@ -0,0 +1,62 @@
+/**
+ * PainSignal query — T-BTS.C.4
+ *
+ * Core logic: Computes a bounded pain signal from recent ToolExperience rows.
+ * Does NOT expose raw payload. Returns aggregated metrics for affordance map
+ * and heartbeat guard consumption.
+ *
+ * Dependencies:
+ * - `ToolExperienceStore` from `../../../../storage/services/tool-experience-store.js`
+ * - `ToolExperience` from `../../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Read-only; no side effects.
+ * - Bounded to last N rows (default 10) to keep computation constant-time.
+ *
+ * Test coverage: tests/unit/body/pain-signal-query.test.ts
+ */
+export function createPainSignalQuery(store, options = {}) {
+    const lookbackLimit = options.lookbackLimit ?? 10;
+    const cooldownThreshold = options.cooldownThreshold ?? 3;
+    return {
+        async getPainSignal(connectorId, capabilityId) {
+            const rows = await store.listToolExperience({
+                connectorId,
+                capabilityId,
+                limit: lookbackLimit,
+            });
+            if (rows.length === 0) {
+                return undefined;
+            }
+            // Sort by createdAt ASC to compute consecutive failures correctly
+            const sorted = [...rows].sort((a, b) => new Date(a.createdAt).getTime() -
+                new Date(b.createdAt).getTime());
+            const failures = sorted.filter((r) => r.outcome === "failure" || r.outcome === "timeout");
+            const recentFailureRate = failures.length / sorted.length;
+            // Count trailing consecutive failures
+            let consecutiveFailures = 0;
+            for (let i = sorted.length - 1; i >= 0; i--) {
+                if (sorted[i].outcome === "failure" ||
+                    sorted[i].outcome === "timeout") {
+                    consecutiveFailures++;
+                }
+                else {
+                    break;
+                }
+            }
+            const painLevel = Math.min(1.0, recentFailureRate * 0.5 + consecutiveFailures * 0.15);
+            return {
+                connectorId,
+                capabilityId: capabilityId ?? "*",
+                painLevel,
+                recentFailureRate,
+                consecutiveFailures,
+                cooldownRecommended: consecutiveFailures >= cooldownThreshold,
+                lastOutcomes: sorted.slice(-5).map((r) => ({
+                    outcome: r.outcome,
+                    createdAt: r.createdAt,
+                })),
+            };
+        },
+    };
+}

package/runtime/core/second-nature/heartbeat/decision-trace-emitter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DecisionTraceEmitter — T-CP.C.2
+ *
+ * Core logic: Emits machine-readable DecisionTracePayload to observability.
+ * Trace persistence belongs to observability-health-system; this module only
+ * constructs and forwards the payload.
+ *
+ * Boundary:
+ * - Emission errors are swallowed — trace must not block heartbeat cycle.
+ * - No-op emitter available for carrier-only paths and tests.
+ *
+ * Test coverage: tests/unit/control-plane/decision-trace-emitter.test.ts
+ */
+export interface DecisionTracePayload {
+    traceId: string;
+    decisionId: string;
+    contextId?: string;
+    scope: string;
+    status: string;
+    reasons: string[];
+    selectedIntentId?: string;
+    emittedAt: string;
+}
+export interface DecisionTraceEmitter {
+    emit(trace: DecisionTracePayload): Promise<void>;
+}
+export declare function createDecisionTraceEmitter(port: (payload: DecisionTracePayload) => Promise<void>): DecisionTraceEmitter;
+/** No-op emitter for carrier-only or test paths. */
+export declare function createNoOpTraceEmitter(): DecisionTraceEmitter;

package/runtime/core/second-nature/heartbeat/decision-trace-emitter.js

@@ -0,0 +1,28 @@
+/**
+ * DecisionTraceEmitter — T-CP.C.2
+ *
+ * Core logic: Emits machine-readable DecisionTracePayload to observability.
+ * Trace persistence belongs to observability-health-system; this module only
+ * constructs and forwards the payload.
+ *
+ * Boundary:
+ * - Emission errors are swallowed — trace must not block heartbeat cycle.
+ * - No-op emitter available for carrier-only paths and tests.
+ *
+ * Test coverage: tests/unit/control-plane/decision-trace-emitter.test.ts
+ */
+export function createDecisionTraceEmitter(port) {
+    return {
+        async emit(trace) {
+            await port(trace);
+        },
+    };
+}
+/** No-op emitter for carrier-only or test paths. */
+export function createNoOpTraceEmitter() {
+    return {
+        async emit() {
+            // intentionally empty
+        },
+    };
+}

package/runtime/core/second-nature/heartbeat/embodied-context-assembler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * EmbodiedContextAssembler — T-CP.C.1
+ *
+ * Core logic: Assembles a complete EmbodiedContext from up to 7 read ports:
+ * - 5 state-memory slices via EmbodiedContextStatePort
+ * - affordanceMap via AffordanceAssembler
+ * - selfHealth via SelfHealthProvider (observability hook)
+ *
+ * Trim policies (DR-020):
+ * - recentInteractions: LIFO 10
+ * - toolExperience: LIFO 10
+ * - sourceRefs: deduplicated to 20 per slice
+ *
+ * Performance: P95 < 400ms for full assembly (DR-016).
+ *
+ * Dependencies:
+ * - `EmbodiedContextStatePort` from `../../../storage/services/embodied-context-state-port.js`
+ * - `AffordanceAssembler` from `../body/tool-affordance/affordance-assembler.js`
+ * - `EmbodiedContext` from `../../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - Candidate dream outputs are NOT included (DR-011).
+ * - Each slice gets its own loaded/degraded/blocked status.
+ * - Does NOT throw on partial failure; assembles best-effort context.
+ *
+ * Test coverage: tests/unit/control-plane/embodied-context-assembler.test.ts
+ */
+import type { EmbodiedContextStatePort } from "../../../storage/services/embodied-context-state-port.js";
+import type { AffordanceAssembler } from "../body/tool-affordance/affordance-assembler.js";
+import type { EmbodiedContext, SelfHealthSnapshot } from "../../../shared/types/v7-entities.js";
+export interface SelfHealthProvider {
+    loadSelfHealth(): Promise<{
+        status: "loaded";
+        data: SelfHealthSnapshot;
+    } | {
+        status: "degraded";
+        reason: string;
+    }>;
+}
+export interface EmbodiedContextAssemblerDeps {
+    statePort: EmbodiedContextStatePort;
+    affordanceAssembler: AffordanceAssembler;
+    selfHealthProvider?: SelfHealthProvider;
+    options?: {
+        interactionLimit?: number;
+        experienceLimit?: number;
+        sourceRefLimit?: number;
+        profileId?: string;
+    };
+}
+export interface EmbodiedContextAssembler {
+    assembleEmbodiedContext(): Promise<EmbodiedContext>;
+}
+export declare function createEmbodiedContextAssembler(deps: EmbodiedContextAssemblerDeps): EmbodiedContextAssembler;