@happyvertical/smrt-sales 0.39.2

package/dist/referrals/services/AttributionService.d.ts

@@ -0,0 +1,248 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { AttributionExceptionCollection } from '../collections/AttributionExceptionCollection.js';
+import { AttributionPolicyCollection } from '../collections/AttributionPolicyCollection.js';
+import { ReferralCollection } from '../collections/ReferralCollection.js';
+import { ReferralProgramCollection } from '../collections/ReferralProgramCollection.js';
+import { ReferralTouchCollection } from '../collections/ReferralTouchCollection.js';
+import { ReferrerCollection } from '../collections/ReferrerCollection.js';
+import { AttributionException } from '../models/AttributionException.js';
+import { Referral } from '../models/Referral.js';
+import { ReferralTouch } from '../models/ReferralTouch.js';
+/**
+ * Thrown by {@link AttributionService.override} when the target already has
+ * a QUALIFIED referral: qualified credit is governed by its term snapshot
+ * and commission adjustments downstream — re-attribution would silently
+ * orphan agreed terms.
+ */
+export declare class QualifiedReferralOverrideError extends Error {
+    constructor(referralIds: string[]);
+}
+/** Collaborators for {@link AttributionService}. */
+export interface AttributionServiceDeps {
+    touches: ReferralTouchCollection;
+    referrals: ReferralCollection;
+    exceptions: AttributionExceptionCollection;
+    policies: AttributionPolicyCollection;
+    programs: ReferralProgramCollection;
+    referrers: ReferrerCollection;
+}
+/** Why {@link AttributionService.resolve} refused to attribute. */
+export type AttributionRefusalReason = 'existing_client_ineligible' | 'no_active_policy' | 'no_eligible_touches';
+/** Input for {@link AttributionService.resolve}. */
+export interface ResolveAttributionInput {
+    /** Generic qualifying target the referrals will point at. */
+    targetKind: string;
+    /** Identifier within the `targetKind` namespace. */
+    targetId: string;
+    /** The program to attribute under. */
+    programId: string;
+    /** Prospect identity to gather touches by (in addition to the target). */
+    subjectKind?: string;
+    /** Identifier within the `subjectKind` namespace. */
+    subjectId?: string;
+    /**
+     * The prospect's own profile id, when known — enables the self-referral
+     * eligibility check against each candidate referrer's `profileId`.
+     */
+    subjectProfileId?: string;
+    /**
+     * Caller's statement that the prospect is already a client. Policies with
+     * `allowExistingClients: false` refuse the whole resolution.
+     */
+    isExistingClient?: boolean;
+    /** Overrides the program's `defaultAttributionPolicyKey`. */
+    policyKey?: string;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/** Result of {@link AttributionService.resolve}. */
+export interface AttributionResolution {
+    /**
+     * The attributed referral(s): one for sole credit, several siblings for
+     * `split` mode. Empty when an exception was raised, the resolution was
+     * refused, or nothing was eligible.
+     */
+    referrals: Referral[];
+    /** The conflict parked for review, when the policy could not conclude. */
+    exception: AttributionException | null;
+    /** Why nothing was attributed, when refused outright. */
+    refused?: AttributionRefusalReason;
+}
+/** Input for {@link AttributionService.recordManualAssignment}. */
+export interface RecordManualAssignmentInput {
+    referrerId: string;
+    programId: string;
+    targetKind: string;
+    targetId: string;
+    /** Prospect identity; defaults to the target pair when omitted. */
+    subjectKind?: string;
+    subjectId?: string;
+    /** Who recorded the assignment (audit). Required. */
+    actorProfileId: string;
+    /** Free-form rationale recorded in the touch evidence. */
+    reason?: string;
+    /** When the assignment applies from; defaults to now. */
+    occurredAt?: Date;
+}
+/** One credit award inside a resolution/override. */
+export interface AttributionAward {
+    referrerId: string;
+    /** Credit share (0–1]; awards must sum to 1.0 (±0.0001). */
+    creditFraction: number;
+}
+/** Input for {@link AttributionService.resolveException}. */
+export interface ResolveExceptionInput {
+    exceptionId: string;
+    awards: AttributionAward[];
+    /** Non-empty rationale. Required — resolutions are audited. */
+    resolutionReason: string;
+    /** Who resolved the exception (audit). Required. */
+    actorProfileId: string;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/** Input for {@link AttributionService.override}. */
+export interface OverrideAttributionInput {
+    targetKind: string;
+    targetId: string;
+    programId: string;
+    awards: AttributionAward[];
+    /** Non-empty rationale. Required — overrides are audited. */
+    resolutionReason: string;
+    /** Who performed the override (audit). Required. */
+    actorProfileId: string;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/** Result of {@link AttributionService.resolveException} / {@link AttributionService.override}. */
+export interface AttributionAwardResult {
+    /** The attributed referral(s) the awards created. */
+    referrals: Referral[];
+    /** The resolved exception row auditing the decision. */
+    exception: AttributionException;
+}
+export declare class AttributionService {
+    private readonly deps;
+    constructor(deps: AttributionServiceDeps);
+    static create(classOptions?: SmrtClassOptions): Promise<AttributionService>;
+    /**
+     * Resolve attribution for one target under one program.
+     *
+     * IDEMPOTENT: existing non-disqualified `attributed`/`qualified`
+     * referrals for the target+program are returned as-is (no new rows), and
+     * an already-OPEN exception for the target+program is returned instead of
+     * a duplicate.
+     *
+     * Flow:
+     * 1. **Policy** — the program's `defaultAttributionPolicyKey` (or the
+     *    `policyKey` override) is resolved via `latestActiveByKey`; no active
+     *    version → `refused: 'no_active_policy'`.
+     * 2. **Existing-client gate** — `isExistingClient` with a policy that
+     *    disallows it → `refused: 'existing_client_ineligible'`.
+     * 3. **Candidates** — touches gathered by the subject pair (when given)
+     *    and by the target pair, deduplicated, restricted to the program and
+     *    to `occurredAt` within `[now - windowDays, now]`.
+     * 4. **Eligibility** — self-referrals (candidate referrer's `profileId`
+     *    equals `subjectProfileId`) are dropped unless the policy allows
+     *    them. Nothing left → `refused: 'no_eligible_touches'`.
+     * 5. **Conflicts** — `conflictBehavior: 'review'` with more than one
+     *    distinct eligible referrer, exact-timestamp ties between distinct
+     *    referrers in `first_touch`/`last_touch`, or competing manual
+     *    assignments in `assigned` mode → an OPEN AttributionException
+     *    carrying the candidates; NO referral rows.
+     * 6. **Credit** — otherwise the mode elects the winner(s):
+     *    `first_touch`/`last_touch` (earliest/latest), `assigned` (most
+     *    recent manual assignment; assignments beat clicks by definition),
+     *    or `split` (every distinct eligible referrer, equal fractions
+     *    rounded to 4 dp with the remainder on the last, one shared
+     *    `splitGroupId`). Referrals are created `pending → attributed` with
+     *    the policy pin, winning touch, `attributedAt = now`, and
+     *    `expiresAt = now + windowDays`.
+     */
+    resolve(input: ResolveAttributionInput): Promise<AttributionResolution>;
+    /**
+     * Record an operator's manual assignment as an immutable
+     * `manual_assignment` ReferralTouch (evidence carries the actor, reason,
+     * and target) and return it. The caller then runs {@link resolve} — under
+     * an `assigned`-mode policy the assignment wins over click evidence.
+     */
+    recordManualAssignment(input: RecordManualAssignmentInput): Promise<ReferralTouch>;
+    /**
+     * Resolve an OPEN exception by awarding credit explicitly.
+     *
+     * Requires a non-empty `resolutionReason` (throws otherwise) and awards
+     * whose `creditFraction`s sum to 1.0 (±0.0001) across distinct referrers.
+     * Creates the attributed referral(s) from the exception's target/program
+     * (split semantics — shared `splitGroupId` — when several awards), then
+     * marks the exception resolved (`resolutionMode: 'override'`, the award
+     * audit fields, `resolvedReferralIds`).
+     */
+    resolveException(input: ResolveExceptionInput): Promise<AttributionAwardResult>;
+    /**
+     * Re-attribute an already-attributed target.
+     *
+     * Requires a non-empty `resolutionReason` and awards summing to 1.0.
+     * REFUSES (throws {@link QualifiedReferralOverrideError}) when the target
+     * has a QUALIFIED referral — those are governed by term snapshots and
+     * commission adjustments downstream. Otherwise: disqualifies the existing
+     * `attributed` referrals for the target+program (stamping the audit
+     * exception's id into their metadata), creates the newly awarded
+     * attributed referral(s), and writes a RESOLVED AttributionException as
+     * the audit record (candidates = the displaced + awarded referrers).
+     *
+     * The new referrals inherit the POLICY PIN the displaced credit carried
+     * (an override re-decides WHO earned the introduction, not which policy
+     * version governed it); the program's current default active policy is
+     * the fallback when nothing was displaced.
+     */
+    override(input: OverrideAttributionInput): Promise<AttributionAwardResult>;
+    private requireProgram;
+    /**
+     * The active policy governing a resolution: the explicit `policyKey`
+     * override when given, else the program's default key; resolved to its
+     * latest ACTIVE version. `null` when no key or no active version.
+     */
+    private resolvePolicy;
+    /**
+     * Candidate touches for a resolution: gathered by the subject pair (when
+     * given) and by the target pair, deduplicated, restricted to the program,
+     * to `occurredAt` within `[now - windowDays, now]`, and to referrers that
+     * pass the self-referral gate. Sorted by `occurredAt` ascending.
+     */
+    private gatherEligibleTouches;
+    /** Create an OPEN exception carrying the competing candidates. */
+    private createOpenException;
+    /**
+     * The policy pin an exception was raised under (stamped into its
+     * metadata at creation); falls back to the program's current default
+     * active policy for exceptions created without one.
+     */
+    private resolvePolicyPin;
+    /**
+     * The policy pin an override re-attributes under: the pin the displaced
+     * credit carried (looking the exact version's `windowDays` back up for
+     * the new expiry), falling back to the program's current default active
+     * policy when nothing pinned was displaced.
+     */
+    private resolveOverridePolicyPin;
+    /**
+     * Create one referral as `pending`, transition it `pending → attributed`
+     * (stamping `attributedAt`), set the policy pin and expiry, and save.
+     */
+    private createAttributedReferral;
+    /**
+     * Equal split fractions for `n` referrers, each rounded to 4 decimal
+     * places, with the LAST adjusted so the set sums to exactly 1.0.
+     */
+    private static equalFractions;
+    private static assertResolutionReason;
+    /**
+     * Attribution decisions are audited — a blank actor would permanently
+     * resolve/override credit with an empty `resolvedByProfileId`, defeating
+     * the audit trail.
+     */
+    private static assertActor;
+    private static assertAwards;
+}
+export default AttributionService;
+//# sourceMappingURL=AttributionService.d.ts.map

package/dist/referrals/services/AttributionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionService.d.ts","sourceRoot":"","sources":["../../../src/referrals/services/AttributionService.ts"],"names":[],"mappings":"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"}

package/dist/referrals/services/ReferralCommissionService.d.ts

@@ -0,0 +1,91 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { Commission, CommissionCalculationService, CommissionCollection, CommissionComponentSkip, EarningEvent } from '../../commissions/index.js';
+import { ReferralCollection } from '../collections/ReferralCollection.js';
+import { ReferralTermSnapshotCollection } from '../collections/ReferralTermSnapshotCollection.js';
+import { ReferrerCollection } from '../collections/ReferrerCollection.js';
+/**
+ * The `termsSnapshotKind` every referral-bridged Commission carries —
+ * points `termsSnapshotId` at a ReferralTermSnapshot row.
+ */
+export declare const REFERRAL_TERMS_SNAPSHOT_KIND = "referral_term_snapshot";
+/** Collaborators for {@link ReferralCommissionService}. */
+export interface ReferralCommissionServiceDeps {
+    referrals: ReferralCollection;
+    snapshots: ReferralTermSnapshotCollection;
+    referrers: ReferrerCollection;
+    /** The commissions module's calculation service (same package). */
+    calculation: CommissionCalculationService;
+    /** The commissions module's commission collection (occurrence counting). */
+    commissions: CommissionCollection;
+}
+/** Input for {@link ReferralCommissionService.processEarningEvent}. */
+export interface ProcessEarningEventInput {
+    /** The (persisted) earning event to pay referrals from. */
+    event: EarningEvent;
+    /** Resolve qualified referrals by target … */
+    targetKind?: string;
+    targetId?: string;
+    /** … or name them explicitly (takes precedence over the target pair). */
+    referralIds?: string[];
+    /** Reserved clock override for symmetry with the sibling services. */
+    now?: Date;
+}
+/** Why a referral produced no calculation. */
+export type ReferralProcessingSkipReason = 'referral_not_found' | 'not_qualified' | 'missing_snapshot' | 'referrer_missing_earner' | 'tenant_mismatch';
+/** One referral the bridge skipped, and why. */
+export interface ReferralProcessingSkip {
+    referralId: string;
+    reason: ReferralProcessingSkipReason;
+}
+/** Per-referral calculation outcome. */
+export interface ReferralCommissionOutcome {
+    referralId: string;
+    /** Commissions newly created for this referral by THIS call. */
+    created: Commission[];
+    /** Idempotent replays — commissions that already existed. */
+    existing: Commission[];
+    /** Components the calculation declined, with reasons. */
+    skipped: CommissionComponentSkip[];
+}
+/** Result of {@link ReferralCommissionService.processEarningEvent}. */
+export interface ProcessEarningEventResult {
+    /** One entry per qualified referral that reached calculation. */
+    results: ReferralCommissionOutcome[];
+    /** Referrals that never reached calculation, with reasons. */
+    skippedReferrals: ReferralProcessingSkip[];
+}
+export declare class ReferralCommissionService {
+    private readonly deps;
+    constructor(deps: ReferralCommissionServiceDeps);
+    static create(classOptions?: SmrtClassOptions): Promise<ReferralCommissionService>;
+    /**
+     * Turn one earning event into Commissions for every qualified referral it
+     * concerns.
+     *
+     * Referral resolution: explicit `referralIds` when given (rows that are
+     * missing / not qualified are reported in `skippedReferrals`), else
+     * `findQualifiedByTarget(targetKind, targetId)`. One of the two forms is
+     * required.
+     *
+     * Per referral:
+     * 1. Load its ReferralTermSnapshot (`'missing_snapshot'` skip when the
+     *    pointer is empty/dangling).
+     * 2. Resolve the referrer's `earnerId`
+     *    (`'referrer_missing_earner'` skip when absent — roles without a
+     *    payout account cannot earn).
+     * 3. Delegate to `CommissionCalculationService.calculateForEvent` with
+     *    the snapshot's plan pin, FROZEN components, currency (mismatches
+     *    surface as the calc service's `currency_mismatch` skips),
+     *    clearingDays, the referral's `creditFraction` as the share, its
+     *    `splitGroupId`, the
+     *    `('referral_term_snapshot', snapshot.id)` terms reference, and an
+     *    occurrence resolver counting existing Commissions for
+     *    `(termsSnapshotId, componentKey)` from PRIOR events.
+     *
+     * Fully idempotent on replay: the calculation service's dedupe keys
+     * return prior rows in each outcome's `existing`.
+     */
+    processEarningEvent(input: ProcessEarningEventInput): Promise<ProcessEarningEventResult>;
+}
+export default ReferralCommissionService;
+//# sourceMappingURL=ReferralCommissionService.d.ts.map

package/dist/referrals/services/ReferralCommissionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralCommissionService.d.ts","sourceRoot":"","sources":["../../../src/referrals/services/ReferralCommissionService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EACL,KAAK,UAAU,EACf,4BAA4B,EAC5B,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E;;;GAGG;AACH,eAAO,MAAM,4BAA4B,2BAA2B,CAAC;AAErE,2DAA2D;AAC3D,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,8BAA8B,CAAC;IAC1C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,mEAAmE;IACnE,WAAW,EAAE,4BAA4B,CAAC;IAC1C,4EAA4E;IAC5E,WAAW,EAAE,oBAAoB,CAAC;CACnC;AAED,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,KAAK,EAAE,YAAY,CAAC;IACpB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sEAAsE;IACtE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,8CAA8C;AAC9C,MAAM,MAAM,4BAA4B,GACpC,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,yBAAyB,GACzB,iBAAiB,CAAC;AAEtB,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,4BAA4B,CAAC;CACtC;AAED,wCAAwC;AACxC,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,yDAAyD;IACzD,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,yBAAyB;IACxC,iEAAiE;IACjE,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,8DAA8D;IAC9D,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;CAC5C;AAED,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,6BAA6B;WAEnD,MAAM,CACjB,YAAY,GAAE,gBAAqB,GAClC,OAAO,CAAC,yBAAyB,CAAC;IAUrC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,mBAAmB,CACvB,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,yBAAyB,CAAC;CA4HtC;AAED,eAAe,yBAAyB,CAAC"}

package/dist/referrals/services/ReferralQualificationService.d.ts

@@ -0,0 +1,135 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { CommissionPlanCollection } from '../../commissions/index.js';
+import { AttributionPolicyCollection } from '../collections/AttributionPolicyCollection.js';
+import { ReferralAgreementCollection } from '../collections/ReferralAgreementCollection.js';
+import { ReferralCollection } from '../collections/ReferralCollection.js';
+import { ReferralTermSnapshotCollection } from '../collections/ReferralTermSnapshotCollection.js';
+import { ReferrerCollection } from '../collections/ReferrerCollection.js';
+import { Referral } from '../models/Referral.js';
+import { ReferralTermSnapshot } from '../models/ReferralTermSnapshot.js';
+/** Collaborators for {@link ReferralQualificationService}. */
+export interface ReferralQualificationServiceDeps {
+    referrals: ReferralCollection;
+    agreements: ReferralAgreementCollection;
+    /** The commissions module's plan collection (same package). */
+    plans: CommissionPlanCollection;
+    policies: AttributionPolicyCollection;
+    snapshots: ReferralTermSnapshotCollection;
+    referrers: ReferrerCollection;
+}
+/** Why {@link ReferralQualificationService.qualify} refused. */
+export type QualificationRefusalReason = 'not_attributed' | 'existing_client_ineligible' | 'self_referral_ineligible' | 'no_active_agreement' | 'no_active_plan';
+/** Input for {@link ReferralQualificationService.qualify}. */
+export interface QualifyReferralInput {
+    referralId: string;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+    /** Re-check flag: the prospect is already a client. */
+    isExistingClient?: boolean;
+    /** Re-check flag: the prospect's own profile id (self-referral gate). */
+    subjectProfileId?: string;
+}
+/** Result of {@link ReferralQualificationService.qualify}. */
+export interface QualifyReferralResult {
+    /** Whether the referral is (now or already) qualified. */
+    qualified: boolean;
+    /** `true` only when THIS call minted the snapshot. */
+    created: boolean;
+    /** The governing snapshot (`null` on refusal). */
+    snapshot: ReferralTermSnapshot | null;
+    /** The (re)loaded referral (`null` only when the id is unknown). */
+    referral: Referral | null;
+    /** Why qualification was refused, when it was. */
+    reason?: QualificationRefusalReason;
+}
+/** Input for {@link ReferralQualificationService.requalify}. */
+export interface RequalifyReferralInput {
+    referralId: string;
+    /** Non-empty rationale recorded in the referral metadata. Required. */
+    reason: string;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/** Result of {@link ReferralQualificationService.requalify}. */
+export interface RequalifyReferralResult {
+    /** Whether a new snapshot now governs the referral. */
+    requalified: boolean;
+    /** The NEW governing snapshot (`null` on refusal). */
+    snapshot: ReferralTermSnapshot | null;
+    /** The previously governing snapshot's id (kept as history). */
+    previousSnapshotId: string;
+    /** Why requalification was refused, when it was. */
+    reason?: 'no_active_agreement' | 'no_active_plan';
+}
+export declare class ReferralQualificationService {
+    private readonly deps;
+    constructor(deps: ReferralQualificationServiceDeps);
+    static create(classOptions?: SmrtClassOptions): Promise<ReferralQualificationService>;
+    /**
+     * Qualify an attributed referral.
+     *
+     * Flow:
+     * 1. **Status** — the referral must be `attributed`
+     *    (`reason: 'not_attributed'` otherwise). Already `qualified` →
+     *    IDEMPOTENT: the existing snapshot returns with `created: false`.
+     * 2. **Eligibility re-check** — the attribution-time policy version's
+     *    flags are re-applied against the caller's current knowledge:
+     *    `isExistingClient` (`existing_client_ineligible`) and
+     *    `subjectProfileId` vs the referrer's profile
+     *    (`self_referral_ineligible`). Refusals do NOT change the referral's
+     *    status — disqualification stays an explicit caller decision.
+     * 3. **Agreement** — the ACTIVE ReferralAgreement for
+     *    (referrerId, programId) effective at `now`
+     *    (`reason: 'no_active_agreement'` when none).
+     * 4. **Plan** — the agreement's pinned `commissionPlanVersion`, or the
+     *    latest active version when the pin is `0`; the resolved version must
+     *    be ACTIVE (`reason: 'no_active_plan'` otherwise).
+     * 5. **Snapshot** — mint the immutable ReferralTermSnapshot (frozen
+     *    component copy, currency, clearingDays, approvalMode, agreement +
+     *    plan + policy version refs), point `referral.snapshotId` at it, and
+     *    transition `attributed → qualified` (stamping `qualifiedAt`).
+     */
+    qualify(input: QualifyReferralInput): Promise<QualifyReferralResult>;
+    /**
+     * Explicitly re-snapshot a QUALIFIED referral under the CURRENT terms —
+     * the "amendment explicitly applied" path: after a plan/agreement
+     * amendment, earnings keep flowing through the OLD snapshot until an
+     * operator invokes this.
+     *
+     * Creates a NEW snapshot from the currently active agreement/plan,
+     * repoints `referral.snapshotId`, leaves the old snapshot row untouched
+     * (history — commissions it produced still reference it), and appends
+     * `{ at, reason, fromSnapshotId, toSnapshotId }` to the referral
+     * metadata's `requalifications` array.
+     *
+     * Throws on misuse (unknown referral, non-qualified status, empty
+     * reason); refuses with a typed reason when no active agreement/plan
+     * currently governs.
+     */
+    requalify(input: RequalifyReferralInput): Promise<RequalifyReferralResult>;
+    private requireReferral;
+    /**
+     * The exact policy version pinned on the referral, when it exists —
+     * resolved in the REFERRAL's tenant lane (global fallback): background
+     * qualification runs without ambient tenant context, and another
+     * tenant's same-keyed policy must never supply the eligibility flags.
+     */
+    private findPolicyVersion;
+    /**
+     * The CommissionPlan an agreement binds: the pinned version when
+     * `commissionPlanVersion > 0`, else the latest active version. Either
+     * way the resolved row must be ACTIVE — superseded/retired terms cannot
+     * govern a NEW qualification (an amendment should be activated, or the
+     * agreement re-pinned, first).
+     */
+    private resolvePlan;
+    /**
+     * Mint the immutable snapshot: agreement/plan/policy refs plus the FROZEN
+     * component copy and the calculation inputs. `planVersion` records the
+     * RESOLVED version — this is where an unpinned (`0`) agreement version
+     * gets pinned.
+     */
+    private mintSnapshot;
+}
+export default ReferralQualificationService;
+//# sourceMappingURL=ReferralQualificationService.d.ts.map

package/dist/referrals/services/ReferralQualificationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralQualificationService.d.ts","sourceRoot":"","sources":["../../../src/referrals/services/ReferralQualificationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAEL,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,2BAA2B,EAAE,MAAM,+CAA+C,CAAC;AAC5F,OAAO,EAAE,2BAA2B,EAAE,MAAM,+CAA+C,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,8DAA8D;AAC9D,MAAM,WAAW,gCAAgC;IAC/C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,UAAU,EAAE,2BAA2B,CAAC;IACxC,+DAA+D;IAC/D,KAAK,EAAE,wBAAwB,CAAC;IAChC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,SAAS,EAAE,8BAA8B,CAAC;IAC1C,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED,gEAAgE;AAChE,MAAM,MAAM,0BAA0B,GAClC,gBAAgB,GAChB,4BAA4B,GAC5B,0BAA0B,GAC1B,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,oEAAoE;IACpE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE,0BAA0B,CAAC;CACrC;AAED,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,gEAAgE;AAChE,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,sDAAsD;IACtD,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,gEAAgE;IAChE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,MAAM,CAAC,EAAE,qBAAqB,GAAG,gBAAgB,CAAC;CACnD;AAED,qBAAa,4BAA4B;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,gCAAgC;WAEtD,MAAM,CACjB,YAAY,GAAE,gBAAqB,GAClC,OAAO,CAAC,4BAA4B,CAAC;IAWxC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA2F1E;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CACb,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC;YA2DrB,eAAe;IAa7B;;;;;OAKG;YACW,iBAAiB;IAgB/B;;;;;;OAMG;YACW,WAAW;IAiCzB;;;;;OAKG;YACW,YAAY;CAoB3B;AAED,eAAe,4BAA4B,CAAC"}