@arkyc/core 1.2.10 → 2.0.0

package/dist/decision.d.mts

@@ -1,4 +1,4 @@
-import { DecisionReason, VerificationDecision, VerificationThresholds } from "@arkyc/types";
+import { DecisionReason, RiskSignal, VerificationDecision, VerificationThresholds } from "@arkyc/types";
 
 //#region src/decision.d.ts
 /** Document signals fed to the decision engine. */
@@ -48,6 +48,8 @@ interface DecisionInput {
   liveness: DecisionLivenessInput;
   faceMatch: DecisionFaceMatchInput;
   address: DecisionAddressInput;
+  /** Fraud and compliance signals, with their policy-resolved severity. */
+  signals?: RiskSignal[];
 }
 /** The decision engine's verdict for a session. */
 interface DecisionResult {
@@ -66,8 +68,9 @@ declare class DecisionEngine {
    * evaluated in a fixed priority order so the result is deterministic.
    *
    * Reject precedence:  expired → liveness failed → face-match failed
+   *                       → address failed → reject signals
    * Review precedence:   multiple faces → low quality → low OCR
-   *                       → low liveness → low face-match
+   *                       → low liveness → low face-match → address → review signals
    *
    * @param input
    * @param thresholds

package/dist/decision.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"decision.d.mts","names":[],"sources":["../src/decision.ts"],"mappings":";;;;UAMiB,qBAAA;EAAA;EAEf,YAAA;;EAEA,aAAA;EAFA;EAIA,OAAA;AAAA;;UAIe,qBAAA;EACf,MAAA;EADoC;EAGpC,KAAA;EAHoC;EAKpC,aAAA;AAAA;;UAIe,sBAAA;EACf,MAAA;EADe;EAGf,eAAe;AAAA;;UAIA,oBAAA;EACf,MAAA;EADmC;EAGnC,KAAA;EAHmC;;;;;EASnC,MAAA;EAMS;AAIX;;;;EAJE,SAAA;AAAA;;UAIe,aAAA;EACf,QAAA,EAAU,qBAAA;EACV,QAAA,EAAU,qBAAA;EACV,SAAA,EAAW,sBAAA;EACX,OAAA,EAAS,oBAAA;AAAA;;UAIM,cAAA;EACf,QAAA,EAAU,oBAAA;EACV,MAAA,EAAQ,cAAc;EANO;EAQ7B,SAAA;AAAA;;cAIW,cAAA;EANW;;;;;;;AAEb;AAIX;;;;;;;EANwB,OAsBf,MAAA,CAAO,KAAA,EAAO,aAAA,EAAe,UAAA,GAAa,OAAA,CAAQ,sBAAA,IAA0B,cAAA;AAAA"}
+{"version":3,"file":"decision.d.mts","names":[],"sources":["../src/decision.ts"],"mappings":";;;;UAOiB,qBAAA;EAAA;EAEf,YAAA;;EAEA,aAAA;EAFA;EAIA,OAAA;AAAA;;UAIe,qBAAA;EACf,MAAA;EADoC;EAGpC,KAAA;EAHoC;EAKpC,aAAA;AAAA;;UAIe,sBAAA;EACf,MAAA;EADe;EAGf,eAAe;AAAA;;UAIA,oBAAA;EACf,MAAA;EADmC;EAGnC,KAAA;EAHmC;;;;;EASnC,MAAA;EAMS;AAIX;;;;EAJE,SAAA;AAAA;;UAIe,aAAA;EACf,QAAA,EAAU,qBAAA;EACV,QAAA,EAAU,qBAAA;EACV,SAAA,EAAW,sBAAA;EACX,OAAA,EAAS,oBAAA;EAFT;EAIA,OAAA,GAAU,UAAA;AAAA;;UAIK,cAAA;EACf,QAAA,EAAU,oBAAA;EACV,MAAA,EAAQ,cAAc;EANZ;EAQV,SAAA;AAAA;AAJF;AAAA,cAQa,cAAA;;;;;;;;;AAJF;AAIX;;;;;;;SAiBS,MAAA,CAAO,KAAA,EAAO,aAAA,EAAe,UAAA,GAAa,OAAA,CAAQ,sBAAA,IAA0B,cAAA;AAAA"}

package/dist/decision.mjs

@@ -1,5 +1,6 @@
 import { Thresholds } from "./thresholds.mjs";
 import { Risk } from "./risk.mjs";
+import { RiskSignals } from "./signals.mjs";
 //#region src/decision.ts
 /** Deterministic verification decision engine. */
 var DecisionEngine = class {
@@ -11,8 +12,9 @@ var DecisionEngine = class {
 	* evaluated in a fixed priority order so the result is deterministic.
 	*
 	* Reject precedence:  expired → liveness failed → face-match failed
+	*                       → address failed → reject signals
 	* Review precedence:   multiple faces → low quality → low OCR
-	*                       → low liveness → low face-match
+	*                       → low liveness → low face-match → address → review signals
 	*
 	* @param input
 	* @param thresholds
@@ -30,6 +32,9 @@ var DecisionEngine = class {
 		if (!input.liveness.passed) return verdict("rejected", "LIVENESS_FAILED");
 		if (!input.faceMatch.passed) return verdict("rejected", "FACE_MATCH_FAILED");
 		if (!input.address.passed && input.address.onFail === "reject") return verdict("rejected", "ADDRESS_VERIFICATION_FAILED");
+		const signals = input.signals ?? [];
+		const rejectSignal = RiskSignals.reasonFor(signals, "reject");
+		if (rejectSignal) return verdict("rejected", rejectSignal);
 		if (input.liveness.multipleFaces === true) return verdict("requires_review", "MULTIPLE_FACES_DETECTED");
 		if (input.document.qualityScore < t.documentQualityThreshold) return verdict("requires_review", "LOW_DOCUMENT_QUALITY");
 		if (input.document.ocrConfidence < t.ocrConfidenceThreshold) return verdict("requires_review", "OCR_LOW_CONFIDENCE");
@@ -37,6 +42,8 @@ var DecisionEngine = class {
 		if (input.faceMatch.similarityScore < t.faceMatchThreshold) return verdict("requires_review", "FACE_MATCH_LOW_CONFIDENCE");
 		if (!input.address.passed) return verdict("requires_review", "ADDRESS_VERIFICATION_FAILED");
 		if (input.address.score < (input.address.threshold ?? t.addressThreshold)) return verdict("requires_review", "ADDRESS_LOW_CONFIDENCE");
+		const reviewSignal = RiskSignals.reasonFor(signals, "review");
+		if (reviewSignal) return verdict("requires_review", reviewSignal);
 		return verdict("approved", "AUTO_APPROVED");
 	}
 };

package/dist/decision.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"decision.mjs","names":[],"sources":["../src/decision.ts"],"sourcesContent":["import type { DecisionReason, VerificationDecision, VerificationThresholds } from '@arkyc/types'\n\nimport { Risk } from './risk'\nimport { Thresholds } from './thresholds'\n\n/** Document signals fed to the decision engine. */\nexport interface DecisionDocumentInput {\n  /** Document image quality in [0, 1]. */\n  qualityScore: number\n  /** OCR extraction confidence in [0, 1]. */\n  ocrConfidence: number\n  /** Whether the document is past its expiry date. */\n  expired: boolean\n}\n\n/** Liveness signals fed to the decision engine. */\nexport interface DecisionLivenessInput {\n  passed: boolean\n  /** Liveness confidence in [0, 1]. */\n  score: number\n  /** Whether more than one face was detected in the selfie/liveness frame. */\n  multipleFaces?: boolean\n}\n\n/** Face-match signals fed to the decision engine. */\nexport interface DecisionFaceMatchInput {\n  passed: boolean\n  /** Similarity between document portrait and selfie in [0, 1]. */\n  similarityScore: number\n}\n\n/** Address-verification signals fed to the decision engine. */\nexport interface DecisionAddressInput {\n  passed: boolean\n  /** Overall address-verification confidence in [0, 1]. */\n  score: number\n  /**\n   * What a failed result does: flag for `review` (default) or `reject`, driven\n   * by the workflow's address config. A low-confidence (but not failed) result\n   * is always review, never a reject.\n   */\n  onFail?: 'review' | 'reject'\n  /**\n   * Workflow-configured minimum confidence to auto-verify the address. A passed\n   * address scoring below this routes to manual review. Falls back to the\n   * project `addressThreshold` when omitted.\n   */\n  threshold?: number\n}\n\n/** The complete set of signals the decision engine evaluates. */\nexport interface DecisionInput {\n  document: DecisionDocumentInput\n  liveness: DecisionLivenessInput\n  faceMatch: DecisionFaceMatchInput\n  address: DecisionAddressInput\n}\n\n/** The decision engine's verdict for a session. */\nexport interface DecisionResult {\n  decision: VerificationDecision\n  reason: DecisionReason\n  /** Aggregate risk score in [0, 1] (higher = riskier). */\n  riskScore: number\n}\n\n/** Deterministic verification decision engine. */\nexport class DecisionEngine {\n  /**\n   * Decide a verification outcome from the gathered signals.\n   *\n   * Hard failures reject outright; borderline/low-confidence signals route to\n   * manual review; everything clearing its threshold is auto-approved. Checks are\n   * evaluated in a fixed priority order so the result is deterministic.\n   *\n   * Reject precedence:  expired → liveness failed → face-match failed\n   * Review precedence:   multiple faces → low quality → low OCR\n   *                       → low liveness → low face-match\n   *\n   * @param input\n   * @param thresholds\n   * @returns\n   */\n  static decide(input: DecisionInput, thresholds?: Partial<VerificationThresholds>): DecisionResult {\n    const t = Thresholds.resolve(thresholds)\n    const riskScore = Risk.score(input)\n    const verdict = (decision: VerificationDecision, reason: DecisionReason): DecisionResult => ({\n      decision,\n      reason,\n      riskScore,\n    })\n\n    // --- Hard rejections (highest priority) ---\n    if (input.document.expired) {\n      return verdict('rejected', 'DOCUMENT_EXPIRED')\n    }\n    if (!input.liveness.passed) {\n      return verdict('rejected', 'LIVENESS_FAILED')\n    }\n    if (!input.faceMatch.passed) {\n      return verdict('rejected', 'FACE_MATCH_FAILED')\n    }\n    // Address only rejects when the workflow opts in (`on_fail: 'reject'`);\n    // otherwise a failed address falls through to manual review below.\n    if (!input.address.passed && input.address.onFail === 'reject') {\n      return verdict('rejected', 'ADDRESS_VERIFICATION_FAILED')\n    }\n\n    // --- Manual review (borderline / ambiguous signals) ---\n    if (input.liveness.multipleFaces === true) {\n      return verdict('requires_review', 'MULTIPLE_FACES_DETECTED')\n    }\n    if (input.document.qualityScore < t.documentQualityThreshold) {\n      return verdict('requires_review', 'LOW_DOCUMENT_QUALITY')\n    }\n    if (input.document.ocrConfidence < t.ocrConfidenceThreshold) {\n      return verdict('requires_review', 'OCR_LOW_CONFIDENCE')\n    }\n    if (input.liveness.score < t.livenessThreshold) {\n      return verdict('requires_review', 'LIVENESS_LOW_CONFIDENCE')\n    }\n    if (input.faceMatch.similarityScore < t.faceMatchThreshold) {\n      return verdict('requires_review', 'FACE_MATCH_LOW_CONFIDENCE')\n    }\n    // A failed address that didn't reject (on_fail: 'review') lands here.\n    if (!input.address.passed) {\n      return verdict('requires_review', 'ADDRESS_VERIFICATION_FAILED')\n    }\n    // Auto-verify gate: the workflow can set its own minimum address confidence;\n    // a passed address below it is held for manual review (never rejected here).\n    if (input.address.score < (input.address.threshold ?? t.addressThreshold)) {\n      return verdict('requires_review', 'ADDRESS_LOW_CONFIDENCE')\n    }\n\n    // --- All checks cleared ---\n    return verdict('approved', 'AUTO_APPROVED')\n  }\n}\n"],"mappings":";;;;AAmEA,IAAa,iBAAb,MAA4B;;;;;;;;;;;;;;;;CAgB1B,OAAO,OAAO,OAAsB,YAA8D;EAChG,MAAM,IAAI,WAAW,QAAQ,UAAU;EACvC,MAAM,YAAY,KAAK,MAAM,KAAK;EAClC,MAAM,WAAW,UAAgC,YAA4C;GAC3F;GACA;GACA;EACF;EAGA,IAAI,MAAM,SAAS,SACjB,OAAO,QAAQ,YAAY,kBAAkB;EAE/C,IAAI,CAAC,MAAM,SAAS,QAClB,OAAO,QAAQ,YAAY,iBAAiB;EAE9C,IAAI,CAAC,MAAM,UAAU,QACnB,OAAO,QAAQ,YAAY,mBAAmB;EAIhD,IAAI,CAAC,MAAM,QAAQ,UAAU,MAAM,QAAQ,WAAW,UACpD,OAAO,QAAQ,YAAY,6BAA6B;EAI1D,IAAI,MAAM,SAAS,kBAAkB,MACnC,OAAO,QAAQ,mBAAmB,yBAAyB;EAE7D,IAAI,MAAM,SAAS,eAAe,EAAE,0BAClC,OAAO,QAAQ,mBAAmB,sBAAsB;EAE1D,IAAI,MAAM,SAAS,gBAAgB,EAAE,wBACnC,OAAO,QAAQ,mBAAmB,oBAAoB;EAExD,IAAI,MAAM,SAAS,QAAQ,EAAE,mBAC3B,OAAO,QAAQ,mBAAmB,yBAAyB;EAE7D,IAAI,MAAM,UAAU,kBAAkB,EAAE,oBACtC,OAAO,QAAQ,mBAAmB,2BAA2B;EAG/D,IAAI,CAAC,MAAM,QAAQ,QACjB,OAAO,QAAQ,mBAAmB,6BAA6B;EAIjE,IAAI,MAAM,QAAQ,SAAS,MAAM,QAAQ,aAAa,EAAE,mBACtD,OAAO,QAAQ,mBAAmB,wBAAwB;EAI5D,OAAO,QAAQ,YAAY,eAAe;CAC5C;AACF"}
+{"version":3,"file":"decision.mjs","names":[],"sources":["../src/decision.ts"],"sourcesContent":["import type { DecisionReason, RiskSignal, VerificationDecision, VerificationThresholds } from '@arkyc/types'\n\nimport { Risk } from './risk'\nimport { RiskSignals } from './signals'\nimport { Thresholds } from './thresholds'\n\n/** Document signals fed to the decision engine. */\nexport interface DecisionDocumentInput {\n  /** Document image quality in [0, 1]. */\n  qualityScore: number\n  /** OCR extraction confidence in [0, 1]. */\n  ocrConfidence: number\n  /** Whether the document is past its expiry date. */\n  expired: boolean\n}\n\n/** Liveness signals fed to the decision engine. */\nexport interface DecisionLivenessInput {\n  passed: boolean\n  /** Liveness confidence in [0, 1]. */\n  score: number\n  /** Whether more than one face was detected in the selfie/liveness frame. */\n  multipleFaces?: boolean\n}\n\n/** Face-match signals fed to the decision engine. */\nexport interface DecisionFaceMatchInput {\n  passed: boolean\n  /** Similarity between document portrait and selfie in [0, 1]. */\n  similarityScore: number\n}\n\n/** Address-verification signals fed to the decision engine. */\nexport interface DecisionAddressInput {\n  passed: boolean\n  /** Overall address-verification confidence in [0, 1]. */\n  score: number\n  /**\n   * What a failed result does: flag for `review` (default) or `reject`, driven\n   * by the workflow's address config. A low-confidence (but not failed) result\n   * is always review, never a reject.\n   */\n  onFail?: 'review' | 'reject'\n  /**\n   * Workflow-configured minimum confidence to auto-verify the address. A passed\n   * address scoring below this routes to manual review. Falls back to the\n   * project `addressThreshold` when omitted.\n   */\n  threshold?: number\n}\n\n/** The complete set of signals the decision engine evaluates. */\nexport interface DecisionInput {\n  document: DecisionDocumentInput\n  liveness: DecisionLivenessInput\n  faceMatch: DecisionFaceMatchInput\n  address: DecisionAddressInput\n  /** Fraud and compliance signals, with their policy-resolved severity. */\n  signals?: RiskSignal[]\n}\n\n/** The decision engine's verdict for a session. */\nexport interface DecisionResult {\n  decision: VerificationDecision\n  reason: DecisionReason\n  /** Aggregate risk score in [0, 1] (higher = riskier). */\n  riskScore: number\n}\n\n/** Deterministic verification decision engine. */\nexport class DecisionEngine {\n  /**\n   * Decide a verification outcome from the gathered signals.\n   *\n   * Hard failures reject outright; borderline/low-confidence signals route to\n   * manual review; everything clearing its threshold is auto-approved. Checks are\n   * evaluated in a fixed priority order so the result is deterministic.\n   *\n   * Reject precedence:  expired → liveness failed → face-match failed\n   *                       → address failed → reject signals\n   * Review precedence:   multiple faces → low quality → low OCR\n   *                       → low liveness → low face-match → address → review signals\n   *\n   * @param input\n   * @param thresholds\n   * @returns\n   */\n  static decide(input: DecisionInput, thresholds?: Partial<VerificationThresholds>): DecisionResult {\n    const t = Thresholds.resolve(thresholds)\n    const riskScore = Risk.score(input)\n    const verdict = (decision: VerificationDecision, reason: DecisionReason): DecisionResult => ({\n      decision,\n      reason,\n      riskScore,\n    })\n\n    // --- Hard rejections (highest priority) ---\n    if (input.document.expired) {\n      return verdict('rejected', 'DOCUMENT_EXPIRED')\n    }\n    if (!input.liveness.passed) {\n      return verdict('rejected', 'LIVENESS_FAILED')\n    }\n    if (!input.faceMatch.passed) {\n      return verdict('rejected', 'FACE_MATCH_FAILED')\n    }\n    // Address only rejects when the workflow opts in (`on_fail: 'reject'`);\n    // otherwise a failed address falls through to manual review below.\n    if (!input.address.passed && input.address.onFail === 'reject') {\n      return verdict('rejected', 'ADDRESS_VERIFICATION_FAILED')\n    }\n\n    const signals = input.signals ?? []\n    const rejectSignal = RiskSignals.reasonFor(signals, 'reject')\n    if (rejectSignal) {\n      return verdict('rejected', rejectSignal)\n    }\n\n    // --- Manual review (borderline / ambiguous signals) ---\n    if (input.liveness.multipleFaces === true) {\n      return verdict('requires_review', 'MULTIPLE_FACES_DETECTED')\n    }\n    if (input.document.qualityScore < t.documentQualityThreshold) {\n      return verdict('requires_review', 'LOW_DOCUMENT_QUALITY')\n    }\n    if (input.document.ocrConfidence < t.ocrConfidenceThreshold) {\n      return verdict('requires_review', 'OCR_LOW_CONFIDENCE')\n    }\n    if (input.liveness.score < t.livenessThreshold) {\n      return verdict('requires_review', 'LIVENESS_LOW_CONFIDENCE')\n    }\n    if (input.faceMatch.similarityScore < t.faceMatchThreshold) {\n      return verdict('requires_review', 'FACE_MATCH_LOW_CONFIDENCE')\n    }\n    // A failed address that didn't reject (on_fail: 'review') lands here.\n    if (!input.address.passed) {\n      return verdict('requires_review', 'ADDRESS_VERIFICATION_FAILED')\n    }\n    // Auto-verify gate: the workflow can set its own minimum address confidence;\n    // a passed address below it is held for manual review (never rejected here).\n    if (input.address.score < (input.address.threshold ?? t.addressThreshold)) {\n      return verdict('requires_review', 'ADDRESS_LOW_CONFIDENCE')\n    }\n\n    const reviewSignal = RiskSignals.reasonFor(signals, 'review')\n    if (reviewSignal) {\n      return verdict('requires_review', reviewSignal)\n    }\n\n    // --- All checks cleared ---\n    return verdict('approved', 'AUTO_APPROVED')\n  }\n}\n"],"mappings":";;;;;AAsEA,IAAa,iBAAb,MAA4B;;;;;;;;;;;;;;;;;CAiB1B,OAAO,OAAO,OAAsB,YAA8D;EAChG,MAAM,IAAI,WAAW,QAAQ,UAAU;EACvC,MAAM,YAAY,KAAK,MAAM,KAAK;EAClC,MAAM,WAAW,UAAgC,YAA4C;GAC3F;GACA;GACA;EACF;EAGA,IAAI,MAAM,SAAS,SACjB,OAAO,QAAQ,YAAY,kBAAkB;EAE/C,IAAI,CAAC,MAAM,SAAS,QAClB,OAAO,QAAQ,YAAY,iBAAiB;EAE9C,IAAI,CAAC,MAAM,UAAU,QACnB,OAAO,QAAQ,YAAY,mBAAmB;EAIhD,IAAI,CAAC,MAAM,QAAQ,UAAU,MAAM,QAAQ,WAAW,UACpD,OAAO,QAAQ,YAAY,6BAA6B;EAG1D,MAAM,UAAU,MAAM,WAAW,CAAC;EAClC,MAAM,eAAe,YAAY,UAAU,SAAS,QAAQ;EAC5D,IAAI,cACF,OAAO,QAAQ,YAAY,YAAY;EAIzC,IAAI,MAAM,SAAS,kBAAkB,MACnC,OAAO,QAAQ,mBAAmB,yBAAyB;EAE7D,IAAI,MAAM,SAAS,eAAe,EAAE,0BAClC,OAAO,QAAQ,mBAAmB,sBAAsB;EAE1D,IAAI,MAAM,SAAS,gBAAgB,EAAE,wBACnC,OAAO,QAAQ,mBAAmB,oBAAoB;EAExD,IAAI,MAAM,SAAS,QAAQ,EAAE,mBAC3B,OAAO,QAAQ,mBAAmB,yBAAyB;EAE7D,IAAI,MAAM,UAAU,kBAAkB,EAAE,oBACtC,OAAO,QAAQ,mBAAmB,2BAA2B;EAG/D,IAAI,CAAC,MAAM,QAAQ,QACjB,OAAO,QAAQ,mBAAmB,6BAA6B;EAIjE,IAAI,MAAM,QAAQ,SAAS,MAAM,QAAQ,aAAa,EAAE,mBACtD,OAAO,QAAQ,mBAAmB,wBAAwB;EAG5D,MAAM,eAAe,YAAY,UAAU,SAAS,QAAQ;EAC5D,IAAI,cACF,OAAO,QAAQ,mBAAmB,YAAY;EAIhD,OAAO,QAAQ,YAAY,eAAe;CAC5C;AACF"}

package/dist/index.d.mts

@@ -2,7 +2,8 @@ import { Thresholds } from "./thresholds.mjs";
 import { InvalidStatusTransitionError, StatusMachine } from "./status.mjs";
 import { DecisionAddressInput, DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult } from "./decision.mjs";
 import { Risk } from "./risk.mjs";
+import { RiskSignals } from "./signals.mjs";
 import { SessionRules } from "./session.mjs";
 import { Normalize, SessionSignals } from "./normalize.mjs";
 import { OrganizationContext, OrganizationProjectContext, OrganizationScopeError } from "./context.mjs";
-export { DecisionAddressInput, DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult, InvalidStatusTransitionError, Normalize, OrganizationContext, OrganizationProjectContext, OrganizationScopeError, Risk, SessionRules, SessionSignals, StatusMachine, Thresholds };
+export { DecisionAddressInput, DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult, InvalidStatusTransitionError, Normalize, OrganizationContext, OrganizationProjectContext, OrganizationScopeError, Risk, RiskSignals, SessionRules, SessionSignals, StatusMachine, Thresholds };

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { Thresholds } from "./thresholds.mjs";
 import { InvalidStatusTransitionError, StatusMachine } from "./status.mjs";
 import { Risk } from "./risk.mjs";
+import { RiskSignals } from "./signals.mjs";
 import { DecisionEngine } from "./decision.mjs";
 import { SessionRules } from "./session.mjs";
 import { Normalize } from "./normalize.mjs";
 import { OrganizationContext, OrganizationScopeError } from "./context.mjs";
-export { DecisionEngine, InvalidStatusTransitionError, Normalize, OrganizationContext, OrganizationScopeError, Risk, SessionRules, StatusMachine, Thresholds };
+export { DecisionEngine, InvalidStatusTransitionError, Normalize, OrganizationContext, OrganizationScopeError, Risk, RiskSignals, SessionRules, StatusMachine, Thresholds };

package/dist/risk.d.mts

@@ -16,7 +16,9 @@ declare class Risk {
    * The baseline is the inverse of the mean of the positive signals (document
    * quality, OCR confidence, liveness score, face-match similarity). Hard failure
    * signals (expired document, failed liveness/face-match, multiple faces) floor
-   * the risk near the top of the range so risky sessions never look safe.
+   * the risk near the top of the range so risky sessions never look safe. Each
+   * non-informational signal compounds the remaining headroom by its score, and
+   * a rejecting signal floors it like a hard failure.
    *
    * @param input
    * @returns

package/dist/risk.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"risk.d.mts","names":[],"sources":["../src/risk.ts"],"mappings":";;;;cASa,IAAA;EAAA;;;;;;EAAA,OAOJ,OAAA,CAAQ,KAAA;EAgBK;;;AAAa;;;;;;;;EAAb,OAAb,KAAA,CAAM,KAAA,EAAO,aAAa;AAAA"}
+{"version":3,"file":"risk.d.mts","names":[],"sources":["../src/risk.ts"],"mappings":";;;;cASa,IAAA;EAAA;;;;;;EAAA,OAOJ,OAAA,CAAQ,KAAA;EAkBK;;;AAAa;;;;;;;;;;EAAb,OAAb,KAAA,CAAM,KAAA,EAAO,aAAa;AAAA"}

package/dist/risk.mjs

@@ -22,7 +22,9 @@ var Risk = class Risk {
 	* The baseline is the inverse of the mean of the positive signals (document
 	* quality, OCR confidence, liveness score, face-match similarity). Hard failure
 	* signals (expired document, failed liveness/face-match, multiple faces) floor
-	* the risk near the top of the range so risky sessions never look safe.
+	* the risk near the top of the range so risky sessions never look safe. Each
+	* non-informational signal compounds the remaining headroom by its score, and
+	* a rejecting signal floors it like a hard failure.
 	*
 	* @param input
 	* @returns
@@ -35,7 +37,10 @@ var Risk = class Risk {
 			input.faceMatch.similarityScore,
 			input.address.score
 		].map(Risk.clamp01));
-		if (input.document.expired || !input.liveness.passed || !input.faceMatch.passed || input.liveness.multipleFaces === true || !input.address.passed && input.address.onFail === "reject") risk = Math.max(risk, .9);
+		const hardFailure = input.document.expired || !input.liveness.passed || !input.faceMatch.passed || input.liveness.multipleFaces === true || !input.address.passed && input.address.onFail === "reject";
+		const signals = (input.signals ?? []).filter((signal) => signal.severity !== "info");
+		for (const signal of signals) risk = 1 - (1 - risk) * (1 - Risk.clamp01(signal.score));
+		if (hardFailure || signals.some((signal) => signal.severity === "reject")) risk = Math.max(risk, .9);
 		return Risk.clamp01(risk);
 	}
 };

