@haaaiawd/second-nature 0.1.8 → 0.1.10

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";

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

@@ -1,11 +1,64 @@
-import { type CapabilityIntent, type ChannelType, type ConnectorManifestLike } from "./contract.js";
-export type ConnectorManifest = ConnectorManifestLike;
+import { z } from "zod";
+import { type CapabilityIntent, type ChannelType } from "./contract.js";
+declare const connectorManifestSchema: z.ZodObject<{
+    platformId: z.ZodString;
+    supportedCapabilities: z.ZodArray<z.ZodEnum<{
+        "feed.read": "feed.read";
+        "post.publish": "post.publish";
+        "comment.reply": "comment.reply";
+        "notification.list": "notification.list";
+        "message.send": "message.send";
+        "agent.register": "agent.register";
+        "agent.heartbeat": "agent.heartbeat";
+        "work.discover": "work.discover";
+        "task.claim": "task.claim";
+    }>>;
+    channelPriority: z.ZodArray<z.ZodEnum<{
+        api_rest: "api_rest";
+        api_rpc: "api_rpc";
+        a2a: "a2a";
+        mcp: "mcp";
+        cli: "cli";
+        skill: "skill";
+        browser: "browser";
+    }>>;
+    credentialTypes: z.ZodArray<z.ZodString>;
+    degradedChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        api_rest: "api_rest";
+        api_rpc: "api_rpc";
+        a2a: "a2a";
+        mcp: "mcp";
+        cli: "cli";
+        skill: "skill";
+        browser: "browser";
+    }>>>;
+    sourceRefPolicy: z.ZodOptional<z.ZodObject<{
+        minSourceRefs: z.ZodDefault<z.ZodNumber>;
+        rejectInlineSensitivePayload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConnectorManifest = z.infer<typeof connectorManifestSchema>;
 export declare class CapabilityContractRegistry {
     private readonly byPlatform;
     register(manifest: ConnectorManifest): void;
     loadManifest(platformId: string): ConnectorManifest;
+    listRegisteredPlatformIds(): string[];
     hasCapability(platformId: string, intent: CapabilityIntent): boolean;
     listCapabilities(platformId: string): CapabilityIntent[];
     listChannels(platformId: string): ChannelType[];
 }
+/** T3.1.1 contract name for manifest-first registry. */
+export declare const ConnectorManifestRegistry: typeof CapabilityContractRegistry;
+export type ConnectorManifestRegistry = CapabilityContractRegistry;
+export declare function describeConnector(registry: CapabilityContractRegistry, platformId: string): ConnectorManifest;
+export declare function checkConnector(registry: CapabilityContractRegistry, platformId: string): {
+    ok: boolean;
+    errors: string[];
+};
+export declare function discoverCapabilities(registry: CapabilityContractRegistry): Array<{
+    platformId: string;
+    capabilities: CapabilityIntent[];
+    degradedChannels?: ChannelType[];
+}>;
 export declare function parseConnectorManifest(input: unknown): ConnectorManifest;
+export {};

package/runtime/connectors/base/manifest.js

@@ -1,11 +1,18 @@
 import { z } from "zod";
 import { CAPABILITY_INTENTS, CHANNEL_TYPES } from "./contract.js";
+const sourceRefPolicySchema = z
+    .object({
+    minSourceRefs: z.number().int().min(0).default(1),
+    rejectInlineSensitivePayload: z.boolean().optional(),
+})
+    .optional();
 const connectorManifestSchema = z.object({
     platformId: z.string().min(1),
     supportedCapabilities: z.array(z.enum(CAPABILITY_INTENTS)).min(1),
     channelPriority: z.array(z.enum(CHANNEL_TYPES)).min(1),
     credentialTypes: z.array(z.string().min(1)).min(1),
     degradedChannels: z.array(z.enum(CHANNEL_TYPES)).optional(),
+    sourceRefPolicy: sourceRefPolicySchema,
 });
 export class CapabilityContractRegistry {
     byPlatform = new Map();
@@ -20,6 +27,9 @@ export class CapabilityContractRegistry {
         }
         return found;
     }
+    listRegisteredPlatformIds() {
+        return [...this.byPlatform.keys()];
+    }
     hasCapability(platformId, intent) {
         const manifest = this.loadManifest(platformId);
         return manifest.supportedCapabilities.includes(intent);
@@ -31,6 +41,46 @@ export class CapabilityContractRegistry {
         return [...this.loadManifest(platformId).channelPriority];
     }
 }
+/** T3.1.1 contract name for manifest-first registry. */
+export const ConnectorManifestRegistry = CapabilityContractRegistry;
+export function describeConnector(registry, platformId) {
+    return registry.loadManifest(platformId);
+}
+export function checkConnector(registry, platformId) {
+    const errors = [];
+    try {
+        const manifest = registry.loadManifest(platformId);
+        if (manifest.supportedCapabilities.length === 0) {
+            errors.push("capability_list_empty");
+        }
+        if (manifest.channelPriority.length === 0) {
+            errors.push("channel_priority_empty");
+        }
+        if (manifest.credentialTypes.length === 0) {
+            errors.push("credential_types_empty");
+        }
+        const degraded = manifest.degradedChannels ?? [];
+        for (const channel of degraded) {
+            if (!manifest.channelPriority.includes(channel)) {
+                errors.push(`degraded_channel_not_in_priority:${channel}`);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function discoverCapabilities(registry) {
+    return registry.listRegisteredPlatformIds().map((platformId) => {
+        const manifest = registry.loadManifest(platformId);
+        return {
+            platformId,
+            capabilities: [...manifest.supportedCapabilities],
+            degradedChannels: manifest.degradedChannels,
+        };
+    });
+}
 export function parseConnectorManifest(input) {
     return connectorManifestSchema.parse(input);
 }

package/runtime/connectors/base/map-life-evidence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maps normalized connector success results to `LifeEvidenceCandidate` (T3.1.2).
+ * Returns null when evidence cannot be source-backed (no refs, wrong intent, or failure).
+ */
+import type { CapabilityIntent, ConnectorResult } from "./contract.js";
+import type { LifeEvidenceCandidate, Sensitivity } from "../../storage/life-evidence/types.js";
+/**
+ * Produce a single life-evidence candidate from a connector outcome, or null if not mappable.
+ */
+export declare function mapLifeEvidence(input: {
+    platformId: string;
+    intent: CapabilityIntent;
+    result: ConnectorResult<unknown>;
+    observedAt?: string;
+    sensitivityOverride?: Sensitivity;
+}): LifeEvidenceCandidate | null;