@haaaiawd/second-nature 0.1.27 → 0.1.29

package/runtime/guidance/channel-feedback-ingestion-service.js

@@ -0,0 +1,231 @@
+import * as crypto from "node:crypto";
+// ─── Configuration ──────────────────────────────────────────────────────────
+const RETRY_DELAYS_MS = [500, 1000, 2000];
+const REACTION_WEIGHTS = {
+    reply: 1.0,
+    react: 0.5,
+    ignore: -0.2,
+    block: -1.0,
+};
+const REDACTION_PATTERNS = [
+    /\b\d{3}-\d{3}-\d{4}\b/g, // phone
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, // email
+    /\b(?:\d{4}[-\s]?){3}\d{4}\b/g, // credit card
+];
+const MIN_TRUST_THRESHOLD = -0.5;
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function validateFeedback(feedback) {
+    const errors = [];
+    if (!feedback.deliveryResult) {
+        errors.push("missing_delivery_result");
+    }
+    if (!feedback.ownerReaction) {
+        errors.push("missing_owner_reaction");
+    }
+    if (!feedback.timestamp) {
+        errors.push("missing_timestamp");
+    }
+    else {
+        const feedbackTime = new Date(feedback.timestamp);
+        if (Number.isNaN(feedbackTime.getTime())) {
+            errors.push("invalid_timestamp");
+        }
+        else {
+            const ageDays = (Date.now() - feedbackTime.getTime()) / (1000 * 60 * 60 * 24);
+            if (ageDays > 30) {
+                errors.push("feedback_too_old");
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+function redactReactionContent(content) {
+    if (!content)
+        return content;
+    let redacted = content;
+    for (const pattern of REDACTION_PATTERNS) {
+        redacted = redacted.replace(pattern, "[REDACTED]");
+    }
+    return redacted;
+}
+function coerceDeliveryResult(feedback) {
+    if (feedback.deliveryResult === "sent") {
+        const hasProof = Boolean(feedback.deliveryProof?.messageId?.trim()) || Boolean(feedback.deliveryProof?.hostProofRef);
+        if (!hasProof) {
+            return "not_sent";
+        }
+    }
+    return feedback.deliveryResult;
+}
+function extractToneScore(content) {
+    if (!content)
+        return 0;
+    const positiveWords = ["thanks", "good", "great", "love", "awesome"];
+    const negativeWords = ["bad", "terrible", "hate", "wrong", "stop"];
+    const lower = content.toLowerCase();
+    const pos = positiveWords.filter((w) => lower.includes(w)).length;
+    const neg = negativeWords.filter((w) => lower.includes(w)).length;
+    if (pos > neg)
+        return 1.0;
+    if (neg > pos)
+        return -0.5;
+    return 0;
+}
+function extractTone(content) {
+    const score = extractToneScore(content);
+    if (score > 0.3)
+        return "positive";
+    if (score < -0.3)
+        return "negative";
+    return "neutral";
+}
+function calculateTiming(timestamp) {
+    const hours = (Date.now() - new Date(timestamp).getTime()) / (1000 * 60 * 60);
+    if (hours < 1)
+        return "immediate";
+    if (hours < 24)
+        return "delayed";
+    return "very_delayed";
+}
+function buildRelationshipUpdate(feedback) {
+    const redactedContent = redactReactionContent(feedback.reactionContent);
+    const toneScore = extractToneScore(redactedContent);
+    const reactionWeight = REACTION_WEIGHTS[feedback.ownerReaction];
+    const deliverySuccess = coerceDeliveryResult(feedback) === "sent";
+    return {
+        channelId: feedback.channelId,
+        timestamp: feedback.timestamp,
+        trustDelta: reactionWeight * (1 + toneScore * 0.5),
+        responsePattern: {
+            reaction: feedback.ownerReaction,
+            timing: calculateTiming(feedback.timestamp),
+            tone: extractTone(redactedContent),
+        },
+        deliverySuccess,
+    };
+}
+function applyTrustDecay(currentTrust, lastUpdated) {
+    if (!lastUpdated)
+        return currentTrust;
+    const daysSince = (Date.now() - new Date(lastUpdated).getTime()) / (1000 * 60 * 60 * 24);
+    const decayFactor = Math.pow(0.95, daysSince);
+    return currentTrust * decayFactor;
+}
+function updateResponsePatterns(existing, update, observedAt) {
+    const entry = {
+        reaction: update.reaction,
+        timing: update.timing,
+        tone: update.tone,
+        observedAt,
+    };
+    // Keep last 20 patterns
+    return [...existing, entry].slice(-20);
+}
+function updateChannelPreferences(existing, channelId, deliverySuccess) {
+    const map = new Map(existing.map((p) => [p.channelId, { ...p }]));
+    const pref = map.get(channelId) ?? { channelId, successRate: 0.5 };
+    // Exponential moving average of success rate
+    pref.successRate = pref.successRate * 0.7 + (deliverySuccess ? 1 : 0) * 0.3;
+    pref.lastUsedAt = new Date().toISOString();
+    map.set(channelId, pref);
+    return Array.from(map.values());
+}
+function generateStrategyAdjustments(update, memory) {
+    const adjustments = [];
+    if (memory.trustDelta < 0) {
+        adjustments.push({
+            type: "frequency",
+            adjustment: "decrease",
+            reason: "negative_trust_delta",
+            value: 0.5,
+        });
+    }
+    if (update.responsePattern.reaction === "block") {
+        adjustments.push({
+            type: "tone",
+            adjustment: "more_cautious",
+            reason: "user_blocked",
+        });
+    }
+    if (update.responsePattern.timing === "very_delayed") {
+        adjustments.push({
+            type: "timing",
+            adjustment: "increase_cooldown",
+            reason: "slow_response",
+        });
+    }
+    return adjustments;
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function persistWithRetry(memory, port) {
+    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+        try {
+            await port.updateRelationshipMemory(memory);
+            return { success: true, retryCount: attempt };
+        }
+        catch {
+            if (attempt < RETRY_DELAYS_MS.length) {
+                await sleep(RETRY_DELAYS_MS[attempt]);
+            }
+        }
+    }
+    return { success: false, retryCount: RETRY_DELAYS_MS.length };
+}
+function hashSummary(feedback) {
+    const data = `${feedback.channelId}:${feedback.deliveryResult}:${feedback.ownerReaction}:${feedback.timestamp}`;
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+// ─── Service ────────────────────────────────────────────────────────────────
+export async function ingestChannelFeedback(feedback, deps) {
+    // Step 1: Validate
+    const validation = validateFeedback(feedback);
+    if (!validation.valid) {
+        return { status: "rejected", errors: validation.errors };
+    }
+    // Step 2: Build relationship update (with redaction + delivery-truth coercion)
+    const relationshipUpdate = buildRelationshipUpdate(feedback);
+    // Step 3: Load current memory
+    const currentMemory = await deps.relationshipPort.loadRelationshipMemory();
+    // Step 4: Apply trust decay
+    const decayedTrust = applyTrustDecay(currentMemory.trustDelta, currentMemory.lastUpdated);
+    // Step 5: Compute new trust
+    const newTrust = Math.max(MIN_TRUST_THRESHOLD, decayedTrust + relationshipUpdate.trustDelta);
+    // Step 6: Update patterns and preferences
+    const updatedPatterns = updateResponsePatterns(currentMemory.responsePatterns, relationshipUpdate.responsePattern, feedback.timestamp);
+    const updatedPreferences = updateChannelPreferences(currentMemory.channelPreferences, feedback.channelId, relationshipUpdate.deliverySuccess);
+    // Step 7: Assemble updated memory
+    const updatedMemory = {
+        ...currentMemory,
+        trustDelta: newTrust,
+        responsePatterns: updatedPatterns,
+        channelPreferences: updatedPreferences,
+        lastUpdated: new Date().toISOString(),
+    };
+    // Step 8: Persist with retry
+    const persistResult = await persistWithRetry(updatedMemory, deps.relationshipPort);
+    // Step 9: If all retries failed, audit and return failed_after_retries
+    if (!persistResult.success) {
+        await deps.auditPort.recordFeedbackIngestionFailed({
+            feedbackId: feedback.messageId ?? "unknown",
+            channelId: feedback.channelId,
+            summaryHash: hashSummary(feedback),
+            retryCount: persistResult.retryCount,
+        });
+        return {
+            status: "failed_after_retries",
+            relationshipUpdate,
+            strategyAdjustments: generateStrategyAdjustments(relationshipUpdate, updatedMemory),
+            updatedTrust: newTrust,
+        };
+    }
+    // Step 10: Generate strategy adjustments
+    const strategyAdjustments = generateStrategyAdjustments(relationshipUpdate, updatedMemory);
+    return {
+        status: "ingested",
+        relationshipUpdate,
+        strategyAdjustments,
+        updatedTrust: newTrust,
+    };
+}

package/runtime/guidance/guidance-draft-service.d.ts

@@ -0,0 +1,60 @@
+/**
+ * GuidanceDraftService — T-GVS.C.1
+ *
+ * Core logic: source-backed draft generation with delivery-time re-validation.
+ * Implements DR-028 (validateDraftSources) and DR-030 (GuidanceDraftRequest 7-field contract).
+ *
+ * Boundary:
+ * - Generates DraftMessage with source_refs traced to evidence pack claims.
+ * - validateDraftSources checks evidence availability before delivery; marks invalid
+ *   if any source has been redacted or deleted, returning `draft_source_invalidated`.
+ * - Does not own delivery; caller must validate before sending.
+ *
+ * Test coverage: tests/unit/guidance/guidance-draft-service.test.ts
+ */
+import type { GuidanceSourceRef } from "./outreach-draft-schema.js";
+export interface GuidanceDraftRequest {
+    requestId: string;
+    sceneKind: "outreach" | "follow_up" | "reconnect";
+    evidencePackRef: string;
+    relationshipContextRef: string;
+    channelHint?: string;
+    ownerPreferenceRef?: string;
+    requestedAt: string;
+}
+export interface DraftMessage {
+    text: string;
+    deliveryWording: "sendable" | "not_sent_fallback_candidate";
+    sourceRefs: GuidanceSourceRef[];
+    explanation?: string;
+}
+export type DraftServiceError = "draft_source_invalidated" | "evidence_pack_unavailable" | "unsupported_scene_kind";
+export interface DraftServiceResult {
+    draft?: DraftMessage;
+    error?: DraftServiceError;
+}
+export interface DraftEvidencePackClaim {
+    id: string;
+    text: string;
+    sourceRefs: GuidanceSourceRef[];
+}
+export interface DraftEvidencePack {
+    claims: DraftEvidencePackClaim[];
+}
+export interface DraftEvidencePackPort {
+    loadEvidencePack(ref: string): Promise<DraftEvidencePack | undefined>;
+}
+export interface SourceValidatorPort {
+    checkSourceAvailable(sourceRef: GuidanceSourceRef): Promise<boolean>;
+}
+export declare function generateGuidanceDraft(request: GuidanceDraftRequest, deps: {
+    evidencePort: DraftEvidencePackPort;
+}): Promise<DraftServiceResult>;
+export interface DraftValidationResult {
+    valid: boolean;
+    invalidated?: boolean;
+    reason?: DraftServiceError;
+}
+export declare function validateDraftSources(draft: DraftMessage, deps: {
+    validatorPort: SourceValidatorPort;
+}): Promise<DraftValidationResult>;

package/runtime/guidance/guidance-draft-service.js

@@ -0,0 +1,80 @@
+/**
+ * GuidanceDraftService — T-GVS.C.1
+ *
+ * Core logic: source-backed draft generation with delivery-time re-validation.
+ * Implements DR-028 (validateDraftSources) and DR-030 (GuidanceDraftRequest 7-field contract).
+ *
+ * Boundary:
+ * - Generates DraftMessage with source_refs traced to evidence pack claims.
+ * - validateDraftSources checks evidence availability before delivery; marks invalid
+ *   if any source has been redacted or deleted, returning `draft_source_invalidated`.
+ * - Does not own delivery; caller must validate before sending.
+ *
+ * Test coverage: tests/unit/guidance/guidance-draft-service.test.ts
+ */
+// ─── Service ────────────────────────────────────────────────────────────────
+const SCENE_KINDS = [
+    "outreach",
+    "follow_up",
+    "reconnect",
+];
+function buildDraftText(request, claims) {
+    const anchor = claims.map((c) => c.text).join("; ");
+    switch (request.sceneKind) {
+        case "outreach":
+            return `Hi there — wanted to share something that came up: ${anchor}`;
+        case "follow_up":
+            return `Following up on what we talked about: ${anchor}`;
+        case "reconnect":
+            return `It's been a while — here's what caught my attention: ${anchor}`;
+        default:
+            return `Draft for ${request.sceneKind}: ${anchor}`;
+    }
+}
+export async function generateGuidanceDraft(request, deps) {
+    if (!SCENE_KINDS.includes(request.sceneKind)) {
+        return { error: "unsupported_scene_kind" };
+    }
+    const pack = await deps.evidencePort.loadEvidencePack(request.evidencePackRef);
+    if (!pack) {
+        return { error: "evidence_pack_unavailable" };
+    }
+    const allSourceRefs = pack.claims.flatMap((c) => c.sourceRefs);
+    if (allSourceRefs.length === 0) {
+        return { error: "draft_source_invalidated" };
+    }
+    const text = buildDraftText(request, pack.claims);
+    const parts = [
+        `evidencePack=${request.evidencePackRef}`,
+        `relationshipContext=${request.relationshipContextRef}`,
+    ];
+    if (request.channelHint) {
+        parts.push(`channel=${request.channelHint}`);
+    }
+    if (request.ownerPreferenceRef) {
+        parts.push(`ownerPreference=${request.ownerPreferenceRef}`);
+    }
+    return {
+        draft: {
+            text,
+            deliveryWording: "sendable",
+            sourceRefs: allSourceRefs,
+            explanation: parts.join("; "),
+        },
+    };
+}
+export async function validateDraftSources(draft, deps) {
+    const results = await Promise.all(draft.sourceRefs.map(async (ref) => ({
+        ref,
+        available: await deps.validatorPort.checkSourceAvailable(ref),
+    })));
+    const firstInvalid = results.find((r) => !r.available);
+    if (firstInvalid) {
+        return {
+            valid: false,
+            invalidated: true,
+            reason: "draft_source_invalidated",
+        };
+    }
+    return { valid: true };
+}

package/runtime/guidance/index.d.ts

@@ -8,5 +8,8 @@ export * from "./review-workflow.js";
 export * from "./guidance-assembler.js";
 export * from "./outreach-draft-schema.js";
 export * from "./draft-outreach-message.js";
+export * from "./guidance-draft-service.js";
+export * from "./channel-feedback-ingestion-service.js";
+export * from "./outreach-strategy-selector.js";
 export * from "./evidence-guidance.js";
 export * from "./draft-narrative-outreach.js";

package/runtime/guidance/index.js

@@ -8,5 +8,8 @@ export * from "./review-workflow.js";
 export * from "./guidance-assembler.js";
 export * from "./outreach-draft-schema.js";
 export * from "./draft-outreach-message.js";
+export * from "./guidance-draft-service.js";
+export * from "./channel-feedback-ingestion-service.js";
+export * from "./outreach-strategy-selector.js";
 export * from "./evidence-guidance.js";
 export * from "./draft-narrative-outreach.js";

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

@@ -52,15 +52,15 @@ export declare const sceneGuidanceRequestSchema: z.ZodObject<{
     }>;
     rhythmWindowKind: z.ZodOptional<z.ZodEnum<{
         quiet: "quiet";
-        social: "social";
         maintenance: "maintenance";
-        work: "work";
         exploration: "exploration";
+        social: "social";
+        work: "work";
         reflection: "reflection";
     }>>;
     riskLevel: z.ZodEnum<{
-        medium: "medium";
         low: "low";
+        medium: "medium";
         high: "high";
     }>;
     sourceRefs: z.ZodArray<z.ZodObject<{
@@ -146,15 +146,15 @@ export declare const outreachDraftRequestSchema: z.ZodObject<{
     }>;
     rhythmWindowKind: z.ZodOptional<z.ZodEnum<{
         quiet: "quiet";
-        social: "social";
         maintenance: "maintenance";
-        work: "work";
         exploration: "exploration";
+        social: "social";
+        work: "work";
         reflection: "reflection";
     }>>;
     riskLevel: z.ZodEnum<{
-        medium: "medium";
         low: "low";
+        medium: "medium";
         high: "high";
     }>;
     sourceRefs: z.ZodArray<z.ZodObject<{
@@ -265,7 +265,7 @@ export declare function parseOutreachDraftRequest(input: unknown): OutreachDraft
 export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafeParseResult<{
     requestId: string;
     runtimeScope: "rhythm" | "user_reply" | "user_task";
-    riskLevel: "medium" | "low" | "high";
+    riskLevel: "low" | "medium" | "high";
     sourceRefs: {
         id: string;
         kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
@@ -285,7 +285,7 @@ export declare function safeParseOutreachDraftRequest(input: unknown): z.ZodSafe
         excerptHash?: string | undefined;
         observedAt?: string | undefined;
     }[];
-    rhythmWindowKind?: "quiet" | "social" | "maintenance" | "work" | "exploration" | "reflection" | undefined;
+    rhythmWindowKind?: "quiet" | "maintenance" | "exploration" | "social" | "work" | "reflection" | undefined;
     deliveryContext?: {
         deliveryVerdict: "target_none" | "channel_missing" | "host_unsupported" | "delivery_failed" | "target_available";
         wordingMode: "sendable" | "not_sent_fallback_candidate";

package/runtime/guidance/outreach-strategy-selector.d.ts

@@ -0,0 +1,77 @@
+/**
+ * OutreachStrategySelector — T-GVS.C.3
+ *
+ * Core logic: select expression frequency, phrasing style and fallback copy
+ * based on RelationshipMemory; apply DR-031 language quality lint (3 rules).
+ * style_lint_failed is a degraded marker — it never blocks delivery.
+ * fallback copy always has information value (not empty string).
+ *
+ * DR-031 lint rules:
+ *   1. no_dry_filler   — no hollow phrases ("reach out", "touch base", "just checking in", etc.)
+ *   2. anchored        — must contain a concrete source anchor (specific fact/observation reference)
+ *   3. no_over_explain — no excessive qualifications (≥3 hedge phrases in one draft)
+ *
+ * Boundary:
+ * - Reads RelationshipMemory (channelPreferences, responsePatterns, trustDelta).
+ * - Does NOT write state; returns OutreachStrategy recommendation only.
+ * - style_lint checks run on draft text passed in; strategy selection itself is rule-based.
+ *
+ * Test coverage:
+ *   tests/unit/guidance/outreach-strategy-selector.test.ts
+ *   tests/unit/guidance/outreach-style-fixtures.test.ts
+ */
+import type { RelationshipMemory } from "./channel-feedback-ingestion-service.js";
+export type OutreachFrequency = "standard" | "reduced" | "minimal" | "paused";
+export type OutreachStyle = "warm_anchored" | "concise_factual" | "light_check";
+export interface OutreachStrategy {
+    frequency: OutreachFrequency;
+    style: OutreachStyle;
+    fallbackCopy: FallbackCopy;
+    rationale: string;
+}
+export interface FallbackCopy {
+    text: string;
+    hasInformationValue: boolean;
+    sourceAnchor?: string;
+    channelSafeReason: string;
+}
+export interface StyleLintResult {
+    passed: boolean;
+    violations: StyleLintViolation[];
+    /**
+     * If lint fails, this is the degraded marker (DR-031).
+     * Never blocks delivery — caller decides what to do with it.
+     */
+    lintStatus: "passed" | "style_lint_failed";
+    hitRules: StyleLintRule[];
+}
+export type StyleLintRule = "no_dry_filler" | "anchored" | "no_over_explain";
+export interface StyleLintViolation {
+    rule: StyleLintRule;
+    description: string;
+}
+export interface FallbackContext {
+    sourceRefs: string[];
+    reason: string;
+    channelId?: string;
+    ownerPreferenceRef?: string;
+}
+/**
+ * Run DR-031 language quality checklist on a draft text.
+ * Returns StyleLintResult. style_lint_failed is a degraded marker — never blocks delivery.
+ */
+export declare function runStyleLint(draftText: string): StyleLintResult;
+/**
+ * Build channel-safe fallback copy that always has information value (DR-031 G4).
+ * Never returns empty string. Includes sourceRefs anchor and human-readable channel reason.
+ */
+export declare function buildFallbackCopy(ctx: FallbackContext): FallbackCopy;
+export interface OutreachStrategySelectorOptions {
+    fallbackContext?: FallbackContext;
+}
+/**
+ * Select outreach strategy based on RelationshipMemory.
+ * Returns OutreachStrategy (frequency + style + fallbackCopy + rationale).
+ * Does NOT write state.
+ */
+export declare function selectOutreachStrategy(memory: RelationshipMemory, options?: OutreachStrategySelectorOptions): OutreachStrategy;