package/dist/risk.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"risk.mjs","names":[],"sources":["../src/risk.ts"],"sourcesContent":["import type { DecisionInput } from './decision'\n\n/** Average of a list of numbers; 0 for an empty list. */\nfunction mean(values: number[]): number {\n  if (values.length === 0) return 0\n  return values.reduce((sum, v) => sum + v, 0) / values.length\n}\n\n/** Aggregate risk scoring for a verification session. */\nexport class Risk {\n  /**\n   * Clamp a number into the [0, 1] range.\n   *\n   * @param value\n   * @returns\n   */\n  static clamp01(value: number): number {\n    if (Number.isNaN(value)) return 0\n    return Math.min(1, Math.max(0, value))\n  }\n\n  /**\n   * Compute an aggregate risk score in [0, 1] for a session (higher = riskier).\n   *\n   * The baseline is the inverse of the mean of the positive signals (document\n   * quality, OCR confidence, liveness score, face-match similarity). Hard failure\n   * signals (expired document, failed liveness/face-match, multiple faces) floor\n   * the risk near the top of the range so risky sessions never look safe.\n   *\n   * @param input\n   * @returns\n   */\n  static score(input: DecisionInput): number {\n    const positives = [\n      input.document.qualityScore,\n      input.document.ocrConfidence,\n      input.liveness.score,\n      input.faceMatch.similarityScore,\n      input.address.score,\n    ].map(Risk.clamp01)\n\n    let risk = 1 - mean(positives)\n\n    const hardFailure =\n      input.document.expired ||\n      !input.liveness.passed ||\n      !input.faceMatch.passed ||\n      input.liveness.multipleFaces === true ||\n      // A failed address only floors risk when it's a rejecting failure.\n      (!input.address.passed && input.address.onFail === 'reject')\n\n    if (hardFailure) {\n      risk = Math.max(risk, 0.9)\n    }\n\n    return Risk.clamp01(risk)\n  }\n}\n"],"mappings":";;AAGA,SAAS,KAAK,QAA0B;CACtC,IAAI,OAAO,WAAW,GAAG,OAAO;CAChC,OAAO,OAAO,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC,IAAI,OAAO;AACxD;;AAGA,IAAa,OAAb,MAAa,KAAK;;;;;;;CAOhB,OAAO,QAAQ,OAAuB;EACpC,IAAI,OAAO,MAAM,KAAK,GAAG,OAAO;EAChC,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,KAAK,CAAC;CACvC;;;;;;;;;;;;CAaA,OAAO,MAAM,OAA8B;EASzC,IAAI,OAAO,IAAI,KARG;GAChB,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,UAAU;GAChB,MAAM,QAAQ;EAChB,CAAC,CAAC,IAAI,KAAK,OAEiB,CAAC;EAU7B,IAPE,MAAM,SAAS,WACf,CAAC,MAAM,SAAS,UAChB,CAAC,MAAM,UAAU,UACjB,MAAM,SAAS,kBAAkB,QAEhC,CAAC,MAAM,QAAQ,UAAU,MAAM,QAAQ,WAAW,UAGnD,OAAO,KAAK,IAAI,MAAM,EAAG;EAG3B,OAAO,KAAK,QAAQ,IAAI;CAC1B;AACF"}
+{"version":3,"file":"risk.mjs","names":[],"sources":["../src/risk.ts"],"sourcesContent":["import type { DecisionInput } from './decision'\n\n/** Average of a list of numbers; 0 for an empty list. */\nfunction mean(values: number[]): number {\n  if (values.length === 0) return 0\n  return values.reduce((sum, v) => sum + v, 0) / values.length\n}\n\n/** Aggregate risk scoring for a verification session. */\nexport class Risk {\n  /**\n   * Clamp a number into the [0, 1] range.\n   *\n   * @param value\n   * @returns\n   */\n  static clamp01(value: number): number {\n    if (Number.isNaN(value)) return 0\n    return Math.min(1, Math.max(0, value))\n  }\n\n  /**\n   * Compute an aggregate risk score in [0, 1] for a session (higher = riskier).\n   *\n   * The baseline is the inverse of the mean of the positive signals (document\n   * quality, OCR confidence, liveness score, face-match similarity). Hard failure\n   * signals (expired document, failed liveness/face-match, multiple faces) floor\n   * the risk near the top of the range so risky sessions never look safe. Each\n   * non-informational signal compounds the remaining headroom by its score, and\n   * a rejecting signal floors it like a hard failure.\n   *\n   * @param input\n   * @returns\n   */\n  static score(input: DecisionInput): number {\n    const positives = [\n      input.document.qualityScore,\n      input.document.ocrConfidence,\n      input.liveness.score,\n      input.faceMatch.similarityScore,\n      input.address.score,\n    ].map(Risk.clamp01)\n\n    let risk = 1 - mean(positives)\n\n    const hardFailure =\n      input.document.expired ||\n      !input.liveness.passed ||\n      !input.faceMatch.passed ||\n      input.liveness.multipleFaces === true ||\n      // A failed address only floors risk when it's a rejecting failure.\n      (!input.address.passed && input.address.onFail === 'reject')\n\n    const signals = (input.signals ?? []).filter((signal) => signal.severity !== 'info')\n    for (const signal of signals) {\n      risk = 1 - (1 - risk) * (1 - Risk.clamp01(signal.score))\n    }\n\n    if (hardFailure || signals.some((signal) => signal.severity === 'reject')) {\n      risk = Math.max(risk, 0.9)\n    }\n\n    return Risk.clamp01(risk)\n  }\n}\n"],"mappings":";;AAGA,SAAS,KAAK,QAA0B;CACtC,IAAI,OAAO,WAAW,GAAG,OAAO;CAChC,OAAO,OAAO,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC,IAAI,OAAO;AACxD;;AAGA,IAAa,OAAb,MAAa,KAAK;;;;;;;CAOhB,OAAO,QAAQ,OAAuB;EACpC,IAAI,OAAO,MAAM,KAAK,GAAG,OAAO;EAChC,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,KAAK,CAAC;CACvC;;;;;;;;;;;;;;CAeA,OAAO,MAAM,OAA8B;EASzC,IAAI,OAAO,IAAI,KARG;GAChB,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,UAAU;GAChB,MAAM,QAAQ;EAChB,CAAC,CAAC,IAAI,KAAK,OAEiB,CAAC;EAE7B,MAAM,cACJ,MAAM,SAAS,WACf,CAAC,MAAM,SAAS,UAChB,CAAC,MAAM,UAAU,UACjB,MAAM,SAAS,kBAAkB,QAEhC,CAAC,MAAM,QAAQ,UAAU,MAAM,QAAQ,WAAW;EAErD,MAAM,WAAW,MAAM,WAAW,CAAC,EAAA,CAAG,QAAQ,WAAW,OAAO,aAAa,MAAM;EACnF,KAAK,MAAM,UAAU,SACnB,OAAO,KAAK,IAAI,SAAS,IAAI,KAAK,QAAQ,OAAO,KAAK;EAGxD,IAAI,eAAe,QAAQ,MAAM,WAAW,OAAO,aAAa,QAAQ,GACtE,OAAO,KAAK,IAAI,MAAM,EAAG;EAG3B,OAAO,KAAK,QAAQ,IAAI;CAC1B;AACF"}

