@haaaiawd/second-nature 0.1.8 → 0.1.10

package/runtime/core/second-nature/rhythm/planner-rhythm-window.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Maps calendar rhythm policy + continuity into planner-facing window slice (T2.1.3).
+ * Control-plane owns allowedIntentKinds; state never emits them (T2.1.2 boundary).
+ */
+import type { ContinuitySnapshot, IntentKind } from "../types.js";
+import type { RhythmPolicy } from "./rhythm-policy.js";
+export interface PlannerRhythmWindowSlice {
+    windowId: string;
+    allowedIntentKinds: IntentKind[];
+    quietBias: boolean;
+}
+/**
+ * Derive allowed intent kinds and quiet bias for candidate planning.
+ */
+export declare function buildPlannerRhythmWindow(now: string, continuity: ContinuitySnapshot, policy: RhythmPolicy): PlannerRhythmWindowSlice;

package/runtime/core/second-nature/rhythm/planner-rhythm-window.js

@@ -0,0 +1,52 @@
+import { selectRhythmWindow } from "./select-window.js";
+const ALL_INTENT_KINDS = [
+    "work",
+    "exploration",
+    "social",
+    "quiet",
+    "reflection",
+    "outreach",
+    "maintenance",
+];
+function allowedForPaused() {
+    return ["maintenance"];
+}
+function allowedForMaintenanceOnly() {
+    return ["work", "maintenance"];
+}
+function allowedForActiveWindow(windowId) {
+    if (windowId.includes("work")) {
+        return ["work", "exploration", "maintenance", "reflection", "outreach", "social", "quiet"];
+    }
+    if (windowId.includes("social")) {
+        return ["social", "exploration", "work", "maintenance", "reflection", "outreach", "quiet"];
+    }
+    if (windowId.includes("reflection")) {
+        return ["reflection", "work", "maintenance", "exploration", "social", "outreach", "quiet"];
+    }
+    return ALL_INTENT_KINDS;
+}
+function mergeQuietBias(decision, continuity, windowIsQuiet) {
+    return windowIsQuiet || decision.topLevelMode === "quiet" || continuity.mode === "quiet";
+}
+/**
+ * Derive allowed intent kinds and quiet bias for candidate planning.
+ */
+export function buildPlannerRhythmWindow(now, continuity, policy) {
+    const decision = selectRhythmWindow(now, continuity, policy);
+    const window = policy.windows.find((w) => w.id === decision.windowId) ?? policy.windows[0];
+    const windowIsQuiet = window.mode === "quiet";
+    const quietBias = mergeQuietBias(decision, continuity, windowIsQuiet);
+    let allowed;
+    if (decision.topLevelMode === "paused_for_interrupt") {
+        allowed = allowedForPaused();
+    }
+    else if (decision.topLevelMode === "maintenance_only") {
+        allowed = allowedForMaintenanceOnly();
+    }
+    else {
+        /** Calendar quiet sets `quietBias` only; candidate kinds stay window-biased (guards enforce quiet suppression). */
+        allowed = allowedForActiveWindow(window.id);
+    }
+    return { windowId: decision.windowId, allowedIntentKinds: allowed, quietBias };
+}

package/runtime/core/second-nature/rhythm/policy-bridge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bridges state-system RhythmPolicySnapshot fields into control-plane RhythmPolicy (T2.1.2).
+ *
+ * State never emits window decisions or allowedIntentKinds; control-plane owns
+ * window geometry used by selectRhythmWindow(). Callers pass a pick of the DB read model.
+ */
+import type { RhythmPolicy } from "./rhythm-policy.js";
+/** Subset of `RhythmPolicySnapshot` used for window derivation (no storage import from core). */
+export interface RhythmPolicySnapshotBridgeInput {
+    quietEnabled: boolean;
+}
+/**
+ * Reject drifted snapshot shapes that smuggle control-plane decision fields.
+ */
+export declare function assertRhythmPolicySnapshotContract(snapshot: Record<string, unknown>): void;
+/**
+ * Deterministic default windows from policy knobs (quiet hour tail when quietEnabled).
+ */
+export declare function rhythmPolicySnapshotToRhythmPolicy(snapshot: RhythmPolicySnapshotBridgeInput): RhythmPolicy;

