@indexnetwork/protocol 22.0.0-rc.498.1 → 64.0.0-rc.604.2

package/dist/opportunities/opportunity.utils.d.ts

@@ -1,217 +0,0 @@
-/**
- * Opportunity graph utilities: role derivation from corpus type.
- * Used by the opportunity graph to map lens corpus to opportunity actor roles.
- *
- * With lens-based HyDE, strategy selection is handled automatically by the
- * LensInferrer agent. This file provides corpus-to-role mapping for opportunity actors.
- */
-import type { HydeTargetCorpus } from '../discovery/index.js';
-/** Actor roles in the opportunity model (agent / patient / peer). */
-export type OpportunityActorRole = 'agent' | 'patient' | 'peer';
-/** Result of mapping a corpus to source and candidate roles. */
-export interface DerivedRoles {
-    sourceRole: OpportunityActorRole;
-    candidateRole: OpportunityActorRole;
-}
-/**
- * Derive actor roles from the corpus type of a lens match.
- *
- * When a candidate is found via:
- * - "profiles" corpus → found by who they are → candidate can help → agent
- * - "intents" corpus → found by what they need → candidate needs something → patient
- *
- * @param corpus - The target corpus that produced the match ('profiles' | 'intents')
- * @returns Roles for the source (intent owner) and the candidate (matched user/intent)
- */
-export declare function deriveRolesFromCorpus(corpus: HydeTargetCorpus): DerivedRoles;
-/**
- * Validates opportunity actors: if an opportunity has an introducer, it must have
- * one or two non-introducer actors (1 = 1:1 intro e.g. "I want to connect with X";
- * 2 = introducer connecting two others).
- *
- * Also rejects self-matches — the same person occupying both sides of a
- * connection. The discovery/persist pipeline trusts the LLM evaluator's actor
- * list, which can collapse onto a single user; downstream readers then garble
- * identity (e.g. a connect link/greeting rendered in one party's voice while the
- * card shows the viewer "matched with themselves"). Two degenerate shapes are
- * blocked here, at the single persist chokepoint:
- *   - every userId-bearing non-introducer actor collapses to the same user,
- *     e.g. `[X(agent), X(patient)]`
- *   - an introducer who is also a participant ("Amina introduced you to Amina")
- * Only `userId`-bearing actors are checked; role-only actors (legacy/tests) pass.
- * Duplicate rows for one participant are allowed when at least one other distinct
- * participant is present (some callers model multiple intents as multiple actor rows).
- *
- * @param actors - Array of actors with at least a role and optional userId
- * @throws Error when the actor set is invalid
- */
-export declare function validateOpportunityActors(actors: Array<{
-    userId?: string;
-    role: string;
-}>): void;
-/**
- * Read-level ACL: whether a user is an actor on the opportunity and may fetch
- * its details. Intentionally broader than `isActionableForViewer` — a user can
- * read an opportunity they are not currently expected to act on (e.g. an agent
- * viewing an accepted opportunity).
- *
- * The feed graph and debug controller chain both predicates: an opportunity only
- * reaches the radar view if it passes `canUserSeeOpportunity` first, then
- * `isActionableForViewer`. For `agent with introducer at pending`,
- * `canUserSeeOpportunity` returns false (read gate blocks it), so the opportunity
- * never surfaces even though `isActionableForViewer` Rule 4 would return true in
- * isolation. This is by design — the agent is not granted read access through the
- * home path until the introducer path completes (negotiation → accepted).
- *
- * Compact Visibility Rule (see `docs/desi./opportunity-status-lifecycle.md`, §3.E):
- * - Introducer or peer: always see.
- * - Patient or party: see if (status is not latent, or there is no introducer).
- * - Agent: see if (status is accepted/rejected/expired, or (status is not latent and there is no introducer)).
- */
-export declare function canUserSeeOpportunity(actors: Array<{
-    userId: string;
-    role: string;
-}>, status: string, userId: string): boolean;
-/**
- * Whether an opportunity should appear on the viewer's radar (actionable =
- * has a pending action for this user).
- *
- * Rules (see `docs/desi./opportunity-status-lifecycle.md`, §3.E):
- *
- *   (1) `latent`, no introducer                   → all actors actionable
- *   (2) `latent`, introducer `approved !== true`  → introducer only
- *   (3) `latent`, introducer `approved === true`  → all non-introducer actors
- *   (4) `pending` (any introducer config)         → non-introducer actors who have not acted.
- *       Acting is per-user, not per-actor-row: re-detection can append duplicate
- *       actor rows for the same user without `actedAt`, so any viewer row with
- *       `actedAt` means the viewer has already acted.
- *   (5) `accepted`/`rejected`/`expired`/`stalled`/`draft`/`negotiating`
- *                                                 → never actionable
- *
- * The introducer approval signal is stored on the `introducer`-roled actor's
- * `approved: boolean` field within the opportunity's `actors` JSONB. It flips
- * from `false` to `true` when the introducer approves; status stays `latent`
- * across the flip while a background negotiation runs.
- */
-export declare function isActionableForViewer(actors: Array<{
-    userId: string;
-    role: string;
-    approved?: boolean;
-    actedAt?: string | null;
-}>, status: string, viewerId: string): boolean;
-/** Feed category for home composition. */
-export type FeedCategory = 'connection' | 'connector-flow' | 'expired';
-/** Soft targets for radar composition. */
-export declare const RADAR_SOFT_TARGETS: {
-    readonly connection: 3;
-    readonly connectorFlow: 2;
-    readonly expired: 2;
-};
-/**
- * Classify an actionable opportunity into a feed category.
- * Assumes the opportunity already passed isActionableForViewer or is expired.
- *
- * @param opp - Opportunity with actors and status
- * @param viewerId - The viewing user's ID
- * @returns Feed category
- */
-export declare function classifyOpportunity(opp: {
-    actors: Array<{
-        userId: string;
-        role: string;
-    }>;
-    status: string;
-}, viewerId: string): FeedCategory;
-/**
- * Select opportunities for the radar using soft composition targets.
- * Fills each category up to its target, then redistributes unused slots
- * to categories that have more items available. Preserves input order.
- *
- * @param opportunities - Pre-sorted opportunities (by confidence/recency)
- * @param viewerId - The viewing user's ID
- * @returns Composition-balanced subset
- */
-export declare function selectByComposition<T extends {
-    actors: Array<{
-        userId: string;
-        role: string;
-    }>;
-    status: string;
-}>(opportunities: T[], viewerId: string): T[];
-/**
- * Deduplicate opportunities so each counterpart appears at most once.
- * Keeps the opportunity with the highest interpretation.confidence per
- * counterpart userId. On ties, the first encountered wins (stable).
- *
- * Counterpart = first actor whose userId !== viewerId and role !== 'introducer'.
- * Opportunities without a derivable counterpart pass through undeduped.
- *
- * @param opportunities - Pre-sorted opportunities (e.g. by confidence/recency)
- * @param viewerId - The viewing user's ID
- * @returns Deduped subset preserving original input order among winners
- */
-export declare function deduplicateByPerson<T extends {
-    actors: Array<{
-        userId: string;
-        role: string;
-    }>;
-    interpretation?: {
-        confidence?: number;
-    } | null;
-}>(opportunities: T[], viewerId: string): T[];
-/**
- * Days a digest-delivered opportunity stays suppressed before it becomes
- * eligible for a "still open" reminder re-show (when nothing fresh exists).
- */
-export declare const DIGEST_REDELIVERY_COOLDOWN_DAYS = 5;
-/** Committed delivery row shape consumed by {@link selectDigestCandidates}. */
-export interface DigestDeliveredRow {
-    opportunityId: string;
-    deliveredAtStatus: string;
-    deliveredAt: Date;
-}
-/**
- * Cross-day digest suppression for scheduled-brief candidates.
- *
- * Three rules, applied in order:
- * 1. **Accepted-counterpart suppression** — a direct-connection candidate whose
- *    counterpart the viewer has already connected with (an `accepted`
- *    opportunity exists with that person) is dropped permanently. A new
- *    discovery run re-minting the same person must not resurface them.
- *    Connector-flow candidates (viewer is the introducer) are exempt: being
- *    connected with someone doesn't make an intro ask on their behalf stale.
- * 2. **Delivery-ledger dedup** — candidates with a committed delivery row at
- *    the same `(opportunityId, status)` key have already been shown. While any
- *    fresh (never-shown) candidate exists, shown ones are dropped entirely.
- * 3. **Cooldown re-show** — when *no* fresh candidate survives, already-shown
- *    candidates whose latest delivery is at least `cooldownDays` old are
- *    returned instead, least-recently-shown first, flagged via
- *    `redeliveryIds` so the digest can frame them as reminders.
- *
- * Pure function — callers fetch accepted counterparts and ledger rows.
- *
- * @param candidates - Deduped, confidence-ordered digest candidates.
- * @param opts.viewerId - The digest recipient.
- * @param opts.acceptedCounterpartIds - userIds the viewer already connected with.
- * @param opts.deliveredRows - Committed ledger rows for the candidate ids.
- * @param opts.now - Clock override for tests.
- * @param opts.cooldownDays - Cooldown override (default {@link DIGEST_REDELIVERY_COOLDOWN_DAYS}).
- * @returns Surviving pool plus the set of candidate ids that are cooldown re-shows.
- */
-export declare function selectDigestCandidates<T extends {
-    id: string;
-    status: string;
-    actors: Array<{
-        userId: string;
-        role: string;
-    }>;
-}>(candidates: T[], opts: {
-    viewerId: string;
-    acceptedCounterpartIds: ReadonlySet<string>;
-    deliveredRows: DigestDeliveredRow[];
-    now?: Date;
-    cooldownDays?: number;
-}): {
-    pool: T[];
-    redeliveryIds: Set<string>;
-};