package/dist/signals.d.mts

@@ -0,0 +1,26 @@
+import { DecisionReason, RiskPolicyConfig, RiskSeverity, RiskSignal } from "@arkyc/types";
+
+//#region src/signals.d.ts
+/** Policy resolution and precedence for risk signals. */
+declare class RiskSignals {
+  /**
+   * Resolve each signal's severity from the workflow policy. `info` signals stay
+   * informational, advisory and review-only signals never exceed review.
+   *
+   * @param signals
+   * @param policy
+   * @returns
+   */
+  static applyPolicy<T extends RiskSignal>(signals: T[], policy?: RiskPolicyConfig): T[];
+  /**
+   * The reason of the highest-precedence signal at `severity`, or `null`.
+   *
+   * @param signals
+   * @param severity
+   * @returns
+   */
+  static reasonFor(signals: RiskSignal[], severity: Exclude<RiskSeverity, 'info'>): DecisionReason | null;
+}
+//#endregion
+export { RiskSignals };
+//# sourceMappingURL=signals.d.mts.map

package/dist/signals.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.mts","names":[],"sources":["../src/signals.ts"],"mappings":";;;;cAmBa,WAAA;EAAA;;;;;;;;EAAA,OASJ,WAAA,WAAsB,UAAA,EAAY,OAAA,EAAS,CAAA,IAAK,MAAA,GAAQ,gBAAA,GAAwB,CAAA;EAmBrC;;;;;;;EAAA,OAA3C,SAAA,CAAU,OAAA,EAAS,UAAA,IAAc,QAAA,EAAU,OAAA,CAAQ,YAAA,YAAwB,cAAA;AAAA"}