package/runtime/core/second-nature/rhythm/policy-bridge.js

@@ -0,0 +1,34 @@
+const FORBIDDEN_SNAPSHOT_KEYS = ["allowedIntentKinds", "windowDecision", "rhythmWindow"];
+/**
+ * Reject drifted snapshot shapes that smuggle control-plane decision fields.
+ */
+export function assertRhythmPolicySnapshotContract(snapshot) {
+    for (const key of FORBIDDEN_SNAPSHOT_KEYS) {
+        if (key in snapshot) {
+            throw new Error(`rhythm_policy_snapshot_field_drift:${key}`);
+        }
+    }
+}
+/**
+ * Deterministic default windows from policy knobs (quiet hour tail when quietEnabled).
+ */
+export function rhythmPolicySnapshotToRhythmPolicy(snapshot) {
+    assertRhythmPolicySnapshotContract(snapshot);
+    if (snapshot.quietEnabled) {
+        return {
+            timezone: "UTC",
+            quietSuppressionEnabled: true,
+            windows: [
+                { id: "w-work", startMinute: 0, endMinute: 480, mode: "active" },
+                { id: "w-social", startMinute: 480, endMinute: 960, mode: "active" },
+                { id: "w-reflection", startMinute: 960, endMinute: 1200, mode: "active" },
+                { id: "w-quiet", startMinute: 1200, endMinute: 1440, mode: "quiet" },
+            ],
+        };
+    }
+    return {
+        timezone: "UTC",
+        quietSuppressionEnabled: false,
+        windows: [{ id: "w-open", startMinute: 0, endMinute: 1440, mode: "active" }],
+    };
+}

package/runtime/core/second-nature/types.d.ts

@@ -1,7 +1,16 @@
 export type TopLevelMode = "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
-export type IntentKind = "work" | "exploration" | "social" | "reflection" | "outreach" | "maintenance";
+/** Control-plane candidate kinds; includes `quiet` for quiet-window–biased intents (L0 alignment). */
+export type IntentKind = "work" | "exploration" | "social" | "quiet" | "reflection" | "outreach" | "maintenance";
 export type DecisionBasis = "rule_only" | "score_based" | "model_assisted";
 export type GuardVerdict = "allow" | "defer" | "deny" | "escalate";