package/dist/opportunities/opportunity.utils.js

@@ -1,395 +0,0 @@
-/**
- * Opportunity graph utilities: role derivation from corpus type.
- * Used by the opportunity graph to map lens corpus to opportunity actor roles.
- *
- * With lens-based HyDE, strategy selection is handled automatically by the
- * LensInferrer agent. This file provides corpus-to-role mapping for opportunity actors.
- */
-import { log } from '../shared/observability/log.js';
-const logger = log.graph.from('SelectByComposition');
-const dedupeByPersonLog = log.graph.from('DeduplicateByPerson');
-const digestCandidatesLog = log.graph.from('SelectDigestCandidates');
-/**
- * Derive actor roles from the corpus type of a lens match.
- *
- * When a candidate is found via:
- * - "profiles" corpus → found by who they are → candidate can help → agent
- * - "intents" corpus → found by what they need → candidate needs something → patient
- *
- * @param corpus - The target corpus that produced the match ('profiles' | 'intents')
- * @returns Roles for the source (intent owner) and the candidate (matched user/intent)
- */
-export function deriveRolesFromCorpus(corpus) {
-    switch (corpus) {
-        case 'profiles':
-            // Source seeks someone who can help → source is patient, candidate can help → agent
-            return { sourceRole: 'patient', candidateRole: 'agent' };
-        case 'intents':
-            // Source offers or needs; candidate has complementary goal → source is agent, candidate is patient
-            return { sourceRole: 'agent', candidateRole: 'patient' };
-        case 'premises':
-            // Premise matches are symmetric: two people whose self-descriptions align.
-            // Unlike intents (directional roles), premises express stable identity truths.
-            return { sourceRole: 'peer', candidateRole: 'peer' };
-        default:
-            return { sourceRole: 'peer', candidateRole: 'peer' };
-    }
-}
-/**
- * Validates opportunity actors: if an opportunity has an introducer, it must have
- * one or two non-introducer actors (1 = 1:1 intro e.g. "I want to connect with X";
- * 2 = introducer connecting two others).
- *
- * Also rejects self-matches — the same person occupying both sides of a
- * connection. The discovery/persist pipeline trusts the LLM evaluator's actor
- * list, which can collapse onto a single user; downstream readers then garble
- * identity (e.g. a connect link/greeting rendered in one party's voice while the
- * card shows the viewer "matched with themselves"). Two degenerate shapes are
- * blocked here, at the single persist chokepoint:
- *   - every userId-bearing non-introducer actor collapses to the same user,
- *     e.g. `[X(agent), X(patient)]`
- *   - an introducer who is also a participant ("Amina introduced you to Amina")
- * Only `userId`-bearing actors are checked; role-only actors (legacy/tests) pass.
- * Duplicate rows for one participant are allowed when at least one other distinct
- * participant is present (some callers model multiple intents as multiple actor rows).
- *
- * @param actors - Array of actors with at least a role and optional userId
- * @throws Error when the actor set is invalid
- */
-export function validateOpportunityActors(actors) {
-    const introducerCount = actors.filter((a) => a.role === 'introducer').length;
-    const nonIntroducerCount = actors.filter((a) => a.role !== 'introducer').length;
-    if (introducerCount > 0 && (nonIntroducerCount < 1 || nonIntroducerCount > 2)) {
-        throw new Error('An opportunity with an introducer must have one or two other actors.');
-    }
-    // Self-match guard. Compare only actors that carry a userId so role-only
-    // shapes (used by some callers/tests) are unaffected.
-    const introducerUserIds = new Set(actors.filter((a) => a.role === 'introducer' && a.userId).map((a) => a.userId));
-    const nonIntroducerUserIds = actors
-        .filter((a) => a.role !== 'introducer' && a.userId)
-        .map((a) => a.userId);
-    for (const userId of nonIntroducerUserIds) {
-        if (introducerUserIds.has(userId)) {
-            throw new Error('An opportunity actor cannot be both the introducer and a participant (self-match).');
-        }
-    }
-    const uniqueNonIntroducerUserIds = new Set(nonIntroducerUserIds);
-    if (nonIntroducerUserIds.length > 1 && uniqueNonIntroducerUserIds.size === 1) {
-        throw new Error('An opportunity cannot match a user with themselves (duplicate participant).');
-    }
-}
-/**
- * Read-level ACL: whether a user is an actor on the opportunity and may fetch
- * its details. Intentionally broader than `isActionableForViewer` — a user can
- * read an opportunity they are not currently expected to act on (e.g. an agent
- * viewing an accepted opportunity).
- *
- * The feed graph and debug controller chain both predicates: an opportunity only
- * reaches the radar view if it passes `canUserSeeOpportunity` first, then
- * `isActionableForViewer`. For `agent with introducer at pending`,
- * `canUserSeeOpportunity` returns false (read gate blocks it), so the opportunity
- * never surfaces even though `isActionableForViewer` Rule 4 would return true in
- * isolation. This is by design — the agent is not granted read access through the
- * home path until the introducer path completes (negotiation → accepted).
- *
- * Compact Visibility Rule (see `docs/desi./opportunity-status-lifecycle.md`, §3.E):
- * - Introducer or peer: always see.
- * - Patient or party: see if (status is not latent, or there is no introducer).
- * - Agent: see if (status is accepted/rejected/expired, or (status is not latent and there is no introducer)).
- */
-export function canUserSeeOpportunity(actors, status, userId) {
-    const hasIntroducer = actors.some((a) => a.role === 'introducer');
-    const userRoles = actors.filter((a) => a.userId === userId).map((a) => a.role);
-    if (userRoles.length === 0)
-        return false;
-    return userRoles.some((role) => {
-        if (role === 'introducer')
-            return true;
-        if (role === 'peer')
-            return true;
-        if (role === 'patient' || role === 'party')
-            return status !== 'latent' || !hasIntroducer;
-        if (role === 'agent')
-            return (['accepted', 'rejected', 'expired'].includes(status) ||
-                (status !== 'latent' && !hasIntroducer));
-        return false;
-    });
-}
-/**
- * Whether an opportunity should appear on the viewer's radar (actionable =
- * has a pending action for this user).
- *
- * Rules (see `docs/desi./opportunity-status-lifecycle.md`, §3.E):
- *
- *   (1) `latent`, no introducer                   → all actors actionable
- *   (2) `latent`, introducer `approved !== true`  → introducer only
- *   (3) `latent`, introducer `approved === true`  → all non-introducer actors
- *   (4) `pending` (any introducer config)         → non-introducer actors who have not acted.
- *       Acting is per-user, not per-actor-row: re-detection can append duplicate
- *       actor rows for the same user without `actedAt`, so any viewer row with
- *       `actedAt` means the viewer has already acted.
- *   (5) `accepted`/`rejected`/`expired`/`stalled`/`draft`/`negotiating`
- *                                                 → never actionable
- *
- * The introducer approval signal is stored on the `introducer`-roled actor's
- * `approved: boolean` field within the opportunity's `actors` JSONB. It flips
- * from `false` to `true` when the introducer approves; status stays `latent`
- * across the flip while a background negotiation runs.
- */
-export function isActionableForViewer(actors, status, viewerId) {
-    const viewerActors = actors.filter((a) => a.userId === viewerId);
-    if (viewerActors.length === 0)
-        return false;
-    // Per-user acted signal: duplicate actor rows appended by re-detection may
-    // lack `actedAt` even though the viewer already accepted/rejected — a single
-    // stamped row means the viewer has acted on this opportunity.
-    const viewerActed = viewerActors.some((a) => !!a.actedAt);
-    const introducer = actors.find((a) => a.role === 'introducer');
-    const hasIntroducer = !!introducer;
-    const introducerApproved = introducer?.approved === true;
-    return viewerActors.some(({ role }) => {
-        if (role === 'introducer') {
-            // Rule 2: introducer sees own latent opp only while not yet approved.
-            return status === 'latent' && !introducerApproved;
-        }
-        // Non-introducer actors: patient / party / agent / peer.
-        if (status === 'latent') {
-            // Rule 1: no introducer → visible.
-            // Rule 3: introducer approved → visible.
-            return !hasIntroducer || introducerApproved;
-        }
-        if (status === 'pending') {
-            // Rule 4: pending is actionable only while the viewer has not acted.
-            // Once any of the viewer's actor rows has `actedAt`, the opportunity is
-            // waiting on the counterparty and should not appear in the viewer's feed.
-            return !viewerActed;
-        }
-        // Rule 5: never actionable at terminal or internal statuses.
-        return false;
-    });
-}
-/** Soft targets for radar composition. */
-export const RADAR_SOFT_TARGETS = {
-    connection: 3,
-    connectorFlow: 2,
-    expired: 2,
-};
-/**
- * Classify an actionable opportunity into a feed category.
- * Assumes the opportunity already passed isActionableForViewer or is expired.
- *
- * @param opp - Opportunity with actors and status
- * @param viewerId - The viewing user's ID
- * @returns Feed category
- */
-export function classifyOpportunity(opp, viewerId) {
-    if (opp.status === 'expired')
-        return 'expired';
-    const viewerIsIntroducer = opp.actors.some((a) => a.userId === viewerId && a.role === 'introducer');
-    if (viewerIsIntroducer)
-        return 'connector-flow';
-    return 'connection';
-}
-/**
- * Select opportunities for the radar using soft composition targets.
- * Fills each category up to its target, then redistributes unused slots
- * to categories that have more items available. Preserves input order.
- *
- * @param opportunities - Pre-sorted opportunities (by confidence/recency)
- * @param viewerId - The viewing user's ID
- * @returns Composition-balanced subset
- */
-export function selectByComposition(opportunities, viewerId) {
-    const buckets = {
-        connection: [],
-        'connector-flow': [],
-        expired: [],
-    };
-    for (const opp of opportunities) {
-        const category = classifyOpportunity(opp, viewerId);
-        buckets[category].push(opp);
-    }
-    const targets = {
-        connection: RADAR_SOFT_TARGETS.connection,
-        'connector-flow': RADAR_SOFT_TARGETS.connectorFlow,
-        expired: RADAR_SOFT_TARGETS.expired,
-    };
-    // First pass: fill each category up to its target
-    const selected = {
-        connection: buckets.connection.slice(0, targets.connection),
-        'connector-flow': buckets['connector-flow'].slice(0, targets['connector-flow']),
-        expired: buckets.expired.slice(0, targets.expired),
-    };
-    // Calculate unused slots and remaining items
-    const totalTarget = targets.connection + targets['connector-flow'] + targets.expired;
-    const usedSlots = selected.connection.length + selected['connector-flow'].length + selected.expired.length;
-    let unusedSlots = totalTarget - usedSlots;
-    // Second pass: redistribute unused slots to categories with remaining items
-    // Priority: connection > connector-flow > expired
-    const redistOrder = ['connection', 'connector-flow', 'expired'];
-    for (const category of redistOrder) {
-        if (unusedSlots <= 0)
-            break;
-        const remaining = buckets[category].slice(selected[category].length);
-        const take = Math.min(remaining.length, unusedSlots);
-        selected[category].push(...remaining.slice(0, take));
-        unusedSlots -= take;
-    }
-    // Merge in category priority order: connection > connector-flow > expired
-    // Within each category, preserve original input order
-    const indexMap = new Map(opportunities.map((opp, i) => [opp, i]));
-    const sortByOriginal = (a, b) => (indexMap.get(a) ?? 0) - (indexMap.get(b) ?? 0);
-    selected.connection.sort(sortByOriginal);
-    selected['connector-flow'].sort(sortByOriginal);
-    selected.expired.sort(sortByOriginal);
-    logger.info('Selected opportunities by composition', {
-        input: opportunities.length,
-        buckets: {
-            connection: buckets.connection.length,
-            connectorFlow: buckets['connector-flow'].length,
-            expired: buckets.expired.length,
-        },
-        selected: {
-            connection: selected.connection.length,
-            connectorFlow: selected['connector-flow'].length,
-            expired: selected.expired.length,
-        },
-    });
-    return [
-        ...selected.connection,
-        ...selected['connector-flow'],
-        ...selected.expired,
-    ];
-}
-/**
- * Deduplicate opportunities so each counterpart appears at most once.
- * Keeps the opportunity with the highest interpretation.confidence per
- * counterpart userId. On ties, the first encountered wins (stable).
- *
- * Counterpart = first actor whose userId !== viewerId and role !== 'introducer'.
- * Opportunities without a derivable counterpart pass through undeduped.
- *
- * @param opportunities - Pre-sorted opportunities (e.g. by confidence/recency)
- * @param viewerId - The viewing user's ID
- * @returns Deduped subset preserving original input order among winners
- */
-export function deduplicateByPerson(opportunities, viewerId) {
-    const bestByCounterpart = new Map();
-    const noCounterpart = [];
-    for (let i = 0; i < opportunities.length; i++) {
-        const opp = opportunities[i];
-        const counterpart = opp.actors.find((a) => a.userId !== viewerId && a.role !== 'introducer');
-        if (!counterpart) {
-            noCounterpart.push({ opp, index: i });
-            continue;
-        }
-        const key = counterpart.userId;
-        const existing = bestByCounterpart.get(key);
-        if (!existing) {
-            bestByCounterpart.set(key, { opp, index: i });
-            continue;
-        }
-        const newConf = opp.interpretation?.confidence ?? -1;
-        const oldConf = existing.opp.interpretation?.confidence ?? -1;
-        if (newConf > oldConf) {
-            bestByCounterpart.set(key, { opp, index: i });
-        }
-    }
-    const all = [...bestByCounterpart.values(), ...noCounterpart];
-    all.sort((a, b) => a.index - b.index);
-    const result = all.map((entry) => entry.opp);
-    if (result.length < opportunities.length) {
-        dedupeByPersonLog.info('Deduped opportunities by person', {
-            input: opportunities.length,
-            output: result.length,
-        });
-    }
-    return result;
-}
-/**
- * Days a digest-delivered opportunity stays suppressed before it becomes
- * eligible for a "still open" reminder re-show (when nothing fresh exists).
- */
-export const DIGEST_REDELIVERY_COOLDOWN_DAYS = 5;
-/**
- * Cross-day digest suppression for scheduled-brief candidates.
- *
- * Three rules, applied in order:
- * 1. **Accepted-counterpart suppression** — a direct-connection candidate whose
- *    counterpart the viewer has already connected with (an `accepted`
- *    opportunity exists with that person) is dropped permanently. A new
- *    discovery run re-minting the same person must not resurface them.
- *    Connector-flow candidates (viewer is the introducer) are exempt: being
- *    connected with someone doesn't make an intro ask on their behalf stale.
- * 2. **Delivery-ledger dedup** — candidates with a committed delivery row at
- *    the same `(opportunityId, status)` key have already been shown. While any
- *    fresh (never-shown) candidate exists, shown ones are dropped entirely.
- * 3. **Cooldown re-show** — when *no* fresh candidate survives, already-shown
- *    candidates whose latest delivery is at least `cooldownDays` old are
- *    returned instead, least-recently-shown first, flagged via
- *    `redeliveryIds` so the digest can frame them as reminders.
- *
- * Pure function — callers fetch accepted counterparts and ledger rows.
- *
- * @param candidates - Deduped, confidence-ordered digest candidates.
- * @param opts.viewerId - The digest recipient.
- * @param opts.acceptedCounterpartIds - userIds the viewer already connected with.
- * @param opts.deliveredRows - Committed ledger rows for the candidate ids.
- * @param opts.now - Clock override for tests.
- * @param opts.cooldownDays - Cooldown override (default {@link DIGEST_REDELIVERY_COOLDOWN_DAYS}).
- * @returns Surviving pool plus the set of candidate ids that are cooldown re-shows.
- */
-export function selectDigestCandidates(candidates, opts) {
-    const { viewerId, acceptedCounterpartIds } = opts;
-    // Rule 1: accepted-counterpart suppression (direct connections only).
-    const afterAccepted = candidates.filter((opp) => {
-        const viewerIsIntroducer = opp.actors.some((a) => a.role === 'introducer' && a.userId === viewerId);
-        if (viewerIsIntroducer)
-            return true;
-        const counterpart = opp.actors.find((a) => a.userId !== viewerId && a.role !== 'introducer');
-        return !counterpart || !acceptedCounterpartIds.has(counterpart.userId);
-    });
-    if (afterAccepted.length < candidates.length) {
-        digestCandidatesLog.info('Accepted-counterpart suppression dropped candidates', {
-            dropped: candidates.length - afterAccepted.length,
-            total: candidates.length,
-        });
-    }
-    // Rule 2: delivery-ledger dedup keyed (opportunityId, deliveredAtStatus).
-    // Keep the LATEST committed delivery per key — cooldown measures time since
-    // the user last saw the card, not since they first saw it.
-    const lastDeliveredByKey = new Map();
-    for (const row of opts.deliveredRows) {
-        if (!(row.deliveredAt instanceof Date) || Number.isNaN(row.deliveredAt.getTime()))
-            continue;
-        const key = `${row.opportunityId}:${row.deliveredAtStatus}`;
-        const existing = lastDeliveredByKey.get(key);
-        if (!existing || row.deliveredAt > existing)
-            lastDeliveredByKey.set(key, row.deliveredAt);
-    }
-    const fresh = afterAccepted.filter((opp) => !lastDeliveredByKey.has(`${opp.id}:${opp.status}`));
-    if (fresh.length > 0) {
-        if (fresh.length < afterAccepted.length) {
-            digestCandidatesLog.info('Ledger dedup dropped already-shown candidates', {
-                dropped: afterAccepted.length - fresh.length,
-            });
-        }
-        return { pool: fresh, redeliveryIds: new Set() };
-    }
-    // Rule 3: nothing fresh — re-show the least-recently-shown candidates past cooldown.
-    const cooldownMs = (opts.cooldownDays ?? DIGEST_REDELIVERY_COOLDOWN_DAYS) * 86400000;
-    const now = opts.now ?? new Date();
-    const cooled = afterAccepted
-        .map((opp) => ({ opp, at: lastDeliveredByKey.get(`${opp.id}:${opp.status}`) }))
-        .filter((entry) => entry.at instanceof Date && now.getTime() - entry.at.getTime() >= cooldownMs)
-        .sort((a, b) => a.at.getTime() - b.at.getTime());
-    if (cooled.length > 0) {
-        digestCandidatesLog.info('No fresh candidates — re-showing past-cooldown candidates', {
-            count: cooled.length,
-        });
-    }
-    return {
-        pool: cooled.map((entry) => entry.opp),
-        redeliveryIds: new Set(cooled.map((entry) => entry.opp.id)),
-    };
-}