package/dist/signals.mjs

@@ -0,0 +1,46 @@
+import { DEFAULT_RISK_SIGNAL_POLICY, REVIEW_ONLY_RISK_SIGNALS, RISK_SIGNAL_KEYS, RISK_SIGNAL_REASONS } from "@arkyc/types";
+//#region src/signals.ts
+const POLICY_SEVERITY = {
+	ignore: "info",
+	review: "review",
+	reject: "reject"
+};
+/** Policy resolution and precedence for risk signals. */
+var RiskSignals = class {
+	/**
+	* Resolve each signal's severity from the workflow policy. `info` signals stay
+	* informational, advisory and review-only signals never exceed review.
+	*
+	* @param signals
+	* @param policy
+	* @returns
+	*/
+	static applyPolicy(signals, policy = {}) {
+		return signals.map((signal) => {
+			if (signal.severity === "info") return signal;
+			let severity = POLICY_SEVERITY[policy[signal.key] ?? DEFAULT_RISK_SIGNAL_POLICY];
+			const capped = signal.advisory === true || REVIEW_ONLY_RISK_SIGNALS.includes(signal.key);
+			if (severity === "reject" && capped) severity = "review";
+			return {
+				...signal,
+				severity
+			};
+		});
+	}
+	/**
+	* The reason of the highest-precedence signal at `severity`, or `null`.
+	*
+	* @param signals
+	* @param severity
+	* @returns
+	*/
+	static reasonFor(signals, severity) {
+		const keys = new Set(signals.filter((signal) => signal.severity === severity).map((signal) => signal.key));
+		const key = RISK_SIGNAL_KEYS.find((candidate) => keys.has(candidate));
+		return key ? RISK_SIGNAL_REASONS[key] : null;
+	}
+};
+//#endregion
+export { RiskSignals };
+
+//# sourceMappingURL=signals.mjs.map