+/** Minimal source ref for planner / guards (matches state-system `SourceRef` subset). */
+export interface ControlPlaneSourceRef {
+    id: string;
+    kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+    uri: string;
+    excerptHash?: string;
+    observedAt?: string;
+}
 export interface ContinuitySnapshot {
     mode: TopLevelMode;
     currentWindowId: string;
@@ -19,6 +28,7 @@ export interface ContinuitySnapshot {
     awaitingUserInput?: boolean;
     riskSuppressed?: boolean;
 }
+export type CandidateEffectClass = "external_platform_action" | "connector_action" | "memory_curation" | "narrative_reflection" | "user_outreach" | "maintenance" | "no_effect";
 export interface CandidateIntent {
     id: string;
     kind: IntentKind;
@@ -26,7 +36,11 @@ export interface CandidateIntent {
     source: "tick" | "interrupt" | "obligation" | "quiet_plan";
     platformId?: string;
     summary: string;
-    effectClass: "external_platform_action" | "memory_curation" | "narrative_reflection" | "user_outreach" | "maintenance";
+    effectClass: CandidateEffectClass;
+    /** Required for source-backed guard; may be empty when planner expects hard-guard deny. */
+    sourceRefs: ControlPlaneSourceRef[];
+    /** Dedupe / cooldown key; defaults to stable fingerprint in guard layer when omitted. */
+    idempotencyKey?: string;
 }
 export interface GuardEvaluation {
     verdict: GuardVerdict;

package/runtime/guidance/draft-outreach-message.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic GuidanceDraftPort implementation for contract tests and packaged runtime.
+ * Does not claim user-visible delivery when wordingMode is not_sent_fallback_candidate (T6.2.1 / ADR-004).
+ */
+import { type GuidanceDraftPort, type OutreachDraftRequest } from "./outreach-draft-schema.js";
+export declare function draftOutreachMessage(request: OutreachDraftRequest): ReturnType<GuidanceDraftPort["draftOutreachMessage"]>;
+export declare function createDraftOutreachMessagePort(): GuidanceDraftPort;

package/runtime/guidance/draft-outreach-message.js

@@ -0,0 +1,42 @@
+/**
+ * Deterministic GuidanceDraftPort implementation for contract tests and packaged runtime.
+ * Does not claim user-visible delivery when wordingMode is not_sent_fallback_candidate (T6.2.1 / ADR-004).
+ */
+import { safeParseOutreachDraftRequest } from "./outreach-draft-schema.js";
+function baseDraftText(request) {
+    const ids = request.sourceRefs.map((s) => s.id).join(",");
+    return `draft:${request.candidateId}:grounded:${ids}`;
+}
+export async function draftOutreachMessage(request) {
+    const parsed = safeParseOutreachDraftRequest(request);
+    if (!parsed.success) {
+        return { status: "unavailable", reasons: ["outreach_draft_schema_invalid"] };
+    }
+    const r = parsed.data;
+    if (r.judgmentVerdict !== "allow") {
+        return { status: "unavailable", reasons: ["hard_decision_not_allow"] };
+    }
+    if (r.sourceRefs.length === 0) {
+        return { status: "unavailable", reasons: ["missing_resolved_source_refs"] };
+    }
+    const wording = r.deliveryContext.wordingMode;
+    if (wording === "sendable") {
+        return {
+            status: "ready",
+            draft: {
+                text: `${baseDraftText(r)};wording=sendable`,
+                deliveryWording: "sendable",
+            },
+        };
+    }
+    return {
+        status: "ready",
+        draft: {
+            text: `Not sent to the user (candidate only). Delivery state: ${r.deliveryContext.deliveryVerdict}. ${baseDraftText(r)}`,
+            deliveryWording: "not_sent_fallback_candidate",
+        },
+    };
+}
+export function createDraftOutreachMessagePort() {
+    return { draftOutreachMessage };
+}

package/runtime/guidance/evidence-guidance.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Evidence pack assembly, interest-basis selection, and Quiet narrative gate (T6.1.2 / ADR-004).
+ * Guidance does not own delivery or judgment; callers pass already-resolved refs.
+ */
+import type { GuidanceSourceRef } from "./outreach-draft-schema.js";
+import type { UserInterestStaleness } from "../storage/user-interest/types.js";
+import type { SourceCoverage } from "../storage/snapshots/types.js";
+export type SourceCoveragePolicy = "strict" | "lenient";
+export interface EvidencePack {
+    groundedRefs: GuidanceSourceRef[];
+    unresolvedIds: string[];
+    sensitiveBlocked: boolean;
+    policy: SourceCoveragePolicy;
+}
+export declare function buildEvidencePack(refs: GuidanceSourceRef[], opts?: {
+    policy?: SourceCoveragePolicy;
+}): {
+    ok: true;
+    pack: EvidencePack;
+} | {
+    ok: false;
+    reasons: string[];
+};
+export type InterestBasisMode = "evidence_only" | "interest_augmented" | "unavailable";
+export declare function selectInterestBasis(input: {
+    staleness: UserInterestStaleness;
+    confidence: number;
+    signalCount: number;
+}): InterestBasisMode;
+export declare function buildQuietNarrativeGuidance(input: {
+    interestBasis: InterestBasisMode;
+    sourceCoverage: Pick<SourceCoverage, "coverageRatio" | "unsupportedClaims">;
+    outline: string[];
+}): {
+    status: "ready";
+    hints: string[];
+} | {
+    status: "unavailable";
+    reasons: string[];
+};

package/runtime/guidance/evidence-guidance.js

@@ -0,0 +1,52 @@
+export function buildEvidencePack(refs, opts) {
+    const policy = opts?.policy ?? "strict";
+    const unresolvedIds = [];
+    let sensitiveBlocked = false;
+    const grounded = [];
+    for (const r of refs) {
+        if (!r.uri?.trim()) {
+            unresolvedIds.push(r.id);
+            continue;
+        }
+        if (r.uri.includes("credential") || r.uri.includes("secret")) {
+            sensitiveBlocked = true;
+            continue;
+        }
+        grounded.push(r);
+    }
+    if (policy === "strict" && unresolvedIds.length > 0) {
+        return { ok: false, reasons: ["unresolved_source_refs", ...unresolvedIds.slice(0, 3)] };
+    }
+    return {
+        ok: true,
+        pack: {
+            groundedRefs: grounded,
+            unresolvedIds,
+            sensitiveBlocked,
+            policy,
+        },
+    };
+}
+export function selectInterestBasis(input) {
+    if (input.staleness === "insufficient" || input.confidence < 0.15) {
+        return input.signalCount > 0 ? "evidence_only" : "unavailable";
+    }
+    if (input.staleness === "stale") {
+        return "evidence_only";
+    }
+    return "interest_augmented";
+}
+export function buildQuietNarrativeGuidance(input) {
+    if (input.interestBasis === "unavailable" && input.sourceCoverage.coverageRatio < 0.25) {
+        return { status: "unavailable", reasons: ["quiet_guidance_insufficient_interest_and_coverage"] };
+    }
+    if (input.sourceCoverage.unsupportedClaims.length > 0) {
+        return { status: "unavailable", reasons: ["quiet_guidance_unsupported_claims"] };
+    }
+    const hints = [
+        ...input.outline.slice(0, 3).map((line) => `hint:${line}`),
+        `basis:${input.interestBasis}`,
+        `coverage:${input.sourceCoverage.coverageRatio.toFixed(2)}`,
+    ];
+    return { status: "ready", hints };
+}

package/runtime/guidance/index.d.ts

@@ -6,3 +6,6 @@ export * from "./fallback.js";
 export * from "./template-registry.js";
 export * from "./review-workflow.js";
 export * from "./guidance-assembler.js";
+export * from "./outreach-draft-schema.js";
+export * from "./draft-outreach-message.js";
+export * from "./evidence-guidance.js";

package/runtime/guidance/index.js

@@ -6,3 +6,6 @@ export * from "./fallback.js";
 export * from "./template-registry.js";
 export * from "./review-workflow.js";
 export * from "./guidance-assembler.js";
+export * from "./outreach-draft-schema.js";
+export * from "./draft-outreach-message.js";
+export * from "./evidence-guidance.js";

package/runtime/guidance/outreach-draft-schema.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Outreach draft request contracts + zod validation (T6.1.1 / behavioral-guidance-system v5).
+ *
+ * Core logic: strict schema for control-plane → guidance handoff; GuidanceDraftPort documents async seam.
+ * Test coverage: tests/unit/guidance/outreach-draft-schema.test.ts
+ */
+import { z } from "zod";
+export declare const guidanceSourceRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        platform_item: "platform_item";
+        workspace_artifact: "workspace_artifact";
+        decision_record: "decision_record";
+        user_anchor: "user_anchor";
+        connector_result: "connector_result";
+        host_report: "host_report";
+        fallback_artifact: "fallback_artifact";
+    }>;
+    uri: z.ZodString;
+    excerptHash: z.ZodOptional<z.ZodString>;
+    observedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GuidanceSourceRef = z.infer<typeof guidanceSourceRefSchema>;
+export declare const deliveryExpressionContextSchema: z.ZodObject<{
+    deliveryVerdict: z.ZodEnum<{
+        target_none: "target_none";
+        channel_missing: "channel_missing";
+        host_unsupported: "host_unsupported";
+        delivery_failed: "delivery_failed";
+        target_available: "target_available";
+    }>;
+    fallbackRef: z.ZodOptional<z.ZodString>;
+    wordingMode: z.ZodEnum<{
+        sendable: "sendable";
+        not_sent_fallback_candidate: "not_sent_fallback_candidate";
+    }>;
+}, z.core.$strip>;
+export declare const sceneGuidanceRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    sceneType: z.ZodEnum<{
+        outreach: "outreach";
+        explain: "explain";
+        social: "social";
+        quiet_reflection: "quiet_reflection";
+        user_reply_continuity: "user_reply_continuity";
+        fallback_candidate: "fallback_candidate";
+    }>;
+    runtimeScope: z.ZodEnum<{
+        rhythm: "rhythm";
+        user_reply: "user_reply";
+        user_task: "user_task";
+    }>;
+    rhythmWindowKind: z.ZodOptional<z.ZodEnum<{
+        quiet: "quiet";
+        social: "social";
+        work: "work";
+        exploration: "exploration";
+        reflection: "reflection";
+        maintenance: "maintenance";
+    }>>;
+    riskLevel: z.ZodEnum<{
+        medium: "medium";
+        low: "low";
+        high: "high";
+    }>;
+    sourceRefs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            platform_item: "platform_item";
+            workspace_artifact: "workspace_artifact";
+            decision_record: "decision_record";
+            user_anchor: "user_anchor";
+            connector_result: "connector_result";
+            host_report: "host_report";
+            fallback_artifact: "fallback_artifact";
+        }>;
+        uri: z.ZodString;
+        excerptHash: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    deliveryContext: z.ZodOptional<z.ZodObject<{
+        deliveryVerdict: z.ZodEnum<{
+            target_none: "target_none";
+            channel_missing: "channel_missing";
+            host_unsupported: "host_unsupported";
+            delivery_failed: "delivery_failed";
+            target_available: "target_available";
+        }>;
+        fallbackRef: z.ZodOptional<z.ZodString>;
+        wordingMode: z.ZodEnum<{
+            sendable: "sendable";
+            not_sent_fallback_candidate: "not_sent_fallback_candidate";
+        }>;
+    }, z.core.$strip>>;
+    language: z.ZodOptional<z.ZodEnum<{
+        "en-US": "en-US";
+        "zh-CN": "zh-CN";
+    }>>;
+}, z.core.$strip>;
+export declare const outreachDraftRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    runtimeScope: z.ZodEnum<{
+        rhythm: "rhythm";
+        user_reply: "user_reply";
+        user_task: "user_task";
+    }>;
+    rhythmWindowKind: z.ZodOptional<z.ZodEnum<{
+        quiet: "quiet";
+        social: "social";
+        work: "work";
+        exploration: "exploration";
+        reflection: "reflection";
+        maintenance: "maintenance";
+    }>>;
+    riskLevel: z.ZodEnum<{
+        medium: "medium";
+        low: "low";
+        high: "high";
+    }>;
+    sourceRefs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            platform_item: "platform_item";
+            workspace_artifact: "workspace_artifact";
+            decision_record: "decision_record";
+            user_anchor: "user_anchor";
+            connector_result: "connector_result";
+            host_report: "host_report";
+            fallback_artifact: "fallback_artifact";
+        }>;
+        uri: z.ZodString;
+        excerptHash: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    deliveryContext: z.ZodOptional<z.ZodObject<{
+        deliveryVerdict: z.ZodEnum<{
+            target_none: "target_none";
+            channel_missing: "channel_missing";
+            host_unsupported: "host_unsupported";
+            delivery_failed: "delivery_failed";
+            target_available: "target_available";
+        }>;
+        fallbackRef: z.ZodOptional<z.ZodString>;
+        wordingMode: z.ZodEnum<{
+            sendable: "sendable";
+            not_sent_fallback_candidate: "not_sent_fallback_candidate";
+        }>;
+    }, z.core.$strip>>;
+    language: z.ZodOptional<z.ZodEnum<{
+        "en-US": "en-US";
+        "zh-CN": "zh-CN";
+    }>>;
+    sceneType: z.ZodEnum<{
+        outreach: "outreach";
+        fallback_candidate: "fallback_candidate";
+    }>;
+    decisionId: z.ZodString;
+    candidateId: z.ZodString;
+    judgmentVerdict: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        defer: "defer";
+    }>;
+    valueScore: z.ZodNumber;
+    interestRefs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            platform_item: "platform_item";
+            workspace_artifact: "workspace_artifact";
+            decision_record: "decision_record";
+            user_anchor: "user_anchor";
+            connector_result: "connector_result";
+            host_report: "host_report";
+            fallback_artifact: "fallback_artifact";
+        }>;
+        uri: z.ZodString;
+        excerptHash: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SceneGuidanceRequest = z.infer<typeof sceneGuidanceRequestSchema>;
+export type OutreachDraftRequest = z.infer<typeof outreachDraftRequestSchema>;
+export type DeliveryExpressionContext = z.infer<typeof deliveryExpressionContextSchema>;
+export declare function parseOutreachDraftRequest(input: unknown): OutreachDraftRequest;
+export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafeParseResult<{
+    requestId: string;
+    runtimeScope: "rhythm" | "user_reply" | "user_task";
+    riskLevel: "medium" | "low" | "high";
+    sourceRefs: {
+        id: string;
+        kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+        uri: string;
+        excerptHash?: string | undefined;
+        observedAt?: string | undefined;
+    }[];
+    sceneType: "outreach" | "fallback_candidate";
+    decisionId: string;
+    candidateId: string;
+    judgmentVerdict: "allow" | "deny" | "defer";
+    valueScore: number;
+    interestRefs: {
+        id: string;
+        kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+        uri: string;
+        excerptHash?: string | undefined;
+        observedAt?: string | undefined;
+    }[];
+    rhythmWindowKind?: "quiet" | "social" | "work" | "exploration" | "reflection" | "maintenance" | undefined;
+    deliveryContext?: {
+        deliveryVerdict: "target_none" | "channel_missing" | "host_unsupported" | "delivery_failed" | "target_available";
+        wordingMode: "sendable" | "not_sent_fallback_candidate";
+        fallbackRef?: string | undefined;
+    } | undefined;
+    language?: "en-US" | "zh-CN" | undefined;
+}>;
+/** Async seam for generative outreach copy (implementation lives outside control-plane). */
+export interface GuidanceDraftPort {
+    draftOutreachMessage(request: OutreachDraftRequest): Promise<{
+        status: "ready";
+        draft: {
+            text: string;
+            deliveryWording: DeliveryExpressionContext["wordingMode"];
+        };
+    } | {
+        status: "unavailable";
+        reasons: string[];
+    }>;
+}

