@haaaiawd/second-nature 0.1.51 → 0.2.0

package/runtime/core/second-nature/orchestrator/platform-capability-router.js

@@ -1,149 +1,149 @@
-function kindToCapability(kind) {
-    if (kind === "exploration")
-        return "feed.read";
-    if (kind === "social")
-        return "comment.reply";
-    if (kind === "work")
-        return "work.discover";
-    if (kind === "outreach")
-        return "message.send";
-    return null;
-}
-function getPlatformIds(registry) {
-    if (registry) {
-        return registry.listRegisteredPlatformIds();
-    }
-    // Fallback: built-in platforms when registry is absent (backward compat)
-    return ["moltbook", "instreet", "evomap", "agent-world"];
-}
-const FALLBACK_PLATFORM_CAPABILITIES = {
-    "moltbook": ["feed.read", "post.publish", "comment.reply", "message.send"],
-    "instreet": ["notification.list", "message.send", "comment.reply", "agent.heartbeat"],
-    "evomap": ["agent.register", "agent.heartbeat", "work.discover", "task.claim"],
-    "agent-world": ["feed.read", "work.discover", "task.claim"],
-};
-function fallbackPlatformSupportsCapability(platformId, kind) {
-    const capability = kindToCapability(kind);
-    if (!capability)
-        return false;
-    return (FALLBACK_PLATFORM_CAPABILITIES[platformId] ?? []).includes(capability);
-}
-function extractPlatformIdsFromGoals(goals, kind, platformIds) {
-    const capability = kindToCapability(kind);
-    const results = new Set();
-    for (const goal of goals) {
-        const text = `${goal.description} ${goal.completionCriteria ?? ""}`.toLowerCase();
-        for (const pid of platformIds) {
-            if (text.includes(pid)) {
-                results.add(pid);
-            }
-        }
-        // Also match if goal text contains the capability name (e.g. "feed.read")
-        if (capability && text.includes(capability.toLowerCase())) {
-            // capability alone doesn't tell us platform; keep for later
-        }
-    }
-    return [...results];
-}
-function extractPlatformIdsFromEvidence(refs, platformIds) {
-    const results = new Set();
-    for (const ref of refs) {
-        if (ref.kind === "connector_result" && ref.id) {
-            for (const pid of platformIds) {
-                if (ref.id.includes(pid)) {
-                    results.add(pid);
-                }
-            }
-        }
-        // Parse platform:// URIs (e.g. platform://moltbook/feed.read)
-        if (ref.uri && ref.uri.startsWith("platform://")) {
-            const afterScheme = ref.uri.slice("platform://".length);
-            const platformPart = afterScheme.split("/")[0];
-            if (platformPart && platformIds.includes(platformPart)) {
-                results.add(platformPart);
-            }
-        }
-        // L-02: Also support namespace format moltbook:feed.read (connector-system §5.3)
-        if (ref.uri && !ref.uri.includes("://") && ref.uri.includes(":")) {
-            const nsPart = ref.uri.split(":")[0];
-            if (nsPart && platformIds.includes(nsPart)) {
-                results.add(nsPart);
-            }
-        }
-    }
-    return [...results];
-}
-function validatePlatformCapability(platformId, kind, registry) {
-    const capability = kindToCapability(kind);
-    if (!capability)
-        return false;
-    try {
-        return registry.hasCapability(platformId, capability);
-    }
-    catch (err) {
-        // H-08: Log registry validation failures for observability.
-        console.warn(`[platform-capability-router] Registry validation failed for ${platformId}:${capability}`, err);
-        return false;
-    }
-}
-/**
- * Resolve an explicit platformId for a candidate intent kind.
- * Returns `undefined` when no unambiguous platform can be inferred.
- */
-export function resolvePlatformForIntent(kind, context, registry) {
-    const capability = kindToCapability(kind);
-    if (!capability) {
-        // Quiet, reflection, maintenance have no connector capability mapping.
-        return undefined;
-    }
-    const platformIds = getPlatformIds(registry);
-    const candidates = [];
-    if (context.acceptedGoals && context.acceptedGoals.length > 0) {
-        candidates.push(...extractPlatformIdsFromGoals(context.acceptedGoals, kind, platformIds));
-    }
-    if (context.evidenceRefs && context.evidenceRefs.length > 0) {
-        candidates.push(...extractPlatformIdsFromEvidence(context.evidenceRefs, platformIds));
-    }
-    // Deduplicate while preserving order
-    const ordered = [...new Set(candidates)];
-    if (ordered.length > 1) {
-        // Ambiguous: multiple platforms inferred → do not guess, return undefined.
-        // Guard layer will deny with "ambiguous_platform" reason.
-        return undefined;
-    }
-    if (ordered.length === 1) {
-        const single = ordered[0];
-        if (registry) {
-            if (validatePlatformCapability(single, kind, registry)) {
-                return single;
-            }
-            // Registry says unsupported → undefined (guard layer will deny)
-            return undefined;
-        }
-        // No registry: keep legacy platform-name fallback, but do not invent an
-        // unsupported platform/capability pair that later fails as protocol_mismatch.
-        if (!fallbackPlatformSupportsCapability(single, kind)) {
-            return undefined;
-        }
-        return single;
-    }
-    // No candidates inferred from goals/evidence → fallback to a supported platform.
-    // Sort alphabetically so different capabilities map to different platforms over time,
-    // preventing a single platform (e.g. moltbook) from monopolising all connector traffic.
-    if (registry) {
-        const supported = platformIds
-            .filter((pid) => validatePlatformCapability(pid, kind, registry))
-            .sort();
-        if (supported.length > 0) {
-            return supported[0];
-        }
-    }
-    // No registry: use fallback capability mapping
-    const supportedFallback = platformIds
-        .filter((pid) => fallbackPlatformSupportsCapability(pid, kind))
-        .sort();
-    if (supportedFallback.length > 0) {
-        return supportedFallback[0];
-    }
-    return undefined;
-}
+function kindToCapability(kind) {
+    if (kind === "exploration")
+        return "feed.read";
+    if (kind === "social")
+        return "comment.reply";
+    if (kind === "work")
+        return "work.discover";
+    if (kind === "outreach")
+        return "message.send";
+    return null;
+}
+function getPlatformIds(registry) {
+    if (registry) {
+        return registry.listRegisteredPlatformIds();
+    }
+    // Fallback: built-in platforms when registry is absent (backward compat)
+    return ["moltbook", "instreet", "evomap", "agent-world"];
+}
+const FALLBACK_PLATFORM_CAPABILITIES = {
+    "moltbook": ["feed.read", "post.publish", "comment.reply", "message.send"],
+    "instreet": ["notification.list", "message.send", "comment.reply", "agent.heartbeat"],
+    "evomap": ["agent.register", "agent.heartbeat", "work.discover", "task.claim"],
+    "agent-world": ["feed.read", "work.discover", "task.claim"],
+};
+function fallbackPlatformSupportsCapability(platformId, kind) {
+    const capability = kindToCapability(kind);
+    if (!capability)
+        return false;
+    return (FALLBACK_PLATFORM_CAPABILITIES[platformId] ?? []).includes(capability);
+}
+function extractPlatformIdsFromGoals(goals, kind, platformIds) {
+    const capability = kindToCapability(kind);
+    const results = new Set();
+    for (const goal of goals) {
+        const text = `${goal.description} ${goal.completionCriteria ?? ""}`.toLowerCase();
+        for (const pid of platformIds) {
+            if (text.includes(pid)) {
+                results.add(pid);
+            }
+        }
+        // Also match if goal text contains the capability name (e.g. "feed.read")
+        if (capability && text.includes(capability.toLowerCase())) {
+            // capability alone doesn't tell us platform; keep for later
+        }
+    }
+    return [...results];
+}
+function extractPlatformIdsFromEvidence(refs, platformIds) {
+    const results = new Set();
+    for (const ref of refs) {
+        if (ref.kind === "connector_result" && ref.id) {
+            for (const pid of platformIds) {
+                if (ref.id.includes(pid)) {
+                    results.add(pid);
+                }
+            }
+        }
+        // Parse platform:// URIs (e.g. platform://moltbook/feed.read)
+        if (ref.uri && ref.uri.startsWith("platform://")) {
+            const afterScheme = ref.uri.slice("platform://".length);
+            const platformPart = afterScheme.split("/")[0];
+            if (platformPart && platformIds.includes(platformPart)) {
+                results.add(platformPart);
+            }
+        }
+        // L-02: Also support namespace format moltbook:feed.read (connector-system §5.3)
+        if (ref.uri && !ref.uri.includes("://") && ref.uri.includes(":")) {
+            const nsPart = ref.uri.split(":")[0];
+            if (nsPart && platformIds.includes(nsPart)) {
+                results.add(nsPart);
+            }
+        }
+    }
+    return [...results];
+}
+function validatePlatformCapability(platformId, kind, registry) {
+    const capability = kindToCapability(kind);
+    if (!capability)
+        return false;
+    try {
+        return registry.hasCapability(platformId, capability);
+    }
+    catch (err) {
+        // H-08: Log registry validation failures for observability.
+        console.warn(`[platform-capability-router] Registry validation failed for ${platformId}:${capability}`, err);
+        return false;
+    }
+}
+/**
+ * Resolve an explicit platformId for a candidate intent kind.
+ * Returns `undefined` when no unambiguous platform can be inferred.
+ */
+export function resolvePlatformForIntent(kind, context, registry) {
+    const capability = kindToCapability(kind);
+    if (!capability) {
+        // Quiet, reflection, maintenance have no connector capability mapping.
+        return undefined;
+    }
+    const platformIds = getPlatformIds(registry);
+    const candidates = [];
+    if (context.acceptedGoals && context.acceptedGoals.length > 0) {
+        candidates.push(...extractPlatformIdsFromGoals(context.acceptedGoals, kind, platformIds));
+    }
+    if (context.evidenceRefs && context.evidenceRefs.length > 0) {
+        candidates.push(...extractPlatformIdsFromEvidence(context.evidenceRefs, platformIds));
+    }
+    // Deduplicate while preserving order
+    const ordered = [...new Set(candidates)];
+    if (ordered.length > 1) {
+        // Ambiguous: multiple platforms inferred → do not guess, return undefined.
+        // Guard layer will deny with "ambiguous_platform" reason.
+        return undefined;
+    }
+    if (ordered.length === 1) {
+        const single = ordered[0];
+        if (registry) {
+            if (validatePlatformCapability(single, kind, registry)) {
+                return single;
+            }
+            // Registry says unsupported → undefined (guard layer will deny)
+            return undefined;
+        }
+        // No registry: keep legacy platform-name fallback, but do not invent an
+        // unsupported platform/capability pair that later fails as protocol_mismatch.
+        if (!fallbackPlatformSupportsCapability(single, kind)) {
+            return undefined;
+        }
+        return single;
+    }
+    // No candidates inferred from goals/evidence → fallback to a supported platform.
+    // Sort alphabetically so different capabilities map to different platforms over time,
+    // preventing a single platform (e.g. moltbook) from monopolising all connector traffic.
+    if (registry) {
+        const supported = platformIds
+            .filter((pid) => validatePlatformCapability(pid, kind, registry))
+            .sort();
+        if (supported.length > 0) {
+            return supported[0];
+        }
+    }
+    // No registry: use fallback capability mapping
+    const supportedFallback = platformIds
+        .filter((pid) => fallbackPlatformSupportsCapability(pid, kind))
+        .sort();
+    if (supportedFallback.length > 0) {
+        return supportedFallback[0];
+    }
+    return undefined;
+}