package/dist/signals.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.mjs","names":[],"sources":["../src/signals.ts"],"sourcesContent":["import {\n  DEFAULT_RISK_SIGNAL_POLICY,\n  REVIEW_ONLY_RISK_SIGNALS,\n  RISK_SIGNAL_KEYS,\n  RISK_SIGNAL_REASONS,\n  type DecisionReason,\n  type RiskPolicyConfig,\n  type RiskSeverity,\n  type RiskSignal,\n  type RiskSignalPolicy,\n} from '@arkyc/types'\n\nconst POLICY_SEVERITY: Record<RiskSignalPolicy, RiskSeverity> = {\n  ignore: 'info',\n  review: 'review',\n  reject: 'reject',\n}\n\n/** Policy resolution and precedence for risk signals. */\nexport class RiskSignals {\n  /**\n   * Resolve each signal's severity from the workflow policy. `info` signals stay\n   * informational, advisory and review-only signals never exceed review.\n   *\n   * @param signals\n   * @param policy\n   * @returns\n   */\n  static applyPolicy<T extends RiskSignal>(signals: T[], policy: RiskPolicyConfig = {}): T[] {\n    return signals.map((signal) => {\n      if (signal.severity === 'info') return signal\n\n      let severity = POLICY_SEVERITY[policy[signal.key] ?? DEFAULT_RISK_SIGNAL_POLICY]\n      const capped = signal.advisory === true || REVIEW_ONLY_RISK_SIGNALS.includes(signal.key)\n      if (severity === 'reject' && capped) severity = 'review'\n\n      return { ...signal, severity }\n    })\n  }\n\n  /**\n   * The reason of the highest-precedence signal at `severity`, or `null`.\n   *\n   * @param signals\n   * @param severity\n   * @returns\n   */\n  static reasonFor(signals: RiskSignal[], severity: Exclude<RiskSeverity, 'info'>): DecisionReason | null {\n    const keys = new Set(signals.filter((signal) => signal.severity === severity).map((signal) => signal.key))\n    const key = RISK_SIGNAL_KEYS.find((candidate) => keys.has(candidate))\n\n    return key ? RISK_SIGNAL_REASONS[key] : null\n  }\n}\n"],"mappings":";;AAYA,MAAM,kBAA0D;CAC9D,QAAQ;CACR,QAAQ;CACR,QAAQ;AACV;;AAGA,IAAa,cAAb,MAAyB;;;;;;;;;CASvB,OAAO,YAAkC,SAAc,SAA2B,CAAC,GAAQ;EACzF,OAAO,QAAQ,KAAK,WAAW;GAC7B,IAAI,OAAO,aAAa,QAAQ,OAAO;GAEvC,IAAI,WAAW,gBAAgB,OAAO,OAAO,QAAQ;GACrD,MAAM,SAAS,OAAO,aAAa,QAAQ,yBAAyB,SAAS,OAAO,GAAG;GACvF,IAAI,aAAa,YAAY,QAAQ,WAAW;GAEhD,OAAO;IAAE,GAAG;IAAQ;GAAS;EAC/B,CAAC;CACH;;;;;;;;CASA,OAAO,UAAU,SAAuB,UAAgE;EACtG,MAAM,OAAO,IAAI,IAAI,QAAQ,QAAQ,WAAW,OAAO,aAAa,QAAQ,CAAC,CAAC,KAAK,WAAW,OAAO,GAAG,CAAC;EACzG,MAAM,MAAM,iBAAiB,MAAM,cAAc,KAAK,IAAI,SAAS,CAAC;EAEpE,OAAO,MAAM,oBAAoB,OAAO;CAC1C;AACF"}