package/runtime/guidance/outreach-draft-schema.js

@@ -0,0 +1,80 @@
+/**
+ * Outreach draft request contracts + zod validation (T6.1.1 / behavioral-guidance-system v5).
+ *
+ * Core logic: strict schema for control-plane → guidance handoff; GuidanceDraftPort documents async seam.
+ * Test coverage: tests/unit/guidance/outreach-draft-schema.test.ts
+ */
+import { z } from "zod";
+const sourceRefKindSchema = z.enum([
+    "platform_item",
+    "workspace_artifact",
+    "decision_record",
+    "user_anchor",
+    "connector_result",
+    "host_report",
+    "fallback_artifact",
+]);
+export const guidanceSourceRefSchema = z.object({
+    id: z.string().min(1),
+    kind: sourceRefKindSchema,
+    uri: z.string().min(1),
+    excerptHash: z.string().optional(),
+    observedAt: z.string().optional(),
+});
+export const deliveryExpressionContextSchema = z.object({
+    deliveryVerdict: z.enum([
+        "target_available",
+        "target_none",
+        "channel_missing",
+        "host_unsupported",
+        "delivery_failed",
+    ]),
+    fallbackRef: z.string().optional(),
+    wordingMode: z.enum(["sendable", "not_sent_fallback_candidate"]),
+});
+const guidanceSceneTypeSchema = z.enum([
+    "outreach",
+    "quiet_reflection",
+    "social",
+    "explain",
+    "user_reply_continuity",
+    "fallback_candidate",
+]);
+const runtimeScopeSchema = z.enum(["rhythm", "user_task", "user_reply"]);
+const riskLevelSchema = z.enum(["low", "medium", "high"]);
+export const sceneGuidanceRequestSchema = z.object({
+    requestId: z.string().min(1),
+    sceneType: guidanceSceneTypeSchema,
+    runtimeScope: runtimeScopeSchema,
+    rhythmWindowKind: z
+        .enum(["work", "exploration", "social", "quiet", "reflection", "maintenance"])
+        .optional(),
+    riskLevel: riskLevelSchema,
+    sourceRefs: z.array(guidanceSourceRefSchema),
+    deliveryContext: deliveryExpressionContextSchema.optional(),
+    language: z.enum(["zh-CN", "en-US"]).optional(),
+});
+export const outreachDraftRequestSchema = sceneGuidanceRequestSchema
+    .extend({
+    sceneType: z.enum(["outreach", "fallback_candidate"]),
+    decisionId: z.string().min(1),
+    candidateId: z.string().min(1),
+    judgmentVerdict: z.enum(["allow", "deny", "defer"]),
+    valueScore: z.number(),
+    interestRefs: z.array(guidanceSourceRefSchema),
+})
+    .superRefine((val, ctx) => {
+    if (!val.deliveryContext) {
+        ctx.addIssue({
+            code: "custom",
+            message: "outreach_draft_requires_delivery_context",
+            path: ["deliveryContext"],
+        });
+    }
+});
+export function parseOutreachDraftRequest(input) {
+    return outreachDraftRequestSchema.parse(input);
+}
+export function safeParseOutreachDraftRequest(input) {
+    return outreachDraftRequestSchema.safeParse(input);
+}