package/runtime/core/second-nature/perception/judgment-engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * JudgmentEngine — Produce JudgmentVerdict records from PerceptionCard.
+ *
+ * Core logic: Read a PerceptionCard, apply rules-only decision tree, and
+ * write a source-backed JudgmentVerdict. No model assist; deterministic
+ * verdict based on relevance, risk flags, source refs, and confidence.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readPerceptionCardById, writeJudgmentVerdict)
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind, SourceRef,
+ *   DegradedOperationResult, V8ReasonCode, ACTION_KIND_REGISTRY)
+ *
+ * Boundary:
+ * - Does not execute actions; produces verdict only.
+ * - Does not write long-term memory; only emits review intent.
+ * - Degrades gracefully on missing card or unreadable state.
+ *
+ * Test coverage: tests/unit/judgment/judgment-engine.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, PlatformNeutralActionKind, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface JudgmentVerdictResult {
+    id: string;
+    cycleId: string;
+    perceptionCardId: string;
+    actionKind: PlatformNeutralActionKind;
+    confidence: number;
+    reason: V8ReasonCode;
+    riskPosture: "low" | "medium" | "high" | "blocked";
+    sourceRefs: SourceRef[];
+    createdAt: string;
+}
+export interface RunAgentJudgmentResult {
+    status: "completed" | "blocked" | "degraded";
+    verdicts: JudgmentVerdictResult[];
+    reason?: V8ReasonCode;
+}
+export interface RunAgentJudgmentOptions {
+    now?: string;
+}
+export declare function runAgentJudgment(db: StateDatabase, perceptionCardId: string, options?: RunAgentJudgmentOptions): Promise<RunAgentJudgmentResult | DegradedOperationResult>;
+export interface BatchJudgmentResult {
+    succeeded: JudgmentVerdictResult[];
+    failed: {
+        perceptionCardId: string;
+        degraded: DegradedOperationResult;
+    }[];
+}
+export declare function runAgentJudgments(db: StateDatabase, perceptionCardIds: string[], options?: RunAgentJudgmentOptions): Promise<BatchJudgmentResult>;