package/dist/thresholds.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"thresholds.d.mts","names":[],"sources":["../src/thresholds.ts"],"mappings":";;;;cAGa,UAAA;EAAA;;;;EAAA,gBAKK,QAAA,EAAU,sBAAA;EAcC;;;;;;EAAA,OAApB,OAAA,CAAQ,SAAA,GAAY,OAAA,CAAQ,sBAAA,IAA0B,sBAAA;AAAA"}
+{"version":3,"file":"thresholds.d.mts","names":[],"sources":["../src/thresholds.ts"],"mappings":";;;;cAGa,UAAA;EAAA;;;;EAAA,gBAKK,QAAA,EAAU,sBAAA;EAQC;;;;;;EAAA,OAApB,OAAA,CAAQ,SAAA,GAAY,OAAA,CAAQ,sBAAA,IAA0B,sBAAA;AAAA"}

package/dist/thresholds.mjs

@@ -1,3 +1,4 @@
+import { DEFAULT_VERIFICATION_THRESHOLDS } from "@arkyc/types";
 //#region src/thresholds.ts
 /** Verification threshold defaults and override resolution. */
 var Thresholds = class Thresholds {
@@ -5,13 +6,7 @@ var Thresholds = class Thresholds {
 	* Platform default verification thresholds. Projects may override any subset
 	* via `ProjectSettings.thresholds`; {@link Thresholds.resolve} merges them.
 	*/
-	static DEFAULTS = {
-		documentQualityThreshold: .75,
-		ocrConfidenceThreshold: .8,
-		livenessThreshold: .85,
-		faceMatchThreshold: .75,
-		addressThreshold: .6
-	};
+	static DEFAULTS = DEFAULT_VERIFICATION_THRESHOLDS;
 	/**
 	* Merge a partial set of project overrides over the platform defaults.
 	*

package/dist/thresholds.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"thresholds.mjs","names":[],"sources":["../src/thresholds.ts"],"sourcesContent":["import type { VerificationThresholds } from '@arkyc/types'\n\n/** Verification threshold defaults and override resolution. */\nexport class Thresholds {\n  /**\n   * Platform default verification thresholds. Projects may override any subset\n   * via `ProjectSettings.thresholds`; {@link Thresholds.resolve} merges them.\n   */\n  static readonly DEFAULTS: VerificationThresholds = {\n    documentQualityThreshold: 0.75,\n    ocrConfidenceThreshold: 0.8,\n    livenessThreshold: 0.85,\n    faceMatchThreshold: 0.75,\n    addressThreshold: 0.6,\n  }\n\n  /**\n   * Merge a partial set of project overrides over the platform defaults.\n   *\n   * @param overrides\n   * @returns\n   */\n  static resolve(overrides?: Partial<VerificationThresholds>): VerificationThresholds {\n    return { ...Thresholds.DEFAULTS, ...(overrides ?? {}) }\n  }\n}\n"],"mappings":";;AAGA,IAAa,aAAb,MAAa,WAAW;;;;;CAKtB,OAAgB,WAAmC;EACjD,0BAA0B;EAC1B,wBAAwB;EACxB,mBAAmB;EACnB,oBAAoB;EACpB,kBAAkB;CACpB;;;;;;;CAQA,OAAO,QAAQ,WAAqE;EAClF,OAAO;GAAE,GAAG,WAAW;GAAU,GAAI,aAAa,CAAC;EAAG;CACxD;AACF"}
+{"version":3,"file":"thresholds.mjs","names":[],"sources":["../src/thresholds.ts"],"sourcesContent":["import { DEFAULT_VERIFICATION_THRESHOLDS, type VerificationThresholds } from '@arkyc/types'\n\n/** Verification threshold defaults and override resolution. */\nexport class Thresholds {\n  /**\n   * Platform default verification thresholds. Projects may override any subset\n   * via `ProjectSettings.thresholds`; {@link Thresholds.resolve} merges them.\n   */\n  static readonly DEFAULTS: VerificationThresholds = DEFAULT_VERIFICATION_THRESHOLDS\n\n  /**\n   * Merge a partial set of project overrides over the platform defaults.\n   *\n   * @param overrides\n   * @returns\n   */\n  static resolve(overrides?: Partial<VerificationThresholds>): VerificationThresholds {\n    return { ...Thresholds.DEFAULTS, ...(overrides ?? {}) }\n  }\n}\n"],"mappings":";;;AAGA,IAAa,aAAb,MAAa,WAAW;;;;;CAKtB,OAAgB,WAAmC;;;;;;;CAQnD,OAAO,QAAQ,WAAqE;EAClF,OAAO;GAAE,GAAG,WAAW;GAAU,GAAI,aAAa,CAAC;EAAG;CACxD;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyc/core",
-  "version": "1.2.10",
+  "version": "2.0.0",
   "description": "Decision engine, status transitions, and scoring logic",
   "license": "MIT",
   "keywords": [
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@arkyc/types": "^1.2.10"
+    "@arkyc/types": "^2.0.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",