package/runtime/observability/audit/append-only-audit-store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-memory append-only audit store with hash-chain verification hooks.
+ *
+ * Core logic: reject broken previousHash links; expose ordered envelopes for tests / local tooling.
+ *
+ * Test coverage: tests/unit/observability/audit-envelope.test.ts
+ */
+import type { AuditEnvelope } from "./audit-envelope.js";
+export declare class AppendOnlyAuditStore {
+    private readonly events;
+    append<T>(envelope: AuditEnvelope<T>): void;
+    list(): readonly AuditEnvelope<unknown>[];
+    lastRecordHash(): string | undefined;
+}

package/runtime/observability/audit/append-only-audit-store.js

@@ -0,0 +1,21 @@
+export class AppendOnlyAuditStore {
+    events = [];
+    append(envelope) {
+        const last = this.events[this.events.length - 1];
+        if (last) {
+            if (envelope.integrity.previousHash !== last.integrity.recordHash) {
+                throw new Error("audit_previous_hash_mismatch");
+            }
+        }
+        else if (envelope.integrity.previousHash !== undefined) {
+            throw new Error("audit_genesis_previous_hash");
+        }
+        this.events.push(envelope);
+    }
+    list() {
+        return this.events;
+    }
+    lastRecordHash() {
+        return this.events[this.events.length - 1]?.integrity.recordHash;
+    }
+}