package/dist/opportunities/outcome/outcome.env.d.ts

@@ -1,60 +0,0 @@
-/**
- * Centralized accessors for Lens B outcome-question environment variables
- * (IND-434).
- *
- *   OUTCOME_QUESTIONS_MODE   off | shadow | on — Lens B "explicit opportunity
- *                            outcomes → grounded questions" pipeline.
- *
- *                            off (default): no outcome feedback events are
- *                              captured and no hypothesis mining runs. Zero
- *                              behavior change.
- *                            shadow: capture one idempotent append-only
- *                              feedback event per explicit owner action, mine
- *                              neutral trade-off hypotheses for the exact
- *                              recipient + intent + fingerprint, and emit
- *                              aggregate telemetry only. No question, ranking,
- *                              intent, premise, memory, newborn-stamp, or push
- *                              writes.
- *                            on: reserved for a later phase (IND-438) that
- *                              turns a grounded hypothesis into a user-facing
- *                              question. This slice treats "on" exactly like
- *                              "shadow" for capture + mining; it never emits
- *                              questions.
- *
- * All reads go through this module — do not read this variable via
- * `process.env` elsewhere. Values are read on every call (no caching) so tests
- * and long-lived processes observe changes.
- */
-/** Lens B outcome-question mode. */
-export type OutcomeQuestionsMode = "off" | "shadow" | "on";
-/**
- * Current OUTCOME_QUESTIONS_MODE (default off). Only the exact trimmed literals
- * "shadow" and "on" activate; every other value (including unset/empty) is off.
- */
-export declare function outcomeQuestionsMode(): OutcomeQuestionsMode;
-/**
- * True when Lens B capture + mining should run at all. Both "shadow" and "on"
- * activate the shadow pipeline; only the future question-emitting behavior is
- * gated on "on" (not part of this slice).
- */
-export declare function isOutcomeQuestionsActivated(): boolean;
-/**
- * Independent-support threshold (k). Every compared group (discriminator side)
- * must have at least this many INDEPENDENT (related-opportunity-deduplicated)
- * examples before the hypothesis is eligible. Enforced per side, so no side
- * can be traced back to a small handful of individuals.
- */
-export declare const OUTCOME_MIN_INDEPENDENT_SUPPORT = 5;
-/** Minimum number of qualified sides (each ≥ k) for a hypothesis to compare. */
-export declare const OUTCOME_MIN_COMPARED_SIDES = 2;
-/**
- * k-anonymity floor for attempting a mining pass at all: the number of
- * distinct independent examples (after related-opportunity dedup) required
- * before the miner is invoked. Set to k × minimum compared sides so a pass can
- * never produce an eligible hypothesis below the aggregate floor.
- */
-export declare const OUTCOME_MIN_INDEPENDENT_EXAMPLES: number;
-/** Max independent examples sent to the miner LLM (most recent first). */
-export declare const OUTCOME_MAX_CANDIDATES = 48;
-/** Max chars of presentation-safe candidate snapshot stored/sent per example. */
-export declare const OUTCOME_MAX_PUBLIC_CONTEXT_CHARS = 400;