package/runtime/core/second-nature/perception/judgment-engine.js

@@ -0,0 +1,239 @@
+/**
+ * JudgmentEngine — Produce JudgmentVerdict records from PerceptionCard.
+ *
+ * Core logic: Read a PerceptionCard, apply rules-only decision tree, and
+ * write a source-backed JudgmentVerdict. No model assist; deterministic
+ * verdict based on relevance, risk flags, source refs, and confidence.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.detail.md §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readPerceptionCardById, writeJudgmentVerdict)
+ * - `src/shared/types/v8-contracts.js` (PlatformNeutralActionKind, SourceRef,
+ *   DegradedOperationResult, V8ReasonCode, ACTION_KIND_REGISTRY)
+ *
+ * Boundary:
+ * - Does not execute actions; produces verdict only.
+ * - Does not write long-term memory; only emits review intent.
+ * - Degrades gracefully on missing card or unreadable state.
+ *
+ * Test coverage: tests/unit/judgment/judgment-engine.test.ts
+ */
+import { readPerceptionCardById, writeJudgmentVerdict, } from "../../../storage/v8-state-stores.js";
+import { ACTION_KIND_REGISTRY } from "../../../shared/types/v8-contracts.js";
+// ───────────────────────────────────────────────────────────────
+// Config
+// ───────────────────────────────────────────────────────────────
+const MIN_EXTERNAL_ACTION_CONFIDENCE = 0.70;
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function inferRiskPosture(sensitivityClass, riskFlags) {
+    if (sensitivityClass === "sensitive" || riskFlags.includes("credential_shape_detected")) {
+        return "blocked";
+    }
+    if (sensitivityClass === "private_context" || riskFlags.includes("private_context")) {
+        return "high";
+    }
+    if (sensitivityClass === "public_technical") {
+        return "medium";
+    }
+    return "low";
+}
+function parseCardSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function selectVerdict(relevance, confidence, riskPosture, hasSourceRefs, possibleIntents) {
+    // Missing source refs → ignore/watch only
+    if (!hasSourceRefs) {
+        return {
+            actionKind: relevance > 0.5 ? "watch" : "ignore",
+            reason: "judgment_missing_source_refs",
+            finalConfidence: 0.5,
+        };
+    }
+    // Risk blocked → watch or notify_owner only, no external write
+    if (riskPosture === "blocked") {
+        return {
+            actionKind: relevance > 0.5 ? "notify_owner" : "watch",
+            reason: "proposal_risk_blocked",
+            finalConfidence: 0.6,
+        };
+    }
+    // Low confidence → no auto/draft external write
+    const canExternalWrite = confidence >= MIN_EXTERNAL_ACTION_CONFIDENCE;
+    // Low relevance → ignore/watch
+    if (relevance <= 0.3) {
+        return {
+            actionKind: relevance > 0.15 ? "watch" : "ignore",
+            reason: "judgment_low_confidence",
+            finalConfidence: 0.4,
+        };
+    }
+    // Medium/high relevance + low risk → actionable
+    const preferredIntent = possibleIntents.find((intent) => {
+        const meta = ACTION_KIND_REGISTRY[intent];
+        if (!meta)
+            return false;
+        if (meta.sideEffectClass === "external_write" && !canExternalWrite)
+            return false;
+        if (meta.sideEffectClass === "external_write" && riskPosture === "high")
+            return false;
+        return true;
+    });
+    if (preferredIntent) {
+        return {
+            actionKind: preferredIntent,
+            reason: "proposal_created",
+            finalConfidence: confidence,
+        };
+    }
+    // Fallback to watch if no actionable intent allowed
+    return {
+        actionKind: "watch",
+        reason: "judgment_low_confidence",
+        finalConfidence: 0.5,
+    };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function runAgentJudgment(db, perceptionCardId, options) {
+    const now = options?.now ?? new Date().toISOString();
+    const readResult = await readPerceptionCardById(db, perceptionCardId);
+    if (readResult.degraded) {
+        return readResult.degraded;
+    }
+    const card = readResult.row;
+    if (!card) {
+        return {
+            status: "degraded",
+            reason: "state_unreadable",
+            ownerStage: "judgment",
+            sourceRefs: [],
+            operatorNextAction: `PerceptionCard ${perceptionCardId} not found`,
+            retryable: false,
+        };
+    }
+    const sourceRefs = parseCardSourceRefs(card.sourceRefsJson);
+    const hasSourceRefs = sourceRefs.length > 0;
+    // Parse sensitivity class from payload (stored there by perception-builder)
+    let sensitivityClass = "public_general";
+    if (card.payloadJson) {
+        try {
+            const payload = JSON.parse(card.payloadJson);
+            if (payload.sensitivityClass)
+                sensitivityClass = String(payload.sensitivityClass);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const riskPosture = inferRiskPosture(sensitivityClass, card.riskFlagsJson ? JSON.parse(card.riskFlagsJson) : []);
+    // Parse possible intents from payload
+    let possibleIntents = ["watch"];
+    if (card.payloadJson) {
+        try {
+            const payload = JSON.parse(card.payloadJson);
+            if (payload.possibleIntents && Array.isArray(payload.possibleIntents)) {
+                possibleIntents = payload.possibleIntents;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const { actionKind, reason, finalConfidence } = selectVerdict(card.relevance ?? 0.3, card.confidence ?? 0.6, riskPosture, hasSourceRefs, possibleIntents);
+    const verdict = {
+        id: `jud_${perceptionCardId}_${now.replace(/[:.]/g, "")}`,
+        cycleId: card.cycleId,
+        perceptionCardId,
+        actionKind,
+        confidence: finalConfidence,
+        reason,
+        riskPosture,
+        sourceRefs: hasSourceRefs
+            ? sourceRefs
+            : [
+                {
+                    uri: `sn://judgment/missing_source_refs/${perceptionCardId}`,
+                    family: "judgment",
+                    id: perceptionCardId,
+                    redactionClass: "none",
+                    resolveStatus: "missing",
+                },
+            ],
+        createdAt: now,
+    };
+    const writeResult = await writeJudgmentVerdict(db, {
+        id: verdict.id,
+        createdAt: now,
+        cycleId: verdict.cycleId,
+        perceptionCardId: verdict.perceptionCardId,
+        actionKind: verdict.actionKind,
+        confidence: verdict.confidence,
+        reason: verdict.reason,
+        riskPosture: verdict.riskPosture,
+        sourceRefs: verdict.sourceRefs,
+        redactionClass: riskPosture === "blocked" ? "blocked" : "none",
+        lifecycleStatus: "pending",
+        payloadJson: JSON.stringify({
+            possibleIntents,
+            sensitivityClass,
+        }),
+    });
+    if ("reason" in writeResult) {
+        return {
+            status: "degraded",
+            verdicts: [],
+            reason: writeResult.reason,
+        };
+    }
+    return {
+        status: riskPosture === "blocked" ? "blocked" : "completed",
+        verdicts: [verdict],
+        reason,
+    };
+}
+export async function runAgentJudgments(db, perceptionCardIds, options) {
+    const succeeded = [];
+    const failed = [];
+    for (const perceptionCardId of perceptionCardIds) {
+        const result = await runAgentJudgment(db, perceptionCardId, options);
+        if ("verdicts" in result) {
+            if (result.status === "completed" || result.status === "blocked") {
+                succeeded.push(...result.verdicts);
+            }
+            else {
+                failed.push({
+                    perceptionCardId,
+                    degraded: {
+                        status: "degraded",
+                        reason: result.reason ?? "judgment_low_confidence",
+                        ownerStage: "judgment",
+                        sourceRefs: [],
+                        operatorNextAction: `Judgment failed for ${perceptionCardId}`,
+                        retryable: true,
+                    },
+                });
+            }
+        }
+        else {
+            failed.push({
+                perceptionCardId,
+                degraded: result,
+            });
+        }
+    }
+    return { succeeded, failed };
+}

package/runtime/core/second-nature/perception/perception-builder.d.ts

@@ -0,0 +1,62 @@
+/**
+ * PerceptionBuilder — Generate PerceptionCard records from EvidenceItem batches.
+ *
+ * Core logic: Read pending evidence, deduplicate by content hash, build
+ * PerceptionCard with topic, entities, novelty, relevance, summary, risk
+ * flags, confidence, and reviewPriority. Rules-only fallback when model
+ * assist is unavailable.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.detail.md §3.1`
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.md §5`
+ *
+ * Dependencies:
+ * - `src/storage/v8-state-stores.js` (readEvidenceItemsByStatus, writePerceptionCard)
+ * - `src/shared/types/v8-contracts.js` (PerceptionCard fields)
+ *
+ * Boundary:
+ * - Does not judge actionability; that is judgment's job.
+ * - Does not fabricate perception on empty input.
+ * - Rules-only path is deterministic and source-backed.
+ *
+ * Test coverage: tests/unit/perception/perception-builder.test.ts
+ */
+import type { StateDatabase } from "../../../storage/db/index.js";
+import type { SourceRef, DegradedOperationResult, PlatformNeutralActionKind, V8ReasonCode } from "../../../shared/types/v8-contracts.js";
+export interface EvidenceItemInput {
+    id: string;
+    platformId: string;
+    contentHash: string;
+    observedAt: string;
+    sensitivityHint?: string;
+    sourceRefsJson: string;
+    payloadJson?: string | null;
+}
+export interface PerceptionCardResult {
+    id: string;
+    cycleId: string;
+    topic: string;
+    entities: string[];
+    novelty: "new" | "recurring" | "update";
+    relevance: number;
+    summary: string;
+    possibleIntents: PlatformNeutralActionKind[];
+    reviewPriority: "low" | "medium" | "high";
+    sensitivityClass: string;
+    riskFlags: string[];
+    confidence: number;
+    evidenceRefs: SourceRef[];
+    createdAt: string;
+}
+export interface BuildPerceptionCardsResult {
+    status: "completed" | "rules_only" | "blocked" | "empty" | "degraded";
+    cards: PerceptionCardResult[];
+    reason?: V8ReasonCode;
+    truncated?: boolean;
+}
+export interface BuildPerceptionCardsOptions {
+    cycleId: string;
+    maxEvidence?: number;
+    now?: string;
+}
+export declare function buildPerceptionCards(db: StateDatabase, options: BuildPerceptionCardsOptions): Promise<BuildPerceptionCardsResult | DegradedOperationResult>;